JBird

A blazing fast, type-safe library for working with JSON in Swift

Why JBird?

JBird brings type safety to unstructured JSON with an elegant, ergonomic API that dramatically improves developer experience compared to Foundation’s JSONSerialization:

// Foundation approach - verbose casting and optional chaining
if let json = try? JSONSerialization.jsonObject(with: data) as? [String: Any],
   let user = json["user"] as? [String: Any],
   let name = user["name"] as? String,
   let isActive = user["isActive"] as? Bool {
   // Finally use the values after multiple casts
}

// JBird approach - clean and type-safe
let json = try JSON(data)
let name = try json["user"]["name"].stringValue
let isActive = try json["user"]["isActive"].boolValue
let user = try json["user"].decode(into: User.self)

JBird also simplifies mutation, which is cumbersome with Foundation:

// Modifying JSON with Foundation requires recreating structures
var jsonDict = json as? [String: Any] ?? [:]
if var user = jsonDict["user"] as? [String: Any] {
    user["status"] = "active" 
    jsonDict["user"] = user
}

// Simple modification with JBird
var mutableJSON = try JSON(data)
try mutableJSON["user"]["status"].setValue("active")

JBird eliminates the verbosity of type casting chains and nested optional unwrapping, providing a statically typed interface for efficient JSON traversal and modification. For more information see the documentation

Features

• ⚡️ High Performance: Built with a C11 core for optimized parsing with SIMD acceleration where appropriate.
• 🛡️ Ergonomic, Type Safe APIs: Rich, Swift-first API with proper type checking and error handling. Easily and safely convert between serialized JSON, type-safe JSON, and native Swift types.
• 🧪 Well Tested: Comprehensive test suite ensures correct adherence to the JSON RFC 8259
• 📝 Fully Documented: Thorough documentation with detailed API references and code samples, available on GitHub Pages.

Installation

JBird is primarily distributed through the Swift Package Manager.

To add JBird as a dependency to an existing Swift package, add the following line of code to the dependencies parameter of your Package.swift file:

dependencies: [
    .package(url: "https://github.com/vsanthanam/JBird.git", from: "0.0.0")
]

Then, add the dependency to your target:

.target(
    name: "YourTarget",
    dependencies: [
        .product(name: "JBird", package: "JBird")
    ]
)

For additional installation instructions, including installation methods without the Swift Package Manager, see the documentation.

Performance

JBird is designed for high performance and memory efficiency in mind, with benchmarks showing it to be one of the fastest JSON parsers available for Swift. The core parsing engine is written in C and is heavily optimized, making it significantly faster than pure Swift alternatives.

JBird demonstrates exceptional performance compared to other popular JSON parsing libraries:

• Speed: JBird parses JSON 2-5x faster than SwiftyJSON and about 25% faster than Foundation
• Memory Efficiency: JBird uses significantly less memory than other parsers (up to a 95% reduction)
• Resource Usage: JBird requires dramatically fewer CPU instructions and memory allocations for equivelent payloads
• Consistent Performance: JBird maintains its performance advantage across different JSON file sizes and formats

These benchmarks were run on a variety of JSON files ranging from 64KB to 5MB, in both minified and pretty-printed formats. You can explore the comparisons with common Swift JSON libraries (Foundation, SwiftyJSON, etc.) in the /Benchmarks directory.

Usage & Documentation

JBird’s documentation is built with DocC and included in the repository as a DocC archive. The latest version is hosted on GitHub Pages and is available here.

Additional installation instructions are available on the Swift Package Index

Explore the documentation for more details.

License

JBird is available under the MIT license. See the LICENSE file for more information.