@zerotal/arch 1.7.3 → 1.7.5

package/docs/flow/routing.md

@@ -11,7 +11,7 @@ Flow pages are plain TypeScript classes. Register them as routes with `Router.fl
 
 `Router.flow(path, PageClass, middleware?)` registers a `Component` subclass as a `GET` route. The third argument accepts an array of middleware classes that run on the **initial GET and on every WebSocket update** — this is Flow's persistent middleware model (no separate "attach middleware per WS frame" step required).
 
-```typescript
+```typescript fragment
 // routes/web.ts
 import { Router } from "zerotal";
 import { DashboardPage } from "#app/flow/DashboardPage.tsx";
@@ -38,7 +38,7 @@ Router.flow("/admin", AdminPage, [RequireAuthMiddleware, RequireAdminMiddleware]
 
 Chain `.name()` to give a route a name for reverse URL generation:
 
-```typescript
+```typescript fragment
 Router.flow("/dashboard", DashboardPage, [RequireAuthMiddleware]).name("dashboard");
 Router.flow("/posts", PostsPage).name("posts.index");
 Router.flow("/posts/:slug", PostDetailPage).name("posts.show");
@@ -48,7 +48,7 @@ Router.flow("/posts/:slug", PostDetailPage).name("posts.show");
 
 Use `Router.group()` to share a prefix and/or middleware across several Flow routes:
 
-```typescript
+```typescript fragment
 Router.group({ prefix: "/app", middleware: [RequireAuthMiddleware] }, () => {
   Router.flow("/dashboard", DashboardPage); // /app/dashboard
   Router.flow("/profile", ProfilePage); // /app/profile
@@ -71,7 +71,7 @@ Middleware declared on the group is persistent: it re-runs on every WebSocket up
 
 When you call `.fileBasedRouting()` on `Application`, the framework scans the given directory and auto-registers any file that exports a `Component` subclass. No import required in a route file.
 
-```typescript
+```typescript fragment
 // bootstrap/app.ts
 import { Application, basePath } from "zerotal";
 import providers from "./providers.ts";
@@ -114,7 +114,7 @@ app/flow/
 
 Export a `middleware` array from a file-route to attach middleware to that specific page:
 
-```typescript
+```typescript fragment
 // app/flow/admin/DashboardPage.tsx
 import { RequireAuthMiddleware } from "#app/middleware/RequireAuth.ts";
 import { RequireAdminMiddleware } from "#app/middleware/RequireAdmin.ts";
@@ -128,7 +128,7 @@ export class DashboardPage extends Component {
 
 Or use a `_middleware.ts` file in a directory to apply middleware to every file in that directory:
 
-```typescript
+```typescript fragment
 // app/flow/admin/_middleware.ts
 import { RequireAuthMiddleware } from "#app/middleware/RequireAuth.ts";
 import { RequireAdminMiddleware } from "#app/middleware/RequireAdmin.ts";
@@ -142,7 +142,7 @@ export const middleware = [RequireAuthMiddleware, RequireAdminMiddleware];
 
 For query string parameters (`/posts?page=2&search=typescript`), use the `@url` decorator. The field is filled from the URL on the first render, and stays in sync as the value changes:
 
-```typescript
+```typescript fragment
 @url page:   number = 1;
 @url search: string = "";
 @url status: string = "all";
@@ -158,7 +158,7 @@ For query string parameters (`/posts?page=2&search=typescript`), use the `@url`
 
 Where `@url` syncs a reactive prop **to** the URL, `this.currentUrl()` and `this.navigateCurrent()` go the other way — they **build** a URL from the one you're on with some query params changed, for filter links and instant filtering. Both are client-only helpers (the compiler rewrites them to the client runtime), so they update without a server round-trip to start.
 
-```typescript
+```typescript fragment
 // Build a URL from the current one — returns a string, does NOT navigate.
 this.currentUrl({ query: { page: 3 } });
 //  /posts?search=ts&page=2   →   /posts?search=ts&page=3
@@ -175,7 +175,7 @@ The merge rules:
 
 **Use `currentUrl()` in a binding** — an attribute value or a text child. The compiler turns it into a reactive client binding, so the link always reflects the current URL:
 
-```tsx
+```tsx fragment
 // Pagination links that preserve the active search / filters
 <a href={this.currentUrl({ query: { page: this.page - 1 } })} flow:navigate>Previous</a>
 <a href={this.currentUrl({ query: { page: this.page + 1 } })} flow:navigate>Next</a>
@@ -183,7 +183,7 @@ The merge rules:
 
 **Use `navigateCurrent()` in a handler** — perfect for instant filters that navigate as the user picks:
 
-```tsx
+```tsx fragment
 <select onChange={(e) => this.navigateCurrent({ query: { status: e.target.value || null } })}>
   <option value="">All</option>
   <option value="active">Active</option>
@@ -199,7 +199,7 @@ down is the case where that's wrong — the user is looking at the control they
 just changed, and the results move out from under them. Pass `preserveScroll` to
 leave the viewport where it is:
 
-```tsx
+```tsx fragment
 <select
   onChange={(e) =>
     this.navigateCurrent({ query: { status: e.target.value || null }, preserveScroll: true })
@@ -217,12 +217,12 @@ Pagination is the opposite case: page 2 should start at the top, so leave it off
 
 Name a field after the segment and it arrives filled. `/posts/:post` names the `Post` model, so the page receives the loaded record — no query, and no lookup code:
 
-```typescript
+```typescript fragment
 // routes/web.ts — nothing to declare; :post is a Post
 Router.flow("/posts/:post", PostDetailPage);
 ```
 
-```typescript
+```typescript fragment
 export class PostDetailPage extends Component {
   @locked post!: Post; // :post — the record, already loaded
 
@@ -252,7 +252,7 @@ Only `@locked` and `@expose` fields are filled, and only from segments the route
 
 When the field's name differs from the segment, `@param` says where it comes from — either the segment's name, or the model:
 
-```typescript
+```typescript fragment
 export class PostDetailPage extends Component {
   @locked @param(Post) article!: Post; // whichever segment resolved to a Post
   @locked @param("post") alsoArticle!: Post; // or name the segment
@@ -266,7 +266,7 @@ Passing the model is the sturdier of the two — the field says what it wants an
 
 `onBoot()` and `onMount()` also receive the request itself — the same `HttpContext` a controller action gets — for anything the URL doesn't carry. It types `ctx.params` only, so the signed-in user is `{ user }`, not `params.user`:
 
-```typescript
+```typescript fragment
 override async onMount({ user }: HttpContext) {
   this.canEdit = user?.id === this.post.authorId;
 }
@@ -278,14 +278,14 @@ The argument is optional, because a component can also be created outside a requ
 
 A URL segment fills the **page**. `/posts/:post` gives the page its `post`; the components inside it get nothing from the URL, even if one of their fields happens to share the segment's name. If a child needs the post, the page hands it over:
 
-```tsx
+```tsx fragment
 // in the page's render()
 <PostCard post={this.post} compact />
 ```
 
 A prop lands on the field of the same name, before any hook runs:
 
-```typescript
+```typescript fragment
 export class PostCard extends Component {
   @locked post!: Post; // required — no default
   @locked compact = false; // optional — false when the page omits it
@@ -309,7 +309,7 @@ Mark props `@locked` (or `@expose`) so their values survive round-trips in the c
 
 Coerce string params to numbers with `ctx.integer()`:
 
-```typescript
+```typescript fragment
 override async onMount(ctx: HttpContext) {
   this.userId = ctx.integer("id") ?? 0;
 }
@@ -343,7 +343,7 @@ ctx.ip(); // string | null — client IP
 
 `@session` binds a field to a session key, so its value survives a browser refresh. Reads and writes go straight to the session; nothing is kept in the component's snapshot, so the browser never sees the value:
 
-```typescript
+```typescript fragment
 @session preferredTheme: string = "light";  // the session's `preferredTheme`
 @session lastVisitedTab: string = "overview";
 
@@ -359,7 +359,7 @@ Requires `SessionMiddleware` on the route. See [Decorators](/docs/flow/decorator
 
 For values that aren't a field on this component — a cart, a flash bag, anything you set elsewhere — use the [`Session`](/docs/session) facade. It resolves the in-flight request's session, so it works in any hook or action:
 
-```typescript
+```typescript fragment
 import { Session } from "@zerotal/session";
 
 override async onMount() {
@@ -381,7 +381,7 @@ Reach for `@session` when the value is a field on the component; reach for the f
 
 When `AuthMiddleware` (or your `RequireAuthMiddleware`) runs, it populates `ctx.user`. Access it via `request()`:
 
-```typescript
+```typescript fragment
 import { request } from "zerotal";
 
 export class ProfilePage extends Component {
@@ -410,7 +410,7 @@ Because `onBoot()` runs on every request (initial GET and WebSocket), the auth c
 
 Declare static properties on the page class to control the document `<title>`, inject `<head>` content, and attach a layout:
 
-```typescript
+```typescript fragment
 export class DashboardPage extends Component {
   // Sets <title>Dashboard</title> on the initial render
   static title = "Dashboard";
@@ -430,7 +430,7 @@ export class DashboardPage extends Component {
 
 `static title` takes a string, or a function of the component:
 
-```typescript
+```typescript fragment
 static title = "Posts";
 static title = (c: PostPage) => `${c.post?.title ?? "Loading"} — My App`;
 ```
@@ -438,7 +438,7 @@ static title = (c: PostPage) => `${c.post?.title ?? "Loading"} — My App`;
 The function form is resolved on the server for every render and every patch, so a title
 that depends on state follows it without an action doing anything:
 
-```typescript
+```typescript fragment
 @expose async loadPost(slug: string): Promise<void> {
   this.post = await Post.where("slug", slug).firstOrFail();
   // the title updates with it — nothing else to call
@@ -449,7 +449,7 @@ Only the resolved string is sent to the browser; the function stays on the serve
 
 For per-render `<head>` content (meta tags, OG tags), use `<Head>` inside `render()`:
 
-```tsx
+```tsx fragment
 import { Head } from "@zerotal/flow";
 
 override async render() {
@@ -470,7 +470,7 @@ override async render() {
 
 A fully wired page with a dynamic route param, auth, session, query string, and layout:
 
-```typescript
+```typescript fragment
 import { Component, expose, locked, url, session } from "@zerotal/flow";
 import { request } from "zerotal";
 import { RequireAuthMiddleware } from "#app/middleware/RequireAuth.ts";

package/docs/flow/testing.md

@@ -13,7 +13,7 @@ Import it from `@zerotal/flow/testing`.
 
 `FlowTest.mount()` drives the **initial GET** cycle: `onBoot → onMount → onRendering → render → onRendered → onDehydrate`. It returns a test handle you can use for assertions and further interactions:
 
-```typescript
+```typescript fragment
 import { FlowTest } from "@zerotal/flow/testing";
 import { CounterPage } from "#app/flow/CounterPage.tsx";
 
@@ -29,7 +29,7 @@ t.assertDontSee("Count: 1");
 
 Pass initial props to seed state before `onMount()` runs. Props are applied to the component instance before the lifecycle starts:
 
-```typescript
+```typescript fragment
 const t = await FlowTest.mount(PostsPage, { page: 2, search: "TypeScript" });
 
 expect(t.page().search).toBe("TypeScript");
@@ -43,7 +43,7 @@ This is equivalent to the component being navigated to with `?page=2&search=Type
 
 `t.call(method, ...args)` drives a **WebSocket action frame**: `onBoot → onHydrate → [onUpdating/onUpdated] → action → onUpdate → onRendering → render → onRendered → onDehydrate`.
 
-```typescript
+```typescript fragment
 await t.call("increment");
 expect(t.page().count).toBe(1);
 t.assertSee("Count: 1");
@@ -67,7 +67,7 @@ Any other error is passed to `onError()` — as in production — and then **ret
 
 When the error path is what you're testing, opt in with `tolerateErrors()`:
 
-```typescript
+```typescript fragment
 const t = (await FlowTest.mount(CheckoutPage)).tolerateErrors();
 await t.call("submit");
 
@@ -79,7 +79,7 @@ t.assertFlashed("error", "Payment failed");
 
 Three methods change a property between calls:
 
-```typescript
+```typescript fragment
 // set() — direct assignment, then re-renders; no hooks fire
 await t.set("draft", "Hello world");
 await t.set("page", 3);
@@ -98,7 +98,7 @@ await t.render(); // one render for both
 
 Use `set()` to put the component in a specific state for a test scenario. Use `update()` when you're testing that `onUpdating`/`onUpdated` hooks run correctly:
 
-```typescript
+```typescript fragment
 // Test that onUpdatedUsername normalises to lowercase
 const t = await FlowTest.mount(ProfilePage);
 await t.update("username", "ALICE");
@@ -108,7 +108,7 @@ expect(t.page().username).toBe("alice"); // hook lowercased it
 
 ## HTML assertions
 
-```typescript
+```typescript fragment
 t.assertSee("Published post"); // rendered HTML contains this string
 t.assertDontSee("Error"); // rendered HTML does NOT contain this string
 t.assertSee("<h1>Dashboard</h1>"); // can match HTML tags too
@@ -118,7 +118,7 @@ Both methods check `t.html()` — the raw rendered HTML string for this componen
 
 ## Validation assertions
 
-```typescript
+```typescript fragment
 await t.call("register"); // trigger a validation action
 
 t.assertHasErrors("email"); // field has at least one error
@@ -131,7 +131,7 @@ t.assertNoErrors(); // no validation errors at all
 
 ## Redirect assertions
 
-```typescript
+```typescript fragment
 await t.call("login");
 
 t.assertRedirectedTo("/dashboard"); // last action redirected to this URL
@@ -140,7 +140,7 @@ t.assertNotRedirected(); // last action did NOT redirect
 
 ## Flash assertions
 
-```typescript
+```typescript fragment
 await t.call("save");
 
 t.assertFlashed("success", "Saved."); // level + message substring
@@ -151,7 +151,7 @@ t.assertFlashed(); // any flash was emitted
 
 ## Event assertions
 
-```typescript
+```typescript fragment
 await t.call("createPost");
 
 t.assertDispatched("post-created"); // event was dispatched
@@ -160,7 +160,7 @@ t.assertDispatched("post-created", { id: 1 }); // event was dispatched with this
 
 ## Accessors
 
-```typescript
+```typescript fragment
 t.page(); // the Component instance — inspect properties and call methods directly
 t.html(); // the rendered HTML string from the last render
 t.errors(); // current error bag: Record<string, string[]>
@@ -170,7 +170,7 @@ t.snapshot(); // the serialised snapshot blob
 
 `t.page()` gives you the live component instance, so you can read any property:
 
-```typescript
+```typescript fragment
 const page = t.page();
 expect(page.posts.length).toBe(10);
 expect(page.user?.email).toBe("alice@example.com");
@@ -191,7 +191,7 @@ That covers most actions on any page behind a sign-in, so open the scope yoursel
 rather than an object literal cast to the type — it carries a real `Request`, which matters as soon
 as anything downstream reads a header (an audited model records the actor's IP, for one):
 
-```typescript
+```typescript fragment
 import { RequestContext, HttpContext } from "@zerotal/core";
 
 function asUser<T>(user: User | null, fn: () => Promise<T>): Promise<T> {
@@ -213,7 +213,7 @@ never makes a request to send it on.
 
 `FlowTest` does not set up or tear down a database — use your test suite's standard database helpers. With Bun, wrap tests in a transaction that rolls back after each test for full isolation:
 
-```typescript
+```typescript fragment
 // tests/flow/PostsPage.test.ts
 import { describe, test, expect, beforeEach, afterEach } from "bun:test";
 import { FlowTest } from "@zerotal/flow/testing";
@@ -250,7 +250,7 @@ describe("PostsPage", () => {
 
 A complete example covering the common scenarios for a login page:
 
-```typescript
+```typescript fragment
 // tests/flow/LoginPage.test.ts
 import { describe, test, expect } from "bun:test";
 import { FlowTest } from "@zerotal/flow/testing";
@@ -314,7 +314,7 @@ describe("LoginPage", () => {
 
 To test that a component dispatches events and that `@on` listeners respond, mount each component separately and verify the dispatch effect:
 
-```typescript
+```typescript fragment
 test("dispatches post-created when saved", async () => {
   const editor = await FlowTest.mount(PostEditorPage);
   await t.set("title", "My post");
@@ -340,7 +340,7 @@ test("post list responds to post-created event", async () => {
 
 ## Testing redirects and navigation
 
-```typescript
+```typescript fragment
 test("redirects to the created post after save", async () => {
   const t = await FlowTest.mount(NewPostPage);
   await t.set("title", "Hello");
@@ -387,7 +387,7 @@ A page can pass every `FlowTest` assertion and still do nothing when a person cl
 over the DevTools Protocol — no Puppeteer or Playwright dependency — so the click is a
 real click and the round-trip is a real round-trip.
 
-```ts
+```ts fragment
 import { describe, it, expect, beforeAll, afterAll } from "bun:test";
 import { Application, Router } from "zerotal";
 import { FlowProvider } from "@zerotal/flow";
@@ -433,7 +433,7 @@ A few things are deliberate and worth copying:
 - **Guard the suite with `FlowBrowser.available()`** so it skips where no browser is
   installed instead of failing:
 
-```ts
+```ts fragment
 const describeBrowser = FlowBrowser.available() ? describe : describe.skip;
 ```
 

package/docs/getting-started.md

@@ -12,7 +12,9 @@ provider.
 ## Requirements
 
 - **Bun** ≥ 1.3.14 — [install](https://bun.sh/docs/installation)
-- A PostgreSQL, MySQL, or SQLite database (SQLite requires nothing extra)
+- A database, unless you scaffold the **Minimal** template. Every other template
+  is configured for **SQLite**, which needs nothing installed — PostgreSQL and
+  MySQL are supported and are a `DATABASE_URL` away.
 
 ## Create a new project
 
@@ -26,11 +28,11 @@ The scaffolder prompts for a project name and a template, then generates a
 ready-to-run project and installs dependencies. The **database** prompt only
 appears for the API template:
 
-| Prompt       | Options                                                                     |
-| ------------ | --------------------------------------------------------------------------- |
-| Project name | Defaults to `my-zerotal-app`                                                |
-| Template     | **API**, **Flow**, **React**, **Vue**, or **Minimal** (see the guide below) |
-| Database     | **SQLite** (zero setup), **PostgreSQL**, or **MySQL** — API template only   |
+| Prompt       | Options                                                                      |
+| ------------ | ---------------------------------------------------------------------------- |
+| Project name | Defaults to `my-zerotal-app`                                                 |
+| Template     | **API**, **Admin**, **Flow**, **React**, **Vue**, or **Minimal** (see below) |
+| Database     | **SQLite** (zero setup), **PostgreSQL**, or **MySQL** — asked for **API**    |
 
 It writes a fresh `APP_KEY` into the generated `.env.example` for you (no manual
 generation needed). For Postgres/MySQL it reminds you to set `DATABASE_URL`
@@ -47,7 +49,7 @@ bunx create-zerotal my-app --yes            # take the defaults for anything uns
 bunx create-zerotal --help
 ```
 
-| Flag                      |                                                    |
+| Flag                      | Values / description                               |
 | ------------------------- | -------------------------------------------------- |
 | `-t`, `--template <name>` | `api`, `admin`, `flow`, `react`, `vue`, `minimal`  |
 | `--db <name>`             | `sqlite`, `postgres`, `mysql` — API template only  |
@@ -64,14 +66,17 @@ terminal: a half-built project that reports success is worse than one that stops
 ### Which template should I use?
 
 - **API** — JSON REST API with core, [ORM](/docs/orm), [auth](/docs/authentication),
-  [validation](/docs/validator), and [testing](/docs/testing/index). The default for a backend service.
+  [validation](/docs/validator), and [testing](/docs/testing). The default for a backend service.
+- **Admin** — an [admin panel](/docs/admin): resources, sign-in, dashboard widgets, and
+  seeded demo data. `bun zt db:seed` gives you an account to log in with.
 - **Flow** — server-driven reactive UI ([Flow](/docs/flow) pages, top nav, Tailwind).
 - **React** — [Inertia](/docs/inertia) + React SPA with file-based routes and Tailwind.
 - **Vue** — Inertia + Vue SPA with file-based routes and Tailwind.
 - **Minimal** — a single page with JSX views and Tailwind on the bare framework.
 
-> **Note** — Only the **API** template ships a database config and migrations.
-> The Flow, React, Vue, and Minimal templates start without a database.
+> **Note** — every template except **Minimal** ships a database config and migrations,
+> configured for SQLite. Only the **API** template _asks_ which database you want; the
+> rest start on SQLite and switch when you set `DATABASE_URL`.
 
 ## Project structure
 
@@ -162,7 +167,7 @@ generated `package.json` also gives you `bun start` (production serve) and
 
 Open `routes/index.ts` and add:
 
-```typescript
+```typescript fragment
 // routes/index.ts
 import { Router } from "zerotal";
 import { PostController } from "../app/controllers/PostController.ts";
@@ -239,7 +244,7 @@ bun zt migrate
 
 Your model is ready to use:
 
-```typescript
+```typescript fragment
 // in a controller or service
 import { Post } from "../models/Post.ts";
 
@@ -257,7 +262,7 @@ Providers are where you wire up your own bindings. Scaffold one:
 bun zt make:provider AppServiceProvider
 ```
 
-```typescript
+```typescript fragment
 // app/providers/AppServiceProvider.ts
 import { ServiceProvider } from "zerotal";
 import { PaymentGateway } from "../services/PaymentGateway.ts";

package/docs/health.md

@@ -19,7 +19,7 @@ Health checks are built into `@zerotal/core` — nothing to install and no
 provider to register. The endpoint is registered when the application starts:
 
 ```typescript
-import { Health } from "zerotal";
+import { Health } from "zerotal/health";
 ```
 
 ## Defaults
@@ -44,7 +44,11 @@ export default AppConfig({
   health: {
     enabled: true, // default: on outside production, off in production
     path: "/health", // default: '/health'
-    secret: env("HEALTH_KEY"), // required in production
+    // Spread rather than assigned, because `secret?: string` under
+    // `exactOptionalPropertyTypes` (which the templates set) will not take the
+    // `undefined` that `env()` returns when the variable is unset. The framework
+    // reads the field the same way.
+    ...(env("HEALTH_KEY") ? { secret: env("HEALTH_KEY") } : {}), // required in production
     showDetails: true, // false → bare { "status": "ok" }
   },
 });
@@ -98,7 +102,7 @@ a built-in `runtime` probe (memory, Bun version, in-flight requests). It becomes
 a **readiness** probe as you register dependency checks against the `Health`
 registry exported from `zerotal`:
 
-```typescript
+```typescript fragment
 // in a bootstrap file (e.g. bootstrap/health.ts)
 import { Health } from "zerotal/health";
 
@@ -113,7 +117,7 @@ Health.register(
 
 // Non-critical failures degrade the report without failing readiness.
 Health.register("cache", async () => {
-  await Cache.put("__health", "1", 5);
+  await Cache.set("__health", "1", 5);
   return { meta: { driver: "redis" } };
 });
 
@@ -176,7 +180,7 @@ fails, since that is the case the endpoint exists for.
 ```typescript
 // tests/health/checks.test.ts
 import { test, expect, afterEach } from "bun:test";
-import { Health } from "zerotal";
+import { Health } from "zerotal/health";
 
 afterEach(() => Health.clear());
 
@@ -189,7 +193,12 @@ test("a failing critical check brings the report down", async () => {
     { critical: true },
   );
 
-  const report = await Health.run({ name: "app", version: "1.0.0", environment: "test" });
+  const report = await Health.run({
+    name: "app",
+    version: "1.0.0",
+    environment: "test",
+    uptime: 0, // required — seconds since boot, and a test has none worth reporting
+  });
 
   expect(report.status).toBe("down");
   expect(report.checks.database?.status).toBe("down");
@@ -205,7 +214,7 @@ to do with it.
 design. A non-critical check that fails must leave the overall status up,
 otherwise a flaky cache probe takes your deployment out of the load balancer:
 
-```typescript
+```typescript fragment
 // tests/health/checks.test.ts
 test("a non-critical failure degrades without going down", async () => {
   Health.register("cache", async () => {
@@ -222,7 +231,7 @@ test("a non-critical failure degrades without going down", async () => {
 **The endpoint's access rules deserve their own test**, because a health endpoint
 that leaks internals is a reconnaissance gift:
 
-```typescript
+```typescript fragment
 // tests/http/health.test.ts
 const res = await app.get("/health");