@keeex/projectconfig 6.0.1 → 7.0.0

package/README.md

@@ -72,6 +72,97 @@ For secrets, the argument would be `--secrets.db.user` for `config.secrets.db.us
 
 ### Accessing the configuration
 
+#### Automatic singleton
+
+The recommended way to load configuration is by generating a singleton.
+This allows asynchronous loading of the configuration on demand, but convenient synchronous access to the loaded object.
+
+```typescript
+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 singleton = getConfigSingleton({
+  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 const loadConfig = singleton.loadConfig;
+export const config = singleton.config;
+```
+
+In the above exemple, we define a module that export both the loading function and the fully-typed configuration, to be used throughout a project.
+
+You have to manually load the configuration, usually during your application initialization:
+
+```typescript
+import {loadConfig} from "./services/config.js";
+
+await loadConfig();
+```
+
+Then, using the configuration would look something like this:
+
+```typescript
+import {config} from "./services/config.js";
+
+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 loading call, so it is safe to recall this function multiple times from multiple places if needed.
+Accessing the `config` object before calling `loadConfig()` will raise an exception.
+
+#### Manual loading
+
 The loaded configuration can be obtained by calling the function `loadConfig()`.
 
 ```typescript
@@ -149,3 +240,11 @@ 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.
+
+## Migration guide
+
+### From 6.x to 7.x
+
+- The config definition property `secretEnvironmentVars` is renamed to `secretsEnvironmentVars`
+- The default genericity value for `SecretsType` changed from `never` to `undefined`
+- Configuration now have two sets of generic types, `ConfigType` and `SecretsType` are loaded as before, but additionally `TypedConfigType` and `TypedSecretsType` can be provided in conjunction with the `convert` property on the configuration definition object to move from the fully loaded configuration to a custom typed loaded configuration.

package/lib/index.d.ts

@@ -26,4 +26,6 @@
  * 
  */
 export { loadConfig } from "./services/loader.js";
-export type { ProjectConfig, TypeForEnv } from "./services/types.js";
+export { TypeForEnv } from "./services/types.js";
+export type { ProjectConfig, ConvertFunc } from "./services/types.js";
+export { getConfigSingleton } from "./services/singleton.js";

package/lib/index.js

@@ -26,3 +26,5 @@
  * 
  */
 export { loadConfig } from "./services/loader.js";
+export { TypeForEnv } from "./services/types.js";
+export { getConfigSingleton } from "./services/singleton.js";

package/lib/services/cli.d.ts

@@ -1,30 +1,30 @@
 /**
- * @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>
- * 
- */
+* @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";
 import type { JSONObject } from "@keeex/utils/json.js";
 /**

package/lib/services/file.d.ts

@@ -1,30 +1,30 @@
 /**
- * @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>
- * 
- */
+* @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 envSrv from "./env.js";
 import type * as types from "./types.js";
 import type { JSONObject } from "@keeex/utils/json.js";

package/lib/services/loader.d.ts

@@ -1,30 +1,30 @@
 /**
- * @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>
- * 
- */
+* @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 envSrv from "./env.js";
 import * as types from "./types.js";
 /**
@@ -40,7 +40,7 @@ import * as types from "./types.js";
  * @returns
  * The config object (cached, if applicable)
  */
-export declare const loadConfig: <ConfigType, SecretsType = never>(loadingConfig?: types.ProjectLoadingConfig<ConfigType, SecretsType>, argv?: Array<string>, env?: envSrv.SysEnv) => Promise<types.ProjectConfig<ConfigType, SecretsType>>;
+export declare const loadConfig: <ConfigType, SecretsType = undefined, TypedConfigType = ConfigType, TypedSecretsType = SecretsType>(loadingConfig?: types.ProjectLoadingConfig<ConfigType, SecretsType, TypedConfigType, TypedSecretsType>, argv?: Array<string>, env?: envSrv.SysEnv) => Promise<types.ProjectConfig<TypedConfigType, TypedSecretsType>>;
 /**
  * Internal function used for testing purpose.
  *

package/lib/services/loader.js

@@ -26,6 +26,7 @@
  * 
  */
 import * as nodeFs from "node:fs";
+import * as nodePath from "node:path";
 import { asError } from "@keeex/utils/error.js";
 import * as utilsJson from "../utils/json.js";
 import * as cliSrv from "./cli.js";
@@ -82,15 +83,37 @@ const getFromCliArgs = async (argv, baseDataConfig) => {
     const fromCliFile = (propPath) => cliSrv.getCfgValue(argv, baseDataConfig.argType, propPath, true);
     return getFromRecords(baseDataConfig, fromCliDirect, fromCliFile, "CLIARGS");
 };
+const getFromIndividualFiles = async (baseDataConfig) => {
+    const fileValues = baseDataConfig.fileValues;
+    if (!fileValues)
+        return null;
+    let res = {};
+    await Promise.all(Object.entries(fileValues.files).map(async ([filename, prop]) => {
+        const filepath = nodePath.resolve(fileValues.baseDirectory, filename);
+        if (!nodeFs.existsSync(filepath))
+            return;
+        const content = (await nodeFs.promises.readFile(filepath, "utf8")).trim();
+        const parsedContent = envSrv.parseValueFromEnvString(content, prop.type);
+        if (typeof prop.target === "string") {
+            utilsJson.setPathValue(res, prop.target, parsedContent);
+        }
+        else {
+            const temp = await prop.target(parsedContent);
+            res = utilsJson.mergeJsonDeep(res, temp);
+        }
+    }));
+    return res;
+};
 /** Build the specific object based on the available sources */
 const getBaseData = async (argv, env, baseDataConfig) => {
-    const [fromFile, fromEnv, fromCliBase, fromCliArgs] = await Promise.all([
+    const [fromFile, fromIndividualFiles, fromEnv, fromCliBase, fromCliArgs] = await Promise.all([
         getFromFile(env, baseDataConfig),
+        getFromIndividualFiles(baseDataConfig),
         getFromEnv(env, baseDataConfig),
         cliSrv.getFromCliBase(argv, baseDataConfig),
         getFromCliArgs(argv, baseDataConfig),
     ]);
-    const result = utilsJson.mergeJsonDeep(baseDataConfig.defaultValues, fromFile, fromEnv, fromCliBase, fromCliArgs);
+    const result = utilsJson.mergeJsonDeep(baseDataConfig.defaultValues, fromFile, fromIndividualFiles, fromEnv, fromCliBase, fromCliArgs);
     try {
         baseDataConfig.predicate?.(result, true);
     }
@@ -115,15 +138,16 @@ const getProjectConfig = async (argv, env, loadingConfig) => {
         const secrets = await getBaseData(argv, env, {
             argType: types.ArgType.secrets,
             defaultValues: loadingConfig.secretsDefault ?? {},
-            environmentValues: loadingConfig.secretEnvironmentVars ?? {},
+            environmentValues: loadingConfig.secretsEnvironmentVars ?? {},
+            fileValues: loadingConfig.secretFiles,
             loadedFrom,
             predicate: loadingConfig.secretsPredicate,
         });
-        if (secrets) {
-            const merged = { ...baseConfig, secrets };
-            return merged;
+        const merged = (secrets ? { ...baseConfig, secrets } : baseConfig);
+        if (loadingConfig.convert) {
+            return await loadingConfig.convert(merged);
         }
-        return baseConfig;
+        return merged;
     }
     catch (error) {
         throw new Error(`Failure to load config (tried:${loadedFrom.map((c) => JSON.stringify(c)).join(",")})`, { cause: error });
@@ -157,8 +181,9 @@ export const loadConfig = (loadingConfig, argv, env) => {
     const realArgv = argv ?? process.argv;
     const realEnv = env ?? process.env;
     const realConfig = loadingConfig ?? {};
-    if (argv || env)
+    if (argv || env) {
         return getProjectConfig(realArgv, realEnv, realConfig);
+    }
     configCache ??= loadConfigCached(realConfig, realArgv, realEnv);
     return configCache;
 };

package/lib/services/singleton.d.ts

@@ -0,0 +1,34 @@
+/**
+ * @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";
+interface ConfigSingleton<ConfigType, SecretsType> {
+    loadConfig: () => Promise<void>;
+    config: types.ProjectConfig<ConfigType, SecretsType>;
+}
+export declare const getConfigSingleton: <ConfigType extends object, SecretsType = undefined, TypedConfigType = ConfigType, TypedSecretsType = SecretsType>(params: types.ProjectLoadingConfig<ConfigType, SecretsType, TypedConfigType, TypedSecretsType>) => ConfigSingleton<TypedConfigType, TypedSecretsType>;
+export {};

package/lib/services/singleton.js

@@ -0,0 +1,63 @@
+/**
+ * @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 loader from "./loader.js";
+export const getConfigSingleton = (params) => {
+    let loadedConfig = null;
+    let loadConfigCache = null;
+    /**
+     * Load the project configuration.
+     *
+     * This function can be called multiple time, only one loading will occur.
+     */
+    const loadConfig = () => {
+        loadConfigCache ??= (async () => {
+            try {
+                loadedConfig = await loader.loadConfig(params);
+            }
+            catch (error) {
+                loadConfigCache = null;
+                throw error;
+            }
+        })();
+        return loadConfigCache;
+    };
+    /**
+     * Access the configuration object when loaded.
+     *
+     * Trying to read a property on this object before loading the configuration will raise an
+     * exception.
+     */
+    const config = new Proxy({}, {
+        get: (_target, prop) => {
+            if (loadedConfig === null)
+                throw new Error("Configuration was not loaded");
+            return loadedConfig[prop];
+        },
+    });
+    return { config: config, loadConfig };
+};

package/lib/services/types.d.ts

@@ -25,7 +25,8 @@
  * <mailto: contact@keeex.net>
  * 
  */
-import type { TypePredicate } from "@keeex/utils/types/types.js";
+import { type JSONObject } from "@keeex/utils/json.js";
+import type * as utilsTypes from "@keeex/utils/types/types.js";
 export type BaseConfig = Record<string, any>;
 /** Separate config from secret inputs */
 export declare enum ArgType {
@@ -46,24 +47,90 @@ export interface BaseDataConfig<Type> {
     argType: ArgType | string;
     defaultValues: DeepPartial<Type>;
     environmentValues: EnvVarsList;
+    fileValues?: SecretFiles;
     loadedFrom: Array<string>;
-    predicate?: TypePredicate<Type>;
+    predicate?: utilsTypes.TypePredicate<Type>;
 }
-export interface ProjectLoadingConfig<ConfigType, SecretsType = never> {
+export type ConvertFunc<ConfigType, SecretsType, TypedConfigType, TypedSecretsType> = (raw: ProjectConfig<ConfigType, SecretsType>) => utilsTypes.Awaitable<ProjectConfig<TypedConfigType, TypedSecretsType>>;
+export type SecretTransform<InType> = (input: InType) => utilsTypes.Awaitable<JSONObject>;
+/** Definition of a single file to load a secret from */
+interface SecretFileString {
+    /** Will parse the file as if read from an environment variable */
+    type: TypeForEnv.string;
+    /**
+     * If a function return a JSON object to merge with secrets.
+     *
+     * If a string, the path to a property to fill.
+     */
+    target: SecretTransform<string> | string;
+}
+interface SecretFileBoolean {
+    /** Will parse the file as if read from an environment variable */
+    type: TypeForEnv.boolean;
+    /**
+     * If a function return a JSON object to merge with secrets.
+     *
+     * If a string, the path to a property to fill.
+     */
+    target: SecretTransform<boolean> | string;
+}
+interface SecretFileNumber {
+    /** Will parse the file as if read from an environment variable */
+    type: TypeForEnv.number;
+    /**
+     * If a function return a JSON object to merge with secrets.
+     *
+     * If a string, the path to a property to fill.
+     */
+    target: SecretTransform<number> | string;
+}
+interface SecretFileJson {
+    /** Will parse the file as if read from an environment variable */
+    type: TypeForEnv.json;
+    /**
+     * If a function return a JSON object to merge with secrets.
+     *
+     * If a string, the path to a property to fill.
+     */
+    target: SecretTransform<JSONObject> | string;
+}
+type SecretFile = SecretFileString | SecretFileBoolean | SecretFileNumber | SecretFileJson;
+/** Definition of files to load secrets from */
+interface SecretFiles {
+    baseDirectory: string;
+    files: Record<string, SecretFile>;
+}
+export interface ProjectLoadingConfig<ConfigType, SecretsType = undefined, TypedConfigType = ConfigType, TypedSecretsType = SecretsType> {
     /** Default values to be used as the base of all configs */
     configDefault?: DeepPartial<ConfigType>;
     /** List properties that can be read from environment variables for the config */
     configEnvironmentVars?: EnvVarsList;
-    /** Type predicate for the base configuration (without secrets) */
-    configPredicate?: TypePredicate<ConfigType>;
+    /**
+     * Type predicate for the base configuration (without secrets).
+     *
+     * Note that this applies to the loaded secret, regardless of the behavior of the `convert`
+     * function.
+     */
+    configPredicate?: utilsTypes.TypePredicate<ConfigType>;
+    /** Convert from the raw types to custom types */
+    convert?: ConvertFunc<ConfigType, SecretsType, TypedConfigType, TypedSecretsType>;
     /** Default values to be used as the base of all secrets */
     secretsDefault?: DeepPartial<SecretsType>;
     /** List properties that can be read from environment variables for the secret */
-    secretEnvironmentVars?: EnvVarsList;
-    /** Type predicate for the secrets only */
-    secretsPredicate?: SecretsType extends never ? never : TypePredicate<SecretsType>;
+    secretsEnvironmentVars?: EnvVarsList;
+    /** Load from files in a specific directory */
+    secretFiles?: SecretFiles;
+    /**
+     * Type predicate for the secrets only.
+     *
+     * Note that this applies to the loaded secret, regardless of the behavior of the `convert`
+     * function.
+     */
+    secretsPredicate?: SecretsType extends never ? never : utilsTypes.TypePredicate<SecretsType>;
 }
-export type ProjectConfig<ConfigType, SecretsType = never> = SecretsType extends never ? ConfigType : {
+export type ProjectConfig<ConfigType, SecretsType = undefined> = SecretsType extends undefined ? {
+    [key in keyof ConfigType]: ConfigType[key];
+} : {
     [key in keyof ConfigType]: ConfigType[key];
 } & {
     secrets: SecretsType;

package/package.json

@@ -1 +1 @@
-{"name":"@keeex/projectconfig","version":"6.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","./index.js":"./lib/index.js"},"dependencies":{"@keeex/utils":"^7.6.2","@keeex/utils-node":"^6.8.2"},"homepage":"https://keeex.me/oss"}
+{"name":"@keeex/projectconfig","version":"7.0.0","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","./index.js":"./lib/index.js"},"dependencies":{"@keeex/utils":"^7.6.2","@keeex/utils-node":"^6.9.2"},"allowScripts":{"@swc/core@1.15.41":true,"unrs-resolver":false},"homepage":"https://keeex.me/oss"}