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 promiseDrop 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 ityield* 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
- 1. Written twicesync~10,478,937async~2,461,765
- 2. MaybePromisesync~8,773,336async~2,432,805
- 3. Generator + runnersync~2,505,835async~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 ayield*of another generator is a build error, not a guess. __syncStep(x)throws ifxis a promise, so a sync body cannot leak an async call.- Functions are named after their variable, so profiles show
completeJobSyncinstead 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
- 1. Written twicesync~10,478,937async~2,461,765
- 2. MaybePromisesync~8,773,336async~2,432,805
- 3. Generator + runnersync~2,505,835async~1,189,558
- 4. Compiled generatorsync~10,059,980async~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
- In-memory, syncgenerator~196,081compiled~285,869
- In-memory, asyncgenerator~155,488compiled~237,795
- better-sqlite3generator~31,196compiled~34,964
- node:sqlitegenerator~32,438compiled~36,215
Jobs completed, concurrency 1
- In-memory, syncgenerator~78,855compiled~141,727
- In-memory, asyncgenerator~72,021compiled~125,750
- better-sqlite3generator~11,330compiled~12,638
- node:sqlitegenerator~10,349compiled~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.