Get Started with EasyFirestore

Overview

Welcome to EasyFirestore! 🎉

EasyFirestore makes it fast and easy to:

• store, update, and retrieve documents quickly
• format data into documents and models that are ready to use with Firestore
• easily link child documents to a list of document ID's in a parent document
• retrieve a list of child documents given a list of ID's
• query for documents in a Swift-y manner

Benefits of EasyFirestore:

• 📦 Out-of-the-box cacheing saves your Firestore read count
• 🤔 Tackle database problems with ease using EasyFirestore's linking methods
• 📈 Automatically track metrics such as document indexes using the Singleton protocol

Requisites

• Installation

What You'll Learn

In this page, you'll learn about:

1. Topic →

Get Started

Setting up Firestore in Firebase Console

To get started, you'll need to set up Firestore in your Firebase console. Find the Firestore tab and click the Get Started button.

Start in test mode, then click Next.

Pick a suitable database location, then click Enable.

You're good to go!

Create a Document Type

You'll first need to create a type that conforms to the Document protocol:

class ExampleDocument: Document {
  
}

Every class that conforms to Document has two required properties:

Property Name	Description
id	The unique identifier of the document.
dateCreated	The date the document object was created.

You'll need to add your own custom properties as well:

class ExampleDocument: Document {
  
  // These properties are required by the Document protocol.
  var id: String
  var dateCreated: Date
  
  // These properties are custom.
  var foodName: String = ""
  var calories: Int = 0
}

Sending a Document to Firestore

Once you have local instances of your Document, you can easily set your documents in Firestore using:

myDocument.set()

Equivalently, you can use the EasyFirestore.Storage helper struct to send the document:

EasyFirestore.Storage.set(myDocument)

Most EasyFirestore methods like set() have optional completion handlers, which are called when the operation is complete:

myDocument.set(completion: { error in
  if let error = error {
    print("An error occured! \(error.localizedDescription)")
  } else {
    // No problems setting the document in Firestore.
  }
})

Conversely, the document can easily be deleted:

EasyFirestore.Removal.remove(myDocument)

Linking to an Array of Document IDs

Every document has an id. If you wish to store a list of documents in another document type, it's useful to store a list of document IDs rather than the documents themselves to save on the size of a document. EasyFirestore makes document linking easy with pre-defined methods.

To see this in action, consider a Dealership document type with a list of car ID's, cars, of document type Car:

class Dealership: Document {
  // DocumentID is equivalent to a String, and is available when you import EasyFirebase.
  var cars: [DocumentID]

  // ...
} 

class Car: Document {
  var make: String
  var model: String
  var year: Int

  // ...
}

We create a Car object and link it to the dealership:

let car = new Car(make: "Toyota", model: "Corolla", year: 2017)
car.assign(toField: "cars", using: \.cars, in: dealership)

If you wish to link the object and send it, you can use setAssign(...):

car.setAssign(toField: "cars", using: \.cars, in: dealership)

Again, the EasyFirestore.Linking helper struct can be used to do this.

ℹ️ Quick Tip

EasyFirestore has many helper structs, including Storage, Retrieval, Querying, Updating, Removal, Linking, Cacheing, and Listening.

Retrieving Data from Firestore