navgo 5.0.0 → 6.0.0-beta.0

package/index.d.ts

@@ -3,23 +3,31 @@
  * For string patterns, missing optional params are `null`.
  * For RegExp named groups, missing groups may be `undefined`.
  */
-export type Params = Record<string, string | null | undefined>
+export type RawParam = string | null | undefined
+export type Params = Record<string, any>
 
 /** Built-in validator helpers shape. */
 export interface ValidatorHelpers {
-	int(opts?: {
-		min?: number | null
-		max?: number | null
-	}): (value: string | null | undefined) => boolean
-	one_of(values: Iterable<string>): (value: string | null | undefined) => boolean
+	int(opts?: { min?: number | null; max?: number | null }): (value: RawParam) => boolean
+	one_of(values: Iterable<string>): (value: RawParam) => boolean
+}
+
+export type ParamRule =
+	| ((value: RawParam) => boolean)
+	| { validator?: (value: RawParam) => boolean; coercer?: (value: RawParam) => any }
+
+export interface LoaderArgs {
+	route_entry: RouteTuple
+	url: URL
+	params: Params
 }
 
 /** Optional per-route hooks recognized by Navgo. */
 export interface Hooks {
-	/** Validate params with custom per-param validators. Return `false` to skip a match. */
-	param_validators?: Record<string, (value: string | null | undefined) => boolean>
+	/** Validate and/or coerce params (validator runs before coercer). */
+	param_rules?: Record<string, ParamRule>
 	/** Load data for a route before navigation. May return a Promise or an array of values/promises. */
-	loader?(params: Params): unknown | Promise<unknown> | Array<unknown | Promise<unknown>>
+	loader?(args: LoaderArgs): unknown | Promise<unknown> | Array<unknown | Promise<unknown>>
 	/** Predicate used during match(); may be async. If it returns `false`, the route is skipped. */
 	validate?(params: Params): boolean | Promise<boolean>
 	/** Route-level navigation guard, called on the current route when leaving it. Synchronous only; call `nav.cancel()` to prevent navigation. */
@@ -46,8 +54,8 @@ export interface Navigation {
 	cancel(): void
 }
 
-/** A route tuple: [pattern, data?]. The `data` may include {@link Hooks}. */
-export type RouteTuple<T = unknown> = [pattern: string | RegExp, data: T]
+/** A route tuple: [pattern, data?, extra?]. The `data`/`extra` may include {@link Hooks}. */
+export type RouteTuple<T = unknown, U = unknown> = [pattern: string | RegExp, data?: T, extra?: U]
 
 /** Result of calling `router.match(url)` */
 export interface MatchResult<T = unknown> {
@@ -86,11 +94,10 @@ export interface Options {
 	 *  scrolling lands on the correct elements.
 	 */
 	tick?: () => void | Promise<void>
-	/** Global hook fired whenever the URL changes.
-	 *  Triggers for shallow pushes/replaces, hash changes, popstate-shallow, 404s, and full navigations.
-	 *  Receives the router's current snapshot (eg `{ url: URL, route: RouteTuple|null, params: Params }`).
-	 */
-	url_changed?(payload: any): void
+	/** When `false`, do not scroll to top on non-hash navigations. Default true. */
+	scroll_to_top?: boolean
+	/** When `true`, sets `aria-current="page"` on active in-app links. Default false. */
+	aria_current?: boolean
 }
 
 /** Navgo default export: class-based router. */

package/index.js

@@ -1,3 +1,4 @@
+import { throttle } from 'es-toolkit'
 import { parse } from 'regexparam'
 import { tick } from 'svelte'
 import { writable } from 'svelte/store'
@@ -12,8 +13,9 @@ export default class Navgo {
 		preload_on_hover: true,
 		before_navigate: undefined,
 		after_navigate: undefined,
-		url_changed: undefined,
 		tick,
+		scroll_to_top: true,
+		aria_current: false,
 		attach_to_window: true,
 	}
 	/** @type {Array<{ pattern: RegExp, keys: string[]|null, data: RouteTuple }>} */
@@ -105,6 +107,7 @@ export default class Navgo {
 			ℹ('  - [🧭 event:popstate]', 'same path+search; skip loader')
 			this.#apply_scroll(ev)
 			this.route.set(this.#current)
+			this.#update_active_links()
 			return
 		}
 		// Explicit shallow entries (pushState/replaceState) regardless of path
@@ -113,6 +116,7 @@ export default class Navgo {
 			ℹ('  - [🧭 event:popstate]', 'shallow entry; skip loader')
 			this.#apply_scroll(ev)
 			this.route.set(this.#current)
+			this.#update_active_links()
 			return
 		}
 
@@ -138,7 +142,7 @@ export default class Navgo {
 				if (pos) {
 					scrollTo(pos.x, pos.y)
 					ℹ('[🧭 scroll]', 'restore hash-back', { idx: this.#route_idx, ...pos })
-				} else {
+				} else if (this.#opts.scroll_to_top) {
 					// no saved position for previous entry — default to top
 					scrollTo(0, 0)
 					ℹ('[🧭 scroll]', 'hash-back -> top')
@@ -148,6 +152,7 @@ export default class Navgo {
 		// update current URL snapshot and notify
 		this.#current.url = new URL(location.href)
 		this.route.set(this.#current)
+		this.#update_active_links()
 	}
 
 	/** @type {any} */
@@ -200,7 +205,7 @@ export default class Navgo {
 			will_unload: true,
 			event: ev,
 		})
-		this.#current.route?.[1]?.before_route_leave?.(nav)
+		this.#get_hooks(this.#current.route)?.before_route_leave?.(nav)
 		if (nav.cancelled) {
 			ℹ('[🧭 navigate]', 'cancelled by before_route_leave during unload')
 			ev.preventDefault()
@@ -245,17 +250,39 @@ export default class Navgo {
 			: null
 	}
 
-	#check_param_validators(param_validators, params) {
-		for (const k in param_validators) {
-			const fn = param_validators[k]
-			if (typeof fn !== 'function') continue
-			if (!fn(params[k])) return false
+	#update_active_links() {
+		if (!this.#opts.aria_current) return
+		const cur = this.format(this.#current.url?.pathname)
+		if (!cur) return
+		for (const a of document.querySelectorAll('a[href]')) {
+			const href = a.getAttribute('href')
+			if (href[0] === '#') continue
+			const link_path = href && this.#resolve_url_and_path(href)?.path
+			if (link_path === cur) a.setAttribute('aria-current', 'page')
+			else if (a.getAttribute('aria-current') === 'page') a.removeAttribute('aria-current')
+		}
+	}
+
+	#get_hooks(route) {
+		if (!route) return {}
+		const a = route[1]
+		const b = route[2]
+		if (!b) return a || {}
+		const hooks = { ...(a || {}), ...b }
+		const ar = a?.param_rules
+		const br = b?.param_rules
+		if (ar || br) {
+			const out = {}
+			const norm = r => (typeof r === 'function' ? { validator: r } : r || {})
+			for (const k in ar || {}) out[k] = norm(ar[k])
+			for (const k in br || {}) out[k] = { ...out[k], ...norm(br[k]) }
+			hooks.param_rules = out
 		}
-		return true
+		return hooks
 	}
 
 	async #run_loader(route, url, params) {
-		const ret_val = route[1].loader?.({ route_entry: route, url, params })
+		const ret_val = this.#get_hooks(route)?.loader?.({ route_entry: route, url, params })
 		return Array.isArray(ret_val) ? Promise.all(ret_val) : ret_val
 	}
 
@@ -316,7 +343,7 @@ export default class Navgo {
 		//
 		// before_route_leave
 		//
-		this.#current.route?.[1]?.before_route_leave?.(nav)
+		this.#get_hooks(this.#current.route)?.before_route_leave?.(nav)
 		if (nav.cancelled) {
 			// use history.go to cancel the nav, and jump back to where we are
 			if (is_popstate) {
@@ -353,11 +380,23 @@ export default class Navgo {
 		let data
 		if (hit) {
 			const pre = this.#preloads.get(path)
-			data =
-				pre?.data ??
-				(await (pre?.promise || this.#run_loader(hit.route, url, hit.params)).catch(e => ({
-					__error: e,
-				})))
+			try {
+				data =
+					pre?.data ??
+					(await (pre?.promise || this.#run_loader(hit.route, url, hit.params)))
+			} catch (e) {
+				this.#preloads.delete(path)
+				ℹ('[🧭 loader]', 'error; abort', { path, error: e })
+				if (is_popstate) {
+					const new_idx = ev_param?.state?.__navgo?.idx
+					if (new_idx != null) {
+						const delta = new_idx - this.#route_idx
+						if (delta) history.go(-delta)
+					}
+				}
+				if (nav_id === this.#nav_active) this.is_navigating.set(false)
+				return
+			}
 			this.#preloads.delete(path)
 			ℹ('[🧭 loader]', pre ? 'using preloaded data' : 'loaded', {
 				path,
@@ -425,6 +464,7 @@ export default class Navgo {
 		// allow frameworks to flush DOM before scrolling
 		await this.#opts.tick?.()
 
+		this.#update_active_links()
 		this.#apply_scroll(nav)
 		this.is_navigating.set(false)
 	}
@@ -465,6 +505,7 @@ export default class Navgo {
 		// update current URL snapshot and notify
 		this.#current.url = u
 		this.route.set(this.#current)
+		this.#update_active_links()
 	}
 
 	/** @param {string|URL} [url] @param {any} [state] */
@@ -535,15 +576,28 @@ export default class Navgo {
 			}
 
 			// per-route validators and optional async validate()
-			const hooks = obj.data[1]
-			if (
-				hooks.param_validators &&
-				!this.#check_param_validators(hooks.param_validators, params)
-			) {
-				ℹ('[🧭 match]', 'skip: param_validators', {
-					pattern: obj.data?.[0],
-				})
-				continue
+			const hooks = this.#get_hooks(obj.data)
+			if (hooks.param_rules) {
+				let ok = true
+				for (const k in hooks.param_rules) {
+					const param_rule = hooks.param_rules[k]
+					const param_validator =
+						typeof param_rule === 'function' ? param_rule : param_rule?.validator
+					if (typeof param_validator === 'function' && !param_validator(params[k])) {
+						ok = false
+						break
+					}
+				}
+				if (!ok) {
+					ℹ('[🧭 match]', 'skip: param_rules', { pattern: obj.data?.[0] })
+					continue
+				}
+				for (const k in hooks.param_rules) {
+					const param_rule = hooks.param_rules[k]
+					const param_coercer =
+						typeof param_rule === 'function' ? null : param_rule?.coercer
+					if (typeof param_coercer === 'function') params[k] = param_coercer(params[k])
+				}
 			}
 			if (hooks.validate && !(await hooks.validate(params))) {
 				ℹ('[🧭 match]', 'skip: validate', { pattern: obj.data?.[0] })
@@ -572,11 +626,6 @@ export default class Navgo {
 			return pat
 		})
 
-		// TODO: deprecated, remove later
-		this.route.subscribe(() => {
-			this.#opts.url_changed?.(this.#current)
-		})
-
 		ℹ('[🧭 init]', {
 			base: this.#base,
 			routes: this.#routes.length,
@@ -699,8 +748,10 @@ export default class Navgo {
 				return
 			}
 			// 3) Default: scroll to top for new navigations
-			scrollTo(0, 0)
-			ℹ('[🧭 scroll]', 'top')
+			if (this.#opts.scroll_to_top) {
+				scrollTo(0, 0)
+				ℹ('[🧭 scroll]', 'top')
+			}
 		})
 	}
 
@@ -736,27 +787,6 @@ export default class Navgo {
 	}
 }
 
-function throttle(fn, ms) {
-	let t,
-		last = 0
-	return e => {
-		const now = Date.now()
-		if (now - last >= ms) {
-			last = now
-			fn(e)
-		} else {
-			clearTimeout(t)
-			t = setTimeout(
-				() => {
-					last = Date.now()
-					fn(e)
-				},
-				ms - (now - last),
-			)
-		}
-	}
-}
-
 /** @typedef {import('./index.d.ts').Options} Options */
 /** @typedef {import('./index.d.ts').RouteTuple} RouteTuple */
 /** @typedef {import('./index.d.ts').MatchResult} MatchResult */

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "navgo",
-	"version": "5.0.0",
+	"version": "6.0.0-beta.0",
 	"repository": {
 		"type": "git",
 		"url": "git+https://github.com/mustafa0x/navgo.git"
@@ -18,7 +18,7 @@
 		"build": "perl -0777 -i -pe 's/console.debug\\(...args\\)/{}/g' index.js",
 		"prepublishOnly": "pnpm run build",
 		"test": "vitest run index.test.js",
-		"test:e2e": "playwright test",
+		"test:e2e": "playwright test --project=chromium",
 		"start:testsite": "pnpm vite dev test/site --port 5714",
 		"types": "tsc -p test/types"
 	},
@@ -32,6 +32,7 @@
 		"router"
 	],
 	"dependencies": {
+		"es-toolkit": "^1.42.0",
 		"regexparam": "^3.0.0"
 	},
 	"peerDependencies": {

package/readme.md

@@ -8,62 +8,64 @@ $ pnpm install --dev navgo
 
 ```js
 import Navgo from 'navgo'
+import {mount} from 'svelte'
+
+import App from './App.svelte'
+import * as HomeRoute from './routes/Home.svelte'
+import * as ReaderRoute from './routes/Reader.svelte'
+import * as AccountRoute from './routes/Account.svelte'
+import * as AdminRoute from './routes/Admin.svelte'
+import * as DebugRoute from './routes/Debug.svelte'
 
-// Define routes up front (strings or RegExp)
 const routes = [
-  ['/', {}],
-  ['/users/:username', {}],
-  ['/books/*', {}],
-  [/articles\/(?<year>[0-9]{4})/, {}],
-  [/privacy|privacy-policy/, {}],
+  ['/', HomeRoute],
+  ['/:book_id', ReaderRoute],
+  ['/account', AccountRoute],
   [
-    '/admin',
+    '/admin/:id',
+    AdminRoute,
     {
-      // constrain params with built-ins or your own
-      param_validators: {
-        /* id: Navgo.validators.int({ min: 1 }) */
+      // constrain/coerce params
+      param_rules: {
+        id: { validator: Navgo.validators.int({ min: 1 }), coercer: Number },
       },
       // load data before URL changes; result goes to after_navigate(...)
-      loader: params => fetch('/api/admin').then(r => r.json()),
+      loader: ({ params }) => fetch(`/api/admin/${params.id}`).then(r => r.json()),
       // per-route guard; cancel synchronously to block nav
       before_route_leave(nav) {
-        if ((nav.type === 'link' || nav.type === 'nav') && !confirm('Enter admin?')) {
+        if ((nav.type === 'link' || nav.type === 'goto') && !confirm('Enter admin?')) {
           nav.cancel()
         }
       },
     },
   ],
 ]
+if (window.__DEBUG__) routes.push(['/debug', DebugRoute])
+
+const props = $state({
+  component: null,
+  route_data: null,
+  is_404: false,
+})
+
+function after_navigate(nav) {
+  props.is_404 = nav.to?.data?.__error?.status === 404
+  props.route_data = nav.to?.data ?? null
+  props.component = nav.to?.route?.[1]?.default || null
+}
 
-// Create router with options + callbacks
 const router = new Navgo(routes, {
-  base: '/',
   before_navigate(nav) {
     // app-level hook before loader/URL update; may cancel
     console.log('before_navigate', nav.type, '→', nav.to?.url.pathname)
   },
-  after_navigate(nav) {
-    // called after routing completes; nav.to.data holds loader result
-    if (nav.to?.data?.__error?.status === 404) {
-      console.log('404 for', nav.to.url.pathname)
-      return
-    }
-
-    console.log('after_navigate', nav.to?.url.pathname, nav.to?.data)
-  },
-  // let your framework flush DOM before scroll
-  // e.g. in Svelte: `import { tick } from 'svelte'`
-  tick: tick,
-  url_changed(cur) {
-    // fires on shallow/hash/popstate-shallow/404 and full navigations
-    // `cur` is the router snapshot: { url: URL, route, params }
-    console.log('url_changed', cur.url.href)
-  },
+  after_navigate,
 })
 
 // Long-lived router: history + <a> bindings
 // Also immediately processes the current location
 router.init()
+mount(App, {target: document.body, props})
 ```
 
 ## API
@@ -74,9 +76,9 @@ Returns: `Router`
 
 #### `routes`
 
-Type: `Array<[pattern: string | RegExp, data: any]>`
+Type: `Array<[pattern: string | RegExp, data?: any, extra?: any]>`
 
-Each route is a tuple whose first item is the pattern and whose second item is hooks (see “Route Hooks”). Pass `{}` when no hooks are needed. Navgo returns this tuple back to you unchanged via `onRoute`.
+Each route is a tuple whose first item is the pattern and whose second item is hooks (see “Route Hooks”). The optional third item is extra hooks and is merged with the second item (third wins; `param_rules` are merged by key).
 
 Supported pattern types:
 
@@ -102,10 +104,10 @@ Notes:
   - App-level hook called after routing completes (URL updated, data loaded). `nav.to.data` holds any loader data.
 - `tick`: `() => void | Promise<void>`
   - Awaited after `after_navigate` and before scroll handling; useful for frameworks to flush DOM so anchor/top scrolling lands correctly.
-- `url_changed`: `(snapshot: any) => void`
-  - Fires on every URL change -- shallow `push_state`/`replace_state`, hash changes, `popstate` shallow entries, 404s, and full navigations. (deprecated; subscribe to `.route` instead.)
-  - Receives the router's current snapshot: an object like `{ url: URL, route: RouteTuple|null, params: Params }`.
-  - The snapshot type is intentionally `any` and may evolve without a breaking change.
+- `scroll_to_top`: `boolean` (default `true`)
+  - When `false`, skips the default top scroll for non-hash navigations.
+- `aria_current`: `boolean` (default `false`)
+  - When `true`, sets `aria-current="page"` on active in-app links.
 - `preload_delay`: `number` (default `20`)
   - Delay in ms before hover preloading triggers.
 - `preload_on_hover`: `boolean` (default `true`)
@@ -137,10 +139,11 @@ const {route, is_navigating} = router
 
 ### Route Hooks
 
-- param_validators?: `Record<string, (value: string|null|undefined) => boolean>`
-  - Validate params (e.g., `id: Navgo.validators.int({ min: 1 })`). Any `false` result skips the route.
-- loader?(params): `unknown | Promise | Array<unknown|Promise>`
-  - Run before URL changes on `link`/`nav`. Results are cached per formatted path and forwarded to `after_navigate`.
+- param_rules?: `Record<string, ((value: string|null|undefined) => boolean) | { validator?: (value: string|null|undefined) => boolean; coercer?: (value: string|null|undefined) => any }>`
+  - Single place for param rules. If the value is a function, it is treated as a validator.
+  - Validators run on raw params; coercers run after validators and may transform params before `validate(...)`/`loader`.
+- loader?({ params }): `unknown | Promise | Array<unknown|Promise>`
+  - Run before URL changes on `link`/`goto`. Results are cached per formatted path and forwarded to `after_navigate`.
 - validate?(params): `boolean | Promise<boolean>`
   - Predicate called during matching. If it returns or resolves to `false`, the route is skipped.
 - before_route_leave?(nav): `(nav: Navigation) => void`
@@ -150,7 +153,7 @@ The `Navigation` object contains:
 
 ```ts
 {
-  type: 'link' | 'nav' | 'popstate' | 'leave',
+  type: 'link' | 'goto' | 'popstate' | 'leave',
   from: { url, params, route } | null,
   to:   { url, params, route } | null,
   will_unload: boolean,
@@ -164,7 +167,7 @@ The `Navigation` object contains:
 
 - Router calls `before_navigate` on the current route (leave).
 - Call `nav.cancel()` synchronously to cancel.
-  - For `link`/`nav`, it stops before URL change.
+  - For `link`/`goto`, it stops before URL change.
   - For `popstate`, cancellation causes an automatic `history.go(...)` to revert to the previous index.
   - For `leave`, cancellation triggers the native “Leave site?” dialog (behavior is browser-controlled).
 
@@ -173,15 +176,15 @@ Example:
 ```js
 const routes = [
   [
-    '/admin',
+    '/account/:account_id',
     {
-      param_validators: {
-        /* ... */
+      param_rules: {
+        account_id: {validator: Navgo.validators.int({min: 1}), coercer: Number},
       },
-      loader: params => fetch('/api/admin/stats').then(r => r.json()),
+      loader: ({params}) => fetch(`/api/account/${params.account_id}`).then(r => r.json()),
       before_route_leave(nav) {
-        if (nav.type === 'link' || nav.type === 'nav') {
-          if (!confirm('Enter admin area?')) nav.cancel()
+        if (nav.type === 'link' || nav.type === 'goto') {
+          if (!confirm('Leave account settings?')) nav.cancel()
         }
       },
     },
@@ -323,7 +326,7 @@ The router passes the type to your route-level `before_route_leave(nav)` hook.
 - Named params from string patterns populate `params` with `string` values; optional params that do not appear are `null`.
 - Wildcards use the `'*'` key.
 - RegExp named groups also populate `params`; omitted groups can be `undefined`.
-- If `data.param_validators` is present, each `params[k]` is validated; any `false` result skips that route.
+- If `data.param_rules` is present, each `params[k]` validator runs first, then coercers run to transform params.
 - If `data.validate(params)` returns or resolves to `false`, the route is also skipped.
 
 ### Data Flow
@@ -335,7 +338,7 @@ For `link` and `goto` navigations that match a route:
         → before_route_leave({ type })  // per-route guard
         → before_navigate(nav)        // app-level start
             → cancelled? yes → stop
-            → no → run loader(params)  // may be value, Promise, or Promise[]
+            → no → run loader({ params })  // may be value, Promise, or Promise[]
             → cache data by formatted path
             → history.push/replaceState(new URL)
             → after_navigate(nav)
@@ -343,8 +346,8 @@ For `link` and `goto` navigations that match a route:
             → scroll restore/hash/top
 ```
 
-- If a loader throws/rejects, navigation continues and `after_navigate(..., with nav.to.data = { __error })` is delivered so UI can render an error state.
-- For `popstate`, the route's `loader` runs before completion so content matches the target entry; this improves scroll restoration. Errors are delivered via `after_navigate` with `nav.to.data = { __error }`.
+- If a loader throws/rejects, navigation aborts (no URL/history change, no `after_navigate`).
+- For `popstate`, the route's `loader` runs before completion so content matches the target entry; this improves scroll restoration. If the loader throws, the popstate is reverted.
 
 ### Shallow Routing
 
@@ -367,7 +370,7 @@ To enable `popstate` cancellation, Navgo stores a monotonic `idx` in `history.st
 Navgo manages scroll manually (sets `history.scrollRestoration = 'manual'`) and applies SvelteKit-like behavior:
 
 - Saves the current scroll position for the active history index.
-- On `link`/`nav` (after route commit):
+- On `link`/`goto` (after route commit):
   - If the URL has a `#hash`, scroll to the matching element `id` or `[name="..."]`.
   - Otherwise, scroll to the top `(0, 0)`.
 - On `popstate`: restore the saved position for the target history index; if not found but there is a `#hash`, scroll to the anchor instead.
@@ -396,7 +399,7 @@ scroll flow
 - `Navgo.validators.int({ min?, max? })` -- `true` iff the value is an integer within optional bounds.
 - `Navgo.validators.one_of(iterable)` -- `true` iff the value is in the provided set.
 
-Attach validators via a route tuple's `data.param_validators` to constrain matches.
+Attach validators via a route tuple's `data.param_rules` rules.
 
 # Credits