@creejs/commons-logging 1.0.8 → 2.0.2

package/lib/index.js

@@ -1,286 +0,0 @@
-/**
- * @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
-import { TypeAssert, TypeUtils } from '@creejs/commons-lang'
-// owned
-import LogFactory from './log-factory.js'
-import Logger from './logger.js'
-import ProviderType from './provider-type.js'
-import LogLevel from './log-level.js'
-import LogConfig from './log-config.js'
-
-import ConsoleProvider from './console/index.js'
-import Log4jsProvider from './log4js/index.js'
-import Provider from './provider.js'
-
-const { assertNotNil, assertString } = TypeAssert
-const { isFunction, isNil } = TypeUtils
-
-/**
- * "default" export to support "import CommonsLogging from '@creejs/commons-logging'"
- */
-export default {
-  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
-}
-/**
- * "named" export to support
- * 1. import { getLogger, ... } from '@creejs/commons-logging'
- * 2. import * as CommonsLogging from '@creejs/commons-logging'
- */
-export { Provider }
-export { LogFactory }
-export { Logger }
-export { LogLevel }
-export { ProviderType }
-export { getLogger }
-export { setLevel }
-export { useProvider }
-export { useProvider as use }
-export { configureProvider }
-export { configureProvider as configure }
-export { configureThenUseProvider }
-export { configureThenUseProvider as configureThenUse }
-export { addProvider }
-export { addProvider as add }
-export { clearProviders }
-export { currentProvider }
-export { currentProvider as current }
-export { removeProvider }
-export { removeProvider as remove }
-export { ConsoleProvider }
-export { Log4jsProvider }
-
-// 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
-  // @ts-ignore
-  // eslint-disable-next-line no-unused-vars
-  for (const [typeName, 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()

package/lib/log-config.js

@@ -1,182 +0,0 @@
-// internal
-import { TypeAssert } from '@creejs/commons-lang'
-// owned
-import { DefaultLevel } from './log-level.js'
-// eslint-disable-next-line no-unused-vars
-import LogFactory from './log-factory.js'
-import Provider from './provider.js'
-
-const { assertString } = TypeAssert
-
-/**
- * @module LogConfig
- * @description Provide Impl of Log Configuration
- * @private
- */
-
-/**
- * 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()
-}
-
-export default {
-  currentProvider,
-  currentLevel,
-  type2Provider,
-  type2Factory,
-  addProvider,
-  getProvider,
-  removeProvider,
-  clearProviders,
-  listProviders,
-  addFactory,
-  getFactory,
-  removeFactory,
-  clearFactories,
-  listFactories,
-  clear
-}
-
-export {
-  currentProvider,
-  currentLevel,
-  type2Provider,
-  type2Factory,
-  addProvider,
-  getProvider,
-  removeProvider,
-  clearProviders,
-  listProviders,
-  addFactory,
-  getFactory,
-  removeFactory,
-  clearFactories,
-  listFactories,
-  clear
-}

package/lib/log-factory.js

@@ -1,84 +0,0 @@
-// owned
-// eslint-disable-next-line no-unused-vars
-import Logger from './logger.js'
-
-/**
- * @abstract
- */
-export default 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')
-  }
-}