Documentation
¶
Overview ¶
Package document provides generic methods to interact with Firestore documents.
A Fuego document provides useful functions allowing to easily manipulate Firestore documents.
Usage ¶
Creating a document is straightforward:
type User struct {
FirstName string `firestore:"FirstName"`
LastName string `firestore:"LastName"`
EmailAddress string `firestore:"EmailAddress"`
Address string `firestore:"Address"`
Tokens map[string]string `firestore:"Tokens"`
}
err := fuego.Document("users", "jsmith").Create(ctx, user)
if err != nil {
panic(err)
}
In some cases, you may want to create a document and let Firebase generated a unique ID for you. Fuego supports this:
err := fuego.DocumentWithGeneratedID("users").Create(ctx, user)
Retrieving a document as even simpler:
user := User{}
err := fuego.Document("users", "jsmith").Retrieve(ctx, &user)
You also may want to only check if a given document exists without providing a struct:
// Note: false will be returned if an error occurs as well
value := fuego.Document("users", "jsmith").Exists(ctx)
Fields - All types ¶
Fuego also allow to easily manipulate specific fields of a document (e.g. retrieve, update, increment, ...) It supports all the fields offered by Firestore at the exception of geopoints and references.
Usage ¶
Retrieving a field is almost as simple as retrieving a document:
value, err := fuego.Document("users", "jsmith").String("FirstName").Retrieve(ctx)
Updating a field:
err := fuego.Document("users", "jsmith").String("FirstName").Update(ctx, "Mike")
Fields - Numbers ¶
Numbers are stored in Firestore as int64. Fuego provides operations that are frequently performed with number fields.
For instance, you may want to increment or decrement a number field. With Fuego, this can be done in one single operatipn. It uses Transactions underneath.
err := fuego.Document("users", "jsmith").Number(Age).Increment(ctx)
// or
err := fuego.Document("users", "ben_button").Number(Age).Decrement(ctx)
Fields - Arrays ¶
As you may know, dealing with arrays in Firestore documents can be somewhat of a burden. When updating an array field, the entire field is overridden. Using Fuego, you can decide to either override or append to the field:
err := fuego.Document("users", "jsmith").
Array("Address").
Override(ctx, []interface{}{"4th Floor"})
// or...
err := fuego.Document("users", "jsmith").
Array("Address").
Append(ctx, []interface{}{"4th Floor"})
Of course, you can also retrieve an array as follow:
values, err := fuego.Document("users", "jsmith").Array("Address").Retrieve(ctx)
if err != nil {
panic(err)
}
// Note the required type assertion
fmt.Println("First Element: ", values[0].(string))
Fields - Timestamp ¶
Timestamp fields work the same way as the other fields except that a timezone (IANA Time Zone) needs to be provided at retrieval:
val, err := fuego.Document("users", "jsmith").Timestamp("LastSeenAt").Retrieve(ctx, "America/Los_Angeles")
Package document provides generic methods to interact with Firestore documents.
Index ¶
- Variables
- type Array
- type ArrayField
- type Boolean
- type BooleanField
- type Document
- type FirestoreDocument
- func (d *FirestoreDocument) Array(name string) *Array
- func (d *FirestoreDocument) Batch() *firestore.WriteBatch
- func (d *FirestoreDocument) Boolean(name string) *Boolean
- func (d *FirestoreDocument) Create(ctx context.Context, from interface{}) error
- func (d *FirestoreDocument) Delete(ctx context.Context) error
- func (d *FirestoreDocument) Exists(ctx context.Context) bool
- func (d *FirestoreDocument) GetDocumentRef() *firestore.DocumentRef
- func (d *FirestoreDocument) InBatch() bool
- func (d *FirestoreDocument) Map(name string) *Map
- func (d *FirestoreDocument) Number(name string) *Number
- func (d *FirestoreDocument) Retrieve(ctx context.Context, to interface{}) error
- func (d *FirestoreDocument) String(name string) *String
- func (d *FirestoreDocument) Timestamp(name string) *Timestamp
- type Map
- type MapField
- type Number
- type NumberField
- type String
- type StringField
- type Timestamp
- type TimestampField
Constants ¶
This section is empty.
Variables ¶
var ( // ErrDocumentNotExist indicates that the requested document doesn't exist. ErrDocumentNotExist = errors.New("document: doesn't exist") // ErrFieldRetrieve indicates that the requested field value could not be retrieved. ErrFieldRetrieve = errors.New("field: couldn't retrieve the field value") )
Functions ¶
This section is empty.
Types ¶
type Array ¶
type Array struct {
// Document is the underlying document (incl. ID and ref).
Document Document
// Name is the name of the field.
Name string
// contains filtered or unexported fields
}
Array represents a document field of type Array.
func (*Array) Append ¶
Append will append the provided data to the existing data (if any) of an Array field.
The update will be executed inside a transaction.
values, err := fuego.Document("users", "jsmith").Array("Address").Append(ctx, []interface{}{"More info"})
type ArrayField ¶
type ArrayField interface {
// Retrieve returns the value of a specific field containing an array.
//
// note : the returned data will require a type assertion.
Retrieve(ctx context.Context) ([]interface{}, error)
// Append will append the provided data to the existing data (if any) of an Array field.
Append(ctx context.Context, data []interface{}) error
// Override will override the existing data (if any) of an Array field.
// Note: this is the default behaviour with Firestore.
Override(ctx context.Context, data []interface{}) error
}
ArrayField provides the necessary to interact with a Firestore document field of type Array.
type Boolean ¶
type Boolean struct {
// Document is the underlying document (incl. ID and ref).
Document Document
// Name is the name of the field.
Name string
}
Boolean represents a document field of type Boolean.
type BooleanField ¶
type BooleanField interface {
// Retrieve returns the value of a specific field containing a Boolean (bool).
Retrieve(ctx context.Context) (bool, error)
// Update updates the value of a specific field containing a Boolean (bool).
Update(ctx context.Context, with bool) error
}
BooleanField provides the necessary to interact with a Firestore document field of type Boolean.
type Document ¶
type Document interface {
// Create a document.
Create(ctx context.Context, from interface{}) error
// Retrieve populate the destination passed as parameter.
//
// note: the `to` parameter has to be a pointer.
Retrieve(ctx context.Context, to interface{}) error
// Exists returns true if the document exists, false otherwise.
//
// note: if an error occurs, false is also returned.
Exists(ctx context.Context) bool
// Delete removes a document from Firestore.
Delete(ctx context.Context) error
// Array returns a specific Array field.
Array(name string) *Array
// String returns a specific String field.
String(name string) *String
// Number returns a specific Number field.
Number(name string) *Number
// Boolean returns a specific Boolean field.
Boolean(name string) *Boolean
// Map returns a specific Map field.
Map(name string) *Map
// Timestamp returns a specific Timestamp field.
Timestamp(name string) *Timestamp
// GetDocumentRef returns a Document Reference (DocumentRef).
GetDocumentRef() *firestore.DocumentRef
// InBatch returns true if a WriteBatch has been started, false otherwise.
InBatch() bool
// Batch returns the pointer to the WriteBatch (if any), nil oherwise.
Batch() *firestore.WriteBatch
}
Document provides the necessary to interact with a Firestore document.
type FirestoreDocument ¶
type FirestoreDocument struct {
// ColRef (firestore.CollectionRef) is a reference to the collection.
ColRef *firestore.CollectionRef
// ID is the ID of the document
ID string
// contains filtered or unexported fields
}
FirestoreDocument provides features related to Firestore documents.
func New ¶
func New(fs *firestore.Client, path, documentID string, wb *firestore.WriteBatch) *FirestoreDocument
New creates and returns a new FirestoreDocument.
func (*FirestoreDocument) Array ¶
func (d *FirestoreDocument) Array(name string) *Array
Array returns a new Array.
func (*FirestoreDocument) Batch ¶
func (d *FirestoreDocument) Batch() *firestore.WriteBatch
Batch returns the pointer to the WriteBatch (if any), nil oherwise.
func (*FirestoreDocument) Boolean ¶
func (d *FirestoreDocument) Boolean(name string) *Boolean
Boolean returns a new Boolean.
func (*FirestoreDocument) Create ¶
func (d *FirestoreDocument) Create(ctx context.Context, from interface{}) error
Create a document in Firestore.
func (*FirestoreDocument) Delete ¶
func (d *FirestoreDocument) Delete(ctx context.Context) error
Delete removes a document from Firestore.
func (*FirestoreDocument) Exists ¶
func (d *FirestoreDocument) Exists(ctx context.Context) bool
Exists returns true if a given document exists, false otherwise.
func (*FirestoreDocument) GetDocumentRef ¶
func (d *FirestoreDocument) GetDocumentRef() *firestore.DocumentRef
GetDocumentRef returns a document reference.
func (*FirestoreDocument) InBatch ¶
func (d *FirestoreDocument) InBatch() bool
InBatch returns true if a WriteBatch has been started, false otherwise.
func (*FirestoreDocument) Map ¶
func (d *FirestoreDocument) Map(name string) *Map
Map returns a new Map.
func (*FirestoreDocument) Number ¶
func (d *FirestoreDocument) Number(name string) *Number
Number returns a new Number.
func (*FirestoreDocument) Retrieve ¶
func (d *FirestoreDocument) Retrieve(ctx context.Context, to interface{}) error
Retrieve a document from Firestore.
to: the destination must be a pointer.
func (*FirestoreDocument) String ¶
func (d *FirestoreDocument) String(name string) *String
String returns a new String.
func (*FirestoreDocument) Timestamp ¶
func (d *FirestoreDocument) Timestamp(name string) *Timestamp
Timestamp returns a new Timestamp.
type Map ¶
type Map struct {
// Document is the underlying document (incl. ID and ref).
Document Document
// Name is the name of the field.
Name string
// contains filtered or unexported fields
}
Map represents a document field of type Map.
type MapField ¶
type MapField interface {
// Retrieve returns the value of a specific field containing a map.
//
// note : the returned values will require type assertion.
Retrieve(ctx context.Context) (map[string]interface{}, error)
// Merge will merge the provided data with the existing data (if any) of a Map field.
// Note: this is the default behaviour with Firestore.
Merge(ctx context.Context, data map[string]interface{}) error
// Override will override the existing data (if any) withthe provided data.
Override(ctx context.Context, data map[string]interface{}) error
}
MapField provides the necessary to interact with a Firestore document field of type Map.
type Number ¶
type Number struct {
// Document is the underlying document (incl. ID and ref).
Document Document
// Name is the name of the field.
Name string
// contains filtered or unexported fields
}
Number represents a document field of type Number.
func (*Number) Decrement ¶
Decrement the value of a specific field of type Number.
The update will be executed inside a transaction. If the field doesn't exist, it will be set to 0.
err := fuego.Document("users", "jsmith").Number("Age").Decrement(ctx)
func (*Number) Increment ¶
Increment the value of a specific field of type Number.
The update will be executed inside a transaction. If the field doesn't exist, it will be set to 1.
err := fuego.Document("users", "jsmith").Number("Age").Increment(ctx)
type NumberField ¶
type NumberField interface {
// Retrieve returns the value of a specific field containing a number (int64).
Retrieve(ctx context.Context) (int64, error)
// Update the value of a specific field containing a number (int64).
Update(ctx context.Context, with int64) error
// Increment the value of a specific field containing a number (int64).
// If the field doesn't exist, it will be set to 1.
Increment(ctx context.Context) error
// Decrement the value of a specific field containing a number (int64).
// If the field doesn't exist, it will be set to 0.
Decrement(ctx context.Context) error
}
NumberField provides the necessary to interact with a Firestore document field of type Number.
type String ¶
type String struct {
// Document is the underlying document (incl. ID and ref).
Document Document
// Name is the name of the field.
Name string
}
String represents a document field of type String.
type StringField ¶
type StringField interface {
// Retrieve returns the value of a specific field containing an string.
Retrieve(ctx context.Context) (string, error)
// Update updates the value of a specific field containing a string.
Update(ctx context.Context, with string) error
}
StringField provides the necessary to interact with a Firestore document field of type String.
type Timestamp ¶
type Timestamp struct {
// Document is the underlying document (incl. ID and ref).
Document Document
// Name is the name of the field.
Name string
}
Timestamp represents a document field of type Timestamp.
func (*Timestamp) Retrieve ¶
Retrieve returns the content of a specific field for a given document.
location needs to be a value from the IANA Time Zone database A time.Time zero value will be returned if an error occurs.
val, err := fuego.Document("users", "jsmith").Timestamp("LastSeenAt").Retrieve(ctx, "America/Los_Angeles")
type TimestampField ¶
type TimestampField interface {
// Retrieve returns the value of a specific field containing a timestamp (time.Time).
//
// location needs to be a value from the IANA Time Zone database (e.g. "America/Los_Angeles")
// A time.Time zero value will be returned if an error occurs.
Retrieve(ctx context.Context, location string) (time.Time, error)
// Update updates the value of a specific field containing a timestamp (time.Time).
Update(ctx context.Context, with time.Time) error
}
TimestampField provides the necessary to interact with a Firestore document field of type Timestamp.
Source Files
Directories