Merge pull request #31 from hebertcisco/9-add-documentation-showing-how-all-methods-and-functions-work

Add documentation showing how all methods and functions work to close #9

Author: hebertcisco

.eslintrc

@@ -8,6 +8,7 @@
     "plugin:jest/recommended"
   ],
   "rules": {
-    "@typescript-eslint/no-explicit-any": "off"
+    "@typescript-eslint/no-explicit-any": "off",
+    "@typescript-eslint/no-unused-vars": "off"
   }
 }

.github/FUNDING.yml

@@ -1,6 +1,6 @@
 # These are supported funding model platforms
 
-github: hebertcisco # Replace with up to 4 GitHub Sponsors-enabled usernames e.g., [user1, user2]
+github: [hebertcisco]
 patreon: # Replace with a single Patreon username
 open_collective: # Replace with a single Open Collective username
 ko_fi: # Replace with a single Ko-fi username

.github/dependabot.yml

@@ -1,9 +1,13 @@
 version: 2
 updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "monthly"
+    open-pull-requests-limit: 10
+
   - package-ecosystem: "npm"
     directory: "/"
     schedule:
-      interval: "daily"
-    target-branch: "develop"
-    labels:
-      - "dependencies"
+      interval: "weekly"
+    open-pull-requests-limit: 10

.gitignore

@@ -15,8 +15,8 @@ npm-debug.log
 /coverage
 /.nyc_output
 
-# dist
-dist
+# lib
+lib
 
 # enviroment
 .env

.husky/pre-commit

@@ -0,0 +1,5 @@
+#!/bin/sh
+. "$(dirname "$0")/_/husky.sh"
+
+npm run lint
+npm run test

README.md

@@ -1,101 +1,130 @@
-[![Vulnerabilities](https://sonarcloud.io/api/project_badges/measure?project=hebertcisco_nestjs-undici&metric=vulnerabilities)](https://sonarcloud.io/summary/new_code?id=hebertcisco_nestjs-undici)
+# nestjs-undici
 
-[![Reliability Rating](https://sonarcloud.io/api/project_badges/measure?project=hebertcisco_nestjs-undici&metric=reliability_rating)](https://sonarcloud.io/summary/new_code?id=hebertcisco_nestjs-undici)
-[![codecov](https://codecov.io/gh/hebertcisco/nestjs-undici/branch/master/graph/badge.svg?token=J79GA9DGDT)](https://codecov.io/gh/hebertcisco/nestjs-undici)
+[**nestjs-undici**](/) is a **NestJS** module that provides utility functions for working with the [@nodejs/undici](https://github.com/nodejs/undici) package. **Undici** is a lightweight *HTTP/1.1* client for Node.js, designed to be used with the **NestJs** *environment*.
 
 [![Lines of Code](https://sonarcloud.io/api/project_badges/measure?project=hebertcisco_nestjs-undici&metric=ncloc)](https://sonarcloud.io/summary/new_code?id=hebertcisco_nestjs-undici) [![Code Smells](https://sonarcloud.io/api/project_badges/measure?project=hebertcisco_nestjs-undici&metric=code_smells)](https://sonarcloud.io/summary/new_code?id=hebertcisco_nestjs-undici)
 
-[![Node.js build and publish package](https://github.com/hebertcisco/nestjs-undici/actions/workflows/npm-publish.yml/badge.svg)](https://github.com/hebertcisco/nestjs-undici/actions/workflows/npm-publish.yml)
-
-[![Running Code Coverage](https://github.com/hebertcisco/nestjs-undici/actions/workflows/coverage.yml/badge.svg)](https://github.com/hebertcisco/nestjs-undici/actions/workflows/coverage.yml)
-[![Bugs](https://sonarcloud.io/api/project_badges/measure?project=hebertcisco_nestjs-undici&metric=bugs)](https://sonarcloud.io/summary/new_code?id=hebertcisco_nestjs-undici)
-
-[![TypeScript](https://img.shields.io/badge/TypeScript-007ACC?style=flat&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
-[![Nestjs](https://img.shields.io/badge/Nestjs-ea2845?style=flat&logo=nestjs&logoColor=white)](https://nestjs.com/)
-[![Free. Built on open source. Runs everywhere.](https://img.shields.io/badge/VS_Code-0078D4?style=flat&logo=visual%20studio%20code&logoColor=white)](https://code.visualstudio.com/)
-[![GitHub Actions](https://img.shields.io/badge/github%20actions-%232671E5.svg?style=flat&logo=githubactions&logoColor=white)](https://github.com/hebertcisco/nestjs-undici/actions)
-
 ## Installation
 
+To install [nestjs-undici](https://www.npmjs.com/package/nestjs-undici), you will need to have [Node.js](https://nodejs.org/en/download/) and npm (or [yarn](https://classic.yarnpkg.com/lang/en/docs/install/#windows-stable)) installed on your system. Then, you can run the following command to install the module:
+
 > Install with yarn or npm: `yarn` or `npm`:
 
 ```bash
 # yarn
 yarn add nestjs-undici
 ```
 
+Or NPM:
+
 ```bash
 # npm
 npm i nestjs-undici --save
 ```
 
-### Usage example:
+#### Importing the module
 
-> Project example: [https://github.com/hebertcisco/nestjs-techniques-undici](https://github.com/hebertcisco/nestjs-techniques-undici)
+To use nestjs-undici in your NestJS application, you will need to import it. You can do this by adding the following line to the top of the file where you want to use the module:
+
+```ts
+import { HttpModule } from 'nestjs-undici';
+```
+
+You will also need to include the HttpModule in the imports array of the root AppModule or the module where you want to use it.
 
 ```ts
 // app.module.ts
+
 import { Module } from '@nestjs/common';
 import { HttpModule } from 'nestjs-undici';
 
 import { AppController } from './app.controller';
 import { AppService } from './app.service';
 
+  
 @Module({
-    imports: [
-        HttpModule.register({
-            headers: {
-                'my-header': `foo-bar`,
-            },
-        }),
-    ],
-    controllers: [AppController],
-    providers: [AppService],
+    imports: [
+        HttpModule.register({
+            headers: {
+                'my-header': `foo-bar`,
+            },
+        }),
+    ],
+    controllers: [AppController],
+    providers: [AppService],
 })
 export class AppModule {}
-
 ```
 
-```ts
-// app.service.ts
-import { lastValueFrom } from 'rxjs';
+#### Using the module
+
+To use the nestjs-undici module, you will need to inject the `HttpService` into your component or controller. You can do this by adding it to the constructor arguments and adding a public or private property for it:
 
-import { Injectable } from '@nestjs/common';
+```ts
 import { HttpService } from 'nestjs-undici';
 
-@Injectable()
-export class AppService {
-    constructor(private httpService: HttpService) {}
-    public fetchExternalInfo = async () => {
-        const baseURL = 'https://api.github.com';
-        try {
-            const result = this.httpService.request(`${baseURL}/repos/hebertcisco/undici`);
-
-            const response = await lastValueFrom(result);
-
-            return response.body.json();
-        } catch (error) {
-            throw error;
-        }
-    };
+export class AppComponent {
+  constructor(private httpService: HttpService) {}
 }
 ```
 
-## 🤝 Contributing
+Once you have injected the `HttpService`, you can use it to make HTTP requests using the `request()` method. The `request()` method takes a URL and an options object as arguments, and returns an [RxJS Observable](https://rxjs.dev/api/index/class/Observable) that you can subscribe to in order to handle the response.
+
+For example, here is how you could use the `HttpService` to make a GET request to the `/users` endpoint:
+
+```ts
+import { of } from 'rxjs';
+
+export class AppService {
+  constructor(private httpService: HttpService) {}
+
+  public getUsers(): void {
+    this.httpService
+      .request
+      .get('/users')
+      .subscribe(response => { // Handle the response here }); 
+}}
+```
+
+> You can also use the `post`, `put`, `patch`, `delete`, and `head` methods to send other types of HTTP requests.
+
+## Configuration
 
-Contributions, issues and feature requests are welcome!<br />Feel free to check [issues page](issues).
+The nestjs-undici module supports configuration options through the `register` method. You can pass an options object to the `register` method to configure the Undici client. The available options are the same as the options for the [@nodejs/undici](https://github.com/nodejs/undici) client.
 
-## Show your support
+You can also use the `registerAsync` method to provide the options asynchronously, for example, from a configuration file. The `registerAsync` method accepts an object with the following properties:
 
-Give a ⭐️ if this project helped you!
+- `useClass`: a provider that returns the options object
+- `useExisting`: a provider that returns the options object
+- `useFactory`: a factory function that returns the options object
+- `inject`: an array of providers to inject into the factory function
+- `imports`: an array of modules to import
+- `extraProviders`: an array of additional providers to add to the module
 
-Or buy me a coffee 🙌🏾
+### Customizing the request options
 
-<a href="https://www.buymeacoffee.com/hebertcisco">
-    <img src="https://img.buymeacoffee.com/button-api/?text=Buy me a coffee&emoji=&slug=hebertcisco&button_colour=FFDD00&font_colour=000000&font_family=Inter&outline_colour=000000&coffee_colour=ffffff" />
-</a>
+The `request()` method also accepts an options object as its second argument. This options object can be used to customize the request, such as setting the HTTP method, adding headers, or setting the body of the request.
 
-## 📝 License
+Here is an example of how you could use the options object to set the HTTP method to `POST` and add a JSON payload to the request body:
+
+```ts
+import { of } from 'rxjs';
 
-Copyright © 2022 [Hebert F Barros](https://github.com/hebertcisco).<br />
-This project is [MIT](LICENSE) licensed.
+export class AppService {
+  constructor(private httpService: HttpService) {}
+
+  public createUser(user: User): void {
+    this.httpService
+      .request('/users', {
+        method: 'POST',
+        body: JSON.stringify(user),
+        headers: {
+          'Content-Type': 'application/json',
+        },
+      })
+      .subscribe(response => {
+        // Handle the response here
+      });
+  }
+}
+```

docs/http/http.module.md

@@ -0,0 +1,16 @@
+## Configuration
+
+The nestjs-undici module supports configuration options through the `register` method. You can pass an options object to the `register` method to configure the Undici client. The available options are the same as the options for the [@nodejs/undici](https://github.com/nodejs/undici) client.
+
+You can also use the `registerAsync` method to provide the options asynchronously, for example, from a configuration file. The `registerAsync` method accepts an object with the following properties:
+
+- `useClass`: a provider that returns the options object
+- `useExisting`: a provider that returns the options object
+- `useFactory`: a factory function that returns the options object
+- `inject`: an array of providers to inject into the factory function
+- `imports`: an array of modules to import
+- `extraProviders`: an array of additional providers to add to the module
+
+### Setting the global dispatcher
+
+The `HttpModule` uses the `dispatcher` option of the `request()` method to specify the [Dispatcher](https://github.com/nodejs/undici#dispatcher) that should be used to make the request. By default, the `HttpModule` uses the `createDispatcher()` function from the `@nodejs/undici` package to create

docs/http/http.service.md

@@ -0,0 +1,59 @@
+#### Using the module
+
+To use the nestjs-undici module, you will need to inject the `HttpService` into your component or controller. You can do this by adding it to the constructor arguments and adding a public or private property for it:
+
+```ts
+import { HttpService } from 'nestjs-undici';
+
+export class AppComponent {
+  constructor(private httpService: HttpService) {}
+}
+```
+
+Once you have injected the `HttpService`, you can use it to make HTTP requests using the `request()` method. The `request()` method takes a URL and an options object as arguments, and returns an [RxJS Observable](https://rxjs.dev/api/index/class/Observable) that you can subscribe to in order to handle the response.
+
+For example, here is how you could use the `HttpService` to make a GET request to the `/users` endpoint:
+
+```ts
+import { of } from 'rxjs';
+
+export class AppComponent {
+  constructor(private httpService: HttpService) {}
+
+  public getUsers(): void {
+    this.httpService
+      .request
+      .get('/users')
+      .subscribe(response => { // Handle the response here }); 
+}}
+```
+
+> You can also use the `post`, `put`, `patch`, `delete`, and `head` methods to send other types of HTTP requests.
+
+### Customizing the request options
+
+The `request()` method also accepts an options object as its second argument. This options object can be used to customize the request, such as setting the HTTP method, adding headers, or setting the body of the request.
+
+Here is an example of how you could use the options object to set the HTTP method to `POST` and add a JSON payload to the request body:
+
+```ts
+import { of } from 'rxjs';
+
+export class AppComponent {
+  constructor(private httpService: HttpService) {}
+
+  public createUser(user: User): void {
+    this.httpService
+      .request('/users', {
+        method: 'POST',
+        body: JSON.stringify(user),
+        headers: {
+          'Content-Type': 'application/json',
+        },
+      })
+      .subscribe(response => {
+        // Handle the response here
+      });
+  }
+}
+```

docsify/sidebar.md

@@ -0,0 +1,6 @@
+<!-- Sidebar for Docsify -->
+
+* [**Home**](/ "NestJs Undici")
+* API
+  * [HttpModule](docs/http/http.module.md "NestJs Undici - HttpModule")
+  * [HttpService](docs/http/http.service.md "NestJs Undici - HttpService")

index.d.ts

@@ -1 +1 @@
-export * from './dist';
+export * from './lib';

index.html

@@ -0,0 +1,40 @@
+<!DOCTYPE html>
+<html lang="en">
+
+<head>
+    <meta charset="UTF-8">
+    <title>NestJs Undici</title>
+    <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
+    <meta name="description" content="Undici utilities module based on the @nodejs undici package 🌐">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0, minimum-scale=1.0">
+    <link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify@4/lib/themes/vue.css">
+    <link rel="icon" type="image/png"
+        href="https://d33wubrfki0l68.cloudfront.net/e937e774cbbe23635999615ad5d7732decad182a/26072/logo-small.ede75a6b.svg" />
+    <link rel="icon" type="image/png"
+        href="https://d33wubrfki0l68.cloudfront.net/e937e774cbbe23635999615ad5d7732decad182a/26072/logo-small.ede75a6b.svg" />
+</head>
+
+<body>
+    <div id="app"></div>
+    <script>
+        window.$docsify = {
+            name: 'NestJs Undici',
+            repo: 'https://github.com/hebertcisco/nestjs-undici',
+            loadSidebar: 'docsify/sidebar.md',
+            auto2top: true,
+            subMaxLevel: 3,
+            maxLevel: 3,
+            themeColor: '#ea2845',
+            noCompileLinks: [
+                'benchmarks/.*'
+            ],
+            relativePath: true
+        }
+    </script>
+    <!-- Docsify v4 -->
+    <script src="https://cdn.jsdelivr.net/npm/docsify@4"
+        integrity="sha256-ycM1gQUpS76Yjdc8fQA5WlyWGQ7YtDR68v+cbMEhdLY=">
+        </script>
+</body>
+
+</html>

index.js

@@ -3,4 +3,4 @@ function __export(m) {
     for (const p in m) if (!exports.hasOwnProperty(p)) exports[p] = m[p];
 }
 exports.__esModule = true;
-__export(require("./dist"));
+__export(require("./lib"));

index.ts

@@ -1 +1 @@
-export * from './dist';
+export * from './lib';

jest.config.js

@@ -1,7 +1,7 @@
 module.exports = {
-    transform: {
-      '^.+\\.(t|j)s$': 'ts-jest',
-    },
-    testRegex: '(/__tests__/.*|(\\.|/)(test|spec))\\.(t|j)s$',
-    moduleFileExtensions: ['ts', 'js', 'json', 'node']
-  };
+  transform: {
+    '^.+\\.(t|j)s$': 'ts-jest',
+  },
+  testRegex: '(/__tests__/.*|(\\.|/)(test|spec))\\.(t|j)s$',
+  moduleFileExtensions: ['ts', 'js', 'json', 'node'],
+};