@egi/smart-log 1.0.0

package/smart-log.js

@@ -0,0 +1,516 @@
+"use strict";
+// noinspection JSUnusedGlobalSymbols
+var __values = (this && this.__values) || function(o) {
+    var s = typeof Symbol === "function" && Symbol.iterator, m = s && o[s], i = 0;
+    if (m) return m.call(o);
+    if (o && typeof o.length === "number") return {
+        next: function () {
+            if (o && i >= o.length) o = void 0;
+            return { value: o && o[i++], done: !o };
+        }
+    };
+    throw new TypeError(s ? "Object is not iterable." : "Symbol.iterator is not defined.");
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.smartLog = exports.SmartLog = exports.SmartLogFormatElement = exports.SmartLocation = exports.SmartSeverityLevel = void 0;
+var smart_log_date_utils_1 = require("./smart-log-date-utils");
+var path = require("node:path");
+var process = require("node:process");
+var fs = require("node:fs");
+var os = require("node:os");
+var smart_tools_1 = require("./smart-tools");
+var SmartSeverityLevel;
+(function (SmartSeverityLevel) {
+    SmartSeverityLevel[SmartSeverityLevel["None"] = 0] = "None";
+    SmartSeverityLevel[SmartSeverityLevel["Fatal"] = 1] = "Fatal";
+    SmartSeverityLevel[SmartSeverityLevel["Error"] = 2] = "Error";
+    SmartSeverityLevel[SmartSeverityLevel["Warning"] = 3] = "Warning";
+    SmartSeverityLevel[SmartSeverityLevel["Info"] = 4] = "Info";
+    SmartSeverityLevel[SmartSeverityLevel["Verbose"] = 5] = "Verbose";
+    SmartSeverityLevel[SmartSeverityLevel["Debug"] = 6] = "Debug";
+    SmartSeverityLevel[SmartSeverityLevel["All"] = 9] = "All";
+})(SmartSeverityLevel || (exports.SmartSeverityLevel = SmartSeverityLevel = {}));
+var SmartLocation;
+(function (SmartLocation) {
+    SmartLocation["App"] = "APP";
+    SmartLocation["Frontend"] = "FRONTEND";
+    SmartLocation["Backend"] = "BACKEND";
+    SmartLocation["Database"] = "DATABASE";
+    SmartLocation["UpgradeManager"] = "UPGRADE-MANAGER";
+})(SmartLocation || (exports.SmartLocation = SmartLocation = {}));
+var SmartLogFormatElement;
+(function (SmartLogFormatElement) {
+    SmartLogFormatElement[SmartLogFormatElement["Severity"] = 0] = "Severity";
+    SmartLogFormatElement[SmartLogFormatElement["Type"] = 1] = "Type";
+    SmartLogFormatElement[SmartLogFormatElement["Timestamp"] = 2] = "Timestamp";
+    SmartLogFormatElement[SmartLogFormatElement["Message"] = 3] = "Message";
+    SmartLogFormatElement[SmartLogFormatElement["Location"] = 4] = "Location";
+})(SmartLogFormatElement || (exports.SmartLogFormatElement = SmartLogFormatElement = {}));
+/**
+ * A logging utility with severity-level control, flexible formatting, stack trace
+ * integration, and optional persistence via `ISmartLogDbWriter`.
+ *
+ * A default singleton `smartLog` is exported for convenience. Create additional
+ * instances for separate concerns (e.g. per-module loggers with different levels).
+ *
+ * ```typescript
+ * import { smartLog, SmartLog, SmartSeverityLevel } from "@egi/smart-log";
+ *
+ * smartLog.info("Application started");
+ *
+ * const verbose = new SmartLog({ logLevel: SmartSeverityLevel.Debug });
+ * verbose.debug("detailed trace");
+ * ```
+ */
+var SmartLog = /** @class */ (function () {
+    function SmartLog(options) {
+        var _a, _b, _c, _d, _e, _f;
+        //
+        this.dbWriter = null;
+        this.includeLocation = false;
+        this.isLogging = false;
+        this.logFifo = [];
+        this.logLevel = SmartSeverityLevel.Info;
+        this.projectRoot = null;
+        this.useLogChannels = false;
+        this.userId = null;
+        if (!options) {
+            options = {};
+        }
+        this.logLevel = (_a = options.logLevel) !== null && _a !== void 0 ? _a : SmartSeverityLevel.Info;
+        this.dbWriter = (_b = options.dbWriter) !== null && _b !== void 0 ? _b : null;
+        this.includeLocation = !!options.location;
+        this.userId = (_c = options.user) !== null && _c !== void 0 ? _c : os.userInfo().username;
+        this.useLogChannels = !!options.logChannels;
+        this.outputHook = (_d = options.outputHook) !== null && _d !== void 0 ? _d : null;
+        this.formatHook = (_e = options.formatHook) !== null && _e !== void 0 ? _e : null;
+        this.stackProvider = (_f = options.stackProvider) !== null && _f !== void 0 ? _f : null;
+        var dir = __dirname;
+        while (!this.projectRoot) {
+            if (!dir.includes("/node_modules/") && fs.existsSync(path.join(dir, "package.json"))) {
+                this.projectRoot = fs.realpathSync(dir);
+            }
+            else if (dir == "/") {
+                dir = process.env.PROJECT_ROOT || process.env.PROJECT_HOME || process.cwd();
+            }
+            else {
+                dir = path.dirname(dir);
+            }
+        }
+        this.setLogFormat(options);
+    }
+    /**
+     * Overrides the stack provider used for automatic caller location detection.
+     * Useful when `SmartLog` is wrapped in another class and the default stack
+     * resolution points to the wrapper instead of the actual call site.
+     *
+     * @param stackProvider - A function that returns a fresh `Error` at the call site.
+     */
+    SmartLog.prototype.setStackProvider = function (stackProvider) {
+        this.stackProvider = stackProvider;
+    };
+    /**
+     * Sets a text transformation hook. Called with the fully formatted log line before
+     * console output; must return the (modified) string.
+     *
+     * Use `setOutputHook()` instead if you need side effects or want to suppress output.
+     *
+     * @param hook - Function receiving `(text, message)` and returning the transformed text.
+     */
+    SmartLog.prototype.setFormatHook = function (hook) {
+        this.formatHook = hook;
+    };
+    /**
+     * Sets a general-purpose output hook. Called after formatting and before console output.
+     * Use this for side effects such as writing to a file, calling a webhook, or emitting events.
+     *
+     * Return `false` (or resolve a Promise to `false`) to suppress console output for the entry.
+     * Any other return value (including `void`) leaves console output enabled.
+     *
+     * @param hook - Function receiving `(text, message)`. May return `false | void`
+     *   or a `Promise` of the same.
+     */
+    SmartLog.prototype.setOutputHook = function (hook) {
+        this.outputHook = hook;
+    };
+    /**
+     * Configures the log format. Any property omitted in `format` retains its current value.
+     * The default sequence is: `Severity - Type - Timestamp: Message [Location]`.
+     *
+     * @param format - Partial `SmartLogFormat` to merge into the current format.
+     */
+    SmartLog.prototype.setLogFormat = function (format) {
+        if (!this.logFormat) {
+            this.logFormat = {
+                leading: "",
+                location: false,
+                lowerCase: false,
+                separator: "-",
+                sequence: [SmartLogFormatElement.Severity, SmartLogFormatElement.Type, SmartLogFormatElement.Timestamp, SmartLogFormatElement.Message, SmartLogFormatElement.Location]
+            };
+        }
+        if (format) {
+            for (var key in this.logFormat) {
+                if (format.hasOwnProperty(key)) {
+                    this.logFormat[key] = format[key];
+                }
+            }
+        }
+    };
+    /**
+     * Returns the current minimum log severity level.
+     */
+    SmartLog.prototype.getLogLevel = function () {
+        return this.logLevel;
+    };
+    /**
+     * Sets the minimum log severity level. Messages with a higher level number are dropped.
+     *
+     * @param level - The new minimum level.
+     */
+    SmartLog.prototype.setLogLevel = function (level) {
+        this.logLevel = level;
+    };
+    /**
+     * Returns `true` if a db writer is currently set.
+     */
+    SmartLog.prototype.hasDbWriter = function () {
+        return this.dbWriter !== null;
+    };
+    /**
+     * Sets or replaces the db writer. Pass `null` to disable db logging.
+     *
+     * @param dbWriter - An `ISmartLogDbWriter` implementation, or `null` to clear.
+     */
+    SmartLog.prototype.setDbWriter = function (dbWriter) {
+        this.dbWriter = dbWriter;
+    };
+    /**
+     * Sets the timezone used when formatting timestamps in log output.
+     * Accepts any IANA timezone identifier (e.g. `"UTC"`, `"Europe/Berlin"`).
+     *
+     * @param timezone - IANA timezone string.
+     */
+    SmartLog.prototype.setTimezone = function (timezone) {
+        this.timezone = timezone;
+    };
+    /**
+     * Controls whether the caller's source location is appended to each log line.
+     *
+     * @param includeLocation - `true` to include location, `false` to omit.
+     */
+    SmartLog.prototype.setIncludeLocation = function (includeLocation) {
+        this.includeLocation = includeLocation;
+    };
+    /**
+     * Returns `true` if caller location is currently included in log output.
+     */
+    SmartLog.prototype.getIncludeLocation = function () {
+        return this.includeLocation;
+    };
+    /**
+     * Sets the user identifier stamped on every subsequent log entry.
+     *
+     * @param userId - A string or numeric user identifier.
+     */
+    SmartLog.prototype.setUserId = function (userId) {
+        this.userId = userId;
+    };
+    SmartLog.prototype.debug = function (message, options) {
+        this.writeLog(SmartSeverityLevel.Debug, message, options);
+    };
+    SmartLog.prototype.error = function (message, options) {
+        this.writeLog(SmartSeverityLevel.Error, message, options);
+    };
+    SmartLog.prototype.fatal = function (message, options) {
+        this.writeLog(SmartSeverityLevel.Fatal, message, options);
+    };
+    SmartLog.prototype.info = function (message, options) {
+        this.writeLog(SmartSeverityLevel.Info, message, options);
+    };
+    SmartLog.prototype.verbose = function (message, options) {
+        this.writeLog(SmartSeverityLevel.Verbose, message, options);
+    };
+    SmartLog.prototype.warning = function (message, options) {
+        this.writeLog(SmartSeverityLevel.Warning, message, options);
+    };
+    SmartLog.prototype.write = function (message, options) {
+        this.writeLog(null, message, options);
+    };
+    /**
+     * Core logging method. Normalises the arguments, resolves the caller location,
+     * and dispatches to `log()`.
+     *
+     * @param severityLevel - Severity of the message, or `null` for unseveritied `write()` calls.
+     * @param messageOrError - The message string or an `Error` whose `.message` is used.
+     * @param optionsOrError - Per-message options, or an `Error` stored as `data`.
+     */
+    SmartLog.prototype.writeLog = function (severityLevel, messageOrError, optionsOrError) {
+        var _a, _b, _c, _d, _e;
+        var options;
+        if (optionsOrError) {
+            if (optionsOrError instanceof Error || typeof optionsOrError != "object") {
+                options = { data: optionsOrError };
+            }
+            else {
+                options = optionsOrError;
+            }
+        }
+        else {
+            options = {};
+        }
+        var message;
+        if (messageOrError instanceof Error) {
+            message = messageOrError.message;
+            if (!options.data) {
+                options.data = messageOrError;
+            }
+        }
+        else if (typeof messageOrError.toString == "function") {
+            message = messageOrError.toString();
+        }
+        else {
+            message = String(messageOrError);
+        }
+        this.log({
+            type: (_a = options.type) !== null && _a !== void 0 ? _a : SmartLocation.App,
+            location: (_b = options.location) !== null && _b !== void 0 ? _b : smart_tools_1.tools.getCallerFromStack(this.stackProvider, {
+                projectRoot: this.projectRoot,
+                ignoreFiles: [__filename]
+            }),
+            severityLevel: severityLevel,
+            message: message,
+            data: options.data,
+            timestamp: (_c = options.timestamp) !== null && _c !== void 0 ? _c : Date.now(),
+            user: this.userId,
+            skipConsole: (_d = options.skipConsole) !== null && _d !== void 0 ? _d : false,
+            skipDatabase: (_e = options.skipDatabase) !== null && _e !== void 0 ? _e : false
+        });
+    };
+    /**
+     * Dispatches a fully-formed `LogMessage`. Filters by `logLevel`, formats the text,
+     * runs `outputHook` and `formatHook`, writes to the console (unless suppressed),
+     * and forwards to the db writer.
+     *
+     * Calls during an in-progress async db write are queued and replayed in order.
+     *
+     * @param messageObj - The complete log entry to process.
+     */
+    SmartLog.prototype.log = function (messageObj) {
+        var _this = this;
+        try {
+            if (this.isLogging) {
+                this.logFifo.push(messageObj);
+            }
+            else {
+                this.isLogging = true;
+                var withinLevel = !messageObj.severityLevel || messageObj.severityLevel <= this.logLevel;
+                if (withinLevel) {
+                    var text = this.formatMessage(messageObj);
+                    this.writeToConsole(text, messageObj);
+                }
+                if (withinLevel && !messageObj.skipDatabase && this.dbWriter) {
+                    try {
+                        var result = this.dbWriter.write(messageObj);
+                        if (result instanceof Promise) {
+                            result.then(function () {
+                                _this.isLogging = false;
+                                _this.nextStackEntry();
+                            }).catch(function (error) {
+                                _this.error("unable to write log entry to database", { skipDatabase: true, data: error });
+                                _this.isLogging = false;
+                                _this.nextStackEntry();
+                            });
+                        }
+                        else {
+                            this.isLogging = false;
+                            this.nextStackEntry();
+                        }
+                    }
+                    catch (error) {
+                        this.error("unable to write log entry to database", { skipDatabase: true, data: error });
+                        this.isLogging = false;
+                        this.nextStackEntry();
+                    }
+                }
+                else {
+                    this.isLogging = false;
+                    this.nextStackEntry();
+                }
+            }
+        }
+        catch (error) {
+            this.isLogging = false;
+            console.error("fatal logging error", error);
+        }
+    };
+    /**
+     * Formats a `LogMessage` into a string using the current log format sequence.
+     * Optionally accepts a custom `sequence` to override the instance format for this call.
+     *
+     * @param message - The log entry to format.
+     * @param sequence - Optional sequence override; uses the instance format when omitted.
+     * @returns The formatted log line string.
+     */
+    SmartLog.prototype.formatMessage = function (message, sequence) {
+        var e_1, _a;
+        var _b;
+        var text = "";
+        var beyondText = false;
+        try {
+            for (var _c = __values((sequence !== null && sequence !== void 0 ? sequence : this.logFormat.sequence)), _d = _c.next(); !_d.done; _d = _c.next()) {
+                var element = _d.value;
+                if (element != SmartLogFormatElement.Location || this.logFormat.location) {
+                    if (text === "") {
+                        text += this.logFormat.leading;
+                    }
+                    else if (element == SmartLogFormatElement.Message) {
+                        text += ": ";
+                        beyondText = true;
+                    }
+                    else if (beyondText) {
+                        text += " ";
+                    }
+                    else {
+                        text += this.logFormat.separator;
+                    }
+                    if (typeof element == "string") {
+                        text += element;
+                    }
+                    else if (typeof element == "function") {
+                        text += element();
+                    }
+                    else {
+                        switch (element) {
+                            case SmartLogFormatElement.Severity:
+                                var severityCode = this.severityCodeFromLevel(message.severityLevel);
+                                text += this.logFormat.lowerCase ? severityCode.toLowerCase() : severityCode;
+                                break;
+                            case SmartLogFormatElement.Type:
+                                text += message.type ? (this.logFormat.lowerCase ? message.type.substring(0, 1).toLowerCase() : message.type.substring(0, 1)) : "";
+                                break;
+                            case SmartLogFormatElement.Timestamp:
+                                text += (0, smart_log_date_utils_1.toSmartDbTimestamp)(message.timestamp, this.timezone);
+                                break;
+                            case SmartLogFormatElement.Message:
+                                text += (_b = message.message) !== null && _b !== void 0 ? _b : "";
+                                break;
+                            case SmartLogFormatElement.Location:
+                                if (this.logFormat.location) {
+                                    text += "[" + message.location + "]";
+                                }
+                                break;
+                        }
+                    }
+                }
+                text = text.trim();
+            }
+        }
+        catch (e_1_1) { e_1 = { error: e_1_1 }; }
+        finally {
+            try {
+                if (_d && !_d.done && (_a = _c.return)) _a.call(_c);
+            }
+            finally { if (e_1) throw e_1.error; }
+        }
+        var data = this.stringifyData(message.data);
+        if (data) {
+            text += " (".concat(data, ")");
+        }
+        return this.formatHook && !sequence ? this.formatHook(text, message) : text;
+    };
+    /**
+     * Returns the single-letter severity code for a given `SmartSeverityLevel`.
+     * Unknown levels fall back to the `Info` code.
+     *
+     * @param level - The severity level to look up.
+     * @returns A single uppercase letter: `F`, `E`, `W`, `I`, `D`, etc.
+     */
+    SmartLog.prototype.severityCodeFromLevel = function (level) {
+        var _a;
+        return (_a = SmartLog.severityLevelToCode[level]) !== null && _a !== void 0 ? _a : SmartLog.severityLevelToCode[SmartSeverityLevel.Info];
+    };
+    SmartLog.prototype.writeToConsole = function (text, messageObj) {
+        var _this = this;
+        if (messageObj.skipConsole) {
+            return;
+        }
+        if (this.outputHook) {
+            var result = this.outputHook(text, messageObj);
+            if (result instanceof Promise) {
+                result.then(function (res) {
+                    if (res !== false) {
+                        _this.printToConsole(text, messageObj);
+                    }
+                }).catch(function (error) {
+                    console.error("outputHook error", error);
+                    _this.printToConsole(text, messageObj);
+                });
+            }
+            else {
+                if (result !== false) {
+                    this.printToConsole(text, messageObj);
+                }
+            }
+        }
+        else {
+            this.printToConsole(text, messageObj);
+        }
+    };
+    SmartLog.prototype.printToConsole = function (text, messageObj) {
+        var logFn;
+        if (this.useLogChannels) {
+            switch (messageObj.severityLevel) {
+                case SmartSeverityLevel.Fatal:
+                case SmartSeverityLevel.Error:
+                    logFn = console.error;
+                    break;
+                case SmartSeverityLevel.Warning:
+                    logFn = console.warn;
+                    break;
+                case SmartSeverityLevel.Info:
+                case SmartSeverityLevel.Verbose:
+                    logFn = console.info;
+                    break;
+                case SmartSeverityLevel.Debug:
+                    logFn = console.debug;
+                    break;
+                default:
+                    logFn = console.log;
+                    break;
+            }
+        }
+        else {
+            logFn = console.log;
+        }
+        logFn(text);
+    };
+    SmartLog.prototype.stringifyData = function (data) {
+        if (data) {
+            if (data instanceof Error) {
+                return data.stack;
+            }
+            else if (typeof data == "object") {
+                return JSON.stringify(data);
+            }
+            else if (typeof data.toString == "function") {
+                return data.toString();
+            }
+            else {
+                return String(data);
+            }
+        }
+        return null;
+    };
+    SmartLog.prototype.nextStackEntry = function () {
+        if (this.logFifo.length > 0) {
+            var entry = this.logFifo.shift();
+            this.log(entry);
+        }
+    };
+    // corresponds with SmartSeverityLevel enum
+    SmartLog.severityLevelToCode = ["-", "F", "E", "W", "I", "I", "D", "A", "-", "-", "*"];
+    return SmartLog;
+}());
+exports.SmartLog = SmartLog;
+exports.smartLog = new SmartLog();

package/smart-tools.d.ts

@@ -0,0 +1,64 @@
+export interface GetCallerOptions {
+    ignoreFiles?: string[];
+    projectRoot?: string;
+}
+export interface FrameData {
+    columnNumber: number;
+    fileName: string;
+    functionName: string;
+    lineNumber: number;
+    methodName: string;
+    native: boolean;
+    typeName: string;
+}
+export declare class SmartTools {
+    /**
+     * Captures the stack trace starting from the point just below the provided function.
+     *
+     * @param belowFn - A reference function to exclude from the stack trace.
+     * @returns An array of FrameData objects representing the captured stack trace.
+     */
+    getStackTrace(belowFn?: () => any): FrameData[];
+    /**
+     * Parses an error's stack trace into an array of FrameData objects.
+     *
+     * @param err - An error object containing the stack trace.
+     * @returns An array of FrameData objects parsed from the error's stack trace.
+     */
+    parseStackTrace(err: Error): FrameData[];
+    /**
+     * Retrieves caller information from the stack trace, excluding specified files or patterns.
+     *
+     * @param {Error | (() => Error)} [errorOrStackProvider] - An error object or function returning an error,
+     *     used to extract the stack trace. Defaults to capturing the current stack trace if omitted.
+     * @param options - Optional settings for filtering and formatting the caller information.
+     * @returns {string} A string with the format "fileName:lineNumber (functionName)",
+     *     or "unknown location" if caller information cannot be determined.
+     */
+    getCallerFromStack(errorOrStackProvider?: Error | (() => Error), options?: GetCallerOptions): string;
+    kebabCase(s: string): string;
+    snakeCase(s: string): string;
+    camelCase(s: string): string;
+    pascalCase(s: string): string;
+    titleCase(s: string): string;
+    constantCase(s: string): string;
+    clone<T extends object>(obj: T): T;
+    cloneDeep<T>(obj: T): T;
+    isSimpleObject(obj: any): boolean;
+    isObject(obj: any): boolean;
+    isArray(obj: any): boolean;
+    isString(obj: any): boolean;
+    isNumber(obj: any): boolean;
+    isBoolean(obj: any): boolean;
+    isNull(obj: any): boolean;
+    isUndefined(obj: any): boolean;
+    isFunction(obj: any): boolean;
+    isDate(obj: any): boolean;
+    isRegExp(obj: any): boolean;
+    isError(obj: any): boolean;
+    isSymbol(obj: any): boolean;
+    isEmpty(obj: any): boolean;
+    isPrimitive(obj: any): boolean;
+    private splitWords;
+}
+export declare const tools: SmartTools;