From 19c9707d62569ff2017659b623c349141988e9dc Mon Sep 17 00:00:00 2001 From: Nick O'Leary Date: Tue, 28 Aug 2018 13:45:38 +0100 Subject: [PATCH] Get jdsoc tagging right for util module --- packages/node_modules/@node-red/util/index.js | 6 +-- .../node_modules/@node-red/util/lib/i18n.js | 32 ++++++++++++ .../node_modules/@node-red/util/lib/log.js | 52 +++++++++++++++++++ .../node_modules/@node-red/util/lib/util.js | 45 ++++++++-------- 4 files changed, 110 insertions(+), 25 deletions(-) diff --git a/packages/node_modules/@node-red/util/index.js b/packages/node_modules/@node-red/util/index.js index e10098b18..7fa63fc7d 100644 --- a/packages/node_modules/@node-red/util/index.js +++ b/packages/node_modules/@node-red/util/index.js @@ -32,17 +32,17 @@ module.exports = { }, /** * Logging utilities - * @type module:@node-red/util-log + * @see module:@node-red/util.module:log */ log: log, /** * Internationalization utilities - * @type module:@node-red/util-i18n + * @see module:@node-red/util.module:i18n */ i18n: i18n, /** * General utilities - * @type module:@node-red/util-util + * @see module:@node-red/util.module:util */ util: util } diff --git a/packages/node_modules/@node-red/util/lib/i18n.js b/packages/node_modules/@node-red/util/lib/i18n.js index 7d0f1ad92..07f534dff 100644 --- a/packages/node_modules/@node-red/util/lib/i18n.js +++ b/packages/node_modules/@node-red/util/lib/i18n.js @@ -15,6 +15,11 @@ * @ignore **/ + /** + * @module i18n + * @memberof module:@node-red/util + */ + var i18n = require("i18next"); var when = require("when"); @@ -27,6 +32,10 @@ var resourceMap = {}; var resourceCache = {}; var initPromise; +/** + * Register multiple message catalogs with i18n. + * @memberof module:@node-red/util.module:i18n + */ function registerMessageCatalogs(catalogs) { var promises = catalogs.map(function(catalog) { return registerMessageCatalog(catalog.namespace,catalog.dir,catalog.file); @@ -34,6 +43,10 @@ function registerMessageCatalogs(catalogs) { return when.settle(promises); } +/** + * Register a message catalog with i18n. + * @memberof module:@node-red/util.module:i18n + */ function registerMessageCatalog(namespace,dir,file) { return initPromise.then(function() { return new Promise((resolve,reject) => { @@ -128,6 +141,13 @@ function init() { } } + +/** + * Gets a message catalog. + * @name catalog + * @function + * @memberof module:@node-red/util.module:i18n + */ function getCatalog(namespace,lang) { var result = null; lang = lang || defaultLang; @@ -148,10 +168,22 @@ var obj = module.exports = { registerMessageCatalog: registerMessageCatalog, registerMessageCatalogs: registerMessageCatalogs, catalog: getCatalog, + /** + * The underlying i18n library for when direct access is really needed + */ i: i18n, + /** + * The default language of the runtime + */ defaultLang: defaultLang } +/** + * Perform a message catalog lookup. + * @name _ + * @function + * @memberof module:@node-red/util.module:i18n + */ obj['_'] = function() { //var opts = {}; //if (def) { diff --git a/packages/node_modules/@node-red/util/lib/log.js b/packages/node_modules/@node-red/util/lib/log.js index f3c66dd98..8c52e3ed9 100644 --- a/packages/node_modules/@node-red/util/lib/log.js +++ b/packages/node_modules/@node-red/util/lib/log.js @@ -15,6 +15,11 @@ * @ignore **/ +/** + * @module log + * @memberof module:@node-red/util + */ + var util = require("util"); var EventEmitter = require("events").EventEmitter; @@ -87,7 +92,9 @@ var consoleLogger = function(msg) { } } + var log = module.exports = { + FATAL: 10, ERROR: 20, WARN: 30, @@ -119,40 +126,79 @@ var log = module.exports = { log.addHandler(new LogHandler()); } }, + + /** + * Add a log handler function. + */ addHandler: function(func) { logHandlers.push(func); }, + + /** + * Remove a log handler function. + */ removeHandler: function(func) { var index = logHandlers.indexOf(func); if (index > -1) { logHandlers.splice(index,1); } }, + + /** + * Log a message object. + */ log: function(msg) { msg.timestamp = Date.now(); logHandlers.forEach(function(handler) { handler.emit("log",msg); }); }, + + /** + * Log a message at INFO level. + */ info: function(msg) { log.log({level:log.INFO,msg:msg}); }, + + /** + * Log a message at WARN level. + */ warn: function(msg) { log.log({level:log.WARN,msg:msg}); }, + + /** + * Log a message at ERROR level. + */ error: function(msg) { log.log({level:log.ERROR,msg:msg}); }, + + /** + * Log a message at TRACE level. + */ trace: function(msg) { log.log({level:log.TRACE,msg:msg}); }, + + /** + * Log a message at DEBUG level. + */ debug: function(msg) { log.log({level:log.DEBUG,msg:msg}); }, + + /** + * Log a metric event. + */ metric: function() { return metricsEnabled; }, + /** + * Log an audit event. + */ audit: function(msg,req) { msg.level = log.AUDIT; if (req) { @@ -164,4 +210,10 @@ var log = module.exports = { } } +/** + * Perform a message catalog lookup. + * @name _ + * @function + * @memberof module:@node-red/util.module:log + */ log["_"] = i18n._; diff --git a/packages/node_modules/@node-red/util/lib/util.js b/packages/node_modules/@node-red/util/lib/util.js index cb0660e24..896a2c25d 100644 --- a/packages/node_modules/@node-red/util/lib/util.js +++ b/packages/node_modules/@node-red/util/lib/util.js @@ -15,16 +15,21 @@ * @ignore **/ + /** + * @module util + * @memberof module:@node-red/util + */ + + const clone = require("clone"); const jsonata = require("jsonata"); const safeJSONStringify = require("json-stringify-safe"); const util = require("util"); - /** * Generates a psuedo-unique-random id. * @return {String} a random-ish id - * @memberof module:@node-red/util-util + * @memberof module:@node-red/util.module:util */ function generateId() { return (1+Math.random()*4294967295).toString(16); @@ -36,7 +41,7 @@ function generateId() { * * @param {any} o - the property to convert to a String * @return {String} the stringified version - * @memberof module:@node-red/util-util + * @memberof module:@node-red/util.module:util */ function ensureString(o) { if (Buffer.isBuffer(o)) { @@ -55,7 +60,7 @@ function ensureString(o) { * * @param {any} o - the property to convert to a Buffer * @return {String} the Buffer version - * @memberof module:@node-red/util-util + * @memberof module:@node-red/util.module:util */ function ensureBuffer(o) { if (Buffer.isBuffer(o)) { @@ -74,7 +79,7 @@ function ensureBuffer(o) { * * @param {any} msg - the message object to clone * @return {Object} the cloned message - * @memberof module:@node-red/util-util + * @memberof module:@node-red/util.module:util */ function cloneMessage(msg) { // Temporary fix for #97 @@ -101,7 +106,7 @@ function cloneMessage(msg) { * @param {any} obj1 * @param {any} obj2 * @return {boolean} whether the two objects are the same - * @memberof module:@node-red/util-util + * @memberof module:@node-red/util.module:util */ function compareObjects(obj1,obj2) { var i; @@ -178,7 +183,7 @@ function compareObjects(obj1,obj2) { * * @param {String} str - the property expression * @return {Array} the normalised expression - * @memberof module:@node-red/util-util + * @memberof module:@node-red/util.module:util */ function normalisePropertyExpression(str) { // This must be kept in sync with validatePropertyExpression @@ -293,7 +298,7 @@ function normalisePropertyExpression(str) { * @param {Object} msg - the message object * @param {String} str - the property expression * @return {any} the message property, or undefined if it does not exist - * @memberof module:@node-red/util-util + * @memberof module:@node-red/util.module:util */ function getMessageProperty(msg,expr) { if (expr.indexOf('msg.')===0) { @@ -308,7 +313,7 @@ function getMessageProperty(msg,expr) { * @param {Object} msg - the object * @param {String} str - the property expression * @return {any} the object property, or undefined if it does not exist - * @memberof module:@node-red/util-util + * @memberof module:@node-red/util.module:util */ function getObjectProperty(msg,expr) { var result = null; @@ -331,7 +336,7 @@ function getObjectProperty(msg,expr) { * @param {String} prop - the property expression * @param {any} value - the value to set * @param {boolean} createMissing - whether to create missing parent properties - * @memberof module:@node-red/util-util + * @memberof module:@node-red/util.module:util */ function setMessageProperty(msg,prop,value,createMissing) { if (prop.indexOf('msg.')===0) { @@ -347,7 +352,7 @@ function setMessageProperty(msg,prop,value,createMissing) { * @param {String} prop - the property expression * @param {any} value - the value to set * @param {boolean} createMissing - whether to create missing parent properties - * @memberof module:@node-red/util-util + * @memberof module:@node-red/util.module:util */ function setObjectProperty(msg,prop,value,createMissing) { if (typeof createMissing === 'undefined') { @@ -411,7 +416,7 @@ function setObjectProperty(msg,prop,value,createMissing) { * will return `Hello Joe!`. * @param {String} value - the string to parse * @return {String} The parsed string -* @memberof module:@node-red/util-util +* @memberof module:@node-red/util.module:util */ function evaluateEnvProperty(value) { if (/^\${[^}]+}$/.test(value)) { @@ -439,7 +444,7 @@ function evaluateEnvProperty(value) { * * @param {String} value - the context property string to parse * @return {Object} The parsed property - * @memberof module:@node-red/util-util + * @memberof module:@node-red/util.module:util */ function parseContextStore(key) { var parts = {}; @@ -463,7 +468,7 @@ function parseContextStore(key) { * @param {Object} msg - the message object to evaluate against * @param {Function} callback - (optional) called when the property is evaluated * @return {any} The evaluted property, if no `callback` is provided - * @memberof module:@node-red/util-util + * @memberof module:@node-red/util.module:util */ function evaluateNodeProperty(value, type, node, msg, callback) { var result = value; @@ -520,7 +525,7 @@ function evaluateNodeProperty(value, type, node, msg, callback) { * @param {String} value - the JSONata expression * @param {Node} node - the node evaluating the property * @return {Object} The JSONata expression that can be evaluated - * @memberof module:@node-red/util-util + * @memberof module:@node-red/util.module:util */ function prepareJSONataExpression(value,node) { var expr = jsonata(value); @@ -548,7 +553,7 @@ function prepareJSONataExpression(value,node) { * @param {Object} msg - the message object to evaluate against * @param {Function} callback - (optional) called when the expression is evaluated * @return {any} If no callback was provided, the result of the expression - * @memberof module:@node-red/util-util + * @memberof module:@node-red/util.module:util */ function evaluateJSONataExpression(expr,msg,callback) { var context = msg; @@ -593,7 +598,7 @@ function evaluateJSONataExpression(expr,msg,callback) { * * @param {String} name - the node type * @return {String} The normalised name - * @memberof module:@node-red/util-util + * @memberof module:@node-red/util.module:util */ function normaliseNodeTypeName(name) { var result = name.replace(/[^a-zA-Z0-9]/g, " "); @@ -617,7 +622,7 @@ function normaliseNodeTypeName(name) { * @param {Object} msg * @param {Object} opts * @return {Object} the encoded object - * @memberof module:@node-red/util-util + * @memberof module:@node-red/util.module:util */ function encodeObject(msg,opts) { var debuglength = 1000; @@ -746,10 +751,6 @@ function encodeObject(msg,opts) { return msg; } -/** - * General utilities - * @module @node-red/util-util - */ module.exports = { encodeObject: encodeObject, ensureString: ensureString,