@rlabs-inc/signals 1.3.0 → 1.4.0

package/README.md

@@ -9,6 +9,9 @@ A complete standalone mirror of Svelte 5's reactivity system. No compiler needed
 - **True Fine-Grained Reactivity** - Changes to deeply nested properties only trigger effects that read that exact path
 - **Per-Property Tracking** - Proxy-based deep reactivity with lazy signal creation per property
 - **Reactive Bindings** - Two-way data binding with `bind()` for connecting reactive values
+- **linkedSignal** - Angular's killer feature: writable computed that resets when source changes
+- **createSelector** - Solid's O(n)→O(2) optimization for list selection
+- **effectScope** - Vue's lifecycle management with pause/resume support
 - **Three-State Dirty Tracking** - Efficient CLEAN/MAYBE_DIRTY/DIRTY propagation
 - **Automatic Cleanup** - Effects clean up when disposed, no memory leaks
 - **Batching** - Group updates to prevent redundant effect runs
@@ -211,6 +214,117 @@ effect.pre(() => {
 })
 ```
 
+### Linked Signals (Angular's killer feature)
+
+#### `linkedSignal<D>(fn: () => D): WritableSignal<D>`
+#### `linkedSignal<S, D>(options: LinkedSignalOptions<S, D>): WritableSignal<D>`
+
+Create a writable signal that derives from a source but can be manually overridden.
+When the source changes, the linked signal resets to the computed value.
+
+```typescript
+// Simple form - derives directly from source
+const options = signal(['a', 'b', 'c'])
+const selected = linkedSignal(() => options.value[0])
+
+console.log(selected.value)  // 'a'
+selected.value = 'b'         // Manual override
+console.log(selected.value)  // 'b'
+
+options.value = ['x', 'y']   // Source changes
+flushSync()
+console.log(selected.value)  // 'x' (reset to computed value)
+```
+
+```typescript
+// Advanced form - with previous value tracking
+const items = signal([1, 2, 3])
+const selectedItem = linkedSignal({
+  source: () => items.value,
+  computation: (newItems, prev) => {
+    // Keep selection if still valid
+    if (prev && newItems.includes(prev.value)) {
+      return prev.value
+    }
+    return newItems[0]
+  }
+})
+```
+
+**Use cases:**
+- Form inputs that reset when parent data changes
+- Selection state that persists within valid options
+- Derived values that can be temporarily overridden
+
+### Selectors (Solid's O(n)→O(2) optimization)
+
+#### `createSelector<T, U = T>(source: () => T, fn?: (key: U, value: T) => boolean): SelectorFn<T, U>`
+
+Create a selector function for efficient list selection tracking.
+Instead of O(n) effects re-running, only affected items run = O(2).
+
+```typescript
+const selectedId = signal(1)
+const isSelected = createSelector(() => selectedId.value)
+
+// In a list of 1000 items:
+items.forEach(item => {
+  effect(() => {
+    // Only runs when THIS item's selection state changes!
+    // When selectedId changes from 1 to 2:
+    // - Only item 1's effect runs (was selected, now not)
+    // - Only item 2's effect runs (was not selected, now is)
+    // - Other 998 items' effects DON'T run
+    if (isSelected(item.id)) {
+      highlight(item)
+    } else {
+      unhighlight(item)
+    }
+  })
+})
+```
+
+### Effect Scope (Vue's lifecycle management)
+
+#### `effectScope(detached?: boolean): EffectScope`
+
+Create an effect scope to group effects for batch disposal with pause/resume support.
+
+```typescript
+const scope = effectScope()
+
+scope.run(() => {
+  // Effects created here are tracked by the scope
+  effect(() => console.log(count.value))
+  effect(() => console.log(name.value))
+
+  onScopeDispose(() => {
+    console.log('Cleaning up...')
+  })
+})
+
+// Later, dispose all effects at once
+scope.stop()
+```
+
+#### Pause and Resume
+
+```typescript
+scope.pause()    // Effects won't run while paused
+
+count.value = 5  // Effect doesn't run
+
+scope.resume()   // Pending updates run
+```
+
+#### `getCurrentScope(): EffectScope | null`
+
+Get the currently active effect scope.
+
+#### `onScopeDispose(fn: () => void): void`
+
+Register a cleanup function on the current scope.
+
 ### Batching & Scheduling
 
 #### `batch(fn: () => T): T`

package/dist/core/constants.d.ts

@@ -42,6 +42,12 @@ export declare const STALE_REACTION: unique symbol;
 export declare const STATE_SYMBOL: unique symbol;
 /** Symbol to mark reactive proxies */
 export declare const REACTIVE_MARKER: unique symbol;
+/** Symbol to identify Binding objects (must not be proxied) */
+export declare const BINDING_SYMBOL: unique symbol;
+/** Symbol to identify LinkedSignal objects */
+export declare const LINKED_SYMBOL: unique symbol;
+/** Flag to identify Source objects */
+export declare const SOURCE: number;
 /** Mask to clear all status bits (CLEAN, DIRTY, MAYBE_DIRTY) */
 export declare const STATUS_MASK: number;
 //# sourceMappingURL=constants.d.ts.map

package/dist/core/constants.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../src/core/constants.ts"],"names":[],"mappings":"AASA,2CAA2C;AAC3C,eAAO,MAAM,OAAO,QAAS,CAAA;AAE7B,0BAA0B;AAC1B,eAAO,MAAM,MAAM,QAAS,CAAA;AAE5B,wEAAwE;AACxE,eAAO,MAAM,aAAa,QAAS,CAAA;AAEnC,0DAA0D;AAC1D,eAAO,MAAM,WAAW,QAAS,CAAA;AAEjC,iDAAiD;AACjD,eAAO,MAAM,aAAa,QAAS,CAAA;AAEnC,wCAAwC;AACxC,eAAO,MAAM,WAAW,QAAS,CAAA;AAEjC,+BAA+B;AAC/B,eAAO,MAAM,YAAY,QAAS,CAAA;AAMlC,4CAA4C;AAC5C,eAAO,MAAM,KAAK,QAAU,CAAA;AAE5B,yDAAyD;AACzD,eAAO,MAAM,KAAK,QAAU,CAAA;AAE5B,mEAAmE;AACnE,eAAO,MAAM,WAAW,QAAU,CAAA;AAElC,0CAA0C;AAC1C,eAAO,MAAM,oBAAoB,QAAU,CAAA;AAE3C,gCAAgC;AAChC,eAAO,MAAM,SAAS,QAAU,CAAA;AAEhC,+BAA+B;AAC/B,eAAO,MAAM,KAAK,QAAU,CAAA;AAE5B,mCAAmC;AACnC,eAAO,MAAM,UAAU,QAAU,CAAA;AAEjC,sDAAsD;AACtD,eAAO,MAAM,gBAAgB,QAAU,CAAA;AAMvC,oDAAoD;AACpD,eAAO,MAAM,OAAO,QAAS,CAAA;AAE7B,0DAA0D;AAC1D,eAAO,MAAM,YAAY,QAAS,CAAA;AAMlC,iDAAiD;AACjD,eAAO,MAAM,cAAc,QAAU,CAAA;AAMrC,2EAA2E;AAC3E,eAAO,MAAM,aAAa,EAAE,OAAO,MAAkD,CAAA;AAErF,wDAAwD;AACxD,eAAO,MAAM,cAAc,EAAE,OAAO,MAAmD,CAAA;AAEvF,0CAA0C;AAC1C,eAAO,MAAM,YAAY,EAAE,OAAO,MAA0C,CAAA;AAE5E,sCAAsC;AACtC,eAAO,MAAM,eAAe,EAAE,OAAO,MAA6C,CAAA;AAMlF,gEAAgE;AAChE,eAAO,MAAM,WAAW,QAAiC,CAAA"}
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../src/core/constants.ts"],"names":[],"mappings":"AASA,2CAA2C;AAC3C,eAAO,MAAM,OAAO,QAAS,CAAA;AAE7B,0BAA0B;AAC1B,eAAO,MAAM,MAAM,QAAS,CAAA;AAE5B,wEAAwE;AACxE,eAAO,MAAM,aAAa,QAAS,CAAA;AAEnC,0DAA0D;AAC1D,eAAO,MAAM,WAAW,QAAS,CAAA;AAEjC,iDAAiD;AACjD,eAAO,MAAM,aAAa,QAAS,CAAA;AAEnC,wCAAwC;AACxC,eAAO,MAAM,WAAW,QAAS,CAAA;AAEjC,+BAA+B;AAC/B,eAAO,MAAM,YAAY,QAAS,CAAA;AAMlC,4CAA4C;AAC5C,eAAO,MAAM,KAAK,QAAU,CAAA;AAE5B,yDAAyD;AACzD,eAAO,MAAM,KAAK,QAAU,CAAA;AAE5B,mEAAmE;AACnE,eAAO,MAAM,WAAW,QAAU,CAAA;AAElC,0CAA0C;AAC1C,eAAO,MAAM,oBAAoB,QAAU,CAAA;AAE3C,gCAAgC;AAChC,eAAO,MAAM,SAAS,QAAU,CAAA;AAEhC,+BAA+B;AAC/B,eAAO,MAAM,KAAK,QAAU,CAAA;AAE5B,mCAAmC;AACnC,eAAO,MAAM,UAAU,QAAU,CAAA;AAEjC,sDAAsD;AACtD,eAAO,MAAM,gBAAgB,QAAU,CAAA;AAMvC,oDAAoD;AACpD,eAAO,MAAM,OAAO,QAAS,CAAA;AAE7B,0DAA0D;AAC1D,eAAO,MAAM,YAAY,QAAS,CAAA;AAMlC,iDAAiD;AACjD,eAAO,MAAM,cAAc,QAAU,CAAA;AAMrC,2EAA2E;AAC3E,eAAO,MAAM,aAAa,EAAE,OAAO,MAAkD,CAAA;AAErF,wDAAwD;AACxD,eAAO,MAAM,cAAc,EAAE,OAAO,MAAmD,CAAA;AAEvF,0CAA0C;AAC1C,eAAO,MAAM,YAAY,EAAE,OAAO,MAA0C,CAAA;AAE5E,sCAAsC;AACtC,eAAO,MAAM,eAAe,EAAE,OAAO,MAA6C,CAAA;AAElF,+DAA+D;AAC/D,eAAO,MAAM,cAAc,EAAE,OAAO,MAA4C,CAAA;AAEhF,8CAA8C;AAC9C,eAAO,MAAM,aAAa,EAAE,OAAO,MAA2C,CAAA;AAM9E,sCAAsC;AACtC,eAAO,MAAM,MAAM,QAAS,CAAA;AAM5B,gEAAgE;AAChE,eAAO,MAAM,WAAW,QAAiC,CAAA"}

package/dist/deep/proxy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"proxy.d.ts","sourceRoot":"","sources":["../../src/deep/proxy.ts"],"names":[],"mappings":"AA8EA;;;;;;;;GAQG;AACH,wBAAgB,KAAK,CAAC,CAAC,SAAS,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,CA8PnD;AAMD;;GAEG;AACH,wBAAgB,KAAK,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,CAKpC;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAElD"}
+{"version":3,"file":"proxy.d.ts","sourceRoot":"","sources":["../../src/deep/proxy.ts"],"names":[],"mappings":"AA6FA;;;;;;;;GAQG;AACH,wBAAgB,KAAK,CAAC,CAAC,SAAS,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,CA6QnD;AAMD;;GAEG;AACH,wBAAgB,KAAK,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,CAKpC;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAElD"}

package/dist/index.d.ts

@@ -2,6 +2,9 @@ export { signal, source, mutableSource, state, stateRaw } from './primitives/sig
 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 { 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';
@@ -10,8 +13,11 @@ 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 { 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, } from './core/constants.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, } from './core/types.js';
 export type { Binding, ReadonlyBinding } from './primitives/bind.js';
+export type { LinkedSignalOptions, LinkedSignalConfig } from './primitives/linked.js';
+export type { SelectorFn } from './primitives/selector.js';
+export type { EffectScope } from './primitives/scope.js';
 //# sourceMappingURL=index.d.ts.map

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;AAMrF,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,GAChB,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,GACd,MAAM,iBAAiB,CAAA;AAExB,YAAY,EAAE,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,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,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,GACd,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"}