Scopes
A scope is a named, reusable piece of a query. Instead of writing .where('status', 'published') in twenty places, you define it once on the model and write .published(). If the rule ever changes, you change it in one place.
There are two kinds:
- Local scopes you call by name when you want them:
Post.query().published(). - Global scopes apply to every query of the model automatically, until you remove them by name.
Your first local scope
Section titled “Your first local scope”import { Model, type Scopes } from '@strutvane/framework'
export class Post extends Model('posts', { fillable: ['title', 'body', 'status'] }) { static readonly scopes = { published: (query) => query.where('status', 'published'), } satisfies Scopes<'posts'>}const posts = await Post.query().published().orderBy('title').get()console.log(posts.map((post) => post.title))What you’ll see:
[ 'Alpha', 'Gamma' ]satisfies Scopes<'posts'> lets TypeScript check each scope against the posts columns, and query inside the function is fully typed.
To add a scope to any model:
- Add
static readonly scopes = { … } satisfies Scopes<'your_table'>to the model class (importScopesfrom@strutvane/framework). - Give each scope a name and a function that receives the query and adds conditions to it.
- Call it on a query by its name:
Post.query().published().
What a scope can use
Section titled “What a scope can use”Inside a scope, query offers the filtering part of the builder, typed by the table:
| Method | Example |
|---|---|
where / orWhere |
query.where('status', 'published'), query.where('published_on', '>=', '2026-01-01') |
whereIn |
query.whereIn('status', ['draft', 'published']) |
whereNull / whereNotNull |
query.whereNotNull('published_on') |
whereRaw |
query.whereRaw(sql`length(${sql.id('title')}) > ${10}`) |
orderBy |
query.orderBy('published_on', 'desc') |
A scope sees the table’s types, not the model class, which keeps the model’s types simple. Relationship methods (with, whereHas) and grouping with a function aren’t part of a scope’s query; add those where you call the scope.
Scopes with arguments
Section titled “Scopes with arguments”Add parameters after query. They become the method’s parameters:
static readonly scopes = { published: (query) => query.where('status', 'published'), ofStatus: (query, status: 'draft' | 'published') => query.where('status', status),} satisfies Scopes<'posts'>await Post.query().ofStatus('draft').orderBy('title').get()// → [ 'Beta', 'Delta 100%' ]
Post.query().ofStatus('archived') // compile error: not 'draft' | 'published'A scope can take several parameters, with defaults like any function:
static readonly scopes = { publishedBetween: (query, from: string, to: string = '9999-12-31') => query.where('status', 'published').where('published_on', '>=', from).where('published_on', '<=', to),} satisfies Scopes<'posts'>await Post.query().publishedBetween('2026-01-01').count()await Post.query().publishedBetween('2026-01-01', '2026-06-30').get()Combining scopes
Section titled “Combining scopes”Scopes chain with everything else, in any order:
const latestPublished = await Post.query() .published() .where('published_on', '>=', '2026-01-01') .latest() .limit(5) .get()They also work through relationships:
const ada = await User.query().where('name', 'Ada').firstOrFail()const adasPublished = await ada.posts().published().get()// → [ 'Ada one' ]Global scopes
Section titled “Global scopes”A global scope is added to every query of the model: lists, find(), counts, relationships, whereHas() and pagination. Use it for rules that should never be forgotten.
import { Model, type Scopes } from '@strutvane/framework'
/** The posts table, seen through a filter: only published posts. */export class PublishedPost extends Model('posts', { fillable: ['title'] }) { static readonly globalScopes = { published: (query) => query.where('status', 'published'), } satisfies Scopes<'posts'>}await PublishedPost.query().orderBy('title').get() // → [ 'Alpha', 'Gamma' ]await PublishedPost.query().count() // → 2Your OR conditions can’t escape a global scope
Section titled “Your OR conditions can’t escape a global scope”Strutvane wraps your conditions in brackets before adding the global scope, so an orWhere() can never leak rows the scope hides:
await PublishedPost.query().where('title', 'Beta').orWhere('title', 'Alpha').get()// SQL: WHERE (title = ? OR title = ?) AND status = ?// → [ 'Alpha' ] (Beta is a draft, so it stays hidden)Without the brackets, SQL would read title = 'Beta' OR (title = 'Alpha' AND status = 'published'), and the draft would leak. This is tested on every database.
Removing a global scope
Section titled “Removing a global scope”await PublishedPost.query().withoutGlobalScope('published').count() // → 4Use the name you gave the scope in globalScopes.
Built-in automatic conditions
Section titled “Built-in automatic conditions”Two conditions behave like global scopes without you writing them:
| Condition | When | How to change it |
|---|---|---|
Hide soft-deleted rows (deleted_at IS NULL) |
the table has t.softDeletes() |
withTrashed(), onlyTrashed() (see Soft Deletes) |
| Only the active tenant’s rows | the table has the tenant column | can’t be removed silently; see Tenancy |
Common mistakes
Section titled “Common mistakes”A scope with the same name as a query method
Section titled “A scope with the same name as a query method”OrmUsageError: Post has a scope named "latest", which clashes with the query method latest(). Rename the scope.Why: scopes become methods on the query builder, so they can’t reuse a built-in name like where, latest or count.
Fix: pick a descriptive name, such as newestFirst or recentlyPublished.
Removing a global scope that doesn’t exist
Section titled “Removing a global scope that doesn’t exist”OrmUsageError: PublishedPost has no global scope "publish". Global scopes are listed in its static globalScopes.Fix: use the exact key from static globalScopes (here 'published').
A scope that isn’t a function
Section titled “A scope that isn’t a function”OrmUsageError: static scopes.published must be a function (query, …args) => …Why: each entry must be a function that receives the query.
Fix:
static readonly scopes = { published: (query) => query.where('status', 'published'),} satisfies Scopes<'posts'>Calling a scope on the model instead of the query
Section titled “Calling a scope on the model instead of the query”Post.published() doesn’t exist: scopes live on the query builder.
Fix: start a query first: Post.query().published().
Next steps
Section titled “Next steps”- Querying: everything you can put inside a scope.
- Soft Deletes: the built-in “hide deleted rows” condition.
- Tenancy: the condition you can’t forget.