Documentation / @zerotal/audit / Auditor
Class: Auditor
Defined in: audit/src/Auditor.ts:30
Core audit service — record events, query history.
Resolved from the container as 'audit'. Access via the Audit facade
(import from @zerotal/audit) after AuditProvider is registered.
Constructors
Constructor
new Auditor(
driver,config):Auditor
Defined in: audit/src/Auditor.ts:31
Parameters
driver
config
Returns
Auditor
Methods
log()
Call Signature
log(
event,model,payload?):Promise<void>
Defined in: audit/src/Auditor.ts:54
Record a manual audit event.
Pass the model instance the event concerns — auditable_type and
auditable_id are derived from it, so logs are always linked to a record (no
orphans) and you never hand-write the type string:
Parameters
event
string
model
payload?
Returns
Promise<void>
Examples
await Audit.log("login.success", user, { tags: { method: "github_oauth" } });
await Audit.log("report.exported", report, { tags: { format: "csv", rows: 5000 } });
For an event not tied to a model, pass a raw payload with `auditable_type`:
await Audit.log("cache.flushed", { auditable_type: "System" });
Call Signature
log(
event,payload):Promise<void>
Defined in: audit/src/Auditor.ts:55
Record a manual audit event.
Pass the model instance the event concerns — auditable_type and
auditable_id are derived from it, so logs are always linked to a record (no
orphans) and you never hand-write the type string:
Parameters
event
string
payload
Omit<AuditPayload, "event">
Returns
Promise<void>
Examples
await Audit.log("login.success", user, { tags: { method: "github_oauth" } });
await Audit.log("report.exported", report, { tags: { format: "csv", rows: 5000 } });
For an event not tied to a model, pass a raw payload with `auditable_type`:
await Audit.log("cache.flushed", { auditable_type: "System" });
historyFor()
historyFor(
type,id,limit?):Promise<AuditRecord[]>
Defined in: audit/src/Auditor.ts:79
Return the audit history for a specific model instance.
Parameters
type
string
id
string | number
limit?
number = 50
Returns
Promise<AuditRecord[]>
Example
const history = await Audit.historyFor("User", user.id, 25);
logs()
logs(
model,id):ModelQueryBuilder<AuditLog>
Defined in: audit/src/Auditor.ts:93
A chainable query of the audit logs for a model instance. Pass the model class
(its name / auditType is used) or a literal type string, plus the id.
Parameters
model
id
string | number
Returns
Example
const logs = await Audit.logs(User, 1).desc().limit(25).get();
const page = await Audit.logs(User, 1).orderBy("id", "desc").paginate(20, 1);
logsByActor()
logsByActor(
actorId):ModelQueryBuilder<AuditLog>
Defined in: audit/src/Auditor.ts:105
A chainable query of every audit log recorded by a given actor.
Parameters
actorId
number
Returns
Example
const actorLog = await Audit.logsByActor(user.id).desc().get();
logsOfEvent()
logsOfEvent(
event):ModelQueryBuilder<AuditLog>
Defined in: audit/src/Auditor.ts:115
A chainable query of every audit log for a given event name.
Parameters
event
string
Returns
Example
const loginEvents = await Audit.logsOfEvent("login.success").get();
_recordModel()
_recordModel(
payload):Promise<void>
Defined in: audit/src/Auditor.ts:125
Record a model lifecycle event. Called by AuditObserver. Automatically enriches the payload with request metadata when available.
Parameters
payload
Returns
Promise<void>