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

package/dist/errors.js

@@ -1,4 +1,24 @@
 import { PlayError } from "@xmachines/play";
+/**
+ * Stringify a thrown value without trusting it: `String()` itself throws for
+ * a null-prototype object or a value whose `toString`/`Symbol.toPrimitive`
+ * throw, and this runs inside the error path — a second throw here would
+ * replace the machine's real failure with a `TypeError` and bypass `onError`.
+ */
+const safeString = (value) => {
+    try {
+        return String(value);
+    }
+    catch {
+        try {
+            return Object.prototype.toString.call(value);
+        }
+        catch {
+            // A revoked Proxy throws even on brand inspection.
+            return "[unrepresentable value]";
+        }
+    }
+};
 /**
  * Thrown by `buildRouteUrl()` when a required route parameter is absent from the
  * actor's context.
@@ -8,16 +28,17 @@ import { PlayError } from "@xmachines/play";
  *
  * **Error code:** `PLAY_XSTATE_ROUTE_PARAM_MISSING`
  *
+ * Note: `actor.currentRoute.get()` never surfaces this error — route
+ * derivation catches it and returns `null` for the transient mid-transition
+ * case. It only escapes direct `buildRouteUrl()` calls.
+ *
  * @example
  * ```typescript
+ * import { buildRouteUrl } from "@xmachines/play-xstate";
  * import { MissingRouteParamError } from "@xmachines/play-xstate/errors";
  *
- * // The route template "/profile/:userId" requires "userId" in context.
- * // If userId is absent, MissingRouteParamError is thrown when the
- * // actor.currentRoute signal is read.
- *
  * try {
- *   actor.currentRoute.get();
+ *   buildRouteUrl("/profile/:userId", { params: {}, query: {} });
  * } catch (err) {
  *   if (err instanceof MissingRouteParamError) {
  *     console.error(
@@ -40,36 +61,18 @@ export class MissingRouteParamError extends PlayError {
     }
 }
 /**
- * Thrown by `buildRouteUrl()` when the context has a `params` field (indicating a
- * routing-aware machine context) but no `query` field.
- *
- * The `params` field signals the context was set up for routing (either manually or via
- * `formatPlayRouteTransitions`). A routing-aware context without `query` will silently
- * drop any query parameters carried by `play.route` events, producing incorrect URLs.
+ * @deprecated Never thrown any more. `buildRouteUrl` treats a missing `query`
+ * field as `query: {}` — the generated `play.route` transitions assign
+ * `query` on every navigation, so the loss this error guarded against cannot
+ * occur through route derivation. Machines that handle `play.route` by hand
+ * and want query forwarding must assign `event.query` to context themselves.
+ * Kept exported so existing `instanceof` handlers keep compiling; remove them
+ * at leisure.
  *
- * **Fix:** Ensure the machine context type includes `query: Record<string, string>`
- * and that the context initializer sets `query: {}` (or a populated value).
- * If using `formatPlayRouteTransitions`, the field is assigned automatically on each
- * `play.route` event — but the machine's initial context must still declare it.
+ * Formerly thrown by `buildRouteUrl()` when the context had a `params` field
+ * (a routing-aware machine context) but no `query` field.
  *
  * **Error code:** `PLAY_XSTATE_MISSING_QUERY_CONTEXT`
- *
- * @example
- * ```typescript
- * import { MissingQueryContextError } from "@xmachines/play-xstate/errors";
- *
- * try {
- *   // params present but no query field — throws
- *   buildRouteUrl("/profile/:userId", { params: { userId: "42" } });
- * } catch (err) {
- *   if (err instanceof MissingQueryContextError) {
- *     console.error("Machine context missing query field");
- *   }
- * }
- *
- * // Correct — both params and query declared
- * buildRouteUrl("/profile/:userId", { params: { userId: "42" }, query: {} });
- * ```
  */
 export class MissingQueryContextError extends PlayError {
     constructor() {
@@ -165,51 +168,6 @@ export class EmptyGuardArrayError extends PlayError {
         this.combinator = combinator;
     }
 }
-/**
- * Thrown when a composed guard cannot resolve a string guard name at call time.
- *
- * String names in `composeGuards`/`composeGuardsOr`/`negateGuard` resolve
- * against `args.guards` — the named guards from `setup({ guards })` that
- * XState v6 provides to transition functions, `always`, entry/exit actions
- * (since 6.0.0-alpha.20), and function-form route resolvers. Resolution fails
- * when the name was never declared or when the composed guard is called
- * without transition arguments.
- *
- * **Error code:** `PLAY_XSTATE_UNRESOLVABLE_GUARD_NAME`
- */
-export class UnresolvableGuardNameError extends PlayError {
-    /** The guard name that could not be resolved. */
-    guardName;
-    constructor(guardName, origin) {
-        super(origin, "PLAY_XSTATE_UNRESOLVABLE_GUARD_NAME", `Guard "${guardName}" is not a function. Either the name was never declared ` +
-            `in setup({ guards }) or the composed guard was called without ` +
-            `transition arguments.`);
-        this.name = "UnresolvableGuardNameError";
-        this.guardName = guardName;
-    }
-}
-/**
- * Thrown when a composed guard evaluates an entry that is neither a predicate
- * function nor a guard name — typically `null`/`undefined` from a typo'd
- * import or an optional lookup.
- *
- * XState v5 failed loudly when evaluating such entries; silently treating them
- * as never-passing would turn `negateGuard(undefined)` into an always-allow.
- * Composition stays lazy (no throw at compose time); evaluation throws.
- *
- * **Error code:** `PLAY_XSTATE_INVALID_GUARD_ENTRY`
- */
-export class InvalidGuardEntryError extends PlayError {
-    /** `typeof` of the invalid entry (e.g. `"undefined"`, `"object"` for null). */
-    entryType;
-    constructor(entryType, origin) {
-        super(origin, "PLAY_XSTATE_INVALID_GUARD_ENTRY", `Guard entry of type "${entryType}" is neither a predicate function nor a ` +
-            `guard name. Check for typo'd imports or optional lookups that resolved ` +
-            `to null/undefined.`);
-        this.name = "InvalidGuardEntryError";
-        this.entryType = entryType;
-    }
-}
 /**
  * Thrown by `PlayerActor.send()` when the event argument is not a plain object.
  *
@@ -244,4 +202,38 @@ export class InvalidEventError extends PlayError {
         this.detail = detail;
     }
 }
+/**
+ * Passed to `PlayerOptions.onError` when the actor failed with a value that is
+ * not an `Error` — e.g. a machine action ran `throw { code: 42 }`.
+ *
+ * An actor error that *is* an `Error` reaches `onError` untouched, keeping the
+ * identity the machine gave it. Only this case constructs a new error, so it
+ * carries a matchable code instead of a `String(value)` message such as
+ * `"[object Object]"`. The thrown value is preserved on `cause`.
+ *
+ * **Error code:** `PLAY_XSTATE_NON_ERROR_THROWN`
+ *
+ * @example
+ * ```typescript
+ * import { ActorThrewNonErrorError } from "@xmachines/play-xstate/errors";
+ *
+ * definePlayer({
+ *   machine,
+ *   options: {
+ *     onError: (actor, err) => {
+ *       if (err instanceof ActorThrewNonErrorError) {
+ *         // err.cause is the value the machine actually threw
+ *         console.error("Machine threw a non-Error:", err.cause);
+ *       }
+ *     },
+ *   },
+ * });
+ * ```
+ */
+export class ActorThrewNonErrorError extends PlayError {
+    constructor(value) {
+        super("PlayerActor", "PLAY_XSTATE_NON_ERROR_THROWN", `PlayerActor failed with a non-Error value: ${safeString(value)}.`, { cause: value });
+        this.name = "ActorThrewNonErrorError";
+    }
+}
 //# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAE5C;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,OAAO,sBAAuB,SAAQ,SAAS;IACpD,0EAA0E;IACjE,KAAK,CAAS;IAEvB,0FAA0F;IACjF,QAAQ,CAAS;IAE1B,YAAY,KAAa,EAAE,QAAgB;QAC1C,KAAK,CACJ,eAAe,EACf,iCAAiC,EACjC,oBAAoB,KAAK,8BAA8B,QAAQ,iCAAiC,CAChG,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;QACrC,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAC1B,CAAC;CACD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,OAAO,wBAAyB,SAAQ,SAAS;IACtD;QACC,KAAK,CACJ,eAAe,EACf,mCAAmC,EACnC,8DAA8D;YAC7D,0EAA0E;YAC1E,0FAA0F,CAC3F,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,0BAA0B,CAAC;IACxC,CAAC;CACD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,OAAO,mBAAoB,SAAQ,SAAS;IACjD,oFAAoF;IAC3E,QAAQ,CAAS;IAC1B,8EAA8E;IACrE,KAAK,CAAS;IAEvB,YAAY,QAAgB,EAAE,KAAa;QAC1C,KAAK,CACJ,4BAA4B,EAC5B,8BAA8B,EAC9B,UAAU,QAAQ,0BAA0B,KAAK,4BAA4B;YAC5E,YAAY,QAAQ,2DAA2D,CAChF,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;QAClC,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACpB,CAAC;CACD;AAED;;;;;GAKG;AACH,MAAM,OAAO,mBAAoB,SAAQ,SAAS;IACjD;QACC,KAAK,CACJ,aAAa,EACb,6BAA6B,EAC7B,6CAA6C,CAC7C,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;IACnC,CAAC;CACD;AAED;;;;;GAKG;AACH,MAAM,OAAO,yBAA0B,SAAQ,SAAS;IACvD,oEAAoE;IAC3D,MAAM,CAAS;IAExB,YAAY,KAAc,EAAE,MAAM,GAAG,aAAa;QACjD,MAAM,MAAM,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;QACrC,KAAK,CACJ,MAAM,EACN,oCAAoC,EACpC,2BAA2B,MAAM,uCAAuC,CACxE,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,2BAA2B,CAAC;QACxC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACtB,CAAC;CACD;AAED;;;;;GAKG;AACH,MAAM,OAAO,oBAAqB,SAAQ,SAAS;IAClD,8EAA8E;IACrE,UAAU,CAAe;IAElC,YAAY,UAAwB;QACnC,KAAK,CACJ,UAAU,KAAK,KAAK,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,iBAAiB,EAC1D,+BAA+B,EAC/B,GAAG,UAAU,KAAK,KAAK,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,iBAAiB,8BAA8B,CAC3F,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;QACnC,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;IAC9B,CAAC;CACD;AAQD;;;;;;;;;;;GAWG;AACH,MAAM,OAAO,0BAA2B,SAAQ,SAAS;IACxD,iDAAiD;IACxC,SAAS,CAAS;IAE3B,YAAY,SAAiB,EAAE,MAAuB;QACrD,KAAK,CACJ,MAAM,EACN,qCAAqC,EACrC,UAAU,SAAS,0DAA0D;YAC5E,gEAAgE;YAChE,uBAAuB,CACxB,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,4BAA4B,CAAC;QACzC,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;IAC5B,CAAC;CACD;AAED;;;;;;;;;;GAUG;AACH,MAAM,OAAO,sBAAuB,SAAQ,SAAS;IACpD,+EAA+E;IACtE,SAAS,CAAS;IAE3B,YAAY,SAAiB,EAAE,MAAuB;QACrD,KAAK,CACJ,MAAM,EACN,iCAAiC,EACjC,wBAAwB,SAAS,0CAA0C;YAC1E,yEAAyE;YACzE,oBAAoB,CACrB,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;QACrC,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;IAC5B,CAAC;CACD;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,OAAO,iBAAkB,SAAQ,SAAS;IAC/C,8CAA8C;IACrC,MAAM,CAAU;IAEzB,YAAY,MAAe;QAC1B,KAAK,CACJ,aAAa,EACb,2BAA2B,EAC3B,iDAAiD,CACjD,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;QAChC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACtB,CAAC;CACD"}
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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"}

package/dist/guards/compose.d.ts

@@ -1,50 +1,35 @@
+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.
+ * Narrowest public return type for 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
+ * widest-compatible concrete XState guard type that does not use `any`.
  *
  * @public
+ * @deprecated The guard utilities will be removed in the next major — use
+ * XState's own combinator types directly.
  */
-export type ComposedGuard = (args: unknown) => boolean;
+export type ComposedGuard = GuardPredicate<MachineContext, EventObject, unknown, ParameterizedObject>;
 /**
- * Compose guards with AND logic.
+ * Compose guards with AND logic using XState's and() helper
  *
  * Combines multiple guard predicates using AND semantics—all guards must pass for
- * the composition to succeed. Evaluation is short-circuiting, left to right.
+ * the composition to succeed. Uses XState's built-in `and()` helper to ensure proper
+ * type inference and machine serialization.
  *
  * **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.
  *
- * **XState v6:** the composed value is a plain predicate. Call it inside a
- * transition function and return early to block the transition:
- *
- * @typeParam TContext - State machine context type (defaults to `any` so the
- *   documented inline-predicate examples compile without annotations)
- * @typeParam TEvent - Event type
- *
- * @typeParam TContext - State machine context type (defaults to `any` so the
- *   documented inline-predicate examples compile without annotations)
+ * @typeParam TContext - State machine context type
  * @typeParam TEvent - 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 - Array of guard predicates or guard names (string references)
+ * @returns XState and() guard composition
  *
- * @throws {EmptyGuardArrayError} If guards array is empty
+ * @throws {Error} If guards array is empty
  *
  * @example
  * AND composition with named guards
@@ -52,8 +37,6 @@ export type ComposedGuard = (args: unknown) => boolean;
  * import { setup } from "xstate";
  * import { composeGuards } from "@xmachines/play-xstate";
  *
- * const canAccessAdmin = composeGuards(['isLoggedIn', 'hasPermission']);
- *
  * const machine = setup({
  *   guards: {
  *     isLoggedIn: ({ context }) => !!context.userId,
@@ -61,9 +44,10 @@ 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'
  *     }
  *   }
  * });
@@ -74,27 +58,32 @@ export type ComposedGuard = (args: unknown) => boolean;
  * ```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
+ * @deprecated Use XState's own `and()`/`or()`/`not()` directly — this helper does not
+ * compose with `setup()`-typed guard slots and will be removed in the next major.
  */
 export declare const composeGuards: <TContext = any, TEvent = any>(guards: GuardArray<TContext, TEvent>) => ComposedGuard;
 /**
- * Compose guards with OR logic.
+ * Compose guards with OR logic using XState's or() helper
  *
  * 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.
+ * for the composition to succeed. Uses XState's built-in `or()` helper for proper
+ * type inference.
+ *
+ * @typeParam TContext - State machine context type
+ * @typeParam TEvent - 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 - Array of guard predicates or guard names
+ * @returns XState or() guard composition
  *
- * @throws {EmptyGuardArrayError} If guards array is empty
+ * @throws {Error} If guards array is empty
  *
  * @example
  * OR composition with named guards
@@ -102,8 +91,6 @@ export declare const composeGuards: <TContext = any, TEvent = any>(guards: Guard
  * 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,9 +98,10 @@ export declare const composeGuards: <TContext = any, TEvent = any>(guards: Guard
  *   }
  * }).createMachine({
  *   on: {
- *     deleteResource: (args, enq) => {
- *       if (!canDelete(args)) return;
- *       enq(() => deleteIt());
+ *     deleteResource: {
+ *       // Either guard can pass
+ *       guard: composeGuardsOr(['isOwner', 'isAdmin']),
+ *       actions: 'delete'
  *     }
  *   }
  * });
@@ -121,20 +109,21 @@ export declare const composeGuards: <TContext = any, TEvent = any>(guards: Guard
  *
  * @see {@link composeGuards} for AND composition
  * @see {@link negateGuard} for NOT logic
+ * @deprecated Use XState's own `and()`/`or()`/`not()` directly — this helper does not
+ * compose with `setup()`-typed guard slots and will be removed in the next major.
  */
 export declare const composeGuardsOr: <TContext = any, TEvent = any>(guards: GuardArray<TContext, TEvent>) => ComposedGuard;
 /**
- * Negate a guard.
+ * Negate a guard using XState's not() helper
  *
  * Inverts a guard's result—if the guard passes, NOT fails; if guard fails, NOT passes.
+ * Uses XState's built-in `not()` helper for proper serialization.
  *
- * @typeParam TContext - State machine context type (defaults to `any` so
- *   inline predicates compile without annotations)
+ * @typeParam TContext - State machine context type
  * @typeParam TEvent - 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 - Guard predicate or guard name to negate
+ * @returns XState not() guard negation
  *
  * @example
  * NOT composition with named guard
@@ -142,17 +131,16 @@ export declare const composeGuardsOr: <TContext = any, TEvent = any>(guards: Gua
  * 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: {
+ *       // Allow if NOT a guest (i.e., authenticated)
+ *       guard: negateGuard('isGuest'),
+ *       target: 'dashboard'
  *     }
  *   }
  * });
@@ -160,6 +148,8 @@ export declare const composeGuardsOr: <TContext = any, TEvent = any>(guards: Gua
  *
  * @see {@link composeGuards} for AND composition
  * @see {@link composeGuardsOr} for OR composition
+ * @deprecated Use XState's own `and()`/`or()`/`not()` directly — this helper does not
+ * compose with `setup()`-typed guard slots and will be removed in the next major.
  */
 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;AAkB/E;;;;;;;;;GASG;AACH,MAAM,MAAM,aAAa,GAAG,cAAc,CACzC,cAAc,EACd,WAAW,EACX,OAAO,EACP,mBAAmB,CACnB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AAEH,eAAO,MAAM,aAAa,GAAI,QAAQ,GAAG,GAAG,EAAE,MAAM,GAAG,GAAG,EACzD,QAAQ,UAAU,CAAC,QAAQ,EAAE,MAAM,CAAC,KAClC,aAYF,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAEH,eAAO,MAAM,eAAe,GAAI,QAAQ,GAAG,GAAG,EAAE,MAAM,GAAG,GAAG,EAC3D,QAAQ,UAAU,CAAC,QAAQ,EAAE,MAAM,CAAC,KAClC,aAYF,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,eAAO,MAAM,WAAW,GAAI,QAAQ,GAAG,GAAG,EAAE,MAAM,GAAG,GAAG,EACvD,OAAO,KAAK,CAAC,QAAQ,EAAE,MAAM,CAAC,GAAG,MAAM,KACrC,aAIF,CAAC"}