@xmachines/play-router 2.0.0 → 2.1.0

package/dist/query.js

@@ -1,28 +1,28 @@
 import { getSuccessors, hasNode, hasPath } from "@statelyai/graph";
 /**
- * Get the routable successor nodes of a state — states directly reachable via
- * transition edges that have a defined `meta.route`.
+ * Returns the successor nodes of a state that have a route: the states of a direct
+ * transition edge that hold a `meta.route` field.
  *
- * Shared traversal core for `getTransitionReachableStateIds` and
- * `getTransitionReachableRoutes`; returns full nodes so callers can project
- * whichever field they need (stateId vs raw route string).
+ * `getTransitionReachableStateIds` and `getTransitionReachableRoutes` share this
+ * walk. The function returns the complete nodes. Therefore each caller reads the
+ * field that it needs: the stateId, or the raw route string.
  */
 const getRoutableSuccessors = (graph, stateId) => 
-// A state ID with no graph node (e.g. a non-routable or removed state) is a
-// normal "nothing reachable" outcome, checked explicitly rather than by
-// pattern-matching thrown error messages.
+// A state ID without a graph node, for example a state without a route or a state
+// that a person removed, is a normal result of "nothing to reach". The code tests
+// that case explicitly, and it matches no message of an error from a throw.
 hasNode(graph, stateId)
     ? getSuccessors(graph, stateId).filter((n) => n.data.route !== undefined)
     : [];
 /**
- * Get all routes navigable from given state
+ * Returns every route of a navigation from the given state
  *
- * Returns child routes of the specified state. Future enhancement will
- * include sibling routes reachable via transitions.
+ * The function returns the child routes of the state. A later version also returns
+ * the sibling routes of a transition.
  *
- * @param tree - Route tree from extractMachineRoutes()
- * @param stateId - Current state ID
- * @returns Array of route nodes reachable from state
+ * @param tree - The route tree, from extractMachineRoutes()
+ * @param stateId - The ID of the current state
+ * @returns The array of the route nodes that the state can reach
  *
  * @example
  * ```typescript
@@ -35,12 +35,13 @@ export const getNavigableRoutes = (tree, stateId) => {
     const node = tree.byStateId.get(stateId);
     if (!node)
         return [];
-    const results = [...node.children]; // Direct child routes (existing behavior)
-    // If graph is available, also include routes reachable via transitions.
-    // Look nodes up by state ID: graph nodes carry the RAW meta.route string
-    // (possibly relative, e.g. "detail"), while tree.byPath is keyed by resolved
-    // fullPath ("/section/detail") — a path-based lookup would silently drop
-    // every relative route. State IDs are unambiguous in both structures.
+    const results = [...node.children]; // The direct child routes
+    // With a graph, the result also holds each route that a transition can reach.
+    // The code looks each node up by its state ID: a graph node carries the RAW
+    // meta.route string, and that string can be relative, for example "detail". The
+    // keys of tree.byPath are the resolved fullPath values, for example
+    // "/section/detail". A lookup by the path therefore loses every relative route in
+    // silence. A state ID is unambiguous in both structures.
     if (tree.graph) {
         const reachableStateIds = getTransitionReachableStateIds(tree.graph, stateId);
         const existingPaths = new Set(results.map((r) => r.fullPath));
@@ -55,24 +56,26 @@ export const getNavigableRoutes = (tree, stateId) => {
     return results;
 };
 /**
- * Get state IDs of routable states reachable via transitions from a state.
+ * Returns the state IDs of the states with a route that a transition from a state
+ * can reach.
  *
- * Same traversal as `getTransitionReachableRoutes`, but returns state IDs
- * instead of raw `meta.route` strings so callers can resolve nodes through
- * `tree.byStateId` without raw-vs-resolved path ambiguity.
+ * The walk is the same as the walk of `getTransitionReachableRoutes`, but this
+ * function returns the state IDs, and not the raw `meta.route` strings. A caller
+ * therefore resolves each node through `tree.byStateId`, with no doubt between a raw
+ * path and a resolved path.
  */
 const getTransitionReachableStateIds = (graph, stateId) => {
     return getRoutableSuccessors(graph, stateId).map((n) => n.data.stateId);
 };
 /**
- * Get all routable routes from tree as flat array
+ * Returns every route of the tree that has a route, in one flat array
  *
- * Returns all routes that have meta.route defined, excluding non-routable
- * states and the synthetic root node. Useful for dynamically generating
- * router configurations in framework adapters.
+ * The function returns each route with a `meta.route` field. It returns no state
+ * without a route, and no synthetic root node. Use it to generate a router
+ * configuration in a framework adapter dynamically.
  *
- * @param tree - Route tree from extractMachineRoutes()
- * @returns Array of routable route nodes with path and stateId
+ * @param tree - The route tree, from extractMachineRoutes()
+ * @returns The array of the route nodes with a route, with their path and their stateId
  *
  * @example
  * ```typescript
@@ -88,7 +91,7 @@ const getTransitionReachableStateIds = (graph, stateId) => {
 export const getRoutableRoutes = (tree) => {
     const routes = [];
     for (const node of tree.byStateId.values()) {
-        // Include only routable nodes (have meta.route), exclude synthetic root
+        // Keep the nodes with a route, which means the nodes with a meta.route field, and skip the synthetic root
         if (node.routable && node.id !== "__root__") {
             routes.push(node);
         }
@@ -96,39 +99,40 @@ export const getRoutableRoutes = (tree) => {
     return routes;
 };
 /**
- * Validate route path exists in tree
+ * Tells you if a route path is in the tree
  *
- * Checks if path has corresponding state with meta.route.
+ * The function tests if the path has a state with a `meta.route` field.
  *
- * @param tree - Route tree from extractMachineRoutes()
- * @param path - Full route path (e.g., '/dashboard/settings')
- * @returns true if path exists, false otherwise
+ * @param tree - The route tree, from extractMachineRoutes()
+ * @param path - The complete route path, for example '/dashboard/settings'
+ * @returns true when the tree holds the path. In every other case, false
  */
 export const routeExists = (tree, path) => {
     return tree.byPath.has(path);
 };
 /**
- * Get routes reachable via transitions from current state
+ * Returns the routes that a transition from the current state can reach
  *
- * Uses the @statelyai/graph successor algorithm to find all states
- * directly reachable via transition edges from the given state,
- * then filters to those with defined routes.
+ * The function uses the successor algorithm of @statelyai/graph. It finds every
+ * state of a direct transition edge from the given state, then it keeps the states
+ * with a route.
  *
- * Returned values are the RAW `meta.route` strings from the machine — relative
- * routes (e.g. `"detail"`) are NOT resolved to full paths and cannot be used as
- * `tree.byPath` keys. For resolved `RouteNode`s use `getNavigableRoutes`, which
- * resolves reachable states through `tree.byStateId`.
+ * The values of the return are the RAW `meta.route` strings of the machine. The
+ * function does NOT resolve a relative route, for example `"detail"`, to a complete
+ * path, and such a value is therefore no key of `tree.byPath`. For a resolved
+ * `RouteNode`, use `getNavigableRoutes`: that function resolves each state that the
+ * transition reaches through `tree.byStateId`.
  *
- * @param graph - Machine graph from RouteTree.graph
- * @param stateId - Current state ID (e.g., "test.home")
- * @returns Array of raw route strings reachable via transitions
+ * @param graph - The machine graph, from RouteTree.graph
+ * @param stateId - The ID of the current state, for example "test.home"
+ * @returns The array of the raw route strings that a transition can reach
  *
  * @example
  * ```typescript
  * const tree = extractMachineRoutes(machine);
  * if (tree.graph) {
  *   const reachable = getTransitionReachableRoutes(tree.graph, 'auth.loggedIn');
- *   // ['/dashboard', '/settings'] — routes reachable via transitions
+ *   // ['/dashboard', '/settings'] — the routes that a transition can reach
  * }
  * ```
  */
@@ -136,27 +140,28 @@ export const getTransitionReachableRoutes = (graph, stateId) => {
     return getRoutableSuccessors(graph, stateId).map((n) => n.data.route);
 };
 /**
- * Check if a route is reachable from current state via transitions
+ * Tells you if a transition from the current state can reach a route
  *
- * Uses @statelyai/graph path-finding to determine if there exists
- * a chain of transition edges from the source state to the target state.
+ * The function uses the path search of @statelyai/graph. It decides if a chain of
+ * transition edges is present from the state of the origin to the state of the
+ * target.
  *
- * @param graph - Machine graph from RouteTree.graph
- * @param fromStateId - Source state ID
- * @param toStateId - Target state ID
- * @returns true if a transition path exists, false otherwise
+ * @param graph - The machine graph, from RouteTree.graph
+ * @param fromStateId - The ID of the state of the origin
+ * @param toStateId - The ID of the state of the target
+ * @returns true when a transition path is present. In every other case, false
  *
  * @example
  * ```typescript
  * const tree = extractMachineRoutes(machine);
  * if (tree.graph) {
  *   const canReach = isRouteReachable(tree.graph, 'auth.login', 'auth.dashboard');
- *   // true if login → dashboard transition path exists
+ *   // it is true when a transition path from login to dashboard is present
  * }
  * ```
  */
 export const isRouteReachable = (graph, fromStateId, toStateId) => {
-    // Missing endpoints are a normal "not reachable" outcome.
+    // An absent endpoint is a normal result of "not reachable".
     return hasNode(graph, fromStateId) && hasNode(graph, toStateId)
         ? hasPath(graph, fromStateId, toStateId)
         : false;

package/dist/query.js.map

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