A powerful JSON serialization framework for swift 4.2 which works on iOS and server side frameworks like Vapor 3.
- Can map objects to
JSON
, fromJSON
or both - Allows you create objects that are only "to"
JSON
encodable or only "from"JSON
- Easy integration
- Handles common object types
- Easily extensible
- Uses swift 4.2
- Supports iOS 8 and up
- Carthage support
- SPM support
For the full documentation, click here: https://cuba.github.io/MapCodableKit/
Add the following to the top of any swift file using MapCodableKit
import MapCodableKit
To be able to map your object to json, your object needs to implement the MapEncodable
protocol
struct MyModel: MapEncodable {
let id: String
let name: String
init(id: String, name: String) {
self.id = id
self.name = name
}
func fill(map: Map) {
map.add(id, forKey: "id")
map.add(name, forKey: "name")
}
}
Then you can get any json data like this
// Initialize your object
let myModel = MyModel(id: "123", name: "Jim Halpert")
// To get a json string (i.e. `String`)
let jsonString = try myModel.jsonString(options: [.prettyPrinted], encoding: .utf8)
// To get a json data (i.e. `Data`)
let jsonData = try myModel.jsonData(options: [.prettyPrinted])
// To get a json object (i.e. `[String: Any]`)
let json = try myModel.json()
To be able to map your object to json, your object needs to implement the MapDecodable
protocol
struct MyModel: MapDecodable {
let id: String
let name: String
init(map: Map) throws {
self.id = try map.value(fromKey: "id")
self.name = try map.value(fromKey: "name")
}
}
Then you can initialize your object like this:
let myModel = MyModel(id: "123", name: "Jim Halpert")
// Initialize from a json string (i.e. `String`)
let jsonString = ...get your `json` string from somewhere like the network
let myModel = try MyModel(jsonString: jsonString, encoding: .utf8)
// Intialize from json data (i.e. `Data`)
let jsonData = ...get your `JSON` data from somewhere like the network
let myModel = try MyModel(jsonData: hsonData, encoding: .utf8)
// Initialize from a json object (i.e. `[String: Any]`)
let json = ["id": "234", "name": "Pam Beezley"]
let jsonString = try MyModel(json: json)
To map your object both ways, just implement both MapDecodable
and MapEncodable
. As a convenience you can also use MapCodable
Sometimes you need to serialize a custom object. For this you can use MapEncoder
and MapDecoder
(MapCoder
for both). A simple exaple of this is the built in URLCoder
public class URLCoder: MapCoder {
public init() {}
public func toMap(value: URL) -> String? {
return value.absoluteString
}
public func fromMap(value: String) throws -> URL? {
return URL(string: value)
}
}
You can also use generics if you chose. Here is an example of a generic used for serializing a response:
struct ListBody<T: MapEncodable>: MapEncodable {
let key: String
let objects: [T]
init(key: String, objects: [T]) {
self.key = key
self.objects = objects
}
func fill(map: Map) throws {
try map.add(objects, forKey: key)
}
}
You can get or set an object nested in a dictionary or an array.
For a nested object in a dictionary, just seperate your keys using a .
. For example the key abc.def
will return an object with the key def
in a parent object.
You may also get the first object in an array. For example, the key def[0]
will return the first object in an array def
.
You may chain as many of these as you would like. For example, abc.def[0]
will return the first object in an array def
which is itself nested in the object abc
.
Note: only the first object 0
is supported for now. using any value other than 0
will give you a MappingError
when trying to save to write the value.
MapCodableKit supports any MapPrimitive
variables. MapPrimitive
are any json primitives such as:
String
Double
Bool
Int
Int8
Int16
Int32
Int64
UInt
UInt8
UInt16
UInt32
UInt64
Array
ofMapPrimitive
objectsDictionary
ofMapPrimitive
objects (i.e.[Key: MapPrimitive]
)
Note: if you request a String
for any value that does not parse to a string it will fail serialization. This includes nested objects and arrays since they entire JSON
structure is already parsed.
Raw representable objects are usually enums. They are suppoted fully in this library.
Codable
objects that are either Encodable
or Decodable
or both are supported.
Your models may contains nested MapCodable
objects, Sets, Arrays or Dictionaries.
Sets are supported for the following types:
MapPrimitive
(strings, integers, booleans, doubles etc ...)RawRepresentable
(enums)MapEncodable
(read only nested objects)MapDecodable
(write only nested objects)MapCodable
(read and write nested objects)
Arrays are supported for the following types:
MapPrimitive
(strings, integers, booleans, doubles etc ...)RawRepresentable
(enums)MapEncodable
(read only nested objects)MapDecodable
(write only nested objects)MapCodable
(read and write nested objects)
Arrays are supported for the following types:
MapPrimitive
(strings, integers, booleans, doubles etc ...)RawRepresentable
(enums)MapEncodable
(read only nested objects)MapDecodable
(write only nested objects)MapCodable
(read and write nested objects)
Package manager is a powerful packaging tool built into xcode. For the full documentation on how to use package manager, click here
Carthage is a decentralized dependency manager that builds your dependencies and provides you with binary frameworks.
You can install Carthage with Homebrew using the following command:
$ brew update
$ brew install carthage
To integrate MapCodableKit
into your Xcode project using Carthage, specify it in your Cartfile
:
github "cuba/MapCodableKit" ~> 1.1
Run carthage update
to build the framework and drag the built MapCodableKit.framework
into your Xcode project.
Framework
is the only dependency 😁
MapCodableKit
is owned and maintained by Jacob Sikorski.
MapCodableKit
is largely inspired by ObjectMapper.
MapCodableKit
is released under the MIT license. See LICENSE for details