@creejs/commons-logging 1.0.0

package/lib/log4js/log4js-factory.js

@@ -0,0 +1,90 @@
+'use strict'
+// internal
+const { TypeAssert: { assertString } } = require('@creejs/commons-lang')
+// owned
+// eslint-disable-next-line no-unused-vars
+const Logger = require('../logger')
+// eslint-disable-next-line no-unused-vars
+const { Level, value2Name } = require('../log-level')
+const LogFactory = require('../log-factory')
+
+const Log4jsLogger = require('./log4js-logger')
+const DefaultConfig = require('./log4js-6x-config')
+
+/**
+ * Use log4js as the logging provider.
+ */
+class Log4jsFactory extends LogFactory {
+  /**
+   * the log4js module instance.
+   * @returns {{}} The log4js module instance.
+   */
+  get log4js () {
+    return this._libraryModule
+  }
+
+  get setting () {
+    if (this._setting == null) {
+      this._setting = cloneDefaultConfig()
+    }
+    return this._setting
+  }
+
+  /**
+   * Initializes the log4js provider by configuring it with the provided settings.
+   * @override
+   */
+  init () {
+    // @ts-ignore
+    this.log4js.configure(this.setting)
+  }
+
+  /**
+   * Update factory's Log Level
+   * 1. Only Provider knows how to update
+   * @param {number} level - The log level to set, see {@link LogLevel.Level}
+   * @returns {void}
+   * @throws {Error} Throws an error as this method is Not Impled Yet.
+   * @abstract
+   */
+  setLevel (level) {
+    let levelName = value2Name(level)
+    if (levelName == null) {
+      throw new Error(`Invalid log level: ${level}`)
+    }
+    levelName = levelName.toLowerCase()
+    let updated = false
+    // @ts-ignore
+    const { categories } = this.setting
+    for (const categoryKey in categories) {
+      const category = categories[categoryKey]
+      const { level: categoryLevel } = category
+      if (categoryLevel !== levelName) {
+        category.level = levelName.toLowerCase()
+        updated = true
+      }
+    }
+    // init log4js again
+    updated && this.init()
+  }
+
+  /**
+   * Creates a new logger instance with the specified name and log level.
+   * @param {string} loggerName - The name of the logger to create.
+   * @returns {Logger} A new logger instance configured with the given name and level.
+   * @override
+   */
+  createLogger (loggerName) {
+    assertString(loggerName)
+    // @ts-ignore
+    const nativeLogger = this.log4js.getLogger(loggerName)
+    const logger = new Log4jsLogger(loggerName, nativeLogger)
+    return logger
+  }
+}
+
+function cloneDefaultConfig () {
+  return JSON.parse(JSON.stringify(DefaultConfig))
+}
+
+module.exports = Log4jsFactory

package/lib/log4js/log4js-logger.js

@@ -0,0 +1,111 @@
+'use strict'
+
+// 3rd
+// internal
+// owned
+const { assertLevel, value2Name, name2Value, Level } = require('../log-level')
+const Logger = require('../logger')
+// module vars
+
+class Log4jsLogger extends Logger {
+  /**
+   * Creates a new ConsoleLogger instance.
+   * @constructor
+   * @param {string} name - The name of the logger.
+   * @param {*} nativeLogger - Log4js library
+   */
+  constructor (name, nativeLogger) {
+    super(name, nativeLogger)
+    // @ts-ignore
+    this._level = undefined // MUST NOT accept level from outside
+    this._logger = nativeLogger
+  }
+
+  /**
+   * 1. log4js may have many categories(loggerName) with diffirent level
+   * 2. return the underlying log4js native logger's level
+   * @returns {number} The current log level.
+   */
+  get level () {
+    if (this._level == null) {
+      const levelName = this._logger.level.levelStr
+      if (levelName == null) {
+        return Level.OFF
+      }
+      const level = name2Value(levelName)
+      if (level == null) {
+        throw new Error(`Unknown level name: ${levelName}`)
+      }
+      return level
+    }
+    return this._level
+  }
+
+  /**
+   * set log4js native logger's level
+   * @param {number} level
+   * @override
+   * @protectd
+   */
+  _setLevel (level) {
+    assertLevel(level)
+    const levelName = value2Name(level)
+    if (levelName == null) {
+      throw new Error(`Invalid log level: ${level}`)
+    }
+    // log4js use string level, eg. 'error, trace'
+    this._logger.level = levelName.toLowerCase()
+  }
+
+  /**
+   * Logs a fatal error message with timestamp and logger name.
+   * Only outputs if fatal logging is enabled for this logger instance.
+   * @param {...any} args - Arguments to log (will be space-separated)
+   */
+  _fatal (...args) {
+    this._logger.fatal(...args)
+  }
+
+  /**
+   * Logs an error message to the console with timestamp and logger name.
+   * Only logs if error logging is enabled for this logger instance.
+   * @param {...any} args - Arguments to be logged as error message
+   */
+  _error (...args) {
+    this._logger.error(...args)
+  }
+
+  /**
+   * Logs a warning message to the console if warn logging is enabled.
+   * @param {...any} args - The arguments to log as a warning message.
+   */
+  _warn (...args) {
+    this._logger.warn(...args)
+  }
+
+  /**
+   * Logs debug messages to console if debug mode is enabled.
+   * @param {...any} args - The data to be logged
+   */
+  _debug (...args) {
+    this._logger.debug(...args)
+  }
+
+  /**
+   * Logs an info message to the console with timestamp and logger name.
+   * @param {...any} args - The data to be logged. Accepts multiple arguments.
+   */
+  _info (...args) {
+    this._logger.info(...args)
+  }
+
+  /**
+   * Logs a trace message with timestamp and logger name if trace logging is enabled.
+   * @param {...any} args - Data to be logged as trace message.
+   */
+  _trace (...args) {
+    this._logger.trace(...args)
+  }
+}
+
+module.exports = Log4jsLogger

package/lib/log4js/log4js-provider.js

@@ -0,0 +1,35 @@
+'use strict'
+// internal
+const { TypeAssert: { assertNotNil } } = require('@creejs/commons-lang')
+
+// owned
+const ProviderType = require('../provider-type')
+const Provider = require('../provider')
+const Log4jsFactory = require('./log4js-factory')
+
+class Log4jsProvider extends Provider {
+  /**
+   * Gets the provider type (Log4js).
+   * @returns {string} "LOG4JS"
+   * @override
+   */
+  getType () {
+    return ProviderType.Log4js
+  }
+
+  /**
+   * Creates a new Provider instance.
+   * @param {*} libraryModule - The library module to be used.
+   * @param {*} setting - Configuration settings for the provider.
+   * @returns {Log4jsFactory} A new instance of Log4jsFactory.
+   * @override
+   */
+  createLogFactory (libraryModule, setting) {
+    assertNotNil(libraryModule)
+    const factory = new Log4jsFactory(libraryModule, setting)
+    factory.init()
+    return factory
+  }
+}
+
+module.exports = Log4jsProvider

package/lib/logger.js

@@ -0,0 +1,285 @@
+'use strict'
+
+const { assertString } = require('@creejs/commons-lang/lib/type-assert')
+const LogLevel = require('./log-level')
+const { Level, DefaultLevel, assertLevel } = require('./log-level')
+
+/**
+ * Abstract Logger Class of All Logger
+ * @abstract
+ */
+class Logger {
+  /**
+   * Creates a new Logger instance.
+   * @constructor
+   * @param {string} name - The name identifier for the logger
+   * @param {*} [nativeLogger]
+   * @param {number} [level] - The logging level, default is Level.ERROR=1
+   */
+  constructor (name, nativeLogger, level = DefaultLevel) {
+    assertString(name)
+    assertLevel(level)
+    this._name = name
+    this._nativeLogger = nativeLogger
+    this._level = level
+  }
+
+  get nativeLogger () {
+    return this._nativeLogger
+  }
+
+  get level () {
+    return this._level
+  }
+
+  /**
+   * Gets the name of the logger instance.
+   * @returns {string} The name of the logger.
+   */
+  get name () {
+    return this._name
+  }
+
+  /**
+   * Checks if FATAL level logging is enabled for this logger.
+   * @returns {boolean} True if FATAL level logging is enabled, false otherwise.
+   */
+  get fatalEnabled () {
+    return this.level >= Level.FATAL
+  }
+
+  /**
+   * Checks if ERROR level logging is enabled for this logger.
+   * @returns {boolean} True if ERROR level logging is enabled, false otherwise.
+   */
+  get errorEnabled () {
+    return this.level >= Level.ERROR
+  }
+
+  /**
+   * Checks if WARN level logging is enabled for this logger.
+   * @returns {boolean} True if WARN level logging is enabled, false otherwise.
+   */
+  get warnEnabled () {
+    return this.level >= Level.WARN
+  }
+
+  /**
+   * Checks if DEBUG level logging is enabled for this logger.
+   * @returns {boolean} True if DEBUG level logging is enabled, false otherwise.
+   */
+  get debugEnabled () {
+    return this.level >= Level.DEBUG
+  }
+
+  /**
+   * Checks if INFO level logging is enabled for this logger.
+   * @returns {boolean} True if INFO level logging is enabled, false otherwise.
+   */
+  get infoEnabled () {
+    return this.level >= Level.INFO
+  }
+
+  /**
+   * Checks if TRACE level logging is enabled for this logger.
+   * @returns {boolean} True if TRACE level logging is enabled, false otherwise.
+   */
+  get traceEnabled () {
+    return this.level >= Level.TRACE
+  }
+
+  /**
+   * change log level for current logger instance.
+   * @param {number} level - new log level to set
+   * @throws {Error} Currently throws an error as this method is Not Impled Yet.
+   * @abstract
+   */
+  setLevel (level) {
+    LogLevel.assertLevel(level)
+    this._setLevel(level)
+    this._level = level
+  }
+
+  /**
+   * Logs a fatal error message with timestamp and logger name.
+   * Only outputs if fatal logging is enabled for this logger instance.
+   * @param {...any} args - Arguments to log (will be space-separated)
+   */
+  fatal (...args) {
+    if (this.fatalEnabled) {
+      this._fatal(...args)
+    }
+  }
+
+  /**
+   * Logs an error message to the console with timestamp and logger name.
+   * Only logs if error logging is enabled for this logger instance.
+   * @param {...any} args - Arguments to be logged as error message
+   */
+  error (...args) {
+    if (this.errorEnabled) {
+      this._error(...args)
+    }
+  }
+
+  /**
+   * Logs a warning message to the console if warn logging is enabled.
+   * @param {...any} args - The arguments to log as a warning message.
+   */
+  warn (...args) {
+    if (this.warnEnabled) {
+      this._warn(...args)
+    }
+  }
+
+  /**
+   * Logs debug messages to console if debug mode is enabled.
+   * @param {...any} args - The data to be logged
+   */
+  debug (...args) {
+    if (this.debugEnabled) {
+      this._debug(...args)
+    }
+  }
+
+  /**
+   * Logs an info message to the console with timestamp and logger name.
+   * @param {...any} args - The data to be logged. Accepts multiple arguments.
+   */
+  info (...args) {
+    if (this.infoEnabled) {
+      this._info(...args)
+    }
+  }
+
+  /**
+   * Logs a trace message with timestamp and logger name if trace logging is enabled.
+   * @param {...any} args - Data to be logged as trace message.
+   */
+  trace (...args) {
+    if (this.traceEnabled) {
+      this._trace(...args)
+    }
+  }
+
+  /**
+   * Checks if FATAL level logging is enabled for this logger.
+   * @returns {boolean} True if FATAL level logging is enabled, false otherwise.
+   */
+  isFatalEnabled () {
+    return this.fatalEnabled
+  }
+
+  /**
+   * Checks if ERROR level logging is enabled for this logger.
+   * @returns {boolean} True if ERROR level logging is enabled, false otherwise.
+   */
+  isErrorEnabled () {
+    return this.errorEnabled
+  }
+
+  /**
+   * Checks if WARN level logging is enabled for this logger.
+   * @returns {boolean} True if WARN level logging is enabled, false otherwise.
+   */
+  isWarnEnabled () {
+    return this.warnEnabled
+  }
+
+  /**
+   * Checks if DEBUG level logging is enabled for this logger.
+   * @returns {boolean} True if DEBUG level logging is enabled, false otherwise.
+   */
+  isDebugEnabled () {
+    return this.debugEnabled
+  }
+
+  /**
+   * Checks if INFO level logging is enabled for this logger.
+   * @returns {boolean} True if INFO level logging is enabled, false otherwise.
+   */
+  isInfoEnabled () {
+    return this.infoEnabled
+  }
+
+  /**
+   * Checks if TRACE level logging is enabled for this logger.
+   * @returns {boolean} True if TRACE level logging is enabled, false otherwise.
+   */
+  isTraceEnabled () {
+    return this.traceEnabled
+  }
+
+  /**
+   * Sets the logging level
+   * @param {number} level
+   * @throws {Error} Always throws "Not Impled Yet Yet" error.
+   * @protected
+   * @abstract
+   */
+  _setLevel (level) {
+    throw new Error('Not Impled Yet')
+  }
+
+  /**
+   * Override this method to implement fatal logging.
+   * @protected
+   * @param {...*} args - Variable arguments
+   * @throws {Error} Always throws "Not Impled Yet Yet" error
+   */
+  _fatal (...args) {
+    throw new Error('Not Impled Yet')
+  }
+
+  /**
+   * Override this method to implement error logging.
+   * @protected
+   * @param {...*} args - Variable arguments
+   * @throws {Error} Always throws "Not Impled Yet Yet" error
+   */
+  _error (...args) {
+    throw new Error('Not Impled Yet')
+  }
+
+  /**
+   * Override this method to implement warn logging.
+   * @protected
+   * @param {...*} args - Variable arguments
+   * @throws {Error} Always throws "Not Impled Yet Yet" error
+   */
+  _warn (...args) {
+    throw new Error('Not Impled Yet')
+  }
+
+  /**
+   * Override this method to implement debug logging.
+   * @protected
+   * @param {...*} args - Variable arguments
+   * @throws {Error} Always throws "Not Impled Yet Yet" error
+   */
+  _debug (...args) {
+    throw new Error('Not Impled Yet')
+  }
+
+  /**
+   * Override this method to implement info logging.
+   * @protected
+   * @param {...*} args - Variable arguments
+   * @throws {Error} Always throws "Not Impled Yet Yet" error
+   */
+  _info (...args) {
+    throw new Error('Not Impled Yet')
+  }
+
+  /**
+   * Override this method to implement trace logging.
+   * @protected
+   * @param {...*} args - Variable arguments
+   * @throws {Error} Always throws "Not Impled Yet Yet" error
+   */
+  _trace (...args) {
+    throw new Error('Not Impled Yet')
+  }
+}
+
+module.exports = Logger

package/lib/provider-type.js

@@ -0,0 +1,13 @@
+'use strict'
+const Log4js = 'LOG4JS'
+const Console = 'CONSOLE'
+/**
+ * @namespace ProviderType
+ * @description Define the static types
+ */
+const ProviderType = {
+  Log4js,
+  Console
+}
+
+module.exports = ProviderType

package/lib/provider.js

@@ -0,0 +1,53 @@
+'use strict'
+
+// owned
+// eslint-disable-next-line no-unused-vars
+const LogFactory = require('./log-factory')
+
+/**
+ * A interface that All Provider module must export
+ * @interface
+ */
+class Provider {
+  /**
+   * Checks if a value resembles a logging provider by verifying it has required methods.
+   * @param {*} value - The value to check
+   * @returns {boolean}
+   */
+  static isProviderLike (value) {
+    if (value == null) {
+      return false
+    }
+    return typeof value === 'object' && typeof value.createLogFactory === 'function' && typeof value.getType === 'function'
+  }
+
+  /**
+   * Asserts that the given value is a valid provider-like object.
+   * @throws {Error} Throws an error if the value is not provider-like.
+   * @param {*} value - The value to check.
+   */
+  static assertProviderLike (value) {
+    if (!this.isProviderLike(value)) {
+      throw new Error('Not LogProvider')
+    }
+  }
+
+  /**
+   * The Type Name of current Provider
+   * @return {String} The type of the provider.
+   */
+  getType () {
+    throw new Error('Not Impled Yet')
+  }
+
+  /**
+   * Create a new LogFactory instance
+   * @param {*} [nativeLib] - The native library to use for logging.
+   * @param {*} [setting] - Configuration settings for the logging provider.
+   * @returns {LogFactory} A new instance of LogFactory.
+   */
+  createLogFactory (nativeLib, setting) {
+    throw new Error('Not Impled Yet')
+  }
+}
+module.exports = Provider

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@creejs/commons-logging",
+  "version": "1.0.0",
+  "description": "Common Utils About Logging",
+  "main": "index.js",
+  "private": false,
+  "files": [
+    "index.js",
+    "lib/",
+    "types/",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/frameworkee/commons.git"
+  },
+  "scripts": {
+    "dts": "tsc",
+    "generate-docs": "node_modules/.bin/jsdoc -c ./jsdoc.json"
+  },
+  "author": "rodney.vin@gmail.com",
+  "license": "Apache-2.0",
+  "dependencies": {
+    "@creejs/commons-lang": "1.x"
+  },
+  "devDependencies": {
+    "better-docs": "^2.7.3",
+    "jsdoc": "^4.0.4",
+    "log4js": "6.x"
+  }
+}

package/types/console-logger.d.ts

@@ -0,0 +1,7 @@
+export = ConsoleLogger;
+/**
+ * A Simple Implementation of the Logger interface that logs to the console.
+ */
+declare class ConsoleLogger extends Logger {
+}
+import Logger = require("./logger");

package/types/index.d.ts

@@ -0,0 +1,22 @@
+import Logger = require("./logger");
+import LoggingLevel = require("./logging-level");
+/**
+ * Adds a logging provider with the specified library and settings.
+ * @param {module} providerLib - The logging provider library to add.
+ * @param {{}} setting - Configuration settings for the provider.
+ */
+export function addProvider(providerLib: any, setting: {}): void;
+/**
+   * Gets or creates a named logger instance with the specified log level.
+   * If a logger with the given name already exists, updates its log level if different.
+   * @param {string} name - The name identifier for the logger
+   * @param {'TRACE'|'DEBUG'|'INFO'|'WARN'|'ERROR'|'FATAL'|'OFF'|'trace'|'debug'|'info'|'warn'|'error'|'fatal'|'off'} [level='ERROR'] - The log level
+   * @returns {Logger} The logger instance for the given name
+   */
+export function getLogger(name: string, level?: "TRACE" | "DEBUG" | "INFO" | "WARN" | "ERROR" | "FATAL" | "OFF" | "trace" | "debug" | "info" | "warn" | "error" | "fatal" | "off"): Logger;
+/**
+   * set Global logging level
+   * @param {'TRACE'|'DEBUG'|'INFO'|'WARN'|'ERROR'|'FATAL'|'OFF'|'trace'|'debug'|'info'|'warn'|'error'|'fatal'|'off'} level - The log level
+   */
+export function setLevel(level: "TRACE" | "DEBUG" | "INFO" | "WARN" | "ERROR" | "FATAL" | "OFF" | "trace" | "debug" | "info" | "warn" | "error" | "fatal" | "off"): void;
+export { Logger, LoggingLevel };

package/types/log4js-logger.d.ts

@@ -0,0 +1,13 @@
+export = Log4jsLogger;
+declare class Log4jsLogger extends Logger {
+    /**
+     * Creates a new ConsoleLogger instance.
+     * @constructor
+     * @param {string} name - The name of the logger.
+     * @param {number} level - The logging level.
+     * @param {module} log4jsModule - Log4js library
+     */
+    constructor(name: string, level: number, log4jsModule: any);
+    _logger: any;
+}
+import Logger = require("./logger");