# API

> @dev-bench/utils diagnostics API reference.

Source: https://utils.n.yatsyk.com/docs/core/api

# 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

Each console line starts with a marker glyph (the docs font has no glyph for some of them, so the table names only the text after it).

| Export               | Signature                                                                    | Dedup'd?                    | Console                                   |
| -------------------- | ---------------------------------------------------------------------------- | --------------------------- | ----------------------------------------- |
| `warnNotImplemented` | `(category: string, detail: string) => void`                                 | yes (`not-impl:<category>`) | `console.warn` line `NOT IMPLEMENTED ...` |
| `warnDegraded`       | `(category: string, detail: string) => void`                                 | yes (`degraded:<category>`) | `console.warn` line `DEGRADED ...`        |
| `warnUnexpected`     | `(category: string, detail: string, data?: Record<string, unknown>) => void` | no                          | `console.error` line `UNEXPECTED ...`     |
| `logInfo`            | `(category: string, detail: string, data?: Record<string, unknown>) => void` | no                          | `console.log` line `INFO ...`             |
| `logError`           | `(category: string, err: unknown, detail?: string) => void`                  | no                          | `console.error` line `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 }`<br /> `\| { 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](/docs/core/jsdoc) for the full surface.