@naturalcycles/nodejs-lib 12.99.0 → 12.100.0

package/dist/index.d.ts

@@ -51,6 +51,7 @@ export * from './stream/transform/transformSplit';
 export * from './stream/transform/transformTap';
 export * from './stream/transform/transformToArray';
 export * from './stream/transform/transformToString';
+export * from './stream/transform/transformTee';
 export * from './stream/transform/worker/baseWorkerClass';
 export * from './stream/transform/worker/transformMultiThreaded';
 export * from './stream/transform/worker/transformMultiThreaded.model';

package/dist/index.js

@@ -56,6 +56,7 @@ tslib_1.__exportStar(require("./stream/transform/transformSplit"), exports);
 tslib_1.__exportStar(require("./stream/transform/transformTap"), exports);
 tslib_1.__exportStar(require("./stream/transform/transformToArray"), exports);
 tslib_1.__exportStar(require("./stream/transform/transformToString"), exports);
+tslib_1.__exportStar(require("./stream/transform/transformTee"), exports);
 tslib_1.__exportStar(require("./stream/transform/worker/baseWorkerClass"), exports);
 tslib_1.__exportStar(require("./stream/transform/worker/transformMultiThreaded"), exports);
 tslib_1.__exportStar(require("./stream/transform/worker/transformMultiThreaded.model"), exports);

package/dist/stream/readable/readableCreate.d.ts

@@ -9,7 +9,7 @@ import { ReadableTyped } from '../stream.model';
  *
  * Caution!
  * The implementation of this Readable is not fully compliant,
- * e.g the read() method doesn't return anything, so, it will hand the Node process (or cause it to process.exit(0))
+ * e.g the read() method doesn't return anything, so, it will hang the Node process (or cause it to process.exit(0))
  * if read() will be called AFTER everything was pushed and Readable is closed (by pushing `null`).
  * Beware of it when e.g doing unit testing! Jest prefers to hang (not exit-0).
  *

package/dist/stream/readable/readableCreate.js

@@ -10,7 +10,7 @@ const node_stream_1 = require("node:stream");
  *
  * Caution!
  * The implementation of this Readable is not fully compliant,
- * e.g the read() method doesn't return anything, so, it will hand the Node process (or cause it to process.exit(0))
+ * e.g the read() method doesn't return anything, so, it will hang the Node process (or cause it to process.exit(0))
  * if read() will be called AFTER everything was pushed and Readable is closed (by pushing `null`).
  * Beware of it when e.g doing unit testing! Jest prefers to hang (not exit-0).
  *

package/dist/stream/transform/transformTee.d.ts

@@ -0,0 +1,14 @@
+/// <reference types="node" />
+import { TransformTyped } from '../stream.model';
+type AnyStream = NodeJS.WritableStream | NodeJS.ReadWriteStream;
+/**
+ * Allows to "tee"/"fork" away from the "main pipeline" into the "secondary pipeline".
+ *
+ * Important, that the main pipeline works "as normal", keeps backpressure, etc.
+ * Secondary pipeline DOES NOT keep backpressure.
+ * Therefor, the "slowest" pipeline should be made Primary (to keep backpressure).
+ *
+ * @experimental
+ */
+export declare function transformTee<T>(streams: AnyStream[]): TransformTyped<T>;
+export {};

package/dist/stream/transform/transformTee.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.transformTee = void 0;
+const node_stream_1 = require("node:stream");
+const pipeline_1 = require("../pipeline/pipeline");
+const readableCreate_1 = require("../readable/readableCreate");
+/**
+ * Allows to "tee"/"fork" away from the "main pipeline" into the "secondary pipeline".
+ *
+ * Important, that the main pipeline works "as normal", keeps backpressure, etc.
+ * Secondary pipeline DOES NOT keep backpressure.
+ * Therefor, the "slowest" pipeline should be made Primary (to keep backpressure).
+ *
+ * @experimental
+ */
+function transformTee(streams) {
+    const readable = (0, readableCreate_1.readableCreate)();
+    const secondPipelinePromise = (0, pipeline_1._pipeline)([readable, ...streams]);
+    return new node_stream_1.Transform({
+        objectMode: true,
+        transform(chunk, _, cb) {
+            // pass to the "secondary" pipeline
+            readable.push(chunk);
+            // pass through to the "main" pipeline
+            cb(null, chunk);
+        },
+        async final(cb) {
+            console.log('transformTee final');
+            // Pushing null "closes"/ends the secondary pipeline correctly
+            readable.push(null);
+            // Second pipeline is expected to finish now, let's await it
+            await secondPipelinePromise;
+            console.log('transformTee final secondPipeline done');
+            // Because second pipeline is done - now we can signal main pipeline to be done as well
+            cb();
+        },
+    });
+}
+exports.transformTee = transformTee;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@naturalcycles/nodejs-lib",
-  "version": "12.99.0",
+  "version": "12.100.0",
   "scripts": {
     "prepare": "husky install",
     "docs-serve": "vuepress dev docs",

package/src/index.ts

@@ -51,6 +51,7 @@ export * from './stream/transform/transformSplit'
 export * from './stream/transform/transformTap'
 export * from './stream/transform/transformToArray'
 export * from './stream/transform/transformToString'
+export * from './stream/transform/transformTee'
 export * from './stream/transform/worker/baseWorkerClass'
 export * from './stream/transform/worker/transformMultiThreaded'
 export * from './stream/transform/worker/transformMultiThreaded.model'

package/src/stream/readable/readableCreate.ts

@@ -9,7 +9,7 @@ import { ReadableTyped } from '../stream.model'
  *
  * Caution!
  * The implementation of this Readable is not fully compliant,
- * e.g the read() method doesn't return anything, so, it will hand the Node process (or cause it to process.exit(0))
+ * e.g the read() method doesn't return anything, so, it will hang the Node process (or cause it to process.exit(0))
  * if read() will be called AFTER everything was pushed and Readable is closed (by pushing `null`).
  * Beware of it when e.g doing unit testing! Jest prefers to hang (not exit-0).
  *

package/src/stream/transform/transformTee.ts

@@ -0,0 +1,45 @@
+import { Transform } from 'node:stream'
+import { _pipeline } from '../pipeline/pipeline'
+import { readableCreate } from '../readable/readableCreate'
+import { TransformTyped } from '../stream.model'
+
+type AnyStream = NodeJS.WritableStream | NodeJS.ReadWriteStream
+
+/**
+ * Allows to "tee"/"fork" away from the "main pipeline" into the "secondary pipeline".
+ *
+ * Important, that the main pipeline works "as normal", keeps backpressure, etc.
+ * Secondary pipeline DOES NOT keep backpressure.
+ * Therefor, the "slowest" pipeline should be made Primary (to keep backpressure).
+ *
+ * @experimental
+ */
+export function transformTee<T>(streams: AnyStream[]): TransformTyped<T> {
+  const readable = readableCreate<T>()
+
+  const secondPipelinePromise = _pipeline([readable, ...streams])
+
+  return new Transform({
+    objectMode: true,
+    transform(chunk: T, _, cb) {
+      // pass to the "secondary" pipeline
+      readable.push(chunk)
+
+      // pass through to the "main" pipeline
+      cb(null, chunk)
+    },
+    async final(cb) {
+      console.log('transformTee final')
+
+      // Pushing null "closes"/ends the secondary pipeline correctly
+      readable.push(null)
+
+      // Second pipeline is expected to finish now, let's await it
+      await secondPipelinePromise
+      console.log('transformTee final secondPipeline done')
+
+      // Because second pipeline is done - now we can signal main pipeline to be done as well
+      cb()
+    },
+  })
+}