create-yerd 0.0.0-stage → 0.2.2

package/templates/api/src/notes.ts

@@ -0,0 +1,65 @@
+import { Conflict, NotFound, is, length, service, trim } from "@toyz/yerd";
+
+export interface Note {
+  id: number;
+  title: string;
+  body: string;
+  done: boolean;
+}
+
+/** The body of POST and PUT. Validated before the handler runs; every issue is reported at once. */
+export class NoteInput {
+  @is.string({ transform: trim, validate: length(1, 120) }) title!: string;
+  @is.string({ transform: trim, validate: length(0, 2000) }) body = "";
+  @is.boolean() done = false;
+}
+
+/** A 404 whose JSON carries the id: `{"error":"No note 7","code":"not_found","id":7}`. */
+export class NoteNotFound extends NotFound {
+  constructor(readonly id: number) {
+    super(`No note ${id}`, { details: { id } });
+  }
+}
+
+/** Notes, in memory. A singleton: swap in a database when you have one. */
+@service
+export class Notes {
+  #notes: Note[] = [{ id: 1, title: "Read the yerd guides", body: "https://toyz.github.io/yerd/", done: false }];
+  #next = 2;
+
+  list(done?: boolean): Note[] {
+    return done === undefined ? this.#notes : this.#notes.filter((n) => n.done === done);
+  }
+
+  /** The note, or a 404 for the request. */
+  find(id: number): Note {
+    const note = this.#notes.find((n) => n.id === id);
+    if (!note) throw new NoteNotFound(id);
+    return note;
+  }
+
+  create(input: NoteInput): Note {
+    this.#unique(input.title);
+    const note = { id: this.#next++, ...input };
+    this.#notes.push(note);
+    return note;
+  }
+
+  update(id: number, input: NoteInput): Note {
+    const note = this.find(id);
+    this.#unique(input.title, id);
+    return Object.assign(note, input);
+  }
+
+  remove(id: number): void {
+    this.find(id);
+    this.#notes = this.#notes.filter((n) => n.id !== id);
+  }
+
+  /** Titles are unique: a 409 with a code clients can switch on. */
+  #unique(title: string, except?: number): void {
+    if (this.#notes.some((n) => n.id !== except && n.title.toLowerCase() === title.toLowerCase())) {
+      throw new Conflict(`A note called "${title}" already exists`, { code: "duplicate_title" });
+    }
+  }
+}

package/templates/api/src/routes/notes.ts

@@ -0,0 +1,49 @@
+import { HttpStatus, body, del, get, inject, param, post, put, query, route, status, toBool, toInt } from "@toyz/yerd";
+import { NoteInput, Notes } from "../notes.js";
+
+/** curl localhost:5173/api/notes?done=false */
+@route("/api/notes")
+export class NotesApi {
+  @inject(Notes) accessor notes!: Notes;
+  @query("done", { transform: toBool }) accessor done: boolean | undefined;
+  // Read and validated only when awaited: a bad body is a 400 listing every issue.
+  @body(NoteInput) accessor input!: Promise<NoteInput>;
+
+  @get list() {
+    return this.notes.list(this.done);
+  }
+
+  /** curl -X POST localhost:5173/api/notes -H 'content-type: application/json' -d '{"title":"Ship it"}' */
+  @post @status(HttpStatus.Created) async create() {
+    return this.notes.create(await this.input);
+  }
+}
+
+@route("/api/notes/:id")
+export class NoteApi {
+  @inject(Notes) accessor notes!: Notes;
+  // Not a number: a 400 before the handler runs.
+  @param("id", { transform: toInt }) accessor id!: number;
+  @body(NoteInput) accessor input!: Promise<NoteInput>;
+
+  @get show() {
+    return this.notes.find(this.id);
+  }
+
+  @put async replace() {
+    return this.notes.update(this.id, await this.input);
+  }
+
+  @del remove() {
+    this.notes.remove(this.id);
+    return HttpStatus.NoContent;
+  }
+}
+
+/** For load balancers and uptime checks: 204, no body. */
+@route("/api/health")
+export class Health {
+  @get check() {
+    return HttpStatus.NoContent;
+  }
+}

package/templates/api/test/notes.test.ts

@@ -0,0 +1,68 @@
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { createApp } from "../src/app.js";
+import "../src/routes/notes.js";
+
+// The app main.ts serves, with the routes this file imports. No port is opened.
+const app = createApp({ handleSignals: false });
+beforeAll(() => app.boot());
+afterAll(() => app.stop());
+
+/** A JSON request. */
+function send(method: string, path: string, body?: unknown) {
+  return app.request(path, {
+    method,
+    headers: { "content-type": "application/json" },
+    body: body === undefined ? undefined : JSON.stringify(body),
+  });
+}
+
+describe("notes", () => {
+  it("lists notes as JSON", async () => {
+    const res = await app.request("/api/notes");
+    expect(res.status).toBe(200);
+    expect(res.headers.get("content-type")).toBe("application/json; charset=utf-8");
+    expect(await res.json()).toMatchObject([{ id: 1, title: "Read the yerd guides" }]);
+  });
+
+  it("creates a note with 201, filling in defaults", async () => {
+    const res = await send("POST", "/api/notes", { title: "  Write tests  " });
+    expect(res.status).toBe(201);
+    expect(await res.json()).toEqual({ id: 2, title: "Write tests", body: "", done: false });
+  });
+
+  it("reports every invalid field at once", async () => {
+    const res = await send("POST", "/api/notes", { title: "", done: "maybe" });
+    expect(res.status).toBe(400);
+    expect(await res.json()).toMatchObject({ issues: [{ path: "title", message: "Can't be empty" }, { path: "done" }] });
+  });
+
+  it("refuses a duplicate title with a code", async () => {
+    const res = await send("POST", "/api/notes", { title: "read the yerd guides" });
+    expect(res.status).toBe(409);
+    expect(await res.json()).toMatchObject({ code: "duplicate_title" });
+  });
+
+  it("replaces, filters and deletes", async () => {
+    const created = (await (await send("POST", "/api/notes", { title: "Deploy" })).json()) as { id: number };
+
+    const replaced = await send("PUT", `/api/notes/${created.id}`, { title: "Deploy", done: true });
+    expect(await replaced.json()).toMatchObject({ id: created.id, done: true });
+    expect(await (await app.request("/api/notes?done=true")).json()).toMatchObject([{ id: created.id }]);
+
+    const removed = await send("DELETE", `/api/notes/${created.id}`);
+    expect(removed.status).toBe(204);
+    expect(await removed.text()).toBe("");
+  });
+
+  it("is a 404 with the id for an unknown note, and a 400 for a bad one", async () => {
+    const missing = await app.request("/api/notes/99");
+    expect(missing.status).toBe(404);
+    expect(await missing.json()).toEqual({ error: "No note 99", code: "not_found", id: 99 });
+
+    expect((await app.request("/api/notes/abc")).status).toBe(400);
+  });
+
+  it("answers health checks with 204", async () => {
+    expect((await app.request("/api/health")).status).toBe(204);
+  });
+});

package/templates/api/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "nodenext",
+    "moduleResolution": "nodenext",
+    "lib": ["ES2023", "esnext.decorators", "DOM"],
+    "types": ["node"],
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "verbatimModuleSyntax": true,
+    "isolatedModules": true,
+    "skipLibCheck": true,
+    "noEmit": true
+  },
+  "include": ["src", "test", "*.config.ts"]
+}

package/templates/api/vite.config.ts

@@ -0,0 +1,7 @@
+import { defineConfig } from "vite";
+import yerd from "@toyz/yerd/vite";
+
+// Vite runs the app in dev with reloads; `vite build` writes dist/server/server.js.
+export default defineConfig({
+  plugins: [yerd({ entry: "/src/main.ts" })],
+});

package/templates/full/README.md

@@ -0,0 +1,46 @@
+# {{name}}
+
+A small [yerd](https://toyz.github.io/yerd/) shop: a catalog, product pages,
+a cart in the session, sign-in, a validated checkout form and a JSON API.
+
+```sh
+{{run_dev}}      # dev server with reloads, on http://localhost:5173
+{{run_test}}     # vitest, in-process: no port, no browser
+{{run_check}}    # type-check (Vite doesn't)
+{{run_build}}    # production build: dist/client and dist/server/server.js
+{{run_start}}    # node dist/server/server.js, on PORT or 3000
+```
+
+Sign in with `ada` / `analytical-engine`. Copy `.env.example` to `.env` and
+set `YERD_SECRET` before you deploy: it signs forms and seals the session
+cookie that holds the cart.
+
+The Playwright test needs a browser once: `{{exec}} playwright install chromium`,
+then `{{run_e2e}}`. It builds the app and runs it on port 4173.
+
+| Route | What |
+| --- | --- |
+| `GET /` | the catalog; `?q=` searches |
+| `GET /products/:id` | a product, a 404 for an unknown id; add to cart is an action |
+| `GET /cart` | the cart, in the session; remove is an action |
+| `GET /login`, `POST /logout` | sign in keeps a guest's cart |
+| `GET /checkout` | signed in only; a validated form that places the order |
+| `GET /orders/:id` | the receipt, only for its owner |
+| `GET /api/products`, `/api/products/:id` | JSON, no session |
+| `GET /api/health` | 204, for load balancers |
+
+| File | What |
+| --- | --- |
+| `src/app.ts` | `createApp()`: layout, error page, sessions, auth; shared with the tests |
+| `src/catalog.ts` | `Catalog` service, `ProductNotFound` |
+| `src/cart.ts` | the `Cart` session shape, `priceCart()` |
+| `src/orders.ts` | `CheckoutForm` DTO, `Orders` service |
+| `src/users.ts` | `Users`, the demo account, `createAuth(...)` |
+| `src/layouts.tsx` | `RootLayout` with the cart badge, `Narrow`, `ErrorPage` |
+| `src/components.tsx` | `Price`, `ProductCard`, `Field` |
+| `src/routes/` | products, cart, checkout and orders, sign-in, the API |
+| `test/shop.test.ts` | every flow, with `app.request()` and `app.client()` |
+| `e2e/shop.spec.ts` | the cart in a real browser |
+
+The [guides](https://toyz.github.io/yerd/#/guide/your-first-app) build a
+bigger version of this shop step by step.

package/templates/full/e2e/shop.spec.ts

@@ -0,0 +1,18 @@
+import { expect, test } from "@playwright/test";
+
+// What only a browser shows: the runtime morphs the answer in, no reload.
+// Everything else is covered faster by test/shop.test.ts.
+test("adds to the cart without reloading the page", async ({ page }) => {
+  await page.goto("/products/2");
+  // A marker a reload would wipe.
+  await page.evaluate(() => ((window as unknown as { marker: boolean }).marker = true));
+
+  await page.getByRole("button", { name: "Add to cart" }).click();
+  await expect(page.locator("#cart-badge .badge")).toHaveText("1");
+  await expect(page.locator("#stock")).toHaveText("25 in stock");
+  expect(await page.evaluate(() => (window as unknown as { marker?: boolean }).marker)).toBe(true);
+
+  await page.locator("#cart-badge").click();
+  await expect(page).toHaveTitle("Your cart · {{name}}");
+  await expect(page.getByRole("link", { name: "Pocket notebook" })).toBeVisible();
+});

package/templates/full/playwright.config.ts

@@ -0,0 +1,16 @@
+import { defineConfig, devices } from "@playwright/test";
+
+const port = Number(process.env.E2E_PORT ?? 4173);
+
+export default defineConfig({
+  testDir: "e2e",
+  use: { baseURL: `http://localhost:${port}` },
+  projects: [{ name: "chromium", use: { ...devices["Desktop Chrome"] } }],
+  // Against the production build, as it will run.
+  webServer: {
+    command: "{{run_build}} && {{run_start}}",
+    env: { PORT: String(port) },
+    url: `http://localhost:${port}/`,
+    reuseExistingServer: !process.env.CI,
+  },
+});

package/templates/full/public/favicon.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32"><rect width="32" height="32" rx="7" fill="#2f5d8a"/><path d="M9 9l7 9 7-9M16 18v6" fill="none" stroke="#fff" stroke-width="3.2" stroke-linecap="round" stroke-linejoin="round"/></svg>

package/templates/full/src/app.ts

@@ -0,0 +1,8 @@
+import { yerd, type YerdOptions } from "@toyz/yerd";
+import { ErrorPage, RootLayout } from "./layouts.js";
+import { auth } from "./users.js";
+
+/** The app without routes: main.ts discovers them, tests import the ones they need. */
+export function createApp(options?: YerdOptions) {
+  return yerd(options).layout(RootLayout).errorPage(ErrorPage).sessions().use(auth);
+}

package/templates/full/src/cart.ts

@@ -0,0 +1,50 @@
+import type { Catalog, Product } from "./catalog.js";
+
+export interface CartLine {
+  id: number;
+  qty: number;
+}
+
+/**
+ * The cart, as a session shape: `@session(Cart) accessor cart!: Session<Cart>`.
+ * Only ids and quantities are stored; names and prices come from the catalog
+ * at render. A new visitor gets no cookie until they add something.
+ */
+export class Cart {
+  lines: CartLine[] = [];
+
+  get count(): number {
+    return this.lines.reduce((sum, line) => sum + line.qty, 0);
+  }
+
+  add(id: number): void {
+    const line = this.lines.find((l) => l.id === id);
+    // In-place changes are noticed and saved, like assignments.
+    if (line) line.qty++;
+    else this.lines.push({ id, qty: 1 });
+  }
+
+  remove(id: number): void {
+    this.lines = this.lines.filter((l) => l.id !== id);
+  }
+
+  /** Not `clear()`: that's the session's own, and would sign the user out too. */
+  empty(): void {
+    this.lines = [];
+  }
+}
+
+export interface PricedLine {
+  product: Product;
+  qty: number;
+  subtotal: number;
+}
+
+/** The cart's lines with their products and prices. Products gone from the catalog drop out. */
+export function priceCart(lines: CartLine[], catalog: Catalog): { lines: PricedLine[]; total: number } {
+  const priced = lines.flatMap(({ id, qty }) => {
+    const product = catalog.get(id);
+    return product ? [{ product, qty, subtotal: product.price * qty }] : [];
+  });
+  return { lines: priced, total: priced.reduce((sum, line) => sum + line.subtotal, 0) };
+}

package/templates/full/src/catalog.ts

@@ -0,0 +1,59 @@
+import { NotFound, service } from "@toyz/yerd";
+
+export interface Product {
+  id: number;
+  name: string;
+  /** In cents: money is never a float. */
+  price: number;
+  stock: number;
+  description: string;
+}
+
+/** A NotFound: pages get the error page, the API a JSON 404 carrying the id. */
+export class ProductNotFound extends NotFound {
+  constructor(readonly id: number) {
+    super(`No product ${id}`, { details: { id } });
+  }
+}
+
+const PRODUCTS: Product[] = [
+  { id: 1, name: "Fountain pen", price: 4800, stock: 5, description: "Steel nib, fine point, refillable." },
+  { id: 2, name: "Pocket notebook", price: 900, stock: 25, description: "48 lined pages that fit a back pocket." },
+  { id: 3, name: "Desk lamp", price: 6500, stock: 3, description: "Warm light, one arm, no app." },
+  { id: 4, name: "Brass ruler", price: 1800, stock: 9, description: "Thirty centimetres, gets better with age." },
+  { id: 5, name: "Dot grid journal", price: 3200, stock: 0, description: "A5, 160 pages, numbered and dotted." },
+];
+
+/** The shelves, in memory. A singleton: every request sees the same stock. */
+@service
+export class Catalog {
+  // Copies, so tests and restarts start from the same shelves.
+  #products = PRODUCTS.map((p) => ({ ...p }));
+
+  /** Products whose name or description contains `q`. */
+  search(q = ""): Product[] {
+    const needle = q.toLowerCase();
+    return this.#products.filter((p) => `${p.name} ${p.description}`.toLowerCase().includes(needle));
+  }
+
+  get(id: number): Product | undefined {
+    return this.#products.find((p) => p.id === id);
+  }
+
+  /** Like get(), but a missing product answers the request with a 404. */
+  find(id: number): Product {
+    const product = this.get(id);
+    if (!product) throw new ProductNotFound(id);
+    return product;
+  }
+
+  /** Take sold items off the shelf. */
+  take(id: number, qty: number): void {
+    this.find(id).stock -= qty;
+  }
+}
+
+/** 2400 -> "$24.00". */
+export function formatPrice(cents: number): string {
+  return `$${(cents / 100).toFixed(2)}`;
+}

package/templates/full/src/components.tsx

@@ -0,0 +1,31 @@
+import { formatPrice, type Product } from "./catalog.js";
+
+export function Price({ cents }: { cents: number }) {
+  return <span class="price">{formatPrice(cents)}</span>;
+}
+
+export function ProductCard({ product }: { product: Product }) {
+  return (
+    <li class="card">
+      <a href={`/products/${product.id}`}>{product.name}</a>
+      <Price cents={product.price} />
+      {product.stock === 0 ? <span class="sold-out">Sold out</span> : null}
+    </li>
+  );
+}
+
+/**
+ * A labelled input with its error box. The runtime writes a failed field's
+ * message into [data-yx-error="<name>"]; a plain form post gets the same
+ * message from the server, via `error`.
+ */
+export function Field(props: { name: string; label: string; type?: string; value?: string | undefined; error?: string | undefined; autocomplete?: string }) {
+  const { name, label, type = "text", value, error, autocomplete } = props;
+  return (
+    <p class="field">
+      <label for={name}>{label}</label>
+      <input id={name} name={name} type={type} value={value} autocomplete={autocomplete} aria-invalid={error ? true : undefined} />
+      <span class="field-error" data-yx-error={name}>{error}</span>
+    </p>
+  );
+}

package/templates/full/src/layouts.tsx

@@ -0,0 +1,67 @@
+import { Region, Scripts, Stylesheet, currentContext, type ErrorPageProps, type LayoutProps } from "@toyz/yerd";
+import { Cart } from "./cart.js";
+import { auth } from "./users.js";
+
+/** The cart link in the header. A Region, so cart actions can send a new count. */
+export function CartBadge({ count }: { count: number }) {
+  return (
+    <Region id="cart-badge" as="a" href="/cart" class="cart-badge">
+      Cart <span class="badge">{count}</span>
+    </Region>
+  );
+}
+
+/** Items in the visitor's cart; 0 on routes without a session (the API). */
+function cartCount(): number {
+  const ctx = currentContext();
+  return ctx.route.session === false ? 0 : ctx.session.as(Cart).count;
+}
+
+/** The document. Every HTML response goes through it, error pages included. */
+export function RootLayout({ children, meta }: LayoutProps) {
+  const me = auth.current();
+  return (
+    <html lang="en">
+      <head>
+        <meta charset="utf-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1" />
+        <link rel="icon" href="/favicon.svg" type="image/svg+xml" />
+        <title>{meta.title ? `${meta.title} · {{name}}` : "{{name}}"}</title>
+        <Stylesheet href="src/styles.css" />
+        <Scripts />
+      </head>
+      <body>
+        <header class="top">
+          <a class="brand" href="/">{"{{name}}"}</a>
+          <CartBadge count={cartCount()} />
+          {me ? (
+            // A POST, not a link: a prefetch or a crawler must not sign anyone out.
+            <form class="account" method="post" action="/logout">
+              {me.name} <button class="link">Sign out</button>
+            </form>
+          ) : (
+            <a class="account" href="/login">Sign in</a>
+          )}
+        </header>
+        <main>{children}</main>
+      </body>
+    </html>
+  );
+}
+
+/** A narrow column for forms: sign-in, checkout, the receipt. */
+export function Narrow({ children }: LayoutProps) {
+  return <div class="narrow">{children}</div>;
+}
+
+/** app.errorPage(): 404s and crashes render here, inside RootLayout. */
+export function ErrorPage({ status, message }: ErrorPageProps) {
+  return (
+    <section class="error-page">
+      <p class="status">{status}</p>
+      <h1>{status === 404 ? "Not on the shelves" : "Something went wrong"}</h1>
+      <p>{message}</p>
+      <a href="/">Back to the shop</a>
+    </section>
+  );
+}

package/templates/full/src/main.ts

@@ -0,0 +1,5 @@
+/// <reference types="vite/client" />
+import { createApp } from "./app.js";
+
+// The Vite entry. The plugin serves it in dev and the build's server.js listens: no listen() here.
+export default createApp().discover(import.meta.glob("./routes/**/*.{ts,tsx}", { eager: true }));

package/templates/full/src/orders.ts

@@ -0,0 +1,52 @@
+import { BadRequest, Conflict, inject, is, length, service, trim } from "@toyz/yerd";
+import { priceCart, type CartLine } from "./cart.js";
+import { Catalog } from "./catalog.js";
+import type { User } from "./users.js";
+
+/** The checkout form. Every field is checked on the server; the browser's checks are a courtesy. */
+export class CheckoutForm {
+  @is.string({ transform: trim, validate: length(2, 80) }) name!: string;
+  @is.email() email!: string;
+  @is.string({ transform: trim, validate: length(5, 200) }) address!: string;
+}
+
+export interface Order {
+  id: number;
+  userId: string;
+  email: string;
+  /** Names and prices as they were when the order was placed. */
+  lines: Array<{ name: string; price: number; qty: number }>;
+  total: number;
+}
+
+@service
+export class Orders {
+  @inject(Catalog) accessor catalog!: Catalog;
+  #orders: Order[] = [];
+  #next = 1001;
+
+  /** Check the stock, take it, keep the order. Throws before taking anything if a line can't be filled. */
+  place(user: User, details: CheckoutForm, cart: CartLine[]): Order {
+    const { lines, total } = priceCart(cart, this.catalog);
+    if (lines.length === 0) throw new BadRequest("Your cart is empty.");
+    for (const { product, qty } of lines) {
+      if (product.stock < qty) throw new Conflict(`Only ${product.stock} of ${product.name} left.`);
+    }
+    for (const { product, qty } of lines) this.catalog.take(product.id, qty);
+
+    const order: Order = {
+      id: this.#next++,
+      userId: user.id,
+      email: details.email,
+      lines: lines.map(({ product, qty }) => ({ name: product.name, price: product.price, qty })),
+      total,
+    };
+    this.#orders.push(order);
+    return order;
+  }
+
+  /** Someone's own order; another user's is as missing as one that never existed. */
+  get(id: number, user: User): Order | undefined {
+    return this.#orders.find((o) => o.id === id && o.userId === user.id);
+  }
+}

package/templates/full/src/routes/api.ts

@@ -0,0 +1,34 @@
+import { HttpStatus, get, inject, param, query, route, toInt, trim } from "@toyz/yerd";
+import { Catalog, ProductNotFound } from "../catalog.js";
+
+// The JSON API. `session: false`: API clients get no cookie, and no session is read.
+
+@route("/api/products", { session: false })
+export class ProductsApi {
+  @inject(Catalog) accessor catalog!: Catalog;
+  @query("q", { transform: trim }) accessor q = "";
+
+  @get list() {
+    // An array becomes JSON.
+    return this.catalog.search(this.q);
+  }
+}
+
+@route("/api/products/:id", { session: false })
+export class ProductApi {
+  @inject(Catalog) accessor catalog!: Catalog;
+  @param("id", { transform: toInt }) accessor id!: number;
+
+  @get show() {
+    // A returned error counts as thrown: a JSON 404 with the id.
+    return this.catalog.get(this.id) ?? new ProductNotFound(this.id);
+  }
+}
+
+/** For load balancers and uptime checks: 204, no body. */
+@route("/api/health", { session: false })
+export class Health {
+  @get check() {
+    return HttpStatus.NoContent;
+  }
+}