@karmaniverous/get-dotenv 6.0.0-0 → 6.0.0

package/dist/config.d.cts

@@ -1,55 +0,0 @@
-type Scripts = Record<string, string | {
-    cmd: string;
-    shell?: string | boolean;
-}>;
-
-type GetDotenvConfigResolved = {
-    dotenvToken?: string;
-    privateToken?: string;
-    paths?: string[];
-    loadProcess?: boolean;
-    log?: boolean;
-    shell?: string | boolean;
-    scripts?: Scripts;
-    requiredKeys?: string[];
-    schema?: unknown;
-    vars?: Record<string, string>;
-    envVars?: Record<string, Record<string, string>>;
-    dynamic?: unknown;
-    plugins?: Record<string, unknown>;
-};
-
-type ConfigPrivacy = 'public' | 'local';
-type ConfigScope = 'packaged' | 'project';
-type ConfigFile = {
-    path: string;
-    privacy: ConfigPrivacy;
-    scope: ConfigScope;
-};
-/**
- * Discover JSON/YAML config files in the packaged root and project root.
- * Order: packaged public → project public → project local. */
-declare const discoverConfigFiles: (importMetaUrl?: string) => Promise<ConfigFile[]>;
-/**
- * Load a single config file (JSON/YAML). JS/TS is not supported in this step.
- * Validates with Zod RAW schema, then normalizes to RESOLVED.
- *
- * For JSON/YAML: if a "dynamic" property is present, throws with guidance.
- * For JS/TS: default export is loaded; "dynamic" is allowed.
- */
-declare const loadConfigFile: (filePath: string) => Promise<GetDotenvConfigResolved>;
-type ResolvedConfigSources = {
-    packaged?: GetDotenvConfigResolved;
-    project?: {
-        public?: GetDotenvConfigResolved;
-        local?: GetDotenvConfigResolved;
-    };
-};
-/**
- * Discover and load configs into resolved shapes, ordered by scope/privacy.
- * JSON/YAML/JS/TS supported; first match per scope/privacy applies.
- */
-declare const resolveGetDotenvConfigSources: (importMetaUrl?: string) => Promise<ResolvedConfigSources>;
-declare const toFileUrl: (p: string) => string;
-
-export { discoverConfigFiles, loadConfigFile, resolveGetDotenvConfigSources, toFileUrl };

package/dist/config.d.mts

@@ -1,55 +0,0 @@
-type Scripts = Record<string, string | {
-    cmd: string;
-    shell?: string | boolean;
-}>;
-
-type GetDotenvConfigResolved = {
-    dotenvToken?: string;
-    privateToken?: string;
-    paths?: string[];
-    loadProcess?: boolean;
-    log?: boolean;
-    shell?: string | boolean;
-    scripts?: Scripts;
-    requiredKeys?: string[];
-    schema?: unknown;
-    vars?: Record<string, string>;
-    envVars?: Record<string, Record<string, string>>;
-    dynamic?: unknown;
-    plugins?: Record<string, unknown>;
-};
-
-type ConfigPrivacy = 'public' | 'local';
-type ConfigScope = 'packaged' | 'project';
-type ConfigFile = {
-    path: string;
-    privacy: ConfigPrivacy;
-    scope: ConfigScope;
-};
-/**
- * Discover JSON/YAML config files in the packaged root and project root.
- * Order: packaged public → project public → project local. */
-declare const discoverConfigFiles: (importMetaUrl?: string) => Promise<ConfigFile[]>;
-/**
- * Load a single config file (JSON/YAML). JS/TS is not supported in this step.
- * Validates with Zod RAW schema, then normalizes to RESOLVED.
- *
- * For JSON/YAML: if a "dynamic" property is present, throws with guidance.
- * For JS/TS: default export is loaded; "dynamic" is allowed.
- */
-declare const loadConfigFile: (filePath: string) => Promise<GetDotenvConfigResolved>;
-type ResolvedConfigSources = {
-    packaged?: GetDotenvConfigResolved;
-    project?: {
-        public?: GetDotenvConfigResolved;
-        local?: GetDotenvConfigResolved;
-    };
-};
-/**
- * Discover and load configs into resolved shapes, ordered by scope/privacy.
- * JSON/YAML/JS/TS supported; first match per scope/privacy applies.
- */
-declare const resolveGetDotenvConfigSources: (importMetaUrl?: string) => Promise<ResolvedConfigSources>;
-declare const toFileUrl: (p: string) => string;
-
-export { discoverConfigFiles, loadConfigFile, resolveGetDotenvConfigSources, toFileUrl };

package/dist/env-overlay.cjs

@@ -1,163 +0,0 @@
-'use strict';
-
-/**
- * Dotenv expansion utilities.
- *
- * This module implements recursive expansion of environment-variable
- * references in strings and records. It supports both whitespace and
- * bracket syntaxes with optional defaults:
- *
- * - Whitespace: `$VAR[:default]`
- * - Bracketed: `${VAR[:default]}`
- *
- * Escaped dollar signs (`\$`) are preserved.
- * Unknown variables resolve to empty string unless a default is provided.
- */
-/**
- * Like String.prototype.search but returns the last index.
- * @internal
- */
-const searchLast = (str, rgx) => {
-    const matches = Array.from(str.matchAll(rgx));
-    return matches.length > 0 ? (matches.slice(-1)[0]?.index ?? -1) : -1;
-};
-const replaceMatch = (value, match, ref) => {
-    /**
-     * @internal
-     */
-    const group = match[0];
-    const key = match[1];
-    const defaultValue = match[2];
-    if (!key)
-        return value;
-    const replacement = value.replace(group, ref[key] ?? defaultValue ?? '');
-    return interpolate(replacement, ref);
-};
-const interpolate = (value = '', ref = {}) => {
-    /**
-     * @internal
-     */
-    // if value is falsy, return it as is
-    if (!value)
-        return value;
-    // get position of last unescaped dollar sign
-    const lastUnescapedDollarSignIndex = searchLast(value, /(?!(?<=\\))\$/g);
-    // return value if none found
-    if (lastUnescapedDollarSignIndex === -1)
-        return value;
-    // evaluate the value tail
-    const tail = value.slice(lastUnescapedDollarSignIndex);
-    // find whitespace pattern: $KEY:DEFAULT
-    const whitespacePattern = /^\$([\w]+)(?::([^\s]*))?/;
-    const whitespaceMatch = whitespacePattern.exec(tail);
-    if (whitespaceMatch != null)
-        return replaceMatch(value, whitespaceMatch, ref);
-    else {
-        // find bracket pattern: ${KEY:DEFAULT}
-        const bracketPattern = /^\${([\w]+)(?::([^}]*))?}/;
-        const bracketMatch = bracketPattern.exec(tail);
-        if (bracketMatch != null)
-            return replaceMatch(value, bracketMatch, ref);
-    }
-    return value;
-};
-/**
- * Recursively expands environment variables in a string. Variables may be
- * presented with optional default as `$VAR[:default]` or `${VAR[:default]}`.
- * Unknown variables will expand to an empty string.
- *
- * @param value - The string to expand.
- * @param ref - The reference object to use for variable expansion.
- * @returns The expanded string.
- *
- * @example
- * ```ts
- * process.env.FOO = 'bar';
- * dotenvExpand('Hello $FOO'); // "Hello bar"
- * dotenvExpand('Hello $BAZ:world'); // "Hello world"
- * ```
- *
- * @remarks
- * The expansion is recursive. If a referenced variable itself contains
- * references, those will also be expanded until a stable value is reached.
- * Escaped references (e.g. `\$FOO`) are preserved as literals.
- */
-const dotenvExpand = (value, ref = process.env) => {
-    const result = interpolate(value, ref);
-    return result ? result.replace(/\\\$/g, '$') : undefined;
-};
-/**
- * Recursively expands environment variables in the values of a JSON object.
- * Variables may be presented with optional default as `$VAR[:default]` or
- * `${VAR[:default]}`. Unknown variables will expand to an empty string.
- *
- * @param values - The values object to expand.
- * @param options - Expansion options.
- * @returns The value object with expanded string values.
- *
- * @example
- * ```ts
- * process.env.FOO = 'bar';
- * dotenvExpandAll({ A: '$FOO', B: 'x${FOO}y' });
- * // => { A: "bar", B: "xbary" }
- * ```
- *
- * @remarks
- * Options:
- * - ref: The reference object to use for expansion (defaults to process.env).
- * - progressive: Whether to progressively add expanded values to the set of
- *   reference keys.
- *
- * When `progressive` is true, each expanded key becomes available for
- * subsequent expansions in the same object (left-to-right by object key order).
- */
-const dotenvExpandAll = (values = {}, options = {}) => Object.keys(values).reduce((acc, key) => {
-    const { ref = process.env, progressive = false } = options;
-    acc[key] = dotenvExpand(values[key], {
-        ...ref,
-        ...(progressive ? acc : {}),
-    });
-    return acc;
-}, {});
-
-const applyKv = (current, kv) => {
-    if (!kv || Object.keys(kv).length === 0)
-        return current;
-    const expanded = dotenvExpandAll(kv, { ref: current, progressive: true });
-    return { ...current, ...expanded };
-};
-const applyConfigSlice = (current, cfg, env) => {
-    if (!cfg)
-        return current;
-    // kind axis: global then env (env overrides global)
-    const afterGlobal = applyKv(current, cfg.vars);
-    const envKv = env && cfg.envVars ? cfg.envVars[env] : undefined;
-    return applyKv(afterGlobal, envKv);
-};
-/**
- * Overlay config-provided values onto a base ProcessEnv using precedence axes:
- * - kind: env \> global
- * - privacy: local \> public
- * - source: project \> packaged \> base
- *
- * Programmatic explicit vars (if provided) override all config slices.
- * Progressive expansion is applied within each slice.
- */
-const overlayEnv = ({ base, env, configs, programmaticVars, }) => {
-    let current = { ...base };
-    // Source: packaged (public -> local)
-    current = applyConfigSlice(current, configs.packaged, env);
-    // Packaged "local" is not expected by policy; if present, honor it.
-    // We do not have a separate object for packaged.local in sources, keep as-is.
-    // Source: project (public -> local)
-    current = applyConfigSlice(current, configs.project?.public, env);
-    current = applyConfigSlice(current, configs.project?.local, env);
-    // Programmatic explicit vars (top of static tier)
-    if (programmaticVars) {
-        const toApply = Object.fromEntries(Object.entries(programmaticVars).filter(([_k, v]) => typeof v === 'string'));
-        current = applyKv(current, toApply);
-    }
-    return current;
-};
-
-exports.overlayEnv = overlayEnv;

package/dist/env-overlay.d.cts

@@ -1,50 +0,0 @@
-/**
- * A minimal representation of an environment key/value mapping.
- * Values may be `undefined` to represent "unset". */ type ProcessEnv = Record<string, string | undefined>;
-
-type Scripts = Record<string, string | {
-    cmd: string;
-    shell?: string | boolean;
-}>;
-
-type GetDotenvConfigResolved = {
-    dotenvToken?: string;
-    privateToken?: string;
-    paths?: string[];
-    loadProcess?: boolean;
-    log?: boolean;
-    shell?: string | boolean;
-    scripts?: Scripts;
-    requiredKeys?: string[];
-    schema?: unknown;
-    vars?: Record<string, string>;
-    envVars?: Record<string, Record<string, string>>;
-    dynamic?: unknown;
-    plugins?: Record<string, unknown>;
-};
-
-type OverlayConfigSources = {
-    packaged?: GetDotenvConfigResolved;
-    project?: {
-        public?: GetDotenvConfigResolved;
-        local?: GetDotenvConfigResolved;
-    };
-};
-/**
- * Overlay config-provided values onto a base ProcessEnv using precedence axes:
- * - kind: env \> global
- * - privacy: local \> public
- * - source: project \> packaged \> base
- *
- * Programmatic explicit vars (if provided) override all config slices.
- * Progressive expansion is applied within each slice.
- */
-declare const overlayEnv: ({ base, env, configs, programmaticVars, }: {
-    base: ProcessEnv;
-    env: string | undefined;
-    configs: OverlayConfigSources;
-    programmaticVars?: ProcessEnv;
-}) => ProcessEnv;
-
-export { overlayEnv };
-export type { OverlayConfigSources };

package/dist/env-overlay.d.mts

@@ -1,50 +0,0 @@
-/**
- * A minimal representation of an environment key/value mapping.
- * Values may be `undefined` to represent "unset". */ type ProcessEnv = Record<string, string | undefined>;
-
-type Scripts = Record<string, string | {
-    cmd: string;
-    shell?: string | boolean;
-}>;
-
-type GetDotenvConfigResolved = {
-    dotenvToken?: string;
-    privateToken?: string;
-    paths?: string[];
-    loadProcess?: boolean;
-    log?: boolean;
-    shell?: string | boolean;
-    scripts?: Scripts;
-    requiredKeys?: string[];
-    schema?: unknown;
-    vars?: Record<string, string>;
-    envVars?: Record<string, Record<string, string>>;
-    dynamic?: unknown;
-    plugins?: Record<string, unknown>;
-};
-
-type OverlayConfigSources = {
-    packaged?: GetDotenvConfigResolved;
-    project?: {
-        public?: GetDotenvConfigResolved;
-        local?: GetDotenvConfigResolved;
-    };
-};
-/**
- * Overlay config-provided values onto a base ProcessEnv using precedence axes:
- * - kind: env \> global
- * - privacy: local \> public
- * - source: project \> packaged \> base
- *
- * Programmatic explicit vars (if provided) override all config slices.
- * Progressive expansion is applied within each slice.
- */
-declare const overlayEnv: ({ base, env, configs, programmaticVars, }: {
-    base: ProcessEnv;
-    env: string | undefined;
-    configs: OverlayConfigSources;
-    programmaticVars?: ProcessEnv;
-}) => ProcessEnv;
-
-export { overlayEnv };
-export type { OverlayConfigSources };