@wataruoguchi/emmett-event-store-kysely 1.0.0

package/README.md

@@ -0,0 +1,127 @@
+# @wataruoguchi/emmett-event-store-kysely
+
+A Kysely-based event store implementation for [Emmett](https://github.com/event-driven-io/emmett), providing event sourcing capabilities with PostgreSQL.
+
+## 📚 Documentation
+
+**👉 [View Complete Documentation →](https://wataruoguchi.github.io/emmett-libs/emmett-event-store-kysely)**
+
+## Features
+
+- **Event Store** - Full event sourcing with Kysely and PostgreSQL
+- **Snapshot Projections** - Recommended approach for read models
+- **Event Consumer** - Continuous background event processing
+- **Type Safety** - Full TypeScript support with discriminated unions
+- **Multi-Tenancy** - Built-in partition support
+
+## Installation
+
+```bash
+npm install @wataruoguchi/emmett-event-store-kysely @event-driven-io/emmett kysely pg
+```
+
+## Quick Start
+
+### 1. Database Setup
+
+Set up the required PostgreSQL tables using [our migration example](https://github.com/wataruoguchi/emmett-libs/blob/main/packages/emmett-event-store-kysely/database/migrations/1758758113676_event_sourcing_migration_example.ts):
+
+```typescript
+import { Kysely } from "kysely";
+
+// Required tables: messages, streams, subscriptions
+```
+
+A read model table expects to have the following columns:
+
+- stream_id (uuid)
+- last_stream_position (bigint)
+- last_global_position (bigint)
+- partition (text)
+- snapshot (jsonb)
+
+### 2. Create Event Store
+
+```typescript
+import { getKyselyEventStore } from "@wataruoguchi/emmett-event-store-kysely";
+import { Kysely, PostgresDialect } from "kysely";
+
+const db = new Kysely({
+  dialect: new PostgresDialect({
+    pool: new Pool({ connectionString: process.env.DATABASE_URL }),
+  }),
+});
+
+const eventStore = getKyselyEventStore({ 
+  db, 
+  logger: console,
+});
+```
+
+### 3. Write Events & Commands & Business Logic & State
+
+Please read <https://event-driven-io.github.io/emmett/getting-started.html>
+
+- [Events](https://event-driven-io.github.io/emmett/getting-started.html#events)
+- [Commands](https://event-driven-io.github.io/emmett/getting-started.html#commands)
+- [Business logic and decisions](https://event-driven-io.github.io/emmett/getting-started.html#business-logic-and-decisions)
+- [Building state from events](https://event-driven-io.github.io/emmett/getting-started.html#building-state-from-events)
+
+### 4. Build Read Models
+
+This package supports "Snapshot Projections".
+
+```typescript
+import { 
+  createSnapshotProjectionRegistry 
+} from "@wataruoguchi/emmett-event-store-kysely/projections";
+
+// Reuse your write model's evolve function!
+const registry = createSnapshotProjectionRegistry(
+  ["CartCreated", "ItemAdded", "CartCheckedOut"],
+  {
+    tableName: "carts",
+    primaryKeys: ["tenant_id", "cart_id", "partition"],
+    extractKeys: (event, partition) => ({
+      tenant_id: event.data.eventMeta.tenantId,
+      cart_id: event.data.eventMeta.cartId,
+      partition,
+    }),
+    evolve: domainEvolve,      // Reuse from write model!
+    initialState,
+    mapToColumns: (state) => ({ // Optional: denormalize for queries
+      currency: state.currency,
+      total: state.status === "checkedOut" ? state.total : null,
+    }),
+  }
+);
+```
+
+### 5. Process Events and Update Read Model
+
+```typescript
+import { createProjectionRunner } from "@wataruoguchi/emmett-event-store-kysely/projections";
+
+const runner = createProjectionRunner({ 
+  db, 
+  readStream: eventStore.readStream, 
+  registry,
+});
+
+await runner.projectEvents("subscription-id", "cart-123", {
+  partition: "tenant-456"
+});
+```
+
+## Examples
+
+- [Working Example](https://github.com/wataruoguchi/emmett-libs/tree/main/example/) - Complete application with carts and generators
+- [Migration Example](https://github.com/wataruoguchi/emmett-libs/blob/main/packages/emmett-event-store-kysely/database/migrations/1758758113676_event_sourcing_migration_example.ts) - Database setup
+
+## License
+
+MIT
+
+## Contributing
+
+Contributions are welcome! Please see our [GitHub repository](https://github.com/wataruoguchi/emmett-libs) for issues and PRs.

package/dist/db-schema.d.ts

@@ -0,0 +1,34 @@
+export interface MessagesTable {
+    created: Date;
+    global_position: bigint | null;
+    is_archived: boolean;
+    message_data: unknown;
+    message_id: string;
+    message_kind: string;
+    message_metadata: unknown;
+    message_schema_version: string;
+    message_type: string;
+    partition: string;
+    stream_id: string;
+    stream_position: bigint;
+}
+export interface StreamsTable {
+    is_archived: boolean;
+    partition: string;
+    stream_id: string;
+    stream_metadata: unknown;
+    stream_position: bigint;
+    stream_type: string;
+}
+export interface SubscriptionsTable {
+    last_processed_position: bigint;
+    partition: string;
+    subscription_id: string;
+    version: number;
+}
+export interface EventStoreDBSchema {
+    messages: MessagesTable;
+    streams: StreamsTable;
+    subscriptions: SubscriptionsTable;
+}
+//# sourceMappingURL=db-schema.d.ts.map

package/dist/db-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"db-schema.d.ts","sourceRoot":"","sources":["../src/db-schema.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,IAAI,CAAC;IACd,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,WAAW,EAAE,OAAO,CAAC;IACrB,YAAY,EAAE,OAAO,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,sBAAsB,EAAE,MAAM,CAAC;IAC/B,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,YAAY;IAC3B,WAAW,EAAE,OAAO,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,EAAE,OAAO,CAAC;IACzB,eAAe,EAAE,MAAM,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,kBAAkB;IACjC,uBAAuB,EAAE,MAAM,CAAC;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,EAAE,MAAM,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,aAAa,CAAC;IACxB,OAAO,EAAE,YAAY,CAAC;IACtB,aAAa,EAAE,kBAAkB,CAAC;CACnC"}

package/dist/db-schema.js

@@ -0,0 +1,3 @@
+// Use the example project's database schema which includes the event store tables
+// This makes the package compatible with any database that includes these tables
+export {};

package/dist/event-store/consumers.d.ts

@@ -0,0 +1,23 @@
+import type { Event, ReadEvent, ReadEventMetadataWithGlobalPosition } from "@event-driven-io/emmett";
+import type { Dependencies } from "../types.js";
+export type KyselyEventStoreConsumerConfig = {
+    /** Consumer name for tracking subscription state */
+    consumerName?: string;
+    /** Batch size for processing events */
+    batchSize?: number;
+    /** Polling interval in milliseconds */
+    pollingInterval?: number;
+};
+export type KyselyEventStoreConsumer = {
+    /** Start consuming events */
+    start(): Promise<void>;
+    /** Stop consuming events */
+    stop(): Promise<void>;
+    /** Subscribe to specific event types */
+    subscribe<EventType extends Event>(handler: (event: ReadEvent<EventType, ReadEventMetadataWithGlobalPosition>) => Promise<void> | void, eventType: string): void;
+    /** Subscribe to all events */
+    subscribeToAll(handler: (event: ReadEvent<Event, ReadEventMetadataWithGlobalPosition>) => Promise<void> | void): void;
+};
+export declare function createKyselyEventStoreConsumer({ db, logger, consumerName, batchSize, pollingInterval, }: Dependencies & KyselyEventStoreConsumerConfig): KyselyEventStoreConsumer;
+export declare function createKyselyEventStoreConsumerWithDefaults(deps: Dependencies, config?: KyselyEventStoreConsumerConfig): KyselyEventStoreConsumer;
+//# sourceMappingURL=consumers.d.ts.map

package/dist/event-store/consumers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"consumers.d.ts","sourceRoot":"","sources":["../../src/event-store/consumers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,KAAK,EACL,SAAS,EACT,mCAAmC,EACpC,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD,MAAM,MAAM,8BAA8B,GAAG;IAC3C,oDAAoD;IACpD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,uCAAuC;IACvC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,uCAAuC;IACvC,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B,CAAC;AAEF,MAAM,MAAM,wBAAwB,GAAG;IACrC,6BAA6B;IAC7B,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,4BAA4B;IAC5B,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACtB,wCAAwC;IACxC,SAAS,CAAC,SAAS,SAAS,KAAK,EAC/B,OAAO,EAAE,CACP,KAAK,EAAE,SAAS,CAAC,SAAS,EAAE,mCAAmC,CAAC,KAC7D,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,EACzB,SAAS,EAAE,MAAM,GAChB,IAAI,CAAC;IACR,8BAA8B;IAC9B,cAAc,CACZ,OAAO,EAAE,CACP,KAAK,EAAE,SAAS,CAAC,KAAK,EAAE,mCAAmC,CAAC,KACzD,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,GACxB,IAAI,CAAC;CACT,CAAC;AAEF,wBAAgB,8BAA8B,CAAC,EAC7C,EAAE,EACF,MAAM,EACN,YAAiC,EACjC,SAAe,EACf,eAAsB,GACvB,EAAE,YAAY,GAAG,8BAA8B,GAAG,wBAAwB,CAkM1E;AAGD,wBAAgB,0CAA0C,CACxD,IAAI,EAAE,YAAY,EAClB,MAAM,GAAE,8BAAmC,GAC1C,wBAAwB,CAK1B"}

package/dist/event-store/consumers.js

@@ -0,0 +1,155 @@
+export function createKyselyEventStoreConsumer({ db, logger, consumerName = "default-consumer", batchSize = 100, pollingInterval = 1000, }) {
+    let isRunning = false;
+    let lastProcessedPosition = 0n;
+    const eventHandlers = new Map();
+    const allEventHandlers = [];
+    let pollingTimer = null;
+    const processEvents = async () => {
+        if (!isRunning)
+            return;
+        try {
+            // Get events from the last processed position
+            const events = await db
+                .selectFrom("messages")
+                .select([
+                "message_type",
+                "message_data",
+                "message_metadata",
+                "stream_position",
+                "global_position",
+                "message_id",
+                "stream_id",
+            ])
+                .where("global_position", ">", lastProcessedPosition)
+                .where("is_archived", "=", false)
+                .orderBy("global_position")
+                .limit(batchSize)
+                .execute();
+            if (events.length === 0) {
+                return;
+            }
+            // Process each event
+            for (const row of events) {
+                const event = {
+                    kind: "Event",
+                    type: row.message_type,
+                    data: row.message_data,
+                    metadata: {
+                        ...row.message_metadata,
+                        messageId: row.message_id,
+                        streamName: row.stream_id,
+                        streamPosition: BigInt(String(row.stream_position)),
+                        globalPosition: BigInt(String(row.global_position)),
+                    },
+                };
+                // Call type-specific handlers
+                const typeHandlers = eventHandlers.get(row.message_type) || [];
+                for (const handler of typeHandlers) {
+                    try {
+                        await handler(event);
+                    }
+                    catch (error) {
+                        logger.error({ error, event }, `Error processing event ${row.message_type}`);
+                    }
+                }
+                // Call all-event handlers
+                for (const handler of allEventHandlers) {
+                    try {
+                        await handler(event);
+                    }
+                    catch (error) {
+                        logger.error({ error, event }, "Error processing event in all-event handler");
+                    }
+                }
+                // Update last processed position
+                const globalPos = row.global_position;
+                if (globalPos !== null) {
+                    lastProcessedPosition = BigInt(String(globalPos));
+                }
+            }
+            // Update subscription tracking
+            await updateSubscriptionPosition();
+        }
+        catch (error) {
+            logger.error({ error }, "Error processing events");
+        }
+    };
+    const updateSubscriptionPosition = async () => {
+        try {
+            await db
+                .insertInto("subscriptions")
+                .values({
+                consumer_name: consumerName,
+                last_processed_position: lastProcessedPosition,
+                last_processed_transaction_id: lastProcessedPosition,
+                created_at: new Date(),
+                updated_at: new Date(),
+            })
+                .onConflict((oc) => oc.column("consumer_name").doUpdateSet({
+                last_processed_position: lastProcessedPosition,
+                last_processed_transaction_id: lastProcessedPosition,
+                updated_at: new Date(),
+            }))
+                .execute();
+        }
+        catch (error) {
+            logger.error({ error }, "Error updating subscription position");
+        }
+    };
+    const loadLastProcessedPosition = async () => {
+        try {
+            const subscription = await db
+                .selectFrom("subscriptions")
+                .select(["last_processed_position"])
+                .where("consumer_name", "=", consumerName)
+                .executeTakeFirst();
+            if (subscription) {
+                lastProcessedPosition = BigInt(String(subscription.last_processed_position));
+            }
+        }
+        catch (error) {
+            logger.error({ error }, "Error loading last processed position");
+        }
+    };
+    return {
+        async start() {
+            if (isRunning)
+                return;
+            isRunning = true;
+            await loadLastProcessedPosition();
+            logger.info({ consumerName }, "Starting event store consumer");
+            pollingTimer = setInterval(processEvents, pollingInterval);
+        },
+        async stop() {
+            if (!isRunning)
+                return;
+            isRunning = false;
+            if (pollingTimer) {
+                clearInterval(pollingTimer);
+                pollingTimer = null;
+            }
+            logger.info({ consumerName }, "Stopped event store consumer");
+        },
+        subscribe(handler, eventType) {
+            if (!eventHandlers.has(eventType)) {
+                eventHandlers.set(eventType, []);
+            }
+            const handlers = eventHandlers.get(eventType);
+            if (handlers) {
+                // Type assertion needed because we're storing handlers for specific event types
+                // in a generic Map that accepts Event handlers
+                handlers.push(handler);
+            }
+        },
+        subscribeToAll(handler) {
+            allEventHandlers.push(handler);
+        },
+    };
+}
+// Helper function to create consumer with default options
+export function createKyselyEventStoreConsumerWithDefaults(deps, config = {}) {
+    return createKyselyEventStoreConsumer({
+        ...deps,
+        ...config,
+    });
+}

package/dist/event-store/kysely-event-store.d.ts

@@ -0,0 +1,42 @@
+import { type AppendToStreamOptions, type AppendToStreamResultWithGlobalPosition, type Event, type EventStore, type EventStoreSessionFactory, type ReadEventMetadataWithGlobalPosition, type ReadStreamOptions, type ReadStreamResult } from "@event-driven-io/emmett";
+import type { Kysely } from "kysely";
+import { type Dependencies, type ExtendedOptions } from "../types.js";
+type KyselyReadEventMetadata = ReadEventMetadataWithGlobalPosition;
+type ExtendedAppendToStreamOptions = AppendToStreamOptions & ExtendedOptions;
+export type ProjectionReadStreamOptions = {
+    from?: bigint;
+    to?: bigint;
+    partition?: string;
+    maxCount?: bigint;
+};
+export interface KyselyEventStore extends EventStore<KyselyReadEventMetadata>, EventStoreSessionFactory<KyselyEventStore> {
+    readStream<EventType extends Event>(streamName: string, options?: ReadStreamOptions<bigint> | ProjectionReadStreamOptions): Promise<ReadStreamResult<EventType, KyselyReadEventMetadata>>;
+    appendToStream<EventType extends Event>(streamName: string, events: EventType[], options?: ExtendedAppendToStreamOptions): Promise<AppendToStreamResultWithGlobalPosition>;
+    close(): Promise<void>;
+    schema: {
+        sql(): string;
+        print(): void;
+        migrate(): Promise<void>;
+    };
+}
+export type KyselyEventStoreOptions = {
+    /** Database connection options */
+    connectionOptions?: {
+        /** Custom database executor (Kysely instance) */
+        db?: Kysely<unknown>;
+    };
+    /** Schema management options */
+    schema?: {
+        /** Auto-migration strategy */
+        autoMigration?: "CreateOrUpdate" | "None";
+    };
+    /** Hooks for lifecycle events */
+    hooks?: {
+        /** Called after schema is created */
+        onAfterSchemaCreated?: () => Promise<void> | void;
+    };
+};
+export declare const defaultKyselyOptions: KyselyEventStoreOptions;
+export declare const getKyselyEventStore: (deps: Dependencies) => KyselyEventStore;
+export {};
+//# sourceMappingURL=kysely-event-store.d.ts.map

package/dist/event-store/kysely-event-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kysely-event-store.d.ts","sourceRoot":"","sources":["../../src/event-store/kysely-event-store.ts"],"names":[],"mappings":"AACA,OAAO,EAIL,KAAK,qBAAqB,EAC1B,KAAK,sCAAsC,EAC3C,KAAK,KAAK,EACV,KAAK,UAAU,EAEf,KAAK,wBAAwB,EAE7B,KAAK,mCAAmC,EACxC,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EACtB,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AACrC,OAAO,EAGL,KAAK,YAAY,EACjB,KAAK,eAAe,EACrB,MAAM,aAAa,CAAC;AAErB,KAAK,uBAAuB,GAAG,mCAAmC,CAAC;AACnE,KAAK,6BAA6B,GAAG,qBAAqB,GAAG,eAAe,CAAC;AAI7E,MAAM,MAAM,2BAA2B,GAAG;IACxC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,MAAM,WAAW,gBACf,SAAQ,UAAU,CAAC,uBAAuB,CAAC,EACzC,wBAAwB,CAAC,gBAAgB,CAAC;IAE5C,UAAU,CAAC,SAAS,SAAS,KAAK,EAChC,UAAU,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE,iBAAiB,CAAC,MAAM,CAAC,GAAG,2BAA2B,GAChE,OAAO,CAAC,gBAAgB,CAAC,SAAS,EAAE,uBAAuB,CAAC,CAAC,CAAC;IACjE,cAAc,CAAC,SAAS,SAAS,KAAK,EACpC,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,SAAS,EAAE,EACnB,OAAO,CAAC,EAAE,6BAA6B,GACtC,OAAO,CAAC,sCAAsC,CAAC,CAAC;IACnD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,MAAM,EAAE;QACN,GAAG,IAAI,MAAM,CAAC;QACd,KAAK,IAAI,IAAI,CAAC;QACd,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;KAC1B,CAAC;CACH;AAED,MAAM,MAAM,uBAAuB,GAAG;IACpC,kCAAkC;IAClC,iBAAiB,CAAC,EAAE;QAClB,iDAAiD;QACjD,EAAE,CAAC,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC;KACtB,CAAC;IACF,gCAAgC;IAChC,MAAM,CAAC,EAAE;QACP,8BAA8B;QAC9B,aAAa,CAAC,EAAE,gBAAgB,GAAG,MAAM,CAAC;KAC3C,CAAC;IACF,iCAAiC;IACjC,KAAK,CAAC,EAAE;QACN,qCAAqC;QACrC,oBAAoB,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;KACnD,CAAC;CACH,CAAC;AAEF,eAAO,MAAM,oBAAoB,EAAE,uBAIlC,CAAC;AAEF,eAAO,MAAM,mBAAmB,GAAI,MAAM,YAAY,KAAG,gBAgLxD,CAAC"}

package/dist/event-store/kysely-event-store.js

@@ -0,0 +1,265 @@
+// biome-ignore assist/source/organizeImports: retain import order similar to app code
+import { assertExpectedVersionMatchesCurrent, } from "@event-driven-io/emmett";
+import { DEFAULT_PARTITION, PostgreSQLEventStoreDefaultStreamVersion, } from "../types.js";
+export const defaultKyselyOptions = {
+    schema: {
+        autoMigration: "CreateOrUpdate",
+    },
+};
+export const getKyselyEventStore = (deps) => {
+    const { db, logger, inTransaction = false } = deps;
+    const eventStore = {
+        /**
+         * @description We do not use schema management in this package.
+         */
+        schema: {
+            sql: () => "",
+            print: () => console.log(""),
+            migrate: async () => Promise.resolve(),
+        },
+        /**
+         * Provide a session-bound event store using a Kysely transaction.
+         * All operations within the callback will share the same DB transaction.
+         */
+        async withSession(callback) {
+            return await db.transaction().execute(async (trx) => {
+                const sessionEventStore = getKyselyEventStore({
+                    db: trx,
+                    logger,
+                    inTransaction: true,
+                });
+                return await callback({
+                    eventStore: sessionEventStore,
+                    close: () => Promise.resolve(),
+                });
+            });
+        },
+        async aggregateStream(streamName, options) {
+            const { evolve, initialState, read } = options;
+            logger.debug?.({ streamName, options }, "aggregateStream");
+            const expectedStreamVersion = read?.expectedStreamVersion;
+            const result = await eventStore.readStream(streamName, read);
+            assertExpectedVersionMatchesCurrent(result.currentStreamVersion, expectedStreamVersion, PostgreSQLEventStoreDefaultStreamVersion);
+            const state = result.events.reduce((state, event) => (event ? evolve(state, event) : state), initialState());
+            return {
+                state,
+                currentStreamVersion: result.currentStreamVersion,
+                streamExists: result.streamExists,
+            };
+        },
+        async readStream(streamName, options) {
+            const partition = getPartition(options);
+            logger.debug?.({ streamName, options, partition }, "readStream");
+            const { currentStreamVersion, streamExists } = await fetchStreamInfo(db, streamName, partition);
+            const range = parseRangeOptions(options);
+            const rows = await buildEventsQuery({ db, logger }, streamName, partition, range).execute();
+            const events = rows.map((row) => mapRowToEvent(row, streamName));
+            return {
+                events,
+                currentStreamVersion,
+                streamExists,
+            };
+        },
+        async appendToStream(streamName, events, options) {
+            const streamType = getStreamType(options);
+            const partition = getPartition(options);
+            const expected = options?.expectedStreamVersion;
+            logger.debug?.({ streamName, events, options, partition }, "appendToStream");
+            ensureEventsNotEmpty(events, expected);
+            // It may be called within a transaction via withSession.
+            const executeOn = async (executor) => {
+                const { currentStreamVersion, streamExists } = await fetchStreamInfo(executor, streamName, partition);
+                assertExpectedVersion(expected, currentStreamVersion, streamExists);
+                const basePos = currentStreamVersion;
+                const nextStreamPosition = computeNextStreamPosition(basePos, events.length);
+                await upsertStreamRow(executor, streamName, partition, streamType, basePos, nextStreamPosition, expected, streamExists);
+                const messagesToInsert = buildMessagesToInsert(events, basePos, streamName, partition);
+                const lastEventGlobalPosition = await insertMessagesAndGetLastGlobalPosition(executor, messagesToInsert);
+                return {
+                    nextExpectedStreamVersion: nextStreamPosition,
+                    lastEventGlobalPosition,
+                    createdNewStream: !streamExists,
+                };
+            };
+            if (inTransaction) {
+                return executeOn(db);
+            }
+            return db.transaction().execute(async (trx) => executeOn(trx));
+        },
+        close: async () => {
+            // Kysely doesn't require explicit closing for most cases
+            // but we can add cleanup logic here if needed
+            await Promise.resolve();
+        },
+    };
+    return eventStore;
+};
+// Helper functions (consolidated from the optimized implementation)
+function getStreamType(options) {
+    return options?.streamType ?? "unknown";
+}
+function getPartition(options) {
+    return options?.partition ?? DEFAULT_PARTITION;
+}
+function ensureEventsNotEmpty(events, _expected) {
+    if (events.length === 0) {
+        throw new Error("Cannot append empty events array");
+    }
+}
+function assertExpectedVersion(expected, currentPos, streamExistsNow) {
+    if (expected === "STREAM_EXISTS" && !streamExistsNow) {
+        throw new Error("Stream does not exist but expected to exist");
+    }
+    if (expected === "STREAM_DOES_NOT_EXIST" && streamExistsNow) {
+        throw new Error("Stream exists but expected not to exist");
+    }
+    if (typeof expected === "bigint" && expected !== currentPos) {
+        throw new Error(`Expected version ${expected} but current is ${currentPos}`);
+    }
+}
+function computeNextStreamPosition(basePos, eventCount) {
+    return basePos + BigInt(eventCount);
+}
+async function upsertStreamRow(executor, streamId, partition, streamType, basePos, nextStreamPosition, expected, streamExistsNow) {
+    if (!streamExistsNow) {
+        await executor
+            .insertInto("streams")
+            .values({
+            stream_id: streamId,
+            stream_position: nextStreamPosition,
+            partition,
+            stream_type: streamType,
+            stream_metadata: {},
+            is_archived: false,
+        })
+            .execute();
+        return;
+    }
+    if (typeof expected === "bigint") {
+        const updatedRow = await executor
+            .updateTable("streams")
+            .set({ stream_position: nextStreamPosition })
+            .where("stream_id", "=", streamId)
+            .where("partition", "=", partition)
+            .where("is_archived", "=", false)
+            .where("stream_position", "=", basePos)
+            .returning("stream_position")
+            .executeTakeFirst();
+        if (!updatedRow) {
+            throw new Error(`Expected version ${expected} but current is ${basePos}`);
+        }
+        return;
+    }
+    await executor
+        .updateTable("streams")
+        .set({ stream_position: nextStreamPosition })
+        .where("stream_id", "=", streamId)
+        .where("partition", "=", partition)
+        .where("is_archived", "=", false)
+        .execute();
+}
+function buildMessagesToInsert(events, basePos, streamId, partition) {
+    return events.map((e, index) => {
+        const messageId = crypto.randomUUID();
+        const streamPosition = basePos + BigInt(index + 1);
+        const rawMeta = "metadata" in e ? e.metadata : undefined;
+        const eventMeta = rawMeta && typeof rawMeta === "object" ? rawMeta : {};
+        const messageMetadata = {
+            ...eventMeta,
+        };
+        return {
+            stream_id: streamId,
+            stream_position: streamPosition,
+            partition,
+            message_data: e.data,
+            message_metadata: messageMetadata,
+            message_schema_version: index.toString(),
+            message_type: e.type,
+            message_kind: "E",
+            message_id: messageId,
+            is_archived: false,
+            created: new Date(),
+        };
+    });
+}
+async function insertMessagesAndGetLastGlobalPosition(executor, messagesToInsert) {
+    const inserted = await executor
+        .insertInto("messages")
+        .values(messagesToInsert)
+        .returning("global_position")
+        .execute();
+    if (!inserted || (Array.isArray(inserted) && inserted.length === 0)) {
+        return 0n;
+    }
+    const globalPositions = inserted.map((r) => BigInt(String(r.global_position)));
+    return globalPositions[globalPositions.length - 1];
+}
+function parseRangeOptions(options) {
+    const from = options && typeof options === "object" && "from" in options
+        ? options.from
+        : undefined;
+    const to = options && typeof options === "object" && "to" in options
+        ? options.to
+        : undefined;
+    const maxCount = options && typeof options === "object" && "maxCount" in options
+        ? options.maxCount
+        : undefined;
+    return { from, to, maxCount };
+}
+function buildEventsQuery(deps, streamId, partition, range) {
+    const { db } = deps;
+    let q = db
+        .selectFrom("messages")
+        .select([
+        "message_type",
+        "message_data",
+        "message_metadata",
+        "stream_position",
+        "global_position",
+        "message_id",
+    ])
+        .where("stream_id", "=", streamId)
+        .where("partition", "=", partition)
+        .where("is_archived", "=", false)
+        .orderBy("stream_position");
+    if (range.from !== undefined) {
+        q = q.where("stream_position", ">=", range.from);
+    }
+    if (range.to !== undefined) {
+        q = q.where("stream_position", "<=", range.to);
+    }
+    if (range.maxCount !== undefined) {
+        q = q.limit(Number(range.maxCount));
+    }
+    return q;
+}
+function mapRowToEvent(row, streamId) {
+    const streamPosition = BigInt(String(row.stream_position));
+    const globalPosition = BigInt(String(row.global_position ?? 0));
+    const baseMetadata = (row.message_metadata ?? {});
+    return {
+        kind: "Event",
+        type: row.message_type,
+        data: row.message_data,
+        metadata: {
+            ...baseMetadata,
+            messageId: row.message_id,
+            streamId: streamId,
+            streamPosition: streamPosition,
+            globalPosition: globalPosition,
+        },
+    };
+}
+async function fetchStreamInfo(executor, streamId, partition) {
+    const streamRow = await executor
+        .selectFrom("streams")
+        .select(["stream_position"])
+        .where("stream_id", "=", streamId)
+        .where("partition", "=", partition)
+        .where("is_archived", "=", false)
+        .executeTakeFirst();
+    const currentStreamVersion = streamRow
+        ? BigInt(String(streamRow.stream_position))
+        : PostgreSQLEventStoreDefaultStreamVersion;
+    return { currentStreamVersion, streamExists: !!streamRow };
+}