@karmaniverous/get-dotenv 6.1.0 → 6.2.0

package/dist/config.mjs

@@ -16,26 +16,58 @@ import { createHash } from 'crypto';
  * Minimal process env representation used by options and helpers.
  * Values may be `undefined` to indicate "unset".
  */
+/**
+ * Schema for an env-like record.
+ *
+ * Keys are environment variable names and values are either strings or `undefined`
+ * (to represent “unset”).
+ *
+ * @public
+ */
 const processEnvSchema = z.record(z.string(), z.string().optional());
 // RAW: all fields optional — undefined means "inherit" from lower layers.
+/**
+ * Programmatic options schema (raw).
+ *
+ * This schema is the canonical runtime source of truth for the `getDotenv()` programmatic API.
+ * All fields are optional; `undefined` generally means “inherit default/lower layer”.
+ *
+ * @public
+ */
 const getDotenvOptionsSchemaRaw = z.object({
+    /** Default environment name when `env` is not provided. */
     defaultEnv: z.string().optional(),
+    /** Base dotenv filename token (default `.env`). */
     dotenvToken: z.string().optional(),
+    /** Path to a dynamic variables module (JS/TS) to load and apply. */
     dynamicPath: z.string().optional(),
-    // Dynamic map is intentionally wide for now; refine once sources are normalized.
+    /** Dynamic map is intentionally wide for now; refine once sources are normalized. */
     dynamic: z.record(z.string(), z.unknown()).optional(),
+    /** Selected environment name for this invocation (for env-scoped files and overlays). */
     env: z.string().optional(),
+    /** When true, skip applying dynamic variables. */
     excludeDynamic: z.boolean().optional(),
+    /** When true, skip environment-scoped dotenv files. */
     excludeEnv: z.boolean().optional(),
+    /** When true, skip global dotenv files. */
     excludeGlobal: z.boolean().optional(),
+    /** When true, skip private dotenv files. */
     excludePrivate: z.boolean().optional(),
+    /** When true, skip public dotenv files. */
     excludePublic: z.boolean().optional(),
+    /** When true, merge the final composed environment into `process.env`. */
     loadProcess: z.boolean().optional(),
+    /** When true, log the final environment map via `logger`. */
     log: z.boolean().optional(),
+    /** Logger used when `log` is enabled (console-compatible). */
     logger: z.unknown().default(console),
+    /** Optional output dotenv file path to write after composition. */
     outputPath: z.string().optional(),
+    /** Dotenv search paths (ordered). */
     paths: z.array(z.string()).optional(),
+    /** Private token suffix for private dotenv files (default `local`). */
     privateToken: z.string().optional(),
+    /** Explicit variables to overlay onto the composed dotenv map. */
     vars: processEnvSchema.optional(),
 });
 
@@ -46,27 +78,55 @@ const getDotenvOptionsSchemaRaw = z.object({
  * reflect normalized types (paths: string[], vars: ProcessEnv), applied in the
  * CLI resolution pipeline.
  */
+/**
+ * CLI options schema (raw).
+ *
+ * Extends the programmatic options schema with CLI-only flags and stringly inputs
+ * which are normalized later by the host resolution pipeline.
+ *
+ * @public
+ */
 const getDotenvCliOptionsSchemaRaw = getDotenvOptionsSchemaRaw.extend({
     // CLI-specific fields (stringly inputs before preprocessing)
+    /** Enable verbose debug output (host-specific). */
     debug: z.boolean().optional(),
+    /** Fail on validation errors (schema/requiredKeys). */
     strict: z.boolean().optional(),
+    /** Capture child process stdio (useful for CI/tests). */
     capture: z.boolean().optional(),
+    /** Emit child env diagnostics (boolean or selected keys). */
     trace: z.union([z.boolean(), z.array(z.string())]).optional(),
+    /** Enable presentation-time redaction in trace/log output. */
     redact: z.boolean().optional(),
+    /** Enable entropy warnings in trace/log output. */
     warnEntropy: z.boolean().optional(),
+    /** Entropy threshold (bits/char) for warnings. */
     entropyThreshold: z.number().optional(),
+    /** Minimum value length to consider for entropy warnings. */
     entropyMinLength: z.number().optional(),
+    /** Regex patterns (strings) to suppress entropy warnings by key. */
     entropyWhitelist: z.array(z.string()).optional(),
+    /** Additional key-match patterns (strings) for redaction. */
     redactPatterns: z.array(z.string()).optional(),
+    /** Dotenv search paths provided as a single delimited string. */
     paths: z.string().optional(),
+    /** Delimiter string used to split `paths`. */
     pathsDelimiter: z.string().optional(),
+    /** Regex pattern used to split `paths` (takes precedence over delimiter). */
     pathsDelimiterPattern: z.string().optional(),
+    /** Scripts table in a permissive shape at parse time (validated elsewhere). */
     scripts: z.record(z.string(), z.unknown()).optional(),
+    /** Shell selection (`false` for shell-off, string for explicit shell). */
     shell: z.union([z.boolean(), z.string()]).optional(),
+    /** Extra variables expressed as a single delimited string of assignments. */
     vars: z.string().optional(),
+    /** Assignment operator used when parsing `vars`. */
     varsAssignor: z.string().optional(),
+    /** Regex pattern used as the assignment operator for `vars` parsing. */
     varsAssignorPattern: z.string().optional(),
+    /** Delimiter string used to split `vars`. */
     varsDelimiter: z.string().optional(),
+    /** Regex pattern used to split `vars` (takes precedence over delimiter). */
     varsDelimiterPattern: z.string().optional(),
 });
 
@@ -90,17 +150,34 @@ const envStringMap = z.record(z.string(), stringMap);
  * Raw configuration schema for get‑dotenv config files (JSON/YAML/JS/TS).
  * Validates allowed top‑level keys without performing path normalization.
  */
+/**
+ * Config schema for discovered get-dotenv configuration documents (raw).
+ *
+ * This schema validates the allowed top-level keys for configuration files.
+ * It does not normalize paths or coerce types beyond Zod’s parsing.
+ *
+ * @public
+ */
 const getDotenvConfigSchemaRaw = z.object({
+    /** Root option defaults applied by the host (CLI-like, collapsed families). */
     rootOptionDefaults: getDotenvCliOptionsSchemaRaw.optional(),
+    /** Help-time visibility map for root flags (false hides). */
     rootOptionVisibility: visibilityMap.optional(),
-    scripts: z.record(z.string(), z.unknown()).optional(), // Scripts validation left wide; generator validates elsewhere
+    /** Scripts table used by cmd/batch resolution (validation intentionally permissive here). */
+    scripts: z.record(z.string(), z.unknown()).optional(),
+    /** Keys required to be present in the final composed environment. */
     requiredKeys: z.array(z.string()).optional(),
+    /** Validation schema (JS/TS only; JSON/YAML loader rejects). */
     schema: z.unknown().optional(), // JS/TS-only; loader rejects in JSON/YAML
+    /** Public global variables (string-only). */
     vars: stringMap.optional(), // public, global
+    /** Public per-environment variables (string-only). */
     envVars: envStringMap.optional(), // public, per-env
     // Dynamic in config (JS/TS only). JSON/YAML loader will reject if set.
+    /** Dynamic variable definitions (JS/TS only). */
     dynamic: z.unknown().optional(),
     // Per-plugin config bag; validated by plugins/host when used.
+    /** Per-plugin config slices keyed by realized mount path (for example, `aws/whoami`). */
     plugins: z.record(z.string(), z.unknown()).optional(),
 });
 /**

package/dist/env-overlay.d.ts

@@ -104,6 +104,11 @@ type ScriptsTable<TShell extends string | boolean = string | boolean> = Record<s
  */
 type Scripts = ScriptsTable;
 
+/**
+ * Resolved configuration object type returned by {@link getDotenvConfigSchemaResolved}.
+ *
+ * @public
+ */
 type GetDotenvConfigResolved = {
     /**
      * Help-time/runtime root defaults applied by the host (collapsed families; CLI‑like).
@@ -242,6 +247,9 @@ interface OverlayEnvOptionsBase<B extends Record<string, string | undefined> | R
  * @public
  */
 interface OverlayEnvOptionsWithProgrammatic<B extends Record<string, string | undefined> | Readonly<Record<string, string | undefined>>, P extends Record<string, string | undefined> | Readonly<Record<string, string | undefined>>> extends OverlayEnvOptionsBase<B> {
+    /**
+     * Explicit programmatic variables applied at the highest precedence tier.
+     */
     programmaticVars: P;
 }
 /**