deja

Find concurrency bugs by controlling the order things happen in — then reproduce them from a number.

npm install --save-dev deja-dst
npx deja test suite.ts --runs 10000 --minimize

The problem

Some bugs only appear when two things happen in an unlucky order. Two workers claim the same job. An email goes out twice. A lock expires while its holder is still working. They surface once a month, in production, at 3am — and they never reproduce on demand, so "fixed" means "hasn't happened lately".

Integration tests don't help. They run one ordering, usually the lucky one.

What deja does

deja runs your workers inside a simulated world — virtual clock, seeded scheduler, in-process Postgres and Redis, no real sockets. Every time your code touches the outside world it doesn't perform the operation; it hands deja a description and gets back a promise deja holds.

The program is now frozen, and deja holds a list of everything that could happen next. It rolls a seeded die, picks one, performs it, and unfreezes exactly that task.

The ordering stops being luck and becomes a number. A run is a pure function of (code, seed), so when seed 4471 breaks an invariant, it breaks it again — on your machine, in CI, next year.

What it catches

| | | |---|---| | Lost updates | read-modify-write across two statements with no transaction | | Double sends | a drainer with no claim protocol, or a retry after an apparent failure | | Lock expiry | a lease that runs out while its holder is still working | | Crash-and-restart | the process dies between the side effect and the record of it | | Fail-after-effect | the write landed and the caller was told it failed | | Stranded work | a row claimed and never released, with nothing to recover it | | Deadlock & starvation | a worker still parked when everything else has gone quiet |

Out of the box deja detects only generic failure — a crash, an unhandled rejection, a deadlock. Everything else comes from laws you declare, which is half the tool.

Quickstart

A suite is a function from a seed to a simulated system:

// outbox.suite.ts
import { createSim, defineSuite } from "deja-dst";

export default defineSuite({
  name: "outbox",
  concurrencySafe: true,

  build(seed) {
    const sim = createSim({ seed });
    sim.kv.seed("row-1", { status: "PENDING" });

    // Two drainers, as during a rolling deploy.
    for (const name of ["drain-a", "drain-b"]) {
      sim.spawn(name, async (ctx) => {
        const row = (await ctx.kv.get("row-1")) as { status: string };
        if (row.status !== "PENDING") return;
        await ctx.net.send("email", "row-1");            // the row is still PENDING here
        await ctx.kv.set("row-1", { status: "SENT" });
      });
    }

    sim.invariant("at most one send per row", () => {
      const n = sim.net.countAccepted("email", "row-1");
      if (n > 1) throw new Error(`row-1 was sent ${n} times`);
    });

    return sim;                    // deja calls run() — don't call it yourself
  },
});

npx deja test outbox.suite.ts --runs 10000

  FAIL  outbox
        4 runs in 0.01s (1050/s) · 4 distinct schedules explored · stopped at first failure

  invariant broken  at most one send per row
                    row-1 was sent 2 times  (t=22ms)

  narrative (11 events, showing 8)
    t=     8ms [drain-a] op:kv.get {"key":"row-1"} -> {"status":"PENDING"}
    t=    14ms [drain-b] op:kv.get {"key":"row-1"} -> {"status":"PENDING"}   ← both read PENDING
    t=    16ms [drain-a] op:net.email {"to":"row-1"} -> {"accepted":true}
    t=    22ms [drain-b] op:net.email {"to":"row-1"} -> {"accepted":true}
  ✗ t=    22ms [sim] violation:at most one send per row

  replay  deja replay --seed 2 outbox.suite.ts

Every failure ends with the command that reproduces it.

Faults

Ordering alone doesn't cause every bug. Ask for the rest:

createSim({
  seed,
  faults: {
    crash: { probability: 0.05, max: 2 },   // die mid-flight; the database survives, memory doesn't
    failAfterEffect: { probability: 0.1 },  // it happened; the caller was told otherwise
    clockSkew: { maxMs: 5_000 },            // this machine's idea of "now"
  },
});

Then let --minimize tell you which of them actually mattered:

  minimized   reproduces with NO faults — the fault injection was not needed (3 were fired)
              this is a pure ordering bug — no crash or failure is required

Being told to stop looking at the crash is worth more than being handed a smaller crash.

CLI

deja test <suite.ts> [options]      search seeds for violations
deja replay --seed <n> <suite.ts>   re-run one seed and narrate it

  --runs <n>          how many seeds to try              (default 100)
  --seed <n>          start here; with replay, THE seed
  --minimize          shrink to the fewest faults that still break it
  --no-bail           keep going past the first failure
  --concurrency <n>   parallel sims, if the suite allows  (default 8)
  --narrative <n>     events to print around a failure    (default 14)
  --quiet             summary only

Exits 1 on a violation, so CI notices.

What you get in a simulation

| handle | what it is | |---|---| | ctx.kv | key/value store with atomic set-if-absent and virtual-clock TTLs | | ctx.sql | real Postgres, in-process, via PGlite — one statement per scheduled operation | | ctx.redis | SET NX PX, INCR, EXPIRE, TTL, KEYS — TTLs on the virtual clock | | ctx.net | outbound sends, recorded and assertable. No sockets | | ctx.sleep / ctx.now | virtual time — a week of hourly crons runs in milliseconds | | ctx.spawn | fan out, the way a drainer handles a batch |

setTimeout, setInterval, Date.now(), Math.random() and crypto.randomUUID() are routed through the simulator automatically, so an existing polling worker usually runs unmodified. Using an ORM? PgStore.driver() makes its statements scheduled operations without patching it.

Requirements

Node 22.18+. deja runs TypeScript natively, so your suite needs no build step. PGlite is an optional peer dependency — install it only if you want the SQL layer:

npm install --save-dev @electric-sql/pglite

Limits worth knowing before you start

• Not drop-in. Your workers must take their handles as parameters. Code that reaches around the harness — real sockets, native modules, a library that captured setTimeout at import — punches a hole in determinism, and one hole breaks replay.
• No microtask-level control. await a(); await b(); inside one task keeps its order, always. deja controls ordering between tasks, which is where these bugs live.
• One open transaction at a time. PGlite has a single connection, so two interleaving BEGIN…COMMIT blocks can't be modelled. Autocommit statements and cross-statement read-modify-writes — the usual worker shape — are fine.
• A clean run has two possible meanings: your code is correct, or your suite can't reach the bug. Telling those apart is most of the skill. The guide opens with it.

Status

v0.1.0, pre-alpha but real. 148 tests. It has been pointed at one production Node/Express/Prisma backend and found two defects that a careful manual review of the same files had missed. It has not been used by anyone else yet, so expect rough edges and please report them.

Documentation

• Writing suites — start here
• How it works — the barrier, the effect thunk, the split random streams

Prior art

FoundationDB originated simulation-first development; TigerBeetle's VOPR applies it relentlessly; Antithesis sells it at hypervisor level; madsim is Rust's. Nothing native and open existed for Node/TypeScript — the stack where outbox, queue and retry patterns are most common. PGlite is the recent unlock that makes a deterministic real database feasible in-process.

Name

Déjà vu. The product is making a failure happen again — byte for byte, from a seed.

License

MIT