@zerotal/arch 1.7.4 → 1.7.5

package/docs/helpers.md

@@ -23,7 +23,7 @@ Read an environment variable with an optional, type-coerced fallback. This is th
 canonical way to read env values — every config file uses it. The return type
 follows the fallback's type.
 
-```typescript
+```typescript fragment
 // config/app.ts
 env("APP_NAME", "Zerotal App"); // string
 env("APP_DEBUG", false); // boolean — coerces 'true' / '1'
@@ -36,7 +36,7 @@ env("APP_KEY"); // string | undefined — no fallback
 Read a variable that must exist. Throws a `ConfigError` at boot if it's missing —
 use it for secrets your app cannot run without.
 
-```typescript
+```typescript fragment
 // config/app.ts
 const key = requireEnv("APP_KEY"); // throws ConfigError if unset
 ```
@@ -47,7 +47,7 @@ Resolve a path relative to the project root (`process.cwd()`), regardless of whi
 file calls it. Use it when declaring route files so paths don't depend on the
 caller's directory.
 
-```typescript
+```typescript fragment
 // bootstrap/app.ts
 Application.create({ providers })
   .routing({ web: basePath("routes/web.ts") })
@@ -61,7 +61,7 @@ managed `zt.ts`; you rarely call it yourself. `serve`/`start`/`s` → `web`,
 `worker`/`queue:work` → `worker`, anything else → `console`. A no-op if `APP_ENV`
 is already a valid runtime mode.
 
-```typescript
+```typescript fragment
 // zt.ts
 setAppEnv(process.argv[2]);
 const { default: app } = await import("./bootstrap/app.ts");
@@ -73,7 +73,7 @@ const { default: app } = await import("./bootstrap/app.ts");
 
 Read (and write) loaded configuration by dot-path, anywhere after boot.
 
-```typescript
+```typescript fragment
 // in a controller
 config("app.name"); // string — typed from the registered config shape
 config("app.port", 3000); // number — fallback must match the path's type
@@ -96,7 +96,7 @@ Reach the current request's `HttpContext` from anywhere in the async call chain
 no thread-through required. With a key, it reads a single merged input value (route
 params, then parsed body, then query string).
 
-```typescript
+```typescript fragment
 // in a controller
 request(); // the HttpContext
 request("email"); // string | undefined — input named 'email'
@@ -114,7 +114,7 @@ request<number>("page", 1); // typed input with a fallback
 Run a side effect on a value and return the value unchanged — perfect for emitting
 an event or logging in the middle of a chain without breaking it.
 
-```typescript
+```typescript fragment
 // in a controller
 return tap(await User.create(data), (user) => Events.emit(new UserRegistered(user.id)));
 
@@ -128,7 +128,7 @@ return await tapAsync(await User.create(data), async (user) => {
 The sibling of `tap` — pass a value through a transformer and return the _result_.
 Use `pipe` when the value should change, `tap` when it shouldn't.
 
-```typescript
+```typescript fragment
 // in a controller
 const slug = pipe(post.title, (t) => t.toLowerCase().replace(/\s+/g, "-"));
 const hashed = await pipeAsync(password, (p) => Hash.make(p));
@@ -140,7 +140,7 @@ Run a callback and fall back to a value (or a function of the caught error) inst
 of throwing. `rescue` awaits; `rescueSync` is for hot paths that can't await
 (JSON parsing, attribute decoding).
 
-```typescript
+```typescript fragment
 // in a controller
 const price = await rescue(() => stripe.getPrice(id), 0);
 const user = await rescue(
@@ -160,7 +160,7 @@ Safely read a deeply nested value by dot-notation, returning a default when any
 segment is absent. Built for untyped JSON — webhooks, third-party API responses —
 where optional chaining gets unwieldy. Numeric segments index into arrays.
 
-```typescript
+```typescript fragment
 // in a webhook handler
 data_get(payload, "user.address.city"); // 'Cape Town' or undefined
 data_get(payload, "items.0.price", 0); // first item's price, or 0
@@ -171,7 +171,7 @@ data_get(payload, "items.0.price", 0); // first item's price, or 0
 `Str` is a namespace of pure string utilities. The common case-conversions are
 also exported individually (`camelCase`, `snakeCase`).
 
-```typescript
+```typescript fragment
 // in a controller
 Str.camelCase("user_id"); // 'userId'
 Str.snakeCase("userId"); // 'user_id'
@@ -270,7 +270,7 @@ flat, and `DeepPartial<XConfigShape>` when it nests — both satisfy the package
 An array in the override replaces the base array entirely. It is **never**
 concatenated, de-duplicated, or merged element-by-element:
 
-```typescript
+```typescript fragment
 // in a config factory
 deepMerge({ hosts: ["a", "b"] }, { hosts: ["c"] });
 // → { hosts: ['c'] }   (not ['a','b','c'], not ['c','b'])
@@ -301,7 +301,7 @@ matches how you want overrides to behave.
 Wrap any value to chain `.pipe()` transforms and `.tap()` side effects, then unwrap
 with `.get()`. Useful for readable builder-style code over a plain value.
 
-```typescript
+```typescript fragment
 // in a controller
 const user = fluent(await User.find(id))
   .tap((u) => log(`loaded ${u.email}`))
@@ -314,7 +314,7 @@ Wrap an array in a `Collection` for chainable, immutable transformations — `ma
 `filter`, `reduce`, `groupBy`, `pluck`, `sum`, `first`, `unique`, and more — a
 fluent collection pipeline.
 
-```typescript
+```typescript fragment
 // in a controller
 const topNames = collect(orders)
   .filter((o) => o.paid)
@@ -332,7 +332,7 @@ These build and send the HTTP response for the current request. The terminal
 helpers (`json`, `view`, `html`, `markdown`, `file`) set `ctx.response` directly;
 `redirect()` and `redirectTo()` return a chainable `ResponseBuilder`.
 
-```typescript
+```typescript fragment
 // in a controller
 import { json, view, html, markdown, redirect, redirectTo, abort } from "zerotal";
 
@@ -352,7 +352,7 @@ redirectTo("posts.show", { id }); // redirect to a named route
 `redirect()` and `redirect().back()` return a `ResponseBuilder` that lets you flash
 data and messages onto the redirect:
 
-```typescript
+```typescript fragment
 // in a controller
 return redirect("/posts").withSuccess("Post created.").with("highlight", post.id);
 
@@ -366,7 +366,7 @@ return redirect().back().withErrors({ title: "Title is required." });
 
 `abort()` throws a framework error that the exception handler renders:
 
-```typescript
+```typescript fragment
 // in a controller
 abort("Something went wrong."); // → 500 with a message
 abort(403, "You can't do that."); // status + message

package/docs/i18n.md

@@ -101,7 +101,7 @@ themselves. An unmatched lookup returns the key, and the key is the English.
 `LocaleMiddleware` resolves the locale for every request and exposes `ctx.locale`
 and `ctx.__()` on the request context:
 
-```typescript
+```typescript fragment
 // in a controller
 async show(ctx: HttpContext) {
   ctx.__("Hello, {name}!", { name: "Alice" });       // active locale
@@ -140,7 +140,7 @@ Lang.translate("Sign in"); // the facade, when you want the instance
 A React interface cannot reach the server's `Translator`, so the active locale's
 catalog travels to it as a shared Inertia prop:
 
-```typescript
+```typescript fragment
 // bootstrap/app.ts
 import { share } from "@zerotal/inertia";
 import fr from "../resources/lang/fr.json";
@@ -157,7 +157,7 @@ Client-side, keep the catalog in module state and hand it to the translator from
 the component in, which is what makes the first render after a language change
 come out in the new language:
 
-```tsx
+```tsx fragment
 // resources/js/app.tsx
 createInertiaApp({
   resolve: async (name, incoming) => {
@@ -179,7 +179,7 @@ guarantees the assignment has run:
 
 A component then calls it with no import and no hook:
 
-```tsx
+```tsx fragment
 // resources/js/pages/login.tsx
 <TextField label={__("Email")} type="email" />
 ```
@@ -267,7 +267,7 @@ English strings as well — the ambiguity was there before the translator found
 Enum values and column names cannot be passed to `__()` — `in_progress` is not
 English. Map them to English first, then translate the result:
 
-```typescript
+```typescript fragment
 const STATUS_LABEL: Record<string, string> = {
   backlog: "Backlog",
   in_progress: "In progress",
@@ -310,7 +310,7 @@ things.
 **Persist a user's choice** by writing the `locale` cookie; the `cookie` resolver
 picks it up on every subsequent request:
 
-```typescript
+```typescript fragment
 // in a controller — save the visitor's language choice
 async setLocale(ctx: HttpContext) {
   const { locale } = await ctx.body<{ locale: string }>();
@@ -328,7 +328,7 @@ async setLocale(ctx: HttpContext) {
 user — by running code inside `I18nContext.run()`. The `Lang` facade and `__()`
 helper use the supplied locale for the duration of the callback:
 
-```typescript
+```typescript fragment
 // in a controller
 import { I18nContext, __ } from "@zerotal/i18n";
 
@@ -355,7 +355,7 @@ belonging to whoever triggered the job was never the right answer anyway. Mail
 should arrive in the language of the person opening it, so pass the locale
 explicitly as the third argument:
 
-```typescript
+```typescript fragment
 // app/notifications/IssueAssignedNotification.ts
 toMail(notifiable: Notifiable): MailMessage {
   const recipient = notifiable as { name?: string; locale?: string | null };
@@ -389,7 +389,7 @@ See [Validator](/docs/validator) for how the validator itself reports errors.
 
 ## Using __ in JSX views
 
-```tsx
+```tsx fragment
 // app/views/PostCard.tsx
 import { __ } from "@zerotal/i18n";
 
@@ -469,7 +469,7 @@ test("reports the strings each locale still needs", async () => {
 separately — a correct catalogue served under the wrong locale looks like a
 missing translation:
 
-```typescript
+```typescript fragment
 // tests/http/locale.test.ts
 const res = await app.get("/", { "Accept-Language": "fr-CA,fr;q=0.9" });
 

package/docs/inertia/devtools.md

@@ -84,7 +84,7 @@ INERTIA_DEVTOOLS_ENABLED=true    # on — see the warning below
 
 Or configure it:
 
-```typescript
+```typescript fragment
 // config/inertia.ts
 import { InertiaConfig } from "zerotal/inertia";
 
@@ -129,7 +129,7 @@ Matching is a case-insensitive substring, so `password` also covers
 
 Add your own:
 
-```typescript
+```typescript fragment
 // config/inertia.ts
 export default InertiaConfig({
   devtools: {
@@ -148,7 +148,7 @@ request.
 The read API never records itself. Add anything else that would bury the
 timeline:
 
-```typescript
+```typescript fragment
 // config/inertia.ts
 export default InertiaConfig({
   devtools: { except: ["/health", "/metrics"] },
@@ -157,7 +157,7 @@ export default InertiaConfig({
 
 ### Gating a shared environment
 
-```typescript
+```typescript fragment
 // config/inertia.ts
 export default InertiaConfig({
   devtools: {

package/docs/inertia/index.md

@@ -128,7 +128,7 @@ object and root `<div>` are injected on every response:
 
 A controller action calls `inertia(component, props)`:
 
-```ts
+```ts fragment
 // app/controllers/DashboardController.ts
 import type { HttpContext } from "zerotal";
 import { inertia } from "@zerotal/inertia";
@@ -147,7 +147,7 @@ argument** — and sets the response as a side effect, so the action returns
 `Promise<void>`. The component name (`"Dashboard"`) maps to
 `resources/js/pages/Dashboard.tsx`.
 
-```tsx
+```tsx fragment
 // resources/js/pages/Dashboard.tsx
 import { Link } from "@inertiajs/react";
 
@@ -191,7 +191,7 @@ one it wants.
 is the assertion you want in almost every route test — it checks the component
 and its props without parsing markup:
 
-```typescript
+```typescript fragment
 // tests/http/dashboard.test.ts
 import { test } from "bun:test";
 import { createApp } from "../helpers.ts";
@@ -211,7 +211,7 @@ test("the dashboard renders with its stats", async () => {
 embedded in a `data-page` attribute — right for asserting the first paint, wrong
 for asserting props:
 
-```typescript
+```typescript fragment
 // tests/http/dashboard.test.ts
 const res = await app.actingAs(user).get("/dashboard");
 
@@ -222,7 +222,7 @@ res.assertHeader("Vary", "X-Inertia"); // the response varies by that header
 **Test partial reloads by the props they omit.** A partial reload that quietly
 returns everything is a performance bug no page-level assertion catches:
 
-```typescript
+```typescript fragment
 // tests/http/dashboard.test.ts
 const res = await app.actingAs(user).get("/dashboard", {
   "X-Inertia": "true",
@@ -238,7 +238,7 @@ expect(page.props.notifications).toBeUndefined(); // excluded, as asked
 **A version mismatch is a `409`, not an error.** It tells the client to reload so
 it picks up new assets — worth a test if you set `ASSET_VERSION` on deploy:
 
-```typescript
+```typescript fragment
 // tests/http/dashboard.test.ts
 const res = await app.get("/dashboard", { "X-Inertia": "true", "X-Inertia-Version": "stale" });
 

package/docs/inertia/props.md

@@ -32,7 +32,7 @@ The server evaluates and returns just those props; the client keeps the rest. Ze
 `X-Inertia-Partial-Data` / `X-Inertia-Partial-Except` / `X-Inertia-Partial-Component` headers
 automatically — you don't write any special code for the route, you just make props lazy.
 
-```tsx
+```tsx fragment
 // client
 router.reload({ only: ["users"] });
 ```
@@ -41,7 +41,7 @@ router.reload({ only: ["users"] });
 
 Wrap optional data in a function so it's only evaluated when actually included:
 
-```ts
+```ts fragment
 // in a controller
 return inertia("Users/Index", {
   users: () => User.all(), // evaluated every full visit, and on partial reloads that ask for it
@@ -57,7 +57,7 @@ it from a partial reload also skips the query.
 `optional(fn)` — never sent on a normal visit; only when explicitly requested via `only`. Ideal for
 expensive data the page can load on demand.
 
-```ts
+```ts fragment
 // in a controller
 return inertia("Users/Index", {
   users: optional(() => User.all()), // only when reloaded with only: ["users"]
@@ -83,7 +83,7 @@ shared `errors` bag uses this internally.)
 request — great for below-the-fold or slow data. Group props to control parallelism (each group is
 one request).
 
-```ts
+```ts fragment
 // in a controller
 return inertia("Users/Index", {
   users: () => User.all(),
@@ -96,7 +96,7 @@ return inertia("Users/Index", {
 The first response carries a `deferredProps` map; the client then partial-reloads each group. On the
 client, wrap the UI in `<Deferred>`:
 
-```tsx
+```tsx fragment
 // in a page component
 import { Deferred } from "@inertiajs/react";
 
@@ -110,7 +110,7 @@ import { Deferred } from "@inertiajs/react";
 Pass `{ rescue: true }` so a thrown error is swallowed and the key reported in `rescuedProps` (the
 client renders the `<Deferred rescue>` slot) instead of failing the whole response:
 
-```ts
+```ts fragment
 // in a controller
 permissions: defer(() => Permission.all(), "default", { rescue: true }),
 ```
@@ -121,7 +121,7 @@ By default a reloaded prop _replaces_ the client value. `merge()` / `deepMerge()
 **combine** the new data with what it already has — the basis for paginated "load more" lists. Merging
 only happens on partial reloads (full visits always replace).
 
-```ts
+```ts fragment
 // in a controller
 return inertia("Feed", {
   posts: merge(() => Post.paginate(15, page)), // append at root
@@ -130,7 +130,7 @@ return inertia("Feed", {
 
 Chainable targeting:
 
-```ts
+```ts fragment
 // in a controller
 merge(users).append("data").matchOn("data.id"); // append to users.data, replace items matching id
 merge(items).prepend(); // prepend at root
@@ -147,7 +147,7 @@ before merging fresh data (e.g. on a new search) — Zerotal honors the `X-Inert
 paginator's `data` array and emits a `scrollProps` entry describing the current/next/previous page,
 so the client knows when (and which way) to load more:
 
-```ts
+```ts fragment
 // app/controllers/PostController.ts
 import { inertia, scroll } from "@zerotal/inertia";
 
@@ -176,7 +176,7 @@ This produces a page object like:
 `X-Inertia-Infinite-Scroll-Merge-Intent: prepend` and Zerotal prepends the new page instead of
 appending — no controller change needed. On the client:
 
-```tsx
+```tsx fragment
 // in a page component
 import { InfiniteScroll } from "@inertiajs/react";
 
@@ -193,7 +193,7 @@ Chain `.once()` onto an optional/merge/defer prop so it's resolved a single time
 client across navigations. The client sends `X-Inertia-Except-Once-Props` with the keys it already
 holds; the server skips re-resolving them.
 
-```ts
+```ts fragment
 // in a controller
 return inertia("Billing/Plans", {
   plans: optional(() => Plan.all()).once(),
@@ -231,7 +231,7 @@ export default InertiaConfig({ encryptHistory: true });
 `Inertia.location(url)` performs a full-page visit to an external URL — a `409` with
 `X-Inertia-Location` for Inertia requests, a `302` otherwise:
 
-```ts
+```ts fragment
 // in a controller
 return Inertia.location("https://billing.stripe.com/session/abc");
 ```
@@ -247,7 +247,7 @@ side effects** — perfect for live, inline validation. Register `PrecognitionMi
 `FormRequest`; when the client sends `Precognition: true`, `FormRequest.validate()` short-circuits
 with a `204` (valid) or `422` (errors), optionally limited to the fields in `Precognition-Validate-Only`.
 
-```ts
+```ts fragment
 // bootstrap — register PrecognitionMiddleware globally
 import { PrecognitionMiddleware } from "@zerotal/inertia";
 
@@ -302,7 +302,7 @@ same key wins.
 
 ### What's provided
 
-```ts
+```ts fragment
 // the shared bag sharedProps() returns
 {
   auth: {
@@ -325,7 +325,7 @@ that bag. The other shared props (`auth`/`flash`/`old`) are ordinary props, so a
 
 Every page component can read these without the controller passing them:
 
-```tsx
+```tsx fragment
 // resources/js/pages/Page.tsx
 import { usePage } from "@inertiajs/react";
 
@@ -365,7 +365,7 @@ Register props once — typically in a provider's boot or in middleware — and
 every page. Values may be plain values, factory functions (evaluated lazily per request), or any
 [prop wrapper](#data-props):
 
-```ts
+```ts fragment
 // in a provider's boot or middleware
 import { Inertia } from "@zerotal/inertia";
 
@@ -384,7 +384,7 @@ over during instant visits.
 
 #### Merge in the controller
 
-```ts
+```ts fragment
 // in a controller
 return inertia("Dashboard", {
   notifications: await Notification.query().where("user_id", user.id).unread().get(),
@@ -397,7 +397,7 @@ return inertia("Dashboard", {
 When several pages need the same extra data, set it on the context in a middleware
 and read it back in the controller — keeping the controller body clean:
 
-```ts
+```ts fragment
 // in a middleware:
 ctx.setInternal("unreadCount", await Notification.unreadCount(ctx.user!.id));
 
@@ -415,7 +415,7 @@ displays the value on every page.
 The props a controller passes are checked against the props the page component
 declares:
 
-```tsx
+```tsx fragment
 // resources/js/pages/Posts/Show.tsx
 interface Props {
   post: Post;
@@ -425,7 +425,7 @@ interface Props {
 export default function Show({ post, related, stats }: Props) { … }
 ```
 
-```ts
+```ts fragment
 // in a controller
 return Inertia.render("Posts/Show", {
   post,
@@ -455,7 +455,7 @@ the component receives `Post[]` — so each prop accepts its value, a factory fo
 it, or a wrapper carrying it, and the wrapper's payload is checked against the
 prop it fills:
 
-```ts
+```ts fragment
 Inertia.render("Posts/Show", { post, related: merge(() => [1, 2]) });
 // ✗ number[] is not Post[]
 ```

package/docs/inertia/rendering.md

@@ -11,7 +11,7 @@ routes, and how redirects behave.
 
 ## The inertia helper
 
-```ts
+```ts fragment
 function inertia(component: PageName, props?: RenderProps): Promise<void>;
 ```
 
@@ -20,7 +20,7 @@ Call `inertia()` from any controller action. It reads the active request from
 it sets `ctx.response` as a side effect. It is **async** (it resolves lazy/deferred props), so it
 returns `Promise<void>` — always `return inertia(...)` (or `await` it):
 
-```ts
+```ts fragment
 // app/controllers/PostController.ts
 import type { HttpContext } from "zerotal";
 import { inertia } from "@zerotal/inertia";
@@ -61,7 +61,7 @@ action.
 Props can be more than plain values. Wrap them to make them lazy, optional, deferred, or mergeable —
 the foundation for partial reloads, "load more" lists, and deferred content:
 
-```ts
+```ts fragment
 // in a controller
 import { inertia, optional, defer, merge } from "@zerotal/inertia";
 
@@ -130,7 +130,7 @@ variants separately. The page object always includes the current `url` and asset
 For pages that need no controller logic (marketing pages, static dashboards), render
 straight from the route with the `Router.inertia()` macro (added by the package):
 
-```ts
+```ts fragment
 // routes/web.ts
 import { Router } from "zerotal";
 
@@ -142,7 +142,7 @@ Router.inertia("/admin", "Admin/Dashboard", [AuthMiddleware]); // middleware sho
 The third argument is polymorphic: pass a **props object**, or pass a **middleware
 array** directly as a shorthand. To use both, pass props third and middleware fourth:
 
-```ts
+```ts fragment
 // routes/web.ts
 Router.inertia("/admin", "Admin/Dashboard", { title: "Admin" }, [AuthMiddleware]);
 ```
@@ -155,7 +155,7 @@ someone clicks, not when someone builds.
 
 Name the route instead, and let the URL be derived:
 
-```tsx
+```tsx fragment
 import { Link } from "@inertiajs/react";
 
 <Link href={route("posts.show", { slug: post.slug })}>{post.title}</Link>
@@ -174,7 +174,7 @@ A form's action is the same kind of string as a link's `href`, and gets the same
 treatment. `useForm()` and `router` both take a URL, so hand them one that was built
 from the route name:
 
-```tsx
+```tsx fragment
 import { useForm, router } from "@inertiajs/react";
 
 export default function Edit({ post }: Props) {
@@ -232,7 +232,7 @@ After a non-GET action (a form POST/PUT/DELETE), redirect as usual — return a
 [`InertiaMiddleware`](/docs/inertia/middleware) upgrades it to a **303** so the
 browser issues a GET on the target instead of replaying the form:
 
-```ts
+```ts fragment
 // in a controller
 async store(ctx: HttpContext): Promise<void> {
   const post = await Post.create(await ctx.body());
@@ -251,7 +251,7 @@ To send the browser to an external URL (or force a full-page visit), use `Inerti
 an Inertia request it returns a `409` + `X-Inertia-Location` so the client does a `window.location`
 visit; on a normal request it's a plain `302`:
 
-```ts
+```ts fragment
 // in a controller
 import { Inertia } from "@zerotal/inertia";
 

package/docs/inertia/ssr.md

@@ -60,7 +60,7 @@ streams the React output between the template's HTML prefix and suffix:
 
 Swap `inertia()` → `inertiaStream()` and `await` it — nothing else changes:
 
-```ts
+```ts fragment
 // app/controllers/PostController.ts
 import { inertiaStream } from "@zerotal/inertia";
 
@@ -83,7 +83,7 @@ traversal (`..` or a leading `/`).
 
 ### inertia vs. inertiaStream
 
-|                | `inertia()`            | `inertiaStream()`                  |
+| Criterion      | `inertia()`            | `inertiaStream()`                  |
 | -------------- | ---------------------- | ---------------------------------- |
 | Return type    | `Promise<void>`        | `Promise<void>`                    |
 | Rendering      | Buffered HTML string   | Streaming `renderToReadableStream` |

package/docs/lifecycle.md

@@ -244,7 +244,7 @@ the pipeline sets `ctx.response`), and `onResponseSent()` (after the response is
 sent). The full phase reference lives in
 [The Application](/docs/application) and [Service Providers](/docs/providers).
 
-```typescript
+```typescript fragment
 // app/providers/PaymentProvider.ts
 import { ServiceProvider } from "zerotal";
 
@@ -303,7 +303,7 @@ Boot and shutdown phases in order, and the per-request hook surface.
 `app.bootDurationMs` is the total. `app.providerReport` is the breakdown — one
 `ProviderReport` per provider, in boot order:
 
-```typescript
+```typescript fragment
 for (const { name, durationMs, bindings } of app.providerReport) {
   console.log(`${name} ${durationMs}ms, bound ${bindings.length}`);
 }