@meltstudio/config-loader 3.2.0 → 3.4.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
+- **Enum constraints** — restrict values to a fixed set with `oneOf`, with full type narrowing
 - **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)
@@ -253,6 +254,45 @@ c.array({
 }); // { name: string; age: number }[]
 ```
 
+## Enum Constraints (`oneOf`)
+
+Use `oneOf` to restrict a field to a fixed set of allowed values. The check runs after type coercion and before any `validate` schema:
+
+```typescript
+const config = c
+  .schema({
+    env: c.string({
+      env: "NODE_ENV",
+      defaultValue: "development",
+      oneOf: ["development", "staging", "production"],
+    }),
+    logLevel: c.number({
+      env: "LOG_LEVEL",
+      defaultValue: 1,
+      oneOf: [0, 1, 2, 3],
+    }),
+  })
+  .load({ env: true, args: false });
+```
+
+If a value is not in the allowed set, a `ConfigLoadError` is thrown with `kind: "validation"`.
+
+### Type Narrowing
+
+When `oneOf` is provided, the inferred type is automatically narrowed to the union of the allowed values:
+
+```typescript
+const config = c
+  .schema({
+    env: c.string({ oneOf: ["dev", "staging", "prod"] }),
+  })
+  .load({ env: false, args: false });
+
+// config.env is typed as "dev" | "staging" | "prod", not string
+```
+
+When used with `cli: true`, the `--help` output automatically lists the allowed values.
+
 ## 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.

package/dist/index.d.ts

@@ -61,6 +61,7 @@ interface OptionClassParams<T extends OptionKind> {
     cli: boolean;
     help: string;
     defaultValue?: TypedDefaultValue<T>;
+    oneOf?: ReadonlyArray<string | number | boolean>;
     validate?: StandardSchemaV1;
 }
 declare class OptionBase<T extends OptionKind = OptionKind> {
@@ -81,6 +82,7 @@ declare class OptionBase<T extends OptionKind = OptionKind> {
         } | null;
     }, envFileResults?: EnvFileResult[], errors?: OptionErrors): ConfigNode | null;
     private resolveValue;
+    private runOneOfCheck;
     private runValidation;
     private resolveFromFileData;
     checkType(val: Value, path: Path, sourceOfVal: string, errors?: OptionErrors): Value;
@@ -101,7 +103,7 @@ declare class ConfigNode {
     constructor(value: Value | ArrayValue, path: string, sourceType: SourceTypes, file: string | null, variableName: string | null, argName: string | null, line?: number | null, column?: number | null);
 }
 
-declare class PrimitiveOption<T extends PrimitiveKind = PrimitiveKind> extends OptionBase<T> {
+declare class PrimitiveOption<T extends PrimitiveKind = PrimitiveKind, Narrowed = TypeOfPrimitiveKind<T>> extends OptionBase<T> {
 }
 
 type NodeTree = {
@@ -140,7 +142,7 @@ type TypeOfPrimitiveKind<T extends PrimitiveKind> = T extends "boolean" ? boolea
 /** Recursively infers the plain TypeScript type from a schema definition. Maps option nodes to their resolved value types. */
 type SchemaValue<T extends OptionBase | Node> = T extends OptionBase ? T extends ArrayOption<OptionTypes> ? SchemaValue<T["item"]>[] : T extends ObjectOption<infer R> ? {
     [K in keyof R]: SchemaValue<R[K]>;
-} : T extends PrimitiveOption<infer R> ? TypeOfPrimitiveKind<R> : never : T extends Node ? {
+} : T extends PrimitiveOption<infer _R, infer Narrowed> ? Narrowed : never : T extends Node ? {
     [K in keyof T]: SchemaValue<T[K]>;
 } : never;
 type Path = Array<string | number>;
@@ -260,6 +262,8 @@ interface OptionPropsArgs<T> {
     defaultValue?: T | (() => T);
     /** Help text shown in CLI `--help` output. */
     help?: string;
+    /** Restrict the value to a fixed set of allowed values. Checked after type coercion, before `validate`. */
+    oneOf?: readonly T[];
     /** Standard Schema validator run after type coercion. Accepts Zod, Valibot, ArkType, or any Standard Schema v1 implementation. */
     validate?: StandardSchemaV1;
 }
@@ -283,6 +287,38 @@ interface ObjectOptionPropsArgs<T extends Node> {
     /** Standard Schema validator run on the resolved object. Accepts Zod, Valibot, ArkType, or any Standard Schema v1 implementation. */
     validate?: StandardSchemaV1;
 }
+/**
+ * Creates a string configuration option.
+ * @param opts - Option configuration (env, cli, required, defaultValue, help, oneOf).
+ * @returns A `PrimitiveOption<"string">` for use in a schema.
+ * @example
+ * c.string({ env: "HOST", defaultValue: "localhost" })
+ * c.string({ env: "NODE_ENV", oneOf: ["development", "staging", "production"] })
+ */
+declare function string<const V extends readonly string[]>(opts: OptionPropsArgs<string> & {
+    oneOf: V;
+}): PrimitiveOption<"string", V[number]>;
+declare function string(opts?: OptionPropsArgs<string>): PrimitiveOption<"string">;
+/**
+ * Creates a number configuration option. String values from env/CLI are coerced to numbers.
+ * @param opts - Option configuration (env, cli, required, defaultValue, help, oneOf).
+ * @returns A `PrimitiveOption<"number">` for use in a schema.
+ * @example
+ * c.number({ env: "PORT", defaultValue: 3000 })
+ * c.number({ env: "LOG_LEVEL", oneOf: [0, 1, 2, 3] })
+ */
+declare function number<const V extends readonly number[]>(opts: OptionPropsArgs<number> & {
+    oneOf: V;
+}): PrimitiveOption<"number", V[number]>;
+declare function number(opts?: OptionPropsArgs<number>): PrimitiveOption<"number">;
+/**
+ * Creates a boolean configuration option. String values `"true"`/`"false"` are coerced.
+ * @param opts - Option configuration (env, cli, required, defaultValue, help).
+ * @returns A `PrimitiveOption<"boolean">` for use in a schema.
+ * @example
+ * c.bool({ env: "DEBUG", defaultValue: false })
+ */
+declare function bool(opts?: OptionPropsArgs<boolean>): PrimitiveOption<"boolean">;
 /**
  * Config-loader entry point. Provides factory functions to define a typed configuration schema.
  *
@@ -297,9 +333,9 @@ interface ObjectOptionPropsArgs<T extends Node> {
  * ```
  */
 declare const option: {
-    string: (opts?: OptionPropsArgs<string>) => PrimitiveOption<"string">;
-    number: (opts?: OptionPropsArgs<number>) => PrimitiveOption<"number">;
-    bool: (opts?: OptionPropsArgs<boolean>) => PrimitiveOption<"boolean">;
+    string: typeof string;
+    number: typeof number;
+    bool: typeof bool;
     array: <T extends OptionTypes>(opts: ArrayOptionPropsArgs<T>) => ArrayOption<T>;
     object: <T extends Node>(opts: ObjectOptionPropsArgs<T>) => ObjectOption<T>;
     schema: <T extends Node>(theSchema: T) => SettingsBuilder<T>;

package/dist/index.js

@@ -292,6 +292,10 @@ var OptionBase = class {
       envFileResults,
       errors
     );
+    if (resolved && this.params.oneOf) {
+      const passed = this.runOneOfCheck(resolved, path2, errors);
+      if (!passed) return resolved;
+    }
     if (resolved && this.params.validate) {
       this.runValidation(resolved, path2, errors);
     }
@@ -455,6 +459,27 @@ var OptionBase = class {
     }
     return null;
   }
+  runOneOfCheck(node, path2, errors) {
+    const allowed = this.params.oneOf;
+    if (!allowed) return true;
+    const value = node.value;
+    if (valueIsInvalid(value)) return true;
+    if (!allowed.includes(value)) {
+      const ident = path2.join(".");
+      const source = node.file ?? node.variableName ?? node.argName ?? node.sourceType;
+      const allowedStr = allowed.map((v) => `'${String(v)}'`).join(", ");
+      errors?.errors.push({
+        message: `Value '${typeof value === "object" ? JSON.stringify(value) : String(value)}' for '${ident}' is not one of: ${allowedStr}.`,
+        path: ident,
+        source,
+        kind: "validation",
+        line: node.line ?? void 0,
+        column: node.column ?? void 0
+      });
+      return false;
+    }
+    return true;
+  }
   runValidation(node, path2, errors) {
     const validator = this.params.validate;
     if (!validator) return;
@@ -654,6 +679,19 @@ var OptionBase = class {
 var ObjectOption = class extends OptionBase {
   item;
   constructor(params) {
+    if (!params.item) {
+      const hasOptionValues = Object.values(params).some(
+        (v) => v instanceof OptionBase
+      );
+      if (hasOptionValues) {
+        throw new Error(
+          "Invalid c.object() call: schema fields were passed directly instead of wrapped in { item: { ... } }. Use c.object({ item: { host: c.string() } }) instead of c.object({ host: c.string() })."
+        );
+      }
+      throw new Error(
+        "Invalid c.object() call: missing required 'item' property. Use c.object({ item: { host: c.string(), port: c.number() } })."
+      );
+    }
     super({
       kind: "object",
       env: null,
@@ -1021,7 +1059,12 @@ var Settings = class {
   addArg(node, path2 = []) {
     if (node.params.cli) {
       const ident = path2.join(".");
-      this.program.option(`--${ident} <value>`, node.params.help);
+      let help = node.params.help;
+      if (node.params.oneOf) {
+        const allowed = node.params.oneOf.map(String).join(", ");
+        help = help ? `${help} (one of: ${allowed})` : `one of: ${allowed}`;
+      }
+      this.program.option(`--${ident} <value>`, help);
     }
   }
   getValuesFromTree(node) {
@@ -1212,27 +1255,27 @@ var DEFAULTS = {
   cli: false,
   help: ""
 };
-var string = (opts) => {
+function string(opts) {
   return new PrimitiveOption({
     kind: "string",
     ...DEFAULTS,
     ...opts
   });
-};
-var number = (opts) => {
+}
+function number(opts) {
   return new PrimitiveOption({
     kind: "number",
     ...DEFAULTS,
     ...opts
   });
-};
-var bool = (opts) => {
+}
+function bool(opts) {
   return new PrimitiveOption({
     kind: "boolean",
     ...DEFAULTS,
     ...opts
   });
-};
+}
 var array = (opts) => {
   return new ArrayOption({
     ...DEFAULTS,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meltstudio/config-loader",
-  "version": "3.2.0",
+  "version": "3.4.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",