types

Documentation

Overview

Package types provides Go types matching BSON types that don't have built-in Go equivalents.

All BSON types have three representations in FerretDB:

1. As they are used in "business logic" / handlers - `types` package.
2. As they are used in the wire protocol implementation - `bson` package.
3. As they are used to store data in PostgreSQL - `fjson` package.

The reason for that is a separation of concerns: to avoid method names clashes, to simplify type asserts, to make refactorings and optimizations easier, etc.

Mapping

Composite types (passed by pointers)

*types.Document  *bson.Document       *fjson.documentType   Document
*types.Array     *bson.arrayType      *fjson.arrayType      Array

Scalar types (passed by values)

float64          *bson.doubleType     *fjson.doubleType     64-bit binary floating point
string           *bson.stringType     *fjson.stringType     UTF-8 string
types.Binary     *bson.binaryType     *fjson.binaryType     Binary data
types.ObjectID   *bson.objectIDType   *fjson.objectIDType   ObjectId
bool             *bson.boolType       *fjson.boolType       Boolean
time.Time        *bson.dateTimeType   *fjson.dateTimeType   UTC datetime
types.NullType   *bson.nullType       *fjson.nullType       Null
types.Regex      *bson.regexType      *fjson.regexType      Regular expression
int32            *bson.int32Type      *fjson.int32Type      32-bit integer
types.Timestamp  *bson.timestampType  *fjson.timestampType  Timestamp
int64            *bson.int64Type      *fjson.int64Type      64-bit integer

Index

• Constants
• Variables
• func RemoveByPath[T CompositeTypeInterface](comp T, keys ...string)
• type Array
  • func MakeArray(capacity int) *Array
  • func NewArray(values ...any) (*Array, error)
  • func (a *Array) Append(values ...any) error
  • func (a *Array) DeepCopy() *Array
  • func (a *Array) Get(index int) (any, error)
  • func (a *Array) GetByPath(path ...string) (any, error)
  • func (a *Array) Len() int
  • func (a *Array) RemoveByPath(keys ...string)
  • func (a *Array) Set(index int, value any) error
• type Binary
• type BinarySubtype
  • func (i BinarySubtype) String() string
• type CompareResult
  • func Compare(v1, v2 any) CompareResult
  • func (i CompareResult) String() string
• type CompositeType
• type CompositeTypeInterface
• type Document
  • func ConvertDocument(d document) (*Document, error)
  • func NewDocument(pairs ...any) (*Document, error)
  • func (d *Document) Command() string
  • func (d *Document) DeepCopy() *Document
  • func (d *Document) Get(key string) (any, error)
  • func (d *Document) GetByPath(path ...string) (any, error)
  • func (d *Document) Has(key string) bool
  • func (d *Document) Keys() []string
  • func (d *Document) Len() int
  • func (d *Document) Map() map[string]any
  • func (d *Document) Remove(key string)
  • func (d *Document) RemoveByPath(keys ...string)
  • func (d *Document) Set(key string, value any) error
• type NullType
• type ObjectID
  • func NewObjectID() ObjectID
• type Regex
  • func (r Regex) Compile() (*regexp.Regexp, error)
• type ScalarType
• type Timestamp
• type Type

Constants

const (
	BinaryGeneric    = BinarySubtype(0x00) // generic
	BinaryFunction   = BinarySubtype(0x01) // function
	BinaryGenericOld = BinarySubtype(0x02) // generic-old
	BinaryUUIDOld    = BinarySubtype(0x03) // uuid-old
	BinaryUUID       = BinarySubtype(0x04) // uuid
	BinaryMD5        = BinarySubtype(0x05) // md5
	BinaryEncrypted  = BinarySubtype(0x06) // encrypted
	BinaryUser       = BinarySubtype(0x80) // user
)

const MaxDocumentLen = 16777216

Variables

var (
	ErrOptionNotImplemented = fmt.Errorf("regex: option not implemented")
	ErrMissingParen         = fmt.Errorf("Regular expression is invalid: missing )")
	ErrMissingBracket       = fmt.Errorf("Regular expression is invalid: missing terminating ] for character class")
	ErrInvalidEscape        = fmt.Errorf("Regular expression is invalid: PCRE does not support \\L, \\l, \\N{name}, \\U, or \\u")
	ErrMissingTerminator    = fmt.Errorf("Regular expression is invalid: syntax error in subpattern name (missing terminator)")
	ErrUnmatchedParentheses = fmt.Errorf("Regular expression is invalid: unmatched parentheses")
	ErrTrailingBackslash    = fmt.Errorf("Regular expression is invalid: \\ at end of pattern")
	ErrNothingToRepeat      = fmt.Errorf("Regular expression is invalid: nothing to repeat")
	ErrInvalidClassRange    = fmt.Errorf("Regular expression is invalid: range out of order in character class")
	ErrUnsupportedPerlOp    = fmt.Errorf("Regular expression is invalid: unrecognized character after (? or (?-")
	ErrInvalidRepeatSize    = fmt.Errorf("Regular expression is invalid: regular expression is too large")
)

var Null = NullType{}

Null represents BSON value Null.

Functions

func RemoveByPath

func RemoveByPath[T CompositeTypeInterface](comp T, keys ...string)

RemoveByPath removes document by path, doing nothing if the key does not exist.

Types

type Array

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

Array represents BSON array.

Zero value is a valid empty array.

func MakeArray

func MakeArray(capacity int) *Array

MakeArray creates an empty array with set capacity.

func NewArray

func NewArray(values ...any) (*Array, error)

NewArray creates an array with the given values.

func (*Array) Append

func (a *Array) Append(values ...any) error

Append appends given values to the array.

func (*Array) DeepCopy

func (a *Array) DeepCopy() *Array

DeepCopy returns a deep copy of this Array.

func (*Array) Get

func (a *Array) Get(index int) (any, error)

Get returns a value at the given index.

func (*Array) GetByPath

func (a *Array) GetByPath(path ...string) (any, error)

GetByPath returns a value by path - a sequence of indexes and keys.

func (*Array) Len

func (a *Array) Len() int

Len returns the number of elements in the array.

It returns 0 for nil Array.

func (*Array) RemoveByPath

func (a *Array) RemoveByPath(keys ...string)

RemoveByPath removes document by path, doing nothing if the key does not exist.

func (*Array) Set

func (a *Array) Set(index int, value any) error

Set sets the value at the given index.

type Binary

type Binary struct {
	Subtype BinarySubtype
	B       []byte
}

Binary represents BSON type Binary.

type BinarySubtype

type BinarySubtype byte

BinarySubtype represents BSON Binary's subtype.

func (BinarySubtype) String

func (i BinarySubtype) String() string

type CompareResult

type CompareResult int8

CompareResult represents the result of a comparison.

const (
	Equal   CompareResult = 0  // ==
	Less    CompareResult = -1 // <
	Greater CompareResult = 1  // >

	// TODO Remove once it is no longer needed.
	// It should not be needed.
	NotEqual CompareResult = 127 // !=
)

Values match results of comparison functions such as bytes.Compare. They do not match MongoDB `sort` values where 1 means ascending order and -1 means descending.

func Compare

func Compare(v1, v2 any) CompareResult

Compare compares any BSON values in the same way as MongoDB does it for filtering or sorting.

It converts types as needed; that may result in different types being equal. For that reason, it typically should not be used in tests.

Compare and contrast with test helpers in testutil package.

func (CompareResult) String

func (i CompareResult) String() string

type CompositeType

type CompositeType interface {
	*Document | *Array
}

CompositeType represents composite type - *Document or *Array.

type CompositeTypeInterface

type CompositeTypeInterface interface {
	CompositeType
	GetByPath(path ...string) (any, error)
	RemoveByPath(path ...string)
	// contains filtered or unexported methods
}

TODO remove once we have go-sumtype equivalent?

type Document

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

Document represents BSON document.

Duplicate field names are not supported.

func ConvertDocument

func ConvertDocument(d document) (*Document, error)

ConvertDocument converts bson.Document to *types.Document and validates it. It references the same data without copying it.

TODO Remove this function.

func NewDocument

func NewDocument(pairs ...any) (*Document, error)

NewDocument creates a document with the given key/value pairs.

func (*Document) Command

func (d *Document) Command() string

Command returns the first document's key. This is often used as a command name. It returns an empty string if document is nil or empty.

func (*Document) DeepCopy

func (d *Document) DeepCopy() *Document

DeepCopy returns a deep copy of this Document.

func (*Document) Get

func (d *Document) Get(key string) (any, error)

Get returns a value at the given key.

func (*Document) GetByPath

func (d *Document) GetByPath(path ...string) (any, error)

GetByPath returns a value by path - a sequence of indexes and keys.

func (*Document) Has

func (d *Document) Has(key string) bool

Has returns true if the given key is present in the document.

func (*Document) Keys

func (d *Document) Keys() []string

Keys returns document's keys. Do not modify it.

It returns nil for nil Document.

func (*Document) Len

func (d *Document) Len() int

Len returns the number of elements in the document.

It returns 0 for nil Document.

func (*Document) Map

func (d *Document) Map() map[string]any

Map returns this document as a map. Do not modify it.

It returns nil for nil Document.

func (*Document) Remove

func (d *Document) Remove(key string)

Remove the given key, doing nothing if the key does not exist.

func (*Document) RemoveByPath

func (d *Document) RemoveByPath(keys ...string)

RemoveByPath removes document by path, doing nothing if the key does not exist.

func (*Document) Set

func (d *Document) Set(key string, value any) error

Set sets the value for the given key, replacing any existing value.

As a special case, _id always becomes the first key.

type NullType

type NullType struct{}

NullType represents BSON type Null.

Most callers should use types.Null value instead.

type ObjectID

type ObjectID [12]byte

ObjectID represents BSON type ObjectID.

Normally, it is generated by the driver, but in some cases (like upserts) FerretDB has to do itself.

func NewObjectID

func NewObjectID() ObjectID

NewObjectID returns a new ObjectID.

type Regex

type Regex struct {
	Pattern string
	Options string
}

Regex represents BSON type Regex.

func (Regex) Compile

func (r Regex) Compile() (*regexp.Regexp, error)

Compile returns Go Regexp object.

type ScalarType

type ScalarType interface {
	float64 | string | Binary | ObjectID | bool | time.Time | NullType | Regex | int32 | Timestamp | int64
}

ScalarType represents scalar type.

type Timestamp

type Timestamp uint64

Timestamp represents BSON type Timestamp.

type Type

type Type interface {
	ScalarType | CompositeType
}

Type represents any BSON type (scalar or composite).