66 online 3 members  + Join RP Base  +
FreeScript

norm

by JustGodWork  ·  version 2026.07.22  ·  updated 3 days ago

No reviews yet

Downloads
0
Reviews
0
Size
164 KB
Code check
Clean
Licence
MIT
Released
Nov 2026

A single-file, zero-dependency Lua ORM : relations, migrations, soft deletes, eager loading. Works on nanos world, FiveM, or plain Lua.

norm
Norm
A small, dependency-free Lua ORM with pluggable database adapters and
pluggable promise providers. It runs anywhere — nanos world,
FiveM, or plain Lua — by keeping framework specifics out of the core.

Full documentation: https://justgodwork.github.io/norm-docs/

  • Zero dependencies, one file. Ships as a single self-contained bundle;
light-class is embedded at build time.
  • **No runtime require, no cross-package import.** An internal module resolver makes
it work even on FiveM (which has no native require).
  • Promises your way. Every async operation returns a promise of your framework
(nanos, FiveM, or the bundled one) through a small provider seam, with a uniform
promise:await().
  • Fully typed. LuaCATS annotations throughout; :await() is narrowed to the
resolved type (User:find(1):await() → NormRecord?).

local db = Norm.new({
    adapter = Norm.adapters.nanos.new({ engine = DatabaseEngine.SQLite, connection = "./game.db" }),
})

local User = db:define("users", {
    id    = Norm.types.id(),
    name  = Norm.types.string({ length = 64, nullable = false }),
    email = Norm.types.string({ length = 128, unique = true }),
    coins = Norm.types.integer({ default = 0 }),
}, { timestamps = true })

coroutine.wrap(function()
    db:sync():await()                                   -- create tables once at boot

    local user = User:create({ name = "John", email = "[email protected]" }):await()
    user:increment("coins", 250):await()

    local rich = User:where("coins", ">", 100):order("coins", "DESC"):all():await()
end)()

An ORM talks to a database, so load Norm server-side only (nanos Server/,
FiveM server_script) — never as a shared/client script.
Install
Norm is one self-contained file: dist/norm.lua (or minified dist/norm.min.lua).
Loading it embeds light-class (global class), sets the global Norm, and returns it.

local Norm = dofile("dist/norm.lua")    -- plain Lua
local Norm = require "dist/norm.lua"    -- nanos (see the companion package `norm-nanos`)
server_script 'dist/norm.lua'           -- FiveM (fxmanifest.lua) — server only

Two abstractions: adapter + promise provider
Frameworks ship different promise implementations and database APIs, so Norm splits
two concerns. The ORM never builds a promise itself — it asks the provider and
resolves it with the already-transformed value, so providers need no chaining.

Concept, Answers, Built-ins

Adapter, How do I talk to the database?, nanos, oxmysql, or your own
Promise provider, Which promise type does this framework use?, builtin, nanos, cfx, or your own

local db = Norm.new({
    adapter            = Norm.adapters.oxmysql.new(),   -- or .nanos.new{...}, or a custom adapter
    -- promise         = Norm.promise.cfx(),            -- optional; defaults to the adapter's, else builtin
    -- log             = true,                          -- log every executed statement
    -- foreignKeys     = "auto",                        -- "auto" | true | false
    -- json            = "auto",                        -- "auto" | a provider | false
    -- queue_until_ready = false,                       -- hold ops until the first sync()/migrate()
})

Defining models
db:define(name, schema, options?) returns a model — your handle for everything.

local User = db:define("users", {
    id         = Norm.types.id(),                                 -- INT PK AUTO_INCREMENT
    name       = Norm.types.string({ length = 64, nullable = false }),
    email      = Norm.types.string({ length = 128, unique = true }),
    coins      = Norm.types.integer({ default = 0 }),
    bio        = Norm.types.text(),
    settings   = Norm.types.json(),                               -- Lua table  JSON string
    created_at = Norm.types.datetime({ default = Norm.types.raw("CURRENT_TIMESTAMP") }),
}, {
    timestamps   = true,          -- manage created_at / updated_at (Norm-side, UTC)
    soft_deletes = true,          -- add deleted_at; queries exclude trashed by default
    indexes      = { { columns = { "name" }, unique = false } },
})

Types (Norm.types): `id, integer, bigint, string, text, float, double, boolean,
datetime, date, json, enum, plus raw(sql)` for raw SQL defaults. Common options:
{ length, nullable, unique, index, primary, autoincrement, default } (plus values
for enum). enum({ values = { "a", "b" } }) is native ENUM on MySQL and
TEXT CHECK (… IN …) on SQLite.

Define options: timestamps, soft_deletes, hooks, scopes, indexes
(see the matching sections below).
CRUD
```lua
local u = User:create({ name = "Zoe" }):await() -- build + INSERT, id populated
local u = User:build({ name = "Zoe" }) -- unsaved; persist later with :save()
u.coins = u.coins + 10; u:save():await() -- INSERT if new, UPDATE if loaded (dirty-tracked)
u:reload():await() -- re-read columns from the DB
u:delete():await() -- DELETE (soft delete if enabled)

local one = User:find(1):await() -- by primary key -> record | nil
local byEm = User:find_by({ email = "[email protected]" }):await()
local all = User:all():await()
local n = User:count():await()

-- find-or-create family
User:find_or_create({ account_id = id }, { name = "Guest" }):await()
User:update_or_create({ account_id = id }, { last_seen = ts }):await()
User:find_or_new({ email = e }, { name = "Anon" }):await() -- unsaved if missing

-- atomic upsert (race-safe; needs a UNIQUE/PK on the conflict columns)
User:upsert({ account_id = id, name = nick }, { conflict = { "account_id" } }):await()

-- bulk insert (one statement). { records = true } returns records with ids (RETURNING).
User:insert_many({ { name = "a" }, { name = "

…