@creejs/commons-logging 1.0.0

package/lib/index.js

@@ -0,0 +1,257 @@
+'use strict'
+/**
+ * @module CommonsLogging
+ * @description Common logging library
+ *
+ * Follow the sequence to init log system: addProvider() -> use() -> configure() -> getLogger()
+ * 1. Add ability to handle the type of library
+ *    * eg. after adding Log4jsProvider, we can use Log4js library
+ * 2. But we MAY NOT use it now.
+ *    * call useProvider(typeName) to select which kind of LogProvider Implementation to use.
+ *    * call configure(typeName, nativeLib, setting) to LogProvider Implementation
+ */
+// 3rd
+// internal
+const {
+  TypeAssert: { assertNotNil, assertString },
+  TypeUtils: { isFunction, isNil }
+} = require('@creejs/commons-lang')
+
+// owned
+const LogFactory = require('./log-factory')
+const Logger = require('./logger')
+const ProviderType = require('./provider-type')
+const LogLevel = require('./log-level')
+const LogConfig = require('./log-config')
+
+const ConsoleProvider = require('./console')
+const Log4jsProvider = require('./log4js')
+const Provider = require('./provider')
+
+// module vars
+
+/**
+ * Store Created Loggers, indexed with Names
+ * @type {Map<string, Logger>}
+ * @private
+ */
+const name2Logger = new Map()
+
+/**
+   * set Global logging level
+   * @param {'TRACE'|'DEBUG'|'INFO'|'WARN'|'ERROR'|'FATAL'|'OFF'|'trace'|'debug'|'info'|'warn'|'error'|'fatal'|'off'} level - The log level
+   */
+function setLevel (level) {
+  assertString(level)
+  const upperLevel = level.toUpperCase()
+  const levelNumber = LogLevel.name2Value(upperLevel)
+  if (levelNumber == null) {
+    throw new Error(`Invalid log level: ${level}`)
+  }
+  if (levelNumber === LogConfig.currentLevel) {
+    return // no change
+  }
+  LogConfig.currentLevel = levelNumber
+
+  // refresh existed factories
+  for (const [, factory] of LogConfig.listFactories()) {
+    factory.setLevel(levelNumber)
+  }
+  // refresh existed Loggers
+  for (const logger of name2Logger.values()) {
+    if (logger.level !== levelNumber) {
+      logger.setLevel(levelNumber)
+    }
+  }
+}
+
+function currentProvider () {
+  return LogConfig.currentProvider
+}
+
+/**
+ * Set the provider using currently
+ * @param {string} typeName - The type name of the logging provider to use.
+ * @returns {void}
+ * @throws {Error} If the provider name is unknown.
+ */
+function useProvider (typeName) {
+  assertString(typeName)
+  typeName = typeName.toUpperCase()
+  const provider = LogConfig.getProvider(typeName)
+  if (provider == null) {
+    throw new Error(`No Provider Named with: ${typeName}`)
+  }
+  LogConfig.currentProvider = typeName
+}
+
+/**
+ * Removes and returns the provider associated with the given type name.
+ * If no provider exists for the type name, the function returns undefined.
+ *
+ * @param {string} typeName - The type name of the provider to remove.
+ * @returns {boolean} The removed provider, or undefined if not found.
+ */
+function removeProvider (typeName) {
+  if (typeName == null) {
+    return false
+  }
+  assertString(typeName)
+  typeName = typeName.toUpperCase()
+  return LogConfig.removeProvider(typeName)
+}
+
+/**
+ * Add a type of Provider
+ *
+ * More:
+ * 1. A Provider is a Module
+ * 2. The module must include the following functions:
+ *   1. getType() - Returns the type name of the provider.
+ *   2. createLogFactory() - Creates a new LogFactory instance.
+ * @param {Provider} provider - Logging Library Module
+ * @returns {void}
+ */
+function addProvider (provider) {
+  assertNotNil(provider)
+  const { getType, createLogFactory } = provider
+  if (!isFunction(getType) || !isFunction(createLogFactory)) {
+    throw new Error('Invalid Provider Module, missing getType(), createLogFactory() functions')
+  }
+  let typeName = provider.getType()
+  assertString(typeName)
+  typeName = typeName.toUpperCase()
+  LogConfig.addProvider(typeName, provider)
+  // set current provider if not set yet
+  if (isNil(currentProvider())) {
+    useProvider(typeName)
+  }
+}
+
+function clearProviders () {
+  name2Logger.clear()
+  LogConfig.clear()
+}
+
+/**
+ * configure provider to initialize its LogFactory
+ * 1. find the LogProvider Implementation of "typeName"
+ *    * if type is not supported, throw error
+ * 2. use the nativeLib and setting to initialize the LogProvider
+ * 3. create a LogFactory via teh LogProvider
+ * @param {string} typeName - The type of logging provider to configure.
+ * @param {*} [nativeLib] - The native library to use for logging.
+ * @param {*} [setting] - Configuration settings for the logging provider.
+ * @throws {Error} If the typeName is not recognized.
+ */
+function configureProvider (typeName, nativeLib, setting) {
+  assertString(typeName)
+  typeName = typeName.toUpperCase()
+  const provider = LogConfig.getProvider(typeName)
+  if (provider == null) {
+    throw new Error(`No Provider: ${typeName}`)
+  }
+  const factory = provider.createLogFactory(nativeLib, setting)
+  LogConfig.addFactory(typeName, factory)
+}
+
+/**
+ * Configures and immediately uses a logging provider with the given settings.
+ * @param {string} typeName - The type/name identifier for the provider.
+ * @param {*} nativeLib - The native library implementation to configure.
+ * @param {*} setting - Configuration settings for the provider.
+ */
+function configureThenUseProvider (typeName, nativeLib, setting) {
+  configureProvider(typeName, nativeLib, setting)
+  useProvider(typeName)
+}
+
+/**
+ * Gets a logger instance for the specified logger name using the current provider.
+ * @param {string} loggerName - The name of the logger to retrieve.
+ * @returns {Logger} The logger instance.
+ * @throws {Error} If no default provider is set or if the current provider is not initialized.
+ */
+function getLogger (loggerName) {
+  // if logger already exists, return it
+  let logger = name2Logger.get(loggerName)
+  if (logger != null) {
+    return logger
+  }
+  // create a new logger via the current provider's LogFactory
+  const currentTypeName = currentProvider()
+  if (currentTypeName == null) {
+    throw new Error('No Default LogProvider, call useProvider(typeName)')
+  }
+  const factory = LogConfig.getFactory(currentTypeName)
+  if (factory == null) {
+    throw new Error('configureProvider(typeName, nativeLib, settting) before getting logger via Provider')
+  }
+  logger = factory.createLogger(loggerName)
+  name2Logger.set(loggerName, logger)
+  return logger
+}
+
+function initLogSystem () {
+  addProvider(Log4jsProvider)
+  // ConsoleProvider as default impl
+  addProvider(ConsoleProvider)
+  configureProvider(ProviderType.Console, console)
+  useProvider(ProviderType.Console) // Use ConsoleLogger as default
+}
+
+initLogSystem()
+
+const CommonsLogging = {
+  Provider,
+  LogFactory,
+  Logger,
+  LogLevel,
+  ProviderType,
+  getLogger,
+  setLevel,
+  useProvider,
+  /**
+   * alias for {@link CommonsLogging.useProvider}
+   * @see {@link CommonsLogging.useProvider}
+   * @function
+   * @alias module:CommonsLogging.use
+   */
+  use: useProvider,
+  configureProvider,
+  /**
+   * @function
+   * @alias module:CommonsLogging.confiure
+   */
+  configure: configureProvider,
+  configureThenUseProvider,
+  /**
+   * @function
+   * @alias module:CommonsLogging.configureThenUseProvider
+   */
+  configureThenUse: configureThenUseProvider,
+  addProvider,
+  add: addProvider,
+  clearProviders,
+  currentProvider,
+  /**
+   * @function
+   * @alias module:CommonsLogging.current
+   */
+  current: currentProvider,
+  removeProvider,
+  /**
+   * @function
+   * @alias module:CommonsLogging.remove
+   */
+  remove: removeProvider,
+  /**
+   * @alias module:CommonsLogging.ConsoleProvider
+   */
+  ConsoleProvider,
+  /**
+   * @alias module:CommonsLogging.Log4jsProvider
+   */
+  Log4jsProvider
+}
+module.exports = CommonsLogging

package/lib/log-config.js

@@ -0,0 +1,157 @@
+'use strict'
+// internal
+const { TypeAssert: { assertString } } = require('@creejs/commons-lang')
+// owned
+const { DefaultLevel } = require('./log-level')
+// eslint-disable-next-line no-unused-vars
+const LogFactory = require('./log-factory')
+const Provider = require('./provider')
+/**
+ * type name of current provider
+ * @type {string}
+ * @public
+ */
+// @ts-ignore
+// eslint-disable-next-line prefer-const
+let currentProvider = null
+
+/**
+ * Global logging level
+ * @type {number}
+ * @public
+ */
+// @ts-ignore
+// eslint-disable-next-line prefer-const
+let currentLevel = DefaultLevel
+
+/**
+ * The map of registered logging libraries
+ * @type {Map<string,Provider>}
+ * @private
+ */
+const type2Provider = new Map()
+
+/**
+ * Adds a logging provider for the specified type.
+ * @param {string} typeName - The type identifier for the provider.
+ * @param {Provider} provider - The logging provider implementation.
+ * @returns {void}
+ */
+function addProvider (typeName, provider) {
+  assertString(typeName)
+  Provider.assertProviderLike(provider)
+  type2Provider.set(typeName, provider)
+}
+
+/**
+ * Gets the logging provider for the specified type name.
+ * @param {string} typeName - The type name to look up in the provider map.
+ * @returns {Provider|undefined} The logging provider instance if found, otherwise undefined.
+ */
+function getProvider (typeName) {
+  assertString(typeName)
+  return type2Provider.get(typeName)
+}
+
+/**
+ * Removes a logging provider of the specified type.
+ * @param {string} typeName - The type name of the provider to remove.
+ * @returns {boolean}
+ */
+function removeProvider (typeName) {
+  assertString(typeName)
+  return type2Provider.delete(typeName)
+}
+
+function clearProviders () {
+  type2Provider.clear()
+}
+
+/**
+ * Returns an array of all registered factory types and intances.
+ * 1. Each entry is a [type, factory] pair
+ * @returns {Array<[string, Provider]>} An array of factory entries.
+ */
+function listProviders () {
+  return [...type2Provider.entries()]
+}
+
+/**
+ * Created LogFactories Index with type name
+ * @type {Map<string, LogFactory>}
+ * @public
+ */
+const type2Factory = new Map()
+
+/**
+ * Registers a log factory for a given type name.
+ * @param {string} typeName - The name of the log type to register.
+ * @param {LogFactory} logFactory - Factory function that creates a logger for the specified type.
+ */
+function addFactory (typeName, logFactory) {
+  assertString(typeName)
+  LogFactory.assertLogFactoryLike(logFactory)
+  type2Factory.set(typeName, logFactory)
+}
+
+/**
+ * Removes a factory of the given type from the type-to-factory mapping.
+ * @param {string} typeName - The name of the type whose factory should be removed.
+ * @returns {boolean}
+ */
+function removeFactory (typeName) {
+  assertString(typeName)
+  return type2Factory.delete(typeName)
+}
+
+/**
+ * Gets the factory function associated with the given type name.
+ * @param {string} typeName - The name of the type to look up.
+ * @returns {LogFactory|undefined} The factory function for the specified type.
+ */
+function getFactory (typeName) {
+  assertString(typeName)
+  return type2Factory.get(typeName)
+}
+
+/**
+ * Clears all registered factories from the type2Factory instance.
+ * This is typically used to reset the factory state during testing or teardown.
+ */
+function clearFactories () {
+  type2Factory.clear()
+}
+
+/**
+ * Returns an array of all registered factory types and intances.
+ * 1. Each entry is a [type, factory] pair
+ * @returns {Array<[string, LogFactory]>} An array of factory entries.
+ */
+function listFactories () {
+  return [...type2Factory.entries()]
+}
+
+function clear () {
+  clearProviders()
+  clearFactories()
+}
+
+const LogConfig = {
+  currentProvider,
+  currentLevel,
+  type2Provider,
+  type2Factory,
+  addProvider,
+  getProvider,
+  removeProvider,
+  clearProviders,
+  listProviders,
+  addFactory,
+  getFactory,
+  removeFactory,
+  clearFactories,
+  listFactories,
+  clear
+}
+
+module.exports = LogConfig

package/lib/log-factory.js

@@ -0,0 +1,88 @@
+'use strict'
+
+// owned
+// eslint-disable-next-line no-unused-vars
+const Logger = require('./logger')
+
+/**
+ * @abstract
+ */
+class LogFactory {
+  /**
+   * Checks if a value resembles a LogFactory by verifying it has required methods.
+   * @param {*} value - The value to check
+   * @returns {boolean}
+   */
+  static isLogFactoryLike (value) {
+    if (value == null) {
+      return false
+    }
+    return typeof value === 'object' && typeof value.createLogger === 'function' && typeof value.setLevel === 'function'
+  }
+
+  /**
+   * Asserts that the given value is a valid LogFactory-Like object.
+   * @throws {Error} Throws an error if the value is not LogFactory-Like
+   * @param {*} value - The value to check.
+   */
+  static assertLogFactoryLike (value) {
+    if (!this.isLogFactoryLike(value)) {
+      throw new Error('Not LogFactory')
+    }
+  }
+
+  /**
+   * Creates a new logging provider instance.
+   * @param {{}} libraryModule - the library module
+   * @param {{}} setting - Configuration settings for the provider
+   */
+  constructor (libraryModule, setting) {
+    this._libraryModule = libraryModule
+    this._setting = setting
+  }
+
+  get libraryModule () {
+    return this._libraryModule
+  }
+
+  get setting () {
+    return this._setting
+  }
+
+  /**
+   * Initializes the logging provider.
+   * 1. Do nothing in the default implementation.
+   * 2. Override this method to initialize the provider.
+   * @returns {Promise<void>|void}
+   */
+  init () {
+    // do nothing
+  }
+
+  /**
+   * Update factory's Log Level
+   * 1. Only Provider knows how to update
+   *    * update level in "setting", so the new created Logger will use the new level
+   * 2. called when users want to change global log level via CommonsLogging.setLevel()
+   * @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) {
+    throw new Error('Not Impled Yet')
+  }
+
+  /**
+   * Creates a new logger named with the "loggerName"
+   * @param {string} loggerName - The name to associate with the logger instance.
+   * @throws {Error} Throws an error indicating the method is Not Impled Yet yet.
+   * @returns {Logger} A new logger intance
+   * @abstract
+   */
+  createLogger (loggerName) {
+    throw new Error('Not Impled Yet')
+  }
+}
+
+module.exports = LogFactory

package/lib/log-level.js

@@ -0,0 +1,163 @@
+'use strict'
+
+const { TypeUtils: { isNumber, isString } } = require('@creejs/commons-lang')
+
+/**
+ * @namespace LogLevel
+ * @description Defines the logging levels and provides utilities for working with them.
+ */
+// module vars
+const TRACE = 'TRACE'
+const DEBUG = 'DEBUG'
+const INFO = 'INFO'
+const WARN = 'WARN'
+const ERROR = 'ERROR'
+const FATAL = 'FATAL'
+const OFF = 'OFF'
+const ALL = 'ALL'
+
+const Names = new Set([TRACE, DEBUG, INFO, WARN, ERROR, FATAL, OFF, ALL])
+/**
+ * The logging level numbers, where OFF=-1, FATAL=0, ERROR=1, WARN=2, INFO=3, DEBUG=4, TRACE=5, ALL=6
+ * @enum {number}
+ * @memberof LogLevel
+ * @static
+ */
+const Level = {
+  OFF: -1,
+  FATAL: 0,
+  ERROR: 1,
+  WARN: 2,
+  INFO: 3,
+  DEBUG: 4,
+  TRACE: 5,
+  ALL: 6
+}
+
+/**
+ * Standard logging level names
+ * @enum {string}
+ * @memberof LogLevel
+ * @static
+ * @constant
+ */
+const Name = {
+  TRACE,
+  DEBUG,
+  INFO,
+  WARN,
+  ERROR,
+  FATAL,
+  OFF
+}
+
+/**
+ * Internal map for quick lookup of level names by their numeric values
+ * @type {Map<number, string>}
+ * @private
+ */
+const Value2Name = new Map()
+for (const [name, value] of Object.entries(Level)) {
+  Value2Name.set(value, name)
+}
+
+/**
+ * The default logging level (ERROR)
+ * @type {number}
+ * @memberof LogLevel
+ * @static
+ */
+const DefaultLevel = Level.ERROR
+
+/**
+ * Converts a numeric logging level value to its corresponding name.
+ * @param {number} value - The numeric logging level value to convert.
+ * @returns {string|undefined} The name associated with the given logging level value, from {@link LogLevel.Name}.
+ * @memberof LogLevel
+ * @static
+ */
+function value2Name (value) {
+  if (!isNumber(value)) {
+    return undefined
+  }
+  return Value2Name.get(value)
+}
+
+/**
+ * Converts a logging level name to its corresponding numeric value.
+ * @param {string} name - The name of the logging level.
+ * @returns {number|undefined} The numeric value of the logging level from {@link LogLevel.Level}, or undefined if name is not supported.
+ * @memberof LogLevel
+ * @static
+ */
+function name2Value (name) {
+  if (!isString(name)) {
+    return undefined
+  }
+  // @ts-ignore
+  return Level[name.toUpperCase()]
+}
+
+/**
+ * Checks if the given level is a valid log level.
+ * @param {number} level - The log level to check.
+ * @returns {boolean} True if the level is valid, false otherwise.
+ */
+function hasLevel (level) {
+  return Value2Name.has(level)
+}
+
+/**
+ * Checks if the given level name exists in the Name enum/object.
+ * @param {string} levelName - The name of the log level to check.
+ * @returns {boolean} True if the level name exists, false otherwise.
+ */
+function hasName (levelName) {
+  if (!isString(levelName)) {
+    return false
+  }
+  return Names.has(levelName.toUpperCase())
+}
+
+/**
+ * Validates that a given level is a number and falls within the valid range.
+ * @param {*} level - The log level to validate
+ * @throws {Error} If level is not a number or outside valid range (Level.OFF to Level.ALL)
+ */
+function assertLevel (level) {
+  if (!isNumber(level)) {
+    throw new Error(`Level Not Number: type=${typeof level} value=${level}`)
+  }
+  if (level < Level.OFF || level > Level.ALL) {
+    throw new Error(`Not Valid Level: ${level}, Expect between ${Level.OFF} and ${Level.ALL}`)
+  }
+}
+
+const LogLevel = {
+  Name,
+  Level,
+  DefaultLevel,
+  hasLevel,
+  hasName,
+  assertLevel,
+  /**
+   *  Same with [Name]{@link LogLevel.Name}
+   *  @type {Object}
+   *  @memberof LogLevel
+   *  @static
+   */
+  LevelName: Name,
+  /**
+   *  Same with [Level]{@link LogLevel.Level}
+   *  @type {Object}
+   *  @memberof LogLevel
+   *  @static
+   */
+  LevelValue: Level,
+
+  value2Name,
+
+  name2Value
+}
+
+module.exports = LogLevel

package/lib/log4js/index.js

@@ -0,0 +1,11 @@
+'use strict'
+
+// internal
+
+// owned
+const Log4jsProvider = require('./log4js-provider')
+
+// module vars
+const log4jsProvider = new Log4jsProvider()
+
+module.exports = log4jsProvider

package/lib/log4js/log4js-6x-config.js

@@ -0,0 +1,12 @@
+'use strict'
+
+const DefaultConfig = { // 6x fromat
+  appenders: {
+    out: { type: 'console' }
+  },
+  categories: {
+    default: { appenders: ['out'], level: 'error' }
+  }
+}
+
+module.exports = DefaultConfig