@jeengbe/config 0.0.9 → 1.0.1

package/README.md

@@ -16,6 +16,17 @@ Define your environment variables once as a schema, and get back a plain, fully
 
 The package is published to [npm](https://www.npmjs.com/package/@jeengbe/config) and [JSR](https://jsr.io/@jeengbe/config) as `@jeengbe/config`. Versions follow Semantic Versioning.
 
+```bash
+npm install @jeengbe/config
+```
+
+```bash
+pnpm add @jeengbe/config
+yarn add @jeengbe/config
+bun add @jeengbe/config
+deno add jsr:@jeengbe/config
+```
+
 ## Usage
 
 ### Defining and loading a schema
@@ -60,15 +71,15 @@ const config = env.load({
 
 Without a `defaultValue`, all of these are required and fail validation when the variable is missing.
 
-### Custom scalars (`env.custom`)
+### Custom scalars (`env.scalar`)
 
-For anything else, write your own parser with `env.custom`. It returns a `ValidationResult<T>` (an `Either<readonly string[], T>` from `@jeengbe/prelude`):
+For anything else, write your own parser with `env.scalar`. It returns a `ValidationResult<T>` (an `Either<readonly string[], T>` from `@jeengbe/prelude`):
 
 ```ts
 import { env } from '@jeengbe/config';
 import { Either } from '@jeengbe/prelude';
 
-const apiUrl = env.custom('API_URL', (value) => {
+const apiUrl = env.scalar('API_URL', (value) => {
   try {
     return Either.right(new URL(value));
   } catch {
@@ -134,3 +145,7 @@ const feature = ifEnabled('FEATURE_ENABLED', {
 ```
 
 This resolves to `{ enabled: true, apiKey: string }` when `FEATURE_ENABLED` is `'true'`, or `{ enabled: false }` otherwise.
+
+## License
+
+[MIT](LICENSE) Jesper Engberg

package/dist/ast.d.mts

@@ -1,24 +1,124 @@
-import { ValidationResult } from "./validation.mjs";
+import { ValidationFailure, ValidationResult } from "./validation.mjs";
+import { Either } from "@jeengbe/prelude";
 //#region src/ast.d.ts
 declare const nodeType: unique symbol;
+/**
+ * A node in a config schema that validates a value out of the loaded environment.
+ *
+ * Do not instantiate this class directly; use the {@link Env} interface instead.
+ */
 declare class EnvNode<T> {
-  readonly validate: (path: string, loadValue: (key: string) => string | undefined) => ValidationResult<T>;
   private readonly [nodeType];
-  constructor(validate: (path: string, loadValue: (key: string) => string | undefined) => ValidationResult<T>);
-  transform<U>(transform: (value: T) => ValidationResult<U>): EnvNode<U>;
+  readonly validate: (loadValue: (key: string) => string | undefined, path: string) => ValidationResult<T>;
+  constructor(validate: (loadValue: (key: string) => string | undefined, path: string) => ValidationResultOrEither<T>);
+  /**
+   * Transforms the validated value of this node into a new value, or fails validation.
+   *
+   * @example
+   *
+   * ```ts
+   * const res = env.load(
+   *   //  ^? number
+   *   env.number('PORT').transform((port, path) =>
+   *     port > 0
+   *       ? ValidationResult.success({ value: port, defaulted: [] })
+   *       : ValidationResult.fail({
+   *           errors: [{ path, key: 'PORT', message: 'must be positive', value: port }],
+   *         }),
+   *   ),
+   * );
+   * ```
+   */
+  transform<U>(transform: (value: T, path: string) => ValidationResultOrEither<U>): EnvNode<U>;
 }
+/**
+ * An {@link EnvNode} backed by a single environment variable.
+ *
+ * Do not instantiate this class directly; use the {@link Env} interface instead.
+ */
 declare class ScalarEnvNode<T> extends EnvNode<T> {
   readonly key: string;
   private readonly validateValue;
-  constructor(key: string, validateValue: (value: string | undefined) => ValidationResult<T>);
+  constructor(key: string, validateValue: (value: string | undefined, path: string) => ScalarValidationResultOrEither<T>);
+  /**
+   * Returns a new ScalarEnvNode that resolves to undefined instead of failing validation when the environment variable is not set.
+   *
+   * @example
+   *
+   * ```ts
+   * const res = env.load(
+   *   //  ^? number | undefined
+   *   env.number('PORT').optional(),
+   * );
+   *
+   * // PORT=3000 -> 3000
+   * // PORT= -> error
+   * // (not set) -> undefined
+   * ```
+   */
   optional(): ScalarEnvNode<T | undefined>;
-  transform<U>(transform: (value: T) => ValidationResult<U>): ScalarEnvNode<U>;
+  /**
+   * Transforms the validated value of this node into a new value, or fails validation.
+   *
+   * As a shorthand for the common case of a single error message, `transform` may return a plain
+   * `Either<string, U>` instead of a full `ValidationResult<U>`. The error string is automatically
+   * wrapped into a {@link ValidationError} using this node's key, its path, and the value that failed to
+   * transform.
+   *
+   * @example
+   *
+   * ```ts
+   * const res = env.load(
+   *   //  ^? number
+   *   env.number('PORT').transform((port) =>
+   *     port > 0 ? Either.right(port) : Either.left('must be positive'),
+   *   ),
+   * );
+   * ```
+   *
+   * @example
+   *
+   * ```ts
+   * const res = env.load(
+   *   //  ^? number
+   *   env.number('PORT').transform((port, path) =>
+   *     port > 0
+   *       ? ValidationResult.success({ value: port, defaulted: [] })
+   *       : ValidationResult.fail({
+   *           errors: [{ path, key: 'PORT', message: 'must be positive', value: port }],
+   *         }),
+   *   ),
+   * );
+   * ```
+   */
+  transform<U>(transform: (value: T, path: string) => ScalarValidationResultOrEither<U>): ScalarEnvNode<U>;
 }
+type ValidationResultOrEither<T> = ValidationResult<T> | Either<ValidationFailure, T>;
+type ScalarValidationResultOrEither<T> = ValidationResultOrEither<T> | Either<string, T>;
+/**
+ * Describes the shape of a config schema: either a single EnvNode, or a nested object of them.
+ */
 type EnvSpec = EnvNode<unknown> | {
   [key: string]: EnvSpec;
 };
-type InferEnvSpec<T extends EnvSpec> = T extends EnvNode<infer U> ? U : T extends Record<string, EnvSpec> ? { [K in keyof T]: InferEnvSpec<T[K]>; } : never;
+/**
+ * Infers the resulting value type produced by loading an EnvSpec.
+ *
+ * @example
+ * ```ts
+ * export function createModuleConfig() {
+ *  return {
+ *    url: env.string('URL'),
+ *    port: env.number('PORT').optional(),
+ *  };
+ * }
+ *
+ * export type ModuleConfig = ParseEnv<ReturnType<typeof createModuleConfig>>;
+ * //    ^? { url: string; port?: number | undefined; }
+ * ```
+ */
+type ParseEnv<T extends EnvSpec> = T extends EnvNode<infer U> ? U : T extends Record<string, EnvSpec> ? { [K in keyof T]: ParseEnv<T[K]>; } : never;
 type Pretty<T> = T extends (infer U extends object) ? { [K in keyof U]: Pretty<U[K]>; } : T;
 //#endregion
-export { EnvNode, EnvSpec, InferEnvSpec, Pretty, ScalarEnvNode };
+export { EnvNode, EnvSpec, ParseEnv, Pretty, ScalarEnvNode, ScalarValidationResultOrEither, ValidationResultOrEither };
 //# sourceMappingURL=ast.d.mts.map

package/dist/ast.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"ast.d.mts","names":[],"sources":["../src/ast.ts"],"mappings":";;cAGM;cAEO,QAAQ;WAIR,WACP,cACA,YAAY,uCACT,iBAAiB;oBANE;EAE1B,YACW,WACP,cACA,YAAY,uCACT,iBAAiB;EAGxB,UAAU,GAAG,YAAY,OAAO,MAAM,iBAAiB,KAAK,QAAQ;;cAKzD,cAAc,WAAW,QAAQ;WAEjC;mBACQ;EAFnB,YACW,aACQ,gBAAgB,8BAA8B,iBAAiB;EASlF,YAAY,cAAc;EAMjB,UAAU,GAAG,YAAY,OAAO,MAAM,iBAAiB,KAAK,cAAc;;KAKzE,UAAU;GAAsB,cAAc;;KAE9C,aAAa,UAAU,WACjC,UAAU,cAAc,KACpB,IACA,UAAU,eAAe,cACpB,WAAW,IAAI,aAAa,EAAE;KAG7B,OAAO,KAAK,iBAAgB,uBAAsB,WAAW,IAAI,OAAO,EAAE,SAAQ"}
+{"version":3,"file":"ast.d.mts","names":[],"sources":["../src/ast.ts"],"mappings":";;;cAQM;;;;;;cAOO,QAAQ;oBACO;WACjB,WACP,YAAY,oCACZ,iBACG,iBAAiB;EAEtB,YACE,WACE,YAAY,oCACZ,iBACG,yBAAyB;;;;;;;;;;;;;;;;;;;EAuBhC,UAAU,GAAG,YAAY,OAAO,GAAG,iBAAiB,yBAAyB,KAAK,QAAQ;;;;;;;cAc/E,cAAc,WAAW,QAAQ;WAEjC;mBACQ;EAFnB,YACW,aACQ,gBACf,2BACA,iBACG,+BAA+B;;;;;;;;;;;;;;;;;EAyBtC,YAAY,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAmDjB,UAAU,GACjB,YAAY,OAAO,GAAG,iBAAiB,+BAA+B,KACrE,cAAc;;KAcP,yBAAyB,KAAK,iBAAiB,KAAK,OAAO,mBAAmB;KAmB9E,+BAA+B,KAAK,yBAAyB,KAAK,eAAe;;;;KAuCjF,UAAU;GAAsB,cAAc;;;;;;;;;;;;;;;;;;KAkB9C,SAAS,UAAU,WAC7B,UAAU,cAAc,KACpB,IACA,UAAU,eAAe,cACpB,WAAW,IAAI,SAAS,EAAE;KAGzB,OAAO,KAAK,iBAAgB,uBAAsB,WAAW,IAAI,OAAO,EAAE,SAAQ"}

package/dist/ast.mjs

@@ -1,32 +1,138 @@
-import { Either } from "@jeengbe/prelude";
+import { ValidationResult } from "./validation.mjs";
+import { EitherBase } from "@jeengbe/prelude";
 
 //#region src/ast.ts
+/**
+* A node in a config schema that validates a value out of the loaded environment.
+*
+* Do not instantiate this class directly; use the {@link Env} interface instead.
+*/
 var EnvNode = class EnvNode {
 	validate;
 	constructor(validate) {
-		this.validate = validate;
+		this.validate = (loadValue, path) => recoverValidationResultOrEither(validate(loadValue, path));
 	}
+	/**
+	* Transforms the validated value of this node into a new value, or fails validation.
+	*
+	* @example
+	*
+	* ```ts
+	* const res = env.load(
+	*   //  ^? number
+	*   env.number('PORT').transform((port, path) =>
+	*     port > 0
+	*       ? ValidationResult.success({ value: port, defaulted: [] })
+	*       : ValidationResult.fail({
+	*           errors: [{ path, key: 'PORT', message: 'must be positive', value: port }],
+	*         }),
+	*   ),
+	* );
+	* ```
+	*/
 	transform(transform) {
-		return new EnvNode((path, loadValue) => this.validate(path, loadValue).flatMap(transform));
+		return new EnvNode((loadValue, path) => this.validate(loadValue, path).flatMap((value) => recoverValidationResultOrEither(transform(value, path))));
 	}
 };
+/**
+* An {@link EnvNode} backed by a single environment variable.
+*
+* Do not instantiate this class directly; use the {@link Env} interface instead.
+*/
 var ScalarEnvNode = class ScalarEnvNode extends EnvNode {
 	key;
 	validateValue;
 	constructor(key, validateValue) {
-		super((path, loadValue) => {
-			return validateValue(loadValue(key)).leftMap((errors) => errors.map((error) => `${key} (${path}): ${error}`));
+		super((loadValue, path) => {
+			const value = loadValue(key);
+			return recoverScalarValidationResultOrEither(validateValue(value, path), path, key, value);
 		});
 		this.key = key;
 		this.validateValue = validateValue;
 	}
+	/**
+	* Returns a new ScalarEnvNode that resolves to undefined instead of failing validation when the environment variable is not set.
+	*
+	* @example
+	*
+	* ```ts
+	* const res = env.load(
+	*   //  ^? number | undefined
+	*   env.number('PORT').optional(),
+	* );
+	*
+	* // PORT=3000 -> 3000
+	* // PORT= -> error
+	* // (not set) -> undefined
+	* ```
+	*/
 	optional() {
-		return new ScalarEnvNode(this.key, (value) => value === void 0 ? Either.right(void 0) : this.validateValue(value));
+		return new ScalarEnvNode(this.key, (value, path) => value === void 0 ? ValidationResult.success({
+			value: void 0,
+			defaulted: [{
+				path,
+				key: this.key,
+				defaultValue: void 0
+			}]
+		}) : this.validateValue(value, path));
 	}
+	/**
+	* Transforms the validated value of this node into a new value, or fails validation.
+	*
+	* As a shorthand for the common case of a single error message, `transform` may return a plain
+	* `Either<string, U>` instead of a full `ValidationResult<U>`. The error string is automatically
+	* wrapped into a {@link ValidationError} using this node's key, its path, and the value that failed to
+	* transform.
+	*
+	* @example
+	*
+	* ```ts
+	* const res = env.load(
+	*   //  ^? number
+	*   env.number('PORT').transform((port) =>
+	*     port > 0 ? Either.right(port) : Either.left('must be positive'),
+	*   ),
+	* );
+	* ```
+	*
+	* @example
+	*
+	* ```ts
+	* const res = env.load(
+	*   //  ^? number
+	*   env.number('PORT').transform((port, path) =>
+	*     port > 0
+	*       ? ValidationResult.success({ value: port, defaulted: [] })
+	*       : ValidationResult.fail({
+	*           errors: [{ path, key: 'PORT', message: 'must be positive', value: port }],
+	*         }),
+	*   ),
+	* );
+	* ```
+	*/
 	transform(transform) {
-		return new ScalarEnvNode(this.key, (value) => this.validateValue(value).flatMap(transform));
+		return new ScalarEnvNode(this.key, (value, path) => recoverScalarValidationResultOrEither(this.validateValue(value, path), path, this.key, value).flatMap((val) => recoverScalarValidationResultOrEither(transform(val, path), path, this.key, value)));
 	}
 };
+function recoverValidationResultOrEither(result) {
+	if (result instanceof EitherBase) return result.fold((error) => ValidationResult.fail(error), (success) => ValidationResult.success({
+		value: success,
+		defaulted: []
+	}));
+	return result;
+}
+function recoverScalarValidationResultOrEither(result, path, key, value) {
+	if (result instanceof EitherBase) return result.fold((error) => ValidationResult.fail(typeof error === "object" ? error : { errors: [{
+		path,
+		key,
+		message: error,
+		value
+	}] }), (success) => ValidationResult.success({
+		value: success,
+		defaulted: []
+	}));
+	return result;
+}
 
 //#endregion
 export { EnvNode, ScalarEnvNode };

package/dist/ast.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"ast.mjs","names":[],"sources":["../src/ast.ts"],"sourcesContent":["import type { ValidationResult } from './validation.js';\nimport { Either } from '@jeengbe/prelude';\n\nconst nodeType = Symbol('type');\n\nexport class EnvNode<T> {\n  declare private readonly [nodeType]: T;\n\n  constructor(\n    readonly validate: (\n      path: string,\n      loadValue: (key: string) => string | undefined,\n    ) => ValidationResult<T>,\n  ) {}\n\n  transform<U>(transform: (value: T) => ValidationResult<U>): EnvNode<U> {\n    return new EnvNode((path, loadValue) => this.validate(path, loadValue).flatMap(transform));\n  }\n}\n\nexport class ScalarEnvNode<T> extends EnvNode<T> {\n  constructor(\n    readonly key: string,\n    private readonly validateValue: (value: string | undefined) => ValidationResult<T>,\n  ) {\n    super((path, loadValue) => {\n      return validateValue(loadValue(key)).leftMap((errors) =>\n        errors.map((error) => `${key} (${path}): ${error}`),\n      );\n    });\n  }\n\n  optional(): ScalarEnvNode<T | undefined> {\n    return new ScalarEnvNode<T | undefined>(this.key, (value) =>\n      value === undefined ? Either.right(undefined) : this.validateValue(value),\n    );\n  }\n\n  override transform<U>(transform: (value: T) => ValidationResult<U>): ScalarEnvNode<U> {\n    return new ScalarEnvNode(this.key, (value) => this.validateValue(value).flatMap(transform));\n  }\n}\n\nexport type EnvSpec = EnvNode<unknown> | { [key: string]: EnvSpec };\n\nexport type InferEnvSpec<T extends EnvSpec> =\n  T extends EnvNode<infer U>\n    ? U\n    : T extends Record<string, EnvSpec>\n      ? { [K in keyof T]: InferEnvSpec<T[K]> }\n      : never;\n\nexport type Pretty<T> = T extends infer U extends object ? { [K in keyof U]: Pretty<U[K]> } : T;\n"],"mappings":";;;AAKA,IAAa,UAAb,MAAa,QAAW;CAIX;CADX,YACE,AAAS,UAIT;EAJS;CAIR;CAEH,UAAa,WAA0D;EACrE,OAAO,IAAI,SAAS,MAAM,cAAc,KAAK,SAAS,MAAM,SAAS,CAAC,CAAC,QAAQ,SAAS,CAAC;CAC3F;AACF;AAEA,IAAa,gBAAb,MAAa,sBAAyB,QAAW;CAEpC;CACQ;CAFnB,YACE,AAAS,KACT,AAAiB,eACjB;EACA,OAAO,MAAM,cAAc;GACzB,OAAO,cAAc,UAAU,GAAG,CAAC,CAAC,CAAC,SAAS,WAC5C,OAAO,KAAK,UAAU,GAAG,IAAI,IAAI,KAAK,KAAK,OAAO,CACpD;EACF,CAAC;EAPQ;EACQ;CAOnB;CAEA,WAAyC;EACvC,OAAO,IAAI,cAA6B,KAAK,MAAM,UACjD,UAAU,SAAY,OAAO,MAAM,MAAS,IAAI,KAAK,cAAc,KAAK,CAC1E;CACF;CAEA,AAAS,UAAa,WAAgE;EACpF,OAAO,IAAI,cAAc,KAAK,MAAM,UAAU,KAAK,cAAc,KAAK,CAAC,CAAC,QAAQ,SAAS,CAAC;CAC5F;AACF"}
+{"version":3,"file":"ast.mjs","names":[],"sources":["../src/ast.ts"],"sourcesContent":["import { ValidationResult } from './validation.js';\nimport { Either, EitherBase } from '@jeengbe/prelude';\n\n// oxlint-disable-next-line no-unused-vars -- Imported for JSDoc\nimport type { Env } from './env.js';\n// oxlint-disable-next-line no-unused-vars -- Imported for JSDoc\nimport type { ValidationError, ValidationFailure } from './validation.js';\n\nconst nodeType = Symbol('type');\n\n/**\n * A node in a config schema that validates a value out of the loaded environment.\n *\n * Do not instantiate this class directly; use the {@link Env} interface instead.\n */\nexport class EnvNode<T> {\n  declare private readonly [nodeType]: T;\n  readonly validate: (\n    loadValue: (key: string) => string | undefined,\n    path: string,\n  ) => ValidationResult<T>;\n\n  constructor(\n    validate: (\n      loadValue: (key: string) => string | undefined,\n      path: string,\n    ) => ValidationResultOrEither<T>,\n  ) {\n    this.validate = (loadValue, path) => recoverValidationResultOrEither(validate(loadValue, path));\n  }\n\n  /**\n   * Transforms the validated value of this node into a new value, or fails validation.\n   *\n   * @example\n   *\n   * ```ts\n   * const res = env.load(\n   *   //  ^? number\n   *   env.number('PORT').transform((port, path) =>\n   *     port > 0\n   *       ? ValidationResult.success({ value: port, defaulted: [] })\n   *       : ValidationResult.fail({\n   *           errors: [{ path, key: 'PORT', message: 'must be positive', value: port }],\n   *         }),\n   *   ),\n   * );\n   * ```\n   */\n  transform<U>(transform: (value: T, path: string) => ValidationResultOrEither<U>): EnvNode<U> {\n    return new EnvNode((loadValue, path) =>\n      this.validate(loadValue, path).flatMap((value) =>\n        recoverValidationResultOrEither(transform(value, path)),\n      ),\n    );\n  }\n}\n\n/**\n * An {@link EnvNode} backed by a single environment variable.\n *\n * Do not instantiate this class directly; use the {@link Env} interface instead.\n */\nexport class ScalarEnvNode<T> extends EnvNode<T> {\n  constructor(\n    readonly key: string,\n    private readonly validateValue: (\n      value: string | undefined,\n      path: string,\n    ) => ScalarValidationResultOrEither<T>,\n  ) {\n    super((loadValue, path) => {\n      const value = loadValue(key);\n\n      return recoverScalarValidationResultOrEither(validateValue(value, path), path, key, value);\n    });\n  }\n\n  /**\n   * Returns a new ScalarEnvNode that resolves to undefined instead of failing validation when the environment variable is not set.\n   *\n   * @example\n   *\n   * ```ts\n   * const res = env.load(\n   *   //  ^? number | undefined\n   *   env.number('PORT').optional(),\n   * );\n   *\n   * // PORT=3000 -> 3000\n   * // PORT= -> error\n   * // (not set) -> undefined\n   * ```\n   */\n  optional(): ScalarEnvNode<T | undefined> {\n    return new ScalarEnvNode<T | undefined>(this.key, (value, path) =>\n      value === undefined\n        ? ValidationResult.success({\n            value: undefined,\n            defaulted: [\n              {\n                path,\n                key: this.key,\n                defaultValue: undefined,\n              },\n            ],\n          })\n        : this.validateValue(value, path),\n    );\n  }\n\n  /**\n   * Transforms the validated value of this node into a new value, or fails validation.\n   *\n   * As a shorthand for the common case of a single error message, `transform` may return a plain\n   * `Either<string, U>` instead of a full `ValidationResult<U>`. The error string is automatically\n   * wrapped into a {@link ValidationError} using this node's key, its path, and the value that failed to\n   * transform.\n   *\n   * @example\n   *\n   * ```ts\n   * const res = env.load(\n   *   //  ^? number\n   *   env.number('PORT').transform((port) =>\n   *     port > 0 ? Either.right(port) : Either.left('must be positive'),\n   *   ),\n   * );\n   * ```\n   *\n   * @example\n   *\n   * ```ts\n   * const res = env.load(\n   *   //  ^? number\n   *   env.number('PORT').transform((port, path) =>\n   *     port > 0\n   *       ? ValidationResult.success({ value: port, defaulted: [] })\n   *       : ValidationResult.fail({\n   *           errors: [{ path, key: 'PORT', message: 'must be positive', value: port }],\n   *         }),\n   *   ),\n   * );\n   * ```\n   */\n  override transform<U>(\n    transform: (value: T, path: string) => ScalarValidationResultOrEither<U>,\n  ): ScalarEnvNode<U> {\n    return new ScalarEnvNode(this.key, (value, path) =>\n      recoverScalarValidationResultOrEither(\n        this.validateValue(value, path),\n        path,\n        this.key,\n        value,\n      ).flatMap((val) =>\n        recoverScalarValidationResultOrEither(transform(val, path), path, this.key, value),\n      ),\n    );\n  }\n}\n\nexport type ValidationResultOrEither<T> = ValidationResult<T> | Either<ValidationFailure, T>;\n\nfunction recoverValidationResultOrEither<T>(\n  result: ValidationResultOrEither<T>,\n): ValidationResult<T> {\n  if (result instanceof EitherBase) {\n    return result.fold(\n      (error) => ValidationResult.fail(error),\n      (success) =>\n        ValidationResult.success({\n          value: success,\n          defaulted: [],\n        }),\n    );\n  }\n\n  return result;\n}\n\nexport type ScalarValidationResultOrEither<T> = ValidationResultOrEither<T> | Either<string, T>;\n\nfunction recoverScalarValidationResultOrEither<T>(\n  result: ScalarValidationResultOrEither<T>,\n  path: string,\n  key: string,\n  value: unknown,\n): ValidationResult<T> {\n  if (result instanceof EitherBase) {\n    return result.fold(\n      (error) =>\n        ValidationResult.fail(\n          typeof error === 'object'\n            ? error\n            : {\n                errors: [\n                  {\n                    path,\n                    key,\n                    message: error,\n                    value,\n                  },\n                ],\n              },\n        ),\n      (success) =>\n        ValidationResult.success({\n          value: success,\n          defaulted: [],\n        }),\n    );\n  }\n\n  return result;\n}\n\n/**\n * Describes the shape of a config schema: either a single EnvNode, or a nested object of them.\n */\nexport type EnvSpec = EnvNode<unknown> | { [key: string]: EnvSpec };\n\n/**\n * Infers the resulting value type produced by loading an EnvSpec.\n *\n * @example\n * ```ts\n * export function createModuleConfig() {\n *  return {\n *    url: env.string('URL'),\n *    port: env.number('PORT').optional(),\n *  };\n * }\n *\n * export type ModuleConfig = ParseEnv<ReturnType<typeof createModuleConfig>>;\n * //    ^? { url: string; port?: number | undefined; }\n * ```\n */\nexport type ParseEnv<T extends EnvSpec> =\n  T extends EnvNode<infer U>\n    ? U\n    : T extends Record<string, EnvSpec>\n      ? { [K in keyof T]: ParseEnv<T[K]> }\n      : never;\n\nexport type Pretty<T> = T extends infer U extends object ? { [K in keyof U]: Pretty<U[K]> } : T;\n"],"mappings":";;;;;;;;;AAeA,IAAa,UAAb,MAAa,QAAW;CAEtB,AAAS;CAKT,YACE,UAIA;EACA,KAAK,YAAY,WAAW,SAAS,gCAAgC,SAAS,WAAW,IAAI,CAAC;CAChG;;;;;;;;;;;;;;;;;;;CAoBA,UAAa,WAAgF;EAC3F,OAAO,IAAI,SAAS,WAAW,SAC7B,KAAK,SAAS,WAAW,IAAI,CAAC,CAAC,SAAS,UACtC,gCAAgC,UAAU,OAAO,IAAI,CAAC,CACxD,CACF;CACF;AACF;;;;;;AAOA,IAAa,gBAAb,MAAa,sBAAyB,QAAW;CAEpC;CACQ;CAFnB,YACE,AAAS,KACT,AAAiB,eAIjB;EACA,OAAO,WAAW,SAAS;GACzB,MAAM,QAAQ,UAAU,GAAG;GAE3B,OAAO,sCAAsC,cAAc,OAAO,IAAI,GAAG,MAAM,KAAK,KAAK;EAC3F,CAAC;EAVQ;EACQ;CAUnB;;;;;;;;;;;;;;;;;CAkBA,WAAyC;EACvC,OAAO,IAAI,cAA6B,KAAK,MAAM,OAAO,SACxD,UAAU,SACN,iBAAiB,QAAQ;GACvB,OAAO;GACP,WAAW,CACT;IACE;IACA,KAAK,KAAK;IACV,cAAc;GAChB,CACF;EACF,CAAC,IACD,KAAK,cAAc,OAAO,IAAI,CACpC;CACF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAoCA,AAAS,UACP,WACkB;EAClB,OAAO,IAAI,cAAc,KAAK,MAAM,OAAO,SACzC,sCACE,KAAK,cAAc,OAAO,IAAI,GAC9B,MACA,KAAK,KACL,KACF,CAAC,CAAC,SAAS,QACT,sCAAsC,UAAU,KAAK,IAAI,GAAG,MAAM,KAAK,KAAK,KAAK,CACnF,CACF;CACF;AACF;AAIA,SAAS,gCACP,QACqB;CACrB,IAAI,kBAAkB,YACpB,OAAO,OAAO,MACX,UAAU,iBAAiB,KAAK,KAAK,IACrC,YACC,iBAAiB,QAAQ;EACvB,OAAO;EACP,WAAW,CAAC;CACd,CAAC,CACL;CAGF,OAAO;AACT;AAIA,SAAS,sCACP,QACA,MACA,KACA,OACqB;CACrB,IAAI,kBAAkB,YACpB,OAAO,OAAO,MACX,UACC,iBAAiB,KACf,OAAO,UAAU,WACb,QACA,EACE,QAAQ,CACN;EACE;EACA;EACA,SAAS;EACT;CACF,CACF,EACF,CACN,IACD,YACC,iBAAiB,QAAQ;EACvB,OAAO;EACP,WAAW,CAAC;CACd,CAAC,CACL;CAGF,OAAO;AACT"}

package/dist/env.d.mts

@@ -1,18 +1,216 @@
 import { ValidationResult } from "./validation.mjs";
-import { EnvNode, EnvSpec, InferEnvSpec, Pretty, ScalarEnvNode } from "./ast.mjs";
+import { EnvNode, EnvSpec, ParseEnv, Pretty, ScalarEnvNode, ScalarValidationResultOrEither } from "./ast.mjs";
 //#region src/env.d.ts
+/**
+ * Type-safe configuration loader.
+ *
+ * @example
+ *
+ * ```ts
+ * import { env } from '@jeengbe/config';
+ *
+ * const config = env.load({
+ *   port: env.number('PORT', 3000),
+ *   debug: env.boolean('DEBUG', false),
+ *   driver: env.discriminate('driver', env.enum('DRIVER', ['memory', 'redis']), {
+ *     memory: {},
+ *     redis: { url: env.string('REDIS_URL') },
+ *   }),
+ * });
+ *
+ * // -> {
+ * //   port: number;
+ * //   debug: boolean;
+ * //   driver: { driver: 'memory' } | { driver: 'redis'; url: string };
+ * // }
+ * ```
+ *
+ * Variables are read from `process.env` and trimmed before validation. Only a fully unset variable
+ * falls back to a default value or fails as required - an explicitly empty value is passed through to
+ * validation like any other input.
+ */
 interface Env {
+  /**
+   * Reads a string environment variable.
+   *
+   * @example
+   *
+   * ```ts
+   * const res = env.load(env.string('API_KEY'));
+   * //    ^? string
+   *
+   * // API_KEY=abc-test -> 'abc-test'
+   * // API_KEY=123 -> '123'
+   * // API_KEY= -> ''
+   * ```
+   */
   string(key: string, defaultValue?: string): ScalarEnvNode<string>;
+  /**
+   * Reads a numeric environment variable. Must match `/^-?\d+(?:\.\d+)?$/`, i.e. `[-]digits[.digits]`.
+   *
+   * @example
+   *
+   * ```ts
+   * const res = env.load(env.number('PORT'));
+   * //    ^? number
+   *
+   * // PORT=3000 -> 3000
+   * // PORT=-1 -> -1
+   * // PORT=abc -> error
+   * ```
+   */
   number(key: string, defaultValue?: number): ScalarEnvNode<number>;
+  /**
+   * Reads a boolean environment variable (must be 'true' or 'false').
+   *
+   * @example
+   *
+   * ```ts
+   * const res = env.load(env.boolean('DEBUG'));
+   * //    ^? boolean
+   *
+   * // DEBUG=true -> true
+   * // DEBUG=false -> false
+   * // DEBUG=abc -> error
+   * ```
+   */
   boolean(key: string, defaultValue?: boolean): ScalarEnvNode<boolean>;
+  /**
+   * Reads an environment variable constrained to one of the provided values.
+   *
+   * @example
+   *
+   * ```ts
+   * const res = env.load(env.enum('DRIVER', ['memory', 'redis']));
+   * //    ^? 'memory' | 'redis'
+   *
+   * // DRIVER=memory -> 'memory'
+   * // DRIVER=abc -> error
+   * ```
+   */
   enum<const T extends string>(key: string, values: readonly T[], defaultValue?: T): ScalarEnvNode<T>;
-  custom<T>(key: string, transform: (value: string) => ValidationResult<T>, defaultValue?: T): ScalarEnvNode<T>;
-  array<T>(itemType: ScalarEnvNode<T>, defaultValue?: readonly T[]): EnvNode<readonly T[]>;
+  /**
+   * Reads a comma-separated list environment variable, validating each item against the provided item type.
+   *
+   * @example
+   *
+   * ```ts
+   * const res = env.load(env.array(env.string('API_KEYS')));
+   * //    ^? readonly string[]
+   *
+   * // API_KEYS=abc,def,ghi -> ['abc', 'def', 'ghi']
+   * // API_KEYS= -> []
+   * // API_KEYS=abc,,ghi -> error
+   * ```
+   *
+   * @example
+   *
+   * ```ts
+   * const res = env.load(env.array(env.string('API_KEYS'), ['default1', 'default2']));
+   * //    ^? readonly string[]
+   *
+   * // API_KEYS=abc,def,ghi -> ['abc', 'def', 'ghi']
+   * // API_KEYS= -> []
+   * // (not set) -> ['default1', 'default2']
+   * // API_KEYS=abc,,ghi -> error
+   * ```
+   *
+   * @example
+   *
+   * ```ts
+   * const res = env.load(env.array(env.string('API_KEYS').optional()));
+   * //    ^? readonly (string | undefined)[]
+   *
+   * // API_KEYS=abc,def,ghi -> ['abc', 'def', 'ghi']
+   * // API_KEYS= -> []
+   * // API_KEYS=abc,,ghi -> ['abc', undefined, 'ghi']
+   * ```
+   */
+  array<const T>(itemType: ScalarEnvNode<T>, defaultValue?: readonly T[]): ScalarEnvNode<readonly T[]>;
+  /**
+   * Reads an environment variable, validating and transforming it with the provided function.
+   *
+   * @example
+   *
+   * ```ts
+   * const res = env.load(
+   *   //  ^? string
+   *   env.scalar('TAG', (value, path) =>
+   *     value.length === 3
+   *       ? ValidationResult.success({ value, defaulted: [] })
+   *       : ValidationResult.fail({
+   *           errors: [{ path, key: 'TAG', message: 'must be 3 characters long', value }],
+   *         }),
+   *   ),
+   * );
+   *
+   * // TAG=abc -> 'abc'
+   * // TAG=abcd -> error
+   * ```
+   */
+  scalar<const T>(key: string, transform: (value: string, path: string) => ScalarValidationResultOrEither<T>, defaultValue?: T): ScalarEnvNode<T>;
+  /**
+   * Reads a discriminator environment variable and resolves the nested schema mapped to its value.
+   *
+   * @example
+   *
+   * ```ts
+   * const res = env.load(
+   *   //  ^? { driver: 'memory'; } | { driver: 'redis'; url: string; }
+   *   env.discriminate('driver', env.enum('DRIVER', ['memory', 'redis']), {
+   *     memory: {},
+   *     redis: { url: env.string('REDIS_URL') },
+   *   }),
+   * );
+   *
+   * // DRIVER=memory -> { driver: 'memory' }
+   * // DRIVER=redis, REDIS_URL=redis://localhost -> { driver: 'redis', url: 'redis://localhost' }
+   * // DRIVER=redis, REDIS_URL= -> { driver: 'redis', url: '' }
+   * // DRIVER=abc -> error
+   * ```
+   */
   discriminate<K extends string, V extends string, M extends Partial<Record<V, Record<string, EnvSpec>>>>(discriminatorKey: K, discriminatorValueType: ScalarEnvNode<V>, mapping: M): EnvNode<DiscriminatorResult<K, V, M>>;
-  load<S extends EnvSpec>(spec: S): Pretty<InferEnvSpec<S>>;
+  /**
+   * Validates and loads the provided schema from `process.env`. Returns a `ValidationResult` that contains either the parsed values or a list of validation errors.
+   *
+   * @example
+   *
+   * ```ts
+   * const result = env.parse({
+   *   port: env.number('PORT'),
+   *   debug: env.boolean('DEBUG'),
+   * });
+   *
+   * if (result.getLeft()) {
+   *   console.error('Validation failed:', result.getLeft());
+   * } else {
+   *   const config = result.get()!;
+   *   // -> { port: number; debug: boolean; }
+   * }
+   * ```
+   */
+  parse<S extends EnvSpec>(spec: S, env?: NodeJS.ProcessEnv): ValidationResult<Pretty<ParseEnv<S>>>;
+  /**
+   * Validates and loads the provided schema from `process.env`. Throws if any required variables are missing or invalid.
+   *
+   * @example
+   *
+   * ```ts
+   * const config = env.load({
+   *   port: env.number('PORT', 3000),
+   *   debug: env.boolean('DEBUG', false),
+   * }, console.log);
+   *
+   * // -> {
+   * //   port: number;
+   * //   debug: boolean;
+   * // }
+   * ```
+   */
+  load<S extends EnvSpec>(spec: S, env?: NodeJS.ProcessEnv): Pretty<ParseEnv<S>>;
 }
 declare const env: Env;
-type DiscriminatorResult<K extends string, V extends string, M extends Partial<Record<V, Record<string, EnvSpec>>>> = Pretty<V extends unknown ? Record<K, V> & InferEnvSpec<M[V] extends EnvSpec ? M[V] : {}> : never>;
+type DiscriminatorResult<K extends string, V extends string, M extends Partial<Record<V, Record<string, EnvSpec>>>> = Pretty<V extends unknown ? Record<K, V> & ParseEnv<M[V] extends EnvSpec ? M[V] : {}> : never>;
 //#endregion
 export { Env, env };
 //# sourceMappingURL=env.d.mts.map

package/dist/env.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"env.d.mts","names":[],"sources":["../src/env.ts"],"mappings":";;;UAMiB;EACf,OAAO,aAAa,wBAAwB;EAC5C,OAAO,aAAa,wBAAwB;EAC5C,QAAQ,aAAa,yBAAyB;EAC9C,WAAW,kBACT,aACA,iBAAiB,KACjB,eAAe,IACd,cAAc;EACjB,OAAO,GACL,aACA,YAAY,kBAAkB,iBAAiB,IAC/C,eAAe,IACd,cAAc;EACjB,MAAM,GAAG,UAAU,cAAc,IAAI,wBAAwB,MAAM,iBAAiB;EACpF,aACE,kBACA,kBACA,UAAU,QAAQ,OAAO,GAAG,eAAe,YAE3C,kBAAkB,GAClB,wBAAwB,cAAc,IACtC,SAAS,IACR,QAAQ,oBAAoB,GAAG,GAAG;EACrC,KAAK,UAAU,SAAS,MAAM,IAAI,OAAO,aAAa;;cAG3C,KAAK;KAgHb,oBACH,kBACA,kBACA,UAAU,QAAQ,OAAO,GAAG,eAAe,cACzC,OAGF,oBAAoB,OAAO,GAAG,KAAK,aAAa,EAAE,WAAW,UAAU,EAAE"}
+{"version":3,"file":"env.d.mts","names":[],"sources":["../src/env.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;UAkCiB;;;;;;;;;;;;;;;EAef,OAAO,aAAa,wBAAwB;;;;;;;;;;;;;;;EAgB5C,OAAO,aAAa,wBAAwB;;;;;;;;;;;;;;;EAgB5C,QAAQ,aAAa,yBAAyB;;;;;;;;;;;;;;EAe9C,WAAW,kBACT,aACA,iBAAiB,KACjB,eAAe,IACd,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAuCjB,YAAY,GACV,UAAU,cAAc,IACxB,wBAAwB,MACvB,uBAAuB;;;;;;;;;;;;;;;;;;;;;;EAuB1B,aAAa,GACX,aACA,YAAY,eAAe,iBAAiB,+BAA+B,IAC3E,eAAe,IACd,cAAc;;;;;;;;;;;;;;;;;;;;;EAsBjB,aACE,kBACA,kBACA,UAAU,QAAQ,OAAO,GAAG,eAAe,YAE3C,kBAAkB,GAClB,wBAAwB,cAAc,IACtC,SAAS,IACR,QAAQ,oBAAoB,GAAG,GAAG;;;;;;;;;;;;;;;;;;;;EAqBrC,MAAM,UAAU,SAAS,MAAM,GAAG,MAAM,OAAO,aAAa,iBAAiB,OAAO,SAAS;;;;;;;;;;;;;;;;;;EAmB7F,KAAK,UAAU,SAAS,MAAM,GAAG,MAAM,OAAO,aAAa,OAAO,SAAS;;cAGhE,KAAK;KA+Lb,oBACH,kBACA,kBACA,UAAU,QAAQ,OAAO,GAAG,eAAe,cACzC,OAGF,oBAAoB,OAAO,GAAG,KAAK,SAAS,EAAE,WAAW,UAAU,EAAE"}