@reckona/mreact-router 0.0.65 → 0.0.67

package/src/import-policy.ts

@@ -0,0 +1,261 @@
+import { builtinModules, createRequire } from "node:module";
+import { dirname, join, relative, resolve, sep } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { resolveWorkspacePackageFile } from "./workspace-packages.js";
+
+const builtinModuleNames = new Set(builtinModules.flatMap((name) => [name, `node:${name}`]));
+const alwaysAllowedPackages = new Set([
+  "@reckona/mreact",
+  "@reckona/mreact-auth",
+  "@reckona/mreact-query",
+  "@reckona/mreact-reactive-core",
+  "@reckona/mreact-router",
+]);
+
+export interface AppRouterImportPolicy {
+  allowedPackages?: readonly string[] | undefined;
+  allowedSourceDirs?: readonly string[] | undefined;
+  projectRoot?: string | undefined;
+}
+
+export interface AppRouterImportPolicyPluginOptions {
+  allowedSourceDirs?: readonly string[] | undefined;
+  appDir: string;
+  importPolicy?: AppRouterImportPolicy | undefined;
+  label: string;
+  projectRoot?: string | undefined;
+}
+
+export function createAppRouterImportPolicyPlugin(options: AppRouterImportPolicyPluginOptions) {
+  const projectRoot = resolve(
+    options.importPolicy?.projectRoot ?? options.projectRoot ?? options.appDir,
+  );
+  const configuredAllowedSourceDirs =
+    options.importPolicy?.allowedSourceDirs ?? options.allowedSourceDirs;
+  const allowedSourceDirs = (configuredAllowedSourceDirs ?? [options.appDir]).map((directory) =>
+    resolve(projectRoot, directory),
+  );
+  const allowedPackages = new Set([
+    ...alwaysAllowedPackages,
+    ...(options.importPolicy?.allowedPackages ?? []),
+  ]);
+  const customAllowedSourceDirs = configuredAllowedSourceDirs !== undefined;
+
+  return {
+    name: `mreact-router-${options.label}-import-policy`,
+    setup(buildApi: {
+      onResolve(
+        options: { filter: RegExp },
+        callback: (args: {
+          path: string;
+          resolveDir: string;
+        }) => { errors?: Array<{ text: string }>; external?: boolean; path?: string } | undefined,
+      ): void;
+    }) {
+      buildApi.onResolve({ filter: /.*/ }, (args) => {
+        if (isRelativeImport(args.path)) {
+          const baseDir = args.resolveDir === "" ? options.appDir : args.resolveDir;
+          if (!isInsideAnyDirectory(allowedSourceDirs, baseDir)) {
+            return undefined;
+          }
+
+          const resolvedPath = resolve(baseDir, args.path);
+
+          return !isInsideDirectory(projectRoot, resolvedPath) ||
+            !isInsideAnyDirectory(allowedSourceDirs, resolvedPath)
+            ? {
+                errors: [
+                  {
+                    text: customAllowedSourceDirs
+                      ? `${options.label} imports must stay inside allowed source directories: ${args.path}`
+                      : `${options.label} imports must stay inside the app directory: ${args.path}`,
+                  },
+                ],
+              }
+            : undefined;
+        }
+
+        if (isAbsoluteOrProtocolImport(args.path)) {
+          return undefined;
+        }
+
+        if (builtinModuleNames.has(args.path)) {
+          return { external: true, path: args.path };
+        }
+
+        const workspacePath = workspacePackagePath(args.path, args.resolveDir);
+        if (workspacePath !== undefined) {
+          return { path: workspacePath };
+        }
+
+        if (args.resolveDir !== "" && !isInsideAnyDirectory(allowedSourceDirs, args.resolveDir)) {
+          return undefined;
+        }
+
+        const packageName = packageNameForSpecifier(args.path);
+
+        if (!allowedPackages.has(packageName)) {
+          return {
+            errors: [
+              {
+                text: importPolicyPackageError(options.label, packageName),
+              },
+            ],
+          };
+        }
+
+        const resolvedPackage = resolvePackageSpecifier(args.path, args.resolveDir, options.appDir);
+
+        return resolvedPackage === undefined
+          ? undefined
+          : { external: true, path: pathToFileURL(resolvedPackage).href };
+      });
+    },
+  };
+}
+
+function resolvePackageSpecifier(
+  specifier: string,
+  resolveDir: string,
+  appDir: string,
+): string | undefined {
+  const baseDir = resolveDir === "" ? appDir : resolveDir;
+
+  try {
+    return createRequire(join(baseDir, "__mreact_resolve__.cjs")).resolve(specifier);
+  } catch {
+    return undefined;
+  }
+}
+
+function importPolicyPackageError(label: string, packageName: string): string {
+  const normalizedLabel = label.toLowerCase();
+  const moduleKind =
+    normalizedLabel.includes("loader") ||
+    normalizedLabel.includes("middleware") ||
+    normalizedLabel.includes("route") ||
+    normalizedLabel.includes("metadata") ||
+    normalizedLabel.includes("action")
+      ? normalizedLabel
+      : `${normalizedLabel} module`;
+
+  return [
+    `"${packageName}" is imported by a ${moduleKind} but is not allowed by the app-router import policy.`,
+    "",
+    "The policy blocks server-side static imports from loader, middleware, route handler, metadata, and server action modules unless the package is explicitly allowed.",
+    "",
+    "Allow it in the Vite plugin config:",
+    "  mreactRouter({",
+    `    importPolicy: { allowedPackages: [${JSON.stringify(packageName)}] },`,
+    "  })",
+    "",
+    "For production builds, also declare the package in package.json dependencies so mreact-router build can derive the generated policy and the package is installed in the runtime artifact.",
+  ].join("\n");
+}
+
+function workspacePackagePath(specifier: string, resolveDir: string): string | undefined {
+  const currentDir = dirname(fileURLToPath(import.meta.url));
+  const packageRoot = dirname(currentDir);
+  const entries = new Map<
+    string,
+    string | { entry: string; monorepoDir: string; packageName: string }
+  >([
+    [
+      "@reckona/mreact-auth",
+      { entry: "index", monorepoDir: "auth", packageName: "@reckona/mreact-auth" },
+    ],
+    [
+      "@reckona/mreact-compiler",
+      { entry: "index", monorepoDir: "compiler", packageName: "@reckona/mreact-compiler" },
+    ],
+    [
+      "@reckona/mreact-query",
+      { entry: "index", monorepoDir: "query", packageName: "@reckona/mreact-query" },
+    ],
+    [
+      "@reckona/mreact-reactive-core",
+      {
+        entry: "index",
+        monorepoDir: "reactive-core",
+        packageName: "@reckona/mreact-reactive-core",
+      },
+    ],
+    [
+      "@reckona/mreact-router",
+      join(packageRoot, currentDir.endsWith(`${sep}dist`) ? "dist/index.js" : "src/index.ts"),
+    ],
+    [
+      "@reckona/mreact-router/app-router-globals",
+      join(
+        packageRoot,
+        currentDir.endsWith(`${sep}dist`)
+          ? "dist/app-router-globals.js"
+          : "src/app-router-globals.ts",
+      ),
+    ],
+    [
+      "@reckona/mreact-router/link",
+      join(packageRoot, currentDir.endsWith(`${sep}dist`) ? "dist/link.js" : "src/link.ts"),
+    ],
+    [
+      "@reckona/mreact-router/navigation-state",
+      join(
+        packageRoot,
+        currentDir.endsWith(`${sep}dist`) ? "dist/navigation-state.js" : "src/navigation-state.ts",
+      ),
+    ],
+    [
+      "@reckona/mreact-router/stream-list",
+      join(
+        packageRoot,
+        currentDir.endsWith(`${sep}dist`) ? "dist/stream-list.js" : "src/stream-list.ts",
+      ),
+    ],
+    [
+      "@reckona/mreact-server",
+      { entry: "index", monorepoDir: "server", packageName: "@reckona/mreact-server" },
+    ],
+  ]);
+  const entry = entries.get(specifier);
+
+  if (entry === undefined || typeof entry === "string") {
+    return entry;
+  }
+
+  return resolveWorkspacePackageFile({
+    currentFileUrl: import.meta.url,
+    entry: entry.entry,
+    monorepoDir: entry.monorepoDir,
+    packageName: entry.packageName,
+    resolveDir,
+    specifier,
+  });
+}
+
+function isRelativeImport(path: string): boolean {
+  return path === "." || path === ".." || path.startsWith("./") || path.startsWith("../");
+}
+
+function isAbsoluteOrProtocolImport(path: string): boolean {
+  return path.startsWith("/") || /^[A-Za-z][A-Za-z0-9+.-]*:/.test(path);
+}
+
+function packageNameForSpecifier(specifier: string): string {
+  if (!specifier.startsWith("@")) {
+    return specifier.split("/")[0] ?? specifier;
+  }
+
+  const [scope, name] = specifier.split("/");
+
+  return scope !== undefined && name !== undefined ? `${scope}/${name}` : specifier;
+}
+
+function isInsideDirectory(directory: string, candidate: string): boolean {
+  const relativePath = relative(directory, candidate);
+
+  return relativePath === "" || (!relativePath.startsWith("..") && !relativePath.startsWith(sep));
+}
+
+function isInsideAnyDirectory(directories: readonly string[], candidate: string): boolean {
+  return directories.some((directory) => isInsideDirectory(directory, candidate));
+}

package/src/index.ts

@@ -0,0 +1,221 @@
+export { buildApp, packageAwsLambdaArtifact } from "./build.js";
+export { assetHref, assetPreloadLinks } from "./assets.js";
+export { cacheControl, createMemoryRouteCache, revalidatePath } from "./cache.js";
+export { deleteCookie, parseCookieHeader, serializeCookie, setCookie } from "./cookies.js";
+export { defineMessages, detectLocale } from "./i18n.js";
+export { defer, isDeferredLoaderData } from "./deferred.js";
+export type { DeferredLoaderData } from "./deferred.js";
+export { Link, linkProps } from "./link.js";
+export { parseMultipartStream } from "./multipart.js";
+export type {
+  MultipartFixedLengthStream,
+  MultipartStreamFieldOptions,
+  MultipartStreamParseOptions,
+  MultipartStreamPart,
+} from "./multipart.js";
+export { getNavigationState, subscribeNavigationState } from "./navigation-state.js";
+export { getRouterRuntimeCacheStats } from "./runtime-cache.js";
+export type { HttpUpgradeHandler } from "./upgrade.js";
+export {
+  cookies,
+  headers,
+  html,
+  isNotFoundError,
+  isRedirectError,
+  json,
+  next,
+  notFound,
+  parseForm,
+  redirect,
+  redirect303,
+  redirectExternal,
+  rewrite,
+  textError,
+} from "./navigation.js";
+export type { ParseSchema } from "./navigation.js";
+export { createMemoryPrerenderStore } from "./prerender-store.js";
+export { getServerRuntimeState } from "./runtime-state.js";
+import {
+  createMemorySessionStore as createMemorySessionStoreInternal,
+  createSession as createSessionInternal,
+  destroySession as destroySessionInternal,
+  getSession as getSessionInternal,
+  rotateSession as rotateSessionInternal,
+} from "./session.js";
+import type {
+  MemorySessionStoreOptions as MemorySessionStoreOptionsInternal,
+  SessionCookieOptions as SessionCookieOptionsInternal,
+  SessionRecord as SessionRecordInternal,
+  SessionStore as SessionStoreInternal,
+} from "./session.js";
+
+/**
+ * @deprecated Import session helpers from `@reckona/mreact-auth` instead.
+ */
+export const createMemorySessionStore = createMemorySessionStoreInternal;
+/**
+ * @deprecated Import session helpers from `@reckona/mreact-auth` instead.
+ */
+export const createSession = createSessionInternal;
+/**
+ * @deprecated Import session helpers from `@reckona/mreact-auth` instead.
+ */
+export const destroySession = destroySessionInternal;
+/**
+ * @deprecated Import session helpers from `@reckona/mreact-auth` instead.
+ */
+export const getSession = getSessionInternal;
+/**
+ * @deprecated Import session helpers from `@reckona/mreact-auth` instead.
+ */
+export const rotateSession = rotateSessionInternal;
+export type {
+  AwsLambdaArtifactManifest,
+  BuildAppOptions,
+  BuildAppResult,
+  BuiltImportPolicyArtifact,
+  PackageAwsLambdaArtifactOptions,
+} from "./build.js";
+export type {
+  InferLoaderData,
+  LayoutProps,
+  LoaderContext,
+  GenerateMetadataContext,
+  ManifestContext,
+  ManifestDescriptor,
+  MetadataImage,
+  MetadataScalar,
+  MetadataThemeColor,
+  MetadataViewport,
+  MReactNode,
+  PageProps,
+  RobotsContext,
+  RobotsManifest,
+  RobotsRule,
+  RouteHeadDescriptor,
+  RouteHandlerContext,
+  RouteMetadata,
+  RouteParams,
+  RouteSecurityHeaders,
+  RouteStrictTransportSecurity,
+  SitemapContext,
+  SitemapEntry,
+} from "./types.js";
+export type {
+  AppRouterBuildTarget,
+  AppRouterClientSourceMapMode,
+  AppRouterClientSourceMapOption,
+} from "./config.js";
+export type {
+  AssetHelperOptions,
+  AssetLinkDescriptor,
+  AssetManifest,
+  AssetManifestEntry,
+} from "./assets.js";
+export type {
+  AppRouterCache,
+  AppRouterCacheEntry,
+  CacheControlOptions,
+  MemoryRouteCacheOptions,
+  RouteCachePolicy,
+} from "./cache.js";
+export type { CookieOptions } from "./cookies.js";
+export type { AppRouterImportPolicy } from "./import-policy.js";
+export type {
+  LinkOptions,
+  LinkPrefetch,
+  LinkProps,
+  LinkScroll,
+  LinkTransition,
+} from "./link.js";
+export type {
+  AppRouterNavigationState,
+  AppRouterNavigationStateListener,
+  AppRouterNavigationType,
+} from "./navigation-state.js";
+export type { RouterRuntimeCacheStat } from "./runtime-cache.js";
+export type { MemorySessionStoreOptionsInternal as MemorySessionStoreOptions };
+export type {
+  AppRouterLogError,
+  AppRouterLogEvent,
+  AppRouterLogger,
+  AppRouterLogLevel,
+  AppRouterRuntime,
+  AppRouterRequestEndLogEvent,
+  AppRouterRequestErrorLogEvent,
+  AppRouterRenderTimingLogEvent,
+  AppRouterRequestStartLogEvent,
+  AppRouterRequestTimingLogEvent,
+} from "./logger.js";
+export type { DetectedLocale, LocaleRoutingOptions, MessageTree } from "./i18n.js";
+export {
+  createFormCsrfToken,
+  formCsrfCookie,
+  formCsrfFieldName,
+  validateFormCsrf,
+} from "./csrf.js";
+export type {
+  AppRouterAllowedServerAction,
+  AppRouterServerActionOptions,
+} from "./actions.js";
+/**
+ * @deprecated Import session helpers and types from `@reckona/mreact-auth` instead.
+ */
+export type SessionCookieOptions = SessionCookieOptionsInternal;
+/**
+ * @deprecated Import session helpers and types from `@reckona/mreact-auth` instead.
+ */
+export type SessionRecord<TData = unknown> = SessionRecordInternal<TData>;
+/**
+ * @deprecated Import session helpers and types from `@reckona/mreact-auth` instead.
+ */
+export type SessionStore<TData = unknown> = SessionStoreInternal<TData>;
+export { startDevServer } from "./dev-server.js";
+export type { StartDevServerOptions } from "./dev-server.js";
+export { renderAppRequest } from "./render.js";
+export type {
+  AppRouterResponseHook,
+  AppRouterResponseHookContext,
+  RenderAppRequestOptions,
+} from "./render.js";
+export {
+  parseTraceContext,
+  traceContextFromRequest,
+} from "./trace.js";
+export type {
+  RouterInstrumentation,
+  RouterMiddlewareEndInstrumentationEvent,
+  RouterMiddlewareInstrumentationEvent,
+  RouterRequestEndInstrumentationEvent,
+  RouterRequestInstrumentationEvent,
+  RouterRouteEndInstrumentationEvent,
+  RouterRouteInstrumentationEvent,
+  RouterTraceContext,
+} from "./trace.js";
+export type {
+  FileSystemPrerenderStoreOptions,
+  KeyValuePrerenderStoreAdapter,
+  KeyValuePrerenderStoreOptions,
+  MemoryPrerenderStoreOptions,
+} from "./prerender-store.js";
+export { createFileSystemPrerenderStore, createKeyValuePrerenderStore } from "./prerender-store.js";
+export { preloadBuiltAppRuntime, renderBuiltAppRequest, startServer } from "./serve.js";
+export type {
+  BuiltAppRuntimePreloadMode,
+  AppRouterPrerenderStore,
+  BuiltAppRuntimePreloadStrategy,
+  RenderBuiltAppRequestOptions,
+  RequestHostPolicy,
+  StartServerOptions,
+} from "./serve.js";
+export { matchRoute, scanAppRoutes } from "./routes.js";
+export type { AppFileConvention } from "./file-conventions.js";
+export type {
+  AppAssetRoute,
+  AppMetadataRoute,
+  AppRoute,
+  MatchedRoute,
+  PageRoute,
+  RouteSegment,
+  ServerRoute,
+} from "./routes.js";

package/src/link.ts

@@ -0,0 +1,47 @@
+import {
+  createElement,
+  type ReactCompatElement,
+  type ReactCompatNode,
+} from "@reckona/mreact-compat";
+
+export type LinkPrefetch = "intent" | "viewport" | "none" | false;
+export type LinkScroll = "top" | "preserve";
+export type LinkTransition = "auto" | "none" | false;
+
+export interface LinkOptions {
+  href: string;
+  prefetch?: LinkPrefetch | undefined;
+  reload?: boolean | undefined;
+  scroll?: LinkScroll | undefined;
+  transition?: LinkTransition | undefined;
+}
+
+export interface LinkProps extends LinkOptions {
+  children?: ReactCompatNode;
+  [attribute: string]: unknown;
+}
+
+export function linkProps(options: LinkOptions): Record<string, string> {
+  return {
+    href: options.href,
+    ...(options.prefetch === undefined || options.prefetch === "intent"
+      ? {}
+      : { "data-mreact-prefetch": options.prefetch === false ? "none" : options.prefetch }),
+    ...(options.reload === true ? { "data-mreact-reload": "true" } : {}),
+    ...(options.scroll === undefined || options.scroll === "top"
+      ? {}
+      : { "data-mreact-scroll": options.scroll }),
+    ...(options.transition === undefined || options.transition === false || options.transition === "none"
+      ? {}
+      : { "data-mreact-transition": options.transition }),
+  };
+}
+
+export function Link(props: LinkProps): ReactCompatElement {
+  const { href, prefetch, reload, scroll, transition, ...rest } = props;
+
+  return createElement("a", {
+    ...rest,
+    ...linkProps({ href, prefetch, reload, scroll, transition }),
+  });
+}

package/src/logger.ts

@@ -0,0 +1,149 @@
+export type AppRouterLogLevel = "debug" | "info" | "warn" | "error";
+
+export type AppRouterRuntime = "aws-lambda" | "cloudflare" | "edge" | "node";
+
+export interface AppRouterLogger {
+  debug?: ((event: AppRouterLogEvent) => void | Promise<void>) | undefined;
+  error?: ((event: AppRouterLogEvent) => void | Promise<void>) | undefined;
+  info?: ((event: AppRouterLogEvent) => void | Promise<void>) | undefined;
+  warn?: ((event: AppRouterLogEvent) => void | Promise<void>) | undefined;
+}
+
+export type AppRouterLogEvent =
+  | AppRouterRequestStartLogEvent
+  | AppRouterRequestEndLogEvent
+  | AppRouterRequestErrorLogEvent
+  | AppRouterRequestTimingLogEvent
+  | AppRouterRenderTimingLogEvent;
+
+export interface AppRouterRequestStartLogEvent {
+  method: string;
+  path: string;
+  runtime: AppRouterRuntime;
+  type: "router:request:start";
+}
+
+export interface AppRouterRequestEndLogEvent {
+  durationMs: number;
+  method: string;
+  path: string;
+  runtime: AppRouterRuntime;
+  status: number;
+  type: "router:request:end";
+}
+
+export interface AppRouterRequestErrorLogEvent {
+  durationMs: number;
+  error: AppRouterLogError;
+  method: string;
+  path: string;
+  runtime: AppRouterRuntime;
+  type: "router:request:error";
+}
+
+export interface AppRouterRequestTimingLogEvent {
+  durationMs: number;
+  method: string;
+  path: string;
+  phases: Record<string, number>;
+  runtime: AppRouterRuntime;
+  status: number;
+  type: "router:request:timing";
+}
+
+export interface AppRouterRenderTimingLogEvent {
+  method: string;
+  path: string;
+  phases: Record<string, number>;
+  status: number;
+  type: "router:render:timing";
+}
+
+export interface AppRouterLogError {
+  message: string;
+  name: string;
+}
+
+export interface RouterRequestLogFields {
+  method: string;
+  path: string;
+  runtime: AppRouterRuntime;
+}
+
+export function emitRouterLog(
+  logger: AppRouterLogger | undefined,
+  level: AppRouterLogLevel,
+  event: AppRouterLogEvent,
+): void {
+  const sink = logger?.[level];
+
+  if (sink === undefined) {
+    return;
+  }
+
+  queueMicrotask(() => {
+    try {
+      const result = sink(event);
+
+      if (isPromiseLike(result)) {
+        result.catch(() => {});
+      }
+    } catch {
+      // Logger sinks are best-effort and must never affect request handling.
+    }
+  });
+}
+
+function isPromiseLike(value: unknown): value is Promise<void> {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "catch" in value &&
+    typeof value.catch === "function"
+  );
+}
+
+export function requestLogFields(
+  request: Request,
+  runtime: AppRouterRuntime,
+): RouterRequestLogFields {
+  return {
+    method: request.method,
+    path: new URL(request.url).pathname,
+    runtime,
+  };
+}
+
+export function nodeRequestPath(url: string | undefined): string {
+  if (url === undefined || url === "") {
+    return "/";
+  }
+
+  try {
+    return new URL(url, "http://mreact.local").pathname;
+  } catch {
+    return "/";
+  }
+}
+
+export function logNow(): number {
+  return performance.now();
+}
+
+export function logDurationMs(startedAt: number): number {
+  return Math.max(0, Math.round((logNow() - startedAt) * 1000) / 1000);
+}
+
+export function logError(error: unknown): AppRouterLogError {
+  if (error instanceof Error) {
+    return {
+      message: error.message,
+      name: error.name,
+    };
+  }
+
+  return {
+    message: String(error),
+    name: "Error",
+  };
+}