FivePersistence

About

This project represents a simple persistence library, primarily used to store Data in memory and onto persistent storage. So far, we (us being Five Agency’s iOS Team) have a few extensions which make saving string and UIImage objects a bit more convenient.

Requirements

• Xcode 8.0+

• Swift 3.0

• iOS 8.0+

• OSX 10.10+

Installation

There are no additional dependencies.

Currently supported installation options:

Swift Package Manager

Create a Package.swift file.

import PackageDescription

let package = Package(
    name: "FivePersistenceTestProject",
    targets: [],
    dependencies: [
        .Package(url: "https://github.com/fiveagency/ios-five-persistence", majorVersion: 1)
    ]
)

Manually using git submodules

• Add FivePersistence as a submodule

$ git submodule add https://github.com/fiveagency/ios-five-persistence.git

• Drag FivePersistence.xcodeproj into Project Navigator.

• Go to Project > Targets > Build Phases > Link Binary With Libraries, click + and select FivePersistence.framework target.

Examples

To run the example project do the following.

• Clone the repo by typing:

$ git clone https://github.com/fiveagency/ios-five-persistence.git YOUR_DESTINATION_FOLDER

• Open FivePersistence.xcworkspace, choose Example scheme and hit run. This method will build everything and run the sample app.

Usage

Keeper

The Keeper class is responsible for read, write and delete operations. It can be initialized using the following:

public init(storageDirectory: FileManager.SearchPathDirectory = .cachesDirectory, shouldExcludeFromBackup: Bool = true)

When it comes to actually using the Keeper, we have two choices. Synchronous and asynchronous. When using the first approach, all of our methods return KeeperResult which is a tuple defined as the following:

/**
 Keeper return type for synchronous calls.

 The first `bool` flag is stating whether or not the call was successfull.
 The second `Data` object represents the requested `Data` provided `success` equals `true`. If `success` equals `false`
 the third `Error` parameter will present the underlaying error.
 */

public typealias KeeperResult = (Bool, Data?, Error?)

Methods returning KeeperResult are:

public func data(forKey key: String) -> KeeperResult
public func save(data: Data, forKey key: String) -> KeeperResult
public func remove(dataForKey key: String) -> KeeperResult

Example usage:

guard let stringData = "some example string".data(using: .utf8) else {
    return
}

let keeper = Keeper()
let (success, _, error) = keeper.save(data: stringData, forKey: "exampleKey")
if let `error` = error, !success {
    print("Failed saving data with error: \(error)")
    return
}
print("Horaaaaay! We've saved our data!")

If we were to read the data, we could do the following:

let keeper = Keeper()
let (success, data, error) = keeper.data(forKey: "exampleKey")
if let `error` = error, !success {
    print("Failed reading data with error: \(error)")
    return
}
guard let stringData = data else {
    print("Hmm, this should not happen :(")
    return
}
let string = String(data: stringData, encoding: .utf8)
print("Our string is: \(string)")

Now, if we were to go with asynchronous approach, we’d have callbacks of KeeperCompletion defined as the following:

/**
 Keeper return type for asynchronous calls.

 - parameter result: The tuple values those represented by `KeeperResult` which are(success: Bool, data: Data?,
 error: Error?)
 */

public typealias KeeperCompletion = (_ result: KeeperResult) -> Void

Methods for asynchronous usage are:

public func data(forKey key: String, completion: @escaping KeeperCompletion)
public func save(data: Data, forKey key: String, completion: @escaping KeeperCompletion)
public func remove(dataForKey key: String, completion: @escaping KeeperCompletion)

It’s worth noting that all of those asynchronous methods are thread safe, and all callbacks are executed on the main queue.

Example usage:

guard let stringData = "some other example string".data(using: .utf8) else {
    return
}

let keeper = Keeper()
keeper.save(data: stringData, forKey: "exampleKey") { success, _, error in
    if let `error` = error, !success {
        print("Failed saving data with error: \(error)")
        return
    }
    print("Horaaaaay! We've saved our data!")
}

Extensions

For ease of use, we’ve introduces a few extensions which have their own return types and corresponding methods. All of them have a similar signature to Data based methods/types:

String

public typealias KeeperStringResult = (Bool, String?, Error?)
public typealias KeeperStringCompletion = (_ result: KeeperStringResult) -> Void

public func string(forKey key: String, completion: @escaping KeeperStringCompletion)
public func save(string: String, forKey key: String, completion: @escaping KeeperStringCompletion)

public func string(forKey key: String) -> KeeperStringResult
public func save(string: String, forKey key: String) -> KeeperStringResult

UIImage

The addition to the original types/enums is the KeeperImageFormat enum which specifies whether the image should be saved as a ‘png’ or a 'jpeg’.

public enum KeeperImageFormat {
    case png
    case jpg(CGFloat)
}

public typealias KeeperImageResult = (Bool, UIImage?, Error?)
public typealias KeeperImageCompletion = (_ result: KeeperImageResult) -> Void

public func image(forKey key: String, completion: @escaping KeeperImageCompletion)
public func save(image: UIImage, forKey key: String, format: KeeperImageFormat = .png, completion: @escaping KeeperImageCompletion)

public func image(forKey key: String) -> KeeperImageResult
public func save(image: UIImage, forKey key: String, format: KeeperImageFormat = .png) -> KeeperImageResult

Note: There is no remove(forKey key: String) present in the extensions as we have no need for it except in the base Data layer.

Authors

Five Persistence library team (listed alphabetically)

• Miran Brajsa

License

FivePersistence is available under the MIT license. See the LICENSE file for more info.