swift-form-coding

A convenience umbrella package that re-exports all form coding functionality for Swift.

Overview

This package provides a single import for all form data encoding/decoding needs in Swift. It re-exports two independent packages:

• swift-url-form-coding - URL form encoding/decoding (application/x-www-form-urlencoded)
• swift-multipart-form-coding - Multipart form data with file uploads (multipart/form-data)

Installation

Add this package to your Package.swift:

dependencies: [
    .package(url: "https://github.com/coenttb/swift-form-coding", from: "0.1.0")
]

Then add the product to your target:

.target(
    name: "YourTarget",
    dependencies: [
        .product(name: "FormCoding", package: "swift-form-coding")
    ]
)

Supported Platforms

• macOS 14.0+
• iOS 17.0+
• tvOS 17.0+
• watchOS 10.0+
• Swift 6.1+

Usage

URL Form Encoding

import FormCoding

struct LoginForm: Codable {
    let username: String
    let password: String
}

let encoder = HTML.Form.Coder.Encoder()
let form = LoginForm(username: "john", password: "secret")
let formData = try encoder.encode(form)
// Result: "username=john&password=secret"

Multipart Form Data

Build a multipart/form-data body (RFC 7578) from the WHATWG HTML form-data model, encode it, and derive the Content-Type header for your HTTP request.

import MultipartFormCoding
import WHATWG_HTML_FormData   // Form.Data.Entry.List, Form.Data.File
import RFC_2046               // RFC_2046.Multipart

// Build the form-data set: a text field plus a file field
var form = Form.Data.Entry.List()
form.append(name: "username", value: "alice")
form.append(
    name: "avatar",
    file: Form.Data.File(
        name: "avatar.png",
        type: "image/png",
        body: pngBytes           // [UInt8]
    )
)

// Encode as multipart/form-data (RFC 7578) with a generated boundary
let boundary = RFC_2046.Boundary.random()
let multipart = try form.multipart(boundary: boundary)

// Content-Type header (with the boundary) for the request
let contentType = multipart.contentType
// contentType.headerValue == "multipart/form-data; boundary=…"

When to Use Each Package

Use URL Form Coding when:

• Submitting simple form data without files
• Working with REST APIs that expect application/x-www-form-urlencoded
• You need PHP/Rails-style bracket notation for arrays

Use Multipart Form Coding when:

• Uploading files (images, documents, etc.)
• Mixing file uploads with form fields
• You need per-field content-type specification

Individual Packages

If you only need one type of form coding, import the specific package instead:

// Just URL form encoding
dependencies: [
    .package(url: "https://github.com/coenttb/swift-url-form-coding", from: "0.1.0")
]

// Just multipart file uploads
dependencies: [
    .package(url: "https://github.com/coenttb/swift-multipart-form-coding", from: "0.1.0")
]

URLRouting Integration

Both underlying packages support optional URLRouting integration via Swift Package Manager traits:

// In your Package.swift
dependencies: [
    .package(
        url: "https://github.com/coenttb/swift-form-coding",
        from: "0.1.0"
    )
]

When the URLRouting trait is enabled:

• HTML.Form.Coder.Conversion<T> and Multipart.Conversion<T> conform to URLRouting.Conversion
• URLRouting is re-exported for convenient access
• Convenience methods like .form(_:) and .multipart(_:) are available

Architecture

This is a minimal umbrella package with no code of its own. It simply re-exports:

• URLFormCoding - URL-encoded form data support
• MultipartFormCoding - Multipart form data with file uploads
• URLRouting - Conditionally exported when URLRouting trait is enabled

The underlying packages are completely independent - they share no dependencies and can be used separately.

Features

URL Form Coding

• ✅ Codable integration for form data
• ✅ Multiple array encoding strategies (accumulate, brackets, indexed)
• ✅ Custom date/data encoding strategies
• ✅ URLRouting integration
• ✅ RFC 2388 compliant

Multipart Form Coding

• ✅ Secure file upload validation
• ✅ Magic number (file signature) checking
• ✅ Configurable size limits
• ✅ Built-in file type support (images, documents, etc.)
• ✅ RFC 2045/2046/7578 compliant
• ✅ URLRouting integration

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Related Packages

• swift-url-form-coding - URL form encoding/decoding
• swift-multipart-form-coding - Multipart form data with file uploads