1
0
mirror of https://github.com/node-red/node-red.git synced 2023-10-10 13:36:53 +02:00

Get jdsoc tagging right for util module

This commit is contained in:
Nick O'Leary 2018-08-28 13:45:38 +01:00
parent 79e004a040
commit 19c9707d62
No known key found for this signature in database
GPG Key ID: 4F2157149161A6C9
4 changed files with 110 additions and 25 deletions

View File

@ -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
}

View File

@ -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) {

View File

@ -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._;

View File

@ -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,