@nifrajs/core 0.1.0-alpha.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nifra Authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,35 @@
+# @nifrajs/core
+
+The Bun-native, contract-first HTTP framework at the heart of [nifra](../../README.md):
+a radix router, a fully type-inferred server, versionable contracts, lifecycle
+middleware, and production hardening.
+
+```sh
+bun add @nifrajs/core
+```
+
+```ts
+import { server } from "@nifrajs/core"
+
+const app = server()
+  .get("/users/:id", (c) => ({ id: c.params.id }))
+  .post("/users", { body: nameSchema }, (c) => ({ created: c.body.name }))
+  .listen(3000)
+
+export type App = typeof app // hand this to @nifrajs/client for end-to-end types
+```
+
+- **Inline or contract-first.** Write routes inline (types inferred from the
+  builder), or `defineContract(...)` + `implement(...)` for a decoupled, versionable
+  surface — handlers lift over unchanged.
+- **Validation at the boundary.** Per-route `body`/`query` is any
+  [Standard Schema](https://standardschema.dev) (zod/valibot/arktype, or `@nifrajs/schema`'s
+  `t`); invalid input is rejected with a structured `400` before the handler runs.
+- **Lifecycle middleware.** `derive`/`decorate` extend the typed context;
+  `onRequest`/`beforeHandle`/`afterHandle`/`onResponse`/`onError` run around handlers;
+  `use(middleware)` applies a bundle.
+- **Hardening built in.** `stop({ drainMs })` graceful shutdown (+ opt-in SIGTERM/
+  SIGINT), `requestTimeoutMs` (+ `ctx.signal`), a streaming body-size cap, and a
+  redacting structured `Logger`.
+
+ESM-only; requires Bun at runtime. MIT.

package/dist/errors.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Base class for every error the framework throws. Carries a stable, string
+ * `code` so callers can branch on the failure programmatically rather than
+ * matching on message text. Messages are prefixed with the brand name.
+ */
+export declare class FrameworkError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+/** Stable codes for boot-time (L2) route configuration failures. */
+export type RouteConfigErrorCode = "DUPLICATE_ROUTE" | "DUPLICATE_PARAM" | "PARAM_NAME_CONFLICT" | "INVALID_PATH" | "INVALID_PARAM_NAME" | "WILDCARD_NOT_LAST" | "INVALID_METHOD";
+/**
+ * Thrown at route registration when a route is misconfigured. This is the
+ * boot-time rejection layer: loud and early,
+ * never deferred to the first request.
+ */
+export declare class RouteConfigError extends FrameworkError {
+    readonly code: RouteConfigErrorCode;
+    constructor(code: RouteConfigErrorCode, message: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,qBAAa,cAAe,SAAQ,KAAK;IACvC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;gBAET,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAK1C;AAED,oEAAoE;AACpE,MAAM,MAAM,oBAAoB,GAC5B,iBAAiB,GACjB,iBAAiB,GACjB,qBAAqB,GACrB,cAAc,GACd,oBAAoB,GACpB,mBAAmB,GACnB,gBAAgB,CAAA;AAEpB;;;;GAIG;AACH,qBAAa,gBAAiB,SAAQ,cAAc;IAElD,SAAiB,IAAI,EAAE,oBAAoB,CAAA;gBAE/B,IAAI,EAAE,oBAAoB,EAAE,OAAO,EAAE,MAAM;CAIxD"}

package/dist/errors.js

@@ -0,0 +1,26 @@
+import { FRAMEWORK_NAME } from "./internal/brand.js";
+/**
+ * Base class for every error the framework throws. Carries a stable, string
+ * `code` so callers can branch on the failure programmatically rather than
+ * matching on message text. Messages are prefixed with the brand name.
+ */
+export class FrameworkError extends Error {
+    code;
+    constructor(code, message) {
+        super(`[${FRAMEWORK_NAME}] ${message}`);
+        this.name = "FrameworkError";
+        this.code = code;
+    }
+}
+/**
+ * Thrown at route registration when a route is misconfigured. This is the
+ * boot-time rejection layer: loud and early,
+ * never deferred to the first request.
+ */
+export class RouteConfigError extends FrameworkError {
+    constructor(code, message) {
+        super(code, message);
+        this.name = "RouteConfigError";
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAA;AAEpD;;;;GAIG;AACH,MAAM,OAAO,cAAe,SAAQ,KAAK;IAC9B,IAAI,CAAQ;IAErB,YAAY,IAAY,EAAE,OAAe;QACvC,KAAK,CAAC,IAAI,cAAc,KAAK,OAAO,EAAE,CAAC,CAAA;QACvC,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAA;QAC5B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAA;IAClB,CAAC;CACF;AAYD;;;;GAIG;AACH,MAAM,OAAO,gBAAiB,SAAQ,cAAc;IAIlD,YAAY,IAA0B,EAAE,OAAe;QACrD,KAAK,CAAC,IAAI,EAAE,OAAO,CAAC,CAAA;QACpB,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAA;IAChC,CAAC;CACF"}

package/dist/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @nifrajs/core — Bun-native, contract-first HTTP framework.
+ *
+ * The router is the perf-critical heart; the server and inline API are built on
+ * the unified route descriptor.
+ */
+/** Current package version. Kept as a literal so type-level tests can pin it. */
+export declare const VERSION: "0.0.0";
+export type Version = typeof VERSION;
+export { FrameworkError, RouteConfigError, type RouteConfigErrorCode } from "./errors.js";
+export { FRAMEWORK_NAME, type FrameworkName } from "./internal/brand.js";
+export { METHODS, type Method, Router, type RouterMatch } from "./router/router.js";
+export type { InferInput, InferOutput, StandardIssue, StandardResult, StandardSchemaV1, StandardTypes, ValidationOutcome, } from "./schema/standard.js";
+export { validateStandard } from "./schema/standard.js";
+export { type RobotsOptions, type RobotsRule, robots, type SitemapChangeFreq, type SitemapEntry, type SitemapOptions, sitemap, } from "./seo.js";
+export type { Context, Params, Platform, Prettify, ResponseControls, RouteSchema, } from "./server/context.js";
+export { type ContextForOp, type ContractShape, defineContract, type HandlersFor, implement, type OperationDef, type RegistryFor, type RegistryFromImpl, type ResponseDef, } from "./server/contract.js";
+export { type CookieOptions, parseCookies, serializeCookie, signValue, unsignValue, } from "./server/cookies.js";
+export { commonSecretPatterns, jsonLogger, type LogFields, type Logger, type RedactOptions, redactLogFields, silentLogger, } from "./server/logger.js";
+export type { Registry, RouteInfo } from "./server/registry.js";
+export { type AnyServer, type DurableObjectNamespaceLike, defineIdentityPlugin, definePlugin, type ExecutionContext, type Handler, type IdentityPlugin, type Middleware, type NifraPlugin, type NodeServeOutcome, type OnRequestResult, type RouteDescriptor, type RunningServer, type ScheduledController, type ScheduledHandler, Server, type ServerOptions, server, toFetchHandler, } from "./server/server.js";
+export { type SSEContext, type SSEInit, type SSEMessage, type SSEStream, sse, } from "./server/sse.js";
+export { type SignatureEncoding, type VerifyWebhookOptions, verifyWebhook, type WebhookFailureReason, type WebhookProvider, type WebhookResult, } from "./server/webhook.js";
+export type { NifraWebSocket, StandardWebSocket, WebSocketContext, WebSocketData, WebSocketHandler, WebSocketUpgradeOutcome, } from "./server/websocket.js";
+export { attachWebSocket, TopicRegistry } from "./server/websocket.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,iFAAiF;AACjF,eAAO,MAAM,OAAO,EAAG,OAAgB,CAAA;AAEvC,MAAM,MAAM,OAAO,GAAG,OAAO,OAAO,CAAA;AAEpC,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,KAAK,oBAAoB,EAAE,MAAM,aAAa,CAAA;AACzF,OAAO,EAAE,cAAc,EAAE,KAAK,aAAa,EAAE,MAAM,qBAAqB,CAAA;AACxE,OAAO,EAAE,OAAO,EAAE,KAAK,MAAM,EAAE,MAAM,EAAE,KAAK,WAAW,EAAE,MAAM,oBAAoB,CAAA;AACnF,YAAY,EACV,UAAU,EACV,WAAW,EACX,aAAa,EACb,cAAc,EACd,gBAAgB,EAChB,aAAa,EACb,iBAAiB,GAClB,MAAM,sBAAsB,CAAA;AAC7B,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAA;AACvD,OAAO,EACL,KAAK,aAAa,EAClB,KAAK,UAAU,EACf,MAAM,EACN,KAAK,iBAAiB,EACtB,KAAK,YAAY,EACjB,KAAK,cAAc,EACnB,OAAO,GACR,MAAM,UAAU,CAAA;AACjB,YAAY,EACV,OAAO,EACP,MAAM,EACN,QAAQ,EACR,QAAQ,EACR,gBAAgB,EAChB,WAAW,GACZ,MAAM,qBAAqB,CAAA;AAC5B,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,aAAa,EAClB,cAAc,EACd,KAAK,WAAW,EAChB,SAAS,EACT,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,KAAK,gBAAgB,EACrB,KAAK,WAAW,GACjB,MAAM,sBAAsB,CAAA;AAC7B,OAAO,EACL,KAAK,aAAa,EAClB,YAAY,EACZ,eAAe,EACf,SAAS,EACT,WAAW,GACZ,MAAM,qBAAqB,CAAA;AAC5B,OAAO,EACL,oBAAoB,EACpB,UAAU,EACV,KAAK,SAAS,EACd,KAAK,MAAM,EACX,KAAK,aAAa,EAClB,eAAe,EACf,YAAY,GACb,MAAM,oBAAoB,CAAA;AAC3B,YAAY,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAA;AAC/D,OAAO,EACL,KAAK,SAAS,EACd,KAAK,0BAA0B,EAC/B,oBAAoB,EACpB,YAAY,EACZ,KAAK,gBAAgB,EACrB,KAAK,OAAO,EACZ,KAAK,cAAc,EACnB,KAAK,UAAU,EACf,KAAK,WAAW,EAChB,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,KAAK,aAAa,EAClB,KAAK,mBAAmB,EACxB,KAAK,gBAAgB,EACrB,MAAM,EACN,KAAK,aAAa,EAClB,MAAM,EACN,cAAc,GACf,MAAM,oBAAoB,CAAA;AAC3B,OAAO,EACL,KAAK,UAAU,EACf,KAAK,OAAO,EACZ,KAAK,UAAU,EACf,KAAK,SAAS,EACd,GAAG,GACJ,MAAM,iBAAiB,CAAA;AACxB,OAAO,EACL,KAAK,iBAAiB,EACtB,KAAK,oBAAoB,EACzB,aAAa,EACb,KAAK,oBAAoB,EACzB,KAAK,eAAe,EACpB,KAAK,aAAa,GACnB,MAAM,qBAAqB,CAAA;AAC5B,YAAY,EACV,cAAc,EACd,iBAAiB,EACjB,gBAAgB,EAChB,aAAa,EACb,gBAAgB,EAChB,uBAAuB,GACxB,MAAM,uBAAuB,CAAA;AAC9B,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAA"}

package/dist/index.js

@@ -0,0 +1,21 @@
+/**
+ * @nifrajs/core — Bun-native, contract-first HTTP framework.
+ *
+ * The router is the perf-critical heart; the server and inline API are built on
+ * the unified route descriptor.
+ */
+/** Current package version. Kept as a literal so type-level tests can pin it. */
+export const VERSION = "0.0.0";
+export { FrameworkError, RouteConfigError } from "./errors.js";
+export { FRAMEWORK_NAME } from "./internal/brand.js";
+export { METHODS, Router } from "./router/router.js";
+export { validateStandard } from "./schema/standard.js";
+export { robots, sitemap, } from "./seo.js";
+export { defineContract, implement, } from "./server/contract.js";
+export { parseCookies, serializeCookie, signValue, unsignValue, } from "./server/cookies.js";
+export { commonSecretPatterns, jsonLogger, redactLogFields, silentLogger, } from "./server/logger.js";
+export { defineIdentityPlugin, definePlugin, Server, server, toFetchHandler, } from "./server/server.js";
+export { sse, } from "./server/sse.js";
+export { verifyWebhook, } from "./server/webhook.js";
+export { attachWebSocket, TopicRegistry } from "./server/websocket.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,iFAAiF;AACjF,MAAM,CAAC,MAAM,OAAO,GAAG,OAAgB,CAAA;AAIvC,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAA6B,MAAM,aAAa,CAAA;AACzF,OAAO,EAAE,cAAc,EAAsB,MAAM,qBAAqB,CAAA;AACxE,OAAO,EAAE,OAAO,EAAe,MAAM,EAAoB,MAAM,oBAAoB,CAAA;AAUnF,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAA;AACvD,OAAO,EAGL,MAAM,EAIN,OAAO,GACR,MAAM,UAAU,CAAA;AASjB,OAAO,EAGL,cAAc,EAEd,SAAS,GAKV,MAAM,sBAAsB,CAAA;AAC7B,OAAO,EAEL,YAAY,EACZ,eAAe,EACf,SAAS,EACT,WAAW,GACZ,MAAM,qBAAqB,CAAA;AAC5B,OAAO,EACL,oBAAoB,EACpB,UAAU,EAIV,eAAe,EACf,YAAY,GACb,MAAM,oBAAoB,CAAA;AAE3B,OAAO,EAGL,oBAAoB,EACpB,YAAY,EAYZ,MAAM,EAEN,MAAM,EACN,cAAc,GACf,MAAM,oBAAoB,CAAA;AAC3B,OAAO,EAKL,GAAG,GACJ,MAAM,iBAAiB,CAAA;AACxB,OAAO,EAGL,aAAa,GAId,MAAM,qBAAqB,CAAA;AAS5B,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAA"}

package/dist/internal/brand.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Single source of truth for the framework's user-facing name.
+ *
+ * Every developer-facing string (error prefixes, the default OpenAPI title, the
+ * logger tag) pulls from here, so renaming the brand is a one-line change. The
+ * npm scope (`@nifrajs/*`) is the other naming axis — `scripts/rename.ts` flips
+ * both at once.
+ */
+export declare const FRAMEWORK_NAME: "Nifra";
+export type FrameworkName = typeof FRAMEWORK_NAME;
+//# sourceMappingURL=brand.d.ts.map

package/dist/internal/brand.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"brand.d.ts","sourceRoot":"","sources":["../../src/internal/brand.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc,EAAG,OAAgB,CAAA;AAE9C,MAAM,MAAM,aAAa,GAAG,OAAO,cAAc,CAAA"}

package/dist/internal/brand.js

@@ -0,0 +1,10 @@
+/**
+ * Single source of truth for the framework's user-facing name.
+ *
+ * Every developer-facing string (error prefixes, the default OpenAPI title, the
+ * logger tag) pulls from here, so renaming the brand is a one-line change. The
+ * npm scope (`@nifrajs/*`) is the other naming axis — `scripts/rename.ts` flips
+ * both at once.
+ */
+export const FRAMEWORK_NAME = "Nifra";
+//# sourceMappingURL=brand.js.map

package/dist/internal/brand.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"brand.js","sourceRoot":"","sources":["../../src/internal/brand.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,OAAgB,CAAA"}

package/dist/internal/secret.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Boot-time guard: reject an HMAC secret under 256 bits, loudly, at construction — never at the
+ * first request. UTF-8 byte length (not char count), so a multibyte secret is measured honestly.
+ * The single source of truth for the framework's secret-strength floor; every HMAC entry point
+ * (signed cookies, `@nifrajs/auth` sessions, webhook verification, signed upload/image URLs) routes
+ * its secret through here so the bar can't drift between them.
+ */
+export declare function requireSecretBytes(secret: string | Uint8Array, label: string): void;
+//# sourceMappingURL=secret.d.ts.map

package/dist/internal/secret.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"secret.d.ts","sourceRoot":"","sources":["../../src/internal/secret.ts"],"names":[],"mappings":"AAQA;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAQnF"}

package/dist/internal/secret.js

@@ -0,0 +1,19 @@
+import { FRAMEWORK_NAME } from "./brand.js";
+/** Minimum HMAC secret strength: 256 bits, matching the SHA-256 block the framework signs with.
+ * A shorter key weakens every signature it backs (cookies, sessions, webhooks, signed URLs). */
+const MIN_SECRET_BYTES = 32;
+const SECRET_ENCODER = new TextEncoder();
+/**
+ * Boot-time guard: reject an HMAC secret under 256 bits, loudly, at construction — never at the
+ * first request. UTF-8 byte length (not char count), so a multibyte secret is measured honestly.
+ * The single source of truth for the framework's secret-strength floor; every HMAC entry point
+ * (signed cookies, `@nifrajs/auth` sessions, webhook verification, signed upload/image URLs) routes
+ * its secret through here so the bar can't drift between them.
+ */
+export function requireSecretBytes(secret, label) {
+    const length = typeof secret === "string" ? SECRET_ENCODER.encode(secret).length : secret.byteLength;
+    if (length < MIN_SECRET_BYTES) {
+        throw new Error(`[${FRAMEWORK_NAME}] ${label} secret must be at least ${MIN_SECRET_BYTES} bytes (256-bit); got ${length}. Generate one with: openssl rand -base64 32`);
+    }
+}
+//# sourceMappingURL=secret.js.map

package/dist/internal/secret.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"secret.js","sourceRoot":"","sources":["../../src/internal/secret.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAE3C;gGACgG;AAChG,MAAM,gBAAgB,GAAG,EAAE,CAAA;AAE3B,MAAM,cAAc,GAAG,IAAI,WAAW,EAAE,CAAA;AAExC;;;;;;GAMG;AACH,MAAM,UAAU,kBAAkB,CAAC,MAA2B,EAAE,KAAa;IAC3E,MAAM,MAAM,GACV,OAAO,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,cAAc,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,UAAU,CAAA;IACvF,IAAI,MAAM,GAAG,gBAAgB,EAAE,CAAC;QAC9B,MAAM,IAAI,KAAK,CACb,IAAI,cAAc,KAAK,KAAK,4BAA4B,gBAAgB,yBAAyB,MAAM,8CAA8C,CACtJ,CAAA;IACH,CAAC;AACH,CAAC"}

package/dist/router/router.d.ts

@@ -0,0 +1,61 @@
+/** HTTP methods the router accepts. */
+export declare const METHODS: readonly ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"];
+export type Method = (typeof METHODS)[number];
+export declare const EMPTY_PARAMS: Record<string, string>;
+/**
+ * Result of {@link Router.find}. The `found: false` cases deliberately separate
+ * a missing path (404) from a path that exists for other methods (405), so the
+ * server layer can answer correctly and populate an `Allow` header.
+ */
+export type RouterMatch<T> = {
+    readonly found: true;
+    readonly payload: T;
+    readonly params: Record<string, string>;
+} | {
+    readonly found: false;
+    readonly reason: "not-found";
+} | {
+    readonly found: false;
+    readonly reason: "method-not-allowed";
+    readonly allowed: string[];
+};
+/**
+ * Radix-style segment trie router. Matching precedence is static > param >
+ * wildcard. Parameter/wildcard values are returned RAW (not percent-decoded);
+ * the server boundary decodes and rejects malformed encodings with a 400,
+ * keeping this layer pure and allocation-light.
+ *
+ * @typeParam T - the payload stored per (method, path); a route descriptor in
+ * practice, but the router is agnostic to it.
+ */
+export declare class Router<T> {
+    private readonly root;
+    /**
+     * Fast path: fully-static paths (no `:param`/`*`) resolve in a single map
+     * lookup keyed by the full path, skipping the trie walk entirely. Values are
+     * the same `Terminal` objects held in the trie, so adding a method later
+     * updates both views at once.
+     */
+    private readonly staticRoutes;
+    /**
+     * Scratch storage for param/wildcard captures during a synchronous trie walk. `find()` copies the
+     * values into the returned params object before clearing this array, so returned matches never share
+     * mutable state. Kept per Router instance, not module-global, to avoid cross-app coupling.
+     */
+    private readonly paramValuesScratch;
+    constructor();
+    /**
+     * Register a payload for `method` + `path`. Throws {@link RouteConfigError}
+     * (boot-time, L2) on a duplicate route, a malformed pattern, or conflicting
+     * parameter names for the same path shape.
+     */
+    add(method: Method, path: string, payload: T): void;
+    /**
+     * Resolve `method` + `path`. Tolerant of a missing leading slash and of
+     * method casing. Never throws.
+     */
+    find(method: string, path: string): RouterMatch<T>;
+    private findDynamic;
+    private maybeCacheDynamicMatch;
+}
+//# sourceMappingURL=router.d.ts.map

package/dist/router/router.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"router.d.ts","sourceRoot":"","sources":["../../src/router/router.ts"],"names":[],"mappings":"AAEA,uCAAuC;AACvC,eAAO,MAAM,OAAO,uEAAwE,CAAA;AAE5F,MAAM,MAAM,MAAM,GAAG,CAAC,OAAO,OAAO,CAAC,CAAC,MAAM,CAAC,CAAA;AA0B7C,eAAO,MAAM,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAqB,CAAA;AAGrE;;;;GAIG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,IACrB;IAAE,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,GACtF;IAAE,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAA;CAAE,GACvD;IAAE,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,oBAAoB,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,CAAA;CAAE,CAAA;AAyKhG;;;;;;;;GAQG;AACH,qBAAa,MAAM,CAAC,CAAC;IACnB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAc;IACnC;;;;;OAKG;IACH,OAAO,CAAC,QAAQ,CAAC,YAAY,CAA0B;IACvD;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAU;;IAQ7C;;;;OAIG;IACH,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,GAAG,IAAI;IA4GnD;;;OAGG;IACH,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC,CAAC,CAAC;IAelD,OAAO,CAAC,WAAW;IA8BnB,OAAO,CAAC,sBAAsB;CAwB/B"}

package/dist/router/router.js

@@ -0,0 +1,324 @@
+import { RouteConfigError } from "../errors.js";
+/** HTTP methods the router accepts. */
+export const METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"];
+const METHOD_SET = new Set(METHODS);
+function isMethod(value) {
+    return METHOD_SET.has(value);
+}
+/** Parameter names must be valid identifiers — mirrors the global identifier rule. */
+const PARAM_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/** Object-prototype keys are rejected as param names: a route like `/:__proto__` could let a captured
+ * value reach a prototype-polluting key. Param *names* come from the route pattern (never from request
+ * input) and are validated here at registration, so a reserved key can never reach `buildParams` —
+ * this boot-time guard is the whole protection. The runtime params object stays a plain `{}` (only
+ * user-controlled *values* land in it, under these validated keys), keeping the param path
+ * allocation-cheap; a null-prototype object would add cost for no added safety. */
+const RESERVED_PARAM_NAMES = new Set(["__proto__", "constructor", "prototype"]);
+/** A param name is valid when it's an identifier AND not a reserved object-prototype key. */
+const validParamName = (name) => PARAM_NAME.test(name) && !RESERVED_PARAM_NAMES.has(name);
+const SLASH = 47;
+const COLON = 58;
+const STAR = 42;
+export const EMPTY_PARAMS = Object.freeze({});
+const DYNAMIC_MATCH_CACHE_MAX = 2048;
+const DYNAMIC_MATCH_CACHES = new WeakMap();
+function dynamicMatchCacheStateFor(owner) {
+    const existing = DYNAMIC_MATCH_CACHES.get(owner);
+    if (existing !== undefined) {
+        return existing;
+    }
+    const state = {
+        cache: undefined,
+        pendingPath: undefined,
+    };
+    DYNAMIC_MATCH_CACHES.set(owner, state);
+    return state;
+}
+function createNode() {
+    return {
+        staticChildren: new Map(),
+        paramChild: undefined,
+        wildcardChild: undefined,
+        terminal: undefined,
+    };
+}
+function sameNames(a, b) {
+    if (a.length !== b.length)
+        return false;
+    for (let i = 0; i < a.length; i++) {
+        if (a[i] !== b[i])
+            return false;
+    }
+    return true;
+}
+/**
+ * Depth-first match with backtracking, walking the path by character offsets
+ * instead of pre-splitting it into an array. `start` is the index of the first
+ * char of the current segment; the segment runs to the next `/` (or end). Tries
+ * static, then param, then wildcard; if a static branch dead-ends, param/wildcard
+ * are still attempted — so `/a/b/c` and `/a/:x/d` coexist and `/a/b/d` resolves
+ * to the param route. Fills `paramValues` along the successful path; abandoned
+ * branches are popped. Avoiding the split keeps `find` allocation-light: only the
+ * segment substrings needed for map lookups (and matched param values) are cut.
+ */
+function matchNode(node, path, start, len, paramValues) {
+    const slash = path.indexOf("/", start);
+    const isLast = slash === -1;
+    const end = isLast ? len : slash;
+    const seg = path.slice(start, end);
+    const staticChild = node.staticChildren.get(seg);
+    if (staticChild !== undefined) {
+        if (isLast) {
+            if (staticChild.terminal !== undefined)
+                return staticChild.terminal;
+        }
+        else {
+            const found = matchNode(staticChild, path, end + 1, len, paramValues);
+            if (found !== undefined)
+                return found;
+        }
+    }
+    const paramChild = node.paramChild;
+    // An empty segment (`/users//posts`) never matches a `:param` — matching would hand the handler
+    // `id: ""` and downstream code a `WHERE id = ''` class of bug. Peers (Hono, Elysia, Next) 404
+    // here too; a static "" child can still match (none is ever registered — INVALID_PATH guards).
+    if (paramChild !== undefined && seg.length > 0) {
+        paramValues.push(seg);
+        if (isLast) {
+            if (paramChild.terminal !== undefined)
+                return paramChild.terminal;
+        }
+        else {
+            const found = matchNode(paramChild, path, end + 1, len, paramValues);
+            if (found !== undefined)
+                return found;
+        }
+        paramValues.pop(); // backtrack: this branch failed deeper down
+    }
+    const wildcard = node.wildcardChild;
+    if (wildcard !== undefined && wildcard.terminal !== undefined) {
+        // Capture the rest of the path verbatim from this segment's start.
+        paramValues.push(path.slice(start));
+        return wildcard.terminal;
+    }
+    return undefined;
+}
+function buildParams(names, values) {
+    if (names.length === 0)
+        return EMPTY_PARAMS;
+    const params = {};
+    for (let i = 0; i < names.length; i++) {
+        // names and values align: one value was pushed per param/wildcard node along
+        // the matched path, in declaration order.
+        params[names[i]] = values[i];
+    }
+    return params;
+}
+function resolve(terminal, method, params) {
+    if (terminal.staticMatches !== undefined && params === EMPTY_PARAMS) {
+        const upper = method.toUpperCase();
+        const cached = terminal.staticMatches.get(upper);
+        if (cached !== undefined)
+            return cached;
+        if (!terminal.handlers.has(upper))
+            return resolveDirect(terminal, method, params);
+        const res = resolveDirect(terminal, method, params);
+        terminal.staticMatches.set(upper, res);
+        return res;
+    }
+    return resolveDirect(terminal, method, params);
+}
+function resolveDirect(terminal, method, params) {
+    if (terminal.handlers.has(method)) {
+        return { found: true, payload: terminal.handlers.get(method), params };
+    }
+    const upper = method.toUpperCase();
+    if (upper === method || !terminal.handlers.has(upper)) {
+        return { found: false, reason: "method-not-allowed", allowed: [...terminal.handlers.keys()] };
+    }
+    const payload = terminal.handlers.get(upper); // present by the has() check above
+    return { found: true, payload, params };
+}
+/**
+ * Radix-style segment trie router. Matching precedence is static > param >
+ * wildcard. Parameter/wildcard values are returned RAW (not percent-decoded);
+ * the server boundary decodes and rejects malformed encodings with a 400,
+ * keeping this layer pure and allocation-light.
+ *
+ * @typeParam T - the payload stored per (method, path); a route descriptor in
+ * practice, but the router is agnostic to it.
+ */
+export class Router {
+    root;
+    /**
+     * Fast path: fully-static paths (no `:param`/`*`) resolve in a single map
+     * lookup keyed by the full path, skipping the trie walk entirely. Values are
+     * the same `Terminal` objects held in the trie, so adding a method later
+     * updates both views at once.
+     */
+    staticRoutes;
+    /**
+     * Scratch storage for param/wildcard captures during a synchronous trie walk. `find()` copies the
+     * values into the returned params object before clearing this array, so returned matches never share
+     * mutable state. Kept per Router instance, not module-global, to avoid cross-app coupling.
+     */
+    paramValuesScratch;
+    constructor() {
+        this.root = createNode();
+        this.staticRoutes = new Map();
+        this.paramValuesScratch = [];
+    }
+    /**
+     * Register a payload for `method` + `path`. Throws {@link RouteConfigError}
+     * (boot-time, L2) on a duplicate route, a malformed pattern, or conflicting
+     * parameter names for the same path shape.
+     */
+    add(method, path, payload) {
+        DYNAMIC_MATCH_CACHES.delete(this);
+        const upper = method.toUpperCase();
+        // The `Method` parameter type is the compile-time guard; this re-checks at
+        // runtime for JS callers and dynamically-computed methods.
+        if (!isMethod(upper)) {
+            throw new RouteConfigError("INVALID_METHOD", `unsupported HTTP method "${method}"`);
+        }
+        if (path.length === 0 || path.charCodeAt(0) !== SLASH) {
+            throw new RouteConfigError("INVALID_PATH", `path must start with "/": "${path}"`);
+        }
+        const segments = path === "/" ? [] : path.slice(1).split("/");
+        const paramNames = [];
+        let isStatic = true;
+        let node = this.root;
+        for (let i = 0; i < segments.length; i++) {
+            const seg = segments[i];
+            const marker = seg.charCodeAt(0);
+            if (marker === COLON) {
+                isStatic = false;
+                const name = seg.slice(1);
+                if (!validParamName(name)) {
+                    throw new RouteConfigError("INVALID_PARAM_NAME", `invalid parameter ":${name}" in "${path}"`);
+                }
+                if (paramNames.includes(name)) {
+                    throw new RouteConfigError("DUPLICATE_PARAM", `duplicate parameter ":${name}" in "${path}"`);
+                }
+                paramNames.push(name);
+                node.paramChild ??= createNode();
+                node = node.paramChild;
+            }
+            else if (marker === STAR) {
+                isStatic = false;
+                if (i !== segments.length - 1) {
+                    throw new RouteConfigError("WILDCARD_NOT_LAST", `wildcard must be the final segment in "${path}"`);
+                }
+                const name = seg.length === 1 ? "*" : seg.slice(1);
+                if (name !== "*" && !validParamName(name)) {
+                    throw new RouteConfigError("INVALID_PARAM_NAME", `invalid wildcard "*${name}" in "${path}"`);
+                }
+                if (paramNames.includes(name)) {
+                    throw new RouteConfigError("DUPLICATE_PARAM", `duplicate parameter "${name}" in "${path}"`);
+                }
+                paramNames.push(name);
+                node.wildcardChild ??= createNode();
+                node = node.wildcardChild;
+            }
+            else {
+                let child = node.staticChildren.get(seg);
+                if (child === undefined) {
+                    child = createNode();
+                    node.staticChildren.set(seg, child);
+                }
+                node = child;
+            }
+        }
+        const existing = node.terminal;
+        let terminal;
+        if (existing !== undefined) {
+            if (!sameNames(existing.paramNames, paramNames)) {
+                throw new RouteConfigError("PARAM_NAME_CONFLICT", `conflicting parameter names for "${path}": [${existing.paramNames.join(", ")}] vs [${paramNames.join(", ")}]`);
+            }
+            if (existing.handlers.has(upper)) {
+                throw new RouteConfigError("DUPLICATE_ROUTE", `duplicate route: ${upper} ${path}`);
+            }
+            existing.handlers.set(upper, payload);
+            existing.staticMatches?.clear();
+            terminal = existing;
+        }
+        else {
+            terminal = isStatic
+                ? {
+                    handlers: new Map([[upper, payload]]),
+                    paramNames,
+                    staticMatches: new Map(),
+                }
+                : {
+                    handlers: new Map([[upper, payload]]),
+                    paramNames,
+                };
+            node.terminal = terminal;
+        }
+        // Mirror fully-static routes into the fast-path map (same Terminal object).
+        if (isStatic) {
+            this.staticRoutes.set(path, terminal);
+        }
+    }
+    /**
+     * Resolve `method` + `path`. Tolerant of a missing leading slash and of
+     * method casing. Never throws.
+     */
+    find(method, path) {
+        const len = path.length;
+        const leading = len > 0 && path.charCodeAt(0) === SLASH;
+        // Fast path: a fully-static path resolves in one map lookup, no trie walk.
+        if (leading) {
+            const staticTerminal = this.staticRoutes.get(path);
+            if (staticTerminal !== undefined) {
+                return resolve(staticTerminal, method, EMPTY_PARAMS);
+            }
+        }
+        return this.findDynamic(method, path, leading, len);
+    }
+    findDynamic(method, path, leading, len) {
+        if (leading) {
+            const cached = DYNAMIC_MATCH_CACHES.get(this)?.cache?.get(path);
+            if (cached !== undefined) {
+                return resolve(cached.terminal, method, buildParams(cached.terminal.paramNames, cached.values));
+            }
+        }
+        const paramValues = this.paramValuesScratch;
+        paramValues.length = 0;
+        try {
+            const terminal = matchNode(this.root, path, leading ? 1 : 0, len, paramValues);
+            if (terminal === undefined) {
+                return { found: false, reason: "not-found" };
+            }
+            if (leading && terminal.paramNames.length > 0) {
+                this.maybeCacheDynamicMatch(path, terminal, paramValues);
+            }
+            return resolve(terminal, method, buildParams(terminal.paramNames, paramValues));
+        }
+        finally {
+            paramValues.length = 0;
+        }
+    }
+    maybeCacheDynamicMatch(path, terminal, values) {
+        const state = dynamicMatchCacheStateFor(this);
+        if (state.pendingPath !== path) {
+            state.pendingPath = path;
+            return;
+        }
+        let cache = state.cache;
+        if (cache === undefined) {
+            cache = new Map();
+            state.cache = cache;
+        }
+        if (cache.size >= DYNAMIC_MATCH_CACHE_MAX) {
+            const oldest = cache.keys().next().value;
+            if (oldest !== undefined)
+                cache.delete(oldest);
+        }
+        cache.set(path, {
+            terminal,
+            values: values.slice(0, terminal.paramNames.length),
+        });
+    }
+}
+//# sourceMappingURL=router.js.map