Reuse HTTPS connections through an undici Agent and negotiate HTTP/2

Every lookup used to call the global fetch with its default dispatcher,
so a client had no connection pool of its own to control or close. IPData
now creates an undici Agent together with the instance (allowH2 for
HTTP/2 via ALPN with HTTP/1.1 fallback, 60 s idle timeout, 30 s HTTP/2
PING and TCP keepalive probes) and passes it to every fetch call, so TCP
and TLS are negotiated once per client instead of once per request.

A trailing, optional httpConfig constructor argument exposes http2,
keepAliveTimeout and dispatcher (to inject a ProxyAgent,
EnvHttpProxyAgent or MockAgent). close() releases an Agent the instance
created and leaves an injected dispatcher alone. A request that fails
before any response byte arrived because a pooled connection was reset
or closed is retried exactly once; HTTP statuses are never retried. The
bulk POST now also sends Accept: application/json.

Tests replace the global.fetch patch with an undici MockAgent injected
through httpConfig.dispatcher, and a loopback HTTP server proves that
consecutive requests reuse one connection and that close() releases it.
CI runs on pull requests and on Node 20, 22 and 24. undici ^7.22.0 needs
Node >= 20.18.1 (lru-cache 11 already excluded Node 18), the version
becomes 3.1.0 and the lock file is regenerated.

Claude-Session: https://claude.ai/code/session_01VQiRp4zEJKUXHrKkFaeUke
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

Author: claude

.github/workflows/default.yml

@@ -4,6 +4,7 @@ on:
   push:
     branches:
       - '**'
+  pull_request:
 
 jobs:
   lint:
@@ -22,13 +23,16 @@ jobs:
 
   test:
     runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [20, 22, 24]
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4
       - name: Install node
         uses: actions/setup-node@v4
         with:
-          node-version: '22'
+          node-version: ${{ matrix.node-version }}
       - name: Install dependencies
         run: npm ci
       - name: Test

README.md

@@ -4,7 +4,7 @@
 
 A Node.js library for the [ipdata](https://ipdata.co) API. Look up IP addresses for geolocation, threat intelligence, company data, and more.
 
-Requires **Node.js 18** or later. Uses the native `fetch` API with zero HTTP dependencies.
+Requires **Node.js 20.18.1** or later. HTTP requests go through [undici](https://undici.nodejs.org), the HTTP client behind Node's built-in `fetch`, so that connections are pooled and reused across lookups and HTTP/2 is negotiated where available.
 
 **Table of Contents**
 
@@ -15,6 +15,7 @@ Requires **Node.js 18** or later. Uses the native `fetch` API with zero HTTP dep
   - [EU Endpoint](#eu-endpoint)
   - [Lookup](#lookup)
   - [Bulk Lookup](#bulk-lookup)
+- [Connection reuse and HTTP/2](#connection-reuse-and-http2)
 - [Response Fields](#response-fields)
 - [TypeScript](#typescript)
 
@@ -140,6 +141,56 @@ With field filtering:
 const info = await ipdata.bulkLookup(['1.1.1.1', '1.0.0.1'], ['ip', 'city']);
 ```
 
+## Connection reuse and HTTP/2
+
+An `IPData` instance keeps a persistent HTTPS connection pool (an [undici](https://undici.nodejs.org) `Agent`) for as long as it lives. Create one client per process (or one per API key or endpoint), keep it, and reuse it for every lookup: each new client pays a fresh TLS handshake. Requests to api.ipdata.co are multiplexed over HTTP/2 when the platform negotiates it, and fall back to HTTP/1.1 keep-alive otherwise.
+
+Node.js runs your code on one thread, so a single instance can be shared by every request handler in the process; `worker_threads` and `cluster` workers each need their own instance, because connections cannot be shared across threads or processes. Idle HTTP/1.1 connections are closed after 60 seconds, HTTP/2 sessions are kept alive with a PING every 30 seconds, and neither keeps the event loop alive, so a script exits normally without any extra call. Call `await ipdata.close()` at shutdown when you want the pooled connections released immediately. If you pass your own `dispatcher`, you own it and `close()` leaves it open.
+
+```js
+const ipdata = new IPData('<apiKey>');
+
+// ... lookups ...
+
+await ipdata.close();
+```
+
+### HTTP options
+
+The optional fourth constructor argument configures the transport:
+
+```js
+const ipdata = new IPData('<apiKey>', undefined, undefined, {
+  http2: true, // negotiate HTTP/2 via ALPN and fall back to HTTP/1.1 (default: true)
+  keepAliveTimeout: 60000, // milliseconds an idle connection is kept before it is closed (default: 60000)
+});
+```
+
+Use `dispatcher` to send requests through your own [undici dispatcher](https://undici.nodejs.org/#/docs/api/Dispatcher), for example to reach the API through a proxy or to intercept requests in tests. `http2` and `keepAliveTimeout` only apply to the pool the library creates itself.
+
+```js
+import { EnvHttpProxyAgent, MockAgent, ProxyAgent } from 'undici';
+
+// Explicit proxy
+const ipdata = new IPData('<apiKey>', undefined, undefined, {
+  dispatcher: new ProxyAgent('http://proxy.example.com:8080'),
+});
+
+// HTTP_PROXY, HTTPS_PROXY and NO_PROXY from the environment
+const ipdata = new IPData('<apiKey>', undefined, undefined, { dispatcher: new EnvHttpProxyAgent() });
+
+// Tests: canned responses, no network
+const mockAgent = new MockAgent();
+mockAgent.disableNetConnect();
+mockAgent
+  .get('https://api.ipdata.co')
+  .intercept({ path: '/1.1.1.1?api-key=<apiKey>', method: 'GET' })
+  .reply(200, { ip: '1.1.1.1', is_eu: false });
+const ipdata = new IPData('<apiKey>', undefined, undefined, { dispatcher: mockAgent });
+```
+
+A request that fails because the server closed a pooled connection before any response byte arrived (connection reset or closed) is sent once more on a fresh connection; this also covers the `POST` made by `bulkLookup()`. HTTP error statuses are never retried.
+
 ## Response Fields
 
 The following fields are available for use with `selectField` and `fields`:
@@ -159,5 +210,5 @@ The following fields are available for use with `selectField` and `fields`:
 The library is written in TypeScript and exports the following types:
 
 ```ts
-import IPData, { EU_BASE_URL, CacheConfig, LookupParams, LookupResponse } from 'ipdata';
+import IPData, { EU_BASE_URL, CacheConfig, HttpConfig, LookupParams, LookupResponse } from 'ipdata';
 ```

package-lock.json

@@ -1,11 +1,11 @@
 {
   "name": "ipdata",
-  "version": "3.0.0",
+  "version": "3.1.0",
   "description": "JavaScript library to gather information for an ip using https://ipdata.co.",
   "main": "./lib/ipdata.js",
   "types": "./lib/ipdata.d.ts",
   "engines": {
-    "node": ">=18"
+    "node": ">=20.18.1"
   },
   "scripts": {
     "prebuild": "del lib",
@@ -25,7 +25,8 @@
   "homepage": "https://github.com/ipdata/node#readme",
   "dependencies": {
     "lru-cache": "^11.2.6",
-    "tslib": "^2.8.1"
+    "tslib": "^2.8.1",
+    "undici": "^7.22.0"
   },
   "devDependencies": {
     "@types/jest": "^29.5.0",