@meltstudio/config-loader 1.1.0 → 2.0.0

package/README.md

@@ -1,101 +1,88 @@
 # @meltstudio/config-loader
 
-> ⚠️ **WARNING**: This project is in beta, so some features may change in the future. Use at your own discretion
+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.
 
-## Project Description
+## Why config-loader?
 
-The Config Loader package is a powerful and user-friendly tool that simplifies the process of retrieving and collecting variables from one or multiple files for your project. It provides an efficient way to extract specific information from files and access those variables in your code. The result is a JSON object, making it easy to work with in various applications.
+Most config libraries give you `Record<string, unknown>` and leave you to cast or validate manually. config-loader infers TypeScript types directly from your schema definition:
 
-## Features
+```typescript
+import c from "@meltstudio/config-loader";
 
-- Retrieve and collect variables from one or multiple files in your project.
-- YAML file support (support for other file types coming soon.)
-- Data can also be retrieved from CLI or environment variables .
-- Compatible with TypeScript/JavaScript environments, making it suitable for Node.js projects.
+const config = c
+  .schema({
+    port: c.number({ required: true, env: "PORT" }),
+    database: c.object({
+      item: {
+        host: c.string({ required: true }),
+        credentials: c.object({
+          item: {
+            username: c.string(),
+            password: c.string({ env: "DB_PASSWORD" }),
+          },
+        }),
+      },
+    }),
+    features: c.array({
+      required: true,
+      item: c.object({
+        item: {
+          name: c.string(),
+          enabled: c.bool(),
+        },
+      }),
+    }),
+  })
+  .load({
+    env: true,
+    args: true,
+    files: "./config.yaml",
+  });
 
-## Table of Contents
+// config is fully typed:
+// {
+//   port: number;
+//   database: { host: string; credentials: { username: string; password: string } };
+//   features: { name: string; enabled: boolean }[];
+// }
+```
 
-- [Installation](#installation)
-- [Usage](#usage)
-- [License](#license)
-- [Acknowledgements](#acknowledgements)
+No separate interface to maintain. No `as` casts. The types flow from the schema.
 
-## Installation
+## Features
 
-To install the project, you can use the following steps:
+- **Full type inference** — schema definition produces typed output automatically
+- **Multiple sources** — YAML files, JSON 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 instead of `process.exit(1)`
+- **Default values** — static or computed (via functions)
+- **Multiple files / directory loading** — load from a list of files or an entire directory
 
-1. Ensure that you have [Node.js](https://nodejs.org/) installed on your machine.
-2. Open a terminal or command prompt.
-3. Run the following command to install the project and its dependencies via npm:
+## Requirements
+
+- Node.js >= 20
+
+## Installation
 
 ```bash
-$ npm install @meltstudio/config-loader
+npm install @meltstudio/config-loader
 ```
 
 ```bash
-$ yarn add @meltstudio/config-loader
+yarn add @meltstudio/config-loader
 ```
 
-## Usage
-
-Here's an example of how to use the `@meltstudio/config-loader` package in a TypeScript project:
-
-```typescript
-import path from "path";
+## Quick Start
 
-import c from "@meltstudio/config-loader";
-
-const run = (): void => {
-  const settings = c.schema({
-    version: c.string({ required: true, cli: true }),
-    website: {
-      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: {
-      host: c.string({ required: true }),
-      port: c.number({ required: true }),
-      credentials: {
-        username: c.string(),
-        password: c.string(),
-      },
-    },
-    socialMedia: c.array({
-      required: true,
-      item: c.string({ required: true }),
-    }),
-    features: c.array({
-      required: true,
-      item: {
-        name: c.string(),
-        enabled: c.bool(),
-      },
-    }),
-  });
-  const config = settings.load({
-    env: false,
-    args: true,
-    files: path.join(__dirname, "./config.yaml"),
-  });
-  console.log(JSON.stringify(config, null, 2));
-};
-
-run();
-```
-
-With a config.yaml file with the following contents:
+**config.yaml:**
 
 ```yaml
 version: 1.0.0
 website:
   title: My Website
   description: A simple and elegant website
-  port: 3000
   isProduction: false
 
 database:
@@ -112,13 +99,64 @@ features:
     enabled: true
   - name: Admin
     enabled: false
+```
+
+**index.ts:**
+
+```typescript
+import path from "path";
+import c from "@meltstudio/config-loader";
 
-apiKeys:
-  googleMaps: ${GOOGLE_MAPS_API_KEY}
-  sendGrid: ${SENDGRID_API_KEY}
+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));
 ```
 
-The expected output would be:
+Output:
 
 ```json
 {
@@ -142,140 +180,239 @@ The expected output would be:
     "https://instagram.com/example"
   ],
   "features": [
-    {
-      "name": "Store",
-      "enabled": true
-    },
-    {
-      "name": "Admin",
-      "enabled": false
-    }
+    { "name": "Store", "enabled": true },
+    { "name": "Admin", "enabled": false }
   ]
 }
 ```
 
-You can try executing our example in your project by following these steps with the command:
+## Schema API
 
-```bash
-yarn example:run
+### 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 });
 ```
 
-### Usage with CLI
+### Objects
 
-When using our package with cli, it is important to have the cli attribute set to true.
-This will allow values to be sent when running the package from the command line.
+Use `c.object()` to declare nested object schemas:
 
 ```typescript
-import path from "path";
+c.object({
+  item: {
+    host: c.string(),
+    port: c.number(),
+  },
+});
+```
 
-import c from "@meltstudio/config-loader";
+Objects can be nested arbitrarily deep:
 
-const run = (): void => {
-  const settings = c.schema({
-    version: c.string({
-      required: true,
-      cli: true, 👈
-    }),
-  });
-  const config = settings.load({
-    env: false,
-    args: true,
-    files: path.join(__dirname, "./config.yaml"),
-  });
-  console.log(JSON.stringify(config, null, 2));
-};
+```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
 
-run();
+```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 }[]
 ```
 
-To use it you need to send the property name on the command line with the new value
+## Loading Sources
 
-```bash
-yarn example:run --version 2.0.0
+```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
+})
 ```
 
-Having the following config.yaml file:
+Both YAML (`.yaml`, `.yml`) and JSON (`.json`) files are supported. The format is detected automatically from the file extension.
 
-```yaml
-version: 1.0.0
+**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 extended = c
+  .schema({
+    port: c.number({ required: true, env: "PORT" }),
+    host: c.string({ defaultValue: "localhost" }),
+  })
+  .loadExtended({
+    env: true,
+    args: false,
+    files: "./config.yaml",
+  });
+
+// Each leaf 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(extended.port.value); // 3000
+console.log(extended.port.sourceType); // "env"
+console.log(extended.port.variableName); // "PORT"
 ```
 
-The expected output would be:
+This is useful for debugging configuration resolution, building admin UIs that show where each setting originated, or auditing which sources are active.
 
-```json
-{
-  "version": "2.0.0"
+## 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.
+    }
+  }
 }
 ```
 
-You can see that the CLI variable overrode the yaml file variable
+For CLI tools that prefer the old exit-on-error behavior:
 
-### Usage with Environment Variables
+```typescript
+.load({ env: true, args: true, files: "./config.yaml", exitOnError: true })
+```
+
+## CLI Arguments
 
-The Config Loader package allows you to use environment variables in your system configuration. You can specify variable names in your configuration and get them. To use this feature you need to set **env: true**
+Set `cli: true` on an option to allow overriding via command line:
 
 ```typescript
-import path from "path";
+c.schema({
+  version: c.string({ required: true, cli: true }),
+});
+```
 
-import c from "@meltstudio/config-loader";
+```bash
+node app.js --version 2.0.0
+```
 
-const run = (): void => {
-  const settings = c.schema({
-    database: {
-      host: c.string({ required: true }),
-      port: c.number({ required: true }),
-      credentials: {
-        username: c.string(),
-        password: c.string({
-          env: "DB_PASSWORD",
-          cli: true,
-        }),
-      },
-    },
-  });
-  const config = settings.load({
-    env: true, 👈
-    args: true,
-    files: path.join(__dirname, "./config.yaml"),
-  });
-  console.log(JSON.stringify(config, null, 2));
-};
+## Environment Variables
+
+Set `env: "VAR_NAME"` on an option and `env: true` in the load options:
 
-run();
+```typescript
+c.schema({
+  database: c.object({
+    item: {
+      password: c.string({ env: "DB_PASSWORD" }),
+    },
+  }),
+}).load({ env: true, args: false, files: "./config.yaml" });
 ```
 
-With the following config.yaml file:
+## `.env` File Support
 
-```yaml
-database:
-  host: localhost
-  port: 5432
-  credentials:
-    username: admin
-    password: IGNORED_PASSWORD
-```
+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
-yarn example:run
+DB_HOST=localhost
+DB_PORT=5432
+DB_PASSWORD="s3cret"
+APP_NAME='My App'
+# This is a comment
 ```
 
-If you have the environment variable `DB_PASSWORD=ENV_USED_PASSWORD`, the expected output would be:
+**Usage:**
 
-```json
-{
-  "database": {
-    "host": "localhost",
-    "port": 5432,
-    "credentials": {
-      "username": "admin",
-      "password": "ENV_USED_PASSWORD"
-    }
-  }
-}
+```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
+})
 ```
 
-You can notice that the environment variable overrode the value in the config.yaml file
+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.
 
 ## License
 
-This package is licensed under the Apache License 2.0. For more information, please see the [LICENSE](./LICENSE) file.
+This package is licensed under the Apache License 2.0. See the [LICENSE](./LICENSE) file for details.