@xmachines/play-xstate 6.0.0 → 7.0.0

package/dist/errors.js

@@ -1,270 +1,273 @@
 import { PlayError } from "@xmachines/play/errors";
 import { describeValue, safeString } from "@xmachines/core/utils";
+//#region packages/play-xstate/src/errors.ts
 /**
- * `buildRouteUrl()` throws this error when the context of the actor does not hold a
- * necessary route parameter.
- *
- * Read the `param` field and the `template` field to identify the parameter that is
- * absent. Your code therefore parses no `.message` string.
- *
- * **Error code:** `PLAY_XSTATE_ROUTE_PARAM_MISSING`
- *
- * Note: `actor.currentRoute.get()` shows this error never. The route derivation
- * catches it, and it returns `null` for the temporary case during a transition. The
- * error leaves a direct `buildRouteUrl()` call only.
- *
- * @example
- * ```typescript
- * import { buildRouteUrl } from "@xmachines/play-xstate/routing";
- * import { MissingRouteParamError } from "@xmachines/play-xstate/errors";
- *
- * try {
- *   buildRouteUrl("/profile/:userId", { params: {}, query: {} });
- * } catch (err) {
- *   if (err instanceof MissingRouteParamError) {
- *     console.error(
- *       `Missing "${err.param}" for template "${err.template}"`
- *     );
- *   }
- * }
- * ```
- */
-export class MissingRouteParamError extends PlayError {
-    /** The name of the route parameter that was absent, for example `"userId"`. */
-    param;
-    /** The route template that needs the absent parameter, for example `"/profile/:userId"`. */
-    template;
-    constructor(param, template) {
-        super("buildRouteUrl", "PLAY_XSTATE_ROUTE_PARAM_MISSING", `Route parameter '${param}' is required by template '${template}' but was not found in context.`);
-        this.name = "MissingRouteParamError";
-        this.param = param;
-        this.template = template;
-    }
-}
+* `buildRouteUrl()` throws this error when the context of the actor does not hold a
+* necessary route parameter.
+*
+* Read the `param` field and the `template` field to identify the parameter that is
+* absent. Your code therefore parses no `.message` string.
+*
+* **Error code:** `PLAY_XSTATE_ROUTE_PARAM_MISSING`
+*
+* Note: `actor.currentRoute.get()` shows this error never. The route derivation
+* catches it, and it returns `null` for the temporary case during a transition. The
+* error leaves a direct `buildRouteUrl()` call only.
+*
+* @example
+* ```typescript
+* import { buildRouteUrl } from "@xmachines/play-xstate/routing";
+* import { MissingRouteParamError } from "@xmachines/play-xstate/errors";
+*
+* try {
+*   buildRouteUrl("/profile/:userId", { params: {}, query: {} });
+* } catch (err) {
+*   if (err instanceof MissingRouteParamError) {
+*     console.error(
+*       `Missing "${err.param}" for template "${err.template}"`
+*     );
+*   }
+* }
+* ```
+*/
+var MissingRouteParamError = class extends PlayError {
+	/** The name of the route parameter that was absent, for example `"userId"`. */
+	param;
+	/** The route template that needs the absent parameter, for example `"/profile/:userId"`. */
+	template;
+	constructor(param, template) {
+		super("buildRouteUrl", "PLAY_XSTATE_ROUTE_PARAM_MISSING", `Route parameter '${param}' is required by template '${template}' but was not found in context.`);
+		this.name = "MissingRouteParamError";
+		this.param = param;
+		this.template = template;
+	}
+};
 /**
- * `buildRouteUrl()` throws this error when a route parameter carries a value that no path
- * can hold, so the template matches the built URL back never.
- *
- * A dot segment is that value. A URL parser resolves `.` and `..` BEFORE it decodes the
- * percent escapes, and it counts `%2e` as the dot, so every encoding of them resolves
- * away: `/files/..` becomes `/`. The actor would hold the route `/files/..` while the
- * address bar shows `/`, and the two stay out of step for the rest of the session.
- *
- * Give the param a value that names a segment. Machine state that can carry a path from a
- * user belongs behind a check of its own, in the same way that a base path checks the
- * values of its `:param` segments.
- *
- * **Error code:** `PLAY_XSTATE_ROUTE_PARAM_INVALID`
- *
- * @example
- * ```typescript
- * import { buildRouteUrl } from "@xmachines/play-xstate/routing";
- * import { InvalidRouteParamError } from "@xmachines/play-xstate/errors";
- *
- * try {
- *   buildRouteUrl("/files/:name", { params: { name: ".." }, query: {} });
- * } catch (err) {
- *   if (err instanceof InvalidRouteParamError) {
- *     console.error(`"${err.value}" cannot stand in "${err.param}"`);
- *   }
- * }
- * ```
- */
-export class InvalidRouteParamError extends PlayError {
-    /** The name of the route parameter that carries the value, for example `"name"`. */
-    param;
-    /** The value that no path can hold, for example `".."`. */
-    value;
-    /** The route template that declares the parameter, for example `"/files/:name"`. */
-    template;
-    constructor(param, value, template) {
-        super("buildRouteUrl", "PLAY_XSTATE_ROUTE_PARAM_INVALID", `Route parameter '${param}' of template '${template}' carries the value '${value}', which resolves away in a URL.`);
-        this.name = "InvalidRouteParamError";
-        this.param = param;
-        this.value = value;
-        this.template = template;
-    }
-}
+* `buildRouteUrl()` throws this error when a route parameter carries a value that no path
+* can hold, so the template matches the built URL back never.
+*
+* A dot segment is that value. A URL parser resolves `.` and `..` BEFORE it decodes the
+* percent escapes, and it counts `%2e` as the dot, so every encoding of them resolves
+* away: `/files/..` becomes `/`. The actor would hold the route `/files/..` while the
+* address bar shows `/`, and the two stay out of step for the rest of the session.
+*
+* Give the param a value that names a segment. Machine state that can carry a path from a
+* user belongs behind a check of its own, in the same way that a base path checks the
+* values of its `:param` segments.
+*
+* **Error code:** `PLAY_XSTATE_ROUTE_PARAM_INVALID`
+*
+* @example
+* ```typescript
+* import { buildRouteUrl } from "@xmachines/play-xstate/routing";
+* import { InvalidRouteParamError } from "@xmachines/play-xstate/errors";
+*
+* try {
+*   buildRouteUrl("/files/:name", { params: { name: ".." }, query: {} });
+* } catch (err) {
+*   if (err instanceof InvalidRouteParamError) {
+*     console.error(`"${err.value}" cannot stand in "${err.param}"`);
+*   }
+* }
+* ```
+*/
+var InvalidRouteParamError = class extends PlayError {
+	/** The name of the route parameter that carries the value, for example `"name"`. */
+	param;
+	/** The value that no path can hold, for example `".."`. */
+	value;
+	/** The route template that declares the parameter, for example `"/files/:name"`. */
+	template;
+	constructor(param, value, template) {
+		super("buildRouteUrl", "PLAY_XSTATE_ROUTE_PARAM_INVALID", `Route parameter '${param}' of template '${template}' carries the value '${value}', which resolves away in a URL.`);
+		this.name = "InvalidRouteParamError";
+		this.param = param;
+		this.value = value;
+		this.template = template;
+	}
+};
 /**
- * `formatPlayRouteTransitions()` throws this error when a state node declares a
- * `meta.route` field but no explicit `id` field.
- *
- * Without an `id`, the function can generate no `play.route` guard that targets the
- * state: the guard compares `event.to` with `#<id>`. An absent `id` therefore makes
- * the state unreachable through the routing, and nothing says so. This error shows
- * the fault of the configuration at the moment of the machine definition, and the
- * function skips no state in silence.
- *
- * **Error code:** `PLAY_XSTATE_MISSING_STATE_ID`
- *
- * @example
- * ```typescript
- * // Bad — a meta.route field without an id field:
- * states: {
- *   profile: {
- *     meta: { route: "/profile/:username" },
- *     // ← the id: "profile" field is absent
- *   }
- * }
- *
- * // Good:
- * states: {
- *   profile: {
- *     id: "profile",
- *     meta: { route: "/profile/:username" },
- *   }
- * }
- * ```
- */
-export class MissingStateIdError extends PlayError {
-    /** The state key, which is the position in the tree of the states, without an explicit `id` field. */
-    stateKey;
-    /** The route template of the state, for example `"/profile/:username"`. */
-    route;
-    constructor(stateKey, route) {
-        super("formatPlayRouteTransitions", "PLAY_XSTATE_MISSING_STATE_ID", `State "${stateKey}" declares meta.route "${route}" but has no explicit id. ` +
-            `Add id: "${stateKey}" to the state config so play.route events can target it.`);
-        this.name = "MissingStateIdError";
-        this.stateKey = stateKey;
-        this.route = route;
-    }
-}
+* `formatPlayRouteTransitions()` throws this error when a state node declares a
+* `meta.route` field but no explicit `id` field.
+*
+* Without an `id`, the function can generate no `play.route` guard that targets the
+* state: the guard compares `event.to` with `#<id>`. An absent `id` therefore makes
+* the state unreachable through the routing, and nothing says so. This error shows
+* the fault of the configuration at the moment of the machine definition, and the
+* function skips no state in silence.
+*
+* **Error code:** `PLAY_XSTATE_MISSING_STATE_ID`
+*
+* @example
+* ```typescript
+* // Bad — a meta.route field without an id field:
+* states: {
+*   profile: {
+*     meta: { route: "/profile/:username" },
+*     // ← the id: "profile" field is absent
+*   }
+* }
+*
+* // Good:
+* states: {
+*   profile: {
+*     id: "profile",
+*     meta: { route: "/profile/:username" },
+*   }
+* }
+* ```
+*/
+var MissingStateIdError = class extends PlayError {
+	/** The state key, which is the position in the tree of the states, without an explicit `id` field. */
+	stateKey;
+	/** The route template of the state, for example `"/profile/:username"`. */
+	route;
+	constructor(stateKey, route) {
+		super("formatPlayRouteTransitions", "PLAY_XSTATE_MISSING_STATE_ID", `State "${stateKey}" declares meta.route "${route}" but has no explicit id. Add id: "${stateKey}" to the state config so play.route events can target it.`);
+		this.name = "MissingStateIdError";
+		this.stateKey = stateKey;
+		this.route = route;
+	}
+};
 /**
- * The `PlayerActor` constructor throws this error when the `machine` argument is not
- * a valid XState machine object, which means that it is null, undefined, or not an
- * object.
- *
- * **Error code:** `PLAY_XSTATE_INVALID_MACHINE`
- */
-export class InvalidMachineError extends PlayError {
-    constructor() {
-        super("PlayerActor", "PLAY_XSTATE_INVALID_MACHINE", "PlayerActor requires a valid XState machine");
-        this.name = "InvalidMachineError";
-    }
-}
+* The `PlayerActor` constructor throws this error when the `machine` argument is not
+* a valid XState machine object, which means that it is null, undefined, or not an
+* object.
+*
+* **Error code:** `PLAY_XSTATE_INVALID_MACHINE`
+*/
+var InvalidMachineError = class extends PlayError {
+	constructor() {
+		super("PlayerActor", "PLAY_XSTATE_INVALID_MACHINE", "PlayerActor requires a valid XState machine");
+		this.name = "InvalidMachineError";
+	}
+};
 /**
- * `normalizeRoute()` throws this error when the `meta.route` value of a state is not
- * a string and not an object with a `path` property.
- *
- * **Error code:** `PLAY_XSTATE_INVALID_ROUTE_METADATA`
- */
-export class InvalidRouteMetadataError extends PlayError {
-    /** The invalid route value, as a string, for the debug work. */
-    detail;
-    constructor(route, source = "deriveRoute") {
-        const detail = describeValue(route);
-        super(source, "PLAY_XSTATE_INVALID_ROUTE_METADATA", `Invalid route metadata: ${detail}. Expected string or { path: string }`);
-        this.name = "InvalidRouteMetadataError";
-        this.detail = detail;
-    }
-}
+* `normalizeRoute()` throws this error when the `meta.route` value of a state is not
+* a string and not an object with a `path` property.
+*
+* **Error code:** `PLAY_XSTATE_INVALID_ROUTE_METADATA`
+*/
+var InvalidRouteMetadataError = class extends PlayError {
+	/** The invalid route value, as a string, for the debug work. */
+	detail;
+	constructor(route, source = "deriveRoute") {
+		const detail = describeValue(route);
+		super(source, "PLAY_XSTATE_INVALID_ROUTE_METADATA", `Invalid route metadata: ${detail}. Expected string or { path: string }`);
+		this.name = "InvalidRouteMetadataError";
+		this.detail = detail;
+	}
+};
 /**
- * `formatPlayRouteTransitions()` throws this error for a `meta.route` object whose
- * `handler` field holds a value that the routing layer does not know.
- *
- * The field decides WHERE the generated `play.route` transition sits, and each value
- * produces a different reachability. `"local"` in particular makes a state reachable
- * only while its parent is active. A typo such as `"locale"` would therefore fall back
- * to a placement that the author did not ask for, and the route would behave correctly
- * in the test that the author wrote and wrongly everywhere else. The error refuses the
- * value instead.
- *
- * **Error code:** `PLAY_XSTATE_INVALID_ROUTE_HANDLER`
- *
- * @example
- * ```typescript
- * import { InvalidRouteHandlerError } from "@xmachines/play-xstate/errors";
- *
- * try {
- *   formatPlayRouteTransitions(config);
- * } catch (error) {
- *   if (error instanceof InvalidRouteHandlerError) {
- *     console.error(error.handler); // the value that the config declared
- *   }
- * }
- * ```
- */
-export class InvalidRouteHandlerError extends PlayError {
-    /** The value that the config declared, as a string, for the debug work. */
-    handler;
-    constructor(handler, source = "formatPlayRouteTransitions") {
-        const detail = describeValue(handler);
-        super(source, "PLAY_XSTATE_INVALID_ROUTE_HANDLER", `Invalid route handler: ${detail}. Expected "root", "local", or "both"`);
-        this.name = "InvalidRouteHandlerError";
-        this.handler = detail;
-    }
-}
+* `formatPlayRouteTransitions()` throws this error for a `meta.route` object whose
+* `handler` field holds a value that the routing layer does not know.
+*
+* The field decides WHERE the generated `play.route` transition sits, and each value
+* produces a different reachability. `"local"` in particular makes a state reachable
+* only while its parent is active. A typo such as `"locale"` would therefore fall back
+* to a placement that the author did not ask for, and the route would behave correctly
+* in the test that the author wrote and wrongly everywhere else. The error refuses the
+* value instead.
+*
+* **Error code:** `PLAY_XSTATE_INVALID_ROUTE_HANDLER`
+*
+* @example
+* ```typescript
+* import { InvalidRouteHandlerError } from "@xmachines/play-xstate/errors";
+*
+* try {
+*   formatPlayRouteTransitions(config);
+* } catch (error) {
+*   if (error instanceof InvalidRouteHandlerError) {
+*     console.error(error.handler); // the value that the config declared
+*   }
+* }
+* ```
+*/
+var InvalidRouteHandlerError = class extends PlayError {
+	/** The value that the config declared, as a string, for the debug work. */
+	handler;
+	constructor(handler, source = "formatPlayRouteTransitions") {
+		const detail = describeValue(handler);
+		super(source, "PLAY_XSTATE_INVALID_ROUTE_HANDLER", `Invalid route handler: ${detail}. Expected "root", "local", or "both"`);
+		this.name = "InvalidRouteHandlerError";
+		this.handler = detail;
+	}
+};
 /**
- * `PlayerActor.send()` throws this error when the event argument is not a plain
- * object.
- *
- * A `PlayEvent` needs the shape `{ type: string, ...fields }`. A `null` value, an
- * `undefined` value, a string, and every other value that is not an object are an
- * error of the programmer.
- *
- * The error holds the value in question in its readonly class field `detail`, for
- * the debug work. A TypeScript consumer reads `err.detail` directly, with no unsafe
- * cast.
- *
- * **Error code:** `PLAY_XSTATE_INVALID_EVENT`
- *
- * @example
- * ```typescript
- * import { InvalidEventError } from "@xmachines/play-xstate/errors";
- *
- * try {
- *   actor.send(null as any);
- * } catch (err) {
- *   if (err instanceof InvalidEventError) {
- *     // err.detail has the type `unknown`, and it needs no cast
- *     console.error("Invalid event passed to actor.send():", err.detail);
- *   }
- * }
- * ```
- */
-export class InvalidEventError extends PlayError {
-    /** The value in question, from the `send()` call. */
-    detail;
-    constructor(detail) {
-        super("PlayerActor", "PLAY_XSTATE_INVALID_EVENT", "PlayerActor.send() received a non-object event.");
-        this.name = "InvalidEventError";
-        this.detail = detail;
-    }
-}
+* `PlayerActor.send()` throws this error when the event argument is not a plain
+* object.
+*
+* A `PlayEvent` needs the shape `{ type: string, ...fields }`. A `null` value, an
+* `undefined` value, a string, and every other value that is not an object are an
+* error of the programmer.
+*
+* The error holds the value in question in its readonly class field `detail`, for
+* the debug work. A TypeScript consumer reads `err.detail` directly, with no unsafe
+* cast.
+*
+* **Error code:** `PLAY_XSTATE_INVALID_EVENT`
+*
+* @example
+* ```typescript
+* import { InvalidEventError } from "@xmachines/play-xstate/errors";
+*
+* try {
+*   actor.send(null as any);
+* } catch (err) {
+*   if (err instanceof InvalidEventError) {
+*     // err.detail has the type `unknown`, and it needs no cast
+*     console.error("Invalid event passed to actor.send():", err.detail);
+*   }
+* }
+* ```
+*/
+var InvalidEventError = class extends PlayError {
+	/** The value in question, from the `send()` call. */
+	detail;
+	constructor(detail) {
+		super("PlayerActor", "PLAY_XSTATE_INVALID_EVENT", "PlayerActor.send() received a non-object event.");
+		this.name = "InvalidEventError";
+		this.detail = detail;
+	}
+};
 /**
- * The actor gives this error to `PlayerOptions.onError` when it failed with a value
- * that is not an `Error`, for example after a machine action ran
- * `throw { code: 42 }`.
- *
- * An actor error that *is* an `Error` reaches `onError` without a change, and it
- * keeps the identity of the machine. This case alone builds a new error. The new
- * error therefore carries a code that your code can match, and not a
- * `String(value)` message such as `"[object Object]"`. The `cause` field holds the
- * value from the throw.
- *
- * **Error code:** `PLAY_XSTATE_NON_ERROR_THROWN`
- *
- * @example
- * ```typescript
- * import { ActorThrewNonErrorError } from "@xmachines/play-xstate/errors";
- *
- * definePlayer({
- *   machine,
- *   options: {
- *     onError: (actor, err) => {
- *       if (err instanceof ActorThrewNonErrorError) {
- *         // err.cause is the value that the machine threw
- *         console.error("Machine threw a non-Error:", err.cause);
- *       }
- *     },
- *   },
- * });
- * ```
- */
-export class ActorThrewNonErrorError extends PlayError {
-    constructor(value) {
-        super("PlayerActor", "PLAY_XSTATE_NON_ERROR_THROWN", `PlayerActor failed with a non-Error value: ${safeString(value)}.`, { cause: value });
-        this.name = "ActorThrewNonErrorError";
-    }
-}
+* The actor gives this error to `PlayerOptions.onError` when it failed with a value
+* that is not an `Error`, for example after a machine action ran
+* `throw { code: 42 }`.
+*
+* An actor error that *is* an `Error` reaches `onError` without a change, and it
+* keeps the identity of the machine. This case alone builds a new error. The new
+* error therefore carries a code that your code can match, and not a
+* `String(value)` message such as `"[object Object]"`. The `cause` field holds the
+* value from the throw.
+*
+* **Error code:** `PLAY_XSTATE_NON_ERROR_THROWN`
+*
+* @example
+* ```typescript
+* import { ActorThrewNonErrorError } from "@xmachines/play-xstate/errors";
+*
+* definePlayer({
+*   machine,
+*   options: {
+*     onError: (actor, err) => {
+*       if (err instanceof ActorThrewNonErrorError) {
+*         // err.cause is the value that the machine threw
+*         console.error("Machine threw a non-Error:", err.cause);
+*       }
+*     },
+*   },
+* });
+* ```
+*/
+var ActorThrewNonErrorError = class extends PlayError {
+	constructor(value) {
+		super("PlayerActor", "PLAY_XSTATE_NON_ERROR_THROWN", `PlayerActor failed with a non-Error value: ${safeString(value)}.`, { cause: value });
+		this.name = "ActorThrewNonErrorError";
+	}
+};
+//#endregion
+export { ActorThrewNonErrorError, InvalidEventError, InvalidMachineError, InvalidRouteHandlerError, InvalidRouteMetadataError, InvalidRouteParamError, MissingRouteParamError, MissingStateIdError };
+
 //# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"errors.js","names":[],"sources":["../src/errors.ts"],"sourcesContent":["import { PlayError } from \"@xmachines/play/errors\";\nimport { describeValue, safeString } from \"@xmachines/core/utils\";\n\n/**\n * `buildRouteUrl()` throws this error when the context of the actor does not hold a\n * necessary route parameter.\n *\n * Read the `param` field and the `template` field to identify the parameter that is\n * absent. Your code therefore parses no `.message` string.\n *\n * **Error code:** `PLAY_XSTATE_ROUTE_PARAM_MISSING`\n *\n * Note: `actor.currentRoute.get()` shows this error never. The route derivation\n * catches it, and it returns `null` for the temporary case during a transition. The\n * error leaves a direct `buildRouteUrl()` call only.\n *\n * @example\n * ```typescript\n * import { buildRouteUrl } from \"@xmachines/play-xstate/routing\";\n * import { MissingRouteParamError } from \"@xmachines/play-xstate/errors\";\n *\n * try {\n *   buildRouteUrl(\"/profile/:userId\", { params: {}, query: {} });\n * } catch (err) {\n *   if (err instanceof MissingRouteParamError) {\n *     console.error(\n *       `Missing \"${err.param}\" for template \"${err.template}\"`\n *     );\n *   }\n * }\n * ```\n */\nexport class MissingRouteParamError extends PlayError {\n\t/** The name of the route parameter that was absent, for example `\"userId\"`. */\n\treadonly param: string;\n\n\t/** The route template that needs the absent parameter, for example `\"/profile/:userId\"`. */\n\treadonly template: string;\n\n\tconstructor(param: string, template: string) {\n\t\tsuper(\n\t\t\t\"buildRouteUrl\",\n\t\t\t\"PLAY_XSTATE_ROUTE_PARAM_MISSING\",\n\t\t\t`Route parameter '${param}' is required by template '${template}' but was not found in context.`,\n\t\t);\n\t\tthis.name = \"MissingRouteParamError\";\n\t\tthis.param = param;\n\t\tthis.template = template;\n\t}\n}\n\n/**\n * `buildRouteUrl()` throws this error when a route parameter carries a value that no path\n * can hold, so the template matches the built URL back never.\n *\n * A dot segment is that value. A URL parser resolves `.` and `..` BEFORE it decodes the\n * percent escapes, and it counts `%2e` as the dot, so every encoding of them resolves\n * away: `/files/..` becomes `/`. The actor would hold the route `/files/..` while the\n * address bar shows `/`, and the two stay out of step for the rest of the session.\n *\n * Give the param a value that names a segment. Machine state that can carry a path from a\n * user belongs behind a check of its own, in the same way that a base path checks the\n * values of its `:param` segments.\n *\n * **Error code:** `PLAY_XSTATE_ROUTE_PARAM_INVALID`\n *\n * @example\n * ```typescript\n * import { buildRouteUrl } from \"@xmachines/play-xstate/routing\";\n * import { InvalidRouteParamError } from \"@xmachines/play-xstate/errors\";\n *\n * try {\n *   buildRouteUrl(\"/files/:name\", { params: { name: \"..\" }, query: {} });\n * } catch (err) {\n *   if (err instanceof InvalidRouteParamError) {\n *     console.error(`\"${err.value}\" cannot stand in \"${err.param}\"`);\n *   }\n * }\n * ```\n */\nexport class InvalidRouteParamError extends PlayError {\n\t/** The name of the route parameter that carries the value, for example `\"name\"`. */\n\treadonly param: string;\n\n\t/** The value that no path can hold, for example `\"..\"`. */\n\treadonly value: string;\n\n\t/** The route template that declares the parameter, for example `\"/files/:name\"`. */\n\treadonly template: string;\n\n\tconstructor(param: string, value: string, template: string) {\n\t\tsuper(\n\t\t\t\"buildRouteUrl\",\n\t\t\t\"PLAY_XSTATE_ROUTE_PARAM_INVALID\",\n\t\t\t`Route parameter '${param}' of template '${template}' carries the value '${value}', which resolves away in a URL.`,\n\t\t);\n\t\tthis.name = \"InvalidRouteParamError\";\n\t\tthis.param = param;\n\t\tthis.value = value;\n\t\tthis.template = template;\n\t}\n}\n\n/**\n * `formatPlayRouteTransitions()` throws this error when a state node declares a\n * `meta.route` field but no explicit `id` field.\n *\n * Without an `id`, the function can generate no `play.route` guard that targets the\n * state: the guard compares `event.to` with `#<id>`. An absent `id` therefore makes\n * the state unreachable through the routing, and nothing says so. This error shows\n * the fault of the configuration at the moment of the machine definition, and the\n * function skips no state in silence.\n *\n * **Error code:** `PLAY_XSTATE_MISSING_STATE_ID`\n *\n * @example\n * ```typescript\n * // Bad — a meta.route field without an id field:\n * states: {\n *   profile: {\n *     meta: { route: \"/profile/:username\" },\n *     // ← the id: \"profile\" field is absent\n *   }\n * }\n *\n * // Good:\n * states: {\n *   profile: {\n *     id: \"profile\",\n *     meta: { route: \"/profile/:username\" },\n *   }\n * }\n * ```\n */\nexport class MissingStateIdError extends PlayError {\n\t/** The state key, which is the position in the tree of the states, without an explicit `id` field. */\n\treadonly stateKey: string;\n\t/** The route template of the state, for example `\"/profile/:username\"`. */\n\treadonly route: string;\n\n\tconstructor(stateKey: string, route: string) {\n\t\tsuper(\n\t\t\t\"formatPlayRouteTransitions\",\n\t\t\t\"PLAY_XSTATE_MISSING_STATE_ID\",\n\t\t\t`State \"${stateKey}\" declares meta.route \"${route}\" but has no explicit id. ` +\n\t\t\t\t`Add id: \"${stateKey}\" to the state config so play.route events can target it.`,\n\t\t);\n\t\tthis.name = \"MissingStateIdError\";\n\t\tthis.stateKey = stateKey;\n\t\tthis.route = route;\n\t}\n}\n\n/**\n * The `PlayerActor` constructor throws this error when the `machine` argument is not\n * a valid XState machine object, which means that it is null, undefined, or not an\n * object.\n *\n * **Error code:** `PLAY_XSTATE_INVALID_MACHINE`\n */\nexport class InvalidMachineError extends PlayError {\n\tconstructor() {\n\t\tsuper(\n\t\t\t\"PlayerActor\",\n\t\t\t\"PLAY_XSTATE_INVALID_MACHINE\",\n\t\t\t\"PlayerActor requires a valid XState machine\",\n\t\t);\n\t\tthis.name = \"InvalidMachineError\";\n\t}\n}\n\n/**\n * `normalizeRoute()` throws this error when the `meta.route` value of a state is not\n * a string and not an object with a `path` property.\n *\n * **Error code:** `PLAY_XSTATE_INVALID_ROUTE_METADATA`\n */\nexport class InvalidRouteMetadataError extends PlayError {\n\t/** The invalid route value, as a string, for the debug work. */\n\treadonly detail: string;\n\n\tconstructor(route: unknown, source = \"deriveRoute\") {\n\t\tconst detail = describeValue(route);\n\t\tsuper(\n\t\t\tsource,\n\t\t\t\"PLAY_XSTATE_INVALID_ROUTE_METADATA\",\n\t\t\t`Invalid route metadata: ${detail}. Expected string or { path: string }`,\n\t\t);\n\t\tthis.name = \"InvalidRouteMetadataError\";\n\t\tthis.detail = detail;\n\t}\n}\n\n/**\n * `formatPlayRouteTransitions()` throws this error for a `meta.route` object whose\n * `handler` field holds a value that the routing layer does not know.\n *\n * The field decides WHERE the generated `play.route` transition sits, and each value\n * produces a different reachability. `\"local\"` in particular makes a state reachable\n * only while its parent is active. A typo such as `\"locale\"` would therefore fall back\n * to a placement that the author did not ask for, and the route would behave correctly\n * in the test that the author wrote and wrongly everywhere else. The error refuses the\n * value instead.\n *\n * **Error code:** `PLAY_XSTATE_INVALID_ROUTE_HANDLER`\n *\n * @example\n * ```typescript\n * import { InvalidRouteHandlerError } from \"@xmachines/play-xstate/errors\";\n *\n * try {\n *   formatPlayRouteTransitions(config);\n * } catch (error) {\n *   if (error instanceof InvalidRouteHandlerError) {\n *     console.error(error.handler); // the value that the config declared\n *   }\n * }\n * ```\n */\nexport class InvalidRouteHandlerError extends PlayError {\n\t/** The value that the config declared, as a string, for the debug work. */\n\treadonly handler: string;\n\n\tconstructor(handler: unknown, source = \"formatPlayRouteTransitions\") {\n\t\tconst detail = describeValue(handler);\n\t\tsuper(\n\t\t\tsource,\n\t\t\t\"PLAY_XSTATE_INVALID_ROUTE_HANDLER\",\n\t\t\t`Invalid route handler: ${detail}. Expected \"root\", \"local\", or \"both\"`,\n\t\t);\n\t\tthis.name = \"InvalidRouteHandlerError\";\n\t\tthis.handler = detail;\n\t}\n}\n\n/**\n * `PlayerActor.send()` throws this error when the event argument is not a plain\n * object.\n *\n * A `PlayEvent` needs the shape `{ type: string, ...fields }`. A `null` value, an\n * `undefined` value, a string, and every other value that is not an object are an\n * error of the programmer.\n *\n * The error holds the value in question in its readonly class field `detail`, for\n * the debug work. A TypeScript consumer reads `err.detail` directly, with no unsafe\n * cast.\n *\n * **Error code:** `PLAY_XSTATE_INVALID_EVENT`\n *\n * @example\n * ```typescript\n * import { InvalidEventError } from \"@xmachines/play-xstate/errors\";\n *\n * try {\n *   actor.send(null as any);\n * } catch (err) {\n *   if (err instanceof InvalidEventError) {\n *     // err.detail has the type `unknown`, and it needs no cast\n *     console.error(\"Invalid event passed to actor.send():\", err.detail);\n *   }\n * }\n * ```\n */\nexport class InvalidEventError extends PlayError {\n\t/** The value in question, from the `send()` call. */\n\treadonly detail: unknown;\n\n\tconstructor(detail: unknown) {\n\t\tsuper(\n\t\t\t\"PlayerActor\",\n\t\t\t\"PLAY_XSTATE_INVALID_EVENT\",\n\t\t\t\"PlayerActor.send() received a non-object event.\",\n\t\t);\n\t\tthis.name = \"InvalidEventError\";\n\t\tthis.detail = detail;\n\t}\n}\n\n/**\n * The actor gives this error to `PlayerOptions.onError` when it failed with a value\n * that is not an `Error`, for example after a machine action ran\n * `throw { code: 42 }`.\n *\n * An actor error that *is* an `Error` reaches `onError` without a change, and it\n * keeps the identity of the machine. This case alone builds a new error. The new\n * error therefore carries a code that your code can match, and not a\n * `String(value)` message such as `\"[object Object]\"`. The `cause` field holds the\n * value from the throw.\n *\n * **Error code:** `PLAY_XSTATE_NON_ERROR_THROWN`\n *\n * @example\n * ```typescript\n * import { ActorThrewNonErrorError } from \"@xmachines/play-xstate/errors\";\n *\n * definePlayer({\n *   machine,\n *   options: {\n *     onError: (actor, err) => {\n *       if (err instanceof ActorThrewNonErrorError) {\n *         // err.cause is the value that the machine threw\n *         console.error(\"Machine threw a non-Error:\", err.cause);\n *       }\n *     },\n *   },\n * });\n * ```\n */\nexport class ActorThrewNonErrorError extends PlayError {\n\tconstructor(value: unknown) {\n\t\tsuper(\n\t\t\t\"PlayerActor\",\n\t\t\t\"PLAY_XSTATE_NON_ERROR_THROWN\",\n\t\t\t`PlayerActor failed with a non-Error value: ${safeString(value)}.`,\n\t\t\t{ cause: value },\n\t\t);\n\t\tthis.name = \"ActorThrewNonErrorError\";\n\t}\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgCA,IAAa,yBAAb,cAA4C,UAAU;;CAErD;;CAGA;CAEA,YAAY,OAAe,UAAkB;EAC5C,MACC,iBACA,mCACA,oBAAoB,MAAM,6BAA6B,SAAS,gCACjE;EACA,KAAK,OAAO;EACZ,KAAK,QAAQ;EACb,KAAK,WAAW;CACjB;AACD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA+BA,IAAa,yBAAb,cAA4C,UAAU;;CAErD;;CAGA;;CAGA;CAEA,YAAY,OAAe,OAAe,UAAkB;EAC3D,MACC,iBACA,mCACA,oBAAoB,MAAM,iBAAiB,SAAS,uBAAuB,MAAM,iCAClF;EACA,KAAK,OAAO;EACZ,KAAK,QAAQ;EACb,KAAK,QAAQ;EACb,KAAK,WAAW;CACjB;AACD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiCA,IAAa,sBAAb,cAAyC,UAAU;;CAElD;;CAEA;CAEA,YAAY,UAAkB,OAAe;EAC5C,MACC,8BACA,gCACA,UAAU,SAAS,yBAAyB,MAAM,qCACrC,SAAS,0DACvB;EACA,KAAK,OAAO;EACZ,KAAK,WAAW;EAChB,KAAK,QAAQ;CACd;AACD;;;;;;;;AASA,IAAa,sBAAb,cAAyC,UAAU;CAClD,cAAc;EACb,MACC,eACA,+BACA,6CACD;EACA,KAAK,OAAO;CACb;AACD;;;;;;;AAQA,IAAa,4BAAb,cAA+C,UAAU;;CAExD;CAEA,YAAY,OAAgB,SAAS,eAAe;EACnD,MAAM,SAAS,cAAc,KAAK;EAClC,MACC,QACA,sCACA,2BAA2B,OAAO,sCACnC;EACA,KAAK,OAAO;EACZ,KAAK,SAAS;CACf;AACD;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4BA,IAAa,2BAAb,cAA8C,UAAU;;CAEvD;CAEA,YAAY,SAAkB,SAAS,8BAA8B;EACpE,MAAM,SAAS,cAAc,OAAO;EACpC,MACC,QACA,qCACA,0BAA0B,OAAO,sCAClC;EACA,KAAK,OAAO;EACZ,KAAK,UAAU;CAChB;AACD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8BA,IAAa,oBAAb,cAAuC,UAAU;;CAEhD;CAEA,YAAY,QAAiB;EAC5B,MACC,eACA,6BACA,iDACD;EACA,KAAK,OAAO;EACZ,KAAK,SAAS;CACf;AACD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgCA,IAAa,0BAAb,cAA6C,UAAU;CACtD,YAAY,OAAgB;EAC3B,MACC,eACA,gCACA,8CAA8C,WAAW,KAAK,EAAE,IAChE,EAAE,OAAO,MAAM,CAChB;EACA,KAAK,OAAO;CACb;AACD"}

package/dist/index.js

@@ -1,25 +1,4 @@
-/**
- * @xmachines/play-xstate - the XState v5 adapter of the Play Architecture
- *
- * This package gives you the definePlayer() API. That function binds an XState state
- * machine to the actor base, with the atom lifecycle and the DevTools
- * integration.
- *
- * The Play RFC gives this package as the adapter of the logic layer. It converts a
- * declarative machine definition into a live actor with an atom-driven
- * reactivity.
- *
- * @packageDocumentation
- */
-export { definePlayer } from "./define-player.js";
-export { PlayerActor } from "./player-actor.js";
-// The composition of the capabilities. Each capability itself lives behind its own entry
-// point — `@xmachines/play-xstate/routing` and `@xmachines/play-xstate/view` — so this
-// module imports neither, and an application loads only what it composes.
-export { compose } from "./capabilities.js";
-// The routing utilities live behind `@xmachines/play-xstate/routing`, with the mixin
-// that needs them: `deriveRoute`, `isAbsoluteRoute`, `buildRouteUrl`,
-// `formatPlayRouteTransitions`, and the route types. Each one names
-// `@xmachines/play-router` in its `.d.ts`, and that package is an OPTIONAL peer. This
-// entry therefore names no capability package, exactly as the view half does.
-//# sourceMappingURL=index.js.map
+import { PlayerActor } from "./player-actor.js";
+import { definePlayer } from "./define-player.js";
+import { compose } from "./capabilities.js";
+export { PlayerActor, compose, definePlayer };