@xmachines/docs 5.0.2 → 6.1.0

package/api/@xmachines/core/errors/classes/DisposeConflictError.md

@@ -0,0 +1,177 @@
+[API](../../../../README.md) / [@xmachines/core](../../README.md) / [errors](../README.md) / DisposeConflictError
+
+# Class: DisposeConflictError
+
+Defined in: [packages/core/src/errors.ts:80](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/core/src/errors.ts#L80)
+
+[asDisposable](../../utils/functions/asDisposable.md) throws this error when the target
+has a dispose member already, and that member is not the named release.
+
+The scope would run that member and never the release that the caller names, so a
+teardown would go missing without a sign. The error is a programmer error: fix the
+call, and do not catch it in production code.
+
+## Extends
+
+- [`BaseError`](BaseError.md)
+
+## Constructors
+
+### Constructor
+
+```ts
+new DisposeConflictError(message, options?): DisposeConflictError;
+```
+
+Defined in: [packages/core/src/errors.ts:81](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/core/src/errors.ts#L81)
+
+#### Parameters
+
+| Parameter  | Type           |
+| ---------- | -------------- |
+| `message`  | `string`       |
+| `options?` | `ErrorOptions` |
+
+#### Returns
+
+`DisposeConflictError`
+
+#### Overrides
+
+[`BaseError`](BaseError.md).[`constructor`](BaseError.md#constructor)
+
+## Properties
+
+| Property                                                | Modifier   | Type      | Description                                                                                                                                                                                                                                                                                                                                                                                                                                       | Inherited from                                                                         | Defined in                                                                                                                 |
+| ------------------------------------------------------- | ---------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-cause"></a> `cause?`                    | `public`   | `unknown` | -                                                                                                                                                                                                                                                                                                                                                                                                                                                 | [`BaseError`](BaseError.md).[`cause`](BaseError.md#property-cause)                     | -                                                                                                                          |
+| <a id="property-code"></a> `code`                       | `readonly` | `string`  | A stable, machine-readable identifier of the error. An error code follows the naming convention `<PACKAGE>_<DESCRIPTION>`, and a Play package writes `PLAY_<PACKAGE>_<DESCRIPTION>`. A code stays the same across each patch release and each minor release of one major version. Never match on `.message`. Always match on `.code`, or on the subclass.                                                                                         | [`BaseError`](BaseError.md).[`code`](BaseError.md#property-code)                       | [packages/core/src/errors.ts:56](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/core/src/errors.ts#L56) |
+| <a id="property-message"></a> `message`                 | `public`   | `string`  | -                                                                                                                                                                                                                                                                                                                                                                                                                                                 | [`BaseError`](BaseError.md).[`message`](BaseError.md#property-message)                 | -                                                                                                                          |
+| <a id="property-name"></a> `name`                       | `public`   | `string`  | -                                                                                                                                                                                                                                                                                                                                                                                                                                                 | [`BaseError`](BaseError.md).[`name`](BaseError.md#property-name)                       | -                                                                                                                          |
+| <a id="property-scope"></a> `scope`                     | `readonly` | `string`  | The class or the module that threw this error, for example `"asDisposable"`.                                                                                                                                                                                                                                                                                                                                                                      | [`BaseError`](BaseError.md).[`scope`](BaseError.md#property-scope)                     | [packages/core/src/errors.ts:46](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/core/src/errors.ts#L46) |
+| <a id="property-stack"></a> `stack?`                    | `public`   | `string`  | -                                                                                                                                                                                                                                                                                                                                                                                                                                                 | [`BaseError`](BaseError.md).[`stack`](BaseError.md#property-stack)                     | -                                                                                                                          |
+| <a id="property-stacktracelimit"></a> `stackTraceLimit` | `static`   | `number`  | The `Error.stackTraceLimit` property specifies the number of stack frames collected by a stack trace (whether generated by `new Error().stack` or `Error.captureStackTrace(obj)`). The default value is `10` but may be set to any valid JavaScript number. Changes will affect any stack trace captured _after_ the value has been changed. If set to a non-number value, or set to a negative number, stack traces will not capture any frames. | [`BaseError`](BaseError.md).[`stackTraceLimit`](BaseError.md#property-stacktracelimit) | -                                                                                                                          |
+
+## Methods
+
+### captureStackTrace()
+
+```ts
+static captureStackTrace(targetObject, constructorOpt?): void;
+```
+
+Defined in: `@types/node`
+
+Creates a `.stack` property on `targetObject`, which when accessed returns
+a string representing the location in the code at which
+`Error.captureStackTrace()` was called.
+
+```js
+const myObject = {};
+Error.captureStackTrace(myObject);
+myObject.stack; // Similar to `new Error().stack`
+```
+
+The first line of the trace will be prefixed with
+`${myObject.name}: ${myObject.message}`.
+
+The optional `constructorOpt` argument accepts a function. If given, all frames
+above `constructorOpt`, including `constructorOpt`, will be omitted from the
+generated stack trace.
+
+The `constructorOpt` argument is useful for hiding implementation
+details of error generation from the user. For instance:
+
+```js
+function a() {
+	b();
+}
+
+function b() {
+	c();
+}
+
+function c() {
+	// Create an error without stack trace to avoid calculating the stack trace twice.
+	const { stackTraceLimit } = Error;
+	Error.stackTraceLimit = 0;
+	const error = new Error();
+	Error.stackTraceLimit = stackTraceLimit;
+
+	// Capture the stack trace above function b
+	Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace
+	throw error;
+}
+
+a();
+```
+
+#### Parameters
+
+| Parameter         | Type       |
+| ----------------- | ---------- |
+| `targetObject`    | `object`   |
+| `constructorOpt?` | `Function` |
+
+#### Returns
+
+`void`
+
+#### Inherited from
+
+[`BaseError`](BaseError.md).[`captureStackTrace`](BaseError.md#capturestacktrace)
+
+---
+
+### isError()
+
+```ts
+static isError(error): error is Error;
+```
+
+Defined in: `typescript`
+
+Indicates whether the argument provided is a built-in Error instance or not.
+
+#### Parameters
+
+| Parameter | Type      |
+| --------- | --------- |
+| `error`   | `unknown` |
+
+#### Returns
+
+`error is Error`
+
+#### Inherited from
+
+[`BaseError`](BaseError.md).[`isError`](BaseError.md#iserror)
+
+---
+
+### prepareStackTrace()
+
+```ts
+static prepareStackTrace(err, stackTraces): any;
+```
+
+Defined in: `@types/node`
+
+#### Parameters
+
+| Parameter     | Type         |
+| ------------- | ------------ |
+| `err`         | `Error`      |
+| `stackTraces` | `CallSite`[] |
+
+#### Returns
+
+`any`
+
+#### See
+
+https://v8.dev/docs/stack-trace-api#customizing-stack-traces
+
+#### Inherited from
+
+[`BaseError`](BaseError.md).[`prepareStackTrace`](BaseError.md#preparestacktrace)

package/api/@xmachines/core/utils/README.md

@@ -0,0 +1,33 @@
+[API](../../../README.md) / [@xmachines/core](../README.md) / utils
+
+# utils
+
+Small shared utilities of the XMachines packages
+
+The `utils` subpath of `@xmachines/core` holds code that more than one `@xmachines/*`
+package needs, and that belongs to no layer of the Play Architecture: the release
+protocol, and small helpers for values and errors. The cache is on the `cache` subpath,
+and the error base is on the `errors` subpath. The subpath keeps no module state, so
+`DISPOSE` resolves to the same symbol in each copy.
+
+## Type Aliases
+
+- [DisposeKey](type-aliases/DisposeKey.md)
+- [DisposeMember](type-aliases/DisposeMember.md)
+
+## Variables
+
+- [DISPOSE](variables/DISPOSE.md)
+
+## Functions
+
+- [asDisposable](functions/asDisposable.md)
+- [createNullRecord](functions/createNullRecord.md)
+- [createWarnOnce](functions/createWarnOnce.md)
+- [describeValue](functions/describeValue.md)
+- [isError](functions/isError.md)
+- [isThenable](functions/isThenable.md)
+- [releaseQuietly](functions/releaseQuietly.md)
+- [rethrowLater](functions/rethrowLater.md)
+- [safeString](functions/safeString.md)
+- [shallowEqualExcept](functions/shallowEqualExcept.md)

package/api/@xmachines/core/utils/functions/asDisposable.md

@@ -0,0 +1,139 @@
+[API](../../../../README.md) / [@xmachines/core](../../README.md) / [utils](../README.md) / asDisposable
+
+# Function: asDisposable()
+
+## Call Signature
+
+```ts
+function asDisposable<F>(release): F & DisposeMember;
+```
+
+Defined in: [packages/core/src/utils/disposable.ts:126](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/core/src/utils/disposable.ts#L126)
+
+Makes one release function a `Disposable`. The function is its own release.
+
+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. A caller that runs the release keeps that
+code, and a caller inside one scope writes `using`:
+
+```ts
+// The explicit form.
+const stop = watchAtom(count, render);
+stop();
+
+// The scoped form. The scope releases it, and an exception releases it too.
+{
+	using stop = asDisposable(watchAtom(count, render));
+	render(count.get());
+}
+```
+
+A value that is a `Disposable` already comes back unchanged. The function adds the key
+only where it is absent, so a second call changes nothing. The one exception is a
+well-known key that a late polyfill installed: the second call stores the release there.
+
+The release 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 accepts that.
+
+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. The `void | undefined` bound rejects
+an async release: a plain `() => void` bound accepts `async () => {}`, because
+TypeScript lets a function that returns a value stand where one that returns `void`
+is wanted. The scope would then ignore the promise, and nothing could await the work.
+
+The bound holds where the compiler knows the return type. It cannot hold where the
+caller erased it: a release typed `any`, such as a bare `vi.fn()`, satisfies every
+constraint. Write the release inline, or type it, and the bound applies.
+
+`using` needs Node 24 or a browser with Explicit Resource Management, and it needs
+`"lib": ["ESNext"]` of the consumer. See [DisposeKey](../type-aliases/DisposeKey.md) for a consumer without it.
+
+### Type Parameters
+
+| Type Parameter                            |
+| ----------------------------------------- |
+| `F` _extends_ () => `void` \| `undefined` |
+
+### Parameters
+
+| Parameter | Type | Description                                                                                                                                                                                                        |
+| --------- | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `release` | `F`  | The release to publish. It must return nothing. The function is changed in place, so pass a function that this caller owns: a shared or module-level function becomes a `Disposable` for every other holder of it. |
+
+### Returns
+
+`F` & [`DisposeMember`](../type-aliases/DisposeMember.md)
+
+The same function, now also a `Disposable`.
+
+### Throws
+
+TypeError - When the function is frozen or is otherwise not extensible, and a
+dispose key holds no member yet.
+
+### See
+
+[Play RFC](../../../../../rfc/play.md)
+
+## Call Signature
+
+```ts
+function asDisposable<T, R>(target, release): T & DisposeMember;
+```
+
+Defined in: [packages/core/src/utils/disposable.ts:157](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/core/src/utils/disposable.ts#L157)
+
+Makes one object a `Disposable`, with a release that the caller names.
+
+The object comes back as itself, with [DISPOSE](../variables/DISPOSE.md) added, so a caller that compares
+two objects sees what it saw before.
+
+An object that is a `Disposable` already, with a dispose member own or inherited,
+makes the call throw. The scope would run that member and never the release that the
+caller names, so a teardown would go missing without a sign. A second call with the
+SAME release is not a conflict: it returns the object, and it writes only a well-known
+key that a late polyfill left empty.
+
+The rules of the function form apply to the release: it must be idempotent, and it
+must be synchronous.
+
+### Type Parameters
+
+| Type Parameter                      |
+| ----------------------------------- |
+| `T` _extends_ `object`              |
+| `R` _extends_ `void` \| `undefined` |
+
+### Parameters
+
+| Parameter | Type      | Description                                                                              |
+| --------- | --------- | ---------------------------------------------------------------------------------------- |
+| `target`  | `T`       | The object to publish. It is changed in place, so pass an object that this release owns. |
+| `release` | () => `R` | The release that the scope runs. It must return nothing.                                 |
+
+### Returns
+
+`T` & [`DisposeMember`](../type-aliases/DisposeMember.md)
+
+The same object, now also a `Disposable`.
+
+### Throws
+
+[DisposeConflictError](../../errors/classes/DisposeConflictError.md) - When
+the object has a dispose member already, and that member is not the named release.
+
+### Throws
+
+TypeError - When the object is frozen or is otherwise not extensible, and a
+dispose key does not hold the release yet.
+
+### Example
+
+```ts
+const subscription = selection.subscribe(render);
+using disposable = asDisposable(subscription, () => subscription.unsubscribe());
+```

package/api/@xmachines/core/utils/functions/createNullRecord.md

@@ -0,0 +1,39 @@
+[API](../../../../README.md) / [@xmachines/core](../../README.md) / [utils](../README.md) / createNullRecord
+
+# Function: createNullRecord()
+
+```ts
+function createNullRecord<V>(): Record<string, V>;
+```
+
+Defined in: [packages/core/src/utils/null-record.ts:21](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/core/src/utils/null-record.ts#L21)
+
+Builds an empty record with no prototype.
+
+A record that collects keys from outside the program — the params of a URL, the query
+of a location — takes any key that the outside sends. An ordinary `{}` inherits from
+`Object.prototype`, so a key such as `__proto__` writes the prototype and not an
+entry, and a key such as `constructor` reads a function that nobody stored. A record
+with no prototype holds each key as an own entry, and it reads nothing it did not
+store.
+
+## Type Parameters
+
+| Type Parameter |
+| -------------- |
+| `V`            |
+
+## Returns
+
+`Record`\<`string`, `V`\>
+
+A new, empty record. Each call builds one.
+
+## Example
+
+```ts
+import { createNullRecord } from "@xmachines/core/utils";
+
+const params = createNullRecord<string>();
+params["__proto__"] = "x"; // an own entry, and the prototype stays null
+```

package/api/@xmachines/core/utils/functions/createWarnOnce.md

@@ -0,0 +1,39 @@
+[API](../../../../README.md) / [@xmachines/core](../../README.md) / [utils](../README.md) / createWarnOnce
+
+# Function: createWarnOnce()
+
+```ts
+function createWarnOnce(): (anchor, message) => void;
+```
+
+Defined in: [packages/core/src/utils/warn-once.ts:27](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/core/src/utils/warn-once.ts#L27)
+
+Builds a function that writes one warning for each anchor object, and no more.
+
+A diagnostic that a hot path finds — a stale field of a static config, read on every
+event — floods the console at the rate of that path. The key of this function is the
+identity of an object that stays the same between two calls, such as the config
+itself. Each anchor therefore reports one time, and a new object reports again.
+
+The function is a factory, and it keeps its memory in a `WeakSet` of its own. A module
+that calls it one time holds one memory for its diagnostics, and an anchor that nothing
+else holds is free for the garbage collector.
+
+## Returns
+
+A function of `(anchor, message)`. It calls `console.warn(message)` for the
+first call with an anchor, and it does nothing for every later call with that anchor.
+
+(`anchor`, `message`) => `void`
+
+## Example
+
+```ts
+import { createWarnOnce } from "@xmachines/core/utils";
+
+const warnOnce = createWarnOnce();
+
+function derive(config: Config): void {
+	if (config.legacy) warnOnce(config, "config.legacy has no effect");
+}
+```

package/api/@xmachines/core/utils/functions/describeValue.md

@@ -0,0 +1,39 @@
+[API](../../../../README.md) / [@xmachines/core](../../README.md) / [utils](../README.md) / describeValue
+
+# Function: describeValue()
+
+```ts
+function describeValue(value): string;
+```
+
+Defined in: [packages/core/src/utils/describe-value.ts:53](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/core/src/utils/describe-value.ts#L53)
+
+Describes an unknown value for the message of an error, and throws nothing itself.
+
+`JSON.stringify` alone is not enough for a value that arrives from the config of a
+user. It returns the VALUE `undefined` for a function, for a symbol, and for
+`undefined`, which puts the text "undefined" in a field that is declared `string`. It
+also THROWS a `TypeError` for a circular object, and an error constructor that throws
+hides the error that it was built to report. The fallback names the type instead, for
+example `[function]`.
+
+## Parameters
+
+| Parameter | Type      | Description            |
+| --------- | --------- | ---------------------- |
+| `value`   | `unknown` | The value to describe. |
+
+## Returns
+
+`string`
+
+The JSON text of the value, or its type in brackets.
+
+## Example
+
+```ts
+import { describeValue } from "@xmachines/core/utils";
+
+describeValue({ path: 1 }); // '{"path":1}'
+describeValue(() => {}); // "[function]"
+```

package/api/@xmachines/core/utils/functions/isError.md

@@ -0,0 +1,46 @@
+[API](../../../../README.md) / [@xmachines/core](../../README.md) / [utils](../README.md) / isError
+
+# Function: isError()
+
+```ts
+function isError(value): value is Error;
+```
+
+Defined in: [packages/core/src/utils/is-error.ts:29](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/core/src/utils/is-error.ts#L29)
+
+Tells if a value is an `Error`, by its identity or by its brand.
+
+The function tries `instanceof` first. It therefore answers `true` for every object
+that inherits from `Error.prototype` of this realm, also one that no `Error`
+constructor built, such as `Object.create(Error.prototype)`.
+
+`instanceof` misses an error from another realm, such as an iframe or `node:vm`. For
+such a value the function uses `Error.isError` where the runtime has it (Node 24 and a
+Baseline 2025 browser), because that function refuses a false `Symbol.toStringTag`. In
+every other runtime the function tests the brand. The type of `Error.isError` is
+structural here, because the lib target of a consumer can be older than the API.
+
+The function can throw for a hostile value: a revoked Proxy traps `instanceof`, and it
+traps the inspection of the brand too. A caller in an error path therefore wraps the
+call in `try`.
+
+## Parameters
+
+| Parameter | Type      | Description        |
+| --------- | --------- | ------------------ |
+| `value`   | `unknown` | The value to test. |
+
+## Returns
+
+`value is Error`
+
+`true` when the value is an `Error` of any realm.
+
+## Example
+
+```ts
+import { isError } from "@xmachines/core/utils";
+
+isError(new TypeError("x")); // true
+isError({ message: "x" }); // false
+```

package/api/@xmachines/core/utils/functions/isThenable.md

@@ -0,0 +1,43 @@
+[API](../../../../README.md) / [@xmachines/core](../../README.md) / [utils](../README.md) / isThenable
+
+# Function: isThenable()
+
+```ts
+function isThenable<T>(value): value is PromiseLike<T>;
+```
+
+Defined in: [packages/core/src/utils/is-thenable.ts:20](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/core/src/utils/is-thenable.ts#L20)
+
+Tells if a value is a thenable, so that the caller can wait for it.
+
+A declared type such as `void | Promise<void>` says nothing at run time: a real
+implementation returns a promise, and a test double returns nothing. The function
+therefore probes the value for a callable `then`, which is the test that `await`
+applies too.
+
+## Type Parameters
+
+| Type Parameter | Default type |
+| -------------- | ------------ |
+| `T`            | `unknown`    |
+
+## Parameters
+
+| Parameter | Type      | Description        |
+| --------- | --------- | ------------------ |
+| `value`   | `unknown` | The value to test. |
+
+## Returns
+
+`value is PromiseLike<T>`
+
+`true` when the value has a callable `then` method.
+
+## Example
+
+```ts
+import { isThenable } from "@xmachines/core/utils";
+
+const result = router.load();
+if (isThenable(result)) await result;
+```

package/api/@xmachines/core/utils/functions/releaseQuietly.md

@@ -0,0 +1,37 @@
+[API](../../../../README.md) / [@xmachines/core](../../README.md) / [utils](../README.md) / releaseQuietly
+
+# Function: releaseQuietly()
+
+```ts
+function releaseQuietly(release, onFailure): void;
+```
+
+Defined in: [packages/core/src/utils/release-quietly.ts:23](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/core/src/utils/release-quietly.ts#L23)
+
+Runs one release, and it contains a failure of that release.
+
+A teardown often runs several releases in a row, and each one can be code of a caller
+that throws. A throw from the first release then skips every release after it, and the
+owner holds a half teardown that no caller can complete. Run each release through this
+function, and each one stands alone: a failure goes to `onFailure`, and the next
+release runs.
+
+## Parameters
+
+| Parameter   | Type                                    | Description                                                                                                                        |
+| ----------- | --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| `release`   | (() => `void`) \| `null` \| `undefined` | The release to run. `null` and `undefined` do nothing, so a field that holds no release yet needs no check at the call.            |
+| `onFailure` | (`failure`) => `void`                   | Receives the value that the release threw. It reports the failure, for example with `console.error`, and it must not throw itself. |
+
+## Returns
+
+`void`
+
+## Example
+
+```ts
+import { releaseQuietly } from "@xmachines/core/utils";
+
+const report = (failure: unknown) => console.error("a release threw", failure);
+for (const release of releases) releaseQuietly(release, report);
+```

package/api/@xmachines/core/utils/functions/rethrowLater.md

@@ -0,0 +1,43 @@
+[API](../../../../README.md) / [@xmachines/core](../../README.md) / [utils](../README.md) / rethrowLater
+
+# Function: rethrowLater()
+
+```ts
+function rethrowLater(error): void;
+```
+
+Defined in: [packages/core/src/utils/rethrow-later.ts:28](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/core/src/utils/rethrow-later.ts#L28)
+
+Throws an error again from a microtask of its own, and returns at once.
+
+A throw from a microtask reaches the global handler of the runtime — the `error` event
+and `window.onerror` in a page, `uncaughtException` in Node — and it touches the
+current stack not. It is not a rejection, so `unhandledrejection` does not see it.
+
+Use it where a throw must not leave the current code: an error handler that a renderer
+contains, or a callback that runs from a microtask already, so that a throw from it
+reaches no caller.
+
+## Parameters
+
+| Parameter | Type      | Description                                                                                      |
+| --------- | --------- | ------------------------------------------------------------------------------------------------ |
+| `error`   | `unknown` | The value to throw again. It is thrown as it is, so an `Error` keeps its identity and its stack. |
+
+## Returns
+
+`void`
+
+## Example
+
+```tsx
+import { rethrowLater } from "@xmachines/core/utils";
+
+<ActorProvider
+	actor={actor}
+	registryResult={registryResult}
+	onError={(error) => rethrowLater(error)}
+>
+	<PlayRenderer />
+</ActorProvider>;
+```