create-nwire 0.7.1 → 0.8.17

package/templates/L2/__tests__/todo-api.test.ts

@@ -0,0 +1,115 @@
+/**
+ * Smoke test — the four CRUD operations + the requireUser middleware.
+ *
+ * Boots the api against a real Node http server, registers a fresh
+ * in-memory TodoStore on a container, and dispatches fetch requests
+ * exactly the way clients will.
+ */
+
+import { describe, it, expect, beforeAll, afterAll } from "vitest";
+import http from "node:http";
+import type { Server } from "node:http";
+import { InMemoryContainer } from "@nwire/container";
+import { TodoStore } from "../app/store/todo-store";
+import { api } from "../app/api";
+
+let server: Server;
+let url: string;
+
+beforeAll(async () => {
+  const container = new InMemoryContainer();
+  container.register("todos", new TodoStore());
+  api.provide(container);
+
+  server = http.createServer(api.compile());
+  await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", resolve));
+  const addr = server.address() as { port: number };
+  url = `http://127.0.0.1:${addr.port}`;
+});
+
+afterAll(async () => {
+  await new Promise<void>((resolve, reject) =>
+    server.close((err) => (err ? reject(err) : resolve())),
+  );
+});
+
+async function req(
+  path: string,
+  init: RequestInit & { user?: string } = {},
+): Promise<{ status: number; body: unknown }> {
+  const headers: Record<string, string> = {
+    "content-type": "application/json",
+    ...((init.headers as Record<string, string>) ?? {}),
+  };
+  if (init.user) headers["x-user-id"] = init.user;
+  const res = await fetch(`${url}${path}`, { ...init, headers });
+  const text = await res.text();
+  let body: unknown = text;
+  try {
+    body = JSON.parse(text);
+  } catch {
+    /* keep as text */
+  }
+  return { status: res.status, body };
+}
+
+describe("todo api", () => {
+  it("requires x-user-id (requireUser middleware)", async () => {
+    const r = await req("/api/todos", { method: "GET" });
+    expect(r.status).toBe(401);
+    expect((r.body as { error: { code: string } }).error.code).toBe("MISSING_USER_ID");
+  });
+
+  it("creates, lists, completes, deletes", async () => {
+    // create
+    const created = await req("/api/todos", {
+      method: "POST",
+      body: JSON.stringify({ text: "buy milk" }),
+      user: "alice",
+    });
+    expect(created.status).toBe(201);
+    const todo = created.body as { id: string; text: string; status: string };
+    expect(todo.text).toBe("buy milk");
+    expect(todo.status).toBe("open");
+
+    // list
+    const listed = await req("/api/todos", { method: "GET", user: "alice" });
+    expect(listed.status).toBe(200);
+    const list = listed.body as { items: Array<{ id: string }>; total: number };
+    expect(list.total).toBe(1);
+    expect(list.items[0]!.id).toBe(todo.id);
+
+    // complete
+    const completed = await req(`/api/todos/${todo.id}/complete`, {
+      method: "POST",
+      user: "alice",
+    });
+    expect(completed.status).toBe(200);
+    expect((completed.body as { status: string }).status).toBe("completed");
+
+    // double-complete → 409
+    const again = await req(`/api/todos/${todo.id}/complete`, {
+      method: "POST",
+      user: "alice",
+    });
+    expect(again.status).toBe(409);
+
+    // delete
+    const removed = await req(`/api/todos/${todo.id}`, {
+      method: "DELETE",
+      user: "alice",
+    });
+    expect(removed.status).toBe(204);
+  });
+
+  it("isolates todos per user (alice doesn't see bob's)", async () => {
+    await req("/api/todos", {
+      method: "POST",
+      body: JSON.stringify({ text: "bob's task" }),
+      user: "bob",
+    });
+    const aliceList = await req("/api/todos", { method: "GET", user: "alice" });
+    const items = (aliceList.body as { items: Array<{ text: string }> }).items;
+    expect(items.find((i) => i.text === "bob's task")).toBeUndefined();
+  });
+});

package/templates/L2/app/api.ts

@@ -1,125 +1,30 @@
 /**
- * The HTTP interface — four routes + their inline handlers.
+ * HTTP interface — the surface this app exposes.
  *
- * Each route binding carries its own schemas (params + body + query);
- * the framework validates the request against them before the handler
- * runs. The handler receives a typed `input` (merged from all three)
- * plus the resolved request context.
+ * One `.wire(Route, Handler)` line per route. To add a new route, drop a
+ * file under `./routes/` exporting `{name}Route + {name}Handler`, then
+ * `.wire()` it in here.
  *
- * What the handler reads from ctx:
+ * Each route's verb + path + schema + handler live in one file under
+ * `./routes/`. The interface stays a 1-line-per-route reducer — easy to
+ * audit, easy to grep, no second config file.
  *
- *   - `input`            parsed + validated route input
- *   - `resolve<T>(name)` container binding (e.g. the todo store)
- *   - `_raw`             Koa context (for state.userId set by requireUser)
- *
- * The middleware chain `requireUser` runs before EVERY route — adding it
- * once at the interface level instead of repeating per-route. Per-route
- * middleware would go on individual `.wire(...)` calls if needed.
- *
- * Response shapes use `Todo.project(record)` so the public field list
- * defined on the model controls what ships. No hand-mapping; no risk
- * of an internal field leaking.
+ * Cross-cutting:
+ *   - `requireUser` middleware runs before EVERY route (chained once here).
+ *   - `.provide(container)` is wired by `main.ts` with the todo store.
  */
 
-import { httpInterface, get, post, del } from "@nwire/http";
-import { z } from "zod";
-import { Todo, type TodoRecord } from "./model";
-import { TodoStore } from "./store";
-import { TodoNotFound, TodoAlreadyCompleted } from "./errors";
-import { requireUser } from "./middleware";
+import { httpInterface } from "@nwire/http";
+import { requireUser } from "./middleware/require-user";
 
-// ─── The interface ────────────────────────────────────────────────
+import { listTodosRoute, listTodosHandler } from "./routes/list-todos";
+import { createTodoRoute, createTodoHandler } from "./routes/create-todo";
+import { completeTodoRoute, completeTodoHandler } from "./routes/complete-todo";
+import { deleteTodoRoute, deleteTodoHandler } from "./routes/delete-todo";
 
 export const api = httpInterface({ prefix: "/api" })
   .use(requireUser)
-
-  // POST /api/todos — add
-  .wire(
-    post("/todos", {
-      body: z.object({ text: z.string().min(1).max(500) }),
-    }),
-    async ({ input, resolve, _raw }) => {
-      const { text } = input as { text: string };
-      const store = resolve<TodoStore>("todos");
-      const userId = _raw.state.userId as string;
-      const todo = store.add({ userId, text });
-      return { $status: 201, body: project(todo) };
-    },
-  )
-
-  // GET /api/todos?status=open|completed — list
-  .wire(
-    get("/todos", {
-      query: z.object({
-        status: z.enum(["open", "completed"]).optional(),
-      }),
-    }),
-    async ({ input, resolve, _raw }) => {
-      const { status } = input as { status?: "open" | "completed" };
-      const store = resolve<TodoStore>("todos");
-      const userId = _raw.state.userId as string;
-      const list = store.listByUser(userId, status);
-      return { items: list.map(project), total: list.length };
-    },
-  )
-
-  // POST /api/todos/:id/complete — mark complete
-  .wire(
-    post("/todos/:id/complete", {
-      params: z.object({ id: z.string() }),
-    }),
-    async ({ input, resolve, _raw }) => {
-      const { id } = input as { id: string };
-      const store = resolve<TodoStore>("todos");
-      const userId = _raw.state.userId as string;
-
-      const existing = store.get(id);
-      if (!existing || existing.userId !== userId) throw TodoNotFound;
-      if (existing.status === "completed") throw TodoAlreadyCompleted;
-
-      const updated = store.complete(id);
-      return project(updated!);
-    },
-  )
-
-  // DELETE /api/todos/:id — remove
-  .wire(
-    del("/todos/:id", {
-      params: z.object({ id: z.string() }),
-    }),
-    async ({ input, resolve, _raw }) => {
-      const { id } = input as { id: string };
-      const store = resolve<TodoStore>("todos");
-      const userId = _raw.state.userId as string;
-
-      const existing = store.get(id);
-      if (!existing || existing.userId !== userId) throw TodoNotFound;
-
-      store.remove(id);
-      return null; // → 204 No Content
-    },
-  );
-
-// ─── Helpers ──────────────────────────────────────────────────────
-
-/**
- * `project()` shapes the internal record onto the public Todo model.
- * In a richer setup with `response.list(Todo)` this happens automatically.
- * Here we call it explicitly so the example reads top-to-bottom.
- */
-function project(t: TodoRecord) {
-  return {
-    id: t.id,
-    userId: t.userId,
-    text: t.text,
-    status: t.status,
-    addedAt: t.addedAt,
-    completedAt: t.completedAt,
-  };
-}
-
-// Reference Todo so the import isn't tree-shaken — the model is the
-// canonical declaration of the public field set, even when we project
-// by hand. Future: switch to response.list(Todo) once the new builder
-// has the project() helper wired.
-void Todo;
+  .wire(listTodosRoute, listTodosHandler)
+  .wire(createTodoRoute, createTodoHandler)
+  .wire(completeTodoRoute, completeTodoHandler)
+  .wire(deleteTodoRoute, deleteTodoHandler);

package/templates/L2/app/{errors.ts → errors/todo-errors.ts}

@@ -2,11 +2,11 @@
  * Typed errors — throwable values, rendered per transport.
  *
  * `defineError` returns an Error subclass with `code` + `status` baked
- * in. In a resolver handler you just `throw TodoNotFound` and the HTTP
- * transport renders it as JSON `{ error: { code: "TODO_NOT_FOUND" } }`
- * with status 404. GraphQL would render it as a GQL error with the same
- * extensions. CLI would print + exit with the right code. One error
- * declaration, every transport does the right thing.
+ * in. In a route handler you `throw TodoNotFound` and the HTTP transport
+ * renders it as JSON `{ error: { code: "TODO_NOT_FOUND" } }` with status
+ * 404. GraphQL would render it as a GQL error with the same extensions.
+ * CLI would print + exit with the right code. One error declaration,
+ * every transport does the right thing.
  *
  * Bonus: clients can switch on `error.code` to render UI per-case
  * (toast "Already done!" vs full 404 page). The shape is part of the
@@ -44,5 +44,5 @@ export const NoUserId = defineError({
   summary: "Caller must provide x-user-id header",
 });
 
-// Re-export common framework errors so resolvers import from one place.
+// Re-export common framework errors so handlers import from one place.
 export { Unauthorized, Forbidden, NotFound, Gone } from "@nwire/forge";

package/templates/L2/app/main.ts

@@ -1,17 +1,17 @@
 /**
  * Entry point — wire the store into the http interface, then run.
  *
- * The shape for Level 1:
+ * The shape for Level 2:
  *
  *   1. Build an in-memory container, register the store on it.
- *   2. Hand it to the http interface via `.provide()` — the resolvers'
- *      `resolve("todos")` reads from there.
+ *   2. Hand it to the http interface via `.provide()` — route handlers
+ *      read it with `resolve<TodoStore>("todos")`.
  *   3. Wrap in `endpoint()` for graceful shutdown + K8s probes.
  *
  * No `createApp` here. With ONE binding and zero plugin lifecycle work,
- * createApp adds ceremony without value. The station-management example
- * shows the full createApp + plugin shape with many bindings and
- * framework events; Level 1 doesn't need it.
+ * createApp adds ceremony without value. The L4 template (and the
+ * station-management example) show the full createApp + plugin shape
+ * with many bindings and framework events; L2 doesn't need it.
  *
  * Run:    pnpm dev
  * Try:    curl -X POST http://localhost:3000/api/todos \
@@ -24,7 +24,7 @@
 
 import { endpoint } from "@nwire/endpoint";
 import { InMemoryContainer } from "@nwire/container";
-import { TodoStore } from "./store";
+import { TodoStore } from "./store/todo-store";
 import { api } from "./api";
 
 const container = new InMemoryContainer();

package/templates/L2/app/middleware/require-user.ts

@@ -0,0 +1,29 @@
+/**
+ * `requireUser` — tiny auth shim that proves the middleware-chain pattern.
+ *
+ * A real app would use `@nwire/auth` + an IdP adapter (Logto, better-auth,
+ * etc.) to extract `user` from a JWT in the Authorization header. For this
+ * template we trust the `x-user-id` header so the test suite stays focused
+ * on the framework shape, not on JWT handling.
+ *
+ * The middleware does two things:
+ *
+ *   1. Throws `NoUserId` if the header is absent — surfaces as 401 JSON.
+ *   2. Attaches the user id to Koa state so handlers can read it without
+ *      re-parsing the request.
+ *
+ * Routes chain it once via `.use(requireUser)` in `api.ts`; auth lives at
+ * the interface seam, not inside business logic.
+ */
+
+import type { HttpMiddleware } from "@nwire/http";
+import { NoUserId } from "../errors/todo-errors";
+
+export const requireUser: HttpMiddleware = async (ctx, next) => {
+  const userId = ctx.request.headers["x-user-id"];
+  if (typeof userId !== "string" || userId.length === 0) {
+    throw NoUserId;
+  }
+  ctx.state.userId = userId;
+  await next();
+};

package/templates/L2/app/{model.ts → resources/todo.ts}

@@ -9,10 +9,10 @@
  * the strip is explicit, and reviewers can see what the API exposes by
  * scanning one array.
  *
- * The same `Todo` model is used by every resolver that returns todos —
- * single, list, paginated. `response.list(Todo)` and `response.ok(Todo)`
- * both call `Todo.project()` on each record so the public field rules
- * apply once, declared in one place.
+ * The same `Todo` resource is used by every route handler that returns
+ * todos — single, list, paginated. Future: `response.list(Todo)` and
+ * `response.ok(Todo)` will call `Todo.project()` on each record so the
+ * public field rules apply once, declared in one place.
  */
 
 import { z } from "zod";
@@ -56,5 +56,21 @@ export const Todo = defineResource("Todo", {
   },
 });
 
-/** Inferred TS type — what handlers work with internally. */
+/** Inferred TS type — what handlers + the store work with internally. */
 export type TodoRecord = z.infer<typeof Todo.schema>;
+
+/**
+ * `project()` shapes the internal record onto the public Todo shape.
+ * Today this just hand-picks fields; future versions will call
+ * `Todo.project(record)` once the helper lands on `defineResource`.
+ */
+export function project(t: TodoRecord) {
+  return {
+    id: t.id,
+    userId: t.userId,
+    text: t.text,
+    status: t.status,
+    addedAt: t.addedAt,
+    completedAt: t.completedAt,
+  };
+}

package/templates/L2/app/routes/complete-todo.ts

@@ -0,0 +1,36 @@
+/**
+ * POST /api/todos/:id/complete — mark a todo done.
+ *
+ * Two negative cases mapped to typed errors:
+ *
+ *   - Todo doesn't exist OR belongs to another user → `TodoNotFound` (404)
+ *   - Todo already completed → `TodoAlreadyCompleted` (409)
+ *
+ * Throwing typed errors keeps the handler readable; transport translates.
+ */
+
+import { post, type HttpHandler } from "@nwire/http";
+import { z } from "zod";
+import { TodoStore } from "../store/todo-store";
+import { project } from "../resources/todo";
+import { TodoNotFound, TodoAlreadyCompleted } from "../errors/todo-errors";
+
+const Params = z.object({ id: z.string() });
+
+export const completeTodoRoute = post("/todos/:id/complete", { params: Params });
+
+export const completeTodoHandler: HttpHandler<z.infer<typeof Params>> = async ({
+  input,
+  resolve,
+  _raw,
+}) => {
+  const store = resolve<TodoStore>("todos");
+  const userId = _raw.state.userId as string;
+
+  const existing = store.get(input.id);
+  if (!existing || existing.userId !== userId) throw TodoNotFound;
+  if (existing.status === "completed") throw TodoAlreadyCompleted;
+
+  const updated = store.complete(input.id);
+  return project(updated!);
+};

package/templates/L2/app/routes/create-todo.ts

@@ -0,0 +1,27 @@
+/**
+ * POST /api/todos — add a new todo to the caller's list.
+ *
+ * Returns 201 + the new todo. The handler reads `userId` from Koa state
+ * (set by `requireUser` middleware) and the store from the request-scoped
+ * container.
+ */
+
+import { post, type HttpHandler } from "@nwire/http";
+import { z } from "zod";
+import { TodoStore } from "../store/todo-store";
+import { project } from "../resources/todo";
+
+const Body = z.object({ text: z.string().min(1).max(500) });
+
+export const createTodoRoute = post("/todos", { body: Body });
+
+export const createTodoHandler: HttpHandler<z.infer<typeof Body>> = async ({
+  input,
+  resolve,
+  _raw,
+}) => {
+  const store = resolve<TodoStore>("todos");
+  const userId = _raw.state.userId as string;
+  const todo = store.add({ userId, text: input.text });
+  return { $status: 201, body: project(todo) };
+};

package/templates/L2/app/routes/delete-todo.ts

@@ -0,0 +1,31 @@
+/**
+ * DELETE /api/todos/:id — remove a todo from the caller's list.
+ *
+ * Returns 204 (no content). Throws `TodoNotFound` if the id is unknown
+ * OR belongs to another user — never leak "exists but not yours" vs
+ * "doesn't exist", that's an information-disclosure vector.
+ */
+
+import { del, type HttpHandler } from "@nwire/http";
+import { z } from "zod";
+import { TodoStore } from "../store/todo-store";
+import { TodoNotFound } from "../errors/todo-errors";
+
+const Params = z.object({ id: z.string() });
+
+export const deleteTodoRoute = del("/todos/:id", { params: Params });
+
+export const deleteTodoHandler: HttpHandler<z.infer<typeof Params>> = async ({
+  input,
+  resolve,
+  _raw,
+}) => {
+  const store = resolve<TodoStore>("todos");
+  const userId = _raw.state.userId as string;
+
+  const existing = store.get(input.id);
+  if (!existing || existing.userId !== userId) throw TodoNotFound;
+
+  store.remove(input.id);
+  return null; // → 204 No Content
+};

package/templates/L2/app/routes/list-todos.ts

@@ -0,0 +1,28 @@
+/**
+ * GET /api/todos — list the caller's todos, optionally filtered by status.
+ *
+ * Returns `{ items, total }`. The store sorts so open-first by added-at;
+ * the handler just projects the records and counts.
+ */
+
+import { get, type HttpHandler } from "@nwire/http";
+import { z } from "zod";
+import { TodoStore } from "../store/todo-store";
+import { project } from "../resources/todo";
+
+const Query = z.object({
+  status: z.enum(["open", "completed"]).optional(),
+});
+
+export const listTodosRoute = get("/todos", { query: Query });
+
+export const listTodosHandler: HttpHandler<z.infer<typeof Query>> = async ({
+  input,
+  resolve,
+  _raw,
+}) => {
+  const store = resolve<TodoStore>("todos");
+  const userId = _raw.state.userId as string;
+  const list = store.listByUser(userId, input.status);
+  return { items: list.map(project), total: list.length };
+};

package/templates/L2/app/{store.ts → store/todo-store.ts}

@@ -11,13 +11,17 @@
  *
  * In a real app you'd swap the store for `@nwire/data-drizzle` against
  * Postgres or `@nwire/store-mongo` against Mongo. The PLUGIN shape stays
- * the same — `provide("todos", { boot, shutdown })`. Resolvers always do
- * `ctx.resolve("todos")` and get whatever the plugin booted.
+ * the same — `provide("todos", { boot, shutdown })`. Handlers always do
+ * `resolve("todos")` and get whatever the plugin booted.
+ *
+ * The L2 template uses the simpler container-register-then-provide path
+ * from `main.ts` (no createApp). The plugin form is exported so it's
+ * one rename away once you graduate to L4.
  */
 
 import { randomUUID } from "node:crypto";
 import { definePlugin } from "@nwire/app";
-import type { TodoRecord } from "./model";
+import type { TodoRecord } from "../resources/todo";
 
 // ─── The store itself ────────────────────────────────────────────
 
@@ -92,18 +96,22 @@ export class TodoStore {
   }
 }
 
-// ─── The plugin ──────────────────────────────────────────────────
+// ─── The plugin (optional — used when you graduate to L4) ────────
 
 /**
  * Plugin shape: `provide("todos", { boot, shutdown })`.
  *
  * The framework calls `boot()` during app start, registers the result
  * on the container under the name we chose, and calls `shutdown(store)`
- * during graceful drain. From any resolver's ctx: `ctx.resolve("todos")`.
+ * during graceful drain. From any handler: `resolve("todos")`.
  *
  * This same shape works whether the store is in-memory (here), a Pool
  * (Postgres via Drizzle), or a MongoClient. The plugin wrapper handles
  * the lifecycle; the store implementation handles its own concerns.
+ *
+ * L2 main.ts uses the simpler `container.register(...)` path because we
+ * don't have a forge app yet. The plugin is exported so L4 graduation
+ * is `import { todoStorePlugin } from "./store/todo-store"`.
  */
 export const todoStorePlugin = definePlugin("todos", ({ provide }) => {
   provide("todos", {

package/templates/L2/package.json

@@ -8,11 +8,11 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@nwire/app": "^0.7.0",
-    "@nwire/container": "^0.7.0",
-    "@nwire/endpoint": "^0.7.0",
-    "@nwire/forge": "^0.7.0",
-    "@nwire/http": "^0.7.0",
+    "@nwire/app": "^0.8.17",
+    "@nwire/container": "^0.8.17",
+    "@nwire/endpoint": "^0.8.17",
+    "@nwire/forge": "^0.8.17",
+    "@nwire/http": "^0.8.17",
     "zod": "^4.0.0"
   },
   "devDependencies": {

package/templates/L2/tsconfig.json

@@ -11,5 +11,5 @@
     "noEmit": true,
     "types": ["node", "vite/client"]
   },
-  "include": ["app/**/*"]
+  "include": ["app/**/*", "__tests__/**/*"]
 }