@vbarbarosh/node-helpers 3.66.1 → 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.1",
+    "version": "3.67.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/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;

package/src/fcmpx.js

@@ -0,0 +1,120 @@
+const fcmp_default = require('./fcmp_default');
+const fcmp_default_desc = require('./fcmp_default_desc');
+const identity = require('./identity');
+
+const MISSING = Symbol('fcmpx.missing');
+
+/**
+ * Comparator builder using compact expressions.
+ *
+ * fcmp expression — Creates an `fcmp` function from an expression, suitable for use with `[].sort()`.
+ *
+ * fcmpx('user.email')
+ * fcmpx('-user.age,user.email')
+ * fcmpx(v => v.user.email)
+ * fcmpx(['user.age', 'user.email'])
+ * fcmpx(['-user.age', 'user.email'])
+ */
+function fcmpx(expr)
+{
+    if (typeof expr === 'string') {
+        if (expr.includes(',')) {
+            return fcmpx(expr.split(','));
+        }
+        return fcmpx_compile(expr);
+    }
+    if (!Array.isArray(expr)) {
+        return fcmpx_compile(expr);
+    }
+    const fcmp_items = expr.map(fcmpx_parse);
+    return function (a, b) {
+        const tuple1 = fcmp_items.map(v => v.read(a));
+        const tuple2 = fcmp_items.map(v => v.read(b));
+        for (let i = 0; i < fcmp_items.length; ++i) {
+            const tmp = fcmp_items[i].fcmp(tuple1[i], tuple2[i]);
+            if (tmp) {
+                return tmp;
+            }
+        }
+        return 0;
+    };
+}
+
+function fcmpx_compile(expr)
+{
+    const {read, fcmp} = fcmpx_parse(expr);
+    return function (a, b) {
+        return fcmp(read(a), read(b));
+    };
+}
+
+function fcmpx_parse(expr)
+{
+    if (typeof expr === 'function') {
+        return {read: fcmpx_compile_read(expr), fcmp: fcmp_wrapper(fcmp_default)};
+    }
+    if (typeof expr === 'string') {
+        const desc = expr.startsWith('-');
+        const read = desc ? fcmpx_compile_read(expr.slice(1)) : fcmpx_compile_read(expr);
+        const fcmp = fcmp_wrapper(desc ? fcmp_default_desc : fcmp_default);
+        return {read, fcmp};
+    }
+    const fcmp_user = expr.fcmp;
+    const read = fcmpx_compile_read(expr.read);
+    const desc = expr.desc ?? false;
+    const fcmp = fcmp_wrapper(desc ? (fcmp_user ? (b, a) => fcmp_user(a, b) : fcmp_default_desc) : (fcmp_user ?? fcmp_default));
+    if (Array.isArray(expr.top)) {
+        const priority = new Map(expr.top.map((v, i) => [v, i]));
+        return {read: v => priority.get(read(v)) ?? priority.size, fcmp};
+    }
+    if (Array.isArray(expr.bottom)) {
+        const priority = new Map(expr.bottom.map((v, i) => [v, i]));
+        return {read: v => priority.get(read(v)) ?? -1, fcmp};
+    }
+    return {read, fcmp};
+}
+
+function fcmpx_compile_read(read)
+{
+    if (read === undefined || read === '' || read === '.') {
+        return identity;
+    }
+    if (typeof read === 'function') {
+        return function (value) {
+            return read(value) ?? MISSING;
+        };
+    }
+    if (typeof read === 'string') {
+        const props = read.split('.');
+        const [a, b, c, d, e] = props;
+        switch (props.length) {
+        case 1: return v => v?.[a] ?? MISSING;
+        case 2: return v => v?.[a]?.[b] ?? MISSING;
+        case 3: return v => v?.[a]?.[b]?.[c] ?? MISSING;
+        case 4: return v => v?.[a]?.[b]?.[c]?.[d] ?? MISSING;
+        case 5: return v => v?.[a]?.[b]?.[c]?.[d]?.[e] ?? MISSING;
+        default: return v => props.reduce((a,p) => a?.[p], v) ?? MISSING;
+        }
+    }
+    return v => v?.[read] ?? MISSING;
+}
+
+// Sorting rule: Missing values are considered greater than any defined value
+// and are therefore placed after all defined values.
+function fcmp_wrapper(fcmp)
+{
+    return function (a, b) {
+        if (a === MISSING) {
+            if (b === MISSING) {
+                return 0;
+            }
+            return 1;
+        }
+        if (b === MISSING) {
+            return -1;
+        }
+        return fcmp(a, b);
+    };
+}
+
+module.exports = fcmpx;

package/src/fcmpx.test.js

@@ -0,0 +1,158 @@
+const assert = require('assert');
+const fcmpx = require('./fcmpx');
+
+const users = [
+    {id: 'fred|48|100', user: {name: 'fred', age: 48, balance: 100}},
+    {id: 'barney|36|-200', user: {name: 'barney', age: 36, balance: -200}},
+    {id: 'wilma|-|-', user: {name: 'wilma', tag: {short: 'foo', long: 'foofoo'}}},
+    {id: 'betty|32|-', user: {name: 'betty', tag: {short: 'bar', long: 'barbar'}, age: 32}},
+];
+
+const tests = [
+    {
+        description: 'missing: should move undefined values to the bottom',
+        items: [
+            {id: 'user1', user: {age: 48}},
+            {id: 'user2', user: {age: 36}},
+            {id: 'user3'},
+            {id: 'user4', user: {age: 32}},
+        ],
+        extract: v => v.id,
+        expressions: [
+            'user.age',
+            v => v.user?.age,
+            {read: 'user.age'},
+            {read: v => v.user?.age},
+            ['user.age'],
+            [v => v.user?.age],
+            [{read: 'user.age'}],
+            [{read: v => v.user?.age}],
+        ],
+        expected: ['user4', 'user2', 'user1', 'user3'],
+    },
+    {
+        description: 'missing: should move undefined values to the bottom #2',
+        items: [
+            {id: 'user1', user: {age: 48}},
+            {id: 'user2', user: {age: 36}},
+            {id: 'user3', user: {tag: {short: 'foo'}}},
+            {id: 'user4', user: {tag: {short: 'bar'}, age: 32}},
+        ],
+        extract: v => v.id,
+        expressions: [
+            'user.age,user.tag.short',
+            ['user.age', 'user.tag.short'],
+            [v => v.user.age, v => v.user.tag?.short],
+            [{read: 'user.age'}, {read: 'user.tag.short'}],
+            [{read: v => v.user.age}, {read: v => v.user.tag?.short}],
+        ],
+        expected: ['user4', 'user2', 'user1', 'user3'],
+    },
+    {
+        description: 'missing: should move undefined values to the bottom and keep their initial order',
+        items: [
+            {id: 'user1', user: {balance: 100}},
+            {id: 'user2', user: {balance: -200}},
+            {id: 'user3'},
+            {id: 'user4'},
+        ],
+        extract: v => v.id,
+        expressions: [
+            'user.balance',
+            v => v.user?.balance,
+            [v => v.user?.balance],
+        ],
+        expected: ['user2', 'user1', 'user3', 'user4'],
+    },
+    {
+        description: 'move undefined value to the bottom, keep their initial order',
+        items: users,
+        extract: v => v.id,
+        expressions: [
+            'user.balance,user.age',
+            [v => v.user.balance, v => v.user.age],
+        ],
+        expected: ['barney|36|-200', 'fred|48|100', 'betty|32|-', 'wilma|-|-'],
+    },
+    {
+        description: 'move undefined value to the bottom, keep their initial order',
+        items: users,
+        extract: v => v.id,
+        expressions: [
+            'user.balance,user.age',
+            [v => v.user.balance, v => v.user.age],
+        ],
+        expected: ['barney|36|-200', 'fred|48|100', 'betty|32|-', 'wilma|-|-'],
+    },
+    {
+        description: 'user.tag.short',
+        items: [
+            {user: {name: 'fred', age: 48}},
+            {user: {name: 'barney', age: 36}},
+            {user: {name: 'wilma', tag: {short: 'foo'}}},
+            {user: {name: 'betty', tag: {short: 'bar'}, age: 32}},
+        ],
+        extract: v => `${v.user.name}|${v.user.tag?.short ?? '-'}`,
+        expressions: [
+            'user.tag.short',
+            v => v.user.tag?.short,
+            [v => v.user.tag?.short],
+        ],
+        expected: ['betty|bar', 'wilma|foo', 'fred|-', 'barney|-'],
+    },
+    {
+        description: 'user.tag.short,user.age',
+        items: [
+            {user: {name: 'fred', age: 48}},
+            {user: {name: 'barney', age: 36}},
+            {user: {name: 'wilma', tag: {short: 'foo'}}},
+            {user: {name: 'betty', tag: {short: 'bar'}, age: 32}},
+        ],
+        extract: v => `${v.user.name}|${v.user.tag?.short ?? ''}|${v.user.age ?? ''}`,
+        expressions: [
+            'user.tag.short,user.age',
+            ['user.tag.short', 'user.age'],
+            [v => v.user.tag?.short, v => v.user.age],
+        ],
+        expected: ['betty|bar|32', 'wilma|foo|', 'barney||36', 'fred||48'],
+    },
+    {
+        description: 'top: move specified values to the top',
+        items: [
+            {id: 'task1', priority: 'normal'},
+            {id: 'task2', priority: 'low'},
+            {id: 'task3', priority: 'high'},
+            {id: 'task4', priority: 'normal'},
+        ],
+        extract: v => `${v.id}:${v.priority}`,
+        expressions: [
+            {read: 'priority', top: ['high']},
+        ],
+        expected: ['task3:high', 'task1:normal', 'task2:low', 'task4:normal'],
+    },
+    {
+        description: 'top: move specified values to the top #2',
+        items: [
+            {id: 'task1', priority: 'normal'},
+            {id: 'task2', priority: 'low'},
+            {id: 'task3', priority: 'high'},
+            {id: 'task4', priority: 'normal'},
+        ],
+        extract: v => `${v.id}:${v.priority}`,
+        expressions: [
+            {read: 'priority', top: ['high', 'normal', 'low']},
+        ],
+        expected: ['task3:high', 'task1:normal', 'task4:normal', 'task2:low'],
+    },
+];
+
+describe('fcmpx', function () {
+    tests.forEach(function (test) {
+        test.expressions.forEach(function (expr, i) {
+            it(`${test.description}: #${i+1} | ${test.description}`, function () {
+                const actual = test.items.slice().sort(fcmpx(expr)).map(test.extract);
+                assert.deepStrictEqual(actual, test.expected);
+            });
+        });
+    });
+});

package/src/format_date_fs.js

@@ -0,0 +1,13 @@
+function format_date_fs(d)
+{
+    const ymd = d.getFullYear() + dd(d.getMonth() + 1) + dd(d.getDate());
+    const hms = dd(d.getHours()) + dd(d.getMinutes()) + dd(d.getSeconds());
+    return ymd + '_' + hms;
+}
+
+function dd(v)
+{
+    return v > 9 ? `${v}` : `0${v}`;
+}
+
+module.exports = format_date_fs;

package/src/format_date_human.js

@@ -0,0 +1,13 @@
+function format_date_human(d)
+{
+    const ymd = d.getFullYear() + '/' + dd(d.getMonth() + 1) + '/' + dd(d.getDate());
+    const hms = dd(d.getHours()) + ':' + dd(d.getMinutes()) + ':' + dd(d.getSeconds());
+    return ymd + ' ' + hms;
+}
+
+function dd(v)
+{
+    return v > 9 ? `${v}` : `0${v}`;
+}
+
+module.exports = format_date_human;

package/src/format_progress_bytes.js

@@ -1,22 +1,22 @@
 const format_bytes = require('./format_bytes');
 const format_percents = require('./format_percents');
 const format_seconds = require('./format_seconds');
-const is_number_gt = require('@vbarbarosh/type-helpers/src/is_number_gt');
+const is_num_gt = require('@vbarbarosh/type-helpers/src/is_num_gt');
 
 function format_progress_bytes({percents, total, done, rate, eta, duration})
 {
-    const bps = is_number_gt(rate, 0) ? `${format_bytes(rate)}/s` : '~';
+    const bps = is_num_gt(rate, 0) ? `${format_bytes(rate)}/s` : '~';
     if (done > total) {
         return `${format_bytes(done)} at ${bps} duration=${format_seconds(duration)}`;
     }
-    if (is_number_gt(total, 0)) {
-        const eta_str = is_number_gt(eta, 0) ? format_seconds(eta) : '~';
+    if (is_num_gt(total, 0)) {
+        const eta_str = is_num_gt(eta, 0) ? format_seconds(eta) : '~';
         return `${format_percents(percents)} | ${format_bytes(done)} of ${format_bytes(total)} at ${bps} ETA ${eta_str} duration=${format_seconds(duration)}`;
     }
-    if (is_number_gt(done, 0)) {
+    if (is_num_gt(done, 0)) {
         return `${format_bytes(done)} of ~ at ${bps} duration=${format_seconds(duration)}`;
     }
-    if (is_number_gt(duration, 0)) {
+    if (is_num_gt(duration, 0)) {
         return `~ duration=${format_seconds(duration)}`;
     }
     return '~';

package/src/format_progress_kilo.js

@@ -1,22 +1,22 @@
 const format_kilo = require('./format_kilo');
 const format_percents = require('./format_percents');
 const format_seconds = require('./format_seconds');
-const is_number_gt = require('@vbarbarosh/type-helpers/src/is_number_gt');
+const is_num_gt = require('@vbarbarosh/type-helpers/src/is_num_gt');
 
 function format_progress_kilo({percents, total, done, rate, eta, duration})
 {
-    const speed = is_number_gt(rate, 0) ? `${format_kilo(rate)}/s` : '~';
+    const speed = is_num_gt(rate, 0) ? `${format_kilo(rate)}/s` : '~';
     if (done > total) {
         return `${format_kilo(done)} at ${speed} duration=${format_seconds(duration)}`;
     }
-    if (is_number_gt(total, 0)) {
-        const eta_str = is_number_gt(eta, 0) ? format_seconds(eta) : '~';
+    if (is_num_gt(total, 0)) {
+        const eta_str = is_num_gt(eta, 0) ? format_seconds(eta) : '~';
         return `${format_percents(percents)} | ${format_kilo(done)} of ${format_kilo(total)} at ${speed} ETA ${eta_str} duration=${format_seconds(duration)}`;
     }
-    if (is_number_gt(done, 0)) {
+    if (is_num_gt(done, 0)) {
         return `${format_kilo(done)} of ~ at ${speed} duration=${format_seconds(duration)}`;
     }
-    if (is_number_gt(duration, 0)) {
+    if (is_num_gt(duration, 0)) {
         return `~ duration=${format_seconds(duration)}`;
     }
     return '~';

package/src/fs_list.js

@@ -0,0 +1,16 @@
+const Promise = require('bluebird');
+const fs_fi = require('./fs_fi');
+const fs_path_join = require('./fs_path_join');
+const fs_readdir = require('./fs_readdir');
+
+async function fs_list(pathname = '.')
+{
+    const fi = await fs_fi(pathname);
+    if (fi.isDirectory()) {
+        const names = await fs_readdir(pathname);
+        return Promise.all(names.map(v => fs_fi(fs_path_join(pathname, v))));
+    }
+    return [fi];
+}
+
+module.exports = fs_list;

package/src/fs_list_deep.js

@@ -0,0 +1,20 @@
+const fs_fi = require('./fs_fi');
+const fs_path_join = require('./fs_path_join');
+const fs_readdir = require('./fs_readdir');
+
+async function fs_list_deep(path = '.')
+{
+    const out = [];
+    const queue = [path];
+    while (queue.length) {
+        const fi = await fs_fi(queue.pop());
+        out.push(fi);
+        if (fi.isDirectory()) {
+            const names = await fs_readdir(fi.pathname);
+            queue.push(...names.map(v => fs_path_join(fi.pathname, v)));
+        }
+    }
+    return out;
+}
+
+module.exports = fs_list_deep;

package/src/fs_ls.js

@@ -3,6 +3,9 @@ const fs_fi = require('./fs_fi');
 const fs_path_join = require('./fs_path_join');
 const fs_readdir = require('./fs_readdir');
 
+/**
+ * @deprecated Deprecated in favor or fs_list
+ */
 async function fs_ls(pathname = '.')
 {
     const fi = await fs_fi(pathname);

package/src/fs_path_extname.js

@@ -0,0 +1,14 @@
+const path = require('path');
+
+function fs_path_extname(p)
+{
+    return path.extname(p);
+}
+
+// function extname(s)
+// {
+//     const i = s.lastIndexOf('.');
+//     return (i > 0) ? s.slice(i) : null;
+// }
+
+module.exports = fs_path_extname;

package/src/fs_path_extname.test.js

@@ -0,0 +1,22 @@
+const assert = require('assert');
+const fs_path_extname = require('./fs_path_extname');
+
+const tests = [
+    ['.', ''],
+    ['..', ''],
+    ['.foo', ''],
+    ['..foo', '.foo'],
+    ['.foo.bar', '.bar'],
+    ['fs_path_extname.js', '.js'],
+    ['/path/to/file.js', '.js'],
+    ['/path/to/file.js/foo', ''],
+];
+
+describe('fs_path_extname', function () {
+    tests.forEach(function ([input, expected]) {
+        it(`${input} -> ${expected}`, function () {
+            const actual = fs_path_extname(input);
+            assert.strictEqual(actual, expected);
+        });
+    });
+});

package/src/now_fs.js

@@ -0,0 +1,8 @@
+const format_date_fs = require('./format_date_fs');
+
+function now_fs()
+{
+    return format_date_fs(new Date());
+}
+
+module.exports = now_fs;

package/src/now_human.js

@@ -0,0 +1,8 @@
+const format_date_human = require('./format_date_human');
+
+function now_human()
+{
+    return format_date_human(new Date());
+}
+
+module.exports = now_human;

package/src/parallel.js

@@ -1,7 +1,7 @@
 const NotImplemented = require('./errors/NotImplemented');
 const Promise = require('bluebird');
-const is_async_function = require('@vbarbarosh/type-helpers/src/is_async_function');
-const is_async_generator = require('@vbarbarosh/type-helpers/src/is_async_generator');
+const is_fn_async = require('@vbarbarosh/type-helpers/src/is_fn_async');
+const is_fn_gen_async = require('@vbarbarosh/type-helpers/src/is_fn_gen_async');
 
 /**
  * - Run until `spawn` return `null`.
@@ -12,7 +12,7 @@ const is_async_generator = require('@vbarbarosh/type-helpers/src/is_async_genera
  */
 async function parallel({concurrency, spawn, progress})
 {
-    if (is_async_function(spawn) || is_async_generator(spawn)) {
+    if (is_fn_async(spawn) || is_fn_gen_async(spawn)) {
         throw new Error('[spawn] should not be async function. Instead, it should be a simple function returning either [null] or a [promise].');
     }
     const running = [];

package/src/pid_exists.js

@@ -0,0 +1,12 @@
+function pid_exists(pid)
+{
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+
+module.exports = pid_exists;

package/src/pid_kill_grace.js

@@ -0,0 +1,28 @@
+const Promise = require('bluebird');
+const format_thousands = require('./format_thousands');
+const ignore = require('./ignore');
+const pid_exists = require('./pid_exists');
+
+async function pid_kill_grace(pid, {grace_timeout_ms = 5000, log = ignore} = {})
+{
+    log('Sending SIGTERM');
+    if (!process.kill(pid, 'SIGTERM')) {
+        throw new Error('SIGTERM Failed');
+    }
+
+    const end = Date.now() + grace_timeout_ms;
+    while (Date.now() < end) {
+        if (!pid_exists(pid)) {
+            return;
+        }
+        log(`Process is still there, waiting for 100ms, ${format_thousands(end - Date.now())}ms left`);
+        await Promise.delay(100);
+    }
+
+    log('Sending SIGKILL');
+    if (!process.kill(pid, 'SIGKILL')) {
+        throw new Error('SIGKILL Failed');
+    }
+}
+
+module.exports = pid_kill_grace;

package/src/ping_socket.js

@@ -0,0 +1,32 @@
+const Promise = require('bluebird');
+const net = require('net');
+
+/**
+ * - Always closes the socket.
+ * - Throws on any error or timeout.
+ * - Doesn’t hang if the server sends nothing.
+ */
+function ping_socket(socket_path, data = 'PING', timeout_ms = 1000)
+{
+    return new Promise(function (resolve, reject) {
+        let done = false;
+        const buf = [];
+        const socket = net.connect(socket_path);
+        socket.setTimeout(timeout_ms, () => finish(new Error('Socket Timeout')));
+        socket.on('end', () => finish(null, Buffer.concat(buf)))
+        socket.on('error', finish);
+        socket.on('connect', () => socket.end(data));
+        socket.on('data', chunk => buf.push(chunk));
+        function finish(error, out) {
+            if (done) {
+                return;
+            }
+            done = true;
+            socket.removeAllListeners();
+            socket.destroy();
+            error ? reject(error) : resolve(out);
+        }
+    });
+}
+
+module.exports = ping_socket;

package/src/plural.js

@@ -1,6 +1,12 @@
-function plural(n, apple, apples)
+function plural(n, singular, plural, zero)
 {
-    return (n % 10 === 1 && n % 100 !== 11) ? apple.split('#').join(n) : apples.split('#').join(n);
+    if (n === 0 && typeof zero === 'string') {
+        return zero;
+    }
+    if (n % 10 === 1 && n % 100 !== 11) {
+        return singular.split('#').join(n);
+    }
+    return plural.split('#').join(n);
 }
 
 module.exports = plural;

package/src/plural.test.js

@@ -1,15 +1,17 @@
 const assert = require('assert');
 const plural = require('./plural');
 
-const items = [
-    ['1 apple', 1, '# apple', '# apples', ],
+const tests = [
+    ['1 apple', 1, '# apple', '# apples'],
     ['2 apples', 2, '# apple', '# apples'],
     ['10 apples', 10, '# apple', '# apples'],
     ['21 apple', 21, '# apple', '# apples'],
+    ['0 apples', 0, '# apple', '# apples'],
+    ['No apples', 0, '# apple', '# apples', 'No apples'],
 ];
 
 describe('plural', function () {
-    items.forEach(function ([expected, ...args],) {
+    tests.forEach(function ([expected, ...args],) {
         it(expected, function () {
             const actual = plural(...args);
             assert.deepStrictEqual(actual, expected);

package/src/sanitize_var_name.js

@@ -1,9 +1,9 @@
-const camel_to_snake = require('./camel_to_snake');
 const sanitize_dash_name = require('./sanitize_dash_name');
+const str_camel_to_snake = require('./str_camel_to_snake');
 
 function sanitize_var_name(var_name)
 {
-    const out = sanitize_dash_name(camel_to_snake(var_name)).replace(/[^a-z0-9]+/g, '_');
+    const out = sanitize_dash_name(str_camel_to_snake(var_name)).replace(/[^a-z0-9]+/g, '_');
     if (out.length === 0) {
         return '_';
     }

package/src/{camel_to_snake.js → str_camel_to_snake.js}

@@ -1,4 +1,4 @@
-function camel_to_snake(s)
+function str_camel_to_snake(s)
 {
     return s
         .replace(/([a-z0-9])([A-Z])/g, '$1_$2')  // Insert underscore between lowercase/number and uppercase
@@ -6,4 +6,4 @@ function camel_to_snake(s)
         .toLowerCase();
 }
 
-module.exports = camel_to_snake;
+module.exports = str_camel_to_snake;

package/src/{camel_to_snake.test.js → str_camel_to_snake.test.js}

@@ -1,5 +1,5 @@
 const assert = require('assert');
-const camel_to_snake = require('./camel_to_snake');
+const str_camel_to_snake = require('./str_camel_to_snake');
 
 const items = [
     ['UPC', 'upc'],
@@ -8,10 +8,10 @@ const items = [
     ['XMLHTTPRequest', 'xmlhttp_request'],
 ];
 
-describe('camel_to_snake', function () {
+describe('str_camel_to_snake', function () {
     items.forEach(function ([input, expected],) {
         it(`${input === '' ? '☒' : input} → ${expected}`, function () {
-            assert.deepStrictEqual(camel_to_snake(input), expected);
+            assert.deepStrictEqual(str_camel_to_snake(input), expected);
         });
     });
 });

package/src/str_parse_kv.js

@@ -0,0 +1,10 @@
+function str_parse_kv(str)
+{
+    const i = str.indexOf(':');
+    if (i === -1) {
+        return [str.trim(), ''];
+    }
+    return [str.slice(0, i).trim(), str.slice(i + 1).trim()];
+}
+
+module.exports = str_parse_kv;

package/src/fcmp_strings.js

@@ -1,6 +0,0 @@
-function fcmp_strings(a, b)
-{
-    return String(a).localeCompare(b);
-}
-
-module.exports = fcmp_strings;