space-router 1.1.0 → 1.2.0

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,16 +50,18 @@ 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 && memory.length) {
@@ -59,7 +70,7 @@ export function createHistory(options = {}) {
             else {
                 memory.push(url);
             }
-            schedule();
+            scheduleEmit(false);
         }
     }
     function getUrl() {

package/dist/index.d.ts

@@ -2,5 +2,5 @@ export { qs } from './qs.ts';
 export { createHistory } from './history.ts';
 export { createMatcher, createRouter, merge } from './router.ts';
 export type { Qs } from './qs.ts';
-export type { Mode, History, CreateHistoryOptions } from './history.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/router.d.ts

@@ -1,10 +1,11 @@
 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;

package/dist/router.js

@@ -6,8 +6,7 @@ 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 });
+    const history = createHistory({ mode, sync: options.sync, schedule: options.schedule });
     let matcher = createMatcher([], { qs });
     const router = {
         listen(routeMap, cb) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "space-router",
   "description": "All the routing essentials.",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.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,21 +76,22 @@ 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 && memory.length) {
         memory[memory.length - 1] = url
       } else {
         memory.push(url)
       }
-      schedule()
+      scheduleEmit(false)
     }
   }
 

package/src/index.ts

@@ -3,7 +3,7 @@ export { createHistory } from './history.ts'
 export { createMatcher, createRouter, merge } from './router.ts'
 
 export type { Qs } from './qs.ts'
-export type { Mode, History, CreateHistoryOptions } from './history.ts'
+export type { Mode, History, CreateHistoryOptions, Schedule, ScheduleInfo } from './history.ts'
 export type {
   MatcherOptions,
   RouteData,

package/src/router.ts

@@ -1,11 +1,12 @@
 import { matchOne, type MatchedRoute } from './match.ts'
-import { createHistory, type Mode } from './history.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 {
@@ -64,8 +65,7 @@ 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 matcher = createMatcher<Data>([], { qs })