konfeeg 0.0.0

package/README.md

@@ -0,0 +1,155 @@
+# konfeeg
+
+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.
+
+---
+
+## Quick start
+
+```ts
+import { createEnvironmentConfig } from "konfeeg"
+
+// 1. Declare your environments (required vs optional)
+type MyEnvs = {
+  dev?: unknown // optional (?) = per-env value may be omitted
+  staging: unknown // required = must supply a value
+  production: unknown
+}
+
+// 2. Build the config — note the extra ()    👇 (curried for TS inference)
+const config = createEnvironmentConfig<MyEnvs>()("staging", {
+  apiUrl: {
+    doc: "Base URL for the API",
+    format: "url", // Will error if the value isn't a valid URL
+    processEnv: "API_URL", // runtime override (highest priority)
+    dev: "http://localhost:3000",
+    staging: "https://staging-api.example.com",
+    production: "https://api.example.com",
+  },
+  mongo: {
+    dbName: {
+      doc: "Mongo database name",
+      format: String, // Will error if the value isn't a string
+      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)
+    },
+  },
+})
+
+config.env // "staging"
+config.apiUrl // string (validated as URL)
+config.mongo.dbName // string
+```
+
+---
+
+## 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                                        |
+
+---
+
+## Formats
+
+Validate that the resolved value matches the declared format. Coercion is applied where reasonable (e.g. numeric strings → numbers, `'true'`/`'false'` → booleans).
+
+| Format       | Resolved type | Notes                                      |
+| ------------ | ------------- | ------------------------------------------ |
+| `String`     | `string`      | Value must be a string                     |
+| `Number`     | `number`      | Numeric strings are coerced                |
+| `Boolean`    | `boolean`     | `'true'`/`'false'` and `0`/`1` are coerced |
+| `Array`      | `any[]`       | Value must be an array                     |
+| `'url'`      | `string`      | Must parse as a valid URL                  |
+| `['a', 'b']` | `'a' \| 'b'`  | Value must be one of the listed literals   |
+
+---
+
+## Value resolution order
+
+When multiple sources are declared on the same entry, the highest-priority source wins.
+
+| Priority    | Source                             | Use for                          |
+| ----------- | ---------------------------------- | -------------------------------- |
+| 3 — highest | `processEnv` / `importMetaEnv`     | Secrets, local overrides         |
+| 2           | Per-env fields (`dev`, `staging`…) | Environment-specific values      |
+| 1 — lowest  | `value`                            | Constants shared across all envs |
+
+---
+
+## 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.
+
+```ts
+const config = createEnvironmentConfig<MyEnvs>()(
+  "dev",
+  {
+    apiUrl: {
+      doc: "API URL",
+      format: "url",
+      // no `dev` field — falls back to `integ`
+      integ: "https://integ.example.com",
+      staging: "https://staging.example.com",
+      production: "https://api.example.com",
+    },
+  },
+  {
+    fallbacks: {
+      dev: "integ", // dev → integ
+      integ: "staging", // integ → staging (chained)
+    },
+  },
+)
+
+config.apiUrl // "https://integ.example.com"
+```
+
+A circular fallback chain (e.g. `{ dev: 'integ', integ: 'dev' }`) throws synchronously with the cycle path in the error message.
+
+---
+
+## `defineEnvironmentConfig`
+
+Same as `createEnvironmentConfig`, but binds the schema first and the environment later — useful when the environment isn't known at schema-definition time.
+
+```ts
+import { defineEnvironmentConfig } from "konfeeg"
+
+const buildConfig = defineEnvironmentConfig<MyEnvs>()({
+  /* schema */
+})
+
+const config = buildConfig(process.env.APP_ENV as any)
+```

package/dist/index.d.mts

@@ -0,0 +1,233 @@
+//#region lib/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 lib/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;
+};
+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 ResolveEntryType<E> = E extends {
+  format: StringConstructor;
+} ? string : E extends {
+  format: NumberConstructor;
+} ? number : E extends {
+  format: BooleanConstructor;
+} ? boolean : E extends {
+  format: 'url';
+} ? string : E extends {
+  format: (infer F)[];
+} ? F : E extends {
+  format: ArrayConstructor;
+} ? any[] : any;
+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;
+};
+//#endregion
+//#region lib/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>(): <G extends ConfigGroup<E>>(env: EnvName<E>, inputConfig: G, options?: CreateConfigOptions<E>) => ResolveConfigGroup<G> & {
+  env: EnvName<E>;
+};
+//#endregion
+//#region lib/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>(): <G extends ConfigGroup<E>>(inputConfig: G, 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.mts.map

package/dist/index.d.mts.map

@@ -0,0 +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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"}

package/dist/index.mjs

@@ -0,0 +1,190 @@
+//#region lib/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`);
+			break;
+		case Number:
+			value = Number(value);
+			if (isNaN(value)) errors.push(`Config value for ${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`);
+			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`);
+			break;
+		case "url":
+			try {
+				new URL(value);
+			} catch {
+				errors.push(`Config value for ${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(", ")}]`);
+		}
+	}
+	return value;
+}
+//#endregion
+//#region lib/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 = 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;
+			if (value === void 0 && !hasValueSource) {
+				errors.push(`No value source declared for ${fullKey}. Supply a value using environment names, "value", "processEnv", or "importMetaEnv".`);
+				continue;
+			}
+			if (value === void 0) if (configEntry.optional) {
+				value = configEntry.default;
+				if (value === void 0) {
+					output[key] = void 0;
+					continue;
+				}
+			} else {
+				errors.push(`Missing required config value for ${fullKey} in environment ${env}`);
+				continue;
+			}
+			value = validateAndCoerce(value, configEntry.format, fullKey, errors);
+			output[key] = value;
+		}
+		return output;
+	}
+	const 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;
+	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 lib/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
+export { createEnvironmentConfig, defineEnvironmentConfig };
+
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +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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"}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "konfeeg",
+  "version": "0.0.0",
+  "description": "Build a validated, strongly-typed config object, and use it everywhere.",
+  "author": "Zach Olivare <https://github.com/0livare>",
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/0livare/konfeeg"
+  },
+  "type": "module",
+  "main": "dist/index.mjs",
+  "module": "dist/index.mjs",
+  "files": [
+    "dist"
+  ],
+  "devDependencies": {
+    "prettier": "^3.8.4",
+    "tsdown": "^0.22.2",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.8"
+  },
+  "keywords": [
+    "environment",
+    "config",
+    "configuration",
+    "typescript",
+    "type-safe",
+    "validation",
+    "browser",
+    "node"
+  ],
+  "scripts": {
+    "build": "tsdown lib/index.ts",
+    "test": "vitest --run",
+    "types": "tsc",
+    "format": "prettier --write .",
+    "pr": "tsc && prettier --check . && pnpm run test && pnpm run build"
+  }
+}