Skip to content
58 changes: 57 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -51,7 +51,7 @@ Tested with ReerJSON 1.0.1, ZippyJSON 1.2.15, IkigaJSON 2.3.2

Add dependency in `Package.swift` or project `Package Dependencies`
```swift
.package(url: "https://github.com/reers/ReerJSON.git", from: "1.0.2"),
.package(url: "https://github.com/reers/ReerJSON.git", from: "1.1.0"),
```

Depend on `ReerJSON` in your target.
Expand Down Expand Up @@ -116,6 +116,62 @@ The `inout` parameter makes it clear that the data is consumed by this operation
> Use in-place parsing only when performance is critical
> and you can accept the ownership semantics.

## Streaming

Parse large or incremental JSON inputs without waiting for the complete payload.
Streaming supports both newline-delimited JSON values and a single top-level JSON array.

Use `JSONStreamParser` when you want DOM-style `JSONValue` results:

```swift
import Foundation
import ReerJSON

var parser = JSONStreamParser(mode: .jsonLines)

let firstChunk = Data("{\"id\":1}\n".utf8)
let secondChunk = Data("{\"id\":2}\n".utf8)

let firstValues = try parser.parse(firstChunk)
let secondValues = try parser.parse(secondChunk)
let remainingValues = try parser.finalize()
```

Use `StreamingJSONLinesDecoder` or `StreamingJSONArrayDecoder` when each item
should be decoded into a `Decodable` type as soon as it is complete:

```swift
import Foundation
import ReerJSON

struct Event: Decodable, Sendable {
let id: Int
let name: String
}

var decoder = StreamingJSONLinesDecoder(Event.self)

let events = try decoder.parseBuffer(Data("{\"id\":1,\"name\":\"start\"}\n".utf8))
let remainingEvents = try decoder.finalize()
```

For `AsyncSequence` sources, stream `Data` chunks directly into `JSONValue`
or decoded models. `AsyncSequence<UInt8>` sources can also use `jsonValues`
with an optional `chunkSize`.

```swift
for try await value in dataChunks.jsonValues(mode: .jsonLines) {
print(value)
}

for try await event in dataChunks.decode(Event.self, mode: .jsonLines) {
print(event)
}
```

`AsyncSequence` adapters are available on macOS 10.15, iOS 13, tvOS 13,
and watchOS 6 or newer.

## JSONSerialization Alternative

Use `ReerJSONSerialization` with the same API as Foundation's `JSONSerialization`:
Expand Down
14 changes: 13 additions & 1 deletion Sources/ReerJSON/Error.swift
Original file line number Diff line number Diff line change
Expand Up @@ -51,17 +51,27 @@ public struct JSONError: Error, Equatable, Sendable, CustomStringConvertible {
/// The coding path where the error occurred (for decoding errors).
public let path: String

/// The underlying yyjson read error code, when this error originates from
/// the JSON parser. Zero (`YYJSON_READ_SUCCESS`) when not applicable.
///
/// This is primarily used by the streaming APIs to distinguish recoverable
/// "need more data" conditions (`YYJSON_READ_ERROR_UNEXPECTED_END`,
/// `YYJSON_READ_ERROR_EMPTY_CONTENT`, `YYJSON_READ_ERROR_MORE`) from
/// non-recoverable parse errors.
internal let readErrorCode: UInt32

public var description: String {
if path.isEmpty {
return message
}
return "\(message) (at \(path))"
}

private init(kind: Kind, message: String, path: String = "") {
private init(kind: Kind, message: String, path: String = "", readErrorCode: UInt32 = 0) {
self.kind = kind
self.message = message
self.path = path
self.readErrorCode = readErrorCode
}

// MARK: - Public Factory Methods
Expand Down Expand Up @@ -144,6 +154,7 @@ public struct JSONError: Error, Equatable, Sendable, CustomStringConvertible {
self.kind = .invalidJSON
self.message = message
self.path = ""
self.readErrorCode = UInt32(error.code)
}

/// Create an error from a yyjson write error.
Expand All @@ -168,5 +179,6 @@ public struct JSONError: Error, Equatable, Sendable, CustomStringConvertible {
self.kind = .writeError
self.message = message
self.path = ""
self.readErrorCode = 0
}
}
76 changes: 56 additions & 20 deletions Sources/ReerJSON/ReerJSONDecoder.swift
Original file line number Diff line number Diff line change
Expand Up @@ -148,15 +148,19 @@ open class ReerJSONDecoder {
/// Set to `true` to allow parsing of JSON5. Defaults to `false`.
open var allowsJSON5: Bool {
get {
options.json5
optionsLock.lock()
defer { optionsLock.unlock() }
return options.json5
}
set {
optionsLock.lock()
defer { optionsLock.unlock() }
options.json5 = newValue
}
}

/// Options set on the top-level encoder to pass down the decoding hierarchy.
struct Options {
struct Options: Sendable {
var dateDecodingStrategy: JSONDecoder.DateDecodingStrategy = .deferredToDate
var dataDecodingStrategy: JSONDecoder.DataDecodingStrategy = .base64
var nonConformingFloatDecodingStrategy: JSONDecoder.NonConformingFloatDecodingStrategy = .throw
Expand All @@ -169,6 +173,12 @@ open class ReerJSONDecoder {
fileprivate var options = Options()
fileprivate let optionsLock = LockedState<Void>()

func optionsSnapshot() -> Options {
optionsLock.lock()
defer { optionsLock.unlock() }
return options
}

// MARK: - Constructing a JSON Decoder

/// Initializes `self` with default strategies.
Expand All @@ -185,6 +195,7 @@ open class ReerJSONDecoder {
/// - throws: `DecodingError.dataCorrupted` if values requested from the payload are corrupted, or if the given data is not valid JSON.
/// - throws: An error if any value throws an error during decoding.
open func decode<T: Decodable>(_ type: T.Type, from data: Data, path: [String] = []) throws -> T {
let options = optionsSnapshot()
var flag: yyjson_read_flag = YYJSON_READ_NUMBER_AS_RAW
if options.json5 {
flag |= YYJSON_READ_JSON5
Expand All @@ -197,7 +208,7 @@ open class ReerJSONDecoder {
)
}
guard let doc else {
return try decodeWithFoundationDecoder(type, from: data)
return try decodeWithFoundationDecoder(type, from: data, options: options)
}

defer {
Expand All @@ -210,7 +221,27 @@ open class ReerJSONDecoder {
}

let json = JSON(pointer: pointer)
let impl = JSONDecoderImpl(json: json, userInfo: userInfo, codingPathNode: .root, options: options)
let impl = JSONDecoderImpl(json: json, userInfo: options.userInfo, codingPathNode: .root, options: options)
return try impl.unbox(json, as: type, for: .root, _CodingKey?.none)
}

func decodeParsedValue<T: Decodable>(_ type: T.Type, from value: JSONValue, path: [String] = []) throws -> T {
try Self.decodeParsedValue(type, from: value, path: path, options: optionsSnapshot())
}

static func decodeParsedValue<T: Decodable>(
_ type: T.Type,
from value: JSONValue,
path: [String] = [],
options: Options
) throws -> T {
var pointer = value.rawValue
for key in path {
pointer = key.withCString { yyjson_obj_get(pointer, $0) }
}

let json = JSON(pointer: pointer)
let impl = JSONDecoderImpl(json: json, userInfo: options.userInfo, codingPathNode: .root, options: options)
return try impl.unbox(json, as: type, for: .root, _CodingKey?.none)
}

Expand Down Expand Up @@ -238,6 +269,7 @@ open class ReerJSONDecoder {
path: [String] = [],
configuration: T.DecodingConfiguration
) throws -> T {
let options = optionsSnapshot()
var flag: yyjson_read_flag = YYJSON_READ_NUMBER_AS_RAW
if options.json5 {
flag |= YYJSON_READ_JSON5
Expand All @@ -251,7 +283,7 @@ open class ReerJSONDecoder {
}
guard let doc else {
if #available(macOS 14, iOS 17, tvOS 17, watchOS 10, visionOS 1, *) {
return try decodeWithFoundationDecoder(type, from: data, configuration: configuration)
return try decodeWithFoundationDecoder(type, from: data, options: options, configuration: configuration)
} else {
throw DecodingError.dataCorrupted(.init(
codingPath: [],
Expand All @@ -270,7 +302,7 @@ open class ReerJSONDecoder {
}

let json = JSON(pointer: pointer)
let impl = JSONDecoderImpl(json: json, userInfo: userInfo, codingPathNode: .root, options: options)
let impl = JSONDecoderImpl(json: json, userInfo: options.userInfo, codingPathNode: .root, options: options)
return try impl.unbox(json, as: type, configuration: configuration, for: .root, _CodingKey?.none)
}

Expand All @@ -288,35 +320,39 @@ open class ReerJSONDecoder {
}
#endif

func decodeWithFoundationDecoder<T : Decodable>(_ type: T.Type, from data: Data) throws -> T {
func decodeWithFoundationDecoder<T : Decodable>(
_ type: T.Type,
from data: Data,
options: Options
) throws -> T {
let decoder = Foundation.JSONDecoder()
decoder.dataDecodingStrategy = dataDecodingStrategy
decoder.dateDecodingStrategy = dateDecodingStrategy
decoder.keyDecodingStrategy = keyDecodingStrategy
decoder.nonConformingFloatDecodingStrategy = nonConformingFloatDecodingStrategy
decoder.userInfo = userInfo
configure(decoder, with: options)
return try decoder.decode(type, from: data)
}

private func configure(_ decoder: Foundation.JSONDecoder, with options: Options) {
decoder.dataDecodingStrategy = options.dataDecodingStrategy
decoder.dateDecodingStrategy = options.dateDecodingStrategy
decoder.keyDecodingStrategy = options.keyDecodingStrategy
decoder.nonConformingFloatDecodingStrategy = options.nonConformingFloatDecodingStrategy
decoder.userInfo = options.userInfo
#if !os(Linux)
if #available(macOS 12.0, iOS 15.0, tvOS 15.0, watchOS 8.0, visionOS 1, *) {
decoder.allowsJSON5 = allowsJSON5
decoder.allowsJSON5 = options.json5
}
#endif
return try decoder.decode(type, from: data)
}

#if !os(Linux)
@available(macOS 14, iOS 17, tvOS 17, watchOS 10, visionOS 1, *)
func decodeWithFoundationDecoder<T : DecodableWithConfiguration>(
_ type: T.Type,
from data: Data,
options: Options,
configuration: T.DecodingConfiguration
) throws -> T {
let decoder = Foundation.JSONDecoder()
decoder.dataDecodingStrategy = dataDecodingStrategy
decoder.dateDecodingStrategy = dateDecodingStrategy
decoder.keyDecodingStrategy = keyDecodingStrategy
decoder.nonConformingFloatDecodingStrategy = nonConformingFloatDecodingStrategy
decoder.userInfo = userInfo
decoder.allowsJSON5 = allowsJSON5
configure(decoder, with: options)
return try decoder.decode(type, from: data, configuration: configuration)
}
#endif
Expand Down
Loading