configate 0.1.2 → 0.1.3

package/dist/common.d.ts

@@ -0,0 +1,7 @@
+export type DefaultConfig = Record<string, any>;
+export type Environment = 'development' | 'staging' | 'production' | 'test' | string;
+export type FileExtension = 'ts' | 'mts' | 'js' | 'mjs' | 'cjs' | 'json';
+export type DeepPartial<T> = T extends object ? {
+    [P in keyof T]?: DeepPartial<T[P]>;
+} : T | undefined;
+export declare function isObject(item: unknown): item is object;

package/dist/common.js

@@ -0,0 +1,3 @@
+export function isObject(item) {
+    return item !== null && typeof item === 'object' && !Array.isArray(item);
+}

package/dist/deepFreezeConfig.d.ts

@@ -0,0 +1,5 @@
+import { type DefaultConfig } from './common.ts';
+/**
+ * Use Object.freeze to make the config object immutable
+ */
+export declare function deepFreezeConfig<T extends DefaultConfig>(config: T): T;

package/dist/deepFreezeConfig.js

@@ -0,0 +1,12 @@
+import { isObject } from "./common.js";
+/**
+ * Use Object.freeze to make the config object immutable
+ */
+export function deepFreezeConfig(config) {
+    for (const key in config) {
+        if (isObject(config[key])) {
+            config[key] = deepFreezeConfig(config[key]);
+        }
+    }
+    return Object.freeze(config);
+}

package/dist/deepMerge.d.ts

@@ -0,0 +1,9 @@
+import { type DefaultConfig } from './common.ts';
+/**
+ * Custom implementation of deepMerge to avoid using an external dependency
+ *
+ * - it merges objects deeply
+ * - it overrides array, doesn't merge array elements
+ * - it ignores properties with `undefined` values
+ */
+export declare function deepMerge<T extends DefaultConfig>(target: T, ...sources: Array<Partial<T>>): T;

package/dist/deepMerge.js

@@ -0,0 +1,31 @@
+import { isObject } from "./common.js";
+/**
+ * Custom implementation of deepMerge to avoid using an external dependency
+ *
+ * - it merges objects deeply
+ * - it overrides array, doesn't merge array elements
+ * - it ignores properties with `undefined` values
+ */
+export function deepMerge(target, ...sources) {
+    if (!sources.length) {
+        return target;
+    }
+    const source = sources.shift();
+    if (isObject(target) && isObject(source)) {
+        for (const key in source) {
+            if (Object.prototype.hasOwnProperty.call(source, key)) {
+                if (key === '__proto__' || key === 'constructor') {
+                    continue;
+                }
+                const sourceValue = source[key];
+                if (isObject(sourceValue) && isObject(target[key])) {
+                    target[key] = deepMerge(target[key], sourceValue);
+                }
+                else if (sourceValue !== undefined) {
+                    target[key] = sourceValue;
+                }
+            }
+        }
+    }
+    return deepMerge(target, ...sources);
+}

package/dist/importConfigFile.d.ts

@@ -0,0 +1,6 @@
+import type { DefaultConfig, FileExtension } from './common.ts';
+export declare function importConfigFile<Config extends DefaultConfig>({ filePath, fileExtensions, shouldThrowError, }: {
+    filePath: string;
+    fileExtensions: FileExtension[];
+    shouldThrowError?: boolean;
+}): Promise<Config>;

package/dist/importConfigFile.js

@@ -0,0 +1,45 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import fs from 'node:fs/promises';
+export async function importConfigFile({ filePath, fileExtensions, shouldThrowError = false, }) {
+    let selectedExtension;
+    for (const ext of fileExtensions) {
+        try {
+            // Quickly check if the file exists to avoid unnecessary parsing in import()
+            await fs.access(`${filePath}.${ext}`, fs.constants.R_OK);
+            selectedExtension = ext;
+            break;
+        }
+        catch (_error) { }
+    }
+    if (!selectedExtension) {
+        if (shouldThrowError) {
+            throw new Error(`Config file "${filePath}" not found with any extension: ${fileExtensions.join(', ')}`);
+        }
+        return {};
+    }
+    const importOptions = selectedExtension === 'json' ? { with: { type: 'json' } } : undefined;
+    try {
+        const configFile = await import(__rewriteRelativeImportExtension(`${filePath}.${selectedExtension}`), importOptions);
+        // Named export of `config` variable is preferred over default export
+        if (configFile.config) {
+            return configFile.config;
+        }
+        if (configFile.default) {
+            return configFile.default;
+        }
+        throw new Error(`Config file "${filePath}" has no default export and does not have export "config"`);
+    }
+    catch (error) {
+        if (shouldThrowError) {
+            throw error;
+        }
+        return {};
+    }
+}

package/dist/importConfigFiles.d.ts

@@ -0,0 +1,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>;
+type ImportConfigFilesOptions = {
+    configDir: string;
+    environment?: Environment;
+    fileExtensions: FileExtension[];
+};
+export {};

package/dist/importConfigFiles.js

@@ -0,0 +1,45 @@
+import { deepMerge } from "./deepMerge.js";
+import { importConfigFile } from "./importConfigFile.js";
+/**
+ * Import multiple config files in defined order and merge them deeply together
+ */
+export async function importConfigFiles({ configDir, environment, fileExtensions, }) {
+    /** default.ext **/
+    const defaultConfig = await importConfigFile({
+        filePath: `${configDir}/default`,
+        fileExtensions,
+        shouldThrowError: true,
+    });
+    /** {environment}.ext **/
+    let envConfig;
+    if (environment) {
+        try {
+            envConfig = await importConfigFile({
+                filePath: `${configDir}/${environment}`,
+                fileExtensions,
+                shouldThrowError: true,
+            });
+        }
+        catch (_error) {
+            console.warn(`Environment ${environment} defined but no config file found`);
+        }
+    }
+    /** local.ext **/
+    const localConfig = await importConfigFile({
+        filePath: `${configDir}/local`,
+        fileExtensions,
+    });
+    /** local-{environment}.ext **/
+    const localEnvConfig = environment
+        ? await importConfigFile({
+            filePath: `${configDir}/local-${environment}`,
+            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));
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { loadConfig } from './loadConfig.ts';
+export type { DeepPartial, FileExtension } from './common.ts';

package/dist/index.js

@@ -0,0 +1 @@
+export { loadConfig } from "./loadConfig.js";

package/dist/loadConfig.d.ts

@@ -0,0 +1,39 @@
+import type { DefaultConfig, Environment, FileExtension } from './common.ts';
+/**
+ * Config library to load configuration files based on the environment
+ *
+ * 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)
+ * - 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)
+ * - Config file can `export default {}` or `export const config: Config = { ... }`.
+ *     - named export is recommended in TS for type safety of the config object
+ *
+ * @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 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
+ *
+ * @returns a promise that resolves to an object with 2 properties:
+ *    - `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<{
+    config: Config;
+    unsecureConfig: Config;
+}>;
+type LoadConfigOptions = {
+    configDirs?: string[];
+    environment?: Environment;
+    fileExtensions?: FileExtension[];
+    throwOnUndefinedProp?: boolean;
+    freezeConfig?: boolean;
+};
+export {};

package/dist/loadConfig.js

@@ -0,0 +1,52 @@
+import { deepFreezeConfig } from "./deepFreezeConfig.js";
+import { deepMerge } from "./deepMerge.js";
+import { importConfigFiles } from "./importConfigFiles.js";
+import { makeSecureDeepProxy } from "./makeSecureDeepProxy.js";
+/**
+ * Config library to load configuration files based on the environment
+ *
+ * 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)
+ * - 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)
+ * - Config file can `export default {}` or `export const config: Config = { ... }`.
+ *     - named export is recommended in TS for type safety of the config object
+ *
+ * @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 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
+ *
+ * @returns a promise that resolves to an object with 2 properties:
+ *    - `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, } = {}) {
+    let mergedConfig = {};
+    for (const configDir of configDirs) {
+        const config = await importConfigFiles({
+            configDir,
+            environment,
+            fileExtensions,
+        });
+        mergedConfig = deepMerge(mergedConfig, config);
+    }
+    const unsecureConfig = structuredClone(mergedConfig);
+    if (throwOnUndefinedProp) {
+        mergedConfig = makeSecureDeepProxy(mergedConfig);
+    }
+    if (freezeConfig) {
+        mergedConfig = deepFreezeConfig(mergedConfig);
+    }
+    return {
+        config: mergedConfig,
+        unsecureConfig: unsecureConfig,
+    };
+}

package/dist/makeSecureDeepProxy.d.ts

@@ -0,0 +1,6 @@
+import { type DefaultConfig } from './common.ts';
+/**
+ * Use Proxy to add custom behavior when accessing properties of the config object
+ * Throw an error if the property is not defined in the config
+ */
+export declare function makeSecureDeepProxy<T extends DefaultConfig>(config: T): T;

package/dist/makeSecureDeepProxy.js

@@ -0,0 +1,35 @@
+import { isObject } from "./common.js";
+/**
+ * Use Proxy to add custom behavior when accessing properties of the config object
+ * Throw an error if the property is not defined in the config
+ */
+export function makeSecureDeepProxy(config) {
+    for (const prop in config) {
+        if (isObject(config[prop])) {
+            // If it's an object, recursively wrap it
+            config[prop] = makeSecureDeepProxy(config[prop]);
+        }
+        else if (Array.isArray(config[prop])) {
+            // If it's an array, wrap each element and the array itself
+            config[prop] = makeSecureProxy(config[prop].map((item) => isObject(item) || Array.isArray(item)
+                ? makeSecureDeepProxy(item)
+                : item));
+        }
+    }
+    return makeSecureProxy(config);
+}
+function makeSecureProxy(targetObject) {
+    return new Proxy(targetObject, {
+        get(target, prop) {
+            // Handle Symbol.toStringTag and Array properties
+            if (prop === Symbol.toStringTag ||
+                (Array.isArray(target) && Number.isNaN(Number(prop)))) {
+                return Reflect.get(target, prop);
+            }
+            if (!(prop in target)) {
+                throw new Error(`Property ${String(prop)} is not defined in the config`);
+            }
+            return Reflect.get(target, prop);
+        },
+    });
+}

package/package.json

@@ -1,43 +1,47 @@
 {
-	"name": "configate",
-	"version": "0.1.2",
-	"type": "module",
-	"description": "Configuration helper for TypeScript applications",
-	"main": "dist/index.js",
-	"module": "dist/index.js",
-	"types": "dist/index.d.ts",
-	"exports": {
-		".": {
-			"default": "./dist/index.js",
-			"import": "./dist/index.js",
-			"types": "./dist/index.d.ts"
-		}
-	},
-	"scripts": {
-		"build": "tsc",
-		"ci": "node --run test && npm run typecheck && node --run lint",
-		"lint": "biome check",
-		"test": "node --test-isolation=none --test-reporter=spec --experimental-test-coverage --test-coverage-exclude='src/{testConfigDirs/**/*,**/*.test.ts}' --test 'src/**/*.test.ts'",
-		"typecheck": "tsc --noEmit"
-	},
-	"files": ["dist"],
-	"engines": {
-		"node": ">= 20"
-	},
-	"repository": {
-		"type": "git",
-		"url": "git+https://github.com/mdrobny/configate.git"
-	},
-	"keywords": ["config"],
-	"author": "Michal Drobniak",
-	"license": "Apache-2.0",
-	"bugs": {
-		"url": "https://github.com/mdrobny/configate/issues"
-	},
-	"homepage": "https://github.com/mdrobny/configate#readme",
-	"devDependencies": {
-		"@biomejs/biome": "1.9.4",
-		"@types/node": "^22.10.6",
-		"typescript": "^5.7.3"
-	}
+  "name": "configate",
+  "version": "0.1.3",
+  "type": "module",
+  "description": "Configuration helper for TypeScript applications",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "default": "./dist/index.js",
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "ci": "node --run test && npm run typecheck && node --run lint",
+    "lint": "biome check",
+    "test": "node --test-isolation=none --test-reporter=spec --experimental-test-coverage --test-coverage-exclude='src/{testConfigDirs/**/*,**/*.test.ts}' --test 'src/**/*.test.ts'",
+    "typecheck": "tsc --noEmit"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">= 20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mdrobny/configate.git"
+  },
+  "keywords": [
+    "config"
+  ],
+  "author": "Michal Drobniak",
+  "license": "Apache-2.0",
+  "bugs": {
+    "url": "https://github.com/mdrobny/configate/issues"
+  },
+  "homepage": "https://github.com/mdrobny/configate#readme",
+  "devDependencies": {
+    "@biomejs/biome": "1.9.4",
+    "@types/node": "^22.10.6",
+    "typescript": "^5.7.3"
+  }
 }