@xmachines/play-xstate 6.1.0 → 7.0.0

package/dist/routing/derive-route.js

@@ -1,256 +1,239 @@
 import { InvalidRouteHandlerError, InvalidRouteMetadataError } from "../errors.js";
+//#region packages/play-xstate/src/routing/derive-route.ts
 /**
- * Derives the route from the metadata of an XState state
- *
- * The function reads the URL template of the route from the `meta.route` field in
- * the metadata of the active state. It supports a string route (`"/about"`) and also
- * an object route with a path property (`{ path: "/about" }`). It returns null for a
- * state without route metadata, because not every state needs a route.
- *
- * **Architectural context:** the function implements **Actor Authority (INV-01)**,
- * because it reads the routing information from the state machine definition, and
- * not from an external configuration. The current state of the Actor decides the
- * route, and no decision of the infrastructure decides it.
- *
- * @param stateMeta - The state metadata from snapshot.getMeta()
- * @returns The template of the route path, which can hold a :param, or null when the function finds no route
- *
- * @example
- * The basic read of a route
- * ```typescript
- * import { deriveRoute } from "@xmachines/play-xstate/routing";
- * import { setup } from "xstate";
- *
- * const machine = setup({}).createMachine({
- *   states: {
- *     about: {
- *       meta: { route: "/about", view: { component: "AboutPage" } }
- *     }
- *   }
- * });
- *
- * const actor = createActor(machine);
- * actor.start();
- * const snapshot = actor.getSnapshot();
- * const meta = snapshot.getMeta();
- *
- * const route = deriveRoute(meta);
- * console.log(route); // "/about"
- * ```
- *
- * @example
- * A route with a parameter
- * ```typescript
- * const machine = setup({}).createMachine({
- *   states: {
- *     profile: {
- *       meta: {
- *         route: "/profile/:userId",
- *         view: { component: "ProfilePage", userId: (ctx) => ctx.userId }
- *       }
- *     }
- *   }
- * });
- *
- * const route = deriveRoute(snapshot.getMeta());
- * console.log(route); // "/profile/:userId" — the template, before the substitution
- * ```
- *
- * @example
- * The object form of a route
- * ```typescript
- * const machine = setup({}).createMachine({
- *   states: {
- *     dashboard: {
- *       meta: {
- *         route: { path: "/dashboard" },
- *         view: { component: "Dashboard" }
- *       }
- *     }
- *   }
- * });
- *
- * const route = deriveRoute(snapshot.getMeta());
- * console.log(route); // "/dashboard"
- * ```
- *
- * @see [Play RFC](../../../docs/rfc/play.md)
- * @see {@link buildRouteUrl} for the construction of a URL, with the substitution of each parameter
- * @see {@link isAbsoluteRoute} for the test of an absolute path
- *
- * @remarks
- * This function reads the route definition from `meta.route`. A state with a
- * `route: {}` config has a route. {@link buildRouteUrl} substitutes each parameter,
- * and this function does not: deriveRoute returns a template.
- *
- * **A state without a route:** a state without a `meta.route` field gives `null`.
- * This is deliberate, because not every state needs a route. An intermediate loading
- * state and a substate, for example, often have no URL of their own.
- */
-export const deriveRoute = (stateMeta) => {
-    // snapshot.getMeta() puts the keys of the ancestors first. Fold each entry with a
-    // route from the top to the bottom. The meta.route of the deepest active state
-    // therefore wins over the route of an ancestor, and a RELATIVE route resolves
-    // against its nearest ancestors with a route. The tree resolution of play-router
-    // does the same: the fullPath of a child is the fullPath of its parent, then "/",
-    // then its own path.
-    let resolved = null;
-    for (const meta of Object.values(stateMeta)) {
-        if (typeof meta !== "object" || meta === null)
-            continue;
-        if (!("route" in meta) || !meta.route)
-            continue;
-        const route = normalizeRoute(meta.route);
-        if (typeof route !== "string" || route === "")
-            continue;
-        if (isAbsoluteRoute(route)) {
-            resolved = route;
-        }
-        else {
-            const base = resolved === null || resolved === "/" ? "" : resolved;
-            resolved = `${base}/${route}`;
-        }
-    }
-    return resolved;
+* Derives the route from the metadata of an XState state
+*
+* The function reads the URL template of the route from the `meta.route` field in
+* the metadata of the active state. It supports a string route (`"/about"`) and also
+* an object route with a path property (`{ path: "/about" }`). It returns null for a
+* state without route metadata, because not every state needs a route.
+*
+* **Architectural context:** the function implements **Actor Authority (INV-01)**,
+* because it reads the routing information from the state machine definition, and
+* not from an external configuration. The current state of the Actor decides the
+* route, and no decision of the infrastructure decides it.
+*
+* @param stateMeta - The state metadata from snapshot.getMeta()
+* @returns The template of the route path, which can hold a :param, or null when the function finds no route
+*
+* @example
+* The basic read of a route
+* ```typescript
+* import { deriveRoute } from "@xmachines/play-xstate/routing";
+* import { setup } from "xstate";
+*
+* const machine = setup({}).createMachine({
+*   states: {
+*     about: {
+*       meta: { route: "/about", view: { component: "AboutPage" } }
+*     }
+*   }
+* });
+*
+* const actor = createActor(machine);
+* actor.start();
+* const snapshot = actor.getSnapshot();
+* const meta = snapshot.getMeta();
+*
+* const route = deriveRoute(meta);
+* console.log(route); // "/about"
+* ```
+*
+* @example
+* A route with a parameter
+* ```typescript
+* const machine = setup({}).createMachine({
+*   states: {
+*     profile: {
+*       meta: {
+*         route: "/profile/:userId",
+*         view: { component: "ProfilePage", userId: (ctx) => ctx.userId }
+*       }
+*     }
+*   }
+* });
+*
+* const route = deriveRoute(snapshot.getMeta());
+* console.log(route); // "/profile/:userId" — the template, before the substitution
+* ```
+*
+* @example
+* The object form of a route
+* ```typescript
+* const machine = setup({}).createMachine({
+*   states: {
+*     dashboard: {
+*       meta: {
+*         route: { path: "/dashboard" },
+*         view: { component: "Dashboard" }
+*       }
+*     }
+*   }
+* });
+*
+* const route = deriveRoute(snapshot.getMeta());
+* console.log(route); // "/dashboard"
+* ```
+*
+* @see [Play RFC](../../../docs/rfc/play.md)
+* @see {@link buildRouteUrl} for the construction of a URL, with the substitution of each parameter
+* @see {@link isAbsoluteRoute} for the test of an absolute path
+*
+* @remarks
+* This function reads the route definition from `meta.route`. A state with a
+* `route: {}` config has a route. {@link buildRouteUrl} substitutes each parameter,
+* and this function does not: deriveRoute returns a template.
+*
+* **A state without a route:** a state without a `meta.route` field gives `null`.
+* This is deliberate, because not every state needs a route. An intermediate loading
+* state and a substate, for example, often have no URL of their own.
+*/
+var deriveRoute = (stateMeta) => {
+	let resolved = null;
+	for (const meta of Object.values(stateMeta)) {
+		if (typeof meta !== "object" || meta === null) continue;
+		if (!("route" in meta) || !meta.route) continue;
+		const route = normalizeRoute(meta.route);
+		if (typeof route !== "string" || route === "") continue;
+		if (isAbsoluteRoute(route)) resolved = route;
+		else resolved = `${resolved === null || resolved === "/" ? "" : resolved}/${route}`;
+	}
+	return resolved;
 };
 /**
- * Normalizes the route metadata into a string path
- *
- * The function handles the string form and the object form of a route definition.
- * The output is therefore always a string, for the construction of the URL.
- *
- * @param route - The route metadata: a string, or an object with a path property
- * @param source - The `PlayError.scope` value to report for invalid metadata. The
- *   default is `"deriveRoute"`
- * @returns The normalized string of the route path
- * @throws {InvalidRouteMetadataError} When the form of the route is invalid
- */
-export const normalizeRoute = (route, source = "deriveRoute") => {
-    if (typeof route === "string") {
-        return route;
-    }
-    // A route object, with a path property
-    if (route && typeof route === "object" && "path" in route) {
-        return route.path;
-    }
-    throw new InvalidRouteMetadataError(route, source);
+* Normalizes the route metadata into a string path
+*
+* The function handles the string form and the object form of a route definition.
+* The output is therefore always a string, for the construction of the URL.
+*
+* @param route - The route metadata: a string, or an object with a path property
+* @param source - The `PlayError.scope` value to report for invalid metadata. The
+*   default is `"deriveRoute"`
+* @returns The normalized string of the route path
+* @throws {InvalidRouteMetadataError} When the form of the route is invalid
+*/
+var normalizeRoute = (route, source = "deriveRoute") => {
+	if (typeof route === "string") return route;
+	if (route && typeof route === "object" && "path" in route) return route.path;
+	throw new InvalidRouteMetadataError(route, source);
 };
 /**
- * Reads the `reenter` flag of the route metadata.
- *
- * The string form of the metadata declares no flag, and the object form declares the
- * flag only when it wants one. Both therefore give `false`, which is the default of
- * XState for a transition. A state without a route gives `false` too, so the caller
- * needs no test of its own for that case.
- *
- * The function does NOT check the form of the metadata. `normalizeRoute` runs first at
- * every call site and throws `InvalidRouteMetadataError` on a malformed value.
- *
- * @param route - The route metadata: a string, an object with a `path` property, or
- *   `undefined` for a state that declares no route
- * @returns The declared flag, or `false` where the metadata declares none
- *
- * @example
- * ```typescript
- * routeReenter("/dashboard");                       // false
- * routeReenter({ path: "/dashboard" });             // false
- * routeReenter({ path: "/dashboard", reenter: true }); // true
- * routeReenter(undefined);                          // false
- * ```
- */
-export const routeReenter = (route) => typeof route === "object" && route !== null && route.reenter === true;
+* Reads the `reenter` flag of the route metadata.
+*
+* The string form of the metadata declares no flag, and the object form declares the
+* flag only when it wants one. Both therefore give `false`, which is the default of
+* XState for a transition. A state without a route gives `false` too, so the caller
+* needs no test of its own for that case.
+*
+* The function does NOT check the form of the metadata. `normalizeRoute` runs first at
+* every call site and throws `InvalidRouteMetadataError` on a malformed value.
+*
+* @param route - The route metadata: a string, an object with a `path` property, or
+*   `undefined` for a state that declares no route
+* @returns The declared flag, or `false` where the metadata declares none
+*
+* @example
+* ```typescript
+* routeReenter("/dashboard");                       // false
+* routeReenter({ path: "/dashboard" });             // false
+* routeReenter({ path: "/dashboard", reenter: true }); // true
+* routeReenter(undefined);                          // false
+* ```
+*/
+var routeReenter = (route) => typeof route === "object" && route !== null && route.reenter === true;
 /**
- * Reads the extra data that a route declares, resolved for one event.
- *
- * The field holds a literal value or a function of `{ context, event }`, which is the
- * `WithDynamicParams` shape of XState. This function collapses the two into the value.
- *
- * The function does NOT check the form of the metadata. `normalizeRoute` runs first at
- * every call site and throws `InvalidRouteMetadataError` on a malformed value.
- *
- * @param route - The route metadata: a string, an object with a `path` property, or
- *   `undefined` for a state that declares no route
- * @param args - The context of the machine and the `play.route` event that asks for the
- *   route. The resolver reads them.
- * @returns The data, or `undefined` where the route declares none
- *
- * @example
- * ```typescript
- * routeData({ path: "/a", data: { titleKey: "a" } }, args);        // { titleKey: "a" }
- * routeData({ path: "/a", data: ({ event }) => ({ to: event.to }) }, args);
- * routeData("/a", args);                                          // undefined
- * ```
- */
-export const routeData = (route, args) => {
-    if (typeof route !== "object" || route === null)
-        return undefined;
-    const data = route.data;
-    if (data === undefined)
-        return undefined;
-    return typeof data === "function" ? data(args) : data;
+* Reads the extra data that a route declares, resolved for one event.
+*
+* The field holds a literal value or a function of `{ context, event }`, which is the
+* `WithDynamicParams` shape of XState. This function collapses the two into the value.
+*
+* The function does NOT check the form of the metadata. `normalizeRoute` runs first at
+* every call site and throws `InvalidRouteMetadataError` on a malformed value.
+*
+* @param route - The route metadata: a string, an object with a `path` property, or
+*   `undefined` for a state that declares no route
+* @param args - The context of the machine and the `play.route` event that asks for the
+*   route. The resolver reads them.
+* @returns The data, or `undefined` where the route declares none
+*
+* @example
+* ```typescript
+* routeData({ path: "/a", data: { titleKey: "a" } }, args);        // { titleKey: "a" }
+* routeData({ path: "/a", data: ({ event }) => ({ to: event.to }) }, args);
+* routeData("/a", args);                                          // undefined
+* ```
+*/
+var routeData = (route, args) => {
+	if (typeof route !== "object" || route === null) return void 0;
+	const data = route.data;
+	if (data === void 0) return void 0;
+	return typeof data === "function" ? data(args) : data;
 };
 /** The placements that a `meta.route` object can declare. */
-const ROUTE_HANDLERS = new Set(["root", "local", "both"]);
+var ROUTE_HANDLERS = /* @__PURE__ */ new Set([
+	"root",
+	"local",
+	"both"
+]);
 /**
- * Reads the placement of the generated `play.route` transition.
- *
- * `"root"` is the default, and it is the placement of XState: every route transition
- * sits on the root of the machine. `"local"` moves the transition to the parent of the
- * state, and `"both"` puts one transition in each place.
- *
- * The function does NOT check the form of the metadata. `normalizeRoute` runs first at
- * every call site and throws `InvalidRouteMetadataError` on a malformed value.
- *
- * @param route - The route metadata: a string, an object with a `path` property, or
- *   `undefined` for a state that declares no route
- * @param source - The `PlayError.scope` value to report for an unknown placement
- * @returns The declared placement, and `"root"` where the metadata declares none
- * @throws {InvalidRouteHandlerError} When the object declares a `handler` that is not
- *   `"root"`, `"local"`, or `"both"`. A typo would otherwise fall back to a placement
- *   that the author did not ask for, and it would change which states a route reaches.
- *
- * @example
- * ```typescript
- * routeHandler("/dashboard");                             // "root"
- * routeHandler({ path: "/dashboard" });                   // "root"
- * routeHandler({ path: "/dashboard", handler: "local" }); // "local"
- * routeHandler({ path: "/dashboard", handler: "both" });  // "both"
- * routeHandler({ path: "/dashboard", handler: "locale" }); // throws
- * ```
- */
-export const routeHandler = (route, source = "formatPlayRouteTransitions") => {
-    if (typeof route !== "object" || route === null)
-        return "root";
-    const handler = route.handler;
-    if (handler === undefined)
-        return "root";
-    if (typeof handler !== "string" || !ROUTE_HANDLERS.has(handler)) {
-        throw new InvalidRouteHandlerError(handler, source);
-    }
-    return handler;
+* Reads the placement of the generated `play.route` transition.
+*
+* `"root"` is the default, and it is the placement of XState: every route transition
+* sits on the root of the machine. `"local"` moves the transition to the parent of the
+* state, and `"both"` puts one transition in each place.
+*
+* The function does NOT check the form of the metadata. `normalizeRoute` runs first at
+* every call site and throws `InvalidRouteMetadataError` on a malformed value.
+*
+* @param route - The route metadata: a string, an object with a `path` property, or
+*   `undefined` for a state that declares no route
+* @param source - The `PlayError.scope` value to report for an unknown placement
+* @returns The declared placement, and `"root"` where the metadata declares none
+* @throws {InvalidRouteHandlerError} When the object declares a `handler` that is not
+*   `"root"`, `"local"`, or `"both"`. A typo would otherwise fall back to a placement
+*   that the author did not ask for, and it would change which states a route reaches.
+*
+* @example
+* ```typescript
+* routeHandler("/dashboard");                             // "root"
+* routeHandler({ path: "/dashboard" });                   // "root"
+* routeHandler({ path: "/dashboard", handler: "local" }); // "local"
+* routeHandler({ path: "/dashboard", handler: "both" });  // "both"
+* routeHandler({ path: "/dashboard", handler: "locale" }); // throws
+* ```
+*/
+var routeHandler = (route, source = "formatPlayRouteTransitions") => {
+	if (typeof route !== "object" || route === null) return "root";
+	const handler = route.handler;
+	if (handler === void 0) return "root";
+	if (typeof handler !== "string" || !ROUTE_HANDLERS.has(handler)) throw new InvalidRouteHandlerError(handler, source);
+	return handler;
 };
 /**
- * Tells you if the route path is absolute
- *
- * The function decides if a route path is absolute, which means that it starts with
- * `/`, or relative. An absolute path inherits nothing from a parent route. A
- * relative path joins a parent path, for a nested routing.
- *
- * @param path - The route path to test
- * @returns true when the path starts with '/'. In every other case, false
- *
- * @example
- * ```typescript
- * import { isAbsoluteRoute } from "@xmachines/play-xstate/routing";
- *
- * console.log(isAbsoluteRoute("/dashboard")); // true
- * console.log(isAbsoluteRoute("settings"));   // false
- * console.log(isAbsoluteRoute("./about"));    // false
- * ```
- *
- * @see {@link deriveRoute} for the read of a route
- */
-export const isAbsoluteRoute = (path) => {
-    return path.startsWith("/");
+* Tells you if the route path is absolute
+*
+* The function decides if a route path is absolute, which means that it starts with
+* `/`, or relative. An absolute path inherits nothing from a parent route. A
+* relative path joins a parent path, for a nested routing.
+*
+* @param path - The route path to test
+* @returns true when the path starts with '/'. In every other case, false
+*
+* @example
+* ```typescript
+* import { isAbsoluteRoute } from "@xmachines/play-xstate/routing";
+*
+* console.log(isAbsoluteRoute("/dashboard")); // true
+* console.log(isAbsoluteRoute("settings"));   // false
+* console.log(isAbsoluteRoute("./about"));    // false
+* ```
+*
+* @see {@link deriveRoute} for the read of a route
+*/
+var isAbsoluteRoute = (path) => {
+	return path.startsWith("/");
 };
+//#endregion
+export { deriveRoute, isAbsoluteRoute, normalizeRoute, routeData, routeHandler, routeReenter };
+
 //# sourceMappingURL=derive-route.js.map

package/dist/routing/derive-route.js.map

@@ -1 +1 @@
-{"version":3,"file":"derive-route.js","sourceRoot":"","sources":["../../src/routing/derive-route.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"derive-route.js","names":[],"sources":["../../src/routing/derive-route.ts"],"sourcesContent":["import type { PlayRouteEvent, RouteData } from \"@xmachines/play-router\";\nimport type { RouteMetadata, RouteObject } from \"./types.js\";\nimport { InvalidRouteHandlerError, InvalidRouteMetadataError } from \"../errors.js\";\n\n/**\n * Derives the route from the metadata of an XState state\n *\n * The function reads the URL template of the route from the `meta.route` field in\n * the metadata of the active state. It supports a string route (`\"/about\"`) and also\n * an object route with a path property (`{ path: \"/about\" }`). It returns null for a\n * state without route metadata, because not every state needs a route.\n *\n * **Architectural context:** the function implements **Actor Authority (INV-01)**,\n * because it reads the routing information from the state machine definition, and\n * not from an external configuration. The current state of the Actor decides the\n * route, and no decision of the infrastructure decides it.\n *\n * @param stateMeta - The state metadata from snapshot.getMeta()\n * @returns The template of the route path, which can hold a :param, or null when the function finds no route\n *\n * @example\n * The basic read of a route\n * ```typescript\n * import { deriveRoute } from \"@xmachines/play-xstate/routing\";\n * import { setup } from \"xstate\";\n *\n * const machine = setup({}).createMachine({\n *   states: {\n *     about: {\n *       meta: { route: \"/about\", view: { component: \"AboutPage\" } }\n *     }\n *   }\n * });\n *\n * const actor = createActor(machine);\n * actor.start();\n * const snapshot = actor.getSnapshot();\n * const meta = snapshot.getMeta();\n *\n * const route = deriveRoute(meta);\n * console.log(route); // \"/about\"\n * ```\n *\n * @example\n * A route with a parameter\n * ```typescript\n * const machine = setup({}).createMachine({\n *   states: {\n *     profile: {\n *       meta: {\n *         route: \"/profile/:userId\",\n *         view: { component: \"ProfilePage\", userId: (ctx) => ctx.userId }\n *       }\n *     }\n *   }\n * });\n *\n * const route = deriveRoute(snapshot.getMeta());\n * console.log(route); // \"/profile/:userId\" — the template, before the substitution\n * ```\n *\n * @example\n * The object form of a route\n * ```typescript\n * const machine = setup({}).createMachine({\n *   states: {\n *     dashboard: {\n *       meta: {\n *         route: { path: \"/dashboard\" },\n *         view: { component: \"Dashboard\" }\n *       }\n *     }\n *   }\n * });\n *\n * const route = deriveRoute(snapshot.getMeta());\n * console.log(route); // \"/dashboard\"\n * ```\n *\n * @see [Play RFC](../../../docs/rfc/play.md)\n * @see {@link buildRouteUrl} for the construction of a URL, with the substitution of each parameter\n * @see {@link isAbsoluteRoute} for the test of an absolute path\n *\n * @remarks\n * This function reads the route definition from `meta.route`. A state with a\n * `route: {}` config has a route. {@link buildRouteUrl} substitutes each parameter,\n * and this function does not: deriveRoute returns a template.\n *\n * **A state without a route:** a state without a `meta.route` field gives `null`.\n * This is deliberate, because not every state needs a route. An intermediate loading\n * state and a substate, for example, often have no URL of their own.\n */\nexport const deriveRoute = (stateMeta: Record<string, unknown>): string | null => {\n\t// snapshot.getMeta() puts the keys of the ancestors first. Fold each entry with a\n\t// route from the top to the bottom. The meta.route of the deepest active state\n\t// therefore wins over the route of an ancestor, and a RELATIVE route resolves\n\t// against its nearest ancestors with a route. The tree resolution of play-router\n\t// does the same: the fullPath of a child is the fullPath of its parent, then \"/\",\n\t// then its own path.\n\tlet resolved: string | null = null;\n\tfor (const meta of Object.values(stateMeta)) {\n\t\tif (typeof meta !== \"object\" || meta === null) continue;\n\t\tif (!(\"route\" in meta) || !meta.route) continue;\n\n\t\tconst route = normalizeRoute(meta.route as RouteMetadata);\n\t\tif (typeof route !== \"string\" || route === \"\") continue;\n\t\tif (isAbsoluteRoute(route)) {\n\t\t\tresolved = route;\n\t\t} else {\n\t\t\tconst base: string = resolved === null || resolved === \"/\" ? \"\" : resolved;\n\t\t\tresolved = `${base}/${route}`;\n\t\t}\n\t}\n\n\treturn resolved;\n};\n\n/**\n * Normalizes the route metadata into a string path\n *\n * The function handles the string form and the object form of a route definition.\n * The output is therefore always a string, for the construction of the URL.\n *\n * @param route - The route metadata: a string, or an object with a path property\n * @param source - The `PlayError.scope` value to report for invalid metadata. The\n *   default is `\"deriveRoute\"`\n * @returns The normalized string of the route path\n * @throws {InvalidRouteMetadataError} When the form of the route is invalid\n */\nexport const normalizeRoute = (route: RouteMetadata, source = \"deriveRoute\"): string => {\n\tif (typeof route === \"string\") {\n\t\treturn route;\n\t}\n\n\t// A route object, with a path property\n\tif (route && typeof route === \"object\" && \"path\" in route) {\n\t\treturn (route as RouteObject).path;\n\t}\n\n\tthrow new InvalidRouteMetadataError(route, source);\n};\n\n/**\n * Reads the `reenter` flag of the route metadata.\n *\n * The string form of the metadata declares no flag, and the object form declares the\n * flag only when it wants one. Both therefore give `false`, which is the default of\n * XState for a transition. A state without a route gives `false` too, so the caller\n * needs no test of its own for that case.\n *\n * The function does NOT check the form of the metadata. `normalizeRoute` runs first at\n * every call site and throws `InvalidRouteMetadataError` on a malformed value.\n *\n * @param route - The route metadata: a string, an object with a `path` property, or\n *   `undefined` for a state that declares no route\n * @returns The declared flag, or `false` where the metadata declares none\n *\n * @example\n * ```typescript\n * routeReenter(\"/dashboard\");                       // false\n * routeReenter({ path: \"/dashboard\" });             // false\n * routeReenter({ path: \"/dashboard\", reenter: true }); // true\n * routeReenter(undefined);                          // false\n * ```\n */\nexport const routeReenter = (route: RouteMetadata | undefined): boolean =>\n\ttypeof route === \"object\" && route !== null && (route as RouteObject).reenter === true;\n\n/**\n * Reads the extra data that a route declares, resolved for one event.\n *\n * The field holds a literal value or a function of `{ context, event }`, which is the\n * `WithDynamicParams` shape of XState. This function collapses the two into the value.\n *\n * The function does NOT check the form of the metadata. `normalizeRoute` runs first at\n * every call site and throws `InvalidRouteMetadataError` on a malformed value.\n *\n * @param route - The route metadata: a string, an object with a `path` property, or\n *   `undefined` for a state that declares no route\n * @param args - The context of the machine and the `play.route` event that asks for the\n *   route. The resolver reads them.\n * @returns The data, or `undefined` where the route declares none\n *\n * @example\n * ```typescript\n * routeData({ path: \"/a\", data: { titleKey: \"a\" } }, args);        // { titleKey: \"a\" }\n * routeData({ path: \"/a\", data: ({ event }) => ({ to: event.to }) }, args);\n * routeData(\"/a\", args);                                          // undefined\n * ```\n */\nexport const routeData = (\n\troute: RouteMetadata | undefined,\n\targs: { context: unknown; event: PlayRouteEvent },\n): RouteData | undefined => {\n\tif (typeof route !== \"object\" || route === null) return undefined;\n\n\tconst data = (route as RouteObject).data;\n\tif (data === undefined) return undefined;\n\n\treturn typeof data === \"function\" ? data(args) : data;\n};\n\n/** The placements that a `meta.route` object can declare. */\nconst ROUTE_HANDLERS = new Set([\"root\", \"local\", \"both\"]);\n\n/**\n * Reads the placement of the generated `play.route` transition.\n *\n * `\"root\"` is the default, and it is the placement of XState: every route transition\n * sits on the root of the machine. `\"local\"` moves the transition to the parent of the\n * state, and `\"both\"` puts one transition in each place.\n *\n * The function does NOT check the form of the metadata. `normalizeRoute` runs first at\n * every call site and throws `InvalidRouteMetadataError` on a malformed value.\n *\n * @param route - The route metadata: a string, an object with a `path` property, or\n *   `undefined` for a state that declares no route\n * @param source - The `PlayError.scope` value to report for an unknown placement\n * @returns The declared placement, and `\"root\"` where the metadata declares none\n * @throws {InvalidRouteHandlerError} When the object declares a `handler` that is not\n *   `\"root\"`, `\"local\"`, or `\"both\"`. A typo would otherwise fall back to a placement\n *   that the author did not ask for, and it would change which states a route reaches.\n *\n * @example\n * ```typescript\n * routeHandler(\"/dashboard\");                             // \"root\"\n * routeHandler({ path: \"/dashboard\" });                   // \"root\"\n * routeHandler({ path: \"/dashboard\", handler: \"local\" }); // \"local\"\n * routeHandler({ path: \"/dashboard\", handler: \"both\" });  // \"both\"\n * routeHandler({ path: \"/dashboard\", handler: \"locale\" }); // throws\n * ```\n */\nexport const routeHandler = (\n\troute: RouteMetadata | undefined,\n\tsource = \"formatPlayRouteTransitions\",\n): \"root\" | \"local\" | \"both\" => {\n\tif (typeof route !== \"object\" || route === null) return \"root\";\n\n\tconst handler = (route as RouteObject).handler;\n\tif (handler === undefined) return \"root\";\n\tif (typeof handler !== \"string\" || !ROUTE_HANDLERS.has(handler)) {\n\t\tthrow new InvalidRouteHandlerError(handler, source);\n\t}\n\n\treturn handler as \"root\" | \"local\" | \"both\";\n};\n\n/**\n * Tells you if the route path is absolute\n *\n * The function decides if a route path is absolute, which means that it starts with\n * `/`, or relative. An absolute path inherits nothing from a parent route. A\n * relative path joins a parent path, for a nested routing.\n *\n * @param path - The route path to test\n * @returns true when the path starts with '/'. In every other case, false\n *\n * @example\n * ```typescript\n * import { isAbsoluteRoute } from \"@xmachines/play-xstate/routing\";\n *\n * console.log(isAbsoluteRoute(\"/dashboard\")); // true\n * console.log(isAbsoluteRoute(\"settings\"));   // false\n * console.log(isAbsoluteRoute(\"./about\"));    // false\n * ```\n *\n * @see {@link deriveRoute} for the read of a route\n */\nexport const isAbsoluteRoute = (path: string): boolean => {\n\treturn path.startsWith(\"/\");\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4FA,IAAa,eAAe,cAAsD;CAOjF,IAAI,WAA0B;CAC9B,KAAK,MAAM,QAAQ,OAAO,OAAO,SAAS,GAAG;EAC5C,IAAI,OAAO,SAAS,YAAY,SAAS,MAAM;EAC/C,IAAI,EAAE,WAAW,SAAS,CAAC,KAAK,OAAO;EAEvC,MAAM,QAAQ,eAAe,KAAK,KAAsB;EACxD,IAAI,OAAO,UAAU,YAAY,UAAU,IAAI;EAC/C,IAAI,gBAAgB,KAAK,GACxB,WAAW;OAGX,WAAW,GADU,aAAa,QAAQ,aAAa,MAAM,KAAK,SAC/C,GAAG;CAExB;CAEA,OAAO;AACR;;;;;;;;;;;;;AAcA,IAAa,kBAAkB,OAAsB,SAAS,kBAA0B;CACvF,IAAI,OAAO,UAAU,UACpB,OAAO;CAIR,IAAI,SAAS,OAAO,UAAU,YAAY,UAAU,OACnD,OAAQ,MAAsB;CAG/B,MAAM,IAAI,0BAA0B,OAAO,MAAM;AAClD;;;;;;;;;;;;;;;;;;;;;;;;AAyBA,IAAa,gBAAgB,UAC5B,OAAO,UAAU,YAAY,UAAU,QAAS,MAAsB,YAAY;;;;;;;;;;;;;;;;;;;;;;;AAwBnF,IAAa,aACZ,OACA,SAC2B;CAC3B,IAAI,OAAO,UAAU,YAAY,UAAU,MAAM,OAAO,KAAA;CAExD,MAAM,OAAQ,MAAsB;CACpC,IAAI,SAAS,KAAA,GAAW,OAAO,KAAA;CAE/B,OAAO,OAAO,SAAS,aAAa,KAAK,IAAI,IAAI;AAClD;;AAGA,IAAM,iCAAiB,IAAI,IAAI;CAAC;CAAQ;CAAS;AAAM,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6BxD,IAAa,gBACZ,OACA,SAAS,iCACsB;CAC/B,IAAI,OAAO,UAAU,YAAY,UAAU,MAAM,OAAO;CAExD,MAAM,UAAW,MAAsB;CACvC,IAAI,YAAY,KAAA,GAAW,OAAO;CAClC,IAAI,OAAO,YAAY,YAAY,CAAC,eAAe,IAAI,OAAO,GAC7D,MAAM,IAAI,yBAAyB,SAAS,MAAM;CAGnD,OAAO;AACR;;;;;;;;;;;;;;;;;;;;;;AAuBA,IAAa,mBAAmB,SAA0B;CACzD,OAAO,KAAK,WAAW,GAAG;AAC3B"}