- Core Concepts · Hook Lifecycle Events · Before vs After Hooks
- Hook Definition Schema · Key Properties Explained
- Sandboxed Hook Bodies (
body) · Capabilities — the complete list · Sandbox restrictions - Hook Context API · Common Patterns · Registration Methods
- Best Practices · Error Handling · References
Reference companion to objectstack-data/SKILL.md, and the catalog's anchor for
data hooks. Covers the lifecycle events, the sandboxed body (and the deprecated
inline handler), the HookContext API, registration, and the canonical patterns
(delete guards, audit trails, cross-object writes, read masking).
check:skill-examples skips the unmarked blocks: fragments, shapes, and pattern 4's bare any.
Hooks are event handlers that execute during the ObjectQL data access lifecycle. They intercept operations at specific points (before/after) — see Before vs After.
ObjectStack provides lifecycle events organized by operation type:
| Event | When It Fires | Use Cases |
|---|---|---|
| Read Operations | ||
beforeFind |
Before any read — find and findOne |
Filter queries by user context, log access |
afterFind |
After any read — find and findOne |
Transform results, enrich data |
| Write Operations | ||
beforeInsert |
Before creating a record | Set defaults, validate, normalize |
afterInsert |
After creating a record | Send notifications, create related records |
beforeUpdate |
Before updating a record (single or bulk multi:true) |
Validate changes, check permissions |
afterUpdate |
After updating a record (single or bulk) | Trigger workflows, sync external systems |
beforeDelete |
Before deleting a record (single or bulk multi:true) |
Check dependencies, prevent deletion |
afterDelete |
After deleting a record (single or bulk) | Clean up related data, notify users |
Why so few? The read events fire for
findOneas well asfind(the event attaches to record materialization, not the engine method), so one subscription covers every read shape — there is nobeforeFindOne/afterFindOne. Likewise the write events fire on bulkmulti:trueoperations, so there is no*Manyevent. A bulk write hands hooks no row-scoping predicate: it lives on the engine-internalOperationContext.ast, so the RLS / sharing filters composed onto it bind the driver call itself, where no handler can widen them — scope a batch throughoptions.whereat the caller. Both phases dispatch once per matched row, each on a single-record-shaped context whoseinput.id(handler; abody:ctx.previous.id) names that row and whosepreviousis that row's pre-image (ADR-0058 Addendum II). And there is nobeforeCount/beforeAggregate: read authorization and row filtering belong to RLS / permission rules, and field masking to field-level metadata — declarative mechanisms that apply everywhere, rather than a hook every author must remember to re-attach.
| Aspect | before* Hooks |
after* Hooks |
|---|---|---|
| Purpose | Validation, enrichment, transformation | Side effects, notifications, logging |
| Can modify | ctx.input (mutable) |
ctx.result (mutable) |
| Can abort | Yes (throw error → rollback) | A sync after-hook's throw still rolls back the transaction (see error handling) |
| Transaction | Within transaction | Within the transaction. async: true on afterInsert / afterUpdate / afterDelete: starts once the outermost transaction commits, never if it rolls back (a failed commit included); on afterFind: starts as the read is dispatched; outside a transaction: starts at once |
| Error handling | Aborts by default (onError: 'abort') |
Also aborts by default — onError defaults to 'abort' unconditionally; set onError: 'log' on side-effect hooks |
Every hook must conform to the HookSchema. Author it with defineHook() —
preferred over a bare : Hook literal (the same rule as defineDatasource):
it validates when the module is imported, so constraint-level mistakes a bare
annotation can't catch — a non-snake_case name, a misspelled key routed
through a spread — fail while you author instead of at deploy, and the export
carries defaults already materialized.
import { P } from '@objectstack/spec';
import { defineHook } from '@objectstack/spec/data';
const myHook = defineHook({
// Required: Unique identifier (snake_case)
name: 'crm_validation_hook',
// Required: Target object(s)
object: 'account', // string | string[] | '*'
// Required: Events to subscribe to
events: ['beforeInsert', 'beforeUpdate'],
// The logic: a sandboxed body (the inline `handler` is deprecated)
body: {
language: 'js',
source: `/* statements against ctx */`,
capabilities: [], // the ctx APIs it may call — see Capabilities
},
// Optional: Execution priority (lower runs first)
priority: 100, // System: 0-99, App: 100-999, User: 1000+
// Optional: Run in background (after* events only)
async: false,
// Optional: Conditional execution (CEL predicate over `record`)
condition: P`record.status == 'active' && record.amount != null && record.amount > 1000`,
// Optional: Human-readable description
description: 'Validates account data before save',
// Optional: Error handling strategy
onError: 'abort', // 'abort' | 'log'
// Optional: Execution timeout (ms)
timeoutMs: 5000,
// Optional: Retry policy
retryPolicy: {
maxRetries: 3,
backoffMs: 1000,
},
});A source of statements against ctx; a throw aborts the write
(Sandboxed Hook Bodies):
body: {
language: 'js',
source: `if (ctx.input.email) ctx.input.email = ctx.input.email.trim().toLowerCase();`,
}Skip the hook if the condition is false. Author it as a CEL
predicate over record and previous (use P\...`from@objectstack/spec; SQL-style =/AND/IN (...)` is not CEL):
// Only run for high-value accounts
condition: P`record.annual_revenue != null && record.annual_revenue > 1000000`
// Only run for specific statuses
condition: P`record.status in ['pending', 'in_review']`
// Complex conditions
condition: P`record.type == 'enterprise' && record.region == 'APAC' && record.is_active == true`
// A TRANSITION — fires only on the update that completes the task,
// not on later updates of an already-done record
condition: P`previous.done != true && record.done == true`record here is the RECORD, not this write's payload. The condition
is evaluated against the stored row overlaid with the fields this write carries,
made total over the object's declared fields (null when a declared field is
in neither). So:
- Reference any declared field, not just the ones this update touches —
record.done == trueworks on an update that only setsstatus. (This is unlikectx.input/ctx.resultinside the body, which stay partial — see Gotcha 1.) recorddescribes the record's state, not the diff.record.done == truefires on every update of an already-done record, not only on the update that set it. For the transition, compare againstprevious:previous.done != true && record.done == true.previousis the stored pre-write row, made total over the same declared fields, and it is the same binding a validation predicate reads.previousisnullon insert (beforeInsert/afterInsert), soprevious == null || …judges an insert andprevious != null && …skips one; a column read off it there (previous.done) has no value and faults.previousis UNBOUND only for a write to an existing row whose prior state is not in hand, which fails closed rather than reading an update as an insert. Thebefore*dispatch of a predicate (multi: true) write is not such a case:beforeUpdate/beforeDeletedispatch once per matched row, each on a single-record-shaped context whosepreviousis that row's pre-image and whoseinput.id(handler; abody:ctx.previous.id) names the row (ADR-0058 Addendum II, D1/D2), so a transition condition evaluates there exactly as on a single-record write, andrecordis that row's state, stored ⊕ payload. Only the payload stays batch-scoped (D3): every row's dispatch carries the one payload, so a rewrite made on any row applies to every matched row, and a rewrite decided per row must assign the same key set on every row, in place (ctx.input.x = …, never a replaced object) — the engine refuses the batch whole, before any write, when two rows' key sets differ (MULTI_UPDATE_HOOK_KEY_DIVERGENCE, status 400; ADR-0058 Amendment II.3).after*hooks fire PER ROW, so a bulk write needs no special condition. A predicate (multi: true) update/delete dispatches itsafter*hooks once per matched row, each on a single-record-shaped context —previousis that row's pre-image,recordis that row's real state (not the bare payload), andinput.id(handler; abody:ctx.previous.id) names the row. A transition condition therefore is available onafterUpdate/afterDelete: write it once and it means the same thing whether the write carried an id or a predicate, with no bulk-aware branch of its own.- Guard optional values with
!= null, never withhas(...). A declared field holdingnullis present, sohas(record.spent)is uniformly true andhas(record.spent) && record.spent > record.budgetstill faults onnull > null.has()answers "is this key declared at all", which is a question about your spelling, not about your data.
record.stauts), a column read off previous on an insert, or a comparison
CEL has no overload for does not degrade to "the hook did not fire" — it
fails the write.
body — sandboxed script |
handler — inline function (deprecated) |
|
|---|---|---|
| Shape | body: { language, source, capabilities } (pure metadata) |
handler: async (ctx) => { … } |
| Runs in | An isolated QuickJS VM (edge-safe, capability-gated) | The host process (full Node) |
| Status | Preferred for new code | Deprecated (HookSchema: "prefer body") |
| Both present? | Runtime uses body and ignores handler |
— |
sourceis the function body, which the runtime wraps as(async (ctx) => { <source> })(ctx). Write statements againstctx;awaitis allowed.- In a
before*hook, change the write by assigningctx.input.x = …orreturn { x: … }(a returned object is shallow-merged ontoctx.input). In anafter*hook the body is for side effects (cross-object writes, logging). language: 'expression'is a pure CEL formula for a computed value or predicate — no IO, noctx.api.
The sandbox is handed a JSON snapshot of these (built by
buildSandboxContext), not live engine objects:
ctx.* |
Shape | Notes |
|---|---|---|
ctx.input |
object | The write payload (mutable). On update, only the changed fields; id only if the payload has it (the row: ctx.previous.id). |
ctx.previous |
object | undefined |
Pre-write record on update/delete. undefined on insert → use !ctx.previous to detect create. |
ctx.result |
object | undefined |
after* only. |
ctx.user |
object | undefined |
{ id, name, email, organizationId }. undefined for system / unauthenticated writes. |
ctx.session |
object | undefined |
{ userId, organizationId, isSystem, … }. No role list — session.roles was retired in 17.0.0. |
ctx.event |
string | e.g. 'afterUpdate' — dispatch on it when one hook subscribes to several events. |
ctx.object |
string | The target object name. |
ctx.api |
object | Cross-object CRUD. Gated by api.read / api.write — see below. |
ctx.log |
{ debug, info, warn, error } |
Gated by log. Call ctx.log.info(msg, data?) — ctx.log is an object, not callable as ctx.log(msg). Emission is best-effort (see Troubleshooting). |
ctx.crypto |
{ randomUUID } |
Gated by crypto.uuid. |
ctx.email |
{ send } |
Gated by email.send; not in a hook body. |
ctx.activity |
{ append } |
Gated by activity.append. |
ctx.notice |
(message) => void |
Tell the saver what this save set in motion — answered as the create/update notice, shown on the save toast. No capability; insert/update only; last call wins. rules/lifecycle.md § Save Notice. |
ctx.title |
(field?) => Promise<string | null> |
Name the record, not its id. ctx.title() resolves this object's nameField, a formula included (no extra read); ctx.title('account_id') resolves a lookup's title (needs api.read). null when there is no title, never the id. Per door: body has it; a deprecated handler gets it at runtime, undeclared on HookContext (TS2339 when annotated) — use body; ql.registerHook and a bare ObjectQL bindHooks lack it. |
(Action bodies additionally receive ctx.recordId and ctx.record, and their
wrap is (async (input, ctx) => { … })(input, ctx) — the action params arrive as
the first arg.)
ctx.api.object('<object>') returns a repository bound to the current
org / user / transaction. Methods:
| Method | Capability | Call |
|---|---|---|
find(opts) |
api.read |
find({ where: { … }, fields, sort, limit }) → array |
findOne(opts) |
api.read |
findOne({ where: { id } }) → record | null — needs a predicate or an orderBy, see below |
count(opts) |
api.read |
count({ where: { … } }) → number |
insert(data) |
api.write |
insert({ … }) |
update(data, opts?) |
api.write |
update({ id, ...fields }) — put the id inside data; bulk: update(fields, { where, multi: true }) |
delete(opts) |
api.write |
delete({ where: { id } }); bulk: delete({ where, multi: true }) |
aggregate(opts) |
api.read |
same where shape |
Query shape — the key is where. It takes an object with $-operators, the
same DSL as the objectstack-query skill:
await ctx.api.object('candidate').findOne({ where: { id: ctx.result.id } });
await ctx.api.object('candidate').find({ where: { stage: 'hired' } });
await ctx.api.object('invoice').count({ where: { amount: { $gte: 1000 } } });
const uid = ctx.session?.userId;
if (!uid) return;
await ctx.api.object('task').find({ where: { $and: [{ done: false }, { owner_id: uid }] } });
filter:is tolerated as an object-valued alias (normalised towhere), but preferwhere. Do not pass an array-of-triples such as[['id', '=', x]]— that is not a supported value shape and silently matches nothing.
findOne must say which record it wants. It reads a single row, so an
absent or empty predicate does not come back as null — it comes back as the
object's first row: a real, plausible-looking record with nothing to do with
what you asked for, which your if (!row) cannot catch. So findOne(),
findOne({}) and findOne({ where: {} }) throw. Be specific in one
of three ways:
await ctx.api.object('candidate').findOne({ where: { id } }); // by predicate
await ctx.api.object('candidate').findOne({ search: 'Acme' }); // by search
await ctx.api.object('audit')
.findOne({ orderBy: [{ field: 'created_at', order: 'desc' }] });// "the newest one"
await ctx.api.object('candidate').find({ limit: 1 }); // any row will doAn unpredicated find / count is fine — returning or counting every row is an
honest answer.
A body may only touch a ctx API it declared in capabilities. Calling an
undeclared one throws inside the VM — capability '<token>' not granted to hook '<name>' … — which surfaces as a hook error (see Troubleshooting). The full
set of legal tokens (HookBodyCapability) is exactly seven:
| Token | Unlocks |
|---|---|
api.read |
ctx.api.object(n).find / findOne / count / aggregate; also ctx.title('<lookup field>'), which reads that related record. Plain ctx.title() reads nothing and needs no token. |
api.write |
ctx.api.object(n).insert / update / delete |
api.transaction |
ctx.api.transaction(async () => { … }) — runs the callback's ctx.api ops in one driver transaction (commit on return, rollback on throw). Pair it with api.write. |
crypto.uuid |
ctx.crypto.randomUUID() |
log |
ctx.log.debug / info / warn / error(msg, data?) |
email.send |
ctx.email.send({ to, subject, text }) — mail via the mail service; sender, user and organization are stamped (BodyMailSendInputSchema). Not in a hook body (refused at parse and at bind): a message cannot be taken back if the hook's write rolls back. Mail on a record change goes through an action, a job or a flow. |
activity.append |
ctx.activity.append({ object, recordId, type, summary }) — one record-timeline entry; actor and origin are stamped (BodyActivityAppendInputSchema). type is the app's own, never a SYS_ACTIVITY_PLATFORM_TYPES value (403 PERMISSION_DENIED, aborting the write under onError: 'abort'); never inside ctx.api.transaction (409 RESOURCE_CONFLICT). Commits or rolls back with the write that runs the body. |
There is no http.fetch capability by design — outbound calls go through
Connector recipes
(connector_action in a flow) so they stay auditable and replayable.
The body runs in an isolated QuickJS VM, not Node:
- Available: standard JS built-ins —
Date,Math,JSON,Object,Array,String,Number,RegExp,Map,Set,Promise,parseInt,encodeURIComponent, … — plusctx.*andawait. - Not available (verified absent from the QuickJS heap):
console(usectx.log),fetch(use Connectors),setTimeout/setInterval,URL,TextEncoder/TextDecoder,structuredClone,atob/btoa,require, Node modules, the filesystem. - Rejected by
objectstack build:import/require/ dynamicimport(),process,globalThis,eval,new Function, and any free identifier — a name bound at module scope, e.g. aconst slugify = …helper sitting next to the hook. Abodymust be self-contained: inline the helper, or keep that hook as a bundled (deprecated)handler.
A deadline stamped from an hours table is calendar hours — nights, weekends and holidays count. Name it
*_CALENDAR_HOURS(SLA_CALENDAR_HOURS, or its camelCase) and add elapsed milliseconds (hours * 3_600_000); never label it "business hours".
On afterUpdate, both ctx.result and ctx.input carry only the fields this
PATCH touched (ctx.result adds id). A field you did not write — a lookup FK, a status
you want to branch on — is absent, not stale. To read the whole record,
re-query it:
// afterUpdate on `candidate`
const full = await ctx.api.object('candidate').findOne({ where: { id: ctx.result.id } });
// full.position_id is present even though this PATCH only set `stage`.A hook's ctx.api.object('other').update(…) goes through the engine's normal
write path, so it is gated by other's permission / sharing rules — not by
whoever is elevated. If the acting user cannot edit the target (e.g. it is
public_read), the write throws:
FORBIDDEN: <a localized sentence; match on code, not prose>
An admin is not automatically exempt — the gate is canEdit, driven by the
sharing model, not a global admin bypass. If a hook must write a target, give the
acting principal edit access to it (sharing rule / permission set), or drive the
write from a system-context automation.
When a candidate is marked hired, look up its position (a lookup FK that
is not in the partial patch) and flip that position to filled:
import { defineHook } from '@objectstack/spec/data';
const fillPositionOnHire = defineHook({
name: 'crm_fill_position_on_hire',
object: 'candidate',
events: ['afterUpdate'],
body: {
language: 'js',
source: `
// afterUpdate → ctx.result is the PARTIAL patch. Gate on the field this
// write actually set, then re-query for the lookup FK it does NOT carry.
if (!ctx.result || ctx.result.stage !== 'hired') return;
const rec = await ctx.api.object('candidate').findOne({ where: { id: ctx.result.id } });
if (!rec || !rec.position_id) return;
// Cross-object write — needs the acting user to be able to edit 'position'.
await ctx.api.object('position').update({ id: rec.position_id, status: 'filled' });
ctx.log.info('position filled', { position: rec.position_id });
`,
capabilities: ['api.read', 'api.write', 'log'],
},
onError: 'log',
});
export default fillPositionOnHire;[BodyRunner] invalid hook.body shape(warn) —bodyfailedHookBodySchema; the hook is skipped. Checklanguage/source/capabilities.[BodyRunner] sandboxed hook threw(error) — the body raised. The wrapped message names the hook; the usual causes are a missing capability, aFORBIDDENcross-object write (gotcha 2), or aReferenceErrorfrom a free identifier or an unavailable global (e.g.console).ctx.log.*produced no output — two independent causes: (1) without thelogcapability the call throws (surfaces as a hook error); (2) with the capability it emits only when the runtime wired a logger into the hook context — otherwise it is a silent no-op. Treatctx.logas best-effort diagnostics, not a reliable side-channel or proof a hook ran; to observe an effect, assert on the data it writes.
Sandbox vs in-process. The
ctxdocumented below is the in-processhandlercontext (full Node;handleris deprecated). A metadata-nativebodysees a capability-gated subset of it inside an isolated VM — see Sandboxed Hook Bodies for exactly what is and isn't available there.
The engine's HookContext provides:
interface HookContext {
// Immutable identifiers
id?: string; // Unique execution ID for tracing
object: string; // Target object name (e.g., 'account')
event: HookEventType; // Current event (e.g., 'beforeInsert')
// Mutable data
input: Record<string, unknown>; // Operation parameters (MUTABLE)
result?: unknown; // Operation result (MUTABLE, after* only)
previous?: Record<string, unknown>; // Previous state (update/delete)
// Execution context
session?: {
userId?: string;
organizationId?: string; // Active org — the single blessed name. Matches the
// `organization_id` column + `current_user.organizationId` (RLS).
// The former `tenantId` alias was removed in v16.
// Privilege is judged by the security service,
// never by a session claim.
accessToken?: string;
isSystem?: boolean; // Elevated system context (engine self-writes).
};
transaction?: unknown; // Database transaction handle
// Engine access
ql: IDataEngine; // ObjectQL engine instance
api?: ScopedContext; // Cross-object CRUD API
notice?: (message: string) => void; // Save notice: rules/lifecycle.md § Save Notice
// User info shortcut (undefined for system / unauthenticated writes)
user?: {
id?: string;
name?: string;
email?: string;
organizationId?: string; // Same value as session.organizationId
};
}The value a hook usually wants when it needs "the current org to filter/scope
by" is the caller's active organization — the same value that lives in the
organization_id column, in current_user.organizationId inside RLS/sharing
predicates, and in seed rows. Read it as organizationId:
// ✅ Blessed — matches columns, RLS `current_user`, and seed data
const org = ctx.user?.organizationId ?? ctx.session?.organizationId;Two isolation axes — don't conflate them.
organization_idis org row-scoping: many organizations share one database and every row carries its owning org (current_user.organizationIdfilters reads/writes; it needs a walled posture —OS_TENANCY_POSTURE=group|isolated— with@objectstack/organizationsdeclared by the app, open core since ADR-0132). That is different from environment / database-per-tenant isolation (service-tenant,driver-turso), where "tenant" means an entire environment/database and the generic driver-layertenantIdknob (execCtx.tenantId/DriverOptions.tenantId) can carry that environment id. The object-metadatatenancy.*knob configures the mechanism (isolation on/off
- which column); the value you read and write is your
organization_idcolumn. Undersinglethe bootstrapped Default Organization is the only one, so there is nothing to scope by (rules/security.md§ Multi-tenancy).
The structure of ctx.input varies by event:
Insert operations:
// beforeInsert, afterInsert
{
// All field values being inserted
name: 'Acme Corp',
industry: 'Technology',
annual_revenue: 5000000,
...
}Update operations:
// beforeUpdate, afterUpdate
{
id: '123', // Record ID being updated
// Only fields being changed
status: 'active',
updated_at: '2026-04-13T10:00:00Z',
}Delete operations:
// beforeDelete, afterDelete
{
id: '123', // Record ID being deleted
}Query operations:
// beforeFind, afterFind
{
query: {
filter: { status: 'active' },
sort: [{ field: 'created_at', order: 'desc' }],
limit: 50,
offset: 0,
},
options: { includeCount: true },
}Available in after* hooks:
// afterInsert
result: { id: '123', name: 'Acme Corp', ... }
// afterUpdate
result: { id: '123', status: 'active', ... }
// afterDelete
result: { success: true, id: '123' }
// afterFind
result: {
records: [{ id: '1', ... }, { id: '2', ... }],
total: 150,
}import { defineHook } from '@objectstack/spec/data';
const protectStrategicAccounts = defineHook({
name: 'crm_protect_strategic_accounts',
object: 'account',
events: ['beforeDelete'],
refusals: {
STRATEGIC_ACCOUNT: { message: 'A strategic account cannot be deleted.' },
OPEN_OPPORTUNITIES: { message: 'Close its open opportunities first.', status: 409 },
},
body: {
language: 'js',
source: `
// A delete's ctx.input is empty: ctx.previous is the row being deleted.
if (ctx.previous && ctx.previous.type === 'Strategic')
throw Object.assign(new Error(), { code: 'STRATEGIC_ACCOUNT' });
const open = await ctx.api.object('opportunity').count({
where: { account_id: ctx.previous.id, stage: { $in: ['Prospecting', 'Negotiation'] } },
});
if (open > 0) throw Object.assign(new Error(), { code: 'OPEN_OPPORTUNITIES' });
`,
capabilities: ['api.read'],
},
});import { defineHook } from '@objectstack/spec/data';
const createAuditTrail = defineHook({
name: 'crm_audit_trail',
object: ['account', 'contact', 'opportunity'],
events: ['afterInsert', 'afterUpdate', 'afterDelete'],
body: {
language: 'js',
source: `
await ctx.api.object('audit_log').insert({
object_type: ctx.object,
record_id: String((ctx.previous || ctx.result || {}).id || ''),
action: ctx.event.replace('after', '').toLowerCase(),
user_id: ctx.session && ctx.session.userId,
timestamp: new Date().toISOString(),
changes: ctx.event === 'afterUpdate' ? { before: ctx.previous, after: ctx.result } : undefined,
});
`,
capabilities: ['api.write'],
},
});import { defineHook } from '@objectstack/spec/data';
const cascadeAccountUpdate = defineHook({
name: 'crm_cascade_account_updates',
object: 'account',
events: ['afterUpdate'],
body: {
language: 'js',
source: `
// Industry changed → update every contact of the account in one bulk write.
if (ctx.input.industry && ctx.previous && ctx.previous.industry !== ctx.input.industry)
await ctx.api.object('contact').update(
{ account_industry: ctx.input.industry },
{ where: { account_id: ctx.previous.id }, multi: true },
);
`,
capabilities: ['api.write'],
},
});A body cannot do this: it writes back only ctx.input, and its ctx.result is a snapshot.
For static field masking (a field is always hidden/masked for a permission set or position), prefer declarative field-level metadata (secret/masked fields) — it applies on every read path automatically. Use an
afterFindhook only for masking that depends on runtime logic the field metadata can't express. A singleafterFindsubscription covers bothfindandfindOne.
const maskSensitiveData = defineHook({
name: 'crm_mask_pii',
object: ['contact', 'lead'],
events: ['afterFind'],
handler: async (ctx) => {
// Exempt the engine's own elevated reads (`isSystem`) — internal writes
// and self-reads must see the real values.
//
// ⚠️ Never gate this on a session claim: `ctx.session?.roles?.includes(…)`
// is always `undefined` (see the ctx table above), so a mask written that
// way never exempts anyone. A per-permission-set or per-position exemption
// belongs in field-level permissions (the callout above), which the read
// path applies for you.
const isElevated = ctx.session?.isSystem === true;
if (!isElevated) {
// Mask sensitive fields
const maskField = (record: any) => {
if (record.ssn) {
record.ssn = '***-**-' + record.ssn.slice(-4);
}
if (record.credit_card) {
record.credit_card = '**** **** **** ' + record.credit_card.slice(-4);
}
};
if (Array.isArray(ctx.result?.records)) {
ctx.result.records.forEach(maskField);
} else if (ctx.result) {
maskField(ctx.result);
}
}
},
});No declarative key refuses two overlapping leave requests of one person; copy
this hook, renaming its name, object and fields (date fields: set DATE_ONLY).
import { defineHook } from '@objectstack/spec/data';
export default defineHook({
name: 'leave_request_no_overlap',
object: 'leave_request',
events: ['beforeInsert', 'beforeUpdate'],
runAs: 'system', // count the rows the saver cannot read too
refusals: { OVERLAP: { message: 'This overlaps another request of yours.', status: 409 } },
body: {
language: 'js',
capabilities: ['api.read'],
source: `
const DATE_ONLY = false; // true when start_at / end_at are date fields: the end day is booked too
const r = Object.assign({}, ctx.previous, ctx.input); // update: stored row under the patch
const off = ['rejected', 'cancelled'];
if (!r.owner_id || !r.start_at || !r.end_at || off.includes(r.status)) return;
const where = {
owner_id: r.owner_id,
status: { $nin: off }, // fail closed: a new status counts until listed here
start_at: DATE_ONLY ? { $lte: r.end_at } : { $lt: r.end_at }, // datetime is half-open:
end_at: DATE_ONLY ? { $gte: r.start_at } : { $gt: r.start_at }, // 18:00 end, 18:00 start is no overlap
};
if (ctx.previous) where.id = { $ne: ctx.previous.id }; // not the record itself
if (await ctx.api.object(ctx.object).count({ where }) > 0)
throw Object.assign(new Error(), { code: 'OVERLAP' });
`,
},
});Known limits: it is a read-then-write check, so two concurrent saves can both pass; a recycle-bin restore runs no insert hook; an import with automations off skips hooks; rows of one bulk insert or update do not see each other; and a row with no start or end is neither checked nor counted.
1. Declarative — defineStack({ hooks }), the default. AppPlugin auto-binds
these at startup: no register*Hook boilerplate, and the declarative fields
(condition, async, retryPolicy, timeoutMs, onError, priority) are honoured
only on this path. A string-named handler (deprecated) resolves through the stack's
functions map.
// objectstack.config.ts
export default defineStack({
hooks: [taskHook, { name: 'crm_h', object: 'account', events: ['beforeInsert'], handler: 'normalize' }],
functions: { normalize: async (ctx) => { /* ... */ } },
});2. Programmatic — ctx.ql.registerHook(), the plugin escape hatch. Pass
packageId so the hook can be unregistered cleanly. condition / retryPolicy / timeoutMs / onError /
async semantics — those apply only through defineStack({ hooks }) or
ql.bindHooks([...]).
// in your plugin's onEnable()
ctx.ql.registerHook('beforeInsert', async (hookCtx) => { /* ... */ },
{ object: 'account', priority: 100, packageId: 'my-plugin' });3. Hook files — src/objects/{object}.hook.ts. One defineHook({ ... }) per
file, default-exported, then listed in the stack's hooks array (method 1). This is
the layout both real hook modules in the repo use.
✅ DO — use before* for validation and after* for side effects; set
async: true for non-critical background work; go through ctx.api for
cross-object operations; refuse a business rule by a
declared code; test hooks in isolation.
❌ DON'T — do expensive work in before* (it blocks the transaction); let a
hook re-trigger itself; use object: '*' unless you mean every object; throw in
after* unless the failure must abort the operation; react to a refused or
rolled-back write from an async: true hook, which never runs then — use a sync
hook (its ctx.api writes roll back with the write) or record it in the caller,
where the write is made; assume ctx.session exists — system operations carry
no user.
A throw aborts the operation and rolls back its transaction; onError: 'log'
(above) makes an after* hook log and continue instead; neither gives the hook's own code.
A hook that enforces a business rule declares a refusals catalogue, one
SCREAMING_SNAKE code per rule, and the hook throws the code. Without one, a body's
throw is answered HOOK_ABORTED, the platform's code: fine for a failure you did not
plan, not for a rule the user can act on. A cross-object guard a validation rule
cannot read:
import { defineHook } from '@objectstack/spec/data';
export default defineHook({
name: 'checkout_requires_stock',
object: 'asset_checkout',
events: ['beforeInsert'],
refusals: {
ASSET_NOT_IN_STOCK: {
message: 'Only an in-stock asset can be checked out.',
status: 409,
params: ['due'],
reasons: { on_loan: { message: 'This asset is on loan until {{ due }}.' } },
},
},
body: {
language: 'js',
capabilities: ['api.read'],
source: `
const id = ctx.input.asset_id;
const asset = id && await ctx.api.object('asset').findOne({ where: { id } });
if (asset?.status === 'on_loan') throw Object.assign(new Error(),
{ code: 'ASSET_NOT_IN_STOCK', reason: 'on_loan', params: { due: asset.due_date } });
if (asset?.status !== 'in_stock') throw Object.assign(new Error(), { code: 'ASSET_NOT_IN_STOCK' });
`,
},
});- A
jsbodyor ahandler(inline or named) can declare one; anexpressionbody, or neither, is refused at save. - The wire
codeis the status's (default 400), with the hook's asdeclaredCode. reasons(snake_case, thrown asreason) add sentences that keep the code's wirecodeand status.paramsnames what a{{ name }}hole may fill (thrown asparams); a hole over any other name, or any hole with noparams, is refused.- Translated via
hooks.<hook>.refusals.<CODE>.message(or….<CODE>.reasons.<REASON>.message); the thrown text andstatusare unused. - An undeclared code (or none), or a reason missing from a code's
reasons, is refused: at save if thrown literally, else as a500. Unchangedctx.apierrors and crashes pass through.
node_modules/@objectstack/spec/src/data/hook.zod.ts— Hook schema definition, HookContext interface- objectstack-platform/references/plugin-hooks.md — plugin/kernel hooks (a different extension point)
- objectstack-automation — Flows and Workflows
- objectstack-platform/SKILL.md — hook test harnesses (vitest units,
LiteKernel)
body: { language: 'js', // 'js' = L2 sandboxed script | 'expression' = L1 pure formula source: "/* function body */", // the FUNCTION BODY only — not a module capabilities: ['api.read', 'api.write', 'log'], // default: [] timeoutMs: 250, // optional, ≤ 30000 (hook default 250ms, action 5000ms) memoryMb: 32, // optional, ≤ 256 (best-effort under QuickJS) }