@egi/smart-log 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Marcel Egloff
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,206 @@
+# smart-log
+
+A TypeScript logging library with severity levels, flexible formatting, stack trace integration, and optional persistence via a pluggable db writer.
+
+## Installation
+
+```bash
+npm install @egi/smart-log
+```
+
+## Quick Start
+
+```typescript
+import { smartLog, SmartSeverityLevel } from "@egi/smart-log";
+
+smartLog.info("Application started");
+smartLog.warning("Low disk space");
+smartLog.error(new Error("Something went wrong"));
+```
+
+A singleton instance `smartLog` is exported for convenience. Create additional instances as needed:
+
+```typescript
+import { SmartLog } from "@egi/smart-log";
+
+const log = new SmartLog({ logLevel: SmartSeverityLevel.Debug });
+log.debug("detailed trace");
+```
+
+## Severity Levels
+
+```typescript
+enum SmartSeverityLevel {
+    None = 0, Fatal = 1, Error = 2, Warning = 3,
+    Info = 4, Verbose = 5, Debug = 6, All = 9
+}
+```
+
+Methods: `fatal()`, `error()`, `warning()`, `info()`, `verbose()`, `debug()`, `write()` (no severity).
+
+Each method accepts a string, an `Error`, or a string + `SmartMessageOptions`:
+
+```typescript
+log.error("fetch failed", { data: err, location: "api.ts:42" });
+log.info("user logged in", { type: "BACKEND", timestamp: new Date() });
+log.debug("internal detail", { skipConsole: true });   // db writer only
+log.info("console only",    { skipDatabase: true });   // console only
+```
+
+## Options
+
+```typescript
+const log = new SmartLog({
+    logLevel: SmartSeverityLevel.Info,  // minimum level to process
+    logChannels: true,                  // route to console.error/warn/info/debug by level
+    location: true,                     // include caller location in output
+    leading: "[APP]",                   // prefix every line
+    separator: " | ",                   // separator between format elements
+    lowerCase: false,                   // lowercase severity codes
+    user: "admin",                      // user id stamped on each log entry
+    dbWriter: myWriter,                 // persist entries (see below)
+    outputHook: (text, msg) => {},      // side-effect hook; return { suppress: true } to skip console
+    formatHook: (text, msg) => text,     // transform output text before console
+    stackProvider: () => new Error(),   // custom stack source for caller detection
+});
+```
+
+## Log Format
+
+The output format is fully configurable via `sequence`. Elements can be enum values, fixed strings, or functions:
+
+```typescript
+import { SmartLog, SmartLogFormatElement } from "@egi/smart-log";
+
+const log = new SmartLog({
+    leading: "%",
+    lowerCase: true,
+    location: true,
+    sequence: [
+        SmartLogFormatElement.Severity,
+        "myapp",
+        SmartLogFormatElement.Timestamp,
+        SmartLogFormatElement.Message,
+        SmartLogFormatElement.Location,
+        () => process.pid.toString()
+    ]
+});
+```
+
+| Element | Output |
+|---|---|
+| `Severity` | Single letter code: `F E W I I D` |
+| `Type` | First letter of the location type (App → `A`) |
+| `Timestamp` | `2024-03-15 14:30:00.000` |
+| `Message` | The log message text |
+| `Location` | `[file.ts:42 (functionName)]` |
+
+Default sequence: `Severity - Type - Timestamp: Message [Location]`
+
+## Output Hook
+
+`outputHook` is called after formatting and before console output. Use it for side effects — writing to a file, sending to a remote service, emitting events — without needing to implement a full `ISmartLogDbWriter`.
+
+Return `false` to prevent the entry from appearing on the console. Both sync and async hooks are supported.
+
+```typescript
+import { SmartLog, LogMessage } from "@egi/smart-log";
+
+const log = new SmartLog({
+    outputHook: (text: string, message: LogMessage) => {
+        fs.appendFileSync("app.log", text + "\n");
+        // return false to hide from console as well
+    }
+});
+
+// or set it later:
+log.setOutputHook(async (text, message) => {
+    await sendToSlack(text);
+    return false;  // already sent, no need to also print
+});
+
+// transform text only:
+log.setFormatHook((text) => `[MyApp] ${text}`);
+```
+
+`formatHook` and `outputHook` serve different purposes:
+
+| Hook | Purpose | Must return |
+|---|---|---|
+| `formatHook` | Transform the formatted text | Modified string |
+| `outputHook` | Side effects / suppress console | `void` or `false` |
+
+## Database Persistence
+
+Implement `ISmartLogDbWriter` to persist log entries:
+
+```typescript
+import { ISmartLogDbWriter, LogMessage } from "@egi/smart-log";
+
+class MyDbWriter implements ISmartLogDbWriter {
+    write(entry: LogMessage): Promise<void> | void {
+        // entry contains: severityLevel, type, location, message, data, timestamp, user
+        return db.insert("logs", entry);
+    }
+}
+
+const log = new SmartLog({ dbWriter: new MyDbWriter() });
+
+// change or disable the writer at runtime:
+log.setDbWriter(null);
+```
+
+The writer receives the raw `LogMessage` object — sync or async writers are both supported.
+
+## Location Types
+
+```typescript
+enum SmartLocation {
+    App = "APP",
+    Frontend = "FRONTEND",
+    Backend = "BACKEND",
+    Database = "DATABASE",
+    UpgradeManager = "UPGRADE-MANAGER"
+}
+```
+
+## Date Utilities
+
+```typescript
+import { toSmartDbDate, toSmartDbTimestamp, smartDbToDate, smartDbToDateTime } from "@egi/smart-log";
+
+toSmartDbDate(new Date())                // "2024-03-15 14:30:00"
+toSmartDbTimestamp(new Date())           // "2024-03-15 14:30:00.000"
+smartDbToDate("2024-03-15 14:30:00")     // Date object
+smartDbToDateTime(1710508200000)         // Luxon DateTime object
+```
+
+## SmartError
+
+A structured error class for use throughout the stack:
+
+```typescript
+import { SmartError, SmartSeverityLevel, SmartLocation } from "@egi/smart-log";
+
+throw new SmartError({
+    message: "Record not found",
+    code: 404,
+    type: SmartSeverityLevel.Error,
+    location: SmartLocation.Backend
+});
+```
+
+## SmartTools
+
+Utility singleton for string conversions and stack inspection:
+
+```typescript
+import { tools } from "@egi/smart-log";
+
+tools.camelCase("my_field_name")   // "myFieldName"
+tools.snakeCase("myFieldName")     // "my_field_name"
+tools.kebabCase("MyComponent")     // "my-component"
+tools.pascalCase("my_model")       // "MyModel"
+
+tools.getCallerFromStack()         // "src/app.ts:42 (doSomething)"
+```

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@egi/smart-log",
+  "version": "1.0.0",
+  "description": "Smart logging library with severity levels, flexible formatting, and optional DB persistence",
+  "author": "Marcel Egloff",
+  "main": "./smart-log-api.js",
+  "repository": {
+    "type": "git",
+    "url": "https://vault.pegasus-consulting.ch/smart-log"
+  },
+  "keywords": [
+    "logging",
+    "smart",
+    "log",
+    "typescript",
+    "severity",
+    "logger"
+  ],
+  "exports": {
+    ".": {
+      "default": "./smart-log-api.js"
+    }
+  },
+  "types": "./smart-log-api.d.ts",
+  "dependencies": {
+    "luxon": "^3.5.0"
+  },
+  "license": "MIT"
+}

package/smart-error.d.ts

@@ -0,0 +1,22 @@
+import { SmartLocation, SmartSeverityLevel } from "./smart-log";
+export type SmartErrorLocation = SmartLocation;
+export interface SmartErrorData {
+    code?: number | string;
+    info?: Record<string, any>;
+    location?: SmartLocation;
+    message: string;
+    name: string;
+    timestamp?: Date | string | number;
+    type?: SmartSeverityLevel;
+}
+export declare class SmartError extends Error implements SmartErrorData {
+    code: number | string;
+    info: Record<string, any>;
+    location: SmartLocation;
+    timestamp: Date | string | number;
+    type: SmartSeverityLevel;
+    private smartErrorKeys;
+    constructor(message: any);
+    toObject(): SmartErrorData;
+    toString(): string;
+}

package/smart-error.js

@@ -0,0 +1,123 @@
+"use strict";
+// noinspection JSUnusedGlobalSymbols
+var __extends = (this && this.__extends) || (function () {
+    var extendStatics = function (d, b) {
+        extendStatics = Object.setPrototypeOf ||
+            ({ __proto__: [] } instanceof Array && function (d, b) { d.__proto__ = b; }) ||
+            function (d, b) { for (var p in b) if (Object.prototype.hasOwnProperty.call(b, p)) d[p] = b[p]; };
+        return extendStatics(d, b);
+    };
+    return function (d, b) {
+        if (typeof b !== "function" && b !== null)
+            throw new TypeError("Class extends value " + String(b) + " is not a constructor or null");
+        extendStatics(d, b);
+        function __() { this.constructor = d; }
+        d.prototype = b === null ? Object.create(b) : (__.prototype = b.prototype, new __());
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SmartError = void 0;
+var smart_log_1 = require("./smart-log");
+var SmartError = /** @class */ (function (_super) {
+    __extends(SmartError, _super);
+    function SmartError(message) {
+        var _this = this;
+        var errorKeys = ["message", "name", "code", "type", "location", "timestamp", "info"];
+        var newMessage;
+        var code;
+        var type;
+        var location;
+        var name;
+        var timestamp;
+        var info;
+        if (message === undefined || typeof message == "string") {
+            newMessage = message;
+        }
+        else if (typeof message == "object") {
+            if (typeof message.message == "string") {
+                newMessage = message.message;
+            }
+            else if (typeof message.text == "string") {
+                newMessage = message.text;
+            }
+            else if (typeof message.error == "string") {
+                newMessage = message.error;
+            }
+            else {
+                newMessage = "Error";
+            }
+            name = message.name;
+            code = message.code;
+            type = message.type;
+            location = message.location;
+            timestamp = message.timestamp;
+            if (!message.constructor) {
+                var keys = Object.keys(message).filter(function (key) { return !errorKeys.includes(key); });
+                if (keys.length > 0) {
+                    info = {};
+                    keys.forEach(function (key) {
+                        info[key] = message[key];
+                    });
+                }
+            }
+        }
+        else if (typeof message.toString == "function") {
+            newMessage = message.toString();
+        }
+        else {
+            newMessage = message;
+        }
+        _this = _super.call(this, newMessage) || this;
+        _this.name = name !== null && name !== void 0 ? name : "";
+        _this.code = code !== null && code !== void 0 ? code : -1;
+        _this.type = type !== null && type !== void 0 ? type : smart_log_1.SmartSeverityLevel.Error;
+        if (location) {
+            _this.location = location;
+        }
+        if (timestamp) {
+            _this.timestamp = timestamp;
+        }
+        if (info) {
+            _this.info = info;
+        }
+        _this.smartErrorKeys = errorKeys;
+        return _this;
+    }
+    SmartError.prototype.toObject = function () {
+        var _this = this;
+        var obj = {
+            name: this.name,
+            message: this.message
+        };
+        this.smartErrorKeys.forEach(function (key) {
+            if (key != "name" && key != "message") {
+                if (_this[key]) {
+                    obj[key] = _this[key];
+                }
+            }
+        });
+        return obj;
+    };
+    SmartError.prototype.toString = function () {
+        var output = _super.prototype.toString.call(this);
+        var addition = "";
+        if (this.type) {
+            addition += this.type;
+        }
+        if (this.location) {
+            if (addition !== "") {
+                addition += "-";
+            }
+            addition += this.location;
+        }
+        if (this.code) {
+            if (addition !== "") {
+                addition += " #";
+            }
+            addition += this.code;
+        }
+        return output + " (" + addition + ")";
+    };
+    return SmartError;
+}(Error));
+exports.SmartError = SmartError;

package/smart-log-api.d.ts

@@ -0,0 +1,4 @@
+export * from "./smart-error";
+export * from "./smart-tools";
+export * from "./smart-log";
+export * from "./smart-log-date-utils";

package/smart-log-api.js

@@ -0,0 +1,21 @@
+"use strict";
+// noinspection JSUnusedGlobalSymbols
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./smart-error"), exports);
+__exportStar(require("./smart-tools"), exports);
+__exportStar(require("./smart-log"), exports);
+__exportStar(require("./smart-log-date-utils"), exports);

package/smart-log-date-utils.d.ts

@@ -0,0 +1,24 @@
+import { DateTime } from "luxon";
+export declare const SmartLogDateRegexp: RegExp;
+export declare const SmartLogTimestampRegexp: RegExp;
+export declare const validDateTimeFormats: string[];
+/**
+ * Returns a DB date string for a given timezone (local timezone if 'zone' omitted).
+ */
+export declare function toSmartDbDate(date: Date | number | DateTime, zone?: string, addZone?: boolean): string | null;
+/**
+ * Returns a DB timestamp string for a given timezone (local timezone if 'zone' omitted).
+ */
+export declare function toSmartDbTimestamp(date: string | number | Date | DateTime, timezone?: string): string | null;
+/**
+ * Returns a timestamp string for a given timezone (local timezone if 'zone' omitted).
+ */
+export declare function toSmartZoneTimestamp(date: Date | number | DateTime, zone?: string, omitZone?: boolean): string | null;
+/**
+ * Converts a date value to a JavaScript Date object.
+ */
+export declare function smartDbToDate(date: Date | number | string | DateTime, zone?: string): Date | null;
+/**
+ * Converts a date value to a Luxon DateTime object in the given zone (local timezone if 'zone' omitted).
+ */
+export declare function smartDbToDateTime(date: Date | number | string | DateTime, zone?: string): DateTime | null;

package/smart-log-date-utils.js

@@ -0,0 +1,129 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validDateTimeFormats = exports.SmartLogTimestampRegexp = exports.SmartLogDateRegexp = void 0;
+exports.toSmartDbDate = toSmartDbDate;
+exports.toSmartDbTimestamp = toSmartDbTimestamp;
+exports.toSmartZoneTimestamp = toSmartZoneTimestamp;
+exports.smartDbToDate = smartDbToDate;
+exports.smartDbToDateTime = smartDbToDateTime;
+var luxon_1 = require("luxon");
+exports.SmartLogDateRegexp = /^(\d{4}-[01]\d-[0-3]\d [0-2]\d:[0-5]\d:[0-5]\d)(Z|[+-]\d\d:\d\d)?$/;
+exports.SmartLogTimestampRegexp = /^(\d{4}-[01]\d-[0-3]\d [0-2]\d:[0-5]\d:[0-5]\d\.\d{3})(Z|[+-]\d\d:\d\d)?$/;
+exports.validDateTimeFormats = [
+    "yyyy-MM-dd",
+    "yyyy-MM-ddZZ",
+    "yyyy-MM-dd HH:mm:ss",
+    "yyyy-MM-dd HH:mm:ssZZ",
+    "yyyy-MM-dd HH:mm:ss.u",
+    "yyyy-MM-dd HH:mm:ss.uZZ",
+    "yyyy-MM-dd'T'HH:mm:ss",
+    "yyyy-MM-dd'T'HH:mm:ssZZ",
+    "yyyy-MM-dd'T'HH:mm:ss.u",
+    "yyyy-MM-dd'T'HH:mm:ss.uZZ"
+];
+/**
+ * Returns a DB date string for a given timezone (local timezone if 'zone' omitted).
+ */
+function toSmartDbDate(date, zone, addZone) {
+    var timestampString = null;
+    if (date) {
+        var dt = void 0;
+        if (typeof date == "number") {
+            dt = luxon_1.DateTime.fromMillis(date, { zone: zone });
+        }
+        else if (date instanceof Date) {
+            dt = luxon_1.DateTime.fromJSDate(date, { zone: zone });
+        }
+        else {
+            dt = date;
+        }
+        if (zone && addZone) {
+            if (zone.toUpperCase() == "UTC" || zone.toUpperCase() == "GMT") {
+                timestampString = dt.toFormat("yyyy-MM-dd HH:mm:ss") + "Z";
+            }
+            else {
+                timestampString = dt.toFormat("yyyy-MM-dd HH:mm:ssZZ");
+            }
+        }
+        else {
+            timestampString = dt.toFormat("yyyy-MM-dd HH:mm:ss");
+        }
+    }
+    else {
+        throw "no date given to toSmartDbDate()";
+    }
+    return timestampString;
+}
+/**
+ * Returns a DB timestamp string for a given timezone (local timezone if 'zone' omitted).
+ */
+function toSmartDbTimestamp(date, timezone) {
+    var timestampString = null;
+    var dt = smartDbToDateTime(date !== null && date !== void 0 ? date : new Date());
+    if (timezone) {
+        timestampString = dt.setZone(timezone).toFormat("yyyy-MM-dd HH:mm:ss.uZZ").replace("+00:00", "Z");
+    }
+    else {
+        timestampString = dt.toFormat("yyyy-MM-dd HH:mm:ss.u");
+    }
+    return timestampString;
+}
+/**
+ * Returns a timestamp string for a given timezone (local timezone if 'zone' omitted).
+ */
+function toSmartZoneTimestamp(date, zone, omitZone) {
+    var timestampString = null;
+    if (date) {
+        var dt = void 0;
+        if (typeof date == "number") {
+            dt = luxon_1.DateTime.fromMillis(date, { zone: zone });
+        }
+        else if (date instanceof Date) {
+            dt = luxon_1.DateTime.fromJSDate(date, { zone: zone });
+        }
+        else {
+            dt = date.setZone(zone);
+        }
+        if (omitZone) {
+            timestampString = dt.toFormat("yyyy-MM-dd HH:mm:ss.u");
+        }
+        else {
+            timestampString = dt.toFormat("yyyy-MM-dd HH:mm:ss.uZZ").replace("+00:00", "Z");
+        }
+    }
+    return timestampString;
+}
+/**
+ * Converts a date value to a JavaScript Date object.
+ */
+function smartDbToDate(date, zone) {
+    var dt = smartDbToDateTime(date, zone);
+    return dt && dt.isValid ? dt.toJSDate() : null;
+}
+/**
+ * Converts a date value to a Luxon DateTime object in the given zone (local timezone if 'zone' omitted).
+ */
+function smartDbToDateTime(date, zone) {
+    var dt = null;
+    if (date) {
+        if (typeof date == "number") {
+            dt = luxon_1.DateTime.fromMillis(date, { zone: zone });
+        }
+        else if (typeof date == "string") {
+            var pattern = exports.validDateTimeFormats.find(function (format) {
+                var d = luxon_1.DateTime.fromFormat(date, format);
+                return d.isValid;
+            });
+            if (pattern) {
+                dt = luxon_1.DateTime.fromFormat(date, pattern, { zone: zone });
+            }
+        }
+        else if (date instanceof Date) {
+            dt = luxon_1.DateTime.fromJSDate(date, { zone: zone });
+        }
+        else {
+            dt = date.setZone(zone);
+        }
+    }
+    return dt;
+}