@xmachines/play-signals 2.2.0 → 4.0.0

package/README.md

@@ -2,7 +2,7 @@
 
 TC39 Signals polyfill for XMachines. It gives the Play Architecture fine-grained reactive state primitives. The primitives propagate state without a glitch and without a subscription.
 
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Version](https://img.shields.io/badge/version-2.2.0-blue)](https://www.npmjs.com/package/@xmachines/play-signals)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Version](https://img.shields.io/badge/version-4.0.0-blue)](https://www.npmjs.com/package/@xmachines/play-signals)
 
 ## Installation
 
@@ -115,39 +115,18 @@ person.set({ name: "Alice", age: 30 });
 | Export                         | Kind      | Description                                                                                            |
 | ------------------------------ | --------- | ------------------------------------------------------------------------------------------------------ |
 | `Signal`                       | namespace | Full TC39 Signals namespace (`State`, `Computed`, `subtle.Watcher`) re-exported from `signal-polyfill` |
-| `watchSignal(signal, onValue)` | function  | The memory-safe subscription helper. It returns a cleanup function                                     |
+| `watchSignal(signal, onValue)` | function  | The memory-safe subscription helper. It returns a `Cleanup`                                            |
 | `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 | The options object for the `Signal.State` constructor (`equals?`)                                      |
 | `ComputedOptions<T>`           | interface | The options object for the `Signal.Computed` constructor (`equals?`)                                   |
 | `WatcherNotify`                | type      | The callback signature of the `Signal.subtle.Watcher` notify function                                  |
-
-## Testing
-
-Run tests for this package in isolation:
-
-```bash
-# From this package directory
-pnpm test
-
-# Watch mode
-pnpm test -- --watch
-```
-
-From the monorepo root:
-
-```bash
-# Run tests for this package
-pnpm --filter @xmachines/play-signals test
-
-# Run with coverage (lines ≥ 90 %, functions ≥ 90 %, branches ≥ 85 %, statements ≥ 90 %)
-pnpm run test:coverage
-```
+| `Cleanup`                      | type      | The release that `watchSignal` returns, re-exported from `@xmachines/play`                             |
 
 ## Requirements
 
-- **Node.js** `>= 22.0.0`
+- **Node.js** `>= 24.0.0`
 - **TypeScript** `5.7+` (for a consumer that uses TypeScript)
 
 ## License

package/dist/index.d.ts

@@ -52,4 +52,5 @@
 export { Signal } from "signal-polyfill";
 export { watchSignal } from "./watch-signal.js";
 export type { SignalState, SignalComputed, SignalWatcher, SignalOptions, ComputedOptions, WatcherNotify, } from "./types.js";
+export { type Cleanup } from "@xmachines/play";
 //# 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":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AAGH,OAAO,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AACzC,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAGhD,YAAY,EACX,WAAW,EACX,cAAc,EACd,aAAa,EACb,aAAa,EACb,eAAe,EACf,aAAa,GACb,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AAGH,OAAO,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AACzC,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAGhD,YAAY,EACX,WAAW,EACX,cAAc,EACd,aAAa,EACb,aAAa,EACb,eAAe,EACf,aAAa,GACb,MAAM,YAAY,CAAC;AAKpB,OAAO,EAAE,KAAK,OAAO,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/index.js

@@ -52,4 +52,9 @@
 // Re-export the complete Signal namespace of the official polyfill
 export { Signal } from "signal-polyfill";
 export { watchSignal } from "./watch-signal.js";
+// The release protocol of @xmachines/play. This package's own published `.d.ts` names
+// exactly these, so a consumer reads them from here and needs no second manifest
+// entry. It names `asCleanup` nowhere: a consumer of this package RECEIVES a
+// release, and builds one only with @xmachines/play itself.
+export {} from "@xmachines/play";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AAEH,mEAAmE;AACnE,OAAO,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AACzC,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AAEH,mEAAmE;AACnE,OAAO,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AACzC,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAWhD,sFAAsF;AACtF,iFAAiF;AACjF,6EAA6E;AAC7E,4DAA4D;AAC5D,OAAO,EAAgB,MAAM,iBAAiB,CAAC"}

package/dist/watch-signal.d.ts

@@ -1,3 +1,4 @@
+import { type Cleanup } from "@xmachines/play";
 import { Signal } from "signal-polyfill";
 /**
  * Subscribes to one signal, with the canonical one-shot watcher lifecycle.
@@ -12,10 +13,33 @@ import { Signal } from "signal-polyfill";
  *   once when the cleanup runs before the microtask fires.
  * - The `needsEnqueue` guard removes the duplicates of rapid synchronous signal
  *   changes: one batch of synchronous changes queues one microtask only.
+ * - The watcher arms again BEFORE the callback: a callback that THROWS keeps the watch, a
+ *   callback that RELEASES the watch leaves no watcher attached to the signal, and a
+ *   callback that WRITES the signal reaches the caller with the value that it wrote.
+ * - The watcher arms with NO argument: `watch(signal)` records the edge a second time on
+ *   every emission, so the edge list of the watcher and the consumer list of the signal
+ *   grow by one for each change, for the life of the watch.
+ *
+ * A CAUTION for a callback that writes the signal that it watches: the write reaches the
+ * callback, so a callback that writes a NEW value on every call runs again for ever, and
+ * the microtask queue drains never. That is the loop of the caller, and this function
+ * bounds it not — a bound here would drop the write of a caller that repairs its state
+ * one time, which is the case that the order above exists to serve. A caller that repairs
+ * from a failure must repair to a state that succeeds, or it must stop after one attempt.
+ * A write of the SAME value ends the sequence by itself, because a signal notifies for a
+ * value that it holds already never.
+ *
+ * The return is a {@link Cleanup}: a function, and a `Disposable`. A caller that keeps
+ * the release in a field and runs it from a teardown keeps that code. A caller inside one
+ * scope writes `using` and writes no teardown:
+ *
+ * ```ts
+ * using stop = watchSignal(count, render);
+ * ```
  *
  * @param signal - The `Signal.State` or `Signal.Computed` to subscribe to.
  * @param onValue - The watcher calls it with the current signal value after each change.
- * @returns The cleanup function. It removes the watcher.
+ * @returns The release. It removes the watcher.
  */
-export declare function watchSignal<T>(signal: Signal.State<T> | Signal.Computed<T>, onValue: (value: T) => void): () => void;
+export declare function watchSignal<T>(signal: Signal.State<T> | Signal.Computed<T>, onValue: (value: T) => void): Cleanup;
 //# sourceMappingURL=watch-signal.d.ts.map

package/dist/watch-signal.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"watch-signal.d.ts","sourceRoot":"","sources":["../src/watch-signal.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAEzC;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAC5B,MAAM,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,EAC5C,OAAO,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,GACzB,MAAM,IAAI,CA0BZ"}
+{"version":3,"file":"watch-signal.d.ts","sourceRoot":"","sources":["../src/watch-signal.ts"],"names":[],"mappings":"AAAA,OAAO,EAAa,KAAK,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAC1D,OAAO,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAEzC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAC5B,MAAM,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,EAC5C,OAAO,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,GACzB,OAAO,CAqDT"}

package/dist/watch-signal.js

@@ -1,3 +1,4 @@
+import { asCleanup } from "@xmachines/play";
 import { Signal } from "signal-polyfill";
 /**
  * Subscribes to one signal, with the canonical one-shot watcher lifecycle.
@@ -12,10 +13,33 @@ import { Signal } from "signal-polyfill";
  *   once when the cleanup runs before the microtask fires.
  * - The `needsEnqueue` guard removes the duplicates of rapid synchronous signal
  *   changes: one batch of synchronous changes queues one microtask only.
+ * - The watcher arms again BEFORE the callback: a callback that THROWS keeps the watch, a
+ *   callback that RELEASES the watch leaves no watcher attached to the signal, and a
+ *   callback that WRITES the signal reaches the caller with the value that it wrote.
+ * - The watcher arms with NO argument: `watch(signal)` records the edge a second time on
+ *   every emission, so the edge list of the watcher and the consumer list of the signal
+ *   grow by one for each change, for the life of the watch.
+ *
+ * A CAUTION for a callback that writes the signal that it watches: the write reaches the
+ * callback, so a callback that writes a NEW value on every call runs again for ever, and
+ * the microtask queue drains never. That is the loop of the caller, and this function
+ * bounds it not — a bound here would drop the write of a caller that repairs its state
+ * one time, which is the case that the order above exists to serve. A caller that repairs
+ * from a failure must repair to a state that succeeds, or it must stop after one attempt.
+ * A write of the SAME value ends the sequence by itself, because a signal notifies for a
+ * value that it holds already never.
+ *
+ * The return is a {@link Cleanup}: a function, and a `Disposable`. A caller that keeps
+ * the release in a field and runs it from a teardown keeps that code. A caller inside one
+ * scope writes `using` and writes no teardown:
+ *
+ * ```ts
+ * using stop = watchSignal(count, render);
+ * ```
  *
  * @param signal - The `Signal.State` or `Signal.Computed` to subscribe to.
  * @param onValue - The watcher calls it with the current signal value after each change.
- * @returns The cleanup function. It removes the watcher.
+ * @returns The release. It removes the watcher.
  */
 export function watchSignal(signal, onValue) {
     let disposed = false;
@@ -29,19 +53,46 @@ export function watchSignal(signal, onValue) {
                 return;
             needsEnqueue = true;
             watcher.getPending();
+            // Arm the watcher BEFORE the callback, and not after it. Three cases need this
+            // order, and no case needs the other one.
+            //
+            // A callback that WRITES the signal notifies the watcher on that write — a
+            // renderer that gives its host an error handler, and the host repairs the actor
+            // from that handler. The watcher must accept the notification at that moment. A
+            // line after the callback arms it too late: the write finds the watcher still
+            // notified, the polyfill drops the notification, and the line then clears the
+            // flag for a change that reaches nobody. Measured: a callback that reads 1 and
+            // writes 2 reads 3 next, and the value 2 reaches the caller never.
+            //
+            // A callback that THROWS keeps the watch, because this line ran already. Before
+            // it, such a callback left the watcher attached to the signal and never armed:
+            // no later change reached the callback, the caller followed the signal no more,
+            // in silence and for the life of the signal.
+            //
+            // A callback that RELEASES the watch from inside itself leaves no watcher on the
+            // signal: the release detaches the edge, and this line adds none.
+            //
+            // NO argument. `watch()` with no signal resets the notified state alone, which is
+            // what this line needs: the edge to the signal stands from the `watch(signal)`
+            // below. `watch(signal)` records the edge a SECOND time — the watcher appends the
+            // producer at the next free index, and it resets that index never — so the edge
+            // list of the watcher and the live-consumer list of the signal grow by one for
+            // EVERY emission. Measured with the polyfill: 50 emissions leave 51 entries in
+            // each list. A view that streams therefore leaks one entry for each chunk, and
+            // each later change walks the whole list.
+            watcher.watch();
             onValue(signal.get());
-            watcher.watch(signal);
         });
     });
     watcher.watch(signal);
-    return () => {
+    return asCleanup(() => {
         disposed = true;
         try {
             watcher.unwatch(signal);
         }
         catch {
-            // Ignore an error of a detached watcher. The cleanup therefore stays idempotent.
+            // Ignore an error of a detached watcher. The release therefore stays idempotent.
         }
-    };
+    });
 }
 //# sourceMappingURL=watch-signal.js.map

package/dist/watch-signal.js.map

@@ -1 +1 @@
-{"version":3,"file":"watch-signal.js","sourceRoot":"","sources":["../src/watch-signal.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAEzC;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,WAAW,CAC1B,MAA4C,EAC5C,OAA2B;IAE3B,IAAI,QAAQ,GAAG,KAAK,CAAC;IACrB,IAAI,YAAY,GAAG,IAAI,CAAC;IAExB,MAAM,OAAO,GAAG,IAAI,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,GAAG,EAAE;QAC9C,IAAI,QAAQ,IAAI,CAAC,YAAY;YAAE,OAAO;QACtC,YAAY,GAAG,KAAK,CAAC;QACrB,cAAc,CAAC,GAAG,EAAE;YACnB,IAAI,QAAQ;gBAAE,OAAO;YACrB,YAAY,GAAG,IAAI,CAAC;YACpB,OAAO,CAAC,UAAU,EAAE,CAAC;YACrB,OAAO,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC;YACtB,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;QACvB,CAAC,CAAC,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IAEtB,OAAO,GAAG,EAAE;QACX,QAAQ,GAAG,IAAI,CAAC;QAChB,IAAI,CAAC;YACJ,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QACzB,CAAC;QAAC,MAAM,CAAC;YACR,iFAAiF;QAClF,CAAC;IACF,CAAC,CAAC;AACH,CAAC"}
+{"version":3,"file":"watch-signal.js","sourceRoot":"","sources":["../src/watch-signal.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAgB,MAAM,iBAAiB,CAAC;AAC1D,OAAO,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAEzC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,MAAM,UAAU,WAAW,CAC1B,MAA4C,EAC5C,OAA2B;IAE3B,IAAI,QAAQ,GAAG,KAAK,CAAC;IACrB,IAAI,YAAY,GAAG,IAAI,CAAC;IAExB,MAAM,OAAO,GAAG,IAAI,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,GAAG,EAAE;QAC9C,IAAI,QAAQ,IAAI,CAAC,YAAY;YAAE,OAAO;QACtC,YAAY,GAAG,KAAK,CAAC;QACrB,cAAc,CAAC,GAAG,EAAE;YACnB,IAAI,QAAQ;gBAAE,OAAO;YACrB,YAAY,GAAG,IAAI,CAAC;YACpB,OAAO,CAAC,UAAU,EAAE,CAAC;YACrB,+EAA+E;YAC/E,0CAA0C;YAC1C,EAAE;YACF,2EAA2E;YAC3E,gFAAgF;YAChF,gFAAgF;YAChF,8EAA8E;YAC9E,8EAA8E;YAC9E,+EAA+E;YAC/E,mEAAmE;YACnE,EAAE;YACF,gFAAgF;YAChF,+EAA+E;YAC/E,gFAAgF;YAChF,6CAA6C;YAC7C,EAAE;YACF,iFAAiF;YACjF,kEAAkE;YAClE,EAAE;YACF,kFAAkF;YAClF,+EAA+E;YAC/E,kFAAkF;YAClF,gFAAgF;YAChF,+EAA+E;YAC/E,+EAA+E;YAC/E,+EAA+E;YAC/E,0CAA0C;YAC1C,OAAO,CAAC,KAAK,EAAE,CAAC;YAChB,OAAO,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC;QACvB,CAAC,CAAC,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IAEtB,OAAO,SAAS,CAAC,GAAG,EAAE;QACrB,QAAQ,GAAG,IAAI,CAAC;QAChB,IAAI,CAAC;YACJ,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QACzB,CAAC;QAAC,MAAM,CAAC;YACR,iFAAiF;QAClF,CAAC;IACF,CAAC,CAAC,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xmachines/play-signals",
-  "version": "2.2.0",
+  "version": "4.0.0",
   "private": false,
   "description": "TC39 Signals polyfill for XMachines - Fine-grained reactive state primitives",
   "keywords": [
@@ -43,6 +43,7 @@
     "test": "vitest",
     "test:coverage": "vitest run --coverage",
     "lint": "oxlint .",
+    "lint:security": "node ../../scripts/semgrep-scan.mjs",
     "lint:fix": "oxlint --fix .",
     "format": "oxfmt .",
     "format:check": "oxfmt --check ."
@@ -51,15 +52,19 @@
     "signal-polyfill": "^0.2.2"
   },
   "devDependencies": {
-    "@testing-library/jest-dom": "^6.9.1",
-    "@types/node": "^26.2.0",
-    "@vitest/browser-playwright": "^4.1.11",
-    "oxfmt": "^0.64.0",
-    "oxlint": "^1.79.0",
-    "vite": "^8.0.10",
-    "vitest": "^4.1.11"
+    "@testing-library/jest-dom": "^7.0.1",
+    "@types/node": "^26.6.2",
+    "@vitest/browser-playwright": "^5.0.1",
+    "@xmachines/play": "4.0.0",
+    "oxfmt": "^0.68.0",
+    "oxlint": "^1.83.0",
+    "vite": "^8.3.0",
+    "vitest": "^5.0.1"
+  },
+  "peerDependencies": {
+    "@xmachines/play": "4.0.0"
   },
   "engines": {
-    "node": ">=22.0.0"
+    "node": ">=24.0.0"
   }
 }