mirror of
https://github.com/node-red/node-red.git
synced 2023-10-10 13:36:53 +02:00
Start documenting apis
This commit is contained in:
parent
19fa69811b
commit
4e21a5e557
14
Gruntfile.js
14
Gruntfile.js
@ -420,6 +420,13 @@ module.exports = function(grunt) {
|
||||
destination: 'docs',
|
||||
configure: './jsdoc.json'
|
||||
}
|
||||
},
|
||||
nodeREDUtil: {
|
||||
src: 'packages/node_modules/@node-red/util/**/*.js',
|
||||
options: {
|
||||
destination: 'packages/node_modules/@node-red/util/docs',
|
||||
configure: './jsdoc.json'
|
||||
}
|
||||
}
|
||||
},
|
||||
jsdoc2md: {
|
||||
@ -429,6 +436,13 @@ module.exports = function(grunt) {
|
||||
},
|
||||
src: 'packages/node_modules/@node-red/runtime/lib/api/*.js',
|
||||
dest: 'docs/runtime-api.md'
|
||||
},
|
||||
nodeREDUtil: {
|
||||
options: {
|
||||
separators: true
|
||||
},
|
||||
src: 'packages/node_modules/@node-red/util/**/*.js',
|
||||
dest: 'packages/node_modules/@node-red/util/docs/api.md'
|
||||
}
|
||||
}
|
||||
});
|
||||
|
@ -1,6 +1,6 @@
|
||||
{
|
||||
"opts": {
|
||||
"template": "./node_modules/ink-docstrap/template",
|
||||
"template": "./node_modules/minami",
|
||||
"destination": "./docs",
|
||||
"recurse": true
|
||||
},
|
||||
@ -9,7 +9,7 @@
|
||||
"dictionaries": ["jsdoc"]
|
||||
},
|
||||
"source": {
|
||||
"include": [
|
||||
"_include": [
|
||||
"./packages/node_modules/@node-red/runtime/lib/api"
|
||||
]
|
||||
},
|
||||
@ -18,5 +18,6 @@
|
||||
"theme":"yeti",
|
||||
"footer": "",
|
||||
"copyright": "Released under the Apache License v2.0"
|
||||
}
|
||||
},
|
||||
"plugins": ["plugins/markdown"]
|
||||
}
|
||||
|
@ -95,8 +95,8 @@
|
||||
"grunt-simple-mocha": "~0.4.1",
|
||||
"grunt-webdriver": "^2.0.3",
|
||||
"http-proxy": "^1.16.2",
|
||||
"ink-docstrap": "^1.3.2",
|
||||
"istanbul": "0.4.5",
|
||||
"minami": "1.2.3",
|
||||
"mocha": "^5.2.0",
|
||||
"should": "^8.4.0",
|
||||
"sinon": "1.17.7",
|
||||
|
11
packages/node_modules/@node-red/util/index.js
generated
vendored
11
packages/node_modules/@node-red/util/index.js
generated
vendored
@ -14,17 +14,26 @@
|
||||
* limitations under the License.
|
||||
**/
|
||||
|
||||
|
||||
/**
|
||||
* @namespace @node-red/util
|
||||
*/
|
||||
const log = require("./lib/log");
|
||||
const i18n = require("./lib/i18n");
|
||||
const util = require("./lib/util");
|
||||
|
||||
module.exports = {
|
||||
/**
|
||||
* Initialise the module with the runtime settings
|
||||
* @param {Object} settings
|
||||
*/
|
||||
init: function(settings) {
|
||||
log.init(settings);
|
||||
i18n.init();
|
||||
},
|
||||
log: log,
|
||||
i18n: i18n,
|
||||
/**
|
||||
* General utilities
|
||||
*/
|
||||
util: util
|
||||
}
|
||||
|
1
packages/node_modules/@node-red/util/lib/i18n.js
generated
vendored
1
packages/node_modules/@node-red/util/lib/i18n.js
generated
vendored
@ -12,6 +12,7 @@
|
||||
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||
* See the License for the specific language governing permissions and
|
||||
* limitations under the License.
|
||||
* @ignore
|
||||
**/
|
||||
|
||||
var i18n = require("i18next");
|
||||
|
1
packages/node_modules/@node-red/util/lib/log.js
generated
vendored
1
packages/node_modules/@node-red/util/lib/log.js
generated
vendored
@ -12,6 +12,7 @@
|
||||
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||
* See the License for the specific language governing permissions and
|
||||
* limitations under the License.
|
||||
* @ignore
|
||||
**/
|
||||
|
||||
var util = require("util");
|
||||
|
182
packages/node_modules/@node-red/util/lib/util.js
generated
vendored
182
packages/node_modules/@node-red/util/lib/util.js
generated
vendored
@ -12,17 +12,32 @@
|
||||
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||
* See the License for the specific language governing permissions and
|
||||
* limitations under the License.
|
||||
* @ignore
|
||||
**/
|
||||
|
||||
var clone = require("clone");
|
||||
var jsonata = require("jsonata");
|
||||
var safeJSONStringify = require("json-stringify-safe");
|
||||
var util = require("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 @node-red/util.util
|
||||
*/
|
||||
function generateId() {
|
||||
return (1+Math.random()*4294967295).toString(16);
|
||||
}
|
||||
|
||||
/**
|
||||
* Converts the provided argument to a String, using type-dependent
|
||||
* methods.
|
||||
*
|
||||
* @param {any} o - the property to convert to a String
|
||||
* @return {String} the stringified version
|
||||
* @memberof @node-red/util.util
|
||||
*/
|
||||
function ensureString(o) {
|
||||
if (Buffer.isBuffer(o)) {
|
||||
return o.toString();
|
||||
@ -34,6 +49,14 @@ function ensureString(o) {
|
||||
return ""+o;
|
||||
}
|
||||
|
||||
/**
|
||||
* Converts the provided argument to a Buffer, using type-dependent
|
||||
* methods.
|
||||
*
|
||||
* @param {any} o - the property to convert to a Buffer
|
||||
* @return {String} the Buffer version
|
||||
* @memberof @node-red/util.util
|
||||
*/
|
||||
function ensureBuffer(o) {
|
||||
if (Buffer.isBuffer(o)) {
|
||||
return o;
|
||||
@ -45,6 +68,14 @@ function ensureBuffer(o) {
|
||||
return new Buffer(o);
|
||||
}
|
||||
|
||||
/**
|
||||
* Safely clones a message object. This handles msg.req/msg.res objects that must
|
||||
* not be cloned.
|
||||
*
|
||||
* @param {any} msg - the message object to clone
|
||||
* @return {Object} the cloned message
|
||||
* @memberof @node-red/util.util
|
||||
*/
|
||||
function cloneMessage(msg) {
|
||||
// Temporary fix for #97
|
||||
// TODO: remove this http-node-specific fix somehow
|
||||
@ -64,6 +95,14 @@ function cloneMessage(msg) {
|
||||
return m;
|
||||
}
|
||||
|
||||
/**
|
||||
* Compares two objects, handling various JavaScript types.
|
||||
*
|
||||
* @param {any} obj1
|
||||
* @param {any} obj2
|
||||
* @return {boolean} whether the two objects are the same
|
||||
* @memberof @node-red/util.util
|
||||
*/
|
||||
function compareObjects(obj1,obj2) {
|
||||
var i;
|
||||
if (obj1 === obj2) {
|
||||
@ -130,6 +169,17 @@ function compareObjects(obj1,obj2) {
|
||||
return true;
|
||||
}
|
||||
|
||||
/**
|
||||
* Parses a property expression, such as `msg.foo.bar[3]` to validate it
|
||||
* and convert it to a canonical version expressed as an Array of property
|
||||
* names.
|
||||
*
|
||||
* For example, `a["b"].c` returns `['a','b','c']`
|
||||
*
|
||||
* @param {String} str - the property expression
|
||||
* @return {Array} the normalised expression
|
||||
* @memberof @node-red/util.util
|
||||
*/
|
||||
function normalisePropertyExpression(str) {
|
||||
// This must be kept in sync with validatePropertyExpression
|
||||
// in editor/js/ui/utils.js
|
||||
@ -234,12 +284,32 @@ function normalisePropertyExpression(str) {
|
||||
return parts;
|
||||
}
|
||||
|
||||
/**
|
||||
* Gets a property of a message object.
|
||||
*
|
||||
* Unlike {@link @node-red/util.util.getObjectProperty}, this function will strip `msg.` from the
|
||||
* front of the property expression if present.
|
||||
*
|
||||
* @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 @node-red/util.util
|
||||
*/
|
||||
function getMessageProperty(msg,expr) {
|
||||
if (expr.indexOf('msg.')===0) {
|
||||
expr = expr.substring(4);
|
||||
}
|
||||
return getObjectProperty(msg,expr);
|
||||
}
|
||||
|
||||
/**
|
||||
* Gets a property of an object.
|
||||
*
|
||||
* @param {Object} msg - the object
|
||||
* @param {String} str - the property expression
|
||||
* @return {any} the object property, or undefined if it does not exist
|
||||
* @memberof @node-red/util.util
|
||||
*/
|
||||
function getObjectProperty(msg,expr) {
|
||||
var result = null;
|
||||
var msgPropParts = normalisePropertyExpression(expr);
|
||||
@ -251,12 +321,34 @@ function getObjectProperty(msg,expr) {
|
||||
return result;
|
||||
}
|
||||
|
||||
/**
|
||||
* Sets a property of a message object.
|
||||
*
|
||||
* Unlike {@link @node-red/util.util.setObjectProperty}, this function will strip `msg.` from the
|
||||
* front of the property expression if present.
|
||||
*
|
||||
* @param {Object} msg - the message object
|
||||
* @param {String} prop - the property expression
|
||||
* @param {any} value - the value to set
|
||||
* @param {boolean} createMissing - whether to create missing parent properties
|
||||
* @memberof @node-red/util.util
|
||||
*/
|
||||
function setMessageProperty(msg,prop,value,createMissing) {
|
||||
if (prop.indexOf('msg.')===0) {
|
||||
prop = prop.substring(4);
|
||||
}
|
||||
return setObjectProperty(msg,prop,value,createMissing);
|
||||
}
|
||||
|
||||
/**
|
||||
* Sets a property of an object.
|
||||
*
|
||||
* @param {Object} msg - the object
|
||||
* @param {String} prop - the property expression
|
||||
* @param {any} value - the value to set
|
||||
* @param {boolean} createMissing - whether to create missing parent properties
|
||||
* @memberof @node-red/util.util
|
||||
*/
|
||||
function setObjectProperty(msg,prop,value,createMissing) {
|
||||
if (typeof createMissing === 'undefined') {
|
||||
createMissing = (typeof value !== 'undefined');
|
||||
@ -311,6 +403,16 @@ function setObjectProperty(msg,prop,value,createMissing) {
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Checks if a String contains any Environment Variable specifiers and returns
|
||||
* it with their values substituted in place.
|
||||
*
|
||||
* For example, if the env var `WHO` is set to `Joe`, the string `Hello ${WHO}!`
|
||||
* will return `Hello Joe!`.
|
||||
* @param {String} value - the string to parse
|
||||
* @return {String} The parsed string
|
||||
* @memberof @node-red/util.util
|
||||
*/
|
||||
function evaluateEnvProperty(value) {
|
||||
if (/^\${[^}]+}$/.test(value)) {
|
||||
// ${ENV_VAR}
|
||||
@ -328,7 +430,18 @@ function evaluateEnvProperty(value) {
|
||||
return value;
|
||||
}
|
||||
|
||||
var parseContextStore = function(key) {
|
||||
|
||||
/**
|
||||
* Parses a context property string, as generated by the TypedInput, to extract
|
||||
* the store name if present.
|
||||
*
|
||||
* For example, `#:(file)::foo` results in ` { store: "file", key: "foo" }`.
|
||||
*
|
||||
* @param {String} value - the context property string to parse
|
||||
* @return {Object} The parsed property
|
||||
* @memberof @node-red/util.util
|
||||
*/
|
||||
function parseContextStore(key) {
|
||||
var parts = {};
|
||||
var m = /^#:\((\S+?)\)::(.*)$/.exec(key);
|
||||
if (m) {
|
||||
@ -340,6 +453,18 @@ var parseContextStore = function(key) {
|
||||
return parts;
|
||||
}
|
||||
|
||||
|
||||
/**
|
||||
* Evaluates a property value according to its type.
|
||||
*
|
||||
* @param {String} value - the raw value
|
||||
* @param {String} type - the type of the value
|
||||
* @param {Node} node - the node evaluating the property
|
||||
* @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 @node-red/util.util
|
||||
*/
|
||||
function evaluateNodeProperty(value, type, node, msg, callback) {
|
||||
var result = value;
|
||||
if (type === 'str') {
|
||||
@ -387,6 +512,16 @@ function evaluateNodeProperty(value, type, node, msg, callback) {
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
/**
|
||||
* Prepares a JSONata expression for evaluation.
|
||||
* This attaches Node-RED specific functions to the expression.
|
||||
*
|
||||
* @param {String} value - the JSONata expression
|
||||
* @param {Node} node - the node evaluating the property
|
||||
* @return {Object} The JSONata expression that can be evaluated
|
||||
* @memberof @node-red/util.util
|
||||
*/
|
||||
function prepareJSONataExpression(value,node) {
|
||||
var expr = jsonata(value);
|
||||
expr.assign('flowContext',function(val) {
|
||||
@ -404,6 +539,17 @@ function prepareJSONataExpression(value,node) {
|
||||
return expr;
|
||||
}
|
||||
|
||||
/**
|
||||
* Evaluates a JSONata expression.
|
||||
* The expression must have been prepared with {@link @node-red/util.util.prepareJSONataExpression}
|
||||
* before passing to this function.
|
||||
*
|
||||
* @param {Object} expr - the prepared JSONata expression
|
||||
* @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 @node-red/util.util
|
||||
*/
|
||||
function evaluateJSONataExpression(expr,msg,callback) {
|
||||
var context = msg;
|
||||
if (expr._legacyMode) {
|
||||
@ -440,7 +586,15 @@ function evaluateJSONataExpression(expr,msg,callback) {
|
||||
return expr.evaluate(context, bindings, callback);
|
||||
}
|
||||
|
||||
|
||||
/**
|
||||
* Normalise a node type name to camel case.
|
||||
*
|
||||
* For example: `a-random node type` will normalise to `aRandomNodeType`
|
||||
*
|
||||
* @param {String} name - the node type
|
||||
* @return {String} The normalised name
|
||||
* @memberof @node-red/util.util
|
||||
*/
|
||||
function normaliseNodeTypeName(name) {
|
||||
var result = name.replace(/[^a-zA-Z0-9]/g, " ");
|
||||
result = result.trim();
|
||||
@ -454,6 +608,17 @@ function normaliseNodeTypeName(name) {
|
||||
return result;
|
||||
}
|
||||
|
||||
/**
|
||||
* Encode an object to JSON without losing information about non-JSON types
|
||||
* such as Buffer and Function.
|
||||
*
|
||||
* *This function is closely tied to its reverse within the editor*
|
||||
*
|
||||
* @param {Object} msg
|
||||
* @param {Object} opts
|
||||
* @return {Object} the encoded object
|
||||
* @memberof @node-red/util.util
|
||||
*/
|
||||
function encodeObject(msg,opts) {
|
||||
var debuglength = 1000;
|
||||
if (opts && opts.hasOwnProperty('maxLength')) {
|
||||
@ -581,6 +746,11 @@ function encodeObject(msg,opts) {
|
||||
return msg;
|
||||
}
|
||||
|
||||
/**
|
||||
* General utilities
|
||||
* @namespace util
|
||||
* @memberof @node-red/util
|
||||
*/
|
||||
module.exports = {
|
||||
encodeObject: encodeObject,
|
||||
ensureString: ensureString,
|
||||
|
Loading…
Reference in New Issue
Block a user