Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/vapor/multipart-kit
🏞 Parses and serializes multipart-encoded data with Codable support.
https://github.com/vapor/multipart-kit
codable formdata multipart server-side-swift swift vapor
Last synced: about 1 month ago
JSON representation
🏞 Parses and serializes multipart-encoded data with Codable support.
- Host: GitHub
- URL: https://github.com/vapor/multipart-kit
- Owner: vapor
- License: mit
- Created: 2016-12-20T23:11:25.000Z (over 7 years ago)
- Default Branch: main
- Last Pushed: 2024-05-23T20:39:41.000Z (4 months ago)
- Last Synced: 2024-07-05T13:46:04.345Z (2 months ago)
- Topics: codable, formdata, multipart, server-side-swift, swift, vapor
- Language: Swift
- Homepage:
- Size: 230 KB
- Stars: 130
- Watchers: 26
- Forks: 39
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
🏞 Multipart parser and serializer with `Codable` support for Multipart Form Data.
### Installation
Use the SPM string to easily include the dependency in your `Package.swift` file.
Add MultipartKit to your package dependencies:
```swift
dependencies: [
// ...
.package(url: "https://github.com/vapor/multipart-kit.git", from: "4.0.0"),
]
```
Add MultipartKit to your target's dependencies:
```swift
targets: [
.target(name: "MyAppTarget", dependencies: [
// ...
.product(name: "MultipartKit", package: "multipart-kit"),
])
]
```
### Supported Platforms
MultipartKit supports the following platforms:
- All Linux distributions supported by Swift 5.7+
- macOS 10.15+
## Overview
MultipartKit is a multipart parsing and serializing library. It provides `Codable` support for the special case of the `multipart/form-data` media type through a `FormDataEncoder` and `FormDataDecoder`. The parser delivers its output as it is parsed through callbacks suitable for streaming.
### Multipart Form Data
Let's define a `Codable` type and a choose a boundary used to separate the multipart parts.
```swift
struct User: Codable {
let name: String
let email: String
}
let user = User(name: "Ed", email: "[email protected]")
let boundary = "abc123"
```
We can encode this instance of a our type using a `FormDataEncoder`.
```swift
let encoded = try FormDataEncoder().encode(foo, boundary: boundary)
```
The output looks then looks like this.
```
--abc123
Content-Disposition: form-data; name="name"
Ed
--abc123
Content-Disposition: form-data; name="email"
[email protected]
--abc123--
```
In order to _decode_ this message we feed this output and the same boundary to a `FormDataDecoder` and we get back an identical instance to the one we started with.
```swift
let decoded = try FormDataDecoder().decode(User.self, from: encoded, boundary: boundary)
```
### A note on `null`
As there is no standard defined for how to represent `null` in Multipart (unlike, for instance, JSON), FormDataEncoder and FormDataDecoder do not support encoding or decoding `null` respectively.
### Nesting and Collections
Nested structures can be represented by naming the parts such that they describe a path using square brackets to denote contained properties or elements in a collection. The following example shows what that looks like in practice.
```swift
struct Nested: Encodable {
let tag: String
let flag: Bool
let nested: [Nested]
}
let boundary = "abc123"
let nested = Nested(tag: "a", flag: true, nested: [Nested(tag: "b", flag: false, nested: [])])
let encoded = try FormDataEncoder().encode(nested, boundary: boundary)
```
This results in the content below.
```
--abc123
Content-Disposition: form-data; name="tag"
a
--abc123
Content-Disposition: form-data; name="flag"
true
--abc123
Content-Disposition: form-data; name="nested[0][tag]"
b
--abc123
Content-Disposition: form-data; name="nested[0][flag]"
false
--abc123--
```
Note that the array elements always include the index (as opposed to just `[]`) in order to support complex nesting.