🧢
Ballcap-iOS
Ballcap is a database schema design framework for Cloud Firestore.
Why Ballcap
Cloud Firestore is a great schema-less and flexible database that can handle data. However, its flexibility can create many bugs in development. Ballcap can assign schemas to Cloud Firestore to visualize data structures. This plays a very important role when developing as a team.
Inspired by https://github.com/firebase/firebase-ios-sdk/tree/pb-codable3
Please donate to continue development.
- Ballcap for TypeScript: https://github.com/1amageek/ballcap.ts
Sameple projects
- Messagestore Chat framework created by Cloud Firestore.
Feature
Requirements
❗️
- iOS 10 or later
- Swift 5.0 or later
- Firebase firestore
- Firebase storage
Installation
⚙
CocoaPods
- Insert
pod 'Ballcap'to your Podfile. - Run
pod install.
If you have a Feature Request, please post an issue.
Usage
Document scheme
You must conform to the Codable and Modelable protocols to define Scheme.
struct Model: Codable, Equatable, Modelable {
var number: Int = 0
var string: String = "Ballcap"
}
Initialization
The document is initialized as follows:
// use auto id
let document: Document<Model> = Document()
print(document.data?.number) // 0
print(document.data?.string) // "Ballcap"
// KeyPath
print(document[\.number]) // 0
print(document[\.string]) // "Ballcap"
// Use your specified ID
let document: Document<Model> = Document(id: "YOUR_ID")
print(document.data?.number) // 0
print(document.data?.string) // "Ballcap"
// KeyPath
print(document[\.number]) // 0
print(document[\.string]) // "Ballcap"
// Use your specified DocumentReference
let documentReference: DocumentReference = Firestore.firestore().document("collection/document")
// note: If DocumentReference is specified, data is initialized with nil.
let document: Document<Model> = Document(documentReference)
print(document.data?.number) // nil
print(document.data?.string) // nil
// KeyPath
print(document[\.number]) // fail
print(document[\.string]) // fail
CRUD
Ballcap has a cache internally.When using the cache, use Batch instead of WriteBatch.
// save
document.save()
// update
document.update()
// delete
document.delete()
// Batch
let batch: Batch = Batch()
batch.save(document: document)
batch.update(document: document)
batch.delete(document: document)
batch.commit()
You can get data by using the get function.
Document<Model>.get(id: "DOCUMENT_ID", completion: { (document, error) in
print(document.data)
})
The next get function gets data in favor of the cache. If there is no cached data, it gets from the server.
let document: Document<Model> = Document("DOCUMENT_ID")
document.get { (document, error) in
print(document.data)
}
Why data is optional?
In CloudFirestore, DocumentReference does not necessarily have data. There are cases where there is no data under the following conditions.
- If no data is stored in DocumentReference.
- If data was acquired using
Source.cachefrom DocumentReference, but there is no data in cache.
Ballcap recommends that developers unwrap if they can determine that there is data.
It is also possible to access the cache without using the network.
let document: Document<Model> = Document(id: "DOCUMENT_ID")
print(document.cache?.number) // 0
print(document.cache?.string) // "Ballcap"
Custom properties
Ballcap is preparing custom property to correspond to FieldValue.
ServerTimestamp
Property for handling FieldValue.serverTimestamp()
struct Model: Codable, Equatable {
let serverValue: ServerTimestamp
let localValue: ServerTimestamp
}
let model = Model(serverValue: .pending,
localValue: .resolved(Timestamp(seconds: 0, nanoseconds: 0)))
IncrementableInt & IncrementableDouble
Property for handling FieldValue.increment()
struct Model: Codable, Equatable, Modelable {
var num: IncrementableInt = 0
}
let document: Document<Model> = Document()
document.data?.num = .increment(1)
OperableArray
Property for handling FieldValue.arrayRemove(), FieldValue.arrayUnion()
struct Model: Codable, Equatable, Modelable {
var array: OperableArray<Int> = [0, 0]
}
let document: Document<Model> = Document()
document.data?.array = .arrayUnion([1])
document.data?.array = .arrayRemove([1])
File
File is a class for accessing Firestorage. You can save Data in the same path as Document by the follow:
let document: Document<Model> = Document(id: "DOCUMENT_ID")
let file: File = File(document.storageReference)
File supports multiple MIMETypes. Although File infers MIMEType from the name, it is better to input MIMEType explicitly.
- plain
- csv
- html
- css
- javascript
- octetStream(String?)
- zip
- tar
- lzh
- jpeg
- pjpeg
- png
- gif
- mp4
- custom(String, String)
Upload & Download
Upload and Download each return a task. You can manage your progress by accessing tasks.
// upload
let ref: StorageReference = Storage.storage().reference().child("/a")
let data: Data = "test".data(using: .utf8)!
let file: File = File(ref, data: data, name: "n", mimeType: .plain)
let task = file.save { (metadata, error) in
}
// download
let task = file.getData(completion: { (data, error) in
let text: String = String(data: data!, encoding: .utf8)!
})
StorageBatch
StorageBatch is used when uploading multiple files to Cloud Storage.
let textData: Data = "test".data(using: .utf8)!
let textFile: File = File(Storage.storage().reference(withPath: "c"), data: textData, mimeType: .plain)
batch.save(textFile)
let jpgData: Data = image.jpegData(compressionQuality: 1)!
let jpgFile: File = File(Storage.storage().reference(withPath: "d"), jpgData: textData, mimeType: .jpeg)
batch.save(jpgFile)
batch.commit { error in
}
DataSource
Ballcap provides a DataSource for easy handling of Collections and SubCollections.
DataSource initialize
from Document
let dataSource: DataSource<Item> = Document<Item>.query.dataSource()
from Collection Reference
CollectionReference
let query: DataSource<Document<Item>>.Query = DataSource.Query(Firestore.firestore().collection("items"))
let dataSource = DataSource(reference: query)
CollectionGroup
let query: DataSource<Document<Item>>.Query = DataSource.Query(Firestore.firestore().collectionGroup("items"))
let dataSource = DataSource(reference: query)
Your custom object
// from Custom class
let dataSource: DataSource<Item> = Item.query.dataSource()
// from CollectionReference
let query: DataSource<Item>.Query = DataSource.Query(Item.collectionReference)
let dataSource: DataSource<Item> = query.dataSource()
NSDiffableDataSourceSnapshot
self.dataSource = Document<Item>.query
.order(by: "updatedAt", descending: true)
.limit(to: 3)
.dataSource()
.retrieve(from: { (snapshot, documentSnapshot, done) in
let document: Document<Item> = Document(documentSnapshot.reference)
document.get { (item, error) in
done(item!)
}
})
.onChanged({ (snapshot, dataSourceSnapshot) in
var snapshot: NSDiffableDataSourceSnapshot<Section, DocumentProxy<Item>> = self.tableViewDataSource.snapshot()
snapshot.appendItems(dataSourceSnapshot.changes.insertions.map { DocumentProxy(document: $0)})
snapshot.deleteItems(dataSourceSnapshot.changes.deletions.map { DocumentProxy(document: $0)})
snapshot.reloadItems(dataSourceSnapshot.changes.modifications.map { DocumentProxy(document: $0)})
self.tableViewDataSource.apply(snapshot, animatingDifferences: true)
})
.listen()
UITableViewDelegate, UITableViewDataSource
self.dataSource = Document<Item>.query
.order(by: "updatedAt", descending: true)
.limit(to: 3)
.dataSource()
.retrieve(from: { (snapshot, documentSnapshot, done) in
let document: Document<Item> = Document(documentSnapshot.reference)
document.get { (item, error) in
done(item!)
}
})
.onChanged({ (snapshot, dataSourceSnapshot) in
self.tableView.performBatchUpdates({
self.tableView.insertRows(at: dataSourceSnapshot.changes.insertions.map { IndexPath(item: dataSourceSnapshot.after.firstIndex(of: $0)!, section: 0)}, with: .automatic)
self.tableView.deleteRows(at: dataSourceSnapshot.changes.deletions.map { IndexPath(item: dataSourceSnapshot.before.firstIndex(of: $0)!, section: 0)}, with: .automatic)
self.tableView.reloadRows(at: dataSourceSnapshot.changes.modifications.map { IndexPath(item: dataSourceSnapshot.after.firstIndex(of: $0)!, section: 0)}, with: .automatic)
}, completion: nil)
})
.listen()
Relationship between Document and Object
Document is a class that inherits Object. For simple operations, it is enough to use Document.
public final class Document<Model: Modelable & Codable>: Object, DataRepresentable, DataCacheable {
public var data: Model?
}
You can perform complex operations by extending Object and defining your own class. Use examples are explained in Using Ballcap with SwiftUI
Migrate from Pring
Overview
The difference from Pring is that ReferenceCollection and NestedCollection have been abolished. In Pring, adding a child Object to the ReferenceCollection and NestedCollection of the parent Object saved the parent Object at the same time when it was saved. Ballcap requires the developer to save SubCollection using Batch. In addition, Pring also saved the File at the same time as the Object with the File was saved. Ballcap requires that developers save files using StorageBatch.
Scheme
Ballcap can handle Object class by inheriting Object class like Pring. If you inherit Object class, you must conform to DataRepresentable.
class Room: Object, DataRepresentable {
var data: Model?
struct Model: Modelable & Codable {
var members: [String] = []
}
}
SubCollection
Ballcap has discontinued NestedCollection and ReferenceCollection Class. Instead, it represents SubCollection by defining CollectionKeys.
Class must match HierarchicalStructurable to use CollectionKeys.
class Room: Object, DataRepresentable & HierarchicalStructurable {
var data: Model?
var transcripts: [Transcript] = []
struct Model: Modelable & Codable {
var members: [String] = []
}
enum CollectionKeys: String {
case transcripts
}
}
Use the collection function to access the SubCollection.
let collectionReference: CollectionReference = obj.collection(path: .transcripts)
SubCollection's Document save
let batch: Batch = Batch()
let room: Room = Room()
batch.save(room.transcripts, to: room.collection(path: .transcripts))
batch.commit()
Using Ballcap with SwiftUI
First, create an object that conforms to ObservableObject. DataListenable makes an Object observable.
final class User: Object, DataRepresentable, DataListenable, ObservableObject, Identifiable {
typealias ID = String
override class var name: String { "users" }
struct Model: Codable, Modelable {
var name: String = ""
}
@Published var data: User.Model?
var listener: ListenerRegistration?
}
Next, create a View that displays this object.
struct UserView: View {
@ObservedObject var user: User
@State var isPresented: Bool = false
var body: some View {
VStack {
Text(user[\.name])
}
.navigationBarTitle(Text("User"))
.navigationBarItems(trailing: Button("Edit") {
self.isPresented.toggle()
})
.sheet(isPresented: $isPresented) {
UserEditView(user: self.user.copy(), isPresented: self.$isPresented)
}
.onAppear {
_ = self.user.listen()
}
}
}
You can access the object data using subscript.
Text(user[\.name])
Start user observation with onAppear.
.onAppear {
_ = self.user.listen()
}
Copy object
Pass a copy of Object to EditView before editing the data.
.sheet(isPresented: $isPresented) {
UserEditView(user: self.user.copy(), isPresented: self.$isPresented)
}
Since the Object is being observed by the listener, changes can be caught automatically.
Finally, create a view that can update the object.
struct UserEditView: View {
@ObservedObject var user: User
@Binding var isPresented: Bool
var body: some View {
VStack {
Form {
Section(header: Text("Name")) {
TextField("Name", text: $user[\.name])
}
}
Button("Save") {
self.user.update()
self.isPresented.toggle()
}
}.frame(height: 200)
}
}
Updating an object is possible only with update().
Button("Update") {
self.user.update()
self.isPresented.toggle()
}
7 Aug 1, 2022
2 Oct 16, 2022
0 Jan 24, 2022
0 Dec 20, 2021
2 Mar 23, 2022
1 Jan 3, 2023
17 Dec 11, 2022
0 Nov 28, 2021
2.5k Jan 1, 2023
0 Feb 13, 2022
2 Sep 20, 2022
337 Dec 25, 2022
43 Dec 22, 2022
0 Oct 6, 2021
2 Jul 11, 2022
1 Nov 20, 2021
2 Jul 31, 2022
0 Dec 19, 2021
0 Dec 26, 2021