@decaf-ts/logging 0.15.0 → 0.16.0

package/lib/types/text.d.mts

@@ -0,0 +1,118 @@
+/**
+ * @description Pads the end of a string with a specified character.
+ * @summary This function extends the input string to a specified length by adding a padding character to the end. If the input string is already longer than the specified length, it is returned unchanged.
+ * @param {string} str - The input string to be padded.
+ * @param {number} length - The desired total length of the resulting string.
+ * @param {string} [char=" "] - The character to use for padding.
+ * @return {string} The padded string.
+ * @throws {Error} If the padding character is not exactly one character long.
+ * @function padEnd
+ * @memberOf module:Logging
+ */
+export declare function padEnd(str: string, length: number, char?: string): string;
+/**
+ * @description Replaces placeholders in a string with the provided values.
+ * @summary This function interpolates a string by replacing placeholders of the form `${variableName}` with the corresponding values from the provided object. If a placeholder does not have a corresponding value, it is left unchanged in the string.
+ * @param {string} input - The input string containing the placeholders to be replaced.
+ * @param {Record<string, (number|string)>} values - An object containing key-value pairs for the replacement.
+ * @param {string} [prefix="${"] - The prefix for the placeholders.
+ * @param {string} [suffix="}"] - The suffix for the placeholders.
+ * @param {string} [flags="g"] - The regular expression flags to use.
+ * @return {string} The interpolated string with the placeholders replaced by their corresponding values.
+ * @function patchPlaceholders
+ * @mermaid
+ * sequenceDiagram
+ *   participant Caller
+ *   participant patchString
+ *   participant String.replace
+ *   Caller->>patchString: Call with input and values
+ *   patchString->>String.replace: Call with regex and replacement function
+ *   String.replace->>patchString: Return replaced string
+ *   patchString-->>Caller: Return patched string
+ * @memberOf module:Logging
+ */
+export declare function patchPlaceholders(input: string, values: Record<string, number | string>, prefix?: string, suffix?: string, flags?: string): string;
+/**
+ * @description Replaces occurrences of keys with their corresponding values in a string.
+ * @summary This function iterates through a set of key-value pairs and replaces all occurrences of each key in the input string with its corresponding value. It supports regular expression flags for customized replacement.
+ * @param {string} input - The input string in which the replacements will be made.
+ * @param {Record<string, (number|string)>} values - An object containing key-value pairs for the replacement.
+ * @param {string} [flags="g"] - The regular expression flags to control the replacement behavior.
+ * @return {string} The string with all the specified replacements applied.
+ * @function patchString
+ * @memberOf module:Logging
+ */
+export declare function patchString(input: string, values: Record<string, number | string>, flags?: string): string;
+/**
+ * @description Converts a string to camelCase.
+ * @summary This function transforms the input string into camelCase format, where words are joined without spaces and each word after the first starts with a capital letter.
+ * @param {string} text - The input string to be converted.
+ * @return {string} The input string converted to camelCase.
+ * @function toCamelCase
+ * @memberOf module:Logging
+ */
+export declare function toCamelCase(text: string): string;
+/**
+ * @description Converts a string to ENVIRONMENT_VARIABLE format.
+ * @summary This function transforms the input string into uppercase with words separated by underscores, which is a format that is typically used for environment variable names.
+ * @param {string} text - The input string to be converted.
+ * @return {string} The input string converted to ENVIRONMENT_VARIABLE format.
+ * @function toENVFormat
+ * @memberOf module:Logging
+ */
+export declare function toENVFormat(text: string): string;
+/**
+ * @description Converts a string to snake_case.
+ * @summary This function transforms the input string into lowercase with words separated by underscores.
+ * @param {string} text - The input string to be converted.
+ * @return {string} The input string converted to snake_case.
+ * @function toSnakeCase
+ * @memberOf module:Logging
+ */
+export declare function toSnakeCase(text: string): string;
+/**
+ * @description Converts a string to kebab-case.
+ * @summary This function transforms the input string into lowercase with words separated by hyphens.
+ * @param {string} text - The input string to be converted.
+ * @return {string} The input string converted to kebab-case.
+ * @function toKebabCase
+ * @memberOf module:Logging
+ */
+export declare function toKebabCase(text: string): string;
+/**
+ * @description Converts a string to PascalCase.
+ * @summary This function transforms the input string into PascalCase format, where words are joined without spaces and each word starts with a capital letter.
+ * @param {string} text - The input string to be converted.
+ * @return {string} The input string converted to PascalCase.
+ * @function toPascalCase
+ * @memberOf module:Logging
+ */
+export declare function toPascalCase(text: string): string;
+/**
+ * @description Escapes special characters in a string for use in a regular expression.
+ * @summary This function adds backslashes before characters that have a special meaning in regular expressions, which allows the string to be used as a literal match in a RegExp.
+ * @param {string} string - The string to escape for regular expression use.
+ * @return {string} The escaped string that is safe for use in regular expressions.
+ * @function escapeRegExp
+ * @memberOf module:Logging
+ */
+export declare function escapeRegExp(string: string): string;
+/**
+ * @description A utility function that provides string formatting functionality that is similar to C#'s string.format.
+ * @summary This function replaces placeholders in a string with the provided arguments.
+ * @param {string} string - The string to format.
+ * @param {...(string|number|Record<string, any>)} args - The arguments to use for formatting.
+ * @return {string} The formatted string.
+ * @function sf
+ * @memberOf module:Logging
+ */
+export declare function sf(string: string, ...args: (string | number | Record<string, any>)[]): string;
+/**
+ * @description A utility function that provides string formatting functionality that is similar to C#'s string.format.
+ * @summary This function is deprecated. Use {@link sf} instead.
+ * @see sf
+ * @deprecated
+ * @function stringFormat
+ * @memberOf module:Logging
+ */
+export declare const stringFormat: typeof sf;

package/lib/types/time.d.cts

@@ -0,0 +1,151 @@
+/**
+ * @description A snapshot of a recorded lap interval.
+ * @summary This captures the lap index, an optional label, the elapsed milliseconds for the lap, and the cumulative elapsed time since the stopwatch started.
+ * @typedef {object} Lap
+ * @property {number} index - The zero-based lap order.
+ * @property {string} [label] - An optional label that describes the lap.
+ * @property {number} ms - The duration of the lap in milliseconds.
+ * @property {number} totalMs - The total elapsed time when the lap was recorded.
+ * @memberOf module:Logging
+ */
+export type Lap = {
+    index: number;
+    label?: string;
+    /** Duration of this lap in milliseconds */
+    ms: number;
+    /** Cumulative time up to this lap in milliseconds */
+    totalMs: number;
+};
+type NowFn = () => number;
+/**
+ * @description A high-resolution clock accessor that returns milliseconds.
+ * @summary This function chooses the most precise timer available in the current runtime, preferring `performance.now` or `process.hrtime.bigint`.
+ * @return {number} The milliseconds that have elapsed, according to the best available clock.
+ * @function now
+ * @memberOf module:Logging
+ */
+export declare const now: NowFn;
+/**
+ * @description A high-resolution stopwatch with pause, resume, and lap tracking.
+ * @summary This class tracks elapsed time using the highest precision timer available. It supports pausing, resuming, and recording labeled laps for diagnostics and benchmarking.
+ * @param {boolean} [autoStart=false] - When `true`, the stopwatch starts immediately upon construction.
+ * @class StopWatch
+ * @example
+ * const sw = new StopWatch(true);
+ * // ... work ...
+ * const lap = sw.lap("phase 1");
+ * sw.pause();
+ * console.log(`Elapsed: ${lap.totalMs}ms`);
+ * @mermaid
+ * sequenceDiagram
+ *   participant Client
+ *   participant StopWatch
+ *   participant Clock as now()
+ *   Client->>StopWatch: start()
+ *   StopWatch->>Clock: now()
+ *   Clock-->>StopWatch: timestamp
+ *   Client->>StopWatch: lap()
+ *   StopWatch->>Clock: now()
+ *   Clock-->>StopWatch: timestamp
+ *   StopWatch-->>Client: Lap
+ *   Client->>StopWatch: pause()
+ *   StopWatch->>Clock: now()
+ *   Clock-->>StopWatch: timestamp
+ */
+export declare class StopWatch {
+    private _startMs;
+    private _elapsedMs;
+    private _running;
+    private _laps;
+    private _lastLapTotalMs;
+    constructor(autoStart?: boolean);
+    /**
+     * @description Indicates whether the stopwatch is actively running.
+     * @summary This method returns `true` when timing is in progress, and `false` when it is paused or stopped.
+     * @return {boolean} The current running state.
+     */
+    get running(): boolean;
+    /**
+     * @description The elapsed time that has been captured by the stopwatch.
+     * @summary This method computes the total elapsed time in milliseconds, including the current session if it is running.
+     * @return {number} The milliseconds that have elapsed since the stopwatch started.
+     */
+    get elapsedMs(): number;
+    /**
+     * @description Starts timing if the stopwatch is not already running.
+     * @summary This method records the current timestamp and transitions the stopwatch into the running state.
+     * @return {this} A fluent reference to the stopwatch.
+     */
+    start(): this;
+    /**
+     * @description Pauses timing and accumulates the elapsed milliseconds.
+     * @summary This method captures the partial duration, updates the accumulator, and keeps the stopwatch ready to resume later.
+     * @return {this} A fluent reference to the stopwatch.
+     */
+    pause(): this;
+    /**
+     * @description Resumes timing after a pause.
+     * @summary This method captures a fresh start timestamp, while keeping the previous elapsed time intact.
+     * @return {this} A fluent reference to the stopwatch.
+     */
+    resume(): this;
+    /**
+     * @description Stops timing and returns the total elapsed milliseconds.
+     * @summary This method invokes {@link StopWatch.pause} to consolidate the elapsed time, and leaves the stopwatch in a non-running state.
+     * @return {number} The milliseconds that have accumulated across all runs.
+     */
+    stop(): number;
+    /**
+     * @description Resets the stopwatch state, while optionally continuing to run.
+     * @summary This method clears the elapsed time and lap history, and preserves whether the stopwatch should continue ticking.
+     * @return {this} A fluent reference to the stopwatch.
+     */
+    reset(): this;
+    /**
+     * @description Records a lap split since the stopwatch started, or since the previous lap.
+     * @summary This method stores the lap metadata, updates the cumulative tracking, and returns the newly created {@link Lap}.
+     * @param {string} [label] - An optional label that describes the lap.
+     * @return {Lap} A lap snapshot that captures incremental and cumulative timings.
+     */
+    lap(label?: string): Lap;
+    /**
+     * @description Retrieves the recorded lap history.
+     * @summary This method returns the internal lap array as a read-only view to prevent external mutation.
+     * @return {Array<Lap>} The laps that have been captured by the stopwatch.
+     */
+    get laps(): readonly Lap[];
+    /**
+     * @description Formats the elapsed time in a human-readable representation.
+     * @summary This method uses {@link formatMs} to produce an `hh:mm:ss.mmm` string for display and logging.
+     * @return {string} The elapsed time, formatted for presentation.
+     */
+    toString(): string;
+    /**
+     * @description Serializes the stopwatch state.
+     * @summary This method provides a JSON-friendly snapshot that includes the running state, elapsed time, and lap details.
+     * @return {{running: boolean, elapsedMs: number, laps: Lap[]}} A serializable stopwatch representation.
+     */
+    toJSON(): {
+        running: boolean;
+        elapsedMs: number;
+        laps: Lap[];
+    };
+}
+/**
+ * @description Formats milliseconds into `hh:mm:ss.mmm`.
+ * @summary This function breaks the duration into hours, minutes, seconds, and milliseconds, and returns a zero-padded string.
+ * @param {number} ms - The milliseconds to format.
+ * @return {string} The formatted duration string.
+ * @function formatMs
+ * @memberOf module:Logging
+ * @mermaid
+ * sequenceDiagram
+ *   participant Caller
+ *   participant Formatter as formatMs
+ *   Caller->>Formatter: formatMs(ms)
+ *   Formatter->>Formatter: derive hours/minutes/seconds
+ *   Formatter->>Formatter: pad segments
+ *   Formatter-->>Caller: hh:mm:ss.mmm
+ */
+export declare function formatMs(ms: number): string;
+export {};

package/lib/types/time.d.mts

@@ -0,0 +1,151 @@
+/**
+ * @description A snapshot of a recorded lap interval.
+ * @summary This captures the lap index, an optional label, the elapsed milliseconds for the lap, and the cumulative elapsed time since the stopwatch started.
+ * @typedef {object} Lap
+ * @property {number} index - The zero-based lap order.
+ * @property {string} [label] - An optional label that describes the lap.
+ * @property {number} ms - The duration of the lap in milliseconds.
+ * @property {number} totalMs - The total elapsed time when the lap was recorded.
+ * @memberOf module:Logging
+ */
+export type Lap = {
+    index: number;
+    label?: string;
+    /** Duration of this lap in milliseconds */
+    ms: number;
+    /** Cumulative time up to this lap in milliseconds */
+    totalMs: number;
+};
+type NowFn = () => number;
+/**
+ * @description A high-resolution clock accessor that returns milliseconds.
+ * @summary This function chooses the most precise timer available in the current runtime, preferring `performance.now` or `process.hrtime.bigint`.
+ * @return {number} The milliseconds that have elapsed, according to the best available clock.
+ * @function now
+ * @memberOf module:Logging
+ */
+export declare const now: NowFn;
+/**
+ * @description A high-resolution stopwatch with pause, resume, and lap tracking.
+ * @summary This class tracks elapsed time using the highest precision timer available. It supports pausing, resuming, and recording labeled laps for diagnostics and benchmarking.
+ * @param {boolean} [autoStart=false] - When `true`, the stopwatch starts immediately upon construction.
+ * @class StopWatch
+ * @example
+ * const sw = new StopWatch(true);
+ * // ... work ...
+ * const lap = sw.lap("phase 1");
+ * sw.pause();
+ * console.log(`Elapsed: ${lap.totalMs}ms`);
+ * @mermaid
+ * sequenceDiagram
+ *   participant Client
+ *   participant StopWatch
+ *   participant Clock as now()
+ *   Client->>StopWatch: start()
+ *   StopWatch->>Clock: now()
+ *   Clock-->>StopWatch: timestamp
+ *   Client->>StopWatch: lap()
+ *   StopWatch->>Clock: now()
+ *   Clock-->>StopWatch: timestamp
+ *   StopWatch-->>Client: Lap
+ *   Client->>StopWatch: pause()
+ *   StopWatch->>Clock: now()
+ *   Clock-->>StopWatch: timestamp
+ */
+export declare class StopWatch {
+    private _startMs;
+    private _elapsedMs;
+    private _running;
+    private _laps;
+    private _lastLapTotalMs;
+    constructor(autoStart?: boolean);
+    /**
+     * @description Indicates whether the stopwatch is actively running.
+     * @summary This method returns `true` when timing is in progress, and `false` when it is paused or stopped.
+     * @return {boolean} The current running state.
+     */
+    get running(): boolean;
+    /**
+     * @description The elapsed time that has been captured by the stopwatch.
+     * @summary This method computes the total elapsed time in milliseconds, including the current session if it is running.
+     * @return {number} The milliseconds that have elapsed since the stopwatch started.
+     */
+    get elapsedMs(): number;
+    /**
+     * @description Starts timing if the stopwatch is not already running.
+     * @summary This method records the current timestamp and transitions the stopwatch into the running state.
+     * @return {this} A fluent reference to the stopwatch.
+     */
+    start(): this;
+    /**
+     * @description Pauses timing and accumulates the elapsed milliseconds.
+     * @summary This method captures the partial duration, updates the accumulator, and keeps the stopwatch ready to resume later.
+     * @return {this} A fluent reference to the stopwatch.
+     */
+    pause(): this;
+    /**
+     * @description Resumes timing after a pause.
+     * @summary This method captures a fresh start timestamp, while keeping the previous elapsed time intact.
+     * @return {this} A fluent reference to the stopwatch.
+     */
+    resume(): this;
+    /**
+     * @description Stops timing and returns the total elapsed milliseconds.
+     * @summary This method invokes {@link StopWatch.pause} to consolidate the elapsed time, and leaves the stopwatch in a non-running state.
+     * @return {number} The milliseconds that have accumulated across all runs.
+     */
+    stop(): number;
+    /**
+     * @description Resets the stopwatch state, while optionally continuing to run.
+     * @summary This method clears the elapsed time and lap history, and preserves whether the stopwatch should continue ticking.
+     * @return {this} A fluent reference to the stopwatch.
+     */
+    reset(): this;
+    /**
+     * @description Records a lap split since the stopwatch started, or since the previous lap.
+     * @summary This method stores the lap metadata, updates the cumulative tracking, and returns the newly created {@link Lap}.
+     * @param {string} [label] - An optional label that describes the lap.
+     * @return {Lap} A lap snapshot that captures incremental and cumulative timings.
+     */
+    lap(label?: string): Lap;
+    /**
+     * @description Retrieves the recorded lap history.
+     * @summary This method returns the internal lap array as a read-only view to prevent external mutation.
+     * @return {Array<Lap>} The laps that have been captured by the stopwatch.
+     */
+    get laps(): readonly Lap[];
+    /**
+     * @description Formats the elapsed time in a human-readable representation.
+     * @summary This method uses {@link formatMs} to produce an `hh:mm:ss.mmm` string for display and logging.
+     * @return {string} The elapsed time, formatted for presentation.
+     */
+    toString(): string;
+    /**
+     * @description Serializes the stopwatch state.
+     * @summary This method provides a JSON-friendly snapshot that includes the running state, elapsed time, and lap details.
+     * @return {{running: boolean, elapsedMs: number, laps: Lap[]}} A serializable stopwatch representation.
+     */
+    toJSON(): {
+        running: boolean;
+        elapsedMs: number;
+        laps: Lap[];
+    };
+}
+/**
+ * @description Formats milliseconds into `hh:mm:ss.mmm`.
+ * @summary This function breaks the duration into hours, minutes, seconds, and milliseconds, and returns a zero-padded string.
+ * @param {number} ms - The milliseconds to format.
+ * @return {string} The formatted duration string.
+ * @function formatMs
+ * @memberOf module:Logging
+ * @mermaid
+ * sequenceDiagram
+ *   participant Caller
+ *   participant Formatter as formatMs
+ *   Caller->>Formatter: formatMs(ms)
+ *   Formatter->>Formatter: derive hours/minutes/seconds
+ *   Formatter->>Formatter: pad segments
+ *   Formatter-->>Caller: hh:mm:ss.mmm
+ */
+export declare function formatMs(ms: number): string;
+export {};