pastoria 1.0.8 → 1.0.9

package/src/generate.ts

@@ -20,6 +20,7 @@
  * - Add @resource <resource-name> to exports for lazy loading
  * - Add @appRoot to a component to designate it as the application root wrapper
  * - Add @gqlContext to a class extending PastoriaRootContext to provide a custom GraphQL context
+ * - Add @serverRoute to functions to add an express handler
  *
  * The generator automatically creates Zod schemas for route parameters based on
  * TypeScript types, enabling runtime validation and type safety.
@@ -27,25 +28,20 @@
 
 import {readFile} from 'node:fs/promises';
 import * as path from 'node:path';
-import {default as pc} from 'picocolors';
-import {Project, SourceFile, Symbol, SyntaxKind, ts, TypeFlags} from 'ts-morph';
-
-const JS_RESOURCE_FILENAME = '__generated__/router/js_resource.ts';
-const JS_RESOURCE_TEMPLATE = path.join(
-  import.meta.dirname,
-  '../templates/js_resource.ts',
-);
-
-const ROUTER_FILENAME = '__generated__/router/router.tsx';
-const ROUTER_TEMPLATE = path.join(
-  import.meta.dirname,
-  '../templates/router.tsx',
-);
-
-const APP_ROOT_FILENAME = '__generated__/router/app_root.ts';
-const CONTEXT_FILENAME = '__generated__/router/context.ts';
-
-async function loadRouterFiles(project: Project) {
+import pc from 'picocolors';
+import {
+  CodeBlockWriter,
+  IndentationText,
+  Project,
+  SourceFile,
+  Symbol,
+  SyntaxKind,
+  ts,
+  TypeFlags,
+  WriterFunction,
+} from 'ts-morph';
+
+async function loadRouterTemplates(project: Project, filename: string) {
   async function loadSourceFile(fileName: string, templateFileName: string) {
     const template = await readFile(templateFileName, 'utf-8');
     const warningComment = `/*
@@ -59,50 +55,51 @@ async function loadRouterFiles(project: Project) {
     });
   }
 
-  const [jsResource, router] = await Promise.all([
-    loadSourceFile(JS_RESOURCE_FILENAME, JS_RESOURCE_TEMPLATE),
-    loadSourceFile(ROUTER_FILENAME, ROUTER_TEMPLATE),
-  ]);
-
-  return {jsResource, router} as const;
+  const template = path.join(import.meta.dirname, '../templates', filename);
+  const output = path.join('__generated__/router', filename);
+  return loadSourceFile(output, template);
 }
 
 type RouterResource = {
-  resourceName: string;
   sourceFile: SourceFile;
   symbol: Symbol;
+  queries: Map<string, string>;
+  entryPoints: Map<string, string>;
 };
 
 type RouterRoute = {
-  routeName: string;
   sourceFile: SourceFile;
   symbol: Symbol;
   params: Map<string, ts.Type>;
 };
 
-type AppRoot = {
+type ExportedSymbol = {
   sourceFile: SourceFile;
   symbol: Symbol;
 };
 
-type GqlContext = {
-  sourceFile: SourceFile;
-  symbol: Symbol;
-};
+interface PastoriaMetadata {
+  resources: Map<string, RouterResource>;
+  routes: Map<string, RouterRoute>;
+  serverHandlers: Map<string, ExportedSymbol>;
+  appRoot: ExportedSymbol | null;
+  gqlContext: ExportedSymbol | null;
+}
 
 // Regex to quickly check if a file contains any Pastoria JSDoc tags
-const PASTORIA_TAG_REGEX = /@(route|resource|appRoot|param|gqlContext)\b/;
-
-function collectRouterNodes(project: Project): {
-  resources: RouterResource[];
-  routes: RouterRoute[];
-  appRoot: AppRoot | null;
-  gqlContext: GqlContext | null;
-} {
-  const resources: RouterResource[] = [];
-  const routes: RouterRoute[] = [];
-  let appRoot: AppRoot | null = null;
-  let gqlContext: GqlContext | null = null;
+const PASTORIA_TAG_REGEX =
+  /@(route|resource|appRoot|param|gqlContext|serverRoute)\b/;
+
+/**
+ *
+ * @query {abc} 123
+ */
+function collectPastoriaMetadata(project: Project): PastoriaMetadata {
+  const resources = new Map<string, RouterResource>();
+  const routes = new Map<string, RouterRoute>();
+  const serverHandlers = new Map<string, ExportedSymbol>();
+  let appRoot: ExportedSymbol | null = null;
+  let gqlContext: ExportedSymbol | null = null;
 
   function visitRouterNodes(sourceFile: SourceFile) {
     // Skip generated files
@@ -117,8 +114,10 @@ function collectRouterNodes(project: Project): {
     }
 
     sourceFile.getExportSymbols().forEach((symbol) => {
-      let routerResource = null as RouterResource | null;
-      let routerRoute = null as RouterRoute | null;
+      let routerResource = null as [string, RouterResource] | null;
+      const resourceQueries = new Map<string, string>();
+      const resourceEntryPoints = new Map<string, string>();
+      let routerRoute = null as [string, RouterRoute] | null;
       const routeParams = new Map<string, ts.Type>();
 
       function visitJSDocTags(tag: ts.JSDoc | ts.JSDocTag) {
@@ -137,25 +136,51 @@ function collectRouterNodes(project: Project): {
         } else if (typeof tag.comment === 'string') {
           switch (tag.tagName.getText()) {
             case 'route': {
-              routerRoute = {
-                routeName: tag.comment,
-                sourceFile,
-                symbol,
-                params: routeParams,
-              };
+              routerRoute = [
+                tag.comment,
+                {sourceFile, symbol, params: routeParams},
+              ];
               break;
             }
             case 'resource': {
-              routerResource = {
-                resourceName: tag.comment,
-                sourceFile,
-                symbol,
-              };
+              routerResource = [
+                tag.comment,
+                {
+                  sourceFile,
+                  symbol,
+                  queries: resourceQueries,
+                  entryPoints: resourceEntryPoints,
+                },
+              ];
+              break;
+            }
+            case 'serverRoute': {
+              serverHandlers.set(tag.comment, {sourceFile, symbol});
+              break;
+            }
+            case 'query': {
+              const match = tag.comment.match(
+                /^\s*\{\s*(?<query>\w+)\s*\}\s+(?<name>\w+)\s*$/,
+              )?.groups;
+
+              if (match && match.query && match.name) {
+                resourceQueries.set(match.name, match.query);
+              }
+              break;
+            }
+            case 'entrypoint': {
+              const match = tag.comment.match(
+                /^\s*\{\s*(?<resource>[\w#]+)\s*\}\s+(?<name>\w+)\s*$/,
+              )?.groups;
+
+              if (match && match.resource && match.name) {
+                resourceEntryPoints.set(match.name, match.resource);
+              }
               break;
             }
           }
         } else {
-          // Handle tags without comments (like @appRoot, @gqlContext)
+          // Handle tags without comments (like @ExportedSymbol, @gqlContext)
           switch (tag.tagName.getText()) {
             case 'appRoot': {
               if (appRoot != null) {
@@ -218,13 +243,18 @@ function collectRouterNodes(project: Project): {
         .flatMap((decl) => ts.getJSDocCommentsAndTags(decl.compilerNode))
         .forEach(visitJSDocTags);
 
-      if (routerRoute != null) routes.push(routerRoute);
-      if (routerResource != null) resources.push(routerResource);
+      if (routerRoute != null) {
+        routes.set(routerRoute[0], routerRoute[1]);
+      }
+
+      if (routerResource != null) {
+        resources.set(routerResource[0], routerResource[1]);
+      }
     });
   }
 
   project.getSourceFiles().forEach(visitRouterNodes);
-  return {resources, routes, appRoot, gqlContext};
+  return {resources, routes, appRoot, gqlContext, serverHandlers};
 }
 
 function zodSchemaOfType(tc: ts.TypeChecker, t: ts.Type): string {
@@ -260,53 +290,287 @@ function zodSchemaOfType(tc: ts.TypeChecker, t: ts.Type): string {
   }
 }
 
-export async function generatePastoriaArtifacts() {
-  const targetDir = process.cwd();
-  const project = new Project({
-    tsConfigFilePath: path.join(targetDir, 'tsconfig.json'),
-  });
+function writeEntryPoint(
+  writer: CodeBlockWriter,
+  metadata: PastoriaMetadata,
+  consumedQueries: Set<string>,
+  resourceName: string,
+  resource: RouterResource,
+  parseVars = true,
+) {
+  writer.writeLine(`root: JSResource.fromModuleId('${resourceName}'),`);
+  writer
+    .write(`getPreloadProps(${parseVars ? '{params, schema}' : ''})`)
+    .block(() => {
+      if (parseVars) {
+        writer.writeLine('const variables = schema.parse(params);');
+      }
+
+      writer.write('return').block(() => {
+        writer
+          .write('queries:')
+          .block(() => {
+            for (const [queryRef, query] of resource.queries.entries()) {
+              consumedQueries.add(query);
+
+              writer
+                .write(`${queryRef}:`)
+                .block(() => {
+                  writer.writeLine(`parameters: ${query}Parameters,`);
+                  writer.writeLine(`variables`);
+                })
+                .write(',');
+            }
+          })
+          .writeLine(',');
+
+        writer.write('entryPoints:').block(() => {
+          for (const [
+            epRef,
+            subresourceName,
+          ] of resource.entryPoints.entries()) {
+            const subresource = metadata.resources.get(subresourceName);
+            if (subresource) {
+              writer.write(`${epRef}:`).block(() => {
+                writer.writeLine(`entryPointParams: {},`);
+                writer.write('entryPoint:').block(() => {
+                  writeEntryPoint(
+                    writer,
+                    metadata,
+                    consumedQueries,
+                    subresourceName,
+                    subresource,
+                    false,
+                  );
+                });
+              });
+            }
+          }
+        });
+      });
+    });
+}
 
+async function generateRouter(project: Project, metadata: PastoriaMetadata) {
+  const routerTemplate = await loadRouterTemplates(project, 'router.tsx');
   const tc = project.getTypeChecker().compilerObject;
-  const routerFiles = await loadRouterFiles(project);
-  const routerNodes = collectRouterNodes(project);
-
-  // Generate app_root.ts if @appRoot tag is found
-  const appRoot: AppRoot | null = routerNodes.appRoot;
-  if (appRoot != null) {
-    const appRootSourceFile: SourceFile = appRoot.sourceFile;
-    const appRootSymbol: Symbol = appRoot.symbol;
-    const filePath = path.relative(targetDir, appRootSourceFile.getFilePath());
-    const appRootFile = project.createSourceFile(APP_ROOT_FILENAME, '', {
-      overwrite: true,
+
+  const routerConf = routerTemplate
+    .getVariableDeclarationOrThrow('ROUTER_CONF')
+    .getInitializerIfKindOrThrow(SyntaxKind.AsExpression)
+    .getExpressionIfKindOrThrow(SyntaxKind.ObjectLiteralExpression);
+
+  routerConf.getPropertyOrThrow('noop').remove();
+
+  let entryPointImportIndex = 0;
+  for (const [
+    routeName,
+    {sourceFile, symbol, params},
+  ] of metadata.routes.entries()) {
+    const filePath = path.relative(process.cwd(), sourceFile.getFilePath());
+    let entryPointExpression: string;
+
+    // Resource-routes are combined declarations of a resource and a route
+    // where we should generate the entrypoint for the route.
+    const isResourceRoute = Array.from(metadata.resources.entries()).find(
+      ([, {symbol: resourceSymbol}]) => symbol === resourceSymbol,
+    );
+
+    if (isResourceRoute) {
+      const [resourceName, resource] = isResourceRoute;
+      const entryPointFunctionName = `entrypoint_${resourceName.replace(/\W/g, '__')}`;
+
+      routerTemplate.addImportDeclaration({
+        moduleSpecifier: './js_resource',
+        namedImports: ['JSResource', 'ModuleType'],
+      });
+
+      const consumedQueries = new Set<string>();
+      routerTemplate.addFunction({
+        name: entryPointFunctionName,
+        returnType: `EntryPoint<ModuleType<'${resourceName}'>, EntryPointParams<'${routeName}'>>`,
+        statements: (writer) => {
+          writer.write('return ').block(() => {
+            writeEntryPoint(
+              writer,
+              metadata,
+              consumedQueries,
+              resourceName,
+              resource,
+            );
+          });
+        },
+      });
+
+      for (const query of consumedQueries) {
+        routerTemplate.addImportDeclaration({
+          moduleSpecifier: `#genfiles/queries/${query}$parameters`,
+          defaultImport: `${query}Parameters`,
+        });
+      }
+
+      entryPointExpression = entryPointFunctionName + '()';
+    } else {
+      const importAlias = `e${entryPointImportIndex++}`;
+      const moduleSpecifier = routerTemplate.getRelativePathAsModuleSpecifierTo(
+        sourceFile.getFilePath(),
+      );
+
+      routerTemplate.addImportDeclaration({
+        moduleSpecifier,
+        namedImports: [
+          {
+            name: symbol.getName(),
+            alias: importAlias,
+          },
+        ],
+      });
+
+      entryPointExpression = importAlias;
+    }
+
+    routerConf.addPropertyAssignment({
+      name: `"${routeName}"`,
+      initializer: (writer) => {
+        writer
+          .write('{')
+          .indent(() => {
+            writer.writeLine(`entrypoint: ${entryPointExpression},`);
+            if (params.size === 0) {
+              writer.writeLine(`schema: z.object({})`);
+            } else {
+              writer.writeLine(`schema: z.object({`);
+              for (const [paramName, paramType] of Array.from(params)) {
+                writer.writeLine(
+                  `  ${paramName}: ${zodSchemaOfType(tc, paramType)},`,
+                );
+              }
+
+              writer.writeLine('})');
+            }
+          })
+          .write('} as const');
+      },
     });
 
-    const moduleSpecifier = appRootFile.getRelativePathAsModuleSpecifierTo(
-      appRootSourceFile.getFilePath(),
+    console.log(
+      'Created route',
+      pc.cyan(routeName),
+      'for',
+      pc.green(symbol.getName()),
+      'exported from',
+      pc.yellow(filePath),
     );
+  }
 
-    appRootFile.addStatements(`/*
- * This file was generated by \`pastoria\`.
- * Do not modify this file directly.
- */
+  await routerTemplate.save();
+}
 
-export {${appRootSymbol.getName()} as App} from '${moduleSpecifier}';
-`);
+async function generateJsResource(
+  project: Project,
+  metadata: PastoriaMetadata,
+) {
+  const jsResourceTemplate = await loadRouterTemplates(
+    project,
+    'js_resource.ts',
+  );
 
-    await appRootFile.save();
+  const resourceConf = jsResourceTemplate
+    .getVariableDeclarationOrThrow('RESOURCE_CONF')
+    .getInitializerIfKindOrThrow(SyntaxKind.AsExpression)
+    .getExpressionIfKindOrThrow(SyntaxKind.ObjectLiteralExpression);
+
+  resourceConf.getPropertyOrThrow('noop').remove();
+  for (const [
+    resourceName,
+    {sourceFile, symbol},
+  ] of metadata.resources.entries()) {
+    const filePath = path.relative(process.cwd(), sourceFile.getFilePath());
+    const moduleSpecifier =
+      jsResourceTemplate.getRelativePathAsModuleSpecifierTo(
+        sourceFile.getFilePath(),
+      );
+
+    resourceConf.addPropertyAssignment({
+      name: `"${resourceName}"`,
+      initializer: (writer) => {
+        writer.block(() => {
+          writer
+            .writeLine(`src: "${filePath}",`)
+            .writeLine(
+              `loader: () => import("${moduleSpecifier}").then(m => m.${symbol.getName()})`,
+            );
+        });
+      },
+    });
 
     console.log(
-      'Created app root for',
-      pc.green(appRootSymbol.getName()),
+      'Created resource',
+      pc.cyan(resourceName),
+      'for',
+      pc.green(symbol.getName()),
       'exported from',
       pc.yellow(filePath),
     );
   }
 
-  // Generate context.ts
-  const gqlContext: GqlContext | null = routerNodes.gqlContext;
-  const contextFile = project.createSourceFile(CONTEXT_FILENAME, '', {
-    overwrite: true,
-  });
+  await jsResourceTemplate.save();
+}
+
+async function generateAppRoot(project: Project, metadata: PastoriaMetadata) {
+  const targetDir = process.cwd();
+  const appRoot: ExportedSymbol | null = metadata.appRoot;
+
+  if (appRoot == null) {
+    await project
+      .getSourceFile('__generated__/router/app_root.ts')
+      ?.deleteImmediately();
+
+    return;
+  }
+
+  const appRootSourceFile: SourceFile = appRoot.sourceFile;
+  const appRootSymbol: Symbol = appRoot.symbol;
+  const filePath = path.relative(targetDir, appRootSourceFile.getFilePath());
+  const appRootFile = project.createSourceFile(
+    '__generated__/router/app_root.ts',
+    '',
+    {overwrite: true},
+  );
+
+  const moduleSpecifier = appRootFile.getRelativePathAsModuleSpecifierTo(
+    appRootSourceFile.getFilePath(),
+  );
+
+  appRootFile.addStatements(`/*
+ * This file was generated by \`pastoria\`.
+ * Do not modify this file directly.
+ */
+
+export {${appRootSymbol.getName()} as App} from '${moduleSpecifier}';
+`);
+
+  await appRootFile.save();
+
+  console.log(
+    'Created app root for',
+    pc.green(appRootSymbol.getName()),
+    'exported from',
+    pc.yellow(filePath),
+  );
+}
+
+async function generateGraphqlContext(
+  project: Project,
+  metadata: PastoriaMetadata,
+) {
+  const targetDir = process.cwd();
+  const gqlContext: ExportedSymbol | null = metadata.gqlContext;
+  const contextFile = project.createSourceFile(
+    '__generated__/router/context.ts',
+    '',
+    {overwrite: true},
+  );
 
   if (gqlContext != null) {
     const contextSourceFile: SourceFile = gqlContext.sourceFile;
@@ -351,95 +615,53 @@ export class Context extends PastoriaRootContext {}
   }
 
   await contextFile.save();
+}
 
-  const resourceConf = routerFiles.jsResource
-    .getVariableDeclarationOrThrow('RESOURCE_CONF')
-    .getInitializerIfKindOrThrow(SyntaxKind.AsExpression)
-    .getExpressionIfKindOrThrow(SyntaxKind.ObjectLiteralExpression);
-
-  resourceConf.getPropertyOrThrow('noop').remove();
-  for (const {resourceName, sourceFile, symbol} of routerNodes.resources) {
-    const filePath = path.relative(process.cwd(), sourceFile.getFilePath());
-    const moduleSpecifier =
-      routerFiles.jsResource.getRelativePathAsModuleSpecifierTo(
-        sourceFile.getFilePath(),
-      );
+async function generateServerHandler(
+  project: Project,
+  metadata: PastoriaMetadata,
+) {
+  if (metadata.serverHandlers.size === 0) {
+    await project
+      .getSourceFile('__generated__/router/server_handler.ts')
+      ?.deleteImmediately();
 
-    resourceConf.addPropertyAssignment({
-      name: `"${resourceName}"`,
-      initializer: (writer) => {
-        writer.block(() => {
-          writer
-            .writeLine(`src: "${filePath}",`)
-            .writeLine(
-              `loader: () => import("${moduleSpecifier}").then(m => m.${symbol.getName()})`,
-            );
-        });
-      },
-    });
-
-    console.log(
-      'Created resource',
-      pc.cyan(resourceName),
-      'for',
-      pc.green(symbol.getName()),
-      'exported from',
-      pc.yellow(filePath),
-    );
+    return;
   }
 
-  const routerConf = routerFiles.router
-    .getVariableDeclarationOrThrow('ROUTER_CONF')
-    .getInitializerIfKindOrThrow(SyntaxKind.AsExpression)
-    .getExpressionIfKindOrThrow(SyntaxKind.ObjectLiteralExpression);
-
-  routerConf.getPropertyOrThrow('noop').remove();
+  const sourceText = `import express from 'express';
+export const router = express.Router();
+`;
 
-  let entryPointImportIndex = 0;
-  for (const {routeName, sourceFile, symbol, params} of routerNodes.routes) {
-    const importAlias = `e${entryPointImportIndex++}`;
+  const serverHandlerTemplate = project.createSourceFile(
+    '__generated__/router/server_handler.ts',
+    sourceText,
+    {overwrite: true},
+  );
+
+  let serverHandlerImportIndex = 0;
+  for (const [
+    routeName,
+    {symbol, sourceFile},
+  ] of metadata.serverHandlers.entries()) {
+    const importAlias = `e${serverHandlerImportIndex++}`;
     const filePath = path.relative(process.cwd(), sourceFile.getFilePath());
     const moduleSpecifier =
-      routerFiles.router.getRelativePathAsModuleSpecifierTo(
+      serverHandlerTemplate.getRelativePathAsModuleSpecifierTo(
         sourceFile.getFilePath(),
       );
 
-    routerFiles.router.addImportDeclaration({
+    serverHandlerTemplate.addImportDeclaration({
       moduleSpecifier,
-      namedImports: [
-        {
-          name: symbol.getName(),
-          alias: importAlias,
-        },
-      ],
+      namedImports: [{name: symbol.getName(), alias: importAlias}],
     });
 
-    routerConf.addPropertyAssignment({
-      name: `"${routeName}"`,
-      initializer: (writer) => {
-        writer
-          .write('{')
-          .indent(() => {
-            writer.writeLine(`entrypoint: ${importAlias},`);
-            if (params.size === 0) {
-              writer.writeLine(`schema: z.object({})`);
-            } else {
-              writer.writeLine(`schema: z.object({`);
-              for (const [paramName, paramType] of Array.from(params)) {
-                writer.writeLine(
-                  `  ${paramName}: ${zodSchemaOfType(tc, paramType)},`,
-                );
-              }
-
-              writer.writeLine('})');
-            }
-          })
-          .write('} as const');
-      },
-    });
+    serverHandlerTemplate.addStatements(
+      `router.use('${routeName}', ${importAlias})`,
+    );
 
     console.log(
-      'Created route',
+      'Created server handler',
       pc.cyan(routeName),
       'for',
       pc.green(symbol.getName()),
@@ -448,5 +670,23 @@ export class Context extends PastoriaRootContext {}
     );
   }
 
-  await Promise.all([routerFiles.jsResource.save(), routerFiles.router.save()]);
+  await serverHandlerTemplate.save();
+}
+
+export async function generatePastoriaArtifacts() {
+  const targetDir = process.cwd();
+  const project = new Project({
+    tsConfigFilePath: path.join(targetDir, 'tsconfig.json'),
+    manipulationSettings: {
+      indentationText: IndentationText.TwoSpaces,
+    },
+  });
+
+  const metadata = collectPastoriaMetadata(project);
+
+  await generateAppRoot(project, metadata);
+  await generateGraphqlContext(project, metadata);
+  await generateRouter(project, metadata);
+  await generateJsResource(project, metadata);
+  await generateServerHandler(project, metadata);
 }