@voyagerpoland/proxy

@voyagerpoland/proxy

HTTP service proxy with Result Pattern integration for Angular. Wraps Angular HttpClient calls into ResultAsync<T> with built-in retry and circuit breaker support.

Installation

npm install @voyagerpoland/proxy

Peer dependencies

npm install @voyagerpoland/results neverthrow rxjs @angular/common

API Reference

fromHttp<T>(observable, errorMapper?)

Converts an Angular HTTP Observable<T> into a ResultAsync<T>.

import { fromHttp } from '@voyagerpoland/proxy';

const result = await fromHttp(httpClient.get<User>('/api/users/1'));
// Result<User> — Ok({ id: 1, name: 'Alice' }) or Err(AppError)

fromHttpError(error)

Converts an HttpErrorResponse (or compatible object) to an AppError with HTTP context.

import { fromHttpError } from '@voyagerpoland/proxy';

const appError = fromHttpError(httpErrorResponse);
// appError.type === ErrorType.NotFound (for 404)
// appError.context.get('url') === '/api/users/42'
// appError.context.get('statusText') === 'Not Found'

ServiceProxy (abstract class)

Abstract base class for Angular HTTP service proxies with built-in resilience. Retry and circuit breaker are enabled by default — no configuration needed.

import { Injectable, inject } from '@angular/core';
import { HttpClient } from '@angular/common/http';
import { ServiceProxy } from '@voyagerpoland/proxy';
import type { ResultAsync } from '@voyagerpoland/results';
import { API_BASE_URL } from '../api-config';

// DTO: automatically generated from OpenAPI
import type { Order, CreateOrderRequest, OrderListResponse } from '../generated/models';

@Injectable({ providedIn: 'root' })
class OrderService extends ServiceProxy {
  constructor() {
    super(inject(HttpClient), inject(API_BASE_URL));
  }

  getOrder(id: number): ResultAsync<Order> {
    return this.get<Order>(`/orders/${id}`);
  }

  listOrders(status?: string, limit?: number): ResultAsync<OrderListResponse> {
    return this.get<OrderListResponse>('/orders', {
      status,
      limit: limit?.toString(),
    });
  }

  createOrder(request: CreateOrderRequest): ResultAsync<Order> {
    return this.post<Order>('/orders', request);
  }

  deleteOrder(id: number): ResultAsync {
    return this.del(`/orders/${id}`);
  }
}

3 lines per endpoint. DTO automatic from OpenAPI. Retry + circuit breaker for free.

Using in Angular components

@Component({
  /* ... */
})
class UserComponent {
  private readonly orders = inject(OrderService);

  loadOrder(id: number): void {
    this.orders.getOrder(id).match(
      (order) => this.order.set(order),
      (error) => this.error.set(error.message),
    );
  }
}

ServiceProxyOptions

All fields are optional — when omitted, sensible defaults are used:

interface ServiceProxyOptions {
  maxRetryAttempts?: number; // default: 3
  retryBaseDelayMs?: number; // default: 1000
  circuitBreakerThreshold?: number; // default: 5
  circuitBreakerTimeoutMs?: number; // default: 30000
  authHandler?: AuthHandler; // default: undefined (no auth handling)
}

Custom configuration example:

super(inject(HttpClient), inject(API_BASE_URL), {
  maxRetryAttempts: 5,
  retryBaseDelayMs: 500,
  circuitBreakerThreshold: 10,
  circuitBreakerTimeoutMs: 60_000,
});

AuthHandler

Optional strategy for reacting to HTTP 401 (Unauthorized) errors. When configured, ServiceProxy calls onUnauthorized() before returning an error, giving the handler a chance to refresh credentials and retry the request.

interface AuthHandler {
  onUnauthorized(): Promise<{ retry: boolean }>;
}

Flow:

Request → 401
  → authHandler defined?
    → NO: Err(Unauthorized) immediately (default behavior)
    → YES: await authHandler.onUnauthorized()
      → { retry: true }  → retry request once (with refreshed credentials)
        → success → Ok(T)
        → 401 again → Err(Unauthorized) — prevents infinite loop
      → { retry: false } → Err(Unauthorized)

Key design decisions:

• Max 1 retry after auth refresh — prevents infinite loops
• Only 401, not 403 — Permission errors are not token problems
• Handler owns coordination — single-refresh guard is the handler's responsibility
• Framework-agnostic — works with BFF, token refresh, or any auth strategy

Example: BFF (Duende IdentityServer)

class BffAuthHandler implements AuthHandler {
  constructor(private window: Window) {}

  async onUnauthorized(): Promise<{ retry: boolean }> {
    const returnUrl = this.window.location.pathname;
    this.window.location.href = `/bff/login?returnUrl=${encodeURIComponent(returnUrl)}`;
    // Redirect leaves the SPA — never resolves
    return { retry: false };
  }
}

@Injectable({ providedIn: 'root' })
class OrderService extends ServiceProxy {
  constructor() {
    super(inject(HttpClient), inject(API_BASE_URL), {
      authHandler: new BffAuthHandler(window),
    });
  }
}

Example: Token refresh (legacy)

class TokenAuthHandler implements AuthHandler {
  private refreshInProgress: Promise<{ retry: boolean }> | null = null;

  constructor(
    private authService: AuthService,
    private router: Router,
  ) {}

  async onUnauthorized(): Promise<{ retry: boolean }> {
    // Single-refresh guard — concurrent 401s share one refresh
    if (this.refreshInProgress) {
      return this.refreshInProgress;
    }

    this.refreshInProgress = this.doRefresh();
    try {
      return await this.refreshInProgress;
    } finally {
      this.refreshInProgress = null;
    }
  }

  private async doRefresh(): Promise<{ retry: boolean }> {
    try {
      await this.authService.refreshToken();
      return { retry: true };
    } catch {
      this.router.navigate(['/login'], {
        queryParams: { returnUrl: this.router.url },
      });
      return { retry: false };
    }
  }
}

After a successful refresh, ServiceProxy retries the original HttpClient call. Angular interceptors run again on the new request, automatically attaching the refreshed Bearer token.

ProxyDiagnostics

Optional callback-based telemetry hooks. When configured, ServiceProxy emits events for request lifecycle, retry attempts, and circuit breaker state changes. Vendor-neutral — wire to Application Insights, OpenTelemetry, or any provider.

interface ProxyDiagnostics {
  onRequestStart?: (event: RequestStartEvent) => void;
  onRequestComplete?: (event: RequestCompleteEvent) => void;
  onRequestFail?: (event: RequestFailEvent) => void;
  onRetryAttempt?: (event: RetryAttemptEvent) => void;
  onCircuitBreakerStateChanged?: (event: CircuitBreakerStateChangedEvent) => void;
}

Configuration:

super(inject(HttpClient), inject(API_BASE_URL), {
  diagnostics: {
    onRequestStart: (e) => console.log(`${e.method} ${e.url}`),
    onRequestComplete: (e) =>
      console.log(`${e.method} ${e.url} ${e.durationMs}ms (${e.retryAttempts} retries)`),
    onRequestFail: (e) => console.error(`${e.method} ${e.url} failed: ${e.error.type}`),
    onRetryAttempt: (e) => console.warn(`Retry #${e.attempt} for ${e.url}, delay ${e.delayMs}ms`),
    onCircuitBreakerStateChanged: (e) => console.warn(`Circuit: ${e.oldState} → ${e.newState}`),
  },
});

Event types

Event	Fields	When
RequestStartEvent	method, url, startedAt	Before first HTTP attempt
RequestCompleteEvent	method, url, durationMs, retryAttempts	After successful response (including retries)
RequestFailEvent	method, url, durationMs, retryAttempts, error	After all retries exhausted
RetryAttemptEvent	method, url, attempt, delayMs, error	On each retry attempt
CircuitBreakerStateChangedEvent	oldState, newState, failureCount, lastError	When circuit breaker transitions

Example: Application Insights adapter

import { ApplicationInsights } from '@microsoft/applicationinsights-web';
import type { ProxyDiagnostics } from '@voyagerpoland/proxy';

export function createAppInsightsDiagnostics(appInsights: ApplicationInsights): ProxyDiagnostics {
  return {
    onRequestComplete: (event) => {
      appInsights.trackDependencyData({
        id: crypto.randomUUID(),
        name: `${event.method} ${event.url}`,
        duration: event.durationMs,
        success: true,
        responseCode: 200,
        properties: { retryAttempts: String(event.retryAttempts) },
      });
    },
    onRequestFail: (event) => {
      appInsights.trackDependencyData({
        id: crypto.randomUUID(),
        name: `${event.method} ${event.url}`,
        duration: event.durationMs,
        success: false,
        responseCode: Number(event.error.code.replace('HTTP_', '')) || 0,
        properties: {
          retryAttempts: String(event.retryAttempts),
          errorType: event.error.type,
        },
      });
    },
    onRetryAttempt: (event) => {
      appInsights.trackEvent({
        name: 'ServiceProxy.RetryAttempt',
        properties: {
          url: event.url,
          attempt: String(event.attempt),
          errorType: event.error.type,
        },
      });
    },
    onCircuitBreakerStateChanged: (event) => {
      appInsights.trackEvent({
        name: 'ServiceProxy.CircuitBreakerStateChanged',
        properties: {
          oldState: event.oldState,
          newState: event.newState,
          failureCount: String(event.failureCount),
        },
      });
    },
  };
}

composeDiagnostics(...providers)

Combines multiple ProxyDiagnostics providers into one. Each event is forwarded to all providers that define the corresponding callback.

import { composeDiagnostics } from '@voyagerpoland/proxy';
import type { ProxyDiagnostics } from '@voyagerpoland/proxy';

// Provider 1: console logging (dev)
function consoleDiagnostics(): ProxyDiagnostics {
  return {
    onRequestStart: (e) => console.log(`→ ${e.method} ${e.url}`),
    onRequestComplete: (e) => console.log(`✓ ${e.method} ${e.url} ${e.durationMs}ms`),
    onRequestFail: (e) => console.error(`✗ ${e.method} ${e.url} failed: ${e.error.type}`),
    onRetryAttempt: (e) => console.warn(`↻ Retry #${e.attempt} for ${e.url}`),
  };
}

// Provider 2: Application Insights (prod) — see adapter example above

// Compose both
const diagnostics = composeDiagnostics(
  consoleDiagnostics(),
  createAppInsightsDiagnostics(appInsights),
);

super(inject(HttpClient), inject(API_BASE_URL), { diagnostics });

Providers that don't define a callback for a given event are simply skipped. You can compose any number of providers.

Integration Guide: OpenAPI DTO Generation + ServiceProxy

@voyagerpoland/proxy provides the ServiceProxy base class. The consumer project is responsible for generating TypeScript DTOs from the backend's OpenAPI spec. Together they give 3 lines per endpoint with full type safety.

Architecture overview

┌─────────────────────────────────────────────────┐
│  Backend .NET                                    │
│  ASP.NET Core → swagger.json (automatically)     │
└──────────────────────┬──────────────────────────-┘
                       │
                       ▼
┌──────────────────────────────────────────────────┐
│  ng-openapi-gen (build-time)                     │
│  swagger.json → TypeScript DTO (models only)     │
│                                                  │
│  Generated:                                      │
│  - models/order.ts          (interface Order)    │
│  - models/create-order-request.ts                │
│  - models/order-list-response.ts                 │
└──────────────────────┬───────────────────────────┘
                       │
                       ▼
┌──────────────────────────────────────────────────┐
│  Service facade (hand-written, ~3 lines/endpoint)│
│                                                  │
│  class OrderService extends ServiceProxy {       │
│    getOrder(id) = this.get<Order>(`/orders/${id}`)│
│  }                                               │
└──────────────────────────────────────────────────┘

Step 1: Install ng-openapi-gen

npm install -D ng-openapi-gen

Step 2: Get the OpenAPI spec

Download swagger.json from the backend (or point to a URL):

curl -o swagger.json https://api.example.com/swagger/v1/swagger.json

Step 3: Configure ng-openapi-gen

Create ng-openapi-gen.json in the project root:

{
  "$schema": "node_modules/ng-openapi-gen/ng-openapi-gen-schema.json",
  "input": "swagger.json",
  "output": "src/app/api/generated",
  "ignoreUnusedModels": false,
  "services": false
}

"services": false — generate only models, not services. Service facades are hand-written with ServiceProxy.

Step 4: Add npm scripts

{
  "scripts": {
    "api:generate": "ng-openapi-gen --config ng-openapi-gen.json",
    "api:update": "curl -o swagger.json https://api.example.com/swagger/v1/swagger.json && npm run api:generate",
    "prebuild": "npm run api:generate"
  }
}

Step 5: Run the generator

npm run api:generate

This produces files under src/app/api/generated/models/:

src/app/api/generated/
  models/
    order.ts                    ← interface Order { id: number; ... }
    create-order-request.ts     ← interface CreateOrderRequest { ... }
    order-list-response.ts      ← interface OrderListResponse { ... }

Step 6: Provide API_BASE_URL token

// src/app/api/api-config.ts
import { InjectionToken } from '@angular/core';

export const API_BASE_URL = new InjectionToken<string>('API_BASE_URL');

// app.config.ts
import { API_BASE_URL } from './api/api-config';

export const appConfig: ApplicationConfig = {
  providers: [provideHttpClient(), { provide: API_BASE_URL, useValue: 'https://api.example.com' }],
};

Step 7: Write the service facade

// src/app/api/order.service.ts
import { Injectable, inject } from '@angular/core';
import { HttpClient } from '@angular/common/http';
import type { ResultAsync } from '@voyagerpoland/results';
import { ServiceProxy } from '@voyagerpoland/proxy';
import { API_BASE_URL } from './api-config';

// Types generated from OpenAPI (Step 5)
import type { Order, CreateOrderRequest, OrderListResponse } from './generated/models';

@Injectable({ providedIn: 'root' })
export class OrderService extends ServiceProxy {
  constructor() {
    super(inject(HttpClient), inject(API_BASE_URL));
  }

  getOrder(id: number): ResultAsync<Order> {
    return this.get<Order>(`/orders/${id}`);
  }

  listOrders(status?: string, limit?: number): ResultAsync<OrderListResponse> {
    return this.get<OrderListResponse>('/orders', {
      status,
      limit: limit?.toString(),
    });
  }

  createOrder(request: CreateOrderRequest): ResultAsync<Order> {
    return this.post<Order>('/orders', request);
  }

  deleteOrder(id: number): ResultAsync {
    return this.del(`/orders/${id}`);
  }
}

Step 8: Use in components

@Component({
  /* ... */
})
export class OrderListComponent {
  private readonly orderService = inject(OrderService);

  orders = signal<Order[]>([]);
  error = signal<string | null>(null);

  loadOrders(): void {
    this.orderService.listOrders('active', 50).match(
      (response) => this.orders.set(response.items),
      (error) => this.error.set(error.message),
    );
  }
}

Target project structure

src/app/api/
  generated/              ← ng-openapi-gen output (git-ignored or committed)
    models/
      order.ts
      create-order-request.ts
      order-list-response.ts
      ...
  api-config.ts           ← API_BASE_URL injection token
  order.service.ts        ← extends ServiceProxy + generated DTO
  payment.service.ts
  user.service.ts

Cost per new endpoint

Step	Time	Who
Add endpoint in C#	5 min	Backend developer
swagger.json regenerates automatically	0 min	CI/CD
npm run api:generate regenerates DTO	0 min	npm script
Add 1 method in service facade (3 lines)	1 min	Frontend developer
Total	~6 min

Alternative generators

If ng-openapi-gen doesn't fit your needs:

Generator	Angular HttpClient	DTO	Requires	Notes
ng-openapi-gen	Yes	Yes	Node.js	Recommended, lightweight
openapi-generator	Yes	Yes	JVM	More mature, heavier
NSwag	Yes	Yes	.NET SDK	Best .NET integration

All generators work the same way: generate only models ("services": false), write service facades with ServiceProxy.

HTTP Status Code Mapping

Status	ErrorType	Classification
0	Unavailable	Transient
400	Validation	Business
401	Unauthorized	Business*
403	Permission	Business
404	NotFound	Business
409	Conflict	Business
422	Business	Business
429	TooManyRequests	Transient
503	Unavailable	Transient
504	Timeout	Transient
Other	Unexpected	Infrastructure

* When authHandler is configured, 401 triggers onUnauthorized() before returning Err. See AuthHandler.

License

MIT