The best way to control Claude Code, Codex and more from any computer or phone
| 1 | import type * as Effect from "effect/Effect"; |
| 2 | import * as Schema from "effect/Schema"; |
| 3 | import type * as Aggregate from "./Aggregate.ts"; |
| 4 | import type * as Middleware from "./Middleware.ts"; |
| 5 | import type * as Rejection from "./Rejection.ts"; |
| 6 | |
| 7 | /** How a client reads a View or an aggregate. */ |
| 8 | export type Mode = "get" | "watch" | "events" | "list"; |
| 9 | |
| 10 | /** |
| 11 | * What `watch` sends: the key's state and the cursor it is valid at, the |
| 12 | * `seq` of the last event the key had when the state was read (`0` before any). |
| 13 | */ |
| 14 | export interface Snapshot<S> { |
| 15 | readonly state: S; |
| 16 | /** Pass as `after` to `events` to receive every later event, once. */ |
| 17 | readonly cursor: number; |
| 18 | } |
| 19 | |
| 20 | /** |
| 21 | * The frame `events` sends once it has sent the key's history: every event up |
| 22 | * to `cursor` was delivered (or filtered out), and what follows is live. A |
| 23 | * read that reconnects sends it again after the events it missed. |
| 24 | */ |
| 25 | export const CaughtUp = Schema.TaggedStruct("CaughtUp", { |
| 26 | /** The `seq` of the last event of the history (`0` for none); resume `events` after it. */ |
| 27 | cursor: Schema.Number, |
| 28 | }); |
| 29 | export type CaughtUp = typeof CaughtUp.Type; |
| 30 | |
| 31 | /** Is a frame of `events` the {@link CaughtUp} marker? */ |
| 32 | export const isCaughtUp = <A extends object>(frame: A | CaughtUp): frame is CaughtUp => |
| 33 | "_tag" in frame && frame._tag === "CaughtUp"; |
| 34 | |
| 35 | /** |
| 36 | * Is a frame of `events` an event, not the {@link CaughtUp} marker? Drops the |
| 37 | * marker from a feed: `Stream.filter(Domain.Read.isEvent)`. |
| 38 | */ |
| 39 | export const isEvent = <A extends object>(frame: A | CaughtUp): frame is Exclude<A, CaughtUp> => |
| 40 | !isCaughtUp(frame); |
| 41 | |
| 42 | /** |
| 43 | * A client's read, as `validate` sees it: what is being read and how. The |
| 44 | * client's own filters are not part of it: they only narrow what a permitted |
| 45 | * read returns, so access never depends on analyzing them. |
| 46 | */ |
| 47 | export interface Request<Ref> { |
| 48 | readonly mode: Mode; |
| 49 | /** The key being read: a view key, or an aggregate instance. */ |
| 50 | readonly key: Ref; |
| 51 | } |
| 52 | |
| 53 | /** |
| 54 | * The read contract of a View or aggregate exposed in an Api: the middleware |
| 55 | * that guards it, the rejections a read may fail with, and `validate`, which |
| 56 | * judges each read. Like a Command, a View is a security boundary: to show an |
| 57 | * audience different data, make another View. |
| 58 | */ |
| 59 | export interface Contract< |
| 60 | Ref, |
| 61 | St, |
| 62 | Ms extends Middleware.List, |
| 63 | Rejects extends ReadonlyArray<Rejection.Any>, |
| 64 | > { |
| 65 | /** |
| 66 | * Middleware that guards reads when an Api exposes them, in order. What it |
| 67 | * provides is what `validate` may read. |
| 68 | */ |
| 69 | readonly middleware?: Ms; |
| 70 | /** The rejections a read may fail with; they reach the client typed. */ |
| 71 | readonly rejects?: Rejects; |
| 72 | /** |
| 73 | * Judge a read from who is asking (what `middleware` provides), the key and |
| 74 | * that key's state. Runs on every `get` and `list`, and on every change |
| 75 | * while a client watches: failing ends the watch with that rejection. |
| 76 | * Without it, anyone who reaches the Api may read every key. |
| 77 | */ |
| 78 | readonly validate?: ( |
| 79 | request: Request<Ref>, |
| 80 | state: St, |
| 81 | ) => Effect.Effect<void, Aggregate.InstanceOf<Rejects[number]>, Middleware.Provides<Ms>>; |
| 82 | } |
| 83 | |
| 84 | /** The read contract a View or aggregate declares, widened. @internal */ |
| 85 | export interface AnyContract { |
| 86 | readonly middleware?: Middleware.List; |
| 87 | readonly rejects?: ReadonlyArray<Rejection.Any>; |
| 88 | readonly validate?: (request: never, state: never) => Effect.Effect<void, unknown, unknown>; |
| 89 | } |