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

1import { Module } from '@nestjs/common';
2import { GotModule } from '@t00nday/nestjs-got';
3
4@Module({
5    imports: [
6        // ... other modules
7        GotModule.register({
8            prefixUrl: 'http://example.org',
9            // ...
10        }), // Accepts a GotModuleOptions object as a parameter
11    ],
12})
13export 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

1// prettier-ignore
2import { 
3    GotModule, 
4    GotModuleOptions 
5} from '@t00nday/nestjs-got';
6import { Module } from '@nestjs/common';
7
8@Module({
9    imports: [
10        // ... other modules
11        GotModule.registerAsync({
12            useFactory: (): GotModuleOptions => ({
13                prefixUrl: 'https://example.org',
14                // ...
15            }),
16        }),
17    ],
18})
19export class AppModule {}

• Using class or existing provider approach:

./got-config.service.ts

1import { Injectable } from '@nestjs/common';
2import { GotModuleOptions, GotOptionsFactory } from '@t00nday/nestjs-got';
3
4@Injectable()
5export class GotConfigService implements GotModuleOptionsFactory {
6    createGotOptions(): GotModuleOptions {
7        return {
8            prefixUrl: 'https://example.org',
9            // ...
10        };
11    }
12}

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

./app.module.ts

1// prettier-ignore
2import { Module } from '@nestjs/common';
3import { GotModule, GotModuleOptions } from '@t00nday/nestjs-got';
4
5import { GotConfigService } from './got-config.service.ts';
6
7@Module({
8    imports: [
9        // ... other modules
10        GotModule.registerAsync({
11            useClass: GotConfigService,
12        }),
13    ],
14})
15export 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.

1// This is just used to explain the methods as this code doesn't exist in the package
2import { Observable } from 'rxjs';
3import { Response, OptionsOfJSONResponseBody } from 'got';
4
5interface GotInterface {
6    // prettier-ignore
7    [method: string]: ( // i.e. 'get', 'head', 'post', 'put' or 'delete' method
8        url: string | URL,
9        options?: OptionsOfJSONResponseBody,
10    ) => Observable<Response<T>>;;
11}

Pagination

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

1// This is just used to explain the methods as this code doesn't exist in the package
2import { Observable } from 'rxjs';
3import { Response, OptionsOfJSONResponseBody } from 'got';
4
5interface PaginateInterface {
6    [method: string]: <T = any, R = unknown>( // i.e 'all' or 'each' method
7        url: string | URL,
8        options?: OptionsWithPagination<T, R>,
9    ) => Observable<T | T[]>;
10}

Usage examples:

1@Controller()
2export class ExampleController {
3    constructor(private readonly gotService: GotService) {}
4
5    controllerMethod() {
6        // ...
7        this.gotService.pagination.all<T>(someUrl, withOptions); // Returns Observable<T[]>
8        // or
9        this.gotService.pagination.each<T>(someUrl, withOptions); // Returns Observable<T>
10        // ...
11    }
12}

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:

1// This is just used to explain the methods as this code doesn't exist in the package
2import { Observable } from 'rxjs';
3import { StreamOptions } from 'got';
4import { StreamRequest } from '@toonday/nestjs-got/dist/stream.request';
5
6interface StreamInterface {
7    [method: string]: <T = unknown>(
8        url: string | URL,
9        options?: StreamOptions,
10    ): StreamRequest;
11}

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

1// This is just used to explain the methods as this code doesn't exist in the package
2import { Observable } from 'rxjs';
3import { StreamOptions } from 'got';
4import { StreamRequest } from '@toonday/nestjs-got/dist/stream.request';
5
6interface StreamInterface {
7    [method: string]: <T = unknown>(
8        url: string | URL,
9        filePathOrStream?: string | Readable, // This is relative to 'process.cwd()'
10        options?: StreamOptions,
11    ): StreamRequest<T>;
12}

Usage examples:

1@Controller()
2export class ExampleController {
3    constructor(private readonly gotService: GotService) {}
4
5    controllerMethod() {
6        // ...
7        this
8            .gotService
9            .stream
10            .get(someUrl, streamOptions)
11            .on<T>(eventType)
12            .subscribe(subscribeFunction: Function); // Returns Observable<T>
13        // or
14        this
15            .gotService
16            .stream
17            .head(someUrl, streamOptions)
18            .on<T>(eventType)
19            .subscribe(subscribeFunction: Function); // Returns Observable<T>
20        // or
21        this
22            .gotService
23            .stream
24            .post(someUrl, filePathOrStream, streamOptions)
25            .on<T>(eventType)
26            .subscribe(subscribeFunction: Function); // Returns Observable<T>
27        // or
28        this
29            .gotService
30            .stream
31            .put(someUrl, filePathOrStream, streamOptions)
32            .on<T>(eventType)
33            .subscribe(subscribeFunction: Function); // Returns Observable<T>
34        // or
35        this
36            .gotService
37            .stream
38            .patch(someUrl, filePathOrStream, streamOptions)
39            .on<T>(eventType)
40            .subscribe(subscribeFunction: Function); // Returns Observable<T>
41        // or
42        this
43            .gotService
44            .stream
45            .delete(someUrl, filePathOrStream, streamOptions)
46            .on<T>(eventType)
47            .subscribe(subscribeFunction: Function); // Returns Observable<T>
48        // ...
49    }
50}

Contributing

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