The best way to control Claude Code, Codex and more from any computer or phone
| 1 | import * as Rpc from "effect/rpc/Rpc"; |
| 2 | import * as Schema from "effect/Schema"; |
| 3 | import type * as Event from "./Event.ts"; |
| 4 | import type { Data, Fields } from "./Event.ts"; |
| 5 | import * as Middleware from "./Middleware.ts"; |
| 6 | import type * as Rejection from "./Rejection.ts"; |
| 7 | import type * as Telemetry from "./Telemetry.ts"; |
| 8 | |
| 9 | /** |
| 10 | * Instance type of a Command class: its `_tag` plus its input. |
| 11 | */ |
| 12 | export type Instance<Tag extends string, F extends Fields> = { readonly _tag: Tag } & Data<F>; |
| 13 | |
| 14 | /** The schema of the aggregate id a command addresses. */ |
| 15 | export type TargetSchema = Schema.Top & { readonly Type: string; readonly Encoded: string }; |
| 16 | |
| 17 | /** |
| 18 | * Structural constraint satisfied by every class produced by {@link make}. |
| 19 | */ |
| 20 | export interface Any extends Schema.Top { |
| 21 | readonly kind: "Command"; |
| 22 | readonly tag: string; |
| 23 | readonly target: TargetSchema; |
| 24 | readonly events: ReadonlyArray<Event.Any>; |
| 25 | readonly rejects: ReadonlyArray<Rejection.Any>; |
| 26 | readonly reply: Schema.Top | undefined; |
| 27 | readonly middleware: Middleware.List; |
| 28 | readonly rpc: Rpc.Any; |
| 29 | new (...args: any[]): { readonly _tag: string }; |
| 30 | } |
| 31 | |
| 32 | /** |
| 33 | * The services a command's `decide` may use: whatever its middleware |
| 34 | * provides. Senders without that middleware (policies, stories) provide them. |
| 35 | */ |
| 36 | export type ContextOf<C extends Any> = Middleware.Provides<C["middleware"]>; |
| 37 | |
| 38 | /** |
| 39 | * The reply schema declared by a command, as a `Schema.Struct`. |
| 40 | */ |
| 41 | export type ReplySchema<Reply extends Fields | undefined> = Reply extends Fields |
| 42 | ? Schema.Struct<Reply> |
| 43 | : undefined; |
| 44 | |
| 45 | /** What a client sends: the target, an optional idempotency key, and the input. */ |
| 46 | export type PayloadFields<Target extends TargetSchema, F extends Fields> = { |
| 47 | readonly target: Target; |
| 48 | readonly commandId: Schema.optional<typeof Schema.String>; |
| 49 | readonly input: Schema.Struct<F>; |
| 50 | }; |
| 51 | |
| 52 | /** What a client receives: the reply and the position of the committed events. */ |
| 53 | export type SuccessFields<Reply extends Schema.Top | undefined> = { |
| 54 | readonly reply: Reply extends Schema.Top ? Reply : typeof Schema.Void; |
| 55 | readonly stream: typeof Schema.String; |
| 56 | readonly version: typeof Schema.Number; |
| 57 | }; |
| 58 | |
| 59 | /** The Effect RPC definition of a command. */ |
| 60 | export type CommandRpc< |
| 61 | Tag extends string, |
| 62 | Target extends TargetSchema, |
| 63 | F extends Fields, |
| 64 | Rejects extends ReadonlyArray<Rejection.Any>, |
| 65 | Reply extends Schema.Top | undefined, |
| 66 | > = Rpc.Rpc< |
| 67 | Tag, |
| 68 | Schema.Struct<PayloadFields<Target, F>>, |
| 69 | Schema.Struct<SuccessFields<Reply>>, |
| 70 | Rejects extends readonly [] ? typeof Schema.Never : Schema.Union<Rejects> |
| 71 | >; |
| 72 | |
| 73 | /** |
| 74 | * The class type returned by {@link make}. |
| 75 | */ |
| 76 | export interface CommandClass< |
| 77 | Tag extends string, |
| 78 | Target extends TargetSchema, |
| 79 | F extends Fields, |
| 80 | Events extends ReadonlyArray<Event.Any>, |
| 81 | Rejects extends ReadonlyArray<Rejection.Any>, |
| 82 | Reply extends Schema.Top | undefined, |
| 83 | Ms extends Middleware.List, |
| 84 | R extends Rpc.Any, |
| 85 | > extends Schema.Class<Instance<Tag, F>, Schema.TaggedStruct<Tag, F>, {}> { |
| 86 | readonly kind: "Command"; |
| 87 | readonly tag: Tag; |
| 88 | readonly target: Target; |
| 89 | readonly events: Events; |
| 90 | readonly rejects: Rejects; |
| 91 | readonly reply: Reply; |
| 92 | /** The middleware that guards the command when an Api exposes it, in order. */ |
| 93 | readonly middleware: Ms; |
| 94 | /** The command as an Effect RPC, for exposing it in an Api. */ |
| 95 | readonly rpc: R; |
| 96 | /** Span attributes the command adds for its input, if it declares any. */ |
| 97 | readonly attributes: Telemetry.Attributes<Instance<Tag, F>> | undefined; |
| 98 | } |
| 99 | |
| 100 | interface Options { |
| 101 | readonly target: TargetSchema; |
| 102 | readonly input?: Fields; |
| 103 | readonly middleware?: Middleware.List; |
| 104 | readonly events?: ReadonlyArray<Event.Any>; |
| 105 | readonly rejects?: ReadonlyArray<Rejection.Any>; |
| 106 | readonly reply?: Fields; |
| 107 | readonly attributes?: Telemetry.Attributes<any>; |
| 108 | } |
| 109 | |
| 110 | const build = (tag: string, options: Options, rpc: Rpc.Any): unknown => { |
| 111 | // The base type is conditional on `Self`, so it is not a constructor until `make` returns. |
| 112 | const Base = Schema.TaggedClass<{ readonly _tag: string }>(tag)( |
| 113 | tag, |
| 114 | options.input ?? {}, |
| 115 | ) as unknown as new (input: object) => object; |
| 116 | return class extends Base { |
| 117 | static readonly kind = "Command" as const; |
| 118 | static readonly tag = tag; |
| 119 | static readonly target = options.target; |
| 120 | static readonly events = options.events ?? []; |
| 121 | static readonly rejects = options.rejects ?? []; |
| 122 | static readonly reply = options.reply ? Schema.Struct(options.reply) : undefined; |
| 123 | static readonly middleware = options.middleware ?? []; |
| 124 | static readonly rpc = rpc; |
| 125 | static readonly attributes = options.attributes; |
| 126 | }; |
| 127 | }; |
| 128 | |
| 129 | /** |
| 130 | * A request to change one aggregate instance. It names the instance it |
| 131 | * targets, its input, the events it may record, the rejections it may return, |
| 132 | * the middleware that guards it, and the reply its caller receives. |
| 133 | * |
| 134 | * ### Declaring a command |
| 135 | * **Example:** A command with its event and rejection |
| 136 | * ```typescript |
| 137 | * import * as Domain from "@alchemy.run/domain"; |
| 138 | * import * as Schema from "effect/Schema"; |
| 139 | * |
| 140 | * export const AccountId = Schema.String.pipe(Schema.brand("AccountId")); |
| 141 | * |
| 142 | * export class MoneyWithdrawn extends Domain.Event("MoneyWithdrawn", { |
| 143 | * amount: Schema.Int, |
| 144 | * balanceAfter: Schema.Int, |
| 145 | * }) {} |
| 146 | * |
| 147 | * export class InsufficientFunds extends Domain.Rejection("InsufficientFunds", { |
| 148 | * balance: Schema.Int, |
| 149 | * requested: Schema.Int, |
| 150 | * }) {} |
| 151 | * |
| 152 | * export class WithdrawMoney extends Domain.Command("WithdrawMoney", { |
| 153 | * target: AccountId, |
| 154 | * input: { amount: Schema.Int }, |
| 155 | * events: [MoneyWithdrawn], |
| 156 | * rejects: [InsufficientFunds], |
| 157 | * reply: { balance: Schema.Int }, |
| 158 | * }) {} |
| 159 | * ``` |
| 160 | * |
| 161 | * ### Guarding it with middleware |
| 162 | * `middleware` runs in order before the command reaches its aggregate. What |
| 163 | * it provides, such as the current actor, is what `decide` may read. |
| 164 | * |
| 165 | * **Example:** Requiring a session and a second factor |
| 166 | * ```typescript |
| 167 | * import * as Domain from "@alchemy.run/domain"; |
| 168 | * import * as Schema from "effect/Schema"; |
| 169 | * import { AccountId, MoneyWithdrawn } from "./Account.ts"; |
| 170 | * import { MfaChallenge } from "./MfaChallenge.ts"; |
| 171 | * import { Session } from "./Session.ts"; |
| 172 | * |
| 173 | * export class WithdrawMoney extends Domain.Command("WithdrawMoney", { |
| 174 | * target: AccountId, |
| 175 | * middleware: [Session, MfaChallenge], |
| 176 | * input: { amount: Schema.Int }, |
| 177 | * events: [MoneyWithdrawn], |
| 178 | * reply: { balance: Schema.Int }, |
| 179 | * }) {} |
| 180 | * ``` |
| 181 | * |
| 182 | * ### Sending it once |
| 183 | * Pass a `commandId`, and a resend with the same id returns the first |
| 184 | * receipt instead of applying the command again. |
| 185 | * |
| 186 | * **Example:** An idempotent send through an Api |
| 187 | * ```typescript |
| 188 | * const receipt = yield* bank.WithdrawMoney(accountId, { amount: 2_000 }, { commandId: requestId }); |
| 189 | * ``` |
| 190 | * |
| 191 | * @primitive |
| 192 | */ |
| 193 | export const make = < |
| 194 | const Tag extends string, |
| 195 | Target extends TargetSchema, |
| 196 | const F extends Fields = {}, |
| 197 | const Ms extends Middleware.List = readonly [], |
| 198 | const Events extends ReadonlyArray<Event.Any> = readonly [], |
| 199 | const Rejects extends ReadonlyArray<Rejection.Any> = readonly [], |
| 200 | const Reply extends Fields | undefined = undefined, |
| 201 | >( |
| 202 | tag: Tag, |
| 203 | options: { |
| 204 | /** The id schema of the aggregate this command addresses. */ |
| 205 | readonly target: Target; |
| 206 | /** The command's fields. */ |
| 207 | readonly input?: F; |
| 208 | /** |
| 209 | * Middleware that guards the command when an Api exposes it, in order. |
| 210 | * What it provides is what `decide` may read. |
| 211 | */ |
| 212 | readonly middleware?: Ms; |
| 213 | /** The events the command may record. */ |
| 214 | readonly events?: Events; |
| 215 | /** The rejections the command's handler may return. */ |
| 216 | readonly rejects?: Rejects; |
| 217 | /** The reply computed after the events are committed. */ |
| 218 | readonly reply?: Reply; |
| 219 | /** |
| 220 | * Span attributes to record for the command's input, on every span it |
| 221 | * passes through. Nothing from the input is recorded unless you return it |
| 222 | * here, and a `Redacted` value is recorded as `<redacted>`. |
| 223 | */ |
| 224 | readonly attributes?: Telemetry.Attributes<Instance<Tag, F>>; |
| 225 | }, |
| 226 | ): CommandClass< |
| 227 | Tag, |
| 228 | Target, |
| 229 | F, |
| 230 | Events, |
| 231 | Rejects, |
| 232 | ReplySchema<Reply>, |
| 233 | Ms, |
| 234 | Middleware.Apply<CommandRpc<Tag, Target, F, Rejects, ReplySchema<Reply>>, Ms> |
| 235 | > => { |
| 236 | const rejects = options.rejects ?? []; |
| 237 | const rpc = Rpc.make(tag, { |
| 238 | payload: { |
| 239 | target: options.target, |
| 240 | commandId: Schema.optional(Schema.String), |
| 241 | input: Schema.Struct(options.input ?? {}), |
| 242 | }, |
| 243 | success: Schema.Struct({ |
| 244 | reply: options.reply ? Schema.Struct(options.reply) : Schema.Void, |
| 245 | stream: Schema.String, |
| 246 | version: Schema.Number, |
| 247 | }), |
| 248 | error: rejects.length === 0 ? Schema.Never : Schema.Union(rejects), |
| 249 | }); |
| 250 | return build(tag, options, Middleware.apply(rpc, options.middleware ?? [])) as CommandClass< |
| 251 | Tag, |
| 252 | Target, |
| 253 | F, |
| 254 | Events, |
| 255 | Rejects, |
| 256 | ReplySchema<Reply>, |
| 257 | Ms, |
| 258 | Middleware.Apply<CommandRpc<Tag, Target, F, Rejects, ReplySchema<Reply>>, Ms> |
| 259 | >; |
| 260 | }; |