@durable-streams/client 0.1.3 → 0.1.4

package/dist/index.d.cts

@@ -436,6 +436,23 @@ interface AppendOptions {
   * AbortSignal for this operation.
   */
   signal?: AbortSignal;
+  /**
+  * Producer ID for idempotent writes.
+  * Client-supplied stable identifier (e.g., "order-service-1").
+  * Must be provided together with producerEpoch and producerSeq.
+  */
+  producerId?: string;
+  /**
+  * Producer epoch for idempotent writes.
+  * Client-declared, server-validated monotonically increasing.
+  * Increment on producer restart.
+  */
+  producerEpoch?: number;
+  /**
+  * Producer sequence for idempotent writes.
+  * Monotonically increasing per epoch, per-batch.
+  */
+  producerSeq?: number;
 }
 /**
 * Legacy live mode type (internal use only).
@@ -698,6 +715,65 @@ interface StreamResponse<TJson = unknown> {
   * - terminal error.
   */
   readonly closed: Promise<void>;
+}
+/**
+* Options for creating an IdempotentProducer.
+*/
+interface IdempotentProducerOptions {
+  /**
+  * Starting epoch (default: 0).
+  * Increment this on producer restart.
+  */
+  epoch?: number;
+  /**
+  * On 403 Forbidden (stale epoch), automatically retry with epoch+1.
+  * Useful for serverless/ephemeral producers.
+  * @default false
+  */
+  autoClaim?: boolean;
+  /**
+  * Maximum bytes before sending a batch.
+  * @default 1048576 (1MB)
+  */
+  maxBatchBytes?: number;
+  /**
+  * Maximum time to wait for more messages before sending batch (ms).
+  * @default 5
+  */
+  lingerMs?: number;
+  /**
+  * Maximum number of concurrent batches in flight.
+  * Higher values improve throughput at the cost of more memory.
+  * @default 5
+  */
+  maxInFlight?: number;
+  /**
+  * Custom fetch implementation.
+  */
+  fetch?: typeof globalThis.fetch;
+  /**
+  * AbortSignal for the producer lifecycle.
+  */
+  signal?: AbortSignal;
+  /**
+  * Callback for batch errors in fire-and-forget mode.
+  * Since append() returns immediately, errors are reported via this callback.
+  * @param error - The error that occurred
+  */
+  onError?: (error: Error) => void;
+}
+/**
+* Result of an append operation from IdempotentProducer.
+*/
+interface IdempotentAppendResult {
+  /**
+  * The offset after this message was appended.
+  */
+  offset: Offset;
+  /**
+  * Whether this was a duplicate (idempotent success).
+  */
+  duplicate: boolean;
 } //#endregion
 //#region src/stream-api.d.ts
 /**
@@ -980,6 +1056,125 @@ declare function warnIfUsingHttpInBrowser(url: string | URL, warnOnHttp?: boolea
 */
 declare function _resetHttpWarningForTesting(): void;
 
+//#endregion
+//#region src/idempotent-producer.d.ts
+/**
+* Error thrown when a producer's epoch is stale (zombie fencing).
+*/
+declare class StaleEpochError extends Error {
+  /**
+  * The current epoch on the server.
+  */
+  readonly currentEpoch: number;
+  constructor(currentEpoch: number);
+}
+/**
+* Error thrown when an unrecoverable sequence gap is detected.
+*
+* With maxInFlight > 1, HTTP requests can arrive out of order at the server,
+* causing temporary 409 responses. The client automatically handles these
+* by waiting for earlier sequences to complete, then retrying.
+*
+* This error is only thrown when the gap cannot be resolved (e.g., the
+* expected sequence is >= our sequence, indicating a true protocol violation).
+*/
+declare class SequenceGapError extends Error {
+  readonly expectedSeq: number;
+  readonly receivedSeq: number;
+  constructor(expectedSeq: number, receivedSeq: number);
+}
+/**
+* An idempotent producer for exactly-once writes to a durable stream.
+*
+* Features:
+* - Fire-and-forget: append() returns immediately, batches in background
+* - Exactly-once: server deduplicates using (producerId, epoch, seq)
+* - Batching: multiple appends batched into single HTTP request
+* - Pipelining: up to maxInFlight concurrent batches
+* - Zombie fencing: stale producers rejected via epoch validation
+*
+* @example
+* ```typescript
+* const stream = new DurableStream({ url: "https://..." });
+* const producer = new IdempotentProducer(stream, "order-service-1", {
+*   epoch: 0,
+*   autoClaim: true,
+* });
+*
+* // Fire-and-forget writes (synchronous, returns immediately)
+* producer.append("message 1");
+* producer.append("message 2");
+*
+* // Ensure all messages are delivered before shutdown
+* await producer.flush();
+* await producer.close();
+* ```
+*/
+declare class IdempotentProducer {
+  #private;
+  /**
+  * Create an idempotent producer for a stream.
+  *
+  * @param stream - The DurableStream to write to
+  * @param producerId - Stable identifier for this producer (e.g., "order-service-1")
+  * @param opts - Producer options
+  */
+  constructor(stream: DurableStream, producerId: string, opts?: IdempotentProducerOptions);
+  /**
+  * Append data to the stream.
+  *
+  * This is fire-and-forget: returns immediately after adding to the batch.
+  * The message is batched and sent when:
+  * - maxBatchBytes is reached
+  * - lingerMs elapses
+  * - flush() is called
+  *
+  * Errors are reported via onError callback if configured. Use flush() to
+  * wait for all pending messages to be sent.
+  *
+  * For JSON streams, pass native objects (which will be serialized internally).
+  * For byte streams, pass string or Uint8Array.
+  *
+  * @param body - Data to append (object for JSON streams, string or Uint8Array for byte streams)
+  */
+  append(body: Uint8Array | string | unknown): void;
+  /**
+  * Send any pending batch immediately and wait for all in-flight batches.
+  *
+  * Call this before shutdown to ensure all messages are delivered.
+  */
+  flush(): Promise<void>;
+  /**
+  * Flush pending messages and close the producer.
+  *
+  * After calling close(), further append() calls will throw.
+  */
+  close(): Promise<void>;
+  /**
+  * Increment epoch and reset sequence.
+  *
+  * Call this when restarting the producer to establish a new session.
+  * Flushes any pending messages first.
+  */
+  restart(): Promise<void>;
+  /**
+  * Current epoch for this producer.
+  */
+  get epoch(): number;
+  /**
+  * Next sequence number to be assigned.
+  */
+  get nextSeq(): number;
+  /**
+  * Number of messages in the current pending batch.
+  */
+  get pendingCount(): number;
+  /**
+  * Number of batches currently in flight.
+  */
+  get inFlightCount(): number;
+}
+
 //#endregion
 //#region src/error.d.ts
 /**
@@ -1077,6 +1272,28 @@ declare const STREAM_TTL_HEADER = "Stream-TTL";
 */
 declare const STREAM_EXPIRES_AT_HEADER = "Stream-Expires-At";
 /**
+* Request header for producer ID (client-supplied stable identifier).
+*/
+declare const PRODUCER_ID_HEADER = "Producer-Id";
+/**
+* Request/response header for producer epoch.
+* Client-declared, server-validated monotonically increasing.
+*/
+declare const PRODUCER_EPOCH_HEADER = "Producer-Epoch";
+/**
+* Request header for producer sequence number.
+* Monotonically increasing per epoch, per-batch (not per-message).
+*/
+declare const PRODUCER_SEQ_HEADER = "Producer-Seq";
+/**
+* Response header indicating expected sequence number on 409 Conflict.
+*/
+declare const PRODUCER_EXPECTED_SEQ_HEADER = "Producer-Expected-Seq";
+/**
+* Response header indicating received sequence number on 409 Conflict.
+*/
+declare const PRODUCER_RECEIVED_SEQ_HEADER = "Producer-Received-Seq";
+/**
 * Query parameter for starting offset.
 */
 declare const OFFSET_QUERY_PARAM = "offset";
@@ -1105,4 +1322,4 @@ declare const SSE_COMPATIBLE_CONTENT_TYPES: ReadonlyArray<string>;
 declare const DURABLE_STREAM_PROTOCOL_QUERY_PARAMS: Array<string>;
 
 //#endregion
-export { AppendOptions, BackoffDefaults, BackoffOptions, ByteChunk, CURSOR_QUERY_PARAM, CreateOptions, DURABLE_STREAM_PROTOCOL_QUERY_PARAMS, DurableStream, DurableStreamError, DurableStreamErrorCode, DurableStreamOptions, FetchBackoffAbortError, FetchError, HeadResult, HeadersRecord, InvalidSignalError, JsonBatch, JsonBatchMeta, LIVE_QUERY_PARAM, LegacyLiveMode, LiveMode, MaybePromise, MissingStreamUrlError, OFFSET_QUERY_PARAM, Offset, ParamsRecord, ReadOptions, ReadableStreamAsyncIterable, RetryOpts, SSEResilienceOptions, SSE_COMPATIBLE_CONTENT_TYPES, STREAM_CURSOR_HEADER, STREAM_EXPIRES_AT_HEADER, STREAM_OFFSET_HEADER, STREAM_SEQ_HEADER, STREAM_TTL_HEADER, STREAM_UP_TO_DATE_HEADER, StreamErrorHandler, StreamHandleOptions, StreamOptions, StreamResponse, TextChunk, _resetHttpWarningForTesting, asAsyncIterableReadableStream, createFetchWithBackoff, createFetchWithConsumedBody, stream, warnIfUsingHttpInBrowser };
+export { AppendOptions, BackoffDefaults, BackoffOptions, ByteChunk, CURSOR_QUERY_PARAM, CreateOptions, DURABLE_STREAM_PROTOCOL_QUERY_PARAMS, DurableStream, DurableStreamError, DurableStreamErrorCode, DurableStreamOptions, FetchBackoffAbortError, FetchError, HeadResult, HeadersRecord, IdempotentAppendResult, IdempotentProducer, IdempotentProducerOptions, InvalidSignalError, JsonBatch, JsonBatchMeta, LIVE_QUERY_PARAM, LegacyLiveMode, LiveMode, MaybePromise, MissingStreamUrlError, OFFSET_QUERY_PARAM, Offset, PRODUCER_EPOCH_HEADER, PRODUCER_EXPECTED_SEQ_HEADER, PRODUCER_ID_HEADER, PRODUCER_RECEIVED_SEQ_HEADER, PRODUCER_SEQ_HEADER, ParamsRecord, ReadOptions, ReadableStreamAsyncIterable, RetryOpts, SSEResilienceOptions, SSE_COMPATIBLE_CONTENT_TYPES, STREAM_CURSOR_HEADER, STREAM_EXPIRES_AT_HEADER, STREAM_OFFSET_HEADER, STREAM_SEQ_HEADER, STREAM_TTL_HEADER, STREAM_UP_TO_DATE_HEADER, SequenceGapError, StaleEpochError, StreamErrorHandler, StreamHandleOptions, StreamOptions, StreamResponse, TextChunk, _resetHttpWarningForTesting, asAsyncIterableReadableStream, createFetchWithBackoff, createFetchWithConsumedBody, stream, warnIfUsingHttpInBrowser };

package/dist/index.d.ts

@@ -436,6 +436,23 @@ interface AppendOptions {
   * AbortSignal for this operation.
   */
   signal?: AbortSignal;
+  /**
+  * Producer ID for idempotent writes.
+  * Client-supplied stable identifier (e.g., "order-service-1").
+  * Must be provided together with producerEpoch and producerSeq.
+  */
+  producerId?: string;
+  /**
+  * Producer epoch for idempotent writes.
+  * Client-declared, server-validated monotonically increasing.
+  * Increment on producer restart.
+  */
+  producerEpoch?: number;
+  /**
+  * Producer sequence for idempotent writes.
+  * Monotonically increasing per epoch, per-batch.
+  */
+  producerSeq?: number;
 }
 /**
 * Legacy live mode type (internal use only).
@@ -698,6 +715,65 @@ interface StreamResponse<TJson = unknown> {
   * - terminal error.
   */
   readonly closed: Promise<void>;
+}
+/**
+* Options for creating an IdempotentProducer.
+*/
+interface IdempotentProducerOptions {
+  /**
+  * Starting epoch (default: 0).
+  * Increment this on producer restart.
+  */
+  epoch?: number;
+  /**
+  * On 403 Forbidden (stale epoch), automatically retry with epoch+1.
+  * Useful for serverless/ephemeral producers.
+  * @default false
+  */
+  autoClaim?: boolean;
+  /**
+  * Maximum bytes before sending a batch.
+  * @default 1048576 (1MB)
+  */
+  maxBatchBytes?: number;
+  /**
+  * Maximum time to wait for more messages before sending batch (ms).
+  * @default 5
+  */
+  lingerMs?: number;
+  /**
+  * Maximum number of concurrent batches in flight.
+  * Higher values improve throughput at the cost of more memory.
+  * @default 5
+  */
+  maxInFlight?: number;
+  /**
+  * Custom fetch implementation.
+  */
+  fetch?: typeof globalThis.fetch;
+  /**
+  * AbortSignal for the producer lifecycle.
+  */
+  signal?: AbortSignal;
+  /**
+  * Callback for batch errors in fire-and-forget mode.
+  * Since append() returns immediately, errors are reported via this callback.
+  * @param error - The error that occurred
+  */
+  onError?: (error: Error) => void;
+}
+/**
+* Result of an append operation from IdempotentProducer.
+*/
+interface IdempotentAppendResult {
+  /**
+  * The offset after this message was appended.
+  */
+  offset: Offset;
+  /**
+  * Whether this was a duplicate (idempotent success).
+  */
+  duplicate: boolean;
 } //#endregion
 //#region src/stream-api.d.ts
 /**
@@ -980,6 +1056,125 @@ declare function warnIfUsingHttpInBrowser(url: string | URL, warnOnHttp?: boolea
 */
 declare function _resetHttpWarningForTesting(): void;
 
+//#endregion
+//#region src/idempotent-producer.d.ts
+/**
+* Error thrown when a producer's epoch is stale (zombie fencing).
+*/
+declare class StaleEpochError extends Error {
+  /**
+  * The current epoch on the server.
+  */
+  readonly currentEpoch: number;
+  constructor(currentEpoch: number);
+}
+/**
+* Error thrown when an unrecoverable sequence gap is detected.
+*
+* With maxInFlight > 1, HTTP requests can arrive out of order at the server,
+* causing temporary 409 responses. The client automatically handles these
+* by waiting for earlier sequences to complete, then retrying.
+*
+* This error is only thrown when the gap cannot be resolved (e.g., the
+* expected sequence is >= our sequence, indicating a true protocol violation).
+*/
+declare class SequenceGapError extends Error {
+  readonly expectedSeq: number;
+  readonly receivedSeq: number;
+  constructor(expectedSeq: number, receivedSeq: number);
+}
+/**
+* An idempotent producer for exactly-once writes to a durable stream.
+*
+* Features:
+* - Fire-and-forget: append() returns immediately, batches in background
+* - Exactly-once: server deduplicates using (producerId, epoch, seq)
+* - Batching: multiple appends batched into single HTTP request
+* - Pipelining: up to maxInFlight concurrent batches
+* - Zombie fencing: stale producers rejected via epoch validation
+*
+* @example
+* ```typescript
+* const stream = new DurableStream({ url: "https://..." });
+* const producer = new IdempotentProducer(stream, "order-service-1", {
+*   epoch: 0,
+*   autoClaim: true,
+* });
+*
+* // Fire-and-forget writes (synchronous, returns immediately)
+* producer.append("message 1");
+* producer.append("message 2");
+*
+* // Ensure all messages are delivered before shutdown
+* await producer.flush();
+* await producer.close();
+* ```
+*/
+declare class IdempotentProducer {
+  #private;
+  /**
+  * Create an idempotent producer for a stream.
+  *
+  * @param stream - The DurableStream to write to
+  * @param producerId - Stable identifier for this producer (e.g., "order-service-1")
+  * @param opts - Producer options
+  */
+  constructor(stream: DurableStream, producerId: string, opts?: IdempotentProducerOptions);
+  /**
+  * Append data to the stream.
+  *
+  * This is fire-and-forget: returns immediately after adding to the batch.
+  * The message is batched and sent when:
+  * - maxBatchBytes is reached
+  * - lingerMs elapses
+  * - flush() is called
+  *
+  * Errors are reported via onError callback if configured. Use flush() to
+  * wait for all pending messages to be sent.
+  *
+  * For JSON streams, pass native objects (which will be serialized internally).
+  * For byte streams, pass string or Uint8Array.
+  *
+  * @param body - Data to append (object for JSON streams, string or Uint8Array for byte streams)
+  */
+  append(body: Uint8Array | string | unknown): void;
+  /**
+  * Send any pending batch immediately and wait for all in-flight batches.
+  *
+  * Call this before shutdown to ensure all messages are delivered.
+  */
+  flush(): Promise<void>;
+  /**
+  * Flush pending messages and close the producer.
+  *
+  * After calling close(), further append() calls will throw.
+  */
+  close(): Promise<void>;
+  /**
+  * Increment epoch and reset sequence.
+  *
+  * Call this when restarting the producer to establish a new session.
+  * Flushes any pending messages first.
+  */
+  restart(): Promise<void>;
+  /**
+  * Current epoch for this producer.
+  */
+  get epoch(): number;
+  /**
+  * Next sequence number to be assigned.
+  */
+  get nextSeq(): number;
+  /**
+  * Number of messages in the current pending batch.
+  */
+  get pendingCount(): number;
+  /**
+  * Number of batches currently in flight.
+  */
+  get inFlightCount(): number;
+}
+
 //#endregion
 //#region src/error.d.ts
 /**
@@ -1077,6 +1272,28 @@ declare const STREAM_TTL_HEADER = "Stream-TTL";
 */
 declare const STREAM_EXPIRES_AT_HEADER = "Stream-Expires-At";
 /**
+* Request header for producer ID (client-supplied stable identifier).
+*/
+declare const PRODUCER_ID_HEADER = "Producer-Id";
+/**
+* Request/response header for producer epoch.
+* Client-declared, server-validated monotonically increasing.
+*/
+declare const PRODUCER_EPOCH_HEADER = "Producer-Epoch";
+/**
+* Request header for producer sequence number.
+* Monotonically increasing per epoch, per-batch (not per-message).
+*/
+declare const PRODUCER_SEQ_HEADER = "Producer-Seq";
+/**
+* Response header indicating expected sequence number on 409 Conflict.
+*/
+declare const PRODUCER_EXPECTED_SEQ_HEADER = "Producer-Expected-Seq";
+/**
+* Response header indicating received sequence number on 409 Conflict.
+*/
+declare const PRODUCER_RECEIVED_SEQ_HEADER = "Producer-Received-Seq";
+/**
 * Query parameter for starting offset.
 */
 declare const OFFSET_QUERY_PARAM = "offset";
@@ -1105,4 +1322,4 @@ declare const SSE_COMPATIBLE_CONTENT_TYPES: ReadonlyArray<string>;
 declare const DURABLE_STREAM_PROTOCOL_QUERY_PARAMS: Array<string>;
 
 //#endregion
-export { AppendOptions, BackoffDefaults, BackoffOptions, ByteChunk, CURSOR_QUERY_PARAM, CreateOptions, DURABLE_STREAM_PROTOCOL_QUERY_PARAMS, DurableStream, DurableStreamError, DurableStreamErrorCode, DurableStreamOptions, FetchBackoffAbortError, FetchError, HeadResult, HeadersRecord, InvalidSignalError, JsonBatch, JsonBatchMeta, LIVE_QUERY_PARAM, LegacyLiveMode, LiveMode, MaybePromise, MissingStreamUrlError, OFFSET_QUERY_PARAM, Offset, ParamsRecord, ReadOptions, ReadableStreamAsyncIterable, RetryOpts, SSEResilienceOptions, SSE_COMPATIBLE_CONTENT_TYPES, STREAM_CURSOR_HEADER, STREAM_EXPIRES_AT_HEADER, STREAM_OFFSET_HEADER, STREAM_SEQ_HEADER, STREAM_TTL_HEADER, STREAM_UP_TO_DATE_HEADER, StreamErrorHandler, StreamHandleOptions, StreamOptions, StreamResponse, TextChunk, _resetHttpWarningForTesting, asAsyncIterableReadableStream, createFetchWithBackoff, createFetchWithConsumedBody, stream, warnIfUsingHttpInBrowser };
+export { AppendOptions, BackoffDefaults, BackoffOptions, ByteChunk, CURSOR_QUERY_PARAM, CreateOptions, DURABLE_STREAM_PROTOCOL_QUERY_PARAMS, DurableStream, DurableStreamError, DurableStreamErrorCode, DurableStreamOptions, FetchBackoffAbortError, FetchError, HeadResult, HeadersRecord, IdempotentAppendResult, IdempotentProducer, IdempotentProducerOptions, InvalidSignalError, JsonBatch, JsonBatchMeta, LIVE_QUERY_PARAM, LegacyLiveMode, LiveMode, MaybePromise, MissingStreamUrlError, OFFSET_QUERY_PARAM, Offset, PRODUCER_EPOCH_HEADER, PRODUCER_EXPECTED_SEQ_HEADER, PRODUCER_ID_HEADER, PRODUCER_RECEIVED_SEQ_HEADER, PRODUCER_SEQ_HEADER, ParamsRecord, ReadOptions, ReadableStreamAsyncIterable, RetryOpts, SSEResilienceOptions, SSE_COMPATIBLE_CONTENT_TYPES, STREAM_CURSOR_HEADER, STREAM_EXPIRES_AT_HEADER, STREAM_OFFSET_HEADER, STREAM_SEQ_HEADER, STREAM_TTL_HEADER, STREAM_UP_TO_DATE_HEADER, SequenceGapError, StaleEpochError, StreamErrorHandler, StreamHandleOptions, StreamOptions, StreamResponse, TextChunk, _resetHttpWarningForTesting, asAsyncIterableReadableStream, createFetchWithBackoff, createFetchWithConsumedBody, stream, warnIfUsingHttpInBrowser };