@meltstudio/config-loader 3.0.2 → 3.2.0

package/LICENSE

@@ -1,201 +1,21 @@
-                                 Apache License
-                           Version 2.0, January 2004
-                        http://www.apache.org/licenses/
-
-   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
-
-   1. Definitions.
-
-      "License" shall mean the terms and conditions for use, reproduction,
-      and distribution as defined by Sections 1 through 9 of this document.
-
-      "Licensor" shall mean the copyright owner or entity authorized by
-      the copyright owner that is granting the License.
-
-      "Legal Entity" shall mean the union of the acting entity and all
-      other entities that control, are controlled by, or are under common
-      control with that entity. For the purposes of this definition,
-      "control" means (i) the power, direct or indirect, to cause the
-      direction or management of such entity, whether by contract or
-      otherwise, or (ii) ownership of fifty percent (50%) or more of the
-      outstanding shares, or (iii) beneficial ownership of such entity.
-
-      "You" (or "Your") shall mean an individual or Legal Entity
-      exercising permissions granted by this License.
-
-      "Source" form shall mean the preferred form for making modifications,
-      including but not limited to software source code, documentation
-      source, and configuration files.
-
-      "Object" form shall mean any form resulting from mechanical
-      transformation or translation of a Source form, including but
-      not limited to compiled object code, generated documentation,
-      and conversions to other media types.
-
-      "Work" shall mean the work of authorship, whether in Source or
-      Object form, made available under the License, as indicated by a
-      copyright notice that is included in or attached to the work
-      (an example is provided in the Appendix below).
-
-      "Derivative Works" shall mean any work, whether in Source or Object
-      form, that is based on (or derived from) the Work and for which the
-      editorial revisions, annotations, elaborations, or other modifications
-      represent, as a whole, an original work of authorship. For the purposes
-      of this License, Derivative Works shall not include works that remain
-      separable from, or merely link (or bind by name) to the interfaces of,
-      the Work and Derivative Works thereof.
-
-      "Contribution" shall mean any work of authorship, including
-      the original version of the Work and any modifications or additions
-      to that Work or Derivative Works thereof, that is intentionally
-      submitted to Licensor for inclusion in the Work by the copyright owner
-      or by an individual or Legal Entity authorized to submit on behalf of
-      the copyright owner. For the purposes of this definition, "submitted"
-      means any form of electronic, verbal, or written communication sent
-      to the Licensor or its representatives, including but not limited to
-      communication on electronic mailing lists, source code control systems,
-      and issue tracking systems that are managed by, or on behalf of, the
-      Licensor for the purpose of discussing and improving the Work, but
-      excluding communication that is conspicuously marked or otherwise
-      designated in writing by the copyright owner as "Not a Contribution."
-
-      "Contributor" shall mean Licensor and any individual or Legal Entity
-      on behalf of whom a Contribution has been received by Licensor and
-      subsequently incorporated within the Work.
-
-   2. Grant of Copyright License. Subject to the terms and conditions of
-      this License, each Contributor hereby grants to You a perpetual,
-      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
-      copyright license to reproduce, prepare Derivative Works of,
-      publicly display, publicly perform, sublicense, and distribute the
-      Work and such Derivative Works in Source or Object form.
-
-   3. Grant of Patent License. Subject to the terms and conditions of
-      this License, each Contributor hereby grants to You a perpetual,
-      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
-      (except as stated in this section) patent license to make, have made,
-      use, offer to sell, sell, import, and otherwise transfer the Work,
-      where such license applies only to those patent claims licensable
-      by such Contributor that are necessarily infringed by their
-      Contribution(s) alone or by combination of their Contribution(s)
-      with the Work to which such Contribution(s) was submitted. If You
-      institute patent litigation against any entity (including a
-      cross-claim or counterclaim in a lawsuit) alleging that the Work
-      or a Contribution incorporated within the Work constitutes direct
-      or contributory patent infringement, then any patent licenses
-      granted to You under this License for that Work shall terminate
-      as of the date such litigation is filed.
-
-   4. Redistribution. You may reproduce and distribute copies of the
-      Work or Derivative Works thereof in any medium, with or without
-      modifications, and in Source or Object form, provided that You
-      meet the following conditions:
-
-      (a) You must give any other recipients of the Work or
-          Derivative Works a copy of this License; and
-
-      (b) You must cause any modified files to carry prominent notices
-          stating that You changed the files; and
-
-      (c) You must retain, in the Source form of any Derivative Works
-          that You distribute, all copyright, patent, trademark, and
-          attribution notices from the Source form of the Work,
-          excluding those notices that do not pertain to any part of
-          the Derivative Works; and
-
-      (d) If the Work includes a "NOTICE" text file as part of its
-          distribution, then any Derivative Works that You distribute must
-          include a readable copy of the attribution notices contained
-          within such NOTICE file, excluding those notices that do not
-          pertain to any part of the Derivative Works, in at least one
-          of the following places: within a NOTICE text file distributed
-          as part of the Derivative Works; within the Source form or
-          documentation, if provided along with the Derivative Works; or,
-          within a display generated by the Derivative Works, if and
-          wherever such third-party notices normally appear. The contents
-          of the NOTICE file are for informational purposes only and
-          do not modify the License. You may add Your own attribution
-          notices within Derivative Works that You distribute, alongside
-          or as an addendum to the NOTICE text from the Work, provided
-          that such additional attribution notices cannot be construed
-          as modifying the License.
-
-      You may add Your own copyright statement to Your modifications and
-      may provide additional or different license terms and conditions
-      for use, reproduction, or distribution of Your modifications, or
-      for any such Derivative Works as a whole, provided Your use,
-      reproduction, and distribution of the Work otherwise complies with
-      the conditions stated in this License.
-
-   5. Submission of Contributions. Unless You explicitly state otherwise,
-      any Contribution intentionally submitted for inclusion in the Work
-      by You to the Licensor shall be under the terms and conditions of
-      this License, without any additional terms or conditions.
-      Notwithstanding the above, nothing herein shall supersede or modify
-      the terms of any separate license agreement you may have executed
-      with Licensor regarding such Contributions.
-
-   6. Trademarks. This License does not grant permission to use the trade
-      names, trademarks, service marks, or product names of the Licensor,
-      except as required for reasonable and customary use in describing the
-      origin of the Work and reproducing the content of the NOTICE file.
-
-   7. Disclaimer of Warranty. Unless required by applicable law or
-      agreed to in writing, Licensor provides the Work (and each
-      Contributor provides its Contributions) on an "AS IS" BASIS,
-      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
-      implied, including, without limitation, any warranties or conditions
-      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
-      PARTICULAR PURPOSE. You are solely responsible for determining the
-      appropriateness of using or redistributing the Work and assume any
-      risks associated with Your exercise of permissions under this License.
-
-   8. Limitation of Liability. In no event and under no legal theory,
-      whether in tort (including negligence), contract, or otherwise,
-      unless required by applicable law (such as deliberate and grossly
-      negligent acts) or agreed to in writing, shall any Contributor be
-      liable to You for damages, including any direct, indirect, special,
-      incidental, or consequential damages of any character arising as a
-      result of this License or out of the use or inability to use the
-      Work (including but not limited to damages for loss of goodwill,
-      work stoppage, computer failure or malfunction, or any and all
-      other commercial damages or losses), even if such Contributor
-      has been advised of the possibility of such damages.
-
-   9. Accepting Warranty or Additional Liability. While redistributing
-      the Work or Derivative Works thereof, You may choose to offer,
-      and charge a fee for, acceptance of support, warranty, indemnity,
-      or other liability obligations and/or rights consistent with this
-      License. However, in accepting such obligations, You may act only
-      on Your own behalf and on Your sole responsibility, not on behalf
-      of any other Contributor, and only if You agree to indemnify,
-      defend, and hold each Contributor harmless for any liability
-      incurred by, or claims asserted against, such Contributor by reason
-      of your accepting any such warranty or additional liability.
-
-   END OF TERMS AND CONDITIONS
-
-   APPENDIX: How to apply the Apache License to your work.
-
-      To apply the Apache License to your work, attach the following
-      boilerplate notice, with the fields enclosed by brackets "[]"
-      replaced with your own identifying information. (Don't include
-      the brackets!)  The text should be enclosed in the appropriate
-      comment syntax for the file format. We also recommend that a
-      file or class name and description of purpose be included on the
-      same "printed page" as the copyright notice for easier
-      identification within third-party archives.
-
-   Copyright [yyyy] [name of copyright owner]
-
-   Licensed under the Apache License, Version 2.0 (the "License");
-   you may not use this file except in compliance with the License.
-   You may obtain a copy of the License at
-
-       http://www.apache.org/licenses/LICENSE-2.0
-
-   Unless required by applicable law or agreed to in writing, software
-   distributed under the License is distributed on an "AS IS" BASIS,
-   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-   See the License for the specific language governing permissions and
-   limitations under the License.
+MIT License
+
+Copyright (c) 2024 MeltStudio
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -61,6 +61,7 @@ No separate interface to maintain. No `as` casts. The types flow from the schema
 - **`.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 and warnings
+- **Schema validation** — optional per-field validation via [Standard Schema](https://github.com/standard-schema/standard-schema) (Zod, Valibot, ArkType, or custom)
 - **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
@@ -252,6 +253,74 @@ c.array({
 }); // { name: string; age: number }[]
 ```
 
+## Validation
+
+Add per-field validation using the `validate` option. config-loader accepts any [Standard Schema v1](https://github.com/standard-schema/standard-schema) implementation — including **Zod**, **Valibot**, and **ArkType** — or a custom validator.
+
+Validation runs **after** type coercion, so validators see the final typed value (e.g., the number `3000`, not the string `"3000"` from an env var).
+
+### With Zod
+
+```typescript
+import c from "@meltstudio/config-loader";
+import { z } from "zod";
+
+const config = c
+  .schema({
+    port: c.number({
+      required: true,
+      env: "PORT",
+      validate: z.number().min(1).max(65535),
+    }),
+    host: c.string({
+      required: true,
+      validate: z.string().url(),
+    }),
+    env: c.string({
+      defaultValue: "development",
+      validate: z.enum(["development", "staging", "production"]),
+    }),
+  })
+  .load({ env: true, args: false, files: "./config.yaml" });
+```
+
+### With a custom validator
+
+Any object with a `~standard.validate()` method works:
+
+```typescript
+const portValidator = {
+  "~standard": {
+    version: 1,
+    vendor: "my-app",
+    validate(value: unknown) {
+      if (typeof value === "number" && value >= 1 && value <= 65535) {
+        return { value };
+      }
+      return { issues: [{ message: "must be a valid port (1-65535)" }] };
+    },
+  },
+};
+
+c.number({ required: true, env: "PORT", validate: portValidator });
+```
+
+Validation errors are collected alongside other config errors and thrown as `ConfigLoadError` with `kind: "validation"`:
+
+```typescript
+try {
+  const config = c.schema({ ... }).load({ ... });
+} catch (err) {
+  if (err instanceof ConfigLoadError) {
+    for (const entry of err.errors) {
+      if (entry.kind === "validation") {
+        console.error(`Validation: ${entry.path} — ${entry.message}`);
+      }
+    }
+  }
+}
+```
+
 ## Loading Sources
 
 ```typescript
@@ -313,6 +382,41 @@ 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.
 
+### Debug Helper
+
+Use `printConfig()` to format the result of `loadExtended()` as a readable table:
+
+```typescript
+import c, { printConfig } from "@meltstudio/config-loader";
+
+const result = c
+  .schema({
+    host: c.string({ defaultValue: "localhost" }),
+    port: c.number({ env: "PORT" }),
+    debug: c.bool({ cli: true }),
+  })
+  .loadExtended({ env: true, args: true, files: "./config.yaml" });
+
+printConfig(result);
+```
+
+Output:
+
+```
+┌───────┬───────────┬─────────┬────────────────┐
+│ Path  │ Value     │ Source  │ Detail         │
+├───────┼───────────┼─────────┼────────────────┤
+│ host  │ localhost │ default │                │
+│ port  │ 8080      │ env     │ PORT           │
+│ debug │ true      │ args    │ --debug        │
+└───────┴───────────┴─────────┴────────────────┘
+```
+
+Options:
+
+- `printConfig(result, { silent: true })` — returns the string without printing to console
+- `printConfig(result, { maxValueLength: 30 })` — truncate long values (default: 50)
+
 ## Error Handling
 
 When validation fails, config-loader throws a `ConfigLoadError` with structured error details:
@@ -353,6 +457,35 @@ Enable `strict: true` to promote all warnings to errors, causing `ConfigLoadErro
 
 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.
 
+## TypeScript Utilities
+
+config-loader exports several types for advanced use cases:
+
+```typescript
+import c, {
+  type SchemaValue, // Infer the resolved config type from a schema
+  type SettingsSources, // Type for the sources object passed to load()
+  type ExtendedResult, // Return type of loadExtended()
+  type NodeTree, // Tree of ConfigNode objects (ExtendedResult.data)
+  ConfigNode, // Class representing a resolved value with source metadata
+  ConfigNodeArray, // Class representing an array of ConfigNode values
+  type RecursivePartial, // Deep partial utility used by the defaults option
+  type StandardSchemaV1, // Standard Schema v1 interface for validators
+} from "@meltstudio/config-loader";
+```
+
+The most commonly needed is `SchemaValue`, which infers the plain TypeScript type from a schema:
+
+```typescript
+const mySchema = {
+  port: c.number({ env: "PORT" }),
+  db: c.object({ item: { host: c.string(), port: c.number() } }),
+};
+
+type MyConfig = SchemaValue<typeof mySchema>;
+// { port: number; db: { host: string; port: number } }
+```
+
 ## CLI Arguments
 
 Set `cli: true` on an option to allow overriding via command line:
@@ -612,4 +745,4 @@ These files follow the [llms.txt standard](https://llmstxt.org/) and are generat
 
 ## License
 
-This package is licensed under the Apache License 2.0. See the [LICENSE](./LICENSE) file for details.
+This package is licensed under the MIT License. See the [LICENSE](./LICENSE) file for details.

package/dist/index.d.ts

@@ -23,7 +23,7 @@ interface ConfigErrorEntry {
     /** The source where the error originated (e.g. file path, `"env"`, `"cli"`). */
     source?: string;
     /** Classification of the error. */
-    kind?: "required" | "type_conversion" | "invalid_path" | "invalid_state" | "file_validation" | "null_value" | "strict";
+    kind?: "required" | "type_conversion" | "invalid_path" | "invalid_state" | "file_validation" | "null_value" | "strict" | "validation";
     /** 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. */
@@ -61,6 +61,7 @@ interface OptionClassParams<T extends OptionKind> {
     cli: boolean;
     help: string;
     defaultValue?: TypedDefaultValue<T>;
+    validate?: StandardSchemaV1;
 }
 declare class OptionBase<T extends OptionKind = OptionKind> {
     readonly params: OptionClassParams<T>;
@@ -79,6 +80,8 @@ declare class OptionBase<T extends OptionKind = OptionKind> {
             } | undefined;
         } | null;
     }, envFileResults?: EnvFileResult[], errors?: OptionErrors): ConfigNode | null;
+    private resolveValue;
+    private runValidation;
     private resolveFromFileData;
     checkType(val: Value, path: Path, sourceOfVal: string, errors?: OptionErrors): Value;
     protected findInObject(obj: ConfigFileData, path: Path, errors?: OptionErrors): Value | ArrayValue;
@@ -149,11 +152,37 @@ interface ConfigFileData extends ConfigFileStructure<ConfigFileData> {
 type ArrayValue = Array<string | number | boolean | ConfigFileData>;
 declare class InvalidValue {
 }
+/**
+ * A single issue returned by a Standard Schema validator.
+ * Mirrors the Standard Schema v1 spec (https://github.com/standard-schema/standard-schema).
+ */
+interface StandardSchemaIssue {
+    message: string;
+    path?: ReadonlyArray<PropertyKey | object>;
+}
+type StandardSchemaResult<Output> = {
+    value: Output;
+} | {
+    issues: ReadonlyArray<StandardSchemaIssue>;
+};
+/**
+ * Minimal Standard Schema v1 interface for value validation.
+ * Any object with a `~standard.validate()` method is accepted — this covers
+ * Zod 3.24+/4+, Valibot 1.0+, ArkType 2.1+, and custom validators.
+ */
+interface StandardSchemaV1<Output = unknown> {
+    "~standard": {
+        version: 1;
+        vendor: string;
+        validate(value: unknown): StandardSchemaResult<Output> | Promise<StandardSchemaResult<Output>>;
+    };
+}
 
 interface ArrayOptionClassParams<T extends OptionTypes> {
     required: boolean;
     defaultValue?: SchemaValue<T>[] | (() => SchemaValue<T>[]);
     item: T;
+    validate?: StandardSchemaV1;
 }
 declare class ArrayOption<T extends OptionTypes> extends OptionBase<"array"> {
     item: T;
@@ -165,6 +194,7 @@ declare class ArrayOption<T extends OptionTypes> extends OptionBase<"array"> {
 interface ObjectOptionClassParams<T extends Node> {
     required: boolean;
     item: T;
+    validate?: StandardSchemaV1;
 }
 declare class ObjectOption<T extends Node = Node> extends OptionBase<"object"> {
     item: T;
@@ -193,6 +223,31 @@ declare class SettingsBuilder<T extends Node> {
     loadExtended(sources: SettingsSources<SchemaValue<T>>): ExtendedResult;
 }
 
+declare class ConfigNodeArray {
+    arrayValues: ConfigNode[];
+    constructor(arrayValues: ConfigNode[]);
+}
+
+/**
+ * Formats the result of `loadExtended()` as a readable table showing each
+ * resolved value and where it came from.
+ *
+ * @param result - The `ExtendedResult` returned by `loadExtended()`.
+ * @param options - Optional settings.
+ * @param options.maxValueLength - Maximum length for value column (default: 50). Values longer than this are truncated.
+ * @returns The formatted table string. Also printed to `console.log` unless `options.silent` is `true`.
+ *
+ * @example
+ * ```ts
+ * const result = c.schema({ port: c.number({ env: "PORT" }) }).loadExtended({ env: true, args: false });
+ * printConfig(result);
+ * ```
+ */
+declare function printConfig(result: ExtendedResult, options?: {
+    silent?: boolean;
+    maxValueLength?: number;
+}): string;
+
 /** Options for configuring a primitive (`string`, `number`, `bool`) schema field. */
 interface OptionPropsArgs<T> {
     /** Whether the field must be present in at least one source. */
@@ -205,6 +260,8 @@ interface OptionPropsArgs<T> {
     defaultValue?: T | (() => T);
     /** Help text shown in CLI `--help` output. */
     help?: string;
+    /** Standard Schema validator run after type coercion. Accepts Zod, Valibot, ArkType, or any Standard Schema v1 implementation. */
+    validate?: StandardSchemaV1;
 }
 /** Options for configuring an `array` schema field. */
 interface ArrayOptionPropsArgs<T extends OptionTypes> {
@@ -214,6 +271,8 @@ interface ArrayOptionPropsArgs<T extends OptionTypes> {
     item: T;
     /** Static default value or factory function returning one. */
     defaultValue?: SchemaValue<T>[] | (() => SchemaValue<T>[]);
+    /** Standard Schema validator run on the resolved array. Accepts Zod, Valibot, ArkType, or any Standard Schema v1 implementation. */
+    validate?: StandardSchemaV1;
 }
 /** Options for configuring a nested `object` schema field. */
 interface ObjectOptionPropsArgs<T extends Node> {
@@ -221,6 +280,8 @@ interface ObjectOptionPropsArgs<T extends Node> {
     required?: boolean;
     /** Schema definition for the nested object's shape. */
     item: T;
+    /** Standard Schema validator run on the resolved object. Accepts Zod, Valibot, ArkType, or any Standard Schema v1 implementation. */
+    validate?: StandardSchemaV1;
 }
 /**
  * Config-loader entry point. Provides factory functions to define a typed configuration schema.
@@ -244,4 +305,4 @@ declare const option: {
     schema: <T extends Node>(theSchema: T) => SettingsBuilder<T>;
 };
 
-export { type ConfigErrorEntry, ConfigFileError, ConfigLoadError, type ExtendedResult, option as default };
+export { type ConfigErrorEntry, ConfigFileError, ConfigLoadError, ConfigNode, ConfigNodeArray, type ExtendedResult, type NodeTree, type RecursivePartial, type SchemaValue, type SettingsSources, type StandardSchemaV1, option as default, printConfig };

package/dist/index.js

@@ -32,7 +32,10 @@ var index_exports = {};
 __export(index_exports, {
   ConfigFileError: () => ConfigFileError,
   ConfigLoadError: () => ConfigLoadError,
-  default: () => index_default
+  ConfigNode: () => configNode_default,
+  ConfigNodeArray: () => configNodeArray_default,
+  default: () => index_default,
+  printConfig: () => printConfig
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -46,7 +49,14 @@ var ConfigLoadError = class extends Error {
   /** Non-fatal warnings collected during loading. */
   warnings;
   constructor(errors, warnings) {
-    const message = `Configuration loading failed with ${errors.length} error${errors.length === 1 ? "" : "s"}`;
+    const count = errors.length;
+    const summary = `Configuration loading failed with ${count} error${count === 1 ? "" : "s"}`;
+    const details = errors.slice(0, 10).map((e, i) => `  ${i + 1}. ${e.message}`).join("\n");
+    const message = count > 0 ? `${summary}:
+${details}` : (
+      /* istanbul ignore next */
+      summary
+    );
     super(message);
     this.name = "ConfigLoadError";
     this.errors = errors;
@@ -272,11 +282,27 @@ var OptionBase = class {
     this.params = params;
   }
   getValue(sourceFile, env, args, path2, defaultValues, objectFromArray, envFileResults, errors) {
+    const resolved = this.resolveValue(
+      sourceFile,
+      env,
+      args,
+      path2,
+      defaultValues,
+      objectFromArray,
+      envFileResults,
+      errors
+    );
+    if (resolved && this.params.validate) {
+      this.runValidation(resolved, path2, errors);
+    }
+    return resolved;
+  }
+  resolveValue(sourceFile, env, args, path2, defaultValues, objectFromArray, envFileResults, errors) {
     const ident = path2.join(".");
     if (this.params.cli && args) {
       if (ident in args) {
         return new configNode_default(
-          this.checkType(args[ident], path2, "args", errors),
+          this.checkType(args[ident], path2, `CLI argument --${ident}`, errors),
           ident,
           "args",
           null,
@@ -296,7 +322,12 @@ var OptionBase = class {
           );
           if (envFileSource) {
             return new configNode_default(
-              this.checkType(val, path2, "envFile", errors),
+              this.checkType(
+                val,
+                path2,
+                `env file ${envFileSource.filePath} (${this.params.env})`,
+                errors
+              ),
               ident,
               "envFile",
               envFileSource.filePath,
@@ -307,7 +338,12 @@ var OptionBase = class {
             );
           }
           return new configNode_default(
-            this.checkType(val, path2, "env", errors),
+            this.checkType(
+              val,
+              path2,
+              `environment variable ${this.params.env}`,
+              errors
+            ),
             ident,
             "env",
             null,
@@ -405,14 +441,47 @@ var OptionBase = class {
       }
     }
     if (this.params.required) {
+      const hints = [];
+      if (this.params.env)
+        hints.push(`environment variable ${this.params.env}`);
+      if (this.params.cli) hints.push(`CLI argument --${ident}`);
+      hints.push(`config file key: ${ident}`);
+      const hint = hints.join(", ");
       errors?.errors.push({
-        message: `Required option '${ident}' not provided.`,
+        message: `Required option '${ident}' is missing. Set it via ${hint}.`,
         path: ident,
         kind: "required"
       });
     }
     return null;
   }
+  runValidation(node, path2, errors) {
+    const validator = this.params.validate;
+    if (!validator) return;
+    const value = node.value;
+    if (valueIsInvalid(value)) return;
+    const result = validator["~standard"].validate(value);
+    if (result instanceof Promise) {
+      throw new Error(
+        "Async validators are not supported. The validate function must return a synchronous result."
+      );
+    }
+    if ("issues" in result && result.issues) {
+      const ident = path2.join(".");
+      const source = node.file ?? node.variableName ?? node.argName ?? node.sourceType;
+      for (const issue of result.issues) {
+        const sourceLabel = source !== node.sourceType ? ` (source: ${source})` : "";
+        errors?.errors.push({
+          message: `Validation failed for '${ident}'${sourceLabel}: ${issue.message}`,
+          path: ident,
+          source,
+          kind: "validation",
+          line: node.line ?? void 0,
+          column: node.column ?? void 0
+        });
+      }
+    }
+  }
   resolveFromFileData(data, file, sourceMap, path2, ident, errors) {
     const val = this.findInObject(data, path2, errors);
     const loc = lookupLocation(sourceMap, path2);
@@ -504,28 +573,28 @@ var OptionBase = class {
       const val = obj[child];
       if (typeof val === "string") {
         errors?.errors.push({
-          message: `Cant get path from string value '${val}'`,
+          message: `Cannot traverse into '${path2.join(".")}': expected an object but found a string '${val}'`,
           kind: "invalid_path"
         });
         return new InvalidValue();
       }
       if (typeof val === "number") {
         errors?.errors.push({
-          message: `Cant get path from number value '${val}'`,
+          message: `Cannot traverse into '${path2.join(".")}': expected an object but found a number '${val}'`,
           kind: "invalid_path"
         });
         return new InvalidValue();
       }
       if (typeof val === "boolean") {
         errors?.errors.push({
-          message: `Cant get path from boolean value '${val.toString()}'`,
+          message: `Cannot traverse into '${path2.join(".")}': expected an object but found a boolean '${val.toString()}'`,
           kind: "invalid_path"
         });
         return new InvalidValue();
       }
       if (Array.isArray(val)) {
         errors?.errors.push({
-          message: `Cant get path from array value '${valueToString(val)}'`,
+          message: `Cannot traverse into '${path2.join(".")}': expected an object but found an array '${valueToString(val)}'`,
           kind: "invalid_path"
         });
         return new InvalidValue();
@@ -700,7 +769,7 @@ function validateFiles(files, dir) {
       const result = [];
       files.forEach((file) => {
         if (!fs3.existsSync(file)) {
-          throw new ConfigFileError(`Invalid config file '${file}'`);
+          throw new ConfigFileError(`Config file '${file}' does not exist`);
         } else {
           result.push(file);
         }
@@ -708,14 +777,16 @@ function validateFiles(files, dir) {
       sourceFile = result;
     } else {
       if (!fs3.existsSync(files)) {
-        throw new ConfigFileError(`Invalid config file '${files}'`);
+        throw new ConfigFileError(`Config file '${files}' does not exist`);
       }
       sourceFile = files;
     }
   }
   if (dir) {
     if (!(fs3.existsSync(dir) && fs3.lstatSync(dir).isDirectory())) {
-      throw new ConfigFileError(`'${dir}' not exists or is not a dir`);
+      throw new ConfigFileError(
+        `Config directory '${dir}' does not exist or is not a directory`
+      );
     }
     const filesInDirectory = fs3.readdirSync(dir).sort();
     if (filesInDirectory.length === 0) {
@@ -1013,6 +1084,127 @@ var SettingsBuilder = class {
   }
 };
 
+// src/printConfig.ts
+function truncate(str, max) {
+  if (str.length <= max) return str;
+  return str.slice(0, max - 3) + "...";
+}
+function formatValue(val) {
+  if (val === null || val === void 0) return "";
+  if (typeof val === "object") return JSON.stringify(val) ?? "";
+  if (typeof val === "string") return val;
+  return `${val}`;
+}
+function formatDetail(node) {
+  const parts = [];
+  if (node.sourceType === "file" || node.sourceType === "envFile") {
+    if (node.file) {
+      let loc = node.file;
+      if (node.line != null) {
+        loc += `:${node.line}`;
+        if (node.column != null) loc += `:${node.column}`;
+      }
+      parts.push(loc);
+    }
+    if (node.sourceType === "envFile" && node.variableName) {
+      parts.push(`(${node.variableName})`);
+    }
+  } else if (node.sourceType === "env" && node.variableName) {
+    parts.push(node.variableName);
+  } else if (node.sourceType === "args" && node.argName) {
+    parts.push(`--${node.argName}`);
+  }
+  return parts.join(" ");
+}
+function flattenTree(tree, prefix = "") {
+  const rows = [];
+  for (const [key, entry] of Object.entries(tree)) {
+    const path2 = prefix ? `${prefix}.${key}` : key;
+    if (entry instanceof configNode_default) {
+      if (entry.value instanceof configNodeArray_default) {
+        for (let i = 0; i < entry.value.arrayValues.length; i++) {
+          const child = entry.value.arrayValues[i];
+          const arrayPath = `${path2}[${i}]`;
+          if (child.value && typeof child.value === "object" && !(child.value instanceof configNodeArray_default)) {
+            const nested = child.value;
+            rows.push(...flattenTree(nested, arrayPath));
+          } else {
+            rows.push({
+              path: arrayPath,
+              value: formatValue(child.value),
+              source: child.sourceType,
+              detail: formatDetail(child)
+            });
+          }
+        }
+      } else {
+        rows.push({
+          path: path2,
+          value: formatValue(entry.value),
+          source: entry.sourceType,
+          detail: formatDetail(entry)
+        });
+      }
+    } else {
+      rows.push(...flattenTree(entry, path2));
+    }
+  }
+  return rows;
+}
+function padRight(str, len) {
+  return str + " ".repeat(Math.max(0, len - str.length));
+}
+function buildTable(rows) {
+  const headers = {
+    path: "Path",
+    value: "Value",
+    source: "Source",
+    detail: "Detail"
+  };
+  const widths = {
+    path: Math.max(headers.path.length, ...rows.map((r) => r.path.length)),
+    value: Math.max(headers.value.length, ...rows.map((r) => r.value.length)),
+    source: Math.max(
+      headers.source.length,
+      ...rows.map((r) => r.source.length)
+    ),
+    detail: Math.max(
+      headers.detail.length,
+      ...rows.map((r) => r.detail.length)
+    )
+  };
+  const hr = `\u251C${"\u2500".repeat(widths.path + 2)}\u253C${"\u2500".repeat(widths.value + 2)}\u253C${"\u2500".repeat(widths.source + 2)}\u253C${"\u2500".repeat(widths.detail + 2)}\u2524`;
+  const top = `\u250C${"\u2500".repeat(widths.path + 2)}\u252C${"\u2500".repeat(widths.value + 2)}\u252C${"\u2500".repeat(widths.source + 2)}\u252C${"\u2500".repeat(widths.detail + 2)}\u2510`;
+  const bottom = `\u2514${"\u2500".repeat(widths.path + 2)}\u2534${"\u2500".repeat(widths.value + 2)}\u2534${"\u2500".repeat(widths.source + 2)}\u2534${"\u2500".repeat(widths.detail + 2)}\u2518`;
+  const formatRow = (r) => `\u2502 ${padRight(r.path, widths.path)} \u2502 ${padRight(r.value, widths.value)} \u2502 ${padRight(r.source, widths.source)} \u2502 ${padRight(r.detail, widths.detail)} \u2502`;
+  const lines = [top, formatRow(headers), hr, ...rows.map(formatRow), bottom];
+  return lines.join("\n");
+}
+function printConfig(result, options) {
+  const maxLen = options?.maxValueLength ?? 50;
+  const rows = flattenTree(result.data).map((r) => ({
+    ...r,
+    value: truncate(r.value, maxLen)
+  }));
+  let output;
+  if (rows.length === 0) {
+    output = "No configuration values loaded.";
+  } else {
+    output = buildTable(rows);
+  }
+  if (result.warnings.length > 0) {
+    output += "\n\nWarnings:";
+    for (const w of result.warnings) {
+      output += `
+  - ${w}`;
+    }
+  }
+  if (!options?.silent) {
+    console.log(output);
+  }
+  return output;
+}
+
 // src/index.ts
 var DEFAULTS = {
   required: false,
@@ -1068,5 +1260,8 @@ var index_default = option;
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ConfigFileError,
-  ConfigLoadError
+  ConfigLoadError,
+  ConfigNode,
+  ConfigNodeArray,
+  printConfig
 });

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@meltstudio/config-loader",
-  "version": "3.0.2",
-  "description": "Melt Studio's tool for loading configurations into a Node.js application.",
+  "version": "3.2.0",
+  "description": "Type-safe configuration loader with full TypeScript inference. Load from YAML, JSON, .env, environment variables, and CLI args.",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "repository": "https://github.com/MeltStudio/config-loader",
   "author": "MeltStudio <dev@meltstudio.co>",
-  "license": "Apache-2.0",
+  "license": "MIT",
   "engines": {
     "node": ">=20"
   },
@@ -14,8 +14,18 @@
     "configuration",
     "config",
     "yaml",
+    "json",
     "loader",
-    "config-node"
+    "env",
+    "environment",
+    "dotenv",
+    "cli",
+    "type-safe",
+    "typescript",
+    "schema",
+    "validation",
+    "zod",
+    "settings"
   ],
   "files": [
     "dist",
@@ -73,6 +83,7 @@
     "tsconfig-paths": "^4.2.0",
     "tsup": "^8.0.0",
     "typescript": "^5.0.4",
-    "typescript-eslint": "^8.24.0"
+    "typescript-eslint": "^8.24.0",
+    "zod": "^4.3.6"
   }
 }