@zerotal/core 1.0.0

package/src/logger/channels/DailyChannel.ts

@@ -0,0 +1,74 @@
+import type { LogChannel, LogEntry } from "../types.ts";
+import type { StorageDriver } from "../../storage/types.ts";
+import { LocalDriver } from "../../storage/drivers/LocalDriver.ts";
+import { readdir, stat, unlink } from "node:fs/promises";
+
+/**
+ * Appends entries as JSON lines to a date-rotated file, one file per day named
+ * `YYYY-MM-DD.log` (derived from the entry's timestamp) inside a directory.
+ *
+ * Writes go through a {@link StorageDriver}, so the log trail uses the same file
+ * API as uploads and the media library rather than a second, private way of
+ * putting bytes on disk — and inherits its path-traversal guard for free.
+ *
+ * When a retention window (`days`) is given, files whose modification time is
+ * older than the cutoff are pruned — checked at most once every 24 hours, in
+ * the background, and only on write. The directory is created on demand.
+ *
+ * @category Channels
+ *
+ * @example
+ * ```ts
+ * // config/logging.ts — keep 14 days of daily files under ./storage/logs
+ * file: { path: "./storage/logs", days: 14 },
+ * ```
+ */
+export class DailyChannel implements LogChannel {
+  private _lastPruned = 0;
+  private readonly _disk: StorageDriver;
+
+  /**
+   * @param _dir - Directory that holds the per-day log files.
+   * @param _days - Retention window in days; older files are pruned. Omit to keep files forever.
+   * @param disk - Driver to write through. Defaults to a {@link LocalDriver} rooted at `_dir`.
+   *   Pass one to send the trail somewhere else — it must support `append`, which
+   *   rules out object stores.
+   */
+  constructor(
+    private readonly _dir: string,
+    private readonly _days?: number,
+    disk?: StorageDriver,
+  ) {
+    this._disk = disk ?? new LocalDriver(_dir);
+  }
+
+  async write(entry: LogEntry): Promise<void> {
+    const date = entry.timestamp.slice(0, 10);
+    await this._disk.append(`${date}.log`, JSON.stringify(entry) + "\n");
+
+    if (this._days !== undefined) {
+      const now = Date.now();
+      if (now - this._lastPruned > 86_400_000) {
+        this._lastPruned = now;
+        void this._prune(now).catch(() => {});
+      }
+    }
+  }
+
+  /**
+   * Delete day-files older than the retention window.
+   *
+   * Listing and stat'ing stay on `node:fs`: the driver contract has no
+   * directory listing, and inventing one for a log pruner would widen it for
+   * every backend to serve a single caller.
+   */
+  private async _prune(now: number): Promise<void> {
+    const cutoff = now - this._days! * 86_400_000;
+    const files = await readdir(this._dir);
+    for (const file of files) {
+      if (!/^\d{4}-\d{2}-\d{2}\.log$/.test(file)) continue;
+      const s = await stat(`${this._dir}/${file}`);
+      if (s.mtimeMs < cutoff) await unlink(`${this._dir}/${file}`);
+    }
+  }
+}

package/src/logger/channels/NullChannel.ts

@@ -0,0 +1,17 @@
+/**
+ * A no-op {@link LogChannel} that discards every entry.
+ *
+ * Useful for silencing logging in tests, or as a `default` channel when you
+ * want logging calls to be harmless no-ops.
+ *
+ * @category Channels
+ *
+ * @example
+ * ```ts
+ * // config/logging.ts
+ * channels: { null: { driver: "null" } }
+ * ```
+ */
+export class NullChannel {
+  async write(): Promise<void> {}
+}

package/src/logger/channels/SingleChannel.ts

@@ -0,0 +1,34 @@
+import type { LogChannel, LogEntry } from "../types.ts";
+import { appendFile, mkdir } from "node:fs/promises";
+
+/**
+ * Appends every entry as a JSON line to a single, fixed log file.
+ *
+ * Parent directories are created on demand. Write failures are swallowed so a
+ * logging error never propagates into application code.
+ *
+ * @category Channels
+ *
+ * @example
+ * ```ts
+ * // config/logging.ts
+ * channels: {
+ *   single: { driver: "single", path: "./storage/logs/app.log", level: "info" },
+ * }
+ * ```
+ */
+export class SingleChannel implements LogChannel {
+  /** @param _file - Path to the log file to append to (config key `path`). */
+  constructor(private readonly _file: string) {}
+
+  async write(entry: LogEntry): Promise<void> {
+    try {
+      const lastSlash = Math.max(this._file.lastIndexOf("/"), this._file.lastIndexOf("\\"));
+      const dir = lastSlash > 0 ? this._file.slice(0, lastSlash) : ".";
+      await mkdir(dir, { recursive: true });
+      await appendFile(this._file, JSON.stringify(entry) + "\n");
+    } catch {
+      return;
+    }
+  }
+}

package/src/logger/channels/StackChannel.ts

@@ -0,0 +1,29 @@
+import type { LogChannel, LogEntry } from "../types.ts";
+
+/**
+ * Fans one entry out to several child channels at once — e.g. print to the
+ * console *and* persist to a daily file from a single log call.
+ *
+ * Writes are dispatched with `Promise.allSettled`, so one failing child channel
+ * never stops the others from receiving the entry.
+ *
+ * @category Channels
+ *
+ * @example
+ * ```ts
+ * // config/logging.ts — "stack" references other channels by name
+ * channels: {
+ *   stack: { driver: "stack", channels: ["console", "daily"] },
+ *   console: { driver: "console", format: "pretty" },
+ *   daily: { driver: "daily", path: "./storage/logs", days: 7 },
+ * }
+ * ```
+ */
+export class StackChannel implements LogChannel {
+  /** @param _channels - The resolved child channels to broadcast each entry to. */
+  constructor(private readonly _channels: LogChannel[]) {}
+
+  async write(entry: LogEntry): Promise<void> {
+    await Promise.allSettled(this._channels.map((ch) => ch.write(entry)));
+  }
+}

package/src/logger/config.ts

@@ -0,0 +1,90 @@
+import { deepMerge } from "../support/deepMerge.ts";
+import type {
+  LoggingConfigShape,
+  ChannelConfig,
+  ConsoleSinkConfig,
+  FileSinkConfig,
+} from "./types.ts";
+
+export type { LoggingConfigShape, ChannelConfig, ConsoleSinkConfig, FileSinkConfig };
+
+/** Where the always-on file trail writes, and how long a day's file survives. */
+export const DEFAULT_LOG_PATH = "./storage/logs";
+export const DEFAULT_LOG_RETENTION_DAYS = 14;
+
+/**
+ * Whether the file trail is on by default.
+ *
+ * Off under test: the path is relative to the working directory, so a suite
+ * that boots an app would otherwise grow a `storage/logs` directory wherever it
+ * happened to run — inside a package, inside a fixture, inside CI's checkout.
+ * A test that wants the trail asks for it explicitly.
+ */
+function _fileDefault(): FileSinkConfig {
+  const env = (Bun.env["APP_ENV"] ?? "").trim().toLowerCase();
+  if (env === "test" || env === "testing") return false;
+  return { path: DEFAULT_LOG_PATH, days: DEFAULT_LOG_RETENTION_DAYS };
+}
+
+const defaults: LoggingConfigShape = {
+  console: { format: "pretty" },
+  file: { path: DEFAULT_LOG_PATH, days: DEFAULT_LOG_RETENTION_DAYS },
+  // `app` deliberately names no channel: the two sinks above are the
+  // destination, and `channels` starts empty. Keeping the old
+  // `default: "console"` here would make the baseline console print twice.
+  default: "app",
+  channels: {},
+};
+
+/**
+ * Build a {@link LoggingConfigShape} with framework defaults applied.
+ *
+ * Out of the box every entry goes two places: the terminal, and a date-rotated
+ * file under `./storage/logs` kept for 14 days. Both are on by default and
+ * independent of each other — you can silence the terminal without losing the
+ * trail, which is the entire point of having one.
+ *
+ * Named `channels` are *extra* destinations layered on top, for routing a
+ * subsystem somewhere specific. Because `channels` is a name-keyed map,
+ * anything you add is merged in rather than replacing the map.
+ *
+ * @param options - Partial overrides deep-merged over the defaults.
+ * @returns The resolved, fully-populated logging config.
+ * @category Configuration
+ *
+ * @example
+ * ```ts
+ * // config/logging.ts — the defaults, spelled out
+ * import { LoggingConfig } from "@zerotal/core/logger";
+ *
+ * export default LoggingConfig();
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Quiet terminal, full trail on disk, a month of history
+ * export default LoggingConfig({
+ *   console: { level: "warn" },
+ *   file: { days: 30 },
+ * });
+ * ```
+ *
+ * @example
+ * ```ts
+ * // No files at all — containers that ship stdout to a collector
+ * export default LoggingConfig({ file: false });
+ * ```
+ */
+export function LoggingConfig(options: Partial<LoggingConfigShape> = {}): LoggingConfigShape {
+  const merged = deepMerge({ ...defaults, file: _fileDefault() }, options);
+  // `deepMerge` merges an object over `false`, so an explicit switch-off — and
+  // an explicit switch-*on* under test — is taken verbatim rather than being
+  // overridden by the default.
+  if (options.console === false) merged.console = false;
+  if (options.file === false) merged.file = false;
+  if (options.file !== undefined && options.file !== false) merged.file = options.file;
+  return merged;
+}
+
+// The `logging` config namespace is registered directly on core's ConfigRegistry
+// (see src/config/registry.ts) since the logger ships as part of core.

package/src/logger/format.ts

@@ -0,0 +1,96 @@
+/**
+ * How a log entry's context is written for a human reader.
+ *
+ * `JSON.stringify` is the right answer for a collector and the wrong one for a
+ * terminal: it escapes every backslash, so a Windows path arrives as
+ * `"C:\\Projects\\app"`, and it spends braces and quotes on structure the reader
+ * can already see. These helpers render the same data as `key=value` pairs with
+ * strings left literal.
+ */
+
+/**
+ * A value as the string a person should see.
+ *
+ * Strings pass through untouched — the whole point, since a path or a URL is
+ * already in its readable form. Everything else gets the shortest faithful
+ * rendering, falling back to JSON for objects and arrays.
+ *
+ * @example
+ * displayValue("C:\\app"); // "C:\app"  (not "C:\\\\app")
+ * displayValue({ a: 1 });  // '{"a":1}'
+ */
+export function displayValue(value: unknown): string {
+  if (value === null) return "null";
+  if (value === undefined) return "";
+  if (typeof value === "string") return value;
+  if (typeof value === "number" || typeof value === "boolean" || typeof value === "bigint") {
+    return String(value);
+  }
+  if (value instanceof Date) return value.toISOString();
+  if (value instanceof Error) return value.message;
+  try {
+    return JSON.stringify(value) ?? String(value);
+  } catch {
+    // Circular, or a toJSON that throws — a readable placeholder beats a crash
+    // inside logging.
+    return String(value);
+  }
+}
+
+/**
+ * Render a context bag as ` key=value` pairs for a terminal line.
+ *
+ * A value containing whitespace is quoted so the pairs stay separable by eye;
+ * nothing else is escaped, which keeps `C:\Program Files\app` legible where a
+ * JSON rendering would double every separator. Keys are dimmed when `dim` is
+ * supplied, so they recede behind the values that carry the information.
+ *
+ * @param context Structured context from a {@link LogEntry}.
+ * @param dim     ANSI dim escape, or "" to render without colour.
+ * @param reset   ANSI reset escape, paired with `dim`.
+ * @returns The rendered pairs, each preceded by a space; "" when there is nothing.
+ *
+ * @example
+ * formatContext({ port: 3000, dir: "C:\\app" }, "", "");
+ * // " port=3000 dir=C:\app"
+ */
+export function formatContext(
+  context: Record<string, unknown>,
+  dim = "\x1b[2m",
+  reset = "\x1b[0m",
+): string {
+  return formatPairs(context, dim, reset)
+    .map((pair) => ` ${pair}`)
+    .join("");
+}
+
+/**
+ * The same pairs as {@link formatContext}, one string each and unprefixed, so a
+ * caller can lay them out itself — wrapping them onto continuation lines when
+ * they would otherwise run off the terminal.
+ *
+ * @example
+ * formatPairs({ port: 3000, env: "web" }, "", ""); // ["port=3000", "env=web"]
+ */
+export function formatPairs(
+  context: Record<string, unknown>,
+  dim = "\x1b[2m",
+  reset = "\x1b[0m",
+): string[] {
+  return Object.entries(context).map(
+    ([key, value]) => `${dim}${key}=${reset}${_quoted(displayValue(value))}`,
+  );
+}
+
+/** Printable width of `text`, ignoring ANSI colour escapes (which take no space). */
+export function visibleWidth(text: string): number {
+  // eslint-disable-next-line no-control-regex
+  return text.replace(/\x1b\[[0-9;]*m/g, "").length;
+}
+
+/** Quote only when whitespace would otherwise run two pairs together. */
+function _quoted(text: string): string {
+  if (text === "") return '""';
+  if (!/\s/.test(text)) return text;
+  return `"${text.replace(/"/g, '\\"')}"`;
+}

package/src/logger/frameworkLog.ts

@@ -0,0 +1,93 @@
+/**
+ * The logger framework internals use, so their output goes wherever the app's
+ * logging config sends it instead of straight to the terminal.
+ *
+ * Framework code runs at moments application code never does — during boot,
+ * inside a CLI command with no application, in a package used standalone — so
+ * it cannot reach for the `Log` facade, which throws when the container has no
+ * logger. This resolves the real logger when there is one and formats to the
+ * console identically when there is not, so a line looks the same either side
+ * of boot.
+ */
+import os from "node:os";
+import { tryCurrentApp } from "../application/currentApp.ts";
+import { ConsoleChannel } from "./channels/ConsoleChannel.ts";
+import type { BoundLogger, LogEntry, LogLevel } from "./types.ts";
+import type { LogManager } from "./LogManager.ts";
+
+/** Pre-boot output goes through the same renderer, so the format never changes. */
+const _fallbackChannel = new ConsoleChannel("pretty");
+
+let _hostname: string | undefined;
+
+/**
+ * A logger tagged with the subsystem it belongs to.
+ *
+ * Resolve it per call rather than caching: a module-level logger would capture
+ * whichever application existed at import time, which in tests is the previous
+ * one and in a CLI is none at all.
+ *
+ * @param scope - Subsystem name, rendered as `[FLOW]` by the console channel.
+ *
+ * @example
+ * ```ts
+ * frameworkLog("flow").info("Compiled 4 page(s)", { ms: 76 });
+ * ```
+ *
+ * @internal
+ */
+export function frameworkLog(scope: string): BoundLogger {
+  const manager = _tryManager();
+  if (manager) return manager.scope(scope);
+
+  const emit =
+    (level: LogLevel) =>
+    (message: string, context?: Record<string, unknown>, err?: unknown): void => {
+      _fallbackChannel.write(_entry(level, scope, message, context, err)).catch(() => {
+        // Logging must never throw into the code that called it.
+      });
+    };
+
+  return {
+    debug: emit("debug"),
+    info: emit("info"),
+    warn: emit("warn"),
+    error: emit("error"),
+    fatal: emit("fatal"),
+    table: (message, rows, level = "info"): void => {
+      const context = Array.isArray(rows) ? { rows } : (rows as Record<string, unknown>);
+      const entry = { ..._entry(level, scope, message, context), display: "table" as const };
+      _fallbackChannel.write(entry).catch(() => {});
+    },
+  };
+}
+
+/** The container's logger, or undefined when there is no application or no binding. */
+function _tryManager(): LogManager | undefined {
+  return tryCurrentApp()?.container.tryMake("log") as LogManager | undefined;
+}
+
+function _entry(
+  level: LogLevel,
+  scope: string,
+  message: string,
+  context?: Record<string, unknown>,
+  err?: unknown,
+): LogEntry {
+  _hostname ??= os.hostname();
+  const entry: LogEntry = {
+    level,
+    channel: "console",
+    scope,
+    message,
+    timestamp: new Date().toISOString(),
+    hostname: _hostname,
+    pid: process.pid,
+    ...(context && Object.keys(context).length > 0 ? { context } : {}),
+  };
+  if (err !== undefined) {
+    entry.error = err instanceof Error ? err.message : String(err);
+    if (err instanceof Error && err.stack) entry.stack = err.stack;
+  }
+  return entry;
+}

package/src/logger/index.ts

@@ -0,0 +1,68 @@
+/**
+ * Structured, channel-based logging for Zerotal applications.
+ *
+ * A single {@link LogManager} owns a set of named {@link LogChannel | channels}
+ * (console, single file, date-rotated `daily` files, `null`, or a `stack` that
+ * fans out to several at once) and routes every {@link LogEntry} to the channel
+ * you select. Entries are enriched automatically with hostname, pid, app/env,
+ * and the active request id, and each channel has its own minimum
+ * {@link LogLevel}. Reach the container-bound manager through the {@link Log}
+ * facade; configure it with {@link LoggingConfig}.
+ *
+ * @example
+ * ```ts
+ * import { Log } from "@zerotal/core/logger";
+ *
+ * // Log at any of the five levels on the default channel.
+ * Log.info("User signed in", { userId: 42 });
+ * Log.error("Payment failed", { orderId: 99 }, err);
+ *
+ * // Bind shared context, or target a specific channel.
+ * Log.withContext({ requestId: "abc" }).warn("Retrying");
+ * Log.channel("daily").info("Written to today's file");
+ * ```
+ *
+ * @example
+ * ```ts
+ * // config/logging.ts — a "stack" that writes to both console and daily files.
+ * import { LoggingConfig } from "@zerotal/core/logger";
+ *
+ * export default LoggingConfig({
+ *   default: "stack",
+ *   channels: {
+ *     stack: { driver: "stack", channels: ["console", "daily"] },
+ *     console: { driver: "console", format: "pretty" },
+ *     daily: { driver: "daily", path: "./storage/logs", days: 14, level: "info" },
+ *   },
+ * });
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+export { Log } from "./Log.ts";
+export { LogManager } from "./LogManager.ts";
+export { frameworkLog } from "./frameworkLog.ts";
+export { LogProvider } from "../provider/LogProvider.ts";
+export { LoggingConfig } from "./config.ts";
+
+export { NullChannel } from "./channels/NullChannel.ts";
+export { StackChannel } from "./channels/StackChannel.ts";
+export { ConsoleChannel } from "./channels/ConsoleChannel.ts";
+export { SingleChannel } from "./channels/SingleChannel.ts";
+export { DailyChannel } from "./channels/DailyChannel.ts";
+
+export { LoggerMiddleware } from "./LoggerMiddleware.ts";
+export type { LoggerOptions } from "./LoggerMiddleware.ts";
+
+export { renderTable } from "./renderTable.ts";
+export type { TableData } from "./renderTable.ts";
+
+export type {
+  LogLevel,
+  LogEntry,
+  LogChannel,
+  BoundLogger,
+  ChannelConfig,
+  LoggingConfigShape,
+} from "./types.ts";

package/src/logger/renderTable.ts

@@ -0,0 +1,111 @@
+/**
+ * Box-drawn tables for terminal log output.
+ *
+ * A structured entry is easy to write and hard to read: past three or four keys
+ * an inline JSON blob is a wall the eye slides off. The same data in columns is
+ * scannable, and lining values up makes an odd one out visible without reading
+ * every key.
+ */
+
+import { displayValue } from "./format.ts";
+
+/** Either one object rendered as key/value rows, or a list rendered as columns. */
+export type TableData = Record<string, unknown> | ReadonlyArray<Record<string, unknown>>;
+
+const DIM = "\x1b[2m";
+const RESET = "\x1b[0m";
+
+/** Widest a single cell may render before it is truncated. */
+const MAX_CELL = 60;
+
+/**
+ * Render `data` as the lines of a box-drawn table, without a trailing newline.
+ *
+ * An array of objects becomes a column per key, in the order the first row
+ * introduces them, with a header. A single object becomes two columns of
+ * key and value. Numeric columns are right-aligned so digits line up.
+ *
+ * @param data   Rows to render.
+ * @param indent Spaces before each line, to sit the table under its message.
+ * @returns One string per line; empty when there is nothing to show.
+ *
+ * @example
+ * ```ts
+ * renderTable([{ page: "home", ms: 12 }, { page: "about", ms: 4 }]).join("\n");
+ * ```
+ */
+export function renderTable(data: TableData, indent = 2): string[] {
+  const { headers, rows } = _shape(data);
+  if (rows.length === 0) return [];
+
+  const widths = headers.map((header, column) =>
+    Math.max(_width(header), ...rows.map((row) => _width(row[column] ?? ""))),
+  );
+
+  // A column is numeric only if every cell in it is, so a "—" placeholder or a
+  // stray label does not silently right-align a column of text.
+  const numeric = headers.map((_, column) => rows.every((row) => _isNumeric(row[column] ?? "")));
+
+  const pad = " ".repeat(indent);
+  const rule = (left: string, mid: string, right: string): string =>
+    `${pad}${DIM}${left}${widths.map((w) => "─".repeat(w + 2)).join(mid)}${right}${RESET}`;
+
+  const line = (cells: readonly string[]): string => {
+    const body = cells
+      .map((cell, column) => ` ${_fit(cell, widths[column]!, numeric[column]!)} `)
+      .join(`${DIM}│${RESET}`);
+    return `${pad}${DIM}│${RESET}${body}${DIM}│${RESET}`;
+  };
+
+  const out = [rule("┌", "┬", "┐")];
+  if (headers.some((header) => header !== "")) {
+    out.push(line(headers), rule("├", "┼", "┤"));
+  }
+  for (const row of rows) out.push(line(headers.map((_, column) => row[column] ?? "")));
+  out.push(rule("└", "┴", "┘"));
+  return out;
+}
+
+// ── Private ──────────────────────────────────────────────────────────────────
+
+/** Normalise either input shape into a header row plus string cells. */
+function _shape(data: TableData): { headers: string[]; rows: string[][] } {
+  if (Array.isArray(data)) {
+    // Union of every row's keys, first-seen order — a row missing a key gets a
+    // blank cell rather than shifting the table.
+    const headers: string[] = [];
+    for (const row of data) {
+      for (const key of Object.keys(row)) if (!headers.includes(key)) headers.push(key);
+    }
+    return {
+      headers,
+      rows: data.map((row) => headers.map((key) => displayValue(row[key]))),
+    };
+  }
+
+  const entries = Object.entries(data);
+  // No header on a key/value table: "key | value" is a caption for something the
+  // reader can already see.
+  return { headers: ["", ""], rows: entries.map(([key, value]) => [key, displayValue(value)]) };
+}
+
+function _isNumeric(cell: string): boolean {
+  return cell !== "" && !Number.isNaN(Number(cell));
+}
+
+/** Visible width, ignoring any colour escapes a caller pre-formatted in. */
+function _width(cell: string): number {
+  return Math.min(_strip(cell).length, MAX_CELL);
+}
+
+function _strip(cell: string): string {
+  // eslint-disable-next-line no-control-regex
+  return cell.replace(/\x1b\[[0-9;]*m/g, "");
+}
+
+/** Truncate to `width`, then pad to it — right-aligned for numbers. */
+function _fit(cell: string, width: number, right: boolean): string {
+  const visible = _strip(cell);
+  const text = visible.length > width ? `${visible.slice(0, Math.max(0, width - 1))}…` : visible;
+  return right ? text.padStart(width) : text.padEnd(width);
+}