Reports for logs and agents

A shutdown produces one record. Handlers receive its first four fields while it runs; when it is over, the registry's report — and the value registry.run() resolves with — adds what the deadline found:

unfinished is non-empty in two cases: the deadline fired, or the path was exit, where Node gives no time at all and an async handler never had a turn.

Two projections of the one recordCopy Anchor Link

reportToJson(report) is one line of JSON for a program's --json mode, with error flattened to text — JSON.stringify of an Error is {}, which looks like a report and carries nothing. reportToEvent(report) is the same values under the family's event key, type: 'closeout.shutdown', for an agent's event stream. Both come from the record the handlers were given, so a log line and an agent event cannot disagree with it.

Hand either to onTimeout, and a breached deadline is reported as data instead of a sentence:

import { install, reportToJson } from 'closeout';

const { onExit } = install({
  deadline: 100,
  onTimeout: (report) => console.error(reportToJson(report)),
});

onExit(() => new Promise(() => {}), { phase: 'flush', label: 'upload-the-trace' });

setTimeout(() => {}, 10_000);
process.kill(process.pid, 'SIGTERM');

{"path":"signal","signal":"SIGTERM","code":null,"error":null,"timedOut":true,"unfinished":["upload-the-trace"]}

Reading the report after a clean shutdownCopy Anchor Link

A registry you drive yourself resolves run() with the report, and keeps it on registry.report for a later caller — including after runSync, which cannot return a promise:

import { createRegistry, reportToEvent } from 'closeout';

const registry = createRegistry({ onError: (error) => console.log(`a handler failed: ${error.message}`) });
registry.add(() => {
  throw new Error('disk full');
}, 'flush');

const report = await registry.run({ code: 1, signal: null, path: 'uncaught', error: new Error('mid-render') });
const event = reportToEvent(report);
console.log(event.type, event.path, event.code, event.timedOut, event.error.split('\n')[0]);

a handler failed: disk full
closeout.shutdown uncaught 1 false Error: mid-render

A handler's own failure is not in the report. It goes to onError — stderr unless you pass one — because the report says how the program left, and a failed handler is a separate fact about one handler.

What is testedCopy Anchor Link

• report.test.ts: the path is inferred only when unstated; an Error and a non-Error rejection both become text; the JSON is one line naming every handler that hung; the event is the same values under the family's key.