configate 1.0.0 → 1.2.0

package/README.md

@@ -45,6 +45,7 @@ Use the `loadConfig` function once, to load and merge configurations from specif
 With parameters you can define:
 - `configDirs`: (Default: `['${current-working-directory}/config']`) An array of directories to load configurations from
 - `environment`: (Default: `process.env.NODE_ENV`) The environment to load specific configurations for
+- `variant`: (Default: `undefined`) Allows to define 2nd dimension of configs above environment. Will load configs matching `*-{variant}` pattern
 - `fileExtensions`: (Default: `['ts', 'js']`) An array of file extensions to load configurations from
 - `throwOnUndefinedProp`: (Default: `true`) If true, throws an error when accessing undefined properties
 - `freezeConfig`: (Default: `true`) If true, freezes the configuration object to make it immutable
@@ -123,8 +124,10 @@ Do the same for other environments if you need to override more properties for t
 When you need to define secrets in configuration, they should be defined via environment variables.
 
 Create `custom-environment-variables.ts` file in `config` directory and export a `config` object.
+
 - use `process.env` to read environment variables and assign to property in your configuration
-- this file will be merged with other configs as last one so environment variables always have priority
+- this file is merged last within its directory, so its defined values override other files in that directory
+   - when loading multiple directories, later directories can override these values.
 
 ```ts
 // config/custom-environment-variables.ts
@@ -153,14 +156,54 @@ Add this to `.gitignore` to prevent committing local configuration files:
 **/config/local*
 ```
 
+### Second layer of variant configurations
+
+Some applications may need another layer of overrides besides environments (for example: regions, brands, customers etc).
+Pass the `variant` option to `loadConfig` and create files that follow the `*-{variant}` naming convention to scope those overrides.
+
+When `variant` is set, Configate looks for these optional files on top of the usual ones:
+- `default-{variant}.ext`
+- `{environment}-{variant}.ext`
+- `local-{variant}.ext`
+- `local-{environment}-{variant}.ext`
+
+Example setup:
+
+```text
+config/
+  default.ts
+  default-customerA.ts
+  default-customerB.ts
+  production.ts
+  production-customerA.ts
+```
+
+```ts
+// src/config.ts
+import { loadConfig } from 'configate';
+
+export const { config } = await loadConfig<AppConfig>({
+  environment: 'production',
+  variant: 'customerA',
+});
+```
+
+This keeps the base config reusable while still letting you target per-variant overrides without duplicating entire files.
+
 ### Order of loading configuration files
 
+The following order applies separately within each configuration directory.
+
 ```
-default.ext
-{environment}.ext
-local.ext
-local-{environment}.ext
-custom-environment-variables.ext
+1. default.ext
+2. default-{variant}.ext
+3. {environment}.ext
+4. {environment}-{variant}.ext
+5. local.ext
+6. local-{variant}.ext
+7. local-{environment}.ext
+8. local-{environment}-{variant}.ext
+9. custom-environment-variables.ext
 ```
 
 ### Using unsecure config
@@ -211,6 +254,11 @@ const host = config.database.host;
 
 #### Loading configurations from multiple directories
 
+Directories are fully loaded and merged in `configDirs` order. 
+Values from later directories override matching properties from earlier directories.
+
+For example, a value in the second directory's `default.ts` can override the same property from the first directory's `custom-environment-variables.ts`.
+
 ```ts
 import { loadConfig } from 'configate';
 
@@ -221,4 +269,3 @@ export const { config } = await loadConfig<TestConfig>({
   ],
 });
 ```
-

package/dist/deepFreezeConfig.js

@@ -4,7 +4,7 @@ import { isObject } from "./common.js";
  */
 export function deepFreezeConfig(config) {
     for (const key in config) {
-        if (isObject(config[key])) {
+        if (isObject(config[key]) || Array.isArray(config[key])) {
             config[key] = deepFreezeConfig(config[key]);
         }
     }

package/dist/importConfigFiles.d.ts

@@ -2,10 +2,11 @@ import type { DefaultConfig, Environment, FileExtension } from './common.ts';
 /**
  * Import multiple config files in defined order and merge them deeply together
  */
-export declare function importConfigFiles<Config extends DefaultConfig>({ configDir, environment, fileExtensions, }: ImportConfigFilesOptions): Promise<DefaultConfig>;
+export declare function importConfigFiles<Config extends DefaultConfig>({ configDir, environment, variant, fileExtensions, }: ImportConfigFilesOptions): Promise<DefaultConfig>;
 type ImportConfigFilesOptions = {
     configDir: string;
     environment?: Environment;
+    variant?: string;
     fileExtensions: FileExtension[];
 };
 export {};

package/dist/importConfigFiles.js

@@ -3,18 +3,27 @@ import { importConfigFile } from "./importConfigFile.js";
 /**
  * Import multiple config files in defined order and merge them deeply together
  */
-export async function importConfigFiles({ configDir, environment, fileExtensions, }) {
+export async function importConfigFiles({ configDir, environment, variant, fileExtensions, }) {
     /** default.ext **/
     const defaultConfig = await importConfigFile({
         filePath: `${configDir}/default`,
         fileExtensions,
         shouldThrowError: true,
     });
+    /** default-{variant}.ext **/
+    let defaultVariantConfig;
+    if (variant) {
+        defaultVariantConfig = await importConfigFile({
+            filePath: `${configDir}/default-${variant}`,
+            fileExtensions,
+        });
+    }
     /** {environment}.ext **/
-    let envConfig;
+    let environmentConfig;
+    let environmentVariantConfig;
     if (environment) {
         try {
-            envConfig = await importConfigFile({
+            environmentConfig = await importConfigFile({
                 filePath: `${configDir}/${environment}`,
                 fileExtensions,
                 shouldThrowError: true,
@@ -23,12 +32,27 @@ export async function importConfigFiles({ configDir, environment, fileExtensions
         catch (_error) {
             console.warn(`Environment ${environment} defined but no config file found`);
         }
+        /** {environment}-{variant}.ext **/
+        if (variant) {
+            environmentVariantConfig = await importConfigFile({
+                filePath: `${configDir}/${environment}-${variant}`,
+                fileExtensions,
+            });
+        }
     }
     /** local.ext **/
     const localConfig = await importConfigFile({
         filePath: `${configDir}/local`,
         fileExtensions,
     });
+    /** local-{variant}.ext **/
+    let localVariantConfig;
+    if (variant) {
+        localVariantConfig = await importConfigFile({
+            filePath: `${configDir}/local-${variant}`,
+            fileExtensions,
+        });
+    }
     /** local-{environment}.ext **/
     const localEnvConfig = environment
         ? await importConfigFile({
@@ -36,10 +60,17 @@ export async function importConfigFiles({ configDir, environment, fileExtensions
             fileExtensions,
         })
         : {};
+    /** local-{environment}-{variant}.ext **/
+    const localEnvVariantConfig = environment && variant
+        ? await importConfigFile({
+            filePath: `${configDir}/local-${environment}-${variant}`,
+            fileExtensions,
+        })
+        : {};
     /** custom-environment-variables.ext **/
     const customEnvVarsConfig = await importConfigFile({
         filePath: `${configDir}/custom-environment-variables`,
         fileExtensions: fileExtensions.filter((ext) => ext !== 'json'), // JSON not supported because it cannot use `process.env`
     });
-    return deepMerge(structuredClone(defaultConfig), structuredClone(envConfig ?? {}), structuredClone(localConfig), structuredClone(localEnvConfig), structuredClone(customEnvVarsConfig));
+    return deepMerge(structuredClone(defaultConfig), structuredClone(defaultVariantConfig ?? {}), structuredClone(environmentConfig ?? {}), structuredClone(environmentVariantConfig ?? {}), structuredClone(localConfig), structuredClone(localVariantConfig ?? {}), structuredClone(localEnvConfig), structuredClone(localEnvVariantConfig), structuredClone(customEnvVarsConfig));
 }

package/dist/loadConfig.d.ts

@@ -5,10 +5,14 @@ import type { DefaultConfig, Environment, FileExtension } from './common.ts';
  * Features:
  * - Load config files in order:
  *     1. default.ext
- *     2. {environment}.ext
- *     4. local.ext
- *     3. local-{environment}.ext
- *     5. custom-environment-variables.ext (only for .ts and .js files)
+ *     2. default-{variant}.ext
+ *     3. {environment}.ext
+ *     4. {environment}-{variant}.ext
+ *     5. local.ext
+ *     6. local-{variant}.ext
+ *     7. local-{environment}.ext
+ *     8. local-{environment}-{variant}.ext
+ *     9. custom-environment-variables.ext (only for .ts and .js files)
  * - Throw an error if a property is accessed that is not defined in the config
  * - Freeze the config object to prevent modifications
  * - Supported config file formats: TypeScript (.ts, .mts), JavaScript (.js, .mjs), JSON (.json)
@@ -17,6 +21,7 @@ import type { DefaultConfig, Environment, FileExtension } from './common.ts';
  *
  * @param configDirs - paths to directories where the config files are located. Relative or absolute. Directories are merged in the array order. Default: ['${current-working-directory}/config']
  * @param environment - the environment to load the config for. Default: process.env.NODE_ENV
+ * @param variant - allows to define 2nd dimension of configs above environment. Default: undefined
  * @param fileExtensions - an array of file extensions to use when looking for config files. Configs are loaded in this order. Default: ['ts', 'js']
  * @param throwOnUndefinedProp - throw an error if a property is accessed that is not defined in the config. Default: true
  * @param freezeConfig - freeze the config object to prevent modifications. Default: true
@@ -25,13 +30,14 @@ import type { DefaultConfig, Environment, FileExtension } from './common.ts';
  *    - `config` - a secure, frozen object with the loaded config. Throws an error if an undefined property is accessed
  *    - `unsecureConfig` - an unsecure config. May be needed if config is passed directly to some module that wants to read undefined props or modify it
  */
-export declare function loadConfig<Config extends DefaultConfig>({ configDirs, environment, fileExtensions, throwOnUndefinedProp, freezeConfig, }?: LoadConfigOptions): Promise<{
+export declare function loadConfig<Config extends DefaultConfig>({ configDirs, environment, variant, fileExtensions, throwOnUndefinedProp, freezeConfig, }?: LoadConfigOptions): Promise<{
     config: Config;
     unsecureConfig: Config;
 }>;
 type LoadConfigOptions = {
     configDirs?: string[];
     environment?: Environment;
+    variant?: string;
     fileExtensions?: FileExtension[];
     throwOnUndefinedProp?: boolean;
     freezeConfig?: boolean;

package/dist/loadConfig.js

@@ -8,10 +8,14 @@ import { makeSecureDeepProxy } from "./makeSecureDeepProxy.js";
  * Features:
  * - Load config files in order:
  *     1. default.ext
- *     2. {environment}.ext
- *     4. local.ext
- *     3. local-{environment}.ext
- *     5. custom-environment-variables.ext (only for .ts and .js files)
+ *     2. default-{variant}.ext
+ *     3. {environment}.ext
+ *     4. {environment}-{variant}.ext
+ *     5. local.ext
+ *     6. local-{variant}.ext
+ *     7. local-{environment}.ext
+ *     8. local-{environment}-{variant}.ext
+ *     9. custom-environment-variables.ext (only for .ts and .js files)
  * - Throw an error if a property is accessed that is not defined in the config
  * - Freeze the config object to prevent modifications
  * - Supported config file formats: TypeScript (.ts, .mts), JavaScript (.js, .mjs), JSON (.json)
@@ -20,6 +24,7 @@ import { makeSecureDeepProxy } from "./makeSecureDeepProxy.js";
  *
  * @param configDirs - paths to directories where the config files are located. Relative or absolute. Directories are merged in the array order. Default: ['${current-working-directory}/config']
  * @param environment - the environment to load the config for. Default: process.env.NODE_ENV
+ * @param variant - allows to define 2nd dimension of configs above environment. Default: undefined
  * @param fileExtensions - an array of file extensions to use when looking for config files. Configs are loaded in this order. Default: ['ts', 'js']
  * @param throwOnUndefinedProp - throw an error if a property is accessed that is not defined in the config. Default: true
  * @param freezeConfig - freeze the config object to prevent modifications. Default: true
@@ -28,12 +33,13 @@ import { makeSecureDeepProxy } from "./makeSecureDeepProxy.js";
  *    - `config` - a secure, frozen object with the loaded config. Throws an error if an undefined property is accessed
  *    - `unsecureConfig` - an unsecure config. May be needed if config is passed directly to some module that wants to read undefined props or modify it
  */
-export async function loadConfig({ configDirs = [`${process.cwd()}/config`], environment = process.env.NODE_ENV, fileExtensions = ['ts', 'js'], throwOnUndefinedProp = true, freezeConfig = true, } = {}) {
+export async function loadConfig({ configDirs = [`${process.cwd()}/config`], environment = process.env.NODE_ENV, variant, fileExtensions = ['ts', 'js'], throwOnUndefinedProp = true, freezeConfig = true, } = {}) {
     let mergedConfig = {};
     for (const configDir of configDirs) {
         const config = await importConfigFiles({
             configDir,
             environment,
+            variant,
             fileExtensions,
         });
         mergedConfig = deepMerge(mergedConfig, config);

package/dist/makeSecureDeepProxy.js

@@ -23,8 +23,10 @@ function makeSecureProxy(targetObject) {
         get(target, prop) {
             // Handle Symbol and Array properties
             if (typeof prop === 'symbol' ||
-                // Don't throw error when using array methods
-                (Array.isArray(target) && Number.isNaN(Number(prop)))) {
+                /** Don't throw error when using array methods */
+                (Array.isArray(target) && Number.isNaN(Number(prop))) ||
+                /** Allow stringifying proxied config (because JSON.stringify calls this method) */
+                prop === 'toJSON') {
                 return Reflect.get(target, prop);
             }
             if (!(prop in target)) {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "configate",
-	"version": "1.0.0",
+	"version": "1.2.0",
 	"type": "module",
 	"description": "Configuration helper for TypeScript applications",
 	"main": "dist/index.js",
@@ -30,6 +30,10 @@
 		"type": "git",
 		"url": "git+https://github.com/mdrobny/configate.git"
 	},
+	"publishConfig": {
+		"registry": "https://registry.npmjs.org",
+		"provenance": true
+	},
 	"keywords": [
 		"config"
 	],
@@ -40,8 +44,18 @@
 	},
 	"homepage": "https://github.com/mdrobny/configate#readme",
 	"devDependencies": {
-		"@biomejs/biome": "2.3.8",
+		"@biomejs/biome": "2.5.13",
 		"@types/node": "^22.10.6",
 		"typescript": "^5.7.3"
+	},
+	"devEngines": {
+		"runtime": {
+			"name": "node",
+			"onFail": "error"
+		},
+		"packageManager": {
+			"name": "npm",
+			"onFail": "error"
+		}
 	}
 }