@xmachines/docs 5.0.2 → 6.0.0

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.2/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-dom-router/type-aliases/Cleanup.md

@@ -1,38 +0,0 @@
-[API](../../../README.md) / [@xmachines/play-dom-router](../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.2/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/variables/DISPOSE.md

@@ -1,34 +0,0 @@
-[API](../../../README.md) / [@xmachines/play-dom-router](../README.md) / DISPOSE
-
-# Variable: DISPOSE
-
-```ts
-const DISPOSE: DisposeKey;
-```
-
-Defined in: [play/src/disposable.ts:94](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.2/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-pattern/interfaces/PatternCache.md

@@ -1,65 +0,0 @@
-[API](../../../README.md) / [@xmachines/play-pattern](../README.md) / PatternCache
-
-# Interface: PatternCache\<V\>
-
-Defined in: [cache.ts:53](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.2/packages/play-pattern/src/cache.ts#L53)
-
-What this package needs from a cache: a read and a write, both by a string key.
-
-The contract is this small on purpose. A `Map` satisfies it, and so does an LRU of any
-library — a caller that wants a time to live or an eviction callback brings the module
-that has one, and this package needs to know nothing about it.
-
-A cache may forget an entry at any time, and it may forget none. Both are correct: the
-parser runs again for an entry that is absent.
-
-## Type Parameters
-
-| Type Parameter |
-| -------------- |
-| `V`            |
-
-## Methods
-
-### get()
-
-```ts
-get(key): V | undefined;
-```
-
-Defined in: [cache.ts:55](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.2/packages/play-pattern/src/cache.ts#L55)
-
-Reads one entry, or `undefined` when the cache holds none for the key.
-
-#### Parameters
-
-| Parameter | Type     |
-| --------- | -------- |
-| `key`     | `string` |
-
-#### Returns
-
-`V` \| `undefined`
-
----
-
-### set()
-
-```ts
-set(key, value): void;
-```
-
-Defined in: [cache.ts:57](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.2/packages/play-pattern/src/cache.ts#L57)
-
-Writes one entry.
-
-#### Parameters
-
-| Parameter | Type     |
-| --------- | -------- |
-| `key`     | `string` |
-| `value`   | `V`      |
-
-#### Returns
-
-`void`

package/api/@xmachines/play-router/index/interfaces/PatternCache.md

@@ -1,65 +0,0 @@
-[API](../../../../README.md) / [@xmachines/play-router](../../README.md) / [index](../README.md) / PatternCache
-
-# Interface: PatternCache\<V\>
-
-Defined in: [packages/play-pattern/src/cache.ts:53](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.2/packages/play-pattern/src/cache.ts#L53)
-
-What this package needs from a cache: a read and a write, both by a string key.
-
-The contract is this small on purpose. A `Map` satisfies it, and so does an LRU of any
-library — a caller that wants a time to live or an eviction callback brings the module
-that has one, and this package needs to know nothing about it.
-
-A cache may forget an entry at any time, and it may forget none. Both are correct: the
-parser runs again for an entry that is absent.
-
-## Type Parameters
-
-| Type Parameter |
-| -------------- |
-| `V`            |
-
-## Methods
-
-### get()
-
-```ts
-get(key): V | undefined;
-```
-
-Defined in: [packages/play-pattern/src/cache.ts:55](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.2/packages/play-pattern/src/cache.ts#L55)
-
-Reads one entry, or `undefined` when the cache holds none for the key.
-
-#### Parameters
-
-| Parameter | Type     |
-| --------- | -------- |
-| `key`     | `string` |
-
-#### Returns
-
-`V` \| `undefined`
-
----
-
-### set()
-
-```ts
-set(key, value): void;
-```
-
-Defined in: [packages/play-pattern/src/cache.ts:57](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.2/packages/play-pattern/src/cache.ts#L57)
-
-Writes one entry.
-
-#### Parameters
-
-| Parameter | Type     |
-| --------- | -------- |
-| `key`     | `string` |
-| `value`   | `V`      |
-
-#### Returns
-
-`void`

package/api/@xmachines/play-url/index/interfaces/PatternCache.md

@@ -1,65 +0,0 @@
-[API](../../../../README.md) / [@xmachines/play-url](../../README.md) / [index](../README.md) / PatternCache
-
-# Interface: PatternCache\<V\>
-
-Defined in: [packages/play-pattern/src/cache.ts:53](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.2/packages/play-pattern/src/cache.ts#L53)
-
-What this package needs from a cache: a read and a write, both by a string key.
-
-The contract is this small on purpose. A `Map` satisfies it, and so does an LRU of any
-library — a caller that wants a time to live or an eviction callback brings the module
-that has one, and this package needs to know nothing about it.
-
-A cache may forget an entry at any time, and it may forget none. Both are correct: the
-parser runs again for an entry that is absent.
-
-## Type Parameters
-
-| Type Parameter |
-| -------------- |
-| `V`            |
-
-## Methods
-
-### get()
-
-```ts
-get(key): V | undefined;
-```
-
-Defined in: [packages/play-pattern/src/cache.ts:55](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.2/packages/play-pattern/src/cache.ts#L55)
-
-Reads one entry, or `undefined` when the cache holds none for the key.
-
-#### Parameters
-
-| Parameter | Type     |
-| --------- | -------- |
-| `key`     | `string` |
-
-#### Returns
-
-`V` \| `undefined`
-
----
-
-### set()
-
-```ts
-set(key, value): void;
-```
-
-Defined in: [packages/play-pattern/src/cache.ts:57](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.2/packages/play-pattern/src/cache.ts#L57)
-
-Writes one entry.
-
-#### Parameters
-
-| Parameter | Type     |
-| --------- | -------- |
-| `key`     | `string` |
-| `value`   | `V`      |
-
-#### Returns
-
-`void`

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

@@ -1,34 +0,0 @@
-[API](../../../../README.md) / [@xmachines/play-xstate](../../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.2/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](../../../play/index/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.