@anabranch/eventlog 0.1.3 → 0.3.0

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();
+ * const eventId = await log.append("users", { userId: 123 }).run();
  *
- * await log.close().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 {
@@ -55,17 +58,15 @@ export class EventLog {
      * ```
      */
     static connect(connector) {
-        return Task.of(async () => {
-            try {
-                return new EventLog(await connector.connect());
-            }
-            catch (error) {
-                throw new EventLogConnectionFailed(error instanceof Error ? error.message : String(error), error);
-            }
+        return Task.of(async () => new EventLog(await connector.connect()))
+            .mapErr((error) => {
+            return new EventLogConnectionFailed(error instanceof Error ? error.message : String(error), error);
         });
     }
     /**
-     * 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
@@ -73,178 +74,134 @@ export class EventLog {
      * ```
      */
     close() {
-        return Task.of(async () => {
-            try {
-                await this.adapter.close();
-            }
-            catch (error) {
-                throw new EventLogCloseFailed(error instanceof Error ? error.message : String(error), error);
-            }
+        return Task.of(async () => await this.adapter.close()).mapErr((error) => {
+            return new EventLogCloseFailed(error instanceof Error ? error.message : String(error), error);
         });
     }
     /**
      * 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(topic, data, options) {
-        return Task.of(async () => {
-            try {
-                return await this.adapter.append(topic, data, options);
-            }
-            catch (error) {
-                throw new EventLogAppendFailed(topic, error instanceof Error ? error.message : String(error), error);
-            }
-        });
-    }
-    /**
-     * 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);
-            }
+        return Task.of(async () => await this.adapter.append(topic, data, options))
+            .mapErr((error) => {
+            return new EventLogAppendFailed(topic, 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) {
-        return Task.of(async () => {
-            try {
-                await this.adapter.commitCursor(topic, consumerGroup, cursor);
-            }
-            catch (error) {
-                throw new EventLogCommitCursorFailed(topic, consumerGroup, error instanceof Error ? error.message : String(error), error);
-            }
+        return Task.of(async () => await this.adapter.commitCursor(topic, consumerGroup, cursor)).mapErr((error) => {
+            return new EventLogCommitCursorFailed(topic, consumerGroup, error instanceof Error ? error.message : String(error), error);
         });
     }
     /**
-     * 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, consumerGroup) {
-        return Task.of(async () => {
-            try {
-                return await this.adapter.getCursor(topic, consumerGroup);
-            }
-            catch (error) {
-                throw new EventLogGetCursorFailed(topic, consumerGroup, error instanceof Error ? error.message : String(error), error);
-            }
+        return Task.of(async () => await this.adapter.getCursor(topic, consumerGroup)).mapErr((error) => {
+            return new EventLogGetCursorFailed(topic, consumerGroup, error instanceof Error ? error.message : String(error), error);
         });
     }
 }

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"}