@dunx/create-app 2.5.0 → 3.0.0

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.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,9 @@ 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 - and it is **never validated at runtime**:
- * the verb decorator holds the handler's return type to it instead, so a route
- * declaring this cannot answer with anything else and still compile.
- *
- * That check is what caught this schema declaring a `tags: string[]` the `users`
- * table has no column for. Every user response advertised an array no handler
- * returned. `tags` stays on {@link CreateUser}, the request side, where it is
- * read - a documented response is a view of the row, and this one is the row.
+ * 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({
@@ -70,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) },
@@ -80,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] });

package/templates/minimal/src/greetings.controller.ts

@@ -1,13 +1,6 @@
 import { Controller, Get, type Input, type RouteSchemas } from '@dunx/http';
 import { GreetingsService } from './greetings.service.js';
 
-/**
- * A controller is a provider with routes on it. `GreetingsService` in the
- * constructor is resolved the same way the service's own `Logger` was.
- *
- * Returning a plain object is enough - `@dunx/http` serialises it. There is no
- * `Response.json()` to remember and no `res` to forget to send.
- */
 @Controller('greetings')
 export class GreetingsController {
   constructor(private readonly greetings: GreetingsService) {}
@@ -17,11 +10,8 @@ export class GreetingsController {
     return { routes: ['GET /greetings', 'GET /greetings/:name'] };
   }
 
-  /**
-   * No schemas are declared, so a path param stays on `input.req.params` as a
-   * string. Declaring a `params` schema is what makes it typed and coerced -
-   * `examples/full` does that; this one is showing the shape, not validation.
-   */
+  // With no `params` schema declared, a path param stays a string.
+  // `examples/full` shows the typed, coerced version.
   @Get('/:name')
   one(input: Input<RouteSchemas>): { greeting: string; served: number } {
     return this.greetings.greet(input.req.params['name'] ?? 'world');

package/templates/minimal/src/greetings.service.ts

@@ -1,20 +1,12 @@
 import { Logger, type OnInit } from '@dunx/core';
 
-/**
- * A provider. No decorator, no registration boilerplate - being listed in a
- * module's `providers` is what makes it injectable.
- *
- * `Logger` in the constructor is the whole dependency injection story: the
- * container reads the parameter's type and resolves it. Nothing bound `Logger`
- * here, so it gets core's default `ConsoleLogger`, which writes one JSON line
- * per entry and needs no dependency.
- */
+/** A provider is a plain class. Listing it in a module's `providers` is what
+ * makes it injectable; the container reads `Logger` off the constructor. */
 export class GreetingsService implements OnInit {
   #greeted = 0;
 
   constructor(private readonly logger: Logger) {}
 
-  /** Runs after the whole graph is constructed, in dependency order. */
   onInit(): void {
     this.logger.info('greetings ready');
   }

package/templates/minimal/src/main.ts

@@ -1,11 +1,6 @@
 import { HttpFactory } from '@dunx/http';
 import { AppModule } from './app.module.js';
 
-/**
- * `create()` builds the container and discovers routes; `listen()` builds the
- * `Bun.serve` route table and returns the URL. `enableShutdownHooks()` makes
- * `ctrl-c` drain the graph in reverse construction order.
- */
 const app = await HttpFactory.create(AppModule);
 app.enableShutdownHooks();