@xmachines/play-signals 1.0.0-beta.45 → 1.0.0-beta.47

package/README.md

@@ -1,16 +1,10 @@
-# @xmachines/play-signals
-
-**Canonical Signals substrate for XMachines with Stage 1 API isolation**
+<!-- generated-by: gsd-doc-writer -->
 
-`@xmachines/play-signals` re-exports `Signal` from `signal-polyfill` as the single import boundary for XMachines packages.
-
-## Why This Package Exists
+# @xmachines/play-signals
 
-- Keep the raw `Signal` API as the canonical substrate surface.
-- Isolate Stage 1 proposal churn behind one package boundary.
-- Preserve Play invariants: Signal-only reactivity, passive infrastructure, and event-only mutation paths.
+TC39 Signals polyfill for XMachines — fine-grained reactive state primitives that enable glitch-free, subscription-free state propagation in the Play Architecture.
 
-This package does not add business behavior to signals. Adapters and renderers observe signals and forward events; they do not mutate business state directly.
+Part of the [xmachines-js monorepo](../../README.md).
 
 ## Installation
 
@@ -18,13 +12,27 @@ This package does not add business behavior to signals. Adapters and renderers o
 npm install @xmachines/play-signals
 ```
 
-## Current Exports
+## Overview
 
-- `Signal` (re-export from `signal-polyfill`)
-- `watchSignal(signal, onValue)`
-- Type exports from `src/types.ts`: `SignalState`, `SignalComputed`, `SignalWatcher`, `SignalOptions`, `ComputedOptions`, `WatcherNotify`
+This package wraps the [`signal-polyfill`](https://github.com/nicolo-ribaudo/tc39-proposal-signals-polyfill) reference implementation of the [TC39 Signals proposal](https://github.com/tc39/proposal-signals) (Stage 1). It re-exports the full `Signal` namespace and adds a memory-safe `watchSignal` utility, isolating the rest of the codebase from potential Stage 1 API churn.
 
-## Quick Start
+**All signal imports in the XMachines ecosystem should come from this package**, not directly from `signal-polyfill`, so that polyfill version bumps or API adaptations can be made in one place.
+
+## Usage
+
+### `Signal.State` — writable reactive state
+
+```typescript
+import { Signal } from "@xmachines/play-signals";
+
+const count = new Signal.State(0);
+
+console.log(count.get()); // 0
+count.set(5);
+console.log(count.get()); // 5
+```
+
+### `Signal.Computed` — lazy memoized derived values
 
 ```typescript
 import { Signal } from "@xmachines/play-signals";
@@ -32,93 +40,117 @@ import { Signal } from "@xmachines/play-signals";
 const count = new Signal.State(0);
 const doubled = new Signal.Computed(() => count.get() * 2);
 
-const watcher = new Signal.subtle.Watcher(() => {
-	queueMicrotask(() => {
-		const pending = watcher.getPending();
-		for (const signal of pending) {
-			signal.get();
-		}
-		watcher.watch(...pending);
-	});
-});
+console.log(doubled.get()); // 0  (computed on first access)
+count.set(5);
+console.log(doubled.get()); // 10 (recomputed because dependency changed)
+console.log(doubled.get()); // 10 (memoized — no recomputation)
+```
 
-watcher.watch(doubled);
-doubled.get();
+Computations automatically track every signal accessed inside them. Dynamic branching is fully supported — only signals read in the _current_ execution path are tracked as dependencies.
 
-count.set(2);
+### `watchSignal` — memory-safe one-shot effect
 
-const dispose = () => {
-	watcher.unwatch(doubled);
-};
+Use `watchSignal` to subscribe to a `Signal.State` or `Signal.Computed` and receive its value after each change. Updates are coalesced into a single microtask per synchronous batch.
 
-void dispose;
+```typescript
+import { Signal, watchSignal } from "@xmachines/play-signals";
+
+const count = new Signal.State(0);
+
+const cleanup = watchSignal(count, (value) => {
+	console.log("count changed:", value);
+});
+
+count.set(1); // → logs "count changed: 1" (via microtask)
+count.set(2); // coalesced with any rapid synchronous changes
+count.set(3); // → logs "count changed: 3" once
+
+// Stop watching
+cleanup();
 ```
 
-### `watchSignal()` helper
+The returned cleanup function is idempotent — calling it multiple times is safe and will not throw.
+
+### `Signal.subtle.Watcher` — low-level multi-signal observation
 
-For the common case of subscribing to one signal with deterministic cleanup, use `watchSignal()`:
+For advanced use cases such as framework integrations, the full `Signal.subtle.Watcher` API is available:
 
 ```typescript
-import { watchSignal } from "@xmachines/play-signals";
+import { Signal } from "@xmachines/play-signals";
 
-const stopWatching = watchSignal(actor.currentRoute, (route) => {
-	console.log("Route changed:", route);
+const count = new Signal.State(0);
+const doubled = new Signal.Computed(() => count.get() * 2);
+
+const watcher = new Signal.subtle.Watcher(() => {
+	queueMicrotask(() => {
+		const pending = watcher.getPending();
+		console.log("signals changed:", pending.length);
+		watcher.watch(...pending); // re-arm for future changes
+	});
 });
 
-stopWatching();
+watcher.watch(count);
+watcher.watch(doubled);
+
+count.set(5); // schedules microtask notification
 ```
 
-`watchSignal()` is memory-safe:
+### Custom equality
 
-- Calling the returned cleanup before a pending microtask fires will **not** invoke the callback — a `disposed` flag prevents use-after-free when components unmount with in-flight updates.
-- Rapid synchronous signal changes coalesce to **one** microtask (`needsEnqueue` guard) — the callback receives the latest value only.
-- Calling the cleanup multiple times is idempotent (no throw).
+Both `Signal.State` and `Signal.Computed` accept an `equals` option to control when dependents are notified:
 
-`watchSignal()` preserves the same canonical watcher lifecycle described below. It is an optional helper for adapter and renderer code; raw `Signal` APIs remain the base substrate.
+```typescript
+import { Signal } from "@xmachines/play-signals";
+import type { SignalOptions } from "@xmachines/play-signals";
 
-## Canonical Watcher Lifecycle
+const options: SignalOptions<{ name: string; age: number }> = {
+	equals: (a, b) => a.name === b.name && a.age === b.age,
+};
 
-Use one lifecycle pattern everywhere (React, Vue, Solid, router bridges, helper wrappers):
+const person = new Signal.State({ name: "Alice", age: 30 }, options);
+// Setting structurally identical value will not notify dependents
+person.set({ name: "Alice", age: 30 });
+```
 
-1. `notify` callback runs.
-2. Schedule work with `queueMicrotask`.
-3. Drain `watcher.getPending()`.
-4. Perform reads/effects.
-5. Re-arm watcher with `watch()` or `watch(...signals)`.
+## API Summary
 
-Watcher notifications are one-shot. If you do not re-arm, you will miss future updates.
+| Export                         | Kind      | Description                                                                                            |
+| ------------------------------ | --------- | ------------------------------------------------------------------------------------------------------ |
+| `Signal`                       | namespace | Full TC39 Signals namespace (`State`, `Computed`, `subtle.Watcher`) re-exported from `signal-polyfill` |
+| `watchSignal(signal, onValue)` | function  | Memory-safe subscription helper; returns a cleanup function                                            |
+| `SignalState<T>`               | interface | Shape of `Signal.State<T>` (`.get()`, `.set()`)                                                        |
+| `SignalComputed<T>`            | interface | Shape of `Signal.Computed<T>` (`.get()`)                                                               |
+| `SignalWatcher`                | interface | Shape of `Signal.subtle.Watcher` (`.watch()`, `.unwatch()`, `.getPending()`)                           |
+| `SignalOptions<T>`             | interface | Options bag for `Signal.State` constructor (`equals?`)                                                 |
+| `ComputedOptions<T>`           | interface | Options bag for `Signal.Computed` constructor (`equals?`)                                              |
+| `WatcherNotify`                | type      | Callback signature for `Signal.subtle.Watcher` notify function                                         |
 
-## Cleanup Contract
+## Testing
 
-Always dispose explicitly. Do not rely on GC-only cleanup guidance.
+Run tests for this package in isolation:
 
-- If you called `watch(...)`, call `unwatch(...)` in teardown.
-- Framework lifecycles (`useEffect` cleanup, `onUnmounted`, `onCleanup`) must unwatch.
-- Bridge lifecycles (`disconnect`, `dispose`) must unwatch and unsubscribe.
+```bash
+# From this package directory
+npm test
 
-## API Surface
+# Watch mode
+npm test -- --watch
 
-- `Signal.State<T>`: writable signal state (`get`, `set`)
-- `Signal.Computed<T>`: lazy memoized derivations
-- `Signal.subtle.Watcher`: low-level watcher (`watch`, `unwatch`, `getPending`)
-- `watchSignal(signal, onValue)`: lifecycle-safe single-signal subscription helper
+# With coverage (lines ≥ 90 %, functions ≥ 90 %, branches ≥ 85 %, statements ≥ 90 %)
+npm run test:coverage
+```
 
-## Architecture Notes
+From the monorepo root:
 
-- **Signal-Only Reactivity (INV-05):** Signals are the reactive substrate.
-- **Passive Infrastructure (INV-04):** Adapters and frameworks only observe/forward.
-- **Actor Authority (INV-01):** Business validity and transitions stay in actors.
-- **Event-only mutation path:** Signals are not a business mutation channel.
+```bash
+npm test -w @xmachines/play-signals
+```
 
-## Resources
+## Requirements
 
-- [TC39 Signals Proposal](https://github.com/tc39/proposal-signals)
-- [signal-polyfill](https://github.com/proposal-signals/signal-polyfill)
-- [Play RFC](../docs/rfc/play.md)
+- **Node.js** `>= 22.0.0`
+- **TypeScript** `5.7+` (for consumers using TypeScript)
 
 ## License
 
-Copyright (c) 2016 [Mikael Karon](mailto:mikael@karon.se). All rights reserved.
-
-This work is licensed under the terms of the MIT license.  
-For a copy, see <https://opensource.org/licenses/MIT>.
+MIT — see [LICENSE](LICENSE).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xmachines/play-signals",
-  "version": "1.0.0-beta.45",
+  "version": "1.0.0-beta.47",
   "private": false,
   "description": "TC39 Signals polyfill for XMachines - Fine-grained reactive state primitives",
   "keywords": [
@@ -51,7 +51,7 @@
   },
   "devDependencies": {
     "@types/node": "^25.6.0",
-    "@xmachines/shared": "1.0.0-beta.45",
+    "@xmachines/shared": "1.0.0-beta.47",
     "oxfmt": "^0.45.0",
     "oxlint": "^1.60.0",
     "vitest": "^4.1.4"