TeqBench Angular HTTPAngular HTTP

Resilient base HTTP service for Angular with automatic retry on transient failures, configurable timeouts, and typed request options — one abstract class that feature services extend to gain consistent resilience without per-call boilerplate.

Overview

API

Package

Resources

npm install @teqbench/tbx-ngx-http

@teqbench/tbx-ngx-http provides an abstract base HTTP service for Angular feature services. Rather than re-implementing retry, timeout, URL resolution, and default-header logic in every service that talks to the backend, feature services extend TbxNgxHttpService and inherit a consistent resilience envelope over HttpClient.

The service exposes typed get, post, put, patch, and delete methods backed by two dedicated option interfaces — TbxNgxHttpRequestOptions for non-body methods (params + headers) and TbxNgxHttpBodyRequestOptions for body methods (headers only). GET goes through the retry operator by default; mutating methods (POST, PUT, PATCH, DELETE) skip retry by default because they are not safely repeatable. Either default can be overridden per call with options.retry. Timeouts apply to every method uniformly.

The retry strategy uses exponential backoff (RETRY_DELAY * 2^(attempt - 1)) and consults a fixed set of retryable statuses — 0 (network error), 408, 429, 500, 502, 503, 504. Non-retryable HTTP errors (4xx client errors other than 408/429) are re-thrown immediately. Non-HttpErrorResponse failures, including TimeoutError from the upstream operator, are always retried whenever the retry pipeline runs (GET by default, mutating methods on opt-in). All four resilience parameters (timeout, retry count, retry delay, retryable statuses) are also exported as standalone constants for consumers building custom retry pipelines outside of TbxNgxHttpService.

The package supports Angular 19, 20, and 21, carries no @teqbench runtime dependencies, and depends only on http-status-codes at runtime for the canonical status-code enum.

When to use

Reach for this package when your Angular application needs:

Consistent HTTP resilience (retry + timeout) across multiple feature services without duplicating the RxJS operators in every call.
A typed, ergonomic surface over HttpClient for GET/POST/PUT/PATCH/DELETE with request-option interfaces that match each method's body semantics.
A single place to tune retry count, backoff delay, and the set of retryable status codes.

Skip it when you're making one-off HTTP calls and don't need resilience beyond HttpClient defaults — direct use is simpler.

At a glance

Resilient base service — Abstract TbxNgxHttpService that feature services extend to inherit retry, timeout, URL resolution, and default headers.
GET retry with exponential backoff — Transient failures (network errors, 408, 429, 5xx) are retried with delay RETRY_DELAY * 2^(attempt - 1).
Configurable timeout — Every request is bounded by DEFAULT_TIMEOUT (10s default); subclasses override the class property to tune per service.
Idempotency-aware retry — GET retries by default. POST, PUT, PATCH, and DELETE skip retry by default. Per-call options.retry overrides either default for endpoints known to be idempotent.
Typed request options — TbxNgxHttpRequestOptions for params + headers (non-body methods); TbxNgxHttpBodyRequestOptions for body methods.
Per-subclass override — DEFAULT_TIMEOUT, RETRY_COUNT, and RETRY_DELAY are protected class properties — redeclare in a subclass to override.
Exposed resilience constants — TBX_NGX_HTTP_DEFAULT_TIMEOUT_MS, RETRY_COUNT, RETRY_DELAY_MS, and RETRYABLE_STATUSES are exported for custom pipelines.
Default headers — Accept application/json is set by default; callers providing options.headers replace the set entirely, or pass mergeHeaders true to merge with defaults.
URL resolution — Relative paths are joined to the subclass-provided baseUrl with consistent slash handling.
Broad Angular peer range — Supports Angular 19, 20, and 21; no @teqbench runtime dependencies.

Concepts

Base HTTP service: The abstract TbxNgxHttpService that consumers extend to gain timeout, retry, URL resolution, and default-header behavior over Angular HttpClient.
Feature service: A consumer-defined subclass of TbxNgxHttpService that provides a baseUrl and exposes typed methods for a specific backend surface.
Resilience constants: Exported default values for timeout, retry count, retry delay, and the set of retryable statuses; can be imported directly when building custom pipelines.
Retryable status: One of 0 (network error), 408, 429, 500, 502, 503, 504 — transient failures worth retrying with backoff.
Idempotency-aware retry: The rule that GET retries automatically while POST, PUT, PATCH, and DELETE skip retry by default. Either default can be overridden per call via options.retry for endpoints the caller knows to be idempotent.
Exponential backoff: A retry delay strategy where the wait doubles on each attempt — delay = RETRY_DELAY * 2^(attempt - 1).
Per-subclass override: The pattern of redeclaring a protected class property (DEFAULT_TIMEOUT, RETRY_COUNT, RETRY_DELAY) in a subclass to change resilience behavior for one feature service.

Services

`TbxNgxHttpService`

Abstract base class for feature services that interact with the API

Remarks

Centralizes path resolution, default headers, and resilience patterns (timeout, exponential-backoff retry on transient errors).

Feature services extend this class, provide the base URL, and call its typed methods. GET retries by default; POST, PUT, PATCH, and DELETE skip retry by default. Either default can be overridden per call with options.retry.

Subclasses can override resilience values by redeclaring the class property.

When to use

Extend this class in feature services to inherit automatic timeout, retry, URL resolution, and default header behavior. Provide baseUrl and call the protected HTTP methods (get, post, put, patch, delete).

Example 1

// UserService is a hypothetical consumer-defined subclass
@Injectable({ providedIn: 'root' })
export class UserService extends TbxNgxHttpService {
    protected override readonly baseUrl = environment.apiUrl;

    getUser(id: string) {
        return this.get<User>(`users/${id}`);
    }
}

Example 2

// SlowApiService is a hypothetical consumer-defined subclass
export class SlowApiService extends TbxNgxHttpService {
    protected override readonly baseUrl = environment.apiUrl;
    protected override readonly DEFAULT_TIMEOUT = 30_000;
}

Interfaces

`TbxNgxHttpBodyRequestOptions`

Options accepted by body HTTP methods (POST, PUT, PATCH)

Remarks

Passed as the optional third argument to post, put, and patch. When headers is provided, the service's default headers are replaced entirely by default; pass mergeHeaders: true to merge instead.

When to use

Pass an instance of this interface to customize headers on POST, PUT, and PATCH requests made through TbxNgxHttpService.

Example

import { HttpHeaders } from '@angular/common/http';
import { TbxNgxHttpBodyRequestOptions } from '@teqbench/tbx-ngx-http';

const options: TbxNgxHttpBodyRequestOptions = {
    headers: new HttpHeaders({ Authorization: 'Bearer token' }),
};

`TbxNgxHttpRequestOptions`

Options accepted by non-body HTTP methods (GET, DELETE)

Remarks

Passed as the optional second argument to get and delete. When headers is provided, the service's default headers are replaced entirely by default; pass mergeHeaders: true to merge instead.

When to use

Pass an instance of this interface to customize query parameters or headers on GET and DELETE requests made through TbxNgxHttpService.

Example

import { HttpParams } from '@angular/common/http';
import { TbxNgxHttpRequestOptions } from '@teqbench/tbx-ngx-http';

const options: TbxNgxHttpRequestOptions = {
    params: new HttpParams().set('page', '1'),
};

Constants

`TBX_NGX_HTTP_DEFAULT_TIMEOUT_MS`

Default request timeout in milliseconds

Remarks

Applied to every HTTP request made through TbxNgxHttpService. Subclasses override by redeclaring the DEFAULT_TIMEOUT class property.

When to use

Import directly when building a custom retry or timeout strategy outside of TbxNgxHttpService.

Example

import { TBX_NGX_HTTP_DEFAULT_TIMEOUT_MS } from '@teqbench/tbx-ngx-http';

`TBX_NGX_HTTP_RETRY_COUNT`

Number of retry attempts for the retry pipeline

Remarks

Controls how many times a failed request is retried before the error propagates to the caller. Used by GET (which retries by default) and by POST/PUT/PATCH/DELETE when the caller opts in via options.retry: true. Subclasses of TbxNgxHttpService override by redeclaring the RETRY_COUNT class property.

When to use

Import directly when building a custom retry strategy outside of TbxNgxHttpService.

Example

import { TBX_NGX_HTTP_RETRY_COUNT } from '@teqbench/tbx-ngx-http';

`TBX_NGX_HTTP_RETRY_DELAY_MS`

Base delay in milliseconds for exponential backoff between retries

Remarks

The actual delay follows the formula RETRY_DELAY * 2^(attempt - 1). Subclasses of TbxNgxHttpService override by redeclaring the RETRY_DELAY class property.

When to use

Import directly when building a custom backoff strategy outside of TbxNgxHttpService.

Example

import { TBX_NGX_HTTP_RETRY_DELAY_MS } from '@teqbench/tbx-ngx-http';

`TBX_NGX_HTTP_RETRYABLE_STATUSES`

HTTP status codes eligible for automatic retry

Remarks

Only transient server errors and network failures are retried. 4xx client errors (except 408 and 429) indicate a malformed request that will not succeed on retry.

Included status codes:

0 — Network error (no response received; browser reports status 0)
408 — Request Timeout
429 — Too Many Requests (rate-limited; retry after backoff)
500 — Internal Server Error
502 — Bad Gateway
503 — Service Unavailable
504 — Gateway Timeout

When to use

Import directly when implementing a custom retry predicate that needs to reference the same set of retryable statuses used by TbxNgxHttpService.

Example

import { TBX_NGX_HTTP_RETRYABLE_STATUSES } from '@teqbench/tbx-ngx-http';

if (TBX_NGX_HTTP_RETRYABLE_STATUSES.has(response.status)) {
    // retry logic
}

Accessibility

This package provides services, constants, and type interfaces only. It has no direct UI surface, no rendered DOM, and no keyboard, focus, color, or motion considerations. Accessibility for any UI that surfaces HTTP errors, loading states, or retry progress is owned by the consuming application.