@zerotal/arch 1.7.4 → 1.8.0

package/docs/config-system.md

@@ -94,7 +94,7 @@ Dot-notation maps to the config file path and the key within it. `config('databa
 
 `config()` is type-aware. Each path resolves to the type declared in the owning package's `*ConfigShape`, with autocomplete on the path string:
 
-```typescript
+```typescript fragment
 // in application code
 config("app.name"); // string
 config("app.port"); // number
@@ -105,7 +105,7 @@ config.set("app.debug", "yes"); // type error: expected boolean
 
 This works exactly like the container's `ContainerBindings`: there's a `ConfigRegistry` interface that every config-owning package augments by namespace. Core registers `app` and `health`; each package registers its own next to its `*ConfigShape`:
 
-```typescript
+```typescript fragment
 // in a package's config registry declaration
 declare module "zerotal" {
   interface ConfigRegistry {
@@ -140,7 +140,7 @@ Because every file is loaded as a normal module, a config file may `import` and
 
 ## Overriding config in tests
 
-```typescript
+```typescript fragment
 // in a test setup file
 import { config } from "zerotal";
 
@@ -227,7 +227,7 @@ SESSION_SECRET=super-secret
 
 Use `APP_ENV` to differentiate behaviour:
 
-```typescript
+```typescript fragment
 // in application code
 if (config("app.env") === "production") {
   // production-only logic

package/docs/container.md

@@ -34,7 +34,7 @@ one line) and decoupling (a class depends on a `Mailer` contract, not on
 
 Inside a `ServiceProvider`, the container lives at `this.app.container`:
 
-```typescript
+```typescript fragment
 // in a ServiceProvider method
 this.app.container.singleton(CacheManager, () => new CacheManager());
 const cache = await this.app.container.make(CacheManager);
@@ -42,7 +42,7 @@ const cache = await this.app.container.make(CacheManager);
 
 Anywhere else, reach it through the application singleton:
 
-```typescript
+```typescript fragment
 // in application code outside a provider
 import { Application } from "zerotal";
 
@@ -97,7 +97,7 @@ Created once, then cached for the lifetime of the application. Every caller gets
 the same instance. The factory receives the container so it can resolve its own
 dependencies:
 
-```typescript
+```typescript fragment
 // in a ServiceProvider's onRegister()
 this.app.container.singleton(CacheManager, async (c) => {
   const cfg = await c.make("config");
@@ -115,7 +115,7 @@ Created once per HTTP request and isolated between concurrent requests via
 `AsyncLocalStorage`. Resolving a scoped binding outside of a request context
 throws `ScopedOutsideRequestError`:
 
-```typescript
+```typescript fragment
 // in a ServiceProvider's onRegister()
 this.app.container.scoped(UserSession, (c) => new UserSession());
 ```
@@ -124,7 +124,7 @@ this.app.container.scoped(UserSession, (c) => new UserSession());
 
 A fresh instance on every `make()`:
 
-```typescript
+```typescript fragment
 // in a ServiceProvider's onRegister()
 this.app.container.bind(ReportGenerator, () => new ReportGenerator());
 ```
@@ -133,7 +133,7 @@ this.app.container.bind(ReportGenerator, () => new ReportGenerator());
 
 Bind a pre-built instance directly — no factory, no lazy construction:
 
-```typescript
+```typescript fragment
 // in a ServiceProvider's onRegister()
 this.app.container.value("config", configObject);
 ```
@@ -142,7 +142,7 @@ this.app.container.value("config", configObject);
 
 Bindings are registered in a `ServiceProvider`'s `onRegister()`:
 
-```typescript
+```typescript fragment
 // app/providers/AppServiceProvider.ts
 import { ServiceProvider } from "zerotal";
 import { CacheManager } from "../services/CacheManager.ts";
@@ -197,7 +197,7 @@ can't register itself, and only reach for a provider when you need lifecycle hoo
 `App` is the canonical surface for application code — resolve from anywhere
 (pages, controllers, jobs) without importing `Application`:
 
-```typescript
+```typescript fragment
 // in a controller, page, or job
 import { App } from "zerotal";
 import { UsersService } from "@app/services/users-service.ts";
@@ -211,7 +211,7 @@ It also exposes registration (`bind`, `singleton`, `scoped`, `value`, `alias`,
 helpers (`environment()`, `isProduction()`, `isLocal()`). The `make()` and
 `app()` global helpers are shorthands:
 
-```typescript
+```typescript fragment
 // in application code
 import { make, app } from "zerotal";
 
@@ -225,7 +225,7 @@ const same = await app(UsersService); // = make(UsersService)
 Register bindings in `bootstrap/app.ts` without a provider. The callback runs at
 boot, before any provider's `onRegister()`, so providers can still override:
 
-```typescript
+```typescript fragment
 // bootstrap/app.ts — the callback receives the live container
 Application.create({ providers })
   .bind((container) => {
@@ -238,7 +238,7 @@ Application.create({ providers })
 This is the place for **interface → implementation** bindings, since a class
 can't register itself against a different token:
 
-```typescript
+```typescript fragment
 // bootstrap/app.ts
 Application.create({ providers }).bind((container) =>
   container.singleton(Mailer, () => new SendGridMailer(env("SENDGRID_KEY"))),
@@ -250,7 +250,7 @@ Application.create({ providers }).bind((container) =>
 Any class under `app/services/` is auto-discovered at boot. Declare its lifetime
 next to the class with a `static lifetime` flag and it's registered for you:
 
-```typescript
+```typescript fragment
 // app/services/users-service.ts
 @inject(Auth)
 export class UsersService {
@@ -288,7 +288,7 @@ binding at boot and the container hands each request its own instance.
 `make()` is the primary way to resolve a binding. It's async because factories
 may be async and deferred providers may need to boot first:
 
-```typescript
+```typescript fragment
 // in application code
 const cache = await container.make(CacheManager);
 const cfg = await container.make("config");
@@ -305,7 +305,7 @@ Anything else throws `SyncResolutionError`. This is what [facades](#facades) use
 internally — which is why providers pre-resolve (warm) their singleton in
 `onBooted()` before any facade call happens:
 
-```typescript
+```typescript fragment
 // in application code
 const cache = container.makeSync(CacheManager); // throws if not yet resolved
 ```
@@ -316,7 +316,7 @@ const cache = container.makeSync(CacheManager); // throws if not yet resolved
 instead of throwing when the token isn't registered. Useful for optional
 services that exist only in certain runtime modes:
 
-```typescript
+```typescript fragment
 // in a ServiceProvider — CommandRunner is only bound in console mode
 const runner = container.tryMake("commandRunner");
 if (runner) runner.register(MyCommand);
@@ -334,7 +334,7 @@ Pass a class's dependency tokens straight to `@inject(...)`. The container
 resolves each token — recursively, and **in parallel** — before constructing the
 class:
 
-```typescript
+```typescript fragment
 // app/repositories/PostRepository.ts
 import { inject } from "zerotal";
 import { CacheManager } from "../services/CacheManager.ts";
@@ -351,7 +351,7 @@ export class PostRepository {
 
 No registration needed — the container auto-wires on first `make()`:
 
-```typescript
+```typescript fragment
 // in application code
 const repo = await container.make(PostRepository);
 ```
@@ -365,7 +365,7 @@ classes, or string keys from `ContainerBindings`.
 A token is the key the container resolves against — a class constructor, an
 abstract class, or a string key declared in `ContainerBindings`:
 
-```typescript
+```typescript fragment
 // in application code
 // Class token (most common)
 container.singleton(CacheManager, factory);
@@ -379,7 +379,7 @@ const cfg = await container.make("config");
 Packages extend the `ContainerBindings` interface via declaration merging so
 string tokens stay fully type-safe:
 
-```typescript
+```typescript fragment
 // in a package's types.ts
 declare module "zerotal" {
   interface ContainerBindings {
@@ -409,7 +409,7 @@ After construction, any [`resolving()`](#resolving-hooks) hooks for the token fi
 
 Hand a different implementation of the same dependency to different consumers:
 
-```typescript
+```typescript fragment
 // in a ServiceProvider or bootstrap bind() callback
 // PostController gets the Redis cache; ReportController gets the file cache
 container.for(PostController).give(CacheDriver, () => new RedisCache());
@@ -434,7 +434,7 @@ of its `@inject` tokens.
 Bind one token as an alias for another. Resolving the alias returns the target's
 instance — handy for binding an interface/contract token to a concrete class:
 
-```typescript
+```typescript fragment
 // in a ServiceProvider or bootstrap bind() callback
 container.alias(CacheContract, CacheManager);
 const cache = await container.make(CacheContract); // → the CacheManager singleton
@@ -448,7 +448,7 @@ alias cycles.
 Run a callback every time a token resolves — for post-construction setup without
 subclassing or wrapping the factory:
 
-```typescript
+```typescript fragment
 // in a ServiceProvider or bootstrap bind() callback
 container.resolving(Logger, (logger) => {
   logger.setChannel("app");
@@ -463,7 +463,7 @@ instance is constructed.
 Register a provider so it boots only when one of its tokens is first resolved —
 keeping cold-start fast for services not used on every request:
 
-```typescript
+```typescript fragment
 // in a ServiceProvider or bootstrap bind() callback
 container.defer(SearchClient, SearchServiceProvider);
 ```
@@ -542,7 +542,7 @@ synchronously via `makeSync`. That's why providers pre-resolve their singleton i
 
 Core ships a few, importable from `zerotal`:
 
-```typescript
+```typescript fragment
 // in application code (after boot)
 import { Config, Events, Artisan } from "zerotal";
 
@@ -560,12 +560,12 @@ await Artisan.call("migrate");
 Packages ship their own — for example `Cache` from `@zerotal/cache`, `Auth` from
 `@zerotal/auth`:
 
-```typescript
+```typescript fragment
 // in application code (after boot)
 import { Cache } from "@zerotal/cache";
 import { Auth } from "@zerotal/auth";
 
-await Cache.put("key", value, 300);
+await Cache.set("key", value, 300);
 Auth.check(); // → boolean
 Auth.user(); // → AuthenticatedUser (throws if guest)
 Auth.userOrNull(); // → AuthenticatedUser | undefined
@@ -575,7 +575,7 @@ Auth.userOrNull(); // → AuthenticatedUser | undefined
 
 Build one with `createFacade<T>(token)`, passing the same token the provider binds:
 
-```typescript
+```typescript fragment
 // src/facades/Cache.ts
 import { createFacade } from "zerotal";
 import type { CacheManager } from "../CacheManager.ts";

package/docs/context.md

@@ -32,7 +32,7 @@ tests, build one with [`HttpContext.fake()`](#testing).
 Every method on the context is bound to its instance, so you can destructure
 exactly what a handler needs — methods included — without losing `this`:
 
-```typescript
+```typescript fragment
 // routes: Router.get('/posts/:post/:tab', PostController, 'show')
 
 async show({ view, params: { post, tab } }: HttpContext<{ post: Post; tab: string }>) {
@@ -55,7 +55,7 @@ instead (`async show(ctx: HttpContext)`) when you prefer `ctx.view(...)` /
 `ctx.params` is `Record<string, string>` — the raw matched segments. Pass a type
 argument to describe what the route resolves, including model bindings:
 
-```typescript
+```typescript fragment
 // raw params only — every value is a string
 async index(ctx: HttpContext) {
   const page = ctx.params.page; // string | undefined
@@ -81,7 +81,7 @@ name (and exposes it via `ctx.model<T>()`).
 Usually there is nothing to declare: a param whose name matches an auto-registered
 model binds on its own, so `:post` resolves through `Post` by primary key.
 
-```typescript
+```typescript fragment
 // routes/web.ts — :post is already bound to Post
 Router.get("/posts/:post", PostController, "show");
 
@@ -91,7 +91,7 @@ Router.get("/posts/:post", PostController, "show").bind("post", (slug) =>
 );
 ```
 
-```typescript
+```typescript fragment
 // in PostController — ctx.params.post is the resolved Post, not the raw id
 async show(ctx: HttpContext<{ post: Post }>) {
   return ctx.json(ctx.params.post);
@@ -114,7 +114,7 @@ custom resolvers, scoped bindings — lives in [Routing](/docs/routing).
 The scalar helpers check route params first, then the query string, and coerce to
 the type the method name promises. Each takes an optional fallback.
 
-```typescript
+```typescript fragment
 // in a controller
 ctx.query("page", "1"); // string | undefined — query string only
 ctx.string("sort", "asc"); // string | undefined — param then query
@@ -131,7 +131,7 @@ is absent, or the value is not a valid integer (`NaN`). Because parsing is base-
 validate with a [form request](/docs/validator) when you need to reject malformed
 input rather than coerce it.
 
-```typescript
+```typescript fragment
 // in a controller — GET /posts?page=3
 ctx.integer("page"); // 3
 ctx.integer("page", 1); // 3 (fallback unused)
@@ -147,7 +147,7 @@ of `'1'`, `'true'`, `'yes'`, or `'on'` (compared case-insensitively). Any other
 present value is `false`; an absent value returns the fallback, which defaults to
 `false`.
 
-```typescript
+```typescript fragment
 // in a controller
 ctx.boolean("active"); // ?active=true / ?active=1 / ?active=ON → true
 ctx.boolean("active"); // ?active=0 / ?active=no / ?active= → false
@@ -164,14 +164,14 @@ ctx.boolean("active", true); // absent → true (custom fallback)
 `body()` parses and caches the body (JSON, form-urlencoded, or multipart fields) so
 repeated calls are free, and returns `{}` on an absent or invalid body:
 
-```typescript
+```typescript fragment
 const data = await ctx.body<{ title: string; body: string }>();
 ```
 
 `input()` reads a single merged value in priority order — route params → cached
 body → query string — without awaiting:
 
-```typescript
+```typescript fragment
 ctx.input("id"); // route :id or ?id=
 ctx.input("q", "all"); // with fallback
 ```
@@ -183,7 +183,7 @@ ctx.input("q", "all"); // with fallback
 Read a header with `header()` (case-insensitive) or pull a Bearer token with
 `bearerToken()`:
 
-```typescript
+```typescript fragment
 ctx.header("x-forwarded-for"); // string | null
 ctx.bearerToken(); // string | null — strips the "Bearer " prefix
 ```
@@ -193,7 +193,7 @@ ctx.bearerToken(); // string | null — strips the "Bearer " prefix
 `file()` returns the first `UploadedFile` for a form field (or `null`); `files()`
 returns all of them. Both parse and cache the multipart body on first call.
 
-```typescript
+```typescript fragment
 const avatar = await ctx.file("avatar"); // UploadedFile | null
 const attachments = await ctx.files("attachments"); // UploadedFile[]
 ```
@@ -201,7 +201,7 @@ const attachments = await ctx.files("attachments"); // UploadedFile[]
 An `UploadedFile` describes the upload and knows how to persist itself. Validate
 before storing, then hand it a disk — `store()` returns the stored path:
 
-```typescript
+```typescript fragment
 // in a controller — single file
 const avatar = await ctx.file("avatar");
 
@@ -220,7 +220,7 @@ if (avatar) {
 }
 ```
 
-```typescript
+```typescript fragment
 // in a controller — multiple files
 for (const file of await ctx.files("attachments")) {
   await file.store("uploads", Storage.disk());
@@ -239,7 +239,7 @@ The response helpers set `ctx.response` for you and return nothing — they are
 terminal. You can also `return` a value from a controller; see
 [Responses](/docs/responses) for the full set.
 
-```typescript
+```typescript fragment
 ctx.json({ user }); // 200 application/json
 ctx.json({ errors }, 422); // custom status
 ctx.view(WelcomeView, { name }); // full HTML document (prepends <!DOCTYPE html>)
@@ -253,7 +253,7 @@ ctx.back(303); // same, with a 303 status
 `view()` accepts either pre-rendered markup, or a **view component plus its props**.
 A view component receives the request `HttpContext` first and your props second:
 
-```typescript
+```typescript fragment
 // resources/views/Welcome.tsx
 export default function Welcome(ctx: HttpContext, { title }: { title: string }) {
   return (
@@ -307,7 +307,7 @@ the pipeline, ordering, and registration.
 the matching record, and assigns it to `ctx.user`; `AuthMiddleware` reads it to guard
 routes. It is `undefined` for guests.
 
-```typescript
+```typescript fragment
 if (!ctx.user) throw new UnauthorizedError();
 return ctx.json({ email: ctx.user.email });
 ```
@@ -317,7 +317,7 @@ registered auth model — see [Authentication](/docs/authentication).
 
 ## Client IP
 
-```typescript
+```typescript fragment
 ctx.ip(); // string | null — socket-level IP from Bun's server.requestIP()
 ```
 
@@ -331,7 +331,7 @@ with `HttpContext.fake()`).
 
 ## URL & matching helpers
 
-```typescript
+```typescript fragment
 ctx.path(); // "/posts" — pathname only
 ctx.fullUrl(); // "https://app.test/posts?page=2"
 ctx.host(); // "app.test"
@@ -343,7 +343,7 @@ ctx.subdomains; // { tenant: "acme" }
 `isJson()` / `wantsJson()` inspect the `Content-Type` / `Accept` headers — handy in
 an exception handler, or anywhere one route serves both browsers and API clients:
 
-```typescript
+```typescript fragment
 // in a controller or middleware
 if (ctx.wantsJson()) {
   ctx.json({ message: "Unauthorized" }, 401);
@@ -358,13 +358,13 @@ Flash writes a value to the session for the **next** request only — ideal for
 post-redirect success and error messages. It requires `SessionMiddleware` and
 silently no-ops without it.
 
-```typescript
+```typescript fragment
 // before redirecting
 ctx.flash("success", "Post saved!");
 return ctx.redirect("/posts", 303);
 ```
 
-```typescript
+```typescript fragment
 // on the next request
 const msg = ctx.flashed<string>("success"); // 'Post saved!'
 ```
@@ -378,7 +378,7 @@ Register work to run **after** the response has been sent — fire-and-forget si
 effects that shouldn't delay the client. `afterResponse()` returns `this`, so calls
 chain.
 
-```typescript
+```typescript fragment
 ctx.afterResponse(async () => {
   await analytics.track(ctx.requestId, ctx.url.pathname);
 });
@@ -413,7 +413,7 @@ request — a service shared with CLI commands or queue workers — uses
 `RequestContext.remember(key, factory)` runs `factory` at most once per request
 for a given key and hands every later caller the same answer:
 
-```typescript
+```typescript fragment
 import { RequestContext } from "zerotal";
 
 const settings = await RequestContext.remember(`household:${id}:settings`, () =>
@@ -446,7 +446,7 @@ earlier in the same request.
 `HttpContext.fake()` builds a context without a live server — perfect for unit
 testing controllers and middleware:
 
-```typescript
+```typescript fragment
 const ctx = HttpContext.fake("http://localhost/posts?page=2", {
   method: "GET",
   headers: { Authorization: "Bearer token" },
@@ -459,7 +459,7 @@ expect(ctx.response?.status).toBe(200);
 Pass a `body` to exercise handlers that read one, and assign `ctx.params` directly
 when the handler expects route params a real match would have provided:
 
-```typescript
+```typescript fragment
 // in a test — a POST with a JSON body
 const ctx = HttpContext.fake("http://localhost/posts", {
   method: "POST",
@@ -470,14 +470,14 @@ ctx.params = { id: "42" };
 ```
 
 The signature is `HttpContext.fake(url?, init?, container?)`; all three are optional.
-See [Testing](/docs/testing/index) for the full harness, and
+See [Testing](/docs/testing) for the full harness, and
 [HTTP testing](/docs/testing/http) for the higher-level request helpers.
 
 ## References
 
 ### `HttpContext<TParams>`
 
-```typescript
+```typescript fragment
 class HttpContext<TParams extends Record<string, unknown> = Record<string, string>> {
   constructor(request: Request, container: ScopedResolver);
 }

package/docs/contributing.md

@@ -149,6 +149,34 @@ that keeps it complete.
 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.
 
+### Code examples are compiled
+
+Every TypeScript block in `docs/` is compiled against the real packages by
+`bun run docs:examples:check`, which CI runs on every pull request. An example that
+names a member the API no longer has fails the build rather than waiting for a reader
+to find it.
+
+Plenty of blocks are not whole programs on purpose — a class body, a set of columns,
+a method shown without the class around it. Say so in the fence:
+
+````text
+```ts fragment
+@column("string") name!: string;
+@column("boolean") active!: boolean;
+```
+````
+
+`fragment` works on `ts`, `tsx` and `typescript`, and readers never see it: a fence's
+info string carries only its first word into the rendered page. It is never guessed —
+a block is a fragment because you wrote that it is, and a run of
+`bun run docs:examples` records it so a new one is a deliberate change rather than a
+silent exemption.
+
+Two lists back that up. `fragments` in `docs-examples-baseline.json` are the
+intentional ones. `drift` is the other kind: a block that resolves every import and
+still fails, which means the page is wrong. Neither list may grow, and `drift` is
+meant to reach zero.
+
 ## Changelogs
 
 Each package keeps its own `CHANGELOG.md`. Add what you changed under

package/docs/controllers.md

@@ -16,7 +16,7 @@ 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
+```typescript fragment
 // app/controllers/PostController.ts
 import type { HttpContext } from "zerotal";
 import { Post } from "../models/Post.ts";
@@ -48,7 +48,7 @@ export class PostController {
 
 Map routes to actions by passing the controller class and the action name:
 
-```typescript
+```typescript fragment
 // routes/index.ts
 import { Router } from "zerotal";
 import { PostController } from "../app/controllers/PostController.ts";
@@ -71,7 +71,7 @@ dependencies. Decorate the **class** with `@inject(...)`, listing the tokens in
 constructor order — the container resolves each token and passes it to the
 constructor:
 
-```typescript
+```typescript fragment
 // app/controllers/PostController.ts
 import type { HttpContext } from "zerotal";
 import { inject } from "zerotal";
@@ -127,12 +127,12 @@ declaration — the resolved instance arrives on `ctx.params` under the param's
 or you can read it explicitly with `ctx.model()`. `.bind()` and the model's own
 `resolveRouteBinding` are for overriding that default:
 
-```typescript
+```typescript fragment
 // routes/index.ts — :post already resolves through Post
 Router.get("/posts/:post", PostController, "show");
 ```
 
-```typescript
+```typescript fragment
 // app/controllers/PostController.ts — via ctx.params:
 async show(ctx: HttpContext<{ post: Post }>): Promise<void> {
   ctx.json(ctx.params.post);
@@ -176,7 +176,7 @@ export class StorePostRequest extends FormRequest {
 returns the validated data fully typed from your `rules()` return — it throws a
 validation error on failure:
 
-```typescript
+```typescript fragment
 // app/controllers/PostController.ts
 import { StorePostRequest } from "../requests/posts/StorePostRequest.ts";
 
@@ -228,7 +228,7 @@ export class ArticleController {
 
 Register all seven with a single call, or narrow them with `.only()` / `.except()`:
 
-```typescript
+```typescript fragment
 // routes/index.ts
 Router.resource("articles", ArticleController);
 Router.resource("articles", ArticleController).only(["index", "show"]);
@@ -243,7 +243,7 @@ Router.resource("articles", ArticleController).except(["create", "edit"]);
 Controllers set `ctx.response` via helper methods — they do not return a value
 (the return type is `Promise<void>`):
 
-```typescript
+```typescript fragment
 // in a controller action
 ctx.json(data); // 200 JSON
 ctx.json(data, 201); // 201 JSON
@@ -281,7 +281,7 @@ 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
+```typescript fragment
 // in a controller action
 import { Auth } from "@zerotal/auth";
 
@@ -304,7 +304,7 @@ 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
+```typescript fragment
 // in a controller action
 async store(ctx: HttpContext): Promise<void> {
   const post = await Post.create(data);