npm package: @glorhythm/config-loader
Description: Glorhythm config loader library
Author: glorhythm
Latest version: 1.0.0-beta.13

# @glorhythm/config-loader

A lightweight and strongly-typed configuration loader for Node.js projects.  
It automatically loads environment variables from `.env`, collects configuration files from the `configs/` directory, and provides **type-safe access** to nested configuration values at runtime.

---

## ✨ Features

- 📦 Auto-load `.env` and `configs/` files
- 🔍 Type-safe config access
- 🧩 Automatic `ConfigData` interface generation (via [`@glorhythm/type-gen`](https://www.npmjs.com/package/@glorhythm/type-gen))
- 📁 Works seamlessly with both JavaScript and TypeScript
- ⚙️ No boilerplate — just `ConfigLoader.load()` and go

---

## 📦 Installation

```bash
npm install @glorhythm/config-loader
# or
yarn add @glorhythm/config-loader
```

---

## 📁 Project Structure

Your project should have a `configs` directory and a `.env` file:

```
project/
├─ src/
│  ├─ configs/
|  │  ├─ app.ts
|  │  ├─ database.ts
|  │  └─ redis.ts
│  └─ index.ts
├─ .env
└─ package.json
```

- `.env` – stores environment variables (e.g., `APP_PORT=3000`)
- `configs/` – each file exports an object with configuration for a specific module

---

## 🚀 Usage

### 1. Load environment and config files

```ts
import { ConfigLoader } from "@glorhythm/config-loader";

ConfigLoader.load(); // Loads .env + configs/*.ts
```

This will:

- Parse `.env`
- Load all config files from `configs/`
- Merge them into a single `ConfigData` object
- Automatically generate a `ConfigData` interface in development mode

---

### 2. Access configuration values (type-safe)

Use the `Config` helper to access deeply nested values **with autocompletion and type safety**:

```ts
import Config from "@glorhythm/config-loader";

const port = Config("app.port"); // ✅ inferred as number
const redisHost = Config("redis.host"); // ✅ inferred as string

console.log(`Server running on port ${port}`);
```

If the path doesn’t exist, `Config()` will return `null`.

---

### 3. Direct API via `ConfigLoader.get()`

If you prefer, you can directly call:

```ts
import { ConfigLoader } from "@glorhythm/config-loader";

const dbName = ConfigLoader.get("database.name");
```

---

## 🧠 Types & Utilities

The library ships with two powerful utility types for type-safe key access:

- **`DotPath<T>`** – Generates all possible dot-notation paths from a nested object
- **`PathValue<T, P>`** – Resolves the type of a nested path

Example:

```ts
type Path = DotPath<ConfigData>;
// "app.port" | "app.env" | "redis.host" | "redis.port" | ...

type Value = PathValue<ConfigData, "redis.host">;
// string
```

---

## ⚙️ Configuration File Example

```ts
// configs/app.ts
export default {
  name: "MyApp",
  env: "development",
  port: 3000,
};
```

```ts
// configs/redis.ts
export default {
  host: "127.0.0.1",
  port: 6379,
};
```

---

## 🛠️ API Reference

### `ConfigLoader.load()`

Loads `.env`, parses all config files, and initializes the internal configuration map.

### `ConfigLoader.get(path: DotPath<ConfigData>): PathValue<ConfigData, P> | null`

Fetch a nested config value with type inference.

### `Config<P>(path: P): PathValue<ConfigData, P> | null`

Shortcut for `ConfigLoader.get()`.

---

## 🧪 Auto Type Generation

When `NODE_ENV` ≠ `production`, the loader uses [`@glorhythm/type-gen`](https://www.npmjs.com/package/@glorhythm/type-gen) to generate a `ConfigData` interface from your runtime configuration.  
This ensures your TypeScript types always stay in sync with the actual config structure — **no manual typing required.**

---

## 📜 License

MIT © glorhythm

---

## 🤝 Contributing

Contributions, issues, and feature requests are welcome!  
Feel free to open a PR or start a discussion in the repository.

---

## 📬 Author

**glorhythm**  
Building powerful developer tooling — one library at a time 🚀