interfaces.go

package datastore

import (
	"context"
)

// FromContext provides default ClientGenerator.
// this variable will be injected by go.mercari.io/datastore/aedatastore or go.mercari.io/datastore/clouddatastore package's init function.
//
// Deprecated: use aedatastore.FromContext or clouddatastore.FromContext instead.
var FromContext ClientGenerator

// ClientGenerator represents the type of function for generating Client.
//
// Deprecated:
type ClientGenerator func(ctx context.Context, opts ...ClientOption) (Client, error)

// Client is a client for reading and writing data in a datastore dataset.
type Client interface {
	// Get loads the entity stored for key into dst, which must be a struct pointer or implement PropertyLoadSaver.
	//
	// If there is no such entity for the key, Get returns ErrNoSuchEntity.
	// The values of dst's unmatched struct fields are not modified, and matching slice-typed fields are not reset before appending to them.
	// In particular, it is recommended to pass a pointer to a zero valued struct on each Get call.
	//
	// If you set false to SuppressErrFieldMismatch variable, act like the original Datastore.
	// ErrFieldMismatch is returned when a field is to be loaded into a different type than the one it was stored from, or when a field is missing or unexported in the destination struct.
	Get(ctx context.Context, key Key, dst interface{}) error

	// GetMulti is a batch version of Get.
	//
	// dst must be a []S, []*S, []I or []P, for some struct type S, some interface type I, or some non-interface non-pointer type P such that P or *P implements PropertyLoadSaver.
	// If an []I, each element must be a valid dst for Get: it must be a struct pointer or implement PropertyLoadSaver.
	//
	// As a special case, PropertyList is an invalid type for dst, even though a PropertyList is a slice of structs.
	// It is treated as invalid to avoid being mistakenly passed when []PropertyList was intended.
	GetMulti(ctx context.Context, keys []Key, dst interface{}) error

	// Put saves the entity src into the datastore with key k.
	// src must be a struct pointer or implement PropertyLoadSaver; if a struct pointer then any unexported fields of that struct will be skipped.
	// If k is an incomplete key, the returned key will be a unique key generated by the datastore.
	Put(ctx context.Context, key Key, src interface{}) (Key, error)

	// PutMulti is a batch version of Put.
	//
	// src must satisfy the same conditions as the dst argument to GetMulti.
	PutMulti(ctx context.Context, keys []Key, src interface{}) ([]Key, error)

	// Delete deletes the entity for the given key.
	Delete(ctx context.Context, key Key) error

	// DeleteMulti is a batch version of Delete.
	DeleteMulti(ctx context.Context, keys []Key) error

	// NewTransaction starts a new transaction.
	NewTransaction(ctx context.Context) (Transaction, error)

	// RunInTransaction runs f in a transaction. f is invoked with a Transaction that f should use for all the transaction's datastore operations.
	//
	// f must not call Commit or Rollback on the provided Transaction.
	//
	// If f returns nil, RunInTransaction commits the transaction, returning the Commit and a nil error if it succeeds.
	// If the commit fails due to a conflicting transaction, RunInTransaction gives up and returns ErrConcurrentTransaction immediately.
	// If you want to retry operation, You have to retry by yourself.
	//
	// If f returns non-nil, then the transaction will be rolled back and RunInTransaction will return the same error.
	//
	// Note that when f returns, the transaction is not committed. Calling code must not assume that any of f's changes have been committed until RunInTransaction returns nil.
	RunInTransaction(ctx context.Context, f func(tx Transaction) error) (Commit, error)

	// Run runs the given query in the given context.
	Run(ctx context.Context, q Query) Iterator

	// AllocateIDs accepts a slice of incomplete keys and returns a slice of complete keys that are guaranteed to be valid in the datastore.
	AllocateIDs(ctx context.Context, keys []Key) ([]Key, error)

	// Count returns the number of results for the given query.
	//
	// The running time and number of API calls made by Count scale linearly with with the sum of the query's offset and limit.
	// Unless the result count is expected to be small, it is best to specify a limit; otherwise Count will continue until it finishes counting or the provided context expires.
	Count(ctx context.Context, q Query) (int, error)

	// GetAll runs the provided query in the given context and returns all keys that match that query, as well as appending the values to dst.
	//
	// dst must have type *[]S or *[]*S or *[]P, for some struct type S or some non-interface, non-pointer type P such that P or *P implements PropertyLoadSaver.
	//
	// As a special case, *PropertyList is an invalid type for dst, even though a PropertyList is a slice of structs.
	// It is treated as invalid to avoid being mistakenly passed when *[]PropertyList was intended.
	//
	// The keys returned by GetAll will be in a 1-1 correspondence with the entities added to dst.
	//
	// If q is a “keys-only” query, GetAll ignores dst and only returns the keys.
	//
	// The running time and number of API calls made by GetAll scale linearly with with the sum of the query's offset and limit.
	// Unless the result count is expected to be small, it is best to specify a limit; otherwise GetAll will continue until it finishes collecting results or the provided context expires.
	GetAll(ctx context.Context, q Query, dst interface{}) ([]Key, error)

	// IncompleteKey creates a new incomplete key.
	// The supplied kind cannot be empty.
	// The namespace of the new key is empty.
	IncompleteKey(kind string, parent Key) Key

	// NameKey creates a new key with a name.
	// The supplied kind cannot be empty.
	// The supplied parent must either be a complete key or nil.
	// The namespace of the new key is empty.
	NameKey(kind, name string, parent Key) Key

	// IDKey creates a new key with an ID.
	// The supplied kind cannot be empty.
	// The supplied parent must either be a complete key or nil.
	// The namespace of the new key is empty.
	IDKey(kind string, id int64, parent Key) Key

	// NewQuery creates a new Query for a specific entity kind.
	//
	// An empty kind means to return all entities, including entities created and managed by other App Engine features, and is called a kindless query.
	// Kindless queries cannot include filters or sort orders on property values.
	NewQuery(kind string) Query

	// Close closes the Client.
	Close() error

	// DecodeKey decodes a key from the opaque representation returned by Encode.
	DecodeKey(encoded string) (Key, error)

	// DecodeCursor from its base-64 string representation.
	DecodeCursor(s string) (Cursor, error)

	// Batch creates batch mode objects.
	Batch() *Batch
	// AppendMiddleware to client.
	// Middleware will apply First-In First-Apply
	AppendMiddleware(middleware Middleware)
	// RemoveMiddleware from client.
	RemoveMiddleware(middleware Middleware) bool
	// Context returns this client's context.
	Context() context.Context
	// SetContext to this client.
	SetContext(ctx context.Context)
}

// Key represents the datastore key for a stored entity.
type Key interface {
	Kind() string
	ID() int64
	Name() string
	ParentKey() Key
	Namespace() string
	SetNamespace(namespace string)

	String() string
	GobEncode() ([]byte, error)
	GobDecode(buf []byte) error
	MarshalJSON() ([]byte, error)
	UnmarshalJSON(buf []byte) error
	Encode() string
	Equal(o Key) bool
	Incomplete() bool
}

// PendingKey represents the key for newly-inserted entity. It can be
// resolved into a Key by calling the Key method of Commit.
type PendingKey interface {
	StoredContext() context.Context
}

// Transaction represents a set of datastore operations to be committed atomically.
//
// Operations are enqueued by calling the Put and Delete methods on Transaction
// (or their Multi-equivalents).  These operations are only committed when the
// Commit method is invoked. To ensure consistency, reads must be performed by
// using Transaction's Get method or by using the Transaction method when
// building a query.
//
// A Transaction must be committed or rolled back exactly once.
type Transaction interface {
	// Get is the transaction-specific version of the package function Get.
	// All reads performed during the transaction will come from a single consistent snapshot.
	// Furthermore, if the transaction is set to a serializable isolation level,
	// another transaction cannot concurrently modify the data that is read or modified by this transaction.
	Get(key Key, dst interface{}) error
	// GetMulti is a batch version of Get.
	GetMulti(keys []Key, dst interface{}) error
	// Put is the transaction-specific version of the package function Put.
	//
	// Put returns a PendingKey which can be resolved into a Key using the return value from a successful Commit.
	// If key is an incomplete key, the returned pending key will resolve to a unique key generated by the datastore.
	Put(key Key, src interface{}) (PendingKey, error)
	// PutMulti is a batch version of Put. One PendingKey is returned for each element of src in the same order.
	PutMulti(keys []Key, src interface{}) ([]PendingKey, error)
	// Delete is the transaction-specific version of the package function Delete.
	// Delete enqueues the deletion of the entity for the given key,
	// to be committed atomically upon calling Commit.
	Delete(key Key) error
	// DeleteMulti is a batch version of Delete.
	DeleteMulti(keys []Key) error

	// Commit applies the enqueued operations atomically.
	Commit() (Commit, error)
	// Rollback abandons a pending transaction.
	Rollback() error

	Batch() *TransactionBatch
}

// Commit represents the result of a committed transaction.
type Commit interface {
	Key(p PendingKey) Key
}

// GeoPoint represents a location as latitude/longitude in degrees.
type GeoPoint struct {
	Lat, Lng float64
}

// Query represents a datastore query.
type Query interface {
	Ancestor(ancestor Key) Query
	EventualConsistency() Query
	Namespace(ns string) Query
	Transaction(t Transaction) Query
	Filter(filterStr string, value interface{}) Query
	Order(fieldName string) Query
	Project(fieldNames ...string) Query
	Distinct() Query
	DistinctOn(fieldNames ...string) Query
	KeysOnly() Query
	Limit(limit int) Query
	Offset(offset int) Query
	Start(c Cursor) Query
	End(c Cursor) Query

	Dump() *QueryDump
}

// Iterator is the result of running a query.
type Iterator interface {
	// Next returns the key of the next result. When there are no more results,
	// iterator.Done is returned as the error.
	//
	// If the query is not keys only and dst is non-nil, it also loads the entity
	// stored for that key into the struct pointer or PropertyLoadSaver dst, with
	// the same semantics and possible errors as for the Get function.
	Next(dst interface{}) (Key, error)
	// Cursor returns a cursor for the iterator's current location.
	Cursor() (Cursor, error)
}

// Cursor is an iterator's position. It can be converted to and from an opaque
// string. A cursor can be used from different HTTP requests, but only with a
// query with the same kind, ancestor, filter and order constraints.
//
// The zero Cursor can be used to indicate that there is no start and/or end
// constraint for a query.
type Cursor interface {
	String() string
}

// PropertyTranslator is for converting the value of Property when saving and loading.
type PropertyTranslator interface {
	ToPropertyValue(ctx context.Context) (interface{}, error)
	FromPropertyValue(ctx context.Context, p Property) (dst interface{}, err error)
}

// TODO ComplexPropertyTranslator e.g. ToProperties(ctx context.Context) ([]Property, error)