@reckona/mreact-router 0.0.152 → 0.0.153

package/src/cache.ts

@@ -56,6 +56,11 @@ const cacheState = ((
 });
 cacheState.storage ??= new AsyncLocalStorage<RouteCacheContext>();
 
+/**
+ * Creates an in-memory route response cache for app-router rendering.
+ *
+ * The cache is process-local, evicts expired entries during reads/writes, and is suitable for development, tests, or single-process deployments that do not need shared invalidation.
+ */
 export function createMemoryRouteCache(options: MemoryRouteCacheOptions = {}): AppRouterCache {
   const maxEntries = positiveIntegerOrDefault(options.maxEntries, 10_000);
   const sweepIntervalMs = nonNegativeIntegerOrDefault(options.sweepIntervalMs, 60_000);
@@ -192,6 +197,11 @@ export function routeCachePolicyFromSource(code: string): RouteCachePolicy | und
   };
 }
 
+/**
+ * Sets the cache policy for the current app-router render.
+ *
+ * Call this during a loader or route render to override the response `Cache-Control` policy; it throws outside an active app-router request.
+ */
 export function cacheControl(options: CacheControlOptions): void {
   const activeContext = activeRouteCacheContext();
 
@@ -326,6 +336,11 @@ function requestCarriesCredentials(request: Request | undefined): boolean {
   return request.headers.has("authorization") || request.headers.has("cookie");
 }
 
+/**
+ * Invalidates cached route responses for a normalized app-router path.
+ *
+ * During a request the invalidation is scoped to that route cache context; outside a request it is queued for the next cache access.
+ */
 export function revalidatePath(path: string): void {
   const normalizedPath = normalizeRevalidationPath(path);
   const activeContext = activeRouteCacheContext();

package/src/cookies.ts

@@ -22,6 +22,11 @@ function assertAttributeValue(value: string): void {
   }
 }
 
+/**
+ * Parses a raw `Cookie` header into decoded name/value pairs.
+ *
+ * Malformed percent-encoded values are skipped so one bad cookie does not abort request handling.
+ */
 export function parseCookieHeader(
   cookieHeader: string | null | undefined,
 ): Map<string, string> {
@@ -50,6 +55,11 @@ export function parseCookieHeader(
   return values;
 }
 
+/**
+ * Serializes a cookie name, value, and attributes for a `Set-Cookie` header.
+ *
+ * Cookie names and attribute values are validated, and `SameSite=None` requires `Secure`.
+ */
 export function serializeCookie(
   name: string,
   value: string,
@@ -91,6 +101,9 @@ export function serializeCookie(
   return parts.join("; ");
 }
 
+/**
+ * Appends a serialized cookie to a response's `Set-Cookie` headers and returns the same response.
+ */
 export function setCookie(
   response: Response,
   name: string,
@@ -101,6 +114,9 @@ export function setCookie(
   return response;
 }
 
+/**
+ * Appends an expiring `Set-Cookie` header that removes a cookie in the browser.
+ */
 export function deleteCookie(
   response: Response,
   name: string,

package/src/dev-server.ts

@@ -33,6 +33,11 @@ export interface StartDevServerOptions extends AppRouterProjectOptions {
   onUpgrade?: HttpUpgradeHandler | undefined;
 }
 
+/**
+ * Starts the local app-router development server with Vite middleware and route compilation.
+ *
+ * The server trusts only the configured host settings, merges declared application packages into the development import policy, and returns a `close()` method that should be awaited by tests and scripts.
+ */
 export async function startDevServer(
   options: StartDevServerOptions,
 ): Promise<{ close(): Promise<void>; server: Server; url: string }> {

package/src/link.ts

@@ -39,6 +39,11 @@ export interface LinkProps<Href extends string = LinkHref> extends LinkOptions<H
   [attribute: string]: unknown;
 }
 
+/**
+ * Converts router link options into anchor attributes consumed by the client navigation runtime.
+ *
+ * Use this when rendering a custom anchor component that should still opt into mreact prefetch, scroll, reload, or transition behavior.
+ */
 export function linkProps(options: LinkOptions<string>): Record<string, string> {
   return {
     href: options.href,
@@ -61,6 +66,11 @@ export type ConcreteLinkHrefGuard<Href extends string> = [RegisteredAppRoutePath
     ? { readonly __mreactRoutePatternHrefError__: never }
     : unknown;
 
+/**
+ * Renders an app-router anchor with typed `href` support and navigation runtime attributes.
+ *
+ * In JSX it returns an anchor element compatible with the mreact runtime; during server streaming it can also write directly to an `HtmlSink`. Unsafe URL attribute values are dropped during rendering.
+ */
 export function Link<const Href extends LinkHref>(
   props: LinkProps<Href> & ConcreteLinkHrefGuard<Href>,
 ): ReactCompatElement;

package/src/middleware.ts

@@ -110,28 +110,78 @@ export function middlewareMatches(config: MiddlewareModule["config"], pathname:
 }
 
 export function parseRouteMiddlewareControl(code: string): RouteMiddlewareControl | undefined {
-  if (!/\bexport\s+const\s+middleware\s*=/.test(code)) {
+  const masked = maskCodeLiterals(code);
+  const declaration = /\bexport\s+const\s+middleware\s*=\s*\{/.exec(masked);
+
+  if (declaration === null) {
+    return undefined;
+  }
+
+  const objectStart = masked.indexOf("{", declaration.index);
+  const objectEnd = findMatchingBrace(masked, objectStart);
+
+  if (objectStart < 0 || objectEnd < 0) {
     return undefined;
   }
 
-  if (/\bmiddleware\s*=\s*\{[\s\S]*?\bskip\s*:\s*true\b/.test(code)) {
+  const maskedBody = masked.slice(objectStart + 1, objectEnd);
+  const body = code.slice(objectStart + 1, objectEnd);
+
+  if (/\bskip\s*:\s*true\b/.test(maskedBody)) {
     return { skip: true };
   }
 
-  const skipArray = /\bmiddleware\s*=\s*\{[\s\S]*?\bskip\s*:\s*\[([\s\S]*?)\]/.exec(code);
+  const skipArray = /\bskip\s*:\s*\[([\s\S]*?)\]/.exec(maskedBody);
 
   if (skipArray === null) {
     return undefined;
   }
 
+  const arrayStart = skipArray.index + skipArray[0].indexOf("[") + 1;
+  const arrayEnd = skipArray.index + skipArray[0].lastIndexOf("]");
+  const arrayBody = body.slice(arrayStart, arrayEnd);
   const ids = Array.from(
-    skipArray[1]?.matchAll(/["']([^"']+)["']/g) ?? [],
+    arrayBody.matchAll(/["']([^"']+)["']/g),
     (match) => match[1],
   ).filter((id) => id !== undefined);
 
   return ids.length === 0 ? undefined : { skip: ids };
 }
 
+function maskCodeLiterals(code: string): string {
+  return code.replace(
+    /\/\*[\s\S]*?\*\/|\/\/[^\n\r]*|"(?:\\[\s\S]|[^"\\])*"|'(?:\\[\s\S]|[^'\\])*'|`(?:\\[\s\S]|[^`\\])*`/g,
+    (match) => " ".repeat(match.length),
+  );
+}
+
+function findMatchingBrace(code: string, openIndex: number): number {
+  if (openIndex < 0) {
+    return -1;
+  }
+
+  let depth = 0;
+
+  for (let index = openIndex; index < code.length; index += 1) {
+    const char = code[index];
+
+    if (char === "{") {
+      depth += 1;
+      continue;
+    }
+
+    if (char === "}") {
+      depth -= 1;
+
+      if (depth === 0) {
+        return index;
+      }
+    }
+  }
+
+  return -1;
+}
+
 export function mergeRouteMiddlewareControls(
   controls: readonly (RouteMiddlewareControl | undefined)[],
 ): RouteMiddlewareControl | undefined {

package/src/navigation.ts

@@ -61,6 +61,11 @@ function throwUnsafeRewrite(location: string): never {
   throw new TypeError(`unsafe rewrite target: ${JSON.stringify(location)}`);
 }
 
+/**
+ * Throws an internal redirect for loaders, middleware, route handlers, or server actions.
+ *
+ * The target must be same-origin or relative; use `redirectExternal()` for trusted `http` or `https` destinations. The default status is `303`.
+ */
 export function redirect(location: string, options: RedirectOptions = {}): never {
   if (!isSafeInternalRedirect(location)) {
     throwUnsafeRedirect(location);
@@ -72,6 +77,11 @@ export function redirect(location: string, options: RedirectOptions = {}): never
   });
 }
 
+/**
+ * Throws an external redirect for trusted `http` or `https` destinations.
+ *
+ * This helper is intentionally separate from `redirect()` so off-site navigation is explicit. The default status is `307`.
+ */
 export function redirectExternal(
   location: string,
   options: RedirectOptions = {},
@@ -86,6 +96,11 @@ export function redirectExternal(
   });
 }
 
+/**
+ * Creates a same-origin `303 See Other` redirect response.
+ *
+ * Use this from route handlers when returning a `Response` is more convenient than throwing through the app-router control flow.
+ */
 export function redirect303(location: string, init: ResponseInit = {}): Response {
   if (!isSafeInternalRedirect(location)) {
     throwUnsafeRedirect(location);
@@ -101,6 +116,9 @@ export function redirect303(location: string, init: ResponseInit = {}): Response
   });
 }
 
+/**
+ * Creates a plain-text error response with a default `text/plain` content type.
+ */
 export function textError(message: string, status = 400, init: ResponseInit = {}): Response {
   const headers = new Headers(init.headers);
 
@@ -115,6 +133,11 @@ export function textError(message: string, status = 400, init: ResponseInit = {}
   });
 }
 
+/**
+ * Reads `request.formData()` and optionally validates it with a schema-like parser.
+ *
+ * Pass a schema object with `parse(FormData)` when a route handler or server action should receive typed form data.
+ */
 export async function parseForm(request: Request): Promise<FormData>;
 export async function parseForm<T>(request: Request, schema: ParseSchema<T>): Promise<T>;
 export async function parseForm<T>(
@@ -126,6 +149,11 @@ export async function parseForm<T>(
   return schema === undefined ? form : schema.parse(form);
 }
 
+/**
+ * Throws a route-level 404 control error.
+ *
+ * Use this from loaders, metadata, middleware, or route handlers when the matched route is valid but the requested resource is absent.
+ */
 export function notFound(): never {
   throw Object.assign(new Error("Not Found"), {
     name: notFoundErrorName,
@@ -133,14 +161,25 @@ export function notFound(): never {
   });
 }
 
+/**
+ * Alias for `notFound()` for codebases that prefer an explicit throwing helper name.
+ */
 export function throwNotFound(): never {
   return notFound();
 }
 
+/**
+ * Continues middleware processing without changing the request.
+ */
 export function next(): MiddlewareNext {
   return undefined;
 }
 
+/**
+ * Creates an internal rewrite response consumed by app-router middleware.
+ *
+ * The target must be a same-origin route path, query, hash, or relative URL; protocol-relative, external, and control-character targets are rejected.
+ */
 export function rewrite(location: string, init: ResponseInit = {}): Response {
   if (!isSafeInternalRedirect(location)) {
     throwUnsafeRewrite(location);
@@ -160,10 +199,16 @@ export function rewrite(location: string, init: ResponseInit = {}): Response {
   return response;
 }
 
+/**
+ * Creates a JSON response using the platform `Response.json()` implementation.
+ */
 export function json(value: unknown, init?: ResponseInit): Response {
   return Response.json(value, init);
 }
 
+/**
+ * Creates an HTML response and defaults the content type to `text/html; charset=utf-8`.
+ */
 export function html(value: string, init: ResponseInit = {}): Response {
   if (init.headers === undefined) {
     return new Response(value, {
@@ -184,6 +229,9 @@ export function html(value: string, init: ResponseInit = {}): Response {
   });
 }
 
+/**
+ * Returns the request headers object for route code that follows app-router helper naming.
+ */
 export function headers(request: Request): Headers {
   return request.headers;
 }
@@ -194,6 +242,11 @@ export interface RequestCookies {
   has(name: string): boolean;
 }
 
+/**
+ * Parses request cookies into a small read-only helper.
+ *
+ * Values are decoded with `decodeURIComponent`; malformed encoded values are ignored rather than throwing during request handling.
+ */
 export function cookies(request: Request): RequestCookies {
   let values: ReadonlyMap<string, string> | undefined;
   const cookieValues = () => {