@requence/event-sourcing 1.1.1 → 1.3.0

package/dist/createAggregateRoot.js

@@ -1,15 +1,15 @@
 import {
   createAggregateRoot
-} from "./chunk-r601d5jm.js";
-import"./chunk-smy8mxvr.js";
+} from "./chunk-wzw95hzk.js";
+import"./chunk-fkzd741s.js";
 import"./chunk-6q8mr1sg.js";
-import"./chunk-6yrb30rx.js";
-import"./chunk-tfy01fah.js";
-import"./chunk-th14wxh8.js";
-import"./chunk-yn2sjcg3.js";
-import"./chunk-8qn1nqnh.js";
 import"./chunk-z388cd25.js";
+import"./chunk-3ejt4h7x.js";
+import"./chunk-8qn1nqnh.js";
+import"./chunk-yn2sjcg3.js";
 import"./chunk-2fe8jjdc.js";
+import"./chunk-tfy01fah.js";
+import"./chunk-6yrb30rx.js";
 import"./chunk-391m4mfp.js";
 export {
   createAggregateRoot

package/dist/createEventStore.js

@@ -1,17 +1,17 @@
 import {
   createEventStore
-} from "./chunk-04wqxaqs.js";
-import"./chunk-gq80tgvf.js";
-import"./chunk-smy8mxvr.js";
-import"./chunk-6q8mr1sg.js";
-import"./chunk-6yrb30rx.js";
-import"./chunk-th14wxh8.js";
-import"./chunk-yn2sjcg3.js";
-import"./chunk-8qn1nqnh.js";
+} from "./chunk-z2yp4rve.js";
+import"./chunk-24xjphpk.js";
 import"./chunk-ty9bhdvx.js";
+import"./chunk-fkzd741s.js";
+import"./chunk-6q8mr1sg.js";
+import"./chunk-gq80tgvf.js";
 import"./chunk-z388cd25.js";
-import"./chunk-24xjphpk.js";
+import"./chunk-3ejt4h7x.js";
+import"./chunk-8qn1nqnh.js";
+import"./chunk-yn2sjcg3.js";
 import"./chunk-2fe8jjdc.js";
+import"./chunk-6yrb30rx.js";
 import"./chunk-391m4mfp.js";
 export {
   createEventStore

package/dist/createProcessManager.js

@@ -2,10 +2,10 @@ import {
   buildProcessManagerCreator,
   getProcessManagerInfo,
   isInsideProcessManager
-} from "./chunk-smy8mxvr.js";
+} from "./chunk-fkzd741s.js";
 import"./chunk-6q8mr1sg.js";
-import"./chunk-6yrb30rx.js";
 import"./chunk-yn2sjcg3.js";
+import"./chunk-6yrb30rx.js";
 import"./chunk-391m4mfp.js";
 export {
   isInsideProcessManager,

package/dist/createProjection.js

@@ -2,9 +2,9 @@ import {
   buildProjectionCreator,
   getProjectionInfo,
   isInsideProjection
-} from "./chunk-th14wxh8.js";
-import"./chunk-yn2sjcg3.js";
+} from "./chunk-3ejt4h7x.js";
 import"./chunk-8qn1nqnh.js";
+import"./chunk-yn2sjcg3.js";
 import"./chunk-2fe8jjdc.js";
 import"./chunk-391m4mfp.js";
 export {

package/dist/drizzle/index.js

@@ -11,25 +11,25 @@ import {
 } from "../chunk-jd4q8fcf.js";
 import {
   createEventStore
-} from "../chunk-04wqxaqs.js";
-import"../chunk-gq80tgvf.js";
+} from "../chunk-z2yp4rve.js";
+import"../chunk-24xjphpk.js";
 import {
   createAggregateRoot
-} from "../chunk-r601d5jm.js";
-import"../chunk-smy8mxvr.js";
+} from "../chunk-wzw95hzk.js";
+import"../chunk-ty9bhdvx.js";
+import"../chunk-fkzd741s.js";
 import {
   extendTypes,
   superjson
 } from "../chunk-6q8mr1sg.js";
-import"../chunk-6yrb30rx.js";
-import"../chunk-tfy01fah.js";
-import"../chunk-th14wxh8.js";
-import"../chunk-yn2sjcg3.js";
-import"../chunk-8qn1nqnh.js";
-import"../chunk-ty9bhdvx.js";
+import"../chunk-gq80tgvf.js";
 import"../chunk-z388cd25.js";
-import"../chunk-24xjphpk.js";
+import"../chunk-3ejt4h7x.js";
+import"../chunk-8qn1nqnh.js";
+import"../chunk-yn2sjcg3.js";
 import"../chunk-2fe8jjdc.js";
+import"../chunk-tfy01fah.js";
+import"../chunk-6yrb30rx.js";
 import {
   ConcurrencyError
 } from "../chunk-391m4mfp.js";
@@ -330,4 +330,4 @@ export {
   createAggregateRoot
 };
 
-//# debugId=A994099EE4DAD7B764756E2164756E21
+//# debugId=295E8F0129E030EF64756E2164756E21

package/dist/drizzle/index.js.map

@@ -5,6 +5,6 @@
     "import {\n  type SQL,\n  and,\n  asc,\n  desc,\n  eq,\n  gt,\n  inArray,\n  lte,\n  sql,\n} from 'drizzle-orm'\nimport type { PgDatabase } from 'drizzle-orm/pg-core'\n\nimport type { AnyAggregateRoot } from '../createAggregateRoot.ts'\nimport {\n  ConcurrencyError,\n  createEventStore as createBaseEventStore,\n  isStreamEvents,\n  isStreamId,\n} from '../index.ts'\nimport {\n  aggregateRootSnapshots,\n  checkpoints,\n  events,\n  projectionAppliedEvents,\n  projectionSnapshots,\n} from './postgres.ts'\nimport type {\n  EventStore,\n  EventStoreParamsWithAggregateRootSnapshots,\n  EventsFromRoot,\n  OnProgress,\n} from '../createEventStore.ts'\nimport type { LockCreator } from '../lock.ts'\nimport { superjson } from '../superjson.ts'\nimport type {\n  BaseOutputEvent,\n  MaybePromise,\n  OutputEvent,\n} from '../utilityTypes.js'\n\nexport { createAggregateRoot } from '../index.ts'\nexport { extendTypes } from '../superjson.ts'\n\nexport type OnEventsAppendend = (\n  events: BaseOutputEvent[],\n) => MaybePromise<void>\n\ninterface DrizzleEventStoreParams<Root extends AnyAggregateRoot> {\n  database: PgDatabase<any, any> | (() => PgDatabase<any, any>)\n  aggregateRoots: Root[]\n  autoInit?: boolean\n  lock?: LockCreator\n  postProcessEvent?: EventStoreParamsWithAggregateRootSnapshots<Root>['postProcessEvent']\n  onProjectionReplay?: OnProgress\n  onProcessManagerRefresh?: OnProgress\n  onEventsAppended?: OnEventsAppendend\n}\n\nfunction isPgUniqueViolation(\n  err: unknown,\n): err is { cause: { code: string; constraint?: string } } {\n  if (typeof err !== 'object' || err === null) {\n    return false\n  }\n\n  const cause = (err as any).cause\n  if (typeof cause !== 'object' || cause === null) {\n    return false\n  }\n\n  if (cause.code !== '23505') {\n    return false\n  }\n\n  return true\n}\n\nfunction createEventsQuery(database: PgDatabase<any, any>) {\n  return database\n    .select({\n      position: events.position,\n      type: events.type,\n      schemaVersion: events.schemaVersion,\n      payload: events.payload,\n      streamId: events.streamId,\n      streamType: events.streamType,\n      streamVersion: events.streamVersion,\n      createdAt: events.createdAt,\n      actorId: events.actorId,\n      correlationId: events.correlationId,\n      causationId: events.causationId,\n      metadata: events.metadata,\n    })\n    .from(events)\n    .orderBy(asc(events.position))\n    .$dynamic()\n}\n\ntype EventsQuery = ReturnType<typeof createEventsQuery>\n\nexport async function fetchEvents<E extends OutputEvent<any> = BaseOutputEvent>(\n  database: PgDatabase<any, any>,\n  modifyQuery: (query: EventsQuery, table: typeof events) => EventsQuery = (\n    q,\n  ) => q,\n) {\n  const resolvedEvents = await modifyQuery(createEventsQuery(database), events)\n\n  return resolvedEvents.map((resolvedEvent) => ({\n    ...resolvedEvent,\n    payload: superjson.parse(resolvedEvent.payload),\n    metadata: superjson.deserialize(resolvedEvent.metadata),\n  })) as E[]\n}\n\nexport function createEventStore<const Root extends AnyAggregateRoot>({\n  database,\n  aggregateRoots,\n  postProcessEvent,\n  onProjectionReplay,\n  onProcessManagerRefresh,\n  onEventsAppended,\n  autoInit,\n  lock,\n}: DrizzleEventStoreParams<Root>): EventStore<\n  EventsFromRoot<Root>,\n  Root,\n  true\n> {\n  const db = () => (typeof database === 'function' ? database() : database)\n\n  return createBaseEventStore({\n    aggregateRoots,\n    postProcessEvent,\n    onProjectionReplay,\n    onProcessManagerRefresh,\n    autoInit,\n    lock,\n    async *loadEvents(select, range) {\n      const conditions = [] as SQL[]\n\n      if (select) {\n        const selects = Array.isArray(select) ? select : [select]\n        const streamTypes = selects.map((select) => select.stream)\n        const streamIds = selects\n          .map((select) => (isStreamId(select) ? select.id : null))\n          .filter(Boolean) as string[]\n        const eventTypes = selects.flatMap((select) =>\n          isStreamEvents(select) ? select.events : [],\n        )\n        conditions.push(inArray(events.streamType, streamTypes))\n\n        if (streamIds.length > 0) {\n          conditions.push(inArray(events.streamId, streamIds))\n        }\n\n        if (eventTypes.length > 0) {\n          conditions.push(inArray(events.type, eventTypes))\n        }\n      }\n      let lastPosition = 0\n\n      if (range?.from) {\n        lastPosition = range.from - 1\n      }\n\n      if (range?.to) {\n        conditions.push(lte(events.position, range.to))\n      }\n\n      const chunkSize = 50\n\n      while (true) {\n        const resolvedEvents = await db()\n          .select({\n            position: events.position,\n            type: events.type,\n            schemaVersion: events.schemaVersion,\n            payload: events.payload,\n            streamId: events.streamId,\n            streamType: events.streamType,\n            streamVersion: events.streamVersion,\n            createdAt: events.createdAt,\n            actorId: events.actorId,\n            correlationId: events.correlationId,\n            causationId: events.causationId,\n            metadata: events.metadata,\n          })\n          .from(events)\n          .where(and(...conditions, gt(events.position, lastPosition)))\n          .limit(chunkSize)\n          .orderBy(asc(events.position))\n\n        if (resolvedEvents.length === 0) {\n          break\n        }\n\n        for (const resolvedEvent of resolvedEvents) {\n          yield {\n            ...resolvedEvent,\n            payload: superjson.parse(resolvedEvent.payload),\n            metadata: superjson.deserialize(resolvedEvent.metadata),\n          }\n          lastPosition = resolvedEvent.position\n        }\n      }\n    },\n    async appendEvents(streamId, newEvents, expectedVersion) {\n      const mappedEvents = newEvents.map((event, index) => ({\n        streamId: streamId.id,\n        streamType: streamId.stream,\n        streamVersion: expectedVersion + 1 + index,\n        type: event.type,\n        payload: superjson.stringify(event.payload),\n        metadata: superjson.serialize(event.metadata),\n        causationId: event.causationId,\n        actorId: event.actorId,\n        correlationId: event.correlationId,\n        schemaVersion: event.schemaVersion,\n      }))\n\n      try {\n        const persistedEvents = await db()\n          .insert(events)\n          .values(mappedEvents)\n          .returning()\n\n        const resolvedEvents = persistedEvents\n          .map((persistendEvent) => ({\n            ...persistendEvent,\n            payload: superjson.parse(persistendEvent.payload),\n            metadata: superjson.deserialize<\n              Record<string, unknown> | undefined\n            >(persistendEvent.metadata),\n          }))\n          .toSorted((eventA, eventB) => eventA.position - eventB.position)\n\n        onEventsAppended?.(resolvedEvents)\n\n        return resolvedEvents\n      } catch (error) {\n        if (isPgUniqueViolation(error)) {\n          const [lastStreamEvent] = await db()\n            .select({\n              streamVersion: events.streamVersion,\n            })\n            .from(events)\n            .where(\n              and(\n                eq(events.streamId, streamId.id),\n                eq(events.streamType, streamId.stream),\n              ),\n            )\n            .orderBy(desc(events.position))\n            .limit(1)\n\n          const currentVersion = lastStreamEvent?.streamVersion ?? 0\n          throw new ConcurrencyError(streamId, expectedVersion, currentVersion)\n        }\n        throw error\n      }\n    },\n    checkpoint: {\n      async upsert(checkpoint, expectedVersion) {\n        const metadata = superjson.stringify(checkpoint.metadata)\n        // Compare-and-swap: on an existing row the DO UPDATE only fires when\n        // the stored version still matches `expectedVersion`. A `null`\n        // expectation means \"insert only\" — if the row already exists the\n        // guard fails and no row is returned, signalling a conflict.\n        const committed = await db()\n          .insert(checkpoints)\n          .values({\n            lastEventPosition: checkpoint.lastEventPosition,\n            name: checkpoint.name,\n            type: checkpoint.type,\n            metadata,\n            version: checkpoint.version,\n          })\n          .onConflictDoUpdate({\n            target: [checkpoints.type, checkpoints.name],\n            set: {\n              lastEventPosition: checkpoint.lastEventPosition,\n              metadata,\n              version: checkpoint.version,\n            },\n            setWhere:\n              expectedVersion === null\n                ? sql`false`\n                : eq(checkpoints.version, expectedVersion),\n          })\n          .returning({ version: checkpoints.version })\n\n        return committed.length > 0\n      },\n      async get(type, name) {\n        const [checkpoint] = await db()\n          .select({\n            type: checkpoints.type,\n            name: checkpoints.name,\n            lastEventPosition: checkpoints.lastEventPosition,\n            metadata: checkpoints.metadata,\n            version: checkpoints.version,\n          })\n          .from(checkpoints)\n          .where(and(eq(checkpoints.type, type), eq(checkpoints.name, name)))\n\n        if (!checkpoint) {\n          return null\n        }\n\n        return {\n          ...checkpoint,\n          metadata: superjson.parse(checkpoint.metadata),\n        }\n      },\n      async delete(type, name) {\n        await db()\n          .delete(checkpoints)\n          .where(and(eq(checkpoints.type, type), eq(checkpoints.name, name)))\n      },\n    },\n\n    projectionSnapshot: {\n      async put(snapshot) {\n        await db()\n          .insert(projectionSnapshots)\n          .values({\n            lastEventPosition: snapshot.lastEventPosition,\n            projectionId: snapshot.projectionId,\n            projectionType: snapshot.projectionType,\n            schemaVersion: snapshot.schemaVersion,\n            state: superjson.stringify(snapshot.state),\n            metadata: superjson.stringify(snapshot.metadata),\n          })\n      },\n      async get(select) {\n        const [snapshot] = await db()\n          .select({\n            projectionId: projectionSnapshots.projectionId,\n            projectionType: projectionSnapshots.projectionType,\n            state: projectionSnapshots.state,\n            lastEventPosition: projectionSnapshots.lastEventPosition,\n            schemaVersion: projectionSnapshots.schemaVersion,\n            createdAt: projectionSnapshots.createdAt,\n            metadata: projectionSnapshots.metadata,\n          })\n          .from(projectionSnapshots)\n          .where(\n            and(\n              eq(projectionSnapshots.projectionId, select.id),\n              eq(projectionSnapshots.projectionType, select.projection),\n            ),\n          )\n          .orderBy(desc(projectionSnapshots.lastEventPosition))\n\n        if (!snapshot) {\n          return null\n        }\n\n        return {\n          ...snapshot,\n          state: superjson.parse(snapshot.state),\n          metadata: super.parse(snapshot.metadata),\n        }\n      },\n      async delete(target, fromPosition) {\n        const conditions = [\n          eq(projectionSnapshots.projectionType, target.projection),\n        ]\n\n        if (target.id) {\n          conditions.push(eq(projectionSnapshots.projectionId, target.id))\n        }\n\n        if (fromPosition) {\n          conditions.push(\n            gt(projectionSnapshots.lastEventPosition, fromPosition),\n          )\n        }\n\n        await db()\n          .delete(projectionSnapshots)\n          .where(and(...conditions))\n      },\n      async incrementAppliedCount(select) {\n        const [applied] = await db()\n          .insert(projectionAppliedEvents)\n          .values({\n            projectionId: select.id,\n            projectionType: select.projection,\n            appliedEvents: 1,\n          })\n          .onConflictDoUpdate({\n            target: [\n              projectionAppliedEvents.projectionId,\n              projectionAppliedEvents.projectionType,\n            ],\n            set: {\n              appliedEvents: sql`${projectionAppliedEvents.appliedEvents} + 1`,\n            },\n          })\n          .returning({\n            appliedEvents: projectionAppliedEvents.appliedEvents,\n          })\n\n        return applied.appliedEvents\n      },\n    },\n    aggregateRootSnapshot: {\n      async put(snapshot) {\n        await db()\n          .insert(aggregateRootSnapshots)\n          .values({\n            lastEventPosition: snapshot.lastEventPosition,\n            schemaVersion: snapshot.schemaVersion,\n            state: superjson.stringify(snapshot.state),\n            streamId: snapshot.streamId,\n            streamType: snapshot.streamType,\n            streamVersion: snapshot.streamVersion,\n            metadata: superjson.stringify(snapshot.metadata),\n          })\n      },\n      async get(select) {\n        const [snapshot] = await db()\n          .select({\n            streamId: aggregateRootSnapshots.streamId,\n            streamType: aggregateRootSnapshots.streamType,\n            streamVersion: aggregateRootSnapshots.streamVersion,\n            schemaVersion: aggregateRootSnapshots.schemaVersion,\n            state: aggregateRootSnapshots.state,\n            createdAt: aggregateRootSnapshots.createdAt,\n            lastEventPosition: aggregateRootSnapshots.lastEventPosition,\n            metadata: aggregateRootSnapshots.metadata,\n          })\n          .from(aggregateRootSnapshots)\n          .where(\n            and(\n              eq(aggregateRootSnapshots.streamId, select.id),\n              eq(aggregateRootSnapshots.streamType, select.stream),\n            ),\n          )\n          .orderBy(desc(aggregateRootSnapshots.streamVersion))\n\n        if (!snapshot) {\n          return null\n        }\n\n        return {\n          ...snapshot,\n          state: superjson.parse(snapshot.state),\n          metadata: superjson.parse(snapshot.metadata),\n        }\n      },\n      async delete(target, fromStreamVersion) {\n        await db()\n          .delete(aggregateRootSnapshots)\n          .where(\n            and(\n              eq(aggregateRootSnapshots.streamId, target.id),\n              eq(aggregateRootSnapshots.streamType, target.stream),\n              gt(aggregateRootSnapshots.streamVersion, fromStreamVersion),\n            ),\n          )\n      },\n    },\n  }) as any\n}\n"
   ],
   "mappings": "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",
-  "debugId": "A994099EE4DAD7B764756E2164756E21",
+  "debugId": "295E8F0129E030EF64756E2164756E21",
   "names": []
 }

package/dist/index.d.ts

@@ -6,7 +6,7 @@ export type { Checkpoint } from './createCheckpointApi.ts';
 export { isInsideProcessManager, getProcessManagerInfo, } from './createProcessManager.ts';
 export { isInsideEventListener, getEventListenerInfo, } from './createEventListener.ts';
 export * from './errors.ts';
-export { type Snapshot as AggregateRootSnapshot, type AnyAggregateRoot, type AnyStream, createAggregateRoot, } from './createAggregateRoot.ts';
+export { type Snapshot as AggregateRootSnapshot, type AnyAggregateRoot, type AnyStream, type SettledOptions, createAggregateRoot, } from './createAggregateRoot.ts';
 export { skipRefreshing } from './refresh.ts';
 export { skipReplay } from './replay.ts';
 export declare function isStreamId(stream: Stream): stream is StreamId | StreamIdEvents;

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,MAAM,EACN,YAAY,EACZ,QAAQ,EACR,cAAc,EACf,MAAM,mBAAmB,CAAA;AAE1B,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAA;AACxD,YAAY,EAAE,eAAe,IAAI,KAAK,EAAE,MAAM,qBAAqB,CAAA;AACnE,OAAO,EACL,KAAK,QAAQ,IAAI,kBAAkB,EACnC,kBAAkB,EAClB,iBAAiB,GAClB,MAAM,uBAAuB,CAAA;AAC9B,YAAY,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAA;AAC1D,OAAO,EACL,sBAAsB,EACtB,qBAAqB,GACtB,MAAM,2BAA2B,CAAA;AAClC,OAAO,EACL,qBAAqB,EACrB,oBAAoB,GACrB,MAAM,0BAA0B,CAAA;AACjC,cAAc,aAAa,CAAA;AAC3B,OAAO,EACL,KAAK,QAAQ,IAAI,qBAAqB,EACtC,KAAK,gBAAgB,EACrB,KAAK,SAAS,EACd,mBAAmB,GACpB,MAAM,0BAA0B,CAAA;AAEjC,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AAC7C,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAExC,wBAAgB,UAAU,CACxB,MAAM,EAAE,MAAM,GACb,MAAM,IAAI,QAAQ,GAAG,cAAc,CAErC;AACD,wBAAgB,cAAc,CAC5B,MAAM,EAAE,MAAM,GACb,MAAM,IAAI,YAAY,GAAG,cAAc,CAEzC;AACD,YAAY,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,MAAM,EACN,YAAY,EACZ,QAAQ,EACR,cAAc,EACf,MAAM,mBAAmB,CAAA;AAE1B,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAA;AACxD,YAAY,EAAE,eAAe,IAAI,KAAK,EAAE,MAAM,qBAAqB,CAAA;AACnE,OAAO,EACL,KAAK,QAAQ,IAAI,kBAAkB,EACnC,kBAAkB,EAClB,iBAAiB,GAClB,MAAM,uBAAuB,CAAA;AAC9B,YAAY,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAA;AAC1D,OAAO,EACL,sBAAsB,EACtB,qBAAqB,GACtB,MAAM,2BAA2B,CAAA;AAClC,OAAO,EACL,qBAAqB,EACrB,oBAAoB,GACrB,MAAM,0BAA0B,CAAA;AACjC,cAAc,aAAa,CAAA;AAC3B,OAAO,EACL,KAAK,QAAQ,IAAI,qBAAqB,EACtC,KAAK,gBAAgB,EACrB,KAAK,SAAS,EACd,KAAK,cAAc,EACnB,mBAAmB,GACpB,MAAM,0BAA0B,CAAA;AAEjC,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AAC7C,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAExC,wBAAgB,UAAU,CACxB,MAAM,EAAE,MAAM,GACb,MAAM,IAAI,QAAQ,GAAG,cAAc,CAErC;AACD,wBAAgB,cAAc,CAC5B,MAAM,EAAE,MAAM,GACb,MAAM,IAAI,YAAY,GAAG,cAAc,CAEzC;AACD,YAAY,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAA"}

package/dist/index.js

@@ -4,35 +4,35 @@ import {
 } from "./chunk-jd4q8fcf.js";
 import {
   createEventStore
-} from "./chunk-04wqxaqs.js";
-import"./chunk-gq80tgvf.js";
+} from "./chunk-z2yp4rve.js";
+import {
+  getEventListenerInfo,
+  isInsideEventListener
+} from "./chunk-24xjphpk.js";
 import {
   createAggregateRoot
-} from "./chunk-r601d5jm.js";
+} from "./chunk-wzw95hzk.js";
+import"./chunk-ty9bhdvx.js";
 import {
   getProcessManagerInfo,
   isInsideProcessManager
-} from "./chunk-smy8mxvr.js";
+} from "./chunk-fkzd741s.js";
 import"./chunk-6q8mr1sg.js";
-import {
-  skipRefreshing
-} from "./chunk-6yrb30rx.js";
-import"./chunk-tfy01fah.js";
+import"./chunk-gq80tgvf.js";
+import"./chunk-z388cd25.js";
 import {
   getProjectionInfo,
   isInsideProjection
-} from "./chunk-th14wxh8.js";
-import"./chunk-yn2sjcg3.js";
+} from "./chunk-3ejt4h7x.js";
 import"./chunk-8qn1nqnh.js";
-import"./chunk-ty9bhdvx.js";
-import"./chunk-z388cd25.js";
-import {
-  getEventListenerInfo,
-  isInsideEventListener
-} from "./chunk-24xjphpk.js";
+import"./chunk-yn2sjcg3.js";
 import {
   skipReplay
 } from "./chunk-2fe8jjdc.js";
+import"./chunk-tfy01fah.js";
+import {
+  skipRefreshing
+} from "./chunk-6yrb30rx.js";
 import {
   CheckpointConcurrencyError,
   CommandError,
@@ -72,4 +72,4 @@ export {
   CheckpointConcurrencyError
 };
 
-//# debugId=6C4703510F84795D64756E2164756E21
+//# debugId=C43CA0108CEF7D7664756E2164756E21

package/dist/index.js.map

@@ -4,6 +4,6 @@
   "sourcesContent": [
   ],
   "mappings": "",
-  "debugId": "6C4703510F84795D64756E2164756E21",
+  "debugId": "C43CA0108CEF7D7664756E2164756E21",
   "names": []
 }

package/dist/memory/index.js

@@ -4,22 +4,22 @@ import {
 } from "../chunk-jd4q8fcf.js";
 import {
   createEventStore
-} from "../chunk-04wqxaqs.js";
-import"../chunk-gq80tgvf.js";
+} from "../chunk-z2yp4rve.js";
+import"../chunk-24xjphpk.js";
 import {
   createAggregateRoot
-} from "../chunk-r601d5jm.js";
-import"../chunk-smy8mxvr.js";
-import"../chunk-6q8mr1sg.js";
-import"../chunk-6yrb30rx.js";
-import"../chunk-tfy01fah.js";
-import"../chunk-th14wxh8.js";
-import"../chunk-yn2sjcg3.js";
-import"../chunk-8qn1nqnh.js";
+} from "../chunk-wzw95hzk.js";
 import"../chunk-ty9bhdvx.js";
+import"../chunk-fkzd741s.js";
+import"../chunk-6q8mr1sg.js";
+import"../chunk-gq80tgvf.js";
 import"../chunk-z388cd25.js";
-import"../chunk-24xjphpk.js";
+import"../chunk-3ejt4h7x.js";
+import"../chunk-8qn1nqnh.js";
+import"../chunk-yn2sjcg3.js";
 import"../chunk-2fe8jjdc.js";
+import"../chunk-tfy01fah.js";
+import"../chunk-6yrb30rx.js";
 import {
   ConcurrencyError
 } from "../chunk-391m4mfp.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@requence/event-sourcing",
-  "version": "1.1.1",
+  "version": "1.3.0",
   "description": "Event sourcing primitives — aggregate roots, projections, process managers, and event listeners",
   "type": "module",
   "sideEffects": false,

package/src/createAggregateRoot.ts

@@ -12,6 +12,7 @@ import { getProcessManagerInfo } from './createProcessManager.ts'
 import { getProjectionInfo } from './createProjection.ts'
 import {
   CommandError,
+  ConcurrencyError,
   EventValidationError,
   InfiniteLoopError,
   ValidationError,
@@ -83,7 +84,12 @@ type InternalEvent<Event extends EventTemplate> = Prettify<
     [K in Event as K['version']]: Omit<
       BaseInternalEvent<K['type'], K['version'], z.output<K['schema']>>,
       'createdAt' | 'position' | 'streamVersion'
-    >
+    > & {
+      // only set when folding persisted events (stream loading/replay);
+      // events yielded by a command fold before they are appended and have
+      // no position yet
+      position?: number
+    }
   }[Event['version']]
 >
 
@@ -130,12 +136,25 @@ type VersionBuilder = <V extends number, S extends z.ZodType>(
   schema: S,
 ) => { schema: S; version: V }
 
+/**
+ * Options for {@link Stream.settled}.
+ *
+ * `maxRetries` — how many times to reload the stream and re-apply the dispatched
+ * commands when the append loses the optimistic-concurrency race
+ * ({@link ConcurrencyError}). Defaults to `0` (no retry — surface the error, the
+ * historical behaviour). Only the append is retried; command handlers must be
+ * pure functions of loaded state and their arguments for retries to be safe.
+ */
+export type SettledOptions = {
+  maxRetries?: number
+}
+
 type Stream<Commands extends Record<string, Command>, State> = {
   [A in keyof Commands]: (
     ...args: Parameters<Commands[A]>
   ) => Stream<Commands, State>
 } & {
-  settled: () => Promise<Stream<Commands, State>>
+  settled: (options?: SettledOptions) => Promise<Stream<Commands, State>>
   state: () => Promise<State>
   transformError: <T extends Error>(
     error: Constructor<T>,
@@ -145,7 +164,7 @@ type Stream<Commands extends Record<string, Command>, State> = {
 }
 
 export type AnyStream = {
-  settled: () => Promise<AnyStream>
+  settled: (options?: SettledOptions) => Promise<AnyStream>
   state: () => Promise<unknown>
   transformError: <T extends Error>(
     error: Constructor<T>,
@@ -470,7 +489,29 @@ export function createAggregateRoot<Name extends string>(type: Name) {
     return version
   }
 
-  const createStream = (state: any, streamId: string) => {
+  // A command as dispatched by the caller, recorded so it can be re-applied
+  // against a freshly-loaded stream when a settle() retries a ConcurrencyError.
+  type RecordedCommand = { name: string; args: any[] }
+
+  type CreateStreamConfig = {
+    // Whether to load the existing stream before commands run. `false` for
+    // newStream (expects version 0); `true` for loadStream and every retry.
+    load?: boolean
+    filter?: (event: BaseOutputEvent) => MaybePromise<boolean>
+    // Seeded on a retry so replayed commands re-apply automatically, and
+    // transformError handlers registered before settle() carry over.
+    replayCommands?: RecordedCommand[]
+    errorHandlerEntries?: [
+      Constructor<Error>,
+      (error: CommandError<Error>) => Error,
+    ][]
+  }
+
+  const createStream = (
+    state: any,
+    streamId: string,
+    config: CreateStreamConfig = {},
+  ) => {
     let version = 0
     const snapshotApi = createSnapshotApi?.(
       state,
@@ -480,7 +521,8 @@ export function createAggregateRoot<Name extends string>(type: Name) {
     const errorHandlers = new Map<
       Constructor<Error>,
       (error: CommandError<Error>) => Error
-    >()
+    >(config.errorHandlerEntries)
+    const dispatchedCommands: RecordedCommand[] = []
     let downstreamSettledPromise = () => Promise.resolve()
     let releaseLock!: () => Promise<void>
     let extendLock!: EventHandlerOptions['extendLock']
@@ -558,6 +600,9 @@ export function createAggregateRoot<Name extends string>(type: Name) {
             return api.commands
           }
 
+          // Record for a potential settle() retry (reload + re-apply).
+          dispatchedCommands.push({ name: commandName, args })
+
           const commandId = crypto.randomUUID()
           transactionDelay ??= transaction.delay()
           commandChainTouched = true
@@ -742,7 +787,7 @@ export function createAggregateRoot<Name extends string>(type: Name) {
 
           return state
         },
-        async settled() {
+        async settled(options?: SettledOptions): Promise<any> {
           const parentProcessManager = getProcessManagerInfo()
           if (parentProcessManager) {
             const error = new Error(
@@ -760,7 +805,36 @@ export function createAggregateRoot<Name extends string>(type: Name) {
             throw error
           }
 
-          await awaitAll(() => commandChain)
+          const maxRetries = options?.maxRetries ?? 0
+
+          try {
+            await awaitAll(() => commandChain)
+          } catch (error) {
+            // Optimistic-concurrency recovery: another writer advanced the
+            // stream between load and append. Reload and re-apply the same
+            // commands against the fresh version. A failed append leaves this
+            // attempt's lock held (it never reached releaseLock), so release it
+            // before the retry re-acquires — otherwise the retry blocks until
+            // the lock's TTL lapses.
+            if (maxRetries > 0 && error instanceof ConcurrencyError) {
+              await releaseLock?.()
+
+              const retryStream = createStream(clone(initialState), streamId, {
+                load: true,
+                filter: config.filter,
+                replayCommands: dispatchedCommands,
+                errorHandlerEntries: Array.from(errorHandlers),
+              })
+
+              return retryStream.commands.settled({
+                ...options,
+                maxRetries: maxRetries - 1,
+              })
+            }
+
+            throw error
+          }
+
           await downstreamSettledPromise()
           return api.commands
         },
@@ -777,6 +851,18 @@ export function createAggregateRoot<Name extends string>(type: Name) {
 
     registerRootPromiseToUpstream(() => api.commands.settled())
     transaction.after(() => api.commands.settled())
+
+    // Fold existing events before commands run (loadStream, and every retry).
+    if (config.load) {
+      api.load(config.filter)
+    }
+
+    // Re-apply the caller's commands on a retry so the fresh, reloaded stream
+    // reproduces the original intent against the current version.
+    for (const { name, args } of config.replayCommands ?? []) {
+      ;(api.commands as any)[name](...args)
+    }
+
     return api
   }
 
@@ -856,8 +942,9 @@ export function createAggregateRoot<Name extends string>(type: Name) {
           `aggregateRoot.newStream() cannot be called inside a projection. Attempted on aggregate stream ${type} within Projection ${parentProjectionName}.`,
         )
       }
-      return createStream(clone(initialState), id ?? crypto.randomUUID())
-        .commands as any
+      return createStream(clone(initialState), id ?? crypto.randomUUID(), {
+        load: false,
+      }).commands as any
     },
 
     loadStream(id, filter) {
@@ -873,9 +960,10 @@ export function createAggregateRoot<Name extends string>(type: Name) {
           `aggregateRoot.loadStream("${id}") cannot be called inside a projection. Attempted on aggregate stream ${type} within Projection ${parentProjectionName}.`,
         )
       }
-      const root = createStream(clone(initialState), id)
-      root.load(filter as any)
-      return root.commands as any
+      return createStream(clone(initialState), id, {
+        load: true,
+        filter: filter as any,
+      }).commands as any
     },
 
     linkEventStore(load, append, emit, trans, lock, snap) {

package/src/index.ts

@@ -26,6 +26,7 @@ export {
   type Snapshot as AggregateRootSnapshot,
   type AnyAggregateRoot,
   type AnyStream,
+  type SettledOptions,
   createAggregateRoot,
 } from './createAggregateRoot.ts'
 

package/src/tests/aggregateRoot.spec.ts

@@ -336,6 +336,53 @@ describe('AggregateRoot', () => {
     expect(pseudoEventStore.length).toBe(3)
   })
 
+  it('passes the persisted position to event handlers when loading a stream', async () => {
+    const foldedPositions: (number | undefined)[] = []
+
+    const aggregateRoot = createAggregateRoot('test')
+      .withInitialState({
+        lastDeletePosition: undefined as number | undefined,
+      })
+      .withEvents(({ z }) => ({
+        Created: z.null(),
+        Deleted: z.null(),
+      }))
+      .withEventHandlers((state) => ({
+        onCreated(event) {
+          foldedPositions.push(event.position)
+        },
+        onDeleted(event) {
+          foldedPositions.push(event.position)
+          state.lastDeletePosition = event.position
+        },
+      }))
+      .withCommands((_state, event) => ({
+        create() {
+          return event('Created', null)
+        },
+        remove() {
+          return event('Deleted', null)
+        },
+      }))
+
+    const { pseudoEventStore } = setupEventStore(aggregateRoot)
+
+    const root = await aggregateRoot.newStream().create().remove().settled()
+    // events yielded by commands fold before they are appended — no position yet
+    expect(foldedPositions).toEqual([undefined, undefined])
+    expect((await root.state()).lastDeletePosition).toBeUndefined()
+
+    foldedPositions.length = 0
+    const { streamId } = pseudoEventStore[0]
+    const state = await aggregateRoot.loadStream(streamId).state()
+    // persisted events carry their global log position when folded
+    expect(foldedPositions).toEqual([
+      pseudoEventStore[0].position,
+      pseudoEventStore[1].position,
+    ])
+    expect(state.lastDeletePosition).toBe(pseudoEventStore[1].position)
+  })
+
   it('resolves state before side effects', async () => {
     const aggregateRoot = createAggregateRoot('test')
       .withInitialState({
@@ -493,6 +540,48 @@ describe('hotAggregateRoot', () => {
     expect(name).toBe('B') // 'A' never made it
   })
 
+  it('retries the losing write on ConcurrencyError when maxRetries is set', async () => {
+    const slowAggregateRoot = createAggregateRoot('slow')
+      .withEvents(({ z }) => ({
+        Created: z.string(),
+      }))
+      .withCommands((event) => ({
+        async create(delay: number, name: string) {
+          await setTimeout(delay)
+          return event('Created', name)
+        },
+      }))
+
+    const { eventStore, pseudoEventStore } = setupEventStore(slowAggregateRoot, {
+      lock: lock(40), // 40ms
+    })
+
+    const called: string[] = []
+    eventStore.createEventListener('test').withEventHandlers({
+      onCreated(event) {
+        called.push(event.payload)
+      },
+    })
+
+    // Same race as the test above: A locks stream:a, the lock auto-releases
+    // after 40ms while A is still in its 100ms command, so B slips in and
+    // advances the stream to v1. A then loses the append race — but with
+    // maxRetries it reloads (now seeing B's event) and re-appends at v2 instead
+    // of surfacing the ConcurrencyError.
+    await Promise.all([
+      slowAggregateRoot
+        .loadStream('a')
+        .create(100, 'A')
+        .settled({ maxRetries: 3 }),
+      slowAggregateRoot.loadStream('a').create(5, 'B').settled(),
+    ])
+
+    const persisted = pseudoEventStore.filter((e) => e.streamType === 'slow')
+    expect(persisted.map((e) => e.payload)).toEqual(['B', 'A'])
+    expect(persisted.map((e) => e.streamVersion)).toEqual([1, 2])
+    expect(called).toEqual(['B', 'A'])
+  })
+
   it('auto extends locks', async () => {
     const aggregateRoot = createAggregateRoot('slow')
       .withEvents(({ z }) => ({