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

main
ts 89 lines 3.31 KB
Raw
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 }