Decoder typedef

Decoder = dynamic Function(String? value, {Encoding? charset})

Decoding options for QS.decode.

This mirrors the behavior of the reference qs library and provides a few guard rails against untrusted input (parameter count, nesting depth, list index limits). The defaults aim to be safe and predictable while matching the semantics used across the ports in this repository.

Highlights

  • Dot notation: set allowDots to treat a.b=c like {a: {b: "c"}}. If you explicitly request dot decoding in keys via decodeDotInKeys, allowDots is implied and will be treated as true.
  • Charset handling: charset selects UTF‑8 or Latin‑1 decoding. When charsetSentinel is true, a leading utf8=✓ token (in either UTF‑8 or Latin‑1 form) can override charset as a compatibility escape hatch.
  • Limits: parameterLimit, depth, and listLimit are DoS guards. If you want hard failures instead of soft limiting, enable throwOnLimitExceeded and/or strictDepth.
  • Duplicates: use duplicates to pick a strategy when the same key is present multiple times in the input.

See also: the options types in other ports for parity, and the individual doc comments below for precise semantics. Signature for a custom scalar decoder used by DecodeOptions.

The function receives a single raw token (already split from the query) and an optional charset hint (either utf8 or latin1). The charset reflects the effective charset after any sentinel (utf8=✓) handling.

Return the decoded value for the token — typically a String, num, bool, or null. If no decoder is provided, the library falls back to Utils.decode.

Notes

  • This hook runs on individual tokens only; do not parse brackets, delimiters, or build containers here.
  • If you throw from this function, the error will surface out of QS.decode.

Implementation

/// Signature for a custom scalar decoder used by [DecodeOptions].
///
/// The function receives a single raw token (already split from the query)
/// and an optional [charset] hint (either [utf8] or [latin1]). The [charset]
/// reflects the *effective* charset after any sentinel (`utf8=✓`) handling.
///
/// Return the decoded value for the token — typically a `String`, `num`,
/// `bool`, or `null`. If no decoder is provided, the library falls back to
/// [Utils.decode].
///
/// Notes
/// - This hook runs on **individual tokens only**; do not parse brackets,
///   delimiters, or build containers here.
/// - If you throw from this function, the error will surface out of
///   [QS.decode].
typedef Decoder = dynamic Function(String? value, {Encoding? charset});