@vbarbarosh/node-helpers 3.75.0 → 3.76.0

package/package.json

@@ -2,20 +2,30 @@
     "author": "Vladimir Barbarosh <vladimir.barbarosh@gmail.com>",
     "license": "MIT",
     "name": "@vbarbarosh/node-helpers",
-    "version": "3.75.0",
+    "version": "3.76.0",
     "description": "A set of helpers for JavaScript/Node.js",
     "unpkg": "dist/browser.js",
     "jsdelivr": "dist/browser.js",
+    "exports": {
+        "./src/*.js": "./src/*.js",
+        "./src/*": "./src/*.js",
+        "./dist/*": "./dist/*",
+        "./package.json": "./package.json"
+    },
     "homepage": "https://vbarbarosh.github.io/node-helpers/",
     "bin": {
         "watchdog": "src/cli-apps/watchdog.js"
     },
     "files": [
         "dist",
-        "src"
+        "src",
+        "!src/**/*.test.js",
+        "!src/**/*.d"
     ],
     "scripts": {
-        "build": "rm -rf dist; webpack",
+        "build": "rm -rf dist && webpack",
+        "coverage": "c8 mocha 'src/**/*.test.js'",
+        "lint": "eslint src webpack.config.js eslint.config.js",
         "test": "mocha 'src/**/*.test.js'"
     },
     "keywords": [
@@ -23,6 +33,9 @@
         "node",
         "helpers"
     ],
+    "engines": {
+        "node": ">=22"
+    },
     "repository": {
         "type": "git",
         "url": "git+https://github.com/vbarbarosh/node-helpers.git"
@@ -30,35 +43,42 @@
     "bugs": {
         "url": "https://github.com/vbarbarosh/node-helpers/issues"
     },
-    "peerDependencies": {
-        "@paralleldrive/cuid2": "^3.0.4",
+    "dependencies": {
+        "@paralleldrive/cuid2": "^3.3.0",
         "@vbarbarosh/type-helpers": "^0.2.0",
         "axios": "^1.7.9",
         "bluebird": "^3.7.2",
-        "csv-parse": "^5.6.0",
+        "csv-parse": "^7.0.1",
         "form-data": "^4.0.1",
-        "htmlparser2": "^10.0.0",
+        "htmlparser2": "^12.0.0",
         "json-stable-stringify": "^1.2.1",
         "json-stringify-safe": "^5.0.1",
-        "mime-types": "^2.1.35",
+        "mime-types": "^3.0.2",
         "sanitize-filename": "^1.6.3",
         "split": "^1.0.1"
     },
     "optionalDependencies": {
+        "redis": "^4.6.0",
         "ssh2": "^1.16.0"
     },
     "devDependencies": {
+        "@eslint/js": "^10.0.1",
         "@vbarbarosh/tree": "^0.5.0",
-        "copy-webpack-plugin": "^12.0.2",
-        "express": "^4.21.2",
+        "c8": "^11.0.0",
+        "copy-webpack-plugin": "^14.0.0",
+        "eslint": "^10.7.0",
+        "express": "^5.2.1",
+        "globals": "^17.7.0",
         "mocha": "^11.0.1",
         "redis-v1": "npm:redis@1",
         "redis-v2": "npm:redis@2",
         "redis-v3": "npm:redis@3",
         "redis-v4": "npm:redis@4",
+        "redis-v5": "npm:redis@^5.12.1",
+        "redis-v6": "npm:redis@^6.1.0",
         "throttle": "^1.0.3",
         "tree-kill": "^1.2.2",
         "webpack": "^5.98.0",
-        "webpack-cli": "^6.0.1"
+        "webpack-cli": "^7.2.1"
     }
 }

package/src/HeartbeatServer.js

@@ -4,10 +4,15 @@ const Promise = require('bluebird');
 const fs = require('fs');
 const fs_path_join = require('./fs_path_join');
 const fs_rmf = require('./fs_rmf');
+const ignore = require('./ignore');
 const net = require('net');
 const now_fs = require('./now_fs');
 const os = require('os');
 
+// now_fs has 1 second resolution: without a counter two instances created
+// within the same second would collide on the socket path (EADDRINUSE)
+let socket_counter = 0;
+
 // 💎 Only the lack of a valid PING within WATCHDOG_INTERVAL is fatal
 class HeartbeatServer extends EventEmitter
 {
@@ -31,13 +36,17 @@ class HeartbeatServer extends EventEmitter
         this.#timer = setInterval(() => this.#tick(), this.#interval_ms);
 
         // Put socket on tmpfs to avoid slow disks.
+        const socket_name = `watchdog-${process.pid}-${now_fs()}-${++socket_counter}.sock`;
         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`);
+            ? fs_path_join('/dev/shm', socket_name)
+            : fs_path_join(os.tmpdir(), socket_name);
 
         this.#promise = new Promise((resolve, reject) => {
             this.#reject = reject;
         });
+        // A clean dispose rejects the internal promise: without a handler of
+        // our own that raises an unhandled rejection when nobody awaits promise()
+        this.#promise.catch(ignore);
 
         this.#server = net.createServer(function (client) {
             let bytes_received = 0;
@@ -109,11 +118,23 @@ class HeartbeatServer extends EventEmitter
         if (!this.#server) {
             return;
         }
+        // removeAllListeners below also removes the 'close' handler which
+        // would have rejected: reject explicitly, as documented
+        this.#reject(new Error('Server Closed'));
         try {
             const _this = this;
             await new Promise(function (resolve, reject) {
                 _this.#server.removeAllListeners();
-                _this.#server.close(error => error ? reject(error) : resolve());
+                _this.#server.close(function (error) {
+                    // close() reports ERR_SERVER_NOT_RUNNING when listen
+                    // never completed (failed or still pending): dispose is
+                    // documented idempotent, "nothing to close" is not an error
+                    if (error && error.code !== 'ERR_SERVER_NOT_RUNNING') {
+                        reject(error);
+                        return;
+                    }
+                    resolve();
+                });
                 _this.#server = null;
             });
         }

package/src/HeartbeatServer.md

@@ -0,0 +1,33 @@
+Watchdog for worker processes. Listens on a unix domain socket and expects
+regular pings (see `ping_socket`); the internal promise rejects when no valid
+ping arrives within `interval_ms` (default 5000). Only the lack of a valid
+PING within the interval is fatal — everything else (client errors, floods)
+merely emits a `warning` event.
+
+**Socket:** placed on `/dev/shm` when available (tmpfs, avoids slow disks),
+otherwise `os.tmpdir()`. The path is unique per instance, even for instances
+created within the same second. A ping is any connection that ends cleanly;
+the server replies `OK` and ignores the payload (a client sending over 1 MiB
+is destroyed with a `warning`).
+
+**promise():** rejects with `ExitCodeError` (`exit_code = 124`,
+`No heartbeat...`) when the watchdog fires — the instance then disposes
+itself, so no `heartbeat` events follow. Rejects with `Server Failed: ...`
+if the socket cannot listen. Never resolves.
+
+**dispose():** stops the timer, closes the server, removes the socket file,
+and rejects the internal promise with a `Server Closed` error. Idempotent —
+safe to call before listening completed, after a failed listen, and twice.
+
+**Events:** `heartbeat` (a ping was received), `warning` (non-fatal error).
+
+```js
+const server = new HeartbeatServer(5000);
+try {
+    worker.send({watchdog_socket: server.socket_path});
+    await server.promise(); // rejects on missing heartbeat or dispose()
+}
+finally {
+    await server.dispose();
+}
+```

package/src/array_chunk.js

@@ -8,7 +8,7 @@
 function array_chunk(array = [], limit = 1)
 {
     if (limit < 1) {
-        throw new Error('Limit value should be greater than 1');
+        throw new Error('Limit value should be at least 1');
     }
 
     const out = [];

package/src/array_chunk.md

@@ -0,0 +1,8 @@
+Splits an array into consecutive chunks of at most `limit` items (default `1`).
+The last chunk may be shorter. Throws if `limit` is less than 1.
+
+```js
+array_chunk([1, 2, 3, 4, 5], 2)    // [[1, 2], [3, 4], [5]]
+array_chunk([1, 2, 3], 5)          // [[1, 2, 3]]
+array_chunk([])                    // []
+```

package/src/array_chunk_balanced.md

@@ -0,0 +1,14 @@
+Splits an array into up to `max_chunks` balanced chunks, keeping at least
+`min_items_per_chunk` items per chunk when possible. Chunk sizes differ by at
+most 1 item; earlier chunks receive the extras. Originally designed for
+distributing jobs across threads: `array_chunk_balanced(jobs, max_threads, min_jobs_per_thread)`.
+
+**Edge cases:**
+- Empty input returns `[]`.
+- If there are too few items to satisfy `min_items_per_chunk` even for a
+  single chunk, all items go into one chunk.
+
+```js
+array_chunk_balanced([1, 2, 3, 4, 5, 6, 7], 3, 2)    // [[1, 2, 3], [4, 5], [6, 7]]
+array_chunk_balanced([1, 2, 3], 5, 5)                // [[1, 2, 3]]
+```

package/src/array_fps.md

@@ -0,0 +1,12 @@
+Returns frame timestamps (in seconds) for a clip of `duration_sec` sampled at
+`fps` frames per second: `Math.floor(duration_sec * fps)` evenly spaced values
+from `0` up to just under `duration_sec`. Each timestamp is pulled back by an
+epsilon of `0.00001` and rounded to it, so the last frame never lands exactly
+on the duration.
+
+If the clip fits one frame or less (`duration_sec * fps <= 1`), returns `[0]`.
+
+```js
+array_fps(1, 4)    // [0, 0.33333, 0.66666, 0.99999]
+array_fps(1, 1)    // [0]
+```

package/src/array_gcd.js

@@ -1,9 +1,11 @@
 const math_gcd = require('./math_gcd');
 
 // https://stackoverflow.com/a/39764792/1478566
-function array_gcd(array, fn = Number)
+function array_gcd(array, read = Number)
 {
-    return array.reduce((a,b) => math_gcd(fn(a), fn(b)));
+    // 0 is the identity of gcd (gcd(0, x) = x); it also makes an empty
+    // array return 0 instead of throwing
+    return array.map(v => read(v)).reduce((a,b) => math_gcd(a, b), 0);
 }
 
 module.exports = array_gcd;

package/src/array_gcd.md

@@ -1,2 +1,3 @@
 Returns the greatest common divisor (GCD) of all elements in the array.
-`fn(item)` is applied to each element before computing.
+`read(item)` is applied to each element before computing.
+The result is always non-negative; an empty array returns `0`.

package/src/array_group.js

@@ -1,13 +1,13 @@
 /**
  * Group items by a common key and return an array of groups.
  *
- * @alternative Map.groupBy(items, fn)
+ * @alternative Map.groupBy(items, read)
  */
-function array_group(array, fn)
+function array_group(array, read)
 {
     const map = new Map();
     array.forEach(function (item) {
-        const key = fn(item);
+        const key = read(item);
         if (!map.has(key)) {
             map.set(key, {key, items: []});
         }

package/src/array_group.md

@@ -0,0 +1,14 @@
+Groups items by the key returned from `read(item)` and returns an array of
+`{key, items}` groups, in the order each key was first seen. Keys are compared
+with `Map` semantics, so any value type works as a key.
+
+```js
+array_group([{t: 'a', v: 1}, {t: 'b', v: 2}, {t: 'a', v: 3}], x => x.t)
+// [
+//     {key: 'a', items: [{t: 'a', v: 1}, {t: 'a', v: 3}]},
+//     {key: 'b', items: [{t: 'b', v: 2}]},
+// ]
+```
+
+Native alternative: `Map.groupBy(items, read)`. See `array_group_map` for the
+same grouping returned as an object keyed by `key`.

package/src/array_group_map.js

@@ -2,14 +2,14 @@
  * Group items by common key and return an object of items grouped by key.
  *
  * @param array
- * @param fn
+ * @param read
  * @returns {{}}
  */
-function array_group_map(array, fn)
+function array_group_map(array, read)
 {
     const out = {};
     array.forEach(function (item) {
-        const key = fn(item);
+        const key = read(item);
         out[key] = out[key] || {key, items: []};
         out[key].items.push(item);
     });

package/src/array_group_map.md

@@ -0,0 +1,13 @@
+Groups items by the key returned from `read(item)` and returns a plain object
+mapping each key to a `{key, items}` group. Keys are used as object properties,
+so they are coerced to strings.
+
+```js
+array_group_map([{t: 'a', v: 1}, {t: 'b', v: 2}, {t: 'a', v: 3}], x => x.t)
+// {
+//     a: {key: 'a', items: [{t: 'a', v: 1}, {t: 'a', v: 3}]},
+//     b: {key: 'b', items: [{t: 'b', v: 2}]},
+// }
+```
+
+See `array_group` for the same grouping returned as an array of groups.

package/src/array_index.js

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

package/src/array_index.md

@@ -0,0 +1,9 @@
+Builds an object mapping `read(item)` to the item itself. `read` defaults to
+`identity`. When several items share a key, the last one wins.
+
+```js
+array_index([{uid: 'a'}, {uid: 'b'}], v => v.uid)
+// {a: {uid: 'a'}, b: {uid: 'b'}}
+```
+
+Native alternative: `Object.fromEntries(items.map(v => [v.uid, v]))`.

package/src/array_lcm.js

@@ -1,8 +1,10 @@
 const math_lcm = require('./math_lcm');
 
-function array_lcm(array, fn = Number)
+function array_lcm(array, read = Number)
 {
-    return array.reduce((a,b) => math_lcm(fn(a), fn(b)));
+    // 1 is the identity of lcm (lcm(1, x) = x); it also makes an empty
+    // array return 1 instead of throwing
+    return array.map(v => read(v)).reduce((a,b) => math_lcm(a, b), 1);
 }
 
 module.exports = array_lcm;

package/src/array_lcm.md

@@ -1,2 +1,3 @@
 Returns the least common multiple (LCM) of all elements in the array.
-`fn(item)` is applied to each element before computing.
+`read(item)` is applied to each element before computing.
+The result is always non-negative; an empty array returns `1`.

package/src/array_max.js

@@ -3,13 +3,20 @@ const identity = require('./identity');
 /**
  * Returns the first element in the array with the maximal weight
  */
-function array_max(array, fn = identity)
+function array_max(array, read = identity)
 {
     let out = null;
     let max = null;
-    array.forEach(function (item, i) {
-        const weight = fn(item);
-        if (i === 0 || max < weight) {
+    let seeded = false;
+    array.forEach(function (item) {
+        const weight = read(item);
+        // NaN compares false with everything: seeding max with it would
+        // make every subsequent comparison fail
+        if (Number.isNaN(weight)) {
+            return;
+        }
+        if (!seeded || max < weight) {
+            seeded = true;
             max = weight;
             out = item;
         }

package/src/array_max.md

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

package/src/array_min.js

@@ -3,13 +3,20 @@ const identity = require('./identity');
 /**
  * Returns the first element in the array with the minimal weight
  */
-function array_min(array, fn = identity)
+function array_min(array, read = identity)
 {
     let out = null;
     let min = null;
-    array.forEach(function (item, i) {
-        const weight = fn(item);
-        if (i === 0 || min > weight) {
+    let seeded = false;
+    array.forEach(function (item) {
+        const weight = read(item);
+        // NaN compares false with everything: seeding min with it would
+        // make every subsequent comparison fail
+        if (Number.isNaN(weight)) {
+            return;
+        }
+        if (!seeded || min > weight) {
+            seeded = true;
             min = weight;
             out = item;
         }

package/src/array_min.md

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

package/src/array_permutations.js

@@ -5,6 +5,10 @@ function array_permutations(array, k = array.length)
         return array_permutations_k(array, k);
     }
 
+    // Heap's algorithm permutes in place: work on a copy, the caller's
+    // array must not be left in an arbitrary permuted state.
+    array = array.slice();
+
     let length = array.length;
     let out = [array.slice()];
     let c = new Array(length).fill(0);

package/src/array_permutations.md

@@ -0,0 +1,13 @@
+Returns all permutations of the array. With the optional `k`, returns all
+ordered arrangements of `k` elements instead. The input array is never mutated.
+
+**Order:** full permutations come out in Heap's-algorithm order, not
+lexicographic; `k`-arrangements come out grouped by the first element in input
+order.
+
+**Edge cases:** `k = 0` gives `[[]]`; `k` larger than the array length gives `[]`.
+
+```js
+array_permutations([1, 2, 3])       // [[1,2,3], [2,1,3], [3,1,2], [1,3,2], [2,3,1], [3,2,1]]
+array_permutations([1, 2, 3], 2)    // [[1,2], [1,3], [2,1], [2,3], [3,1], [3,2]]
+```

package/src/array_sort.js

@@ -5,6 +5,7 @@ const fcmp_tuples = require('./fcmp_tuples');
  * Sorts an array in place by the result of applying `fn` to each item,
  * using `fcmp` to compare the results.
  *
+ * array_sort(items, v => v.name)
  * array_sort(items, v => [v.name])
  * array_sort(items, v => [v.age, v.name])
  */
@@ -12,11 +13,15 @@ function array_sort(array, mapper, fcmp = fcmp_default)
 {
     const keys = new Map();
     return array.sort(function (a, b) {
+        // A scalar key is a 1-tuple: fcmp_tuples on scalars would compare
+        // nothing and silently leave the array unsorted
         if (!keys.has(a)) {
-            keys.set(a, mapper(a));
+            const key = mapper(a);
+            keys.set(a, Array.isArray(key) ? key : [key]);
         }
         if (!keys.has(b)) {
-            keys.set(b, mapper(b));
+            const key = mapper(b);
+            keys.set(b, Array.isArray(key) ? key : [key]);
         }
         return fcmp_tuples(keys.get(a), keys.get(b), fcmp);
     });

package/src/array_sort.md

@@ -0,0 +1,13 @@
+Sorts an array in place by the key(s) that `mapper` returns for each item,
+comparing with `fcmp` (default `fcmp_default`, natural order). The mapper may
+return a scalar or a tuple; tuples compare element by element via
+`fcmp_tuples`, so later elements break ties. Keys are cached, so the mapper
+runs at most once per item. Returns the sorted array.
+
+```js
+array_sort([{id: 3}, {id: 1}, {id: 2}], v => v.id)    // sorted by id
+array_sort(files, v => [v.type, v.name])              // by type, then by name
+```
+
+A common pattern for "these values first" is a priority index in the tuple:
+`array_sort(items, v => [priorities.indexOf(v.type) >>> 0, v.name])`.

package/src/array_sort_other.js

@@ -5,18 +5,21 @@ const fcmp_default = require('./fcmp_default');
  * are not in the `other` are added to the end of the result defined by `fcmp`.
  *
  * @param array
- * @param fn
+ * @param read
  * @param other
  * @param fcmp
  * @returns {*}
  */
-function array_sort_other(array, fn, other, fcmp = fcmp_default)
+function array_sort_other(array, read, other, fcmp = fcmp_default)
 {
-    const other_map = {};
+    // No-prototype object: with a plain {} the keys 'constructor',
+    // 'toString', '__proto__', ... would collide with Object.prototype
+    // members and corrupt the sort order.
+    const other_map = Object.create(null);
     other.forEach((v,i) => other_map[v] = i + 1);
     return array.sort(function (a, b) {
-        const ax = other_map[fn(a)];
-        const bx = other_map[fn(b)];
+        const ax = other_map[read(a)];
+        const bx = other_map[read(b)];
         if (ax && bx) {
             return ax - bx;
         }

package/src/array_sort_other.md

@@ -0,0 +1,11 @@
+Sorts `array` in place so that items whose `read(item)` value appears in
+`other` come first, in the same order as in `other`. Items not found in
+`other` go to the end, ordered by `fcmp(a, b)` — note the fallback compares
+the items themselves, not their `read` keys (default `fcmp_default`).
+
+Lookup keys are coerced to object property strings; a null-prototype map is
+used internally, so values like `'constructor'` or `'__proto__'` are safe.
+
+```js
+array_sort_other([1, 2, 3, 4, 5], v => v, [5])    // [5, 1, 2, 3, 4]
+```

package/src/array_sum.js

@@ -1,8 +1,8 @@
-function array_sum(array, fn = Number)
+function array_sum(array, read = Number)
 {
     let out = 0;
     array.forEach(function (item) {
-        out += fn(item);
+        out += read(item);
     });
     return out;
 }

package/src/array_sum.md

@@ -0,0 +1,8 @@
+Sums `read(item)` over the array. `read` defaults to `Number`, so string
+items are cast. An empty array sums to `0`.
+
+```js
+array_sum([1, 2, 3, 4, 5])              // 15
+array_sum(['1', '2', '3'])              // 6
+array_sum([{n: 1}, {n: 2}], v => v.n)   // 3
+```

package/src/array_unique.js

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

package/src/array_unique_last.js

@@ -3,13 +3,13 @@ const identity = require('./identity');
 /**
  * Return unique values; if a value occurs multiple times, keep the last one.
  */
-function array_unique_last(array, fn = identity)
+function array_unique_last(array, read = identity)
 {
     const out = [];
     const set = new Set();
     for (let i = array.length; --i >= 0; ) {
         const item = array[i];
-        const key = fn(item);
+        const key = read(item);
         if (!set.has(key)) {
             set.add(key);
             out.push(item);

package/src/assert_valid_expires_at.md

@@ -0,0 +1,10 @@
+Asserts that `expires_at` is a `Date` object pointing to the future
+(`getTime() > Date.now()`). Returns nothing on success; throws an `Error`
+for anything else — past dates, the current instant, timestamps, date
+strings, or non-`Date` values.
+
+```js
+assert_valid_expires_at(new Date(Date.now() + 60000))   // ok, returns undefined
+assert_valid_expires_at(new Date(Date.now() - 1))       // throws Error
+assert_valid_expires_at(Date.now() + 60000)             // throws Error (number, not Date)
+```

package/src/clamp.md

@@ -0,0 +1,9 @@
+Clamps `value` into the `[min, max]` range. Note the argument order:
+`clamp(min, max, value)`, the value comes last.
+
+```js
+clamp(0, 10, 15)    // 10
+clamp(0, 10, -1)    // 0
+clamp(0, 10, 5)     // 5
+clamp(5, 5, 7)      // 5 (degenerate range)
+```

package/src/cli-apps/watchdog.js

@@ -47,6 +47,11 @@ async function main()
     }
 
     switch (ARGS[0]) {
+    case '-h':
+    case '--help':
+        usage();
+        process.exit(0);
+        break;
     case '-v':
     case '--version':
         version();

package/src/cli.js

@@ -9,7 +9,9 @@ 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);
+    // Promise.resolve(main()) would evaluate main() before wrapping:
+    // a synchronous throw would bypass report() and the exit code handling
+    Promise.try(main).then(resolve, reject);
 
     function resolve() {
         clearInterval(timer);