feat(loader): support validate with standard schema

package.json

@@ -50,7 +50,8 @@
     "oxlint": "^1.48.0",
     "perfect-debounce": "^2.1.0",
     "typescript": "^5.9.3",
-    "vitest": "^4.0.18"
+    "vitest": "^4.0.18",
+    "zod": "^4.3.6"
   },
   "peerDependencies": {
     "chokidar": "^5",

src/loader.ts

@@ -20,6 +20,7 @@ import type {
   InputConfig,
   ConfigSource,
   ConfigFunctionContext,
+  StandardSchemaV1,
 } from "./types.ts";
 
 const _normalize = (p?: string) => p?.replace(/\\/g, "/");
@@ -49,10 +50,23 @@ export const SUPPORTED_EXTENSIONS = Object.freeze([
   ".toml",
 ]) as unknown as string[];
 
+export async function loadConfig<
+  MT extends ConfigLayerMeta = ConfigLayerMeta,
+  S extends StandardSchemaV1 = StandardSchemaV1,
+>(
+  options: LoadConfigOptions<UserInputConfig, MT, S> & { schema: S },
+): Promise<ResolvedConfig<StandardSchemaV1.InferConfigOutput<S> & UserInputConfig, MT>>;
+
 export async function loadConfig<
   T extends UserInputConfig = UserInputConfig,
   MT extends ConfigLayerMeta = ConfigLayerMeta,
->(options: LoadConfigOptions<T, MT>): Promise<ResolvedConfig<T, MT>> {
+>(options: LoadConfigOptions<T, MT>): Promise<ResolvedConfig<T, MT>>;
+
+export async function loadConfig<
+  T extends UserInputConfig = UserInputConfig,
+  MT extends ConfigLayerMeta = ConfigLayerMeta,
+  S extends StandardSchemaV1 = StandardSchemaV1,
+>(options: LoadConfigOptions<T, MT, S>): Promise<ResolvedConfig<T, MT>> {
   // Normalize options
   options.cwd = resolve(process.cwd(), options.cwd || ".");
   options.name = options.name || "config";
@@ -208,14 +222,28 @@ export async function loadConfig<
     throw new Error(`Required config (${r.configFile}) cannot be resolved.`);
   }
 
+  // Validate config
+  if (options.schema) {
+    let result = options.schema["~standard"].validate(r);
+    if (result instanceof Promise) result = await result;
+    if (result.issues) {
+      const messages = result.issues.map((issue) => {
+        const path = issue.path?.map((p) => (typeof p === "object" ? p.key : p)).join(".");
+        return path ? `  - ${path}: ${issue.message}` : `  - ${issue.message}`;
+      });
+      throw new Error(`Config validation failed:\n${messages.join("\n")}`);
+    }
+  }
+
   // Return resolved config
   return r;
 }
 
 async function extendConfig<
   T extends UserInputConfig = UserInputConfig,
   MT extends ConfigLayerMeta = ConfigLayerMeta,
->(config: InputConfig<T, MT>, options: LoadConfigOptions<T, MT>) {
+  S extends StandardSchemaV1 = StandardSchemaV1,
+>(config: InputConfig<T, MT>, options: LoadConfigOptions<T, MT, S>) {
   (config as any)._layers = config._layers || [];
   if (!options.extend) {
     return;
@@ -275,9 +303,10 @@ const NPM_PACKAGE_RE = /^(@[\da-z~-][\d._a-z~-]*\/)?[\da-z~-][\d._a-z~-]*($|\/.*
 async function resolveConfig<
   T extends UserInputConfig = UserInputConfig,
   MT extends ConfigLayerMeta = ConfigLayerMeta,
+  S extends StandardSchemaV1 = StandardSchemaV1,
 >(
   source: string,
-  options: LoadConfigOptions<T, MT>,
+  options: LoadConfigOptions<T, MT, S>,
   sourceOptions: SourceOptions<T, MT> = {},
 ): Promise<ResolvedConfig<T, MT>> {
   // Custom user resolver
@@ -437,7 +466,7 @@ async function resolveConfig<
 
 // --- internal ---
 
-function tryResolve(id: string, options: LoadConfigOptions<any, any>) {
+function tryResolve(id: string, options: LoadConfigOptions<any, any, any>) {
   const res = resolveModulePath(id, {
     try: true,
     from: pathToFileURL(join(options.cwd || ".", options.configFile || "/")),

src/types.ts

@@ -99,6 +99,7 @@ export type ResolvableConfig<T extends UserInputConfig = UserInputConfig> =
 export interface LoadConfigOptions<
   T extends UserInputConfig = UserInputConfig,
   MT extends ConfigLayerMeta = ConfigLayerMeta,
+  S extends StandardSchemaV1 = StandardSchemaV1,
 > {
   name?: string;
   cwd?: string;
@@ -126,7 +127,7 @@ export interface LoadConfigOptions<
 
   resolve?: (
     id: string,
-    options: LoadConfigOptions<T, MT>,
+    options: LoadConfigOptions<T, MT, S>,
   ) => null | undefined | ResolvedConfig<T, MT> | Promise<ResolvedConfig<T, MT> | undefined | null>;
 
   /** Custom import function used to load configuration files */
@@ -146,6 +147,8 @@ export interface LoadConfigOptions<
       };
 
   configFileRequired?: boolean;
+
+  schema?: S;
 }
 
 export type DefineConfig<
@@ -159,3 +162,82 @@ export function createDefineConfig<
 >(): DefineConfig<T, MT> {
   return (input: InputConfig<T, MT>) => input;
 }
+
+// ----- Standard Schema types -----
+
+// https://github.com/standard-schema/standard-schema/blob/main/packages/spec/src/index.ts
+/** The Standard Schema interface. */
+export interface StandardSchemaV1<Input = unknown, Output = Input> {
+  /** The Standard Schema properties. */
+  readonly "~standard": StandardSchemaV1.Props<Input, Output>;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-namespace
+export declare namespace StandardSchemaV1 {
+  /** The Standard Schema properties interface. */
+  export interface Props<Input = unknown, Output = Input> {
+    /** The version number of the standard. */
+    readonly version: 1;
+    /** The vendor name of the schema library. */
+    readonly vendor: string;
+    /** Validates unknown input values. */
+    readonly validate: (value: unknown) => Result<Output> | Promise<Result<Output>>;
+    /** Inferred types associated with the schema. */
+    readonly types?: Types<Input, Output> | undefined;
+  }
+
+  /** The result interface of the validate function. */
+  export type Result<Output> = SuccessResult<Output> | FailureResult;
+
+  /** The result interface if validation succeeds. */
+  export interface SuccessResult<Output> {
+    /** The typed output value. */
+    readonly value: Output;
+    /** The non-existent issues. */
+    readonly issues?: undefined;
+  }
+
+  /** The result interface if validation fails. */
+  export interface FailureResult {
+    /** The issues of failed validation. */
+    readonly issues: ReadonlyArray<Issue>;
+  }
+
+  /** The issue interface of the failure output. */
+  export interface Issue {
+    /** The error message of the issue. */
+    readonly message: string;
+    /** The path of the issue, if any. */
+    readonly path?: ReadonlyArray<PropertyKey | PathSegment> | undefined;
+  }
+
+  /** The path segment interface of the issue. */
+  export interface PathSegment {
+    /** The key representing a path segment. */
+    readonly key: PropertyKey;
+  }
+
+  /** The Standard Schema types interface. */
+  export interface Types<Input = unknown, Output = Input> {
+    /** The input type of the schema. */
+    readonly input: Input;
+    /** The output type of the schema. */
+    readonly output: Output;
+  }
+
+  /** Infers the input type of a Standard Schema. */
+  export type InferInput<Schema extends StandardSchemaV1> = NonNullable<
+    Schema["~standard"]["types"]
+  >["input"];
+
+  /** Infers the output type of a Standard Schema. */
+  export type InferOutput<Schema extends StandardSchemaV1> = NonNullable<
+    Schema["~standard"]["types"]
+  >["output"];
+
+  /** Extracts the `config` property type from a schema's output type. */
+  export type InferConfigOutput<Schema extends StandardSchemaV1> =
+    InferOutput<Schema> extends { config: infer C } ? C : never;
+
+  // biome-ignore lint/complexity/noUselessEmptyExport: needed for granular visibility control of TS namespace
+}

test/loader.test.ts

@@ -4,10 +4,32 @@ import { normalize } from "pathe";
 import type { ConfigLayer, ConfigLayerMeta, UserInputConfig } from "../src/index.ts";
 import { loadConfig } from "../src/index.ts";
 
+import { z } from "zod";
+
 const r = (path: string) => normalize(fileURLToPath(new URL(path, import.meta.url)));
 const transformPaths = (object: object) =>
   JSON.parse(JSON.stringify(object).replaceAll(r("."), "<path>/"));
 
+const ConfigSchema = z.object({
+  defaultConfig: z.boolean().optional(),
+  virtual: z.boolean().optional(),
+  githubLayer: z.boolean().optional(),
+  npmConfig: z.boolean().optional(),
+  devConfig: z.boolean().optional(),
+  baseConfig: z.boolean().optional(),
+  array: z.array(z.string()).optional(),
+  baseEnvConfig: z.boolean().optional(),
+  packageJSON2: z.boolean().optional(),
+  packageJSON: z.boolean().optional(),
+  testConfig: z.boolean().optional(),
+  rcFile: z.boolean().optional(),
+  configFile: z.union([z.string(), z.boolean(), z.undefined()]).optional(),
+  overridden: z.boolean().optional(),
+  enableDefault: z.boolean().optional(),
+  envConfig: z.boolean().optional(),
+  theme: z.string().optional(),
+});
+
 describe("loader", () => {
   it("load fixture config", async () => {
     type UserConfig = Partial<{
@@ -17,7 +39,10 @@ describe("loader", () => {
       defaultConfig: boolean;
       extends: string[];
     }>;
-    const { config, layers } = await loadConfig<UserConfig>({
+    const { config, layers } = await loadConfig({
+      schema: z.object({
+        config: ConfigSchema,
+      }),
       cwd: r("./fixture"),
       name: "test",
       dotenv: {
@@ -371,6 +396,36 @@ describe("loader", () => {
     });
   });
 
+  it("schema validation formats errors", async () => {
+    await expect(
+      loadConfig({
+        schema: z.object({
+          config: z.object({
+            requiredField: z.string(),
+          }),
+        }),
+        cwd: r("./fixture"),
+        name: "test",
+      }),
+    ).rejects.toThrowError("Config validation failed:");
+  });
+
+  it("schema infers config type", async () => {
+    const { config } = await loadConfig({
+      schema: z.object({
+        config: z.object({
+          configFile: z.union([z.string(), z.boolean()]).optional(),
+        }),
+      }),
+      cwd: r("./fixture"),
+      name: "test",
+    });
+
+    // Type check: config.configFile should be typed as string | boolean | undefined
+    const _configFile: string | boolean | undefined = config.configFile;
+    expect(_configFile).toBeDefined();
+  });
+
   it("try reproduce error with index.js on root importing jsx/tsx", async () => {
     await loadConfig({
       name: "test",