typed-settings 0.1.0 → 0.1.1

package/dist/adapters/joi.d.cts

@@ -4,7 +4,16 @@ type AnySchema = {
     validateSync?: (v: unknown, o?: unknown) => unknown;
     validate?: (...a: never[]) => unknown;
 };
+/**
+ * Adapts a Yup schema via `validateSync` (`stripUnknown`, all errors).
+ * `inner[]` failures map to issues; anything else becomes a root issue.
+ */
 declare function yupAdapter(schema: any): StandardSchemaV1;
+/**
+ * Adapts a Joi schema (`validate` with convert + stripUnknown). `details[]`
+ * map to issues; a throwing `validate()` or empty details still yields a
+ * non-empty issues array, as Standard Schema requires.
+ */
 declare function joiAdapter(schema: AnySchema & {
     validate?: (v: unknown, o?: unknown) => {
         error?: {
@@ -17,6 +26,10 @@ declare function joiAdapter(schema: AnySchema & {
         value: unknown;
     };
 }): StandardSchemaV1;
+/**
+ * Adapts a Superstruct struct via `create()`. `failures()` map to issues;
+ * anything else falls back to the thrown message.
+ */
 declare function superstructAdapter(schema: AnySchema & {
     create?: (v: unknown) => unknown;
 }): StandardSchemaV1;

package/dist/adapters/joi.d.ts

@@ -4,7 +4,16 @@ type AnySchema = {
     validateSync?: (v: unknown, o?: unknown) => unknown;
     validate?: (...a: never[]) => unknown;
 };
+/**
+ * Adapts a Yup schema via `validateSync` (`stripUnknown`, all errors).
+ * `inner[]` failures map to issues; anything else becomes a root issue.
+ */
 declare function yupAdapter(schema: any): StandardSchemaV1;
+/**
+ * Adapts a Joi schema (`validate` with convert + stripUnknown). `details[]`
+ * map to issues; a throwing `validate()` or empty details still yields a
+ * non-empty issues array, as Standard Schema requires.
+ */
 declare function joiAdapter(schema: AnySchema & {
     validate?: (v: unknown, o?: unknown) => {
         error?: {
@@ -17,6 +26,10 @@ declare function joiAdapter(schema: AnySchema & {
         value: unknown;
     };
 }): StandardSchemaV1;
+/**
+ * Adapts a Superstruct struct via `create()`. `failures()` map to issues;
+ * anything else falls back to the thrown message.
+ */
 declare function superstructAdapter(schema: AnySchema & {
     create?: (v: unknown) => unknown;
 }): StandardSchemaV1;

package/dist/adapters/zod.d.cts

@@ -1,6 +1,20 @@
 import { StandardSchemaV1 } from '@standard-schema/spec';
 
+/**
+ * Zod helpers: `withPrefix` scopes any Standard Schema under an env prefix,
+ * `coerceEnv` is the identity hook for composed pipelines.
+ */
+
+/**
+ * Scopes a schema under `prefix`: matching keys strip case-insensitively before
+ * validation, prefixed keys win collisions, non-objects pass through untouched.
+ * An empty prefix returns the schema unchanged.
+ */
 declare function withPrefix<S extends StandardSchemaV1>(schema: S, prefix: string): S;
+/**
+ * Identity hook for composed pipelines. Documents "this value already went
+ * through env coercion"; the real logic lives in `coerce.ts`.
+ */
 declare function coerceEnv(value: unknown): unknown;
 
 export { coerceEnv, withPrefix };

package/dist/adapters/zod.d.ts

@@ -1,6 +1,20 @@
 import { StandardSchemaV1 } from '@standard-schema/spec';
 
+/**
+ * Zod helpers: `withPrefix` scopes any Standard Schema under an env prefix,
+ * `coerceEnv` is the identity hook for composed pipelines.
+ */
+
+/**
+ * Scopes a schema under `prefix`: matching keys strip case-insensitively before
+ * validation, prefixed keys win collisions, non-objects pass through untouched.
+ * An empty prefix returns the schema unchanged.
+ */
 declare function withPrefix<S extends StandardSchemaV1>(schema: S, prefix: string): S;
+/**
+ * Identity hook for composed pipelines. Documents "this value already went
+ * through env coercion"; the real logic lives in `coerce.ts`.
+ */
 declare function coerceEnv(value: unknown): unknown;
 
 export { coerceEnv, withPrefix };

package/dist/cli/main.d.cts

@@ -1,4 +1,8 @@
 #!/usr/bin/env node
+/**
+ * CLI dispatcher (`check|init|gen|watch`). Returns the process exit code
+ * instead of exiting, so it's testable: 0 ok, 1 invalid, 2 usage/load error.
+ */
 declare function main(argv?: string[]): Promise<number>;
 
 export { main };

package/dist/cli/main.d.ts

@@ -1,4 +1,8 @@
 #!/usr/bin/env node
+/**
+ * CLI dispatcher (`check|init|gen|watch`). Returns the process exit code
+ * instead of exiting, so it's testable: 0 ok, 1 invalid, 2 usage/load error.
+ */
 declare function main(argv?: string[]): Promise<number>;
 
 export { main };

package/dist/{errors-IU9n4f3t.d.cts → errors-itGaU4Q8.d.cts}

@@ -1,8 +1,13 @@
+/** One validation failure: the key path, the winning source, and what went wrong. */
 interface ConfigIssue {
     path: string;
     from: string;
     message: string;
 }
+/**
+ * Every settings failure. Carries machine-readable `issues` plus a `code`
+ * (`E_INVALID_CONFIG` by default, e.g. `E_UNKNOWN_KEY`, `E_TIMEOUT`).
+ */
 declare class ConfigError extends Error {
     code: string;
     issues: ConfigIssue[];

package/dist/{errors-IU9n4f3t.d.ts → errors-itGaU4Q8.d.ts}

@@ -1,8 +1,13 @@
+/** One validation failure: the key path, the winning source, and what went wrong. */
 interface ConfigIssue {
     path: string;
     from: string;
     message: string;
 }
+/**
+ * Every settings failure. Carries machine-readable `issues` plus a `code`
+ * (`E_INVALID_CONFIG` by default, e.g. `E_UNKNOWN_KEY`, `E_TIMEOUT`).
+ */
 declare class ConfigError extends Error {
     code: string;
     issues: ConfigIssue[];

package/dist/formats/env.d.cts

@@ -1,3 +1,8 @@
+/**
+ * Parses dotenv text into a flat map. Strips one BOM, joins multiline
+ * double-quoted values, lets the last duplicate win. Throws `ParseError` on
+ * backticks, unterminated quotes, bare keys, and empty keys.
+ */
 declare function parseEnvText(text: string): Record<string, string>;
 
 export { parseEnvText };

package/dist/formats/env.d.ts

@@ -1,3 +1,8 @@
+/**
+ * Parses dotenv text into a flat map. Strips one BOM, joins multiline
+ * double-quoted values, lets the last duplicate win. Throws `ParseError` on
+ * backticks, unterminated quotes, bare keys, and empty keys.
+ */
 declare function parseEnvText(text: string): Record<string, string>;
 
 export { parseEnvText };

package/dist/formats/json.d.cts

@@ -1,3 +1,7 @@
+/**
+ * Strict JSON parse (BOM-tolerant, blank reads as `{}`). Failures throw
+ * `ParseError` naming the source for attribution.
+ */
 declare function parseJsonText(text: string, from?: string): unknown;
 
 export { parseJsonText };

package/dist/formats/json.d.ts

@@ -1,3 +1,7 @@
+/**
+ * Strict JSON parse (BOM-tolerant, blank reads as `{}`). Failures throw
+ * `ParseError` naming the source for attribution.
+ */
 declare function parseJsonText(text: string, from?: string): unknown;
 
 export { parseJsonText };

package/dist/formats/toml.d.cts

@@ -1,3 +1,7 @@
+/**
+ * TOML parse via smol-toml (duplicate keys rejected). Blank reads as `{}`;
+ * failures throw `ParseError` naming the source.
+ */
 declare function parseTomlText(text: string, from?: string): unknown;
 
 export { parseTomlText };

package/dist/formats/toml.d.ts

@@ -1,3 +1,7 @@
+/**
+ * TOML parse via smol-toml (duplicate keys rejected). Blank reads as `{}`;
+ * failures throw `ParseError` naming the source.
+ */
 declare function parseTomlText(text: string, from?: string): unknown;
 
 export { parseTomlText };

package/dist/formats/yaml.d.cts

@@ -1,3 +1,8 @@
+/**
+ * Single-doc YAML parse (1.2, duplicate keys rejected). A trailing lone `---`
+ * still parses; multi-doc payloads, bad indentation, and unresolvable aliases
+ * throw `ParseError` naming the source. Explicit `null` reads as `{}`.
+ */
 declare function parseYamlText(text: string, from?: string): unknown;
 
 export { parseYamlText };

package/dist/formats/yaml.d.ts

@@ -1,3 +1,8 @@
+/**
+ * Single-doc YAML parse (1.2, duplicate keys rejected). A trailing lone `---`
+ * still parses; multi-doc payloads, bad indentation, and unresolvable aliases
+ * throw `ParseError` naming the source. Explicit `null` reads as `{}`.
+ */
 declare function parseYamlText(text: string, from?: string): unknown;
 
 export { parseYamlText };

package/dist/framework/next.d.cts

@@ -1,9 +1,20 @@
 export { StandardSchemaV1 } from '@standard-schema/spec';
 export { pickPublic, settings, settingsAsync } from '../index.cjs';
-export { S as SettingsOptions } from '../types-BswIPp7U.cjs';
-export { C as ConfigError } from '../errors-IU9n4f3t.cjs';
+export { S as SettingsOptions } from '../types-CClP1lxq.cjs';
+export { C as ConfigError } from '../errors-itGaU4Q8.cjs';
 
-/** Explicit public subset — no spread, keys enumerated so secrets can't leak via `...cfg`. */
+/**
+ * Next.js App Router binding (Edge-safe: no `fs`, no static `server-only` import).
+ * Load the full config on the server, hand the client only an explicit subset.
+ *
+ * IMPORTANT: add `import 'server-only'` at the top of YOUR server settings file
+ * (not inside this library — the `server-only` package throws when evaluated
+ * outside a React Server Component, which would break plain Node/vitest usage).
+ *   // settings.ts (server)
+ *   import 'server-only';
+ */
+
+/** Explicit public subset - no spread, keys enumerated so secrets can't leak via `...cfg`. */
 declare function publicSettings<T extends object, K extends keyof T>(cfg: T, keys: readonly K[]): Pick<T, K>;
 
 export { publicSettings };

package/dist/framework/next.d.ts

@@ -1,9 +1,20 @@
 export { StandardSchemaV1 } from '@standard-schema/spec';
 export { pickPublic, settings, settingsAsync } from '../index.js';
-export { S as SettingsOptions } from '../types-BswIPp7U.js';
-export { C as ConfigError } from '../errors-IU9n4f3t.js';
+export { S as SettingsOptions } from '../types-CClP1lxq.js';
+export { C as ConfigError } from '../errors-itGaU4Q8.js';
 
-/** Explicit public subset — no spread, keys enumerated so secrets can't leak via `...cfg`. */
+/**
+ * Next.js App Router binding (Edge-safe: no `fs`, no static `server-only` import).
+ * Load the full config on the server, hand the client only an explicit subset.
+ *
+ * IMPORTANT: add `import 'server-only'` at the top of YOUR server settings file
+ * (not inside this library — the `server-only` package throws when evaluated
+ * outside a React Server Component, which would break plain Node/vitest usage).
+ *   // settings.ts (server)
+ *   import 'server-only';
+ */
+
+/** Explicit public subset - no spread, keys enumerated so secrets can't leak via `...cfg`. */
 declare function publicSettings<T extends object, K extends keyof T>(cfg: T, keys: readonly K[]): Pick<T, K>;
 
 export { publicSettings };

package/dist/framework/vite.d.cts

@@ -1,10 +1,21 @@
 import { StandardSchemaV1 } from '@standard-schema/spec';
 export { StandardSchemaV1 } from '@standard-schema/spec';
 export { pickPublic, settings, settingsAsync } from '../index.cjs';
-import { S as SettingsOptions, F as Flat } from '../types-BswIPp7U.cjs';
-export { C as ConfigError } from '../errors-IU9n4f3t.cjs';
+import { S as SettingsOptions, F as Flat } from '../types-CClP1lxq.cjs';
+export { C as ConfigError } from '../errors-itGaU4Q8.cjs';
 
-/** Validate `import.meta.env` (passed explicitly by the caller) against a schema. */
+/**
+ * Vite binding (Edge-safe, no `fs`). Validates `import.meta.env` against a schema.
+ *
+ * Rules: never spread `import.meta.env` (it drags server secrets into the
+ * client bundle). Pass it as a map; file preloading belongs in `vite.config.ts`
+ * via `loadEnvFiles()` passed as `{ text }`.
+ */
+
+/**
+ * Validates `import.meta.env` (passed explicitly by the caller) against a schema.
+ * Sources and ambient env are fixed: the map is the only input.
+ */
 declare function viteSettings<S extends StandardSchemaV1>(opts: Omit<SettingsOptions<S>, 'sources' | 'env'>, metaEnv: Flat): StandardSchemaV1.InferOutput<S>;
 
 export { Flat, SettingsOptions, viteSettings };

package/dist/framework/vite.d.ts

@@ -1,10 +1,21 @@
 import { StandardSchemaV1 } from '@standard-schema/spec';
 export { StandardSchemaV1 } from '@standard-schema/spec';
 export { pickPublic, settings, settingsAsync } from '../index.js';
-import { S as SettingsOptions, F as Flat } from '../types-BswIPp7U.js';
-export { C as ConfigError } from '../errors-IU9n4f3t.js';
+import { S as SettingsOptions, F as Flat } from '../types-CClP1lxq.js';
+export { C as ConfigError } from '../errors-itGaU4Q8.js';
 
-/** Validate `import.meta.env` (passed explicitly by the caller) against a schema. */
+/**
+ * Vite binding (Edge-safe, no `fs`). Validates `import.meta.env` against a schema.
+ *
+ * Rules: never spread `import.meta.env` (it drags server secrets into the
+ * client bundle). Pass it as a map; file preloading belongs in `vite.config.ts`
+ * via `loadEnvFiles()` passed as `{ text }`.
+ */
+
+/**
+ * Validates `import.meta.env` (passed explicitly by the caller) against a schema.
+ * Sources and ambient env are fixed: the map is the only input.
+ */
 declare function viteSettings<S extends StandardSchemaV1>(opts: Omit<SettingsOptions<S>, 'sources' | 'env'>, metaEnv: Flat): StandardSchemaV1.InferOutput<S>;
 
 export { Flat, SettingsOptions, viteSettings };

package/dist/index.d.cts

@@ -1,12 +1,46 @@
 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-CClP1lxq.cjs';
+export { A as ArrayStrategy, a as SecretProvider, b as SourceInput, U as UnknownKeys } from './types-CClP1lxq.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.
+ */
+
+/**
+ * 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. Throws `ConfigError` on invalid input (issues
+ * carry `path` + winning-source `from`, secrets redacted) and `USE_ASYNC` when a
+ * provider or the schema itself is async — then use `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,46 @@
 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-CClP1lxq.js';
+export { A as ArrayStrategy, a as SecretProvider, b as SourceInput, U as UnknownKeys } from './types-CClP1lxq.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.
+ */
+
+/**
+ * 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. Throws `ConfigError` on invalid input (issues
+ * carry `path` + winning-source `from`, secrets redacted) and `USE_ASYNC` when a
+ * provider or the schema itself is async — then use `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/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-CClP1lxq.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-CClP1lxq.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/{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-CClP1lxq.d.cts

@@ -0,0 +1,67 @@
+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; 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-CClP1lxq.d.ts

@@ -0,0 +1,67 @@
+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; 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,49 @@
-import { a as SecretProvider } from '../types-BswIPp7U.cjs';
+import { a as SecretProvider } from '../types-CClP1lxq.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.
+ */
+
+/** 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,49 @@
-import { a as SecretProvider } from '../types-BswIPp7U.js';
+import { a as SecretProvider } from '../types-CClP1lxq.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.
+ */
+
+/** 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,38 @@
-import { a as SecretProvider } from '../types-BswIPp7U.cjs';
-import { F as FetchFn } from '../shared-DBcV6jIy.cjs';
+import { a as SecretProvider } from '../types-CClP1lxq.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.
+ */
+
+/** 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,38 @@
-import { a as SecretProvider } from '../types-BswIPp7U.js';
-import { F as FetchFn } from '../shared-DBcV6jIy.js';
+import { a as SecretProvider } from '../types-CClP1lxq.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.
+ */
+
+/** 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/http.d.cts

@@ -1,15 +1,31 @@
-import { F as Flat, a as SecretProvider } from '../types-BswIPp7U.cjs';
-import { F as FetchFn } from '../shared-DBcV6jIy.cjs';
+import { F as Flat, a as SecretProvider } from '../types-CClP1lxq.cjs';
+import { F as FetchFn } from '../shared-CucO_XsG.cjs';
 import '@standard-schema/spec';
 
+/**
+ * Generic HTTP secret provider: GETs a JSON endpoint and reads a dot-path
+ * (`jsonPath`, default `'data'`) into a flat map. Auth rides in `headers`.
+ */
+
+/** Options for {@link httpProvider}. */
 interface HttpProviderOptions {
+    /** Endpoint URL. */
     url: string;
+    /** Extra headers. Feed auth from env-injected values, never CLI args. */
     headers?: Flat;
+    /** Dot path into the JSON body. Default `'data'`; `''` reads the whole body. */
     jsonPath?: 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;
 }
+/**
+ * GETs a JSON endpoint and reads `jsonPath` into a flat map. Concurrent loads
+ * share one in-flight request; failures reset so the next call retries.
+ */
 declare function httpProvider(opts: HttpProviderOptions): SecretProvider;
 
 export { type HttpProviderOptions, httpProvider };

package/dist/vault/http.d.ts

@@ -1,15 +1,31 @@
-import { F as Flat, a as SecretProvider } from '../types-BswIPp7U.js';
-import { F as FetchFn } from '../shared-DBcV6jIy.js';
+import { F as Flat, a as SecretProvider } from '../types-CClP1lxq.js';
+import { F as FetchFn } from '../shared-CucO_XsG.js';
 import '@standard-schema/spec';
 
+/**
+ * Generic HTTP secret provider: GETs a JSON endpoint and reads a dot-path
+ * (`jsonPath`, default `'data'`) into a flat map. Auth rides in `headers`.
+ */
+
+/** Options for {@link httpProvider}. */
 interface HttpProviderOptions {
+    /** Endpoint URL. */
     url: string;
+    /** Extra headers. Feed auth from env-injected values, never CLI args. */
     headers?: Flat;
+    /** Dot path into the JSON body. Default `'data'`; `''` reads the whole body. */
     jsonPath?: 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;
 }
+/**
+ * GETs a JSON endpoint and reads `jsonPath` into a flat map. Concurrent loads
+ * share one in-flight request; failures reset so the next call retries.
+ */
 declare function httpProvider(opts: HttpProviderOptions): SecretProvider;
 
 export { type HttpProviderOptions, httpProvider };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "typed-settings",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "One-call typed config for TS: env + .env + yaml/toml/json + secrets-dir + vault -> frozen object. Standard Schema + legacy bridges.",
   "type": "module",
   "main": "./dist/index.cjs",

package/dist/types-BswIPp7U.d.cts

@@ -1,41 +0,0 @@
-import { StandardSchemaV1 } from '@standard-schema/spec';
-
-type Flat = Record<string, string | undefined>;
-interface SecretProvider {
-    name: string;
-    load(): Promise<Flat> | Flat;
-}
-type SourceInput = 'env' | '.env' | '.env.local' | {
-    text: string;
-} | {
-    file: string;
-} | {
-    dir: string;
-} | {
-    map: Flat;
-    prefix?: string;
-} | {
-    provider: SecretProvider;
-    prefix?: string;
-} | SecretProvider | Flat | string;
-type ArrayStrategy = 'replace' | 'concat' | 'mergeIndex';
-type UnknownKeys = 'strip' | 'preserve' | 'reject';
-interface SettingsOptions<S extends StandardSchemaV1 = StandardSchemaV1> {
-    schema: S;
-    sources?: SourceInput[];
-    prefix?: string;
-    separator?: '__';
-    coerce?: boolean;
-    expand?: boolean;
-    expandSecrets?: boolean;
-    arrayStrategy?: ArrayStrategy;
-    unknownKeys?: UnknownKeys;
-    freeze?: boolean;
-    timeoutMs?: number;
-    maxBytes?: number;
-    envMap?: Record<string, string>;
-    allowUnresolved?: boolean;
-    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-BswIPp7U.d.ts

@@ -1,41 +0,0 @@
-import { StandardSchemaV1 } from '@standard-schema/spec';
-
-type Flat = Record<string, string | undefined>;
-interface SecretProvider {
-    name: string;
-    load(): Promise<Flat> | Flat;
-}
-type SourceInput = 'env' | '.env' | '.env.local' | {
-    text: string;
-} | {
-    file: string;
-} | {
-    dir: string;
-} | {
-    map: Flat;
-    prefix?: string;
-} | {
-    provider: SecretProvider;
-    prefix?: string;
-} | SecretProvider | Flat | string;
-type ArrayStrategy = 'replace' | 'concat' | 'mergeIndex';
-type UnknownKeys = 'strip' | 'preserve' | 'reject';
-interface SettingsOptions<S extends StandardSchemaV1 = StandardSchemaV1> {
-    schema: S;
-    sources?: SourceInput[];
-    prefix?: string;
-    separator?: '__';
-    coerce?: boolean;
-    expand?: boolean;
-    expandSecrets?: boolean;
-    arrayStrategy?: ArrayStrategy;
-    unknownKeys?: UnknownKeys;
-    freeze?: boolean;
-    timeoutMs?: number;
-    maxBytes?: number;
-    envMap?: Record<string, string>;
-    allowUnresolved?: boolean;
-    env?: Flat;
-}
-
-export type { ArrayStrategy as A, Flat as F, SettingsOptions as S, UnknownKeys as U, SecretProvider as a, SourceInput as b };