@xmachines/docs 2.2.0 → 3.0.0

package/guides/signals.md

@@ -109,6 +109,49 @@ Use [`watchSignal()`](../api/@xmachines/play-signals/functions/watchSignal.md) i
 
 ---
 
+## The release, and `using`
+
+`watchSignal()` returns a `Cleanup` from [`@xmachines/play`](../api/@xmachines/play/README.md): a
+function, and a `Disposable`. One value therefore serves two forms, and the same holds for
+the mount of `@xmachines/play-dom` and for `history.subscribe()` of
+`@xmachines/play-dom-router`.
+
+Keep the explicit call where the release outlives the scope that made it — a field that a
+teardown reads, an entry in a `Set` of releases:
+
+```typescript
+const stop = watchSignal(actor.currentRoute, render);
+onUnmount(() => stop());
+```
+
+Write `using` where the release belongs to one scope. The scope releases it, an exception
+releases it too, and the code carries no teardown:
+
+```typescript
+{
+	using stop = watchSignal(actor.currentRoute, render);
+	render(actor.currentRoute.get());
+	// stop() runs here, and it runs even when render() throws
+}
+```
+
+A scope releases from the last declaration to the first, so a release that depends on an
+earlier one is safe.
+
+Every release here is synchronous, so `Cleanup` is a `Disposable` and not an
+`AsyncDisposable`. That is the permissive choice: a `Disposable` serves `using` AND
+`await using`, while an `AsyncDisposable` raises a TypeError under a plain `using` and
+forces every holder into an async function. `asCleanup` therefore refuses a release that
+returns a value, and a promise above all — a promise handed to it would go on the floor,
+released and unawaitable.
+
+`using` needs Node 24 or a browser with Explicit Resource Management. The publishable
+packages build at `target: "esnext"` and pass the syntax through untouched, so your bundler
+decides how to emit it. The `Cleanup` VALUE needs neither: a runtime without
+`Symbol.dispose` still calls it as a plain function.
+
+---
+
 ## Why not observables (RxJS) or event emitters?
 
 The XMachines architecture chose TC39 Signals over observable libraries and event emitters for three reasons:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xmachines/docs",
-  "version": "2.2.0",
+  "version": "3.0.0",
   "description": "Documentation for XMachines",
   "keywords": [
     "documentation",