@meltstudio/config-loader 3.4.0 → 3.6.0

package/README.md

@@ -1,6 +1,6 @@
 # @meltstudio/config-loader
 
-A type-safe configuration loader for Node.js. Define your schema once, load from YAML or JSON files, `.env` files, environment variables, and CLI arguments — and get a fully typed result with zero manual type annotations.
+A type-safe configuration loader for Node.js. Define your schema once, load from YAML, JSON, or TOML files, `.env` files, environment variables, and CLI arguments — and get a fully typed result with zero manual type annotations.
 
 > **Upgrading from v1?** v1.x is deprecated. v2 includes breaking changes to the public API, object schema syntax, and requires Node.js >= 20. Install the latest version with `npm install @meltstudio/config-loader@latest` or `yarn add @meltstudio/config-loader@latest`.
 
@@ -16,61 +16,45 @@ import c from "@meltstudio/config-loader";
 const config = c
   .schema({
     port: c.number({ required: true, env: "PORT" }),
+    host: c.string({ env: "HOST", defaultValue: "localhost" }),
+    env: c.string({
+      env: "NODE_ENV",
+      defaultValue: "development",
+      oneOf: ["development", "staging", "production"],
+    }),
+    apiKey: c.string({ env: "API_KEY", sensitive: true }),
     database: c.object({
       item: {
         host: c.string({ required: true }),
-        credentials: c.object({
-          item: {
-            username: c.string(),
-            password: c.string({ env: "DB_PASSWORD" }),
-          },
-        }),
+        password: c.string({ env: "DB_PASSWORD", sensitive: true }),
       },
     }),
-    features: c.array({
-      required: true,
-      item: c.object({
-        item: {
-          name: c.string(),
-          enabled: c.bool(),
-        },
-      }),
-    }),
   })
   .load({
     env: true,
     args: true,
     files: "./config.yaml",
+    envFile: "./.env",
   });
 
-// config is fully typed:
-// {
-//   port: number;
-//   database: { host: string; credentials: { username: string; password: string } };
-//   features: { name: string; enabled: boolean }[];
-// }
+// config is fully typed — no `as` casts, no separate interfaces
 ```
 
-No separate interface to maintain. No `as` casts. The types flow from the schema.
-
 ## Features
 
 - **Full type inference** — schema definition produces typed output automatically
-- **Multiple sources** — YAML files, JSON files, `.env` files, environment variables, CLI arguments
+- **Multiple sources** — YAML, JSON, TOML files, `.env` files, environment variables, CLI arguments
 - **Priority resolution** — CLI > process.env > `.env` files > Config files > Defaults
 - **`.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)
 - **Multiple files / directory loading** — load from a list of files or an entire directory
 
-## Requirements
-
-- Node.js >= 20
-
 ## Installation
 
 ```bash
@@ -81,698 +65,15 @@ npm install @meltstudio/config-loader
 yarn add @meltstudio/config-loader
 ```
 
-## Quick Start
-
-**config.yaml:**
-
-```yaml
-version: 1.0.0
-website:
-  title: My Website
-  description: A simple and elegant website
-  isProduction: false
-
-database:
-  host: localhost
-  port: 5432
-  credentials:
-    username: admin
-    password: secret
-
-socialMedia: [https://twitter.com/example, https://instagram.com/example]
-
-features:
-  - name: Store
-    enabled: true
-  - name: Admin
-    enabled: false
-```
-
-**index.ts:**
-
-```typescript
-import path from "path";
-import c from "@meltstudio/config-loader";
-
-const config = c
-  .schema({
-    version: c.string({ required: true, cli: true }),
-    website: c.object({
-      item: {
-        title: c.string({ required: true }),
-        url: c.string({
-          required: false,
-          defaultValue: "www.mywebsite.dev",
-        }),
-        description: c.string({ required: true }),
-        isProduction: c.bool({ required: true }),
-      },
-    }),
-    database: c.object({
-      item: {
-        host: c.string({ required: true }),
-        port: c.number({ required: true }),
-        credentials: c.object({
-          item: {
-            username: c.string(),
-            password: c.string(),
-          },
-        }),
-      },
-    }),
-    socialMedia: c.array({
-      required: true,
-      item: c.string({ required: true }),
-    }),
-    features: c.array({
-      required: true,
-      item: c.object({
-        item: {
-          name: c.string(),
-          enabled: c.bool(),
-        },
-      }),
-    }),
-  })
-  .load({
-    env: false,
-    args: true,
-    files: path.join(__dirname, "./config.yaml"),
-  });
-
-console.log(JSON.stringify(config, null, 2));
-```
-
-Output:
-
-```json
-{
-  "version": "1.0.0",
-  "website": {
-    "title": "My Website",
-    "url": "www.mywebsite.dev",
-    "description": "A simple and elegant website",
-    "isProduction": false
-  },
-  "database": {
-    "host": "localhost",
-    "port": 5432,
-    "credentials": {
-      "username": "admin",
-      "password": "secret"
-    }
-  },
-  "socialMedia": [
-    "https://twitter.com/example",
-    "https://instagram.com/example"
-  ],
-  "features": [
-    { "name": "Store", "enabled": true },
-    { "name": "Admin", "enabled": false }
-  ]
-}
-```
-
-## Schema API
-
-### Primitives
-
-```typescript
-c.string({
-  required: true,
-  env: "MY_VAR",
-  cli: true,
-  defaultValue: "fallback",
-});
-c.number({ required: true, env: "PORT" });
-c.bool({ env: "DEBUG", defaultValue: false });
-```
-
-### Objects
-
-Use `c.object()` to declare nested object schemas:
-
-```typescript
-c.object({
-  item: {
-    host: c.string(),
-    port: c.number(),
-  },
-});
-```
-
-Objects can be nested arbitrarily deep:
-
-```typescript
-c.schema({
-  database: c.object({
-    item: {
-      host: c.string(),
-      port: c.number(),
-      credentials: c.object({
-        item: {
-          username: c.string(),
-          password: c.string({ env: "DB_PASSWORD" }),
-        },
-      }),
-    },
-  }),
-});
-```
-
-`c.object()` accepts a `required` option (defaults to `false`). When the entire subtree is absent from all sources, child `required` options will trigger errors through normal validation.
-
-### Arrays
-
-```typescript
-c.array({ required: true, item: c.string() }); // string[]
-c.array({ required: true, item: c.number() }); // number[]
-c.array({
-  item: c.object({
-    item: { name: c.string(), age: c.number() },
-  }),
-}); // { 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.
-
-Validation runs **after** type coercion, so validators see the final typed value (e.g., the number `3000`, not the string `"3000"` from an env var).
-
-### With Zod
-
-```typescript
-import c from "@meltstudio/config-loader";
-import { z } from "zod";
-
-const config = c
-  .schema({
-    port: c.number({
-      required: true,
-      env: "PORT",
-      validate: z.number().min(1).max(65535),
-    }),
-    host: c.string({
-      required: true,
-      validate: z.string().url(),
-    }),
-    env: c.string({
-      defaultValue: "development",
-      validate: z.enum(["development", "staging", "production"]),
-    }),
-  })
-  .load({ env: true, args: false, files: "./config.yaml" });
-```
-
-### With a custom validator
-
-Any object with a `~standard.validate()` method works:
-
-```typescript
-const portValidator = {
-  "~standard": {
-    version: 1,
-    vendor: "my-app",
-    validate(value: unknown) {
-      if (typeof value === "number" && value >= 1 && value <= 65535) {
-        return { value };
-      }
-      return { issues: [{ message: "must be a valid port (1-65535)" }] };
-    },
-  },
-};
-
-c.number({ required: true, env: "PORT", validate: portValidator });
-```
-
-Validation errors are collected alongside other config errors and thrown as `ConfigLoadError` with `kind: "validation"`:
-
-```typescript
-try {
-  const config = c.schema({ ... }).load({ ... });
-} catch (err) {
-  if (err instanceof ConfigLoadError) {
-    for (const entry of err.errors) {
-      if (entry.kind === "validation") {
-        console.error(`Validation: ${entry.path} — ${entry.message}`);
-      }
-    }
-  }
-}
-```
-
-## Loading Sources
-
-```typescript
-.load({
-  env: true,          // Read from process.env
-  args: true,         // Read from CLI arguments (--database.port 3000)
-  files: "./config.yaml",                    // Single YAML file
-  files: "./config.json",                    // Single JSON file
-  files: ["./base.yaml", "./overrides.json"], // Mix YAML and JSON (first takes priority)
-  dir: "./config.d/",                        // All files in a directory (sorted)
-  envFile: "./.env",                         // Single .env file
-  envFile: ["./.env", "./.env.local"],       // Multiple .env files (later overrides earlier)
-  defaults: { port: 3000 },                  // Programmatic defaults
-})
-```
-
-Both YAML (`.yaml`, `.yml`) and JSON (`.json`) files are supported. The format is detected automatically from the file extension.
-
-**Priority order:** CLI arguments > `process.env` > `.env` files > Config files > Defaults
-
-## Extended Loading (Source Metadata)
-
-Use `loadExtended()` instead of `load()` to get each value wrapped in a `ConfigNode` that includes source metadata — where the value came from, which file, environment variable, or CLI argument provided it.
-
-```typescript
-import c from "@meltstudio/config-loader";
-
-const { data, warnings } = c
-  .schema({
-    port: c.number({ required: true, env: "PORT" }),
-    host: c.string({ defaultValue: "localhost" }),
-  })
-  .loadExtended({
-    env: true,
-    args: false,
-    files: "./config.yaml",
-  });
-
-// `warnings` is a string[] of non-fatal issues (e.g. type coercions, unused env mappings)
-if (warnings.length > 0) {
-  warnings.forEach((w) => console.warn(w));
-}
-
-// Each leaf in `data` is a ConfigNode with:
-// {
-//   value: 3000,
-//   path: "port",
-//   sourceType: "env" | "envFile" | "file" | "args" | "default",
-//   file: "./config.yaml" | "./.env" | null,
-//   variableName: "PORT" | null,
-//   argName: null,
-//   line: 5 | null,      // source line (1-based) for YAML, JSON, and .env files; null for env/args/default
-//   column: 3 | null      // source column (1-based) for YAML, JSON, and .env files; null for env/args/default
-// }
-console.log(data.port.value); // 3000
-console.log(data.port.sourceType); // "env"
-console.log(data.port.variableName); // "PORT"
-```
-
-This is useful for debugging configuration resolution, building admin UIs that show where each setting originated, or auditing which sources are active.
-
-### Debug Helper
-
-Use `printConfig()` to format the result of `loadExtended()` as a readable table:
-
-```typescript
-import c, { printConfig } from "@meltstudio/config-loader";
-
-const result = c
-  .schema({
-    host: c.string({ defaultValue: "localhost" }),
-    port: c.number({ env: "PORT" }),
-    debug: c.bool({ cli: true }),
-  })
-  .loadExtended({ env: true, args: true, files: "./config.yaml" });
-
-printConfig(result);
-```
-
-Output:
-
-```
-┌───────┬───────────┬─────────┬────────────────┐
-│ Path  │ Value     │ Source  │ Detail         │
-├───────┼───────────┼─────────┼────────────────┤
-│ host  │ localhost │ default │                │
-│ port  │ 8080      │ env     │ PORT           │
-│ debug │ true      │ args    │ --debug        │
-└───────┴───────────┴─────────┴────────────────┘
-```
-
-Options:
-
-- `printConfig(result, { silent: true })` — returns the string without printing to console
-- `printConfig(result, { maxValueLength: 30 })` — truncate long values (default: 50)
-
-## Error Handling
-
-When validation fails, config-loader throws a `ConfigLoadError` with structured error details:
-
-```typescript
-import c, { ConfigLoadError } from "@meltstudio/config-loader";
-
-try {
-  const config = c.schema({ port: c.number({ required: true }) }).load({
-    env: false,
-    args: false,
-    files: "./config.yaml",
-  });
-} catch (err) {
-  if (err instanceof ConfigLoadError) {
-    for (const entry of err.errors) {
-      console.error(`[${entry.kind}] ${entry.message}`);
-      // e.g. [required] Required option 'port' not provided.
-    }
-  }
-}
-```
-
-Warnings (non-fatal issues like type coercions) are never printed to the console. Use `loadExtended()` to access them, or they are included in `ConfigLoadError.warnings` when errors occur.
-
-### Strict Mode
-
-Enable `strict: true` to promote all warnings to errors, causing `ConfigLoadError` to be thrown for any ambiguous or lossy configuration:
-
-```typescript
-.load({
-  env: true,
-  args: false,
-  files: "./config.yaml",
-  strict: true,
-})
-```
-
-This is useful in production environments where you want to catch type coercions, null values, and other ambiguous config early rather than silently accepting them.
-
-## TypeScript Utilities
-
-config-loader exports several types for advanced use cases:
-
-```typescript
-import c, {
-  type SchemaValue, // Infer the resolved config type from a schema
-  type SettingsSources, // Type for the sources object passed to load()
-  type ExtendedResult, // Return type of loadExtended()
-  type NodeTree, // Tree of ConfigNode objects (ExtendedResult.data)
-  ConfigNode, // Class representing a resolved value with source metadata
-  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
-} from "@meltstudio/config-loader";
-```
-
-The most commonly needed is `SchemaValue`, which infers the plain TypeScript type from a schema:
-
-```typescript
-const mySchema = {
-  port: c.number({ env: "PORT" }),
-  db: c.object({ item: { host: c.string(), port: c.number() } }),
-};
-
-type MyConfig = SchemaValue<typeof mySchema>;
-// { port: number; db: { host: string; port: number } }
-```
-
-## CLI Arguments
-
-Set `cli: true` on an option to allow overriding via command line:
-
-```typescript
-c.schema({
-  version: c.string({ required: true, cli: true }),
-});
-```
-
-```bash
-node app.js --version 2.0.0
-```
-
-## Environment Variables
-
-Set `env: "VAR_NAME"` on an option and `env: true` in the load options:
-
-```typescript
-c.schema({
-  database: c.object({
-    item: {
-      password: c.string({ env: "DB_PASSWORD" }),
-    },
-  }),
-}).load({ env: true, args: false, files: "./config.yaml" });
-```
-
-## `.env` File Support
-
-Load environment variables from `.env` files using the `envFile` option. Options with an `env` mapping automatically pick up values from `.env` files — no new syntax needed on individual fields.
-
-**.env:**
-
-```bash
-DB_HOST=localhost
-DB_PORT=5432
-DB_PASSWORD="s3cret"
-APP_NAME='My App'
-# This is a comment
-```
-
-**Usage:**
-
-```typescript
-const config = c
-  .schema({
-    host: c.string({ env: "DB_HOST" }),
-    port: c.number({ env: "DB_PORT" }),
-    password: c.string({ env: "DB_PASSWORD" }),
-  })
-  .load({
-    env: true,
-    args: false,
-    envFile: "./.env",
-  });
-```
-
-`process.env` always takes precedence over `.env` file values. This means you can use `.env` files for development defaults while overriding them in production via real environment variables.
-
-**Multiple `.env` files:**
-
-```typescript
-.load({
-  env: true,
-  args: false,
-  envFile: ["./.env", "./.env.local"],  // .env.local overrides .env
-})
-```
-
-When using multiple files, later files override earlier ones for the same key.
-
-The `.env` parser supports:
-
-- `KEY=VALUE` pairs (whitespace trimmed)
-- Comments (lines starting with `#`)
-- Quoted values (double `"..."` or single `'...'` quotes stripped)
-- Empty values (`KEY=`)
-
-When using `loadExtended()`, values from `.env` files have `sourceType: "envFile"` with `file`, `line`, and `column` metadata pointing to the `.env` file location.
-
-## Common Patterns
+Requires Node.js >= 20.
 
-### Load from YAML with env overrides
-
-```typescript
-import c from "@meltstudio/config-loader";
-
-const config = c
-  .schema({
-    port: c.number({ required: true, env: "PORT", defaultValue: 3000 }),
-    host: c.string({ required: true, env: "HOST", defaultValue: "localhost" }),
-  })
-  .load({ env: true, args: false, files: "./config.yaml" });
-```
-
-### Strict mode for production
-
-```typescript
-const config = c
-  .schema({
-    port: c.number({ required: true, env: "PORT" }),
-    dbUrl: c.string({ required: true, env: "DATABASE_URL" }),
-  })
-  .load({
-    env: true,
-    args: false,
-    files: "./config.yaml",
-    strict: true, // any type coercion or ambiguity throws an error
-  });
-```
-
-### Catch and inspect errors
-
-```typescript
-import c, { ConfigLoadError } from "@meltstudio/config-loader";
-
-try {
-  const config = c
-    .schema({ port: c.number({ required: true }) })
-    .load({ env: false, args: false, files: "./config.yaml" });
-} catch (err) {
-  if (err instanceof ConfigLoadError) {
-    for (const entry of err.errors) {
-      console.error(`[${entry.kind}] ${entry.path}: ${entry.message}`);
-    }
-    // err.warnings contains non-fatal issues
-  }
-}
-```
-
-### Load from a directory of config files
-
-```typescript
-const config = c
-  .schema({
-    port: c.number({ required: true }),
-    host: c.string({ required: true }),
-  })
-  .load({ env: false, args: false, dir: "./config.d/" });
-// All YAML/JSON files in the directory are loaded and merged (sorted by filename)
-```
-
-### Access source metadata with loadExtended
-
-```typescript
-const { data, warnings } = c
-  .schema({
-    port: c.number({ required: true, env: "PORT" }),
-  })
-  .loadExtended({ env: true, args: false, files: "./config.yaml" });
-
-const portNode = data.port; // ConfigNode
-console.log(portNode.value); // 3000
-console.log(portNode.sourceType); // "env" | "file" | "default" | "args" | "envFile"
-console.log(portNode.file); // "./config.yaml" or null
-console.log(portNode.line); // source line number or null
-```
-
-### Combine .env files with process.env
-
-```typescript
-const config = c
-  .schema({
-    apiKey: c.string({ required: true, env: "API_KEY" }),
-    debug: c.bool({ env: "DEBUG", defaultValue: false }),
-  })
-  .load({
-    env: true, // reads process.env
-    args: false,
-    envFile: ["./.env", "./.env.local"], // .env.local overrides .env
-  });
-// Priority: process.env > .env.local > .env > defaults
-```
-
-## Common Mistakes
-
-### Forgetting `item` in `c.object()`
-
-```typescript
-// WRONG — fields are passed directly
-c.object({ host: c.string(), port: c.number() });
-
-// CORRECT — fields must be inside `item`
-c.object({ item: { host: c.string(), port: c.number() } });
-```
-
-### Setting `env` on an option but not enabling env loading
-
-```typescript
-// WRONG — env: "PORT" is set but env loading is disabled
-c.schema({ port: c.number({ env: "PORT" }) }).load({
-  env: false,
-  args: false,
-  files: "./config.yaml",
-});
-// This emits a warning: "Options [port] have env mappings but env loading is disabled"
-
-// CORRECT — set env: true in load options
-c.schema({ port: c.number({ env: "PORT" }) }).load({
-  env: true,
-  args: false,
-  files: "./config.yaml",
-});
-```
-
-### Expecting `.env` files to work without `envFile`
-
-```typescript
-// WRONG — .env files are not loaded by default
-c.schema({ key: c.string({ env: "API_KEY" }) }).load({
-  env: true,
-  args: false,
-});
-// This only reads process.env, not .env files
-
-// CORRECT — explicitly pass envFile
-c.schema({ key: c.string({ env: "API_KEY" }) }).load({
-  env: true,
-  args: false,
-  envFile: "./.env",
-});
-```
-
-### Not catching `ConfigLoadError`
-
-```typescript
-// WRONG — unhandled error crashes the process with an unhelpful stack trace
-const config = c
-  .schema({ port: c.number({ required: true }) })
-  .load({ env: false, args: false });
-
-// CORRECT — catch and handle structured errors
-try {
-  const config = c
-    .schema({ port: c.number({ required: true }) })
-    .load({ env: false, args: false });
-} catch (err) {
-  if (err instanceof ConfigLoadError) {
-    console.error(err.errors); // structured error details
-  }
-}
-```
+## Documentation
 
-### Using `required: true` on nested fields without the parent object
+See the **[full documentation](https://meltstudio.github.io/config-loader/)** for:
 
-If the parent object is entirely absent from all sources, child `required` fields will still trigger errors. Use `required` on the parent `c.object()` only if the entire subtree must be present.
+- [Schema API](https://meltstudio.github.io/config-loader/schema-api) — primitives, objects, arrays, `oneOf`, `sensitive`, validation
+- [Loading & Sources](https://meltstudio.github.io/config-loader/loading-and-sources) — `load()`, `loadExtended()`, file/env/CLI/.env sources, `printConfig()`, `maskSecrets()`, error handling, strict mode
+- [TypeScript Utilities](https://meltstudio.github.io/config-loader/typescript-utilities) — `SchemaValue`, exported types, type narrowing
 
 ## Documentation for AI Agents
 
@@ -785,4 +86,4 @@ These files follow the [llms.txt standard](https://llmstxt.org/) and are generat
 
 ## License
 
-This package is licensed under the MIT License. See the [LICENSE](./LICENSE) file for details.
+Built by [Melt Studio](https://meltstudio.co). Licensed under the [MIT License](./LICENSE).

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;
@@ -123,6 +126,7 @@ var fs = __toESM(require("fs"));
 var import_js_yaml = __toESM(require("js-yaml"));
 var import_js_yaml_source_map = __toESM(require("js-yaml-source-map"));
 var path = __toESM(require("path"));
+var import_smol_toml = require("smol-toml");
 var fileCache = /* @__PURE__ */ new Map();
 var JsonSourceMap = class {
   locations = /* @__PURE__ */ new Map();
@@ -185,6 +189,47 @@ var JsonSourceMap = class {
     return this.locations.get(key);
   }
 };
+function escapeRegex(str) {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function walkTomlObject(obj, prefix, lines, locations) {
+  for (const key of Object.keys(obj)) {
+    const fullPath = [...prefix, key].join(".");
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      const keyPattern = new RegExp(`^\\s*${escapeRegex(key)}\\s*=`);
+      if (keyPattern.test(line)) {
+        const idx = line.indexOf(key);
+        locations.set(fullPath, {
+          line: i + 1,
+          column: idx + 1,
+          position: 0
+        });
+        break;
+      }
+    }
+    const val = obj[key];
+    if (val && typeof val === "object" && !Array.isArray(val)) {
+      walkTomlObject(
+        val,
+        [...prefix, key],
+        lines,
+        locations
+      );
+    }
+  }
+}
+function buildTomlSourceMap(content, data) {
+  const locations = /* @__PURE__ */ new Map();
+  const lines = content.split("\n");
+  walkTomlObject(data, [], lines, locations);
+  return {
+    lookup(lookupPath) {
+      const key = Array.isArray(lookupPath) ? lookupPath.join(".") : lookupPath;
+      return locations.get(key);
+    }
+  };
+}
 function loadConfigFile(filePath) {
   const cached = fileCache.get(filePath);
   if (cached) return cached;
@@ -199,6 +244,15 @@ function loadConfigFile(filePath) {
       fileCache.set(filePath, result2);
       return result2;
     }
+    if (ext === ".toml") {
+      const data2 = (0, import_smol_toml.parse)(content);
+      const result2 = {
+        data: data2,
+        sourceMap: buildTomlSourceMap(content, data2)
+      };
+      fileCache.set(filePath, result2);
+      return result2;
+    }
     const sourceMap = new import_js_yaml_source_map.default();
     const data = import_js_yaml.default.load(content, { listener: sourceMap.listen() });
     const result = { data, sourceMap };
@@ -292,6 +346,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 +1184,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;
@@ -1134,7 +1261,7 @@ function truncate(str, max) {
 }
 function formatValue(val) {
   if (val === null || val === void 0) return "";
-  if (typeof val === "object") return JSON.stringify(val) ?? "";
+  if (typeof val === "object") return JSON.stringify(val);
   if (typeof val === "string") return val;
   return `${val}`;
 }
@@ -1183,7 +1310,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 +1433,6 @@ var index_default = option;
   ConfigLoadError,
   ConfigNode,
   ConfigNodeArray,
+  maskSecrets,
   printConfig
 });

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@meltstudio/config-loader",
-  "version": "3.4.0",
-  "description": "Type-safe configuration loader with full TypeScript inference. Load from YAML, JSON, .env, environment variables, and CLI args.",
+  "version": "3.6.0",
+  "description": "Type-safe configuration loader with full TypeScript inference. Load from YAML, JSON, TOML, .env, environment variables, and CLI args.",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "repository": "https://github.com/MeltStudio/config-loader",
@@ -15,6 +15,7 @@
     "config",
     "yaml",
     "json",
+    "toml",
     "loader",
     "env",
     "environment",
@@ -48,6 +49,7 @@
     "commander": "^14.0.0",
     "js-yaml": "^4.1.0",
     "js-yaml-source-map": "^0.2.2",
+    "smol-toml": "^1.6.0",
     "tslib": "^2.3.0"
   },
   "devDependencies": {