@bronti/wooter 0.0.0-stage → 6.0.0

package/DOC.md

@@ -0,0 +1,289 @@
+Wooter routes Fetch API `Request`s to typed handlers. Paths infer parameters, middleware adds typed state, and handlers answer
+through `resp()` or `json()`.
+
+### Deno
+
+```bash
+deno add @bronti/wooter
+
+JSR from npm tooling
+npx jsr add @bronti/wooter
+```
+
+```ts
+import { p, Wooter } from "@bronti/wooter";
+
+const app = new Wooter();
+
+app.route(p.path("hello"), "GET", ({ resp }) => {
+  resp("Hello, Wooter!");
+});
+
+export default app;
+```
+
+Response-first lifecycle
+
+A handler that exits without calling `⁠resp()`⁠ or `json()`⁠ fails with `HandlerDidntRespondError`⁠. Calling `⁠resp()`⁠ twice fails too.
+
+Routes and parameters
+
+Build paths with `⁠p.path()`⁠. A bare string is literal. `⁠p.param()`⁠ captures a segment, and a matcher parses it while preserving
+the inferred type.
+
+```ts
+app.route(
+  p.path("users", p.param("id", p.num)),
+  "GET",
+  async ({ params, json }) => {
+    const id = params.get("id"); // number
+
+    const user = await db.getUser(id);
+
+    json(user);
+  },
+);
+```
+
+Path helpers
+
+- Root: `⁠p.path()⁠`
+
+- String param: `⁠p.param("slug")⁠`
+
+- Number param: `⁠p.param("id", p.num)⁠`
+
+- Remaining segments: `⁠p.param("rest", p.rest)⁠`
+
+- Optional matcher: `⁠p.optional(matcher)⁠`
+
+- Repeated matcher: `⁠p.multiple(matcher)⁠`
+
+One path can also use a method map:
+
+```ts
+app.route(p.path("items"), {
+  GET: ({ json }) => json(listItems()),
+
+  POST: async ({ request, json }) => {
+    const item = await request.json();
+
+    json(await createItem(item), { status: 201 });
+  },
+});
+```
+
+Middleware
+
+`⁠use()`⁠ adds middleware in registration order. Middleware can enrich downstream state, short-circuit with a response, or inspect
+the response coming back up.import { middleware, p, Wooter } from "@bronti/wooter"
+
+```ts
+const auth = middleware<{ user: User }>(async ({ request, forward, resp }) => {
+  const user = await authenticate(request);
+
+  if (!user) return resp("Unauthorized", { status: 401 });
+
+  await forward({ user });
+});
+
+const app = new Wooter()
+  .use(auth)
+  .route(p.path("me"), "GET", ({ state, json }) => {
+    json(state.user);
+  });
+```
+
+Middleware tools
+
+- forward(state) Runs the rest of the chain and forwards its response unchanged.
+
+- next(state) Runs downstream and returns its `⁠Response`⁠ so middleware can inspect or replace it.
+
+- tryNext(state) Captures downstream success or failure in a `Result` instead of throwing.
+
+- tryForward(state) Captures the `⁠Result`⁠ and forwards a successful response.
+
+The green path
+
+Keep route handlers focused on successful application work. Do not wrap every database call in a local ⁠try/catch⁠ just to translate
+failures into HTTP. Let the operation throw. Put the translation policy once in middleware, keyed by specific error classes.
+
+Handler: business flow only
+
+```ts
+app.route(
+  p.path("books", p.param("id", p.num)),
+  "GET",
+  async ({ params, json }) => {
+    const book = await db.getBook(params.get("id"));
+
+    json(book);
+  },
+);
+```
+
+Middleware: errors become responses
+
+```ts
+const errors = middleware(async ({ tryNext, resp }) => {
+  const result = await tryNext({});
+
+  result.match(
+    (response) => resp(response),
+    (error) => {
+      if (error instanceof BookNotFoundError) {
+        return resp("Book not found", { status: 404 });
+      }
+
+      if (error instanceof DatabaseUnavailableError) {
+        return resp("Try again later", { status: 503 });
+      }
+
+      throw error;
+    },
+  );
+});
+
+const app = new Wooter().use(errors);
+```
+
+Why this stays green
+
+The handler reads top to bottom as the successful request. Middleware owns cross-cutting HTTP policy. Unknown errors are rethrown
+rather than disguised as expected failures.
+
+Throw is part of the design
+
+Wooter deliberately uses thrown values as control flow through the request lifecycle. A route can let an application error throw;
+the middleware chain can capture it with `⁠tryNext()`⁠ and decide which errors become responses.
+
+⁠`safeExit()`⁠ makes that intent explicit for framework control flow. After code has already responded, it throws Wooter’s internal
+`⁠ControlFlowBreak⁠` sentinel to stop the rest of the handler without surfacing a failure.
+
+```ts
+const requireJson = middleware<{ body: unknown }>(
+  async ({ request, resp, forward, safeExit }) => {
+    let body: unknown;
+
+    try {
+      body = await request.json();
+    } catch {
+      resp("Invalid JSON", { status: 400 });
+
+      return safeExit(); // throws ControlFlowBreak intentionally
+    }
+
+    await forward({ body });
+  },
+);
+```
+
+Respond, then stop
+
+`⁠safeExit()`⁠ is for intentional exit after a response exists. Ordinary application errors should keep their real identity so error
+middleware can match them.
+
+Stay on the handler execution
+
+Keep asynchronous route work attached to the handler’s returned promise, usually by using `⁠await⁠`. Wooter requires a response
+before handler execution stops, and attached work lets thrown errors travel through the middleware chain instead of escaping later
+as stray errors or crashes.
+
+Detached: execution ends too early
+
+```ts
+app.route(path, "GET", ({ json }) => {
+  setTimeout(async () => {
+    const book = await db.getBook(1);
+
+    json(book);
+  }, 10);
+  // function exits here, but json() is called 10 milliseconds after
+});
+```
+
+Inside out: await the timer
+
+```ts
+const delay = (ms: number) =>
+  new Promise<void>((resolve) => setTimeout(resolve, ms));
+
+app.route(path, "GET", async ({ json }) => {
+  await delay(10);
+
+  const book = await db.getBook(1);
+
+  json(book);
+});
+```
+
+The rule of thumb
+
+If an API wants a callback such as `⁠setTimeout()`⁠, flip it inside out: wrap it in a promise, await that promise inside the
+handler, then keep going. Response timing and error propagation stay inside one execution.
+
+Response tools
+
+- Text or body: `⁠resp(body, init?)⁠`
+
+- Full response: `⁠resp(new Response(...))⁠`
+
+- JSON: `⁠json(data, init?)⁠`
+
+- Error helper: `⁠makeError(status, message?)⁠`
+
+- Redirect helper: `⁠makeRedirect(location, init?)⁠`
+
+- Intentional stop: `⁠safeExit()⁠`
+
+`safeExit()`⁠ is useful after middleware has already sent a response but nested helper code must stop immediately.
+
+A practical shape
+
+```ts
+import { middleware, p, Wooter } from "@bronti/wooter";
+
+const errors = middleware(async ({ tryNext, resp }) => {
+  const result = await tryNext({});
+
+  result.match(
+    (response) => resp(response),
+    (error) => {
+      if (error instanceof NotFoundError) {
+        return resp("Not found", { status: 404 });
+      }
+
+      throw error;
+    },
+  );
+});
+
+const app = new Wooter()
+  .use(errors)
+  .route(
+    p.path("books", p.param("id", p.num)),
+    "GET",
+    async ({ params, json }) => {
+      json(await db.getBook(params.get("id")));
+    },
+  );
+
+export default app;
+```
+
+One Fetch entrypoint, any runtime
+
+Wooter runs anywhere JavaScript provides the standard `⁠Request⁠` and `⁠Response`⁠ classes, including browsers, Deno, Node.js, Bun,
+Workers and other Fetch-compatible runtimes.
+
+Its runtime entrypoint is `⁠wooter.fetch(request)`⁠. Give it a `⁠Request`⁠; it returns a `⁠Promise<Response>`⁠. The host decides how
+requests reach that method.
+
+```ts
+const wooter = new Wooter().route(p.path("hello"), "GET", ({ resp }) => {
+  resp("Hello");
+});
+
+const response = await wooter.fetch(new Request("https://example.test/hello"));
+```

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright 2026 @brontidev
+
+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

@@ -1,3 +1,24 @@
-# Temporary Holding Version
+# @bronti/wooter
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![JSR](https://jsr.io/badges/@bronti/wooter)](https://jsr.io/@bronti/wooter)
+[![JSR Score](https://jsr.io/badges/@bronti/wooter/score)](https://jsr.io/@bronti/wooter)
+
+A **fetch-native, type-safe HTTP router** for JavaScript/TypeScript with **explicit middleware composition** and **zero runtime
+dependencies**.
+
+```ts
+import { p, Wooter } from "@bronti/wooter";
+
+const app = new Wooter()
+  .use(cors)
+  .use(auth)
+  .route(
+    p.path("users", p.param("id", p.num)),
+    "GET",
+    async ({ params, resp }) => {
+      resp(Response.json({ userId: params.get("id") }));
+    },
+  );
+
+export default app.fetch;
+```

package/package.json

@@ -1,6 +1,15 @@
 {
   "name": "@bronti/wooter",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "6.0.0",
+  "license": "MIT",
+  "exports": {
+    "./*": "./src/export/*"
+  },
+  "scripts": {
+    "fmt:check": "bun fmt --check",
+    "fmt:fix": "bun fmt"
+  },
+  "dependencies": {
+    "@bronti/robust": "npm:@jsr/bronti__robust@0.0.3-beta"
+  }
+}

package/src/Graph.ts

@@ -0,0 +1,231 @@
+import { match } from "./path/match.ts";
+import type { Path } from "./path/types.ts";
+import type { Methods, RouteHandler, State } from "./types/types.ts";
+import type { InternalHandler } from "./RouteContext.ts";
+import MiddlewareContext, {
+  type MiddlewareHandler,
+} from "./MiddlewareContext.ts";
+import RouteContext from "./RouteContext.ts";
+
+/**
+ * Method definition accepted by `route` overloads.
+ *
+ * @internal
+ */
+export type MethodDefinitionInput =
+  Methods | Uppercase<string> | Methods[] | Uppercase<string>[] | "*";
+
+/**
+ * Map of HTTP methods to handlers for a route.
+ *
+ * @internal
+ */
+export type MethodDefinitions<
+  TParams extends Record<string, unknown>,
+  TState extends State | undefined = undefined,
+> = Partial<
+  Record<
+    Methods,
+    RouteHandler<TParams, TState extends undefined ? State : TState>
+  >
+> &
+  Record<
+    Uppercase<string>,
+    RouteHandler<TParams, TState extends undefined ? State : TState>
+  >;
+
+enum NodeType {
+  MethodsToHandlers,
+  AnyMethod,
+  HandlerWithMethods,
+}
+
+export type Node = (
+  | {
+      t: NodeType.MethodsToHandlers;
+      handlers: Map<string, RouteHandler>;
+    }
+  | { t: NodeType.AnyMethod; handler: RouteHandler }
+  | {
+      t: NodeType.HandlerWithMethods;
+      handler: RouteHandler;
+      methods: Set<string>;
+    }
+) & { path: Path };
+
+export type Namespace = {
+  path: Path;
+  graph: Graph;
+};
+
+export class Graph {
+  private nodes = new Set<Node>();
+  private middleware = new Set<MiddlewareHandler>();
+  private namespaces = new Set<Namespace>();
+
+  constructor(private basePath?: Path) {}
+
+  addMiddleware(handler: MiddlewareHandler<any, any, any>) {
+    this.middleware.add(handler);
+  }
+
+  addNamespace(path: Path, graph: Graph) {
+    this.namespaces.add({
+      graph,
+      path,
+    });
+  }
+
+  addNode(node: Node) {
+    this.nodes.add(node);
+  }
+
+  addRoute_wildcardMethod(path: Path, handler: RouteHandler<any, any>) {
+    this.addNode({
+      t: NodeType.AnyMethod,
+      path,
+      handler,
+    });
+  }
+
+  addRoute_withMethodSet(
+    path: Path,
+    handler: RouteHandler<any, any>,
+    methods: Set<string>,
+  ) {
+    this.addNode({
+      t: NodeType.HandlerWithMethods,
+      path,
+      handler,
+      methods,
+    });
+  }
+
+  addRoute_withMethodMap(
+    path: Path,
+    handlers: Record<string, RouteHandler<any, any>>,
+  ) {
+    this.addNode({
+      t: NodeType.MethodsToHandlers,
+      handlers: new Map(
+        Object.entries(handlers).map(([k, v]) => [k.toUpperCase(), v]),
+      ),
+      path,
+    });
+  }
+
+  protected internalGetHandler(
+    path: string[],
+    i: number,
+    method: string,
+    outParams: Record<string, any>,
+    outMiddleware: MiddlewareHandler[],
+  ): RouteHandler | undefined {
+    for (const namespace of this.namespaces) {
+      const namespaceResult = match(path, i, namespace.path, false);
+      if (!namespaceResult.match) continue;
+
+      const middlewareStartIndex = outMiddleware.length;
+      for (const mw of this.middleware) outMiddleware.push(mw);
+      Object.assign(outParams, namespaceResult.params);
+
+      const handler = namespace.graph.internalGetHandler(
+        path,
+        namespaceResult.stopped_at,
+        method,
+        outParams,
+        outMiddleware,
+      );
+      if (handler) return handler;
+
+      outMiddleware.length = middlewareStartIndex;
+      continue;
+    }
+
+    for (const node of this.nodes) {
+      let handler: RouteHandler | undefined;
+      if (node.t === NodeType.MethodsToHandlers) {
+        const _handler = node.handlers.get(method);
+        if (!_handler) continue;
+        handler = _handler;
+      } else if (node.t === NodeType.AnyMethod) {
+        handler = node.handler;
+      } else if (node.t === NodeType.HandlerWithMethods) {
+        if (!node.methods.has(method)) continue;
+        handler = node.handler;
+      } else {
+        throw new TypeError("Invalid configuration");
+      }
+      const result = match(path, i, node.path, true);
+      if (!result.match) continue;
+
+      Object.assign(outParams, result.params);
+      for (const mw of this.middleware) outMiddleware.push(mw);
+
+      return handler;
+    }
+  }
+
+  getHandler(pathname: string, method: string): InternalHandler | undefined {
+    method = method.toUpperCase();
+    const path = pathname.split("/");
+    if (path[0] == "") path.shift();
+    if (path[path.length - 1] == "") path.pop();
+
+    let i = 0;
+
+    const params: Record<string, any> = {};
+    const middleware: MiddlewareHandler[] = [];
+
+    if (this.basePath) {
+      const result = match(path, i, this.basePath, false);
+      if (!result.match) return;
+      Object.assign(params, result.params);
+      i = result.stopped_at;
+    }
+
+    const handler = this.internalGetHandler(path, i, method, {}, []);
+    if (!handler) return;
+    return Graph.compose(handler, params, middleware);
+  }
+
+  /**
+   * Composes middleware and route handler into an executable internal handler.
+   *
+   * @param handler Final route handler.
+   * @param params Route params.
+   * @param middlewareSet Middleware chain.
+   * @returns Internal handler.
+   */
+  static compose(
+    handler: RouteHandler,
+    params: Record<string, unknown>,
+    middlewareSet: readonly MiddlewareHandler[],
+  ): InternalHandler {
+    const middleware = middlewareSet.values();
+    return (state, req, reporter) => {
+      const createNext = (): InternalHandler => (nextState, req, reporter) => {
+        Object.assign(state, nextState);
+        const { done, value: currentMiddleware } = middleware.next();
+        let currentHandler: InternalHandler;
+        if (done) {
+          currentHandler = RouteContext.useRouteHandler(
+            handler,
+            params,
+            reporter,
+          );
+        } else {
+          currentHandler = MiddlewareContext.useMiddlewareHandler(
+            currentMiddleware,
+            params,
+            createNext(),
+            reporter,
+          );
+        }
+
+        return currentHandler(state, req, reporter);
+      };
+      return createNext()(state, req, reporter);
+    };
+  }
+}