@rangojs/router 0.0.0-experimental.bd6e11bc → 0.0.0-experimental.bdaf10aa

package/src/router/middleware-types.ts

@@ -1,10 +1,3 @@
-/**
- * Middleware Types
- *
- * Type definitions and interfaces for the middleware system.
- * Separated from execution logic for cleaner imports.
- */
-
 import type { ContextVar } from "../context-var.js";
 import type {
   DefaultReverseRouteMap,
@@ -16,17 +9,11 @@ import type { Theme } from "../theme/types.js";
 import type { LocationStateEntry } from "../browser/react/location-state-shared.js";
 import type { RequestScope } from "../types/request-scope.js";
 
-/**
- * Get variable function type
- */
 type GetVariableFn = {
   <T>(contextVar: ContextVar<T>): T | undefined;
   <K extends keyof DefaultVars>(key: K): DefaultVars[K];
 };
 
-/**
- * Set variable function type
- */
 type SetVariableFn = {
   <T>(contextVar: ContextVar<T>, value: T, options?: { cache?: boolean }): void;
   <K extends keyof DefaultVars>(
@@ -36,9 +23,6 @@ type SetVariableFn = {
   ): void;
 };
 
-/**
- * Cookie options for setting cookies
- */
 export interface CookieOptions {
   domain?: string;
   path?: string;
@@ -49,109 +33,36 @@ export interface CookieOptions {
   sameSite?: "strict" | "lax" | "none";
 }
 
-/**
- * Context passed to middleware
- *
- * @template TEnv - Environment type (bindings, variables) - defaults to any for internal flexibility
- * @template TParams - URL params type (typed for route middleware,
- *   `Record<string, string | undefined>` for global middleware — absent
- *   optional segments are omitted from the params record at runtime, so
- *   the index signature must include `undefined`)
- */
 export interface MiddlewareContext<
   TEnv = any,
   TParams = Record<string, string | undefined>,
 > extends RequestScope<TEnv> {
-  /** URL params extracted from route/middleware pattern */
   params: TParams;
 
-  /**
-   * Response headers.
-   * Before `next()`, returns headers from the shared response stub.
-   * After `next()`, returns headers from the downstream response.
-   */
   readonly headers: Headers;
 
-  /** Get a context variable (shared with route handlers) */
   get: GetVariableFn;
 
-  /** Set a context variable (shared with route handlers) */
   set: SetVariableFn;
 
-  /**
-   * Set a response header - can be called before or after `next()`.
-   *
-   * When called before `next()`, headers are queued and merged into the final response.
-   * When called after `next()`, headers are set directly on the response.
-   */
   header(name: string, value: string): void;
 
-  /**
-   * The matched route name, if available and the route has an explicit name.
-   * Undefined for global middleware (runs before route matching) or unnamed routes.
-   */
   routeName?: DefaultRouteName;
 
-  /**
-   * Enable performance metrics for this request.
-   * When called, granular timing breakdown is logged to console and
-   * included in the Server-Timing response header, regardless of the
-   * router-level `debugPerformance` option.
-   *
-   * Call **before** `await next()` so the metrics store exists when
-   * downstream phases (route matching, rendering, SSR) record their
-   * spans. Calling after `next()` returns still emits `handler:total`
-   * but misses all upstream metrics.
-   */
   debugPerformance(): void;
 
-  /**
-   * Current theme (from cookie or default).
-   * Only available when theme is enabled in router config.
-   */
   theme?: Theme;
 
-  /**
-   * Set the theme (only available when theme is enabled in router config).
-   * Sets a cookie with the new theme value.
-   */
   setTheme?: (theme: Theme) => void;
 
-  /**
-   * Attach location state entries to this response.
-   * State is delivered to the client via history.pushState and accessible
-   * through the useLocationState() hook.
-   */
   setLocationState(entries: LocationStateEntry | LocationStateEntry[]): void;
 
-  /**
-   * Generate URLs from route names.
-   * - `name` — global route, from the named-routes definition
-   */
   reverse: ScopedReverseFunction<
     Record<string, string>,
     DefaultReverseRouteMap
   >;
 }
 
-/**
- * Middleware function signature
- *
- * @template TEnv - Environment type - defaults to any for internal flexibility
- * @template TParams - URL params type (typed for route middleware)
- *
- * When using middleware with global augmentation (Rango.Env), explicitly
- * annotate your middleware functions, or the types will be inferred from context:
- *
- * @example
- * ```typescript
- * // With explicit annotation (recommended for reusable middleware)
- * const authMiddleware: MiddlewareFn<AppEnv> = async (ctx, next) => {...}
- *
- * // Types inferred from router.use() call
- * router.use((ctx, next) => {...}) // ctx is typed from router's TEnv
- * ```
- */
 export type MiddlewareFn<
   TEnv = any,
   TParams = Record<string, string | undefined>,
@@ -160,50 +71,23 @@ export type MiddlewareFn<
   next: () => Promise<Response>,
 ) => Response | void | Promise<Response | void>;
 
-/**
- * Stored middleware entry with pattern matching info
- * @internal - uses any for internal flexibility
- */
 export interface MiddlewareEntry<TEnv = any> {
-  /** Original pattern string */
   pattern: string | null;
-
-  /** Compiled regex for matching */
   regex: RegExp | null;
-
-  /** Param names extracted from pattern */
   paramNames: string[];
-
-  /** The middleware function */
   handler: MiddlewareFn<TEnv>;
-
-  /** Mount prefix this middleware is scoped to (null = global) */
-  mountPrefix: string | null;
 }
 
-/**
- * Mutable response holder - tracks the current response through the middleware chain.
- */
 export interface ResponseHolder {
   response: Response | null;
 }
 
-/**
- * Entry type for middleware collection
- * Matches the shape of EntryData used in router.ts
- */
 export interface MiddlewareCollectableEntry {
   middleware?: MiddlewareFn<any, any>[];
   layout?: MiddlewareCollectableEntry[];
 }
 
-/**
- * Collected route middleware with params
- */
 export interface CollectedMiddleware {
   handler: MiddlewareFn<any, any>;
-  // Internal shape only. The user-facing `MiddlewareContext.params` is
-  // typed `Record<string, string | undefined>` to reflect that absent
-  // optional segments are omitted from the params record at runtime.
   params: Record<string, string>;
 }