@reckona/mreact-router 0.0.190 → 0.0.192

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/cli-options.ts

@@ -5,11 +5,14 @@ import {
   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;
@@ -157,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),
@@ -195,6 +228,10 @@ export function formatCliHelp(command?: string | undefined): string {
       `      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.",
       "",
@@ -223,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:",
@@ -462,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/index.ts

@@ -116,6 +116,7 @@ export async function rotateSession<TData>(
 }
 export type {
   AwsLambdaArtifactManifest,
+  AwsLambdaGeneratedHandlerPreloadMode,
   BuildAppPhase,
   BuildAppPhaseTiming,
   BuildAppOptions,