Diagnostics
API
All exports come from @dev-bench/utils (re-exported from
./diagnostics/index.js). Every emitter writes a DiagnosticEvent to the
configured hook (if any), then writes the canonical line to
console.{warn,error,log}.
Emitters
| Export | Signature | Dedup'd? | Console |
|---|---|---|---|
warnNotImplemented | (category: string, detail: string) => void | yes (not-impl:<category>) | console.warn("⚠ NOT IMPLEMENTED ...") |
warnDegraded | (category: string, detail: string) => void | yes (degraded:<category>) | console.warn("⚡ DEGRADED ...") |
warnUnexpected | (category: string, detail: string, data?: Record<string, unknown>) => void | no | console.error("🔴 UNEXPECTED ...") |
logInfo | (category: string, detail: string, data?: Record<string, unknown>) => void | no | console.log("ℹ INFO ...") |
logError | (category: string, err: unknown, detail?: string) => void | no | console.error("❌ ERROR ...") |
logError serializes its err argument: Error instances are flattened to
{ name, message, stack } on event.data; anything else is passed through
as { err }. When detail is omitted it falls back to err.message (or
String(err) for non-Error throws), making .catch(logError) work as a
one-liner.
tryCatchWarn
| Export | Signature | Summary |
|---|---|---|
tryCatchWarn | <T>(category: string, fn: () => T | Promise<T>) => Promise<TryCatchResult<T>> | Runs fn; routes any throw through logError(category, err) and returns the failure as data. |
TryCatchResult<T> | | { ok: true; value: T }| { ok: false; error: unknown } | Discriminated union — callers MUST .exhaustive() over { ok }. |
Always returns a Promise, even when fn is synchronous — keeps the type
monomorphic and forces every call site to await.
Hook + reset
| Export | Signature | Summary |
|---|---|---|
setDiagnosticHook | (fn: ((e: DiagnosticEvent) => void) | null) => void | Install or clear the hook. The hook fires before the console.* line. |
resetDiagnostics | () => void | Clears the dedup Set. Test-only — call from beforeEach. |
Types
| Export | Shape | Summary |
|---|---|---|
DiagnosticKind | "not-implemented" | "degraded" | "unexpected" | "info" | "error" | Discriminator on DiagnosticEvent.kind. |
DiagnosticEvent | { kind: DiagnosticKind; category: string; detail: string; stack: string; data?: Record<string, unknown>; timestamp: number } | What the hook receives. stack is a 3-frame mini-stack, not the full trace. |
TryCatchResult<T> | see above | Returned by tryCatchWarn. |
See the generated JSDoc reference for the full surface.