@zerotal/core 1.3.0 → 1.5.0

package/src/container/Container.ts

@@ -246,7 +246,7 @@ export class Container {
 
     if (!binding) {
       throw new BindingNotFoundError(
-        typeof canonical === "function" ? (canonical as Function).name : String(canonical),
+        typeof canonical === "function" ? canonical.name : String(canonical),
       );
     }
 
@@ -353,7 +353,7 @@ export class Container {
     }
 
     throw new BindingNotFoundError(
-      typeof canonical === "function" ? (canonical as Function).name : String(canonical),
+      typeof canonical === "function" ? canonical.name : String(canonical),
     );
   }
 
@@ -442,7 +442,7 @@ export class Container {
   private _guardCycle(token: unknown, _chain: readonly unknown[]): readonly unknown[] {
     if (_chain.includes(token)) {
       const errorChain = [..._chain, token].map((entry) =>
-        typeof entry === "function" ? (entry as Function).name : String(entry),
+        typeof entry === "function" ? entry.name : String(entry),
       );
       throw new CircularDependencyError(errorChain);
     }

package/src/container/inject.ts

@@ -16,6 +16,7 @@
  */
 
 import type { BindingToken } from "./types.ts";
+import type { ClassRef } from "../support/classRef.ts";
 
 /**
  * Module-level registry: constructor → ordered dependency tokens.
@@ -23,7 +24,7 @@ import type { BindingToken } from "./types.ts";
  * @internal Populated by {@link inject} and read by the container during
  * auto-wiring; not part of the public API.
  */
-export const injectRegistry = new Map<Function, BindingToken[]>();
+export const injectRegistry = new Map<ClassRef, BindingToken[]>();
 
 /**
  * Mark a class for auto-wiring by the container, declaring its constructor
@@ -46,7 +47,7 @@ export function inject(...tokens: BindingToken[]) {
   // assignable from classes with typed constructors — `unknown[]` would fail the
   // constructor-parameter contravariance check at the decoration site.
   return function (
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any — decorator target must accept any class shape
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- decorator target must accept any class shape
     target: new (...args: any[]) => unknown,
     _context: ClassDecoratorContext,
   ): void {

package/src/context/RequestContext.ts

@@ -88,4 +88,64 @@ export class RequestContext {
   static transaction(): TransactionContext | undefined {
     return this.tryGet()?._transaction;
   }
+
+  // ── Per-request memoisation ───────────────────────────────────────────
+
+  /**
+   * Run `factory` at most once per request for a given `key`, and hand every
+   * later caller the same answer.
+   *
+   * The N+1 detector tells you a query ran too many times; the fix is almost
+   * always "ask once per request", and this is that. Outside a request it is a
+   * pass-through — a queue worker or a CLI command has no request to scope to,
+   * and silently sharing a value across jobs would be worse than not caching.
+   *
+   * Two details are the whole point, and both were learned the expensive way by
+   * everyone who hand-rolls this:
+   *
+   * - **The promise is cached, not the resolved value.** Cache after the
+   *   `await` and a `Promise.all` of ten readers all miss, because none of them
+   *   has resolved when the others look. Caching the promise makes the first
+   *   caller's in-flight work the answer for the other nine.
+   * - **A rejected promise is evicted.** Leave it in and one transient failure
+   *   poisons every later read in the same request, including the retry.
+   *
+   * @param key - Unique within the request. Include the arguments: `user:${id}`.
+   * @param factory - Runs on the first call for this key.
+   *
+   * @example
+   * const settings = await RequestContext.remember(
+   *   `household:${id}:settings`,
+   *   () => Settings.query().where("household_id", id).first(),
+   * );
+   */
+  static async remember<T>(key: string, factory: () => Promise<T> | T): Promise<T> {
+    const ctx = this.tryGet();
+    if (!ctx) return factory();
+
+    const cacheKey = `memo:${key}`;
+    const hit = ctx.getInternal<Promise<T>>(cacheKey);
+    if (hit) return hit;
+
+    // Store the promise synchronously, before the first await — that is what
+    // makes concurrent callers share one round trip instead of racing.
+    const pending = (async () => factory())();
+    ctx.setInternal(cacheKey, pending);
+
+    try {
+      return await pending;
+    } catch (error) {
+      ctx.deleteInternal(cacheKey);
+      throw error;
+    }
+  }
+
+  /**
+   * Drop a memoised value so the next {@link remember} recomputes it.
+   *
+   * For the case a write invalidates a read taken earlier in the same request.
+   */
+  static forget(key: string): void {
+    this.tryGet()?.deleteInternal(`memo:${key}`);
+  }
 }

package/src/contracts/session.ts

@@ -24,17 +24,32 @@ export interface SessionContract {
   /**
    * Read the value stored under `key`, or `undefined` if absent.
    *
-   * Returns `unknown` — the caller asserts the stored shape. Higher-level
-   * surfaces (the `Session` facade, `ctx.session` helpers) layer a generic
-   * `<T>` cast on top.
+   * Defaults to `unknown`, so the safe form — read, then narrow — still works
+   * and is still the honest one for anything that came off the wire. The
+   * optional `<T>` is the caller asserting a shape they control, and it lives
+   * here rather than only on the facade because `ctx.session` is typed as this
+   * contract: without it, `ctx.session.get<number>(k)` was a compile error while
+   * `ctx.flashed<T>(k)` on the same object was not.
+   *
+   * Two overloads rather than one defaulted parameter: `T = unknown` would make
+   * the return `T | undefined`, which is *not* the same type as `unknown` at a
+   * call site TypeScript has to resolve an overload against — enough to break
+   * existing `expect(session.get(k))` assertions. The un-parameterised form
+   * therefore keeps its exact original signature.
+   *
+   * @example
+   * const issuedAt = ctx.session.get<number>(SESSION_ISSUED_AT);
+   * const raw = ctx.session.get(SOMETHING_EXTERNAL);   // still exactly `unknown`
    */
   get(key: string): unknown;
+  get<T>(key: string): T | undefined;
 
   /**
    * Read the value under `key` and remove it in one step ("read once").
    * Returns the stored value, or `undefined` if absent.
    */
   pull(key: string): unknown;
+  pull<T>(key: string): T | undefined;
 
   /**
    * Store `value` under `key`, overwriting any existing entry.

package/src/dev/BuildCache.ts

@@ -0,0 +1,312 @@
+/**
+ * Skip a bundle whose inputs have not changed since the last successful build.
+ *
+ * `serve --dev` rebuilds every bundle on boot, including the common case where
+ * the project has not been touched since the last run. Bun's bundler has no
+ * incremental API to drive, so the granularity available is all-or-nothing per
+ * bundle: work out what went in, and if none of it moved, leave the output alone.
+ *
+ * ## What counts as an input
+ *
+ * Two sources, because one is not enough:
+ *
+ *   - **The module graph**, read back from the external sourcemaps the dev build
+ *     already emits. Their `sources` arrays are the real list of files the
+ *     bundler pulled in, lazily-imported chunks included.
+ *   - **Scanned trees**, passed in by the caller. Tailwind v4 discovers utility
+ *     classes by reading `@source` globs across `app/` and `resources/`, and
+ *     none of that appears in any sourcemap — a stylesheet's true input set is
+ *     "the source tree". Stat-only, so it costs ~10 ms for a small app.
+ *
+ * ## Failing safe
+ *
+ * Every uncertainty resolves to *build*. A missing cache file, a corrupt one, an
+ * unreadable input, a Bun upgrade, an output someone deleted — all of them mean
+ * rebuild. The cache is only ever allowed to cause an unnecessary build, never
+ * to skip a necessary one.
+ *
+ * @internal
+ */
+import { mkdir, readdir, stat, writeFile } from "node:fs/promises";
+import { dirname, join, relative, resolve } from "node:path";
+
+/** Where cache entries live, alongside the prune manifests. */
+const CACHE_DIR = ".zerotal/build";
+
+/** Set to `1` to make every build unconditional. */
+const DISABLE_ENV_VAR = "ZT_NO_BUILD_CACHE";
+
+/** What a previous successful build consumed and produced. */
+interface CacheEntry {
+  /** Fingerprint of the build's configuration. */
+  key: string;
+  /** Bun version that produced the output. */
+  bun: string;
+  /** Absolute input path → `"<mtimeMs>:<size>"`. */
+  inputs: Record<string, string>;
+  /** Absolute paths this build wrote. */
+  outputs: string[];
+}
+
+/** The subset of a `Bun.build()` artifact this module reads. */
+export interface BuildArtifactLike {
+  path: string;
+  kind?: string;
+  text?: () => Promise<string>;
+}
+
+/** Everything that should invalidate a cached build when it changes. */
+export interface BuildCacheKey {
+  entrypoints: string[];
+  outdir: string;
+  minify: boolean;
+  /** Per-extension loader overrides. */
+  loader?: Record<string, string> | undefined;
+  /** Plugin identities — a different Tailwind plugin must rebuild. */
+  plugins?: readonly string[] | undefined;
+  /** Anything else the caller considers part of the build's identity. */
+  extra?: Record<string, unknown> | undefined;
+}
+
+/**
+ * A cache entry for one bundle, scoped to one build configuration.
+ *
+ * @example
+ * const cache = BuildCache.for({ entrypoints, outdir, minify });
+ * if (await cache.isFresh()) return { success: true, logs: [] };
+ *
+ * const result = await Bun.build({ entrypoints, outdir, sourcemap: "external" });
+ * if (result.success) {
+ *   await pruneBuildOutput(outdir, result.outputs);
+ *   await cache.record(result.outputs, { scanRoots: [`${cwd}/app`] });
+ * }
+ */
+export class BuildCache {
+  private constructor(
+    private readonly path: string,
+    private readonly key: string,
+    private readonly entrypoints: string[],
+  ) {}
+
+  /** Open the cache for one build configuration. */
+  static for(key: BuildCacheKey, cwd: string = process.cwd()): BuildCache {
+    const outdir = resolve(cwd, key.outdir);
+    const entrypoints = key.entrypoints.map((entry) => resolve(cwd, entry));
+
+    // The identity of the *entry*, so two bundles writing to the same directory
+    // (Flow's CSS and JS both land in `public/`) do not share one record.
+    const identity = JSON.stringify({
+      outdir,
+      entrypoints: [...entrypoints].sort(),
+      minify: key.minify,
+      loader: key.loader ?? null,
+      plugins: key.plugins ? [...key.plugins].sort() : null,
+      extra: key.extra ?? null,
+    });
+
+    const slug = (relative(cwd, outdir) || "out").replace(/[^a-z0-9]+/gi, "-");
+    const hash = Bun.hash(identity).toString(36);
+
+    return new BuildCache(
+      join(cwd, CACHE_DIR, `cache-${slug}-${hash}.json`),
+      Bun.hash(identity).toString(36),
+      entrypoints,
+    );
+  }
+
+  /** Whether the cache is consulted at all. */
+  static get enabled(): boolean {
+    return Bun.env[DISABLE_ENV_VAR] !== "1";
+  }
+
+  /**
+   * Whether the last build's output is still good.
+   *
+   * False whenever anything is uncertain — see the module note on failing safe.
+   */
+  async isFresh(): Promise<boolean> {
+    if (!BuildCache.enabled) return false;
+
+    const entry = await this.#read();
+    if (entry === null) return false;
+
+    // A different build configuration, or a different Bun. Bun's output changes
+    // between versions, and serving a stale bundle after `bun upgrade` is a
+    // memorably bad afternoon.
+    if (entry.key !== this.key) return false;
+    if (entry.bun !== Bun.version) return false;
+
+    // An empty input set would make every future build "fresh" forever.
+    if (Object.keys(entry.inputs).length === 0) return false;
+
+    for (const [path, stamp] of Object.entries(entry.inputs)) {
+      if ((await _stamp(path)) !== stamp) return false;
+    }
+
+    // Cheap, and it means `rm -rf public/` always recovers.
+    for (const path of entry.outputs) {
+      if (!(await Bun.file(path).exists())) return false;
+    }
+
+    return true;
+  }
+
+  /**
+   * Record what a successful build consumed and produced.
+   *
+   * Call only after a build that succeeded. Recording a failed build would
+   * cache the inputs of output that was never written.
+   *
+   * @param outputs     The build's artifacts.
+   * @param options.scanRoots Directories whose whole contents count as inputs
+   *   (Tailwind's `@source` scan). Missing directories are skipped.
+   */
+  async record(
+    outputs: readonly BuildArtifactLike[],
+    options: { scanRoots?: readonly string[] } = {},
+  ): Promise<void> {
+    if (!BuildCache.enabled) return;
+
+    const inputs: Record<string, string> = {};
+
+    // Entry points always count, even when sourcemaps are off.
+    for (const entry of this.entrypoints) {
+      const stamp = await _stamp(entry);
+      if (stamp !== null) inputs[entry] = stamp;
+    }
+
+    for (const path of await _graphInputs(outputs)) {
+      if (inputs[path] === undefined) {
+        const stamp = await _stamp(path);
+        if (stamp !== null) inputs[path] = stamp;
+      }
+    }
+
+    for (const root of options.scanRoots ?? []) {
+      for (const [path, stamp] of Object.entries(await fingerprintTree(root))) {
+        inputs[path] ??= stamp;
+      }
+    }
+
+    await this.#write({
+      key: this.key,
+      bun: Bun.version,
+      inputs,
+      outputs: outputs.map((output) => resolve(output.path)),
+    });
+  }
+
+  /** Forget this entry, forcing the next build to run. */
+  async invalidate(): Promise<void> {
+    try {
+      await writeFile(this.path, "{}");
+    } catch {
+      // Nothing to invalidate is the same outcome as invalidating.
+    }
+  }
+
+  async #read(): Promise<CacheEntry | null> {
+    try {
+      const contents = (await Bun.file(this.path).json()) as unknown;
+      if (typeof contents !== "object" || contents === null) return null;
+
+      const entry = contents as Partial<CacheEntry>;
+      if (typeof entry.key !== "string" || typeof entry.bun !== "string") return null;
+      if (typeof entry.inputs !== "object" || entry.inputs === null) return null;
+      if (!Array.isArray(entry.outputs)) return null;
+
+      return entry as CacheEntry;
+    } catch {
+      // Absent, unreadable, or not JSON — all mean "build".
+      return null;
+    }
+  }
+
+  async #write(entry: CacheEntry): Promise<void> {
+    try {
+      await mkdir(dirname(this.path), { recursive: true });
+      await writeFile(this.path, JSON.stringify(entry, null, 2));
+    } catch {
+      // A cache that cannot be written costs a rebuild next time, not correctness.
+    }
+  }
+}
+
+/**
+ * Stat every file under `root`, as absolute path → `"<mtimeMs>:<size>"`.
+ *
+ * Contents are never read: `mtime` plus size is enough to notice an edit, and
+ * hashing a whole source tree on every boot would cost more than the build it
+ * is trying to avoid. The gap — a same-size edit that preserves mtime — needs
+ * deliberate effort to produce, and `ZT_NO_BUILD_CACHE=1` covers it.
+ */
+export async function fingerprintTree(root: string): Promise<Record<string, string>> {
+  const out: Record<string, string> = {};
+
+  let entries: string[];
+  try {
+    entries = await readdir(root, { recursive: true });
+  } catch {
+    // A directory that does not exist contributes nothing rather than failing —
+    // an app without `app/` is a valid app.
+    return out;
+  }
+
+  for (const entry of entries) {
+    const path = join(root, entry);
+    const stamp = await _stamp(path);
+    // Directories stat fine but have no meaningful size; `_stamp` returns null
+    // for anything that is not a regular file.
+    if (stamp !== null) out[path] = stamp;
+  }
+
+  return out;
+}
+
+// ── Private ──────────────────────────────────────────────────────────────────
+
+/** `"<mtimeMs>:<size>"` for a regular file, or `null` for anything else. */
+async function _stamp(path: string): Promise<string | null> {
+  try {
+    const info = await stat(path);
+    if (!info.isFile()) return null;
+    return `${info.mtimeMs}:${info.size}`;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Every source file the bundler read, recovered from the emitted sourcemaps.
+ *
+ * A sourcemap's `sources` are relative to the map itself and use the host's
+ * separators, so both need normalising before they name a real file.
+ */
+async function _graphInputs(outputs: readonly BuildArtifactLike[]): Promise<string[]> {
+  const found = new Set<string>();
+
+  for (const output of outputs) {
+    const isMap = output.kind === "sourcemap" || output.path.endsWith(".map");
+    if (!isMap) continue;
+
+    try {
+      const text = output.text ? await output.text() : await Bun.file(output.path).text();
+      const map = JSON.parse(text) as { sources?: unknown };
+      if (!Array.isArray(map.sources)) continue;
+
+      const base = dirname(resolve(output.path));
+      for (const source of map.sources) {
+        if (typeof source !== "string" || source === "") continue;
+        // Virtual entries a plugin injected have no file behind them.
+        if (source.includes("://")) continue;
+        found.add(resolve(base, source.split("\\").join("/")));
+      }
+    } catch {
+      // A map we cannot parse just means a smaller input set, and a smaller
+      // input set only ever causes extra builds.
+      continue;
+    }
+  }
+
+  return [...found];
+}

package/src/dev/CssPlugins.ts

@@ -5,6 +5,26 @@
  */
 import type { BunPlugin } from "bun";
 import { pruneBuildOutput } from "./BuildOutput.ts";
+import { BuildCache } from "./BuildCache.ts";
+
+/** Outcome of one bundling helper. `skipped` means the cache answered. */
+export interface BundleResult {
+  success: boolean;
+  logs: unknown[];
+  /** True when nothing was rebuilt because no input had changed. */
+  skipped?: boolean;
+}
+
+/**
+ * Directories whose contents feed Tailwind's `@source` scan.
+ *
+ * A stylesheet's inputs are not its imports — utility classes are discovered by
+ * reading templates and components, none of which appear in a sourcemap. These
+ * are the conventional locations; a missing one contributes nothing.
+ */
+function _scanRoots(cwd: string): string[] {
+  return [`${cwd}/app`, `${cwd}/resources`, `${cwd}/routes`, `${cwd}/config`];
+}
 
 /**
  * Detect and load `bun-plugin-tailwind` from the app's own node_modules.
@@ -46,13 +66,29 @@ export async function buildCssBundle(
   outdir: string,
   minify = false,
   loader?: Record<string, string>,
-): Promise<{ success: boolean; logs: unknown[] }> {
+): Promise<BundleResult> {
   const cwd = process.cwd();
   const plugins = await detectCssPlugins(cwd);
 
+  // The whole source tree is this bundle's input set, because that is what
+  // Tailwind reads. Broad, but a stat sweep is far cheaper than the build.
+  const cache = BuildCache.for(
+    {
+      entrypoints: [input],
+      outdir,
+      minify,
+      loader,
+      plugins: plugins.map((plugin) => plugin.name ?? "anonymous"),
+      extra: { kind: "css", cli: plugins.length === 0 },
+    },
+    cwd,
+  );
+
+  if (!minify && (await cache.isFresh())) return { success: true, logs: [], skipped: true };
+
   if (plugins.length > 0) {
     // bun-plugin-tailwind is available — use Bun's native CSS bundler
-    return Bun.build({
+    const result = await Bun.build({
       entrypoints: [input],
       outdir,
       target: "browser",
@@ -62,6 +98,9 @@ export async function buildCssBundle(
         ? { loader: loader as NonNullable<Parameters<typeof Bun.build>[0]["loader"]> }
         : {}),
     });
+
+    if (result.success) await cache.record(result.outputs, { scanRoots: _scanRoots(cwd) });
+    return { success: result.success, logs: result.logs as unknown[] };
   }
 
   // Fallback: run the Tailwind CLI as a subprocess
@@ -91,6 +130,12 @@ export async function buildCssBundle(
       new Response(subprocess.stderr).text(),
     ]);
 
+    if (exitCode === 0) {
+      // The CLI emits no sourcemap and returns no artifact list, so the one
+      // output is named rather than discovered.
+      await cache.record([{ path: outputFile }], { scanRoots: _scanRoots(cwd) });
+    }
+
     return {
       success: exitCode === 0,
       logs: exitCode !== 0 ? [stderr] : [],
@@ -115,15 +160,30 @@ export async function buildJsBundle(
   input: string,
   outdir: string,
   minify = false,
-): Promise<{ success: boolean; logs: unknown[] }> {
+): Promise<BundleResult> {
+  const cwd = process.cwd();
+  const cache = BuildCache.for(
+    { entrypoints: [input], outdir, minify, extra: { kind: "js" } },
+    cwd,
+  );
+
+  if (!minify && (await cache.isFresh())) return { success: true, logs: [], skipped: true };
+
   try {
-    return await Bun.build({
+    const result = await Bun.build({
       entrypoints: [input],
       outdir,
       target: "browser",
       format: "esm",
       minify,
+      // Not only for debugging: the map's `sources` are how the cache learns
+      // which files this bundle actually pulled in.
+      ...(minify ? {} : { sourcemap: "external" as const }),
     });
+
+    // No scan roots — a JS bundle's inputs are exactly its module graph.
+    if (result.success) await cache.record(result.outputs);
+    return { success: result.success, logs: result.logs as unknown[] };
   } catch (error) {
     return { success: false, logs: [error] };
   }
@@ -162,13 +222,32 @@ export interface AssetBuildConfig {
 export async function buildConfiguredAssets(
   assets: AssetBuildConfig,
   cwd: string,
-): Promise<{ success: boolean; logs: unknown[] }> {
+): Promise<BundleResult> {
   const entries = Array.isArray(assets.entrypoint) ? assets.entrypoint : [assets.entrypoint];
   const entrypoints = entries.map((entry) => `${cwd}/${entry}`);
   const outdir = `${cwd}/${assets.outDir}`;
 
   try {
     const plugins = await detectCssPlugins(cwd);
+
+    const cache = BuildCache.for(
+      {
+        entrypoints,
+        outdir,
+        minify: assets.minify,
+        loader: assets.loader,
+        plugins: plugins.map((plugin) => plugin.name ?? "anonymous"),
+        extra: { kind: "configured" },
+      },
+      cwd,
+    );
+
+    // Never in a minified (production) build: the cost of a wrong skip there is
+    // shipping stale assets, and the build runs once rather than on every save.
+    if (!assets.minify && (await cache.isFresh())) {
+      return { success: true, logs: [], skipped: true };
+    }
+
     const result = await Bun.build({
       entrypoints,
       outdir,
@@ -187,8 +266,15 @@ export async function buildConfiguredAssets(
         : {}),
     });
 
-    if (result.success) await pruneBuildOutput(outdir, result.outputs);
-    return result;
+    // Prune only after a build that actually ran. A skipped build returns no
+    // outputs, and pruning against an empty set would delete the entire
+    // previous build — which is why the cache check returns early above rather
+    // than falling through to here.
+    if (result.success) {
+      await pruneBuildOutput(outdir, result.outputs);
+      await cache.record(result.outputs, { scanRoots: _scanRoots(cwd) });
+    }
+    return { success: result.success, logs: result.logs as unknown[] };
   } catch (error) {
     return { success: false, logs: [error] };
   }

package/src/dev/DevBuildHook.ts

@@ -16,6 +16,13 @@
 export interface BuildResult {
   success: boolean;
   logs?: unknown[];
+  /**
+   * True when every registered routine skipped — nothing had changed since the
+   * last build. Reported so the dev log can say so: a developer who saves a file
+   * and sees no rebuild, with no explanation, deletes `.zerotal/` and stops
+   * trusting the tool.
+   */
+  skipped?: boolean;
 }
 
 /** A frontend build routine that resolves once the build finishes. */
@@ -60,7 +67,11 @@ export async function runDevBuildHooks(): Promise<BuildResult> {
     Array.from(_hooks, async ([name, fn]): Promise<BuildResult> => {
       try {
         const result = await fn();
-        return { success: result.success, logs: (result.logs ?? []).map((l) => `[${name}] ${l}`) };
+        return {
+          success: result.success,
+          logs: (result.logs ?? []).map((l) => `[${name}] ${l}`),
+          ...(result.skipped === true ? { skipped: true } : {}),
+        };
       } catch (error) {
         return { success: false, logs: [`[${name}] ${error}`] };
       }
@@ -70,5 +81,7 @@ export async function runDevBuildHooks(): Promise<BuildResult> {
   return {
     success: results.every((result) => result.success),
     logs: results.flatMap((result) => result.logs ?? []),
+    // Only when *every* routine skipped: one bundle rebuilding is a rebuild.
+    skipped: results.length > 0 && results.every((result) => result.skipped === true),
   };
 }