@zerotal/core 1.0.3 → 1.1.0

package/CHANGELOG.md

@@ -1,4 +1,4 @@
-# Changelog — @zerotal/core
+# Changelog — @zerotal/core
 
 All notable changes to this package are documented here. The format is
 based on [Keep a Changelog](https://keepachangelog.com/); this package
@@ -8,6 +8,19 @@ follows the Zerotal monorepo's unified versioning.
 
 ## [Unreleased]
 
+## [1.1.0] — 2026-08-08
+
+### Fixed
+
+- **`bun zt test` no longer fails a cold suite on Bun's 5-second hook timeout.** A `beforeAll` that calls `createTestApp()` boots providers and runs migrations, which exceeds 5s on a cold start; `bunfig.toml`'s `[test] timeout` does not cover hooks, only the CLI flag does. The failure appeared on the first run and not the second, which reads as flakiness and sends you looking for a race that is not there. The default is now 30s, still overridable with `--timeout`.
+- **`serve --dev` no longer loses its server to a restart race.** The debounce timer spaced out the *scheduling* of a restart, but its callback cleared the timer and then awaited a rebuild that can take seconds — so a change arriving in that window scheduled a second callback which ran concurrently. Both reached the spawn, two servers raced for the port, and the loser died with "Failed to start server. Is port 3000 in use?". Dev mode was then left owning no server while the winner kept serving stale code, so every later save appeared to do nothing. Restarts are now serialized: a request arriving mid-restart queues exactly one follow-up instead of running in parallel. A failed bind also retries briefly, since the OS releases a listening socket asynchronously after the previous owner exits, and the initial spawn uses the same path — an orphan from a previous run is the commonest reason the first bind fails. An unexpected exit is reported against the child that actually exited rather than whichever child the field happened to hold.
+
+### Added
+
+- `ctx.param(name, fallback?)` — the single-value route-parameter accessor, matching `string()` and `header()` in shape. Only the `params` record existed, though every other single-value read on the object is a method. Unlike `string()` it does not fall back to the query string: a route parameter either matched or it did not.
+- `URLSigner` is exported from `@zerotal/core/security`. It carried a full documented example but was reachable only through a deep internal path, which is a worse dependency to take than reimplementing it. (`Url` / `url` were already exported — from the **http** subpath, not security; the docblock now says so.)
+- `app.assets.loader` — per-extension bundler loader overrides, e.g. `{ ".woff2": "file" }`. Bun inlines small `url()` assets as data URIs, which is right for an icon and wrong for a font: the bytes move into the render-blocking stylesheet, so nine woff2 subsets turned a 36 KB stylesheet into 260 KB that had to download before first paint. There was no configuration to turn it off.
+
 ## [1.0.3] — 2026-08-07
 
 ### Changed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zerotal/core",
-  "version": "1.0.3",
+  "version": "1.1.0",
   "license": "MIT",
   "maturity": "stable",
   "private": false,

package/src/command/builtin/TestCommand.ts

@@ -28,6 +28,15 @@ export class TestCommand extends Command {
   static description = "Run the test suite in test environment";
   static needsApp = false;
 
+  /**
+   * Default per-test and per-hook timeout, in milliseconds.
+   *
+   * Generous on purpose: the expensive thing in a Zerotal suite is booting the app in a
+   * `beforeAll`, which Bun's 5s default does not allow for. Raising it costs nothing on a
+   * passing suite and removes a failure mode that looks exactly like flakiness.
+   */
+  static readonly DEFAULT_TIMEOUT_MS = 30_000;
+
   static override args = [{ name: "pattern", required: false, default: "" }];
 
   static override flags = [
@@ -47,7 +56,7 @@ export class TestCommand extends Command {
     {
       name: "timeout",
       type: "number" as const,
-      description: "Per-test timeout in milliseconds",
+      description: `Per-test and per-hook timeout in milliseconds (default ${TestCommand.DEFAULT_TIMEOUT_MS})`,
       default: 0,
     },
     {
@@ -103,8 +112,14 @@ export class TestCommand extends Command {
     if (this.flags["watch"]) bunArguments.push("--watch");
     if (this.flags["bail"]) bunArguments.push("--bail");
 
-    const timeout = this.flags["timeout"] as number | undefined;
-    if (timeout && timeout > 0) bunArguments.push(`--timeout=${timeout}`);
+    // Bun's default is 5s and applies to hooks as well as tests — and `bunfig.toml`'s
+    // `[test] timeout` does not cover hooks, only this flag does. A `beforeAll` that calls
+    // `createTestApp()` boots providers and runs migrations, which on a cold start with a
+    // dozen providers exceeds 5s; the failure lands on the first run and not the second,
+    // so it reads as a flaky test and sends you hunting for a race that is not there.
+    // A framework's own test runner should account for that framework's boot cost.
+    const timeout = (this.flags["timeout"] as number | undefined) || TestCommand.DEFAULT_TIMEOUT_MS;
+    bunArguments.push(`--timeout=${timeout}`);
 
     this.dim(`APP_ENV=test  ZT_DB_URL=${dbUrl}`);
     this.dim(`bun ${bunArguments.join(" ")}\n`);

package/src/config/AppConfig.ts

@@ -66,8 +66,29 @@ export interface AppAssetsConfig {
   prefix: string;
   /** Minify output. Default: true in production, false otherwise. */
   minify: boolean;
+  /**
+   * Per-extension loader overrides handed to Bun's bundler, e.g.
+   * `{ ".woff2": "file" }`.
+   *
+   * Bun inlines small files a stylesheet `url()`s as data URIs. That is the right
+   * default for an icon, and the wrong one for a font: the bytes move into the
+   * render-blocking stylesheet, so nine woff2 subsets can turn a 36KB stylesheet into
+   * 260KB that must download before first paint — the opposite of what `font-display:
+   * swap` is for. `{ ".woff2": "file" }` emits them as separate files again.
+   *
+   * @example
+   * // config/app.ts
+   * assets: { entrypoint: 'resources/css/app.css', loader: { '.woff2': 'file', '.woff': 'file' } }
+   */
+  loader?: Record<string, AssetLoaderKind>;
 }
 
+/**
+ * Bun bundler loaders that are meaningful for an asset referenced from CSS/JS.
+ * Mirrors Bun's `Loader` union, minus the source-code loaders a `url()` cannot name.
+ */
+export type AssetLoaderKind = "file" | "dataurl" | "base64" | "text" | "json" | "toml";
+
 /**
  * Default request-body ceiling: 8 MiB.
  *
@@ -214,7 +235,13 @@ export function AppConfig(options: {
   cors?: Partial<AppCorsConfig>;
   throttle?: Partial<AppThrottleConfig>;
   secureHeaders?: Partial<AppSecureHeadersConfig>;
-  assets?: { entrypoint: string | string[]; outDir?: string; prefix?: string; minify?: boolean };
+  assets?: {
+    entrypoint: string | string[];
+    outDir?: string;
+    prefix?: string;
+    minify?: boolean;
+    loader?: Record<string, AssetLoaderKind>;
+  };
   conventions?: { enabled?: boolean; paths?: Partial<ConventionsConfig["paths"]> };
 }): AppConfigShape {
   // Resolve env-derived defaults, then deep-merge the caller's overrides so partial nested
@@ -247,6 +274,9 @@ export function AppConfig(options: {
       outDir: options.assets.outDir ?? "public",
       prefix: options.assets.prefix ?? "/",
       minify: options.assets.minify ?? isProduction,
+      // Only set when declared: an explicit `undefined` is a distinct value under
+      // exactOptionalPropertyTypes, and would override Bun's own defaults with nothing.
+      ...(options.assets.loader ? { loader: options.assets.loader } : {}),
     };
   }
   return resolved;

package/src/config/index.ts

@@ -34,6 +34,7 @@ export type {
   AppTlsConfig,
   ConventionsConfig,
   AppAssetsConfig,
+  AssetLoaderKind,
 } from "./AppConfig.ts";
 export type { ConfigRegistry, ConfigPath, ConfigValue } from "./registry.ts";
 export { ConfigValidationError } from "./validation.ts";

package/src/crypt/URLSigner.ts

@@ -8,11 +8,18 @@ import { safeEqual, hmacHex } from "../support/crypto.ts";
  * the full URL (without the signature param) sorted by key so that the
  * order of other query parameters doesn't matter.
  *
- * For app-key-keyed signing without managing a secret, prefer the {@link Url}
- * facade (`Url.sign` / `Url.verify`), which derives the secret from `APP_KEY`.
+ * For app-key-keyed signing without managing a secret, prefer the `Url` facade
+ * (`Url.sign` / `Url.verify`), which derives the secret from `APP_KEY`. It is exported
+ * from the **http** subpath, not this one:
+ *
+ * ```ts
+ * import { Url } from "zerotal/http";       // or "@zerotal/core/http"
+ * ```
  *
  * @example
  * ```ts
+ * import { URLSigner } from "zerotal/security";  // or "@zerotal/core/security"
+ *
  * const signer = new URLSigner(process.env.APP_KEY!);
  *
  * // Generate a link that expires in 15 minutes:

package/src/dev/CssPlugins.ts

@@ -45,6 +45,7 @@ export async function buildCssBundle(
   input: string,
   outdir: string,
   minify = false,
+  loader?: Record<string, string>,
 ): Promise<{ success: boolean; logs: unknown[] }> {
   const cwd = process.cwd();
   const plugins = await detectCssPlugins(cwd);
@@ -57,6 +58,9 @@ export async function buildCssBundle(
       target: "browser",
       minify,
       plugins,
+      ...(loader
+        ? { loader: loader as NonNullable<Parameters<typeof Bun.build>[0]["loader"]> }
+        : {}),
     });
   }
 
@@ -135,6 +139,8 @@ export interface AssetBuildConfig {
   outDir: string;
   prefix: string;
   minify: boolean;
+  /** Per-extension loader overrides (e.g. `{ ".woff2": "file" }`). See AppAssetsConfig. */
+  loader?: Record<string, string>;
 }
 
 /**
@@ -174,6 +180,11 @@ export async function buildConfiguredAssets(
       sourcemap: assets.minify ? "none" : "external",
       minify: assets.minify,
       plugins,
+      // `app.assets.loader` — e.g. `{ ".woff2": "file" }` to stop fonts being inlined
+      // as data URIs into the render-blocking stylesheet.
+      ...(assets.loader
+        ? { loader: assets.loader as NonNullable<Parameters<typeof Bun.build>[0]["loader"]> }
+        : {}),
     });
 
     if (result.success) await pruneBuildOutput(outdir, result.outputs);

package/src/dev/DevOrchestrator.ts

@@ -45,6 +45,27 @@ export class DevOrchestrator {
   private _child: ReturnType<typeof Bun.spawn> | null = null;
   private _restartTimer: ReturnType<typeof setTimeout> | null = null;
   private _buildTimer: ReturnType<typeof setTimeout> | null = null;
+  /**
+   * Serializes restarts. The debounce timer only spaces out the *scheduling* of a
+   * restart — once its callback starts it clears the timer and then awaits a rebuild
+   * that can take seconds, during which another change schedules a second callback.
+   * Both then reached `_spawnServer()`, so two servers raced for the port, one lost
+   * with "Failed to start server. Is port 3000 in use?", and the dev server was left
+   * dead while the winner kept serving. A restart requested while one is running now
+   * queues a single follow-up instead of running in parallel.
+   */
+  private _restartInFlight: Promise<void> | null = null;
+  private _restartQueued = false;
+
+  /**
+   * Bounded respawn attempts. The race above is fixed at the source, but a port can
+   * still be briefly unavailable after the previous owner exits — the OS releases the
+   * listening socket asynchronously — so a lost bind retries rather than killing dev mode.
+   */
+  private static readonly RESPAWN_ATTEMPTS = 3;
+  private static readonly RESPAWN_DELAY_MS = 300;
+  /** A server that binds stays up; one that loses the port exits almost immediately. */
+  private static readonly BIND_SETTLE_MS = 400;
   /** Per-build asset-version token — bumped on each build, busts `asset()` `?v=` URLs. */
   private _assetVersion = Date.now().toString(36);
 
@@ -61,7 +82,9 @@ export class DevOrchestrator {
       console.warn("  [zerotal:dev] ⚠  initial build failed — starting server anyway");
     }
 
-    this._spawnServer();
+    // Same retry as a restart: the commonest reason the first bind fails is an orphaned
+    // server from a previous run that has not finished exiting.
+    await this._spawnServerWithRetry();
     this._watch();
 
     // Park the process — cleanup happens in signal handlers registered by _watch()
@@ -70,8 +93,8 @@ export class DevOrchestrator {
 
   // ── Server management ──────────────────────────────────────────────────────
 
-  private _spawnServer(): void {
-    this._child = Bun.spawn(
+  private _spawnServer(): ReturnType<typeof Bun.spawn> {
+    const child = Bun.spawn(
       ["bun", Bun.main, "serve", "--port", String(this._port), "--dev-worker"],
       {
         stdin: "pipe",
@@ -91,40 +114,122 @@ export class DevOrchestrator {
       },
     );
 
-    this._child.exited.then((code) => {
-      // Ignore expected exits (restart in progress or clean shutdown)
-      if (this._child && this._restartTimer === null && code !== 0) {
+    this._child = child;
+
+    void child.exited.then((code) => {
+      // Report only the *current* server dying unexpectedly. Comparing against
+      // `this._child` identity matters: reading the field alone reported an exit that a
+      // restart had deliberately caused, because by then the field held the replacement.
+      // A restart in flight owns its own reporting.
+      if (this._child === child && this._restartInFlight === null && code !== 0) {
         console.log(`  [zerotal:dev] server exited with code ${code}`);
       }
     });
+
+    return child;
   }
 
   private _scheduleRestart(): void {
     if (this._restartTimer) clearTimeout(this._restartTimer);
-    this._restartTimer = setTimeout(async () => {
+    this._restartTimer = setTimeout(() => {
       this._restartTimer = null;
-      console.log("  [zerotal:dev] ↻  backend change — rebuilding + restarting server...");
+      void this._requestRestart();
+    }, 150);
+  }
 
-      // Rebuild assets before respawning: server-rendered views (Flow pages in `app/`,
-      // controllers returning markup) contain Tailwind classes the stylesheet scans via
-      // `@source`, so a backend edit can introduce new classes. Without this, a new utility
-      // used in a page wouldn't appear until an unrelated `resources/` file changed. The
-      // fresh `_assetVersion` (bumped by _runBuild) is passed to the respawned worker, so the
-      // browser refetches the updated CSS.
-      await this._runBuild();
+  /**
+   * Run a restart, or fold this request into the one already running.
+   *
+   * Restarts must not overlap: each one kills the current server and binds a new one to
+   * the same port, so two in flight means two servers competing for it. A request that
+   * arrives mid-restart sets a flag instead, and exactly one more restart runs when the
+   * current one finishes — enough to pick up whatever changed, without a queue that
+   * grows one entry per keystroke.
+   */
+  private _requestRestart(): Promise<void> {
+    if (this._restartInFlight) {
+      this._restartQueued = true;
+      return this._restartInFlight;
+    }
 
-      const previousChild = this._child;
-      this._child = null;
+    const run = async (): Promise<void> => {
+      try {
+        do {
+          this._restartQueued = false;
+          await this._restartOnce();
+        } while (this._restartQueued);
+      } finally {
+        this._restartInFlight = null;
+      }
+    };
+
+    this._restartInFlight = run();
+    return this._restartInFlight;
+  }
 
-      if (previousChild) {
-        previousChild.kill("SIGTERM");
-        const forceKill = setTimeout(() => previousChild.kill("SIGKILL"), 1_500);
-        await previousChild.exited;
-        clearTimeout(forceKill);
+  private async _restartOnce(): Promise<void> {
+    console.log("  [zerotal:dev] ↻  backend change — rebuilding + restarting server...");
+
+    // Rebuild assets before respawning: server-rendered views (Flow pages in `app/`,
+    // controllers returning markup) contain Tailwind classes the stylesheet scans via
+    // `@source`, so a backend edit can introduce new classes. Without this, a new utility
+    // used in a page wouldn't appear until an unrelated `resources/` file changed. The
+    // fresh `_assetVersion` (bumped by _runBuild) is passed to the respawned worker, so the
+    // browser refetches the updated CSS.
+    await this._runBuild();
+
+    // Stop before spawning, always: the old server owns the port until it exits.
+    await this._stopChild();
+    await this._spawnServerWithRetry();
+  }
+
+  /** Stop the running server and wait for it to actually exit, releasing the port. */
+  private async _stopChild(): Promise<void> {
+    const child = this._child;
+    this._child = null;
+    if (!child) return;
+
+    child.kill("SIGTERM");
+    const forceKill = setTimeout(() => child.kill("SIGKILL"), 1_500);
+    try {
+      await child.exited;
+    } finally {
+      clearTimeout(forceKill);
+    }
+  }
+
+  /**
+   * Spawn the server, retrying briefly if it dies on startup.
+   *
+   * A bind failure is indistinguishable from an application crash by exit code alone, so
+   * this retries either — a crash simply fails the remaining attempts quickly and reports.
+   * Leaving dev mode with no server and no explanation is the worse outcome: the watcher
+   * stays alive, so the next save appears to do nothing while the browser talks to
+   * whatever is still listening.
+   */
+  private async _spawnServerWithRetry(): Promise<void> {
+    for (let attempt = 1; attempt <= DevOrchestrator.RESPAWN_ATTEMPTS; attempt++) {
+      const child = this._spawnServer();
+
+      const settled = await Promise.race([
+        child.exited.then(() => true),
+        Bun.sleep(DevOrchestrator.BIND_SETTLE_MS).then(() => false),
+      ]);
+
+      if (!settled) return; // still running → it bound the port
+      if (this._child !== child) return; // superseded by a newer restart
+
+      this._child = null;
+      if (attempt < DevOrchestrator.RESPAWN_ATTEMPTS) {
+        await Bun.sleep(DevOrchestrator.RESPAWN_DELAY_MS);
       }
+    }
 
-      this._spawnServer();
-    }, 150);
+    console.error(
+      `  [zerotal:dev] ✗  server did not start after ${DevOrchestrator.RESPAWN_ATTEMPTS} attempts.\n` +
+        `     Port ${this._port} may be held by another process — the error above says which.\n` +
+        `     Dev mode is still watching; fix the cause and save to retry.`,
+    );
   }
 
   // ── Build management ───────────────────────────────────────────────────────

package/src/pipeline/HttpContext.ts

@@ -550,6 +550,29 @@ export class HttpContext<TParams extends Record<string, unknown> = Record<string
     return (this.params[key] as string | undefined) ?? this.url.searchParams.get(key) ?? fallback;
   }
 
+  /**
+   * Read a single route parameter.
+   *
+   * `params` is the whole record; this is the one-value accessor that matches
+   * {@link HttpContext.string} and {@link HttpContext.header} in shape. Every other
+   * single-value read on this object is a method, so reaching for `param('token')` and
+   * finding only `params['token']` is a needless inconsistency — even caught at compile
+   * time, it is one more thing to remember for no benefit.
+   *
+   * Unlike {@link HttpContext.string} this does **not** fall back to the query string: a
+   * route parameter either matched or it did not, and quietly answering with a
+   * user-supplied query value would let `?id=1` stand in for a path segment.
+   *
+   * @example
+   * const token = ctx.param('token');
+   * const page = ctx.param('page', '1');
+   *
+   * @category Request data
+   */
+  param(key: string, fallback?: string): string | undefined {
+    return (this.params[key] as string | undefined) ?? fallback;
+  }
+
   /**
    * Read a query param or route param coerced to a boolean.
    * Truthy values: `'1'`, `'true'`, `'yes'`, `'on'` (case-insensitive).

package/src/security/index.ts

@@ -20,3 +20,9 @@
 export { Crypt, CryptKeyMissingError, DecryptionError } from "../crypt/Crypt.ts";
 export { Hash } from "../hash/Hash.ts";
 export type { HashAlgorithm } from "../hash/Hash.ts";
+// Signed URLs with a secret you manage yourself. Documented with a full example on the
+// class, but previously reachable only through a deep internal path — which is a worse
+// dependency to take than reimplementing it, so people reimplemented it. For app-key-keyed
+// signing with no secret to manage, `Url.sign` / `Url.verify` on the http subpath is the
+// higher-level option.
+export { URLSigner } from "../crypt/URLSigner.ts";