@ydbjs/topic/dist/reader.d.ts

YDB Topics client for publish-subscribe messaging. Provides at-least-once delivery, exactly-once publishing, FIFO guarantees, and scalable message processing for unstructured data.

import { type Duration, type Timestamp } from "@bufbuild/protobuf/wkt";
import type { Driver } from "@ydbjs/core";
import type { StringValue } from "ms";
import { type CodecMap } from "./codec.js";
import { TopicMessage } from "./message.js";
import { TopicPartitionSession } from "./partition-session.js";
import type { TX } from "./tx.js";
export type TopicReaderSource = {
    /**
     * Topic path.
     */
    path: string;
    /**
     * Partitions that will be read by this session.
     * If list is empty - then session will read all partitions.
     */
    partitionIds?: bigint[];
    /**
     * Skip all messages that has write timestamp smaller than now - max_lag.
     * Zero means infinite lag.
     */
    maxLag?: number | StringValue | Duration;
    /**
     * Read data only after this timestamp from this topic.
     * Read only messages with 'written_at' value greater or equal than this timestamp.
     */
    readFrom?: number | Date | Timestamp;
};
export type TopicPartitionCommitOffsets = {
    partitionSession: TopicPartitionSession;
    offsets: {
        start: bigint;
        end: bigint;
    }[];
};
export type onPartitionSessionStartCallback = (partitionSession: TopicPartitionSession, committedOffset: bigint, partitionOffsets: {
    start: bigint;
    end: bigint;
}) => Promise<void | undefined | {
    readOffset?: bigint;
    commitOffset?: bigint;
}>;
export type onPartitionSessionStopCallback = (partitionSession: TopicPartitionSession, committedOffset: bigint) => Promise<void>;
export type onPartitionSessionEndCallback = (partition: {
    partitionSession: TopicPartitionSession;
}) => void;
export type onCommittedOffsetCallback = (partitionSession: TopicPartitionSession, committedOffset: bigint) => void;
export type TopicReaderOptions = {
    topic: string | TopicReaderSource | TopicReaderSource[];
    consumer: string;
    codecMap?: CodecMap;
    maxBufferBytes?: bigint;
    updateTokenIntervalMs?: number;
    onPartitionSessionStart?: onPartitionSessionStartCallback;
    onPartitionSessionStop?: onPartitionSessionStopCallback;
    onCommittedOffset?: onCommittedOffsetCallback;
};
export declare class TopicReader implements Disposable {
    #private;
    /**
     * Creates a new TopicReader instance.
     * @param driver - The YDB driver instance to use for communication with the YDB server.
     * @param options - Options for the topic reader, including topic path, consumer name, and optional callbacks.
     */
    constructor(driver: Driver, options: TopicReaderOptions);
    /**
     * Reads messages from the topic stream.
     * This method returns an async iterable that yields TopicMessage[] objects.
     * It handles reading messages in batches, managing partition sessions, and buffering messages.
     * The method supports options for limiting the number of messages read, setting a timeout,
     * and using an AbortSignal to cancel the read operation.
     *
     * If limit is provided, it will read up to the specified number of messages.
     * If no limit is provided, it will read messages as fast as they are available,
     * up to the maximum buffer size defined in the options.
     *
     * If timeout is provided, it will wait for messages until the specified time elapses.
     * After the timeout, it emits an empty TopicMessage[] if no messages were read.
     *
     * The signal option allows for cancellation of the read operation.
     * If provided, it will merge with the reader's controller signal to allow for cancellation.
     *
     * @param {Object} options - Options for reading messages.
     * @param {number} [options.limit=Infinity] - The maximum number of messages to read. Default is Infinity.
     * @param {number} [options.waitMs=60_000] - The maximum time to wait for messages before timing out. If not provided, it will wait 1 minute.
     * @param {AbortSignal} [options.signal] - An AbortSignal to cancel the read operation. If provided, it will merge with the reader's controller signal.
     * @returns {AsyncIterable<TopicMessage[]>} An async iterable that yields TopicMessage[] objects.
     */
    read(options?: {
        limit?: number;
        waitMs?: number;
        signal?: AbortSignal;
    }): AsyncIterable<TopicMessage[]>;
    readInTx(tx: TX, options?: {
        limit?: number;
        waitMs?: number;
        signal?: AbortSignal;
    }): AsyncIterable<TopicMessage[]>;
    /**
     * Commits offsets for the provided messages.
     *
     * Sends a commit offset request to the server, grouping offsets by partition session and merging consecutive offsets into ranges.
     * Accepts a single TopicMessage, an array of TopicMessages, or a TopicMessage[].
     *
     * Returns a thenable (lazy promise) that resolves when the server acknowledges the commit.
     *
     * Note: Do not `await` this method directly in hot paths, as commit resolution may be delayed or never occur if the stream closes.
     *
     * Throws if the reader is disposed or if any message lacks a partitionSessionId.
     *
     * @param input - TopicMessage or TopicMessage[] to commit.
     * @returns Promise<void> that resolves when the commit is acknowledged.
     */
    commit(input: TopicMessage | TopicMessage[]): Promise<void>;
    /**
     * Disposes the TopicReader instance, cleaning up resources and aborting the stream.
     * This method should be called when the reader is no longer needed to prevent memory leaks.
     */
    dispose(): void;
    [Symbol.dispose](): void;
}
//# sourceMappingURL=reader.d.ts.map