envapt 5.1.1 → 5.2.0-next.1

package/dist/node/Envapter.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"Envapter.cjs","names":["AdvancedMethods","EnvaptError"],"sources":["../../src/Envapter.ts"],"sourcesContent":["import { AdvancedMethods } from './core';\nimport { EnvaptError, EnvaptErrorCodes } from './Error';\n\nexport { EnvaptCache, Environment } from './core';\n\n/**\n * Main configuration class for environment variable management.\n *\n * Provides both static and instance methods for retrieving typed environment variables\n * with support for template resolution, multiple .env files, and environment detection.\n *\n * Extend your own classes from this to define properties with \\@Envapt decorators and get access to environment-variable methods.\n *\n * @example\n * ```ts\n * // Static usage\n * const port = Envapter.getNumber('PORT', 3000);\n * const url = Envapter.get('API_URL', 'http://localhost');\n * const replica = Envapter.get(['READONLY_URL', 'DATABASE_URL'], 'sqlite://memory');\n *\n * // Instance usage\n * const env = new Envapter();\n * const dbUrl = env.get('DATABASE_URL', 'sqlite://memory');\n * const primaryHost = env.get(['PRIMARY_HOST', 'SECONDARY_HOST']);\n * ```\n *\n * @public\n */\nexport class Envapter extends AdvancedMethods {\n    /**\n     * Tagged template literal for resolving environment variables in template strings.\n     *\n     * @example\n     * ```ts\n     * // Given API_HOST=api.example.com and API_PORT=8080 in environment\n     * const endpoint = Envapter.resolve`Connecting to ${'API_HOST'}:${'API_PORT'}`;\n     * // Returns: \"Connecting to api.example.com:8080\"\n     *\n     * // Works with template variables in .env too:\n     * // API_URL=https://${API_HOST}:${API_PORT}\n     * const message = Envapter.resolve`Service endpoint: ${'API_URL'}`;\n     * // Returns: \"Service endpoint: https://api.example.com:8080\"\n     * ```\n     */\n    static resolve(strings: TemplateStringsArray, ...keys: string[]): string {\n        const strict = Envapter.strict;\n        return strings.reduce((result, string, i) => {\n            const envKey = keys[i];\n            if (!envKey) return result + string;\n            const raw = super.get(envKey, '');\n            if (strict && raw.trim() === '') {\n                throw new EnvaptError(\n                    EnvaptErrorCodes.MissingEnvValue,\n                    `Cannot resolve template variable \"\\${${envKey}}\": value is missing or empty.`\n                );\n            }\n            return result + string + raw;\n        }, '');\n    }\n\n    /**\n     * @see {@link Envapter.resolve}\n     */\n    resolve(strings: TemplateStringsArray, ...keys: string[]): string {\n        return Envapter.resolve(strings, ...keys);\n    }\n\n    /**\n     * Assert that one or more environment variables are present and non-empty (post-trim,\n     * after template resolution). Throws `MissingEnvValue` listing every missing key.\n     *\n     * For typed fail-fast in functional code, use `Envapter.getUsing(key, { converter, required: true })`.\n     *\n     * @example\n     * ```ts\n     * Envapter.require('DATABASE_URL');\n     * Envapter.require('DATABASE_URL', 'API_KEY', 'SENTRY_DSN');\n     * ```\n     */\n    static require(...keys: [string, ...string[]]): void {\n        const missing: string[] = [];\n        for (const k of keys) {\n            if (Envapter.resolveAndValidate(k) === undefined) missing.push(k);\n        }\n\n        if (missing.length > 0) {\n            throw new EnvaptError(\n                EnvaptErrorCodes.MissingEnvValue,\n                `Missing required environment variables: ${missing.join(', ')}.`\n            );\n        }\n    }\n\n    private static resolveAndValidate(key: string): string | undefined {\n        const { value } = this.resolveKeyInput(key);\n        if (value === undefined) return undefined;\n        const resolved = this.templateResolver.resolveTemplate(key, value);\n        if (resolved.trim() === '') return undefined;\n        return resolved;\n    }\n\n    /**\n     * @see {@link Envapter.require}\n     */\n    require(...keys: [string, ...string[]]): void {\n        Envapter.require(...keys);\n    }\n}\n"],"mappings":"yJA4BA,IAAa,EAAb,MAAa,UAAiBA,EAAAA,eAAgB,CAgB1C,OAAO,QAAQ,EAA+B,GAAG,EAAwB,CACrE,IAAM,EAAS,EAAS,OACxB,OAAO,EAAQ,QAAQ,EAAQ,EAAQ,IAAM,CACzC,IAAM,EAAS,EAAK,GACpB,GAAI,CAAC,EAAQ,OAAO,EAAS,EAC7B,IAAM,EAAM,MAAM,IAAI,EAAQ,EAAE,EAChC,GAAI,GAAU,EAAI,KAAK,IAAM,GACzB,MAAM,IAAIC,EAAAA,YAAAA,IAEN,wCAAwC,EAAO,+BACnD,EAEJ,OAAO,EAAS,EAAS,CAC7B,EAAG,EAAE,CACT,CAKA,QAAQ,EAA+B,GAAG,EAAwB,CAC9D,OAAO,EAAS,QAAQ,EAAS,GAAG,CAAI,CAC5C,CAcA,OAAO,QAAQ,GAAG,EAAmC,CACjD,IAAM,EAAoB,CAAC,EAC3B,IAAK,IAAM,KAAK,EACR,EAAS,mBAAmB,CAAC,IAAM,IAAA,IAAW,EAAQ,KAAK,CAAC,EAGpE,GAAI,EAAQ,OAAS,EACjB,MAAM,IAAIA,EAAAA,YAAAA,IAEN,2CAA2C,EAAQ,KAAK,IAAI,EAAE,EAClE,CAER,CAEA,OAAe,mBAAmB,EAAiC,CAC/D,GAAM,CAAE,SAAU,KAAK,gBAAgB,CAAG,EAC1C,GAAI,IAAU,IAAA,GAAW,OACzB,IAAM,EAAW,KAAK,iBAAiB,gBAAgB,EAAK,CAAK,EAC7D,KAAS,KAAK,IAAM,GACxB,OAAO,CACX,CAKA,QAAQ,GAAG,EAAmC,CAC1C,EAAS,QAAQ,GAAG,CAAI,CAC5B,CACJ"}

package/dist/node/Envapter.d.mts

@@ -0,0 +1,70 @@
+import { Environment } from "./core/EnvironmentMethods.mjs";
+import { AdvancedMethods } from "./core/AdvancedMethods.mjs";
+
+//#region src/Envapter.d.ts
+/**
+ * Main configuration class for environment variable management.
+ *
+ * Provides both static and instance methods for retrieving typed environment variables
+ * with support for template resolution, multiple .env files, and environment detection.
+ *
+ * Extend your own classes from this to define properties with \@Envapt decorators and get access to environment-variable methods.
+ *
+ * @example
+ * ```ts
+ * // Static usage
+ * const port = Envapter.getNumber('PORT', 3000);
+ * const url = Envapter.get('API_URL', 'http://localhost');
+ * const replica = Envapter.get(['READONLY_URL', 'DATABASE_URL'], 'sqlite://memory');
+ *
+ * // Instance usage
+ * const env = new Envapter();
+ * const dbUrl = env.get('DATABASE_URL', 'sqlite://memory');
+ * const primaryHost = env.get(['PRIMARY_HOST', 'SECONDARY_HOST']);
+ * ```
+ *
+ * @public
+ */
+declare class Envapter extends AdvancedMethods {
+  /**
+   * Tagged template literal for resolving environment variables in template strings.
+   *
+   * @example
+   * ```ts
+   * // Given API_HOST=api.example.com and API_PORT=8080 in environment
+   * const endpoint = Envapter.resolve`Connecting to ${'API_HOST'}:${'API_PORT'}`;
+   * // Returns: "Connecting to api.example.com:8080"
+   *
+   * // Works with template variables in .env too:
+   * // API_URL=https://${API_HOST}:${API_PORT}
+   * const message = Envapter.resolve`Service endpoint: ${'API_URL'}`;
+   * // Returns: "Service endpoint: https://api.example.com:8080"
+   * ```
+   */
+  static resolve(strings: TemplateStringsArray, ...keys: string[]): string;
+  /**
+   * @see {@link Envapter.resolve}
+   */
+  resolve(strings: TemplateStringsArray, ...keys: string[]): string;
+  /**
+   * Assert that one or more environment variables are present and non-empty (post-trim,
+   * after template resolution). Throws `MissingEnvValue` listing every missing key.
+   *
+   * For typed fail-fast in functional code, use `Envapter.getUsing(key, { converter, required: true })`.
+   *
+   * @example
+   * ```ts
+   * Envapter.require('DATABASE_URL');
+   * Envapter.require('DATABASE_URL', 'API_KEY', 'SENTRY_DSN');
+   * ```
+   */
+  static require(...keys: [string, ...string[]]): void;
+  private static resolveAndValidate;
+  /**
+   * @see {@link Envapter.require}
+   */
+  require(...keys: [string, ...string[]]): void;
+}
+//#endregion
+export { Envapter };
+//# sourceMappingURL=Envapter.d.mts.map

package/dist/node/Envapter.mjs

@@ -0,0 +1,2 @@
+import{EnvaptError as e}from"./Error.mjs";import"./core/EnvapterBase.mjs";import"./core/EnvironmentMethods.mjs";import{AdvancedMethods as t}from"./core/AdvancedMethods.mjs";var n=class n extends t{static resolve(t,...r){let i=n.strict;return t.reduce((t,n,a)=>{let o=r[a];if(!o)return t+n;let s=super.get(o,``);if(i&&s.trim()===``)throw new e(305,`Cannot resolve template variable "\${${o}}": value is missing or empty.`);return t+n+s},``)}resolve(e,...t){return n.resolve(e,...t)}static require(...t){let r=[];for(let e of t)n.resolveAndValidate(e)===void 0&&r.push(e);if(r.length>0)throw new e(305,`Missing required environment variables: ${r.join(`, `)}.`)}static resolveAndValidate(e){let{value:t}=this.resolveKeyInput(e);if(t===void 0)return;let n=this.templateResolver.resolveTemplate(e,t);if(n.trim()!==``)return n}require(...e){n.require(...e)}};export{n as Envapter};
+//# sourceMappingURL=Envapter.mjs.map

package/dist/node/Envapter.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"Envapter.mjs","names":[],"sources":["../../src/Envapter.ts"],"sourcesContent":["import { AdvancedMethods } from './core';\nimport { EnvaptError, EnvaptErrorCodes } from './Error';\n\nexport { EnvaptCache, Environment } from './core';\n\n/**\n * Main configuration class for environment variable management.\n *\n * Provides both static and instance methods for retrieving typed environment variables\n * with support for template resolution, multiple .env files, and environment detection.\n *\n * Extend your own classes from this to define properties with \\@Envapt decorators and get access to environment-variable methods.\n *\n * @example\n * ```ts\n * // Static usage\n * const port = Envapter.getNumber('PORT', 3000);\n * const url = Envapter.get('API_URL', 'http://localhost');\n * const replica = Envapter.get(['READONLY_URL', 'DATABASE_URL'], 'sqlite://memory');\n *\n * // Instance usage\n * const env = new Envapter();\n * const dbUrl = env.get('DATABASE_URL', 'sqlite://memory');\n * const primaryHost = env.get(['PRIMARY_HOST', 'SECONDARY_HOST']);\n * ```\n *\n * @public\n */\nexport class Envapter extends AdvancedMethods {\n    /**\n     * Tagged template literal for resolving environment variables in template strings.\n     *\n     * @example\n     * ```ts\n     * // Given API_HOST=api.example.com and API_PORT=8080 in environment\n     * const endpoint = Envapter.resolve`Connecting to ${'API_HOST'}:${'API_PORT'}`;\n     * // Returns: \"Connecting to api.example.com:8080\"\n     *\n     * // Works with template variables in .env too:\n     * // API_URL=https://${API_HOST}:${API_PORT}\n     * const message = Envapter.resolve`Service endpoint: ${'API_URL'}`;\n     * // Returns: \"Service endpoint: https://api.example.com:8080\"\n     * ```\n     */\n    static resolve(strings: TemplateStringsArray, ...keys: string[]): string {\n        const strict = Envapter.strict;\n        return strings.reduce((result, string, i) => {\n            const envKey = keys[i];\n            if (!envKey) return result + string;\n            const raw = super.get(envKey, '');\n            if (strict && raw.trim() === '') {\n                throw new EnvaptError(\n                    EnvaptErrorCodes.MissingEnvValue,\n                    `Cannot resolve template variable \"\\${${envKey}}\": value is missing or empty.`\n                );\n            }\n            return result + string + raw;\n        }, '');\n    }\n\n    /**\n     * @see {@link Envapter.resolve}\n     */\n    resolve(strings: TemplateStringsArray, ...keys: string[]): string {\n        return Envapter.resolve(strings, ...keys);\n    }\n\n    /**\n     * Assert that one or more environment variables are present and non-empty (post-trim,\n     * after template resolution). Throws `MissingEnvValue` listing every missing key.\n     *\n     * For typed fail-fast in functional code, use `Envapter.getUsing(key, { converter, required: true })`.\n     *\n     * @example\n     * ```ts\n     * Envapter.require('DATABASE_URL');\n     * Envapter.require('DATABASE_URL', 'API_KEY', 'SENTRY_DSN');\n     * ```\n     */\n    static require(...keys: [string, ...string[]]): void {\n        const missing: string[] = [];\n        for (const k of keys) {\n            if (Envapter.resolveAndValidate(k) === undefined) missing.push(k);\n        }\n\n        if (missing.length > 0) {\n            throw new EnvaptError(\n                EnvaptErrorCodes.MissingEnvValue,\n                `Missing required environment variables: ${missing.join(', ')}.`\n            );\n        }\n    }\n\n    private static resolveAndValidate(key: string): string | undefined {\n        const { value } = this.resolveKeyInput(key);\n        if (value === undefined) return undefined;\n        const resolved = this.templateResolver.resolveTemplate(key, value);\n        if (resolved.trim() === '') return undefined;\n        return resolved;\n    }\n\n    /**\n     * @see {@link Envapter.require}\n     */\n    require(...keys: [string, ...string[]]): void {\n        Envapter.require(...keys);\n    }\n}\n"],"mappings":"6KA4BA,IAAa,EAAb,MAAa,UAAiB,CAAgB,CAgB1C,OAAO,QAAQ,EAA+B,GAAG,EAAwB,CACrE,IAAM,EAAS,EAAS,OACxB,OAAO,EAAQ,QAAQ,EAAQ,EAAQ,IAAM,CACzC,IAAM,EAAS,EAAK,GACpB,GAAI,CAAC,EAAQ,OAAO,EAAS,EAC7B,IAAM,EAAM,MAAM,IAAI,EAAQ,EAAE,EAChC,GAAI,GAAU,EAAI,KAAK,IAAM,GACzB,MAAM,IAAI,EAAA,IAEN,wCAAwC,EAAO,+BACnD,EAEJ,OAAO,EAAS,EAAS,CAC7B,EAAG,EAAE,CACT,CAKA,QAAQ,EAA+B,GAAG,EAAwB,CAC9D,OAAO,EAAS,QAAQ,EAAS,GAAG,CAAI,CAC5C,CAcA,OAAO,QAAQ,GAAG,EAAmC,CACjD,IAAM,EAAoB,CAAC,EAC3B,IAAK,IAAM,KAAK,EACR,EAAS,mBAAmB,CAAC,IAAM,IAAA,IAAW,EAAQ,KAAK,CAAC,EAGpE,GAAI,EAAQ,OAAS,EACjB,MAAM,IAAI,EAAA,IAEN,2CAA2C,EAAQ,KAAK,IAAI,EAAE,EAClE,CAER,CAEA,OAAe,mBAAmB,EAAiC,CAC/D,GAAM,CAAE,SAAU,KAAK,gBAAgB,CAAG,EAC1C,GAAI,IAAU,IAAA,GAAW,OACzB,IAAM,EAAW,KAAK,iBAAiB,gBAAgB,EAAK,CAAK,EAC7D,KAAS,KAAK,IAAM,GACxB,OAAO,CACX,CAKA,QAAQ,GAAG,EAAmC,CAC1C,EAAS,QAAQ,GAAG,CAAI,CAC5B,CACJ"}

package/dist/node/Error.cjs

@@ -0,0 +1,2 @@
+let e=function(e){return e[e.InvalidFallback=101]=`InvalidFallback`,e[e.InvalidFallbackType=102]=`InvalidFallbackType`,e[e.ArrayFallbackElementTypeMismatch=103]=`ArrayFallbackElementTypeMismatch`,e[e.FallbackConverterTypeMismatch=104]=`FallbackConverterTypeMismatch`,e[e.MalformedTimeFallback=105]=`MalformedTimeFallback`,e[e.InvalidArrayConverterType=201]=`InvalidArrayConverterType`,e[e.InvalidBuiltInConverter=202]=`InvalidBuiltInConverter`,e[e.InvalidCustomConverter=203]=`InvalidCustomConverter`,e[e.InvalidConverterType=204]=`InvalidConverterType`,e[e.PrimitiveCoercionFailed=205]=`PrimitiveCoercionFailed`,e[e.ArrayElementConversionFailed=206]=`ArrayElementConversionFailed`,e[e.EmptyArrayElement=207]=`EmptyArrayElement`,e[e.SchemaValidationFailed=208]=`SchemaValidationFailed`,e[e.SchemaThrew=209]=`SchemaThrew`,e[e.MissingDelimiter=301]=`MissingDelimiter`,e[e.InvalidUserDefinedConfig=302]=`InvalidUserDefinedConfig`,e[e.EnvFilesNotFound=303]=`EnvFilesNotFound`,e[e.InvalidKeyInput=304]=`InvalidKeyInput`,e[e.MissingEnvValue=305]=`MissingEnvValue`,e[e.FileApiUnsupported=306]=`FileApiUnsupported`,e[e.NoSourceBound=307]=`NoSourceBound`,e}({});var t=class extends Error{code;issues;constructor(e,t,n){super(t,n?.cause===void 0?void 0:{cause:n.cause}),this.name=`EnvaptError [${e}]`,this.code=e,this.issues=n?.issues}};exports.EnvaptError=t,exports.EnvaptErrorCodes=e;
+//# sourceMappingURL=Error.cjs.map

package/dist/node/Error.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"Error.cjs","names":[],"sources":["../../src/Error.ts"],"sourcesContent":["/* eslint-disable no-magic-numbers */\nimport type { StandardSchemaV1 } from './StandardSchema';\n\nexport enum EnvaptErrorCodes {\n    // Fallback related errors\n    /** Thrown when an invalid fallback value is provided */\n    InvalidFallback = 101,\n    /** Thrown when fallback value type doesn't match expected converter type */\n    InvalidFallbackType = 102,\n    /** Thrown when array fallback contains elements of wrong type */\n    ArrayFallbackElementTypeMismatch = 103,\n    /** Thrown when fallback type doesn't match the specified converter */\n    FallbackConverterTypeMismatch = 104,\n    /** Thrown when a time-string fallback is malformed (does not match the required `<number><unit>` format) */\n    MalformedTimeFallback = 105,\n\n    // Converter related errors\n    /** Thrown when invalid array converter configuration is provided */\n    InvalidArrayConverterType = 201,\n    /** Thrown when an invalid built-in converter is specified */\n    InvalidBuiltInConverter = 202,\n    /** Thrown when a custom converter is not a function */\n    InvalidCustomConverter = 203,\n    /** Thrown when converter type is not recognized */\n    InvalidConverterType = 204,\n    /** Thrown when primitive type coercion on fallback value fails */\n    PrimitiveCoercionFailed = 205,\n    /** Thrown when an array element fails to convert to the configured element type */\n    ArrayElementConversionFailed = 206,\n    /** Thrown under strict mode when an array element is empty or whitespace only */\n    EmptyArrayElement = 207,\n    /** Thrown when a Standard Schema returns issues for a non-empty env value */\n    SchemaValidationFailed = 208,\n    /** Thrown when a Standard Schema's `validate` itself throws (e.g. a refinement that crashes) */\n    SchemaThrew = 209,\n\n    // Other errors\n    /** Thrown when delimiter is missing in array converter configuration */\n    // This doesn't happen because 203 is thrown when object without delimiter is passed\n    MissingDelimiter = 301,\n    /** Thrown when invalid user-defined configuration is provided */\n    InvalidUserDefinedConfig = 302,\n    /** Thrown when specified environment files don't exist */\n    EnvFilesNotFound = 303,\n    /** Thrown when no valid environment key is provided */\n    InvalidKeyInput = 304,\n    /** Thrown when a required environment value is missing or empty (post-trim) */\n    MissingEnvValue = 305,\n    /** Thrown when a file-based API (envPaths, baseDir, configureProfiles) is used on a source without filesystem support */\n    FileApiUnsupported = 306,\n    /** Thrown when an environment value is read before a source is bound via Envapter.useSource */\n    NoSourceBound = 307\n}\n\ninterface EnvaptErrorOptions {\n    issues?: readonly StandardSchemaV1.Issue[];\n    cause?: unknown;\n}\n\n/**\n * Custom error for better DX and debugging when using Envapt.\n *\n * @example\n * ```ts\n * throw new EnvaptError(EnvaptErrorCodes.InvalidFallback, \"Invalid fallback value provided for environment variable.\");\n * ```\n */\nexport class EnvaptError extends Error {\n    public readonly code: EnvaptErrorCodes;\n    /**\n     * Populated only for {@link EnvaptErrorCodes.SchemaValidationFailed} (208). For every other\n     * code this is `undefined`. Lets callers do `if (err.code === 208) err.issues?.forEach(...)`\n     * without a type cast.\n     */\n    public readonly issues: readonly StandardSchemaV1.Issue[] | undefined;\n\n    constructor(code: EnvaptErrorCodes, message: string, options?: EnvaptErrorOptions) {\n        super(message, options?.cause !== undefined ? { cause: options.cause } : undefined);\n        this.name = `EnvaptError [${code}]`;\n        this.code = code;\n        this.issues = options?.issues;\n    }\n}\n"],"mappings":"AAGA,IAAY,EAAL,SAAA,EAAA,OAGH,GAAA,EAAA,gBAAA,KAAA,kBAEA,EAAA,EAAA,oBAAA,KAAA,sBAEA,EAAA,EAAA,iCAAA,KAAA,mCAEA,EAAA,EAAA,8BAAA,KAAA,gCAEA,EAAA,EAAA,sBAAA,KAAA,wBAIA,EAAA,EAAA,0BAAA,KAAA,4BAEA,EAAA,EAAA,wBAAA,KAAA,0BAEA,EAAA,EAAA,uBAAA,KAAA,yBAEA,EAAA,EAAA,qBAAA,KAAA,uBAEA,EAAA,EAAA,wBAAA,KAAA,0BAEA,EAAA,EAAA,6BAAA,KAAA,+BAEA,EAAA,EAAA,kBAAA,KAAA,oBAEA,EAAA,EAAA,uBAAA,KAAA,yBAEA,EAAA,EAAA,YAAA,KAAA,cAKA,EAAA,EAAA,iBAAA,KAAA,mBAEA,EAAA,EAAA,yBAAA,KAAA,2BAEA,EAAA,EAAA,iBAAA,KAAA,mBAEA,EAAA,EAAA,gBAAA,KAAA,kBAEA,EAAA,EAAA,gBAAA,KAAA,kBAEA,EAAA,EAAA,mBAAA,KAAA,qBAEA,EAAA,EAAA,cAAA,KAAA,iBACJ,EAAA,CAAA,CAAA,EAeA,IAAa,EAAb,cAAiC,KAAM,CACnC,KAMA,OAEA,YAAY,EAAwB,EAAiB,EAA8B,CAC/E,MAAM,EAAS,GAAS,QAAU,IAAA,GAAuC,IAAA,GAA3B,CAAE,MAAO,EAAQ,KAAM,CAAa,EAClF,KAAK,KAAO,gBAAgB,EAAK,GACjC,KAAK,KAAO,EACZ,KAAK,OAAS,GAAS,MAC3B,CACJ"}

package/dist/{Error.d.cts → node/Error.d.cts}

@@ -10,7 +10,7 @@ declare enum EnvaptErrorCodes {
   ArrayFallbackElementTypeMismatch = 103,
   /** Thrown when fallback type doesn't match the specified converter */
   FallbackConverterTypeMismatch = 104,
-  /** Thrown when a time-string fallback is malformed (does not match the required `<integer><unit>` format) */
+  /** Thrown when a time-string fallback is malformed (does not match the required `<number><unit>` format) */
   MalformedTimeFallback = 105,
   /** Thrown when invalid array converter configuration is provided */
   InvalidArrayConverterType = 201,
@@ -39,7 +39,11 @@ declare enum EnvaptErrorCodes {
   /** Thrown when no valid environment key is provided */
   InvalidKeyInput = 304,
   /** Thrown when a required environment value is missing or empty (post-trim) */
-  MissingEnvValue = 305
+  MissingEnvValue = 305,
+  /** Thrown when a file-based API (envPaths, baseDir, configureProfiles) is used on a source without filesystem support */
+  FileApiUnsupported = 306,
+  /** Thrown when an environment value is read before a source is bound via Envapter.useSource */
+  NoSourceBound = 307
 }
 interface EnvaptErrorOptions {
   issues?: readonly StandardSchemaV1.Issue[];

package/dist/node/Error.d.mts

@@ -0,0 +1,72 @@
+import { StandardSchemaV1 } from "./StandardSchema.mjs";
+
+//#region src/Error.d.ts
+declare enum EnvaptErrorCodes {
+  /** Thrown when an invalid fallback value is provided */
+  InvalidFallback = 101,
+  /** Thrown when fallback value type doesn't match expected converter type */
+  InvalidFallbackType = 102,
+  /** Thrown when array fallback contains elements of wrong type */
+  ArrayFallbackElementTypeMismatch = 103,
+  /** Thrown when fallback type doesn't match the specified converter */
+  FallbackConverterTypeMismatch = 104,
+  /** Thrown when a time-string fallback is malformed (does not match the required `<number><unit>` format) */
+  MalformedTimeFallback = 105,
+  /** Thrown when invalid array converter configuration is provided */
+  InvalidArrayConverterType = 201,
+  /** Thrown when an invalid built-in converter is specified */
+  InvalidBuiltInConverter = 202,
+  /** Thrown when a custom converter is not a function */
+  InvalidCustomConverter = 203,
+  /** Thrown when converter type is not recognized */
+  InvalidConverterType = 204,
+  /** Thrown when primitive type coercion on fallback value fails */
+  PrimitiveCoercionFailed = 205,
+  /** Thrown when an array element fails to convert to the configured element type */
+  ArrayElementConversionFailed = 206,
+  /** Thrown under strict mode when an array element is empty or whitespace only */
+  EmptyArrayElement = 207,
+  /** Thrown when a Standard Schema returns issues for a non-empty env value */
+  SchemaValidationFailed = 208,
+  /** Thrown when a Standard Schema's `validate` itself throws (e.g. a refinement that crashes) */
+  SchemaThrew = 209,
+  /** Thrown when delimiter is missing in array converter configuration */
+  MissingDelimiter = 301,
+  /** Thrown when invalid user-defined configuration is provided */
+  InvalidUserDefinedConfig = 302,
+  /** Thrown when specified environment files don't exist */
+  EnvFilesNotFound = 303,
+  /** Thrown when no valid environment key is provided */
+  InvalidKeyInput = 304,
+  /** Thrown when a required environment value is missing or empty (post-trim) */
+  MissingEnvValue = 305,
+  /** Thrown when a file-based API (envPaths, baseDir, configureProfiles) is used on a source without filesystem support */
+  FileApiUnsupported = 306,
+  /** Thrown when an environment value is read before a source is bound via Envapter.useSource */
+  NoSourceBound = 307
+}
+interface EnvaptErrorOptions {
+  issues?: readonly StandardSchemaV1.Issue[];
+  cause?: unknown;
+}
+/**
+ * Custom error for better DX and debugging when using Envapt.
+ *
+ * @example
+ * ```ts
+ * throw new EnvaptError(EnvaptErrorCodes.InvalidFallback, "Invalid fallback value provided for environment variable.");
+ * ```
+ */
+declare class EnvaptError extends Error {
+  readonly code: EnvaptErrorCodes;
+  /**
+   * Populated only for {@link EnvaptErrorCodes.SchemaValidationFailed} (208). For every other
+   * code this is `undefined`. Lets callers do `if (err.code === 208) err.issues?.forEach(...)`
+   * without a type cast.
+   */
+  readonly issues: readonly StandardSchemaV1.Issue[] | undefined;
+  constructor(code: EnvaptErrorCodes, message: string, options?: EnvaptErrorOptions);
+}
+//#endregion
+export { EnvaptError, EnvaptErrorCodes };
+//# sourceMappingURL=Error.d.mts.map

package/dist/{Error.cjs → node/Error.mjs}

@@ -1,2 +1,2 @@
-let e=function(e){return e[e.InvalidFallback=101]=`InvalidFallback`,e[e.InvalidFallbackType=102]=`InvalidFallbackType`,e[e.ArrayFallbackElementTypeMismatch=103]=`ArrayFallbackElementTypeMismatch`,e[e.FallbackConverterTypeMismatch=104]=`FallbackConverterTypeMismatch`,e[e.MalformedTimeFallback=105]=`MalformedTimeFallback`,e[e.InvalidArrayConverterType=201]=`InvalidArrayConverterType`,e[e.InvalidBuiltInConverter=202]=`InvalidBuiltInConverter`,e[e.InvalidCustomConverter=203]=`InvalidCustomConverter`,e[e.InvalidConverterType=204]=`InvalidConverterType`,e[e.PrimitiveCoercionFailed=205]=`PrimitiveCoercionFailed`,e[e.ArrayElementConversionFailed=206]=`ArrayElementConversionFailed`,e[e.EmptyArrayElement=207]=`EmptyArrayElement`,e[e.SchemaValidationFailed=208]=`SchemaValidationFailed`,e[e.SchemaThrew=209]=`SchemaThrew`,e[e.MissingDelimiter=301]=`MissingDelimiter`,e[e.InvalidUserDefinedConfig=302]=`InvalidUserDefinedConfig`,e[e.EnvFilesNotFound=303]=`EnvFilesNotFound`,e[e.InvalidKeyInput=304]=`InvalidKeyInput`,e[e.MissingEnvValue=305]=`MissingEnvValue`,e}({});var t=class extends Error{code;issues;constructor(e,t,n){super(t,n?.cause===void 0?void 0:{cause:n.cause}),this.name=`EnvaptError [${e}]`,this.code=e,this.issues=n?.issues}};exports.EnvaptError=t,exports.EnvaptErrorCodes=e;
-//# sourceMappingURL=Error.cjs.map
+let e=function(e){return e[e.InvalidFallback=101]=`InvalidFallback`,e[e.InvalidFallbackType=102]=`InvalidFallbackType`,e[e.ArrayFallbackElementTypeMismatch=103]=`ArrayFallbackElementTypeMismatch`,e[e.FallbackConverterTypeMismatch=104]=`FallbackConverterTypeMismatch`,e[e.MalformedTimeFallback=105]=`MalformedTimeFallback`,e[e.InvalidArrayConverterType=201]=`InvalidArrayConverterType`,e[e.InvalidBuiltInConverter=202]=`InvalidBuiltInConverter`,e[e.InvalidCustomConverter=203]=`InvalidCustomConverter`,e[e.InvalidConverterType=204]=`InvalidConverterType`,e[e.PrimitiveCoercionFailed=205]=`PrimitiveCoercionFailed`,e[e.ArrayElementConversionFailed=206]=`ArrayElementConversionFailed`,e[e.EmptyArrayElement=207]=`EmptyArrayElement`,e[e.SchemaValidationFailed=208]=`SchemaValidationFailed`,e[e.SchemaThrew=209]=`SchemaThrew`,e[e.MissingDelimiter=301]=`MissingDelimiter`,e[e.InvalidUserDefinedConfig=302]=`InvalidUserDefinedConfig`,e[e.EnvFilesNotFound=303]=`EnvFilesNotFound`,e[e.InvalidKeyInput=304]=`InvalidKeyInput`,e[e.MissingEnvValue=305]=`MissingEnvValue`,e[e.FileApiUnsupported=306]=`FileApiUnsupported`,e[e.NoSourceBound=307]=`NoSourceBound`,e}({});var t=class extends Error{code;issues;constructor(e,t,n){super(t,n?.cause===void 0?void 0:{cause:n.cause}),this.name=`EnvaptError [${e}]`,this.code=e,this.issues=n?.issues}};export{t as EnvaptError,e as EnvaptErrorCodes};
+//# sourceMappingURL=Error.mjs.map

package/dist/node/Error.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"Error.mjs","names":[],"sources":["../../src/Error.ts"],"sourcesContent":["/* eslint-disable no-magic-numbers */\nimport type { StandardSchemaV1 } from './StandardSchema';\n\nexport enum EnvaptErrorCodes {\n    // Fallback related errors\n    /** Thrown when an invalid fallback value is provided */\n    InvalidFallback = 101,\n    /** Thrown when fallback value type doesn't match expected converter type */\n    InvalidFallbackType = 102,\n    /** Thrown when array fallback contains elements of wrong type */\n    ArrayFallbackElementTypeMismatch = 103,\n    /** Thrown when fallback type doesn't match the specified converter */\n    FallbackConverterTypeMismatch = 104,\n    /** Thrown when a time-string fallback is malformed (does not match the required `<number><unit>` format) */\n    MalformedTimeFallback = 105,\n\n    // Converter related errors\n    /** Thrown when invalid array converter configuration is provided */\n    InvalidArrayConverterType = 201,\n    /** Thrown when an invalid built-in converter is specified */\n    InvalidBuiltInConverter = 202,\n    /** Thrown when a custom converter is not a function */\n    InvalidCustomConverter = 203,\n    /** Thrown when converter type is not recognized */\n    InvalidConverterType = 204,\n    /** Thrown when primitive type coercion on fallback value fails */\n    PrimitiveCoercionFailed = 205,\n    /** Thrown when an array element fails to convert to the configured element type */\n    ArrayElementConversionFailed = 206,\n    /** Thrown under strict mode when an array element is empty or whitespace only */\n    EmptyArrayElement = 207,\n    /** Thrown when a Standard Schema returns issues for a non-empty env value */\n    SchemaValidationFailed = 208,\n    /** Thrown when a Standard Schema's `validate` itself throws (e.g. a refinement that crashes) */\n    SchemaThrew = 209,\n\n    // Other errors\n    /** Thrown when delimiter is missing in array converter configuration */\n    // This doesn't happen because 203 is thrown when object without delimiter is passed\n    MissingDelimiter = 301,\n    /** Thrown when invalid user-defined configuration is provided */\n    InvalidUserDefinedConfig = 302,\n    /** Thrown when specified environment files don't exist */\n    EnvFilesNotFound = 303,\n    /** Thrown when no valid environment key is provided */\n    InvalidKeyInput = 304,\n    /** Thrown when a required environment value is missing or empty (post-trim) */\n    MissingEnvValue = 305,\n    /** Thrown when a file-based API (envPaths, baseDir, configureProfiles) is used on a source without filesystem support */\n    FileApiUnsupported = 306,\n    /** Thrown when an environment value is read before a source is bound via Envapter.useSource */\n    NoSourceBound = 307\n}\n\ninterface EnvaptErrorOptions {\n    issues?: readonly StandardSchemaV1.Issue[];\n    cause?: unknown;\n}\n\n/**\n * Custom error for better DX and debugging when using Envapt.\n *\n * @example\n * ```ts\n * throw new EnvaptError(EnvaptErrorCodes.InvalidFallback, \"Invalid fallback value provided for environment variable.\");\n * ```\n */\nexport class EnvaptError extends Error {\n    public readonly code: EnvaptErrorCodes;\n    /**\n     * Populated only for {@link EnvaptErrorCodes.SchemaValidationFailed} (208). For every other\n     * code this is `undefined`. Lets callers do `if (err.code === 208) err.issues?.forEach(...)`\n     * without a type cast.\n     */\n    public readonly issues: readonly StandardSchemaV1.Issue[] | undefined;\n\n    constructor(code: EnvaptErrorCodes, message: string, options?: EnvaptErrorOptions) {\n        super(message, options?.cause !== undefined ? { cause: options.cause } : undefined);\n        this.name = `EnvaptError [${code}]`;\n        this.code = code;\n        this.issues = options?.issues;\n    }\n}\n"],"mappings":"AAGA,IAAY,EAAL,SAAA,EAAA,OAGH,GAAA,EAAA,gBAAA,KAAA,kBAEA,EAAA,EAAA,oBAAA,KAAA,sBAEA,EAAA,EAAA,iCAAA,KAAA,mCAEA,EAAA,EAAA,8BAAA,KAAA,gCAEA,EAAA,EAAA,sBAAA,KAAA,wBAIA,EAAA,EAAA,0BAAA,KAAA,4BAEA,EAAA,EAAA,wBAAA,KAAA,0BAEA,EAAA,EAAA,uBAAA,KAAA,yBAEA,EAAA,EAAA,qBAAA,KAAA,uBAEA,EAAA,EAAA,wBAAA,KAAA,0BAEA,EAAA,EAAA,6BAAA,KAAA,+BAEA,EAAA,EAAA,kBAAA,KAAA,oBAEA,EAAA,EAAA,uBAAA,KAAA,yBAEA,EAAA,EAAA,YAAA,KAAA,cAKA,EAAA,EAAA,iBAAA,KAAA,mBAEA,EAAA,EAAA,yBAAA,KAAA,2BAEA,EAAA,EAAA,iBAAA,KAAA,mBAEA,EAAA,EAAA,gBAAA,KAAA,kBAEA,EAAA,EAAA,gBAAA,KAAA,kBAEA,EAAA,EAAA,mBAAA,KAAA,qBAEA,EAAA,EAAA,cAAA,KAAA,iBACJ,EAAA,CAAA,CAAA,EAeA,IAAa,EAAb,cAAiC,KAAM,CACnC,KAMA,OAEA,YAAY,EAAwB,EAAiB,EAA8B,CAC/E,MAAM,EAAS,GAAS,QAAU,IAAA,GAAuC,IAAA,GAA3B,CAAE,MAAO,EAAQ,KAAM,CAAa,EAClF,KAAK,KAAO,gBAAgB,EAAK,GACjC,KAAK,KAAO,EACZ,KAAK,OAAS,GAAS,MAC3B,CACJ"}

package/dist/node/NodeEnvapter.cjs

@@ -0,0 +1,2 @@
+const e=require("./_virtual/_rolldown/runtime.cjs"),t=require("./Validators.cjs"),n=require("./runtime.cjs"),r=require("./core/EnvapterBase.cjs"),i=require("./core/EnvironmentMethods.cjs"),a=require("./Envapter.cjs"),o=require("./sources/NodeEnvSource.cjs");let s=require("node:process");s=e.__toESM(s,1);var c=class e extends a.Envapter{static{n.setRuntimeSink(e=>s.default.stderr.write(`${e}\n`)),e.useSource(new o.NodeEnvSource)}static set envPaths(e){this.assertFileApiSupported(`envPaths`,r.EnvapterBase._source);let n=Array.isArray(e)?e:[e];t.Validator.validateEnvFilesExist(n.map(e=>this.resolveAgainstBase(e)),e=>this.sourceFileExists(e)),r.EnvapterBase._envPaths=n,r.EnvapterBase._envPathsExplicitlySet=!0,this.refreshCache()}static get envPaths(){return r.EnvapterBase._envPaths}static set baseDir(e){let t=r.EnvapterBase._source;this.assertFileApiSupported(`baseDir`,t),r.EnvapterBase._baseDir=e===void 0?void 0:t.normalizeBaseDir(e),this.refreshCache()}static get baseDir(){return r.EnvapterBase._baseDir}static set envFileOptions(e){t.Validator.validateEnvFileOptions(e),r.EnvapterBase._userDefinedEnvFileOptions=e,this.refreshCache()}static get envFileOptions(){return r.EnvapterBase._userDefinedEnvFileOptions}static configureProfiles(e){this.assertFileApiSupported(`configureProfiles`,r.EnvapterBase._source),i.EnvironmentMethods._profiles=e,this.refreshCache()}static resetProfiles(){i.EnvironmentMethods._profiles=void 0,r.EnvapterBase._envPaths=[`.env`],r.EnvapterBase._envPathsExplicitlySet=!1,this._environmentExplicitlySet=!1,this._environment=void 0,this.refreshCache()}};exports.NodeEnvapter=c;
+//# sourceMappingURL=NodeEnvapter.cjs.map

package/dist/node/NodeEnvapter.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"NodeEnvapter.cjs","names":["Envapter","process","NodeEnvSource","EnvapterBase"],"sources":["../../src/NodeEnvapter.ts"],"sourcesContent":["import process from 'node:process';\n\nimport { EnvapterBase } from './core/EnvapterBase';\nimport { EnvironmentMethods } from './core/EnvironmentMethods';\nimport { Envapter } from './Envapter';\nimport { setRuntimeSink } from './runtime';\nimport { NodeEnvSource } from './sources/NodeEnvSource';\nimport { Validator } from './Validators';\n\nimport type { EnvFileOptions } from './Dotenv';\nimport type { ProfilesConfig } from './types';\n\n/**\n * The Node/Bun/Deno facade: {@link Envapter} plus the filesystem-only configuration APIs (`.env`\n * path selection, base directory, dotenv options, and per-environment profiles). The browser and\n * Workers builds export the base {@link Envapter} without these, so calling one where there is no\n * filesystem is a compile error (and a thrown {@link EnvaptError} when types are bypassed).\n *\n * Writes target the state-owning class (`EnvapterBase`/`EnvironmentMethods`), not `this`: the engine\n * reads that state through `EnvapterBase`-anchored paths, so a subclass own-property would be invisible.\n * @public\n */\nexport class NodeEnvapter extends Envapter {\n    // A static block (not a top-level statement in a separate entry) keeps the bind intrinsic to this\n    // class: tree-shaken out of `import { EnvaptError }`, run whenever `Envapter` is referenced, with no\n    // sideEffects entry. Depends on the es2022 native static-block emit; lowering the target defeats it.\n    static {\n        setRuntimeSink((line) => process.stderr.write(`${line}\\n`));\n        NodeEnvapter.useSource(new NodeEnvSource());\n    }\n\n    /**\n     * Set custom .env file paths. Accepts either a single path or array of paths.\n     * Setting new paths clears the cache and reloads environment variables.\n     *\n     * When set, this takes absolute precedence. The dotenv-flow auto-cascade and any\n     * `Envapter.configureProfiles` configuration are ignored.\n     */\n    static set envPaths(paths: string[] | string) {\n        this.assertFileApiSupported('envPaths', EnvapterBase._source);\n        const newPaths = Array.isArray(paths) ? paths : [paths];\n        Validator.validateEnvFilesExist(\n            newPaths.map((p) => this.resolveAgainstBase(p)),\n            (p) => this.sourceFileExists(p)\n        );\n\n        EnvapterBase._envPaths = newPaths;\n        EnvapterBase._envPathsExplicitlySet = true;\n        this.refreshCache();\n    }\n\n    /**\n     * Get currently configured .env file paths\n     */\n    static get envPaths(): string[] {\n        return EnvapterBase._envPaths;\n    }\n\n    /**\n     * Set a base directory that relative `.env` paths resolve against instead of\n     * `process.cwd()`: the auto-cascade, `Envapter.configureProfiles` paths, and relative\n     * `envPaths`. Absolute paths always bypass it. Pass a directory, or a module URL\n     * (`import.meta.url`, ESM) / `import.meta.dirname` / `__dirname` (CJS) to anchor\n     * resolution next to the calling file regardless of launch directory.\n     *\n     * Set this before `envPaths` so relative `envPaths` validate against the right directory.\n     * Unset (`undefined`) restores `process.cwd()` resolution.\n     */\n    static set baseDir(value: string | URL | undefined) {\n        const source = EnvapterBase._source;\n        this.assertFileApiSupported('baseDir', source);\n        EnvapterBase._baseDir = value === undefined ? undefined : source.normalizeBaseDir(value);\n        this.refreshCache();\n    }\n\n    static get baseDir(): string | undefined {\n        return EnvapterBase._baseDir;\n    }\n\n    static set envFileOptions(config: EnvFileOptions) {\n        Validator.validateEnvFileOptions(config);\n        EnvapterBase._userDefinedEnvFileOptions = config;\n        this.refreshCache();\n    }\n\n    /**\n     * Get current dotenv configuration options\n     */\n    static get envFileOptions(): EnvFileOptions {\n        return EnvapterBase._userDefinedEnvFileOptions;\n    }\n\n    /**\n     * Configure per-environment `.env` path overrides on top of the dotenv-flow auto-cascade.\n     *\n     * When set, each `Environment` key's `paths` are loaded at higher precedence than the\n     * cascade for that environment. Unspecified environments still use the cascade as-is.\n     * Set `useDefaults: false` to disable the cascade entirely (load only the configured paths).\n     *\n     * Setting an explicit `Envapter.envPaths` value at any point overrides this configuration.\n     *\n     * @example\n     * ```ts\n     * Envapter.configureProfiles({\n     *   [Environment.Staging]: { paths: 'config/staging.env' },\n     *   [Environment.Production]: { paths: ['config/prod.env', 'secrets/prod.env'] }\n     * });\n     * ```\n     */\n    static configureProfiles(config: ProfilesConfig): void {\n        this.assertFileApiSupported('configureProfiles', EnvapterBase._source);\n        EnvironmentMethods._profiles = config;\n        this.refreshCache();\n    }\n\n    /**\n     * Reset all path-resolution configuration to defaults: clears any prior\n     * `Envapter.configureProfiles` call AND any explicit `Envapter.envPaths` assignment.\n     * Returns the resolver to the pure dotenv-flow cascade.\n     */\n    static resetProfiles(): void {\n        EnvironmentMethods._profiles = undefined;\n        EnvapterBase._envPaths = ['.env'];\n        EnvapterBase._envPathsExplicitlySet = false;\n        // Clear via `this`, not EnvironmentMethods: determineEnvironment writes `_environment*` via\n        // `this`, so a base-anchored clear would leave a subclass own-property shadowing it.\n        this._environmentExplicitlySet = false;\n        this._environment = undefined;\n        this.refreshCache();\n    }\n}\n"],"mappings":"iTAsBA,IAAa,EAAb,MAAa,UAAqBA,EAAAA,QAAS,CAIvC,OACI,EAAA,eAAgB,GAASC,EAAAA,QAAQ,OAAO,MAAM,GAAG,EAAK,GAAG,CAAC,EAC1D,EAAa,UAAU,IAAIC,EAAAA,aAAe,CAC9C,CASA,WAAW,SAAS,EAA0B,CAC1C,KAAK,uBAAuB,WAAYC,EAAAA,aAAa,OAAO,EAC5D,IAAM,EAAW,MAAM,QAAQ,CAAK,EAAI,EAAQ,CAAC,CAAK,EACtD,EAAA,UAAU,sBACN,EAAS,IAAK,GAAM,KAAK,mBAAmB,CAAC,CAAC,EAC7C,GAAM,KAAK,iBAAiB,CAAC,CAClC,EAEA,EAAA,aAAa,UAAY,EACzB,EAAA,aAAa,uBAAyB,GACtC,KAAK,aAAa,CACtB,CAKA,WAAW,UAAqB,CAC5B,OAAOA,EAAAA,aAAa,SACxB,CAYA,WAAW,QAAQ,EAAiC,CAChD,IAAM,EAASA,EAAAA,aAAa,QAC5B,KAAK,uBAAuB,UAAW,CAAM,EAC7C,EAAA,aAAa,SAAW,IAAU,IAAA,GAAY,IAAA,GAAY,EAAO,iBAAiB,CAAK,EACvF,KAAK,aAAa,CACtB,CAEA,WAAW,SAA8B,CACrC,OAAOA,EAAAA,aAAa,QACxB,CAEA,WAAW,eAAe,EAAwB,CAC9C,EAAA,UAAU,uBAAuB,CAAM,EACvC,EAAA,aAAa,2BAA6B,EAC1C,KAAK,aAAa,CACtB,CAKA,WAAW,gBAAiC,CACxC,OAAOA,EAAAA,aAAa,0BACxB,CAmBA,OAAO,kBAAkB,EAA8B,CACnD,KAAK,uBAAuB,oBAAqBA,EAAAA,aAAa,OAAO,EACrE,EAAA,mBAAmB,UAAY,EAC/B,KAAK,aAAa,CACtB,CAOA,OAAO,eAAsB,CACzB,EAAA,mBAAmB,UAAY,IAAA,GAC/B,EAAA,aAAa,UAAY,CAAC,MAAM,EAChC,EAAA,aAAa,uBAAyB,GAGtC,KAAK,0BAA4B,GACjC,KAAK,aAAe,IAAA,GACpB,KAAK,aAAa,CACtB,CACJ"}

package/dist/node/NodeEnvapter.d.cts

@@ -0,0 +1,73 @@
+import { EnvFileOptions } from "./Dotenv.cjs";
+import { ProfilesConfig } from "./types/Options.cjs";
+import { Envapter } from "./Envapter.cjs";
+
+//#region src/NodeEnvapter.d.ts
+/**
+ * The Node/Bun/Deno facade: {@link Envapter} plus the filesystem-only configuration APIs (`.env`
+ * path selection, base directory, dotenv options, and per-environment profiles). The browser and
+ * Workers builds export the base {@link Envapter} without these, so calling one where there is no
+ * filesystem is a compile error (and a thrown {@link EnvaptError} when types are bypassed).
+ *
+ * Writes target the state-owning class (`EnvapterBase`/`EnvironmentMethods`), not `this`: the engine
+ * reads that state through `EnvapterBase`-anchored paths, so a subclass own-property would be invisible.
+ * @public
+ */
+declare class NodeEnvapter extends Envapter {
+  /**
+   * Set custom .env file paths. Accepts either a single path or array of paths.
+   * Setting new paths clears the cache and reloads environment variables.
+   *
+   * When set, this takes absolute precedence. The dotenv-flow auto-cascade and any
+   * `Envapter.configureProfiles` configuration are ignored.
+   */
+  static set envPaths(paths: string[] | string);
+  /**
+   * Get currently configured .env file paths
+   */
+  static get envPaths(): string[];
+  /**
+   * Set a base directory that relative `.env` paths resolve against instead of
+   * `process.cwd()`: the auto-cascade, `Envapter.configureProfiles` paths, and relative
+   * `envPaths`. Absolute paths always bypass it. Pass a directory, or a module URL
+   * (`import.meta.url`, ESM) / `import.meta.dirname` / `__dirname` (CJS) to anchor
+   * resolution next to the calling file regardless of launch directory.
+   *
+   * Set this before `envPaths` so relative `envPaths` validate against the right directory.
+   * Unset (`undefined`) restores `process.cwd()` resolution.
+   */
+  static set baseDir(value: string | URL | undefined);
+  static get baseDir(): string | undefined;
+  static set envFileOptions(config: EnvFileOptions);
+  /**
+   * Get current dotenv configuration options
+   */
+  static get envFileOptions(): EnvFileOptions;
+  /**
+   * Configure per-environment `.env` path overrides on top of the dotenv-flow auto-cascade.
+   *
+   * When set, each `Environment` key's `paths` are loaded at higher precedence than the
+   * cascade for that environment. Unspecified environments still use the cascade as-is.
+   * Set `useDefaults: false` to disable the cascade entirely (load only the configured paths).
+   *
+   * Setting an explicit `Envapter.envPaths` value at any point overrides this configuration.
+   *
+   * @example
+   * ```ts
+   * Envapter.configureProfiles({
+   *   [Environment.Staging]: { paths: 'config/staging.env' },
+   *   [Environment.Production]: { paths: ['config/prod.env', 'secrets/prod.env'] }
+   * });
+   * ```
+   */
+  static configureProfiles(config: ProfilesConfig): void;
+  /**
+   * Reset all path-resolution configuration to defaults: clears any prior
+   * `Envapter.configureProfiles` call AND any explicit `Envapter.envPaths` assignment.
+   * Returns the resolver to the pure dotenv-flow cascade.
+   */
+  static resetProfiles(): void;
+}
+//#endregion
+export { NodeEnvapter };
+//# sourceMappingURL=NodeEnvapter.d.cts.map

package/dist/node/NodeEnvapter.d.mts

@@ -0,0 +1,73 @@
+import { EnvFileOptions } from "./Dotenv.mjs";
+import { ProfilesConfig } from "./types/Options.mjs";
+import { Envapter } from "./Envapter.mjs";
+
+//#region src/NodeEnvapter.d.ts
+/**
+ * The Node/Bun/Deno facade: {@link Envapter} plus the filesystem-only configuration APIs (`.env`
+ * path selection, base directory, dotenv options, and per-environment profiles). The browser and
+ * Workers builds export the base {@link Envapter} without these, so calling one where there is no
+ * filesystem is a compile error (and a thrown {@link EnvaptError} when types are bypassed).
+ *
+ * Writes target the state-owning class (`EnvapterBase`/`EnvironmentMethods`), not `this`: the engine
+ * reads that state through `EnvapterBase`-anchored paths, so a subclass own-property would be invisible.
+ * @public
+ */
+declare class NodeEnvapter extends Envapter {
+  /**
+   * Set custom .env file paths. Accepts either a single path or array of paths.
+   * Setting new paths clears the cache and reloads environment variables.
+   *
+   * When set, this takes absolute precedence. The dotenv-flow auto-cascade and any
+   * `Envapter.configureProfiles` configuration are ignored.
+   */
+  static set envPaths(paths: string[] | string);
+  /**
+   * Get currently configured .env file paths
+   */
+  static get envPaths(): string[];
+  /**
+   * Set a base directory that relative `.env` paths resolve against instead of
+   * `process.cwd()`: the auto-cascade, `Envapter.configureProfiles` paths, and relative
+   * `envPaths`. Absolute paths always bypass it. Pass a directory, or a module URL
+   * (`import.meta.url`, ESM) / `import.meta.dirname` / `__dirname` (CJS) to anchor
+   * resolution next to the calling file regardless of launch directory.
+   *
+   * Set this before `envPaths` so relative `envPaths` validate against the right directory.
+   * Unset (`undefined`) restores `process.cwd()` resolution.
+   */
+  static set baseDir(value: string | URL | undefined);
+  static get baseDir(): string | undefined;
+  static set envFileOptions(config: EnvFileOptions);
+  /**
+   * Get current dotenv configuration options
+   */
+  static get envFileOptions(): EnvFileOptions;
+  /**
+   * Configure per-environment `.env` path overrides on top of the dotenv-flow auto-cascade.
+   *
+   * When set, each `Environment` key's `paths` are loaded at higher precedence than the
+   * cascade for that environment. Unspecified environments still use the cascade as-is.
+   * Set `useDefaults: false` to disable the cascade entirely (load only the configured paths).
+   *
+   * Setting an explicit `Envapter.envPaths` value at any point overrides this configuration.
+   *
+   * @example
+   * ```ts
+   * Envapter.configureProfiles({
+   *   [Environment.Staging]: { paths: 'config/staging.env' },
+   *   [Environment.Production]: { paths: ['config/prod.env', 'secrets/prod.env'] }
+   * });
+   * ```
+   */
+  static configureProfiles(config: ProfilesConfig): void;
+  /**
+   * Reset all path-resolution configuration to defaults: clears any prior
+   * `Envapter.configureProfiles` call AND any explicit `Envapter.envPaths` assignment.
+   * Returns the resolver to the pure dotenv-flow cascade.
+   */
+  static resetProfiles(): void;
+}
+//#endregion
+export { NodeEnvapter };
+//# sourceMappingURL=NodeEnvapter.d.mts.map

package/dist/node/NodeEnvapter.mjs

@@ -0,0 +1,2 @@
+import{Validator as e}from"./Validators.mjs";import{setRuntimeSink as t}from"./runtime.mjs";import{EnvapterBase as n}from"./core/EnvapterBase.mjs";import{EnvironmentMethods as r}from"./core/EnvironmentMethods.mjs";import{Envapter as i}from"./Envapter.mjs";import{NodeEnvSource as a}from"./sources/NodeEnvSource.mjs";import o from"node:process";var s=class s extends i{static{t(e=>o.stderr.write(`${e}\n`)),s.useSource(new a)}static set envPaths(t){this.assertFileApiSupported(`envPaths`,n._source);let r=Array.isArray(t)?t:[t];e.validateEnvFilesExist(r.map(e=>this.resolveAgainstBase(e)),e=>this.sourceFileExists(e)),n._envPaths=r,n._envPathsExplicitlySet=!0,this.refreshCache()}static get envPaths(){return n._envPaths}static set baseDir(e){let t=n._source;this.assertFileApiSupported(`baseDir`,t),n._baseDir=e===void 0?void 0:t.normalizeBaseDir(e),this.refreshCache()}static get baseDir(){return n._baseDir}static set envFileOptions(t){e.validateEnvFileOptions(t),n._userDefinedEnvFileOptions=t,this.refreshCache()}static get envFileOptions(){return n._userDefinedEnvFileOptions}static configureProfiles(e){this.assertFileApiSupported(`configureProfiles`,n._source),r._profiles=e,this.refreshCache()}static resetProfiles(){r._profiles=void 0,n._envPaths=[`.env`],n._envPathsExplicitlySet=!1,this._environmentExplicitlySet=!1,this._environment=void 0,this.refreshCache()}};export{s as NodeEnvapter};
+//# sourceMappingURL=NodeEnvapter.mjs.map

package/dist/node/NodeEnvapter.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"NodeEnvapter.mjs","names":[],"sources":["../../src/NodeEnvapter.ts"],"sourcesContent":["import process from 'node:process';\n\nimport { EnvapterBase } from './core/EnvapterBase';\nimport { EnvironmentMethods } from './core/EnvironmentMethods';\nimport { Envapter } from './Envapter';\nimport { setRuntimeSink } from './runtime';\nimport { NodeEnvSource } from './sources/NodeEnvSource';\nimport { Validator } from './Validators';\n\nimport type { EnvFileOptions } from './Dotenv';\nimport type { ProfilesConfig } from './types';\n\n/**\n * The Node/Bun/Deno facade: {@link Envapter} plus the filesystem-only configuration APIs (`.env`\n * path selection, base directory, dotenv options, and per-environment profiles). The browser and\n * Workers builds export the base {@link Envapter} without these, so calling one where there is no\n * filesystem is a compile error (and a thrown {@link EnvaptError} when types are bypassed).\n *\n * Writes target the state-owning class (`EnvapterBase`/`EnvironmentMethods`), not `this`: the engine\n * reads that state through `EnvapterBase`-anchored paths, so a subclass own-property would be invisible.\n * @public\n */\nexport class NodeEnvapter extends Envapter {\n    // A static block (not a top-level statement in a separate entry) keeps the bind intrinsic to this\n    // class: tree-shaken out of `import { EnvaptError }`, run whenever `Envapter` is referenced, with no\n    // sideEffects entry. Depends on the es2022 native static-block emit; lowering the target defeats it.\n    static {\n        setRuntimeSink((line) => process.stderr.write(`${line}\\n`));\n        NodeEnvapter.useSource(new NodeEnvSource());\n    }\n\n    /**\n     * Set custom .env file paths. Accepts either a single path or array of paths.\n     * Setting new paths clears the cache and reloads environment variables.\n     *\n     * When set, this takes absolute precedence. The dotenv-flow auto-cascade and any\n     * `Envapter.configureProfiles` configuration are ignored.\n     */\n    static set envPaths(paths: string[] | string) {\n        this.assertFileApiSupported('envPaths', EnvapterBase._source);\n        const newPaths = Array.isArray(paths) ? paths : [paths];\n        Validator.validateEnvFilesExist(\n            newPaths.map((p) => this.resolveAgainstBase(p)),\n            (p) => this.sourceFileExists(p)\n        );\n\n        EnvapterBase._envPaths = newPaths;\n        EnvapterBase._envPathsExplicitlySet = true;\n        this.refreshCache();\n    }\n\n    /**\n     * Get currently configured .env file paths\n     */\n    static get envPaths(): string[] {\n        return EnvapterBase._envPaths;\n    }\n\n    /**\n     * Set a base directory that relative `.env` paths resolve against instead of\n     * `process.cwd()`: the auto-cascade, `Envapter.configureProfiles` paths, and relative\n     * `envPaths`. Absolute paths always bypass it. Pass a directory, or a module URL\n     * (`import.meta.url`, ESM) / `import.meta.dirname` / `__dirname` (CJS) to anchor\n     * resolution next to the calling file regardless of launch directory.\n     *\n     * Set this before `envPaths` so relative `envPaths` validate against the right directory.\n     * Unset (`undefined`) restores `process.cwd()` resolution.\n     */\n    static set baseDir(value: string | URL | undefined) {\n        const source = EnvapterBase._source;\n        this.assertFileApiSupported('baseDir', source);\n        EnvapterBase._baseDir = value === undefined ? undefined : source.normalizeBaseDir(value);\n        this.refreshCache();\n    }\n\n    static get baseDir(): string | undefined {\n        return EnvapterBase._baseDir;\n    }\n\n    static set envFileOptions(config: EnvFileOptions) {\n        Validator.validateEnvFileOptions(config);\n        EnvapterBase._userDefinedEnvFileOptions = config;\n        this.refreshCache();\n    }\n\n    /**\n     * Get current dotenv configuration options\n     */\n    static get envFileOptions(): EnvFileOptions {\n        return EnvapterBase._userDefinedEnvFileOptions;\n    }\n\n    /**\n     * Configure per-environment `.env` path overrides on top of the dotenv-flow auto-cascade.\n     *\n     * When set, each `Environment` key's `paths` are loaded at higher precedence than the\n     * cascade for that environment. Unspecified environments still use the cascade as-is.\n     * Set `useDefaults: false` to disable the cascade entirely (load only the configured paths).\n     *\n     * Setting an explicit `Envapter.envPaths` value at any point overrides this configuration.\n     *\n     * @example\n     * ```ts\n     * Envapter.configureProfiles({\n     *   [Environment.Staging]: { paths: 'config/staging.env' },\n     *   [Environment.Production]: { paths: ['config/prod.env', 'secrets/prod.env'] }\n     * });\n     * ```\n     */\n    static configureProfiles(config: ProfilesConfig): void {\n        this.assertFileApiSupported('configureProfiles', EnvapterBase._source);\n        EnvironmentMethods._profiles = config;\n        this.refreshCache();\n    }\n\n    /**\n     * Reset all path-resolution configuration to defaults: clears any prior\n     * `Envapter.configureProfiles` call AND any explicit `Envapter.envPaths` assignment.\n     * Returns the resolver to the pure dotenv-flow cascade.\n     */\n    static resetProfiles(): void {\n        EnvironmentMethods._profiles = undefined;\n        EnvapterBase._envPaths = ['.env'];\n        EnvapterBase._envPathsExplicitlySet = false;\n        // Clear via `this`, not EnvironmentMethods: determineEnvironment writes `_environment*` via\n        // `this`, so a base-anchored clear would leave a subclass own-property shadowing it.\n        this._environmentExplicitlySet = false;\n        this._environment = undefined;\n        this.refreshCache();\n    }\n}\n"],"mappings":"wVAsBA,IAAa,EAAb,MAAa,UAAqB,CAAS,CAIvC,OACI,EAAgB,GAAS,EAAQ,OAAO,MAAM,GAAG,EAAK,GAAG,CAAC,EAC1D,EAAa,UAAU,IAAI,CAAe,CAC9C,CASA,WAAW,SAAS,EAA0B,CAC1C,KAAK,uBAAuB,WAAY,EAAa,OAAO,EAC5D,IAAM,EAAW,MAAM,QAAQ,CAAK,EAAI,EAAQ,CAAC,CAAK,EACtD,EAAU,sBACN,EAAS,IAAK,GAAM,KAAK,mBAAmB,CAAC,CAAC,EAC7C,GAAM,KAAK,iBAAiB,CAAC,CAClC,EAEA,EAAa,UAAY,EACzB,EAAa,uBAAyB,GACtC,KAAK,aAAa,CACtB,CAKA,WAAW,UAAqB,CAC5B,OAAO,EAAa,SACxB,CAYA,WAAW,QAAQ,EAAiC,CAChD,IAAM,EAAS,EAAa,QAC5B,KAAK,uBAAuB,UAAW,CAAM,EAC7C,EAAa,SAAW,IAAU,IAAA,GAAY,IAAA,GAAY,EAAO,iBAAiB,CAAK,EACvF,KAAK,aAAa,CACtB,CAEA,WAAW,SAA8B,CACrC,OAAO,EAAa,QACxB,CAEA,WAAW,eAAe,EAAwB,CAC9C,EAAU,uBAAuB,CAAM,EACvC,EAAa,2BAA6B,EAC1C,KAAK,aAAa,CACtB,CAKA,WAAW,gBAAiC,CACxC,OAAO,EAAa,0BACxB,CAmBA,OAAO,kBAAkB,EAA8B,CACnD,KAAK,uBAAuB,oBAAqB,EAAa,OAAO,EACrE,EAAmB,UAAY,EAC/B,KAAK,aAAa,CACtB,CAOA,OAAO,eAAsB,CACzB,EAAmB,UAAY,IAAA,GAC/B,EAAa,UAAY,CAAC,MAAM,EAChC,EAAa,uBAAyB,GAGtC,KAAK,0BAA4B,GACjC,KAAK,aAAe,IAAA,GACpB,KAAK,aAAa,CACtB,CACJ"}

package/dist/node/StandardSchema.d.mts

@@ -0,0 +1,59 @@
+//#region src/StandardSchema.d.ts
+/**
+ * Standard Schema V1 interface. Inlined verbatim from the spec at https://standardschema.dev
+ * so envapt has zero runtime peer dependencies on any specific schema library
+ * (zod / valibot / arktype / etc).
+ *
+ * envapt narrows usage to SYNCHRONOUS schemas only: env loading is boot-time,
+ * `validate` returning `Promise<Result>` is rejected at the type level (see
+ * `SchemaMustBeSync` brand in `Types.ts`) and at runtime by the Parser dispatch.
+ *
+ * @public
+ */
+interface StandardSchemaV1<Input = unknown, Output = Input> {
+  readonly '~standard': StandardSchemaV1.Props<Input, Output>;
+}
+declare namespace StandardSchemaV1 {
+  interface Props<Input = unknown, Output = Input> {
+    readonly version: 1;
+    readonly vendor: string;
+    readonly validate: (value: unknown) => Result<Output> | Promise<Result<Output>>;
+    readonly types?: Types<Input, Output> | undefined;
+  }
+  type Result<Output> = SuccessResult<Output> | FailureResult;
+  interface SuccessResult<Output> {
+    readonly value: Output;
+    readonly issues?: undefined;
+  }
+  interface FailureResult {
+    readonly issues: readonly Issue[];
+  }
+  interface Issue {
+    readonly message: string;
+    readonly path?: readonly (PropertyKey | PathSegment)[] | undefined;
+  }
+  interface PathSegment {
+    readonly key: PropertyKey;
+  }
+  interface Types<Input = unknown, Output = Input> {
+    readonly input: Input;
+    readonly output: Output;
+  }
+  type InferInput<Schema extends StandardSchemaV1> = NonNullable<Schema['~standard']['types']>['input'];
+  type InferOutput<Schema extends StandardSchemaV1> = NonNullable<Schema['~standard']['types']>['output'];
+}
+/**
+ * Envapt-side alias for {@link StandardSchemaV1.InferOutput}. Re-exported under a friendlier
+ * name so consumers writing `declare static readonly x: InferSchemaOutput<typeof mySchema>`
+ * don't need the namespace path.
+ * @public
+ */
+type InferSchemaOutput<Schema extends StandardSchemaV1> = StandardSchemaV1.InferOutput<Schema>;
+/**
+ * Envapt-side alias for {@link StandardSchemaV1.InferInput}.
+ * @public
+ */
+type InferSchemaInput<Schema extends StandardSchemaV1> = StandardSchemaV1.InferInput<Schema>;
+//#endregion
+export { InferSchemaInput, InferSchemaOutput, StandardSchemaV1 };
+//# sourceMappingURL=StandardSchema.d.mts.map

package/dist/node/TemplateResolver.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"TemplateResolver.cjs","names":["EnvaptError"],"sources":["../../src/TemplateResolver.ts"],"sourcesContent":["import { debugWarn } from './Debug';\nimport { EnvaptError, EnvaptErrorCodes } from './Error';\n\nimport type { EnvapterService } from './types/Env';\n\n/**\n * Resolve `${VAR}` template references in environment values, guarding against circular\n * references and missing variables.\n * @internal\n */\nexport class TemplateResolver {\n    private readonly TEMPLATE_REGEX = /\\${\\w*}/g;\n\n    constructor(private readonly envService: EnvapterService) {}\n\n    resolveTemplate(key: string, value: string, stack: Set<string> = new Set<string>()): string {\n        stack.add(key);\n        const strict = this.envService.isStrict();\n\n        const out = value.replace(this.TEMPLATE_REGEX, (template) => {\n            const variable = template.slice(2, -1);\n\n            if (stack.has(variable)) return template; // cycle, preserve\n\n            const raw = this.envService.getRaw(variable);\n            const isMissing = raw === undefined || raw === '' || (strict && raw.trim() === '');\n            if (isMissing) {\n                if (strict) {\n                    throw new EnvaptError(\n                        EnvaptErrorCodes.MissingEnvValue,\n                        `Cannot resolve template variable \"\\${${variable}}\": value is missing or empty.`\n                    );\n                }\n                debugWarn(`unresolved template \\${${variable}} preserved as literal`);\n                return template; // missing or empty, preserve\n            }\n\n            const resolved = this.resolveTemplate(variable, raw, new Set(stack));\n\n            // If resolution still references the current key, skip replacement (indirect cycle)\n            if (resolved.includes(`\\${${key}}`)) return template;\n\n            // If nothing changed (unresolved placeholders stayed), also preserve original template\n            if (resolved === raw && /\\$\\{[^}]*\\}/.test(resolved)) return template;\n\n            return resolved;\n        });\n\n        stack.delete(key);\n        return out;\n    }\n}\n"],"mappings":"wDAUA,IAAa,EAAb,KAA8B,CAGG,WAF7B,eAAkC,WAElC,YAAY,EAA8C,CAA7B,KAAA,WAAA,CAA8B,CAE3D,gBAAgB,EAAa,EAAe,EAAqB,IAAI,IAAuB,CACxF,EAAM,IAAI,CAAG,EACb,IAAM,EAAS,KAAK,WAAW,SAAS,EAElC,EAAM,EAAM,QAAQ,KAAK,eAAiB,GAAa,CACzD,IAAM,EAAW,EAAS,MAAM,EAAG,EAAE,EAErC,GAAI,EAAM,IAAI,CAAQ,EAAG,OAAO,EAEhC,IAAM,EAAM,KAAK,WAAW,OAAO,CAAQ,EAE3C,GADkB,IAAQ,IAAA,IAAa,IAAQ,IAAO,GAAU,EAAI,KAAK,IAAM,GAChE,CACX,GAAI,EACA,MAAM,IAAIA,EAAAA,YAAAA,IAEN,wCAAwC,EAAS,+BACrD,EAGJ,OADA,EAAA,UAAU,0BAA0B,EAAS,uBAAuB,EAC7D,CACX,CAEA,IAAM,EAAW,KAAK,gBAAgB,EAAU,EAAK,IAAI,IAAI,CAAK,CAAC,EAQnE,OALI,EAAS,SAAS,MAAM,EAAI,EAAE,GAG9B,IAAa,GAAO,cAAc,KAAK,CAAQ,EAAU,EAEtD,CACX,CAAC,EAGD,OADA,EAAM,OAAO,CAAG,EACT,CACX,CACJ"}

package/dist/node/TemplateResolver.d.mts

@@ -0,0 +1,17 @@
+import { EnvapterService } from "./types/Env.mjs";
+
+//#region src/TemplateResolver.d.ts
+/**
+ * Resolve `${VAR}` template references in environment values, guarding against circular
+ * references and missing variables.
+ * @internal
+ */
+declare class TemplateResolver {
+  private readonly envService;
+  private readonly TEMPLATE_REGEX;
+  constructor(envService: EnvapterService);
+  resolveTemplate(key: string, value: string, stack?: Set<string>): string;
+}
+//#endregion
+export { TemplateResolver };
+//# sourceMappingURL=TemplateResolver.d.mts.map

package/dist/node/TemplateResolver.mjs

@@ -0,0 +1,2 @@
+import{EnvaptError as e}from"./Error.mjs";import{debugWarn as t}from"./Debug.mjs";var n=class{envService;TEMPLATE_REGEX=/\${\w*}/g;constructor(e){this.envService=e}resolveTemplate(n,r,i=new Set){i.add(n);let a=this.envService.isStrict(),o=r.replace(this.TEMPLATE_REGEX,r=>{let o=r.slice(2,-1);if(i.has(o))return r;let s=this.envService.getRaw(o);if(s===void 0||s===``||a&&s.trim()===``){if(a)throw new e(305,`Cannot resolve template variable "\${${o}}": value is missing or empty.`);return t(`unresolved template \${${o}} preserved as literal`),r}let c=this.resolveTemplate(o,s,new Set(i));return c.includes(`\${${n}}`)||c===s&&/\$\{[^}]*\}/.test(c)?r:c});return i.delete(n),o}};export{n as TemplateResolver};
+//# sourceMappingURL=TemplateResolver.mjs.map

package/dist/node/TemplateResolver.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"TemplateResolver.mjs","names":[],"sources":["../../src/TemplateResolver.ts"],"sourcesContent":["import { debugWarn } from './Debug';\nimport { EnvaptError, EnvaptErrorCodes } from './Error';\n\nimport type { EnvapterService } from './types/Env';\n\n/**\n * Resolve `${VAR}` template references in environment values, guarding against circular\n * references and missing variables.\n * @internal\n */\nexport class TemplateResolver {\n    private readonly TEMPLATE_REGEX = /\\${\\w*}/g;\n\n    constructor(private readonly envService: EnvapterService) {}\n\n    resolveTemplate(key: string, value: string, stack: Set<string> = new Set<string>()): string {\n        stack.add(key);\n        const strict = this.envService.isStrict();\n\n        const out = value.replace(this.TEMPLATE_REGEX, (template) => {\n            const variable = template.slice(2, -1);\n\n            if (stack.has(variable)) return template; // cycle, preserve\n\n            const raw = this.envService.getRaw(variable);\n            const isMissing = raw === undefined || raw === '' || (strict && raw.trim() === '');\n            if (isMissing) {\n                if (strict) {\n                    throw new EnvaptError(\n                        EnvaptErrorCodes.MissingEnvValue,\n                        `Cannot resolve template variable \"\\${${variable}}\": value is missing or empty.`\n                    );\n                }\n                debugWarn(`unresolved template \\${${variable}} preserved as literal`);\n                return template; // missing or empty, preserve\n            }\n\n            const resolved = this.resolveTemplate(variable, raw, new Set(stack));\n\n            // If resolution still references the current key, skip replacement (indirect cycle)\n            if (resolved.includes(`\\${${key}}`)) return template;\n\n            // If nothing changed (unresolved placeholders stayed), also preserve original template\n            if (resolved === raw && /\\$\\{[^}]*\\}/.test(resolved)) return template;\n\n            return resolved;\n        });\n\n        stack.delete(key);\n        return out;\n    }\n}\n"],"mappings":"kFAUA,IAAa,EAAb,KAA8B,CAGG,WAF7B,eAAkC,WAElC,YAAY,EAA8C,CAA7B,KAAA,WAAA,CAA8B,CAE3D,gBAAgB,EAAa,EAAe,EAAqB,IAAI,IAAuB,CACxF,EAAM,IAAI,CAAG,EACb,IAAM,EAAS,KAAK,WAAW,SAAS,EAElC,EAAM,EAAM,QAAQ,KAAK,eAAiB,GAAa,CACzD,IAAM,EAAW,EAAS,MAAM,EAAG,EAAE,EAErC,GAAI,EAAM,IAAI,CAAQ,EAAG,OAAO,EAEhC,IAAM,EAAM,KAAK,WAAW,OAAO,CAAQ,EAE3C,GADkB,IAAQ,IAAA,IAAa,IAAQ,IAAO,GAAU,EAAI,KAAK,IAAM,GAChE,CACX,GAAI,EACA,MAAM,IAAI,EAAA,IAEN,wCAAwC,EAAS,+BACrD,EAGJ,OADA,EAAU,0BAA0B,EAAS,uBAAuB,EAC7D,CACX,CAEA,IAAM,EAAW,KAAK,gBAAgB,EAAU,EAAK,IAAI,IAAI,CAAK,CAAC,EAQnE,OALI,EAAS,SAAS,MAAM,EAAI,EAAE,GAG9B,IAAa,GAAO,cAAc,KAAK,CAAQ,EAAU,EAEtD,CACX,CAAC,EAGD,OADA,EAAM,OAAO,CAAG,EACT,CACX,CACJ"}

package/dist/node/Validators.cjs

@@ -0,0 +1,2 @@
+const e=require("./converters/Converters.cjs"),t=require("./Error.cjs"),n=require("./converters/ListOfBuiltInConverters.cjs");var r=class{static isBuiltInConverter(e){return typeof e==`string`?n.ListOfBuiltInConverters.includes(e):!1}static isArrayConverter(t){return e.isArrayOf(t)}static isStandardSchema(e){if(typeof e!=`object`||!e||!(`~standard`in e))return!1;let t=e[`~standard`];if(typeof t!=`object`||!t)return!1;let n=t;return n.version===1&&typeof n.validate==`function`}static customConvertor(e){if(typeof e!=`function`)throw new t.EnvaptError(203,`Custom converter must be a function, got ${typeof e}.`)}static arrayConverter(r){if(!e.isArrayOf(r))throw new t.EnvaptError(201,`Expected an ArrayOf<...> token produced by Converters.array(...)`);if(typeof r.delimiter!=`string`||r.delimiter.length===0)throw new t.EnvaptError(301,`ArrayOf<...> requires a non-empty string delimiter, got ${typeof r.delimiter}`);let i=r.of;if(!(typeof i==`string`&&n.ListOfBuiltInConverters.includes(i))&&typeof i!=`function`)throw new t.EnvaptError(201,`ArrayOf<...> element ("of") must be a built-in scalar token or a function, got ${typeof i}`)}static builtInConverter(e){if(typeof e!=`string`)throw new t.EnvaptError(204,`Expected string, got ${typeof e}`);if(!n.ListOfBuiltInConverters.includes(e))throw new t.EnvaptError(202,`"${e}" is not a valid converter type. Valid types are: ${n.ListOfBuiltInConverters.join(`,`)}`)}static validateBuiltInConverterFallback(e,r){let i=n.BuiltInConverterTypeCheckers[e];if(!i(r))throw new t.EnvaptError(104,`Fallback type does not match converter "${e}". Expected ${e} compatible type.`)}static validateArrayFallbackElementTypes(e){if(e.length===0)return;let n=typeof e[0];if(e.some((e,t)=>t===0?!1:typeof e!==n))throw new t.EnvaptError(103,`All elements in array fallback must have the same type. Found mixed types.`)}static validateArrayConverterElementTypeMatch(e,r){if(r.length===0||typeof e==`function`)return;let i=e;if(i===`time`){let e=r.every(e=>typeof e==`number`),n=r.every(e=>typeof e==`string`);if(!e&&!n)throw new t.EnvaptError(103,`Time array fallback must be all numbers or all time-string entries.`);return}let a=n.BuiltInConverterTypeCheckers[i],o=r[0];if(!a(o))throw new t.EnvaptError(103,`Array converter type "${i}" does not match fallback element type. Expected ${i} compatible elements.`)}static isPrimitiveConstructor(e){return e===String||e===Number||e===Boolean||e===BigInt||e===Symbol}static coercePrimitiveFallback(e,t){return this.isCorrectPrimitiveType(e,t)?t:this.performPrimitiveCoercion(e,t)}static isCorrectPrimitiveType(e,t){return e===String&&typeof t==`string`||e===Number&&typeof t==`number`||e===Boolean&&typeof t==`boolean`||e===BigInt&&typeof t==`bigint`||e===Symbol&&typeof t==`symbol`}static performPrimitiveCoercion(e,n){try{if(e===String)return String(n);if(e===Number)return Number(n);if(e===Boolean)return!!n;if(e===BigInt)return BigInt(n);if(e===Symbol)return Symbol.for(String(n))}catch(n){throw new t.EnvaptError(205,`Failed to coerce fallback value using ${e.name}: ${n.message}`)}throw new t.EnvaptError(205,`Unknown primitive converter: ${e.name}`)}static validateSyncProcessEnv(e){if(typeof e!=`boolean`)throw new t.EnvaptError(302,`Envapter.syncProcessEnv must be a boolean, got ${typeof e}.`)}static validateEnvFileOptions(e){let n=new Set([`encoding`,`override`]),r=Object.keys(e).filter(e=>!n.has(e));if(r.length>0)throw new t.EnvaptError(302,`Invalid envFileOptions: ${r.join(`, `)}. Allowed options: ${Array.from(n).join(`, `)}. For debug output, use Envapter.debug or the ENVAPT_DEBUG env var.`);return!0}static validateEnvFilesExist(e,n){let r=e.filter(e=>!n(e));if(r.length>0)throw new t.EnvaptError(303,`Environment file not found at path: ${r.join(`, `)}`)}};exports.Validator=r;
+//# sourceMappingURL=Validators.cjs.map

package/dist/node/Validators.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"Validators.cjs","names":["ListOfBuiltInConverters","isArrayOf","EnvaptError","BuiltInConverterTypeCheckers"],"sources":["../../src/Validators.ts"],"sourcesContent":["// Import the converter modules directly, not via the `./converters` barrel: that barrel pulls in\n// ValueConverter, which imports this Validator, so a barrel import here would cycle.\nimport { isArrayOf } from './converters/Converters';\nimport { ListOfBuiltInConverters, BuiltInConverterTypeCheckers } from './converters/ListOfBuiltInConverters';\nimport { EnvaptError, EnvaptErrorCodes } from './Error';\n\nimport type { ArrayOf, ConverterToken } from './converters/Converters';\nimport type { EnvFileOptions } from './Dotenv';\nimport type { StandardSchemaV1 } from './StandardSchema';\nimport type { BuiltInConverter, ConverterFunction, EnvaptConverter } from './types';\n\n// eslint-disable-next-line @typescript-eslint/no-extraneous-class -- cohesive dispatch of stateless type guards, same shape as BuiltInConverters\nexport class Validator {\n    /**\n     * Check if a value is a built-in scalar converter token\n     */\n    static isBuiltInConverter<TFallback>(value: EnvaptConverter<TFallback>): value is BuiltInConverter {\n        if (typeof value === 'string') return ListOfBuiltInConverters.includes(value);\n        return false;\n    }\n\n    /**\n     * Check if a value is an `ArrayOf<...>` token produced by {@link Converters.array}.\n     */\n    static isArrayConverter(value: unknown): value is ArrayOf {\n        return isArrayOf(value);\n    }\n\n    // Structural check: `version === 1` + callable `validate` is the minimum dispatchable\n    // shape per the Standard Schema spec.\n    static isStandardSchema(value: unknown): value is StandardSchemaV1 {\n        if (typeof value !== 'object' || value === null) return false;\n        if (!('~standard' in value)) return false;\n        const slot = value['~standard'];\n        if (typeof slot !== 'object' || slot === null) return false;\n        const props = slot as { version?: unknown; validate?: unknown };\n        return props.version === 1 && typeof props.validate === 'function';\n    }\n\n    static customConvertor<TFallback>(\n        converter: EnvaptConverter<TFallback>\n    ): asserts converter is ConverterFunction<TFallback> {\n        if (typeof converter !== 'function') {\n            throw new EnvaptError(\n                EnvaptErrorCodes.InvalidCustomConverter,\n                `Custom converter must be a function, got ${typeof converter}.`\n            );\n        }\n    }\n\n    /**\n     * Runtime validation that the `ArrayOf<...>` configuration is well-formed.\n     */\n    static arrayConverter(value: unknown): asserts value is ArrayOf {\n        if (!isArrayOf(value)) {\n            throw new EnvaptError(\n                EnvaptErrorCodes.InvalidArrayConverterType,\n                'Expected an ArrayOf<...> token produced by Converters.array(...)'\n            );\n        }\n\n        if (typeof value.delimiter !== 'string' || value.delimiter.length === 0) {\n            throw new EnvaptError(\n                EnvaptErrorCodes.MissingDelimiter,\n                `ArrayOf<...> requires a non-empty string delimiter, got ${typeof value.delimiter}`\n            );\n        }\n\n        const elementOf = value.of;\n        const isScalar = typeof elementOf === 'string' && ListOfBuiltInConverters.includes(elementOf);\n        const isCustomFn = typeof elementOf === 'function';\n        if (!isScalar && !isCustomFn) {\n            throw new EnvaptError(\n                EnvaptErrorCodes.InvalidArrayConverterType,\n                `ArrayOf<...> element (\"of\") must be a built-in scalar token or a function, got ${typeof elementOf}`\n            );\n        }\n    }\n\n    /**\n     * Validate that a string is a valid built-in scalar converter token\n     */\n    static builtInConverter(value: unknown): asserts value is BuiltInConverter {\n        if (typeof value !== 'string') {\n            throw new EnvaptError(EnvaptErrorCodes.InvalidConverterType, `Expected string, got ${typeof value}`);\n        }\n\n        if (!ListOfBuiltInConverters.includes(value as ConverterToken)) {\n            throw new EnvaptError(\n                EnvaptErrorCodes.InvalidBuiltInConverter,\n                `\"${value}\" is not a valid converter type. Valid types are: ${ListOfBuiltInConverters.join(',')}`\n            );\n        }\n    }\n\n    /**\n     * Validate that fallback type matches the converter's return type for built-in converters\n     */\n    static validateBuiltInConverterFallback(converter: BuiltInConverter, fallback: unknown): void {\n        const typeChecker = BuiltInConverterTypeCheckers[converter];\n        if (!typeChecker(fallback)) {\n            throw new EnvaptError(\n                EnvaptErrorCodes.FallbackConverterTypeMismatch,\n                `Fallback type does not match converter \"${converter}\". Expected ${converter} compatible type.`\n            );\n        }\n    }\n\n    /**\n     * Validate that all elements in an array fallback have consistent types\n     */\n    static validateArrayFallbackElementTypes(fallback: unknown[]): void {\n        if (fallback.length === 0) return;\n\n        const firstElementType = typeof fallback[0];\n        const hasInconsistentTypes = fallback.some((element, index) => {\n            if (index === 0) return false;\n            return typeof element !== firstElementType;\n        });\n\n        if (hasInconsistentTypes) {\n            throw new EnvaptError(\n                EnvaptErrorCodes.ArrayFallbackElementTypeMismatch,\n                `All elements in array fallback must have the same type. Found mixed types.`\n            );\n        }\n    }\n\n    /**\n     * Validate that an `ArrayOf<...>` element converter matches the runtime types of its\n     * fallback elements. For `Converters.Time` arrays the element-time-string format is also\n     * checked here.\n     */\n    static validateArrayConverterElementTypeMatch(elementOf: ArrayOf['of'], fallback: unknown[]): void {\n        if (fallback.length === 0) return;\n\n        if (typeof elementOf === 'function') {\n            // Custom element converters can return anything; we can't statically validate the fallback shape.\n            return;\n        }\n\n        const elementToken = elementOf;\n\n        // Time array fallbacks may be number[] OR string[] (TimeFallback[]).\n        if (elementToken === 'time') {\n            const everyNumber = fallback.every((v) => typeof v === 'number');\n            const everyString = fallback.every((v) => typeof v === 'string');\n            if (!everyNumber && !everyString) {\n                throw new EnvaptError(\n                    EnvaptErrorCodes.ArrayFallbackElementTypeMismatch,\n                    'Time array fallback must be all numbers or all time-string entries.'\n                );\n            }\n            return;\n        }\n\n        const typeChecker = BuiltInConverterTypeCheckers[elementToken];\n        const firstElement = fallback[0];\n        if (!typeChecker(firstElement)) {\n            throw new EnvaptError(\n                EnvaptErrorCodes.ArrayFallbackElementTypeMismatch,\n                `Array converter type \"${elementToken}\" does not match fallback element type. Expected ${elementToken} compatible elements.`\n            );\n        }\n    }\n\n    /**\n     * Check if a value is a primitive constructor\n     */\n    static isPrimitiveConstructor(\n        value: unknown\n    ): value is typeof String | typeof Number | typeof Boolean | typeof BigInt | typeof Symbol {\n        return value === String || value === Number || value === Boolean || value === BigInt || value === Symbol;\n    }\n\n    /**\n     * Safely coerce a fallback value using a primitive constructor\n     */\n    static coercePrimitiveFallback<CoercedType>(\n        converter: typeof String | typeof Number | typeof Boolean | typeof BigInt | typeof Symbol,\n        fallback: unknown\n    ): CoercedType {\n        if (this.isCorrectPrimitiveType(converter, fallback)) return fallback as CoercedType;\n        return this.performPrimitiveCoercion<CoercedType>(converter, fallback);\n    }\n\n    private static isCorrectPrimitiveType(\n        converter: typeof String | typeof Number | typeof Boolean | typeof BigInt | typeof Symbol,\n        fallback: unknown\n    ): boolean {\n        if (converter === String && typeof fallback === 'string') return true;\n        if (converter === Number && typeof fallback === 'number') return true;\n        if (converter === Boolean && typeof fallback === 'boolean') return true;\n        if (converter === BigInt && typeof fallback === 'bigint') return true;\n        if (converter === Symbol && typeof fallback === 'symbol') return true;\n        return false;\n    }\n\n    private static performPrimitiveCoercion<CoercedType>(\n        converter: typeof String | typeof Number | typeof Boolean | typeof BigInt | typeof Symbol,\n        fallback: unknown\n    ): CoercedType {\n        try {\n            if (converter === String) return String(fallback) as CoercedType;\n            if (converter === Number) return Number(fallback) as CoercedType;\n            if (converter === Boolean) return Boolean(fallback) as CoercedType;\n            if (converter === BigInt) return BigInt(fallback as string | number | bigint) as CoercedType;\n            /* v8 ignore next -- @preserve */\n            if (converter === Symbol) return Symbol.for(String(fallback)) as CoercedType;\n        } catch (error) {\n            throw new EnvaptError(\n                EnvaptErrorCodes.PrimitiveCoercionFailed,\n                `Failed to coerce fallback value using ${converter.name}: ${(error as Error).message}`\n            );\n        }\n\n        /* v8 ignore next -- @preserve */\n        throw new EnvaptError(\n            EnvaptErrorCodes.PrimitiveCoercionFailed,\n            `Unknown primitive converter: ${converter.name}`\n        );\n    }\n\n    /**\n     * Reject non-boolean inputs to `Envapter.syncProcessEnv` so a truthy typo\n     * (`'true'`, `1`, etc.) does not silently enable the mirror.\n     */\n    static validateSyncProcessEnv(value: unknown): asserts value is boolean {\n        if (typeof value !== 'boolean') {\n            throw new EnvaptError(\n                EnvaptErrorCodes.InvalidUserDefinedConfig,\n                `Envapter.syncProcessEnv must be a boolean, got ${typeof value}.`\n            );\n        }\n    }\n\n    /**\n     * Make sure the user hasn't provided prohibited options in their dotenv config\n     */\n    static validateEnvFileOptions(config: object): config is EnvFileOptions {\n        const validKeys = new Set(['encoding', 'override']);\n        const invalidKeys = Object.keys(config).filter((key) => !validKeys.has(key));\n\n        if (invalidKeys.length > 0) {\n            throw new EnvaptError(\n                EnvaptErrorCodes.InvalidUserDefinedConfig,\n                `Invalid envFileOptions: ${invalidKeys.join(', ')}. Allowed options: ${Array.from(validKeys).join(', ')}. For debug output, use Envapter.debug or the ENVAPT_DEBUG env var.`\n            );\n        }\n\n        return true;\n    }\n\n    // Existence is probed through the caller-supplied `fileExists` (backed by the bound source) so\n    // this stays free of `node:fs`.\n    static validateEnvFilesExist(paths: string[], fileExists: (path: string) => boolean): void {\n        const missing = paths.filter((p) => !fileExists(p));\n\n        if (missing.length > 0) {\n            throw new EnvaptError(\n                EnvaptErrorCodes.EnvFilesNotFound,\n                `Environment file not found at path: ${missing.join(', ')}`\n            );\n        }\n    }\n}\n"],"mappings":"8HAYA,IAAa,EAAb,KAAuB,CAInB,OAAO,mBAA8B,EAA8D,CAE/F,OADI,OAAO,GAAU,SAAiBA,EAAAA,wBAAwB,SAAS,CAAK,EACrE,EACX,CAKA,OAAO,iBAAiB,EAAkC,CACtD,OAAOC,EAAAA,UAAU,CAAK,CAC1B,CAIA,OAAO,iBAAiB,EAA2C,CAE/D,GADI,OAAO,GAAU,WAAY,GAC7B,EAAE,cAAe,GAAQ,MAAO,GACpC,IAAM,EAAO,EAAM,aACnB,GAAI,OAAO,GAAS,WAAY,EAAe,MAAO,GACtD,IAAM,EAAQ,EACd,OAAO,EAAM,UAAY,GAAK,OAAO,EAAM,UAAa,UAC5D,CAEA,OAAO,gBACH,EACiD,CACjD,GAAI,OAAO,GAAc,WACrB,MAAM,IAAIC,EAAAA,YAAAA,IAEN,4CAA4C,OAAO,EAAU,EACjE,CAER,CAKA,OAAO,eAAe,EAA0C,CAC5D,GAAI,CAACD,EAAAA,UAAU,CAAK,EAChB,MAAM,IAAIC,EAAAA,YAAAA,IAEN,kEACJ,EAGJ,GAAI,OAAO,EAAM,WAAc,UAAY,EAAM,UAAU,SAAW,EAClE,MAAM,IAAIA,EAAAA,YAAAA,IAEN,2DAA2D,OAAO,EAAM,WAC5E,EAGJ,IAAM,EAAY,EAAM,GAGxB,GAAI,EAFa,OAAO,GAAc,UAAYF,EAAAA,wBAAwB,SAAS,CAAS,IACzE,OAAO,GAAc,WAEpC,MAAM,IAAIE,EAAAA,YAAAA,IAEN,kFAAkF,OAAO,GAC7F,CAER,CAKA,OAAO,iBAAiB,EAAmD,CACvE,GAAI,OAAO,GAAU,SACjB,MAAM,IAAIA,EAAAA,YAAAA,IAAmD,wBAAwB,OAAO,GAAO,EAGvG,GAAI,CAACF,EAAAA,wBAAwB,SAAS,CAAuB,EACzD,MAAM,IAAIE,EAAAA,YAAAA,IAEN,IAAI,EAAM,oDAAoDF,EAAAA,wBAAwB,KAAK,GAAG,GAClG,CAER,CAKA,OAAO,iCAAiC,EAA6B,EAAyB,CAC1F,IAAM,EAAcG,EAAAA,6BAA6B,GACjD,GAAI,CAAC,EAAY,CAAQ,EACrB,MAAM,IAAID,EAAAA,YAAAA,IAEN,2CAA2C,EAAU,cAAc,EAAU,kBACjF,CAER,CAKA,OAAO,kCAAkC,EAA2B,CAChE,GAAI,EAAS,SAAW,EAAG,OAE3B,IAAM,EAAmB,OAAO,EAAS,GAMzC,GAL6B,EAAS,MAAM,EAAS,IAC7C,IAAU,EAAU,GACjB,OAAO,IAAY,CAGP,EACnB,MAAM,IAAIA,EAAAA,YAAAA,IAEN,4EACJ,CAER,CAOA,OAAO,uCAAuC,EAA0B,EAA2B,CAG/F,GAFI,EAAS,SAAW,GAEpB,OAAO,GAAc,WAErB,OAGJ,IAAM,EAAe,EAGrB,GAAI,IAAiB,OAAQ,CACzB,IAAM,EAAc,EAAS,MAAO,GAAM,OAAO,GAAM,QAAQ,EACzD,EAAc,EAAS,MAAO,GAAM,OAAO,GAAM,QAAQ,EAC/D,GAAI,CAAC,GAAe,CAAC,EACjB,MAAM,IAAIA,EAAAA,YAAAA,IAEN,qEACJ,EAEJ,MACJ,CAEA,IAAM,EAAcC,EAAAA,6BAA6B,GAC3C,EAAe,EAAS,GAC9B,GAAI,CAAC,EAAY,CAAY,EACzB,MAAM,IAAID,EAAAA,YAAAA,IAEN,yBAAyB,EAAa,mDAAmD,EAAa,sBAC1G,CAER,CAKA,OAAO,uBACH,EACuF,CACvF,OAAO,IAAU,QAAU,IAAU,QAAU,IAAU,SAAW,IAAU,QAAU,IAAU,MACtG,CAKA,OAAO,wBACH,EACA,EACW,CAEX,OADI,KAAK,uBAAuB,EAAW,CAAQ,EAAU,EACtD,KAAK,yBAAsC,EAAW,CAAQ,CACzE,CAEA,OAAe,uBACX,EACA,EACO,CAMP,OALI,IAAc,QAAU,OAAO,GAAa,UAC5C,IAAc,QAAU,OAAO,GAAa,UAC5C,IAAc,SAAW,OAAO,GAAa,WAC7C,IAAc,QAAU,OAAO,GAAa,UAC5C,IAAc,QAAU,OAAO,GAAa,QAEpD,CAEA,OAAe,yBACX,EACA,EACW,CACX,GAAI,CACA,GAAI,IAAc,OAAQ,OAAO,OAAO,CAAQ,EAChD,GAAI,IAAc,OAAQ,OAAO,OAAO,CAAQ,EAChD,GAAI,IAAc,QAAS,MAAO,EAAQ,EAC1C,GAAI,IAAc,OAAQ,OAAO,OAAO,CAAoC,EAE5E,GAAI,IAAc,OAAQ,OAAO,OAAO,IAAI,OAAO,CAAQ,CAAC,CAChE,OAAS,EAAO,CACZ,MAAM,IAAIA,EAAAA,YAAAA,IAEN,yCAAyC,EAAU,KAAK,IAAK,EAAgB,SACjF,CACJ,CAGA,MAAM,IAAIA,EAAAA,YAAAA,IAEN,gCAAgC,EAAU,MAC9C,CACJ,CAMA,OAAO,uBAAuB,EAA0C,CACpE,GAAI,OAAO,GAAU,UACjB,MAAM,IAAIA,EAAAA,YAAAA,IAEN,kDAAkD,OAAO,EAAM,EACnE,CAER,CAKA,OAAO,uBAAuB,EAA0C,CACpE,IAAM,EAAY,IAAI,IAAI,CAAC,WAAY,UAAU,CAAC,EAC5C,EAAc,OAAO,KAAK,CAAM,EAAE,OAAQ,GAAQ,CAAC,EAAU,IAAI,CAAG,CAAC,EAE3E,GAAI,EAAY,OAAS,EACrB,MAAM,IAAIA,EAAAA,YAAAA,IAEN,2BAA2B,EAAY,KAAK,IAAI,EAAE,qBAAqB,MAAM,KAAK,CAAS,EAAE,KAAK,IAAI,EAAE,oEAC5G,EAGJ,MAAO,EACX,CAIA,OAAO,sBAAsB,EAAiB,EAA6C,CACvF,IAAM,EAAU,EAAM,OAAQ,GAAM,CAAC,EAAW,CAAC,CAAC,EAElD,GAAI,EAAQ,OAAS,EACjB,MAAM,IAAIA,EAAAA,YAAAA,IAEN,uCAAuC,EAAQ,KAAK,IAAI,GAC5D,CAER,CACJ"}

package/dist/node/Validators.mjs

@@ -0,0 +1,2 @@
+import{isArrayOf as e}from"./converters/Converters.mjs";import{EnvaptError as t}from"./Error.mjs";import{BuiltInConverterTypeCheckers as n,ListOfBuiltInConverters as r}from"./converters/ListOfBuiltInConverters.mjs";var i=class{static isBuiltInConverter(e){return typeof e==`string`?r.includes(e):!1}static isArrayConverter(t){return e(t)}static isStandardSchema(e){if(typeof e!=`object`||!e||!(`~standard`in e))return!1;let t=e[`~standard`];if(typeof t!=`object`||!t)return!1;let n=t;return n.version===1&&typeof n.validate==`function`}static customConvertor(e){if(typeof e!=`function`)throw new t(203,`Custom converter must be a function, got ${typeof e}.`)}static arrayConverter(n){if(!e(n))throw new t(201,`Expected an ArrayOf<...> token produced by Converters.array(...)`);if(typeof n.delimiter!=`string`||n.delimiter.length===0)throw new t(301,`ArrayOf<...> requires a non-empty string delimiter, got ${typeof n.delimiter}`);let i=n.of;if(!(typeof i==`string`&&r.includes(i))&&typeof i!=`function`)throw new t(201,`ArrayOf<...> element ("of") must be a built-in scalar token or a function, got ${typeof i}`)}static builtInConverter(e){if(typeof e!=`string`)throw new t(204,`Expected string, got ${typeof e}`);if(!r.includes(e))throw new t(202,`"${e}" is not a valid converter type. Valid types are: ${r.join(`,`)}`)}static validateBuiltInConverterFallback(e,r){let i=n[e];if(!i(r))throw new t(104,`Fallback type does not match converter "${e}". Expected ${e} compatible type.`)}static validateArrayFallbackElementTypes(e){if(e.length===0)return;let n=typeof e[0];if(e.some((e,t)=>t===0?!1:typeof e!==n))throw new t(103,`All elements in array fallback must have the same type. Found mixed types.`)}static validateArrayConverterElementTypeMatch(e,r){if(r.length===0||typeof e==`function`)return;let i=e;if(i===`time`){let e=r.every(e=>typeof e==`number`),n=r.every(e=>typeof e==`string`);if(!e&&!n)throw new t(103,`Time array fallback must be all numbers or all time-string entries.`);return}let a=n[i],o=r[0];if(!a(o))throw new t(103,`Array converter type "${i}" does not match fallback element type. Expected ${i} compatible elements.`)}static isPrimitiveConstructor(e){return e===String||e===Number||e===Boolean||e===BigInt||e===Symbol}static coercePrimitiveFallback(e,t){return this.isCorrectPrimitiveType(e,t)?t:this.performPrimitiveCoercion(e,t)}static isCorrectPrimitiveType(e,t){return e===String&&typeof t==`string`||e===Number&&typeof t==`number`||e===Boolean&&typeof t==`boolean`||e===BigInt&&typeof t==`bigint`||e===Symbol&&typeof t==`symbol`}static performPrimitiveCoercion(e,n){try{if(e===String)return String(n);if(e===Number)return Number(n);if(e===Boolean)return!!n;if(e===BigInt)return BigInt(n);if(e===Symbol)return Symbol.for(String(n))}catch(n){throw new t(205,`Failed to coerce fallback value using ${e.name}: ${n.message}`)}throw new t(205,`Unknown primitive converter: ${e.name}`)}static validateSyncProcessEnv(e){if(typeof e!=`boolean`)throw new t(302,`Envapter.syncProcessEnv must be a boolean, got ${typeof e}.`)}static validateEnvFileOptions(e){let n=new Set([`encoding`,`override`]),r=Object.keys(e).filter(e=>!n.has(e));if(r.length>0)throw new t(302,`Invalid envFileOptions: ${r.join(`, `)}. Allowed options: ${Array.from(n).join(`, `)}. For debug output, use Envapter.debug or the ENVAPT_DEBUG env var.`);return!0}static validateEnvFilesExist(e,n){let r=e.filter(e=>!n(e));if(r.length>0)throw new t(303,`Environment file not found at path: ${r.join(`, `)}`)}};export{i as Validator};
+//# sourceMappingURL=Validators.mjs.map