ng2-http-interceptor

ng2-http-interceptor

Http Interceptor library for Angular 2

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

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.

If you are getting error like: ReferenceError: __extends is not defined
Please make sure that you are importing ts-helpers module in your application.

Installation

To install this library, run:

$ npm install ng2-http-interceptor --save

Usage

New Way (since v1.x.x)

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.

Legacy Way

To use it you must first declare providers in your @NgModule.
You have 2 options:

1. Register InterceptableHttp AND override original Http service so that all your requests will be intercepted
2. Register ONLY InterceptableHttp and keep original Http service so you can make requests which are intercepted and not.

For case #1 use:

{
    providers: [...HTTP_INTERCEPTOR_PROVIDER]
}

For case #2 use:

{
    providers: [...HTTP_INTERCEPTOR_NO_OVERRIDE_PROVIDER]
}

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) => {
      res.subscribe(r => console.log(method, r));
      return res;
    });
    
    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

export interface Interceptor {
  (data: any, method: string): any;
}

_{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()

export 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.

getHttpOptionsAndIdx()

export 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()

export 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()

export 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