NormRecord class

A single row, returned by queries. Persist changes, reload, delete, and traverse relations.

Auto-generated

This page is generated from the source annotations by scripts/gen-api.mjs. Edit the LuaCATS doc comments in the Norm sources, not here.

A single row. Column values are plain fields (e.g. record.name).

🔗 Source: src/model.lua

Member	Returns	Description
attach	NormNumberPromise (async)	Link this record to one or more target rows of a belongs_to_many relation
decrement	NormRecordPromise (async)	Atomically subtract amount (default 1) from a column of this record.
delete	NormRecordPromise (async)	Delete this record.
detach	NormNumberPromise (async)	Unlink this record from target rows of a belongs_to_many relation by
force_delete	NormRecordPromise (async)	Physically DELETE this record by its primary key, even on a soft-delete model.
increment	NormRecordPromise (async)	Atomically add amount (default 1) to a column of THIS record
load	NormPromise (async)	Lazily load a declared relation, cache it on self[name], and resolve with
reload	NormRecordPromise (async)	Re-read this record's columns from the database (discarding local changes).
restore	NormRecordPromise (async)	Un-delete a soft-deleted record (clears deleted_at).
save	NormRecordPromise (async)	Persist the record: INSERT if new, UPDATE (only changed columns) if it was
sync_pivot	NormPromise (async)	Make this record's pivot links for a belongs_to_many relation exactly match
to_table	table<string, any>	Plain { column = value } table for this record (e.g.
trashed	boolean	Whether this record is currently soft-deleted (its deleted_at is set).

attach async method

NormRecord:attach(name: string, ids: any, pivot?: table<string, any>)
  -> promise: NormNumberPromise

Link this record to one or more target rows of a belongs_to_many relation by inserting pivot rows. ids is a key value, an array of them, or record(s). pivot adds extra columns to each pivot row. Resolves with the number attached.

    user:attach("roles", { 1, 2 }):await()
    user:attach("roles", role, { granted_by = adminId }):await()

decrement async method

NormRecord:decrement(column: string, amount?: number)
  -> promise: NormRecordPromise

Atomically subtract amount (default 1) from a column of this record.

delete async method

NormRecord:delete()
  -> promise: NormRecordPromise

Delete this record. For a soft-delete model this sets the deleted_at column (the row stays, but queries exclude it by default); otherwise it physically removes the row. Resolves with the record.

    local user = User:find(1):await()
    user:delete():await()

detach async method

NormRecord:detach(name: string, ids?: any)
  -> promise: NormNumberPromise

Unlink this record from target rows of a belongs_to_many relation by deleting pivot rows. With ids -> only those; without -> ALL links. Resolves with the affected row count.

    user:detach("roles", { 1 }):await()  -- remove one link
    user:detach("roles"):await()          -- remove every link

force_delete async method

NormRecord:force_delete()
  -> promise: NormRecordPromise

Physically DELETE this record by its primary key, even on a soft-delete model. The record is flagged not-persisted (a later :save() re-inserts it). Resolves with the record. Fires before_delete / after_delete.

increment async method

NormRecord:increment(column: string, amount?: number)
  -> promise: NormRecordPromise

Atomically add amount (default 1) to a column of THIS record (SET col = col + ? by primary key — no read-modify-write). Also updates the in-memory value when it is a number, and resnapshots. Resolves with the record.

    player:increment("coins", 50):await()  -- player.coins is updated locally too

load async method

NormRecord:load(name: string)
  -> promise: NormPromise

Lazily load a declared relation, cache it on self[name], and resolve with it. Returns a single record (belongs_to / has_one), nil, or an array (has_many).

    local author = post:load("author"):await()  -- also sets post.author
    local posts  = user:load("posts"):await()   -- also sets user.posts (array)

reload async method

NormRecord:reload()
  -> promise: NormRecordPromise

Re-read this record's columns from the database (discarding local changes). Resolves with the record.

    user:reload():await()

restore async method

NormRecord:restore()
  -> promise: NormRecordPromise

Un-delete a soft-deleted record (clears deleted_at). Resolves with the record.

    local post = Post:only_trashed():where("id", 5):first():await()
    post:restore():await()

save async method

NormRecord:save()
  -> promise: NormRecordPromise

Persist the record: INSERT if new, UPDATE (only changed columns) if it was loaded from the database. Resolves with the record itself.

    local user = User:find(1):await()
    user.coins = user.coins + 50
    user:save():await()

sync_pivot async method

NormRecord:sync_pivot(name: string, ids: any)
  -> promise: NormPromise

Make this record's pivot links for a belongs_to_many relation exactly match ids: attach the missing, detach the extra, leave the rest. Resolves with { attached = n, detached = m }.

    user:sync_pivot("roles", { 1, 2, 3 }):await()

to_table method

NormRecord:to_table()
  -> table<string, any>

Plain { column = value } table for this record (e.g. to serialise it).

    local data = user:to_table() --> { id = 1, name = "John", ... }

trashed method

NormRecord:trashed()
  -> boolean

Whether this record is currently soft-deleted (its deleted_at is set).