@koordinates/xstate-tree 2.0.11 → 3.0.0-beta.2

package/lib/routing/createRoute/createRoute.js

@@ -1,6 +1,5 @@
 import { match, compile } from "path-to-regexp";
 import { parse, stringify } from "query-string";
-import { isNil } from "../../utils";
 import { joinRoutes } from "../joinRoutes";
 /**
  * @public
@@ -19,163 +18,137 @@ export function buildCreateRoute(history, basePath) {
         });
     }
     return {
-        /**
-         * Creates a dynamic Route using the supplied options
-         *
-         * The return value of dynamicRoute is a function that accepts the routes "dynamic" options
-         * The argument to dynamicRoute itself is the params/query/meta schemas defining the route
-         *
-         * The returned function accepts a singular option object with the following fields
-         *
-         * `event`, the string constant for the routes event
-         * `matches`, a function that is passed a url/query string and determines if the route matches
-         * if the route is matched it returns the extracted params/query objects
-         * `reverse`, a function that is passed params/query objects and turns them into a URL
-         *
-         * The params and query schemas are ZodSchemas, they both need to be an object (ie Z.object())
-         */
-        dynamicRoute: function createDynamicRoute(opts) {
-            return ({ event, matches, reverse, }) => {
-                return {
-                    paramsSchema: opts === null || opts === void 0 ? void 0 : opts.params,
-                    querySchema: opts === null || opts === void 0 ? void 0 : opts.query,
-                    event,
-                    history,
-                    basePath,
-                    parent: undefined,
-                    // @ts-ignore the usual
-                    getEvent({ params, query, meta } = {}) {
-                        return { type: event, params, query, meta };
-                    },
-                    // @ts-ignore not sure how to type this
-                    matches(url, search) {
-                        const query = parse(search);
-                        const match = matches(url, query);
+        simpleRoute(baseRoute) {
+            return ({ url, paramsSchema, querySchema, ...args }) => {
+                const matcher = match(url, { end: false });
+                const reverser = compile(url);
+                return this.route(baseRoute)({
+                    ...args,
+                    paramsSchema,
+                    querySchema,
+                    // @ts-ignore :cry:
+                    matcher: (url, query) => {
+                        const match = matcher(url);
                         if (match === false) {
-                            return undefined;
+                            return false;
                         }
-                        if ((opts === null || opts === void 0 ? void 0 : opts.params) && "params" in match) {
-                            opts.params.parse(match.params);
+                        const params = match.params;
+                        if (params && paramsSchema) {
+                            paramsSchema.parse(params);
                         }
-                        if ((opts === null || opts === void 0 ? void 0 : opts.query) && "query" in match) {
-                            opts.query.parse(match.query);
+                        if (query && querySchema) {
+                            querySchema.parse(query);
                         }
-                        return { type: event, originalUrl: `${url}${search}`, ...match };
-                    },
-                    // @ts-ignore not sure how to type this correctly
-                    // The types from external to this function are correct however
-                    reverse({ params, query } = {}) {
-                        return reverse({ params, query });
+                        return {
+                            matchLength: match.path.length,
+                            params,
+                            query,
+                        };
                     },
-                    // @ts-ignore not sure how to type this correctly
-                    // The types from external to this function are correct however
-                    navigate({ params, query, meta } = {}) {
-                        // @ts-ignore same problem
-                        const url = this.reverse({ params, query });
-                        navigate({
-                            url: joinRoutes(this.basePath, url),
-                            meta,
-                            history: this.history,
-                        });
+                    // @ts-ignore :cry:
+                    reverser: (args) => {
+                        const url = reverser(args.params);
+                        if (args.query) {
+                            return `${url}?${stringify(args.query)}`;
+                        }
+                        return url;
                     },
-                };
+                });
             };
         },
-        /**
-         * Creates a static Route using the supplied options
-         *
-         * The return value of staticRoute is a function that accepts the routes options
-         * The only argument to staticRoute itself is an optional parent route
-         *
-         * The returned function accepts 3 arguments
-         *
-         * 1. URL of the route
-         * 2. The event type of the route
-         * 3. The routes options, params schema, query schema and meta type
-         *
-         * The params and query schemas are ZodSchemas, they both need to be an object (ie Z.object())
-         *
-         * When creating a route that has a parent route, the following happens
-         *
-         * 1. The parent routes url is prepended to the routes URL
-         * 2. The parents params schema is merged with the routes schema
-         * 3. The parents meta type is merged with the routes meta type
-         */
-        staticRoute: function createStaticRoute(baseRoute) {
-            return (url, event, opts) => {
-                if (baseRoute && isNil(baseRoute.url)) {
-                    throw new Error("Somehow constructing a route with a base route missing a URL, did you pass a dynamic route?");
+        route(baseRoute) {
+            function getParentArray() {
+                const parentRoutes = [];
+                let currentParent = baseRoute;
+                while (currentParent) {
+                    parentRoutes.unshift(currentParent);
+                    currentParent = currentParent.parent;
+                }
+                return parentRoutes;
+            }
+            return ({ event, matcher, reverser, paramsSchema, querySchema, redirect, }) => {
+                let fullParamsSchema = paramsSchema;
+                let parentRoute = baseRoute;
+                while (fullParamsSchema && parentRoute) {
+                    if (parentRoute.paramsSchema) {
+                        fullParamsSchema = fullParamsSchema.merge(parentRoute.paramsSchema);
+                    }
+                    parentRoute = parentRoute.parent;
                 }
-                const urlWithTrailingSlash = url.endsWith("/") ? url : `${url}/`;
-                const fullUrl = baseRoute
-                    ? joinRoutes(baseRoute.url, urlWithTrailingSlash)
-                    : urlWithTrailingSlash;
-                const matcher = match(fullUrl, {});
-                const reverser = compile(fullUrl);
-                const paramsSchema = (baseRoute === null || baseRoute === void 0 ? void 0 : baseRoute.paramsSchema)
-                    ? (opts === null || opts === void 0 ? void 0 : opts.params)
-                        ? baseRoute.paramsSchema.merge(opts.params)
-                        : baseRoute.paramsSchema
-                    : (opts === null || opts === void 0 ? void 0 : opts.params)
-                        ? opts.params
-                        : undefined;
                 return {
-                    paramsSchema,
-                    querySchema: opts === null || opts === void 0 ? void 0 : opts.query,
+                    basePath,
                     event,
                     history,
-                    basePath,
-                    url: fullUrl,
+                    paramsSchema,
+                    querySchema,
                     parent: baseRoute,
-                    // @ts-ignore the usual
-                    getEvent({ params, query, meta } = {}) {
+                    redirect,
+                    matcher: matcher,
+                    reverser: reverser,
+                    // @ts-ignore :cry:
+                    getEvent(args) {
+                        const { params, query, meta } = args !== null && args !== void 0 ? args : {};
                         return { type: event, params, query, meta };
                     },
-                    // @ts-ignore not sure how to type this
-                    matches(url, search) {
-                        const fullUrl = url.endsWith("/") ? url : `${url}/`;
-                        const matches = matcher(fullUrl);
-                        if (matches === false) {
-                            return undefined;
+                    // @ts-ignore :cry:
+                    matches(suppliedUrl, search) {
+                        var _a, _b, _c;
+                        const fullUrl = suppliedUrl.endsWith("/")
+                            ? suppliedUrl
+                            : suppliedUrl + "/";
+                        let url = fullUrl;
+                        const parentRoutes = getParentArray();
+                        let params = {};
+                        while (parentRoutes.length) {
+                            const parentRoute = parentRoutes.shift();
+                            const parentMatch = parentRoute.matcher(url, undefined);
+                            if (parentMatch === false) {
+                                return false;
+                            }
+                            url = url.slice(parentMatch.matchLength);
+                            // All routes assume the url starts with a /
+                            // so if the parent route matches the / in the url, which consumes it
+                            // need to re-add it for the next route to match against
+                            if (!url.startsWith("/")) {
+                                url = "/" + url;
+                            }
+                            params = { ...params, ...((_a = parentMatch.params) !== null && _a !== void 0 ? _a : {}) };
                         }
-                        const params = matches.params;
-                        if (params && paramsSchema) {
-                            paramsSchema.parse(params);
+                        const matches = matcher(url, parse(search));
+                        // if there is any URL left after matching this route, the last to match
+                        // that means the match isn't actually a match
+                        if (matches === false || matches.matchLength !== url.length) {
+                            return false;
                         }
-                        const query = parse(search);
-                        if (opts === null || opts === void 0 ? void 0 : opts.query) {
-                            opts.query.parse(query);
+                        const fullParams = {
+                            ...params,
+                            ...((_b = matches.params) !== null && _b !== void 0 ? _b : {}),
+                        };
+                        if (fullParamsSchema) {
+                            fullParamsSchema.parse(fullParams);
+                        }
+                        if (querySchema) {
+                            querySchema.parse(matches.query);
                         }
                         return {
-                            type: event,
                             originalUrl: `${fullUrl}${search}`,
-                            params,
-                            query,
+                            type: event,
+                            params: fullParams,
+                            query: (_c = matches.query) !== null && _c !== void 0 ? _c : {},
                         };
                     },
-                    // @ts-ignore not sure how to type this correctly
-                    // The types from external to this function are correct however
-                    reverse({ params, query } = {}) {
-                        const url = (() => {
-                            if (params) {
-                                // @ts-ignore same problem
-                                return reverser(params);
-                            }
-                            else {
-                                return reverser();
-                            }
-                        })();
-                        if (!isNil(query)) {
-                            return `${url}?${stringify(query)}`;
-                        }
-                        else {
-                            return url;
-                        }
+                    // @ts-ignore :cry:
+                    reverse(args) {
+                        const { params, query } = args !== null && args !== void 0 ? args : {};
+                        const parentRoutes = getParentArray();
+                        const baseUrl = parentRoutes
+                            .map((route) => route.reverser({ params }))
+                            .reduce((fullUrl, urlPartial) => joinRoutes(fullUrl, urlPartial), "");
+                        return `${joinRoutes(baseUrl, reverser({ params, query }))}`;
                     },
-                    // @ts-ignore not sure how to type this correctly
-                    // The types from external to this function are correct however
-                    navigate({ params, query, meta } = {}) {
-                        // @ts-ignore same problem
+                    // @ts-ignore :cry:
+                    navigate(args) {
+                        const { params, query, meta } = args !== null && args !== void 0 ? args : {};
                         const url = this.reverse({ params, query });
                         navigate({
                             url: joinRoutes(this.basePath, url),

package/lib/routing/handleLocationChange/handleLocationChange.js

@@ -3,7 +3,7 @@ import { matchRoute } from "../matchRoute";
 /**
  * @internal
  */
-export function handleLocationChange(routes, basePath, path, search, setActiveRouteEvents, meta) {
+export function handleLocationChange(routes, basePath, path, search, meta) {
     console.debug("[xstate-tree] Matching routes", basePath, path, search, meta);
     const match = matchRoute(routes, basePath, path, search);
     console.debug("[xstate-tree] Match result", match);
@@ -14,9 +14,11 @@ export function handleLocationChange(routes, basePath, path, search, setActiveRo
         };
         // @ts-ignore the event won't match GlobalEvents
         broadcast(fourOhFour);
+        return;
     }
     else if (match.type === "match-error") {
         console.error("Error matching route for", location.pathname);
+        return;
     }
     else {
         const matchedEvent = match.event;
@@ -29,7 +31,7 @@ export function handleLocationChange(routes, basePath, path, search, setActiveRo
             routingEvents.push(route.parent.getEvent({ params, query: {}, meta: { ...(meta !== null && meta !== void 0 ? meta : {}) } }));
             route = route.parent;
         }
-        setActiveRouteEvents([...routingEvents, match.event]);
+        const clonedRoutingEvents = [...routingEvents];
         while (routingEvents.length > 0) {
             const event = routingEvents.pop();
             // copy the originalUrl to all parent events
@@ -39,5 +41,9 @@ export function handleLocationChange(routes, basePath, path, search, setActiveRo
         }
         // @ts-ignore the event won't match GlobalEvents
         broadcast(matchedEvent);
+        return {
+            events: [...clonedRoutingEvents, match.event],
+            matchedRoute: match.route,
+        };
     }
 }

package/lib/routing/joinRoutes.js

@@ -1,5 +1,15 @@
 export function joinRoutes(base, route) {
     const realBase = base.endsWith("/") ? base.slice(0, -1) : base;
     const realRoute = route.startsWith("/") ? route : `/${route}`;
-    return realBase + realRoute;
+    const joinedUrl = realBase + realRoute;
+    if (!joinedUrl.endsWith("/")) {
+        if (!joinedUrl.includes("?")) {
+            return `${joinedUrl}/`;
+        }
+        if (!joinedUrl.includes("/?")) {
+            return joinedUrl.replace("?", "/?");
+        }
+        return joinedUrl;
+    }
+    return joinedUrl;
 }

package/lib/xstate-tree.d.ts

@@ -32,12 +32,14 @@ export declare type AnyRoute = {
     navigate: any;
     getEvent: any;
     event: string;
-    url?: string;
     basePath: string;
     history: XstateTreeHistory;
     parent?: AnyRoute;
     paramsSchema?: Z.ZodObject<any>;
     querySchema?: Z.ZodObject<any>;
+    matcher: (url: string, query: ParsedQuery<string> | undefined) => any;
+    reverser: any;
+    redirect?: any;
 };
 
 /**
@@ -90,79 +92,52 @@ export declare function buildActions<TMachine extends AnyStateMachine, TActions,
  * @param basePath - the base path for this route factory
  */
 export declare function buildCreateRoute(history: XstateTreeHistory, basePath: string): {
-    /**
-     * Creates a dynamic Route using the supplied options
-     *
-     * The return value of dynamicRoute is a function that accepts the routes "dynamic" options
-     * The argument to dynamicRoute itself is the params/query/meta schemas defining the route
-     *
-     * The returned function accepts a singular option object with the following fields
-     *
-     * `event`, the string constant for the routes event
-     * `matches`, a function that is passed a url/query string and determines if the route matches
-     * if the route is matched it returns the extracted params/query objects
-     * `reverse`, a function that is passed params/query objects and turns them into a URL
-     *
-     * The params and query schemas are ZodSchemas, they both need to be an object (ie Z.object())
-     */
-    dynamicRoute: <TOpts extends Options<Z.ZodObject<any, "strip", Z.ZodTypeAny, {
+    simpleRoute<TBaseRoute extends AnyRoute>(baseRoute?: TBaseRoute | undefined): <TEvent extends string, TParamsSchema extends Z.ZodObject<any, "strip", Z.ZodTypeAny, {
         [x: string]: any;
     }, {
         [x: string]: any;
-    }>, Z.ZodObject<any, "strip", Z.ZodTypeAny, {
+    }> | undefined, TQuerySchema extends Z.ZodObject<any, "strip", Z.ZodTypeAny, {
         [x: string]: any;
     }, {
         [x: string]: any;
-    }>, any>>(opts?: TOpts | undefined) => <TEvent extends string, TParamsSchema = Params<TOpts>, TQuerySchema = Query<TOpts>, TMeta = Meta<TOpts>, TParams = TParamsSchema extends Z.ZodObject<any, "strip", Z.ZodTypeAny, {
-        [x: string]: any;
-    }, {
-        [x: string]: any;
-    }> ? Z.TypeOf<TParamsSchema> : undefined, TQuery = TQuerySchema extends Z.ZodObject<any, "strip", Z.ZodTypeAny, {
-        [x: string]: any;
-    }, {
-        [x: string]: any;
-    }> ? Z.TypeOf<TQuerySchema> : undefined, TFullMeta = TMeta extends undefined ? SharedMeta : TMeta & SharedMeta>({ event, matches, reverse, }: {
+    }> | undefined, TMeta extends Record<string, unknown>>({ url, paramsSchema, querySchema, ...args }: {
         event: TEvent;
-        matches: (url: string, query: ParsedQuery<string>) => false | RouteArguments<TParams, TQuery, TFullMeta>;
-        reverse: RouteArgumentFunctions<string, TParams, TQuery, TFullMeta, RouteArguments<TParams, TQuery, TFullMeta>>;
-    }) => Route<TParams, TQuery, TEvent, TFullMeta>;
-    /**
-     * Creates a static Route using the supplied options
-     *
-     * The return value of staticRoute is a function that accepts the routes options
-     * The only argument to staticRoute itself is an optional parent route
-     *
-     * The returned function accepts 3 arguments
-     *
-     * 1. URL of the route
-     * 2. The event type of the route
-     * 3. The routes options, params schema, query schema and meta type
-     *
-     * The params and query schemas are ZodSchemas, they both need to be an object (ie Z.object())
-     *
-     * When creating a route that has a parent route, the following happens
-     *
-     * 1. The parent routes url is prepended to the routes URL
-     * 2. The parents params schema is merged with the routes schema
-     * 3. The parents meta type is merged with the routes meta type
-     */
-    staticRoute: <TBaseRoute extends AnyRoute | undefined = undefined, TBaseParams = RouteParams<TBaseRoute>, TBaseMeta = RouteMeta<TBaseRoute>>(baseRoute?: TBaseRoute | undefined) => <TOpts_1 extends Options<Z.ZodObject<any, "strip", Z.ZodTypeAny, {
+        url: string;
+        paramsSchema?: TParamsSchema | undefined;
+        querySchema?: TQuerySchema | undefined;
+        meta?: TMeta | undefined;
+        redirect?: RouteRedirect<MergeRouteTypes<RouteParams<TBaseRoute>, ResolveZodType<TParamsSchema>>, ResolveZodType<TQuerySchema>, MergeRouteTypes<RouteMeta<TBaseRoute>, TMeta> & SharedMeta> | undefined;
+    }) => Route<MergeRouteTypes<RouteParams<TBaseRoute>, ResolveZodType<TParamsSchema>>, ResolveZodType<TQuerySchema>, TEvent, MergeRouteTypes<RouteMeta<TBaseRoute>, TMeta> & SharedMeta>;
+    route<TBaseRoute_1 extends AnyRoute>(baseRoute?: TBaseRoute_1 | undefined): <TEvent_1 extends string, TParamsSchema_1 extends Z.ZodObject<any, "strip", Z.ZodTypeAny, {
         [x: string]: any;
     }, {
         [x: string]: any;
-    }>, Z.ZodObject<any, "strip", Z.ZodTypeAny, {
+    }> | undefined, TQuerySchema_1 extends Z.ZodObject<any, "strip", Z.ZodTypeAny, {
         [x: string]: any;
     }, {
         [x: string]: any;
-    }>, any>, TEvent_1 extends string, TParamsSchema_1 = Params<TOpts_1>, TQuerySchema_1 = Query<TOpts_1>, TMeta_1 = Meta<TOpts_1>, TParams_1 = TParamsSchema_1 extends Z.ZodObject<any, "strip", Z.ZodTypeAny, {
-        [x: string]: any;
-    }, {
-        [x: string]: any;
-    }> ? Z.TypeOf<TParamsSchema_1> : undefined, TQuery_1 = TQuerySchema_1 extends Z.ZodObject<any, "strip", Z.ZodTypeAny, {
-        [x: string]: any;
-    }, {
-        [x: string]: any;
-    }> ? Z.TypeOf<TQuerySchema_1> : undefined, TFullParams = TParams_1 extends undefined ? TBaseParams extends undefined ? undefined : TBaseParams : TParams_1 & (TBaseParams extends undefined ? {} : TBaseParams), TFullMeta_1 = TMeta_1 extends undefined ? TBaseMeta extends undefined ? SharedMeta : TBaseMeta & SharedMeta : TMeta_1 & (TBaseMeta extends undefined ? {} : TBaseMeta) & SharedMeta>(url: string, event: TEvent_1, opts?: TOpts_1 | undefined) => Route<TFullParams, TQuery_1, TEvent_1, TFullMeta_1>;
+    }> | undefined, TMeta_1 extends Record<string, unknown>>({ event, matcher, reverser, paramsSchema, querySchema, redirect, }: {
+        event: TEvent_1;
+        paramsSchema?: TParamsSchema_1 | undefined;
+        querySchema?: TQuerySchema_1 | undefined;
+        meta?: TMeta_1 | undefined;
+        redirect?: RouteRedirect<MergeRouteTypes<RouteParams<TBaseRoute_1>, ResolveZodType<TParamsSchema_1>>, ResolveZodType<TQuerySchema_1>, MergeRouteTypes<RouteMeta<TBaseRoute_1>, TMeta_1> & SharedMeta> | undefined;
+        /**
+         * Determines if the route matches the given url and query
+         *
+         * If there is no match, return false
+         * If there is a match, return the parsed params and query as well as the length of the matched path in the URL
+         */
+        matcher: (url: string, query: ParsedQuery<string> | undefined) => false | (RouteArguments<MergeRouteTypes<RouteParams<TBaseRoute_1>, ResolveZodType<TParamsSchema_1>>, ResolveZodType<TQuerySchema_1>, MergeRouteTypes<RouteMeta<TBaseRoute_1>, TMeta_1>> & {
+            matchLength: number;
+        });
+        /**
+         * Reverses the route to a URL
+         *
+         * Supplied with params/query objects and constructs the correct URL based on them
+         */
+        reverser: RouteArgumentFunctions<string, MergeRouteTypes<RouteParams<TBaseRoute_1>, ResolveZodType<TParamsSchema_1>>, ResolveZodType<TQuerySchema_1>, MergeRouteTypes<RouteMeta<TBaseRoute_1>, TMeta_1>, RouteArguments<MergeRouteTypes<RouteParams<TBaseRoute_1>, ResolveZodType<TParamsSchema_1>>, ResolveZodType<TQuerySchema_1>, MergeRouteTypes<RouteMeta<TBaseRoute_1>, TMeta_1>>>;
+    }) => Route<MergeRouteTypes<RouteParams<TBaseRoute_1>, ResolveZodType<TParamsSchema_1>>, ResolveZodType<TQuerySchema_1>, TEvent_1, MergeRouteTypes<RouteMeta<TBaseRoute_1>, TMeta_1> & SharedMeta>;
 };
 
 /**
@@ -311,9 +286,9 @@ declare type InferViewProps<T> = T extends ViewProps<infer TSelectors, infer TAc
     inState: (state: Parameters<TMatches>[0]) => TMatches;
 } : never;
 
-declare type IsEmptyObject<Obj, ExcludeOptional extends boolean = false> = [
-keyof (ExcludeOptional extends true ? OmitOptional<Obj> : Obj)
-] extends [never] ? true : false;
+declare type IsEmptyObject<Obj, ExcludeOptional extends boolean = false> = undefined extends Obj ? true : [keyof (ExcludeOptional extends true ? OmitOptional<Obj> : Obj)] extends [
+never
+] ? true : false;
 
 /**
  * @public
@@ -325,7 +300,7 @@ keyof (ExcludeOptional extends true ? OmitOptional<Obj> : Obj)
  * @param options - configure loading component and context to invoke machine with
  * @returns an xstate-tree machine that wraps the promise, invoking the resulting machine when it resolves
  */
-export declare function lazy<TMachine extends AnyStateMachine>(factory: () => Promise<TMachine>, { Loader, withContext, }?: Options_2<TMachine["context"]>): StateMachine<Context, any, Events, States, any, any, any>;
+export declare function lazy<TMachine extends AnyStateMachine>(factory: () => Promise<TMachine>, { Loader, withContext, }?: Options<TMachine["context"]>): StateMachine<Context, any, Events, States, any, any, any>;
 
 /**
  * @public
@@ -372,6 +347,8 @@ export declare type MatchesFrom<T extends AnyStateMachine> = StateFrom<T>["match
  */
 export declare function matchRoute<TRoutes extends Route<any, any, any, any>[]>(routes: TRoutes, basePath: string, path: string, search: string): Return<TRoutes>;
 
+declare type MergeRouteTypes<TBase, TSupplied> = undefined extends TBase ? TSupplied : undefined extends TSupplied ? TBase : TBase & TSupplied;
+
 /**
  * @public
  *
@@ -408,16 +385,7 @@ declare type OmitOptional<T> = {
  */
 export declare function onBroadcast(handler: (event: GlobalEvents) => void): () => void;
 
-/**
- * @public
- */
-export declare type Options<TParamsSchema extends Z.ZodObject<any>, TQuerySchema extends Z.ZodObject<any>, TMetaSchema> = {
-    params?: TParamsSchema;
-    query?: TQuerySchema;
-    meta?: TMetaSchema;
-};
-
-declare type Options_2<TContext> = {
+declare type Options<TContext> = {
     /**
      * Displayed while the promise is resolving, defaults to returning null
      */
@@ -465,6 +433,8 @@ export declare type Query<T> = T extends {
     query: infer TQuery;
 } ? TQuery : undefined;
 
+declare type ResolveZodType<T extends Z.ZodType<any> | undefined> = undefined extends T ? undefined : Z.TypeOf<Exclude<T, undefined>>;
+
 declare type Return<TRoutes extends Route<any, any, any, any>[]> = {
     type: "matched";
     route: TRoutes[number];
@@ -498,7 +468,7 @@ export declare type Route<TParams, TQuery, TEvent, TMeta> = {
     matches: (url: string, search: string) => ({
         type: TEvent;
         originalUrl: string;
-    } & RouteArguments<TParams, TQuery, TMeta>) | undefined;
+    } & RouteArguments<TParams, TQuery, TMeta>) | false;
     /**
      * Takes in query/params objects as required by the route and returns a URL for that route
      *
@@ -520,16 +490,20 @@ export declare type Route<TParams, TQuery, TEvent, TMeta> = {
     getEvent: RouteArgumentFunctions<{
         type: TEvent;
     } & RouteArguments<TParams, TQuery, TMeta>, TParams, TQuery, TMeta>;
+    matcher: (url: string, query: ParsedQuery<string> | undefined) => (RouteArguments<TParams, TQuery, TMeta> & {
+        matchLength: number;
+    }) | false;
+    reverser: RouteArgumentFunctions<string, TParams, TQuery, TMeta>;
     /**
      * Event type for this route
      */
     event: TEvent;
-    url?: string;
     history: XstateTreeHistory;
     basePath: string;
     parent?: AnyRoute;
     paramsSchema?: Z.ZodObject<any>;
     querySchema?: Z.ZodObject<any>;
+    redirect?: RouteRedirect<TParams, TQuery, TMeta>;
 };
 
 /**
@@ -575,6 +549,13 @@ export declare type RouteMeta<T> = T extends Route<any, any, any, infer TMeta> ?
  */
 export declare type RouteParams<T> = T extends Route<infer TParams, any, any, any> ? TParams : undefined;
 
+declare type RouteRedirect<TParams, TQuery, TMeta> = (args: MakeEmptyObjectPropertiesOptional<{
+    params: TParams;
+    query: TQuery;
+    meta?: TMeta;
+    abortSignal: AbortSignal;
+}>) => Promise<undefined | RouteArguments<Partial<TParams>, Partial<TQuery>, TMeta>>;
+
 /**
  * @public
  */

package/lib/xstateTree.js

@@ -6,7 +6,7 @@ import { handleLocationChange, RoutingContext, } from "./routing";
 import { useActiveRouteEvents } from "./routing/providers";
 import { useConstant } from "./useConstant";
 import { useService } from "./useService";
-import { isLikelyPageLoad } from "./utils";
+import { assertIsDefined, isLikelyPageLoad } from "./utils";
 export const emitter = new TinyEmitter();
 /**
  * @public
@@ -173,6 +173,7 @@ export function buildRootComponent(machine, routing) {
     }
     const RootComponent = function XstateTreeRootComponent() {
         const [_, __, interpreter] = useMachine(machine, { devTools: true });
+        const [activeRoute, setActiveRoute] = useState(undefined);
         const activeRouteEventsRef = useRef([]);
         const [forceRenderValue, forceRender] = useState(false);
         const setActiveRouteEvents = (events) => {
@@ -187,11 +188,72 @@ export function buildRootComponent(machine, routing) {
                 emitter.off("event", handler);
             };
         }, [interpreter]);
+        useEffect(() => {
+            if (activeRoute === undefined) {
+                return;
+            }
+            const controller = new AbortController();
+            const routes = [activeRoute];
+            let route = activeRoute;
+            while (route.parent) {
+                routes.unshift(route.parent);
+                route = route.parent;
+            }
+            const routeEventPairs = [];
+            const activeRoutesEvent = activeRouteEventsRef.current.find((e) => e.type === activeRoute.event);
+            assertIsDefined(activeRoutesEvent);
+            for (let i = 0; i < routes.length; i++) {
+                const route = routes[i];
+                const routeEvent = activeRouteEventsRef.current[i];
+                routeEventPairs.push([route, routeEvent]);
+            }
+            const routePairsWithRedirects = routeEventPairs.filter(([route]) => {
+                return route.redirect !== undefined;
+            });
+            const redirectPromises = routePairsWithRedirects.map(([route, event]) => {
+                assertIsDefined(route.redirect);
+                return route.redirect({
+                    signal: controller.signal,
+                    query: event.query,
+                    params: event.params,
+                    meta: event.meta,
+                });
+            });
+            void Promise.all(redirectPromises).then((redirects) => {
+                var _a, _b, _c;
+                const didAnyRedirect = redirects.some((x) => x !== undefined);
+                if (!didAnyRedirect || controller.signal.aborted) {
+                    return;
+                }
+                const routeArguments = redirects.reduce((args, redirect) => {
+                    if (redirect) {
+                        args.query = { ...args.query, ...redirect.query };
+                        args.params = { ...args.params, ...redirect.params };
+                        args.meta = { ...args.meta, ...redirect.meta };
+                    }
+                    return args;
+                }, {
+                    // since the redirect results are partials, need to merge them with the original event
+                    // params/query to ensure that all params/query are present
+                    query: { ...((_a = activeRoutesEvent.query) !== null && _a !== void 0 ? _a : {}) },
+                    params: { ...((_b = activeRoutesEvent.params) !== null && _b !== void 0 ? _b : {}) },
+                    meta: { ...((_c = activeRoutesEvent.meta) !== null && _c !== void 0 ? _c : {}) },
+                });
+                activeRoute.navigate(routeArguments);
+            });
+            return () => {
+                controller.abort();
+            };
+        }, [activeRoute]);
         useEffect(() => {
             if (routing) {
                 const { getPathName = () => window.location.pathname, getQueryString = () => window.location.search, } = routing;
                 const queryString = getQueryString();
-                handleLocationChange(routing.routes, routing.basePath, getPathName(), getQueryString(), setActiveRouteEvents, { onloadEvent: isLikelyPageLoad() });
+                const result = handleLocationChange(routing.routes, routing.basePath, getPathName(), getQueryString(), { onloadEvent: isLikelyPageLoad() });
+                if (result) {
+                    setActiveRouteEvents(result.events);
+                    setActiveRoute({ ...result.matchedRoute });
+                }
                 // Hack to ensure the initial location doesn't have undefined state
                 // It's not supposed to, but it does for some reason
                 // And the history library ignores popstate events with undefined state
@@ -202,7 +264,11 @@ export function buildRootComponent(machine, routing) {
             if (routing) {
                 const unsub = routing.history.listen((location) => {
                     var _a;
-                    handleLocationChange(routing.routes, routing.basePath, location.pathname, location.search, setActiveRouteEvents, (_a = location.state) === null || _a === void 0 ? void 0 : _a.meta);
+                    const result = handleLocationChange(routing.routes, routing.basePath, location.pathname, location.search, (_a = location.state) === null || _a === void 0 ? void 0 : _a.meta);
+                    if (result) {
+                        setActiveRouteEvents(result.events);
+                        setActiveRoute({ ...result.matchedRoute });
+                    }
                 });
                 return () => {
                     unsub();

package/package.json

@@ -2,7 +2,7 @@
   "name": "@koordinates/xstate-tree",
   "main": "lib/index.js",
   "types": "lib/xstate-tree.d.ts",
-  "version": "2.0.11",
+  "version": "3.0.0-beta.2",
   "license": "MIT",
   "description": "Build UIs with Actors using xstate and React",
   "keywords": [
@@ -81,7 +81,7 @@
     "test-examples": "tsc --noEmit",
     "todomvc": "vite dev",
     "build": "rimraf lib && rimraf out && tsc -p tsconfig.build.json",
-    "build:watch": "tsc -p tsconfig.build.json -w",
+    "build:watch": "tsc -p tsconfig.json -w",
     "api-extractor": "api-extractor run",
     "release": "semantic-release",
     "commitlint": "commitlint --edit"