typed-settings 0.1.0 → 0.1.4

package/dist/index.d.cts

@@ -1,12 +1,51 @@
 import { StandardSchemaV1 } from '@standard-schema/spec';
-import { S as SettingsOptions, F as Flat } from './types-BswIPp7U.cjs';
-export { A as ArrayStrategy, a as SecretProvider, b as SourceInput, U as UnknownKeys } from './types-BswIPp7U.cjs';
-export { C as ConfigError } from './errors-IU9n4f3t.cjs';
+import { S as SettingsOptions, F as Flat } from './types-B_Dc2L4T.cjs';
+export { A as ArrayStrategy, a as SecretProvider, b as SourceInput, U as UnknownKeys } from './types-B_Dc2L4T.cjs';
+export { C as ConfigError } from './errors-itGaU4Q8.cjs';
 
+/**
+ * Typed config in one call.
+ *
+ * `settings()` / `settingsAsync()` load env, `.env` files, YAML/TOML/JSON,
+ * secrets-dir maps, and vault secrets, then merge, expand `$VAR` references,
+ * coerce, validate against a Standard Schema, and return the result frozen.
+ * Anything invalid throws `ConfigError` at boot with the key and source attached.
+ *
+ * @module
+ */
+
+/**
+ * Runs `fn` with `process.env` patched by `map` (`undefined` deletes a key),
+ * then restores the exact previous environment — synchronously for sync `fn`,
+ * held until settle for async `fn`. Restores on throw too.
+ */
 declare function withOverrides<T>(map: Flat, fn: () => T): T;
+/**
+ * Copies only the listed, actually-present keys. A missing key yields no entry
+ * (not `{ k: undefined }`), and nothing is spread, so secrets can't leak through.
+ */
 declare function pickPublic<T extends object>(cfg: T, keys: (keyof T)[]): Partial<T>;
+/**
+ * Map-only settings for Vite-style `import.meta.env` objects: validates the
+ * map with no filesystem and no ambient env. (The framework entry's overload
+ * drops `sources`/`env` from the options.)
+ */
 declare function viteSettings<S extends StandardSchemaV1>(opts: SettingsOptions<S>, metaEnv: Flat): StandardSchemaV1.InferOutput<S>;
+/**
+ * Loads, merges, expands, coerces, and validates config synchronously, returning
+ * the inferred output type, frozen. Each issue names the failing `path` and the
+ * source that won it, with secrets redacted.
+ *
+ * @throws ConfigError on merge, parse, expansion, or validation failure.
+ * @throws ConfigError with `code: 'USE_ASYNC'` if a provider or the schema is
+ * async — switch to `settingsAsync()`.
+ */
 declare function settings<S extends StandardSchemaV1>(opts: SettingsOptions<S>): StandardSchemaV1.InferOutput<S>;
+/**
+ * Async twin of `settings()`: awaits async providers (whole collection races
+ * `timeoutMs`) and async schemas, with the same merge/expand/coerce/validate/
+ * freeze pipeline and the same `ConfigError` contract.
+ */
 declare function settingsAsync<S extends StandardSchemaV1>(opts: SettingsOptions<S>): Promise<StandardSchemaV1.InferOutput<S>>;
 
 export { Flat, SettingsOptions, pickPublic, settings, settingsAsync, viteSettings, withOverrides };

package/dist/index.d.ts

@@ -1,12 +1,51 @@
 import { StandardSchemaV1 } from '@standard-schema/spec';
-import { S as SettingsOptions, F as Flat } from './types-BswIPp7U.js';
-export { A as ArrayStrategy, a as SecretProvider, b as SourceInput, U as UnknownKeys } from './types-BswIPp7U.js';
-export { C as ConfigError } from './errors-IU9n4f3t.js';
+import { S as SettingsOptions, F as Flat } from './types-B_Dc2L4T.js';
+export { A as ArrayStrategy, a as SecretProvider, b as SourceInput, U as UnknownKeys } from './types-B_Dc2L4T.js';
+export { C as ConfigError } from './errors-itGaU4Q8.js';
 
+/**
+ * Typed config in one call.
+ *
+ * `settings()` / `settingsAsync()` load env, `.env` files, YAML/TOML/JSON,
+ * secrets-dir maps, and vault secrets, then merge, expand `$VAR` references,
+ * coerce, validate against a Standard Schema, and return the result frozen.
+ * Anything invalid throws `ConfigError` at boot with the key and source attached.
+ *
+ * @module
+ */
+
+/**
+ * Runs `fn` with `process.env` patched by `map` (`undefined` deletes a key),
+ * then restores the exact previous environment — synchronously for sync `fn`,
+ * held until settle for async `fn`. Restores on throw too.
+ */
 declare function withOverrides<T>(map: Flat, fn: () => T): T;
+/**
+ * Copies only the listed, actually-present keys. A missing key yields no entry
+ * (not `{ k: undefined }`), and nothing is spread, so secrets can't leak through.
+ */
 declare function pickPublic<T extends object>(cfg: T, keys: (keyof T)[]): Partial<T>;
+/**
+ * Map-only settings for Vite-style `import.meta.env` objects: validates the
+ * map with no filesystem and no ambient env. (The framework entry's overload
+ * drops `sources`/`env` from the options.)
+ */
 declare function viteSettings<S extends StandardSchemaV1>(opts: SettingsOptions<S>, metaEnv: Flat): StandardSchemaV1.InferOutput<S>;
+/**
+ * Loads, merges, expands, coerces, and validates config synchronously, returning
+ * the inferred output type, frozen. Each issue names the failing `path` and the
+ * source that won it, with secrets redacted.
+ *
+ * @throws ConfigError on merge, parse, expansion, or validation failure.
+ * @throws ConfigError with `code: 'USE_ASYNC'` if a provider or the schema is
+ * async — switch to `settingsAsync()`.
+ */
 declare function settings<S extends StandardSchemaV1>(opts: SettingsOptions<S>): StandardSchemaV1.InferOutput<S>;
+/**
+ * Async twin of `settings()`: awaits async providers (whole collection races
+ * `timeoutMs`) and async schemas, with the same merge/expand/coerce/validate/
+ * freeze pipeline and the same `ConfigError` contract.
+ */
 declare function settingsAsync<S extends StandardSchemaV1>(opts: SettingsOptions<S>): Promise<StandardSchemaV1.InferOutput<S>>;
 
 export { Flat, SettingsOptions, pickPublic, settings, settingsAsync, viteSettings, withOverrides };

package/dist/index.js

@@ -1,4 +1,4 @@
-export { pickPublic, settings, settingsAsync, viteSettings, withOverrides } from './chunk-RCO6K3WQ.js';
+export { pickPublic, settings, settingsAsync, viteSettings, withOverrides } from './chunk-YVJEZPPZ.js';
 import './chunk-33M5GIKQ.js';
 import './chunk-OVFMKC2O.js';
 import './chunk-UFUHHR2J.js';

package/dist/node.cjs

@@ -444,12 +444,12 @@ function expandKeys(flat, opts) {
     const stripped = stripPrefix(rawKey);
     if (stripped === null) continue;
     const useKey = stripped;
-    if (useKey.includes("__")) {
-      if (FORBIDDEN.has(useKey.toLowerCase())) throw new ConfigError([{ path: rawKey, from: "keys", message: "E_PROTO: forbidden key" }], "E_PROTO");
-      const parts = useKey.split("__");
+    if (FORBIDDEN.has(useKey.toLowerCase())) throw new ConfigError([{ path: rawKey, from: "keys", message: "E_PROTO: forbidden key" }], "E_PROTO");
+    const parts = useKey.split("__");
+    const cleanSplit = parts.length > 1 && parts.every((p) => p !== "");
+    if (cleanSplit) {
       for (const p of parts) {
         if (FORBIDDEN.has(p.toLowerCase())) throw new ConfigError([{ path: rawKey, from: "keys", message: "E_PROTO: forbidden key" }], "E_PROTO");
-        if (!p) throw new ConfigError([{ path: rawKey, from: "keys", message: "E_EMPTY_SEGMENT" }], "E_EMPTY_SEGMENT");
       }
       const lowered = parts.map((p) => p.toLowerCase());
       const top = lowered[0];
@@ -481,7 +481,6 @@ function expandKeys(flat, opts) {
       setPath(out, lowered, value);
     } else {
       const k = useKey.toLowerCase();
-      if (FORBIDDEN.has(k)) throw new ConfigError([{ path: rawKey, from: "keys", message: "E_PROTO" }], "E_PROTO");
       const kind = kindOf(k);
       if (kind.indexed) {
         throw new ConfigError(
@@ -861,7 +860,13 @@ function makeLookup(merged, envSnapshot) {
 function expandDeepStrings(obj, lookup, ctx, path = []) {
   if (typeof obj === "string") {
     const top = (path[0] ?? "<root>").toLowerCase();
-    return expandLeaf(obj, lookup, { ...ctx, from: ctx.fromMap.get(top) ?? "config" }, path.map((p) => p.toLowerCase()));
+    const from = ctx.fromMap.get(top) ?? "config";
+    try {
+      return expandLeaf(obj, lookup, { ...ctx, from }, path.map((p) => p.toLowerCase()));
+    } catch (e) {
+      if (from === "env") return obj;
+      throw e;
+    }
   }
   if (Array.isArray(obj)) return obj.map((x, i) => expandDeepStrings(x, lookup, ctx, [...path, String(i)]));
   if (obj && typeof obj === "object") {

package/dist/node.d.cts

@@ -1,27 +1,54 @@
-import { F as Flat, S as SettingsOptions } from './types-BswIPp7U.cjs';
+import { F as Flat, S as SettingsOptions } from './types-B_Dc2L4T.cjs';
 import { StandardSchemaV1 } from '@standard-schema/spec';
-import { C as ConfigError } from './errors-IU9n4f3t.cjs';
+import { C as ConfigError } from './errors-itGaU4Q8.cjs';
 
+/**
+ * Reads dotenv files and joins them with newlines for `{ text }` sources.
+ * Missing files are skipped; anything else (e.g. `EACCES`) rethrows.
+ */
 declare function loadEnvFiles(paths: string[]): {
     text: string;
 };
+/**
+ * Reads a secrets dir (Docker/K8s `/run/secrets`) into a flat map keyed by
+ * uppercased filenames. Skips subdirectories, `..*` entries, and empties; strips
+ * one trailing newline but otherwise preserves whitespace verbatim. Missing dir
+ * reads as `{}`; unreadable files throw (`EACCES` fails closed).
+ */
 declare function loadSecretsDir(dir: string): Flat;
+/**
+ * Parses one dotenv file into a flat map. Missing file reads as `{}`;
+ * anything else (including `EACCES` and syntax errors) rethrows.
+ */
 declare function parseEnvFile(path: string): Flat;
+/** Watch tuning: debounce, provider/dir refresh, stat-poll fallback, and callbacks. */
 interface WatchCallbacks {
+    /** Coalesce rapid saves. Default 100. */
     debounceMs?: number;
+    /** Re-poll providers/secrets-dirs. Default 0=off (60000 when providers present). */
     refreshMs?: number;
+    /** Stat-poll fallback for NFS/Docker where fs events are unreliable. Default 0=off. */
     pollMs?: number;
+    /** Fires on each successful reload with the new config and changed leaf paths. */
     onUpdate?: (cfg: unknown, changed: string[]) => void;
+    /** Fires when a reload fails; the old config stays live. Never throws outward. */
     onError?: (e: ConfigError | Error, info?: {
         version: number;
     }) => void;
 }
+/** Live config subscription. `reload()` re-reads now; `dispose()` is idempotent. */
 interface WatchHandle<T = unknown> {
     get(): T;
     reload(): Promise<void>;
     dispose(): Promise<void>;
     readonly version: number;
 }
+/**
+ * Subscribes to config files with parent-dir watching (survives atomic renames),
+ * debounced reloads, and stable-size settling. Each reload validates off-side and
+ * swaps only on success, reporting changed leaf paths; failures keep the old
+ * config and notify `onError`. Overlapping reloads drop the stale one.
+ */
 declare function watchSettings<S extends StandardSchemaV1>(opts: SettingsOptions<S>, cb?: WatchCallbacks): WatchHandle<StandardSchemaV1.InferOutput<S>>;
 
 export { type WatchCallbacks, type WatchHandle, loadEnvFiles, loadSecretsDir, parseEnvFile, watchSettings };

package/dist/node.d.ts

@@ -1,27 +1,54 @@
-import { F as Flat, S as SettingsOptions } from './types-BswIPp7U.js';
+import { F as Flat, S as SettingsOptions } from './types-B_Dc2L4T.js';
 import { StandardSchemaV1 } from '@standard-schema/spec';
-import { C as ConfigError } from './errors-IU9n4f3t.js';
+import { C as ConfigError } from './errors-itGaU4Q8.js';
 
+/**
+ * Reads dotenv files and joins them with newlines for `{ text }` sources.
+ * Missing files are skipped; anything else (e.g. `EACCES`) rethrows.
+ */
 declare function loadEnvFiles(paths: string[]): {
     text: string;
 };
+/**
+ * Reads a secrets dir (Docker/K8s `/run/secrets`) into a flat map keyed by
+ * uppercased filenames. Skips subdirectories, `..*` entries, and empties; strips
+ * one trailing newline but otherwise preserves whitespace verbatim. Missing dir
+ * reads as `{}`; unreadable files throw (`EACCES` fails closed).
+ */
 declare function loadSecretsDir(dir: string): Flat;
+/**
+ * Parses one dotenv file into a flat map. Missing file reads as `{}`;
+ * anything else (including `EACCES` and syntax errors) rethrows.
+ */
 declare function parseEnvFile(path: string): Flat;
+/** Watch tuning: debounce, provider/dir refresh, stat-poll fallback, and callbacks. */
 interface WatchCallbacks {
+    /** Coalesce rapid saves. Default 100. */
     debounceMs?: number;
+    /** Re-poll providers/secrets-dirs. Default 0=off (60000 when providers present). */
     refreshMs?: number;
+    /** Stat-poll fallback for NFS/Docker where fs events are unreliable. Default 0=off. */
     pollMs?: number;
+    /** Fires on each successful reload with the new config and changed leaf paths. */
     onUpdate?: (cfg: unknown, changed: string[]) => void;
+    /** Fires when a reload fails; the old config stays live. Never throws outward. */
     onError?: (e: ConfigError | Error, info?: {
         version: number;
     }) => void;
 }
+/** Live config subscription. `reload()` re-reads now; `dispose()` is idempotent. */
 interface WatchHandle<T = unknown> {
     get(): T;
     reload(): Promise<void>;
     dispose(): Promise<void>;
     readonly version: number;
 }
+/**
+ * Subscribes to config files with parent-dir watching (survives atomic renames),
+ * debounced reloads, and stable-size settling. Each reload validates off-side and
+ * swaps only on success, reporting changed leaf paths; failures keep the old
+ * config and notify `onError`. Overlapping reloads drop the stale one.
+ */
 declare function watchSettings<S extends StandardSchemaV1>(opts: SettingsOptions<S>, cb?: WatchCallbacks): WatchHandle<StandardSchemaV1.InferOutput<S>>;
 
 export { type WatchCallbacks, type WatchHandle, loadEnvFiles, loadSecretsDir, parseEnvFile, watchSettings };

package/dist/node.js

@@ -1,5 +1,5 @@
-export { loadEnvFiles, loadSecretsDir, parseEnvFile, watchSettings } from './chunk-VTIYOSG2.js';
-import './chunk-RCO6K3WQ.js';
+export { loadEnvFiles, loadSecretsDir, parseEnvFile, watchSettings } from './chunk-DEP5SD4J.js';
+import './chunk-YVJEZPPZ.js';
 import './chunk-33M5GIKQ.js';
 import './chunk-OVFMKC2O.js';
 import './chunk-UFUHHR2J.js';

package/dist/{shared-DBcV6jIy.d.cts → shared-CucO_XsG.d.cts}

@@ -1,3 +1,4 @@
+/** Injectable fetch shape, so tests never need a live server. */
 type FetchFn = (url: string, init?: RequestInit) => Promise<Response>;
 
 export type { FetchFn as F };

package/dist/{shared-DBcV6jIy.d.ts → shared-CucO_XsG.d.ts}

@@ -1,3 +1,4 @@
+/** Injectable fetch shape, so tests never need a live server. */
 type FetchFn = (url: string, init?: RequestInit) => Promise<Response>;
 
 export type { FetchFn as F };

package/dist/types-B_Dc2L4T.d.cts

@@ -0,0 +1,69 @@
+import { StandardSchemaV1 } from '@standard-schema/spec';
+
+/** Flat string map: the currency every source compiles to (`process.env` shape). */
+type Flat = Record<string, string | undefined>;
+/** A secret backend. `load()` may be sync or async; async forces `settingsAsync()`. */
+interface SecretProvider {
+    /** Label used in error attribution (`from`) and timeouts. */
+    name: string;
+    load(): Promise<Flat> | Flat;
+}
+/**
+ * One config source. Strings `'env' | '.env' | '.env.local'` are built-ins,
+ * any other string is a file path (relative to cwd; `.json`/`.yaml`/`.yml`/
+ * `.toml` are parsed structurally, anything else as `.env` text); objects cover
+ * inline text, files, secrets dirs (resolved by the caller), maps, and
+ * providers.
+ */
+type SourceInput = 'env' | '.env' | '.env.local' | {
+    text: string;
+} | {
+    file: string;
+} | {
+    dir: string;
+} | {
+    map: Flat;
+    prefix?: string;
+} | {
+    provider: SecretProvider;
+    prefix?: string;
+} | SecretProvider | Flat | string;
+/** How arrays merge across layers: wholesale win, append, or per-index union. */
+type ArrayStrategy = 'replace' | 'concat' | 'mergeIndex';
+/** What to do with input keys the schema doesn't declare. */
+type UnknownKeys = 'strip' | 'preserve' | 'reject';
+/** Options for `settings()` / `settingsAsync()`. Full semantics in docs/configuration.md. */
+interface SettingsOptions<S extends StandardSchemaV1 = StandardSchemaV1> {
+    /** Validating schema (zod/valibot/arktype natively, yup/joi/superstruct via bridges). */
+    schema: S;
+    /** Ordered layers, later wins. Default `['.env', 'env']`. */
+    sources?: SourceInput[];
+    /** Global prefix strip (case-insensitive, once). */
+    prefix?: string;
+    /** Fixed to `'__'`; only double underscores split keys. */
+    separator?: '__';
+    /** Best-effort leaf coercion before validation. Default true. */
+    coerce?: boolean;
+    /** `$VAR` expansion after merging. Default true. */
+    expand?: boolean;
+    /** Also expand `$VAR` inside vault-provided values. Default false. */
+    expandSecrets?: boolean;
+    /** Cross-layer array merge. Default 'replace'. */
+    arrayStrategy?: ArrayStrategy;
+    /** Undeclared keys: drop, keep, or throw. Default 'strip'. */
+    unknownKeys?: UnknownKeys;
+    /** Deep-freeze the result. Default true. */
+    freeze?: boolean;
+    /** Async provider + validation timeout in ms. Default 5000, async only. */
+    timeoutMs?: number;
+    /** Per-file read cap in UTF-8 bytes. Default 2 MiB. */
+    maxBytes?: number;
+    /** Keys used literally: no prefix strip, no `__` split. */
+    envMap?: Record<string, string>;
+    /** Keep `${MISSING}` literally instead of throwing. Default false. */
+    allowUnresolved?: boolean;
+    /** Injectable env snapshot (tests, Edge). Defaults to process.env when available. */
+    env?: Flat;
+}
+
+export type { ArrayStrategy as A, Flat as F, SettingsOptions as S, UnknownKeys as U, SecretProvider as a, SourceInput as b };

package/dist/types-B_Dc2L4T.d.ts

@@ -0,0 +1,69 @@
+import { StandardSchemaV1 } from '@standard-schema/spec';
+
+/** Flat string map: the currency every source compiles to (`process.env` shape). */
+type Flat = Record<string, string | undefined>;
+/** A secret backend. `load()` may be sync or async; async forces `settingsAsync()`. */
+interface SecretProvider {
+    /** Label used in error attribution (`from`) and timeouts. */
+    name: string;
+    load(): Promise<Flat> | Flat;
+}
+/**
+ * One config source. Strings `'env' | '.env' | '.env.local'` are built-ins,
+ * any other string is a file path (relative to cwd; `.json`/`.yaml`/`.yml`/
+ * `.toml` are parsed structurally, anything else as `.env` text); objects cover
+ * inline text, files, secrets dirs (resolved by the caller), maps, and
+ * providers.
+ */
+type SourceInput = 'env' | '.env' | '.env.local' | {
+    text: string;
+} | {
+    file: string;
+} | {
+    dir: string;
+} | {
+    map: Flat;
+    prefix?: string;
+} | {
+    provider: SecretProvider;
+    prefix?: string;
+} | SecretProvider | Flat | string;
+/** How arrays merge across layers: wholesale win, append, or per-index union. */
+type ArrayStrategy = 'replace' | 'concat' | 'mergeIndex';
+/** What to do with input keys the schema doesn't declare. */
+type UnknownKeys = 'strip' | 'preserve' | 'reject';
+/** Options for `settings()` / `settingsAsync()`. Full semantics in docs/configuration.md. */
+interface SettingsOptions<S extends StandardSchemaV1 = StandardSchemaV1> {
+    /** Validating schema (zod/valibot/arktype natively, yup/joi/superstruct via bridges). */
+    schema: S;
+    /** Ordered layers, later wins. Default `['.env', 'env']`. */
+    sources?: SourceInput[];
+    /** Global prefix strip (case-insensitive, once). */
+    prefix?: string;
+    /** Fixed to `'__'`; only double underscores split keys. */
+    separator?: '__';
+    /** Best-effort leaf coercion before validation. Default true. */
+    coerce?: boolean;
+    /** `$VAR` expansion after merging. Default true. */
+    expand?: boolean;
+    /** Also expand `$VAR` inside vault-provided values. Default false. */
+    expandSecrets?: boolean;
+    /** Cross-layer array merge. Default 'replace'. */
+    arrayStrategy?: ArrayStrategy;
+    /** Undeclared keys: drop, keep, or throw. Default 'strip'. */
+    unknownKeys?: UnknownKeys;
+    /** Deep-freeze the result. Default true. */
+    freeze?: boolean;
+    /** Async provider + validation timeout in ms. Default 5000, async only. */
+    timeoutMs?: number;
+    /** Per-file read cap in UTF-8 bytes. Default 2 MiB. */
+    maxBytes?: number;
+    /** Keys used literally: no prefix strip, no `__` split. */
+    envMap?: Record<string, string>;
+    /** Keep `${MISSING}` literally instead of throwing. Default false. */
+    allowUnresolved?: boolean;
+    /** Injectable env snapshot (tests, Edge). Defaults to process.env when available. */
+    env?: Flat;
+}
+
+export type { ArrayStrategy as A, Flat as F, SettingsOptions as S, UnknownKeys as U, SecretProvider as a, SourceInput as b };

package/dist/vault/aws.d.cts

@@ -1,26 +1,51 @@
-import { a as SecretProvider } from '../types-BswIPp7U.cjs';
+import { a as SecretProvider } from '../types-B_Dc2L4T.cjs';
 import '@standard-schema/spec';
 
+/**
+ * AWS provider: Secrets Manager ids plus SSM parameters (with decryption)
+ * merged into one flat map. SDK clients are injected, never imported blindly,
+ * so tests can pass fakes and Edge bundles stay lean.
+ *
+ * @module
+ */
+
+/** Minimal Secrets Manager surface this provider needs (real SDK client or a fake). */
 interface AwsSecretsClient {
     getSecretValue(secretId: string): Promise<{
         SecretString?: string;
         SecretBinary?: Uint8Array | string;
     } | string>;
 }
+/** Minimal SSM surface this provider needs (real SDK client or a fake). */
 interface AwsSsmClient {
     getParameters(names: string[], withDecryption?: boolean): Promise<Record<string, string>>;
 }
+/** Options for {@link awsProvider}. */
 interface AwsProviderOptions {
+    /** Secrets Manager ids. */
     secrets?: string[];
+    /** SSM names or path prefixes (trailing `/` optional). */
     params?: string[];
+    /** Reserved: region override (currently from env `AWS_REGION`). */
     region?: string;
+    /** Reserved: VersionId / stage pin. */
     versionId?: string;
+    /** Applies to the whole `load()`. Default 5000. */
     timeoutMs?: number;
+    /** Injected Secrets Manager client (or test fake); missing throws `E_NO_SDK`. */
     secretsClient?: AwsSecretsClient;
+    /** Injected SSM client (or test fake); missing throws `E_NO_SDK`. */
     ssmClient?: AwsSsmClient;
+    /** Secrets Manager value cap in bytes. Default 64 KiB. */
     maxBytesSecret?: number;
+    /** SSM value cap in bytes. Default 8 KiB. */
     maxBytesParam?: number;
 }
+/**
+ * Merges Secrets Manager values (JSON objects merge, scalars key on the last id
+ * segment) with SSM parameters (longest-prefix strip, `/` to `__`, uppercased).
+ * Concurrent `load()` calls share one in-flight request.
+ */
 declare function awsProvider(opts: AwsProviderOptions): SecretProvider;
 
 export { type AwsProviderOptions, type AwsSecretsClient, type AwsSsmClient, awsProvider };

package/dist/vault/aws.d.ts

@@ -1,26 +1,51 @@
-import { a as SecretProvider } from '../types-BswIPp7U.js';
+import { a as SecretProvider } from '../types-B_Dc2L4T.js';
 import '@standard-schema/spec';
 
+/**
+ * AWS provider: Secrets Manager ids plus SSM parameters (with decryption)
+ * merged into one flat map. SDK clients are injected, never imported blindly,
+ * so tests can pass fakes and Edge bundles stay lean.
+ *
+ * @module
+ */
+
+/** Minimal Secrets Manager surface this provider needs (real SDK client or a fake). */
 interface AwsSecretsClient {
     getSecretValue(secretId: string): Promise<{
         SecretString?: string;
         SecretBinary?: Uint8Array | string;
     } | string>;
 }
+/** Minimal SSM surface this provider needs (real SDK client or a fake). */
 interface AwsSsmClient {
     getParameters(names: string[], withDecryption?: boolean): Promise<Record<string, string>>;
 }
+/** Options for {@link awsProvider}. */
 interface AwsProviderOptions {
+    /** Secrets Manager ids. */
     secrets?: string[];
+    /** SSM names or path prefixes (trailing `/` optional). */
     params?: string[];
+    /** Reserved: region override (currently from env `AWS_REGION`). */
     region?: string;
+    /** Reserved: VersionId / stage pin. */
     versionId?: string;
+    /** Applies to the whole `load()`. Default 5000. */
     timeoutMs?: number;
+    /** Injected Secrets Manager client (or test fake); missing throws `E_NO_SDK`. */
     secretsClient?: AwsSecretsClient;
+    /** Injected SSM client (or test fake); missing throws `E_NO_SDK`. */
     ssmClient?: AwsSsmClient;
+    /** Secrets Manager value cap in bytes. Default 64 KiB. */
     maxBytesSecret?: number;
+    /** SSM value cap in bytes. Default 8 KiB. */
     maxBytesParam?: number;
 }
+/**
+ * Merges Secrets Manager values (JSON objects merge, scalars key on the last id
+ * segment) with SSM parameters (longest-prefix strip, `/` to `__`, uppercased).
+ * Concurrent `load()` calls share one in-flight request.
+ */
 declare function awsProvider(opts: AwsProviderOptions): SecretProvider;
 
 export { type AwsProviderOptions, type AwsSecretsClient, type AwsSsmClient, awsProvider };

package/dist/vault/hashicorp.d.cts

@@ -1,19 +1,40 @@
-import { a as SecretProvider } from '../types-BswIPp7U.cjs';
-import { F as FetchFn } from '../shared-DBcV6jIy.cjs';
+import { a as SecretProvider } from '../types-B_Dc2L4T.cjs';
+import { F as FetchFn } from '../shared-CucO_XsG.cjs';
 import '@standard-schema/spec';
 
+/**
+ * HashiCorp Vault provider (KVv1 + KVv2): reads one secret path into a flat map.
+ * Token comes from `auth.token` or `VAULT_TOKEN`; KVv2 envelopes unwrap only
+ * when a `metadata` sibling is present. Fail-closed on 403.
+ *
+ * @module
+ */
+
+/** Options for {@link hashicorpProvider}. */
 interface HashicorpOptions {
+    /** Vault base URL, e.g. `https://vault:8200`. */
     url: string;
+    /** KV mount. Default `'secret'`. */
     mount?: string;
+    /** Secret path: `data/app/prod` (KVv2) or `app/prod` (KVv1). */
     path: string;
+    /** Explicit token. `''` means none (no `VAULT_TOKEN` fallback); unset reads `VAULT_TOKEN`. */
     auth?: {
         token?: string;
     };
+    /** Pinned KVv2 version (`?version=`). */
     version?: number | string;
+    /** Request timeout in ms. Default 5000. */
     timeoutMs?: number;
+    /** Injectable fetch for tests. */
     fetchFn?: FetchFn;
+    /** Response body cap in bytes. Default 1 MiB. */
     maxBytes?: number;
 }
+/**
+ * Reads one Vault path into a flat map. Concurrent `load()` calls share a
+ * single in-flight request; failures reset so the next call retries.
+ */
 declare function hashicorpProvider(opts: HashicorpOptions): SecretProvider;
 
 export { type HashicorpOptions, hashicorpProvider };

package/dist/vault/hashicorp.d.ts

@@ -1,19 +1,40 @@
-import { a as SecretProvider } from '../types-BswIPp7U.js';
-import { F as FetchFn } from '../shared-DBcV6jIy.js';
+import { a as SecretProvider } from '../types-B_Dc2L4T.js';
+import { F as FetchFn } from '../shared-CucO_XsG.js';
 import '@standard-schema/spec';
 
+/**
+ * HashiCorp Vault provider (KVv1 + KVv2): reads one secret path into a flat map.
+ * Token comes from `auth.token` or `VAULT_TOKEN`; KVv2 envelopes unwrap only
+ * when a `metadata` sibling is present. Fail-closed on 403.
+ *
+ * @module
+ */
+
+/** Options for {@link hashicorpProvider}. */
 interface HashicorpOptions {
+    /** Vault base URL, e.g. `https://vault:8200`. */
     url: string;
+    /** KV mount. Default `'secret'`. */
     mount?: string;
+    /** Secret path: `data/app/prod` (KVv2) or `app/prod` (KVv1). */
     path: string;
+    /** Explicit token. `''` means none (no `VAULT_TOKEN` fallback); unset reads `VAULT_TOKEN`. */
     auth?: {
         token?: string;
     };
+    /** Pinned KVv2 version (`?version=`). */
     version?: number | string;
+    /** Request timeout in ms. Default 5000. */
     timeoutMs?: number;
+    /** Injectable fetch for tests. */
     fetchFn?: FetchFn;
+    /** Response body cap in bytes. Default 1 MiB. */
     maxBytes?: number;
 }
+/**
+ * Reads one Vault path into a flat map. Concurrent `load()` calls share a
+ * single in-flight request; failures reset so the next call retries.
+ */
 declare function hashicorpProvider(opts: HashicorpOptions): SecretProvider;
 
 export { type HashicorpOptions, hashicorpProvider };