@reckona/mreact-router 0.0.189 → 0.0.191

package/src/build.ts

@@ -117,10 +117,18 @@ const serverArtifactFilesystemConcurrency = 2;
 type ServerTransformOutput = ReturnType<typeof transform>;
 type ServerTransformCache = Map<string, Promise<ServerTransformOutput>>;
 
+export type AwsLambdaGeneratedHandlerPreloadMode =
+  | "all"
+  | "hot-route-requests"
+  | "middleware"
+  | "none";
+
 /**
  * Configures an app-router production build and its deployment targets.
  */
 export interface BuildAppOptions extends AppRouterProjectOptions {
+  awsLambdaPreload?: AwsLambdaGeneratedHandlerPreloadMode | undefined;
+  awsLambdaPreloadRoutes?: readonly string[] | undefined;
   onBuildProgress?: ((event: BuildAppProgressEvent) => void) | undefined;
   onBuildPhaseTiming?: ((timing: BuildAppPhaseTiming) => void) | undefined;
   outDir: string;
@@ -261,6 +269,7 @@ export interface AwsLambdaArtifactManifest {
   files: Array<{ bytes: number; path: string }>;
   handler: string;
   runtime: "aws-lambda";
+  streamingHandler?: string | undefined;
   totalBytes: number;
   version: 1;
 }
@@ -280,6 +289,8 @@ export interface CloudflarePagesArtifactManifest {
  * Configures packaging of a built app-router output directory for AWS Lambda.
  */
 export interface PackageAwsLambdaArtifactOptions {
+  awsLambdaPreload?: AwsLambdaGeneratedHandlerPreloadMode | undefined;
+  awsLambdaPreloadRoutes?: readonly string[] | undefined;
   fromDir: string;
   handlerEntry?: string | undefined;
   outDir: string;
@@ -810,7 +821,15 @@ async function buildAppWithResolvedProject(
 
   if (shouldTrackBuildPhases === false) {
     await Promise.all([
-      ...(shouldBuildAwsLambda ? [writeAwsLambdaHandlerArtifact(options.outDir)] : []),
+      ...(shouldBuildAwsLambda
+        ? [
+            writeAwsLambdaHandlerArtifact(
+              options.outDir,
+              options.awsLambdaPreload,
+              options.awsLambdaPreloadRoutes,
+            ),
+          ]
+        : []),
       ...(shouldBuildCloudflare
         ? [
             writeCloudflareWorkerArtifact({
@@ -825,7 +844,15 @@ async function buildAppWithResolvedProject(
   } else {
     await timeBuildPhase(timingSink, progressSink, "adapterArtifacts", async () => {
       await Promise.all([
-        ...(shouldBuildAwsLambda ? [writeAwsLambdaHandlerArtifact(options.outDir)] : []),
+        ...(shouldBuildAwsLambda
+          ? [
+              writeAwsLambdaHandlerArtifact(
+                options.outDir,
+                options.awsLambdaPreload,
+                options.awsLambdaPreloadRoutes,
+              ),
+            ]
+          : []),
         ...(shouldBuildCloudflare
           ? [
               writeCloudflareWorkerArtifact({
@@ -888,14 +915,18 @@ async function createIncrementalBuildCacheFingerprint(options: {
     }))
     .sort((left, right) => left.file.localeCompare(right.file));
   const payload = {
-    appDir: normalizeBuildInputPath(relative(options.project.projectRoot, options.project.routesDir)),
+    appDir: normalizeBuildInputPath(
+      relative(options.project.projectRoot, options.project.routesDir),
+    ),
     assetBaseUrl: options.project.assetBaseUrl ?? null,
     clientConsolePureFunctions: options.project.clientConsolePureFunctions ?? [],
     clientSourceMaps: options.project.clientSourceMaps,
     define,
     nodeEnv: process.env.NODE_ENV ?? null,
     publicAssetBaseUrl: options.project.publicAssetBaseUrl ?? null,
-    publicDir: normalizeBuildInputPath(relative(options.project.projectRoot, options.project.publicDir)),
+    publicDir: normalizeBuildInputPath(
+      relative(options.project.projectRoot, options.project.publicDir),
+    ),
     routes,
     sourceDirs: options.project.allowedSourceDirs
       .map((directory) => normalizeBuildInputPath(relative(options.project.projectRoot, directory)))
@@ -1009,10 +1040,7 @@ async function readJsonBuildOutput<T>(file: string): Promise<T | undefined> {
   try {
     return JSON.parse(await readFile(file, "utf8")) as T;
   } catch (error) {
-    if (
-      (isNodeError(error) && error.code === "ENOENT") ||
-      error instanceof SyntaxError
-    ) {
+    if ((isNodeError(error) && error.code === "ENOENT") || error instanceof SyntaxError) {
       return undefined;
     }
 
@@ -6483,10 +6511,25 @@ async function writeNavigationRuntimeBundle(
   return script;
 }
 
-async function writeAwsLambdaHandlerArtifact(outDir: string): Promise<void> {
+async function writeAwsLambdaHandlerArtifact(
+  outDir: string,
+  preload?: AwsLambdaGeneratedHandlerPreloadMode,
+  routes?: readonly string[],
+): Promise<void> {
   const awsLambdaDir = join(outDir, "aws-lambda");
   await mkdir(awsLambdaDir, { recursive: true });
-  await writeFile(join(awsLambdaDir, "mreact-handler.mjs"), awsLambdaHandlerSource(".."));
+  const policy = { mode: preload ?? "middleware", ...(routes === undefined ? {} : { routes }) };
+  await Promise.all([
+    writeFile(
+      join(awsLambdaDir, "mreact-handler.mjs"),
+      awsLambdaHandlerSource("buffered", "..", policy.mode, policy.routes),
+    ),
+    writeFile(
+      join(awsLambdaDir, "mreact-streaming-handler.mjs"),
+      awsLambdaHandlerSource("streaming", "..", policy.mode, policy.routes),
+    ),
+    writeFile(join(awsLambdaDir, "preload-policy.json"), JSON.stringify(policy, null, 2)),
+  ]);
 }
 
 async function writeCloudflareWorkerArtifact(options: {
@@ -6541,7 +6584,17 @@ export async function packageAwsLambdaArtifact(
     outDir: options.outDir,
   });
   if (options.handlerEntry === undefined) {
-    await writeFile(join(options.outDir, "mreact-handler.mjs"), awsLambdaHandlerSource(".mreact"));
+    const builtPolicy = await readAwsLambdaGeneratedPreloadPolicy(options.fromDir);
+    const preload = options.awsLambdaPreload ?? builtPolicy.mode;
+    const routes = options.awsLambdaPreloadRoutes ?? builtPolicy.routes;
+    await writeFile(
+      join(options.outDir, "mreact-handler.mjs"),
+      awsLambdaHandlerSource("buffered", ".mreact", preload, routes),
+    );
+    await writeFile(
+      join(options.outDir, "mreact-streaming-handler.mjs"),
+      awsLambdaHandlerSource("streaming", ".mreact", preload, routes),
+    );
   } else {
     await writeAwsLambdaCustomHandlerArtifact({
       entry: options.handlerEntry,
@@ -6559,6 +6612,9 @@ export async function packageAwsLambdaArtifact(
     files,
     handler: "mreact-handler.handler",
     runtime: "aws-lambda",
+    ...(options.handlerEntry === undefined
+      ? { streamingHandler: "mreact-streaming-handler.handler" }
+      : {}),
     totalBytes: files.reduce((total, file) => total + file.bytes, 0),
     version: 1,
   } satisfies AwsLambdaArtifactManifest;
@@ -6788,22 +6844,63 @@ async function collectArtifactFiles(
   );
 }
 
-function awsLambdaHandlerSource(outDirRelativeToHandler: string): string {
+function awsLambdaHandlerSource(
+  kind: "buffered" | "streaming",
+  outDirRelativeToHandler: string,
+  preload: AwsLambdaGeneratedHandlerPreloadMode = "middleware",
+  routes?: readonly string[],
+): string {
+  const createHandler =
+    kind === "streaming"
+      ? "createAwsLambdaStreamingRequestHandler"
+      : "createAwsLambdaRequestHandler";
   return `import { fileURLToPath } from "node:url";
 import { dirname, resolve } from "node:path";
-import { createPreloadedAwsLambdaRequestHandler } from "@reckona/mreact-router/adapters/aws-lambda";
+import { ${createHandler}, warmAwsLambdaRuntime } from "@reckona/mreact-router/adapters/aws-lambda";
 
 const here = dirname(fileURLToPath(import.meta.url));
-
-export const handler = await createPreloadedAwsLambdaRequestHandler({
+const options = {
   importPolicy: "generated",
   outDir: resolve(here, ${JSON.stringify(outDirRelativeToHandler)}),
-  preload: { mode: "all" },
+  preload: { mode: ${JSON.stringify(preload)}${routes === undefined ? "" : `, routes: ${JSON.stringify(routes)}`} },
   timings: process.env.MREACT_ROUTER_TIMINGS === "1",
+};
+
+await warmAwsLambdaRuntime(options);
+export const handler = ${createHandler}({
+  ...options,
+  preload: { mode: "none" },
 });
 `;
 }
 
+async function readAwsLambdaGeneratedPreloadPolicy(outDir: string): Promise<{
+  mode: AwsLambdaGeneratedHandlerPreloadMode;
+  routes?: readonly string[] | undefined;
+}> {
+  const path = join(outDir, "aws-lambda", "preload-policy.json");
+  try {
+    return JSON.parse(await readFile(path, "utf8")) as {
+      mode: AwsLambdaGeneratedHandlerPreloadMode;
+      routes?: readonly string[] | undefined;
+    };
+  } catch (error) {
+    if (isNodeErrorCode(error, "ENOENT")) {
+      return { mode: "middleware" };
+    }
+    throw error;
+  }
+}
+
+function isNodeErrorCode(error: unknown, code: string): boolean {
+  return (
+    typeof error === "object" &&
+    error !== null &&
+    "code" in error &&
+    (error as { code?: unknown }).code === code
+  );
+}
+
 async function validateProductionRoutes(options: {
   clientRouteInferenceCache: ClientRouteInferenceCache;
   files: Record<string, string>;

package/src/cache.ts

@@ -58,6 +58,7 @@ interface AppRouterCacheState {
 interface RouteCacheContext {
   cache: AppRouterCache;
   cachePolicy?: RouteCachePolicy | undefined;
+  closed?: boolean | undefined;
   revalidatedPaths: Set<string>;
 }
 
@@ -472,15 +473,20 @@ export async function withRouteCacheContext<T>(
   };
 
   return cacheState.storage.run(context, async () => {
-    const value = await fn();
-    const cachePolicy = context.cachePolicy;
-    const revalidatedPaths = Array.from(context.revalidatedPaths);
+    try {
+      const value = await fn();
+      context.closed = true;
+      const cachePolicy = context.cachePolicy;
+      const revalidatedPaths = Array.from(context.revalidatedPaths);
 
-    for (const path of revalidatedPaths) {
-      await context.cache.deleteByPath(path);
-    }
+      for (const path of revalidatedPaths) {
+        await context.cache.deleteByPath(path);
+      }
 
-    return { cachePolicy, revalidatedPaths, value };
+      return { cachePolicy, revalidatedPaths, value };
+    } finally {
+      context.closed = true;
+    }
   });
 }
 
@@ -500,15 +506,17 @@ export function beginRouteCacheContext(cache: AppRouterCache | undefined): {
       return context.cachePolicy;
     },
     async dispose() {
+      context.closed = true;
       const revalidatedPaths = Array.from(context.revalidatedPaths);
-
-      for (const path of revalidatedPaths) {
-        await context.cache.deleteByPath(path);
-      }
-
-      const index = cacheState.activeContexts.lastIndexOf(context);
-      if (index !== -1) {
-        cacheState.activeContexts.splice(index, 1);
+      try {
+        for (const path of revalidatedPaths) {
+          await context.cache.deleteByPath(path);
+        }
+      } finally {
+        const index = cacheState.activeContexts.lastIndexOf(context);
+        if (index !== -1) {
+          cacheState.activeContexts.splice(index, 1);
+        }
       }
 
       return { revalidatedPaths };
@@ -516,8 +524,22 @@ export function beginRouteCacheContext(cache: AppRouterCache | undefined): {
   };
 }
 
-function activeRouteCacheContext(): RouteCacheContext | undefined {
-  return cacheState.storage.getStore() ?? cacheState.activeContexts.at(-1);
+export function activeRouteCacheContext(): RouteCacheContext | undefined {
+  const asyncContext = cacheState.storage.getStore();
+
+  if (asyncContext !== undefined) {
+    return asyncContext.closed === true ? undefined : asyncContext;
+  }
+
+  for (let index = cacheState.activeContexts.length - 1; index >= 0; index -= 1) {
+    const context = cacheState.activeContexts[index];
+
+    if (context?.closed !== true) {
+      return context;
+    }
+  }
+
+  return undefined;
 }
 
 // Host is excluded from the cache key to prevent attacker-supplied Host

package/src/cli-options.ts

@@ -1,14 +1,18 @@
 import type { AppRouterLogger, AppRouterLogEvent } from "./logger.js";
-import type {
-  AppRouterBuildTarget,
-  AppRouterClientSourceMapMode,
+import {
+  appRouterBuildTargetMetadata,
+  type AppRouterBuildTarget,
+  type AppRouterClientSourceMapMode,
 } from "./config.js";
 import type { RequestHostPolicy } from "./serve.js";
+import type { AwsLambdaGeneratedHandlerPreloadMode } from "./build.js";
 
 export type CliRequestLogMode = "requests";
 export type CliBuildTarget = AppRouterBuildTarget | "all";
 
 export interface ParsedCliArguments {
+  awsLambdaPreload?: AwsLambdaGeneratedHandlerPreloadMode | undefined;
+  awsLambdaPreloadRoutes?: readonly string[] | undefined;
   clientSourceMaps?: AppRouterClientSourceMapMode | undefined;
   command: string;
   allowedHosts?: readonly string[] | undefined;
@@ -156,6 +160,36 @@ export function parseCliArguments(argv: readonly string[]): ParsedCliArguments {
       continue;
     }
 
+    if (value === "--aws-lambda-preload") {
+      parsed.awsLambdaPreload = parseCliAwsLambdaPreloadMode(
+        readOptionValue(argv, index, "aws-lambda-preload"),
+      );
+      index += 1;
+      continue;
+    }
+
+    if (value.startsWith("--aws-lambda-preload=")) {
+      parsed.awsLambdaPreload = parseCliAwsLambdaPreloadMode(
+        value.slice("--aws-lambda-preload=".length),
+      );
+      continue;
+    }
+
+    if (value === "--aws-lambda-preload-routes") {
+      parsed.awsLambdaPreloadRoutes = parseCliAwsLambdaPreloadRoutes(
+        readOptionValue(argv, index, "aws-lambda-preload-routes"),
+      );
+      index += 1;
+      continue;
+    }
+
+    if (value.startsWith("--aws-lambda-preload-routes=")) {
+      parsed.awsLambdaPreloadRoutes = parseCliAwsLambdaPreloadRoutes(
+        value.slice("--aws-lambda-preload-routes=".length),
+      );
+      continue;
+    }
+
     if (value.startsWith("--client-source-maps=")) {
       parsed.clientSourceMaps = parseCliClientSourceMapMode(
         value.slice("--client-source-maps=".length),
@@ -178,6 +212,11 @@ export function parseCliArguments(argv: readonly string[]): ParsedCliArguments {
 }
 
 export function formatCliHelp(command?: string | undefined): string {
+  const defaultTargetLabel = formatBuildTargetDisplayList(
+    appRouterBuildTargetMetadata.defaultTargets,
+  );
+  const allTargetValues = formatBuildTargetValueList(appRouterBuildTargetMetadata.allTargets);
+
   if (command === "build") {
     return [
       "Usage: mreact-router build [appDir] [options]",
@@ -186,9 +225,13 @@ export function formatCliHelp(command?: string | undefined): string {
       "",
       "Options:",
       "  --target=node|cloudflare|aws-lambda|all",
-      "      Select build artifacts. Defaults to node. aws-lambda writes .mreact/aws-lambda/mreact-handler.mjs and .mreact/server/import-policy.json.",
+      `      Select build artifacts. Defaults to ${defaultTargetLabel.toLowerCase()}. all selects ${allTargetValues}. aws-lambda writes .mreact/aws-lambda/mreact-handler.mjs and .mreact/server/import-policy.json.`,
       "  --client-source-maps=none|hidden",
       "      Control production client source map output.",
+      "  --aws-lambda-preload=middleware|hot-route-requests|all|none",
+      "      Select generated Lambda initialization preload. Defaults to middleware.",
+      "  --aws-lambda-preload-routes=/,/login",
+      "      Select routes for hot-route-requests initialization preload.",
       "  -h, --help",
       "      Show this help message.",
       "",
@@ -196,6 +239,7 @@ export function formatCliHelp(command?: string | undefined): string {
       "  mreact-router build --target=node",
       "  mreact-router build --target=cloudflare",
       "  mreact-router build --target=aws-lambda",
+      "  mreact-router build --target=all",
     ].join("\n");
   }
 
@@ -216,6 +260,10 @@ export function formatCliHelp(command?: string | undefined): string {
       "      For aws-lambda only, skip the production node_modules check when a later deploy step installs dependencies into the package directory.",
       "  --handler <entry>",
       "      For aws-lambda only, bundle a custom handler entry into mreact-handler.mjs. App-local extensionless TypeScript imports are bundled; package imports stay external.",
+      "  --aws-lambda-preload=middleware|hot-route-requests|all|none",
+      "      Override generated Lambda initialization preload. Omission preserves the build policy; legacy output without policy metadata falls back to middleware.",
+      "  --aws-lambda-preload-routes=/,/login",
+      "      Select routes for hot-route-requests initialization preload.",
       "  -h, --help        Show this help message.",
       "",
       "Examples:",
@@ -272,7 +320,7 @@ export function formatCliHelp(command?: string | undefined): string {
     "",
     "Commands:",
     "  dev [appDir]                              Start the development server.",
-    "  build [appDir]                            Build Node and Cloudflare artifacts by default.",
+    `  build [appDir]                            Build ${defaultTargetLabel} artifacts by default.`,
     "  build --target=aws-lambda                 Build Lambda artifacts including generated handler and import policy.",
     "  start [outDir]                            Serve built Node output.",
     "  package aws-lambda --from .mreact --out .lambda",
@@ -290,6 +338,7 @@ export function formatCliHelp(command?: string | undefined): string {
     "Examples:",
     "  mreact-router build --target=cloudflare",
     "  mreact-router build --target=aws-lambda",
+    "  mreact-router build --target=all",
     "  mreact-router package aws-lambda --from .mreact --out .lambda",
     "  mreact-router build --help",
   ].join("\n");
@@ -302,7 +351,21 @@ export function buildTargetsFromCliTarget(
     return undefined;
   }
 
-  return target === "all" ? ["node", "cloudflare", "aws-lambda"] : [target];
+  return target === "all" ? appRouterBuildTargetMetadata.allTargets : [target];
+}
+
+function formatBuildTargetDisplayList(targets: readonly AppRouterBuildTarget[]): string {
+  return targets.map(formatBuildTargetDisplayName).join(", ");
+}
+
+function formatBuildTargetDisplayName(target: AppRouterBuildTarget): string {
+  if (target === "aws-lambda") return "AWS Lambda";
+  return target[0]?.toUpperCase() + target.slice(1);
+}
+
+function formatBuildTargetValueList(targets: readonly AppRouterBuildTarget[]): string {
+  if (targets.length < 2) return targets[0] ?? "";
+  return `${targets.slice(0, -1).join(", ")}, and ${targets.at(-1)}`;
 }
 
 export function resolveCliRequestLogMode(
@@ -440,6 +503,29 @@ function parseCliClientSourceMapMode(value: string): AppRouterClientSourceMapMod
   );
 }
 
+function parseCliAwsLambdaPreloadMode(value: string): AwsLambdaGeneratedHandlerPreloadMode {
+  if (
+    value === "all" ||
+    value === "hot-route-requests" ||
+    value === "middleware" ||
+    value === "none"
+  ) {
+    return value;
+  }
+
+  throw new Error(
+    `Unsupported aws-lambda-preload ${JSON.stringify(value)}. Expected "middleware", "hot-route-requests", "all", or "none".`,
+  );
+}
+
+function parseCliAwsLambdaPreloadRoutes(value: string): readonly string[] {
+  const routes = value.split(",").filter((route) => route.startsWith("/"));
+  if (routes.length === 0 || routes.join(",") !== value) {
+    throw new Error("aws-lambda-preload-routes must be a comma-separated list of absolute routes.");
+  }
+  return routes;
+}
+
 function readOptionValue(values: readonly string[], index: number, name: string): string {
   const value = values[index + 1];
 

package/src/cli.ts

@@ -61,6 +61,12 @@ if (parsed !== undefined) {
         try {
           const result = await buildApp({
             ...loaded.project,
+            ...(parsed.awsLambdaPreload === undefined
+              ? {}
+              : { awsLambdaPreload: parsed.awsLambdaPreload }),
+            ...(parsed.awsLambdaPreloadRoutes === undefined
+              ? {}
+              : { awsLambdaPreloadRoutes: parsed.awsLambdaPreloadRoutes }),
             ...(parsed.clientSourceMaps === undefined
               ? {}
               : { clientSourceMaps: parsed.clientSourceMaps }),
@@ -87,6 +93,12 @@ if (parsed !== undefined) {
       } else if (command === "package") {
         if (routeArg === "aws-lambda") {
           const manifest = await packageAwsLambdaArtifact({
+            ...(parsed.awsLambdaPreload === undefined
+              ? {}
+              : { awsLambdaPreload: parsed.awsLambdaPreload }),
+            ...(parsed.awsLambdaPreloadRoutes === undefined
+              ? {}
+              : { awsLambdaPreloadRoutes: parsed.awsLambdaPreloadRoutes }),
             fromDir: resolve(parsed.from ?? ".mreact"),
             ...(parsed.handler === undefined ? {} : { handlerEntry: resolve(parsed.handler) }),
             outDir: resolve(parsed.out ?? ".lambda"),

package/src/client.ts

@@ -103,7 +103,7 @@ export interface ClientRouteInferenceCache {
   transformedSourceByFile: Map<string, Promise<CachedClientRouteSource>>;
 }
 
-interface CachedClientRouteSource {
+export interface CachedClientRouteSource {
   signature: string;
   source: string;
 }
@@ -3535,6 +3535,7 @@ function __mreactSyncRouteDataScripts(root, currentRouteId, nextRouteId) {
 
 function __mreactRouteDataScriptIds(...routeIds) {
   const ids = new Set();
+  ids.add("__mreact_auth_session");
 
   for (const routeId of routeIds) {
     if (typeof routeId !== "string" || routeId === "") {

package/src/config.ts

@@ -4,6 +4,14 @@ import { basename, dirname, isAbsolute, relative, resolve } from "node:path";
  * Selects the deployment runtime artifacts emitted by an app-router build.
  */
 export type AppRouterBuildTarget = "node" | "cloudflare" | "aws-lambda";
+
+export const appRouterBuildTargetMetadata = {
+  allTargets: ["node", "cloudflare", "aws-lambda"],
+  defaultTargets: ["node"],
+} as const satisfies {
+  allTargets: readonly AppRouterBuildTarget[];
+  defaultTargets: readonly AppRouterBuildTarget[];
+};
 /**
  * Names a browser console method that can be stripped from client bundles.
  */
@@ -180,7 +188,7 @@ export function resolveBuildTargets(
   targets: readonly AppRouterBuildTarget[] | undefined,
 ): readonly AppRouterBuildTarget[] {
   if (targets === undefined) {
-    return ["node"];
+    return appRouterBuildTargetMetadata.defaultTargets;
   }
 
   const uniqueTargets = [...new Set(targets)];
@@ -190,7 +198,7 @@ export function resolveBuildTargets(
   }
 
   for (const target of uniqueTargets) {
-    if (target !== "node" && target !== "cloudflare" && target !== "aws-lambda") {
+    if (!appRouterBuildTargetMetadata.allTargets.some((supported) => supported === target)) {
       throw new Error(
         `Unsupported mreactRouter build target ${JSON.stringify(target)}. Expected "node", "cloudflare", or "aws-lambda".`,
       );