effect-cqrs 0.0.0-stage → 0.2.0

package/src/Causation.ts

@@ -0,0 +1,48 @@
+/**
+ * Why an event was recorded. Every event carries two ids:
+ *
+ * - `correlationId` is shared by everything that follows from one original
+ *   request, across aggregates and view models.
+ * - `causationId` names what directly caused the command that recorded it: the
+ *   request, or the event a view model or saga was reacting to.
+ *
+ * They travel in the fiber's context rather than in payloads. A command run
+ * outside any causation starts a new correlation with a fresh id. Inside a view
+ * model handler the event being handled is the cause, so a chain of reactions
+ * can be drawn as a tree without passing ids around by hand.
+ */
+import { Context, Effect, Function } from "effect"
+import { eventId, type StoredEvent } from "./EventStore.ts"
+
+export interface Causation {
+  readonly correlationId: string
+  readonly causationId: string
+}
+
+/** The causation of commands run in this fiber, `undefined` outside any. */
+export const CurrentCausation = Context.Reference<Causation | undefined>("effect-cqrs/Causation", {
+  defaultValue: () => undefined
+})
+
+/** Runs an effect with this causation, for instance the id of an incoming HTTP request. */
+export const withCausation: {
+  (causation: Causation): <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>
+  <A, E, R>(effect: Effect.Effect<A, E, R>, causation: Causation): Effect.Effect<A, E, R>
+} = Function.dual(
+  2,
+  <A, E, R>(effect: Effect.Effect<A, E, R>, causation: Causation) =>
+    Effect.provideService(effect, CurrentCausation, causation)
+)
+
+/** The causation of commands run in reaction to a stored event. */
+export const fromEvent = (event: StoredEvent): Causation => {
+  const id = eventId(event)
+  return { correlationId: event.correlationId ?? id, causationId: id }
+}
+
+/**
+ * Runs an effect in reaction to a stored event, so commands it runs record that
+ * event as their cause. View models do this for their handlers already.
+ */
+export const causedBy = (event: StoredEvent) => <A, E, R>(effect: Effect.Effect<A, E, R>): Effect.Effect<A, E, R> =>
+  Effect.provideService(effect, CurrentCausation, fromEvent(event))

package/src/Checkpoints.ts

@@ -0,0 +1,23 @@
+/**
+ * Remembers how far each view model has read.
+ *
+ * A checkpoint has to live as long as the view model it tracks: pair an
+ * in-memory view model with {@link layerMemory} so it rebuilds from the event
+ * store on restart, and a durable one with a durable checkpoint store.
+ */
+import { Context, Effect, Layer } from "effect"
+import type { EventStoreError } from "./EventStore.ts"
+
+export class Checkpoints extends Context.Service<Checkpoints, {
+  /** The last processed position, `0` when the view model never ran. */
+  get(viewModel: string): Effect.Effect<number, EventStoreError>
+  set(viewModel: string, position: number): Effect.Effect<void, EventStoreError>
+}>()("effect-cqrs/Checkpoints") {}
+
+export const layerMemory: Layer.Layer<Checkpoints> = Layer.sync(Checkpoints, () => {
+  const positions = new Map<string, number>()
+  return Checkpoints.of({
+    get: (viewModel) => Effect.sync(() => positions.get(viewModel) ?? 0),
+    set: (viewModel, position) => Effect.sync(() => void positions.set(viewModel, position))
+  })
+})

package/src/EventStore.ts

@@ -0,0 +1,270 @@
+/**
+ * The append-only log every aggregate and view model is built on.
+ *
+ * Each event belongs to a stream, identified by aggregate name and id, and has
+ * two coordinates: a `version` that orders it inside its stream and a `position`
+ * that orders it across the whole store. Writers use the version for optimistic
+ * concurrency, readers use the position as a durable cursor.
+ */
+import { Context, DateTime, Effect, Layer, Option, Ref, Schema, Stream, SubscriptionRef } from "effect"
+
+export class EventStoreError extends Schema.TaggedError<EventStoreError>()("EventStoreError", {
+  operation: Schema.String,
+  cause: Schema.Defect()
+}) {}
+
+export class ConcurrencyConflict extends Schema.TaggedError<ConcurrencyConflict>()("ConcurrencyConflict", {
+  aggregateName: Schema.String,
+  aggregateId: Schema.String,
+  expectedVersion: Schema.Int
+}) {}
+
+export const StoredEvent = Schema.Struct({
+  position: Schema.Int,
+  aggregateName: Schema.String,
+  aggregateId: Schema.String,
+  version: Schema.Int,
+  type: Schema.String,
+  /** The version of the event's schema the payload was written with. Events from before versions existed are `1`. */
+  schemaVersion: Schema.Int,
+  payload: Schema.Json,
+  timestamp: Schema.DateTimeUtcFromMillis,
+  /** Shared by everything that follows from one original request. */
+  correlationId: Schema.NullOr(Schema.String),
+  /** What directly caused the command that recorded the event: a request, a command or another event. */
+  causationId: Schema.NullOr(Schema.String),
+  /** What the command carried beside its payload, see `Metadata`. Events from before metadata existed have `{}`. */
+  metadata: Schema.JsonObject
+})
+export type StoredEvent = typeof StoredEvent.Type
+
+export interface NewEvent {
+  readonly type: string
+  readonly payload: Schema.Json
+  /** Defaults to `1`. */
+  readonly schemaVersion?: number | undefined
+}
+
+export interface AppendInput {
+  readonly aggregateName: string
+  readonly aggregateId: string
+  /** The stream version the writer based its decision on, `0` for a new stream. */
+  readonly expectedVersion: number
+  readonly events: ReadonlyArray<NewEvent>
+  readonly correlationId?: string | undefined
+  readonly causationId?: string | undefined
+  /** Recorded on every event of the append. Defaults to `{}`. */
+  readonly metadata?: Schema.JsonObject | undefined
+}
+
+/**
+ * Identifies an event wherever it is stored, as the `causationId` of what it causes:
+ * `account/alice@4`. Name and id are URI-encoded, so a `/` or `@` inside one can't
+ * make two events look alike.
+ */
+export const eventId = (event: Pick<StoredEvent, "aggregateName" | "aggregateId" | "version">): string =>
+  `${encodeURIComponent(event.aggregateName)}/${encodeURIComponent(event.aggregateId)}@${event.version}`
+
+/** The columns every adapter stores for a new event, with the defaults filled in. */
+export const toStored = (
+  input: AppendInput,
+  event: NewEvent,
+  index: number,
+  position: number,
+  timestamp: DateTime.Utc
+): StoredEvent => ({
+  position,
+  aggregateName: input.aggregateName,
+  aggregateId: input.aggregateId,
+  version: input.expectedVersion + index + 1,
+  type: event.type,
+  schemaVersion: event.schemaVersion ?? 1,
+  payload: event.payload,
+  timestamp,
+  correlationId: input.correlationId ?? null,
+  causationId: input.causationId ?? null,
+  metadata: input.metadata ?? {}
+})
+
+/**
+ * Selects events by stream, type and time. Omitted fields match everything.
+ * `startTime` is inclusive and `finishTime` is exclusive, so adding one
+ * millisecond to a history timestamp selects up to and including that event.
+ */
+export interface EventFilter {
+  readonly aggregateNames?: ReadonlyArray<string> | undefined
+  readonly aggregateIds?: ReadonlyArray<string> | undefined
+  readonly eventTypes?: ReadonlyArray<string> | undefined
+  readonly startTime?: DateTime.Utc | undefined
+  readonly finishTime?: DateTime.Utc | undefined
+  readonly afterPosition?: number | undefined
+  /**
+   * For a filter on one stream: where to continue in it. Versions follow the stream's
+   * own index, so resuming there costs the same however far the log has moved on.
+   */
+  readonly afterVersion?: number | undefined
+}
+
+/** A filter on exactly one stream, which a store can read through that stream's index. */
+export const isOneStream = ({ aggregateIds, aggregateNames }: EventFilter): boolean =>
+  aggregateNames?.length === 1 && aggregateIds?.length === 1
+
+export class EventStore extends Context.Service<EventStore, {
+  /** Appends atomically, failing if the stream moved past `expectedVersion`. */
+  append(input: AppendInput): Effect.Effect<ReadonlyArray<StoredEvent>, ConcurrencyConflict | EventStoreError>
+  /** Reads the events stored so far, ordered by position, then completes. */
+  read(filter?: EventFilter): Stream.Stream<StoredEvent, EventStoreError>
+  /** Reads the events stored so far, then keeps following new ones. Never completes. */
+  subscribe(filter?: EventFilter): Stream.Stream<StoredEvent, EventStoreError>
+  /** The position of the latest event, `0` when the store is empty. */
+  readonly head: Effect.Effect<number, EventStoreError>
+  /**
+   * Emits the current latest position, then each newly appended one. Consumers
+   * can treat an element as "there may be something new": appends from other
+   * processes are not observed.
+   */
+  readonly changes: Stream.Stream<number>
+}>()("effect-cqrs/EventStore") {}
+
+/** What a storage adapter implements. {@link make} builds the rest on top. */
+export interface Backend {
+  readonly append: EventStore["Service"]["append"]
+  readonly readBatch: (
+    filter: EventFilter,
+    afterPosition: number,
+    limit: number
+  ) => Effect.Effect<ReadonlyArray<StoredEvent>, EventStoreError>
+  readonly head: Effect.Effect<number, EventStoreError>
+}
+
+export const make = Effect.fnUntraced(function*(backend: Backend, options?: { readonly batchSize?: number }) {
+  const batchSize = options?.batchSize ?? 500
+  const latest = yield* SubscriptionRef.make(yield* backend.head)
+
+  const append = Effect.fn("EventStore.append")((input: AppendInput) =>
+    backend.append(input).pipe(
+      Effect.tap((stored) => {
+        const last = stored.at(-1)
+        return last === undefined
+          ? Effect.void
+          : SubscriptionRef.update(latest, (position) => Math.max(position, last.position))
+      })
+    )
+  )
+
+  const read = (filter: EventFilter = {}) =>
+    Stream.paginate(
+      { afterPosition: filter.afterPosition ?? 0, afterVersion: filter.afterVersion ?? 0 },
+      ({ afterPosition, afterVersion }) =>
+        backend.readBatch({ ...filter, afterVersion }, afterPosition, batchSize).pipe(
+          Effect.map((events) => {
+            const last = events.at(-1)
+            return [
+              events,
+              last === undefined || events.length < batchSize
+                ? Option.none()
+                : Option.some({ afterPosition: last.position, afterVersion: last.version })
+            ] as const
+          })
+        )
+    )
+
+  const subscribe = (filter: EventFilter = {}) =>
+    Stream.unwrap(Effect.gen(function*() {
+      const cursor = yield* Ref.make({ position: filter.afterPosition ?? 0, version: filter.afterVersion ?? 0 })
+      return SubscriptionRef.changes(latest).pipe(
+        Stream.filterEffect((position) => Effect.map(Ref.get(cursor), (seen) => position > seen.position)),
+        Stream.flatMap((position) =>
+          Stream.unwrap(
+            Effect.map(Ref.get(cursor), (seen) =>
+              read({ ...filter, afterPosition: seen.position, afterVersion: seen.version }))
+          ).pipe(
+            Stream.tap((event) => Ref.set(cursor, { position: event.position, version: event.version })),
+            // Events the filter skipped must not trigger another read.
+            Stream.ensuring(
+              Ref.update(cursor, (seen) => seen.position >= position ? seen : { ...seen, position })
+            )
+          )
+        )
+      )
+    }))
+
+  return EventStore.of({
+    append,
+    read,
+    subscribe,
+    head: backend.head,
+    changes: SubscriptionRef.changes(latest)
+  })
+})
+
+const matches = (filter: EventFilter, event: StoredEvent): boolean =>
+  (filter.aggregateNames?.includes(event.aggregateName) ?? true) &&
+  (filter.aggregateIds?.includes(event.aggregateId) ?? true) &&
+  (filter.eventTypes?.includes(event.type) ?? true) &&
+  (filter.startTime === undefined || !DateTime.isLessThan(event.timestamp, filter.startTime)) &&
+  (filter.finishTime === undefined || DateTime.isLessThan(event.timestamp, filter.finishTime))
+
+/** The index of the first event past `position`, in events sorted by position. */
+const firstAfter = (events: ReadonlyArray<StoredEvent>, position: number): number => {
+  let low = 0
+  let high = events.length
+  while (low < high) {
+    const middle = (low + high) >>> 1
+    if (events[middle]!.position <= position) low = middle + 1
+    else high = middle
+  }
+  return low
+}
+
+const streamKey = (aggregateName: string, aggregateId: string) => JSON.stringify([aggregateName, aggregateId])
+
+export const makeMemory: Effect.Effect<EventStore["Service"], EventStoreError> = Effect.gen(function*() {
+  const events: Array<StoredEvent> = []
+  const streams = new Map<string, Array<StoredEvent>>()
+
+  // Every command reads one stream, which shouldn't cost a walk through the whole log.
+  const candidates = (filter: EventFilter): ReadonlyArray<StoredEvent> =>
+    isOneStream(filter)
+      ? streams.get(streamKey(filter.aggregateNames![0]!, filter.aggregateIds![0]!)) ?? []
+      : events
+
+  return yield* make({
+    append: Effect.fnUntraced(function*(input) {
+      const timestamp = yield* DateTime.now
+      const key = streamKey(input.aggregateName, input.aggregateId)
+      const stream = streams.get(key) ?? []
+      const version = stream.length
+      if (version !== input.expectedVersion) {
+        return yield* new ConcurrencyConflict({
+          aggregateName: input.aggregateName,
+          aggregateId: input.aggregateId,
+          expectedVersion: input.expectedVersion
+        })
+      }
+      const stored = input.events.map((event, index) =>
+        toStored(input, event, index, events.length + index + 1, timestamp)
+      )
+      for (const event of stored) {
+        events.push(event)
+        stream.push(event)
+      }
+      streams.set(key, stream)
+      return stored
+    }),
+    readBatch: (filter, afterPosition, limit) =>
+      Effect.sync(() => {
+        const source = candidates(filter)
+        const batch: Array<StoredEvent> = []
+        for (let index = firstAfter(source, afterPosition); index < source.length && batch.length < limit; index++) {
+          const event = source[index]!
+          if (matches(filter, event)) batch.push(event)
+        }
+        return batch
+      }),
+    head: Effect.sync(() => events.length)
+  })
+})
+
+/** Keeps events in process memory. They do not survive a restart. */
+export const layerMemory: Layer.Layer<EventStore, EventStoreError> = Layer.effect(EventStore, makeMemory)

package/src/EventVersions.ts

@@ -0,0 +1,104 @@
+/**
+ * The older shapes of one event, so that events stored long ago still reach
+ * projections and view models in today's shape. The log is never rewritten:
+ * old payloads are upcast as they are read.
+ *
+ * ```ts
+ * const AccountOpenedV1 = Schema.Struct({ owner: Schema.String })
+ *
+ * const Account = Aggregate.make<State>()({
+ *   name: "account",
+ *   events: AccountEvent,
+ *   initial,
+ *   projection,
+ *   versions: {
+ *     AccountOpened: EventVersions.from(AccountOpenedV1).next(
+ *       AccountEvent.cases.AccountOpened,
+ *       ({ owner }) => ({ owner, currency: "CHF" })
+ *     )
+ *   }
+ * })
+ * ```
+ *
+ * The first schema is version 1, the shape events had before the history was
+ * declared, and every `next` adds a version. The last one must be the event's
+ * current schema, which is what new events are written with.
+ */
+import { Schema, SchemaGetter } from "effect"
+
+/** A schema that decodes and encodes without services, as stored payloads need. */
+export type VersionSchema = Schema.Top & {
+  readonly DecodingServices: never
+  readonly EncodingServices: never
+}
+
+/** What an upcast returns: the next version, without the `_tag` the event's name already gives. */
+export type Untagged<T> = T extends { readonly _tag: string } ? Omit<T, "_tag"> : T
+
+type Last<Schemas extends ReadonlyArray<VersionSchema>> = Schemas extends readonly [...any, infer L extends VersionSchema]
+  ? L
+  : VersionSchema
+
+export interface EventVersions<Schemas extends ReadonlyArray<VersionSchema>, Latest> {
+  /** Oldest first: `schemas[0]` is version 1. */
+  readonly schemas: Schemas
+  /** `upcasts[i]` turns version `i + 1` into version `i + 2`. */
+  readonly upcasts: ReadonlyArray<(previous: any) => unknown>
+  /** The type of the last version, which an aggregate checks against its event. */
+  readonly "~latest"?: Latest
+  /** Adds a version, with the function that turns the previous one into it. */
+  next<Next extends VersionSchema>(
+    schema: Next,
+    upcast: (previous: Latest) => Untagged<Next["Type"]>
+  ): EventVersions<readonly [...Schemas, Next], Next["Type"]>
+}
+
+/** Any history whose last version is `Latest`. */
+export type Any<Latest = any> = EventVersions<ReadonlyArray<VersionSchema>, Latest>
+
+/** The schema of one version, or `never` when the history has no such version. */
+export type SchemaAt<H extends Any, V extends number> = H extends EventVersions<infer Schemas, any>
+  ? [never, ...Schemas][V] extends infer S extends VersionSchema ? S : never
+  : never
+
+const build = <Schemas extends ReadonlyArray<VersionSchema>>(
+  schemas: Schemas,
+  upcasts: ReadonlyArray<(previous: any) => unknown>
+): EventVersions<Schemas, Last<Schemas>["Type"]> => ({
+  schemas,
+  upcasts,
+  next: (schema, upcast) => build([...schemas, schema] as const, [...upcasts, upcast]) as any
+})
+
+/** Starts a history at version 1. */
+export const from = <V1 extends VersionSchema>(schema: V1): EventVersions<readonly [V1], V1["Type"]> =>
+  build([schema] as const, [])
+
+/** The version new events of this kind are written with. */
+export const current = (versions: Any | undefined): number => versions?.schemas.length ?? 1
+
+/**
+ * Builds one decoder per old version, each going all the way to the current one.
+ * The chains are composed once with `Schema.decodeTo`, so reading an old event
+ * costs one decode however many versions it is behind.
+ *
+ * `decoders[v - 1]` decodes a JSON payload stored at version `v`. The current
+ * version has none, as the aggregate's own schema reads it.
+ */
+export const decoders = (tag: string, versions: Any): ReadonlyArray<Schema.Decoder<unknown>> =>
+  versions.schemas.slice(0, -1).map((schema, index) =>
+    versions.schemas.slice(index + 1).reduce<Schema.Top>(
+      (chain, next, step) =>
+        chain.pipe(Schema.decodeTo(Schema.toType(next), {
+          // Adding the tag lets the last step decode into the tagged event, and a
+          // schema in between without one drops it again.
+          decode: SchemaGetter.transform((previous) => ({
+            ...(versions.upcasts[index + step]!(previous) as object),
+            _tag: tag
+          })),
+          // A payload is only ever written in its current version.
+          encode: SchemaGetter.forbidden(() => `${tag} can only be written in its current version`)
+        })),
+      Schema.toCodecJson(schema)
+    ) as Schema.Decoder<unknown>
+  )