@naturalcycles/nodejs-lib/dist/stream/transform/transformMap.d.ts

Standard library for Node.js

import type { AbortableSignal } from '@naturalcycles/js-lib';
import { ErrorMode } from '@naturalcycles/js-lib/error';
import { END, SKIP } from '@naturalcycles/js-lib/types';
import type { AbortableAsyncMapper, AsyncPredicate, NumberOfSeconds, PositiveInteger, Predicate, Promisable, StringMap, UnixTimestampMillis } from '@naturalcycles/js-lib/types';
import type { TransformOptions, TransformTyped } from '../stream.model.js';
export interface TransformMapOptions<IN = any, OUT = IN> extends TransformOptions {
    /**
     * Predicate to filter outgoing results (after mapper).
     * Allows to not emit all results.
     *
     * Defaults to "pass everything" (including null, undefined, etc).
     * Simpler way to exclude certain cases is to return SKIP symbol from the mapper.
     */
    predicate?: Predicate<OUT>;
    asyncPredicate?: AsyncPredicate<OUT>;
    /**
     * Number of concurrently pending promises returned by `mapper`.
     *
     * @default 16
     */
    concurrency?: PositiveInteger;
    /**
     * Time in seconds to gradually increase concurrency from 1 to `concurrency`.
     * Useful for warming up connections to databases, APIs, etc.
     *
     * Set to 0 to disable warmup (default).
     */
    warmupSeconds?: NumberOfSeconds;
    /**
     * @default THROW_IMMEDIATELY
     */
    errorMode?: ErrorMode;
    /**
     * If defined - will be called on every error happening in the stream.
     * Called BEFORE observable will emit error (unless skipErrors is set to true).
     */
    onError?: (err: Error, input: IN) => any;
    /**
     * A hook that is called when the last item is finished processing.
     * stats object is passed, containing countIn and countOut -
     * number of items that entered the transform and number of items that left it.
     *
     * Callback is called **before** [possible] Aggregated error is thrown,
     * and before [possible] THROW_IMMEDIATELY error.
     *
     * onDone callback will be awaited before Error is thrown.
     */
    onDone?: (stats: TransformMapStats) => Promisable<any>;
    /**
     * Progress metric
     *
     * @default `stream`
     */
    metric?: string;
    /**
     * Allows to abort (gracefully stop) the stream from inside the Transform.
     */
    signal?: AbortableSignal;
}
/**
 * Like transformMap, but with native concurrency control (no through2-concurrent dependency)
 * and support for gradual warmup.
 *
 * @experimental
 */
export declare function transformMap<IN = any, OUT = IN>(mapper: AbortableAsyncMapper<IN, OUT | typeof SKIP | typeof END>, opt?: TransformMapOptions<IN, OUT>): TransformTyped<IN, OUT>;
export interface TransformMapStats {
    /**
     * True if transform was successful (didn't throw Immediate or Aggregated error).
     */
    ok: boolean;
    /**
     * Only used (and returned) for ErrorMode.Aggregated
     */
    collectedErrors: Error[];
    countErrors: number;
    countIn: number;
    countOut: number;
    started: UnixTimestampMillis;
}
export interface TransformMapStatsSummary extends TransformMapStats {
    /**
     * Name of the summary, defaults to `Transform`
     */
    name?: string;
    /**
     * Allows to pass extra key-value object, which will be rendered as:
     * key: value
     * key2: value2
     */
    extra?: StringMap<any>;
}
/**
 * Renders TransformMapStatsSummary into a friendly string,
 * to be used e.g in Github Actions summary or Slack.
 */
export declare function transformMapStatsSummary(summary: TransformMapStatsSummary): string;