All notable changes to this project are documented in this file.
The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.
- New field
connection.is_anycastin response model: whether the IP address is announced via anycast, i.e. simultaneously from multiple locations. - New field
security.is_residential_proxyin response model: whether the IP address is a node of a residential proxy network.
- Custom
fetchimplementation: passfetchin the client options to route requests through your own implementation (proxies, instrumentation, testing), e.g.new IpregistryClient({ apiKey, fetch: myFetch }). - Typed field selection: when a literal
fieldsexpression is passed, the response type is narrowed to the selected fields, including nested paths, e.g.client.lookupIp(ip, { fields: 'location.region' })resolves toApiResponse<{ location: { region: Region } }>and accessing unselected fields (even withinlocation) is a compile-time error. Comma-separated selections are merged and paths that traverse arrays narrow the element type. Dynamic (non-literal) expressions keep the full response type. The newSelectedFieldsutility type is exported. - Missing
decimal_separatorandgroup_separatorfields inCurrencyFormat.
- Build with tsdown instead of tsup; the published files, their names and the package exports are unchanged.
- Options-object API: construct the client with
new IpregistryClient({ apiKey, baseUrl, timeout, maxRetries, cache, ... })and pass per-call options as a plain object, e.g.client.lookupIp(ip, { fields: 'location', hostname: true }). ThebaseUrloption accepts the shorthand'eu'for the European Union endpoint. - Request cancellation: every lookup accepts an
AbortSignalvia{ signal }. Aborting cancels the in-flight request, pending retries and their backoff waits, and pending batch chunks. parseUserAgentsaccepts an array (client.parseUserAgents([ua1, ua2])) in addition to the deprecated variadic form.- Generic cache typing:
IpregistryCache<V>and the newIpregistryCacheValuetype.
- The library is now compiled with full TypeScript strict mode (
noImplicitAnyenabled).
IpregistryConfigBuilder: pass anIpregistryClientOptionsobject to the constructor instead.IpregistryOption,FilterOption,HostnameOption,IpregistryOptionsand the variadic lookup signatures: pass aLookupOptionsobject instead.- The variadic
parseUserAgents(...userAgents)form: pass an array instead.
All deprecated forms keep working in 7.x and behave identically (including cache
key compatibility between legacy options and their LookupOptions equivalents);
they will be removed in a future major version.
// Before (6.x) // After (7.x)
new IpregistryClient( new IpregistryClient({
new IpregistryConfigBuilder('KEY') apiKey: 'KEY',
.withEuBaseUrl() baseUrl: 'eu',
.withTimeout(10000) cache: new InMemoryCache(),
.build(), timeout: 10000,
new InMemoryCache()) })
client.lookupIp(ip, client.lookupIp(ip, {
IpregistryOptions.filter('location'), fields: 'location',
IpregistryOptions.hostname(true)) hostname: true,
})- Automatic splitting of large batch lookups, aligned with the Go client: inputs beyond the API limit (1024 values) are chunked and dispatched with bounded concurrency, preserving input order. Configurable via
withMaxBatchSizeandwithBatchConcurrency(default 4, set 1 for sequential dispatch). - New
DEFAULT_MAX_BATCH_SIZEconstant exposing the API per-request limit.
- Document timeout, retry, and batch configuration in the README.
- Configurable retry behavior aligned with the Go client:
withMaxRetries(default 3),withRetryInterval(exponential backoff base, default 1 second),withRetryOnServerError(default true) andwithRetryOnTooManyRequests(default false, honoring theRetry-Afterheader when enabled).
- Require Node.js 20+.
- Retry transient network errors and, by default, 5xx responses; previously only timeouts were retried.
- Replace the
lru-cachedependency with an internal implementation; the library now has zero runtime dependencies.
- Return
falsefromisErrorandisApiErrorfor non-object values instead of throwing aTypeError.
- Declare the package side-effect free to improve tree-shaking by bundlers.
- Expose
package.jsonthrough the packageexportsmap.
- Map request timeouts to a
ClientErrorwith message 'Request timed out'; a typo prevented the mapping from ever matching. - Send the current library version in the
user-agentheader instead of a hardcoded 4.0.0. - Percent-encode user-supplied values interpolated into API URL paths.
- Cache batch lookup results under the requested IP addresses and ASNs so that caching works when the
fieldsoption filters out theiporasnresponse fields. - Declare the
typescondition first in the packageexportsmap and provide format-specific type declarations so that TypeScript resolves them for both ESM and CommonJS consumers.
6.0.0 - 2024-06-04
- Modify the library packaging to make ECMAScript modules (ESM) optional.
- Substitute the 'ky' dependency with native fetch API.
- Reduce the default timeout setting to 5 seconds.
- Implement retries, up to two times, with exponential backoff in the event of a timeout.
5.0.2 - 2024-03-27
- Add missing fields
sizeandstatusto type AutonomousSystemPrefix.
5.0.1 - 2024-03-17
- Fix a packaging issue.
5.0.0 - 2024-03-17
- New
IpregistryClient#batchLookupAsnsmethod. - New
IpregistryClient#lookupAsnmethod. - New
IpregistryClient#originLookupAsnmethod. - New
IpregistryConfigBuilder.withEuBaseUrlmethod. Once configured, requests will be handled by nodes deployed in the European Union only. - New
IpregistryRequestHandler#batchLookupAsnsmethod. - New
IpregistryRequestHandler#lookupAsnmethod. - New
IpregistryRequestHandler#originLookupAsnmethod.
- Rename
IpregistryClient#batchLookuptoIpregistryClient#batchLookupIps. - Rename
IpregistryClient#lookuptoIpregistryClient#lookupIp. - Rename
IpregistryClient#originLookuptoIpregistryClient#originLookupIp. - Rename
IpregistryClient#parsetoIpregistryClient#parseUserAgents. - Rename
IpregistryConfigBuilder.withApiUrltoIpregistryConfigBuilder.withBaseUrl. - Rename
IpregistryRequestHandler#batchLookuptoIpregistryRequestHandler#batchLookupIps. - Rename
IpregistryRequestHandler#lookuptoIpregistryRequestHandler#lookupIp. - Rename
IpregistryRequestHandler#originLookuptoIpregistryRequestHandler#originLookupIp. - Rename
IpregistryRequestHandler#parsetoIpregistryRequestHandler#parseUserAgents. - Rename utility class
UserAgenttoUserAgents. - Replace Axios by ky to bring support to Cloudflare Workers in addition to browser and NodeJS environments.
- Require NodeJS 18+.
- Fixed origin requests returning wrong information when caching is enabled. Cache is now automatically disabled for origin requests since it is incompatible.
4.5.0 - 2022-04-15
- New
is_vpnfield insecurityobject.
4.4.2 - 2022-04-03
- Invalid field name
security.is_tor_exit_nodehas been renamed tosecurity.is_tor_exit.
- Upgrade dependencies.
4.4.1 - 2022-02-14
- Upgrade dependencies.
4.4.0 - 2021-12-21
- New
security.is_relayfield.
4.3.0 - 2021-12-14
- New
parsemethod in IpregistryClient for parsing user-agent header values.
- Deprecate
IpregistryConfigBuilder.withApiUrlin favor ofIpregistryConfigBuilder.withBaseUrl.
- Replace invalid
operating_systemfield in UserAgent byos.
4.2.0 - 2021-10-26
- IpInfo responses have a new
companyfield. - The Connection type field includes a new value of
INACTIVE.
4.1.0 - 2021-07-26
- New connection type
government.
- Improve utility function to detect bots/crawlers/spiders based on user-agent value.
- Fix invalid property names:
language.name_native->language.nativeandtime_zone.daylight_saving->time_zone.in_daylight_saving.
- Merge connection type
cdnwithhosting.
4.0.0 - 2021-04-08
- [BREAKING] Rename DefaultCache to InMemoryCache.
- Upgrade dependencies.
3.1.0 - 2020-12-02
- Use Authorization header instead of the key query parameter to pass API keys.
3.0.2 - 2020-10-28
- Upgrade dependencies to fix an issue affecting TypeScript users (axios/axios#3219).
3.0.1 - 2020-10-03
- Access to remaining credits was always returning
nulldue to a packaging issue.
3.0.0 - 2020-06-27
- Caching is now optional and disabled by default.
- Default timeout value has been increased to 15s from 3s.
2.0.1 - 2020-10-03
- Fix access to remaining credits due to the removal of the response header
ipregistry-creditsfrom the Ipregistry API.
2.0.0 - 2020-03-12
- [BREAKING] All client methods use a new ApiResponse type as response. You can now access usage data (i.e. remaining credits, throttling info) in addition to IP payloads.
1.4.0 - 2020-01-12
- New field
connection.routein response model. - Introduce new value
cdnfor fieldconnection.type.
- Define a null union type for all fields that can have a
nullvalue.
1.3.0 - 2019-10-27
- New currency fields
name_nativeandplural_native.
- Decrease the default cache period to 10min from 24h. This is to better handle use cases that require fresh security data. Indeed, such data is updated multiple times each hour. You can still configure the cache period to a higher value: https://github.com/ipregistry/ipregistry-javascript#configuring-cache-max-age
1.2.1 - 2019-10-08
- Fix a packaging issue.
1.2.0 - 2019-10-08
- Add examples for cache configuration, hostname lookup and fields selection.
- Add
BAD_REQUESTandFORBIDDEN_IP_ORIGINerror codes.
- Export ipregistry as default export in client side module.
1.1.0 - 2019-08-08
- License headers.
- Types for new fields returned by the Ipregistry API.
1.0.0 - 2019-07-24
- All custom errors extend IpregistryError.
- Ignore case when checking if User-Agent is spider/bot.
0.10.1 - 2019-07-24
- Fix deployment to NPM. No code change.
0.10.0 - 2019-07-24
- Rename browser file to
index.jsfromindex.browser.js.
0.9.2 - 2019-07-24
- Browser support.
0.9.1 - 2019-07-23
- First public release.