@zerotal/arch 1.7.0

package/docs/contributing.md

@@ -0,0 +1,164 @@
+---
+title: Contribution Guide
+description: Get the Zerotal monorepo running locally and pass the checks your change needs to land.
+---
+
+# Contribution Guide
+
+Zerotal is a Bun-native monorepo of composable packages. This guide covers getting the
+repo running locally, the project layout, and the checks your change needs to pass.
+
+> **Warning** — Bun ≥ 1.1 is required. Node.js is not supported; Zerotal uses `Bun.sql`, `Bun.CryptoHasher`, `Bun.build`, and other Bun-native APIs throughout.
+
+## Getting set up
+
+```bash
+# in your project root
+git clone <repo-url> zerotal
+cd zerotal
+bun install            # installs all workspaces
+```
+
+The repo is a Bun workspace (`packages/*` and `apps/*`), so a single `bun install` at
+the root wires every package together via `workspace:*` links.
+
+## Repository layout
+
+```text
+# repo root
+packages/        # the framework — one directory per @zerotal/* package
+  core/          #   IoC container, Application, router, HTTP pipeline, events, config
+  orm/           #   models, migrations, query builder, relationships
+  auth/  cache/  queue/  …  # feature packages
+  testing/       #   factories, fakes, test app harness
+  create-zerotal/ #   the `bun create zerotal` scaffolder
+apps/            # example apps used for end-to-end testing and the docs site
+  docs/          #   this documentation site
+docs/            # the markdown documentation (what you're reading)
+```
+
+Each package owns its own `src/`, tests (`*.test.ts`), and `package.json`.
+
+## The `@zerotal/core` public surface
+
+`@zerotal/core` is deliberately split so importing the kernel doesn't drag in heavy or
+rarely-used subsystems. The root barrel (`@zerotal/core`) exports **only the lean kernel** —
+`Application`, the container, `RequestContext`, `HttpContext`/`Pipeline`, providers, errors,
+events, the router, middleware, facades, `Command`, and the common helpers. Everything else
+lives behind an explicit subpath:
+
+```text
+@zerotal/core            # kernel: Application, Router, HttpContext, Container, errors, events, middleware, helpers
+@zerotal/core/carbon     # Carbon + intervals (pulls the Temporal polyfill — kept out of the kernel)
+@zerotal/core/http       # outbound Http client, URL building/signing, uploads, API Resource, negotiation
+@zerotal/core/view       # server-side JSX runtime + authoring helpers (SafeHtml, definePage, …)
+@zerotal/core/env        # typed environment schema (EnvSchema, t, Def)
+@zerotal/core/config     # ConfigManager/Loader + app config shapes (AppConfig, AppAssetsConfig, …)
+@zerotal/core/security   # Crypt + Hash
+@zerotal/core/dev        # dev-only build/reload tooling (owns Bun.build — inactive outside the dev worker)
+@zerotal/core/assets     # asset() URL helper + versioning
+@zerotal/core/health     # health checks
+@zerotal/core/metrics    # HTTP request metrics
+```
+
+Rule of thumb when adding a public export to core:
+
+- **Kernel** (hot, cheap, needed almost everywhere) → add it to `src/index.ts`, and add the name
+  to the frozen list in `src/index.barrel.test.ts` (a deliberate, reviewed decision).
+- **Belongs to a subsystem** (a specific concern, or it pulls a heavy dependency) → export it from
+  that subpath's `src/<group>/index.ts` and register the subpath in `package.json` `exports`. Do
+  **not** add it to the root barrel.
+
+The `core barrel surface` guard test (`src/index.barrel.test.ts`) fails if the root barrel grows or
+shrinks unexpectedly — that's the signal to pick one of the two paths above on purpose, so the
+barrel never drifts back into a god-module.
+
+## Everyday commands
+
+Run from the repo root — they fan out across every workspace via `bun --filter`:
+
+```bash
+# in your project root
+bun test            # run all package test suites
+bun run typecheck   # type-check every package
+bun run lint        # eslint
+bun run format      # prettier --write
+bun run build       # build every package
+```
+
+To work on a single package, run its script directly inside it:
+
+```bash
+# in your project root
+cd packages/orm
+bun test            # just the ORM suite
+bun test src/db/QueryBuilder.test.ts   # a single file
+```
+
+> **Note** — tests run on Bun's built-in runner. Most database tests use SQLite (`:memory:` or a temp file), so they need no external services.
+
+## Making a change
+
+1. **Branch** off the default branch.
+2. **Write the code and tests.** New behavior needs test coverage; bug fixes should
+   add a regression test. Match the style of the surrounding code.
+3. **Keep the public API typed.** Exported functions and classes should have accurate
+   types — the `typecheck` task gates this.
+4. **Run the checks** before pushing:
+
+   ```bash
+   # in your project root
+   bun run typecheck && bun test && bun run lint
+   ```
+
+5. **Update the docs.** If you change or add public API, update the relevant page
+   under `docs/` (and the nav in `apps/docs/app/routes/_layout.ts` if you add a page).
+
+## Documentation changes
+
+The docs are markdown files in `docs/`, served by the docs app in `apps/docs`. A page's
+URL is its path: `docs/query-builder.md` → `/docs/query-builder`, and
+`docs/orm/casts.md` → `/docs/orm/casts` (a directory's `index.md` serves the bare
+slug). To add a page, create the markdown file and add an entry to the `NAV` array in
+`apps/docs/app/routes/_layout.ts`.
+
+When documenting an API, verify it against the package source rather than memory —
+accuracy is the priority.
+
+### One page, one subject
+
+A page documents its own subject and nothing else. When a feature belongs to another
+area, link to the page that owns it instead of re-explaining it here — a second copy
+drifts out of date, and the reader who needs the detail is better served by the page
+that keeps it complete.
+
+- **Own it or link it.** Route-model binding is explained in [Routing](/docs/routing);
+  every other page states that the model arrives resolved and links there. `HttpContext`
+  members belong to [Requests & Context](/docs/context), not to whichever guide happens
+  to show a handler.
+- **Show the default, not the override.** If a param binds implicitly, the example
+  registers a plain route. Configuration that only exists for the non-default case
+  belongs on the page that owns the mechanism.
+- **Prefer a pointer to a paraphrase.** One sentence naming the behaviour plus a link
+  beats a condensed re-teaching that will disagree with the source page after the next
+  change.
+- **Package-authoring material goes to
+  [Package Development](/docs/package-development)** — macros, driver contracts, and
+  provider internals are not app-builder documentation.
+
+The same rule governs a page's own length: a section that has grown into a second
+subject is a sign it wants to be its own page, or to move to the one that owns it.
+
+## Pull requests
+
+- Keep PRs focused — one logical change per PR.
+- Describe what changed and why; link any related issue.
+- Make sure CI is green (`typecheck`, `test`, `lint`).
+- Note any breaking change clearly so it can be captured in the
+  [Release Notes](/docs/changelog).
+
+## Next steps
+
+- [Package Development](/docs/package-development) — building a `@zerotal/*`-style package.
+- [Testing](/docs/testing) — the test harness, factories, and fakes.
+- [Upgrade Guide](/docs/upgrade) — how releases are versioned.

package/docs/controllers.md

@@ -0,0 +1,354 @@
+---
+title: Controllers
+description: Group related request handlers into classes that map actions to routes and resolve dependencies through the container.
+---
+
+# Controllers
+
+A controller groups related request handlers into a single class, where each
+public method is an action that a route can target. Controllers are resolved
+through the IoC container, so a class declaring `@inject(...)` gets its
+dependencies wired up automatically.
+
+## Basic controller
+
+A controller is a plain class. Each action receives the request `HttpContext`
+directly, reads input from it, and sets the response by calling a helper on it —
+actions return `void`, not a value.
+
+```typescript
+// app/controllers/PostController.ts
+import type { HttpContext } from "zerotal";
+import { Post } from "../models/Post.ts";
+
+export class PostController {
+  async index(ctx: HttpContext): Promise<void> {
+    const posts = await Post.all();
+    ctx.json({ posts });
+  }
+
+  async show(ctx: HttpContext): Promise<void> {
+    const post = await Post.findOrFail(Number(ctx.params.id));
+    ctx.json(post);
+  }
+
+  async store(ctx: HttpContext): Promise<void> {
+    const { title, body } = await ctx.body<{ title: string; body: string }>();
+    const post = await Post.create({ title, body });
+    ctx.json(post, 201);
+  }
+
+  async destroy(ctx: HttpContext): Promise<void> {
+    const post = await Post.findOrFail(Number(ctx.params.id));
+    await post.delete();
+    ctx.response = new Response(null, { status: 204 });
+  }
+}
+```
+
+Map routes to actions by passing the controller class and the action name:
+
+```typescript
+// routes/index.ts
+import { Router } from "zerotal";
+import { PostController } from "../app/controllers/PostController.ts";
+import { AuthMiddleware } from "@zerotal/auth";
+
+Router.get("/posts", PostController, "index");
+Router.get("/posts/:id", PostController, "show");
+Router.post("/posts", PostController, "store", [AuthMiddleware]);
+Router.delete("/posts/:id", PostController, "destroy", [AuthMiddleware]);
+```
+
+> **Note** — The fourth argument is the per-route middleware array:
+> `Router.get(path, Controller, action, middleware?)`. See
+> [Routing](/docs/routing) for groups, prefixes, and named routes.
+
+## Dependency injection
+
+A controller is constructed by `container.make()`, which auto-wires its
+dependencies. Decorate the **class** with `@inject(...)`, listing the tokens in
+constructor order — the container resolves each token and passes it to the
+constructor:
+
+```typescript
+// app/controllers/PostController.ts
+import type { HttpContext } from "zerotal";
+import { inject } from "zerotal";
+import { CacheManager } from "@zerotal/cache";
+
+@inject(CacheManager)
+export class PostController {
+  constructor(private cache: CacheManager) {}
+
+  async index(ctx: HttpContext): Promise<void> {
+    const posts = await this.cache.remember("posts.all", 60, () => Post.all());
+    ctx.json({ posts });
+  }
+}
+```
+
+> **Warning** — `@inject` is a **class** decorator and only supports constructor
+> injection. There is no parameter-level or property-level `@inject` — the tokens
+> are listed on the class and matched to constructor parameters by position.
+
+### Which should I use?
+
+- **Facades** — reach for these first for one-off lookups. No constructor wiring,
+  resolved from request-scoped storage on demand.
+- **`@inject(...)` on the class** — when the controller depends on a service for
+  most of its actions and you want it injected once at construction.
+
+### Resolving via facades
+
+Facades are the lightest-weight option — no constructor wiring needed. They read
+the current request from `AsyncLocalStorage`, so they work anywhere in the async
+tree:
+
+```typescript
+// app/controllers/DashboardController.ts
+import type { HttpContext } from "zerotal";
+import { Cache } from "@zerotal/cache";
+import { Auth } from "@zerotal/auth";
+
+export class DashboardController {
+  async index(ctx: HttpContext): Promise<void> {
+    const user = Auth.user(); // resolved from AsyncLocalStorage
+    const stats = await Cache.get("stats");
+    ctx.json({ user, stats });
+  }
+}
+```
+
+## Model binding
+
+A route parameter whose name matches an auto-registered model is bound without any
+declaration — the resolved instance arrives on `ctx.params` under the param's name,
+or you can read it explicitly with `ctx.model()`. `.bind()` and the model's own
+`resolveRouteBinding` are for overriding that default:
+
+```typescript
+// routes/index.ts — :post already resolves through Post
+Router.get("/posts/:post", PostController, "show");
+```
+
+```typescript
+// app/controllers/PostController.ts — via ctx.params:
+async show(ctx: HttpContext<{ post: Post }>): Promise<void> {
+  ctx.json(ctx.params.post);
+}
+
+// app/controllers/PostController.ts — or via ctx.model():
+async show(ctx: HttpContext): Promise<void> {
+  const post = ctx.model<Post>("post");
+  ctx.json(post);
+}
+```
+
+> **Note** — If the bound record is not found, the resolver throws a 404
+> automatically — no guard needed. `ctx.model()` throws if no binding was
+> registered for that param name.
+
+## FormRequest validation
+
+Delegate validation to a `FormRequest` class for cleaner controllers. The class
+comes from `@zerotal/validator`:
+
+```typescript
+// app/requests/posts/StorePostRequest.ts
+import { FormRequest, RuleBuilder } from "@zerotal/validator";
+
+export class StorePostRequest extends FormRequest {
+  // Do NOT annotate the return type — validate() infers the typed shape from it.
+  // (Pipe-strings like "required|string" are Flow's @validate syntax; FormRequest
+  // uses the RuleBuilder.)
+  rules(r: RuleBuilder) {
+    return {
+      title: r.string().min(3).max(255),
+      body: r.string().min(10),
+      tags: r.array(r.string()).optional(),
+    };
+  }
+}
+```
+
+`StorePostRequest.validate()` parses the request body, runs the rules, and
+returns the validated data fully typed from your `rules()` return — it throws a
+validation error on failure:
+
+```typescript
+// app/controllers/PostController.ts
+import { StorePostRequest } from "../requests/posts/StorePostRequest.ts";
+
+async store(ctx: HttpContext): Promise<void> {
+  const data = await StorePostRequest.validate(); // throws on validation failure
+  const post = await Post.create(data);
+  ctx.json(post, 201);
+}
+```
+
+> **Tip** — Do not annotate the `rules()` return type explicitly. The static
+> `validate()` infers the result shape from `ReturnType<rules>`, so an explicit
+> annotation would widen the result back to `Record<string, unknown>`.
+
+See the [Validator](/docs/validator) guide for the full rules reference.
+
+## Resource controllers
+
+A resource controller implements the standard seven RESTful actions:
+
+```typescript
+// app/controllers/ArticleController.ts
+import type { HttpContext } from "zerotal";
+
+export class ArticleController {
+  async index(ctx: HttpContext): Promise<void> {
+    /* GET /articles          */
+  }
+  async create(ctx: HttpContext): Promise<void> {
+    /* GET /articles/create   */
+  }
+  async store(ctx: HttpContext): Promise<void> {
+    /* POST /articles         */
+  }
+  async show(ctx: HttpContext): Promise<void> {
+    /* GET /articles/:id      */
+  }
+  async edit(ctx: HttpContext): Promise<void> {
+    /* GET /articles/:id/edit */
+  }
+  async update(ctx: HttpContext): Promise<void> {
+    /* PUT /articles/:id      */
+  }
+  async destroy(ctx: HttpContext): Promise<void> {
+    /* DELETE /articles/:id   */
+  }
+}
+```
+
+Register all seven with a single call, or narrow them with `.only()` / `.except()`:
+
+```typescript
+// routes/index.ts
+Router.resource("articles", ArticleController);
+Router.resource("articles", ArticleController).only(["index", "show"]);
+Router.resource("articles", ArticleController).except(["create", "edit"]);
+```
+
+> **Tip** — Generate either shape with `bun zt make:controller` — add
+> `--resource` for the full CRUD stubs.
+
+## Returning responses
+
+Controllers set `ctx.response` via helper methods — they do not return a value
+(the return type is `Promise<void>`):
+
+```typescript
+// in a controller action
+ctx.json(data); // 200 JSON
+ctx.json(data, 201); // 201 JSON
+ctx.view(MyComponent, props); // full HTML document from a view component
+ctx.html("<p>fragment</p>"); // raw HTML, no DOCTYPE
+ctx.redirect("/dashboard", 303); // redirect (default 302)
+ctx.back(); // redirect to a same-origin Referer, else "/"
+```
+
+See the [Responses](/docs/responses) guide for the full API.
+
+## Single-action controllers
+
+For an action that doesn't need grouping, give the controller a single method
+and name it when you register the route — a file route function works equally
+well:
+
+```typescript
+// app/controllers/HealthCheckController.ts
+import type { HttpContext } from "zerotal";
+import { Router } from "zerotal";
+
+export class HealthCheckController {
+  async handle(ctx: HttpContext): Promise<void> {
+    ctx.json({ status: "ok", uptime: Math.floor(process.uptime()) });
+  }
+}
+
+Router.get("/health", HealthCheckController, "handle");
+```
+
+## Accessing the authenticated user
+
+With `@zerotal/auth` installed, the authenticated user is available at
+`ctx.user` after `AuthMiddleware` runs. The `Auth` facade exposes the same data
+from anywhere in the async tree — handy inside services called by the controller:
+
+```typescript
+// in a controller action
+import { Auth } from "@zerotal/auth";
+
+async store(ctx: HttpContext): Promise<void> {
+  // Via ctx (optional — undefined for guests):
+  const userId = ctx.user?.id;
+
+  // Via the facade (throws ForbiddenError when not authenticated):
+  const user = Auth.user();
+  const id = Auth.id(); // number
+}
+```
+
+> **Note** — `ctx.user` and the `Auth` facade are contributed by
+> `@zerotal/auth`, not core. See [Authentication](/docs/authentication).
+
+## After-response work
+
+Register a callback to run after the response has been sent — useful for
+expensive side effects that shouldn't block the client. `afterResponse` returns
+`this`, so it chains:
+
+```typescript
+// in a controller action
+async store(ctx: HttpContext): Promise<void> {
+  const post = await Post.create(data);
+  ctx.json(post, 201);
+
+  ctx.afterResponse(async () => {
+    await NotifyFollowersJob.dispatch({ postId: post.id });
+    await Cache.forget("posts.all");
+  });
+}
+```
+
+> **Note** — An error thrown inside an `afterResponse` callback is logged and
+> swallowed; it never crashes the server or affects the already-sent response.
+
+## References
+
+Controller actions interact with the request through the `ctx` object
+(`HttpContext`). The members used most often from a controller:
+
+| Member                                 | Signature                   | Description                                                                                 |
+| -------------------------------------- | --------------------------- | ------------------------------------------------------------------------------------------- |
+| `ctx.params`                           | `Record<string, string>`    | Route params, plus resolved model bindings under their name (e.g. `/posts/:id` → `{ id }`). |
+| `ctx.body<T>()`                        | `() => Promise<T>`          | Parse and cache the JSON / form request body.                                               |
+| `ctx.input<T>(key, fallback?)`         | `(key, fallback?) => T`     | Read from route params → cached body → query, in order.                                     |
+| `ctx.model<T>(name)`                   | `(name) => T`               | The route-model-bound instance for a param; throws if unbound.                              |
+| `ctx.json(data, status?)`              | `(data, status?) => void`   | Set a JSON response (default 200).                                                          |
+| `ctx.view(component, props?, status?)` | overloaded                  | Render a view component to a full HTML document.                                            |
+| `ctx.html(markup, status?)`            | `(markup, status?) => void` | Set a raw HTML response (no DOCTYPE).                                                       |
+| `ctx.redirect(url, status?)`           | `(url, status?) => void`    | Set a redirect response (default 302).                                                      |
+| `ctx.back(status?)`                    | `(status?) => void`         | Redirect to a same-origin `Referer`, else `/`.                                              |
+| `ctx.afterResponse(cb)`                | `(cb) => this`              | Run work after the response is sent.                                                        |
+
+Container wiring for controllers:
+
+| Member               | Signature       | Description                                                                  |
+| -------------------- | --------------- | ---------------------------------------------------------------------------- |
+| `@inject(...tokens)` | class decorator | Declare constructor dependencies in order; auto-wired by `container.make()`. |
+
+## Next steps
+
+- [Routing](/docs/routing) — map URLs to controller actions and bind models.
+- [Middleware](/docs/middleware) — protect and transform requests before they reach actions.
+- [Validator](/docs/validator) — the rules reference for `FormRequest` validation.
+- [Responses](/docs/responses) — the full response helper API.
+- [Container](/docs/container) — how `@inject` and `make()` resolve your services.
+- [HttpContext](/docs/context) — the full request/response object reference.