sailfork / t3code-github / .repos/ alchemy-effect/ packages/ domain/ src/ Stream.ts

import * as Context from "effect/Context";
import type * as Duration from "effect/Duration";
import type * as Effect from "effect/Effect";
import type * as Option from "effect/Option";
import type * as EffectStream from "effect/Stream";
import type * as Aggregate from "./Aggregate.ts";
import type * as Event from "./Event.ts";
import type { Filter } from "./Filter.ts";
import type * as Key from "./Key.ts";
import type * as Middleware from "./Middleware.ts";
import type * as Read from "./Read.ts";
import type * as Rejection from "./Rejection.ts";
import type { ConsistencyTimeout, Page } from "./View.ts";

/**
 * One entry of a stream key: the event appended, and where it sits.
 */
export interface Entry<E, Id = string> {
  readonly event: E;
  /** `id` is the stream key, `stream` is `Stream/key`, `seq` counts the key's entries. */
  readonly envelope: Aggregate.Envelope<Id>;
}

/**
 * Structural constraint satisfied by every stream class.
 */
export interface Any extends Context.Key<unknown, unknown> {
  readonly kind: "Stream";
  readonly streamName: string;
  readonly definition: {
    readonly key: Key.Any;
    readonly entries: ReadonlyArray<Event.Any>;
  } & Read.AnyContract;
  /** Type-level only: the entry events. */
  readonly "~event": unknown;
}

/** The entry event type of a stream class. */
export type EventOf<S extends Any> = S["~event"];
/** The key of a stream class: an aggregate, or a string Schema. */
export type KeyOf<S extends Any> = S["definition"]["key"];

/**
 * The pure definition of a stream.
 */
export interface Definition<
  Key extends Key.Any,
  Entries extends ReadonlyArray<Event.Any>,
  Ms extends Middleware.List = readonly [],
  Rejects extends ReadonlyArray<Rejection.Any> = readonly [],
> extends Read.Contract<
  Key.RefOf<Key>,
  Entry<Aggregate.InstanceOf<Entries[number]>, Key.IdOf<Key>> | null,
  Ms,
  Rejects
> {
  /**
   * What keys this stream, one ordered log per key: an aggregate, whose refs
   * are its keys, or a string Schema, whose values are.
   */
  readonly key: Key;
  /** The events the stream's entries may be. */
  readonly entries: Entries;
}

/**
 * What a projection's handler passes to {@link Host.append}: the input it is
 * handling. Every input a projection handler receives qualifies.
 */
export interface Origin<Key extends Key.Any> {
  readonly key: Key.RefOf<Key>;
}

/**
 * The API of a stream, obtained with `yield* MyStream`.
 */
export interface Host<Key extends Key.Any, E> {
  /** The latest entry of a key, or `none` if nothing was appended. */
  readonly peek: (
    key: Key.RefOf<Key>,
    options?: {
      /** Wait until the stream's writer has handled this write (a command's `stream` and `version`). */
      readonly atLeast?: { readonly stream: string; readonly version: number };
      readonly timeout?: Duration.Input;
    },
  ) => Effect.Effect<Option.Option<Entry<E, Key.IdOf<Key>>>, ConsistencyTimeout>;
  /** The latest entry, then each new one. */
  readonly watch: (
    key: Key.RefOf<Key>,
  ) => EffectStream.Stream<Option.Option<Entry<E, Key.IdOf<Key>>>>;
  /** Every entry from `after` (an entry `seq`), then live ones. */
  readonly events: (
    key: Key.RefOf<Key>,
    options?: { readonly after?: number; readonly where?: Filter<E> },
  ) => EffectStream.Stream<Entry<E, Key.IdOf<Key>>>;
  /** A page of a key's entries, oldest first unless `order` is `"desc"`. */
  readonly list: (
    key: Key.RefOf<Key>,
    options?: {
      readonly where?: Filter<E>;
      readonly order?: "asc" | "desc";
      readonly take?: number;
      readonly after?: number;
    },
  ) => Effect.Effect<Page<Entry<E, Key.IdOf<Key>>>>;
  /**
   * Append entries for the input a projection is handling, to that input's
   * key. Only a projection that lists this stream in `writes` may append, and
   * a replayed or redelivered input appends nothing twice.
   */
  readonly append: (origin: Origin<Key>, ...events: ReadonlyArray<E>) => Effect.Effect<void>;
}

/**
 * Type-level identity of a stream in an Effect's requirements.
 */
export interface StreamKey<Name extends string> {
  readonly "~alchemy/Domain/Stream": Name;
}

/**
 * A keyed, append-only log: one ordered list of entries per key, kept and
 * replayable. A projection writes it; clients read it through an Api with the
 * same middleware and `validate` as a view. Its latest entry is its current
 * value, so a stream of snapshots serves both "what is it now?" (`peek`) and
 * "tell me every change" (`watch`, `events`).
 *
 * ### Declaring a stream
 * **Example:** An account card, one entry per change
 * ```typescript
 * import * as Domain from "@alchemy.run/domain";
 * import * as Schema from "effect/Schema";
 * import { Account } from "./Account.ts";
 *
 * export class CardChanged extends Domain.Event("CardChanged", {
 *   owner: Schema.String,
 *   balance: Schema.Int,
 * }) {}
 *
 * export class AccountCard extends Domain.Stream("AccountCard", {
 *   key: Account,
 *   entries: [CardChanged],
 * }) {}
 * ```
 *
 * ### Writing it from a projection
 * A projection lists the streams it writes, then appends for the input it is
 * handling.
 *
 * **Example:** Append a card for every summary change
 * ```typescript
 * export class AccountCards extends Domain.Projection("AccountCards", {
 *   from: [AccountSummary],
 *   key: Account,
 *   on: [MoneyDeposited],
 *   writes: [AccountCard],
 * }) {}
 *
 * export const AccountCardsLive = AccountCards.toLayer(
 *   Effect.gen(function* () {
 *     const cards = yield* AccountCard;
 *     return Effect.fn(function* (batch) {
 *       for (const input of batch) {
 *         yield* cards.append(input, new CardChanged({ owner: input.state.owner, balance: input.state.balance }));
 *       }
 *     });
 *   }),
 * );
 * ```
 *
 * ### Reading it
 * **Example:** Through an Api
 * ```typescript
 * const latest = yield* bank.AccountCard.peek(accountId);
 * yield* bank.AccountCard.watch(accountId).pipe(
 *   Stream.runForEach(({ state: card }) => Effect.log(card)),
 * );
 * ```
 *
 * @primitive
 */
export const make = <
  const Name extends string,
  Key extends Key.Any,
  const Entries extends ReadonlyArray<Event.Any>,
  const Ms extends Middleware.List = readonly [],
  const Rejects extends ReadonlyArray<Rejection.Any> = readonly [],
>(
  name: Name,
  definition: Definition<Key, Entries, Ms, Rejects>,
): StreamClass<
  Name,
  Definition<Key, Entries, Ms, Rejects>,
  Key,
  Aggregate.InstanceOf<Entries[number]>
> => {
  const Tag = Context.Service<StreamKey<Name>, Host<Key, Aggregate.InstanceOf<Entries[number]>>>()(
    `alchemy/Domain/Stream/${name}`,
  );
  return class extends Tag {
    static readonly kind = "Stream" as const;
    static readonly streamName: Name = name;
    static readonly definition = definition;
  } as unknown as StreamClass<
    Name,
    Definition<Key, Entries, Ms, Rejects>,
    Key,
    Aggregate.InstanceOf<Entries[number]>
  >;
};

/**
 * The class type returned by {@link make}.
 */
export interface StreamClass<
  Name extends string,
  Def,
  Key extends Key.Any,
  E,
> extends Context.ServiceClass<StreamKey<Name>, string, Host<Key, E>> {
  readonly kind: "Stream";
  readonly streamName: Name;
  readonly definition: Def;
  readonly "~event": E;
}