@lesto/router 0.1.0

package/src/index.ts

@@ -0,0 +1,49 @@
+/**
+ * @lesto/router — the route-matching substrate for Lesto's code-first `lesto()` app.
+ *
+ *   const table = new RouteTable<Handler>();
+ *   table.add("GET", "/posts/:id", handler);
+ *   table.match("GET", "/posts/3");   // { value: handler, params: { id: "3" } }
+ *
+ * Captured params are URL-decoded at match time, so `/posts/a%2Fb` binds the one
+ * param `"a/b"` (a `%2F` never smuggles a path separator) and a malformed `%`
+ * refuses with a coded `RouterError` the web tier maps to a 400 (see `RouteTable`).
+ * `pathFor` is the inverse — it encodes params back into a path that round-trips.
+ *
+ * The pattern compiler (`compile`) and type-level param inference (`ParamKeys` /
+ * `PathParams`) give `lesto()` handlers their `c.param(...)` keys with no codegen.
+ */
+
+// The generic matcher the `lesto()` builder dispatches over, plus the shared
+// pattern compiler and the type-level param inference that gives handlers their
+// `c.param(...)` keys with no codegen.
+export { pathFor, RouteTable } from "./table";
+export type { Match } from "./table";
+export { compile, escapeRegExp, PARAM_SEGMENT } from "./compile";
+export type { CompiledPattern } from "./compile";
+export type { CatchAllParamKeys, ParamKeys, PathParams, SingleParamKeys } from "./params";
+
+// The file-based routing convention: scan a conventional dir (`app/`) into ordered
+// route descriptors that compile to the same `:param` patterns above, so a
+// file-route and a hand-written route share one router (the applier lives in
+// `@lesto/web`'s `applyFileRoutes`, over these descriptors).
+export {
+  BOUNDARY_KINDS,
+  compileFileRoutes,
+  dirKey,
+  NEAREST_BOUNDARY_KINDS,
+  ROUTE_FILE_NAMES,
+} from "./file-routes";
+export type {
+  BoundaryDepths,
+  BoundaryKind,
+  DiscoveredFile,
+  FileRoute,
+  FileRouteKind,
+  NearestBoundaryKind,
+} from "./file-routes";
+export { scanRoutes } from "./scan";
+export type { DirEntry, DirReader } from "./scan";
+
+export { LestoError, RouterError } from "./errors";
+export type { RouterErrorCode } from "./errors";

package/src/params.ts

@@ -0,0 +1,98 @@
+/**
+ * Path params, inferred from the pattern at the type level.
+ *
+ * A route's `:param` segments are not just runtime captures — the compiler can
+ * read them straight off the pattern string. `ParamKeys<"/listings/:id">` is the
+ * literal union `"id"`; `PathParams<…>` lifts that union into the record a
+ * handler receives. This is the spine of Lesto's end-to-end typing: a handler for
+ * `"/posts/:postId/comments/:id"` knows, with no annotation and no codegen, that
+ * `c.param("postId")` and `c.param("id")` are the only valid keys.
+ *
+ * Purely type-level — these emit no JavaScript. The runtime captures still flow
+ * through {@link RouteTable}; these types only describe their shape.
+ */
+
+/**
+ * The name a `:param` captures, stopping at a literal that follows it in the same
+ * segment.
+ *
+ * The runtime compiler captures a name as `[A-Za-z_][A-Za-z0-9_]*` (see
+ * `PARAM_SEGMENT`), so a pattern like `/files/:name.json` binds the param `name`
+ * and matches `.json` literally. A naive split-on-`/` would infer `name.json` and
+ * steer `c.param(...)` to a key that does not exist at runtime. This peels the
+ * trailing literal at the `.`/`-` separators a path segment uses, so the type
+ * agrees with the captured key.
+ */
+type ParamName<Raw extends string> = Raw extends `${infer Name}.${string}`
+  ? ParamName<Name>
+  : Raw extends `${infer Name}-${string}`
+    ? ParamName<Name>
+    : Raw;
+
+/**
+ * The union of single-segment `:param` names in a path pattern.
+ *
+ * Walks the literal: a `:name/` prefix yields `name` and recurses on the rest; a
+ * trailing `:name` yields the final name; anything without a `:` yields `never`
+ * (a static path has no single params). A name stops at the next `/` — or at a
+ * `.`/`-` literal within the segment — mirroring the identifier the runtime
+ * captures. Catch-alls (`*name`) are read separately by {@link CatchAllParamKeys},
+ * since they carry a different VALUE type.
+ */
+export type SingleParamKeys<Path extends string> =
+  Path extends `${string}:${infer Param}/${infer Rest}`
+    ? ParamName<Param> | SingleParamKeys<`/${Rest}`>
+    : Path extends `${string}:${infer Param}`
+      ? ParamName<Param>
+      : never;
+
+/**
+ * The catch-all name in a path pattern — the `name` of a `*name` / `*name?`, or
+ * `never` when there is none. A catch-all is always the FINAL token (the matcher
+ * refuses any other position), so it is read straight off the tail: the optional
+ * `*name?` form is matched first so the trailing `?` is a literal, not part of the
+ * captured name. Its value is a `string[]` (the run of segments it captured),
+ * which is why it is tracked apart from the single `:param` names.
+ *
+ * @example
+ * type A = CatchAllParamKeys<"/docs/*rest">;        // "rest"
+ * type B = CatchAllParamKeys<"/docs/*rest?">;       // "rest"
+ * type C = CatchAllParamKeys<"/listings/:id">;      // never
+ */
+export type CatchAllParamKeys<Path extends string> = Path extends `${string}*${infer Name}?`
+  ? Name
+  : Path extends `${string}*${infer Name}`
+    ? Name
+    : never;
+
+/**
+ * The union of param names in a path pattern — single `:param` AND `*catchAll`
+ * names alike. The spine of `c.param(...)` key-checking; {@link PathParams} adds
+ * the per-name value type on top.
+ *
+ * @example
+ * type A = ParamKeys<"/listings/:id">;             // "id"
+ * type B = ParamKeys<"/posts/:postId/c/:id">;      // "postId" | "id"
+ * type C = ParamKeys<"/files/:name.json">;         // "name"
+ * type D = ParamKeys<"/docs/*rest">;               // "rest"
+ * type E = ParamKeys<"/about">;                     // never
+ */
+export type ParamKeys<Path extends string> = SingleParamKeys<Path> | CatchAllParamKeys<Path>;
+
+/**
+ * The record of path params for a pattern: each single `:param` mapped to `string`,
+ * each `*catchAll` mapped to `string[]`.
+ *
+ * Every single-segment capture is a `string` at runtime (the router never
+ * coerces); a catch-all capture is split on `/` into the `string[]` run of
+ * segments it matched (`[]` for an optional catch-all that matched none). A static
+ * path produces `{}` — no keys, nothing to read.
+ *
+ * @example
+ * type P = PathParams<"/listings/:id">;            // { id: string }
+ * type Q = PathParams<"/docs/*rest">;              // { rest: string[] }
+ * type R = PathParams<"/u/:id/*rest">;             // { id: string; rest: string[] }
+ */
+export type PathParams<Path extends string> = {
+  [Key in ParamKeys<Path>]: Key extends CatchAllParamKeys<Path> ? string[] : string;
+};

package/src/scan.ts

@@ -0,0 +1,143 @@
+/**
+ * Walk a convention directory into the flat {@link DiscoveredFile} list the
+ * compiler takes — over an INJECTED reader, so the walk itself is pure logic.
+ *
+ * The reader is the one impure seam: `readDir(path)` lists a directory's entries
+ * (each a name + whether it is a directory). Everything else — descending the
+ * tree, recognizing `page`/`layout` by name, accumulating segments — is
+ * deterministic over what the reader returns, so the whole scan is exercised under
+ * a fake in-memory reader with no filesystem. The bin wires a real reader
+ * (`fs.readdir(..., { withFileTypes: true })`); a test hands a literal tree.
+ *
+ * Only the convention's recognized files (`page`, `layout`, `middleware`, and the
+ * `loading` / `error` / `not-found` boundaries — any recognized extension) are
+ * surfaced; every other file is ignored, so a co-located component, test, or
+ * stylesheet under the convention dir is never mistaken for a route. The EXTENSION is irrelevant
+ * to the convention — `page.tsx`, `page.ts`, `page.jsx`, `page.js` all name the
+ * directory's page — because the impure loader (the bin) is what resolves a
+ * concrete module path; the scan only needs the base name to classify the kind.
+ */
+
+import type { DiscoveredFile, FileRouteKind } from "./file-routes";
+import { ROUTE_FILE_NAMES } from "./file-routes";
+
+/** One entry the reader yields for a directory: its name and whether it is a subdir. */
+export interface DirEntry {
+  name: string;
+
+  isDirectory: boolean;
+}
+
+/**
+ * List a directory's immediate entries. The single impure seam of the scan — the
+ * bin wires `fs.readdir(path, { withFileTypes: true })`, a test a literal map.
+ * Async because a real filesystem read is.
+ */
+export type DirReader = (path: string) => Promise<ReadonlyArray<DirEntry>>;
+
+/**
+ * The base name of a route file is `<kind>.<ext>` — `page.tsx`, `layout.ts`,
+ * `middleware.ts`, `not-found.tsx`. We split on the FIRST dot so a name like
+ * `page.test.tsx` classifies as `page` only if its base is exactly `page`; a
+ * co-located `page.helper.tsx` has base `page` too, so we additionally require the
+ * name to be a recognized kind (`page`/`layout`/`middleware`/`loading`/`error`/
+ * `not-found`) followed by a SINGLE extension. (A boundary's hyphen is part of its
+ * base — `not-found` is one
+ * base name, not a dot-delimited compound.) This pulls the base name (everything
+ * before the first dot) and the remainder so the classifier can demand a single
+ * extension segment.
+ */
+function baseAndExt(name: string): { base: string; rest: string } {
+  const dot = name.indexOf(".");
+
+  // A dotfile or extension-less name has no kind we recognize; `rest` empty marks it.
+  if (dot <= 0) return { base: name, rest: "" };
+
+  return { base: name.slice(0, dot), rest: name.slice(dot + 1) };
+}
+
+/**
+ * Classify a file name as a route kind, or `undefined` if it is not one.
+ *
+ * A route file is exactly `page.<ext>` or `layout.<ext>` with a SINGLE extension
+ * segment (no inner dot), so `page.tsx` and `layout.js` count while `page.test.tsx`,
+ * `page.module.css`, and a bare `page` do not — a test or a co-located stylesheet
+ * beside a real page is never mistaken for a second route file. The extension's
+ * value does not matter (the loader resolves the concrete path); only that there
+ * is exactly one.
+ */
+function kindOf(name: string): FileRouteKind | undefined {
+  const { base, rest } = baseAndExt(name);
+
+  const kind = ROUTE_FILE_NAMES[base];
+
+  if (kind === undefined) return undefined;
+
+  // Exactly one extension segment: a `rest` with its own dot (`test.tsx`,
+  // `module.css`) is a co-located file, not the route file.
+  if (rest === "" || rest.includes(".")) return undefined;
+
+  return kind;
+}
+
+/**
+ * Scan a convention directory into the flat {@link DiscoveredFile} list the
+ * compiler takes, descending every subdirectory.
+ *
+ * `root` is the convention dir's own path (`app/`); the yielded segments are
+ * relative to it, so the root's own `page`/`layout` arrive with an empty segment
+ * chain and `app/listings/[id]/page.tsx` arrives as `segments: ["listings",
+ * "[id]"]`. The walk is breadth-stable: a directory's own route files are recorded
+ * before its children are descended, but the compiler re-orders for resolution, so
+ * the discovery order here only needs to be COMPLETE, not sorted.
+ *
+ * A `[param]` directory is descended like any other — it is just a segment whose
+ * name happens to compile to `:param` later; the scan stays oblivious to dynamic
+ * vs static, which keeps the one place that distinction matters in the compiler.
+ */
+export async function scanRoutes(
+  readDir: DirReader,
+  root: string,
+): Promise<ReadonlyArray<DiscoveredFile>> {
+  const found: DiscoveredFile[] = [];
+
+  // Descend `dir` (whose path is `path`, whose segments-from-root are `segments`),
+  // recording its route files and recursing into its subdirectories.
+  const walk = async (path: string, segments: ReadonlyArray<string>): Promise<void> => {
+    const entries = await readDir(path);
+
+    // Record this directory's own page/layout files first, then descend — order
+    // within `found` is immaterial (the compiler sorts), so a simple two-pass over
+    // the entries keeps the walk readable.
+    for (const entry of entries) {
+      if (entry.isDirectory) continue;
+
+      const kind = kindOf(entry.name);
+
+      if (kind !== undefined) {
+        found.push({ kind, segments });
+      }
+    }
+
+    // The subdirectories, walked in turn — each adds one raw segment (its name).
+    const subdirs = entries.filter((entry) => entry.isDirectory);
+
+    await Promise.all(
+      subdirs.map((entry) => walk(joinPath(path, entry.name), [...segments, entry.name])),
+    );
+  };
+
+  await walk(root, []);
+
+  return found;
+}
+
+/**
+ * Join a directory path and a child name with a single `/`. The scan never builds
+ * absolute paths — it only re-feeds the result to the reader — so a plain slash
+ * join is enough, and it keeps the (already-pure) walk free of a `node:path`
+ * import that would tie it to one runtime.
+ */
+function joinPath(dir: string, name: string): string {
+  return dir.endsWith("/") ? `${dir}${name}` : `${dir}/${name}`;
+}

package/src/table.ts

@@ -0,0 +1,242 @@
+/**
+ * A generic route table: method + path pattern → a value of the caller's choice.
+ *
+ * Where the legacy {@link Router} hard-codes its value to a `"controller#action"`
+ * string, `RouteTable<T>` is agnostic — the `lesto()` builder stores whatever it
+ * needs to run a route (a handler chain, a page definition) as the value, and the
+ * table only owns matching: compile each pattern once, then resolve a request to
+ * the first route whose verb and path both match, handing back the value and the
+ * captured params.
+ *
+ * Insertion order is resolution order: the first matching route wins, so a more
+ * specific pattern declared earlier shadows a broader one declared later. Pure
+ * over plain strings — no socket, no handler invocation — so every matching edge
+ * is unit-testable in isolation.
+ *
+ * ## Captured params are URL-decoded at match time (BREAKING, Wave 5)
+ *
+ * Matching runs against the *encoded* path, then each capture is
+ * `decodeURIComponent`-d before it reaches the caller. Two consequences a handler
+ * can now rely on:
+ *
+ *   - A percent-encoded separator never smuggles a segment. The pattern's `[^/]+`
+ *     capture matches `%2F` as ONE segment, so `/files/a%2Fb` binds the single
+ *     param `"a/b"` — it does NOT split into two segments or match a two-segment
+ *     pattern. Decoding happens *after* the segment boundary is fixed, so the
+ *     route shape is decided on the wire form and the slash can never be forged
+ *     into the path structure. (`%2e%2e` likewise decodes to the literal `".."`
+ *     value — a string the handler sees, not a path operator the router honors.)
+ *   - Unicode is real text. `/u/%E2%9C%93` binds `"✓"`, not its bytes.
+ *
+ * A param that is not a well-formed percent-encoding (a stray `%`, `%zz`, a
+ * truncated `%E2`) is a client-malformed request, not a server fault: the decode
+ * refuses with a coded {@link RouterError} (`ROUTER_MALFORMED_PARAM`) so the web
+ * tier maps it to a 400 instead of letting `decodeURIComponent`'s bare `URIError`
+ * escape as a 500. The reverse of this — building an encoded path from decoded
+ * params — is {@link pathFor}, which round-trips: `match(pathFor(p, v)).params`
+ * recovers `v`.
+ */
+
+import { compile, PARAM_TOKEN } from "./compile";
+import { RouterError } from "./errors";
+
+/**
+ * Decode one captured segment, turning a malformed percent-sequence into a coded
+ * refusal instead of a bare `URIError`.
+ *
+ * `decodeURIComponent` throws a plain `URIError` on a stray or truncated `%`; left
+ * unhandled that surfaces as an opaque 500 for what is really a bad request. We
+ * catch exactly that case and re-raise a {@link RouterError} the web tier can map
+ * to a 400 by code (`ROUTER_MALFORMED_PARAM`).
+ */
+const decodeParam = (paramName: string, raw: string): string => {
+  try {
+    return decodeURIComponent(raw);
+  } catch {
+    throw new RouterError(
+      "ROUTER_MALFORMED_PARAM",
+      `Route param "${paramName}" is not a valid percent-encoding: "${raw}".`,
+      { param: paramName, raw },
+    );
+  }
+};
+
+/** A compiled entry: its verb, the source pattern (for inspection), and the matcher. */
+interface Entry<T> {
+  method: string;
+
+  pattern: string;
+
+  regExp: RegExp;
+
+  paramNames: ReadonlyArray<string>;
+
+  catchAllParams: ReadonlySet<string>;
+
+  value: T;
+}
+
+/**
+ * A successful match: the stored value and the params captured from the path.
+ *
+ * A single `:param` captures a `string`; a `*catchAll` captures the `string[]` run
+ * of segments it spanned (`[]` for an optional catch-all that matched none) — so a
+ * param value is `string | string[]`, narrowed per-key by `@lesto/router`'s
+ * `PathParams` wherever the pattern is known at the type level.
+ */
+export interface Match<T> {
+  value: T;
+
+  params: Record<string, string | string[]>;
+}
+
+export class RouteTable<T> {
+  // Insertion order is resolution order: the first matching route wins.
+  private readonly entries: Entry<T>[] = [];
+
+  /**
+   * Register a route. The pattern is compiled once, here, so a malformed or
+   * ambiguous pattern (see {@link compile}) fails at declaration, not at request.
+   */
+  add(method: string, pattern: string, value: T): this {
+    const { regExp, paramNames, catchAllParams } = compile(pattern);
+
+    this.entries.push({ method, pattern, regExp, paramNames, catchAllParams, value });
+
+    return this;
+  }
+
+  /**
+   * Find the route that answers this method + path.
+   *
+   * Returns the stored value and the extracted params, or `undefined` when
+   * nothing matches — either no pattern fits the path, or the matching pattern
+   * wants a different verb. The verb check is first and cheapest; the RegExp runs
+   * only for a method that could answer.
+   */
+  match(method: string, path: string): Match<T> | undefined {
+    for (const entry of this.entries) {
+      if (entry.method !== method) continue;
+
+      const matched = entry.regExp.exec(path);
+
+      if (matched === null) continue;
+
+      // A NULL-PROTOTYPE map: param names come from the pattern, but a `:constructor`
+      // / `:__proto__` / dynamically-built name must read back as a plain key, never
+      // an inherited `Object.prototype` member (a truthy `params["constructor"]` could
+      // slip past an `if (!params[name])` check) and never mutate the object's proto.
+      const params: Record<string, string | string[]> = Object.create(null) as Record<
+        string,
+        string | string[]
+      >;
+
+      entry.paramNames.forEach((paramName, index) => {
+        // Group 0 is the whole match; captures start at 1, aligned with paramNames.
+        // The capture is the on-the-wire (encoded) form — decode it here, after the
+        // segment boundary is already fixed, so `%2F` can never smuggle a `/` into the
+        // route shape. A malformed `%` becomes a coded 400, not a 500.
+        const raw = matched[index + 1] as string | undefined;
+
+        if (entry.catchAllParams.has(paramName)) {
+          // A catch-all captured a `/`-joined run of segments — split on the literal
+          // boundary FIRST, then decode each, so the array element count is fixed on
+          // the wire form (a `%2F` decodes to `/` WITHIN an element, never a new one).
+          // An optional catch-all that matched nothing has no capture (`undefined`) → [].
+          params[paramName] =
+            raw === undefined
+              ? []
+              : raw.split("/").map((segment) => decodeParam(paramName, segment));
+        } else {
+          params[paramName] = decodeParam(paramName, raw as string);
+        }
+      });
+
+      return { value: entry.value, params };
+    }
+
+    return undefined;
+  }
+
+  /** Every registered route's verb + pattern, in resolution order, for inspection. */
+  list(): ReadonlyArray<{ method: string; pattern: string }> {
+    return this.entries.map((entry) => ({ method: entry.method, pattern: entry.pattern }));
+  }
+}
+
+/**
+ * Build a concrete path from a pattern by substituting and URL-encoding its params
+ * — the reverse of {@link RouteTable.match}, so a link never hardcodes a URL.
+ *
+ * Each `:param` is replaced by `encodeURIComponent` of its `string` value; each
+ * `*catchAll` by its `string[]` value's segments, each encoded and joined by `/`.
+ * That encoding is the exact inverse of the `decodeURIComponent` `match` applies,
+ * so the two round-trip: a value containing a `/` (or any unicode) survives the
+ * trip out and back unchanged — `pathFor("/files/:p", { p: "a/b" })` yields
+ * `/files/a%2Fb`, which `match` decodes back to `{ p: "a/b" }` as one segment;
+ * `pathFor("/docs/*r", { r: ["a", "b"] })` yields `/docs/a/b`, decoded back to the
+ * two-element array. An OPTIONAL catch-all given `[]` drops its whole segment —
+ * `pathFor("/shop/*r?", { r: [] })` is `/shop`, and the root `pathFor("/*r?", { r:
+ * [] })` is `/`.
+ *
+ * Throws a coded {@link RouterError} (`ROUTER_MISSING_PARAM`) if the pattern needs
+ * a param the caller did not supply, supplied empty, or supplied with the wrong
+ * shape: a `[^/]+` capture matches one-or-more chars, so an empty single value
+ * yields a path that can never route back (`/files/` misses `/files/:p`), and a
+ * required catch-all needs at least one segment. All wiring bugs caught here, not
+ * broken links shipped to a user.
+ */
+export const pathFor = (
+  pattern: string,
+  params: Record<string, string | readonly string[]> = {},
+): string => {
+  const missing = (paramName: string): RouterError =>
+    new RouterError(
+      "ROUTER_MISSING_PARAM",
+      `Pattern "${pattern}" needs a non-empty "${paramName}" param.`,
+      { pattern, param: paramName },
+    );
+
+  let out = "";
+  let lastIndex = 0;
+
+  for (const match of pattern.matchAll(PARAM_TOKEN)) {
+    const between = pattern.slice(lastIndex, match.index);
+    const singleName = match[1];
+
+    if (singleName !== undefined) {
+      const value = params[singleName];
+
+      if (typeof value !== "string" || value === "") throw missing(singleName);
+
+      out += between + encodeURIComponent(value);
+    } else {
+      const name = match[2] as string;
+      const optional = match[3] === "?";
+      const value = params[name];
+
+      // A catch-all takes the `string[]` run of segments; a missing or `string` value
+      // is the wrong shape (and narrows `value` to the array for the rest of the arm).
+      if (value === undefined || typeof value === "string") throw missing(name);
+
+      if (value.length === 0) {
+        if (!optional) throw missing(name);
+
+        // An empty optional catch-all contributes no segment: drop the preceding
+        // slash so the bare prefix stands (`/shop/*r?` → `/shop`), except at the root
+        // where the leading `/` is the path itself (`/*r?` → `/`).
+        out += between === "/" ? "/" : between.slice(0, -1);
+      } else if (value.some((segment) => segment === "")) {
+        // An empty element would emit a `//` the match regex rejects — refuse it, so
+        // the documented round-trip holds rather than shipping an unroutable link.
+        throw missing(name);
+      } else {
+        out += between + value.map((segment) => encodeURIComponent(segment)).join("/");
+      }
+    }
+
+    lastIndex = match.index + match[0].length;
+  }
+
+  return out + pattern.slice(lastIndex);
+};