navgo 3.0.8 → 4.0.2

package/index.d.ts

@@ -7,23 +7,23 @@ export type Params = Record<string, string | null | undefined>
 
 /** Built-in validator helpers shape. */
 export interface ValidatorHelpers {
-	int(_opts?: {
+	int(opts?: {
 		min?: number | null
 		max?: number | null
-	}): (_value: string | null | undefined) => boolean
-	one_of(_values: Iterable<string>): (_value: string | null | undefined) => boolean
+	}): (value: string | null | undefined) => boolean
+	one_of(values: Iterable<string>): (value: string | null | undefined) => boolean
 }
 
 /** 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>
+	param_validators?: Record<string, (value: string | null | undefined) => boolean>
 	/** Load data for a route before navigation. May return a Promise or an array of values/promises. */
-	loaders?(_params: Params): unknown | Promise<unknown> | Array<unknown | Promise<unknown>>
+	loader?(params: Params): 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>
+	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. */
-	before_route_leave?(_nav: Navigation): void
+	before_route_leave?(nav: Navigation): void
 }
 
 export interface NavigationTarget {
@@ -31,7 +31,7 @@ export interface NavigationTarget {
 	params: Params
 	/** The matched route tuple from your original `routes` list; `null` when unmatched (e.g. external). */
 	route: RouteTuple | null
-	/** Optional data from route loaders when available. */
+	/** Optional data from route loader when available. */
 	data?: unknown
 }
 
@@ -77,10 +77,10 @@ export interface Options {
 	preload_on_hover?: boolean
 	/** Attach instance to window as `window.navgo`. Default true. */
 	attach_to_window?: boolean
-	/** Global hook fired after per-route `before_route_leave`, before loaders/history change. Can cancel. */
-	before_navigate?(_nav: Navigation): void
+	/** Global hook fired after per-route `before_route_leave`, before loader/history change. Can cancel. */
+	before_navigate?(nav: Navigation): void
 	/** Global hook fired after routing completes (data loaded, URL updated, handlers run). */
-	after_navigate?(_nav: Navigation): void
+	after_navigate?(nav: Navigation): void
 	/** Optional hook awaited after `after_navigate` and before scroll handling.
 	 *  Useful for UI frameworks (e.g., Svelte) to flush DOM updates so anchor/top
 	 *  scrolling lands on the correct elements.
@@ -90,24 +90,24 @@ export interface Options {
 	 *  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
+	url_changed?(payload: any): void
 }
 
 /** Navgo default export: class-based router. */
 export default class Navgo<T = unknown> {
-	constructor(_routes?: Array<RouteTuple<T>>, _opts?: Options)
+	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>
+	format(url: string): string | false
+	/** SvelteKit-like navigation that runs `loader` before updating the URL. */
+	goto(url: string, opts?: { replace?: boolean }): Promise<void>
 	/** Shallow push — updates URL/state without triggering handlers. */
-	push_state(_url?: string | URL, _state?: any): void
+	push_state(url?: string | URL, state?: any): void
 	/** Shallow replace — updates URL/state without triggering handlers. */
-	replace_state(_url?: string | URL, _state?: any): void
-	/** Manually preload loaders for a URL (deduped). */
-	preload(_url: string): Promise<unknown | void>
+	replace_state(url?: string | URL, state?: any): void
+	/** Manually preload `loader` 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>
+	match(url: string): Promise<MatchResult<T> | null>
 	/** Attach history + click listeners and immediately process current location. */
 	init(): Promise<void>
 	/** Remove listeners installed by `init()`. */

package/index.js

@@ -97,12 +97,12 @@ export default class Navgo {
 
 		const st = ev?.state?.__navgo
 		ℹ('[🧭 event:popstate]', st)
-		// Hash-only or state-only change: pathname+search unchanged -> skip loaders
+		// Hash-only or state-only change: pathname+search unchanged -> skip loader
 		const cur = this.#current.url
 		const target = new URL(location.href)
 		if (cur && target.pathname === cur.pathname) {
 			this.#current.url = target
-			ℹ('  - [🧭 event:popstate]', 'same path+search; skip loaders')
+			ℹ('  - [🧭 event:popstate]', 'same path+search; skip loader')
 			this.#apply_scroll(ev)
 			this.route.set(this.#current)
 			return
@@ -110,7 +110,7 @@ export default class Navgo {
 		// Explicit shallow entries (pushState/replaceState) regardless of path
 		if (st?.shallow) {
 			this.#current.url = target
-			ℹ('  - [🧭 event:popstate]', 'shallow entry; skip loaders')
+			ℹ('  - [🧭 event:popstate]', 'shallow entry; skip loader')
 			this.#apply_scroll(ev)
 			this.route.set(this.#current)
 			return
@@ -254,8 +254,8 @@ export default class Navgo {
 		return true
 	}
 
-	async #run_loaders(route, params) {
-		const ret_val = route[1].loaders?.(params)
+	async #run_loader(route, params) {
+		const ret_val = route[1].loader?.(params)
 		return Array.isArray(ret_val) ? Promise.all(ret_val) : ret_val
 	}
 
@@ -348,18 +348,18 @@ export default class Navgo {
 		if (nav_id !== this.#nav_active) return
 
 		//
-		// loaders
+		// loader
 		//
 		let data
 		if (hit) {
 			const pre = this.#preloads.get(path)
 			data =
 				pre?.data ??
-				(await (pre?.promise || this.#run_loaders(hit.route, hit.params)).catch(e => ({
+				(await (pre?.promise || this.#run_loader(hit.route, hit.params)).catch(e => ({
 					__error: e,
 				})))
 			this.#preloads.delete(path)
-			ℹ('[🧭 loaders]', pre ? 'using preloaded data' : 'loaded', {
+			ℹ('[🧭 loader]', pre ? 'using preloaded data' : 'loaded', {
 				path,
 				preloaded: !!pre,
 				has_error: !!data?.__error,
@@ -409,6 +409,8 @@ export default class Navgo {
 			},
 			event: ev_param,
 		})
+		this.route.set(this.#current)
+
 		// await so that apply_scroll is after potential async work
 		await this.#opts.after_navigate?.(nav)
 
@@ -424,12 +426,11 @@ export default class Navgo {
 		await this.#opts.tick?.()
 
 		this.#apply_scroll(nav)
-		this.route.set(this.#current)
-		if (nav_id === this.#nav_active) this.is_navigating.set(false)
+		this.is_navigating.set(false)
 	}
 
 	/**
-	 * Shallow push — updates the URL/state but DOES NOT call handlers or loaders.
+	 * Shallow push — updates the URL/state but DOES NOT call handlers or loader.
 	 */
 	#commit_shallow(url, state, replace) {
 		const u = new URL(url || location.href, location.href)
@@ -476,7 +477,7 @@ export default class Navgo {
 	}
 
 	/**
-	 * Preload loaders for a URL (e.g. to prime cache).
+	 * Preload loader data for a URL (e.g. to prime cache).
 	 * Dedupes concurrent preloads for the same path.
 	 */
 	/** @param {string} url_raw @returns {Promise<unknown|void>} */
@@ -504,7 +505,7 @@ export default class Navgo {
 		}
 
 		const entry = {}
-		entry.promise = this.#run_loaders(hit.route, hit.params).then(data => {
+		entry.promise = this.#run_loader(hit.route, hit.params).then(data => {
 			entry.data = data
 			delete entry.promise
 			ℹ('[🧭 preload]', 'done', { path })
@@ -634,6 +635,7 @@ export default class Navgo {
 		removeEventListener('hashchange', this.#on_hashchange)
 		removeEventListener('scroll', this.#scroll_handler, { capture: true })
 		this.#areas_pos.clear()
+		delete window.navgo
 	}
 
 	#clear_onward_history() {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "navgo",
-	"version": "3.0.8",
+	"version": "4.0.2",
 	"repository": {
 		"type": "git",
 		"url": "git+https://github.com/mustafa0x/navgo.git"

package/readme.md

@@ -24,7 +24,7 @@ const routes = [
         /* 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()),
+      loader: params => fetch('/api/admin').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?')) {
@@ -39,7 +39,7 @@ const routes = [
 const router = new Navgo(routes, {
   base: '/',
   before_navigate(nav) {
-    // app-level hook before loaders/URL update; may cancel
+    // app-level hook before loader/URL update; may cancel
     console.log('before_navigate', nav.type, '→', nav.to?.url.pathname)
   },
   after_navigate(nav) {
@@ -97,7 +97,7 @@ Notes:
 - `base`: `string` (default `'/'`)
   - 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 loader/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.
 - `tick`: `() => void | Promise<void>`
@@ -139,7 +139,7 @@ const {route, is_navigating} = router
 
 - 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.
-- loaders?(params): `unknown | Promise | Array<unknown|Promise>`
+- 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`.
 - validate?(params): `boolean | Promise<boolean>`
   - Predicate called during matching. If it returns or resolves to `false`, the route is skipped.
@@ -178,7 +178,7 @@ const routes = [
       param_validators: {
         /* ... */
       },
-      loaders: params => fetch('/api/admin/stats').then(r => r.json()),
+      loader: params => fetch('/api/admin/stats').then(r => r.json()),
       before_route_leave(nav) {
         if (nav.type === 'link' || nav.type === 'nav') {
           if (!confirm('Enter admin area?')) nav.cancel()
@@ -218,7 +218,7 @@ The path to format.
 
 Returns: `Promise<void>`
 
-Runs any matching route `loaders` before updating the URL and then updates history. Route processing triggers `after_navigate`. Use `replace: true` to replace the current history entry.
+Runs any matching route `loader` before updating the URL and then updates history. Route processing triggers `after_navigate`. Use `replace: true` to replace the current history entry.
 
 #### uri
 
@@ -284,8 +284,8 @@ Or with a custom id:
 
 Returns: `Promise<unknown | void>`
 
-Preload a route's `loaders` data for a given `uri` without navigating. Concurrent calls for the same path are deduped.
-Note: Resolves to `undefined` when the matched route has no `loaders`.
+Preload a route's `loader` data for a given `uri` without navigating. Concurrent calls for the same path are deduped.
+Note: Resolves to `undefined` when the matched route has no `loader`.
 
 ### push_state(url?, state?)
 
@@ -335,7 +335,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 loaders(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)
@@ -344,7 +344,7 @@ For `link` and `goto` navigations that match a route:
 ```
 
 - 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`, loaders run before completion so content matches the target entry; this improves scroll restoration. Errors are delivered via `after_navigate` with `nav.to.data = { __error }`.
+- 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 }`.
 
 ### Shallow Routing
 
@@ -384,10 +384,10 @@ scroll flow
 
 - `format(uri)` -- normalizes a path relative to `base`. Returns `false` when `uri` is outside of `base`.
 - `match(uri)` -- returns a Promise of `{ route, params } | null` using string/RegExp patterns and validators. Awaits an async `validate(params)` if provided.
-- `goto(uri, { replace? })` -- fires route-level `before_route_leave('goto')`, calls global `before_navigate`, saves scroll, runs loaders, pushes/replaces, and completes via `after_navigate`.
+- `goto(uri, { replace? })` -- fires route-level `before_route_leave('goto')`, calls global `before_navigate`, saves scroll, runs loader, pushes/replaces, and completes via `after_navigate`.
 - `init()` -- wires global listeners (`popstate`, `pushstate`, `replacestate`, click) and optional hover/tap preloading; immediately processes the current location.
 - `destroy()` -- removes listeners added by `init()`.
-- `preload(uri)` -- pre-executes a route's `loaders` for a path and caches the result; concurrent calls are deduped.
+- `preload(uri)` -- pre-executes a route's `loader` for a path and caches the result; concurrent calls are deduped.
 - `push_state(url?, state?)` -- shallow push that updates the URL and `history.state` without route processing.
 - `replace_state(url?, state?)` -- shallow replace that updates the URL and `history.state` without route processing.