@zerotal/arch 1.7.0

package/docs/orm/relationships.md

@@ -0,0 +1,440 @@
+---
+title: Relationships
+description: Define and query associations between models with relation decorators and eager loading.
+---
+
+# Relationships
+
+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.
+
+## One-to-one — @hasOne / @belongsTo
+
+A `User` has one `Profile`. The foreign key (`user_id`) lives on the `profiles` table:
+
+```typescript
+// app/models/User.ts
+import { Model, column, table, hasOne, belongsTo } from "@zerotal/orm";
+
+@table("users")
+export class User extends Model {
+  @column("string") name!: string;
+
+  @hasOne(() => Profile, { foreignKey: "user_id" })
+  profile!: Profile;
+}
+
+@table("profiles")
+export class Profile extends Model {
+  @column("integer") userId!: number;
+  @column("text") bio!: string;
+
+  @belongsTo(() => User, { foreignKey: "userId" })
+  user!: User;
+}
+```
+
+```typescript
+// in a controller
+const user = await User.query().with("profile").findOrFail(1);
+const profile = user.profile; // Profile — no extra query
+
+// Access the inverse
+const found = await Profile.findOrFail(1);
+await found.load(["user"]);
+console.log(found.user.name);
+```
+
+Both `@hasOne` and `@belongsTo` accept a `localKey` (defaults to `"id"`) to override the key the foreign key references.
+
+## One-to-many — @hasMany / @belongsTo
+
+A `User` has many `Post`s. The foreign key (`user_id`) lives on the `posts` table:
+
+```typescript
+// app/models/User.ts
+@table("users")
+export class User extends Model {
+  @hasMany(() => Post, { foreignKey: "user_id" })
+  posts!: Post[];
+}
+
+@table("posts")
+export class Post extends Model {
+  @column("integer") userId!: number;
+
+  @belongsTo(() => User, { foreignKey: "userId" })
+  author!: User;
+}
+```
+
+```typescript
+// in a controller
+const user = await User.query().with("posts").findOrFail(1);
+user.posts; // Post[]
+
+// Constrained eager load
+const users = await User.query()
+  .with("posts", (q) => q.where("status", "published").orderBy("created_at", "desc"))
+  .get();
+```
+
+## associate / dissociate
+
+Set or clear a `belongsTo` foreign key without having to know the parent's ID directly:
+
+```typescript
+// in a controller
+post.associate("author", user); // sets post.userId = user.id
+await post.save();
+
+post.dissociate("author"); // sets post.userId = null
+await post.save();
+```
+
+> **Note** — `@belongsTo` also accepts `withDefault` (a boolean, an attributes object, or a callback) to return an unsaved default related model instead of `null` when the association is absent.
+
+## Many-to-many — @manyToMany
+
+A `Post` belongs to many `Tag`s through a `post_tags` pivot table:
+
+```typescript
+// app/models/Post.ts
+import { Model, column, table, manyToMany, type ManyToMany } from "@zerotal/orm";
+
+@table("posts")
+export class Post extends Model {
+  @manyToMany(() => Tag, {
+    pivotTable: "post_tags",
+    pivotForeignKey: "post_id", // FK pointing to Post
+    pivotRelatedKey: "tag_id", // FK pointing to Tag
+  })
+  tags!: ManyToMany<Tag>;
+}
+
+@table("tags")
+export class Tag extends Model {
+  @column("string") name!: string;
+}
+```
+
+### Pivot operations
+
+```typescript
+// in a controller
+// Attach one or multiple tags
+await post.tags.attach(tagId);
+await post.tags.attach([1, 2, 3]);
+
+// Detach specific tags
+await post.tags.detach(tagId);
+
+// Detach all tags
+await post.tags.detach();
+
+// Sync — replaces all pivot rows with the given set
+await post.tags.sync([1, 2, 3]);
+
+// Toggle — attach if not present, detach if already present
+await post.tags.toggle(tagId);
+```
+
+### Extra pivot columns
+
+If the pivot table has additional columns, declare them with `withPivot`:
+
+```typescript
+// app/models/User.ts
+@manyToMany(() => Role, {
+  pivotTable: "user_roles",
+  pivotForeignKey: "user_id",
+  pivotRelatedKey: "role_id",
+  withPivot: ["assigned_at", "assigned_by"],
+})
+roles!: ManyToMany<Role>;
+```
+
+```typescript
+// in a controller — attach with extra pivot data
+await user.roles.attach(roleId, { assigned_by: adminId, assigned_at: new Date() });
+```
+
+> **Tip** — Pass `withTimestamps: true` to keep `created_at` / `updated_at` maintained on the pivot table during `attach` and `sync`.
+
+## Through relationships — @hasManyThrough / @hasOneThrough
+
+Access distant models through an intermediate model. A `Country` has many `Post`s through `User`s:
+
+```typescript
+// app/models/Country.ts
+import { hasManyThrough, hasOneThrough } from "@zerotal/orm";
+
+@table("countries")
+export class Country extends Model {
+  // Country → User (firstKey: FK on users that points to countries)
+  // User    → Post (secondKey: FK on posts that points to users)
+  @hasManyThrough(() => Post, () => User, {
+    firstKey: "country_id", // users.country_id
+    secondKey: "user_id", // posts.user_id
+  })
+  posts!: Post[];
+
+  @hasOneThrough(() => Post, () => User, {
+    firstKey: "country_id",
+    secondKey: "user_id",
+  })
+  latestPost!: Post;
+}
+```
+
+```typescript
+// in a controller
+const country = await Country.query().with("posts").findOrFail(1);
+country.posts; // Post[] — no manual JOIN required
+```
+
+## Polymorphic relationships
+
+Polymorphic relationships let a single model belong to multiple other models using a type+id pair.
+
+### @morphMany / @morphOne / @morphTo
+
+A `Comment` can belong to either a `Post` or a `Video`:
+
+```typescript
+// app/models/Post.ts
+import {
+  morphMany,
+  morphOne,
+  morphTo,
+  type MorphMany,
+  type MorphOne,
+  type MorphTo,
+} from "@zerotal/orm";
+
+// Parent side — Post has many Comments (polymorphic)
+@table("posts")
+export class Post extends Model {
+  @morphMany(() => Comment, { morphName: "commentable" })
+  declare comments: MorphMany<Comment>;
+
+  @morphOne(() => Image, { morphName: "imageable" })
+  declare image: MorphOne<Image>;
+}
+
+// Owning side — Comment stores commentable_type + commentable_id
+@table("comments")
+export class Comment extends Model {
+  @column("string") declare commentableType: string;
+  @column("integer") declare commentableId: number;
+
+  @morphTo({
+    morphMap: {
+      Post: () => Post,
+      Video: () => Video,
+    },
+  })
+  declare commentable: MorphTo<Post | Video>;
+}
+```
+
+The `morphName` (`"commentable"`) determines the `commentable_type` and `commentable_id` columns. For `@morphTo`, the `morphMap` keys are stored in the `*_type` column; by default the column names derive from the property name (`commentable` → `commentable_type` / `commentable_id`), and you can override them with `morphTypeColumn` / `morphForeignKey`.
+
+> **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
+// in a controller
+// Eager load polymorphic relations
+const posts = await Post.query().with("comments").get();
+posts[0].comments; // Comment[]
+
+const comment = await Comment.query().with("commentable").findOrFail(1);
+comment.commentable; // Post | Video
+```
+
+### @morphToMany / @morphedByMany — polymorphic many-to-many
+
+Share a tagging system across multiple model types through a single `taggables` pivot:
+
+```typescript
+// app/models/Post.ts
+import { morphToMany, morphedByMany, type ManyToMany } from "@zerotal/orm";
+
+// Post can be tagged
+@table("posts")
+export class Post extends Model {
+  @morphToMany(() => Tag, { morphName: "taggable", relatedPivotKey: "tag_id" })
+  tags!: ManyToMany<Tag>;
+}
+
+// Video can also be tagged using the same tags table
+@table("videos")
+export class Video extends Model {
+  @morphToMany(() => Tag, { morphName: "taggable", relatedPivotKey: "tag_id" })
+  tags!: ManyToMany<Tag>;
+}
+
+// Inverse — Tag can retrieve all Posts tagged with it
+@table("tags")
+export class Tag extends Model {
+  @morphedByMany(() => Post, { morphName: "taggable", parentPivotKey: "tag_id" })
+  posts!: ManyToMany<Post>;
+}
+```
+
+The pivot table name defaults to `{morphName}s` (here `taggables`). Its schema:
+
+```sql
+-- migration: create the taggables pivot
+CREATE TABLE taggables (
+  tag_id         INTEGER NOT NULL,
+  taggable_id    INTEGER NOT NULL,
+  taggable_type  TEXT    NOT NULL
+);
+```
+
+## Eager loading
+
+Always prefer eager loading over lazy loading in loops — it prevents N+1 queries.
+
+> **Tip** — Reach for `.with()` whenever you access a relation across a collection; lazy-loading inside a loop fires one query per row.
+
+```typescript
+// in a controller
+// Single relation
+const posts = await Post.query().with("author").get();
+posts[0].author; // User — no extra query
+
+// Multiple relations
+const withBoth = await Post.query().with("author").with("comments").get();
+
+// Nested relations (dot notation)
+const nested = await Post.query().with("author.profile").get();
+nested[0].author.profile; // Profile
+
+// With constraints — only load approved comments
+const filtered = await Post.query()
+  .with("comments", (q) => q.where("approved", true).orderBy("created_at"))
+  .get();
+
+// Load count alongside models (no separate query)
+const counted = await Post.query().withCount("comments").get<Post & { commentsCount: number }>();
+
+counted[0].commentsCount; // number
+```
+
+> **Note** — `withCount("comments")` exposes the count as the camel-cased `commentsCount` property on each result (the underlying `comments_count` SQL alias is converted for you).
+
+### Lazy eager loading on existing instances
+
+When you already have a model instance and realise you need a relation:
+
+```typescript
+// in a controller
+const post = await Post.findOrFail(1);
+
+// Load a relation that wasn't included in the original query
+await post.load(["author", "comments"]);
+
+// Load only if not already loaded (avoids redundant queries)
+await post.loadMissing(["author"]);
+```
+
+## Relation existence filtering
+
+Filter a parent model based on whether its relation exists, without loading the related rows:
+
+```typescript
+// in a controller
+// Posts that have at least one comment
+Post.query().has("comments").get();
+
+// Posts with 3 or more comments
+Post.query().has("comments", ">=", 3).get();
+
+// Posts with no comments at all
+Post.query().doesntHave("comments").get();
+
+// Posts with at least one approved comment
+Post.query()
+  .whereHas("comments", (q) => q.where("approved", true))
+  .get();
+
+// Posts without any approved comment
+Post.query()
+  .whereDoesntHave("comments", (q) => q.where("approved", true))
+  .get();
+
+// Filter by relation AND eager-load with the same constraint in one pass
+Post.query()
+  .withWhereHas("comments", (q) => q.where("approved", true))
+  .get();
+```
+
+> **Warning** — `has()` / `whereHas()` are not supported for `morphTo` relations — the related table isn't known until each row's `*_type` is read. Use eager loading via `with()` for those instead.
+
+## Choosing the right relationship type
+
+Reach for the decorator that matches the shape of your data:
+
+| Scenario                             | Decorator                                             |
+| ------------------------------------ | ----------------------------------------------------- |
+| User has one Profile                 | `@hasOne` on User, `@belongsTo` on Profile            |
+| User has many Posts                  | `@hasMany` on User, `@belongsTo` on Post              |
+| Post belongs to many Tags            | `@manyToMany` on both                                 |
+| Country → User → Post                | `@hasManyThrough` on Country                          |
+| Comment belongs to Post **or** Video | `@morphTo` on Comment, `@morphMany` on each parent    |
+| Tag applies to Post **and** Video    | `@morphToMany` on each model, `@morphedByMany` on Tag |
+
+The rule of thumb: put `@belongsTo` on whichever side stores the foreign-key column, and the matching `@hasOne` / `@hasMany` on the other. Use a polymorphic variant only when one side must point at more than one parent type.
+
+## References
+
+Relation decorators — imported from `@zerotal/orm`, applied to a model property.
+
+| Decorator         | Signature                                                                                                                    | Description                                            |
+| ----------------- | ---------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
+| `@hasOne`         | `hasOne(related, { foreignKey, localKey? })`                                                                                 | One related record; FK lives on the related table.     |
+| `@hasMany`        | `hasMany(related, { foreignKey, localKey? })`                                                                                | Many related records; FK lives on the related table.   |
+| `@belongsTo`      | `belongsTo(related, { foreignKey, localKey?, withDefault? })`                                                                | Inverse of has-one/has-many; FK lives on this model.   |
+| `@manyToMany`     | `manyToMany(related, { pivotTable, pivotForeignKey, pivotRelatedKey, localKey?, relatedKey?, withPivot?, withTimestamps? })` | Many-to-many through a pivot table.                    |
+| `@hasManyThrough` | `hasManyThrough(related, through, { firstKey, secondKey, localKey?, throughLocalKey? })`                                     | Many records across an intermediate model.             |
+| `@hasOneThrough`  | `hasOneThrough(related, through, { firstKey, secondKey, localKey?, throughLocalKey? })`                                      | Single record across an intermediate model.            |
+| `@morphMany`      | `morphMany(related, { morphName, localKey? })`                                                                               | Polymorphic one-to-many (parent side).                 |
+| `@morphOne`       | `morphOne(related, { morphName, localKey? })`                                                                                | Polymorphic one-to-one (parent side).                  |
+| `@morphTo`        | `morphTo({ morphMap, morphTypeColumn?, morphForeignKey? })`                                                                  | Owning side; resolves the parent via the `*_type` map. |
+| `@morphToMany`    | `morphToMany(related, { morphName, relatedPivotKey, pivotTable?, withPivot?, withTimestamps? })`                             | Polymorphic many-to-many (owning side).                |
+| `@morphedByMany`  | `morphedByMany(related, { morphName, parentPivotKey, pivotTable?, withPivot?, withTimestamps? })`                            | Polymorphic many-to-many (inverse side).               |
+
+Query and instance methods used with relations.
+
+| Method            | Signature                                                         | Description                                                            |
+| ----------------- | ----------------------------------------------------------------- | ---------------------------------------------------------------------- |
+| `with`            | `with(relation, constraint?)` / `with(relations[])` / `with(map)` | Eager-load a relation (dot notation for nesting; optional constraint). |
+| `withCount`       | `withCount(relation \| map)`                                      | Add a `<relation>Count` subquery column to each result.                |
+| `has`             | `has(relation, operator?, count?)`                                | Keep parents that have the relation (optionally count-filtered).       |
+| `doesntHave`      | `doesntHave(relation, callback?)`                                 | Keep parents that lack the relation.                                   |
+| `whereHas`        | `whereHas(relation, callback?)`                                   | Keep parents whose relation matches a constraint.                      |
+| `whereDoesntHave` | `whereDoesntHave(relation, callback?)`                            | Keep parents whose relation does not match a constraint.               |
+| `withWhereHas`    | `withWhereHas(relation, callback?)`                               | Filter by the relation and eager-load it with the same constraint.     |
+| `associate`       | `associate(relation, model): this`                                | Set a `belongsTo` foreign key from a related model instance.           |
+| `dissociate`      | `dissociate(relation): this`                                      | Clear a `belongsTo` foreign key (sets it to `null`).                   |
+| `load`            | `load(relations[]): Promise<this>`                                | Lazy-load relations onto an existing instance.                         |
+| `loadMissing`     | `loadMissing(relations[]): Promise<this>`                         | Load relations only if not already loaded.                             |
+
+Pivot collection methods on a `ManyToMany<T>` relation.
+
+| Method   | Signature                                       | Description                                           |
+| -------- | ----------------------------------------------- | ----------------------------------------------------- |
+| `attach` | `attach(id \| id[], pivotData?): Promise<void>` | Insert pivot rows, optionally with extra column data. |
+| `detach` | `detach(id?\| id[]): Promise<void>`             | Delete pivot rows; omit the id to detach all.         |
+| `sync`   | `sync(ids[]): Promise<void>`                    | Replace all pivot rows with the given set.            |
+| `toggle` | `toggle(id \| id[]): Promise<void>`             | Attach missing ids and detach present ones.           |
+
+## Next steps
+
+- [ORM queries](/docs/orm/queries) — eager loading, `whereHas`, and aggregates in depth.
+- [ORM serialization](/docs/orm/serialization) — control how related models appear in JSON.
+- [ORM lifecycle](/docs/orm/lifecycle) — react to changes on related records.
+- [Migrations](/docs/migrations) — create the pivot and foreign-key columns these relations need.

package/docs/orm/serialization.md

@@ -0,0 +1,251 @@
+---
+title: ORM Serialization
+description: Control exactly which model fields reach your JSON API responses.
+---
+
+# Serialization
+
+Models serialize to plain JavaScript objects for API responses and `JSON.stringify()`. You control what gets exposed with `hidden`, `visible`, and `appends`, and can customize the output further with per-instance overrides.
+
+## Basic usage
+
+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
+// in a controller
+import { json } from "zerotal";
+import { User } from "../models/User.ts";
+
+const user = await User.findOrFail(1);
+json(user.toJSON());
+// { id: 1, name: "Alice", email: "alice@example.com", createdAt: "…" }
+```
+
+## Class-level configuration
+
+Three static properties on the model class shape `toJSON()` for every instance: `hidden`, `visible`, and `appends`.
+
+### static hidden — exclude fields
+
+Fields in `hidden` are stripped from `toJSON()` output. Use this to prevent sensitive data from leaking into API responses:
+
+```typescript
+// app/models/User.ts
+import { Model, table, column } from "@zerotal/orm";
+
+@table("users")
+export class User extends Model {
+  static hidden = ["password", "rememberToken", "twoFactorSecret"];
+
+  @column("string") name!: string;
+  @column("string") email!: string;
+  @column("string") password!: string;
+  @column("string") rememberToken?: string;
+  @column("string") twoFactorSecret?: string;
+}
+
+const user = await User.findOrFail(1);
+user.toJSON();
+// { id: 1, name: "Alice", email: "alice@example.com", ... }
+// password, rememberToken, twoFactorSecret are absent
+```
+
+> **Danger** — Password hashes and tokens leak into every API response unless the column is listed in `hidden` (or excluded via `visible`).
+
+### static visible — allowlist fields
+
+`visible` takes precedence over `hidden`. When set (non-empty), `toJSON()` includes **only** those keys:
+
+```typescript
+// app/models/User.ts
+@table("users")
+export class User extends Model {
+  // Only these fields appear in JSON — everything else is excluded:
+  static visible = ["id", "name", "email", "avatarUrl"];
+}
+```
+
+Use `visible` for models that have many internal columns and you want to be explicit about what's safe to expose, rather than listing everything you want to hide.
+
+### static appends — computed accessors
+
+Include the result of a getter method in `toJSON()`. The getter runs at serialization time:
+
+```typescript
+// app/models/User.ts
+@table("users")
+export class User extends Model {
+  @column("string") firstName!: string;
+  @column("string") lastName!: string;
+
+  static appends = ["fullName", "avatarUrl"];
+
+  get fullName(): string {
+    return `${this.firstName} ${this.lastName}`;
+  }
+
+  get avatarUrl(): string {
+    return `https://cdn.example.com/avatars/${this.id}.jpg`;
+  }
+}
+
+user.toJSON();
+// { id: 1, firstName: "Alice", lastName: "Smith", fullName: "Alice Smith", avatarUrl: "https://…" }
+```
+
+## Per-instance overrides
+
+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
+// in a controller
+// Temporarily hide additional fields for this response:
+json(user.makeHidden("email", "phone").toJSON());
+
+// Reveal a field that the class hides (e.g. in an admin context):
+json(user.makeVisible("twoFactorSecret").toJSON());
+
+// Append a computed accessor for this instance only:
+json(user.append("temporaryToken").toJSON());
+
+// Chain multiple overrides:
+json(user.makeHidden("password").makeVisible("phoneVerifiedAt").append("isVerified").toJSON());
+```
+
+> **Note** — `makeVisible()` wins over `hidden`: revealing a key removes it from the effective hidden set, even if the class lists it in `static hidden`.
+
+## toJSON output format
+
+`toJSON()` returns a plain `Record<string, unknown>` with:
+
+- **camelCase keys** — a `created_at` column is exposed as the `createdAt` property and serialized as such.
+- **Casts applied** — `datetime` columns return ISO strings, `boolean` returns `true`/`false`, etc. See [ORM casts](/docs/orm/casts).
+- **Hidden fields removed** — per `static hidden` and any `makeHidden()` overrides.
+- **Appended accessors included** — per `static appends` and any `append()` overrides.
+- **Loaded relations included** — nested models serialize via their own `toJSON()`.
+
+```typescript
+// in a controller
+const post = await Post.query().with("author").findOrFail(1);
+
+post.toJSON();
+// {
+//   id: 1,
+//   title: "Hello world",
+//   status: "published",
+//   publishedAt: "2024-01-15T10:30:00.000Z",
+//   createdAt: "2024-01-10T08:00:00.000Z",
+//   author: { id: 3, name: "Alice", email: "alice@example.com" }
+// }
+```
+
+`toJSON()` is called automatically by `JSON.stringify()` and by the `json()` and `view()` response helpers.
+
+## Serializing collections
+
+When you have an array of models, call `toJSON()` on each item or rely on `JSON.stringify()`:
+
+```typescript
+// in a controller
+const posts = await Post.query().where("status", "published").get();
+
+// Explicit — map to plain objects first:
+json(posts.map((p) => p.toJSON()));
+
+// Implicit — JSON.stringify calls toJSON() on each model automatically:
+json(posts);
+```
+
+## Serialization and relationships
+
+Hidden/visible lists apply per-model and do **not** propagate to nested relations. Each nested model serializes via its own class configuration:
+
+```typescript
+// app/models/User.ts and app/models/Post.ts
+@table("users")
+export class User extends Model {
+  static hidden = ["password"]; // only applies to User
+}
+
+@table("posts")
+export class Post extends Model {
+  // No hidden config — exposes all columns
+}
+
+const post = await Post.query().with("author").findOrFail(1);
+post.toJSON();
+// { ..., author: { id: 1, name: "Alice", email: "alice@example.com" } }
+// User.hidden = ["password"] applies to the nested author — password is absent
+```
+
+## API Resource pattern
+
+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
+// app/resources/PostResource.ts
+import { Resource } from "zerotal/http";
+import type { Post } from "../models/Post.ts";
+
+export class PostResource extends Resource<Post> {
+  toArray(): Record<string, unknown> {
+    return {
+      id: this.resource.id,
+      title: this.resource.title,
+      excerpt: this.resource.body.slice(0, 160),
+      publishedAt: this.resource.publishedAt?.toISOString(),
+    };
+  }
+}
+```
+
+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
+// in a controller
+import { json } from "zerotal";
+import { PostResource } from "../resources/PostResource.ts";
+
+// One model → { data: { id, title, … } }
+json(new PostResource(post).toJson());
+
+// Many models → { data: [ … ] }
+json(PostResource.collection(PostResource, posts));
+```
+
+> **Tip** — Call `Resource.withoutWrapping()` once at boot if you prefer flat responses without the `{ data: ... }` envelope. For paginated results, `ResourceCollection.of(PostResource, paginated)` adds `meta` and `links`.
+
+## Which should I use?
+
+| Approach                           | Reach for it when                                                             |
+| ---------------------------------- | ----------------------------------------------------------------------------- |
+| `static hidden` / `static visible` | Globally sensitive fields (passwords, tokens) that should never be exposed.   |
+| `makeHidden()` / `makeVisible()`   | A one-off tweak for a single response (e.g. an admin endpoint).               |
+| `static appends` / `append()`      | Adding computed values (full name, URLs) that aren't real columns.            |
+| `Resource`                         | Different shapes per route, or output that diverges from the model's columns. |
+
+Use model-level `hidden`/`visible` for globally sensitive fields. Use Resources for per-route shaping.
+
+## References
+
+`toJSON()` and the override methods live on every [`Model`](/docs/orm/index); the `Resource` helpers are exported from `zerotal`.
+
+| Member                  | Signature                                                          | Description                                                      |
+| ----------------------- | ------------------------------------------------------------------ | ---------------------------------------------------------------- |
+| `static hidden`         | `string[]`                                                         | Column/accessor keys excluded from `toJSON()`.                   |
+| `static visible`        | `string[]`                                                         | Allow-list; when non-empty, only these keys serialize.           |
+| `static appends`        | `string[]`                                                         | Getter names whose return values are added to `toJSON()`.        |
+| `toJSON()`              | `toJSON(): Record<string, unknown>`                                | Serialize the model to a plain object.                           |
+| `makeHidden()`          | `makeHidden(...keys: string[]): this`                              | Hide extra keys for this instance only.                          |
+| `makeVisible()`         | `makeVisible(...keys: string[]): this`                             | Reveal hidden keys for this instance only.                       |
+| `append()`              | `append(...keys: string[]): this`                                  | Add computed accessor(s) for this instance only.                 |
+| `Resource#toArray()`    | `toArray(): Record<string, unknown>`                               | Define the serialized representation (override this).            |
+| `Resource#toJson()`     | `toJson(): Record<string, unknown>`                                | Plain object, wrapped in `{ data }` unless wrapping is disabled. |
+| `Resource.collection()` | `collection(ResourceClass, items, meta?): Record<string, unknown>` | Serialize an array of models with a resource class.              |
+
+## Next steps
+
+- [ORM](/docs/orm/index) — 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()`.