@unieojs/unio-nextjs-adapter 0.1.0 → 0.2.0

package/src/types.ts

@@ -69,7 +69,11 @@ export interface BuildContext {
   distDir: string;
   /** Absolute project root */
   projectDir: string;
+  /** Absolute repository root, when Next.js provides it */
+  repoRoot?: string;
   config: NextConfigLike;
+  nextVersion?: string;
+  buildId?: string;
 }
 
 /**
@@ -91,3 +95,181 @@ export interface NextAdapter {
   ) => NextConfigLike | Promise<NextConfigLike>;
   onBuildComplete?: (ctx: BuildContext) => void | Promise<void>;
 }
+
+export type CapabilityStatus =
+  | "supported"
+  | "partial"
+  | "degraded"
+  | "unsupported";
+
+export interface UboaCapabilities {
+  static: CapabilityStatus;
+  routes: CapabilityStatus;
+  serverlessFunction: CapabilityStatus;
+  serverFunctionIntrospection: CapabilityStatus;
+  restRouteIntrospection: CapabilityStatus;
+  edgeMiddleware: CapabilityStatus;
+  isr: CapabilityStatus;
+  imageOptimization: CapabilityStatus;
+}
+
+interface UboaRouteBase {
+  id: string;
+  match: string;
+}
+
+export interface UboaAssetsRoute extends UboaRouteBase {
+  type: "assets";
+  entry: string;
+  serverFunction?: never;
+  edgeFunction?: never;
+  methods?: never;
+}
+
+export interface UboaServerFunctionRoute extends UboaRouteBase {
+  type: "serverFunction";
+  serverFunction: string;
+  methods?: string[];
+  entry?: never;
+  edgeFunction?: never;
+}
+
+export interface UboaEdgeFunctionRoute extends UboaRouteBase {
+  type: "edgeFunction";
+  edgeFunction: string;
+  entry?: never;
+  serverFunction?: never;
+  methods?: never;
+}
+
+export type UboaRoute =
+  | UboaAssetsRoute
+  | UboaServerFunctionRoute
+  | UboaEdgeFunctionRoute;
+
+interface UboaMiddlewareBase {
+  name: string;
+  match: string[];
+}
+
+export interface UboaEdgeMiddleware extends UboaMiddlewareBase {
+  runtime: "edge";
+  entry: string;
+  serverFunction?: never;
+}
+
+export interface UboaNodejsMiddleware extends UboaMiddlewareBase {
+  runtime: "nodejs";
+  serverFunction: string;
+  entry?: never;
+}
+
+export type UboaMiddleware =
+  | UboaEdgeMiddleware
+  | UboaNodejsMiddleware;
+
+export type UboaArtifactResourceKind =
+  | "assets"
+  | "serverFunction"
+  | "edgeBundle"
+  | "apiSchema";
+
+export interface UboaAssetsArtifact {
+  id: string;
+  resourceKind: "assets";
+  path: string;
+}
+
+export interface UboaServerFunctionArtifact {
+  id: string;
+  resourceKind: "serverFunction";
+  path: string;
+}
+
+export interface UboaEdgeBundleArtifact {
+  id: string;
+  resourceKind: "edgeBundle";
+  path: string;
+}
+
+export interface UboaArtifactReference {
+  id: string;
+  resourceKind: UboaArtifactResourceKind;
+}
+
+export type UboaApiSchemaFormat = "oneapi";
+
+export interface UboaApiSchemaArtifact {
+  id: string;
+  resourceKind: "apiSchema";
+  path: string;
+  schemaFormat: UboaApiSchemaFormat;
+  describes?: UboaArtifactReference;
+}
+
+export type UboaArtifact =
+  | UboaAssetsArtifact
+  | UboaServerFunctionArtifact
+  | UboaEdgeBundleArtifact
+  | UboaApiSchemaArtifact;
+
+export interface UboaServerFunctionDescriptor {
+  name: string;
+  runtime: string;
+  entry: string;
+  handler: string;
+  memory: number;
+  maxDuration: number;
+  environment: Record<string, unknown>;
+  bindings: Record<string, unknown>;
+  framework: Record<string, unknown>;
+  source: Record<string, unknown>;
+  [key: string]: unknown;
+}
+
+export type NextRouteOutputGroup =
+  | "pages"
+  | "pagesApi"
+  | "appPages"
+  | "appRoutes"
+  | "middleware";
+
+export interface GeneratedUboa {
+  outputDir: string;
+  routes: UboaRoute[];
+  middleware: UboaMiddleware[];
+  artifacts: UboaArtifact[];
+  capabilities: UboaCapabilities;
+  warnings: string[];
+}
+
+export interface ExtendServerFunctionDescriptorContext {
+  descriptor: UboaServerFunctionDescriptor;
+  name: string;
+  route: RouteOutput;
+  routeGroup: NextRouteOutputGroup;
+  ctx: BuildContext;
+}
+
+export interface ExtendArtifactsContext {
+  artifacts: UboaArtifact[];
+  routes: UboaRoute[];
+  middleware: UboaMiddleware[];
+  ctx: BuildContext;
+}
+
+export interface AfterEmitContext {
+  outputDir: string;
+  generated: GeneratedUboa;
+  ctx: BuildContext;
+}
+
+export interface UnioNextjsAdapterOptions {
+  extendServerFunctionDescriptor?: (
+    context: ExtendServerFunctionDescriptorContext,
+  ) => Record<string, unknown> | Promise<Record<string, unknown>>;
+  extendArtifacts?: (
+    context: ExtendArtifactsContext,
+  ) => UboaArtifact[] | Promise<UboaArtifact[]>;
+  afterEmit?: (context: AfterEmitContext) => void | Promise<void>;
+}

package/src/uboa.ts

@@ -3,45 +3,25 @@ import path from "node:path";
 
 import type {
   BuildContext,
+  GeneratedUboa,
+  NextRouteOutputGroup,
   PrerenderOutput,
   RouteOutput,
   StaticFileOutput,
+  UboaArtifact,
+  UboaCapabilities,
+  UboaMiddleware,
+  UboaRoute,
+  UboaServerFunctionDescriptor,
+  UnioNextjsAdapterOptions,
 } from "./types.js";
 
 const ADAPTER_PACKAGE = "@unieojs/unio-nextjs-adapter";
 const UBOA_VERSION = "1.0.0";
 
-type CapabilityStatus = "supported" | "partial" | "degraded" | "unsupported";
-
-interface UboaRoute {
-  id: string;
-  match: string;
-  type: "static" | "serverFunction";
-  entry?: string;
-  serverFunction?: string;
-}
-
-interface UboaMiddleware {
-  name: string;
-  match: string[];
-  runtime: "serverless";
-  serverFunction?: string;
-}
-
-interface UboaArtifact {
-  id: string;
-  resourceKind: "assets" | "serverFunction";
-  path: string;
-}
-
-interface GeneratedUboa {
-  routes: UboaRoute[];
-  middleware: UboaMiddleware[];
-  artifacts: UboaArtifact[];
-}
-
 type StaticLikeOutput = StaticFileOutput | PrerenderOutput;
 type RouteOutputKey = "pages" | "pagesApi" | "appPages" | "appRoutes";
+type DynamicServerOutput = Pick<GeneratedUboa, "routes" | "middleware" | "artifacts">;
 
 const ROUTE_GROUPS: Array<[string, RouteOutputKey]> = [
   ["pages", "pages"],
@@ -109,6 +89,21 @@ function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
+function isStringRecord(value: unknown): value is Record<string, string> {
+  return isRecord(value) &&
+    Object.values(value).every((entry) => typeof entry === "string");
+}
+
+function isSafeRelativePath(value: string): boolean {
+  if (!value) return false;
+  if (path.isAbsolute(value) || path.win32.isAbsolute(value)) return false;
+  return !value.split(/[\\/]+/).includes("..");
+}
+
+function buildId(ctx: BuildContext): string {
+  return ctx.buildId || process.env.BUILD_ID || process.env.TASK_ID || "local";
+}
+
 function routeConfig(route: RouteOutput): Record<string, unknown> {
   return isRecord(route.config) ? route.config : {};
 }
@@ -118,6 +113,14 @@ function routeMaxDuration(route: RouteOutput): number {
   return typeof maxDuration === "number" ? maxDuration : 10;
 }
 
+function edgeRuntimeModulePath(route: RouteOutput): string {
+  const edgeRuntime = route.edgeRuntime;
+  if (isRecord(edgeRuntime) && typeof edgeRuntime.modulePath === "string") {
+    return edgeRuntime.modulePath;
+  }
+  return route.filePath;
+}
+
 function matcherSource(matcher: unknown): string | undefined {
   if (typeof matcher === "string") return matcher;
   if (!isRecord(matcher)) return undefined;
@@ -149,27 +152,99 @@ async function copyEntryFile(source: string, dest: string): Promise<void> {
   await fs.copyFile(source, dest);
 }
 
+function routeSourceRoot(ctx: BuildContext): string {
+  return ctx.repoRoot ?? ctx.projectDir;
+}
+
+function relativeRouteFile(ctx: BuildContext, filePath: string): string {
+  const relativePath = path.relative(routeSourceRoot(ctx), filePath);
+
+  if (!relativePath || relativePath.startsWith("..") || path.isAbsolute(relativePath)) {
+    return path.basename(filePath);
+  }
+
+  return toPosix(relativePath);
+}
+
+function assetTargetPath(
+  ctx: BuildContext,
+  assetKey: string,
+  assetPath: string,
+): string {
+  return isSafeRelativePath(assetKey)
+    ? toPosix(assetKey)
+    : relativeRouteFile(ctx, assetPath);
+}
+
+async function copyRoutePayload(
+  functionDir: string,
+  ctx: BuildContext,
+  route: RouteOutput,
+): Promise<string> {
+  const entry = relativeRouteFile(ctx, route.filePath);
+  await copyEntryFile(route.filePath, path.join(functionDir, entry));
+
+  for (const assetMap of [route.assets, route.wasmAssets]) {
+    if (!isStringRecord(assetMap)) continue;
+
+    for (const [assetKey, assetPath] of Object.entries(assetMap)) {
+      await copyEntryFile(
+        assetPath,
+        path.join(functionDir, assetTargetPath(ctx, assetKey, assetPath)),
+      );
+    }
+  }
+
+  return entry;
+}
+
 async function emitServerFunction(
   root: string,
+  ctx: BuildContext,
   name: string,
   route: RouteOutput,
+  routeGroup: NextRouteOutputGroup,
+  options: UnioNextjsAdapterOptions,
 ): Promise<void> {
   const functionDir = path.join(root, "server-functions", name);
-  await copyEntryFile(route.filePath, path.join(functionDir, "index.js"));
-  await writeJson(path.join(functionDir, "serverFunction.json"), {
+  const entry = await copyRoutePayload(functionDir, ctx, route);
+  const descriptor: UboaServerFunctionDescriptor = {
     name,
     runtime: "nodejs",
-    entry: "index.js",
-    handler: "default",
+    entry,
+    handler: "handler",
     memory: 512,
     maxDuration: routeMaxDuration(route),
     environment: {},
     bindings: {},
+    framework: {
+      name: "next",
+      version: ctx.nextVersion ?? "unknown",
+      routeGroup,
+      outputType: route.type,
+    },
     source: {
+      id: route.id,
       type: route.type,
       pathname: route.pathname,
+      filePath: relativeRouteFile(ctx, route.filePath),
     },
-  });
+  };
+  const extendedDescriptor = options.extendServerFunctionDescriptor
+    ? await options.extendServerFunctionDescriptor({
+      descriptor,
+      name,
+      route,
+      routeGroup,
+      ctx,
+    })
+    : descriptor;
+
+  if (!isRecord(extendedDescriptor)) {
+    throw new Error("extendServerFunctionDescriptor must return an object.");
+  }
+
+  await writeJson(path.join(functionDir, "serverFunction.json"), extendedDescriptor);
 }
 
 function buildContentVersion(): string {
@@ -181,34 +256,48 @@ function buildContentVersion(): string {
   return parts.length > 0 ? parts.join(", ") : "local";
 }
 
-function buildCapabilities(ctx: BuildContext): Record<string, CapabilityStatus> {
+function buildCapabilities(ctx: BuildContext): UboaCapabilities {
   const { outputs } = ctx;
   const nodeRoutes = ROUTE_GROUPS.some(([, key]) =>
     outputs[key].some((route) => route.runtime === "nodejs"),
   );
   const nodeMiddleware = outputs.middleware?.runtime === "nodejs";
+  const edgeMiddleware = outputs.middleware?.runtime === "edge";
+  const hasServerFunction = nodeRoutes || nodeMiddleware;
 
   return {
     static: outputs.staticFiles.length > 0 || outputs.prerenders.length > 0 ?
       "supported" : "unsupported",
     routes: "supported",
-    serverlessFunction: nodeRoutes || nodeMiddleware ? "supported" : "unsupported",
-    edgeMiddleware: "unsupported",
+    serverlessFunction: hasServerFunction ? "supported" : "unsupported",
+    serverFunctionIntrospection: hasServerFunction ? "supported" : "unsupported",
+    restRouteIntrospection: nodeRoutes ? "supported" : "unsupported",
+    edgeMiddleware: edgeMiddleware ? "supported" : "unsupported",
     isr: outputs.prerenders.length > 0 ? "degraded" : "unsupported",
     imageOptimization: "unsupported",
   };
 }
 
+function buildWarnings(ctx: BuildContext): string[] {
+  return ctx.outputs.prerenders.length > 0
+    ? ["Next.js prerenders are emitted as static assets; ISR metadata is degraded."]
+    : [];
+}
+
 function assertSupportedOutputs(ctx: BuildContext): void {
   const unsupported: string[] = [];
 
-  if (ctx.outputs.middleware && ctx.outputs.middleware.runtime !== "nodejs") {
+  if (
+    ctx.outputs.middleware &&
+    ctx.outputs.middleware.runtime !== "nodejs" &&
+    ctx.outputs.middleware.runtime !== "edge"
+  ) {
     unsupported.push(`middleware (${ctx.outputs.middleware.runtime})`);
   }
 
   for (const [, key] of ROUTE_GROUPS) {
     for (const route of ctx.outputs[key]) {
-      if (route.runtime !== "nodejs") {
+      if (route.runtime !== "nodejs" && route.runtime !== "edge") {
         unsupported.push(`${key}:${route.pathname || route.id} (${route.runtime})`);
       }
     }
@@ -219,26 +308,41 @@ function assertSupportedOutputs(ctx: BuildContext): void {
   throw new Error(
     "[unio-nextjs-adapter] Unsupported Next.js outputs: " +
       `${unsupported.join(", ")}. ` +
-      "This adapter currently supports static assets and nodejs serverless functions only.",
+      "This adapter currently supports static assets, nodejs serverless functions, and edge functions only.",
   );
 }
 
 async function emitCoreManifest(
   root: string,
   ctx: BuildContext,
+  capabilities: UboaCapabilities,
+  warnings: string[],
 ): Promise<void> {
   await writeJson(path.join(root, "unio.json"), {
     version: UBOA_VERSION,
     framework: {
       name: "next",
-      version: "unknown",
+      version: ctx.nextVersion ?? "unknown",
       adapter: ADAPTER_PACKAGE,
     },
     build: {
       contentVersion: buildContentVersion(),
-      buildId: process.env.BUILD_ID || process.env.TASK_ID || "local",
+      buildId: buildId(ctx),
     },
-    capabilities: buildCapabilities(ctx),
+    capabilities,
+    warnings,
+  });
+}
+
+async function emitFeaturesManifest(root: string): Promise<void> {
+  await writeJson(path.join(root, "features.json"), { features: [] });
+}
+
+async function emitObservabilityManifest(root: string, ctx: BuildContext): Promise<void> {
+  await writeJson(path.join(root, "observability.json"), {
+    adapter: ADAPTER_PACKAGE,
+    framework: "next",
+    buildId: buildId(ctx),
   });
 }
 
@@ -257,7 +361,7 @@ async function emitStaticFiles(
     routes.push({
       id: `static-${slugify(file.pathname || file.id, "index")}`,
       match: normalizeStaticMatch(file),
-      type: "static",
+      type: "assets",
       entry: staticEntryFor(file),
     });
   }
@@ -265,9 +369,19 @@ async function emitStaticFiles(
   return routes;
 }
 
+function sourceForRoute(ctx: BuildContext, route: RouteOutput): Record<string, unknown> {
+  return {
+    id: route.id,
+    type: route.type,
+    pathname: route.pathname,
+    filePath: relativeRouteFile(ctx, route.filePath),
+  };
+}
+
 async function emitRouteOutputs(
   root: string,
   ctx: BuildContext,
+  options: UnioNextjsAdapterOptions,
 ): Promise<Pick<GeneratedUboa, "routes" | "artifacts">> {
   const routes: UboaRoute[] = [];
   const artifacts: UboaArtifact[] = [];
@@ -276,7 +390,23 @@ async function emitRouteOutputs(
     for (const route of ctx.outputs[key]) {
       const name = routeFunctionName(group, route);
 
-      await emitServerFunction(root, name, route);
+      if (route.runtime === "edge") {
+        await emitEdgeBundle(root, ctx, name, route, key);
+        routes.push({
+          id: `edge-${name}`,
+          match: routeMatch(route),
+          type: "edgeFunction",
+          edgeFunction: name,
+        });
+        artifacts.push({
+          id: name,
+          resourceKind: "edgeBundle",
+          path: `edge/${name}`,
+        });
+        continue;
+      }
+
+      await emitServerFunction(root, ctx, name, route, key, options);
       routes.push({
         id: `server-${name}`,
         match: routeMatch(route),
@@ -294,21 +424,71 @@ async function emitRouteOutputs(
   return { routes, artifacts };
 }
 
+async function emitEdgeBundle(
+  root: string,
+  ctx: BuildContext,
+  name: string,
+  route: RouteOutput,
+  routeGroup: NextRouteOutputGroup,
+): Promise<void> {
+  const entry = `edge/${name}/index.js`;
+  await copyEntryFile(edgeRuntimeModulePath(route), path.join(root, entry));
+  await writeJson(path.join(root, "edge", name, "edge.json"), {
+    name,
+    runtime: "edge",
+    entry: "index.js",
+    handlerProtocol: "fetch",
+    framework: {
+      name: "next",
+      version: ctx.nextVersion ?? "unknown",
+      routeGroup,
+      outputType: route.type,
+    },
+    source: sourceForRoute(ctx, route),
+  });
+}
+
 async function emitMiddleware(
   root: string,
+  ctx: BuildContext,
   middleware: RouteOutput | undefined,
+  options: UnioNextjsAdapterOptions,
 ): Promise<Pick<GeneratedUboa, "middleware" | "artifacts">> {
   if (!middleware) return { middleware: [], artifacts: [] };
 
   const name = "middleware";
-  await emitServerFunction(root, name, middleware);
+
+  if (middleware.runtime === "edge") {
+    const entry = `edge/${name}/index.js`;
+    await emitEdgeBundle(root, ctx, name, middleware, "middleware");
+
+    return {
+      middleware: [
+        {
+          name,
+          match: middlewareMatchers(middleware),
+          runtime: "edge",
+          entry,
+        },
+      ],
+      artifacts: [
+        {
+          id: name,
+          resourceKind: "edgeBundle",
+          path: `edge/${name}`,
+        },
+      ],
+    };
+  }
+
+  await emitServerFunction(root, ctx, name, middleware, "middleware", options);
 
   return {
     middleware: [
       {
         name,
         match: middlewareMatchers(middleware),
-        runtime: "serverless",
+        runtime: "nodejs",
         serverFunction: name,
       },
     ],
@@ -322,7 +502,25 @@ async function emitMiddleware(
   };
 }
 
-export async function emitUboaOutput(ctx: BuildContext): Promise<GeneratedUboa> {
+async function emitDynamicServerOutput(
+  root: string,
+  ctx: BuildContext,
+  options: UnioNextjsAdapterOptions,
+): Promise<DynamicServerOutput> {
+  const routeOutput = await emitRouteOutputs(root, ctx, options);
+  const middlewareOutput = await emitMiddleware(root, ctx, ctx.outputs.middleware, options);
+
+  return {
+    routes: routeOutput.routes,
+    middleware: middlewareOutput.middleware,
+    artifacts: [...routeOutput.artifacts, ...middlewareOutput.artifacts],
+  };
+}
+
+export async function emitUboaOutput(
+  ctx: BuildContext,
+  options: UnioNextjsAdapterOptions = {},
+): Promise<GeneratedUboa> {
   assertSupportedOutputs(ctx);
 
   const root = path.join(ctx.projectDir, ".unio", "output");
@@ -331,10 +529,9 @@ export async function emitUboaOutput(ctx: BuildContext): Promise<GeneratedUboa>
 
   const staticFiles = [...ctx.outputs.staticFiles, ...ctx.outputs.prerenders];
   const staticRoutes = await emitStaticFiles(root, staticFiles);
-  const routeOutput = await emitRouteOutputs(root, ctx);
-  const middlewareOutput = await emitMiddleware(root, ctx.outputs.middleware);
+  const dynamicOutput = await emitDynamicServerOutput(root, ctx, options);
 
-  const artifacts: UboaArtifact[] = [];
+  let artifacts: UboaArtifact[] = [];
   if (staticFiles.length > 0) {
     artifacts.push({
       id: "static",
@@ -342,15 +539,49 @@ export async function emitUboaOutput(ctx: BuildContext): Promise<GeneratedUboa>
       path: "static",
     });
   }
-  artifacts.push(...routeOutput.artifacts, ...middlewareOutput.artifacts);
+  artifacts.push(...dynamicOutput.artifacts);
+
+  const routes = [...staticRoutes, ...dynamicOutput.routes];
+  const middleware = dynamicOutput.middleware;
+  const capabilities = buildCapabilities(ctx);
+  const warnings = buildWarnings(ctx);
+
+  if (options.extendArtifacts) {
+    const extendedArtifacts = await options.extendArtifacts({
+      artifacts,
+      routes,
+      middleware,
+      ctx,
+    });
 
-  const routes = [...staticRoutes, ...routeOutput.routes];
-  const middleware = middlewareOutput.middleware;
+    if (!Array.isArray(extendedArtifacts)) {
+      throw new Error("extendArtifacts must return an array.");
+    }
 
-  await emitCoreManifest(root, ctx);
+    artifacts = extendedArtifacts;
+  }
+
+  const generated: GeneratedUboa = {
+    outputDir: root,
+    routes,
+    middleware,
+    artifacts,
+    capabilities,
+    warnings,
+  };
+
+  await emitCoreManifest(root, ctx, capabilities, warnings);
   await writeJson(path.join(root, "routes.json"), routes);
   await writeJson(path.join(root, "middleware.json"), middleware);
   await writeJson(path.join(root, "artifacts.json"), { artifacts });
+  await emitFeaturesManifest(root);
+  await emitObservabilityManifest(root, ctx);
+
+  await options.afterEmit?.({
+    outputDir: root,
+    generated,
+    ctx,
+  });
 
-  return { routes, middleware, artifacts };
+  return generated;
 }

package/dist/assert-ssg.d.ts

@@ -1,5 +0,0 @@
-import type { Outputs } from "./types.js";
-/**
- * Validate that a Next.js output set is pure static export.
- */
-export declare function assertSsgOnly(outputs: Outputs): void;