Skip to content

Know who changed what in your NestJS app. ​

@nestarc/audit-log records business events in PostgreSQL or SQL Server, with automatic Prisma field changes on PostgreSQL. Start with one workflow, verify the actor and before/after values, then expand coverage.

Published 0.9.0 · What's new · API reference

See the change, and who made it ​

In the runnable example, a user starts as a member. An HTTP request changes their role to admin, producing an automatic audit record with the request's demo actor and tenant context.

Expected fields from the role-change record; the generated user ID varies:

json
{
  "action": "User.updated",
  "source": "auto",
  "actorId": "demo-user",
  "tenantId": "demo-tenant",
  "targetType": "User",
  "targetId": "<generated-user-id>",
  "changes": {
    "role": { "before": "member", "after": "admin" }
  }
}

With atomic-required, supported business writes and their automatic audit records commit or roll back together inside withAuditTransaction(). The example verifies both the successful change and rollback.

Start where it helps today ​

Log one business event ​

Capture an approval, role change, or export with a manual event. Use AuditService.withManualTransaction() to bind business writes and events to one transaction. Without delivery configured, you can also keep an existing transaction and pass its tx to AuditService.log(). Your application chooses the event name and metadata.

Add a manual event →

Choosing your first workflow? Read Start Your NestJS Audit Trail with One Business Event for a role-change example and a practical adoption checklist.

Track one Prisma model ​

Select a model with trackedModels: ['User'], then move its selected write path into an audited transaction. The extension produces field-level before/after changes automatically.

Track a model →

Both paths include actor and tenant context, sensitive-field masking, and an API to query the recorded history. The Quick Start lets you compare the two before changing your app.

What's new in 0.9.0 ​

  • Stage audit delivery atomically. Opt into createOutboxAuditDelivery() to commit a business change, audit row, and Outbox event in the same PostgreSQL transaction.
  • Recover after commit. An Outbox worker delivers a fixed summary with stable audit identity; consumers deduplicate at-least-once delivery by tenant and audit ID.
  • Keep existing adoption paths. Without delivery, existing manual, automatic, SQL Server, export, and stream APIs retain their behavior.

Follow Atomic Outbox Delivery for the released audit-log 0.9.0 / Outbox 0.4.1 example, payload limits, and managed transaction requirements. Read Migrating to 0.9.0 before enabling delivery. Soft-delete 0.7.6 still requires the separately pinned audit-log 0.8.0 lifecycle recipe below.

Introduced in 0.8.0 ​

  • Manage manual transactions. withManualTransaction() supplies a typed tx and bound log. Audit failures prevent commit even when caught inside the callback.
  • Validate event quality. Opt into strictManualValidation and a maxMetadataBytes budget. Invalid inputs expose structured AuditInputError diagnostics before INSERT.
  • Observe outcomes. onAuditOperation reports manual log and managed transaction outcomes without event contents. getCapabilities() reports the configured provider's API support without database I/O.
  • Read SQL Server history. Use tenant-scoped query() and getById(), optional read indexes, and read-only storage inspection. See the SQL Server guide.

These 0.8.0 capabilities remain available in 0.9.0. Caller-owned manual transactions require delivery to be omitted; the new delivery path uses the managed helper's bound writer.

Fit and supported scope ​

The package supports NestJS 10, 11, or 12.0.1+ and Node.js 22.23.4+ within 22.x or 24.22.1+ within 24.x. PostgreSQL is the default provider; SQL Server supports manual logging, managed manual transactions, and history reads. Prisma 7 is the primary target; Prisma 5/6 retain peer compatibility. The runnable example pins NestJS 12.1.1 and Prisma 7.9.1. An existing Prisma 5/6 app can keep its client setup.

Supported: transaction-first automatic tracking

The Supported claim applies to supported tracked operations through withAuditTransaction() with consistency: 'atomic-required'. Tracked writes outside the helper fail before execution. Base-client writes, raw SQL, and database cascades are outside automatic coverage; review nested and bulk operations before extending adoption.

Explicit best-effort is non-atomic and outside that support claim. It can leave success records after a caller rolls back, or produce stale transaction-local diffs. For manual events, use withManualTransaction() to reject commit after caught audit failures. Without delivery, caller-owned transactions can await log(input, tx) and propagate failures to roll back the business change. With delivery enabled, use only managed manual writers or atomic-required automatic tracking. SQL Server automatic tracking, Outbox delivery, scan/export, retention, and partitioning remain unsupported.

Grow after the first verified record ​

  • NestJS audit log code example — follow a role change from request to recorded history.
  • Installation — shared configuration, audit storage, and NestJS wiring.
  • SQL Server — manual transactions, history queries, storage setup, and provider limits.
  • Query API — tenant-scoped history, filters, and keyset pagination.
  • Atomic Outbox Delivery — stage new audit events with the producer transaction and recover downstream delivery.
  • Streaming export and durable streams — exports and checkpointed delivery, including polling limits.
  • Retention — append-only storage, privileges, and partition maintenance.
  • Soft-delete integration — separately pinned tenancy 0.16.4 / audit-log 0.8.0 / soft-delete 0.7.6 lifecycle recipe. Soft-delete 0.7.6 excludes audit-log 0.9.0.
  • Benchmark guide — measure the atomic path against an unaudited transaction.
  • Agent guide — version-pinned integration checklist for coding agents.

Documentation site: MIT License. Check each package for its license.