| name | orm-models |
| description | Creating Eloquent-style models, queries, relationships, casts, factories, and API resources in Rudder |
| license | MIT |
| appliesTo | ["@rudderjs/orm","@rudderjs/orm-prisma"] |
| trigger | creating or editing a `Model` class under `app/Models/`, writing queries / relationships, defining casts / accessors / factories, or building `JsonResource` API resources |
| skip | a route handler that only reads a model — controller-views is enough |
| metadata | {"author":"rudderjs"} |
ORM Models
When to use this skill
Load when you're creating or editing a Model class under app/Models/, writing queries, defining casts / accessors / factories, or building JsonResource API resources. For depth, open the rule file matching your task.
Quick Reference
| Task | Open |
|---|
Define a model — static table, fillable, hidden, casts, soft deletes, decorators, custom casts | rules/defining-models.md |
Query the database — find / where / paginate, eager loading, scopes, soft-delete filters | rules/querying.md |
CRUD + observers — create / update / delete, observer lifecycle, atomic counters | rules/crud-and-observers.md |
Test data — ModelFactory, sequence, states, .make() vs .create() | rules/factories.md |
API output — JsonResource, ResourceCollection, when / whenLoaded / mergeWhen | rules/resources.md |
Key concepts (load once)
- Adapter pattern —
ModelRegistry.set(adapter) plugs in the DB driver. @rudderjs/orm has no runtime DB dependency.
- Hydration — every read (
find/first/all/where(...).get()/paginate) returns Model instances, not plain records. Use Model.hydrate(record) to wrap external data (cached JSON, fixtures).
- Mass assignment —
static fillable (allowlist) / static guarded (denylist; ['*'] locks all) drop keys outside policy on create / update / fill. instance.forceFill bypasses.
- Observers —
Model.create/update/delete fire lifecycle events. query().create() bypasses them. increment / decrement deliberately do not fire — pure data-plane operations.
- Built-in casts:
'string', 'integer', 'float', 'boolean', 'date', 'datetime', 'json', 'array', 'collection', 'encrypted', 'encrypted:array', 'encrypted:object'. Encrypted casts need @rudderjs/crypt.
Examples
See playground/app/Models/User.ts for a working model and playground/routes/console.ts for factory-based seeding.
