@xmachines/play-xstate 2.0.0 → 2.1.0

package/dist/errors.js

@@ -1,9 +1,10 @@
 import { PlayError } from "@xmachines/play";
 /**
- * Stringify a thrown value without trusting it: `String()` itself throws for
- * a null-prototype object or a value whose `toString`/`Symbol.toPrimitive`
- * throw, and this runs inside the error path — a second throw here would
- * replace the machine's real failure with a `TypeError` and bypass `onError`.
+ * 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 {
@@ -14,23 +15,23 @@ const safeString = (value) => {
             return Object.prototype.toString.call(value);
         }
         catch {
-            // A revoked Proxy throws even on brand inspection.
+            // A revoked Proxy throws also on an inspection of the brand.
             return "[unrepresentable value]";
         }
     }
 };
 /**
- * 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()` never surfaces this error — route
- * derivation catches it and returns `null` for the transient mid-transition
- * case. It only escapes direct `buildRouteUrl()` calls.
+ * 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
@@ -49,9 +50,9 @@ const safeString = (value) => {
  * ```
  */
 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.`);
@@ -61,16 +62,16 @@ export class MissingRouteParamError extends PlayError {
     }
 }
 /**
- * @deprecated Never thrown any more. `buildRouteUrl` treats a missing `query`
- * field as `query: {}` — the generated `play.route` transitions assign
- * `query` on every navigation, so the loss this error guarded against cannot
- * occur through route derivation. Machines that handle `play.route` by hand
- * and want query forwarding must assign `event.query` to context themselves.
- * Kept exported so existing `instanceof` handlers keep compiling; remove them
- * at leisure.
+ * @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.
  *
- * Formerly thrown by `buildRouteUrl()` when the context had a `params` field
- * (a routing-aware machine context) but no `query` field.
+ * `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`
  */
@@ -83,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
  *   }
  * }
  *
@@ -113,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. ` +
@@ -126,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`
  */
@@ -138,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);
@@ -154,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`);
@@ -169,13 +172,16 @@ export class EmptyGuardArrayError extends PlayError {
     }
 }
 /**
- * Thrown by `PlayerActor.send()` when the event argument is not a plain object.
+ * `PlayerActor.send()` throws this error 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.
+ * 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 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`
  *
@@ -187,14 +193,14 @@ export class EmptyGuardArrayError 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.");
@@ -203,13 +209,15 @@ export class InvalidEventError extends PlayError {
     }
 }
 /**
- * Passed to `PlayerOptions.onError` when the actor failed with a value that is
- * not an `Error` — e.g. a machine action ran `throw { code: 42 }`.
+ * 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` untouched, keeping the
- * identity the machine gave it. Only this case constructs a new error, so it
- * carries a matchable code instead of a `String(value)` message such as
- * `"[object Object]"`. The thrown value is preserved on `cause`.
+ * 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`
  *
@@ -222,7 +230,7 @@ export class InvalidEventError extends PlayError {
  *   options: {
  *     onError: (actor, err) => {
  *       if (err instanceof ActorThrewNonErrorError) {
- *         // err.cause is the value the machine actually threw
+ *         // err.cause is the value that the machine threw
  *         console.error("Machine threw a non-Error:", err.cause);
  *       }
  *     },

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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"}

package/dist/guards/compose.d.ts

@@ -2,37 +2,39 @@ import type { GuardPredicate } from "xstate";
 import type { Guard, GuardArray } from "./types.js";
 import type { MachineContext, EventObject, ParameterizedObject } from "xstate";
 /**
- * Narrowest public return type for guard composition helpers.
+ * The narrowest public return type of the guard composition helpers.
  *
  * `GuardPredicate<MachineContext, EventObject, unknown, ParameterizedObject>` is the
- * widest-compatible concrete XState guard type that does not use `any`.
+ * concrete XState guard type with the widest compatibility that uses no `any`.
  *
  * @public
- * @deprecated The guard utilities will be removed in the next major — use
- * XState's own combinator types directly.
+ * @deprecated The next major version removes the guard utilities. Use the
+ * combinator types of XState directly.
  */
 export type ComposedGuard = GuardPredicate<MachineContext, EventObject, unknown, ParameterizedObject>;
 /**
- * Compose guards with AND logic using XState's and() helper
+ * Composes the guards with the AND logic, through the and() helper of XState
  *
- * Combines multiple guard predicates using AND semantics—all guards must pass for
- * the composition to succeed. Uses XState's built-in `and()` helper to ensure proper
- * type inference and machine serialization.
+ * The function joins more than one guard predicate with the AND semantics: every
+ * guard must pass, and the composition then succeeds. It uses the built-in `and()`
+ * helper of XState. The type inference and the serialization of the machine are
+ * therefore correct.
  *
- * **Architectural Context:** Supports **Actor Authority (INV-01)** by enabling
- * declarative guard composition in state machine transitions. Guards enforce business
- * logic rules that determine whether navigation or actions are valid.
+ * **Architectural context:** the function supports **Actor Authority (INV-01)**,
+ * because it composes the guards of a state machine transition declaratively. A
+ * guard enforces a rule of the business logic, and that rule decides if a
+ * navigation or an action is valid.
  *
- * @typeParam TContext - State machine context type
- * @typeParam TEvent - Event type
+ * @typeParam TContext - The context type of the state machine
+ * @typeParam TEvent - The event type
  *
- * @param guards - Array of guard predicates or guard names (string references)
- * @returns XState and() guard composition
+ * @param guards - The array of the guard predicates, or of the guard names as strings
+ * @returns The and() guard composition of XState
  *
- * @throws {Error} If guards array is empty
+ * @throws {Error} When the array of the guards is empty
  *
  * @example
- * AND composition with named guards
+ * An AND composition with named guards
  * ```typescript
  * import { setup } from "xstate";
  * import { composeGuards } from "@xmachines/play-xstate";
@@ -54,7 +56,7 @@ export type ComposedGuard = GuardPredicate<MachineContext, EventObject, unknown,
  * ```
  *
  * @example
- * AND composition with inline predicates
+ * An AND composition with inline predicates
  * ```typescript
  * import { composeGuards } from "@xmachines/play-xstate";
  *
@@ -64,29 +66,29 @@ export type ComposedGuard = GuardPredicate<MachineContext, EventObject, unknown,
  * ])
  * ```
  *
- * @see {@link composeGuardsOr} for OR composition
- * @see {@link negateGuard} for NOT logic
- * @deprecated Use XState's own `and()`/`or()`/`not()` directly — this helper does not
- * compose with `setup()`-typed guard slots and will be removed in the next major.
+ * @see {@link composeGuardsOr} for the OR composition
+ * @see {@link negateGuard} for the NOT logic
+ * @deprecated Use the `and()`, `or()`, and `not()` combinators of XState directly. This helper
+ * does not compose with a guard slot that `setup()` types, and the next major version removes it.
  */
 export declare const composeGuards: <TContext = any, TEvent = any>(guards: GuardArray<TContext, TEvent>) => ComposedGuard;
 /**
- * Compose guards with OR logic using XState's or() helper
+ * Composes the guards with the OR logic, through the or() helper of XState
  *
- * Combines multiple guard predicates using OR semantics—at least one guard must pass
- * for the composition to succeed. Uses XState's built-in `or()` helper for proper
- * type inference.
+ * The function joins more than one guard predicate with the OR semantics: one guard
+ * must pass at least, and the composition then succeeds. It uses the built-in `or()`
+ * helper of XState, and the type inference is therefore correct.
  *
- * @typeParam TContext - State machine context type
- * @typeParam TEvent - Event type
+ * @typeParam TContext - The context type of the state machine
+ * @typeParam TEvent - The event type
  *
- * @param guards - Array of guard predicates or guard names
- * @returns XState or() guard composition
+ * @param guards - The array of the guard predicates, or of the guard names
+ * @returns The or() guard composition of XState
  *
- * @throws {Error} If guards array is empty
+ * @throws {Error} When the array of the guards is empty
  *
  * @example
- * OR composition with named guards
+ * An OR composition with named guards
  * ```typescript
  * import { setup } from "xstate";
  * import { composeGuardsOr } from "@xmachines/play-xstate";
@@ -99,7 +101,7 @@ export declare const composeGuards: <TContext = any, TEvent = any>(guards: Guard
  * }).createMachine({
  *   on: {
  *     deleteResource: {
- *       // Either guard can pass
+ *       // One guard is sufficient
  *       guard: composeGuardsOr(['isOwner', 'isAdmin']),
  *       actions: 'delete'
  *     }
@@ -107,26 +109,27 @@ export declare const composeGuards: <TContext = any, TEvent = any>(guards: Guard
  * });
  * ```
  *
- * @see {@link composeGuards} for AND composition
- * @see {@link negateGuard} for NOT logic
- * @deprecated Use XState's own `and()`/`or()`/`not()` directly — this helper does not
- * compose with `setup()`-typed guard slots and will be removed in the next major.
+ * @see {@link composeGuards} for the AND composition
+ * @see {@link negateGuard} for the NOT logic
+ * @deprecated Use the `and()`, `or()`, and `not()` combinators of XState directly. This helper
+ * does not compose with a guard slot that `setup()` types, and the next major version removes it.
  */
 export declare const composeGuardsOr: <TContext = any, TEvent = any>(guards: GuardArray<TContext, TEvent>) => ComposedGuard;
 /**
- * Negate a guard using XState's not() helper
+ * Negates a guard, through the not() helper of XState
  *
- * Inverts a guard's result—if the guard passes, NOT fails; if guard fails, NOT passes.
- * Uses XState's built-in `not()` helper for proper serialization.
+ * The function inverts the result of a guard: the guard passes, and NOT then fails;
+ * the guard fails, and NOT then passes. It uses the built-in `not()` helper of
+ * XState, and the serialization is therefore correct.
  *
- * @typeParam TContext - State machine context type
- * @typeParam TEvent - Event type
+ * @typeParam TContext - The context type of the state machine
+ * @typeParam TEvent - The event type
  *
- * @param guard - Guard predicate or guard name to negate
- * @returns XState not() guard negation
+ * @param guard - The guard predicate to negate, or its name
+ * @returns The not() guard negation of XState
  *
  * @example
- * NOT composition with named guard
+ * A NOT composition with a named guard
  * ```typescript
  * import { setup } from "xstate";
  * import { negateGuard } from "@xmachines/play-xstate";
@@ -138,7 +141,7 @@ export declare const composeGuardsOr: <TContext = any, TEvent = any>(guards: Gua
  * }).createMachine({
  *   on: {
  *     accessDashboard: {
- *       // Allow if NOT a guest (i.e., authenticated)
+ *       // Permit the transition when the user is NOT a guest, which means an authenticated user
  *       guard: negateGuard('isGuest'),
  *       target: 'dashboard'
  *     }
@@ -146,10 +149,10 @@ export declare const composeGuardsOr: <TContext = any, TEvent = any>(guards: Gua
  * });
  * ```
  *
- * @see {@link composeGuards} for AND composition
- * @see {@link composeGuardsOr} for OR composition
- * @deprecated Use XState's own `and()`/`or()`/`not()` directly — this helper does not
- * compose with `setup()`-typed guard slots and will be removed in the next major.
+ * @see {@link composeGuards} for the AND composition
+ * @see {@link composeGuardsOr} for the OR composition
+ * @deprecated Use the `and()`, `or()`, and `not()` combinators of XState directly. This helper
+ * does not compose with a guard slot that `setup()` types, and the next major version removes it.
  */
 export declare const negateGuard: <TContext = any, TEvent = any>(guard: Guard<TContext, TEvent> | string) => ComposedGuard;
 //# sourceMappingURL=compose.d.ts.map

package/dist/guards/compose.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"compose.d.ts","sourceRoot":"","sources":["../../src/guards/compose.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,QAAQ,CAAC;AAC7C,OAAO,KAAK,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACpD,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,mBAAmB,EAAE,MAAM,QAAQ,CAAC;AAkB/E;;;;;;;;;GASG;AACH,MAAM,MAAM,aAAa,GAAG,cAAc,CACzC,cAAc,EACd,WAAW,EACX,OAAO,EACP,mBAAmB,CACnB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AAEH,eAAO,MAAM,aAAa,GAAI,QAAQ,GAAG,GAAG,EAAE,MAAM,GAAG,GAAG,EACzD,QAAQ,UAAU,CAAC,QAAQ,EAAE,MAAM,CAAC,KAClC,aAYF,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAEH,eAAO,MAAM,eAAe,GAAI,QAAQ,GAAG,GAAG,EAAE,MAAM,GAAG,GAAG,EAC3D,QAAQ,UAAU,CAAC,QAAQ,EAAE,MAAM,CAAC,KAClC,aAYF,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,eAAO,MAAM,WAAW,GAAI,QAAQ,GAAG,GAAG,EAAE,MAAM,GAAG,GAAG,EACvD,OAAO,KAAK,CAAC,QAAQ,EAAE,MAAM,CAAC,GAAG,MAAM,KACrC,aAIF,CAAC"}
+{"version":3,"file":"compose.d.ts","sourceRoot":"","sources":["../../src/guards/compose.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,QAAQ,CAAC;AAC7C,OAAO,KAAK,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACpD,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,mBAAmB,EAAE,MAAM,QAAQ,CAAC;AAmB/E;;;;;;;;;GASG;AACH,MAAM,MAAM,aAAa,GAAG,cAAc,CACzC,cAAc,EACd,WAAW,EACX,OAAO,EACP,mBAAmB,CACnB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0DG;AAEH,eAAO,MAAM,aAAa,GAAI,QAAQ,GAAG,GAAG,EAAE,MAAM,GAAG,GAAG,EACzD,QAAQ,UAAU,CAAC,QAAQ,EAAE,MAAM,CAAC,KAClC,aAYF,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAEH,eAAO,MAAM,eAAe,GAAI,QAAQ,GAAG,GAAG,EAAE,MAAM,GAAG,GAAG,EAC3D,QAAQ,UAAU,CAAC,QAAQ,EAAE,MAAM,CAAC,KAClC,aAYF,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAEH,eAAO,MAAM,WAAW,GAAI,QAAQ,GAAG,GAAG,EAAE,MAAM,GAAG,GAAG,EACvD,OAAO,KAAK,CAAC,QAAQ,EAAE,MAAM,CAAC,GAAG,MAAM,KACrC,aAIF,CAAC"}