@rlabs-inc/signals 1.0.0 → 1.2.0

package/README.md

@@ -8,6 +8,7 @@ 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
 - **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
@@ -94,6 +95,76 @@ Deriveds are:
 - **Cached** - Value is memoized until dependencies change
 - **Pure** - Cannot write to signals inside (throws error)
 
+### Bindings
+
+#### `bind<T>(source: WritableSignal<T>): Binding<T>`
+
+Create a reactive binding that forwards reads and writes to a source signal. Useful for two-way data binding and connecting reactive values across components.
+
+```typescript
+const source = signal(0)
+const binding = bind(source)
+
+// Reading through binding reads from source
+console.log(binding.value)  // 0
+
+// Writing through binding writes to source
+binding.value = 42
+console.log(source.value)  // 42
+```
+
+**Use cases:**
+- Two-way binding for form inputs
+- Connecting parent state to child components
+- Creating reactive links between signals
+
+```typescript
+// Two-way binding example
+const username = signal('')
+const inputBinding = bind(username)
+
+// When user types (e.g., in a UI framework):
+inputBinding.value = 'alice'  // Updates username signal!
+
+// When username changes programmatically:
+username.value = 'bob'        // inputBinding.value is now 'bob'
+```
+
+#### `bindReadonly<T>(source: ReadableSignal<T>): ReadonlyBinding<T>`
+
+Create a read-only binding. Attempting to write throws an error.
+
+```typescript
+const source = signal(0)
+const readonly = bindReadonly(source)
+
+console.log(readonly.value)  // 0
+// readonly.value = 42       // Would throw at compile time
+```
+
+#### `isBinding(value): boolean`
+
+Check if a value is a binding.
+
+```typescript
+const binding = bind(signal(0))
+console.log(isBinding(binding))  // true
+console.log(isBinding(signal(0)))  // false
+```
+
+#### `unwrap<T>(value: T | Binding<T>): T`
+
+Get the value from a binding, or return the value directly if not a binding.
+
+```typescript
+const arr: (string | Binding<string>)[] = [
+  'static',
+  bind(signal('dynamic'))
+]
+
+arr.map(unwrap)  // ['static', 'dynamic']
+```
+
 ### Effects
 
 #### `effect(fn: () => void | CleanupFn): DisposeFn`
@@ -367,6 +438,7 @@ This library is designed for performance:
 | DOM integration | Yes | No |
 | Fine-grained reactivity | Yes | Yes |
 | Deep proxy reactivity | Yes | Yes |
+| Reactive bindings | `bind:` directive | `bind()` function |
 | Batching | Yes | Yes |
 | Effect cleanup | Yes | Yes |
 | TypeScript | Yes | Yes |

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 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 } from './primitives/bind.js';
 export { proxy, toRaw, isReactive } from './deep/proxy.js';
 export { batch, untrack, peek } from './reactivity/batching.js';
 export { flushSync, tick } from './reactivity/scheduling.js';
@@ -12,4 +13,5 @@ export { get, set, isDirty, setSignalStatus, markReactions, updateReaction, remo
 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 { 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';
 //# 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;AAM1F,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"}
+{"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,MAAM,sBAAsB,CAAA;AAM5E,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"}

package/dist/index.js

@@ -32,6 +32,7 @@ __export(exports_src, {
   writeVersion: () => writeVersion,
   updateReaction: () => updateReaction,
   updateEffect: () => updateEffect,
+  unwrap: () => unwrap,
   untracking: () => untracking,
   untrack: () => untrack,
   toRaw: () => toRaw,
@@ -57,6 +58,7 @@ __export(exports_src, {
   markReactions: () => markReactions,
   isReactive: () => isReactive,
   isDirty: () => isDirty,
+  isBinding: () => isBinding,
   incrementWriteVersion: () => incrementWriteVersion,
   incrementReadVersion: () => incrementReadVersion,
   incrementBatchDepth: () => incrementBatchDepth,
@@ -74,6 +76,8 @@ __export(exports_src, {
   createEquals: () => createEquals,
   createEffect: () => createEffect,
   createDerived: () => createDerived,
+  bindReadonly: () => bindReadonly,
+  bind: () => bind,
   batchDepth: () => batchDepth,
   batch: () => batch,
   alwaysEquals: () => alwaysEquals,
@@ -957,6 +961,37 @@ effect.root = function effectRoot(fn) {
 effect.tracking = function effectTracking() {
   return activeEffect !== null;
 };
+// src/primitives/bind.ts
+var BINDING_SYMBOL = Symbol("binding");
+function isBinding(value) {
+  return value !== null && typeof value === "object" && BINDING_SYMBOL in value;
+}
+function bind(source2) {
+  const binding = {
+    [BINDING_SYMBOL]: true,
+    get value() {
+      return source2.value;
+    },
+    set value(v) {
+      source2.value = v;
+    }
+  };
+  return binding;
+}
+function bindReadonly(source2) {
+  return {
+    [BINDING_SYMBOL]: true,
+    get value() {
+      return source2.value;
+    }
+  };
+}
+function unwrap(value) {
+  if (isBinding(value)) {
+    return value.value;
+  }
+  return value;
+}
 // src/reactivity/batching.ts
 function batch(fn) {
   incrementBatchDepth();

package/dist/index.mjs

@@ -849,6 +849,37 @@ effect.root = function effectRoot(fn) {
 effect.tracking = function effectTracking() {
   return activeEffect !== null;
 };
+// src/primitives/bind.ts
+var BINDING_SYMBOL = Symbol("binding");
+function isBinding(value) {
+  return value !== null && typeof value === "object" && BINDING_SYMBOL in value;
+}
+function bind(source2) {
+  const binding = {
+    [BINDING_SYMBOL]: true,
+    get value() {
+      return source2.value;
+    },
+    set value(v) {
+      source2.value = v;
+    }
+  };
+  return binding;
+}
+function bindReadonly(source2) {
+  return {
+    [BINDING_SYMBOL]: true,
+    get value() {
+      return source2.value;
+    }
+  };
+}
+function unwrap(value) {
+  if (isBinding(value)) {
+    return value.value;
+  }
+  return value;
+}
 // src/reactivity/batching.ts
 function batch(fn) {
   incrementBatchDepth();
@@ -1330,6 +1361,7 @@ export {
   writeVersion,
   updateReaction,
   updateEffect,
+  unwrap,
   untracking,
   untrack,
   toRaw,
@@ -1355,6 +1387,7 @@ export {
   markReactions,
   isReactive,
   isDirty,
+  isBinding,
   incrementWriteVersion,
   incrementReadVersion,
   incrementBatchDepth,
@@ -1372,6 +1405,8 @@ export {
   createEquals,
   createEffect,
   createDerived,
+  bindReadonly,
+  bind,
   batchDepth,
   batch,
   alwaysEquals,

package/dist/primitives/bind.d.ts

@@ -0,0 +1,95 @@
+import type { WritableSignal, ReadableSignal } from '../core/types.js';
+/**
+ * A writable binding that forwards reads and writes to a source.
+ * Reading creates dependency on source, writing triggers source's reactions.
+ */
+export interface Binding<T> {
+    get value(): T;
+    set value(v: T);
+}
+/**
+ * A read-only binding that forwards reads to a source.
+ * Reading creates dependency on source, writing throws an error.
+ */
+export interface ReadonlyBinding<T> {
+    readonly value: T;
+}
+/**
+ * Check if a value is a binding created by bind()
+ */
+export declare function isBinding(value: unknown): value is Binding<unknown>;
+/**
+ * Create a reactive binding to a signal or another binding.
+ *
+ * A binding is a "reactive pointer" - it forwards reads and writes to the source.
+ * This enables connecting user's reactive state to internal component state.
+ *
+ * @example
+ * ```ts
+ * const source = signal(0)
+ * const binding = bind(source)
+ *
+ * // Reading through binding reads from source (creates dependency)
+ * console.log(binding.value)  // → 0
+ *
+ * // Writing through binding writes to source (triggers reactivity)
+ * binding.value = 42
+ * console.log(source.value)  // → 42
+ * ```
+ *
+ * @example Two-way binding for inputs
+ * ```ts
+ * const username = signal('')
+ * const inputBinding = bind(username)
+ *
+ * // When user types:
+ * inputBinding.value = 'alice'  // Updates username signal!
+ * ```
+ *
+ * @example Chaining bindings
+ * ```ts
+ * const source = signal(0)
+ * const b1 = bind(source)
+ * const b2 = bind(b1)  // Points to same source
+ *
+ * b2.value = 99
+ * console.log(source.value)  // → 99
+ * ```
+ */
+export declare function bind<T>(source: WritableSignal<T>): Binding<T>;
+export declare function bind<T>(source: ReadableSignal<T>): ReadonlyBinding<T>;
+export declare function bind<T>(source: Binding<T>): Binding<T>;
+export declare function bind<T>(source: ReadonlyBinding<T>): ReadonlyBinding<T>;
+/**
+ * Create an explicitly read-only binding.
+ * Attempting to write will throw an error at runtime.
+ *
+ * Use this when you want to ensure a binding is never written to,
+ * even if the source is writable.
+ *
+ * @example
+ * ```ts
+ * const source = signal(0)
+ * const readonly = bindReadonly(source)
+ *
+ * console.log(readonly.value)  // → 0
+ * readonly.value = 42  // Throws: Cannot write to a read-only binding
+ * ```
+ */
+export declare function bindReadonly<T>(source: ReadableSignal<T> | Binding<T>): ReadonlyBinding<T>;
+/**
+ * Get the value from a binding or return the value directly if not a binding.
+ * Useful for reading values that may or may not be bound.
+ *
+ * @example
+ * ```ts
+ * const arr: (string | Binding<string>)[] = [
+ *   'static',
+ *   bind(signal('dynamic'))
+ * ]
+ *
+ * arr.map(unwrap)  // → ['static', 'dynamic']
+ * ```
+ */
+export declare function unwrap<T>(value: T | Binding<T> | ReadonlyBinding<T>): T;
+//# sourceMappingURL=bind.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"bind.d.ts","sourceRoot":"","sources":["../../src/primitives/bind.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAA;AAMtE;;;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;AAQD;;GAEG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,OAAO,CAAC,OAAO,CAAC,CAEnE;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,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;AA6BvE;;;;;;;;;;;;;;;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,CAKvE"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@rlabs-inc/signals",
-  "version": "1.0.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, and reactive collections.",
+  "version": "1.2.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",
   "types": "dist/index.d.ts",
@@ -37,6 +37,9 @@
     "derived",
     "computed",
     "observable",
+    "bind",
+    "binding",
+    "two-way-binding",
     "svelte",
     "typescript"
   ],