@spoosh/plugin-qs

Query string serialization plugin for Spoosh with nested object support.

Documentation · Requirements: TypeScript >= 5.0 · Peer Dependencies: @spoosh/core

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" }),
]);

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

useRead((api) => api.items.$get({ query }));
// Result: pagination[limit]=10&pagination[offset]=0&filters[status]=active&filters[tags][]=a,b

Features

• ✅ Nested object serialization with bracket notation
• ✅ Multiple array formats (brackets, indices, repeat, comma)
• ✅ Dot notation support for nested objects
• ✅ Automatic null value skipping
• ✅ Per-request configuration override
• ✅ Powered by battle-tested qs package

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

Override plugin defaults for specific requests:

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

// Use dot notation for nested objects
useRead((api) => api.search.$get({ query }), { qs: { allowDots: true } });

// Include null values for this request
useRead((api) => api.data.$get({ query }), { qs: { skipNulls: false } });

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