README.md

🗂 Stores

A typed key-value storage solution to store Codable types in various persistence layers like User Defaults, File System, Core Data, Keychain, and more with a few lines of code!

Features

• macOS Catalina+, iOS 13+, tvOS 13+, watchOS 6+, any Linux supporting Swift 5.4+.
• Store any Codable type.
• Single API with implementations using User Default, file system, Core Data, Keychain, and fakes for testing.
• Thread-safe implementations.
• Swappable implementations with a type-erased store.
• Modular library, add all, or only what you need.

---

Motivation

When working on an app that uses the composable architecture, I fell in love with how reducers use an environment type that holds any dependencies the feature needs, such as API clients, analytics clients, and more.

Stores tries to abstract the concept of a store and provide various implementations that can be injected in such environment and swapped easily when running tests or based on a remote flag.

It all boils down to the two protocols SingleObjectStore and MultiObjectStore defined in the Blueprints layer, which provide the abstract concepts of stores that can store a single or multiple objects of a generic Codable type.

The two protocols are then implemented in the different modules as explained in the chart below:

---

Usage

Let's say you have a User struct defined as below:

struct User: Codable {
    let id: Int
    let name: String
}

Here's how you store it using Stores:

1. Conform to Identifiable

This is required to make the store associate an object with its id.

extension User: Identifiable {}

The property id can be on any Hashable type. Read more.

2. Create a store

Stores comes pre-equipped with the following stores:

• UserDefaults

  // Store for multiple objects
  let store = MultiUserDefaultsStore<User>(suiteName: "users")
  
  // Store for a single object
  let store = SingleUserDefaultsStore<User>(suiteName: "users")

• FileSystem

  // Store for multiple objects
  let store = MultiFileSystemStore<User>(path: "users")
  
  // Store for a single object
  let store = SingleFileSystemStore<User>(path: "users")

• CoreData

  // Store for multiple objects
  let store = MultiCoreDataStore<User>(databaseName: "users")
  
  // Store for a single object
  let store = SingleCoreDataStore<User>(databaseName: "users")

• Keychain

  // Store for multiple objects
  let store = MultiKeychainStore<User>(identifier: "users")
  
  // Store for a single object
  let store = SingleKeychainStore<User>(identifier: "users")

• Fakes (for testing)

  // Store for multiple objects
  let store = MultiObjectStoreFake<User>()
  
  // Store for a single object
  let store = SingleObjectStoreFake<User>()

You can create a custom store by implementing the protocols in Blueprints

• Realm

  // Store for multiple objects
  final class MultiRealmStore<Object: Codable & Identifiable>: MultiObjectStore {
      // ...
  }
  
  // Store for a single object
  final class SingleRealmStore<Object: Codable>: SingleObjectStore {
      // ...
  }

• SQLite

  // Store for multiple objects
  final class MultiSQLiteStore<Object: Codable & Identifiable>: MultiObjectStore {
      // ...
  }
  
  // Store for a single object
  final class SingleSQLiteStore<Object: Codable>: SingleObjectStore {
      // ...
  }

3. Inject the store

Assuming we have a view model that uses a store to fetch data:

struct UsersViewModel {
    let store: AnyMultiObjectStore<User>
}

Inject the appropriate store implementation:

let coreDataStore = MultiCoreDataStore<User>(databaseName: "users")
let prodViewModel = UsersViewModel(store: coreDataStore.eraseToAnyStore())

or:

let fakeStore = MultiObjectStoreFake<User>()
let testViewModel = UsersViewModel(store: fakeStore.eraseToAnyStore())

4. Save, retrieve, update, or remove objects

let john = User(id: 1, name: "John Appleseed")

// Save an object to a store
try store.save(john)

// Save an array of objects to a store
try store.save([jane, steve, jessica])

// Get an object from store
let user = store.object(withId: 1)

// Get an array of object in store
let users = store.objects(withIds: [1, 2, 3])

// Get an array of all objects in store
let allUsers = store.allObjects()

// Check if store has an object
print(store.containsObject(withId: 10)) // false

// Remove an object from a store
try store.remove(withId: 1)

// Remove multiple objects from a store
try store.remove(withIds: [1, 2, 3])

// Remove all objects in a store
try store.removeAll()

---

Documentation

Read the full documentation at Swift Package Index.

---

Installation

You can add Stores to an Xcode project by adding it as a package dependency.

1. From the File menu, select Add Packages...
2. Enter "https://github.com/omaralbeik/Stores" into the package repository URL text field
3. Depending on what you want to use Stores for, add the following target(s) to your app:
   • Stores: the entire library with all stores.
   • UserDefaultsStore: use User Defaults to persist data.
   • FileSystemStore: persist data by saving it to the file system.
   • CoreDataStore: use a Core Data database to persist data.
   • KeychainStore: persist data securely in the Keychain.
   • Blueprints: protocols only, this is a good option if you do not want to use any of the provided stores and build yours.
   • StoresTestUtils to use the fakes in your tests target.

---

Credits and thanks

• Tom Harrington for writing "Core Data Using Only Code".
• Keith Harrison for writing "Testing Core Data In A Swift Package".
• Riccardo Cipolleschi for writing Retrieve multiple values from Keychain.

---

License

Stores is released under the MIT license. See LICENSE for more information.