@controlium/utils 0.0.0

package/dist/types/logger/logger.d.ts

@@ -0,0 +1,388 @@
+import { VideoOptions, WriteLineOptions, LogOutputCallbackSignature } from "./types";
+export declare class Logger {
+    /**
+     * Numeric log level constants used to control and filter log output.
+     *
+     * Levels are ordered from highest verbosity to lowest:
+     * - `Maximum` / `Verbose` — log everything
+     * - `FrameworkDebug` — internal framework debug messages
+     * - `FrameworkInformation` — internal framework info messages
+     * - `TestDebug` — test-level debug messages
+     * - `TestInformation` — test-level info messages
+     * - `Warning` — warnings and errors
+     * - `Error` — errors only
+     * - `NoOutput` — suppress all output
+     *
+     * @example
+     * Logger.loggingLevel = Logger.Levels.TestInformation;
+     */
+    static readonly Levels: {
+        /** Maximum verbosity. Same numeric value as `Verbose`. */
+        readonly Maximum: number;
+        /** Verbose logging. Same numeric value as `Maximum`. */
+        readonly Verbose: number;
+        /** Framework-level debug logs. */
+        readonly FrameworkDebug: 6;
+        /** Framework-level informational logs. */
+        readonly FrameworkInformation: 5;
+        /** Test-level debug logs. */
+        readonly TestDebug: 4;
+        /** Test-level informational logs. */
+        readonly TestInformation: 3;
+        /** Warnings (and errors). */
+        readonly Warning: 2;
+        /** Errors only. */
+        readonly Error: 1;
+        /** No log output is allowed at this level. */
+        readonly NoOutput: 0;
+    };
+    private static readonly videoResolutionLimits;
+    private static options;
+    private static startTime;
+    /**
+     * Callback invoked for every log output (after formatting and preamble generation).
+     *
+     * If defined, the logger calls this function with:
+     *  - `message`: The final formatted log line or attached payload.
+     *  - `mediaType`: Optional MIME-type-style string.
+     *      Examples:
+     *        - `"text/plain"` for normal log lines
+     *        - `"text/html"` for HTML attachments
+     *        - `"base64:image/png"` for screenshots
+     *
+     * If the callback throws, the logger catches the error and processes it,
+     * reporting to the test suite if required.
+     *
+     * Set this to `undefined` (or call `Logger.clearOutputCallback()`) to disable callback output.
+     *
+     * @example
+     * Logger.logOutputCallback = (message, mediaType) => {
+     *   myReporter.attach(message, mediaType ?? "text/plain");
+     * };
+     */
+    static logOutputCallback: LogOutputCallbackSignature | undefined;
+    /**
+     * Resets the logger to its default configuration.
+     *
+     * Clears the output callback and restores all options to their default values.
+     * Optionally resets the elapsed-time start point to the current moment.
+     *
+     * @param resetStartTime - When `true`, the start time used for elapsed-time
+     *   calculation is reset to now. When `false` (the default), the existing
+     *   start time is preserved so elapsed time continues from the original baseline.
+     *
+     * @example
+     * Logger.reset();       // Reset options only, keep elapsed-time baseline
+     * Logger.reset(true);   // Reset options and restart the elapsed timer
+     */
+    static reset(resetStartTime?: boolean): void;
+    /**
+     * Controls whether log output is written to the console.
+     *
+     * When `true`, every log line is written to `console.log()` in addition
+     * to any configured {@link logOutputCallback}.
+     * When `false`, output is sent only to the callback (if defined).
+     *
+     * @example
+     * Logger.logToConsole = true;
+     */
+    static set logToConsole(value: boolean);
+    /**
+     * Returns whether log output is currently being written to the console.
+     *
+     * @returns `true` if console logging is enabled; otherwise `false`.
+     */
+    static get logToConsole(): boolean;
+    /**
+     * Enables or disables Panic Mode.
+     *
+     * When `true`, the current log level is ignored and all log calls produce
+     * output — equivalent to setting the log level to `Verbose`.
+     * When `false`, normal log-level filtering applies.
+     *
+     * @example
+     * Logger.panicMode = true; // Force all output regardless of log level
+     */
+    static set panicMode(value: boolean);
+    /**
+     * Returns whether Panic Mode is currently active.
+     *
+     * When `true`, all log output is written regardless of the configured log level.
+     *
+     * @returns `true` if Panic Mode is enabled; otherwise `false`.
+     */
+    static get panicMode(): boolean;
+    /**
+     * Controls whether an exception is thrown when a log-output operation fails.
+     *
+     * When `true`, any error raised while executing the configured
+     * {@link logOutputCallback} is re-thrown to the caller.
+     * When `false`, such errors are suppressed and logged internally instead.
+     *
+     * @example
+     * Logger.throwErrorIfLogOutputFails = true;
+     */
+    static set throwErrorIfLogOutputFails(value: boolean);
+    /**
+     * Returns whether log-output failures are re-thrown as exceptions.
+     *
+     * @returns `true` if logging errors are propagated to the caller;
+     *   `false` if they are suppressed and logged internally.
+     */
+    static get throwErrorIfLogOutputFails(): boolean;
+    /**
+     * Returns the current global logging level.
+     *
+     * Only messages with a level less than or equal to this value
+     * (or within the configured {@link loggingFilter} range) will be output.
+     *
+     * @returns The current numeric log level.
+     *
+     * @see {@link Levels} for named level constants.
+     */
+    static get loggingLevel(): number;
+    /**
+     * Sets the global logging level.
+     *
+     * Accepts a named level string (case-insensitive, spaces ignored),
+     * or a non-negative integer. Unknown strings and invalid numbers
+     * fall back to `FrameworkDebug` and emit a warning.
+     *
+     * @param requiredLevel - The desired level as a `Levels` constant, number, or string.
+     *
+     * @example
+     * Logger.loggingLevel = Logger.Levels.Warning;
+     * Logger.loggingLevel = 3;
+     * Logger.loggingLevel = "TestInformation";
+     */
+    static set loggingLevel(requiredLevel: string | number);
+    /**
+     * Returns the current logging level as a human-readable string.
+     *
+     * @returns A descriptive string for the current log level,
+     *   e.g. `"Test information (TSINF)"`.
+     */
+    static get loggingLevelText(): string;
+    /**
+     * Builds a human-readable description of the active logging configuration,
+     * combining the current level with any active filter range.
+     *
+     * Includes a Panic Mode preamble prefix when {@link panicMode} is active.
+     *
+     * @param level - The current logging level.
+     * @param minLevel - The minimum level of the active filter range (`NoOutput` if no filter).
+     * @param maxLevel - The maximum level of the active filter range (`NoOutput` if no filter).
+     * @returns A descriptive string. Returns the plain level name when no valid
+     *   filter range is active.
+     *
+     * @example
+     * Logger.loggingLevelDescription(Logger.Levels.FrameworkDebug, Logger.Levels.NoOutput, Logger.Levels.NoOutput);
+     * // => "Framework debug (FKDBG)"
+     */
+    static loggingLevelDescription(level: number, minLevel: number, maxLevel: number): string;
+    /**
+     * Returns the current log-level filter range.
+     *
+     * When both `min` and `max` are `NoOutput` (i.e. `0`), no filter is active
+     * and only {@link loggingLevel} controls output.
+     * When a valid range is set, messages whose level falls within
+     * `[min, max]` are also output regardless of the current logging level.
+     *
+     * @returns An object with `min` and `max` numeric level values.
+     */
+    static get loggingFilter(): {
+        min: number;
+        max: number;
+    };
+    /**
+     * Sets a log-level filter range for additional output inclusion.
+     *
+     * Messages whose level falls within `[min, max]` will be output even if
+     * they fall outside the current {@link loggingLevel}. Pass `NoOutput` (or
+     * omit) for either bound to disable that side of the filter.
+     *
+     * Both bounds accept a named level string or a non-negative integer.
+     * Invalid values fall back to `NoOutput` and emit a warning.
+     *
+     * @param min - Lower bound of the filter range (inclusive).
+     * @param max - Upper bound of the filter range (inclusive).
+     *
+     * @example
+     * Logger.loggingFilter = { min: Logger.Levels.Error, max: Logger.Levels.Warning };
+     */
+    static set loggingFilter({ min, max }: {
+        min?: string | number;
+        max?: string | number;
+    });
+    /**
+     * Returns the current `writeLine` formatting options.
+     *
+     * These control preamble suppression, max lines, timestamp format,
+     * and elapsed time format for log lines written via {@link writeLine}.
+     *
+     * @returns The active {@link WriteLineOptions} configuration object.
+     */
+    static get writeLineOptions(): WriteLineOptions;
+    /**
+     * Returns the current video attachment options.
+     *
+     * These defaults are used by {@link attachVideo} and {@link attachVideoFile}
+     * when no explicit options are provided.
+     *
+     * @returns The active {@link VideoOptions} configuration object.
+     */
+    static get videoOptions(): VideoOptions;
+    /**
+     * Sets the video attachment options used when attaching video to log output.
+     *
+     * Provided values are merged with the current options. If `height` or `width`
+     * fall outside the valid resolution limits, both dimensions are ignored and
+     * the existing values are retained.
+     *
+     * @param options - Partial or full {@link VideoOptions} to apply.
+     *
+     * @example
+     * Logger.videoOptions = { videoCodec: "mp4", width: 1280, height: 720 };
+     */
+    static set videoOptions(options: VideoOptions);
+    /**
+     * Clears the {@link logOutputCallback}, disabling callback-based log output.
+     *
+     * After calling this, log output will only go to the console
+     * (if {@link logToConsole} is `true`), or be silently dropped.
+     *
+     * @example
+     * Logger.clearOutputCallback();
+     */
+    static clearOutputCallback(): void;
+    /**
+     * Attaches a screenshot to the log output at the specified log level.
+     *
+     * The screenshot is base64-encoded and passed to {@link logOutputCallback}
+     * with a media type of `"base64:image/png"`. Accepts either a raw `Buffer`
+     * or an existing base64 string.
+     *
+     * Has no effect if the given `logLevel` does not pass the current level filter.
+     *
+     * @param logLevel - The log level at which to attach the screenshot.
+     * @param screenshot - A `Buffer` containing raw PNG data, or a base64-encoded string.
+     *
+     * @example
+     * Logger.attachScreenshot(Logger.Levels.TestDebug, screenshotBuffer);
+     */
+    static attachScreenshot(logLevel: number, screenshot: Buffer | string): void;
+    /**
+     * Attaches an HTML string to the log output at the specified log level.
+     *
+     * The HTML is passed to {@link logOutputCallback} with a media type of `"text/html"`.
+     * Useful for attaching rich content such as tables or styled reports.
+     *
+     * Has no effect if the given `logLevel` does not pass the current level filter.
+     *
+     * @param logLevel - The log level at which to attach the HTML.
+     * @param htmlString - A valid HTML string to attach.
+     *
+     * @example
+     * Logger.attachHTML(Logger.Levels.TestInformation, "<b>Test passed</b>");
+     */
+    static attachHTML(logLevel: number, htmlString: string): void;
+    /**
+     * Reads a video file from disk and attaches it to the log output.
+     *
+     * The file at `videoFilePath` is read as a `Buffer` and passed to
+     * {@link attachVideo}. If the file cannot be read, an error is processed
+     * via {@link throwErrorIfLogOutputFails}.
+     *
+     * Has no effect if the given `logLevel` does not pass the current level filter.
+     *
+     * @param logLevel - The log level at which to attach the video.
+     * @param videoFilePath - Absolute or relative path to the video file.
+     * @param options - Optional {@link VideoOptions} overriding the current defaults.
+     *
+     * @example
+     * Logger.attachVideoFile(Logger.Levels.TestDebug, "./recordings/run.webm");
+     */
+    static attachVideoFile(logLevel: number, videoFilePath: string, options?: VideoOptions): void;
+    /**
+     * Attaches a video buffer to the log output at the specified log level.
+     *
+     * The video is base64-encoded and wrapped in an HTML `<video>` element,
+     * then passed to {@link logOutputCallback} with a media type of `"text/html"`.
+     * When {@link panicMode} is active, the video element is given a
+     * `title="PANIC_MODE"` attribute.
+     *
+     * Has no effect if the given `logLevel` does not pass the current level filter.
+     *
+     * @param logLevel - The log level at which to attach the video.
+     * @param video - A `Buffer` containing the raw video data.
+     * @param options - Optional {@link VideoOptions} overriding the current defaults.
+     *
+     * @example
+     * Logger.attachVideo(Logger.Levels.TestDebug, videoBuffer, { width: 640, height: 360 });
+     */
+    static attachVideo(logLevel: number, video: Buffer, options?: VideoOptions): void;
+    /**
+     * Passes arbitrary data to the {@link logOutputCallback} at the specified log level.
+     *
+     * If the callback is not set, an error is logged instead. If the callback throws,
+     * the error is processed via {@link throwErrorIfLogOutputFails}.
+     *
+     * Has no effect if the given `logLevel` does not pass the current level filter.
+     *
+     * @param logLevel - The log level at which to attach the data.
+     * @param dataString - The data payload to pass to the callback.
+     * @param mediaType - A MIME-type-style string describing the data
+     *   (e.g. `"text/html"`, `"base64:image/png"`).
+     *
+     * @example
+     * Logger.attach(Logger.Levels.TestDebug, myPayload, "text/plain");
+     */
+    static attach(logLevel: number, dataString: string, mediaType: string): void;
+    /**
+     * Writes a log line (or multiple lines) at the specified log level.
+     *
+     * Multi-line strings are split and each line is written individually.
+     * If the total number of lines exceeds `maxLines`, intermediate lines
+     * are replaced with a single truncation notice.
+     *
+     * Each line is prefixed with a preamble (timestamp, elapsed time, calling method,
+     * and level label) unless suppressed via `options` or the global
+     * {@link writeLineOptions} configuration.
+     *
+     * Has no effect if the given `logLevel` does not pass the current level filter
+     * (unless {@link panicMode} is active).
+     *
+     * @param logLevel - The log level at which to write the message.
+     * @param textString - The message to log. May contain newlines.
+     * @param options - Optional per-call overrides for {@link WriteLineOptions}.
+     *
+     * @example
+     * Logger.writeLine(Logger.Levels.TestInformation, "Test started");
+     * Logger.writeLine(Logger.Levels.Warning, "Something looks off", { suppressAllPreamble: true });
+     */
+    static writeLine(logLevel: number, textString: string, options?: WriteLineOptions): void;
+    /** Builds a fresh default options object. Extracted so both the field initialiser and reset() share one source of truth. */
+    private static buildDefaultOptions;
+    private static levelToText;
+    private static levelFromText;
+    private static checkAndGetVideoResolution;
+    private static doWriteLine;
+    private static getPreAmble;
+    /**
+     * Left-pads a number (or numeric string) with zeroes to reach the required minimum length.
+     * Kept private and self-contained so `logger.ts` has no external utility dependencies.
+     */
+    private static pad;
+    private static getWriteTypeString;
+    private static callingMethodDetails;
+    private static isValidVideoResolutionNumber;
+    private static logLevelOk;
+    private static processError;
+    /**
+     * Truncates a string for safe display in error messages.
+     * Shows the first {@link ERROR_DISPLAY_STRING_HEAD_LENGTH} characters, an ellipsis,
+     * and the last {@link ERROR_DISPLAY_STRING_TAIL_LENGTH} characters when the string
+     * exceeds {@link ERROR_DISPLAY_STRING_MAX_LENGTH}.
+     */
+    private static truncateForDisplay;
+}

package/dist/types/logger/logger.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/logger/types.d.ts

@@ -0,0 +1,235 @@
+/**
+ * A numeric log level value, as defined by {@link Logger.Levels}.
+ */
+export type LogLevel = number;
+/**
+ * Options controlling how attached video content is encoded and sized.
+ *
+ * All fields are optional — omitted values fall back to the Logger's
+ * current video defaults. Use {@link ResolvedVideoOptions} where all
+ * fields are guaranteed to be present (i.e. after merging with defaults).
+ */
+export interface VideoOptions {
+    /**
+     * Video codec identifier embedded in the `<video>` tag's MIME type.
+     *
+     * @example "webm"
+     * @example "mp4"
+     */
+    videoCodec?: string;
+    /**
+     * Output video width in pixels.
+     * Must fall within the Logger's internal min/max resolution limits.
+     * If invalid, both width and height are ignored and the current defaults are kept.
+     */
+    width?: number;
+    /**
+     * Output video height in pixels.
+     * Must fall within the Logger's internal min/max resolution limits.
+     * If invalid, both width and height are ignored and the current defaults are kept.
+     */
+    height?: number;
+}
+/**
+ * A fully-resolved video options object in which all fields are guaranteed present.
+ *
+ * Used internally by `Logger` after merging any user-supplied {@link VideoOptions}
+ * with the configured defaults. Stored on {@link Options.video} so read sites
+ * never need to null-guard individual fields.
+ */
+export interface ResolvedVideoOptions {
+    /**
+     * Video codec identifier embedded in the `<video>` tag's MIME type.
+     *
+     * @example "webm"
+     * @example "mp4"
+     */
+    videoCodec: string;
+    /** Output video width in pixels. */
+    width: number;
+    /** Output video height in pixels. */
+    height: number;
+}
+/**
+ * Controls how {@link Logger.writeLine} formats and emits its output.
+ *
+ * All fields are optional — omitted values fall back to the Logger's
+ * current `writeLineOptions` defaults. Options can be supplied per-call
+ * to override defaults for a single `writeLine` invocation.
+ */
+export interface WriteLineOptions {
+    /**
+     * Maximum number of lines emitted from a multi-line input string.
+     *
+     * When the input contains more lines than this limit, intermediate lines
+     * are dropped and replaced with a single truncation notice showing how
+     * many lines were skipped. The first and last lines are always preserved.
+     *
+     * A value less than `1` is treated as `1`.
+     */
+    maxLines?: number;
+    /**
+     * When `true`, the preamble is suppressed for every line after the first
+     * in a multi-line message. The first line still receives a full preamble.
+     *
+     * Has no effect when {@link suppressAllPreamble} is `true`.
+     */
+    suppressMultilinePreamble?: boolean;
+    /**
+     * When `true`, the preamble is suppressed for every output line,
+     * whether the input is single-line or multi-line.
+     *
+     * Takes precedence over {@link suppressMultilinePreamble}.
+     */
+    suppressAllPreamble?: boolean;
+    /**
+     * When `true`, the wall-clock timestamp is omitted from the preamble.
+     *
+     * Has no effect when {@link suppressAllPreamble} is `true`.
+     */
+    suppressTimeStamp?: boolean;
+    /**
+     * When `true`, the elapsed-time value is omitted from the preamble.
+     *
+     * Has no effect when {@link suppressAllPreamble} is `true`.
+     */
+    suppressElapsed?: boolean;
+    /**
+     * Format string for the wall-clock timestamp, using date-fns syntax.
+     *
+     * Has no effect when {@link suppressTimeStamp} or {@link suppressAllPreamble}
+     * is `true`.
+     *
+     * @example "HH:mm:ss"
+     */
+    timeFormat?: string;
+    /**
+     * Format string for the elapsed time since the logger was started or last
+     * reset, using date-fns syntax.
+     *
+     * Has no effect when {@link suppressElapsed} or {@link suppressAllPreamble}
+     * is `true`.
+     *
+     * @example "mm:ss.SSS"
+     */
+    elapsedFormat?: string;
+    /**
+     * Number of additional call-stack frames to skip when determining the
+     * call-site label shown in the preamble.
+     *
+     * By default (`0` or `undefined`), the preamble shows the location of the
+     * `writeLine` call itself. Increase this when `writeLine` is invoked from
+     * inside a helper or wrapper and you want the preamble to reflect where
+     * *that wrapper* was called from rather than the wrapper's own location.
+     *
+     * @example
+     * // Without stackOffset the preamble shows the helper's location:
+     * //   "myLogHelper (myLogHelper.ts:12:5)"
+     * //
+     * // With stackOffset = 1 it shows the helper's caller instead:
+     * //   "MyTest.someStep (myTest.ts:45:3)"
+     * Logger.writeLine(Logger.Levels.TestInformation, message, { stackOffset: 1 });
+     *
+     * @remarks Not yet implemented — reserved for a future release.
+     */
+    stackOffset?: number;
+}
+/**
+ * General logging behaviour configuration used internally by `Logger`.
+ *
+ * Consumers should not construct this type directly. Use `Logger.reset()` to
+ * initialise the logger and the public getters/setters to modify individual
+ * settings at runtime.
+ */
+export interface Options {
+    /**
+     * The currently active log level.
+     *
+     * Messages whose level is less than or equal to this value are output
+     * (unless overridden by {@link filterMinCurrentLevel}/{@link filterMaxCurrentLevel}
+     * or {@link panicMode}).
+     */
+    loggingCurrentLevel: number;
+    /**
+     * Lower bound of the optional level-filter range (inclusive).
+     *
+     * Messages whose level falls within `[filterMinCurrentLevel, filterMaxCurrentLevel]`
+     * are output regardless of {@link loggingCurrentLevel}.
+     * Set to `Logger.Levels.NoOutput` when no filter is active.
+     */
+    filterMinCurrentLevel: number;
+    /**
+     * Upper bound of the optional level-filter range (inclusive).
+     *
+     * Messages whose level falls within `[filterMinCurrentLevel, filterMaxCurrentLevel]`
+     * are output regardless of {@link loggingCurrentLevel}.
+     * Set to `Logger.Levels.NoOutput` when no filter is active.
+     */
+    filterMaxCurrentLevel: number;
+    /**
+     * When `true`, log lines are also written to `console.log()` in addition
+     * to any configured {@link LogOutputCallbackSignature output callback}.
+     * When `false`, output goes only to the callback (if one is set).
+     */
+    logToConsole: boolean;
+    /**
+     * When `true`, any error thrown inside the output callback is re-thrown
+     * to the caller after being logged internally.
+     * When `false`, callback errors are suppressed and only logged internally.
+     */
+    throwErrorIfLogOutputFails: boolean;
+    /**
+     * When `true`, the current log level is ignored and every output call
+     * produces output — equivalent to setting {@link loggingCurrentLevel}
+     * to `Number.MAX_SAFE_INTEGER`.
+     */
+    panicMode: boolean;
+    /**
+     * Short prefix code prepended to the write-type label in each preamble
+     * when {@link panicMode} is active.
+     *
+     * @example "P"
+     */
+    panicCodePreamble: string;
+    /**
+     * Longer descriptor prefix prepended to level-description strings
+     * when {@link panicMode} is active.
+     *
+     * @example "P: "
+     */
+    panicDescriptorPreamble: string;
+    /** Active formatting options applied by {@link Logger.writeLine}. */
+    writeLine: WriteLineOptions;
+    /**
+     * Active video attachment options.
+     *
+     * Stored as {@link ResolvedVideoOptions} (all fields required) so that
+     * read sites inside `Logger` never need to null-guard individual properties.
+     */
+    video: ResolvedVideoOptions;
+}
+/**
+ * Signature of the callback invoked for every log output line or data attachment.
+ *
+ * Assign an implementation to `Logger.logOutputCallback` to receive all log
+ * output through a custom handler (e.g. a test reporter's `attach` method).
+ *
+ * If the callback throws, `Logger` catches the error and handles it according
+ * to the {@link Options.throwErrorIfLogOutputFails} setting.
+ *
+ * @param message - The fully formatted log line, or the raw data payload for
+ *   attachments (screenshot, video, HTML).
+ * @param mediaType - Optional MIME-type-style content descriptor indicating how
+ *   `message` should be interpreted. Examples:
+ *   - `"text/plain"` — a normal formatted log line (default when omitted)
+ *   - `"text/html"` — an HTML attachment
+ *   - `"base64:image/png"` — a base64-encoded PNG screenshot
+ *
+ * @example
+ * Logger.logOutputCallback = (message, mediaType) => {
+ *   myReporter.attach(message, { contentType: mediaType ?? "text/plain" });
+ * };
+ */
+export interface LogOutputCallbackSignature {
+    (message: string, mediaType?: string): void;
+}