DEV Community: Rodrigo Nogueira

The lockout bypass hiding in your login form

Rodrigo Nogueira — Mon, 20 Jul 2026 16:39:15 +0000

An application adds account lockout: five failed logins for a username, then a cooloff. It looks correct. It has a hole.

POST /login  { username: "Alice",  password: "..." }   // failure #1
POST /login  { username: "alice",  password: "..." }   // failure #1 (again)
POST /login  { username: "ALICE",  password: "..." }   // failure #1 (again)
POST /login  { username: "alice ", password: "..." }   // failure #1 (again)

If the login is case-insensitive but the lockout keys on the raw string, each spelling is a separate counter. The limit is per-spelling, so the attacker never trips it. Case and trailing whitespace alone multiply the effective budget several times over; add Unicode and it is worse.

This is a small bug with a large blast radius — precisely the kind of edge a lockout implementation has to normalize away. Python has django-axes for it. The NestJS ecosystem had no equivalent for the common case — lock on the database you already run, no Redis — so @nest-native/lockout (on a framework-agnostic core, @authlock/core) fills it.

The honest constraint first

django-axes can be nearly install-and-forget because Django emits an ambient user_login_failed signal it hooks into. NestJS has no equivalent signal bus. Any library that claims otherwise is hiding wiring somewhere. So this one doesn't claim it: the integration is explicit, and the docs lead with that.

You call it from your own login handler, at the point where the outcome is known:

async login(input: LoginInput, ip: string | undefined) {
  const identity = { username: input.username, ip };

  const gate = await this.lockout.check(identity); // pre-auth: is it locked?
  if (gate.locked) throw new TooManyRequests(gate.retryAfterMs);

  const user = await this.verify(input);
  if (!user) {
    await this.lockout.reportFailure(identity); // count it
    throw new Unauthorized();
  }
  await this.lockout.reportSuccess(identity);     // reset on success
}

Three explicit calls — check before the credential, reportFailure / reportSuccess after. There is a LockoutGuard for plain HTTP, and the same service works on tRPC, GraphQL, or a WebSocket, where a guard's body-reading extractor doesn't fit.

Closing the bypass

The opening bug is a one-line configuration once the library owns key derivation. Declare a per-dimension normalizer; it is applied to each value before the key is hashed, on every path (check, record, and reset), so the counter is shared and unlock works under any spelling:

LockoutModule.forRoot({
  store: new InMemoryLockoutStore(), // swap for a Drizzle store in production
  limit: 5,
  cooloffMs: 15 * 60_000,
  parameters: [['username'], ['ip']],
  normalize: { username: (v) => v.trim().toLowerCase() }, // ip left verbatim
});

Normalization is the app's decision — only you know which dimensions your auth treats as equal — so it is opt-in, but applied on every path (check, record, reset) rather than left to each call site.

The security details that are easy to get wrong

A lock trips if any configured key trips. With [['username'], ['ip']], a username lock catches a single-target attack even from rotating IPs, and an IP lock catches spraying across many usernames.
Cooloff is anchored to the last failure, not the window start. Every failed attempt during a lock re-anchors it, so an attacker can't get a free burst of guesses between a base lock and the next tier. The counting window is still measured from the first failure, which bounds how long a persistent attacker can keep a victim locked out.
Tiered cooloff is validated as monotonic. A schedule where failing more locks for less time would let an attacker self-unlock early; the constructor rejects it (along with duplicate or non-integer thresholds).
Fail-open by default. If the store errors, the attempt is allowed and logged — a database blip must not lock every user out. failMode: 'closed' is available when denying during an outage is the right trade-off.
Credentials never reach the store. Keys are SHA-256 hashes of the identity dimensions, so a raw username never appears in a row.
Cross-instance counting is atomic. The Drizzle stores (SQLite / Postgres / MySQL) increment through a single atomic create-or-increment-with-window-reset, so concurrent attempts across app instances count exactly once and can never overshoot the limit unnoticed. (MySQL re-reads the row afterward, since it has no RETURNING.)

Operations

reset(identity) unlocks one identity (an admin action, an unlock-via-email link). With single-dimension parameters, reset({ username }) already clears that user across every IP. For a false-positive lockout wave, resetAll() clears every counter at once.

There is no built-in audit log: the library stores only the counters it needs. An audit trail is built from what you already have — log each attempt at your own reportFailure / reportSuccess call site, and alert on the onLockout transition hook — recording identity dimensions only, never the credential.

What it is not

Not a rate limiter. Request-rate limiting is @nestjs/throttler; this is failed-authentication lockout. They compose.
Not a proxy-header parser. The default extractor uses req.ip, not X-Forwarded-For — trusting a spoofable header is how an attacker rotates past an IP lock or forges a victim's IP to lock them out. Configure trust proxy for your topology; the extractor is a hook, not a guess.
Not tied to a framework. The engine is zero-dependency and runs from Express or a bare script; @nest-native/lockout is a thin DI shell over it, built on stable NestJS primitives so the same code runs on NestJS 10, 11, and 12.

Case and whitespace aren't app-level afterthoughts — they are correctness properties of the lockout key, enforced where the library owns that key.

Adapter: @nest-native/lockout · engine: @authlock/core
Docs: nest-native.dev/lockout · source: github.com/nest-native/lockout

Not affiliated with the NestJS core team or the django-axes project.

Cache invalidation is the dual-write problem

Rodrigo Nogueira — Mon, 20 Jul 2026 05:33:25 +0000

Cache invalidation, in the form most backends actually meet it, is not a unique problem. It is the dual-write problem — the failure mode covered in the transactional outbox article — in different clothing:

// the dual-write problem, messaging edition
await db.insert(orders).values(input);        // 1. write the row
await kafka.send({ topic: 'order.placed' });  // 2. publish the event

// the dual-write problem, caching edition
await db.update(projects).set({ name });      // 1. write the row
await cache.del(`project:${id}`);             // 2. invalidate the cache

Same bug, both times. If the process crashes between step 1 and step 2, the database and the second system disagree, and nothing reconciles them. In the messaging edition, consumers silently miss an event. In the caching edition, every instance keeps serving the old value. A database and a cache cannot commit atomically, for the same reason a database and a broker cannot.

Messaging has a proven answer: the transactional outbox — one write, inside the transaction, with the second system driven from what committed. Caching mostly relies on TTLs.

The ecosystem today

What a survey of the ecosystem shows, before building anything new:

@nestjs/cache-manager (the official module, ~2M downloads/week) supports TTL, del, and clear. No tags, no cross-instance invalidation. Requests for richer features — an auto-invalidation strategy and hybrid multi-store caching — were both declined in the same month, with the same reply: "we'd encourage you to collaborate with the community on publishing it as an open source package."
Upstream, tag-based invalidation was requested in 2018 and shipped a first version in mid-2026 — a lazy version-check design, with no way to push an invalidation to other instances.
bentocache, the most architecturally complete Node cache (L1 memory + L2 store + a sync bus), supports Postgres as storage — but its invalidation bus requires Redis or MQTT. The coherence layer is the one piece that demands new infrastructure.
Rails 8 made a database-backed cache the default for new apps; Laravel 11 ships the database cache driver by default. Database-as-cache-infrastructure is mainstream — but neither framework pushes invalidations to in-memory tiers.

The missing piece: an in-memory cache per instance, kept coherent across instances through the database those instances already share, with the invalidation atomic with the write. That now exists as @stalefree/core, with a thin NestJS adapter, @nest-native/cache.

The same fix

On Postgres, pg_notify is transactional: a notification fired inside a transaction is delivered when the transaction commits, and silently dropped if it rolls back. That property removes the dual write. The invalidation is not a second system written after the database — it is part of the same commit:

await db.transaction(async (tx) => {
  await tx.update(projects).set({ name }).where(eq(projects.id, id));

  // both of these ride THIS transaction:
  await store.invalidateTagsInTx(tx, [`project:${id}`]); // shared L2 rows die with the commit
  await bus.publishInTx(tx, { tags: [`project:${id}`] }); // every instance's L1 evicts on commit
});

A crash before the commit means nothing happened — no write, no invalidation, no disagreement. When the commit lands, Postgres itself delivers the eviction to every instance holding a LISTEN connection. There is no window where the row changed but the invalidation was lost, because there were never two writes.

This is the outbox mechanism — pg_notify riding the business transaction — pointed at a different second system.

Tag-based invalidation

Exact-key invalidation breaks as soon as one mutation affects several cached reads: a renamed project appears in project:42, in org:7:projects, and in list views. Reads declare tags; mutations evict by tag:

const project = await cache.wrap(
  `org:${orgId}:project:${id}`,            // tenancy lives IN the key
  () => this.repo.findById(id),
  { ttlMs: 30_000, tags: [`org:${orgId}:projects`, `project:${id}`] },
);

// one call, after the mutation — evicts every carrier, on every instance
await cache.invalidateTags([`project:${id}`]);

wrap is read-through with single-flight: concurrent misses for a key share one loader run. The L1 keeps a reverse tag→keys index, so a tag eviction is O(affected entries), not O(cache size).

Two correctness rules

1. Every entry has a TTL — the API rejects infinite ones. The bus is best-effort by design; a listener mid-reconnect misses a message. The TTL is the delivery backstop: a lost invalidation means stale-until-TTL, never stale-forever. A cache whose correctness depends on a bus message arriving is a design bug, and the API makes that cache impossible to build.

2. Take atomicity where it is available. The transactional path is the strongest guarantee on offer and costs one line inside an existing transaction. Outside Postgres — or outside a transaction — invalidateTags still evicts locally, deletes L2 rows, and publishes, falling back from "atomic with the write" to "fire-and-forget with the TTL backstop."

Coherence by deployment shape

The bus is a seam; the implementation follows the deployment:

Deployment	Bus	Extra infrastructure
One process	none — coherent by definition	none
Several processes, one machine (the classic app + worker split)	a unix-domain-socket mesh with crash re-election	none
Several machines sharing Postgres	`LISTEN`/`NOTIFY`, transactional publish	none

The middle row covers SQLite completely: processes sharing a SQLite file are on one machine by definition, so the socket bus is the entire multi-process story for that dialect. The bottom row is the summary: cross-machine cache coherence, carried by a database already in production.

Degradation: on the socket bus, a frame too large for the wire is not dropped — it degrades on the send side to a full clear on every receiver (colder, never staler). On Postgres, large invalidations are chunked across multiple NOTIFY payloads.

Non-goals

Not a distributed cache, and not a Redis replacement for hot-path KV at massive scale. The target is the common case: expensive reads, tagged, evicted when the data changes.
Not exactly-once delivery of invalidations — the TTL backstop covers loss.
Single-flight is per-process; cross-instance stampede control is out of scope.
Cached values are held by reference in L1 — treat them as immutable.

A running example

The pattern runs as the newest chapter of the nest-native reference app: projects.* and activity.list are cached at the API seam, mutations invalidate by tag, and the activity feed's projection invalidates its own cache at the write site. The e2e spec runs with a deliberately long ten-minute TTL — when it asserts that a mutation is visible in the next read within seconds, only invalidation can make that pass, provably not expiry.

Cache invalidation remains hard in the general case. The version most backends face — a cached read, a database write, an instance serving the old value — is the dual-write problem, and the dual-write problem has a known fix: write to one system, and let the system that can commit atomically drive the other.

Core: @stalefree/core · adapter: @nest-native/cache
Docs: nest-native.dev/cache · source: github.com/nest-native/cache

Feedback and issues welcome — especially for cases the pattern does not cover.

The dual-write problem in NestJS, solved with Drizzle: a transactional outbox + idempotent inbox

Rodrigo Nogueira — Fri, 03 Jul 2026 22:00:26 +0000

Somewhere in most event-driven backends, there's a method that looks like this:

async placeOrder(input: PlaceOrderInput) {
  await this.db.insert(orders).values(input);          // 1. write the row
  await this.kafka.send({ topic: 'order.placed', … }); // 2. publish the event
}

It looks fine, and it has a bug. If the process crashes between 1 and 2, the order exists but the event never happened — downstream consumers silently miss it. Swap the order and you get the opposite failure: an event for an order that was rolled back. There is no try/catch arrangement that fixes this, because a database and a broker cannot commit atomically. This is the dual-write problem.

The boring, proven fix is the transactional outbox: don't publish in step 2. Instead, write the event into an outbox_events table in the same database transaction as the business row. A background worker then relays committed rows to the broker. The transaction is the only atomic boundary you have — so put both writes inside it.

That gives you at-least-once delivery, which means the consumer side needs the mirror-image pattern: an idempotent inbox that deduplicates redeliveries, so the side effect runs exactly once even when Kafka delivers twice.

@nest-native/messaging — part of nest-native, a set of NestJS integrations — packages this pair as a library, after the pattern was first built by hand inside a reference application. It's the outbox/inbox pattern for the Drizzle ORM + NestJS stack — a niche the existing NestJS outbox libraries (which target TypeORM and MikroORM — see nestjs-outbox and nestjs-inbox-outbox, both solid) don't cover.

The producer half: enqueue inside your transaction

The library ships the tables as Drizzle factories per dialect (SQLite, Postgres, MySQL). You add them to your schema and generate a migration like any other table:

// schema.ts
export { outboxEvents, inboxEvents } from '@nest-native/messaging/sqlite'; // or /postgres, /mysql

Transactions ride on @nestjs-cls/transactional with its Drizzle adapter — the same @Transactional() decorator you'd use anyway:

MessagingModule.forRoot({
  drizzleInstanceToken: DRIZZLE,          // your Drizzle DI token
  outboxStore: new SqliteOutboxStore(),   // or PostgresOutboxStore / MysqlOutboxStore
  inboxStore: new SqliteInboxStore(),
  transport,                              // where the claimer relays to — below
}),

Then the business code:

@Injectable()
export class OrderService {
  constructor(
    @InjectTransaction() private readonly db: AppDatabase,
    private readonly producer: OutboxProducer<SqliteOutboxStore>,
  ) {}

  @Transactional()
  placeOrder(id: string, item: string) {
    this.db.insert(orders).values({ id, item }).run();
    this.producer.enqueue({
      topic: 'order.placed',
      payload: { id, item },
      idempotencyKey: `order:${id}`,
    });
  }
}

The order row and the outbox row commit together, or roll back together. A throw after enqueue produces no phantom event; a crash after commit loses nothing, because the event is durably in your database.

(One nuance the library handles for you: better-sqlite3 transactions are synchronous while Postgres/MySQL are async. The per-dialect stores own that difference — on SQLite enqueue returns the row directly inside the sync transaction body; on Postgres you await it. Same code shape either way.)

Relaying: the claimer and the worker

A claimer polls for committed rows, publishes each through a transport, and applies retry-with-backoff on failure — including reclaiming rows from a worker that died mid-flight:

// scripts/start-worker.ts
const app = await NestFactory.createApplicationContext(AppModule);
await runWorkerLoop(app.get(OutboxClaimer), {
  pollIntervalMs: 2_000,
  signal: shutdownSignal, // AbortSignal wired to SIGTERM
});

A note on that pollIntervalMs, because a sharp question in the comments called it "a quiet latency knob": the loop is self-clocking. After a tick that claims a full batch it loops again immediately to drain the backlog; it only sleeps the interval when a tick claims nothing. So 2s is the worst case for a lone event landing in an otherwise-idle outbox — not a per-event tax — and under load, throughput is never gated by it.

When even that idle latency matters (something user-facing waiting behind an outbox event), lowering the interval works but has a floor and a DB-poll cost. As of 0.4.0 there's a better lever — an in-process wake:

const waker = new OutboxWaker();
runWorkerLoop(app.get(OutboxClaimer), { pollIntervalMs: 2_000, waker, signal });

// request path — right AFTER the enqueueing transaction commits:
waker.notify(); // the idle worker ticks now instead of on the next poll

Polling stays the backstop — a missed notify() only widens latency back to one interval, never drops an event — and wakes are latched, so a notify landing in the sliver between a tick and its sleep isn't lost.

Running the worker as a separate process on the same machine (the usual app + worker split)? The WakeSocketServer/WakeSocketClient pair carries the same wake over a unix domain socket — the worker feeds incoming connections into its waker, and the client's notify() is fire-and-forget, never throwing into the request path:

// worker process
await new WakeSocketServer({ path: env.wakeSocket, waker }).listen();

// app process — same path, right after the commit
new WakeSocketClient({ path: env.wakeSocket }).notify();

Workers on other machines (Postgres only, as of 0.5.0) get the wake through the one thing they already share — the database, via LISTEN/NOTIFY:

// producer side — one store option; pg_notify rides the enqueue transaction,
// so Postgres delivers the wake ON COMMIT and drops it on rollback: the signal
// is atomic with the event becoming visible, no post-commit discipline needed
new PostgresOutboxStore({ wakeChannel: 'outbox_wake' })

// worker side — a dedicated (non-pooled) LISTEN connection feeds the same waker
const listener = new PostgresWakeListener({
  connect: () => new pg.Client({ connectionString, keepAlive: true }),
  channel: 'outbox_wake',
  waker,
});
listener.start(); // reconnects on drops; await listener.stop() on shutdown

Missed notifications aren't recovered — polling remains the backstop, as with every tier.

For Kafka the transport is one line, built on @nest-native/kafka (Confluent's official JS client underneath):

MessagingModule.forRootAsync({
  drizzleInstanceToken: DRIZZLE,
  outboxStore: new SqliteOutboxStore(),
  inboxStore: new SqliteInboxStore(),
  inject: [KafkaProducerService],
  useTransport: (producer) => new KafkaOutboxTransport(producer),
}),

Don't have Kafka yet? There's an in-process transport (@nest-native/messaging/in-process) — a topic→handler registry with the same at-least-once semantics — so a modular monolith can adopt the pattern today and swap the transport for a broker later without touching a line of domain code.

The consumer half: exactly-once effects

Kafka is at-least-once by contract, so redelivery is a when, not an if. The inbox primitive is a single method:

const outcome = await inbox.runOnce(dedupKey, source, () => {
  // your side effect — runs in the SAME transaction as the dedup row
  this.audit.record({ … });
});
// 'processed' on the first delivery, 'duplicate' on any redelivery

runOnce inserts a (source, message_key) row protected by a unique index and runs your side effect in the same transaction. A redelivery violates the index → 'duplicate' → the side effect is skipped. If your side effect throws, the dedup row rolls back with it, so the retry reprocesses cleanly. That composition — unique index + shared transaction — is the entire trick, and it's provable in the database.

For Kafka consumers the library wraps the full delivery decision (validate → dedup → ack / dead-letter / redeliver) in an engine you delegate to from a thin @KafkaConsumer shell:

@KafkaConsumer('order.placed', { groupId: 'orders-service' })
export class OrderConsumer {
  constructor(private readonly inbox: KafkaInboxConsumer, private readonly audit: OrderAuditService) {}

  @KafkaHandler()
  async handle(@KafkaMessage() payload: unknown, @KafkaHeaders() headers: Headers, @KafkaCtx() ctx: KafkaContext) {
    await this.inbox.consume<OrderPlaced>({
      source: 'order.placed:orders-service',
      context: ctx, headers, payload,
      validate: isOrderPlaced,                                   // poison message → DLQ, then ack
      sideEffect: (order, dedupKey) => this.audit.record(order, dedupKey),
      dlqTopic: 'order.placed.DLQ',
    });
  }
}

Poison messages (unparseable, unkeyable) go to a dead-letter topic instead of redelivering forever; transient failures rethrow so the broker redelivers; duplicates ack silently.

Testing without a broker

Everything above runs in tests with no infrastructure: an in-memory outbox transport (@nest-native/messaging/testing) for the producer half, and @nest-native/kafka/testing's in-memory broker for the full pipeline — including redelivery:

await broker.emit('order.placed', publishedMessage); // redeliver the same message
await broker.idle();                                 // wait for handler pipelines to settle
expect(auditRows).toHaveLength(1);                   // side effect ran exactly once

The library itself is tested at 100% coverage against real SQLite, real in-process Postgres (pglite), and the in-memory broker — plus gated round-trips against real Postgres and MySQL containers.

See the whole thing running

The pattern is one chapter of a larger, runnable story: the nest-native reference app is a multi-tenant work-tracking SaaS where every task write emits task.created/assigned/completed through this outbox, a consumer builds an activity feed through this inbox, the event contracts are published as an AsyncAPI 3.0 catalog, and a streaming AI assistant summarizes the activity — eight libraries, one coherent journey, green tests, no Docker required for the default profile.

Honest scope

This is the app-level outbox. At larger scale you may prefer CDC (Debezium + Kafka Connect) tailing the WAL — different trade-offs, no app code, more infrastructure.
If you're on TypeORM or MikroORM, the libraries linked above already serve you well. @nest-native/messaging exists specifically because nothing covered Drizzle.
Delivery is at-least-once end to end; the inbox gives you exactly-once effects, which is the guarantee that actually matters — exactly-once delivery across a network isn't something any tool can promise.

Docs: nest-native.dev/messaging · Source: github.com/nest-native/messaging. Feedback and issues welcome — especially if you hit a case the pattern doesn't cover.

A NestJS reference app that proves seven nest-native libraries under realistic backend pressure

Rodrigo Nogueira — Mon, 25 May 2026 15:37:52 +0000

TL;DR: nest-native/reference-app is a production-shaped multi-tenant work-tracking SaaS — think a small Linear — that composes all seven nest-native libraries the way a real product would: Drizzle persistence, a typed tRPC API, domain events emitted in the same transaction as the writes, a Kafka backbone with exactly-once consumer effects, a published AsyncAPI 3.0 catalog, background jobs in the same database (no Redis), and a streaming AI assistant. Every guarantee has a test. It runs with zero infrastructure by default (SQLite, no broker, offline AI), and the same domain code runs against real Kafka by setting one env var.

The org, in one paragraph

nest-native publishes decorator-first NestJS integrations that should feel like official NestJS packages — modules, DI, decorators, guards/interceptors, lifecycle hooks — while staying honest about the tool underneath. Drizzle stays SQL-first; tRPC stays tRPC; the outbox is a real table, not magic. Every package ships with "dependencies": {} (you install only the peers you use), 100% test coverage as a hard CI gate, runnable samples, and documented non-goals.

The problem this app exists to solve

Library docs cover their slice; nobody covers the seams. And the seams are where backends actually get built:

How does "current user / current organization" reach a tRPC procedure, a guard, and a repository three calls deep — through one request-scoped mechanism?
How do I write a row and publish an event without a crash window between them?
How do consumers survive Kafka's at-least-once redelivery without double-applying effects?
How do I schedule deferred work — reminders, follow-ups — atomically with the write that caused it, without adding Redis to my stack just to run it?
Where do other teams find my event contracts — and how do I keep those contracts from drifting apart across producer, consumer, and docs?
How do I ship a streaming AI endpoint that tests offline, deterministically, in CI?

The reference app answers all of these in one codebase, as a coherent product rather than a pile of demos.

The story: one journey through seven libraries

The product is a multi-tenant work-tracking SaaS. Follow one journey and every library shows up exactly where a real system would reach for it:

An org invites a teammate — one @Transactional() method writes the user, membership, project, and audit rows and enqueues a user.invited event, atomically.
They work tasks — create → assign → complete; each write emits task.created / task.assigned / task.completed in the same transaction.
Events flow over the backbone — a background claimer relays committed events (in-process by default; Kafka in production), and consumers build an activity feed read-model, deduplicated against redelivery.
Assignment schedules deferred work — the same delivery that projects task.assigned into the feed also enqueues a delayed assignment-reminder job, in the same transaction, keyed by the same dedup key. A worker fires it exactly once when due. The queue is a table in the same database.
The contracts are published — an AsyncAPI 3.0 catalog at /asyncapi documents every event, generated from the same Zod schemas the code validates with.
AI reads the activity — a streaming assistant turns a project's recent activity into a status update, token by token.

Library	Its job in the story
`@nest-native/drizzle`	Persistence: repositories (`@DrizzleRepository`, `@InjectTransaction`), tenant-scoped queries, migrations
`@nest-native/trpc`	The typed API: `@Router`/`@Query`/`@Mutation`, generated `AppRouter`, superjson, guards
`@nest-native/messaging`	Reliable events: transactional outbox + idempotent inbox on Drizzle
`@nest-native/kafka`	The backbone: `KafkaOutboxTransport` + `@KafkaConsumer` read-models
`@nest-native/jobs`	Deferred work: the assignment reminder — enqueued transactionally, deduped, executed exactly once
`@nest-native/asyncapi`	The event catalog other teams integrate against
`@nest-native/ai-sdk`	The streaming assistant (`@AiStream`), offline-testable

The central proof: five writes, one transaction, zero lost events

The onboarding workflow is the crown jewel. inviteUser() writes five rows — user, membership, project link, audit event, and the outbox event — inside a single @Transactional() method:

@Transactional()
inviteUser(input: InviteUserInput) {
  const user = this.users.create(...);
  this.memberships.create(...);
  // ...audit row...
  this.outbox.enqueue({
    topic: 'user.invited',
    payload,                        // a plain typed interface — no casts
    idempotencyKey: `user.invited:${orgId}:${user.id}`,
  });
}

A throw anywhere rolls back everything — no phantom event. A crash after commit loses nothing — the event is durably in the database. The tests prove both directions (happy path, rollback safety, crash recovery), because "trust me" is not a delivery guarantee.

No lost events, no double effects

The dual-write problem ("write the row, then publish — and pray nothing crashes in between") is solved by @nest-native/messaging: the enqueue above is just an insert into an outbox_events table, and a background claimer relays committed rows with retry/backoff and stuck-claim recovery:

The consumer half is the mirror image: delivery is at-least-once by contract, so the idempotent inbox dedups redeliveries via a unique (source, message_key) row written in the same transaction as the side effect — exactly-once effects, provable in the database. The app's activity feed is built exactly this way, and the test suite redelivers messages on purpose and asserts the side effect ran once.

Two profiles, one codebase:

Default — no broker: the outbox dispatches through an in-process topic→handler registry (@nest-native/messaging/in-process). SQLite in a file. This is what CI runs.
Kafka — set KAFKA_BROKERS and the same domain code relays through KafkaOutboxTransport, with @KafkaConsumers (via @nest-native/kafka, on Confluent's official client) on the other side. Same event bodies, same dedup keys, same wire headers.

Deferred work in the same database (no Redis)

The newest library closes a gap the rest of the story kept pointing at: "…and then, later, do something." In NestJS the standard answer to reminders, follow-ups, and cleanups is BullMQ — which means running Redis. @nest-native/jobs puts the job queue in the database you already have (SQLite/Postgres/MySQL, on Drizzle), with @JobHandler classes, retry with backoff, scheduling, and unique-key dedup. If the lifecycle picture above looks like a job queue — that's because it is one: jobs runs the same hardened claim/retry engine the outbox relay proved in this app.

The app's use case: when a task is assigned, send a reminder later. The interesting part is where the job is created — inside the same transaction as the activity-feed projection of the task.assigned event:

@Transactional() // under Kafka this JOINS the inbox's dedup transaction
apply(payload: TaskAssignedPayload) {
  const activity = taskAssignedActivity(payload);
  const inserted = this.activity.record(activity); // (org_id, dedup_key) unique
  if (inserted) {
    this.jobs.enqueue({
      name: 'task.assignment-reminder',
      payload,                       // the event payload IS the job payload — one Zod contract
      delayMs: this.reminderDelayMs, // TASK_REMINDER_DELAY_MS
      uniqueKey: activity.dedupKey,  // the SAME key that dedups the event
    });
  }
}

One delivery ⇒ one feed row ⇒ one scheduled reminder — atomic, because the dedup row, the feed row, and the job row commit together. And redelivery can never schedule a second reminder, through two independent layers: the feed's (org_id, dedup_key) unique index skips the enqueue for an already-projected event, and the job's uniqueKey (the same dedup key) turns a concurrent duplicate into a no-op that returns the existing row.

When the reminder comes due, a handler class picks it up. A payload that can never succeed fails immediately — no retries burned:

@JobHandler('task.assignment-reminder')
export class AssignmentReminderHandler implements JobHandler {
  handle(payload: Record<string, unknown>, ctx: JobContext): void {
    if (!isTaskAssignedPayload(payload)) {
      throw new PermanentError('task.assignment-reminder: malformed payload');
    }
    // record the notification (audit entry with ctx.jobId / ctx.attempt)
  }
}

The integration test redelivers the event on purpose, enqueues a duplicate on purpose, drains the queue twice, and asserts: one job, one reminder, unique key released on completion. And the worker didn't become a second process — npm run start:worker drains the outbox and runs due jobs: two library-provided loops, one shared graceful shutdown.

A typed API that doesn't lie

The tRPC layer (@nest-native/trpc) is decorator-first (@Router('tasks'), @Query, @Mutation, Zod I/O) with a generated AppRouter consumed by a typed client in CI. Three details worth stealing:

superjson end-to-end — activity.list returns real Date objects, and the generated router carries a type-level transformer marker: a client that forgets to configure superjson fails to compile. Both directions are CI steps.
Validation errors clients can use — an errorFormatter flattens ZodErrors so a failing mutation surfaces error.data.zodError.fieldErrors.title on the typed client.
Cache headers where they're safe — responseMeta sets cache-control only on the public ping query; everything tenant-scoped stays uncached, and tests assert both presence and absence.

Your events, documented

@nest-native/asyncapi publishes an AsyncAPI 3.0 document at /asyncapi (plus -json/-yaml) describing all four domain events. The payload schemas are defined once as Zod objects — the same definitions derive the TypeScript types (z.infer), the runtime guards (safeParse), and the catalog schemas. Producer, consumer, and documentation cannot drift apart, and the document validates against @asyncapi/parser in the test suite. (The reminder job reuses the task.assigned guard — the job payload can't drift from the event contract either.)

AI over your data, tested offline

POST /projects/:id/assistant streams a status update summarizing the project's recent activity, via @nest-native/ai-sdk's @AiStream (SSE, abort on client disconnect). By default it streams from an offline mock model built from the real activity digest — deterministic, no API key, CI-safe. Set OPENAI_API_KEY and a real provider swaps in with no code change. (Adopting the AI SDK is also why the app requires Node ≥ 22 — ai@7 demands it.)

Try it in 30 seconds

git clone https://github.com/nest-native/reference-app && cd reference-app
nvm use            # Node >= 22
npm install
DATABASE_URL=./reference-app.db npm run db:migrate
DATABASE_URL=./reference-app.db npm run seed
AUTH_SECRET=dev-secret-must-be-at-least-32-characters-xxxxx \
  DATABASE_URL=./reference-app.db npm run start:dev

tRPC at /trpc, health at /health, the AsyncAPI catalog at /asyncapi, the AI assistant at POST /projects/1/assistant
Seed login: admin@acme.test / admin123!
The background worker runs as its own process: npm run start:worker — it relays the outbox and executes due jobs
No Docker, no broker, no Redis, no API keys required for any of it

The loop that makes it honest

The app isn't just a showcase — it's the feedback loop for the libraries, and it has teeth. Recent examples, all shipped upstream because building this app surfaced them:

The in-process outbox transport was hand-rolled here first, proved generic, and was extracted into @nest-native/messaging/in-process.
@nest-native/jobs exists because of this loop: the claim/retry/backoff engine hardened here as the outbox relay was generalized into a job queue — and when this app adopted it back for the assignment reminder, the dogfood PR found zero API warts. Porting a battle-tested engine is what that buys.
The app's hand-written AI mock became @nest-native/ai-sdk/testing (createMockLanguageModel) — and deleted every copy-pasted mock in the family.
enqueue() becoming generic (killing as unknown as Record<string, unknown> casts), the in-memory Kafka broker gaining an awaitable idle() (killing sleep(50) in tests), and AsyncAPI accepting Zod schemas directly — all of it started as friction in this codebase.
The app's install even caught a broken peer-dependency range in a fresh release before any user hit it.

If something feels awkward here, that's treated as a library bug — fixed upstream, in its own PR, with its own tests.

What it deliberately is not

Not a starter kit or boilerplate — it optimizes for being read, not forked. Copy patterns, not the repo.
Not 100%-covered — the 100% bar belongs to the libraries; the app's suite is pragmatic and targets the guarantees (rollback, crash recovery, dedup, exactly-once jobs, catalog validity, stream framing).
Not a CDC system — the outbox is the app-level answer; Debezium-style log tailing is a different trade-off and an explicit non-goal.
Not a BullMQ replacement — if you already run Redis and need its throughput, BullMQ is the right tool; @nest-native/jobs is for apps that want deferred work in the database they already operate.
Not affiliated with the NestJS core team.

Where to find it

The app: github.com/nest-native/reference-app — start with the README's story, then the integration tests (they read like the spec of every guarantee above)
The org + all seven packages: github.com/nest-native
Docs hub: nest-native.dev

Feedback, issues, and "this seam is still awkward" reports are the most useful thing you can send — that's literally the mechanism this whole stack improves by.

Introducing @nest-native/drizzle: A Nest-native Drizzle ORM integration

Rodrigo Nogueira — Sun, 17 May 2026 05:11:11 +0000

Renamed: this project was originally published as nest-drizzle-native and is now the scoped @nest-native/drizzle (repo: nest-native/drizzle). Same library, same public API — only the package name changed. To migrate: npm uninstall nest-drizzle-native && npm install @nest-native/drizzle, then update imports to @nest-native/drizzle.

@nest-native/drizzle is a community package designed to make Drizzle ORM feel entirely natural inside NestJS applications.

The core concept is straightforward: preserve Drizzle's explicit, SQL-first philosophy while giving NestJS projects the module, dependency injection, repository, testing, and transaction ergonomics they expect.

The Motivation

Drizzle is excellent because it stays close to SQL and avoids heavy, opaque ORM magic.

NestJS, on the other hand, provides applications with a strong architectural shape built around modules, providers, decorators, testing utilities, lifecycle hooks, and clear dependency boundaries.

A bridge between those two worlds allows teams to build scalable enterprise architectures without turning Drizzle into something it is not. Existing solutions often act as thin connection wrappers, leaving developers to manually solve complex enterprise patterns like cross-service transactions or DTO co-generation.

What it supports today

DrizzleModule.forRoot(), forRootAsync(), and forFeature()
@InjectDrizzle() for direct Drizzle client injection
@DrizzleRepository() for query-focused provider classes
@Transactional() / @InjectTransaction() powered natively via @nestjs-cls/transactional
Named connections for multi-database applications
Testing utilities for clean module and repository testing
Zero runtime dependencies in the published library package
Runnable samples covering transactions, DTO validation, optional drizzle-zod validation, Swagger/OpenAPI integration, raw SQL execution, and various driver setups

Let's look at the code

The biggest pain point of using Drizzle in a structured backend is transaction management. Passing a tx object through five layers of injected services completely breaks Dependency Injection.

With @nest-native/drizzle, transactions are propagated through the CLS transaction context used by @nestjs-cls/transactional, allowing them to flow seamlessly across your services just by using a decorator:

import { Injectable } from '@nestjs/common';
import { Transactional } from '@nest-native/drizzle';
import { AuditService } from './audit.service';
import { UsersRepository } from './users.repository';
import { CreateUserDto } from './create-user.dto';

@Injectable()
export class UsersService {
  constructor(
    private readonly usersRepository: UsersRepository,
    private readonly auditService: AuditService,
  ) {}

  @Transactional()
  async createUser(data: CreateUserDto) {
    const user = await this.usersRepository.insert(data);

    await this.auditService.logAction('USER_CREATED', user.id);

    return user;
  }
}

The repository itself is a clean Nest provider that keeps Drizzle's query builder visible instead of hiding SQL behind an Active Record layer:

import { eq } from 'drizzle-orm';
import {
  DrizzleRepository,
  InjectDrizzle,
} from '@nest-native/drizzle';
import type { AppDatabase } from './database';
import { users } from './schema';
import { CreateUserDto } from './create-user.dto';

@DrizzleRepository()
export class UsersRepository {
  constructor(@InjectDrizzle() private readonly db: AppDatabase) {}

  async insert(data: CreateUserDto) {
    const [user] = await this.db
      .insert(users)
      .values(data)
      .returning();

    return user;
  }

  async findById(id: string) {
    const [user] = await this.db
      .select()
      .from(users)
      .where(eq(users.id, id))
      .limit(1);

    return user;
  }
}

What it does not try to do

The goal is strictly to avoid re-creating TypeORM or an Active Record layer.

Developers still write real, functional Drizzle queries. The library simply provides those queries with a native NestJS structure through decorators and context management, eliminating the need to pass transaction callbacks (tx) down through multiple layers of services.

Links

Docs: https://nest-native.dev/drizzle/
GitHub: https://github.com/nest-native/drizzle
npm: https://www.npmjs.com/package/@nest-native/drizzle
Releases: https://github.com/nest-native/drizzle/releases/latest

Community feedback from NestJS and Drizzle users is highly encourage — especially regarding real-world transaction patterns, testing strategies, multi-database setups, and production adoption. Feel free to open issues or contribute to the repository!

nest-trpc-native: Full NestJS Power + tRPC Type Safety with Zero Runtime Overhead

Rodrigo Nogueira — Tue, 17 Mar 2026 17:24:47 +0000

Hey NestJS + tRPC community! 👋

I’m excited to release nest-trpc-native v0.3.0 — a decorator-first, native-feeling tRPC integration for NestJS.

No adapter glue code in your app layer. No compromise on NestJS features.

You write tRPC routers like Nest classes, with full support for dependency injection, guards, interceptors, pipes, filters, request-scoped providers, and end-to-end type safety.

Why this matters

Most tRPC + NestJS approaches push you toward one side:

Keep all NestJS lifecycle features, but lose clean tRPC developer experience, or
Keep pure tRPC style, but lose NestJS enhancers and request-scoped DI.

nest-trpc-native is designed so you can have both.

Core Features

@Router('users') + @Query(), @Mutation(), @Subscription()
Full support for @UseGuards(), @UseInterceptors(), @UsePipes(ValidationPipe), @UseFilters()
@Input() and @TrpcContext() for parameter extraction
Auto-generated router types (autoSchemaFile: 'src/@generated/server.ts')
Works with Express and Fastify
Zod or classic class-validator validation
Zero runtime dependencies in nest-trpc-native itself (host app controls Nest/tRPC peers)
Monorepo-friendly sample layout
Microservice transport pattern demonstrated in a focused sample

Router Example (NestJS style)

@Router('users')
@UseGuards(AuthGuard)
export class UsersRouter {
  constructor(private readonly usersService: UsersService) {}

  @Query({ input: FindOneSchema, output: UserSchema.nullable() })
  @UsePipes(new ValidationPipe({ transform: true }))
  findOne(
    @Input() input: { id: number },
    @TrpcContext('requestId') requestId: string,
  ) {
    return this.usersService.findById(input.id);
  }

  @Mutation({ input: CreateUserSchema, output: UserSchema })
  create(@Input() input: { name: string; email: string }) {
    return this.usersService.create(input);
  }
}

Client side stays fully type-safe:

const user = await trpc.users.findOne.query({ id: 123 });
// autocomplete + compile-time safety

Installation

npm install nest-trpc-native @trpc/server
npm install @nestjs/common @nestjs/core reflect-metadata rxjs
# optional:
npm install zod

Then register the module:

TrpcModule.forRoot({
  path: '/trpc',
  autoSchemaFile: 'src/@generated/server.ts',
})

Samples You Can Run Now

sample/00-showcase: full integration baseline (guards, interceptors, pipes, filters, request scope, Express/Fastify, typed clients, subscriptions)
sample/11-microservice-transport: tRPC edge gateway + Nest microservice transport (TCP)

From repo root:

npm run showcase

Docs, Repo, and NPM

Docs: https://rodrigobnogueira.github.io/nest-trpc-native/docs/introduction

Repo: https://github.com/rodrigobnogueira/nest-trpc-native

NPM: https://www.npmjs.com/package/nest-trpc-native

Try it, break it, open issues, and share feedback.

Thanks!