@xmachines/docs 5.0.1 → 6.0.0

package/guides/getting-started.md

@@ -151,19 +151,21 @@ All packages are ES modules (`"type": "module"`). Use `.js` extensions in all Ty
 
 #### Step 1: Install the core packages
 
-Every XMachines application needs these four packages plus XState:
+Every XMachines application needs these six packages plus XState:
 
 ```bash
-pnpm add xstate @xmachines/play-xstate @xmachines/play-actor @xmachines/play-atom @xmachines/json-render-core
+pnpm add xstate @xmachines/play-xstate @xmachines/play-actor @xmachines/play-atom @xmachines/play @xmachines/core @xmachines/json-render-core
 ```
 
-| Package                                                             | Role                                                                                                                                                                            |
-| ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `xstate`                                                            | XState v5 state machine engine (peer dependency)                                                                                                                                |
-| [`@xmachines/play-xstate`](../api/@xmachines/play-xstate/README.md) | [`definePlayer()`](../api/@xmachines/play-xstate/index/functions/definePlayer.md), [`PlayerActor`](../api/@xmachines/play-xstate/index/classes/PlayerActor.md), routing helpers |
-| [`@xmachines/play-actor`](../api/@xmachines/play-actor/README.md)   | The actor contract: `PlayActor`, which names no state machine library                                                                                                           |
-| [`@xmachines/play-atom`](../api/@xmachines/play-atom/README.md)     | The atom primitives (`createAtom`, [`watchAtom`](../api/@xmachines/play-atom/functions/watchAtom.md))                                                                           |
-| `@xmachines/json-render-core`                                       | Spec and store types the actor layer builds on — a peer of [`@xmachines/play-actor`](../api/@xmachines/play-actor/README.md), and of every renderer package                     |
+| Package                                                             | Role                                                                                                                                                                                                                                                                       |
+| ------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `xstate`                                                            | XState v5 state machine engine (peer dependency)                                                                                                                                                                                                                           |
+| [`@xmachines/play-xstate`](../api/@xmachines/play-xstate/README.md) | [`definePlayer()`](../api/@xmachines/play-xstate/index/functions/definePlayer.md), [`PlayerActor`](../api/@xmachines/play-xstate/index/classes/PlayerActor.md), routing helpers                                                                                            |
+| [`@xmachines/play-actor`](../api/@xmachines/play-actor/README.md)   | The actor contract: `PlayActor`, which names no state machine library                                                                                                                                                                                                      |
+| [`@xmachines/play-atom`](../api/@xmachines/play-atom/README.md)     | The atom primitives (`createAtom`, [`watchAtom`](../api/@xmachines/play-atom/functions/watchAtom.md))                                                                                                                                                                      |
+| [`@xmachines/play`](../api/@xmachines/play/README.md)               | The protocol: `PlayEvent`, and `PlayError` on its `errors` subpath — a peer of every package that reads it                                                                                                                                                                 |
+| [`@xmachines/core`](../api/@xmachines/core/README.md)               | `BaseError`, the release protocol, and the cache — a peer of [`@xmachines/play-xstate`](../api/@xmachines/play-xstate/README.md), [`@xmachines/play-view`](../api/@xmachines/play-view/README.md), and [`@xmachines/play-router`](../api/@xmachines/play-router/README.md) |
+| `@xmachines/json-render-core`                                       | The spec type that `PlaySpec` extends — a peer of [`@xmachines/play-view`](../api/@xmachines/play-view/README.md), and of every renderer package                                                                                                                           |
 
 #### Step 2: Install a router adapter (pick one)
 
@@ -277,7 +279,7 @@ const stop = watchAtom(actor.state, (snapshot) => {
 
 actor.send({ type: "toggle" }); // the callback runs from a microtask
 
-stop(); // release it, or write `using stop = watchAtom(...)`
+stop(); // release it, or write `using stop = asDisposable(watchAtom(...))`
 ```
 
 Three rules cover every use of them:
@@ -457,12 +459,15 @@ actor.start();
 
 const disconnectRouter = connectRouter({ actor, router, routeMap });
 
-// Cleanup on unload
-window.addEventListener("beforeunload", () => {
+// Call teardown() when the app ends before the page does, for example when the component
+// that holds it unmounts. At the end of the page, do nothing: the browser frees the page.
+// A teardown on `beforeunload` also runs when the page goes into the back/forward cache,
+// and Back then shows a page that does not respond.
+function teardown(): void {
 	disconnectRouter();
 	router.destroy();
 	actor.stop();
-});
+}
 ```
 
 ---
@@ -634,7 +639,8 @@ const registryResult = defineRegistry(catalog, {
 const mount = createPlayUI(registryResult);
 const disconnect = mount(actor, document.getElementById("app")!);
 
-window.addEventListener("beforeunload", () => disconnect());
+// Call disconnect() when the app ends before the page does, for example when the component
+// that holds it unmounts. At the end of the page, do nothing: the browser frees the page.
 ```
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xmachines/docs",
-  "version": "5.0.1",
+  "version": "6.0.0",
   "description": "Documentation for XMachines",
   "keywords": [
     "documentation",
@@ -50,6 +50,7 @@
     "format": "oxfmt .",
     "format:check": "oxfmt --check .",
     "typedoc": "typedoc",
+    "test:generated": "vitest run --config vitest.generated.config.ts",
     "test": "vitest run",
     "clean": "rm -rf coverage node_modules/.vite*"
   },

package/rfc/broker.md

@@ -1,3 +1,7 @@
+---
+status: planned
+---
+
 # RFC: Broker
 
 **Status:** Draft  

package/rfc/browser.md

@@ -1,3 +1,7 @@
+---
+status: planned
+---
+
 # RFC: Browser
 
 **Status:** Draft  

package/rfc/cli.md

@@ -1,3 +1,7 @@
+---
+status: planned
+---
+
 # RFC: CLI
 
 **Status:** Draft  

package/rfc/git.md

@@ -1,3 +1,7 @@
+---
+status: planned
+---
+
 # RFC: Git
 
 **Status:** Draft  

package/rfc/mcp.md

@@ -1,3 +1,7 @@
+---
+status: planned
+---
+
 # RFC: MCP
 
 **Status:** Draft  

package/rfc/node.md

@@ -1,3 +1,7 @@
+---
+status: planned
+---
+
 # RFC: Node
 
 **Status:** Draft  

package/rfc/play.md

@@ -147,7 +147,7 @@ Exports the minimal shared contracts that allow the Logic Engine and Infrastruct
 **Exports:**
 
 - `PlayEvent<TPayload>` — Generic intent event dispatched from Infrastructure to Actor. Any object with `{ readonly type: string }` plus optional typed payload fields.
-- `PlayError` — Structured error base with `scope` and `code` fields for consistent error handling across all `@xmachines/*` packages.
+- `PlayError` — Structured error base with `scope` and `code` fields for consistent error handling across the Play packages. It extends `BaseError` of [`@xmachines/core`](../api/@xmachines/core/README.md).
 
 > **Note:** Routing contracts (`RouterBridge`, `PlayRouteEvent`) live in [`@xmachines/play-router`](../api/@xmachines/play-router/README.md), not here. This keeps the core protocol package dependency-free.
 

package/rfc/rest.md

@@ -1,3 +1,7 @@
+---
+status: planned
+---
+
 # RFC: REST
 
 **Status:** Draft  

package/rfc/run.md

@@ -1,3 +1,7 @@
+---
+status: planned
+---
+
 # RFC: Run
 
 **Status:** Draft  

package/rfc/streams.md

@@ -1,3 +1,7 @@
+---
+status: planned
+---
+
 # RFC: Streams
 
 **Status:** Draft  

package/api/@xmachines/play/index/functions/asCleanup.md

@@ -1,77 +0,0 @@
-[API](../../../../README.md) / [@xmachines/play](../../README.md) / [index](../README.md) / asCleanup
-
-# Function: asCleanup()
-
-```ts
-function asCleanup<R>(release): Cleanup;
-```
-
-Defined in: [packages/play/src/disposable.ts:149](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play/src/disposable.ts#L149)
-
-Makes one release function serve as a [Cleanup](../type-aliases/Cleanup.md).
-
-The function comes back as itself, with [DISPOSE](../variables/DISPOSE.md) added. Nothing wraps it, so
-the identity of the release holds: a caller that compares two releases, or that puts
-one in a `Set`, sees what it saw before this protocol existed.
-
-The release therefore must be idempotent. A scope releases the value one time, but a
-caller that runs the function AND lets the scope end runs it two times. Every release
-of this workspace already accepts that, because a teardown that runs two times is
-older than this protocol.
-
-The release must be synchronous. `Disposable` and not `AsyncDisposable`: a
-`Disposable` serves `using` AND `await using`, because `await using` falls back to
-`Symbol.dispose`, while an `AsyncDisposable` raises a TypeError under a plain `using`
-and forces every holder into an async function. Nothing in this workspace releases
-asynchronously. An `AsyncCleanup` can arrive the day something does.
-
-The `R extends void | undefined` bound is what holds that line. A plain `() => void`
-parameter would ACCEPT `async () => {}`, because TypeScript lets a function that
-returns a value stand where one returning `void` is wanted. The promise would then go
-on the floor: the scope releases, the release looks finished, and the work runs later
-with nobody able to await it. The bound rejects that at the call, and it rejects a
-release that returns any other value as well.
-
-The bound holds where the compiler knows the return type. It cannot hold where the
-caller erased it: `R` infers `any` for a release typed `any`, such as a bare
-`vi.fn()`, and `any` satisfies every constraint. A release declared `() => void` whose
-body is async passes for the same reason — the declaration, and not the body, is what
-the call site sees. Write the release inline, or type it, and the bound applies.
-
-The release lands under [DISPOSE](../variables/DISPOSE.md) and, when the two differ, under the
-`Symbol.dispose` that exists at the CALL. `DISPOSE` resolves when the module evaluates,
-so a polyfill that installs the well-known symbol later would otherwise leave the
-release on the registered key while a downlevelled `using` reads the well-known one.
-Writing both closes that window for every release this function publishes.
-
-## Type Parameters
-
-| Type Parameter                      |
-| ----------------------------------- |
-| `R` _extends_ `void` \| `undefined` |
-
-## Parameters
-
-| Parameter | Type      | Description                                                                                                                                                                                                         |
-| --------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `release` | () => `R` | The release to publish. It must return nothing. The function is changed in place, so pass a function that this release owns: a shared or module-level function becomes a `Disposable` for every other holder of it. |
-
-## Returns
-
-[`Cleanup`](../type-aliases/Cleanup.md)
-
-The same function, now also a `Disposable`.
-
-## Throws
-
-TypeError - When the release is frozen or is otherwise not extensible. The
-protocol adds a property, and a sealed function accepts none.
-
-## Example
-
-```ts
-export function watchAtom<T>(atom: Readable<T>, onValue: (v: T) => void): Cleanup {
-	const subscription = atom.subscribe(() => onValue(atom.get()));
-	return asCleanup(() => subscription.unsubscribe());
-}
-```

package/api/@xmachines/play/index/functions/shallowEqualExcept.md

@@ -1,29 +0,0 @@
-[API](../../../../README.md) / [@xmachines/play](../../README.md) / [index](../README.md) / shallowEqualExcept
-
-# Function: shallowEqualExcept()
-
-```ts
-function shallowEqualExcept(a, b, except?): boolean;
-```
-
-Defined in: [packages/play/src/utils.ts:59](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play/src/utils.ts#L59)
-
-The shallow equality of the own keys, with `Object.is`. It can ignore one key on
-both sides.
-
-This is the one comparison rule behind every decision of the emission dedup: the
-equality of a slice, and also the emit gate of the player, which compares the
-spec fields in `viewSpecsEquivalent` and reuses the composed state in
-`reuseComposedState` of `@xmachines/play-view`.
-
-## Parameters
-
-| Parameter | Type     |
-| --------- | -------- |
-| `a`       | `object` |
-| `b`       | `object` |
-| `except?` | `string` |
-
-## Returns
-
-`boolean`

package/api/@xmachines/play/index/type-aliases/Cleanup.md

@@ -1,38 +0,0 @@
-[API](../../../../README.md) / [@xmachines/play](../../README.md) / [index](../README.md) / Cleanup
-
-# Type Alias: Cleanup
-
-```ts
-type Cleanup = () => void & { [Key in DisposeKey]: () => void };
-```
-
-Defined in: [packages/play/src/disposable.ts:66](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play/src/disposable.ts#L66)
-
-The release of a subscription. A caller runs it, or a scope releases it.
-
-The type is a function AND a `Disposable`, so one value serves both forms. A caller
-that holds 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 at all:
-
-```ts
-// The explicit form. It stays correct.
-const stop = watchAtom(count, render);
-stop();
-
-// The scoped form. The scope releases it, and an exception releases it too.
-{
-	using stop = watchAtom(count, render);
-	render(count.get());
-}
-```
-
-`using` needs Node 24 or a browser with Explicit Resource Management, and it needs
-`"lib": ["ESNext"]` of the consumer. The publishable packages build at
-`target: "esnext"` and pass the syntax through, so the bundler of the consumer decides
-how to emit it. The `Cleanup` VALUE needs neither: a runtime without `Symbol.dispose`
-still calls it as a function, and a consumer that declares a lower `lib` still reads
-the type. See [DisposeKey](DisposeKey.md) for the second half of that.
-
-## See
-
-[Play RFC](../../../../../rfc/play.md)

package/api/@xmachines/play/index/type-aliases/DisposeKey.md

@@ -1,32 +0,0 @@
-[API](../../../../README.md) / [@xmachines/play](../../README.md) / [index](../README.md) / DisposeKey
-
-# Type Alias: DisposeKey
-
-```ts
-type DisposeKey = SymbolConstructor extends object ? Key : never;
-```
-
-Defined in: [packages/play/src/disposable.ts:34](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play/src/disposable.ts#L34)
-
-The dispose key of the ambient library, and `never` where the consumer omits it.
-
-`Symbol.dispose` and the `Disposable` interface arrive with `lib.esnext.disposable`. A
-consumer gets that library from `"lib": ["ESNext"]`, and NOT from `"lib": ["ES2022"]`
-or `["ES2023"]`. A published `.d.ts` that names either one therefore refuses to
-type-check for every consumer of the second kind, and this package cannot ask for the
-library on their behalf: TypeScript copies no `/// <reference lib="..." />` into
-declaration output.
-
-The conditional asks the compiler instead of naming the key. Where the library is
-present the key resolves to `typeof Symbol.dispose`, and [Cleanup](Cleanup.md) is a
-`Disposable` that a `using` declaration accepts. Where the library is absent the key
-resolves to `never`, the mapped type of [Cleanup](Cleanup.md) adds no member, and `Cleanup`
-IS the plain `() => void` that these functions returned before this protocol existed.
-That consumer loses nothing, because `using` is syntax that the same library gates: a
-compiler that cannot name `Symbol.dispose` cannot compile the form either.
-
-The runtime is not involved. [asCleanup](../functions/asCleanup.md) stores the release under [DISPOSE](../variables/DISPOSE.md)
-whatever the consumer declares, so one build serves both.
-
-The type is exported because the published `.d.ts` names it, and a reader who asks why
-[Cleanup](Cleanup.md) carries no dispose member needs to reach the answer.

package/api/@xmachines/play/index/variables/DISPOSE.md

@@ -1,34 +0,0 @@
-[API](../../../../README.md) / [@xmachines/play](../../README.md) / [index](../README.md) / DISPOSE
-
-# Variable: DISPOSE
-
-```ts
-const DISPOSE: DisposeKey;
-```
-
-Defined in: [packages/play/src/disposable.ts:94](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play/src/disposable.ts#L94)
-
-The key that a release is stored under.
-
-`Symbol.dispose` where the runtime has it, and `Symbol.for("Symbol.dispose")` where it
-does not. This is not a convenience — it is the difference between a `using` that
-releases and one that raises.
-
-A bundler that downlevels `using` for a target below Chrome 134 emits a helper that
-reads `object[Symbol.dispose || Symbol.for("Symbol.dispose")]`. A release stored under
-a bare `[Symbol.dispose]` lands on the string key `"undefined"` in that runtime,
-because the well-known symbol is absent and the computed key takes the value
-`undefined`. The helper then looks up the registered symbol, finds nothing, and throws
-`TypeError: Object is not disposable`. Storing under the same fallback closes the gap.
-
-The type assertion states what the fallback IS. `Symbol.for` returns a plain `symbol`,
-TypeScript declares `Symbol.dispose` as a `unique symbol`, and no expression produces
-a `unique symbol` other than the declaration itself.
-
-This binding resolves ONE time, when the module evaluates. [asCleanup](../functions/asCleanup.md) therefore
-reads `Symbol.dispose` again at each call and stores the release under both keys, so a
-polyfill that installs the well-known symbol after this module evaluates still finds
-the release. A class or an object literal that writes `[DISPOSE]()` has no such second
-chance: it carries the key that existed when it was defined. Install an Explicit
-Resource Management polyfill before the first import of `@xmachines/play`, which is the
-ordinary contract of a polyfill.

package/api/@xmachines/play-atom/type-aliases/Cleanup.md

@@ -1,38 +0,0 @@
-[API](../../../README.md) / [@xmachines/play-atom](../README.md) / Cleanup
-
-# Type Alias: Cleanup
-
-```ts
-type Cleanup = () => void & { [Key in DisposeKey]: () => void };
-```
-
-Defined in: [play/src/disposable.ts:66](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play/src/disposable.ts#L66)
-
-The release of a subscription. A caller runs it, or a scope releases it.
-
-The type is a function AND a `Disposable`, so one value serves both forms. A caller
-that holds 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 at all:
-
-```ts
-// The explicit form. It stays correct.
-const stop = watchAtom(count, render);
-stop();
-
-// The scoped form. The scope releases it, and an exception releases it too.
-{
-	using stop = watchAtom(count, render);
-	render(count.get());
-}
-```
-
-`using` needs Node 24 or a browser with Explicit Resource Management, and it needs
-`"lib": ["ESNext"]` of the consumer. The publishable packages build at
-`target: "esnext"` and pass the syntax through, so the bundler of the consumer decides
-how to emit it. The `Cleanup` VALUE needs neither: a runtime without `Symbol.dispose`
-still calls it as a function, and a consumer that declares a lower `lib` still reads
-the type. See [DisposeKey](../../play/index/type-aliases/DisposeKey.md) for the second half of that.
-
-## See
-
-[Play RFC](../../../../rfc/play.md)

package/api/@xmachines/play-dom/functions/asCleanup.md

@@ -1,77 +0,0 @@
-[API](../../../README.md) / [@xmachines/play-dom](../README.md) / asCleanup
-
-# Function: asCleanup()
-
-```ts
-function asCleanup<R>(release): Cleanup;
-```
-
-Defined in: [packages/play/src/disposable.ts:149](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play/src/disposable.ts#L149)
-
-Makes one release function serve as a [Cleanup](../type-aliases/Cleanup.md).
-
-The function comes back as itself, with [DISPOSE](../../play/index/variables/DISPOSE.md) added. Nothing wraps it, so
-the identity of the release holds: a caller that compares two releases, or that puts
-one in a `Set`, sees what it saw before this protocol existed.
-
-The release therefore must be idempotent. A scope releases the value one time, but a
-caller that runs the function AND lets the scope end runs it two times. Every release
-of this workspace already accepts that, because a teardown that runs two times is
-older than this protocol.
-
-The release must be synchronous. `Disposable` and not `AsyncDisposable`: a
-`Disposable` serves `using` AND `await using`, because `await using` falls back to
-`Symbol.dispose`, while an `AsyncDisposable` raises a TypeError under a plain `using`
-and forces every holder into an async function. Nothing in this workspace releases
-asynchronously. An `AsyncCleanup` can arrive the day something does.
-
-The `R extends void | undefined` bound is what holds that line. A plain `() => void`
-parameter would ACCEPT `async () => {}`, because TypeScript lets a function that
-returns a value stand where one returning `void` is wanted. The promise would then go
-on the floor: the scope releases, the release looks finished, and the work runs later
-with nobody able to await it. The bound rejects that at the call, and it rejects a
-release that returns any other value as well.
-
-The bound holds where the compiler knows the return type. It cannot hold where the
-caller erased it: `R` infers `any` for a release typed `any`, such as a bare
-`vi.fn()`, and `any` satisfies every constraint. A release declared `() => void` whose
-body is async passes for the same reason — the declaration, and not the body, is what
-the call site sees. Write the release inline, or type it, and the bound applies.
-
-The release lands under [DISPOSE](../../play/index/variables/DISPOSE.md) and, when the two differ, under the
-`Symbol.dispose` that exists at the CALL. `DISPOSE` resolves when the module evaluates,
-so a polyfill that installs the well-known symbol later would otherwise leave the
-release on the registered key while a downlevelled `using` reads the well-known one.
-Writing both closes that window for every release this function publishes.
-
-## Type Parameters
-
-| Type Parameter                      |
-| ----------------------------------- |
-| `R` _extends_ `void` \| `undefined` |
-
-## Parameters
-
-| Parameter | Type      | Description                                                                                                                                                                                                         |
-| --------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `release` | () => `R` | The release to publish. It must return nothing. The function is changed in place, so pass a function that this release owns: a shared or module-level function becomes a `Disposable` for every other holder of it. |
-
-## Returns
-
-[`Cleanup`](../type-aliases/Cleanup.md)
-
-The same function, now also a `Disposable`.
-
-## Throws
-
-TypeError - When the release is frozen or is otherwise not extensible. The
-protocol adds a property, and a sealed function accepts none.
-
-## Example
-
-```ts
-export function watchAtom<T>(atom: Readable<T>, onValue: (v: T) => void): Cleanup {
-	const subscription = atom.subscribe(() => onValue(atom.get()));
-	return asCleanup(() => subscription.unsubscribe());
-}
-```

package/api/@xmachines/play-dom/type-aliases/Cleanup.md

@@ -1,38 +0,0 @@
-[API](../../../README.md) / [@xmachines/play-dom](../README.md) / Cleanup
-
-# Type Alias: Cleanup
-
-```ts
-type Cleanup = () => void & { [Key in DisposeKey]: () => void };
-```
-
-Defined in: [packages/play/src/disposable.ts:66](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play/src/disposable.ts#L66)
-
-The release of a subscription. A caller runs it, or a scope releases it.
-
-The type is a function AND a `Disposable`, so one value serves both forms. A caller
-that holds 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 at all:
-
-```ts
-// The explicit form. It stays correct.
-const stop = watchAtom(count, render);
-stop();
-
-// The scoped form. The scope releases it, and an exception releases it too.
-{
-	using stop = watchAtom(count, render);
-	render(count.get());
-}
-```
-
-`using` needs Node 24 or a browser with Explicit Resource Management, and it needs
-`"lib": ["ESNext"]` of the consumer. The publishable packages build at
-`target: "esnext"` and pass the syntax through, so the bundler of the consumer decides
-how to emit it. The `Cleanup` VALUE needs neither: a runtime without `Symbol.dispose`
-still calls it as a function, and a consumer that declares a lower `lib` still reads
-the type. See [DisposeKey](../../play/index/type-aliases/DisposeKey.md) for the second half of that.
-
-## See
-
-[Play RFC](../../../../rfc/play.md)

package/api/@xmachines/play-dom-router/functions/asCleanup.md

@@ -1,77 +0,0 @@
-[API](../../../README.md) / [@xmachines/play-dom-router](../README.md) / asCleanup
-
-# Function: asCleanup()
-
-```ts
-function asCleanup<R>(release): Cleanup;
-```
-
-Defined in: [play/src/disposable.ts:149](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play/src/disposable.ts#L149)
-
-Makes one release function serve as a [Cleanup](../type-aliases/Cleanup.md).
-
-The function comes back as itself, with [DISPOSE](../variables/DISPOSE.md) added. Nothing wraps it, so
-the identity of the release holds: a caller that compares two releases, or that puts
-one in a `Set`, sees what it saw before this protocol existed.
-
-The release therefore must be idempotent. A scope releases the value one time, but a
-caller that runs the function AND lets the scope end runs it two times. Every release
-of this workspace already accepts that, because a teardown that runs two times is
-older than this protocol.
-
-The release must be synchronous. `Disposable` and not `AsyncDisposable`: a
-`Disposable` serves `using` AND `await using`, because `await using` falls back to
-`Symbol.dispose`, while an `AsyncDisposable` raises a TypeError under a plain `using`
-and forces every holder into an async function. Nothing in this workspace releases
-asynchronously. An `AsyncCleanup` can arrive the day something does.
-
-The `R extends void | undefined` bound is what holds that line. A plain `() => void`
-parameter would ACCEPT `async () => {}`, because TypeScript lets a function that
-returns a value stand where one returning `void` is wanted. The promise would then go
-on the floor: the scope releases, the release looks finished, and the work runs later
-with nobody able to await it. The bound rejects that at the call, and it rejects a
-release that returns any other value as well.
-
-The bound holds where the compiler knows the return type. It cannot hold where the
-caller erased it: `R` infers `any` for a release typed `any`, such as a bare
-`vi.fn()`, and `any` satisfies every constraint. A release declared `() => void` whose
-body is async passes for the same reason — the declaration, and not the body, is what
-the call site sees. Write the release inline, or type it, and the bound applies.
-
-The release lands under [DISPOSE](../variables/DISPOSE.md) and, when the two differ, under the
-`Symbol.dispose` that exists at the CALL. `DISPOSE` resolves when the module evaluates,
-so a polyfill that installs the well-known symbol later would otherwise leave the
-release on the registered key while a downlevelled `using` reads the well-known one.
-Writing both closes that window for every release this function publishes.
-
-## Type Parameters
-
-| Type Parameter                      |
-| ----------------------------------- |
-| `R` _extends_ `void` \| `undefined` |
-
-## Parameters
-
-| Parameter | Type      | Description                                                                                                                                                                                                         |
-| --------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `release` | () => `R` | The release to publish. It must return nothing. The function is changed in place, so pass a function that this release owns: a shared or module-level function becomes a `Disposable` for every other holder of it. |
-
-## Returns
-
-[`Cleanup`](../type-aliases/Cleanup.md)
-
-The same function, now also a `Disposable`.
-
-## Throws
-
-TypeError - When the release is frozen or is otherwise not extensible. The
-protocol adds a property, and a sealed function accepts none.
-
-## Example
-
-```ts
-export function watchAtom<T>(atom: Readable<T>, onValue: (v: T) => void): Cleanup {
-	const subscription = atom.subscribe(() => onValue(atom.get()));
-	return asCleanup(() => subscription.unsubscribe());
-}
-```