Project configuration loader

Load project for a project from the following places, later levels taking precedence. Each of the following "places" are loaded and merged with the previous one.

• From default values provided programatically
• From a file at the root of the project, or in the parent directory of the root of the project
• From environment variables
• Command line argument, as a JSON string
• Command line argument, as a path to a JSON/JS file

In addition, it will automatically sideload a "secrets" file, for settings that should not remain in a shared configuration file. Loading secrets file follows the same rules as the general config.

Usage

Configuration location

When loading configuration from files without providing the path to the file, the following locations/names are checked:

• <projectRoot>/config.*
• <projectRoot>/../config.*

The file extensions .js, .json, .ts, .cjs, .mjs, .cts, .mts are checked, the first one found is used. For JavaScript/TypeScript files, the default export is expected to contain the configuration. If there is no default export, all other exports are handled as if they were a top-level object.

Secrets file can be placed in the same location (project root or one directory above), and follow the same rules regarding file extensions.

Overriding default file names

For testing purpose it can be useful to override the file names locally. If NODE_ENV is set to test, file names will be config-test.* and secrets-test.*. Alternatively, if KEEEX_CONFIG_SUFFIX is set, it will be appended to the base names (with no dash). The KEEEX_CONFIG_SUFFIX option takes precedence over NODE_ENV.

In any case, the default names (without any suffix) will be used as fallback.

Environment variables

Some properties can be provided using environment variable. Three types of values are supported:

• string: provides the string as-is
• boolean: parse true-like values as true ("1", "true", "TRUE", "on", "ON", "enable", "ENABLED")
• number: any value parsed by Number.parseFloat(value)
• JSON: takes a string and passes it as-is to JSON.parse()
• Arrays: there is no specific option for arrays, use JSON. Note that values of different levels overwrite the previous, so if a value is set in the config file then defined in the environment variable, it will be replaced.

The program must provide a list of fields to load, and environment variable names will be derived from there.

Fields are provided as JSON path, from the root of the configuration (or the root of the secret). The environment variable key is build by converting the path to capital case and replacing the dot with underscores. It is then prefixed with KEEEX_CFG_${name} (or KEEEX_SECRET_${name} for secrets), which is used as the base name below.

For example, assuming a property config.paths.storage that is a string, the config JSON path is paths.storage and the environment key basename is KEEEX_CFG_PATHS_STORAGE. The value can be provided either by setting KEEEX_CFG_PATHS_STORAGE, or by putting the path to a file in KEEEX_CFG_PATHS_STORAGE__FILE which will be loaded as a string (stripping whitespaces at the end).

Command-line configuration

It is possible to load a different configuration from command line. Passing --config <some json> will load that JSON instead of the config file.

One can also pass --config <path to json file> to load a different config from another file.

The same can be done for secrets with --secrets.

Specific values can be set if they're configured to be available through environment variables.

In the above example, config.paths.storage could be set using --config.paths.storage <value> or --config.paths.storage-file <file path>. For secrets, the argument would be --secrets.db.user for config.secrets.db.user.

Accessing the configuration

The loaded configuration can be obtained by calling the function loadConfig().

import {makeProfilePredicate} from "@keeex/utils/types/record.js";
import * as projectConfig from "@keeex/projectconfig";

interface Paths {
  importantDir: string;
  webRoot: string;
}

const isPaths = makeProfilePredicate<Paths>({
  importantDir: "string",
  webRoot: "string",
});

interface Config {
  debug: boolean;
  paths: Paths;
  port: number;
}

const isConfig = makeProfilePredicate<Config>({
  debug: "boolean",
  paths: isPaths,
  port: "number",
});

interface Secrets {
  login: string;
  password: string;
}

const isSecrets = makeProfilePredicate<Secrets>({
  login: "string";
  password: "string";
});

const getConfig = (): Promise<projectConfig.ProjectConfig<Config, Secrets>> =>
  projectConfig.loadConfig({
    configDefault: {
      port: 3000,
      debug: false,
      paths: {webRoot: "./dist"},
    },
    configEnvironmentVars: {
      "port": projectConfig.TypeForEnv.number,
      "debug": projectConfig.TypeForEnv.boolean,
      "paths.importantDir": projectConfig.TypeForEnv.string,
      "paths.webRoot": projectConfig.TypesForEnv.string,
    },
    configPredicate: isConfig,
    secretsPredicate: isSecrets,
  });

export default getConfig();

In the above exemple, we define a module that export the fully-typed configuration, to be used throughout a project. Using this module would look something like this:

import getConfig from "./services/config.js";

const config = await getConfig();

console.log(`
Port: ${config.port}
Debug: ${config.debug}
ImportantDir: ${config.paths.importantDir}
WebRoot: ${config.paths.webRoot}
User: ${config.secrets.login}
Password: ${"*".repeat(config.secrets.password.length)}
`);

The loaded configuration is cached after the first call, so it is safe to recall this function multiple times from multiple places if needed.