sailfork / t3code-github / .repos/ alchemy-effect/ demos/ effect-prezzy/ scenes/ 01-api.ts

import { defineScene, edit } from "../capture/scene.ts";

export default defineScene({
  title: "An Effectful Worker with an API",
  chapter: "01-api",
  notes: "Chapter 1: an Effectful Worker serving a typed HttpApi.",
  async run(s) {
    await s.sync({
      except: [
        "src/Link.ts",
        "src/ShortyApi.ts",
        "src/Api.ts",
        "alchemy.run.ts",
        "src/client.ts",
        "src/main.tsx",
      ],
    });

    s.step("Design the API");

    // src/Link.ts: the domain.
    const link = await s.chapterLines("src/Link.ts");
    await s.editor.patch(
      "src/Link.ts",
      "Model a link with Effect Schema",
      edit.set(link(1, 8)),
      "The data type is an Effect Schema: one definition gives us the TypeScript type, validation, and JSON encoding.",
    );
    await s.editor.patch(
      "src/Link.ts",
      "Declare a typed LinkNotFound error",
      edit.append(`\n${link(10, 15)}`),
      "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.",
    );
    await s.editor.patch(
      "src/Link.ts",
      "Generate short, URL-safe codes",
      edit.append(`\n${link(17, 21)}`),
    );

    // src/ShortyApi.ts: the contract.
    const api = await s.chapterLines("src/ShortyApi.ts");
    await s.editor.patch("src/ShortyApi.ts", "Import Effect's HttpApi", edit.set(api(1, 5)));
    await s.editor.patch(
      "src/ShortyApi.ts",
      "Declare an endpoint to create a link",
      edit.append(`\n${api(7, 10)}`),
      "Each endpoint is a value: its method, path, and the schemas for its payload, success and errors.",
    );
    await s.editor.patch(
      "src/ShortyApi.ts",
      "Declare an endpoint to list links",
      edit.append(`\n${api(12, 14)}`),
    );
    await s.editor.patch(
      "src/ShortyApi.ts",
      "Declare get, with a typed 404",
      edit.append(`\n${api(16, 20)}`),
      "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.",
    );
    await s.editor.patch(
      "src/ShortyApi.ts",
      "Group the endpoints",
      edit.append(`\n${api(22, 25)}`),
    );
    await s.editor.patch(
      "src/ShortyApi.ts",
      "One API value for the server, client and tests",
      edit.append(`\n${api(27, 28)}`),
      "ShortyApi is a plain value. The Worker implements it, the dashboard derives a client from it, and the tests will use that same client.",
    );

    s.step("Build the backend");

    // src/Api.ts: the Worker.
    const worker = await s.chapterLines("src/Api.ts");
    await s.editor.patch(
      "src/Api.ts",
      "Import Cloudflare and Effect",
      edit.set(worker(1) + worker(3)),
    );
    await s.editor.patch(
      "src/Api.ts",
      "Declare a Cloudflare Worker",
      edit.append(`\n${worker(10, 13)}${worker(42, 43)}`),
      "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.",
    );
    await s.editor.patch(
      "src/Api.ts",
      "Construction phase: create an in-memory store",
      edit.all(
        edit.after(
          'import * as Effect from "effect/Effect";\n',
          'import type { Link } from "./Link.ts";\n',
        ),
        edit.after(worker(13), worker(14, 15)),
      ),
      "A Map that lives in this isolate. It's deliberately naive: a deploy or a second isolate loses it. Chapter 2 fixes that.",
    );
    await s.editor.patch(
      "src/Api.ts",
      "Implement the create endpoint",
      edit.all(
        edit.after('import * as Effect from "effect/Effect";\n', worker(6)),
        edit.replace(
          'import type { Link } from "./Link.ts";\n',
          `import { newCode, type Link } from "./Link.ts";\n${worker(8)}`,
        ),
        edit.after(worker(15), worker(16, 25) + worker(31)),
      ),
      "HttpApiBuilder.group implements the links group. The handler's payload is already decoded and typed from the schema.",
    );
    await s.editor.patch(
      "src/Api.ts",
      "Implement list and get",
      edit.all(
        edit.replace(
          "import { newCode, type Link }",
          "import { LinkNotFound, newCode, type Link }",
        ),
        edit.after(worker(24, 25), worker(26, 30)),
      ),
      "get fails with LinkNotFound: the compiler checks it's one of the endpoint's declared errors.",
    );
    await s.editor.patch(
      "src/Api.ts",
      "Runtime phase: serve the API from fetch",
      edit.all(
        edit.after(worker(1), worker(2)),
        edit.before(worker(6), worker(4, 5)),
        edit.before(worker(42, 43), worker(32, 41)),
      ),
      "The Worker returns fetch: the runtime phase, run per request. It's the HttpApi turned into an HTTP handler, with CORS for the dashboard.",
    );

    // alchemy.run.ts: add the Worker to the Stack.
    await s.editor.patch(
      "alchemy.run.ts",
      "Add the Worker to the Stack",
      edit.all(
        edit.after(
          'import * as Effect from "effect/Effect";\n',
          'import Api from "./src/Api.ts";\n',
        ),
        edit.before("    const web = yield*", "    const api = yield* Api;\n"),
      ),
      "yield* Api adds the Worker to the Stack.",
    );
    s.step(
      "alchemy dev reloads: the Worker is running",
      "alchemy dev reloaded: a second local Worker, next to the website.",
    );
    await s.diagram({ stage: `dev_${process.env.USER}`, nodes: ["Api", "Web"] });
    s.pause(0.5);
    await s.editor.patch(
      "alchemy.run.ts",
      "Output the API's URL from the Stack",
      edit.replace(
        "return { web: web.url };",
        "return { api: api.url.as<string>(), web: web.url };",
      ),
      "The Stack's return value is its outputs: printed after every deploy, and handed to the tests.",
    );
    await s.editor.patch(
      "alchemy.run.ts",
      "Pass the API's URL to the website build",
      edit.after(
        "      dev: { port: 5173 },\n",
        "      env: { VITE_API_URL: api.url.as<string>() },\n",
      ),
      "api.url is an Output: a value known once the Worker exists. Alchemy orders the deploy so the website is built with it.",
    );
    s.step(
      "The website now references the API",
      "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.",
    );
    await s.diagram({
      stage: `dev_${process.env.USER}`,
      nodes: ["Api", "Web"],
      edges: ["Web->Api"],
    });
    s.pause(0.5);

    s.step("Wire up the dashboard");

    // The dashboard.
    await s.editor.show("src/client.ts", "Derive a typed client from the same API");
    await s.editor.show("src/main.tsx", "List and create links from the dashboard");

    s.step(
      "Open the dashboard in the browser",
      "The dashboard served by alchemy dev, talking to the local Worker.",
    );
    await s.browser.open("http://localhost:5173", { waitFor: /No links yet/ });
    s.pause(0.5);

    s.step(
      "Shorten a link from the UI",
      "Create a link from the UI: the typed client calls create on the Worker.",
    );
    await s.browser.fill("form input", "https://effect.website");
    await s.browser.click("form button", { waitFor: /effect\.website/ });
    s.pause(1);
  },
});