@bepalo/router 1.11.32 → 1.12.34

package/src/tree.ts

@@ -0,0 +1,139 @@
+export class TreeNode<V> {
+  children: Map<string, TreeNode<V>> = new Map();
+  constructor(public value?: V) {}
+}
+
+type TreeObj<V> = Record<string, V | Record<string, V>>;
+
+function getTreeObj<V>(
+  node: TreeNode<V>,
+  onHit?: (node: TreeNode<V>) => void,
+): TreeObj<V> {
+  const obj: TreeObj<V> = {};
+  if (node.value) {
+    obj[""] = node.value;
+    if (onHit) {
+      onHit(node);
+    }
+  }
+  for (const [keyPart, child] of node.children) {
+    obj[keyPart] = getTreeObj(child, onHit) as Record<string, V>;
+  }
+  return obj;
+}
+
+export class Tree<V> {
+  #root?: TreeNode<V>;
+
+  get root(): TreeNode<V> | undefined {
+    return this.#root;
+  }
+
+  tree(onHit?: (node: TreeNode<V>) => void): TreeObj<V> {
+    const tr: TreeObj<V> = this.#root ? getTreeObj(this.#root, onHit) : {};
+    return tr;
+  }
+
+  constructor() {}
+
+  getAll(key: Array<string>): Array<V> {
+    let node = this.#root;
+    const values: Array<V> = [];
+    const klen_1 = key.length - 1;
+    for (let i = 0; i < key.length && node != null; i++) {
+      const keyPart = key[i];
+      if (keyPart !== "") {
+        const superGlob = node.children.get("**");
+        if (superGlob?.value != null) {
+          values.unshift(superGlob.value);
+        }
+      }
+      if (i < klen_1) {
+        let nextNode = node.children.get(keyPart);
+        if (nextNode == null) {
+          nextNode = node.children.get("*");
+        }
+        node = nextNode;
+      } else {
+        const glob = node.children.get("*");
+        if (glob?.value) values.unshift(glob.value);
+        const value = node.children.get(keyPart)?.value;
+        if (value) values.unshift(value);
+        break;
+      }
+    }
+    return values;
+  }
+
+  get(key: Array<string>): V | undefined {
+    let node = this.#root;
+    const klen_1 = key.length - 1;
+    for (let i = 0; i < key.length && node != null; i++) {
+      const keyPart = key[i];
+      if (i < klen_1) {
+        let nextNode = node.children.get(keyPart);
+        if (nextNode == null) {
+          nextNode = node.children.get("*");
+        }
+        node = nextNode;
+      } else {
+        const value =
+          node.children.get(keyPart)?.value ?? node.children.get("*")?.value;
+        return value;
+      }
+    }
+    return undefined;
+  }
+
+  has(key: Array<string>): boolean {
+    let node = this.#root;
+    const klen_1 = key.length - 1;
+    for (let i = 0; i < key.length && node != null; i++) {
+      const keyPart = key[i];
+      if (i < klen_1) {
+        let nextNode = node.children.get(keyPart);
+        if (nextNode == null) {
+          nextNode = node.children.get("*");
+        }
+        node = nextNode;
+      } else {
+        return node.children.get(keyPart)?.value != null;
+      }
+    }
+    return false;
+  }
+
+  set(key: Array<string>, value: V): void {
+    if (this.#root == null) {
+      this.#root = new TreeNode();
+    }
+    let node = this.#root;
+    const klen_1 = key.length - 1;
+    for (let i = 0; i < key.length; i++) {
+      if (i < klen_1) {
+        const keyPart = key[i];
+        const curNode = node.children.get(keyPart);
+        if (!curNode) {
+          const newNode = new TreeNode<V>();
+          node.children.set(keyPart, newNode);
+          node = newNode;
+        } else {
+          node = curNode;
+        }
+      } else {
+        const keyPart = key[i];
+        const curNode = node.children.get(keyPart);
+        if (curNode) {
+          curNode.value = value;
+          node = curNode;
+        } else {
+          const newNode = new TreeNode<V>(value);
+          node.children.set(keyPart, newNode);
+          node = newNode;
+        }
+      }
+    }
+  }
+}
+
+export default Tree;

package/src/types.ts

@@ -0,0 +1,197 @@
+import Router, { RouterContext } from "./router.ts";
+
+/**
+ * Standard HTTP methods supported by the router.
+ * These methods correspond to HTTP/1.1 request methods.
+ *
+ * @typedef {"HEAD"|"OPTIONS"|"GET"|"POST"|"PUT"|"PATCH"|"DELETE"} HttpMethod
+ *
+ * @example
+ * const method: HttpMethod = "GET";
+ * const method: HttpMethod = "POST";
+ */
+export type HttpMethod =
+  | "HEAD"
+  | "OPTIONS"
+  | "GET"
+  | "POST"
+  | "PUT"
+  | "PATCH"
+  | "DELETE";
+
+/**
+ * HTTP path pattern type.
+ * Represents valid HTTP paths starting with a forward slash.
+ *
+ * @typedef {`/${string}`} HttpPath
+ *
+ * @example
+ * const path: HttpPath = "/";
+ * const path: HttpPath = "/api/users";
+ * const path: HttpPath = "/users/:id";
+ * const path: HttpPath = "/static/**";
+ */
+export type HttpPath = `/${string}`;
+
+/**
+ * Combined HTTP method and path pattern.
+ * Used for route registration with method-specific routing.
+ *
+ * @typedef {`${HttpMethod} ${HttpPath}`} MethodPath
+ *
+ * @example
+ * const route: MethodPath = "GET /api/users";
+ * const route: MethodPath = "POST /api/users";
+ * const route: MethodPath = "DELETE /api/users/:id";
+ */
+export type MethodPath = `${HttpMethod | "ALL" | "CRUD"} ${HttpPath}`;
+
+/**
+ * Types of handlers in the router pipeline.
+ * Each handler type has a specific role in request processing:
+ * - `filter`: Runs before handlers, can intercept requests
+ * - `hook`: Runs before filters, can't return responses
+ * - `handler`: Main request handlers
+ * - `fallback`: Runs when no handler matches
+ * - `catcher`: Error handlers for exceptions
+ * - `after`: Runs after response is created
+ *
+ * @typedef {"filter"|"hook"|"handler"|"fallback"|"catcher"|"after"} HandlerType
+ *
+ */
+export type HandlerType =
+  | "filter"
+  | "hook"
+  | "handler"
+  | "fallback"
+  | "catcher"
+  | "after";
+
+/**
+ * Possible return types from route handlers.
+ * Handlers can:
+ * - Return a Response object to send immediately
+ * - Return void/undefined to continue to next handler
+ * - Return false to stop processing (for filters)
+ * - Return a Promise of any of the above
+ *
+ * @typedef {Response|void|boolean|Promise<Response|void|boolean>} HandlerResponse
+ *
+ * @example
+ * // Return a Response
+ * (req, ctx) => new Response("Hello");
+ *
+ * // Return void (continue)
+ * (req, ctx) => { ctx.user = getUser(); }
+ *
+ * // Return false (stop processing)
+ * (req, ctx) => { if (!authorized) return false; }
+ *
+ * // Return Promise
+ * async (req, ctx) => {
+ *   const data = await fetchData();
+ *   return json(data);
+ * }
+ */
+export type HandlerResponse =
+  | Response
+  | void
+  | boolean
+  | Promise<Response | void | boolean>;
+
+export type BoundHandler<XContext = {}> = (
+  this: Router<XContext>,
+  req: Request,
+  ctx: RouterContext<XContext>,
+) => HandlerResponse;
+
+export type FreeHandler<XContext = {}> = (
+  req: Request,
+  ctx: RouterContext<XContext>,
+) => HandlerResponse;
+
+/**
+ * Generic handler function type.
+ * Represents a function that processes HTTP requests.
+ *
+ * @template Context - The context type available to the handler
+ * @callback Handler
+ * @param {Request} req - The incoming HTTP request
+ * @param {Context} ctx - The request context with params, headers, etc.
+ * @returns {HandlerResponse} The handler's response
+ *
+ * @example
+ * // Simple handler that returns JSON
+ * const userHandler: Handler<MyContext> = async (req, ctx) => {
+ *   const users = await getUsers();
+ *   return json(users);
+ * };
+ *
+ * @example
+ * // Handler that modifies context and continues
+ * const authHandler: Handler<MyContext> = (req, ctx) => {
+ *   const token = req.headers.get("Authorization");
+ *   if (token) {
+ *     ctx.user = decodeToken(token);
+ *   }
+ *   // Return nothing to continue to next handler
+ * };
+ */
+export type Handler<XContext = {}> =
+  | FreeHandler<XContext>
+  | BoundHandler<XContext>;
+
+/**
+ * Array of handler functions executed in sequence.
+ * Used to group multiple handlers for a route.
+ *
+ * @template Context - The context type available to handlers
+ * @typedef {Array<Handler<Context>>} Pipeline
+ *
+ * @example
+ * // Pipeline with multiple handlers
+ * const userPipeline: Pipeline<MyContext> = [
+ *   rateLimiter,       // Apply rate limiting
+ *   authMiddleware,    // Check authentication
+ *   validateInput,     // Validate request body
+ *   userHandler        // Main request logic
+ * ];
+ *
+ * @example
+ * // Register pipeline with router
+ * router.handle("GET /users", userPipeline);
+ */
+export type Pipeline<Context = {}> = Array<Handler<Context>>;
+
+/**
+ * HTTP header tuple.
+ *
+ * @typedef {[string, string]} HeaderTuple
+ *
+ */
+export type HeaderTuple = [string, string];
+
+/**
+ * Generic SocketAddress structure
+ *
+ * @typedef {{address:string;family:string;port:number;}} SocketAddress
+ */
+export interface SocketAddress {
+  address: string;
+  family: string;
+  port: number;
+}
+
+/**
+ * Router Context for certain error
+ *
+ * @typedef {{error:Error}} CTXError
+ */
+export type CTXError = { error: Error };
+
+/**
+ * Router Context for sharing client address
+ *
+ * @typedef {{address:SocketAddress}} CTXAddress
+ */
+export type CTXAddress = { address: SocketAddress };