@decaf-ts/logging 0.15.0 → 0.16.0

package/lib/types/constants.d.cts

@@ -0,0 +1,104 @@
+import { LoggingConfig, Theme } from "./types.cjs";
+/**
+ * @description The global key that is used to store environment variables in browser contexts.
+ * @summary This enables the logging environment helpers to locate serialized environment configuration on `globalThis`.
+ * @const {string} BrowserEnvKey
+ * @memberOf module:Logging
+ */
+export declare const BrowserEnvKey = "ENV";
+/**
+ * @description The delimiter that is used for composing nested environment variable names.
+ * @summary This joins parent and child keys when mapping object paths to ENV strings.
+ * @const {string} ENV_PATH_DELIMITER
+ * @memberOf module:Logging
+ */
+export declare const ENV_PATH_DELIMITER = "__";
+/**
+ * @description The default prefix and suffix that are used for template placeholders.
+ * @summary This provides wrapper strings that are applied when interpolating messages with {@link patchPlaceholders}.
+ * @const {string[]} DefaultPlaceholderWrappers
+ * @memberOf module:Logging
+ */
+export declare const DefaultPlaceholderWrappers: string[];
+/**
+ * @description An enum for log levels.
+ * @summary Defines the different levels of logging for the application.
+ * @enum {string}
+ * @readonly
+ * @memberOf module:Logging
+ */
+export declare enum LogLevel {
+    /** @description Benchmark events that capture performance metrics. */
+    benchmark = "benchmark",
+    /** @description Error events that indicate failures requiring attention. */
+    error = "error",
+    /** @description Warning events that may indicate issues. */
+    warn = "warn",
+    /** @description Informational events describing normal operation. */
+    info = "info",
+    /** @description Verbose diagnostic information for detailed tracing. */
+    verbose = "verbose",
+    /** @description Debug or trace details aimed at developers. */
+    debug = "debug",
+    /** @description trace details aimed at developers */
+    trace = "trace",
+    /** @description Extremely chatty or playful log entries. */
+    silly = "silly"
+}
+/**
+ * @description The numeric values that are associated with log levels.
+ * @summary This provides a numeric representation of log levels for comparison and filtering.
+ * @typedef {object} NumericLogLevelsShape
+ * @property {number} benchmark - The numeric value for the benchmark level (0).
+ * @property {number} error - The numeric value for the error level (3).
+ * @property {number} warn - The numeric value for the warn level (6).
+ * @property {number} info - The numeric value for the info level (9).
+ * @property {number} verbose - The numeric value for the verbose level (12).
+ * @property {number} debug - The numeric value for the debug level (15).
+ * @property {number} trace - The numeric value for the trace level (18).
+ * @property {number} silly - The numeric value for the silly level (21).
+ * @memberOf module:Logging
+ */
+/**
+ * @description The numeric values that are associated with log levels.
+ * @summary This provides a numeric representation of log levels for comparison and filtering.
+ * @const {NumericLogLevelsShape} NumericLogLevels
+ * @memberOf module:Logging
+ */
+export declare const NumericLogLevels: {
+    benchmark: number;
+    error: number;
+    warn: number;
+    info: number;
+    verbose: number;
+    debug: number;
+    trace: number;
+    silly: number;
+};
+/**
+ * @description An enum for logging output modes.
+ * @summary Defines the different output formats for log messages.
+ * @enum {string}
+ * @readonly
+ * @memberOf module:Logging
+ */
+export declare enum LoggingMode {
+    /** Raw text format for human readability */
+    RAW = "raw",
+    /** JSON format for machine parsing */
+    JSON = "json"
+}
+/**
+ * @description The default theme for styling log output.
+ * @summary Defines the default color and style settings for various components of log messages.
+ * @const {Theme} DefaultTheme
+ * @memberOf module:Logging
+ */
+export declare const DefaultTheme: Theme;
+/**
+ * @description The default configuration for logging.
+ * @summary Defines the default settings for the logging system, including verbosity, log level, styling, and timestamp format.
+ * @const {LoggingConfig} DefaultLoggingConfig
+ * @memberOf module:Logging
+ */
+export declare const DefaultLoggingConfig: LoggingConfig;

package/lib/types/constants.d.mts

@@ -0,0 +1,104 @@
+import { LoggingConfig, Theme } from "./types.js";
+/**
+ * @description The global key that is used to store environment variables in browser contexts.
+ * @summary This enables the logging environment helpers to locate serialized environment configuration on `globalThis`.
+ * @const {string} BrowserEnvKey
+ * @memberOf module:Logging
+ */
+export declare const BrowserEnvKey = "ENV";
+/**
+ * @description The delimiter that is used for composing nested environment variable names.
+ * @summary This joins parent and child keys when mapping object paths to ENV strings.
+ * @const {string} ENV_PATH_DELIMITER
+ * @memberOf module:Logging
+ */
+export declare const ENV_PATH_DELIMITER = "__";
+/**
+ * @description The default prefix and suffix that are used for template placeholders.
+ * @summary This provides wrapper strings that are applied when interpolating messages with {@link patchPlaceholders}.
+ * @const {string[]} DefaultPlaceholderWrappers
+ * @memberOf module:Logging
+ */
+export declare const DefaultPlaceholderWrappers: string[];
+/**
+ * @description An enum for log levels.
+ * @summary Defines the different levels of logging for the application.
+ * @enum {string}
+ * @readonly
+ * @memberOf module:Logging
+ */
+export declare enum LogLevel {
+    /** @description Benchmark events that capture performance metrics. */
+    benchmark = "benchmark",
+    /** @description Error events that indicate failures requiring attention. */
+    error = "error",
+    /** @description Warning events that may indicate issues. */
+    warn = "warn",
+    /** @description Informational events describing normal operation. */
+    info = "info",
+    /** @description Verbose diagnostic information for detailed tracing. */
+    verbose = "verbose",
+    /** @description Debug or trace details aimed at developers. */
+    debug = "debug",
+    /** @description trace details aimed at developers */
+    trace = "trace",
+    /** @description Extremely chatty or playful log entries. */
+    silly = "silly"
+}
+/**
+ * @description The numeric values that are associated with log levels.
+ * @summary This provides a numeric representation of log levels for comparison and filtering.
+ * @typedef {object} NumericLogLevelsShape
+ * @property {number} benchmark - The numeric value for the benchmark level (0).
+ * @property {number} error - The numeric value for the error level (3).
+ * @property {number} warn - The numeric value for the warn level (6).
+ * @property {number} info - The numeric value for the info level (9).
+ * @property {number} verbose - The numeric value for the verbose level (12).
+ * @property {number} debug - The numeric value for the debug level (15).
+ * @property {number} trace - The numeric value for the trace level (18).
+ * @property {number} silly - The numeric value for the silly level (21).
+ * @memberOf module:Logging
+ */
+/**
+ * @description The numeric values that are associated with log levels.
+ * @summary This provides a numeric representation of log levels for comparison and filtering.
+ * @const {NumericLogLevelsShape} NumericLogLevels
+ * @memberOf module:Logging
+ */
+export declare const NumericLogLevels: {
+    benchmark: number;
+    error: number;
+    warn: number;
+    info: number;
+    verbose: number;
+    debug: number;
+    trace: number;
+    silly: number;
+};
+/**
+ * @description An enum for logging output modes.
+ * @summary Defines the different output formats for log messages.
+ * @enum {string}
+ * @readonly
+ * @memberOf module:Logging
+ */
+export declare enum LoggingMode {
+    /** Raw text format for human readability */
+    RAW = "raw",
+    /** JSON format for machine parsing */
+    JSON = "json"
+}
+/**
+ * @description The default theme for styling log output.
+ * @summary Defines the default color and style settings for various components of log messages.
+ * @const {Theme} DefaultTheme
+ * @memberOf module:Logging
+ */
+export declare const DefaultTheme: Theme;
+/**
+ * @description The default configuration for logging.
+ * @summary Defines the default settings for the logging system, including verbosity, log level, styling, and timestamp format.
+ * @const {LoggingConfig} DefaultLoggingConfig
+ * @memberOf module:Logging
+ */
+export declare const DefaultLoggingConfig: LoggingConfig;

package/lib/types/decorators.d.cts

@@ -0,0 +1,109 @@
+import { LogLevel } from "./constants.cjs";
+export type ArgFormatFunction = (...args: any[]) => string;
+export type ReturnFormatFunction = (e?: Error, result?: any) => string;
+/**
+ * @description A method decorator for logging function calls.
+ * @summary This decorator wraps a class method to automatically log entry, exit, timing, and optional custom messages at a configurable {@link LogLevel}.
+ * @param {LogLevel} [level=LogLevel.info] - The log level to apply to the generated log statements.
+ * @param {number} [verbosity=0] - The verbosity threshold that is required for the entry log to appear.
+ * @param {ArgFormatFunction} [entryMessage] - A formatter that is invoked with the original method arguments to describe the invocation.
+ * @param {ReturnFormatFunction} [exitMessage] - An optional formatter that describes the outcome or failure of the call.
+ * @return {function(any, any, PropertyDescriptor): void} A method decorator proxy that injects logging behavior.
+ * @function log
+ * @mermaid
+ * sequenceDiagram
+ *   participant Client
+ *   participant Decorator as log decorator
+ *   participant Method as Original Method
+ *   participant Logger as Logging instance
+ *
+ *   Client->>Decorator: call decorated method
+ *   Decorator->>Logger: log method call
+ *   Decorator->>Method: call original method
+ *   alt result is Promise
+ *     Method-->>Decorator: return Promise
+ *     Decorator->>Decorator: attach then handler
+ *     Note over Decorator: Promise resolves
+ *     Decorator->>Logger: log benchmark (if enabled)
+ *     Decorator-->>Client: return result
+ *   else result is not Promise
+ *     Method-->>Decorator: return result
+ *     Decorator->>Logger: log benchmark (if enabled)
+ *     Decorator-->>Client: return result
+ *   end
+ * @category Method Decorators
+ */
+export declare function log(level?: LogLevel, verbosity?: number, entryMessage?: ArgFormatFunction, exitMessage?: ReturnFormatFunction): (target: any, propertyKey?: any, descriptor?: any) => any;
+/**
+ * @description A method decorator that records execution time at the benchmark level.
+ * @summary This decorator wraps the target method to emit {@link Logger.benchmark} entries that capture completion time or failure latency.
+ * @return {function(any, any, PropertyDescriptor): void} A method decorator proxy that benchmarks the original implementation.
+ * @function benchmark
+ * @mermaid
+ * sequenceDiagram
+ *   participant Caller
+ *   participant Decorator as benchmark
+ *   participant Method as Original Method
+ *   Caller->>Decorator: invoke()
+ *   Decorator->>Method: Reflect.apply(...)
+ *   alt Promise result
+ *     Method-->>Decorator: Promise
+ *     Decorator->>Decorator: attach then()
+ *     Decorator->>Decorator: log completion duration
+ *   else Synchronous result
+ *     Method-->>Decorator: value
+ *     Decorator->>Decorator: log completion duration
+ *   end
+ *   Decorator-->>Caller: return result
+ * @category Method Decorators
+ */
+export declare function benchmark(): (target: any, propertyKey?: any, descriptor?: any) => any;
+/**
+ * @description A method decorator for logging function calls with the debug level.
+ * @summary This is a convenience wrapper around {@link log} that logs using `LogLevel.debug`.
+ * @return {function(any, any, PropertyDescriptor): void} A debug-level logging decorator.
+ * @function debug
+ * @category Method Decorators
+ */
+export declare function debug(): (target: any, propertyKey?: any, descriptor?: any) => any;
+/**
+ * @description A method decorator for logging function calls with the info level.
+ * @summary This is a convenience wrapper around {@link log} that logs using `LogLevel.info`.
+ * @return {function(any, any, PropertyDescriptor): void} An info-level logging decorator.
+ * @function info
+ * @category Method Decorators
+ */
+export declare function info(): (target: any, propertyKey?: any, descriptor?: any) => any;
+/**
+ * @description A method decorator for logging function calls with the silly level.
+ * @summary This is a convenience wrapper around {@link log} that logs using `LogLevel.silly`.
+ * @return {function(any, any, PropertyDescriptor): void} A silly-level logging decorator.
+ * @function silly
+ * @category Method Decorators
+ */
+export declare function silly(): (target: any, propertyKey?: any, descriptor?: any) => any;
+/**
+ * @description A method decorator for logging function calls with the trace level.
+ * @summary This is a convenience wrapper around {@link log} that logs using `LogLevel.trace`.
+ * @return {function(any, any, PropertyDescriptor): void} A trace-level logging decorator.
+ * @function trace
+ * @category Method Decorators
+ */
+export declare function trace(): (target: any, propertyKey?: any, descriptor?: any) => any;
+/**
+ * @description A method decorator for logging function calls with the verbose level.
+ * @summary This is a convenience wrapper around {@link log} that logs using `LogLevel.verbose` with a configurable verbosity.
+ * @param {(number|boolean)} [verbosity=0] - The verbosity level for log filtering or a flag to enable benchmarking.
+ * @return {function(any, any, PropertyDescriptor): void} A verbose logging decorator.
+ * @function verbose
+ * @category Method Decorators
+ */
+export declare function verbose(verbosity?: number | boolean): (target: any, propertyKey?: any, descriptor?: any) => any;
+/**
+ * @description Creates a decorator that makes a method non-configurable.
+ * @summary This decorator prevents overriding by marking the method descriptor as non-configurable. It will throw an error if it is applied to non-method targets.
+ * @return {function(object, any, PropertyDescriptor): (PropertyDescriptor|undefined)} A decorator that hardens the method descriptor.
+ * @function final
+ * @category Method Decorators
+ */
+export declare function final(): (target: object, propertyKey?: any, descriptor?: any) => any;

package/lib/types/decorators.d.mts

@@ -0,0 +1,109 @@
+import { LogLevel } from "./constants.js";
+export type ArgFormatFunction = (...args: any[]) => string;
+export type ReturnFormatFunction = (e?: Error, result?: any) => string;
+/**
+ * @description A method decorator for logging function calls.
+ * @summary This decorator wraps a class method to automatically log entry, exit, timing, and optional custom messages at a configurable {@link LogLevel}.
+ * @param {LogLevel} [level=LogLevel.info] - The log level to apply to the generated log statements.
+ * @param {number} [verbosity=0] - The verbosity threshold that is required for the entry log to appear.
+ * @param {ArgFormatFunction} [entryMessage] - A formatter that is invoked with the original method arguments to describe the invocation.
+ * @param {ReturnFormatFunction} [exitMessage] - An optional formatter that describes the outcome or failure of the call.
+ * @return {function(any, any, PropertyDescriptor): void} A method decorator proxy that injects logging behavior.
+ * @function log
+ * @mermaid
+ * sequenceDiagram
+ *   participant Client
+ *   participant Decorator as log decorator
+ *   participant Method as Original Method
+ *   participant Logger as Logging instance
+ *
+ *   Client->>Decorator: call decorated method
+ *   Decorator->>Logger: log method call
+ *   Decorator->>Method: call original method
+ *   alt result is Promise
+ *     Method-->>Decorator: return Promise
+ *     Decorator->>Decorator: attach then handler
+ *     Note over Decorator: Promise resolves
+ *     Decorator->>Logger: log benchmark (if enabled)
+ *     Decorator-->>Client: return result
+ *   else result is not Promise
+ *     Method-->>Decorator: return result
+ *     Decorator->>Logger: log benchmark (if enabled)
+ *     Decorator-->>Client: return result
+ *   end
+ * @category Method Decorators
+ */
+export declare function log(level?: LogLevel, verbosity?: number, entryMessage?: ArgFormatFunction, exitMessage?: ReturnFormatFunction): (target: any, propertyKey?: any, descriptor?: any) => any;
+/**
+ * @description A method decorator that records execution time at the benchmark level.
+ * @summary This decorator wraps the target method to emit {@link Logger.benchmark} entries that capture completion time or failure latency.
+ * @return {function(any, any, PropertyDescriptor): void} A method decorator proxy that benchmarks the original implementation.
+ * @function benchmark
+ * @mermaid
+ * sequenceDiagram
+ *   participant Caller
+ *   participant Decorator as benchmark
+ *   participant Method as Original Method
+ *   Caller->>Decorator: invoke()
+ *   Decorator->>Method: Reflect.apply(...)
+ *   alt Promise result
+ *     Method-->>Decorator: Promise
+ *     Decorator->>Decorator: attach then()
+ *     Decorator->>Decorator: log completion duration
+ *   else Synchronous result
+ *     Method-->>Decorator: value
+ *     Decorator->>Decorator: log completion duration
+ *   end
+ *   Decorator-->>Caller: return result
+ * @category Method Decorators
+ */
+export declare function benchmark(): (target: any, propertyKey?: any, descriptor?: any) => any;
+/**
+ * @description A method decorator for logging function calls with the debug level.
+ * @summary This is a convenience wrapper around {@link log} that logs using `LogLevel.debug`.
+ * @return {function(any, any, PropertyDescriptor): void} A debug-level logging decorator.
+ * @function debug
+ * @category Method Decorators
+ */
+export declare function debug(): (target: any, propertyKey?: any, descriptor?: any) => any;
+/**
+ * @description A method decorator for logging function calls with the info level.
+ * @summary This is a convenience wrapper around {@link log} that logs using `LogLevel.info`.
+ * @return {function(any, any, PropertyDescriptor): void} An info-level logging decorator.
+ * @function info
+ * @category Method Decorators
+ */
+export declare function info(): (target: any, propertyKey?: any, descriptor?: any) => any;
+/**
+ * @description A method decorator for logging function calls with the silly level.
+ * @summary This is a convenience wrapper around {@link log} that logs using `LogLevel.silly`.
+ * @return {function(any, any, PropertyDescriptor): void} A silly-level logging decorator.
+ * @function silly
+ * @category Method Decorators
+ */
+export declare function silly(): (target: any, propertyKey?: any, descriptor?: any) => any;
+/**
+ * @description A method decorator for logging function calls with the trace level.
+ * @summary This is a convenience wrapper around {@link log} that logs using `LogLevel.trace`.
+ * @return {function(any, any, PropertyDescriptor): void} A trace-level logging decorator.
+ * @function trace
+ * @category Method Decorators
+ */
+export declare function trace(): (target: any, propertyKey?: any, descriptor?: any) => any;
+/**
+ * @description A method decorator for logging function calls with the verbose level.
+ * @summary This is a convenience wrapper around {@link log} that logs using `LogLevel.verbose` with a configurable verbosity.
+ * @param {(number|boolean)} [verbosity=0] - The verbosity level for log filtering or a flag to enable benchmarking.
+ * @return {function(any, any, PropertyDescriptor): void} A verbose logging decorator.
+ * @function verbose
+ * @category Method Decorators
+ */
+export declare function verbose(verbosity?: number | boolean): (target: any, propertyKey?: any, descriptor?: any) => any;
+/**
+ * @description Creates a decorator that makes a method non-configurable.
+ * @summary This decorator prevents overriding by marking the method descriptor as non-configurable. It will throw an error if it is applied to non-method targets.
+ * @return {function(object, any, PropertyDescriptor): (PropertyDescriptor|undefined)} A decorator that hardens the method descriptor.
+ * @function final
+ * @category Method Decorators
+ */
+export declare function final(): (target: object, propertyKey?: any, descriptor?: any) => any;

package/lib/types/environment.d.cts

@@ -0,0 +1,120 @@
+import { ObjectAccumulator } from "typed-object-accumulator";
+/**
+ * @description A factory type for creating Environment instances.
+ * @summary This describes factories that construct {@link Environment} derivatives with custom initialization.
+ * @template T - The type of object the Environment will accumulate.
+ * @template E - The specific Environment type to be created, extending Environment<T>.
+ * @typedef {function(unknown[]): E} EnvironmentFactory
+ * @memberOf module:Logging
+ */
+export type EnvironmentFactory<T extends object, E extends Environment<T>> = (...args: unknown[]) => E;
+export type EnvironmentInstance<T extends object = any> = Environment<T> & T & {
+    orThrow(): EnvironmentInstance<any>;
+};
+export type AccumulatedEnvironment<T extends object = any> = EnvironmentInstance<T> & ObjectAccumulator<T> & {
+    accumulate<V extends object>(value: V): AccumulatedEnvironment<T & V>;
+};
+export declare class Environment<T extends object> extends ObjectAccumulator<T> {
+    /**
+     * @static
+     * @protected
+     * @description A factory function for creating Environment instances.
+     * @summary Defines how new instances of the Environment class should be created.
+     * @return {Environment<any>} A new instance of the Environment class.
+     */
+    protected static factory: EnvironmentFactory<any, any>;
+    /**
+     * @static
+     * @private
+     * @description The singleton instance of the Environment class.
+     * @type {Environment<any>}
+     */
+    private static _instance;
+    protected constructor();
+    /**
+     * @description Retrieves a value from the runtime environment.
+     * @summary This method handles browser and Node.js environments by normalizing keys and parsing values.
+     * @param {string} k - The key to resolve from the environment.
+     * @return {unknown} The value that is resolved from the environment, or `undefined` if it is absent.
+     */
+    protected fromEnv(k: string): unknown;
+    /**
+     * @description Converts stringified environment values into native types.
+     * @summary This method interprets booleans and numbers, while leaving other types unchanged.
+     * @param {unknown} val - The raw value that is retrieved from the environment.
+     * @return {unknown} The parsed value, converted to a boolean or number, or left as-is.
+     */
+    protected parseEnvValue(val: unknown): unknown;
+    private static parseRuntimeValue;
+    /**
+     * @description Expands an object into the environment.
+     * @summary This method defines lazy properties that first consult runtime variables before falling back to seeded values.
+     * @template V - The type of the object being expanded.
+     * @param {V} value - The object to expose through environment getters and setters.
+     * @return {void}
+     */
+    protected expand<V extends object>(value: V): void;
+    /**
+     * @description Returns a proxy that enforces required environment variables.
+     * @summary Accessing a property that resolves to `undefined` or an empty string when declared in the model will throw an error.
+     * @return {EnvironmentInstance<any>} A proxy of the environment that enforces required variables.
+     */
+    orThrow(): EnvironmentInstance<any>;
+    /**
+     * @protected
+     * @static
+     * @description Retrieves or creates the singleton instance of the Environment class.
+     * @summary This method ensures that only one {@link Environment} instance is created, and wraps it in a proxy to compose ENV keys on demand.
+     * @template E
+     * @param {...unknown[]} args - Arguments that are forwarded to the factory when instantiating the singleton.
+     * @return {E} The singleton environment instance.
+     */
+    protected static instance<E extends Environment<any>>(...args: unknown[]): E;
+    accumulate<V extends object>(value: V): AccumulatedEnvironment<T & V>;
+    /**
+     * @static
+     * @description Accumulates the given value into the environment.
+     * @summary This method adds new properties and hides raw descriptors to avoid leaking enumeration semantics.
+     * @template V
+     * @param {V} value - The object to merge into the environment.
+     * @return {AccumulatedEnvironment<any>} The updated environment reference.
+     */
+    static accumulate<V extends object>(value: V): AccumulatedEnvironment<any>;
+    /**
+     * @description Retrieves a value using a dot-path key from the accumulated environment.
+     * @summary This method delegates to the singleton instance to access stored configuration.
+     * @param {string} key - The key to resolve from the environment store.
+     * @return {unknown} The stored value that corresponds to the provided key.
+     */
+    static get(key: string): any;
+    private static formatEnvSegment;
+    private static buildEnvKey;
+    private static buildRawKey;
+    private static readRuntimeForPath;
+    /**
+     * @description Builds a proxy that composes environment keys for nested properties.
+     * @summary This allows chained property access to emit uppercase ENV identifiers, while honoring existing runtime overrides.
+     * @param {any} current - The seed model segment to use when projecting nested structures.
+     * @param {string[]} path - The accumulated path segments that lead to the proxy.
+     * @return {any} A proxy that resolves environment values or composes additional proxies for deeper paths.
+     */
+    private static buildEnvProxy;
+    /**
+     * @static
+     * @description Retrieves the keys of the environment, optionally converting them to ENV format.
+     * @summary This method gets all keys in the environment, with an option to format them for environment variables.
+     * @param {boolean} [toEnv=true] - Whether to convert the keys to ENV format.
+     * @return {string[]} An array of keys from the environment.
+     */
+    static keys(toEnv?: boolean): string[];
+    private static mergeModel;
+    private static readRuntimeEnv;
+    private static missingEnvError;
+}
+/**
+ * @description A singleton environment instance that is seeded with the default logging configuration.
+ * @summary This constant combines {@link DefaultLoggingConfig} with runtime environment variables to provide consistent logging defaults across platforms.
+ * @const {AccumulatedEnvironment<any>} LoggedEnvironment
+ * @memberOf module:Logging
+ */
+export declare const LoggedEnvironment: any;

package/lib/types/environment.d.mts

@@ -0,0 +1,120 @@
+import { ObjectAccumulator } from "typed-object-accumulator";
+/**
+ * @description A factory type for creating Environment instances.
+ * @summary This describes factories that construct {@link Environment} derivatives with custom initialization.
+ * @template T - The type of object the Environment will accumulate.
+ * @template E - The specific Environment type to be created, extending Environment<T>.
+ * @typedef {function(unknown[]): E} EnvironmentFactory
+ * @memberOf module:Logging
+ */
+export type EnvironmentFactory<T extends object, E extends Environment<T>> = (...args: unknown[]) => E;
+export type EnvironmentInstance<T extends object = any> = Environment<T> & T & {
+    orThrow(): EnvironmentInstance<any>;
+};
+export type AccumulatedEnvironment<T extends object = any> = EnvironmentInstance<T> & ObjectAccumulator<T> & {
+    accumulate<V extends object>(value: V): AccumulatedEnvironment<T & V>;
+};
+export declare class Environment<T extends object> extends ObjectAccumulator<T> {
+    /**
+     * @static
+     * @protected
+     * @description A factory function for creating Environment instances.
+     * @summary Defines how new instances of the Environment class should be created.
+     * @return {Environment<any>} A new instance of the Environment class.
+     */
+    protected static factory: EnvironmentFactory<any, any>;
+    /**
+     * @static
+     * @private
+     * @description The singleton instance of the Environment class.
+     * @type {Environment<any>}
+     */
+    private static _instance;
+    protected constructor();
+    /**
+     * @description Retrieves a value from the runtime environment.
+     * @summary This method handles browser and Node.js environments by normalizing keys and parsing values.
+     * @param {string} k - The key to resolve from the environment.
+     * @return {unknown} The value that is resolved from the environment, or `undefined` if it is absent.
+     */
+    protected fromEnv(k: string): unknown;
+    /**
+     * @description Converts stringified environment values into native types.
+     * @summary This method interprets booleans and numbers, while leaving other types unchanged.
+     * @param {unknown} val - The raw value that is retrieved from the environment.
+     * @return {unknown} The parsed value, converted to a boolean or number, or left as-is.
+     */
+    protected parseEnvValue(val: unknown): unknown;
+    private static parseRuntimeValue;
+    /**
+     * @description Expands an object into the environment.
+     * @summary This method defines lazy properties that first consult runtime variables before falling back to seeded values.
+     * @template V - The type of the object being expanded.
+     * @param {V} value - The object to expose through environment getters and setters.
+     * @return {void}
+     */
+    protected expand<V extends object>(value: V): void;
+    /**
+     * @description Returns a proxy that enforces required environment variables.
+     * @summary Accessing a property that resolves to `undefined` or an empty string when declared in the model will throw an error.
+     * @return {EnvironmentInstance<any>} A proxy of the environment that enforces required variables.
+     */
+    orThrow(): EnvironmentInstance<any>;
+    /**
+     * @protected
+     * @static
+     * @description Retrieves or creates the singleton instance of the Environment class.
+     * @summary This method ensures that only one {@link Environment} instance is created, and wraps it in a proxy to compose ENV keys on demand.
+     * @template E
+     * @param {...unknown[]} args - Arguments that are forwarded to the factory when instantiating the singleton.
+     * @return {E} The singleton environment instance.
+     */
+    protected static instance<E extends Environment<any>>(...args: unknown[]): E;
+    accumulate<V extends object>(value: V): AccumulatedEnvironment<T & V>;
+    /**
+     * @static
+     * @description Accumulates the given value into the environment.
+     * @summary This method adds new properties and hides raw descriptors to avoid leaking enumeration semantics.
+     * @template V
+     * @param {V} value - The object to merge into the environment.
+     * @return {AccumulatedEnvironment<any>} The updated environment reference.
+     */
+    static accumulate<V extends object>(value: V): AccumulatedEnvironment<any>;
+    /**
+     * @description Retrieves a value using a dot-path key from the accumulated environment.
+     * @summary This method delegates to the singleton instance to access stored configuration.
+     * @param {string} key - The key to resolve from the environment store.
+     * @return {unknown} The stored value that corresponds to the provided key.
+     */
+    static get(key: string): any;
+    private static formatEnvSegment;
+    private static buildEnvKey;
+    private static buildRawKey;
+    private static readRuntimeForPath;
+    /**
+     * @description Builds a proxy that composes environment keys for nested properties.
+     * @summary This allows chained property access to emit uppercase ENV identifiers, while honoring existing runtime overrides.
+     * @param {any} current - The seed model segment to use when projecting nested structures.
+     * @param {string[]} path - The accumulated path segments that lead to the proxy.
+     * @return {any} A proxy that resolves environment values or composes additional proxies for deeper paths.
+     */
+    private static buildEnvProxy;
+    /**
+     * @static
+     * @description Retrieves the keys of the environment, optionally converting them to ENV format.
+     * @summary This method gets all keys in the environment, with an option to format them for environment variables.
+     * @param {boolean} [toEnv=true] - Whether to convert the keys to ENV format.
+     * @return {string[]} An array of keys from the environment.
+     */
+    static keys(toEnv?: boolean): string[];
+    private static mergeModel;
+    private static readRuntimeEnv;
+    private static missingEnvError;
+}
+/**
+ * @description A singleton environment instance that is seeded with the default logging configuration.
+ * @summary This constant combines {@link DefaultLoggingConfig} with runtime environment variables to provide consistent logging defaults across platforms.
+ * @const {AccumulatedEnvironment<any>} LoggedEnvironment
+ * @memberOf module:Logging
+ */
+export declare const LoggedEnvironment: any;