@mudah-cli/config 0.2.0 → 0.4.0

package/dist/config-repository.d.ts

@@ -1,3 +1,4 @@
+import { type Schema, type SchemaResult } from './schema.js';
 /**
  * Dotted-key configuration repository.
  *
@@ -24,4 +25,12 @@ export declare class ConfigRepository {
     merge(key: string, defaults: Record<string, unknown>): this;
     /** Replace the entire configuration tree. */
     clear(): this;
+    /**
+     * Check a subtree against `schema`. Reports every problem at once, with
+     * paths relative to `key` (`db.pool` for `validate('db', …)`).
+     *
+     * Use at boot: a config typo then fails loudly instead of surfacing as a
+     * confusing `undefined` three layers down.
+     */
+    validate<T>(key: string, schema: Schema<T>): SchemaResult<T>;
 }

package/dist/config-repository.js

@@ -1,4 +1,5 @@
 import { assignPath, deepMerge, hasPath, isPlainObject, readPath, removePath } from './paths.js';
+import { validateSchema } from './schema.js';
 /**
  * Dotted-key configuration repository.
  *
@@ -44,5 +45,16 @@ export class ConfigRepository {
         this.root = {};
         return this;
     }
+    /**
+     * Check a subtree against `schema`. Reports every problem at once, with
+     * paths relative to `key` (`db.pool` for `validate('db', …)`).
+     *
+     * Use at boot: a config typo then fails loudly instead of surfacing as a
+     * confusing `undefined` three layers down.
+     */
+    validate(key, schema) {
+        const value = key === '' ? this.root : this.get(key, undefined);
+        return validateSchema(schema, value, key);
+    }
 }
 //# sourceMappingURL=config-repository.js.map

package/dist/config-repository.js.map

@@ -1 +1 @@
-{"version":3,"file":"config-repository.js","sourceRoot":"","sources":["../src/config-repository.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,OAAO,EAAE,aAAa,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAEjG;;;;;;GAMG;AACH,MAAM,OAAO,gBAAgB;IACnB,IAAI,GAA4B,EAAE,CAAC;IAE3C,4EAA4E;IAC5E,GAAG,CAAC,GAAW,EAAE,KAAc;QAC7B,UAAU,CAAC,IAAI,CAAC,IAAI,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC;QAClC,OAAO,IAAI,CAAC;IACd,CAAC;IAED,oEAAoE;IACpE,GAAG,CAAc,GAAW,EAAE,YAAgB;QAC5C,OAAO,QAAQ,CAAC,IAAI,CAAC,IAAI,EAAE,GAAG,EAAE,YAAY,CAAM,CAAC;IACrD,CAAC;IAED,0CAA0C;IAC1C,GAAG,CAAC,GAAW;QACb,OAAO,OAAO,CAAC,IAAI,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IACjC,CAAC;IAED,iEAAiE;IACjE,MAAM,CAAC,GAAW;QAChB,OAAO,UAAU,CAAC,IAAI,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IACpC,CAAC;IAED,qEAAqE;IACrE,GAAG;QACD,OAAO,IAAI,CAAC,IAAI,CAAC;IACnB,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,GAAW,EAAE,QAAiC;QAClD,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAsC,GAAG,EAAE,SAAS,CAAC,CAAC;QAC/E,MAAM,IAAI,GAAG,aAAa,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC;QACrD,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,SAAS,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC;QACzC,OAAO,IAAI,CAAC;IACd,CAAC;IAED,6CAA6C;IAC7C,KAAK;QACH,IAAI,CAAC,IAAI,GAAG,EAAE,CAAC;QACf,OAAO,IAAI,CAAC;IACd,CAAC;CACF"}
+{"version":3,"file":"config-repository.js","sourceRoot":"","sources":["../src/config-repository.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,OAAO,EAAE,aAAa,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACjG,OAAO,EAAE,cAAc,EAAkC,MAAM,aAAa,CAAC;AAE7E;;;;;;GAMG;AACH,MAAM,OAAO,gBAAgB;IACnB,IAAI,GAA4B,EAAE,CAAC;IAE3C,4EAA4E;IAC5E,GAAG,CAAC,GAAW,EAAE,KAAc;QAC7B,UAAU,CAAC,IAAI,CAAC,IAAI,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC;QAClC,OAAO,IAAI,CAAC;IACd,CAAC;IAED,oEAAoE;IACpE,GAAG,CAAc,GAAW,EAAE,YAAgB;QAC5C,OAAO,QAAQ,CAAC,IAAI,CAAC,IAAI,EAAE,GAAG,EAAE,YAAY,CAAM,CAAC;IACrD,CAAC;IAED,0CAA0C;IAC1C,GAAG,CAAC,GAAW;QACb,OAAO,OAAO,CAAC,IAAI,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IACjC,CAAC;IAED,iEAAiE;IACjE,MAAM,CAAC,GAAW;QAChB,OAAO,UAAU,CAAC,IAAI,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IACpC,CAAC;IAED,qEAAqE;IACrE,GAAG;QACD,OAAO,IAAI,CAAC,IAAI,CAAC;IACnB,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,GAAW,EAAE,QAAiC;QAClD,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAsC,GAAG,EAAE,SAAS,CAAC,CAAC;QAC/E,MAAM,IAAI,GAAG,aAAa,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC;QACrD,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,SAAS,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC;QACzC,OAAO,IAAI,CAAC;IACd,CAAC;IAED,6CAA6C;IAC7C,KAAK;QACH,IAAI,CAAC,IAAI,GAAG,EAAE,CAAC;QACf,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;;;OAMG;IACH,QAAQ,CAAI,GAAW,EAAE,MAAiB;QACxC,MAAM,KAAK,GAAG,GAAG,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC;QAChE,OAAO,cAAc,CAAC,MAAM,EAAE,KAAK,EAAE,GAAG,CAAC,CAAC;IAC5C,CAAC;CACF"}

package/dist/define-config.d.ts

@@ -1,3 +1,4 @@
+import { type Schema } from './schema.js';
 /**
  * Define a typed configuration file. Identity at runtime — the value exists
  * for type inference, giving apps full completion on `config.get('app.x')`
@@ -12,3 +13,14 @@
  * ```
  */
 export declare function defineConfig<T extends Record<string, unknown>>(config: T): T;
+/**
+ * Define a validated configuration file. The schema runs immediately, so a
+ * bad config fails at import time with every offending key listed.
+ *
+ * ```ts
+ * export default defineConfig(s.object({ url: s.string(), pool: s.number().default(5) }), {
+ *   url: env('DATABASE_URL', 'sqlite:///local.db'),
+ * });
+ * ```
+ */
+export declare function defineConfig<T>(schema: Schema<T>, config: unknown): T;

package/dist/define-config.js

@@ -1,17 +1,14 @@
-/**
- * Define a typed configuration file. Identity at runtime — the value exists
- * for type inference, giving apps full completion on `config.get('app.x')`
- * when the config file is typed.
- *
- * ```ts
- * // config/app.ts
- * export default defineConfig({
- *   name: 'my-cli',
- *   env: env('APP_ENV', 'production'),
- * });
- * ```
- */
-export function defineConfig(config) {
-    return config;
+import { assertSchema } from './schema.js';
+export function defineConfig(schemaOrConfig, config) {
+    if (isSchema(schemaOrConfig)) {
+        return assertSchema(schemaOrConfig, config);
+    }
+    return schemaOrConfig;
+}
+function isSchema(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        typeof value.parse === 'function' &&
+        typeof value.type === 'string');
 }
 //# sourceMappingURL=define-config.js.map

package/dist/define-config.js.map

@@ -1 +1 @@
-{"version":3,"file":"define-config.js","sourceRoot":"","sources":["../src/define-config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,YAAY,CAAoC,MAAS;IACvE,OAAO,MAAM,CAAC;AAChB,CAAC"}
+{"version":3,"file":"define-config.js","sourceRoot":"","sources":["../src/define-config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAe,MAAM,aAAa,CAAC;AA2BxD,MAAM,UAAU,YAAY,CAAI,cAA6B,EAAE,MAAgB;IAC7E,IAAI,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC;QAC7B,OAAO,YAAY,CAAC,cAAc,EAAE,MAAM,CAAC,CAAC;IAC9C,CAAC;IACD,OAAO,cAAc,CAAC;AACxB,CAAC;AAED,SAAS,QAAQ,CAAI,KAA0B;IAC7C,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,KAAK,IAAI;QACd,OAAQ,KAAmB,CAAC,KAAK,KAAK,UAAU;QAChD,OAAQ,KAAmB,CAAC,IAAI,KAAK,QAAQ,CAC9C,CAAC;AACJ,CAAC"}

package/dist/index.d.ts

@@ -3,3 +3,4 @@ export { defineConfig } from './define-config.js';
 export { env, loadEnvFile } from './env.js';
 export { loadConfigFiles, type LoadConfigOptions } from './load-config-files.js';
 export { deepMerge, isPlainObject } from './paths.js';
+export { assertSchema, ConfigValidationError, s, validateSchema, type AnySchemaBuilder, type ArraySchemaBuilder, type BooleanSchemaBuilder, type NumberSchemaBuilder, type ObjectShape, type ObjectSchemaBuilder, type Schema, type SchemaIssue, type SchemaResult, type StringSchemaBuilder, } from './schema.js';

package/dist/index.js

@@ -3,4 +3,5 @@ export { defineConfig } from './define-config.js';
 export { env, loadEnvFile } from './env.js';
 export { loadConfigFiles } from './load-config-files.js';
 export { deepMerge, isPlainObject } from './paths.js';
+export { assertSchema, ConfigValidationError, s, validateSchema, } from './schema.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,GAAG,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAC5C,OAAO,EAAE,eAAe,EAA0B,MAAM,wBAAwB,CAAC;AACjF,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,GAAG,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAC5C,OAAO,EAAE,eAAe,EAA0B,MAAM,wBAAwB,CAAC;AACjF,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AACtD,OAAO,EACL,YAAY,EACZ,qBAAqB,EACrB,CAAC,EACD,cAAc,GAWf,MAAM,aAAa,CAAC"}

package/dist/schema.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Minimal, zero-dependency config schema validation.
+ *
+ * Schemas describe the shape of a config file, validate it at boot, and
+ * report every problem at once with dotted paths (`db.pool`) instead of
+ * failing on the first bad key.
+ *
+ * ```ts
+ * // config/database.ts
+ * import { defineConfig, s } from '@mudah-cli/config';
+ *
+ * export default defineConfig(
+ *   s.object({
+ *     url: s.string(),
+ *     pool: s.number().min(1).default(5),
+ *     ssl: s.boolean().default(false),
+ *   }),
+ * );
+ * ```
+ */
+export interface SchemaIssue {
+    /** Dotted path to the offending value (`db.pool`, `servers.0.host`). */
+    readonly path: string;
+    /** What went wrong. */
+    readonly message: string;
+}
+export interface SchemaResult<T> {
+    readonly ok: boolean;
+    /** The parsed value: coerced, defaults filled in. Only valid when `ok`. */
+    readonly value: T;
+    /** Every problem found, in document order. Empty when `ok`. */
+    readonly issues: readonly SchemaIssue[];
+}
+export declare class ConfigValidationError extends Error {
+    readonly issues: readonly SchemaIssue[];
+    constructor(issues: readonly SchemaIssue[]);
+}
+/** What every schema node exposes. */
+export interface Schema<T> {
+    readonly type: string;
+    /** True when a missing value is acceptable (via `optional()`/`default()`). */
+    readonly isOptional: boolean;
+    /** Human-readable type name used in error messages. */
+    readonly label: string;
+    /** Validate (and coerce) an unknown value. Returns issues; never throws. */
+    parse(value: unknown, path: string, issues: SchemaIssue[]): T;
+    /** Whether a missing value is acceptable for this node. */
+    acceptsMissing(): boolean;
+    /** The value this node contributes when nothing is supplied. */
+    fallback(): T | undefined;
+    /** Documentation string set by `describe()`, when present. */
+    describeText(): string | undefined;
+}
+type ObjectShape = Record<string, Schema<unknown>>;
+type ObjectOutput<S extends ObjectShape> = {
+    [K in keyof S]: S[K] extends Schema<infer V> ? V : never;
+};
+/**
+ * Fluent builders. Each returns the public interface, not the class, so a
+ * schema can be exported from a module (declaration emit can't describe a
+ * class with private state).
+ */
+export interface StringSchemaBuilder extends Schema<string> {
+    min(length: number): StringSchemaBuilder;
+    max(length: number): StringSchemaBuilder;
+    match(pattern: RegExp): StringSchemaBuilder;
+    optional(): StringSchemaBuilder;
+    default(value: string): StringSchemaBuilder;
+    describe(text: string): StringSchemaBuilder;
+}
+export interface NumberSchemaBuilder extends Schema<number> {
+    min(value: number): NumberSchemaBuilder;
+    max(value: number): NumberSchemaBuilder;
+    int(): NumberSchemaBuilder;
+    optional(): NumberSchemaBuilder;
+    default(value: number): NumberSchemaBuilder;
+    describe(text: string): NumberSchemaBuilder;
+}
+export interface BooleanSchemaBuilder extends Schema<boolean> {
+    optional(): BooleanSchemaBuilder;
+    default(value: boolean): BooleanSchemaBuilder;
+    describe(text: string): BooleanSchemaBuilder;
+}
+export interface ArraySchemaBuilder<T> extends Schema<T[]> {
+    min(length: number): ArraySchemaBuilder<T>;
+    max(length: number): ArraySchemaBuilder<T>;
+    optional(): ArraySchemaBuilder<T>;
+    default(value: T[]): ArraySchemaBuilder<T>;
+    describe(text: string): ArraySchemaBuilder<T>;
+}
+export interface ObjectSchemaBuilder<S extends ObjectShape> extends Schema<ObjectOutput<S>> {
+    /** Reject keys the schema doesn't declare. */
+    strict(): ObjectSchemaBuilder<S>;
+    optional(): ObjectSchemaBuilder<S>;
+    default(value: ObjectOutput<S>): ObjectSchemaBuilder<S>;
+    describe(text: string): ObjectSchemaBuilder<S>;
+    readonly shape: S;
+}
+export interface AnySchemaBuilder extends Schema<unknown> {
+    optional(): AnySchemaBuilder;
+    default(value: unknown): AnySchemaBuilder;
+    describe(text: string): AnySchemaBuilder;
+}
+/** Schema builders. Compose them into `s.object({ … })`. */
+export declare const s: {
+    string(): StringSchemaBuilder;
+    /** A string restricted to `values`. */
+    enum<T extends string>(values: readonly T[]): StringSchemaBuilder;
+    number(): NumberSchemaBuilder;
+    boolean(): BooleanSchemaBuilder;
+    array<T>(item: Schema<T>): ArraySchemaBuilder<T>;
+    object<S extends ObjectShape>(shape: S): ObjectSchemaBuilder<S>;
+    /** Accept anything at this key. */
+    any(): AnySchemaBuilder;
+};
+/** Validate `value` against `schema`. Collects every issue; never throws. */
+export declare function validateSchema<T>(schema: Schema<T>, value: unknown, path?: string): SchemaResult<T>;
+/**
+ * Validate and throw a `ConfigValidationError` when anything is wrong. Use
+ * this at boot — one error listing every bad key beats failing on the first.
+ */
+export declare function assertSchema<T>(schema: Schema<T>, value: unknown, path?: string): T;
+export type { ObjectShape };

package/dist/schema.js

@@ -0,0 +1,297 @@
+/**
+ * Minimal, zero-dependency config schema validation.
+ *
+ * Schemas describe the shape of a config file, validate it at boot, and
+ * report every problem at once with dotted paths (`db.pool`) instead of
+ * failing on the first bad key.
+ *
+ * ```ts
+ * // config/database.ts
+ * import { defineConfig, s } from '@mudah-cli/config';
+ *
+ * export default defineConfig(
+ *   s.object({
+ *     url: s.string(),
+ *     pool: s.number().min(1).default(5),
+ *     ssl: s.boolean().default(false),
+ *   }),
+ * );
+ * ```
+ */
+export class ConfigValidationError extends Error {
+    issues;
+    constructor(issues) {
+        super(`Invalid configuration:\n${issues.map((i) => `  ${i.path === '' ? '(root)' : i.path}: ${i.message}`).join('\n')}`);
+        this.name = 'ConfigValidationError';
+        this.issues = issues;
+    }
+}
+class BaseSchema {
+    isOptional = false;
+    defaulted = undefined;
+    documented = undefined;
+    /** Allow this key to be missing. */
+    optional() {
+        this.isOptional = true;
+        return this;
+    }
+    /** Value used when the key is absent. Implies optional. */
+    default(value) {
+        this.defaulted = { value };
+        this.isOptional = true;
+        return this;
+    }
+    /** Documentation only — surfaced by `describeText()`. */
+    describe(text) {
+        this.documented = text;
+        return this;
+    }
+    acceptsMissing() {
+        return this.isOptional;
+    }
+    fallback() {
+        return this.defaulted?.value;
+    }
+    describeText() {
+        return this.documented;
+    }
+    /** Run the checks common to every node, then the node's own rules. */
+    parse(value, path, issues) {
+        if (value === undefined) {
+            const fallback = this.fallback();
+            if (fallback !== undefined)
+                return fallback;
+            if (!this.isOptional) {
+                issues.push({ path, message: `is required` });
+            }
+            return undefined;
+        }
+        return this.check(value, path, issues);
+    }
+    fail(issues, path, message) {
+        issues.push({ path, message });
+    }
+}
+class StringSchema extends BaseSchema {
+    type = 'string';
+    label = 'string';
+    minLength;
+    maxLength;
+    pattern;
+    allowed;
+    constructor(allowed) {
+        super();
+        this.allowed = allowed;
+    }
+    min(length) {
+        this.minLength = length;
+        return this;
+    }
+    max(length) {
+        this.maxLength = length;
+        return this;
+    }
+    match(pattern) {
+        this.pattern = pattern;
+        return this;
+    }
+    check(value, path, issues) {
+        if (typeof value !== 'string') {
+            this.fail(issues, path, `expected string, got ${typeName(value)}`);
+            return '';
+        }
+        if (this.minLength !== undefined && value.length < this.minLength) {
+            this.fail(issues, path, `must be at least ${this.minLength} characters`);
+        }
+        if (this.maxLength !== undefined && value.length > this.maxLength) {
+            this.fail(issues, path, `must be at most ${this.maxLength} characters`);
+        }
+        if (this.pattern !== undefined && !this.pattern.test(value)) {
+            this.fail(issues, path, `must match ${String(this.pattern)}`);
+        }
+        if (this.allowed !== undefined && !this.allowed.includes(value)) {
+            this.fail(issues, path, `must be one of: ${this.allowed.join(', ')}`);
+        }
+        return value;
+    }
+}
+class NumberSchema extends BaseSchema {
+    type = 'number';
+    label = 'number';
+    minimum;
+    maximum;
+    integerOnly = false;
+    min(value) {
+        this.minimum = value;
+        return this;
+    }
+    max(value) {
+        this.maximum = value;
+        return this;
+    }
+    int() {
+        this.integerOnly = true;
+        return this;
+    }
+    check(value, path, issues) {
+        if (typeof value !== 'number' || Number.isNaN(value)) {
+            this.fail(issues, path, `expected number, got ${typeName(value)}`);
+            return 0;
+        }
+        if (this.integerOnly && !Number.isInteger(value)) {
+            this.fail(issues, path, `must be an integer`);
+        }
+        if (this.minimum !== undefined && value < this.minimum) {
+            this.fail(issues, path, `must be >= ${this.minimum}`);
+        }
+        if (this.maximum !== undefined && value > this.maximum) {
+            this.fail(issues, path, `must be <= ${this.maximum}`);
+        }
+        return value;
+    }
+}
+class BooleanSchema extends BaseSchema {
+    type = 'boolean';
+    label = 'boolean';
+    check(value, path, issues) {
+        if (typeof value !== 'boolean') {
+            this.fail(issues, path, `expected boolean, got ${typeName(value)}`);
+            return false;
+        }
+        return value;
+    }
+}
+class ArraySchema extends BaseSchema {
+    item;
+    type = 'array';
+    label = 'array';
+    minimum;
+    maximum;
+    constructor(item) {
+        super();
+        this.item = item;
+    }
+    min(length) {
+        this.minimum = length;
+        return this;
+    }
+    max(length) {
+        this.maximum = length;
+        return this;
+    }
+    check(value, path, issues) {
+        if (!Array.isArray(value)) {
+            this.fail(issues, path, `expected array, got ${typeName(value)}`);
+            return [];
+        }
+        if (this.minimum !== undefined && value.length < this.minimum) {
+            this.fail(issues, path, `must have at least ${this.minimum} item(s)`);
+        }
+        if (this.maximum !== undefined && value.length > this.maximum) {
+            this.fail(issues, path, `must have at most ${this.maximum} item(s)`);
+        }
+        return value.map((entry, index) => this.item.parse(entry, `${path}.${index}`, issues));
+    }
+}
+class ObjectSchema extends BaseSchema {
+    shape;
+    type = 'object';
+    label = 'object';
+    strictMode = false;
+    constructor(shape) {
+        super();
+        this.shape = shape;
+    }
+    /** Reject keys the schema doesn't declare. */
+    strict() {
+        this.strictMode = true;
+        return this;
+    }
+    check(value, path, issues) {
+        if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+            this.fail(issues, path, `expected object, got ${typeName(value)}`);
+            return {};
+        }
+        const source = value;
+        const output = {};
+        for (const [key, node] of Object.entries(this.shape)) {
+            const childPath = path === '' ? key : `${path}.${key}`;
+            const present = Object.prototype.hasOwnProperty.call(source, key);
+            const parsed = node.parse(present ? source[key] : undefined, childPath, issues);
+            if (present || parsed !== undefined)
+                output[key] = parsed;
+        }
+        if (this.strictMode) {
+            for (const key of Object.keys(source)) {
+                if (!(key in this.shape)) {
+                    this.fail(issues, path === '' ? key : `${path}.${key}`, `is not a known key`);
+                }
+            }
+        }
+        else {
+            // Keep undeclared keys so partial schemas don't silently drop config.
+            for (const key of Object.keys(source)) {
+                if (!(key in this.shape))
+                    output[key] = source[key];
+            }
+        }
+        return output;
+    }
+}
+class AnySchema extends BaseSchema {
+    type = 'any';
+    label = 'any';
+    check(value) {
+        return value;
+    }
+}
+function typeName(value) {
+    if (value === null)
+        return 'null';
+    if (Array.isArray(value))
+        return 'array';
+    return typeof value;
+}
+/** Schema builders. Compose them into `s.object({ … })`. */
+export const s = {
+    string() {
+        return new StringSchema();
+    },
+    /** A string restricted to `values`. */
+    enum(values) {
+        return new StringSchema(values);
+    },
+    number() {
+        return new NumberSchema();
+    },
+    boolean() {
+        return new BooleanSchema();
+    },
+    array(item) {
+        return new ArraySchema(item);
+    },
+    object(shape) {
+        return new ObjectSchema(shape);
+    },
+    /** Accept anything at this key. */
+    any() {
+        return new AnySchema();
+    },
+};
+/** Validate `value` against `schema`. Collects every issue; never throws. */
+export function validateSchema(schema, value, path = '') {
+    const issues = [];
+    const parsed = schema.parse(value, path, issues);
+    return { ok: issues.length === 0, value: parsed, issues };
+}
+/**
+ * Validate and throw a `ConfigValidationError` when anything is wrong. Use
+ * this at boot — one error listing every bad key beats failing on the first.
+ */
+export function assertSchema(schema, value, path = '') {
+    const result = validateSchema(schema, value, path);
+    if (!result.ok)
+        throw new ConfigValidationError(result.issues);
+    return result.value;
+}
+//# sourceMappingURL=schema.js.map

package/dist/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mudah-cli/config",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Typed configuration repository, .env loading, and dotted-key access.",
   "type": "module",
   "license": "MIT",