@kronos-ts/eventsourcing 0.1.0

package/src/in-memory-event-store.ts

@@ -0,0 +1,268 @@
+import type { EventMessage, EventCriteria, TagCriteria, TypeRestrictedCriteria, EitherCriteria, MessageStream, SequencedEvent, StreamingCondition, TrackingToken } from "@kronos-ts/messaging"
+import { createMessageStream, globalSequenceToken, FIRST_TOKEN } from "@kronos-ts/messaging"
+import { qualifiedNameToString } from "@kronos-ts/common"
+import type { EventStore, SourcingResult } from "./event-store.js"
+import type { AppendTransaction } from "./event-storage-engine.js"
+import type { AppendCondition } from "./append-condition.js"
+import type { SourcingCondition } from "./sourcing-condition.js"
+import { markerAt } from "./consistency-marker.js"
+import type { ConsistencyMarker } from "./consistency-marker.js"
+
+/**
+ * In-memory event store for testing and standalone usage.
+ * Events are stored in an ordered array with a global sequence position.
+ * Supports push-based streaming via open().
+ */
+export function createInMemoryEventStore(): EventStore {
+  const events: Array<{ position: bigint; event: EventMessage }> = []
+  let nextPosition = 0n
+
+  // Registered stream listeners — notified when events are appended
+  const streamListeners = new Set<() => void>()
+
+  // Push-based subscribers — notified with actual events on append
+  const eventSubscribers = new Set<(events: ReadonlyArray<EventMessage>) => Promise<void>>()
+
+  function matchesCriteria(event: EventMessage, criteria: EventCriteria): boolean {
+    switch (criteria.kind) {
+      case "tags":
+        return matchesTags(event, criteria)
+      case "any-tag":
+        return event.tags.length > 0
+      case "type-restricted":
+        return matchesTypeRestricted(event, criteria)
+      case "either":
+        return matchesEither(event, criteria)
+    }
+  }
+
+  function matchesTags(event: EventMessage, criteria: TagCriteria): boolean {
+    return criteria.tags.every((requiredTag) =>
+      event.tags.some(
+        (eventTag) =>
+          eventTag.key === requiredTag.key && eventTag.value === requiredTag.value,
+      ),
+    )
+  }
+
+  function matchesTypeRestricted(event: EventMessage, criteria: TypeRestrictedCriteria): boolean {
+    if (!matchesCriteria(event, criteria.inner)) return false
+    const eventType = qualifiedNameToString(event.name)
+    return criteria.types.includes(eventType)
+  }
+
+  function matchesEither(event: EventMessage, criteria: EitherCriteria): boolean {
+    return criteria.criteria.some((c) => matchesCriteria(event, c))
+  }
+
+  function notifyListeners() {
+    for (const listener of streamListeners) {
+      try { listener() } catch { /* ignore */ }
+    }
+  }
+
+  return {
+    async source(condition: SourcingCondition): Promise<SourcingResult> {
+      const start = condition.start ?? 0n
+      const matching = events
+        .filter((entry) => entry.position >= start)
+        .filter((entry) => matchesCriteria(entry.event, condition.criteria))
+
+      const lastPosition = matching.length > 0
+        ? matching[matching.length - 1]!.position
+        : start > 0n ? start - 1n : -1n
+
+      const globalMarker = events.length > 0
+        ? events[events.length - 1]!.position
+        : -1n
+
+      return {
+        events: matching.map((e) => e.event),
+        marker: markerAt(globalMarker),
+      }
+    },
+
+    async appendEvents(
+      newEvents: ReadonlyArray<EventMessage>,
+      condition?: AppendCondition,
+    ): Promise<AppendTransaction> {
+      if (condition) {
+        const conflicting = events
+          .filter((entry) => entry.position > condition.marker.position)
+          .filter((entry) => matchesCriteria(entry.event, condition.criteria))
+
+        if (conflicting.length > 0) {
+          throw new AppendConditionError(
+            `Append condition violated: ${conflicting.length} conflicting event(s) ` +
+            `found after position ${condition.marker.position}`,
+          )
+        }
+      }
+
+      // Stage events — they're added to the store but we track the range
+      const startPosition = nextPosition
+      for (const event of newEvents) {
+        events.push({ position: nextPosition, event })
+        nextPosition++
+      }
+      const endPosition = nextPosition - 1n
+      let committed = false
+
+      return {
+        async commit() {
+          committed = true
+          // Events are already in the array — notify listeners
+          notifyListeners()
+          for (const subscriber of eventSubscribers) {
+            try { await subscriber(newEvents) } catch { /* ignore */ }
+          }
+        },
+        async afterCommit() {
+          return markerAt(endPosition)
+        },
+        rollback() {
+          if (!committed) {
+            // Remove staged events
+            while (events.length > 0 && events[events.length - 1]!.position >= startPosition) {
+              events.pop()
+            }
+            nextPosition = startPosition
+          }
+        },
+      }
+    },
+
+    async append(
+      newEvents: ReadonlyArray<EventMessage>,
+      condition?: AppendCondition,
+    ): Promise<ConsistencyMarker> {
+      if (condition) {
+        const conflicting = events
+          .filter((entry) => entry.position > condition.marker.position)
+          .filter((entry) => matchesCriteria(entry.event, condition.criteria))
+
+        if (conflicting.length > 0) {
+          throw new AppendConditionError(
+            `Append condition violated: ${conflicting.length} conflicting event(s) ` +
+            `found after position ${condition.marker.position}`,
+          )
+        }
+      }
+
+      for (const event of newEvents) {
+        events.push({ position: nextPosition, event })
+        nextPosition++
+      }
+
+      // Notify open streams that new events are available
+      notifyListeners()
+
+      // Notify push-based subscribers with the actual events
+      for (const subscriber of eventSubscribers) {
+        try { await subscriber(newEvents) } catch { /* ignore subscriber errors */ }
+      }
+
+      return markerAt(nextPosition - 1n)
+    },
+
+    open(condition: StreamingCondition): MessageStream<SequencedEvent> {
+      let cursor = condition.position
+      const criteria = condition.criteria
+      let availableCallback: (() => void) | null = null
+      let closed = false
+
+      const listener = () => {
+        if (!closed && availableCallback) {
+          availableCallback()
+        }
+      }
+
+      streamListeners.add(listener)
+
+      function findNext(): SequencedEvent | undefined {
+        if (closed) return undefined
+        for (const entry of events) {
+          if (entry.position < cursor) continue
+          if (criteria && !matchesCriteria(entry.event, criteria)) continue
+          return { sequence: entry.position, event: entry.event }
+        }
+        return undefined
+      }
+
+      return createMessageStream<SequencedEvent>({
+        next() {
+          const item = findNext()
+          if (item) {
+            cursor = item.sequence + 1n
+          }
+          return item
+        },
+
+        peek() {
+          return findNext()
+        },
+
+        hasNextAvailable() {
+          return findNext() !== undefined
+        },
+
+        setCallback(callback: () => void) {
+          availableCallback = callback
+        },
+
+        isCompleted() {
+          return closed
+        },
+
+        error() {
+          return undefined // In-memory store never errors
+        },
+
+        close() {
+          closed = true
+          availableCallback = null
+          streamListeners.delete(listener)
+        },
+      })
+    },
+
+    async getHeadPosition(): Promise<bigint> {
+      return nextPosition
+    },
+
+    async firstToken(): Promise<TrackingToken> {
+      return FIRST_TOKEN
+    },
+
+    async latestToken(): Promise<TrackingToken> {
+      return globalSequenceToken(nextPosition)
+    },
+
+    async publish(publishedEvents: ReadonlyArray<EventMessage>): Promise<void> {
+      // In the in-memory store, publish = append without condition
+      for (const event of publishedEvents) {
+        events.push({ position: nextPosition, event })
+        nextPosition++
+      }
+      notifyListeners()
+      for (const subscriber of eventSubscribers) {
+        try { await subscriber(publishedEvents) } catch { /* ignore */ }
+      }
+    },
+
+    subscribe(handler: (events: ReadonlyArray<EventMessage>) => Promise<void>): () => void {
+      eventSubscribers.add(handler)
+      return () => { eventSubscribers.delete(handler) }
+    },
+  }
+}
+
+/**
+ * Thrown when an append condition is violated — optimistic concurrency failure.
+ */
+export class AppendConditionError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = "AppendConditionError"
+  }
+}

package/src/index.ts

@@ -0,0 +1,73 @@
+export {
+  type ConsistencyMarker,
+  ORIGIN,
+  INFINITY,
+  MARKER_RESOURCE_KEY,
+  noMarker,
+  markerAt,
+  markerLowerBound,
+  markerUpperBound,
+} from "./consistency-marker.js"
+
+export {
+  type SourcingCondition,
+  sourcingCondition,
+} from "./sourcing-condition.js"
+
+export {
+  type AppendCondition,
+  appendCondition,
+} from "./append-condition.js"
+
+export {
+  type EventStore,
+  type SourcingResult,
+} from "./event-store.js"
+
+export {
+  type EventStoreTransaction,
+  createEventStoreTransaction,
+} from "./event-store-transaction.js"
+
+export {
+  createInMemoryEventStore,
+  AppendConditionError,
+} from "./in-memory-event-store.js"
+
+export { type EventStorageEngine, type AppendTransaction } from "./event-storage-engine.js"
+
+export {
+  type TagResolver,
+  descriptorBasedTagResolver,
+  metadataBasedTagResolver,
+  multiTagResolver,
+} from "./tag-resolver.js"
+
+export { createEventSourcedRepository } from "./event-sourced-repository.js"
+export type { EventSourcedRepositoryOptions } from "./event-sourced-repository.js"
+
+export {
+  type SnapshotPolicy,
+  type EvolutionResult,
+  afterEvents,
+  whenSourcingTimeExceeds,
+  noSnapshotPolicy,
+} from "./snapshot-policy.js"
+
+export {
+  type Snapshot,
+  type SnapshotStore,
+  createInMemorySnapshotStore,
+} from "./snapshot-store.js"
+
+export { createInterceptingEventStore } from "./intercepting-event-store.js"
+
+// Module-level handler helpers (Plan 04-01 / HDL-02 / D-42)
+export { load, STATE_MANAGER_KEY } from "./load.js"
+export {
+  append,
+  BUFFERED_EVENTS_KEY,
+  SOURCING_INFOS_KEY,
+  STATE_CACHE_KEY,
+  STATE_MODULES_KEY,
+} from "./append.js"

package/src/intercepting-event-store.ts

@@ -0,0 +1,70 @@
+import type { EventMessage, DispatchInterceptor, StreamingCondition, MessageStream, SequencedEvent } from "@kronos-ts/messaging"
+import type { EventStore } from "./event-store.js"
+import type { AppendTransaction } from "./event-storage-engine.js"
+import type { AppendCondition } from "./append-condition.js"
+import type { ConsistencyMarker } from "./consistency-marker.js"
+import type { SourcingCondition } from "./sourcing-condition.js"
+import type { SourcingResult } from "./event-store.js"
+
+/**
+ * An {@link EventStore} decorator that applies dispatch interceptors
+ * before events are appended or published.
+ *
+ * Read operations (source, open, getHeadPosition) pass through to
+ * the delegate without interception.
+ */
+export function createInterceptingEventStore(
+  delegate: EventStore,
+  dispatchInterceptors: ReadonlyArray<DispatchInterceptor<EventMessage>>,
+): EventStore {
+  async function interceptEvents(
+    events: ReadonlyArray<EventMessage>,
+  ): Promise<EventMessage[]> {
+    const intercepted: EventMessage[] = []
+    for (const event of events) {
+      let msg = event
+      for (const interceptor of dispatchInterceptors) {
+        msg = await interceptor(msg) as EventMessage
+      }
+      intercepted.push(msg)
+    }
+    return intercepted
+  }
+
+  return {
+    // Read operations pass through
+    source(condition: SourcingCondition): Promise<SourcingResult> {
+      return delegate.source(condition)
+    },
+
+    // AppendEvents intercepts events before storage
+    async appendEvents(
+      events: ReadonlyArray<EventMessage>,
+      condition?: AppendCondition,
+    ): Promise<AppendTransaction> {
+      const intercepted = await interceptEvents(events)
+      return delegate.appendEvents(intercepted, condition)
+    },
+
+    async append(
+      events: ReadonlyArray<EventMessage>,
+      condition?: AppendCondition,
+    ): Promise<ConsistencyMarker> {
+      const intercepted = await interceptEvents(events)
+      return delegate.append(intercepted, condition)
+    },
+
+    // Publish intercepts events before distribution
+    async publish(events: ReadonlyArray<EventMessage>): Promise<void> {
+      const intercepted = await interceptEvents(events)
+      return delegate.publish(intercepted)
+    },
+
+    // Stream/read pass through
+    open: (condition: StreamingCondition) => delegate.open(condition),
+    getHeadPosition: () => delegate.getHeadPosition(),
+    firstToken: () => delegate.firstToken(),
+    latestToken: () => delegate.latestToken(),
+    subscribe: (handler) => delegate.subscribe(handler),
+  }
+}

package/src/load.ts

@@ -0,0 +1,70 @@
+import { resourceKey, type ResourceKey } from "@kronos-ts/common"
+import {
+  processingStateStorage,
+  computeIfAbsent,
+  NoActiveUnitOfWork,
+} from "@kronos-ts/messaging/processing-state"
+import type { EventCriteria } from "@kronos-ts/messaging"
+import { STATE_CACHE_KEY, STATE_MODULES_KEY, SOURCING_INFOS_KEY } from "./append.js"
+
+/**
+ * Load event-sourced state for a module within the active unit of work.
+ *
+ * The first signature matches a `StateModule`-shaped object structurally
+ * (without importing `@kronos-ts/modelling`, which would invert the
+ * dependency direction) so both the id and state types are inferred.
+ */
+export interface LoadFunction {
+  <Id, S>(module: { kind: "state-module"; name: string; create: (id: Id) => S }, id: Id): Promise<S>
+  <S>(module: { name: string }, id: unknown): Promise<S>
+}
+
+// ---------------------------------------------------------------------------
+// State manager interface — minimal shape needed by load
+// ---------------------------------------------------------------------------
+
+type StateManagerLike = {
+  load: (
+    module: any,
+    id: any,
+  ) => Promise<{
+    state: any
+    sourcingInfo: { criteria: EventCriteria; markerPosition: bigint }
+  }>
+}
+
+/**
+ * Resource key for the state manager component.
+ * Written by handling modules + processors at handler-invocation entry (D-44).
+ */
+export const STATE_MANAGER_KEY: ResourceKey<StateManagerLike> = resourceKey("stateManager")
+
+/**
+ * Plan 04-01 (HDL-02 / D-42): module-level load.
+ *
+ * Read-only — NOT phase-guarded per D-43. Throws NoActiveUnitOfWork outside
+ * a UoW. Caches state within the UoW (duplicate load() calls for the
+ * same module-id pair return the cached promise without re-querying the store).
+ */
+export const load: LoadFunction = (async <S>(module: { name: string }, id: unknown): Promise<S> => {
+  const state = processingStateStorage.getStore()
+  if (state === undefined) throw new NoActiveUnitOfWork()
+  const stateManager = state.resources.get(STATE_MANAGER_KEY.symbol) as StateManagerLike | undefined
+  if (!stateManager) throw new Error("No state manager configured")
+
+  const cache = computeIfAbsent(STATE_CACHE_KEY, () => new Map())
+  const cacheKey = `${module.name}:${String(id)}`
+  if (!cache.has(cacheKey)) {
+    cache.set(cacheKey, stateManager.load(module, id))
+    const modules = computeIfAbsent(STATE_MODULES_KEY, () => new Map())
+    modules.set(cacheKey, { module, id })
+  }
+  const result = await cache.get(cacheKey)!
+  const loadResult = result as {
+    state: any
+    sourcingInfo: { criteria: EventCriteria; markerPosition: bigint }
+  }
+  const infos = computeIfAbsent(SOURCING_INFOS_KEY, () => [])
+  infos.push(loadResult.sourcingInfo)
+  return loadResult.state as S
+}) as LoadFunction

package/src/snapshot-policy.ts

@@ -0,0 +1,73 @@
+/**
+ * Metrics collected during state evolution (event sourcing).
+ * Used by snapshot policies to decide if a new snapshot should be created.
+ *
+ */
+export interface EvolutionResult {
+  /** Number of events applied to reach the current state. */
+  readonly eventsApplied: number
+  /** Time spent sourcing in milliseconds. */
+  readonly sourcingTimeMs: number
+}
+
+/**
+ * Determines when snapshots should be created for a state.
+ *
+ * Policies are composable via `or()` — if any policy triggers,
+ * a snapshot is created.
+ *
+ */
+export interface SnapshotPolicy {
+  /**
+   * Whether a snapshot should be created based on the evolution result.
+   */
+  shouldSnapshot(result: EvolutionResult): boolean
+
+  /**
+   * Combine this policy with another. The combined policy triggers
+   * if either policy triggers.
+   */
+  or(other: SnapshotPolicy): SnapshotPolicy
+}
+
+/**
+ * Creates a snapshot policy that triggers after N events have been applied.
+ *
+ */
+export function afterEvents(threshold: number): SnapshotPolicy {
+  return createPolicy((result) => result.eventsApplied > threshold)
+}
+
+/**
+ * Creates a snapshot policy that triggers when sourcing time exceeds
+ * the given threshold in milliseconds.
+ *
+ */
+export function whenSourcingTimeExceeds(thresholdMs: number): SnapshotPolicy {
+  return createPolicy((result) => result.sourcingTimeMs >= thresholdMs)
+}
+
+/**
+ * A policy that never triggers. No snapshots will be created.
+ */
+export function noSnapshotPolicy(): SnapshotPolicy {
+  return createPolicy(() => false)
+}
+
+// ---------------------------------------------------------------------------
+// Internal helper
+// ---------------------------------------------------------------------------
+
+function createPolicy(
+  predicate: (result: EvolutionResult) => boolean,
+): SnapshotPolicy {
+  const policy: SnapshotPolicy = {
+    shouldSnapshot: predicate,
+    or(other: SnapshotPolicy): SnapshotPolicy {
+      return createPolicy(
+        (result) => predicate(result) || other.shouldSnapshot(result),
+      )
+    },
+  }
+  return policy
+}

package/src/snapshot-store.ts

@@ -0,0 +1,67 @@
+/**
+ * A point-in-time capture of a state value.
+ *
+ */
+export interface Snapshot {
+  /** The global position in the event stream at snapshot time. */
+  readonly position: bigint
+  /** The serialized state. */
+  readonly payload: unknown
+  /** When the snapshot was created (epoch ms). */
+  readonly timestamp: number
+  /** Optional metadata associated with the snapshot. */
+  readonly metadata: Record<string, string>
+}
+
+/**
+ * Stores and retrieves state snapshots.
+ *
+ * Separate from the event store — snapshots are an optimization, not
+ * part of the event stream.
+ *
+ */
+export interface SnapshotStore {
+  /**
+   * Store a snapshot for a state value.
+   * Replaces any existing snapshot for the same state and id.
+   */
+  store(stateName: string, id: unknown, snapshot: Snapshot): Promise<void>
+
+  /**
+   * Load the most recent snapshot for a state value.
+   * Returns undefined if no snapshot exists.
+   */
+  load(stateName: string, id: unknown): Promise<Snapshot | undefined>
+
+  /**
+   * Delete all snapshots for a state value.
+   */
+  deleteSnapshots(stateName: string, id: unknown): Promise<void>
+}
+
+/**
+ * In-memory snapshot store for testing and standalone usage.
+ */
+export function createInMemorySnapshotStore(): SnapshotStore {
+  // Key: "stateName:id"
+  const snapshots = new Map<string, Snapshot>()
+
+  function key(stateName: string, id: unknown): string {
+    const idStr = typeof id === "object" && id !== null ? JSON.stringify(id) : String(id)
+    return `${stateName}:${idStr}`
+  }
+
+  return {
+    async store(stateName, id, snapshot) {
+      snapshots.set(key(stateName, id), snapshot)
+    },
+
+    async load(stateName, id) {
+      return snapshots.get(key(stateName, id))
+    },
+
+    async deleteSnapshots(stateName, id) {
+      snapshots.delete(key(stateName, id))
+    },
+  }
+}

package/src/sourcing-condition.ts

@@ -0,0 +1,17 @@
+import type { EventCriteria } from "@kronos-ts/messaging"
+
+/**
+ * Defines which events to source from the event store.
+ * Combines criteria (what to match) with an optional start position.
+ */
+export interface SourcingCondition {
+  readonly criteria: EventCriteria
+  readonly start?: bigint
+}
+
+/**
+ * Create a sourcing condition from criteria and an optional start position.
+ */
+export function sourcingCondition(criteria: EventCriteria, start?: bigint): SourcingCondition {
+  return start !== undefined ? { criteria, start } : { criteria }
+}

package/src/tag-resolver.ts

@@ -0,0 +1,62 @@
+import type { Tag } from "@kronos-ts/common"
+import type { EventMessage } from "@kronos-ts/messaging"
+
+/**
+ * Resolves tags from an event message. Tags are metadata markers attached
+ * to events for filtering, categorization, and criteria-based sourcing.
+ *
+ * By default, tags are derived from the event descriptor's `tags` function
+ * at event creation time. The TagResolver runs before storage and can enrich
+ * events with additional tags from metadata, context, etc.
+ */
+export interface TagResolver {
+  resolve(event: EventMessage): Tag[]
+}
+
+/**
+ * Default tag resolver — passes through tags already on the event.
+ *
+ * Events are created with descriptor-derived tags. This resolver simply
+ * returns those existing tags unchanged.
+ */
+export function descriptorBasedTagResolver(): TagResolver {
+  return {
+    resolve(event: EventMessage): Tag[] {
+      return [...event.tags]
+    },
+  }
+}
+
+/**
+ * Resolves additional tags from event metadata. For each configured key,
+ * if the metadata contains that key, a tag is created.
+ */
+export function metadataBasedTagResolver(...metadataKeys: string[]): TagResolver {
+  return {
+    resolve(event: EventMessage): Tag[] {
+      const tags: Tag[] = []
+      for (const key of metadataKeys) {
+        const value = event.metadata[key]
+        if (value != null) {
+          tags.push({ key, value: String(value) })
+        }
+      }
+      return tags
+    },
+  }
+}
+
+/**
+ * Combines multiple tag resolvers. Tags from all resolvers are merged.
+ */
+export function multiTagResolver(...resolvers: TagResolver[]): TagResolver {
+  return {
+    resolve(event: EventMessage): Tag[] {
+      const tags: Tag[] = []
+      for (const resolver of resolvers) {
+        tags.push(...resolver.resolve(event))
+      }
+      return tags
+    },
+  }
+}