@vbarbarosh/node-helpers 3.66.1 → 3.68.0

package/src/parallel.js

@@ -1,7 +1,7 @@
 const NotImplemented = require('./errors/NotImplemented');
 const Promise = require('bluebird');
-const is_async_function = require('@vbarbarosh/type-helpers/src/is_async_function');
-const is_async_generator = require('@vbarbarosh/type-helpers/src/is_async_generator');
+const is_fn_async = require('@vbarbarosh/type-helpers/src/is_fn_async');
+const is_fn_gen_async = require('@vbarbarosh/type-helpers/src/is_fn_gen_async');
 
 /**
  * - Run until `spawn` return `null`.
@@ -12,7 +12,7 @@ const is_async_generator = require('@vbarbarosh/type-helpers/src/is_async_genera
  */
 async function parallel({concurrency, spawn, progress})
 {
-    if (is_async_function(spawn) || is_async_generator(spawn)) {
+    if (is_fn_async(spawn) || is_fn_gen_async(spawn)) {
         throw new Error('[spawn] should not be async function. Instead, it should be a simple function returning either [null] or a [promise].');
     }
     const running = [];

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/pid_exists.js

@@ -0,0 +1,12 @@
+function pid_exists(pid)
+{
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+
+module.exports = pid_exists;

package/src/pid_kill_grace.js

@@ -0,0 +1,28 @@
+const Promise = require('bluebird');
+const format_thousands = require('./format_thousands');
+const ignore = require('./ignore');
+const pid_exists = require('./pid_exists');
+
+async function pid_kill_grace(pid, {grace_timeout_ms = 5000, log = ignore} = {})
+{
+    log('Sending SIGTERM');
+    if (!process.kill(pid, 'SIGTERM')) {
+        throw new Error('SIGTERM Failed');
+    }
+
+    const end = Date.now() + grace_timeout_ms;
+    while (Date.now() < end) {
+        if (!pid_exists(pid)) {
+            return;
+        }
+        log(`Process is still there, waiting for 100ms, ${format_thousands(end - Date.now())}ms left`);
+        await Promise.delay(100);
+    }
+
+    log('Sending SIGKILL');
+    if (!process.kill(pid, 'SIGKILL')) {
+        throw new Error('SIGKILL Failed');
+    }
+}
+
+module.exports = pid_kill_grace;

package/src/ping_socket.js

@@ -0,0 +1,32 @@
+const Promise = require('bluebird');
+const net = require('net');
+
+/**
+ * - Always closes the socket.
+ * - Throws on any error or timeout.
+ * - Doesn’t hang if the server sends nothing.
+ */
+function ping_socket(socket_path, data = 'PING', timeout_ms = 1000)
+{
+    return new Promise(function (resolve, reject) {
+        let done = false;
+        const buf = [];
+        const socket = net.connect(socket_path);
+        socket.setTimeout(timeout_ms, () => finish(new Error('Socket Timeout')));
+        socket.on('end', () => finish(null, Buffer.concat(buf)))
+        socket.on('error', finish);
+        socket.on('connect', () => socket.end(data));
+        socket.on('data', chunk => buf.push(chunk));
+        function finish(error, out) {
+            if (done) {
+                return;
+            }
+            done = true;
+            socket.removeAllListeners();
+            socket.destroy();
+            error ? reject(error) : resolve(out);
+        }
+    });
+}
+
+module.exports = ping_socket;

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/plural.js

@@ -1,6 +1,12 @@
-function plural(n, apple, apples)
+function plural(n, singular, plural, zero)
 {
-    return (n % 10 === 1 && n % 100 !== 11) ? apple.split('#').join(n) : apples.split('#').join(n);
+    if (n === 0 && typeof zero === 'string') {
+        return zero;
+    }
+    if (n % 10 === 1 && n % 100 !== 11) {
+        return singular.split('#').join(n);
+    }
+    return plural.split('#').join(n);
 }
 
 module.exports = plural;

package/src/plural.test.js

@@ -1,15 +1,17 @@
 const assert = require('assert');
 const plural = require('./plural');
 
-const items = [
-    ['1 apple', 1, '# apple', '# apples', ],
+const tests = [
+    ['1 apple', 1, '# apple', '# apples'],
     ['2 apples', 2, '# apple', '# apples'],
     ['10 apples', 10, '# apple', '# apples'],
     ['21 apple', 21, '# apple', '# apples'],
+    ['0 apples', 0, '# apple', '# apples'],
+    ['No apples', 0, '# apple', '# apples', 'No apples'],
 ];
 
 describe('plural', function () {
-    items.forEach(function ([expected, ...args],) {
+    tests.forEach(function ([expected, ...args],) {
         it(expected, function () {
             const actual = plural(...args);
             assert.deepStrictEqual(actual, expected);

package/src/sanitize_var_name.js

@@ -1,9 +1,9 @@
-const camel_to_snake = require('./camel_to_snake');
 const sanitize_dash_name = require('./sanitize_dash_name');
+const str_camel_to_snake = require('./str_camel_to_snake');
 
 function sanitize_var_name(var_name)
 {
-    const out = sanitize_dash_name(camel_to_snake(var_name)).replace(/[^a-z0-9]+/g, '_');
+    const out = sanitize_dash_name(str_camel_to_snake(var_name)).replace(/[^a-z0-9]+/g, '_');
     if (out.length === 0) {
         return '_';
     }

package/src/{camel_to_snake.js → str_camel_to_snake.js}

@@ -1,4 +1,4 @@
-function camel_to_snake(s)
+function str_camel_to_snake(s)
 {
     return s
         .replace(/([a-z0-9])([A-Z])/g, '$1_$2')  // Insert underscore between lowercase/number and uppercase
@@ -6,4 +6,4 @@ function camel_to_snake(s)
         .toLowerCase();
 }
 
-module.exports = camel_to_snake;
+module.exports = str_camel_to_snake;

package/src/{camel_to_snake.test.js → str_camel_to_snake.test.js}

@@ -1,5 +1,5 @@
 const assert = require('assert');
-const camel_to_snake = require('./camel_to_snake');
+const str_camel_to_snake = require('./str_camel_to_snake');
 
 const items = [
     ['UPC', 'upc'],
@@ -8,10 +8,10 @@ const items = [
     ['XMLHTTPRequest', 'xmlhttp_request'],
 ];
 
-describe('camel_to_snake', function () {
+describe('str_camel_to_snake', function () {
     items.forEach(function ([input, expected],) {
         it(`${input === '' ? '☒' : input} → ${expected}`, function () {
-            assert.deepStrictEqual(camel_to_snake(input), expected);
+            assert.deepStrictEqual(str_camel_to_snake(input), expected);
         });
     });
 });

package/src/str_parse_kv.js

@@ -0,0 +1,10 @@
+function str_parse_kv(str)
+{
+    const i = str.indexOf(':');
+    if (i === -1) {
+        return [str.trim(), ''];
+    }
+    return [str.slice(0, i).trim(), str.slice(i + 1).trim()];
+}
+
+module.exports = str_parse_kv;

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])();
+```

package/src/fcmp_strings.js

@@ -1,6 +0,0 @@
-function fcmp_strings(a, b)
-{
-    return String(a).localeCompare(b);
-}
-
-module.exports = fcmp_strings;