@jeengbe/config 0.0.9 → 1.0.0

package/dist/env.mjs

@@ -1,54 +1,91 @@
+import { ValidationResult, arrayIncludes, collectValidationResults } from "./validation.mjs";
 import { EnvNode, ScalarEnvNode } from "./ast.mjs";
-import { arrayIncludes, combineValidationResults } from "./validation.mjs";
 import { Either } from "@jeengbe/prelude";
 
 //#region src/env.ts
 const env = {
 	string(key, defaultValue) {
-		return env.custom(key, (value) => Either.right(value), defaultValue);
+		return env.scalar(key, (value) => ValidationResult.success({
+			value,
+			defaulted: []
+		}), defaultValue);
 	},
 	number(key, defaultValue) {
-		return env.custom(key, (value) => {
-			if (/^-?\d+(?:\.\d+)?$/.test(value)) return Either.right(Number(value));
-			return Either.left(["invalid number"]);
+		return env.scalar(key, (value, path) => {
+			if (/^-?\d+(?:\.\d+)?$/.test(value)) return ValidationResult.success({
+				value: Number(value),
+				defaulted: []
+			});
+			return ValidationResult.fail({ errors: [{
+				path,
+				key,
+				message: "invalid number",
+				value
+			}] });
 		}, defaultValue);
 	},
 	boolean(key, defaultValue) {
-		return env.custom(key, (value) => {
-			if (value.toLowerCase() === "true") return Either.right(true);
-			if (value.toLowerCase() === "false") return Either.right(false);
-			return Either.left(["invalid boolean (must be 'true' or 'false')"]);
+		return env.scalar(key, (value, path) => {
+			if (value.toLowerCase() === "true") return ValidationResult.success({
+				value: true,
+				defaulted: []
+			});
+			if (value.toLowerCase() === "false") return ValidationResult.success({
+				value: false,
+				defaulted: []
+			});
+			return ValidationResult.fail({ errors: [{
+				path,
+				key,
+				message: "invalid boolean",
+				formatHint: "must be 'true' or 'false'",
+				value
+			}] });
 		}, defaultValue);
 	},
 	enum(key, values, defaultValue) {
-		return env.custom(key, (value) => {
-			if (arrayIncludes(values, value)) return Either.right(value);
-			return Either.left([`invalid enum value (must be one of: ${values.map((v) => `'${v}'`).join(", ")})`]);
+		return env.scalar(key, (value, path) => {
+			if (arrayIncludes(values, value)) return ValidationResult.success({
+				value,
+				defaulted: []
+			});
+			return ValidationResult.fail({ errors: [{
+				path,
+				key,
+				message: "invalid enum value",
+				formatHint: `must be one of: ${values.map((v) => `'${v}'`).join(", ")}`,
+				value
+			}] });
 		}, defaultValue);
 	},
-	custom(key, transform, defaultValue) {
-		return new ScalarEnvNode(key, (value) => {
-			if (value === void 0) {
-				if (defaultValue !== void 0) return Either.right(defaultValue);
-				return Either.left(["required"]);
-			}
-			return transform(value);
-		});
-	},
 	array(itemType, defaultValue) {
-		return new EnvNode((path, loadValue) => {
-			const value = loadValue(itemType.key);
+		return env.scalar(itemType.key, (value, path) => {
+			if (value === "") return ValidationResult.success({
+				value: [],
+				defaulted: []
+			});
+			return collectValidationResults(...value.split(",").map((v) => v.trim() || void 0).map((v, i) => itemType.validate((k) => k === itemType.key ? v : 			/* v8 ignore next */ void 0, `${path}.${i}`)));
+		}, defaultValue);
+	},
+	scalar(key, transform, defaultValue) {
+		return new ScalarEnvNode(key, (value, path) => {
 			if (value === void 0) {
-				if (defaultValue !== void 0) return Either.right(defaultValue);
-				return Either.left([`${itemType.key} (${path}): required`]);
+				if (defaultValue !== void 0) return ValidationResult.success({
+					value: defaultValue,
+					defaulted: [{
+						path,
+						key,
+						defaultValue
+					}]
+				});
+				return Either.left("required");
 			}
-			if (value === "") return Either.right([]);
-			return combineValidationResults(...value.split(",").map((v) => v.trim() || void 0).map((v, i) => itemType.validate(`${path}.${i}`, (k) => k === itemType.key ? v : void 0)));
+			return transform(value, path);
 		});
 	},
 	discriminate(discriminatorKey, discriminatorValueType, mapping) {
-		return new EnvNode((path, loadValue) => {
-			return discriminatorValueType.validate(path, loadValue).flatMap((discriminatorValue) => {
+		return new EnvNode((loadValue, path) => {
+			return discriminatorValueType.validate(loadValue, `${path}.${discriminatorKey}`).flatMap((discriminatorValue) => {
 				return resolveNode(path, mapping[discriminatorValue] ?? {}, loadValue).map((mappingValues) => ({
 					[discriminatorKey]: discriminatorValue,
 					...mappingValues
@@ -56,15 +93,18 @@ const env = {
 			});
 		});
 	},
-	load(spec) {
-		return resolveNode("$", spec, (key) => process.env[key]?.trim() || void 0).getOrElse((errors) => {
-			throw new Error(`Failed to load config: ${errors.join(", ")}`);
-		});
+	parse(spec, env = process.env) {
+		return resolveNode("$", spec, (key) => env[key]?.trim());
+	},
+	load(spec, env = process.env) {
+		return this.parse(spec, env).fold((failure) => {
+			throw new Error(`Environment validation failed:\n${failure.errors.map((e) => `  ${e.path} (${e.key}): ${e.message} (${[e.formatHint, `got: '${String(e.value ?? "<not provided>")}'`].filter((x) => x).join("; ")})`).join("\n")}`);
+		}, ({ value }) => value);
 	}
 };
 function resolveNode(path, spec, loadValue) {
-	if (spec instanceof EnvNode) return spec.validate(path, loadValue);
-	return combineValidationResults(...Object.entries(spec).map(([key, value]) => resolveNode(`${path}.${key}`, value, loadValue).map((v) => [key, v]))).map((entries) => Object.fromEntries(entries));
+	if (spec instanceof EnvNode) return spec.validate(loadValue, path);
+	return collectValidationResults(...Object.entries(spec).map(([key, value]) => resolveNode(`${path}.${key}`, value, loadValue).map((v) => [key, v]))).map((entries) => Object.fromEntries(entries));
 }
 
 //#endregion

package/dist/env.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"env.mjs","names":[],"sources":["../src/env.ts"],"sourcesContent":["import type { EnvSpec, InferEnvSpec, Pretty } from './ast.js';\nimport { EnvNode, ScalarEnvNode } from './ast.js';\nimport type { ValidationResult } from './validation.js';\nimport { arrayIncludes, combineValidationResults } from './validation.js';\nimport { Either } from '@jeengbe/prelude';\n\nexport interface Env {\n  string(key: string, defaultValue?: string): ScalarEnvNode<string>;\n  number(key: string, defaultValue?: number): ScalarEnvNode<number>;\n  boolean(key: string, defaultValue?: boolean): ScalarEnvNode<boolean>;\n  enum<const T extends string>(\n    key: string,\n    values: readonly T[],\n    defaultValue?: T,\n  ): ScalarEnvNode<T>;\n  custom<T>(\n    key: string,\n    transform: (value: string) => ValidationResult<T>,\n    defaultValue?: T,\n  ): ScalarEnvNode<T>;\n  array<T>(itemType: ScalarEnvNode<T>, defaultValue?: readonly T[]): EnvNode<readonly T[]>;\n  discriminate<\n    K extends string,\n    V extends string,\n    M extends Partial<Record<V, Record<string, EnvSpec>>>,\n  >(\n    discriminatorKey: K,\n    discriminatorValueType: ScalarEnvNode<V>,\n    mapping: M,\n  ): EnvNode<DiscriminatorResult<K, V, M>>;\n  load<S extends EnvSpec>(spec: S): Pretty<InferEnvSpec<S>>;\n}\n\nexport const env: Env = {\n  string(key, defaultValue) {\n    return env.custom(key, (value) => Either.right(value), defaultValue);\n  },\n\n  number(key, defaultValue) {\n    return env.custom(\n      key,\n      (value) => {\n        if (/^-?\\d+(?:\\.\\d+)?$/.test(value)) {\n          return Either.right(Number(value));\n        }\n\n        return Either.left(['invalid number']);\n      },\n      defaultValue,\n    );\n  },\n\n  boolean(key, defaultValue) {\n    return env.custom(\n      key,\n      (value) => {\n        if (value.toLowerCase() === 'true') return Either.right(true);\n        if (value.toLowerCase() === 'false') return Either.right(false);\n\n        return Either.left([\"invalid boolean (must be 'true' or 'false')\"]);\n      },\n      defaultValue,\n    );\n  },\n\n  enum(key, values, defaultValue) {\n    return env.custom(\n      key,\n      (value) => {\n        if (arrayIncludes(values, value)) return Either.right(value);\n\n        return Either.left([\n          `invalid enum value (must be one of: ${values.map((v) => `'${v}'`).join(', ')})`,\n        ]);\n      },\n      defaultValue,\n    );\n  },\n\n  custom(key, transform, defaultValue) {\n    return new ScalarEnvNode(key, (value) => {\n      if (value === undefined) {\n        if (defaultValue !== undefined) return Either.right(defaultValue);\n        return Either.left(['required']);\n      }\n\n      return transform(value);\n    });\n  },\n\n  array<T>(itemType: ScalarEnvNode<T>, defaultValue?: readonly T[]): EnvNode<readonly T[]> {\n    return new EnvNode((path, loadValue) => {\n      const value = loadValue(itemType.key);\n      if (value === undefined) {\n        if (defaultValue !== undefined) return Either.right(defaultValue);\n        return Either.left([`${itemType.key} (${path}): required`]);\n      }\n      if (value === '') return Either.right([]);\n\n      return combineValidationResults(\n        ...value\n          .split(',')\n          .map((v) => v.trim() || undefined)\n          .map((v, i) =>\n            itemType.validate(`${path}.${i}`, (k) => (k === itemType.key ? v : undefined)),\n          ),\n      );\n    });\n  },\n\n  discriminate<\n    K extends string,\n    V extends string,\n    M extends Partial<Record<V, Record<string, EnvSpec>>>,\n  >(\n    discriminatorKey: K,\n    discriminatorValueType: ScalarEnvNode<V>,\n    mapping: M,\n  ): EnvNode<DiscriminatorResult<K, V, M>> {\n    return new EnvNode((path, loadValue) => {\n      return discriminatorValueType.validate(path, loadValue).flatMap((discriminatorValue) => {\n        return resolveNode<NonNullable<M[keyof M]> | {}>(\n          path,\n          mapping[discriminatorValue] ?? {},\n          loadValue,\n        ).map(\n          (mappingValues) =>\n            ({\n              [discriminatorKey]: discriminatorValue,\n              ...mappingValues,\n            }) as DiscriminatorResult<K, V, M>,\n        );\n      });\n    });\n  },\n\n  load(spec) {\n    return resolveNode('$', spec, (key) => process.env[key]?.trim() || undefined).getOrElse(\n      (errors) => {\n        throw new Error(`Failed to load config: ${errors.join(', ')}`);\n      },\n    );\n  },\n};\n\ntype DiscriminatorResult<\n  K extends string,\n  V extends string,\n  M extends Partial<Record<V, Record<string, EnvSpec>>>,\n> = Pretty<\n  // This \"redundant\" condition is necessary to make sure that 'DiscriminatorResult' distributes over\n  // the union type V\n  V extends unknown ? Record<K, V> & InferEnvSpec<M[V] extends EnvSpec ? M[V] : {}> : never\n>;\n\nfunction resolveNode<S extends EnvSpec>(\n  path: string,\n  spec: S,\n  loadValue: (key: string) => string | undefined,\n): ValidationResult<Pretty<InferEnvSpec<S>>> {\n  if (spec instanceof EnvNode) {\n    return (spec as EnvNode<Pretty<InferEnvSpec<S>>>).validate(path, loadValue);\n  }\n\n  return combineValidationResults(\n    ...Object.entries(spec).map(([key, value]) =>\n      resolveNode(`${path}.${key}`, value, loadValue).map((v) => [key, v] as const),\n    ),\n  ).map((entries) => Object.fromEntries(entries) as Pretty<InferEnvSpec<S>>);\n}\n"],"mappings":"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"}
+{"version":3,"file":"env.mjs","names":[],"sources":["../src/env.ts"],"sourcesContent":["import type { EnvSpec, ParseEnv, Pretty, ScalarValidationResultOrEither } from './ast.js';\nimport { EnvNode, ScalarEnvNode } from './ast.js';\nimport { ValidationResult } from './validation.js';\nimport { arrayIncludes, collectValidationResults } from './validation.js';\nimport { Either } from '@jeengbe/prelude';\n\n/**\n * Type-safe configuration loader.\n *\n * @example\n *\n * ```ts\n * import { env } from '@jeengbe/config';\n *\n * const config = env.load({\n *   port: env.number('PORT', 3000),\n *   debug: env.boolean('DEBUG', false),\n *   driver: env.discriminate('driver', env.enum('DRIVER', ['memory', 'redis']), {\n *     memory: {},\n *     redis: { url: env.string('REDIS_URL') },\n *   }),\n * });\n *\n * // -> {\n * //   port: number;\n * //   debug: boolean;\n * //   driver: { driver: 'memory' } | { driver: 'redis'; url: string };\n * // }\n * ```\n *\n * Variables are read from `process.env` and trimmed before validation. Only a fully unset variable\n * falls back to a default value or fails as required - an explicitly empty value is passed through to\n * validation like any other input.\n */\nexport interface Env {\n  /**\n   * Reads a string environment variable.\n   *\n   * @example\n   *\n   * ```ts\n   * const res = env.load(env.string('API_KEY'));\n   * //    ^? string\n   *\n   * // API_KEY=abc-test -> 'abc-test'\n   * // API_KEY=123 -> '123'\n   * // API_KEY= -> ''\n   * ```\n   */\n  string(key: string, defaultValue?: string): ScalarEnvNode<string>;\n\n  /**\n   * Reads a numeric environment variable. Must match `/^-?\\d+(?:\\.\\d+)?$/`, i.e. `[-]digits[.digits]`.\n   *\n   * @example\n   *\n   * ```ts\n   * const res = env.load(env.number('PORT'));\n   * //    ^? number\n   *\n   * // PORT=3000 -> 3000\n   * // PORT=-1 -> -1\n   * // PORT=abc -> error\n   * ```\n   */\n  number(key: string, defaultValue?: number): ScalarEnvNode<number>;\n\n  /**\n   * Reads a boolean environment variable (must be 'true' or 'false').\n   *\n   * @example\n   *\n   * ```ts\n   * const res = env.load(env.boolean('DEBUG'));\n   * //    ^? boolean\n   *\n   * // DEBUG=true -> true\n   * // DEBUG=false -> false\n   * // DEBUG=abc -> error\n   * ```\n   */\n  boolean(key: string, defaultValue?: boolean): ScalarEnvNode<boolean>;\n\n  /**\n   * Reads an environment variable constrained to one of the provided values.\n   *\n   * @example\n   *\n   * ```ts\n   * const res = env.load(env.enum('DRIVER', ['memory', 'redis']));\n   * //    ^? 'memory' | 'redis'\n   *\n   * // DRIVER=memory -> 'memory'\n   * // DRIVER=abc -> error\n   * ```\n   */\n  enum<const T extends string>(\n    key: string,\n    values: readonly T[],\n    defaultValue?: T,\n  ): ScalarEnvNode<T>;\n\n  /**\n   * Reads a comma-separated list environment variable, validating each item against the provided item type.\n   *\n   * @example\n   *\n   * ```ts\n   * const res = env.load(env.array(env.string('API_KEYS')));\n   * //    ^? readonly string[]\n   *\n   * // API_KEYS=abc,def,ghi -> ['abc', 'def', 'ghi']\n   * // API_KEYS= -> []\n   * // API_KEYS=abc,,ghi -> error\n   * ```\n   *\n   * @example\n   *\n   * ```ts\n   * const res = env.load(env.array(env.string('API_KEYS'), ['default1', 'default2']));\n   * //    ^? readonly string[]\n   *\n   * // API_KEYS=abc,def,ghi -> ['abc', 'def', 'ghi']\n   * // API_KEYS= -> []\n   * // (not set) -> ['default1', 'default2']\n   * // API_KEYS=abc,,ghi -> error\n   * ```\n   *\n   * @example\n   *\n   * ```ts\n   * const res = env.load(env.array(env.string('API_KEYS').optional()));\n   * //    ^? readonly (string | undefined)[]\n   *\n   * // API_KEYS=abc,def,ghi -> ['abc', 'def', 'ghi']\n   * // API_KEYS= -> []\n   * // API_KEYS=abc,,ghi -> ['abc', undefined, 'ghi']\n   * ```\n   */\n  array<const T>(\n    itemType: ScalarEnvNode<T>,\n    defaultValue?: readonly T[],\n  ): ScalarEnvNode<readonly T[]>;\n\n  /**\n   * Reads an environment variable, validating and transforming it with the provided function.\n   *\n   * @example\n   *\n   * ```ts\n   * const res = env.load(\n   *   //  ^? string\n   *   env.scalar('TAG', (value, path) =>\n   *     value.length === 3\n   *       ? ValidationResult.success({ value, defaulted: [] })\n   *       : ValidationResult.fail({\n   *           errors: [{ path, key: 'TAG', message: 'must be 3 characters long', value }],\n   *         }),\n   *   ),\n   * );\n   *\n   * // TAG=abc -> 'abc'\n   * // TAG=abcd -> error\n   * ```\n   */\n  scalar<const T>(\n    key: string,\n    transform: (value: string, path: string) => ScalarValidationResultOrEither<T>,\n    defaultValue?: T,\n  ): ScalarEnvNode<T>;\n\n  /**\n   * Reads a discriminator environment variable and resolves the nested schema mapped to its value.\n   *\n   * @example\n   *\n   * ```ts\n   * const res = env.load(\n   *   //  ^? { driver: 'memory'; } | { driver: 'redis'; url: string; }\n   *   env.discriminate('driver', env.enum('DRIVER', ['memory', 'redis']), {\n   *     memory: {},\n   *     redis: { url: env.string('REDIS_URL') },\n   *   }),\n   * );\n   *\n   * // DRIVER=memory -> { driver: 'memory' }\n   * // DRIVER=redis, REDIS_URL=redis://localhost -> { driver: 'redis', url: 'redis://localhost' }\n   * // DRIVER=redis, REDIS_URL= -> { driver: 'redis', url: '' }\n   * // DRIVER=abc -> error\n   * ```\n   */\n  discriminate<\n    K extends string,\n    V extends string,\n    M extends Partial<Record<V, Record<string, EnvSpec>>>,\n  >(\n    discriminatorKey: K,\n    discriminatorValueType: ScalarEnvNode<V>,\n    mapping: M,\n  ): EnvNode<DiscriminatorResult<K, V, M>>;\n\n  /**\n   * Validates and loads the provided schema from `process.env`. Returns a `ValidationResult` that contains either the parsed values or a list of validation errors.\n   *\n   * @example\n   *\n   * ```ts\n   * const result = env.parse({\n   *   port: env.number('PORT'),\n   *   debug: env.boolean('DEBUG'),\n   * });\n   *\n   * if (result.getLeft()) {\n   *   console.error('Validation failed:', result.getLeft());\n   * } else {\n   *   const config = result.get()!;\n   *   // -> { port: number; debug: boolean; }\n   * }\n   * ```\n   */\n  parse<S extends EnvSpec>(spec: S, env?: NodeJS.ProcessEnv): ValidationResult<Pretty<ParseEnv<S>>>;\n\n  /**\n   * Validates and loads the provided schema from `process.env`. Throws if any required variables are missing or invalid.\n   *\n   * @example\n   *\n   * ```ts\n   * const config = env.load({\n   *   port: env.number('PORT', 3000),\n   *   debug: env.boolean('DEBUG', false),\n   * }, console.log);\n   *\n   * // -> {\n   * //   port: number;\n   * //   debug: boolean;\n   * // }\n   * ```\n   */\n  load<S extends EnvSpec>(spec: S, env?: NodeJS.ProcessEnv): Pretty<ParseEnv<S>>;\n}\n\nexport const env: Env = {\n  string(key: string, defaultValue?: string): ScalarEnvNode<string> {\n    return env.scalar(\n      key,\n      (value): ValidationResult<string> => ValidationResult.success({ value, defaulted: [] }),\n      defaultValue,\n    );\n  },\n\n  number(key: string, defaultValue?: number): ScalarEnvNode<number> {\n    return env.scalar(\n      key,\n      (value, path): ValidationResult<number> => {\n        if (/^-?\\d+(?:\\.\\d+)?$/.test(value)) {\n          return ValidationResult.success({ value: Number(value), defaulted: [] });\n        }\n\n        return ValidationResult.fail({\n          errors: [\n            {\n              path,\n              key,\n              message: 'invalid number',\n              value,\n            },\n          ],\n        });\n      },\n      defaultValue,\n    );\n  },\n\n  boolean(key: string, defaultValue?: boolean): ScalarEnvNode<boolean> {\n    return env.scalar(\n      key,\n      (value, path): ValidationResult<boolean> => {\n        if (value.toLowerCase() === 'true') {\n          return ValidationResult.success({ value: true, defaulted: [] });\n        }\n\n        if (value.toLowerCase() === 'false') {\n          return ValidationResult.success({ value: false, defaulted: [] });\n        }\n\n        return ValidationResult.fail({\n          errors: [\n            {\n              path,\n              key,\n              message: 'invalid boolean',\n              formatHint: \"must be 'true' or 'false'\",\n              value,\n            },\n          ],\n        });\n      },\n      defaultValue,\n    );\n  },\n\n  enum<const T extends string>(\n    key: string,\n    values: readonly T[],\n    defaultValue?: T,\n  ): ScalarEnvNode<T> {\n    return env.scalar(\n      key,\n      (value, path): ValidationResult<T> => {\n        if (arrayIncludes(values, value)) return ValidationResult.success({ value, defaulted: [] });\n\n        return ValidationResult.fail({\n          errors: [\n            {\n              path,\n              key,\n              message: 'invalid enum value',\n              formatHint: `must be one of: ${values.map((v) => `'${v}'`).join(', ')}`,\n              value,\n            },\n          ],\n        });\n      },\n      defaultValue,\n    );\n  },\n\n  array<const T>(\n    itemType: ScalarEnvNode<T>,\n    defaultValue?: readonly T[],\n  ): ScalarEnvNode<readonly T[]> {\n    return env.scalar(\n      itemType.key,\n      (value, path): ValidationResult<readonly T[]> => {\n        // Special case because ''.split(',') returns [''] instead of [].\n        if (value === '') return ValidationResult.success({ value: [], defaulted: [] });\n\n        return collectValidationResults(\n          ...value\n            .split(',')\n            .map((v) => v.trim() || undefined)\n            .map((v, i) =>\n              itemType.validate(\n                (k) =>\n                  // itemType always reads its own key, so this is never false\n                  k === itemType.key ? v : /* v8 ignore next */ undefined,\n                `${path}.${i}`,\n              ),\n            ),\n        );\n      },\n      defaultValue,\n    );\n  },\n\n  scalar<T>(\n    key: string,\n    transform: (value: string, path: string) => ScalarValidationResultOrEither<T>,\n    defaultValue?: T,\n  ): ScalarEnvNode<T> {\n    return new ScalarEnvNode(key, (value, path): ScalarValidationResultOrEither<T> => {\n      if (value === undefined) {\n        if (defaultValue !== undefined) {\n          return ValidationResult.success({\n            value: defaultValue,\n            defaulted: [\n              {\n                path,\n                key,\n                defaultValue,\n              },\n            ],\n          });\n        }\n\n        return Either.left('required');\n      }\n\n      return transform(value, path);\n    });\n  },\n\n  discriminate<\n    K extends string,\n    V extends string,\n    M extends Partial<Record<V, Record<string, EnvSpec>>>,\n  >(\n    discriminatorKey: K,\n    discriminatorValueType: ScalarEnvNode<V>,\n    mapping: M,\n  ): EnvNode<DiscriminatorResult<K, V, M>> {\n    return new EnvNode((loadValue, path): ValidationResult<DiscriminatorResult<K, V, M>> => {\n      return discriminatorValueType\n        .validate(loadValue, `${path}.${discriminatorKey}`)\n        .flatMap((discriminatorValue) => {\n          return resolveNode<NonNullable<M[keyof M]> | {}>(\n            path,\n            mapping[discriminatorValue] ?? {},\n            loadValue,\n          ).map(\n            (mappingValues) =>\n              ({\n                [discriminatorKey]: discriminatorValue,\n                ...mappingValues,\n              }) as DiscriminatorResult<K, V, M>,\n          );\n        });\n    });\n  },\n\n  parse<S extends EnvSpec>(spec: S, env = process.env): ValidationResult<Pretty<ParseEnv<S>>> {\n    return resolveNode('$', spec, (key) => env[key]?.trim());\n  },\n\n  load<S extends EnvSpec>(spec: S, env = process.env): Pretty<ParseEnv<S>> {\n    return this.parse(spec, env).fold(\n      (failure) => {\n        throw new Error(\n          `Environment validation failed:\\n${failure.errors\n            .map(\n              (e) =>\n                // oxlint-disable-next-line typescript/no-base-to-string\n                `  ${e.path} (${e.key}): ${e.message} (${[e.formatHint, `got: '${String(e.value ?? '<not provided>')}'`].filter((x) => x).join('; ')})`,\n            )\n            .join('\\n')}`,\n        );\n      },\n      ({ value }) => value,\n    );\n  },\n};\n\ntype DiscriminatorResult<\n  K extends string,\n  V extends string,\n  M extends Partial<Record<V, Record<string, EnvSpec>>>,\n> = Pretty<\n  // This \"redundant\" condition is necessary to make sure that 'DiscriminatorResult' distributes over\n  // the union type V\n  V extends unknown ? Record<K, V> & ParseEnv<M[V] extends EnvSpec ? M[V] : {}> : never\n>;\n\nfunction resolveNode<S extends EnvSpec>(\n  path: string,\n  spec: S,\n  loadValue: (key: string) => string | undefined,\n): ValidationResult<Pretty<ParseEnv<S>>> {\n  if (spec instanceof EnvNode) {\n    return (spec as EnvNode<Pretty<ParseEnv<S>>>).validate(loadValue, path);\n  }\n\n  return collectValidationResults(\n    ...Object.entries(spec).map(([key, value]) =>\n      resolveNode(`${path}.${key}`, value, loadValue).map((v) => [key, v] as const),\n    ),\n  ).map((entries) => Object.fromEntries(entries) as Pretty<ParseEnv<S>>);\n}\n"],"mappings":"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"}

package/dist/if-enabled.d.mts

@@ -1,11 +1,22 @@
-import { EnvNode, EnvSpec, InferEnvSpec } from "./ast.mjs";
+import { EnvNode, EnvSpec, ParseEnv } from "./ast.mjs";
 //#region src/if-enabled.d.ts
 type IfEnabled<T> = ({
   enabled: true;
 } & Omit<T, 'enabled'>) | {
   enabled: false;
 };
-declare function ifEnabled<T extends Record<string, EnvSpec>>(envVar: string, config: T, defaultEnabled?: boolean): EnvNode<IfEnabled<InferEnvSpec<T>>>;
+/**
+ * Wraps a config schema behind an `enabled` boolean flag read from `envVar`. When disabled, none of the
+ * nested schema's environment variables are validated or required.
+ *
+ * @example
+ *
+ * ```ts
+ * ifEnabled('FEATURE_X', { apiKey: env.string('FEATURE_X_API_KEY') });
+ * // -> { enabled: true; apiKey: string } | { enabled: false }
+ * ```
+ */
+declare function ifEnabled<T extends Record<string, EnvSpec>>(envVar: string, config: T, defaultEnabled?: boolean): EnvNode<IfEnabled<ParseEnv<T>>>;
 //#endregion
 export { ifEnabled };
 //# sourceMappingURL=if-enabled.d.mts.map

package/dist/if-enabled.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"if-enabled.d.mts","names":[],"sources":["../src/if-enabled.ts"],"mappings":";;KAKK,UAAU;EAET;IACE,KAAK;EACP;;iBAEU,UAAU,UAAU,eAAe,UACjD,gBACA,QAAQ,GACR,2BACC,QAAQ,UAAU,aAAa"}
+{"version":3,"file":"if-enabled.d.mts","names":[],"sources":["../src/if-enabled.ts"],"mappings":";;KAIK,UAAU;EAET;IACE,KAAK;EACP;;;;;;;;;;;;;iBAaU,UAAU,UAAU,eAAe,UACjD,gBACA,QAAQ,GACR,2BACC,QAAQ,UAAU,SAAS"}

package/dist/if-enabled.mjs

@@ -2,6 +2,17 @@ import { env } from "./env.mjs";
 import { Either } from "@jeengbe/prelude";
 
 //#region src/if-enabled.ts
+/**
+* Wraps a config schema behind an `enabled` boolean flag read from `envVar`. When disabled, none of the
+* nested schema's environment variables are validated or required.
+*
+* @example
+*
+* ```ts
+* ifEnabled('FEATURE_X', { apiKey: env.string('FEATURE_X_API_KEY') });
+* // -> { enabled: true; apiKey: string } | { enabled: false }
+* ```
+*/
 function ifEnabled(envVar, config, defaultEnabled = false) {
 	return env.discriminate("enabled", env.boolean(envVar, defaultEnabled).transform((v) => Either.right(v ? "enabled" : "disabled")), { enabled: config }).transform((value) => {
 		if (value.enabled === "enabled") return Either.right({

package/dist/if-enabled.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"if-enabled.mjs","names":[],"sources":["../src/if-enabled.ts"],"sourcesContent":["import type { EnvNode, EnvSpec, InferEnvSpec } from './ast.js';\nimport { env } from './env.js';\nimport type { ValidationResult } from './validation.js';\nimport { Either } from '@jeengbe/prelude';\n\ntype IfEnabled<T> =\n  | ({\n      enabled: true;\n    } & Omit<T, 'enabled'>)\n  | { enabled: false };\n\nexport function ifEnabled<T extends Record<string, EnvSpec>>(\n  envVar: string,\n  config: T,\n  defaultEnabled = false,\n): EnvNode<IfEnabled<InferEnvSpec<T>>> {\n  // Since discriminate only works with string values, we need to bridge 'true' -> 'enabled' -> true\n  return env\n    .discriminate(\n      'enabled',\n      env\n        .boolean(envVar, defaultEnabled)\n        .transform(\n          (v): ValidationResult<'enabled' | 'disabled'> => Either.right(v ? 'enabled' : 'disabled'),\n        ),\n      {\n        enabled: config,\n      },\n    )\n    .transform((value): ValidationResult<IfEnabled<InferEnvSpec<T>>> => {\n      if (value.enabled === 'enabled') {\n        return Either.right({\n          ...value,\n          enabled: true,\n        });\n      }\n\n      return Either.right({\n        enabled: false,\n      });\n    });\n}\n"],"mappings":";;;;AAWA,SAAgB,UACd,QACA,QACA,iBAAiB,OACoB;CAErC,OAAO,IACJ,aACC,WACA,IACG,QAAQ,QAAQ,cAAc,CAAC,CAC/B,WACE,MAAgD,OAAO,MAAM,IAAI,YAAY,UAAU,CAC1F,GACF,EACE,SAAS,OACX,CACF,CAAC,CACA,WAAW,UAAwD;EAClE,IAAI,MAAM,YAAY,WACpB,OAAO,OAAO,MAAM;GAClB,GAAG;GACH,SAAS;EACX,CAAC;EAGH,OAAO,OAAO,MAAM,EAClB,SAAS,MACX,CAAC;CACH,CAAC;AACL"}
+{"version":3,"file":"if-enabled.mjs","names":[],"sources":["../src/if-enabled.ts"],"sourcesContent":["import type { EnvNode, EnvSpec, ParseEnv } from './ast.js';\nimport { env } from './env.js';\nimport { Either } from '@jeengbe/prelude';\n\ntype IfEnabled<T> =\n  | ({\n      enabled: true;\n    } & Omit<T, 'enabled'>)\n  | { enabled: false };\n\n/**\n * Wraps a config schema behind an `enabled` boolean flag read from `envVar`. When disabled, none of the\n * nested schema's environment variables are validated or required.\n *\n * @example\n *\n * ```ts\n * ifEnabled('FEATURE_X', { apiKey: env.string('FEATURE_X_API_KEY') });\n * // -> { enabled: true; apiKey: string } | { enabled: false }\n * ```\n */\nexport function ifEnabled<T extends Record<string, EnvSpec>>(\n  envVar: string,\n  config: T,\n  defaultEnabled = false,\n): EnvNode<IfEnabled<ParseEnv<T>>> {\n  // Since discriminate only works with string values, we need to bridge 'true' -> 'enabled' -> true\n  return env\n    .discriminate(\n      'enabled',\n      env\n        .boolean(envVar, defaultEnabled)\n        .transform<'enabled' | 'disabled'>((v) => Either.right(v ? 'enabled' : 'disabled')),\n      {\n        enabled: config,\n      },\n    )\n    .transform((value): Either<never, IfEnabled<ParseEnv<T>>> => {\n      if (value.enabled === 'enabled') {\n        return Either.right({\n          ...value,\n          enabled: true,\n        });\n      }\n\n      return Either.right({\n        enabled: false,\n      });\n    });\n}\n"],"mappings":";;;;;;;;;;;;;;;AAqBA,SAAgB,UACd,QACA,QACA,iBAAiB,OACgB;CAEjC,OAAO,IACJ,aACC,WACA,IACG,QAAQ,QAAQ,cAAc,CAAC,CAC/B,WAAmC,MAAM,OAAO,MAAM,IAAI,YAAY,UAAU,CAAC,GACpF,EACE,SAAS,OACX,CACF,CAAC,CACA,WAAW,UAAiD;EAC3D,IAAI,MAAM,YAAY,WACpB,OAAO,OAAO,MAAM;GAClB,GAAG;GACH,SAAS;EACX,CAAC;EAGH,OAAO,OAAO,MAAM,EAClB,SAAS,MACX,CAAC;CACH,CAAC;AACL"}

package/dist/index.d.mts

@@ -1,4 +1,5 @@
-import { EnvNode, EnvSpec, InferEnvSpec } from "./ast.mjs";
+import { ValidationDefaulted, ValidationError, ValidationFailure, ValidationResult, ValidationSuccess, collectValidationResults } from "./validation.mjs";
+import { EnvNode, EnvSpec, ParseEnv, ScalarEnvNode } from "./ast.mjs";
 import { env } from "./env.mjs";
 import { ifEnabled } from "./if-enabled.mjs";
-export { type EnvNode, type EnvSpec, type InferEnvSpec, env, ifEnabled };
+export { type EnvNode, type EnvSpec, type ParseEnv, type ScalarEnvNode, type ValidationDefaulted, type ValidationError, type ValidationFailure, ValidationResult, type ValidationSuccess, collectValidationResults, env, ifEnabled };

package/dist/index.mjs

@@ -1,4 +1,5 @@
+import { ValidationResult, collectValidationResults } from "./validation.mjs";
 import { env } from "./env.mjs";
 import { ifEnabled } from "./if-enabled.mjs";
 
-export { env, ifEnabled };
+export { ValidationResult, collectValidationResults, env, ifEnabled };

package/dist/validation.d.mts

@@ -1,9 +1,106 @@
-import { Either } from "@jeengbe/prelude";
+import { Maybe } from "@jeengbe/prelude";
 //#region src/validation.d.ts
-type ValidationResult<T> = Either<readonly string[], T>;
-type CombineValidationResult<T extends readonly ValidationResult<unknown>[]> = ValidationResult<{ [K in keyof T]: T[K] extends ValidationResult<infer U> ? U : never; }>;
-declare function combineValidationResults<const U extends readonly ValidationResult<unknown>[]>(...results: U): CombineValidationResult<U>;
-declare function arrayIncludes<const T extends string>(arr: readonly T[], val: unknown): val is T;
+/**
+ * The result of validating a config value: a Left of accumulated structured errors, or a Right of the
+ * validated value together with a log of every default value that was substituted along the way.
+ *
+ * `map` and `flatMap` behave like a regular value monad, except that `flatMap` also concatenates the
+ * defaulted-key log of both sides instead of discarding either - so chaining validations never loses
+ * track of which defaults were applied upstream.
+ */
+declare class ValidationResult<T> {
+  private readonly result;
+  private constructor();
+  /**
+   * Creates a successful ValidationResult with the given value and log of defaulted keys.
+   */
+  static success<T>(success: ValidationSuccess<T>): ValidationResult<T>;
+  /**
+   * Creates a failed ValidationResult with the given errors.
+   */
+  static fail(failure: ValidationFailure): ValidationResult<never>;
+  /**
+   * Maps the value of this ValidationResult if it succeeded, preserving its defaulted-key log. Performs
+   * no operation if this is a failure.
+   */
+  map<U>(f: (value: T) => U): ValidationResult<U>;
+  /**
+   * Flat maps the value of this ValidationResult if it succeeded, concatenating the defaulted-key log of
+   * this result with that of the one returned by `f`. Performs no operation if this is a failure.
+   */
+  flatMap<U>(f: (value: T) => ValidationResult<U>): ValidationResult<U>;
+  /**
+   * Applies the provided functions to this ValidationResult, depending on whether it failed or succeeded,
+   * and returns the result.
+   */
+  fold<R1, R2>(onFailure: (failure: ValidationFailure) => R1, onSuccess: (success: ValidationSuccess<T>) => R2): R1 | R2;
+  getLeft(): Maybe<ValidationFailure>;
+  get(): Maybe<T>;
+}
+interface ValidationFailure {
+  errors: readonly ValidationError[];
+}
+/**
+ * A single structured validation error, pinpointing the key and path it occurred at.
+ */
+interface ValidationError {
+  path: string;
+  key: string;
+  message: string;
+  formatHint?: string;
+  value: unknown;
+}
+interface ValidationSuccess<T> {
+  defaulted: readonly ValidationDefaulted[];
+  value: T;
+}
+/**
+ * Records that a default value was substituted in place of a missing environment variable.
+ */
+interface ValidationDefaulted {
+  path: string;
+  key: string;
+  defaultValue: unknown;
+}
+/**
+ * Combines multiple ValidationResults into one, preserving the tuple's value types. Succeeds with all
+ * values and the concatenation of every branch's defaulted-key log if every result succeeded, or fails
+ * with all accumulated errors otherwise.
+ *
+ * @example
+ *
+ * ```ts
+ * const result1: ValidationResult<number> = ValidationResult.fail({
+ *   errors: [{ path: '$.a', key: 'A', message: 'error1', value: undefined }],
+ * });
+ * const result2: ValidationResult<string> = ValidationResult.success({ value: 'value2', defaulted: [] });
+ * const result3: ValidationResult<boolean> = ValidationResult.fail({
+ *   errors: [{ path: '$.c', key: 'C', message: 'error3', value: undefined }],
+ * });
+ *
+ * const combinedResult = collectValidationResults(result1, result2, result3);
+ *
+ * console.log(combinedResult); // Left with both `error1` and `error3`
+ * ```
+ *
+ * @example
+ *
+ * ```ts
+ * const result1: ValidationResult<number> = ValidationResult.success({ value: 42, defaulted: [] });
+ * const result2: ValidationResult<string> = ValidationResult.success({ value: 'value2', defaulted: [] });
+ * const result3: ValidationResult<boolean> = ValidationResult.success({ value: true, defaulted: [] });
+ *
+ * const combinedResult = collectValidationResults(result1, result2, result3);
+ *
+ * console.log(combinedResult); // Right([42, 'value2', true])
+ * ```
+ */
+declare function collectValidationResults<const U extends readonly ValidationResult<unknown>[]>(...results: U): CollectValidationResult<U>;
+type CollectValidationResult<T extends readonly ValidationResult<unknown>[]> = ValidationResult<{ [K in keyof T]: T[K] extends ValidationResult<infer U> ? U : never; }>;
+/**
+ * Type guard checking whether val is one of the values in arr.
+ */
+declare function arrayIncludes<const T extends string | number | boolean | null | undefined>(arr: readonly T[], val: unknown): val is T;
 //#endregion
-export { ValidationResult, arrayIncludes, combineValidationResults };
+export { ValidationDefaulted, ValidationError, ValidationFailure, ValidationResult, ValidationSuccess, arrayIncludes, collectValidationResults };
 //# sourceMappingURL=validation.d.mts.map

package/dist/validation.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"validation.d.mts","names":[],"sources":["../src/validation.ts"],"mappings":";;KAEY,iBAAiB,KAAK,0BAA0B;KAEvD,wBAAwB,mBAAmB,+BAA+B,oBAC5E,WAAW,IAAI,EAAE,WAAW,uBAAuB,KAAK;iBAG3C,+BAA+B,mBAAmB,gCAC7D,SAAS,IACX,wBAAwB;iBAQX,oBAAoB,kBAAkB,cAAc,KAAK,eAAe,OAAO"}
+{"version":3,"file":"validation.d.mts","names":[],"sources":["../src/validation.ts"],"mappings":";;;;;;;;;;cAUa,iBAAiB;mBACS;UAA9B;;;;SAKA,QAAQ,GAAG,SAAS,kBAAkB,KAAK,iBAAiB;;;;SAO5D,KAAK,SAAS,oBAAoB;;;;;EAQzC,IAAI,GAAG,IAAI,OAAO,MAAM,IAAI,iBAAiB;;;;;EAU7C,QAAQ,GAAG,IAAI,OAAO,MAAM,iBAAiB,KAAK,iBAAiB;;;;;EAenE,KAAK,IAAI,IACP,YAAY,SAAS,sBAAsB,IAC3C,YAAY,SAAS,kBAAkB,OAAO,KAC7C,KAAK;EAIR,WAAW,MAAM;EAIjB,OAAO,MAAM;;UAKE;EACf,iBAAiB;;;;;UAMF;EACf;EACA;EACA;EACA;EACA;;UAGe,kBAAkB;EACjC,oBAAoB;EACpB,OAAO;;;;;UAMQ;EACf;EACA;EACA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAoCc,+BAA+B,mBAAmB,gCAC7D,SAAS,IACX,wBAAwB;KAsBtB,wBAAwB,mBAAmB,+BAA+B,oBAC5E,WAAW,IAAI,EAAE,WAAW,uBAAuB,KAAK;;;;iBAM3C,oBAAoB,wDAClC,cAAc,KACd,eACC,OAAO"}

package/dist/validation.mjs

@@ -1,14 +1,118 @@
-import { Either } from "@jeengbe/prelude";
+import { Either, mapMaybe } from "@jeengbe/prelude";
 
 //#region src/validation.ts
-function combineValidationResults(...results) {
-	const errors = results.filter((r) => r.isLeft()).flatMap((r) => r.getLeft());
-	return errors.length ? Either.left(errors) : Either.right(results.map((r) => r.get()));
+/**
+* The result of validating a config value: a Left of accumulated structured errors, or a Right of the
+* validated value together with a log of every default value that was substituted along the way.
+*
+* `map` and `flatMap` behave like a regular value monad, except that `flatMap` also concatenates the
+* defaulted-key log of both sides instead of discarding either - so chaining validations never loses
+* track of which defaults were applied upstream.
+*/
+var ValidationResult = class ValidationResult {
+	result;
+	constructor(result) {
+		this.result = result;
+	}
+	/**
+	* Creates a successful ValidationResult with the given value and log of defaulted keys.
+	*/
+	static success(success) {
+		return new ValidationResult(Either.right(success));
+	}
+	/**
+	* Creates a failed ValidationResult with the given errors.
+	*/
+	static fail(failure) {
+		return new ValidationResult(Either.left(failure));
+	}
+	/**
+	* Maps the value of this ValidationResult if it succeeded, preserving its defaulted-key log. Performs
+	* no operation if this is a failure.
+	*/
+	map(f) {
+		return new ValidationResult(this.result.map(({ defaulted, value }) => ({
+			defaulted,
+			value: f(value)
+		})));
+	}
+	/**
+	* Flat maps the value of this ValidationResult if it succeeded, concatenating the defaulted-key log of
+	* this result with that of the one returned by `f`. Performs no operation if this is a failure.
+	*/
+	flatMap(f) {
+		return new ValidationResult(this.result.flatMap(({ defaulted, value }) => f(value).result.map(({ defaulted: newDefaulted, value: newValue }) => ({
+			defaulted: [...defaulted, ...newDefaulted],
+			value: newValue
+		}))));
+	}
+	/**
+	* Applies the provided functions to this ValidationResult, depending on whether it failed or succeeded,
+	* and returns the result.
+	*/
+	fold(onFailure, onSuccess) {
+		return this.result.fold(onFailure, onSuccess);
+	}
+	getLeft() {
+		return this.result.getLeft();
+	}
+	get() {
+		return mapMaybe(this.result.get(), ({ value }) => value);
+	}
+};
+/**
+* Combines multiple ValidationResults into one, preserving the tuple's value types. Succeeds with all
+* values and the concatenation of every branch's defaulted-key log if every result succeeded, or fails
+* with all accumulated errors otherwise.
+*
+* @example
+*
+* ```ts
+* const result1: ValidationResult<number> = ValidationResult.fail({
+*   errors: [{ path: '$.a', key: 'A', message: 'error1', value: undefined }],
+* });
+* const result2: ValidationResult<string> = ValidationResult.success({ value: 'value2', defaulted: [] });
+* const result3: ValidationResult<boolean> = ValidationResult.fail({
+*   errors: [{ path: '$.c', key: 'C', message: 'error3', value: undefined }],
+* });
+*
+* const combinedResult = collectValidationResults(result1, result2, result3);
+*
+* console.log(combinedResult); // Left with both `error1` and `error3`
+* ```
+*
+* @example
+*
+* ```ts
+* const result1: ValidationResult<number> = ValidationResult.success({ value: 42, defaulted: [] });
+* const result2: ValidationResult<string> = ValidationResult.success({ value: 'value2', defaulted: [] });
+* const result3: ValidationResult<boolean> = ValidationResult.success({ value: true, defaulted: [] });
+*
+* const combinedResult = collectValidationResults(result1, result2, result3);
+*
+* console.log(combinedResult); // Right([42, 'value2', true])
+* ```
+*/
+function collectValidationResults(...results) {
+	const errors = [];
+	const defaulted = [];
+	const values = [];
+	for (const result of results) result.fold((failure) => errors.push(...failure.errors), (success) => {
+		defaulted.push(...success.defaulted);
+		values.push(success.value);
+	});
+	return errors.length ? ValidationResult.fail({ errors }) : ValidationResult.success({
+		defaulted,
+		value: values
+	});
 }
+/**
+* Type guard checking whether val is one of the values in arr.
+*/
 function arrayIncludes(arr, val) {
 	return arr.includes(val);
 }
 
 //#endregion
-export { arrayIncludes, combineValidationResults };
+export { ValidationResult, arrayIncludes, collectValidationResults };
 //# sourceMappingURL=validation.mjs.map

package/dist/validation.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"validation.mjs","names":[],"sources":["../src/validation.ts"],"sourcesContent":["import { Either } from '@jeengbe/prelude';\n\nexport type ValidationResult<T> = Either<readonly string[], T>;\n\ntype CombineValidationResult<T extends readonly ValidationResult<unknown>[]> = ValidationResult<{\n  [K in keyof T]: T[K] extends ValidationResult<infer U> ? U : never;\n}>;\n\nexport function combineValidationResults<const U extends readonly ValidationResult<unknown>[]>(\n  ...results: U\n): CombineValidationResult<U> {\n  const errors = results.filter((r) => r.isLeft()).flatMap((r) => r.getLeft());\n\n  return errors.length\n    ? Either.left(errors)\n    : (Either.right(results.map((r) => r.get())) as CombineValidationResult<U>);\n}\n\nexport function arrayIncludes<const T extends string>(arr: readonly T[], val: unknown): val is T {\n  return arr.includes(val as T);\n}\n"],"mappings":";;;AAQA,SAAgB,yBACd,GAAG,SACyB;CAC5B,MAAM,SAAS,QAAQ,QAAQ,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,SAAS,MAAM,EAAE,QAAQ,CAAC;CAE3E,OAAO,OAAO,SACV,OAAO,KAAK,MAAM,IACjB,OAAO,MAAM,QAAQ,KAAK,MAAM,EAAE,IAAI,CAAC,CAAC;AAC/C;AAEA,SAAgB,cAAsC,KAAmB,KAAwB;CAC/F,OAAO,IAAI,SAAS,GAAQ;AAC9B"}
+{"version":3,"file":"validation.mjs","names":[],"sources":["../src/validation.ts"],"sourcesContent":["import { Either, mapMaybe, Maybe } from '@jeengbe/prelude';\n\n/**\n * The result of validating a config value: a Left of accumulated structured errors, or a Right of the\n * validated value together with a log of every default value that was substituted along the way.\n *\n * `map` and `flatMap` behave like a regular value monad, except that `flatMap` also concatenates the\n * defaulted-key log of both sides instead of discarding either - so chaining validations never loses\n * track of which defaults were applied upstream.\n */\nexport class ValidationResult<T> {\n  private constructor(private readonly result: Either<ValidationFailure, ValidationSuccess<T>>) {}\n\n  /**\n   * Creates a successful ValidationResult with the given value and log of defaulted keys.\n   */\n  static success<T>(success: ValidationSuccess<T>): ValidationResult<T> {\n    return new ValidationResult(Either.right(success));\n  }\n\n  /**\n   * Creates a failed ValidationResult with the given errors.\n   */\n  static fail(failure: ValidationFailure): ValidationResult<never> {\n    return new ValidationResult(Either.left(failure));\n  }\n\n  /**\n   * Maps the value of this ValidationResult if it succeeded, preserving its defaulted-key log. Performs\n   * no operation if this is a failure.\n   */\n  map<U>(f: (value: T) => U): ValidationResult<U> {\n    return new ValidationResult(\n      this.result.map(({ defaulted, value }) => ({ defaulted, value: f(value) })),\n    );\n  }\n\n  /**\n   * Flat maps the value of this ValidationResult if it succeeded, concatenating the defaulted-key log of\n   * this result with that of the one returned by `f`. Performs no operation if this is a failure.\n   */\n  flatMap<U>(f: (value: T) => ValidationResult<U>): ValidationResult<U> {\n    return new ValidationResult(\n      this.result.flatMap(({ defaulted, value }) =>\n        f(value).result.map(({ defaulted: newDefaulted, value: newValue }) => ({\n          defaulted: [...defaulted, ...newDefaulted],\n          value: newValue,\n        })),\n      ),\n    );\n  }\n\n  /**\n   * Applies the provided functions to this ValidationResult, depending on whether it failed or succeeded,\n   * and returns the result.\n   */\n  fold<R1, R2>(\n    onFailure: (failure: ValidationFailure) => R1,\n    onSuccess: (success: ValidationSuccess<T>) => R2,\n  ): R1 | R2 {\n    return this.result.fold(onFailure, onSuccess);\n  }\n\n  getLeft(): Maybe<ValidationFailure> {\n    return this.result.getLeft();\n  }\n\n  get(): Maybe<T> {\n    return mapMaybe(this.result.get(), ({ value }) => value);\n  }\n}\n\nexport interface ValidationFailure {\n  errors: readonly ValidationError[];\n}\n\n/**\n * A single structured validation error, pinpointing the key and path it occurred at.\n */\nexport interface ValidationError {\n  path: string;\n  key: string;\n  message: string;\n  formatHint?: string;\n  value: unknown;\n}\n\nexport interface ValidationSuccess<T> {\n  defaulted: readonly ValidationDefaulted[];\n  value: T;\n}\n\n/**\n * Records that a default value was substituted in place of a missing environment variable.\n */\nexport interface ValidationDefaulted {\n  path: string;\n  key: string;\n  defaultValue: unknown;\n}\n\n/**\n * Combines multiple ValidationResults into one, preserving the tuple's value types. Succeeds with all\n * values and the concatenation of every branch's defaulted-key log if every result succeeded, or fails\n * with all accumulated errors otherwise.\n *\n * @example\n *\n * ```ts\n * const result1: ValidationResult<number> = ValidationResult.fail({\n *   errors: [{ path: '$.a', key: 'A', message: 'error1', value: undefined }],\n * });\n * const result2: ValidationResult<string> = ValidationResult.success({ value: 'value2', defaulted: [] });\n * const result3: ValidationResult<boolean> = ValidationResult.fail({\n *   errors: [{ path: '$.c', key: 'C', message: 'error3', value: undefined }],\n * });\n *\n * const combinedResult = collectValidationResults(result1, result2, result3);\n *\n * console.log(combinedResult); // Left with both `error1` and `error3`\n * ```\n *\n * @example\n *\n * ```ts\n * const result1: ValidationResult<number> = ValidationResult.success({ value: 42, defaulted: [] });\n * const result2: ValidationResult<string> = ValidationResult.success({ value: 'value2', defaulted: [] });\n * const result3: ValidationResult<boolean> = ValidationResult.success({ value: true, defaulted: [] });\n *\n * const combinedResult = collectValidationResults(result1, result2, result3);\n *\n * console.log(combinedResult); // Right([42, 'value2', true])\n * ```\n */\nexport function collectValidationResults<const U extends readonly ValidationResult<unknown>[]>(\n  ...results: U\n): CollectValidationResult<U> {\n  const errors: ValidationError[] = [];\n  const defaulted: ValidationDefaulted[] = [];\n  const values: unknown[] = [];\n\n  for (const result of results) {\n    result.fold(\n      (failure) => errors.push(...failure.errors),\n      (success) => {\n        defaulted.push(...success.defaulted);\n        values.push(success.value);\n      },\n    );\n  }\n\n  return (\n    errors.length\n      ? ValidationResult.fail({ errors })\n      : ValidationResult.success({ defaulted, value: values })\n  ) as CollectValidationResult<U>;\n}\n\ntype CollectValidationResult<T extends readonly ValidationResult<unknown>[]> = ValidationResult<{\n  [K in keyof T]: T[K] extends ValidationResult<infer U> ? U : never;\n}>;\n\n/**\n * Type guard checking whether val is one of the values in arr.\n */\nexport function arrayIncludes<const T extends string | number | boolean | null | undefined>(\n  arr: readonly T[],\n  val: unknown,\n): val is T {\n  return arr.includes(val as T);\n}\n"],"mappings":";;;;;;;;;;;AAUA,IAAa,mBAAb,MAAa,iBAAoB;CACM;CAArC,AAAQ,YAAY,AAAiB,QAAyD;EAAzD;CAA0D;;;;CAK/F,OAAO,QAAW,SAAoD;EACpE,OAAO,IAAI,iBAAiB,OAAO,MAAM,OAAO,CAAC;CACnD;;;;CAKA,OAAO,KAAK,SAAqD;EAC/D,OAAO,IAAI,iBAAiB,OAAO,KAAK,OAAO,CAAC;CAClD;;;;;CAMA,IAAO,GAAyC;EAC9C,OAAO,IAAI,iBACT,KAAK,OAAO,KAAK,EAAE,WAAW,aAAa;GAAE;GAAW,OAAO,EAAE,KAAK;EAAE,EAAE,CAC5E;CACF;;;;;CAMA,QAAW,GAA2D;EACpE,OAAO,IAAI,iBACT,KAAK,OAAO,SAAS,EAAE,WAAW,YAChC,EAAE,KAAK,CAAC,CAAC,OAAO,KAAK,EAAE,WAAW,cAAc,OAAO,gBAAgB;GACrE,WAAW,CAAC,GAAG,WAAW,GAAG,YAAY;GACzC,OAAO;EACT,EAAE,CACJ,CACF;CACF;;;;;CAMA,KACE,WACA,WACS;EACT,OAAO,KAAK,OAAO,KAAK,WAAW,SAAS;CAC9C;CAEA,UAAoC;EAClC,OAAO,KAAK,OAAO,QAAQ;CAC7B;CAEA,MAAgB;EACd,OAAO,SAAS,KAAK,OAAO,IAAI,IAAI,EAAE,YAAY,KAAK;CACzD;AACF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgEA,SAAgB,yBACd,GAAG,SACyB;CAC5B,MAAM,SAA4B,CAAC;CACnC,MAAM,YAAmC,CAAC;CAC1C,MAAM,SAAoB,CAAC;CAE3B,KAAK,MAAM,UAAU,SACnB,OAAO,MACJ,YAAY,OAAO,KAAK,GAAG,QAAQ,MAAM,IACzC,YAAY;EACX,UAAU,KAAK,GAAG,QAAQ,SAAS;EACnC,OAAO,KAAK,QAAQ,KAAK;CAC3B,CACF;CAGF,OACE,OAAO,SACH,iBAAiB,KAAK,EAAE,OAAO,CAAC,IAChC,iBAAiB,QAAQ;EAAE;EAAW,OAAO;CAAO,CAAC;AAE7D;;;;AASA,SAAgB,cACd,KACA,KACU;CACV,OAAO,IAAI,SAAS,GAAQ;AAC9B"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jeengbe/config",
-  "version": "0.0.9",
+  "version": "1.0.0",
   "description": "A declarative, strongly typed schema for parsing and validating environment variables in TypeScript.",
   "keywords": [
     "config",
@@ -33,6 +33,10 @@
     ".": {
       "types": "./dist/index.d.mts",
       "default": "./dist/index.mjs"
+    },
+    "./validation": {
+      "types": "./dist/validation.d.mts",
+      "default": "./dist/validation.mjs"
     }
   },
   "main": "./dist/index.mjs",
@@ -45,7 +49,7 @@
     "!src/**/fake.ts"
   ],
   "dependencies": {
-    "@jeengbe/prelude": "0.1.3"
+    "@jeengbe/prelude": "0.1.4"
   },
   "devDependencies": {
     "oxfmt": "^0.60.0",