@vbarbarosh/node-helpers 3.73.0 → 3.74.1

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.73.0/dist/browser.js"></script>
+<script src="https://unpkg.com/@vbarbarosh/node-helpers@3.74.1/dist/browser.js"></script>
 ```
 
 ⚠️ All browser functions are exposed globally.

package/dist/browser.js

@@ -80,7 +80,7 @@ function serializer(replacer, cycleReplacer) {
 
 var map = {
 	"./array_chunk.js": "./src/array_chunk.js",
-	"./array_chunk_jobs.js": "./src/array_chunk_jobs.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",
@@ -205,39 +205,44 @@ module.exports = array_chunk;
 
 /***/ }),
 
-/***/ "./src/array_chunk_jobs.js":
-/*!*********************************!*\
-  !*** ./src/array_chunk_jobs.js ***!
-  \*********************************/
+/***/ "./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 of jobs between up to `max_threads`, while trying to put at least
- * `min_jobs_per_thread` items into each chunk.
+ * 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).
  *
- * - 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.
+ * The function distributes items as evenly as possible:
+ * - Chunk sizes differ by at most 1 item.
+ * - The number of chunks never exceeds `max_chunks`.
  *
- * Alternative names:
- *   - array_chunk_balanced
+ * Originally designed for distributing workload across threads
+ * (e.g. `array_chunk_balanced(jobs, max_threads, min_jobs_per_thread)`).
  *
- * @param array
- * @param max_threads
- * @param min_jobs_per_thread
- * @returns {*[]}
+ * 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_jobs(array = [], max_threads = 1, min_jobs_per_thread = 1)
+function array_chunk_balanced(array = [], max_chunks = 1, min_items_per_chunk = 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 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 = jobs_per_thread + (extra ? 1 : 0);
+        const size = items_per_chunk + (extra ? 1 : 0);
         out.push(array.slice(i, i + size));
         i += size;
         if (extra) {
@@ -247,7 +252,7 @@ function array_chunk_jobs(array = [], max_threads = 1, min_jobs_per_thread = 1)
     return out;
 }
 
-module.exports = array_chunk_jobs;
+module.exports = array_chunk_balanced;
 
 
 /***/ }),
@@ -2479,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.73.0"} was not injected — window.${ns} is already in use`);
+    console.log(`❌ @vbarbarosh/node-helpers@${"3.74.1"} was not injected — window.${ns} is already in use`);
 }
 else {
-    console.log(`🎉 @vbarbarosh/node-helpers@${"3.73.0"} successfully exposed as window.${ns}`);
+    console.log(`🎉 @vbarbarosh/node-helpers@${"3.74.1"} 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.73.0",
+    "version": "3.74.1",
     "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.test.js

@@ -7,5 +7,66 @@ describe('array_fps', function () {
         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/cache.js

@@ -0,0 +1,15 @@
+// read, write, refresh
+async function cache({get, set, refresh})
+{
+    try {
+        return await get();
+    }
+    catch {
+    }
+
+    const value = await refresh();
+    await set(value);
+    return value;
+}
+
+module.exports = cache;

package/src/cache.md

@@ -0,0 +1,9 @@
+Probably the most basic cache engine ever.
+
+```javascript
+await cache({
+    get: () => fs_read_json('data.json'),
+    set: v => fs_write_json('data.json', v),
+    refresh: () => compute(),
+});
+```

package/src/urlmod.test.js

@@ -32,4 +32,9 @@ describe('urlmod', function () {
         assert.deepEqual(urlmod('/#ex', {b: 2}), '/?b=2#ex');
         assert.deepEqual(urlmod('http://www.example.com/some/path?a=1#ex', {b: 2}), 'http://www.example.com/some/path?a=1&b=2#ex');
     });
+    it('should keep port', function () {
+        const actual = urlmod('http://localhost:3000/auth/sign-in', {return: '/auth/profile'});
+        const expected = 'http://localhost:3000/auth/sign-in?return=%2Fauth%2Fprofile';
+        assert.strictEqual(actual, expected);
+    })
 });

package/src/urlparts.js

@@ -0,0 +1,20 @@
+function urlparts(url)
+{
+    const tmp = url instanceof URL
+        ? url
+        : new URL((typeof url === 'string' ? url : ''), 'fake://fake/');
+    return {
+        href: tmp.href,
+        protocol: tmp.protocol,
+        hostname: tmp.hostname,
+        username: tmp.username,
+        password: tmp.password,
+        host: tmp.host,
+        port: tmp.port,
+        path: tmp.pathname,
+        search: tmp.search,
+        hash: tmp.hash,
+    };
+}
+
+module.exports = urlparts;

package/src/urlparts.test.js

@@ -0,0 +1,294 @@
+const assert = require('assert');
+const edge_values = require('@vbarbarosh/type-helpers/src/edge_values');
+const urlparts = require('./urlparts');
+
+const extra_edge_values = [
+    // whitespace strings
+    {label: '" "', value: ' '},
+    {label: '"\\t"', value: '\t'},
+    {label: '"\\n"', value: '\n'},
+    {label: '"\\r\\n"', value: '\r\n'},
+
+    // numeric strings
+    {label: '"0"', value: '0'},
+    {label: '"1"', value: '1'},
+    {label: '"NaN"', value: 'NaN'},
+    {label: '"Infinity"', value: 'Infinity'},
+
+    // weird unicode
+    {label: '"💩"', value: '💩'},
+    {label: '"😀"', value: '😀'},
+    {label: '"привет"', value: 'привет'},
+    {label: '"こんにちは"', value: 'こんにちは'},
+
+    // dangerous chars
+    {label: '"<script>"', value: '<script>'},
+    {label: '"../"', value: '../'},
+    {label: '"%20"', value: '%20'},
+    {label: '"a?b=c"', value: 'a?b=c'},
+    {label: '"a#b"', value: 'a#b'},
+
+    // arrays
+    {label: '[1,2,3]', value: [1, 2, 3]},
+    {label: '[null]', value: [null]},
+    {label: '[undefined]', value: [undefined]},
+    {label: 'new Array(5)', value: new Array(5)},
+
+    // typed arrays
+    {label: 'Uint8Array', value: new Uint8Array([1, 2, 3])},
+    {label: 'Buffer', value: Buffer.from('abc')},
+
+    // objects
+    {label: '{a:1}', value: {a: 1}},
+    {label: 'Object.create(null)', value: Object.create(null)},
+
+    // custom coercion
+    {label: 'toString() => x', value: {toString() {return 'x';}}},
+    {label: 'valueOf() => 123', value: {valueOf() {return 123;}}},
+
+    // dates
+    {label: 'new Date()', value: new Date()},
+    {label: 'Invalid Date', value: new Date('invalid')},
+
+    // regexp
+    {label: '/foo/g', value: /foo/g},
+
+    // maps/sets
+    {label: 'Map', value: new Map()},
+    {label: 'Set', value: new Set()},
+    {label: 'WeakMap', value: new WeakMap()},
+    {label: 'WeakSet', value: new WeakSet()},
+
+    // promises
+    {label: 'Promise.resolve(1)', value: Promise.resolve(1)},
+
+    // errors
+    {label: 'Error', value: new Error('boom')},
+    {label: 'TypeError', value: new TypeError('boom')},
+
+    // wrappers
+    {label: 'new String()', value: new String('abc')},
+    {label: 'new Number()', value: new Number(123)},
+    {label: 'new Boolean()', value: new Boolean(false)},
+
+    // url-like
+    {label: 'new URL("https://example.com")', value: new URL('https://example.com')},
+
+    // bigint
+    {label: '1n', value: 1n},
+    {label: '-1n', value: -1n},
+
+    // special numbers
+    {label: 'Number.EPSILON', value: Number.EPSILON},
+
+    // proxy
+    {label: 'Proxy', value: new Proxy({}, {})},
+];
+
+const happy_paths = [
+    {
+        label: 'parses full https url',
+        input: 'https://john:secret@example.com:8080/users/15?page=2#top',
+        expected: {
+            href: 'https://john:secret@example.com:8080/users/15?page=2#top',
+            protocol: 'https:',
+            hostname: 'example.com',
+            username: 'john',
+            password: 'secret',
+            host: 'example.com:8080',
+            port: '8080',
+            path: '/users/15',
+            search: '?page=2',
+            hash: '#top',
+        },
+    },
+    {
+        label: 'parses https url without auth',
+        input: 'https://example.com/users',
+        expected: {
+            href: 'https://example.com/users',
+            protocol: 'https:',
+            hostname: 'example.com',
+            username: '',
+            password: '',
+            host: 'example.com',
+            port: '',
+            path: '/users',
+            search: '',
+            hash: '',
+        },
+    },
+    {
+        label: 'parses root url',
+        input: 'https://example.com',
+        expected: {
+            href: 'https://example.com/',
+            protocol: 'https:',
+            hostname: 'example.com',
+            username: '',
+            password: '',
+            host: 'example.com',
+            port: '',
+            path: '/',
+            search: '',
+            hash: '',
+        },
+    },
+    {
+        label: 'parses relative path',
+        input: '/users?page=5',
+        expected: {
+            href: 'fake://fake/users?page=5',
+            protocol: 'fake:',
+            hostname: 'fake',
+            username: '',
+            password: '',
+            host: 'fake',
+            port: '',
+            path: '/users',
+            search: '?page=5',
+            hash: '',
+        },
+    },
+    {
+        label: 'parses hash',
+        input: 'https://example.com/docs#intro',
+        expected: {
+            href: 'https://example.com/docs#intro',
+            protocol: 'https:',
+            hostname: 'example.com',
+            username: '',
+            password: '',
+            host: 'example.com',
+            port: '',
+            path: '/docs',
+            search: '',
+            hash: '#intro',
+        },
+    },
+    {
+        label: 'parses query string',
+        input: 'https://example.com?a=1&b=2',
+        expected: {
+            href: 'https://example.com/?a=1&b=2',
+            protocol: 'https:',
+            hostname: 'example.com',
+            username: '',
+            password: '',
+            host: 'example.com',
+            port: '',
+            path: '/',
+            search: '?a=1&b=2',
+            hash: '',
+        },
+    },
+    {
+        label: 'parses localhost with port',
+        input: 'http://localhost:3000/foo',
+        expected: {
+            href: 'http://localhost:3000/foo',
+            protocol: 'http:',
+            hostname: 'localhost',
+            username: '',
+            password: '',
+            host: 'localhost:3000',
+            port: '3000',
+            path: '/foo',
+            search: '',
+            hash: '',
+        },
+    },
+    {
+        label: 'parses ftp url',
+        input: 'ftp://example.com/file.txt',
+        expected: {
+            href: 'ftp://example.com/file.txt',
+            protocol: 'ftp:',
+            hostname: 'example.com',
+            username: '',
+            password: '',
+            host: 'example.com',
+            port: '',
+            path: '/file.txt',
+            search: '',
+            hash: '',
+        },
+    },
+];
+
+describe('urlparts', function () {
+    it('no args', function () {
+        assert.deepStrictEqual(urlparts(), {
+            href: 'fake://fake/',
+            protocol: 'fake:',
+            hostname: 'fake',
+            username: '',
+            password: '',
+            host: 'fake',
+            port: '',
+            path: '/',
+            search: '',
+            hash: '',
+        });
+    });
+
+    describe('happy paths', function () {
+        for (const item of happy_paths) {
+            it(item.label, function () {
+                const actual = urlparts(item.input);
+                assert.deepStrictEqual(actual, item.expected);
+            });
+        }
+    });
+
+    describe('edge values', function () {
+        for (const item of [...edge_values, ...extra_edge_values]) {
+            it(item.label, function () {
+                if (typeof item.value === 'string') {
+                    const tmp = new URL(item.value, 'fake://fake/');
+                    assert.deepStrictEqual(urlparts(item.value), {
+                        href: tmp.href,
+                        protocol: tmp.protocol,
+                        hostname: tmp.hostname,
+                        username: tmp.username,
+                        password: tmp.password,
+                        host: tmp.host,
+                        port: tmp.port,
+                        path: tmp.pathname,
+                        search: tmp.search,
+                        hash: tmp.hash,
+                    });
+                }
+                else if (item.value instanceof URL) {
+                    const tmp = item.value;
+                    assert.deepStrictEqual(urlparts(item.value), {
+                        href: tmp.href,
+                        protocol: tmp.protocol,
+                        hostname: tmp.hostname,
+                        username: tmp.username,
+                        password: tmp.password,
+                        host: tmp.host,
+                        port: tmp.port,
+                        path: tmp.pathname,
+                        search: tmp.search,
+                        hash: tmp.hash,
+                    });
+                }
+                else {
+                    assert.deepStrictEqual(urlparts(item.value), {
+                        href: 'fake://fake/',
+                        protocol: 'fake:',
+                        hostname: 'fake',
+                        username: '',
+                        password: '',
+                        host: 'fake',
+                        port: '',
+                        path: '/',
+                        search: '',
+                        hash: '',
+                    });
+                }
+            });
+        }
+    });
+});

package/src/array_chunk_jobs.js

@@ -1,37 +0,0 @@
-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

@@ -1,37 +0,0 @@
-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]
-            ]
-        );
-    });
-});