@zerotal/arch 1.7.4 → 1.8.0

package/docs/orm/lifecycle.md

@@ -47,7 +47,7 @@ query     →  hydrate row → afterFind
 Run async callbacks before or after any persistence event. Register them once at
 boot (typically in a service provider's `onBooting()`):
 
-```typescript
+```typescript fragment
 // in a ServiceProvider.onBooting()
 import { HookRegistry } from "@zerotal/orm";
 
@@ -76,7 +76,7 @@ HookRegistry.register(Order, "beforeUpdate", async (order) => {
 
 The signature is:
 
-```typescript
+```typescript fragment
 HookRegistry.register<T>(ModelClass: Function, hook: HookName, fn: (model: T) => Promise<void> | void): void
 ```
 
@@ -108,7 +108,7 @@ names follow the event-tense convention (`creating`/`created`, `updating`/
 `updated`, `saving`/`saved`, `deleting`/`deleted`, `retrieved`) — implement only
 the ones you need:
 
-```typescript
+```typescript fragment
 // app/observers/UserObserver.ts
 import type { ModelObserver } from "@zerotal/orm";
 
@@ -135,7 +135,7 @@ export class UserObserver implements ModelObserver<User> {
 
 Register the observer once at boot:
 
-```typescript
+```typescript fragment
 // in a ServiceProvider.onBooting()
 import { User } from "#app/models/User.ts";
 import { UserObserver } from "#app/observers/UserObserver.ts";
@@ -229,7 +229,7 @@ export class Subscription extends Model.using(State) {
 Register callbacks that fire after a successful transition. Call `onTransition` in
 a service provider's `onBooting()` so it runs once at startup:
 
-```typescript
+```typescript fragment
 // in a ServiceProvider.onBooting()
 // Specific state
 Post.onTransition("published", async (post, { from }) => {
@@ -245,7 +245,7 @@ Post.onTransition("*", async (post, { from, to }) => {
 
 ### Using transitions
 
-```typescript
+```typescript fragment
 // in a controller or service
 // Validates canTransitionTo, runs the guard, saves, then fires callbacks
 await post.transitionTo("review");
@@ -268,7 +268,7 @@ followed by any `"*"` wildcard callbacks.
 
 ### State machine in a controller
 
-```typescript
+```typescript fragment
 // app/controllers/PostController.ts
 import { StateError } from "@zerotal/orm";
 
@@ -295,7 +295,7 @@ observers — useful when consumers live in separate modules. See the
 [ORM index page](/docs/orm#bridging-model-events-to-the-app-event-bus) for the
 companion overview.
 
-```typescript
+```typescript fragment
 // app/events/PostEvents.ts
 export class PostCreated {
   constructor(public post: Post) {}
@@ -319,7 +319,7 @@ ORM runs standalone).
 
 Subscribe using the event bus anywhere in your application:
 
-```typescript
+```typescript fragment
 // in a ServiceProvider or listener module
 import { Events } from "zerotal";
 
@@ -336,7 +336,7 @@ queries.
 
 ### Implementing pruning
 
-```typescript
+```typescript fragment
 // app/models/AuditLog.ts
 @table("audit_logs")
 export class AuditLog extends Model {
@@ -354,7 +354,7 @@ export class AuditLog extends Model {
 }
 ```
 
-```typescript
+```typescript fragment
 // in a scheduled task or REPL
 const removed = await AuditLog.prune(); // default chunk size: 1000
 const fewer = await AuditLog.prune(500); // custom chunk size
@@ -362,7 +362,7 @@ const fewer = await AuditLog.prune(500); // custom chunk size
 
 The signature is:
 
-```typescript
+```typescript fragment
 static prune(chunkSize = 1000): Promise<number>
 ```
 
@@ -372,7 +372,7 @@ method throws.
 
 ### Scheduling pruning
 
-```typescript
+```typescript fragment
 // bootstrap/app.ts or a scheduler provider
 scheduler
   .job("prune-audit-logs", async () => {

package/docs/orm/queries.md

@@ -16,7 +16,7 @@ fluent API is available on `DB.table()` for unmodelled tables (see
 
 ## Basic finders
 
-```typescript
+```typescript fragment
 // in a controller or service
 // By primary key — returns null if not found
 const user = await User.find(1);
@@ -48,7 +48,7 @@ const admins = await User.query().where("role", "admin").get<User>();
 
 ## Create, update, delete
 
-```typescript
+```typescript fragment
 // in a controller or service
 // INSERT a single record
 const user = await User.create({ name: "Alice", email: "alice@example.com" });
@@ -81,7 +81,7 @@ export class Post extends Model.using(SoftDeletes) {
 }
 ```
 
-```typescript
+```typescript fragment
 // in a controller or service
 // Soft delete — sets deleted_at; row hidden from default queries
 await post.delete();
@@ -108,7 +108,7 @@ await Post.onlyTrashed().get();
 `upsert` inserts a row, or updates the named columns when a conflict on `conflictKeys`
 occurs:
 
-```typescript
+```typescript fragment
 function upsert(
   data: InsertPayload<T>,
   conflictKeys: (keyof T & string)[],
@@ -116,7 +116,7 @@ function upsert(
 ): Promise<void>;
 ```
 
-```typescript
+```typescript fragment
 // in a controller or service
 // Conflict on email → update name and role; omit updateCols to update every column
 await User.upsert(
@@ -132,7 +132,7 @@ await User.upsert(
 
 ## Convenience finders
 
-```typescript
+```typescript fragment
 // in a controller or service
 // Find or create — returns the existing or newly-created instance
 const user = await User.firstOrCreate(
@@ -161,7 +161,7 @@ const user = await User.findOrNew(1);
 
 ### Filtering
 
-```typescript
+```typescript fragment
 // in a controller or service
 Post.query()
   .where("status", "published")
@@ -184,7 +184,7 @@ Post.query()
 
 ### Selecting
 
-```typescript
+```typescript fragment
 // in a controller or service
 Post.query().select("id", "title", "slug").get();
 Post.query().selectRaw("COUNT(*) as total, MAX(score) as top").get();
@@ -193,14 +193,14 @@ Post.query().distinct().select("user_id").get();
 
 ### Ordering and limits
 
-```typescript
+```typescript fragment
 // in a controller or service
 Post.query().orderBy("published_at", "desc").orderBy("id", "asc").limit(10).offset(20).get();
 ```
 
 ### Joins
 
-```typescript
+```typescript fragment
 // in a controller or service
 // Inner join
 Post.query()
@@ -228,7 +228,7 @@ Post.query()
 
 ### Grouping and aggregates
 
-```typescript
+```typescript fragment
 // in a controller or service
 // Terminal aggregates — return a single value
 const total = await Post.query().where("status", "published").count();
@@ -250,7 +250,7 @@ await DB.table("posts")
 
 Load aggregate values alongside model instances without extra queries:
 
-```typescript
+```typescript fragment
 // in a controller or service
 const posts = await Post.query()
   .withCount("comments")
@@ -268,7 +268,7 @@ posts[0].commentsAvg_rating; // number | null
 
 ### Relation existence filtering
 
-```typescript
+```typescript fragment
 // in a controller or service
 // Posts that have at least one comment
 Post.query().has("comments").get();
@@ -299,7 +299,7 @@ Post.query()
 
 Build queries dynamically based on optional inputs without branching `if` statements:
 
-```typescript
+```typescript fragment
 // in a controller
 const posts = await Post.query()
   .when(ctx.query("status"), (q, status) => q.where("status", status))
@@ -314,7 +314,7 @@ making it easy to chain optional filters.
 
 ### Pessimistic locking
 
-```typescript
+```typescript fragment
 // in a controller or service
 // Exclusive write lock — SELECT … FOR UPDATE
 await DB.transaction(async (trx) => {
@@ -346,7 +346,7 @@ const post = await Post.query().where("id", postId).sharedLock().first();
 Classic page-number pagination. Best for small-to-medium tables where users jump to
 arbitrary pages:
 
-```typescript
+```typescript fragment
 // in a controller
 const page = await Post.query()
   .where("status", "published")
@@ -365,7 +365,7 @@ const page = await Post.query()
 Simple, performant pagination using the last-seen ID as a cursor. Stable against
 inserts/deletes between pages:
 
-```typescript
+```typescript fragment
 // in a controller
 const p1 = await Post.query().cursorPaginate({ limit: 20 });
 const p2 = await Post.query().cursorPaginate({ cursor: p1.nextCursor, limit: 20 });
@@ -379,7 +379,7 @@ const p2 = await Post.query().cursorPaginate({ cursor: p1.nextCursor, limit: 20
 Scales to any table size. Uses an indexed column value as the cursor instead of an
 offset. The best choice for infinite scroll and large datasets:
 
-```typescript
+```typescript fragment
 // in a controller
 const p1 = await Post.query()
   .where("status", "published")
@@ -409,7 +409,7 @@ ordering.
 
 Use these for large datasets to avoid loading thousands of rows into memory at once:
 
-```typescript
+```typescript fragment
 // in a console command or job
 // Process in fixed-size batches
 await Post.query().chunk(100, async (posts) => {
@@ -442,7 +442,7 @@ await Post.query().each(async (post) => {
 The builder compiles to SQL without executing, so you can inspect exactly what will
 run:
 
-```typescript
+```typescript fragment
 // in a controller or service
 // Compiled SQL with `?` placeholders (no bindings)
 const sql = Post.query().where("status", "published").toSql();
@@ -465,7 +465,7 @@ Post.query().where("active", 1).dump().get();
 
 Clone a base query to reuse it with different conditions:
 
-```typescript
+```typescript fragment
 // in a controller or service
 const base = Post.query().where("active", 1);
 const admins = await base.clone().where("role", "admin").get();
@@ -476,7 +476,7 @@ const editors = await base.clone().where("role", "editor").get();
 
 ### Loading and refreshing
 
-```typescript
+```typescript fragment
 // in a controller or service
 // Reload a fresh copy from the database (returns a new instance, doesn't mutate)
 const fresh = await post.fresh();
@@ -503,7 +503,7 @@ await post.loadMax("comments", "score");
 
 Know which fields have changed since the last database read or save:
 
-```typescript
+```typescript fragment
 // in a controller or service
 post.name = "Changed";
 
@@ -534,7 +534,7 @@ post.markDirty("slug");
 
 ### Incrementing and touch
 
-```typescript
+```typescript fragment
 // in a controller or service
 await post.increment("views"); // +1
 await post.increment("views", 5); // +5
@@ -546,7 +546,7 @@ await post.touch();
 
 ### Comparison and copying
 
-```typescript
+```typescript fragment
 // in a controller or service
 // True if both are the same model class with the same primary key
 post.is(otherPost); // boolean
@@ -563,7 +563,7 @@ const copy = post.replicate(["slug", "viewCount"]);
 
 ### Saving without updating timestamps
 
-```typescript
+```typescript fragment
 // in a controller or service
 await User.withoutTimestamps(async () => {
   user.role = "admin";
@@ -599,7 +599,7 @@ Apply them via `withScopes()`. The callback receives a proxy whose methods invok
 scope in turn — call them as separate statements (the proxy methods return `void`, so
 they do not chain):
 
-```typescript
+```typescript fragment
 // in a controller
 const posts = await Post.query()
   .withScopes((s) => {
@@ -616,7 +616,7 @@ const posts = await Post.query()
 Global scopes are applied automatically to every query on the model. Register them in
 a [service provider's](/docs/providers) `onBooting()`:
 
-```typescript
+```typescript fragment
 // in AppServiceProvider.onBooting()
 Post.addGlobalScope("tenant", (q) => q.where("tenant_id", currentTenantId()));
 

package/docs/orm/relationships.md

@@ -7,7 +7,7 @@ description: Define and query associations between models with relation decorato
 
 Relation decorators describe how your models connect — one-to-one, one-to-many, many-to-many, through, and polymorphic — so you can traverse and eager-load associated records without writing JOINs by hand.
 
-Zerotal's ORM supports all standard Active Record relationship types, plus polymorphic variants and eager loading with constraints. Relations are declared on the model class with decorators imported from `@zerotal/orm`; see [ORM](/docs/orm/index) for installing and configuring the package.
+Zerotal's ORM supports all standard Active Record relationship types, plus polymorphic variants and eager loading with constraints. Relations are declared on the model class with decorators imported from `@zerotal/orm`; see [ORM](/docs/orm) for installing and configuring the package.
 
 ## One-to-one — @hasOne / @belongsTo
 
@@ -35,7 +35,7 @@ export class Profile extends Model {
 }
 ```
 
-```typescript
+```typescript fragment
 // in a controller
 const user = await User.query().with("profile").findOrFail(1);
 const profile = user.profile; // Profile — no extra query
@@ -52,7 +52,7 @@ Both `@hasOne` and `@belongsTo` accept a `localKey` (defaults to `"id"`) to over
 
 A `User` has many `Post`s. The foreign key (`user_id`) lives on the `posts` table:
 
-```typescript
+```typescript fragment
 // app/models/User.ts
 @table("users")
 export class User extends Model {
@@ -69,7 +69,7 @@ export class Post extends Model {
 }
 ```
 
-```typescript
+```typescript fragment
 // in a controller
 const user = await User.query().with("posts").findOrFail(1);
 user.posts; // Post[]
@@ -84,7 +84,7 @@ const users = await User.query()
 
 Set or clear a `belongsTo` foreign key without having to know the parent's ID directly:
 
-```typescript
+```typescript fragment
 // in a controller
 post.associate("author", user); // sets post.userId = user.id
 await post.save();
@@ -121,7 +121,7 @@ export class Tag extends Model {
 
 ### Pivot operations
 
-```typescript
+```typescript fragment
 // in a controller
 // Attach one or multiple tags
 await post.tags.attach(tagId);
@@ -144,7 +144,7 @@ await post.tags.toggle(tagId);
 
 If the pivot table has additional columns, declare them with `withPivot`:
 
-```typescript
+```typescript fragment
 // app/models/User.ts
 @manyToMany(() => Role, {
   pivotTable: "user_roles",
@@ -155,7 +155,7 @@ If the pivot table has additional columns, declare them with `withPivot`:
 roles!: ManyToMany<Role>;
 ```
 
-```typescript
+```typescript fragment
 // in a controller — attach with extra pivot data
 await user.roles.attach(roleId, { assigned_by: adminId, assigned_at: new Date() });
 ```
@@ -166,7 +166,7 @@ await user.roles.attach(roleId, { assigned_by: adminId, assigned_at: new Date()
 
 Access distant models through an intermediate model. A `Country` has many `Post`s through `User`s:
 
-```typescript
+```typescript fragment
 // app/models/Country.ts
 import { hasManyThrough, hasOneThrough } from "@zerotal/orm";
 
@@ -188,7 +188,7 @@ export class Country extends Model {
 }
 ```
 
-```typescript
+```typescript fragment
 // in a controller
 const country = await Country.query().with("posts").findOrFail(1);
 country.posts; // Post[] — no manual JOIN required
@@ -202,7 +202,7 @@ Polymorphic relationships let a single model belong to multiple other models usi
 
 A `Comment` can belong to either a `Post` or a `Video`:
 
-```typescript
+```typescript fragment
 // app/models/Post.ts
 import {
   morphMany,
@@ -243,7 +243,7 @@ The `morphName` (`"commentable"`) determines the `commentable_type` and `comment
 
 > **Warning** — Renaming a `morphMap` key without migrating existing `*_type` rows will break every stored polymorphic association. Keep the keys stable — changing one requires a data migration.
 
-```typescript
+```typescript fragment
 // in a controller
 // Eager load polymorphic relations
 const posts = await Post.query().with("comments").get();
@@ -257,7 +257,7 @@ comment.commentable; // Post | Video
 
 Share a tagging system across multiple model types through a single `taggables` pivot:
 
-```typescript
+```typescript fragment
 // app/models/Post.ts
 import { morphToMany, morphedByMany, type ManyToMany } from "@zerotal/orm";
 
@@ -300,7 +300,7 @@ Always prefer eager loading over lazy loading in loops — it prevents N+1 queri
 
 > **Tip** — Reach for `.with()` whenever you access a relation across a collection; lazy-loading inside a loop fires one query per row.
 
-```typescript
+```typescript fragment
 // in a controller
 // Single relation
 const posts = await Post.query().with("author").get();
@@ -330,7 +330,7 @@ counted[0].commentsCount; // number
 
 When you already have a model instance and realise you need a relation:
 
-```typescript
+```typescript fragment
 // in a controller
 const post = await Post.findOrFail(1);
 
@@ -345,7 +345,7 @@ await post.loadMissing(["author"]);
 
 Filter a parent model based on whether its relation exists, without loading the related rows:
 
-```typescript
+```typescript fragment
 // in a controller
 // Posts that have at least one comment
 Post.query().has("comments").get();

package/docs/orm/serialization.md

@@ -11,7 +11,7 @@ Models serialize to plain JavaScript objects for API responses and `JSON.stringi
 
 Every `Model` has a `toJSON()` method. It returns a plain object you can pass straight to the `json()` response helper — and `JSON.stringify()` calls it for you automatically:
 
-```typescript
+```typescript fragment
 // in a controller
 import { json } from "zerotal";
 import { User } from "../models/User.ts";
@@ -56,7 +56,7 @@ user.toJSON();
 
 `visible` takes precedence over `hidden`. When set (non-empty), `toJSON()` includes **only** those keys:
 
-```typescript
+```typescript fragment
 // app/models/User.ts
 @table("users")
 export class User extends Model {
@@ -71,7 +71,7 @@ Use `visible` for models that have many internal columns and you want to be expl
 
 Include the result of a getter method in `toJSON()`. The getter runs at serialization time:
 
-```typescript
+```typescript fragment
 // app/models/User.ts
 @table("users")
 export class User extends Model {
@@ -97,7 +97,7 @@ user.toJSON();
 
 Adjust what a specific instance exposes without modifying the class definition. Each method mutates the instance and returns `this`, so they chain and can be passed straight to `json()`:
 
-```typescript
+```typescript fragment
 // in a controller
 // Temporarily hide additional fields for this response:
 json(user.makeHidden("email", "phone").toJSON());
@@ -124,7 +124,7 @@ json(user.makeHidden("password").makeVisible("phoneVerifiedAt").append("isVerifi
 - **Appended accessors included** — per `static appends` and any `append()` overrides.
 - **Loaded relations included** — nested models serialize via their own `toJSON()`.
 
-```typescript
+```typescript fragment
 // in a controller
 const post = await Post.query().with("author").findOrFail(1);
 
@@ -145,7 +145,7 @@ post.toJSON();
 
 When you have an array of models, call `toJSON()` on each item or rely on `JSON.stringify()`:
 
-```typescript
+```typescript fragment
 // in a controller
 const posts = await Post.query().where("status", "published").get();
 
@@ -160,7 +160,7 @@ json(posts);
 
 Hidden/visible lists apply per-model and do **not** propagate to nested relations. Each nested model serializes via its own class configuration:
 
-```typescript
+```typescript fragment
 // app/models/User.ts and app/models/Post.ts
 @table("users")
 export class User extends Model {
@@ -182,7 +182,7 @@ post.toJSON();
 
 For fine-grained, per-endpoint serialization, use API Resources instead of class-level `hidden`/`visible`. A `Resource` wraps a model in `this.resource` and lets you shape the output per route without touching the model class. By default the output is wrapped in a `{ data: ... }` envelope:
 
-```typescript
+```typescript fragment
 // app/resources/PostResource.ts
 import { Resource } from "zerotal/http";
 import type { Post } from "../models/Post.ts";
@@ -201,7 +201,7 @@ export class PostResource extends Resource<Post> {
 
 Build a single resource with `new PostResource(post)`, then `toJson()` for a plain object or `toResponse()` for a `Response`. Serialize a list with the static `collection()` helper, which takes the resource class first:
 
-```typescript
+```typescript fragment
 // in a controller
 import { json } from "zerotal";
 import { PostResource } from "../resources/PostResource.ts";
@@ -228,7 +228,7 @@ Use model-level `hidden`/`visible` for globally sensitive fields. Use Resources
 
 ## References
 
-`toJSON()` and the override methods live on every [`Model`](/docs/orm/index); the `Resource` helpers are exported from `zerotal`.
+`toJSON()` and the override methods live on every [`Model`](/docs/orm); the `Resource` helpers are exported from `zerotal`.
 
 | Member                  | Signature                                                          | Description                                                      |
 | ----------------------- | ------------------------------------------------------------------ | ---------------------------------------------------------------- |
@@ -245,7 +245,7 @@ Use model-level `hidden`/`visible` for globally sensitive fields. Use Resources
 
 ## Next steps
 
-- [ORM](/docs/orm/index) — model definition, casts, and configuration.
+- [ORM](/docs/orm) — model definition, casts, and configuration.
 - [ORM relationships](/docs/orm/relationships) — load the related models you serialize here.
 - [ORM casts](/docs/orm/casts) — control how column values appear in serialized output.
 - [Responses](/docs/responses) — the `json()` helper that calls `toJSON()`.

package/docs/package-development.md

@@ -86,7 +86,7 @@ Everything a consumer should import is re-exported from `index.ts`. Keep
 implementation files internal; export the manager, the provider, the config
 factory and its shape type, any facade, and the typed error vocabulary.
 
-```typescript
+```typescript fragment
 // packages/cache/src/index.ts
 export { CacheManager } from "./CacheManager.ts";
 export { CacheProvider } from "./provider/CacheProvider.ts";
@@ -106,7 +106,7 @@ The provider is the only thing the application boots. It binds your services int
 the container and registers any commands. It must live at `src/provider/` and
 declare both `static provides` and `static environments`.
 
-```typescript
+```typescript fragment
 // packages/cache/src/provider/CacheProvider.ts
 import { ServiceProvider } from "@zerotal/core";
 import type { AppEnvironment } from "@zerotal/core";
@@ -223,7 +223,7 @@ export function CacheConfig(options: Partial<CacheConfigShape> = {}): CacheConfi
 Register the namespace for **typed config dot-paths** by augmenting `ConfigRegistry`
 (the config analogue of `ContainerBindings`) at the bottom of `config.ts`:
 
-```typescript
+```typescript fragment
 // packages/cache/src/config.ts
 declare module "@zerotal/core" {
   interface ConfigRegistry {
@@ -291,7 +291,7 @@ import { createFacade } from "@zerotal/core";
 export const Cache = createFacade("cache");
 ```
 
-```typescript
+```typescript fragment
 function createFacade<K extends keyof ContainerBindings>(key: K): ContainerBindings[K];
 ```
 
@@ -309,7 +309,7 @@ consumers call `Router.flow(...)` as though it shipped with the router. Register
 it in `onRegister()` — that runs before route files load, so the method exists by
 the time an app calls it:
 
-```typescript
+```typescript fragment
 // packages/flow/src/FlowProvider.ts — inside onRegister():
 Router.macro("flow", flowRoute);
 ```
@@ -317,7 +317,7 @@ Router.macro("flow", flowRoute);
 The call is untyped on its own; augment the matching interface so consumers get
 completion and type-checking:
 
-```typescript
+```typescript fragment
 // packages/flow/src/types.ts
 declare module "@zerotal/core" {
   interface RouterMacros {
@@ -337,7 +337,7 @@ boot (the way `app/models` and `app/policies` do), contribute a **concern
 descriptor** from your provider's `onRegister()`. Core stays unaware of your
 package — discovery is push-based.
 
-```typescript
+```typescript fragment
 // packages/webhooks/src/provider/WebhooksProvider.ts
 import type { ConcernDescriptor } from "@zerotal/core";
 
@@ -375,7 +375,7 @@ declare it and `bun zt dev` runs it beside the server in its own tab. Otherwise
 every user of your package has to remember a second terminal, and there is no way
 for you to help them.
 
-```typescript
+```typescript fragment
 // packages/webhooks/src/provider/WebhooksProvider.ts
 import type { DevProcessDefinition } from "@zerotal/core";
 
@@ -427,7 +427,7 @@ user sees.
 `bun zt doctor` is what a developer (or an agent) runs to find out whether an app
 is wired correctly. Contribute the checks only your package can make:
 
-```typescript
+```typescript fragment
 // packages/webhooks/src/provider/WebhooksProvider.ts
 import type { DoctorCheck } from "@zerotal/core";
 
@@ -464,7 +464,7 @@ Every package must ship at least one `*.test.ts` file — the linter treats thei
 absence as a high-severity violation. Co-locate tests next to the code they cover
 (`CacheManager.test.ts` beside `CacheManager.ts`) and run them with `bun test`.
 
-```typescript
+```typescript fragment
 // packages/cache/src/config.test.ts
 import { test, expect } from "bun:test";
 import { CacheConfig } from "./config.ts";