@meltstudio/config-loader 2.0.1 → 3.0.0

package/README.md

@@ -2,6 +2,10 @@
 
 A type-safe configuration loader for Node.js. Define your schema once, load from YAML or JSON files, `.env` files, environment variables, and CLI arguments — and get a fully typed result with zero manual type annotations.
 
+> **Upgrading from v1?** v1.x is deprecated. v2 includes breaking changes to the public API, object schema syntax, and requires Node.js >= 20. Install the latest version with `npm install @meltstudio/config-loader@latest` or `yarn add @meltstudio/config-loader@latest`.
+
+**[Full documentation](https://meltstudio.github.io/config-loader/)**
+
 ## Why config-loader?
 
 Most config libraries give you `Record<string, unknown>` and leave you to cast or validate manually. config-loader infers TypeScript types directly from your schema definition:
@@ -56,7 +60,8 @@ No separate interface to maintain. No `as` casts. The types flow from the schema
 - **Priority resolution** — CLI > process.env > `.env` files > Config files > Defaults
 - **`.env` file support** — load environment variables from `.env` files with automatic line tracking
 - **Nested objects and arrays** — deeply nested configs with full type safety
-- **Structured errors** — typed `ConfigLoadError` with per-field error details instead of `process.exit(1)`
+- **Structured errors** — typed `ConfigLoadError` with per-field error details and warnings
+- **Strict mode** — promote warnings to errors for production safety
 - **Default values** — static or computed (via functions)
 - **Multiple files / directory loading** — load from a list of files or an entire directory
 
@@ -274,7 +279,7 @@ Use `loadExtended()` instead of `load()` to get each value wrapped in a `ConfigN
 ```typescript
 import c from "@meltstudio/config-loader";
 
-const extended = c
+const { data, warnings } = c
   .schema({
     port: c.number({ required: true, env: "PORT" }),
     host: c.string({ defaultValue: "localhost" }),
@@ -285,7 +290,12 @@ const extended = c
     files: "./config.yaml",
   });
 
-// Each leaf is a ConfigNode with:
+// `warnings` is a string[] of non-fatal issues (e.g. type coercions, unused env mappings)
+if (warnings.length > 0) {
+  warnings.forEach((w) => console.warn(w));
+}
+
+// Each leaf in `data` is a ConfigNode with:
 // {
 //   value: 3000,
 //   path: "port",
@@ -296,9 +306,9 @@ const extended = c
 //   line: 5 | null,      // source line (1-based) for YAML, JSON, and .env files; null for env/args/default
 //   column: 3 | null      // source column (1-based) for YAML, JSON, and .env files; null for env/args/default
 // }
-console.log(extended.port.value); // 3000
-console.log(extended.port.sourceType); // "env"
-console.log(extended.port.variableName); // "PORT"
+console.log(data.port.value); // 3000
+console.log(data.port.sourceType); // "env"
+console.log(data.port.variableName); // "PORT"
 ```
 
 This is useful for debugging configuration resolution, building admin UIs that show where each setting originated, or auditing which sources are active.
@@ -326,12 +336,23 @@ try {
 }
 ```
 
-For CLI tools that prefer the old exit-on-error behavior:
+Warnings (non-fatal issues like type coercions) are never printed to the console. Use `loadExtended()` to access them, or they are included in `ConfigLoadError.warnings` when errors occur.
+
+### Strict Mode
+
+Enable `strict: true` to promote all warnings to errors, causing `ConfigLoadError` to be thrown for any ambiguous or lossy configuration:
 
 ```typescript
-.load({ env: true, args: true, files: "./config.yaml", exitOnError: true })
+.load({
+  env: true,
+  args: false,
+  files: "./config.yaml",
+  strict: true,
+})
 ```
 
+This is useful in production environments where you want to catch type coercions, null values, and other ambiguous config early rather than silently accepting them.
+
 ## CLI Arguments
 
 Set `cli: true` on an option to allow overriding via command line:
@@ -413,6 +434,182 @@ The `.env` parser supports:
 
 When using `loadExtended()`, values from `.env` files have `sourceType: "envFile"` with `file`, `line`, and `column` metadata pointing to the `.env` file location.
 
+## Common Patterns
+
+### Load from YAML with env overrides
+
+```typescript
+import c from "@meltstudio/config-loader";
+
+const config = c
+  .schema({
+    port: c.number({ required: true, env: "PORT", defaultValue: 3000 }),
+    host: c.string({ required: true, env: "HOST", defaultValue: "localhost" }),
+  })
+  .load({ env: true, args: false, files: "./config.yaml" });
+```
+
+### Strict mode for production
+
+```typescript
+const config = c
+  .schema({
+    port: c.number({ required: true, env: "PORT" }),
+    dbUrl: c.string({ required: true, env: "DATABASE_URL" }),
+  })
+  .load({
+    env: true,
+    args: false,
+    files: "./config.yaml",
+    strict: true, // any type coercion or ambiguity throws an error
+  });
+```
+
+### Catch and inspect errors
+
+```typescript
+import c, { ConfigLoadError } from "@meltstudio/config-loader";
+
+try {
+  const config = c
+    .schema({ port: c.number({ required: true }) })
+    .load({ env: false, args: false, files: "./config.yaml" });
+} catch (err) {
+  if (err instanceof ConfigLoadError) {
+    for (const entry of err.errors) {
+      console.error(`[${entry.kind}] ${entry.path}: ${entry.message}`);
+    }
+    // err.warnings contains non-fatal issues
+  }
+}
+```
+
+### Load from a directory of config files
+
+```typescript
+const config = c
+  .schema({
+    port: c.number({ required: true }),
+    host: c.string({ required: true }),
+  })
+  .load({ env: false, args: false, dir: "./config.d/" });
+// All YAML/JSON files in the directory are loaded and merged (sorted by filename)
+```
+
+### Access source metadata with loadExtended
+
+```typescript
+const { data, warnings } = c
+  .schema({
+    port: c.number({ required: true, env: "PORT" }),
+  })
+  .loadExtended({ env: true, args: false, files: "./config.yaml" });
+
+const portNode = data.port; // ConfigNode
+console.log(portNode.value); // 3000
+console.log(portNode.sourceType); // "env" | "file" | "default" | "args" | "envFile"
+console.log(portNode.file); // "./config.yaml" or null
+console.log(portNode.line); // source line number or null
+```
+
+### Combine .env files with process.env
+
+```typescript
+const config = c
+  .schema({
+    apiKey: c.string({ required: true, env: "API_KEY" }),
+    debug: c.bool({ env: "DEBUG", defaultValue: false }),
+  })
+  .load({
+    env: true, // reads process.env
+    args: false,
+    envFile: ["./.env", "./.env.local"], // .env.local overrides .env
+  });
+// Priority: process.env > .env.local > .env > defaults
+```
+
+## Common Mistakes
+
+### Forgetting `item` in `c.object()`
+
+```typescript
+// WRONG — fields are passed directly
+c.object({ host: c.string(), port: c.number() });
+
+// CORRECT — fields must be inside `item`
+c.object({ item: { host: c.string(), port: c.number() } });
+```
+
+### Setting `env` on an option but not enabling env loading
+
+```typescript
+// WRONG — env: "PORT" is set but env loading is disabled
+c.schema({ port: c.number({ env: "PORT" }) }).load({
+  env: false,
+  args: false,
+  files: "./config.yaml",
+});
+// This emits a warning: "Options [port] have env mappings but env loading is disabled"
+
+// CORRECT — set env: true in load options
+c.schema({ port: c.number({ env: "PORT" }) }).load({
+  env: true,
+  args: false,
+  files: "./config.yaml",
+});
+```
+
+### Expecting `.env` files to work without `envFile`
+
+```typescript
+// WRONG — .env files are not loaded by default
+c.schema({ key: c.string({ env: "API_KEY" }) }).load({
+  env: true,
+  args: false,
+});
+// This only reads process.env, not .env files
+
+// CORRECT — explicitly pass envFile
+c.schema({ key: c.string({ env: "API_KEY" }) }).load({
+  env: true,
+  args: false,
+  envFile: "./.env",
+});
+```
+
+### Not catching `ConfigLoadError`
+
+```typescript
+// WRONG — unhandled error crashes the process with an unhelpful stack trace
+const config = c
+  .schema({ port: c.number({ required: true }) })
+  .load({ env: false, args: false });
+
+// CORRECT — catch and handle structured errors
+try {
+  const config = c
+    .schema({ port: c.number({ required: true }) })
+    .load({ env: false, args: false });
+} catch (err) {
+  if (err instanceof ConfigLoadError) {
+    console.error(err.errors); // structured error details
+  }
+}
+```
+
+### Using `required: true` on nested fields without the parent object
+
+If the parent object is entirely absent from all sources, child `required` fields will still trigger errors. Use `required` on the parent `c.object()` only if the entire subtree must be present.
+
+## Documentation for AI Agents
+
+This project provides machine-readable documentation for AI coding agents at the docs site:
+
+- **[llms.txt](https://meltstudio.github.io/config-loader/llms.txt)** — structured index of documentation pages
+- **[llms-full.txt](https://meltstudio.github.io/config-loader/llms-full.txt)** — full documentation in a single Markdown file
+
+These files follow the [llms.txt standard](https://llmstxt.org/) and are generated automatically at build time. They are designed to be consumed by AI tools like Claude Code, Cursor, GitHub Copilot, and other LLM-based development assistants.
+
 ## License
 
 This package is licensed under the Apache License 2.0. See the [LICENSE](./LICENSE) file for details.

package/dist/index.d.ts

@@ -14,19 +14,30 @@ interface EnvFileResult {
     filePath: string;
 }
 
+/** A single configuration validation error with optional location metadata. */
 interface ConfigErrorEntry {
+    /** Human-readable error description. */
     message: string;
+    /** Dot-separated path to the offending config key (e.g. `"db.port"`). */
     path?: string;
+    /** The source where the error originated (e.g. file path, `"env"`, `"cli"`). */
     source?: string;
-    kind?: "required" | "type_conversion" | "invalid_path" | "invalid_state" | "file_validation";
+    /** Classification of the error. */
+    kind?: "required" | "type_conversion" | "invalid_path" | "invalid_state" | "file_validation" | "null_value" | "strict";
+    /** Line number in the config file where the error occurred, if applicable. */
     line?: number;
+    /** Column number in the config file where the error occurred, if applicable. */
     column?: number;
 }
+/** Thrown when configuration loading fails validation. Contains structured error entries and warnings. */
 declare class ConfigLoadError extends Error {
+    /** All validation errors that caused the load to fail. */
     readonly errors: ConfigErrorEntry[];
+    /** Non-fatal warnings collected during loading. */
     readonly warnings: string[];
     constructor(errors: ConfigErrorEntry[], warnings: string[]);
 }
+/** Thrown when a configuration file cannot be read or parsed. */
 declare class ConfigFileError extends ConfigLoadError {
     constructor(message: string);
 }
@@ -93,21 +104,37 @@ declare class PrimitiveOption<T extends PrimitiveKind = PrimitiveKind> extends O
 type NodeTree = {
     [key: string]: NodeTree | ConfigNode;
 };
+/** Result returned by `SettingsBuilder.loadExtended()`, including raw node data and warnings. */
+type ExtendedResult = {
+    /** Tree of `ConfigNode` objects preserving source metadata for each resolved value. */
+    data: NodeTree;
+    /** Non-fatal warnings collected during loading. */
+    warnings: string[];
+};
 type RecursivePartial<T> = {
     [K in keyof T]?: RecursivePartial<T[K]>;
 };
+/** Configuration sources passed to `SettingsBuilder.load()` / `loadExtended()`. Priority: CLI > Env > Files > Defaults. */
 type SettingsSources<T> = {
+    /** Whether to read values from `process.env`. */
     env: boolean;
+    /** Whether to parse CLI arguments via Commander. */
     args: boolean;
+    /** YAML/JSON file path(s) to load, or `false` to skip. */
     files?: string | string[] | false;
+    /** Directory to scan for config files, or `false` to skip. */
     dir?: string | false;
+    /** `.env` file path(s) to load, or `false` to skip. */
     envFile?: string | string[] | false;
+    /** Partial default values applied at the lowest priority. */
     defaults?: RecursivePartial<T>;
-    exitOnError?: boolean;
+    /** When `true`, unknown keys in config files cause errors. */
+    strict?: boolean;
 };
 type OptionKind = "boolean" | "string" | "number" | "array" | "object";
 type PrimitiveKind = Extract<OptionKind, "boolean" | "string" | "number">;
 type TypeOfPrimitiveKind<T extends PrimitiveKind> = T extends "boolean" ? boolean : T extends "string" ? string : T extends "number" ? number : never;
+/** Recursively infers the plain TypeScript type from a schema definition. Maps option nodes to their resolved value types. */
 type SchemaValue<T extends OptionBase | Node> = T extends OptionBase ? T extends ArrayOption<OptionTypes> ? SchemaValue<T["item"]>[] : T extends ObjectOption<infer R> ? {
     [K in keyof R]: SchemaValue<R[K]>;
 } : T extends PrimitiveOption<infer R> ? TypeOfPrimitiveKind<R> : never : T extends Node ? {
@@ -146,29 +173,68 @@ declare class ObjectOption<T extends Node = Node> extends OptionBase<"object"> {
 
 type OptionTypes = PrimitiveOption | ArrayOption<OptionTypes> | ObjectOption<Node>;
 
+/** Fluent builder that takes a schema and resolves configuration from multiple sources. */
 declare class SettingsBuilder<T extends Node> {
     private readonly schema;
     constructor(schema: T);
+    /**
+     * Loads and validates configuration, returning a fully-typed plain object.
+     * @param sources - Which sources to read (env, args, files, etc.).
+     * @returns The resolved configuration object matching the schema type.
+     * @throws {ConfigLoadError} If validation fails (missing required fields, type errors, etc.).
+     */
     load(sources: SettingsSources<SchemaValue<T>>): SchemaValue<T>;
-    loadExtended(sources: SettingsSources<SchemaValue<T>>): NodeTree;
+    /**
+     * Loads configuration and returns raw node data with source metadata alongside warnings.
+     * @param sources - Which sources to read (env, args, files, etc.).
+     * @returns An `ExtendedResult` containing the node tree and any warnings.
+     * @throws {ConfigLoadError} If validation fails.
+     */
+    loadExtended(sources: SettingsSources<SchemaValue<T>>): ExtendedResult;
 }
 
+/** Options for configuring a primitive (`string`, `number`, `bool`) schema field. */
 interface OptionPropsArgs<T> {
+    /** Whether the field must be present in at least one source. */
     required?: boolean;
+    /** Environment variable name to read from, or `null` to disable. */
     env?: string | null;
+    /** Whether to expose this field as a CLI argument via Commander. */
     cli?: boolean;
+    /** Static default value or factory function returning one. */
     defaultValue?: T | (() => T);
+    /** Help text shown in CLI `--help` output. */
     help?: string;
 }
+/** Options for configuring an `array` schema field. */
 interface ArrayOptionPropsArgs<T extends OptionTypes> {
+    /** Whether the field must be present in at least one source. */
     required?: boolean;
+    /** Schema definition for each item in the array. */
     item: T;
+    /** Static default value or factory function returning one. */
     defaultValue?: SchemaValue<T>[] | (() => SchemaValue<T>[]);
 }
+/** Options for configuring a nested `object` schema field. */
 interface ObjectOptionPropsArgs<T extends Node> {
+    /** Whether the field must be present in at least one source. */
     required?: boolean;
+    /** Schema definition for the nested object's shape. */
     item: T;
 }
+/**
+ * Config-loader entry point. Provides factory functions to define a typed configuration schema.
+ *
+ * @example
+ * ```ts
+ * import c from "@meltstudio/config-loader";
+ *
+ * const config = c.schema({
+ *   port: c.number({ env: "PORT", defaultValue: 3000 }),
+ *   host: c.string({ env: "HOST" }),
+ * }).load({ env: true, args: false });
+ * ```
+ */
 declare const option: {
     string: (opts?: OptionPropsArgs<string>) => PrimitiveOption<"string">;
     number: (opts?: OptionPropsArgs<number>) => PrimitiveOption<"number">;
@@ -178,4 +244,4 @@ declare const option: {
     schema: <T extends Node>(theSchema: T) => SettingsBuilder<T>;
 };
 
-export { type ConfigErrorEntry, ConfigFileError, ConfigLoadError, option as default };
+export { type ConfigErrorEntry, ConfigFileError, ConfigLoadError, type ExtendedResult, option as default };

package/dist/index.js

@@ -41,7 +41,9 @@ var import_commander = require("commander");
 
 // src/errors.ts
 var ConfigLoadError = class extends Error {
+  /** All validation errors that caused the load to fail. */
   errors;
+  /** Non-fatal warnings collected during loading. */
   warnings;
   constructor(errors, warnings) {
     const message = `Configuration loading failed with ${errors.length} error${errors.length === 1 ? "" : "s"}`;
@@ -286,7 +288,7 @@ var OptionBase = class {
     if (this.params.env && env) {
       if (this.params.env in env) {
         const val = env[this.params.env];
-        if (val) {
+        if (val !== void 0) {
           const envFileSource = findEnvFileSource(
             this.params.env,
             val,
@@ -448,6 +450,12 @@ var OptionBase = class {
         );
         return val.toString();
       }
+      if (typeof val === "boolean") {
+        errors?.warnings.push(
+          `The option ${ident} is stated as a string but is provided as a boolean`
+        );
+        return val.toString();
+      }
       errors?.errors.push({
         message: `Cannot convert value '${valueToString(
           val
@@ -460,10 +468,11 @@ var OptionBase = class {
     }
     if (this.params.kind === "boolean") {
       if (typeof val !== "boolean" && typeof val !== "object") {
-        if ([1, "1", "true"].includes(val)) {
+        const normalized = typeof val === "string" ? val.toLowerCase() : val;
+        if ([1, "1", "true", "yes"].includes(normalized)) {
           return true;
         }
-        if ([0, "0", "false"].includes(val)) {
+        if ([0, "0", "false", "no"].includes(normalized)) {
           return false;
         }
       }
@@ -521,13 +530,33 @@ var OptionBase = class {
         });
         return new InvalidValue();
       }
-      if (val == null) {
+      if (val === void 0) {
+        return new InvalidValue();
+      }
+      if (val === null) {
+        errors?.errors.push({
+          message: `Option '${path2.join(".")}' is null \u2014 expected an object to traverse into`,
+          kind: "null_value"
+        });
         return new InvalidValue();
       }
       return this.findInObject(val, rest, errors);
     }
     if (path2.length === 1) {
       const val = obj[path2[0]];
+      if (val === null) {
+        if (this.params.required) {
+          errors?.errors.push({
+            message: `Option '${path2.join(".")}' is null \u2014 expected a ${this.params.kind}`,
+            kind: "null_value"
+          });
+        } else {
+          errors?.warnings.push(
+            `Option '${path2.join(".")}' is null and will be treated as unset`
+          );
+        }
+        return new InvalidValue();
+      }
       if (!Array.isArray(val) && typeof val === "object" && val || typeof val === "string" || typeof val === "number" || typeof val === "boolean" || typeof val === "undefined") {
         return val;
       }
@@ -754,8 +783,23 @@ var Settings = class {
     this.envFileResults = envFileResults;
     this.envData = mergedEnvData;
   }
+  checkEnvMappingsWithoutEnvLoading() {
+    if (this.sources.env || this.sources.envFile) return;
+    const envMappedOptions = [];
+    this.traverseOptions(this.schema, [], (node, path2) => {
+      if (node.params.env) {
+        envMappedOptions.push(path2.join("."));
+      }
+    });
+    if (envMappedOptions.length > 0) {
+      this.errors.warnings.push(
+        `Options [${envMappedOptions.join(", ")}] have env mappings but env loading is disabled. Set 'env: true' in load options to read from environment variables.`
+      );
+    }
+  }
   load() {
     this.validateAndLoadFiles();
+    this.checkEnvMappingsWithoutEnvLoading();
     if (this.sources.env) {
       this.envData = { ...process.env };
     }
@@ -780,18 +824,13 @@ var Settings = class {
         errors: this.errors
       })
     );
-    if (this.errors.warnings.length > 0) {
-      for (let index = 0; index < this.errors.warnings.length; index += 1) {
-        console.warn(`[Warning]: ${this.errors.warnings[index]}`);
+    if (this.sources.strict && this.errors.warnings.length > 0) {
+      for (const warning of this.errors.warnings) {
+        this.errors.errors.push({ message: warning, kind: "strict" });
       }
+      this.errors.warnings = [];
     }
     if (this.errors.errors.length > 0) {
-      if (this.sources.exitOnError) {
-        for (let index = 0; index < this.errors.errors.length; index += 1) {
-          console.error(`[Error]: ${this.errors.errors[index].message}`);
-        }
-        process.exit(1);
-      }
       throw new ConfigLoadError(
         [...this.errors.errors],
         [...this.errors.warnings]
@@ -922,8 +961,7 @@ var Settings = class {
       return node.value;
     }
     return Object.entries(node).reduce(
-      (acc, item) => {
-        const [key, value] = item;
+      (acc, [key, value]) => {
         acc[key] = this.getValuesFromTree(value);
         return acc;
       },
@@ -938,6 +976,9 @@ var Settings = class {
   getExtended() {
     return this.optionsTree;
   }
+  getWarnings() {
+    return [...this.errors.warnings];
+  }
 };
 var settings_default = Settings;
 
@@ -947,13 +988,28 @@ var SettingsBuilder = class {
   constructor(schema2) {
     this.schema = schema2;
   }
+  /**
+   * Loads and validates configuration, returning a fully-typed plain object.
+   * @param sources - Which sources to read (env, args, files, etc.).
+   * @returns The resolved configuration object matching the schema type.
+   * @throws {ConfigLoadError} If validation fails (missing required fields, type errors, etc.).
+   */
   load(sources) {
     const settings = new settings_default(this.schema, sources);
     return settings.get();
   }
+  /**
+   * Loads configuration and returns raw node data with source metadata alongside warnings.
+   * @param sources - Which sources to read (env, args, files, etc.).
+   * @returns An `ExtendedResult` containing the node tree and any warnings.
+   * @throws {ConfigLoadError} If validation fails.
+   */
   loadExtended(sources) {
     const settings = new settings_default(this.schema, sources);
-    return settings.getExtended();
+    return {
+      data: settings.getExtended(),
+      warnings: settings.getWarnings()
+    };
   }
 };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meltstudio/config-loader",
-  "version": "2.0.1",
+  "version": "3.0.0",
   "description": "Melt Studio's tool for loading configurations into a Node.js application.",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -53,6 +53,7 @@
     "@types/jest": "^30.0.0",
     "@types/js-yaml": "^4.0.5",
     "@types/node": "^22.0.0",
+    "docusaurus-plugin-llms": "^0.3.0",
     "eslint": "^10.0.0",
     "eslint-config-prettier": "^10.0.0",
     "eslint-plugin-jest": "^29.0.0",