@naturalcycles/nodejs-lib 15.22.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,11 +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,11 +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/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/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
         },
     });

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

@@ -1,6 +1,4 @@
-import type { Readable } from 'node:stream';
-import type { CommonLogger } from '@naturalcycles/js-lib/log';
-import { AbortableTransform } from '../pipeline/pipeline.js';
+import type { AbortableSignal } from '@naturalcycles/js-lib';
 import type { TransformOptions, TransformTyped } from '../stream.model.js';
 export interface TransformLimitOptions extends TransformOptions {
     /**
@@ -8,29 +6,8 @@ export interface TransformLimitOptions extends TransformOptions {
      */
     limit?: number;
     /**
-     * If provided (recommended!) - it will call readable.destroy() on limit.
-     * Without it - it will only stop the downstream consumers, but won't stop
-     * the Readable ("source" of the stream).
-     * It is almost always crucial to stop the Source too, so, please provide the Readable here!
+     * Allows to abort (gracefully stop) the stream from inside the Transform.
      */
-    sourceReadable?: Readable;
-    /**
-     * Please provide it (a Promise that resolves when the Stream is done, e.g finished consuming things)
-     * to be able to wait for Consumers before calling `readable.destroy`.
-     * Has no effect if `readable` is not provided.
-     */
-    streamDone?: Promise<void>;
-    logger?: CommonLogger;
-    /**
-     * Set to true to enable additional debug messages, e.g it'll log
-     * when readable still emits values after the limit is reached.
-     */
-    debug?: boolean;
-}
-/**
- * Class only exists to be able to do `instanceof TransformLimit`
- * and to set sourceReadable+streamDone to it in `_pipeline`.
- */
-export declare class TransformLimit extends AbortableTransform {
+    signal: AbortableSignal;
 }
 export declare function transformLimit<IN>(opt: TransformLimitOptions): TransformTyped<IN, IN>;

package/dist/stream/transform/transformLimit.js

@@ -1,41 +1,32 @@
-import { AbortableTransform } from '../pipeline/pipeline.js';
-import { pipelineClose } from '../stream.util.js';
+import { Transform } from 'node:stream';
+import { PIPELINE_GRACEFUL_ABORT } from '../stream.util.js';
 import { transformNoOp } from './transformNoOp.js';
-/**
- * Class only exists to be able to do `instanceof TransformLimit`
- * and to set sourceReadable+streamDone to it in `_pipeline`.
- */
-export class TransformLimit extends AbortableTransform {
-}
 export function transformLimit(opt) {
-    const { logger = console, limit, debug } = opt;
+    const { limit, signal } = opt;
     if (!limit) {
-        // No limit - returning pass-through transform
         return transformNoOp();
     }
     let i = 0; // so we start first chunk with 1
     let ended = false;
-    return new TransformLimit({
+    return new Transform({
         objectMode: true,
         ...opt,
         transform(chunk, _, cb) {
+            if (ended) {
+                return;
+            }
             i++;
             if (i === limit) {
                 ended = true;
-                logger.log(`transformLimit of ${limit} reached`);
                 this.push(chunk);
-                pipelineClose('transformLimit', this, opt.sourceReadable || this.sourceReadable, opt.streamDone || this.streamDone, logger);
-                cb(); // after pause
-            }
-            else if (!ended) {
-                cb(null, chunk);
-            }
-            else {
-                if (debug)
-                    logger.log(`transformLimit.transform after limit`, i);
-                // If we ever HANG (don't call cb) - Node will do process.exit(0) to us
-                cb(); // ended, don't emit anything
+                this.push(null); // tell downstream that we're done
+                cb();
+                queueMicrotask(() => {
+                    signal.abort(new Error(PIPELINE_GRACEFUL_ABORT));
+                });
+                return;
             }
+            cb(null, chunk);
         },
     });
 }

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

@@ -1,3 +1,4 @@
+import { type AbortableSignal } from '@naturalcycles/js-lib';
 import { ErrorMode } from '@naturalcycles/js-lib/error';
 import type { CommonLogger } from '@naturalcycles/js-lib/log';
 import { type AbortableAsyncMapper, type AsyncPredicate, END, type PositiveInteger, type Promisable, SKIP, type StringMap, type UnixTimestampMillis } from '@naturalcycles/js-lib/types';
@@ -57,6 +58,10 @@ export interface TransformMapOptions<IN = any, OUT = IN> {
      */
     metric?: string;
     logger?: CommonLogger;
+    /**
+     * Allows to abort (gracefully stop) the stream from inside the Transform.
+     */
+    signal?: AbortableSignal;
 }
 export interface TransformMapStats {
     /**