@meltstudio/config-loader 3.3.0 → 3.5.0

package/README.md

@@ -61,6 +61,8 @@ 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
+- **Sensitive fields** — mark fields with `sensitive: true` to auto-mask in `printConfig()` and `maskSecrets()`
 - **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 +255,97 @@ 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.
+
+## Sensitive Fields
+
+Mark fields as `sensitive: true` to prevent their values from being exposed in logs or debug output:
+
+```typescript
+const schema = {
+  host: c.string({ defaultValue: "localhost" }),
+  apiKey: c.string({ env: "API_KEY", sensitive: true }),
+  db: c.object({
+    item: {
+      host: c.string({ defaultValue: "db.local" }),
+      password: c.string({ env: "DB_PASS", sensitive: true }),
+    },
+  }),
+};
+
+const config = c.schema(schema).load({ env: true, args: false });
+```
+
+Sensitive values load normally — `config.apiKey` returns the real value. The flag only affects masking utilities.
+
+### `printConfig()` auto-masking
+
+`printConfig()` automatically masks sensitive fields:
+
+```typescript
+const result = c.schema(schema).loadExtended({ env: true, args: false });
+printConfig(result);
+// apiKey shows "***" instead of the real value
+// db.password shows "***" instead of the real value
+```
+
+### `maskSecrets()`
+
+Use `maskSecrets()` to create a safe-to-log copy of your config:
+
+```typescript
+import c, { maskSecrets } from "@meltstudio/config-loader";
+
+// With a plain config from load()
+const config = c.schema(schema).load({ env: true, args: false });
+console.log(maskSecrets(config, schema));
+// { host: "localhost", apiKey: "***", db: { host: "db.local", password: "***" } }
+
+// With an extended result from loadExtended()
+const result = c.schema(schema).loadExtended({ env: true, args: false });
+const masked = maskSecrets(result);
+// masked.data contains ConfigNodes with "***" for sensitive values
+```
+
+The original config object is never mutated — `maskSecrets()` always returns a new copy.
+
 ## 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.
@@ -471,6 +564,8 @@ import c, {
   ConfigNodeArray, // Class representing an array of ConfigNode values
   type RecursivePartial, // Deep partial utility used by the defaults option
   type StandardSchemaV1, // Standard Schema v1 interface for validators
+  maskSecrets, // Create a safe-to-log copy with sensitive values masked
+  printConfig, // Format loadExtended() result as a readable table
 } from "@meltstudio/config-loader";
 ```
 

package/dist/index.d.ts

@@ -60,7 +60,9 @@ interface OptionClassParams<T extends OptionKind> {
     env: string | null;
     cli: boolean;
     help: string;
+    sensitive?: boolean;
     defaultValue?: TypedDefaultValue<T>;
+    oneOf?: ReadonlyArray<string | number | boolean>;
     validate?: StandardSchemaV1;
 }
 declare class OptionBase<T extends OptionKind = OptionKind> {
@@ -81,6 +83,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;
@@ -98,10 +101,11 @@ declare class ConfigNode {
     argName: string | null;
     line: number | null;
     column: number | null;
-    constructor(value: Value | ArrayValue, path: string, sourceType: SourceTypes, file: string | null, variableName: string | null, argName: string | null, line?: number | null, column?: number | null);
+    sensitive: boolean;
+    constructor(value: Value | ArrayValue, path: string, sourceType: SourceTypes, file: string | null, variableName: string | null, argName: string | null, line?: number | null, column?: number | null, sensitive?: boolean);
 }
 
-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 +144,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>;
@@ -223,6 +227,24 @@ declare class SettingsBuilder<T extends Node> {
     loadExtended(sources: SettingsSources<SchemaValue<T>>): ExtendedResult;
 }
 
+/**
+ * Masks sensitive values in an `ExtendedResult` from `loadExtended()`.
+ * Fields marked `sensitive: true` have their values replaced with `"***"`.
+ *
+ * @param result - The `ExtendedResult` returned by `loadExtended()`.
+ * @returns A new `ExtendedResult` with sensitive values masked.
+ */
+declare function maskSecrets(result: ExtendedResult): ExtendedResult;
+/**
+ * Masks sensitive values in a plain config object from `load()`.
+ * Fields marked `sensitive: true` in the schema have their values replaced with `"***"`.
+ *
+ * @param config - The plain config object returned by `load()`.
+ * @param schema - The schema definition used to identify sensitive fields.
+ * @returns A new object with sensitive values masked.
+ */
+declare function maskSecrets<T extends Record<string, unknown>>(config: T, schema: Node): T;
+
 declare class ConfigNodeArray {
     arrayValues: ConfigNode[];
     constructor(arrayValues: ConfigNode[]);
@@ -260,6 +282,10 @@ interface OptionPropsArgs<T> {
     defaultValue?: T | (() => T);
     /** Help text shown in CLI `--help` output. */
     help?: string;
+    /** Mark this field as sensitive. Sensitive values are masked by `printConfig()` and `maskSecrets()`. */
+    sensitive?: boolean;
+    /** 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 +309,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,12 +355,12 @@ 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>;
 };
 
-export { type ConfigErrorEntry, ConfigFileError, ConfigLoadError, ConfigNode, ConfigNodeArray, type ExtendedResult, type NodeTree, type RecursivePartial, type SchemaValue, type SettingsSources, type StandardSchemaV1, option as default, printConfig };
+export { type ConfigErrorEntry, ConfigFileError, ConfigLoadError, ConfigNode, ConfigNodeArray, type ExtendedResult, type NodeTree, type RecursivePartial, type SchemaValue, type SettingsSources, type StandardSchemaV1, option as default, maskSecrets, printConfig };

package/dist/index.js

@@ -35,6 +35,7 @@ __export(index_exports, {
   ConfigNode: () => configNode_default,
   ConfigNodeArray: () => configNodeArray_default,
   default: () => index_default,
+  maskSecrets: () => maskSecrets,
   printConfig: () => printConfig
 });
 module.exports = __toCommonJS(index_exports);
@@ -81,7 +82,8 @@ var ConfigNode = class {
   argName;
   line;
   column;
-  constructor(value, path2, sourceType, file, variableName, argName, line = null, column = null) {
+  sensitive;
+  constructor(value, path2, sourceType, file, variableName, argName, line = null, column = null, sensitive = false) {
     this.value = value;
     this.path = path2;
     this.sourceType = sourceType;
@@ -90,6 +92,7 @@ var ConfigNode = class {
     this.argName = argName;
     this.line = line;
     this.column = column;
+    this.sensitive = sensitive;
   }
 };
 var configNode_default = ConfigNode;
@@ -292,6 +295,13 @@ var OptionBase = class {
       envFileResults,
       errors
     );
+    if (resolved && this.params.sensitive) {
+      resolved.sensitive = true;
+    }
+    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 +465,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;
@@ -1034,7 +1065,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) {
@@ -1097,6 +1133,76 @@ var SettingsBuilder = class {
   }
 };
 
+// src/maskSecrets.ts
+var MASK = "***";
+function maskNodeTree(tree) {
+  const result = {};
+  for (const [key, entry] of Object.entries(tree)) {
+    if (entry instanceof configNode_default) {
+      if (entry.sensitive) {
+        const masked = new configNode_default(
+          MASK,
+          entry.path,
+          entry.sourceType,
+          entry.file,
+          entry.variableName,
+          entry.argName,
+          entry.line,
+          entry.column,
+          entry.sensitive
+        );
+        if (entry.value instanceof configNodeArray_default) {
+          masked.value = entry.value;
+        }
+        result[key] = masked;
+      } else {
+        result[key] = entry;
+      }
+    } else {
+      result[key] = maskNodeTree(entry);
+    }
+  }
+  return result;
+}
+function maskPlainObject(obj, schema2) {
+  const result = {};
+  for (const [key, value] of Object.entries(obj)) {
+    const schemaNode = schema2[key];
+    if (!schemaNode) {
+      result[key] = value;
+      continue;
+    }
+    if (schemaNode instanceof ObjectOption) {
+      if (value && typeof value === "object" && !Array.isArray(value)) {
+        result[key] = maskPlainObject(
+          value,
+          schemaNode.item
+        );
+      } else {
+        result[key] = value;
+      }
+    } else if (schemaNode instanceof OptionBase) {
+      result[key] = schemaNode.params.sensitive ? MASK : value;
+    } else {
+      result[key] = value;
+    }
+  }
+  return result;
+}
+function maskSecrets(resultOrConfig, schema2) {
+  if ("data" in resultOrConfig && "warnings" in resultOrConfig && !schema2) {
+    const extended = resultOrConfig;
+    return {
+      data: maskNodeTree(extended.data),
+      warnings: [...extended.warnings]
+    };
+  }
+  if (schema2) {
+    return maskPlainObject(resultOrConfig, schema2);
+  }
+  return resultOrConfig;
+}
+
 // src/printConfig.ts
 function truncate(str, max) {
   if (str.length <= max) return str;
@@ -1153,7 +1259,7 @@ function flattenTree(tree, prefix = "") {
       } else {
         rows.push({
           path: path2,
-          value: formatValue(entry.value),
+          value: entry.sensitive ? "***" : formatValue(entry.value),
           source: entry.sourceType,
           detail: formatDetail(entry)
         });
@@ -1225,27 +1331,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,
@@ -1276,5 +1382,6 @@ var index_default = option;
   ConfigLoadError,
   ConfigNode,
   ConfigNodeArray,
+  maskSecrets,
   printConfig
 });

package/package.json

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