Types & Options

Option tables and value shapes referenced throughout the API.

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.

NormOptions

🔗 Source: src/orm.lua

Member	Returns	Description
adapter	—	Required.
foreignKeys	—	Emit SQL FOREIGN KEY constraints from belongsTo relations.
json	—	JSON provider for json columns.
log	—	Log every executed statement.
logger	—
promise	—	Promise provider.
queue_until_ready	—	Hold data operations in a queue until the first successful sync()/migrate(), then flush them (default false: run immediately).

adapter field

NormAdapter

Required. An adapter instance (or duck-typed table).

foreignKeys field

(boolean|"auto")?

Emit SQL FOREIGN KEY constraints from belongsTo relations. "auto" (default) emits on MySQL, skips on SQLite (with a one-time warning); true always emits; false never emits (no warning).

json field

("auto"|NormJsonProvider|false)?

JSON provider for json columns. "auto" (default) uses the adapter's, else auto-detects (Nanos JSON / Lua json), else raw passthrough; false disables (de)serialisation.

log field

boolean?

Log every executed statement.

logger field

fun(level: string, message: string)?

promise field

NormPromiseProvider?

Promise provider. Defaults to the adapter's, else built-in.

queue_until_ready field

boolean?

Hold data operations in a queue until the first successful sync()/migrate(), then flush them (default false: run immediately).

NormDefineOptions

Options controlling how a model behaves (3rd arg of define).

🔗 Source: src/model.lua

Member	Returns	Description
hooks	—	Lifecycle hooks per event (see NormModel:hook), as a single handler or a list.
indexes	—	Table indexes emitted at sync() (composite via columns, single via column).
scopes	—	Named reusable query fragments (see NormModel:scope).
soft_deletes	—	Mark rows deleted (set a deleted_at) instead of removing them; queries then exclude them by default.
timestamps	—	Auto-manage created_at/updated_at (Norm-side, UTC; portable across SQLite/MySQL).

hooks field

table<string, fun(record: NormRecord)|fun(record: NormRecord)[]>?

Lifecycle hooks per event (see NormModel:hook), as a single handler or a list.

indexes field

{ columns: string[], column: string, unique: boolean, name: string }[]?

Table indexes emitted at sync() (composite via columns, single via column).

scopes field

table<string, fun(query: NormQueryBuilder, ...any)>?

Named reusable query fragments (see NormModel:scope).

soft_deletes field

(boolean|{ column: string })?

Mark rows deleted (set a deleted_at) instead of removing them; queries then exclude them by default. true uses deleted_at; pass a table to rename.

timestamps field

(boolean|{ created: string, updated: string })?

Auto-manage created_at/updated_at (Norm-side, UTC; portable across SQLite/MySQL). true uses the default names; pass a table to rename.

NormColumn

🔗 Source: src/types.lua

Member	Returns	Description
autoincrement	—
default	—	Literal value, or Norm.types.raw(...) for raw SQL.
index	—	Emit a (non-unique) index on this column at sync().
kind	—
length	—	Length for VARCHAR columns.
name	—	Set by define() from the schema key.
nullable	—	Defaults to true (false for primary keys).
primary	—
unique	—

autoincrement field

boolean?

default field

any

Literal value, or Norm.types.raw(...) for raw SQL.

index field

boolean?

Emit a (non-unique) index on this column at sync().

kind field

NormColumnKind

length field

number?

Length for VARCHAR columns.

name field

string?

Set by define() from the schema key.

nullable field

boolean?

Defaults to true (false for primary keys).

primary field

boolean?

unique field

boolean?

NormColumnOptions

🔗 Source: src/types.lua

Member	Returns	Description
autoincrement	—
default	—	Literal value, or Norm.types.raw(...) for raw SQL.
index	—	Emit a (non-unique) index on this column at sync().
length	—	Length for VARCHAR columns.
nullable	—	Defaults to true (false for primary keys).
primary	—
unique	—

autoincrement field

boolean?

default field

any

Literal value, or Norm.types.raw(...) for raw SQL.

index field

boolean?

Emit a (non-unique) index on this column at sync().

length field

number?

Length for VARCHAR columns.

nullable field

boolean?

Defaults to true (false for primary keys).

primary field

boolean?

unique field

boolean?

NormRelationOptions

🔗 Source: src/types.lua

Member	Returns	Description
key	—	FK column name.
localKey	—	Local column for has_*/belongs_to_many (defaults to this model's primary key).
onDelete	—	Emitted as ON DELETE … on the FK (belongs_to only).
onUpdate	—	Emitted as ON UPDATE … on the FK (belongs_to only).
otherKey	—	Referenced column / target-side pivot FK (defaults to the relevant primary key).
otherLocalKey	—	Target's local column for belongs_to_many (defaults to the target's primary key).
through	—	Pivot (join) table for belongs_to_many (defaults to the two singulars joined alphabetically).

key field

string?

FK column name. See each relation for its default.

localKey field

string?

Local column for has_*/belongs_to_many (defaults to this model's primary key).

onDelete field

NormReferentialAction?

Emitted as ON DELETE … on the FK (belongs_to only).

onUpdate field

NormReferentialAction?

Emitted as ON UPDATE … on the FK (belongs_to only).

otherKey field

string?

Referenced column / target-side pivot FK (defaults to the relevant primary key).

otherLocalKey field

string?

Target's local column for belongs_to_many (defaults to the target's primary key).

through field

string?

Pivot (join) table for belongs_to_many (defaults to the two singulars joined alphabetically).

NormMigration

🔗 Source: src/orm.lua

Member	Returns	Description
id	—	Unique, stable identifier (applied once).
up	—	Receives the schema builder; record changes via m:add_column(...) etc.

id field

string

Unique, stable identifier (applied once). Order them by sorting-friendly ids.

up field

fun(m: table)

Receives the schema builder; record changes via m:add_column(...) etc.

NormForeignKey

A foreign-key constraint to emit inside CREATE TABLE.

🔗 Source: src/sql.lua

Member	Returns	Description
column	—	FK column on this table.
on_delete	—	Referential action (e.g.
on_update	—	Referential action (e.g.
ref_column	—	Referenced column.
ref_table	—	Referenced table.

column field

string

FK column on this table.

on_delete field

string?

Referential action (e.g. "CASCADE").

on_update field

string?

Referential action (e.g. "CASCADE").

ref_column field

string

Referenced column.

ref_table field

string

Referenced table.

NormExecResult

🔗 Source: src/adapter.lua

Member	Returns	Description
affectedRows	—
insertId	—

affectedRows field

number?

insertId field

any

NormQueryState

🔗 Source: src/sql.lua

Member	Returns	Description
columns	—	Selected columns (nil = "*").
groups	—	GROUP BY columns.
havings	—	HAVING conditions (ANDed).
joins	—	JOIN clauses.
limit	—
offset	—
orders	—
raw_columns	—	Raw (unquoted) select expressions, e.g.
table	—
wheres	—

columns field

string[]?

Selected columns (nil = "*").

groups field

string[]?

GROUP BY columns.

havings field

NormHaving[]?

HAVING conditions (ANDed).

joins field

NormJoin[]?

JOIN clauses.

limit field

number?

offset field

number?

orders field

NormOrder[]?

raw_columns field

string[]?

Raw (unquoted) select expressions, e.g. "COUNT(*) AS n".

table field

string

wheres field

NormWhere[]

NormDialect

🔗 Source: src/dialect.lua

Member	Returns	Description
autoincrement	—
name	—
placeholder	—
quote	—
table_suffix	—
types	—

autoincrement field

string

name field

string

placeholder field

fun(index: number):string

quote field

fun(id: string):string

table_suffix field

string

types field

table<string, string>

NormPromiseProvider

A promise provider plugs a framework's promise type into Norm. Built-in builders: Norm.promise.builtin|nanos|cfx. Validate a custom one with Norm.promise.define.

🔗 Source: src/promise.lua

Member	Returns	Description
is_promise	—
name	—
new	—	Returns a framework promise.
reject	—	Already-rejected promise.
resolve	—	Already-resolved promise.

is_promise field

(fun(value: any):boolean)?

name field

string

new field

fun(executor: fun(resolve: fun(value: any), reject: fun(reason: any))):any

Returns a framework promise.

reject field

fun(reason: any):any

Already-rejected promise.

resolve field

fun(value: any):any

Already-resolved promise.

NormJsonProvider

A JSON provider plugs a host's JSON library into Norm.

🔗 Source: src/json.lua

Member	Returns	Description
decode	—
encode	—
name	—

decode field

fun(text: string):any

encode field

fun(value: any):string

name field

string