Make route CommonJS require work after bundling and name unsupported packages

docs/guides/api-routes.md

@@ -220,6 +220,35 @@ export function GET() {
 }
 ```
 
+## npm packages
+
+API routes can import packages listed in the project's `package.json`. The
+package must be installed in the project's `node_modules` where the server
+runs. CommonJS packages support default, named, namespace and dynamic
+`import()` forms. A namespace import or a dynamic `import()` exposes the
+package's `module.exports` as `default`, alongside its named properties.
+
+Import packages by their root name or by a file path inside the package. Subpath
+names defined only in a package's `exports` map, or a package whose `exports`
+field is a single string, may not resolve. A package is treated as CommonJS or
+ESM as a whole, so an `.mjs` file inside a CommonJS package fails with
+`ES module file "<path>" cannot be loaded with require`. Re-export named
+values from a CommonJS package (`export { name } from "pkg"`); `export * from
+"pkg"` is not supported, because its names are only known at run time.
+Inside a CommonJS package, `import("./file.mjs")` with a literal relative or
+absolute path loads that file relative to the package; a computed specifier
+does not.
+
+Packages that ship a native addon (`.node` file) are not supported. Loading one
+fails with `native addon "<path>" cannot be loaded`. A package that is listed
+but not installed fails with `npm package "<name>" is not installed in this
+runtime's node_modules`.
+
+A static `import` resolves when the route module loads, so either error makes
+every request to the route fail until the dependency is changed. A dynamic
+`import()` resolves when it runs: only requests that reach it fail, and the
+handler can catch the rejected promise.
+
 ## Chat endpoint
 
 The most common API route pattern in Veryfront connects a chat UI to an agent:

src/routing/api/module-loader/loader-helpers.test.ts

@@ -41,6 +41,14 @@ describe("routing/api/module-loader helpers", () => {
     );
     assertEquals(toCjsDestructureBindings("{ foo, bar }"), "{ foo, bar }");
     assertEquals(toCjsDestructureBindings("{   }"), "{}");
+    assertEquals(
+      toCjsDestructureBindings(`{ "a-b" as value, 'c,d' as other, e, }`),
+      `{ "a-b": value, 'c,d': other, e }`,
+    );
+    assertEquals(
+      toCjsDestructureBindings("{ café as c2, caf\\u00e9 }"),
+      "{ café: c2, caf\\u00e9 }",
+    );
   });
 
   it("returns the expected file loaders and extensions", () => {

src/routing/api/module-loader/loader-helpers.ts

@@ -46,21 +46,107 @@
   return undefined;
 }
 
-export function toCjsDestructureBindings(bindings: string): string {
-  const inner = bindings.trim().replace(/^\{\s*/, "").trimEnd().replace(/\}$/, "");
-  if (!inner) return "{}";
+/**
+ * A JavaScript identifier, including Unicode letters and `\u` escapes, as
+ * the source of a RegExp built with the `u` flag.
+ */
+export const JS_IDENTIFIER = "(?:[\\p{ID_Start}$_]|\\\\u[0-9a-fA-F]{4}|\\\\u\\{[0-9a-fA-F]+\\})" +
+  "(?:[\\p{ID_Continue}$\\u200C\\u200D]|\\\\u[0-9a-fA-F]{4}|\\\\u\\{[0-9a-fA-F]+\\})*";
+
+/** A single- or double-quoted string literal, as the source of a RegExp. */
+export const JS_STRING_LITERAL = `"(?:[^"\\\\\\r\\n]|\\\\.)*"|'(?:[^'\\\\\\r\\n]|\\\\.)*'`;
+
+const SPECIFIER_ENTRY = new RegExp(
+  `\\s*(?:(${JS_STRING_LITERAL})|(${JS_IDENTIFIER}))` +
+    `(?:\\s+as\\s+(?:(${JS_STRING_LITERAL})|(${JS_IDENTIFIER})))?\\s*(?:,|$)`,
+  "uy",
+);
+
+/** One `name as alias` entry of an import or export clause, as source text. */
+export interface ModuleSpecifier {
+  /** The name in the other module: an identifier or a string literal. */
+  readonly name: string;
+  readonly nameIsString: boolean;
+  /** The local or exported name, if it differs: an identifier or a string literal. */
+  readonly alias?: string;
+  readonly aliasIsString: boolean;
+}
 
-  const converted = inner
-    .split(",")
-    .map((part) => part.trim())
-    .filter(Boolean)
-    .map((part) => {
-      const aliasMatch = part.match(/^([A-Za-z_$][\w$]*)\s+as\s+([A-Za-z_$][\w$]*)$/);
-      if (aliasMatch) return `${aliasMatch[1]}: ${aliasMatch[2]}`;
-      return part;
+/** Parse a `{ ... }` import or export clause. Throws on anything else. */
+export function parseModuleSpecifiers(clause: string): ModuleSpecifier[] {
+  const trimmed = clause.trim();
+  if (!trimmed.startsWith("{") || !trimmed.endsWith("}")) {
+    throw new Error(`Unsupported import or export clause: ${clause}`);
+  }
+  const inner = trimmed.slice(1, -1);
+  const specifiers: ModuleSpecifier[] = [];
+  const entry = new RegExp(SPECIFIER_ENTRY.source, SPECIFIER_ENTRY.flags);
+  while (inner.slice(entry.lastIndex).trim() !== "") {
+    const start = entry.lastIndex;
+    const match = entry.exec(inner);
+    if (!match || entry.lastIndex === start) {
+      throw new Error(`Unsupported import or export clause: ${clause}`);
+    }
+    const [, nameString, nameIdent, aliasString, aliasIdent] = match;
+    specifiers.push({
+      name: (nameString ?? nameIdent)!,
+      nameIsString: nameString !== undefined,
+      alias: aliasString ?? aliasIdent,
+      aliasIsString: aliasString !== undefined,
     });
+  }
+  return specifiers;
+}
+
+const SIMPLE_ESCAPES: Record<string, string> = {
+  b: "\b",
+  f: "\f",
+  n: "\n",
+  r: "\r",
+  t: "\t",
+  v: "\v",
+  "0": "\0",
+};
+
+/**
+ * The name a specifier's `name` denotes, with string-literal quotes removed
+ * and escapes decoded, so `default`, `"default"` and `\u0064efault` compare
+ * equal.
+ */
+export function moduleExportNameValue(specifier: ModuleSpecifier): string {
+  const source = specifier.nameIsString ? specifier.name.slice(1, -1) : specifier.name;
+  return source.replace(
+    /\\(?:u\{([0-9a-fA-F]+)\}|u([0-9a-fA-F]{4})|x([0-9a-fA-F]{2})|(\r\n|[\s\S]))/g,
+    (_match, codePoint?: string, unit?: string, byte?: string, other?: string) => {
+      const hex = codePoint ?? unit ?? byte;
+      if (hex !== undefined) return String.fromCodePoint(parseInt(hex, 16));
+      if (
+        other === "\n" || other === "\r" || other === "\r\n" || other === "\u2028" ||
+        other === "\u2029"
+      ) {
+        return "";
+      }
+      return SIMPLE_ESCAPES[other!] ?? other!;
+    },
+  );
+}
 
-  return `{ ${converted.join(", ")} }`;
+/**
+ * Convert a named import clause (`{ a, b as c, "d-e" as f }`) to a
+ * destructuring pattern (`{ a, b: c, "d-e": f }`). A string-literal name
+ * needs an identifier alias, as in the import itself.
+ */
+export function toCjsDestructureBindings(bindings: string): string {
+  const converted: string[] = [];
+  for (const specifier of parseModuleSpecifiers(bindings)) {
+    if (specifier.aliasIsString || (specifier.nameIsString && specifier.alias === undefined)) {
+      throw new Error(`Unsupported named import clause: ${bindings}`);
+    }
+    converted.push(
+      specifier.alias === undefined ? specifier.name : `${specifier.name}: ${specifier.alias}`,
+    );
+  }
+  return converted.length === 0 ? "{}" : `{ ${converted.join(", ")} }`;
 }
 
 export function getLoaderForFile(filePath: string): "tsx" | "jsx" | "ts" | "js" | "json" {