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

main
ts 105 lines 3.49 KB
Raw
1 import type * as Cause from "effect/Cause";
2 import * as Schema from "effect/Schema";
3 import type { Data, Fields } from "./Event.ts";
4 import type * as Telemetry from "./Telemetry.ts";
5
6 /**
7 * Instance type of a Rejection class: its `_tag` plus its evidence data.
8 */
9 export type Instance<Tag extends string, F extends Fields> = { readonly _tag: Tag } & Data<F>;
10
11 /**
12 * What a command or read can declare in `rejects`: any tagged error schema
13 * class, such as a `Domain.Rejection`, a `Schema.TaggedError`, or one of
14 * Effect's `HttpApiError` classes.
15 */
16 export interface Any extends Schema.Top {
17 new (...args: any[]): { readonly _tag: string };
18 }
19
20 /**
21 * What a Rejection takes after its fields: every annotation
22 * `Schema.TaggedError` takes (`description`, `httpApiStatus`, ...), plus the
23 * span `attributes` it records.
24 */
25 export type Annotations<Tag extends string, F extends Fields> = Schema.Annotations.Declaration<
26 Instance<Tag, F>,
27 readonly [Schema.TaggedStruct<Tag, F>]
28 > & {
29 /**
30 * Span attributes to record for this rejection, on every span it passes
31 * through. Nothing from it is recorded unless you return it here, and a
32 * `Redacted` value is recorded as `<redacted>`.
33 */
34 readonly attributes?: Telemetry.Attributes<Instance<Tag, F>>;
35 };
36
37 /**
38 * A typed reason a command or read was refused. Nothing is recorded when a
39 * command is rejected, and the caller receives the rejection exactly as
40 * declared, through an Api too.
41 *
42 * It is `Schema.TaggedError` with its own type filled in, and takes the same
43 * annotations. Any other tagged error class works in `rejects` as well.
44 *
45 * ### Declaring rejections
46 * **Example:** A rejection with and without data
47 * ```typescript
48 * import * as Domain from "@alchemy.run/domain";
49 * import * as Schema from "effect/Schema";
50 *
51 * export class NotOpen extends Domain.Rejection("NotOpen") {}
52 *
53 * export class InsufficientFunds extends Domain.Rejection("InsufficientFunds", {
54 * balance: Schema.Int,
55 * requested: Schema.Int,
56 * }) {}
57 * ```
58 *
59 * ### Annotating rejections
60 * The third argument takes the annotations of `Schema.TaggedError`. An HTTP
61 * API reads `httpApiStatus` from it, as it does for any Effect error.
62 *
63 * **Example:** A status and a description
64 * ```typescript
65 * export class NotOwner extends Domain.Rejection(
66 * "NotOwner",
67 * {},
68 * { httpApiStatus: 403, description: "Only the account's owner may do this." },
69 * ) {}
70 * ```
71 *
72 * @primitive
73 */
74 export const make = <const Tag extends string, const F extends Fields = {}>(
75 tag: Tag,
76 fields: F = {} as F,
77 annotations: Annotations<Tag, F> = {},
78 ): RejectionClass<Tag, F> => {
79 const { attributes, ...schemaAnnotations } = annotations;
80 // The base type is conditional on `Self`, so it is not a constructor until `make` returns.
81 const Base: new (...args: any[]) => object = Schema.TaggedError<Instance<Tag, F>>(tag)(
82 tag,
83 fields,
84 schemaAnnotations,
85 ) as any;
86 return class extends Base {
87 static readonly kind = "Rejection" as const;
88 static readonly tag: Tag = tag;
89 static readonly attributes = attributes;
90 } as unknown as RejectionClass<Tag, F>;
91 };
92
93 /**
94 * The class type returned by {@link make}.
95 */
96 export interface RejectionClass<Tag extends string, F extends Fields> extends Schema.Class<
97 Instance<Tag, F>,
98 Schema.TaggedStruct<Tag, F>,
99 Cause.YieldableError
100 > {
101 readonly kind: "Rejection";
102 readonly tag: Tag;
103 /** Span attributes the rejection adds, if it declares any. */
104 readonly attributes: Telemetry.Attributes<Instance<Tag, F>> | undefined;
105 }