ng-http-interceptor

Http Interceptor library for Angular

Previously was called ng2-http-interceptor

Version 4.x.x supports Angular 5 (ng-http-interceptor@^4.0.0)

Version 3.x.x supports Angular 4 (ng-http-interceptor@^3.0.0)

Version 2.x.x supports Angular 2 (ng-http-interceptor@^2.0.0)

Features

• Registering interceptors globally
• Separate interceptors for requests and responses
• Attach interceptors for specific urls via strings or RegExp's
• Remove specific/all interceptor(s)
• Modify requests (even url) from request interceptors
• Cancel requests from request interceptors
• Modify responses from response interceptors
• Interceptor Service is not coupled with Http Service
• Choose between overriding original Http Service or keep it and still use interceptors
• Comprehensive type assistance for your interceptor functions
• Supports AOT compilation with shipped *.metadata.json files
• UMD builds in dist/bundles folder ready to use in Browsers
• Simple http data extraction and manipulation with Helpers Functions
• Sharing context object between all interceptors

Table of Contents

• Features
• Prerequisites
• Installation
• Usage
• Documentation
• Development

Prerequisites

This library uses Proxy from ES6 spec so if you need to support browsers that are ES5 compatible include proxy-polyfill.

Library uses tslib (standard Typescript runtime library) so please make sure you have this module installed via npm.

Installation

To install this library, run:

$ npm install ng-http-interceptor --save

Usage

Case #1

Import HttpInterceptorModule to your application module. This will override original Http Service and all requests will be intercepted.

Case #2

Import as HttpInterceptorModule.noOverrideHttp() to keep original Http Service and use InterceptableHttp for requests to be intercepted.

Example use-case

You can use InterceptableHttp for your requests in case #1 and #2 and Http if you chose to override it (case #1 only):

constructor(http: Http, httpInterceptor: HttpInterceptorService) {
    httpInterceptor.request().addInterceptor((data, method) => {
      console.log(method, data);
      return data;
    });

    httpInterceptor.response().addInterceptor((res, method) => {
      return res.do(r => console.log(method, r));
    });

    this.http.get('/')
          .map(r => r.text())
          .subscribe(console.log);
}

In this setup every request and response will be logged to the console. You can also cancel request by returning false value (that coerce to boolean false) from one of registered request interceptors. You can return Observable from request interceptors to do some async job.

You can find in-depth explanation of internal concepts here: https://goo.gl/GU9VWo Also if you want to play with it check this repo. Or check this plnkr demo.

Documentation

All and every interception setup is made by HttpInterceptorService service. Inject this service in place where you want to manage interceptors.

Public API

HttpInterceptorService

HttpInterceptorService: {
    request(url?: string|RegExp): Interceptable,
    response(url?: string|RegExp): Interceptable
}

See src/http/http-interceptor.ts for full reference

Description: Methods will determine when to call interceptor - before request (request()) or after response (response()). You can also specify url filtering (string|RegExp) which will indicate when interceptor must be triggered depending on url. By default all interceptors fall under '/' url key which means every interceptor registered that way will be triggered despite of actual url.

Interceptable

Interceptable: {
    addInterceptor(interceptorFn: Interceptor): Interceptable,
    removeInterceptor(interceptorFn: Interceptor): Interceptable,
    clearInterceptors(interceptorFns?: Interceptor[]): Interceptable
}

See src/http/interceptable.ts for full reference

Description: This object will help you manage interceptors with respect to your selected configuration (url filtering).

Interceptor

Interceptor<T, D> {
  (data: T, method: string, ctx?: any): D;
}

See src/http/interceptable.ts for full reference

Description: This is generic type of interceptor - which is a plain old JavaScript function. You will be dealing with specific one to satisfy it's criteria:

• Interceptor<any[], any[]> - for request interceptors Function will get an array of parameters with which call on Http was made + method name as string (get, post, delete...) and should return array of the same structure or false to cancel request.
• Interceptor<Observable<Response>, Observable<Response>> - for response interceptors Function will get Observable + method name as string (get, post, delete...) and should return same or new Observable but with type Response (this is made specifically to prevent other code being broken because response was intercepted and structure changed)

Helpers Functions (since v1.3.0)

There are a bunch of helper functions added to simplify some common work with data array (for ex. getting RequestOptions or even Headers).

getHttpHeadersOrInit()

function getHttpHeadersOrInit(data: any[], method: string): Headers;

See src/http/helpers/getHttpHeadersOrInit.ts for full reference

Description: Gets Headers from data array. If no RequestOptions found - creates it and updates original data array. If no Headers found - creates it and sets to RequestOptions.

Exmaple how to add custom headers to requests:

httpInterceptor.request().addInterceptor((data, method) => {
  const headers = getHttpHeadersOrInit(data, method);
  headers.set('X-Custom-Header', 'value');
  return data;
});

getHttpOptionsAndIdx()

function getHttpOptionsAndIdx(
    data: any[],
    method: string,
    alwaysOriginal?: boolean
): {
    options: RequestOptions;
    idx: number;
};

See src/http/helpers/getHttpOptionsAndIdx.ts for full reference

Description: Gets RequestOptions and it's index location in data array. If no options found and alwaysOriginal = false - creates new RequestOptions but does NOT set it back on data array.

• Param alwaysOriginal is false by default.

getHttpOptions()

function getHttpOptions(
    data: any[],
    method: string,
    alwaysOriginal?: boolean): RequestOptions;

See src/http/helpers/getHttpOptions.ts for full reference

Description: Gets http RequestOptions from data array. If no options found and alwaysOriginal = false - returns new RequestOptions but does NOT set it back on data array.

• Param alwaysOriginal is false by default.

getHttpOptionsIdx()

function getHttpOptionsIdx(method: string): number;

See src/http/helpers/getHttpOptionsIdx.ts for full reference

Description: Gets index of RequestOptions in http data array for specified method.

Development

To generate all *.js, *.js.map, *.d.ts and *.metadata.json files:

$ npm run build

To lint all *.ts files:

$ npm run lint

To run unit tests:

$ npm test

License

MIT © Alex Malkevich