mongoms

README

MongoMS

Mongo Client for Microservices

Description

MongoMS is a libarary for working with mongo collections within microservices. The library is currently a reference library only and not currently available and standalone pre-built library

Installation

Reference Code only. Download and utilize

Support

No support is provided use at your own risk

Roadmap

Turn into first class documented library

Contributing

Contributions will be welcome

Authors and acknowledgment

Kristopher L Tyra

License

MIT License

Project status

Active

Documentation

Index

• Constants
• func RegisterDriver(scheme string, driver IDriver)
• type ChangeSet
• type IBlob
• type IChangeSetPublisher
• type IDocument
• type IDocumentID
• type IDocumentStore
• type IDriver
  • func Connect(ctx context.Context, server url.URL, opts IDriverOptions) (IDriver, error)
• type IDriverOptions
• type IQuery
• type IQueryResult
• type IStoreOptions
• type IWriter
• type SimpleDocumentID
  • func (sid *SimpleDocumentID) Clone() any
  • func (sid *SimpleDocumentID) Equals(id IDocumentID) bool
  • func (sid *SimpleDocumentID) GetNativeRecordId() any
  • func (sid *SimpleDocumentID) MarshalJSON() ([]byte, error)
  • func (sid *SimpleDocumentID) SetNativeRecordId(value any) error
  • func (sid *SimpleDocumentID) String() string
  • func (sid *SimpleDocumentID) UnmarshalBSON(data []byte) error
  • func (sid *SimpleDocumentID) UnmarshalJSON(raw []byte) error
• type TransformFunc

Constants

const ChangeSetDelete = "delete"

const ChangeSetInsert = "insert"

const ChangeSetUpdate = "update"

Functions

func RegisterDriver

func RegisterDriver(scheme string, driver IDriver)

RegisterDriver Registers a known mongoms for a given scheme

Types

type ChangeSet

type ChangeSet struct {
	Op         string      `json:"op" bson:"-" readonly:"true"`
	DocumentID IDocumentID `json:"id,omitempty" bson:"-" readonly:"true"`
	Value      any         `json:"value,omitempty" bson:"-" readonly:"true"`
}

type IBlob

type IBlob interface {
	FindBlob(id IDocumentID, metadata IDocument) (filename string, length int64, err error)

	ReadBlob(id IDocumentID) (reader io.Reader, err error)

	WriteBlob(filename string, metadata IDocument, reader io.Reader) (newID IDocumentID, length int64, err error)

	DeleteBlob(id IDocumentID) error

	// DuplicateBlob duplicates a blob identified by the given resource.SimpleDocumentID.
	//
	// It returns the new resource.SimpleDocumentID of the duplicated blob and an error if any.
	DuplicateBlob(id IDocumentID, metadata IDocument) (newId IDocumentID, err error)
}

type IChangeSetPublisher

type IChangeSetPublisher interface {
	// PublishChange Called by a change set reader to publish the changes to where ever the implementation pushes changes.
	// If Publish returns true then the stream will stay openSecurity to publish more changes.
	// If Publish returns false then the underlying change set reader will be closed and the publisher's Close() function will be called
	PublishChange(ChangeSet) bool

	// Close Called to notify the publisher that a change stream has closed and will no longer produce calls to Publish()
	Close()

	// AddCloseHandler Handler called when socket is closed by the receiver
	AddCloseHandler(func())

	// String Descriptive string of publisher
	String() string
}

type IDocument

type IDocument interface {

	// String returns a string representation of the Document object.
	String() string

	// GetID returns the ID of the Document
	GetID() IDocumentID

	// SetID sets the ID of the Document.
	SetID(IDocumentID)

	// Clone creates a shallow copy of the Document object.
	Clone() any
}

type IDocumentID

type IDocumentID interface {
	// String returns the string representation of the DocumentID object.`
	String() string

	// Clone creates a shallow copy of the Document ID object.
	Clone() any

	SetNativeRecordId(value any) error

	GetNativeRecordId() any

	Equals(id IDocumentID) bool
}

type IDocumentStore

type IDocumentStore interface {
	IBlob
	IWriter
	IQuery

	// Driver returns the Database driver for the store
	Driver() IDriver

	HasIndex(indexName string) bool
}

IDocumentStore is an interface to URL driven stores All Drivers must only be called synchronously. However, you may create as many instances to the driver through OpenRead and OpenWrite as you wish.

Implementations must ensure the OpenRead and OpenWrite return readers and writer instances that share no variables

type IDriver

type IDriver interface {
	Connect(connCtx context.Context, server url.URL, options IDriverOptions) (IDriver, error)

	OpenStore(options IStoreOptions, collection string, proto IDocument, ctx ...context.Context) (IDocumentStore, error)

	Disconnect(connCtx context.Context) error

	Ping(connCtx context.Context) error

	DumpStats(connCtx context.Context)

	DropAll(connCtx context.Context) error

	DropOpenStores(connCtx context.Context) error

	Drop(connCtx context.Context, collection string) error

	Exists(connCtx context.Context, collection string) (bool, error)
}

func Connect

func Connect(ctx context.Context, server url.URL, opts IDriverOptions) (IDriver, error)

type IDriverOptions

type IDriverOptions interface {

	// MinPoolSize returns the minimum number of connections held open on the server
	MinPoolSize() uint64

	// MaxPoolSize returns the maximum number of connections held open on the server
	MaxPoolSize() uint64

	TransactionTimeout() time.Duration

	// LogLevel returns the Max Log Level
	LogLevel() string

	// ColorizeLog returns if the log should be colorized
	ColorizeLog() bool
}

type IQuery

type IQuery interface {
	// QueryOne same as FindOne but uses function channel
	QueryOne(id IDocumentID) IQueryResult

	// QueryAll Same as FindAll but uses function channel
	QueryAll() IQueryResult

	// Query executes a native query with the given bson.M query and returns a IQueryResult.
	// The query parameter is driver dependent
	Query(query bson.M) IQueryResult

	// Filter executes a filter query with the given bson.M query and returns a IQueryResult.
	// The query parameter is driver dependent
	Filter(query bson.M, svc ...IQuery) IQueryResult

	// Aggregate Aggregates a query with the given bson.M query and returns a IQueryResult.
	// The query parameter is driver dependent
	Aggregate(query bson.M, pipeline ...bson.M) IQueryResult

	// Count returns the number of documents in the collection that match the specified query.
	//
	// query: the filter to apply to the collection.  If nil, all documents in the collection will be counted.
	// Returns:
	//     int64: the number of documents that match the query
	//     error: any error that occurred during the operation
	Count(query bson.M) (int64, error)

	// Distinct returns a distinct set of values for a given field and query in a collection.
	//
	// Parameters:
	// - field: The field in the collection to find distinct values for.
	// - query: The query to filter the documents in the collection.
	//
	// Returns:
	// - []any: A slice of distinct values for the specified field.
	// - error: An error if the distinct operation fails.
	Distinct(field string, query bson.M) ([]any, error)

	// QueryError is a function that takes an error parameter and returns a IQueryResult.
	//
	// error: The error parameter.
	// IQueryResult: The return type of the function.
	QueryError(error) IQueryResult

	// Enrich executes a 'lookup' with a join query with the given bson.M query and returns a IQueryResult.
	// The query parameter is driver dependent
	Enrich(lookupField string, qr IQueryResult) IQueryResult
}

IQuery functions

type IQueryResult

type IQueryResult interface {
	IQuery

	// Error returns the error in processing the query
	Error() error

	// Result is a function that fills in the value current query result into the
	// resource decoded into the resource's type.  Note the call to this function triggers the query
	// on the resource mongoms as built up via query methods described in the interface
	//
	// A duplicate of the stores IDocument prototype is created which is filled in
	// with the field values of the query based upon the structure of the resource using it's a BSON
	// tags of the go field specification.
	// It returns the resourceBuffer and error if the query resulted in an error.  If the query resulted in no results
	// The query returns a NilResource which can be tested for using IsNil() function on the resource.
	Result() (IDocument, error)

	// Results is a function that fills in ALL value current query result into the
	// resources using the resourceBuffer as the decoder to decode the results into the resource's type.  The function relies on the resources Clone() method
	// to create a new the new resources
	// Note the call to this function triggers the query on the resource mongoms as built up via query methods described in the interface.
	//
	//
	// It returns an error.
	Results() ([]IDocument, error)

	// NextResult a function that fills in the next value of query result into the
	// resource decoded into the resource's type.  Note the call to this function triggers the query
	// on the resource mongoms as built up via query methods described in the interface
	//
	// It returns the resource and error if the query resulted in an error.  If the query resulted in no results
	// The query returns a NilResource which can be tested for using IsNil() function on the resource.
	// NextResult returns the next value in the result set converting them to resource and applying any transforms registered with the IQuery
	// the cursor will not be closed until all the values have been retrieved
	NextResult() (IDocument, error)

	// KeyValue is a function similar to Result() but returns the object as key value map
	KeyValue() (map[string]any, error)

	// KeyValues is a function similar to Results() but returns an array the objects as key value map
	KeyValues() ([]map[string]any, error)

	// NextKeyValue is a function similar to NextResult but returns the object as key value map
	NextKeyValue() (map[string]any, error)

	// Close the results free all resources and destroying the mongoms's cursor
	Close()

	// Transform applies a transform function to each object in the query results set
	// The transform function is applied in the order of the query results and only applied once the data is retrieved
	// from the query.  The transform function can be used to enrich the results or to reduce the number of fields returned through
	Transform(TransformFunc) IQueryResult

	// QueryInstruction Returns the query instruction for the query in native bson format
	QueryInstruction() bson.M

	// PipelineInstruction Returns the pipeline instruction for the query in native bson format
	PipelineInstruction() []bson.M

	// Watch watches for changes that match the given query and publishes them using the provided IChangeSetPublisher.
	//
	// query: the query used to filter the changes
	// publisher: the IChangeSetPublisher used to publish the changes
	// error: an error if there was a problem watching for changes
	Watch(publisher IChangeSetPublisher) IQueryResult

	// FilterByPermissions reduces the query result set by the permission model as specified in the query
	FilterByPermissions() IQueryResult

	// Enrich executes a 'lookup' with a join query with the given bson.M query and returns a IQueryResult.
	// The query parameter is driver dependent
	Enrich(lookupField string, qr IQueryResult) IQueryResult

	// EmptyQuery returns an empty IQueryResult.
	//
	// It does not take any parameters.
	// It returns a IQueryResult.
	EmptyQuery() IQueryResult
}

type IStoreOptions

type IStoreOptions interface {
	DocumentPrototype() IDocument

	DocumentIDPrototype() IDocumentID

	// DebugQueryOn returns true if debug logging for queries is enabled
	DebugQueryOn() bool

	// LogLevel returns log level required for the driver
	LogLevel() string
}

type IWriter

type IWriter interface {
	AddOne(doc IDocument) (IDocumentID, error)

	// WriteOne Writes a record to the data mongoms.  If the record has an id then the record is updated.
	// Otherwise, a new record is created and the value of the DocumentID is set in the mongoms
	// In both cases the id of the record is returned on success.
	// If the function errored it will return.
	WriteOne(id IDocumentID, doc IDocument) error

	// UpdateFor updates the specified field with the given value for the provided mongoms.
	//
	// Parameters:
	// - field: The name of the field to be updated.
	// - value: The new value for the field.
	// - document: The document values to update.
	//
	// Returns:
	// - An error if the update operation fails.
	UpdateFor(field string, fieldValue any, document IDocument) error

	// DeleteOne deletes a mongoms specified by its id.
	//
	// id: the unique identifier of the mongoms to be deleted.
	// error: an error if the deletion fails.
	DeleteOne(id IDocumentID) error

	// RemoveIdsFromSet removes the given mongoms ID from a set of mongoms ids.
	//
	// id: the mongoms ID to be removed.
	// field: the field to be updated.
	// ids: additional mongoms IDs to be removed.
	// error: if an error occurs during the removal process.
	RemoveIdsFromSet(id IDocumentID, field string, ids ...IDocumentID) error

	// AddIdsToSet adds the given mongoms ID to a set of ids, identified by the specified field, in a given mongoms ID.
	//
	// Parameters:
	// - id: The mongoms ID of the set to which the IDs will be added.
	// - field: The field in the set to which the IDs will be added.
	// - ids: The mongoms IDs to be added to the set.
	//
	// Returns:
	// - error: An error if there was a problem adding the IDs to the set.
	AddIdsToSet(id IDocumentID, field string, ids ...IDocumentID) error

	// RemoveFromSet removes the specified values from the set associated with the given mongoms ID and field.
	//
	// Parameters:
	// - id: The mongoms ID.
	// - field: The field associated with the set.
	// - values: The values to remove from the set.
	//
	// Returns:
	// - An error if the operation fails.
	RemoveFromSet(id IDocumentID, field string, values ...any) error

	// AddToSet adds the specified values to the set associated with the given mongoms ID and field.
	//
	// Parameters:
	// - id: The mongoms ID.
	// - field: The field associated with the set.
	// - values: The values to add to the set.
	//
	// Returns:
	// - An error if the operation fails.
	AddToSet(id IDocumentID, field string, values ...any) error

	// UpdateToSetById updates a mongoms by its ID with a new value for a specific field.
	//
	// - id: the ID of the mongoms to update.
	// - field: the field to update.
	// - idField: the ID field of the mongoms to update.
	// - subRID: the ID of the sub-mongoms to update.
	// - update: the new value for the field.
	//
	// Returns an error if the update operation fails.
	UpdateToSetById(id IDocumentID, field string, idField string, subID IDocumentID, update any) error

	// RemoveField removes a field from a mongoms identified by its id.
	//
	// Parameters:
	//   - id: the mongoms ID of the mongoms to remove the field from.
	//   - field: the name of the field to remove from the mongoms.
	//
	// Returns:
	//   - error: an error, if any, encountered during the field removal process.
	RemoveField(id IDocumentID, field string) error

	// IncField increments the value of a field in a mongoms identified by its id
	//
	// query: the MongoDB query document.
	// field: the name of the field to increment.
	// Returns an error if there was a problem incrementing the field.
	IncField(query bson.M, field string) error

	Drop() error
}

type SimpleDocumentID

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

SimpleDocumentID represents the Resource Identifier which is a string

func (*SimpleDocumentID) Clone

func (sid *SimpleDocumentID) Clone() any

func (*SimpleDocumentID) Equals

func (sid *SimpleDocumentID) Equals(id IDocumentID) bool

func (*SimpleDocumentID) GetNativeRecordId

func (sid *SimpleDocumentID) GetNativeRecordId() any

func (*SimpleDocumentID) MarshalJSON

func (sid *SimpleDocumentID) MarshalJSON() ([]byte, error)

func (*SimpleDocumentID) SetNativeRecordId

func (sid *SimpleDocumentID) SetNativeRecordId(value any) error

func (*SimpleDocumentID) String

func (sid *SimpleDocumentID) String() string

func (*SimpleDocumentID) UnmarshalBSON

func (sid *SimpleDocumentID) UnmarshalBSON(data []byte) error

UnmarshalBSON customizes the BSON un-marshaling of ID.

func (*SimpleDocumentID) UnmarshalJSON

func (sid *SimpleDocumentID) UnmarshalJSON(raw []byte) error

UnmarshalJSON un-marshals the raw JSON which contains a string in to a SimpleDocumentID object.

It takes a byte slice as input which represents the raw JSON data. Returns an error if there is an issue un-marshaling the data.

type TransformFunc

type TransformFunc func(any) (any, error)

TransformFunc is a function that transforms one object type to another object type in a query pipeline. Useful for enriching results with additional information or reducing the number of fields returned type TransformFunc func(any) (any, error)