@vbarbarosh/node-helpers 3.72.5 → 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.5/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

@@ -80,6 +80,8 @@ function serializer(replacer, cycleReplacer) {
 
 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",
@@ -201,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":
@@ -644,6 +723,22 @@ function array_unique_last(array, fn = identity)
 module.exports = array_unique_last;
 
 
+/***/ }),
+
+/***/ "./src/clamp.js":
+/*!**********************!*\
+  !*** ./src/clamp.js ***!
+  \**********************/
+/***/ ((module) => {
+
+function clamp(min, max, value)
+{
+    return Math.max(min, Math.min(max, value));
+}
+
+module.exports = clamp;
+
+
 /***/ }),
 
 /***/ "./src/date_add_hours.js":
@@ -2124,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":
@@ -2273,10 +2479,10 @@ 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.5"} 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.5"} 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

package/package.json

@@ -2,7 +2,7 @@
     "author": "Vladimir Barbarosh <vladimir.barbarosh@gmail.com>",
     "license": "MIT",
     "name": "@vbarbarosh/node-helpers",
-    "version": "3.72.5",
+    "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/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

@@ -1,3 +1,41 @@
+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)
 // {
@@ -11,14 +49,53 @@
 //     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 Math.round((value * factor) + epsilon) / factor;
-}
+// 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

@@ -6,6 +6,7 @@ const items = [
     [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
@@ -27,6 +28,23 @@ const items = [
     [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 () {