@rlabs-inc/signals 1.4.4 → 1.6.0

package/README.md

@@ -557,33 +557,49 @@ if (isReactive(value)) {
 Control when signals trigger updates:
 
 ```typescript
-import { signal, equals, safeEquals, shallowEquals, neverEquals, alwaysEquals, createEquals } from '@rlabs-inc/signals'
+import { signal, derived, equals, deepEquals, safeEquals, shallowEquals, neverEquals, alwaysEquals, createEquals } from '@rlabs-inc/signals'
 
-// Default - uses Object.is
-const a = signal(0)  // Uses equals by default
+// signal() - uses Object.is (reference equality)
+const a = signal(0)
+
+// derived() - uses Bun.deepEquals (structural equality) by default
+// This prevents unnecessary propagation when computed values are structurally identical
+const items = signal([1, 2, 3])
+const doubled = derived(() => items.value.map(x => x * 2))
+// If doubled produces [2, 4, 6] again, downstream effects won't re-run
+
+// Deep equality - uses Bun.deepEquals (36ns for small objects!)
+const c = signal({ a: 1 }, { equals: deepEquals })
+c.value = { a: 1 }  // Won't trigger - deeply equal
 
 // Safe equality - handles NaN correctly
-const b = signal(NaN, { equals: safeEquals })
+const d = signal(NaN, { equals: safeEquals })
 
 // Shallow comparison - compares one level deep
-const c = signal({ a: 1 }, { equals: shallowEquals })
-c.value = { a: 1 }  // Won't trigger - shallowly equal
+const e = signal({ a: 1 }, { equals: shallowEquals })
 
 // Always trigger updates
-const d = signal(0, { equals: neverEquals })
-d.value = 0  // Still triggers!
+const f = signal(0, { equals: neverEquals })
+f.value = 0  // Still triggers!
 
 // Never trigger updates
-const e = signal(0, { equals: alwaysEquals })
-e.value = 100  // Doesn't trigger
+const g = signal(0, { equals: alwaysEquals })
+g.value = 100  // Doesn't trigger
 
 // Custom equality
 const customEquals = createEquals((a, b) =>
   JSON.stringify(a) === JSON.stringify(b)
 )
-const f = signal([], { equals: customEquals })
+const h = signal([], { equals: customEquals })
 ```
 
+**Default equality by primitive:**
+| Primitive | Default | Reason |
+|-----------|---------|--------|
+| `signal()` | `Object.is` | User-controlled input - reference equality |
+| `derived()` | `Bun.deepEquals` | Computed output - structural equality prevents unnecessary work |
+| `linkedSignal()` | `Bun.deepEquals` | Computed output - structural equality |
+
 ---
 
 ## Error Handling

package/dist/index.d.ts

@@ -1,18 +1,18 @@
 export { signal, source, mutableSource, state, stateRaw } from './primitives/signal.js';
 export { derived, createDerived, disconnectDerived } from './primitives/derived.js';
 export { effect, createEffect, updateEffect, destroyEffect } from './primitives/effect.js';
-export { bind, bindReadonly, isBinding, unwrap, signals } from './primitives/bind.js';
+export { bind, bindReadonly, isBinding, unwrap, signals, disconnectBinding, bindingHasInternalSource } from './primitives/bind.js';
 export { linkedSignal, isLinkedSignal } from './primitives/linked.js';
 export { createSelector } from './primitives/selector.js';
 export { effectScope, getCurrentScope, onScopeDispose } from './primitives/scope.js';
 export { proxy, toRaw, isReactive } from './deep/proxy.js';
 export { batch, untrack, peek } from './reactivity/batching.js';
 export { flushSync, tick } from './reactivity/scheduling.js';
-export { equals, safeEquals, safeNotEqual, shallowEquals, createEquals, neverEquals, alwaysEquals, } from './reactivity/equality.js';
+export { equals, deepEquals, safeEquals, safeNotEqual, shallowEquals, createEquals, neverEquals, alwaysEquals, } from './reactivity/equality.js';
 export { ReactiveMap } from './collections/map.js';
 export { ReactiveSet } from './collections/set.js';
 export { ReactiveDate } from './collections/date.js';
-export { get, set, isDirty, setSignalStatus, markReactions, updateReaction, removeReactions, } from './reactivity/tracking.js';
+export { get, set, isDirty, setSignalStatus, markReactions, updateReaction, removeReactions, disconnectSource, } from './reactivity/tracking.js';
 export { DERIVED, EFFECT, RENDER_EFFECT, ROOT_EFFECT, BRANCH_EFFECT, USER_EFFECT, BLOCK_EFFECT, CLEAN, DIRTY, MAYBE_DIRTY, REACTION_IS_UPDATING, DESTROYED, INERT, EFFECT_RAN, EFFECT_PRESERVED, UNOWNED, DISCONNECTED, UNINITIALIZED, STALE_REACTION, STATE_SYMBOL, REACTIVE_MARKER, BINDING_SYMBOL, LINKED_SYMBOL, } from './core/constants.js';
 export { activeReaction, activeEffect, untracking, writeVersion, readVersion, batchDepth, setActiveReaction, setActiveEffect, setUntracking, incrementWriteVersion, incrementReadVersion, incrementBatchDepth, decrementBatchDepth, getReadVersion, getWriteVersion, getBatchDepth, } from './core/globals.js';
 export type { Signal, Source, Reaction, Derived, Effect, Value, ReadableSignal, WritableSignal, DerivedSignal, DisposeFn, CleanupFn, EffectFn, Equals, Uninitialized, ExtractInner, } from './core/types.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAoBA,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAA;AACvF,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAA;AACnF,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAA;AAC1F,OAAO,EAAE,IAAI,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAA;AACrF,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAA;AACrE,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAA;AACzD,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAA;AAMpF,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAM1D,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,0BAA0B,CAAA;AAC/D,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,4BAA4B,CAAA;AAM5D,OAAO,EACL,MAAM,EACN,UAAU,EACV,YAAY,EACZ,aAAa,EACb,YAAY,EACZ,WAAW,EACX,YAAY,GACb,MAAM,0BAA0B,CAAA;AAMjC,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAA;AAClD,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAA;AAClD,OAAO,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAA;AAMpD,OAAO,EACL,GAAG,EACH,GAAG,EACH,OAAO,EACP,eAAe,EACf,aAAa,EACb,cAAc,EACd,eAAe,GAChB,MAAM,0BAA0B,CAAA;AAMjC,OAAO,EAEL,OAAO,EACP,MAAM,EACN,aAAa,EACb,WAAW,EACX,aAAa,EACb,WAAW,EACX,YAAY,EAGZ,KAAK,EACL,KAAK,EACL,WAAW,EACX,oBAAoB,EACpB,SAAS,EACT,KAAK,EACL,UAAU,EACV,gBAAgB,EAGhB,OAAO,EACP,YAAY,EAGZ,aAAa,EACb,cAAc,EACd,YAAY,EACZ,eAAe,EACf,cAAc,EACd,aAAa,GACd,MAAM,qBAAqB,CAAA;AAM5B,OAAO,EACL,cAAc,EACd,YAAY,EACZ,UAAU,EACV,YAAY,EACZ,WAAW,EACX,UAAU,EAGV,iBAAiB,EACjB,eAAe,EACf,aAAa,EACb,qBAAqB,EACrB,oBAAoB,EACpB,mBAAmB,EACnB,mBAAmB,EAGnB,cAAc,EACd,eAAe,EACf,aAAa,GACd,MAAM,mBAAmB,CAAA;AAM1B,YAAY,EAEV,MAAM,EACN,MAAM,EACN,QAAQ,EACR,OAAO,EACP,MAAM,EACN,KAAK,EAGL,cAAc,EACd,cAAc,EACd,aAAa,EACb,SAAS,EACT,SAAS,EACT,QAAQ,EAGR,MAAM,EACN,aAAa,EACb,YAAY,GACb,MAAM,iBAAiB,CAAA;AAExB,YAAY,EAAE,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AACpE,YAAY,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAA;AACrF,YAAY,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAA;AAC1D,YAAY,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAoBA,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAA;AACvF,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAA;AACnF,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAA;AAC1F,OAAO,EAAE,IAAI,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,iBAAiB,EAAE,wBAAwB,EAAE,MAAM,sBAAsB,CAAA;AAClI,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAA;AACrE,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAA;AACzD,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAA;AAMpF,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAM1D,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,0BAA0B,CAAA;AAC/D,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,4BAA4B,CAAA;AAM5D,OAAO,EACL,MAAM,EACN,UAAU,EACV,UAAU,EACV,YAAY,EACZ,aAAa,EACb,YAAY,EACZ,WAAW,EACX,YAAY,GACb,MAAM,0BAA0B,CAAA;AAMjC,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAA;AAClD,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAA;AAClD,OAAO,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAA;AAMpD,OAAO,EACL,GAAG,EACH,GAAG,EACH,OAAO,EACP,eAAe,EACf,aAAa,EACb,cAAc,EACd,eAAe,EACf,gBAAgB,GACjB,MAAM,0BAA0B,CAAA;AAMjC,OAAO,EAEL,OAAO,EACP,MAAM,EACN,aAAa,EACb,WAAW,EACX,aAAa,EACb,WAAW,EACX,YAAY,EAGZ,KAAK,EACL,KAAK,EACL,WAAW,EACX,oBAAoB,EACpB,SAAS,EACT,KAAK,EACL,UAAU,EACV,gBAAgB,EAGhB,OAAO,EACP,YAAY,EAGZ,aAAa,EACb,cAAc,EACd,YAAY,EACZ,eAAe,EACf,cAAc,EACd,aAAa,GACd,MAAM,qBAAqB,CAAA;AAM5B,OAAO,EACL,cAAc,EACd,YAAY,EACZ,UAAU,EACV,YAAY,EACZ,WAAW,EACX,UAAU,EAGV,iBAAiB,EACjB,eAAe,EACf,aAAa,EACb,qBAAqB,EACrB,oBAAoB,EACpB,mBAAmB,EACnB,mBAAmB,EAGnB,cAAc,EACd,eAAe,EACf,aAAa,GACd,MAAM,mBAAmB,CAAA;AAM1B,YAAY,EAEV,MAAM,EACN,MAAM,EACN,QAAQ,EACR,OAAO,EACP,MAAM,EACN,KAAK,EAGL,cAAc,EACd,cAAc,EACd,aAAa,EACb,SAAS,EACT,SAAS,EACT,QAAQ,EAGR,MAAM,EACN,aAAa,EACb,YAAY,GACb,MAAM,iBAAiB,CAAA;AAExB,YAAY,EAAE,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AACpE,YAAY,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAA;AACrF,YAAY,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAA;AAC1D,YAAY,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA"}

package/dist/index.js

@@ -75,14 +75,18 @@ __export(exports_src, {
   equals: () => equals,
   effectScope: () => effectScope,
   effect: () => effect,
+  disconnectSource: () => disconnectSource,
   disconnectDerived: () => disconnectDerived,
+  disconnectBinding: () => disconnectBinding,
   destroyEffect: () => destroyEffect,
   derived: () => derived,
+  deepEquals: () => deepEquals,
   decrementBatchDepth: () => decrementBatchDepth,
   createSelector: () => createSelector,
   createEquals: () => createEquals,
   createEffect: () => createEffect,
   createDerived: () => createDerived,
+  bindingHasInternalSource: () => bindingHasInternalSource,
   bindReadonly: () => bindReadonly,
   bind: () => bind,
   batchDepth: () => batchDepth,
@@ -155,6 +159,7 @@ var shallowEquals = (oldValue, newValue) => {
   }
   return true;
 };
+var deepEquals = typeof Bun !== "undefined" && typeof Bun.deepEquals === "function" ? (a, b) => Bun.deepEquals(a, b) : shallowEquals;
 function createEquals(fn) {
   return (oldValue, newValue) => fn(oldValue, newValue);
 }
@@ -592,6 +597,26 @@ function updateDerived(derived) {
 function setUpdateDerivedImpl(impl) {
   updateDerivedImpl = impl;
 }
+function disconnectSource(source) {
+  const reactions = source.reactions;
+  if (reactions !== null) {
+    for (let i = 0;i < reactions.length; i++) {
+      const reaction = reactions[i];
+      const deps = reaction.deps;
+      if (deps !== null) {
+        const idx = deps.indexOf(source);
+        if (idx !== -1) {
+          const last = deps.length - 1;
+          if (idx !== last) {
+            deps[idx] = deps[last];
+          }
+          deps.pop();
+        }
+      }
+    }
+    source.reactions = null;
+  }
+}
 function removeReactions(reaction, start) {
   const deps = reaction.deps;
   if (deps === null)
@@ -949,7 +974,7 @@ function createDerived(fn, options) {
     f: flags,
     fn,
     v: UNINITIALIZED,
-    equals: options?.equals ?? equals,
+    equals: options?.equals ?? deepEquals,
     reactions: null,
     deps: null,
     effects: null,
@@ -1246,8 +1271,9 @@ effect.tracking = function effectTracking() {
   return activeEffect !== null;
 };
 // src/primitives/bind.ts
+var BINDING_SOURCE_SYMBOL = Symbol("binding.source");
 var bindingCleanup = new FinalizationRegistry((internalSource) => {
-  internalSource.reactions = null;
+  disconnectSource(internalSource);
 });
 function isBinding(value) {
   return value !== null && typeof value === "object" && BINDING_SYMBOL in value;
@@ -1258,31 +1284,59 @@ function isSignal(value) {
 function isGetter(value) {
   return typeof value === "function";
 }
+function isStaticPrimitive(value) {
+  const type = typeof value;
+  return value === null || value === undefined || type === "number" || type === "string" || type === "boolean";
+}
 function bind(source2) {
   if (isGetter(source2)) {
-    return {
+    const getterBinding = {
       [BINDING_SYMBOL]: true,
+      [BINDING_SOURCE_SYMBOL]: null,
       get value() {
         return source2();
       }
     };
+    return getterBinding;
   }
-  let actualSource;
-  let internalSource = null;
   if (isBinding(source2) || isSignal(source2)) {
-    actualSource = source2;
-  } else {
-    const sig = signal(source2);
-    actualSource = sig;
-    internalSource = getSource(sig) ?? null;
+    const actualSource = source2;
+    const forwardBinding = {
+      [BINDING_SYMBOL]: true,
+      [BINDING_SOURCE_SYMBOL]: null,
+      get value() {
+        return actualSource.value;
+      },
+      set value(v) {
+        actualSource.value = v;
+      }
+    };
+    return forwardBinding;
+  }
+  if (isStaticPrimitive(source2)) {
+    let staticValue = source2;
+    const staticBinding = {
+      [BINDING_SYMBOL]: true,
+      [BINDING_SOURCE_SYMBOL]: null,
+      get value() {
+        return staticValue;
+      },
+      set value(v) {
+        staticValue = v;
+      }
+    };
+    return staticBinding;
   }
+  const sig = signal(source2);
+  const internalSource = getSource(sig) ?? null;
   const binding = {
     [BINDING_SYMBOL]: true,
+    [BINDING_SOURCE_SYMBOL]: internalSource,
     get value() {
-      return actualSource.value;
+      return sig.value;
     },
     set value(v) {
-      actualSource.value = v;
+      sig.value = v;
     }
   };
   if (internalSource !== null) {
@@ -1290,6 +1344,18 @@ function bind(source2) {
   }
   return binding;
 }
+function disconnectBinding(binding) {
+  if (binding === null || binding === undefined)
+    return;
+  const internalSource = binding[BINDING_SOURCE_SYMBOL];
+  if (internalSource !== null && internalSource !== undefined) {
+    disconnectSource(internalSource);
+  }
+}
+function bindingHasInternalSource(binding) {
+  const internalSource = binding[BINDING_SOURCE_SYMBOL];
+  return internalSource !== null && internalSource !== undefined;
+}
 function bindReadonly(source2) {
   return {
     [BINDING_SYMBOL]: true,
@@ -1342,7 +1408,7 @@ var peek = untrack;
 function linkedSignal(config) {
   let sourceFn;
   let computation;
-  let equalsFn = Object.is;
+  let equalsFn = deepEquals;
   if (typeof config === "function") {
     const fn = config;
     sourceFn = fn;

package/dist/index.mjs

@@ -34,6 +34,7 @@ var shallowEquals = (oldValue, newValue) => {
   }
   return true;
 };
+var deepEquals = typeof Bun !== "undefined" && typeof Bun.deepEquals === "function" ? (a, b) => Bun.deepEquals(a, b) : shallowEquals;
 function createEquals(fn) {
   return (oldValue, newValue) => fn(oldValue, newValue);
 }
@@ -471,6 +472,26 @@ function updateDerived(derived) {
 function setUpdateDerivedImpl(impl) {
   updateDerivedImpl = impl;
 }
+function disconnectSource(source) {
+  const reactions = source.reactions;
+  if (reactions !== null) {
+    for (let i = 0;i < reactions.length; i++) {
+      const reaction = reactions[i];
+      const deps = reaction.deps;
+      if (deps !== null) {
+        const idx = deps.indexOf(source);
+        if (idx !== -1) {
+          const last = deps.length - 1;
+          if (idx !== last) {
+            deps[idx] = deps[last];
+          }
+          deps.pop();
+        }
+      }
+    }
+    source.reactions = null;
+  }
+}
 function removeReactions(reaction, start) {
   const deps = reaction.deps;
   if (deps === null)
@@ -828,7 +849,7 @@ function createDerived(fn, options) {
     f: flags,
     fn,
     v: UNINITIALIZED,
-    equals: options?.equals ?? equals,
+    equals: options?.equals ?? deepEquals,
     reactions: null,
     deps: null,
     effects: null,
@@ -1125,8 +1146,9 @@ effect.tracking = function effectTracking() {
   return activeEffect !== null;
 };
 // src/primitives/bind.ts
+var BINDING_SOURCE_SYMBOL = Symbol("binding.source");
 var bindingCleanup = new FinalizationRegistry((internalSource) => {
-  internalSource.reactions = null;
+  disconnectSource(internalSource);
 });
 function isBinding(value) {
   return value !== null && typeof value === "object" && BINDING_SYMBOL in value;
@@ -1137,31 +1159,59 @@ function isSignal(value) {
 function isGetter(value) {
   return typeof value === "function";
 }
+function isStaticPrimitive(value) {
+  const type = typeof value;
+  return value === null || value === undefined || type === "number" || type === "string" || type === "boolean";
+}
 function bind(source2) {
   if (isGetter(source2)) {
-    return {
+    const getterBinding = {
       [BINDING_SYMBOL]: true,
+      [BINDING_SOURCE_SYMBOL]: null,
       get value() {
         return source2();
       }
     };
+    return getterBinding;
   }
-  let actualSource;
-  let internalSource = null;
   if (isBinding(source2) || isSignal(source2)) {
-    actualSource = source2;
-  } else {
-    const sig = signal(source2);
-    actualSource = sig;
-    internalSource = getSource(sig) ?? null;
+    const actualSource = source2;
+    const forwardBinding = {
+      [BINDING_SYMBOL]: true,
+      [BINDING_SOURCE_SYMBOL]: null,
+      get value() {
+        return actualSource.value;
+      },
+      set value(v) {
+        actualSource.value = v;
+      }
+    };
+    return forwardBinding;
+  }
+  if (isStaticPrimitive(source2)) {
+    let staticValue = source2;
+    const staticBinding = {
+      [BINDING_SYMBOL]: true,
+      [BINDING_SOURCE_SYMBOL]: null,
+      get value() {
+        return staticValue;
+      },
+      set value(v) {
+        staticValue = v;
+      }
+    };
+    return staticBinding;
   }
+  const sig = signal(source2);
+  const internalSource = getSource(sig) ?? null;
   const binding = {
     [BINDING_SYMBOL]: true,
+    [BINDING_SOURCE_SYMBOL]: internalSource,
     get value() {
-      return actualSource.value;
+      return sig.value;
     },
     set value(v) {
-      actualSource.value = v;
+      sig.value = v;
     }
   };
   if (internalSource !== null) {
@@ -1169,6 +1219,18 @@ function bind(source2) {
   }
   return binding;
 }
+function disconnectBinding(binding) {
+  if (binding === null || binding === undefined)
+    return;
+  const internalSource = binding[BINDING_SOURCE_SYMBOL];
+  if (internalSource !== null && internalSource !== undefined) {
+    disconnectSource(internalSource);
+  }
+}
+function bindingHasInternalSource(binding) {
+  const internalSource = binding[BINDING_SOURCE_SYMBOL];
+  return internalSource !== null && internalSource !== undefined;
+}
 function bindReadonly(source2) {
   return {
     [BINDING_SYMBOL]: true,
@@ -1221,7 +1283,7 @@ var peek = untrack;
 function linkedSignal(config) {
   let sourceFn;
   let computation;
-  let equalsFn = Object.is;
+  let equalsFn = deepEquals;
   if (typeof config === "function") {
     const fn = config;
     sourceFn = fn;
@@ -1871,14 +1933,18 @@ export {
   equals,
   effectScope,
   effect,
+  disconnectSource,
   disconnectDerived,
+  disconnectBinding,
   destroyEffect,
   derived,
+  deepEquals,
   decrementBatchDepth,
   createSelector,
   createEquals,
   createEffect,
   createDerived,
+  bindingHasInternalSource,
   bindReadonly,
   bind,
   batchDepth,

package/dist/primitives/bind.d.ts

@@ -24,6 +24,30 @@ export declare function bind<T>(source: Binding<T>): Binding<T>;
 export declare function bind<T>(source: ReadonlyBinding<T>): ReadonlyBinding<T>;
 export declare function bind<T>(source: () => T): ReadonlyBinding<T>;
 export declare function bind<T>(source: T): Binding<ExtractInner<T>>;
+/**
+ * Disconnect a binding from the reactive graph.
+ *
+ * In most cases, this is NOT needed because:
+ * 1. Static primitives (numbers, strings, booleans) don't create internal signals
+ * 2. Bindings to existing signals forward to them (no internal source)
+ * 3. FinalizationRegistry handles cleanup when objects are GC'd
+ *
+ * Use this ONLY when you have circular references that prevent GC,
+ * such as when a binding's internal source is tracked by a long-lived derived.
+ *
+ * @example
+ * ```ts
+ * const binding = bind(someNonPrimitiveValue)
+ * // ... later, when cleaning up:
+ * disconnectBinding(binding)  // Breaks reactive links, allows GC
+ * ```
+ */
+export declare function disconnectBinding(binding: Binding<unknown> | ReadonlyBinding<unknown> | null | undefined): void;
+/**
+ * Check if a binding has an internal source that may need cleanup.
+ * Static primitives and forwarding bindings return false.
+ */
+export declare function bindingHasInternalSource(binding: Binding<unknown> | ReadonlyBinding<unknown>): boolean;
 /**
  * Create an explicitly read-only binding.
  * Attempting to write will throw an error at runtime.

package/dist/primitives/bind.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bind.d.ts","sourceRoot":"","sources":["../../src/primitives/bind.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAU,YAAY,EAAE,MAAM,kBAAkB,CAAA;AAsB5F;;;GAGG;AACH,MAAM,WAAW,OAAO,CAAC,CAAC;IACxB,IAAI,KAAK,IAAI,CAAC,CAAA;IACd,IAAI,KAAK,CAAC,CAAC,EAAE,CAAC,EAAC;CAChB;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe,CAAC,CAAC;IAChC,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAA;CAClB;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,OAAO,CAAC,OAAO,CAAC,CAEnE;AA0DD,wBAAgB,IAAI,CAAC,CAAC,EAAE,MAAM,EAAE,cAAc,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAA;AAC9D,wBAAgB,IAAI,CAAC,CAAC,EAAE,MAAM,EAAE,cAAc,CAAC,CAAC,CAAC,GAAG,eAAe,CAAC,CAAC,CAAC,CAAA;AACtE,wBAAgB,IAAI,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAA;AACvD,wBAAgB,IAAI,CAAC,CAAC,EAAE,MAAM,EAAE,eAAe,CAAC,CAAC,CAAC,GAAG,eAAe,CAAC,CAAC,CAAC,CAAA;AACvE,wBAAgB,IAAI,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,GAAG,eAAe,CAAC,CAAC,CAAC,CAAA;AAC5D,wBAAgB,IAAI,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAA;AA2D5D;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,EAAE,cAAc,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,eAAe,CAAC,CAAC,CAAC,CAQ1F;AAMD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,MAAM,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,eAAe,CAAC,CAAC,CAAC,GAAG,CAAC,CAUvE;AAMD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,OAAO,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACvD,OAAO,EAAE,CAAC,GACT;KAAG,CAAC,IAAI,MAAM,CAAC,GAAG,cAAc,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CAAE,CAU1C"}
+{"version":3,"file":"bind.d.ts","sourceRoot":"","sources":["../../src/primitives/bind.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAU,YAAY,EAAE,MAAM,kBAAkB,CAAA;AAoC5F;;;GAGG;AACH,MAAM,WAAW,OAAO,CAAC,CAAC;IACxB,IAAI,KAAK,IAAI,CAAC,CAAA;IACd,IAAI,KAAK,CAAC,CAAC,EAAE,CAAC,EAAC;CAChB;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe,CAAC,CAAC;IAChC,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAA;CAClB;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,OAAO,CAAC,OAAO,CAAC,CAEnE;AAyED,wBAAgB,IAAI,CAAC,CAAC,EAAE,MAAM,EAAE,cAAc,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAA;AAC9D,wBAAgB,IAAI,CAAC,CAAC,EAAE,MAAM,EAAE,cAAc,CAAC,CAAC,CAAC,GAAG,eAAe,CAAC,CAAC,CAAC,CAAA;AACtE,wBAAgB,IAAI,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAA;AACvD,wBAAgB,IAAI,CAAC,CAAC,EAAE,MAAM,EAAE,eAAe,CAAC,CAAC,CAAC,GAAG,eAAe,CAAC,CAAC,CAAC,CAAA;AACvE,wBAAgB,IAAI,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,GAAG,eAAe,CAAC,CAAC,CAAC,CAAA;AAC5D,wBAAgB,IAAI,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAA;AAoF5D;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,GAAG,eAAe,CAAC,OAAO,CAAC,GAAG,IAAI,GAAG,SAAS,GAAG,IAAI,CAO/G;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,GAAG,eAAe,CAAC,OAAO,CAAC,GAAG,OAAO,CAGtG;AAMD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,EAAE,cAAc,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,eAAe,CAAC,CAAC,CAAC,CAQ1F;AAMD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,MAAM,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,eAAe,CAAC,CAAC,CAAC,GAAG,CAAC,CAUvE;AAMD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,OAAO,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACvD,OAAO,EAAE,CAAC,GACT;KAAG,CAAC,IAAI,MAAM,CAAC,GAAG,cAAc,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CAAE,CAU1C"}

package/dist/primitives/linked.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"linked.d.ts","sourceRoot":"","sources":["../../src/primitives/linked.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAA;AAY9D;;GAEG;AACH,MAAM,WAAW,mBAAmB,CAAC,CAAC,EAAE,CAAC;IACvC,MAAM,EAAE,MAAM,CAAC,CAAA;IACf,WAAW,EAAE,CAAC,MAAM,EAAE,CAAC,EAAE,QAAQ,CAAC,EAAE;QAAE,MAAM,EAAE,CAAC,CAAC;QAAC,KAAK,EAAE,CAAC,CAAA;KAAE,KAAK,CAAC,CAAA;IACjE,KAAK,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,CAAA;CAClB;AAED;;;GAGG;AACH,MAAM,MAAM,qBAAqB,CAAC,CAAC,IAAI,MAAM,CAAC,CAAA;AAE9C;;GAEG;AACH,MAAM,MAAM,kBAAkB,CAAC,CAAC,EAAE,CAAC,IAAI,qBAAqB,CAAC,CAAC,CAAC,GAAG,mBAAmB,CAAC,CAAC,EAAE,CAAC,CAAC,CAAA;AAM3F;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,EAAE,qBAAqB,CAAC,CAAC,CAAC,GAAG,cAAc,CAAC,CAAC,CAAC,CAAA;AACpF,wBAAgB,YAAY,CAAC,CAAC,EAAE,CAAC,EAAE,MAAM,EAAE,mBAAmB,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,cAAc,CAAC,CAAC,CAAC,CAAA;AA4GxF;;GAEG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,cAAc,CAAC,OAAO,CAAC,CAM/E"}
+{"version":3,"file":"linked.d.ts","sourceRoot":"","sources":["../../src/primitives/linked.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAA;AAa9D;;GAEG;AACH,MAAM,WAAW,mBAAmB,CAAC,CAAC,EAAE,CAAC;IACvC,MAAM,EAAE,MAAM,CAAC,CAAA;IACf,WAAW,EAAE,CAAC,MAAM,EAAE,CAAC,EAAE,QAAQ,CAAC,EAAE;QAAE,MAAM,EAAE,CAAC,CAAC;QAAC,KAAK,EAAE,CAAC,CAAA;KAAE,KAAK,CAAC,CAAA;IACjE,KAAK,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,CAAA;CAClB;AAED;;;GAGG;AACH,MAAM,MAAM,qBAAqB,CAAC,CAAC,IAAI,MAAM,CAAC,CAAA;AAE9C;;GAEG;AACH,MAAM,MAAM,kBAAkB,CAAC,CAAC,EAAE,CAAC,IAAI,qBAAqB,CAAC,CAAC,CAAC,GAAG,mBAAmB,CAAC,CAAC,EAAE,CAAC,CAAC,CAAA;AAM3F;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,EAAE,qBAAqB,CAAC,CAAC,CAAC,GAAG,cAAc,CAAC,CAAC,CAAC,CAAA;AACpF,wBAAgB,YAAY,CAAC,CAAC,EAAE,CAAC,EAAE,MAAM,EAAE,mBAAmB,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,cAAc,CAAC,CAAC,CAAC,CAAA;AA4GxF;;GAEG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,cAAc,CAAC,OAAO,CAAC,CAM/E"}

package/dist/reactivity/equality.d.ts

@@ -19,6 +19,14 @@ export declare const safeEquals: Equals;
  * Compares own enumerable properties one level deep
  */
 export declare const shallowEquals: Equals;
+/**
+ * Deep structural equality using Bun.deepEquals.
+ * Used as default for derived() and linkedSignal() to prevent unnecessary
+ * propagation when computed values are structurally identical.
+ *
+ * Falls back to shallowEquals in non-Bun environments.
+ */
+export declare const deepEquals: Equals;
 /**
  * Create a custom equality function
  */

package/dist/reactivity/equality.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"equality.d.ts","sourceRoot":"","sources":["../../src/reactivity/equality.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAA;AAM9C;;;GAGG;AACH,eAAO,MAAM,MAAM,EAAE,MAA8D,CAAA;AAMnF;;;GAGG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,GAAG,OAAO,CAQnD;AAED;;;GAGG;AACH,eAAO,MAAM,UAAU,EAAE,MAAkE,CAAA;AAM3F;;;GAGG;AACH,eAAO,MAAM,aAAa,EAAE,MAkD3B,CAAA;AAMD;;GAEG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,KAAK,OAAO,GAAG,MAAM,CAAC,CAAC,CAAC,CAEtE;AAED;;;GAGG;AACH,eAAO,MAAM,WAAW,EAAE,MAAoB,CAAA;AAE9C;;;GAGG;AACH,eAAO,MAAM,YAAY,EAAE,MAAmB,CAAA"}
+{"version":3,"file":"equality.d.ts","sourceRoot":"","sources":["../../src/reactivity/equality.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAA;AAM9C;;;GAGG;AACH,eAAO,MAAM,MAAM,EAAE,MAA8D,CAAA;AAMnF;;;GAGG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,GAAG,OAAO,CAQnD;AAED;;;GAGG;AACH,eAAO,MAAM,UAAU,EAAE,MAAkE,CAAA;AAM3F;;;GAGG;AACH,eAAO,MAAM,aAAa,EAAE,MAkD3B,CAAA;AAMD;;;;;;GAMG;AACH,eAAO,MAAM,UAAU,EAAE,MAGN,CAAA;AAMnB;;GAEG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,KAAK,OAAO,GAAG,MAAM,CAAC,CAAC,CAAC,CAEtE;AAED;;;GAGG;AACH,eAAO,MAAM,WAAW,EAAE,MAAoB,CAAA;AAE9C;;;GAGG;AACH,eAAO,MAAM,YAAY,EAAE,MAAmB,CAAA"}

package/dist/reactivity/tracking.d.ts

@@ -39,6 +39,14 @@ export declare function setSignalStatus(signal: {
 export declare function isDirty(reaction: Reaction): boolean;
 export declare function updateDerived(derived: Derived): void;
 export declare function setUpdateDerivedImpl(impl: (derived: Derived) => void): void;
+/**
+ * Disconnect a source from all its reactions.
+ * This breaks the circular reference between Source.reactions and Reaction.deps,
+ * allowing both to be garbage collected.
+ *
+ * Use this when disposing of a signal/binding that was tracked by deriveds/effects.
+ */
+export declare function disconnectSource(source: Source): void;
 /**
  * Remove a reaction from its dependencies, starting at the given index
  * Uses swap-and-pop for O(1) removal

package/dist/reactivity/tracking.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tracking.d.ts","sourceRoot":"","sources":["../../src/reactivity/tracking.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAA;AAkCjE;;;;;;;;GAQG;AACH,wBAAgB,GAAG,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,CAiD3C;AAoGD;;GAEG;AACH,wBAAgB,GAAG,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,CA8BrD;AAMD;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CA8BlE;AAMD;;GAEG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE;IAAE,CAAC,EAAE,MAAM,CAAA;CAAE,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAE3E;AAMD;;;;;;;;GAQG;AACH,wBAAgB,OAAO,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAoGnD;AAWD,wBAAgB,aAAa,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAEpD;AAED,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,GAAG,IAAI,CAE3E;AAMD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAOvE;AA8BD;;;GAGG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAmG1D"}
+{"version":3,"file":"tracking.d.ts","sourceRoot":"","sources":["../../src/reactivity/tracking.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAA;AAkCjE;;;;;;;;GAQG;AACH,wBAAgB,GAAG,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,CAiD3C;AAoGD;;GAEG;AACH,wBAAgB,GAAG,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,CA8BrD;AAMD;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CA8BlE;AAMD;;GAEG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE;IAAE,CAAC,EAAE,MAAM,CAAA;CAAE,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAE3E;AAMD;;;;;;;;GAQG;AACH,wBAAgB,OAAO,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAoGnD;AAWD,wBAAgB,aAAa,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAEpD;AAED,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,GAAG,IAAI,CAE3E;AAMD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAsBrD;AAMD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAOvE;AA8BD;;;GAGG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAmG1D"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rlabs-inc/signals",
-  "version": "1.4.4",
+  "version": "1.6.0",
   "description": "Production-grade fine-grained reactivity for TypeScript. A complete standalone mirror of Svelte 5's reactivity system - signals, effects, derived values, deep reactivity, reactive collections, and reactive bindings.",
   "main": "dist/index.js",
   "module": "dist/index.mjs",