@xmachines/play-xstate 3.0.0 → 5.0.0

package/dist/with-view.js

@@ -0,0 +1,158 @@
+import { createAtom } from "@xmachines/play-atom";
+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;
+};
+/**
+ * Two WeakMaps stood here, and the derivation below needs neither.
+ *
+ * `lastViewSnapshots` skipped the derivation for a snapshot that the pipeline read
+ * already, because XState notifies each observer on EVERY event that it processes and an
+ * event that it ignores delivers the identical snapshot again. A computed atom answers
+ * that by itself: `state.set(snapshot)` compares with `Object.is`, an identical reference
+ * therefore propagates nothing, and this atom stays valid.
+ *
+ * `lastEmittedViews` held the previous emission for the equality gate, because a read of
+ * `currentView` would have registered it as a dependency of the computation around the
+ * call and `@xstate/store` exports no `untrack`. The `previous` parameter of a computed
+ * atom is that same value, and the engine hands it in rather than tracking a read.
+ */
+/**
+ * Adds the view capability to an actor class.
+ *
+ * The ORDER of the composition does not matter. `currentView` and `currentRoute` are two
+ * computed atoms over `state`, and neither reads the other, so the engine evaluates both
+ * from one write in topological order. An earlier release wrote `currentView` from an
+ * `onSnapshot` override, and the order then decided which capability held its new value
+ * first.
+ *
+ * @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 atom of the current view spec. The atom 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 atom 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 atom 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.
+         *
+         * It is a COMPUTED atom over `state`, and not a written one. One write for each
+         * transition therefore reaches the whole actor — `state.set(snapshot)` — and the
+         * engine evaluates this atom and `currentRoute` in one propagation, in topological
+         * order. A second write would flush a second time, and an observer that reads two
+         * atoms would see the new state beside the old view in between.
+         */
+        currentView = createAtom((previous) => {
+            // `previous` is the value that this atom holds already. The engine hands it in,
+            // so the gate below reads it without a `get()`, and it therefore registers
+            // `currentView` as a dependency of nothing.
+            const lastEmittedView = previous ?? null;
+            try {
+                const view = deriveCurrentView(this.state.get());
+                // 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.
+                //
+                // A return of `lastEmittedView` compares equal under `Object.is`, so the atom
+                // notifies no subscriber and the propagation stops here.
+                const nextView = reuseComposedState(lastEmittedView, view);
+                return viewSpecsEquivalent(lastEmittedView, nextView)
+                    ? lastEmittedView
+                    : nextView;
+            }
+            catch (error) {
+                // The derivation runs inside the `set` of `state`, which runs inside the XState
+                // subscription. A throw that leaves this function therefore leaves that `set`
+                // and breaks the transition for every other observer of the actor. Report it,
+                // and keep the last valid view.
+                //
+                // The derivation runs inside the `set` of `state`, and the engine TRACKS every
+                // atom that this function reads — the handler of the host included. A report
+                // from HERE therefore made whatever that handler reads a dependency of this
+                // atom, and an unrelated write of it re-derived and reported again: three
+                // reports for one failure. The microtask leaves the evaluation, so the handler
+                // reads what it likes and this atom depends on none of it.
+                //
+                // It leaves the `set` as well, which is what the comment below already needed:
+                // a throw from the handler lands on the global handler of the runtime, and it
+                // breaks the transition for no other observer of the actor.
+                const onError = this.hooks.onError;
+                if (onError) {
+                    const reported = toError(error);
+                    queueMicrotask(() => {
+                        onError(this, reported);
+                    });
+                }
+                return lastEmittedView;
+            }
+        });
+    }
+    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,16 +1,16 @@
 {
   "name": "@xmachines/play-xstate",
-  "version": "3.0.0",
+  "version": "5.0.0",
   "description": "XState v5 adapter for Play Architecture",
   "keywords": [
     "actor-model",
+    "atoms",
     "play-architecture",
-    "signals",
     "state-machine",
     "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,47 @@
     "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": "3.0.0",
-    "@xmachines/play-actor": "3.0.0",
-    "@xmachines/play-signals": "3.0.0",
-    "dequal": "^2.0.3"
+    "@xmachines/play-actor": "5.0.0",
+    "@xmachines/play-pattern": "5.0.0"
   },
   "devDependencies": {
-    "@testing-library/jest-dom": "^6.9.1",
-    "@types/node": "^26.2.0",
+    "@testing-library/jest-dom": "^7.0.1",
+    "@types/node": "^26.6.2",
     "@xmachines/json-render-core": "^0.20.0-xm.4",
-    "@xmachines/play-router": "3.0.0",
-    "oxfmt": "^0.64.0",
-    "oxlint": "^1.79.0",
+    "@xmachines/play": "5.0.0",
+    "@xmachines/play-atom": "5.0.0",
+    "@xmachines/play-router": "5.0.0",
+    "@xmachines/play-view": "5.0.0",
+    "oxfmt": "^0.70.0",
+    "oxlint": "^1.85.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": "5.0.0",
+    "@xmachines/play-atom": "5.0.0",
+    "@xmachines/play-router": "5.0.0",
+    "@xmachines/play-view": "5.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"}