@xmachines/docs 1.0.0-beta.9 → 1.1.0

package/api/@xmachines/play/classes/PlayError.md

@@ -0,0 +1,251 @@
+[API](../../../README.md) / [@xmachines/play](../README.md) / PlayError
+
+# Class: PlayError
+
+Defined in: [packages/play/src/errors.ts:64](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play/src/errors.ts#L64)
+
+Base class for all typed runtime errors thrown by `@xmachines/*` packages.
+
+`PlayError` gives every error two structured fields:
+
+- `scope` — the class or module that threw (e.g. `"RouterBridgeBase"`)
+- `code` — a stable, machine-readable identifier (e.g. `"PLAY_ROUTER_SYNC_FAILED"`)
+
+These fields let application code branch on error type without parsing `.message`
+strings, which change across releases.
+
+## Error codes
+
+Each `@xmachines/*` package exports its own typed subclasses from an
+`"./errors"` subpath:
+
+| Package                      | Import                              |
+| ---------------------------- | ----------------------------------- |
+| `@xmachines/play`            | `@xmachines/play/errors`            |
+| `@xmachines/play-router`     | `@xmachines/play-router/errors`     |
+| `@xmachines/play-vue-router` | `@xmachines/play-vue-router/errors` |
+| `@xmachines/play-xstate`     | `@xmachines/play-xstate/errors`     |
+| `@xmachines/play-react`      | `@xmachines/play-react/errors`      |
+| `@xmachines/play-solid`      | `@xmachines/play-solid/errors`      |
+
+`PlayError` itself is exported from the root `@xmachines/play` and is the base
+for all of those subclasses.
+
+## Catching errors by type
+
+```typescript
+import { PlayError } from "@xmachines/play";
+import { RouterSyncError } from "@xmachines/play-router/errors";
+
+try {
+	bridge.connect();
+} catch (err) {
+	if (err instanceof RouterSyncError) {
+		// err.scope === "RouterBridgeBase"
+		// err.code  === "PLAY_ROUTER_SYNC_FAILED"
+		// err.cause  — the original error that triggered the sync failure
+		reportToMonitoring(err);
+	} else if (err instanceof PlayError) {
+		// Any other @xmachines/* error
+		console.error(`[${err.scope}:${err.code}] ${err.message}`);
+	} else {
+		throw err; // Re-throw unknown errors
+	}
+}
+```
+
+## Extending PlayError
+
+```typescript
+import { PlayError } from "@xmachines/play";
+
+export class MyPackageError extends PlayError {
+	constructor(message: string, options?: ErrorOptions) {
+		super("MyScope", "MY_PACKAGE_ERROR_CODE", message, options);
+		this.name = "MyPackageError";
+	}
+}
+```
+
+## Extends
+
+- `Error`
+
+## Extended by
+
+- [`NonNullableError`](NonNullableError.md)
+
+## Constructors
+
+### Constructor
+
+```ts
+new PlayError(
+   scope,
+   code,
+   message,
+   options?): PlayError;
+```
+
+Defined in: [packages/play/src/errors.ts:83](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play/src/errors.ts#L83)
+
+#### Parameters
+
+| Parameter  | Type           | Description                                                               |
+| ---------- | -------------- | ------------------------------------------------------------------------- |
+| `scope`    | `string`       | The class or module throwing this error.                                  |
+| `code`     | `string`       | Machine-readable error identifier (e.g. `"PLAY_ROUTER_SYNC_FAILED"`).     |
+| `message`  | `string`       | Human-readable description. Do not match on this in code.                 |
+| `options?` | `ErrorOptions` | Standard `ErrorOptions`; pass `{ cause: originalError }` to chain errors. |
+
+#### Returns
+
+`PlayError`
+
+#### Overrides
+
+```ts
+Error.constructor;
+```
+
+## Properties
+
+| Property                                                | Modifier   | Type      | Description                                                                                                                                                                                                                                                                                                                                                                                                                                       | Inherited from          | Defined in                                                                                                                 |
+| ------------------------------------------------------- | ---------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-cause"></a> `cause?`                    | `public`   | `unknown` | -                                                                                                                                                                                                                                                                                                                                                                                                                                                 | `Error.cause`           | -                                                                                                                          |
+| <a id="property-code"></a> `code`                       | `readonly` | `string`  | A stable, machine-readable error identifier. Error codes follow the `PLAY_<PACKAGE>_<DESCRIPTION>` naming convention and are guaranteed stable across patch and minor releases within a major version. Never match on `.message` — always match on `.code` or the subclass.                                                                                                                                                                       | -                       | [packages/play/src/errors.ts:75](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play/src/errors.ts#L75) |
+| <a id="property-message"></a> `message`                 | `public`   | `string`  | -                                                                                                                                                                                                                                                                                                                                                                                                                                                 | `Error.message`         | -                                                                                                                          |
+| <a id="property-name"></a> `name`                       | `public`   | `string`  | -                                                                                                                                                                                                                                                                                                                                                                                                                                                 | `Error.name`            | -                                                                                                                          |
+| <a id="property-scope"></a> `scope`                     | `readonly` | `string`  | The class or module that threw this error (e.g. `"RouterBridgeBase"`).                                                                                                                                                                                                                                                                                                                                                                            | -                       | [packages/play/src/errors.ts:66](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play/src/errors.ts#L66) |
+| <a id="property-stack"></a> `stack?`                    | `public`   | `string`  | -                                                                                                                                                                                                                                                                                                                                                                                                                                                 | `Error.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. | `Error.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
+
+```ts
+Error.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
+
+```ts
+Error.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
+
+```ts
+Error.prepareStackTrace;
+```

package/api/@xmachines/play/functions/assertNonNullable.md

@@ -0,0 +1,56 @@
+[API](../../../README.md) / [@xmachines/play](../README.md) / assertNonNullable
+
+# Function: assertNonNullable()
+
+```ts
+function assertNonNullable<V>(value, name?): NonNullable<V>;
+```
+
+Defined in: [packages/play/src/utils.ts:39](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play/src/utils.ts#L39)
+
+Assert that `value` is neither `null` nor `undefined`, and return it typed
+as `NonNullable<V>` — combining the guard and the narrowed value in a single
+expression.
+
+Unlike a non-null assertion (`value!`), this throws a descriptive error at
+the point of failure rather than producing `undefined`-is-not-an-object`
+crashes somewhere downstream.
+
+Unlike an `asserts value is T` assertion function, this returns the narrowed
+value directly, so no separate variable or `as` cast is required at the call
+site.
+
+## Type Parameters
+
+| Type Parameter |
+| -------------- |
+| `V`            |
+
+## Parameters
+
+| Parameter | Type     | Description                                                                                                          |
+| --------- | -------- | -------------------------------------------------------------------------------------------------------------------- |
+| `value`   | `V`      | The value to check.                                                                                                  |
+| `name?`   | `string` | Optional name included in the error message to identify the missing value (e.g. the variable or injection key name). |
+
+## Returns
+
+`NonNullable`\<`V`\>
+
+`value` typed as `NonNullable<V>` — `null` and `undefined` removed.
+
+## Throws
+
+When `value` is `null` or `undefined`.
+
+## Example
+
+```ts
+import { assertNonNullable } from "@xmachines/play";
+
+// inject() + assertNonNullable in one line — no `!` or intermediate variable:
+const actor = assertNonNullable(inject<AuthActor>("actor"), "actor");
+
+// Element lookup:
+const el = assertNonNullable(document.getElementById("app"), "#app");
+```

package/api/@xmachines/play/type-aliases/PlayEvent.md

@@ -1,4 +1,4 @@
-[Documentation](../../../README.md) / [@xmachines/play](../README.md) / PlayEvent
+[API](../../../README.md) / [@xmachines/play](../README.md) / PlayEvent
 
 # Type Alias: PlayEvent\<TPayload\>
 
@@ -6,7 +6,7 @@
 type PlayEvent<TPayload> = object & TPayload;
 ```
 
-Defined in: [types.ts:69](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play/src/types.ts#L69)
+Defined in: [packages/play/src/types.ts:69](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play/src/types.ts#L69)
 
 Generic event type for Play Architecture
 
@@ -32,9 +32,9 @@ Robot, and other state machine libraries.
 
 ## Type Declaration
 
-| Name   | Type     | Defined in                                                                                                                               |
-| ------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
-| `type` | `string` | [types.ts:70](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play/src/types.ts#L70) |
+| Name   | Type     | Defined in                                                                                                               |
+| ------ | -------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `type` | `string` | [packages/play/src/types.ts:70](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play/src/types.ts#L70) |
 
 ## Type Parameters
 
@@ -78,4 +78,4 @@ const invalid: LoginEvent = { type: "auth.login" }; // Error!
 
 ## See
 
-[RFC Play v1](https://gitlab.com/xmachin-es/rfc/-/blob/main/src/play-v1.md)
+[Play RFC](../../../../rfc/play.md)