@vbarbarosh/node-helpers 3.67.0 → 3.69.0

package/package.json

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

package/src/_finally.js

@@ -0,0 +1,8 @@
+function _finally(callback)
+{
+    return {
+        [Symbol.dispose]: callback,
+    };
+}
+
+module.exports = _finally;

package/src/_finally.md

@@ -0,0 +1,19 @@
+`_finally` lets you register cleanup code that always runs when the scope ends.
+
+```js
+this.foo = 12345;
+using _ = _finally(() => this.foo = null);
+// ...
+```
+
+This is essentially the same as:
+
+```js
+this.foo = 12345;
+try {
+    // ..
+}
+finally {
+    this.foo = null;
+}
+```

package/src/_perf.js

@@ -0,0 +1,18 @@
+function _perf(name, print = s => console.log(s))
+{
+    const time0 = performance.now();
+    return {
+        times: 1,
+        [Symbol.dispose]: function () {
+            const duration = performance.now() - time0;
+            if (this.times > 1) {
+                print(`[${name}] ${duration.toFixed(4)}ms x ${this.times}`);
+            }
+            else {
+                print(`[${name}] ${duration.toFixed(4)}ms`);
+            }
+        },
+    };
+}
+
+module.exports = _perf;

package/src/_perf.md

@@ -0,0 +1,13 @@
+Measures time from the current position till the end of a block scope.
+
+```js
+app.component('sidebar', {
+    template: `...`,
+    methods: {
+        click_download: async function () {
+            using _ = _perf('download');
+            // ...
+        },
+    },
+});
+```

package/src/_restore.js

@@ -0,0 +1,16 @@
+// 1) Capture original value
+// 2) Assign a temporary one
+// 3) Automatically restore on scope exit
+//
+// Basically: set variable, and automatically restore the original value at the end of scope.
+function _restore(value, callback)
+{
+    const [original] = callback(value);
+    return {
+        [Symbol.dispose]: function () {
+            callback(original);
+        },
+    };
+}
+
+module.exports = _restore;

package/src/_restore.md

@@ -0,0 +1,21 @@
+The pattern "set a new value now, restore the old one when scope ends".
+
+```js
+using _ = _restore(false, v => [this.controls.play, this.controls.play = v]);
+// ...
+```
+
+This is essentially the same as:
+
+```js
+{
+    const _old = this.controls.play;
+    this.controls.play = false;
+    try {
+        // ...
+    }
+    finally {
+        this.controls.play = _old;
+    }
+}
+```

package/src/_try.js

@@ -0,0 +1,11 @@
+function _try(callback, default_value)
+{
+    try {
+        return callback();
+    }
+    catch {
+        return default_value;
+    }
+}
+
+module.exports = _try;

package/src/_try.md

@@ -0,0 +1,5 @@
+Safely evaluates code and falls back to a default value if something goes wrong.
+
+```js
+const time = _try(() => this.$refs.iframe.contentWindow.timeline.time(), 0);
+```

package/src/array_max.md

@@ -0,0 +1 @@
+Returns the first element in the array with the maximal weight.

package/src/array_min.md

@@ -0,0 +1 @@
+Returns the first element in the array with the minimal weight.

package/src/array_shuffle.md

@@ -0,0 +1,5 @@
+Shuffles an array using Durstenfeld shuffle algorithm.
+
+Note: This function performs shuffle in-place. To get a shuffled copy
+use call slice before calling, e.g. `array_shuffle(items.slice())`.
+ 

package/src/array_unique.md

@@ -0,0 +1 @@
+Return unique values; if a value occurs multiple times, keep the first one.

package/src/array_unique_last.md

@@ -0,0 +1 @@
+Return unique values; if a value occurs multiple times, keep the last one.

package/src/browser/index.js

@@ -1,7 +1,15 @@
-// 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$/);
-require_tmp.keys().forEach(function (key) {
-    const [, basename] = key.match(/([^/]+)\.js$/);
-    window[basename] = require_tmp(key);
-});
+const ns = new URL(document.currentScript.src).searchParams.get('var') ?? 'h';
+if (typeof window[ns] !== 'undefined') {
+    console.log(`❌ @vbarbarosh/node-helpers@${__VERSION__} was not injected — window.${ns} is already in use`);
+}
+else {
+    console.log(`🎉 @vbarbarosh/node-helpers@${__VERSION__} 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 = 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$/);
+    require_tmp.keys().forEach(function (key) {
+        const [, basename] = key.match(/([^/]+)\.js$/);
+        window[ns][basename] = require_tmp(key);
+    });
+}

package/src/fastdl.md

@@ -0,0 +1,8 @@
+Download a file in several connections in parallel.
+
+```js
+await fastdl({
+    file: fs_path_basename(new URL(url).pathname),
+    read_stream_with_range: (first, last) => http_get_stream_range(url, first, last),
+});
+```

package/src/fcmp_from_spec.js

@@ -1,6 +1,8 @@
 /**
  * Create fcmp from an array of props. For desc order a prop should be prefixed
  * with minus sign (e.g. -price).
+ *
+ * @deprecated Deprecated in favor of fcmpx
  */
 function fcmp_from_spec(props)
 {

package/src/fcmpx.md

@@ -0,0 +1,17 @@
+Comparator builder using compact expressions.
+
+fcmp expression — Creates an `fcmp` function from an expression, suitable for use with `[].sort()`.
+
+```js
+fcmpx('user.email')
+fcmpx('-user.age,user.email')
+fcmpx(v => v.user.email)
+fcmpx(['user.age', 'user.email'])
+fcmpx(['-user.age', 'user.email'])
+```
+
+Sorting rule: Missing values are considered greater than any defined value
+and are therefore placed after all defined values.
+
+- YouTube: [Сортировка объектов в JavaScript](https://www.youtube.com/watch?v=rHEH_JfQjL4)
+- https://github.com/vbarbarosh/speaking/tree/master/20250822-js-sort-fcmpx

package/src/fcmpx.test.js

@@ -8,6 +8,21 @@ const users = [
     {id: 'betty|32|-', user: {name: 'betty', tag: {short: 'bar', long: 'barbar'}, age: 32}},
 ];
 
+// https://dummyjson.com/docs/products
+
+const products = [
+    {id: 1, name: 'Yoga Mat', category: 'Yoga', price: 25.99, brand: 'BalanceFrom', rating: 4.6, discount: 0.1, availability: 'in_stock'},
+    {id: 2, name: 'Adjustable Dumbbells', category: 'Strength', price: 199.99, brand: 'Bowflex', rating: 4.8, availability: 'preorder'},
+    {id: 3, name: 'Resistance Bands Set', category: 'Strength', price: 32.5, brand: 'Fit Simplify', rating: 4.5, discount: 0.15, availability: 'in_stock'},
+    {id: 4, name: 'Treadmill', category: 'Cardio', price: 899, brand: 'NordicTrack', rating: 4.7, availability: 'out_of_stock'},
+    {id: 5, name: 'Kettlebell 20lb', category: 'Strength', price: 45, brand: 'CAP Barbell', rating: 4.4, discount: 0.05, availability: 'in_stock'},
+    {id: 6, name: 'Foam Roller', category: 'Recovery', price: 19.99, brand: 'TriggerPoint', rating: 4.6, availability: 'limited'},
+    {id: 7, name: 'Exercise Bike', category: 'Cardio', price: 599, brand: 'Peloton', rating: 4.9, discount: 0.2, availability: 'in_stock'},
+    {id: 8, name: 'Pull-Up Bar', category: 'Strength', price: 29.95, brand: 'Iron Gym', rating: 4.3, availability: 'in_stock'},
+    {id: 9, name: 'Jump Rope', category: 'Cardio', price: 12.99, brand: 'WOD Nation', rating: 4.2, discount: 0.25, availability: 'limited'},
+    {id: 10, name: 'Ab Roller', category: 'Core', price: 21.49, brand: 'Perfect Fitness', rating: 4.5, availability: 'in_stock'},
+];
+
 const tests = [
     {
         description: 'missing: should move undefined values to the bottom',
@@ -149,7 +164,7 @@ const tests = [
 describe('fcmpx', function () {
     tests.forEach(function (test) {
         test.expressions.forEach(function (expr, i) {
-            it(`${test.description}: #${i+1} | ${test.description}`, function () {
+            it(`${test.description}: #${i + 1} | ${test.description}`, function () {
                 const actual = test.items.slice().sort(fcmpx(expr)).map(test.extract);
                 assert.deepStrictEqual(actual, test.expected);
             });

package/src/filter1_from_spec.md

@@ -0,0 +1,7 @@
+Creates a filtering function based on the following spec:
+
+1. Substrings are separated by `/`.
+2. Each substring may have special characters:
+   - `^`: Substring must appear at the beginning.
+   - `$`: Substring must appear at the end.
+   - `!`: Negates the condition (substring must not appear).

package/src/format_hrtime.md

@@ -0,0 +1 @@
+Return a human-readable representation of hrtime (the return value from `process.hrtime(hrtime0)`).

package/src/fs_fopen_update.md

@@ -0,0 +1,5 @@
+The main use case is uploading files in chunks.
+
+Each time a chunk is uploaded, update the target file.
+
+By the end, you will have a ready-to-use file.

package/src/fs_size_enoent.md

@@ -0,0 +1,3 @@
+Returns the size of a file, or 0 if the file is not present.
+
+It was created for cases when you need to resume a download.

package/src/fs_tempdir.md

@@ -0,0 +1,6 @@
+```js
+await fs_tempdir(async function (d) {
+    await fs_write(`${d}/input.txt`, 'hello');
+    await shell(['ls', '-alh'], {cwd: d});
+});
+```

package/src/now_atom.js

@@ -1,5 +1,5 @@
 /**
- * Return current date in ATOM format (e.g. "2021-07-17T23:27:01.030Z")
+ * Return the current date in ATOM format (e.g. "2021-07-17T23:27:01.030Z")
  *
  * @returns {string}
  * @link https://www.php.net/manual/en/class.datetimeinterface.php#datetime.constants.atom

package/src/now_atom.md

@@ -0,0 +1 @@
+Return the current date in ATOM format (e.g. "2021-07-17T23:27:01.030Z")

package/src/parallel.md

@@ -0,0 +1,5 @@
+- Run until `spawn` return `null`.
+- Keep no more than `concurrency` number of workers at a time.
+
+⚠️ Warning: `spawn` should not be async function (async functions are always return `promise`).
+Instead, it should be a simple function returning either `null` or a `promise`.

package/src/ping_socket.md

@@ -0,0 +1,3 @@
+- Always closes the socket.
+- Throws on any error or timeout.
+- Doesn’t hang if the server sends nothing.

package/src/stream_chunk.md

@@ -0,0 +1 @@
+Split a stream into chunks of objects.

package/src/stream_data_ln.md

@@ -0,0 +1 @@
+Split stream on each `\n` and call `fn` for each line.

package/src/stream_each.md

@@ -0,0 +1 @@
+Pass each item to a simple function. This is a final step.

package/src/stream_filter.md

@@ -0,0 +1 @@
+Pass down only those items passed user-defined criteria.

package/src/stream_lines.md

@@ -0,0 +1 @@
+Split stream into lines.

package/src/stream_map.md

@@ -0,0 +1 @@
+Transform each item using a simple function.

package/src/stream_map_flatten.md

@@ -0,0 +1 @@
+Pass each item through a user-defined generator, passes down each yielded item.

package/src/stream_map_parallel.md

@@ -0,0 +1 @@
+Transform each item using a simple function in parallel.

package/src/stream_parse_csv.md

@@ -0,0 +1,3 @@
+Parse input stream as CSV data.
+
+- https://csv.js.org/parse/options/

package/src/stream_progress.js

@@ -7,7 +7,7 @@ const stream = require('stream');
  * Monitor the progress of data through a pipe, similar to the UNIX `pv` command.
  *
  * Requirements:
- * - should emit first message as fast as possible
+ * - should emit the first message as fast as possible
  * - should always emit 100% message
  *
  * @similar https://www.npmjs.com/package/progress-stream

package/src/stream_progress.md

@@ -0,0 +1,8 @@
+Monitor the progress of data through a pipe, similar to the UNIX `pv` command.
+
+Requirements:
+
+- should emit the first message as fast as possible
+- should always emit 100% message
+
+- Similar: https://www.npmjs.com/package/progress-stream

package/src/stream_skip.md

@@ -0,0 +1 @@
+Skip first `n` records.

package/src/stream_strpbrk.md

@@ -0,0 +1 @@
+Split the input stream by consecutive delimiters in `chars`.

package/src/stream_tap.md

@@ -0,0 +1 @@
+Call `fn` on each item.

package/src/stream_xml_analyze.md

@@ -0,0 +1 @@
+Consume XML, produce an object with analytics about provided xml stream.

package/src/stream_xml_parse.md

@@ -0,0 +1 @@
+Consume XML, produce objects.

package/src/throttle.md

@@ -0,0 +1,3 @@
+Ensure that only one event was fired for each ms.
+
+- https://stackoverflow.com/questions/25991367/difference-between-throttling-and-debouncing-a-function

package/src/urlclean.js

@@ -2,7 +2,7 @@ const querystring = require('querystring');
 
 /**
  * Replace unnecessary encodes symbols with chars. The returned url will be
- * more human frieldy, at the same time it still be valid url.
+ * more human-friendly, at the same time it will still be valid url.
  */
 function urlclean(url)
 {

package/src/urlclean.md

@@ -0,0 +1,2 @@
+Replace unnecessary encodes symbols with chars. The returned url will be
+more human-friendly, at the same time it will still be valid url.

package/src/urlmod.md

@@ -0,0 +1,7 @@
+Set, change, or remove query string parameters.
+
+```js
+urlmod('', {a: 1})          // '?a=1'  set
+urlmod('?a=1', {a: 2})      // '?a=2'  change
+urlmod('?a=1', {a: null})   // ''      remove
+```

package/src/user_friendly_status.md

@@ -0,0 +1,4 @@
+Concept. Represents a way to display a status of a currently running task to the end-user.
+
+@see countdown
+@see progress

package/src/wait_while.md

@@ -0,0 +1,5 @@
+Wait until `fn` returns `true`.
+
+W A R N I N G
+This method was designed mainly for prototyping (where code cleanliness is important).
+It might drastically decrease performance.

package/src/waitcb.md

@@ -0,0 +1,12 @@
+Wait for a Node-like function to finish (which will call `callback`
+with 2 arguments: `error` and `value`).
+
+```js
+await waitcb(cb => fs.writeFile('a', 'hello\n', cb));
+```
+
+The same as:
+
+```js
+const [promise, resolve, reject] = (a => [new Promise((...v) => a = v), ...a])();
+```