addUnbinder

Associate a cleanup callback with a DOM node’s binding lifetime.

addUnbinderCleanup and Unbind

Associate a cleanup callback with a DOM node’s binding lifetime.

Overview

The addUnbinder function is used to associate an unbinder function with a DOM node in Regor. An unbinder function is used to remove bound data and associated logic from the DOM node when necessary.

Try it live

Own a node through its full lifetimeLive API

Live preview

Source value: 0 · Node: absent

0Source observers

0Root unbinders

0Custom cleanup calls

Unbind keeps the node but freezes its bindings. Remove + drain removes it and flushes deferred cleanup.

cleanup.ts

import {
  addUnbinder,
  createApp,
  drainUnbind,
  getBindData,
  html,
  observerCount,
  onUnmounted,
  ref,
  removeNode,
  sref,
  unbind,
  useScope,
} from 'regor'

export function createCleanup(interactive = false) {
  const host = sref<HTMLElement | null>(null)
  const source = ref(0),
    value = ref(0),
    present = ref(false),
    bound = ref(false)
  const observers = ref(0),
    callbacks = ref(0),
    registered = ref(0)
  let node: HTMLElement | null = null
  const inspect = () => {
    observers(observerCount(source))
    registered(node ? getBindData(node).unbinders.length : 0)
  }
  const mount = () => {
    if (!host() || node) return
    node = document.createElement('div')
    node.className = 'directive-card api-owned-node'
    host()!.appendChild(node)
    createApp(
      useScope(() => ({ source })),
      {
        element: node,
        template:
          '<strong>Owned node</strong><p>Bound value: <output r-text="source"></output></p>',
      },
    )
    addUnbinder(node, () => callbacks(callbacks() + 1))
    present(true)
    bound(true)
    inspect()
  }
  const detach = () => {
    if (node) unbind(node)
    bound(false)
    inspect()
  }
  const remove = async () => {
    if (!node) return
    removeNode(node)
    await drainUnbind()
    node = null
    present(false)
    bound(false)
    inspect()
  }
  onUnmounted(() => {
    if (node) {
      unbind(node)
      node.remove()
    }
  })
  return {
    interactive,
    host,
    value,
    present,
    bound,
    observers,
    callbacks,
    registered,
    mount,
    detach,
    remove,
    increment: () => {
      source(source() + 1)
      value(source())
      inspect()
    },
  }
}

export const cleanupTemplate = html` <div class="guide-demo">
  <div class="guide-session-bar">
    <button type="button" @click="mount" :disabled="!interactive || present">
      Mount node</button
    ><button type="button" @click="increment" :disabled="!interactive">
      Write +1</button
    ><button type="button" @click="detach" :disabled="!interactive || !bound">
      Unbind</button
    ><button type="button" @click="remove" :disabled="!interactive || !present">
      Remove + drain
    </button>
  </div>
  <p>
    Source value: <strong>{{ value }}</strong> · Node: {{ present ? 'present' :
    'absent' }}
  </p>
  <div :ref="host"></div>
  <div class="guide-metrics">
    <div><output>{{ observers }}</output><span>Source observers</span></div>
    <div><output>{{ registered }}</output><span>Root unbinders</span></div>
    <div><output>{{ callbacks }}</output><span>Custom cleanup calls</span></div>
  </div>
  <p class="guide-hint">
    Unbind keeps the node but freezes its bindings. Remove + drain removes it
    and flushes deferred cleanup.
  </p>
</div>`

browser.ts

import { createApp, RegorConfig, useScope } from 'regor'
import { apiExamples } from './examples'

const element = document.getElementById('api-demo')
const name = element?.dataset.example
if (element && name && Object.hasOwn(apiExamples, name)) {
  const example = apiExamples[name as keyof typeof apiExamples]
  const scope = useScope<object>(() => example.create(true))
  const config =
    'config' in scope.context && scope.context.config instanceof RegorConfig
      ? scope.context.config
      : undefined
  createApp(scope, { element, template: example.template }, config)
}

Mount, write, unbind, or remove and drain. Watch the DOM, observer count, and registered cleanup.

Usage

Associating an Unbinder Function

To associate an unbinder function with a DOM node, call the addUnbinder function with the following parameters:

node: The DOM node to which you want to associate the unbinder function.
unbinder: A function that can be executed later to remove bound data and associated logic from the DOM node.

Example

import { addUnbinder } from 'regor'

// Create an unbinder function
const myUnbinder = () => {
  // Remove bound data and associated logic
  // ...
}

// Associate the unbinder function with a DOM node
const someElement = document.getElementById('example')
addUnbinder(someElement, myUnbinder)

Parameters

node: The DOM node to which you want to associate the unbinder function.
unbinder: A function that can be executed later to remove bound data and associated logic from the DOM node.

Associate cleanup with the node it belongs to

The callback should release resources owned by that node. The preview counts custom cleanup calls.

Notes

The addUnbinder function is typically used internally within Regor to manage unbinder functions associated with DOM nodes.
It provides a way to associate an unbinder function with a specific DOM element, allowing for the clean removal of bound data and logic when needed.
Unbinder functions are typically created and associated with DOM nodes as part of the data binding process in Regor.
The unbinder function, when executed, should perform any necessary cleanup or removal of data bindings and associated logic from the DOM node.
This function is primarily intended for use in advanced scenarios where direct access to Regor's internal data management is required.