@xmachines/docs 4.0.0 → 5.0.0

package/api/@xmachines/play-react/functions/useSignalEffect.md

@@ -1,77 +0,0 @@
-[API](../../../README.md) / [@xmachines/play-react](../README.md) / useSignalEffect
-
-# Function: useSignalEffect()
-
-```ts
-function useSignalEffect(callback, deps?): void;
-```
-
-Defined in: [packages/play-react/src/useSignalEffect.ts:81](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-react/src/useSignalEffect.ts#L81)
-
-The React hook that subscribes to the signal changes and runs an effect callback
-
-The hook puts the callback in a Signal.Computed, which tracks each signal that
-the callback reads. It then gives the watcher lifecycle to `watchSignal` from
-`@xmachines/play-signals`. That function does the microtask batching, the new arm
-of the watcher, and the disposal. It is the one canonical implementation, and
-every framework renderer uses it.
-
-Architecture:
-
-- The hook puts the callback in a Signal.Computed for the dependency tracking
-- watchSignal owns the Signal.subtle.Watcher lifecycle (Phase 29, memory safety)
-- The microtask batching groups rapid signal updates
-- The callback triggers each new render with its own setState (see the remarks)
-- The hook cleans up on unmount, so that nothing stays in memory
-
-Invariant: Signal-Only Reactivity. The hook watches each signal that the callback reads.
-Invariant: Passive Infrastructure. React observes the signals, and it does not control them.
-
-## Parameters
-
-| Parameter  | Type                           | Default value | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
-| ---------- | ------------------------------ | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `callback` | () => `void` \| (() => `void`) | `undefined`   | The effect function that reads the signals. It can return a cleanup function.                                                                                                                                                                                                                                                                                                                                                                                                         |
-| `deps`     | `DependencyList`               | `[]`          | The optional dependency list, as in useEffect. On a change of one dependency, the hook removes the watcher and the Computed, then makes them again and tracks the signals from the start. The default is `[]`, which subscribes one time for each mount. Give this list when the identity of the object whose signals you read can change during the life of the component, for example an `actor` prop. Without the list, the watcher tracks the signals of the OLD object for ever. |
-
-## Returns
-
-`void`
-
-## Example
-
-```typescript
-const MyComponent = ({ actor }) => {
-  const [view, setView] = useState(null);
-
-  // Subscribe to the actor.currentView signal, and subscribe again on a new actor
-  useSignalEffect(() => {
-    const currentView = actor.currentView.get();
-    setView(currentView);
-  }, [actor]);
-
-  return <div>{view?.root}</div>;
-};
-```
-
-## Remarks
-
-**CRITICAL:** read each signal unconditionally, with no `if` statement. A
-conditional read breaks the dependency tracking.
-
-**Performance:** the microtask batching (queueMicrotask, inside watchSignal)
-stops a flood of React renders when several signals update in rapid sequence.
-
-**Re-rendering:** the hook itself does NOT force a React render on a signal
-change. The callback triggers each new render, because it calls setState with the
-new signal value, as in the example above. The setState bailout of React can
-therefore skip a render when the derived value is the same. An unconditional
-force-update here caused one wasted render for each notification before, also
-when the setState of the callback made the bailout. If you must render again on
-every notification, and you read the signals during the render, copy the signal
-value into the React state inside the callback.
-
-**Implementation note:** the hook puts the callback in a Signal.Computed, because
-Signal.subtle.Watcher cannot track an arbitrary function call. The Computed does
-the dependency tracking. watchSignal evaluates the Computed, which runs the
-callback, on each change of a tracked signal.

package/api/@xmachines/play-router/index/functions/getPatternParamNames.md

@@ -1,29 +0,0 @@
-[API](../../../../README.md) / [@xmachines/play-router](../../README.md) / [index](../README.md) / getPatternParamNames
-
-# Function: getPatternParamNames()
-
-```ts
-function getPatternParamNames(pattern): string[];
-```
-
-Defined in: [packages/play-url/src/framework-params.ts:26](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/framework-params.ts#L26)
-
-Reads the names of every `:param` of a route pattern of the route map.
-
-The names come from the parse of `pattern-grammar.ts`, which reads the WHOLE grammar:
-a `{…}` group and a `(\d+)` constraint both hide a name from an expression that looks
-for `:name` alone. An ANONYMOUS param — `*` and a bare `(\d+)` — carries no name, and
-the list therefore holds none.
-
-## Parameters
-
-| Parameter | Type     | Description                                      |
-| --------- | -------- | ------------------------------------------------ |
-| `pattern` | `string` | A route pattern, for example `/profile/:userId`. |
-
-## Returns
-
-`string`[]
-
-The names, in the order that the pattern declares them. A fresh array, because
-`parsePattern` caches the parse that it reads.

package/api/@xmachines/play-router/index/functions/getRequiredPatternParamNames.md

@@ -1,39 +0,0 @@
-[API](../../../../README.md) / [@xmachines/play-router](../../README.md) / [index](../README.md) / getRequiredPatternParamNames
-
-# Function: getRequiredPatternParamNames()
-
-```ts
-function getRequiredPatternParamNames(pattern): string[];
-```
-
-Defined in: [packages/play-url/src/framework-params.ts:52](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/framework-params.ts#L52)
-
-The names of every param the pattern REQUIRES, so an optional one is left out.
-
-A param is optional when its own modifier is `?` or `*`, and when EVERY group above it
-carries one of the two. `?` alone was the test before, and it read `/files/:path*` and
-`/books{/:id}?` as required patterns: a path that fills neither then counted as a gap,
-the pick was discarded, and a correct parse from Vue Router or SolidJS Router went with
-it. That is the same class of defect as the all-optional bug of !133, for the modifiers
-that the fix did not cover.
-
-An optional segment that did not match has no value, and a framework reports none. That
-is a complete answer and not a partial one, so a MIXED pattern such as
-`/profile/:userId/:tab?` keeps the parse of the framework when only `:tab` is absent.
-
-A pattern whose params are ALL optional reports nothing at all, which reads the same as
-"the framework matched another route", so [pickOwnParams](pickOwnParams.md) falls back for it.
-[resolveFrameworkParams](resolveFrameworkParams.md) settles that case from the PATH instead.
-
-## Parameters
-
-| Parameter | Type     | Description                                            |
-| --------- | -------- | ------------------------------------------------------ |
-| `pattern` | `string` | A route pattern, for example `/profile/:userId/:tab?`. |
-
-## Returns
-
-`string`[]
-
-The required names, in the order that the pattern declares them. A fresh
-array, because `parsePattern` caches the parse that it reads.

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`