@xmachines/play-xstate 2.0.0-alpha.1 → 2.1.0

package/dist/errors.d.ts

@@ -1,23 +1,24 @@
 import { PlayError } from "@xmachines/play";
 /**
- * Thrown by `buildRouteUrl()` when a required route parameter is absent from the
- * actor's context.
+ * `buildRouteUrl()` throws this error when the context of the actor does not hold a
+ * necessary route parameter.
  *
- * Use the `param` and `template` fields to identify the missing parameter without
- * parsing the `.message` string.
+ * 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";
  * import { MissingRouteParamError } from "@xmachines/play-xstate/errors";
  *
- * // The route template "/profile/:userId" requires "userId" in context.
- * // If userId is absent, MissingRouteParamError is thrown when the
- * // actor.currentRoute signal is read.
- *
  * try {
- *   actor.currentRoute.get();
+ *   buildRouteUrl("/profile/:userId", { params: {}, query: {} });
  * } catch (err) {
  *   if (err instanceof MissingRouteParamError) {
  *     console.error(
@@ -28,65 +29,48 @@ import { PlayError } from "@xmachines/play";
  * ```
  */
 export declare class MissingRouteParamError extends PlayError {
-    /** The name of the route parameter that was missing (e.g. `"userId"`). */
+    /** The name of the route parameter that was absent, for example `"userId"`. */
     readonly param: string;
-    /** The route template that required the missing parameter (e.g. `"/profile/:userId"`). */
+    /** The route template that needs the absent parameter, for example `"/profile/:userId"`. */
     readonly template: string;
     constructor(param: string, template: string);
 }
 /**
- * Thrown by `buildRouteUrl()` when the context has a `params` field (indicating a
- * routing-aware machine context) but no `query` field.
- *
- * The `params` field signals the context was set up for routing (either manually or via
- * `formatPlayRouteTransitions`). A routing-aware context without `query` will silently
- * drop any query parameters carried by `play.route` events, producing incorrect URLs.
+ * @deprecated Nothing throws this error now. `buildRouteUrl` reads an absent `query`
+ * field as `query: {}`. The generated `play.route` transitions assign `query` on
+ * every navigation, and the loss that this error guarded against therefore cannot
+ * happen through the route derivation. A machine that handles `play.route` itself
+ * and wants the query must assign `event.query` to its context itself. This class
+ * stays in the exports, so that an `instanceof` handler that exists now still
+ * compiles. Remove such a handler when you have the time.
  *
- * **Fix:** Ensure the machine context type includes `query: Record<string, string>`
- * and that the context initializer sets `query: {}` (or a populated value).
- * If using `formatPlayRouteTransitions`, the field is assigned automatically on each
- * `play.route` event — but the machine's initial context must still declare it.
+ * `buildRouteUrl()` threw this error before, when the context had a `params` field,
+ * which means a context that knows the routing, but no `query` field.
  *
  * **Error code:** `PLAY_XSTATE_MISSING_QUERY_CONTEXT`
- *
- * @example
- * ```typescript
- * import { MissingQueryContextError } from "@xmachines/play-xstate/errors";
- *
- * try {
- *   // params present but no query field — throws
- *   buildRouteUrl("/profile/:userId", { params: { userId: "42" } });
- * } catch (err) {
- *   if (err instanceof MissingQueryContextError) {
- *     console.error("Machine context missing query field");
- *   }
- * }
- *
- * // Correct — both params and query declared
- * buildRouteUrl("/profile/:userId", { params: { userId: "42" }, query: {} });
- * ```
  */
 export declare class MissingQueryContextError extends PlayError {
     constructor();
 }
 /**
- * Thrown by `formatPlayRouteTransitions()` when a state node declares `meta.route`
- * but omits an explicit `id`.
+ * `formatPlayRouteTransitions()` throws this error when a state node declares a
+ * `meta.route` field but no explicit `id` field.
  *
- * Without `id`, the function cannot generate a `play.route` guard that targets the
- * state — the guard compares `event.to` against `#<id>`, so a missing `id` means
- * the state is silently unreachable via routing. This error surfaces the
- * misconfiguration at machine-definition time rather than silently skipping the state.
+ * 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 — meta.route without id:
+ * // Bad — a meta.route field without an id field:
  * states: {
  *   profile: {
  *     meta: { route: "/profile/:username" },
- *     // ← missing id: "profile"
+ *     // ← the id: "profile" field is absent
  *   }
  * }
  *
@@ -100,15 +84,16 @@ export declare class MissingQueryContextError extends PlayError {
  * ```
  */
 export declare class MissingStateIdError extends PlayError {
-    /** The state key (position in the states tree) that is missing an explicit `id`. */
+    /** The state key, which is the position in the tree of the states, without an explicit `id` field. */
     readonly stateKey: string;
-    /** The route template declared on the state (e.g. `"/profile/:username"`). */
+    /** The route template of the state, for example `"/profile/:username"`. */
     readonly route: string;
     constructor(stateKey: string, route: string);
 }
 /**
- * Thrown by the `PlayerActor` constructor when the `machine` argument is not a
- * valid XState machine object (null, undefined, or a non-object).
+ * 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`
  */
@@ -116,73 +101,38 @@ export declare class InvalidMachineError extends PlayError {
     constructor();
 }
 /**
- * Thrown by `normalizeRoute()` when a state's `meta.route` value is neither a
- * string nor an object with a `path` property.
+ * `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 declare class InvalidRouteMetadataError extends PlayError {
-    /** The serialised form of the invalid route value for debugging. */
+    /** The invalid route value, as a string, for the debug work. */
     readonly detail: string;
     constructor(route: unknown, source?: string);
 }
 /**
- * Thrown by `composeGuards()` or `composeGuardsOr()` when called with an empty
- * guards array. A composition of zero guards has no meaningful semantics.
+ * `composeGuards()` and `composeGuardsOr()` throw this error for an empty array of
+ * guards. A composition of zero guards has no meaning.
  *
  * **Error code:** `PLAY_XSTATE_EMPTY_GUARD_ARRAY`
  */
 export declare class EmptyGuardArrayError extends PlayError {
-    /** The combinator that was called with an empty array (`"and"` or `"or"`). */
+    /** The combinator of the call with the empty array: `"and"` or `"or"`. */
     readonly combinator: "and" | "or";
     constructor(combinator: "and" | "or");
 }
 /**
- * The guard-composition helper a composed guard was built by. Threaded into
- * guard errors so `PlayError.scope` names the actual origin.
- */
-export type GuardCombinator = "composeGuards" | "composeGuardsOr" | "negateGuard";
-/**
- * Thrown when a composed guard cannot resolve a string guard name at call time.
- *
- * String names in `composeGuards`/`composeGuardsOr`/`negateGuard` resolve
- * against `args.guards` — the named guards from `setup({ guards })` that
- * XState v6 provides to transition functions, `always`, entry/exit actions
- * (since 6.0.0-alpha.20), and function-form route resolvers. Resolution fails
- * when the name was never declared or when the composed guard is called
- * without transition arguments.
- *
- * **Error code:** `PLAY_XSTATE_UNRESOLVABLE_GUARD_NAME`
- */
-export declare class UnresolvableGuardNameError extends PlayError {
-    /** The guard name that could not be resolved. */
-    readonly guardName: string;
-    constructor(guardName: string, origin: GuardCombinator);
-}
-/**
- * Thrown when a composed guard evaluates an entry that is neither a predicate
- * function nor a guard name — typically `null`/`undefined` from a typo'd
- * import or an optional lookup.
+ * `PlayerActor.send()` throws this error when the event argument is not a plain
+ * object.
  *
- * XState v5 failed loudly when evaluating such entries; silently treating them
- * as never-passing would turn `negateGuard(undefined)` into an always-allow.
- * Composition stays lazy (no throw at compose time); evaluation throws.
+ * 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.
  *
- * **Error code:** `PLAY_XSTATE_INVALID_GUARD_ENTRY`
- */
-export declare class InvalidGuardEntryError extends PlayError {
-    /** `typeof` of the invalid entry (e.g. `"undefined"`, `"object"` for null). */
-    readonly entryType: string;
-    constructor(entryType: string, origin: GuardCombinator);
-}
-/**
- * Thrown by `PlayerActor.send()` when the event argument is not a plain object.
- *
- * `PlayEvent` requires `{ type: string, ...fields }`. Passing `null`, `undefined`,
- * a string, or any other non-object value is a programmer error.
- *
- * The offending value is attached as the `detail` readonly class field for debugging.
- * TypeScript consumers can access `err.detail` directly without any unsafe cast.
+ * 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`
  *
@@ -194,15 +144,48 @@ export declare class InvalidGuardEntryError extends PlayError {
  *   actor.send(null as any);
  * } catch (err) {
  *   if (err instanceof InvalidEventError) {
- *     // err.detail is typed as `unknown` — no cast needed
+ *     // err.detail has the type `unknown`, and it needs no cast
  *     console.error("Invalid event passed to actor.send():", err.detail);
  *   }
  * }
  * ```
  */
 export declare class InvalidEventError extends PlayError {
-    /** The offending value passed to `send()`. */
+    /** The value in question, from the `send()` call. */
     readonly detail: unknown;
     constructor(detail: unknown);
 }
+/**
+ * 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 declare class ActorThrewNonErrorError extends PlayError {
+    constructor(value: unknown);
+}
 //# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAE5C;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,qBAAa,sBAAuB,SAAQ,SAAS;IACpD,0EAA0E;IAC1E,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAEvB,0FAA0F;IAC1F,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;gBAEd,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM;CAU3C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,qBAAa,wBAAyB,SAAQ,SAAS;;CAWtD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,qBAAa,mBAAoB,SAAQ,SAAS;IACjD,oFAAoF;IACpF,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,8EAA8E;IAC9E,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;gBAEX,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM;CAW3C;AAED;;;;;GAKG;AACH,qBAAa,mBAAoB,SAAQ,SAAS;;CASjD;AAED;;;;;GAKG;AACH,qBAAa,yBAA0B,SAAQ,SAAS;IACvD,oEAAoE;IACpE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAEZ,KAAK,EAAE,OAAO,EAAE,MAAM,SAAgB;CAUlD;AAED;;;;;GAKG;AACH,qBAAa,oBAAqB,SAAQ,SAAS;IAClD,8EAA8E;IAC9E,QAAQ,CAAC,UAAU,EAAE,KAAK,GAAG,IAAI,CAAC;gBAEtB,UAAU,EAAE,KAAK,GAAG,IAAI;CASpC;AAED;;;GAGG;AACH,MAAM,MAAM,eAAe,GAAG,eAAe,GAAG,iBAAiB,GAAG,aAAa,CAAC;AAElF;;;;;;;;;;;GAWG;AACH,qBAAa,0BAA2B,SAAQ,SAAS;IACxD,iDAAiD;IACjD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;gBAEf,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,eAAe;CAWtD;AAED;;;;;;;;;;GAUG;AACH,qBAAa,sBAAuB,SAAQ,SAAS;IACpD,+EAA+E;IAC/E,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;gBAEf,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,eAAe;CAWtD;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,qBAAa,iBAAkB,SAAQ,SAAS;IAC/C,8CAA8C;IAC9C,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;gBAEb,MAAM,EAAE,OAAO;CAS3B"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAsB5C;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,qBAAa,sBAAuB,SAAQ,SAAS;IACpD,+EAA+E;IAC/E,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAEvB,4FAA4F;IAC5F,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;gBAEd,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM;CAU3C;AAED;;;;;;;;;;;;;GAaG;AACH,qBAAa,wBAAyB,SAAQ,SAAS;;CAWtD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,qBAAa,mBAAoB,SAAQ,SAAS;IACjD,sGAAsG;IACtG,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,2EAA2E;IAC3E,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;gBAEX,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM;CAW3C;AAED;;;;;;GAMG;AACH,qBAAa,mBAAoB,SAAQ,SAAS;;CASjD;AAED;;;;;GAKG;AACH,qBAAa,yBAA0B,SAAQ,SAAS;IACvD,gEAAgE;IAChE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAEZ,KAAK,EAAE,OAAO,EAAE,MAAM,SAAgB;CAUlD;AAED;;;;;GAKG;AACH,qBAAa,oBAAqB,SAAQ,SAAS;IAClD,0EAA0E;IAC1E,QAAQ,CAAC,UAAU,EAAE,KAAK,GAAG,IAAI,CAAC;gBAEtB,UAAU,EAAE,KAAK,GAAG,IAAI;CASpC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,qBAAa,iBAAkB,SAAQ,SAAS;IAC/C,qDAAqD;IACrD,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;gBAEb,MAAM,EAAE,OAAO;CAS3B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,qBAAa,uBAAwB,SAAQ,SAAS;gBACzC,KAAK,EAAE,OAAO;CAS1B"}

package/dist/errors.js

@@ -1,23 +1,45 @@
 import { PlayError } from "@xmachines/play";
 /**
- * Thrown by `buildRouteUrl()` when a required route parameter is absent from the
- * actor's context.
+ * Converts a value from a throw into a string, and it trusts that value not:
+ * `String()` itself throws for an object with a null prototype, and also for a value
+ * whose `toString` or `Symbol.toPrimitive` throws. This function runs inside the
+ * error path. A second throw here therefore replaces the real failure of the machine
+ * with a `TypeError`, and it passes around `onError`.
+ */
+const safeString = (value) => {
+    try {
+        return String(value);
+    }
+    catch {
+        try {
+            return Object.prototype.toString.call(value);
+        }
+        catch {
+            // A revoked Proxy throws also on an inspection of the brand.
+            return "[unrepresentable value]";
+        }
+    }
+};
+/**
+ * `buildRouteUrl()` throws this error when the context of the actor does not hold a
+ * necessary route parameter.
  *
- * Use the `param` and `template` fields to identify the missing parameter without
- * parsing the `.message` string.
+ * 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";
  * import { MissingRouteParamError } from "@xmachines/play-xstate/errors";
  *
- * // The route template "/profile/:userId" requires "userId" in context.
- * // If userId is absent, MissingRouteParamError is thrown when the
- * // actor.currentRoute signal is read.
- *
  * try {
- *   actor.currentRoute.get();
+ *   buildRouteUrl("/profile/:userId", { params: {}, query: {} });
  * } catch (err) {
  *   if (err instanceof MissingRouteParamError) {
  *     console.error(
@@ -28,9 +50,9 @@ import { PlayError } from "@xmachines/play";
  * ```
  */
 export class MissingRouteParamError extends PlayError {
-    /** The name of the route parameter that was missing (e.g. `"userId"`). */
+    /** The name of the route parameter that was absent, for example `"userId"`. */
     param;
-    /** The route template that required the missing parameter (e.g. `"/profile/:userId"`). */
+    /** 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.`);
@@ -40,36 +62,18 @@ export class MissingRouteParamError extends PlayError {
     }
 }
 /**
- * Thrown by `buildRouteUrl()` when the context has a `params` field (indicating a
- * routing-aware machine context) but no `query` field.
- *
- * The `params` field signals the context was set up for routing (either manually or via
- * `formatPlayRouteTransitions`). A routing-aware context without `query` will silently
- * drop any query parameters carried by `play.route` events, producing incorrect URLs.
+ * @deprecated Nothing throws this error now. `buildRouteUrl` reads an absent `query`
+ * field as `query: {}`. The generated `play.route` transitions assign `query` on
+ * every navigation, and the loss that this error guarded against therefore cannot
+ * happen through the route derivation. A machine that handles `play.route` itself
+ * and wants the query must assign `event.query` to its context itself. This class
+ * stays in the exports, so that an `instanceof` handler that exists now still
+ * compiles. Remove such a handler when you have the time.
  *
- * **Fix:** Ensure the machine context type includes `query: Record<string, string>`
- * and that the context initializer sets `query: {}` (or a populated value).
- * If using `formatPlayRouteTransitions`, the field is assigned automatically on each
- * `play.route` event — but the machine's initial context must still declare it.
+ * `buildRouteUrl()` threw this error before, when the context had a `params` field,
+ * which means a context that knows the routing, but no `query` field.
  *
  * **Error code:** `PLAY_XSTATE_MISSING_QUERY_CONTEXT`
- *
- * @example
- * ```typescript
- * import { MissingQueryContextError } from "@xmachines/play-xstate/errors";
- *
- * try {
- *   // params present but no query field — throws
- *   buildRouteUrl("/profile/:userId", { params: { userId: "42" } });
- * } catch (err) {
- *   if (err instanceof MissingQueryContextError) {
- *     console.error("Machine context missing query field");
- *   }
- * }
- *
- * // Correct — both params and query declared
- * buildRouteUrl("/profile/:userId", { params: { userId: "42" }, query: {} });
- * ```
  */
 export class MissingQueryContextError extends PlayError {
     constructor() {
@@ -80,23 +84,24 @@ export class MissingQueryContextError extends PlayError {
     }
 }
 /**
- * Thrown by `formatPlayRouteTransitions()` when a state node declares `meta.route`
- * but omits an explicit `id`.
+ * `formatPlayRouteTransitions()` throws this error when a state node declares a
+ * `meta.route` field but no explicit `id` field.
  *
- * Without `id`, the function cannot generate a `play.route` guard that targets the
- * state — the guard compares `event.to` against `#<id>`, so a missing `id` means
- * the state is silently unreachable via routing. This error surfaces the
- * misconfiguration at machine-definition time rather than silently skipping the state.
+ * 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 — meta.route without id:
+ * // Bad — a meta.route field without an id field:
  * states: {
  *   profile: {
  *     meta: { route: "/profile/:username" },
- *     // ← missing id: "profile"
+ *     // ← the id: "profile" field is absent
  *   }
  * }
  *
@@ -110,9 +115,9 @@ export class MissingQueryContextError extends PlayError {
  * ```
  */
 export class MissingStateIdError extends PlayError {
-    /** The state key (position in the states tree) that is missing an explicit `id`. */
+    /** The state key, which is the position in the tree of the states, without an explicit `id` field. */
     stateKey;
-    /** The route template declared on the state (e.g. `"/profile/:username"`). */
+    /** 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. ` +
@@ -123,8 +128,9 @@ export class MissingStateIdError extends PlayError {
     }
 }
 /**
- * Thrown by the `PlayerActor` constructor when the `machine` argument is not a
- * valid XState machine object (null, undefined, or a non-object).
+ * 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`
  */
@@ -135,13 +141,13 @@ export class InvalidMachineError extends PlayError {
     }
 }
 /**
- * Thrown by `normalizeRoute()` when a state's `meta.route` value is neither a
- * string nor an object with a `path` property.
+ * `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 serialised form of the invalid route value for debugging. */
+    /** The invalid route value, as a string, for the debug work. */
     detail;
     constructor(route, source = "deriveRoute") {
         const detail = JSON.stringify(route);
@@ -151,13 +157,13 @@ export class InvalidRouteMetadataError extends PlayError {
     }
 }
 /**
- * Thrown by `composeGuards()` or `composeGuardsOr()` when called with an empty
- * guards array. A composition of zero guards has no meaningful semantics.
+ * `composeGuards()` and `composeGuardsOr()` throw this error for an empty array of
+ * guards. A composition of zero guards has no meaning.
  *
  * **Error code:** `PLAY_XSTATE_EMPTY_GUARD_ARRAY`
  */
 export class EmptyGuardArrayError extends PlayError {
-    /** The combinator that was called with an empty array (`"and"` or `"or"`). */
+    /** The combinator of the call with the empty array: `"and"` or `"or"`. */
     combinator;
     constructor(combinator) {
         super(combinator === "and" ? "composeGuards" : "composeGuardsOr", "PLAY_XSTATE_EMPTY_GUARD_ARRAY", `${combinator === "and" ? "composeGuards" : "composeGuardsOr"} requires at least one guard`);
@@ -166,58 +172,16 @@ export class EmptyGuardArrayError extends PlayError {
     }
 }
 /**
- * Thrown when a composed guard cannot resolve a string guard name at call time.
+ * `PlayerActor.send()` throws this error when the event argument is not a plain
+ * object.
  *
- * String names in `composeGuards`/`composeGuardsOr`/`negateGuard` resolve
- * against `args.guards` — the named guards from `setup({ guards })` that
- * XState v6 provides to transition functions, `always`, entry/exit actions
- * (since 6.0.0-alpha.20), and function-form route resolvers. Resolution fails
- * when the name was never declared or when the composed guard is called
- * without transition arguments.
+ * 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.
  *
- * **Error code:** `PLAY_XSTATE_UNRESOLVABLE_GUARD_NAME`
- */
-export class UnresolvableGuardNameError extends PlayError {
-    /** The guard name that could not be resolved. */
-    guardName;
-    constructor(guardName, origin) {
-        super(origin, "PLAY_XSTATE_UNRESOLVABLE_GUARD_NAME", `Guard "${guardName}" is not a function. Either the name was never declared ` +
-            `in setup({ guards }) or the composed guard was called without ` +
-            `transition arguments.`);
-        this.name = "UnresolvableGuardNameError";
-        this.guardName = guardName;
-    }
-}
-/**
- * Thrown when a composed guard evaluates an entry that is neither a predicate
- * function nor a guard name — typically `null`/`undefined` from a typo'd
- * import or an optional lookup.
- *
- * XState v5 failed loudly when evaluating such entries; silently treating them
- * as never-passing would turn `negateGuard(undefined)` into an always-allow.
- * Composition stays lazy (no throw at compose time); evaluation throws.
- *
- * **Error code:** `PLAY_XSTATE_INVALID_GUARD_ENTRY`
- */
-export class InvalidGuardEntryError extends PlayError {
-    /** `typeof` of the invalid entry (e.g. `"undefined"`, `"object"` for null). */
-    entryType;
-    constructor(entryType, origin) {
-        super(origin, "PLAY_XSTATE_INVALID_GUARD_ENTRY", `Guard entry of type "${entryType}" is neither a predicate function nor a ` +
-            `guard name. Check for typo'd imports or optional lookups that resolved ` +
-            `to null/undefined.`);
-        this.name = "InvalidGuardEntryError";
-        this.entryType = entryType;
-    }
-}
-/**
- * Thrown by `PlayerActor.send()` when the event argument is not a plain object.
- *
- * `PlayEvent` requires `{ type: string, ...fields }`. Passing `null`, `undefined`,
- * a string, or any other non-object value is a programmer error.
- *
- * The offending value is attached as the `detail` readonly class field for debugging.
- * TypeScript consumers can access `err.detail` directly without any unsafe cast.
+ * 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`
  *
@@ -229,14 +193,14 @@ export class InvalidGuardEntryError extends PlayError {
  *   actor.send(null as any);
  * } catch (err) {
  *   if (err instanceof InvalidEventError) {
- *     // err.detail is typed as `unknown` — no cast needed
+ *     // 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 offending value passed to `send()`. */
+    /** The value in question, from the `send()` call. */
     detail;
     constructor(detail) {
         super("PlayerActor", "PLAY_XSTATE_INVALID_EVENT", "PlayerActor.send() received a non-object event.");
@@ -244,4 +208,40 @@ export class InvalidEventError extends PlayError {
         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";
+    }
+}
 //# 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","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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"}