@meltstudio/config-loader 3.4.0 → 3.5.0

package/README.md

@@ -62,6 +62,7 @@ No separate interface to maintain. No `as` casts. The types flow from the schema
 - **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)
@@ -293,6 +294,58 @@ const config = c
 
 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.
@@ -511,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,6 +60,7 @@ interface OptionClassParams<T extends OptionKind> {
     env: string | null;
     cli: boolean;
     help: string;
+    sensitive?: boolean;
     defaultValue?: TypedDefaultValue<T>;
     oneOf?: ReadonlyArray<string | number | boolean>;
     validate?: StandardSchemaV1;
@@ -100,7 +101,8 @@ 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, Narrowed = TypeOfPrimitiveKind<T>> extends OptionBase<T> {
@@ -225,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[]);
@@ -262,6 +282,8 @@ 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. */
@@ -341,4 +363,4 @@ declare const option: {
     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,9 @@ 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;
@@ -1127,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;
@@ -1183,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)
         });
@@ -1306,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.4.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",