{"id":1001,"url":"https://github.com/StorageKit/StorageKit","last_synced_at":"2025-07-30T20:30:40.583Z","repository":{"id":49089509,"uuid":"96405808","full_name":"StorageKit/StorageKit","owner":"StorageKit","description":"Your Data Storage Troubleshooter 🛠","archived":false,"fork":false,"pushed_at":"2017-10-30T17:46:01.000Z","size":215,"stargazers_count":227,"open_issues_count":1,"forks_count":10,"subscribers_count":8,"default_branch":"develop","last_synced_at":"2025-07-23T23:10:44.088Z","etag":null,"topics":["coredata","database","persistence","realmswift","swift"],"latest_commit_sha":null,"homepage":"","language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/StorageKit.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-07-06T08:15:54.000Z","updated_at":"2025-05-26T20:55:31.000Z","dependencies_parsed_at":"2022-09-24T02:01:19.265Z","dependency_job_id":null,"html_url":"https://github.com/StorageKit/StorageKit","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/StorageKit/StorageKit","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/StorageKit%2FStorageKit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/StorageKit%2FStorageKit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/StorageKit%2FStorageKit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/StorageKit%2FStorageKit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/StorageKit","download_url":"https://codeload.github.com/StorageKit/StorageKit/tar.gz/refs/heads/develop","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/StorageKit%2FStorageKit/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":267935128,"owners_count":24168267,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-30T02:00:09.044Z","response_time":70,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["coredata","database","persistence","realmswift","swift"],"created_at":"2024-01-05T20:15:36.675Z","updated_at":"2025-07-30T20:30:40.225Z","avatar_url":"https://github.com/StorageKit.png","language":"Swift","funding_links":[],"categories":["Database","Libs"],"sub_categories":["Getting Started","Other free courses","Linter","Data Management"],"readme":"\u003ch3 align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/StorageKit/StorageKit/master/Resources/logo.jpg\" alt=\"StorageKit\"/\u003e\n\n  Your Data Storage Troubleshooter 🛠\n\u003c/h3\u003e\n\n\u003cdiv align=\"center\"\u003e\n\u003cimg src=\"https://img.shields.io/cocoapods/v/StorageKit.svg\"\u003e\n\u003cimg src=\"https://img.shields.io/badge/Carthage-compatible-4BC51D.svg?style=flat\"\u003e\n\u003cimg src=\"https://cocoapod-badges.herokuapp.com/l/StorageKit/badge.png\"\u003e\n\u003cimg src=\"https://img.shields.io/badge/Swift-3.2-orange.svg\"\u003e\n\u003cimg src=\"https://img.shields.io/cocoapods/p/StorageKit.svg?style=flat\"\u003e\n\u003c/div\u003e\n\n\u003cbr /\u003e\n\n## Introduction\nStorageKit 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.\n\nOur 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.\n\n* Hassle free setup 👍\n* Easy to use 🤖\n* Extensible 🚀\n* Support for background queries 🙌🏼\n* Fully tested ( well, almost, ... ☺️ )\n\n*StorageKit* is a **Swift 3** and **XCode 8** compatible project.\n\n## Build Status\n\n| Branch | Status |\n| ------------- | ------------- |\n| Master | [![BuddyBuild](https://dashboard.buddybuild.com/api/statusImage?appID=59a9d6cad65c7a00012ae953\u0026branch=master\u0026build=latest)](https://dashboard.buddybuild.com/apps/59a9d6cad65c7a00012ae953/build/latest?branch=master) |\n| Develop | [![BuddyBuild](https://dashboard.buddybuild.com/api/statusImage?appID=59a9d6cad65c7a00012ae953\u0026branch=develop\u0026build=latest)](https://dashboard.buddybuild.com/apps/59a9d6cad65c7a00012ae953/build/latest?branch=develop) |\n\n# Table of Contents\n1. [How it works](#how-it-works)\n2. [Define entities](#define-entities)\n3. [CRUD](#crud)\n3. [Background operations](#background-operations)\n4. [Installation](#installation)\n5. [Core Mantainers](#core-mantainers)\n6. [Known issues](#known-issues)\n7. [TODO](#todo)\n8. [License](#license)\n9. [Credits](#credits)\n\n## How it works\nThe 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`:\n\n```\nlet storage = StorageKit.addStorage(type: .Realm)\n```\n\nor\n\n```\nlet storage = StorageKit.addStorage(type: .CoreData(dataModelName: \"Example\")\n```\n\nThe storage exposes a `context` which is the object you will use to perform the common *CRUD operations*, for instance:\n\n```\ntry storage.mainContext?.fetch(predicate: NSPredicate(format: \"done == false\"), sortDescriptors: [sortDescriptors], completion: { (fetchedTasks: [RTodoTask]?) in\n    self.tasks = fetchedTasks\n        // do whatever you want\n    }\n)\n```\n\nor \n\n```\nlet task = functionThatRetrieveASpecificTaskFromDatabase()\n\ndo {\n    try storage.mainContext?.delete(task)\n} catch {\n    // manage the error\n}\n```\n\nThat's it! 🎉\n\nIn just few lines of code you are able to use your favorite database (through the `Storage`) and perform any CRUD operations through the `StorageContext`.\n\n## Define Entities\nBoth [Core Data](https://developer.apple.com/documentation/coredata/nsmanagedobject) and [Realm](https://realm.io/docs/swift/latest/#models) relies on two base\n objects to define the entities:\n\n![Code Data Entity](https://raw.githubusercontent.com/StorageKit/StorageKit/master/Resources/entity_dog.png)\n\n```\nimport RealmSwift\n\nclass RTodoTask: Object {\n    dynamic var name = \"\"\n    dynamic var done = false\n    \n    override static func primaryKey() -\u003e String? {\n        return \"taskID\"\n    }\n}\n```\n\n*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.*\n\nYou can create a new entity using in this way:\n```\ndo {\n    try let entity: MyEntity = context.create()\n} catch {}\n```\n\n\u003e If you are using `Realm`, `entity` is an unmanaged object and it should be explicitily added to the database with:\n\n```\ndo {\n    try storage.mainContext?.add(entity)\n} catch {}\n```\n\n## CRUD\n### C as Create\n\n```\ndo {\n    try let entity: MyEntity = context.create()\n} catch {}\n```\n\nThis method creates a new entity object: an `NSManagedObject` for `Core Data` and an `Object` for `Realm`.\n\nNote\n\u003e 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.\n\u003e If you are using the Realm configuration, you have to add it in the storage before performing any update operations.\n\n\n```\ndo {\n    try let entity: MyEntity = context.create()\n    entity.myProperty = \"Hello\"\n\n    try context.add(entity)\n} catch {}\n```\n\n### R as Read\n\n```\n    try context.fetch { (result: [MyEntity]?) in\n        // do whatever you want with `result`\n    }\n```\n\nAs 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]?`.\n\n### U as Update\n\n```\ndo {\n    try context.update {\n        entity.myProperty = \"Hello\"\n        entity2.myProperty = \"Hello 2\"\n    }\n} catch {}\n```\n\nNote\n\u003e 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.\n\n### D as Delete\n\n```\ndo {\n    try let entity: MyEntity = context.create()\n    entity.myProperty = \"Hello\"\n\n    try context.delete(entity)\n} catch {}\n```\n\n## Background Operations\nGood 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 🎉\n\n[`Storage`](Source/Core/Storage/Storage.swift) exposes the following method:\n\n```\nstorage.performBackgroundTask {[weak self] backgroundContext in\n    // the backgroundContext might be nil because of internal errors\n    guard let backgroundContext = backgroundContext else { return }\n    \n    do {\n        // perform your background CRUD operations here on the `backgroundContext`\n           backgroundContext.fetch { [weak self] (entities: [MyEntity]?) in\n        // do something with `entities`\n    } catch {\n    \tprint(error.localizedDescription)\n    }\n}\n```\n\nNow 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`:\n\n```\nstorage.getThreadSafeEntities(for: context, originalContext: backgroundContext, originalEntities: fetchedTasks, completion: { safeFetchedTaks in\n    self?.tasks = safeFetchedTaks\n                    \n    DispatchQueue.main.async {\n        dispatchGroup.leave()\n    }\n})\n```\n\nThe method `func getThreadSafeEntities\u003cT: StorageEntityType\u003e(for destinationContext: StorageContext, originalContext: StorageContext, originalEntities: [T], completion: @escaping ([T]) -\u003e Void)` create an array of entities with the same data of `originalEntities` but thread safe, ready to be used in `destinatinationContext`.\n\nThis means that, once `getThreadSafeEntities` is called, you will be able to use the entities returned by `completion: @escaping ([T]) -\u003e Void)` in the choosen context.\n\nThe common use of this method is:\n1. perform a background operation (for instance a fetch) in `performBackgroundTask`\n2. move the entities retrieved to the main context using `getThreadSafeEntities`\n\n```\nstorage.performBackgroundTask {[weak self] (backgroundContext, backgroundQueue) in\n    guard let backgroundContext = backgroundContext else { return }\n    \n    do {\n        // 1\n        backgroundContext.fetch { [weak self] (entities: [MyEntity]?) in\n            // 2\n            storage.getThreadSafeEntities(for: context, originalContext: backgroundContext, originalEntities: entities, completion: { safeEntities in\n                self?.entities = safeEntities\n\t        })\n\t    }\n    } catch {\n    \tprint(error.localizedDescription)\n    }\n}\n```\n\n## Installation\n## CocoaPods\nAdd `StorageKit` to your Podfile\n\n```ruby\nuse_frameworks!\ntarget 'MyTarget' do\n    pod 'StorageKit', '~\u003e 0.3.1'\nend\n```\n\n```bash\n$ pod install\n```\n\n## Carthage\n```ruby\ngithub \"StorageKit/StorageKit\" ~\u003e \"0.3.1\"\n```\n\nThen on your application target *Build Phases* settings tab, add a \"New Run Script Phase\". Create a Run Script with the following content:\n\n```ruby\n/usr/local/bin/carthage copy-frameworks\n```\n\nand add the following paths under \"Input Files\":\n\n```ruby\n$(SRCROOT)/Carthage/Build/iOS/StorageKit.framework\n```\n\n## Core Mantainers \n| Guardians | |\n| ------------- | ------------- |\n| Ennio Masi | [@ennioma](https://twitter.com/ennioma) |\n| Marco Santarossa | [@MarcoSantaDev](https://twitter.com/MarcoSantaDev) |\n\n## Known Issues\n* Now it's not possible to exclude `Realm.framework` and `RealmSwift.framework` from the installation\n* UI Test target doesn't work in the example project\n\n## TODO\n* Remove Realm dependency if not needed (the user can decide between Core Data or Realm)\n* Add Reactive interface\n* Distribute through the Swift Package Manager\n* Add more functionalities to the context\n* Add notifications\n* Add migrations\n\n## License\nStorageKit is available under the MIT license. See the [LICENSE](LICENSE) file for more info.\n\n## Credits:\nBoxes icon provided by `Nuon Project` ([LLuisa Iborra](https://thenounproject.com/marialuisa.iborra/)). We have changed the boxes color.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FStorageKit%2FStorageKit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FStorageKit%2FStorageKit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FStorageKit%2FStorageKit/lists"}