@enhanced-dom/logging 0.0.1

package/LICENSE.md

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2023-present CD9B4A105290E17E0948E021DF4105107C88693C59C0B891CCC08366C51AEA990902A6A156AC87D88A2FC41422A5E1C3C4071F251F19441C4516000EC25F87DF
+
+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,58 @@
+TL;DR;
+
+Helpers for structured logging.
+
+# What?
+
+In many occasions we like to 'log' to multiple streams (e.g. console, analytics server, error server, etc.). Some of these streams are interested in some messages, others in completely different messages. This code has a log collector (fancy name for a list of messages) that can be flushed in 1 go to send logs to various streams. By default a console stream is implemented
+
+# Why?
+
+There seems to be a gap between a 'common' logging interface and the ability to inject consumers and 'collect' logs over a certain scope while staying within the app. Ideally, we'd like to:
+
+- add different consumers, with the ability to filter the messages to send each consumer
+- categorise the messages (by various tags)
+- retain an entire messages 'session' (regardless of their 'importance') and capture it completely on e.g. an error
+- be able to do some aggregations (wrt to perf) - similar to what `Logstash` can do (without having to use external apps ofc)
+- expose a contextualized logger for inner context (i.e. function F1 calls F2, and F2 logs a message. F1 would like to 'set some context = tags' on the message logged from F2 without F2 knowing)
+
+# How does this look like in practice?
+
+**src/paymentHandlers.ts**
+
+```ts
+import { CollectorLogger, LogTagType, LogLevel } from '@enhanced-dom/logging'
+const logger = new CollectorLogger('my unique id for a list of logs', { [LogTagType.Area]: 'payments' })
+const acceptBalanceInquiry = (balanceInquiry: SimpleBalanceInquiry | ComplicatedBalanceInquiry) => {
+  enhancedLogger = logger.withTags({ [LogTagType.Procedure]: 'balance inquiry flow' })
+  logger.log()
+  if (validateBalanceInquiry(paymentInquiry, enhancedLogger)) {
+    processBalanceInquiry(paymentInquiry, enhancedLogger)
+  }
+}
+
+const validateBalanceInquiry = (balanceInquiry: SimpleBalanceInquiry | ComplicatedBalanceInquiry, enhancedLogger?: ILogger) => {
+  const validationLogger = enhancedLogger?.withTags({
+    [LogTagType.Step]: 'validation',
+    [LogTagType.Entity]: balanceInquiry.type,
+    [LogTagType.Id]: balanceInquiry.id,
+  })
+  validationLogger?.log({ stage: 'start' }, { [LogTagType.Level]: LogLevel.Perf }, 'Starting validation')
+  /// validation code
+  validationLogger?.log({ stage: 'end' }, { [LogTagType.Level]: LogLevel.Perf }, 'Ended validation')
+  return true
+}
+
+const processBalanceInquiry = (balanceInquiry: SimpleBalanceInquiry | ComplicatedBalanceInquiry, enhancedLogger?: ILogger) => {
+  const processLogger = enhancedLogger?.withTags({
+    [LogTagType.Step]: 'process',
+    [LogTagType.Entity]: balanceInquiry.type,
+    [type: LogTagType.Id]: balanceInquiry.id
+})
+  validationLogger?.log({ stage: 'start' }, { [LogTagType.Level]: LogLevel.Perf }, 'Starting processing')
+  /// process
+  validationLogger?.log({ stage: 'end' }, { [LogTagType.Level]: LogLevel.Perf }, 'Ended processing')
+}
+```
+
+Of course, this 'passing of logger through props' is not so ideal. One could do a service locator-like pattern where the right logger instance for a 'session id' is returned, but this fails short as soon as the tags need to be changed for the 'child' scope. In a tree-like context, one can access the parent contexts (e.g. dom nodes) to figure out which logger instance to use. This is much harder without binding the current execution to a global tree-like structure.

package/index.d.ts

@@ -0,0 +1,5 @@
+export { LogLevel, type ILogEntry, type ILoggingSession, type ILogger, LogTagType } from './logging.types';
+export * from './logging.collector';
+export * from './logging.console';
+export * from './logging.consumers';
+export * from './logging.stream';

package/index.js

@@ -0,0 +1,5 @@
+export { LogLevel, LogTagType } from './logging.types';
+export * from './logging.collector';
+export * from './logging.console';
+export * from './logging.consumers';
+export * from './logging.stream';

package/logging.collector.d.ts

@@ -0,0 +1,16 @@
+import { ILogConsumerType, ILogEntry, ILogger, ILoggingSession } from './logging.types';
+export declare class CollectorLogger implements ILogger {
+    protected _tags: ILoggingSession['tags'];
+    protected _consumers: Record<string, ILogConsumerType>;
+    protected _session: ILoggingSession;
+    protected _sessionsRepository: Record<string, ILoggingSession>;
+    constructor(sessionId?: string, tags?: ILoggingSession['tags'], consumersRegistry?: Record<string, ILogConsumerType>, sessionsRepository?: Record<string, ILoggingSession>);
+    log(...args: [ILogEntry['params']] | [ILogEntry['params'], ILogEntry['tags'], ILogEntry['message']] | [ILogEntry['params'], ILogEntry['message']]): void;
+    withTags(tags: ILogEntry['tags']): ILogger;
+    flush(): void;
+}
+/**
+ * Flushing at the end of the log is nice, but in case we have some sort of unhandled exception,
+ * we should be able to flush all the logs in progress
+ */
+export declare const flushAllOutstandingSessions: () => void;

package/logging.collector.js

@@ -0,0 +1,61 @@
+import uniqueId from 'lodash.uniqueid';
+import { defaultConsumers } from './logging.consumers';
+const defaultSessionsRepository = {};
+export class CollectorLogger {
+    constructor(sessionId, tags = {}, consumersRegistry, sessionsRepository) {
+        this._tags = {};
+        this._consumers = defaultConsumers;
+        this._sessionsRepository = defaultSessionsRepository;
+        const id = sessionId !== null && sessionId !== void 0 ? sessionId : uniqueId('logging-session-');
+        this._consumers = consumersRegistry !== null && consumersRegistry !== void 0 ? consumersRegistry : this._consumers;
+        this._sessionsRepository = sessionsRepository !== null && sessionsRepository !== void 0 ? sessionsRepository : this._sessionsRepository;
+        if (!this._sessionsRepository[id]) {
+            this._sessionsRepository[id] = {
+                id,
+                tags,
+                entries: [],
+                lastUpdatedOn: null,
+                createdOn: new Date(),
+            };
+        }
+        else {
+            this._tags = tags;
+        }
+        this._session = this._sessionsRepository[id];
+    }
+    log(...args) {
+        const params = args[0];
+        let tags = {};
+        let message = undefined;
+        if (args.length > 2) {
+            tags = args[1];
+            message = args[2];
+        }
+        else if (args.length > 1) {
+            message = args[1];
+        }
+        this._session.entries.push({
+            params,
+            message,
+            tags,
+            createdOn: new Date(),
+        });
+        this._session.lastUpdatedOn = new Date();
+    }
+    withTags(tags) {
+        return new CollectorLogger(this._session.id, { ...this._tags, ...tags }, this._consumers, this._sessionsRepository);
+    }
+    flush() {
+        Object.values(this._consumers).forEach((consumer) => { var _a; return (_a = consumer.session) === null || _a === void 0 ? void 0 : _a.call(consumer, this._session); });
+        delete this._sessionsRepository[this._session.id];
+    }
+}
+/**
+ * Flushing at the end of the log is nice, but in case we have some sort of unhandled exception,
+ * we should be able to flush all the logs in progress
+ */
+export const flushAllOutstandingSessions = () => {
+    Object.values(defaultSessionsRepository)
+        .sort((s1, s2) => (s1.createdOn.valueOf() < s2.createdOn.valueOf() ? -1 : 1))
+        .forEach((session) => Object.values(defaultConsumers).forEach((consumer) => { var _a; return (_a = consumer.session) === null || _a === void 0 ? void 0 : _a.call(consumer, session); }));
+};

package/logging.console.d.ts

@@ -0,0 +1,25 @@
+import { ILogEntry, ILoggingSession } from './logging.types';
+export declare const levelClearsTreshold: (tresholdLevel: string, evaluatedLevel?: string) => boolean;
+export declare const getEntryLevel: (entry: ILogEntry) => string;
+declare let defaultConfig: {
+    level: any;
+    sessionFilter: (session: ILoggingSession) => boolean;
+    entryFilter: (entries: ILogEntry[]) => ILogEntry[];
+    sessionSerializer: (session: ILoggingSession) => string;
+    entrySerializer: (entry: ILogEntry) => string;
+};
+export declare const defaultLookbackEntrySelector: (entries: ILogEntry[]) => ILogEntry[];
+export declare const defaultPerformanceEntryCompactor: (entries: ILogEntry[]) => ILogEntry[];
+export declare const defaultConsoleConsumer: {
+    session: (session: ILoggingSession) => void;
+    entry: (entry: ILogEntry) => void;
+};
+export declare const configureDefaultConsoleConsumer: (config: Partial<typeof defaultConfig>) => void;
+export declare const getDefaultConsoleConsumerConfig: () => {
+    level: any;
+    sessionFilter: (session: ILoggingSession) => boolean;
+    entryFilter: (entries: ILogEntry[]) => ILogEntry[];
+    sessionSerializer: (session: ILoggingSession) => string;
+    entrySerializer: (entry: ILogEntry) => string;
+};
+export {};

package/logging.console.js

@@ -0,0 +1,88 @@
+import omit from 'lodash.omit';
+import zip from 'lodash.zip';
+import { LogLevel, LogTagType } from './logging.types';
+export const levelClearsTreshold = (tresholdLevel, evaluatedLevel) => {
+    switch (tresholdLevel) {
+        case LogLevel.Fatal:
+            return evaluatedLevel === LogLevel.Fatal;
+        case LogLevel.Critical:
+            return [LogLevel.Fatal, LogLevel.Critical].includes(evaluatedLevel);
+        case LogLevel.Error:
+            return [LogLevel.Fatal, LogLevel.Critical, LogLevel.Error].includes(evaluatedLevel);
+        case LogLevel.Warning:
+            return [LogLevel.Fatal, LogLevel.Critical, LogLevel.Error, LogLevel.Warning].includes(evaluatedLevel);
+        case LogLevel.Performance:
+            return [LogLevel.Fatal, LogLevel.Critical, LogLevel.Error, LogLevel.Warning, LogLevel.Performance].includes(evaluatedLevel);
+        case LogLevel.Info:
+            return [LogLevel.Fatal, LogLevel.Critical, LogLevel.Error, LogLevel.Warning, LogLevel.Performance, LogLevel.Info].includes(evaluatedLevel);
+        default:
+            return true;
+    }
+};
+export const getEntryLevel = (entry) => {
+    return entry.tags[LogTagType.Level];
+};
+let defaultConfig = Object.freeze({
+    level: LogLevel.Error,
+    sessionFilter: () => true,
+    entryFilter: (entries) => entries.filter((e) => levelClearsTreshold(defaultConfig.level, getEntryLevel(e))),
+    sessionSerializer: (session) => {
+        const listOfFormattedEntries = zip(new Array(session.entries.length - 1).fill('\t'), session.entries.map((e) => defaultConfig.entrySerializer(e)), new Array(session.entries.length - 1).fill('\n')).flatMap((a) => a.filter((e) => !!e));
+        return [`Log session with tags ${JSON.stringify(session.tags)}}:`, '\n', ...listOfFormattedEntries].join();
+    },
+    entrySerializer: (entry) => {
+        return `${entry.createdOn} | ${JSON.stringify(entry.tags)} | ${entry.message}`;
+    },
+});
+export const defaultLookbackEntrySelector = (entries) => {
+    const anyEntryClearsThreshold = entries.some((e) => levelClearsTreshold(defaultConfig.level, getEntryLevel(e)));
+    return anyEntryClearsThreshold ? entries : [];
+};
+export const defaultPerformanceEntryCompactor = (entries) => {
+    const performanceEndEntries = entries.filter((e) => e.tags[LogTagType.Level] === LogLevel.Performance && e.params.stage === 'end');
+    const performanceEntryPairs = performanceEndEntries.map((endEntry) => [
+        entries.find((possibleStartEntry) => possibleStartEntry.params.stage === 'start' && JSON.stringify(endEntry.tags) == JSON.stringify(possibleStartEntry.tags)),
+        endEntry,
+    ]);
+    const entryPairsToCompact = performanceEntryPairs.filter(([startEntry]) => !!startEntry);
+    if (!entryPairsToCompact) {
+        return entries;
+    }
+    const compactedEntries = [...entries];
+    entryPairsToCompact.forEach(([startEntry, endEntry]) => {
+        compactedEntries.splice(compactedEntries.indexOf(endEntry), 1, {
+            tags: startEntry.tags,
+            createdOn: endEntry.createdOn,
+            params: omit({ ...startEntry.params, elapsed: endEntry.createdOn.valueOf() - startEntry.createdOn.valueOf(), ...endEntry.params }, [
+                'stage',
+            ]),
+            message: 'Performance calculation',
+        });
+    });
+    return compactedEntries;
+};
+export const defaultConsoleConsumer = {
+    session: (session) => {
+        if (!defaultConfig.sessionFilter(session)) {
+            return;
+        }
+        const entriesToShow = defaultConfig.entryFilter(session.entries);
+        if (!entriesToShow.length) {
+            return;
+        }
+        console.log(defaultConfig.sessionSerializer({ ...session, entries: entriesToShow }));
+    },
+    entry: (entry) => {
+        const entriesToShow = defaultConfig.entryFilter([entry]);
+        if (!entriesToShow.length) {
+            return;
+        }
+        console.log(defaultConfig.entrySerializer(entry));
+    },
+};
+export const configureDefaultConsoleConsumer = (config) => {
+    defaultConfig = Object.freeze({ ...defaultConfig, ...config });
+};
+export const getDefaultConsoleConsumerConfig = () => {
+    return defaultConfig;
+};

package/logging.consumers.d.ts

@@ -0,0 +1,3 @@
+import { ILogConsumerType } from './logging.types';
+export declare const defaultConsumers: Record<string, ILogConsumerType>;
+export declare const registerDefaultConsumer: (name: string, consumer: ILogConsumerType) => void;

package/logging.consumers.js

@@ -0,0 +1,7 @@
+import { defaultConsoleConsumer } from './logging.console';
+export const defaultConsumers = {
+    console: defaultConsoleConsumer,
+};
+export const registerDefaultConsumer = (name, consumer) => {
+    defaultConsumers[name] = consumer;
+};

package/logging.stream.d.ts

@@ -0,0 +1,8 @@
+import { ILogConsumerType, ILogEntry, ILogger, ILoggingSession } from './logging.types';
+export declare class StreamingLogger implements ILogger {
+    protected _tags: ILoggingSession['tags'];
+    protected _consumers: Record<string, ILogConsumerType>;
+    constructor(tags?: ILoggingSession['tags'], consumers?: Record<string, ILogConsumerType>);
+    log(...args: [ILogEntry['params']] | [ILogEntry['params'], ILogEntry['tags'], ILogEntry['message']] | [ILogEntry['params'], ILogEntry['message']]): void;
+    withTags(tags: ILogEntry['tags']): ILogger;
+}

package/logging.stream.js

@@ -0,0 +1,31 @@
+import { defaultConsumers } from './logging.consumers';
+export class StreamingLogger {
+    constructor(tags = {}, consumers = defaultConsumers) {
+        this._tags = {};
+        this._consumers = {};
+        this._tags = tags;
+        this._consumers = consumers;
+    }
+    log(...args) {
+        const params = args[0];
+        let tags = {};
+        let message = undefined;
+        if (args.length > 2) {
+            tags = args[1];
+            message = args[2];
+        }
+        else if (args.length > 1) {
+            message = args[1];
+        }
+        const logMessage = {
+            params,
+            message,
+            tags: { ...this._tags, ...tags },
+            createdOn: new Date(),
+        };
+        Object.values(this._consumers).forEach((consumer) => { var _a; return (_a = consumer.entry) === null || _a === void 0 ? void 0 : _a.call(consumer, logMessage); });
+    }
+    withTags(tags) {
+        return new StreamingLogger({ ...this._tags, ...tags }, this._consumers);
+    }
+}

package/logging.types.d.ts

@@ -0,0 +1,44 @@
+export interface ILogEntry {
+    createdOn: Date;
+    params: Record<string, any>;
+    message?: string;
+    tags: Record<string, string>;
+}
+export interface ILoggingSession {
+    id: string;
+    createdOn: Date;
+    lastUpdatedOn: Date;
+    entries: ILogEntry[];
+    tags: Record<string, string>;
+}
+export interface ILogger {
+    log(...args: [ILogEntry['params'], ILogEntry['tags'], ILogEntry['message']]): void;
+    log(...args: [ILogEntry['params'], ILogEntry['message']]): void;
+    log(...args: [ILogEntry['params']]): void;
+    withTags(tags: ILogEntry['tags']): ILogger;
+    flush?: () => void;
+}
+export declare enum LogTagType {
+    Level = "level",
+    Entity = "entity",
+    Id = "id",
+    Area = "area",
+    Procedure = "procedure",
+    Step = "step"
+}
+export declare enum LogLevel {
+    Fatal = "fatal",
+    Critical = "critical",
+    Error = "error",
+    Warning = "warn",
+    Performance = "perf",
+    Info = "info",
+    Debug = "debug"
+}
+export type ILogConsumerType = {
+    session: (session: ILoggingSession) => void;
+    entry?: (entry: ILogEntry) => void;
+} | {
+    session?: (session: ILoggingSession) => void;
+    entry: (entry: ILogEntry) => void;
+};

package/logging.types.js

@@ -0,0 +1,19 @@
+export var LogTagType;
+(function (LogTagType) {
+    LogTagType["Level"] = "level";
+    LogTagType["Entity"] = "entity";
+    LogTagType["Id"] = "id";
+    LogTagType["Area"] = "area";
+    LogTagType["Procedure"] = "procedure";
+    LogTagType["Step"] = "step";
+})(LogTagType || (LogTagType = {}));
+export var LogLevel;
+(function (LogLevel) {
+    LogLevel["Fatal"] = "fatal";
+    LogLevel["Critical"] = "critical";
+    LogLevel["Error"] = "error";
+    LogLevel["Warning"] = "warn";
+    LogLevel["Performance"] = "perf";
+    LogLevel["Info"] = "info";
+    LogLevel["Debug"] = "debug";
+})(LogLevel || (LogLevel = {}));

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@enhanced-dom/logging",
+  "version": "0.0.1",
+  "description": "Helpers for basic logging",
+  "repository": "https://github.com/enhanced-dom/logging.git",
+  "main": "index.js",
+  "keywords": [],
+  "author": "CD9B4A105290E17E0948E021DF4105107C88693C59C0B891CCC08366C51AEA990902A6A156AC87D88A2FC41422A5E1C3C4071F251F19441C4516000EC25F87DF",
+  "license": "MIT",
+  "dependencies": {
+    "lodash.zip": "^4.2.0",
+    "lodash.omit": "^4.5.0",
+    "lodash.uniqueid": "^4.0.1"
+  },
+  "devDependencies": {
+    "@enhanced-dom/build": "^0.0.2",
+    "@enhanced-dom/lint": "^0.0.9",
+    "@enhanced-dom/jest": "^0.0.1",
+    "@types/lodash.omit": "^4.5.7",
+    "@types/lodash.uniqueid": "^4.0.7",
+    "@types/lodash.zip": "^4.2.7",
+    "typescript": "^4.9.4"
+  },
+  "engines": {
+    "node": ">=14.17.0",
+    "npm": ">=9.0.0"
+  }
+}