# node-dnslookup

> Improve your dns lookup in NodeJS, more customizable.

Latest version **0.1.1** (published 2021-05-31) · MIT license · 0 weekly downloads

## Install

```sh
npm install node-dnslookup
pnpm add node-dnslookup
yarn add node-dnslookup
bun add node-dnslookup
```

## Health

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

Positive: no vulnerabilities.

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

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.1.1 |
| Published | 2021-05-31 |
| First published | 2021-05-31 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 15.8 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | litilexuezha |
| Maintainers | litilexuezha |
| Keywords | dns, lookup, node, ip, hosts |

## Links

- npm: https://www.npmjs.com/package/node-dnslookup
- Repository: https://github.com/LitileXueZha/node-dnslookup
- Homepage: https://github.com/LitileXueZha/node-dnslookup#readme
- Issues: https://github.com/LitileXueZha/node-dnslookup/issues
- npm.io page: https://npm.io/package/node-dnslookup

## Alternatives

- [lodash.startswith](https://npm.io/package/lodash.startswith.md) — 769.7K weekly downloads
- [@tarojs/service](https://npm.io/package/@tarojs/service.md) — 33.9K weekly downloads
- [io.extendreality.tilia.indicators.spatialtargets.unity](https://npm.io/package/io.extendreality.tilia.indicators.spatialtargets.unity.md) — 131 weekly downloads
- [@rtarojs/taro](https://npm.io/package/@rtarojs/taro.md) — 90 weekly downloads
- [node-branch-io](https://npm.io/package/node-branch-io.md) — 50 weekly downloads

## Recent versions

- 0.1.1 (latest) — 2021-05-31
- 0.1.0 — 2021-05-31

## README

# node-dnslookup

Improve your dns lookup in NodeJS, more customizable.

#### Features

+ DNS cache in memory
+ Local hosts map like `/etc/hosts`
+ Use specific DNS servers

## Usage

Install via npm.

```shell
npm install --save node-dnslookup
```

Quck examples:

```javascript
const ns = require('node-dnslookup');

https.request('example.org', {
    lookup: ns.lookup,
});

// Apply to all requests
ns.use(https.globalAgent);

// With options
new ns.DNSLookup(options).lookup
// Or
ns.use(agent, options);
```

Options table:

|property|description|default|example|
|-|-|-|-|
|hosts|self-defined local hosts|`[]`|`['127.0.0.1 local localhost', '::1 ipv6.local']`|
|servers|DNS servers. Useful for private network|`[]`|`['8.8.8.8']`|

## More

Inspired by `cacheable-lookup`; Related post: [Fixing DNS in Node.js](https://httptoolkit.tech/blog/configuring-nodejs-dns/).

#### Reason

The native [`dns.lookup`](https://nodejs.org/api/dns.html#dns_dns_lookup_hostname_options_callback) is implemented as a synchronous call on libuv's threadpool. So when you have a lot of network requests in short time, the process may be blocked becauseof DNS lookups, even causes itself or other unrelated node scripts hang up and be a "zombie" process.

> No benchmark data proves better performance in production, but it theoretically does. It's not recommanded if no problems come with you.

<!-- In my case, there is a spider script that makes lot of https request, run long time with loops, on 1vCore 2G cloud server. It always hang up after several hours, finally this resolve my problem. -->

#### Benchmarks

```log
┌──────────────┬─────────┬─────────┬──────────┬────────┬────────┬──────────┬─────────┬───────────┬───────────┐
│   function   │    N    │   #1    │   max    │  min   │  avg   │ >10ms(%) │ >1ms(%) │ >0.1ms(%) │ faster(%) │
├──────────────┼─────────┼─────────┼──────────┼────────┼────────┼──────────┼─────────┼───────────┼───────────┤
│ 'dns.lookup' │ 1000000 │ 11.9297 │ 361.3681 │ 0.1868 │ 0.2596 │  0.0203  │ 0.6732  │  99.3064  │           │
│  'ns.lookup' │ 1000000 │ 14.0073 │ 110.6485 │ 0.0004 │ 0.0009 │  0.0001  │ 0.0053  │   0.0103  │  99.986   │
└──────────────┴─────────┴─────────┴──────────┴────────┴────────┴──────────┴─────────┴───────────┴───────────┘
Total: 26:19.123 (m:ss.mmm)
```

<details>

Indicators|description
-|-
"N"         | run times
"#1"        | average cost time of every hostname first lookup
"max"       | maximum lookup cost time exclude the first
"min"       | minimum lookup cost time exclude the first
"min"       | average lookup cost time exclude the first
"faster(%)" | (count of cost time that less than `dns.lookup` minimum value) / total
</details>

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