@xmachines/docs 4.0.0 → 5.0.1

package/api/@xmachines/play-atom/interfaces/BaseAtom.md

@@ -0,0 +1,97 @@
+[API](../../../README.md) / [@xmachines/play-atom](../README.md) / BaseAtom
+
+# Interface: BaseAtom\<T\>
+
+Defined in: [play-atom/src/types.ts:74](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-atom/src/types.ts#L74)
+
+The common base of a writable atom and a computed atom
+
+Use it for a value that a caller reads and observes, when the caller must accept
+both kinds.
+
+## Extends
+
+- [`Readable`](Readable.md)\<`T`\>
+
+## Extended by
+
+- [`Atom`](Atom.md)
+- [`ReadonlyAtom`](ReadonlyAtom.md)
+
+## Type Parameters
+
+| Type Parameter |
+| -------------- |
+| `T`            |
+
+## Methods
+
+### get()
+
+```ts
+get(): T;
+```
+
+Defined in: [play-atom/src/types.ts:59](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-atom/src/types.ts#L59)
+
+#### Returns
+
+`T`
+
+#### Inherited from
+
+[`Readable`](Readable.md).[`get`](Readable.md#get)
+
+---
+
+### subscribe()
+
+#### Call Signature
+
+```ts
+subscribe(observer): AtomSubscription;
+```
+
+Defined in: [play-atom/src/types.ts:60](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-atom/src/types.ts#L60)
+
+##### Parameters
+
+| Parameter  | Type                                     |
+| ---------- | ---------------------------------------- |
+| `observer` | [`AtomObserver`](AtomObserver.md)\<`T`\> |
+
+##### Returns
+
+[`AtomSubscription`](AtomSubscription.md)
+
+##### Inherited from
+
+[`Readable`](Readable.md).[`subscribe`](Readable.md#subscribe)
+
+#### Call Signature
+
+```ts
+subscribe(
+   next,
+   error?,
+   complete?
+): AtomSubscription;
+```
+
+Defined in: [play-atom/src/types.ts:61](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-atom/src/types.ts#L61)
+
+##### Parameters
+
+| Parameter   | Type                |
+| ----------- | ------------------- |
+| `next`      | (`value`) => `void` |
+| `error?`    | (`error`) => `void` |
+| `complete?` | () => `void`        |
+
+##### Returns
+
+[`AtomSubscription`](AtomSubscription.md)
+
+##### Inherited from
+
+[`Readable`](Readable.md).[`subscribe`](Readable.md#subscribe)

package/api/@xmachines/play-atom/interfaces/CreateAtom.md

@@ -0,0 +1,91 @@
+[API](../../../README.md) / [@xmachines/play-atom](../README.md) / CreateAtom
+
+# Interface: CreateAtom()
+
+Defined in: [play-atom/src/create-atom.ts:33](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-atom/src/create-atom.ts#L33)
+
+The two forms of `createAtom`
+
+A function argument builds a COMPUTED atom, which reads its dependencies and gives a
+`ReadonlyAtom`. Any other argument builds a WRITABLE atom, which holds the value and
+gives an `Atom`.
+
+A computed getter reads each dependency with the `get` of that dependency, and the
+engine records the edge as it reads. Its one parameter is the PREVIOUS value, which is
+`undefined` on the first derivation. `@xstate/store` 3 passed a `read` helper in that
+first position and the previous value in the second; version 4 dropped the helper,
+because `get` tracked the edge already.
+
+## Call Signature
+
+```ts
+CreateAtom<T>(getValue, options?): ReadonlyAtom<T>;
+```
+
+Defined in: [play-atom/src/create-atom.ts:34](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-atom/src/create-atom.ts#L34)
+
+The two forms of `createAtom`
+
+A function argument builds a COMPUTED atom, which reads its dependencies and gives a
+`ReadonlyAtom`. Any other argument builds a WRITABLE atom, which holds the value and
+gives an `Atom`.
+
+A computed getter reads each dependency with the `get` of that dependency, and the
+engine records the edge as it reads. Its one parameter is the PREVIOUS value, which is
+`undefined` on the first derivation. `@xstate/store` 3 passed a `read` helper in that
+first position and the previous value in the second; version 4 dropped the helper,
+because `get` tracked the edge already.
+
+### Type Parameters
+
+| Type Parameter |
+| -------------- |
+| `T`            |
+
+### Parameters
+
+| Parameter  | Type                                   |
+| ---------- | -------------------------------------- |
+| `getValue` | (`previous?`) => `T`                   |
+| `options?` | [`AtomOptions`](AtomOptions.md)\<`T`\> |
+
+### Returns
+
+[`ReadonlyAtom`](ReadonlyAtom.md)\<`T`\>
+
+## Call Signature
+
+```ts
+CreateAtom<T>(initialValue, options?): Atom<T>;
+```
+
+Defined in: [play-atom/src/create-atom.ts:35](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-atom/src/create-atom.ts#L35)
+
+The two forms of `createAtom`
+
+A function argument builds a COMPUTED atom, which reads its dependencies and gives a
+`ReadonlyAtom`. Any other argument builds a WRITABLE atom, which holds the value and
+gives an `Atom`.
+
+A computed getter reads each dependency with the `get` of that dependency, and the
+engine records the edge as it reads. Its one parameter is the PREVIOUS value, which is
+`undefined` on the first derivation. `@xstate/store` 3 passed a `read` helper in that
+first position and the previous value in the second; version 4 dropped the helper,
+because `get` tracked the edge already.
+
+### Type Parameters
+
+| Type Parameter |
+| -------------- |
+| `T`            |
+
+### Parameters
+
+| Parameter      | Type                                   |
+| -------------- | -------------------------------------- |
+| `initialValue` | `T`                                    |
+| `options?`     | [`AtomOptions`](AtomOptions.md)\<`T`\> |
+
+### Returns
+
+[`Atom`](Atom.md)\<`T`\>

package/api/@xmachines/play-atom/interfaces/Readable.md

@@ -0,0 +1,93 @@
+[API](../../../README.md) / [@xmachines/play-atom](../README.md) / Readable
+
+# Interface: Readable\<T\>
+
+Defined in: [play-atom/src/types.ts:58](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-atom/src/types.ts#L58)
+
+The read side of an atom
+
+`Readable` holds `get()` and `subscribe()`. A function that only READS an atom takes
+this type, and it therefore accepts an `Atom`, a `ReadonlyAtom`, and a store
+selection alike.
+
+## Example
+
+```typescript
+import { createAtom, type Readable } from "@xmachines/play-atom";
+
+function show(source: Readable<string>): string {
+	return source.get();
+}
+
+show(createAtom("ready")); // "ready"
+```
+
+## Extended by
+
+- [`BaseAtom`](BaseAtom.md)
+
+## Type Parameters
+
+| Type Parameter |
+| -------------- |
+| `T`            |
+
+## Methods
+
+### get()
+
+```ts
+get(): T;
+```
+
+Defined in: [play-atom/src/types.ts:59](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-atom/src/types.ts#L59)
+
+#### Returns
+
+`T`
+
+---
+
+### subscribe()
+
+#### Call Signature
+
+```ts
+subscribe(observer): AtomSubscription;
+```
+
+Defined in: [play-atom/src/types.ts:60](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-atom/src/types.ts#L60)
+
+##### Parameters
+
+| Parameter  | Type                                     |
+| ---------- | ---------------------------------------- |
+| `observer` | [`AtomObserver`](AtomObserver.md)\<`T`\> |
+
+##### Returns
+
+[`AtomSubscription`](AtomSubscription.md)
+
+#### Call Signature
+
+```ts
+subscribe(
+   next,
+   error?,
+   complete?
+): AtomSubscription;
+```
+
+Defined in: [play-atom/src/types.ts:61](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-atom/src/types.ts#L61)
+
+##### Parameters
+
+| Parameter   | Type                |
+| ----------- | ------------------- |
+| `next`      | (`value`) => `void` |
+| `error?`    | (`error`) => `void` |
+| `complete?` | () => `void`        |
+
+##### Returns
+
+[`AtomSubscription`](AtomSubscription.md)

package/api/@xmachines/play-atom/interfaces/ReadonlyAtom.md

@@ -0,0 +1,108 @@
+[API](../../../README.md) / [@xmachines/play-atom](../README.md) / ReadonlyAtom
+
+# Interface: ReadonlyAtom\<T\>
+
+Defined in: [play-atom/src/types.ts:97](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-atom/src/types.ts#L97)
+
+The computed atom. It evaluates late, and it memoizes the result
+
+`createAtom` returns this type for a function argument. The atom tracks each
+dependency when it runs the function, and it runs the function again only after a
+dependency changes. The atom therefore tracks each dependency for you, and you
+manage no subscription.
+
+## Example
+
+```typescript
+import { createAtom } from "@xmachines/play-atom";
+
+const count = createAtom(0);
+const doubled = createAtom(() => count.get() * 2);
+
+console.log(doubled.get()); // 0
+count.set(5);
+console.log(doubled.get()); // 10 (the atom computed it again)
+console.log(doubled.get()); // 10 (from the memory, with no new computation)
+```
+
+## Extends
+
+- [`BaseAtom`](BaseAtom.md)\<`T`\>
+
+## Type Parameters
+
+| Type Parameter |
+| -------------- |
+| `T`            |
+
+## Methods
+
+### get()
+
+```ts
+get(): T;
+```
+
+Defined in: [play-atom/src/types.ts:59](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-atom/src/types.ts#L59)
+
+#### Returns
+
+`T`
+
+#### Inherited from
+
+[`BaseAtom`](BaseAtom.md).[`get`](BaseAtom.md#get)
+
+---
+
+### subscribe()
+
+#### Call Signature
+
+```ts
+subscribe(observer): AtomSubscription;
+```
+
+Defined in: [play-atom/src/types.ts:60](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-atom/src/types.ts#L60)
+
+##### Parameters
+
+| Parameter  | Type                                     |
+| ---------- | ---------------------------------------- |
+| `observer` | [`AtomObserver`](AtomObserver.md)\<`T`\> |
+
+##### Returns
+
+[`AtomSubscription`](AtomSubscription.md)
+
+##### Inherited from
+
+[`BaseAtom`](BaseAtom.md).[`subscribe`](BaseAtom.md#subscribe)
+
+#### Call Signature
+
+```ts
+subscribe(
+   next,
+   error?,
+   complete?
+): AtomSubscription;
+```
+
+Defined in: [play-atom/src/types.ts:61](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-atom/src/types.ts#L61)
+
+##### Parameters
+
+| Parameter   | Type                |
+| ----------- | ------------------- |
+| `next`      | (`value`) => `void` |
+| `error?`    | (`error`) => `void` |
+| `complete?` | () => `void`        |
+
+##### Returns
+
+[`AtomSubscription`](AtomSubscription.md)
+
+##### Inherited from
+
+[`BaseAtom`](BaseAtom.md).[`subscribe`](BaseAtom.md#subscribe)

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

@@ -0,0 +1,13 @@
+[API](../../../README.md) / [@xmachines/play-atom](../README.md) / AnyAtom
+
+# Type Alias: AnyAtom
+
+```ts
+type AnyAtom = BaseAtom<unknown>;
+```
+
+Defined in: [play-atom/src/types.ts:129](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-atom/src/types.ts#L129)
+
+An atom of an unknown value type
+
+Use it for a collection that holds atoms of mixed types.

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

@@ -0,0 +1,32 @@
+[API](../../../README.md) / [@xmachines/play-atom](../README.md) / AsyncAtomState
+
+# Type Alias: AsyncAtomState\<TData, TError\>
+
+```ts
+type AsyncAtomState<TData, TError> =
+	| {
+			status: "pending";
+	  }
+	| {
+			data: TData;
+			status: "done";
+	  }
+	| {
+			error: TError;
+			status: "error";
+	  };
+```
+
+Defined in: [play-atom/src/types.ts:157](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-atom/src/types.ts#L157)
+
+The state of an atom that reads a promise
+
+`createAsyncAtom` holds this shape. Read `status` first, and the compiler then gives
+you `data` or `error`.
+
+## Type Parameters
+
+| Type Parameter | Default type |
+| -------------- | ------------ |
+| `TData`        | -            |
+| `TError`       | `unknown`    |

package/api/@xmachines/{play-signals → play-atom}/type-aliases/Cleanup.md

@@ -1,4 +1,4 @@
-[API](../../../README.md) / [@xmachines/play-signals](../README.md) / Cleanup
+[API](../../../README.md) / [@xmachines/play-atom](../README.md) / Cleanup
 
 # Type Alias: Cleanup
 
@@ -6,7 +6,7 @@
 type Cleanup = () => void & { [Key in DisposeKey]: () => void };
 ```
 
-Defined in: [packages/play/src/disposable.ts:66](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play/src/disposable.ts#L66)
+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.
 
@@ -16,12 +16,12 @@ caller inside one scope writes `using` and writes no teardown at all:
 
 ```ts
 // The explicit form. It stays correct.
-const stop = watchSignal(count, render);
+const stop = watchAtom(count, render);
 stop();
 
 // The scoped form. The scope releases it, and an exception releases it too.
 {
-	using stop = watchSignal(count, render);
+	using stop = watchAtom(count, render);
 	render(count.get());
 }
 ```

package/api/@xmachines/play-atom/variables/createAsyncAtom.md

@@ -0,0 +1,42 @@
+[API](../../../README.md) / [@xmachines/play-atom](../README.md) / createAsyncAtom
+
+# Variable: createAsyncAtom
+
+```ts
+const createAsyncAtom: <T>(getValue, options?) => ReadonlyAtom<AsyncAtomState<T>> =
+	createEngineAsyncAtom;
+```
+
+Defined in: [play-atom/src/create-atom.ts:64](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-atom/src/create-atom.ts#L64)
+
+Builds a read-only atom that holds the state of a promise
+
+The atom starts at `pending`, and it moves to `done` or to `error`.
+
+The getter receives an `AbortSignal`. The engine aborts it when the atom derives again
+before the run settles, so a stale answer reaches the atom never. A getter that needs no
+signal takes no parameter.
+
+## Type Parameters
+
+| Type Parameter |
+| -------------- |
+| `T`            |
+
+## Parameters
+
+| Parameter  | Type                                                                                                          |
+| ---------- | ------------------------------------------------------------------------------------------------------------- |
+| `getValue` | (`options`) => `Promise`\<`T`\>                                                                               |
+| `options?` | [`AtomOptions`](../interfaces/AtomOptions.md)\<[`AsyncAtomState`](../type-aliases/AsyncAtomState.md)\<`T`\>\> |
+
+## Returns
+
+[`ReadonlyAtom`](../interfaces/ReadonlyAtom.md)\<[`AsyncAtomState`](../type-aliases/AsyncAtomState.md)\<`T`\>\>
+
+## Example
+
+```typescript
+const user = createAsyncAtom(() => fetch("/me").then((response) => response.json()));
+if (user.get().status === "done") console.log("ready");
+```

package/api/@xmachines/play-atom/variables/createAtom.md

@@ -0,0 +1,18 @@
+[API](../../../README.md) / [@xmachines/play-atom](../README.md) / createAtom
+
+# Variable: createAtom
+
+```ts
+const createAtom: CreateAtom = createEngineAtom;
+```
+
+Defined in: [play-atom/src/create-atom.ts:47](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-atom/src/create-atom.ts#L47)
+
+Builds a writable atom from a value, and a computed atom from a function
+
+## Example
+
+```typescript
+const count = createAtom(0);
+const doubled = createAtom(() => count.get() * 2);
+```

package/api/@xmachines/play-atom/variables/createWritableAtom.md

@@ -0,0 +1,70 @@
+[API](../../../README.md) / [@xmachines/play-atom](../README.md) / createWritableAtom
+
+# Variable: createWritableAtom
+
+```ts
+const createWritableAtom: <T>(initialValue, options?) => Atom<T> = createAtom;
+```
+
+Defined in: [play-atom/src/create-writable-atom.ts:50](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-atom/src/create-writable-atom.ts#L50)
+
+Builds a WRITABLE atom, and never a computed one.
+
+`createAtom` carries two signatures: a function argument builds a computed atom, and
+a value argument builds a writable one. TypeScript reads the signatures in order, so
+it needs to prove that the argument is NOT a function before it reaches the second
+one. For a concrete type it proves that at once, and `createAtom` is then the right
+call.
+
+For an UNRESOLVED type the proof fails. `ReturnType<TMachine["transition"]>` inside a
+generic class is a conditional type that TypeScript cannot evaluate yet, so it cannot
+rule a function out, it picks the first signature, and the call returns a
+`ReadonlyAtom` that carries no `set`. The error arrives at the assignment, and it
+names a type that the reader never wrote.
+
+This function states the one signature. The assignment below checks that the
+signature belongs to `createAtom`, so the two stay in step and no cast hides a
+mistake.
+
+Use `createAtom` everywhere else. Reach for this function when the value type is a
+type parameter, or a conditional type over one.
+
+A CAUTION: the signature states ONE overload, and the implementation is `createAtom`
+itself, which reads a FUNCTION argument as a computed atom. A `T` that a function
+satisfies therefore gets a `ReadonlyAtom` at run time while the type says `Atom`, and
+the first `set` call throws. Hold a function in a wrapper — `createWritableAtom({ fn })`
+— as the value types of this workspace already do.
+
+## Type Parameters
+
+| Type Parameter |
+| -------------- |
+| `T`            |
+
+## Parameters
+
+| Parameter      | Type                                                 | Description                                                  |
+| -------------- | ---------------------------------------------------- | ------------------------------------------------------------ |
+| `initialValue` | `T`                                                  | The first value of the atom. It must not be a function.      |
+| `options?`     | [`AtomOptions`](../interfaces/AtomOptions.md)\<`T`\> | The optional `compare` function. The default is `Object.is`. |
+
+## Returns
+
+[`Atom`](../interfaces/Atom.md)\<`T`\>
+
+The writable atom.
+
+## Example
+
+```typescript
+import { createWritableAtom, type Atom } from "@xmachines/play-atom";
+
+class Holder<T extends { value: unknown }> {
+	// `createAtom(seed)` would give a ReadonlyAtom<T["value"]> here.
+	public readonly state: Atom<T["value"]>;
+
+	constructor(seed: T["value"]) {
+		this.state = createWritableAtom(seed);
+	}
+}
+```