nunoalexandre / stork

Delivering types from JSON like a Stork

Stork

Stork is a lightweight library focused on making the flight from JSON to Types as smooth as possible. Stork believes in simplicity, explicitness, and control.

Based on functional programming principles and mildly inspired in Aeson, Stork is the middle sweet between JSON parsers such as Argo - full-fledged but requiring extra dependencies and too functional for some - and other parsers that require your types to be mutable, to throw on init, or that take the control away from you.

How it works

To go from JSON to types, all you need to do is to state what fields you want to parse. Stork infers their type and parses them for you. To make that possible, your types must follow the FromJson protocol.

protocol FromJson {
  static func from(value: JsonValue) -> Self?
}

In practice, this means that for a type to be parseable from JSON, it needs to provide a way of being constructed from a JsonValue: string, number, bool, JSON, or [JsonValue].

At compile-time, Storks requires the types you want to get from JSON to be FromJson compliant. Otherwise, you encounter the following compile error message on Xcode:

Generic parameter 'T' could not be infered

Examples

Say that we want to retrieve values of type User from some JSON input, where User and its nested types are defined as follows:

struct User {
  let id: Int
  let name: String
  let email: String?
  let country: Country?
  let subscription: Subscription
  let favouriteSongs: [Song]
}

enum Subscription: String {
  case free
  case bronze
  case silver
  case gold
}

enum Country: String {
  case netherlands
  case portugal
}

struct Song: Equatable {
  let name: String
  let band: String
}

With Stork, to go from JSON to this model all we need to do is to have these types complying to our FromJson protocol.

extension User: FromJson {
  static func from(value: JsonValue) -> User? {
    return value.ifObject { json in
      User(
        id:             try json .! "id",
        name:           try json .! "name",
        email:          json .? "email",
        country:        json .? "country",
        subscription:   try json .! "subscription",
        favouriteSongs: (json ..? "favouriteSongs") ?? []
      )
    }
  }
}

// That's all you need for String/Int RawRepresentable Enums!
extension Subscription: FromJson {}

// Or you get to say how it's done!
// In this case, the country in JSON is short-coded and
// thus needs to be translated to the right Country case.
extension Country: FromJson {
  static func from(value: JsonValue) -> Country? {
    return value.ifString { str in
      switch str {
      case "nl": return .netherlands
      case "pt": return .portugal
      default:   return nil
      }
    }
  }
}

extension Song: FromJson {
  static func from(value: JsonValue) -> Song? {
    return value.ifObject { json in
      Song(
        name: try json .! "name",
        band: try json .! "band"
      )
    }
  }
}

Now that we have everything, let's get Stork to deliver that baby:

// Single user
let maybeUser: User? = User.from(json: userJSON)

// Array of users
let users: [User] = [User].from(jsonArray: usersJSON)

See more, unit-tested examples at the Examples directory

Installation

You can add Stork as a dependency to your project via the following ways.

CocoaPods

1. To add Stork to your Xcode project using CocoaPods, add this line to your Podfile:

pod 'StorkEgg', '0.2.1'

_{Note: The pod name is StorkEgg since Stork was already taken.}

2. Then let CocoaPods fetch and install it for you:

pod install

3. Finally, build your project and import Stork:

import Stork

Git Submodules

# Add Stork as a git submodule to your repository
git submodule add [email protected]:NunoAlexandre/stork.git

# Get the most updated version of Stork
git submodule update --remote

Read more about Git Submodules here.

TODO

I plan to support Carthage and the Swift Package Manager.

Help is rather appreciated!

stork's Issues

Support RawRepresentable enums out of the box

As long as a user can still write their own FromJson, I'd be happy to do this.

Consider adding a 'DecodeResult' value instead of using optionals

Now we are blind in optionals. That means that we don't know why a computation failed.
There are two critical drawbacks now, where whenever 1) an expected required field is missing or its expected type is wrong, no information is passed on to provide a clear suggestion of what is wrong and must be fixed.

Add more examples

• Show how to get a list of Ts from a given [JSON]
• Show how to handle backwards-compatibility
• Show how to build a type from different JsonValues.

Make Stork a pod, carthage, and swift package manager dependency

• Pod
• Carhage
• Swift Package Manager

Write a complete and friendly README

The structure of the page should be something like this:

• 1. Name + Logo(todo)
  • 1.1 Description
• 2. Table of contents
• 3. How it works (It'd be nice to have an illustration explaining the dots and the flow)
• 4. Examples
• 5. Installation (#6)
  • cocoa
  • carthage
  • swift package manager

Consider supporting decoding of values built from JsonValue.list

Say we have the following type:

struct MyCollection {
  let items: [SomeType]
}

This type could be decoded from JSON by supporting JsonValue.list in decodeValue (Decode.swift).

This is not a fundamental feature.

Support decoding of Double values

Support decoding of Double values