docstore

Documentation

Overview

Package docstore provides a portable implementation of a document store. TODO(jba): link to an explanation of document stores (https://en.wikipedia.org/wiki/Document-oriented_database?) TODO(jba): expand package doc to batch other Go CDK APIs.

Index

• Variables
• type Action
• type ActionList
  • func (l *ActionList) Create(doc Document) *ActionList
  • func (l *ActionList) Delete(doc Document) *ActionList
  • func (l *ActionList) Do(ctx context.Context) (int, error)
  • func (l *ActionList) Get(doc Document, fps ...FieldPath) *ActionList
  • func (l *ActionList) Put(doc Document) *ActionList
  • func (l *ActionList) Replace(doc Document) *ActionList
  • func (l *ActionList) Update(doc Document, mods Mods) *ActionList
• type Collection
  • func (c *Collection) Actions() *ActionList
  • func (c *Collection) Create(ctx context.Context, doc Document) error
  • func (c *Collection) Delete(ctx context.Context, doc Document) error
  • func (c *Collection) Get(ctx context.Context, doc Document, fps ...FieldPath) error
  • func (c *Collection) Put(ctx context.Context, doc Document) error
  • func (c *Collection) Replace(ctx context.Context, doc Document) error
  • func (c *Collection) Update(ctx context.Context, doc Document, mods Mods) error
• type Document
• type FieldPath
• type Mods

Variables

var NewCollection = newCollection

NewCollection is intended for use by provider implementations.

Types

type Action

type Action struct {
	// contains filtered or unexported fields
}

An Action is a read or write on a single document. Use the methods of ActionList to create and execute Actions.

type ActionList

type ActionList struct {
	// contains filtered or unexported fields
}

An ActionList is a sequence of actions that affect a single collection. The actions are performed in order. If an action fails, the ones following it are not executed.

func (*ActionList) Create

func (l *ActionList) Create(doc Document) *ActionList

Create adds an action that creates a new document. The document must not already exist; an error for which gcerrors.Code returns AlreadyExists is returned if it does. If the document doesn't have key fields, it will be given key fields with unique values. TODO(jba): treat zero values for struct fields as not present?

func (*ActionList) Delete

func (l *ActionList) Delete(doc Document) *ActionList

Delete adds an action that deletes a document. Only the key fields and RevisionField of doc are used. If the document doesn't exist, nothing happens and no error is returned.

func (*ActionList) Do

func (l *ActionList) Do(ctx context.Context) (int, error)

Do executes the action list. If all the actions executed successfully, Do returns (number of actions, nil). If any failed, Do returns the number of successful actions and an error. In general there is no way to know which actions succeeded, but the error will contain as much information as possible about the failures.

func (*ActionList) Get

func (l *ActionList) Get(doc Document, fps ...FieldPath) *ActionList

Get adds an action that retrieves a document. Only the key fields of doc are used. If fps is omitted, all the fields of doc are set to those of the retrieved document. If fps is present, only the given field paths are set. In both cases, other fields of doc are not touched.

func (*ActionList) Put

func (l *ActionList) Put(doc Document) *ActionList

Put adds an action that adds or replaces a document. The key fields must be set. The document may or may not already exist.

func (*ActionList) Replace

func (l *ActionList) Replace(doc Document) *ActionList

Replace adds an action that replaces a document. The key fields must be set. The document must already exist; an error for which gcerrors.Code returns NotFound is returned if it does not.

func (*ActionList) Update

func (l *ActionList) Update(doc Document, mods Mods) *ActionList

Update applies Mods to doc, which must exist. Only the key and revision fields of doc are used.

A modification will create a field if it doesn't exist.

No field path in mods can be a prefix of another. (It makes no sense to, say, set foo but increment foo.bar.)

Update does not modify its doc argument. To obtain the new value of the document, call Get after calling Update.

type Collection

type Collection struct {
	// contains filtered or unexported fields
}

A Collection is a set of documents. TODO(jba): make the docstring look more like blob.Bucket.

func (*Collection) Actions

func (c *Collection) Actions() *ActionList

Actions returns an ActionList that can be used to perform actions on the collection's documents.

func (*Collection) Create

func (c *Collection) Create(ctx context.Context, doc Document) error

Create is a convenience for building and running a single-element action list. See ActionList.Create.

func (*Collection) Delete

func (c *Collection) Delete(ctx context.Context, doc Document) error

Delete is a convenience for building and running a single-element action list. See ActionList.Delete.

func (*Collection) Get

func (c *Collection) Get(ctx context.Context, doc Document, fps ...FieldPath) error

Get is a convenience for building and running a single-element action list. See ActionList.Get.

func (*Collection) Put

func (c *Collection) Put(ctx context.Context, doc Document) error

Put is a convenience for building and running a single-element action list. See ActionList.Put.

func (*Collection) Replace

func (c *Collection) Replace(ctx context.Context, doc Document) error

Replace is a convenience for building and running a single-element action list. See ActionList.Replace.

func (*Collection) Update

func (c *Collection) Update(ctx context.Context, doc Document, mods Mods) error

Update is a convenience for building and running a single-element action list. See ActionList.Update.

type Document

type Document = interface{}

A Document is a set of field-value pairs. One or more fields, called the key fields, must uniquely identify the document in the collection. You specify the key fields when you open a provider collection. A field name must be a valid UTF-8 string that does not contain a '.'.

A Document can be represented as a map[string]int or a pointer to a struct. For structs, the exported fields are the document fields.

type FieldPath

type FieldPath string

A FieldPath is a dot-separated sequence of UTF-8 field names. Examples:

room
room.size
room.size.width

A FieldPath can be used select top-level fields or elements of sub-documents. There is no way to select a single list element.

type Mods

type Mods map[FieldPath]interface{}

Mods is a map from field paths to modifications. At present, a modification is one of: - nil, to delete the field - any other value, to set the field to that value TODO(jba): add other kinds of modification See ActionList.Update.