typed-settings 0.1.0 → 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/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,22 @@
 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
+ */
+
+/**
+ * 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,22 @@
 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
+ */
+
+/**
+ * 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/{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.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/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/{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.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,9 +1,22 @@
 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-B_Dc2L4T.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';
+ *
+ * @module
+ */
+
+/** 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,22 @@
 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-B_Dc2L4T.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';
+ *
+ * @module
+ */
+
+/** 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.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,10 +1,23 @@
 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-B_Dc2L4T.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 }`.
+ *
+ * @module
+ */
+
+/**
+ * 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,23 @@
 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-B_Dc2L4T.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 }`.
+ *
+ * @module
+ */
+
+/**
+ * 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.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") {