[pull] master from DefinitelyTyped:master

types/node-red__util/.npmignore

@@ -3,3 +3,4 @@
 !**/*.d.cts
 !**/*.d.mts
 !**/*.d.*.ts
+/v3/

types/node-red__util/index.d.ts

@@ -1,3 +1,4 @@
+import { SpawnOptions } from "child_process";
 import { EventEmitter } from "events";
 import { Expression as JsonataExpression } from "jsonata";
 
@@ -9,6 +10,44 @@ declare const util: util.UtilModule;
 export = util;
 
 declare namespace util {
+    /**
+     * Runtime events
+     */
+    interface Events extends EventEmitter {} // eslint-disable-line @typescript-eslint/no-empty-interface
+
+    interface ExecRunOptions extends SpawnOptions {
+        shell?: boolean;
+    }
+
+    interface ExecRunResult {
+        code: number | null;
+        stdout: string;
+        stderr: string;
+    }
+
+    /**
+     * Run a system command with stdout/err being emitted as 'event-log' events
+     * on the @node-red/util/events handler.
+     *
+     * The main arguments to this function are the same as passed to `child_process.spawn`
+     *
+     * @param command - the command to run
+     * @param args - arguments for the command
+     * @param options - options to pass child_process.spawn
+     * @param emit - whether to emit events to the event-log for each line of stdout/err
+     * @return A promise that resolves (rc=0) or rejects (rc!=0) when the command completes. The value
+     *                   of the promise is an object of the form:
+     *
+     *       {
+     *           code: <exit code>,
+     *           stdout: <standard output from the command>,
+     *           stderr: <standard error from the command>
+     *       }
+     */
+    interface Exec {
+        run(command: string, args?: string[], options?: {}, emit?: boolean): Promise<ExecRunResult>;
+    }
+
     interface LogMessageObject {
         level: number;
         msg?: LogMessage | undefined;
@@ -98,6 +137,10 @@ declare namespace util {
 
     // eslint-disable-next-line @typescript-eslint/naming-convention
     interface I18n {
+        /**
+         * The default language of the runtime
+         */
+        readonly defaultLang: "en-US";
         /**
          * Perform a message catalog lookup.
          */
@@ -126,7 +169,7 @@ declare namespace util {
 
     interface Util {
         /**
-         * Generates a psuedo-unique-random id.
+         * Generates a pseudo-unique-random id.
          * @returns a random-ish id
          */
         generateId(): string;
@@ -157,8 +200,8 @@ declare namespace util {
         /**
          * Compares two objects, handling various JavaScript types.
          *
-         * @param obj1
-         * @param obj2
+         * @param obj1 - the first object
+         * @param obj2 - the second object
          * @returns whether the two objects are the same
          */
         compareObjects(obj1: object, obj2: object): boolean;
@@ -181,32 +224,47 @@ declare namespace util {
          * @param msg - the message object to use for cross-references
          * @param toString - whether to convert the returned array to a string
          * @returns the normalised expression
+         * @throws Will throw an error if the expression is incorrect
          */
         normalisePropertyExpression(str: string, msg?: registry.NodeMessage, toString?: false): Array<string | number>;
         normalisePropertyExpression(str: string, msg: registry.NodeMessage, toString: true): string;
         /**
          * Gets a property of a message object.
          *
-         * Unlike `getObjectProperty`, this function will strip `msg.` from the
+         * Unlike {@link getObjectProperty}, this function will strip `msg.` from the
          * front of the property expression if present.
          *
          * @param msg - the message object
          * @param expr - the property expression
          * @returns the message property, or undefined if it does not exist
+         * @throws Will throw an error if the *parent* of the property does not exist
          */
         getMessageProperty(msg: registry.NodeMessage, expr: string): any;
         /**
          * Gets a property of an object.
+         * Given the object:
+         *
+         *     {
+         *       "pet": {
+         *           "type": "cat"
+         *       }
+         *     }
+         *
+         * - `pet.type` will return `"cat"`.
+         * - `pet.name` will return `undefined`
+         * - `car` will return `undefined`
+         * - `car.type` will throw an Error (as `car` does not exist)
          *
          * @param msg - the object
          * @param expr - the property expression
          * @returns the object property, or undefined if it does not exist
+         * @throws Will throw an error if the *parent* of the property does not exist
          */
         getObjectProperty(msg: registry.NodeMessage, expr: string): any;
         /**
          * Sets a property of a message object.
          *
-         * Unlike `setObjectProperty`, this function will strip `msg.` from the
+         * Unlike {@link setObjectProperty}, this function will strip `msg.` from the
          * front of the property expression if present.
          *
          * @param  msg           - the message object
@@ -228,20 +286,10 @@ declare namespace util {
          * Get value of environment variable.
          * @param node - accessing node
          * @param name - name of variable
+         * @param flow - accessing flow
          * @returns value of env var
          */
-        getSetting(node: registry.Node, name: string): string;
-        /**
-         * 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 value - the string to parse
-         * @param node - the node evaluating the property
-         * @returns The parsed string
-         */
-        evaluateEnvProperty(value: string, node: registry.Node): string;
+        getSetting(node: registry.Node, name: string, flow?: runtime.Flow): string | undefined;
         /**
          * Parses a context property string, as generated by the TypedInput, to extract
          * the store name if present.
@@ -281,7 +329,7 @@ declare namespace util {
         prepareJSONataExpression(value: string, node: registry.Node): JsonataExpression;
         /**
          * Evaluates a JSONata expression.
-         * The expression must have been prepared with `prepareJSONataExpression`
+         * The expression must have been prepared with {@link prepareJSONataExpression}
          * before passing to this function.
          *
          * @param   expr     - the prepared JSONata expression
@@ -318,6 +366,7 @@ declare namespace util {
     // Used `boolean` in PromiseLike instead of `false` because it caused problems with `async` functions
     type HandlerFunction<T> = (payload: T, callback: (err?: any) => void) => void | false | PromiseLike<void | boolean>; // eslint-disable-line @typescript-eslint/no-invalid-void-type
 
+    /** @link https://nodered.org/docs/api/hooks/ */
     interface Hooks {
         /**
          * A node has called `node.send()` with one or more messages.
@@ -461,7 +510,17 @@ declare namespace util {
          * To remove all hooks with a given label, `*.my-hooks` can be used.
          */
         remove(hookName: string): void;
+
+        /**
+         * Check if the hook has been registered.
+         * @param hookName the name of the hook
+         */
         has(hookName: string): boolean;
+
+        /**
+         * Clears all registered hook handlers.
+         */
+        clear(): void;
     }
 
     // #region Hook Event Objects
@@ -534,6 +593,16 @@ declare namespace util {
          */
         init(settings: runtime.LocalSettings): void;
 
+        /**
+         * Runtime events
+         */
+        events: Events;
+
+        /**
+         * Run system commands with event-log integration
+         */
+        exec: Exec;
+
         /**
          * Logging utilities
          */

types/node-red__util/node-red__util-tests.ts

@@ -2,6 +2,32 @@ import utilModule = require("@node-red/util");
 import { Node, NodeMessage } from "@node-red/registry";
 import { EventEmitter } from "events";
 
+function eventsTests() {
+    const events = utilModule.events;
+
+    // $ExpectType Events
+    events.on("event-name", (_) => {});
+
+    // $ExpectType Events
+    events.once("event-name", (_) => {});
+
+    // $ExpectType Events
+    events.off("event-name", (_) => {});
+}
+
+function execTests() {
+    const exec = utilModule.exec;
+
+    // $ExpectType Promise<ExecRunResult>
+    exec.run("echo test");
+
+    // $ExpectType Promise<ExecRunResult>
+    exec.run("echo", ["test"]);
+
+    // $ExpectType Promise<ExecRunResult>
+    exec.run("echo", ["test"], { shell: false }, false);
+}
+
 function i18nTests() {
     const i18n = utilModule.i18n;
 
@@ -101,12 +127,9 @@ function utilTests(someNode: Node) {
     // $ExpectType boolean
     util.setObjectProperty({}, "key", { dataKey: "dataVal" }, true);
 
-    // $ExpectType string
+    // $ExpectType string | undefined
     util.getSetting(someNode, "name");
 
-    // $ExpectType string
-    util.evaluateEnvProperty("name", someNode);
-
     // $ExpectType any
     util.evaluateNodeProperty("value", "type", someNode, {});
     // $ExpectType void

types/node-red__util/package.json

@@ -1,15 +1,15 @@
 {
     "private": true,
     "name": "@types/node-red__util",
-    "version": "1.3.9999",
+    "version": "5.0.9999",
     "projects": [
         "https://github.com/node-red/node-red/tree/master/packages/node_modules/%40node-red/util",
         "https://nodered.org/"
     ],
     "dependencies": {
         "@types/node-red__registry": "*",
         "@types/node-red__runtime": "*",
-        "jsonata": "2.0.5"
+        "jsonata": "2.2.2"
     },
     "devDependencies": {
         "@types/node-red__util": "workspace:."
@@ -22,6 +22,10 @@
         {
             "name": "Tadeusz Wyrzykowski",
             "githubUsername": "Shaquu"
+        },
+        {
+            "name": "Gauthier Dandele",
+            "githubUsername": "GogoVega"
         }
     ]
 }

types/node-red__util/v3/.npmignore

@@ -0,0 +1,5 @@
+*
+!**/*.d.ts
+!**/*.d.cts
+!**/*.d.mts
+!**/*.d.*.ts