@nwire/config 0.13.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alex Gefter / 200apps Ltd.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/config-env.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Typed environment reader.
+ *
+ * Reads from `process.env` (or a supplied override — useful for tests).
+ * Values are coerced from strings; mismatches are collected across every
+ * read call and surfaced all-at-once when `env.assertValid()` is called
+ * (or automatically by `loadConfig`). That way a developer with three
+ * mis-named vars sees all three in one boot failure instead of one at a time.
+ *
+ * The instance is intentionally created once per `loadConfig` call so the
+ * aggregated error is scoped to one configuration load, not the process
+ * lifetime.
+ */
+export interface EnvError {
+    key: string;
+    message: string;
+}
+export declare class ConfigEnv {
+    private readonly source;
+    private readonly errors;
+    constructor(source?: NodeJS.ProcessEnv);
+    /**
+     * Read a string value. Returns `defaultValue` when the key is absent.
+     * Undefined `defaultValue` means the key is optional — absent is fine.
+     */
+    string(key: string, defaultValue?: string): string | undefined;
+    /**
+     * Read an integer value. Coerces from the string representation found in
+     * `process.env`. Records an error when the value is present but not a valid
+     * integer; returns `defaultValue` otherwise.
+     */
+    number(key: string, defaultValue?: number): number | undefined;
+    /**
+     * Read a boolean. Accepts `"true"` / `"1"` / `"yes"` as truthy and
+     * `"false"` / `"0"` / `"no"` as falsy (case-insensitive). Any other
+     * non-empty value is recorded as an error.
+     */
+    bool(key: string, defaultValue?: boolean): boolean | undefined;
+    /**
+     * Read a value constrained to a fixed set of strings. Records an error when
+     * the value is present but not in `allowed`.
+     */
+    enum<const T extends string>(key: string, allowed: readonly T[], defaultValue?: T): T | undefined;
+    readonly required: {
+        /**
+         * Read a required string. Records an error when the key is absent or empty.
+         * Returns an empty string as a safe stand-in so downstream code can
+         * continue collecting errors rather than throw immediately.
+         */
+        readonly string: (key: string) => string;
+        /**
+         * Read a required integer.
+         */
+        readonly number: (key: string) => number;
+        /**
+         * Read a required boolean.
+         */
+        readonly bool: (key: string) => boolean;
+        /**
+         * Read a required enum value.
+         */
+        readonly enum: <const T extends string>(key: string, allowed: readonly T[]) => T;
+    };
+    /**
+     * Return a snapshot of all errors collected so far. Empty when everything
+     * was valid.
+     */
+    collectErrors(): readonly EnvError[];
+    /**
+     * Throw an aggregated `ConfigEnvError` if any validation errors were
+     * recorded. Called once by `loadConfig` after all slices have been
+     * evaluated, so the developer sees every problem in one shot.
+     */
+    assertValid(): void;
+}
+/**
+ * Thrown by `assertValid()` / `loadConfig()` when one or more environment
+ * variables are missing or malformed. The `errors` property lists every
+ * problem so the developer can fix them all at once rather than restarting
+ * the process per error.
+ */
+export declare class ConfigEnvError extends Error {
+    readonly errors: readonly EnvError[];
+    constructor(message: string, errors: readonly EnvError[]);
+}

package/dist/config-env.js

@@ -0,0 +1,200 @@
+/**
+ * Typed environment reader.
+ *
+ * Reads from `process.env` (or a supplied override — useful for tests).
+ * Values are coerced from strings; mismatches are collected across every
+ * read call and surfaced all-at-once when `env.assertValid()` is called
+ * (or automatically by `loadConfig`). That way a developer with three
+ * mis-named vars sees all three in one boot failure instead of one at a time.
+ *
+ * The instance is intentionally created once per `loadConfig` call so the
+ * aggregated error is scoped to one configuration load, not the process
+ * lifetime.
+ */
+export class ConfigEnv {
+    source;
+    errors = [];
+    constructor(source = process.env) {
+        this.source = source;
+    }
+    // -------------------------------------------------------------------------
+    // Optional readers (return undefined when key is absent and no default)
+    // -------------------------------------------------------------------------
+    /**
+     * Read a string value. Returns `defaultValue` when the key is absent.
+     * Undefined `defaultValue` means the key is optional — absent is fine.
+     */
+    string(key, defaultValue) {
+        const raw = this.source[key];
+        if (raw === undefined || raw === "") {
+            return defaultValue;
+        }
+        return raw;
+    }
+    /**
+     * Read an integer value. Coerces from the string representation found in
+     * `process.env`. Records an error when the value is present but not a valid
+     * integer; returns `defaultValue` otherwise.
+     */
+    number(key, defaultValue) {
+        const raw = this.source[key];
+        if (raw === undefined || raw === "") {
+            return defaultValue;
+        }
+        const n = Number(raw);
+        if (!Number.isFinite(n)) {
+            this.errors.push({ key, message: `expected a finite number, got "${raw}"` });
+            return defaultValue;
+        }
+        return n;
+    }
+    /**
+     * Read a boolean. Accepts `"true"` / `"1"` / `"yes"` as truthy and
+     * `"false"` / `"0"` / `"no"` as falsy (case-insensitive). Any other
+     * non-empty value is recorded as an error.
+     */
+    bool(key, defaultValue) {
+        const raw = this.source[key];
+        if (raw === undefined || raw === "") {
+            return defaultValue;
+        }
+        const lower = raw.toLowerCase();
+        if (lower === "true" || lower === "1" || lower === "yes")
+            return true;
+        if (lower === "false" || lower === "0" || lower === "no")
+            return false;
+        this.errors.push({
+            key,
+            message: `expected a boolean ("true"/"false"/"1"/"0"/"yes"/"no"), got "${raw}"`,
+        });
+        return defaultValue;
+    }
+    /**
+     * Read a value constrained to a fixed set of strings. Records an error when
+     * the value is present but not in `allowed`.
+     */
+    enum(key, allowed, defaultValue) {
+        const raw = this.source[key];
+        if (raw === undefined || raw === "") {
+            return defaultValue;
+        }
+        if (allowed.includes(raw)) {
+            return raw;
+        }
+        this.errors.push({
+            key,
+            message: `expected one of [${allowed.map((v) => `"${v}"`).join(", ")}], got "${raw}"`,
+        });
+        return defaultValue;
+    }
+    // -------------------------------------------------------------------------
+    // Required readers (no default — missing is always an error)
+    // -------------------------------------------------------------------------
+    required = {
+        /**
+         * Read a required string. Records an error when the key is absent or empty.
+         * Returns an empty string as a safe stand-in so downstream code can
+         * continue collecting errors rather than throw immediately.
+         */
+        string: (key) => {
+            const raw = this.source[key];
+            if (raw === undefined || raw === "") {
+                this.errors.push({ key, message: "required but not set" });
+                return "";
+            }
+            return raw;
+        },
+        /**
+         * Read a required integer.
+         */
+        number: (key) => {
+            const raw = this.source[key];
+            if (raw === undefined || raw === "") {
+                this.errors.push({ key, message: "required but not set" });
+                return 0;
+            }
+            const n = Number(raw);
+            if (!Number.isFinite(n)) {
+                this.errors.push({ key, message: `required; expected a finite number, got "${raw}"` });
+                return 0;
+            }
+            return n;
+        },
+        /**
+         * Read a required boolean.
+         */
+        bool: (key) => {
+            const raw = this.source[key];
+            if (raw === undefined || raw === "") {
+                this.errors.push({ key, message: "required but not set" });
+                return false;
+            }
+            const lower = raw.toLowerCase();
+            if (lower === "true" || lower === "1" || lower === "yes")
+                return true;
+            if (lower === "false" || lower === "0" || lower === "no")
+                return false;
+            this.errors.push({
+                key,
+                message: `required; expected a boolean ("true"/"false"/"1"/"0"/"yes"/"no"), got "${raw}"`,
+            });
+            return false;
+        },
+        /**
+         * Read a required enum value.
+         */
+        enum: (key, allowed) => {
+            const raw = this.source[key];
+            if (raw === undefined || raw === "") {
+                this.errors.push({
+                    key,
+                    message: `required; expected one of [${allowed.map((v) => `"${v}"`).join(", ")}]`,
+                });
+                return allowed[0];
+            }
+            if (allowed.includes(raw)) {
+                return raw;
+            }
+            this.errors.push({
+                key,
+                message: `required; expected one of [${allowed.map((v) => `"${v}"`).join(", ")}], got "${raw}"`,
+            });
+            return allowed[0];
+        },
+    };
+    // -------------------------------------------------------------------------
+    // Error collection
+    // -------------------------------------------------------------------------
+    /**
+     * Return a snapshot of all errors collected so far. Empty when everything
+     * was valid.
+     */
+    collectErrors() {
+        return [...this.errors];
+    }
+    /**
+     * Throw an aggregated `ConfigEnvError` if any validation errors were
+     * recorded. Called once by `loadConfig` after all slices have been
+     * evaluated, so the developer sees every problem in one shot.
+     */
+    assertValid() {
+        if (this.errors.length === 0)
+            return;
+        const lines = this.errors.map((e) => `  ${e.key}: ${e.message}`);
+        throw new ConfigEnvError(`Invalid environment — fix these before booting:\n${lines.join("\n")}`, [...this.errors]);
+    }
+}
+/**
+ * Thrown by `assertValid()` / `loadConfig()` when one or more environment
+ * variables are missing or malformed. The `errors` property lists every
+ * problem so the developer can fix them all at once rather than restarting
+ * the process per error.
+ */
+export class ConfigEnvError extends Error {
+    errors;
+    constructor(message, errors) {
+        super(message);
+        this.errors = errors;
+        this.name = "ConfigEnvError";
+    }
+}

package/dist/config.d.ts

@@ -0,0 +1,34 @@
+/**
+ * @nwire/config — typed configuration layer.
+ *
+ * Three building blocks:
+ *
+ *   `env`          — a stand-alone `ConfigEnv` instance backed by `process.env`.
+ *                    Use it inside `defineConfig` factories. For aggregated
+ *                    fail-fast validation, pass slices to `loadConfig` instead
+ *                    of calling `env` methods ad-hoc.
+ *
+ *   `defineConfig` — declare a named configuration slice (factory + name).
+ *
+ *   `loadConfig`   — evaluate all slices, aggregate env errors, return a
+ *                    deeply-frozen typed config object.
+ *
+ * Quick-start:
+ *
+ *   import { defineConfig, loadConfig } from '@nwire/config'
+ *
+ *   const http = defineConfig('http', (env) => ({
+ *     port:   env.number('PORT', 3000),
+ *     prefix: env.string('HTTP_PREFIX', '/api'),
+ *   }))
+ *
+ *   export const config = loadConfig([http])
+ *   // config.http.port   — number
+ *   // config.http.prefix — string | undefined
+ */
+export { ConfigEnv, ConfigEnvError } from "./config-env.js";
+export type { EnvError } from "./config-env.js";
+export { defineConfig } from "./define-config.js";
+export type { ConfigDefinition, ConfigFactory } from "./define-config.js";
+export { loadConfig } from "./load-config.js";
+export type { LoadConfigOptions } from "./load-config.js";

package/dist/config.js

@@ -0,0 +1,31 @@
+/**
+ * @nwire/config — typed configuration layer.
+ *
+ * Three building blocks:
+ *
+ *   `env`          — a stand-alone `ConfigEnv` instance backed by `process.env`.
+ *                    Use it inside `defineConfig` factories. For aggregated
+ *                    fail-fast validation, pass slices to `loadConfig` instead
+ *                    of calling `env` methods ad-hoc.
+ *
+ *   `defineConfig` — declare a named configuration slice (factory + name).
+ *
+ *   `loadConfig`   — evaluate all slices, aggregate env errors, return a
+ *                    deeply-frozen typed config object.
+ *
+ * Quick-start:
+ *
+ *   import { defineConfig, loadConfig } from '@nwire/config'
+ *
+ *   const http = defineConfig('http', (env) => ({
+ *     port:   env.number('PORT', 3000),
+ *     prefix: env.string('HTTP_PREFIX', '/api'),
+ *   }))
+ *
+ *   export const config = loadConfig([http])
+ *   // config.http.port   — number
+ *   // config.http.prefix — string | undefined
+ */
+export { ConfigEnv, ConfigEnvError } from "./config-env.js";
+export { defineConfig } from "./define-config.js";
+export { loadConfig } from "./load-config.js";

package/dist/define-config.d.ts

@@ -0,0 +1,41 @@
+/**
+ * `defineConfig` — declares a single named configuration slice.
+ *
+ * Each slice is a factory that receives the `ConfigEnv` reader and returns a
+ * typed settings object. The factory is evaluated lazily by `loadConfig`;
+ * the returned definition carries only the name and factory, never the
+ * resolved value.
+ *
+ *   const http = defineConfig('http', (env) => ({
+ *     port: env.number('PORT', 3000),
+ *     prefix: env.string('HTTP_PREFIX', '/api'),
+ *   }))
+ *
+ * The name must be unique within any `loadConfig` call — duplicates throw at
+ * load time.
+ */
+import type { ConfigEnv } from "./config-env.js";
+export type ConfigFactory<T> = (env: ConfigEnv) => T;
+/**
+ * An opaque handle produced by `defineConfig`. Pass it to `loadConfig` to
+ * include the slice in the frozen config object.
+ *
+ * The `_phantom` field is a compile-time marker that carries the resolved
+ * type `T` through to `loadConfig`'s return type without ever existing at
+ * runtime.
+ */
+export interface ConfigDefinition<Name extends string, T> {
+    /** Slice name — used as the key on the config object returned by `loadConfig`. */
+    readonly name: Name;
+    /** Evaluated once by `loadConfig`. Not called directly. */
+    readonly factory: ConfigFactory<T>;
+    /** Compile-time phantom type marker. Never set at runtime. */
+    readonly _phantom?: T;
+}
+/**
+ * Declare a typed configuration slice.
+ *
+ * @param name    The key under which this slice appears in the loaded config.
+ * @param factory A function that reads from `env` and returns the slice value.
+ */
+export declare function defineConfig<const Name extends string, T>(name: Name, factory: ConfigFactory<T>): ConfigDefinition<Name, T>;

package/dist/define-config.js

@@ -0,0 +1,25 @@
+/**
+ * `defineConfig` — declares a single named configuration slice.
+ *
+ * Each slice is a factory that receives the `ConfigEnv` reader and returns a
+ * typed settings object. The factory is evaluated lazily by `loadConfig`;
+ * the returned definition carries only the name and factory, never the
+ * resolved value.
+ *
+ *   const http = defineConfig('http', (env) => ({
+ *     port: env.number('PORT', 3000),
+ *     prefix: env.string('HTTP_PREFIX', '/api'),
+ *   }))
+ *
+ * The name must be unique within any `loadConfig` call — duplicates throw at
+ * load time.
+ */
+/**
+ * Declare a typed configuration slice.
+ *
+ * @param name    The key under which this slice appears in the loaded config.
+ * @param factory A function that reads from `env` and returns the slice value.
+ */
+export function defineConfig(name, factory) {
+    return { name, factory };
+}

package/dist/load-config.d.ts

@@ -0,0 +1,62 @@
+/**
+ * `loadConfig` — evaluates all declared slices, aggregates env errors, and
+ * returns a deeply-frozen typed config object.
+ *
+ * Evaluation order:
+ *   1. Create a single `ConfigEnv` that collects all validation errors.
+ *   2. Call every slice factory, collecting results by name.
+ *   3. After all slices are evaluated, call `env.assertValid()` — this throws
+ *      a single `ConfigEnvError` listing every bad or missing variable if
+ *      any were encountered. The developer sees every problem in one boot
+ *      failure instead of one at a time.
+ *   4. Deep-freeze the result and return it.
+ *
+ * Usage:
+ *
+ *   import { env, defineConfig, loadConfig } from '@nwire/config'
+ *
+ *   const http   = defineConfig('http',   (e) => ({ port: e.number('PORT', 3000) }))
+ *   const mail   = defineConfig('mail',   (e) => ({ host: e.required.string('MAIL_HOST') }))
+ *
+ *   export const config = loadConfig([http, mail])
+ *   // config.http.port  — number
+ *   // config.mail.host  — string
+ */
+import type { ConfigDefinition } from "./define-config.js";
+/** Extract the resolved value type from a `ConfigDefinition`. */
+type DefinitionValue<D> = D extends ConfigDefinition<string, infer T> ? T : never;
+/** Extract the name literal from a `ConfigDefinition`. */
+type DefinitionName<D> = D extends ConfigDefinition<infer N, unknown> ? N : never;
+/**
+ * Given a tuple of `ConfigDefinition` instances, produce the record type
+ * that `loadConfig` returns. Each slice name becomes a key.
+ *
+ * Example:
+ *   [ConfigDefinition<'http', { port: number }>, ConfigDefinition<'mail', { host: string }>]
+ *   → { readonly http: { port: number }; readonly mail: { host: string } }
+ */
+type LoadedConfig<Defs extends ReadonlyArray<ConfigDefinition<string, unknown>>> = {
+    readonly [D in Defs[number] as DefinitionName<D>]: DefinitionValue<D>;
+};
+/**
+ * Options for `loadConfig`.
+ */
+export interface LoadConfigOptions {
+    /**
+     * A source to read environment variables from. Defaults to `process.env`.
+     * Useful for tests that need to supply a synthetic environment without
+     * mutating `process.env`.
+     *
+     *   loadConfig([http], { source: { PORT: '8080' } })
+     */
+    source?: NodeJS.ProcessEnv;
+}
+/**
+ * Evaluate all config slices, validate the environment in aggregate, and
+ * return a deeply-frozen typed config object.
+ *
+ * @param defs   One or more `ConfigDefinition` values produced by `defineConfig`.
+ * @param opts   Optional overrides (e.g. `source` for testing).
+ */
+export declare function loadConfig<const Defs extends ReadonlyArray<ConfigDefinition<string, unknown>>>(defs: Defs, opts?: LoadConfigOptions): LoadedConfig<Defs>;
+export {};

package/dist/load-config.js

@@ -0,0 +1,62 @@
+/**
+ * `loadConfig` — evaluates all declared slices, aggregates env errors, and
+ * returns a deeply-frozen typed config object.
+ *
+ * Evaluation order:
+ *   1. Create a single `ConfigEnv` that collects all validation errors.
+ *   2. Call every slice factory, collecting results by name.
+ *   3. After all slices are evaluated, call `env.assertValid()` — this throws
+ *      a single `ConfigEnvError` listing every bad or missing variable if
+ *      any were encountered. The developer sees every problem in one boot
+ *      failure instead of one at a time.
+ *   4. Deep-freeze the result and return it.
+ *
+ * Usage:
+ *
+ *   import { env, defineConfig, loadConfig } from '@nwire/config'
+ *
+ *   const http   = defineConfig('http',   (e) => ({ port: e.number('PORT', 3000) }))
+ *   const mail   = defineConfig('mail',   (e) => ({ host: e.required.string('MAIL_HOST') }))
+ *
+ *   export const config = loadConfig([http, mail])
+ *   // config.http.port  — number
+ *   // config.mail.host  — string
+ */
+import { ConfigEnv } from "./config-env.js";
+// ---------------------------------------------------------------------------
+// Deep-freeze helper
+// ---------------------------------------------------------------------------
+function deepFreeze(obj) {
+    if (obj === null || typeof obj !== "object")
+        return obj;
+    Object.getOwnPropertyNames(obj).forEach((name) => {
+        const val = obj[name];
+        if (val && typeof val === "object")
+            deepFreeze(val);
+    });
+    return Object.freeze(obj);
+}
+/**
+ * Evaluate all config slices, validate the environment in aggregate, and
+ * return a deeply-frozen typed config object.
+ *
+ * @param defs   One or more `ConfigDefinition` values produced by `defineConfig`.
+ * @param opts   Optional overrides (e.g. `source` for testing).
+ */
+export function loadConfig(defs, opts = {}) {
+    const seen = new Set();
+    for (const def of defs) {
+        if (seen.has(def.name)) {
+            throw new Error(`@nwire/config: duplicate slice name "${def.name}". Each defineConfig name must be unique within a loadConfig call.`);
+        }
+        seen.add(def.name);
+    }
+    const env = new ConfigEnv(opts.source ?? process.env);
+    const result = {};
+    for (const def of defs) {
+        result[def.name] = def.factory(env);
+    }
+    // Aggregate — throws once with every env error listed
+    env.assertValid();
+    return deepFreeze(result);
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@nwire/config",
+  "version": "0.13.2",
+  "description": "Nwire — typed configuration layer. env reader with coercion + aggregated fail-fast, defineConfig slices, loadConfig registry. Laravel/Adonis-grade configuration for @nwire apps.",
+  "keywords": [
+    "config",
+    "env",
+    "environment",
+    "nwire"
+  ],
+  "license": "MIT",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "main": "./dist/config.js",
+  "types": "./dist/config.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/config.js",
+      "types": "./dist/config.d.ts"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.9",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  },
+  "scripts": {
+    "build": "tsc && node ../../scripts/fix-dist-extensions.mjs dist",
+    "dev": "tsc --watch",
+    "typecheck": "tsc --noEmit"
+  }
+}