Need help with Disk?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

saoudrizwan
2.8K Stars 140 Forks MIT License 241 Commits 14 Opened issues

Description

Delightful framework for iOS to easily persist structs, images, and data

Services available

!
?

Need anything else?

Contributors list

# 25,898
TypeScr...
Swift
ios11
ios10
158 commits
# 59,210
ios11
Swift
Objecti...
ios10
19 commits
# 22,653
Objecti...
Swift
ios11
image-p...
2 commits
# 292,337
ios11
ios-swi...
Swift
Objecti...
1 commit
# 5,225
Swift
Objecti...
qq
alipay
1 commit
# 270,780
ios11
ios-swi...
Swift
Objecti...
1 commit
# 290,810
ios11
ios-swi...
Swift
Objecti...
1 commit
# 278,942
Objecti...
ios11
ios-swi...
Swift
1 commit
# 236,452
Objecti...
Swift
swift-f...
ios11
1 commit

Disk

GitRoyalty Platform: iOS 9.0+ Language: Swift 4 Carthage compatible License: MIT

InstallationUsageDebuggingA WordDocumentationApps Using DiskLicenseContributeQuestions?

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

Support Disk's contributors with a monthly subscription on https://gitroyalty.com/saoudrizwan/Disk to install this package.

Subscribe on GitRoyalty
* comes with a 2 week free trial and can be cancelled anytime

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 /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 /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 /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 /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

throw
ing them. See Handling Errors Using Do-Catch.

Structs (must conform to
Codable
)

Let's say we have a data model called

Message
...
swift
struct Message: Codable {
    let title: String
    let body: String
}
... and we want to persist a message to disk...
swift
let message = Message(title: "Hello", body: "How are you?")
swift
try Disk.save(message, to: .caches, as: "message.json")
... or maybe we want to save it in a folder...
swift
try Disk.save(message, to: .caches, as: "Folder/message.json")
... we might then want to retrieve this message later...
swift
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? example

So what happened in the background? Disk first converts

message
to JSON data and atomically writes that data to a newly created file at
/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.
swift
var messages = [Message]()
for i in 0..<5 {
    messages.append(Message(title: "\(i)", body: "..."))
}
swift
try Disk.save(messages, to: .caches, as: "messages.json")
swift
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.

swift
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.

swift
let encoder = JSONEncoder()
encoder.keyEncodingStrategy = .convertToSnakeCase
try Disk.save(messages, to: .caches, as: "messages.json", encoder: encoder)
swift
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.
swift
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.

swift
var images = [UIImages]()
// ...
swift
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.
swift
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:
swift
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:
swift
try Disk.save(diary, to: .documents, as: "Nature/diary.json")
Then you could retrieve all the images in the Nature folder like so:
swift
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.

swift
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.
swift
var data = [Data]()
// ...
swift
try Disk.save(data, to: .documents, as: "videos")
swift
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:
swift
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.
swift
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:

swift
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

    swift
    Disk.totalCapacity
    
  • Available capacity

    swift
    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.)

    swift
    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.)

    swift
    Disk.availableCapacityForOpportunisticUsage
    

Note: These variables return Optional

Int
s 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

    swift
    try Disk.clear(.caches)
    
  • Remove a file/folder

    swift
    try Disk.remove("video.mp4", from: .documents)
    
  • Check if file/folder exists

    swift
    if Disk.exists("album", in: .documents) {
    // ...
    }
    
  • Move a file/folder to another directory

    swift
    try Disk.move("album/", in: .documents, to: .caches)
    
  • Rename a file/folder

    swift
    try Disk.rename("currentName.json", in: .documents, to: "newName.json")
    
  • Get file system URL for a file/folder

    swift
    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.)
    swift
    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.

    swift
    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

    swift
    try Disk.remove(fileUrl)
    
  • Check if file/folder exists

    swift
    if Disk.exists(fileUrl) {
    // ...
    }
    
  • Move a file/folder to another directory

    swift
    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
    swift
    try Disk.doNotBackup(fileUrl)
    
    swift
    try Disk.backup(fileUrl)
    
  • Check if URL is of a folder

    swift
    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:
swift
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... ```swift 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]`...
swift 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. 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?

Contact me by email [email protected], or by twitter @sdrzn. Please create an issue if you come across a bug or would like a feature to be added.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.