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

import type * as Effect from "effect/Effect";
import * as Schema from "effect/Schema";
import type * as Aggregate from "./Aggregate.ts";
import type * as Middleware from "./Middleware.ts";
import type * as Rejection from "./Rejection.ts";

/** How a client reads a View or an aggregate. */
export type Mode = "get" | "watch" | "events" | "list";

/**
 * What `watch` sends: the key's state and the cursor it is valid at, the
 * `seq` of the last event the key had when the state was read (`0` before any).
 */
export interface Snapshot<S> {
  readonly state: S;
  /** Pass as `after` to `events` to receive every later event, once. */
  readonly cursor: number;
}

/**
 * The frame `events` sends once it has sent the key's history: every event up
 * to `cursor` was delivered (or filtered out), and what follows is live. A
 * read that reconnects sends it again after the events it missed.
 */
export const CaughtUp = Schema.TaggedStruct("CaughtUp", {
  /** The `seq` of the last event of the history (`0` for none); resume `events` after it. */
  cursor: Schema.Number,
});
export type CaughtUp = typeof CaughtUp.Type;

/** Is a frame of `events` the {@link CaughtUp} marker? */
export const isCaughtUp = <A extends object>(frame: A | CaughtUp): frame is CaughtUp =>
  "_tag" in frame && frame._tag === "CaughtUp";

/**
 * Is a frame of `events` an event, not the {@link CaughtUp} marker? Drops the
 * marker from a feed: `Stream.filter(Domain.Read.isEvent)`.
 */
export const isEvent = <A extends object>(frame: A | CaughtUp): frame is Exclude<A, CaughtUp> =>
  !isCaughtUp(frame);

/**
 * A client's read, as `validate` sees it: what is being read and how. The
 * client's own filters are not part of it: they only narrow what a permitted
 * read returns, so access never depends on analyzing them.
 */
export interface Request<Ref> {
  readonly mode: Mode;
  /** The key being read: a view key, or an aggregate instance. */
  readonly key: Ref;
}

/**
 * The read contract of a View or aggregate exposed in an Api: the middleware
 * that guards it, the rejections a read may fail with, and `validate`, which
 * judges each read. Like a Command, a View is a security boundary: to show an
 * audience different data, make another View.
 */
export interface Contract<
  Ref,
  St,
  Ms extends Middleware.List,
  Rejects extends ReadonlyArray<Rejection.Any>,
> {
  /**
   * Middleware that guards reads when an Api exposes them, in order. What it
   * provides is what `validate` may read.
   */
  readonly middleware?: Ms;
  /** The rejections a read may fail with; they reach the client typed. */
  readonly rejects?: Rejects;
  /**
   * Judge a read from who is asking (what `middleware` provides), the key and
   * that key's state. Runs on every `get` and `list`, and on every change
   * while a client watches: failing ends the watch with that rejection.
   * Without it, anyone who reaches the Api may read every key.
   */
  readonly validate?: (
    request: Request<Ref>,
    state: St,
  ) => Effect.Effect<void, Aggregate.InstanceOf<Rejects[number]>, Middleware.Provides<Ms>>;
}

/** The read contract a View or aggregate declares, widened. @internal */
export interface AnyContract {
  readonly middleware?: Middleware.List;
  readonly rejects?: ReadonlyArray<Rejection.Any>;
  readonly validate?: (request: never, state: never) => Effect.Effect<void, unknown, unknown>;
}