@xmachines/docs 6.1.0 → 7.0.0

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

@@ -4,7 +4,7 @@
 
 The atom primitives for XMachines. They give the Play Architecture fine-grained reactive state. The primitives propagate state without a glitch and without a subscription of the consumer.
 
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Version](https://img.shields.io/badge/version-6.1.0-blue)](https://www.npmjs.com/package/@xmachines/play-atom)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Version](https://img.shields.io/badge/version-7.0.0-blue)](https://www.npmjs.com/package/@xmachines/play-atom)
 
 ## Installation
 
@@ -60,9 +60,14 @@ A computation tracks each atom that it reads. A dynamic branch is safe: the comp
 The getter takes ONE parameter: the value that the atom holds already. It is `undefined` before the first derivation. Return it to keep the atom still, which stops the propagation at this atom:
 
 ```typescript
-const view = createAtom((previous) => {
-	const next = derive(source.get());
-	return equivalent(previous, next) ? (previous ?? null) : next;
+import { createAtom } from "@xmachines/play-atom";
+
+const source = createAtom({ title: "Home", clicks: 0 });
+
+const view = createAtom<{ title: string }>((previous) => {
+	const next = { title: source.get().title };
+	// A click changes no title, so the atom keeps the object that it holds
+	return previous?.title === next.title ? previous : next;
 });
 ```
 
@@ -115,6 +120,10 @@ The cleanup function is idempotent. A second call is safe, and it does not throw
 Every atom carries `subscribe`. The observer runs SYNCHRONOUSLY, inside the `set` of the atom that changed, and nothing coalesces the calls. An observer that throws therefore throws inside that `set`, and the failure lands in the code that wrote the atom. Prefer `watchAtom` unless you need the notification at the exact moment of the write.
 
 ```typescript
+import { createAtom } from "@xmachines/play-atom";
+
+const count = createAtom(0);
+
 const subscription = count.subscribe((value) => console.log(value));
 subscription.unsubscribe();
 ```
@@ -123,6 +132,9 @@ The subscription is the plain `{ unsubscribe }` of the engine. To hold it with `
 
 ```typescript
 import { asDisposable } from "@xmachines/core/utils";
+import { createAtom } from "@xmachines/play-atom";
+
+const count = createAtom(0);
 
 {
 	const plain = count.subscribe((value) => console.log(value));

package/api/@xmachines/play-atom/functions/watchAtom.md

@@ -6,7 +6,7 @@
 function watchAtom<T>(atom, onValue): () => void;
 ```
 
-Defined in: [watch-atom.ts:57](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/play-atom/src/watch-atom.ts#L57)
+Defined in: [watch-atom.ts:57](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/packages/play-atom/src/watch-atom.ts#L57)
 
 Subscribes to one atom, and coalesces the notifications into one microtask.
 

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

@@ -2,7 +2,7 @@
 
 # Interface: AsyncAtomOptions
 
-Defined in: [types.ts:168](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/play-atom/src/types.ts#L168)
+Defined in: [types.ts:168](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/packages/play-atom/src/types.ts#L168)
 
 What `createAsyncAtom` gives its getter
 
@@ -13,4 +13,4 @@ stale answer reaches the atom never. Pass it to `fetch`, and the request stops w
 
 | Property                              | Modifier   | Type          | Description                                                  | Defined in                                                                                                    |
 | ------------------------------------- | ---------- | ------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------- |
-| <a id="property-signal"></a> `signal` | `readonly` | `AbortSignal` | Aborted when the atom derives again before this run settles. | [types.ts:170](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/play-atom/src/types.ts#L170) |
+| <a id="property-signal"></a> `signal` | `readonly` | `AbortSignal` | Aborted when the atom derives again before this run settles. | [types.ts:170](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/packages/play-atom/src/types.ts#L170) |

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

@@ -2,7 +2,7 @@
 
 # Interface: Atom\<T\>
 
-Defined in: [types.ts:117](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/play-atom/src/types.ts#L117)
+Defined in: [types.ts:117](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/packages/play-atom/src/types.ts#L117)
 
 The writable atom. It holds one reactive value
 
@@ -40,7 +40,7 @@ name.set((previous) => previous.toUpperCase()); // "BOB"
 get(): T;
 ```
 
-Defined in: [types.ts:59](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/play-atom/src/types.ts#L59)
+Defined in: [types.ts:59](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/packages/play-atom/src/types.ts#L59)
 
 #### Returns
 
@@ -60,7 +60,7 @@ Defined in: [types.ts:59](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1
 set(fn): void;
 ```
 
-Defined in: [types.ts:119](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/play-atom/src/types.ts#L119)
+Defined in: [types.ts:119](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/packages/play-atom/src/types.ts#L119)
 
 Sets the value of the atom from the previous value.
 
@@ -80,7 +80,7 @@ Sets the value of the atom from the previous value.
 set(value): void;
 ```
 
-Defined in: [types.ts:121](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/play-atom/src/types.ts#L121)
+Defined in: [types.ts:121](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/packages/play-atom/src/types.ts#L121)
 
 Sets the value of the atom.
 
@@ -104,7 +104,7 @@ Sets the value of the atom.
 subscribe(observer): AtomSubscription;
 ```
 
-Defined in: [types.ts:60](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/play-atom/src/types.ts#L60)
+Defined in: [types.ts:60](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/packages/play-atom/src/types.ts#L60)
 
 ##### Parameters
 
@@ -130,7 +130,7 @@ subscribe(
 ): AtomSubscription;
 ```
 
-Defined in: [types.ts:61](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/play-atom/src/types.ts#L61)
+Defined in: [types.ts:61](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/packages/play-atom/src/types.ts#L61)
 
 ##### Parameters
 

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

@@ -2,7 +2,7 @@
 
 # Interface: AtomObserver\<T\>
 
-Defined in: [types.ts:34](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/play-atom/src/types.ts#L34)
+Defined in: [types.ts:34](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/packages/play-atom/src/types.ts#L34)
 
 The observer of an atom, in the object form
 
@@ -20,6 +20,6 @@ consumers that adapt an atom to an observable.
 
 | Property                                   | Type                | Defined in                                                                                                  |
 | ------------------------------------------ | ------------------- | ----------------------------------------------------------------------------------------------------------- |
-| <a id="property-complete"></a> `complete?` | () => `void`        | [types.ts:37](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/play-atom/src/types.ts#L37) |
-| <a id="property-error"></a> `error?`       | (`error`) => `void` | [types.ts:36](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/play-atom/src/types.ts#L36) |
-| <a id="property-next"></a> `next?`         | (`value`) => `void` | [types.ts:35](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/play-atom/src/types.ts#L35) |
+| <a id="property-complete"></a> `complete?` | () => `void`        | [types.ts:37](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/packages/play-atom/src/types.ts#L37) |
+| <a id="property-error"></a> `error?`       | (`error`) => `void` | [types.ts:36](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/packages/play-atom/src/types.ts#L36) |
+| <a id="property-next"></a> `next?`         | (`value`) => `void` | [types.ts:35](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/packages/play-atom/src/types.ts#L35) |

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

@@ -2,7 +2,7 @@
 
 # Interface: AtomOptions\<T\>
 
-Defined in: [types.ts:147](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/play-atom/src/types.ts#L147)
+Defined in: [types.ts:147](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/packages/play-atom/src/types.ts#L147)
 
 The options of `createAtom`
 
@@ -30,4 +30,4 @@ const point = createAtom(
 
 | Property                                 | Type                              | Defined in                                                                                                    |
 | ---------------------------------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------- |
-| <a id="property-compare"></a> `compare?` | (`previous`, `next`) => `boolean` | [types.ts:148](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/play-atom/src/types.ts#L148) |
+| <a id="property-compare"></a> `compare?` | (`previous`, `next`) => `boolean` | [types.ts:148](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/packages/play-atom/src/types.ts#L148) |

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

@@ -2,7 +2,7 @@
 
 # Interface: AtomSubscription
 
-Defined in: [types.ts:23](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/play-atom/src/types.ts#L23)
+Defined in: [types.ts:23](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/packages/play-atom/src/types.ts#L23)
 
 The release of one subscription
 
@@ -16,7 +16,7 @@ The release of one subscription
 unsubscribe(): void;
 ```
 
-Defined in: [types.ts:24](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/play-atom/src/types.ts#L24)
+Defined in: [types.ts:24](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/packages/play-atom/src/types.ts#L24)
 
 #### Returns
 

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

@@ -2,7 +2,7 @@
 
 # Interface: BaseAtom\<T\>
 
-Defined in: [types.ts:74](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/play-atom/src/types.ts#L74)
+Defined in: [types.ts:74](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/packages/play-atom/src/types.ts#L74)
 
 The common base of a writable atom and a computed atom
 
@@ -32,7 +32,7 @@ both kinds.
 get(): T;
 ```
 
-Defined in: [types.ts:59](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/play-atom/src/types.ts#L59)
+Defined in: [types.ts:59](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/packages/play-atom/src/types.ts#L59)
 
 #### Returns
 
@@ -52,7 +52,7 @@ Defined in: [types.ts:59](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1
 subscribe(observer): AtomSubscription;
 ```
 
-Defined in: [types.ts:60](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/play-atom/src/types.ts#L60)
+Defined in: [types.ts:60](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/packages/play-atom/src/types.ts#L60)
 
 ##### Parameters
 
@@ -78,7 +78,7 @@ subscribe(
 ): AtomSubscription;
 ```
 
-Defined in: [types.ts:61](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/play-atom/src/types.ts#L61)
+Defined in: [types.ts:61](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/packages/play-atom/src/types.ts#L61)
 
 ##### Parameters
 

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

@@ -2,7 +2,7 @@
 
 # Interface: CreateAtom()
 
-Defined in: [create-atom.ts:33](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/play-atom/src/create-atom.ts#L33)
+Defined in: [create-atom.ts:33](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/packages/play-atom/src/create-atom.ts#L33)
 
 The two forms of `createAtom`
 
@@ -22,7 +22,7 @@ because `get` tracked the edge already.
 CreateAtom<T>(getValue, options?): ReadonlyAtom<T>;
 ```
 
-Defined in: [create-atom.ts:34](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/play-atom/src/create-atom.ts#L34)
+Defined in: [create-atom.ts:34](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/packages/play-atom/src/create-atom.ts#L34)
 
 The two forms of `createAtom`
 
@@ -59,7 +59,7 @@ because `get` tracked the edge already.
 CreateAtom<T>(initialValue, options?): Atom<T>;
 ```
 
-Defined in: [create-atom.ts:35](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/play-atom/src/create-atom.ts#L35)
+Defined in: [create-atom.ts:35](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/packages/play-atom/src/create-atom.ts#L35)
 
 The two forms of `createAtom`
 

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

@@ -2,7 +2,7 @@
 
 # Interface: Readable\<T\>
 
-Defined in: [types.ts:58](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/play-atom/src/types.ts#L58)
+Defined in: [types.ts:58](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/packages/play-atom/src/types.ts#L58)
 
 The read side of an atom
 
@@ -40,7 +40,7 @@ show(createAtom("ready")); // "ready"
 get(): T;
 ```
 
-Defined in: [types.ts:59](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/play-atom/src/types.ts#L59)
+Defined in: [types.ts:59](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/packages/play-atom/src/types.ts#L59)
 
 #### Returns
 
@@ -56,7 +56,7 @@ Defined in: [types.ts:59](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1
 subscribe(observer): AtomSubscription;
 ```
 
-Defined in: [types.ts:60](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/play-atom/src/types.ts#L60)
+Defined in: [types.ts:60](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/packages/play-atom/src/types.ts#L60)
 
 ##### Parameters
 
@@ -78,7 +78,7 @@ subscribe(
 ): AtomSubscription;
 ```
 
-Defined in: [types.ts:61](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/play-atom/src/types.ts#L61)
+Defined in: [types.ts:61](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/packages/play-atom/src/types.ts#L61)
 
 ##### Parameters
 

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

@@ -2,7 +2,7 @@
 
 # Interface: ReadonlyAtom\<T\>
 
-Defined in: [types.ts:97](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/play-atom/src/types.ts#L97)
+Defined in: [types.ts:97](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/packages/play-atom/src/types.ts#L97)
 
 The computed atom. It evaluates late, and it memoizes the result
 
@@ -43,7 +43,7 @@ console.log(doubled.get()); // 10 (from the memory, with no new computation)
 get(): T;
 ```
 
-Defined in: [types.ts:59](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/play-atom/src/types.ts#L59)
+Defined in: [types.ts:59](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/packages/play-atom/src/types.ts#L59)
 
 #### Returns
 
@@ -63,7 +63,7 @@ Defined in: [types.ts:59](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1
 subscribe(observer): AtomSubscription;
 ```
 
-Defined in: [types.ts:60](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/play-atom/src/types.ts#L60)
+Defined in: [types.ts:60](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/packages/play-atom/src/types.ts#L60)
 
 ##### Parameters
 
@@ -89,7 +89,7 @@ subscribe(
 ): AtomSubscription;
 ```
 
-Defined in: [types.ts:61](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/play-atom/src/types.ts#L61)
+Defined in: [types.ts:61](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/packages/play-atom/src/types.ts#L61)
 
 ##### Parameters
 

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

@@ -6,7 +6,7 @@
 type AnyAtom = BaseAtom<unknown>;
 ```
 
-Defined in: [types.ts:129](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/play-atom/src/types.ts#L129)
+Defined in: [types.ts:129](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/packages/play-atom/src/types.ts#L129)
 
 An atom of an unknown value type
 

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

@@ -17,7 +17,7 @@ type AsyncAtomState<TData, TError> =
 	  };
 ```
 
-Defined in: [types.ts:157](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/play-atom/src/types.ts#L157)
+Defined in: [types.ts:157](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/packages/play-atom/src/types.ts#L157)
 
 The state of an atom that reads a promise
 

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

@@ -7,7 +7,7 @@ const createAsyncAtom: <T>(getValue, options?) => ReadonlyAtom<AsyncAtomState<T>
 	createEngineAsyncAtom;
 ```
 
-Defined in: [create-atom.ts:64](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/play-atom/src/create-atom.ts#L64)
+Defined in: [create-atom.ts:64](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/packages/play-atom/src/create-atom.ts#L64)
 
 Builds a read-only atom that holds the state of a promise
 

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

@@ -6,7 +6,7 @@
 const createAtom: CreateAtom = createEngineAtom;
 ```
 
-Defined in: [create-atom.ts:47](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/play-atom/src/create-atom.ts#L47)
+Defined in: [create-atom.ts:47](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/packages/play-atom/src/create-atom.ts#L47)
 
 Builds a writable atom from a value, and a computed atom from a function
 

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

@@ -6,7 +6,7 @@
 const createWritableAtom: <T>(initialValue, options?) => Atom<T> = createAtom;
 ```
 
-Defined in: [create-writable-atom.ts:50](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/play-atom/src/create-writable-atom.ts#L50)
+Defined in: [create-writable-atom.ts:50](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/packages/play-atom/src/create-writable-atom.ts#L50)
 
 Builds a WRITABLE atom, and never a computed one.