dns-cache-resolver

dns-cache-resolver is a lightweight, performant DNS caching library for Node.js, designed with TypeScript for robust and type-safe applications. 🚀

Why Use dns-cache-resolver? 🧐

Boost Performance: Reduce repetitive DNS lookups with in-memory caching.
Customizable: Configure cache behavior with flexible TTL and size options.
TypeScript First: Enjoy the benefits of type safety and IDE autocompletion.
Plug-and-Play: Simple to integrate into existing applications.

Features ✨

Configurable TTL 🕒: Set the time-to-live for cache entries.
Maximum Entries 📦: Control the number of entries in the cache.
In-Memory Caching 🧠: Speed up DNS resolutions with fast, local cache storage.
IPv4 and IPv6 Support 🌍: Resolve addresses for both address families.
Timeout Handling ⏱️: Avoid slow lookups with built-in resolution timeouts.

Installation ⚙️

Install via npm:

npm install dns-cache-resolver

Usage 📘

Here’s a quick example:

import { DnsCache } from 'dns-cache-resolver';

// Initialize the DNS cache
const dnsCache = new DnsCache({
  ttl: 60000, // Cache entries live for 60 seconds
  maxEntries: 100, // Maximum of 100 cache entries
});

// Resolve a hostname and cache the result
const ip = await dnsCache.resolve('example.com');
console.log(`IP Address: ${ip}`);

Configuration Options 🛠️

Option	Type	Default	Description
`ttl`	number	60000	Time-to-live for cache entries in milliseconds.
`maxEntries`	number	1000	Maximum number of entries allowed in the cache.

Examples 💡

Basic Usage

import { DnsCache } from 'dns-cache-resolver';

const dnsCache = new DnsCache({
  ttl: 30000, // 30 seconds TTL
  maxEntries: 50, // Limit to 50 cache entries
});

async function getIp(hostname: string) {
  try {
    const ip = await dnsCache.resolve(hostname);
    console.log(`Resolved IP for ${hostname}: ${ip}`);
  } catch (error) {
    console.error(`Error resolving ${hostname}:`, error.message);
  }
}

getIp('example.com');
getIp('nodejs.org');

IPv4 and IPv6 Support

const ipV4 = await dnsCache.resolve('example.com', 4); // IPv4
console.log(`IPv4: ${ipV4}`);

const ipV6 = await dnsCache.resolve('example.com', 6); // IPv6
console.log(`IPv6: ${ipV6}`);

Integrating with Axios 🌐

You can use dns-cache-resolver with Axios to enhance performance and avoid DNS overhead:

import axios from 'axios';
import { DnsCache } from 'dns-cache-resolver';

const dnsCache = new DnsCache({
  ttl: 30000,
  maxEntries: 100,
});

// Create an Axios instance
const axiosInstance = axios.create();

// Add a DNS resolution interceptor
axiosInstance.interceptors.request.use(
  async config => {
    const url = new URL(config.url || '');
    const hostname = url.hostname;

    try {
      const ip = await dnsCache.resolve(hostname);
      config.url = config.url.replace(hostname, ip);
    } catch (error) {
      console.error(`Failed to resolve DNS for ${hostname}: ${error.message}`);
    }

    return config;
  },
  error => Promise.reject(error)
);

// Make a request
axiosInstance
  .get('https://example.com/api/data')
  .then(response => console.log('Response:', response.data))
  .catch(error => console.error('Error:', error));

Clearing Cache

dnsCache.clear(); // Remove all cached entries
dnsCache.remove('example.com', 4); // Remove specific entry for IPv4

Listing Cache Entries

const entries = dnsCache.list();
entries.forEach(([key, value]) => {
  console.log(`Key: ${key}, Address: ${value.address}, Expires At: ${value.expiresAt}`);
});

Contributing 🤝

We’re excited to have your contributions! Whether it’s fixing bugs, adding features, or improving documentation, feel free to open issues or submit pull requests on GitHub.

How to Contribute

Fork the repository.
Create a feature branch (git checkout -b feature/your-feature).
Commit your changes (git commit -m 'Add some feature').
Push to your branch (git push origin feature/your-feature).
Open a pull request.

License 📄

This project is licensed under the MIT License. See the LICENSE file for more details.

Contact 📬

For questions, feedback, or suggestions, reach out to Alex Silva.

Acknowledgements 🙏

A huge thanks to our contributors and users for their continuous support and feedback!