better-lookup

library1.4.1jsnpmunverified

An async DNS lookup function for Node.js that implements atomic cache operations using throttling to ensure only one write-procedure occurs for concurrent requests. Current stable version is 1.4.1, with regular updates. Unlike alternatives like cacheable-lookup or dns-lookup-cache, it guarantees atomicity and supports /etc/hosts file on both Unix and Windows. Ships TypeScript types and requires Node.js >=14.

devops

npm install better-lookup

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · BETTER-LOOKUP

better-lookup

devopsjavascriptv1.4.1

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

lookup

✓ import { lookup } from 'better-lookup'

✗ import lookup from 'better-lookup'

ESM import using named export. The package is ESM-only and does not provide a default export.

install

✓ import { install } from 'better-lookup'

✗ const { install } = require('better-lookup')

Package is ESM-only since v1, CommonJS require() is not supported and will throw an error.

AddressInfo

✓ import { AddressInfo } from 'better-lookup'

TypeScript type export for use in type annotations. Only available with TypeScript.

Demonstrates using the lookup function with Node.js https module to resolve IPv4 addresses.

import * as https from 'https'; import { lookup } from 'better-lookup'; const req = https.get('https://example.com', { lookup, family: 4 }, (res) => { console.log('Status:', res.statusCode); });

Debug

Known issues

breakingPackage is ESM-only. CommonJS require() is not supported.

fix

Use ES module imports (import ... from 'better-lookup') or switch to dynamic import().

affects: >=1.0.0

deprecatedCallback-based API is deprecated in favor of Promise-based API.

fix

Use the async/await or Promise-based overloads of lookup().

affects: >=1.0.0

gotchaTTL is supported but will enforce a refresh after 10 seconds regardless of the TTL value.

fix

Be aware that cached results may be refreshed at most every 10 seconds.

affects: >=1.0.0

gotchaWhen family is omitted and all is not set, only one address (IPv4 or IPv6) is returned, not both.

fix

Explicitly set family: 0 to get both, or use options.all to get all addresses.

affects: >=1.0.0

Errors

Common errors & fixes

ERR_REQUIRE_ESM: require() of ES Module not supported

Attempting to use CommonJS require() on this ESM-only package.

fix

Use import syntax in your project or enable ESM in package.json.

TypeError: lookup is not a function

Incorrect import of default export instead of named export.

fix

Change to: import { lookup } from 'better-lookup'

getaddrinfo EAI_AGAIN

DNS resolution failure due to network issues or /etc/hosts not being parsed correctly.

fix

Ensure network connectivity or check if the hostname exists. The package uses dns.resolve4/6, which may fail on some systems.

Upgrade

Version history

1.4.1latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

9 hits · last 30 days

node

Resources

githubhttps://github.com/ayonli/better-lookup ↗

packagebetter-lookup ↗

homepagehttps://github.com/ayonli/better-lookup#readme ↗