configate 0.1.0 → 0.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "configate",
-	"version": "0.1.0",
+	"version": "0.1.2",
 	"type": "module",
 	"description": "Configuration helper for TypeScript applications",
 	"main": "dist/index.js",

package/dist/common.d.ts

@@ -1,7 +0,0 @@
-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

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

package/dist/deepFreezeConfig.d.ts

@@ -1,5 +0,0 @@
-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

@@ -1,12 +0,0 @@
-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

@@ -1,9 +0,0 @@
-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

@@ -1,31 +0,0 @@
-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/defineConfig.d.ts

@@ -1,39 +0,0 @@
-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 defineConfig<Config extends DefaultConfig>({ configDirs, environment, fileExtensions, throwOnUndefinedProp, freezeConfig, }: DefineConfigOptions): Promise<{
-    config: Config;
-    unsecureConfig: Config;
-}>;
-type DefineConfigOptions = {
-    configDirs?: string[];
-    environment?: Environment;
-    fileExtensions?: FileExtension[];
-    throwOnUndefinedProp?: boolean;
-    freezeConfig?: boolean;
-};
-export {};

package/dist/defineConfig.js

@@ -1,52 +0,0 @@
-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 defineConfig({ 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/importConfigFile.d.ts

@@ -1,6 +0,0 @@
-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

@@ -1,45 +0,0 @@
-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

@@ -1,8 +0,0 @@
-import type { DefaultConfig, Environment, FileExtension } from './common.ts';
-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

@@ -1,37 +0,0 @@
-import { deepMerge } from "./deepMerge.js";
-import { importConfigFile } from "./importConfigFile.js";
-export async function importConfigFiles({ configDir, environment, fileExtensions, }) {
-    const defaultConfig = await importConfigFile({
-        filePath: `${configDir}/default`,
-        fileExtensions,
-        shouldThrowError: true,
-    });
-    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`);
-        }
-    }
-    const localConfig = await importConfigFile({
-        filePath: `${configDir}/local`,
-        fileExtensions,
-    });
-    const localEnvConfig = environment
-        ? await importConfigFile({
-            filePath: `${configDir}/local-${environment}`,
-            fileExtensions,
-        })
-        : {};
-    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

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

package/dist/index.js

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

package/dist/makeSecureDeepProxy.d.ts

@@ -1,6 +0,0 @@
-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

@@ -1,35 +0,0 @@
-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);
-        },
-    });
-}