This fork of Kyle Hughes's URLQueryItemCoder adds repeated query-key encoding for APIs such as ATProto and guards Combine integration on platforms where it is available. The original MIT license and attribution are preserved.

struct Query: Encodable { var ids: [String] }
let items = try URLQueryItemEncoder(arrayStrategy: .repeated)
    .encode(Query(ids: ["first", "second"]))
// ids=first&ids=second

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.

Extra #

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

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://tangled.org/woody.fm/swift-urlqueryitem-coder", .upToNextMajor(from: "1.1.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.

Clone this repository

URLQueryItemCoder #