@vbarbarosh/node-helpers 3.70.1 → 3.72.0

package/README.md

@@ -20,7 +20,7 @@ npm install @vbarbarosh/node-helpers
 A subset of `@vbarbarosh/node-helpers` is available for browser:
 
 ```html
-<script src="https://unpkg.com/@vbarbarosh/node-helpers@3.70.1/dist/browser.js"></script>
+<script src="https://unpkg.com/@vbarbarosh/node-helpers@3.72.0/dist/browser.js"></script>
 ```
 
 ⚠️ All browser functions are exposed globally.

package/dist/browser.js

@@ -84,6 +84,7 @@ var map = {
 	"./array_group.js": "./src/array_group.js",
 	"./array_group_map.js": "./src/array_group_map.js",
 	"./array_index.js": "./src/array_index.js",
+	"./array_lcm.js": "./src/array_lcm.js",
 	"./array_max.js": "./src/array_max.js",
 	"./array_min.js": "./src/array_min.js",
 	"./array_permutations.js": "./src/array_permutations.js",
@@ -93,6 +94,8 @@ var map = {
 	"./array_sum.js": "./src/array_sum.js",
 	"./array_unique.js": "./src/array_unique.js",
 	"./array_unique_last.js": "./src/array_unique_last.js",
+	"./cli-apps/watchdog.d/ignore_sigterm.js": "./src/cli-apps/watchdog.d/ignore_sigterm.js",
+	"./cli-apps/watchdog.d/my-ignore-sigterm.js": "./src/cli-apps/watchdog.d/my-ignore-sigterm.js",
 	"./date_add_hours.js": "./src/date_add_hours.js",
 	"./date_add_milliseconds.js": "./src/date_add_milliseconds.js",
 	"./date_add_minutes.js": "./src/date_add_minutes.js",
@@ -143,6 +146,8 @@ var map = {
 	"./http_put_utf8.js": "./src/http_put_utf8.js",
 	"./identity.js": "./src/identity.js",
 	"./ignore.js": "./src/ignore.js",
+	"./pid_kill_grace.d/ignore-sigterm-for-10ms.js": "./src/pid_kill_grace.d/ignore-sigterm-for-10ms.js",
+	"./pid_kill_grace.d/ignore-sigterm.js": "./src/pid_kill_grace.d/ignore-sigterm.js",
 	"./plural.js": "./src/plural.js",
 	"./random_int.js": "./src/random_int.js",
 	"./urlmod.js": "./src/urlmod.js",
@@ -206,21 +211,14 @@ module.exports = array_chunk;
 /*!**************************!*\
   !*** ./src/array_gcd.js ***!
   \**************************/
-/***/ ((module) => {
+/***/ ((module, __unused_webpack_exports, __webpack_require__) => {
 
-// https://stackoverflow.com/a/39764792/1478566
-function array_gcd(array, fn = Number)
-{
-    return array.reduce((a,b) => gcd(fn(a), fn(b)));
-}
+const math_gcd = __webpack_require__(/*! ./math_gcd */ "./src/math_gcd.js");
 
 // https://stackoverflow.com/a/39764792/1478566
-function gcd(a, b)
+function array_gcd(array, fn = Number)
 {
-    if (b) {
-        return gcd(b, a % b);
-    }
-    return a;
+    return array.reduce((a,b) => math_gcd(fn(a), fn(b)));
 }
 
 module.exports = array_gcd;
@@ -311,6 +309,24 @@ function array_index(array, fn = identity)
 module.exports = array_index;
 
 
+/***/ }),
+
+/***/ "./src/array_lcm.js":
+/*!**************************!*\
+  !*** ./src/array_lcm.js ***!
+  \**************************/
+/***/ ((module, __unused_webpack_exports, __webpack_require__) => {
+
+const math_lcm = __webpack_require__(/*! ./math_lcm */ "./src/math_lcm.js");
+
+function array_lcm(array, fn = Number)
+{
+    return array.reduce((a,b) => math_lcm(fn(a), fn(b)));
+}
+
+module.exports = array_lcm;
+
+
 /***/ }),
 
 /***/ "./src/array_max.js":
@@ -632,6 +648,116 @@ function array_unique_last(array, fn = identity)
 module.exports = array_unique_last;
 
 
+/***/ }),
+
+/***/ "./src/cli-apps/watchdog.d/ignore_sigterm.js":
+/*!***************************************************!*\
+  !*** ./src/cli-apps/watchdog.d/ignore_sigterm.js ***!
+  \***************************************************/
+/***/ (() => {
+
+//#!/usr/bin/env node
+
+// 1️⃣ Client that ignores SIGTERM
+// Goal: process stays alive after SIGTERM and only dies on SIGKILL (exactly what pid_kill_grace should handle).
+//
+// What this tests for watchdog:
+//   - watchdog sends SIGTERM → process prints “ignored” and keeps running.
+//   - pid_kill_grace waits grace_timeout_ms, sees PID still alive, sends SIGKILL.
+//   - Process must die after SIGKILL.
+//   - Watchdog should log the whole sequence correctly.
+// This is a realistic scenario.
+
+console.log('PID:', process.pid);
+
+// Ignore SIGTERM
+process.on('SIGTERM', function () {
+    console.log('SIGTERM received, but intentionally ignored');
+});
+
+// Still react to SIGINT (Ctrl+C) so you can stop it manually if needed
+process.on('SIGINT', function () {
+    console.log('SIGINT received, exiting');
+    process.exit(130);
+});
+
+// Keep process alive
+setInterval(() => {
+    // simulate work
+}, 1000);
+
+
+/***/ }),
+
+/***/ "./src/cli-apps/watchdog.d/my-ignore-sigterm.js":
+/*!******************************************************!*\
+  !*** ./src/cli-apps/watchdog.d/my-ignore-sigterm.js ***!
+  \******************************************************/
+/***/ ((__unused_webpack_module, __unused_webpack_exports, __webpack_require__) => {
+
+//#!/usr/bin/env node
+
+const Promise = __webpack_require__(/*! bluebird */ "bluebird");
+const cli = __webpack_require__(/*! @vbarbarosh/node-helpers/src/cli */ "./src/cli.js");
+const now_human = __webpack_require__(/*! @vbarbarosh/node-helpers/src/now_human */ "./src/now_human.js");
+
+cli(main);
+
+async function main()
+{
+    process.on('SIGTERM', function () {
+        console.log(`[${now_human()}][ignore-sigterm] SIGTERM, ignoring...`);
+    });
+    process.on('SIGINT', function () {
+        console.log(`[${now_human()}][ignore-sigterm] SIGINT, ignoring...`);
+    });
+
+    for (let iter = 1, last = 100; iter <= last; ++iter) {
+        console.log(`[${now_human()}][ignore-sigterm] ${iter} of ${last}`);
+        await Promise.delay(100);
+    }
+}
+
+
+/***/ }),
+
+/***/ "./src/cli.js":
+/*!********************!*\
+  !*** ./src/cli.js ***!
+  \********************/
+/***/ ((module, __unused_webpack_exports, __webpack_require__) => {
+
+const ExitCodeError = __webpack_require__(/*! ./errors/ExitCodeError */ "./src/errors/ExitCodeError.js");
+const Promise = __webpack_require__(/*! bluebird */ "bluebird");
+
+/**
+ * Entry point for Node CLI apps
+ */
+function cli(main, report = error => console.error(error))
+{
+    // https://stackoverflow.com/a/46916601/1478566
+    const timer = setInterval(v => v, 1E9);
+
+    Promise.resolve(main()).then(resolve, reject);
+
+    function resolve() {
+        clearInterval(timer);
+    }
+    function reject(error) {
+        clearInterval(timer);
+        report(error);
+        if (error instanceof ExitCodeError) {
+            process.exit(error.exit_code);
+        }
+        else {
+            process.exit(1);
+        }
+    }
+}
+
+module.exports = cli;
+
+
 /***/ }),
 
 /***/ "./src/date_add_hours.js":
@@ -775,6 +901,25 @@ function date_is_leap_year(d)
 module.exports = date_is_leap_year;
 
 
+/***/ }),
+
+/***/ "./src/errors/ExitCodeError.js":
+/*!*************************************!*\
+  !*** ./src/errors/ExitCodeError.js ***!
+  \*************************************/
+/***/ ((module) => {
+
+class ExitCodeError extends Error
+{
+    constructor(exit_code, message = '') {
+        super(message);
+        this.exit_code = exit_code;
+    }
+}
+
+module.exports = ExitCodeError;
+
+
 /***/ }),
 
 /***/ "./src/factorize_ms.js":
@@ -2036,6 +2181,137 @@ const json_stringify_safe = __webpack_require__(/*! json-stringify-safe */ "./no
 module.exports = json_stringify_safe;
 
 
+/***/ }),
+
+/***/ "./src/math_gcd.js":
+/*!*************************!*\
+  !*** ./src/math_gcd.js ***!
+  \*************************/
+/***/ ((module) => {
+
+// https://stackoverflow.com/a/39764792/1478566
+function math_gcd(a, b)
+{
+    if (b) {
+        return math_gcd(b, a % b);
+    }
+    return a;
+}
+
+module.exports = math_gcd;
+
+
+/***/ }),
+
+/***/ "./src/math_lcm.js":
+/*!*************************!*\
+  !*** ./src/math_lcm.js ***!
+  \*************************/
+/***/ ((module, __unused_webpack_exports, __webpack_require__) => {
+
+const math_gcd = __webpack_require__(/*! ./math_gcd */ "./src/math_gcd.js");
+
+function math_lcm(a, b)
+{
+    return Math.abs(a*b) / math_gcd(a, b);
+}
+
+module.exports = math_lcm;
+
+
+/***/ }),
+
+/***/ "./src/now_human.js":
+/*!**************************!*\
+  !*** ./src/now_human.js ***!
+  \**************************/
+/***/ ((module, __unused_webpack_exports, __webpack_require__) => {
+
+const format_date_human = __webpack_require__(/*! ./format_date_human */ "./src/format_date_human.js");
+
+function now_human()
+{
+    return format_date_human(new Date());
+}
+
+module.exports = now_human;
+
+
+/***/ }),
+
+/***/ "./src/pid_kill_grace.d/ignore-sigterm-for-10ms.js":
+/*!*********************************************************!*\
+  !*** ./src/pid_kill_grace.d/ignore-sigterm-for-10ms.js ***!
+  \*********************************************************/
+/***/ ((__unused_webpack_module, __unused_webpack_exports, __webpack_require__) => {
+
+//#!/usr/bin/env node
+
+const Promise = __webpack_require__(/*! bluebird */ "bluebird");
+const cli = __webpack_require__(/*! ../cli */ "./src/cli.js");
+const now_human = __webpack_require__(/*! ../now_human */ "./src/now_human.js");
+
+// Child ignores SIGTERM for 10 ms, but dies naturally before the grace loop ends
+
+cli(main);
+
+async function main()
+{
+    let timer;
+
+    process.on('SIGTERM', function () {
+        console.log(`[${now_human()}][ignore-sigterm-for-10ms] SIGTERM_ignoring...`);
+        timer ??= setTimeout(terminate, 10);
+    });
+    process.on('SIGINT', function () {
+        console.log(`[${now_human()}][ignore-sigterm-for-10ms] SIGINT_ignoring...`);
+    });
+
+    for (let iter = 1, last = 100; iter <= last; ++iter) {
+        console.log(`[${now_human()}][ignore-sigterm-for-10ms] ${iter} of ${last}`);
+        await Promise.delay(10);
+    }
+}
+
+function terminate()
+{
+    console.log(`[${now_human()}][ignore-sigterm-for-10ms] TERMINATE_AFTER_10MS`);
+    process.exit(0);
+}
+
+
+/***/ }),
+
+/***/ "./src/pid_kill_grace.d/ignore-sigterm.js":
+/*!************************************************!*\
+  !*** ./src/pid_kill_grace.d/ignore-sigterm.js ***!
+  \************************************************/
+/***/ ((__unused_webpack_module, __unused_webpack_exports, __webpack_require__) => {
+
+//#!/usr/bin/env node
+
+const Promise = __webpack_require__(/*! bluebird */ "bluebird");
+const cli = __webpack_require__(/*! ../cli */ "./src/cli.js");
+const now_human = __webpack_require__(/*! ../now_human */ "./src/now_human.js");
+
+cli(main);
+
+async function main()
+{
+    process.on('SIGTERM', function () {
+        console.log(`[${now_human()}][ignore-sigterm] SIGTERM_ignoring...`);
+    });
+    process.on('SIGINT', function () {
+        console.log(`[${now_human()}][ignore-sigterm] SIGINT_ignoring...`);
+    });
+
+    for (let iter = 1, last = 100; iter <= last; ++iter) {
+        console.log(`[${now_human()}][ignore-sigterm] ${iter} of ${last}`);
+        await Promise.delay(10);
+    }
+}
+
+
 /***/ }),
 
 /***/ "./src/plural.js":
@@ -2223,10 +2499,10 @@ var __webpack_exports__ = {};
   \******************************/
 const ns = new URL(document.currentScript.src).searchParams.get('var') ?? 'h';
 if (typeof window[ns] !== 'undefined') {
-    console.log(`❌ @vbarbarosh/node-helpers@${"3.70.1"} was not injected — window.${ns} is already in use`);
+    console.log(`❌ @vbarbarosh/node-helpers@${"3.72.0"} was not injected — window.${ns} is already in use`);
 }
 else {
-    console.log(`🎉 @vbarbarosh/node-helpers@${"3.70.1"} successfully exposed as window.${ns}`);
+    console.log(`🎉 @vbarbarosh/node-helpers@${"3.72.0"} successfully exposed as window.${ns}`);
     window[ns] = {};
     // https://github.com/webpack/webpack/issues/625
     // https://webpack.js.org/guides/dependency-management/#require-context

package/package.json

@@ -2,11 +2,14 @@
     "author": "Vladimir Barbarosh <vladimir.barbarosh@gmail.com>",
     "license": "MIT",
     "name": "@vbarbarosh/node-helpers",
-    "version": "3.70.1",
+    "version": "3.72.0",
     "description": "A set of helpers for JavaScript/Node.js",
     "unpkg": "dist/browser.js",
     "jsdelivr": "dist/browser.js",
     "homepage": "https://vbarbarosh.github.io/node-helpers/",
+    "bin": {
+        "watchdog": "src/cli-apps/watchdog.js"
+    },
     "files": [
         "dist",
         "src"
@@ -28,6 +31,7 @@
         "url": "https://github.com/vbarbarosh/node-helpers/issues"
     },
     "peerDependencies": {
+        "@paralleldrive/cuid2": "^3.0.4",
         "@vbarbarosh/type-helpers": "^0.2.0",
         "axios": "^1.7.9",
         "bluebird": "^3.7.2",
@@ -38,7 +42,9 @@
         "json-stringify-safe": "^5.0.1",
         "mime-types": "^2.1.35",
         "sanitize-filename": "^1.6.3",
-        "split": "^1.0.1",
+        "split": "^1.0.1"
+    },
+    "optionalDependencies": {
         "ssh2": "^1.16.0"
     },
     "devDependencies": {

package/src/HeartbeatServer.js

@@ -1,4 +1,5 @@
 const EventEmitter = require('events');
+const ExitCodeError = require('./errors/ExitCodeError');
 const Promise = require('bluebird');
 const fs = require('fs');
 const fs_path_join = require('./fs_path_join');
@@ -7,6 +8,7 @@ const net = require('net');
 const now_fs = require('./now_fs');
 const os = require('os');
 
+// 💎 Only the lack of a valid PING within WATCHDOG_INTERVAL is fatal
 class HeartbeatServer extends EventEmitter
 {
     #socket_path;
@@ -37,36 +39,52 @@ class HeartbeatServer extends EventEmitter
             this.#reject = reject;
         });
 
-        this.#server = net.createServer(function (socket) {
-            socket.setEncoding('utf8');
-            socket.on('error', function (error) {
-                _this.#reject(new Error(`Client Socket Failed: ${error.message}`));
+        this.#server = net.createServer(function (client) {
+            let bytes_received = 0;
+            client.setEncoding('utf8');
+            client.on('error', function (error) {
+                if (!_this.#server) {
+                    return;
+                }
+                _this.emit('warning', error);
             });
-            socket.on('end', function () {
+            client.on('end', function () {
+                if (!_this.#server) {
+                    return;
+                }
                 _this.#last_ping = Date.now();
                 _this.emit('heartbeat');
             });
-            socket.on('data', function () {
+            client.on('data', function (buf) {
+                if (!_this.#server) {
+                    return;
+                }
                 // Not really interested in any data
+                bytes_received += buf.length;
+                if (bytes_received > 1024*1024) {
+                    _this.emit('warning', new Error(`Client floods. Bytes recieved: ${bytes_received}`));
+                    client.destroy();
+                }
             });
-            socket.end('OK');
+            client.end('OK');
         });
         this.#server.on('error', function (error) {
             _this.#reject(new Error(`Server Failed: ${error.message}`));
         });
         this.#server.on('close', function () {
-            _this.#reject(new Error(`Server Closed`));
+            _this.#reject(new Error('Server Closed'));
         });
         this.#server.listen(this.#socket_path, function () {
             // started = true;
         });
     }
 
-    #tick() {
+    async #tick() {
         if (this.#last_ping + this.#interval_ms < Date.now()) {
             clearInterval(this.#timer);
             this.#timer = null;
-            this.#reject(new Error(`No heartbeat for the last ${this.#interval_ms}ms`));
+            this.#reject(new ExitCodeError(124, `No heartbeat for the last ${this.#interval_ms}ms`));
+            await this.dispose();
         }
     }
 
@@ -78,20 +96,30 @@ class HeartbeatServer extends EventEmitter
         return this.#promise;
     }
 
+    // - Stops the watchdog
+    // - Closes socket
+    // - Removes socket file
+    // - Rejects the internal promise with a "Server Closed" error
+    // - Safe to call multiple times (idempotent)
     async dispose() {
         if (this.#timer) {
             clearInterval(this.#timer);
             this.#timer = null;
         }
+        if (!this.#server) {
+            return;
+        }
         try {
             const _this = this;
             await new Promise(function (resolve, reject) {
                 _this.#server.removeAllListeners();
                 _this.#server.close(error => error ? reject(error) : resolve());
+                _this.#server = null;
             });
         }
         finally {
             await fs_rmf(this.#socket_path);
+            this.#socket_path = null;
         }
     }
 }

package/src/HeartbeatServer.test.js

@@ -0,0 +1,31 @@
+const HeartbeatServer = require('./HeartbeatServer');
+const assert = require('assert');
+const fs_assert_file_socket = require('./fs_assert_file_socket');
+const ping_socket = require('./ping_socket');
+
+// 💎 Only the lack of a valid PING within WATCHDOG_INTERVAL is fatal
+
+// 📕 Notes by ChatGPT
+// If listen() fails (EADDRINUSE, perms, etc.), constructor will throw,
+// and heartbeat_server will be undefined in finally { await heartbeat_server.dispose() }.
+
+describe('HeartbeatServer', function () {
+    it('Happy Path', async function () {
+        const server = new HeartbeatServer();
+        try {
+            let counter = 0;
+            server.on('heartbeat', () => counter++);
+            await fs_assert_file_socket(server.socket_path);
+            await ping_socket(server.socket_path);
+            await ping_socket(server.socket_path);
+            assert.strictEqual(counter, 2);
+        }
+        finally {
+            await server.dispose();
+        }
+    });
+
+    // should emit a "warning" event on any client errors
+    // should not send any heartbeat signals after rejection (decision to kill a child process)
+    // should reject when no heartbeat received in an expected interval
+});

package/src/array_gcd.js

@@ -1,16 +1,9 @@
-// https://stackoverflow.com/a/39764792/1478566
-function array_gcd(array, fn = Number)
-{
-    return array.reduce((a,b) => gcd(fn(a), fn(b)));
-}
+const math_gcd = require('./math_gcd');
 
 // https://stackoverflow.com/a/39764792/1478566
-function gcd(a, b)
+function array_gcd(array, fn = Number)
 {
-    if (b) {
-        return gcd(b, a % b);
-    }
-    return a;
+    return array.reduce((a,b) => math_gcd(fn(a), fn(b)));
 }
 
 module.exports = array_gcd;

package/src/array_gcd.md

@@ -0,0 +1,2 @@
+Returns the greatest common divisor (GCD) of all elements in the array.
+`fn(item)` is applied to each element before computing.

package/src/array_lcm.js

@@ -0,0 +1,8 @@
+const math_lcm = require('./math_lcm');
+
+function array_lcm(array, fn = Number)
+{
+    return array.reduce((a,b) => math_lcm(fn(a), fn(b)));
+}
+
+module.exports = array_lcm;

package/src/array_lcm.md

@@ -0,0 +1,2 @@
+Returns the least common multiple (LCM) of all elements in the array.
+`fn(item)` is applied to each element before computing.

package/src/array_lcm.test.js

@@ -0,0 +1,12 @@
+const array_lcm = require('./array_lcm');
+const assert = require('assert');
+
+describe('array_lcm', function () {
+    it('should handle basic input', function () {
+        assert.deepStrictEqual(array_lcm([1,2,3,4,5]), 60);
+        assert.deepStrictEqual(array_lcm([15,25]), 75);
+        assert.deepStrictEqual(array_lcm([4,6,8]), 24);
+        assert.deepStrictEqual(array_lcm([4,8,16]), 16);
+        assert.deepStrictEqual(array_lcm([300,100,200,300]), 600);
+    });
+});

package/src/array_max.md

@@ -1 +1,2 @@
-Returns the first element in the array with the maximal weight.
+Returns the first element of the array for which `fn(item)` is maximized.
+If multiple elements have the same maximal weight, the earliest one is returned.

package/src/array_min.md

@@ -1 +1,2 @@
-Returns the first element in the array with the minimal weight.
+Returns the first element of the array for which `fn(item)` is minimized.
+If multiple elements have the same minimal weight, the earliest one is returned.

package/src/cli-apps/watchdog.d/connect_close.js

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+
+// 9. Client that connects but sends absolutely NO DATA.
+// Watchdog must NOT treat this as a PING.
+
+const net = require('net');
+
+const SOCKET = process.env.WATCHDOG_SOCKET;
+if (!SOCKET) throw new Error('WATCHDOG_SOCKET missing');
+
+// Connect → immediately destroy the socket → NO write events
+const socket = net.connect(SOCKET, () => {
+    console.log('connected (no ping), closing immediately');
+    socket.destroy(); // IMPORTANT: destroy() does not flush anything
+});
+
+setInterval(() => {}, 1000);

package/src/cli-apps/watchdog.d/connect_close2.js

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+
+// 9. Client that connects but sends absolutely NO DATA.
+// Watchdog must NOT treat this as a PING.
+
+const net = require('net');
+
+const SOCKET = process.env.WATCHDOG_SOCKET;
+if (!SOCKET) throw new Error('WATCHDOG_SOCKET missing');
+
+setInterval(ping, 1000);
+
+function ping()
+{
+    // Connect → immediately destroy the socket → NO write events
+    const socket = net.connect(SOCKET, () => {
+        console.log('connected (no ping), closing immediately');
+        socket.destroy(); // IMPORTANT: destroy() does not flush anything
+    });
+}

package/src/cli-apps/watchdog.d/connect_close3.js

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+
+// ❌ 11. Client sends heartbeats sporadically (sometimes missing)
+// Simulates flaky client.
+
+const net = require('net');
+
+const SOCKET = process.env.WATCHDOG_SOCKET;
+if (!SOCKET) throw new Error('WATCHDOG_SOCKET missing');
+
+setInterval(ping, 1000);
+
+function ping()
+{
+    // Connect → immediately destroy the socket → NO write events
+    const socket = net.connect(SOCKET, () => {
+        if (Math.random() > 0.5) {
+            socket.end('PING');
+        }
+        else {
+            console.log('connected (no ping), closing immediately');
+            socket.destroy(); // IMPORTANT: destroy() does not flush anything
+        }
+    });
+}