yieldNow - API reference

API reference › @evolu/common › Task › yieldNow

const yieldNow: Task<void>;

Defined in: packages/common/src/Task.ts:1685

Yields execution to allow other work to proceed.

Long-running JavaScript blocks the main thread. In browsers, this makes the UI unresponsive (user interactions, animations). In Node.js, it prevents I/O callbacks, timers, and other requests from being handled. Inserting yield points lets the runtime process high-priority work between chunks of code.

Uses scheduler.yield() in browsers for optimal main thread scheduling, falls back to setImmediate in Node.js, or setTimeout elsewhere.

Example

const processLargeArray: Task<void, never> = async (run) => {
  const { time } = run.deps;
  let lastYield = time.now();

  for (const item of largeArray) {
    processItem(item);

    // Yield periodically to keep UI responsive
    if (time.now() - lastYield > msLongTask) {
      const r = await run(yieldNow);
      if (!r.ok) return r;
      lastYield = time.now();
    }
  }

  return ok();
};

Recursive tasks also benefit from periodic yields — without them, deep recursion overflows the call stack:

const processRecursive =
  (count: number, index: number, sum: number): Task<number> =>
  async (run) => {
    if (index >= count) return ok(sum);

    // Yield periodically to break synchronous call chains.
    if (index > 0 && index % 1000 === 0) {
      const y = await run(yieldNow);
      if (!y.ok) return y;
    }

    // Direct tail-call: no fiber overhead, stack-safe thanks to yieldNow.
    return await processRecursive(count, index + 1, sum + index)(run);
  };

Example

See