@dunx/create-app 2.4.0 → 3.0.0

package/templates/features/jobs/jobs.controller.ts

@@ -17,8 +17,7 @@ const Enqueue = z
     width: z.coerce.number().int().min(1).max(1024).default(128),
     format: z.enum(EncodableFormat).default(EncodableFormat.WEBP),
   })
-  // `.strict()` **after** `.meta()` discards the metadata - `meta()` then returns
-  // null and the schema is inlined despite declaring an id. Order matters.
+  // `.strict()` after `.meta()` discards the metadata; put `.meta()` last.
   .strict()
   .meta({
     id: 'EnqueueRender',
@@ -28,11 +27,7 @@ const Enqueue = z
 const enqueue = { body: Enqueue } as const;
 const oneJob = { params: z.object({ id: z.string().min(1) }) } as const;
 
-/**
- * The publish side. Nothing here consumes: `QueueModule.forRoot` binds
- * `JobPublisher` and no worker, so this process enqueues and returns immediately.
- * Consumed by this same process - see `JobsModule`'s `consume: true`.
- */
+/** The publish side: `QueueModule.forRoot` binds `JobPublisher` and no worker. */
 @Controller('jobs')
 export class JobsController {
   constructor(private readonly publisher: JobPublisher) {}
@@ -48,16 +43,12 @@ export class JobsController {
     return {
       id: job.id ?? '(unassigned)',
       queue: THUMBNAIL_QUEUE,
-      // `waiting` until a worker takes it - which is the observable point of a
-      // queue, so it is in the response rather than hidden.
       state: await job.getState(),
     };
   }
 
-  /**
-   * Poll a job. `returnvalue` is whatever the handler returned, so this is how the
-   * web process reads a result computed in another process.
-   */
+  /** `returnvalue` is whatever the handler returned, so this is how the web
+   * process reads a result computed elsewhere. */
   @Get('/thumbnails/:id', oneJob)
   async status(input: Input<typeof oneJob>): Promise<{
     id: string;
@@ -84,11 +75,9 @@ export class JobsController {
   }
 
   /**
-   * No Redis is a degraded queue, not a broken app - the same contract the cache
-   * routes keep. bullmq surfaces the failure through ioredis rather than Bun's
-   * client, so the connection-error shape is not guaranteed to match; anything
-   * unrecognised still becomes a 503 rather than a 500, because "the queue is not
-   * reachable" is the only thing it can mean here.
+   * No Redis is a degraded queue, not a broken app. bullmq surfaces the failure
+   * through ioredis, so the error shape is not guaranteed; anything unrecognised
+   * still becomes a 503.
    */
   private async degrades<T>(run: () => Promise<T>): Promise<T> {
     try {

package/templates/features/jobs/jobs.module.ts

@@ -6,17 +6,9 @@ import { JobsController } from './jobs.controller.js';
 import { ThumbnailJobs } from './thumbnail.jobs.js';
 
 /**
- * Imported by **both** containers, which is the whole shape of a queue: the web
- * process publishes, a separate worker process consumes, and they agree only on
- * this module.
- *
- * `consume: true` is what makes this process work them as well as publish, and it
- * is the only line about it anywhere - the container owns starting and stopping the
- * workers, so no entrypoint has to. Leave it out and the module binds the publish
- * side alone, which is what a web tier with a separate worker fleet wants.
- *
- * `PicturesModule` is here because the handler injects `Thumbnails`, and the
- * container that runs it has to be able to build it.
+ * Imported by both containers: the web process publishes, a worker process
+ * consumes, and they agree only on this module. `consume: true` makes this
+ * process work them too; leave it out and it binds the publish side alone.
  */
 @Module({
   imports: [
@@ -26,12 +18,11 @@ import { ThumbnailJobs } from './thumbnail.jobs.js';
         return {
           ...(url === undefined ? {} : { url }),
           prefix: 'dunx-full',
-          // This process works its own queues. The container starts the workers at
-          // onInit and stops them at onShutdown - before the database they use -
-          // so `main.ts` says nothing about queues and there is no second command.
+          // The container starts the workers at onInit and stops them before
+          // the database they use, so `main.ts` says nothing about queues.
           consume: true,
-          // The file bullmq forks into for a queue whose handler is marked
-          // `background`. Absolute, because the child resolves it, not this module.
+          // Where bullmq forks for a `background` handler. Absolute: the child
+          // resolves it, not this module.
           processor: new URL('./jobs.processor.ts', import.meta.url).pathname,
         };
       },
@@ -41,8 +32,7 @@ import { ThumbnailJobs } from './thumbnail.jobs.js';
   ],
   controllers: [JobsController],
   providers: [ThumbnailJobs],
-  // The publisher, re-exported so a feature that enqueues does not import
-  // @dunx/infra/queue itself.
+  // Re-exported so a feature that enqueues does not import @dunx/infra/queue.
   exports: [JobPublisher, ThumbnailJobs],
 })
 export class JobsModule {}

package/templates/features/jobs/jobs.processor.ts

@@ -5,25 +5,17 @@ import { AppConfigService, validate } from '../config.js';
 import { JobsModule } from './jobs.module.js';
 
 /**
- * **The file bullmq forks into.** Its default export is the processor, and nothing
- * else here runs in the parent.
- *
- * The child builds its own container, which is the whole point: a handler gets the
- * database, the image pipeline and the logger it declares, without sharing an event
- * loop with the process serving HTTP. `JobProcessor` builds it once per child and
- * reuses it for every job on that child.
- *
- * Its own module rather than reusing `WorkerModule` from `worker.ts`: that file is
- * an entrypoint with a `run()` at the bottom, and importing it here would boot a
- * second worker inside every child.
+ * The file bullmq forks into; its default export is the processor. The child
+ * builds its own container, so a handler gets what it declares without sharing
+ * an event loop with the HTTP process. Its own module rather than `worker.ts`,
+ * which has a `run()` that would boot a second worker inside every child.
  */
 @Module({
   imports: [
     ConfigModule.forRoot({ validate, as: AppConfigService }),
     LoggerModule.forRootAsync({
       useFactory: (config: AppConfigService) => ({
-        // Named so a line from a child is attributable to one on sight - which is
-        // the traceability a sandbox is for.
+        // Named, so a line from a child is attributable on sight.
         name: `${config.get('appName')}-job`,
         level: config.get('log').level,
       }),

package/templates/features/schedule/maintenance.service.ts

@@ -2,21 +2,13 @@ import { Logger } from '@dunx/core';
 import { Cron, Interval, OnceOnBoot } from '@dunx/infra/schedule';
 
 /**
- * The three decorators, on one class.
+ * The three schedule decorators on one class, discovered off the prototype chain
+ * with no second registration. Nothing here coordinates across replicas: work
+ * that must happen once per fleet is a `@JobHandler`.
  *
- * The runner finds them by walking the prototype chains of the classes the modules
- * already declare, so none of these needs a second registration - the same
- * discovery routes, gateways and `@JobHandler` use.
- *
- * Nothing here is single-node-unsafe on purpose: two replicas would both run every
- * one of these, because nothing in `@dunx/infra/schedule` coordinates. Work that
- * must happen once across a fleet is a job, which is `@JobHandler` and bullmq.
- */
-/**
- * Counters are written as `x = x + 1` rather than `x += 1`, and that is not style.
- * Bun 1.4.0 refuses to parse a class that has both a decorated member and a
- * read-modify-write on a private field - `+=`, `++` and `??=` alike - with a
- * `SyntaxError` naming neither. See docs/bun-apis.md.
+ * Counters are `x = x + 1` rather than `x += 1` because Bun 1.4.0 fails to parse
+ * a class with both a decorated member and a read-modify-write on a private
+ * field. See docs/bun-apis.md.
  */
 export class Maintenance {
   #sweeps = 0;
@@ -25,22 +17,15 @@ export class Maintenance {
 
   constructor(private readonly logger: Logger) {}
 
-  /**
-   * `0`, so it fires on the next macrotask after the container is ready - and
-   * "ready" is `onInit`, which is the latest hook there is and runs **before**
-   * `Bun.serve` binds. Measured: this has already run by the time `listen()`
-   * resolves, so the first request never sees a cold cache.
-   */
+  /** `0` fires on the next macrotask after `onInit`, which is before
+   * `Bun.serve` binds - so the first request never sees a cold cache. */
   @OnceOnBoot(0, { name: 'maintenance.warm' })
   warmCaches(): void {
     this.#warmed = true;
     this.logger.info('@OnceOnBoot(0): caches warmed, before listen() resolved');
   }
 
-  /**
-   * Every ten minutes, so it does not fire during a tour or a suite. `trigger`
-   * runs it now, which is what makes a schedule testable without waiting.
-   */
+  /** Ten minutes, so it never fires during a tour. `trigger` runs it now. */
   @Interval(600_000, { name: 'maintenance.sweep' })
   sweepSessions(): number {
     this.#sweeps = this.#sweeps + 1;
@@ -48,11 +33,8 @@ export class Maintenance {
   }
 
   /**
-   * Minute resolution: `Bun.cron` rejects a sixth field with "seconds are not
-   * supported", so anything sub-minute is `@Interval`.
-   *
-   * `overlap` is `skip` by default, which is what `Bun.cron` does for free - it
-   * computes the next fire only once the returned promise settles.
+   * Minute resolution: `Bun.cron` rejects a sixth field, so sub-minute work is
+   * `@Interval`. `overlap` defaults to `skip`, which `Bun.cron` gives for free.
    */
   @Cron('0 3 * * *', { name: 'maintenance.compact' })
   async compactLedger(): Promise<number> {

package/templates/features/schedule/schedule.module.ts

@@ -7,13 +7,9 @@ import { ScheduleDemo } from './schedule.demo.js';
 /**
  * `Bun.cron` behind `@Cron`, `@Interval` and `@OnceOnBoot`, armed at boot.
  *
- * `keepAlive: false`, unlike the default. `Bun.cron` holds the event loop open so a
- * process with an armed schedule and nothing else to do waits for the next fire;
- * this app has a server holding it open already, and `bun run tour` has to exit.
- *
- * `tz` comes from the config because that is the one thing a zero-argument
- * `forRoot` cannot reach. A named zone is refused at boot on a Bun that ignores
- * `Bun.cron`'s `tz` option, rather than running at the UTC hour and saying nothing.
+ * `keepAlive: false`: `Bun.cron` would hold the event loop open, and this app has
+ * a server doing that already while `bun run tour` has to exit. `tz` comes from
+ * the config, and a named zone is refused at boot on a Bun that ignores it.
  */
 @Module({
   imports: [

package/templates/features/storage/files.controller.ts

@@ -11,10 +11,9 @@ import { LocalStorage, PathTraversalError, Storage } from '@dunx/infra/files';
 import { z } from 'zod';
 
 /**
- * The key is a query parameter rather than a path segment because keys contain
- * slashes - `reports/q1.csv` is one key, not two segments. Traversal is rejected
- * by `Storage` itself rather than by a pattern here, which is the behaviour worth
- * seeing: try `?key=../../etc/passwd`.
+ * The key is a query parameter because keys contain slashes: `reports/q1.csv` is
+ * one key, not two segments. `Storage` itself rejects traversal - try
+ * `?key=../../etc/passwd`.
  */
 const FileKey = z.object({ key: z.string().min(1).max(200) }).meta({
   id: 'FileKey',
@@ -34,15 +33,12 @@ const listFiles = {
 const objectKey = { query: FileKey } as const;
 const writeFile = { query: FileKey, body: WriteFile } as const;
 
-/**
- * Injects `Storage`, never `LocalStorage` - swapping a disk for a bucket is one
- * `forRoot` call in storage.module.ts and nothing here changes.
- */
+/** Injects `Storage`, never `LocalStorage`: swapping disk for bucket is one
+ * `forRoot` call and nothing here changes. */
 @Controller('files')
 export class FilesController {
   constructor(private readonly storage: Storage) {}
 
-  /** `list` is an AsyncIterable so a million objects page rather than accumulate. */
   @Get('/', listFiles)
   async list(
     input: Input<typeof listFiles>,
@@ -54,8 +50,7 @@ export class FilesController {
     })) {
       keys.push(entry.key);
     }
-    // The contract cannot promise a root - narrowing to the backend is how you
-    // reach anything backend-specific.
+    // The contract cannot promise a root, so narrowing reaches it.
     const root =
       this.storage instanceof LocalStorage ? this.storage.root : '(remote)';
     return { root, keys: keys.sort() };
@@ -97,10 +92,8 @@ export class FilesController {
     return { deleted: true };
   }
 
-  /**
-   * Nothing signs bytes on a local disk, so this refuses with the backend's own
-   * message instead of handing back a URL that cannot work.
-   */
+  /** Nothing signs bytes on a local disk, so this refuses rather than hand back
+   * a URL that cannot work. */
   @Get('/presign', objectKey)
   async presign(input: Input<typeof objectKey>): Promise<{ url: string }> {
     const { key } = input.query;
@@ -115,10 +108,8 @@ export class FilesController {
     }
   }
 
-  /**
-   * A traversal is a bad request, not a server fault - `Storage` rejects it
-   * before any syscall, and without this it would surface as a 500.
-   */
+  /** A traversal is a bad request: `Storage` rejects it before any syscall, and
+   * without this it would surface as a 500. */
   private async present(key: string): Promise<void> {
     try {
       if (await this.storage.exists(key)) return;

package/templates/features/throttle/limits.controller.ts

@@ -1,33 +1,26 @@
 import { Controller, Get, SkipThrottle, Throttle } from '@dunx/http';
 
 /**
- * What the limit looks like from the outside.
- *
- * The module's default is generous, so the interesting cases are the two
- * decorators: `@Throttle` replaces it for one handler, `@SkipThrottle` opts out.
- * A limit on the class would cover every handler here, and a handler's own would
- * still win - the same precedence `@Roles` has.
+ * `@Throttle` replaces the module default for one handler, `@SkipThrottle` opts
+ * out. A class-level limit covers every handler, and a handler's own still wins.
  */
 @Controller('limits')
 export class LimitsController {
-  /**
-   * Three per minute, per subject. The fourth is a 429 carrying `retry-after`,
-   * thrown rather than returned, so it comes out in the app's own error shape.
-   */
+  /** Three per minute per subject; the fourth is a thrown 429 with
+   * `retry-after`, so it takes the app's own error shape. */
   @Throttle({ limit: 3, windowSeconds: 60 })
   @Get('/burst')
   burst(): { allowed: true } {
     return { allowed: true };
   }
 
-  /** Exempt. A probe or an internal callback that must never be counted. */
+  /** Exempt: a probe or internal callback that must never be counted. */
   @SkipThrottle()
   @Get('/exempt')
   exempt(): { counted: false } {
     return { counted: false };
   }
 
-  /** The module default, which is what every other route in this app gets. */
   @Get('/default')
   standard(): { ok: true } {
     return { ok: true };

package/templates/features/throttle/throttle.module.ts

@@ -13,28 +13,12 @@ import { LimitsController } from './limits.controller.js';
 import { ThrottleDemo } from './throttle.demo.js';
 
 /**
- * A fixed-window rate limit over the whole app.
+ * A fixed-window rate limit over the whole app, picking its counter at boot by
+ * asking whether the cache answers. A real deployment names one outright.
  *
- * **Which counter is decided at boot, by asking whether the cache answers.** A real
- * deployment names one outright: `RedisThrottleStore` for more than one replica,
- * because the in-process default lets each of them allow the full budget. This
- * example has to work with nothing installed, so it probes and says which it got.
- *
- * That probe is `Sessions.status()`, which `CacheModule` already exports rather than
- * a second ping written here.
- *
- * Falling back matters more than it looks. The guard fails **open**, so with
- * `RedisThrottleStore` and no Redis nothing is counted at all: no 429, no
- * `ratelimit-*` headers, every request through. That is the right call for a
- * production limiter, and it would make this example demonstrate nothing on a
- * machine without Redis.
- *
- * `RedisThrottleStore` takes its client structurally, so `RedisConnection` satisfies
- * it with no adapter.
- *
- * The prefix carries the pid, the same trick `Sessions` uses: two runs against one
- * Redis would otherwise spend each other's budget, and a leftover window would make
- * a suite fail on the previous run's counters.
+ * The probe matters because the guard fails open: with `RedisThrottleStore` and
+ * no Redis nothing is counted. The prefix carries the pid, so two runs against one
+ * Redis cannot spend each other's budget.
  */
 @Module({
   imports: [
@@ -62,11 +46,9 @@ import { ThrottleDemo } from './throttle.demo.js';
             ? new RedisThrottleStore(redis)
             : new MemoryThrottleStore(),
           /**
-           * Who is being counted. An API key when one is presented, else the
-           * address - which is the shape a real app wants, where an authenticated
-           * caller is limited by identity and an anonymous one by where it came
-           * from. Only a guard ahead of this one knows which, which is why this is
-           * an option rather than something the package reads for itself.
+           * Who is counted: an API key when presented, else the address. Only a
+           * guard ahead of this one knows, so it is an option rather than
+           * something the package reads for itself.
            */
           subject: (req: Bun.BunRequest) =>
             req.headers.get('x-api-key') ?? address.of(req),

package/templates/features/upstream/upstream.demo.ts

@@ -6,11 +6,9 @@ import {
 } from '@dunx/http/client';
 
 /**
- * Calling out, over `fetch` and therefore over no dependency at all.
- *
- * Three things a bare `fetch` does not do: retry a 503 with backoff, raise a
- * non-2xx as an error carrying the parsed body, and forward the inbound request id
- * so one trace covers both services.
+ * Calling out over `fetch`. Three things a bare `fetch` does not do: retry a 503
+ * with backoff, raise a non-2xx as an error carrying the parsed body, and forward
+ * the inbound request id.
  */
 export class UpstreamDemo {
   constructor(
@@ -24,7 +22,6 @@ export class UpstreamDemo {
     );
     this.logger.info(`GET api/notes -> ${JSON.stringify(notes)}`);
 
-    // The 503s are retried; the attempt callback is what makes that visible.
     const attempts: string[] = [];
     const recovered = await this.http.get<{ after: number }>(
       new URL('api/upstream/flaky', url),
@@ -42,12 +39,8 @@ export class UpstreamDemo {
         `recovered after ${recovered.after}`,
     );
 
-    /**
-     * A 404 is a `FetchError`, not an `HttpError`. That distinction is the whole
-     * reason the class exists: an upstream 401 arriving as an `HttpError(401)`
-     * would make *this* service answer 401, telling its own caller "you are
-     * unauthorized" when what failed was this service authenticating upstream.
-     */
+    /** A 404 is a `FetchError`, not an `HttpError`: an upstream 401 arriving as
+     * `HttpError(401)` would make this service answer 401 to its own caller. */
     try {
       await this.http.get(new URL('api/upstream/missing', url), {
         retry: { maxRetries: 0 },
@@ -61,9 +54,7 @@ export class UpstreamDemo {
       );
     }
 
-    // Not retried: the budget for the call is spent, and an abort means the
-    // caller's signal fired or the timeout did. `/slow` sleeps 300 ms, so this
-    // is a deadline rather than a race with the loopback.
+    // Not retried: an abort means the caller's signal or the timeout fired.
     try {
       await this.http.get(new URL('api/upstream/slow', url), {
         timeoutMs: 25,

package/templates/features/upstream/upstream.module.ts

@@ -5,15 +5,9 @@ import { FlakyController } from './flaky.controller.js';
 import { UpstreamDemo } from './upstream.demo.js';
 
 /**
- * The outbound half of `@dunx/http`, from the `./client` subpath.
- *
- * Imported as `HttpClientModule`, because this app already has an `HttpModule` of
- * its own and `@dunx/http` exports `HttpFactory` for the inbound direction. The
- * subpath is what keeps the two unambiguous at an import site; the alias is what
- * keeps them unambiguous here.
- *
- * No `baseUrl`: this app calls itself, and its own url is not known until
- * `listen()` has run. A real upstream sets one and every call names a path.
+ * The outbound half of `@dunx/http`, from the `./client` subpath, aliased because
+ * this app has an `HttpModule` of its own. No `baseUrl`: this app calls itself,
+ * and its url is not known until `listen()` has run.
  */
 @Module({
   imports: [
@@ -24,12 +18,9 @@ import { UpstreamDemo } from './upstream.demo.js';
         retry: {
           maxRetries: 3,
           retryDelayMs: 20,
-          // Jitter comes from `crypto.getRandomValues`, not `Math.random`.
           backoff: { jitterMs: 10, maxMs: 200 },
         },
-        // The inbound request id, forwarded to the upstream, so one trace spans
-        // both services. Read from `RequestContext`, so it only carries when there
-        // is a request in scope.
+        // The inbound request id, forwarded so one trace spans both services.
         propagateRequestId: true,
       }),
       inject: [AppConfigService] as const,

package/templates/features/users/users.controller.ts

@@ -17,11 +17,19 @@ export class UsersController {
   // `Input<typeof listUsers>` has to be written out - a standard method decorator
   // can check a parameter's type but cannot contextually type an unannotated one.
   // Every field type still comes from the schema, so nothing is declared twice.
+  //
+  // The return type is checked too, against `listUsers.response[200]`: a handler
+  // that answers with a shape the document does not describe is a TS1241 here
+  // rather than a surprise for whoever read the document. `readonly User[]` is
+  // accepted against a schema inferring `User[]` - mutability does not survive
+  // serialisation.
   @Get('/', listUsers)
   list(input: Input<typeof listUsers>): Promise<readonly User[]> {
     return this.users.findAll(input.query.limit, input.query.q);
   }
 
+  // Only the success status is checked - the 404 in `oneUser.response` leaves via
+  // a thrown HttpError, which no return type can describe.
   @Get('/:id', oneUser)
   async one(input: Input<typeof oneUser>): Promise<User> {
     // Already a number: the params schema coerced it before this ran.

package/templates/features/users/users.repository.ts

@@ -3,21 +3,13 @@ import { eq, like, sql } from 'drizzle-orm';
 import * as schema from '../database/schema.js';
 import { users, type User } from '../database/schema.js';
 
-// The row type comes from the table, so the controller and the service import one
-// definition rather than a hand-written copy of the columns.
 export type { User };
 
 export class UsersRepository {
   /**
-   * `SyncDatabase` because `DatabaseModule` configured synchronous mode; it is
-   * drizzle's `BunSQLiteDatabase` with a name the container can tell apart.
-   * `@dunx/transform` records the bare type name - a real runtime class, so a usable
-   * token - and ignores the type argument, so the schema types survive injection.
-   *
-   * Every method below is `async` although bun-sqlite executes synchronously: the
-   * HTTP layer awaits them, and moving this table to the pooled backend then costs
-   * no signature change. `Ledger.transferSync` is what refusing that trade looks
-   * like.
+   * Every method is `async` although bun-sqlite executes synchronously, so moving
+   * this table to the pooled backend costs no signature change.
+   * `Ledger.transferSync` is what refusing that trade looks like.
    */
   constructor(private readonly db: SyncDatabase<typeof schema>) {}
 
@@ -28,7 +20,7 @@ export class UsersRepository {
     )`);
   }
 
-  /** One statement for every name; `name` is UNIQUE, so a repeat boot is a no-op. */
+  /** `name` is UNIQUE, so a repeat boot is a no-op. */
   async seed(names: readonly string[]): Promise<void> {
     this.db
       .insert(users)
@@ -52,7 +44,6 @@ export class UsersRepository {
     return this.db.select().from(users).where(eq(users.id, id)).get() ?? null;
   }
 
-  /** `.returning()`, so the id is the one the database wrote. */
   async create(name: string): Promise<User> {
     return this.db.insert(users).values({ name }).returning().get();
   }

package/templates/features/users/users.schemas.ts

@@ -2,28 +2,13 @@ import type { RouteSchemas } from '@dunx/http';
 import { z } from 'zod';
 
 /**
- * Real zod, dropped straight into a route's options: `z.object()` already carries
- * `~standard` (vendor `zod`, version 1), which is the entire contract
- * `@dunx/http` validates against - so nothing adapts anything, and the framework
- * still depends on no validator.
+ * Plain zod in a route's options: `z.object()` already carries `~standard`, the
+ * whole contract `@dunx/http` validates against.
  *
- * `.meta({ id })` names the definition zod emits under `$defs`, which is the slot
- * OpenAPI calls `components/schemas`. Without an id the schema is inlined at every
- * use site instead of referenced once.
- *
- * **Prose goes in `description`, not `title`.** In JSON Schema `title` is a short
- * display name, and Swagger UI labels a schema by it. A sentence there makes the
- * whole Schemas list read as prose: `User` shows up as "A stored user" and is
- * impossible to find.
- *
- * Leaving `title` out is right, and not because it is unused: `@dunx/openapi` fills
- * it in with the component name when a schema is hoisted, which is what makes the
- * item of `array<User>` read as `User` rather than as `object`.
- *
- * One more ordering trap: `.strict()` **after** `.meta()` discards the metadata, so
- * the schema is inlined despite declaring an id. Put `.meta()` last.
- *
- * See `UsersDemo` for the generated document.
+ * Three traps. `.meta({ id })` names the `$defs` entry, and without it the schema
+ * is inlined at every use site. Prose goes in `description` - Swagger UI labels a
+ * schema by `title`, and `@dunx/openapi` fills that with the component name.
+ * `.strict()` after `.meta()` discards the metadata, so put `.meta()` last.
  */
 export const Tag = z
   .object({ label: z.string().min(1) })
@@ -49,15 +34,14 @@ export const ListUsers = z
   .meta({ id: 'ListUsers', description: 'Filter and page the user list' });
 
 /**
- * The response side. Same Standard Schema contract as a request, so it hoists into
- * `components/schemas` the same way - but it is **never validated**: it documents
- * what comes back, and the handler's return type is what checks it.
+ * The response side, never validated at runtime: the verb decorator holds the
+ * handler's return type to it at compile time instead. That check caught this
+ * schema advertising a `tags: string[]` the `users` table has no column for.
  */
 export const User = z
   .object({
     id: z.number().int(),
     name: z.string(),
-    tags: z.array(z.string()),
   })
   .meta({ id: 'User', description: 'A stored user' });
 
@@ -65,8 +49,8 @@ export const NotFound = z
   .object({ error: z.string(), status: z.literal(404) })
   .meta({ id: 'NotFound', description: 'Nothing at that id' });
 
-// Declaring a schema is what makes the matching `input` field exist, get parsed
-// and get validated. `satisfies` keeps the literal types `Input<>` reads.
+// A declared schema is what makes the matching `input` field exist and be
+// parsed. `satisfies` keeps the literal types `Input<>` reads.
 export const listUsers = {
   query: ListUsers,
   response: { 200: z.array(User) },
@@ -75,7 +59,6 @@ export const oneUser = {
   params: UserIndex,
   response: { 200: User, 404: NotFound },
 } as const satisfies RouteSchemas;
-// No status: POST defaults to 201, every other verb to 200.
 export const createUser = {
   body: CreateUser,
   response: { 201: User },

package/templates/minimal/src/app.module.ts

@@ -2,11 +2,6 @@ import { Module } from '@dunx/core';
 import { GreetingsController } from './greetings.controller.js';
 import { GreetingsService } from './greetings.service.js';
 
-/**
- * The root module. `controllers` are discovered for routes, `providers` are
- * everything else. Import order is construction order, and shutdown runs in
- * reverse - which matters once there is a database to close.
- */
 @Module({
   controllers: [GreetingsController],
   providers: [GreetingsService],

package/templates/minimal/src/app.test.ts

@@ -2,11 +2,6 @@ import { describe, expect, test } from 'bun:test';
 import { createTestServer } from '@dunx/testing';
 import { AppModule } from './app.module.js';
 
-/**
- * The whole app behind a real `Bun.serve` on port 0. This is also what CI runs to
- * prove the example still boots - see `examples/testing` for overrides and the
- * rest of `@dunx/testing`.
- */
 describe('minimal', () => {
   test('serves the greeting', async () => {
     const server = await createTestServer({ modules: [AppModule] });