Registry / api / graphql-query-batcher

graphql-query-batcher

library1.0.1jsnpmunverified

GraphQL Query Batcher is a minimal (<700 bytes) JavaScript library that batches multiple GraphQL queries into a single HTTP request, reducing network overhead. Version 1.0.1 is current (unreleased yet, based on semver). It works by collecting queries within a configurable batch interval (default 6ms) and sending them together to a GraphQL endpoint that supports batching (e.g., Apollo Server). Key differentiators: extremely lightweight, zero dependencies, simple API with fetch and forceFetch methods. Unlike Apollo's batch link, this is standalone and framework-agnostic. Requires the server to accept an array of queries and return an array of results.

api

npm install graphql-query-batcher

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · GRAPHQL-QUERY-BATC

graphql-query-batcher

apijavascriptv1.0.1

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

QueryBatcher

✓ import { QueryBatcher } from 'graphql-query-batcher'

✗ const { QueryBatcher } = require('graphql-query-batcher')

Package is ESM-only. Named export only, no default export.

QueryBatcher

✓ const { QueryBatcher } = await import('graphql-query-batcher')

✗ const QueryBatcher = require('graphql-query-batcher')

Dynamic import works in Node ESM and browsers.

Options

✓ import type { Options } from 'graphql-query-batcher'

✗ import { Options } from 'graphql-query-batcher'

Options is only a TypeScript type; not exported as runtime value.

Creates a batcher client with custom fetcher, sends batched queries, and shows both fetch and forceFetch methods.

import { QueryBatcher } from 'graphql-query-batcher'; const fetcher = (batchedQuery) => fetch('https://api.example.com/graphql', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(batchedQuery), }).then(res => res.json()); const client = new QueryBatcher(fetcher, { batchInterval: 10, maxBatchSize: 5 }); client .fetch(`query getUser($id: ID!) { user(id: $id) { name } }`, { id: '1' }) .then(data => console.log(data)); client .forceFetch(`query getPost($id: ID!) { post(id: $id) { title } }`, { id: '2' }) .then(data => console.log(data));

Debug

Known issues

gotchaServer must support batching: endpoint must accept array of queries and return array of results (e.g., Apollo Server with batch plugin).

fix

Ensure GraphQL server supports batching, or set shouldBatch: false to send individual requests.

affects: >=1.0.0

gotchaforceFetch does not batch the request; it sends immediately. Use it when you need a fresh result outside the batch window.

fix

Prefer fetch() for normal usage; only use forceFetch when you need to bypass batching.

affects: >=1.0.0

gotchabatchInterval default is 6ms, which may be too short for high-latency connections; adjust based on your use case.

fix

Set a larger batchInterval (e.g., 50ms) to allow more queries to accumulate.

affects: >=1.0.0

gotchamaxBatchSize of 0 (default) means no limit; if you set a limit, requests beyond that will be sent in separate batches.

fix

Set maxBatchSize to a reasonable number like 10 to avoid overly large payloads.

affects: >=1.0.0

Errors

Common errors & fixes

Uncaught TypeError: Intermediate value (first) is not a function

Missing `await` when importing if using dynamic import incorrectly, or fetcher is not a function.

fix

Ensure the fetcher parameter is a function that takes a batched query and returns a promise of the parsed JSON response.

Cannot read properties of undefined (reading 'length')

Server returned an unexpected format (not an array) when batching is enabled but server doesn't support it.

fix

Disable batching (shouldBatch: false) or configure server to return array of results.

ReferenceError: fetch is not defined

Running in an environment without global fetch (e.g., older Node.js).

fix

Use a fetch polyfill like 'node-fetch' or import from 'node-fetch' and pass as the fetcher argument.

Upgrade

Version history

1.0.1latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

50 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/nicksrandall/graphql-query-batcher ↗

packagegraphql-query-batcher ↗

homepagehttps://github.com/nicksrandall/graphql-query-batcher ↗