JavaScript: Fundamental (ES6), part 2, 1–37

1
2
3
4
5
6
7
8
9
10
11
12function* countdown(from) {
  while (from > 0) yield from--;
  return 'lift off';
}

const it = countdown(3);
const steps = [it.next(), it.next(), it.next(), it.next(), it.next()];

console.log('step by step:');
for (const s of steps) console.log(' ', JSON.stringify(s));
console.log('spread     :', [...countdown(3)], '<- no "lift off"');
console.log('own iterator?', it[Symbol.iterator]() === it);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28function* runningTotal() {
  let total = 0;
  while (true) {
    const amount = yield total;   // out goes the total, in comes the next amount
    total += amount;
  }
}

const till = runningTotal();
const first = till.next(500);     // 500 is DISCARDED: no yield is waiting for it
const second = till.next(1000);
const third = till.next(250);

// The fix is to prime it, then hide the priming behind a small API.
function openTill() {
  const g = runningTotal();
  g.next();                       // run to the first yield and drop that value
  return { add: (naira) => g.next(naira).value };
}
const shop = openTill();
const takings = [shop.add(4500), shop.add(300), shop.add(1200)];

const sentNothing = (() => { const g = runningTotal(); g.next(); return g.next().value; })();

console.log('first next(500) gave', first.value, '<- the 500 went nowhere');
console.log('then next(1000) ->', second.value, ' next(250) ->', third.value);
console.log('primed till     :', takings);
console.log('next() with no argument:', sentNothing);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35function* connection(log) {
  log.push('open');
  try {
    yield 'row 1';
    yield 'row 2';
    yield 'row 3';
  } finally {
    log.push('close');            // runs on normal end, on return(), on throw()
  }
}

const log = [];
const rows = connection(log);
const read = [rows.next().value, rows.next().value];
const ended = rows.return('stopped early');
const afterwards = rows.next();

// for...of does the same thing for you when you break.
const loopLog = [];
const loopRead = [];
for (const row of connection(loopLog)) {
  loopRead.push(row);
  if (loopRead.length === 1) break;
}

// And nothing at all happens if you simply stop reading.
const abandonedLog = [];
const abandoned = connection(abandonedLog);
abandoned.next();

console.log('read      :', read);
console.log('return()  :', JSON.stringify(ended));
console.log('log       :', log);
console.log('after break:', loopLog, loopRead);
console.log('abandoned :', abandonedLog, '<- never closed');

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36function* resilient(log) {
  let n = 0;
  while (n < 4) {
    try {
      yield n++;
    } catch (err) {
      log.push('caught ' + err.message);   // recover and keep going
    }
  }
  return 'finished at ' + n;
}

const log = [];
const g = resilient(log);
const started = g.next();
const resumed = g.throw(new Error('bad row'));
const rest = [g.next().value, g.next().value, g.next().value];

// A generator with no try/catch cannot absorb it.
function* fragile() { yield 1; yield 2; }
const f = fragile();
f.next();
const escaped = (() => {
  try { f.throw(new Error('boom')); return 'no throw'; } catch (e) { return e.message; }
})();

// Neither can one that has not started: there is no active try block yet.
const tooSoon = (() => {
  try { resilient([]).throw(new Error('too soon')); return 'no throw'; } catch (e) { return e.message; }
})();

console.log('started :', JSON.stringify(started));
console.log('resumed :', JSON.stringify(resumed), '<- alive, and one value further on');
console.log('log     :', log);
console.log('rest    :', rest);
console.log('no handler inside:', escaped, ' before starting:', tooSoon);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35function* inner() {
  yield 'a';
  yield 'b';
  return 'inner result';
}

function* outer() {
  const handedBack = yield* inner();   // the inner RETURN lands here
  yield handedBack;
  yield* [1, 2];                       // any iterable
  yield* 'hi';                         // a string is one too
}

// The hand-rolled relay yields the same values and loses the return value.
function* relay() {
  for (const v of inner()) yield v;
}

function* deep(n) {
  if (n === 0) return;
  yield n;
  yield* deep(n - 1);
}

// next() is forwarded through the delegation, not swallowed by it.
function* echo() { const got = yield 'ready'; return 'got ' + got; }
function* wrapper() { const r = yield* echo(); yield r; }
const w = wrapper();
w.next();
const passedThrough = w.next('cash').value;

console.log('outer :', [...outer()]);
console.log('relay :', [...relay()], '<- the return value is gone');
console.log('deep  :', [...deep(3)]);
console.log('sent through the delegation:', passedThrough);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40const TRANSITIONS = {
  pending: { pay: 'paid', cancel: 'cancelled' },
  paid: { ship: 'shipped', refund: 'refunded' },
  shipped: { deliver: 'delivered' },
  cancelled: {},
  refunded: {},
  delivered: {},
};

function* order(start = 'pending') {
  let state = start;
  const history = [state];
  while (Object.keys(TRANSITIONS[state]).length > 0) {
    const event = yield state;
    const next = TRANSITIONS[state][event];
    if (next === undefined) continue;      // this state cannot handle that event
    state = next;
    history.push(state);
  }
  return history;
}

const o = order();
const a = o.next();               // start it
const b = o.next('pay');
const ignored = o.next('deliver');  // shipping has not happened yet
const c = o.next('ship');
const done = o.next('deliver');

const cancelled = (() => { const x = order(); x.next(); return x.next('cancel'); })();
const independent = (() => {
  const p = order(); const q = order();
  p.next(); q.next(); p.next('pay');
  return q.next('cancel').value;
})();

console.log('pending ->', b.value, '->', c.value);
console.log('an event it cannot handle:', ignored.value, '<- unchanged');
console.log('terminal:', done.done, JSON.stringify(done.value));
console.log('cancelled route:', cancelled.value);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40function* naturals(from = 1) {
  let n = from;
  while (true) yield n++;
}

function* take(iterable, count) {
  if (count <= 0) return;
  let taken = 0;
  for (const value of iterable) {
    yield value;
    if (++taken === count) return;
  }
}

// A version that drives next() itself, so it never closes the source.
function* takeFrom(iterator, count) {
  for (let i = 0; i < count; i++) {
    const step = iterator.next();
    if (step.done) return;
    yield step.value;
  }
}

let produced = 0;
function* counted() { let n = 1; while (true) { produced++; yield n++; } }

const firstThree = [...take(counted(), 3)];
const producedForThree = produced;
const nothing = [...take(counted(), 0)];
const producedAfterZero = produced;

const shared = naturals();
const twiceOverForOf = [[...take(shared, 2)], [...take(shared, 2)]];
const openSource = naturals();
const twiceOverNext = [[...takeFrom(openSource, 2)], [...takeFrom(openSource, 2)]];

console.log('first three   :', firstThree, 'source produced', producedForThree);
console.log('take(..., 0)  :', nothing, 'source produced', producedAfterZero);
console.log('shared via for...of:', twiceOverForOf, '<- second pass is empty');
console.log('shared via next()  :', twiceOverNext);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30function* mapG(iterable, fn) { for (const v of iterable) yield fn(v); }
function* filterG(iterable, keep) { for (const v of iterable) if (keep(v)) yield v; }
function* takeG(iterable, n) {
  if (n <= 0) return;
  let i = 0;
  for (const v of iterable) { yield v; if (++i === n) return; }
}

let touched = 0;
function* meterReadings() {
  let naira = 500;
  while (true) { touched++; yield naira; naira += 500; }
}

const roundThousands = takeG(
  mapG(filterG(meterReadings(), (n) => n % 1000 === 0), (n) => `₦${n}`),
  3
);
const formatted = [...roundThousands];

let pulls = 0;
function* three() { for (const v of [1, 2, 3]) { pulls++; yield v; } }
const chain = mapG(three(), (n) => n * 2);
const pullsBeforeIterating = pulls;
const doubled = [...chain];

console.log('formatted :', formatted);
console.log('source touched', touched, 'times for three results');
console.log('pulls before iterating:', pullsBeforeIterating, ' after:', pulls);
console.log('second pass over the same chain:', [...chain]);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25function* idFactory(prefix, start = 1) {
  let n = start;
  while (true) {
    const reseat = yield `${prefix}-${String(n).padStart(4, '0')}`;
    n = reseat === undefined ? n + 1 : reseat;
  }
}

const invoices = idFactory('INV');
const ids = [invoices.next().value, invoices.next().value, invoices.next().value];
const jumped = invoices.next(100).value;
const carriedOn = invoices.next().value;

const twoStreams = (() => {
  const a = idFactory('LAG');
  const b = idFactory('ABJ');
  return [a.next().value, b.next().value, a.next().value, b.next().value];
})();

const long = (() => { const g = idFactory('X'); g.next(); return g.next(99999).value; })();

console.log('sequential :', ids);
console.log('reseated   :', jumped, '->', carriedOn);
console.log('two streams:', twoStreams);
console.log('own keys on the generator object:', Object.keys(invoices));

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38const org = {
  name: 'Lagos HQ',
  staff: 12,
  units: [
    { name: 'Ikeja branch', staff: 5, units: [{ name: 'Ikeja counter', staff: 2, units: [] }] },
    { name: 'Yaba branch', staff: 3, units: [] },
  ],
};

function* walk(node, depth = 0) {
  yield { name: node.name, staff: node.staff, depth };
  for (const child of node.units ?? []) yield* walk(child, depth + 1);
}

function* levels(root) {
  const queue = [root];
  while (queue.length) {
    const node = queue.shift();
    yield node.name;
    queue.push(...(node.units ?? []));
  }
}

const flat = [...walk(org)];
let total = 0;
for (const node of walk(org)) total += node.staff;

const lazily = walk(org);
const firstTwo = [lazily.next().value.name, lazily.next().value.name];

let chain = { name: 'n0', staff: 0, units: [] };
for (let i = 1; i <= 200; i++) chain = { name: 'n' + i, staff: 0, units: [chain] };
const deepWalk = [...walk(chain)];

console.log('depth-first  :', flat.map((n) => `${'  '.repeat(n.depth)}${n.name}`).join(' | '));
console.log('breadth-first:', [...levels(org)]);
console.log('staff total  :', total);
console.log('read two, stopped:', firstTwo);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31class Ledger {
  constructor(rows) { this.rows = rows; }
  *[Symbol.iterator]() { for (const row of this.rows) yield row; }
}

const broken = {
  rows: [1, 2, 3],
  cached: null,
  [Symbol.iterator]() {
    if (!this.cached) this.cached = (function* (rows) { yield* rows; })(this.rows);
    return this.cached;                 // the SAME iterator every time
  },
};

const ledger = new Ledger([
  { item: 'rice, 50kg', naira: 45000 },
  { item: 'palm oil', naira: 12000 },
]);

const firstPass = [...ledger];
const secondPass = [...ledger];
const brokenPasses = [[...broken], [...broken]];

const arrayTwice = (() => { const a = [1, 2]; return [[...a], [...a]]; })();
const iteratorTwice = (() => { const it = [1, 2][Symbol.iterator](); return [[...it], [...it]]; })();
const [firstRow, secondRow] = new Ledger(['x', 'y']);

console.log('two passes over the ledger:', firstPass.length, secondPass.length);
console.log('two passes over the broken one:', brokenPasses);
console.log('array twice   :', arrayTwice);
console.log('iterator twice:', iteratorTwice);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31const tills = {
  amounts: [1200, 3400, 800],
  [Symbol.asyncIterator]() {
    const amounts = this.amounts;
    let i = 0;
    return {
      next() {
        return i < amounts.length
          ? Promise.resolve({ value: amounts[i++], done: false })
          : Promise.resolve({ value: undefined, done: true });
      },
    };
  },
};

const collect = async (source) => {
  const out = [];
  for await (const value of source) out.push(value);
  return out;
};

const seen = await collect(tills);
const syncRefused = (() => {
  try { for (const x of tills) return 'looped ' + x; return 'empty'; }
  catch (e) { return e.constructor.name; }
})();
const emptySource = { [Symbol.asyncIterator]: () => ({ next: () => Promise.resolve({ done: true }) }) };

console.log('for await gave:', seen, 'total', seen.reduce((a, b) => a + b, 0));
console.log('plain for...of :', syncRefused);
console.log('next() returns a promise?', typeof tills[Symbol.asyncIterator]().next().then);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36const store = {
  rows: [
    { plate: 'LAG-441-XA', fee: 2500 },
    { plate: 'ABJ-772-KM', fee: 4000 },
    { plate: 'KAN-118-QQ', fee: 1500 },
  ],
  // Pretend I/O. It resolves at once, so nothing here waits on real time.
  read(i) { return Promise.resolve(this.rows[i]); },
};

async function* rowsOf(source) {
  for (let i = 0; i < source.rows.length; i++) yield await source.read(i);
}

async function* feesOver(source, limit) {
  for await (const row of source) if (row.fee > limit) yield row.plate;
}

const collect = async (source) => {
  const out = [];
  for await (const v of source) out.push(v);
  return out;
};

const big = await collect(feesOver(rowsOf(store), 2000));
const all = await collect(feesOver(rowsOf(store), 100));

let reads = 0;
const metered = { rows: store.rows, read(i) { reads++; return Promise.resolve(this.rows[i]); } };
const lazily = feesOver(rowsOf(metered), 2000);
const firstOne = await lazily.next();
const readsAfterOne = reads;

console.log('over ₦2000 :', big);
console.log('everything :', all);
console.log('one value out cost', readsAfterOne, 'read(s)');

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41const PAGES = {
  1: { items: ['LAG-001', 'LAG-002'], next: 2 },
  2: { items: ['LAG-003', 'LAG-004'], next: 3 },
  3: { items: ['LAG-005'], next: null },
};

let requests = 0;
const api = { get(page) { requests++; return Promise.resolve(PAGES[page]); } };

async function* paged(api, from = 1) {
  let page = from;
  while (page !== null) {
    const body = await api.get(page);
    yield* body.items;              // the caller never sees a page boundary
    page = body.next;
  }
}

async function* takeAsync(source, n) {
  if (n <= 0) return;
  let i = 0;
  for await (const v of source) { yield v; if (++i === n) return; }
}

const collect = async (source) => {
  const out = [];
  for await (const v of source) out.push(v);
  return out;
};

const everything = await collect(paged(api));
const requestsForAll = requests;

requests = 0;
const firstThree = await collect(takeAsync(paged(api), 3));
const requestsForThree = requests;

const onePage = await collect(paged({ get: () => Promise.resolve({ items: [], next: null }) }));

console.log('all plates :', everything, 'in', requestsForAll, 'requests');
console.log('first three:', firstThree, 'in', requestsForThree, 'requests');

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37let cleanups = 0;

async function* subscription(log) {
  log.push('subscribe');
  try {
    let n = 1;
    while (true) {
      await Promise.resolve();          // pretend a message arrived
      yield 'event ' + n++;
    }
  } finally {
    cleanups++;
    log.push('unsubscribe');
  }
}

const breakLog = [];
const got = [];
for await (const event of subscription(breakLog)) {
  got.push(event);
  if (got.length === 2) break;
}

const returnLog = [];
const s = subscription(returnLog);
await s.next();
const ended = await s.return('cancelled');
const afterwards = await s.next();

const abandonedLog = [];
const abandoned = subscription(abandonedLog);
await abandoned.next();

console.log('events    :', got);
console.log('break     :', breakLog);
console.log('return()  :', JSON.stringify(ended), returnLog);
console.log('abandoned :', abandonedLog, '<- still subscribed, for ever');

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29const mixed = [
  Promise.resolve('till 1: ₦2,500'),
  Promise.reject(new Error('till 2 offline')),
  Promise.resolve('till 3: ₦4,000'),
];

const collected = [];
let caught = '';
try {
  for await (const line of mixed) collected.push(line);
} catch (err) {
  caught = err.message;
}

// One try per item, so a failure is data rather than an exit.
const settledEach = async (promises) => {
  const out = [];
  for (const p of promises) {
    try { out.push({ status: 'fulfilled', value: await p }); }
    catch (err) { out.push({ status: 'rejected', reason: err.message }); }
  }
  return out;
};

const everyOutcome = await settledEach(mixed);

console.log('got before the failure:', collected);
console.log('caught                :', caught);
console.log('every outcome         :', everyOutcome.map((r) => r.status));

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62function pushStream() {
  const buffer = [];
  let parked = null;
  let closed = false;
  return {
    push(value) {
      if (parked) { const release = parked; parked = null; release({ value, done: false }); }
      else buffer.push(value);
    },
    close() {
      closed = true;
      if (parked) { const release = parked; parked = null; release({ value: undefined, done: true }); }
    },
    [Symbol.asyncIterator]() {
      return {
        next: () => {
          if (buffer.length) return Promise.resolve({ value: buffer.shift(), done: false });
          if (closed) return Promise.resolve({ value: undefined, done: true });
          return new Promise((resolve) => { parked = resolve; });
        },
      };
    },
  };
}

const collect = async (source) => {
  const out = [];
  for await (const v of source) out.push(v);
  return out;
};

// Pushed first, read afterwards: the buffer path.
const early = pushStream();
early.push('a');
early.push('b');
early.close();
const buffered = await collect(early);

// Read first, pushed afterwards: the parked path.
const live = pushStream();
const reading = collect(live);
live.push('x');
live.push('y');
live.close();
const streamed = await reading;

// A reader parked with nothing coming is released by close().
const idle = pushStream();
const pending = collect(idle);
idle.close();
const nothing = await pending;

// And the buffer is still drained after close, which is a real wrinkle.
const late = pushStream();
late.close();
late.push('late');
const afterClose = await collect(late);

console.log('buffered :', buffered);
console.log('streamed :', streamed);
console.log('idle     :', nothing);
console.log('pushed after close:', afterClose, '<- still delivered');

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30const both = {
  [Symbol.iterator]() {
    let i = 0;
    return { next: () => (i < 2 ? { value: 'sync ' + i++, done: false } : { value: undefined, done: true }) };
  },
  [Symbol.asyncIterator]() {
    let i = 0;
    return {
      next: () => Promise.resolve(i < 2 ? { value: 'async ' + i++, done: false } : { value: undefined, done: true }),
    };
  },
};

const collect = async (source) => {
  const out = [];
  for await (const v of source) out.push(v);
  return out;
};

const spread = [...both];
const syncLoop = [];
for (const v of both) syncLoop.push(v);
const asyncLoop = await collect(both);
const syncOnly = await collect({ [Symbol.iterator]: both[Symbol.iterator] });
const neither = (() => { try { return [...{}]; } catch (e) { return e.constructor.name; } })();

console.log('spread     :', spread);
console.log('for...of   :', syncLoop);
console.log('for await  :', asyncLoop, '<- the async one wins');
console.log('sync only, awaited:', syncOnly);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34const bank = {
  balances: { 'LAG-01': 45000, 'ABJ-02': 12000 },
  lookup(account, callback) {
    // Deliberately asynchronous: the callback never fires in the same tick.
    Promise.resolve().then(() =>
      account in this.balances
        ? callback(null, this.balances[account])
        : callback(new Error('no such account: ' + account))
    );
  },
};

const balanceOf = (account) =>
  new Promise((resolve, reject) => {
    bank.lookup(account, (err, value) => (err ? reject(err) : resolve(value)));
  });

let executorRan = false;
new Promise(() => { executorRan = true; });

const order = [];
const watching = balanceOf('LAG-01').then((v) => order.push('resolved ' + v));
order.push('the line after the call');
await watching;

const missing = await balanceOf('nope').then(() => 'resolved', (e) => e.message);
const twice = await new Promise((resolve) => { resolve('first'); resolve('second'); });
const thenRejected = await new Promise((resolve, reject) => { resolve('kept'); reject(new Error('ignored')); });
const blewUp = await new Promise(() => { throw new Error('executor blew up'); }).catch((e) => e.message);

console.log('balance   :', await balanceOf('ABJ-02'));
console.log('missing   :', missing);
console.log('order     :', order);
console.log('settled twice:', twice, ' rejected after resolving:', thenRejected);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29const promisify = (fn) => (...args) =>
  new Promise((resolve, reject) => {
    fn(...args, (err, value) => (err ? reject(err) : resolve(value)));
  });

const readFee = (plate, callback) => {
  const fees = { 'LAG-441-XA': 2500, 'ABJ-772-KM': 4000 };
  Promise.resolve().then(() =>
    plate in fees ? callback(null, fees[plate]) : callback(new Error('unknown plate: ' + plate))
  );
};

const feeFor = promisify(readFee);

// A METHOD is the problem case: it needs its receiver.
const till = {
  total: 9000,
  read(callback) { callback(null, this.total); },
};
const detachedFails = (() => {
  try { const loose = till.read; loose(() => {}); return 'no throw'; }
  catch (e) { return e.constructor.name; }
})();
const readTotal = promisify(till.read.bind(till));

console.log('fee      :', await feeFor('LAG-441-XA'));
console.log('unknown  :', await feeFor('XXX').then(() => 'resolved', (e) => e.message));
console.log('detached method:', detachedFails);
console.log('bound then promisified:', await readTotal());

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42async function mapLimit(items, limit, worker) {
  const results = new Array(items.length);
  let next = 0;
  const runner = async () => {
    while (next < items.length) {
      const index = next++;                 // claimed synchronously: no two runners share one
      results[index] = await worker(items[index], index);
    }
  };
  await Promise.all(Array.from({ length: Math.min(limit, items.length) }, runner));
  return results;
}

let active = 0;
let peak = 0;
const upload = async (n) => {
  active++;
  peak = Math.max(peak, active);
  await Promise.resolve();
  await Promise.resolve();
  active--;
  return n * 2;
};

const doubled = await mapLimit([1, 2, 3, 4, 5, 6, 7], 3, upload);

const sequential = [];
await mapLimit([1, 2, 3], 1, async (n) => {
  sequential.push('start ' + n);
  await Promise.resolve();
  sequential.push('end ' + n);
});

const failed = await mapLimit([1, 2, 3], 2, async (n) => {
  if (n === 2) throw new Error('item 2 failed');
  return n;
}).then(() => 'resolved', (e) => e.message);

console.log('results :', doubled);
console.log('peak    :', peak, 'of a limit of 3');
console.log('limit 1 :', sequential);
console.log('failure :', failed);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49// Simulated time. wait() records the delay and moves the clock instantly, so
// nothing here sleeps and the schedule can be asserted exactly.
function fakeClock() {
  let now = 0;
  const waits = [];
  return {
    get time() { return now; },
    get waits() { return waits.slice(); },
    wait(ms) { waits.push(ms); now += ms; return Promise.resolve(); },
  };
}

async function retry(task, { attempts = 4, baseMs = 200, capMs = Infinity, budgetMs = Infinity, clock }) {
  let last;
  for (let attempt = 1; attempt <= attempts; attempt++) {
    try { return { value: await task(attempt), attempt }; }
    catch (err) {
      last = err;
      if (attempt === attempts) break;
      const wait = Math.min(capMs, baseMs * 2 ** (attempt - 1));
      if (clock.time + wait > budgetMs) break;     // no point waiting past the budget
      await clock.wait(wait);
    }
  }
  throw new Error(`gave up after ${attempts} attempt(s)`, { cause: last });
}

const clock = fakeClock();
let calls = 0;
const flaky = async () => {
  calls++;
  if (calls < 3) throw new Error('502 from the gateway');
  return 'receipt LAG-0007';
};
const good = await retry(flaky, { baseMs: 200, clock });

const capped = fakeClock();
await retry(async () => { throw new Error('down'); }, { attempts: 5, baseMs: 100, capMs: 300, clock: capped }).catch(() => {});

const tight = fakeClock();
const gaveUp = await retry(async () => { throw new Error('down'); }, { attempts: 9, baseMs: 100, budgetMs: 350, clock: tight }).catch((e) => e);

const clean = fakeClock();
await retry(async () => 'first time', { clock: clean });

console.log('succeeded  :', good, 'after', clock.waits, 'ms of waiting');
console.log('capped     :', capped.waits);
console.log('budgeted   :', tight.waits, 'stopped at', tight.time, 'ms');
console.log('cause      :', gaveUp.cause.message);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48// A clock you drive by hand: timers fire only when you advance past them.
function manualClock() {
  let now = 0;
  const timers = [];
  return {
    get time() { return now; },
    get pending() { return timers.length; },
    wait(ms) { return new Promise((resolve) => timers.push({ at: now + ms, resolve })); },
    async advance(ms) {
      now += ms;
      for (const t of timers.filter((t) => t.at <= now)) {
        timers.splice(timers.indexOf(t), 1);
        t.resolve();
      }
      for (let i = 0; i < 8; i++) await Promise.resolve();   // let the waiters run
    },
  };
}

const withTimeout = (work, ms, clock) =>
  Promise.race([
    work,
    clock.wait(ms).then(() => { throw new Error(`timed out after ${ms}ms`); }),
  ]);

const clock = manualClock();
const wonByWork = await withTimeout(Promise.resolve('paid'), 1000, clock);
const leakedTimer = clock.pending;

let finish;
const slow = new Promise((resolve) => { finish = resolve; });
const running = withTimeout(slow, 5000, clock).then((v) => 'value ' + v, (e) => e.message);
await clock.advance(5000);
const timedOut = await running;
finish('late receipt');
const workStillFinished = await slow;

const edge = manualClock();
const onTheBoundary = withTimeout(new Promise(() => {}), 100, edge).catch((e) => e.message);
await edge.advance(99);
const notYet = edge.pending;
await edge.advance(1);
const fired = await onTheBoundary;

console.log('work won  :', wonByWork, '- timers still pending:', leakedTimer);
console.log('timed out :', timedOut);
console.log('yet the work finished anyway:', workStillFinished);
console.log('at 99ms pending:', notYet, ' at 100ms:', fired);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30const tills = () => [
  Promise.resolve('till 1: ₦2,500'),
  Promise.reject(new Error('till 2 offline')),
  Promise.resolve('till 3: ₦4,000'),
];

const fromAll = await Promise.all(tills()).then((v) => ({ ok: v }), (e) => ({ error: e.message }));
const fromSettled = (await Promise.allSettled(tills())).map((r) =>
  r.status === 'fulfilled' ? r.value : 'ERR: ' + r.reason.message
);
const fromAny = await Promise.any(tills());
const fromRace = await Promise.race(tills()).then((v) => v, (e) => 'rejected: ' + e.message);

const raceCanReject = await Promise.race([
  Promise.reject(new Error('first to settle')),
  Promise.resolve('a success that was available'),
]).then(() => 'resolved', (e) => e.message);

const allRejected = await Promise.any([Promise.reject(new Error('a')), Promise.reject(new Error('b'))])
  .catch((e) => [e.constructor.name, e.errors.map((x) => x.message)]);

let emptyRace = 'still pending';
Promise.race([]).then(() => { emptyRace = 'settled'; });
for (let i = 0; i < 6; i++) await Promise.resolve();

console.log('all       :', fromAll);
console.log('allSettled:', fromSettled);
console.log('any       :', fromAny);
console.log('race      :', fromRace);
console.log('empties   : all', await Promise.all([]), ' race:', emptyRace);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18const failed = Promise.reject(new Error('nobody is listening'));

let picked = '';
await Promise.resolve();                          // a turn goes by, still unhandled
await failed.catch((e) => { picked = e.message; });

const secondLook = await failed.catch((e) => e.message);
const recovered = await failed.catch(() => 'recovered');
const carriedOn = await failed.catch(() => 0).then((n) => n + 1);
const throwInThen = await Promise.resolve(1).then(() => { throw new Error('thrown in then'); }).catch((e) => e.message);
const skipped = await Promise.reject(new Error('skipped past')).then(() => 'not run').catch((e) => e.message);
const throwInCatch = await Promise.reject(new Error('a')).catch(() => { throw new Error('b'); }).catch((e) => e.message);
const notAnError = await Promise.reject('just a string').catch((e) => [typeof e, e]);

console.log('picked up later :', picked);
console.log('and again       :', secondLook);
console.log('catch recovers  :', recovered, '-> chain continues:', carriedOn);
console.log('rejecting with a non-Error:', notAnError);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40const makeTask = (log) => async (name, rounds) => {
  log.push('start ' + name);
  for (let i = 0; i < rounds; i++) await Promise.resolve();
  log.push('end ' + name);
  return name.toUpperCase();
};

const peakOf = (log) => {
  let inFlight = 0;
  let peak = 0;
  for (const line of log) {
    if (line.startsWith('start')) peak = Math.max(peak, ++inFlight);
    else inFlight--;
  }
  return peak;
};

const seqLog = [];
const seqTask = makeTask(seqLog);
const seqOut = [];
for (const name of ['a', 'b', 'c']) seqOut.push(await seqTask(name, 2));

const parLog = [];
const parTask = makeTask(parLog);
const parOut = await Promise.all(['a', 'b', 'c'].map((name) => parTask(name, 2)));

// When each step needs the one before it, the loop is right.
const chain = [];
let carry = 1;
for (const factor of [2, 3, 4]) { carry = await Promise.resolve(carry * factor); chain.push(carry); }

// forEach does not await, so this collects nothing at all.
const dropped = [];
['a', 'b'].forEach(async (v) => { await Promise.resolve(); dropped.push(v); });
const droppedNow = [...dropped];

console.log('sequential:', seqLog);
console.log('parallel  :', parLog);
console.log('peaks     :', peakOf(seqLog), 'against', peakOf(parLog));
console.log('forEach right after the loop:', droppedNow);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54class AsyncQueue {
  #tail = Promise.resolve();
  #pending = 0;

  get pending() { return this.#pending; }

  add(task) {
    this.#pending++;
    const result = this.#tail.then(() => task());
    // The tail must absorb failures, or one bad task blocks the queue for ever.
    this.#tail = result.then(
      () => { this.#pending--; },
      () => { this.#pending--; }
    );
    return result;
  }

  drain() { return this.#tail; }
}

const log = [];
const step = (name, rounds) => async () => {
  log.push('start ' + name);
  for (let i = 0; i < rounds; i++) await Promise.resolve();
  log.push('end ' + name);
  return name;
};

const q = new AsyncQueue();
const results = await Promise.all([q.add(step('a', 3)), q.add(step('b', 1)), q.add(step('c', 0))]);

const failLog = [];
const q2 = new AsyncQueue();
const bad = q2.add(async () => { failLog.push('bad'); throw new Error('kaboom'); }).catch((e) => e.message);
const good = q2.add(async () => { failLog.push('good'); return 'ran anyway'; });
const outcome = [await bad, await good];

const counting = new AsyncQueue();
counting.add(async () => 1);
counting.add(async () => 2);
const whileBusy = counting.pending;
await counting.drain();
const whenDrained = counting.pending;

const syncLog = [];
const q3 = new AsyncQueue();
q3.add(() => { syncLog.push('sync task'); return 'done'; });
const beforeDrain = [...syncLog];
await q3.drain();

console.log('order    :', log);
console.log('results  :', results);
console.log('failure  :', outcome, failLog);
console.log('pending  :', whileBusy, '->', whenDrained);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61function createMutex() {
  let chain = Promise.resolve();
  let held = false;
  return {
    get held() { return held; },
    acquire() {
      let release;
      const released = new Promise((resolve) => {
        release = () => { held = false; resolve(); };
      });
      const mine = chain.then(() => { held = true; return release; });
      chain = chain.then(() => released);      // the next acquirer waits for this release
      return mine;
    },
    async runExclusive(fn) {
      const release = await this.acquire();
      try { return await fn(); } finally { release(); }
    },
  };
}

let balance = 100000;
const withdrawUnsafe = async (naira) => {
  const current = balance;          // read
  await Promise.resolve();          // ...anything at all happens here
  balance = current - naira;        // write, from a stale read
};
await Promise.all([withdrawUnsafe(30000), withdrawUnsafe(50000)]);
const lost = balance;

balance = 100000;
const mutex = createMutex();
const withdrawSafe = (naira) =>
  mutex.runExclusive(async () => {
    const current = balance;
    await Promise.resolve();
    balance = current - naira;
  });
await Promise.all([withdrawSafe(30000), withdrawSafe(50000)]);
const safe = balance;

const order = [];
const m2 = createMutex();
const first = m2.runExclusive(async () => {
  order.push('a in');
  await Promise.resolve();
  await Promise.resolve();
  order.push('a out');
});
const second = m2.runExclusive(async () => { order.push('b in'); order.push('b out'); });
await Promise.all([first, second]);

const m3 = createMutex();
const blewUp = await m3.runExclusive(async () => { throw new Error('inside the lock'); }).catch((e) => e.message);
const stillFree = m3.held;
const nextHolder = await m3.runExclusive(async () => 'not deadlocked');

console.log('without a lock:', lost, 'instead of', 100000 - 30000 - 50000);
console.log('with a lock   :', safe);
console.log('holder order  :', order);
console.log('after a throw :', blewUp, '- held:', stillFree);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69function createSemaphore(permits) {
  let free = permits;
  const waiting = [];
  return {
    get free() { return free; },
    get queued() { return waiting.length; },
    acquire() {
      if (free > 0) { free--; return Promise.resolve(); }
      return new Promise((resolve) => waiting.push(resolve));
    },
    release() {
      const next = waiting.shift();
      if (next) next();               // handed straight on: the count never moves
      else free++;
    },
    async use(fn) {
      await this.acquire();
      try { return await fn(); } finally { this.release(); }
    },
  };
}

const sem = createSemaphore(2);
let active = 0;
let peak = 0;
const job = (n) =>
  sem.use(async () => {
    active++;
    peak = Math.max(peak, active);
    await Promise.resolve();
    await Promise.resolve();
    active--;
    return n;
  });
const out = await Promise.all([1, 2, 3, 4, 5].map(job));

const one = createSemaphore(1);
let mutexPeak = 0;
let mutexActive = 0;
await Promise.all([1, 2, 3].map(() =>
  one.use(async () => {
    mutexActive++;
    mutexPeak = Math.max(mutexPeak, mutexActive);
    await Promise.resolve();
    mutexActive--;
  })
));

const queueing = createSemaphore(1);
queueing.acquire();
queueing.acquire();
const queuedState = [queueing.free, queueing.queued];

const handoff = createSemaphore(1);
await handoff.acquire();
const waiter = handoff.acquire();
handoff.release();
const duringHandoff = handoff.free;
await waiter;

const afterThrow = await (async () => {
  const s = createSemaphore(1);
  await s.use(async () => { throw new Error('x'); }).catch(() => {});
  return s.free;
})();

console.log('results:', out, ' peak:', peak, 'of 2');
console.log('permits of 1 behaves as a mutex, peak:', mutexPeak);
console.log('one permit, two acquirers:', queuedState);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21const chained = await Promise.resolve(1)
  .then((n) => n + 1)                                       // a value is wrapped
  .then((n) => Promise.resolve(n * 10))                      // a promise is adopted
  .then((n) => ({ then: (resolve) => resolve(n + 5) }));     // a thenable, adopted too

const sameObject = (() => { const p = Promise.resolve(1); return p.then((x) => x) === p; })();
const resolveIsIdentity = (() => { const p = Promise.resolve(1); return Promise.resolve(p) === p; })();
const nested = await Promise.resolve(Promise.resolve('deep'));
const nothingReturned = String(await Promise.resolve(1).then(() => {}));
const ignoredHandler = await Promise.resolve('kept').then(null).then((v) => v);

const rounds = [];
Promise.resolve().then(() => rounds.push(1)).then(() => rounds.push(4)).then(() => rounds.push(6));
Promise.resolve().then(() => rounds.push(2)).then(() => rounds.push(5)).then(() => rounds.push(7));
Promise.resolve().then(() => rounds.push(3));
for (let i = 0; i < 8; i++) await Promise.resolve();

console.log('1 -> +1 -> x10 -> +5 =', chained);
console.log('then returns a new promise?', !sameObject, ' Promise.resolve is identity?', resolveIsIdentity);
console.log('returning nothing gives:', nothingReturned);
console.log('interleaving:', rounds);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38const order = [];
let release;
const slowCleanup = new Promise((resolve) => { release = resolve; });

let sawArguments = -1;
const passedThrough = await Promise.resolve('₦2,500 paid').finally((...args) => {
  sawArguments = args.length;                  // nothing is passed in
  return 'this return value is thrown away';   // and nothing comes out
});

let cleanups = 0;
const rejectionSurvives = await Promise.reject(new Error('till 2 offline'))
  .finally(() => { cleanups++; })
  .catch((err) => err.message);
await Promise.resolve('ok').finally(() => { cleanups++; });

const throwWins = await Promise.resolve('would have been kept')
  .finally(() => { throw new Error('cleanup itself failed'); })
  .catch((err) => err.message);

const originalBuried = await Promise.reject(new Error('the real problem'))
  .finally(() => { throw new Error('cleanup itself failed'); })
  .catch((err) => err.message);

// A promise returned from finally IS waited for, even though its value is dropped.
const delayed = Promise.resolve('receipt LAG-0031')
  .finally(() => slowCleanup.then(() => order.push('cleanup finished')));
delayed.then((value) => order.push('caller got ' + value));
for (let i = 0; i < 6; i++) await Promise.resolve();
const beforeRelease = order.slice();
release();
await delayed;
for (let i = 0; i < 4; i++) await Promise.resolve();

console.log('through   :', passedThrough, '- arguments seen:', sawArguments);
console.log('rejection :', rejectionSurvives, '- cleanups run:', cleanups);
console.log('a throw   :', throwWins, '/', originalBuried);
console.log('order     :', beforeRelease, '->', order);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55const receipt = () => {
  try { return 'receipt LAG-0011'; }
  finally { /* release the printer, change nothing */ }
};

const overridden = () => {
  try { return 'receipt LAG-0011'; }
  finally { return 'whatever finally says'; }    // wins, silently
};

const swallowed = () => {
  try { throw new Error('printer offline'); }
  finally { return 'looks like a success'; }     // the throw is gone
};

const byValue = () => {
  let out = 'first';
  try { return out; }
  finally { out = 'changed after the return'; }  // too late: the value was taken
};

const byReference = () => {
  const out = { total: 1 };
  try { return out; }
  finally { out.total = 2; }                     // same object, so the caller sees it
};

const order = [];
const timing = () => {
  try { order.push('return computed'); return 'value'; }
  finally { order.push('finally ran'); }
};
timing();
order.push('caller resumed');

const asyncOverride = async () => {
  try { return await Promise.reject(new Error('gateway down')); }
  finally { return 'finally wins here too'; }
};
const rejectionLost = await asyncOverride();

const tills = [];
for (const till of ['ikeja', 'yaba', 'lekki']) {
  try {
    if (till === 'yaba') continue;
    tills.push(till);
  } finally {
    tills.push('closed ' + till);
  }
}

console.log('plain / overridden :', receipt(), '/', overridden());
console.log('a throw swallowed  :', swallowed());
console.log('value vs reference :', byValue(), '/', byReference());
console.log('continue           :', tills);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74class CancelledError extends Error {
  constructor(reason) {
    super(reason);
    this.name = 'CancelledError';
  }
}

function cancellation() {
  let cancelled = false;
  let reason = '';
  const listeners = [];
  return {
    get cancelled() { return cancelled; },
    get reason() { return reason; },
    throwIfCancelled() { if (cancelled) throw new CancelledError(reason); },
    onCancel(fn) { if (cancelled) fn(reason); else listeners.push(fn); },
    cancel(why) {
      if (cancelled) return false;                       // the first cancel wins
      cancelled = true;
      reason = why;
      for (const fn of listeners.splice(0)) fn(why);
      return true;
    },
  };
}

// The work co-operates: it checks the token before each unit of work.
async function payOut(tills, token, onStep) {
  const paid = [];
  for (const till of tills) {
    token.throwIfCancelled();
    await Promise.resolve();                             // the transfer
    paid.push(till);
    if (onStep) onStep(till);
  }
  return paid;
}

const token = cancellation();
const notified = [];
token.onCancel((why) => notified.push(why));

const seen = [];
const outcome = await payOut(['ikeja', 'yaba', 'lekki', 'ajah'], token, (till) => {
  seen.push(till);
  if (till === 'yaba') token.cancel('user closed the tab');
}).catch((err) => err);

const secondCancel = token.cancel('a different reason');
let lateSubscriber = 'never told';
token.onCancel((why) => { lateSubscriber = why; });

const dead = cancellation();
dead.cancel('cancelled before it started');
const never = [];
const nothingRan = await payOut(['ikeja'], dead, (till) => never.push(till)).catch((err) => err.name);

// The honest limit: cancelling mid-step does not interrupt that step.
const late = cancellation();
const finished = [];
const inFlight = (async () => {
  late.throwIfCancelled();
  await Promise.resolve();
  finished.push('the step that was already running');
  late.throwIfCancelled();
  finished.push('a step that never starts');
})().catch((err) => err.name);
late.cancel('too late for the step in flight');
const interrupted = await inFlight;

console.log('paid before the cancel :', seen);
console.log('outcome                :', outcome.name + ': ' + outcome.message);
console.log('already cancelled      :', nothingRan, '- steps run:', never.length);
console.log('mid-step cancel        :', interrupted, finished);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40class PaymentError extends Error {
  constructor(message, options) {
    super(message, options);
    this.name = 'PaymentError';
  }
}

class InsufficientFunds extends PaymentError {
  constructor(shortfall, options) {
    super(`short by ₦${shortfall}`, options);
    this.name = 'InsufficientFunds';
    this.shortfall = shortfall;
  }
}

class Bare extends Error {}                    // the trap: no name assigned

const err = new InsufficientFunds(1500);
const chain = [
  err instanceof InsufficientFunds,
  err instanceof PaymentError,
  err instanceof Error,
  err instanceof TypeError,
];

const handle = (e) => {
  if (e instanceof InsufficientFunds) return 'top up ₦' + e.shortfall;
  if (e instanceof PaymentError) return 'payment problem: ' + e.message;
  return 'not ours: ' + e.name;
};
const routed = [handle(err), handle(new PaymentError('card declined')), handle(new RangeError('out of range'))];

const bare = new Bare('printer offline');
const survivesRejection = await Promise.reject(err).catch((e) => e instanceof InsufficientFunds);
const wrapped = new PaymentError('could not take payment', { cause: bare });

console.log('description :', String(err));
console.log('routed      :', routed);
console.log('the trap    :', bare.name, '/', String(bare), '/ but constructor:', bare.constructor.name);
console.log('own keys    :', Object.keys(err));

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35const socket = new Error('ECONNRESET from the card network');
const driver = new Error('charge request failed', { cause: socket });
const service = new Error('could not take payment for order LAG-0035', { cause: driver });

function chainOf(err) {
  const messages = [];
  const seen = new Set();
  let current = err;
  while (current instanceof Error && !seen.has(current)) {
    seen.add(current);
    messages.push(current.message);
    current = current.cause;
  }
  return messages;
}

function rootCause(err) {
  const seen = new Set();
  let current = err;
  while (current.cause instanceof Error && !seen.has(current.cause)) {
    seen.add(current);
    current = current.cause;
  }
  return current;
}

const loopA = new Error('a');
const loopB = new Error('b', { cause: loopA });
loopA.cause = loopB;                                  // a cycle, by accident

const report = chainOf(service).map((m, depth) => '  '.repeat(depth) + m).join('\n');
console.log('the chain, outside in:');
console.log(report);
console.log('root cause :', rootCause(service).message);
console.log('serialised :', JSON.stringify(service), Object.keys(service));

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29const uploads = () => [
  Promise.resolve('ikeja receipts'),
  Promise.reject(new Error('yaba: timed out')),
  Promise.resolve('lekki receipts'),
  Promise.reject(new Error('ajah: 500 from the API')),
];

async function allOrReport(tasks) {
  const settled = await Promise.allSettled(tasks);
  const failures = settled.filter((r) => r.status === 'rejected').map((r) => r.reason);
  if (failures.length) {
    throw new AggregateError(failures, `${failures.length} of ${settled.length} uploads failed`);
  }
  return settled.map((r) => r.value);
}

const agg = await allOrReport(uploads()).catch((err) => err);
const clean = await allOrReport([Promise.resolve('one'), Promise.resolve('two')]);
const fromSet = new AggregateError(new Set([new Error('a'), new Error('b')]), 'from any iterable');
const nested = new Error('nightly batch failed', { cause: agg });
const builtForYou = await Promise.any([
  Promise.reject(new Error('mirror 1 down')),
  Promise.reject(new Error('mirror 2 down')),
]).catch((err) => [err.name, err.errors.length, err.message.length > 0]);

console.log('summary  :', agg.message);
console.log('reasons  :', agg.errors.map((e) => e.message));
console.log('clean run:', clean);
console.log('serialise:', JSON.stringify(agg), Object.keys(agg));

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65class RepositoryError extends Error {
  constructor(message, options) {
    super(message, options);
    this.name = 'RepositoryError';
  }
}

const failures = [];
const driver = () => {
  const err = new RepositoryError('duplicate key on tills.name');
  failures.push(err);                                   // so the test can compare identity
  throw err;
};

const rethrown = () => { try { driver(); } catch (err) { throw err; } };
const rebuilt = () => { try { driver(); } catch (err) { throw new Error(err.message); } };
const wrapped = () => { try { driver(); } catch (err) { throw new Error('could not save the till', { cause: err }); } };

const bare = (() => {
  try { rethrown(); } catch (err) { return { sameObject: err === failures.at(-1), name: err.name }; }
})();

const flat = (() => {
  try { rebuilt(); } catch (err) {
    return {
      isRepositoryError: err instanceof RepositoryError,
      causeMissing: err.cause === undefined,
      sameStack: err.stack === failures.at(-1).stack,
    };
  }
})();

const kept = (() => {
  try { wrapped(); } catch (err) {
    return {
      message: err.message,
      causeIsOriginal: err.cause === failures.at(-1),
      causeStillTyped: err.cause instanceof RepositoryError,
    };
  }
})();

// Handle what you understand; rethrow the rest exactly as it came.
const handleOnly = (fn) => {
  try { return fn(); }
  catch (err) {
    if (err instanceof RepositoryError) return 'handled: ' + err.message;
    throw err;
  }
};
const mine = handleOnly(driver);
const notMine = (() => {
  try { handleOnly(() => { throw new TypeError('cannot read property of undefined'); }); }
  catch (err) { return err.name; }
})();

const target = new RepositoryError('carried across an await');
const acrossAwait = await (async () => {
  try { await Promise.reject(target); } catch (err) { throw err; }
})().then(() => false, (err) => err === target);

console.log('rethrown :', bare);
console.log('rebuilt  :', flat);
console.log('wrapped  :', kept);
console.log('selective:', mine, '/ passed through:', notMine);