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
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.
Norm is one self-contained file:
Loading it embeds light-class (global
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?,
Promise provider, Which promise type does this framework use?,
Defining models
Types (
datetime, date, json, enum
for
Define options:
(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 = "
…
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;
- **No runtime
require, no cross-package import.** An internal module resolver makes
require).
- Promises your way. Every async operation returns a promise of your framework
promise:await().
- Fully typed. LuaCATS annotations throughout;
:await()is narrowed to the
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 (nanosInstallServer/,
FiveMserver_script) — never as a shared/client script.
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 onlyTwo 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 ownPromise 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 valuesfor
enum). enum({ values = { "a", "b" } }) is native ENUM on MySQL andTEXT 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 = "
…