@zakkster/lite-observe 1.0.0 → 1.0.2

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## 1.0.1 -- Internal: delegate to @zakkster/lite-cleanup
+
+### Changed
+
+- Internal: `FinalizationRegistry` bookkeeping now delegated to
+  `@zakkster/lite-cleanup`. Behavior identical; extracted the shared
+  pattern used by lite-observe and lite-floating into a canonical primitive
+  that both packages consume.
+- New diagnostic export `_registrySize()` surfaces the live handle count
+  from the underlying disposal registry.
+
+### Notes
+
+- No public API changes.
+- Allocation gate unchanged (verified: 0 B/call, 0 scavenges on all
+  dispatch paths).
+- All existing tests pass unchanged.
+- `@zakkster/lite-cleanup` added as a runtime dependency (~500 bytes
+  gzipped); this is the shared cost paid once across all consumers of
+  the ecosystem.
+
 ## 1.0.0 -- Production cut
 
 The 0.2.x line proved out FinalizationRegistry-based orphan cleanup; the

package/index.d.ts

@@ -217,3 +217,6 @@ export function attachFinalizer<T extends { dispose: () => void }>(
  *  browsers + Node 14+). Returns false on environments without it; in that
  *  case `attachFinalizer` becomes a no-op pass-through. */
 export function _hasFinalizationRegistry(): boolean;
+
+/** Number of live handles tracked by the shared disposal registry. */
+export function _registrySize(): number;

package/index.js

@@ -22,4 +22,4 @@ export { _resetIntersection, _intersectionBucketCount } from './src/Intersection
 export { _resetMutation, _mutationObserverCount } from './src/Mutation.js';
 export { _resetMedia, _mediaCacheSize } from './src/Media.js';
 export { _forceVisibilitySync } from './src/Visibility.js';
-export { _hasFinalizationRegistry, attachFinalizer } from './src/_finalize.js';
+export { _hasFinalizationRegistry, _registrySize, attachFinalizer } from './src/_finalize.js';

package/package.json

@@ -1,12 +1,12 @@
 {
     "name": "@zakkster/lite-observe",
-    "version": "1.0.0",
+    "version": "1.0.2",
     "author": "Zahary Shinikchiev <shinikchiev@yahoo.com>",
     "description": "Zero-GC reactive bridge for the DOM observer APIs. ResizeObserver, IntersectionObserver, MutationObserver, matchMedia, and Page Visibility collapsed to fine-grained lite-signal signals. Shared registry: N components observing the same element pay one observer cost.",
     "type": "module",
     "sideEffects": false,
-    "main": "index.js",
-    "module": "index.js",
+    "main": "./index.js",
+    "module": "./index.js",
     "types": "./index.d.ts",
     "exports": {
         ".": {
@@ -49,6 +49,9 @@
         "tiny",
         "esm"
     ],
+    "dependencies": {
+        "@zakkster/lite-cleanup": "^1.0.0"
+    },
     "peerDependencies": {
         "@zakkster/lite-signal": "^1.2.2"
     },
@@ -65,6 +68,10 @@
         "url": "https://github.com/PeshoVurtoleta/lite-observe/issues",
         "email": "shinikchiev@yahoo.com"
     },
+    "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/PeshoVurtoleta"
+    },
     "engines": {
         "node": ">=18"
     }

package/src/_finalize.js

@@ -1,44 +1,28 @@
 /**
  * @zakkster/lite-observe -- shared orphan-handle finalizer.
  *
- * The observer modules (Resize, Intersection, Mutation) return handles with
- * a `dispose()` method. Consumers are expected to call dispose when they're
- * done. If they don't, the underlying browser observer keeps its target
- * alive via spec-defined internal references (HashSet<Ref<Node>> in WebKit,
- * HeapVector<Member<Node>> in Chromium) -- a leak.
+ * Delegates to @zakkster/lite-cleanup's disposal registry. The semantics
+ * are identical to the previous inline FinalizationRegistry: dropped
+ * handles are eventually cleaned up by GC; explicit dispose unregisters
+ * the finalizer and runs cleanup synchronously; double-fire is prevented
+ * by the registry's `disposed` guard.
  *
- * FinalizationRegistry is the canonical safety net: when the consumer drops
- * the handle (their last reference to it), the runtime eventually GCs the
- * handle and fires our cleanup callback, which disconnects the browser
- * observer.
+ * The `attachFinalizer` contract is unchanged:
+ *   - `innerCleanup` MUST NOT reference `handle`.
+ *   - `innerCleanup` MUST be idempotent.
+ *   - Errors thrown by cleanup are swallowed by the registry.
  *
- * Caveats acknowledged:
- *   1. Finalization is non-deterministic. The runtime may run the cleanup
- *      "eventually" -- on the next GC cycle, or never if the program exits
- *      first. Explicit dispose remains the primary path; this is a safety
- *      net for the forgot-to-dispose case.
- *   2. The held value (second arg to register) must not reference the
- *      handle. We pass the bare inner-cleanup closure, which captures only
- *      slot / element / Map references -- never the handle itself.
- *   3. Calling explicit dispose unregisters the finalizer so it doesn't
- *      double-fire. The wrapper that does this DOES capture the handle
- *      (via `registry.unregister(handle)`), but it's set as a property of
- *      the handle, so the self-reference is collected with the handle.
- *
- * Single registry shared across the three modules so finalisation pressure
- * is concentrated -- the runtime processes one queue, not three.
+ * Single registry shared across the three observer modules so
+ * finalisation pressure is concentrated -- the runtime processes one
+ * queue, not three.
  */
 
-const registry = typeof FinalizationRegistry !== 'undefined'
-    ? new FinalizationRegistry(function (cleanup) {
-        // Swallow errors. A failing finalizer must not poison the queue
-        // for other pending finalizations.
-        try { cleanup(); } catch (_e) { /* intentional */ }
-    })
-    : null;
+import { createDisposalRegistry } from '@zakkster/lite-cleanup';
+
+const registry = createDisposalRegistry({ name: 'lite-observe' });
 
 /**
- * Register a handle for FinalizationRegistry-backed orphan cleanup.
+ * Register a handle for orphan cleanup via @zakkster/lite-cleanup.
  *
  * Used internally by `observeResize`, `observeIntersection`, and
  * `observeMutation` so dropped handles trigger disconnect via GC.
@@ -55,31 +39,6 @@ const registry = typeof FinalizationRegistry !== 'undefined'
  *   - Errors thrown are swallowed by the registry so the finalizer
  *     queue continues to drain for other pending finalisations.
  *
- * Note on timing: FinalizationRegistry is non-deterministic. The
- * runtime decides when to process its queue. Explicit `dispose()` is
- * still the primary path when you have a lifecycle hook; this is the
- * safety net for the forgot-to-dispose case.
- *
- * Example -- building a ScrollObserver primitive:
- *
- *     function observeScroll(target) {
- *         const positionSig = signal({ x: 0, y: 0 });
- *         let disposed = false;
- *         function onScroll() {
- *             positionSig.set({ x: target.scrollLeft, y: target.scrollTop });
- *         }
- *         target.addEventListener('scroll', onScroll);
- *         function cleanup() {
- *             if (disposed) return;
- *             disposed = true;
- *             target.removeEventListener('scroll', onScroll);
- *         }
- *         return attachFinalizer(
- *             { position: positionSig, dispose: cleanup },
- *             cleanup
- *         );
- *     }
- *
  * @param {object} handle        Handle returned to the consumer; must
  *                               have a `.dispose` method to wrap.
  * @param {() => void} innerCleanup  Bare cleanup; MUST NOT reference
@@ -88,24 +47,32 @@ const registry = typeof FinalizationRegistry !== 'undefined'
  *                   unregister the finalizer before running cleanup.
  */
 export function attachFinalizer(handle, innerCleanup) {
-    if (registry === null) return handle;
-    registry.register(handle, innerCleanup, handle);
+    const handleId = registry.register(handle, innerCleanup);
     const originalDispose = handle.dispose;
     handle.dispose = function () {
-        registry.unregister(handle);
+        registry.unregister(handleId);
         originalDispose();
     };
     return handle;
 }
 
 /**
- * Test hook. The shared FinalizationRegistry has no size; tests cannot
- * directly observe pending finalisations. The runtime's `--expose-gc` flag
- * plus a few synchronous gc() calls followed by a microtask flush is the
- * portable way to encourage processing.
+ * Test hook. Returns true when the underlying disposal registry is
+ * backed by a FinalizationRegistry (always true on modern runtimes,
+ * since lite-cleanup requires it).
  *
  * @internal
  */
 export function _hasFinalizationRegistry() {
-    return registry !== null;
+    return true;
+}
+
+/**
+ * Diagnostic: number of live (registered, not yet disposed or finalized)
+ * handles tracked by the shared registry.
+ *
+ * @internal
+ */
+export function _registrySize() {
+    return registry.size();
 }