// Copyright 2017 Google LLC

//

// Licensed under the Apache License, Version 2.0 (the "License");

// you may not use this file except in compliance with the License.

// You may obtain a copy of the License at

//

// http://www.apache.org/licenses/LICENSE-2.0

//

// Unless required by applicable law or agreed to in writing, software

// distributed under the License is distributed on an "AS IS" BASIS,

// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

// See the License for the specific language governing permissions and

// limitations under the License.

package firestore

import (

"context"

"errors"

"fmt"

"io"

"reflect"

"sort"

vkit "cloud.google.com/go/firestore/apiv1"

pb "cloud.google.com/go/firestore/apiv1/firestorepb"

"cloud.google.com/go/internal/trace"

"google.golang.org/api/iterator"

"google.golang.org/grpc/codes"

"google.golang.org/grpc/status"

)

var errNilDocRef = errors.New("firestore: nil DocumentRef")

// A DocumentRef is a reference to a Firestore document.

type DocumentRef struct {

}

func newDocRef(parent *CollectionRef, id string) *DocumentRef {

}

// Collection returns a reference to sub-collection of this document.

func (d *DocumentRef) Collection(id string) *CollectionRef {

return newCollRefWithParent(d.Parent.c, d, id)

}

// Get retrieves the document. If the document does not exist, Get return a NotFound error, which

// can be checked with

//

// status.Code(err) == codes.NotFound

//

// In that case, Get returns a non-nil DocumentSnapshot whose Exists method return false and whose

// ReadTime is the time of the failed read operation.

func (d *DocumentRef) Get(ctx context.Context) (_ *DocumentSnapshot, err error) {

}

// Create creates the document with the given data.

// It returns an error if a document with the same ID already exists.

//

// The data argument can be a map with string keys, a struct, or a pointer to a

// struct. The map keys or exported struct fields become the fields of the firestore

// document.

// The values of data are converted to Firestore values as follows:

//

// - bool converts to Bool.

// - string converts to String.

// - int, int8, int16, int32 and int64 convert to Integer.

// - uint8, uint16 and uint32 convert to Integer. uint, uint64 and uintptr are disallowed,

// because they may be able to represent values that cannot be represented in an int64,

// which is the underlying type of a Integer.

// - float32 and float64 convert to Double.

// - []byte converts to Bytes.

// - time.Time and *ts.Timestamp convert to Timestamp. ts is the package

// "github.com/golang/protobuf/ptypes/timestamp".

// - *latlng.LatLng converts to GeoPoint. latlng is the package

// "google.golang.org/genproto/googleapis/type/latlng". You should always use

// a pointer to a LatLng.

// - Slices convert to Array.

// - *firestore.DocumentRef converts to Reference.

// - Maps and structs convert to Map.

// - nils of any type convert to Null.

//

// Pointers and interface{} are also permitted, and their elements processed

// recursively.

//

// Struct fields can have tags like those used by the encoding/json package. Tags

// begin with "firestore:" and are followed by "-", meaning "ignore this field," or

// an alternative name for the field. Following the name, these comma-separated

// options may be provided:

//

// - omitempty: Do not encode this field if it is empty. A value is empty

// if it is a zero value, or an array, slice or map of length zero.

// - serverTimestamp: The field must be of type time.Time. serverTimestamp

// is a sentinel token that tells Firestore to substitute the server time

// into that field. When writing, if the field has the zero value, the

// server will populate the stored document with the time that the request

// is processed. However, if the field value is non-zero it won't be saved.

func (d *DocumentRef) Create(ctx context.Context, data interface{}) (_ *WriteResult, err error) {

}

func (d *DocumentRef) newCreateWrites(data interface{}) ([]*pb.Write, error) {

}

// Set creates or overwrites the document with the given data. See DocumentRef.Create

// for the acceptable values of data. Without options, Set overwrites the document

// completely. Specify one of the Merge options to preserve an existing document's

// fields. To delete some fields, use a Merge option with firestore.Delete as the

// field value.

func (d *DocumentRef) Set(ctx context.Context, data interface{}, opts ...SetOption) (_ *WriteResult, err error) {

}

func (d *DocumentRef) newSetWrites(data interface{}, opts []SetOption) ([]*pb.Write, error) {

}

// fpvsFromData converts v into a list of (FieldPath, value) pairs.

func fpvsFromData(v reflect.Value, prefix FieldPath, fpvs *[]fpv) {

}

// Delete deletes the document. If the document doesn't exist, it does nothing

// and returns no error.

func (d *DocumentRef) Delete(ctx context.Context, preconds ...Precondition) (_ *WriteResult, err error) {

}

func (d *DocumentRef) newDeleteWrites(preconds []Precondition) ([]*pb.Write, error) {

}

func (d *DocumentRef) newUpdatePathWrites(updates []Update, preconds []Precondition) ([]*pb.Write, error) {

}

func (d *DocumentRef) fpvsToWrites(fpvs []fpv, pc *pb.Precondition) ([]*pb.Write, error) {

}

// newUpdateWithTransform constructs operations for a commit. Most generally, it

// returns an update operation with update transforms.

//

// If there are no serverTimestampPaths, the transform is omitted.

//

// If doc.Fields is empty, there are no updatePaths, and there is no precondition,

// the update is omitted, unless updateOnEmpty is true.

func (d *DocumentRef) newUpdateWithTransform(doc *pb.Document, updatePaths []FieldPath, pc *pb.Precondition, transforms []*pb.DocumentTransform_FieldTransform, updateOnEmpty bool) []*pb.Write {

}

// arrayUnion is a special type in firestore. It instructs the server to add its

// elements to whatever array already exists, or to create an array if no value

// exists.

type arrayUnion struct {

elems []interface{}

}

// ArrayUnion specifies elements to be added to whatever array already exists in

// the server, or to create an array if no value exists.

//

// If a value exists and it's an array, values are appended to it. Any duplicate

// value is ignored.

// If a value exists and it's not an array, the value is replaced by an array of

// the values in the ArrayUnion.

// If a value does not exist, an array of the values in the ArrayUnion is created.

//

// ArrayUnion must be the value of a field directly; it cannot appear in

// array or struct values, or in any value that is itself inside an array or

// struct.

func ArrayUnion(elems ...interface{}) arrayUnion {

return arrayUnion{elems: elems}

}

// This helper converts an arrayUnion into a proto object.

func arrayUnionTransform(au arrayUnion, fp FieldPath) (*pb.DocumentTransform_FieldTransform, error) {

}

// arrayRemove is a special type in firestore. It instructs the server to remove

// the specified values.

type arrayRemove struct {

elems []interface{}

}

// ArrayRemove specifies elements to be removed from whatever array already

// exists in the server.

//

// If a value exists and it's an array, values are removed from it. All

// duplicate values are removed.

// If a value exists and it's not an array, the value is replaced by an empty

// array.

// If a value does not exist, an empty array is created.

//

// ArrayRemove must be the value of a field directly; it cannot appear in

// array or struct values, or in any value that is itself inside an array or

// struct.

func ArrayRemove(elems ...interface{}) arrayRemove {

return arrayRemove{elems: elems}

}

// This helper converts an arrayRemove into a proto object.

func arrayRemoveTransform(ar arrayRemove, fp FieldPath) (*pb.DocumentTransform_FieldTransform, error) {

}

type transform struct {

}

// FieldTransformIncrement returns a special value that can be used with Set, Create, or

// Update that tells the server to transform the field's current value

// by the given value.

//

// The supported values are:

//

// int, int8, int16, int32, int64

// uint8, uint16, uint32

// float32, float64

//

// If the field does not yet exist, the transformation will set the field to

// the given value.

func FieldTransformIncrement(n interface{}) transform {

}

// Increment is an alias for FieldTransformIncrement.

func Increment(n interface{}) transform {

return FieldTransformIncrement(n)

}

// FieldTransformMaximum returns a special value that can be used with Set, Create, or

// Update that tells the server to set the field to the maximum of the

// field's current value and the given value.

//

// The supported values are:

//

// int, int8, int16, int32, int64

// uint8, uint16, uint32

// float32, float64

//

// If the field is not an integer or double, or if the field does not yet

// exist, the transformation will set the field to the given value. If a

// maximum operation is applied where the field and the input value are of

// mixed types (that is - one is an integer and one is a double) the field

// takes on the type of the larger operand. If the operands are equivalent

// (e.g. 3 and 3.0), the field does not change. 0, 0.0, and -0.0 are all zero.

// The maximum of a zero stored value and zero input value is always the

// stored value. The maximum of any numeric value x and NaN is NaN.

func FieldTransformMaximum(n interface{}) transform {

}

// FieldTransformMinimum returns a special value that can be used with Set, Create, or

// Update that tells the server to set the field to the minimum of the

// field's current value and the given value.

//

// The supported values are:

//

// int, int8, int16, int32, int64

// uint8, uint16, uint32

// float32, float64

//

// If the field is not an integer or double, or if the field does not yet

// exist, the transformation will set the field to the given value. If a

// minimum operation is applied where the field and the input value are of

// mixed types (that is - one is an integer and one is a double) the field

// takes on the type of the smaller operand. If the operands are equivalent

// (e.g. 3 and 3.0), the field does not change. 0, 0.0, and -0.0 are all zero.

// The minimum of a zero stored value and zero input value is always the

// stored value. The minimum of any numeric value x and NaN is NaN.

func FieldTransformMinimum(n interface{}) transform {

}

func numericTransformValue(n interface{}) (*pb.Value, error) {

}

func fieldTransform(ar transform, fp FieldPath) (*pb.DocumentTransform_FieldTransform, error) {

}

type sentinel int

const (

// Delete is used as a value in a call to Update or Set with merge to indicate

// that the corresponding key should be deleted.

Delete sentinel = iota

// ServerTimestamp is used as a value in a call to Update to indicate that the

// key's value should be set to the time at which the server processed

// the request.

//

// ServerTimestamp must be the value of a field directly; it cannot appear in

// array or struct values, or in any value that is itself inside an array or

// struct.

ServerTimestamp

)

func (s sentinel) String() string {

}

// An Update describes an update to a value referred to by a path.

// An Update should have either a non-empty Path or a non-empty FieldPath,

// but not both.

//

// See DocumentRef.Create for acceptable values.

// To delete a field, specify firestore.Delete as the value.

type Update struct {

}

// An fpv is a pair of validated FieldPath and value.

type fpv struct {

fieldPath FieldPath

value interface{}

}

func (u *Update) process() (fpv, error) {

}

// Update updates the document. The values at the given

// field paths are replaced, but other fields of the stored document are untouched.

func (d *DocumentRef) Update(ctx context.Context, updates []Update, preconds ...Precondition) (_ *WriteResult, err error) {

}

// Collections returns an iterator over the immediate sub-collections of the document.

func (d *DocumentRef) Collections(ctx context.Context) *CollectionIterator {

}

// CollectionIterator is an iterator over sub-collections of a document.

type CollectionIterator struct {

}

// PageInfo supports pagination. See the google.golang.org/api/iterator package for details.

func (it *CollectionIterator) PageInfo() *iterator.PageInfo { return it.pageInfo }

// Next returns the next result. Its second return value is iterator.Done if there

// are no more results. Once Next returns Done, all subsequent calls will return

// Done.

func (it *CollectionIterator) Next() (*CollectionRef, error) {

}

func (it *CollectionIterator) fetch(pageSize int, pageToken string) (string, error) {

}

// GetAll returns all the collections remaining from the iterator.

func (it *CollectionIterator) GetAll() ([]*CollectionRef, error) {

}

// Common fetch code for iterators that are backed by vkit iterators.

// TODO(jba): dedup with same function in logging/logadmin.

func iterFetch(pageSize int, pageToken string, pi *iterator.PageInfo, next func() error) (string, error) {

}

// Snapshots returns an iterator over snapshots of the document. Each time the document

// changes or is added or deleted, a new snapshot will be generated.

func (d *DocumentRef) Snapshots(ctx context.Context) *DocumentSnapshotIterator {

}

// DocumentSnapshotIterator is an iterator over snapshots of a document.

// Call Next on the iterator to get a snapshot of the document each time it changes.

// Call Stop on the iterator when done.

//

// For an example, see DocumentRef.Snapshots.

type DocumentSnapshotIterator struct {

docref *DocumentRef

ws *watchStream

}

// Next blocks until the document changes, then returns the DocumentSnapshot for

// the current state of the document. If the document has been deleted, Next

// returns a DocumentSnapshot whose Exists method returns false.

//

// Next is not expected to return iterator.Done unless it is called after Stop.

// Rarely, networking issues may also cause iterator.Done to be returned.

func (it *DocumentSnapshotIterator) Next() (*DocumentSnapshot, error) {

}

// Stop stops receiving snapshots. You should always call Stop when you are done with

// a DocumentSnapshotIterator, to free up resources. It is not safe to call Stop

// concurrently with Next.

func (it *DocumentSnapshotIterator) Stop() {

it.ws.stop()

}

// WithReadOptions specifies constraints for accessing documents from the database,

// e.g. at what time snapshot to read the documents.

func (d *DocumentRef) WithReadOptions(opts ...ReadOption) *DocumentRef {

}