nestjs-env-getter 0.1.0 → 1.0.0-beta.2

package/CHANGELOG.md

@@ -0,0 +1,56 @@
+# Changelog
+
+<!-- markdownlint-disable MD024 -->
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0-beta.2] - 2025-10-17
+
+### Added
+
+- **Inject Custom Providers**: Added the ability to inject custom providers into `AppConfigModule` via `forRoot` and `forRootAsync`. This allows `AppConfig` classes to depend on other services for dynamic configuration.
+
+### Changed
+
+- **Updated Example**: The `nestjs-server` example was updated to demonstrate how to inject a custom `AppConfigOptionsService` to dynamically select configuration files based on the environment.
+
+## [1.0.0-beta.1] - 2025-10-08
+
+### Added
+
+- **Configuration from Files**:
+  - Added `getRequiredConfigFromFile` and `getOptionalConfigFromFile` to read, parse, and validate JSON configuration files.
+  - Implemented automatic file watching with hot-reload, which updates configuration in-place without requiring an application restart.
+  - Configuration objects are enhanced with `on`, `once`, and `off` methods for subscribing to file change events.
+- **Graceful Error Handling**:
+  - `getOptionalConfigFromFile` now gracefully handles missing files or JSON parsing errors by returning a default value or `undefined`, preventing process termination.
+  - Process now only terminates on critical errors, such as validation failures in class-based configs.
+- **Project Scaffolding and Examples**:
+  - Added an example NestJS application demonstrating usage with a MongoDB connection.
+  - Included executable scripts for bootstrapping the library.
+  - Integrated `AppConfigModule` to streamline configuration setup.
+
+### Changed
+
+- Updated all dependencies to their latest versions.
+
+## [0.1.0] - 2025-05-08
+
+### Changed
+
+- Bumped version.
+- Bumped development dependencies and changed the registry.
+
+### Fixed
+
+- Updated the GitHub Action for publishing.
+- Fixed issues in the CI/CD workflows.
+
+## [0.0.0-beta1] - 2025-02-04
+
+### Added
+
+- Initial release with total refactoring.

package/README.md

@@ -1,125 +1,401 @@
-# nestjs-env-getter
+# NestJS ENV Getter
 
-The `nestjs-env-getter` is a NestJS module designed to simplify the process of retrieving and validating environment variables in your application. It provides a robust and type-safe way to handle environment variables, ensuring that your application starts with the correct configuration.
+`nestjs-env-getter` is a powerful and lightweight NestJS module designed to streamline the process of retrieving and validating environment variables. It ensures your application starts with a correct and type-safe configuration by providing a robust API for handling various data types and validation scenarios.
 
-## Features
+## Key Features
 
-- **Type-safe environment variable retrieval**: Retrieve environment variables as strings, numbers, booleans, URLs, objects, arrays, or time periods.
-- **Validation**: Validate environment variables against allowed values or custom validation functions.
-- **Default values**: Provide default values for optional environment variables.
-- **Error handling**: Automatically terminates the process with a descriptive error message if required environment variables are missing or invalid.
+- **Type-Safe Retrieval**: Get environment variables as strings, numbers, booleans, URLs, objects, arrays, or time periods.
+- **Built-in Validation**: Validate variables against allowed values or use custom validation functions.
+- **Required vs. Optional**: Clearly distinguish between required variables that terminate the process if missing and optional ones with default values.
+- **Error Handling**: Automatically terminates the process with a descriptive error message if a required variable is missing or invalid.
+- **`.env` Support**: Automatically loads environment variables from a `.env` file using `dotenv`.
+- **Configuration Scaffolding**: Includes a CLI helper to quickly set up a centralized configuration file.
 
 ## Installation
 
-Install the package using npm:
-
 ```bash
 npm install nestjs-env-getter
 ```
 
-Or using yarn:
+## Quick Start
 
-```bash
-yarn add nestjs-env-getter
-```
+The recommended way to use `nestjs-env-getter` is by creating a centralized configuration service.
 
-## Usage
+### 1. Create a Configuration Service
 
-### Importing the Module
+Create a file `src/app.config.ts` to define and validate all your environment variables.
+
+```typescript
+// src/app.config.ts
+import { Injectable } from "@nestjs/common";
+import { EnvGetterService } from "nestjs-env-getter";
 
-To use the `EnvGetterService`, import the `EnvGetterModule` into your application's module:
+@Injectable()
+export class AppConfig {
+  readonly port: number;
+  readonly mongoConnectionString: string;
+  readonly nodeEnv: string;
+
+  constructor(private readonly envGetter: EnvGetterService) {
+    this.port = this.envGetter.getRequiredNumericEnv("PORT");
+    this.mongoConnectionString = this.envGetter.getRequiredEnv(
+      "MONGO_CONNECTION_STRING",
+    );
+    this.nodeEnv = this.envGetter.getRequiredEnv("NODE_ENV", [
+      "development",
+      "production",
+    ]);
+  }
+}
+```
+
+### 2. Register the Configuration
+
+In your `AppModule`, import `AppConfigModule` and provide your custom `AppConfig` class. This makes `AppConfig` a singleton provider available for dependency injection across your application.
 
 ```typescript
+// src/app.module.ts
 import { Module } from "@nestjs/common";
-import { EnvGetterModule } from "nestjs-env-getter";
-
-@Module({ imports: [EnvGetterModule] })
+import { AppConfigModule } from "nestjs-env-getter";
+import { AppConfig } from "./app.config";
+
+@Module({
+  imports: [
+    // Register the custom AppConfig class
+    AppConfigModule.forRoot({ useClass: AppConfig }),
+  ],
+})
 export class AppModule {}
 ```
 
-### Using the Service
+### 3. Use the Configuration
 
-Inject the `EnvGetterService` into your service or controller to retrieve environment variables:
+Now you can inject `AppConfig` anywhere in your application.
 
 ```typescript
 import { Injectable } from "@nestjs/common";
-import { EnvGetterService } from "nestjs-env-getter";
+import { AppConfig } from "./app.config";
 
 @Injectable()
-export class AppService {
-  constructor(private readonly envGetter: EnvGetterService) {
-    const port = this.envGetter.getRequiredNumericEnv("PORT");
-    console.log(`Application will run on port: ${port}`);
+export class DatabaseService {
+  private readonly connectionString: string;
+
+  constructor(private readonly config: AppConfig) {
+    this.connectionString = config.mongoConnectionString;
+    // Use the connection string...
   }
 }
 ```
 
-### Examples
+This approach centralizes your environment variable management, making your application cleaner and easier to maintain.
 
-#### Retrieving Required Environment Variables
+## CLI Helper
 
-```typescript
-const dbHost = this.envGetter.getRequiredEnv("DB_HOST");
+You can scaffold the configuration file and module setup automatically with the built-in CLI command. Run this in the root of your NestJS project:
+
+```bash
+npx nestjs-env-getter init
 ```
 
-#### Retrieving Optional Environment Variables with Default Values
+This command (shorthand `npx nestjs-env-getter i`) will:
 
-```typescript
-const logLevel = this.envGetter.getOptionalEnv("LOG_LEVEL", "info");
-```
+1. Create `src/app.config.ts` from a template.
+2. Import `AppConfigModule.forRoot({ useClass: AppConfig })` into your `src/app.module.ts`.
 
-#### Validating Environment Variables Against Allowed Values
+## API Reference (`EnvGetterService`)
 
-```typescript
-const environment = this.envGetter.getRequiredEnv("NODE_ENV", [
-  "development",
-  "production",
-  "test",
-]);
-```
+Here are detailed examples of the methods available in `EnvGetterService`.
 
-#### Parsing Numeric Environment Variables
+### String
 
-```typescript
-const timeout = this.envGetter.getRequiredNumericEnv("TIMEOUT");
-```
+- **`getRequiredEnv(name: string, allowed?: string[]): string`**
 
-#### Parsing Boolean Environment Variables
+  ```typescript
+  // Throws an error if DB_HOST is not set
+  const dbHost = this.envGetter.getRequiredEnv("DB_HOST");
 
-```typescript
-const isDebugMode = this.envGetter.getRequiredBooleanEnv("DEBUG_MODE");
-```
+  // Throws an error if NODE_ENV is not 'development' or 'production'
+  const nodeEnv = this.envGetter.getRequiredEnv("NODE_ENV", [
+    "development",
+    "production",
+  ]);
+  ```
 
-#### Parsing URLs
+- **`getOptionalEnv(name: string, default?: string, allowed?: string[]): string | undefined`**
 
-```typescript
-const apiUrl = this.envGetter.getRequiredURL("API_URL");
-```
+  ```typescript
+  // Returns 'info' if LOG_LEVEL is not set
+  const logLevel = this.envGetter.getOptionalEnv("LOG_LEVEL", "info");
+  ```
 
-#### Parsing Time Periods
+### Number
 
-```typescript
-const cacheDuration = this.envGetter.getRequiredTimePeriod(
-  "CACHE_DURATION",
-  "s",
-);
-```
+- **`getRequiredNumericEnv(name: string): number`**
+
+  ```typescript
+  // Throws an error if PORT is not a valid number
+  const port = this.envGetter.getRequiredNumericEnv("PORT");
+  ```
+
+- **`getOptionalNumericEnv(name: string, default?: number): number | undefined`**
+
+  ```typescript
+  // Returns 3000 if TIMEOUT is not set or not a valid number
+  const timeout = this.envGetter.getOptionalNumericEnv("TIMEOUT", 3000);
+  ```
+
+### Boolean
+
+- **`getRequiredBooleanEnv(name: string): boolean`**
+
+  ```typescript
+  // Throws an error if DEBUG_MODE is not 'true' or 'false'
+  const isDebug = this.envGetter.getRequiredBooleanEnv("DEBUG_MODE");
+  ```
+
+- **`getOptionalBooleanEnv(name: string, default?: boolean): boolean | undefined`**
+
+  ```typescript
+  // Returns false if ENABLE_SSL is not set
+  const useSsl = this.envGetter.getOptionalBooleanEnv("ENABLE_SSL", false);
+  ```
+
+### URL
+
+- **`getRequiredURL(name: string): URL`**
+
+  ```typescript
+  // Throws an error if API_URL is not a valid URL
+  const apiUrl = this.envGetter.getRequiredURL("API_URL");
+  ```
+
+- **`getOptionalURL(name: string, default?: URL): URL | undefined`**
 
-#### Parsing JSON Objects
+  ```typescript
+  const defaultUrl = new URL("https://fallback.example.com");
+  // Returns defaultUrl if CDN_URL is not set or not a valid URL
+  const cdnUrl = this.envGetter.getOptionalURL("CDN_URL", defaultUrl);
+  ```
+
+### Time Period
+
+Parses a string like `'10s'`, `'5m'`, `'2h'`, `'1d'` into a numeric value.
+
+- **`getRequiredTimePeriod(name: string, resultIn: 'ms' | 's' | 'm' | 'h' | 'd' = 'ms'): number`**
+
+  ```typescript
+  // Parses '30s' into 30000
+  const cacheTtl = this.envGetter.getRequiredTimePeriod("CACHE_TTL");
+
+  // Parses '2h' into 2
+  const sessionHours = this.envGetter.getRequiredTimePeriod(
+    "SESSION_DURATION",
+    "h",
+  );
+  ```
+
+- **`getOptionalTimePeriod(name: string, default: string, resultIn: ...): number`**
+
+  ```typescript
+  // Returns 60 (seconds) if JWT_EXPIRES_IN is not set
+  const expiresIn = this.envGetter.getOptionalTimePeriod(
+    "JWT_EXPIRES_IN",
+    "1m",
+    "s",
+  );
+  ```
+
+### Object (from JSON string)
+
+- **`getRequiredObject<T>(name: string, cls?: ClassConstructor<T>): T`**
+
+  ```typescript
+  // ENV: '{"user": "admin", "port": 5432}'
+  const dbConfig = this.envGetter.getRequiredObject<{
+    user: string;
+    port: number;
+  }>("DB_CONFIG");
+  console.log(dbConfig.port); // 5432
+  ```
+
+### Array (from JSON string)
+
+- **`getRequiredArray<T>(name: string, validate?: (el: T) => boolean | string): T[]`**
+
+  ```typescript
+  // ENV: '["192.168.1.1", "10.0.0.1"]'
+  const allowedIPs = this.envGetter.getRequiredArray<string>("ALLOWED_IPS");
+
+  // With validation
+  const servicePorts = this.envGetter.getRequiredArray<number>(
+    "SERVICE_PORTS",
+    (port) => {
+      if (typeof port !== "number" || port < 1024) {
+        return `Port ${port} is invalid. Must be a number >= 1024.`;
+      }
+      return true;
+    },
+  );
+  ```
+
+### Configuration from JSON Files
+
+Load and validate configuration from JSON files with automatic file watching and hot-reload support.
+
+- **`getRequiredConfigFromFile<T>(filePath: string, cls?: ClassConstructor<T>, watcherOptions?: FileWatcherOptions): T`**
+
+  Reads a required JSON configuration file. Automatically watches for file changes and updates the cached config.
+
+  ```typescript
+  // With class validation
+  class MongoCredentials {
+    connectionString: string;
+
+    constructor(data: any) {
+      if (!data.connectionString) {
+        throw new Error("connectionString is required");
+      }
+      this.connectionString = data.connectionString;
+    }
+  }
+
+  const mongoCreds = this.envGetter.getRequiredConfigFromFile(
+    "configs/mongo-creds.json",
+    MongoCredentials,
+  );
+  console.log(mongoCreds.connectionString);
+
+  // Disable file watching
+  const staticConfig = this.envGetter.getRequiredConfigFromFile(
+    "config.json",
+    undefined,
+    { enabled: false },
+  );
+
+  // Custom debounce timing (default is 200ms)
+  const config = this.envGetter.getRequiredConfigFromFile(
+    "config.json",
+    undefined,
+    { debounceMs: 1000 },
+  );
+  ```
+
+- **`getOptionalConfigFromFile<T>(filePath: string, defaultValue?: T, cls?: ClassConstructor<T>, watcherOptions?: FileWatcherOptions): T | undefined`**
+
+  Reads an optional JSON configuration file. Returns the default value if the file doesn't exist or cannot be parsed as JSON. Only terminates the process if validation fails (when using a class constructor).
+
+  ```typescript
+  // With class validation
+  class TestConfig {
+    testConfigStringFromFile: string;
+
+    constructor(data: any) {
+      if (!data.testConfigStringFromFile) {
+        throw new Error("testConfigStringFromFile is required");
+      }
+      this.testConfigStringFromFile = data.testConfigStringFromFile;
+    }
+  }
+
+  const testConfig = this.envGetter.getOptionalConfigFromFile(
+    "configs/test-configs.json",
+    TestConfig,
+  );
+
+  // With default value - gracefully handles missing files and JSON parsing errors
+  const config = this.envGetter.getOptionalConfigFromFile(
+    "optional-config.json",
+    { fallbackValue: "default" },
+  );
+
+  // Note: Optional config files are graceful - missing files or JSON parsing errors
+  // return the default value (or undefined). Only validation errors crash the process.
+  ```
+
+#### ⚠️ Important: Error Handling Behavior
+
+**Required vs Optional Config Files:**
+
+- **`getRequiredConfigFromFile`**: Crashes the process if the file is missing, has invalid JSON, or fails validation.
+- **`getOptionalConfigFromFile`**: Only crashes the process on validation errors (when using class constructors). Missing files or JSON parsing errors gracefully return the default value or `undefined`.
+
+This design ensures that optional configurations truly are optional - your application won't crash due to missing or malformed optional config files, but validation constraints are still enforced when files are present and parsable.
+
+#### ⚠️ Important: Using Config Values by Reference
+
+To ensure your application automatically receives updated config values when files change, you **must store config objects by reference**, not by extracting primitive values:
 
 ```typescript
-const config = this.envGetter.getRequiredObject<{ key: string }>("CONFIG");
-```
+// ✅ CORRECT - Store the object reference
+@Injectable()
+export class AppConfig {
+  mongoConfigs: MongoCredentials; // Store the entire object
+  testConfig?: TestConfig; // Store the entire object
+
+  constructor(protected readonly envGetter: EnvGetterService) {
+    // Store references to config objects
+    this.mongoConfigs = this.envGetter.getRequiredConfigFromFile(
+      "configs/mongo-creds.json",
+      MongoCredentials,
+    );
+    this.testConfig = this.envGetter.getOptionalConfigFromFile(
+      "configs/test-configs.json",
+      TestConfig,
+    );
+  }
+}
 
-#### Parsing Arrays with Validation
+// Access via the reference - values will update automatically
+@Module({
+  imports: [
+    MongooseModule.forRootAsync({
+      useFactory: (config: AppConfig) => ({
+        uri: config.mongoConfigs.connectionString, // Access via reference
+      }),
+      inject: [AppConfig],
+    }),
+  ],
+})
+export class AppModule {}
+```
 
 ```typescript
-const allowedIPs = this.envGetter.getRequiredArray<string>(
-  "ALLOWED_IPS",
-  (ip) => ip.startsWith("192.") || "IP must start with 192.",
-);
+// ❌ WRONG - Extracting primitive values breaks hot-reload
+@Injectable()
+export class AppConfig {
+  mongoConnectionString: string; // Primitive value - won't update!
+
+  constructor(protected readonly envGetter: EnvGetterService) {
+    const mongoCreds = this.envGetter.getRequiredConfigFromFile(
+      "configs/mongo-creds.json",
+      MongoCredentials,
+    );
+    // This extracts the VALUE at startup time - it won't update!
+    this.mongoConnectionString = mongoCreds.connectionString;
+  }
+}
 ```
 
+When the file watcher detects changes, it updates the **same object instance** in memory. If you store the object reference, your application automatically sees the updated values. If you extract primitive values (strings, numbers, booleans), they become snapshots that never update.
+
+**File Watcher Options:**
+
+- `enabled` (boolean, default: `true`): Enable or disable automatic file watching
+- `debounceMs` (number, default: `200`): Delay in milliseconds before re-reading the file after a change
+
+**Features:**
+
+- ✅ Supports both absolute and relative paths (relative to `process.cwd()`)
+- ✅ Automatic JSON parsing and validation
+- ✅ **Hot-reload with reference preservation** - updates existing object instances in-place
+- ✅ File watching with automatic change detection
+- ✅ Debouncing to prevent excessive re-reads
+- ✅ Class-based validation with constructor pattern
+- ✅ **Graceful error handling for optional configs** - missing files or JSON parsing errors return default values
+- ✅ Process termination only on validation errors (required configs crash on any error)
+- ✅ **Event methods attached to default values** - consistent API even when files don't exist
+- ✅ No application restart needed - changes apply immediately when using object references
+
 ## License
 
 This project is licensed under the MIT License. See the [LICENSE](./LICENSE) file for details.