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

main
ts 205 lines 7.24 KB
Raw
1 import { defineScene, edit } from "../capture/scene.ts";
2
3 export default defineScene({
4 title: "An Effectful Worker with an API",
5 chapter: "01-api",
6 notes: "Chapter 1: an Effectful Worker serving a typed HttpApi.",
7 async run(s) {
8 await s.sync({
9 except: [
10 "src/Link.ts",
11 "src/ShortyApi.ts",
12 "src/Api.ts",
13 "alchemy.run.ts",
14 "src/client.ts",
15 "src/main.tsx",
16 ],
17 });
18
19 s.step("Design the API");
20
21 // src/Link.ts: the domain.
22 const link = await s.chapterLines("src/Link.ts");
23 await s.editor.patch(
24 "src/Link.ts",
25 "Model a link with Effect Schema",
26 edit.set(link(1, 8)),
27 "The data type is an Effect Schema: one definition gives us the TypeScript type, validation, and JSON encoding.",
28 );
29 await s.editor.patch(
30 "src/Link.ts",
31 "Declare a typed LinkNotFound error",
32 edit.append(`\n${link(10, 15)}`),
33 "Errors are values too. httpApiStatus: 404 means this error travels over HTTP as a typed 404 and comes back out as the same tagged error on the client.",
34 );
35 await s.editor.patch(
36 "src/Link.ts",
37 "Generate short, URL-safe codes",
38 edit.append(`\n${link(17, 21)}`),
39 );
40
41 // src/ShortyApi.ts: the contract.
42 const api = await s.chapterLines("src/ShortyApi.ts");
43 await s.editor.patch("src/ShortyApi.ts", "Import Effect's HttpApi", edit.set(api(1, 5)));
44 await s.editor.patch(
45 "src/ShortyApi.ts",
46 "Declare an endpoint to create a link",
47 edit.append(`\n${api(7, 10)}`),
48 "Each endpoint is a value: its method, path, and the schemas for its payload, success and errors.",
49 );
50 await s.editor.patch(
51 "src/ShortyApi.ts",
52 "Declare an endpoint to list links",
53 edit.append(`\n${api(12, 14)}`),
54 );
55 await s.editor.patch(
56 "src/ShortyApi.ts",
57 "Declare get, with a typed 404",
58 edit.append(`\n${api(16, 20)}`),
59 "get declares LinkNotFound as its error, so a missing link is a typed 404 on the wire and the same tagged error on the client.",
60 );
61 await s.editor.patch(
62 "src/ShortyApi.ts",
63 "Group the endpoints",
64 edit.append(`\n${api(22, 25)}`),
65 );
66 await s.editor.patch(
67 "src/ShortyApi.ts",
68 "One API value for the server, client and tests",
69 edit.append(`\n${api(27, 28)}`),
70 "ShortyApi is a plain value. The Worker implements it, the dashboard derives a client from it, and the tests will use that same client.",
71 );
72
73 s.step("Build the backend");
74
75 // src/Api.ts: the Worker.
76 const worker = await s.chapterLines("src/Api.ts");
77 await s.editor.patch(
78 "src/Api.ts",
79 "Import Cloudflare and Effect",
80 edit.set(worker(1) + worker(3)),
81 );
82 await s.editor.patch(
83 "src/Api.ts",
84 "Declare a Cloudflare Worker",
85 edit.append(`\n${worker(10, 13)}${worker(42, 43)}`),
86 "A Worker is a class. Its body is an Effect: this outer part is the construction phase. It runs at deploy time, to discover the Worker's infrastructure, and at cold start.",
87 );
88 await s.editor.patch(
89 "src/Api.ts",
90 "Construction phase: create an in-memory store",
91 edit.all(
92 edit.after(
93 'import * as Effect from "effect/Effect";\n',
94 'import type { Link } from "./Link.ts";\n',
95 ),
96 edit.after(worker(13), worker(14, 15)),
97 ),
98 "A Map that lives in this isolate. It's deliberately naive: a deploy or a second isolate loses it. Chapter 2 fixes that.",
99 );
100 await s.editor.patch(
101 "src/Api.ts",
102 "Implement the create endpoint",
103 edit.all(
104 edit.after('import * as Effect from "effect/Effect";\n', worker(6)),
105 edit.replace(
106 'import type { Link } from "./Link.ts";\n',
107 `import { newCode, type Link } from "./Link.ts";\n${worker(8)}`,
108 ),
109 edit.after(worker(15), worker(16, 25) + worker(31)),
110 ),
111 "HttpApiBuilder.group implements the links group. The handler's payload is already decoded and typed from the schema.",
112 );
113 await s.editor.patch(
114 "src/Api.ts",
115 "Implement list and get",
116 edit.all(
117 edit.replace(
118 "import { newCode, type Link }",
119 "import { LinkNotFound, newCode, type Link }",
120 ),
121 edit.after(worker(24, 25), worker(26, 30)),
122 ),
123 "get fails with LinkNotFound: the compiler checks it's one of the endpoint's declared errors.",
124 );
125 await s.editor.patch(
126 "src/Api.ts",
127 "Runtime phase: serve the API from fetch",
128 edit.all(
129 edit.after(worker(1), worker(2)),
130 edit.before(worker(6), worker(4, 5)),
131 edit.before(worker(42, 43), worker(32, 41)),
132 ),
133 "The Worker returns fetch: the runtime phase, run per request. It's the HttpApi turned into an HTTP handler, with CORS for the dashboard.",
134 );
135
136 // alchemy.run.ts: add the Worker to the Stack.
137 await s.editor.patch(
138 "alchemy.run.ts",
139 "Add the Worker to the Stack",
140 edit.all(
141 edit.after(
142 'import * as Effect from "effect/Effect";\n',
143 'import Api from "./src/Api.ts";\n',
144 ),
145 edit.before(" const web = yield*", " const api = yield* Api;\n"),
146 ),
147 "yield* Api adds the Worker to the Stack.",
148 );
149 s.step(
150 "alchemy dev reloads: the Worker is running",
151 "alchemy dev reloaded: a second local Worker, next to the website.",
152 );
153 await s.diagram({ stage: `dev_${process.env.USER}`, nodes: ["Api", "Web"] });
154 s.pause(0.5);
155 await s.editor.patch(
156 "alchemy.run.ts",
157 "Output the API's URL from the Stack",
158 edit.replace(
159 "return { web: web.url };",
160 "return { api: api.url.as<string>(), web: web.url };",
161 ),
162 "The Stack's return value is its outputs: printed after every deploy, and handed to the tests.",
163 );
164 await s.editor.patch(
165 "alchemy.run.ts",
166 "Pass the API's URL to the website build",
167 edit.after(
168 " dev: { port: 5173 },\n",
169 " env: { VITE_API_URL: api.url.as<string>() },\n",
170 ),
171 "api.url is an Output: a value known once the Worker exists. Alchemy orders the deploy so the website is built with it.",
172 );
173 s.step(
174 "The website now references the API",
175 "That one line is an edge in the architecture: Web references Api's URL through an Output. It's a reference, not a binding: no permissions are granted.",
176 );
177 await s.diagram({
178 stage: `dev_${process.env.USER}`,
179 nodes: ["Api", "Web"],
180 edges: ["Web->Api"],
181 });
182 s.pause(0.5);
183
184 s.step("Wire up the dashboard");
185
186 // The dashboard.
187 await s.editor.show("src/client.ts", "Derive a typed client from the same API");
188 await s.editor.show("src/main.tsx", "List and create links from the dashboard");
189
190 s.step(
191 "Open the dashboard in the browser",
192 "The dashboard served by alchemy dev, talking to the local Worker.",
193 );
194 await s.browser.open("http://localhost:5173", { waitFor: /No links yet/ });
195 s.pause(0.5);
196
197 s.step(
198 "Shorten a link from the UI",
199 "Create a link from the UI: the typed client calls create on the Worker.",
200 );
201 await s.browser.fill("form input", "https://effect.website");
202 await s.browser.click("form button", { waitFor: /effect\.website/ });
203 s.pause(1);
204 },
205 });