serde_qs

serde_qs is a Rust library that serializes to and deserializes from querystrings using Serde, extending serde_urlencoded with support for arbitrarily nested structures. It handles complex structs, maps, and arrays encoded with bracket notation (e.g. user[name]=John&user_ids[0]=1), matching the conventions used by the qs library for Node.js and by Ruby on Rails via Rack.

Beyond the core from_str and to_string helpers, serde_qs ships a configurable Config builder for nesting-depth limits, array formats, encoding modes, and duplicate-key behavior, plus first-class extractors for the Actix-web, Axum, and Warp web frameworks so query parameters bind directly into your typed structs.

What You Get

• Serde-native from_str / to_string helpers for querystring encoding and decoding
• Support for arbitrarily nested structs, maps, arrays, options, and enums
• A configurable Config builder for max depth, array format, encoding mode, and duplicate-key handling
• Built-in request extractors for the Actix-web, Axum, and Warp frameworks
• Compatibility with qs (JavaScript) and Rack (Ruby on Rails) bracket-notation conventions

Common Use Cases

• Parsing complex, nested query parameters in Rust web services
• Serializing typed request models into querystrings for outbound API calls
• Binding nested filter and pagination parameters directly into handler structs in Actix, Axum, or Warp
• Interoperating with front-end or Rails clients that already emit qs-style nested querystrings

Under The Hood

Architecture

The crate is organized around a Deserializer and Serializer pair (src/de.rs, src/ser.rs) coordinated by a Config layer (src/config.rs) that exposes builder-style options for max depth, array format, encoding mode, and duplicate-key behavior. Deserialization performs two passes over the input string: the first parses bracket-notation keys into an intermediate nested representation, and the second drives Serde’s data model to populate the target type, which is what allows arbitrarily ordered and nested inputs to be reconstructed. A dedicated Error enum (src/error.rs) carries position-aware parse failures, and framework adapters (src/actix.rs, src/axum.rs, src/warp.rs, src/web.rs) wrap the core deserializer as request extractors gated behind cargo features.

Tech Stack

Written in Rust on the 2024 edition (MSRV 1.85), the library depends on serde for the data model, percent-encoding for URL handling, and itoa/ryu for fast integer and float formatting. Optional features pull in indexmap for ordered maps and the actix-web (v3/v4), axum, and warp integrations, keeping the default build lean. Benchmarks use criterion behind a feature flag.

Code Quality

The repository is thoroughly tested, with dedicated suites for deserialization, serialization, round-tripping, regressions, and each framework integration (tests/test_deserialize.rs, test_serialize.rs, test_roundtrip.rs, test_regression.rs, test_actix.rs, test_axum.rs, test_warp.rs), plus chrono interop and insta snapshot testing. Error handling is explicit through a typed enum with proper source chaining, and the public surface is documented with runnable doc examples.

API Design

The public API mirrors serde_json’s familiar shape - top-level from_str, to_string, and Config-driven variants - so it is immediately recognizable to Serde users. The Config builder reads fluently (Config::new().max_depth(5).use_form_encoding(true)), framework extractors require almost no boilerplate, and the extensive module-level documentation walks through nesting, encoding modes, and flatten workarounds with concrete examples.