konfeeg 0.0.0 → 0.0.2

package/README.md

@@ -2,7 +2,11 @@
 
 Validated, strongly-typed config for Node and the browser. Define a schema once; values are resolved, coerced, and validated at startup — missing or invalid values throw immediately.
 
-> **Note:** Throws at startup if any required value is missing or fails format validation — broken `.env` files surface immediately, not at runtime.
+> API is inspired by [convict](https://github.com/mozilla/node-convict/tree/master/packages/convict), but this package:
+>
+> - works in the browser (as well as node)
+> - supports environment-specific values without requiring use of global env vars
+> - supports `import.meta.env` (e.g. for Vite)
 
 ---
 
@@ -11,7 +15,7 @@ Validated, strongly-typed config for Node and the browser. Define a schema once;
 ```ts
 import { createEnvironmentConfig } from "konfeeg"
 
-// 1. Declare your environments (required vs optional)
+// 1. Declare the names of your environments
 type MyEnvs = {
   dev?: unknown // optional (?) = per-env value may be omitted
   staging: unknown // required = must supply a value
@@ -28,6 +32,26 @@ const config = createEnvironmentConfig<MyEnvs>()("staging", {
     staging: "https://staging-api.example.com",
     production: "https://api.example.com",
   },
+  logLevel: {
+    doc: "Minimum log level",
+    format: ["debug", "info", "warn", "error"] as const, // Must be one of these literals
+    processEnv: "LOG_LEVEL",
+    dev: "debug",
+    staging: "info",
+    production: "warn",
+  },
+  port: {
+    doc: "HTTP port to listen on",
+    format: Number, // Numeric strings (e.g. from env vars) are coerced
+    processEnv: "PORT",
+    value: 3000,
+  },
+  allowedOrigins: {
+    doc: "CORS allow-list",
+    format: Array, // Value must be an array
+    staging: ["https://staging.example.com"],
+    production: ["https://example.com", "https://admin.example.com"],
+  },
   mongo: {
     dbName: {
       doc: "Mongo database name",
@@ -35,34 +59,56 @@ const config = createEnvironmentConfig<MyEnvs>()("staging", {
       processEnv: "MONGO_DB_NAME",
       value: "my-app-db", // static fallback (lowest priority)
     },
-    password: {
-      doc: "Mongo database password",
-      format: String,
-      // runtime-only, no static fallback
-      importMetaEnv: "MONGO_PASSWORD", // uses import.meta.env instead of process.env (e.g. for Vite)
+    poolSize: {
+      doc: "Max connections in the Mongo pool",
+      format: Number,
+      optional: true, // missing value resolves to `default` instead of throwing
+      default: 10,
     },
   },
 })
 
 config.env // "staging"
 config.apiUrl // string (validated as URL)
+config.logLevel // "debug" | "info" | "warn" | "error"
+config.port // number
+config.allowedOrigins // any[]
 config.mongo.dbName // string
+config.mongo.poolSize // number
 ```
 
+> [!important]
+> The above example hardcodes the active environment (`"staging"`) for clarity, but you'll want that to be dynamic in a real app:
+>
+> ```ts
+> type WhichEnvsAreRequired = {
+>   local?: unknown // optional (?) = per-env value may be omitted
+>   nonprod: unknown // required = must supply a value
+>   prod: unknown
+> }
+>
+> // type AppEnvironment = keyof WhichEnvsAreRequired // "local" | "nonprod" | "prod"
+>
+> const appEnv = import.meta.env.VITE_APP_ENV as AppEnvironment
+> if (!appEnv) throw new Error("VITE_APP_ENV is required")
+>
+> const config = createEnvironmentConfig<WhichEnvsAreRequired>()(appEnv, { ... })
+> ```
+
 ---
 
 ## Schema fields
 
-| Field                        | Required | Description                                                            |
-| ---------------------------- | -------- | ---------------------------------------------------------------------- |
-| `doc`                        | required | Human-readable description                                             |
-| `format`                     | required | Validation format — see below                                          |
-| `value`                      | optional | Constant shared across all environments (lowest priority)              |
-| `processEnv`                 | optional | `process.env` key — runtime override (highest priority)                |
-| `importMetaEnv`              | optional | `import.meta.env` key — runtime override (highest priority)            |
-| `optional`                   | optional | When `true`, missing value resolves to `undefined` instead of throwing |
-| `default`                    | optional | Fallback when `optional: true` and no value is found                   |
-| env keys (`dev`, `staging`…) | optional | Per-environment value overrides                                        |
+| Field                             | Required | Description                                                                           |
+| --------------------------------- | -------- | ------------------------------------------------------------------------------------- |
+| `doc`                             | required | Human-readable description                                                            |
+| `format`                          | optional | Validation format — see below. If omitted, no validation is applied; the resolved type is inferred from `value`/per-env fields, or `any` if none are declared |
+| `value`                           | optional | Constant shared across all environments (lowest priority)                             |
+| `processEnv`                      | optional | `process.env` key — runtime override (highest priority)                               |
+| `importMetaEnv`                   | optional | `import.meta.env` key — runtime override (highest priority)                           |
+| `optional`                        | optional | When `true`, missing value will not throw. Resolves to `default` field or `undefined` |
+| `default`                         | optional | Fallback to replace `undefined` when `optional: true` and no value is found           |
+| env keys (e.g. `dev`, `staging`…) | optional | Per-environment value overrides. _(These are the env names that you pass in in)_      |
 
 ---
 
@@ -93,21 +139,6 @@ When multiple sources are declared on the same entry, the highest-priority sourc
 
 ---
 
-## Defining environments
-
-Declare a plain object type. Required properties mean every entry that supplies per-env values must include that env. Optional properties (`?`) may be omitted.
-
-```ts
-type MyEnvs = {
-  dev?: unknown // optional — per-env value may be omitted
-  integ?: unknown
-  staging: unknown // required — every entry must supply a value
-  production: unknown
-}
-```
-
----
-
 ## Fallbacks
 
 When an entry has no value for the active environment, resolution can fall back to another env's value. Chains are transitive. Only affects per-env resolution (priority 2) — runtime env vars still win.

package/dist/index.cjs

@@ -0,0 +1,195 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region src/format.ts
+function validateAndCoerce(value, format, fullKey, errors) {
+	switch (format) {
+		case String:
+			if (typeof value !== "string") errors.push(`${fullKey}: must be a string`);
+			break;
+		case Number:
+			value = Number(value);
+			if (isNaN(value)) errors.push(`${fullKey}: must be a number`);
+			break;
+		case Boolean:
+			if (typeof value !== "boolean" && value !== "true" && value !== "false" && value !== 1 && value !== 0) errors.push(`${fullKey}: must be a boolean`);
+			value = value === "true" ? true : value === "false" ? false : Boolean(value);
+			break;
+		case Array:
+			if (!Array.isArray(value)) errors.push(`${fullKey}: must be an array`);
+			break;
+		case "url":
+			try {
+				new URL(value);
+			} catch {
+				errors.push(`${fullKey}: must be a valid URL; found "${value}"`);
+			}
+			break;
+		default: if (format instanceof Array) {
+			if (!format.includes(value)) errors.push(`${fullKey}: must be one of: [${format.join(", ")}]`);
+		}
+	}
+	return value;
+}
+//#endregion
+//#region src/create-config.ts
+/**
+* Create a resolved, validated config for the given environment.
+*
+* Curried so the envs declaration is bound on the first call and the
+* schema is inferred (giving you autocomplete) on the second call.
+*
+* @typeParam E - The envs shape describing required/optional environments.
+*
+* @example
+* ```ts
+* type MyEnvs = {
+*   dev?: unknown
+*   staging: unknown
+*   production: unknown
+* }
+* const config = createEnvironmentConfig<MyEnvs>()('dev', {
+*   port: { doc: 'Port', format: Number, value: 3000 },
+* })
+* config.port // number
+* ```
+*
+* @example Fallback environments
+* ```ts
+* // When running in `dev`, any entry that does not declare a `dev` value
+* // falls back to the entry's `integ` value.
+* const config = createEnvironmentConfig<MyEnvs>()(
+*   'dev',
+*   {
+*     apiUrl: {
+*       doc: 'API URL',
+*       format: 'url',
+*       integ: 'https://integ.example.com',
+*       staging: 'https://staging.example.com',
+*       production: 'https://api.example.com',
+*     },
+*   },
+*   { fallbacks: { dev: 'integ' } },
+* )
+* ```
+*/
+function createEnvironmentConfig() {
+	return (env, inputConfig, options) => buildConfig(env, inputConfig, options);
+}
+function buildConfig(env, inputConfig, options) {
+	const errors = [];
+	const envChain = resolveFallbackChain(env, options?.fallbacks);
+	function processConfig(config, keyPrefix) {
+		const output = {};
+		for (const [key, entry] of Object.entries(config)) {
+			if (key === "env") throw new Error(`Config key "env" is reserved and cannot be used. It will already be present by default.`);
+			const fullKey = keyPrefix ? `${keyPrefix}.${key}` : key;
+			if (!("doc" in entry)) {
+				output[key] = processConfig(entry, fullKey);
+				continue;
+			}
+			const configEntry = entry;
+			let value = "value" in configEntry ? configEntry.value : void 0;
+			for (const candidateEnv of envChain) {
+				const envValue = configEntry[candidateEnv];
+				if (envValue !== void 0) {
+					value = envValue;
+					break;
+				}
+			}
+			if ("processEnv" in configEntry) {
+				const runtimeOverride = typeof process !== "undefined" && process.env ? process.env[configEntry.processEnv] : void 0;
+				if (runtimeOverride !== void 0) value = runtimeOverride;
+			} else if ("importMetaEnv" in configEntry) {
+				const runtimeOverride = {}.env ? {}.env[configEntry.importMetaEnv] : void 0;
+				if (runtimeOverride !== void 0) value = runtimeOverride;
+			}
+			const hasValueSource = value !== void 0 || "processEnv" in configEntry || "importMetaEnv" in configEntry || configEntry.optional;
+			if (value === void 0 && !hasValueSource) {
+				errors.push(`${fullKey}: No value source declared and "optional" is not set.`);
+				continue;
+			}
+			if (value === void 0) if (configEntry.optional) {
+				value = configEntry.default;
+				if (value === void 0) {
+					output[key] = void 0;
+					continue;
+				}
+			} else {
+				errors.push(`${fullKey}: Missing required config value in environment ${env}`);
+				continue;
+			}
+			value = validateAndCoerce(value, configEntry.format, fullKey, errors);
+			output[key] = value;
+		}
+		return output;
+	}
+	let outputConfig = processConfig(inputConfig, "");
+	if (errors.length > 0) {
+		console.error("Environment config validation failed", errors);
+		throw new Error(`Environment config validation failed:\n${errors.join("\n")}`);
+	}
+	outputConfig = {
+		env,
+		...outputConfig
+	};
+	return outputConfig;
+}
+/**
+* Build the ordered list of environments to consult for per-environment
+* value resolution. The active env is always first; each subsequent entry
+* is the fallback target declared for the previous env. Throws if the
+* chain is cyclic.
+*/
+function resolveFallbackChain(env, fallbacks) {
+	const chain = [env];
+	if (!fallbacks) return chain;
+	const seen = new Set([env]);
+	let current = env;
+	while (fallbacks[current] !== void 0) {
+		const next = fallbacks[current];
+		if (seen.has(next)) throw new Error(`Circular fallback chain detected: ${[...chain, next].join(" -> ")}`);
+		seen.add(next);
+		chain.push(next);
+		current = next;
+	}
+	return chain;
+}
+//#endregion
+//#region src/define-config.ts
+/**
+* Like {@link createEnvironmentConfig}, but binds the schema first and the
+* environment later. Useful when the active environment is not known at
+* schema-definition time.
+*
+* @typeParam E - The envs shape describing required/optional environments.
+*
+* @example
+* ```ts
+* type MyEnvs = {
+*   dev?: unknown
+*   staging: unknown
+*   production: unknown
+* }
+* const buildConfig = defineEnvironmentConfig<MyEnvs>()({
+*   port: { doc: 'Port', format: Number, value: 3000 },
+* })
+* const config = buildConfig('dev')
+* ```
+*
+* @example Fallback environments
+* ```ts
+* const buildConfig = defineEnvironmentConfig<MyEnvs>()(
+*   { apiUrl: { doc: 'API URL', format: 'url', staging: 'https://staging' } },
+*   { fallbacks: { dev: 'staging' } },
+* )
+* const config = buildConfig('dev') // apiUrl resolved from `staging`
+* ```
+*/
+function defineEnvironmentConfig() {
+	const create = createEnvironmentConfig();
+	return (inputConfig, options) => (env) => create(env, inputConfig, options);
+}
+//#endregion
+exports.createEnvironmentConfig = createEnvironmentConfig;
+exports.defineEnvironmentConfig = defineEnvironmentConfig;
+
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","names":[],"sources":["../src/format.ts","../src/create-config.ts","../src/define-config.ts"],"sourcesContent":["/* eslint-disable @typescript-eslint/no-explicit-any */\n\nexport function validateAndCoerce(\n  value: any,\n  format: any,\n  fullKey: string,\n  errors: string[],\n): any {\n  switch (format) {\n    case String:\n      if (typeof value !== \"string\") {\n        errors.push(`${fullKey}: must be a string`)\n      }\n      break\n    case Number:\n      value = Number(value)\n      if (isNaN(value))\n        errors.push(`${fullKey}: must be a number`)\n      break\n    case Boolean:\n      if (\n        typeof value !== \"boolean\" &&\n        value !== \"true\" &&\n        value !== \"false\" &&\n        value !== 1 &&\n        value !== 0\n      ) {\n        errors.push(`${fullKey}: must be a boolean`)\n      }\n      value =\n        value === \"true\" ? true : value === \"false\" ? false : Boolean(value)\n      break\n    case Array:\n      if (!Array.isArray(value)) {\n        errors.push(`${fullKey}: must be an array`)\n      }\n      break\n    case \"url\":\n      try {\n        new URL(value)\n      } catch {\n        errors.push(\n          `${fullKey}: must be a valid URL; found \"${value}\"`,\n        )\n      }\n      break\n    default:\n      if (format instanceof Array) {\n        if (!format.includes(value)) {\n          errors.push(\n            `${fullKey}: must be one of: [${format.join(\", \")}]`,\n          )\n        }\n      }\n  }\n\n  return value\n}\n","/* eslint-disable @typescript-eslint/no-explicit-any */\n\nimport { validateAndCoerce } from \"./format.js\"\nimport type {\n  ConfigGroup,\n  ResolveConfigGroup,\n  ValidateSchema,\n} from \"./types.js\"\nimport type {\n  CreateConfigOptions,\n  EnvName,\n  EnvsShape,\n  Fallbacks,\n} from \"./util-types.js\"\n\n/**\n * Create a resolved, validated config for the given environment.\n *\n * Curried so the envs declaration is bound on the first call and the\n * schema is inferred (giving you autocomplete) on the second call.\n *\n * @typeParam E - The envs shape describing required/optional environments.\n *\n * @example\n * ```ts\n * type MyEnvs = {\n *   dev?: unknown\n *   staging: unknown\n *   production: unknown\n * }\n * const config = createEnvironmentConfig<MyEnvs>()('dev', {\n *   port: { doc: 'Port', format: Number, value: 3000 },\n * })\n * config.port // number\n * ```\n *\n * @example Fallback environments\n * ```ts\n * // When running in `dev`, any entry that does not declare a `dev` value\n * // falls back to the entry's `integ` value.\n * const config = createEnvironmentConfig<MyEnvs>()(\n *   'dev',\n *   {\n *     apiUrl: {\n *       doc: 'API URL',\n *       format: 'url',\n *       integ: 'https://integ.example.com',\n *       staging: 'https://staging.example.com',\n *       production: 'https://api.example.com',\n *     },\n *   },\n *   { fallbacks: { dev: 'integ' } },\n * )\n * ```\n */\nexport function createEnvironmentConfig<E extends EnvsShape>() {\n  return <const G extends ConfigGroup<E>>(\n    env: EnvName<E>,\n    inputConfig: ValidateSchema<G, E>,\n    options?: CreateConfigOptions<E>,\n  ): ResolveConfigGroup<G> & { env: EnvName<E> } =>\n    buildConfig<E, G>(env, inputConfig as unknown as G, options)\n}\n\nfunction buildConfig<E extends EnvsShape, G extends ConfigGroup<E>>(\n  env: EnvName<E>,\n  inputConfig: G,\n  options?: CreateConfigOptions<E>,\n): ResolveConfigGroup<G> & { env: EnvName<E> } {\n  const errors: string[] = []\n\n  // Resolve the per-environment lookup chain once for the active env.\n  // Throws synchronously on a circular fallback chain.\n  const envChain = resolveFallbackChain<E>(env, options?.fallbacks)\n\n  function processConfig(\n    config: ConfigGroup<E>,\n    keyPrefix: string,\n  ): Record<string, any> {\n    const output: Record<string, any> = {}\n\n    for (const [key, entry] of Object.entries(config)) {\n      if (key === \"env\") {\n        throw new Error(\n          `Config key \"env\" is reserved and cannot be used. It will already be present by default.`,\n        )\n      }\n\n      const fullKey = keyPrefix ? `${keyPrefix}.${key}` : key\n\n      if (!(\"doc\" in entry)) {\n        output[key] = processConfig(entry as ConfigGroup<E>, fullKey)\n        continue\n      }\n\n      const configEntry = entry as any\n\n      // Value resolution — sources are evaluated in ascending priority order.\n      // The highest-priority source that resolves to a defined value wins.\n      //\n      //  Priority │ Source\n      //  ─────────┼────────────────────────────────────────────────────────────────\n      //  1 (low)  │ Static `value` — same value across all environments\n      //  2        │ Per-environment field, walking the fallback chain\n      //           │ — overrides the static value for that specific environment\n      //  3 (high) │ Runtime env var via `processEnv` or `importMetaEnv`\n      //           │ — always wins; intended for secrets and local dev overrides\n\n      // Priority 1: static value (lowest precedence)\n      let value: any = \"value\" in configEntry ? configEntry.value : undefined\n\n      // Priority 2: per-environment value, walking the fallback chain.\n      // The first env in the chain with a defined value wins.\n      for (const candidateEnv of envChain) {\n        const envValue = configEntry[candidateEnv]\n        if (envValue !== undefined) {\n          value = envValue\n          break\n        }\n      }\n\n      // Priority 3: runtime env var (highest precedence — always wins when defined)\n      if (\"processEnv\" in configEntry) {\n        const runtimeOverride =\n          // @ts-expect-error process may not be defined in browser builds\n          typeof process !== \"undefined\" && process.env\n            ? // @ts-expect-error process may not be defined in browser builds\n              process.env[configEntry.processEnv as string]\n            : undefined\n        if (runtimeOverride !== undefined) value = runtimeOverride\n      } else if (\"importMetaEnv\" in configEntry) {\n        const runtimeOverride =\n          // @ts-expect-error import.meta.env may not be defined in Node builds\n          typeof import.meta !== \"undefined\" && import.meta.env\n            ? // @ts-expect-error import.meta.env may not be defined in Node builds\n              import.meta.env[configEntry.importMetaEnv as string]\n            : undefined\n        if (runtimeOverride !== undefined) value = runtimeOverride\n      }\n\n      const hasValueSource =\n        value !== undefined ||\n        \"processEnv\" in configEntry ||\n        \"importMetaEnv\" in configEntry ||\n        configEntry.optional\n\n      if (value === undefined && !hasValueSource) {\n        errors.push(\n          `${fullKey}: No value source declared and \"optional\" is not set.`,\n        )\n        continue\n      }\n\n      if (value === undefined) {\n        if (configEntry.optional) {\n          value = configEntry.default\n          if (value === undefined) {\n            output[key] = undefined\n            continue\n          }\n        } else {\n          errors.push(\n            `${fullKey}: Missing required config value in environment ${env}`,\n          )\n          continue\n        }\n      }\n\n      //\n      // Format validation and coercion\n      //\n      value = validateAndCoerce(value, configEntry.format, fullKey, errors)\n\n      output[key] = value\n    }\n\n    return output\n  }\n\n  let outputConfig = processConfig(inputConfig, \"\")\n\n  if (errors.length > 0) {\n    console.error(\"Environment config validation failed\", errors)\n    throw new Error(\n      `Environment config validation failed:\\n${errors.join(\"\\n\")}`,\n    )\n  }\n\n  outputConfig = {\n    env,\n    ...outputConfig,\n  }\n  return outputConfig as ResolveConfigGroup<G> & { env: EnvName<E> }\n}\n\n/**\n * Build the ordered list of environments to consult for per-environment\n * value resolution. The active env is always first; each subsequent entry\n * is the fallback target declared for the previous env. Throws if the\n * chain is cyclic.\n */\nfunction resolveFallbackChain<E extends EnvsShape>(\n  env: EnvName<E>,\n  fallbacks: Fallbacks<E> | undefined,\n): EnvName<E>[] {\n  const chain: EnvName<E>[] = [env]\n  if (!fallbacks) return chain\n\n  const seen = new Set<string>([env])\n  let current: EnvName<E> = env\n  while (fallbacks[current] !== undefined) {\n    const next = fallbacks[current] as EnvName<E>\n    if (seen.has(next)) {\n      throw new Error(\n        `Circular fallback chain detected: ${[...chain, next].join(\" -> \")}`,\n      )\n    }\n    seen.add(next)\n    chain.push(next)\n    current = next\n  }\n  return chain\n}\n","import { createEnvironmentConfig } from \"./create-config.js\"\nimport type {\n  ConfigGroup,\n  ResolveConfigGroup,\n  ValidateSchema,\n} from \"./types.js\"\nimport type { CreateConfigOptions, EnvName, EnvsShape } from \"./util-types.js\"\n\n/**\n * Like {@link createEnvironmentConfig}, but binds the schema first and the\n * environment later. Useful when the active environment is not known at\n * schema-definition time.\n *\n * @typeParam E - The envs shape describing required/optional environments.\n *\n * @example\n * ```ts\n * type MyEnvs = {\n *   dev?: unknown\n *   staging: unknown\n *   production: unknown\n * }\n * const buildConfig = defineEnvironmentConfig<MyEnvs>()({\n *   port: { doc: 'Port', format: Number, value: 3000 },\n * })\n * const config = buildConfig('dev')\n * ```\n *\n * @example Fallback environments\n * ```ts\n * const buildConfig = defineEnvironmentConfig<MyEnvs>()(\n *   { apiUrl: { doc: 'API URL', format: 'url', staging: 'https://staging' } },\n *   { fallbacks: { dev: 'staging' } },\n * )\n * const config = buildConfig('dev') // apiUrl resolved from `staging`\n * ```\n */\nexport function defineEnvironmentConfig<E extends EnvsShape>() {\n  const create = createEnvironmentConfig<E>()\n  return <const G extends ConfigGroup<E>>(\n    inputConfig: ValidateSchema<G, E>,\n    options?: CreateConfigOptions<E>,\n  ): ((env: EnvName<E>) => ResolveConfigGroup<G> & { env: EnvName<E> }) =>\n    (env: EnvName<E>) =>\n      create(env, inputConfig as any, options)\n}\n"],"mappings":"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"}

package/dist/index.d.cts

@@ -0,0 +1,258 @@
+//#region src/util-types.d.ts
+/**
+ * Declaration of the environments a config supports: an object whose keys
+ * are environment names, with required envs as required properties and
+ * optional envs as optional properties.
+ *
+ * The property value type is not used by the library — only the keys and
+ * their required/optional status matter — so `unknown` (or any other type)
+ * is fine.
+ *
+ * @example
+ * ```ts
+ * type MyEnvs = {
+ *   dev?: unknown
+ *   integ?: unknown
+ *   staging: unknown
+ *   production: unknown
+ * }
+ * ```
+ */
+type EnvsShape = Record<string, any>;
+type RequiredKeys<T> = { [K in keyof T]-?: {} extends Pick<T, K> ? never : K }[keyof T] & string;
+type OptionalKeys<T> = { [K in keyof T]-?: {} extends Pick<T, K> ? K : never }[keyof T] & string;
+/** Union of all environment names declared on `E` (required ∪ optional). */
+type EnvName<E extends EnvsShape> = keyof E & string;
+/**
+ * Per-environment value shape for a value of type `T`:
+ * required envs are required, optional envs are optional.
+ */
+type PerEnv<E extends EnvsShape, T> = { [K in RequiredKeys<E>]: T } & { [K in OptionalKeys<E>]?: T };
+/**
+ * Map of environment names to a fallback environment name.
+ *
+ * If a per-environment value is not declared for the active environment on
+ * a given config entry, resolution falls back to the value declared for the
+ * environment named here. Fallbacks chain transitively until a value is
+ * found or the chain ends.
+ *
+ * Both keys and values must be names declared on the envs shape `E`.
+ *
+ * @example
+ * ```ts
+ * type MyEnvs = {
+ *   dev?: unknown
+ *   integ?: unknown
+ *   staging: unknown
+ *   production: unknown
+ * }
+ *
+ * // When running in `dev`, fall back to `integ`; if `integ` is also
+ * // missing a value, fall back to `staging`.
+ * const fallbacks: Fallbacks<MyEnvs> = {
+ *   dev: 'integ',
+ *   integ: 'staging',
+ * }
+ * ```
+ */
+type Fallbacks<E extends EnvsShape> = Partial<Record<EnvName<E>, EnvName<E>>>;
+/**
+ * Options accepted as the third argument to `createEnvironmentConfig` (and
+ * the second argument to `defineEnvironmentConfig`).
+ */
+type CreateConfigOptions<E extends EnvsShape> = {
+  /**
+   * Map of environment names to a fallback environment name. See
+   * {@link Fallbacks} for details.
+   */
+  fallbacks?: Fallbacks<E>;
+};
+//#endregion
+//#region src/types.d.ts
+type NoEnvKeys<E extends EnvsShape> = { [K in EnvName<E>]?: never };
+type RuntimeSourceOptional<T> = {
+  value?: T;
+  processEnv?: never;
+  importMetaEnv?: never;
+} | {
+  value?: T;
+  processEnv: string;
+  importMetaEnv?: never;
+} | {
+  value?: T;
+  processEnv?: never;
+  importMetaEnv: string;
+};
+type ValueSourceRequired<T> = {
+  value: T;
+  processEnv?: never;
+  importMetaEnv?: never;
+} | {
+  value?: T;
+  processEnv: string;
+  importMetaEnv?: never;
+} | {
+  value?: T;
+  processEnv?: never;
+  importMetaEnv: string;
+} | {
+  optional: true;
+  value?: T;
+  processEnv?: never;
+  importMetaEnv?: never;
+  default: T;
+};
+type ValueSource<T, E extends EnvsShape> = (PerEnv<E, T> & RuntimeSourceOptional<T>) | (NoEnvKeys<E> & ValueSourceRequired<T>);
+type ConfigEntryBase<T, E extends EnvsShape> = {
+  doc: string;
+  optional?: boolean;
+} & ValueSource<T, E>;
+type ConfigGroup<E extends EnvsShape> = {
+  [key: string]: ConfigEntry<any, E> | ConfigGroup<E>;
+};
+type MaybeOptionalUndefined<E, T> = E extends {
+  optional: true;
+} ? E extends {
+  default: any;
+} ? T : T | undefined : T;
+type ReservedEntryKeys = "doc" | "format" | "optional" | "default" | "value" | "processEnv" | "importMetaEnv";
+type NeverToAny<T> = [T] extends [never] ? any : T;
+type UntypedResolved<E> = NeverToAny<(E extends {
+  value: infer V;
+} ? V : never) | (E extends {
+  default: infer D;
+} ? D : never) | (E extends Record<string, any> ? E[Exclude<keyof E, ReservedEntryKeys>] : never)>;
+type ResolveEntryType<E> = E extends {
+  format: StringConstructor;
+} ? MaybeOptionalUndefined<E, string> : E extends {
+  format: NumberConstructor;
+} ? MaybeOptionalUndefined<E, number> : E extends {
+  format: BooleanConstructor;
+} ? MaybeOptionalUndefined<E, boolean> : E extends {
+  format: 'url';
+} ? MaybeOptionalUndefined<E, string> : E extends {
+  format: (infer F)[];
+} ? MaybeOptionalUndefined<E, F> : E extends {
+  format: ArrayConstructor;
+} ? MaybeOptionalUndefined<E, any[]> : MaybeOptionalUndefined<E, UntypedResolved<E>>;
+type ResolveConfigGroup<G> = { [K in keyof G]: G[K] extends {
+  doc: string;
+} ? ResolveEntryType<G[K]> : ResolveConfigGroup<G[K]> };
+type ConfigEntry<T, E extends EnvsShape> = UntypedEntry<E> | StringEntry<E> | NumberEntry<E> | BooleanEntry<E> | ArrayEntry<T, E> | EnumEntry<T, E> | UrlEntry<E>;
+type StringEntry<E extends EnvsShape> = ConfigEntryBase<string, E> & {
+  format: StringConstructor;
+  default?: string;
+};
+type NumberEntry<E extends EnvsShape> = ConfigEntryBase<number, E> & {
+  format: NumberConstructor;
+  default?: number;
+};
+type BooleanEntry<E extends EnvsShape> = ConfigEntryBase<boolean, E> & {
+  format: BooleanConstructor;
+  default?: boolean;
+};
+type ArrayEntry<T, E extends EnvsShape> = ConfigEntryBase<T[], E> & {
+  format: ArrayConstructor;
+  default?: T[];
+};
+type EnumEntry<T, E extends EnvsShape> = ConfigEntryBase<T, E> & {
+  format: T[];
+  default?: T;
+};
+type UrlEntry<E extends EnvsShape> = ConfigEntryBase<string, E> & {
+  format: "url";
+  default?: string;
+};
+type UntypedEntry<E extends EnvsShape> = ConfigEntryBase<any, E> & {
+  format?: never;
+  default?: any;
+};
+type ValidateSchema<G, E extends EnvsShape> = { [K in keyof G]: G[K] extends {
+  format: readonly (infer V)[];
+} ? { [P in keyof G[K]]: P extends EnvName<E> | "value" | "default" ? G[K][P] extends V | undefined ? G[K][P] : V : G[K][P] } : G[K] extends {
+  format: unknown;
+} ? G[K] : G[K] extends {
+  doc: string;
+} ? G[K] : ValidateSchema<G[K], E> };
+//#endregion
+//#region src/create-config.d.ts
+/**
+ * Create a resolved, validated config for the given environment.
+ *
+ * Curried so the envs declaration is bound on the first call and the
+ * schema is inferred (giving you autocomplete) on the second call.
+ *
+ * @typeParam E - The envs shape describing required/optional environments.
+ *
+ * @example
+ * ```ts
+ * type MyEnvs = {
+ *   dev?: unknown
+ *   staging: unknown
+ *   production: unknown
+ * }
+ * const config = createEnvironmentConfig<MyEnvs>()('dev', {
+ *   port: { doc: 'Port', format: Number, value: 3000 },
+ * })
+ * config.port // number
+ * ```
+ *
+ * @example Fallback environments
+ * ```ts
+ * // When running in `dev`, any entry that does not declare a `dev` value
+ * // falls back to the entry's `integ` value.
+ * const config = createEnvironmentConfig<MyEnvs>()(
+ *   'dev',
+ *   {
+ *     apiUrl: {
+ *       doc: 'API URL',
+ *       format: 'url',
+ *       integ: 'https://integ.example.com',
+ *       staging: 'https://staging.example.com',
+ *       production: 'https://api.example.com',
+ *     },
+ *   },
+ *   { fallbacks: { dev: 'integ' } },
+ * )
+ * ```
+ */
+declare function createEnvironmentConfig<E extends EnvsShape>(): <const G extends ConfigGroup<E>>(env: EnvName<E>, inputConfig: ValidateSchema<G, E>, options?: CreateConfigOptions<E>) => ResolveConfigGroup<G> & {
+  env: EnvName<E>;
+};
+//#endregion
+//#region src/define-config.d.ts
+/**
+ * Like {@link createEnvironmentConfig}, but binds the schema first and the
+ * environment later. Useful when the active environment is not known at
+ * schema-definition time.
+ *
+ * @typeParam E - The envs shape describing required/optional environments.
+ *
+ * @example
+ * ```ts
+ * type MyEnvs = {
+ *   dev?: unknown
+ *   staging: unknown
+ *   production: unknown
+ * }
+ * const buildConfig = defineEnvironmentConfig<MyEnvs>()({
+ *   port: { doc: 'Port', format: Number, value: 3000 },
+ * })
+ * const config = buildConfig('dev')
+ * ```
+ *
+ * @example Fallback environments
+ * ```ts
+ * const buildConfig = defineEnvironmentConfig<MyEnvs>()(
+ *   { apiUrl: { doc: 'API URL', format: 'url', staging: 'https://staging' } },
+ *   { fallbacks: { dev: 'staging' } },
+ * )
+ * const config = buildConfig('dev') // apiUrl resolved from `staging`
+ * ```
+ */
+declare function defineEnvironmentConfig<E extends EnvsShape>(): <const G extends ConfigGroup<E>>(inputConfig: ValidateSchema<G, E>, options?: CreateConfigOptions<E>) => ((env: EnvName<E>) => ResolveConfigGroup<G> & {
+  env: EnvName<E>;
+});
+//#endregion
+export { type CreateConfigOptions, type EnvName, type EnvsShape, type Fallbacks, type PerEnv, createEnvironmentConfig, defineEnvironmentConfig };
+//# sourceMappingURL=index.d.cts.map

package/dist/index.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.cts","names":[],"sources":["../src/util-types.ts","../src/types.ts","../src/create-config.ts","../src/define-config.ts"],"mappings":"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"}

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-//#region lib/util-types.d.ts
+//#region src/util-types.d.ts
 /**
  * Declaration of the environments a config supports: an object whose keys
  * are environment names, with required envs as required properties and
@@ -68,7 +68,7 @@ type CreateConfigOptions<E extends EnvsShape> = {
   fallbacks?: Fallbacks<E>;
 };
 //#endregion
-//#region lib/types.d.ts
+//#region src/types.d.ts
 type NoEnvKeys<E extends EnvsShape> = { [K in EnvName<E>]?: never };
 type RuntimeSourceOptional<T> = {
   value?: T;
@@ -95,6 +95,12 @@ type ValueSourceRequired<T> = {
   value?: T;
   processEnv?: never;
   importMetaEnv: string;
+} | {
+  optional: true;
+  value?: T;
+  processEnv?: never;
+  importMetaEnv?: never;
+  default: T;
 };
 type ValueSource<T, E extends EnvsShape> = (PerEnv<E, T> & RuntimeSourceOptional<T>) | (NoEnvKeys<E> & ValueSourceRequired<T>);
 type ConfigEntryBase<T, E extends EnvsShape> = {
@@ -104,19 +110,31 @@ type ConfigEntryBase<T, E extends EnvsShape> = {
 type ConfigGroup<E extends EnvsShape> = {
   [key: string]: ConfigEntry<any, E> | ConfigGroup<E>;
 };
+type MaybeOptionalUndefined<E, T> = E extends {
+  optional: true;
+} ? E extends {
+  default: any;
+} ? T : T | undefined : T;
+type ReservedEntryKeys = "doc" | "format" | "optional" | "default" | "value" | "processEnv" | "importMetaEnv";
+type NeverToAny<T> = [T] extends [never] ? any : T;
+type UntypedResolved<E> = NeverToAny<(E extends {
+  value: infer V;
+} ? V : never) | (E extends {
+  default: infer D;
+} ? D : never) | (E extends Record<string, any> ? E[Exclude<keyof E, ReservedEntryKeys>] : never)>;
 type ResolveEntryType<E> = E extends {
   format: StringConstructor;
-} ? string : E extends {
+} ? MaybeOptionalUndefined<E, string> : E extends {
   format: NumberConstructor;
-} ? number : E extends {
+} ? MaybeOptionalUndefined<E, number> : E extends {
   format: BooleanConstructor;
-} ? boolean : E extends {
+} ? MaybeOptionalUndefined<E, boolean> : E extends {
   format: 'url';
-} ? string : E extends {
+} ? MaybeOptionalUndefined<E, string> : E extends {
   format: (infer F)[];
-} ? F : E extends {
+} ? MaybeOptionalUndefined<E, F> : E extends {
   format: ArrayConstructor;
-} ? any[] : any;
+} ? MaybeOptionalUndefined<E, any[]> : MaybeOptionalUndefined<E, UntypedResolved<E>>;
 type ResolveConfigGroup<G> = { [K in keyof G]: G[K] extends {
   doc: string;
 } ? ResolveEntryType<G[K]> : ResolveConfigGroup<G[K]> };
@@ -149,8 +167,15 @@ type UntypedEntry<E extends EnvsShape> = ConfigEntryBase<any, E> & {
   format?: never;
   default?: any;
 };
+type ValidateSchema<G, E extends EnvsShape> = { [K in keyof G]: G[K] extends {
+  format: readonly (infer V)[];
+} ? { [P in keyof G[K]]: P extends EnvName<E> | "value" | "default" ? G[K][P] extends V | undefined ? G[K][P] : V : G[K][P] } : G[K] extends {
+  format: unknown;
+} ? G[K] : G[K] extends {
+  doc: string;
+} ? G[K] : ValidateSchema<G[K], E> };
 //#endregion
-//#region lib/create-config.d.ts
+//#region src/create-config.d.ts
 /**
  * Create a resolved, validated config for the given environment.
  *
@@ -191,11 +216,11 @@ type UntypedEntry<E extends EnvsShape> = ConfigEntryBase<any, E> & {
  * )
  * ```
  */
-declare function createEnvironmentConfig<E extends EnvsShape>(): <G extends ConfigGroup<E>>(env: EnvName<E>, inputConfig: G, options?: CreateConfigOptions<E>) => ResolveConfigGroup<G> & {
+declare function createEnvironmentConfig<E extends EnvsShape>(): <const G extends ConfigGroup<E>>(env: EnvName<E>, inputConfig: ValidateSchema<G, E>, options?: CreateConfigOptions<E>) => ResolveConfigGroup<G> & {
   env: EnvName<E>;
 };
 //#endregion
-//#region lib/define-config.d.ts
+//#region src/define-config.d.ts
 /**
  * Like {@link createEnvironmentConfig}, but binds the schema first and the
  * environment later. Useful when the active environment is not known at
@@ -225,7 +250,7 @@ declare function createEnvironmentConfig<E extends EnvsShape>(): <G extends Conf
  * const config = buildConfig('dev') // apiUrl resolved from `staging`
  * ```
  */
-declare function defineEnvironmentConfig<E extends EnvsShape>(): <G extends ConfigGroup<E>>(inputConfig: G, options?: CreateConfigOptions<E>) => ((env: EnvName<E>) => ResolveConfigGroup<G> & {
+declare function defineEnvironmentConfig<E extends EnvsShape>(): <const G extends ConfigGroup<E>>(inputConfig: ValidateSchema<G, E>, options?: CreateConfigOptions<E>) => ((env: EnvName<E>) => ResolveConfigGroup<G> & {
   env: EnvName<E>;
 });
 //#endregion

package/dist/index.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","names":[],"sources":["../lib/util-types.ts","../lib/types.ts","../lib/create-config.ts","../lib/define-config.ts"],"mappings":"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"}
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/util-types.ts","../src/types.ts","../src/create-config.ts","../src/define-config.ts"],"mappings":";;AAoBA;;;;AAA8B;AAAa;;;;;;;;;;;;;KAA/B,SAAA,GAAY,MAAM;AAAA,KAEzB,YAAA,oBAES,CAAA,gBAAiB,IAAA,CAAK,CAAA,EAAG,CAAA,YAAa,CAAA,SAC5C,CAAA;AAAA,KAGH,YAAA,oBAES,CAAA,gBAAiB,IAAA,CAAK,CAAA,EAAG,CAAA,IAAK,CAAA,iBACpC,CAAA;AANC;AAAA,KAUG,OAAA,WAAkB,SAAA,UAAmB,CAAC;;;;;KAMtC,MAAA,WAAiB,SAAA,eAAwB,YAAA,CAAa,CAAA,IAAK,CAAA,aAC/D,YAAA,CAAa,CAAA,KAAM,CAAA;;;;;;;;;;;AAXlB;AAIT;;;;;;;;AAAkD;AAMlD;;;;;;;KA+BY,SAAA,WAAoB,SAAA,IAAa,OAAA,CAC3C,MAAA,CAAO,OAAA,CAAQ,CAAA,GAAI,OAAA,CAAQ,CAAA;;;;;KAOjB,mBAAA,WAA8B,SAAA;EAvCb;;;;EA4C3B,SAAA,GAAY,SAAA,CAAU,CAAA;AAAA;;;KCjFnB,SAAA,WAAoB,SAAA,YAAqB,OAAA,CAAQ,CAAA;AAAA,KAGjD,qBAAA;EACC,KAAA,GAAQ,CAAA;EAAG,UAAA;EAAoB,aAAA;AAAA;EAC/B,KAAA,GAAQ,CAAA;EAAG,UAAA;EAAoB,aAAA;AAAA;EAC/B,KAAA,GAAQ,CAAA;EAAG,UAAA;EAAoB,aAAA;AAAA;AAAA,KAIhC,mBAAA;EACC,KAAA,EAAO,CAAA;EAAG,UAAA;EAAoB,aAAA;AAAA;EAC9B,KAAA,GAAQ,CAAA;EAAG,UAAA;EAAoB,aAAA;AAAA;EAC/B,KAAA,GAAQ,CAAA;EAAG,UAAA;EAAoB,aAAA;AAAA;EAC/B,QAAA;EAAgB,KAAA,GAAQ,CAAA;EAAG,UAAA;EAAoB,aAAA;EAAuB,OAAA,EAAS,CAAA;AAAA;AAAA,KAKhF,WAAA,cAAyB,SAAA,KACzB,MAAA,CAAO,CAAA,EAAG,CAAA,IAAK,qBAAA,CAAsB,CAAA,MACrC,SAAA,CAAU,CAAA,IAAK,mBAAA,CAAoB,CAAA;AAAA,KAE5B,eAAA,cAA6B,SAAA;EACvC,GAAA;EACA,QAAA;AAAA,IACE,WAAA,CAAY,CAAA,EAAG,CAAA;AAAA,KAEP,WAAA,WAAsB,SAAA;EAAA,CAC/B,GAAA,WAAc,WAAA,MAAiB,CAAA,IAAK,WAAA,CAAY,CAAA;AAAA;AAAA,KAK9C,sBAAA,SACH,CAAA;EAAY,QAAA;AAAA,IACR,CAAA;EAAY,OAAA;AAAA,IACV,CAAA,GACA,CAAA,eACF,CAAA;AAAA,KAGD,iBAAA;AAAA,KAUA,UAAA,OAAiB,CAAA,0BAA2B,CAAC;AAAA,KAM7C,eAAA,MAAqB,UAAA,EACrB,CAAA;EAAY,KAAA;AAAA,IAAmB,CAAA,aAC/B,CAAA;EAAY,OAAA;AAAA,IAAqB,CAAA,aACjC,CAAA,SAAU,MAAA,gBAAsB,CAAA,CAAE,OAAA,OAAc,CAAA,EAAG,iBAAA;AAAA,KAI5C,gBAAA,MACV,CAAA;EAAW,MAAA,EAAQ,iBAAA;AAAA,IAAqB,sBAAA,CAAuB,CAAA,YAC/D,CAAA;EAAW,MAAA,EAAQ,iBAAA;AAAA,IAAqB,sBAAA,CAAuB,CAAA,YAC/D,CAAA;EAAW,MAAA,EAAQ,kBAAA;AAAA,IAAsB,sBAAA,CAAuB,CAAA,aAChE,CAAA;EAAW,MAAA;AAAA,IAAiB,sBAAA,CAAuB,CAAA,YACnD,CAAA;EAAW,MAAA;AAAA,IAAuB,sBAAA,CAAuB,CAAA,EAAG,CAAA,IAC5D,CAAA;EAAW,MAAA,EAAQ,gBAAA;AAAA,IAAoB,sBAAA,CAAuB,CAAA,WAC9D,sBAAA,CAAuB,CAAA,EAAG,eAAA,CAAgB,CAAA;AAAA,KAEhC,kBAAA,oBACE,CAAA,GAAI,CAAA,CAAE,CAAA;EAAa,GAAA;AAAA,IAC3B,gBAAA,CAAiB,CAAA,CAAE,CAAA,KACnB,kBAAA,CAAmB,CAAA,CAAE,CAAA;AAAA,KAOf,WAAA,cAAyB,SAAA,IACjC,YAAA,CAAa,CAAA,IACb,WAAA,CAAY,CAAA,IACZ,WAAA,CAAY,CAAA,IACZ,YAAA,CAAa,CAAA,IACb,UAAA,CAAW,CAAA,EAAG,CAAA,IACd,SAAA,CAAU,CAAA,EAAG,CAAA,IACb,QAAA,CAAS,CAAA;AAAA,KAER,WAAA,WAAsB,SAAA,IAAa,eAAA,SAAwB,CAAA;EAC9D,MAAA,EAAQ,iBAAA;EACR,OAAA;AAAA;AAAA,KAGG,WAAA,WAAsB,SAAA,IAAa,eAAA,SAAwB,CAAA;EAC9D,MAAA,EAAQ,iBAAA;EACR,OAAA;AAAA;AAAA,KAGG,YAAA,WAAuB,SAAA,IAAa,eAAA,UAAyB,CAAA;EAChE,MAAA,EAAQ,kBAAA;EACR,OAAA;AAAA;AAAA,KAGG,UAAA,cAAwB,SAAA,IAAa,eAAA,CAAgB,CAAA,IAAK,CAAA;EAC7D,MAAA,EAAQ,gBAAA;EACR,OAAA,GAAU,CAAA;AAAA;AAAA,KAGP,SAAA,cAAuB,SAAA,IAAa,eAAA,CAAgB,CAAA,EAAG,CAAA;EAC1D,MAAA,EAAQ,CAAA;EACR,OAAA,GAAU,CAAA;AAAA;AAAA,KAGP,QAAA,WAAmB,SAAA,IAAa,eAAA,SAAwB,CAAA;EAC3D,MAAA;EACA,OAAA;AAAA;AAAA,KAGG,YAAA,WAAuB,SAAA,IAAa,eAAA,MAAqB,CAAA;EAC5D,MAAA;EACA,OAAA;AAAA;AAAA,KAMU,cAAA,cAA4B,SAAA,kBAC1B,CAAA,GAAI,CAAA,CAAE,CAAA;EAAa,MAAA;AAAA,kBAEb,CAAA,CAAE,CAAA,IAAK,CAAA,SAAU,OAAA,CAAQ,CAAA,0BACjC,CAAA,CAAE,CAAA,EAAG,CAAA,UAAW,CAAA,eACd,CAAA,CAAE,CAAA,EAAG,CAAA,IACL,CAAA,GACF,CAAA,CAAE,CAAA,EAAG,CAAA,MAEX,CAAA,CAAE,CAAA;EAAa,MAAA;AAAA,IACb,CAAA,CAAE,CAAA,IACF,CAAA,CAAE,CAAA;EAAa,GAAA;AAAA,IACb,CAAA,CAAE,CAAA,IACF,cAAA,CAAe,CAAA,CAAE,CAAA,GAAI,CAAA;;;;;;ADhID;AAAa;;;;;;;;;;;;;;;;;;;;AAKlC;AAAA;;;;;;;;;;;;;;;iBE8BO,uBAAA,WAAkC,SAAA,sBACxB,WAAA,CAAY,CAAA,GAClC,GAAA,EAAK,OAAA,CAAQ,CAAA,GACb,WAAA,EAAa,cAAA,CAAe,CAAA,EAAG,CAAA,GAC/B,OAAA,GAAU,mBAAA,CAAoB,CAAA,MAC7B,kBAAA,CAAmB,CAAA;EAAO,GAAA,EAAK,OAAA,CAAQ,CAAA;AAAA;;;;;;AFxCd;AAAa;;;;;;;;;;;;;;;;;;;;AAKlC;AAAA;;;;iBGYO,uBAAA,WAAkC,SAAA,sBAExB,WAAA,CAAY,CAAA,GAClC,WAAA,EAAa,cAAA,CAAe,CAAA,EAAG,CAAA,GAC/B,OAAA,GAAU,mBAAA,CAAoB,CAAA,QAC3B,GAAA,EAAK,OAAA,CAAQ,CAAA,MAAO,kBAAA,CAAmB,CAAA;EAAO,GAAA,EAAK,OAAA,CAAQ,CAAA;AAAA"}

package/dist/index.mjs

@@ -1,35 +1,35 @@
-//#region lib/format.ts
+//#region src/format.ts
 function validateAndCoerce(value, format, fullKey, errors) {
 	switch (format) {
 		case String:
-			if (typeof value !== "string") errors.push(`Config value for ${fullKey} must be a string`);
+			if (typeof value !== "string") errors.push(`${fullKey}: must be a string`);
 			break;
 		case Number:
 			value = Number(value);
-			if (isNaN(value)) errors.push(`Config value for ${fullKey} must be a number`);
+			if (isNaN(value)) errors.push(`${fullKey}: must be a number`);
 			break;
 		case Boolean:
-			if (typeof value !== "boolean" && value !== "true" && value !== "false" && value !== 1 && value !== 0) errors.push(`Config value for ${fullKey} must be a boolean`);
+			if (typeof value !== "boolean" && value !== "true" && value !== "false" && value !== 1 && value !== 0) errors.push(`${fullKey}: must be a boolean`);
 			value = value === "true" ? true : value === "false" ? false : Boolean(value);
 			break;
 		case Array:
-			if (!Array.isArray(value)) errors.push(`Config value for ${fullKey} must be an array`);
+			if (!Array.isArray(value)) errors.push(`${fullKey}: must be an array`);
 			break;
 		case "url":
 			try {
 				new URL(value);
 			} catch {
-				errors.push(`Config value for ${fullKey} must be a valid URL; found "${value}"`);
+				errors.push(`${fullKey}: must be a valid URL; found "${value}"`);
 			}
 			break;
 		default: if (format instanceof Array) {
-			if (!format.includes(value)) errors.push(`Config value for ${fullKey} must be one of: [${format.join(", ")}]`);
+			if (!format.includes(value)) errors.push(`${fullKey}: must be one of: [${format.join(", ")}]`);
 		}
 	}
 	return value;
 }
 //#endregion
-//#region lib/create-config.ts
+//#region src/create-config.ts
 /**
 * Create a resolved, validated config for the given environment.
 *
@@ -101,9 +101,9 @@ function buildConfig(env, inputConfig, options) {
 				const runtimeOverride = typeof import.meta !== "undefined" && import.meta.env ? import.meta.env[configEntry.importMetaEnv] : void 0;
 				if (runtimeOverride !== void 0) value = runtimeOverride;
 			}
-			const hasValueSource = value !== void 0 || "processEnv" in configEntry || "importMetaEnv" in configEntry;
+			const hasValueSource = value !== void 0 || "processEnv" in configEntry || "importMetaEnv" in configEntry || configEntry.optional;
 			if (value === void 0 && !hasValueSource) {
-				errors.push(`No value source declared for ${fullKey}. Supply a value using environment names, "value", "processEnv", or "importMetaEnv".`);
+				errors.push(`${fullKey}: No value source declared and "optional" is not set.`);
 				continue;
 			}
 			if (value === void 0) if (configEntry.optional) {
@@ -113,7 +113,7 @@ function buildConfig(env, inputConfig, options) {
 					continue;
 				}
 			} else {
-				errors.push(`Missing required config value for ${fullKey} in environment ${env}`);
+				errors.push(`${fullKey}: Missing required config value in environment ${env}`);
 				continue;
 			}
 			value = validateAndCoerce(value, configEntry.format, fullKey, errors);
@@ -121,12 +121,15 @@ function buildConfig(env, inputConfig, options) {
 		}
 		return output;
 	}
-	const outputConfig = processConfig(inputConfig, "");
+	let outputConfig = processConfig(inputConfig, "");
 	if (errors.length > 0) {
 		console.error("Environment config validation failed", errors);
 		throw new Error(`Environment config validation failed:\n${errors.join("\n")}`);
 	}
-	outputConfig.env = env;
+	outputConfig = {
+		env,
+		...outputConfig
+	};
 	return outputConfig;
 }
 /**
@@ -150,7 +153,7 @@ function resolveFallbackChain(env, fallbacks) {
 	return chain;
 }
 //#endregion
-//#region lib/define-config.ts
+//#region src/define-config.ts
 /**
 * Like {@link createEnvironmentConfig}, but binds the schema first and the
 * environment later. Useful when the active environment is not known at

package/dist/index.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.mjs","names":[],"sources":["../lib/format.ts","../lib/create-config.ts","../lib/define-config.ts"],"sourcesContent":["/* eslint-disable @typescript-eslint/no-explicit-any */\n\nexport function validateAndCoerce(\n  value: any,\n  format: any,\n  fullKey: string,\n  errors: string[],\n): any {\n  switch (format) {\n    case String:\n      if (typeof value !== \"string\") {\n        errors.push(`Config value for ${fullKey} must be a string`)\n      }\n      break\n    case Number:\n      value = Number(value)\n      if (isNaN(value))\n        errors.push(`Config value for ${fullKey} must be a number`)\n      break\n    case Boolean:\n      if (\n        typeof value !== \"boolean\" &&\n        value !== \"true\" &&\n        value !== \"false\" &&\n        value !== 1 &&\n        value !== 0\n      ) {\n        errors.push(`Config value for ${fullKey} must be a boolean`)\n      }\n      value =\n        value === \"true\" ? true : value === \"false\" ? false : Boolean(value)\n      break\n    case Array:\n      if (!Array.isArray(value)) {\n        errors.push(`Config value for ${fullKey} must be an array`)\n      }\n      break\n    case \"url\":\n      try {\n        new URL(value)\n      } catch {\n        errors.push(\n          `Config value for ${fullKey} must be a valid URL; found \"${value}\"`,\n        )\n      }\n      break\n    default:\n      if (format instanceof Array) {\n        if (!format.includes(value)) {\n          errors.push(\n            `Config value for ${fullKey} must be one of: [${format.join(\", \")}]`,\n          )\n        }\n      }\n  }\n\n  return value\n}\n","/* eslint-disable @typescript-eslint/no-explicit-any */\n\nimport type {\n  EnvsShape,\n  EnvName,\n  CreateConfigOptions,\n  Fallbacks,\n} from \"./util-types.js\"\nimport type { ConfigGroup, ResolveConfigGroup } from \"./types.js\"\nimport { validateAndCoerce } from \"./format.js\"\n\n/**\n * Create a resolved, validated config for the given environment.\n *\n * Curried so the envs declaration is bound on the first call and the\n * schema is inferred (giving you autocomplete) on the second call.\n *\n * @typeParam E - The envs shape describing required/optional environments.\n *\n * @example\n * ```ts\n * type MyEnvs = {\n *   dev?: unknown\n *   staging: unknown\n *   production: unknown\n * }\n * const config = createEnvironmentConfig<MyEnvs>()('dev', {\n *   port: { doc: 'Port', format: Number, value: 3000 },\n * })\n * config.port // number\n * ```\n *\n * @example Fallback environments\n * ```ts\n * // When running in `dev`, any entry that does not declare a `dev` value\n * // falls back to the entry's `integ` value.\n * const config = createEnvironmentConfig<MyEnvs>()(\n *   'dev',\n *   {\n *     apiUrl: {\n *       doc: 'API URL',\n *       format: 'url',\n *       integ: 'https://integ.example.com',\n *       staging: 'https://staging.example.com',\n *       production: 'https://api.example.com',\n *     },\n *   },\n *   { fallbacks: { dev: 'integ' } },\n * )\n * ```\n */\nexport function createEnvironmentConfig<E extends EnvsShape>() {\n  return <G extends ConfigGroup<E>>(\n    env: EnvName<E>,\n    inputConfig: G,\n    options?: CreateConfigOptions<E>,\n  ): ResolveConfigGroup<G> & { env: EnvName<E> } =>\n    buildConfig<E, G>(env, inputConfig, options)\n}\n\nfunction buildConfig<E extends EnvsShape, G extends ConfigGroup<E>>(\n  env: EnvName<E>,\n  inputConfig: G,\n  options?: CreateConfigOptions<E>,\n): ResolveConfigGroup<G> & { env: EnvName<E> } {\n  const errors: string[] = []\n\n  // Resolve the per-environment lookup chain once for the active env.\n  // Throws synchronously on a circular fallback chain.\n  const envChain = resolveFallbackChain<E>(env, options?.fallbacks)\n\n  function processConfig(\n    config: ConfigGroup<E>,\n    keyPrefix: string,\n  ): Record<string, any> {\n    const output: Record<string, any> = {}\n\n    for (const [key, entry] of Object.entries(config)) {\n      if (key === \"env\") {\n        throw new Error(\n          `Config key \"env\" is reserved and cannot be used. It will already be present by default.`,\n        )\n      }\n\n      const fullKey = keyPrefix ? `${keyPrefix}.${key}` : key\n\n      if (!(\"doc\" in entry)) {\n        output[key] = processConfig(entry as ConfigGroup<E>, fullKey)\n        continue\n      }\n\n      const configEntry = entry as any\n\n      // Value resolution — sources are evaluated in ascending priority order.\n      // The highest-priority source that resolves to a defined value wins.\n      //\n      //  Priority │ Source\n      //  ─────────┼────────────────────────────────────────────────────────────────\n      //  1 (low)  │ Static `value` — same value across all environments\n      //  2        │ Per-environment field, walking the fallback chain\n      //           │ — overrides the static value for that specific environment\n      //  3 (high) │ Runtime env var via `processEnv` or `importMetaEnv`\n      //           │ — always wins; intended for secrets and local dev overrides\n\n      // Priority 1: static value (lowest precedence)\n      let value: any = \"value\" in configEntry ? configEntry.value : undefined\n\n      // Priority 2: per-environment value, walking the fallback chain.\n      // The first env in the chain with a defined value wins.\n      for (const candidateEnv of envChain) {\n        const envValue = configEntry[candidateEnv]\n        if (envValue !== undefined) {\n          value = envValue\n          break\n        }\n      }\n\n      // Priority 3: runtime env var (highest precedence — always wins when defined)\n      if (\"processEnv\" in configEntry) {\n        const runtimeOverride =\n          // @ts-expect-error process may not be defined in browser builds\n          typeof process !== \"undefined\" && process.env\n            ? // @ts-expect-error process may not be defined in browser builds\n              process.env[configEntry.processEnv as string]\n            : undefined\n        if (runtimeOverride !== undefined) value = runtimeOverride\n      } else if (\"importMetaEnv\" in configEntry) {\n        const runtimeOverride =\n          // @ts-expect-error import.meta.env may not be defined in Node builds\n          typeof import.meta !== \"undefined\" && import.meta.env\n            ? // @ts-expect-error import.meta.env may not be defined in Node builds\n              import.meta.env[configEntry.importMetaEnv as string]\n            : undefined\n        if (runtimeOverride !== undefined) value = runtimeOverride\n      }\n\n      const hasValueSource =\n        value !== undefined ||\n        \"processEnv\" in configEntry ||\n        \"importMetaEnv\" in configEntry\n\n      if (value === undefined && !hasValueSource) {\n        errors.push(\n          `No value source declared for ${fullKey}. Supply a value using environment names, \"value\", \"processEnv\", or \"importMetaEnv\".`,\n        )\n        continue\n      }\n\n      if (value === undefined) {\n        if (configEntry.optional) {\n          value = configEntry.default\n          if (value === undefined) {\n            output[key] = undefined\n            continue\n          }\n        } else {\n          errors.push(\n            `Missing required config value for ${fullKey} in environment ${env}`,\n          )\n          continue\n        }\n      }\n\n      //\n      // Format validation and coercion\n      //\n      value = validateAndCoerce(value, configEntry.format, fullKey, errors)\n\n      output[key] = value\n    }\n\n    return output\n  }\n\n  const outputConfig = processConfig(inputConfig, \"\")\n\n  if (errors.length > 0) {\n    console.error(\"Environment config validation failed\", errors)\n    throw new Error(\n      `Environment config validation failed:\\n${errors.join(\"\\n\")}`,\n    )\n  }\n\n  outputConfig.env = env\n  return outputConfig as ResolveConfigGroup<G> & { env: EnvName<E> }\n}\n\n/**\n * Build the ordered list of environments to consult for per-environment\n * value resolution. The active env is always first; each subsequent entry\n * is the fallback target declared for the previous env. Throws if the\n * chain is cyclic.\n */\nfunction resolveFallbackChain<E extends EnvsShape>(\n  env: EnvName<E>,\n  fallbacks: Fallbacks<E> | undefined,\n): EnvName<E>[] {\n  const chain: EnvName<E>[] = [env]\n  if (!fallbacks) return chain\n\n  const seen = new Set<string>([env])\n  let current: EnvName<E> = env\n  while (fallbacks[current] !== undefined) {\n    const next = fallbacks[current] as EnvName<E>\n    if (seen.has(next)) {\n      throw new Error(\n        `Circular fallback chain detected: ${[...chain, next].join(\" -> \")}`,\n      )\n    }\n    seen.add(next)\n    chain.push(next)\n    current = next\n  }\n  return chain\n}\n","import type { EnvsShape, EnvName, CreateConfigOptions } from \"./util-types.js\"\nimport type { ConfigGroup, ResolveConfigGroup } from \"./types.js\"\nimport { createEnvironmentConfig } from \"./create-config.js\"\n\n/**\n * Like {@link createEnvironmentConfig}, but binds the schema first and the\n * environment later. Useful when the active environment is not known at\n * schema-definition time.\n *\n * @typeParam E - The envs shape describing required/optional environments.\n *\n * @example\n * ```ts\n * type MyEnvs = {\n *   dev?: unknown\n *   staging: unknown\n *   production: unknown\n * }\n * const buildConfig = defineEnvironmentConfig<MyEnvs>()({\n *   port: { doc: 'Port', format: Number, value: 3000 },\n * })\n * const config = buildConfig('dev')\n * ```\n *\n * @example Fallback environments\n * ```ts\n * const buildConfig = defineEnvironmentConfig<MyEnvs>()(\n *   { apiUrl: { doc: 'API URL', format: 'url', staging: 'https://staging' } },\n *   { fallbacks: { dev: 'staging' } },\n * )\n * const config = buildConfig('dev') // apiUrl resolved from `staging`\n * ```\n */\nexport function defineEnvironmentConfig<E extends EnvsShape>() {\n  const create = createEnvironmentConfig<E>()\n  return <G extends ConfigGroup<E>>(\n      inputConfig: G,\n      options?: CreateConfigOptions<E>,\n    ): ((env: EnvName<E>) => ResolveConfigGroup<G> & { env: EnvName<E> }) =>\n    (env: EnvName<E>) =>\n      create(env, inputConfig, options)\n}\n"],"mappings":"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"}
+{"version":3,"file":"index.mjs","names":[],"sources":["../src/format.ts","../src/create-config.ts","../src/define-config.ts"],"sourcesContent":["/* eslint-disable @typescript-eslint/no-explicit-any */\n\nexport function validateAndCoerce(\n  value: any,\n  format: any,\n  fullKey: string,\n  errors: string[],\n): any {\n  switch (format) {\n    case String:\n      if (typeof value !== \"string\") {\n        errors.push(`${fullKey}: must be a string`)\n      }\n      break\n    case Number:\n      value = Number(value)\n      if (isNaN(value))\n        errors.push(`${fullKey}: must be a number`)\n      break\n    case Boolean:\n      if (\n        typeof value !== \"boolean\" &&\n        value !== \"true\" &&\n        value !== \"false\" &&\n        value !== 1 &&\n        value !== 0\n      ) {\n        errors.push(`${fullKey}: must be a boolean`)\n      }\n      value =\n        value === \"true\" ? true : value === \"false\" ? false : Boolean(value)\n      break\n    case Array:\n      if (!Array.isArray(value)) {\n        errors.push(`${fullKey}: must be an array`)\n      }\n      break\n    case \"url\":\n      try {\n        new URL(value)\n      } catch {\n        errors.push(\n          `${fullKey}: must be a valid URL; found \"${value}\"`,\n        )\n      }\n      break\n    default:\n      if (format instanceof Array) {\n        if (!format.includes(value)) {\n          errors.push(\n            `${fullKey}: must be one of: [${format.join(\", \")}]`,\n          )\n        }\n      }\n  }\n\n  return value\n}\n","/* eslint-disable @typescript-eslint/no-explicit-any */\n\nimport { validateAndCoerce } from \"./format.js\"\nimport type {\n  ConfigGroup,\n  ResolveConfigGroup,\n  ValidateSchema,\n} from \"./types.js\"\nimport type {\n  CreateConfigOptions,\n  EnvName,\n  EnvsShape,\n  Fallbacks,\n} from \"./util-types.js\"\n\n/**\n * Create a resolved, validated config for the given environment.\n *\n * Curried so the envs declaration is bound on the first call and the\n * schema is inferred (giving you autocomplete) on the second call.\n *\n * @typeParam E - The envs shape describing required/optional environments.\n *\n * @example\n * ```ts\n * type MyEnvs = {\n *   dev?: unknown\n *   staging: unknown\n *   production: unknown\n * }\n * const config = createEnvironmentConfig<MyEnvs>()('dev', {\n *   port: { doc: 'Port', format: Number, value: 3000 },\n * })\n * config.port // number\n * ```\n *\n * @example Fallback environments\n * ```ts\n * // When running in `dev`, any entry that does not declare a `dev` value\n * // falls back to the entry's `integ` value.\n * const config = createEnvironmentConfig<MyEnvs>()(\n *   'dev',\n *   {\n *     apiUrl: {\n *       doc: 'API URL',\n *       format: 'url',\n *       integ: 'https://integ.example.com',\n *       staging: 'https://staging.example.com',\n *       production: 'https://api.example.com',\n *     },\n *   },\n *   { fallbacks: { dev: 'integ' } },\n * )\n * ```\n */\nexport function createEnvironmentConfig<E extends EnvsShape>() {\n  return <const G extends ConfigGroup<E>>(\n    env: EnvName<E>,\n    inputConfig: ValidateSchema<G, E>,\n    options?: CreateConfigOptions<E>,\n  ): ResolveConfigGroup<G> & { env: EnvName<E> } =>\n    buildConfig<E, G>(env, inputConfig as unknown as G, options)\n}\n\nfunction buildConfig<E extends EnvsShape, G extends ConfigGroup<E>>(\n  env: EnvName<E>,\n  inputConfig: G,\n  options?: CreateConfigOptions<E>,\n): ResolveConfigGroup<G> & { env: EnvName<E> } {\n  const errors: string[] = []\n\n  // Resolve the per-environment lookup chain once for the active env.\n  // Throws synchronously on a circular fallback chain.\n  const envChain = resolveFallbackChain<E>(env, options?.fallbacks)\n\n  function processConfig(\n    config: ConfigGroup<E>,\n    keyPrefix: string,\n  ): Record<string, any> {\n    const output: Record<string, any> = {}\n\n    for (const [key, entry] of Object.entries(config)) {\n      if (key === \"env\") {\n        throw new Error(\n          `Config key \"env\" is reserved and cannot be used. It will already be present by default.`,\n        )\n      }\n\n      const fullKey = keyPrefix ? `${keyPrefix}.${key}` : key\n\n      if (!(\"doc\" in entry)) {\n        output[key] = processConfig(entry as ConfigGroup<E>, fullKey)\n        continue\n      }\n\n      const configEntry = entry as any\n\n      // Value resolution — sources are evaluated in ascending priority order.\n      // The highest-priority source that resolves to a defined value wins.\n      //\n      //  Priority │ Source\n      //  ─────────┼────────────────────────────────────────────────────────────────\n      //  1 (low)  │ Static `value` — same value across all environments\n      //  2        │ Per-environment field, walking the fallback chain\n      //           │ — overrides the static value for that specific environment\n      //  3 (high) │ Runtime env var via `processEnv` or `importMetaEnv`\n      //           │ — always wins; intended for secrets and local dev overrides\n\n      // Priority 1: static value (lowest precedence)\n      let value: any = \"value\" in configEntry ? configEntry.value : undefined\n\n      // Priority 2: per-environment value, walking the fallback chain.\n      // The first env in the chain with a defined value wins.\n      for (const candidateEnv of envChain) {\n        const envValue = configEntry[candidateEnv]\n        if (envValue !== undefined) {\n          value = envValue\n          break\n        }\n      }\n\n      // Priority 3: runtime env var (highest precedence — always wins when defined)\n      if (\"processEnv\" in configEntry) {\n        const runtimeOverride =\n          // @ts-expect-error process may not be defined in browser builds\n          typeof process !== \"undefined\" && process.env\n            ? // @ts-expect-error process may not be defined in browser builds\n              process.env[configEntry.processEnv as string]\n            : undefined\n        if (runtimeOverride !== undefined) value = runtimeOverride\n      } else if (\"importMetaEnv\" in configEntry) {\n        const runtimeOverride =\n          // @ts-expect-error import.meta.env may not be defined in Node builds\n          typeof import.meta !== \"undefined\" && import.meta.env\n            ? // @ts-expect-error import.meta.env may not be defined in Node builds\n              import.meta.env[configEntry.importMetaEnv as string]\n            : undefined\n        if (runtimeOverride !== undefined) value = runtimeOverride\n      }\n\n      const hasValueSource =\n        value !== undefined ||\n        \"processEnv\" in configEntry ||\n        \"importMetaEnv\" in configEntry ||\n        configEntry.optional\n\n      if (value === undefined && !hasValueSource) {\n        errors.push(\n          `${fullKey}: No value source declared and \"optional\" is not set.`,\n        )\n        continue\n      }\n\n      if (value === undefined) {\n        if (configEntry.optional) {\n          value = configEntry.default\n          if (value === undefined) {\n            output[key] = undefined\n            continue\n          }\n        } else {\n          errors.push(\n            `${fullKey}: Missing required config value in environment ${env}`,\n          )\n          continue\n        }\n      }\n\n      //\n      // Format validation and coercion\n      //\n      value = validateAndCoerce(value, configEntry.format, fullKey, errors)\n\n      output[key] = value\n    }\n\n    return output\n  }\n\n  let outputConfig = processConfig(inputConfig, \"\")\n\n  if (errors.length > 0) {\n    console.error(\"Environment config validation failed\", errors)\n    throw new Error(\n      `Environment config validation failed:\\n${errors.join(\"\\n\")}`,\n    )\n  }\n\n  outputConfig = {\n    env,\n    ...outputConfig,\n  }\n  return outputConfig as ResolveConfigGroup<G> & { env: EnvName<E> }\n}\n\n/**\n * Build the ordered list of environments to consult for per-environment\n * value resolution. The active env is always first; each subsequent entry\n * is the fallback target declared for the previous env. Throws if the\n * chain is cyclic.\n */\nfunction resolveFallbackChain<E extends EnvsShape>(\n  env: EnvName<E>,\n  fallbacks: Fallbacks<E> | undefined,\n): EnvName<E>[] {\n  const chain: EnvName<E>[] = [env]\n  if (!fallbacks) return chain\n\n  const seen = new Set<string>([env])\n  let current: EnvName<E> = env\n  while (fallbacks[current] !== undefined) {\n    const next = fallbacks[current] as EnvName<E>\n    if (seen.has(next)) {\n      throw new Error(\n        `Circular fallback chain detected: ${[...chain, next].join(\" -> \")}`,\n      )\n    }\n    seen.add(next)\n    chain.push(next)\n    current = next\n  }\n  return chain\n}\n","import { createEnvironmentConfig } from \"./create-config.js\"\nimport type {\n  ConfigGroup,\n  ResolveConfigGroup,\n  ValidateSchema,\n} from \"./types.js\"\nimport type { CreateConfigOptions, EnvName, EnvsShape } from \"./util-types.js\"\n\n/**\n * Like {@link createEnvironmentConfig}, but binds the schema first and the\n * environment later. Useful when the active environment is not known at\n * schema-definition time.\n *\n * @typeParam E - The envs shape describing required/optional environments.\n *\n * @example\n * ```ts\n * type MyEnvs = {\n *   dev?: unknown\n *   staging: unknown\n *   production: unknown\n * }\n * const buildConfig = defineEnvironmentConfig<MyEnvs>()({\n *   port: { doc: 'Port', format: Number, value: 3000 },\n * })\n * const config = buildConfig('dev')\n * ```\n *\n * @example Fallback environments\n * ```ts\n * const buildConfig = defineEnvironmentConfig<MyEnvs>()(\n *   { apiUrl: { doc: 'API URL', format: 'url', staging: 'https://staging' } },\n *   { fallbacks: { dev: 'staging' } },\n * )\n * const config = buildConfig('dev') // apiUrl resolved from `staging`\n * ```\n */\nexport function defineEnvironmentConfig<E extends EnvsShape>() {\n  const create = createEnvironmentConfig<E>()\n  return <const G extends ConfigGroup<E>>(\n    inputConfig: ValidateSchema<G, E>,\n    options?: CreateConfigOptions<E>,\n  ): ((env: EnvName<E>) => ResolveConfigGroup<G> & { env: EnvName<E> }) =>\n    (env: EnvName<E>) =>\n      create(env, inputConfig as any, options)\n}\n"],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "konfeeg",
-  "version": "0.0.0",
+  "version": "0.0.2",
   "description": "Build a validated, strongly-typed config object, and use it everywhere.",
   "author": "Zach Olivare <https://github.com/0livare>",
   "license": "ISC",
@@ -9,13 +9,33 @@
     "url": "https://github.com/0livare/konfeeg"
   },
   "type": "module",
-  "main": "dist/index.mjs",
-  "module": "dist/index.mjs",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
   "files": [
     "dist"
   ],
+  "nx": {
+    "targets": {
+      "types": {},
+      "format": {},
+      "lint": {}
+    }
+  },
   "devDependencies": {
-    "prettier": "^3.8.4",
+    "@biomejs/biome": "^2.4.16",
     "tsdown": "^0.22.2",
     "typescript": "^6.0.3",
     "vitest": "^4.1.8"
@@ -31,10 +51,9 @@
     "node"
   ],
   "scripts": {
-    "build": "tsdown lib/index.ts",
+    "dev": "tsdown --watch",
+    "build": "tsdown",
     "test": "vitest --run",
-    "types": "tsc",
-    "format": "prettier --write .",
-    "pr": "tsc && prettier --check . && pnpm run test && pnpm run build"
+    "pub": "npx bumpp && pnpm publish"
   }
 }