@bronti/wooter 0.0.0-stage → 6.0.0

package/src/Wooter.ts

@@ -0,0 +1,318 @@
+import type { EmptyObject } from "./types/types.ts";
+import type { MethodDefinitionInput, MethodDefinitions } from "./Graph.ts";
+import type {
+  MiddlewareHandler,
+  OptionalMerge,
+  Params,
+  RouteHandler,
+  State,
+} from "./types/types.ts";
+import type { Merge } from "./types/internal.ts";
+import RouteContext, {
+  RouteContext__execution,
+  RouteContext__respond,
+} from "./RouteContext.ts";
+import { Graph } from "./Graph.ts";
+import type { ParamsOfPath, Path } from "./path/types.ts";
+
+type KeysSubset<U, T> =
+  Exclude<keyof U, keyof T> extends never ? unknown : never;
+
+/**
+ * Typed HTTP router with composable middleware and nested route namespaces.
+ *
+ * @typeParam TState Middleware-provided state available on every handler context.
+ * @typeParam TParentParams Params inherited from parent routers.
+ */
+export default class Wooter<
+  BaseState extends State | undefined = undefined,
+  TState extends State | undefined = undefined,
+  BasePath extends Path = Path,
+  TParentParams extends Params | undefined = ParamsOfPath<BasePath>,
+> {
+  private graph: Graph;
+  #notFoundHandler?: RouteHandler<EmptyObject>;
+
+  /**
+   * Returns the registered 404 handler, or a default fallback when none is set.
+   *
+   * @internal
+   */
+  private get notFoundHandler(): RouteHandler<EmptyObject> {
+    return (
+      this.#notFoundHandler ??
+      (({ resp, url, request }) =>
+        resp(
+          new Response(`Not found ${request.method} ${url.pathname}`, {
+            status: 404,
+          }),
+        ))
+    );
+  }
+
+  /**
+   * Creates a new router instance.
+   *
+   * @param basePath Optional base path prepended to all routes registered on this instance.
+   * @param catchStrayErrors Error sink used for asynchronous errors that occur after a response was already sent.
+   */
+  constructor(
+    basePath?: BasePath,
+    protected catchStrayErrors: (e: unknown) => void = (e) => {
+      throw e;
+    },
+  ) {
+    this.graph = new Graph(basePath);
+  }
+
+  /**
+   * Registers a handler for one or more HTTP methods on a path.
+   *
+   * Routes are matched in registration order. Use this overload for single methods,
+   * arrays of methods, or the wildcard `"*"`.
+   *
+   * @example Register a GET route
+   * ```ts
+   * router.route(p.path("users"), "GET", ({ resp }) => {
+   *   resp(Response.json([]))
+   * })
+   * ```
+   *
+   * @example Register multiple methods
+   * ```ts
+   * router.route(p.path("users"), ["GET", "POST"], ({ request, resp }) => {
+   *   if (request.method === "GET") resp(Response.json([]))
+   *   else resp(Response.json({}, { status: 201 }))
+   * })
+   * ```
+   *
+   * @typeParam TParams Parameter type inferred from the path.
+   * @param path Typed route path built with the path API.
+   * @param method HTTP method: string, array of methods, or `"*"` for all.
+   * @param handler Route handler receiving the route context.
+   * @returns The current router for method chaining.
+   * @throws TypeError if handler is not provided with string/array method.
+   */
+  route<
+    TPath extends Path,
+    TParams extends Record<string, unknown> = ParamsOfPath<TPath>,
+  >(
+    path: TPath,
+    method: MethodDefinitionInput,
+    handler: RouteHandler<OptionalMerge<TParams, TParentParams>, TState>,
+  ): this;
+  /**
+   * Registers different handlers for different HTTP methods on the same path.
+   *
+   * This overload accepts a method-to-handler map. Omitted methods are not handled.
+   *
+   * @example Register per-method handlers
+   * ```ts
+   * router.route(p.path("users"), {
+   *   GET: ({ resp }) => resp(Response.json([])),
+   *   POST: ({ request, resp }) => {
+   *     const body = await request.json()
+   *     resp(Response.json(body, { status: 201 }))
+   *   },
+   * })
+   * ```
+   *
+   * @typeParam TParams Parameter type inferred from the path.
+   * @param path Typed route path built with the path API.
+   * @param handlers Map of HTTP methods to their handler functions.
+   * @returns The current router for method chaining.
+   */
+  route<
+    TPath extends Path,
+    TParams extends Record<string, unknown> = ParamsOfPath<TPath>,
+  >(
+    path: TPath,
+    handlers: MethodDefinitions<Merge<TParams, TParentParams>, TState>,
+  ): this;
+  /**
+   * Registers a route definition on this router.
+   *
+   * @param path Typed route path.
+   * @param methodOrHandlers Method selector(s) or method-to-handler map.
+   * @param handler Handler used when `methodOrHandlers` is method-based.
+   * @returns The current router instance for chaining.
+   */
+  route<
+    TPath extends Path,
+    TParams extends Record<string, unknown> = ParamsOfPath<TPath>,
+  >(
+    path: TPath,
+    methodOrHandlers:
+      | MethodDefinitionInput
+      | MethodDefinitions<Merge<TParams, TParentParams>, TState>,
+    handler?: RouteHandler<OptionalMerge<TParams, TParentParams>, TState>,
+  ): this {
+    if (
+      typeof methodOrHandlers == "string" ||
+      Array.isArray(methodOrHandlers)
+    ) {
+      if (!handler) throw new TypeError();
+      if (methodOrHandlers === "*") {
+        this.graph.addRoute_wildcardMethod(path, handler);
+      } else {
+        const methods = new Set(
+          [methodOrHandlers].flat().map((x) => x.toUpperCase()),
+        );
+        this.graph.addRoute_withMethodSet(path, handler, methods);
+      }
+    } else {
+      this.graph.addRoute_withMethodMap(
+        path,
+        methodOrHandlers as MethodDefinitions<
+          Merge<TParams, TParentParams>,
+          TState
+        >,
+      );
+    }
+    return this;
+  }
+
+  /**
+   * Adds middleware that can enrich context state for downstream handlers.
+   *
+   * @param handler Middleware to run before route handlers.
+   * @returns A typed router view whose `state` reflects middleware output.
+   *
+   * @ignore
+   */
+  use<TNextState extends State | undefined = undefined>(
+    handler: MiddlewareHandler<Params, TState, TNextState>,
+  ): Wooter<
+    BaseState,
+    OptionalMerge<TState, TNextState>,
+    BasePath,
+    TParentParams
+  >;
+
+  /**
+   * Adds middleware authored against a narrower input state shape.
+   *
+   * @param handler Middleware to run before route handlers.
+   * @returns A typed router view whose `state` reflects middleware output.
+   *
+   * @ignore
+   */
+  use<
+    TNextState extends State | undefined = undefined,
+    THandlerInputState extends
+      (State & KeysSubset<THandlerInputState, TState>) | undefined = undefined,
+  >(
+    handler: MiddlewareHandler<
+      Record<string, unknown>,
+      THandlerInputState,
+      TNextState
+    >,
+  ): Wooter<
+    BaseState,
+    OptionalMerge<TState, TNextState>,
+    BasePath,
+    TParentParams
+  >;
+
+  /**
+   * Adds middleware to this router.
+   *
+   * @param handler Middleware to run before matching route handlers.
+   * @returns A typed router view whose `state` includes middleware output.
+   */
+  use<TNextState extends State | undefined = undefined>(
+    handler: MiddlewareHandler<Record<string, unknown>, TState, TNextState>,
+  ): Wooter<
+    BaseState,
+    OptionalMerge<TState, TNextState>,
+    BasePath,
+    TParentParams
+  > {
+    this.graph.addMiddleware(handler);
+    return this as unknown as Wooter<
+      BaseState,
+      OptionalMerge<TState, TNextState>,
+      BasePath,
+      TParentParams
+    >;
+  }
+
+  /**
+   * Creates a child router mounted under the current router.
+   *
+   * Routes registered on the returned router are reachable through this router.
+   *
+   * @param basePath Path prefix for the child router.
+   * @returns A new router instance scoped to `basePath`.
+   */
+  branch<
+    TPath extends Path,
+    TParams extends Record<string, unknown> = ParamsOfPath<TPath>,
+  >(
+    basePath: TPath,
+  ): Wooter<BaseState, TState, BasePath, Merge<TParams, TParentParams>> {
+    const router = new Wooter<
+      BaseState,
+      TState,
+      BasePath,
+      Merge<TParams, TParentParams>
+    >();
+    this.graph.addNamespace(basePath, router.graph);
+    return router;
+  }
+
+  /**
+   * Registers a fallback handler used when no route matches.
+   *
+   * @param handler Route handler for unmatched requests.
+   * @returns The current router instance for chaining.
+   */
+  notFound(handler: RouteHandler<EmptyObject>): this {
+    this.#notFoundHandler = handler;
+    return this;
+  }
+
+  /**
+   * Handles a request through middleware and route matching.
+   *
+   * This is the entry point to the router. Export it directly to an HTTP server.
+   *
+   * @example Use with Deno
+   * ```ts
+   * export default app
+   * // Or serve directly: Deno.serve(app.fetch)
+   * ```
+   *
+   * @param request The incoming HTTP request.
+   * @returns A promise resolving to the HTTP response.
+   * @throws On framework errors (handler didn't respond, responded twice, etc.).
+   */
+  readonly fetch = (
+    request: Request,
+    base_state?: BaseState,
+  ): Promise<Response> => {
+    const url = new URL(request.url);
+    let handler = this.graph.getHandler(url.pathname, request.method);
+    if (!handler) {
+      handler = RouteContext.useRouteHandler(
+        this.notFoundHandler,
+        {},
+        this.catchStrayErrors,
+      );
+    }
+
+    const { promise, resolve, reject } = Promise.withResolvers<Response>();
+    const ctx = handler(base_state ?? {}, request, this.catchStrayErrors);
+    const execution = ctx[RouteContext__execution];
+    const respond = ctx[RouteContext__respond];
+
+    respond.then(resolve);
+    execution.then((result) => {
+      result.inspect((err) => {
+        reject(err);
+      });
+    });
+
+    return promise;
+  };
+}

package/src/WooterError.ts

@@ -0,0 +1,26 @@
+/**
+ * Sentinel error used to abort handler execution without surfacing as a failure.
+ *
+ * Throw this after sending a response to stop further lifecycle work.
+ */
+export const ControlFlowBreak = Symbol("ControlFlowBreak");
+
+/**
+ * Type of {@link ControlFlowBreak}.
+ */
+export type ControlFlowBreak = typeof ControlFlowBreak;
+
+/**
+ * Base error class for framework-level errors.
+ */
+export default class WooterError extends Error {}
+
+/**
+ * Checks whether a value is a known internal framework error.
+ *
+ * @param v Value to test.
+ * @returns `true` when `v` is a `WooterError` or `ControlFlowBreak`.
+ */
+export function isWooterError(v: unknown): v is WooterError {
+  return v instanceof WooterError || v == ControlFlowBreak;
+}

package/src/export/error.ts

@@ -0,0 +1,17 @@
+/**
+ * Public error exports.
+ *
+ * @module
+ */
+
+export {
+  ControlFlowBreak,
+  default as WooterError,
+  isWooterError,
+} from "../WooterError.ts";
+
+export {
+  HandlerDidntRespondError,
+  HandlerRespondedTwiceError,
+} from "../RouteContext.ts";
+export { MiddlewareHandlerDidntCallUpError } from "../MiddlewareContext.ts";

package/src/export/mod.ts

@@ -0,0 +1,10 @@
+export * from "./error.ts";
+export * from "./response.ts";
+export { default as use, middleware } from "./use.ts";
+/** Typed path builders and matchers. */
+export * as p from "./path.ts";
+export { Option, UnwrapNoneError } from "./option.ts";
+export { ExpectErrError, ExpectOkError, Result } from "./result.ts";
+export { default as Wooter } from "../Wooter.ts";
+
+export * from "./types.ts";

package/src/export/option.ts

@@ -0,0 +1,8 @@
+/**
+ * Option utility exports.
+ *
+ * @module
+ */
+
+import { none, Option, some, UnwrapNoneError } from "@bronti/robust/Option";
+export { none, Option, some, UnwrapNoneError };

package/src/export/path.ts

@@ -0,0 +1,13 @@
+/** Typed path utility exports.
+ *
+ * @module
+ */
+
+import * as _p from "../path/index.ts";
+
+/** Namespace-like default export containing all path utilities. */
+const p: typeof import("../path/index.ts") = _p;
+
+export default p;
+export * from "../path/index.ts";
+export * from "../path/types.ts";

package/src/export/response.ts

@@ -0,0 +1,39 @@
+/**
+ * Creates a redirect response.
+ *
+ * @param location Redirect destination.
+ * @param init Optional response init. `status` defaults to `307`.
+ * @returns Redirect response with `Location` header set.
+ */
+export function makeRedirect(
+  location: string | URL,
+  init?: ResponseInit,
+): Response {
+  const headers = new Headers(init?.headers);
+  headers.set("Location", location.toString());
+  return new Response(null, {
+    ...init,
+    status: init?.status ?? 307,
+    headers,
+  });
+}
+
+/**
+ * Creates an error response with an optional body message.
+ *
+ * @param status HTTP status code.
+ * @param message Optional error message for body and status text.
+ * @param headers Optional response headers.
+ * @returns Error response.
+ */
+export function makeError(
+  status: number,
+  message?: string,
+  headers?: HeadersInit,
+): Response {
+  return new Response(message, {
+    status,
+    statusText: message,
+    headers,
+  });
+}

package/src/export/result.ts

@@ -0,0 +1,14 @@
+/**
+ * Result utility exports.
+ *
+ * @module
+ */
+
+import {
+  err,
+  ExpectErrError,
+  ExpectOkError,
+  ok,
+  Result,
+} from "@bronti/robust/Result";
+export { err, ExpectErrError, ExpectOkError, ok, Result };

package/src/export/types.ts

@@ -0,0 +1 @@
+export * from "../types/types.ts";

package/src/export/use.ts

@@ -0,0 +1,68 @@
+import type {
+  MiddlewareHandler,
+  OptionalMerge,
+  Params,
+  RouteHandler,
+  State,
+} from "./types.ts";
+import {
+  RouteContext__execution,
+  RouteContext__reporter,
+  RouteContext__respond,
+} from "../RouteContext.ts";
+import { Graph } from "../Graph.ts";
+
+/**
+ * Applies middleware directly to a route handler and returns a wrapped handler.
+ *
+ * @param middlewareHandler Middleware to apply before the handler.
+ * @param handler Route handler to wrap.
+ * @returns Route handler that executes middleware and then delegates to `handler`.
+ */
+export default function use<
+  NextState extends State | undefined = undefined,
+  BaseState extends State | undefined = undefined,
+  // deno-lint-ignore ban-types
+  TParams extends Params = {},
+>(
+  middlewareHandler: MiddlewareHandler<TParams, BaseState, NextState>,
+  handler: RouteHandler<TParams, OptionalMerge<BaseState, NextState>>,
+): RouteHandler<TParams, BaseState> {
+  return async (ctx) => {
+    const { params, request, state, resp } = ctx;
+    const reporter = ctx[RouteContext__reporter];
+    // @ts-expect-error: Generics defaults get annoying here
+    const internalHandler = Graph.compose(handler, params, [middlewareHandler]);
+    const new_ctx = internalHandler(state, request, reporter);
+
+    new_ctx[RouteContext__respond].promise.then((r) => resp(r));
+    return (await new_ctx[RouteContext__execution].promise).inspect((e) => {
+      throw e;
+    });
+  };
+}
+
+/**
+ * Identity helper used to type middleware declarations.
+ *
+ * @param handler Middleware handler.
+ * @returns The same middleware handler with preserved generic inference.
+ *
+ * @example
+ * ```ts
+ * const userAgent = middleware<{ userAgent: string | null }>(async ({ request, next }) => {
+ *   await next({ userAgent: request.headers.get("User-Agent") })
+ * })
+ *
+ * router.use(userAgent)
+ * ```
+ */
+export function middleware<
+  TNextState extends State | undefined = undefined,
+  TState extends State | undefined = undefined, // deno-lint-ignore ban-types
+  TParams extends Params = {},
+>(
+  handler: MiddlewareHandler<TParams, TState, TNextState>,
+): MiddlewareHandler<TParams, TState, TNextState> {
+  return handler;
+}

package/src/path/index.ts

@@ -0,0 +1,84 @@
+import { single, wrap } from "./matcher.ts";
+import type { Matcher, Param, Path } from "./types.ts";
+
+export * from "./matcher.ts";
+export * from "./match.ts";
+
+/** Builds a typed route path from literal segments and parameters. */
+export const path = <const TPath extends Path>(...path: TPath): TPath => path;
+
+/** Creates a named route parameter, optionally parsed by a matcher. */
+export function param<Name extends string>(name: Name): Param<Name, string>;
+/** Creates a named route parameter parsed by a matcher. */
+export function param<Name extends string, T>(
+  name: Name,
+  matcher: Matcher<T, undefined>,
+): Param<Name, T, undefined>;
+/** Creates a named route parameter parsed by a matcher with options. */
+export function param<Name extends string, T, Options>(
+  name: Name,
+  matcher: Matcher<T, Options>,
+  options: Options,
+): Param<Name, T, Options>;
+export function param(
+  name: string,
+  matcher?: Matcher<any, any>,
+  options?: any,
+): Param<any, any, any> {
+  return matcher ? { name, matcher, options } : { name };
+}
+
+/** Matches a segment and converts it to a number. */
+export const num: Matcher<number> = single<number>(function num(seg) {
+  const value = Number(seg);
+  if (isNaN(value)) return { ok: false };
+  return { ok: true, value };
+});
+
+/** Matches and returns one non-empty path segment. */
+export const passthrough: Matcher<string> = single<string>((value) =>
+  value ? { ok: true, value } : { ok: false },
+);
+
+/** Repeats a matcher zero or more times, or one or more times when requested. */
+export function multiple<T, Opt>(
+  matcher: Matcher<T, Opt>,
+  at_least_one = false,
+): Matcher<T[], Opt> {
+  return wrap<T[], Opt>(
+    (path, i, opt) => {
+      let consume = 0;
+      const value = [];
+
+      while (true) {
+        const result = matcher(path, i, opt);
+        if (!result.ok || !result.consume || result.consume <= 0) break;
+        value.push(result.value);
+        i += result.consume;
+        consume += result.consume;
+      }
+
+      if (consume == 0 && at_least_one) return { ok: false };
+      return { ok: true, consume, value };
+    },
+    matcher.name,
+    (name) => name + (at_least_one ? "+" : "*"),
+  );
+}
+
+/** Matches the remaining path segments. */
+export const rest: Matcher<string[]> = multiple(passthrough);
+
+/** Makes a matcher optional. */
+export function optional<T, Opt>(
+  matcher: Matcher<T, Opt>,
+): Matcher<T | undefined, Opt> {
+  return wrap<T | undefined, Opt>(
+    (path, i, opt) => {
+      const result = matcher(path, i, opt);
+      return result.ok ? result : { ok: true, value: undefined, consume: 0 };
+    },
+    matcher.name,
+    (name) => `${name}?`,
+  );
+}

package/src/path/match.ts

@@ -0,0 +1,82 @@
+import type { ParamsOfPath, Path } from "./types.ts";
+
+/**
+ * Matches path segments against a typed pattern and extracts params.
+ *
+ * When `exact` is `true`, all remaining segments must be consumed.
+ */
+export function match<const TPath extends Path>(
+  segments: string[],
+  i: number,
+  pattern: TPath,
+  exact: true,
+): { match: false } | { match: true; params: ParamsOfPath<TPath> };
+/**
+ * Matches path segments against a typed pattern and extracts params.
+ *
+ * When `exact` is `true`, all remaining segments must be consumed.
+ */
+export function match<const TPath extends Path>(
+  segments: string[],
+  i: number,
+  pattern: TPath,
+  exact: false,
+):
+  | { match: false }
+  | { match: true; params: ParamsOfPath<TPath>; stopped_at: number };
+export function match(
+  segments: string[],
+  i: number,
+  pattern: Path,
+  exact: boolean,
+):
+  | { match: false }
+  | { match: true; params: Record<string, unknown>; stopped_at?: number } {
+  const params: Record<string, unknown> = {};
+
+  for (const patternElement of pattern) {
+    if (typeof patternElement == "string") {
+      if (i >= segments.length || segments[i] != patternElement)
+        return { match: false };
+      i++;
+      continue;
+    }
+    if (!("matcher" in patternElement)) {
+      if (i >= segments.length) return { match: false };
+      params[patternElement.name] = segments[i];
+      i++;
+      continue;
+    }
+
+    const result = patternElement.matcher(segments, i, patternElement.options);
+    if (result.ok) {
+      params[patternElement.name] = result.value;
+      i += result.consume;
+      continue;
+    }
+
+    return { match: false };
+  }
+
+  if (i < segments.length && exact) return { match: false };
+
+  return { match: true, params, stopped_at: i };
+}
+
+/** Converts a typed path pattern into a readable route string. */
+export function stringify(path: Path): string {
+  const strs = [];
+  for (const patternElement of path) {
+    if (typeof patternElement == "string") {
+      strs.push(patternElement);
+      continue;
+    }
+    if ("matcher" in patternElement && patternElement.matcher.name) {
+      strs.push(`:${patternElement.name}(${patternElement.matcher.name})`);
+      continue;
+    }
+    strs.push(`:${patternElement.name}`);
+  }
+  strs.unshift("");
+  return strs.join("/");
+}