{"id":19932715,"url":"https://github.com/mixmaxhq/batchelor","last_synced_at":"2025-05-03T11:32:38.611Z","repository":{"id":27389168,"uuid":"30865312","full_name":"mixmaxhq/batchelor","owner":"mixmaxhq","description":"A lovely little Node.js module to perform batch requests with the Google REST API","archived":false,"fork":false,"pushed_at":"2023-11-21T07:57:38.000Z","size":824,"stargazers_count":67,"open_issues_count":3,"forks_count":11,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-04-24T10:03:48.344Z","etag":null,"topics":["batch-request","batchelor","google-api","javascript","node-module","nodejs","npm-package"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/batchelor","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"tvrcgo/weixin-pay","license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mixmaxhq.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-02-16T11:26:52.000Z","updated_at":"2024-03-27T00:06:08.000Z","dependencies_parsed_at":"2022-08-15T04:30:39.037Z","dependency_job_id":"88296108-2164-43e2-828c-31f20a854329","html_url":"https://github.com/mixmaxhq/batchelor","commit_stats":{"total_commits":65,"total_committers":13,"mean_commits":5.0,"dds":0.6461538461538461,"last_synced_commit":"b8cb8290e6307079dfa1d5adf2ffde0c7487e1c2"},"previous_names":["wapisasa/batchelor"],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mixmaxhq%2Fbatchelor","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mixmaxhq%2Fbatchelor/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mixmaxhq%2Fbatchelor/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mixmaxhq%2Fbatchelor/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mixmaxhq","download_url":"https://codeload.github.com/mixmaxhq/batchelor/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252184967,"owners_count":21708057,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["batch-request","batchelor","google-api","javascript","node-module","nodejs","npm-package"],"created_at":"2024-11-12T23:11:20.345Z","updated_at":"2025-05-03T11:32:37.918Z","avatar_url":"https://github.com/mixmaxhq.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Batchelor\nA lovely little Node.js module to perform batch requests with the Google REST API. Simply does it.\n\n## Google API Batch Requests\nThis is a project to solve a need for a missing feature in the wonderfully epic and useful [google/google-api-nodejs-client](https://github.com/google/google-api-nodejs-client). Currently, this cannot be used to post media and has not been tested with posting anything but JSON.\n\nIn theory this library could be used with other APIs, but has only been tested with Google's APIs as that's what we need it for.\n\nFeel free to get involved in development.\n\n## Upgrading to 2.0\n\n`batch.run(...)` now takes a node style callback, with an error as the first parameter and the result as the second.\n\n**INCORRECT** (old, v1.0-style):\n\n``` node\nbatch.run(function(result){});\n```\n\n**CORRECT** (new, v2.0-style):\n\n``` node\nbatch.run(function(err, result){});\n```\n\n## Upgrading to 1.0\n\nThe API was changed in 1.0 to move from a singleton instance to a constructor. So before where you used `Batchelor` directly:\n\n``` node\nvar Batchelor = require('batchelor')\nBatchelor.init(...)\nBatchelor.add(...)\nBatchelor.run(...)\n```\n\nYou now need to create an instance of Batchelor:\n\n``` node\nvar Batchelor = require('batchelor')\nvar batch = new Batchelor(...)\nbatch.add(...)\nbatch.run(...)\n```\n\nSee \u003chttps://github.com/wapisasa/batchelor/issues/4\u003e for why this change was made.\n\n## Installation\n\nThis library has also been distributed on `npm`. Install it with the following command:\n\n``` sh\n$ npm install batchelor --save\n```\n\n## How to Use\n#### GET Requests\n``` node\nvar Batchelor = require('batchelor');\n```\nOnce the module has been included, we initialise it with all our default options:\n``` node\nvar batch = new Batchelor({\n\t// Any batch uri endpoint in the form: https://www.googleapis.com/batch/\u003capi\u003e/\u003cversion\u003e\n\t'uri':'https://www.googleapis.com/batch/gmail/v1/',\n\t'method':'POST',\n\t'auth': {\n\t\t'bearer': [... Google API Token ...]\n\t},\n\t'headers': {\n\t\t'Content-Type': 'multipart/mixed'\n\t}\n});\n```\nWe can then start adding requests to our batch. This can be done 2 ways:\n\nAs a one-off object:\n``` node\nbatch.add({\n\t'method':'GET',\n\t'path':'/gmail/v1/users/me/messages/123'\n})\n```\nOr an Array of objects:\n``` node\nbatch.add([\n\t{\n\t\t'method':'GET',\n\t\t'path':'/gmail/v1/users/me/messages/123'\n\t},\n\t{\n\t\t'method':'GET',\n\t\t'path':'/gmail/v1/users/me/messages/456'\n\t},\n\t{\n\t\t'method':'GET',\n\t\t'path':/gmail/v1/users/me/messages/789'\n\t}\n]);\n```\nOnce you have added all of the requests you need, call `.run()`:\n``` node\nbatch.run(function(err, response){\n\tif (err){\n\t\tconsole.log(\"Error: \" + err.toString());\n\t} else {\n\t\tres.json(response);\n\t}\n});\n```\n#### POST Requests\nThe above examples show `GET` requests. To perform a `POST` requires a few more settings:\n``` node\nbatch.add({\n\t'method':'POST',\n\t'path':'/gmail/v1/users/me/messages/',\n\t'parameters':{\n\t\t'Content-Type':'application/json;',\n\t\t'body':{'object':{'originalContent': 'A wonderful batch post!'},'access': {'items': [{'type': 'domain'}],'domainRestricted': true}}\n\t}\n});\n```\n#### Callbacks\nBy default, all responses are returned through the callback function in the `batch.run()` call. Alternatively, a callback can be supplied for each individual calls:\n``` node\nbatch.add({\n\t'method':'POST',\n\t'path':'/gmail/v1/users/me/messages/',\n\t'parameters':{\n\t\t'Content-Type':'application/json;',\n\t\t'body':{'object':{'originalContent': 'Another wonderful batch post with callback!'},'access': {'items': [{'type': 'domain'}],'domainRestricted': true}}\n\t},\n\t'callback':function(response){\n\t\tconsole.log(response);\n\t}\n});\n```\n#### Request and Response IDs\nThe module will assign a request a randomly generated unique `Content-ID` by default, but this can be supplied as part of the options to supply `batch.add()`:\n``` node\nbatch.add({\n\t'method':'GET',\n\t'path':'/gmail/v1/users/me/messages/123',\n\t'requestId':'Batch_UniqueID_1'\n})\n```\n#### A Couple of Little Gifts\n###### Method Chaining\nAll methods return the `Batchelor` instance. So you can chain calls together.\n\n``` node\nbatch.add([\n\t...\n]).run(function(err, data){\n\t...\n});\n```\n###### Data Pass-through\nWhen passing options to the `.add()` you can include an Object called `extend`. In the case of providing a callback, this will be passed back as a second parameter. When using the default callback on the `.run()` call, an array of all data passed through will be added as a second parameter with the requestId as the key:\n``` node\nbatch.add({\n\t...\n\t'extend':{\n\t\t...\n\t},\n\t'callback':function(response, extendObj){\n\t\tconsole.log(response, extendObj);\n\t}\n});\n```\nThis could be required, for example, when making multiple requests with different Auth data and then needing to make further requests with the same Auth data.\n\n###### Resetting and Re-using\nOnce Batchelor has been run, there are certain use-cases for running futher batch requests on response. This requires the variables in the instance to be reset. This can be done using the `.reset()` call:\n``` node\nbatch.run(function(err, response){\n\n\t//\tReset Batchelor for further use\n\tbatch.reset();\n\t...\n\n});\n```\n\n## To Do List-ish\nThese might get done if we end up needing them/have time:\n* Limit requests per batch request\n* Handle Media in API calls (no need for it here, feel free to write it)\n\n## Release History\n\n* 2.0.2 Added [error handler](https://github.com/wapisasa/batchelor/pull/15) and [made `headers` optional](https://github.com/wapisasa/batchelor/pull/17)\n* 2.0.1 Include response status code in error\n* 2.0.0 Bug Fixes and Improvements\n* 1.0.0 The API was changed in 1.0 to move from a singleton instance to a constructor (Thanks again to [@bradvogel](https://github.com/bradvogel))\n* 0.0.8 Added support for DELETE requests (Thanks to [@bradvogel](https://github.com/bradvogel))\n* 0.0.7 Reset function for when you are using batchelor more than once in a script (ability for nested requests too)\n* 0.0.6 Bug fixes introduced in the last update and clean up was happening too soon. Moved it.\n* 0.0.5 Added the ability to passthrough specific information from the `.add()` options to the response object\n* 0.0.4 Authorization can now be set on each request (currently Bearer [...] only)\n* 0.0.3 More bug fixes: New contentId for every request\n* 0.0.2 Bug fixes\n* 0.0.1 Initial release\n\n## Acknowledgement\nBuilt on the clock by [@jamesmhaley](https://github.com/jamesmhaley) as an internal project of [wapisasa C.I.C.](http://www.wapisasa.com)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmixmaxhq%2Fbatchelor","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmixmaxhq%2Fbatchelor","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmixmaxhq%2Fbatchelor/lists"}