@zerotal/core 1.0.0

package/src/config/ConfigLoader.ts

@@ -0,0 +1,117 @@
+/**
+ * Synchronous loader for a `config/` directory: discovers each config file,
+ * exposes its values as a namespaced map, and collects optional per-file
+ * validators so configuration can be checked before the app boots.
+ */
+import path from "node:path";
+import { createRequire } from "node:module";
+import { frameworkLog } from "../logger/frameworkLog.ts";
+
+const requireModule = createRequire(import.meta.url);
+
+/** Namespace → config object map (filename without extension is the namespace). */
+export type ConfigMap = Record<string, Record<string, unknown>>;
+type Validator = (value: Record<string, unknown>) => void;
+
+/**
+ * A loaded set of config files, keyed by filename (`config/app.ts` → `app`). Pass `all()` (or the
+ * loader itself) to `Application.create({ config })` / `app.useConfig(...)`.
+ */
+export class ConfigLoader {
+  constructor(
+    private readonly _map: ConfigMap,
+    private readonly _validators: ReadonlyArray<{ ns: string; fn: Validator }> = [],
+  ) {}
+
+  /** The full namespace → config map. */
+  all(): ConfigMap {
+    return this._map;
+  }
+
+  /**
+   * Dot-path read, e.g. `get("database.url")`.
+   *
+   * @param key       Dot-notation path across the loaded namespaces.
+   * @param fallback  Value returned when the path is missing.
+   * @returns The stored value, or `fallback` when unset.
+   */
+  get<T = unknown>(key: string, fallback?: T): T {
+    let current: unknown = this._map;
+    for (const part of key.split(".")) {
+      if (current && typeof current === "object" && part in (current as Record<string, unknown>)) {
+        current = (current as Record<string, unknown>)[part];
+      } else {
+        return fallback as T;
+      }
+    }
+    return (current ?? fallback) as T;
+  }
+
+  /** Whether a value exists at the given dot-path. */
+  has(key: string): boolean {
+    return this.get(key, undefined as unknown) !== undefined;
+  }
+
+  /**
+   * Run each config file's optional `validate(config)` named export against its value, throwing on
+   * the first failure. Returns `this` for chaining. (Config files that read env at module load are
+   * already validated by the act of loading.)
+   *
+   * @returns `this`, so the call chains into `Application.create({ config })`.
+   * @throws Whatever a config file's `validate(config)` export throws on the first failure.
+   */
+  validate(): this {
+    for (const { ns: namespace, fn: validate } of this._validators) {
+      validate(this._map[namespace] ?? {});
+    }
+    return this;
+  }
+}
+
+/**
+ * Synchronously load every `*.ts` / `*.js` file in `dir` (default `./config`) into a namespace map
+ * keyed by filename. Safe to call at the top level of an entry script (`zerotal.ts`) — no `await`.
+ *
+ * Each file's **default export** is the config object; an optional named **`validate(config)`**
+ * export is collected and run by `ConfigLoader.validate()`.
+ *
+ * @param dir  Directory to scan, relative to `process.cwd()`. Defaults to `./config`.
+ * @returns A {@link ConfigLoader} over the discovered namespaces. A missing
+ * directory yields an empty loader rather than throwing.
+ *
+ * @example
+ * ```ts
+ * const config = configLoader("./config");
+ * config.validate();
+ * const app = Application.create({ config });   // or app.useConfig(config)
+ * ```
+ */
+export function configLoader(dir = "./config"): ConfigLoader {
+  const absoluteDirectory = path.resolve(process.cwd(), dir);
+  const map: ConfigMap = {};
+  const validators: Array<{ ns: string; fn: Validator }> = [];
+  try {
+    const glob = new Bun.Glob("*.{ts,js}");
+    for (const file of glob.scanSync({ cwd: absoluteDirectory, onlyFiles: true })) {
+      const namespace = file.replace(/\.(ts|js)$/, "");
+      try {
+        const loadedModule = requireModule(path.join(absoluteDirectory, file)) as Record<
+          string,
+          unknown
+        >;
+        const value = loadedModule["default"] ?? loadedModule;
+        if (value && typeof value === "object" && !Array.isArray(value)) {
+          map[namespace] = value as Record<string, unknown>;
+        }
+        if (typeof loadedModule["validate"] === "function") {
+          validators.push({ ns: namespace, fn: loadedModule["validate"] as Validator });
+        }
+      } catch (error) {
+        frameworkLog("config").error(`Config "${file}" failed to load`, { file }, error);
+      }
+    }
+  } catch {
+    // A missing config/ directory is fine — minimal apps may not have one.
+  }
+  return new ConfigLoader(map, validators);
+}

package/src/config/ConfigManager.ts

@@ -0,0 +1,169 @@
+/**
+ * The runtime configuration store: holds the merged config namespaces and
+ * serves dot-path reads/writes behind the `Config` facade and `config()` helper.
+ */
+import { ConfigError } from "../errors/ConfigError.ts";
+
+/**
+ * The runtime configuration store — holds every loaded config namespace and
+ * serves dot-path reads and writes.
+ *
+ * Populated from the `config/*.ts` files during `onBooting()` by a
+ * ServiceProvider, then bound in the container under `config`. Application code
+ * rarely touches this class directly; it reads through the `Config` facade or
+ * the `config()` helper, both of which delegate here.
+ *
+ * @example
+ * ```ts
+ * import { config } from "@zerotal/core";
+ * import { Config } from "@zerotal/core/facades";
+ *
+ * // Typed dot-path access (via the config() helper):
+ * const name = config("app.name");     // string
+ * const port = config("app.port");     // number
+ *
+ * // Or through the facade:
+ * const url = Config.get("app.url", "http://localhost:3000");
+ * ```
+ */
+export class ConfigManager {
+  private _data: Record<string, unknown>;
+  constructor() {
+    this._data = {};
+  }
+
+  // ── Loading ───────────────────────────────────────────────────────────
+
+  /**
+   * Merge a config namespace into the store, replacing any existing value under
+   * the same key. Called by ConfigProvider during `onBooting()`.
+   *
+   * @param namespace  Top-level namespace key (the config filename, e.g. `app`).
+   * @param values     The namespace's config object.
+   *
+   * @example
+   * ```ts
+   * config.load('app', { name: 'Zerotal', env: 'production' });
+   * config.load('database', { url: 'postgres://localhost/mydb' });
+   * ```
+   */
+  load(namespace: string, values: Record<string, unknown>): void {
+    this._data[namespace] = values;
+  }
+
+  // ── Access ────────────────────────────────────────────────────────────
+
+  /**
+   * Get a config value by dot-notation path, returning `fallback` when the path
+   * resolves to `null`/`undefined` or does not exist.
+   *
+   * @param path      Dot-notation path, e.g. `app.name`.
+   * @param fallback  Value returned when the path is missing.
+   * @returns The stored value, or `fallback` when unset.
+   *
+   * @example
+   * ```ts
+   * config.get('app.name')                      // 'Zerotal'
+   * config.get('database.connections.postgres') // { url: '...' }
+   * config.get('app.missing', 'default')        // 'default'
+   * ```
+   */
+  get<T = unknown>(path: string, fallback?: T): T {
+    const keys = path.split(".");
+    let current: unknown = this._data;
+
+    for (const key of keys) {
+      if (current == null || typeof current !== "object") {
+        return (fallback ?? undefined) as T;
+      }
+      current = (current as Record<string, unknown>)[key];
+    }
+
+    return (current ?? fallback ?? undefined) as T;
+  }
+
+  /**
+   * Get a config value, throwing when it is `null` or `undefined`. Use for
+   * required config that the app cannot start without.
+   *
+   * @param path  Dot-notation path, e.g. `app.key`.
+   * @returns The stored value (guaranteed present).
+   * @throws {ConfigError} When the path resolves to `undefined` or `null`.
+   *
+   * @example
+   * ```ts
+   * config.require('app.key') // throws if APP_KEY is not set
+   * ```
+   */
+  require<T = unknown>(path: string): T {
+    const value = this.get<T>(path);
+    if (value === undefined || value === null) {
+      throw new ConfigError(
+        `Required config value "${path}" is not set. ` +
+          `Check your .env file and config/${path.split(".")[0]}.ts.`,
+      );
+    }
+    return value;
+  }
+
+  /**
+   * Set a config value at a dot-path at runtime, creating intermediate objects
+   * as needed. Intended for tests or dynamic overrides; in production prefer
+   * loading config files via {@link ConfigManager.load}.
+   *
+   * @param path   Dot-notation path to write, e.g. `app.debug`.
+   * @param value  The value to store.
+   */
+  set(path: string, value: unknown): void {
+    const keys = path.split(".");
+    // `config.set("__proto__.isAdmin", true)` used to walk onto Object.prototype and pollute
+    // every object in the process. deepMerge already guards exactly these keys
+    // (support/deepMerge.ts _UNSAFE_KEYS); ConfigManager did not.
+    if (keys.some((key) => _UNSAFE_CONFIG_KEYS.has(key))) {
+      throw new ConfigError(
+        `Refusing to set config path "${path}": it walks through a prototype key ` +
+          `(__proto__, constructor, prototype), which would mutate Object.prototype.`,
+      );
+    }
+    let current = this._data;
+
+    for (let index = 0; index < keys.length - 1; index++) {
+      const key = keys[index]!;
+      if (typeof current[key] !== "object" || current[key] == null) {
+        current[key] = {};
+      }
+      current = current[key] as Record<string, unknown>;
+    }
+
+    current[keys[keys.length - 1]!] = value;
+  }
+
+  /**
+   * Check whether a config path has a value set (i.e. `get(path)` is not
+   * `undefined`).
+   *
+   * @param path  Dot-notation path to test.
+   * @returns `true` when a value exists at the path.
+   */
+  has(path: string): boolean {
+    return this.get(path) !== undefined;
+  }
+
+  /**
+   * Return a shallow copy of all loaded config namespaces. Useful for
+   * debugging.
+   *
+   * @returns A new object mapping each namespace to its config value. The copy
+   * is shallow — nested namespace objects are shared, not cloned.
+   */
+  all(): Record<string, unknown> {
+    return { ...this._data };
+  }
+}
+
+/**
+ * Keys that must never appear in a `set()` path. Writing through any of them reaches
+ * `Object.prototype` and pollutes every object in the process. Mirrors the guard in
+ * `support/deepMerge.ts`.
+ */
+const _UNSAFE_CONFIG_KEYS = new Set(["__proto__", "constructor", "prototype"]);

package/src/config/index.ts

@@ -0,0 +1,46 @@
+/**
+ * The `@zerotal/core/config` subpath — the runtime configuration system.
+ *
+ * Config lives in a set of `config/*.ts` files, each default-exporting one
+ * namespace object (`config/app.ts` → the `app` namespace). {@link configLoader}
+ * discovers and loads them synchronously into a {@link ConfigLoader}, which the
+ * application hands to a {@link ConfigManager} — the store that serves
+ * dot-path reads/writes behind the `Config` facade and the `config()` helper.
+ * {@link AppConfig} builds the framework's own `app` namespace with defaults,
+ * and the {@link ConfigRegistry} interface makes dot-path access type-checked.
+ *
+ * The everyday `config()` helper lives on the kernel barrel (`@zerotal/core`);
+ * the symbols here are the lower-level classes and types used when defining or
+ * wiring configuration.
+ *
+ * @example
+ * ```ts
+ * import { configLoader } from "@zerotal/core/config";
+ * import { Application } from "@zerotal/core";
+ *
+ * // In the entry script — load and validate config, then boot the app.
+ * const config = configLoader("./config").validate();
+ * const app = Application.create({ config });
+ * ```
+ *
+ * @packageDocumentation
+ */
+export { ConfigManager } from "./ConfigManager.ts";
+export { configLoader, ConfigLoader } from "./ConfigLoader.ts";
+export type { ConfigMap } from "./ConfigLoader.ts";
+export { AppConfig } from "./AppConfig.ts";
+export type {
+  AppConfigShape,
+  AppTlsConfig,
+  ConventionsConfig,
+  AppAssetsConfig,
+} from "./AppConfig.ts";
+export type { ConfigRegistry, ConfigPath, ConfigValue } from "./registry.ts";
+export { ConfigValidationError } from "./validation.ts";
+export type {
+  ConfigIssue,
+  ConfigIssueLevel,
+  ConfigValidator,
+  ConfigValidationContext,
+  RegisteredConfigValidator,
+} from "./validation.ts";

package/src/config/registry.ts

@@ -0,0 +1,59 @@
+/**
+ * The typed config registry and the dot-path types built from it. `ConfigRegistry`
+ * is the config analogue of `ContainerBindings`: every config-owning package
+ * augments it via declaration merging so `config("app.name")` is type-checked and
+ * auto-completed by namespace. Core owns the `app` and `health` namespaces.
+ */
+
+// Augmenting packages extend the registry like so:
+//
+//   declare module "@zerotal/core" {
+//     interface ConfigRegistry { cache: CacheConfigShape }
+//   }
+
+import type { AppConfigShape } from "./AppConfig.ts";
+import type { HealthConfigShape } from "../health/Health.ts";
+
+/**
+ * Maps each config namespace to its shape. Augment it from any package that owns a
+ * `config/<namespace>.ts` file. Unaugmented namespaces fall back to the untyped
+ * `config(path: string)` overload, so dynamic access still compiles.
+ */
+export interface ConfigRegistry {
+  app: AppConfigShape;
+  health: HealthConfigShape;
+  lock: import("../lock/config.ts").LockConfigShape;
+  logging: import("../logger/config.ts").LoggingConfigShape;
+}
+
+// ── Dot-path machinery ────────────────────────────────────────────────────────
+
+/** True only for plain nested objects — not arrays or functions (which shouldn't expand). */
+type IsNested<T> = T extends readonly unknown[]
+  ? false
+  : // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    T extends (...args: any[]) => unknown
+    ? false
+    : T extends object
+      ? true
+      : false;
+
+/** Union of every dot-path through `T` (e.g. `'app' | 'app.name' | 'cache.ttl'`). */
+type Leaves<T> = {
+  [K in keyof T & string]: IsNested<T[K]> extends true ? `${K}` | `${K}.${Leaves<T[K]>}` : `${K}`;
+}[keyof T & string];
+
+/** The value type at dot-path `P` within `T`. Unknown paths resolve to `unknown`. */
+type ValueAt<T, P extends string> = P extends `${infer Head}.${infer Rest}`
+  ? Head extends keyof T
+    ? ValueAt<T[Head], Rest>
+    : unknown
+  : P extends keyof T
+    ? T[P]
+    : unknown;
+
+/** Every valid dot-path string across the registered config namespaces. */
+export type ConfigPath = Leaves<ConfigRegistry>;
+
+/** The value type stored at a given config dot-path. */
+export type ConfigValue<P extends string> = ValueAt<ConfigRegistry, P>;

package/src/config/validation.ts

@@ -0,0 +1,117 @@
+/**
+ * Boot-time config validation with production-refusal semantics.
+ *
+ * Each config namespace already has a typed shape in {@link ConfigRegistry}; a
+ * package can attach a validator to its namespace (via
+ * `app.registerConfigValidator(namespace, fn)`) that inspects the loaded value
+ * and reports problems. The boot sequence runs every validator once, after
+ * providers register and before they boot:
+ *
+ * - in a **production-like** deployment, any `error`-level issue **refuses boot**
+ *   — aggregated into a {@link ConfigValidationError} that names each culprit;
+ * - everywhere else, issues are logged as warnings and boot continues.
+ *
+ * `warning`-level issues are always advisory (logged, never fatal). This is the
+ * "delight in development, refusal in production" posture: a placeholder secret
+ * or an insecure cookie flag is a nuisance locally and a hard stop in prod.
+ */
+import type { ConfigManager } from "./ConfigManager.ts";
+import { ZerotalError } from "../errors/ZerotalError.ts";
+
+/** Severity of a config problem. `error` refuses boot in production; `warning` only ever warns. */
+export type ConfigIssueLevel = "error" | "warning";
+
+/** A single problem a config validator reports. */
+export interface ConfigIssue {
+  /** `error` — fatal in production. `warning` — always advisory. */
+  level: ConfigIssueLevel;
+  /** Human-readable description plus the remedy. */
+  message: string;
+}
+
+/** Context handed to a config validator. */
+export interface ConfigValidationContext {
+  /** The namespace being validated (e.g. `"session"`). */
+  namespace: string;
+  /** True in a production-like deployment — the only case where `error` issues are fatal. */
+  isProduction: boolean;
+  /** The full config store, for cross-namespace reads (e.g. checking `app.key`). */
+  config: ConfigManager;
+}
+
+/**
+ * Validates one config namespace's loaded value and returns any problems found.
+ *
+ * The value arrives as `unknown` — config is a dynamic dot-path store, so a
+ * validator narrows to its namespace's shape itself (usually with a single cast
+ * to the package's `*ConfigShape`). Return an empty array (or nothing) when the
+ * namespace is well-formed.
+ */
+export type ConfigValidator = (
+  value: unknown,
+  ctx: ConfigValidationContext,
+) => ConfigIssue[] | void;
+
+/** A validator paired with the namespace it guards, as held on the application. */
+export interface RegisteredConfigValidator {
+  namespace: string;
+  validate: ConfigValidator;
+}
+
+/**
+ * Thrown when config validation refuses a production boot. Lists every fatal
+ * issue by namespace, so a startup failure names exactly what to fix.
+ *
+ * @category Errors
+ */
+export class ConfigValidationError extends ZerotalError {
+  constructor(public readonly issues: Array<{ namespace: string; message: string }>) {
+    super(ConfigValidationError._format(issues), "E_CONFIG_VALIDATION_FAILED", 500, { issues });
+  }
+
+  private static _format(issues: Array<{ namespace: string; message: string }>): string {
+    const lines = issues.map((i) => `  • config(${i.namespace}): ${i.message}`);
+    const plural = issues.length === 1 ? "" : "s";
+    return (
+      `[Zerotal] Refusing to boot: ${issues.length} insecure or invalid config value${plural} ` +
+      `in this production deployment:\n${lines.join("\n")}`
+    );
+  }
+}
+
+/**
+ * Run every registered validator against the loaded config.
+ *
+ * In a production-like deployment, each `error`-level issue is collected and, if
+ * any exist, an aggregated {@link ConfigValidationError} is thrown (boot
+ * refused). Otherwise — and for every `warning`-level issue in any environment —
+ * the issue is logged via `warn` and boot continues.
+ *
+ * @param validators - The namespace/validator pairs to run.
+ * @param config - The loaded configuration store.
+ * @param isProduction - Whether this is a production-like deployment.
+ * @param warn - Sink for advisory messages (defaults to `console.warn`).
+ * @throws {ConfigValidationError} in production when one or more `error` issues are found.
+ */
+export function runConfigValidators(
+  validators: readonly RegisteredConfigValidator[],
+  config: ConfigManager,
+  isProduction: boolean,
+  warn: (message: string) => void = console.warn,
+): void {
+  const fatal: Array<{ namespace: string; message: string }> = [];
+
+  for (const { namespace, validate } of validators) {
+    const value = config.get(namespace);
+    const issues = validate(value, { namespace, isProduction, config }) ?? [];
+    for (const issue of issues) {
+      if (issue.level === "error" && isProduction) {
+        fatal.push({ namespace, message: issue.message });
+      } else {
+        warn(`[Zerotal] config(${namespace}): ${issue.message}`);
+      }
+    }
+  }
+
+  if (fatal.length > 0) throw new ConfigValidationError(fatal);
+}