API Reference

Depending on your needs you can choose synchronous or asynchronous methods.

Synchronous API

getConfigFilesSync

Returns a list of absolute file paths of existing files in order of precedence. Doesn't work in browser environment.

For example, if we have the following file structure:

project_root
 │
 └ configuration
    │
    ├ settings.json
    ├ settings.development.json
    ├ settings.production.json
    ├ settings.local.json
    ├ settings.development.local.json
    └ settings.production.local.json

And call getConfigFilesSync like the following in development environment:

getConfigFilesSync("configuration/settings.json");

It will return the following array:

["<project_root_absolute_path>/configuration/settings.development.local.json", "<project_root_absolute_path>/configuration/settings.local.json", "<project_root_absolute_path>/configuration/settings.development.json", "<project_root_absolute_path>/configuration/settings.json"]

It will return an empty array if there is no relevant files.

Note: it checks files existence and doesn't include inexistent files!

Signature is the following:

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

Parameters:

  • file: string — is base file path (related to process.cwd()).
  • includeTestLocals: boolean (optional, default is false) — if true it will include local files for test environment (ignores them by default). So, if you pass true it will work absolutely the same way for any environment. See explanation about test environment in introduction section.

Returns:

string[] — an array of existing absolute file paths in order of precedence.

To import it with SystemJS:

const getConfigFilesSync = require("@constantiner/resolve-node-configs-hierarchy").getConfigFilesSync;

or with ES6 modules:

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

getConfigFileSync

Returns absolute file path of the most precedent existing file in files hierarchy.

For example, if we have the following file structure:

project_root
 │
 └ configuration
    │
    ├ settings.json
    ├ settings.development.json
    ├ settings.production.json
    ├ settings.local.json
    └ settings.production.local.json

And call getConfigFileSync like the following in development environment:

getConfigFileSync("configuration/settings.json");

It will return the following string:

"<project_root_absolute_path>/configuration/settings.local.json"

It will return null if there is no relevant files.

Note: it checks files existence and doesn't include inexistent files!

Signature is the following:

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

Parameters:

  • file: string — is base file path (related to process.cwd()).
  • includeTestLocals: boolean (optional, default is false) — if true it will include local files for test environment (ignores them by default). So, if you pass true it will work absolutely the same way for any environment. See explanation about test environment in introduction section.

Returns either:

  • string — the most precedent existing file in files hierarchy. It is the first element of array, returned from getConfigFilesSync method (if the array is not empty).
  • null if there are no existing files.

To import it with SystemJS:

const getConfigFileSync = require("@constantiner/resolve-node-configs-hierarchy").getConfigFileSync;

or with ES6 modules:

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

Asynchronous API

getConfigFiles

Returns a promise resolving to a list of absolute file paths of existing files in order of precedence. Doesn't work in browser environment.

For example, if we have the following file structure:

project_root
 │
 └ configuration
    │
    ├ settings.json
    ├ settings.development.json
    ├ settings.production.json
    ├ settings.local.json
    ├ settings.development.local.json
    └ settings.production.local.json

And call getConfigFiles like the following in development environment:

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

It will print in console the following array:

["<project_root_absolute_path>/configuration/settings.development.local.json", "<project_root_absolute_path>/configuration/settings.local.json", "<project_root_absolute_path>/configuration/settings.development.json", "<project_root_absolute_path>/configuration/settings.json"]

Returning promise will resolve to an empty array if there is no relevant files.

Note: it checks files existence and doesn't include inexistent files!

Signature is the following:

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

Parameters:

  • file: string — is base file path (related to process.cwd()).
  • includeTestLocals: boolean (optional, default is false) — if true it will include local files for test environment (ignores them by default). So, if you pass true it will work absolutely the same way for any environment. See explanation about test environment in introduction section.

Returns:

Promise<string[]> — a promise resolving to an array of existing absolute file paths in order of precedence.

To import it with SystemJS:

const getConfigFiles = require("@constantiner/resolve-node-configs-hierarchy").getConfigFiles;

or with ES6 modules:

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

getConfigFile

Returns a promise resolving to absolute file path of the most precedent existing file in files hierarchy.

For example, if we have the following file structure:

project_root
 │
 └ configuration
    │
    ├ settings.json
    ├ settings.development.json
    ├ settings.production.json
    ├ settings.local.json
    └ settings.production.local.json

And call getConfigFile like the following in development environment:

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

It will print to console the following string:

"<project_root_absolute_path>/configuration/settings.local.json"

Resulting promise will resolve to null if there is no relevant files.

Note: it checks files existence and doesn't include inexistent files!

Signature is the following:

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

Parameters:

  • file: string — is base file path (related to process.cwd()).
  • includeTestLocals: boolean (optional, default is false) — if true it will include local files for test environment (ignores them by default). So, if you pass true it will work absolutely the same way for any environment. See explanation about test environment in introduction section.

Returns:

Promise<string | null> — a promise resolving to the most precedent existing file in files hierarchy. It is the first element of array, returned from getConfigFiles method (if the array is not empty). In case of empty array (files don't exist) the resulting promise will resolve to null.

To import it with SystemJS:

const getConfigFile = require("@constantiner/resolve-node-configs-hierarchy").getConfigFile;

or with ES6 modules:

import { getConfigFile } from "@constantiner/resolve-node-configs-hierarchy";
← ChangelogCode Samples →