@creejs/commons-logging 1.0.0

package/README.md

@@ -0,0 +1,291 @@
+# @creejs/commons-logging
+A Common Logging Library:
+
+- **light-weight, No 3rd Dependencies**
+
+  Obey style of commons-logging, Output logs to Console
+
+- **Log4js supported**
+
+  Work with log4js smoothly, No Changes to existed codes
+
+- **use Property to check LogLevel**
+
+  - properties like: logger.errorEnabled, logger.traceEnabled, ...
+  - Also Support: logger.isErrorEnabled(), logger.isTraceEnabled(), ...
+
+- **Extensible via Provider mechanism**
+
+  Easy to support more Logging Libraries via adding new Providers
+
+
+
+## Install
+
+```shell
+npm intall @creejs/commons-logging
+```
+
+
+
+## Usage
+
+The short examples demostrate some basic usages:
+
+- ##### Embbed Console-Logging
+
+```javascript
+const { getLogger } = require('@creejs/commons-logging')
+
+// get or create Logger instance with default level: error
+const logger = getLogger('logger1')
+
+// logging, use property to check level
+logger.errorEnabled && logger.error('This a', 'test string')
+// 2025-07-14T09:28:30.442Z logger1 [Debug] This a test string
+
+// logging, use method to check level
+logger.isErrorEnabled() && logger.error('This a', 'test string')
+// 2025-07-14T09:28:30.445Z logger1 [Debug] This a test string
+```
+
+- ##### Work with Log4js
+
+````javascript
+const { ProviderType, configureThenUse, getLogger } = require('@creejs/commons-logging')
+const Log4js = require('log4js')
+
+// inject Log4js with default setting: log to Console with Error level
+configureThenUse(ProviderType.Log4js, Log4js)
+
+// get or create Logger instance
+const logger = getLogger('logger1')
+
+// logging
+logger.errorEnabled && logger.error('This a', 'test string')
+// 2025-07-14T09:43:21.508Z logger1 [Error] This a test string
+
+logger.isFatalEnabled() && logger.fatal('Another', 'message')
+// 2025-07-14T09:43:21.511Z logger1 [Fatal] Another message
+````
+
+#### Work with Log4js, use customized settings
+
+```javascript
+const { ProviderType, configure, use, getLogger } = require('@creejs/commons-logging')
+const Log4js = require('log4js')
+
+const setting = { // log4js 6.x syntax
+  appenders: {
+    out: { type: 'console' }
+  },
+  categories: {
+    default: { appenders: ['out'], level: 'info' }
+  }
+}
+// inject Log4js with default setting: log to Console with Error level
+configure(ProviderType.Log4js, Log4js, setting)
+// use log4js as Current Log Provider
+use(ProviderType.Log4js)
+
+// get or create Logger instance
+const logger = getLogger('logger1')
+
+// logging
+logger.errorEnabled && logger.error('log4js error string')
+// [2025-07-14T19:37:45.308] [ERROR] logger1 - log4js error string
+
+logger.isInfoEnabled() && logger.info('log4js info string')
+// [2025-07-14T19:37:45.312] [INFO] logger1 - log4js info string
+```
+
+
+
+## Add New Provider
+
+See the Example under **/examples/new-provider**
+
+Add a new Provider to support new Logging Libraries,  the limited  steps should be following:
+
+- Implement the **Provider** Interface
+- Implement the **LogFactory** abstract class
+- Implement the **Logger** abstract class
+- Export a Provider Instance
+- Add Provider
+- Configure Provider
+- Use Provider
+
+##### Implement the **Provider** Interface
+
+The Provider Class:
+
+```javascript
+class Provider {
+  /**
+   * @return {String} The type of the provider.
+   */
+  getType () {
+    throw new Error('Not Impled Yet')
+  }
+
+  /**
+   * Create a new LogFactory instance 
+   * @param {*} [nativeLib] - eg. log4js
+   * @param {*} [setting] - eg. log4js' Setting JSON
+   * @returns {LogFactory} A new instance of LogFactory.
+   */
+  createLogFactory (nativeLib, setting) {
+    throw new Error('Not Impled Yet')
+  }
+}
+```
+
+
+
+##### Implement the **LogFactory** abstract class
+
+```javascript
+class LogFactory {
+  /**
+   * 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}
+   * @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')
+  }
+}
+```
+
+
+
+##### Implement the Logger abstract class
+
+```javascript
+class Logger {
+  /**
+   * 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')
+  }
+}
+```
+
+
+
+##### Export a Provider Instance
+
+Put your Provider, LogFactory, Logger inside one Folder, and export the **new Provider()** inside index.js
+
+```javascript
+'user strict'
+const YourProvider = require('./provider')
+
+module.exports = new YourProvider()
+```
+
+##### Add->Configure->Use Provider
+
+```javascript
+const { add, configure, use, getLogger } = require('@creejs/commons-logging')
+
+const newProvider = require('YourProviderModule')
+
+// add your Provider
+add(newProvider)
+// configure your Provider
+configure(newProvider.getType(), ThirdPartLib, yourSetting)
+// set your Provider as Default
+use(newProvider.getType())
+```
+

package/index.js

@@ -0,0 +1,3 @@
+'use strict'
+
+module.exports = require('./lib')

package/lib/console/console-log-factory.js

@@ -0,0 +1,76 @@
+'use strict'
+
+// owned
+// eslint-disable-next-line no-unused-vars
+const Logger = require('../logger')
+// eslint-disable-next-line no-unused-vars
+const { Level, assertLevel } = require('../log-level')
+const LogFactory = require('../log-factory')
+const ConsoleLogger = require('./console-logger')
+const LogConfig = require('../log-config')
+
+/**
+ * Use Console as the native library
+ */
+class ConsoleLogFactory extends LogFactory {
+  /**
+   * the underlying "Console" Object.
+   * @returns {{}}
+   */
+  get console () {
+    return this._libraryModule // it's the embedded "console" object
+  }
+
+  /**
+   * Gets the current logging settings
+   * @returns {{level:number}} The logging settings object containing the current log level.
+   */
+  get setting () {
+    if (this._setting == null) {
+      this._setting = {
+        level: LogConfig.currentLevel
+      }
+    }
+    // @ts-ignore
+    return 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) {
+    assertLevel(level)
+    if (level !== this.setting.level) {
+      this.setting.level = level
+    }
+    // init again
+    this.init()
+  }
+
+  /**
+   * Initializes the log4js provider by configuring it with the provided settings.
+   * @async
+   * @override
+   * @returns {Promise<void>|void}
+   */
+  init () {
+    // do nothing
+  }
+
+  /**
+   * 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) {
+    return new ConsoleLogger(loggerName, this.console, this.setting.level)
+  }
+}
+
+module.exports = ConsoleLogFactory

package/lib/console/console-log-provider.js

@@ -0,0 +1,29 @@
+'use strict'
+
+const ProviderType = require('../provider-type')
+const Provider = require('../provider')
+const ConsoleLogFactory = require('./console-log-factory')
+
+class ConsoleProvider extends Provider {
+  /**
+   * Gets the provider type (Console).
+   * @returns {string} "CONSOLE"
+   * @override
+   */
+  getType () {
+    return ProviderType.Console
+  }
+
+  /**
+ * Creates a new Provider instance.
+ * @param {Object} libraryModule - The library module to be used.
+ * @param {Object} setting - Configuration settings for the provider.
+ * @returns {ConsoleLogFactory} A new instance of ConsoleProvider.
+ * @override
+ */
+  createLogFactory (libraryModule, setting) {
+    return new ConsoleLogFactory(libraryModule, setting)
+  }
+}
+
+module.exports = ConsoleProvider

package/lib/console/console-logger.js

@@ -0,0 +1,88 @@
+'use strict'
+
+// 3rd
+// internal
+// owned
+const Logger = require('../logger')
+// module vars
+/**
+ * A Simple Implementation of the Logger interface that logs to the console.
+ */
+class ConsoleLogger extends Logger {
+  /**
+   * Creates a ConsoleLogger instance.
+   * @constructor
+   * @param {string} name - The logger name.
+   * @param {*} nativeLogger - The native console object to use for logging.
+   * @param {number} level - The initial log level.
+   */
+  constructor (name, nativeLogger, level) {
+    super(name, nativeLogger, level)
+    /**
+     * @type {{error:function, warn:function, debug:function, log:function, info:function, trace:function}}
+     */
+    this.console = nativeLogger
+  }
+
+  /**
+   * For ConsoleLogger, Nothing to do
+   * @param {number} level
+   * @override
+   * @protectd
+   */
+  _setLevel (level) {
+    // do nothing
+  }
+
+  /**
+   * Logs a fatal error message with timestamp and logger name.
+   * Only outputs if fatal logging is enabled for this logger instance.
+   * @param {...any} args
+   */
+  _fatal (...args) {
+    this.console.error(new Date().toISOString(), this.name, '[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
+   */
+  _error (...args) {
+    this.console.error(new Date().toISOString(), this.name, '[Error]', ...args)
+  }
+
+  /**
+   * Logs a warning message to the console if warn logging is enabled.
+   * @param {...any} args
+   */
+  _warn (...args) {
+    this.console.warn(new Date().toISOString(), this.name, '[Warn]', ...args)
+  }
+
+  /**
+   * Logs debug messages to console if debug mode is enabled.
+   * @param {...any} args
+   */
+  _debug (...args) {
+    this.console.debug(new Date().toISOString(), this.name, '[Debug]', ...args)
+  }
+
+  /**
+   * Logs an info message to the console with timestamp and logger name.
+   * @param {...any} args
+   */
+  _info (...args) {
+    this.console.log(new Date().toISOString(), this.name, '[Info]', ...args)
+  }
+
+  /**
+   * Logs a trace message with timestamp and logger name if trace logging is enabled.
+   * @param {...any} args
+   */
+  _trace (...args) {
+    this.console.log(new Date().toISOString(), this.name, '[Trace]', ...args)
+  }
+}
+
+module.exports = ConsoleLogger

package/lib/console/index.js

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