@requence/event-sourcing 0.0.1 → 1.0.0

package/src/lock.ts

@@ -0,0 +1,58 @@
+import { Mutex } from 'async-mutex'
+
+export default function lock(defaultTtl = 5000) {
+  const locks = new Map<string, Mutex>()
+  return async (key: string | string[]) => {
+    const k = Array.isArray(key) ? key.join(':') : key
+    if (!locks.has(k)) {
+      locks.set(k, new Mutex())
+    }
+
+    const mutex = locks.get(k)!
+
+    const releaseMutex = await mutex.acquire()
+    let isReleased = false
+
+    let timer: ReturnType<typeof setTimeout>
+    const startTimer = (ttl: number) => {
+      timer = setTimeout(() => {
+        if (!isReleased) {
+          console.warn('lock ttl expired for key', k)
+          isReleased = true
+          releaseMutex()
+          if (!mutex.isLocked()) {
+            locks.delete(k)
+          }
+        }
+      }, ttl)
+    }
+
+    startTimer(defaultTtl)
+
+    return {
+      async extend(ttl?: number) {
+        if (isReleased) {
+          return false
+        }
+        clearTimeout(timer)
+        startTimer(ttl ?? defaultTtl / 2)
+        return true
+      },
+      async release() {
+        if (isReleased) {
+          return
+        }
+
+        isReleased = true
+        clearTimeout(timer)
+        releaseMutex()
+
+        if (!mutex.isLocked()) {
+          locks.delete(k)
+        }
+      },
+    }
+  }
+}
+
+export type LockCreator = ReturnType<typeof lock>

package/src/memory/index.ts

@@ -0,0 +1,224 @@
+import type { AnyAggregateRoot } from '../createAggregateRoot.ts'
+import type { Checkpoint } from '../createCheckpointApi.ts'
+import {
+  type AggregateRootSnapshot,
+  ConcurrencyError,
+  type Event,
+  type ProjectionSnapshot,
+  createEventStore as createBaseEventStore,
+  isStreamEvents,
+  isStreamId,
+} from '../index.ts'
+import type {
+  EventStore,
+  EventStoreParamsWithAggregateRootSnapshots,
+  EventsFromRoot,
+  OnProgress,
+} from '../createEventStore.ts'
+import type { BaseOutputEvent, MaybePromise } from '../utilityTypes.js'
+
+export { createAggregateRoot } from '../index.ts'
+
+export type OnEventsAppended = (
+  events: BaseOutputEvent[],
+) => MaybePromise<void>
+
+interface MemoryEventStoreParams<Root extends AnyAggregateRoot> {
+  aggregateRoots: Root[]
+  autoInit?: boolean
+  postProcessEvent?: EventStoreParamsWithAggregateRootSnapshots<Root>['postProcessEvent']
+  onProjectionReplay?: OnProgress
+  onProcessManagerRefresh?: OnProgress
+  onEventsAppended?: OnEventsAppended
+}
+
+export function createEventStore<const Root extends AnyAggregateRoot>({
+  aggregateRoots,
+  postProcessEvent,
+  onProjectionReplay,
+  onProcessManagerRefresh,
+  onEventsAppended,
+  autoInit,
+}: MemoryEventStoreParams<Root>): EventStore<
+  EventsFromRoot<Root>,
+  Root,
+  true
+> {
+  const events: Event[] = []
+  const checkpoints = new Set<Checkpoint>()
+  const aggregateRootSnapshots = new Map<string, AggregateRootSnapshot>()
+  const projectionSnapshots = new Set<ProjectionSnapshot>()
+  const projectionAppliedCount = new Map<string, number>()
+
+  return createBaseEventStore({
+    aggregateRoots,
+    postProcessEvent,
+    onProjectionReplay,
+    onProcessManagerRefresh,
+    autoInit,
+
+    async *loadEvents(select, range) {
+      let streamTypes: string[] | null = null
+      let streamIds: string[] | null = null
+      let eventTypes: string[] | null = null
+
+      if (select) {
+        const selects = Array.isArray(select) ? select : [select]
+        streamTypes = selects.map((select) => select.stream)
+        streamIds = selects
+          .map((select) => (isStreamId(select) ? select.id : null))
+          .filter(Boolean) as string[]
+        eventTypes = selects.flatMap((select) =>
+          isStreamEvents(select) ? select.events : [],
+        )
+      }
+
+      const filteredEvents = events.filter((event) => {
+        if (streamTypes?.length && !streamTypes.includes(event.streamType)) {
+          return false
+        }
+
+        if (streamIds?.length && !streamIds.includes(event.streamId)) {
+          return false
+        }
+
+        if (eventTypes?.length && !eventTypes.includes(event.type)) {
+          return false
+        }
+
+        if (range?.from && event.position < range.from) {
+          return false
+        }
+
+        if (range?.to && event.position > range.to) {
+          return false
+        }
+
+        return true
+      })
+
+      for (const event of filteredEvents) {
+        yield event
+      }
+    },
+
+    appendEvents({ id, stream }, newEvents, expectedVersion) {
+      const lastEvent = events.findLast(
+        (e) => e.streamId === id && e.streamType === stream,
+      )
+
+      const currentVersion = lastEvent?.streamVersion ?? 0
+
+      if (currentVersion !== expectedVersion) {
+        throw new ConcurrencyError(
+          { id, stream },
+          expectedVersion,
+          currentVersion,
+        )
+      }
+
+      const extendedEvents: Event[] = newEvents.map((event, index) => ({
+        ...event,
+        createdAt: new Date(),
+        position: events.length + index,
+        streamId: id,
+        streamType: stream,
+        streamVersion: expectedVersion + index + 1,
+      }))
+
+      events.push(...extendedEvents)
+      onEventsAppended?.(extendedEvents)
+      return extendedEvents
+    },
+
+    checkpoint: {
+      get(type, name) {
+        for (const checkpoint of checkpoints) {
+          if (checkpoint.type === type && checkpoint.name === name) {
+            return checkpoint
+          }
+        }
+      },
+      upsert(checkpoint) {
+        let persisted: Checkpoint | undefined
+        for (const c of checkpoints) {
+          if (c.type === checkpoint.type && c.name === checkpoint.name) {
+            persisted = c
+            break
+          }
+        }
+
+        if (persisted) {
+          persisted.lastEventPosition = checkpoint.lastEventPosition
+          persisted.metadata = checkpoint.metadata
+        } else {
+          checkpoints.add(checkpoint)
+        }
+      },
+      delete(type, name) {
+        for (const checkpoint of checkpoints) {
+          if (checkpoint.type === type && checkpoint.name === name) {
+            checkpoints.delete(checkpoint)
+          }
+        }
+      },
+    },
+
+    projectionSnapshot: {
+      put(snapshot) {
+        projectionSnapshots.add(snapshot)
+      },
+      get(select) {
+        return Array.from(projectionSnapshots)
+          .toReversed()
+          .find(
+            (snapshot) =>
+              snapshot.projectionId === select.id &&
+              snapshot.projectionType === select.projection,
+          )
+      },
+      delete(target, fromPosition) {
+        for (const snapshot of projectionSnapshots) {
+          if (target.id && snapshot.projectionId !== target.id) {
+            continue
+          }
+
+          if (snapshot.projectionType !== target.projection) {
+            continue
+          }
+
+          if (fromPosition && snapshot.lastEventPosition < fromPosition) {
+            continue
+          }
+
+          projectionSnapshots.delete(snapshot)
+        }
+      },
+      incrementAppliedCount(select) {
+        const key = `${select.projection}-${select.id}`
+        const nextCount = (projectionAppliedCount.get(key) ?? 0) + 1
+        projectionAppliedCount.set(key, nextCount)
+        return nextCount
+      },
+    },
+
+    aggregateRootSnapshot: {
+      put(snapshot) {
+        aggregateRootSnapshots.set(
+          `${snapshot.streamType}:${snapshot.streamId}`,
+          snapshot,
+        )
+      },
+      get(select) {
+        return aggregateRootSnapshots.get(`${select.stream}:${select.id}`)
+      },
+      delete(target, fromStreamVersion) {
+        const key = `${target.stream}:${target.id}`
+        const snapshot = aggregateRootSnapshots.get(key)
+        if (snapshot && snapshot.streamVersion > fromStreamVersion) {
+          aggregateRootSnapshots.delete(key)
+        }
+      },
+    },
+  }) as any
+}

package/src/redis/index.ts

@@ -0,0 +1 @@
+export * from './redisLock.ts'

package/src/redis/redisLock.ts

@@ -0,0 +1,61 @@
+import type { Redis } from 'ioredis'
+
+import type { LockCreator } from '../lock.ts'
+
+const extendScript = `
+  if redis.call("get", KEYS[1]) == ARGV[1] then
+      return redis.call("pexpire", KEYS[1], ARGV[2])
+  else
+      return 0
+  end
+`
+
+const deleteScript = `
+    if redis.call("get", KEYS[1]) == ARGV[1] then
+        return redis.call("del", KEYS[1])
+    else
+        return 0
+    end
+`
+
+export function redisLock(client: Redis, defaultTtl = 5000): LockCreator {
+  return async (rawKey) => {
+    const key = Array.isArray(rawKey) ? rawKey.join(':') : rawKey
+    const token = crypto.randomUUID()
+
+    while (true) {
+      const acquired = await client.set(key, token, 'PX', defaultTtl, 'NX')
+
+      if (acquired !== 'OK') {
+        await new Promise((resolve) => setTimeout(resolve, 100))
+        continue
+      }
+
+      let isReleased = false
+      return {
+        async extend(ttl) {
+          const extended = await client.eval(
+            extendScript,
+            1,
+            key,
+            token,
+            ttl ?? defaultTtl / 2,
+          )
+          if (extended === 0) {
+            isReleased = true
+            return false
+          }
+          return true
+        },
+        async release() {
+          if (isReleased) {
+            return
+          }
+
+          isReleased = true
+          await client.eval(deleteScript, 1, key, token)
+        },
+      }
+    }
+  }
+}

package/src/refresh.ts

@@ -0,0 +1,19 @@
+import { AsyncLocalStorage } from 'node:async_hooks'
+
+import { RefreshingSkipError } from './errors.ts'
+
+const refreshStore = new AsyncLocalStorage<boolean>()
+
+export function isRefreshing() {
+  return refreshStore.getStore() ?? false
+}
+
+export function withRefreshing<T extends () => any>(handler: T) {
+  return refreshStore.run(true, handler)
+}
+
+export function skipRefreshing() {
+  if (isRefreshing()) {
+    throw new RefreshingSkipError()
+  }
+}

package/src/replay.ts

@@ -0,0 +1,19 @@
+import { AsyncLocalStorage } from 'node:async_hooks'
+
+import { ReplaySkipError } from './errors.ts'
+
+const replayStore = new AsyncLocalStorage<boolean>()
+
+export function isReplaying() {
+  return replayStore.getStore() ?? false
+}
+
+export function withReplaying<T extends () => any>(handler: T) {
+  return replayStore.run(true, handler)
+}
+
+export function skipReplay() {
+  if (isReplaying()) {
+    throw new ReplaySkipError()
+  }
+}

package/src/snapshotGenerator.ts

@@ -0,0 +1,190 @@
+import { z } from 'zod/v4'
+
+import { ValidationError } from './errors.ts'
+import type {
+  BaseOutputEvent,
+  Keys,
+  Max,
+  MaybePromise,
+  Merge,
+} from './utilityTypes.js'
+
+type RegisteredSnapshotSchemas = { schemaVersion: number; schema: z.ZodType }
+
+type LatestSnapshotSchemaInput<
+  T extends RegisteredSnapshotSchemas,
+  M = Max<T['schemaVersion']>,
+> = T extends { schemaVersion: M } ? z.input<T['schema']> : never
+
+type OutputSnapshot<T extends RegisteredSnapshotSchemas> = T extends {
+  schemaVersion: infer V
+  schema: infer S
+}
+  ? {
+      schemaVersion: V
+      state: z.output<S>
+      createdAt: Date
+    }
+  : never
+
+type SnapshotApplier<Base, T extends RegisteredSnapshotSchemas> = (
+  snapshot: OutputSnapshot<T> & Base,
+) => MaybePromise<void>
+type SnapshotCapturer<T extends RegisteredSnapshotSchemas> = (
+  event: BaseOutputEvent,
+) => MaybePromise<LatestSnapshotSchemaInput<T> | undefined | null | void>
+
+export type SnapshotGenerator<
+  Base,
+  Schemas extends RegisteredSnapshotSchemas = never,
+  Flags extends {
+    every: boolean
+    apply: boolean
+    capture: boolean
+    schema: boolean
+  } = {
+    every: false
+    apply: true
+    capture: true
+    schema: false
+  },
+> = {
+  every(
+    count: number,
+  ): Omit<
+    SnapshotGenerator<Base, Schemas, Merge<Flags, { every: true }>>,
+    Keys<Merge<Flags, { every: true }>>
+  >
+  schema<Schema extends z.ZodType, V extends number = 0>(
+    schema: Schema,
+    schemaVersion?: V,
+  ): Omit<
+    SnapshotGenerator<
+      Base,
+      Schemas | { schemaVersion: V; schema: Schema },
+      Merge<Flags, { apply: false; capture: false }>
+    >,
+    Keys<Merge<Flags, { apply: false; capture: false }>>
+  >
+  apply(
+    applier: SnapshotApplier<Base, Schemas>,
+  ): Omit<
+    SnapshotGenerator<
+      Base,
+      Schemas,
+      Merge<Flags, { apply: true; schema: true }>
+    >,
+    Keys<Merge<Flags, { apply: true; schema: true }>>
+  >
+  capture(
+    capturer: SnapshotCapturer<Schemas>,
+  ): Omit<
+    SnapshotGenerator<
+      Base,
+      Schemas,
+      Merge<Flags, { capture: true; schema: true }>
+    >,
+    Keys<Merge<Flags, { capture: true; schema: true }>>
+  >
+  readonly complete: Flags['schema'] extends true
+    ? Flags['capture'] extends true
+      ? Flags['apply'] extends true
+        ? true
+        : false
+      : false
+    : false
+}
+
+export type InternalSnapshotGenerator = {
+  internalApply: (snapshot: OutputSnapshot<any>) => Promise<void>
+  internalCapture: (
+    event: BaseOutputEvent,
+    applied: number,
+  ) => Promise<null | { state: any; version: number }>
+}
+
+export type CompleteSnapshotGenerator = Omit<
+  SnapshotGenerator<
+    any,
+    RegisteredSnapshotSchemas,
+    { every: true; apply: true; capture: true; schema: true }
+  >,
+  'schema' | 'capture' | 'apply' | 'every'
+>
+
+export default function createSnapshotGenerator<Base>(
+  schemas: Array<RegisteredSnapshotSchemas> = [],
+  config: { every: number } | null = null,
+  applier:
+    | ((snapshot: OutputSnapshot<any>) => MaybePromise<void>)
+    | null = null,
+  capturer: ((event: BaseOutputEvent) => any) | null = null,
+): CompleteSnapshotGenerator {
+  return {
+    async internalApply(snapshot) {
+      const result = z
+        .union(schemas.map(({ schema }) => schema))
+        .safeParse(snapshot.state)
+
+      if (!result.success) {
+        throw new ValidationError(
+          `loaded snapshot version ${snapshot.schemaVersion} does not comply with registered schema`,
+          result.error,
+        )
+      }
+
+      await applier!(snapshot)
+    },
+    async internalCapture(event, applied) {
+      if (!config || applied % config.every !== 0) {
+        return null
+      }
+
+      const latestSchema = schemas
+        .slice(1)
+        .reduce(
+          (latest, schema) =>
+            schema.schemaVersion > latest.schemaVersion ? schema : latest,
+          schemas[0],
+        )
+
+      const result = latestSchema.schema.safeParse(await capturer!(event))
+
+      if (!result.success) {
+        throw new ValidationError(
+          `generated snapshot does not comply with schema for version ${latestSchema.schemaVersion}`,
+          result.error,
+        )
+      }
+
+      return {
+        state: result.data,
+        version: latestSchema.schemaVersion,
+      }
+    },
+    every(count) {
+      return createSnapshotGenerator(
+        schemas,
+        { every: count },
+        applier,
+        capturer,
+      )
+    },
+    schema(schema, schemaVersion) {
+      schemas.push({ schemaVersion: schemaVersion ?? 0, schema })
+      return createSnapshotGenerator(schemas, config, null, null) as any
+    },
+    apply(applier) {
+      return createSnapshotGenerator(schemas, config, applier as any, capturer)
+    },
+    capture(capturer) {
+      return createSnapshotGenerator(schemas, config, applier, capturer as any)
+    },
+    complete: true,
+  } as SnapshotGenerator<
+    Base,
+    RegisteredSnapshotSchemas,
+    { capture: true; apply: true; every: true; schema: true }
+  > &
+    InternalSnapshotGenerator
+}

package/src/superjson.ts

@@ -0,0 +1,11 @@
+import SuperJSON from 'superjson'
+
+export const superjson = new SuperJSON()
+
+export function extendTypes(handler: (superjson: SuperJSON) => void) {
+  handler(superjson)
+}
+
+export function clone<T>(obj: T): T {
+  return superjson.deserialize(superjson.serialize(obj))
+}