@devries-cameron20 / t3code Mirror · read-only
Fork 0

The best way to control Claude Code, Codex and more from any computer or phone

Mirrored from https://github.com/Camo67/t3code.git

Synced Nov 21, 04:45 UTC

main
ts 260 lines 8.71 KB
Raw
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 };