typed-settings 0.1.1 → 0.1.4

package/README.md

@@ -185,7 +185,7 @@ Provider details: [docs/vault.md](docs/vault.md).
 | `schema` | Standard Schema | required | zod / valibot / arktype object, or a legacy bridge. An async `validate()` forces `settingsAsync()` |
 | `sources` | array | `['.env', 'env']` | layers in priority order, later wins |
 | `prefix` | `string` | - | global prefix strip, case-insensitive, once |
-| `envMap` | object | - | keys used literally: no prefix strip, no `__` splitting |
+| `envMap` | object | `{}` | maps an env key to the literal key it should occupy (used as-is: no strip/split) |
 | `env` | object | `process.env` | the env snapshot. Pass `{}` to isolate, or a map in tests/on Edge |
 | `expand` | `boolean` | `true` | `$VAR` expansion after merging. `false` leaves literals alone |
 | `allowUnresolved` | `boolean` | `false` | `true` keeps `${MISSING}` as-is instead of throwing |
@@ -279,7 +279,9 @@ Things people actually hit, in rough order of frequency:
 
 - **`USE_ASYNC: provider is async`.** One of your providers (or the schema itself) is async. Switch to `settingsAsync()`.
 - **`E_UNRESOLVED: FOO missing`.** A `$FOO` reference points at nothing. Set the variable, give it a default (`${FOO:-fallback}`), or pass `allowUnresolved: true` to leave it literal.
-- **Schema rejects everything.** Keys are lowercased during load, so schemas need lowercase keys. `port`, not `PORT`.
+- **Schema rejects everything.** Keys are lowercased during load, so schemas need lowercase keys (`port`, not `PORT`). The failure mode is sneaky: `z.object({ PORT: z.coerce.number() })` never matches the lowercased input, so it validates `undefined`, and `z.coerce.number()` turns that into `NaN` — you get the confusing "expected number, received NaN".
+- **Everything is silently empty or wrong.** Most often a global `prefix` ate your keys: matching applies to every source, so `prefix: 'APP_'` drops a YAML key like `port:` and a secrets-dir entry like `API_TOKEN` without a word. Scope it per source, or skip it and bridge env names via `envMap`.
+- **Deno (JSR) refuses a fresh release.** Deno's minimum-dependency-age policy blocks versions published within ~24h. For local dev, run with `--minimum-dependency-age=0`.
 - **`E_NO_FS` under ESM.** Core can't reach `node:fs` on its own. Import `typed-settings/node` once, or stick to `{ text }` / `{ map }` sources.
 - **`E_UNKNOWN_KEY`.** Extra keys with `unknownKeys: 'reject'` (the CLI calls this `--strict`). Either drop the keys or switch to `strip` / `preserve`.
 - **`SCHEMA_LOAD_ERROR`.** The CLI can't find your schema. Export it under the name `schema`, or point at it with `--schema-export NAME`.

package/dist/adapters/zod.d.cts

@@ -3,6 +3,8 @@ 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.
+ *
+ * @module
  */
 
 /**

package/dist/adapters/zod.d.ts

@@ -3,6 +3,8 @@ 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.
+ *
+ * @module
  */
 
 /**

package/dist/{chunk-VTIYOSG2.js → chunk-DEP5SD4J.js}

@@ -1,4 +1,4 @@
-import { settings } from './chunk-RCO6K3WQ.js';
+import { settings } from './chunk-YVJEZPPZ.js';
 import { parseEnvText } from './chunk-F6DX3HXZ.js';
 import { readFileSync, readdirSync, statSync, watch } from 'fs';
 import { join, dirname, basename, resolve } from 'path';

package/dist/{chunk-RCO6K3WQ.js → chunk-YVJEZPPZ.js}

@@ -253,12 +253,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];
@@ -290,7 +290,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(
@@ -791,7 +790,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/cli/main.cjs

@@ -485,12 +485,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];
@@ -522,7 +522,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(
@@ -1044,7 +1043,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/cli/main.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
-import { watchSettings } from '../chunk-VTIYOSG2.js';
-import { settings } from '../chunk-RCO6K3WQ.js';
+import { watchSettings } from '../chunk-DEP5SD4J.js';
+import { settings } from '../chunk-YVJEZPPZ.js';
 import '../chunk-33M5GIKQ.js';
 import '../chunk-OVFMKC2O.js';
 import '../chunk-UFUHHR2J.js';

package/dist/framework/next.cjs

@@ -440,12 +440,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];
@@ -477,7 +477,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(
@@ -949,7 +948,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/framework/next.d.cts

@@ -1,6 +1,6 @@
 export { StandardSchemaV1 } from '@standard-schema/spec';
 export { pickPublic, settings, settingsAsync } from '../index.cjs';
-export { S as SettingsOptions } from '../types-CClP1lxq.cjs';
+export { S as SettingsOptions } from '../types-B_Dc2L4T.cjs';
 export { C as ConfigError } from '../errors-itGaU4Q8.cjs';
 
 /**
@@ -12,6 +12,8 @@ export { C as ConfigError } from '../errors-itGaU4Q8.cjs';
  * outside a React Server Component, which would break plain Node/vitest usage).
  *   // settings.ts (server)
  *   import 'server-only';
+ *
+ * @module
  */
 
 /** Explicit public subset - no spread, keys enumerated so secrets can't leak via `...cfg`. */

package/dist/framework/next.d.ts

@@ -1,6 +1,6 @@
 export { StandardSchemaV1 } from '@standard-schema/spec';
 export { pickPublic, settings, settingsAsync } from '../index.js';
-export { S as SettingsOptions } from '../types-CClP1lxq.js';
+export { S as SettingsOptions } from '../types-B_Dc2L4T.js';
 export { C as ConfigError } from '../errors-itGaU4Q8.js';
 
 /**
@@ -12,6 +12,8 @@ export { C as ConfigError } from '../errors-itGaU4Q8.js';
  * outside a React Server Component, which would break plain Node/vitest usage).
  *   // settings.ts (server)
  *   import 'server-only';
+ *
+ * @module
  */
 
 /** Explicit public subset - no spread, keys enumerated so secrets can't leak via `...cfg`. */

package/dist/framework/next.js

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

package/dist/framework/vite.cjs

@@ -440,12 +440,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];
@@ -477,7 +477,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(
@@ -949,7 +948,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/framework/vite.d.cts

@@ -1,7 +1,7 @@
 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-CClP1lxq.cjs';
+import { S as SettingsOptions, F as Flat } from '../types-B_Dc2L4T.cjs';
 export { C as ConfigError } from '../errors-itGaU4Q8.cjs';
 
 /**
@@ -10,6 +10,8 @@ export { C as ConfigError } from '../errors-itGaU4Q8.cjs';
  * 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 }`.
+ *
+ * @module
  */
 
 /**

package/dist/framework/vite.d.ts

@@ -1,7 +1,7 @@
 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-CClP1lxq.js';
+import { S as SettingsOptions, F as Flat } from '../types-B_Dc2L4T.js';
 export { C as ConfigError } from '../errors-itGaU4Q8.js';
 
 /**
@@ -10,6 +10,8 @@ export { C as ConfigError } from '../errors-itGaU4Q8.js';
  * 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 }`.
+ *
+ * @module
  */
 
 /**

package/dist/framework/vite.js

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

package/dist/index.cjs

@@ -440,12 +440,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];
@@ -477,7 +477,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(
@@ -978,7 +977,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/index.d.cts

@@ -1,6 +1,6 @@
 import { StandardSchemaV1 } from '@standard-schema/spec';
-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';
+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';
 
 /**
@@ -10,6 +10,8 @@ export { C as ConfigError } from './errors-itGaU4Q8.cjs';
  * 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
  */
 
 /**
@@ -31,9 +33,12 @@ declare function pickPublic<T extends object>(cfg: T, keys: (keyof T)[]): Partia
 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()`.
+ * 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>;
 /**

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { StandardSchemaV1 } from '@standard-schema/spec';
-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';
+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';
 
 /**
@@ -10,6 +10,8 @@ export { C as ConfigError } from './errors-itGaU4Q8.js';
  * 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
  */
 
 /**
@@ -31,9 +33,12 @@ declare function pickPublic<T extends object>(cfg: T, keys: (keyof T)[]): Partia
 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()`.
+ * 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>;
 /**

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,4 +1,4 @@
-import { F as Flat, S as SettingsOptions } from './types-CClP1lxq.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-itGaU4Q8.cjs';
 

package/dist/node.d.ts

@@ -1,4 +1,4 @@
-import { F as Flat, S as SettingsOptions } from './types-CClP1lxq.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-itGaU4Q8.js';
 

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/{types-CClP1lxq.d.cts → types-B_Dc2L4T.d.cts}

@@ -10,8 +10,10 @@ interface SecretProvider {
 }
 /**
  * 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.
+ * 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;

package/dist/{types-CClP1lxq.d.ts → types-B_Dc2L4T.d.ts}

@@ -10,8 +10,10 @@ interface SecretProvider {
 }
 /**
  * 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.
+ * 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;

package/dist/vault/aws.d.cts

@@ -1,10 +1,12 @@
-import { a as SecretProvider } from '../types-CClP1lxq.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). */

package/dist/vault/aws.d.ts

@@ -1,10 +1,12 @@
-import { a as SecretProvider } from '../types-CClP1lxq.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). */

package/dist/vault/hashicorp.d.cts

@@ -1,4 +1,4 @@
-import { a as SecretProvider } from '../types-CClP1lxq.cjs';
+import { a as SecretProvider } from '../types-B_Dc2L4T.cjs';
 import { F as FetchFn } from '../shared-CucO_XsG.cjs';
 import '@standard-schema/spec';
 
@@ -6,6 +6,8 @@ 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}. */

package/dist/vault/hashicorp.d.ts

@@ -1,4 +1,4 @@
-import { a as SecretProvider } from '../types-CClP1lxq.js';
+import { a as SecretProvider } from '../types-B_Dc2L4T.js';
 import { F as FetchFn } from '../shared-CucO_XsG.js';
 import '@standard-schema/spec';
 
@@ -6,6 +6,8 @@ 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}. */

package/dist/vault/http.d.cts

@@ -1,10 +1,12 @@
-import { F as Flat, a as SecretProvider } from '../types-CClP1lxq.cjs';
+import { F as Flat, a as SecretProvider } from '../types-B_Dc2L4T.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`.
+ *
+ * @module
  */
 
 /** Options for {@link httpProvider}. */

package/dist/vault/http.d.ts

@@ -1,10 +1,12 @@
-import { F as Flat, a as SecretProvider } from '../types-CClP1lxq.js';
+import { F as Flat, a as SecretProvider } from '../types-B_Dc2L4T.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`.
+ *
+ * @module
  */
 
 /** Options for {@link httpProvider}. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "typed-settings",
-  "version": "0.1.1",
+  "version": "0.1.4",
   "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",
@@ -89,6 +89,14 @@
     "standard-schema"
   ],
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/prosubodh/typed-settings"
+  },
+  "homepage": "https://github.com/prosubodh/typed-settings#readme",
+  "bugs": {
+    "url": "https://github.com/prosubodh/typed-settings/issues"
+  },
   "engines": {
     "node": ">=20"
   },