@palbase/backend 3.0.0 → 5.0.0

package/docs/getting-started.md

@@ -3,7 +3,7 @@
 There is no CLI init command. A starter project is created for you when your
 Palbase project is provisioned. You then edit the files locally and deploy them.
 
-## package.json
+## package.json + tsconfig.json
 
 Your project depends on the SDK and uses the Palbase CLI for the dev loop:
 
@@ -20,46 +20,84 @@ Your project depends on the SDK and uses the Palbase CLI for the dev loop:
 }
 ```
 
+The controllers use **decorators**, so the `tsconfig.json` must set
+`experimentalDecorators: true` (the scaffold ships it):
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "strict": true,
+    "experimentalDecorators": true,
+    "noEmit": true
+  },
+  "include": ["controllers/**/*.ts", "models/**/*.ts", "services/**/*.ts", "db/**/*.ts", "*.d.ts"]
+}
+```
+
 ## Local dev loop
 
 - `palbase serve` — run your backend locally with hot reload. It runs your
-  `controllers/` locally but proxies `Database`/`ctx.*` to the **deployed**
-  branch, so the branch must already be deployed (serve tells you to push first
-  if it isn't). See [migrations.md](./migrations.md) for the schema/migration
-  side of this.
+  `controllers/` locally but proxies `Database` and the service singletons to
+  the **deployed** branch, so the branch must already be deployed (serve tells
+  you to push first if it isn't). On startup it also runs `gen-types`. See
+  [migrations.md](./migrations.md) for the schema/migration side of this.
+- `palbase gen-types` — regenerate `palbase-env.d.ts` from `db/schema.ts` so
+  `Database.tables.*` is typed (no import, no generic). Run it standalone after
+  editing the schema, or rely on `palbase serve` running it for you.
 - **Deploy is GitHub-native** — there is no `palbase push`. Commit and
   `git push` to your project's repo; the push triggers a deploy of the backend
   runtime. Push a **branch** to deploy that branch instead of `main`.
 
 ## Your first endpoint
 
-A handler is one endpoint unit; a controller maps method+path to it. Create
-`handlers/hello.ts`:
+An endpoint is a method on a class controller. Declare the schemas in `models/`:
 
 ```ts
-import { defineHandler, z } from "@palbase/backend";
-
-export default defineHandler({
-  input: z.object({ name: z.string().optional() }),
-  output: z.object({ message: z.string(), user: z.string().nullable() }),
-  handler: async (req) => ({
-    message: `hello, ${req.input.name ?? "world"}!`,
-    user: req.user?.id ?? null,
-  }),
-});
+// models/hello/greet.ts
+import { z } from "@palbase/backend";
+
+export const GreetQuery = z.object({ name: z.string().optional() });
+export type GreetQuery = z.infer<typeof GreetQuery>;
+
+export const HelloResponse = z.object({ message: z.string(), user: z.string().nullable() });
+export type HelloResponse = z.infer<typeof HelloResponse>;
 ```
 
-Then mount it in `controllers/hello.controller.ts`:
+Then write the controller in `controllers/hello.controller.ts`:
 
 ```ts
-import { defineController, route } from "@palbase/backend";
-import hello from "../handlers/hello.js";
+import { Controller, Get, Query, OptionalUser } from "@palbase/backend";
+import type { UserT } from "@palbase/backend";
+import { GreetQuery } from "../models/hello/greet.js";
+import type { HelloResponse } from "../models/hello/greet.js";  // the return TYPE names the 200 schema
 
-export default defineController("/hello", {
-  hello: route.get("/", hello),
-});
+@Controller("/hello", { auth: false })
+export default class HelloController {
+  @Get("")
+  greet(@Query(GreetQuery) q: GreetQuery, @OptionalUser() user: UserT | null): HelloResponse {
+    return { message: `hello, ${q.name ?? "world"}!`, user: user?.id ?? null };
+  }
+}
 ```
 
-This is served at `GET /hello`. The Zod `input` schema validates the request and
-flows into `req.input`; the `output` schema validates your return value. See
-[routing.md](./routing.md) for the handler + controller model.
+This is served at `GET /hello`. The `@Query` schema validates the query string;
+the method's RETURN TYPE (`: HelloResponse`) names the response schema — codegen
++ the runtime read it to validate and describe the 200 response. There is no
+`@Returns` decorator; a body route with no named return type is a build error.
+
+Two things every controller file MUST have:
+
+- **A default export of the `@Controller` class.** Above it is `export default class
+  HelloController` (inline); the equivalent trailing form is `export class
+  HelloController {…}` then `export default HelloController;`. Without a default
+  export the deploy fails ("not a @Controller").
+- **`async` + `Promise<T>` once the method awaits a service.** `greet` above is
+  synchronous (pure), so it returns `HelloResponse` directly. The moment a method
+  calls a service that awaits `Database`, make it `async` and return
+  `Promise<HelloResponse>`.
+
+See [routing.md](./routing.md) and [endpoints.md](./endpoints.md) for the full
+class-controller model.