@creejs/commons-logging 2.0.0 → 2.0.2

package/lib/log-config.js

@@ -1,163 +0,0 @@
-'use strict'
-/**
- * @module LogConfig
- * @description Provide Impl of Log Configuration
- * @private
- */
-// 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}
- * @alias module:LogConfig.addProvider
- */
-function addProvider (typeName, provider) {
-  assertString(typeName)
-  Provider.assertProviderLike(provider)
-  type2Provider.set(typeName.toUpperCase(), 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.toUpperCase())
-}
-
-/**
- * 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.toUpperCase())
-}
-
-function clearProviders () {
-  type2Provider.clear()
-}
-
-/**
- * Returns an array of all registered factory types and intances.
- * 1. Each entry is a [type, factory] pair
- * @returns {Array<{0:string, 1: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.toUpperCase(), 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.toUpperCase())
-}
-
-/**
- * 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.toUpperCase())
-}
-
-/**
- * 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<{0:string, 1: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

@@ -1,88 +0,0 @@
-'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

@@ -1,169 +0,0 @@
-'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.
- * @memberof LogLevel
- * @static
- */
-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.
- * @memberof LogLevel
- * @static
- */
-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)
- * @memberof LogLevel
- * @static
- */
-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

@@ -1,11 +0,0 @@
-'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

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

package/lib/log4js/log4js-factory.js

@@ -1,90 +0,0 @@
-'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

@@ -1,111 +0,0 @@
-'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

@@ -1,35 +0,0 @@
-'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