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

import * as Rpc from "effect/rpc/Rpc";
import * as Schema from "effect/Schema";
import type * as Event from "./Event.ts";
import type { Data, Fields } from "./Event.ts";
import * as Middleware from "./Middleware.ts";
import type * as Rejection from "./Rejection.ts";
import type * as Telemetry from "./Telemetry.ts";

/**
 * Instance type of a Command class: its `_tag` plus its input.
 */
export type Instance<Tag extends string, F extends Fields> = { readonly _tag: Tag } & Data<F>;

/** The schema of the aggregate id a command addresses. */
export type TargetSchema = Schema.Top & { readonly Type: string; readonly Encoded: string };

/**
 * Structural constraint satisfied by every class produced by {@link make}.
 */
export interface Any extends Schema.Top {
  readonly kind: "Command";
  readonly tag: string;
  readonly target: TargetSchema;
  readonly events: ReadonlyArray<Event.Any>;
  readonly rejects: ReadonlyArray<Rejection.Any>;
  readonly reply: Schema.Top | undefined;
  readonly middleware: Middleware.List;
  readonly rpc: Rpc.Any;
  new (...args: any[]): { readonly _tag: string };
}

/**
 * The services a command's `decide` may use: whatever its middleware
 * provides. Senders without that middleware (policies, stories) provide them.
 */
export type ContextOf<C extends Any> = Middleware.Provides<C["middleware"]>;

/**
 * The reply schema declared by a command, as a `Schema.Struct`.
 */
export type ReplySchema<Reply extends Fields | undefined> = Reply extends Fields
  ? Schema.Struct<Reply>
  : undefined;

/** What a client sends: the target, an optional idempotency key, and the input. */
export type PayloadFields<Target extends TargetSchema, F extends Fields> = {
  readonly target: Target;
  readonly commandId: Schema.optional<typeof Schema.String>;
  readonly input: Schema.Struct<F>;
};

/** What a client receives: the reply and the position of the committed events. */
export type SuccessFields<Reply extends Schema.Top | undefined> = {
  readonly reply: Reply extends Schema.Top ? Reply : typeof Schema.Void;
  readonly stream: typeof Schema.String;
  readonly version: typeof Schema.Number;
};

/** The Effect RPC definition of a command. */
export type CommandRpc<
  Tag extends string,
  Target extends TargetSchema,
  F extends Fields,
  Rejects extends ReadonlyArray<Rejection.Any>,
  Reply extends Schema.Top | undefined,
> = Rpc.Rpc<
  Tag,
  Schema.Struct<PayloadFields<Target, F>>,
  Schema.Struct<SuccessFields<Reply>>,
  Rejects extends readonly [] ? typeof Schema.Never : Schema.Union<Rejects>
>;

/**
 * The class type returned by {@link make}.
 */
export interface CommandClass<
  Tag extends string,
  Target extends TargetSchema,
  F extends Fields,
  Events extends ReadonlyArray<Event.Any>,
  Rejects extends ReadonlyArray<Rejection.Any>,
  Reply extends Schema.Top | undefined,
  Ms extends Middleware.List,
  R extends Rpc.Any,
> extends Schema.Class<Instance<Tag, F>, Schema.TaggedStruct<Tag, F>, {}> {
  readonly kind: "Command";
  readonly tag: Tag;
  readonly target: Target;
  readonly events: Events;
  readonly rejects: Rejects;
  readonly reply: Reply;
  /** The middleware that guards the command when an Api exposes it, in order. */
  readonly middleware: Ms;
  /** The command as an Effect RPC, for exposing it in an Api. */
  readonly rpc: R;
  /** Span attributes the command adds for its input, if it declares any. */
  readonly attributes: Telemetry.Attributes<Instance<Tag, F>> | undefined;
}

interface Options {
  readonly target: TargetSchema;
  readonly input?: Fields;
  readonly middleware?: Middleware.List;
  readonly events?: ReadonlyArray<Event.Any>;
  readonly rejects?: ReadonlyArray<Rejection.Any>;
  readonly reply?: Fields;
  readonly attributes?: Telemetry.Attributes<any>;
}

const build = (tag: string, options: Options, rpc: Rpc.Any): unknown => {
  // The base type is conditional on `Self`, so it is not a constructor until `make` returns.
  const Base = Schema.TaggedClass<{ readonly _tag: string }>(tag)(
    tag,
    options.input ?? {},
  ) as unknown as new (input: object) => object;
  return class extends Base {
    static readonly kind = "Command" as const;
    static readonly tag = tag;
    static readonly target = options.target;
    static readonly events = options.events ?? [];
    static readonly rejects = options.rejects ?? [];
    static readonly reply = options.reply ? Schema.Struct(options.reply) : undefined;
    static readonly middleware = options.middleware ?? [];
    static readonly rpc = rpc;
    static readonly attributes = options.attributes;
  };
};

/**
 * A request to change one aggregate instance. It names the instance it
 * targets, its input, the events it may record, the rejections it may return,
 * the middleware that guards it, and the reply its caller receives.
 *
 * ### Declaring a command
 * **Example:** A command with its event and rejection
 * ```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 },
 * }) {}
 * ```
 *
 * ### Guarding it with middleware
 * `middleware` runs in order before the command reaches its aggregate. What
 * it provides, such as the current actor, is what `decide` may read.
 *
 * **Example:** Requiring a session and a second factor
 * ```typescript
 * import * as Domain from "@alchemy.run/domain";
 * import * as Schema from "effect/Schema";
 * import { AccountId, MoneyWithdrawn } from "./Account.ts";
 * import { MfaChallenge } from "./MfaChallenge.ts";
 * import { Session } from "./Session.ts";
 *
 * export class WithdrawMoney extends Domain.Command("WithdrawMoney", {
 *   target: AccountId,
 *   middleware: [Session, MfaChallenge],
 *   input: { amount: Schema.Int },
 *   events: [MoneyWithdrawn],
 *   reply: { balance: Schema.Int },
 * }) {}
 * ```
 *
 * ### Sending it once
 * Pass a `commandId`, and a resend with the same id returns the first
 * receipt instead of applying the command again.
 *
 * **Example:** An idempotent send through an Api
 * ```typescript
 * const receipt = yield* bank.WithdrawMoney(accountId, { amount: 2_000 }, { commandId: requestId });
 * ```
 *
 * @primitive
 */
export const make = <
  const Tag extends string,
  Target extends TargetSchema,
  const F extends Fields = {},
  const Ms extends Middleware.List = readonly [],
  const Events extends ReadonlyArray<Event.Any> = readonly [],
  const Rejects extends ReadonlyArray<Rejection.Any> = readonly [],
  const Reply extends Fields | undefined = undefined,
>(
  tag: Tag,
  options: {
    /** The id schema of the aggregate this command addresses. */
    readonly target: Target;
    /** The command's fields. */
    readonly input?: F;
    /**
     * Middleware that guards the command when an Api exposes it, in order.
     * What it provides is what `decide` may read.
     */
    readonly middleware?: Ms;
    /** The events the command may record. */
    readonly events?: Events;
    /** The rejections the command's handler may return. */
    readonly rejects?: Rejects;
    /** The reply computed after the events are committed. */
    readonly reply?: Reply;
    /**
     * Span attributes to record for the command's input, on every span it
     * passes through. Nothing from the input is recorded unless you return it
     * here, and a `Redacted` value is recorded as `<redacted>`.
     */
    readonly attributes?: Telemetry.Attributes<Instance<Tag, F>>;
  },
): CommandClass<
  Tag,
  Target,
  F,
  Events,
  Rejects,
  ReplySchema<Reply>,
  Ms,
  Middleware.Apply<CommandRpc<Tag, Target, F, Rejects, ReplySchema<Reply>>, Ms>
> => {
  const rejects = options.rejects ?? [];
  const rpc = Rpc.make(tag, {
    payload: {
      target: options.target,
      commandId: Schema.optional(Schema.String),
      input: Schema.Struct(options.input ?? {}),
    },
    success: Schema.Struct({
      reply: options.reply ? Schema.Struct(options.reply) : Schema.Void,
      stream: Schema.String,
      version: Schema.Number,
    }),
    error: rejects.length === 0 ? Schema.Never : Schema.Union(rejects),
  });
  return build(tag, options, Middleware.apply(rpc, options.middleware ?? [])) as CommandClass<
    Tag,
    Target,
    F,
    Events,
    Rejects,
    ReplySchema<Reply>,
    Ms,
    Middleware.Apply<CommandRpc<Tag, Target, F, Rejects, ReplySchema<Reply>>, Ms>
  >;
};