@rlabs-inc/signals 1.5.0 → 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

@@ -8,7 +8,7 @@ export { effectScope, getCurrentScope, onScopeDispose } from './primitives/scope
 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';

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,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,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"}
+{"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

@@ -80,6 +80,7 @@ __export(exports_src, {
   disconnectBinding: () => disconnectBinding,
   destroyEffect: () => destroyEffect,
   derived: () => derived,
+  deepEquals: () => deepEquals,
   decrementBatchDepth: () => decrementBatchDepth,
   createSelector: () => createSelector,
   createEquals: () => createEquals,
@@ -158,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);
 }
@@ -972,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,
@@ -1406,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);
 }
@@ -848,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,
@@ -1282,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;
@@ -1937,6 +1938,7 @@ export {
   disconnectBinding,
   destroyEffect,
   derived,
+  deepEquals,
   decrementBatchDepth,
   createSelector,
   createEquals,

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rlabs-inc/signals",
-  "version": "1.5.0",
+  "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",