Audit logging

An audit log answers "who changed this row, when, and what did it look like
before?" — a different question from query logging, which only
records the statements that ran.

Prorm ships two implementations:

	`AuditLogger`	`@Audit` decorator
Where entries go	a database table	an in-memory array
Survives a restart	yes	no
Scope	every model on the connection, or chosen ones	one model class
Use for	compliance, forensics, change history	tests, local debugging

For regulated workloads that need tamper-evidence, retention policy and DSAR
support, see Compliance — AuditTrail, WORMStorage and
ImmutableRecord build on the same idea with stronger guarantees.

Every AuditLogger entry also carries a level (info by default; warning,
critical, outage…) chosen by an explicit call, an @AuditLevel decorator or
an escalation rule — see Audit levels & escalation
for levels, escalation policies, presets, aggregation and retention by level.

`AuditLogger`

import { AuditLogger, setAuditLogger } from 'ts-prorm-orm';

const audit = new AuditLogger(prorm, {
  tableName: 'AuditLogs',                       // default
  modelName: 'AuditLog',                        // default
  userIdGetter: () => currentRequest()?.userId, // called per entry
  ipAddressGetter: () => currentRequest()?.ip,
});

audit.setupHooks();     // hook every model registered so far
setAuditLogger(audit);  // make it the process-wide logger

setupHooks() walks prorm.getModels() and attaches hooks to each. Models
defined after that call need audit.addHooksToModel(Model); hasHooks(Model)
tells you whether one is already covered, and a model is never hooked twice.

Who and where, per request

userIdGetter and ipAddressGetter are called once per entry, inside the
hook, so they have to find the current request without being handed it. In a
Node server, AsyncLocalStorage carries it across every await between the
route handler and the hook:

import { AsyncLocalStorage } from 'node:async_hooks';
import { AuditLogger, setAuditLogger } from 'ts-prorm-orm';

interface RequestContext {
  userId?: string;
  ip?: string;
}

export const requestContext = new AsyncLocalStorage<RequestContext>();

// Express-style middleware: everything this request awaits sees the store.
export function withRequestContext(req: any, _res: any, next: () => void): void {
  requestContext.run({ userId: req.user?.id, ip: req.ip }, next);
}

export const audit = new AuditLogger(prorm, {
  userIdGetter: () => requestContext.getStore()?.userId,
  ipAddressGetter: () => requestContext.getStore()?.ip,
});
audit.setupHooks();
setAuditLogger(audit);

A write made outside any request (a cron job, a queue consumer) gets
userId: null. Wrap those in requestContext.run({ userId: 'system:billing-cron' }, …)
so the audit table never has an anonymous row you cannot explain.

The audit table

The first write defines and creates the model if it does not exist:

That is the statement SQLite receives (read back from sqlite_master after
new AuditLogger(prorm) and prorm.sync()), broken over lines; on
PostgreSQL action is an ENUM and oldValues / newValues are JSON.
The last six columns belong to audit levels and escalation;
an audit table created before they existed gets them from
prorm.sync({ alter: true }).

The model is defined with timestamps: false, and recordId / userId are
strings so any primary-key type fits. ipAddress is 45 characters — enough for
an IPv6 address. Pass new AuditLogger(prorm, { underscored: true }) for
snake_case columns (table_name, record_id, old_values, incident_id, …);
entries still read back with the camelCase names above.

What gets captured

Hook	`action`	`oldValues`	`newValues`
`beforeCreate`	`CREATE`	—	the new row
`beforeUpdate`	`UPDATE`	the previous values	the new row
`beforeDestroy`	`DELETE`	the row as it stood	—

Entries are written from before* hooks, so an audit row exists even if the
write then fails — you get a record of the attempt. Values come from
instance.toJSON(), which means hidden attributes stay hidden and virtual
fields are included.

[!WARNING] Bulk statements
Because capture is hook-based, it sees instance writes. Static bulk
statements (Model.update({…}, { where }), Model.destroy({ where }),
bulkCreate without individualHooks) do not construct instances and so are
not captured. Route audited changes through instances, or call
logAction() yourself.

Reading the history

import { AuditLogger } from 'ts-prorm-orm';

const audit = new AuditLogger(prorm);
const history = await audit.getHistory('users', 42, {
  limit: 50,
  offset: 0,
  startDate: new Date('2026-01-01'),
  endDate: new Date(),
});

Omit recordId for the whole table's history. The default page is 100 entries,
newest first.

Each entry reads back with its values parsed. The history of invoice 2 after
one save() that changed its total:

Audit-log queries

The questions people ask of an audit table are rarely "the history of one
row". The aggregation helpers from audit levels and escalation
answer the others through the ORM's query API, so they work on every dialect:

import { AuditLogger, recentAuditEntries, countAuditEntries, topNoisySources } from 'ts-prorm-orm';

const audit = new AuditLogger(prorm);
const since = new Date(Date.now() - 24 * 60 * 60 * 1000);

// Every delete on the billing tables in the last day, newest first.
const deletes = await recentAuditEntries(audit, {
  operations: ['DELETE'],
  models: ['invoices', 'payments'],
  since,
  limit: 200,
});
for (const e of deletes) console.log(e.timestamp, e.tableName, e.recordId, e.userId, e.ipAddress);

// How many writes each table took, per day.
await countAuditEntries(audit, { by: 'model', bucket: 'day', since });
// [{ bucket: '2026-09-26', model: 'invoices', count: 6 }]

// Which table and operation make the most noise.
await topNoisySources(audit, { since, limit: 3 });
// [{ model: 'invoices', operation: 'CREATE', count: 3, levels: { info: 3 }, maxLevel: 'info' }, …]

From a terminal, prorm logs tail reads the same table with the usual
connection flags:

$ prorm logs tail --dialect sqlite --database app.db --limit 3
time                      level     table     action  record  user   incident
2026-09-26T22:04:29.470Z  warning   invoices  DELETE  1       u_ada
2026-09-26T22:04:29.460Z  critical  invoices  DELETE  3       u_ada  inc_muixtdot_6a126a37
2026-09-26T22:04:29.424Z  info      invoices  UPDATE  2       u_ada

Logging by hand

import { AuditLogger } from 'ts-prorm-orm';

const audit = new AuditLogger(prorm);
await audit.logAction('UPDATE', 'users', 42, { plan: 'free' }, { plan: 'pro' });

Use this for changes that do not go through a model at all — a raw SQL fix-up, a
migration backfill, an action taken by an external system.

Convenience accessors

addAuditHistoryToModel(Model) and addAuditHistoryToInstance(prototype) graft
history methods on, resolved through the logger you registered with
setAuditLogger():

await User.getAuditHistory({ limit: 10 });          // whole table
await User.getAuditHistoryForRecord(42);            // one row
await user.getAuditHistory();                       // that instance's row

They throw AuditLogger not initialized. Call setAuditLogger() first. if no
logger has been registered.

The `@Audit` decorator

An in-memory change log for one class — no table, no persistence.

import { Audit, getAuditLog, clearAuditLog } from 'ts-prorm-orm';

@Audit({ trackFields: ['email', 'role'], userField: 'updatedBy' })
class User extends Model { /* … */ }

const entries = getAuditLog(User);
// [{ action: 'UPDATE', model: 'User', oldValues: {…}, newValues: {…}, user, timestamp }]

clearAuditLog(User);

Option	Effect
`tableName`	Label on entries. Default `'audit_log'`. Nothing is written to a table.
`trackFields`	Capture only these fields in `oldValues` / `newValues`.
`userField`	Attribute on the model holding the acting user.

getAuditOptions(User) reads the configuration back. Entries live for the
lifetime of the process — this is a debugging and testing aid, not a compliance
control.

Choosing a shape

Track everything on every model — new AuditLogger(prorm) +
setupHooks(). Simple, and the audit table grows with your write volume; plan
retention.

Track a few sensitive models — skip setupHooks() and call
addHooksToModel() for the ones that matter.

Track specific columns — @Audit({ trackFields }), or filter inside your
own logAction() call.

Need tamper-evidence — Compliance's AuditTrail and
WORMStorage.

Index the audit table on (tableName, recordId, timestamp); every read above
filters on exactly those columns.

Hooks — the mechanism this is built on

Logging — statement-level logging

Compliance — tamper-evident trails, retention, DSAR

Decorators — @Audit and friends

AuditLogger#

Who and where, per request#

The audit table#

What gets captured#

Reading the history#

Audit-log queries#

Logging by hand#

Convenience accessors#

The @Audit decorator#

Choosing a shape#

Related reading#