Diagnostics

Everything the framework recovers from is reported on one cancelable event, and nothing in core calls console.warn() or console.error() directly.

The exports

• EVENTS — the framework event names
• DIAGNOSTICS — every code
• reportDiagnostic(code, message, error, ctx?) — report an error
• warn(code, message, ctx?) — report a warning

From inside a component, $warn() and $error() fill the component name in.

The detail

type ToolkitDiagnosticDetail =
  | {
      readonly severity: 'warning';
      readonly code: ToolkitDiagnosticCode;
      readonly message: string;
      readonly component?: string;
      readonly error?: never;
    }
  | {
      readonly severity: 'error';
      readonly code: ToolkitDiagnosticCode;
      readonly message: string;
      readonly component?: string;
      readonly error: unknown;
    };

An error detail requires the original caught value; a warning carries none. That is a union, not an optional field, so a listener that reads detail.error has already narrowed on severity.

Listening

document.addEventListener(EVENTS.diagnostic, (rawEvent) => {
  const event = rawEvent as CustomEvent<ToolkitDiagnosticDetail>;
  monitor(event.detail.code, event.detail);

  if (event.detail.code === DIAGNOSTICS.responsive.unknownBreakpoint) {
    event.preventDefault();
  }
});

Every diagnostic starts on its relevant connected element, or on document when there is none, with { bubbles: true, composed: true, cancelable: true }.

Dispatch always happens before the default output. An uncancelled warning calls console.warn() once with exactly [js-toolkit:<code>] <message>; an uncancelled error calls reportError(detail.error) with the original value. preventDefault() suppresses that output only and changes no framework decision.

Read next

Diagnostics.