@denis_bruns/http-client-middleware NPM

Below is a suggested README for @denis_bruns/http-client-middleware:

@denis_bruns/http-client-middleware

A modular middleware library for HTTP client requests.
This package provides middleware to inject secrets from AWS Secrets Manager and environment variables into HTTP request options, and a factory to chain multiple middleware Observables together.

Overview

@denis_bruns/http-client-middleware supplies three key pieces of functionality:

AWS Secrets Manager Middleware
Retrieves secrets from AWS Secrets Manager (with caching) and injects them into HTTP request headers.
Environment Variable Middleware
Reads specified environment variables, caches their values for a configurable TTL, and injects them into HTTP request headers.
HTTP Client Middleware Factory
Composes multiple middleware Observables sequentially, merging their resulting configuration objects—allowing you to layer modifications to your HTTP client request options.

These middleware utilities are designed to work with a common HTTP client interface and help keep your application configuration declarative and testable.

Key Features

AWS Secrets Middleware:
- Uses @aws-sdk/client-secrets-manager to fetch secrets.
- Caches secrets for 1 hour to reduce AWS calls.
- Applies header mappings from secret keys to request headers.
- Throws a custom AWSSecretsManagerError if the secret string is absent.
Environment Middleware:
- Reads environment variables using a provided mapping.
- Caches variable values for 5 minutes.
- Emits an EnvironmentError if a required variable is missing.
- Synchronously sets headers using a custom Observable to catch errors.
Middleware Factory:
- Sequentially chains multiple middleware Observables.
- Merges headers and other configuration options step-by-step.
- Enables a functional, modular approach to composing HTTP request configurations.

Installation

You can install the package using npm or yarn:

npm install @denis_bruns/http-client-middleware

Or with yarn:

yarn add @denis_bruns/http-client-middleware

Make sure you have the following peer dependencies installed:

TypeScript 5.x
rxjs
@aws-sdk/client-secrets-manager
@denis_bruns/web-core-ts

Basic Usage

1. AWS Secrets Manager Middleware

This middleware fetches secrets from AWS Secrets Manager and appends header values.

import { createAwsSecretsMiddleware, AWSSecretsManagerError } from '@denis_bruns/http-client-middleware';
import { HttpClientRequestOptions, ISecretManagerConfig } from '@denis_bruns/web-core-ts';
import { firstValueFrom } from 'rxjs';

const secretManagerConfig: ISecretManagerConfig = {
  region: 'us-east-1',
  secretName: 'my-secret',
  headerMappings: {
    'X-API-Key': 'API_KEY',
    'Authorization': 'AUTH_TOKEN',
  }
};

const requestOptions: HttpClientRequestOptions = {
  headers: { 'Content-Type': 'application/json' },
};

createAwsSecretsMiddleware(secretManagerConfig, requestOptions)
  .subscribe({
    next: (options) => {
      console.log('Updated request options:', options.headers);
    },
    error: (err: AWSSecretsManagerError) => {
      console.error('Failed to fetch secrets:', err.message);
    }
  });

2. Environment Variable Middleware

This middleware reads environment variables, applies caching, and sets headers accordingly.

import { createEnvironmentMiddleware, EnvironmentError } from '@denis_bruns/http-client-middleware';
import { HttpClientRequestOptions, EnvironmentVariable } from '@denis_bruns/web-core-ts';
import { firstValueFrom } from 'rxjs';

const headerMappings = {
  'X-API-Key': 'API_KEY' as EnvironmentVariable,
};

const requestOptions: HttpClientRequestOptions = {
  headers: { 'Content-Type': 'application/json' },
};

firstValueFrom(createEnvironmentMiddleware(headerMappings, requestOptions))
  .then((options) => {
    console.log('Environment headers:', options.headers);
  })
  .catch((err: EnvironmentError) => {
    console.error('Environment variable missing:', err.message);
  });

3. HTTP Client Middleware Factory

The factory composes multiple middleware in order. Each middleware builds on the configuration produced by the previous one.

import { createHttpClientMiddlewareFactory } from '@denis_bruns/http-client-middleware';
import { HttpClientRequestOptions } from '@denis_bruns/web-core-ts';
import { of, firstValueFrom } from 'rxjs';
import { map } from 'rxjs/operators';

const initialConfig: HttpClientRequestOptions = { headers: { 'Content-Type': 'application/json' } };

const middleware1$ = of(initialConfig).pipe(
  map((config) => ({
    ...config,
    headers: { ...config.headers, 'X-Test-1': 'value1' }
  }))
);

const middleware2$ = of(initialConfig).pipe(
  map((config) => ({
    ...config,
    headers: { ...config.headers, 'X-Test-2': 'value2' }
  }))
);

createHttpClientMiddlewareFactory([middleware1$, middleware2$], initialConfig)
  .subscribe((finalConfig) => {
    console.log('Final merged request options:', finalConfig.headers);
  });

// Expected output includes headers from both middlewares:
// { 'Content-Type': 'application/json', 'X-Test-1': 'value1', 'X-Test-2': 'value2' }

Related Packages

@denis_bruns/web-core-ts

Provides core types and interfaces used for clean architecture and HTTP client configuration.
@denis_bruns/http-client-angular
- Angular HTTP Client conforming axios interfaces with middleware support
@denis_bruns/http-client-axios
- HTTP Client built on axios with middleware support