TeqBench Angular Errors

@teqbench/tbx-ngx-errors
angularv2.1.0

Pluggable multi-layer error handling pipeline for Angular. Provides an HTTP error interceptor, a global error handler, and a manual client-error logger utility — all unified through a swappable TbxNgxErrorLoggerService abstraction that routes every error (caught and uncaught, HTTP and application) through a single extension point.

@teqbench/tbx-ngx-errors provides a unified error-handling pipeline for Angular applications. Rather than sprinkling logging calls across every service, component, and catch block, the package captures errors at three well-defined layers and routes all of them through a single, swappable logger abstraction.

The three capture layers are independent and composable: tbxNgxHttpErrorInterceptor captures failed HTTP responses before they propagate; TbxNgxGlobalErrorHandlerService implements Angular's `ErrorHandler` to catch uncaught application errors (and deliberately skips HTTP errors so layer one owns them); logClientError gives services and components an ergonomic utility for logging errors caught explicitly in try/catch blocks. All three build the same TbxNgxErrorContextModel — a structured record with timestamp, URL, message, stack, and HTTP-specific fields — and delegate to the injected TbxNgxErrorLoggerService.

The logger itself is the extension point. A default console logger ships with the package; a composite logger fans out to any number of registered backends, so consumers can write to the console, ship to Sentry or LogRocket, and raise a UI toast from a single error event without modifying any of the capture layers. The package is built for Angular 21+ zoneless applications, is SSR-safe (guards against window access in the interceptor and handler), and carries no @teqbench runtime dependencies.

When to use

Reach for this package when your Angular application needs:

  • A unified extension point for routing every error — caught and uncaught, HTTP and application — through a single logger abstraction.
  • To plug in a remote logging backend like Sentry or LogRocket without editing every catch block.
  • Composition of multiple loggers (e.g., console for dev plus a remote backend for production) via a fan-out composite.

Skip it when your app only needs ad-hoc try/catch logging and has no plans for a centralized logging backend — the plumbing is overkill for that case.

At a glance

  • HTTP error interceptor — Functional interceptor that captures failed HTTP responses and delegates to the logging pipeline.
  • Global error handler — Angular ErrorHandler implementation that captures uncaught application errors, skipping HTTP errors already handled by the interceptor.
  • Manual client-error logger — logClientError utility for routing explicitly caught errors through the same pipeline from any service or component.
  • Pluggable logger abstraction — Abstract TbxNgxErrorLoggerService acts as the single swap point for routing errors to any backend.
  • Console logger — Default TbxNgxConsoleErrorLoggerService for local development.
  • Composite fan-out logger — TbxNgxCompositeErrorLoggerService broadcasts each error to multiple registered backends (console + remote + UI toast).
  • Structured error context — Every error flows through as a TbxNgxErrorContextModel with timestamp, URL, message, stack, and optional HTTP status and URL.
  • SSR-safe — Window access in the interceptor and global handler is guarded so errors raised during server-side rendering do not crash.
  • Promise rejection unwrapping — The global handler automatically unwraps Angular-wrapped promise rejections before logging.
  • Zoneless ready — Built for Angular 21+ zoneless applications with no Zone.js dependency.

Concepts

  • Capture layer — One of three places where errors enter the pipeline — the HTTP interceptor, the global error handler, or a manual logClientError call.
  • Logger abstraction — The abstract TbxNgxErrorLoggerService that every capture layer delegates to; consumers swap in a concrete implementation via Angular DI.
  • Error context model — TbxNgxErrorContextModel — a structured record built by every capture layer with timestamp, URL, message, stack, and HTTP-specific fields.
  • Composite logger — A logger that broadcasts each error to a list of registered child loggers, enabling fan-out to multiple backends without altering the capture layers.
  • HTTP vs application error — HTTP errors are captured by the interceptor and skipped by the global handler; uncaught application errors are captured by the global handler.
  • Manual capture — Logging an explicitly caught error through logClientError rather than letting it propagate to the global handler.
  • Extension point — The single site (TbxNgxErrorLoggerService) where a consumer plugs in remote logging or UI-surfacing without touching any capture layer.

Services

TbxNgxCompositeErrorLoggerService

Composite logger that broadcasts errors to multiple registered backends

Enables a fan-out pattern, allowing the consuming app to log to the console (for developers) and a notification service (for users) simultaneously without modifying any of the capture layers — TbxNgxGlobalErrorHandlerService, tbxNgxHttpErrorInterceptor, or logClientError.

When to use

Use when the application needs to dispatch errors to more than one destination (e.g., console + Sentry + toast notification). Create an instance, register backends with addLogger, and provide it as the TbxNgxErrorLoggerService implementation.

Example

// app.config.ts
{
  provide: TbxNgxErrorLoggerService,
  useFactory: () => {
    const composite = new TbxNgxCompositeErrorLoggerService();
    composite.addLogger(new TbxNgxConsoleErrorLoggerService());
    // ToastErrorLogger is a hypothetical consumer-defined subclass
    composite.addLogger(inject(ToastErrorLogger));
    return composite;
  }
}

TbxNgxConsoleErrorLoggerService

Default error logger that writes human-readable output to the browser console

HTTP errors and application errors are formatted distinctly for quick identification during development. Replace with a remote logger (Sentry, LogRocket, custom API) for production use.

When to use

Use as the default logger during development. For production, swap in a remote logging implementation via the TbxNgxErrorLoggerService DI token.

Example

// app.config.ts
{ provide: TbxNgxErrorLoggerService, useClass: TbxNgxConsoleErrorLoggerService }

TbxNgxErrorLoggerService

Abstract error logger — the extension point for error reporting backends

Both TbxNgxGlobalErrorHandlerService and tbxNgxHttpErrorInterceptor delegate to this class, so swapping the implementation in app.config.ts routes all errors (HTTP and application) to the same backend.

The package ships TbxNgxConsoleErrorLoggerService as a ready-made implementation, but consumers must explicitly register it (or a custom subclass) via { provide: TbxNgxErrorLoggerService, useClass: ... } in app.config.ts.

When to use

Extend this class to create a custom error logging backend. Provide the subclass via Angular DI to route all pipeline errors to the custom destination.

Example

// app.config.ts
// SentryErrorLogger is a hypothetical consumer-defined subclass
{ provide: TbxNgxErrorLoggerService, useClass: SentryErrorLogger }

TbxNgxGlobalErrorHandlerService

Angular ErrorHandler that captures uncaught application errors and routes them through the logging pipeline

HTTP errors are skipped because they are already handled by tbxNgxHttpErrorInterceptor. Promise rejections are automatically unwrapped before logging. Uses Injector to lazily resolve TbxNgxErrorLoggerService, avoiding a circular dependency on ErrorHandler during DI initialization.

When to use

Provide as Angular's ErrorHandler in app.config.ts to capture all uncaught application errors and route them through the pluggable logging pipeline.

Example

// app.config.ts
{ provide: ErrorHandler, useClass: TbxNgxGlobalErrorHandlerService }

Interfaces

TbxNgxErrorContextModel

Structured context attached to every error passed through the error handling pipeline

Both the tbxNgxHttpErrorInterceptor and the TbxNgxGlobalErrorHandlerService produce this same shape, ensuring a consistent contract for any logging backend.

The generic type parameters allow consuming apps to narrow the classification fields to application-specific enums or literal unions while defaulting to plain strings for simple use cases.

When to use

Use this interface when building custom error loggers that need to inspect or transform error metadata before forwarding to a remote service.

Constants

tbxNgxHttpErrorInterceptor

HTTP error interceptor that captures failed responses and delegates to the logging pipeline

Builds a structured TbxNgxErrorContextModel with HTTP-specific details (status code, request URL) and delegates to the same TbxNgxErrorLoggerService backend used by TbxNgxGlobalErrorHandlerService.

Every HTTP error is logged, then re-thrown so subscribers can handle it in their own error callbacks (e.g., showing form validation messages).

When to use

Register as an HTTP interceptor in app.config.ts using provideHttpClient with withInterceptors to automatically capture and log all HTTP errors.

Example

// app.config.ts
provideHttpClient(withInterceptors([tbxNgxHttpErrorInterceptor]))

Function

logClientError

Log a manually caught error through the pluggable logging pipeline

Builds a TbxNgxErrorContextModel from the caught value and delegates to the provided TbxNgxErrorLoggerService, avoiding duplicated context-construction logic across services and components that catch their own errors.

When to use

Call from any service or component catch block to route manually caught errors through the same logging pipeline used by the interceptor and global handler.

Example

try {
  await riskyOperation();
} catch (error) {
  logClientError('riskyOperation failed', error, this.logger);
}

Accessibility

  • This package provides services, interceptors, and utilities only. It has no direct UI surface, no rendered DOM, and no keyboard, focus, color, or motion considerations. Surfacing errors to users visually (toast, banner, dialog) is the consuming application's responsibility — accessibility for those surfaces is owned by the chosen UI package.