From 163d155238fc6a5aad65cc2a335876fdc41411c4 Mon Sep 17 00:00:00 2001 From: Evgeny Metelkin Date: Mon, 6 Sep 2021 13:31:31 +0300 Subject: [PATCH] logger and transport API --- api-references.md | 26 ++++++++---- src/logger.js | 105 ++++++++++++++++++++++++++++++++++++++++++++-- src/namespace.js | 4 ++ 3 files changed, 125 insertions(+), 10 deletions(-) diff --git a/api-references.md b/api-references.md index 7a33d72e..b16653cd 100644 --- a/api-references.md +++ b/api-references.md @@ -6,17 +6,29 @@ For users guidance and CLI references see the main [documentation site](https:// *Under developments. If you have questions contact the developers directly.* -## Classes +## Main classes - [Builder]{@link Builder} - [Container]{@link Container} - [Namespace]{@link Namespace} -- [Logger]{@link Logger} -- [Unit]{@link Unit} -- [Expression]{@link Expression} + +## Modules + - [ModuleSystem]{@link ModuleSystem} - [_Module]{@link _Module} -- Component -- _Size -- Const +## Elements + +- [Top]{@link Top} +- [Component]{@link Component} +- [Const]{@link Const} +- [Unit]{@link Unit} +- [Expression]{@link Expression} + +## Auxiliary + +- [Logger]{@link Logger} +- [Transport]{@link Transport} +- [JSONTransport]{@link JSONTransport} +- [StdoutTransport]{@link StdoutTransport} +- [StringTransport]{@link StringTransport} diff --git a/src/logger.js b/src/logger.js index ac102a7b..0dbf8a51 100644 --- a/src/logger.js +++ b/src/logger.js @@ -12,11 +12,25 @@ const levels = [ ]; class Logger { - constructor(showLogLevel = 'info'){ - this.showLogLevel = showLogLevel; + /** + * + * Object to work with several logging transports simultaneously. + * This class was inspired by package but much simpler. + * + * @property {Transport[]} _transports storage for different log transports. + * @property {boolean} _hasErrors Value is equal to `true` if there is at least one log of level 'error' or higher. + */ + constructor(){ this._transports = []; this._hasErrors = false; } + /** + * To attach another transport to a logger. + * + * @param {Transport} transport=() => {} `Transport` instance of function. + * + * @returns {Logger} Self. + */ addTransport(transport = () => {}){ let checkTransport = (transport instanceof Transport) || typeof transport === 'function'; @@ -26,9 +40,20 @@ class Logger { return this; } + /** + * Remove all transports from a logger. + */ clearTransport(){ this._transports = []; } + /** + * To add a new log event to logger. + * This event will be then sent to all transports. + * + * @param {string} level Log level: 'debug', 'info', 'warn', 'error', 'panic' + * @param {string} msg Log message. + * @param {object} opt Options for transport. + */ log(level, msg, opt){ let levelNum = levels.indexOf(level); if (levelNum < 0) { @@ -46,27 +71,75 @@ class Logger { } }); } + /** + * To add a 'debug' level message to logger. + * This is just a shortened version of the general log interface: + * ```js + * logger.debug('Something happens.') + * ``` + * + * which is the same as + * ```js + * logger.log('debug', 'Something happens.') + * ``` + * @param {string} msg Log message. + * @param {object} opt Options for transport. + */ debug(msg, opt){ this.log('debug', msg, opt); } + /** + * To add a 'info' level message to logger. + * This is just a shortened version of the general log interface: + + * @param {string} msg Log message. + * @param {object} opt Options for transport. + */ info(msg, opt){ this.log('info', msg, opt); } + /** + * To add a 'warn' level message to logger. + * This is just a shortened version of the general log interface: + + * @param {string} msg Log message. + * @param {object} opt Options for transport. + */ warn(msg, opt){ this.log('warn', msg, opt); } + /** + * To add a 'error' level message to logger. + * This is just a shortened version of the general log interface: + + * @param {string} msg Log message. + * @param {object} opt Options for transport. + */ error(msg, opt){ this.log('error', msg, opt); } + /** + * To check if there is a log event of level 'error' or higher. + */ get hasErrors(){ return this._hasErrors; } - resetErrors(){ // should be used only for testing properties + // should be used only for testing properties + resetErrors(){ this._hasErrors = false; } } class Transport { + /** + * Ways to analyze log events. Each transport does something with log event: prints to console, store in file, etc. + * See also {@link Logger}. + * + * @param {string} showLevel If level is equal or higher than the value it will be analyzed. + * Possible values: 'debug', 'info', 'warn', 'error', 'panic' + * + * @property {number} showLevelNum Numeric identifier of showLevel value: 0, 1, 2, 3, 4. + */ constructor(showLevel = 'info'){ let showLevelNum = levels.indexOf(showLevel); if (showLevelNum < 0) { @@ -74,12 +147,23 @@ class Transport { } this.showLevelNum = showLevelNum; } + /** + * Actions to perform when call log in parent `Logger`. + */ analyzer(){ throw new Error('Transport is abstract class'); } } class JSONTransport extends Transport{ + /** + * Transport type storing everything in a JS array. + * + * @extends Transport + * + * @param {string} showLevel If level is equal or higher than the value it will be analyzed. + * @param {object[]} target Array to store logs. + */ constructor(showLevel = 'info', target = []){ super(showLevel); this.target = target; @@ -92,6 +176,13 @@ class JSONTransport extends Transport{ } } +/** + * Transport type sending colored messages into console. + * + * @extends Transport + * + * @param {string} showLevel If level is equal or higher than the value it will be analyzed. + */ class StdoutTransport extends Transport { analyzer(level, msg, opt, levelNum){ let levelColors = [ @@ -109,6 +200,14 @@ class StdoutTransport extends Transport { } } +/** + * Transport type sending strings into array. + * + * @extends Transport + * + * @param {string} showLevel If level is equal or higher than the value it will be analyzed. + * @param {object[]} target Array to store logs. + */ class StringTransport extends Transport { constructor(showLevel = 'info', target = []){ super(showLevel); diff --git a/src/namespace.js b/src/namespace.js index 567facfa..8fecef2a 100644 --- a/src/namespace.js +++ b/src/namespace.js @@ -8,6 +8,10 @@ class Namespace extends Map { * * @extends Map * + * @property {Container} container Parent container. + * @property {string} _spaceName String identifier for namespace. + * @property {boolean} _isAbstract `true` if namespace is abstract. `false` otherwise. + * * @param {string} spaceName Space identifier. */ constructor(spaceName){