@nimble-api/node-adapter

Node.js http/https adapter for @nimble-api/api-service. Provides keep-alive connection pooling, proxy support, redirect handling, stream responses, decompression, TLS configuration, and cookie jar integration.

npm install @nimble-api/node-adapter

Quick Start

import { createApiClient } from '@nimble-api/api-service'
import { createNodeAdapter } from '@nimble-api/node-adapter'

const client = createApiClient({
  baseUrl: 'https://api.example.com',
  adapter: createNodeAdapter({
    keepAlive: true,
    maxRedirects: 5,
  }),
})

const data = await client.get('/users')

Adapter Options

Option	Default	Description
`keepAlive`	`true`	Reuse TCP connections
`maxSockets`	`Infinity`	Max sockets per host
`maxFreeSockets`	`256`	Max idle sockets per host
`keepAliveMsecs`	`1000`	Keep-alive timeout ms
`connectTimeout`	—	TCP connection establishment timeout (ms)
`readTimeout`	—	Socket read timeout (ms), separate from request timeout
`proxy`	`'env'`	`'env'` \| `{ host, port, protocol?, auth? }` \| `false`
`maxRedirects`	`5`	Max redirects to follow. `0` disables
`decompress`	`true`	Auto-decompress gzip/deflate/brotli
`httpAgent`	—	Custom `http.Agent` (overrides keepAlive settings)
`httpsAgent`	—	Custom `https.Agent` (overrides keepAlive settings)
`rejectUnauthorized`	`true`	TLS certificate validation
`ca`	—	CA certificate(s) for self-signed certs
`cert`	—	Client certificate
`key`	—	Client private key
`socketPath`	—	Unix socket path
`lookup`	—	Custom DNS lookup function
`cookieJar`	—	Cookie jar instance for automatic cookie handling

Proxy

By default, HTTP_PROXY / HTTPS_PROXY / NO_PROXY environment variables are respected.

// Explicit proxy config (overrides env vars)
createNodeAdapter({
  proxy: { host: 'proxy.corp.com', port: 8080, auth: { username: 'user', password: 'pass' } },
})

// Disable proxy
createNodeAdapter({ proxy: false })

Response Stream

const client = createApiClient({
  adapter: createNodeAdapter(),
})

const stream = await client.get('/large-file', { responseType: 'stream' })
stream.pipe(fs.createWriteStream('output.bin'))

import { SimpleCookieJar } from '@nimble-api/node-adapter'

const jar = new SimpleCookieJar()
const client = createApiClient({
  adapter: createNodeAdapter({ cookieJar: jar }),
})

// Cookies are automatically stored and sent
await client.post('/login', { json: { user: 'admin', pass: 'secret' } })
await client.get('/dashboard') // automatically sends session cookie

For advanced use cases, implement the CookieJar interface or wrap tough-cookie.

Connection Timeout vs Read Timeout

createNodeAdapter({
  connectTimeout: 5000,  // TCP handshake timeout — 5s
  readTimeout: 10000,    // Socket idle timeout — 10s (for slow responses)
})

The adapter also respects ApiOptions.timeout / RequestOptions.timeout as the overall request deadline (including redirects and retries).

TLS / Client Certificates

createNodeAdapter({
  rejectUnauthorized: false,  // for self-signed certs
  cert: fs.readFileSync('/path/to/client.crt'),
  key: fs.readFileSync('/path/to/client.key'),
  ca: fs.readFileSync('/path/to/ca.crt'),
})

DNS Lookup

import { promises as dns } from 'node:dns'

createNodeAdapter({
  lookup: (hostname, opts, cb) => {
    // IPv4 first, then IPv6
    dns.resolve4(hostname).then(addrs => cb(null, addrs[0], 4), cb)
  },
})

License

ISC