@requence/event-sourcing 1.4.1 → 1.5.0

package/dist/chunk-yn2sjcg3.js.map

@@ -1,10 +0,0 @@
-{
-  "version": 3,
-  "sources": ["../src/createCheckpointApi.ts"],
-  "sourcesContent": [
-    "import z from 'zod/v4'\n\nimport type { LoadEvents } from './createEventStore.ts'\nimport { CheckpointConcurrencyError, ValidationError } from './errors.ts'\nimport type {\n  BaseOutputEvent,\n  MaybePromise,\n  StreamEvents,\n} from './utilityTypes.ts'\n\nconst checkpointSchema = z.object({\n  lastEventPosition: z.int(),\n  type: z.enum(['projection', 'processManager']),\n  name: z.string(),\n  metadata: z.record(z.string(), z.any()),\n  version: z.int(),\n})\n\nexport type Checkpoint = z.output<typeof checkpointSchema>\n\nexport type CheckpointMethods = {\n  get: (\n    type: 'projection' | 'processManager',\n    name: string,\n  ) => MaybePromise<Checkpoint | null | undefined>\n  delete: (\n    type: 'projection' | 'processManager',\n    name: string,\n  ) => MaybePromise<void>\n  /**\n   * Persist a checkpoint using optimistic concurrency control.\n   *\n   * The write must only succeed if the currently stored version equals\n   * `expectedVersion` (or, when `expectedVersion` is `null`, if no checkpoint\n   * exists yet). `checkpoint.version` holds the version to store on success.\n   * Return `true` when the write was applied and `false` when it was rejected\n   * because another writer had advanced the checkpoint in the meantime.\n   */\n  upsert: (\n    checkpoint: Checkpoint,\n    expectedVersion: number | null,\n  ) => MaybePromise<boolean>\n}\n\nexport function createCheckpointApi(\n  params: CheckpointMethods & {\n    loadEvents: LoadEvents\n    relatedStreamEvents: StreamEvents[] | null\n    name: string\n    type: 'processManager' | 'projection'\n    apply: (event: BaseOutputEvent) => MaybePromise<void>\n    applyAfter?: (event: BaseOutputEvent) => MaybePromise<void>\n  },\n) {\n  // In-memory view of the persisted checkpoint version. `null` means \"no\n  // checkpoint has been written yet\". It is kept in sync with the store on\n  // every load/upsert so optimistic-concurrency writes can detect when another\n  // instance has advanced the same checkpoint.\n  let version: number | null = null\n\n  const api = {\n    relatedStreamEvents: params.relatedStreamEvents,\n    async clear() {\n      await params.delete(params.type, params.name)\n      version = null\n    },\n    /**\n     * Load the persisted checkpoint and sync the local version. Returns the\n     * raw checkpoint (or `null`), so callers can rehydrate their own state\n     * (e.g. a process manager reloading its folded state) from it.\n     */\n    async load() {\n      const checkpoint = await params.get(params.type, params.name)\n      version = checkpoint?.version ?? null\n      return checkpoint ?? null\n    },\n    /**\n     * Persist the checkpoint position (and optional metadata) for the given\n     * event.\n     *\n     * - `'cas'` (compare-and-swap): the write must land on top of the exact\n     *   version we last observed. If another writer advanced the checkpoint,\n     *   the local version is refreshed and a {@link CheckpointConcurrencyError}\n     *   is thrown so the caller can re-fold its state and retry. Used for\n     *   process managers that fold state into the checkpoint.\n     * - `'monotonic'` (default): retries on conflict, skipping the write once\n     *   the stored position already covers this event. Safe for cursors with\n     *   no derived state (projections, stateless/after-effect writes).\n     */\n    async upsert(\n      event: BaseOutputEvent,\n      metadata: Record<string, any> = {},\n      mode: 'cas' | 'monotonic' = 'monotonic',\n    ) {\n      while (true) {\n        const expectedVersion = version\n        const nextVersion = (expectedVersion ?? -1) + 1\n        const committed = await params.upsert(\n          {\n            lastEventPosition: event.position,\n            type: params.type,\n            name: params.name,\n            metadata,\n            version: nextVersion,\n          },\n          expectedVersion,\n        )\n\n        if (committed) {\n          version = nextVersion\n          return\n        }\n\n        // Another writer advanced this checkpoint. Refresh our view of it.\n        const current = await api.load()\n\n        if (mode === 'cas') {\n          throw new CheckpointConcurrencyError(\n            params.type,\n            params.name,\n            expectedVersion,\n          )\n        }\n\n        // monotonic: the stored cursor already covers this event, nothing to do.\n        if (current && current.lastEventPosition >= event.position) {\n          return\n        }\n      }\n    },\n    async rehydrated(\n      options: {\n        onMetadata?: (metadata: Record<string, any>) => unknown\n        getMetadata?: () => Record<string, any>\n        onProgress?: (index: number, event: BaseOutputEvent) => void\n      } = {},\n    ) {\n      const checkpoint = await api.load()\n      let startPosition = 0\n      if (checkpoint) {\n        const result = checkpointSchema.safeParse(checkpoint)\n        if (!result.success) {\n          throw new ValidationError(\n            `loaded checkpoint for ${params.type} ${params.name} does not comply with schema`,\n            result.error,\n          )\n        }\n        startPosition = checkpoint.lastEventPosition + 1\n        options.onMetadata?.(checkpoint.metadata)\n      }\n\n      const events = params.loadEvents(params.relatedStreamEvents, {\n        from: startPosition,\n      })\n\n      let index = 0\n      let lastEvent: BaseOutputEvent | null = null\n      for await (const event of events) {\n        lastEvent = event\n        await params.apply(event)\n        index++\n        options.onProgress?.(index, event)\n      }\n\n      if (!lastEvent) {\n        return // up to date\n      }\n\n      if (params.applyAfter) {\n        for await (const event of events) {\n          await params.applyAfter(event)\n        }\n      }\n\n      await api.upsert(lastEvent, options.getMetadata?.())\n    },\n  }\n\n  return api\n}\n\nexport type CheckpointApi = ReturnType<typeof createCheckpointApi>\n"
-  ],
-  "mappings": ";;;;;;AAAA;AAUA,IAAM,mBAAmB,EAAE,OAAO;AAAA,EAChC,mBAAmB,EAAE,IAAI;AAAA,EACzB,MAAM,EAAE,KAAK,CAAC,cAAc,gBAAgB,CAAC;AAAA,EAC7C,MAAM,EAAE,OAAO;AAAA,EACf,UAAU,EAAE,OAAO,EAAE,OAAO,GAAG,EAAE,IAAI,CAAC;AAAA,EACtC,SAAS,EAAE,IAAI;AACjB,CAAC;AA4BM,SAAS,mBAAmB,CACjC,QAQA;AAAA,EAKA,IAAI,UAAyB;AAAA,EAE7B,MAAM,MAAM;AAAA,IACV,qBAAqB,OAAO;AAAA,SACtB,MAAK,GAAG;AAAA,MACZ,MAAM,OAAO,OAAO,OAAO,MAAM,OAAO,IAAI;AAAA,MAC5C,UAAU;AAAA;AAAA,SAON,KAAI,GAAG;AAAA,MACX,MAAM,aAAa,MAAM,OAAO,IAAI,OAAO,MAAM,OAAO,IAAI;AAAA,MAC5D,UAAU,YAAY,WAAW;AAAA,MACjC,OAAO,cAAc;AAAA;AAAA,SAejB,OAAM,CACV,OACA,WAAgC,CAAC,GACjC,OAA4B,aAC5B;AAAA,MACA,OAAO,MAAM;AAAA,QACX,MAAM,kBAAkB;AAAA,QACxB,MAAM,eAAe,mBAAmB,MAAM;AAAA,QAC9C,MAAM,YAAY,MAAM,OAAO,OAC7B;AAAA,UACE,mBAAmB,MAAM;AAAA,UACzB,MAAM,OAAO;AAAA,UACb,MAAM,OAAO;AAAA,UACb;AAAA,UACA,SAAS;AAAA,QACX,GACA,eACF;AAAA,QAEA,IAAI,WAAW;AAAA,UACb,UAAU;AAAA,UACV;AAAA,QACF;AAAA,QAGA,MAAM,UAAU,MAAM,IAAI,KAAK;AAAA,QAE/B,IAAI,SAAS,OAAO;AAAA,UAClB,MAAM,IAAI,2BACR,OAAO,MACP,OAAO,MACP,eACF;AAAA,QACF;AAAA,QAGA,IAAI,WAAW,QAAQ,qBAAqB,MAAM,UAAU;AAAA,UAC1D;AAAA,QACF;AAAA,MACF;AAAA;AAAA,SAEI,WAAU,CACd,UAII,CAAC,GACL;AAAA,MACA,MAAM,aAAa,MAAM,IAAI,KAAK;AAAA,MAClC,IAAI,gBAAgB;AAAA,MACpB,IAAI,YAAY;AAAA,QACd,MAAM,SAAS,iBAAiB,UAAU,UAAU;AAAA,QACpD,IAAI,CAAC,OAAO,SAAS;AAAA,UACnB,MAAM,IAAI,gBACR,yBAAyB,OAAO,QAAQ,OAAO,oCAC/C,OAAO,KACT;AAAA,QACF;AAAA,QACA,gBAAgB,WAAW,oBAAoB;AAAA,QAC/C,QAAQ,aAAa,WAAW,QAAQ;AAAA,MAC1C;AAAA,MAEA,MAAM,SAAS,OAAO,WAAW,OAAO,qBAAqB;AAAA,QAC3D,MAAM;AAAA,MACR,CAAC;AAAA,MAED,IAAI,QAAQ;AAAA,MACZ,IAAI,YAAoC;AAAA,MACxC,iBAAiB,SAAS,QAAQ;AAAA,QAChC,YAAY;AAAA,QACZ,MAAM,OAAO,MAAM,KAAK;AAAA,QACxB;AAAA,QACA,QAAQ,aAAa,OAAO,KAAK;AAAA,MACnC;AAAA,MAEA,IAAI,CAAC,WAAW;AAAA,QACd;AAAA,MACF;AAAA,MAEA,IAAI,OAAO,YAAY;AAAA,QACrB,iBAAiB,SAAS,QAAQ;AAAA,UAChC,MAAM,OAAO,WAAW,KAAK;AAAA,QAC/B;AAAA,MACF;AAAA,MAEA,MAAM,IAAI,OAAO,WAAW,QAAQ,cAAc,CAAC;AAAA;AAAA,EAEvD;AAAA,EAEA,OAAO;AAAA;",
-  "debugId": "E7ED2588EB8CF7CA64756E2164756E21",
-  "names": []
-}