@pithyjs/signals 0.1.0-beta.0 → 0.1.0-beta.1

package/LICENSE

@@ -19,3 +19,30 @@ 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.
+
+---
+
+The dependency graph in src/signal.ts is adapted from alien-signals
+(https://github.com/stackblitz/alien-signals), under the following license:
+
+MIT License
+
+Copyright (c) 2024-present Johnson Chu
+
+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

@@ -1,6 +1,6 @@
 # @pithyjs/signals
 
-Fine-grained reactive signal system for the PithyJS framework. Signals provide O(1) reactive state with automatic dependency tracking — no virtual DOM, no re-renders, only the exact DOM nodes that depend on a signal update.
+Fine-grained reactive signal system for the PithyJS framework. Signals provide reactive state with automatic dependency tracking — no virtual DOM, no re-renders, only the exact DOM nodes that depend on a signal update.
 
 ## Installation
 
@@ -19,7 +19,7 @@ yarn add @pithyjs/signals
 <!-- @codex:end -->
 
 ```typescript
-import { signal, computed, effect, batch, onCleanup, isSignal } from '@pithyjs/signals';
+import { signal, computed, effect, batch, untrack, onCleanup, isSignal } from '@pithyjs/signals';
 ```
 
 ## Quick Start
@@ -40,14 +40,78 @@ count(); // → 1
 <!-- @codex:auto api="pithy.feature.signals" format="table" -->
 | API | Signature | Stability | Description |
 | --- | --- | --- | --- |
-| isSignal | `(value: unknown) => value is Signal<any>` | stable | - |
+| isSignal | `(value: unknown) => value is ReadableSignal<unknown>` | stable | - |
 | onCleanup | `(fn: () => void) => void` | stable | - |
 | effect | `(fn: () => void) => () => void` | stable | - |
 | batch | `(fn: () => void) => void` | stable | - |
+| untrack | `<T>(fn: () => T) => T` | stable | - |
+| createRoot | `<T>(fn: (dispose: () => void) => T) => T` | stable | - |
 | signal | `<T>(initial: T) => Signal<T>` | stable | - |
-| computed | `<T>(compute: () => T) => () => T` | stable | - |
+| computed | `<T>(compute: () => T) => ReadableSignal<T>` | stable | - |
 <!-- @codex:end -->
 
+### How a computed updates
+
+A write marks the computeds downstream of it and runs the effects they reach,
+once each, before `set()` returns. A computed recomputes when something reads
+it, and only if one of its sources changed, so every effect sees values that
+belong together: a diamond reads `4/3`, never `4/2`. A computed nobody reads does
+not recompute. It computes once when created, and it has no `set()`.
+
+Inside a `batch()` body, a computed read is up to date with the values written
+so far. A compute that throws there returns its last value and stays
+out of date; its next reader computes it on the final values and reports the
+error if it still fails. The full rules are in [`docs/signals/semantics.md`](../../docs/signals/semantics.md).
+
+### A computed must be pure
+
+A `computed()`'s compute, and any `onCleanup` it registers, must not write a
+signal or create an effect. A compute runs while an effect is reading it, so a
+write from inside it changes state under that effect. In development, the first
+such write or effect from each computed logs a warning; move the work into an
+`effect()` that reads the computed.
+
+### When a subscriber throws
+
+- A `set()`, or the flush at the end of the outermost `batch()`, notifies every
+  subscriber and listener, then rethrows the first failure it collected. A write
+  made from inside an effect behaves the same way.
+- A `computed()` whose compute throws keeps its last value, and the write or
+  batch flush that made it recompute reports the error once its effects have
+  run. Inside a batch body the error is not reported there: the computed stays
+  out of date, and its next reader reports on the values the batch leaves.
+  Reading a computed inside a write, an effect or a batch never throws. A read
+  outside all three throws the error, and so does every later one until a write
+  lets the compute succeed. A computed whose first compute throws is disposed,
+  and `computed()` rethrows; so is one whose first compute fails through a
+  computed it reads, outside any write, effect or batch.
+- An effect whose first run throws makes `effect()` throw, and so does one whose
+  first run reads a failing computed outside any write, effect or batch. The
+  caller then gets no disposer: with no owner, the effect is disposed first;
+  under an owner (`createRoot()` or another effect), it stays alive and owned,
+  and runs again on the next write to what it read. An effect created inside a
+  `batch()` body first runs when the batch ends, and the batch reports its
+  failure.
+- Two computeds that read each other are not detected as a cycle: each reads
+  the other's last value, so the pair can disagree until a later write.
+- The exception is a write to a signal that is still notifying — an effect writing
+  a signal it reads, or a reactive cycle. That notification stops at the failure
+  and rethrows the first one it collected, and so does any notification it was
+  started from, up to the outermost one, which carries on. A `batch()` inside an
+  effect that a flush is running does the same.
+- A reactive cycle whose effects let the error propagate ends in a stack overflow.
+  One whose effects catch their own errors hangs
+  ([BUG-049](../../docs/BUGS.md)).
+- A write that never settles can hang where a throwing subscriber used to end it:
+  a self-writing cycle through `batch()` beside a subscriber that throws, or a
+  chain deeper than the stack with several writers at each level
+  ([BUG-050](../../docs/BUGS.md)).
+- If a batch body throws, its error is the one reported, even when the flush
+  fails too.
+- A `subscribe()` listener that throws on its first, immediate call is not kept.
+  One that throws on a later write stays subscribed and rethrows on every write
+  until it is unsubscribed.
+
 ## Examples
 
 <!-- @codex:auto examples="pithy.feature.signals" -->
@@ -142,6 +206,29 @@ isSignal(42); // → false
 isSignal(() => {}); // → false
 isSignal(null); // → false
 ```
+
+**unsubscribes from a dependency it stopped reading**
+
+```typescript
+const useB = signal(true);
+const b = signal(2);
+
+let runs = 0;
+const dispose = effect(() => {
+  runs += 1;
+  if (useB()) b();
+});
+
+useB.set(false);
+const afterSwitch = runs;
+
+b.set(99);
+expect(runs, 'live effect re-ran for a dependency it stopped reading').toBe(
+  afterSwitch
+);
+
+dispose();
+```
 <!-- @codex:end -->
 
 ## Testing
@@ -153,6 +240,8 @@ isSignal(null); // → false
 | onCleanup | ✓ | - | - | Missing integration |
 | effect | ✓ | - | - | Missing integration |
 | batch | ✓ | - | - | Missing integration |
+| untrack | ✓ | - | - | Missing integration |
+| createRoot | ✓ | - | - | Missing integration |
 | signal | ✓ | - | - | Missing integration |
 | computed | ✓ | - | - | Missing integration |
 <!-- @codex:end -->

package/dist/internals.d.ts

@@ -0,0 +1,29 @@
+import { EffectFn } from './types';
+declare global {
+    const __PITHY_TEST__: boolean | undefined;
+}
+export interface ContextReading {
+    effect: object | null;
+    owner: object | null;
+    tracking: boolean;
+    suppression: number;
+    batching: boolean;
+    pending: number;
+    notifying: number;
+    flushing: number;
+}
+export interface Introspection {
+    context: () => ContextReading;
+    cleanupStack: (owner: object) => readonly EffectFn[] | null | undefined;
+    subscribers: (node: object) => readonly object[];
+    links: (node: object) => number;
+    dependencies: (node: object) => readonly object[];
+    disposed: (node: object) => boolean;
+}
+export declare const nodesOf: WeakMap<object, object>;
+export declare const effectWrappers: WeakMap<EffectFn, object>;
+export declare const rootOwners: WeakMap<EffectFn, object>;
+export declare const disposerCalled: WeakSet<object>;
+export declare function installIntrospection(source: Introspection): void;
+export declare function introspection(): Introspection;
+//# sourceMappingURL=internals.d.ts.map

package/dist/internals.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"internals.d.ts","sourceRoot":"","sources":["../src/internals.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAEnC,OAAO,CAAC,MAAM,CAAC;IACb,MAAM,cAAc,EAAE,OAAO,GAAG,SAAS,CAAC;CAC3C;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,QAAQ,EAAE,OAAO,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,OAAO,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,cAAc,CAAC;IAC9B,YAAY,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,SAAS,QAAQ,EAAE,GAAG,IAAI,GAAG,SAAS,CAAC;IACxE,WAAW,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,SAAS,MAAM,EAAE,CAAC;IACjD,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;IAChC,YAAY,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,SAAS,MAAM,EAAE,CAAC;IAClD,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;CACrC;AAED,eAAO,MAAM,OAAO,EAAE,OAAO,CAAC,MAAM,EAAE,MAAM,CAAiB,CAAC;AAE9D,eAAO,MAAM,cAAc,EAAE,OAAO,CAAC,QAAQ,EAAE,MAAM,CAAiB,CAAC;AAEvE,eAAO,MAAM,UAAU,EAAE,OAAO,CAAC,QAAQ,EAAE,MAAM,CAAiB,CAAC;AAEnE,eAAO,MAAM,cAAc,EAAE,OAAO,CAAC,MAAM,CAAiB,CAAC;AAI7D,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,aAAa,GAAG,IAAI,CAEhE;AAED,wBAAgB,aAAa,IAAI,aAAa,CAO7C"}

package/dist/internals.js

@@ -0,0 +1,15 @@
+export const nodesOf = new WeakMap();
+export const effectWrappers = new WeakMap();
+export const rootOwners = new WeakMap();
+export const disposerCalled = new WeakSet();
+let installed = null;
+export function installIntrospection(source) {
+    installed = source;
+}
+export function introspection() {
+    if (!installed) {
+        throw new Error('[PithyJS] Signal introspection is not installed. Define `__PITHY_TEST__` as `true` in the vitest config that needs it, as `packages/signals/vitest.config.ts` does.');
+    }
+    return installed;
+}
+//# sourceMappingURL=internals.js.map

package/dist/internals.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"internals.js","sourceRoot":"","sources":["../src/internals.ts"],"names":[],"mappings":"AA0BA,MAAM,CAAC,MAAM,OAAO,GAA4B,IAAI,OAAO,EAAE,CAAC;AAE9D,MAAM,CAAC,MAAM,cAAc,GAA8B,IAAI,OAAO,EAAE,CAAC;AAEvE,MAAM,CAAC,MAAM,UAAU,GAA8B,IAAI,OAAO,EAAE,CAAC;AAEnE,MAAM,CAAC,MAAM,cAAc,GAAoB,IAAI,OAAO,EAAE,CAAC;AAE7D,IAAI,SAAS,GAAyB,IAAI,CAAC;AAE3C,MAAM,UAAU,oBAAoB,CAAC,MAAqB;IACxD,SAAS,GAAG,MAAM,CAAC;AACrB,CAAC;AAED,MAAM,UAAU,aAAa;IAC3B,IAAI,CAAC,SAAS,EAAE,CAAC;QACf,MAAM,IAAI,KAAK,CACb,qKAAqK,CACtK,CAAC;IACJ,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/dist/signal.d.ts

@@ -5,17 +5,20 @@
   "category": "feature"
 }
 */
-import { Signal } from './types';
+import { ReadableSignal, Signal } from './types';
 /**
- * Checks if a value is a Signal at runtime.
+ * Checks if a value is a signal or a computed at runtime.
  * @param value - The value to check.
- * @returns True if the value is a Signal.
+ * @returns True if the value is a signal or a computed.
  */
-/** @codexApi {"parent":"pithy.feature.signals","name":"isSignal","stability":"stable","signature":"(value: unknown) => value is Signal<any>"} */
-export declare function isSignal(value: unknown): value is Signal<unknown>;
+/** @codexApi {"parent":"pithy.feature.signals","name":"isSignal","stability":"stable","signature":"(value: unknown) => value is ReadableSignal<unknown>"} */
+export declare function isSignal(value: unknown): value is ReadableSignal<unknown>;
 /**
- * Registers a cleanup callback that will be executed
- * before the current effect is re-run.
+ * Registers a cleanup callback, executed once — before the current effect's
+ * next re-run, or when it is disposed, whichever comes first. Effects and
+ * computeds created during a run are
+ * owned by that run and torn down on the same schedule; use `createRoot` for
+ * work that must outlive the run that built it.
  *
  * @param fn - The cleanup function.
  */
@@ -32,12 +35,35 @@ export declare function onCleanup(fn: () => void): void;
 export declare function effect(fn: () => void): () => void;
 /**
  * Batches multiple signal updates together.
- * Effects triggered during the batch are deferred and executed once after the batch.
+ * Batches nest: effects triggered inside are deferred and run once, after the outermost batch.
  *
  * @param fn - The function performing multiple signal updates.
  */
 /** @codexApi {"parent":"pithy.feature.signals","name":"batch","stability":"stable","signature":"(fn: () => void) => void"} */
 export declare function batch(fn: () => void): void;
+/**
+ * Reads signals without subscribing the enclosing effect to them.
+ *
+ * @param fn - The function to run untracked.
+ * @returns Whatever `fn` returns.
+ */
+/** @codexApi {"parent":"pithy.feature.signals","name":"untrack","stability":"stable","signature":"<T>(fn: () => T) => T"} */
+export declare function untrack<T>(fn: () => T): T;
+/**
+ * Creates an ownership root: effects and computeds created inside `fn` are owned
+ * by the root rather than by any enclosing effect, so an enclosing re-run does
+ * not dispose them. Disposing the root disposes everything it owns — but a root
+ * created inside another root is independent: hold its disposer, because the
+ * outer root will not reach it.
+ *
+ * Tracking is untouched — a signal read inside `fn` still subscribes whatever
+ * effect is current.
+ *
+ * @param fn - Receives the root's disposer.
+ * @returns Whatever `fn` returns.
+ */
+/** @codexApi {"parent":"pithy.feature.signals","name":"createRoot","stability":"stable","signature":"<T>(fn: (dispose: () => void) => T) => T"} */
+export declare function createRoot<T>(fn: (dispose: () => void) => T): T;
 /**
  * Creates a signal: a reactive function holding a value and supporting subscriptions.
  *
@@ -47,12 +73,12 @@ export declare function batch(fn: () => void): void;
 /** @codexApi {"parent":"pithy.feature.signals","name":"signal","stability":"stable","signature":"<T>(initial: T) => Signal<T>"} */
 export declare function signal<T>(initial: T): Signal<T>;
 /**
- * Creates a derived signal (computed value) that automatically
- * recalculates when its dependencies change.
+ * Creates a derived signal (computed value). It computes once when created,
+ * then recomputes when it is read after one of its sources changed.
  *
- * @param compute - A function returning the computed value.
- * @returns A readonly function returning the latest computed value.
+ * @param compute - A function returning the computed value. It must not write signals or create effects.
+ * @returns A read-only signal returning the latest computed value.
  */
-/** @codexApi {"parent":"pithy.feature.signals","name":"computed","stability":"stable","signature":"<T>(compute: () => T) => () => T"} */
-export declare function computed<T>(compute: () => T): () => T;
+/** @codexApi {"parent":"pithy.feature.signals","name":"computed","stability":"stable","signature":"<T>(compute: () => T) => ReadableSignal<T>"} */
+export declare function computed<T>(compute: () => T): ReadableSignal<T>;
 //# sourceMappingURL=signal.d.ts.map

package/dist/signal.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"signal.d.ts","sourceRoot":"","sources":["../src/signal.ts"],"names":[],"mappings":"AAAA;;;;;;EAME;AAEF,OAAO,EAAE,MAAM,EAAiB,MAAM,SAAS,CAAC;AAmChD;;;;GAIG;AACH,iJAAiJ;AACjJ,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAAC,OAAO,CAAC,CAKjE;AAiBD;;;;;GAKG;AACH,kIAAkI;AAClI,wBAAgB,SAAS,CAAC,EAAE,EAAE,MAAM,IAAI,GAAG,IAAI,CAK9C;AAED;;;;;;GAMG;AACH,qIAAqI;AACrI,wBAAgB,MAAM,CAAC,EAAE,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAajD;AAED;;;;;GAKG;AACH,8HAA8H;AAC9H,wBAAgB,KAAK,CAAC,EAAE,EAAE,MAAM,IAAI,GAAG,IAAI,CAa1C;AAED;;;;;GAKG;AACH,mIAAmI;AACnI,wBAAgB,MAAM,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,CAoE/C;AAED;;;;;;GAMG;AACH,yIAAyI;AACzI,wBAAgB,QAAQ,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,GAAG,MAAM,CAAC,CAmBrD"}
+{"version":3,"file":"signal.d.ts","sourceRoot":"","sources":["../src/signal.ts"],"names":[],"mappings":"AAAA;;;;;;EAME;AAIF,OAAO,EAAE,cAAc,EAAE,MAAM,EAAiB,MAAM,SAAS,CAAC;AA0kBhE;;;;GAIG;AACH,6JAA6J;AAC7J,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,cAAc,CAAC,OAAO,CAAC,CAKzE;AAiBD;;;;;;;;GAQG;AACH,kIAAkI;AAClI,wBAAgB,SAAS,CAAC,EAAE,EAAE,MAAM,IAAI,GAAG,IAAI,CAI9C;AAED;;;;;;GAMG;AACH,qIAAqI;AACrI,wBAAgB,MAAM,CAAC,EAAE,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAkFjD;AA8CD;;;;;GAKG;AACH,8HAA8H;AAC9H,wBAAgB,KAAK,CAAC,EAAE,EAAE,MAAM,IAAI,GAAG,IAAI,CAiD1C;AAED;;;;;GAKG;AACH,6HAA6H;AAC7H,wBAAgB,OAAO,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAQzC;AAED;;;;;;;;;;;;GAYG;AACH,mJAAmJ;AACnJ,wBAAgB,UAAU,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,OAAO,EAAE,MAAM,IAAI,KAAK,CAAC,GAAG,CAAC,CA2B/D;AA+CD;;;;;GAKG;AACH,mIAAmI;AACnI,wBAAgB,MAAM,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,CAgE/C;AAED;;;;;;GAMG;AACH,mJAAmJ;AACnJ,wBAAgB,QAAQ,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,GAAG,cAAc,CAAC,CAAC,CAAC,CAkH/D"}