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

import * as Context from "effect/Context";
import * as Data from "effect/Data";
import type * as DateTime from "effect/DateTime";
import type * as Duration from "effect/Duration";
import type * as Effect from "effect/Effect";
import type * as Option from "effect/Option";
import * as Schema from "effect/Schema";
import type * as Stream from "effect/Stream";
import type * as Aggregate from "./Aggregate.ts";
import type * as Event from "./Event.ts";
import type { Filter } from "./Filter.ts";
import { evolveView, type LocalViewInput } from "./internal.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";

/**
 * Raised by `waitFor` when the predicate does not hold before the timeout.
 */
export class WaitTimeout extends Data.TaggedError("WaitTimeout")<{
  readonly view: string;
  readonly key: string;
}> {}

/**
 * Raised by a read with `atLeast` when the view has not applied that write
 * before the timeout. A client receives it like a rejection.
 */
export class ConsistencyTimeout extends Schema.TaggedError<ConsistencyTimeout>()(
  "ConsistencyTimeout",
  {
    view: Schema.String,
    key: Schema.String,
    stream: Schema.String,
    version: Schema.Number,
  },
) {}

/** A handler, or one handler per named route. */
type Handlers = {
  readonly [key: string]:
    | ((...args: never[]) => unknown)
    | { readonly [route: string]: ((...args: never[]) => unknown) | undefined }
    | undefined;
};

/**
 * Structural constraint satisfied by every view class.
 */
export interface Any extends Context.Key<unknown, unknown> {
  readonly kind: "View";
  readonly viewName: string;
  readonly definition: {
    readonly from: ReadonlyArray<Aggregate.Any | Any>;
    readonly key: Key.Any;
    readonly state?: Schema.Top;
    readonly initial?: unknown;
    readonly keyOf?: Handlers;
    readonly evolve?: Handlers;
    readonly events?: ReadonlyArray<Event.Any>;
    readonly emit?: Handlers;
    readonly computed?: { readonly [name: string]: ((state: never) => unknown) | undefined };
    readonly version?: number;
  } & Read.AnyContract;
  /** Type-level only: the view's state. */
  readonly "~state": unknown;
  /** Type-level only: the events the view emits. */
  readonly "~events": unknown;
}

/** Something a view or policy can consume: an aggregate or a view. */
export type Source = Aggregate.Any | Any;

/** The state type of a view class (`null` for a view without state). */
export type StateOf<V extends Any> = V["~state"];
/** The events a view class emits. */
export type EventOf<V extends Any> = V["~events"];
/** The key aggregate of a view class. */
export type KeyOf<V extends Any> = V["definition"]["key"];

/** The name of a source. */
export type NameOf<S> = S extends Aggregate.Any
  ? S["aggregateName"]
  : S extends Any
    ? S["viewName"]
    : never;
/** The events a source produces. */
export type SourceEvent<S> = S extends Aggregate.Any
  ? Aggregate.EventOf<S>
  : S extends Any
    ? EventOf<S>
    : never;
/** The key that identifies a source's instances: an aggregate, or a view's key. */
export type SourceKey<S> = S extends Aggregate.Any ? S : S extends Any ? KeyOf<S> : never;
/** What a source attaches to each event: a view's state after it, nothing for an aggregate. */
export type SourceState<S> = S extends Any ? StateOf<S> | null : undefined;

/**
 * One input to a view or policy: an event, the source instance it came from,
 * and (for a view source) that view's state after the event.
 */
export type Input<S> = S extends unknown
  ? SourceEvent<S> extends infer E
    ? E extends unknown
      ? {
          readonly name: NameOf<S>;
          readonly event: E;
          readonly source: Key.RefOf<SourceKey<S>>;
          readonly state: SourceState<S>;
        }
      : never
    : never
  : never;

/** Every input a list of sources produces. */
export type Inputs<From extends ReadonlyArray<unknown>> = Input<From[number]>;
type EventTag<From extends ReadonlyArray<unknown>> = Inputs<From>["event"] extends infer E
  ? E extends { readonly _tag: infer T extends string }
    ? T
    : never
  : never;
/**
 * What a handler may be keyed by: an event tag, or a source's name to handle
 * every event from that source.
 */
export type HandlerKey<From extends ReadonlyArray<unknown>> = EventTag<From> | Inputs<From>["name"];
/** The inputs a handler keyed by `K` (an event tag or a source name) receives. */
export type InputFor<From extends ReadonlyArray<unknown>, K> =
  | Extract<Inputs<From>, { readonly event: { readonly _tag: K } }>
  | Extract<Inputs<From>, { readonly name: K }>;

/** The state of a view with state schema `S` (`null` without one). */
export type StateType<S> = S extends Schema.Top ? S["Type"] : null;
/** What a view emits: its declared events, or every event it consumes. */
export type Output<
  From extends ReadonlyArray<unknown>,
  Events extends ReadonlyArray<Event.Any>,
> = Events extends readonly [] ? Inputs<From>["event"] : Aggregate.InstanceOf<Events[number]>;

/**
 * Where an input is delivered and what handlers receive alongside it.
 */
export interface Routing<I> {
  readonly event: I extends { readonly event: infer E } ? E : never;
  /** The source instance the event came from. */
  readonly source: I extends { readonly source: infer R } ? R : never;
  /** For a view source: its state after the event. */
  readonly state: I extends { readonly state: infer S } ? S : never;
  readonly envelope: Aggregate.Envelope;
}

/**
 * The context passed to `evolve` and `emit` handlers.
 */
export interface HandlerContext<Key extends Key.Any, I> {
  /** The view instance being updated: a ref, or the value of a Schema key. */
  readonly key: Key.RefOf<Key>;
  /** The source instance the event came from. */
  readonly source: Routing<I>["source"];
  /** For a view source: its state after the event. */
  readonly state: Routing<I>["state"];
  readonly envelope: Aggregate.Envelope;
  /** The commit time of the originating event. */
  readonly at: DateTime.Utc;
}

/** The context passed to `emit` handlers. */
export interface EmitContext<Key extends Key.Any, I, St> extends HandlerContext<Key, I> {
  /** This view's state before the event. */
  readonly before: St;
  /** This view's state after the event (`null` if it was deleted). */
  readonly after: St | null;
}

/** Picks the key an input goes to, or `undefined` for none. */
export type KeyFn<Key extends Key.Any, I> = (routing: Routing<I>) => Key.RefOf<Key> | undefined;
type EvolveFn<St, Key extends Key.Any, I> = (
  state: St,
  event: Routing<I>["event"],
  context: HandlerContext<Key, I>,
) => St | null;
type EmitFn<St, Key extends Key.Any, I, Out> = (
  event: Routing<I>["event"],
  context: EmitContext<Key, I, St>,
) => Out | ReadonlyArray<Out> | undefined;

/** A handler, or one handler per route named in `keyOf`. */
export type Routed<F> = F | { readonly [route: string]: F };

/**
 * The pure definition of a view.
 */
export interface Definition<
  From extends ReadonlyArray<Source>,
  Key extends Key.Any,
  S extends Schema.Top | undefined,
  Events extends ReadonlyArray<Event.Any>,
  Computed extends Record<string, unknown>,
  Ms extends Middleware.List = readonly [],
  Rejects extends ReadonlyArray<Rejection.Any> = readonly [],
> extends Read.Contract<Key.RefOf<Key>, StateType<S> | null, Ms, Rejects> {
  /** The aggregates and views this view consumes. */
  readonly from: From;
  /**
   * What keys this view's instances: an aggregate, whose refs key them, or a
   * string Schema (such as an org id), whose values key them with no
   * aggregate behind them.
   */
  readonly key: Key;
  /**
   * Which instance each input updates, keyed by event tag or source name. May
   * be omitted for a source keyed by the same aggregate or Schema (the source
   * is the key). Return a ref (an aggregate key) or a value (a Schema key), or
   * an object of named routes to update several instances; each route then
   * gets its own `evolve` and `emit` handler.
   */
  readonly keyOf?: {
    readonly [K in HandlerKey<From>]?: Routed<KeyFn<Key, InputFor<From, K>>>;
  };
  /** Schema of the view's state. Omit it for a view that only emits events. */
  readonly state?: S;
  /** The state every instance starts from. */
  readonly initial?: StateType<S>;
  /**
   * Fold inputs into state, keyed by event tag or source name. Return `null`
   * to delete the instance.
   */
  readonly evolve?: {
    readonly [K in HandlerKey<From>]?: Routed<EvolveFn<StateType<S>, Key, InputFor<From, K>>>;
  };
  /**
   * The events this view emits. Without `events`, a view emits every event it
   * applies, unchanged.
   */
  readonly events?: Events;
  /**
   * Derive the events to emit for an input, keyed by event tag or source name.
   * Runs after `evolve`, with the state before and after. A declared event
   * with no `emit` handler passes through unchanged.
   */
  readonly emit?: {
    readonly [K in HandlerKey<From>]?: Routed<
      EmitFn<StateType<S>, Key, InputFor<From, K>, Aggregate.InstanceOf<Events[number]>>
    >;
  };
  /** Values derived from state when read. */
  readonly computed?: ComputedFns<StateType<S>, Computed>;
  /**
   * Bump it whenever you change what the view computes (`evolve`, `emit`,
   * `keyOf`, `state`, the events or sources it reads): every key is computed
   * again from the history, and so is every view and projection that reads
   * this one. Only ever increase it.
   *
   * A view keyed by the one aggregate it reads is rebuilt in place: the deploy
   * waits for nothing, and each key re-reads its own instance's events the
   * first time it is touched. Any other view is rebuilt from the history
   * before the deploy finishes.
   *
   * @default 0
   */
  readonly version?: number;
}

/** Derived-value functions of a view. */
export type ComputedFns<State, Computed> = {
  readonly [K in keyof Computed]: (state: State) => Computed[K];
};

/**
 * An event a view emitted, with the view's state after it.
 */
export interface Entry<S, E, Id = string> {
  readonly event: E;
  /** The view's state after the event (`null` if deleted, or for a view without state). */
  readonly state: S | null;
  /** `id` is the view key, `stream` is `View/key`, `seq` counts the key's events. */
  readonly envelope: Aggregate.Envelope<Id>;
}

/**
 * A page of entries.
 */
export interface Page<Entry> {
  readonly entries: ReadonlyArray<Entry>;
  /** Pass as `after` to continue; `null` when there are no more entries. */
  readonly cursor: number | null;
}

/**
 * Options for watching a view key.
 */
export interface WatchOptions<S> {
  /** Only emit states matching this filter; emits `none` when filtered out. */
  readonly where?: Filter<S>;
}

/**
 * How much of the history recorded before a view or projection (or before its
 * current version) has reached it. A consumer added to a model that already
 * has events, or rebuilt by bumping its version, receives that history first.
 */
export interface History {
  /** Every event recorded before it has reached it: its answers cover the whole history. */
  readonly complete: boolean;
}

/**
 * The read API of a view, obtained with `yield* MyView`.
 */
export interface Host<S, Key extends Key.Any, E> {
  /**
   * Whether the history recorded before this view, or before its current
   * version, has reached it. Until it has, its answers cover only part of
   * the history: a screen can say so, or hold its reads until it is complete.
   */
  readonly history: Effect.Effect<History>;
  /** Read the current state of a key. `none` if it does not exist. */
  readonly query: (
    key: Key.RefOf<Key>,
    options?: {
      /** Wait until the view has applied this write (a command's `stream` and `version`). */
      readonly atLeast?: { readonly stream: string; readonly version: number };
      readonly timeout?: Duration.Input;
    },
  ) => Effect.Effect<Option.Option<S>, ConsistencyTimeout>;
  /**
   * Read the current state of a key together with its cursor: the `seq` of
   * the last event the key emitted when the state was read. Pass the cursor
   * to `events` as `after` to follow every later change once.
   */
  readonly snapshot: (
    key: Key.RefOf<Key>,
    options?: {
      /** Wait until the view has applied this write (a command's `stream` and `version`). */
      readonly atLeast?: { readonly stream: string; readonly version: number };
      readonly timeout?: Duration.Input;
    },
  ) => Effect.Effect<Read.Snapshot<S | null>, ConsistencyTimeout>;
  /** Wait until a key's state matches a filter. */
  readonly waitFor: (
    key: Key.RefOf<Key>,
    where: Filter<S>,
    options: { readonly timeout: Duration.Input },
  ) => Effect.Effect<S, WaitTimeout>;
  /** The current state, then every change. */
  readonly watch: (
    key: Key.RefOf<Key>,
    options?: WatchOptions<S>,
  ) => Stream.Stream<Option.Option<S>>;
  /**
   * Follow a changing set of keys derived from a parent stream, emitting the
   * parent together with the current state of every key that exists and
   * matches `where`.
   */
  readonly watchEach: <P, Err, R>(
    parent: Stream.Stream<P, Err, R>,
    keysOf: (parent: P) => ReadonlyArray<Key.RefOf<Key>>,
    options?: WatchOptions<S>,
  ) => Stream.Stream<readonly [P, ReadonlyArray<readonly [Key.RefOf<Key>, S]>], Err, R>;
  /**
   * Every event the key emitted, with the state after it: history (from
   * `after`, a cursor or entry `seq`), then live.
   */
  readonly events: (
    key: Key.RefOf<Key>,
    options?: { readonly after?: number; readonly where?: Filter<E> },
  ) => Stream.Stream<Entry<S, E, Key.IdOf<Key>>>;
  /** A page of the key's emitted events, 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<S, E, Key.IdOf<Key>>>>;
}

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

/**
 * A read model: events folded into state per key, kept up to date as new
 * events arrive. A view can emit events of its own, route one event to
 * several keys, and decide who may read it.
 *
 * ### Folding events into state
 * **Example:** An account's balance
 * ```typescript
 * import * as Domain from "@alchemy.run/domain";
 * import * as Schema from "effect/Schema";
 * import { Account } from "./Account.ts";
 *
 * export class AccountSummary extends Domain.View("AccountSummary", {
 *   from: [Account],
 *   key: Account,
 *   state: Schema.Struct({ balance: Schema.Int }),
 *   initial: { balance: 0 },
 *   evolve: {
 *     MoneyDeposited: (v, e) => ({ ...v, balance: e.balanceAfter }),
 *     MoneyWithdrawn: (v, e) => ({ ...v, balance: e.balanceAfter }),
 *   },
 * }) {}
 * ```
 *
 * ### Emitting events
 * **Example:** One statement line per movement
 * ```typescript
 * import * as Domain from "@alchemy.run/domain";
 * import * as Schema from "effect/Schema";
 * import { Account } from "./Account.ts";
 *
 * export class StatementLine extends Domain.Event("StatementLine", {
 *   kind: Schema.Literals(["deposit", "withdrawal"]),
 *   amount: Schema.Int,
 * }) {}
 *
 * export class Statement extends Domain.View("Statement", {
 *   from: [Account],
 *   key: Account,
 *   events: [StatementLine],
 *   emit: {
 *     MoneyDeposited: (e) => new StatementLine({ kind: "deposit", amount: e.amount }),
 *     MoneyWithdrawn: (e) => new StatementLine({ kind: "withdrawal", amount: e.amount }),
 *   },
 * }) {}
 * ```
 *
 * ### Routing one event to several keys
 * **Example:** A transfer appears on both accounts
 * ```typescript
 * keyOf: {
 *   TransferRequested: {
 *     out: ({ event }) => Account.ref(event.from),
 *     in: ({ event }) => Account.ref(event.to),
 *   },
 * },
 * ```
 *
 * ### Keying by a value
 * **Example:** One schedule per org, with no Org aggregate
 * ```typescript
 * key: OrgId, // a string Schema
 * keyOf: { Tour: ({ event }) => event.orgId },
 * ```
 *
 * ### Validating reads
 * **Example:** Only the owner may read
 * ```typescript
 * middleware: [Session],
 * rejects: [NotOwner],
 * validate: Effect.fn(function* (_request, summary) {
 *   const actor = yield* CurrentActor;
 *   if (summary?.owner && summary.owner !== actor.customerId) return yield* new NotOwner();
 * }),
 * ```
 *
 * @primitive
 */
export const make = <
  const Name extends string,
  const From extends ReadonlyArray<Source>,
  Key extends Key.Any,
  S extends Schema.Top | undefined = undefined,
  const Events extends ReadonlyArray<Event.Any> = readonly [],
  Computed extends Record<string, unknown> = {},
  const Ms extends Middleware.List = readonly [],
  const Rejects extends ReadonlyArray<Rejection.Any> = readonly [],
>(
  name: Name,
  definition: Definition<From, Key, S, Events, Computed, Ms, Rejects>,
): ViewClass<
  Name,
  Definition<From, Key, S, Events, Computed, Ms, Rejects>,
  S,
  StateType<S>,
  Key,
  ComputedFns<StateType<S>, Computed>,
  Output<From, Events>
> => {
  const Tag = Context.Service<ViewKey<Name>, Host<StateType<S>, Key, Output<From, Events>>>()(
    `alchemy/Domain/View/${name}`,
  );
  return class extends Tag {
    static readonly kind = "View" as const;
    static readonly viewName: Name = name;
    static readonly definition: Definition<From, Key, S, Events, Computed, Ms, Rejects> =
      definition;
    /** The view's state schema. */
    static readonly State = definition.state;
    /** Derived values, computed from a state when read. */
    static readonly computed = definition.computed ?? {};
    /** Apply one input to one key's state, as the server's view does. */
    static evolve(state: unknown, input: LocalViewInput) {
      return evolveView({ definition }, state, input);
    }
  } as unknown as ViewClass<
    Name,
    Definition<From, Key, S, Events, Computed, Ms, Rejects>,
    S,
    StateType<S>,
    Key,
    ComputedFns<StateType<S>, Computed>,
    Output<From, Events>
  >;
};

/** One source input, with the source's state optional (aggregates attach none). */
type LocalSourceInput<I> = I extends {
  readonly name: infer N;
  readonly event: infer E;
  readonly source: infer R;
  readonly state: infer S;
}
  ? { readonly name: N; readonly event: E; readonly source: R; readonly state?: S }
  : never;

/** What {@link ViewClass.evolve} applies: a source input, its envelope, and the key. */
export type LocalInput<Def, Key extends Key.Any> = (Def extends {
  readonly from: infer From extends ReadonlyArray<unknown>;
}
  ? LocalSourceInput<Inputs<From>>
  : never) & {
  readonly envelope: Aggregate.Envelope;
  /** The key to update: defaults to what `keyOf` returns, or to the source. */
  readonly key?: Key.RefOf<Key>;
};

/**
 * The class type returned by {@link make}.
 */
export interface ViewClass<
  Name extends string,
  Def,
  S extends Schema.Top | undefined,
  St,
  Key extends Key.Any,
  Computed,
  Out,
> extends Context.ServiceClass<ViewKey<Name>, string, Host<St, Key, Out>> {
  readonly kind: "View";
  readonly viewName: Name;
  readonly definition: Def;
  /** The view's state schema. */
  readonly State: S;
  /** Derived values, computed from a state when read. */
  readonly computed: Computed;
  /**
   * Apply one input (an event of a source) to one key's state, with this
   * view's own `keyOf` and `evolve`: the state the server's view will hold
   * after it. Use it with the events of `Aggregate.predict` to show a view's
   * next state before the server answers. `key` defaults to what `keyOf`
   * returns, or to the source; it is required for a view with routes.
   *
   * **Example:** The next balance of a predicted withdrawal
   * ```typescript
   * const next = outcome.events.reduce(
   *   (state, event, i) =>
   *     AccountSummary.evolve(state, {
   *       name: "Account",
   *       event,
   *       source: Account.ref(id),
   *       envelope: outcome.envelopes[i],
   *     }),
   *   summary,
   * );
   * ```
   */
  evolve(state: St | null, input: LocalInput<Def, Key>): St | null;
  readonly "~state": St;
  readonly "~events": Out;
}