@spfn/core 0.3.0-beta.17 → 0.3.0-beta.19

package/dist/codegen/index.d.ts

@@ -379,6 +379,7 @@ declare class RouteMapGeneratorError extends Error {
  *         defineGenerator({
  *             name: '@spfn/core:contract',
  *             routerPath: './src/server/router.ts',
+ *             eventRouterPath: './src/server/events.ts',   // optional: contracted SSE events
  *             outputDir: './contracts',
  *         })
  *     ]
@@ -401,6 +402,18 @@ interface ContractGeneratorConfig {
      * @default 'appRouter', falling back to the default export
      */
     routerExport?: string;
+    /**
+     * Path to the file exporting the `defineEventRouter()` result (relative to
+     * project root). When set, its contracted events are written into the
+     * document's `events` section; unset, the document has none.
+     * @example './src/server/events.ts'
+     */
+    eventRouterPath?: string;
+    /**
+     * Named export holding the event router.
+     * @default 'eventRouter', falling back to the default export
+     */
+    eventRouterExport?: string;
     /**
      * Directory holding current.json, released/ and usage/ (relative to project root)
      * @default './contracts'
@@ -466,7 +479,14 @@ interface RegistrationScan {
     exportName: string;
     /** What is being generated, named in the message: `route map`, `contract`. */
     subject: string;
+    /**
+     * The call the router is built with. `defineEventRouter` scans an event
+     * router file, whose event set the contract publishes the same way.
+     * @default 'defineRouter'
+     */
+    factory?: RouterFactory;
 }
+type RouterFactory = 'defineRouter' | 'defineEventRouter';
 /**
  * Refuse a router whose route set depends on a condition.
  */

package/dist/codegen/index.js

@@ -348,6 +348,18 @@ var ConditionalRegistrationError = class extends Error {
     this.name = "ConditionalRegistrationError";
   }
 };
+var REFUSAL_WORDING = {
+  defineRouter: {
+    noun: "routes",
+    consequence: "a route production registers is left out, and the client that addresses it by name gets a 404",
+    remedy: "Register the route unconditionally and gate its behaviour inside the handler instead."
+  },
+  defineEventRouter: {
+    noun: "events",
+    consequence: "an event production streams is left out, and the client that subscribes to it by name gets a 400",
+    remedy: "Register the event unconditionally and decide who receives it with the stream's authorize hook instead."
+  }
+};
 function assertUnconditionalRegistration(scan) {
   const compiler2 = typescript();
   const file = compiler2.createSourceFile(
@@ -358,11 +370,14 @@ function assertUnconditionalRegistration(scan) {
     false
   );
   const declarations = topLevelInitialisers(compiler2, file);
-  const routes = routesLiteral(compiler2, declarations.get(scan.exportName), declarations, /* @__PURE__ */ new Set());
+  const routes = routesLiteral(compiler2, declarations.get(scan.exportName), declarations, /* @__PURE__ */ new Set(), factoryOf(scan));
   if (routes) {
     assertLiteral(compiler2, file, routes, declarations, /* @__PURE__ */ new Set(), scan);
   }
 }
+function factoryOf(scan) {
+  return scan.factory ?? "defineRouter";
+}
 function topLevelInitialisers(compiler2, file) {
   const found = /* @__PURE__ */ new Map();
   for (const statement of file.statements) {
@@ -404,7 +419,7 @@ function unwrap(compiler2, expression) {
   }
   return expression;
 }
-function routesLiteral(compiler2, expression, declarations, seen) {
+function routesLiteral(compiler2, expression, declarations, seen, factory) {
   const node = unwrap(compiler2, expression);
   if (!node) {
     return void 0;
@@ -414,17 +429,17 @@ function routesLiteral(compiler2, expression, declarations, seen) {
       return void 0;
     }
     seen.add(node.text);
-    return routesLiteral(compiler2, declarations.get(node.text), declarations, seen);
+    return routesLiteral(compiler2, declarations.get(node.text), declarations, seen, factory);
   }
   if (!compiler2.isCallExpression(node)) {
     return void 0;
   }
   const callee = unwrap(compiler2, node.expression);
-  if (callee && compiler2.isIdentifier(callee) && callee.text === "defineRouter") {
+  if (callee && compiler2.isIdentifier(callee) && callee.text === factory) {
     const routes = unwrap(compiler2, node.arguments[0]);
     return routes && compiler2.isObjectLiteralExpression(routes) ? routes : void 0;
   }
-  return callee && compiler2.isPropertyAccessExpression(callee) ? routesLiteral(compiler2, callee.expression, declarations, seen) : void 0;
+  return callee && compiler2.isPropertyAccessExpression(callee) ? routesLiteral(compiler2, callee.expression, declarations, seen, factory) : void 0;
 }
 function assertLiteral(compiler2, file, literal, declarations, seen, scan) {
   for (const property of literal.properties) {
@@ -432,7 +447,7 @@ function assertLiteral(compiler2, file, literal, declarations, seen, scan) {
       assertUnconditionalSpread(compiler2, file, property.expression, scan);
       continue;
     }
-    const nested = routesLiteral(compiler2, mountedRouter(compiler2, property), declarations, seen);
+    const nested = routesLiteral(compiler2, mountedRouter(compiler2, property), declarations, seen, factoryOf(scan));
     if (nested) {
       assertLiteral(compiler2, file, nested, declarations, seen, scan);
     }
@@ -449,11 +464,12 @@ function assertUnconditionalSpread(compiler2, file, expression, scan) {
   if (!condition) {
     return;
   }
+  const wording = REFUSAL_WORDING[factoryOf(scan)];
   throw new ConditionalRegistrationError(
-    `${scan.routerPath} registers routes conditionally: "...${spreadText(file, expression)}" (${condition}).
+    `${scan.routerPath} registers ${wording.noun} conditionally: "...${spreadText(file, expression)}" (${condition}).
 
-The ${scan.subject} is generated from the router as it loads, so a route set that depends on a flag or an environment describes whichever way the generator happened to run: a route production registers is left out, and the client that addresses it by name gets a 404.
-Register the route unconditionally and gate its behaviour inside the handler instead.`
+The ${scan.subject} is generated from the router as it loads, so a set of ${wording.noun} that depends on a flag or an environment describes whichever way the generator happened to run: ${wording.consequence}.
+` + wording.remedy
   );
 }
 function conditionKind(compiler2, expression) {
@@ -985,10 +1001,51 @@ function loadRouter2(cwd, absoluteRouterPath, routerExport) {
     `No router found in ${relative(cwd, absoluteRouterPath)}. Looked for: ${candidates.join(", ")}. Set "routerExport" to the export holding the defineRouter() result.`
   );
 }
+function isEventRouter(value) {
+  return value !== null && typeof value === "object" && "events" in value && "eventNames" in value;
+}
+function loadEventRouter(cwd, absolutePath, eventRouterExport) {
+  const module = loadRouterModule({
+    cwd,
+    absoluteRouterPath: absolutePath,
+    subject: "contract",
+    fail: (message) => new ContractGeneratorError(message)
+  });
+  const candidates = eventRouterExport ? [eventRouterExport] : ["eventRouter", "default"];
+  const exportName = candidates.find((candidate) => isEventRouter(module[candidate]));
+  if (exportName) {
+    return { eventRouter: module[exportName], exportName };
+  }
+  throw new ContractGeneratorError(
+    `No event router found in ${relative(cwd, absolutePath)}. Looked for: ${candidates.join(", ")}. Set "eventRouterExport" to the export holding the defineEventRouter() result.`
+  );
+}
+function readEventRouter(cwd, eventRouterPath, eventRouterExport) {
+  if (!eventRouterPath) {
+    return void 0;
+  }
+  const absolutePath = join(cwd, eventRouterPath);
+  if (!existsSync(absolutePath)) {
+    throw new ContractGeneratorError(
+      `Event router file not found: ${eventRouterPath}. The contract generator is configured with "eventRouterPath" but has nothing to read there.`
+    );
+  }
+  const { eventRouter, exportName } = loadEventRouter(cwd, absolutePath, eventRouterExport);
+  assertUnconditionalRegistration({
+    routerPath: eventRouterPath,
+    source: readFileSync(absolutePath, "utf-8"),
+    exportName,
+    subject: "contract",
+    factory: "defineEventRouter"
+  });
+  return eventRouter;
+}
 function createContractGenerator(config) {
   const {
     routerPath,
     routerExport,
+    eventRouterPath,
+    eventRouterExport,
     outputDir = "./contracts",
     additionalRouteDirs = []
   } = config;
@@ -1007,6 +1064,7 @@ Usage:
     name: "@spfn/core:contract",
     watchPatterns: [
       routerPath,
+      ...eventRouterPath ? [eventRouterPath] : [],
       "src/server/routes/**/*.ts",
       ...additionalRouteDirs.map((dir) => `${dir}/**/*.ts`)
     ],
@@ -1028,7 +1086,7 @@ Usage:
         exportName,
         subject: "contract"
       });
-      const document = collectContractDocument(router);
+      const document = collectContractDocument(router, readEventRouter(cwd, eventRouterPath, eventRouterExport));
       const changed = writeCurrentDocument(contractsDir, document);
       genLogger2.info(
         `${changed ? "Wrote" : "Verified"} ${relative(cwd, join(contractsDir, "current.json"))} (${document.operations.length} contracted operation(s))`