versioned

type ElementEdit struct {
	OldElement *Object
	NewElement *Object
	Operation  KeyOperation
}

type KV interface {
	// Get returns the object stored at the specified version.
	Get(key string, version uint64) (*Object, error)

	// GetAndUpgrade gets and upgrades data stored in the key/value store.
	// Make sure to inspect the version returned in the versioned object.
	GetAndUpgrade(key string, ut UpgradeTable) (*Object, error)

	// Delete removes a given key from the data store.
	Delete(key string, version uint64) error

	// Set upserts new data into the storage
	Set(key string, object *Object) error

	// StoreMapElement stores a versioned map element into the KV. This relies
	// on the underlying remote [KV.StoreMapElement] function to lock and control
	// updates, but it uses [versioned.Object] values.
	// The version of the value must match the version of the map.
	// All Map storage functions update the remote.
	StoreMapElement(mapName, elementName string, value *Object,
		mapVersion uint64) error

	// StoreMap saves a versioned map element into the KV. This relies
	// on the underlying remote [KV.StoreMap] function to lock and control
	// updates, but it uses [versioned.Object] values.
	// the version of values must match the version of the map
	// All Map storage functions update the remote.
	StoreMap(mapName string, values map[string]*Object, mapVersion uint64) error

	// GetMap loads a versioned map from the KV. This relies
	// on the underlying remote [KV.GetMap] function to lock and control
	// updates, but it uses [versioned.Object] values.
	GetMap(mapName string, mapVersion uint64) (map[string]*Object, error)

	// GetMapElement loads a versioned map element from the KV. This relies
	// on the underlying remote [KV.GetMapElement] function to lock and control
	// updates, but it uses [versioned.Object] values.
	GetMapElement(mapName, elementName string, mapVersion uint64) (
		*Object, error)

	// DeleteMapElement removes a map element from the list. It
	// returns the element that was deleted and any errors if they occur.
	DeleteMapElement(mapName, elementName string, mapVersion uint64) (
		*Object, error)

	// ListenOnRemoteKey allows the caller to receive updates when
	// a key is updated by synching with another client.
	// Only one callback can be written per key.
	// On call, a state update will be created on the callback containing
	// the current state of the key as a creation event. This call will occur
	// in the go routine that ListenOnRemoteKey is called from, blocking its
	// return until the callback returns.
	// If local Events is true, the callback will also trigger when
	// setting this key locally
	ListenOnRemoteKey(key string, version uint64,
		callback KeyChangedByRemoteCallback, localEvents bool) error

	// ListenOnRemoteMap allows the caller to receive updates when
	// the map or map elements are updated
	// Only one callback can be written per map.
	// On call, a state update will be created on the callback containing
	// the entire state of the map as a creation event. This call will occur
	// in the go routine that ListenOnRemoteMap is called from, blocking its
	// return until the callback returns.
	// If local Events is true, the callback will also trigger when
	// modifying this map locally
	ListenOnRemoteMap(mapName string, version uint64,
		callback MapChangedByRemoteCallback, localEvents bool) error

	// GetPrefix returns the full Prefix of the KV
	GetPrefix() string

	// HasPrefix returns whether this prefix exists in the KV
	HasPrefix(prefix string) bool

	// Prefix returns a new KV with the new prefix appending
	Prefix(prefix string) (KV, error)

	// Root returns the KV with no prefixes
	Root() KV

	// IsMemStore returns true if the underlying KV is memory based
	IsMemStore() bool

	// GetFullKey returns the key with all prefixes appended
	GetFullKey(key string, version uint64) string

	// Exists returns if the error indicates a KV error showing
	// the key exists.
	Exists(err error) bool

	// StartProcesses starts any applicable networking processes
	StartProcesses() (stoppable.Stoppable, error)
}

type KeyChangedByRemoteCallback func(old, new *Object, op KeyOperation)

type KeyOperation uint8

type KeyType uint8

type MapChangedByRemoteCallback func(edits map[string]ElementEdit)

type Object struct {
	// Used to determine version Upgrade, if any
	Version uint64

	// Set when this object is written
	Timestamp time.Time

	// Serialized version of original object
	Data []byte
}

type TransactionOperation func(old *Object, existed bool) (data *Object,
	err error)

type Upgrade func(oldObject *Object) (*Object,
	error)

type UpgradeTable struct {
	CurrentVersion uint64
	Table          []Upgrade
}