One body, sync and async

Why a library that runs inside synchronous SQLite transactions and asynchronous Postgres ones writes each function once as a generator, and why it then compiles the generators away.

better-sqlite3, node:sqlite and bun:sqlite run statements synchronously, and so are their transactions. Nothing inside one may await:

TypeScript

const placeOrder = db.transaction(async (order) => {
  db.prepare("INSERT INTO orders (id, total) VALUES (?, ?)").run(order.id, order.total);
  await queue.enqueue(db, "send-receipt", { orderId: order.id });
});

placeOrder(order);
// TypeError: Transaction function cannot return a promise

Drop the await and the enqueue runs after COMMIT, outside the transaction — the dual-write problem, caused by a function's color. So a library that writes inside the caller's transaction must be synchronous over a synchronous driver and asynchronous over pg, mysql2 or postgres, with the same logic in both. There are four ways to write that logic once.

Option 1: write it twice

TypeScript

function completeJobSync(db, id) {
  const job = findJobSync(db, id);
  db.update(id, "completed");
  return db.insert(job.chainId);
}

async function completeJobAsync(db, id) {
  const job = await findJobAsync(db, id);
  await db.update(id, "completed");
  return db.insert(job.chainId);
}

As fast as JavaScript gets. For a hundred functions, every fix lands twice and the copies drift.

Option 2: MaybePromise and .then

TypeScript

const andThen = (value, next) => (isPromise(value) ? value.then(next) : next(value));

const completeJob = (db, id) =>
  andThen(findJob(db, id), (job) =>
    andThen(db.update(id, "completed"), () => db.insert(job.chainId)),
  );

One body, but continuation-passing style by hand: each step nests deeper, and try/finally and loops turn into helpers.

Option 3: a generator and a runner

TypeScript

const completeJob = syncAsync(function* (db, id) {
  const job = yield* findJob.steps(db, id);
  yield* step(db.update(id, "completed"));
  return yield* step(db.insert(job.chainId));
});

completeJob.sync(db, id); // the row id
await completeJob.async(db, id); // a promise of it

yield* step(x) goes where await x would. A runner loops over the generator: in sync mode it sends each value straight back (and throws on a promise), in async mode it awaits it. Control flow reads like normal code — the same pattern as co before async/await, and Babel's gensync.

Measuring options 1–3

The same "complete a job" body — a nested lookup and three writes — over an in-memory Map, so only the plumbing is measured. Node 24 on an Apple M1 Pro, median of three processes.

Complete a job, in-memory map

calls/s
sync async
  • 1. Written twice
    sync
    ~10,478,937
    async
    ~2,461,765
  • 2. MaybePromise
    sync
    ~8,773,336
    async
    ~2,432,805
  • 3. Generator + runner
    sync
    ~2,505,835
    async
    ~1,189,558

The most readable option is the slowest: 4.2× slower than writing it twice in sync mode, 2.1× in async. Every call allocates a generator, and every step is a suspend and resume through the runner.

Option 4: compile the generator away

The bodies only ever yield step(…) or .steps(…), so the rewrite is mechanical. A build plugin turns each syncAsync(function* …) into two plain functions:

TypeScript

const completeJob = {
  sync: function completeJobSync(db, id) {
    const job = __syncStep(findJob.sync(db, id));
    __syncStep(db.update(id, "completed"));
    return __syncStep(db.insert(job.chainId));
  },
  async: async function completeJobAsync(db, id) {
    const job = await findJob.async(db, id);
    await db.update(id, "completed");
    return await db.insert(job.chainId);
  },
};

That is option 1, generated, so it cannot drift. The compiler keeps it sound:

  • A plain yield, an async generator or a yield* of another generator is a build error, not a guess.
  • __syncStep(x) throws if x is a promise, so a sync body cannot leak an async call.
  • Functions are named after their variable, so profiles show completeJobSync instead of runner frames.
  • A fixture per construct (try/finally, nested calls, renamed imports) pins the output.

Measuring option 4

Complete a job, in-memory map

calls/s
sync async
  • 1. Written twice
    sync
    ~10,478,937
    async
    ~2,461,765
  • 2. MaybePromise
    sync
    ~8,773,336
    async
    ~2,432,805
  • 3. Generator + runner
    sync
    ~2,505,835
    async
    ~1,189,558
  • 4. Compiled generator
    sync
    ~10,059,980
    async
    ~2,420,873

4.0× faster than the runner in sync mode and 2.0× in async, close to writing it twice — with one body.

Outcome

The whole queue built both ways — every sync-async body in the core and the SQLite adapter left as a generator, or compiled — through a throughput benchmark. The in-memory adapters show the library's own overhead; SQLite shows what is left once a database does real work.

Chains created, one per transaction

chains/s
generator compiled
  • In-memory, sync
    generator
    ~196,081
    compiled
    ~285,869
  • In-memory, async
    generator
    ~155,488
    compiled
    ~237,795
  • better-sqlite3
    generator
    ~31,196
    compiled
    ~34,964
  • node:sqlite
    generator
    ~32,438
    compiled
    ~36,215

Jobs completed, concurrency 1

jobs/s
generator compiled
  • In-memory, sync
    generator
    ~78,855
    compiled
    ~141,727
  • In-memory, async
    generator
    ~72,021
    compiled
    ~125,750
  • better-sqlite3
    generator
    ~11,330
    compiled
    ~12,638
  • node:sqlite
    generator
    ~10,349
    compiled
    ~11,512
  • In memory, compiling speeds completion up 1.8× and creation 1.5×.
  • Over real SQLite it is 10–12%, with either driver.
  • Batched creation barely moves (2–8%): one call does a hundred jobs' work.

Most code should pick a color and stay in it. When one codebase must run on both sides of the line, write the body once as a generator and compile it away. In Queuert, every function that touches a state adapter works this way; the SQLite adapter page covers synchronous providers.

esc

Search guides, integrations and every exported symbol.

↑ ↓ to navigate↵ to open