@freemework/common
Version:
Common library of the Freemework Project.
263 lines (262 loc) • 10.1 kB
TypeScript
import { FConfigurationValue } from "./f_configuration_value.js";
/**
* The `FConfiguration` provides contract to access key-value configuration sources
*/
export declare abstract class FConfiguration {
/**
* Construct configuration from json object
*
* Complex json object expands into plain dictionary of key-values.
*
* @example
* ```js
* const config: FConfiguration = FConfiguration.factoryJson({ a: { b: { c: 42 } } });
* assert.equal(config.get("a.b.c").asInteger, 42);
* ```
*
* @example
* ```js
* const config: FConfiguration = FConfiguration.factoryJson({ a: { b: [ { c: 40 }, { c: 41 }, { c: 42 } ] } });
*
* assert.equal(config.get("a.b.0.c").asString, "40");
* assert.equal(config.get("a.b.1.c").asString, "41");
* assert.equal(config.get("a.b.2.c").asString, "42");
*
* const array: ReadonlyArray<FConfiguration> = config.getArray("a.b");
* assert.equal(array.length, 3);
* assert.equal(array[0].get("c").asInteger, 40);
* assert.equal(array[1].get("c").asInteger, 41);
* assert.equal(array[2].get("c").asInteger, 42);
* ```
*/
static factoryJson(jsonObject: any, indexFieldName?: string): FConfiguration;
protected static readonly DEFAULT_INDEXES_KEY: string;
protected static readonly DEFAULT_INDEX_KEY: string;
/**
* Gets configuration source URI.
*
* @remarks This value mostly need to debug purposes to understand source of a value.
*
* @see https://docs.freemework.org/configuration/FConfiguration#sourceURI?lang=typescript
*
* Each configuration source should represents an URI.
* For example:
* - configuration+file+properies:///path/to/file.properies
* - configuration+file+ini:///path/to/file.ini
* - configuration+file+json:///path/to/file.json
* - configuration+file+toml:///path/to/file.toml
* - configuration+file+yaml:///path/to/file.yml
* - configuration+consul://my.consul.host:????
* - configuration+redis://my.redis.host:6379/1
* - configuration+directory+keyperfile:///run/secrets
* - configuration:json?data=%7B%22a%22%3A42%7D
* - configuration:properies?data=...
* - configuration:toml?data=...
* - configuration:chain?sources=configuration:env,configuration%3Ajson%3Fdata%3D...,...
* - configuration:env
* - etc.
*/
abstract get sourceURI(): URL;
/**
* Gets fully qualified configuration namespace name
*
* @example
* ```js
* const appCfg = FConfiguration.factoryJson({
* "runtime.server.ONE.listenAddress": "localhost",
* "runtime.server.ONE.listenPort": "8081",
* "runtime.server.TWO.listenAddress": "localhost",
* "runtime.server.TWO.listenPort": "8082",
* });
*
* console.log(appCfg.namespaceFull); // null
*
* const runtimeCfg = appCfg.getNamespace("runtime");
* console.log(runtimeCfg.namespaceFull); // "runtime"
*
* const serverTwoCfg = runtimeCfg.getNamespace("server.TWO");
* console.log(serverTwoCfg.namespaceFull); // "runtime.server.TWO"
* ```
*/
abstract get namespaceFull(): string | null;
/**
* Gets parent configuration namespace name
*
* @example
* ```js
* const appCfg = FConfiguration.factoryJson({
* "runtime.server.ONE.listenAddress": "localhost",
* "runtime.server.ONE.listenPort": "8081",
* "runtime.server.TWO.listenAddress": "localhost",
* "runtime.server.TWO.listenPort": "8082",
* });
*
* console.log(appCfg.namespaceParent); // null
*
* const runtimeCfg = appCfg.getNamespace("runtime");
* console.log(runtimeCfg.namespaceParent); // "runtime"
*
* const serverTwoCfg = runtimeCfg.getNamespace("server.TWO");
* console.log(serverTwoCfg.namespaceParent); // "TWO"
* ```
*/
abstract get namespaceParent(): string | null;
/**
* Gets list of keys available in current configuration
*
* @example
* ```js
* const appCfg = FConfiguration.factoryJson({
* "runtime.server.ONE.listenAddress": "localhost",
* "runtime.server.ONE.listenPort": "8081",
* "runtime.server.TWO.listenAddress": "localhost",
* "runtime.server.TWO.listenPort": "8082",
* });
*
* console.log(appCfg.keys); // ["runtime.server.ONE.listenAddress", "runtime.server.ONE.listenPort", "runtime.server.TWO.listenAddress", "runtime.server.TWO.listenPort"]
*
* const runtimeCfg = appCfg.getNamespace("runtime");
* console.log(runtimeCfg.keys); // ["server.ONE.listenAddress", "server.ONE.listenPort", "server.TWO.listenAddress", "server.TWO.listenPort"]
*
* const serverTwoCfg = appCfg.getNamespace("runtime.server.TWO");
* console.log(serverTwoCfg.keys); // ["listenAddress","listenPort"]
* ```
*/
abstract get keys(): ReadonlyArray<string>;
/**
* Obtain array of sub-configurations
*
* @param key Name of array key
* @param indexesName Name of indexes key. Default: "indexes".
*
* @example
* ```js
* const appCfg = FConfiguration.factoryJson({
* "runtime.server.ONE.listenAddress": "localhost",
* "runtime.server.ONE.listenPort": "8081",
* "runtime.server.TWO.listenAddress": "localhost",
* "runtime.server.TWO.listenPort": "8082",
* "runtime.server.THREE.listenAddress": "localhost",
* "runtime.server.THREE.listenPort": "8083",
* "runtime.server.indexes": "ONE THREE",
* });
*
* const runtimeCfg = appCfg.getNamespace("runtime");
* const serverCfgs = runtimeCfg.getArray("server", "indexes");
*
* console.log(serverCfgs.length); // 2
*
* console.log(serverCfgs[0].keys); // ["listenAddress","listenPort"]
* console.log(serverCfgs[1].keys); // ["listenAddress","listenPort"]
*
* console.log(serverCfgs[0].namespaceFull); // runtime.server.ONE
* console.log(serverCfgs[0].get("listenAddress").asString); // localhost
* console.log(serverCfgs[0].get("listenPort").asInteger); // 8081
*
* console.log(serverCfgs[1].namespaceFull); // runtime.server.THREE
* console.log(serverCfgs[1].get("listenAddress").asString); // localhost
* console.log(serverCfgs[1].get("listenPort").asInteger); // 8083
* ```
*/
abstract getArray(key: string, indexesName?: string): Array<FConfiguration>;
/**
* Get inner configuration for specific namespace.
*
* @throw `FConfigurationException` if no specific namespace found
* @returns Inner configuration
*
* @example
* ```js
* const appCfg = FConfiguration.factoryJson({
* "runtime.server.ONE.listenAddress": "localhost",
* "runtime.server.ONE.listenPort": "8081",
* "runtime.server.TWO.listenAddress": "localhost",
* "runtime.server.TWO.listenPort": "8082",
* });
*
* console.log(appCfg.namespaceFull); // ""
*
* const runtimeCfg = appCfg.getNamespace("runtime");
* console.log(runtimeCfg.namespaceFull); // "runtime"
*
* const serverTwoCfg = runtimeCfg.getNamespace("server.TWO");
* console.log(serverTwoCfg.namespaceFull); // "runtime.server.TWO"
* ```
*/
abstract getNamespace(namespaceFull: string): FConfiguration;
/**
* @throws `FConfigurationException` if the `key` not found and no `defaultData` provided
*/
abstract get(key: string, defaultData?: string | null): FConfigurationValue;
/**
* Find inner configuration for specific namespace.
*
* @returns Inner configuration or `null` if no specific namespace found
*
* @example
* ```js
* const appCfg = FConfiguration.factoryJson({
* "runtime.server.ONE.listenAddress": "localhost",
* "runtime.server.ONE.listenPort": "8081",
* "runtime.server.TWO.listenAddress": "localhost",
* "runtime.server.TWO.listenPort": "8082",
* });
*
* const setupCfg = appCfg.findNamespace("setup");
* console.log(setupCfg === null); // true
*
* const runtimeCfg = appCfg.findNamespace("runtime");
* console.log(runtimeCfg !== null); // true
* ```
*/
abstract findNamespace(namespaceFull: string): FConfiguration | null;
abstract find(key: string): FConfigurationValue | null;
abstract hasNamespace(namespaceFull: string): boolean;
/**
* Checks whether key is presented in current configuration
*
* @param key Name of key
* @returns `true` is the key is presented, otherwise `false`
*
* @example
* ```js
* const appCfg = FConfiguration.factoryJson({
* "runtime.port": "8080",
* "runtime.loglevel": "DEBUG",
* });
*
* const runtimeCfg = appCfg.getNamespace("runtime");
* const isLogLevelPresented = runtimeCfg.has("loglevel")
*
* console.log(isLogLevelPresented); // true
* ```
*/
abstract has(key: string): boolean;
toDynamicView(opts?: {
readonly strict: boolean;
}): any;
}
export declare class FConfigurationDictionary extends FConfiguration {
private static readonly NAMESPACE_DELIMITER_SYMBOL;
private readonly _dict;
private readonly _sourceURI;
private readonly _configurationNamespace;
private _keys;
constructor(sourceURI: URL, dict: FConfigurationDictionary.Data, namespaceFull?: string);
get namespaceFull(): string | null;
get namespaceParent(): string | null;
get keys(): ReadonlyArray<string>;
get sourceURI(): URL;
findNamespace(_: string): FConfiguration | null;
find(key: string): FConfigurationValue | null;
getNamespace(namespaceFull: string): FConfiguration;
get(key: string, defaultData?: string | null): FConfigurationValue;
getArray(key: string, indexesName?: string): Array<FConfiguration>;
hasNamespace(namespaceFull: string): boolean;
has(key: string): boolean;
}
export declare namespace FConfigurationDictionary {
type Data = {
readonly [key: string]: string | null;
};
}