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.