@avijs/cli 0.1.2 → 0.2.1

package/src/generate.ts

@@ -1,8 +1,15 @@
-import { existsSync, readdirSync } from 'node:fs';
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { parseArgs } from 'node:util';
 import ts from 'typescript';
+import {
+  SYNTAX,
+  VALIDATORS,
+  detectValidator,
+  type SchemaSyntax,
+  type Validator,
+} from './validators.js';
 
 type Kind = 'module' | 'controller' | 'service' | 'resource';
 type Layout = 'modular' | 'minimal';
@@ -23,7 +30,8 @@ export const GENERATE_USAGE = `  avi generate <module|controller|service|resourc
       Create a module, controller or service and register it. Short: avi g co admin/posts.
       Modular projects get src/modules/<path>/<name>.<kind>.ts, registered in the nearest
       module; minimal projects get src/routes/<path>.ts or src/services/<path>.ts, registered
-      in src/app.ts. A resource (avi g res posts) creates all of them with CRUD routes.`;
+      in src/app.ts. A resource (avi g res posts) creates all of them with CRUD routes, validated
+      with the project's valibot or zod (--validator valibot|zod|none to choose).`;
 
 interface Names {
   /** kebab-case file name, e.g. `user-profile`. */
@@ -79,6 +87,7 @@ export async function generate(args: readonly string[]): Promise<number> {
     options: {
       root: { type: 'string', default: '.' },
       'dry-run': { type: 'boolean', default: false },
+      validator: { type: 'string' },
     },
   });
   const [kindArg, target] = positionals;
@@ -110,12 +119,20 @@ export async function generate(args: readonly string[]): Promise<number> {
     return 1;
   }
 
+  const validator = (values.validator ??
+    detectValidator(readJson(path.join(root, 'package.json')))) as Validator;
+  if (!VALIDATORS.includes(validator)) {
+    console.error(`Unknown validator "${validator}". Use ${VALIDATORS.join(', ')}.`);
+    return 2;
+  }
+  const syntax = validator === 'none' ? undefined : SYNTAX[validator];
+
   const names = toNames(segments.at(-1) as string);
   const dirs = segments.slice(0, -1);
   const plan = new Plan();
   try {
-    if (layout === 'modular') await modular(plan, src, kind, dirs, names);
-    else await minimal(plan, src, kind, dirs, names);
+    if (layout === 'modular') await modular(plan, src, kind, dirs, names, syntax);
+    else await minimal(plan, src, kind, dirs, names, syntax);
   } catch (error) {
     if (!(error instanceof GenerateError)) throw error;
     console.error(error.message);
@@ -131,14 +148,29 @@ async function modular(
   kind: Kind,
   dirs: readonly string[],
   names: Names,
+  syntax: SchemaSyntax | undefined,
 ): Promise<void> {
   const folder = path.join(src, 'modules', ...dirs, names.file);
 
   if (kind === 'resource') {
     const module = path.join(folder, `${names.file}.module.ts`);
     plan.create(module, resourceModule(names));
-    plan.create(path.join(folder, `${names.file}.service.ts`), crudService(names, true));
-    plan.create(path.join(folder, `${names.file}.controller.ts`), crudController(names));
+    if (syntax) {
+      const schemas = `./${names.file}.schemas.js`;
+      plan.create(path.join(folder, `${names.file}.schemas.ts`), resourceSchemas(names, syntax));
+      plan.create(
+        path.join(folder, `${names.file}.service.ts`),
+        typedService(names, true, schemas),
+      );
+      plan.create(
+        path.join(folder, `${names.file}.controller.ts`),
+        typedController(names, schemas),
+      );
+    } else {
+      plan.create(path.join(folder, `${names.file}.service.ts`), crudService(names, true));
+      plan.create(path.join(folder, `${names.file}.controller.ts`), crudController(names));
+      plan.notes.push(UNVALIDATED);
+    }
     const parent = nearestModule(plan, src, path.dirname(folder));
     await register(plan, parent, 'imports', `${names.pascal}Module`, module);
     return;
@@ -219,6 +251,7 @@ async function minimal(
   kind: Kind,
   dirs: readonly string[],
   names: Names,
+  syntax: SchemaSyntax | undefined,
 ): Promise<void> {
   if (kind === 'module') {
     throw new GenerateError(
@@ -231,8 +264,19 @@ async function minimal(
 
   if (kind === 'resource') {
     const routes = path.join(src, 'routes', ...dirs, `${names.file}.ts`);
-    plan.create(service, crudService(names, false));
-    plan.create(routes, crudRoutes(names, importPath(routes, service)));
+    if (syntax) {
+      const schemas = path.join(src, 'schemas', ...dirs, `${names.file}.ts`);
+      plan.create(schemas, resourceSchemas(names, syntax));
+      plan.create(service, typedService(names, false, importPath(service, schemas)));
+      plan.create(
+        routes,
+        typedRoutes(names, importPath(routes, service), importPath(routes, schemas)),
+      );
+    } else {
+      plan.create(service, crudService(names, false));
+      plan.create(routes, crudRoutes(names, importPath(routes, service)));
+      plan.notes.push(UNVALIDATED);
+    }
     await register(plan, app, 'providers', serviceClass, service);
     await register(plan, app, 'controllers', `${names.camel}Routes`, routes);
     return;
@@ -569,3 +613,177 @@ export const ${field}Routes = defineController({
 });
 `;
 }
+
+function readJson(file: string): unknown {
+  try {
+    return JSON.parse(readFileSync(file, 'utf8')) as unknown;
+  } catch {
+    return undefined;
+  }
+}
+
+const UNVALIDATED =
+  'NOTE   No validation library in package.json: request bodies are stored as sent. Install valibot\n       or zod and generate with --validator to get schemas that reject unknown fields.';
+
+/** Names of a resource's schemas: `posts` → `PostId`, `CreatePost`, `UpdatePost`. */
+function schemaNames(names: Names) {
+  const item = singular(names.pascal);
+  return { item, id: `${item}Id`, create: `Create${item}`, update: `Update${item}` };
+}
+
+function resourceSchemas(names: Names, syntax: SchemaSyntax): string {
+  const { id, create, update } = schemaNames(names);
+  return `${syntax.import}
+
+export const ${id} = ${syntax.id};
+
+// Add your fields here. Fields not listed are dropped from request bodies.
+export const ${create} = ${syntax.object([['title', syntax.text(200, 'title is required')]])};
+export type ${create} = ${syntax.infer(create)};
+
+export const ${update} = ${syntax.partialNonEmpty(create)};
+export type ${update} = ${syntax.infer(update)};
+`;
+}
+
+function typedService(names: Names, decorated: boolean, schemas: string): string {
+  const { item, create, update } = schemaNames(names);
+  const imports = decorated ? 'HttpError, Injectable' : 'HttpError';
+  return `import { ${imports} } from '@avijs/core';
+import type { ${create}, ${update} } from '${schemas}';
+
+export type ${item} = { id: number } & ${create};
+
+/** Keeps ${names.file} in memory. Swap the Map for your database; the routes stay the same. */
+${decorated ? '@Injectable()\n' : ''}export class ${names.pascal}Service {
+  readonly #items = new Map<number, ${item}>();
+  #nextId = 1;
+
+  findAll(): ${item}[] {
+    return [...this.#items.values()];
+  }
+
+  findOne(id: number): ${item} {
+    const item = this.#items.get(id);
+    if (!item) throw new HttpError(404, \`${item} \${String(id)} not found\`);
+    return item;
+  }
+
+  create(data: ${create}): ${item} {
+    const item = { ...data, id: this.#nextId++ };
+    this.#items.set(item.id, item);
+    return item;
+  }
+
+  update(id: number, data: ${update}): ${item} {
+    const item = { ...this.findOne(id), ...data, id };
+    this.#items.set(id, item);
+    return item;
+  }
+
+  remove(id: number): void {
+    this.findOne(id);
+    this.#items.delete(id);
+  }
+}
+`;
+}
+
+function typedController(names: Names, schemas: string): string {
+  const { id, create, update } = schemaNames(names);
+  const service = `${names.pascal}Service`;
+  const field = names.camel;
+  return `import {
+  Controller,
+  Delete,
+  Get,
+  Patch,
+  Post,
+  reply,
+  type RouteContext,
+  type RouteSchema,
+} from '@avijs/core';
+import { ${create}, ${id}, ${update} } from '${schemas}';
+import { ${service} } from './${names.file}.service.js';
+
+const byId = { params: ${id} } satisfies RouteSchema;
+const create = { body: ${create} } satisfies RouteSchema;
+const update = { params: ${id}, body: ${update} } satisfies RouteSchema;
+
+@Controller('/${names.file}')
+export class ${names.pascal}Controller {
+  static inject = [${service}] as const;
+
+  constructor(private readonly ${field}: ${service}) {}
+
+  @Get()
+  findAll() {
+    return this.${field}.findAll();
+  }
+
+  @Get('/:id', { schema: byId })
+  findOne(ctx: RouteContext<typeof byId>) {
+    return this.${field}.findOne(ctx.input.params.id);
+  }
+
+  @Post('/', { schema: create })
+  create(ctx: RouteContext<typeof create>) {
+    return reply(this.${field}.create(ctx.input.body), { status: 201 });
+  }
+
+  @Patch('/:id', { schema: update })
+  update(ctx: RouteContext<typeof update>) {
+    return this.${field}.update(ctx.input.params.id, ctx.input.body);
+  }
+
+  @Delete('/:id', { schema: byId })
+  remove(ctx: RouteContext<typeof byId>) {
+    this.${field}.remove(ctx.input.params.id);
+  }
+}
+`;
+}
+
+function typedRoutes(names: Names, serviceImport: string, schemas: string): string {
+  const { id, create, update } = schemaNames(names);
+  const service = `${names.pascal}Service`;
+  const field = names.camel;
+  return `import { defineController, reply, route } from '@avijs/core';
+import { ${create}, ${id}, ${update} } from '${schemas}';
+import { ${service} } from '${serviceImport}';
+
+export const ${field}Routes = defineController({
+  prefix: '/${names.file}',
+  inject: [${service}],
+  routes: (${field}) => [
+    route({ method: 'GET', path: '/', handler: () => ${field}.findAll() }),
+    route({
+      method: 'GET',
+      path: '/:id',
+      schema: { params: ${id} },
+      handler: (ctx) => ${field}.findOne(ctx.input.params.id),
+    }),
+    route({
+      method: 'POST',
+      path: '/',
+      schema: { body: ${create} },
+      handler: (ctx) => reply(${field}.create(ctx.input.body), { status: 201 }),
+    }),
+    route({
+      method: 'PATCH',
+      path: '/:id',
+      schema: { params: ${id}, body: ${update} },
+      handler: (ctx) => ${field}.update(ctx.input.params.id, ctx.input.body),
+    }),
+    route({
+      method: 'DELETE',
+      path: '/:id',
+      schema: { params: ${id} },
+      handler: (ctx) => {
+        ${field}.remove(ctx.input.params.id);
+      },
+    }),
+  ],
+});
+`;
+}

package/src/index.ts

@@ -1,3 +1,4 @@
 export { main } from './cli.js';
 export { templateFiles } from './templates.js';
 export type { TemplateName, TemplateOptions } from './templates.js';
+export type { Validator } from './validators.js';

package/src/templates.ts

@@ -1,3 +1,5 @@
+import { SYNTAX, VALIDATOR_VERSIONS, type SchemaSyntax, type Validator } from './validators.js';
+
 export type TemplateName = 'modular' | 'minimal';
 
 export interface TemplateOptions {
@@ -11,22 +13,29 @@ export interface TemplateOptions {
    * each other resolve locally too.
    */
   localPackages?: Readonly<Record<string, string>>;
+  /** How the users routes validate input. Default: `valibot`. */
+  validator?: Validator;
 }
 
 /** Every file of a new project, keyed by its path relative to the project folder. */
 export function templateFiles(options: TemplateOptions): Record<string, string> {
-  return {
-    ...shared(options),
-    ...(options.template === 'modular' ? modular() : minimal()),
-  };
+  const validator = options.validator ?? 'valibot';
+  const syntax = validator === 'none' ? undefined : SYNTAX[validator];
+  const files = options.template === 'modular' ? modular() : minimal();
+  if (syntax) {
+    Object.assign(
+      files,
+      options.template === 'modular' ? modularSchemas(syntax) : minimalSchemas(syntax),
+    );
+    if (options.template === 'modular') delete files['src/modules/users/dto/create-user.dto.ts'];
+  }
+  return { ...shared(options, validator), ...files };
 }
 
-function shared({
-  name,
-  template,
-  aviVersion,
-  localPackages,
-}: TemplateOptions): Record<string, string> {
+function shared(
+  { name, template, aviVersion, localPackages }: TemplateOptions,
+  validator: Validator,
+): Record<string, string> {
   const spec = (pkg: string) => localPackages?.[pkg] ?? aviVersion;
   const pkg = {
     name,
@@ -40,7 +49,10 @@ function shared({
       check: 'avi check',
       test: 'tsc && node --test "dist/**/*.test.js"',
     },
-    dependencies: { '@avijs/core': spec('@avijs/core') },
+    dependencies: {
+      '@avijs/core': spec('@avijs/core'),
+      ...(validator === 'none' ? {} : { [validator]: VALIDATOR_VERSIONS[validator] }),
+    },
     devDependencies: {
       '@avijs/cli': spec('@avijs/cli'),
       '@avijs/testing': spec('@avijs/testing'),
@@ -68,7 +80,7 @@ function shared({
   return {
     'package.json': `${JSON.stringify(pkg, null, 2)}\n`,
     'tsconfig.json': `${JSON.stringify(tsconfig, null, 2)}\n`,
-    '.gitignore': 'node_modules/\ndist/\n',
+    '.gitignore': 'node_modules/\ndist/\n.env\n',
     'README.md': `# ${name}
 
 An [Avi.js](https://github.com/chrischase011/avi-js) API (${template} template).
@@ -85,7 +97,10 @@ Then open http://localhost:3000/health and http://localhost:3000/users.
   };
 }
 
-const MAIN_LISTEN = `const { port } = await app.listen(Number(process.env['PORT'] ?? 3000));
+const MAIN_LISTEN = listenOn("Number(process.env['PORT'] ?? 3000)");
+
+function listenOn(port: string): string {
+  return `const { port } = await app.listen(${port});
 console.log(\`Listening on http://localhost:\${String(port)}\`);
 
 const shutdown = () => {
@@ -94,6 +109,19 @@ const shutdown = () => {
 process.once('SIGINT', shutdown);
 process.once('SIGTERM', shutdown);
 `;
+}
+
+/** `src/config.ts`: environment variables checked at startup. */
+function configFile(syntax: SchemaSyntax): string {
+  return `import { defineConfig } from '@avijs/core';
+${syntax.import}
+
+// Environment variables, checked when the app starts. A .env file is read too, if present.
+const env = ${syntax.object([['PORT', syntax.port]])};
+
+export const Config = defineConfig(env, { envFile: '.env' });
+`;
+}
 
 function modular(): Record<string, string> {
   return {
@@ -331,3 +359,233 @@ test('answers 404 for an unknown user', async () => {
 `,
   };
 }
+
+const REJECTS_NAMELESS = `test('rejects a user without a name', async () => {
+  const res = await client.post('/users', {});
+  assert.equal(res.status, 400);
+  const body = res.body as { details: { issues: { in: string; path: string[] }[] } };
+  assert.deepEqual(
+    body.details.issues.map((issue) => \`\${issue.in}.\${issue.path.join('.')}\`),
+    ['body.name'],
+  );
+});
+`;
+
+/** The users feature with route schemas instead of a handwritten parser. */
+function modularSchemas(syntax: SchemaSyntax): Record<string, string> {
+  return {
+    'src/config.ts': configFile(syntax),
+    'src/main.ts': `import { AviFactory } from '@avijs/core';
+import { AppModule } from './app.module.js';
+import { Config } from './config.js';
+
+const app = await AviFactory.create(AppModule);
+${listenOn('app.get(Config).PORT')}`,
+    'src/app.module.ts': `import { Module } from '@avijs/core';
+import { HealthController } from './common/health.controller.js';
+import { Config } from './config.js';
+import { UsersModule } from './modules/users/users.module.js';
+
+@Module({ imports: [Config.module, UsersModule], controllers: [HealthController] })
+export class AppModule {}
+`,
+    'src/modules/users/dto/user.dto.ts': `${syntax.import}
+
+export const UserId = ${syntax.id};
+
+export const CreateUserDto = ${syntax.object([['name', syntax.text(100, 'name is required')]])};
+export type CreateUserDto = ${syntax.infer('CreateUserDto')};
+
+// Responses are checked against these and lose any field not listed, so internals cannot leak.
+export const User = ${syntax.object([
+      ['id', syntax.number],
+      ['name', syntax.string],
+    ])};
+export type User = ${syntax.infer('User')};
+
+export const UserList = ${syntax.array('User')};
+`,
+    'src/modules/users/users.service.ts': `import { Injectable } from '@avijs/core';
+import type { CreateUserDto, User } from './dto/user.dto.js';
+
+@Injectable()
+export class UsersService {
+  readonly #users: User[] = [{ id: 1, name: 'Ada' }];
+
+  findAll(): User[] {
+    return this.#users;
+  }
+
+  findOne(id: number): User | undefined {
+    return this.#users.find((user) => user.id === id);
+  }
+
+  create(dto: CreateUserDto): User {
+    const user = { id: this.#users.length + 1, name: dto.name };
+    this.#users.push(user);
+    return user;
+  }
+}
+`,
+    'src/modules/users/users.controller.ts': `import {
+  Controller,
+  Get,
+  HttpError,
+  Post,
+  reply,
+  type RouteContext,
+  type RouteSchema,
+} from '@avijs/core';
+import { CreateUserDto, User, UserId, UserList } from './dto/user.dto.js';
+import { UsersService } from './users.service.js';
+
+const findOne = { params: UserId, response: User } satisfies RouteSchema;
+const create = { body: CreateUserDto, response: User } satisfies RouteSchema;
+
+@Controller('/users')
+export class UsersController {
+  static inject = [UsersService] as const;
+
+  constructor(private readonly users: UsersService) {}
+
+  @Get('/', { schema: { response: UserList } })
+  findAll() {
+    return this.users.findAll();
+  }
+
+  @Get('/:id', { schema: findOne })
+  findOne(ctx: RouteContext<typeof findOne>) {
+    const user = this.users.findOne(ctx.input.params.id);
+    if (!user) throw new HttpError(404, 'User not found');
+    return user;
+  }
+
+  @Post('/', { schema: create })
+  create(ctx: RouteContext<typeof create>) {
+    return reply(this.users.create(ctx.input.body), { status: 201 });
+  }
+}
+`,
+    'src/modules/users/users.test.ts': `import assert from 'node:assert/strict';
+import { after, before, test } from 'node:test';
+import { createTestClient, type TestClient } from '@avijs/testing';
+import { AppModule } from '../../app.module.js';
+
+let client: TestClient;
+before(async () => {
+  client = await createTestClient(AppModule);
+});
+after(() => client.close());
+
+test('lists users', async () => {
+  const res = await client.get('/users');
+  assert.equal(res.status, 200);
+  assert.deepEqual(res.body, [{ id: 1, name: 'Ada' }]);
+});
+
+test('creates a user', async () => {
+  const res = await client.post('/users', { name: '  Grace  ', role: 'admin' });
+  assert.equal(res.status, 201);
+  assert.deepEqual(res.body, { id: 2, name: 'Grace' });
+});
+
+${REJECTS_NAMELESS}`,
+  };
+}
+
+function minimalSchemas(syntax: SchemaSyntax): Record<string, string> {
+  return {
+    'src/config.ts': configFile(syntax),
+    'src/main.ts': `import { createApp } from './app.js';
+import { Config } from './config.js';
+
+const app = createApp();
+await app.init();
+${listenOn('app.get(Config).PORT')}`,
+    'src/app.ts': `import { createAvi } from '@avijs/core';
+import { Config } from './config.js';
+import { healthRoutes } from './routes/health.js';
+import { usersRoutes } from './routes/users.js';
+import { UsersService } from './services/users.js';
+
+export function createApp() {
+  return createAvi().register({
+    imports: [Config.module],
+    providers: [UsersService],
+    controllers: [healthRoutes, usersRoutes],
+  });
+}
+`,
+    'src/routes/users.ts': `import { HttpError, defineController, reply, route } from '@avijs/core';
+${syntax.import}
+import { UsersService } from '../services/users.js';
+
+const UserId = ${syntax.id};
+
+const CreateUser = ${syntax.object([['name', syntax.text(100, 'name is required')]])};
+
+// Responses are checked against this and lose any field not listed, so internals cannot leak.
+const User = ${syntax.object([
+      ['id', syntax.number],
+      ['name', syntax.string],
+    ])};
+
+export const usersRoutes = defineController({
+  prefix: '/users',
+  inject: [UsersService],
+  routes: (users) => [
+    route({
+      method: 'GET',
+      path: '/',
+      schema: { response: ${syntax.array('User')} },
+      handler: () => users.findAll(),
+    }),
+    route({
+      method: 'GET',
+      path: '/:id',
+      schema: { params: UserId, response: User },
+      handler: (ctx) => {
+        const user = users.findOne(ctx.input.params.id);
+        if (!user) throw new HttpError(404, 'User not found');
+        return user;
+      },
+    }),
+    route({
+      method: 'POST',
+      path: '/',
+      schema: { body: CreateUser, response: User },
+      handler: (ctx) => reply(users.create(ctx.input.body.name), { status: 201 }),
+    }),
+  ],
+});
+`,
+    'src/app.test.ts': `import assert from 'node:assert/strict';
+import { after, before, test } from 'node:test';
+import { createTestClient, type TestClient } from '@avijs/testing';
+import { createApp } from './app.js';
+
+let client: TestClient;
+before(async () => {
+  client = await createTestClient(createApp());
+});
+after(() => client.close());
+
+test('lists users', async () => {
+  const res = await client.get('/users');
+  assert.equal(res.status, 200);
+  assert.deepEqual(res.body, [{ id: 1, name: 'Ada' }]);
+});
+
+test('creates a user', async () => {
+  const res = await client.post('/users', { name: '  Grace  ', role: 'admin' });
+  assert.equal(res.status, 201);
+  assert.deepEqual(res.body, { id: 2, name: 'Grace' });
+});
+
+test('answers 404 for an unknown user', async () => {
+  assert.equal((await client.get('/users/99')).status, 404);
+});
+
+${REJECTS_NAMELESS}`,
+  };
+}