Scopes & default scopes

Scopes let you name a reusable set of query options — a where filter, an
order, an attributes projection, a limit, and so on — and attach them to a
model. Instead of repeating the same conditions on every call, you apply a scope
by name and let prorm merge it into the query for you.

prorm supports two kinds of scope:

A default scope, applied automatically to every findAll / findOne /
count unless you explicitly opt out.

Named scopes, applied on demand with Model.scope('name').

[!NOTE]
scope() and unscoped() return a scoped copy of the model and leave the
model itself alone, so a scoped call never changes what a later plain call
sends. Recorded on SQLite:
Earlier releases changed the base model on define() models, so one
User.unscoped() dropped the default scope for every later query. Even
now, a default scope is a convenience, not a security boundary: any call
site can opt out with unscoped(). Use row-level security
or a beforeFind hook for tenancy.

All of the examples below use the same model:

import { Prorm, DataTypes } from 'ts-prorm-orm';

const prorm = new Prorm({ dialect: 'sqlite', storage: ':memory:' });
await prorm.connect();

const User = prorm.define(
  'User',
  {
    name: { type: DataTypes.STRING(100) },
    status: { type: DataTypes.STRING(20) },
    role: { type: DataTypes.STRING(20) },
    createdAt: { type: DataTypes.DATE() },
  },
  {
    defaultScope: {
      where: { status: 'active' },
      order: [['createdAt', 'DESC']],
    },
    scopes: {
      admin: { where: { role: 'admin' } },
      active: { where: { status: 'active' } },
      inactive: { where: { status: 'inactive' } },
      nameOnly: { attributes: ['id', 'name'] },
    },
  },
);

A scope definition is a plain object shaped like FindOptions. The supported
keys are where, order, attributes, include, limit, and offset.

The default scope

Whatever you pass as defaultScope is folded into every query on the model. No
call site has to know about it.

// Automatically filtered to status = 'active' and ordered by createdAt DESC
const activeUsers = await User.findAll();

The default scope contributes each option only when your call does not already
provide it:

Its where keys are merged with the call's where. When the same key appears
in both, the value you pass at the call site wins.

Its order, limit, and attributes apply only if you did not set them on
the call.

// Your explicit ordering overrides the default scope's order,
// but the default status = 'active' filter still applies.
const byName = await User.findAll({ order: [['name', 'ASC']] });

// Your where key replaces the default's for that key.
const banned = await User.findAll({ where: { status: 'banned' } });

// count() honours the default scope too.
const n = await User.count();

Named scopes

Named scopes are declared under scopes and pulled in with Model.scope(name),
which returns a scoped copy of the model. You then run any finder on it.

const admins = await User.scope('admin').findAll();
const count = await User.scope('admin').count();

Important: a named scope replaces the default scope. Once you apply a named
scope, the default scope's where is no longer added. That is why the
inactive scope can return inactive rows even though the default scope filters
to status = 'active':

// Returns inactive users — the default `status = 'active'` filter is dropped
const inactive = await User.scope('inactive').findAll();

To read the default scope explicitly, request it by name:

User.getScope('defaultScope'); // the default scope definition, evaluated

How scopes merge

The default scope and named scopes are alternatives, not layers: a named scope
replaces the default scope. where clauses from several named scopes
combine — every applied scope's conditions must hold. Singular options like
limit and order do not combine: the first one set wins, and the call's own
options win over every scope.

Combining scopes

Apply several named scopes at once by passing an array. Their where clauses
are merged together (later scopes override earlier ones on conflicting keys):

// role = 'admin' AND status = 'active'
const activeAdmins = await User.scope(['admin', 'active']).findAll();

scope() returns a model you can scope again, so the calls also chain
fluently — this is equivalent to the array form above:

const activeAdmins = await User.scope('admin').scope('active').findAll();

For non-where options in a combined scope, the first value set wins: once an
order, limit, or attributes has been contributed by a scope (or by your
call), later scopes leave it alone.

Merging a scope with a call-site `where`

You can still pass query options to a finder on a scoped model. The scope and
your options are merged:

const results = await User.scope('admin').findAll({
  where: { status: 'active' },
});

Non-overlapping where keys are combined (ANDed together), so the query above
matches role = 'admin' AND status = 'active'. When the scope and your call-site
where set the same key, the named scope's value takes precedence:

// role: 'user' is silently replaced by the scope's role: 'admin'
await User.scope('admin').findAll({ where: { role: 'user', status: 'active' } });

[!WARNING]
This is the opposite of the default scope, where the call site wins. If a
caller must be able to narrow a value, leave that key out of the named scope
and pass it as a scope argument instead.

Parameterised scopes

A scope may be a function returning the options. Pass its arguments after
its name in the array form; each string that names a known scope starts a new
scope, and everything after it is that scope's arguments:

import { DataTypes, Op } from 'ts-prorm-orm';

const User = prorm.define(
  'User',
  {
    name: { type: DataTypes.STRING(100) },
    status: { type: DataTypes.STRING(20) },
    role: { type: DataTypes.STRING(20) },
    createdAt: { type: DataTypes.DATE() },
  },
  {
    scopes: {
      nameOnly: { attributes: ['id', 'name'] },
      byRole: (role: string) => ({ where: { role } }),
      recent: (days: number) => ({
        where: { createdAt: { [Op.gte]: new Date(Date.now() - days * 86_400_000) } },
        order: [['createdAt', 'DESC']],
        limit: 50,
      }),
    },
  },
);

// byRole('editor'), then recent(7), then nameOnly
const editors = await User.scope(['byRole', 'editor', 'recent', 7, 'nameOnly']).findAll();

The limit in recent is where the engines differ:

MySQL and SQL Server render the Date in the process's local time zone
(2026-09-18 20:00:00.000 above, from a UTC-4 machine), PostgreSQL and SQLite
as UTC ISO text — set timezone on the connection when that matters.

[!TIP]
Because a string argument is only treated as a new scope when it names a
scope, ['byRole', 'admin'] passes 'admin' to byRole even though a scope
called admin exists… unless it does — then 'admin' starts the admin
scope and byRole gets no argument. Pick argument values and scope names that
cannot collide, or apply the scopes one scope() call at a time.

`addScope()` — registering scopes after definition

Scopes do not have to be declared up front. addScope(name, definition)
registers a new named scope on an already-defined model, and it behaves exactly
like a scope declared in define.

User.addScope('users', { where: { role: 'user' } });

const regularUsers = await User.scope('users').findAll();

This is handy when a scope depends on values you only know at runtime, or when a
plugin or module wants to extend a model it did not define. You can register
scopes before or after any query — each findAll resolves the scopes that exist
at call time.

Bypassing scopes with `unscoped()`

unscoped() returns a model view with no scopes applied — not the default
scope, and not any named scope. Use it when you genuinely need every row.

// Every user, regardless of status (and see the caution at the top of the page)
const everyone = await User.unscoped().findAll();

// Still no default scope, but with your own filter
const archived = await User.unscoped().findAll({
  where: { status: 'archived' },
});

Managing scopes

A model exposes a small API for inspecting and editing its scopes at runtime:

User.hasScope('admin'); // true
User.getScope('admin'); // { where: { role: 'admin' } }
User.getScopes(); // { admin: {...}, active: {...}, ... }
User.allScopes(); // alias for getScopes()

User.removeScope('inactive'); // true; deletes the named scope
User.clearScopes(); // remove every named scope

hasScope(name) reports whether a named scope is registered.

getScope(name) returns a single scope definition. A getScope('defaultScope')
call returns the default scope.

getScopes() (and its alias allScopes()) returns every named scope as a
plain object keyed by name.

removeScope(name) deletes one named scope and returns true if it existed,
false otherwise.

clearScopes() removes all named scopes at once. The default scope is left
intact.

How merging works, in short

When a query runs, prorm resolves the active scopes into your FindOptions:

If the model view is not unscoped and no named scope is applied, the
default scope is merged in. Its where combines with your call-site where
(your keys win on conflict); its order, limit, and attributes fill in
only what you left unset.

If one or more named scopes are applied, the default scope is skipped
entirely. Each named scope's where is merged into the query in order (later
keys override earlier ones), while order, limit, and attributes keep the
first value that gets set.

unscoped() skips both steps — nothing is merged.

Keeping filters in scopes rather than scattered across call sites means the rule
lives in one place, reads clearly, and is easy to change later.

A tenant scope, done safely

A multi-tenant app is the classic case for a default scope, and exactly the one
the caution above rules out. A beforeFind hook gives the same "every query is
filtered" guarantee without the shared-state problem, because it runs on every
call and reads the tenant from the request context:

import { AsyncLocalStorage } from 'node:async_hooks';

export const tenantContext = new AsyncLocalStorage<{ tenantId: number }>();

export function enforceTenant(Model: { hook: (name: string, fn: (opts: any) => void) => unknown }) {
  Model.hook('beforeFind', (findOptions) => {
    const ctx = tenantContext.getStore();
    if (!ctx) throw new Error('query outside a tenant context');
    findOptions.where = { ...(findOptions.where ?? {}), tenantId: ctx.tenantId };
  });
}

enforceTenant(Invoice);

// in the request handler
await tenantContext.run({ tenantId: 42 }, () => Invoice.findAll({ where: { status: 'open' } }));

Querying — the options a scope is made of

Associations — scopes applied through a relationship

Scopes & default scopes

The default scope#

Named scopes#

How scopes merge#

Combining scopes#

Merging a scope with a call-site where#

Parameterised scopes#

addScope() — registering scopes after definition#

Bypassing scopes with unscoped()#

Managing scopes#

How merging works, in short#

A tenant scope, done safely#

Related reading#