@karmaniverous/get-dotenv 6.5.1 → 6.5.2

package/dist/index.d.ts

@@ -1792,6 +1792,52 @@ declare const applyIncludeExclude: (env: ProcessEnv, { include, exclude, }: {
     exclude?: string[];
 }) => ProcessEnv;
 
+/**
+ * Assert that a value is a non-empty string.
+ *
+ * @param v - Value to check.
+ * @param msg - Error message to throw if check fails.
+ */
+declare const requireString: (v: unknown, msg: string) => string;
+/**
+ * Assert that the byte length of a value (stringified) does not exceed a limit.
+ *
+ * @param value - Value to measure (strings used as-is; others JSON-stringified).
+ * @param limit - Maximum allowed byte length.
+ * @param errorMsg - Error message string or generator function.
+ */
+declare const assertByteLimit: (value: unknown, limit: number, errorMsg: string | ((v: unknown, l: number) => string)) => void;
+
+/**
+ * Perform a deep defaults‑style merge across plain objects.
+ * - Only merges plain objects (prototype === Object.prototype).
+ * - Arrays and non‑objects are replaced, not merged.
+ * - `undefined` values are ignored and do not overwrite prior values.
+ *
+ * @typeParam T - Resulting shape after merging all layers.
+ * @returns The merged object typed as T.
+ *
+ * @example
+ * defaultsDeep(\{ a: 1, nested: \{ b: 2 \} \}, \{ nested: \{ b: 3, c: 4 \} \})
+ * =\> \{ a: 1, nested: \{ b: 3, c: 4 \} \}
+ */
+declare function defaultsDeep<A extends object>(a?: Partial<A>): A;
+declare function defaultsDeep<A extends object, B extends object>(a?: Partial<A>, b?: Partial<B>): A & B;
+declare function defaultsDeep<A extends object, B extends object, C extends object>(a?: Partial<A>, b?: Partial<B>, c?: Partial<C>): A & B & C;
+declare function defaultsDeep<A extends object, B extends object, C extends object, D extends object>(a?: Partial<A>, b?: Partial<B>, c?: Partial<C>, d?: Partial<D>): A & B & C & D;
+declare function defaultsDeep<A extends object, B extends object, C extends object, D extends object, E extends object>(a?: Partial<A>, b?: Partial<B>, c?: Partial<C>, d?: Partial<D>, e?: Partial<E>): A & B & C & D & E;
+declare function defaultsDeep<T extends object>(...layers: Array<Partial<T> | undefined>): T;
+
+/**
+ * Serialize a dotenv record to a file with minimal quoting (multiline values are quoted).
+ * Future-proofs for ordering/sorting changes (currently insertion order).
+ *
+ * @param filename - Destination dotenv file path.
+ * @param data - Env-like map of values to write (values may be `undefined`).
+ * @returns A `Promise\<void\>` which resolves when the file has been written.
+ */
+declare function writeDotenvFile(filename: string, data: ProcessEnv): Promise<void>;
+
 /**
  * Deeply interpolate string leaves against envRef.
  * Arrays are not recursed into; they are returned unchanged.
@@ -1803,6 +1849,36 @@ declare const applyIncludeExclude: (env: ProcessEnv, { include, exclude, }: {
  */
 declare const interpolateDeep: <T>(value: T, envRef: ProcessEnv) => T;
 
+/**
+ * Load a module default export from a JS/TS file with robust fallbacks.
+ *
+ * Behavior by extension:
+ *
+ * - `.js`/`.mjs`/`.cjs`: direct dynamic import.
+ * - `.ts`/`.mts`/`.cts`/`.tsx`:
+ *   - try direct dynamic import (when a TS loader is active),
+ *   - else compile via `esbuild` to a cached `.mjs` file and import,
+ *   - else fallback to `typescript.transpileModule` for simple modules.
+ *
+ * @typeParam T - Type of the expected default export.
+ * @param absPath - Absolute path to the source file.
+ * @param cacheDirName - Cache subfolder under `.tsbuild/`.
+ * @returns A `Promise\<T | undefined\>` resolving to the default export (if any).
+ */
+declare const loadModuleDefault: <T>(absPath: string, cacheDirName: string) => Promise<T | undefined>;
+
+/**
+ * A silent logger that implements the Logger interface but performs no operations.
+ */
+declare const silentLogger: Logger;
+
+/**
+ * Parse a value into a number or undefined.
+ *
+ * @param v - Value to parse.
+ * @returns The parsed number, or undefined if the input was undefined or empty string.
+ */
+declare const toNumber: (v: unknown) => number | undefined;
 /**
  * Build a Commander option parser that coerces a raw string to a finite number.
  *
@@ -1825,5 +1901,27 @@ declare const parsePositiveInt: (label: string) => (raw: string) => number;
  */
 declare const parseNonNegativeInt: (label: string) => (raw: string) => number;
 
-export { GetDotenvCli, applyDotenvEdits, applyIncludeExclude, baseRootOptionDefaults, buildSpawnEnv, createCli, defineDynamic, defineGetDotenvConfig, definePlugin, defineScripts, dotenvExpand, dotenvExpandAll, dotenvExpandFromProcessEnv, editDotenvFile, editDotenvText, getDotenv, getDotenvCliOptions2Options, groupPlugins, interpolateDeep, maybeWarnEntropy, parseDotenvDocument, parseFiniteNumber, parseNonNegativeInt, parsePositiveInt, readMergedOptions, redactDisplay, redactObject, renderDotenvDocument, shouldCapture, traceChildEnv };
-export type { CreateCliOptions, DotenvAssignmentSegment, DotenvBareKeySegment, DotenvConfigProvenanceEntry, DotenvDocument, DotenvDuplicateKeyStrategy, DotenvDynamicProvenanceEntry, DotenvDynamicSource, DotenvEditMode, DotenvEditOptions, DotenvEolMode, DotenvFileProvenanceEntry, DotenvFs, DotenvPathSearchOrder, DotenvProvenance, DotenvProvenanceEntry, DotenvProvenanceEntryBase, DotenvProvenanceKind, DotenvProvenanceOp, DotenvSegment, DotenvTargetPrivacy, DotenvTargetScope, DotenvUpdateMap, DotenvUpdateValue, DotenvVarsProvenanceEntry, DynamicFn, DynamicMap, EditDotenvFileOptions, EditDotenvFileResult, EntropyOptions, GetDotenvCliOptions, GetDotenvCliPlugin, GetDotenvCliPublic, GetDotenvConfig, GetDotenvDynamic, GetDotenvOptions, InferGetDotenvVarsFromConfig, InferPluginConfig, PluginWithInstanceHelpers, ProcessEnv, RedactOptions, ScriptsTable, TraceChildEnvOptions };
+/**
+ * Options for the tokenizer used by shell-off command handling.
+ *
+ * @public
+ */
+interface TokenizeOptions {
+    /**
+     * When true, keep doubled quotes inside a quoted segment (e.g., `""` stays `""`),
+     * which is useful for preserving Node -e payload quoting patterns.
+     * When false (default), doubled quotes collapse to a single literal quote.
+     */
+    preserveDoubledQuotes?: boolean;
+}
+/**
+ * Minimal tokenizer for shell-off execution.
+ * Splits by whitespace while preserving quoted segments (single or double quotes).
+ *
+ * @param command - The command string to tokenize.
+ * @param opts - Tokenization options (e.g. quote handling).
+ */
+declare const tokenize: (command: string, opts?: TokenizeOptions) => string[];
+
+export { GetDotenvCli, applyDotenvEdits, applyIncludeExclude, assertByteLimit, baseRootOptionDefaults, buildSpawnEnv, createCli, defaultsDeep, defineDynamic, defineGetDotenvConfig, definePlugin, defineScripts, dotenvExpand, dotenvExpandAll, dotenvExpandFromProcessEnv, editDotenvFile, editDotenvText, getDotenv, getDotenvCliOptions2Options, groupPlugins, interpolateDeep, loadModuleDefault, maybeWarnEntropy, parseDotenvDocument, parseFiniteNumber, parseNonNegativeInt, parsePositiveInt, readMergedOptions, redactDisplay, redactObject, renderDotenvDocument, requireString, shouldCapture, silentLogger, toNumber, tokenize, traceChildEnv, writeDotenvFile };
+export type { CreateCliOptions, DotenvAssignmentSegment, DotenvBareKeySegment, DotenvConfigProvenanceEntry, DotenvDocument, DotenvDuplicateKeyStrategy, DotenvDynamicProvenanceEntry, DotenvDynamicSource, DotenvEditMode, DotenvEditOptions, DotenvEolMode, DotenvFileProvenanceEntry, DotenvFs, DotenvPathSearchOrder, DotenvProvenance, DotenvProvenanceEntry, DotenvProvenanceEntryBase, DotenvProvenanceKind, DotenvProvenanceOp, DotenvSegment, DotenvTargetPrivacy, DotenvTargetScope, DotenvUpdateMap, DotenvUpdateValue, DotenvVarsProvenanceEntry, DynamicFn, DynamicMap, EditDotenvFileOptions, EditDotenvFileResult, EntropyOptions, GetDotenvCliOptions, GetDotenvCliPlugin, GetDotenvCliPublic, GetDotenvConfig, GetDotenvDynamic, GetDotenvOptions, InferGetDotenvVarsFromConfig, InferPluginConfig, PluginWithInstanceHelpers, ProcessEnv, RedactOptions, ScriptsTable, TokenizeOptions, TraceChildEnvOptions };

package/dist/index.mjs

@@ -1,27 +1,27 @@
 export { c as createCli } from './chunks/createCli-pZgHlwKX.mjs';
 import { e as resolveGetDotenvOptions, w as writeDotenvFile } from './chunks/readMergedOptions-uWSetyes.mjs';
-export { G as GetDotenvCli, b as baseRootOptionDefaults, f as defineDynamic, h as defineGetDotenvConfig, d as definePlugin, g as getDotenvCliOptions2Options, i as interpolateDeep, r as readMergedOptions } from './chunks/readMergedOptions-uWSetyes.mjs';
-export { d as buildSpawnEnv, s as shouldCapture } from './chunks/spawnEnv-5kdIVv0x.mjs';
+export { G as GetDotenvCli, b as baseRootOptionDefaults, a as defaultsDeep, f as defineDynamic, h as defineGetDotenvConfig, d as definePlugin, g as getDotenvCliOptions2Options, i as interpolateDeep, r as readMergedOptions } from './chunks/readMergedOptions-uWSetyes.mjs';
+export { d as buildSpawnEnv, s as shouldCapture, t as tokenize } from './chunks/spawnEnv-5kdIVv0x.mjs';
 export { d as defineScripts, g as groupPlugins } from './chunks/types-BSMtAo8_.mjs';
 import { omit, pick } from 'radash';
-import 'node:buffer';
-import fs from 'fs-extra';
-import 'crypto';
-import path$1 from 'path';
-import 'url';
+import { Buffer } from 'node:buffer';
+export { l as loadModuleDefault } from './chunks/loadModuleDefault-Dj8B3Stt.mjs';
 import { InvalidArgumentError } from '@commander-js/extra-typings';
 export { z } from 'zod';
 import { nanoid } from 'nanoid';
+import path$1 from 'path';
 import { r as redactObject, m as maybeWarnEntropy } from './chunks/index-Cg50N4ys.mjs';
 export { a as redactDisplay, t as traceChildEnv } from './chunks/index-Cg50N4ys.mjs';
 import { g as readDotenv, d as dotenvExpandAll, a as applyDynamicMap, c as loadAndApplyDynamic } from './chunks/readDotenvCascade-HLU7FsEQ.mjs';
 export { h as dotenvExpand, f as dotenvExpandFromProcessEnv } from './chunks/readDotenvCascade-HLU7FsEQ.mjs';
+import fs from 'fs-extra';
 import path from 'node:path';
+import 'crypto';
+import 'url';
 import 'dotenv';
 import './chunks/loader-CE4HSRN4.mjs';
 import 'package-directory';
 import 'yaml';
-import './chunks/loadModuleDefault-Dj8B3Stt.mjs';
 import 'execa';
 import './chunks/helpConfig-CGejgwWW.mjs';
 import './chunks/resolveCliOptions-7MwNdHqz.mjs';
@@ -63,6 +63,33 @@ const applyIncludeExclude = (env, { include, exclude, }) => {
     return out;
 };
 
+/**
+ * Assert that a value is a non-empty string.
+ *
+ * @param v - Value to check.
+ * @param msg - Error message to throw if check fails.
+ */
+const requireString = (v, msg) => {
+    if (typeof v !== 'string' || !v)
+        throw new Error(msg);
+    return v;
+};
+/**
+ * Assert that the byte length of a value (stringified) does not exceed a limit.
+ *
+ * @param value - Value to measure (strings used as-is; others JSON-stringified).
+ * @param limit - Maximum allowed byte length.
+ * @param errorMsg - Error message string or generator function.
+ */
+const assertByteLimit = (value, limit, errorMsg) => {
+    const s = typeof value === 'string' ? value : JSON.stringify(value);
+    const bytes = Buffer.byteLength(s, 'utf8');
+    if (bytes > limit) {
+        const msg = typeof errorMsg === 'function' ? errorMsg(value, limit) : errorMsg;
+        throw new Error(msg);
+    }
+};
+
 /**
  * Dotenv editor types (format-preserving).
  *
@@ -799,6 +826,32 @@ async function editDotenvFile(updates, options) {
     return { path: resolved.targetPath, createdFromTemplate, changed };
 }
 
+/**
+ * A silent logger that implements the Logger interface but performs no operations.
+ */
+const silentLogger = {
+    debug: () => { },
+    info: () => { },
+    warn: () => { },
+    error: () => { },
+    log: () => { },
+};
+
+/**
+ * Parse a value into a number or undefined.
+ *
+ * @param v - Value to parse.
+ * @returns The parsed number, or undefined if the input was undefined or empty string.
+ */
+const toNumber = (v) => {
+    if (typeof v === 'undefined')
+        return;
+    if (typeof v === 'number')
+        return v;
+    if (typeof v === 'string' && v.trim())
+        return Number(v);
+    return;
+};
 /**
  * Build a Commander option parser that coerces a raw string to a finite number.
  *
@@ -944,4 +997,4 @@ async function getDotenv(options = {}) {
     return resultDotenv;
 }
 
-export { applyDotenvEdits, applyIncludeExclude, dotenvExpandAll, editDotenvFile, editDotenvText, getDotenv, maybeWarnEntropy, parseDotenvDocument, parseFiniteNumber, parseNonNegativeInt, parsePositiveInt, redactObject, renderDotenvDocument };
+export { applyDotenvEdits, applyIncludeExclude, assertByteLimit, dotenvExpandAll, editDotenvFile, editDotenvText, getDotenv, maybeWarnEntropy, parseDotenvDocument, parseFiniteNumber, parseNonNegativeInt, parsePositiveInt, redactObject, renderDotenvDocument, requireString, silentLogger, toNumber, writeDotenvFile };

package/package.json

@@ -221,5 +221,5 @@
   },
   "type": "module",
   "types": "dist/index.d.ts",
-  "version": "6.5.1"
+  "version": "6.5.2"
 }