@vbarbarosh/node-helpers 3.41.1 → 3.43.0

package/package.json

@@ -2,7 +2,7 @@
     "author": "Vladimir Barbarosh <vladimir.barbarosh@gmail.com>",
     "license": "MIT",
     "name": "@vbarbarosh/node-helpers",
-    "version": "3.41.1",
+    "version": "3.43.0",
     "description": "A set of helpers for JavaScript/Node.js",
     "files": [
         "src"

package/src/fs_fopen_update.js

@@ -1,9 +1,10 @@
 const fs_fopen = require('./fs_fopen');
 
-// Main use case is uploading files in chunks. Each time
-// a chunk is uploaded do update a target file. At the end
-// you will have a ready to go file.
-
+/**
+ * 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.
+ */
 async function fs_fopen_update(pathname)
 {
     try {
@@ -11,23 +12,22 @@ async function fs_fopen_update(pathname)
         return await fs_fopen(pathname, 'r+');
     }
     catch (error) {
-        if (error.code != 'ENOENT') {
+        if (error.code !== 'ENOENT') {
             throw error;
         }
     }
 
     try {
-        // There is no such a file, try to create it...
+        // There is no such file; try to create it...
         return await fs_fopen(pathname, 'wx');
     }
     catch (error) {
-        if (error.code != 'EEXIST') {
+        if (error.code !== 'EEXIST') {
             throw error;
         }
     }
 
-    // Another process might have already created it, try to
-    // open for updating...
+    // Another process might have already created it; try opening it for updating
     return fs_fopen(pathname, 'r+');
 }
 

package/src/fs_fread.js

@@ -1,15 +1,16 @@
 const fs = require('fs');
-const util = require('util');
-
-// https://nodejs.org/api/util.html#util_util_promisify_original
-const read = util.promisify(fs.read);
-
-// Main use case is for reading chunks of data from file.
 
+/**
+ * The main use case is reading chunks of data from a file.
+ */
 async function fs_fread(fp, buffer, offset = null)
 {
-    const {bytesRead} = await read(fp, buffer, 0, buffer.length, offset);
-    return (bytesRead == buffer.length) ? buffer : buffer.slice(0, bytesRead);
+    const {bytesRead} = await new Promise(function (resolve, reject) {
+        fs.read(fp, buffer, 0, buffer.length, offset, function (error, out) {
+            error ? reject(error) : resolve(out);
+        });
+    });
+    return (bytesRead === buffer.length) ? buffer : buffer.slice(0, bytesRead);
 }
 
 module.exports = fs_fread;

package/src/fs_fwrite.js

@@ -1,14 +1,15 @@
 const fs = require('fs');
-const util = require('util');
-
-// https://nodejs.org/api/util.html#util_util_promisify_original
-const write = util.promisify(fs.write);
-
-// Main use case is for writing chunks of data to file.
 
+/**
+ * The main use case is writing chunks of data to a file.
+ */
 async function fs_fwrite(fp, buffer, offset = null)
 {
-    const {bytesWritten} = await write(fp, buffer, 0, buffer.length, offset);
+    const {bytesWritten} = await new Promise(function (resolve, reject) {
+        fs.write(fp, buffer, 0, buffer.length, offset, function (error, out) {
+            error ? reject(error) : resolve(out);
+        });
+    });
     return bytesWritten;
 }
 

package/src/fs_read_buffer.js

@@ -1,5 +1,8 @@
 const fs_read = require('./fs_read');
 
+/**
+ * Read the entire contents of a file into a buffer.
+ */
 function fs_read_buffer(file)
 {
     return fs_read(file);

package/src/fs_read_utf8.js

@@ -1,5 +1,8 @@
 const fs_read = require('./fs_read');
 
+/**
+ * Read the entire contents of a file into a UTF-8 encoded string.
+ */
 function fs_read_utf8(file)
 {
     return fs_read(file, {encoding: 'utf8'});

package/src/fs_rmrf.js

@@ -5,6 +5,9 @@ const fs_readdir = require('./fs_readdir');
 const fs_rm = require('./fs_rm');
 const fs_rmdir = require('./fs_rmdir');
 
+/**
+ * Remove a file or directory, along with all nested files and directories, recursively.
+ */
 async function fs_rmrf(pathname)
 {
     const fi = await fs_fi(pathname).catch(() => null);

package/src/fs_size_enoent.js

@@ -1,10 +1,8 @@
 const fs = require('fs');
 
 /**
- * Returns size of a file, or 0 if file is not present. Was created for cases
- * when you need to resume download.
- *
- * @returns {Promise<int>}
+ * 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.
  */
 async function fs_size_enoent(path)
 {

package/src/perf_end_human.js

@@ -0,0 +1,8 @@
+const format_hrtime = require('./format_hrtime');
+
+function perf_end_human(time0, digits = 4)
+{
+    return format_hrtime(time0, digits);
+}
+
+module.exports = perf_end_human;

package/src/perf_end_ms.js

@@ -0,0 +1,7 @@
+function perf_end_ms(time0)
+{
+    const [u, v] = process.hrtime(time0);
+    return Math.round((u + v/1E9)*1000);
+}
+
+module.exports = perf_end_ms;

package/src/perf_measure_human.js

@@ -0,0 +1,11 @@
+const perf_end_human = require('./perf_end_human');
+const perf_start = require('./perf_start');
+
+async function perf_measure_human(fn, digits = 4)
+{
+    const time0 = perf_start();
+    await fn();
+    return perf_end_human(time0, digits);
+}
+
+module.exports = perf_measure_human;

package/src/perf_start.js

@@ -0,0 +1,6 @@
+function perf_start()
+{
+    return process.hrtime();
+}
+
+module.exports = perf_start;

package/src/stream_chunk.js

@@ -0,0 +1,27 @@
+const stream = require('stream');
+
+/**
+ * Split a stream into chunks of objects.
+ */
+function stream_chunk(chunk_size)
+{
+    const chunk = [];
+    return new stream.Transform({
+        objectMode: true,
+        transform: function (item, encoding, callback) {
+            chunk.push(item);
+            if (chunk.length >= chunk_size) {
+                this.push(chunk.splice(0));
+            }
+            callback();
+        },
+        flush: function (callback) {
+            if (chunk.length) {
+                this.push(chunk.splice(0));
+            }
+            callback();
+        },
+    });
+}
+
+module.exports = stream_chunk;

package/src/stream_data_ln.test.js

@@ -3,14 +3,13 @@ const fs = require('fs');
 const split = require('split');
 const stream = require('stream');
 const stream_data_ln = require('./stream_data_ln');
-const stream_promise = require('./stream_promise');
 
 describe('stream_data_ln', function () {
     it('should handle basic input', async function () {
         let actual = '';
         const s = fs.createReadStream(__filename);
         const off = stream_data_ln(s, v => actual += v + '\n');
-        await stream_promise(s);
+        await stream.promises.finished(s);
         off();
         assert.deepStrictEqual(actual, fs.readFileSync(__filename, {encoding: 'utf8'}));
     });

package/src/stream_each.js

@@ -7,9 +7,14 @@ function stream_each(fn)
 {
     return stream.Writable({
         objectMode: true,
-        write: function (item, encoding, callback) {
-            fn(item);
-            callback();
+        write: async function (item, encoding, callback) {
+            try {
+                await fn(item);
+                callback();
+            }
+            catch (error) {
+                callback(error);
+            }
         }
     });
 }

package/src/stream_filter.js

@@ -7,9 +7,9 @@ function stream_filter(fn)
 {
     return new stream.Transform({
         objectMode: true,
-        transform: function (item, encoding, callback) {
+        transform: async function (item, encoding, callback) {
             try {
-                if (fn(item)) {
+                if (await fn(item)) {
                     this.push(item);
                 }
                 callback();

package/src/stream_group.js

@@ -1,29 +1,13 @@
-const stream = require('stream');
+const stream_chunk = require('./stream_chunk');
 
 /**
- * Returns a transform stream used to group object into chunks of objects.
+ * Split a stream into chunks of objects.
  *
- * TODO Rename to stream_chunk
+ * @deprecated Deprecated in favor of `stream_chunk`
  */
 function stream_group(chunk_size)
 {
-    const chunk = [];
-    return new stream.Transform({
-        objectMode: true,
-        transform: function (item, encoding, callback) {
-            chunk.push(item);
-            if (chunk.length >= chunk_size) {
-                this.push(chunk.splice(0));
-            }
-            callback();
-        },
-        flush: function (callback) {
-            if (chunk.length) {
-                this.push(chunk.splice(0));
-            }
-            callback();
-        },
-    });
+    return stream_chunk(chunk_size);
 }
 
 module.exports = stream_group;

package/src/stream_map.js

@@ -1,7 +1,7 @@
 const stream = require('stream');
 
 /**
- * Transform each item by simple function.
+ * Transform each item using a simple function.
  */
 function stream_map(fn)
 {

package/src/stream_map_parallel.js

@@ -2,7 +2,7 @@ const Promise = require('bluebird');
 const stream = require('stream');
 
 /**
- * Transform each item by simple function in parallel.
+ * Transform each item using a simple function in parallel.
  */
 function stream_map_parallel({handler, concurrency})
 {

package/src/stream_progress.js

@@ -3,7 +3,7 @@ const make_progress = require('./make_progress');
 const stream = require('stream');
 
 /**
- * Monitor the progress of data through a pipe. Similar to UNIX `pv` command.
+ * Monitor the progress of data through a pipe, similar to the UNIX `pv` command.
  *
  * @similar https://www.npmjs.com/package/progress-stream
  */

package/src/stream_strpbrk.js

@@ -1,7 +1,7 @@
 const stream = require('stream');
 
 /**
- * Split input stream by consecutive delimiters in `chars`.
+ * Split the input stream by consecutive delimiters in `chars`
  */
 function stream_strpbrk(chars = '\r\n')
 {

package/src/stream_tap.js

@@ -0,0 +1,23 @@
+const stream = require('stream');
+
+/**
+ * Call `fn` on each item.
+ */
+function stream_tap(fn)
+{
+    return new stream.Transform({
+        objectMode: true,
+        transform: async function (item, encoding, callback) {
+            try {
+                await fn(item);
+                this.push(item, encoding);
+                callback();
+            }
+            catch (error) {
+                callback(error);
+            }
+        },
+    });
+}
+
+module.exports = stream_tap;

package/src/stream_through.js

@@ -1,23 +1,13 @@
-const stream = require('stream');
+const stream_tap = require('./stream_tap');
 
 /**
  * Call `fn` on each item.
+ *
+ * @deprecated Deprecated in favor of `stream_tap`.
  */
 function stream_through(fn)
 {
-    return new stream.Transform({
-        objectMode: true,
-        transform: function (item, encoding, callback) {
-            try {
-                fn(item);
-                this.push(item, encoding);
-                callback();
-            }
-            catch (error) {
-                callback(error);
-            }
-        },
-    });
+    return stream_tap(fn);
 }
 
 module.exports = stream_through;

package/src/stream_transform.js

@@ -1,22 +1,11 @@
-const stream = require('stream');
+const stream_map = require('./stream_map');
 
 /**
- * @deprecated Deprecated in favor of stream_map
+ * @deprecated Deprecated in favor of `stream_map`
  */
 function stream_transform(fn)
 {
-    return new stream.Transform({
-        objectMode: true,
-        transform: function (item, encoding, next) {
-            try {
-                this.push(fn(item));
-                next();
-            }
-            catch (error) {
-                next(error);
-            }
-        },
-    });
+    return stream_map(fn);
 }
 
 module.exports = stream_transform;

package/src/stream_promise.js

@@ -1,63 +0,0 @@
-const {finished} = require('stream/promises');
-
-// /**
-//  * Wait for a stream to finish with `await stream_promise(stream)`.
-//  *
-//  * @param stream
-//  * @returns {Promise}
-//  */
-// function stream_promise(stream)
-// {
-//     /**
-//      * https://stackoverflow.com/a/34310963/1478566
-//      * > end and finish are the same event BUT on different types of
-//      * > Streams.
-//      * >   * stream.Readable fires ONLY end and NEVER finish
-//      * >   * stream.Writable fires ONLY finish and NEVER end
-//      */
-//     return new Promise(function (resolve, reject) {
-//         stream.once('end', resolve); // Stream.Readable
-//         stream.once('finish', resolve); // Stream.Writable
-//         stream.once('error', reject);
-//         function end() { off(); resolve(); }
-//         function finish() { off(); resolve(); }
-//         function error() { off(); reject(); }
-//         function off() {
-//             stream.off('end', end);
-//             stream.off('finish', finish);
-//             stream.off('error', error);
-//         }
-//     });
-// }
-
-/**
- * Wait for a stream to finish with `await stream_promise(stream)`.
- *
- * https://nodejs.org/api/stream.html#stream_stream_finished_stream_options_callback
- * > Especially useful in error handling scenarios where a stream
- * > is destroyed prematurely (like an aborted HTTP request), and
- * > will not emit 'end' or 'finish'.
- *
- * @param stream
- * @returns {Promise<void>}
- * @deprecated Deprecated in favor of `stream.promises.finished`. Should be removed in the next major release.
- */
-function stream_promise(stream)
-{
-    // https://nodejs.org/api/stream.html#stream_stream_finished_stream_options_callback
-    // > stream.finished() leaves dangling event listeners (in particular
-    // > 'error', 'end', 'finish' and 'close') after callback has been
-    // > invoked. The reason for this is so that unexpected 'error'
-    // > events (due to incorrect stream implementations) do not cause
-    // > unexpected crashes. If this is unwanted behavior then the
-    // > returned cleanup function needs to be invoked in the callback:
-    // >
-    // >     const cleanup = finished(rs, (err) => {
-    // >         cleanup();
-    // >         // ...
-    // >     });
-    // >
-    return finished(stream);
-}
-
-module.exports = stream_promise;

package/src/stream_promise.test.js

@@ -1,14 +0,0 @@
-const fs = require('fs');
-const ignore = require('./ignore');
-const stream_promise = require('./stream_promise');
-
-describe('stream_promise', function () {
-    it('should handle ReadableStream', async function () {
-        this.timeout(100);
-        await stream_promise(fs.createReadStream(__filename).on('data', ignore));
-    });
-    it('should handle WritableStream', async function () {
-        this.timeout(100);
-        await stream_promise(fs.createWriteStream('/dev/null').end('hello\n'));
-    });
-});