@keeex/projectconfig 4.2.1 → 5.0.1

package/README.md

@@ -43,10 +43,55 @@ The same can be done for secrets with `--secrets`.
 
 ### Accessing the configuration
 
-The loaded configuration is available as the default export of the library:
+The loaded configuration can be obtained by calling the function `loadConfig()`.
+
+```typescript
+import {makeProfilePredicate} from "@keeex/utils/types/record.js";
+import * as projectConfig from "@keeex/projectconfig";
+
+interface Config {
+  port: number;
+  debug: boolean;
+}
+
+const isConfig = makeProfilePredicate<Config>({
+  port: "number";
+  debug: "boolean";
+});
+
+interface Secrets {
+  login: string;
+  password: string;
+}
+
+const isSecrets = makeProfilePredicate<Secrets>({
+  login: "string";
+  password: "string";
+});
+
+const getConfig = (): Promise<projectConfig.ProjectConfig<Config, Secrets>> =>
+  projectConfig.loadConfig({
+    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:
 
-```JavaScript
-import config from "@keeex/projectconfig";
+```typescript
+import getConfig from "./services/config.js";
 
-console.log(config.something);
+const config = await getConfig();
+
+console.log(`
+Port: ${config.port}
+Debug: ${config.debug}
+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.

package/lib/index.d.ts

@@ -25,6 +25,5 @@
  * <mailto: contact@keeex.net>
  * 
  */
-import type * as types from "./types.js";
-declare const _default: types.BaseConfig;
-export default _default;
+export { loadConfig } from "./loader.js";
+export type { ProjectConfig } from "./types.js";

package/lib/index.js

@@ -25,120 +25,4 @@
  * <mailto: contact@keeex.net>
  * 
  */
-import * as nodeFs from "node:fs";
-import * as nodePath from "node:path";
-import * as env from "./env.js";
-/** Return the suffix to use, if any */
-const configSuffix = () => {
-    const suffixFromEnv = env.getConfigSuffix();
-    if (suffixFromEnv !== undefined)
-        return suffixFromEnv;
-    const nodeEnvValue = env.getNodeEnv();
-    return nodeEnvValue === "test" ? "-test" : null;
-};
-/** Suffix to use for default file name */
-const suffix = configSuffix();
-/** If a suffix is present, return both the name without and with the suffix */
-const applySuffix = (basestr) => suffix ? [`${basestr}${suffix}`, basestr] : [basestr];
-/** Basename for config file */
-const configBasename = applySuffix("config");
-/** Basename for secret file */
-const secretsBasename = applySuffix("secrets");
-/** Compute the default directories to look through */
-const getDefaultDirs = () => {
-    /** Initial directory of the app. Hopefully the project root */
-    const projectRoot = process.cwd();
-    const parentDir = nodePath.resolve(projectRoot, "..");
-    return parentDir !== projectRoot && parentDir ? [projectRoot, parentDir] : [projectRoot];
-};
-/** Directories to search for config/secrets into */
-const checkDirs = getDefaultDirs();
-/** Returns the first file found in `checkDirs`, filenames, and configured extensions */
-const getFirstFileFound = (filenames) => {
-    for (const filepath of checkDirs) {
-        for (const filename of filenames) {
-            for (const extension of [".js", ".json", ".ts", ".cjs", ".mjs", ".cts", ".mts"]) {
-                const candidate = nodePath.resolve(filepath, `${filename}${extension}`);
-                if (nodeFs.existsSync(candidate))
-                    return candidate;
-            }
-        }
-    }
-};
-/** Path to the default config file */
-const configPath = getFirstFileFound(configBasename);
-/** Path to the default secrets file */
-const secretsPath = getFirstFileFound(secretsBasename);
-const loadFile = async (path) => {
-    const fileSuffix = nodePath.extname(path);
-    if ([".js", ".ts", ".cjs", ".mjs", ".cts", ".mts"].includes(fileSuffix)) {
-        const module = (await import(path));
-        if (module.default)
-            return module.default;
-        return module;
-    }
-    if (fileSuffix === ".json")
-        return JSON.parse(await nodeFs.promises.readFile(path, "utf8"));
-    throw new Error(`Unexpected suffix: ${fileSuffix}`);
-};
-/** Return the content of a file */
-const getFromFile = async (filepath) => {
-    if (filepath === undefined)
-        return;
-    return loadFile(filepath);
-};
-/**
- * Get config from the CLI.
- *
- * Check if `--${argName}` is present, and if so, tries to interpret it as JSON or as a file path to load.
- *
- * @returns
- * The loaded content, or `null` if the argument is not present.
- */
-const getFromCli = async (argv, argName) => {
-    const configArgIndex = argv.indexOf(`--${argName}`);
-    if (configArgIndex === -1)
-        return null;
-    const valueIndex = configArgIndex + 1;
-    if (argv.length <= valueIndex)
-        throw new Error(`--${argName} requires a string argument`);
-    const value = argv[valueIndex];
-    const valuesExtracted = 2;
-    argv.splice(configArgIndex, valuesExtracted);
-    if (value.startsWith("{")) {
-        const configObj = JSON.parse(value);
-        return configObj;
-    }
-    return JSON.parse(await nodeFs.promises.readFile(value, "utf8"));
-};
-/** Return the specified object from the first available source */
-const getBaseData = async (argv, argName, filepath) => (await getFromCli(argv, argName)) ?? getFromFile(filepath);
-/** Merge the base configuration and the secrets */
-const getProjectConfig = async (argv) => {
-    const baseConfig = await getBaseData(argv, "config", configPath);
-    if (!baseConfig)
-        throw new Error("Missing base project configuration");
-    const secrets = await getBaseData(argv, "secrets", secretsPath);
-    if (secrets) {
-        const merged = { ...baseConfig, secrets };
-        return merged;
-    }
-    return baseConfig;
-};
-/** Cache of the loaded configuration */
-let config = null;
-/** Load the project configuration */
-const loadConfig = (argv) => {
-    config ??= (async () => {
-        try {
-            const cfg = await getProjectConfig(argv);
-            return cfg;
-        }
-        catch (error) {
-            config = null;
-            throw error;
-        }
-    })();
-    return config;
-};
-export default await loadConfig(process.argv);
+export { loadConfig } from "./loader.js";

package/lib/loader.d.ts

@@ -0,0 +1,31 @@
+/**
+ * @license
+ * @preserve
+ *
+ * KeeeX SAS Public code
+ * https://keeex.me
+ * Copyright 2013-2026 KeeeX All Rights Reserved.
+ * 
+ * These computer program listings and specifications, herein,
+ * are and remain the property of KeeeX SAS. The intellectual
+ * and technical concepts herein are proprietary to KeeeX SAS
+ * and may be covered by EU and foreign patents,
+ * patents in process, trade secrets and copyright law.
+ * 
+ * These listings are published as a way to provide third party
+ * with the ability to process KeeeX data.
+ * As such, support for public inquiries is limited.
+ * They are provided "as-is", without warrany of any kind.
+ * 
+ * They shall not be reproduced or copied or used in whole or
+ * in part as the basis for manufacture or sale of items unless
+ * prior written permission is obtained from KeeeX SAS.
+ * 
+ * For a license agreement, please contact:
+ * <mailto: contact@keeex.net>
+ * 
+ */
+import type * as types from "./types.js";
+/** Load the project configuration */
+export declare const loadConfig: <ConfigType, SecretsType = never>(loadingConfig?: types.ProjectLoadingConfig<ConfigType, SecretsType>) => Promise<types.ProjectConfig<ConfigType, SecretsType>>;
+export default loadConfig;

package/lib/loader.js

@@ -0,0 +1,184 @@
+/**
+ * @license
+ * @preserve
+ *
+ * KeeeX SAS Public code
+ * https://keeex.me
+ * Copyright 2013-2026 KeeeX All Rights Reserved.
+ * 
+ * These computer program listings and specifications, herein,
+ * are and remain the property of KeeeX SAS. The intellectual
+ * and technical concepts herein are proprietary to KeeeX SAS
+ * and may be covered by EU and foreign patents,
+ * patents in process, trade secrets and copyright law.
+ * 
+ * These listings are published as a way to provide third party
+ * with the ability to process KeeeX data.
+ * As such, support for public inquiries is limited.
+ * They are provided "as-is", without warrany of any kind.
+ * 
+ * They shall not be reproduced or copied or used in whole or
+ * in part as the basis for manufacture or sale of items unless
+ * prior written permission is obtained from KeeeX SAS.
+ * 
+ * For a license agreement, please contact:
+ * <mailto: contact@keeex.net>
+ * 
+ */
+import * as nodeFs from "node:fs";
+import * as nodePath from "node:path";
+import * as env from "./env.js";
+let suffixCache = null;
+/** Return the suffix to use, if any */
+const getConfigSuffix = () => {
+    if (suffixCache === null) {
+        const suffixFromEnv = env.getConfigSuffix();
+        if (suffixFromEnv === undefined) {
+            const nodeEnvValue = env.getNodeEnv();
+            suffixCache = nodeEnvValue === "test" ? "-test" : "";
+        }
+        else {
+            suffixCache = suffixFromEnv;
+        }
+    }
+    return suffixCache;
+};
+/** If a suffix is present, return both the name without and with the suffix */
+const applySuffix = (basestr) => {
+    const suffix = getConfigSuffix();
+    return suffix ? [`${basestr}${suffix}`, basestr] : [basestr];
+};
+let defaultDirsCache = null;
+/** Compute the default directories to look through */
+const getDefaultDirs = () => {
+    if (defaultDirsCache === null) {
+        /** Initial directory of the app. Hopefully the project root */
+        const projectRoot = process.cwd();
+        const parentDir = nodePath.resolve(projectRoot, "..");
+        defaultDirsCache =
+            parentDir !== projectRoot && parentDir ? [projectRoot, parentDir] : [projectRoot];
+    }
+    return defaultDirsCache;
+};
+/** Returns the first file found in `checkDirs`, filenames, and configured extensions */
+const getFirstFileFound = (filenames, candidates) => {
+    for (const filepath of getDefaultDirs()) {
+        for (const filename of filenames) {
+            for (const extension of [".js", ".json", ".ts", ".cjs", ".mjs", ".cts", ".mts"]) {
+                const candidate = nodePath.resolve(filepath, `${filename}${extension}`);
+                if (nodeFs.existsSync(candidate)) {
+                    candidates.push(`found: ${candidate}`);
+                    return candidate;
+                }
+                candidates.push(`missing: ${candidate}`);
+            }
+        }
+    }
+};
+/** Load a source/json file as a config object */
+const loadFile = async (path) => {
+    const fileSuffix = nodePath.extname(path);
+    if ([".js", ".ts", ".cjs", ".mjs", ".cts", ".mts"].includes(fileSuffix)) {
+        const module = (await import(path));
+        if (module.default)
+            return module.default;
+        return module;
+    }
+    if (fileSuffix === ".json")
+        return JSON.parse(await nodeFs.promises.readFile(path, "utf8"));
+    throw new Error(`Unexpected suffix: ${fileSuffix}`);
+};
+/** Return the content of a file, if provided, otherwise returns `null` */
+const getFromFile = async (basename, candidates) => {
+    const filepath = getFirstFileFound(applySuffix(basename), candidates);
+    if (filepath === undefined)
+        return null;
+    return loadFile(filepath);
+};
+/**
+ * Get config from the CLI.
+ *
+ * Check if `--${argName}` is present, and if so, tries to interpret it as JSON or as a file path to load.
+ *
+ * @returns
+ * The loaded content, or `null` if the argument is not present.
+ */
+const getFromCli = async (argv, argName, candidates) => {
+    const configArgIndex = argv.indexOf(`--${argName}`);
+    if (configArgIndex === -1) {
+        candidates.push(`missing: --${argName} on CLI`);
+        return null;
+    }
+    const valueIndex = configArgIndex + 1;
+    if (argv.length <= valueIndex) {
+        candidates.push(`incomplete: --${argName} on CLI requires an argument`);
+        throw new Error(`--${argName} requires a string argument`);
+    }
+    const value = argv[valueIndex];
+    const valuesExtracted = 2;
+    argv.splice(configArgIndex, valuesExtracted);
+    if (value.startsWith("{")) {
+        try {
+            return JSON.parse(value);
+        }
+        catch (error) {
+            candidates.push(`error: --${argName} JSON on CLI`);
+            throw error;
+        }
+    }
+    try {
+        return JSON.parse(await nodeFs.promises.readFile(value, "utf8"));
+    }
+    catch (error) {
+        candidates.push(`error: --${argName} as file path`);
+        throw error;
+    }
+};
+/** Return the specified object from the first available source */
+const getBaseData = async (argv, argName, candidates, predicate) => {
+    const result = (await getFromCli(argv, argName, candidates)) ?? getFromFile(argName, candidates);
+    if (predicate) {
+        try {
+            predicate(result, true);
+        }
+        catch (error) {
+            throw new Error(`Error while loading ${argName} data`, { cause: error });
+        }
+    }
+    return result;
+};
+/** Build the full configuration object on demand */
+const getProjectConfig = async (argv, loadingConfig) => {
+    const candidates = [];
+    try {
+        const baseConfig = await getBaseData(argv, "config", candidates, loadingConfig.configPredicate);
+        if (!baseConfig)
+            throw new Error("Missing base project configuration");
+        const secrets = await getBaseData(argv, "secrets", candidates, loadingConfig.secretsPredicate);
+        if (secrets) {
+            const merged = { ...baseConfig, secrets };
+            return merged;
+        }
+        return baseConfig;
+    }
+    catch (error) {
+        throw new Error(`Failure to load config (tried:${candidates.map((c) => JSON.stringify(c)).join(",")})`, { cause: error });
+    }
+};
+/** Cache of the loaded configuration */
+let configCache = null;
+const loadConfigCached = async (loadingConfig) => {
+    try {
+        return await getProjectConfig(process.argv, loadingConfig);
+    }
+    catch (error) {
+        configCache = null;
+        throw error;
+    }
+};
+/** Load the project configuration */
+export const loadConfig = (loadingConfig) => {
+    configCache ??= loadConfigCached(loadingConfig ?? {});
+    return configCache;
+};
+export default loadConfig;

package/lib/types.d.ts

@@ -27,3 +27,16 @@
  */
 /** Base for any returned configuration */
 export type BaseConfig = Record<string, any>;
+/** Generic type predicate */
+export type TypePredicate<Type> = (obj: unknown, throwOnError?: boolean) => obj is Type;
+export interface ProjectLoadingConfig<ConfigType, SecretsType = never> {
+    /** Type predicate for the base configuration (without secrets) */
+    configPredicate?: TypePredicate<ConfigType>;
+    /** Type predicate for the secrets only */
+    secretsPredicate?: SecretsType extends never ? never : TypePredicate<SecretsType>;
+}
+export type ProjectConfig<ConfigType, SecretsType = never> = SecretsType extends never ? ConfigType : {
+    [key in keyof ConfigType]: ConfigType[key];
+} & {
+    secrets: SecretsType;
+};

package/package.json

@@ -1 +1 @@
-{"name":"@keeex/projectconfig","version":"4.2.1","description":"Load project configuration with separate secrets","main":"./lib/index.js","scripts":{},"type":"module","author":"KeeeX SAS","contributors":[{"email":"gabriel@keeex.net","name":"Gabriel Paul \"Cley Faye\" Risterucci"}],"license":"SEE LICENSE IN LICENSE","files":["lib"],"exports":{".":"./lib/index.js","./env.js":"./lib/env.js","./index.js":"./lib/index.js","./lib/env.js":"./lib/env.js","./lib/index.js":"./lib/index.js","./lib/types.js":"./lib/types.js","./types.js":"./lib/types.js"},"homepage":"https://keeex.me/oss"}
+{"name":"@keeex/projectconfig","version":"5.0.1","description":"Load project configuration with separate secrets","main":"./lib/index.js","scripts":{},"type":"module","author":"KeeeX SAS","contributors":[{"email":"gabriel@keeex.net","name":"Gabriel Paul \"Cley Faye\" Risterucci"}],"license":"SEE LICENSE IN LICENSE","files":["lib"],"exports":{".":"./lib/index.js","./env.js":"./lib/env.js","./index.js":"./lib/index.js","./lib/env.js":"./lib/env.js","./lib/index.js":"./lib/index.js","./lib/loader.js":"./lib/loader.js","./lib/types.js":"./lib/types.js","./loader.js":"./lib/loader.js","./types.js":"./lib/types.js"},"homepage":"https://keeex.me/oss"}