# Blaze

A wrapper that simplifies interactions with the
[official Cloud Firestore API](https://github.com/googleapis/elixir-google-api/tree/master/clients/firestore).

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](#usage) below for more information.

## Installation

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

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

For online document, see [https://hexdocs.pm/blaze](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:

```elixir
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`.