@rlabs-inc/signals 1.1.0 → 1.2.1

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,7 +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 { bind, bindReadonly, isBinding, unwrap, signals } 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';

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

package/dist/index.js

@@ -40,6 +40,7 @@ __export(exports_src, {
   stateRaw: () => stateRaw,
   state: () => state,
   source: () => source,
+  signals: () => signals,
   signal: () => signal,
   shallowEquals: () => shallowEquals,
   setUntracking: () => setUntracking,
@@ -966,14 +967,34 @@ var BINDING_SYMBOL = Symbol("binding");
 function isBinding(value) {
   return value !== null && typeof value === "object" && BINDING_SYMBOL in value;
 }
+function isSignal(value) {
+  return value !== null && typeof value === "object" && "value" in value;
+}
+function isGetter(value) {
+  return typeof value === "function";
+}
 function bind(source2) {
+  if (isGetter(source2)) {
+    return {
+      [BINDING_SYMBOL]: true,
+      get value() {
+        return source2();
+      }
+    };
+  }
+  let actualSource;
+  if (isBinding(source2) || isSignal(source2)) {
+    actualSource = source2;
+  } else {
+    actualSource = signal(source2);
+  }
   const binding = {
     [BINDING_SYMBOL]: true,
     get value() {
-      return source2.value;
+      return actualSource.value;
     },
     set value(v) {
-      source2.value = v;
+      actualSource.value = v;
     }
   };
   return binding;
@@ -992,6 +1013,15 @@ function unwrap(value) {
   }
   return value;
 }
+function signals(initial) {
+  const result = {};
+  for (const key in initial) {
+    if (Object.prototype.hasOwnProperty.call(initial, key)) {
+      result[key] = signal(initial[key]);
+    }
+  }
+  return result;
+}
 // src/reactivity/batching.ts
 function batch(fn) {
   incrementBatchDepth();

package/dist/index.mjs

@@ -854,14 +854,34 @@ var BINDING_SYMBOL = Symbol("binding");
 function isBinding(value) {
   return value !== null && typeof value === "object" && BINDING_SYMBOL in value;
 }
+function isSignal(value) {
+  return value !== null && typeof value === "object" && "value" in value;
+}
+function isGetter(value) {
+  return typeof value === "function";
+}
 function bind(source2) {
+  if (isGetter(source2)) {
+    return {
+      [BINDING_SYMBOL]: true,
+      get value() {
+        return source2();
+      }
+    };
+  }
+  let actualSource;
+  if (isBinding(source2) || isSignal(source2)) {
+    actualSource = source2;
+  } else {
+    actualSource = signal(source2);
+  }
   const binding = {
     [BINDING_SYMBOL]: true,
     get value() {
-      return source2.value;
+      return actualSource.value;
     },
     set value(v) {
-      source2.value = v;
+      actualSource.value = v;
     }
   };
   return binding;
@@ -880,6 +900,15 @@ function unwrap(value) {
   }
   return value;
 }
+function signals(initial) {
+  const result = {};
+  for (const key in initial) {
+    if (Object.prototype.hasOwnProperty.call(initial, key)) {
+      result[key] = signal(initial[key]);
+    }
+  }
+  return result;
+}
 // src/reactivity/batching.ts
 function batch(fn) {
   incrementBatchDepth();
@@ -1369,6 +1398,7 @@ export {
   stateRaw,
   state,
   source,
+  signals,
   signal,
   shallowEquals,
   setUntracking,

package/dist/primitives/bind.d.ts

@@ -18,48 +18,12 @@ export interface ReadonlyBinding<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>;
+export declare function bind<T>(source: () => T): ReadonlyBinding<T>;
+export declare function bind<T>(source: T): Binding<T>;
 /**
  * Create an explicitly read-only binding.
  * Attempting to write will throw an error at runtime.
@@ -92,4 +56,31 @@ export declare function bindReadonly<T>(source: ReadableSignal<T> | Binding<T>):
  * ```
  */
 export declare function unwrap<T>(value: T | Binding<T> | ReadonlyBinding<T>): T;
+/**
+ * Create multiple signals from an object.
+ * Returns an object with the same keys, where each value is a signal.
+ *
+ * This is a convenience helper for creating reactive props without
+ * declaring each signal individually.
+ *
+ * @example
+ * ```ts
+ * // Instead of:
+ * const content = signal('hello')
+ * const width = signal(40)
+ * const visible = signal(true)
+ *
+ * // Do this:
+ * const ui = signals({ content: 'hello', width: 40, visible: true })
+ *
+ * // Pass to components:
+ * text({ content: ui.content })  // ui.content IS a Signal<string>
+ *
+ * // Update:
+ * ui.content.value = 'updated'  // Works!
+ * ```
+ */
+export declare function signals<T extends Record<string, unknown>>(initial: T): {
+    [K in keyof T]: WritableSignal<T[K]>;
+};
 //# sourceMappingURL=bind.d.ts.map

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,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"}
+{"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;AAOtE;;;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;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,CAAC,CAAC,CAAA;AAiD9C;;;;;;;;;;;;;;;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;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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rlabs-inc/signals",
-  "version": "1.1.0",
+  "version": "1.2.1",
   "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",
@@ -37,6 +37,9 @@
     "derived",
     "computed",
     "observable",
+    "bind",
+    "binding",
+    "two-way-binding",
     "svelte",
     "typescript"
   ],