space-router 1.0.0 → 1.2.0

package/README.md

@@ -6,7 +6,7 @@
 <h4 align="center">Framework agnostic router for single page apps</h4>
 <br />
 
-Space Router packs all the features you need to keep your app in sync with the url. It's distinct from many other routers in that there is only **a single callback**. This callback can be used to re-render your applocation, update a store and perform other actions on each url change. Space Router is **stateless**, it doesn't store the current route leaving state completely up to you to handle.
+Space Router packs all the features you need to keep your app in sync with the url. It's distinct from many other routers in that there is only **a single callback**. This callback can be used to re-render your application, update a store and perform other actions on each url change. Space Router is **stateless**, it doesn't store the current route leaving state completely up to you to handle.
 
 In summary, Space Router:
 

package/dist/history.d.ts

@@ -5,8 +5,13 @@ export interface History {
     push(url: string): void;
     replace(url: string): void;
 }
+export interface ScheduleInfo {
+    traversal: boolean;
+}
+export type Schedule = (fire: () => void, info: ScheduleInfo) => void;
 export interface CreateHistoryOptions {
     mode?: Mode;
     sync?: boolean;
+    schedule?: Schedule;
 }
 export declare function createHistory(options?: CreateHistoryOptions): History;

package/dist/history.js

@@ -1,8 +1,9 @@
 export function createHistory(options = {}) {
-    const sync = !!options.sync;
+    const schedule = options.schedule || (options.sync ? (fire) => fire() : (fire) => queueMicrotask(fire));
     let mode = options.mode || 'history';
     let listener = null;
-    let pending = false;
+    let seq = 0;
+    let selfNavs = 0;
     const memory = [];
     if (typeof window === 'undefined') {
         mode = 'memory';
@@ -11,16 +12,24 @@ export function createHistory(options = {}) {
         if (listener)
             listener(getUrl());
     }
-    function schedule() {
-        if (sync)
-            return emit();
-        if (pending)
-            return;
-        pending = true;
-        queueMicrotask(() => {
-            pending = false;
-            emit();
-        });
+    // each scheduled fire captures its seq: superseded fires no-op, and the
+    // surviving one reads the url fresh in emit() — so racing schedules of any
+    // mix (e.g. a deferred traversal emit overtaken by a push's microtask emit)
+    // coalesce into a single emit of the final url
+    function scheduleEmit(traversal) {
+        const s = ++seq;
+        schedule(() => {
+            if (s === seq)
+                emit();
+        }, { traversal });
+    }
+    function onTraversal() {
+        // a hashchange caused by our own push/replace is a navigation,
+        // not a back/forward traversal
+        const traversal = selfNavs === 0;
+        if (selfNavs > 0)
+            selfNavs--;
+        scheduleEmit(traversal);
     }
     function listen(onChange) {
         if (listener)
@@ -28,8 +37,8 @@ export function createHistory(options = {}) {
         listener = onChange;
         let off;
         if (mode !== 'memory') {
-            off = on(window, mode === 'history' ? 'popstate' : 'hashchange', schedule);
-            schedule();
+            off = on(window, mode === 'history' ? 'popstate' : 'hashchange', onTraversal);
+            scheduleEmit(false);
         }
         return () => {
             listener = null;
@@ -41,30 +50,32 @@ export function createHistory(options = {}) {
         url = url.replace(/^\/?#?\/?/, '/').replace(/\/$/, '') || '/';
         if (mode === 'history') {
             history[replace ? 'replaceState' : 'pushState']({}, '', url);
-            schedule();
+            scheduleEmit(false);
         }
         else if (mode === 'hash') {
             // hashchange only fires when the URL actually changes; if it doesn't,
             // we schedule the emit manually so navigation stays consistent with
             // history mode (where pushState is silent and we always schedule).
             const same = url === getUrl();
+            if (!same)
+                selfNavs++;
             location[replace ? 'replace' : 'assign']('#' + url);
             if (same)
-                schedule();
+                scheduleEmit(false);
         }
         else if (mode === 'memory') {
-            if (replace) {
+            if (replace && memory.length) {
                 memory[memory.length - 1] = url;
             }
             else {
                 memory.push(url);
             }
-            schedule();
+            scheduleEmit(false);
         }
     }
     function getUrl() {
         if (mode === 'memory') {
-            return memory[memory.length - 1];
+            return memory[memory.length - 1] ?? '';
         }
         const hash = getHash();
         if (mode === 'hash') {

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 export { qs } from './qs.ts';
 export { createHistory } from './history.ts';
-export { createRouter, merge } from './router.ts';
+export { createMatcher, createRouter, merge } from './router.ts';
 export type { Qs } from './qs.ts';
-export type { Mode, History, CreateHistoryOptions } from './history.ts';
-export type { RouterOptions, Route, NavigateTarget, To, Redirect, RouteDefinition, Router } from './router.ts';
+export type { Mode, History, CreateHistoryOptions, Schedule, ScheduleInfo } from './history.ts';
+export type { MatcherOptions, RouteData, RouterOptions, Route, NavigateTarget, To, Redirect, RouteDefinition, Matcher, Router, } from './router.ts';

package/dist/index.js

@@ -1,3 +1,3 @@
 export { qs } from "./qs.js";
 export { createHistory } from "./history.js";
-export { createRouter, merge } from "./router.js";
+export { createMatcher, createRouter, merge } from "./router.js";

package/dist/match.d.ts

@@ -8,9 +8,4 @@ export interface MatchedRoute {
     search: string;
     hash: string;
 }
-interface RouteEntry {
-    pattern: string;
-}
-export declare function match(routes: RouteEntry[], url: string | undefined, qs: Qs): MatchedRoute | undefined;
 export declare function matchOne(pattern: string, url: string, qs?: Qs): MatchedRoute | undefined;
-export {};

package/dist/match.js

@@ -1,12 +1,3 @@
-export function match(routes, url, qs) {
-    if (!url)
-        return;
-    for (let i = 0; i < routes.length; i++) {
-        const m = matchOne(routes[i].pattern, url, qs);
-        if (m)
-            return m;
-    }
-}
 export function matchOne(pattern, url, qs) {
     if (!pattern)
         return;

package/dist/router.d.ts

@@ -1,13 +1,17 @@
 import { type MatchedRoute } from './match.ts';
-import { type Mode } from './history.ts';
+import { type Mode, type Schedule } from './history.ts';
 import { type Qs } from './qs.ts';
 export interface RouterOptions {
     mode?: Mode;
     qs?: Qs;
     sync?: boolean;
+    schedule?: Schedule;
+}
+export interface MatcherOptions {
+    qs?: Qs;
 }
 export interface Route<Data = Record<string, unknown>> extends MatchedRoute {
-    data: Data[];
+    data: RouteData<Data>[];
 }
 export interface NavigateTarget {
     url?: string;
@@ -20,6 +24,10 @@ export interface NavigateTarget {
 }
 export type To = string | NavigateTarget;
 export type Redirect<Data = Record<string, unknown>> = To | ((route: Route<Data>) => To);
+export type RouteData<Data = Record<string, unknown>> = Data & {
+    path: string;
+    redirect?: Redirect<Data>;
+};
 export type RouteDefinition<Data = Record<string, unknown>> = Data & {
     path?: string;
     redirect?: Redirect<Data>;
@@ -32,11 +40,15 @@ export interface Router<Data = Record<string, unknown>> {
     match(url: string): Route<Data> | undefined;
     getUrl(): string;
 }
-interface FlatRoute {
+export interface Matcher<Data = Record<string, unknown>> {
+    match(url: string): Route<Data> | undefined;
+}
+interface FlatRoute<Data = Record<string, unknown>> {
     pattern: string;
-    data: Array<Record<string, unknown>>;
+    data: RouteData<Data>[];
 }
 export declare function createRouter<Data = Record<string, unknown>>(options?: RouterOptions): Router<Data>;
-export declare function flatten(routeMap: RouteDefinition[]): FlatRoute[];
+export declare function createMatcher<Data = Record<string, unknown>>(routeMap: RouteDefinition<Data>[], options?: MatcherOptions): Matcher<Data>;
+export declare function flatten<Data = Record<string, unknown>>(routeMap: RouteDefinition<Data>[]): FlatRoute<Data>[];
 export declare function merge(curr: Partial<Route> | NavigateTarget | undefined, to: NavigateTarget): NavigateTarget;
 export {};

package/dist/router.js

@@ -1,4 +1,4 @@
-import { match as findMatch } from "./match.js";
+import { matchOne } from "./match.js";
 import { createHistory } from "./history.js";
 import { qs as defaultQs } from "./qs.js";
 const PARAM_RE = /:([A-Za-z0-9_]+)([+*?])?/g;
@@ -6,15 +6,14 @@ const MAX_REDIRECTS = 10;
 export function createRouter(options = {}) {
     const mode = options.mode || 'history';
     const qs = options.qs || defaultQs;
-    const sync = options.sync || false;
-    const history = createHistory({ mode, sync });
-    let routes = [];
+    const history = createHistory({ mode, sync: options.sync, schedule: options.schedule });
+    let matcher = createMatcher([], { qs });
     const router = {
         listen(routeMap, cb) {
-            routes = flatten(routeMap);
+            matcher = createMatcher(routeMap, { qs });
             let redirects = 0;
             return history.listen((url) => {
-                const route = router.match(url);
+                const route = matcher.match(url);
                 if (!route) {
                     redirects = 0;
                     return;
@@ -84,11 +83,7 @@ export function createRouter(options = {}) {
             return url;
         },
         match(url) {
-            const route = findMatch(routes, url, qs);
-            if (route) {
-                return { ...route, data: data(routes, route) };
-            }
-            return undefined;
+            return matcher.match(url);
         },
         getUrl() {
             return history.getUrl();
@@ -96,15 +91,37 @@ export function createRouter(options = {}) {
     };
     return router;
 }
+export function createMatcher(routeMap, options = {}) {
+    const routes = flatten(routeMap);
+    const qs = options.qs || defaultQs;
+    return {
+        match(url) {
+            if (!url)
+                return undefined;
+            for (const route of routes) {
+                const m = matchOne(route.pattern, url, qs);
+                if (m) {
+                    return { ...m, data: route.data };
+                }
+            }
+            return undefined;
+        },
+    };
+}
 export function flatten(routeMap) {
     const routes = [];
     const parentData = [];
     function addLevel(level) {
         level.forEach((route) => {
             const { path = '', routes: children, ...routeData } = route;
-            routes.push({ pattern: path, data: parentData.concat([routeData]) });
+            const segment = { path, ...routeData };
+            // pathless routes only contribute data to their children — they have
+            // no pattern of their own to match
+            if (path) {
+                routes.push({ pattern: path, data: parentData.concat([segment]) });
+            }
             if (children) {
-                parentData.push(routeData);
+                parentData.push(segment);
                 addLevel(children);
                 parentData.pop();
             }
@@ -113,14 +130,6 @@ export function flatten(routeMap) {
     addLevel(routeMap);
     return routes;
 }
-function data(routes, matchingRoute) {
-    for (let i = 0; i < routes.length; i++) {
-        if (routes[i].pattern === matchingRoute.pattern) {
-            return routes[i].data;
-        }
-    }
-    return [];
-}
 export function merge(curr, to) {
     const c = (curr || {});
     const pathname = to.pathname || c.pattern || c.pathname;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "space-router",
   "description": "All the routing essentials.",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -47,16 +47,16 @@
     "release:docs": "hugo -s docs && gh-pages -d docs/public"
   },
   "devDependencies": {
-    "ava": "^7.0.0",
+    "ava": "^8.0.1",
     "c8": "^11.0.0",
     "gh-pages": "^6.3.0",
-    "oxfmt": "^0.46.0",
-    "oxlint": "^1.61.0",
+    "oxfmt": "^0.57.0",
+    "oxlint": "^1.72.0",
     "typescript": "^6.0.3"
   },
   "ava": {
-    "extensions": {
-      "ts": "module"
-    }
+    "extensions": [
+      "ts"
+    ]
   }
 }

package/src/history.ts

@@ -7,16 +7,24 @@ export interface History {
   replace(url: string): void
 }
 
+export interface ScheduleInfo {
+  traversal: boolean
+}
+
+export type Schedule = (fire: () => void, info: ScheduleInfo) => void
+
 export interface CreateHistoryOptions {
   mode?: Mode
   sync?: boolean
+  schedule?: Schedule
 }
 
 export function createHistory(options: CreateHistoryOptions = {}): History {
-  const sync = !!options.sync
+  const schedule: Schedule = options.schedule || (options.sync ? (fire) => fire() : (fire) => queueMicrotask(fire))
   let mode: Mode = options.mode || 'history'
   let listener: ((url: string) => void) | null = null
-  let pending = false
+  let seq = 0
+  let selfNavs = 0
 
   const memory: string[] = []
 
@@ -28,14 +36,26 @@ export function createHistory(options: CreateHistoryOptions = {}): History {
     if (listener) listener(getUrl())
   }
 
-  function schedule() {
-    if (sync) return emit()
-    if (pending) return
-    pending = true
-    queueMicrotask(() => {
-      pending = false
-      emit()
-    })
+  // each scheduled fire captures its seq: superseded fires no-op, and the
+  // surviving one reads the url fresh in emit() — so racing schedules of any
+  // mix (e.g. a deferred traversal emit overtaken by a push's microtask emit)
+  // coalesce into a single emit of the final url
+  function scheduleEmit(traversal: boolean) {
+    const s = ++seq
+    schedule(
+      () => {
+        if (s === seq) emit()
+      },
+      { traversal },
+    )
+  }
+
+  function onTraversal() {
+    // a hashchange caused by our own push/replace is a navigation,
+    // not a back/forward traversal
+    const traversal = selfNavs === 0
+    if (selfNavs > 0) selfNavs--
+    scheduleEmit(traversal)
   }
 
   function listen(onChange: (url: string) => void) {
@@ -43,8 +63,8 @@ export function createHistory(options: CreateHistoryOptions = {}): History {
     listener = onChange
     let off: (() => void) | undefined
     if (mode !== 'memory') {
-      off = on(window, mode === 'history' ? 'popstate' : 'hashchange', schedule)
-      schedule()
+      off = on(window, mode === 'history' ? 'popstate' : 'hashchange', onTraversal)
+      scheduleEmit(false)
     }
     return () => {
       listener = null
@@ -56,27 +76,28 @@ export function createHistory(options: CreateHistoryOptions = {}): History {
     url = url.replace(/^\/?#?\/?/, '/').replace(/\/$/, '') || '/'
     if (mode === 'history') {
       history[replace ? 'replaceState' : 'pushState']({}, '', url)
-      schedule()
+      scheduleEmit(false)
     } else if (mode === 'hash') {
       // hashchange only fires when the URL actually changes; if it doesn't,
       // we schedule the emit manually so navigation stays consistent with
       // history mode (where pushState is silent and we always schedule).
       const same = url === getUrl()
+      if (!same) selfNavs++
       location[replace ? 'replace' : 'assign']('#' + url)
-      if (same) schedule()
+      if (same) scheduleEmit(false)
     } else if (mode === 'memory') {
-      if (replace) {
+      if (replace && memory.length) {
         memory[memory.length - 1] = url
       } else {
         memory.push(url)
       }
-      schedule()
+      scheduleEmit(false)
     }
   }
 
   function getUrl(): string {
     if (mode === 'memory') {
-      return memory[memory.length - 1]
+      return memory[memory.length - 1] ?? ''
     }
 
     const hash = getHash()

package/src/index.ts

@@ -1,7 +1,18 @@
 export { qs } from './qs.ts'
 export { createHistory } from './history.ts'
-export { createRouter, merge } from './router.ts'
+export { createMatcher, createRouter, merge } from './router.ts'
 
 export type { Qs } from './qs.ts'
-export type { Mode, History, CreateHistoryOptions } from './history.ts'
-export type { RouterOptions, Route, NavigateTarget, To, Redirect, RouteDefinition, Router } from './router.ts'
+export type { Mode, History, CreateHistoryOptions, Schedule, ScheduleInfo } from './history.ts'
+export type {
+  MatcherOptions,
+  RouteData,
+  RouterOptions,
+  Route,
+  NavigateTarget,
+  To,
+  Redirect,
+  RouteDefinition,
+  Matcher,
+  Router,
+} from './router.ts'

package/src/match.ts

@@ -10,18 +10,6 @@ export interface MatchedRoute {
   hash: string
 }
 
-interface RouteEntry {
-  pattern: string
-}
-
-export function match(routes: RouteEntry[], url: string | undefined, qs: Qs): MatchedRoute | undefined {
-  if (!url) return
-  for (let i = 0; i < routes.length; i++) {
-    const m = matchOne(routes[i].pattern, url, qs)
-    if (m) return m
-  }
-}
-
 export function matchOne(pattern: string, url: string, qs?: Qs): MatchedRoute | undefined {
   if (!pattern) return
 

package/src/router.ts

@@ -1,15 +1,20 @@
-import { match as findMatch, type MatchedRoute } from './match.ts'
-import { createHistory, type Mode } from './history.ts'
+import { matchOne, type MatchedRoute } from './match.ts'
+import { createHistory, type Mode, type Schedule } from './history.ts'
 import { qs as defaultQs, type Qs } from './qs.ts'
 
 export interface RouterOptions {
   mode?: Mode
   qs?: Qs
   sync?: boolean
+  schedule?: Schedule
+}
+
+export interface MatcherOptions {
+  qs?: Qs
 }
 
 export interface Route<Data = Record<string, unknown>> extends MatchedRoute {
-  data: Data[]
+  data: RouteData<Data>[]
 }
 
 export interface NavigateTarget {
@@ -26,6 +31,11 @@ export type To = string | NavigateTarget
 
 export type Redirect<Data = Record<string, unknown>> = To | ((route: Route<Data>) => To)
 
+export type RouteData<Data = Record<string, unknown>> = Data & {
+  path: string
+  redirect?: Redirect<Data>
+}
+
 export type RouteDefinition<Data = Record<string, unknown>> = Data & {
   path?: string
   redirect?: Redirect<Data>
@@ -40,9 +50,13 @@ export interface Router<Data = Record<string, unknown>> {
   getUrl(): string
 }
 
-interface FlatRoute {
+export interface Matcher<Data = Record<string, unknown>> {
+  match(url: string): Route<Data> | undefined
+}
+
+interface FlatRoute<Data = Record<string, unknown>> {
   pattern: string
-  data: Array<Record<string, unknown>>
+  data: RouteData<Data>[]
 }
 
 const PARAM_RE = /:([A-Za-z0-9_]+)([+*?])?/g
@@ -51,22 +65,21 @@ const MAX_REDIRECTS = 10
 export function createRouter<Data = Record<string, unknown>>(options: RouterOptions = {}): Router<Data> {
   const mode = options.mode || 'history'
   const qs = options.qs || defaultQs
-  const sync = options.sync || false
-  const history = createHistory({ mode, sync })
+  const history = createHistory({ mode, sync: options.sync, schedule: options.schedule })
 
-  let routes: FlatRoute[] = []
+  let matcher = createMatcher<Data>([], { qs })
 
   const router: Router<Data> = {
     listen(routeMap, cb) {
-      routes = flatten(routeMap as RouteDefinition[])
+      matcher = createMatcher(routeMap, { qs })
       let redirects = 0
       return history.listen((url) => {
-        const route = router.match(url)
+        const route = matcher.match(url)
         if (!route) {
           redirects = 0
           return
         }
-        for (const r of route.data as Array<{ redirect?: Redirect<Data> }>) {
+        for (const r of route.data) {
           if (r.redirect) {
             if (++redirects > MAX_REDIRECTS) {
               redirects = 0
@@ -138,11 +151,7 @@ export function createRouter<Data = Record<string, unknown>>(options: RouterOpti
     },
 
     match(url) {
-      const route = findMatch(routes, url, qs)
-      if (route) {
-        return { ...route, data: data(routes, route) } as Route<Data>
-      }
-      return undefined
+      return matcher.match(url)
     },
 
     getUrl() {
@@ -153,22 +162,48 @@ export function createRouter<Data = Record<string, unknown>>(options: RouterOpti
   return router
 }
 
-export function flatten(routeMap: RouteDefinition[]): FlatRoute[] {
-  const routes: FlatRoute[] = []
-  const parentData: Array<Record<string, unknown>> = []
-  function addLevel(level: RouteDefinition[]) {
+export function createMatcher<Data = Record<string, unknown>>(
+  routeMap: RouteDefinition<Data>[],
+  options: MatcherOptions = {},
+): Matcher<Data> {
+  const routes = flatten(routeMap)
+  const qs = options.qs || defaultQs
+
+  return {
+    match(url) {
+      if (!url) return undefined
+      for (const route of routes) {
+        const m = matchOne(route.pattern, url, qs)
+        if (m) {
+          return { ...m, data: route.data } as Route<Data>
+        }
+      }
+      return undefined
+    },
+  }
+}
+
+export function flatten<Data = Record<string, unknown>>(routeMap: RouteDefinition<Data>[]): FlatRoute<Data>[] {
+  const routes: FlatRoute<Data>[] = []
+  const parentData: RouteData<Data>[] = []
+  function addLevel(level: RouteDefinition<Data>[]) {
     level.forEach((route) => {
       const {
         path = '',
         routes: children,
         ...routeData
-      } = route as RouteDefinition & {
+      } = route as RouteDefinition<Data> & {
         path?: string
-        routes?: RouteDefinition[]
+        routes?: RouteDefinition<Data>[]
+      }
+      const segment = { path, ...routeData } as RouteData<Data>
+      // pathless routes only contribute data to their children — they have
+      // no pattern of their own to match
+      if (path) {
+        routes.push({ pattern: path, data: parentData.concat([segment]) })
       }
-      routes.push({ pattern: path, data: parentData.concat([routeData]) })
       if (children) {
-        parentData.push(routeData)
+        parentData.push(segment)
         addLevel(children)
         parentData.pop()
       }
@@ -178,15 +213,6 @@ export function flatten(routeMap: RouteDefinition[]): FlatRoute[] {
   return routes
 }
 
-function data(routes: FlatRoute[], matchingRoute: { pattern: string }) {
-  for (let i = 0; i < routes.length; i++) {
-    if (routes[i].pattern === matchingRoute.pattern) {
-      return routes[i].data
-    }
-  }
-  return []
-}
-
 export function merge(curr: Partial<Route> | NavigateTarget | undefined, to: NavigateTarget): NavigateTarget {
   const c = (curr || {}) as Partial<Route> & NavigateTarget
   const pathname = to.pathname || c.pattern || c.pathname