@reckona/mreact-router 0.0.182 → 0.0.184

package/src/build.ts

@@ -1,4 +1,5 @@
 import { createHash } from "node:crypto";
+import { AsyncLocalStorage } from "node:async_hooks";
 import type { Dirent } from "node:fs";
 import {
   copyFile,
@@ -108,7 +109,8 @@ const nativeEscapeTransform = {
   batchImportSource: "@reckona/mreact-router/native-escape",
 } as const;
 
-const defaultBuildConcurrency = Math.max(1, Math.min(2, availableParallelism()));
+const maxDefaultBuildConcurrency = 8;
+const buildConcurrencyStorage = new AsyncLocalStorage<number>();
 const serverArtifactFilesystemConcurrency = 2;
 
 type ServerTransformOutput = ReturnType<typeof transform>;
@@ -219,6 +221,29 @@ export interface BuildAppResult {
   routes: AppRoute[];
 }
 
+interface IncrementalBuildCacheManifest {
+  fingerprint: string;
+  version: 1;
+}
+
+interface IncrementalBuildServerManifestOutputs {
+  serverModuleFiles?: Record<string, string>;
+  serverModuleRenderFiles?: Record<string, string>;
+  serverModuleRequestFiles?: Record<string, string>;
+}
+
+interface IncrementalBuildClientManifestOutputs {
+  assets?: readonly string[];
+  publicAssets?: readonly string[];
+  routes: readonly {
+    css?: readonly string[];
+    imports?: readonly string[];
+    navigationScript?: string | undefined;
+    script?: string | undefined;
+    sourceMap?: string | undefined;
+  }[];
+}
+
 /**
  * Describes the generated import policy artifact consumed by built request handlers.
  */
@@ -377,10 +402,24 @@ type StaticParams = Record<string, string | number | boolean | readonly string[]
  * Use this from custom build scripts when the CLI is too coarse-grained; the returned manifest paths describe the files written under `outDir`. The build reads route files, loaders, middleware, metadata, server actions, and client references, so callers should pass the same project root and source allow-list they expect to deploy.
  */
 export async function buildApp(options: BuildAppOptions): Promise<BuildAppResult> {
+  const project = resolveAppRouterProjectOptions(options);
+  const buildConcurrency = resolveBuildConcurrency(
+    options.buildConcurrency ?? project.buildConcurrency,
+  );
+
+  return await buildConcurrencyStorage.run(
+    buildConcurrency,
+    async () => await buildAppWithResolvedProject(options, project),
+  );
+}
+
+async function buildAppWithResolvedProject(
+  options: BuildAppOptions,
+  project: ResolvedAppRouterProject,
+): Promise<BuildAppResult> {
   const timingSink = options.onBuildPhaseTiming;
   const progressSink = options.onBuildProgress;
   const shouldTrackBuildPhases = timingSink !== undefined || progressSink !== undefined;
-  const project = resolveAppRouterProjectOptions(options);
   const buildTargets = resolveBuildTargets(options.targets ?? project.buildTargets);
   const shouldBuildCloudflare = buildTargets.includes("cloudflare");
   const shouldBuildAwsLambda = buildTargets.includes("aws-lambda");
@@ -405,6 +444,14 @@ export async function buildApp(options: BuildAppOptions): Promise<BuildAppResult
   const serverDir = join(options.outDir, "server");
   const clientDir = join(options.outDir, "client");
   const cloudflareDir = join(options.outDir, "cloudflare");
+  const incrementalBuildFingerprint = await createIncrementalBuildCacheFingerprint({
+    buildTargets,
+    files,
+    project,
+    routes,
+    viteDefine,
+    vitePlugins,
+  });
   const sourceAnalysis =
     shouldTrackBuildPhases === false
       ? await analyzeBuildRouteSources({
@@ -452,6 +499,17 @@ export async function buildApp(options: BuildAppOptions): Promise<BuildAppResult
     );
   }
 
+  if (
+    incrementalBuildFingerprint !== undefined &&
+    (await isIncrementalBuildCacheHit({
+      buildTargets,
+      fingerprint: incrementalBuildFingerprint,
+      outDir: options.outDir,
+    }))
+  ) {
+    return { routes };
+  }
+
   if (shouldTrackBuildPhases === false) {
     await rm(options.outDir, { force: true, recursive: true });
     await Promise.all([
@@ -601,9 +659,7 @@ export async function buildApp(options: BuildAppOptions): Promise<BuildAppResult
         ),
   ]);
   const clientRoutes = clientBundle.routes;
-  const navigationRuntimeScript = clientRoutes.some(
-    (route) => route.navigation === true && !route.client,
-  )
+  const navigationRuntimeScript = clientRoutes.some((route) => route.navigation === true)
     ? shouldTrackBuildPhases === false
       ? await writeNavigationRuntimeBundle(clientDir, project.clientConsolePureFunctions)
       : await timeBuildPhase(timingSink, progressSink, "navigationRuntime", () =>
@@ -614,7 +670,7 @@ export async function buildApp(options: BuildAppOptions): Promise<BuildAppResult
     navigationRuntimeScript === undefined
       ? clientRoutes
       : clientRoutes.map((route) =>
-          route.navigation === true && !route.client
+          route.navigation === true
             ? { ...route, navigationScript: navigationRuntimeScript }
             : route,
         );
@@ -783,9 +839,284 @@ export async function buildApp(options: BuildAppOptions): Promise<BuildAppResult
     });
   }
 
+  if (incrementalBuildFingerprint !== undefined) {
+    await writeIncrementalBuildCacheManifest(options.outDir, incrementalBuildFingerprint);
+  }
+
   return { routes };
 }
 
+const incrementalBuildCacheFilename = "build-cache.json";
+const incrementalBuildCacheVersion = 1;
+
+async function createIncrementalBuildCacheFingerprint(options: {
+  buildTargets: readonly AppRouterBuildTarget[];
+  files: Record<string, string>;
+  project: ResolvedAppRouterProject;
+  routes: readonly AppRoute[];
+  viteDefine: UserConfig["define"] | undefined;
+  vitePlugins: readonly PluginOption[] | undefined;
+}): Promise<string | undefined> {
+  if (options.vitePlugins !== undefined && options.vitePlugins.length > 0) {
+    return undefined;
+  }
+
+  let define: string;
+  try {
+    const serializedDefine = JSON.stringify(options.viteDefine ?? null);
+    if (serializedDefine === undefined) {
+      return undefined;
+    }
+    define = serializedDefine;
+  } catch {
+    return undefined;
+  }
+
+  const [publicAssets, appConventionAssets] = await Promise.all([
+    collectBuildInputFileHashes(options.project.publicDir, options.project.projectRoot),
+    collectAppConventionAssetInputHashes(options.project.routesDir, options.project.projectRoot),
+  ]);
+  const sourceFiles = Object.keys(options.files)
+    .sort()
+    .map((file) => [normalizeBuildInputPath(file), hashText(options.files[file] ?? "")] as const);
+  const routes = options.routes
+    .map((route) => ({
+      file: normalizeBuildInputPath(relative(options.project.projectRoot, route.file)),
+      kind: route.kind,
+      path: route.path,
+    }))
+    .sort((left, right) => left.file.localeCompare(right.file));
+  const payload = {
+    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)),
+    routes,
+    sourceDirs: options.project.allowedSourceDirs
+      .map((directory) => normalizeBuildInputPath(relative(options.project.projectRoot, directory)))
+      .sort(),
+    sourceFiles,
+    targets: [...options.buildTargets].sort(),
+    version: incrementalBuildCacheVersion,
+    publicAssets,
+    appConventionAssets,
+  };
+
+  return createHash("sha256").update(JSON.stringify(payload)).digest("hex");
+}
+
+async function isIncrementalBuildCacheHit(options: {
+  buildTargets: readonly AppRouterBuildTarget[];
+  fingerprint: string;
+  outDir: string;
+}): Promise<boolean> {
+  const cache = await readJsonBuildOutput<IncrementalBuildCacheManifest>(
+    join(options.outDir, incrementalBuildCacheFilename),
+  );
+  if (cache === undefined) {
+    return false;
+  }
+
+  return (
+    cache.version === incrementalBuildCacheVersion &&
+    cache.fingerprint === options.fingerprint &&
+    (await hasRequiredIncrementalBuildOutputs(options.outDir, options.buildTargets))
+  );
+}
+
+async function hasRequiredIncrementalBuildOutputs(
+  outDir: string,
+  buildTargets: readonly AppRouterBuildTarget[],
+): Promise<boolean> {
+  const serverManifestFile = join(outDir, "server", "manifest.json");
+  const clientManifestFile = join(outDir, "client", "manifest.json");
+  const requiredFiles = [
+    serverManifestFile,
+    join(outDir, "server", "import-policy.json"),
+    clientManifestFile,
+    join(outDir, "client", ".vite", "manifest.json"),
+    join(outDir, "routes.d.ts"),
+    join(outDir, "public-assets.d.ts"),
+    ...(buildTargets.includes("aws-lambda")
+      ? [join(outDir, "aws-lambda", "mreact-handler.mjs")]
+      : []),
+    ...(buildTargets.includes("cloudflare") ? [join(outDir, "cloudflare", "worker.mjs")] : []),
+  ];
+  const [serverManifest, clientManifest] = await Promise.all([
+    readJsonBuildOutput<IncrementalBuildServerManifestOutputs>(serverManifestFile),
+    readJsonBuildOutput<IncrementalBuildClientManifestOutputs>(clientManifestFile),
+  ]);
+  if (serverManifest === undefined || clientManifest === undefined) {
+    return false;
+  }
+
+  for (const file of [
+    ...Object.values(serverManifest.serverModuleFiles ?? {}),
+    ...Object.values(serverManifest.serverModuleRenderFiles ?? {}),
+    ...Object.values(serverManifest.serverModuleRequestFiles ?? {}),
+  ]) {
+    requiredFiles.push(join(outDir, "server", file));
+  }
+
+  for (const file of collectClientManifestOutputFiles(clientManifest)) {
+    requiredFiles.push(join(outDir, "client", file));
+  }
+
+  for (const file of requiredFiles) {
+    if (!(await isExistingFile(file))) {
+      return false;
+    }
+  }
+
+  return true;
+}
+
+function collectClientManifestOutputFiles(
+  manifest: IncrementalBuildClientManifestOutputs,
+): string[] {
+  const files = new Set<string>();
+
+  for (const asset of manifest.assets ?? []) {
+    files.add(asset);
+  }
+  for (const asset of manifest.publicAssets ?? []) {
+    files.add(asset);
+    files.add(`public/${asset}`);
+  }
+  for (const route of manifest.routes) {
+    for (const file of [
+      route.script,
+      route.sourceMap,
+      route.navigationScript,
+      ...(route.css ?? []),
+      ...(route.imports ?? []),
+    ]) {
+      if (file !== undefined) {
+        files.add(file);
+      }
+    }
+  }
+
+  return [...files];
+}
+
+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
+    ) {
+      return undefined;
+    }
+
+    throw error;
+  }
+}
+
+async function writeIncrementalBuildCacheManifest(
+  outDir: string,
+  fingerprint: string,
+): Promise<void> {
+  const cache = {
+    fingerprint,
+    version: incrementalBuildCacheVersion,
+  } satisfies IncrementalBuildCacheManifest;
+
+  await writeFile(
+    join(outDir, incrementalBuildCacheFilename),
+    `${JSON.stringify(cache, null, 2)}\n`,
+  );
+}
+
+async function collectBuildInputFileHashes(
+  directory: string,
+  projectRoot: string,
+): Promise<readonly (readonly [string, string])[]> {
+  if (!(await isPublicAssetDirectory(directory))) {
+    return [];
+  }
+
+  const files = await collectFiles(directory);
+  const hashes = await mapWithBuildConcurrency(
+    files,
+    async (file) =>
+      [
+        normalizeBuildInputPath(relative(projectRoot, file)),
+        hashBuffer(await readFile(file)),
+      ] as const,
+  );
+
+  return hashes.sort(([left], [right]) => left.localeCompare(right));
+}
+
+async function collectAppConventionAssetInputHashes(
+  appDir: string,
+  projectRoot: string,
+): Promise<readonly (readonly [string, string])[]> {
+  const entries = await readdir(appDir, { withFileTypes: true });
+  const assetFiles = entries
+    .filter((entry) => entry.isFile())
+    .map((entry) => join(appDir, entry.name))
+    .filter((file) => isAppFileConventionAsset(file, appDir));
+  const hashes = await mapWithBuildConcurrency(
+    assetFiles,
+    async (file) =>
+      [
+        normalizeBuildInputPath(relative(projectRoot, file)),
+        hashBuffer(await readFile(file)),
+      ] as const,
+  );
+
+  return hashes.sort(([left], [right]) => left.localeCompare(right));
+}
+
+async function isExistingFile(file: string): Promise<boolean> {
+  try {
+    return (await stat(file)).isFile();
+  } catch (error) {
+    if (isNodeError(error) && error.code === "ENOENT") {
+      return false;
+    }
+
+    throw error;
+  }
+}
+
+function normalizeBuildInputPath(path: string): string {
+  return path.split(sep).join("/");
+}
+
+function hashBuffer(buffer: Buffer): string {
+  return createHash("sha256").update(buffer).digest("hex").slice(0, 16);
+}
+
+function defaultBuildConcurrency(): number {
+  return Math.max(1, Math.min(maxDefaultBuildConcurrency, availableParallelism()));
+}
+
+function currentBuildConcurrency(): number {
+  return buildConcurrencyStorage.getStore() ?? defaultBuildConcurrency();
+}
+
+function resolveBuildConcurrency(
+  value: number | undefined,
+  cores = availableParallelism(),
+): number {
+  const resolved = value ?? Math.max(1, Math.min(maxDefaultBuildConcurrency, cores));
+
+  if (!Number.isSafeInteger(resolved) || resolved < 1) {
+    throw new Error("mreactRouter buildConcurrency must be a positive integer.");
+  }
+
+  return resolved;
+}
+
 function typedRoutesDeclaration(routes: readonly AppRoute[]): string {
   const routePaths = Array.from(
     new Set(
@@ -803,21 +1134,60 @@ function typedRoutesDeclaration(routes: readonly AppRoute[]): string {
     return left.localeCompare(right);
   });
   const routeUnion = routePaths.map((routePath) => JSON.stringify(routePath)).join(" | ");
+  const routeParamEntries = routePaths.map(
+    (routePath) => `  readonly ${JSON.stringify(routePath)}: ${routeParamsType(routePath)};`,
+  );
   return [
-    `import type { AppRouteLinkHref as MreactAppRouteLinkHref } from "@reckona/mreact-router";`,
+    `import type { AppRouteLinkHref as MreactAppRouteLinkHref, RouteParamsFor as MreactRouteParamsFor } from "@reckona/mreact-router";`,
     ``,
     `export type AppRoutePath = ${routeUnion === "" ? "never" : routeUnion};`,
     `export type AppRouteHref = MreactAppRouteLinkHref<AppRoutePath>;`,
+    `export type AppRouteParams<Path extends AppRoutePath> = MreactRouteParamsFor<Path>;`,
+    `export interface AppRouteParamMap {`,
+    ...(routeParamEntries.length === 0 ? [`  readonly [path: string]: never;`] : routeParamEntries),
+    `}`,
     ``,
     `declare module "@reckona/mreact-router/link" {`,
     `  interface AppRouteDeclarations {`,
     `    readonly path: AppRoutePath;`,
+    `    readonly params: AppRouteParamMap;`,
     `  }`,
     `}`,
     ``,
   ].join("\n");
 }
 
+function routeParamsType(routePath: string): string {
+  const params = routePath
+    .split("/")
+    .flatMap((segment): Array<{ catchAll: boolean; name: string }> => {
+      if (segment.startsWith(":...")) {
+        return [{ catchAll: true, name: segment.slice(4) }];
+      }
+
+      if (segment.startsWith(":")) {
+        return [{ catchAll: false, name: segment.slice(1) }];
+      }
+
+      return [];
+    });
+
+  if (params.length === 0) {
+    return "Record<never, never>";
+  }
+
+  return `{ ${params
+    .map(
+      (param) =>
+        `readonly ${propertyKeyForType(param.name)}: ${param.catchAll ? "readonly string[]" : "string"}`,
+    )
+    .join("; ")} }`;
+}
+
+function propertyKeyForType(value: string): string {
+  return /^[A-Za-z_$][\w$]*$/.test(value) ? value : JSON.stringify(value);
+}
+
 function typedPublicAssetsDeclaration(publicAssets: readonly string[]): string {
   const assetUnion = publicAssets.map((assetPath) => JSON.stringify(assetPath)).join(" | ");
 
@@ -861,7 +1231,7 @@ function roundBuildPhaseMs(value: number): number {
 async function mapWithBuildConcurrency<T, R>(
   items: readonly T[],
   map: (item: T, index: number) => Promise<R>,
-  concurrency = defaultBuildConcurrency,
+  concurrency = currentBuildConcurrency(),
 ): Promise<R[]> {
   if (items.length === 0) {
     return [];
@@ -897,6 +1267,27 @@ export async function __mapWithBuildConcurrencyForTests<T, R>(
   return await mapWithBuildConcurrency(items, map, concurrency);
 }
 
+async function mapServerOutputsWithBuildConcurrency<R>(
+  serverOutputs: readonly ServerOutputMode[],
+  map: (serverOutput: ServerOutputMode, index: number) => Promise<R>,
+): Promise<R[]> {
+  return await mapWithBuildConcurrency(serverOutputs, map, 1);
+}
+
+export async function __mapServerOutputsWithBuildConcurrencyForTests<R>(
+  serverOutputs: readonly ServerOutputMode[],
+  map: (serverOutput: ServerOutputMode, index: number) => Promise<R>,
+): Promise<R[]> {
+  return await mapServerOutputsWithBuildConcurrency(serverOutputs, map);
+}
+
+export function __resolveBuildConcurrencyForTests(
+  value: number | undefined,
+  cores: number,
+): number {
+  return resolveBuildConcurrency(value, cores);
+}
+
 async function analyzeBuildRouteSources(options: {
   clientRouteInferenceCache: ClientRouteInferenceCache;
   files: Record<string, string>;
@@ -2479,7 +2870,7 @@ async function buildServerModuleArtifacts(options: {
         });
       }
 
-      const serverOutputArtifacts = await mapWithBuildConcurrency(
+      const serverOutputArtifacts = await mapServerOutputsWithBuildConcurrency(
         serverOutputs,
         async (serverOutput) => {
           const output = await transformServerRouteSource({
@@ -5386,6 +5777,10 @@ function cloudflareWorkspaceRuntimePlugin(): RouterCompatPlugin {
       "@reckona/mreact-compat/scheduler",
       packageFile("react-compat", "@reckona/mreact-compat", "scheduler"),
     ],
+    [
+      "@reckona/mreact-compat/server",
+      packageFile("react-compat", "@reckona/mreact-compat", "server"),
+    ],
     ["@reckona/mreact-query", packageFile("query", "@reckona/mreact-query", "index")],
     [
       "@reckona/mreact-reactive-core",
@@ -5775,6 +6170,7 @@ async function writeClientRouteBundles(options: {
       scriptBasename: routeOutput.chunk.fileName.split("/").pop() ?? "route.js",
       sourceMaps: options.sourceMaps,
     });
+    const navigation = entry.navigation === true || entry.build.clientNavigation !== false;
 
     return {
       bytes: Buffer.byteLength(code),
@@ -5787,7 +6183,7 @@ async function writeClientRouteBundles(options: {
         : { clientReferenceManifest: entry.build.clientReferenceManifest }),
       ...(entry.css.length === 0 ? {} : { css: entry.css }),
       ...(routeOutput.chunk.imports.length === 0 ? {} : { imports: routeOutput.chunk.imports }),
-      ...(entry.navigation ? { navigation: entry.navigation } : {}),
+      ...(navigation ? { navigation } : {}),
       routeId,
       script: routeOutput.chunk.fileName,
       ...(options.sourceMaps === "linked" ? { sourceMap } : {}),

package/src/bundle-pipeline.ts

@@ -230,6 +230,15 @@ const mreactJsxRuntimeAliasPaths = new Map([
       packageName: "@reckona/mreact-compat",
     }),
   ],
+  [
+    "@reckona/mreact-compat/server",
+    workspacePackageFile({
+      currentFileUrl: import.meta.url,
+      entry: "server",
+      monorepoDir: "react-compat",
+      packageName: "@reckona/mreact-compat",
+    }),
+  ],
 ]);
 
 export async function bundleRouterModule(