URLQueryItemCoder

Encoder & decoder for working with Codable types as URLQueryItems.

About

URLQueryItemCoder provides an implementation of Swift’s Encoder protocol suitable for encoding an Encodable type as an array of URLQueryItems, and an implementation of Swift’s Decoder protocol suitable for decoding a Decodable type from an array of URLQueryItems.

This allows us to lift URLQueryItem requirements into the type system (e.g. modeling an HTTP GET API).

Capabilities

URLQueryItemCoder is an exhaustive implementation with an exhaustive test suite.

Standard

All standard features expected by the protocols are supported.

• Single-value containers
• Keyed containers
• Unkeyed containers
• Nested containers
• Inheritance

Extra

All extra features offered by Swift’s JSON implementations are supported.

• Data special treatment
• Date special treatment
• Double & Float special treatment
• Key conversions
• Sorted keys

Usage

Encoding

URLQueryItemEncoder can be configured through its initializer or strategies and outputFormatting properties.

For example, given…

import URLQueryItemCoder

struct Interval: Codable {
    let start: Date
    let end: Date
}

struct GetPostsQuery: Codable {    
    let interval: Interval
    let userID: String
}

let interval = Interval(start: .now.addingTimeInterval(-1_000), end: .now)
let query = GetPostsQuery(interval: interval, userID: "123abc")

Then…

let encoder = URLQueryItemEncoder(dateStrategy: .secondsSince1970)
let queryItems = try! encoder.encode(query)
// [
//     URLQueryItem(name: "interval.end", value: "1681256918.240762"),
//     URLQueryItem(name: "interval.start", value: "1681255918.240762"),
//     URLQueryItem(name: "userID", value: "123abc"),
// ]

Decoding

URLQueryItemDecoder can be configured through its initializer or strategy property.

For example, given…

import URLQueryItemCoder

struct GetPostsQuery: Codable {
    struct Interval: Codable {
        let start: Date
        let end: Date
    }
    
    let interval: Interval
    let userID: String
}

let queryItems = [
    URLQueryItem(name: "interval.start", value: "1681255918.240762"),
    URLQueryItem(name: "interval.end", value: "1681256918.240762"),
    URLQueryItem(name: "userID", value: "123abc"),
]

Then…

let decoder = URLQueryItemDecoder(dateStrategy: .secondsSince1970)
let query = try! decoder.decode(GetPostsQuery.self, from: queryItems)
// GetPostsQuery(
//     interval: Interval(start: 1681255918.240762, end: 1681256918.240762),
//     userID: "123abc"
// )

Supported Platforms

• iOS
• macOS
• tvOS
• watchOS

Requirements

• Swift 5.7+

Installation

Swift Package Manager

dependencies: [
    .package(url: "https://github.com/kylehughes/URLQueryItemCoder.git", .upToNextMajor(from: "1.0.0")),
]

Documentation

Documentation is available on GitHub Pages.

Contributions

URLQueryItemCoder is not accepting source contributions at this time. Bug reports will be considered.

Author

Kyle Hughes

License

URLQueryItemCoder is available under the MIT license.

See LICENSE for details.