Decoder typedef
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 treata.b=c
like{a: {b: "c"}}
. If you explicitly request dot decoding in keys viadecodeDotInKeys
,allowDots
is implied and will be treated astrue
. - Charset handling:
charset
selects UTF‑8 or Latin‑1 decoding. WhencharsetSentinel
istrue
, a leadingutf8=✓
token (in either UTF‑8 or Latin‑1 form) can overridecharset
as a compatibility escape hatch. - Limits:
parameterLimit
,depth
, andlistLimit
are DoS guards. If you want hard failures instead of soft limiting, enablethrowOnLimitExceeded
and/orstrictDepth
. - 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});