@vbarbarosh/node-helpers 3.66.0 → 3.67.0

package/package.json

@@ -2,7 +2,7 @@
     "author": "Vladimir Barbarosh <vladimir.barbarosh@gmail.com>",
     "license": "MIT",
     "name": "@vbarbarosh/node-helpers",
-    "version": "3.66.0",
+    "version": "3.67.0",
     "description": "A set of helpers for JavaScript/Node.js",
     "unpkg": "dist/browser.js",
     "jsdelivr": "dist/browser.js",
@@ -28,7 +28,7 @@
         "url": "https://github.com/vbarbarosh/node-helpers/issues"
     },
     "peerDependencies": {
-        "@vbarbarosh/type-helpers": "^0.1.0",
+        "@vbarbarosh/type-helpers": "^0.2.0",
         "axios": "^1.7.9",
         "bluebird": "^3.7.2",
         "csv-parse": "^5.6.0",
@@ -42,6 +42,7 @@
         "ssh2": "^1.16.0"
     },
     "devDependencies": {
+        "@vbarbarosh/tree": "^0.5.0",
         "copy-webpack-plugin": "^12.0.2",
         "express": "^4.21.2",
         "mocha": "^11.0.1",
@@ -50,6 +51,7 @@
         "redis-v3": "npm:redis@3",
         "redis-v4": "npm:redis@4",
         "throttle": "^1.0.3",
+        "tree-kill": "^1.2.2",
         "webpack": "^5.98.0",
         "webpack-cli": "^6.0.1"
     }

package/src/HeartbeatServer.js

@@ -0,0 +1,99 @@
+const EventEmitter = require('events');
+const Promise = require('bluebird');
+const fs = require('fs');
+const fs_path_join = require('./fs_path_join');
+const fs_rmf = require('./fs_rmf');
+const net = require('net');
+const now_fs = require('./now_fs');
+const os = require('os');
+
+class HeartbeatServer extends EventEmitter
+{
+    #socket_path;
+    #last_ping = Date.now();
+    #interval_ms;
+    #promise;
+    #reject;
+    #timer;
+    #server;
+
+    constructor(interval_ms = 5000) {
+        super();
+        this.#interval_ms = interval_ms;
+        this.#init();
+    }
+
+    #init() {
+        const _this = this;
+
+        this.#timer = setInterval(() => this.#tick(), this.#interval_ms);
+
+        // Put socket on tmpfs to avoid slow disks.
+        this.#socket_path = fs.existsSync('/dev/shm')
+            ? fs_path_join('/dev/shm', `watchdog-${process.pid}-${now_fs()}.sock`)
+            : fs_path_join(os.tmpdir(), `watchdog-${process.pid}-${now_fs()}.sock`);
+
+        this.#promise = new Promise((resolve, reject) => {
+            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}`));
+            });
+            socket.on('end', function () {
+                _this.#last_ping = Date.now();
+                _this.emit('heartbeat');
+            });
+            socket.on('data', function () {
+                // Not really interested in any data
+            });
+            socket.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.#server.listen(this.#socket_path, function () {
+            // started = true;
+        });
+    }
+
+    #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`));
+        }
+    }
+
+    get socket_path() {
+        return this.#socket_path;
+    }
+
+    promise() {
+        return this.#promise;
+    }
+
+    async dispose() {
+        if (this.#timer) {
+            clearInterval(this.#timer);
+            this.#timer = null;
+        }
+        try {
+            const _this = this;
+            await new Promise(function (resolve, reject) {
+                _this.#server.removeAllListeners();
+                _this.#server.close(error => error ? reject(error) : resolve());
+            });
+        }
+        finally {
+            await fs_rmf(this.#socket_path);
+        }
+    }
+}
+
+module.exports = HeartbeatServer;

package/src/array_group.js

@@ -1,15 +1,19 @@
-const array_group_map = require('./array_group_map');
-
 /**
- * Group items by common key and return an array of groups.
+ * Group items by a common key and return an array of groups.
  *
- * @param array
- * @param fn
- * @returns {unknown[]}
+ * @alternative Map.groupBy(items, fn)
  */
 function array_group(array, fn)
 {
-    return Object.values(array_group_map(array, fn));
+    const map = new Map();
+    array.forEach(function (item) {
+        const key = fn(item);
+        if (!map.has(key)) {
+            map.set(key, {key, items: []});
+        }
+        map.get(key).items.push(item);
+    });
+    return map.values().toArray();
 }
 
 module.exports = array_group;

package/src/array_index.js

@@ -1,3 +1,5 @@
+const identity = require('./identity');
+
 /**
  * Usage:
  *     array_index(items, v => v.name)
@@ -5,7 +7,7 @@
  * Seems, there is a native way to do it:
  *     Object.fromEntries(items.map(v => [v.name, v]));
  */
-function array_index(array, fn)
+function array_index(array, fn = identity)
 {
     const out = {};
     array.forEach(v => out[fn(v)] = v);

package/src/array_max.js

@@ -1,26 +1,20 @@
+const identity = require('./identity');
+
 /**
- * Return first among maximum values.
- *
- * @param array
- * @param fn
+ * Returns the first element in the array with the maximal weight
  */
 function array_max(array, fn = identity)
 {
     let out = null;
-    let out_value = null;
-    array.forEach(function (item) {
-        const item_value = fn(item);
-        if (item_value > out_value || out_value === null) {
+    let max = null;
+    array.forEach(function (item, i) {
+        const weight = fn(item);
+        if (i === 0 || max < weight) {
+            max = weight;
             out = item;
-            out_value = item_value;
         }
     });
     return out;
 }
 
-function identity(value)
-{
-    return value;
-}
-
 module.exports = array_max;

package/src/array_max.test.js

@@ -9,4 +9,12 @@ describe('array_max', function () {
         assert.deepStrictEqual(array_max([1, 1, 2, 2, 3, 3, 1]), 3);
         assert.deepStrictEqual(array_max([{x:1},{x:2}], v => v.x), {x: 2});
     });
+    it('should handle strings', function () {
+        const items = [
+            {id: 1, time: '2025-08-08T05:03:13+00:00'},
+            {id: 2, time: '2025-08-07T05:03:13+00:00'},
+            {id: 3, time: '2025-08-06T05:03:13+00:00'},
+        ];
+        assert.deepStrictEqual(array_max(items, v => v.time), items[0]);
+    });
 });

package/src/array_min.js

@@ -1,26 +1,20 @@
+const identity = require('./identity');
+
 /**
- * Return first among minimum values.
- *
- * @param array
- * @param fn
+ * Returns the first element in the array with the minimal weight
  */
 function array_min(array, fn = identity)
 {
     let out = null;
-    let out_value = null;
-    array.forEach(function (item) {
-        const item_value = fn(item);
-        if (item_value < out_value || out_value === null) {
+    let min = null;
+    array.forEach(function (item, i) {
+        const weight = fn(item);
+        if (i === 0 || min > weight) {
+            min = weight;
             out = item;
-            out_value = item_value;
         }
     });
     return out;
 }
 
-function identity(value)
-{
-    return value;
-}
-
 module.exports = array_min;

package/src/array_min.test.js

@@ -9,4 +9,12 @@ describe('array_min', function () {
         assert.deepStrictEqual(array_min([1, 1, 2, 2, 3, 3, 1]), 1);
         assert.deepStrictEqual(array_min([{x:2},{x:1}], v => v.x), {x: 1});
     });
+    it('should handle strings', function () {
+        const items = [
+            {id: 1, time: '2025-08-08T05:03:13+00:00'},
+            {id: 2, time: '2025-08-07T05:03:13+00:00'},
+            {id: 3, time: '2025-08-06T05:03:13+00:00'},
+        ];
+        assert.deepStrictEqual(array_min(items, v => v.time), items[2]);
+    });
 });

package/src/array_sort.js

@@ -1,23 +1,32 @@
-const fcmp_strings = require('./fcmp_strings');
+const fcmp_default = require('./fcmp_default');
+const fcmp_tuples = require('./fcmp_tuples');
 
 /**
- * Sort items in an `array`.
+ * Sorts an array in place by the result of applying `fn` to each item,
+ * using `fcmp` to compare the results.
  *
- * @param array
- * @param fn
- * @param fcmp
- * @returns {*}
+ * array_sort(items, v => [v.name])
+ * array_sort(items, v => [v.age, v.name])
  */
-function array_sort(array, fn = identity, fcmp = fcmp_strings)
+function array_sort(array, mapper, fcmp = fcmp_default)
 {
+    const keys = new Map();
     return array.sort(function (a, b) {
-        return fcmp(fn(a), fn(b));
+        if (!keys.has(a)) {
+            keys.set(a, mapper(a));
+        }
+        if (!keys.has(b)) {
+            keys.set(b, mapper(b));
+        }
+        return fcmp_tuples(keys.get(a), keys.get(b), fcmp);
     });
 }
 
-function identity(v)
-{
-    return v;
-}
+// function array_sort(array, fn = identity, fcmp = fcmp_default)
+// {
+//     return array.sort(function (a, b) {
+//         return fcmp(fn(a), fn(b));
+//     });
+// }
 
 module.exports = array_sort;

package/src/array_sort.test.js

@@ -1,10 +1,85 @@
 const array_sort = require('./array_sort');
 const assert = require('assert');
+const fs_path_extname = require('./fs_path_extname');
 
 describe('array_sort', function () {
     it('should handle basic input', function () {
-        assert.deepStrictEqual(array_sort([5,4,3,2,1]), [1,2,3,4,5]);
-        assert.deepStrictEqual(array_sort([5,4,3,2,1], v => v), [1,2,3,4,5]);
-        assert.deepStrictEqual(array_sort([{id:5},{id:4},{id:3},{id:2},{id:1}], v => v.id), [{id:1},{id:2},{id:3},{id:4},{id:5}]);
+        assert.deepStrictEqual(array_sort([5,4,3,2,1], v => [v]), [1,2,3,4,5]);
+        assert.deepStrictEqual(array_sort([5,4,3,2,1], v => [v]), [1,2,3,4,5]);
+        assert.deepStrictEqual(array_sort([{id:5},{id:4},{id:3},{id:2},{id:1}], v => [v.id]), [{id:1},{id:2},{id:3},{id:4},{id:5}]);
+    });
+    it('should handle sort by priorities', function () {
+        assert.deepStrictEqual(array_sort([1,2,3,4,5], v => [[5].indexOf(v) >>> 0]), [5,1,2,3,4]);
+        assert.deepStrictEqual(array_sort([{id:1},{id:2},{id:3},{id:4},{id:5}], v => [[5].indexOf(v.id) >>> 0]), [{id:5},{id:1},{id:2},{id:3},{id:4}]);
+    });
+    it('should handle sort by priorities #2', function () {
+        const files = [
+            {name: 'README.md', size: 1024, type: 'file'},
+            {name: 'package.json', size: 860, type: 'file'},
+            {name: 'src', size: 0, type: 'dir'},
+            {name: 'src/index.js', size: 2048, type: 'file'},
+            {name: 'src/utils', size: 0, type: 'dir'},
+            {name: 'src/utils/helpers.js', size: 1536, type: 'file'},
+            {name: 'node_modules', size: 0, type: 'dir'},
+            {name: 'LICENSE', size: 1078, type: 'file'},
+        ];
+        const expected = [
+            {name: 'node_modules', size: 0, type: 'dir'},
+            {name: 'src', size: 0, type: 'dir'},
+            {name: 'src/utils', size: 0, type: 'dir'},
+            {name: 'LICENSE', size: 1078, type: 'file'},
+            {name: 'README.md', size: 1024, type: 'file'},
+            {name: 'package.json', size: 860, type: 'file'},
+            {name: 'src/index.js', size: 2048, type: 'file'},
+            {name: 'src/utils/helpers.js', size: 1536, type: 'file'},
+        ];
+        const actual = array_sort(files, v => [pri_start(v.type, ['dir']), v.name]);
+        assert.deepStrictEqual(actual, expected);
+    });
+    it('sort by name, directory first; .js, then .txt, then all the reset', function () {
+        const files = [
+            {name: 'docs', type: 'dir', size: 0},
+            {name: 'zeta.txt', type: 'file', size: 1200},
+            {name: 'alpha.js', type: 'file', size: 1500},
+            {name: 'src', type: 'dir', size: 0},
+            {name: 'readme.txt', type: 'file', size: 800},
+            {name: 'beta.js', type: 'file', size: 1600},
+            {name: 'build', type: 'dir', size: 0},
+            {name: 'build.foo.js', type: 'dir', size: 0},
+            {name: 'build.foo.md', type: 'dir', size: 0},
+            {name: 'build.foo.txt', type: 'dir', size: 0},
+            {name: 'notes.md', type: 'file', size: 400},
+            {name: 'zeta.js', type: 'file', size: 1000},
+            {name: 'config', type: 'dir', size: 0},
+        ];
+        const expected = [
+            {name: 'build.foo.js', type: 'dir', size: 0},
+            {name: 'build.foo.txt', type: 'dir', size: 0},
+            {name: 'build', type: 'dir', size: 0},
+            {name: 'build.foo.md', type: 'dir', size: 0},
+            {name: 'config', type: 'dir', size: 0},
+            {name: 'docs', type: 'dir', size: 0},
+            {name: 'src', type: 'dir', size: 0},
+            {name: 'alpha.js', type: 'file', size: 1500},
+            {name: 'beta.js', type: 'file', size: 1600},
+            {name: 'zeta.js', type: 'file', size: 1000},
+            {name: 'readme.txt', type: 'file', size: 800},
+            {name: 'zeta.txt', type: 'file', size: 1200},
+            {name: 'notes.md', type: 'file', size: 400},
+        ];
+        array_sort(files, v => [pri_start(v.type, ['dir']), pri_start(fs_path_extname(v.name), ['.js', '.txt']), v.name])
+        assert.deepStrictEqual(files, expected);
     });
 });
+
+// priorities.indexOf(v) >>> 0
+function pri_start(value, array)
+{
+    const i = array.indexOf(value);
+    return i === -1 ? array.length : i;
+}
+
+function pri_end(value, array)
+{
+    return array.indexOf(value);
+}

package/src/array_sort_other.js

@@ -1,4 +1,4 @@
-const fcmp_strings = require('./fcmp_strings');
+const fcmp_default = require('./fcmp_default');
 
 /**
  * Sort items in an `array` at the same order as in `other`. Values which
@@ -10,7 +10,7 @@ const fcmp_strings = require('./fcmp_strings');
  * @param fcmp
  * @returns {*}
  */
-function array_sort_other(array, fn, other, fcmp = fcmp_strings)
+function array_sort_other(array, fn, other, fcmp = fcmp_default)
 {
     const other_map = {};
     other.forEach((v,i) => other_map[v] = i + 1);

package/src/array_unique.js

@@ -1,11 +1,17 @@
-function array_unique(values)
+const identity = require('./identity');
+
+/**
+ * Return unique values; if a value occurs multiple times, keep the first one.
+ */
+function array_unique(values, fn = identity)
 {
     const set = new Set();
     return values.filter(function (item) {
-        if (set.has(item)) {
+        const key = fn(item);
+        if (set.has(key)) {
             return false;
         }
-        set.add(item);
+        set.add(key);
         return true;
     });
 }

package/src/array_unique_last.js

@@ -1,28 +1,21 @@
+const identity = require('./identity');
+
 /**
- * Return only unique values. If there are many values - prefer last one.
- *
- * @param array
- * @param fn
- * @returns {*[]}
+ * Return unique values; if a value occurs multiple times, keep the last one.
  */
 function array_unique_last(array, fn = identity)
 {
     const out = [];
-    const taken = {};
+    const set = new Set();
     for (let i = array.length; --i >= 0; ) {
         const item = array[i];
-        const pk = fn(item);
-        if (!taken[pk]) {
-            taken[pk] = true;
+        const key = fn(item);
+        if (!set.has(key)) {
+            set.add(key);
             out.push(item);
         }
     }
     return out.reverse();
 }
 
-function identity(value)
-{
-    return value;
-}
-
 module.exports = array_unique_last;

package/src/countdown.js

@@ -13,7 +13,7 @@ function countdown(ctx)
     let timer = null;
     return new Promise(function (resolve, reject) {
         ctx.value = ctx.fn ? Promise.method(ctx.fn).call() : Promise.resolve(ctx.value);
-        ctx.timeout = ctx.timeout || 0;
+        ctx.timeout = ctx.timeout || 0; // ⚠️ Rename to timeout_ms
         ctx.time_now = new Date();
         ctx.time_begin = new Date();
         ctx.time_end = Date.now() + ctx.timeout;

package/src/fcmp_default.js

@@ -0,0 +1,12 @@
+function fcmp_default(a, b)
+{
+    if (a < b) {
+        return -1;
+    }
+    if (a > b) {
+        return 1;
+    }
+    return 0;
+}
+
+module.exports = fcmp_default;

package/src/fcmp_default_desc.js

@@ -0,0 +1,12 @@
+function fcmp_default_desc(b, a)
+{
+    if (a < b) {
+        return -1;
+    }
+    if (a > b) {
+        return 1;
+    }
+    return 0;
+}
+
+module.exports = fcmp_default_desc;

package/src/fcmp_numbers.js

@@ -1,6 +1,6 @@
 function fcmp_numbers(a, b)
 {
-    return Number(a) - b;
+    return a - b;
 }
 
 module.exports = fcmp_numbers;

package/src/fcmp_tuples.js

@@ -0,0 +1,15 @@
+const fcmp_default = require('./fcmp_default');
+
+function fcmp_tuples(a, b, fcmp = fcmp_default)
+{
+    const end = Math.min(a.length, b.length);
+    for (let i = 0; i < end; ++i) {
+        const tmp = fcmp(a[i], b[i]);
+        if (tmp) {
+            return tmp;
+        }
+    }
+    return 0;
+}
+
+module.exports = fcmp_tuples;

package/src/fcmp_utf8_bin.js

@@ -0,0 +1,13 @@
+// Strict binary (codepoint) comparison, like MySQL's utf8_bin collation
+function fcmp_utf8_bin(a, b)
+{
+    if (a < b) {
+        return -1;
+    }
+    if (a > b) {
+        return 1;
+    }
+    return 0;
+}
+
+module.exports = fcmp_utf8_bin;

package/src/fcmp_utf8_ci.js

@@ -0,0 +1,7 @@
+// Locale-aware, case-insensitive, like utf8_ci or utf8mb4_ci
+function fcmp_utf8_ci(a, b)
+{
+    return a.localeCompare(b, undefined, {sensitivity: 'base'});
+}
+
+module.exports = fcmp_utf8_ci;

package/src/fcmp_utf8_cs.js

@@ -0,0 +1,7 @@
+// Locale-aware, case-sensitive, like utf8_cs or utf8mb4_cs (but using system locale)
+function fcmp_utf8_cs(a, b)
+{
+    return a.localeCompare(b, undefined, {sensitivity: 'variant'});
+}
+
+module.exports = fcmp_utf8_cs;

package/src/fcmp_utf8_natural_ci.js

@@ -0,0 +1,7 @@
+// Natural sort (numeric), case-insensitive
+function fcmp_utf8_natural_ci(a, b)
+{
+    return a.localeCompare(b, undefined, {numeric: true, sensitivity: 'base'});
+}
+
+module.exports = fcmp_utf8_natural_ci;

package/src/fcmp_utf8_natural_cs.js

@@ -0,0 +1,7 @@
+// Natural sort (numeric), case-sensitive
+function fcmp_utf8_natural_cs(a, b)
+{
+    return a.localeCompare(b, undefined, {numeric: true, sensitivity: 'variant'});
+}
+
+module.exports = fcmp_utf8_natural_cs;