@palbase/backend 24.3.0 → 25.0.0

package/docs/README.md

@@ -23,17 +23,26 @@ services/<name>.service.ts          # plain class + singleton — the real logic
 db/schema.ts                        # config-as-code Postgres schema (tables, columns, RLS) — auto-migrated on deploy
 ```
 
-The four folders above are the daily surface. These also exist (own docs, linked
-below): `resources/` (plain modules a controller imports — a client, a
-formatter, anything shared), `seeds/` (seed data), `jobs/` (background — [background.md](./background.md)),
-`webhooks/` + `hooks/` (events — [events.md](./events.md)), `middleware/`.
+The four folders above are the daily surface. Three more are discovered by name,
+one class per file, `export default` required: `jobs/` (background —
+[background.md](./background.md)), `webhooks/` and `hooks/` (events —
+[events.md](./events.md)).
+
+There is no `resources/`, no `seeds/` and no working `middleware/`. `middleware/`
+is discovered by nothing and the engine has no middleware pipeline: code written
+against it deploys, never runs, and nothing says so. Put cross-cutting work in a
+service the controllers call.
 
 ### The 7 rules (checklist)
 
-1. **`export default <ControllerClass>` is REQUIRED.** Every `controllers/*.controller.ts`
-   must default-export its `@Controller` class, or the deploy FAILS with a
-   "not a @Controller / non-controller export" error. Either `export default class X {}`
-   or a trailing `export default X;` — both work.
+1. **A controller needs NO export at all.** `@Controller` records the class into a
+   `globalThis` registry as it decorates it, and the bundler imports the file for
+   that side effect alone — the shipped scaffold's own `HealthController` and
+   `NotesController` are not exported. Exporting is harmless and reads well, so
+   these examples do it; it is not a requirement. (`export default` **is**
+   required for `jobs/`, `webhooks/`, `hooks/` and `db/public.ts`, one class per
+   file.) What IS fatal is a `@Controller` class that collected zero routes —
+   usually `experimentalDecorators` missing from `tsconfig.json`.
 2. **Methods that call a service are `async` and return `Promise<T>`.** Services
    `await Database`, so they return promises; a sync return type on an async body
    is a tsc error. Annotate `: Promise<TodoSchema>`, not `: TodoSchema`, whenever
@@ -62,7 +71,7 @@ formatter, anything shared), `seeds/` (seed data), `jobs/` (background — [back
 
 > **Never** emit `defineController`, `defineHandler`, `defineEndpoint`, `route.get(...)`,
 > `req.input`, `req.params`, or `req.errors` — those are the removed legacy model
-> and will not compile against `@palbase/backend` 4.
+> and will not compile against `@palbase/backend` 25.
 
 ### Complete CRUD example (copy-pasteable, compiles)
 
@@ -89,25 +98,44 @@ export type CreateTodoBody = z.infer<typeof CreateTodoBody>;
 import { Database, NotFound } from "@palbase/backend";
 import type { TodoSchema } from "../models/todos/shared.js";
 
+/** The typed surface of ONE table. Naming it keeps the seam one table wide:
+ * a test fake implements five methods, not the whole `Database`. */
+type TodosTable = typeof Database.tables.todos;
+
 export class TodoService {
+  private readonly todos: TodosTable;
+
+  // THE SEAM IS THE CONSTRUCTOR: the class is handed the table rather than
+  // reaching for the singleton, so a test constructs it with a stand-in and
+  // never needs a database. Assign in the BODY — a parameter property
+  // (`constructor(private todos: …)`) is refused by Node's type-stripping test
+  // runner, and refused for the whole FILE.
+  constructor(todos: TodosTable) {
+    this.todos = todos;
+  }
+
   list(userId: string): Promise<TodoSchema[]> {
-    return Database.tables.todos.findMany({ user_id: userId });
+    return this.todos.findMany({ user_id: userId });
   }
   create(userId: string, title: string): Promise<TodoSchema> {
-    return Database.tables.todos.insert({ user_id: userId, title });
+    return this.todos.insert({ user_id: userId, title });
   }
   async get(userId: string, id: string): Promise<TodoSchema> {
-    const t = await Database.tables.todos.findById(id);
+    const t = await this.todos.findById(id);
     if (!t || t.user_id !== userId) throw new NotFound("No todo with that id");
     return t;
   }
   async remove(userId: string, id: string): Promise<void> {
-    const t = await Database.tables.todos.findById(id);
-    if (!t || t.user_id !== userId) throw new NotFound("No todo with that id");
-    await Database.tables.todos.delete(id);
+    await this.get(userId, id);
+    await this.todos.delete(id);
   }
 }
-export const todoService = new TodoService();
+
+/** The wired instance. Controllers import THIS, never the class. It is also the
+ * ONLY supported way to hold a dependency: a controller, job, hook or webhook is
+ * constructed with no arguments, and one that declares a constructor parameter
+ * is refused at build with the class named. */
+export const todoService = new TodoService(Database.tables.todos);
 ```
 
 ```ts
@@ -119,31 +147,33 @@ import { TodoSchema } from "../models/todos/shared.js";
 import { CreateTodoBody } from "../models/todos/create.js";
 
 @Controller("/todos")                                  // secure-by-default; { auth: false } opts the whole controller out
-export class TodosController {
-  private todos = todoService;
+export default class TodosController {
+  // The service arrives as an IMPORTED SINGLETON, not a constructor parameter:
+  // the runtime constructs this class with no arguments, and one that declares a
+  // parameter is refused at build with the class named.
 
   @Get("")                                             // GET /todos → operationId todos.list
   async list(@User() user: UserT): Promise<TodoSchema[]> {  // return type → 200 response schema
-    return this.todos.list(user.id);
+    return todoService.list(user.id);
   }
 
   @Post("")                                            // POST /todos → todos.create
   async create(@Body(CreateTodoBody) body: CreateTodoBody, @User() user: UserT): Promise<TodoSchema> {
-    return this.todos.create(user.id, body.title);
+    return todoService.create(user.id, body.title);
   }
 
   @Get("/{id}")                                        // GET /todos/{id} → todos.get
   async get(@Param("id") id: string, @User() user: UserT): Promise<TodoSchema> {
-    return this.todos.get(user.id, id);
+    return todoService.get(user.id, id);
   }
 
   @Delete("/{id}")                                     // DELETE /todos/{id} → todos.remove; no body → : Promise<void>
   async remove(@Param("id") id: string, @User() user: UserT): Promise<void> {
-    await this.todos.remove(user.id, id);
+    await todoService.remove(user.id, id);
   }
 }
-
-export default TodosController;                         // REQUIRED — the runtime loads the default export
+// No export is needed at all — @Controller registered the class as it decorated
+// it. `export default` here is style, not a requirement.
 ```
 
 ```ts
@@ -230,7 +260,10 @@ The **only difference** is the trigger argument:
 | **Jobs** (`jobs/**`) | `(meta)` | `JobMeta` |
 | **Hooks** (`hooks/**`) | `(event, meta)` | typed event + `HookMeta` |
 | **Webhooks** (`webhooks/**`) | `(event, meta)` | typed event + `WebhookMeta` |
-| **Middleware** (`middleware/**`) | `(ctx, next)` | `MiddlewareContext` — the **one exception** |
+
+`defineMiddleware` is still exported and takes `(ctx, next)`, but **no bundler
+reads a `middleware/` directory and the engine never calls one** — there is no
+`ctx` anywhere on a path that runs. Every handler above imports its services.
 
 `meta` carries non-service data: `env` (Environment variables),
 `environmentId`, and for webhooks `requestId`. Services always come from
@@ -247,16 +280,16 @@ my-backend/
 ├── models/<ctrl>/<ep>.ts   # zod schemas, folder per controller, file per endpoint
 │   └── hello/greet.ts      # GreetQuery + HelloResponse (zod value + z.infer type)
 ├── services/               # plain classes/singletons your controllers call
-├── db/schema.ts            # table definitions (optional, enables typed DB)
-├── db/migrations/          # explicit SQL migrations for type changes (optional)
-├── resources/              # external connections, set up once at boot (optional)
-├── seeds/                  # seed data (optional)
+├── db/public.ts            # the database itself: tables, columns, RLS policies
 ├── jobs/                   # cron-scheduled jobs (optional)
 ├── hooks/                  # auth/storage/document event hooks (optional)
-├── webhooks/               # inbound provider webhooks (optional)
-└── middleware/             # cross-cutting request middleware (optional)
+└── webhooks/               # inbound provider webhooks (optional)
 ```
 
+There is **no `db/migrations/`**. Nothing generates a migration file, nothing
+commits one and nothing replays one: `db/schema.ts` is diffed against the live
+database and applied — see [migrations.md](./migrations.md).
+
 HTTP endpoints are **not** file-path routed. You author a class controller
 (`@Controller("/base")` with `@Get`/`@Post`/… methods); putting it under
 `controllers/` mounts it. See [routing.md](./routing.md).

package/docs/endpoints.md

@@ -12,35 +12,38 @@ imported singletons (see [services.md](./services.md)).
 
 ```ts
 // controllers/rooms.controller.ts
-import { Controller, Get, Post, Body, Param, User, NotFound, Database } from "@palbase/backend";
+import { Controller, Get, Post, Body, Param, User } from "@palbase/backend";
 import type { UserT } from "@palbase/backend";
+import { roomService } from "../services/room.service.js";
 import { CreateRoomBody } from "../models/rooms/create.js";
 import type { RoomSchema } from "../models/rooms/shared.js";  // the return TYPE names the 200 schema
 
+// A controller does not import `Database`. Everything here is HTTP: validate the
+// body through a named schema, name the 200 shape as the return type, delegate.
+// Which rows, whose, in what order is the service's job — and the service is the
+// thing worth testing, because it is the thing that can be wrong.
 @Controller("/rooms")
 export default class RoomsController {
   @Post("")
-  async create(@Body(CreateRoomBody) body: CreateRoomBody, @User() user: UserT): Promise<RoomSchema> {
-    const room = await Database.insert("rooms", { name: body.name, capacity: body.capacity ?? null });
-    return { id: room.id as string, name: room.name as string, capacity: (room.capacity as number) ?? null };
+  create(@Body(CreateRoomBody) body: CreateRoomBody, @User() user: UserT): Promise<RoomSchema> {
+    return roomService.create(user.id, body);
   }
 
   @Get("/{id}")
-  async getOne(@Param("id") id: string): Promise<RoomSchema> {
-    const room = await Database.findById("rooms", id);
-    if (!room) throw new NotFound("Room does not exist", "room_not_found");
-    return { id: room.id as string, name: room.name as string, capacity: (room.capacity as number) ?? null };
+  getOne(@Param("id") id: string): Promise<RoomSchema> {
+    return roomService.get(id);
   }
 }
 ```
 
 **Two non-negotiables** (the most common codegen mistakes):
 
-1. **`export default <Controller>` is REQUIRED.** Above it is
-   `export default class RoomsController`; the trailing form `export class
-   RoomsController {…}` + `export default RoomsController;` is equivalent. Without
-   a default export the deploy aborts with a "not a @Controller / non-controller
-   export" error — the runtime loads the file's default export.
+1. **The controller does not touch the database.** It delegates to a service, as
+   above. A method here that reaches for `Database` has moved the logic into the
+   layer that is hardest to test. (An export is not required at all: `@Controller`
+   records the class as it decorates it, and importing the file IS the
+   registration — the shipped scaffold's own controllers are not exported.
+   `export default` here is style.)
 2. **A method that awaits a service is `async` + `Promise<T>`.** `Database`
    returns promises, so a body that `await`s it cannot have a sync return type
    (`: RoomSchema` on an `async` body is a `tsc` error). Both methods above are
@@ -150,20 +153,14 @@ throw new PalError(418, "teapot", "custom");  // → custom status/code
 
 See [errors.md](./errors.md) for the full set + the wire envelope shape.
 
-## Middleware
+## There is no middleware
 
-A middleware wraps a request. Define one in `middleware/<name>.ts`:
+`defineMiddleware(async (ctx, next) => { … })` is still exported and still
+type-checks, but **nothing mounts a `middleware/` directory and the engine has no
+middleware pipeline** — a handler written against it deploys, never runs, and
+nothing reports it. There is no `ctx` object anywhere on a path that executes, so
+treat the export as a leftover rather than a seam.
 
-```ts
-// middleware/logger.ts
-import { defineMiddleware } from "@palbase/backend";
-
-export default defineMiddleware(async (ctx, next) => {
-  ctx.log.info(`start ${ctx.requestId}`);
-  await next();
-  ctx.log.info(`done ${ctx.requestId}`);
-});
-```
-
-The middleware handler receives `(ctx, next)` — call `await next()` to run the
-rest of the chain (other middleware, then the endpoint method).
+Cross-cutting work goes in a service the controllers call, and the route concerns
+that used to live in a wrapper are route options instead: `auth` on `@Controller`
+or the method decorator, and `rateLimit: { max, window }` per route.