Map items with limited concurrency, settling every outcome
A newsletter tool sends a test email to every address on a list before a campaign goes out. The mail API allows only a few requests at a time, and some addresses will bounce. A bounce must not stop the run: the tool needs a full report with one line per address, and a live counter that ticks up as each send finishes.
Implement mapSettledPool(items, mapper, options). It calls mapper for every item with limited concurrency and resolves with an outcome for every item, whether it succeeded or failed.
mapSettledPool(items, mapper, options?) // => Promise<Outcome[]>
// mapper(item, index) => value | Promise<value>
// options: { limit?: number, onSettle?: (outcome, index) => void }
// Outcome: { status: 'fulfilled', value } | { status: 'rejected', reason }
outcomes[i] describes items[i]: { status: 'fulfilled', value } if the call returned a value or its promise fulfilled, { status: 'rejected', reason } if the call threw synchronously or its promise rejected. Outcome objects have exactly those two keys.mapper(item, index) for items in index order.mapper is called until its result settles. Never have more than limit pending calls. Start the first limit items right away, then start the next item as soon as any pending call settles, whether it succeeded or failed. Do not wait for a whole batch.limit defaults to Infinity (start everything at once). If it is not a positive integer or Infinity, the returned promise rejects with a RangeError and mapper is never called. options itself is optional.onSettle(outcome, index), if given, is called once per item as soon as that item settles, in the order the items settle, and always before the returned promise resolves. If it throws, ignore the error and keep going.[] without calling mapper or onSettle.items.const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
const sendTimes = { 'ana@x.io': 300, 'bounce@x.io': 100, 'raj@x.io': 100 };
let sent = 0;
const report = await mapSettledPool(
Object.keys(sendTimes),
async (address) => {
await sleep(sendTimes[address]);
if (address.startsWith('bounce')) throw new Error('mailbox not found');
return `queued ${address}`;
},
{ limit: 2, onSettle: () => sent++ },
);
// report => [
// { status: 'fulfilled', value: 'queued ana@x.io' },
// { status: 'rejected', reason: Error('mailbox not found') },
// { status: 'fulfilled', value: 'queued raj@x.io' },
// ]
// sent => 3
// Timeline: t=0 start ana, bounce; t=100 bounce fails -> start raj; t=200 raj done; t=300 ana done.
Tests use mappers that return promises the test settles by hand, then check which items have started. They wait for pending promise callbacks to run before checking, so it does not matter whether your first calls happen synchronously or in a microtask.