@nxtedition/yield

Cooperative yielding for Node.js to keep servers and applications responsive.

When using synchronous APIs like DatabaseSync, sync fs API's such as fs.readFileSync, or fs.statSync — or simply performing lots of synchronous computation — the event loop is blocked and cannot process I/O, timers, or incoming requests. Even long-running chains of asynchronous microtasks (e.g. deeply nested Promise.then chains) can starve the event loop in the same way.

This library provides a simple mechanism to periodically yield control back to the event loop during these long-running operations, preventing event loop starvation and keeping your application responsive.

Install

npm install @nxtedition/yield

Usage

Promise-based

import { maybeYield } from '@nxtedition/yield'
import { DatabaseSync } from 'node:sqlite'

const db = new DatabaseSync('data.db')

for (const row of db.prepare('SELECT * FROM large_table').iterate()) {
  processRow(row)
  const yielded = maybeYield()
  if (yielded) {
    await yielded // give the event loop a turn
  }
}

Callback-based

import { shouldYield, doYield } from '@nxtedition/yield'
import fs from 'node:fs'

function processFiles(files, i = 0) {
  for (; i < files.length; i++) {
    if (shouldYield()) {
      doYield((index) => processFiles(files, index), i)
      return // resumes at index i after the event loop has had a turn
    }
    const data = fs.readFileSync(files[i])
    transform(data)
  }
}

Unconditional yield

import { doYield } from '@nxtedition/yield'

// Promise-based
await doYield()

// Callback-based
doYield((opaque) => {
  continueWork(opaque)
}, data)

Checking without yielding

import { shouldYield } from '@nxtedition/yield'

while (hasWork()) {
  if (shouldYield()) {
    break // pick the remaining work back up on a later turn
  }
  doWork()
}

API

shouldYield(timeout?): boolean

Returns true when more than timeout milliseconds (default: 40) have elapsed since the last yield dispatch. Does not yield — only checks whether yielding is recommended.

Once it returns true it latches and keeps returning true until the pending yield dispatch has run. When it latches, a dispatch is scheduled automatically, so the latch clears after the next event-loop turn even if the caller never enqueues a yield.

maybeYield(timeout?): Promise<void> | null

If a yield is needed, queues a yield and returns a Promise. Otherwise returns null. Use this in async functions.

maybeYield(callback, opaque?, timeout?): void

If a yield is needed, defers callback(opaque) to after the yield. Otherwise calls callback(opaque) synchronously.

Note: because the no-yield path invokes the callback synchronously, a recursive continuation-passing loop built on this overload grows the stack until the timeout elapses. For long loops prefer the shouldYield()/doYield() pattern shown above.

doYield(): Promise<void>

Unconditionally queues a yield and returns a Promise that resolves after the event loop has been given a turn.

doYield(callback, opaque?): void

Unconditionally defers callback(opaque) to after the next yield.

setYieldTimeout(timeout): void

Set the default yield timeout in milliseconds. Must be a non-negative number (NaN is rejected; Infinity disables time-based yielding). Default: 40.

setYieldDispatcher(dispatcher): void

Override the scheduling function used to defer work. The dispatcher receives a callback and should invoke it asynchronously (e.g. via setTimeout or setImmediate) — asynchronous invocation is what actually gives the event loop a turn. A dispatcher that invokes the callback synchronously is tolerated and loses no queued items, but it defeats the purpose of yielding. Pass null (or undefined) to restore the default dispatcher. Throws a TypeError for any other non-function value. If the dispatcher itself throws, the error propagates to the caller and the library recovers on the next scheduling attempt.

How it works

The library tracks when the last yield occurred using performance.now(). When shouldYield() detects that more than timeout milliseconds have elapsed, it signals that a yield is due. doYield and maybeYield batch pending callbacks into a queue that is drained on the next event-loop turn (via setImmediate by default), yielding again if the timeout is exceeded during draining.

License

MIT