@anabranch/eventlog 0.1.2 → 0.2.0

package/esm/eventlog.d.ts

@@ -1,8 +1,12 @@
-import { Source, Task } from "anabranch";
-import type { AppendOptions, ConsumeOptions, Event, EventBatch, EventLogAdapter, EventLogConnector, ListOptions } from "./adapter.js";
-import { EventLogAppendFailed, EventLogCloseFailed, EventLogCommitCursorFailed, EventLogConnectionFailed, EventLogGetCursorFailed, EventLogGetFailed, EventLogListFailed } from "./errors.js";
+import { Channel, Task } from 'anabranch';
+import type { AppendOptions, ConsumeOptions, EventBatch, EventLogAdapter, EventLogConnector } from './adapter.js';
+import { EventLogAppendFailed, EventLogCloseFailed, EventLogCommitCursorFailed, EventLogConnectionFailed, EventLogConsumeFailed, EventLogGetCursorFailed } from './errors.js';
 /**
- * EventLog wrapper with Task/Stream semantics for event-sourced systems.
+ * Event log wrapper with Task/Stream semantics for event-sourced systems.
+ *
+ * Provides high-level methods for appending events, consuming streams,
+ * and managing cursors. All operations return Tasks for composable error
+ * handling.
  *
  * @example Basic usage
  * ```ts
@@ -12,35 +16,34 @@ import { EventLogAppendFailed, EventLogCloseFailed, EventLogCommitCursorFailed,
  * const log = await EventLog.connect(connector).run();
  *
  * // Append an event
- * const eventId = await log.append("users", { action: "created", userId: 123 }).run();
- *
- * // Get a specific event
- * const event = await log.get("users", 0).run();
- *
- * // List events
- * const events = await log.list("users").run();
- *
- * await log.close().run();
- * ```
+ * const eventId = await log.append("users", { userId: 123 }).run();
  *
- * @example Consuming events as a stream
- * ```ts
+ * // Consume events as a stream
  * const { successes, errors } = await log
- *   .consume("users", "my-consumer-group")
+ *   .consume("users", "my-processor")
  *   .withConcurrency(5)
  *   .map(async (batch) => {
  *     for (const event of batch.events) {
- *       await handleEvent(event.data);
+ *       await processEvent(event.data);
  *     }
- *     // Explicitly commit after successful processing!
- *     await log.commit(batch.topic, batch.consumerGroup, batch.cursor).run();
  *   })
  *   .partition();
+ *
+ * await log.close().run();
+ * ```
+ *
+ * @example Manual cursor management
+ * ```ts
+ * // Get current cursor position
+ * const cursor = await log.getCommittedCursor("users", "my-processor").run();
+ *
+ * // Save cursor after processing
+ * await log.commit("users", "my-processor", batch.cursor).run();
  * ```
  */
-export declare class EventLog {
+export declare class EventLog<Cursor = string> {
     private readonly adapter;
-    constructor(adapter: EventLogAdapter);
+    constructor(adapter: EventLogAdapter<Cursor>);
     /**
      * Connect to an event log via a connector.
      *
@@ -49,9 +52,11 @@ export declare class EventLog {
      * const log = await EventLog.connect(createInMemory()).run();
      * ```
      */
-    static connect(connector: EventLogConnector): Task<EventLog, EventLogConnectionFailed>;
+    static connect<Cursor = string>(connector: EventLogConnector<Cursor>): Task<EventLog<Cursor>, EventLogConnectionFailed>;
     /**
-     * Release the connection back to its source.
+     * Close the event log connection.
+     *
+     * After closing, no further operations can be performed on this instance.
      *
      * @example
      * ```ts
@@ -62,110 +67,87 @@ export declare class EventLog {
     /**
      * Append an event to a topic.
      *
-     * @example Basic append
-     * ```ts
-     * const eventId = await log.append("users", { action: "created", userId: 123 }).run();
-     * ```
+     * Returns the event ID which can be used for logging or correlation.
      *
-     * @example With partition key
+     * @example
      * ```ts
-     * const eventId = await log.append("orders", orderData, {
-     *   partitionKey: orderData.userId,
+     * const eventId = await log.append("users", { action: "created" }).run();
+     *
+     * // With options
+     * await log.append("orders", order, {
+     *   partitionKey: order.userId,
+     *   metadata: { source: "checkout" },
      * }).run();
      * ```
      */
     append<T>(topic: string, data: T, options?: AppendOptions): Task<string, EventLogAppendFailed>;
     /**
-     * Get a single event by topic and sequence number.
-     *
-     * @example
-     * ```ts
-     * const event = await log.get("users", 0).run();
-     * if (event) {
-     *   console.log(event.data);
-     * }
-     * ```
-     */
-    get<T>(topic: string, sequenceNumber: number): Task<Event<T> | null, EventLogGetFailed>;
-    /**
-     * List events in a topic with optional filtering and pagination.
+     * Consume events from a topic as a stream.
      *
-     * @example List all events
-     * ```ts
-     * const events = await log.list("users").run();
-     * ```
+     * Returns a Channel that yields batches of events. Each batch includes
+     * a cursor that can be committed to mark progress. Use stream methods
+     * like `withConcurrency()`, `map()`, and `partition()` for processing.
      *
-     * @example With pagination
-     * ```ts
-     * const events = await log.list("users", {
-     *   fromSequenceNumber: 100,
-     *   limit: 50,
-     * }).run();
-     * ```
+     * Batches are delivered asynchronously as they become available. Use
+     * `take()` to limit iterations or pass an AbortSignal in options to
+     * cancel consumption.
      *
-     * @example Filtered by partition key
+     * @example
      * ```ts
-     * const events = await log.list("orders", {
-     *   partitionKey: "user-123",
-     * }).run();
-     * ```
-     */
-    list<T>(topic: string, options?: ListOptions): Task<Event<T>[], EventLogListFailed>;
-    /**
-     * Consume events from a topic as a Source for streaming.
+     * const ac = new AbortController();
      *
-     * Note: You must manually commit the cursor after processing to guarantee
-     * at-least-once delivery. Auto-commit is intentionally omitted to prevent
-     * data loss when using concurrent processing.
-     *
-     * @example Basic consumption
-     * ```ts
-     * const { successes, errors } = await log
-     *   .consume("users", "processor-1")
-     *   .withConcurrency(5)
+     * await log.consume("users", "processor-1", { signal: ac.signal })
+     *   .withConcurrency(10)
      *   .map(async (batch) => {
      *     for (const event of batch.events) {
-     *       await handleEvent(event.data);
+     *       await processUser(event.data);
      *     }
-     *     await log.commit(batch.topic, batch.consumerGroup, batch.cursor).run();
+     *     await batch.commit(); // Mark progress
      *   })
      *   .partition();
+     *
+     * ac.abort(); // Stop consumption
      * ```
      *
-     * @example From specific cursor position
+     * @example Resume from a saved cursor
      * ```ts
-     * const lastCursor = await log.getCommittedCursor("users", "processor-1").run();
-     * const { successes } = await log
-     *   .consume("users", "processor-1", { cursor: lastCursor })
-     *   .tap(async (batch) => {
-     *     for (const event of batch.events) {
-     *       console.log(event);
-     *     }
-     *   })
-     *   .partition();
+     * const cursor = await log.getCommittedCursor("users", "processor-1").run();
+     * const stream = log.consume("users", "processor-1", { cursor });
      * ```
      */
-    consume<T>(topic: string, consumerGroup: string, options?: ConsumeOptions): Source<EventBatch<T>, EventLogListFailed>;
+    consume<T>(topic: string, consumerGroup: string, options?: ConsumeOptions<Cursor>): Channel<EventBatch<T, Cursor>, EventLogConsumeFailed>;
     /**
-     * Commit a cursor position for a consumer group.
+     * Commit a cursor to mark progress for a consumer group.
+     *
+     * This is for administrative use cases where you can't commit in-band, preferably when you're
+     * not actively consuming events. For example, you might want to skip ahead after a downtime or reset to the beginning for reprocessing.
+     * Do prefer to commit in-band, i.e. after processing each batch, by calling `batch.commit()`.
+     *
+     * After processing events, commit the cursor to resume from that position
+     * on the next run. Cursors are obtained from `batch.cursor` in the consume
+     * stream or from `getCommittedCursor()`.
      *
      * @example
      * ```ts
-     * await log.commit("users", "processor-1", cursor).run();
+     * await log.commit("users", "processor-1", batch.cursor).run();
      * ```
      */
-    commit(topic: string, consumerGroup: string, cursor: string): Task<void, EventLogCommitCursorFailed>;
+    commit(topic: string, consumerGroup: string, cursor: Cursor): Task<void, EventLogCommitCursorFailed>;
     /**
-     * Get the committed cursor position for a consumer group.
+     * Get the last committed cursor for a consumer group.
+     *
+     * Returns null if no cursor has been committed yet. Use this to resume
+     * consumption from the last processed position.
      *
      * @example
      * ```ts
      * const cursor = await log.getCommittedCursor("users", "processor-1").run();
      * if (cursor) {
-     *   console.log(`Resuming from cursor: ${cursor}`);
+     *   // Resume from saved position
+     *   const stream = log.consume("users", "processor-1", { cursor });
      * }
      * ```
      */
-    getCommittedCursor(topic: string, consumerGroup: string): Task<string | null, EventLogGetCursorFailed>;
+    getCommittedCursor(topic: string, consumerGroup: string): Task<Cursor | null, EventLogGetCursorFailed>;
 }
 //# sourceMappingURL=eventlog.d.ts.map

package/esm/eventlog.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"eventlog.d.ts","sourceRoot":"","sources":["../src/eventlog.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EACV,aAAa,EACb,cAAc,EACd,KAAK,EACL,UAAU,EACV,eAAe,EACf,iBAAiB,EACjB,WAAW,EACZ,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,oBAAoB,EACpB,mBAAmB,EACnB,0BAA0B,EAC1B,wBAAwB,EACxB,uBAAuB,EACvB,iBAAiB,EACjB,kBAAkB,EACnB,MAAM,aAAa,CAAC;AAErB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,qBAAa,QAAQ;IACP,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAAP,OAAO,EAAE,eAAe;IAErD;;;;;;;OAOG;IACH,MAAM,CAAC,OAAO,CACZ,SAAS,EAAE,iBAAiB,GAC3B,IAAI,CAAC,QAAQ,EAAE,wBAAwB,CAAC;IAa3C;;;;;;;OAOG;IACH,KAAK,IAAI,IAAI,CAAC,IAAI,EAAE,mBAAmB,CAAC;IAaxC;;;;;;;;;;;;;;OAcG;IACH,MAAM,CAAC,CAAC,EACN,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,CAAC,EACP,OAAO,CAAC,EAAE,aAAa,GACtB,IAAI,CAAC,MAAM,EAAE,oBAAoB,CAAC;IAcrC;;;;;;;;;;OAUG;IACH,GAAG,CAAC,CAAC,EACH,KAAK,EAAE,MAAM,EACb,cAAc,EAAE,MAAM,GACrB,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,IAAI,EAAE,iBAAiB,CAAC;IAe3C;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,IAAI,CAAC,CAAC,EACJ,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,WAAW,GACpB,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,kBAAkB,CAAC;IAcvC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;IACH,OAAO,CAAC,CAAC,EACP,KAAK,EAAE,MAAM,EACb,aAAa,EAAE,MAAM,EACrB,OAAO,CAAC,EAAE,cAAc,GACvB,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,kBAAkB,CAAC;IAmB5C;;;;;;;OAOG;IACH,MAAM,CACJ,KAAK,EAAE,MAAM,EACb,aAAa,EAAE,MAAM,EACrB,MAAM,EAAE,MAAM,GACb,IAAI,CAAC,IAAI,EAAE,0BAA0B,CAAC;IAezC;;;;;;;;;;OAUG;IACH,kBAAkB,CAChB,KAAK,EAAE,MAAM,EACb,aAAa,EAAE,MAAM,GACpB,IAAI,CAAC,MAAM,GAAG,IAAI,EAAE,uBAAuB,CAAC;CAchD"}
+{"version":3,"file":"eventlog.d.ts","sourceRoot":"","sources":["../src/eventlog.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AACzC,OAAO,KAAK,EACV,aAAa,EACb,cAAc,EACd,UAAU,EACV,eAAe,EACf,iBAAiB,EAClB,MAAM,cAAc,CAAA;AACrB,OAAO,EACL,oBAAoB,EACpB,mBAAmB,EACnB,0BAA0B,EAC1B,wBAAwB,EACxB,qBAAqB,EACrB,uBAAuB,EACxB,MAAM,aAAa,CAAA;AAEpB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,qBAAa,QAAQ,CAAC,MAAM,GAAG,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAAP,OAAO,EAAE,eAAe,CAAC,MAAM,CAAC;IAE7D;;;;;;;OAOG;IACH,MAAM,CAAC,OAAO,CAAC,MAAM,GAAG,MAAM,EAC5B,SAAS,EAAE,iBAAiB,CAAC,MAAM,CAAC,GACnC,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,wBAAwB,CAAC;IAanD;;;;;;;;;OASG;IACH,KAAK,IAAI,IAAI,CAAC,IAAI,EAAE,mBAAmB,CAAC;IAaxC;;;;;;;;;;;;;;;OAeG;IACH,MAAM,CAAC,CAAC,EACN,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,CAAC,EACP,OAAO,CAAC,EAAE,aAAa,GACtB,IAAI,CAAC,MAAM,EAAE,oBAAoB,CAAC;IAcrC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;IACH,OAAO,CAAC,CAAC,EACP,KAAK,EAAE,MAAM,EACb,aAAa,EAAE,MAAM,EACrB,OAAO,CAAC,EAAE,cAAc,CAAC,MAAM,CAAC,GAC/B,OAAO,CAAC,UAAU,CAAC,CAAC,EAAE,MAAM,CAAC,EAAE,qBAAqB,CAAC;IAsDxD;;;;;;;;;;;;;;;OAeG;IACH,MAAM,CACJ,KAAK,EAAE,MAAM,EACb,aAAa,EAAE,MAAM,EACrB,MAAM,EAAE,MAAM,GACb,IAAI,CAAC,IAAI,EAAE,0BAA0B,CAAC;IAezC;;;;;;;;;;;;;;OAcG;IACH,kBAAkB,CAChB,KAAK,EAAE,MAAM,EACb,aAAa,EAAE,MAAM,GACpB,IAAI,CAAC,MAAM,GAAG,IAAI,EAAE,uBAAuB,CAAC;CAchD"}

package/esm/eventlog.js

@@ -1,7 +1,11 @@
-import { Source, Task } from "anabranch";
-import { EventLogAppendFailed, EventLogCloseFailed, EventLogCommitCursorFailed, EventLogConnectionFailed, EventLogGetCursorFailed, EventLogGetFailed, EventLogListFailed, } from "./errors.js";
+import { Channel, Task } from 'anabranch';
+import { EventLogAppendFailed, EventLogCloseFailed, EventLogCommitCursorFailed, EventLogConnectionFailed, EventLogConsumeFailed, EventLogGetCursorFailed, } from './errors.js';
 /**
- * EventLog wrapper with Task/Stream semantics for event-sourced systems.
+ * Event log wrapper with Task/Stream semantics for event-sourced systems.
+ *
+ * Provides high-level methods for appending events, consuming streams,
+ * and managing cursors. All operations return Tasks for composable error
+ * handling.
  *
  * @example Basic usage
  * ```ts
@@ -11,30 +15,29 @@ import { EventLogAppendFailed, EventLogCloseFailed, EventLogCommitCursorFailed,
  * const log = await EventLog.connect(connector).run();
  *
  * // Append an event
- * const eventId = await log.append("users", { action: "created", userId: 123 }).run();
- *
- * // Get a specific event
- * const event = await log.get("users", 0).run();
- *
- * // List events
- * const events = await log.list("users").run();
- *
- * await log.close().run();
- * ```
+ * const eventId = await log.append("users", { userId: 123 }).run();
  *
- * @example Consuming events as a stream
- * ```ts
+ * // Consume events as a stream
  * const { successes, errors } = await log
- *   .consume("users", "my-consumer-group")
+ *   .consume("users", "my-processor")
  *   .withConcurrency(5)
  *   .map(async (batch) => {
  *     for (const event of batch.events) {
- *       await handleEvent(event.data);
+ *       await processEvent(event.data);
  *     }
- *     // Explicitly commit after successful processing!
- *     await log.commit(batch.topic, batch.consumerGroup, batch.cursor).run();
  *   })
  *   .partition();
+ *
+ * await log.close().run();
+ * ```
+ *
+ * @example Manual cursor management
+ * ```ts
+ * // Get current cursor position
+ * const cursor = await log.getCommittedCursor("users", "my-processor").run();
+ *
+ * // Save cursor after processing
+ * await log.commit("users", "my-processor", batch.cursor).run();
  * ```
  */
 export class EventLog {
@@ -65,7 +68,9 @@ export class EventLog {
         });
     }
     /**
-     * Release the connection back to its source.
+     * Close the event log connection.
+     *
+     * After closing, no further operations can be performed on this instance.
      *
      * @example
      * ```ts
@@ -85,15 +90,16 @@ export class EventLog {
     /**
      * Append an event to a topic.
      *
-     * @example Basic append
-     * ```ts
-     * const eventId = await log.append("users", { action: "created", userId: 123 }).run();
-     * ```
+     * Returns the event ID which can be used for logging or correlation.
      *
-     * @example With partition key
+     * @example
      * ```ts
-     * const eventId = await log.append("orders", orderData, {
-     *   partitionKey: orderData.userId,
+     * const eventId = await log.append("users", { action: "created" }).run();
+     *
+     * // With options
+     * await log.append("orders", order, {
+     *   partitionKey: order.userId,
+     *   metadata: { source: "checkout" },
      * }).run();
      * ```
      */
@@ -108,112 +114,82 @@ export class EventLog {
         });
     }
     /**
-     * Get a single event by topic and sequence number.
-     *
-     * @example
-     * ```ts
-     * const event = await log.get("users", 0).run();
-     * if (event) {
-     *   console.log(event.data);
-     * }
-     * ```
-     */
-    get(topic, sequenceNumber) {
-        return Task.of(async () => {
-            try {
-                return await this.adapter.get(topic, sequenceNumber);
-            }
-            catch (error) {
-                throw new EventLogGetFailed(topic, sequenceNumber, error instanceof Error ? error.message : String(error), error);
-            }
-        });
-    }
-    /**
-     * List events in a topic with optional filtering and pagination.
+     * Consume events from a topic as a stream.
      *
-     * @example List all events
-     * ```ts
-     * const events = await log.list("users").run();
-     * ```
+     * Returns a Channel that yields batches of events. Each batch includes
+     * a cursor that can be committed to mark progress. Use stream methods
+     * like `withConcurrency()`, `map()`, and `partition()` for processing.
      *
-     * @example With pagination
-     * ```ts
-     * const events = await log.list("users", {
-     *   fromSequenceNumber: 100,
-     *   limit: 50,
-     * }).run();
-     * ```
+     * Batches are delivered asynchronously as they become available. Use
+     * `take()` to limit iterations or pass an AbortSignal in options to
+     * cancel consumption.
      *
-     * @example Filtered by partition key
+     * @example
      * ```ts
-     * const events = await log.list("orders", {
-     *   partitionKey: "user-123",
-     * }).run();
-     * ```
-     */
-    list(topic, options) {
-        return Task.of(async () => {
-            try {
-                return await this.adapter.list(topic, options);
-            }
-            catch (error) {
-                throw new EventLogListFailed(topic, error instanceof Error ? error.message : String(error), error);
-            }
-        });
-    }
-    /**
-     * Consume events from a topic as a Source for streaming.
-     *
-     * Note: You must manually commit the cursor after processing to guarantee
-     * at-least-once delivery. Auto-commit is intentionally omitted to prevent
-     * data loss when using concurrent processing.
+     * const ac = new AbortController();
      *
-     * @example Basic consumption
-     * ```ts
-     * const { successes, errors } = await log
-     *   .consume("users", "processor-1")
-     *   .withConcurrency(5)
+     * await log.consume("users", "processor-1", { signal: ac.signal })
+     *   .withConcurrency(10)
      *   .map(async (batch) => {
      *     for (const event of batch.events) {
-     *       await handleEvent(event.data);
+     *       await processUser(event.data);
      *     }
-     *     await log.commit(batch.topic, batch.consumerGroup, batch.cursor).run();
+     *     await batch.commit(); // Mark progress
      *   })
      *   .partition();
+     *
+     * ac.abort(); // Stop consumption
      * ```
      *
-     * @example From specific cursor position
+     * @example Resume from a saved cursor
      * ```ts
-     * const lastCursor = await log.getCommittedCursor("users", "processor-1").run();
-     * const { successes } = await log
-     *   .consume("users", "processor-1", { cursor: lastCursor })
-     *   .tap(async (batch) => {
-     *     for (const event of batch.events) {
-     *       console.log(event);
-     *     }
-     *   })
-     *   .partition();
+     * const cursor = await log.getCommittedCursor("users", "processor-1").run();
+     * const stream = log.consume("users", "processor-1", { cursor });
      * ```
      */
     consume(topic, consumerGroup, options) {
-        const adapter = this.adapter;
-        return Source.from(async function* () {
-            try {
-                for await (const batch of adapter.consume(topic, consumerGroup, options)) {
-                    yield batch;
-                }
-            }
-            catch (error) {
-                throw new EventLogListFailed(topic, error instanceof Error ? error.message : String(error), error);
-            }
+        if (options?.bufferSize !== undefined) {
+            if (options.bufferSize <= 0 || !Number.isInteger(options.bufferSize)) {
+                throw new Error('bufferSize must be a positive integer');
+            }
+        }
+        if (options?.batchSize !== undefined) {
+            if (options.batchSize <= 0 || !Number.isInteger(options.batchSize)) {
+                throw new Error('batchSize must be a positive integer');
+            }
+        }
+        const channel = new Channel({
+            onDrop: (batch) => {
+                channel.fail(new EventLogConsumeFailed(topic, consumerGroup, `Batch dropped due to full buffer (events ${batch.events
+                    .map((e) => e.id)
+                    .join(',')})`));
+            },
+            onClose: () => close(),
+            bufferSize: options?.bufferSize ?? Infinity,
+            signal: options?.signal,
         });
+        const { close } = this.adapter.consume(topic, consumerGroup, async (batch) => {
+            await channel.waitForCapacity();
+            channel.send(batch);
+        }, (error) => {
+            channel.fail(new EventLogConsumeFailed(topic, consumerGroup, error instanceof Error ? error.message : String(error)));
+        }, options);
+        return channel;
     }
     /**
-     * Commit a cursor position for a consumer group.
+     * Commit a cursor to mark progress for a consumer group.
+     *
+     * This is for administrative use cases where you can't commit in-band, preferably when you're
+     * not actively consuming events. For example, you might want to skip ahead after a downtime or reset to the beginning for reprocessing.
+     * Do prefer to commit in-band, i.e. after processing each batch, by calling `batch.commit()`.
+     *
+     * After processing events, commit the cursor to resume from that position
+     * on the next run. Cursors are obtained from `batch.cursor` in the consume
+     * stream or from `getCommittedCursor()`.
      *
      * @example
      * ```ts
-     * await log.commit("users", "processor-1", cursor).run();
+     * await log.commit("users", "processor-1", batch.cursor).run();
      * ```
      */
     commit(topic, consumerGroup, cursor) {
@@ -227,13 +203,17 @@ export class EventLog {
         });
     }
     /**
-     * Get the committed cursor position for a consumer group.
+     * Get the last committed cursor for a consumer group.
+     *
+     * Returns null if no cursor has been committed yet. Use this to resume
+     * consumption from the last processed position.
      *
      * @example
      * ```ts
      * const cursor = await log.getCommittedCursor("users", "processor-1").run();
      * if (cursor) {
-     *   console.log(`Resuming from cursor: ${cursor}`);
+     *   // Resume from saved position
+     *   const stream = log.consume("users", "processor-1", { cursor });
      * }
      * ```
      */

package/esm/in-memory.d.ts

@@ -1,9 +1,13 @@
-import type { EventLogAdapter, EventLogConnector, EventLogOptions } from "./adapter.js";
+import type { EventLogAdapter, EventLogConnector, EventLogOptions } from './adapter.js';
+export declare function createInMemory(options?: InMemoryOptions): InMemoryConnector;
+/** Configuration options for in-memory event log. */
+export interface InMemoryOptions extends EventLogOptions {
+}
 /**
- * Creates an in-memory event log connector using a simple event store.
+ * Creates an in-memory event log connector for testing and development.
  *
- * Events are stored in memory only and will be lost on process restart.
- * Useful for testing and development.
+ * Events are stored in memory and lost when the process exits. Ideal for
+ * unit tests, prototyping, and development environments.
  *
  * @example Basic usage
  * ```ts
@@ -12,42 +16,19 @@ import type { EventLogAdapter, EventLogConnector, EventLogOptions } from "./adap
  * const connector = createInMemory();
  * const log = await EventLog.connect(connector).run();
  *
- * // Append an event
- * const eventId = await log.append("users", { action: "created", userId: 123 }).run();
+ * await log.append("users", { userId: 123 }).run();
  *
- * // List events
- * const events = await log.list("users").run();
+ * // After testing, clean up
+ * await connector.end();
  * ```
  *
- * @example With partition key
+ * @example With custom partition key
  * ```ts
- * await log.append("orders", { orderId: 456, total: 99.99 }, {
- *   partitionKey: "user-123"
- * }).run();
- * ```
- *
- * @example Consuming events
- * ```ts
- * const connector = createInMemory();
- * const log = await EventLog.connect(connector).run();
- *
- * // Append some events first
- * await log.append("notifications", { type: "email" }).run();
- * await log.append("notifications", { type: "sms" }).run();
- *
- * // Consume events
- * for await (const batch of log.consume("notifications", "my-consumer-group")) {
- *   for (const event of batch.events) {
- *     console.log(event.data);
- *   }
- * }
+ * const connector = createInMemory({
+ *   defaultPartitionKey: "user-events",
+ * });
  * ```
  */
-export declare function createInMemory(options?: InMemoryOptions): InMemoryConnector;
-/** In-memory event log connector options. */
-export interface InMemoryOptions extends EventLogOptions {
-}
-/** In-memory event log connector. */
 export interface InMemoryConnector extends EventLogConnector {
     connect(): Promise<EventLogAdapter>;
     end(): Promise<void>;

package/esm/in-memory.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"in-memory.d.ts","sourceRoot":"","sources":["../src/in-memory.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAKV,eAAe,EACf,iBAAiB,EACjB,eAAe,EAEhB,MAAM,cAAc,CAAC;AAsBtB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,wBAAgB,cAAc,CAAC,OAAO,CAAC,EAAE,eAAe,GAAG,iBAAiB,CA0O3E;AAED,6CAA6C;AAC7C,MAAM,WAAW,eAAgB,SAAQ,eAAe;CAAG;AAE3D,qCAAqC;AACrC,MAAM,WAAW,iBAAkB,SAAQ,iBAAiB;IAC1D,OAAO,IAAI,OAAO,CAAC,eAAe,CAAC,CAAC;IACpC,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACtB"}
+{"version":3,"file":"in-memory.d.ts","sourceRoot":"","sources":["../src/in-memory.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAKV,eAAe,EACf,iBAAiB,EACjB,eAAe,EAChB,MAAM,cAAc,CAAA;AAsBrB,wBAAgB,cAAc,CAAC,OAAO,CAAC,EAAE,eAAe,GAAG,iBAAiB,CA4Q3E;AAED,qDAAqD;AACrD,MAAM,WAAW,eAAgB,SAAQ,eAAe;CAAG;AAE3D;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,WAAW,iBAAkB,SAAQ,iBAAiB;IAC1D,OAAO,IAAI,OAAO,CAAC,eAAe,CAAC,CAAA;IACnC,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CACrB"}