@xmachines/play-xstate 2.2.0 → 4.0.0

package/dist/with-view.js

@@ -0,0 +1,150 @@
+import { Signal } from "@xmachines/play-signals";
+import { shallowEqualExcept } from "@xmachines/play";
+import { reuseComposedState } from "@xmachines/play-view";
+import { toError } from "./player-actor.js";
+import { deriveCurrentView } from "./view/derive-current-view.js";
+/**
+ * The structural equality of two derived view specs, with a limit on its depth.
+ *
+ * The function walks exactly the shape that `deriveCurrentView` builds: the spec
+ * fields, then `elements`, then the `props` object of each element. It compares
+ * each leaf with `Object.is`. It never enters the VALUE of a prop: a new reference
+ * therefore emits the view again, also when the contents are equal. This design
+ * keeps two things correct: a prop of a container (a Map, a Set, or an instance of a
+ * class, which a structural comparison cannot see), and a cyclic value, which gives
+ * a structural comparison a recursion without an end.
+ */
+const viewSpecsEquivalent = (a, b) => {
+    if (a === b)
+        return true;
+    if (!a || !b)
+        return false;
+    if (!shallowEqualExcept(a, b, "elements"))
+        return false;
+    const aElements = a.elements ?? {};
+    const bElements = b.elements ?? {};
+    // A derived spec spreads the same static meta.view. Therefore the elements
+    // usually have the same reference, and the walk over each element is then not
+    // necessary.
+    if (aElements === bElements)
+        return true;
+    const elementKeys = Object.keys(aElements);
+    if (elementKeys.length !== Object.keys(bElements).length)
+        return false;
+    for (const key of elementKeys) {
+        const aElement = aElements[key]; // nosemgrep: gitlab.eslint.detect-object-injection
+        const bElement = bElements[key]; // nosemgrep: gitlab.eslint.detect-object-injection
+        if (aElement === bElement)
+            continue;
+        if (!aElement || !bElement)
+            return false;
+        if (!shallowEqualExcept(aElement, bElement, "props"))
+            return false;
+        if (!shallowEqualExcept(aElement.props ?? {}, bElement.props ?? {}))
+            return false;
+    }
+    return true;
+};
+/**
+ * The last snapshot that the view pipeline of each actor read.
+ *
+ * A WeakMap at the module level, and not a field of the class: a `private` or a `#` field
+ * makes a class type NOMINAL, so the compiler then compares the mixin class with no other
+ * type and the return of this function needs `as unknown as`. The map holds the same state
+ * with no member, and it releases each entry with its actor.
+ *
+ * XState notifies each observer on EVERY event that it processes, and an event that it
+ * ignores delivers the identical snapshot again. `deriveCurrentView` is pure in the
+ * snapshot, so an identical reference can change no result. An actor that the map does not
+ * hold has read no snapshot yet, which is correct for the first derivation: the snapshot of
+ * the construction has the same reference as the snapshot that `start()` replays.
+ */
+const lastViewSnapshots = new WeakMap();
+/**
+ * Adds the view capability to an actor class.
+ *
+ * Compose it AFTER the routing capability. An override calls `super.onSnapshot()` first,
+ * so `compose(PlayerActor, withRouting, withView)` gives the route its new value before
+ * the view derives from the same transition. A router bridge therefore sees a guard
+ * redirect before a renderer sees the view of the state that the guard refused.
+ *
+ * @param Base - The actor class to extend, normally `PlayerActor` or the result of
+ *   another capability.
+ */
+export function withView(Base) {
+    class ViewableActor extends Base {
+        /**
+         * The reactive signal of the current view spec. The signal derives the spec from the
+         * `meta.view` metadata of the active state.
+         *
+         * It emits a **new object reference** on each real change of the view on the screen:
+         * the view of a different state, or a change of a param or of the context that changes
+         * the resolved spec. A re-entry with `reenter: true` and new params also changes the
+         * spec. A snapshot that changes no view on the screen, such as an assign of the
+         * context alone, keeps the previous reference. A provider below the signal therefore
+         * mounts the UI again not on every event.
+         *
+         * The `PlaySpec` of the emission carries the context of the machine in its composed
+         * `state` field, under the read-only `/context` subtree. A spec therefore reads the
+         * context, and also each URL param, through the ordinary state grammar
+         * (`{ $state: "/context/params/section" }`). The context-projection module of
+         * `@xmachines/play-view` holds the complete contract.
+         *
+         * The signal returns `null` when the current state has no `meta.view` metadata.
+         *
+         * Two states can declare two separate `meta.view` literals with an identical
+         * structure. A transition between those two states then emits two different
+         * references, and a provider mounts the UI again. Move the shared literal into one
+         * `typedSpec` constant, and the identity then removes the duplicate.
+         */
+        currentView = new Signal.State(null);
+        onSnapshot(snapshot) {
+            // FIRST, so that every capability composed before this one holds its new value.
+            super.onSnapshot(snapshot);
+            this.validateAndCacheView(snapshot);
+        }
+        /**
+         * Derives the view at the entry of a state, and keeps it. This happens one time for
+         * each transition. The signal holds the view, and the code computes it not on each
+         * read.
+         *
+         * @param snapshot - The current XState snapshot
+         */
+        validateAndCacheView(snapshot) {
+            if (snapshot === lastViewSnapshots.get(this)) {
+                return;
+            }
+            lastViewSnapshots.set(this, snapshot);
+            try {
+                const view = deriveCurrentView(snapshot);
+                // Emit only after a real change of the view on the screen: deriveCurrentView
+                // returns a fresh object on each call, and the identity of the reference therefore
+                // tells nothing. A new reference for a snapshot that changes the view not, for
+                // example a context-only assign, makes a provider below mount the UI again, and
+                // that removes the state of the view. A deep equality test is deliberately NOT
+                // here: it sees nothing inside a Map or a Set, and it therefore stops a real
+                // change, and it recurses without an end on a cyclic prop. The last spec of an
+                // emission IS the current value of the signal. Read it without a track, so that
+                // the gate registers currentView never as a dependency of a computation around it.
+                const lastEmittedView = Signal.subtle.untrack(() => this.currentView.get());
+                // Use the reference of the previous composed state again when the value of the
+                // /context projection did not change. A context-only assign that changes no
+                // projected value therefore changes the identity of the state not.
+                const nextView = reuseComposedState(lastEmittedView, view);
+                if (viewSpecsEquivalent(lastEmittedView, nextView)) {
+                    return;
+                }
+                this.currentView.set(nextView);
+            }
+            catch (error) {
+                const onError = this.hooks.onError;
+                if (onError) {
+                    onError(this, toError(error));
+                }
+                // On an error: keep the last valid view, and clear it not
+            }
+        }
+    }
+    return ViewableActor;
+}
+//# sourceMappingURL=with-view.js.map

package/dist/with-view.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"with-view.js","sourceRoot":"","sources":["../src/with-view.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xmachines/play-xstate",
-  "version": "2.2.0",
+  "version": "4.0.0",
   "description": "XState v5 adapter for Play Architecture",
   "keywords": [
     "actor-model",
@@ -10,7 +10,7 @@
     "xstate"
   ],
   "license": "MIT",
-  "author": "",
+  "author": "XMachines Contributors",
   "repository": {
     "type": "git",
     "url": "git+https://gitlab.com/xmachin-es/xmachines-js.git",
@@ -30,6 +30,14 @@
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
+    "./routing": {
+      "types": "./dist/with-routing.d.ts",
+      "default": "./dist/with-routing.js"
+    },
+    "./view": {
+      "types": "./dist/with-view.d.ts",
+      "default": "./dist/with-view.js"
+    },
     "./errors": {
       "types": "./dist/errors.d.ts",
       "default": "./dist/errors.js"
@@ -43,33 +51,46 @@
     "build": "vite build && tsc --build",
     "clean": "rm -rf dist *.tsbuildinfo coverage node_modules/.svelte2tsx-* node_modules/.vite*",
     "lint": "oxlint .",
+    "lint:security": "node ../../scripts/semgrep-scan.mjs",
     "format": "oxfmt .",
     "test": "vitest",
     "test:coverage": "vitest run --coverage"
   },
   "dependencies": {
-    "@xmachines/play": "2.2.0",
-    "@xmachines/play-actor": "2.2.0",
-    "@xmachines/play-signals": "2.2.0",
-    "dequal": "^2.0.3"
+    "@xmachines/play-actor": "4.0.0"
   },
   "devDependencies": {
-    "@testing-library/jest-dom": "^6.9.1",
-    "@types/node": "^26.2.0",
-    "@xmachines/json-render-core": "^0.20.0-xm.3",
-    "@xmachines/play-router": "2.2.0",
-    "oxfmt": "^0.64.0",
-    "oxlint": "^1.79.0",
+    "@testing-library/jest-dom": "^7.0.1",
+    "@types/node": "^26.6.2",
+    "@xmachines/json-render-core": "^0.20.0-xm.4",
+    "@xmachines/play": "4.0.0",
+    "@xmachines/play-router": "4.0.0",
+    "@xmachines/play-signals": "4.0.0",
+    "@xmachines/play-view": "4.0.0",
+    "oxfmt": "^0.68.0",
+    "oxlint": "^1.83.0",
     "typescript": "^5.9.3 || ^6.0.3",
-    "vite": "^8.0.10",
-    "vitest": "^4.1.11",
-    "xstate": "^5.31.0"
+    "vite": "^8.3.0",
+    "vitest": "^5.0.1",
+    "xstate": "^5.33.0"
   },
   "peerDependencies": {
-    "xstate": "^5.31.0"
+    "@xmachines/play": "4.0.0",
+    "@xmachines/play-router": "4.0.0",
+    "@xmachines/play-signals": "4.0.0",
+    "@xmachines/play-view": "4.0.0",
+    "xstate": "^5.33.0"
+  },
+  "peerDependenciesMeta": {
+    "@xmachines/play-view": {
+      "optional": true
+    },
+    "@xmachines/play-router": {
+      "optional": true
+    }
   },
   "engines": {
-    "node": ">=22.0.0"
+    "node": ">=24.0.0"
   },
-  "_devDependencies_note": "xstate appears in both peerDependencies and devDependencies intentionally. devDependencies provides workspace resolution for local builds, tests, and typechecking. peerDependencies declares the consumer version constraint. Both are pinned to ^5.30.0 to prevent drift."
+  "_devDependencies_note": "xstate appears in both peerDependencies and devDependencies intentionally. devDependencies provides workspace resolution for local builds, tests, and typechecking. peerDependencies declares the consumer version constraint. Both hold the same range, to prevent drift."
 }

package/dist/guards/compose.d.ts

@@ -1,158 +0,0 @@
-import type { GuardPredicate } from "xstate";
-import type { Guard, GuardArray } from "./types.js";
-import type { MachineContext, EventObject, ParameterizedObject } from "xstate";
-/**
- * The narrowest public return type of the guard composition helpers.
- *
- * `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 = GuardPredicate<MachineContext, EventObject, unknown, ParameterizedObject>;
-/**
- * Composes the guards with the AND logic, through the and() helper of XState
- *
- * 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:** 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 - The context type of the state machine
- * @typeParam TEvent - The event type
- *
- * @param guards - The array of the guard predicates, or of the guard names as strings
- * @returns The and() guard composition of XState
- *
- * @throws {Error} When the array of the guards is empty
- *
- * @example
- * An AND composition with named guards
- * ```typescript
- * import { setup } from "xstate";
- * import { composeGuards } from "@xmachines/play-xstate";
- *
- * const machine = setup({
- *   guards: {
- *     isLoggedIn: ({ context }) => !!context.userId,
- *     hasPermission: ({ context }) => context.permissions.includes('admin'),
- *   }
- * }).createMachine({
- *   on: {
- *     accessAdmin: {
- *       // Both guards must pass
- *       guard: composeGuards(['isLoggedIn', 'hasPermission']),
- *       target: 'adminPanel'
- *     }
- *   }
- * });
- * ```
- *
- * @example
- * An AND composition with inline predicates
- * ```typescript
- * import { composeGuards } from "@xmachines/play-xstate";
- *
- * guard: composeGuards([
- *   ({ context }) => context.age >= 18,
- *   ({ context }) => context.verified
- * ])
- * ```
- *
- * @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;
-/**
- * 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.
- *
- * @typeParam TContext - The context type of the state machine
- * @typeParam TEvent - The event type
- *
- * @param guards - The array of the guard predicates, or of the guard names
- * @returns The or() guard composition of XState
- *
- * @throws {Error} When the array of the guards is empty
- *
- * @example
- * An OR composition with named guards
- * ```typescript
- * import { setup } from "xstate";
- * import { composeGuardsOr } from "@xmachines/play-xstate";
- *
- * const machine = setup({
- *   guards: {
- *     isOwner: ({ context }) => context.role === 'owner',
- *     isAdmin: ({ context }) => context.role === 'admin'
- *   }
- * }).createMachine({
- *   on: {
- *     deleteResource: {
- *       // One guard is sufficient
- *       guard: composeGuardsOr(['isOwner', 'isAdmin']),
- *       actions: 'delete'
- *     }
- *   }
- * });
- * ```
- *
- * @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;
-/**
- * Negates a guard, through the not() helper of XState
- *
- * 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 - The context type of the state machine
- * @typeParam TEvent - The event type
- *
- * @param guard - The guard predicate to negate, or its name
- * @returns The not() guard negation of XState
- *
- * @example
- * A NOT composition with a named guard
- * ```typescript
- * import { setup } from "xstate";
- * import { negateGuard } from "@xmachines/play-xstate";
- *
- * const machine = setup({
- *   guards: {
- *     isGuest: ({ context }) => !context.userId
- *   }
- * }).createMachine({
- *   on: {
- *     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 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 +0,0 @@
-{"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,188 +0,0 @@
-import { and, or, not } from "xstate";
-import { EmptyGuardArrayError } from "../errors.js";
-/**
- * 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;
-/**
- * Composes the guards with the AND logic, through the and() helper of XState
- *
- * 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:** 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 - The context type of the state machine
- * @typeParam TEvent - The event type
- *
- * @param guards - The array of the guard predicates, or of the guard names as strings
- * @returns The and() guard composition of XState
- *
- * @throws {Error} When the array of the guards is empty
- *
- * @example
- * An AND composition with named guards
- * ```typescript
- * import { setup } from "xstate";
- * import { composeGuards } from "@xmachines/play-xstate";
- *
- * const machine = setup({
- *   guards: {
- *     isLoggedIn: ({ context }) => !!context.userId,
- *     hasPermission: ({ context }) => context.permissions.includes('admin'),
- *   }
- * }).createMachine({
- *   on: {
- *     accessAdmin: {
- *       // Both guards must pass
- *       guard: composeGuards(['isLoggedIn', 'hasPermission']),
- *       target: 'adminPanel'
- *     }
- *   }
- * });
- * ```
- *
- * @example
- * An AND composition with inline predicates
- * ```typescript
- * import { composeGuards } from "@xmachines/play-xstate";
- *
- * guard: composeGuards([
- *   ({ context }) => context.age >= 18,
- *   ({ context }) => context.verified
- * ])
- * ```
- *
- * @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");
-    }
-    if (guards.length === 1) {
-        // One guard passes through. asXStateGuard gives the reason for the boundary.
-        return asXStateGuard(guards[0]);
-    }
-    // Use the built-in and() of XState, for the type inference and the serialization.
-    return and(asXStateGuard(guards));
-};
-/**
- * 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.
- *
- * @typeParam TContext - The context type of the state machine
- * @typeParam TEvent - The event type
- *
- * @param guards - The array of the guard predicates, or of the guard names
- * @returns The or() guard composition of XState
- *
- * @throws {Error} When the array of the guards is empty
- *
- * @example
- * An OR composition with named guards
- * ```typescript
- * import { setup } from "xstate";
- * import { composeGuardsOr } from "@xmachines/play-xstate";
- *
- * const machine = setup({
- *   guards: {
- *     isOwner: ({ context }) => context.role === 'owner',
- *     isAdmin: ({ context }) => context.role === 'admin'
- *   }
- * }).createMachine({
- *   on: {
- *     deleteResource: {
- *       // One guard is sufficient
- *       guard: composeGuardsOr(['isOwner', 'isAdmin']),
- *       actions: 'delete'
- *     }
- *   }
- * });
- * ```
- *
- * @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");
-    }
-    if (guards.length === 1) {
-        // One guard passes through. asXStateGuard gives the reason for the boundary.
-        return asXStateGuard(guards[0]);
-    }
-    // Use the built-in or() of XState, for the type inference and the serialization.
-    return or(asXStateGuard(guards));
-};
-/**
- * Negates a guard, through the not() helper of XState
- *
- * 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 - The context type of the state machine
- * @typeParam TEvent - The event type
- *
- * @param guard - The guard predicate to negate, or its name
- * @returns The not() guard negation of XState
- *
- * @example
- * A NOT composition with a named guard
- * ```typescript
- * import { setup } from "xstate";
- * import { negateGuard } from "@xmachines/play-xstate";
- *
- * const machine = setup({
- *   guards: {
- *     isGuest: ({ context }) => !context.userId
- *   }
- * }).createMachine({
- *   on: {
- *     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 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 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 +0,0 @@
-{"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,62 +0,0 @@
-import type { Guard } from "./types.js";
-import type { PlayEvent } from "@xmachines/play";
-/**
- * Tells you if the context holds a value at the path, and that the value is truthy
- *
- * @example
- * ```typescript
- * const machine = setup({
- *   guards: {
- *     hasUserId: hasContext('userId'),
- *     hasEmail: hasContext('user.email')
- *   }
- * });
- * ```
- *
- * @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>;
-/**
- * Tells you if the type of the event is the expected type
- *
- * @example
- * ```typescript
- * const machine = setup({
- *   guards: {
- *     isSubmitEvent: eventMatches('submit'),
- *     isBackOrForward: composeGuardsOr([
- *       eventMatches('back'),
- *       eventMatches('forward')
- *     ])
- *   }
- * });
- * ```
- *
- * @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>;
-/**
- * Tells you if a context field holds the expected value.
- *
- * - 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 a match of an XState state node, use the built-in `in:` guard syntax 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.d.ts.map

@@ -1 +0,0 @@
-{"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"}