@xmachines/play-xstate 2.0.0 → 2.1.0

package/dist/guards/compose.js

@@ -1,40 +1,43 @@
 import { and, or, not } from "xstate";
 import { EmptyGuardArrayError } from "../errors.js";
 /**
- * PRODUCTION code's single unsound boundary, scoped to XState's guard typings.
- * (Test code uses `unsafeCast` from `@xmachines/shared/test-support` instead —
- * the two are counterparts; a grep-based cast audit must cover both names.)
- *
- * These deprecated helpers bridge two known gaps in XState 5.28's types: our
- * `Guard<TContext, TEvent>` does not structurally match `ComposedGuard`
- * (generic event mismatch), and `and()`/`or()` require `readonly [...tuple]`
- * where `GuardArray` is a mutable array. The runtime values are identical in
- * every case. The parameter is `unknown`, so the one `as` lives here instead
- * of double-casts at each call site.
- * Track XState typing improvements: https://github.com/statelyai/xstate/issues
+ * The one unsound boundary of the PRODUCTION code, and it covers the guard types of
+ * XState only. (The test code uses `unsafeCast` from
+ * `@xmachines/shared/test-support` instead. The two functions are counterparts, and
+ * an audit of the casts with grep must cover both names.)
+ *
+ * These deprecated helpers close two known gaps in the types of XState 5.28. In the
+ * first gap, our `Guard<TContext, TEvent>` type does not match `ComposedGuard`
+ * structurally, because the event generic is different. In the second gap, `and()`
+ * and `or()` need a `readonly [...tuple]`, and `GuardArray` is a mutable array. The
+ * values at run time are identical in each case. The parameter has the type
+ * `unknown`. Therefore one `as` cast is here, and no call site needs a double cast.
+ * Follow the improvements of the XState types: https://github.com/statelyai/xstate/issues
  */
 const asXStateGuard = (value) => value;
 /**
- * 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";
@@ -56,7 +59,7 @@ const asXStateGuard = (value) => value;
  * ```
  *
  * @example
- * AND composition with inline predicates
+ * An AND composition with inline predicates
  * ```typescript
  * import { composeGuards } from "@xmachines/play-xstate";
  *
@@ -66,10 +69,10 @@ const asXStateGuard = (value) => value;
  * ])
  * ```
  *
- * @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.
  */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export const composeGuards = (guards) => {
@@ -77,29 +80,29 @@ export const composeGuards = (guards) => {
         throw new EmptyGuardArrayError("and");
     }
     if (guards.length === 1) {
-        // Single guard passthrough — see asXStateGuard for why the boundary exists.
+        // One guard passes through. asXStateGuard gives the reason for the boundary.
         return asXStateGuard(guards[0]);
     }
-    // Use XState's built-in and() for type inference and serialization.
+    // Use the built-in and() of XState, for the type inference and the serialization.
     return and(asXStateGuard(guards));
 };
 /**
- * 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";
@@ -112,7 +115,7 @@ export const composeGuards = (guards) => {
  * }).createMachine({
  *   on: {
  *     deleteResource: {
- *       // Either guard can pass
+ *       // One guard is sufficient
  *       guard: composeGuardsOr(['isOwner', 'isAdmin']),
  *       actions: 'delete'
  *     }
@@ -120,10 +123,10 @@ export const composeGuards = (guards) => {
  * });
  * ```
  *
- * @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.
  */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export const composeGuardsOr = (guards) => {
@@ -131,26 +134,27 @@ export const composeGuardsOr = (guards) => {
         throw new EmptyGuardArrayError("or");
     }
     if (guards.length === 1) {
-        // Single guard passthrough — see asXStateGuard for why the boundary exists.
+        // One guard passes through. asXStateGuard gives the reason for the boundary.
         return asXStateGuard(guards[0]);
     }
-    // Use XState's built-in or() for type inference and serialization.
+    // Use the built-in or() of XState, for the type inference and the serialization.
     return or(asXStateGuard(guards));
 };
 /**
- * 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";
@@ -162,7 +166,7 @@ export const composeGuardsOr = (guards) => {
  * }).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'
  *     }
@@ -170,15 +174,15 @@ export const composeGuardsOr = (guards) => {
  * });
  * ```
  *
- * @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.
  */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export const negateGuard = (guard) => {
-    // XState 5.28.0: not() requires a specific SingleGuardArg shape, not our
-    // Guard type — see asXStateGuard.
+    // XState 5.28.0: not() requires one SingleGuardArg shape, and not the Guard
+    // type of this package. See asXStateGuard.
     return not(asXStateGuard(guard));
 };
 //# sourceMappingURL=compose.js.map

package/dist/guards/compose.js.map

@@ -1 +1 @@
-{"version":3,"file":"compose.js","sourceRoot":"","sources":["../../src/guards/compose.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,EAAE,EAAE,GAAG,EAAE,MAAM,QAAQ,CAAC;AAItC,OAAO,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AAEpD;;;;;;;;;;;;GAYG;AACH,MAAM,aAAa,GAAG,CAAI,KAAc,EAAK,EAAE,CAAC,KAAU,CAAC;AAmB3D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AACH,8DAA8D;AAC9D,MAAM,CAAC,MAAM,aAAa,GAAG,CAC5B,MAAoC,EACpB,EAAE;IAClB,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,MAAM,IAAI,oBAAoB,CAAC,KAAK,CAAC,CAAC;IACvC,CAAC;IAED,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,4EAA4E;QAC5E,OAAO,aAAa,CAAgB,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;IAChD,CAAC;IAED,oEAAoE;IACpE,OAAO,GAAG,CAAC,aAAa,CAA4B,MAAM,CAAC,CAAC,CAAC;AAC9D,CAAC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,8DAA8D;AAC9D,MAAM,CAAC,MAAM,eAAe,GAAG,CAC9B,MAAoC,EACpB,EAAE;IAClB,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,MAAM,IAAI,oBAAoB,CAAC,IAAI,CAAC,CAAC;IACtC,CAAC;IAED,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,4EAA4E;QAC5E,OAAO,aAAa,CAAgB,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;IAChD,CAAC;IAED,mEAAmE;IACnE,OAAO,EAAE,CAAC,aAAa,CAA2B,MAAM,CAAC,CAAC,CAAC;AAC5D,CAAC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,8DAA8D;AAC9D,MAAM,CAAC,MAAM,WAAW,GAAG,CAC1B,KAAuC,EACvB,EAAE;IAClB,yEAAyE;IACzE,kCAAkC;IAClC,OAAO,GAAG,CAAC,aAAa,CAA4B,KAAK,CAAC,CAAC,CAAC;AAC7D,CAAC,CAAC"}
+{"version":3,"file":"compose.js","sourceRoot":"","sources":["../../src/guards/compose.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,EAAE,EAAE,GAAG,EAAE,MAAM,QAAQ,CAAC;AAItC,OAAO,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AAEpD;;;;;;;;;;;;;GAaG;AACH,MAAM,aAAa,GAAG,CAAI,KAAc,EAAK,EAAE,CAAC,KAAU,CAAC;AAmB3D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0DG;AACH,8DAA8D;AAC9D,MAAM,CAAC,MAAM,aAAa,GAAG,CAC5B,MAAoC,EACpB,EAAE;IAClB,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,MAAM,IAAI,oBAAoB,CAAC,KAAK,CAAC,CAAC;IACvC,CAAC;IAED,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,6EAA6E;QAC7E,OAAO,aAAa,CAAgB,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;IAChD,CAAC;IAED,kFAAkF;IAClF,OAAO,GAAG,CAAC,aAAa,CAA4B,MAAM,CAAC,CAAC,CAAC;AAC9D,CAAC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,8DAA8D;AAC9D,MAAM,CAAC,MAAM,eAAe,GAAG,CAC9B,MAAoC,EACpB,EAAE;IAClB,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,MAAM,IAAI,oBAAoB,CAAC,IAAI,CAAC,CAAC;IACtC,CAAC;IAED,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,6EAA6E;QAC7E,OAAO,aAAa,CAAgB,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;IAChD,CAAC;IAED,iFAAiF;IACjF,OAAO,EAAE,CAAC,aAAa,CAA2B,MAAM,CAAC,CAAC,CAAC;AAC5D,CAAC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,8DAA8D;AAC9D,MAAM,CAAC,MAAM,WAAW,GAAG,CAC1B,KAAuC,EACvB,EAAE;IAClB,4EAA4E;IAC5E,2CAA2C;IAC3C,OAAO,GAAG,CAAC,aAAa,CAA4B,KAAK,CAAC,CAAC,CAAC;AAC7D,CAAC,CAAC"}

package/dist/guards/helpers.d.ts

@@ -1,7 +1,7 @@
 import type { Guard } from "./types.js";
 import type { PlayEvent } from "@xmachines/play";
 /**
- * Check if context has a truthy value at path
+ * Tells you if the context holds a value at the path, and that the value is truthy
  *
  * @example
  * ```typescript
@@ -13,14 +13,14 @@ import type { PlayEvent } from "@xmachines/play";
  * });
  * ```
  *
- * @param path - Dot-separated path to context property
- * @returns Guard predicate checking if property is truthy
- * @deprecated Part of the guard utilities slated for removal in the next major —
- * write a plain typed predicate instead.
+ * @param path - The path to the context property, with a dot between two segments
+ * @returns The guard predicate. It tests the property for a truthy value
+ * @deprecated This function is part of the guard utilities, and the next major version removes
+ * them. Write a plain typed predicate instead.
  */
 export declare const hasContext: <TContext = Record<string, unknown>>(path: string) => Guard<TContext, PlayEvent>;
 /**
- * Check if event type matches expected type
+ * Tells you if the type of the event is the expected type
  *
  * @example
  * ```typescript
@@ -35,28 +35,28 @@ export declare const hasContext: <TContext = Record<string, unknown>>(path: stri
  * });
  * ```
  *
- * @param eventType - Expected event type
- * @returns Guard predicate checking event type
- * @deprecated Part of the guard utilities slated for removal in the next major —
- * write a plain typed predicate instead.
+ * @param eventType - The expected event type
+ * @returns The guard predicate. It tests the event type
+ * @deprecated This function is part of the guard utilities, and the next major version removes
+ * them. Write a plain typed predicate instead.
  */
 export declare const eventMatches: <TEvent extends PlayEvent = PlayEvent>(eventType: string) => Guard<unknown, TEvent>;
 /**
- * Check if a context field matches an expected value.
+ * Tells you if a context field holds the expected value.
  *
- * - Accepts an explicit dot-separated field path (e.g. `"user.role"`)
- * - Uses strict equality for primitives, deep structural equality for objects
- * - Object comparison is key-order-insensitive: `{a:1,b:2}` equals `{b:2,a:1}`
- * - Supports Date, RegExp, class instances, nested objects and arrays via `dequal/lite`
- * - Does NOT use substring matching — `"a"` will not match `"active"`
+ * - The function accepts an explicit field path, with a dot between two segments, for example `"user.role"`
+ * - It compares a primitive with a strict equality, and an object with a deep structural equality
+ * - The order of the keys has no effect on the comparison of an object: `{a:1,b:2}` equals `{b:2,a:1}`
+ * - It supports a Date, a RegExp, an instance of a class, a nested object, and an array, through `dequal/lite`
+ * - It does NOT match a substring: `"a"` does not match `"active"`
  *
- * For XState state-node matching, use the built-in `in:` guard syntax instead.
+ * For a match of an XState state node, use the built-in `in:` guard syntax instead.
  *
- * @param fieldPath - Dot-separated path to context property (e.g., "status", "user.role")
- * @param expectedValue - Value to compare against (string, object, Date, etc.)
- * @returns Guard predicate checking if context field matches
- * @deprecated Part of the guard utilities slated for removal in the next major —
- * write a plain typed predicate instead.
+ * @param fieldPath - The path to the context property, with a dot between two segments, for example "status" or "user.role"
+ * @param expectedValue - The value for the comparison: a string, an object, a Date, and so on
+ * @returns The guard predicate. It tests the context field for the value
+ * @deprecated This function is part of the guard utilities, and the next major version removes
+ * them. Write a plain typed predicate instead.
  */
 export declare const contextFieldMatches: <TContext = Record<string, unknown>>(fieldPath: string, expectedValue: unknown) => Guard<TContext, PlayEvent>;
 //# sourceMappingURL=helpers.d.ts.map

package/dist/guards/helpers.js

@@ -1,6 +1,6 @@
 import { dequal } from "dequal/lite";
 /**
- * Check if context has a truthy value at path
+ * Tells you if the context holds a value at the path, and that the value is truthy
  *
  * @example
  * ```typescript
@@ -12,17 +12,17 @@ import { dequal } from "dequal/lite";
  * });
  * ```
  *
- * @param path - Dot-separated path to context property
- * @returns Guard predicate checking if property is truthy
- * @deprecated Part of the guard utilities slated for removal in the next major —
- * write a plain typed predicate instead.
+ * @param path - The path to the context property, with a dot between two segments
+ * @returns The guard predicate. It tests the property for a truthy value
+ * @deprecated This function is part of the guard utilities, and the next major version removes
+ * them. Write a plain typed predicate instead.
  */
 export const hasContext = (path) => ({ context }) => {
     const value = getNestedValue(context, path);
     return value !== undefined && value !== null && value !== "";
 };
 /**
- * Check if event type matches expected type
+ * Tells you if the type of the event is the expected type
  *
  * @example
  * ```typescript
@@ -37,37 +37,37 @@ export const hasContext = (path) => ({ context }) => {
  * });
  * ```
  *
- * @param eventType - Expected event type
- * @returns Guard predicate checking event type
- * @deprecated Part of the guard utilities slated for removal in the next major —
- * write a plain typed predicate instead.
+ * @param eventType - The expected event type
+ * @returns The guard predicate. It tests the event type
+ * @deprecated This function is part of the guard utilities, and the next major version removes
+ * them. Write a plain typed predicate instead.
  */
 export const eventMatches = (eventType) => ({ event }) => {
     return event.type === eventType;
 };
 /**
- * Check if a context field matches an expected value.
+ * Tells you if a context field holds the expected value.
  *
- * - Accepts an explicit dot-separated field path (e.g. `"user.role"`)
- * - Uses strict equality for primitives, deep structural equality for objects
- * - Object comparison is key-order-insensitive: `{a:1,b:2}` equals `{b:2,a:1}`
- * - Supports Date, RegExp, class instances, nested objects and arrays via `dequal/lite`
- * - Does NOT use substring matching — `"a"` will not match `"active"`
+ * - The function accepts an explicit field path, with a dot between two segments, for example `"user.role"`
+ * - It compares a primitive with a strict equality, and an object with a deep structural equality
+ * - The order of the keys has no effect on the comparison of an object: `{a:1,b:2}` equals `{b:2,a:1}`
+ * - It supports a Date, a RegExp, an instance of a class, a nested object, and an array, through `dequal/lite`
+ * - It does NOT match a substring: `"a"` does not match `"active"`
  *
- * For XState state-node matching, use the built-in `in:` guard syntax instead.
+ * For a match of an XState state node, use the built-in `in:` guard syntax instead.
  *
- * @param fieldPath - Dot-separated path to context property (e.g., "status", "user.role")
- * @param expectedValue - Value to compare against (string, object, Date, etc.)
- * @returns Guard predicate checking if context field matches
- * @deprecated Part of the guard utilities slated for removal in the next major —
- * write a plain typed predicate instead.
+ * @param fieldPath - The path to the context property, with a dot between two segments, for example "status" or "user.role"
+ * @param expectedValue - The value for the comparison: a string, an object, a Date, and so on
+ * @returns The guard predicate. It tests the context field for the value
+ * @deprecated This function is part of the guard utilities, and the next major version removes
+ * them. Write a plain typed predicate instead.
  */
 export const contextFieldMatches = (fieldPath, expectedValue) => ({ context }) => {
     const actual = getNestedValue(context, fieldPath);
     return dequal(actual, expectedValue);
 };
 /**
- * Get nested value from object using dot-separated path
+ * Returns a nested value of an object, from a path with a dot between two segments
  *
  * @internal
  */

package/dist/guards/index.d.ts

@@ -1,15 +1,15 @@
 /**
- * Guard composition and helper utilities for XState machines
+ * The guard composition utilities and the guard helpers of an XState machine
  *
- * Provides array-means-AND composition and convenience helpers
- * for common guard patterns in Play Architecture.
+ * The package gives you a composition where an array means AND. It also gives you
+ * the helpers of the common guard patterns of the Play Architecture.
  *
- * @deprecated The guard helpers wrap XState's own `and` / `or` / `not`
- * combinators without composing with `setup()`-typed guard slots (the
- * package's own example needs a cast to use them). Use XState's combinators
- * directly; this module will be removed in the next major. Every exported
- * symbol carries its own deprecation tag, since consumers import them through
- * the package root rather than this barrel.
+ * @deprecated These guard helpers wrap the `and`, `or`, and `not` combinators of
+ * XState, but they do not compose with a guard slot that `setup()` types. The
+ * example of the package itself needs a cast for them. Use the combinators of XState
+ * directly. The next major version removes this module. Each exported symbol carries
+ * its own deprecation tag, because a consumer imports it through the root of the
+ * package, and not through this barrel.
  *
  * @packageDocumentation
  */

package/dist/guards/index.js

@@ -1,15 +1,15 @@
 /**
- * Guard composition and helper utilities for XState machines
+ * The guard composition utilities and the guard helpers of an XState machine
  *
- * Provides array-means-AND composition and convenience helpers
- * for common guard patterns in Play Architecture.
+ * The package gives you a composition where an array means AND. It also gives you
+ * the helpers of the common guard patterns of the Play Architecture.
  *
- * @deprecated The guard helpers wrap XState's own `and` / `or` / `not`
- * combinators without composing with `setup()`-typed guard slots (the
- * package's own example needs a cast to use them). Use XState's combinators
- * directly; this module will be removed in the next major. Every exported
- * symbol carries its own deprecation tag, since consumers import them through
- * the package root rather than this barrel.
+ * @deprecated These guard helpers wrap the `and`, `or`, and `not` combinators of
+ * XState, but they do not compose with a guard slot that `setup()` types. The
+ * example of the package itself needs a cast for them. Use the combinators of XState
+ * directly. The next major version removes this module. Each exported symbol carries
+ * its own deprecation tag, because a consumer imports it through the root of the
+ * package, and not through this barrel.
  *
  * @packageDocumentation
  */

package/dist/guards/types.d.ts

@@ -1,21 +1,22 @@
 import type { PlayEvent } from "@xmachines/play";
 /**
- * Standard XState guard function signature — guards receive `{ context, event }`.
+ * The standard signature of an XState guard function. A guard receives `{ context, event }`.
  *
- * @param args - Guard arguments with context and event
- * @param args.context - Current machine context
- * @param args.event - Event that triggered the guard evaluation
- * @returns boolean indicating if guard passes
- * @deprecated The guard utilities will be removed in the next major.
+ * @param args - The arguments of the guard: the context and the event
+ * @param args.context - The current machine context
+ * @param args.event - The event that started the evaluation of the guard
+ * @returns The boolean value. It tells you if the guard passes
+ * @deprecated The next major version removes the guard utilities.
  */
 export type Guard<TContext = Record<string, unknown>, TEvent = PlayEvent> = (args: {
     context: TContext;
     event: TEvent;
 }) => boolean;
 /**
- * Array of guard predicates or guard names — an array means AND: all must pass.
+ * The array of the guard predicates, or of the guard names. An array means AND:
+ * every guard must pass.
  *
- * @deprecated The guard utilities will be removed in the next major.
+ * @deprecated The next major version removes the guard utilities.
  */
 export type GuardArray<TContext = Record<string, unknown>, TEvent = PlayEvent> = Array<Guard<TContext, TEvent> | string>;
 //# sourceMappingURL=types.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/guards/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAEjD;;;;;;;;GAQG;AACH,MAAM,MAAM,KAAK,CAAC,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,IAAI,CAAC,IAAI,EAAE;IAClF,OAAO,EAAE,QAAQ,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;CACd,KAAK,OAAO,CAAC;AAEd;;;;GAIG;AACH,MAAM,MAAM,UAAU,CAAC,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,IAAI,KAAK,CACrF,KAAK,CAAC,QAAQ,EAAE,MAAM,CAAC,GAAG,MAAM,CAChC,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/guards/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAEjD;;;;;;;;GAQG;AACH,MAAM,MAAM,KAAK,CAAC,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,IAAI,CAAC,IAAI,EAAE;IAClF,OAAO,EAAE,QAAQ,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;CACd,KAAK,OAAO,CAAC;AAEd;;;;;GAKG;AACH,MAAM,MAAM,UAAU,CAAC,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,IAAI,KAAK,CACrF,KAAK,CAAC,QAAQ,EAAE,MAAM,CAAC,GAAG,MAAM,CAChC,CAAC"}

package/dist/index.d.ts

@@ -1,11 +1,12 @@
 /**
- * @xmachines/play-xstate - XState v5 adapter for Play Architecture
+ * @xmachines/play-xstate - the XState v5 adapter of the Play Architecture
  *
- * Provides definePlayer() API for binding XState state machines to the
- * actor base with signal lifecycle and DevTools integration.
+ * This package gives you the definePlayer() API. That function binds an XState state
+ * machine to the actor base, with the signal lifecycle and the DevTools
+ * integration.
  *
- * Per the Play RFC, this package implements the Logic Layer adapter that
- * transforms declarative machine definitions into live actors with signal-driven
+ * The Play RFC gives this package as the adapter of the logic layer. It converts a
+ * declarative machine definition into a live actor with a signal-driven
  * reactivity.
  *
  * @packageDocumentation

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,YAAY,EACX,YAAY,EACZ,aAAa,EACb,aAAa,EACb,0BAA0B,GAC1B,MAAM,YAAY,CAAC;AAGpB,OAAO,EACN,aAAa,EACb,eAAe,EACf,WAAW,EACX,UAAU,EACV,YAAY,EACZ,mBAAmB,GACnB,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EAAE,KAAK,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAG1E,OAAO,EACN,WAAW,EACX,eAAe,EACf,aAAa,EACb,0BAA0B,GAC1B,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EACX,kBAAkB,EAClB,cAAc,EACd,YAAY,EACZ,WAAW,EACX,aAAa,GACb,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,YAAY,EACX,YAAY,EACZ,aAAa,EACb,aAAa,EACb,0BAA0B,GAC1B,MAAM,YAAY,CAAC;AAGpB,OAAO,EACN,aAAa,EACb,eAAe,EACf,WAAW,EACX,UAAU,EACV,YAAY,EACZ,mBAAmB,GACnB,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EAAE,KAAK,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAG1E,OAAO,EACN,WAAW,EACX,eAAe,EACf,aAAa,EACb,0BAA0B,GAC1B,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EACX,kBAAkB,EAClB,cAAc,EACd,YAAY,EACZ,WAAW,EACX,aAAa,GACb,MAAM,oBAAoB,CAAC"}

package/dist/index.js

@@ -1,19 +1,20 @@
 /**
- * @xmachines/play-xstate - XState v5 adapter for Play Architecture
+ * @xmachines/play-xstate - the XState v5 adapter of the Play Architecture
  *
- * Provides definePlayer() API for binding XState state machines to the
- * actor base with signal lifecycle and DevTools integration.
+ * This package gives you the definePlayer() API. That function binds an XState state
+ * machine to the actor base, with the signal lifecycle and the DevTools
+ * integration.
  *
- * Per the Play RFC, this package implements the Logic Layer adapter that
- * transforms declarative machine definitions into live actors with signal-driven
+ * The Play RFC gives this package as the adapter of the logic layer. It converts a
+ * declarative machine definition into a live actor with a signal-driven
  * reactivity.
  *
  * @packageDocumentation
  */
 export { definePlayer } from "./define-player.js";
 export { PlayerActor } from "./player-actor.js";
-// Guard utilities
+// The guard utilities
 export { composeGuards, composeGuardsOr, negateGuard, hasContext, eventMatches, contextFieldMatches, } from "./guards/index.js";
-// Routing utilities
+// The routing utilities
 export { deriveRoute, isAbsoluteRoute, buildRouteUrl, formatPlayRouteTransitions, } from "./routing/index.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAQhD,kBAAkB;AAClB,OAAO,EACN,aAAa,EACb,eAAe,EACf,WAAW,EACX,UAAU,EACV,YAAY,EACZ,mBAAmB,GACnB,MAAM,mBAAmB,CAAC;AAG3B,oBAAoB;AACpB,OAAO,EACN,WAAW,EACX,eAAe,EACf,aAAa,EACb,0BAA0B,GAC1B,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAQhD,sBAAsB;AACtB,OAAO,EACN,aAAa,EACb,eAAe,EACf,WAAW,EACX,UAAU,EACV,YAAY,EACZ,mBAAmB,GACnB,MAAM,mBAAmB,CAAC;AAG3B,wBAAwB;AACxB,OAAO,EACN,WAAW,EACX,eAAe,EACf,aAAa,EACb,0BAA0B,GAC1B,MAAM,oBAAoB,CAAC"}