database

type AggFunc string

type FilterFunction func(raw map[string]any, filter QueryFilter) bool

type IAdvancedQuery interface {
	IQuery
	IQueryAnalytic
}

type IDataCache interface {

	// Closer includes method Close()
	io.Closer

	// Ping tests connectivity for retries number of time with time interval (in seconds) between retries
	Ping(retries uint, intervalInSeconds uint) error

	// CloneDataCache Returns a clone (copy) of the instance
	CloneDataCache() (IDataCache, error)

	// Get the value of a key
	Get(factory EntityFactory, key string) (Entity, error)

	// GetRaw gets the raw value of a key
	GetRaw(key string) ([]byte, error)

	// GetKeys Get the value of all the given keys
	GetKeys(factory EntityFactory, keys ...string) ([]Entity, error)

	// GetRawKeys gets the raw value of all the given keys
	GetRawKeys(keys ...string) ([]Tuple[string, []byte], error)

	// Set value of key with optional expiration
	Set(key string, entity Entity, expiration ...time.Duration) error

	// SetRaw sets the raw value of key with optional expiration
	SetRaw(key string, bytes []byte, expiration ...time.Duration) error

	// SetNX sets value of key only if it is not exist with optional expiration, return false if the key exists
	SetNX(key string, entity Entity, expiration ...time.Duration) (bool, error)

	// SetRawNX sets the raw value of key only if it is not exist with optional expiration, return false if the key exists
	SetRawNX(key string, bytes []byte, expiration ...time.Duration) (bool, error)

	// Add Set the value of a key only if the key does not exist
	Add(key string, entity Entity, expiration time.Duration) (bool, error)

	// AddRaw sets the raw value of a key only if the key does not exist
	AddRaw(key string, bytes []byte, expiration time.Duration) (bool, error)

	// Del Delete keys
	Del(keys ...string) (err error)

	// Rename a key
	Rename(key string, newKey string) (err error)

	// Exists Check if key exists
	Exists(key string) (result bool, err error)

	// Scan keys from the provided cursor
	Scan(from uint64, match string, count int64) (keys []string, cursor uint64, err error)

	// HGet gets the value of a hash field
	HGet(factory EntityFactory, key, field string) (result Entity, err error)

	// HGetRaw gets the raw value of a hash field
	HGetRaw(key, field string) ([]byte, error)

	// HKeys gets all the fields in a hash
	HKeys(key string) (fields []string, err error)

	// HGetAll gets all the fields and values in a hash
	HGetAll(factory EntityFactory, key string) (result map[string]Entity, err error)

	// HGetRawAll gets all the fields and raw values in a hash
	HGetRawAll(key string) (result map[string][]byte, err error)

	// HSet sets the value of a hash field
	HSet(key, field string, entity Entity) (err error)

	// HSetRaw sets the raw value of a hash field
	HSetRaw(key, field string, bytes []byte) (err error)

	// HSetNX Set value of key only if it is not exist with optional expiration, return false if the key exists
	HSetNX(key, field string, entity Entity) (result bool, err error)

	// HSetRawNX sets the raw value of key only if it is not exist with optional expiration, return false if the key exists
	HSetRawNX(key, field string, bytes []byte) (result bool, err error)

	// HDel delete one or more hash fields
	HDel(key string, fields ...string) (err error)

	// HAdd sets the value of a key only if the key does not exist
	HAdd(key, field string, entity Entity) (result bool, err error)

	// HAddRaw sets the raw value of a key only if the key does not exist
	HAddRaw(key, field string, bytes []byte) (result bool, err error)

	// HExists Check if key exists
	HExists(key, field string) (result bool, err error)

	// RPush Append one or multiple values to a list
	RPush(key string, value ...Entity) (err error)

	// LPush Prepend one or multiple values to a list
	LPush(key string, value ...Entity) (err error)

	// RPop Remove and get the last element in a list
	RPop(factory EntityFactory, key string) (entity Entity, err error)

	// LPop Remove and get the first element in a list
	LPop(factory EntityFactory, key string) (entity Entity, err error)

	// BRPop Remove and get the last element in a list or block until one is available
	BRPop(factory EntityFactory, timeout time.Duration, keys ...string) (key string, entity Entity, err error)

	// BLPop Remove and get the first element in a list or block until one is available
	BLPop(factory EntityFactory, timeout time.Duration, keys ...string) (key string, entity Entity, err error)

	// LRange Get a range of elements from list
	LRange(factory EntityFactory, key string, start, stop int64) (result []Entity, err error)

	// LLen Get the length of a list
	LLen(key string) (result int64)

	// ObtainLocker tries to obtain a new lock using a key with the given TTL
	ObtainLocker(key string, ttl time.Duration) (ILocker, error)
}

type IDatabase interface {

	// Closer includes method Close()
	io.Closer

	// Ping Test database connectivity for retries number of time with time interval (in seconds) between retries
	Ping(retries uint, intervalInSeconds uint) error

	// CloneDatabase Returns a clone (copy) of the database instance
	CloneDatabase() (IDatabase, error)

	// Get a single entity by ID
	Get(factory EntityFactory, entityID string, keys ...string) (result Entity, err error)

	// List Get multiple entities by IDs
	List(factory EntityFactory, entityIDs []string, keys ...string) (list []Entity, err error)

	// Exists Check if entity exists by ID
	Exists(factory EntityFactory, entityID string, keys ...string) (result bool, err error)

	// Insert new entity
	Insert(entity Entity) (added Entity, err error)

	// Update existing entity
	Update(entity Entity) (updated Entity, err error)

	// Upsert Update entity or create it if it does not exist
	Upsert(entity Entity) (updated Entity, err error)

	// Delete entity by id and shard (key)
	Delete(factory EntityFactory, entityID string, keys ...string) (err error)

	// BulkInsert Insert multiple entities
	BulkInsert(entities []Entity) (affected int64, err error)

	// BulkUpdate Update multiple entities
	BulkUpdate(entities []Entity) (affected int64, err error)

	// BulkUpsert Update or insert multiple entities
	BulkUpsert(entities []Entity) (affected int64, err error)

	// BulkDelete Delete multiple entities by IDs
	BulkDelete(factory EntityFactory, entityIDs []string, keys ...string) (affected int64, err error)

	// SetField Update single field of the document in a single transaction (eliminates the need to fetch - change - update)
	SetField(factory EntityFactory, entityID string, field string, value any, keys ...string) (err error)

	// SetFields Update some fields of the document in a single transaction (eliminates the need to fetch - change - update)
	SetFields(factory EntityFactory, entityID string, fields map[string]any, keys ...string) (err error)

	// BulkSetFields Update specific field of multiple entities in a single transaction (eliminates the need to fetch - change - update)
	// The field is the name of the field, values is a map of entityId -> field value
	BulkSetFields(factory EntityFactory, field string, values map[string]any, keys ...string) (affected int64, err error)

	// Query Utility struct method to build a query
	Query(factory EntityFactory) IQuery

	// descriptive comment will follow. for now: it returns an implementation of
	// composed interface IAdvancedQuery, which is composition of IQuery and IQueryAnalytic
	// and is intended to work with sharded tables ( via EntitySharded )
	QueryAdvanced(factory EntityFactory) IAdvancedQuery

	// ExecuteDDL Execute DDL - create table and indexes
	ExecuteDDL(ddl map[string][]string) (err error)

	// ExecuteSQL Execute SQL - execute SQL command
	ExecuteSQL(sql string, args ...any) (affected int64, err error)

	// ExecuteQuery Execute native SQL query
	ExecuteQuery(source, sql string, args ...any) ([]Json, error)

	// DropTable Drop table and indexes
	DropTable(table string) (err error)

	// PurgeTable Fast delete table content (truncate)
	PurgeTable(table string) (err error)
}

type IDatastore interface {

	// Closer includes method Close()
	io.Closer

	// Ping tests database connectivity for retries number of time with time interval (in seconds) between retries
	Ping(retries uint, intervalInSeconds uint) error

	// CloneDatastore Returns a clone (copy) of the instance
	CloneDatastore() (IDatastore, error)

	// Get a single entity by ID
	Get(factory EntityFactory, entityID string, keys ...string) (result Entity, err error)

	// List gets multiple entities by IDs
	List(factory EntityFactory, entityIDs []string, keys ...string) (list []Entity, err error)

	// Exists checks if entity exists by ID
	Exists(factory EntityFactory, entityID string, keys ...string) (result bool, err error)

	// Insert a new entity
	Insert(entity Entity) (added Entity, err error)

	// Update an existing entity
	Update(entity Entity) (updated Entity, err error)

	// Upsert update entity or create it if it does not exist
	Upsert(entity Entity) (updated Entity, err error)

	// Delete entity by id and shard (key)
	Delete(factory EntityFactory, entityID string, keys ...string) (err error)

	// BulkInsert inserts multiple entities
	BulkInsert(entities []Entity) (affected int64, err error)

	// BulkUpdate updates multiple entities
	BulkUpdate(entities []Entity) (affected int64, err error)

	// BulkUpsert update or insert multiple entities
	BulkUpsert(entities []Entity) (affected int64, err error)

	// BulkDelete delete multiple entities by IDs
	BulkDelete(factory EntityFactory, entityIDs []string, keys ...string) (affected int64, err error)

	// SetField update a single field of the document in a single transaction (eliminates the need to fetch - change - update)
	SetField(factory EntityFactory, entityID string, field string, value any, keys ...string) (err error)

	// SetFields update some fields of the document in a single transaction (eliminates the need to fetch - change - update)
	SetFields(factory EntityFactory, entityID string, fields map[string]any, keys ...string) (err error)

	// Query is a factory method for query builder Utility
	Query(factory EntityFactory) IQuery

	// IndexExists tests if index exists
	IndexExists(indexName string) (exists bool)

	// CreateIndex creates an index (without mapping)
	CreateIndex(indexName string) (name string, err error)

	// CreateEntityIndex creates an index of entity and add entity field mapping
	CreateEntityIndex(factory EntityFactory, key string) (name string, err error)

	// ListIndices returns a list of all indices matching the pattern
	ListIndices(pattern string) (map[string]int, error)

	// DropIndex drops an index
	DropIndex(indexName string) (ack bool, err error)

	// ExecuteQuery Execute native KQL query
	ExecuteQuery(source string, query string, args ...any) ([]Json, error)
}

type ILocker interface {
	// Key returns the locker key
	Key() string

	// Token returns the token value set by the lock.
	Token() string

	// TTL returns the remaining time-to-live. Returns 0 if the lock has expired.
	TTL(ctx context.Context) (time.Duration, error)

	// Refresh extends the lock with a new TTL.
	Refresh(ctx context.Context, ttl time.Duration) error

	// Release manually releases the lock.
	Release(ctx context.Context) error
}

type IQuery interface {

	// Apply adds a callback to apply on each result entity in the query
	Apply(cb func(in Entity) Entity) IQuery

	// Filter Add single field filter
	Filter(filter QueryFilter) IQuery

	// Range add time frame filter on specific time field
	Range(field string, from Timestamp, to Timestamp) IQuery

	// MatchAll Add list of filters, all of them should be satisfied (AND)
	MatchAll(filters ...QueryFilter) IQuery

	// MatchAny Add list of filters, any of them should be satisfied (OR)
	MatchAny(filters ...QueryFilter) IQuery

	// Sort Add sort order by field,  expects sort parameter in the following form: field_name (Ascending) or field_name- (Descending)
	Sort(sort string) IQuery

	// Page Set page number (for pagination)
	Page(page int) IQuery

	// Limit Set page size limit (for pagination)
	Limit(page int) IQuery

	// List Execute a query to get list of entities by IDs (the criteria is ignored)
	List(entityIDs []string, keys ...string) (out []Entity, err error)

	// Find Execute the query based on the criteria, order and pagination
	Find(keys ...string) (out []Entity, total int64, err error)

	// Select is similar to find but with ability to retrieve specific fields
	Select(fields ...string) ([]Json, error)

	// Count Execute the query based on the criteria, order and pagination and return only the count of matching rows
	Count(keys ...string) (total int64, err error)

	// Aggregation Execute the query based on the criteria, order and pagination and return the provided aggregation function on the field
	// supported functions: count : avg, sum, min, max
	Aggregation(field string, function AggFunc, keys ...string) (value float64, err error)

	// GroupCount Execute the query based on the criteria, grouped by field and return count per group
	GroupCount(field string, keys ...string) (out map[any]int64, total int64, err error)

	// GroupAggregation Execute the query based on the criteria, order and pagination and return the aggregated value per group
	// the data point is a calculation of the provided function on the selected field, each data point includes the number of documents and the calculated value
	// the total is the sum of all calculated values in all the buckets
	// supported functions: count : avg, sum, min, max
	GroupAggregation(field string, function AggFunc, keys ...string) (out map[any]Tuple[int64, float64], total float64, err error)

	// Histogram returns a time series data points based on the time field, supported intervals: Minute, Hour, Day, week, month
	// the data point is a calculation of the provided function on the selected field, each data point includes the number of documents and the calculated value
	// the total is the sum of all calculated values in all the buckets
	// supported functions: count : avg, sum, min, max
	Histogram(field string, function AggFunc, timeField string, interval time.Duration, keys ...string) (out map[Timestamp]Tuple[int64, float64], total float64, err error)

	// Histogram2D returns a two-dimensional time series data points based on the time field, supported intervals: Minute, Hour, Day, week, month
	// the data point is a calculation of the provided function on the selected field
	// supported functions: count : avg, sum, min, max
	Histogram2D(field string, function AggFunc, dim, timeField string, interval time.Duration, keys ...string) (out map[Timestamp]map[any]Tuple[int64, float64], total float64, err error)

	// FindSingle Execute query based on the where criteria to get a single (the first) result
	FindSingle(keys ...string) (entity Entity, err error)

	// GetMap Execute query based on the criteria, order and pagination and return the results as a map of id->Entity
	GetMap(keys ...string) (out map[string]Entity, err error)

	// GetIDs executes a query based on the where criteria, order and pagination and return the results as a list of Ids
	GetIDs(keys ...string) (out []string, err error)

	// Delete the entities satisfying the criteria
	Delete(keys ...string) (total int64, err error)

	// SetField Update single field of all the documents meeting the criteria in a single transaction
	SetField(field string, value any, keys ...string) (total int64, err error)

	// SetFields Update multiple fields of all the documents meeting the criteria in a single transaction
	SetFields(fields map[string]any, keys ...string) (total int64, err error)

	// ToString Get the string representation of the query
	ToString() string
}

type IQueryAnalytic interface {
	Sum(fieldName string) IQueryAnalytic
	Min(fieldName string) IQueryAnalytic
	Max(fieldName string) IQueryAnalytic
	Avg(fieldName string) IQueryAnalytic
	CountAll(fieldName string) IQueryAnalytic
	CountUnique(fieldName string) IQueryAnalytic
	GroupBy(fieldName string, timePeriod e.TimePeriodCode) IQueryAnalytic
	Compute() (out []e.Entity, err error)
}

type ITable interface {

	// Get single entity by ID
	Get(entityID string) (entity Entity, err error)

	// Exists checks if entity exists by ID
	Exists(entityID string) (result bool, err error)

	// Insert entity
	Insert(entity Entity) (added Entity, err error)

	// Update entity
	Update(entity Entity) (added Entity, err error)

	// Upsert update entity or insert if not found
	Upsert(entity Entity) (added Entity, err error)

	// Delete entity
	Delete(entityID string) (err error)

	// Table get access to the underlying data structure
	Table() (result map[string]Entity)
}

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

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

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

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

type QueryFilter interface {

	// Eq - Equal
	Eq(value any) QueryFilter

	// Neq - Not equal
	Neq(value any) QueryFilter

	// Like - similar
	Like(value string) QueryFilter

	// Gt - Greater than
	Gt(value any) QueryFilter

	// Gte - Greater or equal
	Gte(value any) QueryFilter

	// Lt - Less than
	Lt(value any) QueryFilter

	// Lte - Less or equal
	Lte(value any) QueryFilter

	// In - match one of the values
	In(values ...any) QueryFilter

	// NotIn - Not In
	NotIn(values ...any) QueryFilter

	// InSubQuery - match one of the values in the result of the sub query
	InSubQuery(field string, subQuery IQuery) QueryFilter

	// NotInSubQuery - exclude any record matching one of the values in the result of the sub query
	NotInSubQuery(field string, subQuery IQuery) QueryFilter

	// Between - equal or greater than the lower boundary and equal or less than the upper boundary
	Between(value1, value2 any) QueryFilter

	// Contains - a field of type array contains the provided value
	Contains(value any) QueryFilter

	// IsEmpty - field is null or empty
	IsEmpty() QueryFilter

	// If - Include this filter only if condition is true
	If(value bool) QueryFilter

	// IsActive Include this filter only if condition is true
	IsActive() bool

	// GetField Get the field name
	GetField() string

	// GetOperator Get the criteria operator
	GetOperator() QueryOperator

	// GetValues Get the criteria values
	GetValues() []any

	// GetStringValue Get string representation of the value
	GetStringValue(index int) string

	// GetSubQuery gets the underlying sub-query
	GetSubQuery() IQuery

	// GetSubQueryField gets the underlying sub-query field
	GetSubQueryField() string
}

type QueryOperator string