@dunx/create-app 2.5.0 → 3.0.1

package/templates/features/database/ledger.service.ts

@@ -16,12 +16,9 @@ import { ledger, type Entry } from './schema.js';
 
 export class Ledger implements OnInit, OnShutdown {
   /**
-   * `SyncDatabase` is drizzle's `BunSQLiteDatabase` under a name that says the
-   * connection was opened in synchronous mode - which is what makes
-   * `transactionSync` below reachable. `@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. `DbConnection` is the lifecycle and the driver
-   * underneath; drizzle has neither.
+   * `SyncDatabase` is `BunSQLiteDatabase` under a name saying the connection was
+   * opened in synchronous mode, which is what reaches `transactionSync` below.
+   * `DbConnection` carries the lifecycle and the driver; drizzle has neither.
    */
   constructor(
     private readonly db: SyncDatabase<typeof schema>,
@@ -29,13 +26,7 @@ export class Ledger implements OnInit, OnShutdown {
     private readonly logger: Logger,
   ) {}
 
-  /**
-   * Standing in for a migration rather than replacing one: schema changes are
-   * `drizzle-kit generate` plus drizzle-orm/bun-sqlite/migrator, which own the
-   * SQL, the journal and the snapshot folder. A `:memory:` database has nowhere
-   * to keep any of that, so the table is created here - and at `onInit`, so the
-   * routes below have somewhere to write before the first request arrives.
-   */
+  /** Standing in for a migration, which a `:memory:` database cannot keep. */
   async onInit(): Promise<void> {
     this.db.run(sql`CREATE TABLE IF NOT EXISTS ledger (
       id INTEGER PRIMARY KEY AUTOINCREMENT,
@@ -55,17 +46,9 @@ export class Ledger implements OnInit, OnShutdown {
   }
 
   /**
-   * The same rows, paginated by cursor instead of by `limit`.
-   *
-   * Keyset rather than `OFFSET`, which is what makes it correct while rows are being
-   * written: a cursor names the last row seen, so an insert between two requests
-   * cannot shift a page and serve the same entry twice. This table has no timestamp,
-   * so `paginate` falls back to the primary key - `id` is unique on its own, so no
-   * tie-break column is needed.
-   *
-   * Synchronous, because `paginate`'s return type follows its `db`: a
-   * `drizzle-orm/bun-sqlite` handle answers `all()` rather than a promise, so this
-   * method needs no `async` and neither does its caller.
+   * Keyset rather than `OFFSET`: a cursor names the last row seen, so an insert
+   * between two requests cannot shift a page and serve an entry twice. No
+   * timestamp column here, so `paginate` falls back to the unique primary key.
    */
   page(options: PageOptions): Page<Entry> {
     return paginate<typeof ledger, Entry>({
@@ -107,11 +90,9 @@ export class Ledger implements OnInit, OnShutdown {
   }
 
   /**
-   * Both legs or neither. `transaction()` from `@dunx/infra/db`, not
-   * `db.transaction()`: drizzle's own on bun-sqlite delegates to `bun:sqlite`'s
-   * synchronous `transaction()`, which commits as soon as the callback returns its
-   * promise - so everything after the first `await` would run in autocommit. That
-   * is what makes the rollback below possible at all.
+   * `transaction()` from `@dunx/infra/db`, not `db.transaction()`: drizzle's own
+   * commits as soon as the callback returns its promise, so everything after the
+   * first `await` would run in autocommit.
    */
   transfer(
     from: string,
@@ -134,11 +115,8 @@ export class Ledger implements OnInit, OnShutdown {
   }
 
   /**
-   * The same two legs, with nothing to await. `transactionSync` is drizzle's own
-   * `db.transaction()` - correct here precisely because the callback cannot return
-   * a promise, which is the case its early commit breaks. The return type is
-   * `number`, not `Promise<number>`, so a controller calling this needs no `async`
-   * and the request never yields.
+   * The same two legs with nothing to await. `transactionSync` is drizzle's own
+   * `db.transaction()`, safe because the callback cannot return a promise.
    */
   transferSync(from: string, to: string, amount: number, fail = false): number {
     return transactionSync(this.db, (tx) => {
@@ -161,8 +139,7 @@ export class Ledger implements OnInit, OnShutdown {
         'table "ledger" created at onInit',
     );
 
-    // The escape hatch. `raw` is `unknown` on the base - the abstract class cannot
-    // promise either driver - and `instanceof` is what restores the concrete type.
+    // `raw` is `unknown` on the base, so `instanceof` restores the driver type.
     if (this.connection instanceof SqliteConnection) {
       logger.info(`raw driver -> bun:sqlite ${this.connection.raw.filename}`);
     }
@@ -195,10 +172,7 @@ export class Ledger implements OnInit, OnShutdown {
     await this.seeds();
   }
 
-  /**
-   * The same rollback with no promise anywhere - `transactionSync` throws where
-   * `transaction` rejects, so the recovery is `try`/`catch` rather than `.catch()`.
-   */
+  /** `transactionSync` throws where `transaction` rejects. */
   private rollsBackSynchronously(): void {
     const before = this.rows();
     try {
@@ -214,7 +188,6 @@ export class Ledger implements OnInit, OnShutdown {
     );
   }
 
-  /** The `await` inside is what proves the transaction is not autocommitting. */
   private async commits(): Promise<void> {
     const balance = await transaction(this.db, async (tx) => {
       tx.insert(ledger).values({ memo: 'refund', amount: 12 }).run();
@@ -246,9 +219,8 @@ export class Ledger implements OnInit, OnShutdown {
   }
 
   /**
-   * Seed *data*, which is the half `drizzle-kit` has no concept of. Numbered files
-   * in `seeds/`, each applied once and recorded in `dunx_seeds` - so this reports
-   * them journaled rather than applied, `onInit` having already run them.
+   * Seed data, the half `drizzle-kit` has no concept of. Numbered files in
+   * `seeds/`, applied once and recorded in `dunx_seeds`.
    */
   private async seeds(): Promise<void> {
     const dir = `${import.meta.dir}/seeds`;

package/templates/features/docs/docs.demo.ts

@@ -17,11 +17,8 @@ const documentAt = async (
 export class DocsDemo {
   constructor(private readonly logger: Logger) {}
 
-  /**
-   * The document is served by a controller in the same graph, so it goes through the
-   * same middleware and the same CORS as everything else - and describes the paths
-   * the app really mounted, `setGlobalPrefix('api')` included.
-   */
+  /** Served by a controller in the same graph, so it goes through the same
+   * middleware and describes the paths the app really mounted. */
   async demonstrate(app: HttpApp, url: string): Promise<void> {
     const { logger } = this;
     const [response, document] = await documentAt(url);
@@ -35,8 +32,6 @@ export class DocsDemo {
       `components/schemas: ${JSON.stringify(Object.keys(document.components.schemas))}`,
     );
 
-    // `.meta({ id: 'CreateUser' })` on the zod schema is what named this ref, and
-    // the $defs entry it referenced (`Tag`) came along with it.
     const create = document.paths['/api/users']?.post;
     logger.info(
       `POST /api/users requestBody -> ` +
@@ -48,9 +43,8 @@ export class DocsDemo {
       `POST /api/users 400 -> ` +
         JSON.stringify(create?.responses['400']?.content?.['application/json']),
     );
-    // `options.response` is the same contract as the request side, so a named
-    // response schema becomes a component and the operation $refs it. It is
-    // documentation only - nothing validates a response.
+    // A named response schema becomes a component the operation $refs. It is
+    // documentation only: nothing validates a response.
     const one = document.paths['/api/users/{id}']?.get;
     logger.info(
       `GET /api/users/{id} responses -> ` +
@@ -66,8 +60,7 @@ export class DocsDemo {
     const list = document.paths['/api/users']?.get;
     logger.info(`GET /api/users query -> ${JSON.stringify(list?.parameters)}`);
 
-    // The check that matters: a $ref that resolves to nothing renders as an empty
-    // box in every viewer and reports no error at all.
+    // A $ref resolving to nothing renders as an empty box and reports no error.
     logger.info(
       `unresolved $refs: ${danglingRefs(document).length}, warnings: ` +
         JSON.stringify(app.get(OpenApiExplorer).warnings),
@@ -81,14 +74,9 @@ export class DocsDemo {
     );
 
     /**
-     * **The page fetches, and this is the check that it only fetches from here.**
-     * The explorer used to be dunx's own bundle inlined into the page, so the
-     * assertion was that nothing was requested at all. It is now `swagger-ui-dist`,
-     * 3.7x the size gzipped, served as two assets - so the guarantee is narrower and
-     * has to be stated as what it is: same-origin only, no CDN.
-     *
-     * Script bodies are stripped first. Inside a `<script>` everything is text, so a
-     * `src=` in the boot script is not a resource.
+     * The page fetches two `swagger-ui-dist` assets, and the guarantee is that
+     * they are same-origin: no CDN. Script bodies are stripped first, since a
+     * `src=` inside a `<script>` is text rather than a resource.
      */
     const shell = html.replace(/(<script[^>]*>)[\s\S]*?(<\/script>)/g, '$1$2');
     const requested = [
@@ -102,9 +90,7 @@ export class DocsDemo {
         JSON.stringify(requested),
     );
 
-    // Every one of them has to actually answer, which is the half a unit test
-    // cannot show: these resolve out of the consumer's own swagger-ui-dist
-    // install, through this app's global prefix.
+    // Each has to answer, resolving out of the consumer's own install.
     for (const href of requested) {
       const asset = await fetch(new URL(href.replace(/^\//, ''), url));
       logger.info(
@@ -116,11 +102,8 @@ export class DocsDemo {
     }
   }
 
-  /**
-   * The guarded app, whose `AuthGuard` is global. Security in the document comes from
-   * the same `@Public()` and `@Roles()` metadata the guards read at runtime - there
-   * is no second annotation for the documentation to disagree with.
-   */
+  /** Security in the document comes from the same `@Public()` and `@Roles()`
+   * metadata the guards read at runtime. */
   async guarded(url: string): Promise<void> {
     const { logger } = this;
     const [, document] = await documentAt(url);
@@ -137,10 +120,8 @@ export class DocsDemo {
       `@Public() GET /api/reports/health -> security ${JSON.stringify(health?.security)}`,
     );
 
-    // The class-level @Roles('admin') is merged into every one of its routes, so it
-    // is documented on this one too - even though no RolesGuard reads it here. The
-    // document describes what the metadata declares; which guard enforces it is a
-    // separate decision, and one no generator can see.
+    // A class-level @Roles merges into every route, so it is documented here
+    // too. The document describes the metadata; enforcement is a separate call.
     const list = document.paths['/api/reports']?.get;
     logger.info(
       `class-level @Roles("admin") GET /api/reports -> security ` +

package/templates/features/health/health.module.ts

@@ -11,20 +11,16 @@ import { HealthDemo } from './health.demo.js';
 import { AppIndicators } from './indicators.js';
 
 /**
- * The indicators, in a module of their own for the reason `WorkspaceModule` is:
- * `HealthModule.forRootAsync` registers its provider in its own scope, so a factory
- * injecting `AppIndicators` has to name the module it comes from - and pointing that
- * back at `ProbesModule` would be a cycle.
- *
- * A health check is still the feature that imports the most, so this list is an
- * accurate statement of what it touches.
+ * Its own module because `HealthModule.forRootAsync` registers in its own scope,
+ * so a factory injecting `AppIndicators` must name where it comes from - and
+ * pointing that back at `ProbesModule` would be a cycle.
  */
 @Module({
   imports: [DatabaseModule, CacheModule, WorkspaceModule],
   providers: [
     provide(AppIndicators, {
-      // Async because the upload root is: `Workspace.create()` is idempotent, so
-      // this is the directory `FilesModule` already made rather than a second one.
+      // `Workspace.create()` is idempotent, so this is the directory
+      // `FilesModule` already made.
       useFactory: async (
         db: DbConnection,
         redis: RedisConnection,
@@ -45,13 +41,9 @@ import { AppIndicators } from './indicators.js';
 export class IndicatorsModule {}
 
 /**
- * `HealthModule` from `@dunx/http`, which mounts `/api/health/live` and
- * `/api/health/ready`. Both are `@Public()` and hidden from the OpenAPI document:
- * a probe carries no credentials and is not an API a consumer calls.
- *
- * There is no indicator for `@dunx/infra/files` or `@dunx/infra/images`. Both are
- * in-process, so "it booted" is already answered by the port answering at all, and
- * a check that cannot fail tells an operator nothing.
+ * Mounts `/api/health/live` and `/api/health/ready`, both `@Public()` and hidden
+ * from the document. No indicator for the in-process packages: a check that
+ * cannot fail tells an operator nothing.
  */
 @Module({
   imports: [
@@ -61,9 +53,8 @@ export class IndicatorsModule {}
       useFactory: (indicators: AppIndicators) => ({
         readiness: indicators.readiness,
         liveness: indicators.liveness,
-        // A real deployment sets a few probe intervals here, so a load balancer
-        // sees readiness fail before the socket closes. Short enough that
-        // `bun run tour` and the suites are not waiting on it.
+        // A real deployment tunes these so a load balancer sees readiness fail
+        // before the socket closes.
         drainDelayMs: 250,
       }),
       inject: [AppIndicators] as const,

package/templates/features/health/indicators.ts

@@ -12,12 +12,8 @@ import type { DbConnection } from '@dunx/infra/db';
 import type { RedisConnection } from '@dunx/infra/redis';
 import { Ledger } from '../database/ledger.service.js';
 
-/**
- * The custom-indicator path: an app-specific query rather than a round trip.
- *
- * `DatabaseIndicator` answers "does the connection answer". This answers "is the
- * data there", which is the part only the app knows how to ask.
- */
+/** A custom indicator: `DatabaseIndicator` asks whether the connection answers,
+ * this asks whether the data is there. */
 export class LedgerIndicator extends HealthIndicator {
   readonly name = 'ledger';
 
@@ -37,12 +33,8 @@ export class LedgerIndicator extends HealthIndicator {
 }
 
 /**
- * `RedisIndicator` with the criticality flipped, because this app treats a missing
- * cache as degraded rather than fatal - the same promise `CacheModule` makes with
- * lazy connections and `maxRetries: 0`.
- *
- * Shedding traffic here would be wrong: the routes that need Redis report
- * themselves degraded and every other route still works.
+ * `RedisIndicator` with the criticality flipped: a missing cache is degraded
+ * rather than fatal, matching `CacheModule`'s lazy connect and `maxRetries: 0`.
  */
 export class CacheIndicator extends RedisIndicator {
   override readonly critical = false;
@@ -57,21 +49,14 @@ export interface AppIndicatorsInit {
 }
 
 /**
- * The one declaration of what this service probes.
- *
- * It is a provider rather than two lists inlined into two factories because two
- * things read it: `HealthModule` answers `/api/health/ready`, and
- * `DashboardModule` lights the same checks on the ops page. A `HealthIndicator`
- * satisfies `DashboardProbe` as written, so neither side needs an adapter.
+ * One declaration of what this service probes, read by both `HealthModule` and
+ * `DashboardModule`. A `HealthIndicator` satisfies `DashboardProbe` as written.
  */
 export class AppIndicators {
   readonly readiness: readonly HealthIndicator[];
   readonly liveness: readonly HealthIndicator[];
-  /**
-   * The readiness list minus what the dashboard already sources itself:
-   * `DashboardOptions.redis` drives the Redis panel *and* a `redis` probe, so
-   * handing it `CacheIndicator` as well would light the same name twice.
-   */
+  /** Minus what the dashboard sources itself: `DashboardOptions.redis` already
+   * drives a `redis` probe, so `CacheIndicator` here would light it twice. */
   readonly dashboardProbes: readonly HealthIndicator[];
 
   constructor(init: AppIndicatorsInit) {
@@ -79,13 +64,12 @@ export class AppIndicators {
       new DatabaseIndicator(init.db),
       new LedgerIndicator(init.ledger),
       new CacheIndicator(init.redis),
-      // Non-critical, because no other pod's disk is any emptier.
       new DiskIndicator(
         new DiskOptions({ path: init.uploadRoot, maxUsedFraction: 0.95 }),
       ),
     ];
-    // A ceiling belongs on liveness, where the orchestrator restarts the process
-    // rather than routing around it.
+    // A ceiling belongs on liveness, where the orchestrator restarts rather
+    // than routes around.
     this.liveness = [
       new MemoryIndicator(
         new MemoryOptions({ maxRssBytes: 1024 * 1024 * 1024 }),

package/templates/features/http/compression.demo.ts

@@ -1,8 +1,7 @@
 import { Logger } from '@dunx/core';
 
-/** Large enough that every branch below is the interesting one. */
 const DOCUMENT = 'api/openapi.json';
-/** Two fields. Under the 1024-byte threshold, so it is sent as it is. */
+/** Under the 1024-byte threshold, so it is sent as it is. */
 const SMALL = 'api/notes/whoami';
 
 interface Measured {
@@ -12,10 +11,8 @@ interface Measured {
   readonly vary: string;
 }
 
-/**
- * `fetch` decodes the body itself but leaves `content-encoding` and the encoded
- * `content-length` on the response, so one request measures both sides.
- */
+/** `fetch` decodes the body but leaves `content-encoding` and the encoded
+ * `content-length`, so one request measures both sides. */
 const measure = async (
   url: string,
   path: string,
@@ -43,9 +40,8 @@ export class CompressionDemo {
   async demonstrate(url: string): Promise<void> {
     const { logger } = this;
 
-    // This folder is vendored by `@dunx/create-app`, and a scaffold that took
-    // `http` without `openapi` has no document to encode. Same convention as a
-    // part whose backing service is absent: say so and carry on.
+    // Vendored by `@dunx/create-app`: a scaffold taking `http` without `openapi`
+    // has no document to encode.
     const available = await fetch(new URL(DOCUMENT, url));
     await available.body?.cancel();
     if (!available.ok) {
@@ -53,8 +49,7 @@ export class CompressionDemo {
       return;
     }
 
-    // `identity` names a coding the app does not offer, so negotiation picks
-    // nothing and the body goes out unencoded.
+    // `identity` is a coding the app does not offer, so nothing is picked.
     for (const accept of ['identity', 'gzip', 'zstd', 'gzip, zstd']) {
       const m = await measure(url, DOCUMENT, accept);
       logger.info(
@@ -63,15 +58,12 @@ export class CompressionDemo {
       );
     }
 
-    // Both offered at the same q, so the server's own order decides. The app
-    // offers `['zstd', 'gzip']`: on a body this size the two compress to within
-    // 0.2% of each other and zstd is the faster encoder.
+    // Same q, so the server's order decides: `['zstd', 'gzip']`.
     const preferred = await measure(url, DOCUMENT, 'gzip, zstd');
     logger.info(
       `a tie in the client's q-values is broken by the server order -> ${preferred.encoding}`,
     );
 
-    // An explicit q-value outranks that order.
     const forced = await measure(url, DOCUMENT, 'zstd;q=0.1, gzip;q=0.9');
     logger.info(`zstd;q=0.1, gzip;q=0.9 -> ${forced.encoding}`);
 

package/templates/features/http/http.demo.ts

@@ -34,11 +34,8 @@ const postNote = (url: string, text: unknown): Promise<Response> =>
     body: JSON.stringify({ text }),
   });
 
-/**
- * `203.0.113.7` stands in for whatever the caller put in the header itself, and
- * `10.0.0.1` for the entry the one proxy in front of this app appended. With
- * `trust proxy` set to one hop, only the second is worth anything.
- */
+/** `203.0.113.7` is what the caller sent, `10.0.0.1` what the one proxy
+ * appended. With `trust proxy` at one hop, only the second counts. */
 const whoami = async (url: string, forwarded: boolean): Promise<string> => {
   const response = await fetch(new URL('api/notes/whoami', url), {
     headers: forwarded ? { 'x-forwarded-for': '203.0.113.7, 10.0.0.1' } : {},
@@ -83,28 +80,25 @@ export class HttpDemo {
         `${JSON.stringify(await rejected.json())}`,
     );
 
-    // Bun.serve answers a method miss with 404, so a preflight can never be
-    // inferred - enableCors mounts an explicit OPTIONS per path.
+    // Bun.serve answers a method miss with 404, so `enableCors` mounts an
+    // explicit OPTIONS per path.
     const allowed = await preflight(url, origin);
     logger.info(
       `enableCors: OPTIONS from ${origin} -> ${allowed.status} ${describeCors(allowed)}`,
     );
-    // A denied origin gets no CORS headers at all, which is what makes a browser
-    // block the response.
+    // A denied origin gets no CORS headers, which is what blocks the browser.
     const denied = await preflight(url, 'https://evil.test');
     logger.info(
       `OPTIONS from https://evil.test -> ${denied.status} ${describeCors(denied)}`,
     );
 
-    // One trusted hop, so the last entry wins and the caller's own leftmost
-    // entry is ignored. Reaching past the proxy takes set('trust proxy', 2).
+    // One trusted hop, so the last entry wins. Reaching past it takes 2.
     logger.info(
       `set("trust proxy", true): X-Forwarded-For sent -> ${await whoami(url, true)}`,
     );
     logger.info(`no header -> ${await whoami(url, false)}`);
 
-    // The route table and the middleware chain fold into one closure per route at
-    // listen(), so a late call could only ever be a silent no-op.
+    // Routes and middleware fold into one closure per route at listen().
     try {
       app.setGlobalPrefix('too-late');
     } catch (error) {

package/templates/features/http/request-trail.ts

@@ -7,15 +7,12 @@ export class RequestTrail {
 }
 
 /**
- * A class with `handle(req, ctx, next)`, resolved from the container - which is
- * what lets it inject. Chains are folded into one closure per route at boot, and
- * `ctx` is the route it was folded into: names, method, path, and its metadata.
+ * A class with `handle(req, ctx, next)`, resolved from the container so it can
+ * inject. `ctx` is the route the chain was folded into.
  *
- * **This does not log**, which is what the name says now and did not before.
- * `@dunx/http` installs `RequestLoggingMiddleware` itself - one structured entry
- * per request, tuned through `requestLogging` in bootstrap.ts - so an app writing
- * its own would write everything twice. What is left here is the part a framework
- * cannot supply: an app-specific side effect on a response the middleware can see.
+ * It does not log: `@dunx/http` writes the request entry itself, so an app doing
+ * its own would write everything twice. What is left is the app-specific side
+ * effect a framework cannot supply.
  */
 export class RequestTrailMiddleware implements Middleware {
   constructor(private readonly trail: RequestTrail) {}

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,
       }),