@wataruoguchi/emmett-event-store-kysely 2.2.7 → 2.3.1

package/README.md

@@ -32,14 +32,16 @@ import { Kysely } from "kysely";
 // Required tables: messages, streams, subscriptions
 ```
 
-A read model table expects to have the following columns:
+**Legacy approach:** A read model table expects to have the following columns:
 
-- stream_id (uuid)
+- stream_id (text)
 - last_stream_position (bigint)
 - last_global_position (bigint)
 - partition (text)
 - snapshot (jsonb)
 
+**New approach (recommended):** Use `createSnapshotProjectionWithSnapshotTable` to store snapshots in a separate centralized table, keeping read model tables clean with only keys and denormalized columns.
+
 ### 2. Create Event Store
 
 ```typescript
@@ -69,12 +71,69 @@ Please read <https://event-driven-io.github.io/emmett/getting-started.html>
 
 ### 4. Build Read Models
 
-This package supports "Snapshot Projections".
+This package supports "Snapshot Projections" with two approaches:
+
+#### Option A: Separate Snapshot Table (Recommended) ⭐
+
+Use `createSnapshotProjectionWithSnapshotTable` to store snapshots in a centralized table:
+
+```typescript
+import { 
+  createSnapshotProjectionRegistryWithSnapshotTable 
+} from "@wataruoguchi/emmett-event-store-kysely";
+
+// First, create the snapshots table:
+// CREATE TABLE snapshots (
+//   readmodel_table_name TEXT NOT NULL,
+//   stream_id TEXT NOT NULL,
+//   last_stream_position BIGINT NOT NULL,
+//   last_global_position BIGINT NOT NULL,
+//   snapshot JSONB NOT NULL,
+//   PRIMARY KEY (readmodel_table_name, stream_id)
+// );
+
+// Reuse your write model's evolve function!
+const registry = createSnapshotProjectionRegistryWithSnapshotTable(
+  ["CartCreated", "ItemAdded", "CartCheckedOut"],
+  {
+    tableName: "carts",
+    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,
+    }),
+  }
+);
+```
+
+**Benefits:**
+
+- ✅ Cleaner read model tables (no event-sourcing columns)
+- ✅ Easier to create new read models (no schema migrations for event-sourcing columns)
+- ✅ Centralized snapshot management
+- ✅ Race condition protection with `FOR UPDATE` locking
+- ✅ Operations wrapped in transactions for stronger race condition protection
+- ✅ Automatic idempotency (skips already-processed events)
+- ✅ Primary key validation (ensures consistent `extractKeys`)
+
+**Important:** The `extractKeys` function must return the same set of keys for all events. The projection validates this at runtime.
+
+#### Option B: Legacy Approach (Backward Compatible)
+
+Use `createSnapshotProjectionRegistry` to store everything in the read model table:
+
+**Note:** This approach stores event-sourcing columns (`stream_id`, `last_stream_position`, etc.) directly in the read model table. Consider using Option A for new projects.
 
 ```typescript
 import { 
   createSnapshotProjectionRegistry 
-} from "@wataruoguchi/emmett-event-store-kysely/projections";
+} from "@wataruoguchi/emmett-event-store-kysely";
 
 // Reuse your write model's evolve function!
 const registry = createSnapshotProjectionRegistry(
@@ -99,7 +158,7 @@ const registry = createSnapshotProjectionRegistry(
 ### 5. Process Events and Update Read Model
 
 ```typescript
-import { createProjectionRunner } from "@wataruoguchi/emmett-event-store-kysely/projections";
+import { createProjectionRunner } from "@wataruoguchi/emmett-event-store-kysely";
 
 const runner = createProjectionRunner({ 
   db, 

package/dist/index.cjs

@@ -25,6 +25,8 @@ __export(index_exports, {
   createProjectionRunner: () => createProjectionRunner,
   createSnapshotProjection: () => createSnapshotProjection,
   createSnapshotProjectionRegistry: () => createSnapshotProjectionRegistry,
+  createSnapshotProjectionRegistryWithSnapshotTable: () => createSnapshotProjectionRegistryWithSnapshotTable,
+  createSnapshotProjectionWithSnapshotTable: () => createSnapshotProjectionWithSnapshotTable,
   getKyselyEventStore: () => getKyselyEventStore
 });
 module.exports = __toCommonJS(index_exports);
@@ -451,8 +453,8 @@ function createProjectionRunner({
   readStream,
   registry
 }) {
-  async function getOrCreateCheckpoint(subscriptionId, partition) {
-    const existing = await db.selectFrom("subscriptions").select([
+  async function getOrCreateCheckpoint(executor, subscriptionId, partition) {
+    const existing = await executor.selectFrom("subscriptions").select([
       "subscription_id as subscriptionId",
       "partition",
       "last_processed_position as lastProcessedPosition"
@@ -469,7 +471,7 @@ function createProjectionRunner({
         lastProcessedPosition: last
       };
     }
-    await db.insertInto("subscriptions").values({
+    await executor.insertInto("subscriptions").values({
       subscription_id: subscriptionId,
       partition,
       version: 1,
@@ -485,74 +487,145 @@ function createProjectionRunner({
       lastProcessedPosition: 0n
     };
   }
-  async function updateCheckpoint(subscriptionId, partition, lastProcessedPosition) {
-    await db.updateTable("subscriptions").set({ last_processed_position: lastProcessedPosition }).where("subscription_id", "=", subscriptionId).where("partition", "=", partition).execute();
+  async function updateCheckpoint(executor, subscriptionId, partition, lastProcessedPosition) {
+    await executor.updateTable("subscriptions").set({ last_processed_position: lastProcessedPosition }).where("subscription_id", "=", subscriptionId).where("partition", "=", partition).execute();
   }
   async function projectEvents(subscriptionId, streamId, opts) {
     const partition = opts?.partition ?? "default_partition";
     const batchSize = BigInt(opts?.batchSize ?? 500);
-    const checkpoint = await getOrCreateCheckpoint(subscriptionId, partition);
+    const checkpoint = await getOrCreateCheckpoint(
+      db,
+      subscriptionId,
+      partition
+    );
     const { events, currentStreamVersion } = await readStream(streamId, {
       from: checkpoint.lastProcessedPosition + 1n,
       to: checkpoint.lastProcessedPosition + batchSize,
       partition
     });
+    let processed = 0;
     for (const ev of events) {
       if (!ev) continue;
-      const handlers = registry[ev.type] ?? [];
-      if (handlers.length === 0) {
+      await db.transaction().execute(async (trx) => {
+        const handlers = registry[ev.type] ?? [];
+        if (handlers.length === 0) {
+          await updateCheckpoint(
+            trx,
+            subscriptionId,
+            partition,
+            ev.metadata.streamPosition
+          );
+          return;
+        }
+        const projectionEvent = {
+          type: ev.type,
+          data: ev.data,
+          metadata: {
+            streamId: ev.metadata.streamId,
+            streamPosition: ev.metadata.streamPosition,
+            globalPosition: ev.metadata.globalPosition
+          }
+        };
+        for (const handler of handlers) {
+          await handler({ db: trx, partition }, projectionEvent);
+        }
         await updateCheckpoint(
+          trx,
           subscriptionId,
           partition,
-          ev.metadata.streamPosition
+          projectionEvent.metadata.streamPosition
         );
-        continue;
-      }
-      const projectionEvent = {
-        type: ev.type,
-        data: ev.data,
-        metadata: {
-          streamId: ev.metadata.streamId,
-          streamPosition: ev.metadata.streamPosition,
-          globalPosition: ev.metadata.globalPosition
-        }
-      };
-      for (const handler of handlers) {
-        await handler({ db, partition }, projectionEvent);
-      }
-      await updateCheckpoint(
-        subscriptionId,
-        partition,
-        projectionEvent.metadata.streamPosition
-      );
+      });
+      processed++;
     }
-    return { processed: events.length, currentStreamVersion };
+    return { processed, currentStreamVersion };
   }
   return { projectEvents };
 }
 
 // src/projections/snapshot-projection.ts
+function constructStreamId(keys) {
+  const sortedEntries = Object.entries(keys).sort(([a], [b]) => {
+    if (a < b) return -1;
+    if (a > b) return 1;
+    return 0;
+  });
+  return sortedEntries.map(([key, value]) => {
+    const encodedKey = encodeURIComponent(key);
+    const encodedValue = encodeURIComponent(value);
+    return `${encodedKey}:${encodedValue}`;
+  }).join("|");
+}
+function validateAndCachePrimaryKeys(keys, tableName, cachedKeys) {
+  const currentKeys = Object.keys(keys);
+  const sortedCurrentKeys = [...currentKeys].sort();
+  if (!cachedKeys) {
+    return sortedCurrentKeys;
+  }
+  if (cachedKeys.length !== sortedCurrentKeys.length || !cachedKeys.every((key, index) => key === sortedCurrentKeys[index])) {
+    throw new Error(
+      `Snapshot projection "${tableName}" received inconsistent primary keys from extractKeys. Expected keys: ${cachedKeys.join(", ")}, but received: ${sortedCurrentKeys.join(", ")}. Ensure extractKeys returns a consistent set of keys for all events.`
+    );
+  }
+  return cachedKeys;
+}
+function shouldSkipEvent(eventPosition, lastProcessedPosition) {
+  return eventPosition <= lastProcessedPosition;
+}
+function loadStateFromSnapshot(snapshot, initialState, tableName) {
+  if (!snapshot) {
+    return initialState();
+  }
+  if (typeof snapshot === "string") {
+    try {
+      return JSON.parse(snapshot);
+    } catch (error) {
+      const tableContext = tableName ? ` for table "${tableName}"` : "";
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      throw new Error(
+        `Failed to parse snapshot${tableContext}: ${errorMessage}. Snapshot value: ${snapshot.substring(0, 200)}${snapshot.length > 200 ? "..." : ""}`
+      );
+    }
+  }
+  return snapshot;
+}
+function buildDenormalizedUpdateSet(columns) {
+  const updateSet = {};
+  if (columns) {
+    for (const columnName of Object.keys(columns)) {
+      updateSet[columnName] = (eb) => eb.ref(`excluded.${columnName}`);
+    }
+  }
+  return updateSet;
+}
 function createSnapshotProjection(config) {
   const { tableName, extractKeys, evolve, initialState, mapToColumns } = config;
   let inferredPrimaryKeys;
   return async ({ db, partition }, event) => {
     const keys = extractKeys(event, partition);
-    if (!inferredPrimaryKeys) {
-      inferredPrimaryKeys = Object.keys(keys);
-    }
+    inferredPrimaryKeys = validateAndCachePrimaryKeys(
+      keys,
+      tableName,
+      inferredPrimaryKeys
+    );
     const primaryKeys = inferredPrimaryKeys;
     const existing = await db.selectFrom(tableName).select(["last_stream_position", "snapshot"]).where((eb) => {
       const conditions = Object.entries(keys).map(
         ([key, value]) => eb(key, "=", value)
       );
       return eb.and(conditions);
-    }).executeTakeFirst();
+    }).forUpdate().executeTakeFirst();
     const lastPos = existing?.last_stream_position ? BigInt(String(existing.last_stream_position)) : -1n;
-    if (event.metadata.streamPosition <= lastPos) {
+    if (shouldSkipEvent(event.metadata.streamPosition, lastPos)) {
       return;
     }
-    const currentState = existing?.snapshot ? existing.snapshot : initialState();
+    const currentState = loadStateFromSnapshot(
+      existing?.snapshot,
+      initialState,
+      tableName
+    );
     const newState = evolve(currentState, event);
+    const denormalizedColumns = mapToColumns ? mapToColumns(newState) : void 0;
     const rowData = {
       ...keys,
       snapshot: JSON.stringify(newState),
@@ -560,9 +633,8 @@ function createSnapshotProjection(config) {
       last_stream_position: event.metadata.streamPosition.toString(),
       last_global_position: event.metadata.globalPosition.toString()
     };
-    if (mapToColumns) {
-      const columns = mapToColumns(newState);
-      Object.assign(rowData, columns);
+    if (denormalizedColumns) {
+      Object.assign(rowData, denormalizedColumns);
     }
     const insertQuery = db.insertInto(tableName).values(rowData);
     const updateSet = {
@@ -571,18 +643,69 @@ function createSnapshotProjection(config) {
       last_stream_position: (eb) => eb.ref("excluded.last_stream_position"),
       last_global_position: (eb) => eb.ref("excluded.last_global_position")
     };
-    if (mapToColumns) {
-      const columns = mapToColumns(newState);
-      for (const columnName of Object.keys(columns)) {
-        updateSet[columnName] = (eb) => eb.ref(`excluded.${columnName}`);
-      }
-    }
+    const denormalizedUpdateSet = buildDenormalizedUpdateSet(denormalizedColumns);
+    Object.assign(updateSet, denormalizedUpdateSet);
     await insertQuery.onConflict((oc) => {
       const conflictBuilder = oc.columns(primaryKeys);
       return conflictBuilder.doUpdateSet(updateSet);
     }).execute();
   };
 }
+function createSnapshotProjectionWithSnapshotTable(config) {
+  const { tableName, extractKeys, evolve, initialState, mapToColumns } = config;
+  let inferredPrimaryKeys;
+  return async ({ db, partition }, event) => {
+    const keys = extractKeys(event, partition);
+    inferredPrimaryKeys = validateAndCachePrimaryKeys(
+      keys,
+      tableName,
+      inferredPrimaryKeys
+    );
+    const primaryKeys = inferredPrimaryKeys;
+    const streamId = constructStreamId(keys);
+    const existing = await db.selectFrom("snapshots").select(["last_stream_position", "snapshot"]).where("readmodel_table_name", "=", tableName).where("stream_id", "=", streamId).forUpdate().executeTakeFirst();
+    const lastPos = existing?.last_stream_position ? BigInt(String(existing.last_stream_position)) : -1n;
+    if (shouldSkipEvent(event.metadata.streamPosition, lastPos)) {
+      return;
+    }
+    const currentState = loadStateFromSnapshot(
+      existing?.snapshot,
+      initialState,
+      tableName
+    );
+    const newState = evolve(currentState, event);
+    const denormalizedColumns = mapToColumns ? mapToColumns(newState) : void 0;
+    await db.insertInto("snapshots").values({
+      readmodel_table_name: tableName,
+      stream_id: streamId,
+      snapshot: JSON.stringify(newState),
+      last_stream_position: event.metadata.streamPosition.toString(),
+      last_global_position: event.metadata.globalPosition.toString()
+    }).onConflict((oc) => {
+      return oc.columns(["readmodel_table_name", "stream_id"]).doUpdateSet({
+        snapshot: (eb) => eb.ref("excluded.snapshot"),
+        last_stream_position: (eb) => eb.ref("excluded.last_stream_position"),
+        last_global_position: (eb) => eb.ref("excluded.last_global_position")
+      });
+    }).execute();
+    const readModelData = { ...keys };
+    if (denormalizedColumns) {
+      Object.assign(readModelData, denormalizedColumns);
+    }
+    const readModelInsertQuery = db.insertInto(tableName).values(readModelData);
+    const readModelUpdateSet = buildDenormalizedUpdateSet(denormalizedColumns);
+    if (Object.keys(readModelUpdateSet).length > 0) {
+      await readModelInsertQuery.onConflict((oc) => {
+        const conflictBuilder = oc.columns(primaryKeys);
+        return conflictBuilder.doUpdateSet(readModelUpdateSet);
+      }).execute();
+    } else {
+      await readModelInsertQuery.onConflict((oc) => {
+        return oc.columns(primaryKeys).doNothing();
+      }).execute();
+    }
+  };
+}
 function createSnapshotProjectionRegistry(eventTypes, config) {
   const handler = createSnapshotProjection(config);
   const registry = {};
@@ -591,6 +714,14 @@ function createSnapshotProjectionRegistry(eventTypes, config) {
   }
   return registry;
 }
+function createSnapshotProjectionRegistryWithSnapshotTable(eventTypes, config) {
+  const handler = createSnapshotProjectionWithSnapshotTable(config);
+  const registry = {};
+  for (const eventType of eventTypes) {
+    registry[eventType] = [handler];
+  }
+  return registry;
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   createKyselyEventStoreConsumer,
@@ -598,5 +729,7 @@ function createSnapshotProjectionRegistry(eventTypes, config) {
   createProjectionRunner,
   createSnapshotProjection,
   createSnapshotProjectionRegistry,
+  createSnapshotProjectionRegistryWithSnapshotTable,
+  createSnapshotProjectionWithSnapshotTable,
   getKyselyEventStore
 });

package/dist/index.d.ts

@@ -4,7 +4,7 @@ export { getKyselyEventStore } from "./event-store/kysely-event-store.js";
 export type { KyselyEventStore, KyselyEventStoreOptions, ProjectionReadStreamOptions, } from "./event-store/kysely-event-store.js";
 export { createProjectionRunner } from "./projections/runner.js";
 export type { ProjectEvents } from "./projections/runner.js";
-export { createSnapshotProjection, createSnapshotProjectionRegistry, } from "./projections/snapshot-projection.js";
+export { createSnapshotProjection, createSnapshotProjectionRegistry, createSnapshotProjectionWithSnapshotTable, createSnapshotProjectionRegistryWithSnapshotTable, } from "./projections/snapshot-projection.js";
 export type { SnapshotProjectionConfig } from "./projections/snapshot-projection.js";
 export { createProjectionRegistry } from "./types.js";
 export type { DatabaseExecutor, Dependencies, ExtendedOptions, ProjectionContext, ProjectionEvent, ProjectionEventMetadata, ProjectionHandler, ProjectionRegistry, } from "./types.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,8BAA8B,EAAE,MAAM,4BAA4B,CAAC;AAC5E,YAAY,EACV,wBAAwB,EACxB,8BAA8B,GAC/B,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAAE,mBAAmB,EAAE,MAAM,qCAAqC,CAAC;AAC1E,YAAY,EACV,gBAAgB,EAChB,uBAAuB,EACvB,2BAA2B,GAC5B,MAAM,qCAAqC,CAAC;AAC7C,OAAO,EAAE,sBAAsB,EAAE,MAAM,yBAAyB,CAAC;AACjE,YAAY,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAC7D,OAAO,EACL,wBAAwB,EACxB,gCAAgC,GACjC,MAAM,sCAAsC,CAAC;AAC9C,YAAY,EAAE,wBAAwB,EAAE,MAAM,sCAAsC,CAAC;AACrF,OAAO,EAAE,wBAAwB,EAAE,MAAM,YAAY,CAAC;AACtD,YAAY,EACV,gBAAgB,EAChB,YAAY,EACZ,eAAe,EACf,iBAAiB,EACjB,eAAe,EACf,uBAAuB,EACvB,iBAAiB,EACjB,kBAAkB,GACnB,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,8BAA8B,EAAE,MAAM,4BAA4B,CAAC;AAC5E,YAAY,EACV,wBAAwB,EACxB,8BAA8B,GAC/B,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAAE,mBAAmB,EAAE,MAAM,qCAAqC,CAAC;AAC1E,YAAY,EACV,gBAAgB,EAChB,uBAAuB,EACvB,2BAA2B,GAC5B,MAAM,qCAAqC,CAAC;AAC7C,OAAO,EAAE,sBAAsB,EAAE,MAAM,yBAAyB,CAAC;AACjE,YAAY,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAC7D,OAAO,EACL,wBAAwB,EACxB,gCAAgC,EAChC,yCAAyC,EACzC,iDAAiD,GAClD,MAAM,sCAAsC,CAAC;AAC9C,YAAY,EAAE,wBAAwB,EAAE,MAAM,sCAAsC,CAAC;AACrF,OAAO,EAAE,wBAAwB,EAAE,MAAM,YAAY,CAAC;AACtD,YAAY,EACV,gBAAgB,EAChB,YAAY,EACZ,eAAe,EACf,iBAAiB,EACjB,eAAe,EACf,uBAAuB,EACvB,iBAAiB,EACjB,kBAAkB,GACnB,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -1,5 +1,5 @@
 export { createKyselyEventStoreConsumer } from "./event-store/consumers.js";
 export { getKyselyEventStore } from "./event-store/kysely-event-store.js";
 export { createProjectionRunner } from "./projections/runner.js";
-export { createSnapshotProjection, createSnapshotProjectionRegistry, } from "./projections/snapshot-projection.js";
+export { createSnapshotProjection, createSnapshotProjectionRegistry, createSnapshotProjectionWithSnapshotTable, createSnapshotProjectionRegistryWithSnapshotTable, } from "./projections/snapshot-projection.js";
 export { createProjectionRegistry } from "./types.js";

package/dist/projections/runner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../../src/projections/runner.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAqB,MAAM,QAAQ,CAAC;AAExD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sCAAsC,CAAC;AAC7E,OAAO,KAAK,EAAmB,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEvE,MAAM,MAAM,sBAAsB,GAAG;IACnC,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,qBAAqB,EAAE,MAAM,CAAC;CAC/B,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,oBAAoB,GAAG;IACjC,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC;IACtB,UAAU,EAAE,gBAAgB,CAAC,YAAY,CAAC,CAAC;IAC3C,QAAQ,EAAE,kBAAkB,CAAC;CAC9B,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG,CAC1B,cAAc,EAAE,MAAM,EACtB,QAAQ,EAAE,MAAM,EAChB,IAAI,CAAC,EAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,KAC9C,OAAO,CAAC;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,oBAAoB,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAElE,wBAAgB,sBAAsB,CAAC,EACrC,EAAE,EACF,UAAU,EACV,QAAQ,GACT,EAAE,oBAAoB,GAAG;IAAE,aAAa,EAAE,aAAa,CAAA;CAAE,CA+HzD"}
+{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../../src/projections/runner.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAqB,MAAM,QAAQ,CAAC;AAExD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sCAAsC,CAAC;AAC7E,OAAO,KAAK,EAAmB,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEvE,MAAM,MAAM,sBAAsB,GAAG;IACnC,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,qBAAqB,EAAE,MAAM,CAAC;CAC/B,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,oBAAoB,GAAG;IACjC,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC;IACtB,UAAU,EAAE,gBAAgB,CAAC,YAAY,CAAC,CAAC;IAC3C,QAAQ,EAAE,kBAAkB,CAAC;CAC9B,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG,CAC1B,cAAc,EAAE,MAAM,EACtB,QAAQ,EAAE,MAAM,EAChB,IAAI,CAAC,EAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,KAC9C,OAAO,CAAC;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,oBAAoB,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAElE,wBAAgB,sBAAsB,CAAC,EACrC,EAAE,EACF,UAAU,EACV,QAAQ,GACT,EAAE,oBAAoB,GAAG;IAAE,aAAa,EAAE,aAAa,CAAA;CAAE,CA6JzD"}

package/dist/projections/runner.js

@@ -1,6 +1,6 @@
 export function createProjectionRunner({ db, readStream, registry, }) {
-    async function getOrCreateCheckpoint(subscriptionId, partition) {
-        const existing = await db
+    async function getOrCreateCheckpoint(executor, subscriptionId, partition) {
+        const existing = await executor
             .selectFrom("subscriptions")
             .select([
             "subscription_id as subscriptionId",
@@ -19,7 +19,7 @@ export function createProjectionRunner({ db, readStream, registry, }) {
                 lastProcessedPosition: last,
             };
         }
-        await db
+        await executor
             .insertInto("subscriptions")
             .values({
             subscription_id: subscriptionId,
@@ -37,8 +37,8 @@ export function createProjectionRunner({ db, readStream, registry, }) {
             lastProcessedPosition: 0n,
         };
     }
-    async function updateCheckpoint(subscriptionId, partition, lastProcessedPosition) {
-        await db
+    async function updateCheckpoint(executor, subscriptionId, partition, lastProcessedPosition) {
+        await executor
             .updateTable("subscriptions")
             .set({ last_processed_position: lastProcessedPosition })
             .where("subscription_id", "=", subscriptionId)
@@ -48,35 +48,49 @@ export function createProjectionRunner({ db, readStream, registry, }) {
     async function projectEvents(subscriptionId, streamId, opts) {
         const partition = opts?.partition ?? "default_partition";
         const batchSize = BigInt(opts?.batchSize ?? 500);
-        const checkpoint = await getOrCreateCheckpoint(subscriptionId, partition);
+        // Read checkpoint outside transaction to avoid holding locks during event reading
+        const checkpoint = await getOrCreateCheckpoint(db, subscriptionId, partition);
+        // Read events outside transaction - this is just a read operation
         const { events, currentStreamVersion } = await readStream(streamId, {
             from: checkpoint.lastProcessedPosition + 1n,
             to: checkpoint.lastProcessedPosition + batchSize,
             partition,
         });
+        let processed = 0;
+        // Process each event in its own transaction
+        // This keeps transactions short and reduces lock contention
         for (const ev of events) {
             if (!ev)
                 continue;
-            const handlers = registry[ev.type] ?? [];
-            if (handlers.length === 0) {
-                await updateCheckpoint(subscriptionId, partition, ev.metadata.streamPosition);
-                continue;
-            }
-            const projectionEvent = {
-                type: ev.type,
-                data: ev.data,
-                metadata: {
-                    streamId: ev.metadata.streamId,
-                    streamPosition: ev.metadata.streamPosition,
-                    globalPosition: ev.metadata.globalPosition,
-                },
-            };
-            for (const handler of handlers) {
-                await handler({ db, partition }, projectionEvent);
-            }
-            await updateCheckpoint(subscriptionId, partition, projectionEvent.metadata.streamPosition);
+            // Each event gets its own transaction
+            // This ensures atomicity per event while keeping transactions short
+            await db.transaction().execute(async (trx) => {
+                const handlers = registry[ev.type] ?? [];
+                if (handlers.length === 0) {
+                    // No handlers, just update checkpoint
+                    await updateCheckpoint(trx, subscriptionId, partition, ev.metadata.streamPosition);
+                    return;
+                }
+                const projectionEvent = {
+                    type: ev.type,
+                    data: ev.data,
+                    metadata: {
+                        streamId: ev.metadata.streamId,
+                        streamPosition: ev.metadata.streamPosition,
+                        globalPosition: ev.metadata.globalPosition,
+                    },
+                };
+                // All handlers for this event run in the same transaction
+                // This ensures they see each other's changes and maintain consistency
+                for (const handler of handlers) {
+                    await handler({ db: trx, partition }, projectionEvent);
+                }
+                // Update checkpoint after all handlers succeed
+                await updateCheckpoint(trx, subscriptionId, partition, projectionEvent.metadata.streamPosition);
+            });
+            processed++;
         }
-        return { processed: events.length, currentStreamVersion };
+        return { processed, currentStreamVersion };
     }
     return { projectEvents };
 }

package/dist/projections/snapshot-projection.d.ts

@@ -54,6 +54,26 @@ export type SnapshotProjectionConfig<TState, TTable extends string, E extends {
      */
     mapToColumns?: (state: TState) => Record<string, unknown>;
 };
+/**
+ * Constructs a deterministic stream_id from the keys.
+ * The stream_id is created by sorting the keys and concatenating them with a delimiter.
+ * This ensures the same keys always produce the same stream_id.
+ *
+ * URL encoding is used to handle special characters (like `|` and `:`) in key names or values
+ * that could otherwise cause collisions or parsing issues when used as delimiters.
+ *
+ * @internal
+ * Exported for testing purposes only.
+ */
+export declare function constructStreamId(keys: Record<string, string>): string;
+/**
+ * Loads the current state from a snapshot, handling both string and parsed JSON formats.
+ * Falls back to initial state if no snapshot exists.
+ *
+ * @internal
+ * Exported for testing purposes only.
+ */
+export declare function loadStateFromSnapshot<TState>(snapshot: unknown, initialState: () => TState, tableName?: string): TState;
 /**
  * Creates a projection handler that stores the aggregate state as a snapshot.
  *
@@ -91,6 +111,62 @@ export declare function createSnapshotProjection<TState, TTable extends string,
     type: string;
     data: unknown;
 }>(config: SnapshotProjectionConfig<TState, TTable, E>): ProjectionHandler<DatabaseExecutor, E>;
+/**
+ * Creates a projection handler that stores snapshots in a separate centralized table.
+ *
+ * This is similar to `createSnapshotProjection`, but uses a separate `snapshots` table
+ * to store event-sourcing-related columns. This approach makes read model tables cleaner
+ * and more scalable, as they don't need to include event-sourcing columns.
+ *
+ * **Key differences from `createSnapshotProjection`:**
+ * - Snapshots are stored in a centralized `snapshots` table
+ * - Read model tables only contain keys from `extractKeys` and columns from `mapToColumns`
+ * - The `stream_id` is deterministically constructed from the keys (not from event metadata)
+ *
+ * **Database schema required:**
+ * ```sql
+ * CREATE TABLE snapshots (
+ *   readmodel_table_name TEXT NOT NULL,
+ *   stream_id TEXT NOT NULL,
+ *   last_stream_position BIGINT NOT NULL,
+ *   last_global_position BIGINT NOT NULL,
+ *   snapshot JSONB NOT NULL,
+ *   PRIMARY KEY (readmodel_table_name, stream_id)
+ * );
+ * ```
+ *
+ * @example
+ * ```typescript
+ * const cartProjection = createSnapshotProjectionWithSnapshotTable({
+ *   tableName: 'carts',
+ *   extractKeys: (event, partition) => ({
+ *     tenant_id: event.data.eventMeta.tenantId,
+ *     cart_id: event.data.eventMeta.cartId,
+ *     partition
+ *   }),
+ *   evolve: cartEvolve,
+ *   initialState: () => ({ status: 'init', items: [] }),
+ *   mapToColumns: (state) => ({
+ *     currency: state.currency,
+ *     is_checked_out: state.status === 'checkedOut'
+ *   })
+ * });
+ *
+ * // Use it in a projection registry
+ * const registry: ProjectionRegistry = {
+ *   CartCreated: [cartProjection],
+ *   ItemAddedToCart: [cartProjection],
+ *   // ... other events
+ * };
+ * ```
+ */
+export declare function createSnapshotProjectionWithSnapshotTable<TState, TTable extends string, E extends {
+    type: string;
+    data: unknown;
+} = {
+    type: string;
+    data: unknown;
+}>(config: SnapshotProjectionConfig<TState, TTable, E>): ProjectionHandler<DatabaseExecutor, E>;
 /**
  * Creates multiple projection handlers that all use the same snapshot projection logic.
  * This is a convenience function to avoid repeating the same handler for multiple event types.
@@ -119,4 +195,37 @@ export declare function createSnapshotProjectionRegistry<TState, TTable extends
     type: string;
     data: unknown;
 }>(eventTypes: E["type"][], config: SnapshotProjectionConfig<TState, TTable, E>): ProjectionRegistry;
+/**
+ * Creates multiple projection handlers that all use the same snapshot projection logic
+ * with a separate snapshots table. This is a convenience function to avoid repeating
+ * the same handler for multiple event types.
+ *
+ * @example
+ * ```typescript
+ * const registry = createSnapshotProjectionRegistryWithSnapshotTable(
+ *   ['CartCreated', 'ItemAddedToCart', 'ItemRemovedFromCart'],
+ *   {
+ *     tableName: 'carts',
+ *     extractKeys: (event, partition) => ({
+ *       tenant_id: event.data.eventMeta.tenantId,
+ *       cart_id: event.data.eventMeta.cartId,
+ *       partition
+ *     }),
+ *     evolve: cartEvolve,
+ *     initialState: () => ({ status: 'init', items: [] }),
+ *     mapToColumns: (state) => ({
+ *       currency: state.currency,
+ *       is_checked_out: state.status === 'checkedOut'
+ *     })
+ *   }
+ * );
+ * ```
+ */
+export declare function createSnapshotProjectionRegistryWithSnapshotTable<TState, TTable extends string, E extends {
+    type: string;
+    data: unknown;
+} = {
+    type: string;
+    data: unknown;
+}>(eventTypes: E["type"][], config: SnapshotProjectionConfig<TState, TTable, E>): ProjectionRegistry;
 //# sourceMappingURL=snapshot-projection.d.ts.map

package/dist/projections/snapshot-projection.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"snapshot-projection.d.ts","sourceRoot":"","sources":["../../src/projections/snapshot-projection.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,gBAAgB,EAEhB,eAAe,EACf,iBAAiB,EACjB,kBAAkB,EACnB,MAAM,aAAa,CAAC;AAErB;;;;;;GAMG;AACH,MAAM,MAAM,wBAAwB,CAClC,MAAM,EACN,MAAM,SAAS,MAAM,EACrB,CAAC,SAAS;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,IACzE;IACF;;OAEG;IACH,SAAS,EAAE,MAAM,CAAC;IAElB;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IAEvB;;;OAGG;IACH,WAAW,EAAE,CACX,KAAK,EAAE,eAAe,CAAC,CAAC,CAAC,EACzB,SAAS,EAAE,MAAM,KACd,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAE5B;;;OAGG;IACH,MAAM,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,eAAe,CAAC,CAAC,CAAC,KAAK,MAAM,CAAC;IAE7D;;OAEG;IACH,YAAY,EAAE,MAAM,MAAM,CAAC;IAE3B;;;;;;;;;;;;OAYG;IACH,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC3D,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,wBAAwB,CACtC,MAAM,EACN,MAAM,SAAS,MAAM,EACrB,CAAC,SAAS;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,EAE3E,MAAM,EAAE,wBAAwB,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC,GAClD,iBAAiB,CAAC,gBAAgB,EAAE,CAAC,CAAC,CAqGxC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,gCAAgC,CAC9C,MAAM,EACN,MAAM,SAAS,MAAM,EACrB,CAAC,SAAS;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,EAE3E,UAAU,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,EACvB,MAAM,EAAE,wBAAwB,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC,GAClD,kBAAkB,CAYpB"}
+{"version":3,"file":"snapshot-projection.d.ts","sourceRoot":"","sources":["../../src/projections/snapshot-projection.ts"],"names":[],"mappings":"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"}

package/dist/projections/snapshot-projection.js

@@ -1,3 +1,98 @@
+/**
+ * Constructs a deterministic stream_id from the keys.
+ * The stream_id is created by sorting the keys and concatenating them with a delimiter.
+ * This ensures the same keys always produce the same stream_id.
+ *
+ * URL encoding is used to handle special characters (like `|` and `:`) in key names or values
+ * that could otherwise cause collisions or parsing issues when used as delimiters.
+ *
+ * @internal
+ * Exported for testing purposes only.
+ */
+export function constructStreamId(keys) {
+    const sortedEntries = Object.entries(keys).sort(([a], [b]) => {
+        if (a < b)
+            return -1;
+        if (a > b)
+            return 1;
+        return 0;
+    });
+    return sortedEntries
+        .map(([key, value]) => {
+        const encodedKey = encodeURIComponent(key);
+        const encodedValue = encodeURIComponent(value);
+        return `${encodedKey}:${encodedValue}`;
+    })
+        .join("|");
+}
+/**
+ * Validates and caches primary keys from extractKeys.
+ * Ensures that extractKeys returns a consistent set of keys across all events.
+ */
+function validateAndCachePrimaryKeys(keys, tableName, cachedKeys) {
+    const currentKeys = Object.keys(keys);
+    const sortedCurrentKeys = [...currentKeys].sort();
+    if (!cachedKeys) {
+        // Cache the initially inferred primary keys in a deterministic order
+        return sortedCurrentKeys;
+    }
+    // Validate that subsequent calls to extractKeys return the same key set
+    if (cachedKeys.length !== sortedCurrentKeys.length ||
+        !cachedKeys.every((key, index) => key === sortedCurrentKeys[index])) {
+        throw new Error(`Snapshot projection "${tableName}" received inconsistent primary keys from extractKeys. ` +
+            `Expected keys: ${cachedKeys.join(", ")}, ` +
+            `but received: ${sortedCurrentKeys.join(", ")}. ` +
+            `Ensure extractKeys returns a consistent set of keys for all events.`);
+    }
+    return cachedKeys;
+}
+/**
+ * Checks if the event should be processed based on the last processed position.
+ * Returns true if the event should be skipped (already processed or older).
+ * Callers should pass -1n for lastProcessedPosition when there is no previous position
+ * so that events are processed from the beginning.
+ */
+function shouldSkipEvent(eventPosition, lastProcessedPosition) {
+    return eventPosition <= lastProcessedPosition;
+}
+/**
+ * Loads the current state from a snapshot, handling both string and parsed JSON formats.
+ * Falls back to initial state if no snapshot exists.
+ *
+ * @internal
+ * Exported for testing purposes only.
+ */
+export function loadStateFromSnapshot(snapshot, initialState, tableName) {
+    if (!snapshot) {
+        return initialState();
+    }
+    // Some database drivers return JSONB as strings, others as parsed objects
+    if (typeof snapshot === "string") {
+        try {
+            return JSON.parse(snapshot);
+        }
+        catch (error) {
+            const tableContext = tableName ? ` for table "${tableName}"` : "";
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            throw new Error(`Failed to parse snapshot${tableContext}: ${errorMessage}. ` +
+                `Snapshot value: ${snapshot.substring(0, 200)}${snapshot.length > 200 ? "..." : ""}`);
+        }
+    }
+    return snapshot;
+}
+/**
+ * Builds the update set for denormalized columns.
+ * Returns an empty object if columns is not provided or empty.
+ */
+function buildDenormalizedUpdateSet(columns) {
+    const updateSet = {};
+    if (columns) {
+        for (const columnName of Object.keys(columns)) {
+            updateSet[columnName] = (eb) => eb.ref(`excluded.${columnName}`);
+        }
+    }
+    return updateSet;
+}
 /**
  * Creates a projection handler that stores the aggregate state as a snapshot.
  *
@@ -34,12 +129,11 @@ export function createSnapshotProjection(config) {
     let inferredPrimaryKeys;
     return async ({ db, partition }, event) => {
         const keys = extractKeys(event, partition);
-        // Infer primary keys from extractKeys on first call
-        if (!inferredPrimaryKeys) {
-            inferredPrimaryKeys = Object.keys(keys);
-        }
+        // Validate and cache primary keys
+        inferredPrimaryKeys = validateAndCachePrimaryKeys(keys, tableName, inferredPrimaryKeys);
         const primaryKeys = inferredPrimaryKeys;
         // Check if event is newer than what we've already processed
+        // Use FOR UPDATE to lock the row and prevent race conditions with concurrent transactions
         // Note: Casting to `any` is necessary because Kysely cannot infer types for dynamic table names.
         // The table name is provided at runtime, so TypeScript cannot verify the table structure at compile time.
         // This is a known limitation when working with dynamic table names in Kysely.
@@ -52,21 +146,23 @@ export function createSnapshotProjection(config) {
             const conditions = Object.entries(keys).map(([key, value]) => eb(key, "=", value));
             return eb.and(conditions);
         })
+            .forUpdate()
             .executeTakeFirst();
         const lastPos = existing?.last_stream_position
             ? BigInt(String(existing.last_stream_position))
             : -1n;
         // Skip if we've already processed a newer event
-        if (event.metadata.streamPosition <= lastPos) {
+        if (shouldSkipEvent(event.metadata.streamPosition, lastPos)) {
             return;
         }
         // Load current state from snapshot or use initial state
-        // Note: snapshot is stored as JSONB and Kysely returns it as parsed JSON
-        const currentState = existing?.snapshot
-            ? existing.snapshot
-            : initialState();
+        const currentState = loadStateFromSnapshot(existing?.snapshot, initialState, tableName);
         // Apply the event to get new state
         const newState = evolve(currentState, event);
+        // Call mapToColumns once after evolve (only if provided)
+        const denormalizedColumns = mapToColumns
+            ? mapToColumns(newState)
+            : undefined;
         // Prepare the row data with snapshot
         const rowData = {
             ...keys,
@@ -75,10 +171,9 @@ export function createSnapshotProjection(config) {
             last_stream_position: event.metadata.streamPosition.toString(),
             last_global_position: event.metadata.globalPosition.toString(),
         };
-        // If mapToColumns is provided, add the denormalized columns
-        if (mapToColumns) {
-            const columns = mapToColumns(newState);
-            Object.assign(rowData, columns);
+        // If denormalized columns exist, add them to row data
+        if (denormalizedColumns) {
+            Object.assign(rowData, denormalizedColumns);
         }
         // Upsert the snapshot
         const insertQuery = db.insertInto(tableName).values(rowData);
@@ -88,24 +183,165 @@ export function createSnapshotProjection(config) {
             last_stream_position: (eb) => eb.ref("excluded.last_stream_position"),
             last_global_position: (eb) => eb.ref("excluded.last_global_position"),
         };
-        // If mapToColumns is provided, also update the denormalized columns
-        if (mapToColumns) {
-            const columns = mapToColumns(newState);
-            for (const columnName of Object.keys(columns)) {
-                updateSet[columnName] = (eb) => eb.ref(`excluded.${columnName}`);
-            }
-        }
+        // Add denormalized columns to update set if provided
+        const denormalizedUpdateSet = buildDenormalizedUpdateSet(denormalizedColumns);
+        Object.assign(updateSet, denormalizedUpdateSet);
         await insertQuery
             // Note: `any` is used here because the conflict builder needs to work with any table schema.
             // The actual schema is validated at runtime through Kysely's query builder.
+            // The FOR UPDATE lock above ensures that concurrent transactions wait, preventing race conditions.
             // eslint-disable-next-line @typescript-eslint/no-explicit-any
             .onConflict((oc) => {
             const conflictBuilder = oc.columns(primaryKeys);
+            // Note: We could add a WHERE clause here (via doUpdateSet's `where` option) to only update
+            // if excluded.last_stream_position > table.last_stream_position, but the FOR UPDATE lock above
+            // already provides the primary protection, so we intentionally rely on that for concurrency control.
             return conflictBuilder.doUpdateSet(updateSet);
         })
             .execute();
     };
 }
+/**
+ * Creates a projection handler that stores snapshots in a separate centralized table.
+ *
+ * This is similar to `createSnapshotProjection`, but uses a separate `snapshots` table
+ * to store event-sourcing-related columns. This approach makes read model tables cleaner
+ * and more scalable, as they don't need to include event-sourcing columns.
+ *
+ * **Key differences from `createSnapshotProjection`:**
+ * - Snapshots are stored in a centralized `snapshots` table
+ * - Read model tables only contain keys from `extractKeys` and columns from `mapToColumns`
+ * - The `stream_id` is deterministically constructed from the keys (not from event metadata)
+ *
+ * **Database schema required:**
+ * ```sql
+ * CREATE TABLE snapshots (
+ *   readmodel_table_name TEXT NOT NULL,
+ *   stream_id TEXT NOT NULL,
+ *   last_stream_position BIGINT NOT NULL,
+ *   last_global_position BIGINT NOT NULL,
+ *   snapshot JSONB NOT NULL,
+ *   PRIMARY KEY (readmodel_table_name, stream_id)
+ * );
+ * ```
+ *
+ * @example
+ * ```typescript
+ * const cartProjection = createSnapshotProjectionWithSnapshotTable({
+ *   tableName: 'carts',
+ *   extractKeys: (event, partition) => ({
+ *     tenant_id: event.data.eventMeta.tenantId,
+ *     cart_id: event.data.eventMeta.cartId,
+ *     partition
+ *   }),
+ *   evolve: cartEvolve,
+ *   initialState: () => ({ status: 'init', items: [] }),
+ *   mapToColumns: (state) => ({
+ *     currency: state.currency,
+ *     is_checked_out: state.status === 'checkedOut'
+ *   })
+ * });
+ *
+ * // Use it in a projection registry
+ * const registry: ProjectionRegistry = {
+ *   CartCreated: [cartProjection],
+ *   ItemAddedToCart: [cartProjection],
+ *   // ... other events
+ * };
+ * ```
+ */
+export function createSnapshotProjectionWithSnapshotTable(config) {
+    const { tableName, extractKeys, evolve, initialState, mapToColumns } = config;
+    // Cache the inferred primary keys after the first call
+    let inferredPrimaryKeys;
+    return async ({ db, partition }, event) => {
+        const keys = extractKeys(event, partition);
+        // Validate and cache primary keys
+        inferredPrimaryKeys = validateAndCachePrimaryKeys(keys, tableName, inferredPrimaryKeys);
+        const primaryKeys = inferredPrimaryKeys;
+        // Construct deterministic stream_id from keys
+        const streamId = constructStreamId(keys);
+        // Check if event is newer than what we've already processed
+        // Use FOR UPDATE to lock the row and prevent race conditions with concurrent transactions
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const existing = await db
+            .selectFrom("snapshots")
+            .select(["last_stream_position", "snapshot"])
+            .where("readmodel_table_name", "=", tableName)
+            .where("stream_id", "=", streamId)
+            .forUpdate()
+            .executeTakeFirst();
+        const lastPos = existing?.last_stream_position
+            ? BigInt(String(existing.last_stream_position))
+            : -1n;
+        // Skip if we've already processed a newer event
+        if (shouldSkipEvent(event.metadata.streamPosition, lastPos)) {
+            return;
+        }
+        // Load current state from snapshot or use initial state
+        const currentState = loadStateFromSnapshot(existing?.snapshot, initialState, tableName);
+        // Apply the event to get new state
+        const newState = evolve(currentState, event);
+        // Call mapToColumns once after evolve (only if provided)
+        const denormalizedColumns = mapToColumns
+            ? mapToColumns(newState)
+            : undefined;
+        // Upsert the snapshot in the snapshots table
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        await db
+            .insertInto("snapshots")
+            .values({
+            readmodel_table_name: tableName,
+            stream_id: streamId,
+            snapshot: JSON.stringify(newState),
+            last_stream_position: event.metadata.streamPosition.toString(),
+            last_global_position: event.metadata.globalPosition.toString(),
+        })
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            .onConflict((oc) => {
+            // The FOR UPDATE lock above ensures that concurrent transactions wait, preventing race conditions.
+            // Note: We could add a WHERE clause here to only update if excluded.last_stream_position > snapshots.last_stream_position,
+            // but this would be redundant for correctness: the FOR UPDATE lock, combined with the shouldSkipEvent check,
+            // already prevents stale or out-of-order events from overwriting newer snapshots.
+            return oc.columns(["readmodel_table_name", "stream_id"]).doUpdateSet({
+                snapshot: (eb) => eb.ref("excluded.snapshot"),
+                last_stream_position: (eb) => eb.ref("excluded.last_stream_position"),
+                last_global_position: (eb) => eb.ref("excluded.last_global_position"),
+            });
+        })
+            .execute();
+        // Upsert the read model table with keys and denormalized columns only
+        const readModelData = { ...keys };
+        if (denormalizedColumns) {
+            Object.assign(readModelData, denormalizedColumns);
+        }
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const readModelInsertQuery = db
+            .insertInto(tableName)
+            .values(readModelData);
+        // Build the update set for conflict resolution (only for denormalized columns)
+        const readModelUpdateSet = buildDenormalizedUpdateSet(denormalizedColumns);
+        // Only update if there are denormalized columns, otherwise just insert (no-op on conflict)
+        if (Object.keys(readModelUpdateSet).length > 0) {
+            await readModelInsertQuery
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                .onConflict((oc) => {
+                const conflictBuilder = oc.columns(primaryKeys);
+                return conflictBuilder.doUpdateSet(readModelUpdateSet);
+            })
+                .execute();
+        }
+        else {
+            // If no denormalized columns, use insert with on conflict do nothing
+            await readModelInsertQuery
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                .onConflict((oc) => {
+                return oc.columns(primaryKeys).doNothing();
+            })
+                .execute();
+        }
+    };
+}
 /**
  * Creates multiple projection handlers that all use the same snapshot projection logic.
  * This is a convenience function to avoid repeating the same handler for multiple event types.
@@ -138,3 +374,40 @@ export function createSnapshotProjectionRegistry(eventTypes, config) {
     }
     return registry;
 }
+/**
+ * Creates multiple projection handlers that all use the same snapshot projection logic
+ * with a separate snapshots table. This is a convenience function to avoid repeating
+ * the same handler for multiple event types.
+ *
+ * @example
+ * ```typescript
+ * const registry = createSnapshotProjectionRegistryWithSnapshotTable(
+ *   ['CartCreated', 'ItemAddedToCart', 'ItemRemovedFromCart'],
+ *   {
+ *     tableName: 'carts',
+ *     extractKeys: (event, partition) => ({
+ *       tenant_id: event.data.eventMeta.tenantId,
+ *       cart_id: event.data.eventMeta.cartId,
+ *       partition
+ *     }),
+ *     evolve: cartEvolve,
+ *     initialState: () => ({ status: 'init', items: [] }),
+ *     mapToColumns: (state) => ({
+ *       currency: state.currency,
+ *       is_checked_out: state.status === 'checkedOut'
+ *     })
+ *   }
+ * );
+ * ```
+ */
+export function createSnapshotProjectionRegistryWithSnapshotTable(eventTypes, config) {
+    const handler = createSnapshotProjectionWithSnapshotTable(config);
+    const registry = {};
+    for (const eventType of eventTypes) {
+        // Type cast is safe here because ProjectionHandler is contravariant in its event type parameter.
+        // A handler for a specific event type E can safely handle any event that matches E's structure.
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        registry[eventType] = [handler];
+    }
+    return registry;
+}

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "2.2.7",
+  "version": "2.3.1",
   "description": "Emmett Event Store with Kysely",
   "author": "Wataru Oguchi",
   "license": "MIT",