@vvlad1973/simple-logger 1.2.0

package/docs/styles/prettify-jsdoc.css

@@ -0,0 +1,111 @@
+/* JSDoc prettify.js theme */
+
+/* plain text */
+.pln {
+  color: #000000;
+  font-weight: normal;
+  font-style: normal;
+}
+
+/* string content */
+.str {
+  color: #006400;
+  font-weight: normal;
+  font-style: normal;
+}
+
+/* a keyword */
+.kwd {
+  color: #000000;
+  font-weight: bold;
+  font-style: normal;
+}
+
+/* a comment */
+.com {
+  font-weight: normal;
+  font-style: italic;
+}
+
+/* a type name */
+.typ {
+  color: #000000;
+  font-weight: normal;
+  font-style: normal;
+}
+
+/* a literal value */
+.lit {
+  color: #006400;
+  font-weight: normal;
+  font-style: normal;
+}
+
+/* punctuation */
+.pun {
+  color: #000000;
+  font-weight: bold;
+  font-style: normal;
+}
+
+/* lisp open bracket */
+.opn {
+  color: #000000;
+  font-weight: bold;
+  font-style: normal;
+}
+
+/* lisp close bracket */
+.clo {
+  color: #000000;
+  font-weight: bold;
+  font-style: normal;
+}
+
+/* a markup tag name */
+.tag {
+  color: #006400;
+  font-weight: normal;
+  font-style: normal;
+}
+
+/* a markup attribute name */
+.atn {
+  color: #006400;
+  font-weight: normal;
+  font-style: normal;
+}
+
+/* a markup attribute value */
+.atv {
+  color: #006400;
+  font-weight: normal;
+  font-style: normal;
+}
+
+/* a declaration */
+.dec {
+  color: #000000;
+  font-weight: bold;
+  font-style: normal;
+}
+
+/* a variable name */
+.var {
+  color: #000000;
+  font-weight: normal;
+  font-style: normal;
+}
+
+/* a function name */
+.fun {
+  color: #000000;
+  font-weight: bold;
+  font-style: normal;
+}
+
+/* Specify class=linenums on a pre to get line numbering */
+ol.linenums {
+  margin-top: 0;
+  margin-bottom: 0;
+}

package/docs/styles/prettify-tomorrow.css

@@ -0,0 +1,132 @@
+/* Tomorrow Theme */
+/* Original theme - https://github.com/chriskempson/tomorrow-theme */
+/* Pretty printing styles. Used with prettify.js. */
+/* SPAN elements with the classes below are added by prettyprint. */
+/* plain text */
+.pln {
+  color: #4d4d4c; }
+
+@media screen {
+  /* string content */
+  .str {
+    color: #718c00; }
+
+  /* a keyword */
+  .kwd {
+    color: #8959a8; }
+
+  /* a comment */
+  .com {
+    color: #8e908c; }
+
+  /* a type name */
+  .typ {
+    color: #4271ae; }
+
+  /* a literal value */
+  .lit {
+    color: #f5871f; }
+
+  /* punctuation */
+  .pun {
+    color: #4d4d4c; }
+
+  /* lisp open bracket */
+  .opn {
+    color: #4d4d4c; }
+
+  /* lisp close bracket */
+  .clo {
+    color: #4d4d4c; }
+
+  /* a markup tag name */
+  .tag {
+    color: #c82829; }
+
+  /* a markup attribute name */
+  .atn {
+    color: #f5871f; }
+
+  /* a markup attribute value */
+  .atv {
+    color: #3e999f; }
+
+  /* a declaration */
+  .dec {
+    color: #f5871f; }
+
+  /* a variable name */
+  .var {
+    color: #c82829; }
+
+  /* a function name */
+  .fun {
+    color: #4271ae; } }
+/* Use higher contrast and text-weight for printable form. */
+@media print, projection {
+  .str {
+    color: #060; }
+
+  .kwd {
+    color: #006;
+    font-weight: bold; }
+
+  .com {
+    color: #600;
+    font-style: italic; }
+
+  .typ {
+    color: #404;
+    font-weight: bold; }
+
+  .lit {
+    color: #044; }
+
+  .pun, .opn, .clo {
+    color: #440; }
+
+  .tag {
+    color: #006;
+    font-weight: bold; }
+
+  .atn {
+    color: #404; }
+
+  .atv {
+    color: #060; } }
+/* Style */
+/*
+pre.prettyprint {
+  background: white;
+  font-family: Consolas, Monaco, 'Andale Mono', monospace;
+  font-size: 12px;
+  line-height: 1.5;
+  border: 1px solid #ccc;
+  padding: 10px; }
+*/
+
+/* Specify class=linenums on a pre to get line numbering */
+ol.linenums {
+  margin-top: 0;
+  margin-bottom: 0; }
+
+/* IE indents via margin-left */
+li.L0,
+li.L1,
+li.L2,
+li.L3,
+li.L4,
+li.L5,
+li.L6,
+li.L7,
+li.L8,
+li.L9 {
+  /* */ }
+
+/* Alternate shading for lines */
+li.L1,
+li.L3,
+li.L5,
+li.L7,
+li.L9 {
+  /* */ }

package/docs/styles/reset.css

@@ -0,0 +1,44 @@
+/* reset css */
+html, body, div, span, applet, object, iframe,
+h1, h2, h3, h4, h5, h6, p, blockquote, pre,
+a, abbr, acronym, address, big, cite, code,
+del, dfn, em, img, ins, kbd, q, s, samp,
+small, strike, strong, sub, sup, tt, var,
+b, u, i, center,
+dl, dt, dd, ol, ul, li,
+fieldset, form, label, legend,
+table, caption, tbody, tfoot, thead, tr, th, td,
+article, aside, canvas, details, embed, 
+figure, figcaption, footer, header, hgroup, 
+menu, nav, output, ruby, section, summary,
+time, mark, audio, video {
+  margin: 0;
+  padding: 0;
+  border: 0;
+  font-size: 100%;
+  font: inherit;
+  vertical-align: baseline;
+}
+/* HTML5 display-role reset for older browsers */
+article, aside, details, figcaption, figure, 
+footer, header, hgroup, menu, nav, section {
+  display: block;
+}
+body {
+  line-height: 1;
+}
+ol, ul {
+  list-style: none;
+}
+blockquote, q {
+  quotes: none;
+}
+blockquote:before, blockquote:after,
+q:before, q:after {
+  content: '';
+  content: none;
+}
+table {
+  border-collapse: collapse;
+  border-spacing: 0;
+}

package/jsdoc.json

@@ -0,0 +1,14 @@
+{
+    "source": {
+      "include": ["./src/"],
+      "includePattern": "\\.(ts)$",
+      "excludePattern": "(^|\\/|\\\\)node_modules"
+    },
+    "plugins": ["node_modules/better-docs/typescript"],
+    "opts": {
+      "destination": "./docs",
+      "recurse": true,
+      "template": "node_modules/better-docs"
+    }
+  }
+  

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@vvlad1973/simple-logger",
+  "version": "1.2.0",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "type": "module",
+  "scripts": {
+    "test": "npm run build && node --loader ts-node/esm --test",
+    "build": "tsc",
+    "doc": "jsdoc -c jsdoc.json"
+  },
+  "author": "Vladislav Vnukovskiy <vvlad1973@gmail.com>",
+  "license": "MIT with Commercial Use",
+  "description": "A simple logging utility for JavaScript applications, providing customizable log levels and flexible external logger integration.",
+  "devDependencies": {
+    "@types/node": "^20.16.1",
+    "better-docs": "^2.7.3",
+    "jsdoc": "^4.0.3",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.5.4"
+  },
+  "dependencies": {
+    "vvlad1973-utils": "^2.6.0"
+  }
+}

package/src/__test__/simple-logger.test.ts

@@ -0,0 +1,188 @@
+import { describe, it, beforeEach } from 'node:test';
+import assert from 'assert';
+import SimpleLogger from '../simple-logger.js';
+
+type MockFunction = {
+  (...args: any[]): void;
+  mock: { calls: any[][] };
+};
+
+type NoopFunction = {
+  (...args: any[]): void;
+  mock: { calls: any[][] };
+};
+
+function createMockLoggerMethod(): MockFunction {
+  const calls: any[][] = [];
+  const mockFn = function (...args: any[]) {
+    calls.push(args);
+  } as MockFunction;
+  mockFn.mock = { calls };
+  return mockFn;
+}
+
+function createNoopMethod(): MockFunction {
+  const calls: any[][] = [];
+  const mockFn = function (...args: any[]) {} as MockFunction;
+  mockFn.mock = { calls };
+  return mockFn;
+}
+type ExternalLoggerMock = {
+  trace: MockFunction | NoopFunction;
+  debug: MockFunction | NoopFunction;
+  info: MockFunction | NoopFunction;
+  warn: MockFunction | NoopFunction;
+  error: MockFunction | NoopFunction;
+  fatal: MockFunction | NoopFunction;
+  silent: MockFunction | NoopFunction;
+};
+
+function createExternalLoggerMock(): ExternalLoggerMock {
+  return {
+    trace: createMockLoggerMethod(),
+    debug: createMockLoggerMethod(),
+    info: createMockLoggerMethod(),
+    warn: createMockLoggerMethod(),
+    error: createMockLoggerMethod(),
+    fatal: createMockLoggerMethod(),
+    silent:createMockLoggerMethod(),
+  };
+}
+
+describe('SimpleLogger', () => {
+  let logger: SimpleLogger;
+  let externalLoggerMock: ExternalLoggerMock;
+
+  beforeEach(() => {
+    externalLoggerMock = createExternalLoggerMock();
+    logger = new SimpleLogger('info', externalLoggerMock);
+  });
+
+  it('should call external logger methods appropriately', () => {
+    logger.trace('trace message');
+    logger.debug('debug message');
+    logger.info('info message');
+    logger.warn('warn message');
+    logger.error('error message');
+    logger.fatal('fatal message');
+
+    assert.strictEqual(externalLoggerMock.trace.mock.calls.length, 0);
+    assert.strictEqual(externalLoggerMock.debug.mock.calls.length, 0);
+    assert.strictEqual(externalLoggerMock.info.mock.calls.length, 1);
+    assert.strictEqual(
+      externalLoggerMock.info.mock.calls[0][0],
+      'info message'
+    );
+    assert.strictEqual(externalLoggerMock.warn.mock.calls.length, 1);
+    assert.strictEqual(
+      externalLoggerMock.warn.mock.calls[0][0],
+      'warn message'
+    );
+    assert.strictEqual(externalLoggerMock.error.mock.calls.length, 1);
+    assert.strictEqual(
+      externalLoggerMock.error.mock.calls[0][0],
+      'error message'
+    );
+    assert.strictEqual(externalLoggerMock.fatal.mock.calls.length, 1);
+    assert.strictEqual(
+      externalLoggerMock.fatal.mock.calls[0][0],
+      'fatal message'
+    );
+  });
+
+  it('should log function start and end', () => {
+    logger.setLevel('TRACE');
+
+    function testFunction() {
+      logger.logFunctionStart();
+      logger.logFunctionEnd();
+    }
+
+    testFunction();
+
+    assert.strictEqual(externalLoggerMock.trace.mock.calls.length, 2);
+    assert.strictEqual(
+      externalLoggerMock.trace.mock.calls[0][0],
+      'Function start: testFunction'
+    );
+    assert.strictEqual(
+      externalLoggerMock.trace.mock.calls[1][0],
+      'Function end: testFunction'
+    );
+  });
+});
+
+describe('SimpleLogger2', () => {
+  let logger: SimpleLogger;
+  let externalLoggerMock: ExternalLoggerMock;
+
+  beforeEach(() => {
+    externalLoggerMock = createExternalLoggerMock();
+    logger = new SimpleLogger('info', externalLoggerMock);
+  });
+
+  it('should use console as default external logger', () => {
+    const defaultLogger = new SimpleLogger();
+    assert.ok(defaultLogger);
+  });
+
+  it('should set the correct log level', () => {
+    logger.setLevel('DEBUG');
+    assert.notStrictEqual(logger.trace, () => {});
+    assert.strictEqual(typeof logger.debug, 'function');
+    assert.strictEqual(typeof logger.info, 'function');
+  });
+
+  it('should call external logger methods appropriately', () => {
+    logger.trace('trace message');
+    logger.debug('debug message');
+    logger.info('info message');
+    logger.warn('warn message');
+    logger.error('error message');
+    logger.fatal('fatal message');
+
+    assert.strictEqual(externalLoggerMock.trace.mock.calls.length, 0); // because default level is INFO
+    assert.strictEqual(externalLoggerMock.debug.mock.calls.length, 0); // because default level is INFO
+    assert.strictEqual(externalLoggerMock.info.mock.calls.length, 1);
+    assert.strictEqual(
+      externalLoggerMock.info.mock.calls[0][0],
+      'info message'
+    );
+    assert.strictEqual(externalLoggerMock.warn.mock.calls.length, 1);
+    assert.strictEqual(
+      externalLoggerMock.warn.mock.calls[0][0],
+      'warn message'
+    );
+    assert.strictEqual(externalLoggerMock.error.mock.calls.length, 1);
+    assert.strictEqual(
+      externalLoggerMock.error.mock.calls[0][0],
+      'error message'
+    );
+    assert.strictEqual(externalLoggerMock.fatal.mock.calls.length, 1);
+    assert.strictEqual(
+      externalLoggerMock.fatal.mock.calls[0][0],
+      'fatal message'
+    );
+  });
+
+  it('should log function start and end', () => {
+    logger.setLevel('TRACE');
+
+    function testFunction() {
+      logger.logFunctionStart();
+      logger.logFunctionEnd();
+    }
+
+    testFunction();
+
+    assert.strictEqual(externalLoggerMock.trace.mock.calls.length, 2);
+    assert.strictEqual(
+      externalLoggerMock.trace.mock.calls[0][0],
+      'Function start: testFunction'
+    );
+    assert.strictEqual(
+      externalLoggerMock.trace.mock.calls[1][0],
+      'Function end: testFunction'
+    );
+  });
+});

package/src/index.ts

@@ -0,0 +1,2 @@
+export { default } from './simple-logger.js'
+export * from './simple-logger.js'

package/src/simple-logger.ts

@@ -0,0 +1,188 @@
+/**
+ * A module for simple logging with various logging levels.
+ * @module SimpleLogger
+ */
+
+import { getCallerName } from 'vvlad1973-utils';
+
+export type ExternalLogger = {
+  trace?: LogFn;
+  debug?: LogFn;
+  info?: LogFn;
+  warn?: LogFn;
+  error?: LogFn;
+  fatal?: LogFn;
+  silent?: LogFn;
+  level?: string;
+};
+
+interface LogFn {
+  <T extends object>(obj: T, msg?: string, ...args: any[]): void;
+  (obj: unknown, msg?: string, ...args: any[]): void;
+  (msg: string, ...args: any[]): void;
+}
+
+const loggerLevels = [
+  'trace',
+  'debug',
+  'info',
+  'warn',
+  'error',
+  'fatal',
+  'silent',
+] as const;
+export type LoggerLevel = (typeof loggerLevels)[number];
+/**
+ * A simple logger class with various logging levels.
+ * @class
+ * @param {string} [level='info'] - Initial logging level.
+ * @param {ExternalLogger | undefined | null} [externalLogger=null] - Optional external logger to use.
+ */
+export class SimpleLogger {
+  #levels = loggerLevels;
+  #currentLevel: number = 2;
+  #logger: ExternalLogger | Console = console;
+
+  isExternal: boolean = false;
+
+  constructor(level?: LoggerLevel, externalLogger?: ExternalLogger) {
+    if (externalLogger && this.isValidLogger(externalLogger)) {
+      this.setExternalLogger(externalLogger, level);
+    } else {
+      this.setLevel(level ?? 'info');
+    }
+  }
+
+  trace: LogFn = (...args: any[]) => {};
+  debug: LogFn = (...args: any[]) => {};
+  info: LogFn = (...args: any[]) => {};
+  warn: LogFn = (...args: any[]) => {};
+  error: LogFn = (...args: any[]) => {};
+  fatal: LogFn = (...args: any[]) => {};
+  silent: LogFn = (...args: any[]) => {};
+
+  /**
+   * Updates the logging methods based on the current logging level.
+   * @private
+   */
+  private updateLoggingMethods() {
+    try {
+      const noop = (...args: any[]) => {};
+      this.trace =
+        this.#currentLevel <= 0 ? this.getExternalLoggerMethod('trace') : noop;
+      this.debug =
+        this.#currentLevel <= 1 ? this.getExternalLoggerMethod('debug') : noop;
+      this.info =
+        this.#currentLevel <= 2 ? this.getExternalLoggerMethod('info') : noop;
+      this.warn =
+        this.#currentLevel <= 3 ? this.getExternalLoggerMethod('warn') : noop;
+      this.error =
+        this.#currentLevel <= 4 ? this.getExternalLoggerMethod('error') : noop;
+      this.fatal =
+        this.#currentLevel <= 5
+          ? this.getExternalLoggerMethod('fatal', 'error')
+          : noop;
+      this.silent = noop;
+    } catch (error) {
+      console.error(error);
+    }
+  }
+
+  /**
+   * Checks if the provided logger is valid.
+   * @private
+   * @param {any} logger - The logger to check.
+   * @returns {boolean} - True if the logger is valid, otherwise false.
+   */
+  private isValidLogger(logger: any): boolean {
+    return loggerLevels.every((method) => {
+      return typeof logger[method] === 'function';
+    });
+  }
+
+  /**
+   * Gets the external logger method for a specific level.
+   * @param {string} method - The logger method to get.
+   * @param {string} [fallbackMethod] - The fallback logger method to get.
+   * @returns {LoggerMethod} - The logger method or a no-op function.
+   * @private
+   */
+  private getExternalLoggerMethod(
+    method: keyof ExternalLogger,
+    fallbackMethod?: keyof ExternalLogger
+  ): LogFn {
+    try {
+      const loggerMethod = (this.#logger as ExternalLogger)[method];
+
+      if (typeof loggerMethod === 'function') {
+        return loggerMethod.bind(this.#logger);
+      } else if (typeof fallbackMethod !== 'undefined') {
+        const fallbackLoggerMethod = (this.#logger as ExternalLogger)[
+          fallbackMethod
+        ];
+
+        if (typeof fallbackLoggerMethod === 'function') {
+          return fallbackLoggerMethod.bind(this.#logger);
+        }
+      }
+      return () => {};
+    } catch (error) {
+      console.error(error);
+      return () => {};
+    }
+  }
+
+  /**
+   * Sets the logging level.
+   * @param {string} level - The logging level to set.
+   */
+  public setLevel(level: string) {
+    const index = this.#levels.indexOf(level.toLowerCase() as LoggerLevel);
+    if (index !== -1) {
+      this.#currentLevel = index;
+
+      if (typeof (this.#logger as ExternalLogger).level === 'string') {
+        (this.#logger as ExternalLogger).level = level;
+      }
+      this.updateLoggingMethods();
+    }
+  }
+
+  /**
+   * Sets an external logger to be used.
+   * @param {ExternalLogger | undefined | null} logger - The external logger to set.
+   */
+  public setExternalLogger(
+    logger: ExternalLogger | undefined | null,
+    level?: LoggerLevel
+  ) {
+    if (logger && this.isValidLogger(logger)) {
+      this.#logger = logger;
+      this.isExternal = true;
+    } else {
+      this.#logger = console;
+      this.isExternal = false;
+    }
+    this.setLevel(level ?? logger?.level ?? this.#levels[this.#currentLevel]);
+  }
+
+  /**
+   * Logs the start of a function.
+   * @param {string} [functionName] - Optional function name to log.
+   */
+  public logFunctionStart(functionName?: string) {
+    const callerName = functionName || getCallerName();
+    this.trace(`Function start: ${callerName}`);
+  }
+
+  /**
+   * Logs the end of a function.
+   * @param {string} [functionName] - Optional function name to log.
+   */
+  public logFunctionEnd(functionName?: string) {
+    const callerName = functionName || getCallerName();
+    this.trace(`Function end: ${callerName}`);
+  }
+}
+
+export default SimpleLogger;