qs_dart library

A faithful, cross‑port implementation of Node.js qs for Dart.

This package parses query strings into nested Dart structures and stringifies Dart structures back into query strings — matching the behavior of the canonical qs library where practical.

Highlights

  • RFC 3986 encoding by default, with RFC 1738 (+ for spaces) via Format.
  • Deep bracket notation for nested maps/lists (e.g. a[b][0]=c).
  • Multiple list styles via ListFormat (brackets, indices, repeat‑key, comma).
  • Deterministic key handling and duplicate‑key policy via Duplicates.
  • Charset sentinels and helpers via Sentinel.

Primary API

  • decode — Parse a query string into a Map<String, dynamic>.
  • encode — Stringify a Dart value (map/list/scalars) into a query string.

Tune behavior with DecodeOptions and EncodeOptions. See the repository README for complete examples and edge‑case notes.

Classes

DecodeOptions
Options that configure the output of QS.decode.
EncodeOptions
Options that configure the output of QS.encode.
QS
QS (Dart)
Undefined
Sentinel used to distinguish between a missing value and an explicit null.

Enums

Duplicates
Strategy to resolve repeated keys when decoding a query string.
Format
Output formatting strategies applied after RFC 3986 percent-encoding.
ListFormat
Shapes how list/array keys are written during query-string encoding.
Sentinel
Sentinels for signalling the character set of form/query submissions.

Extensions

UriExtension on Uri
Extensions that integrate qs_dart with Uri.

Functions

decode(dynamic input, [DecodeOptions? options]) → Map<String, dynamic>
Top-level convenience functions that mirror the JavaScript qs API.
encode(Object? object, [EncodeOptions? options]) → String
Encode a Dart object into a query string (convenience for QS.encode).

Typedefs

DateSerializer = String Function(DateTime date)
Hook to stringify a DateTime before it goes through the Encoder. Return a plain, unencoded string; the encoder will percent‑encode it.
Decoder = dynamic Function(String? value, {Encoding? charset})
Decoding options for QS.decode.
Encoder = String Function(dynamic value, {Encoding? charset, Format? format})
Encoders, sorters, and the immutable EncodeOptions used by qs_dart.
Formatter = String Function(String value)
Signature for a post–percent-encoding formatter that normalizes a single URI component string.
ListFormatGenerator = String Function(String prefix, [String? key])
Signature used by ListFormat to construct the key path for a single element in a list during encoding.
Sorter = int Function(dynamic a, dynamic b)
3‑way comparator to impose a deterministic order on keys (‑1/0/+1). Returning values outside that set will be signum‑clamped by callers.
SplitResult = ({bool exceeded, List<String> parts})
Decoder: query-string → nested Dart maps/lists (Node qs parity)