@orkestrel/router 0.0.1

package/dist/src/browser/index.js

@@ -0,0 +1,643 @@
+import { canonicalizePath, createRouter, joinPaths } from "../core/index.cjs";
+//#region src/browser/helpers.ts
+/**
+* Extract the `/`-prefixed pathname from a `location.hash` value — strip the
+* leading `#` (keeping the route's own leading `/`) and any `?query` suffix.
+*
+* @remarks
+* The grammar this package matches everywhere is `/`-prefixed (§4 path
+* grammar), so a hash-mode location's `'#/users/7?x'` becomes `'/users/7'`
+* — a hash pattern is expected to start `'#/'`; anything else (an empty hash,
+* or one that does not begin `'#/'`) yields `''` (the `Navigator` then falls
+* back). Total — never throws.
+*
+* @param hash - The raw `window.location.hash` value (e.g. `'#/users/7?x'`)
+* @returns The `/`-prefixed pathname to match, or `''` for an empty / non-`#/` hash
+*
+* @example
+* ```ts
+* extractHashPath('#/users/7?x') // '/users/7'
+* extractHashPath('#/tokens') // '/tokens'
+* extractHashPath('') // '' — the Navigator falls back
+* extractHashPath('#other') // '' — not a `#/` route hash
+* ```
+*/
+function extractHashPath(hash) {
+	if (!hash.startsWith("#/")) return "";
+	const withoutHash = hash.slice(1);
+	const queryIndex = withoutHash.indexOf("?");
+	return queryIndex === -1 ? withoutHash : withoutHash.slice(0, queryIndex);
+}
+/**
+* Resolve the `/`-prefixed pathname to match for the CURRENT location, in
+* either navigation mode — the one seam `extractHashPath` (hash mode) and
+* history-mode base-stripping share.
+*
+* @remarks
+* Hash mode (`history: false`) reads `location.hash` through
+* {@link extractHashPath}. History mode (`history: true`) reads
+* `location.pathname` and strips a leading `base` prefix when one is
+* configured: `base` itself maps to the root `'/'`; a pathname that is not
+* under `base` is returned unchanged (a base mismatch is not this helper's
+* concern — the `Navigator`'s match then simply misses). Total — never throws.
+*
+* @param location - The `hash` + `pathname` pair to resolve from (accepts a
+*   real `Location` or any object shaped the same, for pure unit testing)
+* @param history - The navigation substrate: `false` for hash mode, `true`
+*   for history mode
+* @param base - The history-mode path prefix to strip (ignored in hash mode;
+*   omit for no prefix)
+* @returns The `/`-prefixed pathname to match
+*
+* @example
+* ```ts
+* resolveLocationPath({ hash: '#/users/7', pathname: '/' }, false) // '/users/7'
+* resolveLocationPath({ hash: '', pathname: '/app/users/7' }, true, '/app') // '/users/7'
+* resolveLocationPath({ hash: '', pathname: '/app' }, true, '/app') // '/'
+* resolveLocationPath({ hash: '', pathname: '/other/users' }, true, '/app') // '/other/users'
+* ```
+*/
+function resolveLocationPath(location, history, base) {
+	if (!history) return extractHashPath(location.hash);
+	const pathname = location.pathname;
+	if (base === void 0 || base === "") return pathname;
+	const normalizedBase = base.endsWith("/") ? base.slice(0, -1) : base;
+	if (pathname === normalizedBase) return "/";
+	if (pathname.startsWith(`${normalizedBase}/`)) return pathname.slice(normalizedBase.length);
+	return pathname;
+}
+/**
+* Find the nearest enclosing `<a>` element a DOM event originated from, by
+* walking its composed path — the pure lookup behind history-mode link
+* interception.
+*
+* @remarks
+* Uses `event.composedPath()` (not `event.target`) so a click on a styled
+* child INSIDE an anchor (an icon, a span) still resolves to the anchor.
+* Total — never throws; returns `undefined` when no anchor is found on the
+* path.
+*
+* @param event - The DOM event to search (typically a `click`)
+* @returns The nearest enclosing `HTMLAnchorElement`, or `undefined`
+*
+* @example
+* ```ts
+* document.addEventListener('click', (event) => {
+* 	const anchor = findAnchor(event)
+* 	if (anchor !== undefined) console.log(anchor.href)
+* })
+* ```
+*/
+function findAnchor(event) {
+	for (const node of event.composedPath()) if (node instanceof HTMLAnchorElement) return node;
+}
+//#endregion
+//#region node_modules/@orkestrel/abort/dist/src/core/index.js
+/**
+* Link an own `AbortSignal` to an optional parent signal.
+*
+* @remarks
+* When `parent` is `undefined`, the own signal is returned unchanged. When a
+* parent is given, the result is `AbortSignal.any([own, parent])`, which fires
+* on EITHER the own signal aborting or the parent aborting — without
+* re-implementing listener wiring. A parent that has ALREADY aborted makes the
+* combined signal born aborted (carrying the parent's reason).
+*
+* @param own - The instance's own signal.
+* @param parent - An optional parent signal to link against.
+* @returns `own` unchanged when `parent` is `undefined`, otherwise
+*   `AbortSignal.any([own, parent])`.
+*
+* @example
+* ```ts
+* import { linkSignal } from '@src/core'
+*
+* const controller = new AbortController()
+* const linked = linkSignal(controller.signal, undefined) // controller.signal
+* ```
+*/
+function linkSignal(own, parent) {
+	return parent === void 0 ? own : AbortSignal.any([own, parent]);
+}
+Object.freeze([
+	"null",
+	"boolean",
+	"object",
+	"array",
+	"number",
+	"integer",
+	"string"
+]);
+/** Determine whether a value is a string. */
+function isString$1(value) {
+	return typeof value === "string";
+}
+/**
+* A cancellation handle — a thin, traceable wrapper over a native
+* `AbortController` whose exposed `signal` can be linked to a parent signal.
+*
+* @remarks
+* - **Own controller.** The instance owns a private `AbortController`; `abort`
+*   aborts it, and `aborted` reads the exposed signal. `abort(reason)` keeps any
+*   DEFINED reason verbatim (including a falsy `null` / `0` / `''` / `false`);
+*   `abort()` / `abort(undefined)` defaults `signal.reason` to an `AbortError`
+*   `DOMException`. Aborting is idempotent — the first reason sticks.
+* - **Parent linking.** When `options.signal` is given, the exposed `signal` is
+*   `AbortSignal.any([own, parent])`, so it fires on EITHER the own `abort()` or
+*   the parent aborting — without re-implementing listener wiring. A parent that
+*   has ALREADY aborted makes the handle born aborted (carrying the parent's reason).
+* - **Traceable.** Each handle carries an `id` (caller-supplied or a random UUID)
+*   for correlating cancellations across the system.
+* - **Event-free.** A pure functional primitive — no Emitter, no events.
+*
+* @example
+* ```ts
+* const abort = new Abort()
+* abort.signal.addEventListener('abort', () => stop(), { once: true })
+* abort.abort('cancelled') // flips `aborted`, fires `signal` with the reason
+* ```
+*/
+var Abort = class {
+	#controller = new AbortController();
+	id;
+	signal;
+	constructor(options) {
+		this.id = isString$1(options?.id) ? options.id : crypto.randomUUID();
+		this.signal = linkSignal(this.#controller.signal, options?.signal);
+	}
+	get aborted() {
+		return this.signal.aborted;
+	}
+	abort(reason) {
+		this.#controller.abort(reason);
+	}
+};
+/**
+* Create a cancellation handle — a thin, traceable wrapper over a native
+* `AbortController` whose `signal` can be linked to a parent signal.
+*
+* @remarks
+* The created handle's `signal` fires when its own `abort()` is called; when
+* `options.signal` is given, it ALSO fires when that parent signal aborts (linked
+* via `AbortSignal.any`). Pass `options.id` to label the handle for tracing, or
+* let it default to a random UUID.
+*
+* @param options - Optional `id` (a trace label; defaults to a random UUID) and
+*   `signal` (a parent signal whose abort also fires the created handle's signal)
+* @returns A working {@link AbortInterface}
+*
+* @example
+* ```ts
+* import { createAbort } from '@src/core'
+*
+* const abort = createAbort()
+* const work = fetch(url, { signal: abort.signal })
+* abort.abort() // cancels the fetch via the linked native signal
+* ```
+*
+* @example
+* ```ts
+* // Link to a parent so a parent cancellation also aborts the child.
+* const parent = createAbort()
+* const child = createAbort({ signal: parent.signal })
+* parent.abort() // child.aborted is now true
+* ```
+*/
+function createAbort(options) {
+	return new Abort(options);
+}
+//#endregion
+//#region node_modules/@orkestrel/emitter/dist/src/core/index.js
+/**
+* Extract the own enumerable keys of a mapped object, typed as its key union.
+*
+* @remarks
+* `Object.keys` widens its result to `string[]`, which breaks the key↔value
+* correlation a mapped type (like `EmitterHooks<TMap>`) otherwise guarantees.
+* A `for…in` push into a `keyof`-typed array narrows the result back,
+* type-safely and with no assertion.
+*
+* @typeParam T - The object shape whose keys are extracted.
+* @param object - The object to read keys from.
+* @returns The object's own enumerable keys, typed as `(keyof T)[]`.
+*
+* @example
+* ```ts
+* import { extractKeys } from '@src/core'
+*
+* const hooks = { tick: () => {}, done: () => {} }
+* extractKeys(hooks) // ['tick', 'done']
+* extractKeys({}) // []
+* ```
+*/
+function extractKeys(object) {
+	const collected = [];
+	for (const key in object) collected.push(key);
+	return collected;
+}
+Object.freeze([
+	"null",
+	"boolean",
+	"object",
+	"array",
+	"number",
+	"integer",
+	"string"
+]);
+/** Determine whether a value is callable. */
+function isFunction$1(value) {
+	return typeof value === "function";
+}
+/**
+* A typed synchronous event emitter — the foundational observable primitive of
+* the codebase (AGENTS §13). Stateful entities OWN one as a `#emitter` field and
+* expose it through `readonly emitter`; they never inherit from it.
+*
+* @typeParam TMap - The event map: each event name to the argument tuple its
+*   listeners receive.
+*
+* @remarks
+* - **Synchronous.** `emit` invokes listeners in registration order, in the
+*   current tick.
+* - **Listener isolation.** A throwing listener never stops its siblings: every
+*   listener runs, and a throw is routed to the `error` handler
+*   ({@link EmitterOptions.error}) — never rethrown. Every throwing listener
+*   surfaces (not just the first), and with no `error` handler a throw is swallowed
+*   silently. The `error` handler runs inside its own try/catch, so a throwing
+*   error-handler is swallowed too (anti-recursion — it cannot escape or re-enter).
+* - **Per-event storage.** Listeners live in a per-event `Set`, so every public
+*   method is precisely typed with no assertions.
+* - **Destroyed → no-op.** After `destroy()`, `on` / `once` / `emit` do nothing
+*   and `destroyed` is `true`.
+*
+* @example
+* ```ts
+* type CounterEventMap = {
+* 	tick: readonly [count: number]
+* 	done: readonly []
+* }
+*
+* const emitter = new Emitter<CounterEventMap>({
+* 	on: { done: () => stop() },
+* 	error: (error, event) => log(`listener for ${event} threw`, error),
+* })
+* emitter.on('tick', (count) => render(count))
+* emitter.emit('tick', 1)
+* ```
+*/
+var Emitter = class {
+	#destroyed = false;
+	#listeners = {};
+	#wrappers = {};
+	#error;
+	constructor(options) {
+		const error = options?.error;
+		this.#error = isFunction$1(error) ? error : void 0;
+		const hooks = options?.on;
+		if (hooks !== void 0) this.#wire(hooks);
+	}
+	get destroyed() {
+		return this.#destroyed;
+	}
+	on(event, handler) {
+		if (this.#destroyed) return;
+		(this.#listeners[event] ??= /* @__PURE__ */ new Set()).add(handler);
+	}
+	once(event, handler) {
+		if (this.#destroyed) return;
+		const pending = this.#wrappers[event] ??= /* @__PURE__ */ new Map();
+		const wrapper = (...args) => {
+			this.#listeners[event]?.delete(wrapper);
+			const wrappers = pending.get(handler);
+			wrappers?.delete(wrapper);
+			if (wrappers !== void 0 && wrappers.size === 0) pending.delete(handler);
+			handler(...args);
+		};
+		const wrappers = pending.get(handler) ?? /* @__PURE__ */ new Set();
+		wrappers.add(wrapper);
+		pending.set(handler, wrappers);
+		this.on(event, wrapper);
+	}
+	off(event, handler) {
+		const listeners = this.#listeners[event];
+		const wrappers = this.#wrappers[event];
+		const pending = wrappers?.get(handler);
+		if (pending !== void 0) {
+			for (const wrapper of pending) listeners?.delete(wrapper);
+			wrappers?.delete(handler);
+		}
+		listeners?.delete(handler);
+	}
+	emit(event, ...args) {
+		if (this.#destroyed) return;
+		const listeners = this.#listeners[event];
+		if (listeners === void 0) return;
+		for (const handler of [...listeners]) try {
+			handler(...args);
+		} catch (error) {
+			this.#surface(error, event);
+		}
+	}
+	count(event) {
+		if (event !== void 0) return this.#listeners[event]?.size ?? 0;
+		let total = 0;
+		for (const set of Object.values(this.#listeners)) total += set?.size ?? 0;
+		return total;
+	}
+	clear(event) {
+		if (event !== void 0) {
+			delete this.#listeners[event];
+			delete this.#wrappers[event];
+			return;
+		}
+		this.#listeners = {};
+		this.#wrappers = {};
+	}
+	destroy() {
+		this.#listeners = {};
+		this.#wrappers = {};
+		this.#error = void 0;
+		this.#destroyed = true;
+	}
+	#surface(error, event) {
+		const handler = this.#error;
+		if (handler === void 0) return;
+		try {
+			handler(error, String(event));
+		} catch {}
+	}
+	#wire(hooks) {
+		for (const event of extractKeys(hooks)) {
+			const handler = hooks[event];
+			if (isFunction$1(handler)) this.on(event, handler);
+		}
+	}
+};
+Object.freeze([
+	"null",
+	"boolean",
+	"object",
+	"array",
+	"number",
+	"integer",
+	"string"
+]);
+/** Determine whether a value is a string. */
+function isString(value) {
+	return typeof value === "string";
+}
+/** Determine whether a value is callable. */
+function isFunction(value) {
+	return typeof value === "function";
+}
+//#endregion
+//#region src/browser/Navigator.ts
+/**
+* The headless History/hash navigation entity — composes one core
+* `Router<RouteEntry<Meta>>`, resolving the current location on `start()` and
+* every subsequent navigation event, tracking `active`, and emitting
+* `navigate` through the core {@link Emitter} (AGENTS §13). No `render` /
+* `outlet` — the consumer owns rendering.
+*
+* @typeParam Meta - The opaque per-route payload a match carries back
+*
+* @remarks
+* - **One shared engine.** Each `route.path` is registered on the SAME
+*   `Router` machine the core `Dispatcher` composes, keyed for dedup by its
+*   {@link canonicalizePath} (last write wins, replace-in-place) — literal-
+*   over-param precedence, trailing-slash insensitivity, and
+*   `:param`/`*wildcard` extraction all come from that one engine (AGENTS
+*   §21).
+* - **Resolve pipeline.** Compute the `/`-prefixed pathname to match
+*   ({@link resolveLocationPath}) → {@link match} it → on a miss, match the
+*   `fallback` through the SAME engine → a fallback that ALSO matches nothing
+*   aborts any pending guarded navigation (a miss SUPERSEDES it, same as a
+*   newer navigation) and leaves `active` `undefined`, emitting nothing
+*   (§21-honest: no phantom match is fabricated) → the optional `guard` may
+*   veto → on a verdict, `active` is set and `navigate` emitted.
+* - **Supersede-safe guard.** Every navigation mints an `@orkestrel/abort`
+*   handle, aborting the PREVIOUS navigation's handle first; a guard verdict
+*   that resolves after its navigation was superseded (`signal.aborted`) is
+*   discarded, same as a `false`/rejected verdict. A guard throw routes to
+*   the `error` handler and vetoes. `stop()`/`destroy()` also abort the
+*   pending handle.
+* - **Hash vs history mode.** Hash mode (`history: false`, the default) binds
+*   `hashchange`; history mode (`history: true`) binds `popstate` and, when
+*   `intercept` is set, same-origin `<a>` click interception (a plain
+*   left-click with no modifier keys, `target`, or `download` attribute).
+*
+* @example
+* ```ts
+* const navigator = new Navigator<{ readonly title: string }>({
+* 	routes: [
+* 		{ path: '/users/:id', meta: { title: 'User' } },
+* 		{ path: '/tokens', meta: { title: 'Tokens' } },
+* 	],
+* })
+* navigator.emitter.on('navigate', (match) => (document.title = match.meta.title))
+* navigator.start() // resolves the current hash now, and on every hashchange
+* navigator.navigate('/tokens')
+* ```
+*/
+var Navigator = class {
+	#router;
+	#emitter;
+	#history;
+	#base;
+	#fallback;
+	#guard;
+	#error;
+	#intercept;
+	#hashListener;
+	#popListener;
+	#clickListener;
+	#active;
+	#started = false;
+	#current;
+	constructor(options) {
+		if (options.guard !== void 0 && !isFunction(options.guard)) throw new TypeError(`a navigator guard must be a function, got ${JSON.stringify(options.guard)}`);
+		if (options.fallback !== void 0 && !isString(options.fallback)) throw new TypeError(`a navigator fallback must be a string, got ${JSON.stringify(options.fallback)}`);
+		if (options.base !== void 0 && !isString(options.base)) throw new TypeError(`a navigator base must be a string, got ${JSON.stringify(options.base)}`);
+		this.#history = options.history ?? false;
+		this.#base = options.base;
+		this.#intercept = options.intercept ?? false;
+		this.#guard = options.guard;
+		this.#error = options.error;
+		this.#emitter = new Emitter({
+			on: options.on,
+			error: options.error
+		});
+		this.#router = createRouter({
+			entries: options.routes.map((route) => ({
+				path: route.path,
+				meta: route,
+				name: route.name
+			})),
+			sensitive: options.sensitive,
+			key: (entry) => canonicalizePath(entry.meta.path)
+		});
+		this.#fallback = options.fallback ?? options.routes[0]?.path;
+		this.#hashListener = () => this.#resolve();
+		this.#popListener = () => this.#resolve();
+		this.#clickListener = (event) => this.#intercepted(event);
+	}
+	get router() {
+		return this.#router;
+	}
+	get emitter() {
+		return this.#emitter;
+	}
+	get active() {
+		return this.#active;
+	}
+	start() {
+		if (this.#started) return;
+		this.#started = true;
+		if (!this.#history) window.addEventListener("hashchange", this.#hashListener);
+		else {
+			window.addEventListener("popstate", this.#popListener);
+			if (this.#intercept) document.addEventListener("click", this.#clickListener);
+		}
+		this.#resolve();
+	}
+	stop() {
+		if (!this.#started) return;
+		this.#started = false;
+		if (!this.#history) window.removeEventListener("hashchange", this.#hashListener);
+		else {
+			window.removeEventListener("popstate", this.#popListener);
+			if (this.#intercept) document.removeEventListener("click", this.#clickListener);
+		}
+		this.#current?.abort();
+	}
+	navigate(path) {
+		if (!this.#history) {
+			const next = `#${path}`;
+			if (window.location.hash === next) this.#resolve();
+			else window.location.hash = next;
+			return;
+		}
+		const target = this.#base === void 0 ? path : joinPaths(this.#base, path);
+		window.history.pushState(null, "", target);
+		this.#resolve();
+	}
+	match(path) {
+		const hit = this.#router.match(path);
+		if (hit === void 0) return void 0;
+		return {
+			path: hit.path,
+			params: hit.params,
+			meta: hit.meta.meta,
+			name: hit.meta.name
+		};
+	}
+	destroy() {
+		this.stop();
+		this.#emitter.destroy();
+	}
+	#resolve() {
+		const pathname = resolveLocationPath({
+			hash: window.location.hash,
+			pathname: window.location.pathname
+		}, this.#history, this.#base);
+		const to = this.match(pathname) ?? this.#matchFallback();
+		if (to === void 0) {
+			this.#current?.abort();
+			this.#active = void 0;
+			return;
+		}
+		this.#navigate(to);
+	}
+	#matchFallback() {
+		if (this.#fallback === void 0) return void 0;
+		return this.match(this.#fallback);
+	}
+	#navigate(to) {
+		this.#current?.abort();
+		const handle = createAbort();
+		this.#current = handle;
+		const guard = this.#guard;
+		if (guard === void 0) {
+			this.#commit(to);
+			return;
+		}
+		this.#guarded(guard, to, this.#active, handle);
+	}
+	#commit(to) {
+		this.#active = to;
+		this.#emitter.emit("navigate", to);
+	}
+	async #guarded(guard, to, from, handle) {
+		let verdict;
+		try {
+			verdict = await guard(to, from, handle.signal);
+		} catch (error) {
+			this.#surface(error);
+			return;
+		}
+		if (handle.signal.aborted || !verdict) return;
+		this.#commit(to);
+	}
+	#surface(error) {
+		const handler = this.#error;
+		if (handler === void 0) return;
+		try {
+			handler(error, "navigate");
+		} catch {}
+	}
+	#intercepted(event) {
+		if (event.defaultPrevented || event.button !== 0) return;
+		if (event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return;
+		const anchor = findAnchor(event);
+		if (anchor === void 0) return;
+		if (anchor.target !== "" && anchor.target !== "_self") return;
+		if (anchor.hasAttribute("download")) return;
+		const url = new URL(anchor.href, window.location.href);
+		if (url.origin !== window.location.origin) return;
+		event.preventDefault();
+		this.navigate(resolveLocationPath({
+			hash: url.hash,
+			pathname: url.pathname
+		}, true, this.#base));
+	}
+};
+//#endregion
+//#region src/browser/factories.ts
+/**
+* Create a {@link NavigatorInterface} — the headless History/hash navigation
+* entity composing one core `Router<RouteEntry<Meta>>`.
+*
+* @remarks
+* Prefer this over `new Navigator(...)` at call sites that only need the
+* interface.
+*
+* @typeParam Meta - The opaque per-route payload a match carries back
+* @param options - The `routes` to register, the `history` toggle (default
+*   `false`, hash mode), an optional `base` (history mode), an optional
+*   `fallback` path, an optional `guard` hook, opt-in link `intercept`
+*   (history mode), the `sensitive` case toggle, and the AGENTS §13 emitter
+*   `on`/`error` wiring
+* @returns A live {@link NavigatorInterface} handle — call `start()` to begin
+*   dispatching
+*
+* @example
+* ```ts
+* import { createNavigator } from '@src/browser'
+*
+* const navigator = createNavigator({
+* 	routes: [
+* 		{ path: '/users/:id', meta: { title: 'User' } },
+* 		{ path: '/tokens', meta: { title: 'Tokens' } },
+* 	],
+* 	on: { navigate: (match) => (document.title = match.meta.title) },
+* })
+* navigator.start()
+* ```
+*/
+function createNavigator(options) {
+	return new Navigator(options);
+}
+//#endregion
+export { Navigator, createNavigator, extractHashPath, findAnchor, resolveLocationPath };
+
+//# sourceMappingURL=index.js.map