@pryv/boiler 1.2.5 → 1.2.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pryv/boiler",
-  "version": "1.2.5",
+  "version": "1.2.6",
   "private": false,
   "description": "Logging and config boilerplate library for Node.js apps and services at Pryv",
   "keywords": [

package/src/index.d.ts

@@ -3,208 +3,222 @@
  * [BSD-3-Clause](https://github.com/pryv/pryv-boiler/blob/master/LICENSE)
  */
 
-export = boiler;
+// ----- Exported Types (for ESM: import type { Config, Logger } from '@pryv/boiler') -----
+
+export interface InitOptions {
+  /** The name of the application, used by Logger and debug */
+  appName: string;
+  /** Directory to use to look for configs (default, env) */
+  baseConfigDir?: string;
+  /** Directory to use for `file://` relative paths */
+  baseFilesDir?: string;
+  /** Array of extra config sources to load */
+  extraConfigs?: Array<ConfigFile | ConfigPlugin | ConfigPluginAsync | ConfigData | ConfigRemoteURL | ConfigRemoteURLFromKey | ConfigFileAsync>;
+}
+
+export interface ConfigFile {
+  /** Scope for nconf hierarchical load */
+  scope: string;
+  /** The config file path (.yml, .json, .js) */
+  file: string;
+}
+
+export interface ConfigFileAsync {
+  /** Scope for nconf hierarchical load */
+  scope: string;
+  /** The async config file path (.js that exports an async function) */
+  fileAsync: string;
+}
+
+export interface ConfigPlugin {
+  plugin: {
+    /** Function that takes the Config instance and returns the plugin name */
+    load: (config: Config) => string;
+  };
+}
+
+export interface ConfigPluginAsync {
+  pluginAsync: {
+    /** Async function that takes the Config instance and returns the plugin name */
+    load: (config: Config) => Promise<string>;
+  };
+}
+
+export interface ConfigData {
+  /** Scope for nconf hierarchical load */
+  scope: string;
+  /** Key to load data under. If null, loaded at root of the config */
+  key?: string;
+  /** The data to load */
+  data: object;
+}
+
+export interface ConfigRemoteURL {
+  /** Scope for nconf hierarchical load */
+  scope: string;
+  /** Key to load result of URL under. If null, loaded at root of the config */
+  key?: string;
+  /** The URL to the config definition */
+  url: string;
+}
+
+export interface ConfigRemoteURLFromKey {
+  /** Scope for nconf hierarchical load */
+  scope: string;
+  /** Key to load result of URL under. If null, override */
+  key?: string;
+  /** Retrieve URL from config matching this key */
+  urlFromKey: string;
+}
+
+export interface ScopeAndValue {
+  value: unknown;
+  scope: string;
+  info: string;
+}
+
+/** Type alias for extra config entries */
+export type ExtraConfig = ConfigFile | ConfigPlugin | ConfigPluginAsync | ConfigData | ConfigRemoteURL | ConfigRemoteURLFromKey | ConfigFileAsync;
+
+export interface Config {
+  /** The nconf store instance */
+  store: unknown;
+  /** The logger instance for config */
+  logger: Logger;
+  /** Base directory for config files */
+  baseConfigDir: string;
+
+  /**
+   * Return true if key has a value
+   * @param key - The config key to check
+   */
+  has(key: string): boolean;
+
+  /**
+   * Retrieve value
+   * @param key - The config key. If no key is provided, all the config is returned
+   */
+  get(key?: string): unknown;
+  get<T>(key: string): T;
 
-declare const boiler: {
+  /**
+   * Retrieve value and store info that applies
+   * @param key - The config key
+   */
+  getScopeAndValue(key: string): ScopeAndValue | null;
+
+  /**
+   * Set value
+   * @param key - The config key
+   * @param value - The value to set
+   */
+  set(key: string, value: unknown): void;
+
+  /**
+   * Inject test config and override any other option
+   * @param configObject - The config object to inject for testing
+   */
+  injectTestConfig(configObject: object): void;
+
+  /**
+   * Replace a scope config set
+   * @param scope - The scope to replace
+   * @param configObject - The new config object for the scope
+   */
+  replaceScopeConfig(scope: string, configObject: object): void;
+}
+
+export interface Logger {
+  /** The name of this logger */
+  name: string;
+  /** The parent logger, if any */
+  parent: Logger | null;
+
+  /**
+   * Log a message at the specified level
+   * @param level - The log level
+   * @param message - The log message
+   * @param context - Additional context
+   */
+  log(level: string, message: string, ...context: unknown[]): void;
+
+  /**
+   * Log an info message
+   * @param message - The log message
+   * @param context - Additional context
+   */
+  info(message: string, ...context: unknown[]): void;
+
+  /**
+   * Log a warning message
+   * @param message - The log message
+   * @param context - Additional context
+   */
+  warn(message: string, ...context: unknown[]): void;
+
+  /**
+   * Log an error message
+   * @param message - The log message
+   * @param context - Additional context
+   */
+  error(message: string, ...context: unknown[]): void;
+
+  /**
+   * Log a debug message
+   * @param message - The log message
+   * @param context - Additional context
+   */
+  debug(message: string, ...context: unknown[]): void;
+
+  /**
+   * Get a "sub" Logger
+   * @param name - The name of the child logger
+   */
+  getLogger(name: string): Logger;
+
+  /**
+   * Dump objects with file and line for debugging
+   */
+  inspect(...args: unknown[]): void;
+}
+
+/** The Boiler instance type (returned by init()) */
+export interface Boiler {
   /**
    * Get a Logger
    * @param name - The name of the logger
    */
-  getLogger: (name?: string) => boiler.Logger;
+  getLogger: (name?: string) => Logger;
 
   /**
    * Preferred way to get the configuration.
    * Waits until the configuration is fully initialized.
    */
-  getConfig: () => Promise<boiler.Config>;
+  getConfig: () => Promise<Config>;
 
   /**
    * Get the configuration.
    * If the configuration is not fully initialized, throws an error (or warns if warnOnly is true).
    * @param warnOnly - Only warns about potential misuse of config instead of throwing
    */
-  getConfigUnsafe: (warnOnly?: boolean) => boiler.Config;
+  getConfigUnsafe: (warnOnly?: boolean) => Config;
 
   /**
    * Initialize Boiler. Should be called just once when starting an app.
    * @param options - Initialization options
    * @param fullyLoadedCallback - Called when the config is fully loaded
    */
-  init: (options: boiler.InitOptions, fullyLoadedCallback?: (config: boiler.Config) => void) => typeof boiler;
-};
-
-declare namespace boiler {
-  interface InitOptions {
-    /** The name of the application, used by Logger and debug */
-    appName: string;
-    /** Directory to use to look for configs (default, env) */
-    baseConfigDir?: string;
-    /** Directory to use for `file://` relative paths */
-    baseFilesDir?: string;
-    /** Array of extra config sources to load */
-    extraConfigs?: Array<ConfigFile | ConfigPlugin | ConfigPluginAsync | ConfigData | ConfigRemoteURL | ConfigRemoteURLFromKey | ConfigFileAsync>;
-  }
-
-  interface ConfigFile {
-    /** Scope for nconf hierarchical load */
-    scope: string;
-    /** The config file path (.yml, .json, .js) */
-    file: string;
-  }
-
-  interface ConfigFileAsync {
-    /** Scope for nconf hierarchical load */
-    scope: string;
-    /** The async config file path (.js that exports an async function) */
-    fileAsync: string;
-  }
-
-  interface ConfigPlugin {
-    plugin: {
-      /** Function that takes the Config instance and returns the plugin name */
-      load: (config: Config) => string;
-    };
-  }
-
-  interface ConfigPluginAsync {
-    pluginAsync: {
-      /** Async function that takes the Config instance and returns the plugin name */
-      load: (config: Config) => Promise<string>;
-    };
-  }
-
-  interface ConfigData {
-    /** Scope for nconf hierarchical load */
-    scope: string;
-    /** Key to load data under. If null, loaded at root of the config */
-    key?: string;
-    /** The data to load */
-    data: object;
-  }
-
-  interface ConfigRemoteURL {
-    /** Scope for nconf hierarchical load */
-    scope: string;
-    /** Key to load result of URL under. If null, loaded at root of the config */
-    key?: string;
-    /** The URL to the config definition */
-    url: string;
-  }
-
-  interface ConfigRemoteURLFromKey {
-    /** Scope for nconf hierarchical load */
-    scope: string;
-    /** Key to load result of URL under. If null, override */
-    key?: string;
-    /** Retrieve URL from config matching this key */
-    urlFromKey: string;
-  }
-
-  interface ScopeAndValue {
-    value: unknown;
-    scope: string;
-    info: string;
-  }
-
-  class Config {
-    /** The nconf store instance */
-    store: unknown;
-    /** The logger instance for config */
-    logger: Logger;
-    /** Base directory for config files */
-    baseConfigDir: string;
-
-    /**
-     * Return true if key has a value
-     * @param key - The config key to check
-     */
-    has(key: string): boolean;
-
-    /**
-     * Retrieve value
-     * @param key - The config key. If no key is provided, all the config is returned
-     */
-    get(key?: string): unknown;
-    get<T>(key: string): T | undefined;
-
-    /**
-     * Retrieve value and store info that applies
-     * @param key - The config key
-     */
-    getScopeAndValue(key: string): ScopeAndValue | null;
-
-    /**
-     * Set value
-     * @param key - The config key
-     * @param value - The value to set
-     */
-    set(key: string, value: unknown): void;
-
-    /**
-     * Inject test config and override any other option
-     * @param configObject - The config object to inject for testing
-     */
-    injectTestConfig(configObject: object): void;
-
-    /**
-     * Replace a scope config set
-     * @param scope - The scope to replace
-     * @param configObject - The new config object for the scope
-     */
-    replaceScopeConfig(scope: string, configObject: object): void;
-  }
-
-  class Logger {
-    /** The name of this logger */
-    name: string;
-    /** The parent logger, if any */
-    parent: Logger | null;
-
-    /**
-     * Log a message at the specified level
-     * @param level - The log level
-     * @param message - The log message
-     * @param context - Additional context
-     */
-    log(level: string, message: string, ...context: unknown[]): void;
-
-    /**
-     * Log an info message
-     * @param message - The log message
-     * @param context - Additional context
-     */
-    info(message: string, ...context: unknown[]): void;
-
-    /**
-     * Log a warning message
-     * @param message - The log message
-     * @param context - Additional context
-     */
-    warn(message: string, ...context: unknown[]): void;
-
-    /**
-     * Log an error message
-     * @param message - The log message
-     * @param context - Additional context
-     */
-    error(message: string, ...context: unknown[]): void;
-
-    /**
-     * Log a debug message
-     * @param message - The log message
-     * @param context - Additional context
-     */
-    debug(message: string, ...context: unknown[]): void;
-
-    /**
-     * Get a "sub" Logger
-     * @param name - The name of the child logger
-     */
-    getLogger(name: string): Logger;
-
-    /**
-     * Dump objects with file and line for debugging
-     */
-    inspect(...args: unknown[]): void;
-  }
+  init: (options: InitOptions, fullyLoadedCallback?: (config: Config) => void) => Boiler;
 }
+
+// ----- Module-level functions (for: const { getConfig, getLogger } = boiler) -----
+
+export function getLogger(name?: string): Logger;
+export function getConfig(): Promise<Config>;
+export function getConfigUnsafe(warnOnly?: boolean): Config;
+export function init(options: InitOptions, fullyLoadedCallback?: (config: Config) => void): Boiler;
+
+// ----- Default Export (for: import boiler from '@pryv/boiler') -----
+
+declare const boiler: Boiler;
+export default boiler;