# @mangar2/httpservice

> implements a simple http/https client/server

Latest version **2.1.0** (published 2023-02-08) · LGPL-3.0-or-later license · 0 weekly downloads

## Install

```sh
npm install @mangar2/httpservice
pnpm add @mangar2/httpservice
yarn add @mangar2/httpservice
bun add @mangar2/httpservice
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 2.1.0 |
| Published | 2023-02-08 |
| First published | 2020-01-12 |
| Weekly downloads | 0 |
| License | LGPL-3.0-or-later |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 2 |
| Unpacked size | 62.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | Volker Böhm |
| Maintainers | mangar2 |
| Keywords | http, https, client, server |

## Links

- npm: https://www.npmjs.com/package/@mangar2/httpservice
- Repository: https://github.com/Mangar2/yaha.git#master
- Homepage: https://github.com/Mangar2/yaha.git
- Issues: https://github.com/Mangar2/yaha/issues
- npm.io page: https://npm.io/package/@mangar2/httpservice

## Dependencies (2)

- [@mangar2/errorlog](https://npm.io/package/@mangar2/errorlog.md) latest
- [@mangar2/callbacks](https://npm.io/package/@mangar2/callbacks.md) latest

## Alternatives

- [launchdarkly-js-client-sdk](https://npm.io/package/launchdarkly-js-client-sdk.md) — 2.5M weekly downloads
- [@elastic/elasticsearch](https://npm.io/package/@elastic/elasticsearch.md) — 2.1M weekly downloads
- [@c8y/client](https://npm.io/package/@c8y/client.md) — 15.3K weekly downloads
- [@signaldb/maverickjs](https://npm.io/package/@signaldb/maverickjs.md) — 1.7K weekly downloads
- [@bbc/http-transport-cache](https://npm.io/package/@bbc/http-transport-cache.md) — 1.2K weekly downloads

## Recent versions

- 2.1.0 (latest) — 2023-02-08
- 2.0.3 — 2023-01-14
- 2.0.2 — 2023-01-14
- 2.0.1 — 2023-01-14
- 2.0.0 — 2023-01-14
- 1.2.0 — 2023-01-10
- 1.1.2 — 2022-11-13
- 1.1.1 — 2022-11-13
- 1.1.0 — 2020-04-14
- 1.0.2 — 2020-03-21
- 1.0.1 — 2020-01-13
- 1.0.0 — 2020-01-12

## README

<!-- This file is generated by jsmddoc version 0.1 -->

# Abstract

Provides simple http/https client and server classes

## Contents

- [Meta](#Meta)
- [Global Functions](#Global-functions)
  - [echo](#echo)
  - [run](#run)
- [Class HTTPClient](#Class-HTTPClient)
  - [Parameters](#HTTPClient-Parameters)
  - [Members](#HTTPClient-Members)
  - [Methods](#HTTPClient-Methods)
    - [close](#close)
    - [getRequest](#getRequest)
    - [post](#post)
    - [put](#put)
    - [send](#send)
    - [sendv2](#sendv2)
    - [setConnection](#setConnection)
- [Class HTTPSClient](#Class-HTTPSClient)
  - [Parameters](#HTTPSClient-Parameters)
  - [Methods](#HTTPSClient-Methods)
    - [close](#close)
    - [getRequest](#getRequest)
    - [post](#post)
    - [put](#put)
    - [send](#send)
    - [sendv2](#sendv2)
- [Class HTTPSServer](#Class-HTTPSServer)
  - [Parameters](#HTTPSServer-Parameters)
  - [Members](#HTTPSServer-Members)
  - [Methods](#HTTPSServer-Methods)
    - [close](#close)
    - [listen](#listen)
    - [on](#on)
- [Class HTTPServer](#Class-HTTPServer)
  - [Parameters](#HTTPServer-Parameters)
  - [Members](#HTTPServer-Members)
  - [Methods](#HTTPServer-Methods)
    - [close](#close)
    - [listen](#listen)
    - [on](#on)

## Meta

| | |
| --- | --- |
| **File** | httpservice.js |
| **Abstract** | Provides simple http/https client and server classes |
| **Author** | Volker Böhm |
| **Copyright** | Copyright ( c ) 2020 Volker Böhm |
| **License** | This software is licensed under the GNU LESSER GENERAL PUBLIC LICENSE Version 3 . It is furnished "as is" , without any support , and with no warranty , express or implied , as to its usefulness for any purpose . |

## Callback definitions

### HTTPGetCallback

Callback for HTTP ( S ) GET requests

#### HTTPGetCallback Parameters

| Name | Type | Description |
| ---------- | ------------ | ----------------- |
| `params` | `URLSearchParams` | Search parameter of the GET URL | |
| `headers` | `Object` | headers | |
| `path` | `string` | path name ( without search parameters ) | |
| `res` | `Object` | http ( s ) res structure | |

### HTTPCallback

Callback for HTTP ( S ) put , post , patch , delete , listen , or closed requests

#### HTTPCallback Parameters

| Name | Type | Description |
| ---------- | ------------ | ----------------- |
| `payload` | `string` | http payload ( maybe stringified JSON ) | |
| `headers` | `Object` | headers | |
| `path` | `string` | path name ( without search parameters ) | |
| `res` | `Object` | http ( s ) res structure | |

## Global functions

### echo

`async echo (method, header, payload, path, res)`

Handles a post request

#### echo Parameters

| Name | Type | Description |
| ---------- | ------------ | ----------------- |
| `method` | `string` | method name | |
| `header` | `object` | header of the sender | |
| `payload` | `string` | object payload | |
| `path` | `string` | path of the request | |
| `res` | `object` | result object | |

### run

`run ()`

Starts the server

## Class HTTPClient

`new HTTPClient(host, port, type)`

Class simplifying access to the node http service for http clients

### Example

```javascript
const client = new HTTPClient('myhost', 10000);
client.sendv2({ path: 'info/getdata/1', method: 'GET' })
client.post({ path: 'postdata/1', payload={info: 'hello world')}, type='json' })
client.get('info/getdata/1')
```

### HTTPClient Parameters

| Name | Type | Attribute | Default | Description |
| ---------- | ------------ | ------------ | ------------ | ----------------- |
| `host` | `string` |  |  | host name or ip address | |
| `port` | `string, number` |  |  | port number | |
| `type` | `string` | optional | 'http' | either 'http' or 'https' for http/https clients | |

### HTTPClient Members

| Name | Type | description |
| ------------ | ------------ | ------------ |
| `agent` | `` | @description |

### HTTPClient Methods

#### close

`close () => {promise}`

Aborts all open requests

##### close returns

| Type | Description |
| ---- | ----------- |
| `promise` | , resolved once all connections are closed |

#### getRequest

`getRequest (path, headers) => {Promise<{statusCode, headers, payload}`

Sends a get request

##### getRequest Parameters

| Name | Type | Attribute | Default | Description |
| ---------- | ------------ | ------------ | ------------ | ----------------- |
| `path` | `string` |  |  | http path | |
| `headers` | `object` | optional | { } | header to send | |

##### getRequest returns

| Type | Description |
| ---- | ----------- |
| `Promise<{statusCode, headers, payload` | > } Promise; resolve = { statusCode , headers , payload } |

#### post

`post (sendOptions, type) => {Promise<{statusCode, headers, payload}`

Sends a post request

##### post Parameters

| Name | Type | Attribute | Description |
| ---------- | ------------ | ------------ | ----------------- |
| `sendOptions` | `object` |  | all information required for sending | |
| `type` | `string` | optional | type of the payload data : html , text , json , form , xml | |

#### sendOptions properties

| Name | Type | Attribute | Default | Description |
| ---------- | ------------ | ------------ | ------------ | ----------------- |
| `path` | `string` |  |  | http path | |
| `payload` | `object` | optional |  | payload to send | |
| `headers` | `object` | optional | { } | header to send | |

##### post returns

| Type | Description |
| ---- | ----------- |
| `Promise<{statusCode, headers, payload` | > } Promise; resolve = { statusCode , headers , payload } |

#### put

`put (sendOptions, type) => {Promise<{statusCode, headers, payload}`

Sends a put request

##### put Parameters

| Name | Type | Attribute | Description |
| ---------- | ------------ | ------------ | ----------------- |
| `sendOptions` | `object` |  | all information required for sending | |
| `type` | `string` | optional | type of the payload data : html , text , json , form , xml | |

#### sendOptions properties

| Name | Type | Attribute | Default | Description |
| ---------- | ------------ | ------------ | ------------ | ----------------- |
| `path` | `string` |  |  | http path | |
| `payload` | `object` | optional |  | payload to send | |
| `headers` | `object` | optional | { } | header to send | |

##### put returns

| Type | Description |
| ---- | ----------- |
| `Promise<{statusCode, headers, payload` | > } Promise; resolve = { statusCode , headers , payload } |

#### send

`send (path, method, payload, headers) => {Promise<{statusCode, headers, payload}`

Sends data . A payload of type "object" is automatically stringified , a string is not

##### send Parameters

| Name | Type | Attribute | Default | Description |
| ---------- | ------------ | ------------ | ------------ | ----------------- |
| `path` | `string` |  |  | http path | |
| `method` | `string` |  |  | http send method PUT , GET , . . . | |
| `payload` | `string, object` |  |  | payload to send | |
| `headers` | `object` | optional | { } | header to send | |

##### send returns

| Type | Description |
| ---- | ----------- |
| `Promise<{statusCode, headers, payload` | > } Promise; resolve = { statusCode , headers , payload } |

#### sendv2

`sendv2 (sendOptions, type) => {Promise<{statusCode, headers, payload}`

Sends data . Adds a content-type element to the header and stringifies the boy based on the type

##### sendv2 Parameters

| Name | Type | Attribute | Description |
| ---------- | ------------ | ------------ | ----------------- |
| `sendOptions` | `object` |  | all information required for sending | |
| `type` | `string` | optional | type of the payload data : html , text , json , form , xml | |

#### sendOptions properties

| Name | Type | Attribute | Default | Description |
| ---------- | ------------ | ------------ | ------------ | ----------------- |
| `path` | `string` |  |  | http path | |
| `method` | `string` |  |  | http send method PUT , GET , . . . | |
| `payload` | `object` | optional |  | payload to send | |
| `headers` | `object` | optional | { } | header to send | |

##### sendv2 returns

| Type | Description |
| ---- | ----------- |
| `Promise<{statusCode, headers, payload` | > } Promise; resolve = { statusCode , headers , payload } |

#### setConnection

`setConnection (host, port)`

Sets host name and port number

##### setConnection Parameters

| Name | Type | Description |
| ---------- | ------------ | ----------------- |
| `host` | `string` | host name | |
| `port` | `string` | port number | |

## Class HTTPSClient

`new HTTPSClient(host, port)`

Class simplifying access to the node http service for http clients

### Example

```javascript
client.sendv2({ path: 'info/getdata/1', method: 'GET' })
client.post({ path: 'postdata/1', payload={info: 'hello world')}, type='json' })
client.get('info/getdata/1')
```

### HTTPSClient Parameters

| Name | Type | Description |
| ---------- | ------------ | ----------------- |
| `host` | `string` | host name or ip address | |
| `port` | `string, number` | port number | |

### HTTPSClient Methods

#### close

`close () => {promise}`

Aborts all open requests

##### close returns

| Type | Description |
| ---- | ----------- |
| `promise` | resolved once all connections are closed |

#### getRequest

`getRequest (path, headers) => {Promise<{statusCode, headers, payload}`

Sends a get request

##### getRequest Parameters

| Name | Type | Attribute | Default | Description |
| ---------- | ------------ | ------------ | ------------ | ----------------- |
| `path` | `string` |  |  | http path | |
| `headers` | `object` | optional | { } | header to send | |

##### getRequest returns

| Type | Description |
| ---- | ----------- |
| `Promise<{statusCode, headers, payload` | > } Promise; resolve = { statusCode , headers , payload } |

#### post

`post (sendOptions, type) => {Promise<{statusCode, headers, payload}`

Sends a post request

##### post Parameters

| Name | Type | Attribute | Description |
| ---------- | ------------ | ------------ | ----------------- |
| `sendOptions` | `object` |  | all information required for sending | |
| `type` | `string` | optional | type of the payload data : html , text , json , form , xml | |

#### sendOptions properties

| Name | Type | Attribute | Default | Description |
| ---------- | ------------ | ------------ | ------------ | ----------------- |
| `path` | `string` |  |  | http path | |
| `payload` | `object` | optional |  | payload to send | |
| `headers` | `object` | optional | { } | header to send | |

##### post returns

| Type | Description |
| ---- | ----------- |
| `Promise<{statusCode, headers, payload` | > } Promise; resolve = { statusCode , headers , payload } |

#### put

`put (sendOptions, type) => {Promise<{statusCode, headers, payload}`

Sends a put request

##### put Parameters

| Name | Type | Attribute | Description |
| ---------- | ------------ | ------------ | ----------------- |
| `sendOptions` | `object` |  | all information required for sending | |
| `type` | `string` | optional | type of the payload data : html , text , json , form , xml | |

#### sendOptions properties

| Name | Type | Attribute | Default | Description |
| ---------- | ------------ | ------------ | ------------ | ----------------- |
| `path` | `string` |  |  | http path | |
| `payload` | `object` | optional |  | payload to send | |
| `headers` | `object` | optional | { } | header to send | |

##### put returns

| Type | Description |
| ---- | ----------- |
| `Promise<{statusCode, headers, payload` | > } Promise; resolve = { statusCode , headers , payload } |

#### send

`send (path, method, payload, headers) => {Promise<{statusCode, headers, payload}`

Sends data . A payload of type "object" is automatically stringified , a string is not

##### send Parameters

| Name | Type | Attribute | Default | Description |
| ---------- | ------------ | ------------ | ------------ | ----------------- |
| `path` | `string` |  |  | http path | |
| `method` | `string` |  |  | http send method PUT , GET , . . . | |
| `payload` | `string, object` |  |  | payload to send | |
| `headers` | `object` | optional | { } | header to send | |

##### send returns

| Type | Description |
| ---- | ----------- |
| `Promise<{statusCode, headers, payload` | > } Promise; resolve = { statusCode , headers , payload } |

#### sendv2

`sendv2 (sendOptions, type) => {Promise<{statusCode, headers, payload}`

Sends data . Adds a content-type element to the header and stringifies the boy based on the type

##### sendv2 Parameters

| Name | Type | Attribute | Description |
| ---------- | ------------ | ------------ | ----------------- |
| `sendOptions` | `object` |  | all information required for sending | |
| `type` | `string` | optional | type of the payload data : html , text , json , form , xml | |

#### sendOptions properties

| Name | Type | Attribute | Default | Description |
| ---------- | ------------ | ------------ | ------------ | ----------------- |
| `path` | `string` |  |  | http path | |
| `method` | `string` |  |  | http send method PUT , GET , . . . | |
| `payload` | `object` | optional |  | payload to send | |
| `headers` | `object` | optional | { } | header to send | |

##### sendv2 returns

| Type | Description |
| ---- | ----------- |
| `Promise<{statusCode, headers, payload` | > } Promise; resolve = { statusCode , headers , payload } |

## Class HTTPSServer

`new HTTPSServer(port)`

Creates a http server listening to a certain port for simplifying access to the node http service Register your callbacks according to the http functions you need .

### Example

```javascript
const server = new HTTPSServer(10000)
server.on('GET', (URLSearchParam, headers, path, res) => console.log(path))
const httpsOptions = {
  key: fs.readFileSync('key.pem'),
  cert: fs.readFileSync('cert.pem')
}
server.listen(httpsOptions)
server.close()
```

### HTTPSServer Parameters

| Name | Type | Description |
| ---------- | ------------ | ----------------- |
| `port` | `number` | port to listen to | |

### HTTPSServer Members

| Name | Type | description |
| ------------ | ------------ | ------------ |
| `address` | `@type` | Gets the address of the server , once listen has been called If listen has not been called yet , undefined is returned |

### HTTPSServer Methods

#### close

`close () => {promise}`

Stops the server from accepting new connections and closes existing connections . Calls the callback "close" , once the server is closed .

##### close returns

| Type | Description |
| ---- | ----------- |
| `promise` | resolved , once the connection is closed |

#### listen

`listen (options)`

Creates a https server listening

##### listen Parameters

| Name | Type | Description |
| ---------- | ------------ | ----------------- |
| `options` | `Object` | additional options | |

#### on

`on (event, callback)`

Sets a callback

##### on Parameters

| Name | Type | Description |
| ---------- | ------------ | ----------------- |
| `event` | `string` | RESTful http verb ( POST , GET , PUT , PATCH , DELETE , OPTIONS ) and 'listen' ( called once listening ) and 'closed' ( called once closed ) | |
| `callback` | `HTTPGetCallback, HTTPCallback` | ( payload , headers , path , res ) where payload is the http payload , headers the http headers , res the result structure and path is is the http path as string | |

## Class HTTPServer

`new HTTPServer(port)`

Creates a http server listening to a certain port for simplifying access to the node http service Register your callbacks according to the http functions you need .

### Example

```javascript
const server = new HTTPServer(10000)
server.on('GET', (URLSearchParam, headers, path, res) => console.log(path))
server.listen()
server.close()
```

### HTTPServer Parameters

| Name | Type | Description |
| ---------- | ------------ | ----------------- |
| `port` | `number` | port to listen to | |

### HTTPServer Members

| Name | Type | description |
| ------------ | ------------ | ------------ |
| `address` | `@type` | Gets the address of the server , once listen has been called If listen has not been called yet , undefined is returned |

### HTTPServer Methods

#### close

`close () => {promise}`

Stops the server from accepting new connections and closes existing connections . Calls the callback "close" , once the server is closed .

##### close returns

| Type | Description |
| ---- | ----------- |
| `promise` | resolved , once the connection is closed |

#### listen

`listen ()`

Creates a http server listening

#### on

`on (event, callback)`

Sets a callback

##### on Parameters

| Name | Type | Description |
| ---------- | ------------ | ----------------- |
| `event` | `string` | RESTful http verb ( POST , GET , PUT , PATCH , DELETE , OPTIONS ) and 'listen' ( called once listening ) and 'closed' ( called once closed ) | |
| `callback` | `HTTPGetCallback, HTTPCallback` | ( payload , headers , path , res ) where payload is the http payload , headers the http headers , res the result structure and path is is the http path as string | |

---
_Source: https://npm.io/package/@mangar2/httpservice · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._