@orkestrel/router 0.0.1 → 0.0.2

package/dist/src/core/Dispatcher.d.ts

@@ -1,51 +0,0 @@
-import type { DispatchGroupInterface, DispatcherEventMap, DispatcherInterface, DispatcherOptions, DispatchResult, Method, RouteInput, RouteRecord, RouterInterface } from './types.js';
-import type { EmitterInterface } from '@orkestrel/emitter';
-/**
- * The fetch-standard, method-dimensioned dispatch entity — layers HTTP method
- * dispatch and web-standard `Request`/`Response` handling over one internal
- * `Router<RouteRecord<TState>>`. The core machine the eventual server face
- * (§7) and any fetch-native runtime consumes directly.
- *
- * @typeParam TState - The consumer's opaque per-request state type
- *
- * @remarks
- * - **Dedup by `method + canonicalizePath`.** The underlying `Router` is
- *   constructed with a `key` function so registering the same method+path
- *   twice REPLACES the prior route in place (§5.1).
- * - **Registration boundary guard (§14).** `add` validates each input's
- *   `handler` (`isFunction`) and `method` (must be in {@link METHODS}) —
- *   throws `TypeError` on a malformed registration; path validation is
- *   delegated to the underlying `Router`'s own guard. `match`/`handle` stay
- *   guard-free.
- * - **Auto-`HEAD` / auto-`OPTIONS`.** A `HEAD` request with no registered
- *   `HEAD` route runs the matching `GET` handler and strips the response
- *   body; an `OPTIONS` request with no registered `OPTIONS` route answers
- *   `204` with a derived `Allow` header.
- * - **Handler throws propagate.** `handle` never invents an error boundary —
- *   a handler throw reaches the caller uncaught (§5.1).
- * - **Emitter (§13).** Owns a `#emitter` for {@link DispatcherEventMap};
- *   `match`/`miss` fire AFTER resolution, before the handler/responder runs.
- *
- * @example
- * ```ts
- * const dispatcher = new Dispatcher<{ readonly userId: string }>()
- * dispatcher.add({
- * 	method: 'GET',
- * 	path: '/users/:id',
- * 	handler: (request, context) => Response.json({ id: context.params.id }),
- * })
- * const response = await dispatcher.handle(new Request('http://x/users/7'), { userId: 'me' })
- * ```
- */
-export declare class Dispatcher<TState = undefined> implements DispatcherInterface<TState> {
-    #private;
-    readonly router: RouterInterface<RouteRecord<TState>>;
-    constructor(options?: DispatcherOptions<TState>);
-    get emitter(): EmitterInterface<DispatcherEventMap>;
-    add<Path extends string>(input: RouteInput<Path, TState>): void;
-    add(inputs: readonly RouteInput<string, TState>[]): void;
-    group(prefix: string): DispatchGroupInterface<TState>;
-    match(method: Method, pathname: string): DispatchResult<TState>;
-    handle(request: Request, state: TState): Promise<Response>;
-    destroy(): void;
-}

package/dist/src/core/Group.d.ts

@@ -1,30 +0,0 @@
-import type { GroupInterface, RouteEntry, RouterInterface } from './types.js';
-/**
- * A prefix-scoped registration handle over a {@link import('./Router.js').Router} —
- * pure string composition (AGENTS §4.2.2), no independent state or storage.
- *
- * @typeParam Meta - The entry payload type, matching the owning router
- *
- * @remarks
- * Every `add` composes `entry.path` as `joinPaths(prefix, entry.path)` and
- * forwards to the OWNING router, so grouped routes land in the SAME registry.
- * `group(prefix)` nests, composing prefixes via {@link joinPaths}.
- *
- * @example
- * ```ts
- * import { Router } from '@src/core'
- *
- * const router = new Router<{ readonly page: string }>()
- * const api = router.group('/api')
- * api.add({ path: '/users', meta: { page: 'list' } })
- * router.match('/api/users')?.path // '/api/users'
- * ```
- */
-export declare class Group<Meta> implements GroupInterface<Meta> {
-    #private;
-    readonly prefix: string;
-    constructor(parent: RouterInterface<Meta>, prefix: string);
-    add(entry: RouteEntry<Meta>): void;
-    add(entries: readonly RouteEntry<Meta>[]): void;
-    group(prefix: string): GroupInterface<Meta>;
-}

package/dist/src/core/Router.d.ts

@@ -1,42 +0,0 @@
-import type { AnswerHandler, GroupInterface, RouteEntry, RouterInterface, RouterMatch, RouterOptions } from './types.js';
-/**
- * The path-matching + registry engine — registers `{ path, meta, name? }`
- * entries (compiling each path once) and resolves a concrete pathname to the
- * MOST SPECIFIC matching entry. The shared machine both the `Navigator`
- * (browser) and the `Dispatcher` (core, method-dimensioned) compose.
- *
- * @typeParam Meta - The opaque payload each entry carries and a match returns
- *
- * @remarks
- * - **Registration boundary guard (§14).** `add` validates each entry's
- *   `path` — `isString` plus a leading `/` — and throws `TypeError` on a
- *   malformed registration; `match` stays guard-free (the hot path).
- * - **Compile-once.** Each path is compiled exactly once at registration into
- *   a parallel `#compiled` array, so `match` runs only a cached `exec` per
- *   candidate.
- * - **Dedup via `key`.** When `options.key` is set, an entry whose computed
- *   key already exists REPLACES the prior one IN PLACE (both the `#entries`
- *   and `#compiled` arrays, at the existing index) — last write wins, no
- *   engine rebuild. Omitted ⇒ every entry is kept, even duplicate paths.
- * - **Groups.** `group(prefix)` returns a {@link GroupInterface} that composes
- *   `prefix` onto every entry it registers, nesting via {@link joinPaths}.
- *
- * @example
- * ```ts
- * const router = new Router<{ readonly page: string }>()
- * router.add({ path: '/users/:id', meta: { page: 'profile' } })
- * router.match('/users/7') // { path: '/users/:id', params: { id: '7' }, meta: { page: 'profile' } }
- * ```
- */
-export declare class Router<Meta> implements RouterInterface<Meta> {
-    #private;
-    constructor(options?: RouterOptions<Meta>);
-    get count(): number;
-    add(entry: RouteEntry<Meta>): void;
-    add(entries: readonly RouteEntry<Meta>[]): void;
-    match(pathname: string, answers?: AnswerHandler<Meta>): RouterMatch<Meta> | undefined;
-    entries(): readonly RouteEntry<Meta>[];
-    entries(pathname: string): readonly RouteEntry<Meta>[];
-    group(prefix: string): GroupInterface<Meta>;
-    clear(): void;
-}

package/dist/src/core/constants.d.ts

@@ -1,60 +0,0 @@
-/**
- * The complete set of HTTP methods a {@link import('./types.js').Dispatcher}
- * registers routes under — backs the registration guard (`add` rejects any
- * `method` outside this set) and the auto-`OPTIONS` `Allow` derivation.
- *
- * @remarks
- * A `ReadonlySet` of the seven {@link import('./types.js').Method} literals:
- * `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `HEAD`, `OPTIONS`. `HEAD` is
- * included even though it is never required at registration (a `GET` route
- * auto-answers `HEAD`) — it is still a valid method to register explicitly.
- *
- * @example
- * ```ts
- * METHODS.has('GET') // true
- * METHODS.has('TRACE') // false
- * ```
- */
-export declare const METHODS: ReadonlySet<string>;
-/**
- * Specificity tier for a **literal** path segment (`/users`) — the highest
- * tier, always outranking a param or wildcard segment at the same position.
- *
- * @remarks
- * Consumed by `computeSpecificity` (U1 `helpers.ts`) when ranking candidate
- * matches left-to-right at the earliest differing segment (§4 precedence).
- *
- * @example
- * ```ts
- * TIER_LITERAL > TIER_PARAM // true
- * ```
- */
-export declare const TIER_LITERAL = 2;
-/**
- * Specificity tier for a **param** path segment (`:name`) — ranks below a
- * literal segment and above a wildcard segment at the same position.
- *
- * @remarks
- * Consumed by `computeSpecificity` (U1 `helpers.ts`) alongside {@link TIER_LITERAL}
- * and {@link TIER_WILDCARD}.
- *
- * @example
- * ```ts
- * TIER_PARAM > TIER_WILDCARD // true
- * ```
- */
-export declare const TIER_PARAM = 1;
-/**
- * Specificity tier for a **wildcard** path segment (`*name`) — the lowest
- * tier; a wildcard only ever wins against another wildcard shape (an
- * equal-specificity tie resolved by registration order).
- *
- * @remarks
- * Consumed by `computeSpecificity` (U1 `helpers.ts`).
- *
- * @example
- * ```ts
- * TIER_WILDCARD // 0
- * ```
- */
-export declare const TIER_WILDCARD = 0;

package/dist/src/core/factories.d.ts

@@ -1,53 +0,0 @@
-import type { DispatcherInterface, DispatcherOptions, RouterInterface, RouterOptions } from './types.js';
-/**
- * Create a {@link RouterInterface} — the pure path-matching + registry engine
- * shared by the browser `Navigator` and the core `Dispatcher`.
- *
- * @remarks
- * Prefer this over `new Router(...)` at call sites that only need the
- * interface; an entity that OWNS a `Router` internally (like `Dispatcher`)
- * still constructs `new Router(...)` directly.
- *
- * @typeParam Meta - The opaque payload each entry carries and a match returns
- * @param options - Optional initial `entries`, the `sensitive` case toggle
- *   (default `true`), and a `key` dedup identity function
- * @returns A {@link RouterInterface}
- *
- * @example
- * ```ts
- * import { createRouter } from '@src/core'
- *
- * const router = createRouter<{ readonly page: string }>()
- * router.add({ path: '/users/:id', meta: { page: 'profile' } })
- * router.match('/users/7') // { path: '/users/:id', params: { id: '7' }, meta: { page: 'profile' } }
- * ```
- */
-export declare function createRouter<Meta>(options?: RouterOptions<Meta>): RouterInterface<Meta>;
-/**
- * Create a {@link DispatcherInterface} — the fetch-standard, method-
- * dimensioned dispatch entity over one internal `Router<RouteRecord<TState>>`.
- *
- * @remarks
- * Prefer this over `new Dispatcher(...)` at call sites that only need the
- * interface.
- *
- * @typeParam TState - The consumer's opaque per-request state type (default
- *   `undefined` for stateless use)
- * @param options - Optional initial `routes`, the `sensitive` case toggle,
- *   the `unmatched`/`unmethoded` default-responder overrides, and the AGENTS
- *   §13 emitter `on`/`error` wiring
- * @returns A {@link DispatcherInterface}
- *
- * @example
- * ```ts
- * import { createDispatcher } from '@src/core'
- *
- * const dispatcher = createDispatcher<{ readonly userId: string }>({
- * 	routes: [
- * 		{ method: 'GET', path: '/health', handler: () => new Response('ok') },
- * 	],
- * })
- * const response = await dispatcher.handle(new Request('http://x/health'), { userId: 'me' })
- * ```
- */
-export declare function createDispatcher<TState = undefined>(options?: DispatcherOptions<TState>): DispatcherInterface<TState>;

package/dist/src/core/helpers.d.ts

@@ -1,274 +0,0 @@
-import type { CompiledPath, Method } from './types.js';
-/**
- * Escape every regex metacharacter in a literal string so it can be embedded
- * inside a larger `RegExp` source without being interpreted as syntax.
- *
- * @remarks
- * {@link compilePath} escapes the literal segments of a route pattern with this
- * before splicing in `:name` / `*name` capture groups, so a path like
- * `/files/:name.json` matches the `.` literally rather than as "any character".
- * Pure and total — never throws.
- *
- * @param value - The literal string to escape
- * @returns `value` with every regex metacharacter backslash-escaped
- *
- * @example
- * ```ts
- * escapeRegExp('a.b+c') // 'a\\.b\\+c'
- * new RegExp(`^${escapeRegExp('a.b')}$`).test('a.b') // true
- * new RegExp(`^${escapeRegExp('a.b')}$`).test('axb') // false
- * ```
- */
-export declare function escapeRegExp(value: string): string;
-/**
- * Canonicalize a route path for REGISTRY IDENTITY — strip a single trailing
- * slash, except the root `/` (and the empty pattern). The trailing-slash fold
- * {@link compilePath} normalizes a pattern through, so identity agrees with the
- * matcher.
- *
- * @remarks
- * Mirrors {@link compilePath}'s trailing-slash folding: `/users/` canonicalizes
- * to `/users` (the two compile to the same regex and match the same
- * pathnames), while the root `/` and the empty `''` are EXEMPT (a bare `/`
- * already matches `/`; stripping it would break that). Pure and total — a path
- * without a trailing slash returns unchanged.
- *
- * @param path - The route path pattern
- * @returns The canonical path (one trailing slash removed, except `/` and `''`)
- *
- * @example
- * ```ts
- * canonicalizePath('/users/') // '/users'
- * canonicalizePath('/users') // '/users'
- * canonicalizePath('/') // '/'
- * canonicalizePath('') // ''
- * ```
- */
-export declare function canonicalizePath(path: string): string;
-/**
- * Compile a route path pattern into an anchored regex and its ordered param
- * names.
- *
- * @remarks
- * Splits the CANONICALIZED path into segments. Each `:name` segment becomes a
- * `([^/]+)` capture group; the FINAL segment may instead be `*name`, which
- * becomes a `(.+)` capture spanning the REST of the path including slashes — a
- * wildcard segment anywhere but last is a registration-time programmer error
- * and throws `TypeError` (§14 construction/registration boundary). Every regex
- * metacharacter in a literal segment is escaped first ({@link escapeRegExp}),
- * so a path like `/files/:name.json` matches the `.` literally apart from the
- * param. The regex is anchored (`^…$`), so it matches the whole pathname, not
- * a prefix.
- *
- * **Trailing slash is INSENSITIVE** (Express's `strict: false` default): a
- * single trailing slash on the request path is OPTIONAL, so `/users` matches
- * both `/users` and `/users/`, and `/users/:id` matches both `/users/me` and
- * `/users/me/`. This is NOT prefix matching — a deeper path is still a
- * distinct segment, so `/api` does not match `/api/users`. The ROOT `/` (and
- * the empty pattern `''`) are EXEMPT — they are not stripped, so `/` stays
- * `^/$` and `''` stays `^$`.
- *
- * `sensitive` (default `true`) controls case folding: `false` adds the `i`
- * regex flag, so `/Users` matches `/users`. The pattern's own casing is never
- * altered — only the matching behavior.
- *
- * @param path - The route path pattern (e.g. `/users/:id`, `/files/*rest`)
- * @param sensitive - Case-sensitive matching (default `true`)
- * @returns The {@link CompiledPath} — its `regex` + ordered `params`
- * @throws {TypeError} When a `*name` wildcard segment is not the FINAL segment
- *
- * @example
- * ```ts
- * const { regex, params } = compilePath('/users/:id/posts/:slug')
- * params // ['id', 'slug']
- * regex.exec('/users/7/posts/hello') // ['…', '7', 'hello']
- * regex.test('/users/7/posts/hello/') // true — the trailing slash is optional
- *
- * compilePath('/files/*rest').regex.test('/files/a/b.png') // true
- * compilePath('/Users', false).regex.test('/users') // true — case-insensitive
- * ```
- */
-export declare function compilePath(path: string, sensitive?: boolean): CompiledPath;
-/**
- * URL-decode one captured param value, tolerating a malformed percent-escape —
- * the decode {@link matchPath} applies to each captured group.
- *
- * @remarks
- * A bad `%` sequence is not a reason to reject an otherwise-matching route, so
- * a `decodeURIComponent` that would throw falls back to the raw value
- * (mirroring the cookie / token boundary readers, AGENTS §14). Total — never
- * throws.
- *
- * @param value - The raw captured param value
- * @returns The URL-decoded value, or the raw value when decoding would throw
- *
- * @example
- * ```ts
- * decodeParam('a%2Fb') // 'a/b'
- * decodeParam('100%25') // '100%'
- * decodeParam('%') // '%' — malformed escape stays literal
- * ```
- */
-export declare function decodeParam(value: string): string;
-/**
- * Extract the URL-decoded params a compiled path captures from a concrete
- * pathname, or `undefined` when the pathname does not match.
- *
- * @remarks
- * Runs the {@link CompiledPath} `regex` against `pathname` (a single `exec`); a
- * miss returns `undefined`. On a hit it walks `params` POSITIONALLY — the
- * `n`-th param name pairs with the `n`-th capture group — and URL-decodes each
- * value with {@link decodeParam}. Returns a frozen `name → value` record (empty
- * for a parameterless path). Total — never throws.
- *
- * @param compiled - The {@link CompiledPath} from {@link compilePath}
- * @param pathname - The concrete request pathname to match (e.g. `/users/7`)
- * @returns The decoded params on a hit, or `undefined` on a miss
- *
- * @example
- * ```ts
- * const compiled = compilePath('/users/:id')
- * matchPath(compiled, '/users/7') // { id: '7' }
- * matchPath(compiled, '/users/a%2Fb') // { id: 'a/b' } — decoded
- * matchPath(compiled, '/posts/7') // undefined
- * ```
- */
-export declare function matchPath(compiled: CompiledPath, pathname: string): Readonly<Record<string, string>> | undefined;
-/**
- * Classify one path segment into its specificity TIER — the SAME syntax
- * {@link compilePath} rewrites: a syntactically valid `:name` head is a PARAM
- * segment, a final `*name` is a WILDCARD segment, everything else (including a
- * literal segment that merely CONTAINS a `:` mid-string, e.g. `a:b`) is a
- * LITERAL segment.
- *
- * @remarks
- * This is the fix over the old engine's bug: the old classifier ranked any
- * segment `includes(':')` as a param, so a literal segment like `a:b` was
- * mis-tiered even though {@link compilePath} compiles it literally. Sharing one
- * segment parser between compilation and classification keeps the two in
- * agreement (§4 fixes). Pure and total.
- *
- * @param segment - One `/`-split path segment
- * @param isFinal - Whether `segment` is the last segment of its path (only the
- *   final segment may be classified as a wildcard)
- * @returns The segment's specificity tier — {@link import('./constants.js').TIER_LITERAL},
- *   {@link import('./constants.js').TIER_PARAM}, or
- *   {@link import('./constants.js').TIER_WILDCARD}
- *
- * @example
- * ```ts
- * classifySegment(':id', true) // 1 — TIER_PARAM
- * classifySegment('*rest', true) // 0 — TIER_WILDCARD
- * classifySegment('a:b', true) // 2 — TIER_LITERAL — the old bug's regression case
- * classifySegment('users', false) // 2 — TIER_LITERAL
- * ```
- */
-export declare function classifySegment(segment: string, isFinal: boolean): number;
-/**
- * Compute a route path's SPECIFICITY VECTOR — the per-segment type ranking
- * that breaks a tie when several registered routes match the same concrete
- * pathname.
- *
- * @remarks
- * Splits the CANONICALIZED path into segments (on `/`) and maps each to its
- * specificity tier via {@link classifySegment} — the same segment parser
- * {@link compilePath} uses, so a literal segment that merely contains a `:`
- * (e.g. `a:b`) is correctly tiered as literal rather than param (the old
- * engine's bug, fixed here). The standard route-precedence rule compares two
- * matching routes' vectors LEFT-TO-RIGHT: at the first index where the tiers
- * differ, the HIGHER tier (a literal over a param over a wildcard) is MORE
- * SPECIFIC and wins — so `/users/me` (`[2, 2]`) beats `/users/:id` (`[2, 1]`)
- * beats `/users/*rest` (`[2, 0]`) regardless of registration order. Two routes
- * that match the SAME concrete pathname necessarily have the same segment
- * count in the common case; {@link compareSpecificity} handles the general
- * case for totality.
- *
- * @param path - The route path pattern (e.g. `/users/:id`)
- * @returns The per-segment specificity tiers, in order
- *
- * @example
- * ```ts
- * computeSpecificity('/users/me') // [2, 2]
- * computeSpecificity('/users/:id') // [2, 1]
- * computeSpecificity('/files/*rest') // [2, 0]
- * computeSpecificity('/a:b') // [2] — literal, not param — the classification fix
- * ```
- */
-export declare function computeSpecificity(path: string): readonly number[];
-/**
- * Compare two route paths by SPECIFICITY — the comparator that picks the
- * most-specific matching route (literal-over-param-over-wildcard,
- * registration-order-independent).
- *
- * @remarks
- * Compares the two paths' {@link computeSpecificity} vectors LEFT-TO-RIGHT and
- * returns a standard `Array.sort` ordering: a NEGATIVE number when `a` is MORE
- * specific than `b` (so a descending-specificity sort puts `a` first),
- * positive when `b` is more specific, `0` when neither out-ranks the other
- * across the compared segments. At the first index where the tiers differ,
- * the higher tier wins; if one vector is a prefix of the other (different
- * segment counts), the LONGER, more-segmented path is treated as more
- * specific (a missing segment ranks below any real one).
- *
- * @param a - The first route path
- * @param b - The second route path
- * @returns A negative number when `a` is more specific, positive when `b` is, else `0`
- *
- * @example
- * ```ts
- * compareSpecificity('/users/me', '/users/:id') // negative — literal wins
- * compareSpecificity('/users/:id', '/users/*rest') // negative — param beats wildcard
- * compareSpecificity('/users/:id', '/users/:id') // 0 — equal specificity
- * ```
- */
-export declare function compareSpecificity(a: string, b: string): number;
-/**
- * Narrow a raw `request.method` string into a typed {@link Method} — total,
- * never throws.
- *
- * @remarks
- * Guarded via {@link import('./constants.js').METHODS} (the seven registrable
- * HTTP methods); any other value (an unknown verb, non-uppercase casing)
- * resolves to `undefined` rather than throwing (§14 guard totality). Pure
- * leaf shared by the `Dispatcher`'s `handle` (§5.1 unknown-verb honesty) and
- * anywhere else a raw method string needs narrowing.
- *
- * @param value - The raw `request.method` string to narrow
- * @returns The matching {@link Method}, or `undefined` when `value` is not one
- *   of the seven registrable methods
- *
- * @example
- * ```ts
- * parseMethod('GET') // 'GET'
- * parseMethod('PURGE') // undefined
- * parseMethod('get') // undefined — case-sensitive
- * ```
- */
-export declare function parseMethod(value: string): Method | undefined;
-/**
- * Join a group prefix and a route path into one `/`-prefixed path, normalizing
- * duplicate or missing joining slashes.
- *
- * @remarks
- * {@link import('./types.js').GroupInterface} / {@link import('./types.js').DispatchGroupInterface}
- * compose a prefix with each registered entry's path this way — pure string
- * composition (§4.2.2), no independent state. Both a duplicated slash
- * (`'/api/'` + `'/users'`) and a missing one (`'/api'` + `'users'`) normalize
- * to a single joining slash. An empty `prefix` returns `path` unchanged (after
- * ensuring a leading slash); an empty `path` returns `prefix` unchanged.
- * Pure and total.
- *
- * @param prefix - The group prefix (e.g. `/api`)
- * @param path - The route path being joined under the prefix (e.g. `/users`)
- * @returns The joined `/`-prefixed path
- *
- * @example
- * ```ts
- * joinPaths('/api', '/users') // '/api/users'
- * joinPaths('/api/', '/users') // '/api/users'
- * joinPaths('/api', 'users') // '/api/users'
- * joinPaths('', '/users') // '/users'
- * joinPaths('/api', '') // '/api'
- * ```
- */
-export declare function joinPaths(prefix: string, path: string): string;