https://github.com/dnlup/agent-11
A simple pool manager for undici
https://github.com/dnlup/agent-11
http nodejs undici
Last synced: about 2 months ago
JSON representation
A simple pool manager for undici
- Host: GitHub
- URL: https://github.com/dnlup/agent-11
- Owner: dnlup
- License: isc
- Created: 2020-08-13T10:35:39.000Z (almost 5 years ago)
- Default Branch: next
- Last Pushed: 2023-03-10T23:57:37.000Z (about 2 years ago)
- Last Synced: 2025-03-14T09:17:48.299Z (2 months ago)
- Topics: http, nodejs, undici
- Language: JavaScript
- Homepage:
- Size: 582 KB
- Stars: 6
- Watchers: 3
- Forks: 0
- Open Issues: 15
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# agent-11
[](https://badge.fury.io/js/%40dnlup%2Fagent-11)
[](https://codecov.io/gh/dnlup/agent-11)
[](https://snyk.io/test/github/dnlup/agent-11?targetFile=package.json)
> A simple pool manager for [`undici`](https://github.com/nodejs/undici).
You might find this module useful if you use [`undici`](https://github.com/nodejs/undici) and need to manage connections to different hosts and you don't know them ahead of time, so you can't
create static clients.
`agent-11` controls [`undici`'s](https://github.com/nodejs/undici) pool connections to different hosts. Each time you request a new one, it creates a new pool.
If you don't request this connection after a certain amount of time, `agent-11` will close it.
- [Installation](#installation)
+ [Requirements](#requirements)
+ [latest stable version](#latest-stable-version)
+ [latest development version](#latest-development-version)
- [Usage](#usage)
- [API](#api)
* [Class: `Agent11`](#class-agent11)
+ [Static method: `Agent11.urlToObject(url)`](#static-method-agent11urltoobjecturl)
+ [Static method: `Agent11.getKey(url[, options])`](#static-method-agent11getkeyurl-options)
+ [new `Agent11([options])`](#new-agent11options)
+ [`agent.getConnection(url, [options])`](#agentgetconnectionurl-options)
+ [`agent.close()`](#agentclose)
+ [`agent.destroy([error])`](#agentdestroyerror)
- [Contributing](#contributing)
## Installation
#### Requirements
`agent-11` requires that you already have installed `undici` in your project.
#### latest stable version
```bash
$ npm i @dnlup/agent-11
```
#### latest development version
```bash
$ npm i @dnlup/agent-11@next
```
## Usage
```js
const Agent11 = require('@dnlup/agent-11')
const agent = new Agent11({
closeTimeout: 6e5, // inactive connections will be closed after 600000 millieconds
connectionOptions: {
pipelining: 10
}
}
const conn1 = agent.getConnection('http://localhost:3000/some/path') // use conn1 to make requests with undici API to locahost:3000
const conn2 = agent.getConnection(new URL('http://localhost:4000/some/other/path', {
socketPath: '/tmp/agent-11.sock' // these options are merged with the default `connectionOptions` passed when creating the agent
})
const conn3 = agent.getConnection({
protocol: 'http:',
hostname: 'localhost',
port: 5000
})
// close all the agent connections
agent.close().then().catch(console.error)
// destroy all the agent connections
agent.destroy(new Error('no more!')).then().catch(console.error)
```
## API
> The module directly exports a [`Agent11`](#class-agent11) class, which is the connections manager.
### Class: `Agent11`
It manages `undici`'s pool connections.
#### Static method: `Agent11.urlToObject(url)`
* `url` ``: the url to convert.
* Returns: `` A url-like object with the properties `protocol`, `hostname` and `port`.
#### Static method: `Agent11.getKey(url[, options])`
* `url` ``: a url-like object.
* `options` ``: connection options. See [undici documentation](https://github.com/nodejs/undici#new-undiciclienturl-opts).
* Returns: ``: the key that maps the url.
This method creates a key that maps a connection pool to a url.
#### new `Agent11([options])`
* `options` ``
* `closeTimeout` ``: the time (in milliseconds) of inactivity, after which it will close a connection. **Default:** `60000`.
* `maxHosts` ``: the maximum number of connections to different hosts. **Default:** `Infinity` .
* `connectionOptions`: the default options to use to create a new connection. See [undici documentation](https://github.com/nodejs/undici#new-undiciclienturl-opts).
#### `agent.getConnection(url, [options])`
* `url` ``: the url to connect to.
* `options` ``: the connection options.
* Returns: [`Pool`](https://github.com/nodejs/undici#new-undicipoolurl-opts)
The parameters are the same ones as [`undici`](https://github.com/nodejs/undici#new-undiciclienturl-opts). It will merge the `options` object with the `connectionOptions` specified when creating the class instance.
It returns a `Pool` instance connected to the given `url` and `options`.
#### `agent.close()`
* Returns: ``
It closes all the `Pool` connections gracefully.
#### `agent.destroy([error])`
* `error` ``: the error to emit when destroying the connections.
* Returns: ``
It destroys all the `Pool` connections. It optionally takes an error parameter.
## Contributing
You found a bug or want to discuss and implement a new feature? This project welcomes contributions.
The code follows the [standardjs](https://standardjs.com/) style guide.
Every contribution should pass the existing tests or implementing new ones if that's the case.
```bash
# Run tests
$ npm test
# Lint the code
$ npm lint
# Create the TOC in the README
$ npm run doc
```