model

type BatchError struct {
	// Total is the number of keys in the batch request.
	Total int
	// Failed is the number of keys that encountered a real retrieval error.
	Failed int
	// KeyErrors maps each failed key to its specific error.
	KeyErrors map[string]error
}

type CacheBucket interface {
	Name() string
	// Docs returns docs parallel to keys. nil at index i means keys[i] not found (not an error).
	// Returns *BatchError if one or more keys encountered real retrieval errors.
	Docs(ctx context.Context, keys []string) ([]CacheDoc, error)
	// Values returns values parallel to keys. nil at index i means keys[i] not found (not an error).
	// Returns *BatchError if one or more keys encountered real retrieval errors.
	Values(ctx context.Context, keys []string) ([]any, error)
	Update(ctx context.Context, key string, data any) (CacheDoc, error)
	// UpdateWithTs return doc, updated flag, and error
	UpdateWithTs(ctx context.Context, key string, data any, ts time.Time) (CacheDoc, bool, error)
	//Filter return all keys that match the given label filters
	Filter(ctx context.Context, labelFilters ...[]string) ([]string, error)
	// Scan return all keys that match the given pattern
	Scan(ctx context.Context, match string) ([]string, error)
	Remove(ctx context.Context, keys []string) error
	Clear(ctx context.Context) error
	Delete(ctx context.Context) error
}

type CacheClient interface {
	WithBucket(CacheBucket) CacheBucket
	Bucket(name string) CacheBucket
	Buckets() []CacheBucket
	RemoveBucket(bktName string)

	Collection(name string) CacheCollection
	Collections() []CacheCollection
	RemoveCollection(name string)

	Timeline(name string) CacheTimeline
	Timelines() []CacheTimeline
	RemoveTimeline(name string) error
}

type CacheCollection interface {
	Name() string
	Keys(ctx context.Context) ([]string, error)
	MembersMap(ctx context.Context, key string) (MembersMap, error)
	MembersMaps(ctx context.Context, keys []string) ([]MembersMap, error)
	Add(ctx context.Context, key string, members []string) error
	Remove(ctx context.Context, key string, members []string) error
	Clear(ctx context.Context, key string) error
	ClearAll(ctx context.Context) error
	Delete(ctx context.Context) error
}

type CacheDoc interface {
	CacheTime
	CacheExpire
	Key() string
	Val(ctx context.Context) (any, error)
	SetValue(ctx context.Context, val any) error
	Labels(ctx context.Context) (LabelSet, error)
	AddLabels(ctx context.Context, labels []string) error
	RemoveLabels(ctx context.Context, labels []string) error
	Delete(ctx context.Context) error
}

type CacheExpire interface {
	Expire(d time.Duration, onExpire func(CacheDoc)) error
	CancelExpire() error
}

type CacheTime interface {
	WithTime(ctx context.Context, ts time.Time) error
	// SetValueWithTs returns updated flag and error
	SetValueWithTs(ctx context.Context, val any, ts time.Time) (bool, error)
	Time(ctx context.Context) (time.Time, error)
}

type CacheTimeline interface {
	// Name returns the timeline name.
	Name() string

	// Append adds or updates fields at the specified timestamp.
	// Optimized for chronological writes (ts >= last timestamp).
	// If force is false, returns error if any field already exists at timestamp.
	// If force is true, overwrites existing fields.
	Append(ctx context.Context, key string, ts time.Time, data map[string]string, force bool) error

	// Insert adds or updates fields at the specified timestamp.
	// Supports out-of-order writes at any historical position.
	// If force is false, returns error if any field already exists at timestamp.
	// If force is true, overwrites existing fields.
	Insert(ctx context.Context, key string, ts time.Time, data map[string]string, force bool) error

	// GetAt returns the complete merged state at or before ts for each key.
	// Results are parallel to keys: results[i] corresponds to keys[i].
	// nil at results[i] means keys[i] has no state at or before ts (not an error).
	// Returns *BatchError if one or more keys encountered retrieval errors.
	GetAt(ctx context.Context, keys []string, ts time.Time) ([]map[string]string, error)

	// GetExact returns the raw sparse fields at the exact timestamp for each key.
	// Results are parallel to keys: results[i] corresponds to keys[i].
	// nil at results[i] means keys[i] has no time point at exactly ts (not an error).
	// Returns *BatchError if one or more keys encountered retrieval errors.
	GetExact(ctx context.Context, keys []string, ts time.Time) ([]map[string]string, error)

	// GetRange returns all complete states in [start, end] for each key.
	// Results are parallel to keys: results[i] corresponds to keys[i].
	// nil at results[i] means keys[i] has no time points in the range (not an error).
	// Non-nil inner slices contain only non-nil *TimeValue pointers.
	// Returns *BatchError if one or more keys encountered retrieval errors.
	GetRange(ctx context.Context, keys []string, start, end time.Time) ([][]*TimeValue, error)

	// GetLatest returns the complete merged state at the most recent timestamp for each key.
	// Results are parallel to keys: results[i] corresponds to keys[i].
	// nil at results[i] means keys[i] has no time-series data (not an error).
	// Returns *BatchError if one or more keys encountered retrieval errors.
	GetLatest(ctx context.Context, keys []string) ([]map[string]string, error)

	// Timeline returns all complete states for the key in chronological order.
	// Each element is a non-nil *TimeValue pointer.
	Timeline(ctx context.Context, key string) ([]*TimeValue, error)

	// GetAffectedRange returns all states from insertedAt (inclusive) to end of timeline.
	// Used for recomputation after historical insertion.
	// Each element is a non-nil *TimeValue pointer.
	GetAffectedRange(ctx context.Context, key string, insertedAt time.Time) ([]*TimeValue, error)

	// WithRetention sets the retention policy for the timeline and returns self for method chaining.
	// The policy applies to all keys in the timeline.
	// Retention policy is stored in-memory only and must be set after timeline creation.
	WithRetention(policy RetentionPolicy) CacheTimeline

	// GetRetention returns the timeline's retention policy.
	// Returns zero values (MaxCount: 0, MaxDuration: 0) if no policy has been set, meaning unlimited retention.
	GetRetention() RetentionPolicy

	// Keys returns all logical keys in the timeline.
	// With no label filter arguments, all keys are returned.
	// Labels within a single []string argument are OR'd together.
	// Multiple arguments are AND'd: Keys(ctx, []string{"a","b"}, []string{"c"})
	// returns keys that have (a OR b) AND c.
	Keys(ctx context.Context, labelFilters ...[]string) ([]string, error)

	// AddKeyLabels associates labels with a logical key.
	// Empty strings in labels are ignored. Adding an existing label is a no-op.
	AddKeyLabels(ctx context.Context, key string, labels []string) error

	// RemoveKeyLabels removes labels from a logical key.
	// Removing a non-existent label is a no-op.
	RemoveKeyLabels(ctx context.Context, key string, labels []string) error

	// KeyLabels returns the set of labels associated with a logical key.
	// Returns an empty LabelSet if the key has no labels or does not exist.
	KeyLabels(ctx context.Context, key string) (LabelSet, error)

	// GetUpdatedKeys returns all keys that have been updated after the specified timestamp.
	// The timestamp boundary is exclusive: only keys with updates strictly after the timestamp are returned.
	// Each key appears at most once in the result, even if it was updated multiple times.
	// Result order is unordered and implementation-defined.
	// Returns an empty slice if no keys were updated after the timestamp.
	GetUpdatedKeys(ctx context.Context, after time.Time) ([]string, error)

	// Remove removes the specified keys from the timeline.
	Remove(ctx context.Context, keys []string) error

	// Clear removes all data from the timeline but keeps the timeline instance.
	Clear(ctx context.Context) error

	// Delete removes the timeline instance from the client.
	Delete(ctx context.Context) error
}

type Coder interface {
	Encoder
	Decoder
}

type Decoder interface {
	Decode(data string, out any) error
}

type Encoder interface {
	Encode(data any) (string, error)
}

type LabelSet map[string]bool

type Logger interface {
	// Debug logs a debug message with optional key-value pairs
	Debug(msg string, keysAndValues ...any)
	// Info logs an informational message with optional key-value pairs
	Info(msg string, keysAndValues ...any)
	// Error logs an error message with optional key-value pairs
	Error(msg string, keysAndValues ...any)
	// Fatal logs an error message and then panics
	// This is used for critical errors that should stop execution
	Fatal(msg string, keysAndValues ...any)
}

type MembersMap map[string]struct{}

type RetentionPolicy struct {
	MaxCount    int               // Maximum number of time points per key (0 = unlimited)
	MaxDuration time.Duration     // Maximum age of time points (0 = unlimited)
	Strategy    RetentionStrategy // Strategy for applying count and duration constraints
}

type RetentionStrategy int

type TimeValue struct {
	Time  time.Time
	Value map[string]string
}