{"id":13525496,"url":"https://github.com/szmarczak/cacheable-lookup","last_synced_at":"2025-05-15T16:03:05.314Z","repository":{"id":34416982,"uuid":"165464004","full_name":"szmarczak/cacheable-lookup","owner":"szmarczak","description":"A cacheable dns.lookup(…) that respects TTL :tada:","archived":false,"fork":false,"pushed_at":"2024-01-29T00:52:40.000Z","size":125,"stargazers_count":204,"open_issues_count":20,"forks_count":31,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-05-04T14:47:27.458Z","etag":null,"topics":["cache","dns","lookup","query","resolve"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/szmarczak.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-01-13T04:03:49.000Z","updated_at":"2025-04-22T16:02:23.000Z","dependencies_parsed_at":"2024-06-03T17:25:23.342Z","dependency_job_id":null,"html_url":"https://github.com/szmarczak/cacheable-lookup","commit_stats":{"total_commits":118,"total_committers":12,"mean_commits":9.833333333333334,"dds":0.1694915254237288,"last_synced_commit":"9e60c9f6e74a003692aec68f3ddad93afe613b8f"},"previous_names":[],"tags_count":29,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/szmarczak%2Fcacheable-lookup","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/szmarczak%2Fcacheable-lookup/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/szmarczak%2Fcacheable-lookup/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/szmarczak%2Fcacheable-lookup/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/szmarczak","download_url":"https://codeload.github.com/szmarczak/cacheable-lookup/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253415086,"owners_count":21904790,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cache","dns","lookup","query","resolve"],"created_at":"2024-08-01T06:01:19.391Z","updated_at":"2025-05-15T16:03:05.295Z","avatar_url":"https://github.com/szmarczak.png","language":"JavaScript","readme":"# cacheable-lookup\n\n\u003e A cacheable [`dns.lookup(…)`](https://nodejs.org/api/dns.html#dns_dns_lookup_hostname_options_callback) that respects TTL :tada:\n\n[![Node CI](https://github.com/szmarczak/cacheable-lookup/workflows/Node%20CI/badge.svg)](https://github.com/szmarczak/cacheable-lookup/actions)\n[![codecov](https://codecov.io/gh/szmarczak/cacheable-lookup/branch/master/graph/badge.svg)](https://codecov.io/gh/szmarczak/cacheable-lookup)\n[![npm](https://img.shields.io/npm/dm/cacheable-lookup.svg)](https://www.npmjs.com/package/cacheable-lookup)\n[![install size](https://packagephobia.now.sh/badge?p=cacheable-lookup)](https://packagephobia.now.sh/result?p=cacheable-lookup)\n\nMaking lots of HTTP requests? You can save some time by caching DNS lookups :zap:\n\n## Usage\n\n### Using the `lookup` option\n\n```js\nimport http from 'node:http';\nimport CacheableLookup from 'cacheable-lookup';\n\nconst cacheable = new CacheableLookup();\n\nhttp.get('http://example.com', {lookup: cacheable.lookup}, response =\u003e {\n\t// Handle the response here\n});\n```\n\n### Attaching CacheableLookup to an Agent\n\n```js\nimport http from 'node:http';\nimport https from 'node:https';\nimport CacheableLookup from 'cacheable-lookup';\n\nconst cacheable = new CacheableLookup();\n\ncacheable.install(http.globalAgent);\ncacheable.install(https.globalAgent);\n\nhttp.get('http://example.com', response =\u003e {\n\t// Handle the response here\n});\n```\n\n## API\n\n### new CacheableLookup(options)\n\nReturns a new instance of `CacheableLookup`.\n\n#### options\n\nType: `object`\\\nDefault: `{}`\n\nOptions used to cache the DNS lookups.\n\n##### cache\n\nType: `Map` | [`Keyv`](https://github.com/lukechilds/keyv/)\\\nDefault: `new Map()`\n\nCustom cache instance. If `undefined`, it will create a new one.\n\n**Note**: If you decide to use Keyv instead of the native implementation, the performance will drop by 10x. Memory leaks may occur as it doesn't provide any way to remove all the deprecated values at once.\n\n**Tip**: [`QuickLRU`](https://github.com/sindresorhus/quick-lru) is fully compatible with the Map API, you can use it to limit the amount of cached entries. Example:\n\n```js\nimport http from 'node:http';\nimport CacheableLookup from 'cacheable-lookup';\nimport QuickLRU from 'quick-lru';\n\nconst cacheable = new CacheableLookup({\n\tcache: new QuickLRU({maxSize: 1000})\n});\n\nhttp.get('http://example.com', {lookup: cacheable.lookup}, response =\u003e {\n\t// Handle the response here\n});\n```\n\n##### options.maxTtl\n\nType: `number`\\\nDefault: `Infinity`\n\nThe maximum lifetime of the entries received from the specifed DNS server (TTL in seconds).\n\nIf set to `0`, it will make a new DNS query each time.\n\n**Pro Tip**: This shouldn't be lower than your DNS server response time in order to prevent bottlenecks. For example, if you use Cloudflare, this value should be greater than `0.01`.\n\n##### options.fallbackDuration\n\nType: `number`\\\nDefault: `3600` (1 hour)\n\nWhen the DNS server responds with `ENOTFOUND` or `ENODATA` and the OS reports that the entry is available, it will use `dns.lookup(...)` directly for the requested hostnames for the specified amount of time (in seconds).\n\n**Note**: You should avoid setting this to `0` unless the provided DNS servers' database is limited to few domains.\n\n##### options.errorTtl\n\nType: `number`\\\nDefault: `0.15`\n\nThe time how long it needs to remember queries that threw `ENOTFOUND` or `ENODATA` (TTL in seconds).\n\n**Note**: This option is independent, `options.maxTtl` does not affect this.\n\n**Pro Tip**: This shouldn't be lower than your DNS server response time in order to prevent bottlenecks. For example, if you use Cloudflare, this value should be greater than `0.01`.\n\n##### options.resolver\n\nType: `dns.Resolver | dns.promises.Resolver`\\\nDefault: [`new dns.promises.Resolver()`](https://nodejs.org/api/dns.html#dns_class_dns_resolver)\n\nAn instance of [DNS Resolver](https://nodejs.org/api/dns.html#dns_class_dns_resolver) used to make DNS queries.\n\n##### options.lookup\n\nType: `Function`\\\nDefault: [`dns.lookup`](https://nodejs.org/api/dns.html#dns_dns_lookup_hostname_options_callback)\n\nThe fallback function to use when the DNS server responds with `ENOTFOUND` or `ENODATA`.\n\nIf you don't query internal hostnames (such as `localhost`, `database.local` etc.), it is strongly recommended to set this to `false`.\n\n### Entry object\n\nType: `object`\n\n#### address\n\nType: `string`\n\nThe IP address (can be an IPv4 or IPv6 address).\n\n#### family\n\nType: `number`\n\nThe IP family (`4` or `6`).\n\n##### expires\n\nType: `number`\n\n**Note**: This is not present when falling back to `dns.lookup(...)`!\n\nThe timestamp (`Date.now() + ttl * 1000`) when the entry expires.\n\n#### ttl\n\n**Note**: This is not present when falling back to `dns.lookup(...)`!\n\nThe time in seconds for its lifetime.\n\n#### source\n\n**Note**: This is not present when falling back to `dns.lookup(...)`!\n\nWhether this entry was loaded from the cache or came from a query (`cache` or `query`)\n\n### Entry object (callback-style)\n\nWhen `options.all` is `false`, then `callback(error, address, family, expires, ttl)` is called.\\\nWhen `options.all` is `true`, then `callback(error, entries)` is called.\n\n### CacheableLookup instance\n\n#### servers\n\nType: `Array`\n\nThe DNS servers used to make queries. Can be overridden - doing so will clear the cache.\n\n#### [lookup(hostname, options, callback)](https://nodejs.org/api/dns.html#dns_dns_lookup_hostname_options_callback)\n\n#### lookupAsync(hostname, options)\n\nThe asynchronous version of `dns.lookup(…)`.\n\nReturns an [entry object](#entry-object).\\\nIf `options.all` is true, returns an array of entry objects.\n\n##### hostname\n\nType: `string`\n\n##### options\n\nType: `object`\n\nThe same as the [`dns.lookup(…)`](https://nodejs.org/api/dns.html#dns_dns_lookup_hostname_options_callback) options.\n\n#### query(hostname)\n\nAn asynchronous function which returns cached DNS lookup entries.\\\nThis is the base for `lookupAsync(hostname, options)` and `lookup(hostname, options, callback)`.\n\n**Note**: This function has no options.\n\nReturns an array of objects with `address`, `family`, `ttl` and `expires` properties.\n\n#### queryAndCache(hostname)\n\nAn asynchronous function which makes two DNS queries: A and AAAA. The result is cached.\\\nThis is used by `query(hostname)` if no entry in the database is present.\n\nReturns an array of objects with `address`, `family`, `ttl` and `expires` properties.\n\n#### updateInterfaceInfo()\n\nUpdates interface info. For example, you need to run this when you plug or unplug your WiFi driver.\n\n**Note:** Running `updateInterfaceInfo()` will trigger `clear()` only on network interface removal.\n\n#### clear(hostname?)\n\nClears the cache for the given hostname. If the hostname argument is not present, the entire cache will be emptied.\n\n## High performance\n\nPerformed on:\n- Query: `example.com`\n- CPU: i7-7700k\n- CPU governor: performance\n\n```\nCacheableLookup#lookupAsync                x 2,896,251 ops/sec ±1.07% (85 runs sampled)\nCacheableLookup#lookupAsync.all            x 2,842,664 ops/sec ±1.11% (88 runs sampled)\nCacheableLookup#lookupAsync.all.ADDRCONFIG x 2,598,283 ops/sec ±1.21% (88 runs sampled)\nCacheableLookup#lookup                     x 2,565,913 ops/sec ±1.56% (85 runs sampled)\nCacheableLookup#lookup.all                 x 2,609,039 ops/sec ±1.01% (86 runs sampled)\nCacheableLookup#lookup.all.ADDRCONFIG      x 2,416,242 ops/sec ±0.89% (85 runs sampled)\ndns#lookup                                 x 7,272     ops/sec ±0.36% (86 runs sampled)\ndns#lookup.all                             x 7,249     ops/sec ±0.40% (86 runs sampled)\ndns#lookup.all.ADDRCONFIG                  x 5,693     ops/sec ±0.28% (85 runs sampled)\nFastest is CacheableLookup#lookupAsync.all\n```\n\n## Related\n\n- [cacheable-request](https://github.com/lukechilds/cacheable-request) - Wrap native HTTP requests with RFC compliant cache support\n","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fszmarczak%2Fcacheable-lookup","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fszmarczak%2Fcacheable-lookup","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fszmarczak%2Fcacheable-lookup/lists"}