@jeengbe/config 0.0.8 → 1.0.0

package/README.md

@@ -1,9 +1,136 @@
 <h1 align="center">@jeengbe/config</h1>
 <div align="center">
 
+A declarative, strongly typed schema for parsing and validating environment variables in TypeScript.
+
 [![License](https://img.shields.io/npm/l/@jeengbe/config)](https://github.com/jeengbe/ts-packages/blob/master/packages/config/LICENSE)
 [![Version](https://img.shields.io/npm/v/@jeengbe/config)](https://www.npmjs.com/package/@jeengbe/config)
 [![JSR](https://jsr.io/badges/@jeengbe/config)](https://jsr.io/@jeengbe/config)
 [![Coverage](https://codecov.io/gh/jeengbe/ts-packages/branch/master/graph/badge.svg?component=config)](https://app.codecov.io/gh/jeengbe/ts-packages/tree/master/packages/config)
 
 </div>
+
+Define your environment variables once as a schema, and get back a plain, fully typed config object. Missing or invalid values are collected across the whole schema and reported together, so you find out about every misconfigured variable at once, rather than one crash at a time.
+
+## Installation
+
+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.
+
+## Usage
+
+### Defining and loading a schema
+
+```ts
+import { env } from '@jeengbe/config';
+
+const config = env.load({
+  port: env.number('PORT', 3000),
+  host: env.string('HOST', '0.0.0.0'),
+  logLevel: env.enum('LOG_LEVEL', ['debug', 'info', 'warn', 'error'], 'info'),
+});
+// config: { port: number; host: string; logLevel: 'debug' | 'info' | 'warn' | 'error' }
+```
+
+`env.load` reads from `process.env` (values are trimmed, and a missing or whitespace-only value is treated as absent), validates every field, and returns a plain object typed to match the schema. If anything is missing or invalid, it throws a single error combining every failure:
+
+```
+Failed to load config: FOO ($.foo): required, NUM ($.num): invalid number
+```
+
+Schemas nest using plain objects:
+
+```ts
+const config = env.load({
+  server: {
+    port: env.number('PORT', 3000),
+  },
+  database: {
+    url: env.string('DATABASE_URL'),
+  },
+});
+// config: { server: { port: number }; database: { url: string } }
+```
+
+### Scalars
+
+- `env.string(key, defaultValue?)`
+- `env.number(key, defaultValue?)` — accepts integers and decimals, including negative numbers.
+- `env.boolean(key, defaultValue?)` — accepts `'true'`/`'false'`, case-insensitively.
+- `env.enum(key, values, defaultValue?)` — restricts the value to one of a fixed list, typed as a literal union of `values`.
+
+Without a `defaultValue`, all of these are required and fail validation when the variable is missing.
+
+### Custom scalars (`env.scalar`)
+
+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.scalar('API_URL', (value) => {
+  try {
+    return Either.right(new URL(value));
+  } catch {
+    return Either.left(['must be a valid URL']);
+  }
+});
+```
+
+### Optional values (`.optional()`)
+
+Any scalar node can be made optional. This resolves to `undefined` when the variable is missing, ignoring the default value on the underlying node, instead of failing validation:
+
+```ts
+const timeoutMs = env.number('TIMEOUT_MS').optional();
+```
+
+### Transforming values (`.transform()`)
+
+Every node can be transformed into a different value. The transform function receives the already-validated value and itself returns a `ValidationResult`, so it can also fail validation:
+
+```ts
+const port = env
+  .number('PORT')
+  .transform((n) =>
+    n > 0 && n < 65536 ? Either.right(n) : Either.left(['must be between 1 and 65535']),
+  );
+```
+
+### Arrays (`env.array`)
+
+`env.array` splits a comma-separated string and validates each item against a scalar node:
+
+```ts
+const ports = env.array(env.number('PORTS'));
+// PORTS="3000,3001,3002" -> [3000, 3001, 3002]
+```
+
+An empty item between commas (e.g. `"1,,3"`) is treated as `undefined` for the item schema (mark the item node `.optional()` to allow that). A missing variable falls back to the array's own `defaultValue`, if one was given; the item schema's default is not applied per-missing-item.
+
+### Discriminated variants (`env.discriminate`)
+
+Use `env.discriminate` to pick between several shapes based on the value of another variable, similar to a discriminated union:
+
+```ts
+const storage = env.discriminate('type', env.enum('STORAGE_TYPE', ['s3', 'local']), {
+  s3: { bucket: env.string('S3_BUCKET') },
+  local: { path: env.string('LOCAL_PATH') },
+});
+// storage: { type: 's3'; bucket: string } | { type: 'local'; path: string }
+```
+
+### Feature flags (`ifEnabled`)
+
+`ifEnabled` wraps `env.discriminate` for the common case of gating a block of config behind a boolean flag:
+
+```ts
+import { ifEnabled } from '@jeengbe/config';
+
+const feature = ifEnabled('FEATURE_ENABLED', {
+  apiKey: env.string('FEATURE_API_KEY'),
+});
+// feature: { enabled: true; apiKey: string } | { enabled: false }
+```
+
+This resolves to `{ enabled: true, apiKey: string }` when `FEATURE_ENABLED` is `'true'`, or `{ enabled: false }` otherwise.

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