### Installation

Source: https://github.com/constantiner/resolve-node-configs-hierarchy/blob/master/README.md

Installs the resolve-node-configs-hierarchy library using npm.

```bash
npm install @constantiner/resolve-node-configs-hierarchy
```

--------------------------------

### Install via NPM

Source: https://github.com/constantiner/resolve-node-configs-hierarchy/blob/master/docs/installation.md

Installs the @constantiner/resolve-node-configs-hierarchy package using npm. This is the primary method for integrating the library into your Node.js project.

```bash
npm install @constantiner/resolve-node-configs-hierarchy
```

--------------------------------

### Configuration File Precedence (JSON Example)

Source: https://github.com/constantiner/resolve-node-configs-hierarchy/blob/master/docs/introduction.md

Illustrates the hierarchical loading order for configuration files with extensions, such as JSON. The example shows how environment-specific and local overrides are prioritized.

```APIDOC
resolve-node-configs-hierarchy JSON Precedence Order:

1. `settings.development.local.json` (highest priority)
2. `settings.local.json`
3. `settings.development.json`
4. `settings.json` (lowest priority)
```

--------------------------------

### Get All Config Files (Sync)

Source: https://github.com/constantiner/resolve-node-configs-hierarchy/blob/master/README.md

Imports and uses the synchronous `getConfigFilesSync` function to get an array of configuration file paths. It then iterates through the files and loads them using `dotenv.config`.

```JavaScript
import { getConfigFilesSync } from "@constantiner/resolve-node-configs-hierarchy";

getConfigFilesSync("src/.env").forEach(file => {
	dotenv.config({
		path: file
	})
});
```

--------------------------------

### Get All Config Files with Local Flag (Async)

Source: https://github.com/constantiner/resolve-node-configs-hierarchy/blob/master/README.md

Demonstrates using `getConfigFiles` with a boolean flag to include local files, typically for specific environments like 'test'. It loads the resolved files using `dotenv.config`.

```JavaScript
import { getConfigFiles } from "@constantiner/resolve-node-configs-hierarchy";

getConfigFiles("src/.env", true).then(files => {
	files.forEach(file => {
		dotenv.config({
			path: file
		})
	})
});
```

--------------------------------

### Get Single Config File with Local Flag (Async)

Source: https://github.com/constantiner/resolve-node-configs-hierarchy/blob/master/README.md

Shows how to use `getConfigFile` with a flag to include local files asynchronously. If a file path is returned, the configuration is loaded using `require`.

```JavaScript
import { getConfigFile } from "@constantiner/resolve-node-configs-hierarchy";

getConfigFile("src/.env", true).then(filePath => {
	if (filePath) {
		const config = require(filePath);
	}
});
```

--------------------------------

### Get All Config Files (Async)

Source: https://github.com/constantiner/resolve-node-configs-hierarchy/blob/master/README.md

Imports and uses the `getConfigFiles` function to retrieve an array of configuration file paths asynchronously. It then iterates through the files and loads them using `dotenv.config`.

```JavaScript
import { getConfigFiles } from "@constantiner/resolve-node-configs-hierarchy";

getConfigFiles("src/.env").then(files => {
	files.forEach(file => {
		dotenv.config({
			path: file
		})
	})
});
```

--------------------------------

### Get Single Config File (Sync)

Source: https://github.com/constantiner/resolve-node-configs-hierarchy/blob/master/README.md

Imports and uses the synchronous `getConfigFileSync` function to get the path of the single most actual configuration file. It loads the configuration using `require` if a file path is found.

```JavaScript
import { getConfigFileSync } from "@constantiner/resolve-node-configs-hierarchy";

const filePath = getConfigFileSync("src/.env");
if (filePath) {
	const config = require(filePath);
}
```

--------------------------------

### Get Single Config File (Async)

Source: https://github.com/constantiner/resolve-node-configs-hierarchy/blob/master/README.md

Imports and uses the `getConfigFile` function to retrieve the path of the single most actual configuration file asynchronously. It then loads the configuration if a file path is found.

```JavaScript
import { getConfigFile } from "@constantiner/resolve-node-configs-hierarchy";

getConfigFile("src/.env").then(filePath => {
	if (filePath) {
		const config = require(filePath);
	}
});
```

--------------------------------

### Configuration File Precedence (.env)

Source: https://github.com/constantiner/resolve-node-configs-hierarchy/blob/master/docs/introduction.md

Demonstrates the order in which `.env` files are loaded, starting from the base `.env` file and progressing to environment-specific and local overrides. The first value set or already defined in the environment takes precedence.

```APIDOC
resolve-node-configs-hierarchy Precedence Order:

1. `.env.production.local` (highest priority)
2. `.env.local`
3. `.env.production`
4. `.env` (lowest priority)

*Note: For the 'test' environment, `.env.local` and `.env.test.local` are excluded by default unless explicitly included via an API flag.
```

--------------------------------

### Ignoring Local Configuration Files (.gitignore)

Source: https://github.com/constantiner/resolve-node-configs-hierarchy/blob/master/docs/introduction.md

Provides examples of local configuration files that should be added to a project's `.gitignore` file to prevent sensitive or environment-specific settings from being committed to version control.

```bash
# Ignore local configuration files
settings.development.local.json
settings.production.local.json
settings.local.json
```

--------------------------------

### Synchronous API: Get Config Files

Source: https://github.com/constantiner/resolve-node-configs-hierarchy/blob/master/docs/api.md

Returns a list of absolute file paths of existing configuration files in order of precedence. This method does not work in a browser environment. It checks for file existence and only includes files that are present.

```TypeScript
declare function getConfigFilesSync(file: string, includeTestLocals?: boolean): string[];
```

```JavaScript
const getConfigFilesSync = require("@constantiner/resolve-node-configs-hierarchy").getConfigFilesSync;
// or
import { getConfigFilesSync } from "@constantiner/resolve-node-configs-hierarchy";
```

--------------------------------

### Get All Config Files

Source: https://github.com/constantiner/resolve-node-configs-hierarchy/blob/master/docs/api.md

Returns a promise that resolves to an array of absolute file paths for existing configuration files, ordered by precedence. This function is not available in browser environments. It checks for file existence and only includes files that are present.

```TypeScript
declare function getConfigFiles(file: string, includeTestLocals?: boolean): Promise<string[]>;

// Example Usage:
// getConfigFiles("configuration/settings.json").then(files => console.log(files));

// Import:
// const getConfigFiles = require("@constantiner/resolve-node-configs-hierarchy").getConfigFiles;
// import { getConfigFiles } from "@constantiner/resolve-node-configs-hierarchy";
```

```JavaScript
getConfigFiles("configuration/settings.json").then(files => console.log(files));

// To import with SystemJS:
// const getConfigFiles = require("@constantiner/resolve-node-configs-hierarchy").getConfigFiles;
// To import with ES6 modules:
// import { getConfigFiles } from "@constantiner/resolve-node-configs-hierarchy";
```

--------------------------------

### Synchronous API: Get Config File

Source: https://github.com/constantiner/resolve-node-configs-hierarchy/blob/master/docs/api.md

Returns the absolute file path of the most precedent existing configuration file in the hierarchy. It checks for file existence and only includes files that are present. Returns null if no relevant files are found.

```TypeScript
declare function getConfigFileSync(file: string, includeTestLocals?: boolean): string | null;
```

```JavaScript
const getConfigFileSync = require("@constantiner/resolve-node-configs-hierarchy").getConfigFileSync;
// or
import { getConfigFileSync } from "@constantiner/resolve-node-configs-hierarchy";
```

--------------------------------

### Get Single Precedent Config File

Source: https://github.com/constantiner/resolve-node-configs-hierarchy/blob/master/docs/api.md

Returns a promise that resolves to the absolute file path of the most precedent existing configuration file. If no relevant files are found, the promise resolves to null. This function also checks for file existence and only includes present files.

```TypeScript
declare function getConfigFile(file: string, includeTestLocals?: boolean): Promise<string | null>;

// Example Usage:
// getConfigFile("configuration/settings.json").then(file => console.log(file));

// Import:
// const getConfigFile = require("@constantiner/resolve-node-configs-hierarchy").getConfigFile;
// import { getConfigFile } from "@constantiner/resolve-node-configs-hierarchy";
```

```JavaScript
getConfigFile("configuration/settings.json").then(file => console.log(file));

// To import with SystemJS:
// const getConfigFile = require("@constantiner/resolve-node-configs-hierarchy").getConfigFile;
// To import with ES6 modules:
// import { getConfigFile } from "@constantiner/resolve-node-configs-hierarchy";
```

--------------------------------

### Environment-Specific Implementations (Email Sender)

Source: https://github.com/constantiner/resolve-node-configs-hierarchy/blob/master/docs/code-samples.md

Demonstrates how to use environment-specific files for different implementations of a module, like an email sender. It finds the appropriate file (e.g., emailSender.development.js) based on the environment and uses it.

```JavaScript
const sendEmail = (to, subject, body) => {
	// Some real implementation here
	return sentStatus;
}

export { sendEmail };
```

```JavaScript
const sendEmail = (to, subject, body) => {
	// Do nothing
	return true;
}

export { sendEmail };
```

```JavaScript
import { getConfigFileSync } from "@constantiner/resolve-node-configs-hierarchy";

const emailSenderFileName = getConfigFileSync("./email/emailSender.js");

const sendEmail = require(emailSenderFileName).sendEmail;

const emailSent = sendEmail("hello@example.com", "Test message", "Hello there!");
console.log(`Email sent status is ${emailSent}`);
```

--------------------------------

### Load Environment Variables (Synchronous)

Source: https://github.com/constantiner/resolve-node-configs-hierarchy/blob/master/docs/code-samples.md

Loads environment variables from .env files using a synchronous approach. It utilizes getConfigFilesSync to find the files and then iterates through them, applying dotenv and dotenvExpand for variable expansion.

```JavaScript
import { getConfigFilesSync } from "@constantiner/resolve-node-configs-hierarchy";
import dotenv from "dotenv";
import dotenvExpand from "dotenv-expand";

const dotenvFiles = getConfigFilesSync(".env");
dotenvFiles.forEach(file => {
	dotenvExpand(
		dotenv.config({
			path: file
		})
	);
});
```

--------------------------------

### API Documentation for Configuration Resolution

Source: https://github.com/constantiner/resolve-node-configs-hierarchy/blob/master/README.md

Provides asynchronous and synchronous methods to resolve configuration file paths based on environment variables and file hierarchy. It supports various environment-specific and local override files.

```APIDOC
getConfigFiles(configPath: string, allowLocal?: boolean): Promise<string[]>
  - Returns a list of absolute file paths of existing configuration files in the order of precedence.
  - Parameters:
    - configPath: The base path and filename of the configuration file (e.g., "configuration/log4js.json").
    - allowLocal: Optional boolean to include `.local` files for the test environment (defaults to false).
  - Example Hierarchy (for development environment):
    - `<project_path>/configuration/log4js.development.local.json`
    - `<project_path>/configuration/log4js.local.json`
    - `<project_path>/configuration/log4js.development.json`
    - `<project_path>/configuration/log4js.json`
  - Returns: A Promise resolving to an array of absolute file paths.

getConfigFile(configPath: string, allowLocal?: boolean): Promise<string | null>
  - Returns the most relevant absolute file path of an existing configuration file in the hierarchy.
  - Parameters:
    - configPath: The base path and filename of the configuration file (e.g., "configuration/log4js.json").
    - allowLocal: Optional boolean to include `.local` files for the test environment (defaults to false).
  - Example (for development environment):
    - `<project_path>/configuration/log4js.development.local.json`
  - Returns: A Promise resolving to the absolute file path as a String, or null if no file is found.

getConfigFilesSync(configPath: string, allowLocal?: boolean): string[]
  - Synchronous version of `getConfigFiles`.
  - Returns: An array of absolute file paths.

getConfigFileSync(configPath: string, allowLocal?: boolean): string | null
  - Synchronous version of `getConfigFile`.
  - Returns: The absolute file path as a String, or null if no file is found.
```

--------------------------------

### Load Environment Variables (Asynchronous)

Source: https://github.com/constantiner/resolve-node-configs-hierarchy/blob/master/docs/code-samples.md

Loads environment variables from .env files using an asynchronous approach. It uses getConfigFiles to retrieve the file paths and then processes them within a Promise, applying dotenv and dotenvExpand.

```JavaScript
import { getConfigFiles } from "@constantiner/resolve-node-configs-hierarchy";
import dotenv from "dotenv";
import dotenvExpand from "dotenv-expand";

getConfigFiles(".env").then(dotenvFiles => {
	dotenvFiles.forEach(file => {
		dotenvExpand(
			dotenv.config({
				path: file
			})
		);
	});
});
```

--------------------------------

### Read Configuration from JSON File

Source: https://github.com/constantiner/resolve-node-configs-hierarchy/blob/master/docs/code-samples.md

Reads configuration settings from a JSON file. It uses getConfigFileSync to locate the JSON file and then requires it to access the settings, such as an API key.

```JavaScript
import { getConfigFileSync } from "@constantiner/resolve-node-configs-hierarchy";

const settingsFileName = getConfigFileSync("./settings.json");

const settings = require(settingsFileName);

console.log(settings.apiKey);
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.