@silvery/signals 0.5.0 → 0.23.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bjørn Stabell
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,48 @@
+# @silvery/signals
+
+Reactive signals for silvery -- thin wrapper around [alien-signals](https://github.com/nicepkg/alien-signals).
+
+Provides fine-grained reactivity: signals hold values, computeds derive from them, and effects re-run when dependencies change.
+
+Part of the [Silvery](https://silvery.dev) ecosystem.
+
+## Install
+
+```bash
+npm install @silvery/signals
+```
+
+## Quick Start
+
+```ts
+import { signal, computed, effect, batch } from "@silvery/signals"
+
+const count = signal(0)
+const doubled = computed(() => count() * 2)
+effect(() => console.log(`doubled: ${doubled()}`)) // logs "doubled: 0"
+
+batch(() => {
+  count(1)
+  count(2)
+}) // logs "doubled: 4" (once, not twice)
+```
+
+## API
+
+### Core
+
+- **`signal(value)`** -- Create a reactive value (call to read, call with arg to write)
+- **`computed(fn)`** -- Derived value that recomputes when dependencies change
+- **`effect(fn)`** -- Side effect that re-runs when dependencies change
+- **`batch(fn)`** -- Batch multiple updates into one notification
+
+### Advanced
+
+- **`effectScope(fn)`** -- Group effects for collective disposal
+- **`startBatch()` / `endBatch()`** -- Manual batch control
+- **`trigger(signal)`** -- Force subscribers to re-run
+- **`isSignal(v)`**, **`isComputed(v)`**, **`isEffect(v)`**, **`isEffectScope(v)`** -- Type guards
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,56 @@
+import { computed, effect, effectScope, endBatch, getActiveSub, getBatchDepth, isComputed, isEffect, isEffectScope, isSignal, setActiveSub, signal, startBatch, trigger } from "alien-signals";
+
+//#region src/index.d.ts
+/**
+ * A reactive value — callable getter/setter.
+ *
+ * - `sig()` reads the current value (and subscribes the active effect/computed).
+ * - `sig(next)` writes a new value; subscribers re-run only if `next !== current`.
+ *
+ * Matches the return shape of `signal<T>(initial)` from alien-signals, so any
+ * `signal()` result is assignable to `Signal<T>`.
+ */
+type Signal<T> = {
+  (): T;
+  (value: T): void;
+};
+/**
+ * A read-only reactive value — callable getter that subscribes the active
+ * effect/computed but cannot be written to. Matches the return shape of
+ * `computed<T>(fn)` from alien-signals.
+ */
+type ReadSignal<T> = () => T;
+/** Batch multiple signal updates, notifying subscribers once at the end. */
+declare function batch(fn: () => void): void;
+/**
+ * Options for {@link watch}.
+ */
+interface WatchOptions<T> {
+  /** If true, fire `onChange` on the seed read with `(next, next)`. Default false (change-only). */
+  immediate?: boolean;
+  /** Equality predicate — handler fires only when `equals(next, prev)` is false. Default `Object.is`. */
+  equals?: (a: T, b: T) => boolean;
+}
+/**
+ * Subscribe to signal changes via an imperative callback.
+ *
+ * alien-signals' `effect()` runs once eagerly to establish dependencies,
+ * which means an `effect(() => { handler(sig()) })` fires with the seed
+ * value. `watch()` swallows that first fire and only calls `onChange` when
+ * the value actually changes — matching the old `.subscribe(handler)`
+ * semantic consumers often want.
+ *
+ * ```ts
+ * const stop = watch(
+ *   () => size.snapshot(),
+ *   (next, prev) => { emit({ cols: next.cols, rows: next.rows }) },
+ * )
+ * // stop() to unsubscribe
+ * ```
+ *
+ * Returns the effect's stop function.
+ */
+declare function watch<T>(read: () => T, onChange: (next: T, prev: T) => void, opts?: WatchOptions<T>): () => void;
+//#endregion
+export { ReadSignal, Signal, WatchOptions, batch, computed, effect, effectScope, endBatch, getActiveSub, getBatchDepth, isComputed, isEffect, isEffectScope, isSignal, setActiveSub, signal, startBatch, trigger, watch };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/index.ts"],"mappings":";;;;;;;AAuDA;;;;;KAbY,MAAA;EAAA,IACN,CAAA;EAAA,CACH,KAAA,EAAO,CAAA;AAAA;;;;;;KAQE,UAAA,YAAsB,CAAA;;iBAGlB,KAAA,CAAM,EAAA;;AAsCtB;;UA1BiB,YAAA;EA2BH;EAzBZ,SAAA;EA0B0B;EAxB1B,MAAA,IAAU,CAAA,EAAG,CAAA,EAAG,CAAA,EAAG,CAAA;AAAA;;;;;;;;;;;;;;;;;;;;iBAsBL,KAAA,GAAA,CACd,IAAA,QAAY,CAAA,EACZ,QAAA,GAAW,IAAA,EAAM,CAAA,EAAG,IAAA,EAAM,CAAA,WAC1B,IAAA,GAAM,YAAA,CAAa,CAAA"}

package/dist/index.mjs

@@ -0,0 +1,52 @@
+import { computed, effect, effect as effect$1, effectScope, endBatch, endBatch as endBatch$1, getActiveSub, getBatchDepth, isComputed, isEffect, isEffectScope, isSignal, setActiveSub, signal, startBatch, startBatch as startBatch$1, trigger } from "alien-signals";
+//#region src/index.ts
+/** Batch multiple signal updates, notifying subscribers once at the end. */
+function batch(fn) {
+	startBatch$1();
+	try {
+		fn();
+	} finally {
+		endBatch$1();
+	}
+}
+/**
+* Subscribe to signal changes via an imperative callback.
+*
+* alien-signals' `effect()` runs once eagerly to establish dependencies,
+* which means an `effect(() => { handler(sig()) })` fires with the seed
+* value. `watch()` swallows that first fire and only calls `onChange` when
+* the value actually changes — matching the old `.subscribe(handler)`
+* semantic consumers often want.
+*
+* ```ts
+* const stop = watch(
+*   () => size.snapshot(),
+*   (next, prev) => { emit({ cols: next.cols, rows: next.rows }) },
+* )
+* // stop() to unsubscribe
+* ```
+*
+* Returns the effect's stop function.
+*/
+function watch(read, onChange, opts = {}) {
+	const equals = opts.equals ?? Object.is;
+	let seeded = false;
+	let prev;
+	return effect$1(() => {
+		const next = read();
+		if (!seeded) {
+			seeded = true;
+			prev = next;
+			if (opts.immediate) onChange(next, next);
+			return;
+		}
+		if (equals(next, prev)) return;
+		const old = prev;
+		prev = next;
+		onChange(next, old);
+	});
+}
+//#endregion
+export { batch, computed, effect, effectScope, endBatch, getActiveSub, getBatchDepth, isComputed, isEffect, isEffectScope, isSignal, setActiveSub, signal, startBatch, trigger, watch };
+
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":["effect"],"sources":["../src/index.ts"],"sourcesContent":["/**\n * @silvery/signals — Reactive signals for silvery.\n *\n * Thin wrapper around alien-signals providing:\n * - signal(value) — create a reactive value (call to read, call with arg to write)\n * - computed(fn) — derived reactive value that recomputes on dependency changes\n * - effect(fn) — side effect that re-runs when dependencies change\n * - effectScope(fn) — group effects for collective disposal\n * - batch(fn) — batch multiple signal updates into one notification\n * - watch(read, onChange) — change-only subscription (skips the seed fire)\n *\n * @packageDocumentation\n */\n\nexport {\n  signal,\n  computed,\n  effect,\n  effectScope,\n  startBatch,\n  endBatch,\n  trigger,\n  isSignal,\n  isComputed,\n  isEffect,\n  isEffectScope,\n  getActiveSub,\n  setActiveSub,\n  getBatchDepth,\n} from \"alien-signals\"\n\nimport { effect, startBatch, endBatch } from \"alien-signals\"\n\n/**\n * A reactive value — callable getter/setter.\n *\n * - `sig()` reads the current value (and subscribes the active effect/computed).\n * - `sig(next)` writes a new value; subscribers re-run only if `next !== current`.\n *\n * Matches the return shape of `signal<T>(initial)` from alien-signals, so any\n * `signal()` result is assignable to `Signal<T>`.\n */\nexport type Signal<T> = {\n  (): T\n  (value: T): void\n}\n\n/**\n * A read-only reactive value — callable getter that subscribes the active\n * effect/computed but cannot be written to. Matches the return shape of\n * `computed<T>(fn)` from alien-signals.\n */\nexport type ReadSignal<T> = () => T\n\n/** Batch multiple signal updates, notifying subscribers once at the end. */\nexport function batch(fn: () => void): void {\n  startBatch()\n  try {\n    fn()\n  } finally {\n    endBatch()\n  }\n}\n\n/**\n * Options for {@link watch}.\n */\nexport interface WatchOptions<T> {\n  /** If true, fire `onChange` on the seed read with `(next, next)`. Default false (change-only). */\n  immediate?: boolean\n  /** Equality predicate — handler fires only when `equals(next, prev)` is false. Default `Object.is`. */\n  equals?: (a: T, b: T) => boolean\n}\n\n/**\n * Subscribe to signal changes via an imperative callback.\n *\n * alien-signals' `effect()` runs once eagerly to establish dependencies,\n * which means an `effect(() => { handler(sig()) })` fires with the seed\n * value. `watch()` swallows that first fire and only calls `onChange` when\n * the value actually changes — matching the old `.subscribe(handler)`\n * semantic consumers often want.\n *\n * ```ts\n * const stop = watch(\n *   () => size.snapshot(),\n *   (next, prev) => { emit({ cols: next.cols, rows: next.rows }) },\n * )\n * // stop() to unsubscribe\n * ```\n *\n * Returns the effect's stop function.\n */\nexport function watch<T>(\n  read: () => T,\n  onChange: (next: T, prev: T) => void,\n  opts: WatchOptions<T> = {},\n): () => void {\n  const equals = opts.equals ?? Object.is\n  let seeded = false\n  let prev!: T\n  return effect(() => {\n    const next = read()\n    if (!seeded) {\n      seeded = true\n      prev = next\n      if (opts.immediate) onChange(next, next)\n      return\n    }\n    if (equals(next, prev)) return\n    const old = prev\n    prev = next\n    onChange(next, old)\n  })\n}\n"],"mappings":";;;AAuDA,SAAgB,MAAM,IAAsB;AAC1C,eAAY;AACZ,KAAI;AACF,MAAI;WACI;AACR,cAAU;;;;;;;;;;;;;;;;;;;;;;AAiCd,SAAgB,MACd,MACA,UACA,OAAwB,EAAE,EACd;CACZ,MAAM,SAAS,KAAK,UAAU,OAAO;CACrC,IAAI,SAAS;CACb,IAAI;AACJ,QAAOA,eAAa;EAClB,MAAM,OAAO,MAAM;AACnB,MAAI,CAAC,QAAQ;AACX,YAAS;AACT,UAAO;AACP,OAAI,KAAK,UAAW,UAAS,MAAM,KAAK;AACxC;;AAEF,MAAI,OAAO,MAAM,KAAK,CAAE;EACxB,MAAM,MAAM;AACZ,SAAO;AACP,WAAS,MAAM,IAAI;GACnB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@silvery/signals",
-  "version": "0.5.0",
+  "version": "0.23.0",
   "description": "Reactive signals for silvery — thin wrapper around alien-signals",
   "license": "MIT",
   "author": "Bjørn Stabell <bjorn@stabell.org>",
@@ -10,21 +10,28 @@
     "directory": "packages/signals"
   },
   "files": [
-    "src"
+    "dist"
   ],
   "type": "module",
-  "main": "src/index.ts",
-  "types": "src/index.ts",
   "exports": {
     ".": {
-      "types": "./src/index.ts",
-      "import": "./src/index.ts"
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
     }
   },
   "publishConfig": {
     "access": "public"
   },
   "dependencies": {
-    "alien-signals": "^3.1.2"
+    "alien-signals": "~3.2.1"
+  },
+  "tsdown": {
+    "clean": true,
+    "dts": true,
+    "entry": "src/index.ts",
+    "format": "esm"
+  },
+  "scripts": {
+    "build": "tsdown"
   }
-}
+}

package/src/index.ts

@@ -1,41 +0,0 @@
-/**
- * @silvery/signals — Reactive signals for silvery.
- *
- * Thin wrapper around alien-signals providing:
- * - signal(value) — create a reactive value (call to read, call with arg to write)
- * - computed(fn) — derived reactive value that recomputes on dependency changes
- * - effect(fn) — side effect that re-runs when dependencies change
- * - effectScope(fn) — group effects for collective disposal
- * - batch(fn) — batch multiple signal updates into one notification
- *
- * @packageDocumentation
- */
-
-export {
-  signal,
-  computed,
-  effect,
-  effectScope,
-  startBatch,
-  endBatch,
-  trigger,
-  isSignal,
-  isComputed,
-  isEffect,
-  isEffectScope,
-  getActiveSub,
-  setActiveSub,
-  getBatchDepth,
-} from "alien-signals"
-
-import { startBatch, endBatch } from "alien-signals"
-
-/** Batch multiple signal updates, notifying subscribers once at the end. */
-export function batch(fn: () => void): void {
-  startBatch()
-  try {
-    fn()
-  } finally {
-    endBatch()
-  }
-}