@naturalcycles/nodejs-lib 15.22.0 → 15.23.0

package/dist/stream/transform/transformMap.js

@@ -1,11 +1,11 @@
 import { _hc } from '@naturalcycles/js-lib';
 import { _since } from '@naturalcycles/js-lib/datetime/time.util.js';
-import { _anyToError, ErrorMode } from '@naturalcycles/js-lib/error';
+import { _anyToError, _assert, ErrorMode } from '@naturalcycles/js-lib/error';
 import { _stringify } from '@naturalcycles/js-lib/string/stringify.js';
 import { END, SKIP, } from '@naturalcycles/js-lib/types';
 import through2Concurrent from 'through2-concurrent';
 import { yellow } from '../../colors/colors.js';
-import { pipelineClose } from '../stream.util.js';
+import { PIPELINE_GRACEFUL_ABORT } from '../stream.util.js';
 // doesn't work, cause here we don't construct our Transform instance ourselves
 // export class TransformMap extends AbortableTransform {}
 /**
@@ -22,11 +22,12 @@ import { pipelineClose } from '../stream.util.js';
  */
 export function transformMap(mapper, opt = {}) {
     const { concurrency = 16, highWaterMark = 64, predicate, // we now default to "no predicate" (meaning pass-everything)
-    errorMode = ErrorMode.THROW_IMMEDIATELY, onError, onDone, metric = 'stream', logger = console, } = opt;
+    errorMode = ErrorMode.THROW_IMMEDIATELY, onError, onDone, metric = 'stream', logger = console, signal, } = opt;
     const started = Date.now();
     let index = -1;
     let countOut = 0;
     let isSettled = false;
+    let ok = true;
     let errors = 0;
     const collectedErrors = []; // only used if errorMode == THROW_AGGREGATED
     return through2Concurrent.obj({
@@ -57,7 +58,7 @@ export function transformMap(mapper, opt = {}) {
                 // emit no error
                 try {
                     await onDone?.({
-                        ok: true,
+                        ok,
                         collectedErrors,
                         countErrors: errors,
                         countIn: index + 1,
@@ -84,7 +85,8 @@ export function transformMap(mapper, opt = {}) {
             if (res === END) {
                 isSettled = true;
                 logger.log(`transformMap END received at index ${currentIndex}`);
-                pipelineClose('transformMap', this, this.sourceReadable, this.streamDone, logger);
+                _assert(signal, 'signal is required when using END');
+                signal.abort(new Error(PIPELINE_GRACEFUL_ABORT));
                 return cb();
             }
             if (res === SKIP) {
@@ -110,19 +112,21 @@ export function transformMap(mapper, opt = {}) {
             }
             if (errorMode === ErrorMode.THROW_IMMEDIATELY) {
                 isSettled = true;
-                try {
-                    await onDone?.({
-                        ok: false,
-                        collectedErrors,
-                        countErrors: errors,
-                        countIn: index + 1,
-                        countOut,
-                        started,
-                    });
-                }
-                catch (err) {
-                    logger.error(err);
-                }
+                ok = false;
+                // Tests show that onDone is still called at `final` (second time),
+                // so, we no longer call it here
+                // try {
+                //   await onDone?.({
+                //     ok: false,
+                //     collectedErrors,
+                //     countErrors: errors,
+                //     countIn: index + 1,
+                //     countOut,
+                //     started,
+                //   })
+                // } catch (err) {
+                //   logger.error(err)
+                // }
                 return cb(err); // Emit error immediately
             }
             if (errorMode === ErrorMode.THROW_AGGREGATED) {

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

@@ -1,8 +1,8 @@
+import type { AbortableSignal } from '@naturalcycles/js-lib';
 import { ErrorMode } from '@naturalcycles/js-lib/error';
 import type { CommonLogger } from '@naturalcycles/js-lib/log';
 import type { IndexedMapper, Predicate } from '@naturalcycles/js-lib/types';
 import { END, SKIP } from '@naturalcycles/js-lib/types';
-import { AbortableTransform } from '../pipeline/pipeline.js';
 import type { TransformTyped } from '../stream.model.js';
 import type { TransformMapStats } from './transformMap.js';
 export interface TransformMapSyncOptions<IN = any, OUT = IN> {
@@ -45,8 +45,10 @@ export interface TransformMapSyncOptions<IN = any, OUT = IN> {
      */
     metric?: string;
     logger?: CommonLogger;
-}
-export declare class TransformMapSync extends AbortableTransform {
+    /**
+     * Allows to abort (gracefully stop) the stream from inside the Transform.
+     */
+    signal?: AbortableSignal;
 }
 /**
  * Sync (not async) version of transformMap.

package/dist/stream/transform/transformMapSync.js

@@ -1,24 +1,22 @@
-import { _anyToError, ErrorMode } from '@naturalcycles/js-lib/error';
+import { Transform } from 'node:stream';
+import { _anyToError, _assert, ErrorMode } from '@naturalcycles/js-lib/error';
 import { END, SKIP } from '@naturalcycles/js-lib/types';
 import { yellow } from '../../colors/colors.js';
-import { AbortableTransform } from '../pipeline/pipeline.js';
-import { pipelineClose } from '../stream.util.js';
-export class TransformMapSync extends AbortableTransform {
-}
+import { PIPELINE_GRACEFUL_ABORT } from '../stream.util.js';
 /**
  * Sync (not async) version of transformMap.
  * Supposedly faster, for cases when async is not needed.
  */
 export function transformMapSync(mapper, opt = {}) {
     const { predicate, // defaults to "no predicate" (pass everything)
-    errorMode = ErrorMode.THROW_IMMEDIATELY, onError, onDone, metric = 'stream', objectMode = true, logger = console, } = opt;
+    errorMode = ErrorMode.THROW_IMMEDIATELY, onError, onDone, metric = 'stream', objectMode = true, logger = console, signal, } = opt;
     const started = Date.now();
     let index = -1;
     let countOut = 0;
     let isSettled = false;
     let errors = 0;
     const collectedErrors = []; // only used if errorMode == THROW_AGGREGATED
-    return new TransformMapSync({
+    return new Transform({
         objectMode,
         ...opt,
         transform(chunk, _, cb) {
@@ -32,7 +30,8 @@ export function transformMapSync(mapper, opt = {}) {
                 if (v === END) {
                     isSettled = true; // will be checked later
                     logger.log(`transformMapSync END received at index ${currentIndex}`);
-                    pipelineClose('transformMapSync', this, this.sourceReadable, this.streamDone, logger);
+                    _assert(signal, 'signal is required when using END');
+                    signal.abort(new Error(PIPELINE_GRACEFUL_ABORT));
                     return cb();
                 }
                 if (v === SKIP) {

package/dist/stream/transform/transformTee.js

@@ -1,5 +1,5 @@
 import { Transform } from 'node:stream';
-import { _pipeline } from '../pipeline/pipeline.js';
+import { pipeline } from 'node:stream/promises';
 import { readableCreate } from '../readable/readableCreate.js';
 /**
  * Allows to "tee"/"fork" away from the "main pipeline" into the "secondary pipeline".
@@ -12,10 +12,12 @@ import { readableCreate } from '../readable/readableCreate.js';
  */
 export function transformTee(streams) {
     const readable = readableCreate();
-    const secondPipelinePromise = _pipeline([readable, ...streams]);
+    const secondPipelinePromise = pipeline([readable, ...streams]);
     return new Transform({
         objectMode: true,
         transform(chunk, _, cb) {
+            // todo: it's possible to start respecting backpressure,
+            // if we start to listen to the boolean output of .push()
             // pass to the "secondary" pipeline
             readable.push(chunk);
             // pass through to the "main" pipeline

package/dist/stream/writable/writableForEach.d.ts

@@ -1,6 +1,7 @@
 import type { AsyncIndexedMapper, IndexedMapper } from '@naturalcycles/js-lib/types';
 import type { WritableTyped } from '../stream.model.js';
 import { type TransformMapOptions } from '../transform/transformMap.js';
+import { type TransformMapSyncOptions } from '../transform/transformMapSync.js';
 /**
  * Just an alias to transformMap that declares OUT as void.
  */
@@ -8,4 +9,4 @@ export declare function writableForEach<IN = any>(mapper: AsyncIndexedMapper<IN,
 /**
  * Just an alias to transformMap that declares OUT as void.
  */
-export declare function writableForEachSync<IN = any>(mapper: IndexedMapper<IN, void>, opt?: TransformMapOptions<IN, void>): WritableTyped<IN>;
+export declare function writableForEachSync<IN = any>(mapper: IndexedMapper<IN, void>, opt?: TransformMapSyncOptions<IN, void>): WritableTyped<IN>;

package/dist/stream/writable/writableFork.js

@@ -1,5 +1,5 @@
 import { Writable } from 'node:stream';
-import { _pipeline } from '../pipeline/pipeline.js';
+import { pipeline } from 'node:stream/promises';
 import { readableCreate } from '../readable/readableCreate.js';
 /**
  * Allows "forking" a stream inside pipeline into a number of pipeline chains (2 or more).
@@ -14,7 +14,7 @@ export function writableFork(chains, opt) {
     const allChainsDone = Promise.all(chains.map(async (chain) => {
         const readable = readableCreate();
         readables.push(readable);
-        return await _pipeline([readable, ...chain]);
+        return await pipeline([readable, ...chain]);
     })).catch(err => {
         console.error(err); // ensure the error is logged
         throw err;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@naturalcycles/nodejs-lib",
   "type": "module",
-  "version": "15.22.0",
+  "version": "15.23.0",
   "dependencies": {
     "@naturalcycles/js-lib": "^15",
     "@types/js-yaml": "^4",

package/src/exec2/exec2.ts

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

package/src/stream/index.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/src/stream/ndjson/ndjsonMap.ts

@@ -1,13 +1,7 @@
 import { ErrorMode } from '@naturalcycles/js-lib/error/errorMode.js'
 import type { AbortableAsyncMapper } from '@naturalcycles/js-lib/types'
-import {
-  createReadStreamAsNDJSON,
-  createWriteStreamAsNDJSON,
-  transformFlatten,
-  type TransformLogProgressOptions,
-  type TransformMapOptions,
-} from '../index.js'
-import { _pipeline, transformLimit, transformLogProgress, transformMap } from '../index.js'
+import type { TransformLogProgressOptions, TransformMapOptions } from '../index.js'
+import { Pipeline } from '../pipeline.js'
 
 export interface NDJSONMapOptions<IN = any, OUT = IN>
   extends TransformMapOptions<IN, OUT>,
@@ -39,20 +33,16 @@ export async function ndjsonMap<IN = any, OUT = any>(
     outputFilePath,
   })
 
-  const readable = createReadStreamAsNDJSON(inputFilePath).take(
-    limitInput || Number.POSITIVE_INFINITY,
-  )
-
-  await _pipeline([
-    readable,
-    transformLogProgress({ metric: 'read', ...opt }),
-    transformMap(mapper, {
+  await Pipeline.fromNDJsonFile<IN>(inputFilePath)
+    .limitSource(limitInput)
+    .logProgress({ metric: 'read', ...opt })
+    .map(mapper, {
       errorMode: ErrorMode.SUPPRESS,
       ...opt,
-    }),
-    transformFlatten(),
-    transformLimit({ limit: limitOutput, sourceReadable: readable }),
-    transformLogProgress({ metric: 'saved', logEvery: logEveryOutput }),
-    ...createWriteStreamAsNDJSON(outputFilePath),
-  ])
+    })
+    .flattenIfNeeded()
+    // .typeCastAs<OUT>()
+    .limit(limitOutput)
+    .logProgress({ metric: 'saved', logEvery: logEveryOutput })
+    .toNDJsonFile(outputFilePath)
 }

package/src/stream/ndjson/ndjsonStreamForEach.ts

@@ -1,13 +1,8 @@
 import { ErrorMode } from '@naturalcycles/js-lib/error/errorMode.js'
 import type { AbortableAsyncMapper } from '@naturalcycles/js-lib/types'
-import { _pipeline } from '../pipeline/pipeline.js'
-import {
-  transformLogProgress,
-  type TransformLogProgressOptions,
-} from '../transform/transformLogProgress.js'
-import { transformMap, type TransformMapOptions } from '../transform/transformMap.js'
-import { writableVoid } from '../writable/writableVoid.js'
-import { createReadStreamAsNDJSON } from './createReadStreamAsNDJSON.js'
+import { Pipeline } from '../pipeline.js'
+import type { TransformLogProgressOptions } from '../transform/transformLogProgress.js'
+import type { TransformMapOptions } from '../transform/transformMap.js'
 
 export interface NDJSONStreamForEachOptions<IN = any>
   extends TransformMapOptions<IN, void>,
@@ -22,14 +17,12 @@ export async function ndjsonStreamForEach<T>(
   mapper: AbortableAsyncMapper<T, void>,
   opt: NDJSONStreamForEachOptions<T>,
 ): Promise<void> {
-  await _pipeline([
-    createReadStreamAsNDJSON(opt.inputFilePath),
-    transformMap<T, any>(mapper, {
+  await Pipeline.fromNDJsonFile<T>(opt.inputFilePath)
+    .map(mapper, {
       errorMode: ErrorMode.THROW_AGGREGATED,
       ...opt,
       predicate: () => true, // to log progress properly
-    }),
-    transformLogProgress(opt),
-    writableVoid(),
-  ])
+    })
+    .logProgress(opt)
+    .run()
 }

package/src/stream/pipeline.ts

@@ -0,0 +1,301 @@
+import { Readable, type Transform } from 'node:stream'
+import { pipeline } from 'node:stream/promises'
+import { createGzip } from 'node:zlib'
+import { createAbortableSignal } from '@naturalcycles/js-lib'
+import type {
+  AbortableAsyncMapper,
+  AsyncIndexedMapper,
+  AsyncPredicate,
+  END,
+  IndexedMapper,
+  Integer,
+  NonNegativeInteger,
+  PositiveInteger,
+  Predicate,
+  SKIP,
+} from '@naturalcycles/js-lib/types'
+import { fs2 } from '../fs/fs2.js'
+import { createReadStreamAsNDJSON } from './ndjson/createReadStreamAsNDJSON.js'
+import { transformToNDJson } from './ndjson/transformToNDJson.js'
+import type {
+  ReadableTyped,
+  TransformOptions,
+  TransformTyped,
+  WritableTyped,
+} from './stream.model.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,
+  type TransformLogProgressOptions,
+} from './transform/transformLogProgress.js'
+import { transformMap, type TransformMapOptions } from './transform/transformMap.js'
+import {
+  transformMapSimple,
+  type TransformMapSimpleOptions,
+} from './transform/transformMapSimple.js'
+import { transformMapSync, type TransformMapSyncOptions } from './transform/transformMapSync.js'
+import { transformOffset, type TransformOffsetOptions } from './transform/transformOffset.js'
+import { transformTap, type TransformTapOptions } from './transform/transformTap.js'
+import { transformThrottle, type TransformThrottleOptions } from './transform/transformThrottle.js'
+import { writablePushToArray } from './writable/writablePushToArray.js'
+import { writableVoid } from './writable/writableVoid.js'
+
+export class Pipeline<T> {
+  // biome-ignore lint/correctness/noUnusedPrivateClassMembers: ok
+  private readonly source: Readable
+  private transforms: NodeJS.ReadWriteStream[] = []
+  private destination?: NodeJS.WritableStream
+  private readableLimit?: Integer
+  private abortableSignal = createAbortableSignal()
+
+  private constructor(source: ReadableTyped<T>) {
+    this.source = source
+  }
+
+  static from<T>(source: ReadableTyped<T>): Pipeline<T> {
+    return new Pipeline(source)
+  }
+
+  /**
+   * Technically same as `fromIterable` (since Array is Iterable),
+   * but named a bit friendlier.
+   */
+  static fromArray<T>(input: T[]): Pipeline<T> {
+    return new Pipeline(Readable.from(input))
+  }
+
+  static fromIterable<T>(input: Iterable<T> | AsyncIterable<T>): Pipeline<T> {
+    return new Pipeline(Readable.from(input))
+  }
+
+  static fromNDJsonFile<T>(sourceFilePath: string): Pipeline<T> {
+    return new Pipeline(createReadStreamAsNDJSON<T>(sourceFilePath))
+  }
+
+  /**
+   * Limits the source Readable, but using `.take(limit)` on it.
+   * This is THE preferred way of limiting the source.
+   */
+  limitSource(limit: NonNegativeInteger | undefined): this {
+    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: NonNegativeInteger | undefined): this {
+    this.transforms.push(
+      transformLimit({
+        limit,
+        signal: this.abortableSignal,
+      }),
+    )
+    return this
+  }
+
+  chunk(chunkSize: PositiveInteger, opt?: TransformOptions): Pipeline<T[]> {
+    this.transforms.push(transformChunk(chunkSize, opt))
+    return this as any
+  }
+
+  flatten<TO>(this: Pipeline<readonly TO[]>): Pipeline<TO> {
+    this.transforms.push(transformFlatten())
+    return this as any
+  }
+
+  flattenIfNeeded(): Pipeline<T extends readonly (infer TO)[] ? TO : T> {
+    this.transforms.push(transformFlattenIfNeeded())
+    return this as any
+  }
+
+  // TransformLogProgressOptions intentionally doesn't have <T> passed, as it's inconvenient in many cases
+  logProgress(opt?: TransformLogProgressOptions): this {
+    this.transforms.push(transformLogProgress(opt))
+    return this
+  }
+
+  map<TO>(
+    mapper: AbortableAsyncMapper<T, TO | typeof SKIP | typeof END>,
+    opt?: TransformMapOptions<T, TO>,
+  ): Pipeline<TO> {
+    this.transforms.push(
+      transformMap(mapper, {
+        ...opt,
+        signal: this.abortableSignal,
+      }),
+    )
+    return this as any
+  }
+
+  mapSync<TO>(
+    mapper: IndexedMapper<T, TO | typeof SKIP | typeof END>,
+    opt?: TransformMapSyncOptions,
+  ): Pipeline<TO> {
+    this.transforms.push(
+      transformMapSync(mapper, {
+        ...opt,
+        signal: this.abortableSignal,
+      }),
+    )
+    return this as any
+  }
+
+  mapSimple<TO>(mapper: IndexedMapper<T, TO>, opt?: TransformMapSimpleOptions): Pipeline<TO> {
+    this.transforms.push(transformMapSimple(mapper, opt))
+    return this as any
+  }
+
+  filter(predicate: AsyncPredicate<T>, opt?: TransformMapOptions): this {
+    this.transforms.push(
+      transformMap(v => v, {
+        predicate,
+        ...opt,
+        signal: this.abortableSignal,
+      }),
+    )
+    return this
+  }
+
+  filterSync(predicate: Predicate<T>, opt?: TransformOptions): this {
+    this.transforms.push(transformFilterSync(predicate, opt))
+    return this
+  }
+
+  offset(opt: TransformOffsetOptions): this {
+    this.transforms.push(transformOffset(opt))
+    return this
+  }
+
+  tap(fn: AsyncIndexedMapper<T, any>, opt?: TransformTapOptions): this {
+    this.transforms.push(transformTap(fn, opt))
+    return this
+  }
+
+  throttle(opt: TransformThrottleOptions): this {
+    this.transforms.push(transformThrottle(opt))
+    return this
+  }
+
+  // todo: tee/fork
+
+  transform<TO>(transform: TransformTyped<T, TO>): Pipeline<TO> {
+    this.transforms.push(transform)
+    return this as any
+  }
+
+  /**
+   * 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> {
+    this.transforms.push(...transforms)
+    return this as any
+  }
+
+  /**
+   * Utility method just to conveniently type-cast the current Pipeline type.
+   * No runtime effect.
+   */
+  typeCastAs<TO>(): Pipeline<TO> {
+    return this as any
+  }
+
+  async toArray(opt?: TransformOptions): Promise<T[]> {
+    const arr: T[] = []
+    this.destination = writablePushToArray(arr, opt)
+    await this.run()
+    return arr
+  }
+
+  async toFile(outputFilePath: string): Promise<void> {
+    fs2.ensureFile(outputFilePath)
+    this.destination = fs2.createWriteStream(outputFilePath)
+    await this.run()
+  }
+
+  async toNDJsonFile(outputFilePath: string): Promise<void> {
+    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: WritableTyped<T>): Promise<void> {
+    this.destination = destination
+    await this.run()
+  }
+
+  async forEach(
+    fn: AsyncIndexedMapper<T, void>,
+    opt?: TransformMapOptions<T, void>,
+  ): Promise<void> {
+    this.transforms.push(
+      transformMap(fn, {
+        ...opt,
+        signal: this.abortableSignal,
+      }),
+    )
+    await this.run()
+  }
+
+  async forEachSync(
+    fn: IndexedMapper<T, void>,
+    opt?: TransformMapSyncOptions<T, void>,
+  ): Promise<void> {
+    this.transforms.push(
+      transformMapSync(fn, {
+        ...opt,
+        signal: this.abortableSignal,
+      }),
+    )
+    await this.run()
+  }
+
+  async run(): Promise<void> {
+    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 as any)?.message === PIPELINE_GRACEFUL_ABORT) {
+        console.log('pipeline gracefully aborted') // todo: this message may be removed later
+        return
+      }
+      throw err
+    }
+  }
+}

package/src/stream/stream.util.ts

@@ -1,29 +1 @@
-import type { Readable } from 'node:stream'
-import type { CommonLogger } from '@naturalcycles/js-lib/log'
-
-export function pipelineClose(
-  name: string,
-  readableDownstream: Readable,
-  sourceReadable: Readable | undefined,
-  streamDone: Promise<void> | undefined,
-  logger: CommonLogger,
-): void {
-  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'