Express 4.x middleware for batched API requests.

Usage no npm install needed!

<script type="module">
  import expressBatchDeep from '';



Build Status NPM Downloads License


Express 4.x middleware that allows for batched API requests with nested field-value pairs. This began as a fork of express-batch by yarikos.

If you need to perform several different but simultaneous requests to one API endpoint, express-batch-deep allows you to combine them all together (in one querystring) and send only one request to the handler's route. This fork of express-batch by yarikos aims to add support for nested field-value pairs within querystrings.

The original express-batch module (and many like it) already leveraged req.query to separate the distinct batched API endpoints via field-value pairs. However, if any of those batched API endpoints required field-value pairs, it no longer worked. express-batch-deep, however, allows for you to pass in an optional "separator" value (in the test, | is used as an example), to indicate that the endpoints should not be separated by &, and that & should rather be considered an integral part of the endpoint's query string. In other words, whereas before /api/batch?one=/api/test?option1=true&option2=false&two=/api/test would be represented in the requests object as something like

  one: '/api/test?option1=true',
  option2: 'false',
  two: '/api/test'

it is now possible, by initializing the middleware with an optional parameter (e.g., app.use('/api/batchNested', expressBatchDeep(app, { separator: '|' }))), and changing the batch endpoint query string accordingly to /api/batch?one=/api/test?option1=true&option2=false|two=/api/test, it will now be represented as:

  one: '/api/test?option1=true&option2=false',
  two: '/api/test'

as it might be desired.

All responses are sent back as a JSON object with sections for each response.

Currently only routes for GET locations are supported.


// app init
var express = require("express");
var expressBatchDeep = require("express-batch-deep");
var app = express();

// mounting batch handler with optional separator for nested field-value pairs
var options = {
    separator: '|'
app.use("/api/batch", expressBatchDeep(app, options));

// mounting ordinary API endpoints
app.get("/api/constants/pi", function apiUserHandler(req, res) {

app.get("/api/users/:id", function apiUserHandler(req, res) {
        name: "Alice"

// easily handle batched requests with deep field-value pairs
app.get("/api/climate/", function apiClimateHandler(req, res) {
    var response = {
        sunny: false,
        warm: false

    // e.g., with a request path of 'api/batch?climate=/api/climate/?sunny=true&warm=true'
    if (req.query.sunny === 'true' && req.query.warm === 'true') {
        response.sunny = true;
        response.warm = true;

// starting app

This example in code.

With this example request to http://localhost:3000/api/batch?users=/api/users/49&pi=api/constants/pi&nonexistent=/not/existent/route will return:

    users: {
        result: {
            id: "49",
            name: "Alice"
        status: 200
    pi: {
        result: 3.141592653589793,
        status: 200
    nonexistent: {
        result: "Not Found",
        status: 404