@zerotal/core 1.8.1 → 1.9.0

package/src/shared/format.ts

@@ -0,0 +1,135 @@
+/**
+ * Formatting both sides of the wire can agree on.
+ *
+ * The problem this solves is not that formatting is hard. `Intl` is in every
+ * runtime the framework targets and does the work. The problem is that a server
+ * helper and a browser helper are two places to make the same decision, and a
+ * total that reads `R 39 147` on screen and `R39,147.00` on the invoice looks like
+ * two different numbers to the person paying it.
+ *
+ * So these are deliberately thin — they fix the options, not the arithmetic. The
+ * value is that there is one definition of "how this app writes money" and both
+ * the controller and the component import it.
+ *
+ * Everything here is pure and dependency-free, and this module is reachable from
+ * `zerotal/shared`, so it bundles into a browser build without pulling the
+ * framework in behind it.
+ *
+ * @module
+ */
+
+/** How a value should be written. */
+export interface FormatOptions {
+  /**
+   * BCP-47 locale. Defaults to the runtime's — which on a server is the machine's
+   * and in a browser is the reader's, and those are not the same. Pass one
+   * explicitly wherever the two sides must match, and they usually must.
+   */
+  locale?: string;
+}
+
+/** How money should be written. */
+export interface MoneyOptions extends FormatOptions {
+  /** ISO 4217 code — `ZAR`, `USD`, `EUR`. */
+  currency: string;
+  /**
+   * Whether the amount is in the currency's minor unit (cents), which is how a
+   * database column that must not lose a cent stores it. Default `true`, because
+   * an app that stores money in a float has a different problem.
+   */
+  minorUnits?: boolean;
+  /** Digits after the decimal point. Defaults to whatever the currency uses. */
+  fractionDigits?: number;
+}
+
+/**
+ * Write an amount of money.
+ *
+ * @param amount - The amount, in minor units unless `minorUnits: false`.
+ * @param options - Currency, and how to write it.
+ *
+ * @example
+ * ```ts
+ * formatMoney(3_914_700, { currency: "ZAR", locale: "en-ZA" });  // "R 39 147,00"
+ * formatMoney(39_147, { currency: "USD", minorUnits: false });   // "$39,147.00"
+ * ```
+ */
+export function formatMoney(amount: number, options: MoneyOptions): string {
+  const { currency, locale, minorUnits = true, fractionDigits } = options;
+  const value = minorUnits ? amount / 100 : amount;
+  return new Intl.NumberFormat(locale, {
+    style: "currency",
+    currency,
+    ...(fractionDigits !== undefined
+      ? { minimumFractionDigits: fractionDigits, maximumFractionDigits: fractionDigits }
+      : {}),
+  }).format(value);
+}
+
+/** How a plain number should be written. */
+export interface NumberOptions extends FormatOptions {
+  /** Smallest number of digits after the decimal point. */
+  minimumFractionDigits?: number;
+  /** Largest number of digits after the decimal point. */
+  maximumFractionDigits?: number;
+}
+
+/**
+ * Write a number with the reader's group and decimal separators.
+ *
+ * @example
+ * ```ts
+ * formatNumber(39147.5, { locale: "en-GB", maximumFractionDigits: 1 });  // "39,147.5"
+ * ```
+ */
+export function formatNumber(value: number, options: NumberOptions = {}): string {
+  const { locale, ...rest } = options;
+  return new Intl.NumberFormat(locale, rest).format(value);
+}
+
+/** How a date should be written. */
+export interface DateOptions extends FormatOptions {
+  /** Length of the date part. Omit for none. */
+  dateStyle?: "full" | "long" | "medium" | "short";
+  /** Length of the time part. Omit for none. */
+  timeStyle?: "full" | "long" | "medium" | "short";
+  /**
+   * IANA zone — `Africa/Johannesburg`, `UTC`.
+   *
+   * Worth passing on the server. A machine set to UTC and a reader in Cape Town
+   * disagree about which day an 11pm booking happened on, and that is the shape
+   * the bug takes: not a wrong time, a wrong date.
+   */
+  timeZone?: string;
+}
+
+/**
+ * Write a date or timestamp.
+ *
+ * @param value - A `Date`, an epoch-milliseconds number, or an ISO string.
+ * @param options - Which parts to write, and in whose zone.
+ *
+ * @example
+ * ```ts
+ * formatDate("2026-08-28T21:00:00Z", {
+ *   locale: "en-ZA",
+ *   dateStyle: "medium",
+ *   timeZone: "Africa/Johannesburg",
+ * });
+ * ```
+ */
+export function formatDate(value: Date | number | string, options: DateOptions = {}): string {
+  const { locale, ...rest } = options;
+  const date = value instanceof Date ? value : new Date(value);
+  if (Number.isNaN(date.getTime())) return "";
+  // `Intl` given neither style writes the date and nothing else, which is the
+  // useful default for a helper named `formatDate`. Spread rather than replaced:
+  // the default has to keep `timeZone`, or a caller who passed a zone and no style
+  // silently gets the machine's — which is the exact wrong-day bug the option is
+  // there to prevent.
+  const noStyle = rest.dateStyle === undefined && rest.timeStyle === undefined;
+  return new Intl.DateTimeFormat(locale, {
+    ...rest,
+    ...(noStyle ? { dateStyle: "medium" as const } : {}),
+  }).format(date);
+}

package/src/shared/index.ts

@@ -0,0 +1,34 @@
+/**
+ * The helpers that are safe to import from a browser bundle.
+ *
+ * Every function reachable from this module is pure: no `node:` imports, no `Bun`
+ * globals, no config, no container, no request context. Importing it from a
+ * component pulls in these functions and nothing else — the framework does not
+ * come with them.
+ *
+ * **Why this exists.** Without it, an app that wants the framework's `pluralize`
+ * on a page has two options, and both are bad. Importing `zerotal` into the client
+ * bundle drags the server in. Writing a second implementation means maintaining
+ * the same rule twice — and the second copy is always the worse one, because the
+ * irregulars and the inflect-the-last-word behaviour are exactly what somebody
+ * re-deriving it by hand leaves out. `"supplier line"` pluralises to
+ * `"supplier lines"`; the naive rule gives `"suppliers line"`.
+ *
+ * The same argument applies to money. Two formatters that must agree are a bug
+ * waiting for a rounding difference, and the person who finds it is the one paying
+ * the invoice.
+ *
+ * @example
+ * ```tsx
+ * // resources/js/pages/Trips/Index.tsx — a browser bundle
+ * import { pluralize, formatMoney } from "zerotal/shared";
+ *
+ * <p>{trips.length} {pluralize("trip")} — {formatMoney(total, { currency: "ZAR" })}</p>
+ * ```
+ *
+ * @packageDocumentation
+ */
+export { pluralize, singularize, snakeCase, camelCase, tableNameFor } from "../support/str.ts";
+export { Str } from "../helpers/str.ts";
+export { formatMoney, formatNumber, formatDate } from "./format.ts";
+export type { FormatOptions, MoneyOptions, NumberOptions, DateOptions } from "./format.ts";

package/src/storage/StorageFilesMiddleware.ts

@@ -132,6 +132,8 @@ export class StorageFilesMiddleware extends BaseMiddleware<StorageFilesOptions>
  * accepts a request rather than the first time someone guesses a path.
  *
  * @throws {@link UnsafePublicMountError}
+ *
+ * @internal
  */
 export function mountsFrom(config: StorageConfigShape): Mount[] {
   const mounts: Mount[] = [];

package/src/support/cookie.ts

@@ -35,6 +35,8 @@ export interface CookieOptions {
  * @example
  * buildCookie({ name: "session", value, maxAge: 86400, secure: true });
  * // "session=…; Path=/; HttpOnly; SameSite=Lax; Max-Age=86400; Secure"
+ *
+ * @internal
  */
 export function buildCookie(options: CookieOptions): string {
   const parts = [`${options.name}=${options.value}`, `Path=${options.path ?? "/"}`];
@@ -59,7 +61,11 @@ export function readCookie(request: Request, name: string): string | undefined {
   return parseCookieHeader(request.headers.get("Cookie") ?? "", name);
 }
 
-/** Extract a single cookie value from a raw `Cookie` header string. */
+/**
+ * Extract a single cookie value from a raw `Cookie` header string.
+ *
+ * @internal
+ */
 export function parseCookieHeader(header: string, name: string): string | undefined {
   for (const part of header.split(";")) {
     const eqIdx = part.indexOf("=");

package/src/support/runtime.ts

@@ -0,0 +1,136 @@
+/**
+ * One project, one Bun.
+ *
+ * `engines.bun` is a floor, and nothing enforces it. A project can therefore end
+ * up with two runtimes in play at once — the shell's `bun` and the one sitting in
+ * `node_modules/bun`, put there by a transitive peer dependency nobody declared —
+ * and split its work between them: the server served by one, the suite run by the
+ * other. Nothing announces that. The suite stays green, and it is green about a
+ * runtime the app is not served by.
+ *
+ * What makes it expensive is that the difference is real but narrow. The SQLite
+ * bindings, `node:` compatibility and the test runner itself all differ between
+ * releases, so a handful of assertions happen to be 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 "different binary". And a suite that passes
+ * is not evidence: it only means no test happened to stand on a difference.
+ *
+ * This module is the check. It is not a pin — the version to agree on is whichever
+ * one the project installed, so `bun update bun` moves it and nothing here needs
+ * editing. What it enforces is that there is only one.
+ *
+ * @module
+ */
+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. */
+export const RUNTIME_MISMATCH_ESCAPE = "ZT_ALLOW_RUNTIME_MISMATCH";
+
+/** A running runtime and the installed one it disagrees with. */
+export interface RuntimeMismatch {
+  /** `Bun.version` — the binary this process is executing under. */
+  running: string;
+  /** The version in `node_modules/bun/package.json`. */
+  installed: string;
+  /** Absolute path of the manifest `installed` was read from. */
+  manifest: string;
+}
+
+/**
+ * The Bun version a project has installed, by walking up from `cwd` looking for
+ * `node_modules/bun/package.json`.
+ *
+ * Walking rather than reading one fixed path because hoisting decides where the
+ * package lands: in a workspace it is at the repo root, not beside the app.
+ *
+ * @param cwd - Directory to start from.
+ * @returns `{ version, manifest }`, or `null` when the project does not install
+ *   Bun as a package — which is the common case and not a finding.
+ */
+export function installedBunVersion(cwd: string): { version: string; manifest: string } | null {
+  let dir = cwd;
+  // Bounded by the filesystem root: dirname("/") === "/" and dirname("C:\\") === "C:\\".
+  for (;;) {
+    const manifest = join(dir, "node_modules", "bun", "package.json");
+    try {
+      const { version } = JSON.parse(readFileSync(manifest, "utf8")) as { version?: string };
+      if (version) return { version, manifest };
+    } catch {
+      // Not here — keep climbing.
+    }
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+/**
+ * Compare the running runtime against the installed one.
+ *
+ * The comparison is exact. A patch difference is still two binaries, and the
+ * failures this guards against do not respect semver — a change to the SQLite
+ * bindings is a patch release to Bun and a behaviour change to an app that stores
+ * money in SQLite. "Close enough" is the belief that cost the weeks.
+ *
+ * @param cwd - Project root to look under. Defaults to the working directory.
+ * @returns The mismatch, or `null` when the versions agree or nothing is installed
+ *   to disagree with.
+ */
+export function runtimeMismatch(cwd: string = process.cwd()): RuntimeMismatch | null {
+  const running = typeof Bun === "undefined" ? "" : Bun.version;
+  if (!running) return null;
+  const installed = installedBunVersion(cwd);
+  if (!installed) return null;
+  if (installed.version === running) return null;
+  return { running, installed: installed.version, manifest: installed.manifest };
+}
+
+/**
+ * The message shown for a mismatch — the two versions, where the second came from,
+ * and the two ways out.
+ *
+ * @param mismatch - The disagreement to describe.
+ */
+export function runtimeMismatchMessage(mismatch: RuntimeMismatch): string {
+  return (
+    `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` +
+    `  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` +
+    `  To boot anyway, set ${RUNTIME_MISMATCH_ESCAPE}=1 — it downgrades this to a warning.`
+  );
+}
+
+/**
+ * Whether the escape hatch is set. Deliberately an env var and not a config key:
+ * the situation it covers is a project mid-upgrade, where the thing you want is to
+ * get one command through, not to write the exception down.
+ */
+export function runtimeMismatchAllowed(): boolean {
+  const raw = (globalThis as { Bun?: { env: Record<string, string | undefined> } }).Bun?.env[
+    RUNTIME_MISMATCH_ESCAPE
+  ];
+  return raw === "1" || raw === "true";
+}
+
+/**
+ * The Bun binary to spawn a child process with.
+ *
+ * `process.execPath` rather than `"bun"`, because `"bun"` is resolved by the OS
+ * against `PATH` and the parent process was not necessarily started from `PATH`.
+ * A command that exists to run *this app's* tests, spawning whichever binary the
+ * shell happens to offer, is how the suite ends up on a different runtime from the
+ * server — and it is invisible, because the child prints a version nobody reads.
+ *
+ * @returns An absolute path to the running binary, or `"bun"` when there is none to
+ *   read (a compiled binary, an unusual embed) and PATH is all that is left.
+ */
+export function bunBinary(): string {
+  const path = process.execPath;
+  return path && path.length > 0 ? path : "bun";
+}

package/src/view/FileRouteResolver.ts

@@ -23,6 +23,8 @@ function isClass(fn: Function): boolean {
  * export that is a view component (or any function tagged via the view marker)
  * is rendered to HTML, wrapped in the nearest `_layout`, and registered as a GET
  * route. Call from a provider's `onRegister()` before file routes are scanned.
+ *
+ * @internal
  */
 export function registerViewFileRouteResolver(): void {
   enableFileRouteLayouts();

package/src/view/jsx-runtime.ts

@@ -7,12 +7,16 @@ import { escapeHtml as escHtml } from "../helpers/html.ts";
  * letting the renderer distinguish page/layout components from ordinary
  * functions. Registered via `Symbol.for` so the marker survives across module
  * realms.
+ *
+ * @internal
  */
 export const VIEW_COMPONENT_SYMBOL = Symbol.for("zerotal.view.component");
 
 /**
  * String-keyed twin of {@link VIEW_COMPONENT_SYMBOL}. Set alongside the symbol
  * as a fallback for tooling or environments that can't read symbol-keyed props.
+ *
+ * @internal
  */
 export const VIEW_COMPONENT_PROP = "__zerotalViewComponent";