kirill255 / nestjs-got

A simple (got) http nestjs module which exposes npm got package's API to the Nestjs framework.

Nestjs Got

This is a simple nestjs module that exposes the got http package by exporting the GotService after module registration while leveraging the Reactive Programming Pattern provided by rxjs.

Table of content (click to expand)

• Installation
• Usage
• Configuration
• API Methods
  • HTTP
  • Pagination
  • Stream
• Contributing

Installation

Installation is pretty simple and straightforward as all you have to do is run the following commands depending on your package manager:

• npm

npm install --save @t00nday/nestjs-got got@^11.0.0

• yarn

yarn add @t00nday/nestjs-got got@^11.0.0

Usage

Using this module is quite simple, you just have to register it as a dependency using any of the methods below:

This could be done synchronously using the register() method:

./app.module.ts

import { Module } from '@nestjs/common';
import { GotModule } from '@t00nday/nestjs-got';

@Module({
    imports: [
        // ... other modules
        GotModule.register({
            prefixUrl: 'http://example.org',
            // ...
        }), // Accepts a GotModuleOptions object as a parameter
    ],
})
export class AppModule {}

The module could also be registered asynchronously using any of the approaches provided by the registerAsync() method:

Examples below:

• Using options factory provider approach

./app.module.ts

// prettier-ignore
import { 
    GotModule, 
    GotModuleOptions 
} from '@t00nday/nestjs-got';
import { Module } from '@nestjs/common';

@Module({
    imports: [
        // ... other modules
        GotModule.registerAsync({
            useFactory: (): GotModuleOptions => ({
                prefixUrl: 'https://example.org',
                // ...
            }),
        }),
    ],
})
export class AppModule {}

• Using class or existing provider approach:

./got-config.service.ts

import { Injectable } from '@nestjs/common';
import { GotModuleOptions, GotOptionsFactory } from '@t00nday/nestjs-got';

@Injectable()
export class GotConfigService implements GotModuleOptionsFactory {
    createGotOptions(): GotModuleOptions {
        return {
            prefixUrl: 'https://example.org',
            // ...
        };
    }
}

The GotConfigService SHOULD implement the GotModuleOptionsFactory, MUST declare the createGotOptions() method and MUST return GotModuleOptions object.

./app.module.ts

// prettier-ignore
import { Module } from '@nestjs/common';
import { GotModule, GotModuleOptions } from '@t00nday/nestjs-got';

import { GotConfigService } from './got-config.service.ts';

@Module({
    imports: [
        // ... other modules
        GotModule.registerAsync({
            useClass: GotConfigService,
        }),
    ],
})
export class AppModule {}

Configuration

The GotModuleOptions is an alias for the got package's ExtendOptions hence accepts the same configuration object.

API Methods

HTTP

The module currently only exposes the basic JSON HTTP verbs, as well as the pagination methods through the GotService.

For all JSON HTTP verbs - get, head, post, put, patch and delete - which are also the exposed methods, below is the the method signature where method: string MUST be any of their corresponding verbs.

// This is just used to explain the methods as this code doesn't exist in the package
import { Observable } from 'rxjs';
import { Response, OptionsOfJSONResponseBody } from 'got';

interface GotInterface {
    // prettier-ignore
    [method: string]: ( // i.e. 'get', 'head', 'post', 'put' or 'delete' method
        url: string | URL,
        options?: OptionsOfJSONResponseBody,
    ) => Observable<Response<T>>;;
}

Pagination

For all pagination methods - each and all, below is the method signature each of them.

// This is just used to explain the methods as this code doesn't exist in the package
import { Observable } from 'rxjs';
import { Response, OptionsOfJSONResponseBody } from 'got';

interface PaginateInterface {
    [method: string]: <T = any, R = unknown>( // i.e 'all' or 'each' method
        url: string | URL,
        options?: OptionsWithPagination<T, R>,
    ) => Observable<T | T[]>;
}

Usage examples:

@Controller()
export class ExampleController {
    constructor(private readonly gotService: GotService) {}

    controllerMethod() {
        // ...
        this.gotService.pagination.all<T>(someUrl, withOptions); // Returns Observable<T[]>
        // or
        this.gotService.pagination.each<T>(someUrl, withOptions); // Returns Observable<T>
        // ...
    }
}

For more information of the usage pattern, please check here

Stream

The stream feature is divided into two parts. This is because (and as stated in the documentation here), while the stream request is actually a stream.Duplex the GET and HEAD requests return a stream.Readable and the POST, PUT, PATCH and DELETE requests return a stream.Writable.

This prompted an implementation that attempts to cover both scenarios. The difference is only present in the arguments acceptable by the respective methods.

Further, all methods of the stream property return a stream request to which we can chain an on<T>(eventType) method which in turn returns a fromEvent observable. This affords us the ability to subscribe to events we wish to listen for from the request.

Possible eventTypes include (and quite constrained to those provided by the got package):

• end

• data

• error

• request

• readable

• response

• redirect

• uploadProgress

• downloadProgress

For GET and HEAD stream requests, below is the method signature:

// This is just used to explain the methods as this code doesn't exist in the package
import { Observable } from 'rxjs';
import { StreamOptions } from 'got';
import { StreamRequest } from '@toonday/nestjs-got/dist/stream.request';

interface StreamInterface {
    [method: string]: <T = unknown>(
        url: string | URL,
        options?: StreamOptions,
    ): StreamRequest;
}

while that of the POST, PUT, PATCH and DELETE is:

// This is just used to explain the methods as this code doesn't exist in the package
import { Observable } from 'rxjs';
import { StreamOptions } from 'got';
import { StreamRequest } from '@toonday/nestjs-got/dist/stream.request';

interface StreamInterface {
    [method: string]: <T = unknown>(
        url: string | URL,
        filePathOrStream?: string | Readable, // This is relative to 'process.cwd()'
        options?: StreamOptions,
    ): StreamRequest<T>;
}

Usage examples:

@Controller()
export class ExampleController {
    constructor(private readonly gotService: GotService) {}

    controllerMethod() {
        // ...
        this
            .gotService
            .stream
            .get(someUrl, streamOptions)
            .on<T>(eventType)
            .subscribe(subscribeFunction: Function); // Returns Observable<T>
        // or
        this
            .gotService
            .stream
            .head(someUrl, streamOptions)
            .on<T>(eventType)
            .subscribe(subscribeFunction: Function); // Returns Observable<T>
        // or
        this
            .gotService
            .stream
            .post(someUrl, filePathOrStream, streamOptions)
            .on<T>(eventType)
            .subscribe(subscribeFunction: Function); // Returns Observable<T>
        // or
        this
            .gotService
            .stream
            .put(someUrl, filePathOrStream, streamOptions)
            .on<T>(eventType)
            .subscribe(subscribeFunction: Function); // Returns Observable<T>
        // or
        this
            .gotService
            .stream
            .patch(someUrl, filePathOrStream, streamOptions)
            .on<T>(eventType)
            .subscribe(subscribeFunction: Function); // Returns Observable<T>
        // or
        this
            .gotService
            .stream
            .delete(someUrl, filePathOrStream, streamOptions)
            .on<T>(eventType)
            .subscribe(subscribeFunction: Function); // Returns Observable<T>
        // ...
    }
}

Contributing

Contributions are welcome. However, please read the contribution's guide.