@dunx/create-app 3.1.2 → 3.2.0

package/README.md

@@ -40,8 +40,8 @@ There is no flag for choosing features. The command opens a list:
 | Ctrl+C, Esc     | Stop, having written nothing                  |
 
 `◉` is chosen, `◈` is pulled in by something else you chose, `○` is neither. The
-two lines under the list update as you go: what your selection drags in, and which
-of it needs Redis or Postgres running to do anything.
+two lines under the list update as you go: one shows what your selection drags in,
+the other shows which of it needs Redis or Postgres running to do anything.
 
 Three more questions appear only when there is something to ask: a directory, when
 the command line named none; a package name, when the directory's is one npm would
@@ -56,9 +56,10 @@ reject; and whether to write into a directory that already has files in it.
 | `--yes`, `-y`   | off                | Skip the questions, take the minimal template |
 | `--help`        |                    | Print usage                                   |
 
-**Piped, redirected or in CI it asks nothing** and writes the minimal template, so
-a script never hangs on a question nothing can answer. To choose features without
-a terminal, call [`scaffold`](#programmatic-use) rather than passing flags.
+**Piped, redirected or in CI it asks nothing.** It writes the minimal template
+instead, so a script never hangs on a question nothing can answer. To choose
+features without a terminal, call [`scaffold`](#programmatic-use) rather than
+passing flags.
 
 The name is validated against npm's rules **before** anything is created, because
 an invalid one would otherwise surface as a confusing `bun install` failure inside
@@ -73,8 +74,8 @@ bunx @dunx/create-app .
 
 `.git`, `.gitkeep`, `.DS_Store` and `LICENSE` do not count as contents, so a fresh
 repo or a clone of an empty GitHub repository is a valid target without a question.
-Nothing else is ignored: `.gitignore` and `README.md` both come out of the template,
-and overwriting your copy of either is what the last question asks about.
+Nothing else is ignored: `.gitignore` and `README.md` both come out of the template.
+Overwriting your copy of either is what the last question asks about.
 
 ## What a composed app looks like
 
@@ -89,9 +90,10 @@ my-api/
   bunfig.toml        the transform preload
 ```
 
-Three files are generated for the selection and the feature directories are copied.
-`main.ts` is one file rather than two: a test imports `createApp` from it, and the
-`import.meta.main` block at the bottom is what stops that starting a server.
+Three files are generated for the selection, and the feature directories are just
+copied. `main.ts` is one file rather than two: a test imports `createApp` from it,
+and the `import.meta.main` block at the bottom stops that same import from
+starting a server.
 
 **There is no worker entry point, even with queues.** `QueueModule` is given
 `consume: true`, so the container opens the bullmq workers at `onInit` and closes
@@ -100,18 +102,21 @@ forked by bullmq itself into `src/jobs/jobs.processor.ts`.
 
 ## What it generates
 
-The `minimal` template, the same app as
-[`examples/minimal`](https://github.com/petarzarkov/dunx/tree/main/examples/minimal) a service, a controller, a module, `HttpFactory.create`, one test against a real
+The `minimal` template is the same app as
+[`examples/minimal`](https://github.com/petarzarkov/dunx/tree/main/examples/minimal):
+a service, a controller, a module, `HttpFactory.create`, one test against a real
 server, and the `bunfig.toml` preload line that makes constructor injection work.
 
-Its `src/` is a **byte-for-byte copy** of that example, and a test in this package
+Its `src/` is a **byte-for-byte copy** of that example. A test in this package
 fails if the two ever drift.
 
 Every app also gets an `AGENTS.md` naming its layout, its commands and the rules
 dunx fails at boot over, plus a `CLAUDE.md` pointing at it. Both link
 <https://petarzarkov.github.io/dunx/setup.md>, which is served per release, rather
-than copying the framework's own instructions into your repository. The example is the one CI boots, so keeping them
-identical is what makes the template trustworthy rather than merely plausible.
+than copying the framework's own instructions into your repository.
+
+The example is the one CI boots, so keeping them identical makes the template
+trustworthy rather than merely plausible.
 
 ## Two details
 
@@ -146,7 +151,7 @@ const { directory, files } = await scaffold({
 ```
 
 This is the scripted path the removed `--with` flag used to be. `features` takes
-the same names the list shows, in any order, and pulls in what they require;
+the same names the list shows, in any order, and pulls in what they require.
 `FEATURES` exports the set. Omitting it writes the minimal template.
 
 `scaffold` throws `ScaffoldError` for anything the caller can fix - an unknown

package/dist/{chunk-tn4dnvcw.js → chunk-rv2w0t23.js}

@@ -284,6 +284,15 @@ var FEATURES = [
     dependencies: [],
     config: []
   },
+  {
+    name: "stats",
+    source: "stats",
+    summary: "Per-route request timings and per-operation query timings, as JSON.",
+    requires: ["database"],
+    module: { klass: "StatsModule", from: "./stats/stats.module.js" },
+    dependencies: [],
+    config: []
+  },
   {
     name: "client",
     source: "upstream",
@@ -495,11 +504,11 @@ var manifest = (features) => {
 `;
 };
 var THIRD_PARTY = Object.freeze({
-  zod: "^4.4.3",
-  "drizzle-orm": "^0.45.2",
-  "better-auth": "^1.6.25",
-  bullmq: "^6.0.5",
-  ioredis: "^6.0.0"
+  zod: "4.5.4",
+  "drizzle-orm": "0.45.2",
+  "better-auth": "1.6.25",
+  bullmq: "6.0.5",
+  ioredis: "6.0.0"
 });
 var versionOf = (dep) => THIRD_PARTY[dep] ?? "latest";
 var appModule = (name, features) => {
@@ -642,14 +651,17 @@ var main = (name, features) => {
       version: '0.1.0',
       root: AppModule,
     })` : "AppModule";
-  const options = websockets ? [
-    "// Multi-node websocket fan-out on `Bun.RedisClient`, so it costs no",
-    "// dependency. With no Redis running this degrades to single-process",
-    "// behaviour, logs one warning, and the app still boots.",
-    "websocket: { idleTimeout: 30 },",
-    "relay: new RedisRelay({ connectionTimeout: 500 }),",
-    "relayChannel: RELAY_CHANNEL,"
-  ] : [];
+  const options = [
+    ...has(features, "stats") ? ["metrics: true,"] : [],
+    ...websockets ? [
+      "// Multi-node websocket fan-out on `Bun.RedisClient`, so it costs no",
+      "// dependency. With no Redis running this degrades to single-process",
+      "// behaviour, logs one warning, and the app still boots.",
+      "websocket: { idleTimeout: 30 },",
+      "relay: new RedisRelay({ connectionTimeout: 500 }),",
+      "relayChannel: RELAY_CHANNEL,"
+    ] : []
+  ];
   const shaping = [
     "app.setGlobalPrefix('api');",
     ...assets ? ["app.use(StaticFiles);"] : [],

package/dist/cli.js

@@ -9,7 +9,7 @@ import {
   packageVersion,
   resolveFeatures,
   scaffold
-} from "./chunk-tn4dnvcw.js";
+} from "./chunk-rv2w0t23.js";
 
 // src/cli.ts
 import { parseArgs } from "util";

package/dist/generate.d.ts

@@ -3,7 +3,8 @@ import { type Feature } from './features.js';
 export declare const configGroupsFor: (features: readonly Feature[]) => readonly string[];
 export declare const manifest: (features: readonly Feature[]) => string;
 /**
- * Third-party ranges, pinned here rather than read off `examples/full` at run time:
+ * Third-party versions, exact for the reason dunx's own manifests are, and
+ * written here rather than read off `examples/full` at run time:
  * the generated app installs from npm and the example installs from the workspace,
  * so the example's manifest is not a statement about what a consumer should take.
  * `features.test.ts` checks these against the example's, which is what stops them

package/dist/index.js

@@ -8,7 +8,7 @@ import {
   featureNames,
   isValidPackageName,
   scaffold
-} from "./chunk-tn4dnvcw.js";
+} from "./chunk-rv2w0t23.js";
 export {
   FEATURES,
   ScaffoldError,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dunx/create-app",
-  "version": "3.1.2",
+  "version": "3.2.0",
   "description": "Scaffold a new dunx application - bunx @dunx/create-app my-api",
   "keywords": [
     "bun",

package/templates/features/chat/chat.gateway.ts

@@ -1,4 +1,4 @@
-import { Logger } from '@dunx/core';
+import { Gauge, Logger } from '@dunx/core';
 import {
   Gateway,
   HttpStatusCode,
@@ -18,6 +18,9 @@ import { Lobby } from './lobby.service.js';
  * upgrade as a native route. */
 @Gateway('/chat')
 export class ChatGateway {
+  /** A `Gauge` rather than a `Counter`: connections close as well as open. */
+  readonly #live = new Gauge();
+
   constructor(
     private readonly lobby: Lobby,
     private readonly logger: Logger,
@@ -41,9 +44,15 @@ export class ChatGateway {
   opened(socket: Socket): void {
     // Bun's own pub/sub: topics live in the runtime.
     socket.subscribe(Lobby.TOPIC);
+    this.#live.inc();
     socket.send('welcome');
   }
 
+  /** What the gauge reads, for the tour and for anything else that asks. */
+  get live(): number {
+    return this.#live.value;
+  }
+
   @OnMessage('say')
   say(text: string): { delivered: number } {
     // Broadcast reaches every subscriber; the return value replies to the sender.
@@ -69,6 +78,7 @@ export class ChatGateway {
 
   @OnClose()
   closed(socket: Socket, code: number): void {
+    this.#live.dec();
     this.logger.info(`${socket.data.path} closed with ${code}`);
   }
 }

package/templates/features/database/database.module.ts

@@ -2,6 +2,7 @@ import { Module } from '@dunx/core';
 import {
   DbConnection,
   DbModule,
+  QueryMetrics,
   SyncDatabase,
   SyncSqliteOptions,
 } from '@dunx/infra/db';
@@ -18,18 +19,24 @@ import * as schema from './schema.js';
     // `SyncSqliteOptions` runs SQLite in synchronous mode, so the token is
     // `SyncDatabase` and `transactionSync` is reachable. `SqliteOptions` is the
     // default and what an app wants if it might move to Postgres.
-    DbModule.forRootAsync(SyncDatabase, {
-      useFactory: (config: AppConfigService) =>
-        new SyncSqliteOptions({
-          // Required: the type argument every constructor below sees.
-          schema,
-          // A dotted path, checked against AppConfig the same way a top-level
-          // key is. `config.get('database').file` still reads the same value.
-          filename: config.get('database.file'),
-          pragmas: ['foreign_keys = ON'],
-        }),
-      inject: [AppConfigService],
-    }),
+    DbModule.forRootAsync(
+      SyncDatabase,
+      {
+        useFactory: (config: AppConfigService) =>
+          new SyncSqliteOptions({
+            // Required: the type argument every constructor below sees.
+            schema,
+            // A dotted path, checked against AppConfig the same way a top-level
+            // key is. `config.get('database').file` still reads the same value.
+            filename: config.get('database.file'),
+            pragmas: ['foreign_keys = ON'],
+          }),
+        inject: [AppConfigService],
+      },
+      // Times every query the driver runs, readable through `QueryMetrics` and
+      // shown on the dashboard's stats panel. Off by default.
+      { metrics: true },
+    ),
   ],
   controllers: [LedgerController],
   providers: [Ledger],
@@ -37,6 +44,6 @@ import * as schema from './schema.js';
    * Re-exported so importers can inject it. `DbModule` exports to this module
    * only; naming it again passes it on.
    */
-  exports: [SyncDatabase, DbConnection, Ledger],
+  exports: [SyncDatabase, DbConnection, Ledger, QueryMetrics],
 })
 export class DatabaseModule {}

package/templates/features/http/http-options.ts

@@ -66,9 +66,8 @@ export class AppHttpOptions extends HttpOptionsProvider {
       responseBody: log.responseBody,
       // The dashboard polls every five seconds and would bury everything else.
       ignorePrefix: ['/api/_dunx'],
-      // ~360 ns per request, so off by default. On here so `traceId` joins
-      // `requestId` and `@dunx/http/client` forwards it upstream.
-      trace: true,
+      // `trace` and `traceResponse` are not set: both are on by default, and
+      // `TraceController` reading the trace back proves it.
     };
   }
 }

package/templates/features/http/trace.controller.ts

@@ -5,8 +5,9 @@ import { Controller, Get, type Input, type RouteSchemas } from '@dunx/http';
  * What the request's W3C trace looks like from inside a handler.
  *
  * `RequestContext` is bound by `@dunx/core` whatever else the app imports, and
- * `requestLogging: { trace: true }` is what puts the trace fields into it. Every
- * log line this request writes carries the same three values.
+ * request logging puts the trace fields into it with nothing configured. Every
+ * log line this request writes carries the same values, and the response carries
+ * `traceresponse`. `requestLogging: { trace: false }` is what removes them.
  */
 @Controller('trace')
 export class TraceController {
@@ -17,13 +18,16 @@ export class TraceController {
     traceId: string | undefined;
     spanId: string | undefined;
     parentSpanId: string | undefined;
+    traceFlags: string | undefined;
     inbound: string | null;
   } {
-    const { traceId, spanId, parentSpanId } = this.context.getContext();
+    const { traceId, spanId, parentSpanId, traceFlags } =
+      this.context.getContext();
     return {
       traceId: traceId as string | undefined,
       spanId: spanId as string | undefined,
       parentSpanId: parentSpanId as string | undefined,
+      traceFlags: traceFlags as string | undefined,
       inbound: input.req.headers.get('traceparent'),
     };
   }

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

@@ -1,4 +1,4 @@
-import { Logger } from '@dunx/core';
+import { Counter, Logger } from '@dunx/core';
 import { Cron, Interval, OnceOnBoot } from '@dunx/infra/schedule';
 
 /**
@@ -6,13 +6,13 @@ import { Cron, Interval, OnceOnBoot } from '@dunx/infra/schedule';
  * with no second registration. Nothing here coordinates across replicas: work
  * that must happen once per fleet is a `@JobHandler`.
  *
- * 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.
+ * Counts go through `@dunx/core`'s `Counter` rather than a private field, which
+ * also sidesteps Bun 1.4.0 failing 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;
-  #compactions = 0;
+  readonly #sweeps = new Counter();
+  readonly #compactions = new Counter();
   #warmed = false;
 
   constructor(private readonly logger: Logger) {}
@@ -28,8 +28,8 @@ export class Maintenance {
   /** 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;
-    return this.#sweeps;
+    this.#sweeps.inc();
+    return this.#sweeps.value;
   }
 
   /**
@@ -39,14 +39,14 @@ export class Maintenance {
   @Cron('0 3 * * *', { name: 'maintenance.compact' })
   async compactLedger(): Promise<number> {
     await Bun.sleep(1);
-    this.#compactions = this.#compactions + 1;
-    return this.#compactions;
+    this.#compactions.inc();
+    return this.#compactions.value;
   }
 
   get counts(): { sweeps: number; compactions: number; warmed: boolean } {
     return {
-      sweeps: this.#sweeps,
-      compactions: this.#compactions,
+      sweeps: this.#sweeps.value,
+      compactions: this.#compactions.value,
       warmed: this.#warmed,
     };
   }

package/templates/features/stats/stats.demo.ts

@@ -0,0 +1,69 @@
+import { EventLoopLag, Logger } from '@dunx/core';
+import { RequestMetrics } from '@dunx/http';
+import { QueryMetrics } from '@dunx/infra/db';
+
+/** Read out of the same container, from work the tour already did. */
+export class StatsDemo {
+  constructor(
+    private readonly logger: Logger,
+    private readonly requests: RequestMetrics,
+    private readonly queries: QueryMetrics,
+    private readonly lag: EventLoopLag,
+  ) {}
+
+  demonstrate(): void {
+    const http = this.requests.snapshot();
+    const ms = (nanoseconds: number | undefined): string =>
+      nanoseconds === undefined ? '-' : `${(nanoseconds / 1e6).toFixed(2)}ms`;
+
+    this.logger.info(
+      `${http.routes.length} route series, ${http.inFlight} in flight, ` +
+        `${http.pendingWebSockets} sockets - both read off Bun.serve, not counted`,
+    );
+
+    const slowest = [...http.routes]
+      .sort((a, b) => (b.duration.p99 ?? 0) - (a.duration.p99 ?? 0))
+      .slice(0, 3);
+    for (const route of slowest) {
+      this.logger.info(
+        `${route.method} ${route.route}: ${route.count} calls, ` +
+          `p50 ${ms(route.duration.p50)} p99 ${ms(route.duration.p99)} ` +
+          `max ${ms(route.duration.max)}`,
+      );
+    }
+
+    const worst = slowest[0];
+    if (worst?.slowestTraceId !== undefined) {
+      this.logger.info(
+        `the slowest ${worst.route} call has traceId ${worst.slowestTraceId} - ` +
+          'every line that request wrote carries it',
+      );
+    }
+
+    const unmatched = http.routes.find(
+      (route) => route.route === '(unmatched)',
+    );
+    this.logger.info(
+      `unmatched paths: ${unmatched?.count ?? 0} across one series, so a ` +
+        'scanner walking urls cannot grow the series count',
+    );
+
+    const db = this.queries.snapshot();
+    this.logger.info(
+      `${db.total} queries, timed at the bun:sqlite handle dunx constructs - ` +
+        "drizzle's own logQuery fires before the statement runs and cannot time one",
+    );
+    for (const operation of db.operations) {
+      this.logger.info(
+        `${operation.operation}: ${operation.count} calls, ` +
+          `${operation.errors} failed, p99 ${ms(operation.duration.p99)}`,
+      );
+    }
+
+    const loop = this.lag.snapshot();
+    this.logger.info(
+      `event loop lag: ${loop.count} samples, p99 ${ms(loop.p99)} ` +
+        `max ${ms(loop.max)}`,
+    );
+  }
+}

package/templates/features/stats/stats.module.ts

@@ -0,0 +1,14 @@
+import { EventLoopLag, Module } from '@dunx/core';
+import { DatabaseModule } from '../database/database.module.js';
+import { StatsDemo } from './stats.demo.js';
+
+/**
+ * `RequestMetrics` is global, so only `QueryMetrics` is imported. `EventLoopLag`
+ * is a provider so its `onInit` enables it at boot rather than at read time.
+ */
+@Module({
+  imports: [DatabaseModule],
+  providers: [EventLoopLag, StatsDemo],
+  exports: [StatsDemo],
+})
+export class StatsModule {}

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

@@ -9,7 +9,7 @@ import { HealthClient } from './health.client.js';
 /**
  * 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.
+ * the inbound trace.
  */
 export class UpstreamDemo {
   constructor(

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

@@ -21,8 +21,10 @@ import { UpstreamDemo } from './upstream.demo.js';
           retryDelayMs: 20,
           backoff: { jitterMs: 10, maxMs: 200 },
         },
-        // The inbound request id, forwarded so one trace spans both services.
-        propagateRequestId: true,
+        // The inbound trace, forwarded as `traceparent` so one trace spans
+        // both services. On by default; stated here because it is the point of
+        // this module.
+        propagateTrace: true,
       }),
       inject: [AppConfigService] as const,
     }),

package/templates/minimal/README.md

@@ -26,12 +26,12 @@ preload = ["@dunx/transform/preload"]
 ```
 
 `@dunx/transform` reads each class's constructor parameter types when the file
-loads and records them, so the container can resolve them before calling `new`.
-Without it, providers are constructed with no arguments and boot fails saying so -
-it is not a silent `undefined`.
+loads and records them. The container uses that record to resolve them before
+calling `new`. Without it, providers are constructed with no arguments, and boot
+fails by naming the problem rather than returning a silent `undefined`.
 
 That is also why there is no `@Injectable()` and no `@Inject()`. Being listed in a
-module's `providers` is what makes a class injectable, and TC39 standard decorators
+module's `providers` is what makes a class injectable. TC39 standard decorators
 have no parameter decorators, so `@Inject()` does not exist.
 
 ## Next