Split large batch lookups into chunks with bounded concurrency like the Go client

laurentpellegrino · laurentpellegrino · commit f55e5974c399 · 2026-07-05T08:48:12.000+02:00
diff --git a/README.md b/README.md
@@ -195,6 +195,29 @@ Rate limiting is opt-in per API key on Ipregistry, which is why
 `retryOnTooManyRequests` defaults to false. Enable it if your key is
 rate limited.
 
+## Batch lookups
+
+`batchLookupIps` and `batchLookupAsns` look up many values in a single call:
+
+```typescript
+const response = await client.batchLookupIps(['1.1.1.1', '8.8.8.8']);
+```
+
+Inputs larger than the API's per-request limit (1024 values) are split
+automatically into multiple requests dispatched with bounded concurrency
+(4 requests in flight by default), and results are returned in input order.
+Cached entries are served locally; only the remainder is requested. Both knobs
+are configurable:
+
+```typescript
+const client = new IpregistryClient(
+    new IpregistryConfigBuilder('YOUR_API_KEY')
+        .withMaxBatchSize(256)     // values per request, capped at 1024
+        .withBatchConcurrency(1)   // sequential dispatch, gentler on rate-limited keys
+        .build()
+);
+```
+
 ## Enabling hostname lookup
 
 By default, the Ipregistry API does not return information about the hostname a given IP address resolves to. 
diff --git a/src/index.ts b/src/index.ts
@@ -16,6 +16,8 @@
 
 import {
     ApiResponse,
+    ApiResponseCredits,
+    ApiResponseThrottling,
     BatchResult,
     DefaultRequestHandler,
     IpregistryRequestHandler,
@@ -32,6 +34,12 @@ import { IpregistryOption } from './options.js'
 
 import { isApiError, LookupError } from './errors.js'
 
+/**
+ * The maximum number of IP addresses or ASNs the Ipregistry API accepts in a
+ * single batch request.
+ */
+export const DEFAULT_MAX_BATCH_SIZE = 1024
+
 /**
  * Represents the configuration for the Ipregistry API client.
  * This class holds the API key, base URL, and timeout setting used for API requests.
@@ -81,6 +89,19 @@ export class IpregistryConfig {
      */
     public readonly retryOnTooManyRequests: boolean = false
 
+    /**
+     * The maximum number of values sent in a single batch request. Larger
+     * batches are split into this many values per request. Capped at
+     * `DEFAULT_MAX_BATCH_SIZE` (the API limit).
+     */
+    public readonly maxBatchSize: number = DEFAULT_MAX_BATCH_SIZE
+
+    /**
+     * How many batch sub-requests are dispatched concurrently when a batch is
+     * large enough to be split into chunks. Defaults to 4.
+     */
+    public readonly batchConcurrency: number = 4
+
     /**
      * Constructs a new `IpregistryConfig` instance.
      * @param apiKey The API key for authenticating requests.
@@ -90,6 +111,8 @@ export class IpregistryConfig {
      * @param retryInterval Optional. The base backoff between retries in milliseconds.
      * @param retryOnServerError Optional. Whether 5xx responses are retried.
      * @param retryOnTooManyRequests Optional. Whether 429 responses are retried.
+     * @param maxBatchSize Optional. The maximum number of values per batch request.
+     * @param batchConcurrency Optional. How many batch sub-requests run concurrently.
      */
     constructor(
         apiKey: string,
@@ -99,6 +122,8 @@ export class IpregistryConfig {
         retryInterval?: number,
         retryOnServerError?: boolean,
         retryOnTooManyRequests?: boolean,
+        maxBatchSize?: number,
+        batchConcurrency?: number,
     ) {
         this.apiKey = apiKey
 
@@ -125,6 +150,18 @@ export class IpregistryConfig {
         if (retryOnTooManyRequests !== undefined) {
             this.retryOnTooManyRequests = retryOnTooManyRequests
         }
+
+        if (
+            maxBatchSize !== undefined &&
+            maxBatchSize > 0 &&
+            maxBatchSize <= DEFAULT_MAX_BATCH_SIZE
+        ) {
+            this.maxBatchSize = maxBatchSize
+        }
+
+        if (batchConcurrency !== undefined && batchConcurrency > 0) {
+            this.batchConcurrency = batchConcurrency
+        }
     }
 }
 
@@ -148,6 +185,10 @@ export class IpregistryConfigBuilder {
 
     private retryOnTooManyRequests: boolean = false
 
+    private maxBatchSize: number = DEFAULT_MAX_BATCH_SIZE
+
+    private batchConcurrency: number = 4
+
     constructor(apiKey: string) {
         this.apiKey = apiKey
     }
@@ -222,6 +263,34 @@ export class IpregistryConfigBuilder {
         return this
     }
 
+    /**
+     * Sets the maximum number of values sent in a single batch request. Batch
+     * lookups split larger inputs into this many values per request. Values
+     * are capped at `DEFAULT_MAX_BATCH_SIZE` (the API limit); a value <= 0 is
+     * ignored.
+     * @param maxBatchSize The maximum number of values per batch request.
+     * @returns The `IpregistryConfigBuilder` instance for chaining.
+     */
+    public withMaxBatchSize(maxBatchSize: number): IpregistryConfigBuilder {
+        this.maxBatchSize = maxBatchSize
+        return this
+    }
+
+    /**
+     * Sets how many batch sub-requests are dispatched concurrently when a
+     * batch is large enough to be split into chunks. A value <= 0 is ignored.
+     * Set it to 1 for strictly sequential dispatch, which is gentler on a
+     * rate-limited API key.
+     * @param batchConcurrency How many batch sub-requests run concurrently.
+     * @returns The `IpregistryConfigBuilder` instance for chaining.
+     */
+    public withBatchConcurrency(
+        batchConcurrency: number,
+    ): IpregistryConfigBuilder {
+        this.batchConcurrency = batchConcurrency
+        return this
+    }
+
     public build(): IpregistryConfig {
         return new IpregistryConfig(
             this.apiKey,
@@ -231,6 +300,8 @@ export class IpregistryConfigBuilder {
             this.retryInterval,
             this.retryOnServerError,
             this.retryOnTooManyRequests,
+            this.maxBatchSize,
+            this.batchConcurrency,
         )
     }
 }
@@ -312,21 +383,12 @@ export class IpregistryClient {
             AutonomousSystem | LookupError
         >(asns.length)
 
-        let apiResponse: ApiResponse<
-            BatchResult<AutonomousSystem | LookupError>
-        > | null
-        let freshAutonomousSystem: (AutonomousSystem | LookupError)[]
-
-        if (cacheMisses.length > 0) {
-            apiResponse = await this.requestHandler.batchLookupAsns(
-                cacheMisses,
-                options,
-            )
-            freshAutonomousSystem = apiResponse.data.results
-        } else {
-            apiResponse = null
-            freshAutonomousSystem = []
-        }
+        const apiResponse = await this.dispatchBatchChunks(cacheMisses, chunk =>
+            this.requestHandler.batchLookupAsns(chunk, options),
+        )
+        const freshAutonomousSystem = apiResponse
+            ? apiResponse.data.results
+            : []
 
         let j = 0
         let k = 0
@@ -403,19 +465,10 @@ export class IpregistryClient {
             IpInfo | LookupError
         >(ips.length)
 
-        let apiResponse: ApiResponse<BatchResult<IpInfo | LookupError>> | null
-        let freshIpInfo: (IpInfo | LookupError)[]
-
-        if (cacheMisses.length > 0) {
-            apiResponse = await this.requestHandler.batchLookupIps(
-                cacheMisses,
-                options,
-            )
-            freshIpInfo = apiResponse.data.results
-        } else {
-            apiResponse = null
-            freshIpInfo = []
-        }
+        const apiResponse = await this.dispatchBatchChunks(cacheMisses, chunk =>
+            this.requestHandler.batchLookupIps(chunk, options),
+        )
+        const freshIpInfo = apiResponse ? apiResponse.data.results : []
 
         let j = 0
         let k = 0
@@ -574,6 +627,113 @@ export class IpregistryClient {
         return this.cache
     }
 
+    /**
+     * Resolves batch values, splitting inputs larger than `maxBatchSize` into
+     * chunks dispatched with at most `batchConcurrency` requests in flight,
+     * and concatenating their results in order. When a chunk fails, the first
+     * error is thrown and no further chunk is dispatched (in-flight chunks
+     * complete but their results are discarded). Returns null when there is
+     * nothing to resolve.
+     */
+    private async dispatchBatchChunks<V, R>(
+        values: V[],
+        request: (chunk: V[]) => Promise<ApiResponse<BatchResult<R>>>,
+    ): Promise<ApiResponse<BatchResult<R>> | null> {
+        if (values.length === 0) {
+            return null
+        }
+
+        const { batchConcurrency, maxBatchSize } = this.config
+
+        if (values.length <= maxBatchSize) {
+            return await request(values)
+        }
+
+        const chunks: V[][] = []
+        for (let start = 0; start < values.length; start += maxBatchSize) {
+            chunks.push(values.slice(start, start + maxBatchSize))
+        }
+
+        const responses: ApiResponse<BatchResult<R>>[] = new Array(
+            chunks.length,
+        )
+        let nextChunk = 0
+        let firstError: unknown = null
+
+        const worker = async () => {
+            while (firstError === null) {
+                const index = nextChunk++
+                if (index >= chunks.length) {
+                    return
+                }
+                try {
+                    responses[index] = await request(chunks[index])
+                } catch (error) {
+                    firstError = firstError ?? error
+                    return
+                }
+            }
+        }
+
+        await Promise.all(
+            Array.from(
+                { length: Math.min(batchConcurrency, chunks.length) },
+                () => worker(),
+            ),
+        )
+
+        if (firstError !== null) {
+            throw firstError
+        }
+
+        const results: R[] = []
+        for (const response of responses) {
+            results.push(...response.data.results)
+        }
+
+        return {
+            credits: IpregistryClient.aggregateCredits(responses),
+            data: { results },
+            throttling: IpregistryClient.mostConstrainedThrottling(responses),
+        }
+    }
+
+    private static aggregateCredits(
+        responses: ApiResponse<unknown>[],
+    ): ApiResponseCredits {
+        const consumed = responses
+            .map(response => response.credits.consumed)
+            .filter((value): value is number => value !== null)
+        const remaining = responses
+            .map(response => response.credits.remaining)
+            .filter((value): value is number => value !== null)
+
+        return {
+            consumed: consumed.length
+                ? consumed.reduce((total, value) => total + value, 0)
+                : null,
+            remaining: remaining.length ? Math.min(...remaining) : null,
+        }
+    }
+
+    private static mostConstrainedThrottling(
+        responses: ApiResponse<unknown>[],
+    ): ApiResponseThrottling | null {
+        let result: ApiResponseThrottling | null = null
+
+        for (const response of responses) {
+            const throttling = response.throttling
+            if (
+                throttling &&
+                (!result || throttling.remaining < result.remaining)
+            ) {
+                result = throttling
+            }
+        }
+
+        return result
+    }
+
     private static buildCacheKey(
         primaryKey: string,
         options: IpregistryOption[],
diff --git a/test/batch.test.ts b/test/batch.test.ts
