@zerotal/core 1.0.0

package/src/logger/types.ts

@@ -0,0 +1,212 @@
+import type { TableData } from "./renderTable.ts";
+
+export type { TableData };
+
+/**
+ * Severity of a log entry, from lowest to highest: `debug`, `info`, `warn`,
+ * `error`, `fatal`. A channel's configured minimum level suppresses any entry
+ * below it.
+ *
+ * @category Logging
+ */
+export type LogLevel = "debug" | "info" | "warn" | "error" | "fatal";
+
+/**
+ * Numeric rank of each {@link LogLevel}, used to compare an entry's level
+ * against a channel's minimum. Higher means more severe.
+ *
+ * @internal
+ */
+export const LEVEL_ORDER: Record<LogLevel, number> = {
+  debug: 0,
+  info: 1,
+  warn: 2,
+  error: 3,
+  fatal: 4,
+};
+
+/**
+ * A single fully-enriched log record as it is handed to a {@link LogChannel}.
+ *
+ * The {@link LogManager} populates `timestamp`, `hostname`, and `pid` on every
+ * entry; `app`, `env`, `requestId`, `context`, `error`, and `stack` appear only
+ * when the corresponding data is available.
+ *
+ * @category Logging
+ */
+export interface LogEntry {
+  /** Severity the entry was emitted at. */
+  level: LogLevel;
+  /** Name of the channel the entry was routed to. */
+  channel: string;
+  /**
+   * Subsystem that emitted the entry — `app`, `flow`, `inertia`, `queue`.
+   * Rendered as a `[SCOPE]` tag by the console channel and kept as a field by
+   * the file/JSON ones, so a log file can be filtered by source.
+   */
+  scope?: string | undefined;
+  /** Human-readable log message. */
+  message: string;
+  /** ISO-8601 timestamp of when the entry was created. */
+  timestamp: string;
+  /** Application name, from `app.name` config, when configured. */
+  app?: string | undefined;
+  /** Application environment, from `app.env` config, when configured. */
+  env?: string | undefined;
+  /** Host machine name (`os.hostname()`). */
+  hostname: string;
+  /** Process id of the emitting process. */
+  pid: number;
+  /** Id of the active HTTP request, when logging inside a request context. */
+  requestId?: string | undefined;
+  /** Arbitrary structured context passed at the call site (omitted when empty). */
+  context?: Record<string, unknown> | undefined;
+  /**
+   * How a human-facing channel should present {@link LogEntry.context}. `"table"`
+   * asks the console for box-drawn columns; file and JSON channels ignore it and
+   * keep writing the same structured data. Purely a rendering hint — never a
+   * change to what the entry contains.
+   */
+  display?: "table" | undefined;
+  /** Error message, when an error/value was passed to the log call. */
+  error?: string | undefined;
+  /** Stack trace, when the passed value was an `Error` with a stack. */
+  stack?: string | undefined;
+}
+
+/**
+ * Contract every log destination implements: a single async `write` that
+ * persists or displays one {@link LogEntry}. Implementations include
+ * {@link ConsoleChannel}, {@link SingleChannel}, {@link DailyChannel},
+ * {@link StackChannel}, and {@link NullChannel}. Implement this to add a custom
+ * destination.
+ *
+ * @category Channels
+ */
+export interface LogChannel {
+  write(entry: LogEntry): Promise<void>;
+}
+
+/**
+ * A logger pinned to a specific channel and/or a fixed context bag.
+ *
+ * Returned by {@link LogManager.channel} and {@link LogManager.withContext}
+ * (and implemented by {@link LogManager} itself for the default channel). Each
+ * level method takes a `message`, optional structured `context`, and an
+ * optional error/value whose message and stack are captured onto the entry.
+ *
+ * @category Context
+ */
+export interface BoundLogger {
+  debug(message: string, context?: Record<string, unknown>, err?: unknown): void;
+  info(message: string, context?: Record<string, unknown>, err?: unknown): void;
+  warn(message: string, context?: Record<string, unknown>, err?: unknown): void;
+  error(message: string, context?: Record<string, unknown>, err?: unknown): void;
+  fatal(message: string, context?: Record<string, unknown>, err?: unknown): void;
+  /**
+   * Log `message` with `rows` attached, asking human-facing channels to render
+   * them as a table. The data is ordinary context, so a JSON or file channel
+   * records exactly what the other level methods would have recorded.
+   *
+   * @param rows  One object (key/value rows) or a list of objects (columns).
+   * @param level Severity to emit at. Defaults to `info`.
+   */
+  table(message: string, rows: TableData, level?: LogLevel): void;
+}
+
+/**
+ * Discriminated union describing one channel's configuration, keyed by
+ * `driver`. Each variant maps to a concrete {@link LogChannel}:
+ *
+ * - `console` — {@link ConsoleChannel}; `format` is `"pretty"` (default) or `"json"`.
+ * - `single` — {@link SingleChannel}; appends every entry to `path`.
+ * - `daily` — {@link DailyChannel}; date-rotated files under `path`, pruned after `days`.
+ * - `stack` — {@link StackChannel}; fans out to the named `channels`.
+ * - `null` — {@link NullChannel}; discards everything.
+ *
+ * @category Channels
+ */
+export type ChannelConfig =
+  | { driver: "console"; level?: LogLevel; format?: "json" | "pretty" }
+  | { driver: "single"; level?: LogLevel; path: string }
+  | { driver: "daily"; level?: LogLevel; path: string; days?: number }
+  | { driver: "stack"; level?: LogLevel; channels: string[] }
+  | { driver: "null" };
+
+/**
+ * The always-on terminal sink. Every entry is printed unless this is `false`.
+ *
+ * Console output is a property of the logger rather than a channel you route
+ * to, so pointing `default` at a file channel no longer costs you the terminal.
+ *
+ * @category Configuration
+ */
+export type ConsoleSinkConfig =
+  | false
+  | {
+      /** Minimum level printed. Defaults to `debug`. */
+      level?: LogLevel;
+      /** `"pretty"` (default) or `"json"`. */
+      format?: "json" | "pretty";
+    };
+
+/**
+ * The always-on file trail. Every entry is appended to a date-rotated file
+ * unless this is `false`.
+ *
+ * This is the record you read when the terminal is gone: after the process
+ * exited, after the scrollback rolled over, on a machine you were not watching.
+ * It is deliberately independent of {@link ConsoleSinkConfig} — quietening the
+ * terminal must not cost you the trail.
+ *
+ * @category Configuration
+ */
+export type FileSinkConfig =
+  | false
+  | {
+      /** Directory holding the per-day files. Defaults to `./storage/logs`. */
+      path?: string;
+      /** Days a file survives before being pruned. Defaults to `14`. */
+      days?: number;
+      /**
+       * Minimum level written. Defaults to `debug` — the trail records
+       * everything, and the console threshold controls what you actually watch.
+       */
+      level?: LogLevel;
+    };
+
+/**
+ * Full shape of the `logging` config namespace, as produced by
+ * {@link LoggingConfig}. Defines the two always-on sinks, the channel map,
+ * which channel is the default, and framework logging thresholds.
+ *
+ * @category Configuration
+ */
+export interface LoggingConfigShape {
+  /**
+   * The terminal sink, on unless `false`. See {@link ConsoleSinkConfig}.
+   */
+  console?: ConsoleSinkConfig;
+  /**
+   * The durable file trail, on unless `false`. See {@link FileSinkConfig}.
+   */
+  file?: FileSinkConfig;
+  /** Name of the channel used by unqualified `Log.*` calls. */
+  default: string;
+  /**
+   * Named channel definitions; see {@link ChannelConfig}.
+   *
+   * Channels are *additional* destinations, not replacements — an entry routed
+   * to one still reaches the console and the file trail. A channel that already
+   * covers a sink (a `console` driver, or `single`/`daily`) suppresses that
+   * baseline for its own entries, so nothing is written twice.
+   */
+  channels: Record<string, ChannelConfig>;
+  /** Threshold, in ms, above which ORM queries are logged as slow (default 1000). */
+  slowQueryMs?: number;
+  /**
+   * Log every HTTP request (method, path, status, duration) via `LoggerMiddleware`.
+   * On by default; set `false` to silence the per-request access log.
+   */
+  requests?: boolean;
+}

package/src/macros/config.macro.ts

@@ -0,0 +1,50 @@
+/**
+ * A Bun build-time macro that bakes a config directory into a static object,
+ * for embedding configuration into a compiled binary (`bun build --compile`).
+ */
+import { join } from "node:path";
+
+/**
+ * Bun macro — scan a config directory and return all configs as a static object.
+ *
+ * ⚠️  USE ONLY WITH `bun build --compile`.
+ * This macro is evaluated at bundle time and is primarily intended for baking
+ * config values into a self-contained binary. Do NOT use it in zt.ts for
+ * development or test workflows — it fails on Windows when the argument
+ * contains a runtime expression like `${process.cwd()}`.
+ *
+ * For development (and for all apps not compiled to a binary), import configs
+ * directly instead:
+ *
+ * ```ts
+ * // zt.ts — preferred approach (works everywhere)
+ * import appConfig      from './config/app.ts';
+ * import databaseConfig from './config/database.ts';
+ * app.useConfig({ app: appConfig, database: databaseConfig, ... });
+ * ```
+ *
+ * For compiled binaries only:
+ *
+ * ```ts
+ * import { loadConfigsSync } from '@zerotal/core/macros/config' with { type: 'macro' };
+ * const configs = loadConfigsSync('/absolute/path/to/config');
+ * app.useConfig(configs);
+ * ```
+ *
+ * Note: config files that read `Bun.env` capture their values from the
+ * environment at macro-evaluation time. For bun build --compile this is the
+ * CI/CD environment — the same intended behaviour as any immutable artifact.
+ */
+export function loadConfigsSync(configDir: string): Record<string, Record<string, unknown>> {
+  const glob = new Bun.Glob("*.ts");
+  const result: Record<string, Record<string, unknown>> = {};
+
+  for (const file of glob.scanSync({ cwd: configDir })) {
+    if (file === "index.ts") continue;
+    const key = file.replace(/\.ts$/, "");
+    const loadedModule = require(join(configDir, file)) as Record<string, unknown>;
+    result[key] = (loadedModule["default"] ?? loadedModule) as Record<string, unknown>;
+  }
+
+  return result;
+}

package/src/metrics/HttpMetrics.ts

@@ -0,0 +1,114 @@
+/**
+ * In-process HTTP request metrics — request counts by status class, latency
+ * (avg / p95 / max), and short-window throughput. Recorded once per request by
+ * the server and surfaced on the admin Health page. Best-effort and memory-safe
+ * (a bounded rolling window), reset on process restart.
+ */
+
+interface Sample {
+  t: number;
+  status: number;
+  ms: number;
+}
+
+const WINDOW_MS = 60 * 60 * 1000; // keep ~1h of samples for percentiles/rates
+const MAX_SAMPLES = 10_000; // hard cap regardless of window
+const FIVE_MINUTES_MS = 5 * 60 * 1000; // the recent window for p95, error rate, and throughput
+
+const _samples: Sample[] = [];
+let _total = 0;
+let _inFlight = 0;
+let _2xx = 0,
+  _3xx = 0,
+  _4xx = 0,
+  _5xx = 0;
+let _sumMs = 0,
+  _maxMs = 0;
+
+/** Mark a request as started — increments the in-flight (currently-processing) gauge. */
+export function beginHttp(): void {
+  _inFlight++;
+}
+
+/** Mark a request as finished — decrements the in-flight gauge (floored at 0). */
+export function endHttp(): void {
+  if (_inFlight > 0) _inFlight--;
+}
+
+/** Record one completed request. Called by the server for every pipeline response. */
+export function recordHttp(status: number, ms: number): void {
+  _total++;
+  _sumMs += ms;
+  if (ms > _maxMs) _maxMs = ms;
+  if (status >= 500) _5xx++;
+  else if (status >= 400) _4xx++;
+  else if (status >= 300) _3xx++;
+  else _2xx++;
+
+  const now = Date.now();
+  _samples.push({ t: now, status, ms });
+  const cutoff = now - WINDOW_MS;
+  while (_samples.length && _samples[0]!.t < cutoff) _samples.shift();
+  if (_samples.length > MAX_SAMPLES) _samples.splice(0, _samples.length - MAX_SAMPLES);
+}
+
+/** A point-in-time view of the request metrics, as shown on the Health page. */
+export interface HttpMetricsSnapshot {
+  /** Requests since boot. */
+  total: number;
+  /** Requests currently being processed (in-flight concurrency). */
+  inFlight: number;
+  /** 2xx + 3xx responses. */
+  success: number;
+  /** 4xx responses. */
+  clientErrors: number;
+  /** 5xx responses. */
+  serverErrors: number;
+  /** Success percentage (0–100). */
+  successRate: number;
+  /** Mean response time since boot, ms. */
+  avgMs: number;
+  /** 95th-percentile response time over the last 5 minutes, ms. */
+  p95Ms: number;
+  /** Slowest response since boot, ms. */
+  maxMs: number;
+  /** Requests per minute over the last 5 minutes. */
+  perMinute: number;
+  /** Last-5-minute totals. */
+  last5m: { total: number; errors: number };
+}
+
+/** Snapshot the current metrics. */
+export function httpMetrics(): HttpMetricsSnapshot {
+  const now = Date.now();
+  const recentSamples = _samples.filter((sample) => sample.t >= now - FIVE_MINUTES_MS);
+  const sortedLatencies = recentSamples
+    .map((sample) => sample.ms)
+    .sort((first, second) => first - second);
+  const p95 = sortedLatencies.length
+    ? sortedLatencies[
+        Math.min(sortedLatencies.length - 1, Math.floor(sortedLatencies.length * 0.95))
+      ]!
+    : 0;
+  const errors = recentSamples.filter((sample) => sample.status >= 400).length;
+  const success = _2xx + _3xx;
+  return {
+    total: _total,
+    inFlight: _inFlight,
+    success,
+    clientErrors: _4xx,
+    serverErrors: _5xx,
+    successRate: _total ? Math.round((success / _total) * 100) : 100,
+    avgMs: _total ? Math.round(_sumMs / _total) : 0,
+    p95Ms: Math.round(p95),
+    maxMs: Math.round(_maxMs),
+    perMinute: Math.round(recentSamples.length / 5),
+    last5m: { total: recentSamples.length, errors },
+  };
+}
+
+/** @internal — test reset. */
+export function _resetHttpMetrics(): void {
+  _samples.length = 0;
+  _total = _inFlight = _2xx = _3xx = _4xx = _5xx = _sumMs = _maxMs = 0;
+}

package/src/metrics/index.ts

@@ -0,0 +1,18 @@
+/**
+ * In-process HTTP request metrics (the `@zerotal/core/metrics` subpath) —
+ * request counts by status class, latency (avg / p95 / max), and short-window
+ * throughput. Recorded once per request by the server and surfaced on the admin
+ * Health page; best-effort, memory-safe, and reset on process restart.
+ *
+ * @example
+ * ```ts
+ * import { httpMetrics } from "@zerotal/core/metrics";
+ *
+ * const snapshot = httpMetrics();
+ * console.log(snapshot.total, snapshot.successRate, snapshot.p95Ms);
+ * ```
+ *
+ * @packageDocumentation
+ */
+export { recordHttp, beginHttp, endHttp, httpMetrics } from "./HttpMetrics.ts";
+export type { HttpMetricsSnapshot } from "./HttpMetrics.ts";

package/src/middleware/BaseMiddleware.ts

@@ -0,0 +1,72 @@
+/**
+ * The base class every Zerotal middleware extends, providing the `Pipe`
+ * contract plus the static `with()` helper that bakes options into a
+ * zero-argument middleware class usable directly in `app.use([...])`.
+ */
+import type { Pipe, NextFn } from "../pipeline/types.ts";
+import type { HttpContext } from "../pipeline/HttpContext.ts";
+// Canonical implementation now lives in support/deepMerge.ts; re-exported here so existing
+// `import { deepMerge } from "./BaseMiddleware.ts"` call sites keep working.
+import { deepMerge } from "../support/deepMerge.ts";
+
+export { deepMerge };
+
+/**
+ * Base class for all Zerotal middlewares.
+ *
+ * Subclasses must declare `protected options` with their default values.
+ * Use `MyMiddleware.with({ ... })` to produce a zero-arg constructor with
+ * options deep-merged on top of the subclass defaults.
+ *
+ * @example
+ * class MyMiddleware extends BaseMiddleware<MyOptions> {
+ *   protected options: MyOptions = { timeout: 5000 };
+ *
+ *   async handle(ctx: HttpContext, next: NextFn): Promise<Response | void> {
+ *     // ...read/write ctx.* ...
+ *     return next();
+ *   }
+ * }
+ *
+ * app.use([MyMiddleware.with({ timeout: 1000 })]);
+ */
+export abstract class BaseMiddleware<O extends object = object> implements Pipe<HttpContext> {
+  // Explicit constructor so JSC's function-coverage counter attributes
+  // the super() call from concrete subclasses to this entry.
+  constructor() {}
+
+  /**
+   * Subclasses must declare this with their default option values.
+   * TypeScript enforces this at compile time — forgetting it is a type error.
+   */
+  protected abstract options: O;
+
+  /**
+   * Returns a zero-arg subclass with the given options deep-merged on top of
+   * the subclass defaults, usable directly in app.use([...]).
+   */
+  static with<
+    // 1. Constrain T to be a concrete class (not abstract) that extends BaseMiddleware
+    T extends new (...args: any[]) => BaseMiddleware<any>,
+    // 2. Dynamically infer the specific options type (U) from that concrete class
+    Opts = T extends new (...args: any[]) => BaseMiddleware<infer U> ? U : object,
+  >(this: T, options: Partial<Opts>): new () => InstanceType<T> {
+    const configured = class extends (this as any) {
+      constructor() {
+        super();
+        (this as any).options = deepMerge((this as any).options ?? {}, options);
+      }
+    };
+    // A class expression is anonymous, so a configured middleware used to appear
+    // as `""` everywhere a name is read — the pipeline listing, `route:list`,
+    // error messages. Carrying the base name across keeps a middleware
+    // identifiable after it has been configured.
+    Object.defineProperty(configured, "name", { value: this.name, configurable: true });
+    return configured as any;
+  }
+
+  abstract handle(ctx: HttpContext, next: NextFn): Promise<Response | void>;
+
+  afterResponse?(ctx: HttpContext): Promise<void>;
+  onError?(ctx: HttpContext, error: Error): Promise<void>;
+}

package/src/middleware/CorsMiddleware.ts

@@ -0,0 +1,152 @@
+/**
+ * CORS middleware: applies `Access-Control-*` headers to responses and answers
+ * preflight `OPTIONS` requests, configurable per-origin and via app config.
+ */
+import type { NextFn } from "../pipeline/types.ts";
+import type { HttpContext } from "../pipeline/HttpContext.ts";
+import { BaseMiddleware, deepMerge } from "./BaseMiddleware.ts";
+import { withHeaders } from "../http/withHeaders.ts";
+import { config } from "../helpers/config.ts";
+
+export interface CorsOptions {
+  /**
+   * Allowed origins. Default: `[]` — same-origin only, so nothing is shared until an app
+   * names what it means to share with.
+   *
+   * A **string** or **array** is matched exactly against the request's `Origin`, scheme
+   * and port included.
+   *
+   * `'*'` allows any origin. It cannot be combined with `credentials: true` (the browser
+   * rejects that pairing outright), and it means every page on the internet can read any
+   * response this middleware covers that is not separately credential-gated.
+   *
+   * A **function** receives the raw `Origin` header and returns whether to allow it. Match
+   * the whole origin, not a suffix: `o.endsWith('.example.com')` also matches
+   * `https://evil.example.com.attacker.test` and `http://x.example.com` — write
+   * `new URL(o).hostname.endsWith('.example.com') && o.startsWith('https://')`, or just
+   * list the origins.
+   */
+  origin?: string | string[] | ((origin: string) => boolean);
+  /** Allowed HTTP methods. Default: `['GET','POST','PUT','PATCH','DELETE','OPTIONS']`. */
+  methods?: string[];
+  /** Allowed request headers. Default: `['Content-Type','Authorization','X-Requested-With']`. */
+  allowedHeaders?: string[];
+  /** Headers the browser may expose to JS. Default: `[]`. */
+  exposedHeaders?: string[];
+  /** Allow cookies / auth headers in cross-origin requests. Default: `false`. */
+  credentials?: boolean;
+  /** Preflight cache duration in seconds. Default: `600`. */
+  maxAge?: number;
+}
+
+/**
+ * CORS middleware — adds Access-Control-* headers to every response and
+ * short-circuits HTTP OPTIONS preflight requests with 204.
+ *
+ * @example
+ * // Global (most common):
+ * app.use(new CorsMiddleware());
+ *
+ * // Restrict to specific origins (the usual case):
+ * app.use(CorsMiddleware.with({ origin: 'https://app.example.com', credentials: true }));
+ *
+ * // Dynamic per-origin check — compare the whole origin, never a suffix:
+ * app.use(CorsMiddleware.with({
+ *   origin: (o) => o.startsWith('https://') && new URL(o).hostname.endsWith('.example.com'),
+ * }));
+ */
+export class CorsMiddleware extends BaseMiddleware<CorsOptions> {
+  protected options: CorsOptions = {
+    origin: [],
+    methods: ["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"],
+    allowedHeaders: ["Content-Type", "Authorization", "X-Requested-With"],
+    exposedHeaders: [],
+    credentials: false,
+    maxAge: 600,
+  };
+
+  constructor(options: CorsOptions = {}) {
+    super();
+    // App-level defaults from config('app.cors') layer over the built-ins; explicit
+    // options (constructor arg or .with(...)) win over both.
+    this.options = deepMerge(this.options, config.safe("app.cors", {} as Partial<CorsOptions>));
+    this.options = deepMerge(this.options, options);
+  }
+
+  async handle(http: HttpContext, next: NextFn): Promise<Response | void> {
+    const requestOrigin = http.request.headers.get("Origin") ?? "";
+    const allowedOrigin = this._resolveOrigin(requestOrigin);
+
+    // Preflight: respond immediately without going deeper into the pipeline
+    if (http.request.method === "OPTIONS") {
+      return new Response(null, {
+        status: 204,
+        headers: this._buildHeaders(allowedOrigin, http),
+      });
+    }
+
+    const response = await next();
+
+    // Attach CORS headers to the actual response
+    if (response && allowedOrigin) {
+      return withHeaders(response, this._buildHeaders(allowedOrigin, http));
+    }
+  }
+
+  private _resolveOrigin(requestOrigin: string): string {
+    const origin = this.options.origin ?? [];
+    if (origin === "*") {
+      // `Access-Control-Allow-Origin: *` and `Allow-Credentials: true` is a combination
+      // browsers reject, so an app that sets both has a misconfiguration rather than a
+      // wildcard. Reflecting the caller's origin there would quietly turn it into
+      // "any origin, with cookies" — refuse instead.
+      if (this.options.credentials) return "";
+      return "*";
+    }
+    if (typeof origin === "function") {
+      return origin(requestOrigin) ? requestOrigin : "";
+    }
+    if (Array.isArray(origin)) {
+      return origin.includes(requestOrigin) ? requestOrigin : "";
+    }
+    return origin === requestOrigin ? requestOrigin : "";
+  }
+
+  private _buildHeaders(allowedOrigin: string, ctx: HttpContext): Record<string, string> {
+    if (!allowedOrigin) return {};
+
+    const methods = this.options.methods ?? ["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"];
+    const allowedHeaders = this.options.allowedHeaders ?? [
+      "Content-Type",
+      "Authorization",
+      "X-Requested-With",
+    ];
+    const exposedHeaders = this.options.exposedHeaders ?? [];
+    const credentials = this.options.credentials ?? false;
+    const maxAge = this.options.maxAge ?? 600;
+
+    const headers: Record<string, string> = {
+      "Access-Control-Allow-Origin": allowedOrigin,
+      "Access-Control-Allow-Methods": methods.join(", "),
+      "Access-Control-Allow-Headers": allowedHeaders.join(", "),
+      "Access-Control-Max-Age": String(maxAge),
+    };
+
+    if (credentials) {
+      headers["Access-Control-Allow-Credentials"] = "true";
+    }
+
+    if (exposedHeaders.length > 0) {
+      headers["Access-Control-Expose-Headers"] = exposedHeaders.join(", ");
+    }
+
+    // Vary by Origin for non-wildcard responses so shared caches don't serve
+    // one origin's CORS headers to another.
+    if (allowedOrigin !== "*") {
+      const existing = ctx.response?.headers.get("Vary") ?? "";
+      headers["Vary"] = existing ? `${existing}, Origin` : "Origin";
+    }
+
+    return headers;
+  }
+}