The best way to control Claude Code, Codex and more from any computer or phone
| 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 | } |