Verify Bun and Cloudflare Workers support in CI and document supported runtimes

Author: laurentpellegrino

.github/workflows/tests.yaml

@@ -31,3 +31,33 @@ jobs:
 
       - name: Build and test
         run: npm test
+
+  # Verifies the built library on non-Node runtimes: Bun and the Cloudflare
+  # Workers runtime (workerd, via Miniflare).
+  runtimes:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Use Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: 24.x
+
+      - name: Use Bun
+        uses: oven-sh/setup-bun@v2
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: Build
+        run: npm run build
+
+      - name: Smoke test on Node.js
+        run: npm run test:smoke
+
+      - name: Smoke test on Bun
+        run: bun test/smoke.mjs
+
+      - name: Smoke test on Cloudflare Workers (workerd)
+        run: npm run test:workers

README.md

@@ -110,6 +110,26 @@ Browser support:
 More samples are available in the [samples](https://github.com/ipregistry/ipregistry-javascript/tree/master/samples) 
 folder.
 
+## Supported runtimes
+
+The library has zero runtime dependencies and only relies on web-standard APIs
+(`fetch`, `AbortController`, timers), so it runs on any modern JavaScript
+runtime:
+
+- **Node.js 20+** — CommonJS and ESM, with bundled TypeScript declarations for
+  both. Verified continuously on Node 20, 22 and 24.
+- **Bun** — verified continuously.
+- **Cloudflare Workers** — verified continuously against the real Workers
+  runtime (workerd). Note that retry backoff waits count toward a Worker's
+  wall-clock duration; on latency-sensitive Workers consider
+  `withMaxRetries(1)` or a lower `withRetryInterval`.
+- **Deno** and other web-standard runtimes are expected to work through the
+  same APIs.
+- **Browsers** — through a bundler (the ESM build is tree-shakable) or a
+  `<script>` tag exposing the `ipregistry` global, as shown above. Use an
+  origin-restricted API key for browser deployments so your key cannot be
+  reused from other websites.
+
 ## Caching
 
 The Ipregistry client library has built-in support for in-memory caching. 

package.json

@@ -62,6 +62,8 @@
         "test": "node --import ./test/register.mjs --test test/*.test.ts",
         "pretest:integration": "npm run clean && npm run build",
         "test:integration": "node --loader ts-node/esm integration_test/ipregistry.ts",
+        "test:smoke": "node test/smoke.mjs",
+        "test:workers": "node test/workers/run.mjs",
         "tsdoc": "typedoc --out docs ./src/index.ts"
     },
     "author": "Ipregistry <support@ipregistry.co>",
@@ -72,6 +74,7 @@
         "chai": "^6.2.2",
         "eslint": "^10.6.0",
         "eslint-config-prettier": "^10.1.8",
+        "miniflare": "^4.20260701.0",
         "prettier": "^3.9.4",
         "terser": "^5.48.0",
         "ts-node": "^10.9.2",

test/smoke-scenario.mjs

@@ -0,0 +1,110 @@
+/*
+ * Copyright 2019 Ipregistry (https://ipregistry.co).
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+// The shared scenario behind the runtime smoke tests. Stubs globalThis.fetch
+// (restoring it afterwards) and drives lookups, caching, retries, and error
+// mapping through the built ESM bundle using only web-standard APIs.
+
+import {
+    ApiError,
+    InMemoryCache,
+    IpregistryClient,
+    IpregistryConfigBuilder,
+} from '../dist/index.mjs'
+
+function assertEqual(actual, expected, label) {
+    if (actual !== expected) {
+        throw new Error(`${label}: expected ${expected}, got ${actual}`)
+    }
+}
+
+function jsonResponse(body, status = 200, headers = {}) {
+    return new Response(JSON.stringify(body), {
+        status,
+        headers: { 'content-type': 'application/json', ...headers },
+    })
+}
+
+export async function runSmokeTest() {
+    const originalFetch = globalThis.fetch
+    let requests = 0
+
+    globalThis.fetch = async url => {
+        requests++
+        const path = new URL(url).pathname
+
+        if (path === '/1.2.3.4') {
+            return jsonResponse(
+                { ip: '1.2.3.4', location: { country: { code: 'AU' } } },
+                200,
+                { 'ipregistry-credits-consumed': '1' },
+            )
+        }
+
+        if (path === '/5.6.7.8') {
+            // Fail once with a 503 to exercise the retry path.
+            return requests % 2 === 0
+                ? jsonResponse({ ip: '5.6.7.8' })
+                : jsonResponse(
+                      { code: 'INTERNAL', message: 'oops', resolution: '-' },
+                      503,
+                  )
+        }
+
+        return jsonResponse(
+            {
+                code: 'INVALID_IP_ADDRESS',
+                message: 'Invalid IP',
+                resolution: '-',
+            },
+            400,
+        )
+    }
+
+    try {
+        const client = new IpregistryClient(
+            new IpregistryConfigBuilder('tryout').withRetryInterval(1).build(),
+            new InMemoryCache(),
+        )
+
+        // Plain lookup, response headers, and caching.
+        const first = await client.lookupIp('1.2.3.4')
+        assertEqual(first.data.location.country.code, 'AU', 'country code')
+        assertEqual(first.credits.consumed, 1, 'credits consumed')
+
+        const requestsBeforeCachedCall = requests
+        const second = await client.lookupIp('1.2.3.4')
+        assertEqual(second.data.ip, '1.2.3.4', 'cached ip')
+        assertEqual(requests, requestsBeforeCachedCall, 'cache hit')
+
+        // Retry on server error.
+        const retried = await client.lookupIp('5.6.7.8')
+        assertEqual(retried.data.ip, '5.6.7.8', 'retried ip')
+
+        // API error mapping.
+        try {
+            await client.lookupIp('not-an-ip')
+            throw new Error('expected lookupIp to throw an ApiError')
+        } catch (error) {
+            if (!(error instanceof ApiError)) {
+                throw error
+            }
+            assertEqual(error.code, 'INVALID_IP_ADDRESS', 'error code')
+        }
+    } finally {
+        globalThis.fetch = originalFetch
+    }
+}

test/smoke.mjs

@@ -0,0 +1,33 @@
+/*
+ * Copyright 2019 Ipregistry (https://ipregistry.co).
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+// Runtime smoke test: exercises the built library against a stubbed fetch so
+// it can run unchanged on any web-standard runtime (Node.js, Bun, Deno,
+// workerd). Plain JavaScript on purpose: no test framework, no TypeScript
+// loader. Exits non-zero (or rejects) on failure.
+
+import { runSmokeTest } from './smoke-scenario.mjs'
+
+try {
+    await runSmokeTest()
+    console.log('smoke test OK')
+} catch (error) {
+    console.error('smoke test FAILED:', error)
+    if (globalThis.process) {
+        globalThis.process.exit(1)
+    }
+    throw error
+}

test/workers/run.mjs

@@ -0,0 +1,61 @@
+/*
+ * Copyright 2019 Ipregistry (https://ipregistry.co).
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+// Runs the smoke scenario inside the real Cloudflare Workers runtime
+// (workerd, via Miniflare). The worker entry is bundled first with esbuild so
+// workerd receives a single self-contained module.
+
+import { build } from 'esbuild'
+import { Miniflare } from 'miniflare'
+import { mkdtemp, readFile, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+const outDir = await mkdtemp(join(tmpdir(), 'ipregistry-worker-smoke-'))
+const outFile = join(outDir, 'worker.mjs')
+
+try {
+    await build({
+        bundle: true,
+        entryPoints: [new URL('worker.mjs', import.meta.url).pathname],
+        format: 'esm',
+        outfile: outFile,
+        target: 'es2022',
+    })
+
+    const miniflare = new Miniflare({
+        compatibilityDate: '2026-01-01',
+        modules: true,
+        script: await readFile(outFile, 'utf-8'),
+    })
+
+    try {
+        const response = await miniflare.dispatchFetch('http://smoke.test/')
+        const body = await response.text()
+
+        if (response.status !== 200 || body !== 'OK') {
+            console.error(`workerd smoke test FAILED (${response.status}):`)
+            console.error(body)
+            process.exit(1)
+        }
+
+        console.log('workerd smoke test OK')
+    } finally {
+        await miniflare.dispose()
+    }
+} finally {
+    await rm(outDir, { force: true, recursive: true })
+}

test/workers/worker.mjs

@@ -0,0 +1,31 @@
+/*
+ * Copyright 2019 Ipregistry (https://ipregistry.co).
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+// Cloudflare Workers smoke test entry: runs the shared smoke scenario inside
+// workerd and reports the outcome over HTTP.
+
+import { runSmokeTest } from '../smoke-scenario.mjs'
+
+export default {
+    async fetch() {
+        try {
+            await runSmokeTest()
+            return new Response('OK')
+        } catch (error) {
+            return new Response(`${error?.stack ?? error}`, { status: 500 })
+        }
+    },
+}