Blaze

A wrapper that simplifies interactions with the official Cloud Firestore API.

If you've ever worked with any of the official Elixir client libraries for Google Cloud, you'll know that they aren't typically simple to interact with. Although it's great that all of the libraries are generated by a tool rather than created by hand, some of the conventions chosen for the final output are less than ideal. This is even more prominent with the Firebase APIs.

Firestore especially is frustrating because every document is wrapped in a model with every field in the document wrapped in a model with sometimes the values of those fields being wrapped in models. It's just layer upon layer of custom models.

Blaze was created to simplify that interaction with Firestore. Instead of wrapping objects in models, you simply pass in Elixir primitives such as lists, maps, and whatever else. All of the conversions to and from models are handled automatically. If you need to use any of the special features or data types available to Firestore, you can do so simply by storing your values as tuples where the first element is a special key representing the Firestore-native data type and the second element is the Elixir primitive that represents it. See Usage below for more information.

Installation

Add blaze to your list of dependencies in mix.exs:

def deps do
  [
    {:blaze, "~> 0.1.0"}
  ]
end

For online document, see https://hexdocs.pm/blaze.

Usage

Currently there is only one API made available through Blaze: document interaction. You can create, retrieve, delete, modify, list, and query for documents using Blaze.API.

When querying for documents, it is recommended to use Blaze.Query to build valid structured query objects in a simple and composable manner. For example:

defmodule Books do
  import Blaze.Query

  @parent_path "projects/my-book-project/databases/(default)/documents"
  @book_collection "books"

  def by(author) do
    @book_collection
    |> from()
    |> where(author: author)
    |> limit(20)
  end

  def published_before(date) do
    @book_collection
    |> from()
    |> where(published: {:lt, {:__firestore_time, 1588268380}})
    |> limit(20)
  end
end

In the above example we see:

• That from accepts a collection id and generates a query object which can be composed with any other query-related function from Blaze.Query.
• That where accepts values of multiple forms. In the case of searching for an author, setting the value to any non-tuple is equivalent to an equality condition, e.g. field == value. If a tuple is given, the first element is a custom operator and the second element is the value. In the case of looking for books published before a certain date, we see that the value is, itself, a tuple that is specifying we want to use the Firestore-native timestamp data type.
• That we can limit the maximum number of results returned.

There are more query functions that you can read about in the documentation for Blaze.Query.