@xmachines/docs 4.0.0 → 5.0.1

package/api/@xmachines/play-signals/README.md

@@ -1,209 +0,0 @@
-[API](../../README.md) / @xmachines/play-signals
-
-# @xmachines/play-signals
-
-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-4.0.0-blue)](https://www.npmjs.com/package/@xmachines/play-signals)
-
-## Installation
-
-```bash
-pnpm add @xmachines/play-signals
-```
-
-## Overview
-
-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 complete `Signal` namespace, and it adds the memory-safe `watchSignal` utility. The wrapper keeps the rest of the code away from a Stage 1 API that can still change.
-
-**Import every signal in the XMachines ecosystem from this package**, not from `signal-polyfill`. One import point keeps each polyfill update and each API change 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";
-
-const count = new Signal.State(0);
-const doubled = new Signal.Computed(() => count.get() * 2);
-
-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)
-```
-
-A computation tracks each signal that it reads. A dynamic branch is safe: the computation keeps only the signals of the _current_ execution path as its dependencies.
-
-### `watchSignal` — memory-safe one-shot effect
-
-Use `watchSignal` to subscribe to a `Signal.State` or to a `Signal.Computed`. The callback receives the value after each change. `watchSignal` groups the updates of one synchronous batch into a single microtask.
-
-```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();
-```
-
-The cleanup function is idempotent. A second call is safe, and it does not throw.
-
-### `Signal.subtle.Watcher` — low-level multi-signal observation
-
-Advanced code, such as a framework integration, can use the complete `Signal.subtle.Watcher` API:
-
-```typescript
-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();
-		console.log("signals changed:", pending.length);
-		watcher.watch(...pending); // re-arm for future changes
-	});
-});
-
-watcher.watch(count);
-watcher.watch(doubled);
-
-count.set(5); // schedules microtask notification
-```
-
-### Custom equality
-
-Both `Signal.State` and `Signal.Computed` accept an `equals` option. The option controls when a signal notifies its dependents:
-
-```typescript
-import { Signal } from "@xmachines/play-signals";
-import type { SignalOptions } from "@xmachines/play-signals";
-
-const options: SignalOptions<{ name: string; age: number }> = {
-	equals: (a, b) => a.name === b.name && a.age === b.age,
-};
-
-const person = new Signal.State({ name: "Alice", age: 30 }, options);
-// A structurally identical value does not notify the dependents
-person.set({ name: "Alice", age: 30 });
-```
-
-## API Summary
-
-| 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`                                            |
-| `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                                  |
-| `Cleanup`                      | type      | The release that `watchSignal` returns, re-exported from `@xmachines/play`                             |
-
-## Requirements
-
-- **Node.js** `>= 24.0.0`
-- **TypeScript** `5.7+` (for a consumer that uses TypeScript)
-
-## License
-
-MIT — see [LICENSE](LICENSE).
-
-The TC39 Signals polyfill of the XMachines Play Architecture
-
-This package gives you the fine-grained reactive state primitives of the TC39
-Signals proposal (Stage 1). It keeps the TC39 polyfill in one place, and it
-therefore protects the code from a change of the Stage 1 API.
-
-**Architectural context:** the package implements **Signal-Only Reactivity
-(INV-05)**. It gives the reactive primitives that carry the communication from
-the Actor to the infrastructure, without a subscription and without an event
-emitter. Every propagation of state in the Play Architecture uses a TC39 Signal,
-which tracks each dependency and updates without a glitch.
-
-## Example
-
-The basic use of a signal
-
-```typescript
-import { Signal } from "@xmachines/play-signals";
-
-// Create a state signal
-const count = new Signal.State(0);
-
-// Create a computed signal
-const doubled = new Signal.Computed(() => count.get() * 2);
-
-// Observe the changes
-const watcher = new Signal.subtle.Watcher(() => {
-	console.log("Count:", count.get(), "Doubled:", doubled.get());
-});
-watcher.watch(count);
-
-count.set(5); // Logs: Count: 5 Doubled: 10
-```
-
-## See
-
-- [Play RFC](../../../rfc/play.md) - invariant INV-05
-- [TC39 Signals Proposal](https://github.com/tc39/proposal-signals)
-
-## Remarks
-
-**Stage 1 status:** TC39 Signals is at Stage 1 in the TC39 process now. This
-package uses the official `signal-polyfill` reference implementation. The code
-therefore stays separate from an API that can change while the proposal
-develops. Import every signal through this package, and the separation stays
-complete.
-
-**The reason for the separation:** this dedicated package re-exports the
-polyfill. Therefore one place holds each new polyfill version and each change of
-the API, and no consuming package changes. This architectural decision protects
-the code from a change of the Stage 1 API.
-
-## Namespaces
-
-- [Signal](namespaces/Signal/README.md)
-
-## Interfaces
-
-- [ComputedOptions](interfaces/ComputedOptions.md)
-- [SignalComputed](interfaces/SignalComputed.md)
-- [SignalOptions](interfaces/SignalOptions.md)
-- [SignalState](interfaces/SignalState.md)
-- [SignalWatcher](interfaces/SignalWatcher.md)
-
-## Type Aliases
-
-- [Cleanup](type-aliases/Cleanup.md)
-- [WatcherNotify](type-aliases/WatcherNotify.md)
-
-## Functions
-
-- [watchSignal](functions/watchSignal.md)

package/api/@xmachines/play-signals/functions/watchSignal.md

@@ -1,65 +0,0 @@
-[API](../../../README.md) / [@xmachines/play-signals](../README.md) / watchSignal
-
-# Function: watchSignal()
-
-```ts
-function watchSignal<T>(signal, onValue): Cleanup;
-```
-
-Defined in: [packages/play-signals/src/watch-signal.ts:45](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-signals/src/watch-signal.ts#L45)
-
-Subscribes to one signal, with the canonical one-shot watcher lifecycle.
-
-The callback runs from a microtask in the queue, after the watcher drains the
-notifications that wait. The watcher then arms itself again, so that it misses no
-later update. The cleanup function is idempotent, because it accepts a watcher
-that is detached already.
-
-**Memory safety (Phase 29):**
-
-- The `disposed` flag stops a callback after the cleanup: the microtask returns at
-  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 [Cleanup](../type-aliases/Cleanup.md): 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);
-```
-
-## Type Parameters
-
-| Type Parameter |
-| -------------- |
-| `T`            |
-
-## Parameters
-
-| Parameter | Type                                                                                                                        | Description                                                           |
-| --------- | --------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
-| `signal`  | \| [`State`](../namespaces/Signal/classes/State.md)\<`T`\> \| [`Computed`](../namespaces/Signal/classes/Computed.md)\<`T`\> | The `Signal.State` or `Signal.Computed` to subscribe to.              |
-| `onValue` | (`value`) => `void`                                                                                                         | The watcher calls it with the current signal value after each change. |
-
-## Returns
-
-[`Cleanup`](../type-aliases/Cleanup.md)
-
-The release. It removes the watcher.

package/api/@xmachines/play-signals/interfaces/ComputedOptions.md

@@ -1,36 +0,0 @@
-[API](../../../README.md) / [@xmachines/play-signals](../README.md) / ComputedOptions
-
-# Interface: ComputedOptions\<T\>
-
-Defined in: [packages/play-signals/src/types.ts:85](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-signals/src/types.ts#L85)
-
-The options of a Signal.Computed
-
-## Param
-
-**equals**
-
-The optional equality function of your own, for the memoization
-
-## Example
-
-```typescript
-import { Signal } from "@xmachines/play-signals";
-import type { ComputedOptions } from "@xmachines/play-signals";
-
-const options: ComputedOptions<string> = {
-	equals: (a, b) => a.toLowerCase() === b.toLowerCase(),
-};
-```
-
-## Type Parameters
-
-| Type Parameter |
-| -------------- |
-| `T`            |
-
-## Properties
-
-| Property                               | Type                    | Description                                            | Defined in                                                                                                                               |
-| -------------------------------------- | ----------------------- | ------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-equals"></a> `equals?` | (`a`, `b`) => `boolean` | The equality function of your own, for the memoization | [packages/play-signals/src/types.ts:89](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-signals/src/types.ts#L89) |

package/api/@xmachines/play-signals/interfaces/SignalComputed.md

@@ -1,49 +0,0 @@
-[API](../../../README.md) / [@xmachines/play-signals](../README.md) / SignalComputed
-
-# Interface: SignalComputed\<T\>
-
-Defined in: [packages/play-signals/src/types.ts:112](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-signals/src/types.ts#L112)
-
-The computed signal. It evaluates late, and it memoizes the result
-
-Signal.Computed tracks each dependency when it runs its callback. It memoizes the
-result, and it runs the callback again only after a dependency changes. It
-therefore tracks each dependency for you, and you manage no subscription.
-
-## Example
-
-```typescript
-import { Signal } from "@xmachines/play-signals";
-
-const count = new Signal.State(0);
-const doubled = new Signal.Computed(() => count.get() * 2);
-
-console.log(doubled.get()); // 0
-count.set(5);
-console.log(doubled.get()); // 10 (the signal computed it again)
-console.log(doubled.get()); // 10 (from the memory, with no new computation)
-```
-
-## Type Parameters
-
-| Type Parameter |
-| -------------- |
-| `T`            |
-
-## Methods
-
-### get()
-
-```ts
-get(): T;
-```
-
-Defined in: [packages/play-signals/src/types.ts:118](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-signals/src/types.ts#L118)
-
-Reads the computed value. It computes the value again only after a dependency changed
-
-#### Returns
-
-`T`
-
-The value from the current dependencies

package/api/@xmachines/play-signals/interfaces/SignalOptions.md

@@ -1,37 +0,0 @@
-[API](../../../README.md) / [@xmachines/play-signals](../README.md) / SignalOptions
-
-# Interface: SignalOptions\<T\>
-
-Defined in: [packages/play-signals/src/types.ts:27](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-signals/src/types.ts#L27)
-
-The options of a Signal.State
-
-## Param
-
-**equals**
-
-The optional equality function of your own. It decides if the value changed
-
-## Example
-
-```typescript
-import { Signal } from "@xmachines/play-signals";
-import type { SignalOptions } from "@xmachines/play-signals";
-
-const options: SignalOptions<number> = {
-	equals: (a, b) => a === b,
-};
-const count = new Signal.State(0, options);
-```
-
-## Type Parameters
-
-| Type Parameter |
-| -------------- |
-| `T`            |
-
-## Properties
-
-| Property                               | Type                    | Description                                                        | Defined in                                                                                                                               |
-| -------------------------------------- | ----------------------- | ------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-equals"></a> `equals?` | (`a`, `b`) => `boolean` | The equality function of your own. It decides if the value changed | [packages/play-signals/src/types.ts:34](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-signals/src/types.ts#L34) |

package/api/@xmachines/play-signals/interfaces/SignalState.md

@@ -1,68 +0,0 @@
-[API](../../../README.md) / [@xmachines/play-signals](../README.md) / SignalState
-
-# Interface: SignalState\<T\>
-
-Defined in: [packages/play-signals/src/types.ts:54](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-signals/src/types.ts#L54)
-
-The writable state signal. It holds one reactive value
-
-Signal.State is the base primitive of a reactive state. A `get()` call inside a
-computed signal or inside a watcher tracks the state as a dependency. A `set()`
-call notifies every computation and every watcher that depends on the state.
-
-## Example
-
-```typescript
-import { Signal } from "@xmachines/play-signals";
-
-const name = new Signal.State("Alice");
-console.log(name.get()); // 'Alice'
-name.set("Bob");
-console.log(name.get()); // 'Bob'
-```
-
-## Type Parameters
-
-| Type Parameter |
-| -------------- |
-| `T`            |
-
-## Methods
-
-### get()
-
-```ts
-get(): T;
-```
-
-Defined in: [packages/play-signals/src/types.ts:60](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-signals/src/types.ts#L60)
-
-Reads the current value, and tracks the signal as a dependency
-
-#### Returns
-
-`T`
-
-The current value of the signal
-
----
-
-### set()
-
-```ts
-set(value): void;
-```
-
-Defined in: [packages/play-signals/src/types.ts:67](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-signals/src/types.ts#L67)
-
-Writes a new value, and notifies the watchers when the value changed
-
-#### Parameters
-
-| Parameter | Type | Description   |
-| --------- | ---- | ------------- |
-| `value`   | `T`  | The new value |
-
-#### Returns
-
-`void`

package/api/@xmachines/play-signals/interfaces/SignalWatcher.md

@@ -1,97 +0,0 @@
-[API](../../../README.md) / [@xmachines/play-signals](../README.md) / SignalWatcher
-
-# Interface: SignalWatcher
-
-Defined in: [packages/play-signals/src/types.ts:169](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-signals/src/types.ts#L169)
-
-The watcher. It observes each signal change and schedules an effect
-
-Signal.subtle.Watcher observes more than one signal, and it groups the updates.
-It is the low-level primitive, and a framework uses it to make a reactive effect.
-
-## Example
-
-```typescript
-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();
-		console.log("Signals changed:", pending.length);
-	});
-});
-
-watcher.watch(count);
-watcher.watch(doubled);
-
-count.set(5); // The watcher schedules the notification in a microtask
-```
-
-## Methods
-
-### getPending()
-
-```ts
-getPending(): (
-  | SignalState<unknown>
-  | SignalComputed<unknown>)[];
-```
-
-Defined in: [packages/play-signals/src/types.ts:189](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-signals/src/types.ts#L189)
-
-Returns the signals that changed after the last check
-
-#### Returns
-
-(
-\| [`SignalState`](SignalState.md)\<`unknown`\>
-\| [`SignalComputed`](SignalComputed.md)\<`unknown`\>)[]
-
-The array of the signals with an update that waits
-
----
-
-### unwatch()
-
-```ts
-unwatch(signal): void;
-```
-
-Defined in: [packages/play-signals/src/types.ts:182](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-signals/src/types.ts#L182)
-
-Stops the watch of one signal
-
-#### Parameters
-
-| Parameter | Type                                                                                                  | Description         |
-| --------- | ----------------------------------------------------------------------------------------------------- | ------------------- |
-| `signal`  | \| [`SignalState`](SignalState.md)\<`unknown`\> \| [`SignalComputed`](SignalComputed.md)\<`unknown`\> | The signal to leave |
-
-#### Returns
-
-`void`
-
----
-
-### watch()
-
-```ts
-watch(signal): void;
-```
-
-Defined in: [packages/play-signals/src/types.ts:175](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-signals/src/types.ts#L175)
-
-Starts the watch of one signal
-
-#### Parameters
-
-| Parameter | Type                                                                                                  | Description                                  |
-| --------- | ----------------------------------------------------------------------------------------------------- | -------------------------------------------- |
-| `signal`  | \| [`SignalState`](SignalState.md)\<`unknown`\> \| [`SignalComputed`](SignalComputed.md)\<`unknown`\> | The signal to observe: a State or a Computed |
-
-#### Returns
-
-`void`

package/api/@xmachines/play-signals/namespaces/Signal/README.md

@@ -1,22 +0,0 @@
-[API](../../../../README.md) / [@xmachines/play-signals](../../README.md) / Signal
-
-# Signal
-
-## Namespaces
-
-- [subtle](namespaces/subtle/README.md)
-
-## Classes
-
-- [Computed](classes/Computed.md)
-- [State](classes/State.md)
-
-## Interfaces
-
-- [Options](interfaces/Options.md)
-
-## Variables
-
-- [isComputed](variables/isComputed.md)
-- [isState](variables/isState.md)
-- [isWatcher](variables/isWatcher.md)

package/api/@xmachines/play-signals/namespaces/Signal/classes/Computed.md

@@ -1,52 +0,0 @@
-[API](../../../../../README.md) / [@xmachines/play-signals](../../../README.md) / [Signal](../README.md) / Computed
-
-# Class: Computed\<T\>
-
-Defined in: `signal-polyfill`
-
-## Type Parameters
-
-| Type Parameter |
-| -------------- |
-| `T`            |
-
-## Constructors
-
-### Constructor
-
-```ts
-new Computed<T>(computation, options?): Computed<T>;
-```
-
-Defined in: `signal-polyfill`
-
-#### Parameters
-
-| Parameter     | Type                                         |
-| ------------- | -------------------------------------------- |
-| `computation` | () => `T`                                    |
-| `options?`    | [`Options`](../interfaces/Options.md)\<`T`\> |
-
-#### Returns
-
-`Computed`\<`T`\>
-
-## Properties
-
-| Property                            | Modifier   | Type                  | Defined in |
-| ----------------------------------- | ---------- | --------------------- | ---------- |
-| <a id="property-node"></a> `[NODE]` | `readonly` | `ComputedNode`\<`T`\> | -          |
-
-## Methods
-
-### get()
-
-```ts
-get(): T;
-```
-
-Defined in: `signal-polyfill`
-
-#### Returns
-
-`T`