@dunx/create-app 3.3.1 → 3.3.2

package/README.md

@@ -43,6 +43,12 @@ There is no flag for choosing features. The command opens a list:
 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.
 
+After the list, one more question: whether to compile the app to a single
+standalone binary. Yes adds a `scripts/build.ts` and a `build` script, so
+`bun run build` writes one executable with `bun build --compile` that a host runs
+with nothing installed. It needs Bun >= 1.4.1, the floor the generated
+`package.json` already declares.
+
 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
 reject; and whether to write into a directory that already has files in it.
@@ -152,7 +158,9 @@ 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.
-`FEATURES` exports the set. Omitting it writes the minimal template.
+`FEATURES` exports the set. Omitting it writes the minimal template. `binary: true`
+adds the standalone-binary build, and forces the generation path so it works with
+no features too.
 
 `scaffold` throws `ScaffoldError` for anything the caller can fix - an unknown
 template, an unusable package name, a non-empty target without `force` - and lets

package/dist/build-template.d.ts

@@ -0,0 +1,9 @@
+/** The binary a compiled build writes, from the package name's last segment. */
+export declare const binaryName: (name: string) => string;
+/**
+ * The `scripts/build.ts` a `binary` scaffold gets. `Bun.build` takes both the
+ * `@dunx/transform` plugin and `compile`, so the constructor-dependency records
+ * the container resolves are baked into the executable at build time - a compiled
+ * binary has no load-time plugin to record them.
+ */
+export declare const buildScript: (name: string) => string;

package/dist/{chunk-nznx4cv8.js → chunk-akm69d19.js}

@@ -456,6 +456,39 @@ var agentFiles = (name, features) => ({
   "CLAUDE.md": CLAUDE_POINTER
 });
 
+// src/build-template.ts
+var binaryName = (name) => name.split("/").at(-1) ?? name;
+var buildScript = (name) => `// Generated by @dunx/create-app for ${name}. Yours to edit.
+import { depsPlugin } from '@dunx/transform';
+import { join, resolve } from 'node:path';
+
+const DIR = resolve(import.meta.dir, '..');
+const outfile = join(DIR, 'dist', '${binaryName(name)}');
+
+const compiled = await Bun.build({
+  entrypoints: [join(DIR, 'src/main.ts')],
+  target: 'bun',
+  // One self-contained executable: the Bun runtime plus the app in one file, so a
+  // host needs nothing installed to run it.
+  compile: { outfile },
+  plugins: [depsPlugin],
+  minify: true,
+  // A stack trace is never read off a shipped binary; symbols would only add size.
+  sourcemap: 'none',
+  tsconfig: join(DIR, 'tsconfig.json'),
+});
+
+if (!compiled.success) {
+  for (const log of compiled.logs) console.error(log);
+  throw new AggregateError(compiled.logs, 'compile failed');
+}
+
+const bytes = await Bun.file(outfile).bytes();
+console.log(
+  \`Built \${(bytes.byteLength / 1024 / 1024).toFixed(1)} MB -> \${outfile}\`,
+);
+`;
+
 // src/generate.ts
 var HEADER = (name) => `// Generated by @dunx/create-app for ${name}. Yours to edit.
 `;
@@ -475,7 +508,7 @@ var dependenciesFor = (features) => uniq([
   ...features.flatMap((feature) => feature.dependencies)
 ]).sort();
 var DUNX = /^@dunx\//;
-var manifest = (features) => {
+var manifest = (features, binary = false) => {
   const deps = dependenciesFor(features);
   const dependencies = {};
   for (const dep of deps) {
@@ -484,6 +517,7 @@ var manifest = (features) => {
   const scripts = {
     dev: "bun --watch src/main.ts",
     start: "bun src/main.ts",
+    ...binary ? { build: "bun scripts/build.ts" } : {},
     test: "bun test",
     typecheck: "tsc --noEmit"
   };
@@ -746,8 +780,9 @@ ${lines.join(`
 `)}
 `;
 };
-var readme = (name, features) => {
+var readme = (name, features, binary = false) => {
   const services = features.filter((feature) => feature.service !== undefined);
+  const bin = binaryName(name);
   return `# ${name}
 
 Scaffolded with \`bunx @dunx/create-app\`.
@@ -757,6 +792,24 @@ bun install
 bun run dev     # restarts on a change
 bun run start
 \`\`\`
+${binary ? `
+## Compile to a binary
+
+\`\`\`bash
+bun run build   # -> dist/${bin} (the Bun runtime plus the app, one file)
+\`\`\`
+
+\`scripts/build.ts\` hands \`Bun.build\` the \`@dunx/transform\` plugin and \`compile\`
+together, so the constructor-dependency records the container needs are baked into
+the executable. This needs Bun >= 1.4.1, the version \`package.json\` already
+requires: an earlier one dropped the records. Copy \`dist/${bin}\` to a host and run
+it; it needs nothing installed.
+
+Run it from a directory without this app's \`bunfig.toml\`. A standalone bun
+executable still reads \`preload\` from the working directory's bunfig and would try
+to load \`@dunx/transform/preload\`, which the binary no longer needs and cannot
+resolve. A deployment host has no such file.
+` : ""}
 
 ## What is wired up
 
@@ -821,15 +874,16 @@ var packageVersion = async () => {
   return json.version ?? "0.0.0";
 };
 var fill = (contents, name, version) => contents.replaceAll(VERSION_PLACEHOLDER2, version).replaceAll("__DUNX_APP_NAME__", name);
-var generated = (name, features) => {
+var generated = (name, features, binary) => {
   const groups = configGroupsFor(features);
   return {
-    "package.json": manifest(features),
-    "README.md": readme(name, features),
+    "package.json": manifest(features, binary),
+    "README.md": readme(name, features, binary),
     ".env.example": envExample(groups),
     "src/main.ts": main(name, features),
     "src/app.module.ts": appModule(name, features),
-    "src/config.ts": config(name, groups)
+    "src/config.ts": config(name, groups),
+    ...binary ? { "scripts/build.ts": buildScript(name) } : {}
   };
 };
 var scaffold2 = async (options) => {
@@ -844,7 +898,8 @@ var scaffold2 = async (options) => {
   } catch (error) {
     throw new ScaffoldError2(error instanceof Error ? error.message : String(error));
   }
-  const composing = features.length > 0;
+  const binary = options.binary === true;
+  const composing = features.length > 0 || binary;
   const directory = resolve(options.cwd ?? process.cwd(), options.target);
   const name = options.name ?? basename(directory);
   if (!isValidPackageName2(name)) {
@@ -892,6 +947,7 @@ var scaffold2 = async (options) => {
       name,
       template,
       features: [],
+      binary: false,
       files: written.sort()
     };
   }
@@ -908,7 +964,7 @@ var scaffold2 = async (options) => {
     await copyTree(from, join("src", feature.source));
   }
   await writeAll({
-    ...generated(name, features),
+    ...generated(name, features, binary),
     ...agentFiles(name, features)
   });
   return {
@@ -916,6 +972,7 @@ var scaffold2 = async (options) => {
     name,
     template: "composed",
     features: features.map((feature) => feature.name),
+    binary,
     files: written.sort()
   };
 };

package/dist/cli.js

@@ -9,7 +9,7 @@ import {
   isValidPackageName2,
   packageVersion,
   scaffold2
-} from "./chunk-nznx4cv8.js";
+} from "./chunk-akm69d19.js";
 
 // src/cli.ts
 import { parseArgs } from "util";
@@ -673,8 +673,14 @@ class Wizard {
     const target = defaults.target ?? await this.#runner.ask(new DirectoryPrompt(this.#style, "Directory", DEFAULT_TARGET));
     const name = await this.#name(defaults, target);
     const features = await this.#runner.ask(new FeaturePrompt(this.#style, defaults.features));
+    const binary = await this.#binary(defaults);
     const force = await this.#force(defaults, target);
-    return { target, name, features, force };
+    return { target, name, features, binary, force };
+  }
+  async#binary(defaults) {
+    if (defaults.binary !== undefined)
+      return defaults.binary;
+    return this.#runner.ask(new ConfirmPrompt(this.#style, "Compile to a standalone binary?", false));
   }
   async#name(defaults, target) {
     if (defaults.name !== undefined)
@@ -766,6 +772,7 @@ var byAsking = async () => {
     target,
     name: values.name,
     features: [],
+    binary: undefined,
     force: values.force === true,
     cwd: process.cwd()
   });
@@ -802,6 +809,9 @@ Created ${result.name} in ${where}/`);
     console.log(`  cd ${where}`);
   console.log("  bun install");
   console.log(`  bun run dev  ${style.muted("# or `start`, which does not watch")}`);
+  if (result.binary) {
+    console.log(`  bun run build  ${style.muted("# compile to one standalone binary")}`);
+  }
 } catch (error) {
   if (error instanceof CancelledError) {
     console.log(style.muted(error.message));

package/dist/generate.d.ts

@@ -1,7 +1,7 @@
 import { type Feature } from './features.js';
 /** Every config group the selection needs, base first, in a stable order. */
 export declare const configGroupsFor: (features: readonly Feature[]) => readonly string[];
-export declare const manifest: (features: readonly Feature[]) => string;
+export declare const manifest: (features: readonly Feature[], binary?: boolean) => string;
 /**
  * Third-party versions, exact for the reason dunx's own manifests are, and
  * written here rather than read off `examples/full` at run time:
@@ -15,4 +15,4 @@ export declare const appModule: (name: string, features: readonly Feature[]) =>
 export declare const config: (name: string, groups: readonly string[]) => string;
 export declare const main: (name: string, features: readonly Feature[]) => string;
 export declare const envExample: (groups: readonly string[]) => string;
-export declare const readme: (name: string, features: readonly Feature[]) => string;
+export declare const readme: (name: string, features: readonly Feature[], binary?: boolean) => string;

package/dist/index.js

@@ -8,7 +8,7 @@ import {
   ScaffoldError2,
   isValidPackageName2,
   scaffold2
-} from "./chunk-nznx4cv8.js";
+} from "./chunk-akm69d19.js";
 export {
   FEATURES2 as FEATURES,
   ScaffoldError2 as ScaffoldError,

package/dist/scaffold.d.ts

@@ -32,6 +32,12 @@ export interface ScaffoldOptions {
      * what it was.
      */
     readonly features?: readonly string[];
+    /**
+     * Add a `scripts/build.ts` and a `build` script that compile the app to one
+     * standalone executable. Forces the generation path, so it works with no
+     * features chosen too.
+     */
+    readonly binary?: boolean;
     /** Write into a directory that already has files in it. */
     readonly force?: boolean;
     readonly cwd?: string;
@@ -44,6 +50,8 @@ export interface ScaffoldResult {
     readonly template: TemplateName | 'composed';
     /** Resolved feature names, in import order. Empty for a fixed template. */
     readonly features: readonly string[];
+    /** Whether a standalone-binary build was generated. */
+    readonly binary: boolean;
     readonly files: readonly string[];
 }
 export declare class ScaffoldError extends Error {

package/dist/wizard.d.ts

@@ -4,6 +4,7 @@ export interface WizardAnswers {
     readonly target: string;
     readonly name: string;
     readonly features: readonly string[];
+    readonly binary: boolean;
     readonly force: boolean;
 }
 /** What the flags already settled, so the wizard skips asking again. */
@@ -11,16 +12,19 @@ export interface WizardDefaults {
     readonly target: string | undefined;
     readonly name: string | undefined;
     readonly features: readonly string[];
+    /** `undefined` asks; a boolean skips the question, the way `target` does. */
+    readonly binary: boolean | undefined;
     readonly force: boolean;
     readonly cwd: string;
 }
 /**
  * The questions, in the order the answers are needed.
  *
- * Each one is skipped when there is nothing to ask: a target given on the command
- * line, a package name that is already legal, a directory that is already empty.
- * Running `bunx @dunx/create-app my-api` in a clean directory therefore asks one
- * question, the one nothing else can answer.
+ * The directory, package name and force questions are skipped when there is
+ * nothing to ask: a target given on the command line, a package name that is
+ * already legal, a directory that is already empty. Running
+ * `bunx @dunx/create-app my-api` in a clean directory therefore asks the two that
+ * nothing else can answer, features and the binary build.
  */
 export declare class Wizard {
     #private;

package/package.json

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

package/templates/features/cache/cache.controller.ts

@@ -42,33 +42,35 @@ export class CacheController {
   }
 
   @Get('/:id', oneSession)
-  async read(
-    input: Input<typeof oneSession>,
-  ): Promise<{ id: string; data: unknown; ttl: number }> {
-    const found = await this.degrades(() =>
-      this.sessions.read(input.params.id),
-    );
+  async read({ params }: Input<typeof oneSession>): Promise<{
+    id: string;
+    data: unknown;
+    ttl: number;
+  }> {
+    const found = await this.degrades(() => this.sessions.read(params.id));
     if (found === null) {
       throw new HttpError(
         HttpStatusCode.NOT_FOUND,
-        `No session "${input.params.id}"`,
+        `No session "${params.id}"`,
       );
     }
     return found;
   }
 
   @Put('/:id', putSession)
-  store(
-    input: Input<typeof putSession>,
-  ): Promise<{ id: string; ttl: number; visits: number }> {
+  store({ body, params }: Input<typeof putSession>): Promise<{
+    id: string;
+    ttl: number;
+    visits: number;
+  }> {
     return this.degrades(() =>
-      this.sessions.store(input.params.id, input.body.data, input.body.ttl),
+      this.sessions.store(params.id, body.data, body.ttl),
     );
   }
 
   @Delete('/:id', oneSession)
-  remove(input: Input<typeof oneSession>): Promise<{ removed: number }> {
-    return this.degrades(() => this.sessions.remove(input.params.id));
+  remove({ params }: Input<typeof oneSession>): Promise<{ removed: number }> {
+    return this.degrades(() => this.sessions.remove(params.id));
   }
 
   private async degrades<T>(run: () => Promise<T>): Promise<T> {

package/templates/features/chat/chat.demo.ts

@@ -2,61 +2,10 @@ import { Logger, Module } from '@dunx/core';
 import { HttpFactory, PubSub, type HttpApp } from '@dunx/http';
 import { isConnectionError, RedisConnection } from '@dunx/infra/redis';
 import { RELAY_CHANNEL } from '../config.js';
+import { connect, type Client } from './ws-client.js';
 import { ChatGateway } from './chat.gateway.js';
 import { Lobby } from './lobby.service.js';
 
-interface Client {
-  next(): Promise<string>;
-  send(event: string, data: unknown): void;
-  close(): void;
-  /** Every frame this socket ever received, so a *second* delivery is visible. */
-  readonly received: readonly string[];
-}
-
-/** A real `new WebSocket()`, with a deadline so a stall fails instead of hanging. */
-const connect = async (base: string): Promise<Client> => {
-  const socket = new WebSocket(
-    new URL('chat', base).href.replace('http', 'ws'),
-  );
-  const frames: string[] = [];
-  const received: string[] = [];
-  const waiting: ((frame: string) => void)[] = [];
-
-  socket.addEventListener('message', (event: MessageEvent) => {
-    const frame = String(event.data);
-    received.push(frame);
-    const waiter = waiting.shift();
-    if (waiter) waiter(frame);
-    else frames.push(frame);
-  });
-  await new Promise<void>((resolve, reject) => {
-    socket.addEventListener('open', () => resolve(), { once: true });
-    setTimeout(() => reject(new Error('the socket never opened')), 2000);
-  });
-
-  return {
-    next: () =>
-      new Promise<string>((resolve, reject) => {
-        const queued = frames.shift();
-        if (queued !== undefined) {
-          resolve(queued);
-          return;
-        }
-        const timer = setTimeout(
-          () => reject(new Error('no frame arrived')),
-          2000,
-        );
-        waiting.push((frame) => {
-          clearTimeout(timer);
-          resolve(frame);
-        });
-      }),
-    send: (event, data) => socket.send(JSON.stringify({ event, data })),
-    close: () => socket.close(),
-    received,
-  };
-};
-
 /**
  * A second node in-process: two `Bun.serve` instances, two containers, two
  * `PubSub` origin ids. It reuses the same `ChatGateway` and excludes `ChatDemo`,

package/templates/features/chat/chat.module.ts

@@ -1,6 +1,7 @@
 import { Module } from '@dunx/core';
 import { CacheModule } from '../cache/cache.module.js';
 import { ChatDemo } from './chat.demo.js';
+import { PostgresRelayDemo } from './postgres-relay.demo.js';
 import { ChatGateway } from './chat.gateway.js';
 import { Lobby } from './lobby.service.js';
 
@@ -9,7 +10,7 @@ import { Lobby } from './lobby.service.js';
 @Module({
   // `RedisConnection`, for cross-process fan-out.
   imports: [CacheModule],
-  providers: [ChatGateway, Lobby, ChatDemo],
-  exports: [Lobby, ChatDemo],
+  providers: [ChatGateway, Lobby, ChatDemo, PostgresRelayDemo],
+  exports: [Lobby, ChatDemo, PostgresRelayDemo],
 })
 export class ChatModule {}

package/templates/features/chat/postgres-relay.demo.ts

@@ -0,0 +1,171 @@
+import { Logger, Module, provide } from '@dunx/core';
+import {
+  HttpFactory,
+  HttpOptionsProvider,
+  PubSub,
+  WsRelay,
+  WsRelayModule,
+  type PubSubRelay,
+} from '@dunx/http';
+import { RELAY_CHANNEL } from '../config.js';
+import { ChatGateway } from './chat.gateway.js';
+import { Lobby } from './lobby.service.js';
+import { connect } from './ws-client.js';
+
+/**
+ * Read here rather than injected: the module is declared at file scope, so it
+ * cannot reach `ConfigService`. The default matches `compose.yml` and the schema's.
+ */
+const POSTGRES_URL =
+  Bun.env['POSTGRES_URL'] ?? 'postgres://dunx:dunx@localhost:5432/dunx';
+
+/** Host and database only. The url carries a password and a log outlives it. */
+const where = (url: string): string => {
+  try {
+    const parsed = new URL(url);
+    return `${parsed.host}${parsed.pathname}`;
+  } catch {
+    return 'the configured Postgres';
+  }
+};
+
+/**
+ * The same fan-out as the Redis relay, over `Bun.SQL`'s `LISTEN`/`NOTIFY`, for an
+ * app that already has Postgres and would rather not run a broker.
+ *
+ * Two nodes, each with its own `WsRelayModule.forPostgres` and its own `PubSub`
+ * origin. Neither shares a container with the other, which is what makes the
+ * delivery real rather than a same-process shortcut.
+ */
+/**
+ * Binding the relay is not the same as using it. `WsRelayModule` puts a `WsRelay`
+ * in the container; what attaches it to `PubSub` is an `HttpOptionsProvider`
+ * answering `relay`, exactly as `AppHttpOptions` does for the app itself. Without
+ * this the nodes come up, the sockets work, and every publish stays local.
+ */
+class NodeHttpOptions extends HttpOptionsProvider {
+  constructor(private readonly bus: WsRelay) {
+    super();
+  }
+
+  override get relay(): PubSubRelay {
+    return this.bus;
+  }
+
+  override readonly relayChannel = RELAY_CHANNEL;
+}
+
+@Module({
+  imports: [WsRelayModule.forPostgres({ url: POSTGRES_URL })],
+  providers: [
+    ChatGateway,
+    Lobby,
+    // Bound to the token `HttpFactory` asks for, not registered as itself:
+    // the factory looks up `HttpOptionsProvider` and promotes a default when
+    // nothing answers it, so a bare subclass in `providers` is never consulted.
+    provide(HttpOptionsProvider, { useClass: NodeHttpOptions }),
+  ],
+})
+class PostgresNode {}
+
+interface Node {
+  readonly app: Awaited<ReturnType<typeof HttpFactory.create>>;
+  readonly url: string;
+  readonly pubsub: PubSub;
+}
+
+/** Postgres caps a `NOTIFY` payload at 7999 bytes, envelope included. */
+const OVER_THE_NOTIFY_CAP = 9000;
+
+export class PostgresRelayDemo {
+  constructor(private readonly logger: Logger) {}
+
+  async demonstrate(): Promise<void> {
+    const { logger } = this;
+    if (!(await this.#postgresUp())) {
+      logger.warn(
+        `skipping the Postgres relay demo: nothing answering at ${where(POSTGRES_URL)}`,
+      );
+      logger.info('`bun run services:up` starts it, and CI runs the same file');
+      return;
+    }
+
+    // Started one at a time and collected as they come up. `Promise.all` rejects
+    // on the first failure and abandons a peer that had already bound a port,
+    // which keeps the process alive after the demo has given up.
+    const nodes: Node[] = [];
+    try {
+      nodes.push(await this.#node(), await this.#node());
+      const [a, b] = nodes as [Node, Node];
+      logger.info(
+        `two nodes on LISTEN/NOTIFY, origins …${a.pubsub.origin.slice(-6)} / …${b.pubsub.origin.slice(-6)}`,
+      );
+
+      const [onA, onB] = await Promise.all([connect(a.url), connect(b.url)]);
+      await Promise.all([onA.next(), onB.next()]);
+
+      const said = 'across nodes, over Postgres';
+      a.pubsub.publishEvent(Lobby.TOPIC, 'said', said);
+      logger.info(
+        `node B's client <- ${await onB.next()} (relayed via NOTIFY)`,
+      );
+
+      await Bun.sleep(250);
+      const seen = (frames: readonly string[]): number =>
+        frames.filter((frame) => frame.includes(said)).length;
+      logger.info(
+        `deliveries: A ${seen(onA.received)}, B ${seen(onB.received)} ` +
+          '(one each, so the publisher did not fan its own frame out twice)',
+      );
+
+      // Postgres refuses the NOTIFY rather than truncating it. The publish is
+      // reported and fan-out stays local, which is the documented degradation.
+      const huge = 'x'.repeat(OVER_THE_NOTIFY_CAP);
+      a.pubsub.publishEvent(Lobby.TOPIC, 'said', huge);
+      await Bun.sleep(400);
+      const huge_ = (frames: readonly string[]): number =>
+        frames.filter((frame) => frame.includes(huge)).length;
+      logger.info(
+        `a ${OVER_THE_NOTIFY_CAP}-byte frame: A ${huge_(onA.received)}, B ${huge_(onB.received)} ` +
+          '(over the 7999-byte NOTIFY cap, so the publishing node still delivers ' +
+          'it and the relay reports one warn)',
+      );
+
+      onA.close();
+      onB.close();
+      await Bun.sleep(20);
+    } finally {
+      await Promise.all(nodes.map((node) => node.app.shutdown()));
+    }
+  }
+
+  async #node(): Promise<Node> {
+    const app = await HttpFactory.create(PostgresNode, {
+      requestLogging: false,
+    });
+    try {
+      const url = await app.listen(0);
+      return { app, url, pubsub: app.get(PubSub) };
+    } catch (error) {
+      // The container is up even when the port is not, so it is ours to close.
+      await app.shutdown();
+      throw error;
+    }
+  }
+
+  /** A relay demo needs its backend; an absent one is a skip, not a failure. */
+  async #postgresUp(): Promise<boolean> {
+    const sql = new Bun.SQL(POSTGRES_URL, {
+      max: 1,
+      connectionTimeout: 2,
+    });
+    try {
+      await sql`select 1`;
+      return true;
+    } catch {
+      return false;
+    } finally {
+      await sql.close().catch(() => undefined);
+    }
+  }
+}

package/templates/features/chat/ws-client.ts

@@ -0,0 +1,65 @@
+/**
+ * A real `new WebSocket()` against the chat gateway, with a deadline so a stall
+ * fails instead of hanging.
+ *
+ * Shared rather than copied: both relay demos and the soak workload open sockets
+ * the same way, and a second copy of the frame-queue handling is where the two
+ * would drift.
+ */
+export interface Client {
+  next(): Promise<string>;
+  send(event: string, data: unknown): void;
+  close(): void;
+  /** Every frame this socket ever received, so a *second* delivery is visible. */
+  readonly received: readonly string[];
+}
+
+/** A real `new WebSocket()`, with a deadline so a stall fails instead of hanging. */
+export const connect = async (base: string): Promise<Client> => {
+  const socket = new WebSocket(
+    new URL('chat', base).href.replace('http', 'ws'),
+  );
+  const frames: string[] = [];
+  const received: string[] = [];
+  const waiting: ((frame: string) => void)[] = [];
+
+  socket.addEventListener('message', (event: MessageEvent) => {
+    const frame = String(event.data);
+    received.push(frame);
+    const waiter = waiting.shift();
+    if (waiter) waiter(frame);
+    else frames.push(frame);
+  });
+  await new Promise<void>((resolve, reject) => {
+    socket.addEventListener('open', () => resolve(), { once: true });
+    setTimeout(() => reject(new Error('the socket never opened')), 2000);
+  });
+
+  return {
+    next: () =>
+      new Promise<string>((resolve, reject) => {
+        const queued = frames.shift();
+        if (queued !== undefined) {
+          resolve(queued);
+          return;
+        }
+        const waiter = (frame: string): void => {
+          clearTimeout(timer);
+          resolve(frame);
+        };
+        // Dropped from the queue before rejecting, or the next frame is handed to
+        // this dead promise and discarded, and every later `next()` waits one
+        // frame behind. Only shows up after a timeout, which is when the test is
+        // already trying to explain itself.
+        const timer = setTimeout(() => {
+          const at = waiting.indexOf(waiter);
+          if (at !== -1) waiting.splice(at, 1);
+          reject(new Error('no frame arrived'));
+        }, 2000);
+        waiting.push(waiter);
+      }),
+    send: (event, data) => socket.send(JSON.stringify({ event, data })),
+    close: () => socket.close(),
+    received,
+  };
+};

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

@@ -7,7 +7,14 @@ import {
   Post,
   type Input,
 } from '@dunx/http';
-import { PAGINATION, type Page } from '@dunx/infra/pagination';
+import {
+  decodeCursor,
+  encodeCursor,
+  PAGINATION,
+  pageOf,
+  parsePageOptions,
+  type Page,
+} from '@dunx/infra/pagination';
 import { z } from 'zod';
 import { Ledger } from './ledger.service.js';
 import type { Entry } from './schema.js';
@@ -69,6 +76,18 @@ const pageQuery = z
   });
 
 const pagedEntries = { query: pageQuery } as const;
+const keyset = {
+  query: z.object({
+    take: z.coerce
+      .number()
+      .int()
+      .min(PAGINATION.MIN_TAKE)
+      .max(PAGINATION.MAX_TAKE)
+      .optional(),
+    cursor: z.string().max(PAGINATION.MAX_CURSOR).optional(),
+  }),
+} as const;
+
 const oneEntry = { params: EntryIndex } as const;
 const createEntry = { body: CreateEntry } as const;
 const transfer = { body: Transfer } as const;
@@ -78,12 +97,12 @@ export class LedgerController {
   constructor(private readonly ledger: Ledger) {}
 
   @Get('/', listEntries)
-  list(input: Input<typeof listEntries>): {
+  list({ query }: Input<typeof listEntries>): {
     entries: readonly Entry[];
     balance: number;
   } {
     return {
-      entries: this.ledger.list(input.query.limit),
+      entries: this.ledger.list(query.limit),
       balance: this.ledger.balance(),
     };
   }
@@ -91,34 +110,34 @@ export class LedgerController {
   /** Walked by cursor. Declared before `/:id` for readability only: `Bun.serve`
    * matches a static segment ahead of a parameter. */
   @Get('/page', pagedEntries)
-  page(input: Input<typeof pagedEntries>): Page<Entry> {
-    return this.ledger.page(input.query);
+  page({ query }: Input<typeof pagedEntries>): Page<Entry> {
+    return this.ledger.page(query);
   }
 
   @Get('/:id', oneEntry)
-  one(input: Input<typeof oneEntry>): Entry {
-    const entry = this.ledger.find(input.params.id);
+  one({ params }: Input<typeof oneEntry>): Entry {
+    const entry = this.ledger.find(params.id);
     if (entry === undefined) {
       throw new HttpError(
         HttpStatusCode.NOT_FOUND,
-        `No ledger entry ${input.params.id}`,
+        `No ledger entry ${params.id}`,
       );
     }
     return entry;
   }
 
   @Post('/', createEntry)
-  create(input: Input<typeof createEntry>): Entry {
-    return this.ledger.add(input.body.memo, input.body.amount);
+  create({ body }: Input<typeof createEntry>): Entry {
+    return this.ledger.add(body.memo, body.amount);
   }
 
   /** `"fail": true` throws between the two inserts; the 409's unchanged `rows`
    * is proof the first leg rolled back. */
   @Post('/transfer', transfer)
-  async transfer(
-    input: Input<typeof transfer>,
-  ): Promise<{ balance: number; rows: number }> {
-    const { from, to, amount, fail } = input.body;
+  async transfer({
+    body,
+  }: Input<typeof transfer>): Promise<{ balance: number; rows: number }> {
+    const { from, to, amount, fail } = body;
     try {
       const balance = await this.ledger.transfer(from, to, amount, fail);
       return { balance, rows: this.ledger.rows() };
@@ -136,11 +155,11 @@ export class LedgerController {
    * what allows it - `transactionSync` will not compile against the async handle.
    */
   @Post('/transfer-sync', transfer)
-  transferSync(input: Input<typeof transfer>): {
+  transferSync({ body }: Input<typeof transfer>): {
     balance: number;
     rows: number;
   } {
-    const { from, to, amount, fail } = input.body;
+    const { from, to, amount, fail } = body;
     try {
       const balance = this.ledger.transferSync(from, to, amount, fail);
       return { balance, rows: this.ledger.rows() };
@@ -152,13 +171,69 @@ export class LedgerController {
     }
   }
 
+  /**
+   * Keyset pagination without the service: `parsePageOptions` reads the query the
+   * way the module's own docs suggest a schema does, `pageOf` shapes the envelope
+   * from rows the caller already has, and a cursor round-trips through
+   * `encodeCursor`/`decodeCursor`.
+   *
+   * The cursor is opaque on purpose and every malformed one collapses to the same
+   * `CursorError`, so `?cursor=not-a-cursor` answers 400 rather than telling the
+   * caller which layer rejected it.
+   */
+  @Get('/keyset', keyset)
+  keyset({ query }: Input<typeof keyset>): {
+    options: { take: number; direction: string; order: string };
+    page: Page<Entry>;
+    roundTrip: { encoded: string; decoded: { s: string; i: string } } | null;
+  } {
+    // Throws PageOptionsError on a take outside the range, which the framework
+    // renders as a 400 because the class carries the status.
+    const options = parsePageOptions(query as Record<string, unknown>);
+    // A cursor handed back in is decoded first, which is where a hand-written one
+    // fails, and it is what the next page is keyed from.
+    const roundTrip =
+      query.cursor === undefined
+        ? null
+        : { encoded: query.cursor, decoded: decodeCursor(query.cursor) };
+
+    const cursorOf = (row: Entry): string =>
+      // No timestamp on this table, so the id is both sort value and tiebreak.
+      encodeCursor(row.id, String(row.id));
+
+    // Descending ids, so the page after a cursor is everything below it. One row
+    // more than asked for is what answers `hasNextPage` without a second count.
+    const after = roundTrip === null ? undefined : Number(roundTrip.decoded.i);
+    const scanned = this.ledger
+      .list(PAGINATION.MAX_TAKE)
+      .filter((row) => after === undefined || row.id < after);
+    const rows = scanned.slice(0, options.take);
+
+    const page = pageOf(rows, {
+      take: options.take,
+      hasNextPage: scanned.length > options.take,
+      hasPreviousPage: after !== undefined,
+      cursorOf,
+    });
+
+    return {
+      options: {
+        take: options.take,
+        direction: options.direction,
+        order: options.order,
+      },
+      page,
+      roundTrip,
+    };
+  }
+
   @Delete('/:id', oneEntry)
-  remove(input: Input<typeof oneEntry>): { deleted: boolean } {
-    const deleted = this.ledger.remove(input.params.id);
+  remove({ params }: Input<typeof oneEntry>): { deleted: boolean } {
+    const deleted = this.ledger.remove(params.id);
     if (!deleted) {
       throw new HttpError(
         HttpStatusCode.NOT_FOUND,
-        `No ledger entry ${input.params.id}`,
+        `No ledger entry ${params.id}`,
       );
     }
     return { deleted };

package/templates/features/guards/reports.controller.ts

@@ -55,15 +55,15 @@ export class ReportsController {
   // Method-scoped guard, reading the class-level @Roles('admin').
   @UseGuards(RolesGuard)
   @Post('/', createReport)
-  create(input: Input<typeof createReport>): readonly string[] {
-    return this.reports.add(input.body.title);
+  create({ body }: Input<typeof createReport>): readonly string[] {
+    return this.reports.add(body.title);
   }
 
   // A method-level @Roles wins over the class-level one.
   @Roles('editor')
   @UseGuards(RolesGuard)
   @Patch('/:id', renameReport)
-  rename(input: Input<typeof renameReport>): readonly string[] {
-    return this.reports.rename(input.params.id, input.body.title);
+  rename({ body, params }: Input<typeof renameReport>): readonly string[] {
+    return this.reports.rename(params.id, body.title);
   }
 }

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

@@ -1,9 +1,26 @@
 import type { BunRequest } from 'bun';
 import type { Middleware, Next, RouteContext } from '@dunx/http';
 
-/** The observable side effect: whatever the middleware saw is readable after. */
+/**
+ * The observable side effect: whatever the middleware saw is readable after.
+ *
+ * Capped, because this grows by one entry on **every request** and this folder is
+ * vendored into `@dunx/create-app`'s `http` feature. Unbounded it put 46 MiB on
+ * the heap across 3.1 million requests in the soak run and read as a framework
+ * leak until a heap census named the strings. A demo that keeps the last few
+ * hundred shows the same thing and survives production traffic.
+ */
+const KEEP = 500;
+
 export class RequestTrail {
   readonly entries: string[] = [];
+
+  record(entry: string): void {
+    this.entries.push(entry);
+    if (this.entries.length > KEEP) {
+      this.entries.splice(0, this.entries.length - KEEP);
+    }
+  }
 }
 
 /**
@@ -23,7 +40,7 @@ export class RequestTrailMiddleware implements Middleware {
     next: Next,
   ): Promise<Response> {
     const response = await next();
-    this.trail.entries.push(
+    this.trail.record(
       `${req.method} ${new URL(req.url).pathname} -> ${response.status} ` +
         `(${ctx.controller}.${ctx.handler})`,
     );

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

@@ -14,7 +14,7 @@ export class TraceController {
   constructor(private readonly context: RequestContext) {}
 
   @Get('/')
-  current(input: Input<RouteSchemas>): {
+  current({ req }: Input<RouteSchemas>): {
     traceId: string | undefined;
     spanId: string | undefined;
     parentSpanId: string | undefined;
@@ -28,7 +28,7 @@ export class TraceController {
       spanId: spanId as string | undefined,
       parentSpanId: parentSpanId as string | undefined,
       traceFlags: traceFlags as string | undefined,
-      inbound: input.req.headers.get('traceparent'),
+      inbound: req.headers.get('traceparent'),
     };
   }
 }

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

@@ -33,11 +33,13 @@ export class JobsController {
   constructor(private readonly publisher: JobPublisher) {}
 
   @Post('/thumbnails', enqueue)
-  async enqueue(
-    input: Input<typeof enqueue>,
-  ): Promise<{ id: string; queue: string; state: string }> {
+  async enqueue({ body }: Input<typeof enqueue>): Promise<{
+    id: string;
+    queue: string;
+    state: string;
+  }> {
     const job = await this.degrades(() =>
-      this.publisher.publish(THUMBNAIL_QUEUE, 'render', input.body),
+      this.publisher.publish(THUMBNAIL_QUEUE, 'render', body),
     );
 
     return {
@@ -50,24 +52,24 @@ export class JobsController {
   /** `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<{
+  async status({ params }: Input<typeof oneJob>): Promise<{
     id: string;
     state: string;
     result: RenderResult | null;
     failedReason: string | null;
   }> {
     const job = await this.degrades(() =>
-      this.publisher.queue(THUMBNAIL_QUEUE).getJob(input.params.id),
+      this.publisher.queue(THUMBNAIL_QUEUE).getJob(params.id),
     );
     if (job === undefined) {
       throw new HttpError(
         HttpStatusCode.NOT_FOUND,
-        `No job ${input.params.id} on "${THUMBNAIL_QUEUE}"`,
+        `No job ${params.id} on "${THUMBNAIL_QUEUE}"`,
       );
     }
 
     return {
-      id: job.id ?? input.params.id,
+      id: job.id ?? params.id,
       state: await job.getState(),
       result: (job.returnvalue as RenderResult | null) ?? null,
       failedReason: job.failedReason ?? null,

package/templates/features/notes/notes.controller.ts

@@ -46,7 +46,10 @@ export class NotesController {
     return this.notes.rows();
   }
 
-  // No schemas declared, so the request is all `input` carries.
+  // Destructuring at the parameter is the usual shape, and it is what every other
+  // handler here does. The whole object has a name when a handler wants to pass it
+  // on: `whoami(input: Input<RouteSchemas>)` types the same. No schemas are
+  // declared on this route, so `req` is all it carries.
   @ApiDoc({
     summary: 'Echo the caller’s address',
     description:
@@ -54,12 +57,12 @@ export class NotesController {
     deprecated: true,
   })
   @Get('/whoami')
-  whoami(input: Input<RouteSchemas>): { ip: string | undefined } {
-    return { ip: this.address.of(input.req) };
+  whoami({ req }: Input<RouteSchemas>): { ip: string | undefined } {
+    return { ip: this.address.of(req) };
   }
 
   @Post('/', createNote)
-  create(input: Input<typeof createNote>): readonly string[] {
-    return this.notes.add(input.body.text);
+  create({ body }: Input<typeof createNote>): readonly string[] {
+    return this.notes.add(body.text);
   }
 }

package/templates/features/notes/notes.service.ts

@@ -1,6 +1,17 @@
 import { Logger } from '@dunx/core';
 import type { OnInit } from '@dunx/core';
 
+/**
+ * The list is capped, and the cap is the point.
+ *
+ * An in-memory demo store that only ever grows is a leak the moment anyone runs
+ * real traffic through it, and this folder is vendored into `@dunx/create-app`'s
+ * `notes` feature, so an unbounded array would ship into every scaffold. The soak
+ * run found it: 42,000 posts a minute put 250,000 retained strings on the heap and
+ * read as a framework leak until the census named them.
+ */
+const KEEP = 200;
+
 export class NotesService implements OnInit {
   readonly #rows = ['read the architecture doc', 'measure before deciding'];
 
@@ -16,6 +27,9 @@ export class NotesService implements OnInit {
 
   add(text: string): readonly string[] {
     this.#rows.push(text);
+    if (this.#rows.length > KEEP) {
+      this.#rows.splice(0, this.#rows.length - KEEP);
+    }
     return this.#rows;
   }
 }

package/templates/features/pictures/images.controller.ts

@@ -33,8 +33,8 @@ export class ImagesController {
 
   /** Returns the encoded image itself, so a browser renders it inline. */
   @Get('/render', render)
-  async render(input: Input<typeof render>): Promise<Response> {
-    const encoded = await this.thumbnails.render(input.query);
+  async render({ query }: Input<typeof render>): Promise<Response> {
+    const encoded = await this.thumbnails.render(query);
     return new Response(encoded.bytes, {
       headers: {
         'content-type': encoded.mimeType,
@@ -45,14 +45,14 @@ export class ImagesController {
 
   /** The same render, described rather than returned - easier to read in swagger. */
   @Get('/metadata', render)
-  async metadata(input: Input<typeof render>): Promise<{
+  async metadata({ query }: Input<typeof render>): Promise<{
     width: number;
     height: number;
     format: string;
     mimeType: string;
     bytes: number;
   }> {
-    const encoded = await this.thumbnails.render(input.query);
+    const encoded = await this.thumbnails.render(query);
     return {
       width: encoded.width,
       height: encoded.height,
@@ -67,11 +67,11 @@ export class ImagesController {
    * is a header read rather than a decode, so a truncated file still answers.
    */
   @Post('/describe', describe)
-  describe(input: Input<typeof describe>): Promise<{
+  describe({ body }: Input<typeof describe>): Promise<{
     width: number;
     height: number;
     format: string;
   }> {
-    return this.thumbnails.describe(input.body.base64);
+    return this.thumbnails.describe(body.base64);
   }
 }

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

@@ -1,5 +1,5 @@
-import { Counter, Logger } from '@dunx/core';
-import { Cron, Interval, OnceOnBoot } from '@dunx/infra/schedule';
+import { Counter, Gauge, Logger } from '@dunx/core';
+import { Cron, Interval, OnceOnBoot, Overlap } from '@dunx/infra/schedule';
 
 /**
  * The three schedule decorators on one class, discovered off the prototype chain
@@ -43,6 +43,44 @@ export class Maintenance {
     return this.#compactions.value;
   }
 
+  readonly #slow = new Counter();
+  /**
+   * A `Gauge`, not `#inFlight += 1`. A compound assignment to a private field in
+   * a class that also has a decorated member is a `SyntaxError` in Bun's parser,
+   * still on 1.4.2 - which is what the note at the top of this class is about,
+   * and which this method walked straight into before it was written this way.
+   */
+  readonly #inFlight = new Gauge();
+  readonly #peak = new Gauge();
+
+  /**
+   * `overlap: Overlap.CONCURRENT`, which is the half `skip` hides.
+   *
+   * The default refuses to start a run while the last one is still going, so a
+   * handler that outlives its own cadence quietly runs at the rate it can finish.
+   * `concurrent` starts anyway, and `maxInFlight` is how you can tell: triggered
+   * twice inside its own sleep it reaches 2, where the sweep above stays at 1.
+   */
+  @Interval(600_000, {
+    name: 'maintenance.overlapping',
+    overlap: Overlap.CONCURRENT,
+  })
+  async overlappingWork(): Promise<number> {
+    this.#inFlight.inc();
+    this.#peak.set(Math.max(this.#peak.value, this.#inFlight.value));
+    try {
+      await Bun.sleep(40);
+      this.#slow.inc();
+      return this.#slow.value;
+    } finally {
+      this.#inFlight.dec();
+    }
+  }
+
+  get overlapping(): { runs: number; maxInFlight: number } {
+    return { runs: this.#slow.value, maxInFlight: this.#peak.value };
+  }
+
   get counts(): { sweeps: number; compactions: number; warmed: boolean } {
     return {
       sweeps: this.#sweeps.value,

package/templates/features/schedule/schedule.demo.ts

@@ -41,6 +41,18 @@ export class ScheduleDemo {
         'neither waited for a clock',
     );
 
+    // Two triggers inside one run's own sleep. `concurrent` lets the second start,
+    // so both are in flight at once; the default would have skipped it.
+    await Promise.all([
+      this.registry.trigger('maintenance.overlapping'),
+      this.registry.trigger('maintenance.overlapping'),
+    ]);
+    const overlapping = this.maintenance.overlapping;
+    this.logger.info(
+      `overlap: concurrent -> ${overlapping.runs} runs, ` +
+        `${overlapping.maxInFlight} in flight at once (skip would hold it at 1)`,
+    );
+
     const entry = this.registry.get('maintenance.compact');
     this.logger.info(
       `runs recorded on the entry -> ${entry?.runs ?? 0}, lastError ` +

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

@@ -40,13 +40,14 @@ export class FilesController {
   constructor(private readonly storage: Storage) {}
 
   @Get('/', listFiles)
-  async list(
-    input: Input<typeof listFiles>,
-  ): Promise<{ root: string; keys: readonly string[] }> {
+  async list({ query }: Input<typeof listFiles>): Promise<{
+    root: string;
+    keys: readonly string[];
+  }> {
     const keys: string[] = [];
     for await (const entry of this.storage.list({
-      prefix: input.query.prefix,
-      glob: input.query.glob,
+      prefix: query.prefix,
+      glob: query.glob,
     })) {
       keys.push(entry.key);
     }
@@ -57,10 +58,13 @@ export class FilesController {
   }
 
   @Get('/object', objectKey)
-  async read(
-    input: Input<typeof objectKey>,
-  ): Promise<{ key: string; size: number; type: string; content: string }> {
-    const { key } = input.query;
+  async read({ query }: Input<typeof objectKey>): Promise<{
+    key: string;
+    size: number;
+    type: string;
+    content: string;
+  }> {
+    const { key } = query;
     await this.present(key);
     const stat = await this.storage.stat(key);
     return {
@@ -72,12 +76,13 @@ export class FilesController {
   }
 
   @Put('/object', writeFile)
-  async write(
-    input: Input<typeof writeFile>,
-  ): Promise<{ key: string; bytes: number }> {
-    const { key } = input.query;
+  async write({
+    body,
+    query,
+  }: Input<typeof writeFile>): Promise<{ key: string; bytes: number }> {
+    const { key } = query;
     try {
-      return { key, bytes: await this.storage.write(key, input.body.content) };
+      return { key, bytes: await this.storage.write(key, body.content) };
     } catch (error) {
       if (!(error instanceof PathTraversalError)) throw error;
       throw new HttpError(HttpStatusCode.BAD_REQUEST, error.message);
@@ -85,8 +90,10 @@ export class FilesController {
   }
 
   @Delete('/object', objectKey)
-  async remove(input: Input<typeof objectKey>): Promise<{ deleted: boolean }> {
-    const { key } = input.query;
+  async remove({
+    query,
+  }: Input<typeof objectKey>): Promise<{ deleted: boolean }> {
+    const { key } = query;
     await this.present(key);
     await this.storage.delete(key);
     return { deleted: true };
@@ -95,8 +102,8 @@ export class FilesController {
   /** 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;
+  async presign({ query }: Input<typeof objectKey>): Promise<{ url: string }> {
+    const { key } = query;
     await this.present(key);
     try {
       return { url: this.storage.presign(key) };

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

@@ -24,21 +24,18 @@ export class UsersController {
   // 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);
+  list({ query }: Input<typeof listUsers>): Promise<readonly User[]> {
+    return this.users.findAll(query.limit, 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> {
+  async one({ params }: Input<typeof oneUser>): Promise<User> {
     // Already a number: the params schema coerced it before this ran.
-    const user = await this.users.find(input.params.id);
+    const user = await this.users.find(params.id);
     if (user === null) {
-      throw new HttpError(
-        HttpStatusCode.NOT_FOUND,
-        `No user ${input.params.id}`,
-      );
+      throw new HttpError(HttpStatusCode.NOT_FOUND, `No user ${params.id}`);
     }
     return user;
   }
@@ -46,10 +43,10 @@ export class UsersController {
   // No req.json(), no Response.json(), no status - the body arrives validated and
   // typed, and 201 is the POST default.
   @Post('/', createUser)
-  create(input: Input<typeof createUser>): Promise<User> {
+  create({ body }: Input<typeof createUser>): Promise<User> {
     return this.users.create(
-      input.body.name,
-      input.body.tags.map((tag) => tag.label),
+      body.name,
+      body.tags.map((tag) => tag.label),
     );
   }
 }