@zerotal/core 1.9.0 → 1.11.0

package/src/storage/StorageFilesMiddleware.ts

@@ -16,9 +16,9 @@ interface Mount {
 
 export interface StorageFilesOptions {
   /** Disks to serve, in match order. Built from config by {@link StorageProvider}. */
-  mounts?: Mount[];
+  mounts?: Mount[] | undefined;
   /** The manager the files are read through. */
-  storage?: StorageManager;
+  storage?: StorageManager | undefined;
 }
 
 /**

package/src/storage/types.ts

@@ -1,6 +1,6 @@
 export interface PutOptions {
-  contentType?: string;
-  visibility?: "public" | "private";
+  contentType?: string | undefined;
+  visibility?: "public" | "private" | undefined;
 }
 
 export interface StorageDriver {
@@ -61,14 +61,14 @@ export interface DiskServeConfig {
    * only someone holding a link you signed can read a file, and only until it
    * expires.
    */
-  signed?: boolean;
+  signed?: boolean | undefined;
   /**
    * How long a signed link stays valid, in seconds. Only meaningful with
    * `signed`. Defaults to 900 (15 minutes).
    */
-  expiresIn?: number;
+  expiresIn?: number | undefined;
   /** Extra response headers, e.g. `Cache-Control`. */
-  headers?: Record<string, string>;
+  headers?: Record<string, string> | undefined;
 }
 
 export interface LocalDiskConfig {
@@ -76,9 +76,9 @@ export interface LocalDiskConfig {
   /** Absolute or relative root directory for file storage. */
   root: string;
   /** Optional base URL for url() — e.g. '/storage' or 'https://cdn.example.com'. */
-  url?: string;
+  url?: string | undefined;
   /** Expose this disk over HTTP. Omit to keep it unreachable. */
-  serve?: DiskServeConfig;
+  serve?: DiskServeConfig | undefined;
 }
 
 export interface S3DiskConfig {
@@ -88,11 +88,11 @@ export interface S3DiskConfig {
   region: string;
   bucket: string;
   /** Override endpoint for R2, MinIO, etc. E.g. 'https://<account>.r2.cloudflarestorage.com' */
-  endpoint?: string;
+  endpoint?: string | undefined;
   /** Custom public URL base (e.g. CDN or R2 public domain). */
-  url?: string;
+  url?: string | undefined;
   /** Expose this disk over HTTP, proxied through the app. Omit to keep it unreachable. */
-  serve?: DiskServeConfig;
+  serve?: DiskServeConfig | undefined;
 }
 
 export type DiskConfig = LocalDiskConfig | S3DiskConfig;

package/src/support/cookie.ts

@@ -16,17 +16,17 @@ export interface CookieOptions {
   /** Cookie value (caller is responsible for encoding if needed). */
   value: string;
   /** `Path` attribute. Defaults to `/`. */
-  path?: string;
+  path?: string | undefined;
   /** `Max-Age` in seconds. Omit for a session cookie. `0` clears the cookie. */
-  maxAge?: number;
+  maxAge?: number | undefined;
   /** `SameSite` attribute. Defaults to `Lax`. */
-  sameSite?: SameSite;
+  sameSite?: SameSite | undefined;
   /** Add the `HttpOnly` attribute. Defaults to `true` — pass `false` for cookies JS must read (e.g. XSRF-TOKEN). */
-  httpOnly?: boolean;
+  httpOnly?: boolean | undefined;
   /** Add the `Secure` attribute. Defaults to `false`. */
-  secure?: boolean;
+  secure?: boolean | undefined;
   /** `Domain` attribute. Omitted when absent. */
-  domain?: string;
+  domain?: string | undefined;
 }
 
 /**

package/src/support/deepMerge.ts

@@ -155,3 +155,52 @@ export function deepMerge<T extends object>(base: T, override: DeepPartial<T>):
   }
   return result;
 }
+
+/**
+ * A shape whose optional properties have all been given a value.
+ *
+ * `Required<T>` is not this, which is the trap. `-?` removes the *optionality* a
+ * `?` introduced; it does not remove an `undefined` that was written into the type.
+ * So once an options shape says `retentionDays?: number | undefined` — as every
+ * public option shape here does, so that `{ x: a ?? undefined }` is writable —
+ * `Required<Options>` still hands back `number | undefined`, and the "defaults have
+ * been applied" type quietly stops meaning that.
+ *
+ * Use this for the object a constructor builds after applying its defaults.
+ *
+ * @example
+ * ```ts
+ * private readonly _opts: Resolved<Pick<Options, "retentionDays">> & Omit<Options, "retentionDays">;
+ * ```
+ */
+export type Resolved<T> = { [K in keyof T]-?: Exclude<T[K], undefined> };
+
+/**
+ * `value` without the keys whose value is `undefined`.
+ *
+ * Object spread copies own properties even when they hold `undefined`, so
+ * `{ ...defaults, ...options }` lets an explicitly-`undefined` field overwrite a
+ * default rather than leave it alone. Every public option shape accepts an explicit
+ * `undefined` — that is what makes `{ x: a ?? undefined }` writable — so the merge
+ * is where "supplied as undefined" has to be turned back into "not supplied".
+ *
+ * The return type keeps each key optional while dropping `undefined` from its type,
+ * which is exactly the guarantee this provides.
+ *
+ * @param value - The bag to filter.
+ * @returns A new object with the `undefined`-valued keys absent.
+ *
+ * @example
+ * ```ts
+ * const merged = { ...DEFAULTS, ...definedOnly(options) };
+ * ```
+ */
+export function definedOnly<T extends object>(
+  value: T,
+): { [K in keyof T]?: Exclude<T[K], undefined> } {
+  const out: Record<string, unknown> = {};
+  for (const [key, item] of Object.entries(value)) {
+    if (item !== undefined) out[key] = item;
+  }
+  return out as { [K in keyof T]?: Exclude<T[K], undefined> };
+}

package/src/support/runtime.ts

@@ -24,7 +24,7 @@
 import { readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 
-/** Set to `1`/`true` to downgrade a runtime mismatch from a refusal to a warning. */
+/** Set to `1`/`true` to downgrade a runtime disagreement from a refusal to a warning. */
 export const RUNTIME_MISMATCH_ESCAPE = "ZT_ALLOW_RUNTIME_MISMATCH";
 
 /** A running runtime and the installed one it disagrees with. */
@@ -35,6 +35,12 @@ export interface RuntimeMismatch {
   installed: string;
   /** Absolute path of the manifest `installed` was read from. */
   manifest: string;
+  /**
+   * Whether the project *asked* for a `bun` package — named it in its own
+   * dependencies — or merely acquired one as a transitive peer. A mismatch the
+   * project chose is a refusal; one it did not is a warning.
+   */
+  chosen?: boolean | undefined;
 }
 
 /**
@@ -83,7 +89,54 @@ export function runtimeMismatch(cwd: string = process.cwd()): RuntimeMismatch |
   const installed = installedBunVersion(cwd);
   if (!installed) return null;
   if (installed.version === running) return null;
-  return { running, installed: installed.version, manifest: installed.manifest };
+  return {
+    running,
+    installed: installed.version,
+    manifest: installed.manifest,
+    chosen: declaresBunDependency(cwd),
+  };
+}
+
+/**
+ * Whether the project asked for a `bun` package, or merely ended up with one.
+ *
+ * This is the difference between two runtimes and one runtime plus a stray npm
+ * package, and it decides whether the mismatch is a refusal or a warning.
+ *
+ * It matters because the common way to acquire a `node_modules/bun` is not to want
+ * one. `bun-plugin-tailwind@0.1.2` — which the scaffold itself installs — declares
+ * `"peerDependencies": { "bun": ">=1.0.0" }` with no `peerDependenciesMeta` marking
+ * it optional, so `bun install` auto-installs the Bun *npm package* as a second
+ * runtime, newer than the one executing. An app hit exactly that and took two
+ * production outages: the first when the refusal crash-looped behind a 502, the
+ * second when the obvious fix (`rm -rf node_modules/bun` after install) could not
+ * work, because that package's postinstall runs *during* install and its removal
+ * leaves the tree incomplete.
+ *
+ * Nothing about that situation is a project running two runtimes. Nobody executes
+ * the stray copy; it is a directory. Refusing to boot over it is the guard being
+ * confidently wrong, and the remedies it prints — `bun update bun`, or run
+ * everything through `node_modules/.bin/bun` — are both wrong answers to it.
+ *
+ * @param cwd - Project root to look under.
+ * @returns `true` when a manifest up the tree names `bun` in its own dependencies.
+ */
+export function declaresBunDependency(cwd: string): boolean {
+  let dir = cwd;
+  for (;;) {
+    try {
+      const manifest = JSON.parse(readFileSync(join(dir, "package.json"), "utf8")) as {
+        dependencies?: Record<string, string>;
+        devDependencies?: Record<string, string>;
+      };
+      if (manifest.dependencies?.["bun"] ?? manifest.devDependencies?.["bun"]) return true;
+    } catch {
+      // No manifest here, or unreadable — keep climbing.
+    }
+    const parent = dirname(dir);
+    if (parent === dir) return false;
+    dir = parent;
+  }
 }
 
 /**
@@ -93,12 +146,34 @@ export function runtimeMismatch(cwd: string = process.cwd()): RuntimeMismatch |
  * @param mismatch - The disagreement to describe.
  */
 export function runtimeMismatchMessage(mismatch: RuntimeMismatch): string {
-  return (
+  const head =
     `Two Bun runtimes are in play. This process is Bun ${mismatch.running}, but the ` +
     `project installs Bun ${mismatch.installed} (${mismatch.manifest}).\n\n` +
     `  Whichever one is not running this command is still running something else — ` +
     `the server, the suite, a deploy step — and a test that passes under one is not ` +
-    `evidence about the other.\n\n` +
+    `evidence about the other.\n\n`;
+
+  // Nothing named `bun`, so it arrived as a transitive peer. Naming the usual
+  // culprit is most of the fix, because the remedies below are the opposite of the
+  // ones for a runtime somebody chose — and following those instead cost an app two
+  // production outages.
+  if (mismatch.chosen === false) {
+    return (
+      head +
+      `  Nothing in this project depends on "bun", so it arrived as a transitive peer —\n` +
+      `  usually bun-plugin-tailwind, which declares "bun" as a required peer dependency\n` +
+      `  and has Bun auto-install it as a second runtime.\n\n` +
+      `  Fix it by not installing it:\n` +
+      `    bun install --omit=peer   # skips every peer; safe when yours are direct deps\n\n` +
+      `  Do NOT remove node_modules/bun after installing. That package's postinstall runs\n` +
+      `  *during* install, so deleting it afterwards leaves the tree incomplete and the\n` +
+      `  next install fails — which is its own outage.\n\n` +
+      `  To boot anyway, set ${RUNTIME_MISMATCH_ESCAPE}=1 — it downgrades this to a warning.`
+    );
+  }
+
+  return (
+    head +
     `  Fix it by picking one:\n` +
     `    bun update bun          # move the installed one to match your shell\n` +
     `    node_modules/.bin/bun   # or run everything through the installed one\n\n` +
@@ -134,3 +209,93 @@ export function bunBinary(): string {
   const path = process.execPath;
   return path && path.length > 0 ? path : "bun";
 }
+
+/** A running runtime and the floor the project says it needs. */
+export interface RuntimeFloor {
+  /** `Bun.version` — the binary this process is executing under. */
+  running: string;
+  /** The `engines.bun` range the project declares. */
+  required: string;
+  /** Absolute path of the manifest `required` was read from. */
+  manifest: string;
+}
+
+/**
+ * The project's declared Bun floor, by walking up from `cwd` for a `package.json`
+ * with an `engines.bun`.
+ *
+ * Walking rather than reading one fixed path, for the same reason
+ * {@link installedBunVersion} walks: in a workspace the app and the manifest that
+ * pins the runtime are not always the same directory. The first `engines.bun` found
+ * wins — the nearest one is the app's own.
+ *
+ * @param cwd - Directory to start from.
+ * @returns `{ range, manifest }`, or `null` when nothing up the tree declares one.
+ */
+export function declaredBunFloor(cwd: string): { range: string; manifest: string } | null {
+  let dir = cwd;
+  // Bounded by the filesystem root: dirname("/") === "/" and dirname("C:\\") === "C:\\".
+  for (;;) {
+    const manifest = join(dir, "package.json");
+    try {
+      const parsed = JSON.parse(readFileSync(manifest, "utf8")) as {
+        engines?: { bun?: string };
+      };
+      const range = parsed.engines?.bun;
+      if (range) return { range, manifest };
+    } catch {
+      // No manifest here, or not one we can read — keep climbing.
+    }
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+/**
+ * Whether this process is running below the Bun version the project says it needs.
+ *
+ * `engines.bun` is written by every generated app and enforced by nothing, which is
+ * the gap {@link runtimeMismatch} does not cover: that one compares the running
+ * runtime against an *installed* one, and most projects do not install Bun as a
+ * package, so it has nothing to compare against and correctly says nothing.
+ *
+ * The failure this catches is narrow and expensive. `Intl` output differs between
+ * Bun releases, so a suite with currency or date assertions goes red on a runtime
+ * that is otherwise fine, and the failures name the code they touch rather than the
+ * binary. The version is the last thing anyone checks.
+ *
+ * An unparseable range is treated as satisfied. A refusal because we could not read
+ * a version range is worse than the mismatch it would have prevented.
+ *
+ * @param cwd - Project root to look under. Defaults to the working directory.
+ * @returns The shortfall, or `null` when the floor is met or none is declared.
+ */
+export function runtimeBelowFloor(cwd: string = process.cwd()): RuntimeFloor | null {
+  const running = typeof Bun === "undefined" ? "" : Bun.version;
+  if (!running) return null;
+  const declared = declaredBunFloor(cwd);
+  if (!declared) return null;
+  if (Bun.semver.satisfies(running, declared.range)) return null;
+  return { running, required: declared.range, manifest: declared.manifest };
+}
+
+/**
+ * The message shown when the runtime is below the project's floor.
+ *
+ * @param floor - The shortfall to describe.
+ */
+export function runtimeBelowFloorMessage(floor: RuntimeFloor): string {
+  return (
+    `This process is Bun ${floor.running}, and the project requires ${floor.required} ` +
+    `(${floor.manifest}).\n\n` +
+    `  The difference between two Bun releases is real and narrow: Intl formatting, the ` +
+    `SQLite bindings and node: compatibility all move, so a handful of assertions are ` +
+    `runtime-sensitive and the rest are not. When two of them fail you go looking for a bug ` +
+    `in the code they touch, because nothing in the failure says "wrong binary".\n\n` +
+    `  Fix it by upgrading the runtime, or by lowering engines.bun if this version is ` +
+    `genuinely supported:\n` +
+    `    bun upgrade\n\n` +
+    `  To run anyway, set ${RUNTIME_MISMATCH_ESCAPE}=1 — it downgrades this to a warning.`
+  );
+}