@s2-dev/streamstore 0.17.6 → 0.18.1

package/dist/esm/lib/result.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Result types for AppendSession operations.
+ * Using discriminated unions for ergonomic error handling with TypeScript control flow analysis.
+ */
+import { S2Error } from "../error.js";
+import type { AppendAck } from "../generated/index.js";
+/**
+ * Result of an append operation.
+ * Use discriminated union pattern: check `result.ok` to access either `value` or `error`.
+ */
+export type AppendResult = {
+    ok: true;
+    value: AppendAck;
+} | {
+    ok: false;
+    error: S2Error;
+};
+/**
+ * Result of a close operation.
+ */
+export type CloseResult = {
+    ok: true;
+} | {
+    ok: false;
+    error: S2Error;
+};
+/**
+ * Constructs a successful append result.
+ */
+export declare function ok(value: AppendAck): AppendResult;
+/**
+ * Constructs a failed append result.
+ */
+export declare function err(error: S2Error): AppendResult;
+/**
+ * Constructs a successful close result.
+ */
+export declare function okClose(): CloseResult;
+/**
+ * Constructs a failed close result.
+ */
+export declare function errClose(error: S2Error): CloseResult;
+/**
+ * Type guard to check if a result is successful.
+ * Mainly for internal use; prefer `result.ok` for public API.
+ */
+export declare function isOk<T>(result: {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: S2Error;
+}): result is {
+    ok: true;
+    value: T;
+};
+//# sourceMappingURL=result.d.ts.map

package/dist/esm/lib/result.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"result.d.ts","sourceRoot":"","sources":["../../../src/lib/result.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AACtC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAEvD;;;GAGG;AACH,MAAM,MAAM,YAAY,GACrB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,SAAS,CAAA;CAAE,GAC9B;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAAC;AAEjC;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAAC;AAEvE;;GAEG;AACH,wBAAgB,EAAE,CAAC,KAAK,EAAE,SAAS,GAAG,YAAY,CAEjD;AAED;;GAEG;AACH,wBAAgB,GAAG,CAAC,KAAK,EAAE,OAAO,GAAG,YAAY,CAEhD;AAED;;GAEG;AACH,wBAAgB,OAAO,IAAI,WAAW,CAErC;AAED;;GAEG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,WAAW,CAEpD;AAED;;;GAGG;AACH,wBAAgB,IAAI,CAAC,CAAC,EACrB,MAAM,EAAE;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,CAAC,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,GAC5D,MAAM,IAAI;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,CAAC,CAAA;CAAE,CAElC"}

package/dist/esm/lib/result.js

@@ -0,0 +1,37 @@
+/**
+ * Result types for AppendSession operations.
+ * Using discriminated unions for ergonomic error handling with TypeScript control flow analysis.
+ */
+import { S2Error } from "../error.js";
+/**
+ * Constructs a successful append result.
+ */
+export function ok(value) {
+    return { ok: true, value };
+}
+/**
+ * Constructs a failed append result.
+ */
+export function err(error) {
+    return { ok: false, error };
+}
+/**
+ * Constructs a successful close result.
+ */
+export function okClose() {
+    return { ok: true };
+}
+/**
+ * Constructs a failed close result.
+ */
+export function errClose(error) {
+    return { ok: false, error };
+}
+/**
+ * Type guard to check if a result is successful.
+ * Mainly for internal use; prefer `result.ok` for public API.
+ */
+export function isOk(result) {
+    return result.ok;
+}
+//# sourceMappingURL=result.js.map

package/dist/esm/lib/result.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"result.js","sourceRoot":"","sources":["../../../src/lib/result.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAgBtC;;GAEG;AACH,MAAM,UAAU,EAAE,CAAC,KAAgB;IAClC,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;AAC5B,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,GAAG,CAAC,KAAc;IACjC,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;AAC7B,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,OAAO;IACtB,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC;AACrB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,QAAQ,CAAC,KAAc;IACtC,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;AAC7B,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,IAAI,CACnB,MAA8D;IAE9D,OAAO,MAAM,CAAC,EAAE,CAAC;AAClB,CAAC"}

package/dist/esm/lib/retry.d.ts

@@ -0,0 +1,151 @@
+import type { RetryConfig } from "../common.js";
+import { S2Error } from "../error.js";
+import type { AppendAck, StreamPosition } from "../generated/index.js";
+import type { AcksStream, AppendArgs, AppendRecord, AppendSessionOptions, AppendSession as AppendSessionType, ReadArgs, ReadRecord, ReadSession as ReadSessionType, TransportAppendSession, TransportReadSession } from "./stream/types.js";
+/**
+ * Default retry configuration.
+ */
+export declare const DEFAULT_RETRY_CONFIG: Required<RetryConfig> & {
+    requestTimeoutMillis: number;
+};
+/**
+ * Determines if an error should be retried based on its characteristics.
+ * 400-level errors (except 408, 429) are non-retryable validation/client errors.
+ */
+export declare function isRetryable(error: S2Error): boolean;
+/**
+ * Calculates the delay before the next retry attempt using fixed backoff
+ * with jitter. The `attempt` parameter is currently ignored to keep a
+ * constant base delay per attempt.
+ */
+export declare function calculateDelay(attempt: number, baseDelayMillis: number): number;
+/**
+ * Sleeps for the specified duration.
+ */
+export declare function sleep(ms: number): Promise<void>;
+/**
+ * Executes an async function with automatic retry logic for transient failures.
+ *
+ * @param retryConfig Retry configuration (max attempts, backoff duration)
+ * @param fn The async function to execute
+ * @returns The result of the function
+ * @throws The last error if all retry attempts are exhausted
+ */
+export declare function withRetries<T>(retryConfig: RetryConfig | undefined, fn: () => Promise<T>, isPolicyCompliant?: (config: RetryConfig, error: S2Error) => boolean): Promise<T>;
+export declare class RetryReadSession<Format extends "string" | "bytes" = "string"> extends ReadableStream<ReadRecord<Format>> implements ReadSessionType<Format> {
+    private _nextReadPosition;
+    private _lastObservedTail;
+    private _recordsRead;
+    private _bytesRead;
+    static create<Format extends "string" | "bytes" = "string">(generator: (args: ReadArgs<Format>) => Promise<TransportReadSession<Format>>, args?: ReadArgs<Format>, config?: RetryConfig): Promise<RetryReadSession<Format>>;
+    private constructor();
+    [Symbol.asyncDispose](): Promise<void>;
+    [Symbol.asyncIterator](): AsyncIterableIterator<ReadRecord<Format>>;
+    lastObservedTail(): StreamPosition | undefined;
+    nextReadPosition(): StreamPosition | undefined;
+}
+export declare class RetryAppendSession implements AsyncDisposable, AppendSessionType {
+    private readonly generator;
+    private readonly sessionOptions?;
+    private readonly requestTimeoutMillis;
+    private readonly maxQueuedBytes;
+    private readonly maxInflightBatches?;
+    private readonly retryConfig;
+    private readonly inflight;
+    private capacityWaiter?;
+    private session?;
+    private queuedBytes;
+    private pendingBytes;
+    private consecutiveFailures;
+    private currentAttempt;
+    private pumpPromise?;
+    private pumpStopped;
+    private closing;
+    private pumpWakeup?;
+    private closed;
+    private fatalError?;
+    private _lastAckedPosition?;
+    private acksController?;
+    readonly readable: ReadableStream<AppendAck>;
+    readonly writable: WritableStream<AppendArgs>;
+    /**
+     * If the session has failed, returns the original fatal error that caused
+     * the pump to stop. Returns undefined when the session has not failed.
+     */
+    failureCause(): S2Error | undefined;
+    constructor(generator: (options?: AppendSessionOptions) => Promise<TransportAppendSession>, sessionOptions?: AppendSessionOptions | undefined, config?: RetryConfig);
+    static create(generator: (options?: AppendSessionOptions) => Promise<TransportAppendSession>, sessionOptions?: AppendSessionOptions, config?: RetryConfig): Promise<RetryAppendSession>;
+    /**
+     * Submit an append request. Returns a promise that resolves with the ack.
+     * This method does not block on capacity (only writable.write() does).
+     */
+    submit(records: AppendRecord | AppendRecord[], args?: Omit<AppendArgs, "records"> & {
+        precalculatedSize?: number;
+    }): Promise<AppendAck>;
+    /**
+     * Internal submit that returns discriminated union.
+     * Creates inflight entry and starts pump if needed.
+     */
+    private submitInternal;
+    /**
+     * Wait for capacity before allowing write to proceed (writable only).
+     */
+    private waitForCapacity;
+    /**
+     * Release capacity and wake waiter if present.
+     */
+    private releaseCapacity;
+    /**
+     * Ensure pump loop is running.
+     */
+    private ensurePump;
+    /**
+     * Main pump loop: processes inflight queue, handles acks, retries, and recovery.
+     */
+    private runPump;
+    /**
+     * Wait for head entry's innerPromise with timeout.
+     * Returns either the settled result or a timeout indicator.
+     *
+     * Per-attempt ack timeout semantics:
+     * - The deadline is computed from the most recent (re)submit attempt using
+     *   a monotonic clock (performance.now) to avoid issues with wall clock
+     *   adjustments.
+     * - If attempt start is missing (for backward compatibility), we measure
+     *   from "now" with the full timeout window.
+     */
+    private waitForHead;
+    /**
+     * Recover from transient error: recreate session and resubmit all inflight entries.
+     */
+    private recover;
+    /**
+     * Check if append can be retried under noSideEffects policy.
+     * For appends, idempotency requires match_seq_num.
+     */
+    private isIdempotent;
+    /**
+     * Ensure session exists, creating it if necessary.
+     */
+    private ensureSession;
+    /**
+     * Abort the session with a fatal error.
+     */
+    private abort;
+    /**
+     * Close the append session.
+     * Waits for all pending appends to complete before resolving.
+     * Does not interrupt recovery - allows it to complete.
+     */
+    close(): Promise<void>;
+    [Symbol.asyncDispose](): Promise<void>;
+    /**
+     * Get a stream of acknowledgements for appends.
+     */
+    acks(): AcksStream;
+    /**
+     * Get the last acknowledged position.
+     */
+    lastAckedPosition(): AppendAck | undefined;
+}
+//# sourceMappingURL=retry.d.ts.map

package/dist/esm/lib/retry.d.ts.map

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