@vbarbarosh/node-helpers 3.72.4 → 3.73.0

package/README.md

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

package/dist/browser.js

@@ -72,14 +72,16 @@ function serializer(replacer, cycleReplacer) {
 
 /***/ }),
 
-/***/ "./src sync recursive \\b(array%7Cdate%7Chttp_delete%7Chttp_get_blob%7Chttp_get_buffer%7Chttp_get_json%7Chttp_get_utf8%7Chttp_head%7Chttp_patch_json%7Chttp_post_json%7Chttp_post_multipart%7Chttp_put_buffer%7Chttp_put_json%7Chttp_put_utf8%7Cidentity%7Cignore%7Cfcmp%7Cfilter%7Cformat%7Cplural%7Crandom_int%7Curlmod%7Cwaitcb)[^/]*(?<%21\\.test)\\.js$":
-/*!*******************************************************************************************************************************************************************************************************************************************************************************************************************************************************!*\
-  !*** ./src/ sync \b(array%7Cdate%7Chttp_delete%7Chttp_get_blob%7Chttp_get_buffer%7Chttp_get_json%7Chttp_get_utf8%7Chttp_head%7Chttp_patch_json%7Chttp_post_json%7Chttp_post_multipart%7Chttp_put_buffer%7Chttp_put_json%7Chttp_put_utf8%7Cidentity%7Cignore%7Cfcmp%7Cfilter%7Cformat%7Cplural%7Crandom_int%7Curlmod%7Cwaitcb)[^/]*(?<%21\.test)\.js$ ***!
-  \*******************************************************************************************************************************************************************************************************************************************************************************************************************************************************/
+/***/ "./src sync recursive ^(?%21.*(cli-apps%7Cbrowser%7C\\.d)\\/).*\\b(array%7Cdate%7Chttp_delete%7Chttp_get_blob%7Chttp_get_buffer%7Chttp_get_json%7Chttp_get_utf8%7Chttp_head%7Chttp_patch_json%7Chttp_post_json%7Chttp_post_multipart%7Chttp_put_buffer%7Chttp_put_json%7Chttp_put_utf8%7Cidentity%7Cignore%7Cfcmp%7Cfilter%7Cformat%7Cplural%7Crandom_int%7Curlmod%7Cwaitcb)[^/]*(?<%21\\.test)\\.js$":
+/*!**********************************************************************************************************************************************************************************************************************************************************************************************************************************************************************************************!*\
+  !*** ./src/ sync ^(?%21.*(cli-apps%7Cbrowser%7C\.d)\/).*\b(array%7Cdate%7Chttp_delete%7Chttp_get_blob%7Chttp_get_buffer%7Chttp_get_json%7Chttp_get_utf8%7Chttp_head%7Chttp_patch_json%7Chttp_post_json%7Chttp_post_multipart%7Chttp_put_buffer%7Chttp_put_json%7Chttp_put_utf8%7Cidentity%7Cignore%7Cfcmp%7Cfilter%7Cformat%7Cplural%7Crandom_int%7Curlmod%7Cwaitcb)[^/]*(?<%21\.test)\.js$ ***!
+  \**********************************************************************************************************************************************************************************************************************************************************************************************************************************************************************************************/
 /***/ ((module, __unused_webpack_exports, __webpack_require__) => {
 
 var map = {
 	"./array_chunk.js": "./src/array_chunk.js",
+	"./array_chunk_jobs.js": "./src/array_chunk_jobs.js",
+	"./array_fps.js": "./src/array_fps.js",
 	"./array_gcd.js": "./src/array_gcd.js",
 	"./array_group.js": "./src/array_group.js",
 	"./array_group_map.js": "./src/array_group_map.js",
@@ -94,8 +96,6 @@ var map = {
 	"./array_sum.js": "./src/array_sum.js",
 	"./array_unique.js": "./src/array_unique.js",
 	"./array_unique_last.js": "./src/array_unique_last.js",
-	"./cli-apps/watchdog.d/ignore_sigterm.js": "./src/cli-apps/watchdog.d/ignore_sigterm.js",
-	"./cli-apps/watchdog.d/my-ignore-sigterm.js": "./src/cli-apps/watchdog.d/my-ignore-sigterm.js",
 	"./date_add_hours.js": "./src/date_add_hours.js",
 	"./date_add_milliseconds.js": "./src/date_add_milliseconds.js",
 	"./date_add_minutes.js": "./src/date_add_minutes.js",
@@ -146,8 +146,6 @@ var map = {
 	"./http_put_utf8.js": "./src/http_put_utf8.js",
 	"./identity.js": "./src/identity.js",
 	"./ignore.js": "./src/ignore.js",
-	"./pid_kill_grace.d/ignore-sigterm-for-10ms.js": "./src/pid_kill_grace.d/ignore-sigterm-for-10ms.js",
-	"./pid_kill_grace.d/ignore-sigterm.js": "./src/pid_kill_grace.d/ignore-sigterm.js",
 	"./plural.js": "./src/plural.js",
 	"./random_int.js": "./src/random_int.js",
 	"./urlmod.js": "./src/urlmod.js",
@@ -172,7 +170,7 @@ webpackContext.keys = function webpackContextKeys() {
 };
 webpackContext.resolve = webpackContextResolve;
 module.exports = webpackContext;
-webpackContext.id = "./src sync recursive \\b(array%7Cdate%7Chttp_delete%7Chttp_get_blob%7Chttp_get_buffer%7Chttp_get_json%7Chttp_get_utf8%7Chttp_head%7Chttp_patch_json%7Chttp_post_json%7Chttp_post_multipart%7Chttp_put_buffer%7Chttp_put_json%7Chttp_put_utf8%7Cidentity%7Cignore%7Cfcmp%7Cfilter%7Cformat%7Cplural%7Crandom_int%7Curlmod%7Cwaitcb)[^/]*(?<%21\\.test)\\.js$";
+webpackContext.id = "./src sync recursive ^(?%21.*(cli-apps%7Cbrowser%7C\\.d)\\/).*\\b(array%7Cdate%7Chttp_delete%7Chttp_get_blob%7Chttp_get_buffer%7Chttp_get_json%7Chttp_get_utf8%7Chttp_head%7Chttp_patch_json%7Chttp_post_json%7Chttp_post_multipart%7Chttp_put_buffer%7Chttp_put_json%7Chttp_put_utf8%7Cidentity%7Cignore%7Cfcmp%7Cfilter%7Cformat%7Cplural%7Crandom_int%7Curlmod%7Cwaitcb)[^/]*(?<%21\\.test)\\.js$";
 
 /***/ }),
 
@@ -205,6 +203,83 @@ function array_chunk(array = [], limit = 1)
 module.exports = array_chunk;
 
 
+/***/ }),
+
+/***/ "./src/array_chunk_jobs.js":
+/*!*********************************!*\
+  !*** ./src/array_chunk_jobs.js ***!
+  \*********************************/
+/***/ ((module, __unused_webpack_exports, __webpack_require__) => {
+
+const clamp = __webpack_require__(/*! ./clamp */ "./src/clamp.js");
+
+/**
+ * Split an array of jobs between up to `max_threads`, while trying to put at least
+ * `min_jobs_per_thread` items into each chunk.
+ *
+ * - If an array is empty → returns [].
+ * - If there are too few items to satisfy `min_items_per_chunk`, even for 1 chunk,
+ *   everything goes into a single chunk.
+ *
+ * Alternative names:
+ *   - array_chunk_balanced
+ *
+ * @param array
+ * @param max_threads
+ * @param min_jobs_per_thread
+ * @returns {*[]}
+ */
+function array_chunk_jobs(array = [], max_threads = 1, min_jobs_per_thread = 1)
+{
+    const total_threads = clamp(1, max_threads, Math.floor(array.length / min_jobs_per_thread));
+    const jobs_per_thread = Math.floor(array.length / total_threads);
+    let extra = array.length % total_threads;
+
+    const out = [];
+    for (let i = 0; i < array.length; ) {
+        const size = jobs_per_thread + (extra ? 1 : 0);
+        out.push(array.slice(i, i + size));
+        i += size;
+        if (extra) {
+            extra--;
+        }
+    }
+    return out;
+}
+
+module.exports = array_chunk_jobs;
+
+
+/***/ }),
+
+/***/ "./src/array_fps.js":
+/*!**************************!*\
+  !*** ./src/array_fps.js ***!
+  \**************************/
+/***/ ((module, __unused_webpack_exports, __webpack_require__) => {
+
+const round = __webpack_require__(/*! ./round */ "./src/round.js");
+
+const EPS = 0.00001;
+
+function array_fps(duration_sec, fps)
+{
+    const total_frames = Math.floor(duration_sec * fps);
+
+    if (total_frames <= 1) {
+        return [0];
+    }
+
+    const out = [];
+    for (let i = 0; i < total_frames; ++i) {
+        out.push(round((i / (total_frames - 1)) * (duration_sec - EPS), EPS));
+    }
+    return out;
+}
+
+module.exports = array_fps;
+
+
 /***/ }),
 
 /***/ "./src/array_gcd.js":
@@ -650,112 +725,18 @@ module.exports = array_unique_last;
 
 /***/ }),
 
-/***/ "./src/cli-apps/watchdog.d/ignore_sigterm.js":
-/*!***************************************************!*\
-  !*** ./src/cli-apps/watchdog.d/ignore_sigterm.js ***!
-  \***************************************************/
-/***/ (() => {
-
-//#!/usr/bin/env node
-
-// 1️⃣ Client that ignores SIGTERM
-// Goal: process stays alive after SIGTERM and only dies on SIGKILL (exactly what pid_kill_grace should handle).
-//
-// What this tests for watchdog:
-//   - watchdog sends SIGTERM → process prints “ignored” and keeps running.
-//   - pid_kill_grace waits grace_timeout_ms, sees PID still alive, sends SIGKILL.
-//   - Process must die after SIGKILL.
-//   - Watchdog should log the whole sequence correctly.
-// This is a realistic scenario.
-
-console.log('PID:', process.pid);
-
-// Ignore SIGTERM
-process.on('SIGTERM', function () {
-    console.log('SIGTERM received, but intentionally ignored');
-});
-
-// Still react to SIGINT (Ctrl+C) so you can stop it manually if needed
-process.on('SIGINT', function () {
-    console.log('SIGINT received, exiting');
-    process.exit(130);
-});
-
-// Keep process alive
-setInterval(() => {
-    // simulate work
-}, 1000);
-
-
-/***/ }),
-
-/***/ "./src/cli-apps/watchdog.d/my-ignore-sigterm.js":
-/*!******************************************************!*\
-  !*** ./src/cli-apps/watchdog.d/my-ignore-sigterm.js ***!
-  \******************************************************/
-/***/ ((__unused_webpack_module, __unused_webpack_exports, __webpack_require__) => {
-
-//#!/usr/bin/env node
-
-const Promise = __webpack_require__(/*! bluebird */ "bluebird");
-const cli = __webpack_require__(/*! @vbarbarosh/node-helpers/src/cli */ "./src/cli.js");
-const now_human = __webpack_require__(/*! @vbarbarosh/node-helpers/src/now_human */ "./src/now_human.js");
-
-cli(main);
-
-async function main()
-{
-    process.on('SIGTERM', function () {
-        console.log(`[${now_human()}][ignore-sigterm] SIGTERM, ignoring...`);
-    });
-    process.on('SIGINT', function () {
-        console.log(`[${now_human()}][ignore-sigterm] SIGINT, ignoring...`);
-    });
-
-    for (let iter = 1, last = 100; iter <= last; ++iter) {
-        console.log(`[${now_human()}][ignore-sigterm] ${iter} of ${last}`);
-        await Promise.delay(100);
-    }
-}
-
-
-/***/ }),
-
-/***/ "./src/cli.js":
-/*!********************!*\
-  !*** ./src/cli.js ***!
-  \********************/
-/***/ ((module, __unused_webpack_exports, __webpack_require__) => {
-
-const ExitCodeError = __webpack_require__(/*! ./errors/ExitCodeError */ "./src/errors/ExitCodeError.js");
-const Promise = __webpack_require__(/*! bluebird */ "bluebird");
+/***/ "./src/clamp.js":
+/*!**********************!*\
+  !*** ./src/clamp.js ***!
+  \**********************/
+/***/ ((module) => {
 
-/**
- * Entry point for Node CLI apps
- */
-function cli(main, report = error => console.error(error))
+function clamp(min, max, value)
 {
-    // https://stackoverflow.com/a/46916601/1478566
-    const timer = setInterval(v => v, 1E9);
-
-    Promise.resolve(main()).then(resolve, reject);
-
-    function resolve() {
-        clearInterval(timer);
-    }
-    function reject(error) {
-        clearInterval(timer);
-        report(error);
-        if (error instanceof ExitCodeError) {
-            process.exit(error.exit_code);
-        }
-        else {
-            process.exit(1);
-        }
-    }
+    return Math.max(min, Math.min(max, value));
 }
 
-module.exports = cli;
+module.exports = clamp;
 
 
 /***/ }),
@@ -901,25 +882,6 @@ function date_is_leap_year(d)
 module.exports = date_is_leap_year;
 
 
-/***/ }),
-
-/***/ "./src/errors/ExitCodeError.js":
-/*!*************************************!*\
-  !*** ./src/errors/ExitCodeError.js ***!
-  \*************************************/
-/***/ ((module) => {
-
-class ExitCodeError extends Error
-{
-    constructor(exit_code, message = '') {
-        super(message);
-        this.exit_code = exit_code;
-    }
-}
-
-module.exports = ExitCodeError;
-
-
 /***/ }),
 
 /***/ "./src/factorize_ms.js":
@@ -1725,7 +1687,7 @@ const factorize_ms = __webpack_require__(/*! ./factorize_ms */ "./src/factorize_
 /**
  * Format milliseconds
  */
-function format_ms3(ms)
+function format_ms3(ms, include_zero_hours = false)
 {
     if (!ms) {
         ms = 0;
@@ -1733,7 +1695,7 @@ function format_ms3(ms)
 
     // 00:05.445
     const [h, m, s, xx] = factorize_ms(ms);
-    if (h) {
+    if (h || include_zero_hours) {
         return `0${h}:0${m}:0${s}.00${xx}`.replace(/0+(?=\d\d+[:.]|\d\d\d)/g, '');
     }
     return `0${m}:0${s}.00${xx}`.replace(/0+(?=\d\d+[:.]|\d\d\d)/g, '')
@@ -2219,99 +2181,6 @@ function math_lcm(a, b)
 module.exports = math_lcm;
 
 
-/***/ }),
-
-/***/ "./src/now_human.js":
-/*!**************************!*\
-  !*** ./src/now_human.js ***!
-  \**************************/
-/***/ ((module, __unused_webpack_exports, __webpack_require__) => {
-
-const format_date_human = __webpack_require__(/*! ./format_date_human */ "./src/format_date_human.js");
-
-function now_human()
-{
-    return format_date_human(new Date());
-}
-
-module.exports = now_human;
-
-
-/***/ }),
-
-/***/ "./src/pid_kill_grace.d/ignore-sigterm-for-10ms.js":
-/*!*********************************************************!*\
-  !*** ./src/pid_kill_grace.d/ignore-sigterm-for-10ms.js ***!
-  \*********************************************************/
-/***/ ((__unused_webpack_module, __unused_webpack_exports, __webpack_require__) => {
-
-//#!/usr/bin/env node
-
-const Promise = __webpack_require__(/*! bluebird */ "bluebird");
-const cli = __webpack_require__(/*! ../cli */ "./src/cli.js");
-const now_human = __webpack_require__(/*! ../now_human */ "./src/now_human.js");
-
-// Child ignores SIGTERM for 10 ms, but dies naturally before the grace loop ends
-
-cli(main);
-
-async function main()
-{
-    let timer;
-
-    process.on('SIGTERM', function () {
-        console.log(`[${now_human()}][ignore-sigterm-for-10ms] SIGTERM_ignoring...`);
-        timer ??= setTimeout(terminate, 10);
-    });
-    process.on('SIGINT', function () {
-        console.log(`[${now_human()}][ignore-sigterm-for-10ms] SIGINT_ignoring...`);
-    });
-
-    for (let iter = 1, last = 100; iter <= last; ++iter) {
-        console.log(`[${now_human()}][ignore-sigterm-for-10ms] ${iter} of ${last}`);
-        await Promise.delay(10);
-    }
-}
-
-function terminate()
-{
-    console.log(`[${now_human()}][ignore-sigterm-for-10ms] TERMINATE_AFTER_10MS`);
-    process.exit(0);
-}
-
-
-/***/ }),
-
-/***/ "./src/pid_kill_grace.d/ignore-sigterm.js":
-/*!************************************************!*\
-  !*** ./src/pid_kill_grace.d/ignore-sigterm.js ***!
-  \************************************************/
-/***/ ((__unused_webpack_module, __unused_webpack_exports, __webpack_require__) => {
-
-//#!/usr/bin/env node
-
-const Promise = __webpack_require__(/*! bluebird */ "bluebird");
-const cli = __webpack_require__(/*! ../cli */ "./src/cli.js");
-const now_human = __webpack_require__(/*! ../now_human */ "./src/now_human.js");
-
-cli(main);
-
-async function main()
-{
-    process.on('SIGTERM', function () {
-        console.log(`[${now_human()}][ignore-sigterm] SIGTERM_ignoring...`);
-    });
-    process.on('SIGINT', function () {
-        console.log(`[${now_human()}][ignore-sigterm] SIGINT_ignoring...`);
-    });
-
-    for (let iter = 1, last = 100; iter <= last; ++iter) {
-        console.log(`[${now_human()}][ignore-sigterm] ${iter} of ${last}`);
-        await Promise.delay(10);
-    }
-}
-
-
 /***/ }),
 
 /***/ "./src/plural.js":
@@ -2350,6 +2219,117 @@ function random_int(min, max)
 module.exports = random_int;
 
 
+/***/ }),
+
+/***/ "./src/round.js":
+/*!**********************!*\
+  !*** ./src/round.js ***!
+  \**********************/
+/***/ ((module) => {
+
+function round(value, precision = 1)
+{
+    if (precision === 0) {
+        return value;
+    }
+
+    const factor = 1 / precision;
+    const sign = Math.sign(value);
+
+    // Count decimal places for the cleanup (toFixed)
+    const exponent = get_decimal_places(precision);
+
+    // Small epsilon helps fix most floating point edge cases involving ties
+    const epsilon = 1e-12*sign;
+
+    // Scale → Nudge → Round → Unscale
+    const final = (Math.round(value*factor + epsilon) / factor);
+
+    // Cleanup trailing garbage such as: 34.038000000000004 → 34.038
+    return Number(final.toFixed(exponent));
+}
+
+function get_decimal_places(precision)
+{
+    if (Math.floor(precision) === precision) {
+        return 0;
+    }
+
+    // Scientific notation support: e.g., 1e-20
+    const e = precision.toExponential().split('e');
+    if (e.length > 1) {
+        return Math.abs(parseInt(e[1], 10));
+    }
+
+    // Normal decimal notation (e.g., 0.001)
+    return precision.toString().split('.')[1]?.length || 0;
+}
+
+// // round(34.037531, 0.001) -> 34.038000000000004
+// function round(value, precision = 1)
+// {
+//     return Math.round(value / precision) * precision;
+// }
+
+// // round(1.005, 0.01) -> 1
+// function round(value, precision = 1)
+// {
+//     const p = 1 / precision;
+//     return Math.round(value * p) / p;
+// }
+
+// function round(value, precision = 1)
+// {
+//     if (precision === 0) {
+//         return value;
+//     }
+//     const factor = 1 / precision;
+//     const epsilon = 1e-12 * Math.sign(value);
+//     return Number((Math.round((value * factor) + epsilon) / factor).toPrecision(15));
+// }
+
+// function round(value, precision = 1)
+// {
+//     if (precision === 0) {
+//         return value;
+//     }
+//
+//     const factor = 1 / precision;
+//
+//     // The exponent is critical for defining the precision of the cleanup
+//     const exponent = Math.max(0, String(precision).length - 2);
+//
+//     // 1. Calculate the scaled value.
+//     let scaled = value * factor;
+//
+//     // 2. Strategic Nudge: Add a tiny, signed epsilon (1e-12) to correct floating-point
+//     //    representation errors and force symmetric rounding (as Math.abs failed).
+//     const epsilon = 1e-12 * Math.sign(value);
+//
+//     // 3. Round the nudged value.
+//     const roundedScaled = Math.round(scaled + epsilon);
+//
+//     // 4. Unscale the value.
+//     const result = roundedScaled / factor;
+//
+//     // 5. CRITICAL FINAL STEP: Use .toFixed() with the required decimal places for cleanup.
+//     // This stabilizes the result against the strict equality checks, including
+//     // the safe integer boundary errors caused by the final division.
+//     return Number(result.toFixed(exponent));
+// }
+
+// 💎 The most precise solution, but - extra dependency.
+//
+// const Decimal = require('decimal.js');
+//
+// function round(value, precision = 1)
+// {
+//     return new Decimal(value).div(precision).round().times(precision).toNumber();
+// }
+
+module.exports = round;
+
+
 /***/ }),
 
 /***/ "./src/urlmod.js":
@@ -2499,14 +2479,14 @@ var __webpack_exports__ = {};
   \******************************/
 const ns = new URL(document.currentScript.src).searchParams.get('var') ?? 'h';
 if (typeof window[ns] !== 'undefined') {
-    console.log(`❌ @vbarbarosh/node-helpers@${"3.72.4"} was not injected — window.${ns} is already in use`);
+    console.log(`❌ @vbarbarosh/node-helpers@${"3.73.0"} was not injected — window.${ns} is already in use`);
 }
 else {
-    console.log(`🎉 @vbarbarosh/node-helpers@${"3.72.4"} successfully exposed as window.${ns}`);
+    console.log(`🎉 @vbarbarosh/node-helpers@${"3.73.0"} 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 = __webpack_require__("./src sync recursive \\b(array%7Cdate%7Chttp_delete%7Chttp_get_blob%7Chttp_get_buffer%7Chttp_get_json%7Chttp_get_utf8%7Chttp_head%7Chttp_patch_json%7Chttp_post_json%7Chttp_post_multipart%7Chttp_put_buffer%7Chttp_put_json%7Chttp_put_utf8%7Cidentity%7Cignore%7Cfcmp%7Cfilter%7Cformat%7Cplural%7Crandom_int%7Curlmod%7Cwaitcb)[^/]*(?<%21\\.test)\\.js$");
+    const require_tmp = __webpack_require__("./src sync recursive ^(?%21.*(cli-apps%7Cbrowser%7C\\.d)\\/).*\\b(array%7Cdate%7Chttp_delete%7Chttp_get_blob%7Chttp_get_buffer%7Chttp_get_json%7Chttp_get_utf8%7Chttp_head%7Chttp_patch_json%7Chttp_post_json%7Chttp_post_multipart%7Chttp_put_buffer%7Chttp_put_json%7Chttp_put_utf8%7Cidentity%7Cignore%7Cfcmp%7Cfilter%7Cformat%7Cplural%7Crandom_int%7Curlmod%7Cwaitcb)[^/]*(?<%21\\.test)\\.js$");
     require_tmp.keys().forEach(function (key) {
         const [, basename] = key.match(/([^/]+)\.js$/);
         window[ns][basename] = require_tmp(key);

package/package.json

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

package/src/array_chunk_jobs.js

@@ -0,0 +1,37 @@
+const clamp = require('./clamp');
+
+/**
+ * Split an array of jobs between up to `max_threads`, while trying to put at least
+ * `min_jobs_per_thread` items into each chunk.
+ *
+ * - If an array is empty → returns [].
+ * - If there are too few items to satisfy `min_items_per_chunk`, even for 1 chunk,
+ *   everything goes into a single chunk.
+ *
+ * Alternative names:
+ *   - array_chunk_balanced
+ *
+ * @param array
+ * @param max_threads
+ * @param min_jobs_per_thread
+ * @returns {*[]}
+ */
+function array_chunk_jobs(array = [], max_threads = 1, min_jobs_per_thread = 1)
+{
+    const total_threads = clamp(1, max_threads, Math.floor(array.length / min_jobs_per_thread));
+    const jobs_per_thread = Math.floor(array.length / total_threads);
+    let extra = array.length % total_threads;
+
+    const out = [];
+    for (let i = 0; i < array.length; ) {
+        const size = jobs_per_thread + (extra ? 1 : 0);
+        out.push(array.slice(i, i + size));
+        i += size;
+        if (extra) {
+            extra--;
+        }
+    }
+    return out;
+}
+
+module.exports = array_chunk_jobs;

package/src/array_chunk_jobs.test.js

@@ -0,0 +1,37 @@
+const array_chunk_jobs = require('./array_chunk_jobs');
+const assert = require('assert');
+
+describe('array_chunk_jobs', function () {
+    it('should handle basic input', function () {
+        assert.deepStrictEqual(array_chunk_jobs([1]), [[1]]);
+        assert.deepStrictEqual(array_chunk_jobs([1,2]), [[1,2]]);
+        assert.deepStrictEqual(array_chunk_jobs([1,2,3]), [[1,2,3]]);
+        assert.deepStrictEqual(array_chunk_jobs([1,2,3,4,5], 3, 2), [[1,2,3],[4,5]]);
+        assert.deepStrictEqual(array_chunk_jobs([1,2,3,4,5,6], 3, 2), [[1,2],[3,4],[5,6]]);
+        assert.deepStrictEqual(array_chunk_jobs([1,2,3,4,5,6,7], 3, 2), [[1,2,3],[4,5],[6,7]]);
+        assert.deepStrictEqual(array_chunk_jobs([1,2,3,4,5], 3, 3), [[1,2,3,4,5]]);
+        assert.deepStrictEqual(array_chunk_jobs([1,2,3,4,5,6], 3, 3), [[1,2,3],[4,5,6]]);
+        assert.deepStrictEqual(array_chunk_jobs([1,2,3,4,5,6,7], 3, 3), [[1,2,3,4],[5,6,7]]);
+        assert.deepStrictEqual(array_chunk_jobs([1,2,3,4,5,6,7,8], 3, 3), [[1,2,3,4],[5,6,7,8]]);
+    });
+    it('edge: If an array is empty → returns []', function () {
+        assert.deepStrictEqual(array_chunk_jobs([]), []);
+    });
+    it('edge: If there are too few items to satisfy `min_items_per_chunk`, even for 1 chunk, everything goes into a single chunk', function () {
+        assert.deepStrictEqual(array_chunk_jobs([1,2,3], 5, 5), [[1,2,3]]);
+    });
+    it('should never produce more chunks than max_threads', function () {
+        // 12 jobs, max 5 threads, min 2 jobs per thread
+        // Correct result MUST have exactly 5 chunks
+        assert.deepStrictEqual(
+            array_chunk_jobs([1,2,3,4,5,6,7,8,9,10,11,12], 5, 2),
+            [
+                [1,2,3],
+                [4,5,6],
+                [7,8],
+                [9,10],
+                [11,12]
+            ]
+        );
+    });
+});

package/src/array_fps.js

@@ -0,0 +1,20 @@
+const round = require('./round');
+
+const EPS = 0.00001;
+
+function array_fps(duration_sec, fps)
+{
+    const total_frames = Math.floor(duration_sec * fps);
+
+    if (total_frames <= 1) {
+        return [0];
+    }
+
+    const out = [];
+    for (let i = 0; i < total_frames; ++i) {
+        out.push(round((i / (total_frames - 1)) * (duration_sec - EPS), EPS));
+    }
+    return out;
+}
+
+module.exports = array_fps;

package/src/array_fps.test.js

@@ -0,0 +1,11 @@
+const array_fps = require('./array_fps');
+const assert = require('assert');
+
+describe('array_fps', function () {
+    it('should handle basic input', function () {
+        assert.deepStrictEqual(array_fps(1, 1), [0]);
+        assert.deepStrictEqual(array_fps(1, 2), [0, 0.99999]);
+        assert.deepStrictEqual(array_fps(1, 3), [0, 0.49999, 0.99999]);
+        assert.deepStrictEqual(array_fps(1, 4), [0, 0.33333, 0.66666, 0.99999]);
+    });
+});

package/src/browser/index.js

@@ -7,7 +7,7 @@ else {
     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$/);
+    const require_tmp = require.context('..', true, /^(?!.*(cli-apps|browser|\.d)\/).*\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/clamp.js

@@ -0,0 +1,6 @@
+function clamp(min, max, value)
+{
+    return Math.max(min, Math.min(max, value));
+}
+
+module.exports = clamp;

package/src/cli-apps/watchdog.d/quick-exit-after-2-pings.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+
+const Promise = require('bluebird');
+const cli = require('../../cli');
+const ping_socket = require('../../ping_socket');
+
+cli(main);
+
+async function main()
+{
+    for (let iter = 1, last = 2; iter <= last; ++iter) {
+        await ping_socket(process.env.WATCHDOG_SOCKET);
+        await Promise.delay(10);
+    }
+}

package/src/cli-apps/watchdog.d/quick-hang-after-1-ping.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+
+const Promise = require('bluebird');
+const cli = require('../../cli');
+const ping_socket = require('../../ping_socket');
+
+cli(main);
+
+async function main()
+{
+    await ping_socket(process.env.WATCHDOG_SOCKET);
+    while (true) {
+        await Promise.delay(1000);
+    }
+}

package/src/cli-apps/watchdog.js

@@ -15,6 +15,7 @@ const shell_spawn = require('../shell_spawn');
 
 const STARTED_AT = Date.now();
 const LOGS_ROOT_UID = cuid.createId();
+const ARGS = process.argv.slice(2);
 
 let PING_COUNTER = 0;
 
@@ -35,18 +36,17 @@ cli(main, report);
 
 function report(error)
 {
-    log(`[watchdog_end_error] ${render_stats()} | ${error.message}`);
+    log(`[watchdog_end_error] ${render_stats()} | ${error.message} | ${ARGS.join(' ')}`);
 }
 
 async function main()
 {
-    const args = process.argv.slice(2);
-    if (!args.length) {
+    if (!ARGS.length) {
         usage();
         process.exit(1);
     }
 
-    switch (args[0]) {
+    switch (ARGS[0]) {
     case '-v':
     case '--version':
         version();
@@ -56,18 +56,20 @@ async function main()
 
     log(`[watchdog_begin] v${pkg.version}`);
 
-    const WATCHDOG_INTERVAL = make(process.env.WATCHDOG_INTERVAL, {type: 'int', min: 1000, default: 5000});
+    const WATCHDOG_INTERVAL = process.env.__TESTING__
+        ? make(process.env.WATCHDOG_INTERVAL, {type: 'int', min: 1, default: 5000})
+        : make(process.env.WATCHDOG_INTERVAL, {type: 'int', min: 1000, default: 5000});
     const heartbeat_server = new HeartbeatServer(WATCHDOG_INTERVAL);
     const WATCHDOG_SOCKET = heartbeat_server.socket_path;
     heartbeat_server.on('heartbeat', () => log(`[watchdog_ping] ❤️ ${render_stats(++PING_COUNTER)}`))
     heartbeat_server.on('warning', error => log(`[watchdog_warn] ⚠️ ${error}`))
 
     try {
-        log(`[watchdog_args] ${args.join(' ')}`);
+        log(`[watchdog_args] ${ARGS.join(' ')}`);
         log(`[watchdog_interval] ${WATCHDOG_INTERVAL}`);
         log(`[watchdog_socket_path] ${heartbeat_server.socket_path}`);
         const env = {...process.env, WATCHDOG_INTERVAL, WATCHDOG_SOCKET};
-        const proc = await shell_spawn(args, {stdio: 'inherit', env, detached: true}).init();
+        const proc = await shell_spawn(ARGS, {stdio: 'inherit', env, detached: true}).init();
         const pgid = proc.pid; // group id == leader pid
 
         const signal = new Promise(function (resolve, reject) {
@@ -98,7 +100,7 @@ async function main()
         await Promise.resolve(heartbeat_server.dispose()).timeout(1000);
     }
 
-    log(`[watchdog_end_ok] ${render_stats()}`);
+    log(`[watchdog_end_ok] ${render_stats()} | ${ARGS.join(' ')}`);
     process.exit(0);
 }
 
@@ -106,10 +108,10 @@ function log(s)
 {
     const ss = JSON.stringify(s).slice(1, -1).replaceAll('\\"', '"');
     if (ss[0] === '[') {
-        console.log(`[${LOGS_ROOT_UID}][+${format_ms3(Date.now() - STARTED_AT)}]${ss}`);
+        console.log(`[${LOGS_ROOT_UID}][${format_ms3(Date.now() - STARTED_AT, true)}]${ss}`);
     }
     else {
-        console.log(`[${LOGS_ROOT_UID}][+${format_ms3(Date.now() - STARTED_AT)}] ${ss}`);
+        console.log(`[${LOGS_ROOT_UID}][${format_ms3(Date.now() - STARTED_AT, true)}] ${ss}`);
     }
 }
 

package/src/cli-apps/watchdog.test.js

@@ -1,7 +1,48 @@
 const assert = require('assert');
+const pid_exists = require('../pid_exists');
+const shell_spawn = require('../shell_spawn');
+const stream = require('stream');
+const stream_each = require('../stream_each');
+const stream_lines = require('../stream_lines');
 
 // watchdog true -> race condition; true exists too quickly; bug in shell_spawn
 
-describe.skip('watchdog', function () {
-
+describe('watchdog', function () {
+    this.timeout(1000);
+    it('Happy Path', async function () {
+        const env = {...process.env, WATCHDOG_INTERVAL: 100, __TESTING__: 1};
+        const proc = shell_spawn([`${__dirname}/watchdog.js`, `${__dirname}/watchdog.d/quick-exit-after-2-pings.js`], {env});
+        try {
+            const stdout = [];
+            await Promise.all([
+                stream.promises.pipeline(proc.stdout, stream_lines(), stream_each(v => stdout.push(v))),
+                proc.promise(),
+            ]);
+            assert.strictEqual(stdout.filter(v => v.includes('[watchdog_ping]')).length, 2);
+            assert.strictEqual(stdout.filter(v => v.includes('[watchdog_end_ok] pings=2')).length, 1);
+        }
+        finally {
+            if (pid_exists(proc.pid)) {
+                process.kill(proc.pid, 'SIGTERM');
+            }
+        }
+    });
+    it('Hang after 1 ping', async function () {
+        const env = {...process.env, WATCHDOG_INTERVAL: 100, __TESTING__: 1};
+        const proc = shell_spawn([`${__dirname}/watchdog.js`, `${__dirname}/watchdog.d/quick-hang-after-1-ping.js`], {env});
+        const stdout = [];
+        try {
+            await Promise.all([
+                stream.promises.pipeline(proc.stdout, stream_lines(), stream_each(v => stdout.push(v))),
+                assert.rejects(proc.promise().timeout(500), {message: 'Process terminated with code 124 and signal null'}),
+            ]);
+            assert.strictEqual(stdout.filter(v => v.includes('[watchdog_ping]')).length, 1);
+            assert.strictEqual(stdout.filter(v => v.includes('[watchdog_end_error] pings=1 | No heartbeat for the last 100ms')).length, 1);
+        }
+        finally {
+            if (pid_exists(proc.pid)) {
+                process.kill(proc.pid, 'SIGTERM');
+            }
+        }
+    });
 });

package/src/format_ms3.js

@@ -3,7 +3,7 @@ const factorize_ms = require('./factorize_ms');
 /**
  * Format milliseconds
  */
-function format_ms3(ms)
+function format_ms3(ms, include_zero_hours = false)
 {
     if (!ms) {
         ms = 0;
@@ -11,7 +11,7 @@ function format_ms3(ms)
 
     // 00:05.445
     const [h, m, s, xx] = factorize_ms(ms);
-    if (h) {
+    if (h || include_zero_hours) {
         return `0${h}:0${m}:0${s}.00${xx}`.replace(/0+(?=\d\d+[:.]|\d\d\d)/g, '');
     }
     return `0${m}:0${s}.00${xx}`.replace(/0+(?=\d\d+[:.]|\d\d\d)/g, '')

package/src/fs_lsr.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_walk
+ */
 async function fs_lsr(pathname = '.')
 {
     const fi = await fs_fi(pathname);

package/src/fs_walk.js

@@ -0,0 +1,40 @@
+const fs_lstat = require('./fs_lstat');
+const fs_path_join = require('./fs_path_join');
+const fs_readdir = require('./fs_readdir');
+const ignore = require('./ignore');
+
+async function fs_walk({path = '.', user_friendly_status = ignore, error_handler = error_handler, signal})
+{
+    const out = [];
+    const queue = [path];
+    while (queue.length) {
+        if (signal) {
+            signal.throwIfAborted();
+        }
+        try {
+            const current_path = queue.pop();
+            user_friendly_status(`Reading ${current_path}`);
+            const lstat = await fs_lstat(current_path);
+            lstat.path = current_path;
+            out.push(lstat);
+            if (lstat.isDirectory()) {
+                if (current_path === '/dev' || current_path === '/proc') {
+                    continue;
+                }
+                const basenames = await fs_readdir(current_path);
+                basenames.forEach(v => queue.push(fs_path_join(current_path, v)));
+            }
+        }
+        catch (error) {
+            error_handler(error);
+        }
+    }
+    return out;
+}
+
+function error_handler(error)
+{
+    console.log(`⚠️ ${error.message}`);
+}
+
+module.exports = fs_walk;

package/src/round.js

@@ -0,0 +1,101 @@
+function round(value, precision = 1)
+{
+    if (precision === 0) {
+        return value;
+    }
+
+    const factor = 1 / precision;
+    const sign = Math.sign(value);
+
+    // Count decimal places for the cleanup (toFixed)
+    const exponent = get_decimal_places(precision);
+
+    // Small epsilon helps fix most floating point edge cases involving ties
+    const epsilon = 1e-12*sign;
+
+    // Scale → Nudge → Round → Unscale
+    const final = (Math.round(value*factor + epsilon) / factor);
+
+    // Cleanup trailing garbage such as: 34.038000000000004 → 34.038
+    return Number(final.toFixed(exponent));
+}
+
+function get_decimal_places(precision)
+{
+    if (Math.floor(precision) === precision) {
+        return 0;
+    }
+
+    // Scientific notation support: e.g., 1e-20
+    const e = precision.toExponential().split('e');
+    if (e.length > 1) {
+        return Math.abs(parseInt(e[1], 10));
+    }
+
+    // Normal decimal notation (e.g., 0.001)
+    return precision.toString().split('.')[1]?.length || 0;
+}
+
+// // round(34.037531, 0.001) -> 34.038000000000004
+// function round(value, precision = 1)
+// {
+//     return Math.round(value / precision) * precision;
+// }
+
+// // round(1.005, 0.01) -> 1
+// function round(value, precision = 1)
+// {
+//     const p = 1 / precision;
+//     return Math.round(value * p) / p;
+// }
+
+// function round(value, precision = 1)
+// {
+//     if (precision === 0) {
+//         return value;
+//     }
+//     const factor = 1 / precision;
+//     const epsilon = 1e-12 * Math.sign(value);
+//     return Number((Math.round((value * factor) + epsilon) / factor).toPrecision(15));
+// }
+
+// function round(value, precision = 1)
+// {
+//     if (precision === 0) {
+//         return value;
+//     }
+//
+//     const factor = 1 / precision;
+//
+//     // The exponent is critical for defining the precision of the cleanup
+//     const exponent = Math.max(0, String(precision).length - 2);
+//
+//     // 1. Calculate the scaled value.
+//     let scaled = value * factor;
+//
+//     // 2. Strategic Nudge: Add a tiny, signed epsilon (1e-12) to correct floating-point
+//     //    representation errors and force symmetric rounding (as Math.abs failed).
+//     const epsilon = 1e-12 * Math.sign(value);
+//
+//     // 3. Round the nudged value.
+//     const roundedScaled = Math.round(scaled + epsilon);
+//
+//     // 4. Unscale the value.
+//     const result = roundedScaled / factor;
+//
+//     // 5. CRITICAL FINAL STEP: Use .toFixed() with the required decimal places for cleanup.
+//     // This stabilizes the result against the strict equality checks, including
+//     // the safe integer boundary errors caused by the final division.
+//     return Number(result.toFixed(exponent));
+// }
+
+// 💎 The most precise solution, but - extra dependency.
+//
+// const Decimal = require('decimal.js');
+//
+// function round(value, precision = 1)
+// {
+//     return new Decimal(value).div(precision).round().times(precision).toNumber();
+// }
+
+module.exports = round;

package/src/round.test.js

@@ -0,0 +1,56 @@
+const assert = require('assert');
+const round = require('./round');
+
+const items = [
+    [34, 25, 25],
+    [37.5, 25, 50],
+    [34.037531, 0.001, 34.038],
+    [1.005, 0.01, 1.01],
+    [0.99999, 0.00001, 0.99999],
+
+    // Synthetic cases generated by DeepSeek
+    [1.005, 0.001, 1.005],        // More precise rounding
+    [1.005, 0.1, 1.0],            // Less precise rounding
+    [1.015, 0.01, 1.02],          // Another edge case with 5
+    [1.025, 0.01, 1.03],          // Yet another edge case
+    [0.5, 1, 1],                  // Round to nearest integer
+    [0.4, 1, 0],                  // Round down to integer
+    [123.456, 0.01, 123.46],      // Standard decimal rounding
+    [123.456, 0.1, 123.5],        // Different precision
+    [123.456, 1, 123],            // Round to whole number
+    [123.456, 10, 120],           // Round to tens
+    [123.456, 100, 100],          // Round to hundreds
+    [0, 0.01, 0],                 // Zero value
+    [-1.005, 0.01, -1.01],        // Negative numbers
+    [-1.015, 0.01, -1.02],        // Negative edge case
+    [-37.5, 25, -50],             // Negative with integer precision
+    [1.2345e-5, 1e-6, 0.000012],  // Very small numbers
+    [999.999, 0.001, 999.999],    // Rounding that causes carry-over
+    [0.0000000000001, 0.01, 0],   // Extremely small number
+    [Number.MAX_SAFE_INTEGER, 1000, 9007199254741000], // Large numbers
+
+    [0.005, 0.01, 0.01],
+    [-1.5, 1, -2],                          // Symmetric negative rounding (Math.abs is critical here)
+    [-0.5, 1, -1],                          // Symmetric negative rounding for half
+    [123456789123.45, 1000, 123456789000],  // Testing very large numbers
+    [1.2345e-20, 1e-20, 1e-20],             // Testing very small numbers
+    [1.0000000000000001, 0.0000000000000001, 1.0000000000000000], // Testing rounding near Number.EPSILON range
+
+    [9007199254740992, 1, 9007199254740992],
+    [9007199254740991.5, 1, 9007199254740992],
+    [Number.MIN_SAFE_INTEGER, 1, Number.MIN_SAFE_INTEGER],
+    [Number.MAX_SAFE_INTEGER, 1, Number.MAX_SAFE_INTEGER],
+
+    // Out of scope of standard JS
+    // [0.004999999999999999, 0.01, 0.0],
+    // [Number.MIN_SAFE_INTEGER, 0.1, Number.MIN_SAFE_INTEGER],
+    // [Number.MAX_SAFE_INTEGER, 0.1, Number.MAX_SAFE_INTEGER],
+];
+
+describe('round', function () {
+    items.forEach(function ([value, precision, expected],) {
+        it(`${value} [${precision}] → ${expected}`, function () {
+            assert.deepStrictEqual(round(value, precision), expected);
+        });
+    });
+});

package/src/shell.md

@@ -0,0 +1,16 @@
+Basic helper for running external commands via `execFile`.
+
+- Fails if the command exits with non-zero code.
+- Fails if anything is printed to `stderr`.
+- Resolves with `stdout` (string), exactly as produced.
+
+## Signature
+
+```
+shell(args, options) → Promise<string>
+```
+
+## Notes
+
+- `args[0]` is the executable; `args[1..]` are arguments.
+- Suitable for commands that produce clean stdout and no warnings.

package/src/shell_json.md

@@ -0,0 +1,12 @@
+Basic helper for running external commands via `execFile`, and parse result by JSON.parse.
+
+- Fails if the command exits with non-zero code.
+- Fails if anything is printed to `stderr`.
+- Fails if stdout is not valid JSON.
+- Resolves with parsed JSON value.
+
+## Signature
+
+```
+shell_json(args, options) → Promise<any>
+```

package/src/shell_lines.md

@@ -0,0 +1,12 @@
+Basic helper for running external commands via `execFile`, and splits stdout into lines.
+
+- Fails if the command exits with non-zero code.
+- Fails if anything is printed to `stderr`.
+- Strips trailing newline(s).
+- Returns array of lines.
+
+## Signature
+
+```
+shell_lines(args, options) → Promise<string[]>
+```

package/src/shell_spawn.js

@@ -1,6 +1,7 @@
 const ExitCodeError = require('./errors/ExitCodeError');
 const Promise = require('bluebird');
 const child_process = require('child_process');
+const ignore = require('./ignore');
 
 // 📕 Notes by ChatGPT:
 // If the child is killed by a signal (e.g. SIGKILL from outside),
@@ -20,45 +21,44 @@ const child_process = require('child_process');
 // >     }
 // > }
 
-// ⚠️ Both .init and .promise are targets for race conditions!
 function shell_spawn(args, options)
 {
-    let init, promise;
+    const init = {};
+    const run = {};
+
+    init.promise = new Promise(function (resolve, reject) {
+        init.resolve = resolve;
+        init.reject = reject;
+    });
+    run.promise = new Promise(function (resolve, reject) {
+        run.resolve = resolve;
+        run.reject = reject;
+    });
+
     const out = child_process.spawn(args[0], args.slice(1), options);
-    out.init = function () {
-        return init = init || new Promise(function (resolve, reject) {
-            out.once('error', init_error);
-            out.once('spawn', init_spawn);
-            function init_error(error) {
-                out.off('spawn', init_spawn);
-                reject(error);
-            }
-            function init_spawn() {
-                out.off('error', init_error);
-                resolve(out);
-            }
-        });
-    };
-    out.promise = function () {
-        return promise = promise || new Promise(function (resolve, reject) {
-            out.once('error', promise_error);
-            out.once('exit', promise_exit);
-            function promise_error(error) {
-                out.off('exit', promise_exit);
-                reject(error);
-            }
-            function promise_exit(code, signal) {
-                out.off('error', promise_error);
-                if (code === 0) {
-                    resolve();
-                }
-                else {
-                    reject(new ExitCodeError(code || 128, `Process terminated with code ${code} and signal ${signal}`));
-                }
-            }
-        });
-    };
+    out.once('error', onerror);
+    out.once('spawn', onspawn);
+    out.once('exit', onexit);
+    out.init = () => init.promise;
+    out.promise = () => run.promise;
     return out;
+
+    function onerror(error) {
+        init.reject(error);
+        run.reject(error);
+    }
+    function onexit(code, signal) {
+        if (code === 0) {
+            run.resolve();
+        }
+        else {
+            run.reject(new ExitCodeError(code || 128, `Process terminated with code ${code} and signal ${signal}`));
+        }
+    }
+    function onspawn() {
+        init.resolve(out);
+        init.reject = ignore;
+    }
 }
 
 module.exports = shell_spawn;

package/src/shell_spawn.md

@@ -0,0 +1,25 @@
+Spawn-based helper for long-running or streaming commands.
+
+Provides two promises:
+
+- `proc.init()` — resolves when the child emits `spawn`.
+- `proc.promise()` — resolves when the child exits with code 0.
+
+## Failure semantics
+
+- Rejects if `error` event occurs.
+- Rejects if exit code is non-zero.
+- If child dies by signal, treated as non-zero exit (uses exitCode = 128).
+
+## Signature
+
+```
+const proc = shell_spawn(args, options)
+proc.init() → Promise<ChildProcess>
+proc.promise() → Promise<void>
+```
+
+## Notes
+
+- Output is streamed (not buffered).
+- Use when you need live stdout/stderr or long-running jobs.

package/src/shell_spawn.test.js

@@ -3,7 +3,7 @@ const assert = require('assert');
 const pid_exists = require('./pid_exists');
 const shell_spawn = require('./shell_spawn');
 
-describe.skip('shell_spawn', function () {
+describe('shell_spawn', function () {
     describe('Happy Path', function () {
         it('basic', async function () {
             await shell_spawn(['true']).promise().timeout(100);
@@ -20,4 +20,11 @@ describe.skip('shell_spawn', function () {
         assert(!pid_exists(proc.pid));
         await proc.promise().timeout(100);
     });
+    it('should throw when init fails', async function () {
+        await assert.rejects(shell_spawn(['ggg111']).init(), /^Error: spawn ggg111 ENOENT$/);
+    });
+    it('should throw when process exists with non zero code', async function () {
+        const proc = await shell_spawn(['false']).init();
+        await assert.rejects(proc.promise().timeout(100), /^Error: Process terminated with code 1 and signal null$/);
+    });
 });

package/src/shell_stdall.md

@@ -0,0 +1,11 @@
+Runs a command via `execFile` and returns both stdout and stderr.
+
+- Rejects only on exec error.
+- Resolves with `{stdout, stderr}`.
+- Does NOT treat stderr output as failure.
+
+## Signature
+
+```
+shell_stdall(args, options) → Promise<{stdout: string, stderr: string}>
+```

package/src/shell_thru.md

@@ -0,0 +1,10 @@
+Convenience wrapper over `shell_spawn` with `stdio: 'inherit'`.
+
+- Child stdout/stderr are streamed directly to parent terminal.
+- Supports `proc.init()` and `proc.promise()` like `shell_spawn`.
+
+## Signature
+
+```
+shell_thru(args, options) → ChildProcess
+```