Storage: A Swift repository from kylebrowning

Installation • Usage • Debugging • A Word • Documentation • Apps Using Disk • License • Contribute • Questions?

This is a hard fork of https://github.com/saoudrizwan/Disk since it was no longer maintained.

Disk is a powerful and simple file management library built with Apple's iOS Data Storage Guidelines in mind. Disk uses the new Codable protocol introduced in Swift 4 to its utmost advantage and gives you the power to persist structs without ever having to worry about encoding/decoding. Disk also helps you save images and other data types to disk with as little as one line of code.

Compatibility

Disk requires iOS 9+ and is compatible with projects using Swift 4.0 and above. Therefore you must use at least Xcode 9 when working with Disk.

Installation

Swift Package Manager:

dependencies: [
    .Package(url: "https://github.com/saoudrizwan/Disk.git", "0.6.3")
]

Or embed the Disk framework into your project

And import Disk in the files you'd like to use it.

Usage

Disk currently supports persistence of the following types:

Codable
[Codable]
UIImage
[UIImage]
Data
[Data]

These are generally the only types you'll ever need to persist on iOS.

Disk follows Apple's iOS Data Storage Guidelines and therefore allows you to save files in four primary directories and shared containers:

Documents Directory `.documents`

Only documents and other data that is user-generated, or that cannot otherwise be recreated by your application, should be stored in the <Application_Home>/Documents directory and will be automatically backed up by iCloud.

Caches Directory `.caches`

Data that can be downloaded again or regenerated should be stored in the <Application_Home>/Library/Caches directory. Examples of files you should put in the Caches directory include database cache files and downloadable content, such as that used by magazine, newspaper, and map applications.

Use this directory to write any application-specific support files that you want to persist between launches of the application or during application updates. Your application is generally responsible for adding and removing these files (see Helper Methods). It should also be able to re-create these files as needed because iTunes removes them during a full restoration of the device. In iOS 2.2 and later, the contents of this directory are not backed up by iTunes.

Note that the system may delete the Caches/ directory to free up disk space, so your app must be able to re-create or download these files as needed.

Application Support Directory `.applicationSupport`

Put app-created support files in the <Application_Home>/Library/Application support directory. In general, this directory includes files that the app uses to run but that should remain hidden from the user. This directory can also include data files, configuration files, templates and modified versions of resources loaded from the app bundle.

Temporary Directory `.temporary`

Data that is used only temporarily should be stored in the <Application_Home>/tmp directory. Although these files are not backed up to iCloud, remember to delete those files when you are done with them so that they do not continue to consume space on the user’s device.

Application Group Shared Container `.sharedContainer(appGroupName: String)`

Multiple applications on a single device can access a shared directory, as long as these apps have the same groupIdentifier in the com.apple.security.application-groups entitlements array, as described in Adding an App to an App Group in Entitlement Key Reference.

For more information, visit the documentation: https://developer.apple.com/documentation/foundation/nsfilemanager/1412643-containerurlforsecurityapplicati

With all these requirements and best practices, it can be hard working with the iOS file system appropriately, which is why Disk was born. Disk makes following these tedious rules simple and fun.

Using Disk is easy.

Disk handles errors by throwing them. See Handling Errors Using Do-Catch.

Structs (must conform to `Codable`)

Let's say we have a data model called Message...

struct Message: Codable {
    let title: String
    let body: String
}

... and we want to persist a message to disk...

let message = Message(title: "Hello", body: "How are you?")

try Disk.save(message, to: .caches, as: "message.json")

... or maybe we want to save it in a folder...

try Disk.save(message, to: .caches, as: "Folder/message.json")

... we might then want to retrieve this message later...

let retrievedMessage = try Disk.retrieve("Folder/message.json", from: .caches, as: Message.self)

If you Option + click retrievedMessage, then Xcode will show its type as Message. Pretty neat, huh?

So what happened in the background? Disk first converts message to JSON data and atomically writes that data to a newly created file at <Application_Home>/Library/Caches/Folder/message.json. Then when we retrieve the message, Disk automatically converts the JSON data to our Codable struct type.

What about arrays of structs?

Thanks to the power of Codable, storing and retrieving arrays of structs is just as easy as the code above.

var messages = [Message]()
for i in 0..<5 {
    messages.append(Message(title: "\(i)", body: "..."))
}

try Disk.save(messages, to: .caches, as: "messages.json")

let retrievedMessages = try Disk.retrieve("messages.json", from: .caches, as: [Message].self)

Appending structs (Thank you for the suggestion @benpackard)

Disk also allows you to append a struct or array of structs to a file with data of the same type.

try Disk.append(newMessage, to: "messages.json", in: .caches)

Note: you may append a single struct to an empty file, but then in order to properly retrieve that struct again, you must retrieve it as an array.

Using custom JSONEncoder or JSONDecoder (Thank you @nixzhu and @mecid)

Behind the scenes, Disk uses Apple's JSONEncoder and JSONDecoder classes to encode and decode raw JSON data. You can use custom instances of these classes if you require special encoding or decoding strategies for example.

let encoder = JSONEncoder()
encoder.keyEncodingStrategy = .convertToSnakeCase
try Disk.save(messages, to: .caches, as: "messages.json", encoder: encoder)

let decoder = JSONDecoder()
decoder.keyDecodingStrategy = .convertFromSnakeCase
let retrievedMessages = try Disk.retrieve("messages.json", from: .caches, as: [Message].self, decoder: decoder)

Note: appending a Codable structure requires Disk to first decode any existing values at the file location, append the new value, then encode the resulting structure to that location.

try Disk.append(newMessage, to: "messages.json", in: .caches, decoder: decoder, encoder: encoder)

Images

let image = UIImage(named: "nature.png")

try Disk.save(image, to: .documents, as: "Album/nature.png")

let retrievedImage = try Disk.retrieve("Album/nature.png", from: .documents, as: UIImage.self)

Array of images

Multiple images are saved to a new folder. Each image is then named 0.png, 1.png, 2.png, etc.

var images = [UIImages]()
// ...

try Disk.save(images, to: .documents, as: "FolderName/")

You don't need to include the "/" after the folder name, but doing so is declarative that you're not writing all the images' data to one file, but rather as several files to a new folder.

let retrievedImages = try Disk.retrieve("FolderName", from: .documents, as: [UIImage].self)

Let's say you saved a bunch of images to a folder like so:

try Disk.save(deer, to: .documents, as: "Nature/deer.png")
try Disk.save(lion, to: .documents, as: "Nature/lion.png")
try Disk.save(bird, to: .documents, as: "Nature/bird.png")

And maybe you even saved a JSON file to this Nature folder:

try Disk.save(diary, to: .documents, as: "Nature/diary.json")

Then you could retrieve all the images in the Nature folder like so:

let images = try Disk.retrieve("Nature", from: .documents, as: [UIImage].self)

... which would return -> [deer.png, lion.png, bird.png]

Appending images

Unlike how appending a struct simply modifies an existing JSON file, appending an image adds that image as an independent file to a folder.

try Disk.append(goat, to: "Nature", in: .documents)

Note: it's recommended to manually save an independent image using the save(:to:as:) function in order to specify a name for that image file in case you want to retrieve it later. Using the append(:to:in:) function results in creating a file with an auto-generated name (i.e. if you append an image to a folder with images already present (0.png, 1.png, 2.png), then the new image will be named 3.png.) If the image name is not important, then using append(:to:in:) is fine. Appending arrays of images is similar in behavior.

Data

If you're trying to save data like .mp4 video data for example, then Disk's methods for Data will help you work with the file system to persist all data types.

let videoData = Data(contentsOf: videoURL, options: [])

try Disk.save(videoData, to: .documents, as: "anime.mp4")

let retrievedData = try Disk.retrieve("anime.mp4", from: .documents, as: Data.self)

Array of Data

Disk saves arrays of Data objects like it does arrays of images, as files in a folder.

var data = [Data]()
// ...

try Disk.save(data, to: .documents, as: "videos")

let retrievedVideos = try Disk.retrieve("videos", from: .documents, as: [Data].self)

If you were to retrieve [Data] from a folder with images and JSON files, then those files would be included in the returned value. Continuing the example from the Array of images section:

let files = try Disk.retrieve("Nature", from: .documents, as: [Data].self)

... would return -> [deer.png, lion.png, bird.png, diary.json]

Appending Data

Appending Data or an array of Data is similar to appending an image or array of images—new files are created with auto-generated names and added to the specified folder.

try Disk.append(newDataObject, to: "Folder/", in: .documents)

Large files

It's important to know when to work with the file system on the background thread. Disk is synchronous, giving you more control over read/write operations on the file system. Apple says that "because file operations involve accessing the disk, performing those operations asynchronously is almost always preferred."

Grand Central Dispatch is the best way to work with Disk asynchronously. Here's an example:

activityIndicator.startAnimating()
DispatchQueue.global(qos: .userInitiated).async {
    do {
        try Disk.save(largeData, to: .documents, as: "Movies/spiderman.mp4")
    } catch {
        // ...
    }
    DispatchQueue.main.async {
        activityIndicator.stopAnimating()
        // ...
    }
}

Don't forget to handle these sorts of tasks being interrupted.

iOS 11 Volume Information

Apple introduced several great iOS storage practices in Session 204, putting emphasis on several new NSURL volume capacity details added in iOS 11. This information allows us to gauge when it's appropriate to store data on the user's disk.

Total capacity

Disk.totalCapacity

Available capacity

Disk.availableCapacity

Available capacity for important usage. This indicates the amount of space that can be made available for things the user has explicitly requested in the app's UI (i.e. downloading a video or new level for a game.)

Disk.availableCapacityForImportantUsage

Available capacity for opportunistic usage. This indicates the amount of space available for things that the user is likely to want but hasn't explicitly requested (i.e. next episode in video series they're watching, or recently updated documents in a server that they might be likely to open.)

Disk.availableCapacityForOpportunisticUsage

Note: These variables return Optional Ints since retrieving file system resource values may fail and return nil. However this is very unlikely to happen, and this behavior exists solely for safety purposes.

Helper Methods

Clear an entire directory

try Disk.clear(.caches)

Remove a file/folder

try Disk.remove("video.mp4", from: .documents)

Check if file/folder exists

if Disk.exists("album", in: .documents) {
    // ...
}

Move a file/folder to another directory

try Disk.move("album/", in: .documents, to: .caches)

Rename a file/folder

try Disk.rename("currentName.json", in: .documents, to: "newName.json")

Get file system URL for a file/folder

let url = try Disk.url(for: "album/", in: .documents)

Mark a file/folder with the do not backup attribute (this keeps the file/folder on disk even in low storage situations, but prevents it from being backed up by iCloud or iTunes.)

try Disk.doNotBackup("album", in: .documents)

Everything in your app’s home directory is backed up, with the exception of the application bundle itself, the caches directory, and temporary directory.

try Disk.backup("album", in: .documents)

(You should generally never use the .doNotBackup(:in:) and .backup(:in:) methods unless you're absolutely positive you want to persist data no matter what state the user's device is in.)

`URL` Counterparts

Most of these helper methods have URL counterparts, in case you want to work with files directly with their file system URLs.

let fileUrl = try Disk.url(for: "file.json", in: .documents)

Remove a file/folder

try Disk.remove(fileUrl)

Check if file/folder exists

if Disk.exists(fileUrl) {
    // ...
}

Move a file/folder to another directory

let newUrl = try Disk.url(for: "Folder/newFileName.json", in: .documents)
try Disk.move(fileUrl, to: newUrl)

Mark a file/folder with the do not backup attribute

try Disk.doNotBackup(fileUrl)

try Disk.backup(fileUrl)

Check if URL is of a folder

if Disk.isFolder(fileUrl) {
    // ...
}

Debugging

Disk is thorough, meaning that it will not leave an error to chance. Almost all of Disk's methods throw errors either on behalf of Foundation or custom Disk Errors that are worth bringing to your attention. These errors have a lot of information, such as a description, failure reason, and recovery suggestion:

do {
    if Disk.exists("posts.json", in: .documents) {
        try Disk.remove("posts.json", from: .documents)
    }
} catch let error as NSError {
    fatalError("""
        Domain: \(error.domain)
        Code: \(error.code)
        Description: \(error.localizedDescription)
        Failure Reason: \(error.localizedFailureReason ?? "")
        Suggestions: \(error.localizedRecoverySuggestion ?? "")
        """)
}

The example above takes care of the most common error when dealing with the file system: removing a file that doesn't exist.

A Word from the Developer

After developing for iOS for 8+ years, I've come across almost every method of data persistence there is to offer (Core Data, Realm, NSKeyedArchiver, UserDefaults, etc.) Nothing really fit the bill except NSKeyedArchiver, but there were too many hoops to jump through. After Swift 4 was released, I was really excited about the Codable protocol because I knew what it had to offer in terms of JSON coding. Working with network responses' JSON data and converting them to usable structures has never been easier. Disk aims to extend that simplicity of working with data to the file system.

Let's say we get some data back from a network request...

let _ = URLSession.shared.dataTask(with: request) { (data, response, error) in
    DispatchQueue.main.async {
        guard error == nil else { fatalError(error!.localizedDescription) }
        guard let data = data else { fatalError("No data retrieved") }

        // ... we could directly save this data to disk...
        try? Disk.save(data, to: .caches, as: "posts.json")

    }
}.resume()

... and retrieve it later as [Post]...

let posts = try Disk.retrieve("posts.json", from: .caches, as: [Post].self)

Disk takes out a lot of the tedious handy work required in coding data to the desired type, and it does it well. Disk also makes necessary but monotonous tasks simple, such as clearing out the caches or temporary directory (as required by Apple's iOS Data Storage Guidelines):

try Disk.clear(.temporary)

Disk is also significantly faster than alternative persistence solutions like NSKeyedArchiver, since it works directly with the file system. Best of all, Disk is thorough when it comes to throwing errors, ensuring that you understand why a problem occurs when it does.

Documentation

Option + click on any of Disk's methods for detailed documentation.

Apps Using Disk

License

Disk uses the MIT license. Please file an issue if you have any questions or if you'd like to share how you're using Disk.

Contribute

Please feel free to create issues for feature requests or send pull requests of any additions you think would complement Disk and its philosophy.

Questions?

Use the discussions feature on github.

kylebrowning/Storage