@s2-dev/streamstore 0.16.0 → 0.16.2

package/dist/stream.d.ts

@@ -0,0 +1,156 @@
+import type { S2RequestOptions } from "./common";
+import { type AppendAck, type AppendInput as GeneratedAppendInput, type AppendRecord as GeneratedAppendRecord, type ReadBatch as GeneratedReadBatch, type SequencedRecord as GeneratedSequencedRecord, type ReadData, type StreamPosition } from "./generated";
+import type { Client } from "./generated/client/types.gen";
+import { EventStream } from "./lib/event-stream";
+export declare class S2Stream {
+    private readonly client;
+    readonly name: string;
+    constructor(name: string, client: Client);
+    /**
+     * Check the tail of the stream.
+     *
+     * Returns the next sequence number and timestamp to be assigned (`tail`).
+     */
+    checkTail(options?: S2RequestOptions): Promise<import("./generated").TailResponse>;
+    /**
+     * Read records from the stream.
+     *
+     * - When `as: "bytes"` is provided, bodies and headers are decoded from base64 to `Uint8Array`.
+     * - Supports starting position by `seq_num`, `timestamp`, or `tail_offset` and can clamp to the tail.
+     * - Non-streaming reads are bounded by `count` and `bytes` (defaults 1000 and 1 MiB).
+     * - Use `readSession` for streaming reads
+     */
+    read<Format extends "string" | "bytes" = "string">(args?: ReadArgs<Format>, options?: S2RequestOptions): Promise<ReadBatch<Format>>;
+    /**
+     * Append one or more records to the stream.
+     *
+     * - Automatically base64-encodes when any body or header is a `Uint8Array`.
+     * - Supports conditional appends via `fencing_token` and `match_seq_num`.
+     * - Returns the acknowledged range and the stream tail after the append.
+     */
+    append(records: AppendRecord | AppendRecord[], args?: Omit<AppendArgs, "records">, options?: S2RequestOptions): Promise<AppendAck>;
+    /**
+     * Open a streaming read session
+     *
+     * Use the returned session as an async iterable or as a readable stream.
+     * When `as: "bytes"` is provided, bodies and headers are decoded to `Uint8Array`.
+     */
+    readSession<Format extends "string" | "bytes" = "string">(args?: ReadArgs<Format>, options?: S2RequestOptions): Promise<ReadSession<Format>>;
+    /**
+     * Create an append session that guaranteeds ordering of submissions.
+     *
+     * Use this to coordinate high-throughput, sequential appends with backpressure.
+     */
+    appendSession(options?: S2RequestOptions): Promise<AppendSession>;
+}
+export type Header<Format extends "string" | "bytes" = "string"> = Format extends "string" ? [string, string] : [Uint8Array, Uint8Array];
+export type ReadBatch<Format extends "string" | "bytes" = "string"> = Omit<GeneratedReadBatch, "records"> & {
+    records?: Array<SequencedRecord<Format>>;
+};
+export type SequencedRecord<Format extends "string" | "bytes" = "string"> = Omit<GeneratedSequencedRecord, "body" | "headers"> & {
+    body?: Format extends "string" ? string : Uint8Array;
+    headers?: Array<Header<Format>>;
+};
+export type ReadArgs<Format extends "string" | "bytes" = "string"> = ReadData["query"] & {
+    as?: Format;
+};
+export type AppendRecord = Omit<GeneratedAppendRecord, "body" | "headers"> & {
+    body?: string | Uint8Array;
+    headers?: Array<[string | Uint8Array, string | Uint8Array]> | Record<string, string | Uint8Array>;
+};
+export type AppendArgs = Omit<GeneratedAppendInput, "records"> & {
+    records: Array<AppendRecord>;
+};
+declare class ReadSession<Format extends "string" | "bytes" = "string"> extends EventStream<SequencedRecord<Format>> {
+    static create<Format extends "string" | "bytes" = "string">(client: Client, name: string, args?: ReadArgs<Format>, options?: S2RequestOptions): Promise<ReadSession<"string" | Format>>;
+    private _streamPosition;
+    private constructor();
+    get streamPosition(): StreamPosition | undefined;
+}
+declare class AcksStream extends ReadableStream<AppendAck> implements AsyncDisposable {
+    constructor(setController: (controller: ReadableStreamDefaultController<AppendAck>) => void);
+    [Symbol.asyncDispose](): Promise<void>;
+    [Symbol.asyncIterator](): AsyncIterableIterator<AppendAck>;
+}
+interface BatcherArgs {
+    /** Duration in milliseconds to wait before flushing a batch (default: 5ms) */
+    lingerDuration?: number;
+    /** Maximum number of records in a batch (default: 1000) */
+    maxBatchSize?: number;
+    /** Optional fencing token to enforce (remains static across batches) */
+    fencing_token?: string;
+    /** Optional sequence number to match for first batch (auto-increments for subsequent batches) */
+    match_seq_num?: number;
+}
+/**
+ * Batches individual records and submits them to an AppendSession.
+ * Handles linger duration, batch size limits, and auto-incrementing match_seq_num.
+ */
+declare class Batcher extends WritableStream<AppendRecord | AppendRecord[]> implements AsyncDisposable {
+    private session;
+    private currentBatch;
+    private currentBatchResolvers;
+    private lingerTimer;
+    private closed;
+    private readonly maxBatchSize;
+    private readonly lingerDuration;
+    private readonly fencing_token?;
+    private next_match_seq_num?;
+    constructor(session: AppendSession, args?: BatcherArgs);
+    [Symbol.asyncDispose](): Promise<void>;
+    /**
+     * Submit one or more records to be batched.
+     * For array submits, the entire array is treated as an atomic unit and will never be split across batches.
+     * If it doesn't fit in the current batch, the current batch is flushed and the array is queued in the next batch.
+     * Returns a promise that resolves when the batch containing these records is acknowledged.
+     */
+    submit(records: AppendRecord | AppendRecord[]): Promise<AppendAck>;
+    /**
+     * Flush the current batch to the session.
+     */
+    flush(): void;
+    private startLingerTimer;
+    private cancelLingerTimer;
+    private cleanup;
+}
+/**
+ * Session for appending records to a stream.
+ * Queues append requests and ensures only one is in-flight at a time.
+ */
+declare class AppendSession extends WritableStream<AppendArgs> implements AsyncDisposable {
+    private _lastSeenPosition;
+    private queue;
+    private pendingResolvers;
+    private inFlight;
+    private readonly options?;
+    private readonly stream;
+    private acksController;
+    private _acksStream;
+    private closed;
+    private processingPromise;
+    static create(stream: S2Stream, options?: S2RequestOptions): Promise<AppendSession>;
+    private constructor();
+    [Symbol.asyncDispose](): Promise<void>;
+    /**
+     * Create a batcher that batches individual records and submits them to this session.
+     */
+    makeBatcher(args?: BatcherArgs): Batcher;
+    /**
+     * Get a stream of acknowledgements for appends.
+     */
+    acks(): AcksStream;
+    /**
+     * Submit an append request to the session.
+     * The request will be queued and sent when no other request is in-flight.
+     * Returns a promise that resolves when the append is acknowledged or rejects on error.
+     */
+    submit(records: AppendRecord | AppendRecord[], args?: Omit<AppendArgs, "records">): Promise<AppendAck>;
+    /**
+     * Main processing loop that sends queued requests one at a time.
+     */
+    private processLoop;
+    private waitForDrain;
+    get lastSeenPosition(): AppendAck | undefined;
+}
+export {};
+//# sourceMappingURL=stream.d.ts.map

package/dist/stream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream.d.ts","sourceRoot":"","sources":["../src/stream.ts"],"names":[],"mappings":"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"}