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

import { CurrentActivity } from "alchemy/WorkflowEncoding";
import * as Cause from "effect/Cause";
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 * as Effect from "effect/Effect";
import * as Option from "effect/Option";
import * as Schema from "effect/Schema";
import type * as Command from "./Command.ts";
import { DefinitionError, UnhandledCommand } from "./DefinitionError.ts";
import type * as Event from "./Event.ts";
import { judge, settle, targetId as internalTargetId } from "./internal.ts";
import type * as Middleware from "./Middleware.ts";
import type * as Read from "./Read.ts";
import type * as Rejection from "./Rejection.ts";
import * as RequestContext from "./RequestContext.ts";
import type * as Telemetry from "./Telemetry.ts";

/**
 * The instance type of a class: `InstanceOf<typeof NotOwner>` is `NotOwner`.
 * Distributes over a union of classes.
 */
export type InstanceOf<C> = C extends abstract new (...args: any[]) => infer I ? I : never;

/**
 * Context passed to every `decide` handler.
 */
export interface DecideContext<Id> {
  /** The id of the aggregate instance handling the command. */
  readonly id: Id;
  /** The id the command was sent with; its events' envelopes carry it too. */
  readonly commandId: string;
  /** The stream the command's events commit to, e.g. `Account/a-1`. */
  readonly stream: string;
  /** The stream's version before this decision: `0` for a new instance. */
  readonly version: number;
  /** The time the command is being handled. Controlled by stories via `clock`. */
  readonly now: DateTime.Utc;
}

/**
 * Metadata recorded with every committed event. Its schema is what Api clients
 * decode, so the wire carries every field.
 */
export const Envelope = Schema.Struct({
  /** The id of the aggregate instance that committed the event. */
  id: Schema.String,
  /** The stream the event belongs to, e.g. `Account/a-1`. */
  stream: Schema.String,
  /** The event's sequence number within its stream, starting at 1. */
  seq: Schema.Number,
  /** The commit time. */
  at: Schema.DateTimeUtc,
  /** The id of the command that produced the event. */
  commandId: Schema.String,
  /**
   * The id of the first command in the chain that led here: the same for a
   * command, the events it records, and every reaction and command they cause.
   */
  correlationId: Schema.String,
});

/** An {@link Envelope} whose `id` is the aggregate's (branded) id. */
export type Envelope<Id = string> = typeof Envelope.Type & { readonly id: Id };

/**
 * The outcome of a successfully handled command.
 */
export interface Receipt<Ev = unknown, Reply = unknown> {
  /** The stream the command was applied to, e.g. `Account/a-1`. */
  readonly stream: string;
  /** The stream's version (last sequence number) after the command. */
  readonly version: number;
  /** The events committed by the command (empty for an accepted no-op). */
  readonly events: ReadonlyArray<Ev>;
  /** The command's reply, if it declares one. */
  readonly reply: Reply;
}

/**
 * What {@link Client.schedule} returns: the pending command's id, to
 * `unschedule` it by, and when it is due.
 */
export interface ScheduleReceipt {
  /** The command id: the one passed in `options`, or the one derived for it. */
  readonly commandId: string;
  /** When the command is due, on the platform's clock. */
  readonly at: DateTime.Utc;
}

type ByTag<U, T> = Extract<U, { readonly tag: T }>;
type ReplyTags<C extends Command.Any> = C extends {
  readonly reply: Schema.Top;
  readonly tag: infer T extends string;
}
  ? T
  : never;

type IdSchema = Schema.Top & { readonly Type: string; readonly Encoded: string };

/**
 * What `decide` returns for a command: events, a rejection, or an Effect of
 * either. The Effect may read what the command's middleware provides.
 */
export type Decision<C extends Command.Any> =
  | ReadonlyArray<InstanceOf<C["events"][number]>>
  | InstanceOf<C["rejects"][number]>
  | Effect.Effect<
      ReadonlyArray<InstanceOf<C["events"][number]>>,
      InstanceOf<C["rejects"][number]>,
      Command.ContextOf<C>
    >;

/** The event classes a set of commands may record. */
export type EventsOf<C extends ReadonlyArray<Command.Any>> = C[number]["events"][number];

/**
 * The pure definition of an aggregate: identity, state, the commands it
 * decides and the events it folds. Its events are those its commands declare.
 */
export interface Definition<
  Id extends IdSchema,
  S extends Schema.Top,
  C extends ReadonlyArray<Command.Any>,
  Ms extends Middleware.List = readonly [],
  Rejects extends ReadonlyArray<Rejection.Any> = readonly [],
  E extends Event.Any = EventsOf<C>,
> {
  /** Schema of the aggregate id (a string or branded string). */
  readonly id: Id;
  /** Schema of the aggregate's state. Used to persist snapshots. */
  readonly state: S;
  /** The state of an instance that has never committed an event. */
  readonly initial: S["Type"];
  /** Every command this aggregate handles, each declaring the events it records. */
  readonly commands: C;
  /**
   * One handler per command: returns the events to commit (from the command's
   * declared events), an empty array for an accepted no-op, or one of the
   * command's declared rejections. A handler may be an Effect that reads the
   * context its command's middleware provides (e.g. `yield* CurrentActor`)
   * and fails with a rejection; it may require nothing else.
   */
  readonly decide: {
    readonly [T in C[number]["tag"]]: (
      state: S["Type"],
      command: InstanceOf<ByTag<C[number], T>>,
      ctx: DecideContext<Id["Type"]>,
    ) => Decision<ByTag<C[number], T>>;
  };
  /**
   * One handler per event: folds a committed event into state. It covers
   * every state and never fails: `decide` refuses a command with a rejection
   * before it records an event, so a handler keeps a state its event can't
   * follow.
   */
  readonly evolve: {
    readonly [T in E["tag"]]: (
      state: S["Type"],
      event: InstanceOf<ByTag<E, T>>,
      envelope: Envelope<Id["Type"]>,
    ) => S["Type"];
  };
  /**
   * One handler per command that declares a reply: computes it from the
   * updated state and the committed events. Like `evolve`, it covers every
   * state and never fails.
   */
  readonly reply?: {
    readonly [T in ReplyTags<C[number]>]: (
      state: S["Type"],
      events: ReadonlyArray<InstanceOf<E>>,
    ) => NonNullable<ByTag<C[number], T>["reply"]>["Type"];
  };
  /**
   * Let an Api expose this aggregate's state and committed events to clients
   * (`get`, `watch`, `events`): its middleware, rejections, and `validate`,
   * which judges each read against the instance's current state.
   */
  readonly read?: Read.Contract<{ readonly id: Id["Type"] }, S["Type"], Ms, Rejects>;
}

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

/**
 * Options for {@link Client.send}.
 */
export interface SendOptions {
  /** Idempotency key. A command with an already-seen id returns the original receipt. */
  readonly commandId?: string;
}

/**
 * The instance already handled a command with this id, so it can no longer
 * be scheduled or cancelled: a deadline that fired before it was cancelled,
 * or a command id that was already sent.
 */
export class AlreadyExecuted extends Data.TaggedError("AlreadyExecuted")<{
  readonly aggregate: string;
  readonly id: string;
  readonly commandId: string;
}> {}

/** The scheduled command with this id was already cancelled. */
export class AlreadyCancelled extends Data.TaggedError("AlreadyCancelled")<{
  readonly aggregate: string;
  readonly id: string;
  readonly commandId: string;
}> {}

/** No command was ever scheduled with this id on the instance. */
export class NotScheduled extends Data.TaggedError("NotScheduled")<{
  readonly aggregate: string;
  readonly id: string;
  readonly commandId: string;
}> {}

/**
 * Options for {@link Client.schedule}: when to send, absolutely or after a delay.
 */
export type ScheduleOptions = SendOptions &
  (
    | { readonly at: DateTime.Utc; readonly after?: never }
    | { readonly after: Duration.Input; readonly at?: never }
  );

/**
 * When a scheduled command is due: an epoch-millisecond time, or a delay the
 * platform measures on its own clock (stories control it with `clock`).
 */
export type Due = { readonly at: number } | { readonly afterMillis: number };

/**
 * Metadata a platform receives with every command.
 */
export interface SendMeta {
  readonly commandId: string;
  /** The command context services the sender provided, encoded. */
  readonly context: RequestContext.Json;
  /** The flow the command belongs to (see {@link Envelope.correlationId}). */
  readonly correlationId?: string;
  /** The span that sent the command, so the aggregate's span continues its trace. */
  readonly trace?: Telemetry.TraceJson;
  /** Link to `trace` instead of continuing it: the command runs later (scheduled). */
  readonly link?: boolean;
}

type AnyHandlers = { readonly [tag: string]: (...args: never[]) => unknown };

/**
 * The widened shape of every {@link Definition}.
 */
export interface AnyDefinition {
  readonly id: IdSchema;
  readonly state: Schema.Top;
  readonly initial: unknown;
  readonly commands: ReadonlyArray<Command.Any>;
  readonly events: ReadonlyArray<Event.Any>;
  readonly decide: AnyHandlers;
  readonly evolve: AnyHandlers;
  readonly reply?: AnyHandlers;
  readonly read?: Read.AnyContract;
}

/** An aggregate instance to address: its id, or a ref carrying it. */
export type Target<Def extends AnyDefinition> =
  | Def["id"]["Type"]
  | { readonly id: Def["id"]["Type"] };

type CommandClassOf<Def extends AnyDefinition, Cmd> = ByTag<
  Def["commands"][number],
  Cmd extends { readonly _tag: infer T } ? T : never
>;

type ReplyOf<C> = C extends { readonly reply: infer R }
  ? R extends Schema.Top
    ? R["Type"]
    : void
  : void;

/**
 * The runtime API of an aggregate, obtained with `yield* MyAggregate`. Resolve
 * it once while building a policy or an operation, then call it per event or
 * request; its methods require nothing.
 *
 * **Example:** Sending a command
 * ```typescript
 * const accounts = yield* Account;
 * const { reply } = yield* accounts.send(accountId, new WithdrawMoney({ amount: 30 }));
 * ```
 */
export interface Client<Def extends AnyDefinition> {
  /**
   * Send a command. Succeeds with a {@link Receipt} once the resulting events
   * are committed, or fails with one of the command's declared rejections.
   * Requires the context the command's middleware provides (e.g. the current
   * actor): an Api's middleware provides it, other senders provide it.
   */
  readonly send: <Cmd extends InstanceOf<Def["commands"][number]>>(
    target: Target<Def>,
    command: Cmd,
    options?: SendOptions,
  ) => Effect.Effect<
    Receipt<InstanceOf<Def["events"][number]>, ReplyOf<CommandClassOf<Def, Cmd>>>,
    InstanceOf<CommandClassOf<Def, Cmd>["rejects"][number]>,
    Command.ContextOf<CommandClassOf<Def, Cmd>>
  >;
  /**
   * Send a command later, durably: a deadline or a reminder. Only commands
   * that never reject can be scheduled, since nobody is waiting to handle a
   * rejection when it fires; such a command reports a fact ("the approval
   * window closed") and records nothing when it no longer applies.
   * Scheduling again with the same command id replaces the earlier one.
   * Returns the command id to `unschedule` it by, and when it is due. Fails with `AlreadyExecuted` when the instance already handled a command
   * with that id.
   */
  readonly schedule: <Cmd extends InstanceOf<Schedulable<Def>>>(
    target: Target<Def>,
    command: Cmd,
    options: ScheduleOptions,
  ) => Effect.Effect<ScheduleReceipt, AlreadyExecuted, Command.ContextOf<CommandClassOf<Def, Cmd>>>;
  /**
   * Cancel a pending scheduled command by the command id it was scheduled
   * with. Once it succeeds, the command never runs. Fails with
   * `AlreadyExecuted` when the command ran first, `AlreadyCancelled` when it
   * was cancelled before, and `NotScheduled` when nothing was scheduled with
   * that id.
   */
  readonly unschedule: (
    target: Target<Def>,
    commandId: string,
  ) => Effect.Effect<void, AlreadyExecuted | AlreadyCancelled | NotScheduled>;
  /** Read the current state of an instance. */
  readonly state: (target: Target<Def>) => Effect.Effect<Def["state"]["Type"]>;
}

/** The commands of a definition that never reject, so can be scheduled. */
export type Schedulable<Def extends AnyDefinition> = Extract<
  Def["commands"][number],
  { readonly rejects: readonly [] }
>;

/**
 * The untyped form of {@link Client} the framework implements.
 *
 * @internal
 */
export interface ClientImpl {
  readonly send: (
    target: unknown,
    command: { readonly _tag: string },
    options?: SendOptions,
  ) => Effect.Effect<Receipt, unknown>;
  readonly schedule: (
    target: unknown,
    command: { readonly _tag: string },
    options: ScheduleOptions,
  ) => Effect.Effect<ScheduleReceipt, AlreadyExecuted>;
  readonly unschedule: (
    target: unknown,
    commandId: string,
  ) => Effect.Effect<void, AlreadyExecuted | AlreadyCancelled | NotScheduled>;
  readonly state: (target: unknown) => Effect.Effect<unknown>;
}

/**
 * Structural constraint satisfied by every aggregate class.
 */
export interface Any extends Context.Key<unknown, unknown> {
  readonly kind: "Aggregate";
  readonly aggregateName: string;
  readonly definition: AnyDefinition;
}

/** The id type of an aggregate class. */
export type IdOf<A extends Any> = A["definition"]["id"]["Type"];
/** The state type of an aggregate class. */
export type StateOf<A extends Any> = A["definition"]["state"]["Type"];
/** The event instance types of an aggregate class. */
export type EventOf<A extends Any> = InstanceOf<A["definition"]["events"][number]>;
/** The command instance types of an aggregate class. */
export type CommandOf<A extends Any> = InstanceOf<A["definition"]["commands"][number]>;
/** The requirement identifier of an aggregate class. */
export type Identifier<A extends Any> = A extends Context.Key<infer I, unknown> ? I : never;

/**
 * Options for {@link predict}: what the server would give `decide`. A command
 * with middleware needs `context`: what its middleware provides, from a
 * client-side Layer of the same services.
 */
export type PredictOptions<Id = string, R = never> = PredictBase<Id> &
  ([R] extends [never]
    ? { readonly context?: Context.Context<never> }
    : { readonly context: Context.Context<R> });

interface PredictBase<Id> {
  /** The id of the instance the command targets. */
  readonly id: Id;
  /** The time the command is decided at (the server stamps commands with its clock). */
  readonly now: DateTime.Utc;
  /** The state's version: `decide` sees it, and predicted envelopes continue from it. Defaults to `0`. */
  readonly version?: number;
  /** The id the command will be sent with, for `decide` and the predicted envelopes. Defaults to `""`. */
  readonly commandId?: string;
  /** Defaults to the command id. */
  readonly correlationId?: string;
}

/**
 * What the aggregate would do with a command, decided locally: the events it
 * would record and the state after them, the rejection it would return, or
 * `Unpredictable` when only the server can tell. `cause` says why: `decide`
 * waited on something asynchronous (the server awaits it; `predict` is
 * synchronous), died, or broke its command's declaration through a cast (a
 * `DefinitionError`, which the server dies on).
 */
export type Prediction<State, Ev, Rej, Id = string> =
  | {
      readonly _tag: "Accepted";
      readonly events: ReadonlyArray<Ev>;
      /** One envelope per event, as the server would stamp it (`seq` from `version`). */
      readonly envelopes: ReadonlyArray<Envelope<Id>>;
      readonly state: State;
    }
  | { readonly _tag: "Rejected"; readonly rejection: Rej }
  | { readonly _tag: "Unpredictable"; readonly cause: Cause.Cause<unknown> };

/**
 * Run an aggregate's own `decide` and `evolve` for one command, without a
 * platform: the same events and state, or the same rejection, as the server
 * for the same state, id and time. Use it to show a command's outcome before
 * the server answers.
 *
 * An effectful decision runs here synchronously, as the kernel runs it: a
 * rejection fails with itself, and a `decide` that suspends or dies gives
 * `Unpredictable`. `predict` never throws.
 */
export const predict = (
  aggregate: Any,
  state: unknown,
  command: { readonly _tag: string },
  options: PredictOptions,
): Prediction<unknown, { readonly _tag: string }, { readonly _tag: string }> => {
  const def = aggregate.definition;
  const cls = def.commands.find((c) => c.tag === command._tag);
  const decide = def.decide[command._tag] as
    | ((state: unknown, command: unknown, ctx: DecideContext<unknown>) => unknown)
    | undefined;
  if (!cls || !decide) {
    return {
      _tag: "Unpredictable",
      cause: Cause.die(
        new DefinitionError({
          reason: new UnhandledCommand({
            aggregate: aggregate.aggregateName,
            command: command._tag,
          }),
        }),
      ),
    };
  }
  const version = options.version ?? 0;
  const commandId = options.commandId ?? "";
  const stream = `${aggregate.aggregateName}/${String(options.id)}`;
  let decision = decide(state, command, {
    id: options.id,
    now: options.now,
    commandId,
    stream,
    version,
  });
  if (Effect.isEffect(decision)) {
    const settled = decision.pipe(
      Effect.provideContext((options.context ?? Context.empty()) as Context.Context<unknown>),
      Effect.runSyncExit,
      settle,
    );
    if (settled._tag === "Failed") return { _tag: "Unpredictable", cause: settled.cause };
    decision = settled.decision;
  }
  const judged = judge(aggregate.aggregateName, cls, decision);
  if (judged._tag === "Undeclared")
    return { _tag: "Unpredictable", cause: Cause.die(judged.error) };
  if (judged._tag === "Rejected") return judged;
  const envelopes: Array<Envelope> = [];
  let next = state;
  judged.events.forEach((event, index) => {
    const envelope: Envelope = {
      id: options.id,
      stream,
      seq: version + index + 1,
      at: options.now,
      commandId,
      correlationId: options.correlationId ?? commandId,
    };
    envelopes.push(envelope);
    next = (def.evolve[event._tag] as (s: unknown, e: unknown, env: unknown) => unknown)(
      next,
      event,
      envelope,
    );
  });
  return { _tag: "Accepted", events: judged.events, envelopes, state: next };
};

const RefClass = Symbol.for("alchemy/Domain/Ref.class");

/**
 * A typed address of one aggregate instance: aggregate type plus id.
 */
export interface Ref<A extends Any = Any> {
  readonly aggregate: A["aggregateName"];
  readonly id: IdOf<A>;
  readonly [RefClass]: A;
}

/** @internal */
export const refClass = <A extends Any>(ref: Ref<A>): A => ref[RefClass];

/**
 * One entity that decides, such as a bank account: a consistency boundary.
 * It takes a command, checks it against its current state, and records events
 * or returns a rejection. Each instance handles one command at a time, and
 * its events, new state and reply commit together.
 *
 * ### Deciding and evolving
 * **Example:** An account that refuses overdrafts
 * ```typescript
 * import * as Domain from "@alchemy.run/domain";
 * import * as Schema from "effect/Schema";
 *
 * export const AccountId = Schema.String.pipe(Schema.brand("AccountId"));
 *
 * export class MoneyWithdrawn extends Domain.Event("MoneyWithdrawn", {
 *   amount: Schema.Int,
 *   balanceAfter: Schema.Int,
 * }) {}
 *
 * export class InsufficientFunds extends Domain.Rejection("InsufficientFunds", {
 *   balance: Schema.Int,
 *   requested: Schema.Int,
 * }) {}
 *
 * export class WithdrawMoney extends Domain.Command("WithdrawMoney", {
 *   target: AccountId,
 *   input: { amount: Schema.Int },
 *   events: [MoneyWithdrawn],
 *   rejects: [InsufficientFunds],
 *   reply: { balance: Schema.Int },
 * }) {}
 *
 * export class Account extends Domain.Aggregate("Account", {
 *   id: AccountId,
 *   state: Schema.Struct({ balance: Schema.Int }),
 *   initial: { balance: 0 },
 *   commands: [WithdrawMoney],
 *   decide: {
 *     WithdrawMoney: (s, cmd) =>
 *       cmd.amount > s.balance
 *         ? new InsufficientFunds({ balance: s.balance, requested: cmd.amount })
 *         : [new MoneyWithdrawn({ amount: cmd.amount, balanceAfter: s.balance - cmd.amount })],
 *   },
 *   evolve: {
 *     MoneyWithdrawn: (_, e) => ({ balance: e.balanceAfter }),
 *   },
 *   reply: {
 *     WithdrawMoney: (s) => ({ balance: s.balance }),
 *   },
 * }) {}
 * ```
 *
 * ### Authorizing in decide
 * A handler can be an `Effect.fn` that reads what the command's middleware
 * provides.
 *
 * **Example:** Only the owner may withdraw
 * ```typescript
 * decide: {
 *   WithdrawMoney: Effect.fn(function* (s, cmd) {
 *     const actor = yield* CurrentActor;
 *     if (actor.customerId !== s.owner) return yield* new NotOwner();
 *     return [new MoneyWithdrawn({ amount: cmd.amount, balanceAfter: s.balance - cmd.amount })];
 *   }),
 * },
 * ```
 *
 * ### Exposing reads
 * `read` lets an Api expose the aggregate itself, so a client can get it,
 * watch it, and follow its events. `validate` judges every read.
 *
 * **Example:** A read contract
 * ```typescript
 * read: {
 *   middleware: [Session],
 *   rejects: [NotOwner],
 *   validate: Effect.fn(function* (_request, s) {
 *     const actor = yield* CurrentActor;
 *     if (actor.customerId !== s.owner) return yield* new NotOwner();
 *   }),
 * },
 * ```
 *
 * ### Sending and scheduling
 * **Example:** From a policy or your own code
 * ```typescript
 * const accounts = yield* Account;
 * const { reply } = yield* accounts.send(accountId, new WithdrawMoney({ amount: 30 }));
 * yield* accounts.schedule(accountId, new SendStatement(), { after: "30 days", commandId: "statement" });
 * yield* accounts.unschedule(accountId, "statement"); // cancel it while it is pending
 * ```
 *
 * @primitive
 */
export const makeRef = <A extends Any>(aggregate: A, id: IdOf<A>): Ref<A> => {
  const ref = { aggregate: aggregate.aggregateName, id } as Ref<A>;
  Object.defineProperty(ref, RefClass, { value: aggregate, enumerable: false });
  return ref;
};

/** The stream id of a ref, e.g. `Account/a-1`. */
export const streamOf = (ref: { readonly aggregate: string; readonly id: string }) =>
  `${ref.aggregate}/${ref.id}`;

/** The id addressed by a {@link Target}. @internal */
export const targetId = internalTargetId;

/**
 * Deterministic command ids for sends made while a policy handles a trigger,
 * so a re-run of the same trigger is deduplicated by the target aggregate.
 *
 * @internal
 */
export class PolicyRun extends Context.Service<PolicyRun, { readonly next: () => string }>()(
  "alchemy/Domain/PolicyRun",
) {}

/**
 * The command id for a send: the caller's; inside a saga step, the step's
 * next id, so a step that runs again sends the same commands; the policy
 * run's next deterministic id; or a fresh one.
 *
 * @internal
 */
export const commandIdFor = (options: SendOptions | undefined): Effect.Effect<string> =>
  options?.commandId !== undefined
    ? Effect.succeed(options.commandId)
    : Effect.gen(function* () {
        // A step is the narrower scope: a saga started by a policy runs inside it.
        const step = yield* Effect.serviceOption(CurrentActivity);
        if (Option.isSome(step)) return step.value.next();
        const policy = yield* Effect.serviceOption(PolicyRun);
        if (Option.isSome(policy)) return policy.value.next();
        return yield* Effect.sync(() => crypto.randomUUID());
      });

/**
 * Declare an aggregate: a consistency boundary keyed by id that decides
 * commands against its current state and records events.
 *
 * The class is also a service tag: `yield* Customer` gives its {@link Client}
 * (`send`, `state`), provided by the Domain's Layer.
 *
 * **Example:** Declaring an aggregate
 * ```typescript
 * export class Customer extends Domain.Aggregate("Customer", {
 *   id: CustomerId,
 *   state: CustomerState,
 *   initial: { _tag: "New" },
 *   commands: [Register], // declares events: [CustomerRegistered]
 *   decide: {
 *     Register: (s, cmd) =>
 *       s._tag === "Registered" ? new AlreadyRegistered() : [new CustomerRegistered({ name: cmd.name })],
 *   },
 *   evolve: {
 *     CustomerRegistered: (_, e) => ({ _tag: "Registered", name: e.name }),
 *   },
 * }) {}
 *
 * const customers = yield* Customer;
 * yield* customers.send("c-1", new Register({ name: "sam" }));
 * ```
 */
export const make = <
  const Name extends string,
  Id extends IdSchema,
  S extends Schema.Top,
  const C extends ReadonlyArray<Command.Any>,
  const Ms extends Middleware.List = readonly [],
  const Rejects extends ReadonlyArray<Rejection.Any> = readonly [],
  // The declared `read`, inferred apart from `Definition` so the type records it.
  // Its constraint carries no members, so it never narrows how `read` is typed.
  const R extends object | undefined = object | undefined,
>(
  name: Name,
  definition: Definition<Id, S, C, Ms, Rejects> & TargetsMatch<Id, C> & { readonly read?: R },
): AggregateClass<Name, Resolved<Id, S, C, Ms, Rejects, ReadOf<R>>> => {
  const Tag = Context.Service<Key<Name>, Client<Resolved<Id, S, C, Ms, Rejects, ReadOf<R>>>>()(
    `alchemy/Domain/Aggregate/${name}`,
  );
  // oxlint-disable-next-line effecttsgo/schema-sync -- ids decode synchronously when building refs
  const decodeId = Schema.decodeUnknownSync(
    definition.id as unknown as Schema.Codec<unknown, unknown>,
  );
  return class extends Tag {
    static readonly kind = "Aggregate" as const;
    static readonly aggregateName: Name = name;
    static readonly definition: Resolved<Id, S, C, Ms, Rejects, ReadOf<R>> = {
      ...definition,
      events: [...new Set(definition.commands.flatMap((command) => command.events))],
    } as unknown as Resolved<Id, S, C, Ms, Rejects, ReadOf<R>>;
    /** Address one instance of this aggregate. */
    static ref<Self extends Any>(this: Self, id: Self["definition"]["id"]["Encoded"]): Ref<Self> {
      return makeRef(this, decodeId(id) as IdOf<Self>);
    }
    /** Decide a command locally. See {@link predict}. */
    static predict(
      this: Any,
      state: unknown,
      command: { readonly _tag: string },
      options: PredictOptions,
    ) {
      return predict(this, state, command, options);
    }
  } as unknown as AggregateClass<Name, Resolved<Id, S, C, Ms, Rejects, ReadOf<R>>>;
};

/**
 * A command whose `target` is the aggregate's `id`, both ways; any other
 * command becomes a message naming it.
 */
type CheckTarget<Id extends IdSchema, Cmd> = Cmd extends Command.Any
  ? [Id["Type"]] extends [Cmd["target"]["Type"]]
    ? [Cmd["target"]["Type"]] extends [Id["Type"]]
      ? Cmd
      : `${Cmd["tag"]}'s target must be this aggregate's id schema`
    : `${Cmd["tag"]}'s target must be this aggregate's id schema`
  : Cmd;

/**
 * Every command's `target` must be the aggregate's `id`: an Api decodes the
 * target with the command's schema and the aggregate decodes it with its own.
 * A mismatched command is a type error on its entry in `commands`.
 */
export type TargetsMatch<Id extends IdSchema, C extends ReadonlyArray<Command.Any>> = {
  readonly commands: { readonly [K in keyof C]: CheckTarget<Id, C[K]> };
};

/**
 * The `read` an aggregate declared, or `undefined`. With none declared, `R`
 * is left at its default, which includes `undefined`; a declared contract
 * never does.
 */
type ReadOf<R> = undefined extends R ? undefined : R;

/**
 * A definition with its events collected from its commands. `R` is the
 * `read` it declared, or `undefined`: an aggregate that declares one has a
 * required `read` in its type, so an Api can tell which aggregates it may
 * serve.
 */
export type Resolved<
  Id extends IdSchema,
  S extends Schema.Top,
  C extends ReadonlyArray<Command.Any>,
  Ms extends Middleware.List = readonly [],
  Rejects extends ReadonlyArray<Rejection.Any> = readonly [],
  R extends Read.AnyContract | undefined = Read.AnyContract | undefined,
> = Definition<Id, S, C, Ms, Rejects> & {
  readonly events: ReadonlyArray<EventsOf<C>>;
  readonly read: R;
};

/**
 * The class type returned by {@link make}.
 */
export interface AggregateClass<
  Name extends string,
  Def extends AnyDefinition,
> extends Context.ServiceClass<Key<Name>, string, Client<Def>> {
  readonly kind: "Aggregate";
  readonly aggregateName: Name;
  readonly definition: Def;
  /** Address one instance of this aggregate. */
  ref<Self extends Any>(this: Self, id: Self["definition"]["id"]["Encoded"]): Ref<Self>;
  /**
   * Decide a command locally, with this aggregate's own `decide` and
   * `evolve`: the events and state, or the rejection, the server would give
   * for the same state, id and time. A command with middleware needs
   * `context`: what its middleware provides, from a client-side Layer. See
   * {@link predict}.
   *
   * **Example:** Show a withdrawal before the bank answers
   * ```typescript
   * const context = yield* Layer.build(Layer.succeed(CurrentActor, actor));
   * const outcome = Account.predict(state, new WithdrawMoney({ amount: 30 }), { id, now, context });
   * if (outcome._tag === "Rejected") showError(outcome.rejection); // InsufficientFunds
   * if (outcome._tag === "Accepted") showPending(outcome.state);
   * ```
   */
  predict<Self extends Any, Cmd extends CommandOf<Self>>(
    this: Self,
    state: StateOf<Self>,
    command: Cmd,
    options: PredictOptions<IdOf<Self>, Command.ContextOf<CommandClassOf<Self["definition"], Cmd>>>,
  ): Prediction<
    StateOf<Self>,
    InstanceOf<CommandClassOf<Self["definition"], Cmd>["events"][number]>,
    InstanceOf<CommandClassOf<Self["definition"], Cmd>["rejects"][number]>,
    IdOf<Self>
  >;
}