@photon-grove/evt 0.1.1 → 0.2.0

package/src/staging.ts

@@ -0,0 +1,138 @@
+// What a commit of one stream carries beyond its decided events, the same for a single command
+// and for a transaction: the stored events, the snapshot the policy calls for, and the projectors'
+// operations.
+
+import {
+  type Aggregate,
+  type EventDefinitions,
+  type EventOf,
+  type Projection,
+  encodeEventData,
+} from './aggregate.js'
+import {EvtError} from './errors.js'
+import {type SerializedEvent, eventId} from './event.js'
+import type {Metadata} from './metadata.js'
+import type {NewSnapshot, ProjectorGroup} from './repository.js'
+import {MAX_COMMIT_ITEM_BYTES, snapshotCommitSize, snapshotEventsDue} from './snapshots.js'
+
+const INT64_MAX = 2n ** 63n - 1n
+
+/**
+ * Serializes decided events continuing the stream after `after`, each with its own copy of
+ * `metadata`, and then folds them into `state`. Every event is encoded before any is applied, so
+ * when one fails to encode, `state` is untouched, even for an aggregate whose `apply` changes the
+ * state it's given.
+ */
+export function serializeEvents<S, C, D extends EventDefinitions>(
+  aggregate: Aggregate<S, C, D>,
+  entityId: string,
+  after: bigint,
+  state: S,
+  decided: readonly EventOf<D>[],
+  metadata: Metadata,
+): {events: SerializedEvent[]; state: S} {
+  let sequence = after
+  const events: SerializedEvent[] = []
+
+  for (const event of decided) {
+    if (sequence >= INT64_MAX) {
+      throw new EvtError(
+        'invalidCommit',
+        `invalid commit: entity ${entityId} is at the maximum event sequence`,
+      )
+    }
+    sequence++
+
+    const {version, payload} = encodeEventData(aggregate.events, event)
+    events.push({
+      id: eventId(entityId, sequence),
+      sequence,
+      type: event.type,
+      version,
+      entityId,
+      entityType: aggregate.type,
+      payload,
+      metadata: copyMetadata(metadata),
+    })
+  }
+
+  for (const event of decided) {
+    state = aggregate.apply(state, event)
+  }
+
+  return {events, state}
+}
+
+/**
+ * The snapshot a commit of `appended` events after `loadedSequence` carries, or null when the
+ * interval calls for none. A snapshot whose item is over the per-item commit budget is left out
+ * too, since it would fail every commit that carries it.
+ */
+export function commitSnapshot<S, C, D extends EventDefinitions>(
+  aggregate: Aggregate<S, C, D>,
+  entityId: string,
+  interval: number,
+  loaded: {readonly sequence: bigint; readonly snapshotSequence: bigint},
+  appended: number,
+  state: S,
+): NewSnapshot | null {
+  if (snapshotEventsDue(loaded.sequence, appended, interval) === 0) {
+    return null
+  }
+
+  const snapshot: NewSnapshot = {
+    entityType: aggregate.type,
+    sequence: loaded.snapshotSequence + 1n,
+    payload: aggregate.state.encode(state),
+  }
+  const eventSequence = loaded.sequence + BigInt(appended)
+  const size = snapshotCommitSize({...snapshot, entityId, eventSequence})
+
+  return size > MAX_COMMIT_ITEM_BYTES ? null : snapshot
+}
+
+/** The operations the aggregate's projectors add to a commit, in declaration order. */
+export function projectCommit<S, C, D extends EventDefinitions>(
+  aggregate: Aggregate<S, C, D>,
+  entityId: string,
+  state: S,
+  events: readonly SerializedEvent[],
+  snapshot: NewSnapshot | null,
+): ProjectorGroup[] {
+  const projectors = aggregate.projectors ?? []
+  if (projectors.length === 0) {
+    return []
+  }
+
+  // Each projector gets its own frozen copy of the events, their metadata and every byte array,
+  // so none can change what another one sees, or what the commit writes.
+  const encodedState = snapshot?.payload ?? aggregate.state.encode(state)
+  const detached = (): Projection<S> =>
+    Object.freeze({
+      entityType: aggregate.type,
+      entityId,
+      state,
+      encodedState: encodedState.slice(),
+      events: Object.freeze(
+        events.map((event) =>
+          Object.freeze({
+            ...event,
+            payload: event.payload && event.payload.slice(),
+            metadata: Object.freeze(copyMetadata(event.metadata)),
+          }),
+        ),
+      ),
+    })
+
+  return projectors.flatMap((projector) => projector.project(detached()) ?? [])
+}
+
+/** A copy of the metadata, so changing one event's changes no other. */
+export function copyMetadata(metadata: Metadata): Metadata {
+  return {
+    ...metadata,
+    trace: metadata.trace && new Map(metadata.trace),
+    origin: metadata.origin && {...metadata.origin},
+    extensions: new Map(metadata.extensions),
+  }
+}

package/src/store.ts

@@ -6,14 +6,19 @@ import {
   type EventDefinitions,
   type EventOf,
   type Rejection,
-  encodeEventData,
   replayEvent,
 } from './aggregate.js'
 import {commitIds} from './commit-id.js'
 import {EvtError, SequenceGapError, SnapshotError, isConflict, isRetryable} from './errors.js'
-import {type SerializedEvent, eventId} from './event.js'
+import type {SerializedEvent} from './event.js'
 import {type Metadata, emptyMetadata} from './metadata.js'
-import type {CallOptions, NewSnapshot, Repository} from './repository.js'
+import type {
+  CallOptions,
+  NewSnapshot,
+  ProjectorGroup,
+  Repository,
+  TransactionalRepository,
+} from './repository.js'
 import {
   DEFAULT_RETRY_POLICY,
   type RetryPolicy,
@@ -21,7 +26,8 @@ import {
   retryDelay,
   sleep,
 } from './retry.js'
-import {MAX_COMMIT_ITEM_BYTES, snapshotCommitSize, snapshotEventsDue} from './snapshots.js'
+import {commitSnapshot, projectCommit, serializeEvents} from './staging.js'
+import {Transaction} from './transaction.js'
 
 /** The default number of events between snapshots, as in Go and Rust. */
 export const DEFAULT_SNAPSHOT_INTERVAL = 5
@@ -29,8 +35,6 @@ export const DEFAULT_SNAPSHOT_INTERVAL = 5
 // How many times a load reads the stream when it finds a sequence gap.
 const LOAD_ATTEMPTS = 3
 
-const INT64_MAX = 2n ** 63n - 1n
-
 /** How a {@link Store} fills in what commands leave out. */
 export interface StoreOptions {
   /** The region metadata gets when a command's metadata has none. */
@@ -146,8 +150,10 @@ export class Store {
 
   /**
    * Loads the aggregate, runs the command, and commits its events, with a snapshot when the
-   * commit reaches the snapshot interval. A snapshot whose item is over the per-item commit budget
-   * is left out, so the commit still succeeds and later loads replay from the one before.
+   * commit reaches the snapshot interval, and the aggregate's projector operations. A snapshot
+   * whose item is over the per-item commit budget is left out, so the commit still succeeds and
+   * later loads replay from the one before, but a projector's own items are budgeted as they are:
+   * a view row of a state that large fails the commit.
    *
    * A command ID already carried by an event folded in since the latest snapshot makes the
    * command a `duplicate`, and the handler doesn't run. A conflict with another writer throws;
@@ -175,8 +181,13 @@ export class Store {
       return {kind: 'committed', state: loaded, events: []}
     }
 
-    const {state, events, snapshot} = this.#stage(aggregate, loaded, decision.events, metadata)
-    await this.repository.commit({entityId, events, snapshot}, options)
+    const {state, events, snapshot, projections} = this.#stage(
+      aggregate,
+      loaded,
+      decision.events,
+      metadata,
+    )
+    await this.repository.commit({entityId, events, snapshot, projections}, options)
 
     return {kind: 'committed', state, events}
   }
@@ -212,6 +223,28 @@ export class Store {
     /* oxlint-enable no-await-in-loop */
   }
 
+  /**
+   * Begins a transaction that reads streams of any aggregate types, appends to some of them, and
+   * commits them all at once, with a read fence on every stream it reads but doesn't write. The
+   * store's region, clock, commit IDs and snapshot interval apply to it, and each stream's
+   * aggregate projectors run in its commit. The repository must be a
+   * {@link TransactionalRepository}, as every one this package ships is, or this throws
+   * `invalidArgument`. {@link execute} stays the shortcut for one stream.
+   */
+  transaction(): Transaction {
+    const repository = this.repository
+    if (!isTransactional(repository)) {
+      throw new EvtError('invalidArgument', 'the repository has no commitTransaction')
+    }
+
+    return new Transaction({
+      repository,
+      load: (aggregate, entityId, options) => this.load(aggregate, entityId, options),
+      snapshotInterval: (aggregate) => this.snapshotInterval(aggregate),
+      metadata: (partial) => this.#metadata(partial),
+    })
+  }
+
   async #loadOnce<S, C, D extends EventDefinitions>(
     aggregate: Aggregate<S, C, D>,
     entityId: string,
@@ -262,57 +295,30 @@ export class Store {
     return {entityId, state, sequence, snapshotSequence, seenCommandIds}
   }
 
-  // Applies the decided events, and builds the stored events and the snapshot the policy calls
-  // for. The state is only used once the commit succeeds.
+  // Applies the decided events, and builds the stored events, the snapshot the policy calls for,
+  // and the projectors' operations. The state is only used once the commit succeeds.
   #stage<S, C, D extends EventDefinitions>(
     aggregate: Aggregate<S, C, D>,
     loaded: Loaded<S>,
     decided: readonly EventOf<D>[],
     metadata: Metadata,
-  ): {state: Loaded<S>; events: SerializedEvent[]; snapshot: NewSnapshot | null} {
+  ): {
+    state: Loaded<S>
+    events: SerializedEvent[]
+    snapshot: NewSnapshot | null
+    projections: ProjectorGroup[]
+  } {
     const entityId = loaded.entityId
-    let sequence = loaded.sequence
-    let state = loaded.state
-    const events: SerializedEvent[] = []
-
-    for (const event of decided) {
-      if (sequence >= INT64_MAX) {
-        throw new EvtError(
-          'invalidCommit',
-          `invalid commit: entity ${entityId} is at the maximum event sequence`,
-        )
-      }
-      sequence++
-
-      const {version, payload} = encodeEventData(aggregate.events, event)
-      events.push({
-        id: eventId(entityId, sequence),
-        sequence,
-        type: event.type,
-        version,
-        entityId,
-        entityType: aggregate.type,
-        payload,
-        metadata: copyMetadata(metadata),
-      })
-      state = aggregate.apply(state, event)
-    }
-
+    const {events, state} = serializeEvents(
+      aggregate,
+      entityId,
+      loaded.sequence,
+      loaded.state,
+      decided,
+      metadata,
+    )
     const interval = this.snapshotInterval(aggregate)
-    let snapshot: NewSnapshot | null = null
-    if (snapshotEventsDue(loaded.sequence, decided.length, interval) > 0) {
-      snapshot = {
-        entityType: aggregate.type,
-        sequence: loaded.snapshotSequence + 1n,
-        payload: aggregate.state.encode(state),
-      }
-
-      // A snapshot over the per-item budget would fail every commit that carries it.
-      const size = snapshotCommitSize({...snapshot, entityId, eventSequence: sequence})
-      if (size > MAX_COMMIT_ITEM_BYTES) {
-        snapshot = null
-      }
-    }
+    const snapshot = commitSnapshot(aggregate, entityId, interval, loaded, events.length, state)
 
     const seenCommandIds = new Set(loaded.seenCommandIds)
     if (metadata.commandId !== null && metadata.commandId !== '') {
@@ -323,12 +329,13 @@ export class Store {
       state: {
         entityId,
         state,
-        sequence,
+        sequence: loaded.sequence + BigInt(events.length),
         snapshotSequence: snapshot ? snapshot.sequence : loaded.snapshotSequence,
         seenCommandIds,
       },
       events,
       snapshot,
+      projections: projectCommit(aggregate, entityId, state, events, snapshot),
     }
   }
 
@@ -361,17 +368,11 @@ export class Store {
   }
 }
 
-// Each stored event gets its own metadata, so changing one changes no other.
-function copyMetadata(metadata: Metadata): Metadata {
-  return {
-    ...metadata,
-    trace: metadata.trace && new Map(metadata.trace),
-    origin: metadata.origin && {...metadata.origin},
-    extensions: new Map(metadata.extensions),
-  }
-}
-
 // RFC 3339 in UTC, to the second, as Go's time.RFC3339 formats a UTC time.
 function rfc3339Seconds(ms: number): string {
   return new Date(ms).toISOString().replace(/\.\d{3}Z$/, 'Z')
 }
+
+function isTransactional(repository: Repository): repository is TransactionalRepository {
+  return typeof (repository as Partial<TransactionalRepository>).commitTransaction === 'function'
+}

package/src/transaction.ts

@@ -0,0 +1,322 @@
+// The Store's multi-stream transaction (ADR 0004 C1, C2): a read set of any aggregate types, the
+// events decided for some of them, and one atomic commit that fences every stream it read but
+// didn't write.
+
+import type {Aggregate, EventDefinitions, EventOf} from './aggregate.js'
+import {EvtError} from './errors.js'
+import type {SerializedEvent} from './event.js'
+import {type Metadata, emptyMetadata} from './metadata.js'
+import {
+  type CallOptions,
+  type Commit,
+  type ReadFence,
+  type TransactionalRepository,
+  checkNotReserved,
+} from './repository.js'
+import {commitSnapshot, copyMetadata, projectCommit, serializeEvents} from './staging.js'
+import type {ExecuteOptions, Loaded} from './store.js'
+import {compareUtf8} from './utf8.js'
+
+const MAX_INT64 = 2n ** 63n - 1n
+
+// The key of the property that types a handle by its aggregate's events. It exists only in types,
+// and a symbol keeps it out of the way while the published declarations still check it.
+declare const eventTypes: unique symbol
+
+/** What a transaction needs from its store. */
+export interface TransactionContext {
+  readonly repository: TransactionalRepository
+  load<S, C, D extends EventDefinitions>(
+    aggregate: Aggregate<S, C, D>,
+    entityId: string,
+    options?: CallOptions,
+  ): Promise<Loaded<S>>
+  snapshotInterval(aggregate: {readonly snapshotInterval?: number | undefined}): number
+  /** The command's metadata with what the store fills in, and the commit ID stamped. */
+  metadata(partial?: Partial<Metadata>): Metadata
+}
+
+/** A fence the caller stamps on a stream the transaction doesn't read. */
+export interface CallerFence {
+  readonly entityId: string
+  /** The stream's entity type, which a fence on a retained type is refused for. */
+  readonly entityType: string
+  /** The head the caller observed: 0 for a stream with no events. */
+  readonly head: bigint
+}
+
+/**
+ * What a transaction's commit did:
+ *
+ * - `committed`: every stream's events (possibly none) are stored, and every fence held. `events`
+ *   are the stored events in the order the commit wrote them: by entity ID bytes, then sequence.
+ * - `duplicate`: an event a read stream folded in since its latest snapshot already carries the
+ *   command ID, so nothing was written.
+ */
+export type TransactionResult =
+  {kind: 'committed'; events: SerializedEvent[]} | {kind: 'duplicate'; commandId: string}
+
+// One stream of the read set: what the read loaded, and what the transaction appended since.
+interface Stream {
+  // oxlint-disable-next-line typescript/no-explicit-any -- each stream has its own aggregate type.
+  readonly aggregate: Aggregate<any, any, any>
+  // The position of its read call, which orders the commit's projector operations.
+  readonly order: number
+  readonly loaded: Loaded<unknown>
+  state: unknown
+  events: SerializedEvent[]
+}
+
+/**
+ * A stream read into a {@link Transaction}, typed by its aggregate. Pass it to
+ * {@link Transaction.append} to stage events for it; a read never appended to is fenced at the
+ * head it was read at.
+ */
+export class StreamRead<S, D extends EventDefinitions> {
+  readonly #stream: Stream
+  // Ties the handle to its aggregate's event types, which only append reads.
+  declare readonly [eventTypes]?: D
+
+  /** @internal Built by {@link Transaction.read}. */
+  constructor(stream: Stream) {
+    this.#stream = stream
+  }
+
+  get entityId(): string {
+    return this.#stream.loaded.entityId
+  }
+
+  /** The state, with the events appended through this handle. */
+  get state(): S {
+    return this.#stream.state as S
+  }
+
+  /** The sequence of the last event, with the events appended through this handle. */
+  get sequence(): bigint {
+    return this.#stream.loaded.sequence + BigInt(this.#stream.events.length)
+  }
+
+  /** The stream as it was read. */
+  get loaded(): Loaded<S> {
+    return this.#stream.loaded as Loaded<S>
+  }
+}
+
+/**
+ * One atomic commit across several streams. {@link read} loads streams of any aggregate types,
+ * {@link append} stages the events decided for them, {@link fence} adds a fence the caller stamped
+ * on a stream it didn't read, and {@link commit} writes everything in one repository transaction,
+ * or nothing. A stream read but never appended to adds a fence the engine filled at the head it
+ * was read at, so the commit fails with a retryable `FenceConflictError` once another writer
+ * moves it. Begin one with {@link Store.transaction}.
+ *
+ * Every staging call checks its input before it changes anything, so one that throws leaves the
+ * transaction as it was. A transaction commits once: after {@link commit}, whatever it returned
+ * or threw, every call throws `invalidCommit`. Begin a new transaction to try again.
+ */
+export class Transaction {
+  readonly #context: TransactionContext
+  readonly #streams = new Map<StreamRead<unknown, EventDefinitions>, Stream>()
+  // Every stream read or being read, by ID, with the position of its read call.
+  readonly #ids = new Map<string, number>()
+  readonly #fences = new Map<string, CallerFence>()
+  #reads = 0
+  #pending = 0
+  #done = false
+
+  /** @internal Begun by {@link Store.transaction}. */
+  constructor(context: TransactionContext) {
+    this.#context = context
+  }
+
+  /**
+   * Loads a stream into the read set, as {@link Store.load} does, and returns its typed handle.
+   * Reading a stream the transaction already read, or is reading, throws `invalidCommit`.
+   */
+  async read<S, C, D extends EventDefinitions>(
+    aggregate: Aggregate<S, C, D>,
+    entityId: string,
+    options: CallOptions = {},
+  ): Promise<StreamRead<S, D>> {
+    this.#checkOpen()
+    if (this.#ids.has(entityId)) {
+      throw invalidCommit(`duplicate read of ${entityId}`)
+    }
+
+    // The ID is held while the load runs, so a concurrent read of the same stream is refused too,
+    // and the read keeps the place it was called in, whenever its load finishes.
+    const order = this.#reads++
+    this.#ids.set(entityId, order)
+    this.#pending++
+    let loaded: Loaded<S>
+    try {
+      loaded = await this.#context.load(aggregate, entityId, options)
+    } catch (error) {
+      this.#ids.delete(entityId)
+      throw error
+    } finally {
+      this.#pending--
+    }
+
+    const stream: Stream = {
+      aggregate,
+      order,
+      loaded,
+      state: loaded.state,
+      events: [],
+    }
+    const read = new StreamRead<S, D>(stream)
+    this.#streams.set(read as StreamRead<unknown, EventDefinitions>, stream)
+
+    return read
+  }
+
+  /**
+   * Stages events for a stream this transaction read. They're applied to the handle's state, and
+   * appending again continues the sequence. The commit stamps their metadata, and runs the
+   * aggregate's projectors over every event appended to the stream, with its final state. A
+   * handle from another transaction throws `invalidCommit`.
+   */
+  append<S, D extends EventDefinitions>(
+    read: StreamRead<S, D>,
+    events: readonly EventOf<D>[],
+  ): this {
+    this.#checkOpen()
+    const stream = this.#streams.get(read as StreamRead<unknown, EventDefinitions>)
+    if (stream === undefined) {
+      throw invalidCommit(`stream ${read.entityId} was not read by this transaction`)
+    }
+
+    // Serialized now, so an event the aggregate can't encode fails here, with nothing staged.
+    const after = stream.loaded.sequence + BigInt(stream.events.length)
+    const staged = serializeEvents(
+      stream.aggregate,
+      stream.loaded.entityId,
+      after,
+      stream.state,
+      events,
+      emptyMetadata(),
+    )
+    stream.events.push(...staged.events)
+    stream.state = staged.state
+
+    return this
+  }
+
+  /**
+   * Adds a fence the caller stamped, for a stream the transaction doesn't read: the commit fails
+   * with a `FenceConflictError` once another writer moves the stream past `head`, which isn't
+   * retryable, since only the caller knows what it read. A fence on a stream the transaction reads,
+   * before or after the read, is dropped at commit: the read's own fence, or its write, holds the
+   * stream instead. A fence in a reserved namespace, at a head outside [0, 2^63 - 1), or on a
+   * stream already fenced throws, with nothing added.
+   */
+  fence(fence: CallerFence): this {
+    this.#checkOpen()
+    checkNotReserved(fence.entityId)
+    if (fence.head < 0n || fence.head >= MAX_INT64 || this.#fences.has(fence.entityId)) {
+      throw invalidCommit(`invalid or duplicate fence ${fence.entityId}`)
+    }
+
+    this.#fences.set(fence.entityId, {...fence})
+
+    return this
+  }
+
+  /**
+   * Stamps one commit ID and the command's metadata on every appended event, and commits every
+   * stream with events, a fence on every stream read without any, and the caller's fences, in one
+   * atomic repository transaction. On failure nothing is written. A command ID that an event a
+   * read stream folded in since its latest snapshot already carries is a `duplicate`, and nothing
+   * is written. Projector operations follow the streams in the order they were read. A commit
+   * while a read is still loading throws `invalidCommit`, and leaves the transaction open.
+   */
+  async commit(options: ExecuteOptions = {}): Promise<TransactionResult> {
+    this.#checkOpen()
+    if (this.#pending > 0) {
+      throw invalidCommit('a read is still loading; await it before the commit')
+    }
+    this.#done = true
+
+    const metadata = this.#context.metadata(options.metadata)
+    const commandId = metadata.commandId
+    const streams = [...this.#streams.values()]
+    streams.sort((a, b) => a.order - b.order)
+    if (
+      commandId !== null &&
+      commandId !== '' &&
+      streams.some((stream) => stream.loaded.seenCommandIds.has(commandId))
+    ) {
+      return {kind: 'duplicate', commandId}
+    }
+
+    const commits: Commit[] = []
+    const fences: ReadFence[] = []
+    for (const stream of streams) {
+      const {aggregate, loaded} = stream
+      if (stream.events.length === 0) {
+        fences.push({
+          entityId: loaded.entityId,
+          entityType: aggregate.type,
+          head: loaded.sequence,
+          provenance: 'engine',
+        })
+        continue
+      }
+
+      for (const event of stream.events) {
+        event.metadata = copyMetadata(metadata)
+      }
+      const interval = this.#context.snapshotInterval(aggregate)
+      const appended = stream.events.length
+      const snapshot = commitSnapshot(
+        aggregate,
+        loaded.entityId,
+        interval,
+        loaded,
+        appended,
+        stream.state,
+      )
+      commits.push({
+        entityId: loaded.entityId,
+        events: stream.events,
+        snapshot,
+        projections: projectCommit(
+          aggregate,
+          loaded.entityId,
+          stream.state,
+          stream.events,
+          snapshot,
+        ),
+      })
+    }
+
+    // A caller's fence on a stream the transaction read is superseded by the read's own.
+    for (const fence of this.#fences.values()) {
+      if (!this.#ids.has(fence.entityId)) {
+        fences.push({...fence, provenance: 'caller'})
+      }
+    }
+
+    await this.#context.repository.commitTransaction({streams: commits, fences}, options)
+
+    // Sorted apart from what the repository was given, which stays in read order.
+    const written = [...commits]
+    written.sort((a, b) => compareUtf8(a.entityId, b.entityId))
+
+    return {
+      kind: 'committed',
+      events: written.flatMap((commit) => commit.events),
+    }
+  }
+
+  #checkOpen(): void {
+    if (this.#done) {
+      throw invalidCommit('the transaction has committed; begin a new one')
+    }
+  }
+}
+
+function invalidCommit(message: string): EvtError {
+  return new EvtError('invalidCommit', `invalid commit: ${message}`)
+}