@zerotal/arch 1.7.4 → 1.7.5

package/docs/pagination.md

@@ -25,13 +25,13 @@ carrying the rows plus the metadata, cursors, and URL helpers a UI needs.
 Pagination ships with `@zerotal/orm` as query-builder methods — nothing to
 install or register. Call them at the end of any query:
 
-```typescript
+```typescript fragment
 const page = await Post.query().latest().paginate();
 ```
 
 ## paginate — full numbered pages
 
-```typescript
+```typescript fragment
 // in a controller
 const page = await Post.query()
   .where("status", "published")
@@ -48,7 +48,7 @@ complete picture — at the cost of the extra count query. `perPage` defaults to
 omit `page` and it reads the request's current page (`?page=`, or the page a Flow
 component registered).
 
-```typescript
+```typescript fragment
 async paginate<T>(perPage?: number, page?: number): Promise<PaginateResult<T>>
 ```
 
@@ -77,7 +77,7 @@ interface PaginateResult<T> {
 
 ### URL & state helpers
 
-```typescript
+```typescript fragment
 // using a PaginateResult `page`
 page.hasMorePages; // boolean
 page.onFirstPage; // boolean
@@ -101,7 +101,7 @@ and extra query params, which are preserved across links so filters survive
 Skips the `COUNT` entirely by fetching `perPage + 1` rows to detect whether
 another page follows. Use it when you don't need a total or page numbers:
 
-```typescript
+```typescript fragment
 // in a controller
 const page = await Post.query().latest().simplePaginate(20);
 
@@ -111,7 +111,7 @@ page.nextPageUrl();
 page.onFirstPage;
 ```
 
-```typescript
+```typescript fragment
 async simplePaginate<T>(perPage?: number, page?: number): Promise<SimplePaginateResult<T>>
 ```
 
@@ -128,7 +128,7 @@ BY id ASC`, fetching `limit + 1` rows to detect a next page. It has **no
 `COUNT`** and stays fast no matter how deep you scroll — ideal for
 infinite-scroll feeds and very large tables:
 
-```typescript
+```typescript fragment
 // in a controller
 let result = await Post.query().cursorPaginate({ limit: 20 });
 
@@ -141,7 +141,7 @@ result.hasMore; // boolean
 const more = await Post.query().cursorPaginate({ cursor: result.nextCursor!, limit: 20 });
 ```
 
-```typescript
+```typescript fragment
 async cursorPaginate<T>(options?: { cursor?: number; limit?: number }): Promise<CursorPaginateResult<T>>
 ```
 
@@ -157,7 +157,7 @@ that encodes the last row's sort value so clients cannot interpret or tamper wit
 it. A secondary `id ASC` tiebreaker keeps page boundaries stable when the sort
 column isn't unique.
 
-```typescript
+```typescript fragment
 // in a controller
 // First page, newest first
 const p1 = await Post.query().keysetPaginate({ column: "created_at", direction: "desc" });
@@ -173,7 +173,7 @@ const p2 = await Post.query().keysetPaginate({
 });
 ```
 
-```typescript
+```typescript fragment
 async keysetPaginate<T>(options?: KeysetOptions): Promise<KeysetPaginateResult<T>>
 
 interface KeysetOptions {
@@ -213,7 +213,7 @@ Paginate _after_ applying filters and sorting, then pass the current filters to
 `links()` so they ride along on every page URL — without that, clicking "page 2" would
 silently drop the user's search:
 
-```typescript
+```typescript fragment
 // in a controller — GET /search?q=bun&page=2
 const q = http.query("q", "");
 
@@ -235,7 +235,7 @@ return view("search", {
 For a feed the client scrolls forever, return the rows plus the next cursor and nothing
 else — no count, no page numbers. The client sends the cursor back to fetch more:
 
-```typescript
+```typescript fragment
 // in a controller — GET /api/posts?cursor=128
 const result = await Post.query()
   .with("author")
@@ -258,7 +258,7 @@ live at the edges, so test the boundaries rather than the happy page.
 A `paginate()` result carries `data` plus the counts, so one call proves several
 things at once:
 
-```typescript
+```typescript fragment
 // tests/pagination/Posts.test.ts
 import { test, expect } from "bun:test";
 import { PostFactory } from "../../database/factories/PostFactory.ts";
@@ -280,7 +280,7 @@ test("reports the right totals on the last page", async () => {
 **The three cases worth pinning down** are the ones that produce a broken UI
 rather than an exception:
 
-```typescript
+```typescript fragment
 // tests/pagination/Posts.test.ts
 test("an empty result reports null bounds, not zero", async () => {
   const page = await Post.query().where("status", "nothing").paginate();

package/docs/password-reset.md

@@ -35,7 +35,7 @@ The broker reads and writes through your query functions, so it needs a table to
 back them. The default examples below use a `password_reset_tokens` table keyed by
 email:
 
-```typescript
+```typescript fragment
 // database/migrations/xxxx_create_password_reset_tokens.ts
 await Schema.create("password_reset_tokens", (table) => {
   table.string("email").primary();
@@ -54,7 +54,7 @@ Create the broker once and export it so controllers can import it. Pass an objec
 implementing `PasswordBrokerOptions` — each query function maps the broker onto your
 storage:
 
-```typescript
+```typescript fragment
 // app/auth/passwords.ts
 import { PasswordBroker, Hash } from "@zerotal/auth";
 import { Notify } from "@zerotal/notifications";
@@ -136,7 +136,7 @@ The controller wires the broker into request handlers: one pair for requesting a
 link, one pair for submitting the new password. Compare the broker result against the
 [`PASSWORDS` constants](#passwords-constants) rather than raw strings.
 
-```typescript
+```typescript fragment
 // app/controllers/PasswordResetController.ts
 import { broker } from "#app/auth/passwords.ts";
 import { Auth, PASSWORDS } from "@zerotal/auth";
@@ -199,7 +199,7 @@ export class PasswordResetController {
 
 ## Routes
 
-```typescript
+```typescript fragment
 // routes/web.ts
 import { GuestMiddleware } from "@zerotal/auth";
 import { PasswordResetController } from "#app/controllers/PasswordResetController.ts";
@@ -220,7 +220,7 @@ Expired rows accumulate because `reset()` only deletes a token when it's used or
 found expired on lookup. Call `broker.prune()` on a schedule to clear the rest — it
 delegates to your `pruneTokens` function with the cutoff date:
 
-```typescript
+```typescript fragment
 // app/schedules/PrunePasswordTokens.ts
 import { Schedule } from "@zerotal/scheduler";
 import { broker } from "#app/auth/passwords.ts";
@@ -292,7 +292,7 @@ earn a test: a wrong token, an expired one, and the replay above.
 On the HTTP side, the case worth pinning down is that a miss is indistinguishable
 from a hit:
 
-```typescript
+```typescript fragment
 // tests/http/password-reset.test.ts
 const res = await app.post("/forgot-password", { email: "nobody@example.com" });
 

package/docs/providers.md

@@ -53,7 +53,7 @@ import { ServiceProvider } from "zerotal";
 
 ## Anatomy of a provider
 
-```typescript
+```typescript fragment
 // app/providers/AppServiceProvider.ts
 import { ServiceProvider } from "zerotal";
 import { PaymentGateway } from "../services/PaymentGateway.ts";
@@ -107,7 +107,7 @@ one provider must be fully prepared before another even registers. There are als
 List providers in `bootstrap/providers.ts`. Order matters — a provider can
 only resolve bindings registered by providers that appear earlier in the list:
 
-```typescript
+```typescript fragment
 // bootstrap/providers.ts
 import { DatabaseProvider } from "@zerotal/orm";
 import { CacheProvider } from "@zerotal/cache";
@@ -157,7 +157,7 @@ type-checked and survives renames. It does two jobs at once:
 
 So an app that uses the admin panel only needs the panel itself:
 
-```typescript
+```typescript fragment
 // bootstrap/providers.ts — FlowProvider arrives via AdminProvider.dependsOn
 const providers = [AdminProvider];
 
@@ -180,7 +180,7 @@ defaults to `0`), then to registration order. It's a coarse knob — useful for
 framework-core provider that should generally boot ahead of everything else,
 without every other provider having to name it explicitly:
 
-```typescript
+```typescript fragment
 export class CoreProvider extends ServiceProvider {
   static priority = -100; // boots before ordinary (priority 0) providers
 }
@@ -214,7 +214,7 @@ is **synchronous** — no `await` — and runs before any binding is resolved, s
 treat it as pure wiring. The factory closures you pass don't run yet; they run
 _later_, when the binding is first resolved.
 
-```typescript
+```typescript fragment
 // inside a ServiceProvider
 onRegister(): void {
   // Singleton — one shared instance per app lifetime
@@ -243,7 +243,7 @@ booted. Reach for it only when one provider must finish preparing before the nex
 one even registers — most providers skip it entirely. It's async, so you can
 `await`:
 
-```typescript
+```typescript fragment
 // inside a ServiceProvider
 async onBooting(): Promise<void> {
   // e.g. open a connection pool that a provider listed after this one
@@ -259,7 +259,7 @@ By `onBooted()` every provider has registered, so this is the safe place to
 _resolve_ bindings (including from other providers), start background work, and
 register event listeners. It runs in parallel across all providers:
 
-```typescript
+```typescript fragment
 // inside a ServiceProvider
 async onBooted(): Promise<void> {
   // Resolve a binding from another provider
@@ -299,7 +299,7 @@ A provider can add its own auto-discovered directory by registering a concern de
 `onRegister()`/`onBooting()`. The framework scans the directory at boot and calls `register()`
 for each file's exports:
 
-```typescript
+```typescript fragment
 // inside a ServiceProvider
 onRegister(): void {
   this.app.registerConcern({
@@ -346,7 +346,7 @@ Second — and this is the part that actually defers it — register it with
 `app.defer()` instead of the normal providers array. `static provides` on its own
 is just metadata; it's `defer()` that wires the lazy boot:
 
-```typescript
+```typescript fragment
 // bootstrap/app.ts
 const app = Application.create({ providers });
 app.defer([SearchProvider]); // array form reads each provider's `static provides`
@@ -366,7 +366,7 @@ A provider runs in every runtime by default. Branch on `this.app.environment` to
 bind a different implementation per environment — a fake mailer under `test`, the
 real one everywhere else:
 
-```typescript
+```typescript fragment
 // inside a ServiceProvider
 onRegister(): void {
   if (this.app.environment === 'test') {
@@ -387,7 +387,7 @@ Providers can push middleware into the global pipeline via `this.app.useOnce()`
 the framework guarantees it's added exactly once, even if the same middleware is
 registered by several providers:
 
-```typescript
+```typescript fragment
 // inside a ServiceProvider
 onBooting(): Promise<void> {
   this.app.useOnce(SessionMiddleware);

package/docs/query-builder.md

@@ -53,7 +53,7 @@ just a description of a query until you `await` it.
 
 ## Selecting columns
 
-```typescript
+```typescript fragment
 // in a controller or service
 DB.table("posts").select("id", "title", "created_at");
 DB.table("posts").distinct().select("status");
@@ -65,7 +65,7 @@ so build it only from trusted constants.
 
 ## Where clauses
 
-```typescript
+```typescript fragment
 // in a controller or service
 DB.table("posts").where("status", "published"); // column = value
 DB.table("posts").where("views", ">", 1000); // explicit operator
@@ -106,7 +106,7 @@ parameterized.
 
 ## Joins
 
-```typescript
+```typescript fragment
 // in a controller or service
 DB.table("posts")
   .join("users", "posts.user_id", "=", "users.id")
@@ -122,7 +122,7 @@ alias, first, operator, second)`.
 
 ## Ordering, grouping, limits
 
-```typescript
+```typescript fragment
 // in a controller or service
 DB.table("posts").orderBy("created_at", "desc");
 DB.table("posts").orderByDesc("created_at"); // shorthand for the line above
@@ -145,7 +145,7 @@ clauses and optionally applies a fresh one.
 Apply clauses only when a condition is truthy — handy for optional filters without
 breaking the chain:
 
-```typescript
+```typescript fragment
 // in a controller or service
 DB.table("posts")
   .when(status, (q, value) => q.where("status", value))
@@ -157,7 +157,7 @@ The callback receives the builder and the (truthy) condition value.
 
 ## Retrieving results
 
-```typescript
+```typescript fragment
 // in a controller or service
 const rows = await DB.table("posts").where("status", "published").get();
 const row = await DB.table("posts").where("id", 1).first(); // first row or null
@@ -171,7 +171,7 @@ const has = await DB.table("posts").where("user_id", userId).exists(); // boolea
 
 Pass a row type to `get<T>()` / `first<T>()` for typed results:
 
-```typescript
+```typescript fragment
 // in a controller or service
 const rows = await DB.table("posts").get<{ id: number; title: string }>();
 ```
@@ -181,7 +181,7 @@ const rows = await DB.table("posts").get<{ id: number; title: string }>();
 
 ### Aggregates
 
-```typescript
+```typescript fragment
 // in a controller or service
 await DB.table("posts").count();
 await DB.table("posts").where("status", "published").sum("views");
@@ -197,7 +197,7 @@ For paged result sets, see [Pagination](/docs/pagination).
 For result sets too large to hold in memory, page through them instead of calling
 `get()`:
 
-```typescript
+```typescript fragment
 // in a command or job
 await DB.table("posts").chunk(500, async (rows, page) => {
   for (const row of rows) await archive(row);
@@ -215,7 +215,7 @@ for await (const row of DB.table("posts").lazy()) {
 
 ## Writing rows
 
-```typescript
+```typescript fragment
 // in a controller or service
 // INSERT
 await DB.table("post_tags").insert({ post_id: 1, tag_id: 3 });
@@ -242,7 +242,7 @@ one if none exists; it returns `true` when a row was inserted.
 
 Inside a [transaction](/docs/database#transactions), lock the selected rows:
 
-```typescript
+```typescript fragment
 // in a controller or service
 await DB.transaction(async (trx) => {
   const row = await trx.table("accounts").where("id", 1).lockForUpdate().first();
@@ -260,7 +260,7 @@ await DB.transaction(async (trx) => {
 
 ## Debugging
 
-```typescript
+```typescript fragment
 // in a controller or service
 DB.table("posts").where("status", "published").toSql(); // SQL with ? placeholders
 DB.table("posts").where("status", "published").toRawSql(); // values inlined (logging only)
@@ -282,7 +282,7 @@ The bread and butter of any index page or list endpoint. `when()` lets every fil
 be optional without a tangle of `if` statements, and `paginate()` returns the rows
 plus the page metadata in one call:
 
-```typescript
+```typescript fragment
 // in a controller — req.query holds the optional filters
 const posts = await DB.table("posts")
   .when(req.query.status, (q, status) => q.where("status", status))
@@ -301,7 +301,7 @@ For join tables and key/value rows, `updateOrInsert` avoids the "check then inse
 race — it updates the row matching the first argument, or inserts the two merged if
 none exists:
 
-```typescript
+```typescript fragment
 await DB.table("user_settings").updateOrInsert(
   { user_id: userId, key: "theme" }, // how to find the row
   { value: "dark" }, // what to set
@@ -313,7 +313,7 @@ await DB.table("user_settings").updateOrInsert(
 When you only need numbers, skip model hydration entirely and let the database do the
 aggregation:
 
-```typescript
+```typescript fragment
 const byAuthor = await DB.table("posts")
   .select("user_id")
   .selectRaw("COUNT(*) AS post_count")
@@ -329,7 +329,7 @@ const byAuthor = await DB.table("posts")
 Never load a big table with `get()`. Page through it with `chunkById`, which walks an
 incrementing key so concurrent inserts or deletes can't make it skip or repeat rows:
 
-```typescript
+```typescript fragment
 // in a command or job
 await DB.table("posts")
   .whereNull("slug")
@@ -347,7 +347,7 @@ await DB.table("posts")
 When exactly one row should match — looking a user up by email, say — `sole()` turns
 "zero or many matches" into a thrown error instead of a silent bug:
 
-```typescript
+```typescript fragment
 const user = await DB.table("users").where("email", email).sole();
 ```
 
@@ -383,7 +383,7 @@ silently dropped by a mis-chained `orWhere` — without needing rows to prove it
 **Assert the rows when the result is the point.** Arrange with factories and run
 the query for real:
 
-```typescript
+```typescript fragment
 // tests/queries/ActiveSubscribers.test.ts
 test("excludes users still in trial", async () => {
   await UserFactory.create({ status: "active", trialEndsAt: null });

package/docs/queue.md

@@ -56,7 +56,9 @@ import { QueueConfig } from "@zerotal/queue";
 import { env } from "zerotal";
 
 export default QueueConfig({
-  driver: env("QUEUE_DRIVER", "sqlite"),
+  // One of 'sqlite' | 'redis' | 'sync', written literally: the field is that union
+  // and `env()` returns a plain string.
+  driver: "sqlite",
   pollInterval: env("QUEUE_POLL_INTERVAL", 500),
   queues: ["default"],
   workers: env("QUEUE_WORKERS", 0),
@@ -81,7 +83,7 @@ A job is a class that extends `Job` and implements `handle()`. Constructor
 arguments are the job's state — serialise them in `payload()` and restore them in
 a static `fromPayload()`:
 
-```typescript
+```typescript fragment
 // app/jobs/NotifyFollowersJob.ts
 import { Job, JobRegistry } from "@zerotal/queue";
 
@@ -126,7 +128,7 @@ JobRegistry.register(NotifyFollowersJob as never);
 
 A job with no constructor state needs only `handle()` plus the registration line:
 
-```typescript
+```typescript fragment
 // app/jobs/PruneDeletedContentJob.ts
 import { Job, JobRegistry } from "@zerotal/queue";
 
@@ -164,7 +166,7 @@ the `JobRegistry.register(...)` line — keep it at the bottom of each job file.
 
 ## Dispatching jobs
 
-```typescript
+```typescript fragment
 // in a controller
 import { Queue } from "@zerotal/queue";
 
@@ -183,7 +185,7 @@ worker loop, not the web request.
 
 A document saved eight times in a minute should rebuild its search index once, and the only rebuild anyone sees is the last one. Set `debounce` to a number of seconds and repeated dispatches collapse into a single run:
 
-```typescript
+```typescript fragment
 export class ReindexDocument extends Job {
   /** Run 30s after the last dispatch, not once per dispatch. */
   override readonly debounce = 30;
@@ -202,7 +204,7 @@ export class ReindexDocument extends Job {
 }
 ```
 
-```typescript
+```typescript fragment
 // Eight saves in quick succession…
 for (const _ of edits) await Queue.dispatch(new ReindexDocument(doc.id));
 // …one job, running 30s after the last one.
@@ -220,7 +222,7 @@ By default, the class name plus the serialised payload. So `ReindexDocument(1)`
 
 Override `debounceKey()` when two payloads mean the same work. A job carrying a timestamp or a request id is unique on every dispatch and would otherwise never collapse with anything:
 
-```typescript
+```typescript fragment
 export class ReindexDocument extends Job {
   override readonly debounce = 30;
 
@@ -258,7 +260,7 @@ This is the behaviour you want for the reindex case: a save that lands while the
 Batch a set of jobs and react when they all finish. Batching uses the
 `zerotal_job_batches` table (auto-created by `SqliteDriver`).
 
-```typescript
+```typescript fragment
 // in a controller
 import { Bus } from "@zerotal/queue";
 
@@ -283,7 +285,7 @@ const batch = await Bus.batch(rows.map((row) => new ImportCsvRowJob(row)))
 
 `Bus.batch(...).dispatch()` resolves to a `Batch` instance:
 
-```typescript
+```typescript fragment
 // after .dispatch()
 batch.id; // UUID string
 batch.name; // label from .name()
@@ -304,7 +306,7 @@ batch.progress(); // 0.0 → 1.0
 Run jobs sequentially: each job dispatches the next one only after it succeeds. If
 any job fails, the rest of the chain is abandoned.
 
-```typescript
+```typescript fragment
 // in a controller
 import { Bus } from "@zerotal/queue";
 
@@ -437,7 +439,7 @@ which stops every thread. Any in-flight or queued work is resolved with
 `QueueFake` swaps the `queue` binding for a fake that captures dispatched jobs
 instead of running them, so you can assert on them:
 
-```typescript
+```typescript fragment
 // in a test
 import { QueueFake } from "@zerotal/queue";
 
@@ -530,7 +532,7 @@ while leaving unrelated failures alone.
 | `QueueShuttingDownError`        | `E_QUEUE_SHUTTING_DOWN`        | Dispatching during a graceful shutdown — the manager is draining. |
 | `QueueBatchingUnsupportedError` | `E_QUEUE_BATCHING_UNSUPPORTED` | Using batches on a driver that has no batch support.              |
 
-```typescript
+```typescript fragment
 // in a controller or service
 import { QueueError, QueueShuttingDownError } from "@zerotal/queue";
 

package/docs/rate-limiting.md

@@ -38,7 +38,7 @@ import { ThrottleMiddleware } from "zerotal";
 Attach it directly with the static `.with(options)` factory, which returns a
 ready-to-use middleware class:
 
-```typescript
+```typescript fragment
 // in routes/web.ts (or wherever you register routes)
 import { ThrottleMiddleware } from "zerotal";
 
@@ -117,7 +117,7 @@ is the client IP.
 `RateLimiter.middleware(name)` returns the middleware instance for a registered
 limiter, ready to drop into a route or group:
 
-```typescript
+```typescript fragment
 // in routes/web.ts
 import { RateLimiter } from "zerotal";
 
@@ -133,7 +133,7 @@ Router.group({ prefix: "/api", middleware: [RateLimiter.middleware("api")] }, ()
 Check or clear a limiter imperatively — e.g. reset failed-login counts after a
 successful sign-in:
 
-```typescript
+```typescript fragment
 // in a controller
 import { RateLimiter } from "zerotal";
 
@@ -171,7 +171,7 @@ line for CLI requests.
 Set your suite up once as described in [Testing](/docs/testing). A rate limiter
 is only proven by the request that gets refused, so the test has to exhaust it.
 
-```typescript
+```typescript fragment
 // tests/http/throttle.test.ts
 import { test, expect } from "bun:test";
 import { createApp } from "../helpers.ts";
@@ -196,7 +196,7 @@ test("the sixth attempt in a minute is refused", async () => {
 reads to back off. A limiter that returns `429` without them still fails the
 clients it was meant to protect you from:
 
-```typescript
+```typescript fragment
 // tests/http/throttle.test.ts
 blocked.assertHeader("X-RateLimit-Limit", "5");
 blocked.assertHeader("X-RateLimit-Remaining", "0");
@@ -206,7 +206,7 @@ blocked.assertHeader("X-RateLimit-Remaining", "0");
 next in the same window. Give each test a distinct key — a different route, IP
 header, or user — rather than relying on ordering:
 
-```typescript
+```typescript fragment
 // tests/http/throttle.test.ts
 await app.post("/login", { email: "a@b.c" }, { "X-Forwarded-For": "10.0.0.7" });
 ```