NestJS Drizzle CRUD events and audit logs

NestJS Drizzle CRUD events in nestjs-drizzle-crud are module-level notifications raised before and after every write. Turn on hooks.enableGlobalHooks, and every service publishes a before event and an after event on one CrudEventBus for create, update, upsert, soft delete, restore, delete, attach, detach and sync. A mass write raises one pair for the whole batch. Subscribe once and you see every entity, which is what an audit log or a cache needs.

How do I turn on CRUD events?Copy Anchor Link

DrizzleCrudModule.forRoot({
  dialect: "postgresql",
  connectionString: process.env.DATABASE_URL,
  hooks: {
    enableGlobalHooks: true,
    subscribers: [
      { afterWrite: (e) => console.log(e.entity, e.operation, e.ids) },
    ],
  },
});

import { Inject, Injectable, type OnModuleInit } from "@nestjs/common";
import { CrudEventBus, DRIZZLE_DB } from "@avytrix/nestjs-drizzle-crud";
import { auditLog } from "./db/schema";

@Injectable()
export class AuditService implements OnModuleInit {
  constructor(
    private readonly bus: CrudEventBus,
    @Inject(DRIZZLE_DB) private readonly db: any,
  ) {}

  onModuleInit() {
    this.bus.subscribe({
      afterWrite: async (event) => {
        const db = event.transaction ?? this.db;
        await db.insert(auditLog).values({
          entity: event.entity,
          operation: event.operation,
          ids: event.ids.map(String),
        });
      },
    });
  }
}

What does a subscriber look like?Copy Anchor Link

An object of optional listener methods. beforeWrite and afterWrite see every operation; the named methods see one:

entities: ["posts", "authors"] limits a subscriber to those table names. Subscribers run one after another in the order they subscribed, and every listener is awaited. Within one subscriber, beforeWrite or afterWrite runs before the named method.

What is in an event?Copy Anchor Link

Every listener receives one CrudEvent:

interface CrudEvent<T = any> {
  entity: string;            // the table name
  operation: "create" | "update" | "upsert" | "softDelete" | "restore"
    | "delete" | "attach" | "detach" | "sync";
  phase: "before" | "after";
  bulk: boolean;             // true for the mass methods
  ids: unknown[];            // primary keys; empty before a create or upsert
  input?: unknown;           // the DTO, the array of DTOs, or the related ids
  rows: T[];                 // after: the rows as stored; empty for deletes
  transaction?: unknown;     // the transaction the write runs in, if any
  context?: Record<string, unknown>; // options.context or CrudContext
}

A force delete is reported as delete. context is the call's options.context, or the CrudContext of the request, so an audit row can record the tenant or user.

How do bulk writes raise events?Copy Anchor Link

Once per call. A mass write raises one before event and one after event with bulk: true, every id in ids and every written row in rows, from inside its transaction. A massUpdate of 500 rows is two events, not a thousand.

With bulkMode: "perItem" each item goes through the single-row method instead, so you get one pair of events per item with bulk: false. See Bulk operations.

Can a listener stop a write?Copy Anchor Link

Yes, a before listener can. If it throws, nothing is written and the caller gets the error (a Nest HttpException keeps its status). An after listener that throws inside a transaction rolls the write back. Every mass write runs in a transaction; a single write only does when you pass one in options.transaction.

How do I bust a cache on write?Copy Anchor Link

Subscribe to the entity and drop the keys its ids touch:

this.bus.subscribe({
  entities: ["products"],
  afterWrite: (e) => {
    for (const id of e.ids) this.cache.delete(`product:${id}`);
    this.cache.delete("products:list");
  },
});

How do events relate to the per-service hooks?Copy Anchor Link

They are separate and both run. The protected hooks on a service (beforeCreate, afterUpdate and the rest) run per row and follow options.hooks.skipBefore / skipAfter. Events run once per call and follow options.skipEvents instead, so skipping a hook never silently skips the audit trail. See Drizzle hooks and validation in NestJS.

How do I use events without the module?Copy Anchor Link

Pass a bus in the config when you build a service by hand, as in tests:

const bus = new CrudEventBus();
bus.subscribe({ afterWrite: (e) => seen.push(e) });
const posts = new PostsService({ ...config, events: bus });

Common questionsCopy Anchor Link

Next stepsCopy Anchor Link