@epsilon-asi/foundation 0.0.10 → 0.0.12

package/build/decorators/environment/parse.js

@@ -0,0 +1,88 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toEnvKey = toEnvKey;
+exports.parseEnvValue = parseEnvValue;
+const errors_1 = require("./errors");
+function toEnvKey(propertyName) {
+    return propertyName
+        .replace(/([A-Z]+)([A-Z][a-z])/g, '$1_$2')
+        .replace(/([a-z0-9])([A-Z])/g, '$1_$2')
+        .replace(/[-\s]+/g, '_')
+        .toUpperCase();
+}
+function parseEnvValue(args) {
+    const { envName, propertyName, rawValue, metadata, emptyStringAsMissing } = args;
+    const missing = rawValue === undefined || (emptyStringAsMissing && rawValue.trim() === '');
+    if (missing) {
+        if ('default' in metadata)
+            return metadata.default;
+        if (metadata.required === false)
+            return undefined;
+        throw new errors_1.EnvParseError(`Missing required environment variable "${envName}".`, {
+            envName,
+            propertyName,
+        });
+    }
+    switch (metadata.type) {
+        case 'string':
+            return rawValue;
+        case 'number':
+            return parseNumberValue({
+                envName,
+                propertyName,
+                rawValue,
+                metadata,
+            });
+        case 'boolean':
+            return parseBooleanValue({
+                envName,
+                propertyName,
+                rawValue,
+            });
+        default:
+            return assertNever(metadata);
+    }
+}
+function parseNumberValue(args) {
+    const { envName, propertyName, rawValue, metadata } = args;
+    const value = Number(rawValue);
+    if (!Number.isFinite(value)) {
+        throw new errors_1.EnvParseError(`Environment variable "${envName}" must be a finite number. Received "${rawValue}".`, { envName, propertyName });
+    }
+    if (metadata.integer === true && !Number.isInteger(value)) {
+        throw new errors_1.EnvParseError(`Environment variable "${envName}" must be an integer. Received "${rawValue}".`, { envName, propertyName });
+    }
+    if (metadata.min !== undefined && value < metadata.min) {
+        throw new errors_1.EnvParseError(`Environment variable "${envName}" must be >= ${metadata.min}. Received "${rawValue}".`, { envName, propertyName });
+    }
+    if (metadata.max !== undefined && value > metadata.max) {
+        throw new errors_1.EnvParseError(`Environment variable "${envName}" must be <= ${metadata.max}. Received "${rawValue}".`, { envName, propertyName });
+    }
+    return value;
+}
+function parseBooleanValue(args) {
+    const { envName, propertyName, rawValue } = args;
+    const normalized = rawValue.trim().toLowerCase();
+    if (isTruthyEnvValue(normalized))
+        return true;
+    if (isFalsyEnvValue(normalized))
+        return false;
+    throw new errors_1.EnvParseError(`Environment variable "${envName}" must be a boolean. Received "${rawValue}".`, { envName, propertyName });
+}
+function isTruthyEnvValue(value) {
+    return value === 'true'
+        || value === '1'
+        || value === 'yes'
+        || value === 'y'
+        || value === 'on';
+}
+function isFalsyEnvValue(value) {
+    return value === 'false'
+        || value === '0'
+        || value === 'no'
+        || value === 'n'
+        || value === 'off';
+}
+function assertNever(value) {
+    throw new errors_1.EnvParseError(`Unsupported env metadata: ${JSON.stringify(value)}`);
+}

package/build/decorators/environment/system.d.ts

@@ -0,0 +1,4 @@
+import type { RegistryMetadataSnapshot } from '../factory';
+import type { EnvConfigMetadata, EnvSystem } from './types';
+export declare function createEnvSystem(): EnvSystem;
+export declare function getEnvConfigMetadata(snapshot: RegistryMetadataSnapshot): EnvConfigMetadata | undefined;

package/build/decorators/environment/system.js

@@ -0,0 +1,133 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createEnvSystem = createEnvSystem;
+exports.getEnvConfigMetadata = getEnvConfigMetadata;
+const factory_1 = require("../factory");
+const dotenv_1 = require("./dotenv");
+const errors_1 = require("./errors");
+const parse_1 = require("./parse");
+function createEnvSystem() {
+    const registry = (0, factory_1.createDecoratorRegistry)({
+        namespace: 'env',
+    });
+    const RawEnvConfig = registry.class('envConfig');
+    const Env = ((metadata) => {
+        return metadata === undefined ? RawEnvConfig() : RawEnvConfig(metadata);
+    });
+    const EnvConfig = Env;
+    /**
+     * Broad scoped contract because this system decorates arbitrary env classes.
+     * The public EnvVar.string/number/boolean helper return types enforce the actual
+     * decorated property type.
+     */
+    const Scoped = registry.for();
+    const RawEnvVar = Scoped.property('envVar');
+    const EnvVar = ((metadata) => RawEnvVar(metadata));
+    EnvVar.string = (name, options = {}) => {
+        return RawEnvVar(Object.assign(Object.assign({}, options), { name, type: 'string' }));
+    };
+    EnvVar.number = (name, options = {}) => {
+        return RawEnvVar(Object.assign(Object.assign({}, options), { name, type: 'number' }));
+    };
+    EnvVar.boolean = (name, options = {}) => {
+        return RawEnvVar(Object.assign(Object.assign({}, options), { name, type: 'boolean' }));
+    };
+    function describeEnv(target, options = {}) {
+        var _a, _b;
+        const includeInherited = (_a = options.includeInherited) !== null && _a !== void 0 ? _a : true;
+        const snapshot = registry.read(target, { includeInherited });
+        const classMetadata = getEnvConfigMetadata(snapshot);
+        const prefix = (_b = classMetadata === null || classMetadata === void 0 ? void 0 : classMetadata.prefix) !== null && _b !== void 0 ? _b : '';
+        return Object.freeze(snapshot.propertyRecords('envVar').map((record) => {
+            var _a;
+            if (record.memberName === undefined) {
+                throw new errors_1.EnvParseError('EnvVar metadata record is missing memberName.');
+            }
+            if (typeof record.memberName === 'symbol') {
+                throw new errors_1.EnvParseError(`EnvVar does not support symbol member keys: ${String(record.memberName)}.`);
+            }
+            const metadata = record.metadata;
+            const propertyName = record.memberName;
+            const envName = prefix + ((_a = metadata.name) !== null && _a !== void 0 ? _a : (0, parse_1.toEnvKey)(propertyName));
+            return Object.freeze({
+                propertyName,
+                envName,
+                static: record.static,
+                private: record.private,
+                metadata,
+            });
+        }));
+    }
+    function loadEnv(target, options = {}) {
+        var _a, _b, _c, _d, _e, _f, _g;
+        const source = (_a = options.source) !== null && _a !== void 0 ? _a : getDefaultEnvSource();
+        const requireStatic = (_b = options.requireStatic) !== null && _b !== void 0 ? _b : true;
+        const emptyStringAsMissing = (_c = options.emptyStringAsMissing) !== null && _c !== void 0 ? _c : true;
+        const includeInherited = (_d = options.includeInherited) !== null && _d !== void 0 ? _d : true;
+        const snapshot = registry.read(target, { includeInherited });
+        const definitions = describeEnv(target, { includeInherited });
+        const values = {};
+        const dotenvOptions = (0, dotenv_1.resolveDotenvOptions)((_e = getEnvConfigMetadata(snapshot)) === null || _e === void 0 ? void 0 : _e.dotenv, options.dotenv);
+        const dotenv = dotenvOptions === undefined ? undefined : (0, dotenv_1.readDotenvFiles)(dotenvOptions);
+        const dotenvWins = (_f = dotenvOptions === null || dotenvOptions === void 0 ? void 0 : dotenvOptions.override) !== null && _f !== void 0 ? _f : true;
+        const lookup = (envName) => {
+            var _a;
+            const fromDotenv = dotenv === null || dotenv === void 0 ? void 0 : dotenv.values[envName];
+            return dotenvWins ? fromDotenv !== null && fromDotenv !== void 0 ? fromDotenv : source[envName] : (_a = source[envName]) !== null && _a !== void 0 ? _a : fromDotenv;
+        };
+        for (const definition of definitions) {
+            if (requireStatic && !definition.static) {
+                throw new errors_1.EnvParseError(`@EnvVar field "${definition.propertyName}" must be static when using loadEnv().`, {
+                    envName: definition.envName,
+                    propertyName: definition.propertyName,
+                });
+            }
+            if (definition.private) {
+                throw new errors_1.EnvParseError(`@EnvVar field "${definition.propertyName}" cannot be private.`, {
+                    envName: definition.envName,
+                    propertyName: definition.propertyName,
+                });
+            }
+            const rawValue = lookup(definition.envName);
+            const parsedValue = (0, parse_1.parseEnvValue)({
+                envName: definition.envName,
+                propertyName: definition.propertyName,
+                rawValue,
+                metadata: definition.metadata,
+                emptyStringAsMissing,
+            });
+            Object.defineProperty(target, definition.propertyName, {
+                configurable: true,
+                enumerable: true,
+                writable: true,
+                value: parsedValue,
+            });
+            values[definition.propertyName] = parsedValue;
+        }
+        return Object.freeze({
+            target,
+            definitions,
+            values: Object.freeze(Object.assign({}, values)),
+            snapshot,
+            dotenvFiles: (_g = dotenv === null || dotenv === void 0 ? void 0 : dotenv.files) !== null && _g !== void 0 ? _g : Object.freeze([]),
+        });
+    }
+    return Object.freeze({
+        registry,
+        Env,
+        EnvConfig,
+        EnvVar,
+        loadEnv,
+        describeEnv,
+    });
+}
+function getEnvConfigMetadata(snapshot) {
+    const configRecords = snapshot.classRecords('envConfig');
+    const lastRecord = configRecords[configRecords.length - 1];
+    return lastRecord === null || lastRecord === void 0 ? void 0 : lastRecord.metadata;
+}
+function getDefaultEnvSource() {
+    var _a, _b;
+    const maybeGlobal = globalThis;
+    return (_b = (_a = maybeGlobal.process) === null || _a === void 0 ? void 0 : _a.env) !== null && _b !== void 0 ? _b : {};
+}

package/build/decorators/environment/types.d.ts

@@ -0,0 +1,160 @@
+import type { ClassDecoratorDefinition, Constructor, DecoratorRegistry, PropertyDecoratorDefinition, RegistryMetadataSnapshot } from '../factory';
+import type { DotenvSetting } from './dotenv';
+export type EnvPrimitive = string | number | boolean;
+export type EnvPrimitiveOrUndefined = EnvPrimitive | undefined;
+export type EnvBooleanTrueValue = 'true' | '1' | 'yes' | 'y' | 'on';
+export type EnvBooleanFalseValue = 'false' | '0' | 'no' | 'n' | 'off';
+export type EnvValueKind = 'string' | 'number' | 'boolean';
+export interface EnvConfigMetadata {
+    /**
+     * Optional prefix applied to every variable lookup.
+     *
+     * Example:
+     * prefix: 'APP_'
+     * @EnvVar.string('PORT')
+     * final lookup key: APP_PORT
+     */
+    prefix?: string;
+    /** Optional human-readable description for docs/debug output. */
+    description?: string;
+    /**
+     * Dotenv files this class loads. On by default: loadEnv() reads '.env' from the working
+     * directory (skipping it when missing) and its values take precedence over process.env.
+     *
+     * Pass a path, a list of paths (later files win) or DotenvOptions to change that,
+     * or `false` to opt this class out. loadEnv({ dotenv }) is merged over this setting.
+     */
+    dotenv?: DotenvSetting;
+}
+export type StringEnvVarMetadata = {
+    type: 'string';
+    name?: string;
+    required?: boolean;
+    default?: string;
+    description?: string;
+};
+export type NumberEnvVarMetadata = {
+    type: 'number';
+    name?: string;
+    required?: boolean;
+    default?: number;
+    min?: number;
+    max?: number;
+    integer?: boolean;
+    description?: string;
+};
+export type BooleanEnvVarMetadata = {
+    type: 'boolean';
+    name?: string;
+    required?: boolean;
+    default?: boolean;
+    description?: string;
+};
+export type EnvVarMetadata = StringEnvVarMetadata | NumberEnvVarMetadata | BooleanEnvVarMetadata;
+export type EnvDecoratorSchema = {
+    class: {
+        envConfig: ClassDecoratorDefinition<EnvConfigMetadata | undefined>;
+    };
+    property: {
+        envVar: PropertyDecoratorDefinition<EnvVarMetadata, EnvPrimitiveOrUndefined>;
+    };
+    method: {};
+    accessor: {};
+};
+export type EnvSource = Record<string, string | undefined>;
+export interface LoadEnvOptions {
+    /**
+     * Defaults to globalThis.process.env when available.
+     * Pass this in tests to avoid mutating or depending on the real process env.
+     * Dotenv files are still layered over it; add `dotenv: false` to isolate fully.
+     */
+    source?: EnvSource;
+    /**
+     * Dotenv files layered over `source`. On by default: reads '.env' from the working
+     * directory, skips it when missing, and its values take precedence over `source`.
+     *
+     * Merged over the class-level @Env({ dotenv }) setting. Pass `false` to turn it off
+     * for this call, or `{ override: false }` to let `source` win instead.
+     */
+    dotenv?: DotenvSetting;
+    /**
+     * Whether @EnvVar fields must be static.
+     *
+     * Defaults to true because loadEnv mutates the class constructor in place.
+     */
+    requireStatic?: boolean;
+    /**
+     * Whether empty strings and whitespace-only strings should be treated as missing.
+     *
+     * Defaults to true.
+     */
+    emptyStringAsMissing?: boolean;
+    /**
+     * Whether inherited metadata should be loaded.
+     *
+     * Defaults to true.
+     */
+    includeInherited?: boolean;
+}
+export interface DescribeEnvOptions {
+    /** Defaults to true. */
+    includeInherited?: boolean;
+}
+export interface EnvVariableDefinition {
+    readonly propertyName: string;
+    readonly envName: string;
+    readonly static: boolean;
+    readonly private: boolean;
+    readonly metadata: EnvVarMetadata;
+}
+export interface EnvLoadResult<TClass extends Constructor> {
+    readonly target: TClass;
+    readonly definitions: readonly EnvVariableDefinition[];
+    readonly values: Readonly<Record<string, EnvPrimitiveOrUndefined>>;
+    readonly snapshot: RegistryMetadataSnapshot;
+    /** Absolute paths of the dotenv files that were read, in load order. */
+    readonly dotenvFiles: readonly string[];
+}
+export interface EnvConfigDecorator {
+    (metadata?: EnvConfigMetadata): <TClass extends Constructor>(value: TClass, context: ClassDecoratorContext<TClass>) => void;
+}
+export interface EnvVarDecoratorApi {
+    /**
+     * Generic form:
+     *
+     * @EnvVar({ name: 'PORT', type: 'number' })
+     * static port: number;
+     */
+    (metadata: StringEnvVarMetadata): (value: undefined, context: ClassFieldDecoratorContext<any, string | undefined>) => void;
+    (metadata: NumberEnvVarMetadata): (value: undefined, context: ClassFieldDecoratorContext<any, number | undefined>) => void;
+    (metadata: BooleanEnvVarMetadata): (value: undefined, context: ClassFieldDecoratorContext<any, boolean | undefined>) => void;
+    /**
+     * @EnvVar.string('API_KEY')
+     * static apiKey: string;
+     */
+    string(name?: string, options?: Omit<StringEnvVarMetadata, 'type' | 'name'>): (value: undefined, context: ClassFieldDecoratorContext<any, string | undefined>) => void;
+    /**
+     * @EnvVar.number('PORT', { default: 3000, integer: true })
+     * static port: number;
+     */
+    number(name?: string, options?: Omit<NumberEnvVarMetadata, 'type' | 'name'>): (value: undefined, context: ClassFieldDecoratorContext<any, number | undefined>) => void;
+    /**
+     * @EnvVar.boolean('DEBUG', { default: false })
+     * static debug: boolean;
+     */
+    boolean(name?: string, options?: Omit<BooleanEnvVarMetadata, 'type' | 'name'>): (value: undefined, context: ClassFieldDecoratorContext<any, boolean | undefined>) => void;
+}
+export interface EnvSystem {
+    readonly registry: DecoratorRegistry<EnvDecoratorSchema>;
+    /** Preferred class decorator name. */
+    readonly Env: EnvConfigDecorator;
+    /** Alias for Env, for users who prefer a more explicit name. */
+    readonly EnvConfig: EnvConfigDecorator;
+    readonly EnvVar: EnvVarDecoratorApi;
+    /**
+     * Mutates the provided class in place by assigning parsed values to static fields.
+     */
+    loadEnv<TClass extends Constructor>(target: TClass, options?: LoadEnvOptions): EnvLoadResult<TClass>;
+    /** Reads env metadata without mutating the class. */
+    describeEnv<TClass extends Constructor>(target: TClass, options?: DescribeEnvOptions): readonly EnvVariableDefinition[];
+}

package/build/decorators/environment/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/build/files/index.d.ts

@@ -0,0 +1,11 @@
+import { createSchemaFile, interpolateEnv, interpolateEnvHook } from "./init";
+import { loadFile, loadFileSync, safeLoadFile, safeLoadFileSync } from "./load";
+import { parseStringSync } from "./parse";
+import { parseString } from "./parse";
+import { serialize, serializeAsync } from "./serialize";
+import { saveFile, saveFileSync } from "./save";
+import { SchemaFileError } from "./types";
+import { deepMerge } from "./util";
+import { createLayeredFile, discoverLayers, discoverLayersSync, loadLayeredFile, loadLayeredFileSync, loadMergedFiles, loadMergedFilesSync, safeLoadLayeredFile, safeLoadLayeredFileSync } from "./layered";
+export type { DiscoverOptions, ErrorFormatter, FileLayer, LayeredLoadOptions, LayeredResult, LayerOrigin, FileFormat, LoadOptions, ParseOptions, ParseParams, PreprocessContext, SafeResult, SaveOptions, SchemaFileErrorKind, SerializeOptions, SerializeStrategy, } from "./types";
+export { createSchemaFile, interpolateEnv, interpolateEnvHook, loadFile, loadFileSync, safeLoadFile, safeLoadFileSync, serialize, serializeAsync, parseString, parseStringSync, saveFileSync, saveFile, SchemaFileError, deepMerge, createLayeredFile, discoverLayers, discoverLayersSync, loadLayeredFile, loadLayeredFileSync, loadMergedFiles, loadMergedFilesSync, safeLoadLayeredFile, safeLoadLayeredFileSync, };

package/build/files/index.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.safeLoadLayeredFileSync = exports.safeLoadLayeredFile = exports.loadMergedFilesSync = exports.loadMergedFiles = exports.loadLayeredFileSync = exports.loadLayeredFile = exports.discoverLayersSync = exports.discoverLayers = exports.createLayeredFile = exports.deepMerge = exports.SchemaFileError = exports.saveFile = exports.saveFileSync = exports.parseStringSync = exports.parseString = exports.serializeAsync = exports.serialize = exports.safeLoadFileSync = exports.safeLoadFile = exports.loadFileSync = exports.loadFile = exports.interpolateEnvHook = exports.interpolateEnv = exports.createSchemaFile = void 0;
+const init_1 = require("./init");
+Object.defineProperty(exports, "createSchemaFile", { enumerable: true, get: function () { return init_1.createSchemaFile; } });
+Object.defineProperty(exports, "interpolateEnv", { enumerable: true, get: function () { return init_1.interpolateEnv; } });
+Object.defineProperty(exports, "interpolateEnvHook", { enumerable: true, get: function () { return init_1.interpolateEnvHook; } });
+const load_1 = require("./load");
+Object.defineProperty(exports, "loadFile", { enumerable: true, get: function () { return load_1.loadFile; } });
+Object.defineProperty(exports, "loadFileSync", { enumerable: true, get: function () { return load_1.loadFileSync; } });
+Object.defineProperty(exports, "safeLoadFile", { enumerable: true, get: function () { return load_1.safeLoadFile; } });
+Object.defineProperty(exports, "safeLoadFileSync", { enumerable: true, get: function () { return load_1.safeLoadFileSync; } });
+const parse_1 = require("./parse");
+Object.defineProperty(exports, "parseStringSync", { enumerable: true, get: function () { return parse_1.parseStringSync; } });
+const parse_2 = require("./parse");
+Object.defineProperty(exports, "parseString", { enumerable: true, get: function () { return parse_2.parseString; } });
+const serialize_1 = require("./serialize");
+Object.defineProperty(exports, "serialize", { enumerable: true, get: function () { return serialize_1.serialize; } });
+Object.defineProperty(exports, "serializeAsync", { enumerable: true, get: function () { return serialize_1.serializeAsync; } });
+const save_1 = require("./save");
+Object.defineProperty(exports, "saveFile", { enumerable: true, get: function () { return save_1.saveFile; } });
+Object.defineProperty(exports, "saveFileSync", { enumerable: true, get: function () { return save_1.saveFileSync; } });
+const types_1 = require("./types");
+Object.defineProperty(exports, "SchemaFileError", { enumerable: true, get: function () { return types_1.SchemaFileError; } });
+const util_1 = require("./util");
+Object.defineProperty(exports, "deepMerge", { enumerable: true, get: function () { return util_1.deepMerge; } });
+const layered_1 = require("./layered");
+Object.defineProperty(exports, "createLayeredFile", { enumerable: true, get: function () { return layered_1.createLayeredFile; } });
+Object.defineProperty(exports, "discoverLayers", { enumerable: true, get: function () { return layered_1.discoverLayers; } });
+Object.defineProperty(exports, "discoverLayersSync", { enumerable: true, get: function () { return layered_1.discoverLayersSync; } });
+Object.defineProperty(exports, "loadLayeredFile", { enumerable: true, get: function () { return layered_1.loadLayeredFile; } });
+Object.defineProperty(exports, "loadLayeredFileSync", { enumerable: true, get: function () { return layered_1.loadLayeredFileSync; } });
+Object.defineProperty(exports, "loadMergedFiles", { enumerable: true, get: function () { return layered_1.loadMergedFiles; } });
+Object.defineProperty(exports, "loadMergedFilesSync", { enumerable: true, get: function () { return layered_1.loadMergedFilesSync; } });
+Object.defineProperty(exports, "safeLoadLayeredFile", { enumerable: true, get: function () { return layered_1.safeLoadLayeredFile; } });
+Object.defineProperty(exports, "safeLoadLayeredFileSync", { enumerable: true, get: function () { return layered_1.safeLoadLayeredFileSync; } });

package/build/files/init.d.ts

@@ -0,0 +1,33 @@
+import * as z from "zod";
+import { LoadOptions, ParseOptions, SaveOptions, SerializeOptions } from "./types";
+/**
+ * Bind a schema and default options once, reuse everywhere.
+ * Per-call options are shallow-merged over the defaults.
+ */
+export declare function createSchemaFile<S extends z.ZodType>(schema: S, defaults?: {
+    load?: LoadOptions;
+    save?: SaveOptions;
+}): {
+    schema: S;
+    load: (filePath: string, o?: LoadOptions) => Promise<z.core.output<S>>;
+    loadSync: (filePath: string, o?: LoadOptions) => z.core.output<S>;
+    safeLoad: (filePath: string, o?: LoadOptions) => Promise<import("./types").SafeResult<z.core.output<S>>>;
+    safeLoadSync: (filePath: string, o?: LoadOptions) => import("./types").SafeResult<z.core.output<S>>;
+    parse: (text: string, o?: ParseOptions) => Promise<z.core.output<S>>;
+    save: (filePath: string, value: z.output<S>, o?: SaveOptions) => Promise<string>;
+    saveSync: (filePath: string, value: z.output<S>, o?: SaveOptions) => string;
+    serialize: (value: z.output<S>, o: SerializeOptions) => Promise<string>;
+};
+/**
+ * Recursively replace ${VAR} and ${VAR:-fallback} in string values.
+ * For a `preprocess` hook use interpolateEnvHook(): a hook's second argument is the
+ * PreprocessContext, which this function would read as `env`. Note results are strings,
+ * so use z.coerce.* in the schema for numeric/boolean fields filled from env vars.
+ */
+export declare function interpolateEnv(value: unknown, env?: Record<string, string | undefined>, options?: {
+    strict?: boolean;
+}): unknown;
+/** A `preprocess` hook that runs interpolateEnv over the parsed data: { preprocess: interpolateEnvHook() }. */
+export declare function interpolateEnvHook(env?: Record<string, string | undefined>, options?: {
+    strict?: boolean;
+}): (raw: unknown) => unknown;

package/build/files/init.js

@@ -0,0 +1,62 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSchemaFile = createSchemaFile;
+exports.interpolateEnv = interpolateEnv;
+exports.interpolateEnvHook = interpolateEnvHook;
+const util_1 = require("./util");
+const serialize_1 = require("./serialize");
+const load_1 = require("./load");
+const save_1 = require("./save");
+const parse_1 = require("./parse");
+/**
+ * Bind a schema and default options once, reuse everywhere.
+ * Per-call options are shallow-merged over the defaults.
+ */
+function createSchemaFile(schema, defaults = {}) {
+    const l = (o) => (Object.assign(Object.assign({}, defaults.load), o));
+    const s = (o) => (Object.assign(Object.assign({}, defaults.save), o));
+    return {
+        schema,
+        load: (filePath, o) => (0, load_1.loadFile)(filePath, schema, l(o)),
+        loadSync: (filePath, o) => (0, load_1.loadFileSync)(filePath, schema, l(o)),
+        safeLoad: (filePath, o) => (0, load_1.safeLoadFile)(filePath, schema, l(o)),
+        safeLoadSync: (filePath, o) => (0, load_1.safeLoadFileSync)(filePath, schema, l(o)),
+        parse: (text, o) => (0, parse_1.parseString)(schema, text, l(o)),
+        save: (filePath, value, o) => (0, save_1.saveFile)(filePath, schema, value, s(o)),
+        saveSync: (filePath, value, o) => (0, save_1.saveFileSync)(filePath, schema, value, s(o)),
+        serialize: (value, o) => (0, serialize_1.serializeAsync)(schema, value, Object.assign(Object.assign({}, defaults.save), o)),
+    };
+}
+/**
+ * Recursively replace ${VAR} and ${VAR:-fallback} in string values.
+ * For a `preprocess` hook use interpolateEnvHook(): a hook's second argument is the
+ * PreprocessContext, which this function would read as `env`. Note results are strings,
+ * so use z.coerce.* in the schema for numeric/boolean fields filled from env vars.
+ */
+function interpolateEnv(value, env = process.env, options = {}) {
+    const pattern = /\$\{([A-Za-z_][A-Za-z0-9_]*)(?::-([^}]*))?\}/g;
+    const walk = (v) => {
+        if (typeof v === "string") {
+            return v.replace(pattern, (_m, name, fallback) => {
+                const found = env[name];
+                if (found !== undefined && found !== "")
+                    return found;
+                if (fallback !== undefined)
+                    return fallback;
+                if (options.strict)
+                    throw new Error(`Environment variable "${name}" is not set`);
+                return "";
+            });
+        }
+        if (Array.isArray(v))
+            return v.map(walk);
+        if ((0, util_1.isPlainObject)(v))
+            return Object.fromEntries(Object.entries(v).map(([k, x]) => [k, walk(x)]));
+        return v;
+    };
+    return walk(value);
+}
+/** A `preprocess` hook that runs interpolateEnv over the parsed data: { preprocess: interpolateEnvHook() }. */
+function interpolateEnvHook(env = process.env, options = {}) {
+    return (raw) => interpolateEnv(raw, env, options);
+}

package/build/files/layered.d.ts

@@ -0,0 +1,44 @@
+import * as z from "zod";
+import { DiscoverOptions, FileLayer, LayeredLoadOptions, LayeredResult, LoadOptions, SafeResult } from "./types";
+/**
+ * Find every existing `fileName` (a name or a relative path such as `.tool/config.yaml`) from
+ * `startDir` upwards, then among `fallbacks`. Results are ordered highest precedence first.
+ */
+export declare function discoverLayers(fileName: string, options?: DiscoverOptions): Promise<FileLayer[]>;
+export declare function discoverLayersSync(fileName: string, options?: DiscoverOptions): FileLayer[];
+/**
+ * Load several JSON/YAML files, deep-merge them and validate the result once.
+ * `filePaths` is highest precedence first. Each file is read raw (no schema defaults), so a
+ * lower layer's value is never masked by a default; defaults apply only to keys no layer sets.
+ */
+export declare function loadMergedFiles<S extends z.ZodType>(filePaths: readonly string[], schema: S, options?: LoadOptions): Promise<z.output<S>>;
+export declare function loadMergedFilesSync<S extends z.ZodType>(filePaths: readonly string[], schema: S, options?: LoadOptions): z.output<S>;
+/**
+ * Discover every `fileName` layer (see discoverLayers), merge them and validate.
+ * Precedence: start directory > nearer ancestors > farther ancestors > fallbacks, in order.
+ * With no layers found, the schema validates `{}`, so its defaults apply.
+ */
+export declare function loadLayeredFile<S extends z.ZodType>(fileName: string, schema: S, options?: LayeredLoadOptions): Promise<LayeredResult<z.output<S>>>;
+/** Synchronous variant. Fails if the schema contains async refinements/transforms. */
+export declare function loadLayeredFileSync<S extends z.ZodType>(fileName: string, schema: S, options?: LayeredLoadOptions): LayeredResult<z.output<S>>;
+/** Like loadLayeredFile, but returns a result object instead of throwing SchemaFileError. */
+export declare function safeLoadLayeredFile<S extends z.ZodType>(fileName: string, schema: S, options?: LayeredLoadOptions): Promise<SafeResult<LayeredResult<z.output<S>>>>;
+export declare function safeLoadLayeredFileSync<S extends z.ZodType>(fileName: string, schema: S, options?: LayeredLoadOptions): SafeResult<LayeredResult<z.output<S>>>;
+/**
+ * Bind a schema, file name and default options once, reuse everywhere.
+ * Per-call options are shallow-merged over the defaults, e.g. `config.load({startDir})`.
+ *
+ * @example
+ * const Config = createLayeredFile(ConfigSchema, "tool.yaml", {fallbacks: ["~/.tool/tool.yaml"]});
+ * const {value, layers} = await Config.load();
+ */
+export declare function createLayeredFile<S extends z.ZodType>(schema: S, fileName: string, defaults?: LayeredLoadOptions): {
+    schema: S;
+    fileName: string;
+    discover: (options?: DiscoverOptions) => Promise<FileLayer[]>;
+    discoverSync: (options?: DiscoverOptions) => FileLayer[];
+    load: (options?: LayeredLoadOptions) => Promise<LayeredResult<z.core.output<S>>>;
+    loadSync: (options?: LayeredLoadOptions) => LayeredResult<z.core.output<S>>;
+    safeLoad: (options?: LayeredLoadOptions) => Promise<SafeResult<LayeredResult<z.core.output<S>>>>;
+    safeLoadSync: (options?: LayeredLoadOptions) => SafeResult<LayeredResult<z.core.output<S>>>;
+};