https://github.com/crichez/swift-bison
BSON (Binary JSON) reading and writing in Swift
https://github.com/crichez/swift-bison
bson ios ipados linux macos mongodb serialization swift tvos watchos windows
Last synced: 8 months ago
JSON representation
BSON (Binary JSON) reading and writing in Swift
- Host: GitHub
- URL: https://github.com/crichez/swift-bison
- Owner: crichez
- License: apache-2.0
- Archived: true
- Created: 2022-03-25T21:58:04.000Z (over 4 years ago)
- Default Branch: main
- Last Pushed: 2022-08-02T13:51:11.000Z (almost 4 years ago)
- Last Synced: 2025-01-23T05:14:16.701Z (over 1 year ago)
- Topics: bson, ios, ipados, linux, macos, mongodb, serialization, swift, tvos, watchos, windows
- Language: Swift
- Homepage:
- Size: 420 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: .github/CONTRIBUTING.md
- License: LICENSE.md
- Code of conduct: .github/CODE_OF_CONDUCT.md
- Security: .github/SECURITY.md
Awesome Lists containing this project
README
# 🦬 Bison
BSON (binary JSON) encoding and decoding in Swift.
## Overview
The swift-bison package features **two flavors** of BSON document management:
* `BisonRead` & `BisonWrite`: custom APIs designed for flexibility and performance.
* `BisonEncode` & `BisonDecode`: Swift `Codable` adapters to start working with BSON today.
This project is tested in continuous integration on the following platforms:
* macOS 11
* iOS 15
* tvOS 15
* watchOS 8
* ubuntu 20.04
* Windows Server 2022
## Version
You can import this package by adding the following line to your `Package.swift` dependencies:
```swift
.package(url: "https://github.com/crichez/swift-bison", .upToNextMinor("0.0.1"))
```
*Note:* versions before 1.0.0 are considered pre-release, and sources-breaking changes may be
introduced with a minor version bump. Once the project graduates to 1.0.0, regular semantic
versioning rules will apply.
## Documentation
**This package is documented using [swift-docc](https://github.com/apple/swift-docc)**. You can
build the documentation for a specific module by following instructions at that repository,
or read inline documentation for each source file. The following sections give a brief
introduction to the most common APIs of each module.
### BisonWrite
Import the `BisonWrite` module to compose and encode complex documents using a custom result
builder. The following example declares a simple BSON document with conditionals and nesting,
then encodes it to an Array of bytes.
```swift
import BisonWrite
let ownerDoc = WritableDoc {
"name" => "Bob Belcher"
if season8 {
"age" => Int64(46)
} else {
"age" => Int64(45)
}
"children" => WritableArray {
"Tina"
"Louise"
"Gene"
}
}
.encode(as: [UInt8].self)
```
### BisonRead
Import the `BisonRead` module to parse and decode documents from raw bytes. The following example
parses a document, then extracts select values.
```swift
import BisonRead
do {
// Parse and validate the document.
let doc = try ReadableDoc(bsonBytes: ownerDoc)
// Get the "name" value and initialize it as a String.
guard let nameData = doc["name"] else { return }
let name = try String(bsonBytes: nameData)
// Get the "children" nested document and initialize each value.
guard let childrenData = doc["children"] else { return }
let childrenDoc = try ReadableDoc(bsonBytes: childrenData)
for childNameData in childrenDoc.values {
let childName = try String(bsonBytes: childNameData)
}
} catch DocError<[UInt8]>.unknownType(let type, let key, let progress) {
// Handle document parsing errors.
} catch ValueError.sizeMismatch {
// Handle value parsing errors.
}
```
### BisonEncode & BisonDecode
Import the `BisonEncode` & `BisonDecode` modules to use the `BSONEncoder` and `BSONDecoder` types.
These expose a similar API to Foundation's JSON encoder and decoder, while still featuring support
for custom BSON types through `BisonWrite` & `BisonRead` APIs.
```swift
import BisonEncode
import BisonDecode
import Foundation
struct Owner: Codable {
let name: String
let age: Int64
let children: [String]
}
do {
let owner = Owner(name: "Bob Belcher", age: 46, children: ["Tina", "Louise", "Gene"])
let encodedOwnerDoc = try BSONEncoder().encode(owner)
let decodedOwner = try BSONDecoder().decode(Owner.self, from: encodedOwnerDoc)
} catch DecodingError.typeMismatch(let requested, let context) {
// Handle traditional Swift EncodingErrors and DecodingErrors
}
```
### ObjectID
The `ObjectID` module includes a full-featured BSON ObjectID implementation.
```swift
import ObjectID
// Initialize IDs randomly or from hexadecimal data.
var randomID = ObjectID()
// Use the timestamp property for chronological tracking.
let created: Date = randomID.timestamp
// Use the increment property for version tracking.
let version: Int = randomID.increment
// Easily output hexadecimal strings using custom LosslessStringConvertible conformance
let hexID = String(describing: randomID)
```