@s2-dev/streamstore 0.19.5 → 0.21.0

package/dist/esm/lib/stream/types.d.ts

@@ -1,31 +1,38 @@
 import type { RetryConfig, S2RequestOptions } from "../../common.js";
-import type { S2Error } from "../../error.js";
-import type { AppendAck, AppendInput as GeneratedAppendInput, AppendRecord as GeneratedAppendRecord, ReadBatch as GeneratedReadBatch, SequencedRecord as GeneratedSequencedRecord, ReadData, StreamPosition } from "../../generated/index.js";
+import { S2Error } from "../../error.js";
+import type * as API from "../../generated/index.js";
+import type * as Types from "../../types.js";
 import type * as Redacted from "../redacted.js";
+import type * as Result from "../result.js";
 export type ReadHeaders<Format extends "string" | "bytes" = "string"> = Format extends "string" ? Record<string, string> : Array<[Uint8Array, Uint8Array]>;
-export type ReadBatch<Format extends "string" | "bytes" = "string"> = Omit<GeneratedReadBatch, "records"> & {
+/**
+ * Internal read batch type used by transports.
+ * Records use API-level field names (snake_case).
+ */
+export type ReadBatch<Format extends "string" | "bytes" = "string"> = {
     records: Array<ReadRecord<Format>>;
+    tail?: API.StreamPosition | null;
 };
-export type ReadRecord<Format extends "string" | "bytes" = "string"> = Omit<GeneratedSequencedRecord, "body" | "headers"> & {
+/**
+ * Internal read record type used by transports.
+ * Uses API-level field names (snake_case).
+ */
+export type ReadRecord<Format extends "string" | "bytes" = "string"> = {
+    seq_num: number;
+    timestamp: number;
     body?: Format extends "string" ? string : Uint8Array;
     headers?: ReadHeaders<Format>;
 };
-export type ReadArgs<Format extends "string" | "bytes" = "string"> = ReadData["query"] & {
+export type ReadArgs<Format extends "string" | "bytes" = "string"> = API.ReadData["query"] & {
     as?: Format;
 };
-export type AppendHeaders<Format extends "string" | "bytes" = "string"> = Format extends "string" ? Array<[string, string]> | Record<string, string> : Array<[Uint8Array, Uint8Array]>;
-export type AppendRecordForFormat<Format extends "string" | "bytes" = "string"> = Omit<GeneratedAppendRecord, "body" | "headers"> & {
-    body?: Format extends "string" ? string : Uint8Array;
-    headers?: AppendHeaders<Format>;
-};
-export type AppendRecord = AppendRecordForFormat<"string"> | AppendRecordForFormat<"bytes">;
-export type AppendArgs = Omit<GeneratedAppendInput, "records"> & {
-    records: Array<AppendRecord>;
-};
+export type AppendHeaders<Format extends "string" | "bytes" = "string"> = Format extends "string" ? Array<[string, string]> : Array<[Uint8Array, Uint8Array]>;
+export type AppendRecordForFormat<Format extends "string" | "bytes" = "string"> = Format extends "string" ? Types.StringAppendRecord : Types.BytesAppendRecord;
+export type AppendRecord = Types.AppendRecord;
 /**
  * Stream of append acknowledgements used by {@link AppendSession}.
  */
-export interface AcksStream extends ReadableStream<AppendAck>, AsyncIterable<AppendAck> {
+export interface AcksStream extends ReadableStream<Types.AppendAck>, AsyncIterable<Types.AppendAck> {
 }
 /**
  * Low-level append session implemented by transports.
@@ -34,31 +41,54 @@ export interface AcksStream extends ReadableStream<AppendAck>, AsyncIterable<App
  * - Does not implement retry or backpressure; those are added by {@link AppendSession}.
  */
 export interface TransportAppendSession {
-    submit(records: AppendRecord | AppendRecord[], args?: Omit<AppendArgs, "records"> & {
-        precalculatedSize?: number;
-    }): Promise<import("../result.js").AppendResult>;
-    close(): Promise<import("../result.js").CloseResult>;
+    submit(input: Types.AppendInput): Promise<Result.AppendResult>;
+    close(): Promise<Result.CloseResult>;
+}
+export declare class BatchSubmitTicket {
+    private readonly promise;
+    readonly bytes: number;
+    readonly numRecords: number;
+    constructor(promise: Promise<Types.AppendAck>, bytes: number, numRecords: number);
+    /**
+     * Returns a promise that resolves with the AppendAck once the batch is durable.
+     */
+    ack(): Promise<Types.AppendAck>;
 }
 /**
- * Public AppendSession interface with retry, backpressure, and streams.
- * This is what users interact with - implemented by AppendSession in ../retry.ts.
+ * Public AppendSession interface with retry, backpressure, and readable/writable streams.
+ *
+ * Typical lifecycle:
+ * 1. Call {@link S2Stream.appendSession} to create a session (optionally tuning {@link AppendSessionOptions}).
+ * 2. Submit batches with {@link AppendSession.submit} or pipe `AppendInput` objects into {@link AppendSession.writable}.
+ * 3. Observe acknowledgements via {@link AppendSession.readable} / {@link AppendSession.acks}.
+ * 4. Call {@link AppendSession.close} to flush and surface any fatal errors.
+ *
+ * @example
+ * ```ts
+ * const session = await stream.appendSession();
+ * const ackTicket = await session.submit(
+ *   AppendInput.create([AppendRecord.string({ body: "event" })]),
+ * );
+ * await ackTicket.ack();
+ * await session.close();
+ * ```
  */
 export interface AppendSession extends AsyncDisposable {
     /**
      * Readable stream of acknowledgements for appends.
      */
-    readonly readable: ReadableStream<AppendAck>;
+    readonly readable: ReadableStream<Types.AppendAck>;
     /**
      * Writable stream of append requests.
      */
-    readonly writable: WritableStream<AppendArgs>;
+    readonly writable: WritableStream<Types.AppendInput>;
     /**
-     * Submit an append request and await its acknowledgement.
-     * This method does not apply backpressure; use {@link writable} for that.
+     * Submit an append request.
+     * Returns a promise that resolves to a submit ticket once the batch is enqueued (has capacity).
+     * Call ticket.ack() to get a promise for the AppendAck once the batch is durable.
+     * This method applies backpressure and will block if capacity limits are reached.
      */
-    submit(records: AppendRecord | AppendRecord[], args?: Omit<AppendArgs, "records"> & {
-        precalculatedSize?: number;
-    }): Promise<AppendAck>;
+    submit(input: Types.AppendInput): Promise<BatchSubmitTicket>;
     /**
      * Close the append session, waiting for all inflight appends to settle.
      */
@@ -70,7 +100,7 @@ export interface AppendSession extends AsyncDisposable {
     /**
      * Get the last acknowledged position, if any.
      */
-    lastAckedPosition(): AppendAck | undefined;
+    lastAckedPosition(): Types.AppendAck | undefined;
     /**
      * If the session failed, returns the fatal error that caused it to stop.
      */
@@ -93,22 +123,36 @@ export type ReadResult<Format extends "string" | "bytes" = "string"> = {
  * ReadSession wraps these and converts them to the public ReadSession interface.
  */
 export interface TransportReadSession<Format extends "string" | "bytes" = "string"> extends ReadableStream<ReadResult<Format>>, AsyncIterable<ReadResult<Format>>, AsyncDisposable {
-    nextReadPosition(): StreamPosition | undefined;
-    lastObservedTail(): StreamPosition | undefined;
+    nextReadPosition(): API.StreamPosition | undefined;
+    lastObservedTail(): API.StreamPosition | undefined;
 }
 /**
  * Public-facing read session interface.
- * Yields records directly and propagates errors by throwing (standard stream behavior).
+ *
+ * Yields records directly (as an async iterable or `ReadableStream`) and translates transport errors into thrown exceptions.
+ * Track progress using {@link ReadSession.nextReadPosition} / {@link ReadSession.lastObservedTail}.
+ *
+ * @example
+ * ```ts
+ * const session = await stream.readSession({
+ *   start: { from: { tailOffset: 50 } },
+ *   stop: { wait: 15 },
+ * });
+ *
+ * for await (const record of session) {
+ *   console.log(record.seqNum, record.body);
+ * }
+ * ```
  */
-export interface ReadSession<Format extends "string" | "bytes" = "string"> extends ReadableStream<ReadRecord<Format>>, AsyncIterable<ReadRecord<Format>>, AsyncDisposable {
+export interface ReadSession<Format extends "string" | "bytes" = "string"> extends ReadableStream<Types.ReadRecord<Format>>, AsyncIterable<Types.ReadRecord<Format>>, AsyncDisposable {
     /**
      * Get the next read position, if known.
      */
-    nextReadPosition(): StreamPosition | undefined;
+    nextReadPosition(): Types.StreamPosition | undefined;
     /**
      * Get the last observed tail position, if known.
      */
-    lastObservedTail(): StreamPosition | undefined;
+    lastObservedTail(): Types.StreamPosition | undefined;
 }
 /**
  * Options that control client-side append backpressure and concurrency.
@@ -117,7 +161,7 @@ export interface ReadSession<Format extends "string" | "bytes" = "string"> exten
  */
 export interface AppendSessionOptions {
     /**
-     * Aggregate size of records, as calculated by {@link meteredBytes}, to allow in-flight before applying backpressure (default: 10 MiB).
+     * Aggregate size of records, as calculated by {@link meteredBytes}, to allow in-flight before applying backpressure (default: 3 MiB).
      */
     maxInflightBytes?: number;
     /**
@@ -129,6 +173,7 @@ export interface AppendSessionOptions {
 export interface SessionTransport {
     makeAppendSession(stream: string, args?: AppendSessionOptions, options?: S2RequestOptions): Promise<AppendSession>;
     makeReadSession<Format extends "string" | "bytes" = "string">(stream: string, args?: ReadArgs<Format>, options?: S2RequestOptions): Promise<ReadSession<Format>>;
+    close(): Promise<void>;
 }
 export type SessionTransports = "fetch" | "s2s";
 export interface TransportConfig {

package/dist/esm/lib/stream/types.d.ts.map

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

package/dist/esm/lib/stream/types.js

@@ -1,2 +1,18 @@
-export {};
+import { S2Error } from "../../error.js";
+export class BatchSubmitTicket {
+    promise;
+    bytes;
+    numRecords;
+    constructor(promise, bytes, numRecords) {
+        this.promise = promise;
+        this.bytes = bytes;
+        this.numRecords = numRecords;
+    }
+    /**
+     * Returns a promise that resolves with the AppendAck once the batch is durable.
+     */
+    ack() {
+        return this.promise;
+    }
+}
 //# sourceMappingURL=types.js.map

package/dist/esm/lib/stream/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../src/lib/stream/types.ts"],"names":[],"mappings":""}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../src/lib/stream/types.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAoEzC,MAAM,OAAO,iBAAiB;IAEX;IACD;IACA;IAHjB,YACkB,OAAiC,EAClC,KAAa,EACb,UAAkB;QAFjB,YAAO,GAAP,OAAO,CAA0B;QAClC,UAAK,GAAL,KAAK,CAAQ;QACb,eAAU,GAAV,UAAU,CAAQ;IAChC,CAAC;IAEJ;;OAEG;IACH,GAAG;QACF,OAAO,IAAI,CAAC,OAAO,CAAC;IACrB,CAAC;CACD"}

package/dist/esm/metrics.d.ts

@@ -1,12 +1,13 @@
-import type { DataToObject, RetryConfig, S2RequestOptions } from "./common.js";
+import type { RetryConfig, S2RequestOptions } from "./common.js";
 import type { Client } from "./generated/client/types.gen.js";
-import { type AccountMetricsData, type BasinMetricsData, type StreamMetricsData } from "./generated/index.js";
-export interface AccountMetricsArgs extends DataToObject<AccountMetricsData> {
-}
-export interface BasinMetricsArgs extends DataToObject<BasinMetricsData> {
-}
-export interface StreamMetricsArgs extends DataToObject<StreamMetricsData> {
-}
+import type * as Types from "./types.js";
+/** Convert API metric response to SDK types with Date conversions. */
+export declare function fromAPIMetricSetResponse(response: unknown): Types.MetricSetResponse;
+/**
+ * Helper for querying account, basin, and stream level metrics.
+ *
+ * Access via {@link S2.metrics}. Responses are automatically converted to Date-friendly SDK types.
+ */
 export declare class S2Metrics {
     readonly client: Client;
     private readonly retryConfig?;
@@ -15,31 +16,31 @@ export declare class S2Metrics {
      * Account-level metrics.
      *
      * @param args.set Metric set to return
-     * @param args.start Optional start timestamp (Unix seconds)
-     * @param args.end Optional end timestamp (Unix seconds)
+     * @param args.start Optional start timestamp (milliseconds since Unix epoch)
+     * @param args.end Optional end timestamp (milliseconds since Unix epoch)
      * @param args.interval Optional aggregation interval for timeseries sets
      */
-    account(args: AccountMetricsArgs, options?: S2RequestOptions): Promise<import("./generated/types.gen.js").MetricSetResponse>;
+    account(args: Types.AccountMetricsInput, options?: S2RequestOptions): Promise<Types.MetricSetResponse>;
     /**
      * Basin-level metrics.
      *
      * @param args.basin Basin name
      * @param args.set Metric set to return
-     * @param args.start Optional start timestamp (Unix seconds)
-     * @param args.end Optional end timestamp (Unix seconds)
+     * @param args.start Optional start timestamp (milliseconds since Unix epoch)
+     * @param args.end Optional end timestamp (milliseconds since Unix epoch)
      * @param args.interval Optional aggregation interval for timeseries sets
      */
-    basin(args: BasinMetricsArgs, options?: S2RequestOptions): Promise<import("./generated/types.gen.js").MetricSetResponse>;
+    basin(args: Types.BasinMetricsInput, options?: S2RequestOptions): Promise<Types.MetricSetResponse>;
     /**
      * Stream-level metrics.
      *
      * @param args.basin Basin name
      * @param args.stream Stream name
      * @param args.set Metric set to return
-     * @param args.start Optional start timestamp (Unix seconds)
-     * @param args.end Optional end timestamp (Unix seconds)
+     * @param args.start Optional start timestamp (milliseconds since Unix epoch)
+     * @param args.end Optional end timestamp (milliseconds since Unix epoch)
      * @param args.interval Optional aggregation interval for timeseries sets
      */
-    stream(args: StreamMetricsArgs, options?: S2RequestOptions): Promise<import("./generated/types.gen.js").MetricSetResponse>;
+    stream(args: Types.StreamMetricsInput, options?: S2RequestOptions): Promise<Types.MetricSetResponse>;
 }
 //# sourceMappingURL=metrics.d.ts.map

package/dist/esm/metrics.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"metrics.d.ts","sourceRoot":"","sources":["../../src/metrics.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAE/E,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,iCAAiC,CAAC;AAC9D,OAAO,EACN,KAAK,kBAAkB,EAEvB,KAAK,gBAAgB,EAErB,KAAK,iBAAiB,EAEtB,MAAM,sBAAsB,CAAC;AAG9B,MAAM,WAAW,kBAAmB,SAAQ,YAAY,CAAC,kBAAkB,CAAC;CAAG;AAC/E,MAAM,WAAW,gBAAiB,SAAQ,YAAY,CAAC,gBAAgB,CAAC;CAAG;AAC3E,MAAM,WAAW,iBAAkB,SAAQ,YAAY,CAAC,iBAAiB,CAAC;CAAG;AAE7E,qBAAa,SAAS;IACrB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAc;gBAE/B,MAAM,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,WAAW;IAKrD;;;;;;;OAOG;IACU,OAAO,CAAC,IAAI,EAAE,kBAAkB,EAAE,OAAO,CAAC,EAAE,gBAAgB;IAYzE;;;;;;;;OAQG;IACU,KAAK,CAAC,IAAI,EAAE,gBAAgB,EAAE,OAAO,CAAC,EAAE,gBAAgB;IAarE;;;;;;;;;OASG;IACU,MAAM,CAAC,IAAI,EAAE,iBAAiB,EAAE,OAAO,CAAC,EAAE,gBAAgB;CAYvE"}
+{"version":3,"file":"metrics.d.ts","sourceRoot":"","sources":["../../src/metrics.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAEjE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,iCAAiC,CAAC;AAQ9D,OAAO,KAAK,KAAK,KAAK,MAAM,YAAY,CAAC;AASzC,sEAAsE;AACtE,wBAAgB,wBAAwB,CACvC,QAAQ,EAAE,OAAO,GACf,KAAK,CAAC,iBAAiB,CAqCzB;AAED;;;;GAIG;AACH,qBAAa,SAAS;IACrB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAc;gBAE/B,MAAM,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,WAAW;IAKrD;;;;;;;OAOG;IACU,OAAO,CACnB,IAAI,EAAE,KAAK,CAAC,mBAAmB,EAC/B,OAAO,CAAC,EAAE,gBAAgB,GACxB,OAAO,CAAC,KAAK,CAAC,iBAAiB,CAAC;IAiBnC;;;;;;;;OAQG;IACU,KAAK,CACjB,IAAI,EAAE,KAAK,CAAC,iBAAiB,EAC7B,OAAO,CAAC,EAAE,gBAAgB,GACxB,OAAO,CAAC,KAAK,CAAC,iBAAiB,CAAC;IAkBnC;;;;;;;;;OASG;IACU,MAAM,CAClB,IAAI,EAAE,KAAK,CAAC,kBAAkB,EAC9B,OAAO,CAAC,EAAE,gBAAgB,GACxB,OAAO,CAAC,KAAK,CAAC,iBAAiB,CAAC;CAiBnC"}

package/dist/esm/metrics.js

@@ -1,6 +1,45 @@
 import { withS2Data } from "./error.js";
 import { accountMetrics, basinMetrics, streamMetrics, } from "./generated/index.js";
+import { toCamelCase, toSnakeCase } from "./internal/case-transform.js";
 import { withRetries } from "./lib/retry.js";
+/** Convert timestamp (Date or milliseconds) to Unix seconds (floored). */
+function toEpochSeconds(value) {
+    if (value === undefined)
+        return undefined;
+    const ms = typeof value === "number" ? value : value.getTime();
+    return Math.floor(ms / 1000);
+}
+/** Convert API metric response to SDK types with Date conversions. */
+export function fromAPIMetricSetResponse(response) {
+    const camelCased = toCamelCase(response);
+    // Convert timeseries timestamps from seconds to Date
+    return {
+        values: camelCased.values.map((metric) => {
+            if ("accumulation" in metric) {
+                return {
+                    accumulation: {
+                        ...metric.accumulation,
+                        values: metric.accumulation.values.map(([ts, value]) => [new Date(ts * 1000), value]),
+                    },
+                };
+            }
+            if ("gauge" in metric) {
+                return {
+                    gauge: {
+                        ...metric.gauge,
+                        values: metric.gauge.values.map(([ts, value]) => [new Date(ts * 1000), value]),
+                    },
+                };
+            }
+            return metric;
+        }),
+    };
+}
+/**
+ * Helper for querying account, basin, and stream level metrics.
+ *
+ * Access via {@link S2.metrics}. Responses are automatically converted to Date-friendly SDK types.
+ */
 export class S2Metrics {
     client;
     retryConfig;
@@ -12,37 +51,47 @@ export class S2Metrics {
      * Account-level metrics.
      *
      * @param args.set Metric set to return
-     * @param args.start Optional start timestamp (Unix seconds)
-     * @param args.end Optional end timestamp (Unix seconds)
+     * @param args.start Optional start timestamp (milliseconds since Unix epoch)
+     * @param args.end Optional end timestamp (milliseconds since Unix epoch)
      * @param args.interval Optional aggregation interval for timeseries sets
      */
     async account(args, options) {
-        return await withRetries(this.retryConfig, async () => {
+        const response = await withRetries(this.retryConfig, async () => {
             return await withS2Data(() => accountMetrics({
                 client: this.client,
-                query: args,
+                query: toSnakeCase({
+                    ...args,
+                    start: toEpochSeconds(args.start),
+                    end: toEpochSeconds(args.end),
+                }),
                 ...options,
             }));
         });
+        return fromAPIMetricSetResponse(response);
     }
     /**
      * Basin-level metrics.
      *
      * @param args.basin Basin name
      * @param args.set Metric set to return
-     * @param args.start Optional start timestamp (Unix seconds)
-     * @param args.end Optional end timestamp (Unix seconds)
+     * @param args.start Optional start timestamp (milliseconds since Unix epoch)
+     * @param args.end Optional end timestamp (milliseconds since Unix epoch)
      * @param args.interval Optional aggregation interval for timeseries sets
      */
     async basin(args, options) {
-        return await withRetries(this.retryConfig, async () => {
+        const response = await withRetries(this.retryConfig, async () => {
             return await withS2Data(() => basinMetrics({
                 client: this.client,
                 path: args,
-                query: args,
+                query: toSnakeCase({
+                    ...args,
+                    start: toEpochSeconds(args.start),
+                    end: toEpochSeconds(args.end),
+                }),
                 ...options,
             }));
         });
+        return fromAPIMetricSetResponse(response);
     }
     /**
      * Stream-level metrics.
@@ -50,19 +99,24 @@ export class S2Metrics {
      * @param args.basin Basin name
      * @param args.stream Stream name
      * @param args.set Metric set to return
-     * @param args.start Optional start timestamp (Unix seconds)
-     * @param args.end Optional end timestamp (Unix seconds)
+     * @param args.start Optional start timestamp (milliseconds since Unix epoch)
+     * @param args.end Optional end timestamp (milliseconds since Unix epoch)
      * @param args.interval Optional aggregation interval for timeseries sets
      */
     async stream(args, options) {
-        return await withRetries(this.retryConfig, async () => {
+        const response = await withRetries(this.retryConfig, async () => {
             return await withS2Data(() => streamMetrics({
                 client: this.client,
                 path: args,
-                query: args,
+                query: toSnakeCase({
+                    ...args,
+                    start: toEpochSeconds(args.start),
+                    end: toEpochSeconds(args.end),
+                }),
                 ...options,
             }));
         });
+        return fromAPIMetricSetResponse(response);
     }
 }
 //# sourceMappingURL=metrics.js.map

package/dist/esm/metrics.js.map

@@ -1 +1 @@
-{"version":3,"file":"metrics.js","sourceRoot":"","sources":["../../src/metrics.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAExC,OAAO,EAEN,cAAc,EAEd,YAAY,EAEZ,aAAa,GACb,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAM7C,MAAM,OAAO,SAAS;IACZ,MAAM,CAAS;IACP,WAAW,CAAe;IAE3C,YAAY,MAAc,EAAE,WAAyB;QACpD,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,WAAW,GAAG,WAAW,CAAC;IAChC,CAAC;IAED;;;;;;;OAOG;IACI,KAAK,CAAC,OAAO,CAAC,IAAwB,EAAE,OAA0B;QACxE,OAAO,MAAM,WAAW,CAAC,IAAI,CAAC,WAAW,EAAE,KAAK,IAAI,EAAE;YACrD,OAAO,MAAM,UAAU,CAAC,GAAG,EAAE,CAC5B,cAAc,CAAC;gBACd,MAAM,EAAE,IAAI,CAAC,MAAM;gBACnB,KAAK,EAAE,IAAI;gBACX,GAAG,OAAO;aACV,CAAC,CACF,CAAC;QACH,CAAC,CAAC,CAAC;IACJ,CAAC;IAED;;;;;;;;OAQG;IACI,KAAK,CAAC,KAAK,CAAC,IAAsB,EAAE,OAA0B;QACpE,OAAO,MAAM,WAAW,CAAC,IAAI,CAAC,WAAW,EAAE,KAAK,IAAI,EAAE;YACrD,OAAO,MAAM,UAAU,CAAC,GAAG,EAAE,CAC5B,YAAY,CAAC;gBACZ,MAAM,EAAE,IAAI,CAAC,MAAM;gBACnB,IAAI,EAAE,IAAI;gBACV,KAAK,EAAE,IAAI;gBACX,GAAG,OAAO;aACV,CAAC,CACF,CAAC;QACH,CAAC,CAAC,CAAC;IACJ,CAAC;IAED;;;;;;;;;OASG;IACI,KAAK,CAAC,MAAM,CAAC,IAAuB,EAAE,OAA0B;QACtE,OAAO,MAAM,WAAW,CAAC,IAAI,CAAC,WAAW,EAAE,KAAK,IAAI,EAAE;YACrD,OAAO,MAAM,UAAU,CAAC,GAAG,EAAE,CAC5B,aAAa,CAAC;gBACb,MAAM,EAAE,IAAI,CAAC,MAAM;gBACnB,IAAI,EAAE,IAAI;gBACV,KAAK,EAAE,IAAI;gBACX,GAAG,OAAO;aACV,CAAC,CACF,CAAC;QACH,CAAC,CAAC,CAAC;IACJ,CAAC;CACD"}
+{"version":3,"file":"metrics.js","sourceRoot":"","sources":["../../src/metrics.ts"],"names":[],"mappings":"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"}

package/dist/esm/producer.d.ts

@@ -0,0 +1,82 @@
+import { type BatchOutput, BatchTransform } from "./batch-transform.js";
+import type { AppendSession } from "./lib/stream/types.js";
+import { type AppendAck, type AppendRecord } from "./types.js";
+export declare class IndexedAppendAck {
+    readonly index: number;
+    readonly ack: AppendAck;
+    constructor(index: number, ack: AppendAck);
+    batchAppendAck(): AppendAck;
+    seqNum(): number;
+}
+export declare class RecordSubmitTicket {
+    private readonly ackPromise;
+    constructor(ackPromise: Promise<IndexedAppendAck>);
+    /**
+     * Returns a promise that resolves with the IndexedAppendAck once the record is durable.
+     */
+    ack(): Promise<IndexedAppendAck>;
+}
+/**
+ * Producer provides per-record append semantics on top of a batched AppendSession.
+ *
+ * - submit(record) returns a Promise<RecordSubmitTicket> that resolves once the record
+ *   has been accepted (written to the batch transform). Backpressure is applied
+ *   automatically via the transform stream when the AppendSession is at capacity.
+ * - ticket.ack() returns a Promise<IndexedAppendAck> that resolves once the record is durable.
+ *
+ * See the "Producer API" section of the root README for guidance on sizing batches,
+ * wiring transforms, and handling application-level ids.
+ *
+ * @example
+ * ```ts
+ * const appendSession = await stream.appendSession();
+ * const producer = new Producer(new BatchTransform(), appendSession);
+ * const writer = producer.writable.getWriter();
+ * await writer.write(AppendRecord.string({ body: "hello" }));
+ * await writer.close();
+ *
+ * for await (const ack of producer.readable) {
+ *   console.log("record durable at seq", ack.seqNum());
+ * }
+ *
+ * await producer.close();
+ * ```
+ */
+export declare class Producer implements AsyncDisposable {
+    readonly batchTransform: BatchTransform;
+    readonly transformWriter: WritableStreamDefaultWriter<AppendRecord>;
+    readonly transformReader: ReadableStreamDefaultReader<BatchOutput>;
+    readonly pump: Promise<void>;
+    readonly appendSession: AppendSession;
+    readonly readable: ReadableStream<IndexedAppendAck>;
+    readonly writable: WritableStream<AppendRecord>;
+    private readonly inflightRecords;
+    private pumpError;
+    private readableController;
+    private readonly debugName;
+    private submitCounter;
+    constructor(batchTransform: BatchTransform, appendSession: AppendSession, debugName?: string);
+    /**
+     * Main pump loop: reads batches from transform, submits to session, handles acks.
+     */
+    private runPump;
+    /**
+     * Submit a single record for appending.
+     *
+     * Returns a promise that resolves to a RecordSubmitTicket once the record has been
+     * accepted. The promise blocks if the underlying AppendSession is at capacity
+     * (backpressure is applied via the transform stream).
+     *
+     * @throws S2Error if the Producer has failed
+     */
+    submit(record: AppendRecord): Promise<RecordSubmitTicket>;
+    /**
+     * Close the Producer gracefully.
+     *
+     * Waits for all pending records to be flushed, submitted, and acknowledged.
+     * If any error occurred during the Producer's lifetime, this method throws it.
+     */
+    close(): Promise<void>;
+    [Symbol.asyncDispose](): Promise<void>;
+}
+//# sourceMappingURL=producer.d.ts.map

package/dist/esm/producer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"producer.d.ts","sourceRoot":"","sources":["../../src/producer.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,WAAW,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAExE,OAAO,KAAK,EAAE,aAAa,EAAqB,MAAM,uBAAuB,CAAC;AAC9E,OAAO,EAAE,KAAK,SAAS,EAAe,KAAK,YAAY,EAAE,MAAM,YAAY,CAAC;AAa5E,qBAAa,gBAAgB;IAE3B,QAAQ,CAAC,KAAK,EAAE,MAAM;IACtB,QAAQ,CAAC,GAAG,EAAE,SAAS;gBADd,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,SAAS;IAGxB,cAAc,IAAI,SAAS;IAI3B,MAAM,IAAI,MAAM;CAGhB;AAED,qBAAa,kBAAkB;IAClB,OAAO,CAAC,QAAQ,CAAC,UAAU;gBAAV,UAAU,EAAE,OAAO,CAAC,gBAAgB,CAAC;IAKlE;;OAEG;IACH,GAAG,IAAI,OAAO,CAAC,gBAAgB,CAAC;CAGhC;AAWD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,qBAAa,QAAS,YAAW,eAAe;IAC/C,QAAQ,CAAC,cAAc,EAAE,cAAc,CAAC;IACxC,QAAQ,CAAC,eAAe,EAAE,2BAA2B,CAAC,YAAY,CAAC,CAAC;IACpE,QAAQ,CAAC,eAAe,EAAE,2BAA2B,CAAC,WAAW,CAAC,CAAC;IAEnE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IAE7B,QAAQ,CAAC,aAAa,EAAE,aAAa,CAAC;IAEtC,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAC,gBAAgB,CAAC,CAAC;IACpD,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAC,YAAY,CAAC,CAAC;IAEhD,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAwB;IAExD,OAAO,CAAC,SAAS,CAAwB;IACzC,OAAO,CAAC,kBAAkB,CACpB;IAEN,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,aAAa,CAAK;gBAGzB,cAAc,EAAE,cAAc,EAC9B,aAAa,EAAE,aAAa,EAC5B,SAAS,CAAC,EAAE,MAAM;IAuCnB;;OAEG;YACW,OAAO;IA2IrB;;;;;;;;OAQG;IACG,MAAM,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,kBAAkB,CAAC;IA6E/D;;;;;OAKG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAuCtB,CAAC,MAAM,CAAC,YAAY,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC;CAG5C"}