Query String

The QS plugin serializes nested objects in query parameters using bracket notation, powered by the battle-tested qs package.

Installation

npm install @spoosh/plugin-qs

Usage

import { Spoosh } from "@spoosh/core";
import { qsPlugin } from "@spoosh/plugin-qs";

const client = new Spoosh<ApiSchema, Error>("/api").use([
  qsPlugin({ arrayFormat: "brackets" }),
]);

Example

// Query object
const query = {
  pagination: { limit: 10, offset: 0 },
  filters: { status: "active", tags: ["a", "b"] },
};

// Serialized result
// pagination[limit]=10&pagination[offset]=0&filters[status]=active&filters[tags][]=a,b

Per-Request Override

// Use comma-separated arrays for this request
injectRead((api) => api("items").GET({ query }), {
  qs: { arrayFormat: "comma" },
});

// Use dot notation for nested objects
injectRead((api) => api("search").GET({ query }), { qs: { allowDots: true } });

Options

Plugin Config

Accepts all qs stringify options. Common options:

Option	Type	Default	Description
`arrayFormat`	`"brackets" \| "indices" \| "repeat" \| "comma"`	`"brackets"`	How to serialize arrays
`allowDots`	`boolean`	`false`	Use dot notation instead of brackets
`skipNulls`	`boolean`	`true`	Skip null values in serialization

Per-Request Options

Same options as plugin config, nested under qs:

injectRead((api) => api("items").GET({ query }), {
  qs: { arrayFormat: "comma" },
});

Array Formats

brackets (default)

{
  tags: ["a", "b"];
}
// tags[]=a,b

indices

{
  tags: ["a", "b"];
}
// tags[0]=a&tags[1]=b

repeat

{
  tags: ["a", "b"];
}
// tags=a,b

comma

{
  tags: ["a", "b"];
}
// tags=a,b

Dot Notation

// allowDots: false (default)
{
  filters: {
    status: "active";
  }
}
// filters[status]=active

// allowDots: true
{
  filters: {
    status: "active";
  }
}
// filters.status=active

On this page