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

package/dist/guards/compose.d.ts

@@ -1,59 +1,44 @@
+import type { GuardPredicate } from "xstate";
 import type { Guard, GuardArray } from "./types.js";
+import type { MachineContext, EventObject, ParameterizedObject } from "xstate";
 /**
- * Composed guard: a plain predicate over transition arguments.
+ * The narrowest public return type of the guard composition helpers.
  *
- * XState v6 removed guard objects and the `and()`/`or()`/`not()` creators —
- * guards are now plain functions evaluated inside transition functions. A
- * composed guard is therefore just another predicate with the same shape as
- * {@link Guard}, callable anywhere transition args are available.
- *
- * String guard names are resolved against `args.guards` (the named guards
- * declared in `setup({ guards })`, which XState v6 passes to every transition
- * function). Resolving a name outside a transition function — or a name that
- * was never declared — throws `UnresolvableGuardNameError` immediately.
- *
- * String names work in `on` transitions, `always`, entry/exit actions (since
- * xstate 6.0.0-alpha.20 populates `guards` there), and function-form route
- * resolvers.
+ * `GuardPredicate<MachineContext, EventObject, unknown, ParameterizedObject>` is the
+ * concrete XState guard type with the widest compatibility that uses no `any`.
  *
  * @public
+ * @deprecated The next major version removes the guard utilities. Use the
+ * combinator types of XState directly.
  */
-export type ComposedGuard = (args: unknown) => boolean;
+export type ComposedGuard = GuardPredicate<MachineContext, EventObject, unknown, ParameterizedObject>;
 /**
- * Compose guards with AND logic.
- *
- * Combines multiple guard predicates using AND semantics—all guards must pass for
- * the composition to succeed. Evaluation is short-circuiting, left to right.
- *
- * **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.
+ * Composes the guards with the AND logic, through the and() helper of XState
  *
- * **XState v6:** the composed value is a plain predicate. Call it inside a
- * transition function and return early to block the transition:
+ * 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.
  *
- * @typeParam TContext - State machine context type (defaults to `any` so the
- *   documented inline-predicate examples compile without annotations)
- * @typeParam TEvent - Event type
+ * **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 (defaults to `any` so the
- *   documented inline-predicate examples compile without annotations)
- * @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
- *   resolved against `args.guards` from `setup({ guards })`)
- * @returns Predicate returning `true` only when every guard passes
+ * @param guards - The array of the guard predicates, or of the guard names as strings
+ * @returns The and() guard composition of XState
  *
- * @throws {EmptyGuardArrayError} 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";
  *
- * const canAccessAdmin = composeGuards(['isLoggedIn', 'hasPermission']);
- *
  * const machine = setup({
  *   guards: {
  *     isLoggedIn: ({ context }) => !!context.userId,
@@ -61,49 +46,53 @@ export type ComposedGuard = (args: unknown) => boolean;
  *   }
  * }).createMachine({
  *   on: {
- *     accessAdmin: (args) => {
- *       if (!canAccessAdmin(args)) return;
- *       return { target: 'adminPanel' };
+ *     accessAdmin: {
+ *       // Both guards must pass
+ *       guard: composeGuards(['isLoggedIn', 'hasPermission']),
+ *       target: 'adminPanel'
  *     }
  *   }
  * });
  * ```
  *
  * @example
- * AND composition with inline predicates
+ * An AND composition with inline predicates
  * ```typescript
  * import { composeGuards } from "@xmachines/play-xstate";
  *
- * const isEligible = composeGuards([
+ * guard: composeGuards([
  *   ({ context }) => context.age >= 18,
  *   ({ context }) => context.verified
- * ]);
+ * ])
  * ```
  *
- * @see {@link composeGuardsOr} for OR composition
- * @see {@link negateGuard} for NOT logic
+ * @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.
+ * Composes the guards with the OR logic, through the or() helper of XState
+ *
+ * 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.
  *
- * Combines multiple guard predicates using OR semantics—at least one guard must pass
- * for the composition to succeed. Evaluation is short-circuiting, left to right.
+ * @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
- *   resolved against `args.guards` from `setup({ guards })`)
- * @returns Predicate returning `true` when any guard passes
+ * @param guards - The array of the guard predicates, or of the guard names
+ * @returns The or() guard composition of XState
  *
- * @throws {EmptyGuardArrayError} 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";
  *
- * const canDelete = composeGuardsOr(['isOwner', 'isAdmin']);
- *
  * const machine = setup({
  *   guards: {
  *     isOwner: ({ context }) => context.role === 'owner',
@@ -111,55 +100,59 @@ export declare const composeGuards: <TContext = any, TEvent = any>(guards: Guard
  *   }
  * }).createMachine({
  *   on: {
- *     deleteResource: (args, enq) => {
- *       if (!canDelete(args)) return;
- *       enq(() => deleteIt());
+ *     deleteResource: {
+ *       // One guard is sufficient
+ *       guard: composeGuardsOr(['isOwner', 'isAdmin']),
+ *       actions: 'delete'
  *     }
  *   }
  * });
  * ```
  *
- * @see {@link composeGuards} for AND composition
- * @see {@link negateGuard} for NOT logic
+ * @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.
+ * 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.
+ * 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 (defaults to `any` so
- *   inline predicates compile without annotations)
- * @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 (resolved against `args.guards`
- *   from `setup({ guards })`) to negate
- * @returns Predicate returning the inverted guard result
+ * @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";
  *
- * const isAuthenticated = negateGuard('isGuest');
- *
  * const machine = setup({
  *   guards: {
  *     isGuest: ({ context }) => !context.userId
  *   }
  * }).createMachine({
  *   on: {
- *     accessDashboard: (args) => {
- *       if (!isAuthenticated(args)) return;
- *       return { target: 'dashboard' };
+ *     accessDashboard: {
+ *       // Permit the transition when the user is NOT a guest, which means an authenticated user
+ *       guard: negateGuard('isGuest'),
+ *       target: 'dashboard'
  *     }
  *   }
  * });
  * ```
  *
- * @see {@link composeGuards} for AND composition
- * @see {@link composeGuardsOr} for OR composition
+ * @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":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAQpD;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,IAAI,EAAE,OAAO,KAAK,OAAO,CAAC;AAqCvD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+DG;AAEH,eAAO,MAAM,aAAa,GAAI,QAAQ,GAAG,GAAG,EAAE,MAAM,GAAG,GAAG,EACzD,QAAQ,UAAU,CAAC,QAAQ,EAAE,MAAM,CAAC,KAClC,aAgBF,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,eAAO,MAAM,eAAe,GAAI,QAAQ,GAAG,GAAG,EAAE,MAAM,GAAG,GAAG,EAC3D,QAAQ,UAAU,CAAC,QAAQ,EAAE,MAAM,CAAC,KAClC,aAgBF,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,aAGF,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"}

package/dist/guards/compose.js

@@ -1,69 +1,47 @@
-import { EmptyGuardArrayError, InvalidGuardEntryError, UnresolvableGuardNameError, } from "../errors.js";
+import { and, or, not } from "xstate";
+import { EmptyGuardArrayError } from "../errors.js";
 /**
- * Resolve a guard entry (predicate or setup guard name) to an evaluator thunk.
- *
- * The predicate-vs-name discrimination happens once at compose time; only the
- * `args.guards` lookup for string names stays at call time, preserving the
- * documented late-binding semantics. `origin` names the combinator that built
- * the guard, so thrown errors report the correct `scope`.
- *
- * @internal
+ * 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 toEvaluator = (guard, origin) => {
-    if (typeof guard === "function") {
-        return (args) => Boolean(guard(args));
-    }
-    if (typeof guard === "string") {
-        return (args) => {
-            const named = args?.guards?.[guard];
-            if (typeof named !== "function") {
-                throw new UnresolvableGuardNameError(guard, origin);
-            }
-            return Boolean(named(args));
-        };
-    }
-    // XState v5 failed loudly when EVALUATING a nullish guard entry — silently
-    // treating it as never-passing would turn negateGuard(undefined) into an
-    // always-allow. Composition stays lazy; evaluation throws.
-    return () => {
-        throw new InvalidGuardEntryError(typeof guard, origin);
-    };
-};
+const asXStateGuard = (value) => value;
 /**
- * Compose guards with AND logic.
- *
- * Combines multiple guard predicates using AND semantics—all guards must pass for
- * the composition to succeed. Evaluation is short-circuiting, left to right.
+ * Composes the guards with the AND logic, through the and() helper of XState
  *
- * **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.
+ * 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.
  *
- * **XState v6:** the composed value is a plain predicate. Call it inside a
- * transition function and return early to block the transition:
+ * **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 (defaults to `any` so the
- *   documented inline-predicate examples compile without annotations)
- * @typeParam TEvent - Event type
+ * @typeParam TContext - The context type of the state machine
+ * @typeParam TEvent - The event type
  *
- * @typeParam TContext - State machine context type (defaults to `any` so the
- *   documented inline-predicate examples compile without annotations)
- * @typeParam TEvent - Event type
+ * @param guards - The array of the guard predicates, or of the guard names as strings
+ * @returns The and() guard composition of XState
  *
- * @param guards - Array of guard predicates or guard names (string references
- *   resolved against `args.guards` from `setup({ guards })`)
- * @returns Predicate returning `true` only when every guard passes
- *
- * @throws {EmptyGuardArrayError} 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";
  *
- * const canAccessAdmin = composeGuards(['isLoggedIn', 'hasPermission']);
- *
  * const machine = setup({
  *   guards: {
  *     isLoggedIn: ({ context }) => !!context.userId,
@@ -71,65 +49,64 @@ const toEvaluator = (guard, origin) => {
  *   }
  * }).createMachine({
  *   on: {
- *     accessAdmin: (args) => {
- *       if (!canAccessAdmin(args)) return;
- *       return { target: 'adminPanel' };
+ *     accessAdmin: {
+ *       // Both guards must pass
+ *       guard: composeGuards(['isLoggedIn', 'hasPermission']),
+ *       target: 'adminPanel'
  *     }
  *   }
  * });
  * ```
  *
  * @example
- * AND composition with inline predicates
+ * An AND composition with inline predicates
  * ```typescript
  * import { composeGuards } from "@xmachines/play-xstate";
  *
- * const isEligible = composeGuards([
+ * guard: composeGuards([
  *   ({ context }) => context.age >= 18,
  *   ({ context }) => context.verified
- * ]);
+ * ])
  * ```
  *
- * @see {@link composeGuardsOr} for OR composition
- * @see {@link negateGuard} for NOT logic
+ * @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) => {
     if (guards.length === 0) {
         throw new EmptyGuardArrayError("and");
     }
-    const evaluators = guards.map((guard) => toEvaluator(guard, "composeGuards"));
-    if (evaluators.length === 1) {
-        return evaluators[0];
+    if (guards.length === 1) {
+        // One guard passes through. asXStateGuard gives the reason for the boundary.
+        return asXStateGuard(guards[0]);
     }
-    return (args) => {
-        for (const evaluate of evaluators) {
-            if (!evaluate(args))
-                return false;
-        }
-        return true;
-    };
+    // Use the built-in and() of XState, for the type inference and the serialization.
+    return and(asXStateGuard(guards));
 };
 /**
- * Compose guards with OR logic.
+ * Composes the guards with the OR logic, through the or() helper of XState
+ *
+ * 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.
  *
- * Combines multiple guard predicates using OR semantics—at least one guard must pass
- * for the composition to succeed. Evaluation is short-circuiting, left to right.
+ * @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
- *   resolved against `args.guards` from `setup({ guards })`)
- * @returns Predicate returning `true` when any guard passes
+ * @param guards - The array of the guard predicates, or of the guard names
+ * @returns The or() guard composition of XState
  *
- * @throws {EmptyGuardArrayError} 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";
  *
- * const canDelete = composeGuardsOr(['isOwner', 'isAdmin']);
- *
  * const machine = setup({
  *   guards: {
  *     isOwner: ({ context }) => context.role === 'owner',
@@ -137,75 +114,75 @@ export const composeGuards = (guards) => {
  *   }
  * }).createMachine({
  *   on: {
- *     deleteResource: (args, enq) => {
- *       if (!canDelete(args)) return;
- *       enq(() => deleteIt());
+ *     deleteResource: {
+ *       // One guard is sufficient
+ *       guard: composeGuardsOr(['isOwner', 'isAdmin']),
+ *       actions: 'delete'
  *     }
  *   }
  * });
  * ```
  *
- * @see {@link composeGuards} for AND composition
- * @see {@link negateGuard} for NOT logic
+ * @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) => {
     if (guards.length === 0) {
         throw new EmptyGuardArrayError("or");
     }
-    const evaluators = guards.map((guard) => toEvaluator(guard, "composeGuardsOr"));
-    if (evaluators.length === 1) {
-        return evaluators[0];
+    if (guards.length === 1) {
+        // One guard passes through. asXStateGuard gives the reason for the boundary.
+        return asXStateGuard(guards[0]);
     }
-    return (args) => {
-        for (const evaluate of evaluators) {
-            if (evaluate(args))
-                return true;
-        }
-        return false;
-    };
+    // Use the built-in or() of XState, for the type inference and the serialization.
+    return or(asXStateGuard(guards));
 };
 /**
- * Negate a guard.
+ * 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.
+ * 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 (defaults to `any` so
- *   inline predicates compile without annotations)
- * @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 (resolved against `args.guards`
- *   from `setup({ guards })`) to negate
- * @returns Predicate returning the inverted guard result
+ * @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";
  *
- * const isAuthenticated = negateGuard('isGuest');
- *
  * const machine = setup({
  *   guards: {
  *     isGuest: ({ context }) => !context.userId
  *   }
  * }).createMachine({
  *   on: {
- *     accessDashboard: (args) => {
- *       if (!isAuthenticated(args)) return;
- *       return { target: 'dashboard' };
+ *     accessDashboard: {
+ *       // Permit the transition when the user is NOT a guest, which means an authenticated user
+ *       guard: negateGuard('isGuest'),
+ *       target: 'dashboard'
  *     }
  *   }
  * });
  * ```
  *
- * @see {@link composeGuards} for AND composition
- * @see {@link composeGuardsOr} for OR composition
+ * @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) => {
-    const evaluate = toEvaluator(guard, "negateGuard");
-    return (args) => !evaluate(args);
+    // 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":"AACA,OAAO,EACN,oBAAoB,EACpB,sBAAsB,EACtB,0BAA0B,GAE1B,MAAM,cAAc,CAAC;AAuBtB;;;;;;;;;GASG;AACH,MAAM,WAAW,GAAG,CAAC,KAAc,EAAE,MAAuB,EAAiB,EAAE;IAC9E,IAAI,OAAO,KAAK,KAAK,UAAU,EAAE,CAAC;QACjC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAE,KAAuB,CAAC,IAAI,CAAC,CAAC,CAAC;IAC1D,CAAC;IAED,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC/B,OAAO,CAAC,IAAI,EAAE,EAAE;YACf,MAAM,KAAK,GAAI,IAAyD,EAAE,MAAM,EAAE,CACjF,KAAK,CACL,CAAC;YACF,IAAI,OAAO,KAAK,KAAK,UAAU,EAAE,CAAC;gBACjC,MAAM,IAAI,0BAA0B,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;YACrD,CAAC;YACD,OAAO,OAAO,CAAE,KAAuB,CAAC,IAAI,CAAC,CAAC,CAAC;QAChD,CAAC,CAAC;IACH,CAAC;IAED,2EAA2E;IAC3E,yEAAyE;IACzE,2DAA2D;IAC3D,OAAO,GAAG,EAAE;QACX,MAAM,IAAI,sBAAsB,CAAC,OAAO,KAAK,EAAE,MAAM,CAAC,CAAC;IACxD,CAAC,CAAC;AACH,CAAC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+DG;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,MAAM,UAAU,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,WAAW,CAAC,KAAK,EAAE,eAAe,CAAC,CAAC,CAAC;IAC9E,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC7B,OAAO,UAAU,CAAC,CAAC,CAAkB,CAAC;IACvC,CAAC;IAED,OAAO,CAAC,IAAI,EAAE,EAAE;QACf,KAAK,MAAM,QAAQ,IAAI,UAAU,EAAE,CAAC;YACnC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC;gBAAE,OAAO,KAAK,CAAC;QACnC,CAAC;QACD,OAAO,IAAI,CAAC;IACb,CAAC,CAAC;AACH,CAAC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;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,MAAM,UAAU,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,WAAW,CAAC,KAAK,EAAE,iBAAiB,CAAC,CAAC,CAAC;IAChF,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC7B,OAAO,UAAU,CAAC,CAAC,CAAkB,CAAC;IACvC,CAAC;IAED,OAAO,CAAC,IAAI,EAAE,EAAE;QACf,KAAK,MAAM,QAAQ,IAAI,UAAU,EAAE,CAAC;YACnC,IAAI,QAAQ,CAAC,IAAI,CAAC;gBAAE,OAAO,IAAI,CAAC;QACjC,CAAC;QACD,OAAO,KAAK,CAAC;IACd,CAAC,CAAC;AACH,CAAC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,8DAA8D;AAC9D,MAAM,CAAC,MAAM,WAAW,GAAG,CAC1B,KAAuC,EACvB,EAAE;IAClB,MAAM,QAAQ,GAAG,WAAW,CAAC,KAAK,EAAE,aAAa,CAAC,CAAC;IACnD,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;AAClC,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,9 +1,7 @@
 import type { Guard } from "./types.js";
 import type { PlayEvent } from "@xmachines/play";
 /**
- * Check if context has a truthy value at path
- *
- * Per CONTEXT.md: Convenience helper for common guard pattern
+ * Tells you if the context holds a value at the path, and that the value is truthy
  *
  * @example
  * ```typescript
@@ -15,12 +13,14 @@ import type { PlayEvent } from "@xmachines/play";
  * });
  * ```
  *
- * @param path - Dot-separated path to context property
- * @returns Guard predicate checking if property is truthy
+ * @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,24 +35,28 @@ export declare const hasContext: <TContext = Record<string, unknown>>(path: stri
  * });
  * ```
  *
- * @param eventType - Expected event type
- * @returns Guard predicate checking event type
+ * @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
+ * @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.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../src/guards/helpers.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAEjD;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,UAAU,GACrB,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,MAAM,KAAG,KAAK,CAAC,QAAQ,EAAE,SAAS,CAI5E,CAAC;AAEH;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,YAAY,GACvB,MAAM,SAAS,SAAS,GAAG,SAAS,EAAE,WAAW,MAAM,KAAG,KAAK,CAAC,OAAO,EAAE,MAAM,CAG/E,CAAC;AAEH;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,mBAAmB,GAC9B,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAClC,WAAW,MAAM,EACjB,eAAe,OAAO,KACpB,KAAK,CAAC,QAAQ,EAAE,SAAS,CAI3B,CAAC"}
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../src/guards/helpers.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAEjD;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,UAAU,GACrB,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,MAAM,KAAG,KAAK,CAAC,QAAQ,EAAE,SAAS,CAI5E,CAAC;AAEH;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,YAAY,GACvB,MAAM,SAAS,SAAS,GAAG,SAAS,EAAE,WAAW,MAAM,KAAG,KAAK,CAAC,OAAO,EAAE,MAAM,CAG/E,CAAC;AAEH;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,mBAAmB,GAC9B,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAClC,WAAW,MAAM,EACjB,eAAe,OAAO,KACpB,KAAK,CAAC,QAAQ,EAAE,SAAS,CAI3B,CAAC"}