@zudojs/config 1.2.0 → 1.3.1

package/README.md

@@ -118,6 +118,28 @@ const db = manager.scoped("db");
 db.string("host", "localhost");
 ```
 
+`required<T>(key)` does NOT convert: `T` is an unchecked cast, so with
+`DB__PORT=5432`, `scoped("db").required<number>("port")` returns the
+string `"5432"`. Use the typed variants, which parse and check the value
+and throw when it is missing or does not parse: `requiredString()`,
+`requiredNumber()`, `requiredBoolean()` and `requiredDate()` (on the
+manager, the resolver and scoped resolvers).
+
+```typescript
+const db = manager.scoped("db");
+db.requiredNumber("port"); // 5432 (a number)
+```
+
+`store.getByPrefix(prefix)` and `store.getObjectByPrefix(prefix)` accept
+the prefix with or without a trailing dot: `"db"` and `"db."` both select
+`db.host` and `db.port` (and not `dbx`).
+
+Passing a fallback narrows the return type: `manager.number("app.port")`
+is `number | undefined`, while `manager.number("app.port", 3000)` is
+`number`. The same holds for every typed getter and for `get(key,
+fallback)`, whose literal fallback is widened (`get("mode", "dev")` is
+`string`, not `"dev"`).
+
 `number()` accepts decimal notation only: `"0x1F90"`, `"0b11"` and `"0o17"`
 are rejected rather than silently becoming 8080, 3 and 15.
 
@@ -138,6 +160,46 @@ const config = manager.validate({
 });
 ```
 
+Environment variables are always strings, so string input is coerced
+before the type check when a schema's type is `NUMBER` or `BOOLEAN` (and
+does not also accept `STRING`). Parsing is strict: `"8080"` becomes
+`8080`, while `"80a"`, `"0x1F90"` and `""` are still rejected as
+`TYPE_MISMATCH`. Booleans follow the `boolean()` convention: `true` /
+`false`, `1` / `0`, `yes` / `no`, `y` / `n`, `on` / `off`. `validate` and
+`transform` receive the coerced value. Set `coerce: false` on a schema to
+require a real number or boolean.
+
+```typescript
+// PORT=8080 DEBUG=true
+const { port, debug } = manager.validate<{ port: number; debug: boolean }>({
+  properties: {
+    port: { type: ConfigValueType.NUMBER, min: 1, max: 65535 },
+    debug: { type: ConfigValueType.BOOLEAN },
+  },
+});
+```
+
+`resolve(key, schema)` types its schema per value type
+(`TypedConfigSchema`), so the constraints the validator enforces are
+accepted: `{ type: NUMBER, min: 1 }`, `{ type: STRING, minLength: 1 }`,
+`{ type: ARRAY, minItems: 1 }`. A constraint that belongs to another type
+(`{ type: NUMBER, minLength: 1 }`) is a compile error.
+
+Validation runs in this order: coerce, type check, constraints,
+`transform`, then `validate` on the final (transformed) value. A string
+that does not have the schema's type is handed to `transform` as a
+parser, and its output must then have the type and pass the constraints:
+
+```typescript
+manager.resolve("hosts", {
+  type: ConfigValueType.ARRAY,
+  minItems: 1,
+  transform: (value) => String(value).split(",").map((s) => s.trim()),
+}); // HOSTS="a, b" -> ["a", "b"]
+```
+
+A non-string of the wrong type is rejected without calling `transform`.
+
 Object schemas nest: a property schema of type `OBJECT` that declares
 its own `properties` / `additionalProperties` is validated recursively,
 so nested constraints are enforced by `validate()`, `resolve()` and the

package/dist/configManager/configManager.core.d.ts

@@ -1,11 +1,12 @@
 import type { ConfigValue } from "../configValue/configValue.core.js";
-import type { ConfigSchema, AnyConfigSchema } from "../configSchema/index.js";
+import type { AnyConfigSchema, TypedConfigSchema } from "../configSchema/index.js";
 import type { ConfigSource } from "../configSource/configSource.core.js";
 import type { ConfigEntry } from "../configEntry/configEntry.type.js";
 import type { ConfigLoader, ConfigLoadResult } from "../configLoader/configLoader.core.js";
 import type { ConfigStore } from "../configStore/configStore.core.js";
 import type { ConfigResolver } from "../configResolver/core/configResolver.core.js";
 import type { ScopedConfigResolver } from "../configResolver/accessors/configResolver.scoped.js";
+import type { ConfigWiden } from "../configResolver/core/configResolver.type.js";
 import type { ConfigManagerOptions, ConfigManagerStatus, ConfigManagerListener } from "./configManager.type.js";
 import { ConfigManagerState } from "./configManager.type.js";
 /**
@@ -96,41 +97,74 @@ export declare class ConfigManager {
      * Gets a raw configuration value.
      */
     get<T extends ConfigValue = ConfigValue>(key: string): T | undefined;
+    get<T extends ConfigValue>(key: string, fallback: T): ConfigWiden<T>;
     /**
-     * Gets a required configuration value.
+     * Returns a required value WITHOUT converting it: `T` is an unchecked
+     * cast. An environment variable is always a string, so
+     * `required<number>("port")` returns `"5432"`, not `5432`. Use
+     * `requiredNumber`, `requiredBoolean`, `requiredString` or
+     * `requiredDate`, which parse and check the value.
      */
     required<T extends ConfigValue = ConfigValue>(key: string): T;
+    /** Gets a required string; throws when missing or not a string. */
+    requiredString(key: string): string;
+    /**
+     * Gets a required number, parsing decimal strings (`"5432"`); throws
+     * when missing or not a number.
+     */
+    requiredNumber(key: string): number;
+    /**
+     * Gets a required boolean, parsing `true/false`, `1/0`, `yes/no`, `y/n`
+     * and `on/off`; throws when missing or not a boolean.
+     */
+    requiredBoolean(key: string): boolean;
+    /** Gets a required Date, parsing ISO strings; throws when missing. */
+    requiredDate(key: string): Date;
     /**
      * Gets a configuration value with schema validation.
      */
-    resolve<T extends ConfigValue>(key: string, schema: ConfigSchema<T>): T | undefined;
+    resolve<T extends ConfigValue>(key: string, schema: TypedConfigSchema<T>): T | undefined;
     /**
      * Gets a string value.
      */
+    string(key: string): string | undefined;
+    string(key: string, fallback: string): string;
     string(key: string, fallback?: string): string | undefined;
     /**
      * Gets a number value.
      */
+    number(key: string): number | undefined;
+    number(key: string, fallback: number): number;
     number(key: string, fallback?: number): number | undefined;
     /**
      * Gets a boolean value.
      */
+    boolean(key: string): boolean | undefined;
+    boolean(key: string, fallback: boolean): boolean;
     boolean(key: string, fallback?: boolean): boolean | undefined;
     /**
      * Gets a bigint value.
      */
+    bigint(key: string): bigint | undefined;
+    bigint(key: string, fallback: bigint): bigint;
     bigint(key: string, fallback?: bigint): bigint | undefined;
     /**
      * Gets a Date value.
      */
+    date(key: string): Date | undefined;
+    date(key: string, fallback: Date): Date;
     date(key: string, fallback?: Date): Date | undefined;
     /**
      * Gets an object value.
      */
+    object<T extends ConfigValue = ConfigValue>(key: string): T | undefined;
+    object<T extends ConfigValue = ConfigValue>(key: string, fallback: T): T;
     object<T extends ConfigValue = ConfigValue>(key: string, fallback?: T): T | undefined;
     /**
      * Gets an array value.
      */
+    array<T extends ConfigValue = ConfigValue>(key: string): readonly T[] | undefined;
+    array<T extends ConfigValue = ConfigValue>(key: string, fallback: readonly T[]): readonly T[];
     array<T extends ConfigValue = ConfigValue>(key: string, fallback?: readonly T[]): readonly T[] | undefined;
     /**
      * Sets a runtime configuration value.

package/dist/configManager/configManager.core.js

@@ -223,20 +223,47 @@ export class ConfigManager {
         markSecretEntries(this.store, collectSecretPaths(schema.properties));
         return cloneConfigValue(result.value);
     }
-    /**
-     * Gets a raw configuration value.
-     */
-    get(key) {
+    get(key, fallback) {
         this.assertActive();
-        return this.resolver.get(key);
+        return this.resolver.get(key, fallback);
     }
     /**
-     * Gets a required configuration value.
+     * Returns a required value WITHOUT converting it: `T` is an unchecked
+     * cast. An environment variable is always a string, so
+     * `required<number>("port")` returns `"5432"`, not `5432`. Use
+     * `requiredNumber`, `requiredBoolean`, `requiredString` or
+     * `requiredDate`, which parse and check the value.
      */
     required(key) {
         this.assertActive();
         return this.resolver.required(key);
     }
+    /** Gets a required string; throws when missing or not a string. */
+    requiredString(key) {
+        this.assertActive();
+        return this.resolver.requiredString(key);
+    }
+    /**
+     * Gets a required number, parsing decimal strings (`"5432"`); throws
+     * when missing or not a number.
+     */
+    requiredNumber(key) {
+        this.assertActive();
+        return this.resolver.requiredNumber(key);
+    }
+    /**
+     * Gets a required boolean, parsing `true/false`, `1/0`, `yes/no`, `y/n`
+     * and `on/off`; throws when missing or not a boolean.
+     */
+    requiredBoolean(key) {
+        this.assertActive();
+        return this.resolver.requiredBoolean(key);
+    }
+    /** Gets a required Date, parsing ISO strings; throws when missing. */
+    requiredDate(key) {
+        this.assertActive();
+        return this.resolver.requiredDate(key);
+    }
     /**
      * Gets a configuration value with schema validation.
      */
@@ -244,51 +271,30 @@ export class ConfigManager {
         this.assertActive();
         return this.resolver.resolve(key, schema);
     }
-    /**
-     * Gets a string value.
-     */
     string(key, fallback) {
         this.assertActive();
         return this.resolver.string(key, fallback);
     }
-    /**
-     * Gets a number value.
-     */
     number(key, fallback) {
         this.assertActive();
         return this.resolver.number(key, fallback);
     }
-    /**
-     * Gets a boolean value.
-     */
     boolean(key, fallback) {
         this.assertActive();
         return this.resolver.boolean(key, fallback);
     }
-    /**
-     * Gets a bigint value.
-     */
     bigint(key, fallback) {
         this.assertActive();
         return this.resolver.bigint(key, fallback);
     }
-    /**
-     * Gets a Date value.
-     */
     date(key, fallback) {
         this.assertActive();
         return this.resolver.date(key, fallback);
     }
-    /**
-     * Gets an object value.
-     */
     object(key, fallback) {
         this.assertActive();
         return this.resolver.object(key, fallback);
     }
-    /**
-     * Gets an array value.
-     */
     array(key, fallback) {
         this.assertActive();
         return this.resolver.array(key, fallback);

package/dist/configManager/configManager.error.d.ts

@@ -4,6 +4,7 @@
  * ConfigurationManager error types re-exported from @zudojs/errors.
  */
 import { ConfigurationError, createConfigurationError, isConfigurationError, missingConfigurationError, invalidConfigurationError } from "@zudojs/errors";
+import type { ConfigValidationIssue } from "../configSchema/configSchema.type.js";
 /**
  * Error thrown when complete configuration validation fails.
  *
@@ -11,8 +12,8 @@ import { ConfigurationError, createConfigurationError, isConfigurationError, mis
  * the base ConfigurationError from @zudojs/errors.
  */
 export declare class ConfigManagerValidationError extends ConfigurationError {
-    readonly issues: readonly unknown[];
-    constructor(issues: readonly unknown[]);
+    readonly issues: readonly ConfigValidationIssue[];
+    constructor(issues: readonly ConfigValidationIssue[]);
 }
 export { ConfigurationError, createConfigurationError, isConfigurationError, missingConfigurationError, invalidConfigurationError, };
 //# sourceMappingURL=configManager.error.d.ts.map

package/dist/configResolver/accessors/configResolver.scoped.d.ts

@@ -1,6 +1,7 @@
 import type { ConfigValue } from "../../configValue/configValue.core.js";
-import type { ConfigSchema } from "../../configSchema/index.js";
+import type { TypedConfigSchema } from "../../configSchema/index.js";
 import type { ConfigResolver } from "../core/configResolver.core.js";
+import type { ConfigWiden } from "../core/configResolver.type.js";
 /**
  * Resolver scoped to a configuration key prefix.
  */
@@ -13,15 +14,51 @@ export declare class ScopedConfigResolver {
      */
     key(key: string): string;
     get<T extends ConfigValue = ConfigValue>(key: string): T | undefined;
+    get<T extends ConfigValue>(key: string, fallback: T): ConfigWiden<T>;
+    /**
+     * Returns a required value WITHOUT converting it: `T` is an unchecked
+     * cast. An environment variable is always a string, so
+     * `required<number>("port")` returns `"5432"`, not `5432`. Use
+     * `requiredNumber`, `requiredBoolean`, `requiredString` or
+     * `requiredDate`, which parse and check the value.
+     */
     required<T extends ConfigValue = ConfigValue>(key: string): T;
+    /** Returns a required string; throws when missing or not a string. */
+    requiredString(key: string): string;
+    /**
+     * Returns a required number, parsing decimal strings (`"5432"`); throws
+     * when missing or not a number.
+     */
+    requiredNumber(key: string): number;
+    /**
+     * Returns a required boolean, parsing `true/false`, `1/0`, `yes/no`,
+     * `y/n` and `on/off`; throws when missing or not a boolean.
+     */
+    requiredBoolean(key: string): boolean;
+    /** Returns a required Date, parsing ISO strings; throws when missing. */
+    requiredDate(key: string): Date;
+    string(key: string): string | undefined;
+    string(key: string, fallback: string): string;
     string(key: string, fallback?: string): string | undefined;
+    number(key: string): number | undefined;
+    number(key: string, fallback: number): number;
     number(key: string, fallback?: number): number | undefined;
+    boolean(key: string): boolean | undefined;
+    boolean(key: string, fallback: boolean): boolean;
     boolean(key: string, fallback?: boolean): boolean | undefined;
+    bigint(key: string): bigint | undefined;
+    bigint(key: string, fallback: bigint): bigint;
     bigint(key: string, fallback?: bigint): bigint | undefined;
+    date(key: string): Date | undefined;
+    date(key: string, fallback: Date): Date;
     date(key: string, fallback?: Date): Date | undefined;
+    object<T extends ConfigValue = ConfigValue>(key: string): T | undefined;
+    object<T extends ConfigValue = ConfigValue>(key: string, fallback: T): T;
     object<T extends ConfigValue = ConfigValue>(key: string, fallback?: T): T | undefined;
+    array<T extends ConfigValue = ConfigValue>(key: string): readonly T[] | undefined;
+    array<T extends ConfigValue = ConfigValue>(key: string, fallback: readonly T[]): readonly T[];
     array<T extends ConfigValue = ConfigValue>(key: string, fallback?: readonly T[]): readonly T[] | undefined;
-    resolve<T extends ConfigValue>(key: string, schema: ConfigSchema<T>): T | undefined;
+    resolve<T extends ConfigValue>(key: string, schema: TypedConfigSchema<T>): T | undefined;
     pick(keys: readonly string[]): Readonly<Record<string, ConfigValue>>;
     scoped(prefix: string): ScopedConfigResolver;
 }

package/dist/configResolver/accessors/configResolver.scoped.js

@@ -14,12 +14,41 @@ export class ScopedConfigResolver {
     key(key) {
         return this.prefix ? `${this.prefix}.${key}` : key;
     }
-    get(key) {
-        return this.resolver.get(this.key(key));
+    get(key, fallback) {
+        return this.resolver.get(this.key(key), fallback);
     }
+    /**
+     * Returns a required value WITHOUT converting it: `T` is an unchecked
+     * cast. An environment variable is always a string, so
+     * `required<number>("port")` returns `"5432"`, not `5432`. Use
+     * `requiredNumber`, `requiredBoolean`, `requiredString` or
+     * `requiredDate`, which parse and check the value.
+     */
     required(key) {
         return this.resolver.required(this.key(key));
     }
+    /** Returns a required string; throws when missing or not a string. */
+    requiredString(key) {
+        return this.resolver.requiredString(this.key(key));
+    }
+    /**
+     * Returns a required number, parsing decimal strings (`"5432"`); throws
+     * when missing or not a number.
+     */
+    requiredNumber(key) {
+        return this.resolver.requiredNumber(this.key(key));
+    }
+    /**
+     * Returns a required boolean, parsing `true/false`, `1/0`, `yes/no`,
+     * `y/n` and `on/off`; throws when missing or not a boolean.
+     */
+    requiredBoolean(key) {
+        return this.resolver.requiredBoolean(this.key(key));
+    }
+    /** Returns a required Date, parsing ISO strings; throws when missing. */
+    requiredDate(key) {
+        return this.resolver.requiredDate(this.key(key));
+    }
     string(key, fallback) {
         return this.resolver.string(this.key(key), fallback);
     }

package/dist/configResolver/core/configResolver.core.d.ts

@@ -1,7 +1,7 @@
 import type { ConfigValue } from "../../configValue/configValue.core.js";
-import type { ConfigSchema } from "../../configSchema/index.js";
+import type { TypedConfigSchema } from "../../configSchema/index.js";
 import type { ConfigStore } from "../../configStore/configStore.core.js";
-import type { ConfigResolverOptions, ConfigResolutionResult } from "./configResolver.type.js";
+import type { ConfigResolverOptions, ConfigResolutionResult, ConfigWiden } from "./configResolver.type.js";
 import { ScopedConfigResolver } from "../accessors/configResolver.scoped.js";
 /**
  * Resolves typed configuration values from a ConfigStore.
@@ -17,21 +17,28 @@ export declare class ConfigResolver {
      * Returns the raw configuration value.
      */
     get<T extends ConfigValue = ConfigValue>(key: string): T | undefined;
+    get<T extends ConfigValue>(key: string, fallback: T): ConfigWiden<T>;
     /**
      * Resolves a value using a schema.
      */
-    resolve<T extends ConfigValue>(key: string, schema: ConfigSchema<T>): T | undefined;
+    resolve<T extends ConfigValue>(key: string, schema: TypedConfigSchema<T>): T | undefined;
     /**
      * Resolves a value and returns diagnostic information.
      */
-    resolveResult<T extends ConfigValue>(key: string, schema: ConfigSchema<T>): ConfigResolutionResult<T>;
+    resolveResult<T extends ConfigValue>(key: string, schema: TypedConfigSchema<T>): ConfigResolutionResult<T>;
     /**
-     * Returns a required configuration value.
+     * Returns a required value WITHOUT converting it: `T` is an unchecked
+     * cast. An environment variable is always a string, so
+     * `required<number>("port")` returns `"5432"`, not `5432`. Use
+     * `requiredNumber`, `requiredBoolean`, `requiredString` or
+     * `requiredDate`, which parse and check the value.
      */
     required<T extends ConfigValue = ConfigValue>(key: string): T;
     /**
      * Returns a string configuration value.
      */
+    string(key: string): string | undefined;
+    string(key: string, fallback: string): string;
     string(key: string, fallback?: string): string | undefined;
     /**
      * Returns a required string.
@@ -40,6 +47,8 @@ export declare class ConfigResolver {
     /**
      * Returns a number configuration value.
      */
+    number(key: string): number | undefined;
+    number(key: string, fallback: number): number;
     number(key: string, fallback?: number): number | undefined;
     /**
      * Returns a required number.
@@ -48,6 +57,8 @@ export declare class ConfigResolver {
     /**
      * Returns a boolean configuration value.
      */
+    boolean(key: string): boolean | undefined;
+    boolean(key: string, fallback: boolean): boolean;
     boolean(key: string, fallback?: boolean): boolean | undefined;
     /**
      * Returns a required boolean.
@@ -56,10 +67,14 @@ export declare class ConfigResolver {
     /**
      * Returns a bigint configuration value.
      */
+    bigint(key: string): bigint | undefined;
+    bigint(key: string, fallback: bigint): bigint;
     bigint(key: string, fallback?: bigint): bigint | undefined;
     /**
      * Returns a Date configuration value.
      */
+    date(key: string): Date | undefined;
+    date(key: string, fallback: Date): Date;
     date(key: string, fallback?: Date): Date | undefined;
     /**
      * Returns a required Date.
@@ -68,10 +83,14 @@ export declare class ConfigResolver {
     /**
      * Returns an object configuration value.
      */
+    object<T extends ConfigValue = ConfigValue>(key: string): T | undefined;
+    object<T extends ConfigValue = ConfigValue>(key: string, fallback: T): T;
     object<T extends ConfigValue = ConfigValue>(key: string, fallback?: T): T | undefined;
     /**
      * Returns an array configuration value.
      */
+    array<T extends ConfigValue = ConfigValue>(key: string): readonly T[] | undefined;
+    array<T extends ConfigValue = ConfigValue>(key: string, fallback: readonly T[]): readonly T[];
     array<T extends ConfigValue = ConfigValue>(key: string, fallback?: readonly T[]): readonly T[] | undefined;
     /**
      * Resolves a group of configuration keys.

package/dist/configResolver/core/configResolver.core.js

@@ -18,12 +18,9 @@ export class ConfigResolver {
             clone: options.clone ?? false,
         };
     }
-    /**
-     * Returns the raw configuration value.
-     */
-    get(key) {
+    get(key, fallback) {
         const value = this.store.get(key);
-        return this.prepareValue(value);
+        return this.prepareValue(value === undefined ? fallback : value);
     }
     /**
      * Resolves a value using a schema.
@@ -77,7 +74,11 @@ export class ConfigResolver {
         };
     }
     /**
-     * Returns a required configuration value.
+     * Returns a required value WITHOUT converting it: `T` is an unchecked
+     * cast. An environment variable is always a string, so
+     * `required<number>("port")` returns `"5432"`, not `5432`. Use
+     * `requiredNumber`, `requiredBoolean`, `requiredString` or
+     * `requiredDate`, which parse and check the value.
      */
     required(key) {
         const value = this.store.get(key);
@@ -92,9 +93,6 @@ export class ConfigResolver {
         }
         return this.prepareValue(value);
     }
-    /**
-     * Returns a string configuration value.
-     */
     string(key, fallback) {
         const value = this.store.get(key);
         if (value === undefined) {
@@ -121,9 +119,6 @@ export class ConfigResolver {
         }
         return value;
     }
-    /**
-     * Returns a number configuration value.
-     */
     number(key, fallback) {
         const value = this.store.get(key);
         if (value === undefined) {
@@ -159,9 +154,6 @@ export class ConfigResolver {
         }
         return value;
     }
-    /**
-     * Returns a boolean configuration value.
-     */
     boolean(key, fallback) {
         const value = this.store.get(key);
         if (value === undefined) {
@@ -194,9 +186,6 @@ export class ConfigResolver {
         }
         return value;
     }
-    /**
-     * Returns a bigint configuration value.
-     */
     bigint(key, fallback) {
         const value = this.store.get(key);
         if (value === undefined) {
@@ -213,9 +202,6 @@ export class ConfigResolver {
         }
         return this.invalidType(key, "bigint", value, fallback);
     }
-    /**
-     * Returns a Date configuration value.
-     */
     date(key, fallback) {
         const value = this.store.get(key);
         if (value === undefined) {
@@ -254,9 +240,6 @@ export class ConfigResolver {
         }
         return value;
     }
-    /**
-     * Returns an object configuration value.
-     */
     object(key, fallback) {
         const value = this.store.get(key);
         if (value === undefined) {
@@ -270,9 +253,6 @@ export class ConfigResolver {
         }
         return this.prepareValue(value);
     }
-    /**
-     * Returns an array configuration value.
-     */
     array(key, fallback) {
         const value = this.store.get(key);
         if (value === undefined) {

package/dist/configResolver/core/configResolver.type.d.ts

@@ -17,4 +17,12 @@ export interface ConfigResolutionResult<T extends ConfigValue = ConfigValue> {
     readonly valid: boolean;
     readonly issues: readonly unknown[];
 }
+/**
+ * Widens a literal fallback to its primitive type.
+ *
+ * `get(key, fallback)` returns the stored value when one exists, so a
+ * fallback of `false` or `"dev"` must not narrow the result to the literal
+ * `false` or `"dev"`: the result is `boolean` or `string`.
+ */
+export type ConfigWiden<T> = T extends string ? string : T extends number ? number : T extends boolean ? boolean : T extends bigint ? bigint : T;
 //# sourceMappingURL=configResolver.type.d.ts.map

package/dist/configSchema/configSchema.coerce.d.ts

@@ -0,0 +1,15 @@
+import type { AnyConfigSchema } from "./configSchema.type.js";
+/**
+ * Strictly coerces string input for `NUMBER` and `BOOLEAN` schemas.
+ *
+ * Environment-style sources only ever produce strings. The value is
+ * returned unchanged when it is not a string, when the schema opted out
+ * with `coerce: false`, when the schema also accepts strings (or any
+ * value), or when the string does not parse; the type check that follows
+ * then reports the mismatch as before.
+ *
+ * `NUMBER` is tried before `BOOLEAN`, so `"1"` against
+ * `[NUMBER, BOOLEAN]` becomes `1`.
+ */
+export declare function coerceConfigInput(value: unknown, schema: AnyConfigSchema): unknown;
+//# sourceMappingURL=configSchema.coerce.d.ts.map

package/dist/configSchema/configSchema.coerce.js

@@ -0,0 +1,44 @@
+import { parseConfigBoolean, parseConfigNumber, } from "../configValue/configValue.core.js";
+import { ConfigValueType } from "./configSchema.type.js";
+/**
+ * Returns whether a schema type (single or union) includes `candidate`.
+ */
+function includesType(type, candidate) {
+    return Array.isArray(type) ? type.includes(candidate) : type === candidate;
+}
+/**
+ * Strictly coerces string input for `NUMBER` and `BOOLEAN` schemas.
+ *
+ * Environment-style sources only ever produce strings. The value is
+ * returned unchanged when it is not a string, when the schema opted out
+ * with `coerce: false`, when the schema also accepts strings (or any
+ * value), or when the string does not parse; the type check that follows
+ * then reports the mismatch as before.
+ *
+ * `NUMBER` is tried before `BOOLEAN`, so `"1"` against
+ * `[NUMBER, BOOLEAN]` becomes `1`.
+ */
+export function coerceConfigInput(value, schema) {
+    if (typeof value !== "string" || schema.coerce === false) {
+        return value;
+    }
+    const { type } = schema;
+    if (includesType(type, ConfigValueType.STRING) ||
+        includesType(type, ConfigValueType.ANY)) {
+        return value;
+    }
+    if (includesType(type, ConfigValueType.NUMBER)) {
+        const parsed = parseConfigNumber(value);
+        if (parsed !== undefined) {
+            return parsed;
+        }
+    }
+    if (includesType(type, ConfigValueType.BOOLEAN)) {
+        const parsed = parseConfigBoolean(value);
+        if (parsed !== undefined) {
+            return parsed;
+        }
+    }
+    return value;
+}
+//# sourceMappingURL=configSchema.coerce.js.map

package/dist/configSchema/configSchema.type.d.ts

@@ -64,7 +64,34 @@ export interface ConfigSchema<T extends ConfigValue = ConfigValue> {
      * serialization redact them.
      */
     readonly secret?: boolean;
+    /**
+     * Coerces string input before the type check. Defaults to `true`.
+     *
+     * Environment variables, `.env` files and CLI flags are always
+     * strings, so a `NUMBER` or `BOOLEAN` schema could never pass on them.
+     * When the value is a string, the schema does not itself accept
+     * strings, and the schema type includes `NUMBER` or `BOOLEAN`, the
+     * string is parsed strictly first: decimal numbers only (`"8080"`
+     * passes, `"80a"` and `"0x1F90"` do not), and booleans by the
+     * `parseConfigBoolean` convention (`true/false`, `1/0`, `yes/no`,
+     * `y/n`, `on/off`). A string that does not parse is still reported
+     * as `TYPE_MISMATCH`. `validate` and `transform` receive the coerced
+     * value. Set `false` to require a real number or boolean.
+     */
+    readonly coerce?: boolean;
+    /**
+     * Custom check on the FINAL value, after coercion and `transform`.
+     * Returning `false`, a message or issues fails validation.
+     */
     readonly validate?: (value: T, context: ConfigValidationContext) => boolean | string | ConfigValidationIssue | readonly ConfigValidationIssue[];
+    /**
+     * Converts the value. A value that already has the schema's `type` is
+     * transformed after its constraints pass. A STRING that does not have
+     * the type is passed to `transform` as a parser, and the output must
+     * then have the type and satisfy the constraints (so `{ type: ARRAY,
+     * transform: (s) => String(s).split(",") }` accepts `"a,b"`). A
+     * non-string of the wrong type is rejected without calling it.
+     */
     readonly transform?: (value: ConfigValue, context: ConfigValidationContext) => T;
 }
 /**
@@ -119,30 +146,73 @@ export interface ConfigArraySchema<T extends ConfigValue = ConfigValue> extends
     readonly minItems?: number;
     readonly maxItems?: number;
 }
-/**
- * String configuration schema.
- */
-export interface ConfigStringSchema extends ConfigSchema<string> {
-    readonly type: ConfigValueType.STRING;
+/** Constraints enforced on a string value. */
+export interface ConfigStringConstraints {
     readonly minLength?: number;
     readonly maxLength?: number;
     readonly pattern?: string | RegExp;
     readonly enum?: readonly string[];
 }
-/**
- * Number configuration schema.
- */
-export interface ConfigNumberSchema extends ConfigSchema<number> {
-    readonly type: ConfigValueType.NUMBER;
+/** Constraints enforced on a number value. */
+export interface ConfigNumberConstraints {
     readonly min?: number;
     readonly max?: number;
     readonly integer?: boolean;
     readonly positive?: boolean;
 }
+/**
+ * String configuration schema.
+ */
+export interface ConfigStringSchema extends ConfigSchema<string>, ConfigStringConstraints {
+    readonly type: ConfigValueType.STRING;
+}
+/**
+ * Number configuration schema.
+ */
+export interface ConfigNumberSchema extends ConfigSchema<number>, ConfigNumberConstraints {
+    readonly type: ConfigValueType.NUMBER;
+}
+/**
+ * A schema accepted by `resolve()` / `resolveResult()`: a union keyed on
+ * `type`, so each value type carries exactly the constraints the
+ * validator enforces for it. `{ type: NUMBER, min: 1 }` and
+ * `{ type: STRING, minLength: 1 }` type-check; `{ type: NUMBER,
+ * minLength: 1 }` does not. `T` is the resolved (post-`transform`) type.
+ */
+export type TypedConfigSchema<T extends ConfigValue = ConfigValue> = (ConfigSchemaBase<T> & ConfigStringConstraints & {
+    readonly type: ConfigValueType.STRING;
+}) | (ConfigSchemaBase<T> & ConfigNumberConstraints & {
+    readonly type: ConfigValueType.NUMBER;
+}) | (ConfigSchemaBase<T> & ConfigArrayConstraints & {
+    readonly type: ConfigValueType.ARRAY;
+}) | (ConfigSchemaBase<T> & ConfigObjectConstraints & {
+    readonly type: ConfigValueType.OBJECT;
+}) | (ConfigSchemaBase<T> & {
+    readonly type: ConfigValueType.BOOLEAN | ConfigValueType.BIGINT | ConfigValueType.DATE | ConfigValueType.NULL | ConfigValueType.ANY;
+}) | (ConfigSchemaBase<T> & ConfigStringConstraints & ConfigNumberConstraints & ConfigArrayConstraints & ConfigObjectConstraints & {
+    readonly type: readonly ConfigValueType[];
+});
+/**
+ * {@link ConfigSchema} without `type`, so each {@link TypedConfigSchema}
+ * member can declare a single `type` that TypeScript discriminates on.
+ */
+type ConfigSchemaBase<T extends ConfigValue> = Omit<ConfigSchema<T>, "type">;
+/** Constraints enforced on an array value. */
+export interface ConfigArrayConstraints {
+    readonly items?: AnyConfigSchema;
+    readonly minItems?: number;
+    readonly maxItems?: number;
+}
+/** Nested property schemas enforced on an object value. */
+export interface ConfigObjectConstraints {
+    readonly properties?: Readonly<Record<string, AnyConfigSchema>>;
+    readonly additionalProperties?: boolean | AnyConfigSchema;
+}
 /**
  * Boolean configuration schema.
  */
 export interface ConfigBooleanSchema extends ConfigSchema<boolean> {
     readonly type: ConfigValueType.BOOLEAN;
 }
+export {};
 //# sourceMappingURL=configSchema.type.d.ts.map

package/dist/configSchema/configSchema.validator.d.ts

@@ -17,7 +17,7 @@ export declare function createConfigValidationIssue(path: string, message: strin
 /**
  * Validates a value against a schema.
  */
-export declare function validateConfigValue(value: unknown, schema: AnyConfigSchema, context?: Partial<ConfigValidationContext>): ConfigValidationResult;
+export declare function validateConfigValue(input: unknown, schema: AnyConfigSchema, context?: Partial<ConfigValidationContext>): ConfigValidationResult;
 /**
  * Validates an entire configuration object.
  */

package/dist/configSchema/configSchema.validator.js

@@ -1,5 +1,6 @@
 import { defineConfigProperty, readOwnConfigProperty, } from "../configValue/configValue.core.js";
 import { ConfigValidationSeverity, ConfigValueType, } from "./configSchema.type.js";
+import { coerceConfigInput } from "./configSchema.coerce.js";
 /**
  * Returns the runtime configuration value type.
  */
@@ -218,8 +219,11 @@ function validateBuiltInRules(value, schema, context, issues) {
 /**
  * Validates a value against a schema.
  */
-export function validateConfigValue(value, schema, context) {
+export function validateConfigValue(input, schema, context) {
     const path = context?.path ?? "$";
+    // Env-style strings are parsed for NUMBER/BOOLEAN schemas before the
+    // type check; otherwise "8080" could never satisfy a NUMBER schema.
+    const value = coerceConfigInput(input, schema);
     const validationContext = {
         path,
         root: context?.root ?? value,
@@ -256,63 +260,107 @@ export function validateConfigValue(value, schema, context) {
             issues,
         };
     }
-    if (!matchesConfigType(value, schema.type)) {
-        issues.push(createConfigValidationIssue(path, `Expected ${formatExpectedType(schema.type)} but received ${getConfigValueType(value)}.`, "TYPE_MISMATCH", {
-            expected: schema.type,
-            received: getConfigValueType(value),
-        }));
-        return {
-            valid: false,
-            issues,
-        };
+    const hasErrors = () => issues.some((issue) => issue.severity === ConfigValidationSeverity.ERROR);
+    // Order: coerce -> (transform) -> type check -> constraints -> validate.
+    // A value that already has the schema's type is constrained first and
+    // transformed afterwards (so a type-changing transform such as
+    // `STRING -> Number(v)` keeps working). A string that does NOT have the
+    // type is handed to `transform` as a parser, and its OUTPUT must have
+    // the type and satisfy the constraints. Either way `validate` receives
+    // the final value, matching its `(value: T)` signature.
+    let base;
+    let transformed = false;
+    if (matchesConfigType(value, schema.type)) {
+        base = checkConstraints(value, schema, validationContext, issues);
     }
-    const rewritten = validateBuiltInRules(value, schema, validationContext, issues);
-    // An object schema carries `properties` / `additionalProperties`.
-    // Those were declared on ConfigObjectSchema but read nowhere in this
-    // function, so every nested object schema — including the ones used
-    // by ConfigResolver.resolve() and ConfigManager.resolve() — passed
-    // validation unconditionally. Delegate to validateConfigObject so
-    // nested constraints are actually enforced.
-    const objectSchema = schema;
-    let base = rewritten ?? value;
-    if (matchesConfigType(value, ConfigValueType.OBJECT) &&
-        (objectSchema.properties !== undefined ||
-            objectSchema.additionalProperties !== undefined)) {
-        const nested = validateConfigObject(value, {
-            type: ConfigValueType.OBJECT,
-            properties: objectSchema.properties ?? {},
-            additionalProperties: objectSchema.additionalProperties,
-        }, path);
-        issues.push(...nested.issues);
-        if (nested.value !== undefined) {
-            base = nested.value;
+    else {
+        const parsed = parseWithTransform(value, schema, validationContext);
+        if (parsed === NOT_PARSED || !matchesConfigType(parsed, schema.type)) {
+            issues.push(createConfigValidationIssue(path, `Expected ${formatExpectedType(schema.type)} but received ${getConfigValueType(value)}.`, "TYPE_MISMATCH", {
+                expected: schema.type,
+                received: getConfigValueType(value),
+            }));
+            return {
+                valid: false,
+                issues,
+            };
         }
+        transformed = true;
+        base = checkConstraints(parsed, schema, validationContext, issues);
     }
-    if (schema.validate) {
-        const result = schema.validate(base, validationContext);
-        appendCustomValidationResult(result, path, issues);
-    }
-    let transformed = base;
-    const hasErrors = () => issues.some((issue) => issue.severity === ConfigValidationSeverity.ERROR);
-    // Transforms only run on values that passed validation; running
+    let final = base;
+    // Transforms only run on values that passed their constraints; running
     // them on invalid input would surface invalid values to callers.
-    if (schema.transform && !hasErrors()) {
+    if (!transformed && schema.transform && !hasErrors()) {
         try {
-            transformed = schema.transform(base, validationContext);
+            final = schema.transform(base, validationContext);
+            transformed = true;
         }
         catch (error) {
             issues.push(createConfigValidationIssue(path, error instanceof Error ? error.message : String(error), "TRANSFORM_FAILED"));
         }
     }
+    // `validate` sees the final value. It is skipped only when a transform
+    // should have produced that value but did not run.
+    if (schema.validate && (transformed || schema.transform === undefined)) {
+        const result = schema.validate(final, validationContext);
+        appendCustomValidationResult(result, path, issues);
+    }
     const valid = !hasErrors();
     return {
         valid,
         // Invalid values are never returned; callers fall back to the
         // schema default or undefined instead.
-        value: valid ? transformed : undefined,
+        value: valid ? final : undefined,
         issues,
     };
 }
+/** Marks a transform that threw, or a schema without one. */
+const NOT_PARSED = Symbol("NOT_PARSED");
+/**
+ * Runs `schema.transform` as a parser on a STRING that failed the type
+ * check (environment variables, `.env` files and CLI flags only produce
+ * strings). Returns {@link NOT_PARSED} for any other value, when there is
+ * no transform, or when it threw; the caller then reports the original
+ * type mismatch. A non-string of the wrong type is a real type error and
+ * is never handed to `transform`.
+ */
+function parseWithTransform(value, schema, context) {
+    if (schema.transform === undefined || typeof value !== "string") {
+        return NOT_PARSED;
+    }
+    try {
+        return schema.transform(value, context);
+    }
+    catch {
+        return NOT_PARSED;
+    }
+}
+/**
+ * Applies the built-in constraints and, for object schemas, the nested
+ * property schemas. Returns the value to continue with (rebuilt when an
+ * item or property schema rewrote part of it).
+ */
+function checkConstraints(value, schema, context, issues) {
+    const rewritten = validateBuiltInRules(value, schema, context, issues);
+    // An object schema carries `properties` / `additionalProperties`;
+    // delegate to validateConfigObject so nested constraints are enforced.
+    const objectSchema = schema;
+    if (matchesConfigType(value, ConfigValueType.OBJECT) &&
+        (objectSchema.properties !== undefined ||
+            objectSchema.additionalProperties !== undefined)) {
+        const nested = validateConfigObject(value, {
+            type: ConfigValueType.OBJECT,
+            properties: objectSchema.properties ?? {},
+            additionalProperties: objectSchema.additionalProperties,
+        }, context.path);
+        issues.push(...nested.issues);
+        if (nested.value !== undefined) {
+            return nested.value;
+        }
+    }
+    return rewritten ?? value;
+}
 /**
  * Validates an entire configuration object.
  */

package/dist/configStore/configStore.core.d.ts

@@ -105,11 +105,13 @@ export declare class ConfigStore {
      */
     toSafeObject(): Readonly<Record<string, ConfigValue>>;
     /**
-     * Returns entries matching a prefix.
+     * Returns entries matching a prefix. A trailing dot is optional:
+     * `"db"` and `"db."` both match `db` and `db.*` (but not `dbx`).
      */
     getByPrefix(prefix: string): readonly ConfigEntry[];
     /**
-     * Returns configuration values matching a prefix.
+     * Returns configuration values matching a prefix, keyed by the rest of
+     * the key. A trailing dot is optional, as for {@link getByPrefix}.
      */
     getObjectByPrefix(prefix: string): Readonly<Record<string, ConfigValue>>;
     /**

package/dist/configStore/configStore.core.js

@@ -14,6 +14,18 @@ export function normalizeKey(key) {
     }
     return normalized;
 }
+/**
+ * Normalizes a key prefix: trims it and drops trailing dots, so `"db."`
+ * and `"db"` select the same entries. A prefix that is only dots is
+ * rejected like an empty key.
+ */
+function normalizePrefix(prefix) {
+    const normalized = normalizeKey(prefix).replace(/\.+$/, "");
+    if (normalized.length === 0) {
+        throw new TypeError("Configuration prefix cannot be empty.");
+    }
+    return normalized;
+}
 /**
  * Central in-memory configuration store.
  *
@@ -248,20 +260,22 @@ export class ConfigStore {
         return Object.freeze(result);
     }
     /**
-     * Returns entries matching a prefix.
+     * Returns entries matching a prefix. A trailing dot is optional:
+     * `"db"` and `"db."` both match `db` and `db.*` (but not `dbx`).
      */
     getByPrefix(prefix) {
         this.assertActive();
-        const normalizedPrefix = normalizeKey(prefix);
+        const normalizedPrefix = normalizePrefix(prefix);
         return Array.from(this.entries.values()).filter((entry) => entry.key === normalizedPrefix ||
             entry.key.startsWith(`${normalizedPrefix}.`));
     }
     /**
-     * Returns configuration values matching a prefix.
+     * Returns configuration values matching a prefix, keyed by the rest of
+     * the key. A trailing dot is optional, as for {@link getByPrefix}.
      */
     getObjectByPrefix(prefix) {
         const entries = this.getByPrefix(prefix);
-        const normalizedPrefix = normalizeKey(prefix);
+        const normalizedPrefix = normalizePrefix(prefix);
         const result = {};
         for (const entry of entries) {
             const key = entry.key === normalizedPrefix

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zudojs/config",
-  "version": "1.2.0",
+  "version": "1.3.1",
   "description": "Layered configuration management with multiple sources, validation, and environment-specific overrides.",
   "license": "MIT",
   "author": {
@@ -28,12 +28,12 @@
     "node": ">=24.0.0"
   },
   "dependencies": {
-    "@zudojs/constants": "1.1.1",
-    "@zudojs/errors": "1.2.0"
+    "@zudojs/constants": "1.1.2",
+    "@zudojs/errors": "1.3.0"
   },
   "devDependencies": {
     "typescript": "7.0.2",
-    "vitest": "^4.1.11"
+    "vitest": "^5.0.1"
   },
   "publishConfig": {
     "access": "public"
@@ -44,7 +44,7 @@
     "environment",
     "settings"
   ],
-  "homepage": "https://github.com/oyinlola-tech/zudo#readme",
+  "homepage": "https://zudojs.oyinlola.site/docs/packages-config",
   "bugs": {
     "url": "https://github.com/oyinlola-tech/zudo/issues"
   },