@vbarbarosh/node-helpers 3.66.1 → 3.68.0

package/package.json

@@ -2,7 +2,7 @@
     "author": "Vladimir Barbarosh <vladimir.barbarosh@gmail.com>",
     "license": "MIT",
     "name": "@vbarbarosh/node-helpers",
-    "version": "3.66.1",
+    "version": "3.68.0",
     "description": "A set of helpers for JavaScript/Node.js",
     "unpkg": "dist/browser.js",
     "jsdelivr": "dist/browser.js",
@@ -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/_finally.js

@@ -0,0 +1,8 @@
+function _finally(callback)
+{
+    return {
+        [Symbol.dispose]: callback,
+    };
+}
+
+module.exports = _finally;

package/src/_finally.md

@@ -0,0 +1,19 @@
+`_finally` lets you register cleanup code that always runs when the scope ends.
+
+```js
+this.foo = 12345;
+using _ = _finally(() => this.foo = null);
+// ...
+```
+
+This is essentially the same as:
+
+```js
+this.foo = 12345;
+try {
+    // ..
+}
+finally {
+    this.foo = null;
+}
+```

package/src/_perf.js

@@ -0,0 +1,18 @@
+function _perf(name, print = s => console.log(s))
+{
+    const time0 = performance.now();
+    return {
+        times: 1,
+        [Symbol.dispose]: function () {
+            const duration = performance.now() - time0;
+            if (this.times > 1) {
+                print(`[${name}] ${duration.toFixed(4)}ms x ${this.times}`);
+            }
+            else {
+                print(`[${name}] ${duration.toFixed(4)}ms`);
+            }
+        },
+    };
+}
+
+module.exports = _perf;

package/src/_perf.md

@@ -0,0 +1,13 @@
+Measures time from the current position till the end of a block scope.
+
+```js
+app.component('sidebar', {
+    template: `...`,
+    methods: {
+        click_download: async function () {
+            using _ = _perf('download');
+            // ...
+        },
+    },
+});
+```

package/src/_restore.js

@@ -0,0 +1,16 @@
+// 1) Capture original value
+// 2) Assign a temporary one
+// 3) Automatically restore on scope exit
+//
+// Basically: set variable, and automatically restore the original value at the end of scope.
+function _restore(value, callback)
+{
+    const [original] = callback(value);
+    return {
+        [Symbol.dispose]: function () {
+            callback(original);
+        },
+    };
+}
+
+module.exports = _restore;

package/src/_restore.md

@@ -0,0 +1,21 @@
+The pattern "set a new value now, restore the old one when scope ends".
+
+```js
+using _ = _restore(false, v => [this.controls.play, this.controls.play = v]);
+// ...
+```
+
+This is essentially the same as:
+
+```js
+{
+    const _old = this.controls.play;
+    this.controls.play = false;
+    try {
+        // ...
+    }
+    finally {
+        this.controls.play = _old;
+    }
+}
+```

package/src/_try.js

@@ -0,0 +1,11 @@
+function _try(callback, default_value)
+{
+    try {
+        return callback();
+    }
+    catch {
+        return default_value;
+    }
+}
+
+module.exports = _try;

package/src/_try.md

@@ -0,0 +1,5 @@
+Safely evaluates code and falls back to a default value if something goes wrong.
+
+```js
+const time = _try(() => this.$refs.iframe.contentWindow.timeline.time(), 0);
+```

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.md

@@ -0,0 +1 @@
+Returns the first element in the array with the maximal weight.

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.md

@@ -0,0 +1 @@
+Returns the first element in the array with the minimal weight.

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_shuffle.md

@@ -0,0 +1,5 @@
+Shuffles an array using Durstenfeld shuffle algorithm.
+
+Note: This function performs shuffle in-place. To get a shuffled copy
+use call slice before calling, e.g. `array_shuffle(items.slice())`.
+ 

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.md

@@ -0,0 +1 @@
+Return unique values; if a value occurs multiple times, keep the first one.

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/array_unique_last.md

@@ -0,0 +1 @@
+Return unique values; if a value occurs multiple times, keep the last one.

package/src/browser/index.js

@@ -1,7 +1,15 @@
-// https://github.com/webpack/webpack/issues/625
-// https://webpack.js.org/guides/dependency-management/#require-context
-const require_tmp = require.context('..', true, /\b(array|date|http_delete|http_get_blob|http_get_buffer|http_get_json|http_get_utf8|http_head|http_patch_json|http_post_json|http_post_multipart|http_put_buffer|http_put_json|http_put_utf8|identity|ignore|fcmp|filter|format|plural|random_int|urlmod|waitcb)[^/]*(?<!\.test)\.js$/);
-require_tmp.keys().forEach(function (key) {
-    const [, basename] = key.match(/([^/]+)\.js$/);
-    window[basename] = require_tmp(key);
-});
+const ns = new URL(document.currentScript.src).searchParams.get('var') ?? 'h';
+if (typeof window[ns] !== 'undefined') {
+    console.log(`❌ @vbarbarosh/node-helpers@${__VERSION__} was not injected — window.${ns} is already in use`);
+}
+else {
+    console.log(`🎉 @vbarbarosh/node-helpers@${__VERSION__} successfully exposed as window.${ns}`);
+    window[ns] = {};
+    // https://github.com/webpack/webpack/issues/625
+    // https://webpack.js.org/guides/dependency-management/#require-context
+    const require_tmp = require.context('..', true, /\b(array|date|http_delete|http_get_blob|http_get_buffer|http_get_json|http_get_utf8|http_head|http_patch_json|http_post_json|http_post_multipart|http_put_buffer|http_put_json|http_put_utf8|identity|ignore|fcmp|filter|format|plural|random_int|urlmod|waitcb)[^/]*(?<!\.test)\.js$/);
+    require_tmp.keys().forEach(function (key) {
+        const [, basename] = key.match(/([^/]+)\.js$/);
+        window[ns][basename] = require_tmp(key);
+    });
+}

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/fastdl.md

@@ -0,0 +1,8 @@
+Download a file in several connections in parallel.
+
+```js
+await fastdl({
+    file: fs_path_basename(new URL(url).pathname),
+    read_stream_with_range: (first, last) => http_get_stream_range(url, first, last),
+});
+```