Swift Database coredata persistence realmswift
Need help with StorageKit?
Click the โ€œchatโ€ button below for chat support from the developer who created it, or find similar developers for support.
StorageKit

Description

Your Data Storage Troubleshooter ๐Ÿ› 

213 Stars 12 Forks MIT License 34 Commits 2 Opened issues

Services available

Need anything else?

StorageKit

Your Data Storage Troubleshooter ๐Ÿ› 


Introduction

StorageKit is a framework which reduces the complexity of managing a persistent layer. You can easily manage your favorite persistent frameworks (Core Data / Realm at the moment), accessing them through a high-level interface.

Our mission is keeping the persistence layer isolated as much as possible from the client codebase. In this way, you can just focus on developing your app. Moreover, you can migrate to another persistent framework easily, keeping the same interface: StorageKit will do almost everything for you.

  • Hassle free setup ๐Ÿ‘
  • Easy to use ๐Ÿค–
  • Extensible ๐Ÿš€
  • Support for background queries ๐Ÿ™Œ๐Ÿผ
  • Fully tested ( well, almost, ... โ˜บ๏ธ )

StorageKit is a Swift 3 and XCode 8 compatible project.

Build Status

| Branch | Status | | ------------- | ------------- | | Master | BuddyBuild | | Develop | BuddyBuild |

Table of Contents

  1. How it works
  2. Define entities
  3. CRUD
  4. Background operations
  5. Installation
  6. Core Mantainers
  7. Known issues
  8. TODO
  9. License
  10. Credits

How it works

The first step is to create a new

Storage
object with a specific type (either
.CoreData
or
.Realm
) which is the entry-point object to setup
StorageKit
:
let storage = StorageKit.addStorage(type: .Realm)

or

let storage = StorageKit.addStorage(type: .CoreData(dataModelName: "Example")

The storage exposes a

context
which is the object you will use to perform the common CRUD operations, for instance:
try storage.mainContext?.fetch(predicate: NSPredicate(format: "done == false"), sortDescriptors: [sortDescriptors], completion: { (fetchedTasks: [RTodoTask]?) in
    self.tasks = fetchedTasks
        // do whatever you want
    }
)

or

let task = functionThatRetrieveASpecificTaskFromDatabase()

do { try storage.mainContext?.delete(task) } catch { // manage the error }

That's it! ๐ŸŽ‰

In just few lines of code you are able to use your favorite database (through the

Storage
) and perform any CRUD operations through the
StorageContext
.

Define Entities

Both Core Data and Realm relies on two base objects to define the entities:

Code Data Entity

import RealmSwift

class RTodoTask: Object { dynamic var name = "" dynamic var done = false

override static func primaryKey() -> String? {
    return "taskID"
}

}

StorageKit is not able to define your entity class. It means that you must define all your entities manually. It's the only thing you have to do by yourself, please bear with us.

You can create a new entity using in this way:

do {
    try let entity: MyEntity = context.create()
} catch {}

If you are using

Realm
,
entity
is an unmanaged object and it should be explicitily added to the database with:
do {
    try storage.mainContext?.add(entity)
} catch {}

CRUD

C as Create

do {
    try let entity: MyEntity = context.create()
} catch {}

This method creates a new entity object: an

NSManagedObject
for
Core Data
and an
Object
for
Realm
.

Note

You must create a class entity by yourself before using

StorageKit
. Therefore, for Core Data you must add an entity in the data model, for Realm you must create a new class which extends the base class Object. If you are using the Realm configuration, you have to add it in the storage before performing any update operations.
do {
    try let entity: MyEntity = context.create()
    entity.myProperty = "Hello"

try context.add(entity)

} catch {}

R as Read

    try context.fetch { (result: [MyEntity]?) in
        // do whatever you want with `result`
    }

As you can see, in order to perform a query over a specific data type, you have to explicitily write it in this way

result: [MyEntity]?
.

U as Update

do {
    try context.update {
        entity.myProperty = "Hello"
        entity2.myProperty = "Hello 2"
    }
} catch {}

Note

If you are using the Realm configuration, you have to add the entity in the

storage
(with the method
add
) before performing any update operations.

D as Delete

do {
    try let entity: MyEntity = context.create()
    entity.myProperty = "Hello"

try context.delete(entity)

} catch {}

Background Operations

Good news for you!

StorageKit
has been implemented with a strong focus on background operations and concurrency to improve the user experience of your applications and making your life easier ๐ŸŽ‰

Storage
exposes the following method:

storage.performBackgroundTask {[weak self] backgroundContext in
    // the backgroundContext might be nil because of internal errors
    guard let backgroundContext = backgroundContext else { return }

do {
    // perform your background CRUD operations here on the `backgroundContext`
       backgroundContext.fetch { [weak self] (entities: [MyEntity]?) in
    // do something with `entities`
} catch {
    print(error.localizedDescription)
}

}

Now the point is that

entities
are retrieved in a background context, so if you need to use these entities in another queue (for example in the main one to update the UI), you must pass them to the other context through another method exposed by the
Storage
:
storage.getThreadSafeEntities(for: context, originalContext: backgroundContext, originalEntities: fetchedTasks, completion: { safeFetchedTaks in
    self?.tasks = safeFetchedTaks

DispatchQueue.main.async {
    dispatchGroup.leave()
}

})

The method

func getThreadSafeEntities(for destinationContext: StorageContext, originalContext: StorageContext, originalEntities: [T], completion: @escaping ([T]) -> Void)
create an array of entities with the same data of
originalEntities
but thread safe, ready to be used in
destinatinationContext
.

This means that, once

getThreadSafeEntities
is called, you will be able to use the entities returned by
completion: @escaping ([T]) -> Void)
in the choosen context.

The common use of this method is: 1. perform a background operation (for instance a fetch) in

performBackgroundTask
2. move the entities retrieved to the main context using
getThreadSafeEntities
storage.performBackgroundTask {[weak self] (backgroundContext, backgroundQueue) in
    guard let backgroundContext = backgroundContext else { return }

do {
    // 1
    backgroundContext.fetch { [weak self] (entities: [MyEntity]?) in
        // 2
        storage.getThreadSafeEntities(for: context, originalContext: backgroundContext, originalEntities: entities, completion: { safeEntities in
            self?.entities = safeEntities
        })
    }
} catch {
    print(error.localizedDescription)
}

}

Installation

CocoaPods

Add

StorageKit
to your Podfile
use_frameworks!
target 'MyTarget' do
    pod 'StorageKit', '~> 0.3.1'
end
$ pod install

Carthage

github "StorageKit/StorageKit" ~> "0.3.1"

Then on your application target Build Phases settings tab, add a "New Run Script Phase". Create a Run Script with the following content:

/usr/local/bin/carthage copy-frameworks

and add the following paths under "Input Files":

$(SRCROOT)/Carthage/Build/iOS/StorageKit.framework

Core Mantainers

| Guardians | | | ------------- | ------------- | | Ennio Masi | @ennioma | | Marco Santarossa | @MarcoSantaDev |

Known Issues

  • Now it's not possible to exclude
    Realm.framework
    and
    RealmSwift.framework
    from the installation
  • UI Test target doesn't work in the example project

TODO

  • Remove Realm dependency if not needed (the user can decide between Core Data or Realm)
  • Add Reactive interface
  • Distribute through the Swift Package Manager
  • Add more functionalities to the context
  • Add notifications
  • Add migrations

License

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

Credits:

Boxes icon provided by

Nuon Project
(LLuisa Iborra). We have changed the boxes color.

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.