@meltstudio/config-loader 3.5.0 → 3.7.0

package/README.md

@@ -1,8 +1,8 @@
 # @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`.
+> **Upgrading from v1?** v1.x is deprecated and no longer maintained. Install the latest version with `npm install @meltstudio/config-loader@latest` or `yarn add @meltstudio/config-loader@latest`.
 
 **[Full documentation](https://meltstudio.github.io/config-loader/)**
 
@@ -16,47 +16,34 @@ 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
@@ -67,10 +54,7 @@ No separate interface to maintain. No `as` casts. The types flow from the schema
 - **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
+- **File watching** — `watch()` reloads config on file changes with debouncing, change detection, and error recovery
 
 ## Installation
 
@@ -82,753 +66,28 @@ 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.
-
-## 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.
-
-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:
+Requires Node.js >= 20.
 
-- `printConfig(result, { silent: true })` — returns the string without printing to console
-- `printConfig(result, { maxValueLength: 30 })` — truncate long values (default: 50)
+## Documentation
 
-## Error Handling
+See the **[full documentation](https://meltstudio.github.io/config-loader/)** for:
 
-When validation fails, config-loader throws a `ConfigLoadError` with structured error details:
+- [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()`, `watch()`, 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
 
-```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.
-    }
-  }
-}
-```
+## Examples
 
-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,
-})
-```
+The [`example/`](./example) directory contains runnable examples:
 
-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
-  maskSecrets, // Create a safe-to-log copy with sensitive values masked
-  printConfig, // Format loadExtended() result as a readable table
-} 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 }),
-});
-```
+- **[Basic](./example/basic)** — Schema definition, YAML file loading, nested objects and arrays, CLI arguments
+- **[Advanced](./example/advanced)** — TOML config, `.env` files, `oneOf` constraints, `sensitive` fields, validation, `printConfig()`, `maskSecrets()`, error handling
 
 ```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
-
-### 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
-  }
-}
+yarn example:basic
+yarn example:advanced
 ```
 
-### 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
-  }
-}
-```
-
-### Using `required: true` on nested fields without the parent object
-
-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.
-
 ## Documentation for AI Agents
 
 This project provides machine-readable documentation for AI coding agents at the docs site:
@@ -840,4 +99,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

@@ -207,6 +207,40 @@ declare class ObjectOption<T extends Node = Node> extends OptionBase<"object"> {
 
 type OptionTypes = PrimitiveOption | ArrayOption<OptionTypes> | ObjectOption<Node>;
 
+/** A single change detected between two config loads. */
+interface ConfigChange {
+    /** Dot-separated path to the changed key (e.g. "db.url"). */
+    path: string;
+    /** The previous value (undefined if key was added). */
+    oldValue: unknown;
+    /** The new value (undefined if key was removed). */
+    newValue: unknown;
+    /** Whether the change was an addition, removal, or modification. */
+    type: "added" | "removed" | "changed";
+}
+/**
+ * Compares two plain config objects and returns a list of changes.
+ * Sensitive fields (from the schema) are masked in the output.
+ */
+declare function diffConfig(oldConfig: Record<string, unknown>, newConfig: Record<string, unknown>, schema?: Node): ConfigChange[];
+
+/** Options for the `watch()` method. */
+interface WatchOptions<T> {
+    /** Called after a successful reload with the new config, old config, and list of changes. */
+    onChange: (newConfig: T, oldConfig: T, changes: ConfigChange[]) => void;
+    /** Called when a reload fails (parse error, validation error). The previous config is retained. */
+    onError?: (error: Error) => void;
+    /** Debounce interval in milliseconds. Default: 100. */
+    debounce?: number;
+}
+/** Handle returned by `watch()`. Provides access to the current config and a `close()` method. */
+interface ConfigWatcher<T> {
+    /** The current resolved configuration. Updated on each successful reload. */
+    readonly config: T;
+    /** Stop watching all files. Idempotent. */
+    close(): void;
+}
+
 /** Fluent builder that takes a schema and resolves configuration from multiple sources. */
 declare class SettingsBuilder<T extends Node> {
     private readonly schema;
@@ -225,6 +259,15 @@ declare class SettingsBuilder<T extends Node> {
      * @throws {ConfigLoadError} If validation fails.
      */
     loadExtended(sources: SettingsSources<SchemaValue<T>>): ExtendedResult;
+    /**
+     * Watches config files for changes and reloads automatically.
+     * File watchers are `.unref()`'d so they don't prevent the process from exiting.
+     * @param sources - Which sources to read (env, args, files, etc.).
+     * @param options - Callbacks and debounce configuration.
+     * @returns A `ConfigWatcher` with the current config and a `close()` method.
+     * @throws {ConfigLoadError} If the initial load fails.
+     */
+    watch(sources: SettingsSources<SchemaValue<T>>, options: WatchOptions<SchemaValue<T>>): ConfigWatcher<SchemaValue<T>>;
 }
 
 /**
@@ -363,4 +406,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, maskSecrets, printConfig };
+export { type ConfigChange, type ConfigErrorEntry, ConfigFileError, ConfigLoadError, ConfigNode, ConfigNodeArray, type ConfigWatcher, type ExtendedResult, type NodeTree, type RecursivePartial, type SchemaValue, type SettingsSources, type StandardSchemaV1, type WatchOptions, option as default, diffConfig, maskSecrets, printConfig };

package/dist/index.js

@@ -35,6 +35,7 @@ __export(index_exports, {
   ConfigNode: () => configNode_default,
   ConfigNodeArray: () => configNodeArray_default,
   default: () => index_default,
+  diffConfig: () => diffConfig,
   maskSecrets: () => maskSecrets,
   printConfig: () => printConfig
 });
@@ -126,6 +127,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();
@@ -188,6 +190,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;
@@ -202,6 +245,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 };
@@ -1102,6 +1154,176 @@ var Settings = class {
 };
 var settings_default = Settings;
 
+// src/watcher.ts
+var fs4 = __toESM(require("fs"));
+
+// src/diffConfig.ts
+var MASK = "***";
+function collectSensitivePaths(schema2, prefix = "") {
+  const paths = /* @__PURE__ */ new Set();
+  for (const key of Object.keys(schema2)) {
+    const opt = schema2[key];
+    const fullPath = prefix ? `${prefix}.${key}` : key;
+    if (opt instanceof PrimitiveOption && opt.params.sensitive) {
+      paths.add(fullPath);
+    }
+    if (opt instanceof ObjectOption) {
+      const childPaths = collectSensitivePaths(opt.item, fullPath);
+      for (const p of childPaths) {
+        paths.add(p);
+      }
+    }
+  }
+  return paths;
+}
+function diffObjects(oldObj, newObj, sensitivePaths, prefix = "") {
+  const changes = [];
+  const allKeys = /* @__PURE__ */ new Set([...Object.keys(oldObj), ...Object.keys(newObj)]);
+  for (const key of allKeys) {
+    const fullPath = prefix ? `${prefix}.${key}` : key;
+    const isSensitive = sensitivePaths.has(fullPath);
+    const oldVal = oldObj[key];
+    const newVal = newObj[key];
+    const hasOld = key in oldObj;
+    const hasNew = key in newObj;
+    if (hasNew && !hasOld) {
+      changes.push({
+        path: fullPath,
+        type: "added",
+        oldValue: void 0,
+        newValue: isSensitive ? MASK : newVal
+      });
+    } else if (hasOld && !hasNew) {
+      changes.push({
+        path: fullPath,
+        type: "removed",
+        oldValue: isSensitive ? MASK : oldVal,
+        newValue: void 0
+      });
+    } else if (oldVal !== null && newVal !== null && typeof oldVal === "object" && typeof newVal === "object" && !Array.isArray(oldVal) && !Array.isArray(newVal)) {
+      changes.push(
+        ...diffObjects(
+          oldVal,
+          newVal,
+          sensitivePaths,
+          fullPath
+        )
+      );
+    } else if (!Object.is(oldVal, newVal)) {
+      if (Array.isArray(oldVal) && Array.isArray(newVal) && JSON.stringify(oldVal) === JSON.stringify(newVal)) {
+        continue;
+      }
+      changes.push({
+        path: fullPath,
+        type: "changed",
+        oldValue: isSensitive ? MASK : oldVal,
+        newValue: isSensitive ? MASK : newVal
+      });
+    }
+  }
+  return changes;
+}
+function diffConfig(oldConfig, newConfig, schema2) {
+  const sensitivePaths = schema2 ? collectSensitivePaths(schema2) : /* @__PURE__ */ new Set();
+  return diffObjects(oldConfig, newConfig, sensitivePaths);
+}
+
+// src/watcher.ts
+function resolveFilePaths(sources) {
+  const paths = [];
+  const configFiles = validateFiles(
+    sources.files ?? false,
+    sources.dir ?? false
+  );
+  if (Array.isArray(configFiles)) {
+    paths.push(...configFiles);
+  } else if (configFiles) {
+    paths.push(configFiles);
+  }
+  if (sources.envFile) {
+    const envFiles = Array.isArray(sources.envFile) ? sources.envFile : [sources.envFile];
+    paths.push(...envFiles);
+  }
+  return paths;
+}
+function createWatcher(schema2, sources, options) {
+  const debounceMs = options.debounce ?? 100;
+  const initialSettings = new settings_default(schema2, sources);
+  let currentConfig = initialSettings.get();
+  const filePaths = resolveFilePaths(sources);
+  const watchers = [];
+  let debounceTimer = null;
+  let closed = false;
+  function reload() {
+    if (closed) return;
+    try {
+      clearFileCache();
+      const settings = new settings_default(schema2, sources);
+      const newConfig = settings.get();
+      const changes = diffConfig(
+        currentConfig,
+        newConfig,
+        schema2
+      );
+      if (changes.length > 0) {
+        const oldConfig = currentConfig;
+        currentConfig = newConfig;
+        options.onChange(newConfig, oldConfig, changes);
+      }
+    } catch (err) {
+      if (options.onError) {
+        options.onError(err instanceof Error ? err : new Error(String(err)));
+      }
+    }
+  }
+  function scheduleReload() {
+    if (closed) return;
+    if (debounceTimer) {
+      clearTimeout(debounceTimer);
+    }
+    debounceTimer = setTimeout(reload, debounceMs);
+    debounceTimer.unref();
+  }
+  for (const filePath of filePaths) {
+    try {
+      const watcher = fs4.watch(filePath, () => {
+        scheduleReload();
+      });
+      watcher.unref();
+      watchers.push(watcher);
+    } catch {
+    }
+  }
+  if (sources.dir && typeof sources.dir === "string") {
+    try {
+      const dirWatcher = fs4.watch(sources.dir, () => {
+        scheduleReload();
+      });
+      dirWatcher.unref();
+      watchers.push(dirWatcher);
+    } catch {
+    }
+  }
+  function close() {
+    if (closed) return;
+    closed = true;
+    if (debounceTimer) {
+      clearTimeout(debounceTimer);
+      debounceTimer = null;
+    }
+    for (const watcher of watchers) {
+      watcher.close();
+    }
+    watchers.length = 0;
+  }
+  return {
+    get config() {
+      return currentConfig;
+    },
+    close
+  };
+}
+
 // src/builder/settings.ts
 var SettingsBuilder = class {
   schema;
@@ -1131,17 +1353,28 @@ var SettingsBuilder = class {
       warnings: settings.getWarnings()
     };
   }
+  /**
+   * Watches config files for changes and reloads automatically.
+   * File watchers are `.unref()`'d so they don't prevent the process from exiting.
+   * @param sources - Which sources to read (env, args, files, etc.).
+   * @param options - Callbacks and debounce configuration.
+   * @returns A `ConfigWatcher` with the current config and a `close()` method.
+   * @throws {ConfigLoadError} If the initial load fails.
+   */
+  watch(sources, options) {
+    return createWatcher(this.schema, sources, options);
+  }
 };
 
 // src/maskSecrets.ts
-var MASK = "***";
+var MASK2 = "***";
 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,
+          MASK2,
           entry.path,
           entry.sourceType,
           entry.file,
@@ -1182,7 +1415,7 @@ function maskPlainObject(obj, schema2) {
         result[key] = value;
       }
     } else if (schemaNode instanceof OptionBase) {
-      result[key] = schemaNode.params.sensitive ? MASK : value;
+      result[key] = schemaNode.params.sensitive ? MASK2 : value;
     } else {
       result[key] = value;
     }
@@ -1210,7 +1443,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}`;
 }
@@ -1382,6 +1615,7 @@ var index_default = option;
   ConfigLoadError,
   ConfigNode,
   ConfigNodeArray,
+  diffConfig,
   maskSecrets,
   printConfig
 });

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@meltstudio/config-loader",
-  "version": "3.5.0",
-  "description": "Type-safe configuration loader with full TypeScript inference. Load from YAML, JSON, .env, environment variables, and CLI args.",
+  "version": "3.7.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",
@@ -38,7 +39,8 @@
     "type-check": "tsc --noEmit",
     "test": "jest --verbose",
     "replace-tspaths": "./scripts/replace-tspaths/index.mjs",
-    "example:run": "ts-node -r tsconfig-paths/register ./example/index.ts",
+    "example:basic": "ts-node -r tsconfig-paths/register ./example/basic/index.ts",
+    "example:advanced": "ts-node -r tsconfig-paths/register ./example/advanced/index.ts",
     "prepare": "husky",
     "docs:build": "docusaurus build && node scripts/fix-llms-urls.mjs",
     "docs:serve": "docusaurus serve",
@@ -48,6 +50,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": {