@requence/event-sourcing 1.4.1 → 1.5.1

package/dist/tests/projectionMultiInstance.spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"projectionMultiInstance.spec.d.ts","sourceRoot":"","sources":["../../src/tests/projectionMultiInstance.spec.ts"],"names":[],"mappings":""}

package/dist/tests/storageDriverContract.d.ts

@@ -0,0 +1,19 @@
+import type { AggregateRootSnapshotMethods } from '../createAggregateRoot.ts';
+import type { CheckpointMethods } from '../createCheckpointApi.ts';
+import type { LoadEvents } from '../createEventStore.ts';
+import type { ProjectionSnapshotMethods } from '../createProjection.ts';
+import type { BaseInputEvent, BaseOutputEvent, MaybePromise, StreamId } from '../utilityTypes.ts';
+export type StorageDriver = {
+    loadEvents: LoadEvents;
+    appendEvents: (streamId: StreamId, events: BaseInputEvent[], expectedVersion: number) => MaybePromise<BaseOutputEvent[]>;
+    checkpoint: CheckpointMethods;
+    projectionSnapshot: ProjectionSnapshotMethods;
+    aggregateRootSnapshot: AggregateRootSnapshotMethods;
+};
+/**
+ * Reusable contract suite exercising the raw storage methods every driver
+ * must supply to the core `createEventStore`. Call it once per driver with a
+ * factory producing a fresh, empty storage instance.
+ */
+export declare function runStorageDriverContract(name: string, makeStorage: () => MaybePromise<StorageDriver>): void;
+//# sourceMappingURL=storageDriverContract.d.ts.map

package/dist/tests/storageDriverContract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storageDriverContract.d.ts","sourceRoot":"","sources":["../../src/tests/storageDriverContract.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAEV,4BAA4B,EAC7B,MAAM,2BAA2B,CAAA;AAClC,OAAO,KAAK,EAAc,iBAAiB,EAAE,MAAM,2BAA2B,CAAA;AAC9E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAA;AACxD,OAAO,KAAK,EAEV,yBAAyB,EAC1B,MAAM,wBAAwB,CAAA;AAE/B,OAAO,KAAK,EACV,cAAc,EACd,eAAe,EACf,YAAY,EACZ,QAAQ,EACT,MAAM,oBAAoB,CAAA;AAE3B,MAAM,MAAM,aAAa,GAAG;IAC1B,UAAU,EAAE,UAAU,CAAA;IACtB,YAAY,EAAE,CACZ,QAAQ,EAAE,QAAQ,EAClB,MAAM,EAAE,cAAc,EAAE,EACxB,eAAe,EAAE,MAAM,KACpB,YAAY,CAAC,eAAe,EAAE,CAAC,CAAA;IACpC,UAAU,EAAE,iBAAiB,CAAA;IAC7B,kBAAkB,EAAE,yBAAyB,CAAA;IAC7C,qBAAqB,EAAE,4BAA4B,CAAA;CACpD,CAAA;AA8CD;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,YAAY,CAAC,aAAa,CAAC,QAghB/C"}

package/dist/transaction.js

@@ -1,6 +1,6 @@
 import {
   createTransaction
-} from "./chunk-pc1q4se9.js";
+} from "./chunk-9qtjz725.js";
 export {
   createTransaction as default
 };

package/dist/utils.js

@@ -1,10 +1,10 @@
 import {
-  awaitAll,
-  normalizeArray
-} from "./chunk-tfy01fah.js";
+  normalizeArray2,
+  awaitAll2
+} from "./chunk-c7sytwpp.js";
 export {
-  normalizeArray,
-  awaitAll
+  awaitAll2 as awaitAll,
+  normalizeArray2 as normalizeArray
 };
 
-//# debugId=B02575DAA75C385064756E2164756E21
+//# debugId=27F4432A2CD67A7364756E2164756E21

package/dist/utils.js.map

@@ -4,6 +4,6 @@
   "sourcesContent": [
   ],
   "mappings": "",
-  "debugId": "B02575DAA75C385064756E2164756E21",
+  "debugId": "27F4432A2CD67A7364756E2164756E21",
   "names": []
 }

package/dist/wrappedEventBuilder.js

@@ -1,12 +1,12 @@
 import {
-  handleEventError,
-  unwrapEvent,
-  wrappedEventBuilder
-} from "./chunk-z388cd25.js";
+  unwrapEvent2,
+  handleEventError2,
+  wrappedEventBuilder2
+} from "./chunk-zkz6ew8c.js";
 export {
-  wrappedEventBuilder,
-  unwrapEvent,
-  handleEventError
+  handleEventError2 as handleEventError,
+  unwrapEvent2 as unwrapEvent,
+  wrappedEventBuilder2 as wrappedEventBuilder
 };
 
-//# debugId=AEFF0A7062715AE064756E2164756E21
+//# debugId=13D61F145C1E7AE864756E2164756E21

package/dist/wrappedEventBuilder.js.map

@@ -4,6 +4,6 @@
   "sourcesContent": [
   ],
   "mappings": "",
-  "debugId": "AEFF0A7062715AE064756E2164756E21",
+  "debugId": "13D61F145C1E7AE864756E2164756E21",
   "names": []
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@requence/event-sourcing",
-  "version": "1.4.1",
+  "version": "1.5.1",
   "description": "Event sourcing primitives — aggregate roots, projections, process managers, and event listeners",
   "type": "module",
   "sideEffects": false,
@@ -37,6 +37,12 @@
       "types": "./dist/redis/index.d.ts",
       "import": "./dist/redis/index.js",
       "default": "./dist/redis/index.js"
+    },
+    "./surreal": {
+      "bun": "./src/surreal/index.ts",
+      "types": "./dist/surreal/index.d.ts",
+      "import": "./dist/surreal/index.js",
+      "default": "./dist/surreal/index.js"
     }
   },
   "files": [
@@ -49,6 +55,9 @@
     "build": "bun run build.ts",
     "test": "bun test",
     "check-types": "tsc --noEmit",
+    "lint": "oxlint",
+    "format": "oxfmt",
+    "format:check": "oxfmt --check",
     "cs": "changeset",
     "version": "changeset version",
     "release": "bun run build && changeset publish",
@@ -62,7 +71,8 @@
   "peerDependencies": {
     "zod": "^4.3.6",
     "drizzle-orm": "^0.45.1",
-    "ioredis": "^5.9.3"
+    "ioredis": "^5.9.3",
+    "surrealdb": "^2.0.0"
   },
   "peerDependenciesMeta": {
     "drizzle-orm": {
@@ -70,24 +80,23 @@
     },
     "ioredis": {
       "optional": true
+    },
+    "surrealdb": {
+      "optional": true
     }
   },
   "devDependencies": {
     "@changesets/changelog-github": "^0.6.0",
     "@changesets/cli": "^2.31.0",
-    "@eslint/js": "^10.0.1",
-    "@stylistic/eslint-plugin": "^5.10.0",
+    "@surrealdb/node": "^3.0.3",
     "@types/bun": "^1.3.13",
     "@types/node": "^25.6.0",
     "drizzle-orm": "^0.45.1",
-    "eslint": "^10.2.1",
-    "eslint-plugin-import": "^2.32.0",
-    "eslint-plugin-no-only-tests": "^3.3.0",
-    "globals": "^17.5.0",
     "ioredis": "^5.10.1",
-    "prettier": "^3.8.3",
+    "oxfmt": "^0.59.0",
+    "oxlint": "^1.74.0",
+    "surrealdb": "^2.0.7",
     "typescript": "^6.0.3",
-    "typescript-eslint": "^8.59.1",
     "zod": "^4.3.6"
   },
   "license": "MIT",

package/src/createAggregateRoot.ts

@@ -17,7 +17,7 @@ import {
   InfiniteLoopError,
   ValidationError,
 } from './errors.ts'
-import type { LockCreator } from './lock.ts'
+import { DEFAULT_LOCK_TTL, type LockCreator } from './lock.ts'
 import { isRefreshing } from './refresh.ts'
 import createSnapshotGenerator, {
   type CompleteSnapshotGenerator,
@@ -530,6 +530,7 @@ export function createAggregateRoot<Name extends string>(type: Name) {
     let downstreamSettledPromise = () => Promise.resolve()
     let releaseLock!: () => Promise<void>
     let extendLock!: EventHandlerOptions['extendLock']
+    let lockTtl: number | undefined
 
     const warnReleaseLock = () => {
       if (releasedAfterChain) {
@@ -582,8 +583,25 @@ export function createAggregateRoot<Name extends string>(type: Name) {
     let commandChain = createLock([type, streamId]).then((lock) => {
       releaseLock = lock.release
       extendLock = lock.extend
+      lockTtl = lock.ttl
       return [] as Error | BaseInputEvent[]
     })
+
+    // A replay is the library's own work and takes as long as the stream is
+    // long, so unlike a slow command it must not cost the caller the lock.
+    // Extended on a timer while it runs, and never past it: a lock nobody
+    // releases still expires.
+    const keepLockAlive = async <T>(work: () => Promise<T>) => {
+      const timer = setInterval(
+        () => void extendLock().catch(() => false),
+        (lockTtl ?? DEFAULT_LOCK_TTL) / 4,
+      )
+      try {
+        return await work()
+      } finally {
+        clearInterval(timer)
+      }
+    }
     let commandChainTouched = false
     let releasedAfterChain = false
     let transactionDelay: TransactionDelay | undefined
@@ -616,9 +634,8 @@ export function createAggregateRoot<Name extends string>(type: Name) {
                 return previousEvents
               }
               const events = (
-                await normalizeArray(
-                  commandFn.apply(rawCommands, args),
-                  () => extendLock(),
+                await normalizeArray(commandFn.apply(rawCommands, args), () =>
+                  extendLock(),
                 )
               ).filter((event) => Boolean(event))
 
@@ -770,7 +787,9 @@ export function createAggregateRoot<Name extends string>(type: Name) {
         // ensure commands are executed after load is finished
         commandChain = commandChain
           .then(() =>
-            loadUntil(state, snapshotApi, streamId, undefined, filter),
+            keepLockAlive(() =>
+              loadUntil(state, snapshotApi, streamId, undefined, filter),
+            ),
           )
           .then((loadedVersion) => {
             version = loadedVersion

package/src/createCheckpointApi.ts

@@ -18,6 +18,14 @@ const checkpointSchema = z.object({
 
 export type Checkpoint = z.output<typeof checkpointSchema>
 
+/**
+ * The outcome of {@link CheckpointApi.claim}: either this instance owns the
+ * event and must run its work, or another instance already has it.
+ */
+export type ClaimResult =
+  | { claimed: false }
+  | { claimed: true; release: () => Promise<void> }
+
 export type CheckpointMethods = {
   get: (
     type: 'projection' | 'processManager',
@@ -57,12 +65,16 @@ export function createCheckpointApi(
   // every load/upsert so optimistic-concurrency writes can detect when another
   // instance has advanced the same checkpoint.
   let version: number | null = null
+  // The position that goes with `version`. Only {@link CheckpointApi.claim}
+  // needs it, to put the cursor back if the work it claimed then fails.
+  let position: number | null = null
 
   const api = {
     relatedStreamEvents: params.relatedStreamEvents,
     async clear() {
       await params.delete(params.type, params.name)
       version = null
+      position = null
     },
     /**
      * Load the persisted checkpoint and sync the local version. Returns the
@@ -72,8 +84,93 @@ export function createCheckpointApi(
     async load() {
       const checkpoint = await params.get(params.type, params.name)
       version = checkpoint?.version ?? null
+      position = checkpoint?.lastEventPosition ?? null
       return checkpoint ?? null
     },
+    /**
+     * Takes ownership of `event` *before* its work runs, so that exactly one
+     * instance does that work.
+     *
+     * Every instance runs its own copy of a projection against shared storage,
+     * and each decides what it has already applied from a cursor only it can
+     * see. Two instances catching up over the same backlog — or one catching up
+     * while the other applies an event it just appended — therefore both reach
+     * the same handler. Writing the cursor first, through the same
+     * compare-and-swap the ordinary write uses, is what breaks the tie: the
+     * loser is told so and skips the event instead of repeating its side
+     * effects.
+     *
+     * Returns `{ claimed: false }` when another writer already covers this
+     * position. On success the caller gets a `release` to call if the work then
+     * fails, which puts the cursor back so the event is picked up again rather
+     * than silently skipped — without it, claiming would turn every failed
+     * handler into a lost event.
+     */
+    async claim(
+      event: BaseOutputEvent,
+      metadata: Record<string, any> = {},
+    ): Promise<ClaimResult> {
+      while (true) {
+        const expectedVersion = version
+        const previousPosition = position
+        const nextVersion = (expectedVersion ?? -1) + 1
+
+        const committed = await params.upsert(
+          {
+            lastEventPosition: event.position,
+            type: params.type,
+            name: params.name,
+            metadata,
+            version: nextVersion,
+          },
+          expectedVersion,
+        )
+
+        if (committed) {
+          version = nextVersion
+          position = event.position
+
+          return {
+            claimed: true,
+            async release() {
+              // Only undo a claim that is still the newest write. Once anything
+              // else has moved the cursor, rewinding it would drop that work.
+              if (version !== nextVersion) {
+                return
+              }
+
+              if (previousPosition === null) {
+                await api.clear()
+                return
+              }
+
+              const restored = await params.upsert(
+                {
+                  lastEventPosition: previousPosition,
+                  type: params.type,
+                  name: params.name,
+                  metadata,
+                  version: nextVersion + 1,
+                },
+                nextVersion,
+              )
+
+              if (restored) {
+                version = nextVersion + 1
+                position = previousPosition
+              }
+            },
+          }
+        }
+
+        // Another writer advanced this checkpoint. Refresh our view of it.
+        const current = await api.load()
+
+        if (current && current.lastEventPosition >= event.position) {
+          return { claimed: false }
+        }
+      }
+    },
     /**
      * Persist the checkpoint position (and optional metadata) for the given
      * event.
@@ -108,6 +205,7 @@ export function createCheckpointApi(
 
         if (committed) {
           version = nextVersion
+          position = event.position
           return
         }
 

package/src/createProcessManager.ts

@@ -293,7 +293,9 @@ export function buildProcessManagerCreator(params: {
         await hydrated
       },
       async beginSession() {
-        if (!hasState) return
+        if (!hasState) {
+          return
+        }
         // Load through the checkpoint API so the local version is synced with
         // the store; the subsequent fold relies on it for compare-and-swap.
         const checkpoint = await checkpointApi.load()
@@ -310,7 +312,9 @@ export function buildProcessManagerCreator(params: {
         sessionActive = true
       },
       endSession() {
-        if (!hasState) return
+        if (!hasState) {
+          return
+        }
         state = null
         sessionActive = false
       },
@@ -379,10 +383,7 @@ export function buildProcessManagerCreator(params: {
       async state() {
         await hydrated
         if (!sessionActive && hasState) {
-          const checkpoint = await params.checkpoint.get(
-            'processManager',
-            name,
-          )
+          const checkpoint = await params.checkpoint.get('processManager', name)
           return checkpoint?.metadata?.state ?? clone(initialState)
         }
         return state

package/src/createProjection.ts

@@ -266,86 +266,112 @@ export function buildProjectionCreator(params: {
 
       const runner = (async () => {
         await unlocked
-        await withProjectionInfo({ name, event }, async () => {
-          try {
-            await handler?.(event, {
-              replaying,
-              async replayUntil(position, filterEvents) {
-                if (position >= event.position) {
-                  throw new ProjectionReplayLoopError(
-                    `Event handler on${event.type} of projection ${name} tried to replay to the future`,
-                    { name, eventHandler: `on${event.type}` },
-                    event,
-                  )
+
+        // Take ownership of the event before anything observable happens, so a
+        // peer applying the same event does not apply it twice. `claimed` is
+        // null while replaying: a replay deliberately re-applies everything and
+        // `beginReplay` leaves the stored cursor where it was, so a claim would
+        // read that not-yet-rewound position and skip the whole run.
+        const claimed = isReplaying() ? null : await checkpointApi.claim(event)
+
+        if (claimed && !claimed.claimed) {
+          return
+        }
+
+        const release = claimed?.claimed ? claimed.release : null
+
+        try {
+          await withProjectionInfo({ name, event }, async () => {
+            try {
+              await handler?.(event, {
+                replaying,
+                async replayUntil(position, filterEvents) {
+                  if (position >= event.position) {
+                    throw new ProjectionReplayLoopError(
+                      `Event handler on${event.type} of projection ${name} tried to replay to the future`,
+                      { name, eventHandler: `on${event.type}` },
+                      event,
+                    )
+                  }
+
+                  locks.delete(event.streamId)
+                  return api.replayUntil(event.streamId, position, filterEvents)
+                },
+              })
+            } catch (error) {
+              if (error instanceof ReplaySkipError) {
+                if (isReplaying()) {
+                  return
                 }
 
-                locks.delete(event.streamId)
-                return api.replayUntil(event.streamId, position, filterEvents)
-              },
-            })
-          } catch (error) {
-            if (error instanceof ReplaySkipError) {
-              if (isReplaying()) {
-                return
+                throw new Error(
+                  'ReplaySkipError should never be thrown outside replay',
+                )
               }
 
-              throw new Error(
-                'ReplaySkipError should never be thrown outside replay',
+              if (
+                !(error instanceof Error) ||
+                error instanceof ProjectionReplayLoopError
+              ) {
+                throw error
+              }
+              throw new ProjectionEventHandlerExecutionError(
+                name,
+                `on${event.type}`,
+                event,
+                error,
               )
             }
+            try {
+              await globalEventHandler?.(event)
+            } catch (error) {
+              if (!(error instanceof Error)) {
+                throw error
+              }
 
-            if (
-              !(error instanceof Error) ||
-              error instanceof ProjectionReplayLoopError
-            ) {
-              throw error
-            }
-            throw new ProjectionEventHandlerExecutionError(
-              name,
-              `on${event.type}`,
-              event,
-              error,
-            )
-          }
-          try {
-            await globalEventHandler?.(event)
-          } catch (error) {
-            if (!(error instanceof Error)) {
-              throw error
+              throw new ProjectionEventHandlerExecutionError(
+                name,
+                'GLOBAL',
+                event,
+                error,
+              )
             }
+          })
 
-            throw new ProjectionEventHandlerExecutionError(
-              name,
-              'GLOBAL',
+          if (params.snapshot && snapshotting) {
+            const appliedEvents = await params.snapshot.incrementAppliedCount({
+              projection: name,
+              id: event.streamId,
+            })
+            const snapshot = await snapshotting.internalCapture(
               event,
-              error,
+              appliedEvents,
             )
-          }
-        })
-
-        if (params.snapshot && snapshotting) {
-          const appliedEvents = await params.snapshot.incrementAppliedCount({
-            projection: name,
-            id: event.streamId,
-          })
-          const snapshot = await snapshotting.internalCapture(
-            event,
-            appliedEvents,
-          )
 
-          if (snapshot) {
-            await params.snapshot.put({
-              projectionType: name,
-              projectionId: event.streamId,
-              lastEventPosition: event.position,
-              state: snapshot.state,
-              schemaVersion: snapshot.version,
-              createdAt: new Date(),
-            })
+            if (snapshot) {
+              await params.snapshot.put({
+                projectionType: name,
+                projectionId: event.streamId,
+                lastEventPosition: event.position,
+                state: snapshot.state,
+                schemaVersion: snapshot.version,
+                createdAt: new Date(),
+              })
+            }
           }
+        } catch (error) {
+          // The cursor was moved before this work ran, so it has to go back or
+          // the event would never be retried — a claim must not turn a failing
+          // handler into a silently skipped one.
+          await release?.()
+          throw error
         }
 
-        await checkpointApi.upsert(event)
+        // A claim already wrote the cursor. A replay did not take one, so it
+        // still advances the cursor the ordinary way.
+        if (!release) {
+          await checkpointApi.upsert(event)
+        }
       })()
 
       if (exclusive) {

package/src/lock.ts

@@ -1,6 +1,21 @@
 import { Mutex } from 'async-mutex'
 
-export default function lock(defaultTtl = 5000) {
+export const DEFAULT_LOCK_TTL = 5000
+
+export type Lock = {
+  /** Moves the expiry to `ttl` from now (default: half the lock's TTL). */
+  extend(ttl?: number): Promise<boolean>
+  release(): Promise<void>
+  /**
+   * The TTL the lock was taken with. The aggregate root keeps a replay's lock
+   * alive at a quarter of it, and assumes {@link DEFAULT_LOCK_TTL} without it.
+   */
+  ttl?: number
+}
+
+export type LockCreator = (key: string | string[]) => Promise<Lock>
+
+export default function lock(defaultTtl = DEFAULT_LOCK_TTL): LockCreator {
   const locks = new Map<string, Mutex>()
   return async (key: string | string[]) => {
     const k = Array.isArray(key) ? key.join(':') : key
@@ -30,6 +45,7 @@ export default function lock(defaultTtl = 5000) {
     startTimer(defaultTtl)
 
     return {
+      ttl: defaultTtl,
       async extend(ttl?: number) {
         if (isReleased) {
           return false
@@ -54,5 +70,3 @@ export default function lock(defaultTtl = 5000) {
     }
   }
 }
-
-export type LockCreator = ReturnType<typeof lock>

package/src/memory/index.spec.ts

@@ -0,0 +1,4 @@
+import { runStorageDriverContract } from '../tests/storageDriverContract.ts'
+import { createMemoryStorage } from './index.ts'
+
+runStorageDriverContract('memory', () => createMemoryStorage())