@naturalcycles/nodejs-lib 15.21.0 → 15.23.0

package/dist/exec2/exec2.js

@@ -250,6 +250,7 @@ class Exec2 {
             console.log([
                 '  ',
                 dimGrey(envString),
+                // todo: only before first space
                 white(_substringAfterLast(cmd, '/')),
                 ...(opt.args || []),
             ]

package/dist/stream/index.d.ts

@@ -5,10 +5,10 @@ export * from './ndjson/ndjsonMap.js';
 export * from './ndjson/ndjsonStreamForEach.js';
 export * from './ndjson/transformJsonParse.js';
 export * from './ndjson/transformToNDJson.js';
-export * from './pipeline/pipeline.js';
+export * from './pipeline.js';
 export * from './progressLogger.js';
+export * from './readable/readableCombined.js';
 export * from './readable/readableCreate.js';
-export * from './readable/readableForEach.js';
 export * from './readable/readableFromArray.js';
 export * from './readable/readableToArray.js';
 export * from './stream.model.js';

package/dist/stream/index.js

@@ -5,10 +5,10 @@ export * from './ndjson/ndjsonMap.js';
 export * from './ndjson/ndjsonStreamForEach.js';
 export * from './ndjson/transformJsonParse.js';
 export * from './ndjson/transformToNDJson.js';
-export * from './pipeline/pipeline.js';
+export * from './pipeline.js';
 export * from './progressLogger.js';
+export * from './readable/readableCombined.js';
 export * from './readable/readableCreate.js';
-export * from './readable/readableForEach.js';
 export * from './readable/readableFromArray.js';
 export * from './readable/readableToArray.js';
 export * from './stream.model.js';

package/dist/stream/ndjson/ndjsonMap.d.ts

@@ -1,5 +1,5 @@
 import type { AbortableAsyncMapper } from '@naturalcycles/js-lib/types';
-import { type TransformLogProgressOptions, type TransformMapOptions } from '../index.js';
+import type { TransformLogProgressOptions, TransformMapOptions } from '../index.js';
 export interface NDJSONMapOptions<IN = any, OUT = IN> extends TransformMapOptions<IN, OUT>, TransformLogProgressOptions<IN> {
     inputFilePath: string;
     outputFilePath: string;

package/dist/stream/ndjson/ndjsonMap.js

@@ -1,6 +1,5 @@
 import { ErrorMode } from '@naturalcycles/js-lib/error/errorMode.js';
-import { createReadStreamAsNDJSON, createWriteStreamAsNDJSON, transformFlatten, } from '../index.js';
-import { _pipeline, transformLimit, transformLogProgress, transformMap } from '../index.js';
+import { Pipeline } from '../pipeline.js';
 /**
  * Unzips input file automatically, if it ends with `.gz`.
  * Zips output file automatically, if it ends with `.gz`.
@@ -11,17 +10,16 @@ export async function ndjsonMap(mapper, opt) {
         inputFilePath,
         outputFilePath,
     });
-    const readable = createReadStreamAsNDJSON(inputFilePath).take(limitInput || Number.POSITIVE_INFINITY);
-    await _pipeline([
-        readable,
-        transformLogProgress({ metric: 'read', ...opt }),
-        transformMap(mapper, {
-            errorMode: ErrorMode.SUPPRESS,
-            ...opt,
-        }),
-        transformFlatten(),
-        transformLimit({ limit: limitOutput, sourceReadable: readable }),
-        transformLogProgress({ metric: 'saved', logEvery: logEveryOutput }),
-        ...createWriteStreamAsNDJSON(outputFilePath),
-    ]);
+    await Pipeline.fromNDJsonFile(inputFilePath)
+        .limitSource(limitInput)
+        .logProgress({ metric: 'read', ...opt })
+        .map(mapper, {
+        errorMode: ErrorMode.SUPPRESS,
+        ...opt,
+    })
+        .flattenIfNeeded()
+        // .typeCastAs<OUT>()
+        .limit(limitOutput)
+        .logProgress({ metric: 'saved', logEvery: logEveryOutput })
+        .toNDJsonFile(outputFilePath);
 }

package/dist/stream/ndjson/ndjsonStreamForEach.d.ts

@@ -1,6 +1,6 @@
 import type { AbortableAsyncMapper } from '@naturalcycles/js-lib/types';
-import { type TransformLogProgressOptions } from '../transform/transformLogProgress.js';
-import { type TransformMapOptions } from '../transform/transformMap.js';
+import type { TransformLogProgressOptions } from '../transform/transformLogProgress.js';
+import type { TransformMapOptions } from '../transform/transformMap.js';
 export interface NDJSONStreamForEachOptions<IN = any> extends TransformMapOptions<IN, void>, TransformLogProgressOptions<IN> {
     inputFilePath: string;
 }

package/dist/stream/ndjson/ndjsonStreamForEach.js

@@ -1,21 +1,15 @@
 import { ErrorMode } from '@naturalcycles/js-lib/error/errorMode.js';
-import { _pipeline } from '../pipeline/pipeline.js';
-import { transformLogProgress, } from '../transform/transformLogProgress.js';
-import { transformMap } from '../transform/transformMap.js';
-import { writableVoid } from '../writable/writableVoid.js';
-import { createReadStreamAsNDJSON } from './createReadStreamAsNDJSON.js';
+import { Pipeline } from '../pipeline.js';
 /**
  * Convenience function to `forEach` through an ndjson file.
  */
 export async function ndjsonStreamForEach(mapper, opt) {
-    await _pipeline([
-        createReadStreamAsNDJSON(opt.inputFilePath),
-        transformMap(mapper, {
-            errorMode: ErrorMode.THROW_AGGREGATED,
-            ...opt,
-            predicate: () => true, // to log progress properly
-        }),
-        transformLogProgress(opt),
-        writableVoid(),
-    ]);
+    await Pipeline.fromNDJsonFile(opt.inputFilePath)
+        .map(mapper, {
+        errorMode: ErrorMode.THROW_AGGREGATED,
+        ...opt,
+        predicate: () => true, // to log progress properly
+    })
+        .logProgress(opt)
+        .run();
 }

package/dist/stream/ndjson/transformJsonParse.js

@@ -19,7 +19,6 @@ export function transformJsonParse(opt = {}) {
         writableObjectMode: false,
         readableObjectMode: true,
         // highWatermark increased, because it's proven to be faster: https://github.com/nodejs/node/pull/52037
-        // todo: it'll be default in Node 22, then we can remove this
         writableHighWaterMark: 64 * 1024,
         transform(chunk, _, cb) {
             try {

package/dist/stream/pipeline.d.ts

@@ -0,0 +1,79 @@
+import { type Transform } from 'node:stream';
+import type { AbortableAsyncMapper, AsyncIndexedMapper, AsyncPredicate, END, IndexedMapper, NonNegativeInteger, PositiveInteger, Predicate, SKIP } from '@naturalcycles/js-lib/types';
+import type { ReadableTyped, TransformOptions, TransformTyped, WritableTyped } from './stream.model.js';
+import { type TransformLogProgressOptions } from './transform/transformLogProgress.js';
+import { type TransformMapOptions } from './transform/transformMap.js';
+import { type TransformMapSimpleOptions } from './transform/transformMapSimple.js';
+import { type TransformMapSyncOptions } from './transform/transformMapSync.js';
+import { type TransformOffsetOptions } from './transform/transformOffset.js';
+import { type TransformTapOptions } from './transform/transformTap.js';
+import { type TransformThrottleOptions } from './transform/transformThrottle.js';
+export declare class Pipeline<T> {
+    private readonly source;
+    private transforms;
+    private destination?;
+    private readableLimit?;
+    private abortableSignal;
+    private constructor();
+    static from<T>(source: ReadableTyped<T>): Pipeline<T>;
+    /**
+     * Technically same as `fromIterable` (since Array is Iterable),
+     * but named a bit friendlier.
+     */
+    static fromArray<T>(input: T[]): Pipeline<T>;
+    static fromIterable<T>(input: Iterable<T> | AsyncIterable<T>): Pipeline<T>;
+    static fromNDJsonFile<T>(sourceFilePath: string): Pipeline<T>;
+    /**
+     * Limits the source Readable, but using `.take(limit)` on it.
+     * This is THE preferred way of limiting the source.
+     */
+    limitSource(limit: NonNegativeInteger | undefined): this;
+    /**
+     * If possible - STRONGLY PREFER applying `.take(limit)` on the source Readable,
+     * as it's a clean graceful way of limiting the Readable. Example:
+     *
+     * Pipeline.from(myReadable.take(10))
+     *
+     * or
+     *
+     * Pipeline
+     *   .from(myReadable)
+     *   .limitSource(10)
+     *
+     * If applying `take` on Readable is not possible - use this method at your own risk.
+     * Why warning?
+     * The limit works by aborting the stream, and then catching the error - certainly
+     * less clean than `.take()` on the source.
+     */
+    limit(limit: NonNegativeInteger | undefined): this;
+    chunk(chunkSize: PositiveInteger, opt?: TransformOptions): Pipeline<T[]>;
+    flatten<TO>(this: Pipeline<readonly TO[]>): Pipeline<TO>;
+    flattenIfNeeded(): Pipeline<T extends readonly (infer TO)[] ? TO : T>;
+    logProgress(opt?: TransformLogProgressOptions): this;
+    map<TO>(mapper: AbortableAsyncMapper<T, TO | typeof SKIP | typeof END>, opt?: TransformMapOptions<T, TO>): Pipeline<TO>;
+    mapSync<TO>(mapper: IndexedMapper<T, TO | typeof SKIP | typeof END>, opt?: TransformMapSyncOptions): Pipeline<TO>;
+    mapSimple<TO>(mapper: IndexedMapper<T, TO>, opt?: TransformMapSimpleOptions): Pipeline<TO>;
+    filter(predicate: AsyncPredicate<T>, opt?: TransformMapOptions): this;
+    filterSync(predicate: Predicate<T>, opt?: TransformOptions): this;
+    offset(opt: TransformOffsetOptions): this;
+    tap(fn: AsyncIndexedMapper<T, any>, opt?: TransformTapOptions): this;
+    throttle(opt: TransformThrottleOptions): this;
+    transform<TO>(transform: TransformTyped<T, TO>): Pipeline<TO>;
+    /**
+     * Helper method to add multiple transforms at once.
+     * Not type safe! Prefer using singular `transform()` multiple times for type safety.
+     */
+    transformMany<TO>(transforms: Transform[]): Pipeline<TO>;
+    /**
+     * Utility method just to conveniently type-cast the current Pipeline type.
+     * No runtime effect.
+     */
+    typeCastAs<TO>(): Pipeline<TO>;
+    toArray(opt?: TransformOptions): Promise<T[]>;
+    toFile(outputFilePath: string): Promise<void>;
+    toNDJsonFile(outputFilePath: string): Promise<void>;
+    to(destination: WritableTyped<T>): Promise<void>;
+    forEach(fn: AsyncIndexedMapper<T, void>, opt?: TransformMapOptions<T, void>): Promise<void>;
+    forEachSync(fn: IndexedMapper<T, void>, opt?: TransformMapSyncOptions<T, void>): Promise<void>;
+    run(): Promise<void>;
+}

package/dist/stream/pipeline.js

@@ -0,0 +1,220 @@
+import { Readable } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import { createGzip } from 'node:zlib';
+import { createAbortableSignal } from '@naturalcycles/js-lib';
+import { fs2 } from '../fs/fs2.js';
+import { createReadStreamAsNDJSON } from './ndjson/createReadStreamAsNDJSON.js';
+import { transformToNDJson } from './ndjson/transformToNDJson.js';
+import { PIPELINE_GRACEFUL_ABORT } from './stream.util.js';
+import { transformChunk } from './transform/transformChunk.js';
+import { transformFilterSync } from './transform/transformFilter.js';
+import { transformFlatten, transformFlattenIfNeeded } from './transform/transformFlatten.js';
+import { transformLimit } from './transform/transformLimit.js';
+import { transformLogProgress, } from './transform/transformLogProgress.js';
+import { transformMap } from './transform/transformMap.js';
+import { transformMapSimple, } from './transform/transformMapSimple.js';
+import { transformMapSync } from './transform/transformMapSync.js';
+import { transformOffset } from './transform/transformOffset.js';
+import { transformTap } from './transform/transformTap.js';
+import { transformThrottle } from './transform/transformThrottle.js';
+import { writablePushToArray } from './writable/writablePushToArray.js';
+import { writableVoid } from './writable/writableVoid.js';
+export class Pipeline {
+    // biome-ignore lint/correctness/noUnusedPrivateClassMembers: ok
+    source;
+    transforms = [];
+    destination;
+    readableLimit;
+    abortableSignal = createAbortableSignal();
+    constructor(source) {
+        this.source = source;
+    }
+    static from(source) {
+        return new Pipeline(source);
+    }
+    /**
+     * Technically same as `fromIterable` (since Array is Iterable),
+     * but named a bit friendlier.
+     */
+    static fromArray(input) {
+        return new Pipeline(Readable.from(input));
+    }
+    static fromIterable(input) {
+        return new Pipeline(Readable.from(input));
+    }
+    static fromNDJsonFile(sourceFilePath) {
+        return new Pipeline(createReadStreamAsNDJSON(sourceFilePath));
+    }
+    /**
+     * Limits the source Readable, but using `.take(limit)` on it.
+     * This is THE preferred way of limiting the source.
+     */
+    limitSource(limit) {
+        this.readableLimit = limit;
+        return this;
+    }
+    /**
+     * If possible - STRONGLY PREFER applying `.take(limit)` on the source Readable,
+     * as it's a clean graceful way of limiting the Readable. Example:
+     *
+     * Pipeline.from(myReadable.take(10))
+     *
+     * or
+     *
+     * Pipeline
+     *   .from(myReadable)
+     *   .limitSource(10)
+     *
+     * If applying `take` on Readable is not possible - use this method at your own risk.
+     * Why warning?
+     * The limit works by aborting the stream, and then catching the error - certainly
+     * less clean than `.take()` on the source.
+     */
+    limit(limit) {
+        this.transforms.push(transformLimit({
+            limit,
+            signal: this.abortableSignal,
+        }));
+        return this;
+    }
+    chunk(chunkSize, opt) {
+        this.transforms.push(transformChunk(chunkSize, opt));
+        return this;
+    }
+    flatten() {
+        this.transforms.push(transformFlatten());
+        return this;
+    }
+    flattenIfNeeded() {
+        this.transforms.push(transformFlattenIfNeeded());
+        return this;
+    }
+    // TransformLogProgressOptions intentionally doesn't have <T> passed, as it's inconvenient in many cases
+    logProgress(opt) {
+        this.transforms.push(transformLogProgress(opt));
+        return this;
+    }
+    map(mapper, opt) {
+        this.transforms.push(transformMap(mapper, {
+            ...opt,
+            signal: this.abortableSignal,
+        }));
+        return this;
+    }
+    mapSync(mapper, opt) {
+        this.transforms.push(transformMapSync(mapper, {
+            ...opt,
+            signal: this.abortableSignal,
+        }));
+        return this;
+    }
+    mapSimple(mapper, opt) {
+        this.transforms.push(transformMapSimple(mapper, opt));
+        return this;
+    }
+    filter(predicate, opt) {
+        this.transforms.push(transformMap(v => v, {
+            predicate,
+            ...opt,
+            signal: this.abortableSignal,
+        }));
+        return this;
+    }
+    filterSync(predicate, opt) {
+        this.transforms.push(transformFilterSync(predicate, opt));
+        return this;
+    }
+    offset(opt) {
+        this.transforms.push(transformOffset(opt));
+        return this;
+    }
+    tap(fn, opt) {
+        this.transforms.push(transformTap(fn, opt));
+        return this;
+    }
+    throttle(opt) {
+        this.transforms.push(transformThrottle(opt));
+        return this;
+    }
+    // todo: tee/fork
+    transform(transform) {
+        this.transforms.push(transform);
+        return this;
+    }
+    /**
+     * Helper method to add multiple transforms at once.
+     * Not type safe! Prefer using singular `transform()` multiple times for type safety.
+     */
+    transformMany(transforms) {
+        this.transforms.push(...transforms);
+        return this;
+    }
+    /**
+     * Utility method just to conveniently type-cast the current Pipeline type.
+     * No runtime effect.
+     */
+    typeCastAs() {
+        return this;
+    }
+    async toArray(opt) {
+        const arr = [];
+        this.destination = writablePushToArray(arr, opt);
+        await this.run();
+        return arr;
+    }
+    async toFile(outputFilePath) {
+        fs2.ensureFile(outputFilePath);
+        this.destination = fs2.createWriteStream(outputFilePath);
+        await this.run();
+    }
+    async toNDJsonFile(outputFilePath) {
+        fs2.ensureFile(outputFilePath);
+        this.transforms.push(transformToNDJson());
+        if (outputFilePath.endsWith('.gz')) {
+            this.transforms.push(createGzip({
+            // chunkSize: 64 * 1024, // no observed speedup
+            }));
+        }
+        this.destination = fs2.createWriteStream(outputFilePath, {
+        // highWaterMark: 64 * 1024, // no observed speedup
+        });
+        await this.run();
+    }
+    async to(destination) {
+        this.destination = destination;
+        await this.run();
+    }
+    async forEach(fn, opt) {
+        this.transforms.push(transformMap(fn, {
+            ...opt,
+            signal: this.abortableSignal,
+        }));
+        await this.run();
+    }
+    async forEachSync(fn, opt) {
+        this.transforms.push(transformMapSync(fn, {
+            ...opt,
+            signal: this.abortableSignal,
+        }));
+        await this.run();
+    }
+    async run() {
+        this.destination ||= writableVoid();
+        let { source } = this;
+        if (this.readableLimit) {
+            source = source.take(this.readableLimit);
+        }
+        try {
+            await pipeline([source, ...this.transforms, this.destination], {
+                signal: this.abortableSignal,
+            });
+        }
+        catch (err) {
+            if (err instanceof Error && err.cause?.message === PIPELINE_GRACEFUL_ABORT) {
+                console.log('pipeline gracefully aborted'); // todo: this message may be removed later
+                return;
+            }
+            throw err;
+        }
+    }
+}

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

@@ -0,0 +1,30 @@
+import { Readable } from 'node:stream';
+import type { ReadableTyped } from '@naturalcycles/nodejs-lib/stream';
+/**
+ * Allows to combine multiple Readables into 1 Readable.
+ * As soon as any of the input Readables emit - the output Readable emits
+ * (passes through).
+ * Order is not preserved in any way, first come first served!
+ *
+ * Readable completes when all input Readables complete.
+ *
+ * @experimental
+ */
+export declare class ReadableCombined<T> extends Readable implements ReadableTyped<T> {
+    inputs: Readable[];
+    static create<T>(inputs: Readable[]): ReadableCombined<T>;
+    private constructor();
+    /**
+     * If defined - we are in Paused mode
+     * and should await the lock to be resolved before proceeding.
+     *
+     * If not defined - we are in Flowing mode, no limits in data flow.
+     */
+    private lock?;
+    private countIn;
+    private countOut;
+    private countReads;
+    private start;
+    _read(): void;
+    private logStats;
+}

package/dist/stream/readable/readableCombined.js

@@ -0,0 +1,77 @@
+import { Readable } from 'node:stream';
+import { pDefer } from '@naturalcycles/js-lib/promise/pDefer.js';
+import { pMap } from '@naturalcycles/js-lib/promise/pMap.js';
+/**
+ * Allows to combine multiple Readables into 1 Readable.
+ * As soon as any of the input Readables emit - the output Readable emits
+ * (passes through).
+ * Order is not preserved in any way, first come first served!
+ *
+ * Readable completes when all input Readables complete.
+ *
+ * @experimental
+ */
+export class ReadableCombined extends Readable {
+    inputs;
+    static create(inputs) {
+        return new ReadableCombined(inputs);
+    }
+    constructor(inputs) {
+        super({ objectMode: true });
+        this.inputs = inputs;
+        void this.start();
+    }
+    /**
+     * If defined - we are in Paused mode
+     * and should await the lock to be resolved before proceeding.
+     *
+     * If not defined - we are in Flowing mode, no limits in data flow.
+     */
+    lock;
+    // biome-ignore lint/correctness/noUnusedPrivateClassMembers: ok
+    countIn = 0;
+    // biome-ignore lint/correctness/noUnusedPrivateClassMembers: ok
+    countOut = 0;
+    // biome-ignore lint/correctness/noUnusedPrivateClassMembers: ok
+    countReads = 0;
+    async start() {
+        await pMap(this.inputs, async (input, i) => {
+            for await (const item of input) {
+                this.countIn++;
+                this.logStats();
+                if (this.lock) {
+                    await this.lock;
+                    // lock is undefined at this point
+                }
+                const shouldContinue = this.push(item);
+                this.countOut++;
+                if (!shouldContinue && !this.lock) {
+                    this.lock = pDefer();
+                    console.log(`ReadableCombined.push #${i} returned false, pausing the flow!`);
+                }
+            }
+            console.log(`ReadableCombined: input #${i} done`);
+        });
+        console.log(`ReadableCombined: all inputs done!`);
+        this.push(null);
+    }
+    _read() {
+        this.countReads++;
+        if (this.lock) {
+            console.log(`ReadableCombined._read: resuming the flow!`);
+            // calling it in this order is important!
+            // this.lock should be undefined BEFORE we call lock.resolve()
+            const { lock } = this;
+            this.lock = undefined;
+            lock.resolve();
+        }
+    }
+    logStats() {
+        const { countIn, countOut, countReads } = this;
+        console.log({
+            countIn,
+            countOut,
+            countReads,
+        });
+    }
+}

package/dist/stream/stream.util.d.ts

@@ -1,3 +1 @@
-import type { Readable } from 'node:stream';
-import type { CommonLogger } from '@naturalcycles/js-lib/log';
-export declare function pipelineClose(name: string, readableDownstream: Readable, sourceReadable: Readable | undefined, streamDone: Promise<void> | undefined, logger: CommonLogger): void;
+export declare const PIPELINE_GRACEFUL_ABORT = "PIPELINE_GRACEFUL_ABORT";

package/dist/stream/stream.util.js

@@ -1,20 +1 @@
-export function pipelineClose(name, readableDownstream, sourceReadable, streamDone, logger) {
-    readableDownstream.push(null); // this closes the stream, so downstream Readable will receive `end` and won't write anything
-    if (!sourceReadable) {
-        logger.warn(`${name} sourceReadable is not provided, readable stream will not be stopped`);
-    }
-    else {
-        logger.log(`${name} is calling readable.unpipe() to pause the stream`);
-        sourceReadable.unpipe(); // it is expected to pause the stream
-        if (!streamDone) {
-            logger.log(`${name} streamDone is not provided, will do readable.destroy right away`);
-            sourceReadable.destroy();
-        }
-        else {
-            void streamDone.then(() => {
-                logger.log(`${name} streamDone, calling readable.destroy()`);
-                sourceReadable.destroy(); // this throws ERR_STREAM_PREMATURE_CLOSE
-            });
-        }
-    }
-}
+export const PIPELINE_GRACEFUL_ABORT = 'PIPELINE_GRACEFUL_ABORT';

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

@@ -1,14 +1,11 @@
+import type { PositiveInteger } from '@naturalcycles/js-lib/types';
 import type { TransformOptions, TransformTyped } from '../stream.model.js';
-export interface TransformChunkOptions extends TransformOptions {
-    /**
-     * How many items to include in each chunk.
-     * Last chunk will contain the remaining items, possibly less than chunkSize.
-     */
-    chunkSize: number;
-}
 /**
  * Similar to RxJS bufferCount(),
  * allows to "chunk" the input stream into chunks of `opt.chunkSize` size.
  * Last chunk will contain the remaining items, possibly less than chunkSize.
+ *
+ * `chunkSize` indicates how many items to include in each chunk.
+ * Last chunk will contain the remaining items, possibly less than chunkSize.
  */
-export declare function transformChunk<IN = any>(opt: TransformChunkOptions): TransformTyped<IN, IN[]>;
+export declare function transformChunk<IN = any>(chunkSize: PositiveInteger, opt?: TransformOptions): TransformTyped<IN, IN[]>;

package/dist/stream/transform/transformChunk.js

@@ -3,9 +3,11 @@ import { Transform } from 'node:stream';
  * Similar to RxJS bufferCount(),
  * allows to "chunk" the input stream into chunks of `opt.chunkSize` size.
  * Last chunk will contain the remaining items, possibly less than chunkSize.
+ *
+ * `chunkSize` indicates how many items to include in each chunk.
+ * Last chunk will contain the remaining items, possibly less than chunkSize.
  */
-export function transformChunk(opt) {
-    const { chunkSize } = opt;
+export function transformChunk(chunkSize, opt) {
     let buf = [];
     return new Transform({
         objectMode: true,

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

@@ -1,2 +1,3 @@
 import type { TransformTyped } from '../stream.model.js';
 export declare function transformFlatten<T>(): TransformTyped<T[], T>;
+export declare function transformFlattenIfNeeded<T>(): TransformTyped<T[], T>;

package/dist/stream/transform/transformFlatten.js

@@ -3,15 +3,26 @@ export function transformFlatten() {
     return new Transform({
         objectMode: true,
         transform(chunk, _, cb) {
-            if (!Array.isArray(chunk)) {
-                // As a safety precaution, to not crash the pipeline - push as is
-                this.push(chunk);
+            for (const item of chunk) {
+                this.push(item);
             }
-            else {
+            cb(); // acknowledge
+        },
+    });
+}
+export function transformFlattenIfNeeded() {
+    return new Transform({
+        objectMode: true,
+        transform(chunk, _, cb) {
+            if (Array.isArray(chunk)) {
                 for (const item of chunk) {
                     this.push(item);
                 }
             }
+            else {
+                // As a safety precaution, to not crash the pipeline - push as is
+                this.push(chunk);
+            }
             cb(); // acknowledge
         },
     });