@meltstudio/config-loader 3.0.1 → 3.1.0

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

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,36 @@ 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>;
+}
+/**
+ * Minimal Standard Schema v1 interface for value validation.
+ * Any object with a `~standard.validate()` method is accepted — this covers
+ * Zod 3.24+, Valibot 1.0+, ArkType 2.1+, and custom validators.
+ */
+interface StandardSchemaV1<Output = unknown> {
+    "~standard": {
+        version: 1;
+        vendor: string;
+        validate(value: unknown): {
+            value: Output;
+        } | {
+            issues: ReadonlyArray<StandardSchemaIssue>;
+        };
+    };
+}
 
 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 +193,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;
@@ -205,6 +234,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 +245,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 +254,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 +279,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, type ExtendedResult, type StandardSchemaV1, option as default };

package/dist/index.js

@@ -272,6 +272,22 @@ 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) {
@@ -413,6 +429,27 @@ var OptionBase = class {
     }
     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 ("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) {
+        errors?.errors.push({
+          message: `Validation failed for '${ident}': ${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);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meltstudio/config-loader",
-  "version": "3.0.1",
+  "version": "3.1.0",
   "description": "Melt Studio's tool for loading configurations into a Node.js application.",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",