@zerotal/arch 1.7.0

package/docs/i18n.md

@@ -0,0 +1,414 @@
+---
+title: Internationalization
+description: Resolve each visitor's locale automatically, then translate keys with interpolation, pluralization, and fallback.
+---
+
+# Internationalization
+
+Request-scoped localization: resolve each visitor's locale automatically, then
+translate keys with interpolation, pluralization, and fallback — without threading
+the locale through every function call.
+
+## Getting Started
+
+```bash
+# in your project root
+bun add @zerotal/i18n
+```
+
+## Register the provider
+
+Add `I18nProvider` to the providers array in `bootstrap/providers.ts`:
+
+```typescript
+// bootstrap/providers.ts
+import { I18nProvider } from "@zerotal/i18n";
+
+const providers = [
+  // …your other providers
+  I18nProvider,
+];
+
+export default providers;
+```
+
+Registering the provider switches on the following:
+
+- `onRegister` — binds the translation service as the lazy `i18n` singleton (a
+  `Translator` loaded from your catalogs).
+- `onBooting` — configures and registers `LocaleMiddleware` via `app.useOnce()`,
+  so every request resolves a locale and gains `ctx.locale` + `ctx.t()`.
+
+## Configuration
+
+Create `config/i18n.ts`. The `I18nConfig()` helper fills in sensible defaults, so
+you only set what differs:
+
+```typescript
+// config/i18n.ts
+import { I18nConfig } from "@zerotal/i18n";
+import { env } from "zerotal";
+
+export default I18nConfig({
+  defaultLocale: env("APP_LOCALE", "en"),
+  fallbackLocale: env("APP_FALLBACK_LOCALE", "en"),
+  supportedLocales: ["en"],
+  resolvers: ["query", "cookie", "accept-header"], // tried in order
+  queryKey: "lang", // ?lang=fr
+  cookieKey: "locale", // locale=fr cookie
+  loadPath: "resources/lang", // <locale>.json files (optional)
+});
+```
+
+| Field              | Required | Default                        | Description                                                  |
+| ------------------ | -------- | ------------------------------ | ------------------------------------------------------------ |
+| `defaultLocale`    | no       | `"en"`                         | Locale used when no resolver matches.                        |
+| `fallbackLocale`   | no       | `defaultLocale`                | Locale consulted when a key is missing in the active locale. |
+| `supportedLocales` | no       | `[defaultLocale]`              | Locales resolvers may return; others fall back to default.   |
+| `resolvers`        | no       | `query, cookie, accept-header` | Request resolvers, tried in order (see below).               |
+| `queryKey`         | no       | `"lang"`                       | Query-string key for the `query` resolver.                   |
+| `cookieKey`        | no       | `"locale"`                     | Cookie name for the `cookie` resolver.                       |
+| `loadPath`         | no       | —                              | Directory of `<locale>.json` catalogs, loaded at boot.       |
+| `catalogs`         | no       | —                              | In-memory catalogs, merged over anything from `loadPath`.    |
+
+> **Tip** — `I18nConfig()` is optional. You can instead write a plain object with
+> `satisfies I18nConfigShape` for the same type-checking — but then every field is
+> required, since the helper is what supplies the defaults above.
+
+Catalog files live under `loadPath`, one JSON file per locale:
+
+```
+resources/lang/
+├── en.json
+├── fr.json
+└── es.json
+```
+
+## Basic usage
+
+`LocaleMiddleware` resolves the locale for every request and exposes `ctx.locale`
+and `ctx.t()` on the request context:
+
+```typescript
+// in a controller
+async show(ctx: HttpContext) {
+  ctx.t("welcome.greeting", { name: "Alice" });       // active locale
+  ctx.t("welcome.greeting", { name: "Alice" }, "fr");  // explicit locale
+  return ctx.json({ locale: ctx.locale });
+}
+```
+
+Outside a controller — in a service, job, or view — use the `Lang` facade or the
+global `t()` helper. Both read the active request locale from `I18nContext`, so no
+locale needs to be passed around:
+
+```typescript
+// anywhere in the request's async tree
+import { Lang, t } from "@zerotal/i18n";
+
+Lang.translate("auth.login.title");
+t("dashboard.welcome");
+```
+
+## Keys, interpolation, pluralization
+
+Catalogs may use nested objects or flat dotted keys — both resolve:
+
+```json
+// resources/lang/en.json
+{
+  "welcome": { "greeting": "Hello, {name}!" },
+  "validation.required": "The :field field is required.",
+  "apples": "no apples | one apple | {count} apples"
+}
+```
+
+- **Interpolation** — `{name}` and `:name` are both replaced from the
+  replacements object.
+- **Pluralization** — pipe-separated segments are chosen by `count`: two segments
+  are `singular | plural` (`count === 1` → first); three or more are
+  `zero | one | many` (`0` → first, `1` → second, otherwise last).
+- **Fallback** — a key missing in the active locale is looked up in
+  `fallbackLocale`; if still missing, the key itself is returned, so gaps are
+  visible and never throw.
+
+```typescript
+t("apples", { count: 0 }); // "no apples"
+t("apples", { count: 5 }); // "5 apples"
+```
+
+## Locale resolution
+
+`resolveLocale(request, config)` tries each configured resolver in order and only
+returns a value listed in `supportedLocales` (otherwise `defaultLocale`):
+
+| Resolver        | Source                                                    |
+| --------------- | --------------------------------------------------------- |
+| `query`         | `?lang=fr` (key configurable via `queryKey`)              |
+| `cookie`        | `locale=fr` cookie (name configurable via `cookieKey`)    |
+| `accept-header` | `Accept-Language`, by quality; `fr-FR` falls back to `fr` |
+
+**Which resolvers should I list?** Order them most-explicit first:
+
+- **`query`** — useful for a one-off preview link (`?lang=fr`) or language
+  switcher, but it doesn't persist. Put it first so it can override the others.
+- **`cookie`** — the choice that _sticks_. List it when you let users pick a
+  language and persist it (see [Overriding the locale](#overriding-the-locale)).
+- **`accept-header`** — the visitor's browser preference; a sensible default when
+  no explicit choice has been made. List it last as the fallback.
+
+## Overriding the locale
+
+The locale is resolved once, when `LocaleMiddleware` runs, and is then fixed for
+the rest of the request — so `ctx.locale` and `ctx.t()` always reflect what the
+resolvers chose. There is no `setLocale()`. To change the language, do one of two
+things.
+
+**Persist a user's choice** by writing the `locale` cookie; the `cookie` resolver
+picks it up on every subsequent request:
+
+```typescript
+// in a controller — save the visitor's language choice
+async setLocale(ctx: HttpContext) {
+  const { locale } = await ctx.body<{ locale: string }>();
+
+  const headers = new Headers({ Location: ctx.header("Referer") ?? "/" });
+  headers.append(
+    "Set-Cookie",
+    `locale=${locale}; Path=/; Max-Age=${365 * 86400}; SameSite=Lax`,
+  );
+  ctx.response = new Response(null, { status: 303, headers });
+}
+```
+
+**Override within the current request** — e.g. to honour a locale stored on the
+user — by running code inside `I18nContext.run()`. The `Lang` facade and `t()`
+helper use the supplied locale for the duration of the callback:
+
+```typescript
+// in a controller
+import { I18nContext, t } from "@zerotal/i18n";
+
+async show(ctx: HttpContext) {
+  const user = ctx.user as { name?: string; locale?: string } | undefined;
+  const locale = user?.locale ?? ctx.locale;
+
+  const greeting = I18nContext.run(locale, () =>
+    t("welcome.greeting", { name: user?.name }),
+  );
+
+  return ctx.view(DashboardPage({ greeting }));
+}
+```
+
+> **Note** — `I18nContext.run()` only affects the `Lang` facade and `t()` inside
+> its callback. `ctx.t()` and `ctx.locale` were bound by the middleware and stay on
+> the request's resolved locale. For a persistent change, set the cookie above.
+
+## Catalog structure
+
+Catalogs can be flat or deeply nested — both styles resolve with the same dot-path:
+
+```json
+// resources/lang/en.json
+{
+  "auth": {
+    "login": {
+      "title": "Sign in",
+      "submit": "Sign in to your account",
+      "forgot": "Forgot your password?"
+    },
+    "logout": "Sign out"
+  },
+  "validation": {
+    "required": "The :field field is required.",
+    "email": "The :field must be a valid email address.",
+    "min": "The :field must be at least :min characters."
+  },
+  "posts": {
+    "count": "no posts | one post | :count posts",
+    "created": "Post created on :date"
+  }
+}
+```
+
+```typescript
+ctx.t("auth.login.title"); // "Sign in"
+ctx.t("auth.logout"); // "Sign out"
+ctx.t("validation.required", { field: "name" }); // "The name field is required."
+ctx.t("posts.count", { count: 0 }); // "no posts"
+ctx.t("posts.count", { count: 1 }); // "one post"
+ctx.t("posts.count", { count: 42 }); // "42 posts"
+```
+
+## Translating validation messages
+
+A common pattern is to keep your localized form-error strings under a `validation`
+namespace in each catalog, then translate them with `t()` where you build the
+error response:
+
+```json
+// resources/lang/fr.json
+{
+  "validation": {
+    "required": "Le champ :field est obligatoire.",
+    "email": "Le champ :field doit être une adresse e-mail valide.",
+    "min": "Le champ :field doit contenir au moins :min caractères.",
+    "unique": "Cette valeur est déjà prise."
+  }
+}
+```
+
+```typescript
+// in a controller — translate a validation message yourself
+t("validation.required", { field: "email" }); // active locale
+```
+
+> **Note** — The `validation` namespace is just a convention for organizing keys;
+> the i18n package translates any key you pass to `t()`. See
+> [Validator](/docs/validator) for how the validator itself reports errors.
+
+## Multiple supported locales
+
+List every locale your app ships in `supportedLocales`. The resolver only returns a
+locale from this list — unsupported values fall back to `defaultLocale`:
+
+```typescript
+// config/i18n.ts
+export default I18nConfig({
+  defaultLocale: "en",
+  fallbackLocale: "en",
+  supportedLocales: ["en", "fr", "es", "zu", "af"],
+  resolvers: ["cookie", "accept-header"],
+});
+```
+
+Add a catalog file for each:
+
+```
+resources/lang/
+  en.json
+  fr.json
+  es.json
+  zu.json   ← isiZulu
+  af.json   ← Afrikaans
+```
+
+## Using t in JSX views
+
+```tsx
+// app/views/PostCard.tsx
+import { t } from "@zerotal/i18n";
+
+export function PostCard({ post }: { post: Post }) {
+  return (
+    <div>
+      <h2>{post.title}</h2>
+      <p>{t("posts.count", { count: post.commentCount })}</p>
+      <a href={`/posts/${post.slug}`}>{t("posts.readMore")}</a>
+    </div>
+  );
+}
+```
+
+`t()` reads the active locale from `I18nContext` (async local storage) — no props
+threading needed.
+
+## Errors
+
+`I18nError` (`E_I18N`) is the base; `CatalogLoadError` (`E_I18N_CATALOG_LOAD`) is
+thrown when a catalog file exists but contains malformed JSON. Both extend
+`ZerotalError`.
+
+## Testing
+
+Set your suite up once as described in [Testing](/docs/testing). Translation
+tests are cheap, and the two worth writing are the ones that catch a missing
+string before a user does.
+
+**Assert the resolved string, not the key.** A test that checks `t("cart.empty")
+=== "cart.empty"` passes when the catalogue is missing entirely:
+
+```typescript
+// tests/i18n/catalogues.test.ts
+import { test, expect } from "bun:test";
+import { t } from "@zerotal/i18n";
+
+test("renders the French cart message", () => {
+  expect(t("cart.empty", {}, "fr")).toBe("Votre panier est vide");
+});
+
+test("substitutes replacements", () => {
+  expect(t("cart.count", { n: 3 }, "fr")).toContain("3");
+});
+```
+
+**Test that every locale has every key.** This is the test that earns its place —
+it fails the moment someone adds an English string and forgets the translation,
+which is otherwise found in production by a French speaker:
+
+```typescript
+// tests/i18n/parity.test.ts
+import { test, expect } from "bun:test";
+import { loadCatalogs } from "@zerotal/i18n";
+
+test("every locale defines the same keys as English", async () => {
+  const catalogs = await loadCatalogs("./resources/lang");
+  const english = Object.keys(catalogs.en).sort();
+
+  for (const [locale, messages] of Object.entries(catalogs)) {
+    expect(Object.keys(messages).sort(), `locale: ${locale}`).toEqual(english);
+  }
+});
+```
+
+**Locale resolution is a separate concern** from translation, and fails
+separately — a correct catalogue served under the wrong locale looks like a
+missing translation:
+
+```typescript
+// tests/http/locale.test.ts
+const res = await app.get("/", { "Accept-Language": "fr-CA,fr;q=0.9" });
+
+res.assertSee("Votre panier est vide");
+```
+
+> **Note** — `resolveLocale` and `parseAcceptLanguage` are exported and pure, so
+> a header you are unsure about can be checked directly rather than through a
+> request.
+
+## References
+
+**Request context** — added by `LocaleMiddleware`:
+
+| Member       | Signature                                                              | Description                           |
+| ------------ | ---------------------------------------------------------------------- | ------------------------------------- |
+| `ctx.locale` | `string`                                                               | The locale resolved for this request. |
+| `ctx.t()`    | `t(key: string, replacements?: Replacements, locale?: string): string` | Translate using the request locale.   |
+
+**`Lang` facade** — the `i18n` binding (a `Translator`):
+
+| Method            | Signature                                                             | Description                                              |
+| ----------------- | --------------------------------------------------------------------- | -------------------------------------------------------- |
+| `Lang.translate`  | `(key: string, replacements?: Replacements, locale?: string): string` | Translate a key; a missing key returns the key itself.   |
+| `Lang.has`        | `(key: string, locale?: string): boolean`                             | Whether the key exists in the active or fallback locale. |
+| `Lang.locales`    | `string[]`                                                            | Loaded locales.                                          |
+| `Lang.addCatalog` | `(locale: string, messages: Messages): void`                          | Merge messages into a locale (tooling / tests).          |
+
+**Helpers & context** — importable from `@zerotal/i18n`:
+
+| Export                | Signature                                                             | Description                                      |
+| --------------------- | --------------------------------------------------------------------- | ------------------------------------------------ |
+| `t`                   | `(key: string, replacements?: Replacements, locale?: string): string` | Global translate; reads the active locale.       |
+| `I18nContext.run`     | `<T>(locale: string, cb: () => T): T`                                 | Run `cb` with `locale` active.                   |
+| `I18nContext.current` | `(): string \| undefined`                                             | Active locale, or `undefined` outside a request. |
+| `resolveLocale`       | `(request: Request, config: I18nConfigShape): string`                 | Resolve a request's locale per config.           |
+
+See [Configuration](#configuration) for the `config/i18n.ts` fields.
+
+## Next steps
+
+- [Validator](/docs/validator) — pair form validation with a translated `validation` namespace.
+- [Middleware](/docs/middleware) — how `LocaleMiddleware` resolves the request locale.
+- [Cookies](/docs/cookies) — persist a visitor's locale choice.
+- [View](/docs/view) — use `t()` inside server-rendered JSX.

package/docs/index.md

@@ -0,0 +1,65 @@
+---
+title: Documentation
+description: Start here — installation, the ideas behind Zerotal, and a map of every guide in the documentation.
+---
+
+# Zerotal Documentation
+
+Zerotal is a Bun-native, full-stack TypeScript framework. You write plain classes,
+drop them in convention-named folders, and the framework wires them together at
+boot — no build step, no manual registration.
+
+## New here?
+
+Three pages, in order, and you'll be productive:
+
+1. **[Getting Started](/docs/getting-started)** — scaffold a project, run it, add a
+   route, a model, and a [service provider](/docs/providers). Fifteen minutes.
+2. **[About Zerotal](/docs/about)** — the whole framework on one screen: the four
+   ideas it rests on, and a runnable example of every major feature.
+3. **[Conventions](/docs/conventions)** — what gets auto-discovered, and the naming
+   rules that make it happen. This is the page that stops the surprises.
+
+```bash
+# in your project's parent directory
+bun create zerotal my-app
+cd my-app && bun dev
+```
+
+## Find your way around
+
+| If you want to…                    | Read                                                                                                                                              |
+| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Handle a request                   | [Routing](/docs/routing) · [Controllers](/docs/controllers) · [Middleware](/docs/middleware) · [Requests Context](/docs/context)                  |
+| Talk to a database                 | [Database](/docs/database) · [ORM](/docs/orm) · [Migrations](/docs/migrations) · [Query Builder](/docs/query-builder)                             |
+| Build a UI                         | [Views](/docs/view) · [Flow](/docs/flow) · [Inertia](/docs/inertia) · [Assets](/docs/assets)                                                      |
+| Sign users in                      | [Authentication](/docs/authentication) · [Authorization](/docs/authorization) · [Roles & 2FA](/docs/roles-and-2fa) · [Social Login](/docs/social) |
+| Do work in the background          | [Queue](/docs/queue) · [Scheduler](/docs/scheduler) · [Broadcasting](/docs/broadcasting)                                                          |
+| Understand how the framework boots | [The Application](/docs/application) · [Lifecycle](/docs/lifecycle) · [Container](/docs/container) · [Providers](/docs/providers)                 |
+| Test what you built                | [Testing](/docs/testing) · [HTTP Tests](/docs/testing/http) · [Database Tests](/docs/testing/database)                                            |
+| See what's running in production   | [Logger](/docs/logger) · [Monitor](/docs/monitor) · [Telemetry](/docs/telemetry) · [Health](/docs/health)                                         |
+| Debug what it just did             | [DevTools](/docs/devtools) · [Errors](/docs/errors)                                                                                               |
+| Work with a coding agent           | [Agent Surface](/docs/arch)                                                                                                                       |
+| Ship it                            | [Deployment](/docs/deployment) · [Commands](/docs/commands)                                                                                       |
+
+## Choosing a frontend
+
+Zerotal doesn't pick for you, and the choice is per project rather than per
+framework:
+
+- **[Views](/docs/view)** — server-rendered JSX. No client runtime at all. Right for
+  content sites, forms, and anything that doesn't need live updates.
+- **[Flow](/docs/flow)** — reactive components rendered on the server, updated
+  over a WebSocket. You write TypeScript classes, not client state. Right when you
+  want interactivity without a separate frontend codebase.
+- **[Inertia](/docs/inertia)** — a React or Vue SPA that talks to your controllers
+  directly, with no API layer to maintain. Right when you already know React or Vue
+  and want the full client-side experience.
+
+## Reference
+
+- **[API Reference](/docs/api)** — generated from source, every exported symbol.
+- **[Commands](/docs/commands)** — every `bun zt` command.
+- **[Release Notes](/docs/changelog)** · **[Upgrade Guide](/docs/upgrade)**
+- **[Package Development](/docs/package-development)** — build your own `@zerotal`-style package.
+- **[Contribution Guide](/docs/contributing)** · **[Inspirations](/docs/inspirations)**

package/docs/inertia/build.md

@@ -0,0 +1,95 @@
+---
+title: Inertia CLI & Build
+description: The page registry, the bundler pipeline, and building for production.
+---
+
+# CLI & build
+
+`@zerotal/inertia` ships two commands — one to scaffold page components, one to
+bundle them — plus the page registry that ties component names to files.
+
+## Generating a page
+
+Scaffold a new page component under your pages directory (`resources/js/pages/` by default):
+
+```bash
+# in your project root
+bun zt make:page Dashboard
+bun zt make:page Users/Index          # nested — creates resources/js/pages/Users/Index.tsx
+```
+
+The generated stub wires up `usePage()` for typed access to shared props and a couple
+of starter links. The framework (React `.tsx` or Vue `.vue`) is auto-detected from
+the Inertia adapter you installed; force it with `--framework vue` or `--framework react`.
+After writing the file, `make:page` regenerates the [page registry](#page-registry)
+automatically.
+
+### Persistent layouts — --layout
+
+Pass `--layout` to wrap the page in an Inertia persistent layout (the layout mounts
+once and survives client-side navigations; only the page content re-renders):
+
+```bash
+# in your project root
+bun zt make:page Settings --layout MainLayout
+```
+
+This emits a page that assigns a `.layout` function and imports the layout from a
+`layouts/` directory relative to the page. Adjust the import path if your layouts live
+elsewhere — the generator prints a reminder.
+
+| Argument / flag | Description                                                        |
+| --------------- | ------------------------------------------------------------------ |
+| `name`          | Page name, e.g. `Dashboard` or `Users/Index` (required).           |
+| `--layout`      | Wrap the page in a persistent layout component.                    |
+| `--framework`   | Force `vue` or `react` (auto-detected from the installed adapter). |
+
+## Building assets
+
+Bundle the frontend with `Bun.build` and regenerate the page registry:
+
+```bash
+# in your project root
+bun zt inertia:build         # development build (external source maps)
+bun zt inertia:build -p      # production build (minified, no source maps)
+```
+
+The build:
+
+- entrypoint `resources/js/app.tsx` → output `public/assets/`,
+- targets the browser with **code splitting on** (each page becomes its own chunk
+  from the registry's dynamic imports, so navigation only loads what it needs),
+- auto-detects and applies CSS (and Vue) plugins present in your project,
+- prints a table of output files and sizes.
+
+| Flag                 | Effect                                              |
+| -------------------- | --------------------------------------------------- |
+| `-p`, `--production` | Minify and drop source maps for a production build. |
+
+Pair `inertia:build -p` with a hashed [asset version](/docs/inertia/middleware#asset-versioning)
+in your deploy so clients reload onto the new bundle.
+
+## Page registry
+
+The page registry is a generated module (`resources/js/pages.generated.ts`) mapping each
+component name (e.g. `"Users/Index"`) to a dynamic `import()` of its file. It's what lets
+the client resolve `inertia("Users/Index")` to the right chunk, and what enables per-page
+code splitting.
+
+You rarely touch it directly — both `make:page` and `inertia:build` regenerate it.
+To regenerate programmatically:
+
+```ts
+// in a build script
+import { generatePageRegistry } from "@zerotal/inertia";
+
+await generatePageRegistry(process.cwd());
+```
+
+Run it whenever you add or remove page files outside the generators (e.g. in a custom
+build script) so the registry stays in sync with your pages directory.
+
+## Next steps
+
+- [Inertia overview](/docs/inertia) — the guide's front page and the rest of the sections.
+- [Reference](/docs/inertia/references) — the full API surface in one table.