navgo 3.0.3 → 3.0.4

package/index.d.ts

@@ -14,7 +14,7 @@ export interface ValidatorHelpers {
 	oneOf(values: Iterable<string>): (value: string | null | undefined) => boolean
 }
 
-/** Optional per-route hooks recognized by Navaid. */
+/** 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>
@@ -55,27 +55,11 @@ export interface MatchResult<T = unknown> {
 	params: Params
 }
 
-export interface Router<T = unknown> {
-	/** Format `url` relative to the configured base. */
-	format(url: string): string | false
-	/** SvelteKit-like navigation that runs loaders before updating the URL. */
-	goto(url: string, opts?: { replace?: boolean }): Promise<void>
-	/** Shallow push — updates URL/state without triggering handlers. */
-	pushState(url?: string | URL, state?: any): void
-	/** Shallow replace — updates URL/state without triggering handlers. */
-	replaceState(url?: string | URL, state?: any): void
-	/** Manually preload loaders for a URL (deduped). */
-	preload(url: string): Promise<unknown | void>
-	/** Try to match `url`; returns route tuple and params or `null`. Supports async `validate`. */
-	match(url: string): Promise<MatchResult<T> | null>
-	/** Attach history + click listeners and immediately process current location. */
-	init(): Promise<void>
-	/** Remove listeners installed by `init()`. */
-	destroy(): void
-}
+// For convenience in docs/types, alias the class instance type
+export type Router<T = unknown> = Navgo<T>
 
-/** Router metadata stored under `history.state.__navaid`. */
-export interface NavaidHistoryMeta {
+/** Router metadata stored under `history.state.__navgo`. */
+export interface NavgoHistoryMeta {
 	/** Monotonic index of the current history entry for scroll restoration. */
 	idx: number
 	/** Present when the entry was created via shallow `pushState`/`replaceState`. */
@@ -102,9 +86,25 @@ export interface Options {
 	url_changed?(payload: any): void
 }
 
-/** Navaid default export: class-based router. */
-export default class Navgo<T = unknown> implements Router<T> {
+/** Navgo default export: class-based router. */
+export default class Navgo<T = unknown> {
 	constructor(routes?: Array<RouteTuple<T>>, opts?: Options)
+	/** Format `url` relative to the configured base. */
+	format(url: string): string | false
+	/** SvelteKit-like navigation that runs loaders before updating the URL. */
+	goto(url: string, opts?: { replace?: boolean }): Promise<void>
+	/** Shallow push — updates URL/state without triggering handlers. */
+	pushState(url?: string | URL, state?: any): void
+	/** Shallow replace — updates URL/state without triggering handlers. */
+	replaceState(url?: string | URL, state?: any): void
+	/** Manually preload loaders for a URL (deduped). */
+	preload(url: string): Promise<unknown | void>
+	/** Try to match `url`; returns route tuple and params or `null`. Supports async `validate`. */
+	match(url: string): Promise<MatchResult<T> | null>
+	/** Attach history + click listeners and immediately process current location. */
+	init(): Promise<void>
+	/** Remove listeners installed by `init()`. */
+	destroy(): void
 	/** Built-in validator helpers (namespaced). */
 	static validators: ValidatorHelpers
 }

package/index.js

@@ -1,6 +1,6 @@
 import { parse } from 'regexparam'
 
-const ℹ = (...args) => console.debug(...args)
+const ℹ = (...args) => {}
 
 export default class Navgo {
 	#opts = {
@@ -67,7 +67,7 @@ export default class Navgo {
 		// ignore popstate while a hash-originating nav is in flight
 		if (this.#hash_navigating) return
 
-		const st = ev?.state?.__navaid
+		const st = ev?.state?.__navgo
 		ℹ('[🧭 event:popstate]', st)
 		// Hash-only or state-only change: pathname+search unchanged -> skip loaders
 		const cur = this.#current.url
@@ -97,7 +97,7 @@ export default class Navgo {
 			this.#hash_navigating = false
 			const prev = history.state && typeof history.state == 'object' ? history.state : {}
 			const next_idx = this.#route_idx + 1
-			const next_state = { ...prev, __navaid: { ...prev.__navaid, idx: next_idx } }
+			const next_state = { ...prev, __navgo: { ...prev.__navgo, idx: next_idx } }
 			history.replaceState(next_state, '', location.href)
 			this.#route_idx = next_idx
 			ℹ('[🧭 event:hashchange]', { idx: next_idx, href: location.href })
@@ -125,7 +125,7 @@ export default class Navgo {
 		// persist scroll for refresh / session restore
 		try {
 			sessionStorage.setItem(
-				`__navaid_scroll:${location.href}`,
+				`__navgo_scroll:${location.href}`,
 				JSON.stringify({ x: scrollX, y: scrollY }),
 			)
 		} catch {}
@@ -259,7 +259,7 @@ export default class Navgo {
 		if (nav.cancelled) {
 			// use history.go to cancel the nav, and jump back to where we are
 			if (is_popstate) {
-				const new_idx = ev_param?.state?.__navaid?.idx
+				const new_idx = ev_param?.state?.__navgo?.idx
 				if (new_idx != null) {
 					const delta = new_idx - this.#route_idx
 					if (delta) {
@@ -315,7 +315,7 @@ export default class Navgo {
 				history.state && typeof history.state == 'object' ? history.state : {}
 			const next_state = {
 				...prev_state,
-				__navaid: { ...prev_state.__navaid, idx: next_idx, type: nav_type },
+				__navgo: { ...prev_state.__navgo, idx: next_idx, type: nav_type },
 			}
 			history[(opts.replace ? 'replace' : 'push') + 'State'](next_state, null, url.href)
 			ℹ('[🧭 history]', opts.replace ? 'replaceState' : 'pushState', {
@@ -522,10 +522,10 @@ export default class Navgo {
 		}
 
 		// ensure current history state carries our index
-		const cur_idx = history.state?.__navaid?.idx
+		const cur_idx = history.state?.__navgo?.idx
 		if (cur_idx == null) {
 			const prev = history.state && typeof history.state == 'object' ? history.state : {}
-			const next_state = { ...prev, __navaid: { ...prev.__navaid, idx: this.#route_idx } }
+			const next_state = { ...prev, __navgo: { ...prev.__navgo, idx: this.#route_idx } }
 			history.replaceState(next_state, '', location.href)
 			ℹ('[🧭 history]', 'init idx', { idx: this.#route_idx })
 		} else {
@@ -567,7 +567,7 @@ export default class Navgo {
 			const is_initial = ctx && 'from' in ctx ? ctx.from == null : !t
 			if (is_initial) {
 				try {
-					const k = `__navaid_scroll:${location.href}`
+					const k = `__navgo_scroll:${location.href}`
 					const { x, y } = JSON.parse(sessionStorage.getItem(k))
 					sessionStorage.removeItem(k)
 					scrollTo(x, y)
@@ -578,7 +578,7 @@ export default class Navgo {
 			// 1) On back/forward, restore saved position if available
 			if (t === 'popstate') {
 				const ev_state = ctx?.state ?? ctx?.event?.state
-				const idx = ev_state?.__navaid?.idx
+				const idx = ev_state?.__navgo?.idx
 				const target_idx = typeof idx === 'number' ? idx : this.#route_idx - 1
 				this.#route_idx = target_idx
 				const pos = this.#scroll.get(target_idx)

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "navgo",
-	"version": "3.0.3",
+	"version": "3.0.4",
 	"repository": {
 		"type": "git",
 		"url": "git+https://github.com/mustafa0x/navgo.git"
@@ -15,11 +15,10 @@
 		"name": "mustafa j"
 	},
 	"scripts": {
-		"pretest": "pnpm run build",
-		"test": "vitest run",
-		"test:e2e": "playwright test",
-		"test:all": "pnpm run build && vitest run && playwright test",
-		"types": "pnpm --package=typescript@5.6.3 dlx tsc -p test/types"
+		"build": "perl -0777 -i -pe 's/console.debug\\(...args\\)/{}/g' index.js",
+		"prepublishOnly": "pnpm run build",
+		"test": "vitest run index.test.js",
+		"types": "tsc -p test/types"
 	},
 	"files": [
 		"*.d.ts",
@@ -34,26 +33,27 @@
 		"regexparam": "^3.0.0"
 	},
 	"devDependencies": {
-		"@eslint/js": "^9.36.0",
-		"@playwright/test": "^1.55.1",
+		"@eslint/js": "^9.37.0",
+		"@playwright/test": "^1.56.0",
 		"@sveltejs/vite-plugin-svelte": "^6.2.1",
-		"@tailwindcss/vite": "^4.1.13",
+		"@tailwindcss/vite": "^4.1.14",
 		"@tsconfig/svelte": "^5.0.5",
-		"@types/node": "^24.6.0",
-		"eslint": "^9.36.0",
+		"@types/node": "^24.7.2",
+		"eslint": "^9.37.0",
 		"eslint-plugin-svelte": "^3.12.4",
 		"globals": "^16.4.0",
-		"jiti": "^2.6.0",
+		"jiti": "^2.6.1",
 		"lightningcss": "^1.30.2",
 		"prettier": "^3.6.2",
 		"prettier-plugin-svelte": "^3.4.0",
 		"prettier-plugin-tailwindcss": "^0.6.14",
-		"svelte": "^5.39.7",
-		"tailwindcss": "^4.1.13",
+		"svelte": "^5.39.11",
+		"tailwindcss": "^4.1.14",
 		"terser": "5.44.0",
-		"typescript-eslint": "^8.45.0",
-		"vite": "^7.1.7",
-		"vitest": "^2.1.3"
+		"typescript": "5.9.3",
+		"typescript-eslint": "^8.46.0",
+		"vite": "^7.1.9",
+		"vitest": "^3.2.4"
 	},
 	"pnpm": {
 		"onlyBuiltDependencies": [
@@ -69,6 +69,15 @@
 		"quoteProps": "as-needed",
 		"bracketSpacing": true,
 		"arrowParens": "avoid",
-		"useTabs": true
+		"useTabs": true,
+		"overrides": [
+			{
+				"files": "*.md",
+				"options": {
+					"tabWidth": 2,
+					"useTabs": false
+				}
+			}
+		]
 	}
 }

package/readme.md

@@ -11,51 +11,51 @@ import Navgo from 'navgo'
 
 // Define routes up front (strings or RegExp)
 const routes = [
-	['/', {}],
-	['/users/:username', {}],
-	['/books/*', {}],
-	[/articles\/(?<year>[0-9]{4})/, {}],
-	[/privacy|privacy-policy/, {}],
-	[
-		'/admin',
-		{
-			// constrain params with built-ins or your own
-			param_validators: {
-				/* id: Navaid.validators.int({ min: 1 }) */
-			},
-			// load data before URL changes; result goes to after_navigate(...)
-			loaders: params => fetch('/api/admin').then(r => r.json()),
-			// per-route guard; cancel synchronously to block nav
-			beforeRouteLeave(nav) {
-				if ((nav.type === 'link' || nav.type === 'nav') && !confirm('Enter admin?')) {
-					nav.cancel()
-				}
-			},
-		},
-	],
+  ['/', {}],
+  ['/users/:username', {}],
+  ['/books/*', {}],
+  [/articles\/(?<year>[0-9]{4})/, {}],
+  [/privacy|privacy-policy/, {}],
+  [
+    '/admin',
+    {
+      // constrain params with built-ins or your own
+      param_validators: {
+        /* id: Navgo.validators.int({ min: 1 }) */
+      },
+      // load data before URL changes; result goes to after_navigate(...)
+      loaders: params => fetch('/api/admin').then(r => r.json()),
+      // per-route guard; cancel synchronously to block nav
+      beforeRouteLeave(nav) {
+        if ((nav.type === 'link' || nav.type === 'nav') && !confirm('Enter admin?')) {
+          nav.cancel()
+        }
+      },
+    },
+  ],
 ]
 
 // Create router with options + callbacks
 const router = new Navgo(routes, {
-	base: '/',
-	before_navigate(nav) {
-		// app-level hook before loaders/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)
-	},
-	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)
-	},
+  base: '/',
+  before_navigate(nav) {
+    // app-level hook before loaders/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)
+  },
+  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)
+  },
 })
 
 // Long-lived router: history + <a> bindings
@@ -92,32 +92,32 @@ Notes:
 #### `options`
 
 - `base`: `string` (default `'/'`)
-    - App base pathname. With or without leading/trailing slashes is accepted.
+  - App base pathname. With or without leading/trailing slashes is accepted.
 - `before_navigate`: `(nav: Navigation) => void`
-    - App-level hook called once per navigation attempt after the per-route guard and before loaders/URL update. May call `nav.cancel()` synchronously to prevent navigation.
+  - App-level hook called once per navigation attempt after the per-route guard and before loaders/URL update. May call `nav.cancel()` synchronously to prevent navigation.
 - `after_navigate`: `(nav: Navigation) => void`
-    - App-level hook called after routing completes (URL updated, data loaded). `nav.to.data` holds any loader data.
+  - App-level hook called after routing completes (URL updated, data loaded). `nav.to.data` holds any loader data.
 - `url_changed`: `(snapshot: any) => void`
-    - Fires on every URL change — shallow `pushState`/`replaceState`, hash changes, `popstate` shallow entries, 404s, and full navigations.
-    - 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.
+  - Fires on every URL change — shallow `pushState`/`replaceState`, hash changes, `popstate` shallow entries, 404s, and full navigations.
+  - 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.
 - `preload_delay`: `number` (default `20`)
-    - Delay in ms before hover preloading triggers.
+  - Delay in ms before hover preloading triggers.
 - `preload_on_hover`: `boolean` (default `true`)
-    - When `false`, disables hover/touch preloading.
+  - When `false`, disables hover/touch preloading.
 
-Important: Navaid only processes routes that match your `base` path.
+Important: Navgo only processes routes that match your `base` path.
 
 ### Route Hooks
 
 - param_validators?: `Record<string, (value: string|null|undefined) => boolean>`
-    - Validate params (e.g., `id: Navaid.validators.int({ min: 1 })`). Any `false` result skips the route.
+  - Validate params (e.g., `id: Navgo.validators.int({ min: 1 })`). Any `false` result skips the route.
 - loaders?(params): `unknown | Promise | Array<unknown|Promise>`
-    - Run before URL changes on `link`/`nav`. Results are cached per formatted path and forwarded to `after_navigate`.
+  - Run before URL changes on `link`/`nav`. 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.
+  - Predicate called during matching. If it returns or resolves to `false`, the route is skipped.
 - beforeRouteLeave?(nav): `(nav: Navigation) => void`
-    - Guard called once per navigation attempt on the current route (leave). Call `nav.cancel()` synchronously to prevent navigation. For `popstate`, cancellation auto-reverts the history jump.
+  - Guard called once per navigation attempt on the current route (leave). Call `nav.cancel()` synchronously to prevent navigation. For `popstate`, cancellation auto-reverts the history jump.
 
 The `Navigation` object contains:
 
@@ -137,29 +137,29 @@ 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 `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).
+  - For `link`/`nav`, 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).
 
 Example:
 
 ```js
 const routes = [
-	[
-		'/admin',
-		{
-			param_validators: {
-				/* ... */
-			},
-				loaders: params => fetch('/api/admin/stats').then(r => r.json()),
-			beforeRouteLeave(nav) {
-					if (nav.type === 'link' || nav.type === 'nav') {
-					if (!confirm('Enter admin area?')) nav.cancel()
-				}
-			},
-		},
-	],
-	['/', {}],
+  [
+    '/admin',
+    {
+      param_validators: {
+        /* ... */
+      },
+      loaders: params => fetch('/api/admin/stats').then(r => r.json()),
+      beforeRouteLeave(nav) {
+        if (nav.type === 'link' || nav.type === 'nav') {
+          if (!confirm('Enter admin area?')) nav.cancel()
+        }
+      },
+    },
+  ],
+  ['/', {}],
 ]
 
 const router = new Navgo(routes, { base: '/app' })
@@ -204,7 +204,7 @@ The desired path to navigate. If it begins with `/` and does not match the confi
 Type: `Object`
 
 - replace: `Boolean` (default `false`)
-    - When `true`, uses `history.replaceState`; otherwise `history.pushState`.
+  - When `true`, uses `history.replaceState`; otherwise `history.pushState`.
 
 ### init()
 
@@ -312,7 +312,7 @@ This lets you reflect UI state in the URL while deferring route transitions unti
 
 ### History Index & popstate Cancellation
 
-To enable `popstate` cancellation, Navaid stores a monotonic `idx` in `history.state.__navaid.idx`. On `popstate`, a cancelled navigation computes the delta between the target and current `idx` and calls `history.go(-delta)` to return to the prior entry.
+To enable `popstate` cancellation, Navgo stores a monotonic `idx` in `history.state.__navgo.idx`. On `popstate`, a cancelled navigation computes the delta between the target and current `idx` and calls `history.go(-delta)` to return to the prior entry.
 
 ### Scroll Restoration
 
@@ -320,8 +320,8 @@ Navgo manages scroll manually (sets `history.scrollRestoration = 'manual'`) and
 
 - Saves the current scroll position for the active history index.
 - On `link`/`nav` (after route commit):
-    - If the URL has a `#hash`, scroll to the matching element `id` or `[name="..."]`.
-    - Otherwise, scroll to the top `(0, 0)`.
+  - 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.
 - Shallow `pushState`/`replaceState` never adjust scroll (routing is skipped).