@reckona/mreact-router 0.0.160 → 0.0.162

package/src/logger.ts

@@ -1,7 +1,16 @@
+/**
+ * Names the severity channel used for app-router structured logs.
+ */
 export type AppRouterLogLevel = "debug" | "info" | "warn" | "error";
 
+/**
+ * Names the runtime that handled an app-router request.
+ */
 export type AppRouterRuntime = "aws-lambda" | "cloudflare" | "edge" | "node";
 
+/**
+ * Receives structured app-router log events by severity.
+ */
 export interface AppRouterLogger {
   debug?: ((event: AppRouterLogEvent) => void | Promise<void>) | undefined;
   error?: ((event: AppRouterLogEvent) => void | Promise<void>) | undefined;
@@ -9,6 +18,9 @@ export interface AppRouterLogger {
   warn?: ((event: AppRouterLogEvent) => void | Promise<void>) | undefined;
 }
 
+/**
+ * Represents every structured log event emitted by the app router.
+ */
 export type AppRouterLogEvent =
   | AppRouterRequestStartLogEvent
   | AppRouterRequestEndLogEvent
@@ -17,6 +29,9 @@ export type AppRouterLogEvent =
   | AppRouterRenderTimingLogEvent
   | AppRouterCspInlineNonceWarningLogEvent;
 
+/**
+ * Logs the start of an app-router request.
+ */
 export interface AppRouterRequestStartLogEvent {
   method: string;
   path: string;
@@ -24,6 +39,9 @@ export interface AppRouterRequestStartLogEvent {
   type: "router:request:start";
 }
 
+/**
+ * Logs the successful completion of an app-router request.
+ */
 export interface AppRouterRequestEndLogEvent {
   durationMs: number;
   method: string;
@@ -33,6 +51,9 @@ export interface AppRouterRequestEndLogEvent {
   type: "router:request:end";
 }
 
+/**
+ * Logs a request that ended with an app-router error response.
+ */
 export interface AppRouterRequestErrorLogEvent {
   durationMs: number;
   error: AppRouterLogError;
@@ -42,6 +63,9 @@ export interface AppRouterRequestErrorLogEvent {
   type: "router:request:error";
 }
 
+/**
+ * Logs per-phase timings for a complete app-router request.
+ */
 export interface AppRouterRequestTimingLogEvent {
   durationMs: number;
   method: string;
@@ -52,6 +76,9 @@ export interface AppRouterRequestTimingLogEvent {
   type: "router:request:timing";
 }
 
+/**
+ * Logs per-phase timings for route rendering.
+ */
 export interface AppRouterRenderTimingLogEvent {
   method: string;
   path: string;
@@ -60,6 +87,9 @@ export interface AppRouterRenderTimingLogEvent {
   type: "router:render:timing";
 }
 
+/**
+ * Logs an inline CSP nonce warning emitted while rendering a route.
+ */
 export interface AppRouterCspInlineNonceWarningLogEvent {
   directive: "script-src" | "style-src";
   path: string;
@@ -67,6 +97,9 @@ export interface AppRouterCspInlineNonceWarningLogEvent {
   type: "router:csp:inline-nonce-warning";
 }
 
+/**
+ * Serializes an error for app-router structured logs.
+ */
 export interface AppRouterLogError {
   message: string;
   name: string;

package/src/multipart.ts

@@ -1,14 +1,23 @@
+/**
+ * Configures multipart stream parsing limits and field handling.
+ */
 export interface MultipartStreamParseOptions {
   fields?: Readonly<Record<string, MultipartStreamFieldOptions>>;
   maxParts?: number;
   maxBytes?: number;
 }
 
+/**
+ * Configures parsing behavior for a named multipart field.
+ */
 export interface MultipartStreamFieldOptions {
   type?: "stream" | "text";
   maxBytes?: number;
 }
 
+/**
+ * Represents one parsed multipart field or file part.
+ */
 export interface MultipartStreamPart {
   name: string;
   filename?: string;
@@ -21,6 +30,9 @@ export interface MultipartStreamPart {
   fixedLengthStream(length?: number | bigint): MultipartFixedLengthStream;
 }
 
+/**
+ * Couples a readable multipart part stream with a completion signal.
+ */
 export interface MultipartFixedLengthStream {
   readable: ReadableStream<Uint8Array<ArrayBufferLike>>;
   done: Promise<void>;
@@ -39,6 +51,9 @@ const maxHeaderBytes = 64 * 1024;
 export const defaultMultipartMaxBytes = 10 * 1024 * 1024;
 export const defaultMultipartMaxParts = 1_000;
 
+/**
+ * Parses a multipart request body as an async iterable of streamable parts.
+ */
 export function parseMultipartStream(
   request: Request,
   options: MultipartStreamParseOptions = {},

package/src/native-escape.ts

@@ -9,6 +9,9 @@ interface NativeEscapeModule {
 let nativeModule: NativeEscapeModule | false | undefined;
 let nativeRequire: ReturnType<typeof createRequire> | false | undefined;
 
+/**
+ * Escapes a batch of values as HTML text using the native helper when available.
+ */
 export function escapeHtmlBatch(values: readonly unknown[]): string[] {
   const strings = values.map((value) => String(value ?? ""));
   const native = loadNativeEscapeModule();

package/src/navigation-state.ts

@@ -1,5 +1,11 @@
+/**
+ * Names the client navigation operation that produced the current router state.
+ */
 export type AppRouterNavigationType = "push" | "replace" | "pop" | "refresh";
 
+/**
+ * Describes the latest client-side app-router navigation state.
+ */
 export interface AppRouterNavigationState {
   pending: boolean;
   from: string | null;
@@ -7,6 +13,9 @@ export interface AppRouterNavigationState {
   type: AppRouterNavigationType | null;
 }
 
+/**
+ * Receives app-router client navigation state updates.
+ */
 export type AppRouterNavigationStateListener = (
   state: AppRouterNavigationState,
 ) => void;
@@ -18,6 +27,9 @@ const idleNavigationState: AppRouterNavigationState = {
   type: null,
 };
 
+/**
+ * Reads the current client navigation state snapshot.
+ */
 export function getNavigationState(): AppRouterNavigationState {
   const runtimeState = (globalThis as {
     __mreactNavigationState?: { current?: unknown };
@@ -31,6 +43,9 @@ export function getNavigationState(): AppRouterNavigationState {
   return navigationStateFromDocument();
 }
 
+/**
+ * Subscribes to app-router client navigation state changes.
+ */
 export function subscribeNavigationState(
   listener: AppRouterNavigationStateListener,
 ): () => void {

package/src/navigation.ts

@@ -11,6 +11,9 @@ export interface RedirectOptions {
 
 export type MiddlewareNext = undefined;
 
+/**
+ * Describes a parser used by `parseForm()` to validate submitted form data.
+ */
 export interface ParseSchema<T> {
   parse(value: FormData): T;
 }
@@ -270,12 +273,18 @@ export function rewriteLocation(response: Response): string | undefined {
   return candidate !== undefined && isSafeInternalRedirect(candidate) ? candidate : undefined;
 }
 
+/**
+ * Checks whether an unknown error is an app-router redirect signal.
+ */
 export function isRedirectError(error: unknown): error is Error & { location: string; status: number } {
   return error instanceof Error &&
     error.name === redirectErrorName &&
     typeof (error as { location?: unknown }).location === "string";
 }
 
+/**
+ * Checks whether an unknown error is an app-router not-found signal.
+ */
 export function isNotFoundError(error: unknown): boolean {
   return error instanceof Error && error.name === notFoundErrorName;
 }

package/src/prerender-store.ts

@@ -4,6 +4,9 @@ import { dirname, join } from "node:path";
 import type { BuiltPrerenderedRoute } from "./build.js";
 import type { AppRouterPrerenderStore } from "./serve.js";
 
+/**
+ * Configures the process-local prerender store used for cached prerendered routes.
+ */
 export interface MemoryPrerenderStoreOptions {
   backing?: Map<string, MemoryPrerenderStoreEntry>;
   maxEntries?: number;
@@ -18,6 +21,9 @@ export interface MemoryPrerenderStoreEntry {
   lastAccessedAt: number;
 }
 
+/**
+ * Configures a filesystem-backed prerender store.
+ */
 export interface FileSystemPrerenderStoreOptions {
   directory: string;
   lockPollMs?: number;
@@ -25,6 +31,9 @@ export interface FileSystemPrerenderStoreOptions {
   namespace?: string;
 }
 
+/**
+ * Defines the adapter API used by key-value prerender stores.
+ */
 export interface KeyValuePrerenderStoreAdapter {
   delete(key: string): void | Promise<void>;
   get(key: string): string | undefined | Promise<string | undefined>;
@@ -32,12 +41,18 @@ export interface KeyValuePrerenderStoreAdapter {
   withLock?<T>(key: string, task: (token: string) => Promise<T>): Promise<T>;
 }
 
+/**
+ * Configures a key-value-backed prerender store.
+ */
 export interface KeyValuePrerenderStoreOptions {
   adapter: KeyValuePrerenderStoreAdapter;
   namespace?: string;
   ttlMs?: number;
 }
 
+/**
+ * Creates an in-memory prerender store with optional TTL and LRU eviction.
+ */
 export function createMemoryPrerenderStore(
   options: MemoryPrerenderStoreOptions = {},
 ): AppRouterPrerenderStore {
@@ -100,6 +115,9 @@ export function createMemoryPrerenderStore(
   };
 }
 
+/**
+ * Creates a prerender store that persists entries as JSON files.
+ */
 export function createFileSystemPrerenderStore(
   options: FileSystemPrerenderStoreOptions,
 ): AppRouterPrerenderStore {
@@ -162,6 +180,9 @@ export function createFileSystemPrerenderStore(
   };
 }
 
+/**
+ * Creates a prerender store backed by a caller-provided key-value adapter.
+ */
 export function createKeyValuePrerenderStore(
   options: KeyValuePrerenderStoreOptions,
 ): AppRouterPrerenderStore {

package/src/render.ts

@@ -163,6 +163,9 @@ interface RenderTiming {
   phases: Record<string, number>;
 }
 
+/**
+ * Configures server rendering for a source app-router request.
+ */
 export interface RenderAppRequestOptions {
   appDir: string;
   assetBaseUrl?: string | undefined;
@@ -204,11 +207,17 @@ export interface AppRouterRenderPreload {
   wait: "before-render";
 }
 
+/**
+ * Allows callers to inspect or replace an app-router response before it is returned.
+ */
 export type AppRouterResponseHook = (
   response: Response,
   context: AppRouterResponseHookContext,
 ) => Response | undefined | void | Promise<Response | undefined | void>;
 
+/**
+ * Provides request context to an app-router response hook.
+ */
 export interface AppRouterResponseHookContext {
   request: Request;
 }
@@ -603,6 +612,9 @@ interface RouteSourceAnalysis {
   usesRuntimeCacheControl: boolean;
 }
 
+/**
+ * Renders a source app-router request into a `Response`.
+ */
 export async function renderAppRequest(options: RenderAppRequestOptions): Promise<Response> {
   const authStorage = authRequestStorage();
 

package/src/routes.ts

@@ -6,12 +6,21 @@ import {
   type AppFileConvention,
 } from "./file-conventions.js";
 
+/**
+ * Configures app route discovery from a routes directory.
+ */
 export interface ScanAppRoutesOptions {
   appDir: string;
 }
 
+/**
+ * Represents any route discovered by the app-router file-system scanner.
+ */
 export type AppRoute = AppAssetRoute | AppMetadataRoute | PageRoute | ServerRoute;
 
+/**
+ * Describes a page route that renders a component.
+ */
 export interface PageRoute {
   kind: "page";
   path: string;
@@ -19,6 +28,9 @@ export interface PageRoute {
   segments: RouteSegment[];
 }
 
+/**
+ * Describes a server route that handles HTTP methods directly.
+ */
 export interface ServerRoute {
   kind: "server";
   path: string;
@@ -26,6 +38,9 @@ export interface ServerRoute {
   segments: RouteSegment[];
 }
 
+/**
+ * Describes a generated metadata route such as robots or sitemap.
+ */
 export interface AppMetadataRoute {
   convention: AppFileConvention;
   kind: "metadata";
@@ -34,6 +49,9 @@ export interface AppMetadataRoute {
   segments: RouteSegment[];
 }
 
+/**
+ * Describes a static asset route produced from an app file convention.
+ */
 export interface AppAssetRoute {
   convention: AppFileConvention;
   kind: "asset";
@@ -42,11 +60,17 @@ export interface AppAssetRoute {
   segments: RouteSegment[];
 }
 
+/**
+ * Represents a static, dynamic, or catch-all segment in an app route path.
+ */
 export type RouteSegment =
   | { kind: "static"; value: string }
   | { kind: "dynamic"; name: string }
   | { kind: "catch-all"; name: string };
 
+/**
+ * Holds the route and params selected for a request pathname.
+ */
 export interface MatchedRoute {
   route: AppRoute;
   params: Record<string, readonly string[] | string>;
@@ -56,6 +80,9 @@ export interface RouteMatcher {
   match(pathname: string): MatchedRoute | undefined;
 }
 
+/**
+ * Scans an app directory and returns sorted app-router route definitions.
+ */
 export async function scanAppRoutes(
   options: ScanAppRoutesOptions,
 ): Promise<AppRoute[]> {
@@ -84,6 +111,9 @@ export async function scanAppRoutes(
     .sort(compareRouteListEntries);
 }
 
+/**
+ * Matches a request pathname against a route list.
+ */
 export function matchRoute(
   routes: readonly AppRoute[],
   pathname: string,

package/src/runtime-cache.ts

@@ -1,8 +1,13 @@
 import { routerModuleRunnerRuntimeCacheStats } from "./module-runner.js";
 import { routerRenderRuntimeCacheStats } from "./render.js";
 import type { RouterRuntimeCacheStat } from "./cache-stats.js";
+
+/** Reports a named runtime cache and its current entry count. */
 export type { RouterRuntimeCacheStat } from "./cache-stats.js";
 
+/**
+ * Reads app-router runtime cache sizes for diagnostics.
+ */
 export function getRouterRuntimeCacheStats(): RouterRuntimeCacheStat[] {
   return [...routerRenderRuntimeCacheStats(), ...routerModuleRunnerRuntimeCacheStats()];
 }

package/src/runtime-state.ts

@@ -3,6 +3,9 @@ type RuntimeStateRoot = Record<string, unknown>;
 
 const namespace = "__mreactRouterRuntimeState";
 
+/**
+ * Reads or initializes shared server runtime state stored on `globalThis`.
+ */
 export function getServerRuntimeState<TState extends object>(
   key: string,
   create: () => TState,

package/src/serve.ts

@@ -119,10 +119,16 @@ interface BuiltPublicAsset {
  * that on your workload.
  */
 export type ResponseSinkStrategy = "string" | "buffer";
+/**
+ * Controls whether built request handling trusts the incoming Host header.
+ */
 export type RequestHostPolicy = "strict" | "trusted-proxy";
 
 let warnedImplicitHostTrust = false;
 
+/**
+ * Configures rendering a request against a built app-router output directory.
+ */
 export interface RenderBuiltAppRequestOptions {
   outDir: string;
   importPolicy?: AppRouterImportPolicy | undefined;
@@ -159,6 +165,9 @@ export interface BuiltRequestRuntime {
   ): Promise<Response>;
 }
 
+/**
+ * Selects which built runtime modules should be preloaded.
+ */
 export type BuiltAppRuntimePreloadMode =
   | "all"
   | "hot-route-requests"
@@ -166,11 +175,17 @@ export type BuiltAppRuntimePreloadMode =
   | "middleware"
   | "none";
 
+/**
+ * Configures built app runtime preload scope and optional hot routes.
+ */
 export interface BuiltAppRuntimePreloadStrategy {
   mode: BuiltAppRuntimePreloadMode;
   routes?: readonly string[] | undefined;
 }
 
+/**
+ * Configures the Node HTTP server used to serve a built app-router output.
+ */
 export interface StartServerOptions {
   outDir: string;
   port: number;
@@ -232,6 +247,9 @@ export function warnIfImplicitHostTrust(options: {
   );
 }
 
+/**
+ * Defines storage for prerendered route responses used by built request rendering.
+ */
 export interface AppRouterPrerenderStore {
   delete(path: string): void | Promise<void>;
   get(path: string): BuiltPrerenderedRoute | undefined | Promise<BuiltPrerenderedRoute | undefined>;
@@ -277,6 +295,9 @@ export async function createBuiltRequestRuntime(
   };
 }
 
+/**
+ * Preloads selected modules from a built app-router runtime.
+ */
 export async function preloadBuiltAppRuntime(options: {
   importPolicy?: AppRouterImportPolicy | undefined;
   outDir: string;
@@ -363,6 +384,9 @@ function builtRuntimePreloadRoutes(
   });
 }
 
+/**
+ * Renders a request using a built app-router output directory.
+ */
 export async function renderBuiltAppRequest(
   options: RenderBuiltAppRequestOptions,
 ): Promise<Response> {

package/src/session.ts

@@ -1,5 +1,8 @@
 import { deleteCookie, parseCookieHeader, setCookie } from "./cookies.js";
 
+/**
+ * Stores session data and expiration metadata for one session id.
+ */
 export interface SessionRecord<TData = unknown> {
   createdAt: number;
   data: TData;
@@ -8,17 +11,26 @@ export interface SessionRecord<TData = unknown> {
   rotatedAt?: number;
 }
 
+/**
+ * Defines the persistence API used by app-router session helpers.
+ */
 export interface SessionStore<TData = unknown> {
   delete(id: string): void | Promise<void>;
   get(id: string): SessionRecord<TData> | undefined | Promise<SessionRecord<TData> | undefined>;
   set(record: SessionRecord<TData>): void | Promise<void>;
 }
 
+/**
+ * Configures the process-local memory session store.
+ */
 export interface MemorySessionStoreOptions {
   maxEntries?: number;
   sweepIntervalMs?: number;
 }
 
+/**
+ * Configures the cookie used by app-router session helpers.
+ */
 export interface SessionCookieOptions {
   cookieName?: string;
   maxAgeSeconds?: number;

package/src/stream-list.ts

@@ -1,3 +1,6 @@
+/**
+ * Represents one resolved batch emitted by `streamList()`.
+ */
 export interface StreamListBatch<TItem> {
   index: number;
   items: TItem[];
@@ -5,6 +8,9 @@ export interface StreamListBatch<TItem> {
   start: number;
 }
 
+/**
+ * Represents one pending batch and its eventual loaded items.
+ */
 export interface StreamListPendingBatch<TItem> {
   index: number;
   size: number;
@@ -12,6 +18,9 @@ export interface StreamListPendingBatch<TItem> {
   value: Promise<StreamListBatch<TItem>>;
 }
 
+/**
+ * Configures how a list is divided into asynchronous batches.
+ */
 export interface StreamListOptions<TInput, TItem> {
   batchSize: number;
   loadBatch: (
@@ -20,6 +29,9 @@ export interface StreamListOptions<TInput, TItem> {
   ) => PromiseLike<readonly TItem[]> | readonly TItem[];
 }
 
+/**
+ * Splits an input list into pending batches that load their items asynchronously.
+ */
 export function streamList<TInput, TItem = TInput>(
   items: readonly TInput[],
   options: StreamListOptions<TInput, TItem>,

package/src/trace.ts

@@ -1,3 +1,6 @@
+/**
+ * Represents parsed W3C trace context headers for router instrumentation.
+ */
 export interface RouterTraceContext {
   parentSpanId: string;
   sampled: boolean;
@@ -6,6 +9,9 @@ export interface RouterTraceContext {
   tracestate?: string;
 }
 
+/**
+ * Describes a router request lifecycle instrumentation event.
+ */
 export interface RouterRequestInstrumentationEvent {
   method: string;
   path: string;
@@ -13,32 +19,50 @@ export interface RouterRequestInstrumentationEvent {
   trace?: RouterTraceContext;
 }
 
+/**
+ * Describes completion of a router request lifecycle event.
+ */
 export interface RouterRequestEndInstrumentationEvent
   extends RouterRequestInstrumentationEvent {
   status: number;
 }
 
+/**
+ * Describes a route-level loader or render instrumentation event.
+ */
 export interface RouterRouteInstrumentationEvent
   extends RouterRequestInstrumentationEvent {
   routeId: string;
   routePath: string;
 }
 
+/**
+ * Describes completion of a route-level instrumentation event.
+ */
 export interface RouterRouteEndInstrumentationEvent
   extends RouterRouteInstrumentationEvent {
   error?: unknown;
 }
 
+/**
+ * Describes a middleware instrumentation event.
+ */
 export interface RouterMiddlewareInstrumentationEvent
   extends RouterRequestInstrumentationEvent {
   name: string;
 }
 
+/**
+ * Describes completion of a middleware instrumentation event.
+ */
 export interface RouterMiddlewareEndInstrumentationEvent
   extends RouterMiddlewareInstrumentationEvent {
   error?: unknown;
 }
 
+/**
+ * Registers optional hooks for app-router request, middleware, and route instrumentation.
+ */
 export interface RouterInstrumentation {
   onLoaderEnd?: (event: RouterRouteEndInstrumentationEvent) => void | Promise<void>;
   onLoaderStart?: (event: RouterRouteInstrumentationEvent) => void | Promise<void>;
@@ -48,6 +72,9 @@ export interface RouterInstrumentation {
   onRequestStart?: (event: RouterRequestInstrumentationEvent) => void | Promise<void>;
 }
 
+/**
+ * Parses W3C trace context header values for router instrumentation.
+ */
 export function parseTraceContext(
   traceparent: string | null | undefined,
   tracestate: string | null | undefined,
@@ -81,6 +108,9 @@ export function parseTraceContext(
   };
 }
 
+/**
+ * Reads trace context headers from a request.
+ */
 export function traceContextFromRequest(request: Request): RouterTraceContext | undefined {
   return parseTraceContext(request.headers.get("traceparent"), request.headers.get("tracestate"));
 }