{"_id":"@bullet.to/googleapis-batcher","name":"@bullet.to/googleapis-batcher","dist-tags":{"latest":"0.8.0"},"versions":{"0.8.0":{"name":"@bullet.to/googleapis-batcher","version":"0.8.0","description":"A library for batching Google APIs requests in Node.js","contributors":[{"name":"Jeremie Dayan","email":"dayanjeremie@gmail.com"}],"license":"MIT","homepage":"https://github.com/jrmdayn/googleapis-batcher","bugs":{"url":"https://github.com/jrmdayn/googleapis-batcher/issues"},"main":"./dist/index.js","module":"./dist/index.mjs","types":"./dist/index.d.ts","exports":{".":{"import":"./dist/index.mjs","require":"./dist/index.js","types":"./dist/index.d.ts"}},"scripts":{"format":"prettier --write .","lint":"eslint --ext .ts src/**","typecheck":"tsc --noEmit","build":"npm run lint && tsup src/index.ts --dts --format cjs,esm","test":"vitest"},"devDependencies":{"@types/debug":"^4.1.7","@types/node":"16.11.22","@typescript-eslint/eslint-plugin":"^5.36.2","@typescript-eslint/parser":"^5.36.2","envsafe":"^2.0.3","eslint":"^8.23.0","eslint-config-prettier":"^8.5.0","eslint-plugin-prettier":"^4.2.1","googleapis":"^110.0.0","open":"^8.4.0","prettier":"^2.7.1","tsup":"^6.2.3","typescript":"^4.8.2","vite":"^4.0.2","vitest":"^0.23.1"},"dependencies":{"dataloader":"^2.2.1","debug":"^4.3.4","handlebars":"^4.7.7","next-line":"^1.1.0","node-fetch":"2"},"peerDependencies":{"gaxios":">= 5","googleapis":">= 109"},"_id":"@bullet.to/googleapis-batcher@0.8.0","gitHead":"46af454d7fe57f6ec41431319b57f3f58ac53d0b","_nodeVersion":"22.14.0","_npmVersion":"11.3.0","dist":{"integrity":"sha512-rHyb9/xBSVArSEG9sNY1Fjx2bz3Q9zc+9lsvUnMCmOp2FzFY0PrbZKpepdbE8G3zVUwH5zTxOLlKKDNIiBV5EA==","shasum":"0a778cb6eeecf42c7e2c201ebe9ec6223c10f768","tarball":"https://registry.npmjs.org/@bullet.to/googleapis-batcher/-/googleapis-batcher-0.8.0.tgz","fileCount":6,"unpackedSize":30055,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCU4UlR+WvOKwdgt3tOxcx5DcXpk3tt5I41g9i+che9eAIhAJnXljy1WP43lDZE7qA6Vz860fvz0LHwLnx7yP1Bzs6r"}]},"_npmUser":{"name":"bullet.to","email":"hamish@bulletjournal.app"},"directories":{},"maintainers":[{"name":"bullet.to","email":"hamish@bulletjournal.app"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/googleapis-batcher_0.8.0_1759133852844_0.44274301057233"},"_hasShrinkwrap":false}},"time":{"created":"2025-09-29T08:17:32.741Z","0.8.0":"2025-09-29T08:17:33.017Z","modified":"2025-09-29T08:17:33.317Z"},"maintainers":[{"name":"bullet.to","email":"hamish@bulletjournal.app"}],"description":"A library for batching Google APIs requests in Node.js","homepage":"https://github.com/jrmdayn/googleapis-batcher","contributors":[{"name":"Jeremie Dayan","email":"dayanjeremie@gmail.com"}],"bugs":{"url":"https://github.com/jrmdayn/googleapis-batcher/issues"},"license":"MIT","readme":"\"Google\n\n# Batching library for Google APIs Node.js Client\n\n

\n \n \"\"\n \n \n \n \n \n \n \n \n \"\"\n \n \n \"\"\n \n \n \"\"\n \n

\n\n\nNode.js library for batching multiple requests made with the official [Google APIs Node.js client](https://github.com/googleapis/google-api-nodejs-client)\n\n## Getting started\n\nFirst, install the library using yarn/npm/pnpm:\n```bash\nyarn add @jrmdayn/googleapis-batcher\n```\n\nThen instantiate and use the `batchFetchImplementation`:\n\n```js\nimport { google } from 'googleapis'\nimport { batchFetchImplementation } from '@jrmdayn/googleapis-batcher'\n\nconst fetchImpl = batchFetchImplementation()\n\nconst client = google.calendar({\n version: 'v3',\n fetchImplementation: fetchImpl,\n})\n\n// The 3 requests will be batched together\nconst [list, get, patch] = await Promise.all([\n calendarClient.events.list({ calendarId: 'john@gmail.com' }),\n calendarClient.events.get({\n calendarId: 'john@gmail.com',\n eventId: 'xyz123'\n }),\n calendarClient.events.patch({\n calendarId: 'john@gmail.com',\n eventId: 'xyz456',\n requestBody: { colorId: '1' }\n })\n ])\n\n```\n\n## Options\n\n### maxBatchSize\nControls the maximum number of requests to batch together in one HTTP request.\n\n```js\n// limit the number of batched requests to 50\nconst fetchImpl = batchFetchImplementation({ maxBatchSize: 50 })\n```\n\n_Note: Google limits the number of batched requests on a per API basis. For example, for the Calendar API it is 50 requests and for the People API it is 1000._\n\n### batchWindowMs\nControls the size of the time window (in milliseconds) that will be used to batch requests together. By default, all requests made in the same tick will be batched together. See Dataloader [documentation](https://github.com/graphql/dataloader/tree/main#batch-scheduling) for more on this.\n\n```js\n// batch all requests made in a 30ms window\nconst fetchImpl = batchFetchImplementation({ batchWindowMs: 30 })\n```\n\n### signal\nDefines a user controlled signal that is used to manually trigger a batch request.\n\n```js\nconst signal = makeBatchSchedulerSignal();\nconst fetchImpl = batchFetchImplementation({ signal })\n\nconst client = google.calendar({\n version: 'v3',\n fetchImplementation: fetchImpl,\n})\n\nconst pList = calendarClient.events.list({ calendarId: 'john@gmail.com' }),\nconst pGet = calendarClient.events.get({\n calendarId: 'john@gmail.com',\n eventId: 'xyz123'\n}),\nconst pPatch = calendarClient.events.patch({\n calendarId: 'john@gmail.com',\n eventId: 'xyz456',\n requestBody: { colorId: '1' }\n})\n\n...\n\nsignal.schedule();\n\n```\n\n## Known limitations\n\nThe max batch size varies per Google API. For example, it is set to 50 for Calendar API and to 1000 for People API. Read the docs to find out and configure the options accordingly.\n\n\nBatching is homogeneous, so you cannot batch Calendar API and People API requests together. Instead, you must make 2 seperate batching calls, as there are 2 separate batching endpoints. Concretly what it means is that you should always provide a `fetchImplementation` at the client API level, not at the global Google options level:\n\n```js\nconst fetchImpl = batchFetchImplementation()\n\nconst calendarClient = google.calendar({\n version: 'v3',\n fetchImplementation: fetchImpl,\n})\n\nconst peopleClient = google.people({\n version: 'v1',\n fetchImplementation: fetchImpl,\n})\n\n// This will raise an error\nawait Promise.all([\n calendarClient.events.list(),\n peopleClient.people.get()\n ])\n```\n\nDo this instead:\n\n```js\nconst fetchImpl1 = batchFetchImplementation()\nconst fetchImpl2 = batchFetchImplementation()\n\nconst calendarClient = google.calendar({\n version: 'v3',\n fetchImplementation: fetchImpl1,\n})\n\nconst peopleClient = google.people({\n version: 'v1',\n fetchImplementation: fetchImpl2,\n})\n\nawait Promise.all([\n calendarClient.events.list(),\n peopleClient.people.get()\n ])\n```\n\n\n## Motivation\n\nOn August 12, 2020 Google deprecated its global batching endpoints (blog article [here](https://developers.googleblog.com/2018/03/discontinuing-support-for-json-rpc-and.html)). Going forward, it is recommended to use API specific batch endpoints for batching homogeneous requests together. Unfortunately, the official [Google APIs Node.js client](https://github.com/googleapis/google-api-nodejs-client) does not support batching requests together out of the box. The task of composing a batched request and parsing the batch response is left to the developer.\n\n[Here](https://developers.google.com/calendar/api/guides/batch) is a link to the official guide for doing so with the Calendar API. As you can see, the task consists in handcrafting a `multipart/mixed` HTTP request composed of multiple raw HTTP requests (one per request), and then parsing a `multipart/mixed` response body composed of multiple raw HTTP responses (one per response).\n\nAt this point, I see at least 2 reasons as to why developers would not batch Google APIs requests:\n1. There is no easy way to easily generate the individual raw HTTP requests (url + headers + JSON body) from the official Node.js client. The only solution would be to read the developers doc and craft the request by hand..\n1. The task of handcrafting/parsing a `multipart/mixed` HTTP request/response seems daunting and error prone\n\n## Solution\n\nI decided to write this library when I first encountered the need for batching Google APIs requests in Node.js, so that other developers would not have to face the task of writing and parsing `multipart/mixed` HTTP requests. The key of the solution consists of providing your own `fetch` implementation to the API client you are using. Google exposes a `fetchImplementation` parameter in the options (probably for testing purpose) that we can easily override to intercept requests and group them together. For grouping the requests together, we use [Dataloader](https://github.com/graphql/dataloader), which can be configured to batch all requests made in one tick, or in a certain time window, or until an external signal is fired.\n\nFrom a developer's point of vue, you do not need to worry about handcrafting the individual raw HTTP requests. You simply use the official Google APIs Node.js client as normal, and the fetch implementation will automatically batch the requests for you.\n\n","readmeFilename":"README.md","_rev":"1-19bfb529ca2b026bcb74de97f7283459"}