@vbarbarosh/node-helpers 3.72.5 → 3.74.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.74.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_balanced.js": "./src/array_chunk_balanced.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,88 @@ function array_chunk(array = [], limit = 1)
 module.exports = array_chunk;
 
 
+/***/ }),
+
+/***/ "./src/array_chunk_balanced.js":
+/*!*************************************!*\
+  !*** ./src/array_chunk_balanced.js ***!
+  \*************************************/
+/***/ ((module, __unused_webpack_exports, __webpack_require__) => {
+
+const clamp = __webpack_require__(/*! ./clamp */ "./src/clamp.js");
+
+/**
+ * Split an array into up to `max_chunks` balanced chunks, while ensuring that
+ * each chunk contains at least `min_items_per_chunk` items (when possible).
+ *
+ * The function distributes items as evenly as possible:
+ * - Chunk sizes differ by at most 1 item.
+ * - The number of chunks never exceeds `max_chunks`.
+ *
+ * Originally designed for distributing workload across threads
+ * (e.g. `array_chunk_balanced(jobs, max_threads, min_jobs_per_thread)`).
+ *
+ * Edge cases:
+ * - If the input array is empty → returns [].
+ * - If there are too few items to satisfy `min_items_per_chunk`, even for a single
+ *   chunk, all items are placed into one chunk.
+ *
+ * @param {Array} array
+ * @param {number} max_chunks
+ * @param {number} min_items_per_chunk
+ * @returns {Array<Array>}
+ */
+function array_chunk_balanced(array = [], max_chunks = 1, min_items_per_chunk = 1)
+{
+    const total_chunks = clamp(1, max_chunks, Math.floor(array.length / min_items_per_chunk));
+    const items_per_chunk = Math.floor(array.length / total_chunks);
+    let extra = array.length % total_chunks;
+
+    const out = [];
+    for (let i = 0; i < array.length; ) {
+        const size = items_per_chunk + (extra ? 1 : 0);
+        out.push(array.slice(i, i + size));
+        i += size;
+        if (extra) {
+            extra--;
+        }
+    }
+    return out;
+}
+
+module.exports = array_chunk_balanced;
+
+
+/***/ }),
+
+/***/ "./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 +728,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 +2224,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 +2484,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.74.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.74.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.74.0",
     "description": "A set of helpers for JavaScript/Node.js",
     "unpkg": "dist/browser.js",
     "jsdelivr": "dist/browser.js",

package/src/array_chunk_balanced.js

@@ -0,0 +1,42 @@
+const clamp = require('./clamp');
+
+/**
+ * Split an array into up to `max_chunks` balanced chunks, while ensuring that
+ * each chunk contains at least `min_items_per_chunk` items (when possible).
+ *
+ * The function distributes items as evenly as possible:
+ * - Chunk sizes differ by at most 1 item.
+ * - The number of chunks never exceeds `max_chunks`.
+ *
+ * Originally designed for distributing workload across threads
+ * (e.g. `array_chunk_balanced(jobs, max_threads, min_jobs_per_thread)`).
+ *
+ * Edge cases:
+ * - If the input array is empty → returns [].
+ * - If there are too few items to satisfy `min_items_per_chunk`, even for a single
+ *   chunk, all items are placed into one chunk.
+ *
+ * @param {Array} array
+ * @param {number} max_chunks
+ * @param {number} min_items_per_chunk
+ * @returns {Array<Array>}
+ */
+function array_chunk_balanced(array = [], max_chunks = 1, min_items_per_chunk = 1)
+{
+    const total_chunks = clamp(1, max_chunks, Math.floor(array.length / min_items_per_chunk));
+    const items_per_chunk = Math.floor(array.length / total_chunks);
+    let extra = array.length % total_chunks;
+
+    const out = [];
+    for (let i = 0; i < array.length; ) {
+        const size = items_per_chunk + (extra ? 1 : 0);
+        out.push(array.slice(i, i + size));
+        i += size;
+        if (extra) {
+            extra--;
+        }
+    }
+    return out;
+}
+
+module.exports = array_chunk_balanced;

package/src/array_chunk_balanced.test.js

@@ -0,0 +1,37 @@
+const array_chunk_balanced = require('./array_chunk_balanced');
+const assert = require('assert');
+
+describe('array_chunk_balanced', function () {
+    it('should handle basic input', function () {
+        assert.deepStrictEqual(array_chunk_balanced([1]), [[1]]);
+        assert.deepStrictEqual(array_chunk_balanced([1,2]), [[1,2]]);
+        assert.deepStrictEqual(array_chunk_balanced([1,2,3]), [[1,2,3]]);
+        assert.deepStrictEqual(array_chunk_balanced([1,2,3,4,5], 3, 2), [[1,2,3],[4,5]]);
+        assert.deepStrictEqual(array_chunk_balanced([1,2,3,4,5,6], 3, 2), [[1,2],[3,4],[5,6]]);
+        assert.deepStrictEqual(array_chunk_balanced([1,2,3,4,5,6,7], 3, 2), [[1,2,3],[4,5],[6,7]]);
+        assert.deepStrictEqual(array_chunk_balanced([1,2,3,4,5], 3, 3), [[1,2,3,4,5]]);
+        assert.deepStrictEqual(array_chunk_balanced([1,2,3,4,5,6], 3, 3), [[1,2,3],[4,5,6]]);
+        assert.deepStrictEqual(array_chunk_balanced([1,2,3,4,5,6,7], 3, 3), [[1,2,3,4],[5,6,7]]);
+        assert.deepStrictEqual(array_chunk_balanced([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_balanced([]), []);
+    });
+    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_balanced([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_balanced([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,72 @@
+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]);
+        assert.deepStrictEqual(array_fps(5, 20), [
+            0,       0.0505,  0.10101, 0.15151, 0.20202, 0.25252, 0.30303, 0.35353, 0.40404, 0.45454,
+            0.50505, 0.55555, 0.60606, 0.65656, 0.70707, 0.75757, 0.80808, 0.85858, 0.90909, 0.95959,
+            1.0101,  1.0606,  1.11111, 1.16161, 1.21212, 1.26262, 1.31313, 1.36363, 1.41414, 1.46464,
+            1.51515, 1.56565, 1.61616, 1.66666, 1.71717, 1.76767, 1.81818, 1.86868, 1.91919, 1.96969,
+            2.0202,  2.0707,  2.12121, 2.17171, 2.22222, 2.27272, 2.32323, 2.37373, 2.42424, 2.47474,
+            2.52525, 2.57575, 2.62626, 2.67676, 2.72727, 2.77777, 2.82828, 2.87878, 2.92929, 2.97979,
+            3.0303,  3.0808,  3.13131, 3.18181, 3.23232, 3.28282, 3.33333, 3.38383, 3.43434, 3.48484,
+            3.53535, 3.58585, 3.63636, 3.68686, 3.73737, 3.78787, 3.83838, 3.88888, 3.93939, 3.98989,
+            4.0404,  4.0909,  4.14141, 4.19191, 4.24242, 4.29292, 4.34343, 4.39393, 4.44444, 4.49494,
+            4.54545, 4.59595, 4.64646, 4.69696, 4.74747, 4.79797, 4.84848, 4.89898, 4.94949, 4.99999,
+        ]);
+        assert.deepStrictEqual(array_fps(5, 30), [
+            0,       0.03356, 0.06711, 0.10067, 0.13423, 0.16778, 0.20134, 0.2349,  0.26846, 0.30201,
+            0.33557, 0.36913, 0.40268, 0.43624, 0.4698,  0.50335, 0.53691, 0.57047, 0.60403, 0.63758,
+            0.67114, 0.7047,  0.73825, 0.77181, 0.80537, 0.83892, 0.87248, 0.90604, 0.9396,  0.97315,
+            1.00671, 1.04027, 1.07382, 1.10738, 1.14094, 1.17449, 1.20805, 1.24161, 1.27517, 1.30872,
+            1.34228, 1.37584, 1.40939, 1.44295, 1.47651, 1.51006, 1.54362, 1.57718, 1.61074, 1.64429,
+            1.67785, 1.71141, 1.74496, 1.77852, 1.81208, 1.84563, 1.87919, 1.91275, 1.9463,  1.97986,
+            2.01342, 2.04698, 2.08053, 2.11409, 2.14765, 2.1812,  2.21476, 2.24832, 2.28187, 2.31543,
+            2.34899, 2.38255, 2.4161,  2.44966, 2.48322, 2.51677, 2.55033, 2.58389, 2.61744, 2.651,
+            2.68456, 2.71812, 2.75167, 2.78523, 2.81879, 2.85234, 2.8859,  2.91946, 2.95301, 2.98657,
+            3.02013, 3.05369, 3.08724, 3.1208,  3.15436, 3.18791, 3.22147, 3.25503, 3.28858, 3.32214,
+            3.3557,  3.38925, 3.42281, 3.45637, 3.48993, 3.52348, 3.55704, 3.5906,  3.62415, 3.65771,
+            3.69127, 3.72482, 3.75838, 3.79194, 3.8255,  3.85905, 3.89261, 3.92617, 3.95972, 3.99328,
+            4.02684, 4.06039, 4.09395, 4.12751, 4.16107, 4.19462, 4.22818, 4.26174, 4.29529, 4.32885,
+            4.36241, 4.39596, 4.42952, 4.46308, 4.49664, 4.53019, 4.56375, 4.59731, 4.63086, 4.66442,
+            4.69798, 4.73153, 4.76509, 4.79865, 4.83221, 4.86576, 4.89932, 4.93288, 4.96643, 4.99999,
+        ]);
+        assert.deepStrictEqual(array_fps(5, 60), [
+            0,       0.01672, 0.03344, 0.05017, 0.06689, 0.08361, 0.10033, 0.11706, 0.13378, 0.1505,
+            0.16722, 0.18395, 0.20067, 0.21739, 0.23411, 0.25084, 0.26756, 0.28428, 0.301,   0.31773,
+            0.33445, 0.35117, 0.36789, 0.38461, 0.40134, 0.41806, 0.43478, 0.4515,  0.46823, 0.48495,
+            0.50167, 0.51839, 0.53512, 0.55184, 0.56856, 0.58528, 0.60201, 0.61873, 0.63545, 0.65217,
+            0.66889, 0.68562, 0.70234, 0.71906, 0.73578, 0.75251, 0.76923, 0.78595, 0.80267, 0.8194,
+            0.83612, 0.85284, 0.86956, 0.88629, 0.90301, 0.91973, 0.93645, 0.95318, 0.9699,  0.98662,
+            1.00334, 1.02006, 1.03679, 1.05351, 1.07023, 1.08695, 1.10368, 1.1204,  1.13712, 1.15384,
+            1.17057, 1.18729, 1.20401, 1.22073, 1.23746, 1.25418, 1.2709,  1.28762, 1.30435, 1.32107,
+            1.33779, 1.35451, 1.37123, 1.38796, 1.40468, 1.4214,  1.43812, 1.45485, 1.47157, 1.48829,
+            1.50501, 1.52174, 1.53846, 1.55518, 1.5719,  1.58863, 1.60535, 1.62207, 1.63879, 1.65552,
+            1.67224, 1.68896, 1.70568, 1.7224,  1.73913, 1.75585, 1.77257, 1.78929, 1.80602, 1.82274,
+            1.83946, 1.85618, 1.87291, 1.88963, 1.90635, 1.92307, 1.9398,  1.95652, 1.97324, 1.98996,
+            2.00668, 2.02341, 2.04013, 2.05685, 2.07357, 2.0903,  2.10702, 2.12374, 2.14046, 2.15719,
+            2.17391, 2.19063, 2.20735, 2.22408, 2.2408,  2.25752, 2.27424, 2.29097, 2.30769, 2.32441,
+            2.34113, 2.35785, 2.37458, 2.3913,  2.40802, 2.42474, 2.44147, 2.45819, 2.47491, 2.49163,
+            2.50836, 2.52508, 2.5418,  2.55852, 2.57525, 2.59197, 2.60869, 2.62541, 2.64214, 2.65886,
+            2.67558, 2.6923,  2.70902, 2.72575, 2.74247, 2.75919, 2.77591, 2.79264, 2.80936, 2.82608,
+            2.8428,  2.85953, 2.87625, 2.89297, 2.90969, 2.92642, 2.94314, 2.95986, 2.97658, 2.99331,
+            3.01003, 3.02675, 3.04347, 3.06019, 3.07692, 3.09364, 3.11036, 3.12708, 3.14381, 3.16053,
+            3.17725, 3.19397, 3.2107,  3.22742, 3.24414, 3.26086, 3.27759, 3.29431, 3.31103, 3.32775,
+            3.34447, 3.3612,  3.37792, 3.39464, 3.41136, 3.42809, 3.44481, 3.46153, 3.47825, 3.49498,
+            3.5117,  3.52842, 3.54514, 3.56187, 3.57859, 3.59531, 3.61203, 3.62876, 3.64548, 3.6622,
+            3.67892, 3.69564, 3.71237, 3.72909, 3.74581, 3.76253, 3.77926, 3.79598, 3.8127,  3.82942,
+            3.84615, 3.86287, 3.87959, 3.89631, 3.91304, 3.92976, 3.94648, 3.9632,  3.97993, 3.99665,
+            4.01337, 4.03009, 4.04681, 4.06354, 4.08026, 4.09698, 4.1137,  4.13043, 4.14715, 4.16387,
+            4.18059, 4.19732, 4.21404, 4.23076, 4.24748, 4.26421, 4.28093, 4.29765, 4.31437, 4.3311,
+            4.34782, 4.36454, 4.38126, 4.39798, 4.41471, 4.43143, 4.44815, 4.46487, 4.4816,  4.49832,
+            4.51504, 4.53176, 4.54849, 4.56521, 4.58193, 4.59865, 4.61538, 4.6321,  4.64882, 4.66554,
+            4.68226, 4.69899, 4.71571, 4.73243, 4.74915, 4.76588, 4.7826,  4.79932, 4.81604, 4.83277,
+            4.84949, 4.86621, 4.88293, 4.89966, 4.91638, 4.9331,  4.94982, 4.96655, 4.98327, 4.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 () {