caches

package module
v0.0.1-beta.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 12, 2025 License: MIT Imports: 3 Imported by: 2

README ¶

go-caches

A unified caching interface for Go applications with pluggable backends (Redis and Redka). This library provides a consistent API for cache operations while allowing you to switch between different storage backends without changing your application code.

Features

  • 🔄 Unified Interface: Single API for multiple cache backends
  • 📦 Multiple Providers: Support for Redis and Redka (SQLite-based) backends
  • 🎯 Type-Safe: Generic results with proper error handling using Result[T]
  • âš¡ Full Redis API Support: Complete implementation of Redis commands
  • 🔧 Namespace Isolation: Key prefixing for multi-tenant applications
  • 🧪 Well Tested: Comprehensive test suite with integration tests
  • 📈 High Performance: Minimal overhead and efficient backend implementations

Quick Start

Installation
go get github.com/rockcookies/go-caches
go get github.com/rockcookies/go-caches/providers/redis
go get github.com/rockcookies/go-caches/providers/redka
Basic Usage
package main

import (
    "context"
    "fmt"
    "time"

    "github.com/redis/go-redis/v9"
    "github.com/rockcookies/go-caches"
    "github.com/rockcookies/go-caches/providers/redis"
)

func main() {
    // Redis Provider
    rdb := redis.NewClient(&redis.Options{
        Addr: "localhost:6379",
    })

    cache := redis.New(rdb)
    ctx := context.Background()

    // Set a value
    result := cache.Set(ctx, "key", "value", time.Hour)
    if result.Err() != nil {
        panic(result.Err())
    }

    // Get a value
    value := cache.Get(ctx, "key")
    if value.Err() != nil {
        panic(value.Err())
    }

    fmt.Printf("Value: %s\n", string(value.Val()))
}
Switching Backends
// Redis Provider
redisCache := redis.New(redisClient)

// Redka Provider (SQLite-based)
redkaCache, _ := redka.New("file:cache.db?mode=memory")

// Both implement the same interface!
func useCache(cache caches.StringCommand) {
    // Your cache logic works with any provider
    result := cache.Get(ctx, "key")
    // ...
}

API Overview

The library provides six main command interfaces:

StringCommand

String value operations with atomic increments/decrements:

// Basic operations
cache.Set(ctx, "counter", "0", 0)           // Set value
result := cache.Get(ctx, "counter")         // Get value

// Atomic operations
cache.Incr(ctx, "counter")                  // Increment by 1
cache.IncrBy(ctx, "counter", 10)            // Increment by 10
cache.DecrBy(ctx, "counter", 5)             // Decrement by 5

// Multi-key operations
values := map[string]any{
    "key1": "value1",
    "key2": "value2",
}
cache.MSet(ctx, values)                     // Set multiple keys
KeyCommand

Key lifecycle management:

// Expiration
cache.Expire(ctx, "key", time.Hour)         // Set expiration
cache.TTL(ctx, "key")                       // Get remaining TTL
cache.Persist(ctx, "key")                   // Remove expiration

// Key operations
cache.Exists(ctx, "key1", "key2")           // Check if keys exist
cache.Del(ctx, "key1", "key2")              // Delete keys
cache.Type(ctx, "key")                      // Get key type
SetCommand, HashCommand, ListCommand, SortedSetCommand

Full Redis data structure support:

// Sets
cache.SAdd(ctx, "myset", "member1", "member2")
cache.SMembers(ctx, "myset")

// Hashes
cache.HSet(ctx, "myhash", "field", "value")
cache.HGet(ctx, "myhash", "field")

// Lists
cache.LPush(ctx, "mylist", "item1", "item2")
cache.LRange(ctx, "mylist", 0, -1)

// Sorted Sets
cache.ZAdd(ctx, "myzset", &caches.ZMember{
    Member: []byte("member"),
    Score:  1.0,
})
cache.ZRange(ctx, "myzset", 0, -1)

Configuration

Provider Options
// With key prefixing for namespace isolation
options := &redis.Options{
    Prefix: "myapp:v1:",
}

cache := redis.NewWithOptions(redisClient, options)
Advanced Set Operations
args := caches.SetArgs{
    Mode:    "NX",        // Set only if key doesn't exist
    TTL:     time.Hour,   // Auto-expire after 1 hour
    Get:     true,        // Return old value
    KeepTTL: false,       // Don't preserve existing TTL
}

result := cache.SetArgs(ctx, "key", "value", args)

Error Handling

The library uses a consistent Result[T] pattern for error handling:

result := cache.Get(ctx, "key")

// Check for errors
if result.Err() != nil {
    if result.Err() == caches.Nil {
        fmt.Println("Key does not exist")
    } else {
        fmt.Printf("Error: %v\n", result.Err())
    }
    return
}

// Get the value (zero value if error occurred)
value := result.Val()

// Or get both at once
value, err := result.Result()

Testing

The library includes comprehensive tests:

# Run all tests
go test -race -coverprofile=coverage.out ./tests/

# Run specific provider tests
go test -v -run TestRedis ./tests/
go test -v -run TestRedka ./tests/

# Skip integration tests (CI environments)
go test -short ./tests/

Providers

Redis Provider
  • Backend: Redis server using github.com/redis/go-redis/v9
  • Features: Full Redis API support, clustering, sentinel support
  • Requirements: Redis server running on localhost:6379 (for development)
Redka Provider
  • Backend: SQLite using github.com/nalgeon/redka
  • Features: Zero dependencies, in-memory databases, transactions
  • Requirements: None (uses embedded SQLite)

Architecture

The library follows an interface-driven design:

caches package (interfaces)
├── StringCommand    # String operations
├── KeyCommand       # Key management
├── SetCommand       # Set data structure
├── HashCommand      # Hash data structure
├── ListCommand      # List data structure
└── SortedSetCommand # Sorted set data structure

providers/
├── redis/           # Redis provider implementation
└── redka/           # Redka provider implementation

Dependencies

  • Go: 1.21+ (root module), 1.21+ (provider modules)
  • Redis Provider: github.com/redis/go-redis/v9 v9.16.0
  • Redka Provider: github.com/nalgeon/redka v0.6.0
  • Testing: github.com/stretchr/testify v1.11.1

License

[Add your license information here]

Contributing

[Add contributing guidelines here]

Documentation ¶

Index ¶

Constants ¶

View Source 
const KeepTTL = -1
View Source 
const Nil = error.Nil

Variables ¶

This section is empty.

Functions ¶

func NewResult ¶ 

func NewResult[T any](result T, err error) *genericResult[T]

NewResult creates a new genericResult with the given value and error. This is intended to be used by providers with their own error handling.

Types ¶

type HScanResult ¶ 

type HScanResult struct {
	// Cursor is the cursor to use in the next scan call.
	// A cursor value of 0 indicates the iteration is complete.
	Cursor uint64
	// Fields contains the scanned fields and their values.
	Fields map[string][]byte
}

HScanResult represents the result of a hash scan operation.

type HashCommand ¶ 

type HashCommand interface {
	// HDel deletes one or more fields from a hash.
	// Returns the number of fields that were removed from the hash,
	// not including non-existing fields.
	HDel(ctx context.Context, key string, fields ...string) Result[int64]

	// HExists determines whether a field exists in a hash.
	// Returns true if the field exists, false otherwise.
	HExists(ctx context.Context, key string, field string) Result[bool]

	// HGet returns the value of a field in a hash.
	// Returns nil if the field does not exist.
	HGet(ctx context.Context, key string, field string) Result[[]byte]

	// HGetAll returns all fields and values in a hash.
	// Returns an empty map if the key does not exist.
	HGetAll(ctx context.Context, key string) Result[map[string][]byte]

	// HIncrBy increments the integer value of a hash field by the given number.
	// If the field does not exist, it is set to 0 before performing the operation.
	// Returns the value of the field after the increment.
	HIncrBy(ctx context.Context, key string, field string, increment int64) Result[int64]

	// HIncrByFloat increments the float value of a hash field by the given amount.
	// If the field does not exist, it is set to 0 before performing the operation.
	// Returns the value of the field after the increment.
	HIncrByFloat(ctx context.Context, key string, field string, increment float64) Result[float64]

	// HKeys returns all field names in a hash.
	// Returns an empty slice if the key does not exist.
	HKeys(ctx context.Context, key string) Result[[]string]

	// HLen returns the number of fields in a hash.
	// Returns 0 if the key does not exist.
	HLen(ctx context.Context, key string) Result[int64]

	// HMGet returns the values of multiple fields in a hash.
	// For each field that does not exist, nil is returned in the corresponding position.
	// Returns a map with field names as keys and values as byte slices.
	HMGet(ctx context.Context, key string, fields ...string) Result[map[string][]byte]

	// HMSet sets the values of multiple fields in a hash.
	// If the hash does not exist, it is created.
	// If a field already exists, its value is overwritten.
	HMSet(ctx context.Context, key string, values map[string]any) StatusResult

	// HScan iterates over fields and values of a hash.
	// cursor is the cursor to start iteration from (0 to start).
	// match is a glob-style pattern to filter fields (empty string for no filter).
	// count is a hint for how many fields to return per iteration.
	// Returns the next cursor and a map of fields and values.
	HScan(ctx context.Context, key string, cursor uint64, match string, count int64) Result[HScanResult]

	// HSet sets the values of one or more fields in a hash.
	// If the hash does not exist, it is created.
	// If a field already exists, its value is overwritten.
	// Returns the number of fields that were added (not including updated fields).
	HSet(ctx context.Context, key string, values map[string]any) Result[int64]

	// HSetNX sets the value of a field in a hash only if the field does not exist.
	// If the field already exists, this operation has no effect.
	// Returns true if the field was set, false if the field already existed.
	HSetNX(ctx context.Context, key string, field string, value any) Result[bool]

	// HVals returns all values in a hash.
	// Returns an empty slice if the key does not exist.
	HVals(ctx context.Context, key string) Result[[][]byte]
}

HashCommand defines operations for Redis hash data structure. Hashes are field-value maps where both field and value are strings.

type KeyCommand ¶ 

type KeyCommand interface {
	// DBSize returns the number of keys in the current database.
	DBSize(ctx context.Context) Result[int64]

	// Del deletes one or more keys.
	// Non-existing keys are ignored.
	// Returns the number of keys that were deleted.
	Del(ctx context.Context, keys ...string) Result[int64]

	// Exists checks if one or more keys exist.
	// Returns the number of keys that exist among the given keys.
	Exists(ctx context.Context, keys ...string) Result[int64]

	// Expire sets a timeout on a key using seconds.
	// After the timeout expires, the key will be automatically deleted.
	// Returns true if the timeout was set, false if the key does not exist.
	Expire(ctx context.Context, key string, expiration time.Duration) Result[bool]

	// ExpireNX sets a timeout on a key only if the key has no existing expiration.
	// Returns true if the timeout was set, false if the key does not exist or already has an expiration.
	ExpireNX(ctx context.Context, key string, expiration time.Duration) Result[bool]

	// ExpireXX sets a timeout on a key only if the key has an existing expiration.
	// Returns true if the timeout was set, false if the key does not exist or has no expiration.
	ExpireXX(ctx context.Context, key string, expiration time.Duration) Result[bool]

	// ExpireGT sets a timeout on a key only if the new expiration is greater than the current one.
	// Returns true if the timeout was set, false otherwise.
	ExpireGT(ctx context.Context, key string, expiration time.Duration) Result[bool]

	// ExpireLT sets a timeout on a key only if the new expiration is less than the current one.
	// Returns true if the timeout was set, false otherwise.
	ExpireLT(ctx context.Context, key string, expiration time.Duration) Result[bool]

	// ExpireAt sets an expiration timestamp on a key.
	// The key will be automatically deleted at the specified UNIX time in seconds.
	// Returns true if the expiration was set, false if the key does not exist.
	ExpireAt(ctx context.Context, key string, tm time.Time) Result[bool]

	// ExpireTime returns the absolute UNIX timestamp at which the key will expire.
	// Returns -1 if the key exists but has no associated expiration.
	// Returns -2 if the key does not exist.
	ExpireTime(ctx context.Context, key string) Result[time.Duration]

	// PExpire sets a timeout on a key using milliseconds.
	// After the timeout expires, the key will be automatically deleted.
	// Returns true if the timeout was set, false if the key does not exist.
	PExpire(ctx context.Context, key string, expiration time.Duration) Result[bool]

	// PExpireAt sets an expiration timestamp on a key using milliseconds.
	// The key will be automatically deleted at the specified UNIX time in milliseconds.
	// Returns true if the expiration was set, false if the key does not exist.
	PExpireAt(ctx context.Context, key string, tm time.Time) Result[bool]

	// PExpireTime returns the absolute UNIX timestamp in milliseconds at which the key will expire.
	// Returns -1 if the key exists but has no associated expiration.
	// Returns -2 if the key does not exist.
	PExpireTime(ctx context.Context, key string) Result[time.Duration]

	// FlushAll deletes all keys from the current database.
	// This operation is irreversible.
	FlushAll(ctx context.Context) StatusResult

	// Persist removes the expiration timeout from a key, making it persistent.
	// Returns true if the timeout was removed, false if the key does not exist or has no expiration.
	Persist(ctx context.Context, key string) Result[bool]

	// Keys returns all keys matching a pattern.
	// Pattern syntax: * matches any number of characters, ? matches a single character, [] matches character ranges.
	// Use with caution on large databases as this is a O(N) operation.
	Keys(ctx context.Context, pattern string) Result[[]string]

	// Rename renames a key to a new key.
	// If the new key already exists, it will be overwritten.
	// Returns an error if the source key does not exist.
	Rename(ctx context.Context, key string, newKey string) StatusResult

	// RenameNX renames a key to a new key only if the new key does not exist.
	// Returns true if the key was renamed, false if the new key already exists or the source key does not exist.
	RenameNX(ctx context.Context, key string, newKey string) Result[bool]

	// TTL returns the remaining time to live of a key in seconds.
	// Returns -1 if the key exists but has no associated expiration.
	// Returns -2 if the key does not exist.
	TTL(ctx context.Context, key string) Result[time.Duration]

	// PTTL returns the remaining time to live of a key in milliseconds.
	// Returns -1 if the key exists but has no associated expiration.
	// Returns -2 if the key does not exist.
	PTTL(ctx context.Context, key string) Result[time.Duration]

	// Type returns the string representation of the type of the value stored at key.
	// Returns "none" if the key does not exist.
	Type(ctx context.Context, key string) Result[string]

	// RandomKey returns a random key from the current database.
	// Returns an empty string if the database is empty.
	RandomKey(ctx context.Context) Result[string]

	// Scan iterates over keys in the database.
	// cursor is the cursor to start iteration from (0 to start).
	// match is a glob-style pattern to filter keys (empty string for no filter).
	// count is a hint for how many keys to return per iteration.
	// Returns the next cursor and a slice of keys.
	Scan(ctx context.Context, cursor uint64, match string, count int64) Result[KeyScanResult]
}

KeyCommand defines operations for key management and lifecycle in the cache. This includes key creation, deletion, expiration, scanning, and metadata operations.

type KeyScanResult ¶ 

type KeyScanResult struct {
	// Cursor is the cursor to use in the next scan call.
	// A cursor value of 0 indicates the iteration is complete.
	Cursor uint64
	// Keys contains the scanned keys.
	Keys []string
}

KeyScanResult represents the result of a key scan operation.

type LInsertPosition ¶ 

type LInsertPosition string

LInsertPosition represents the position for list insert operation. 

const (
	// LInsertBefore inserts an element before the pivot.
	LInsertBefore LInsertPosition = "BEFORE"
	// LInsertAfter inserts an element after the pivot.
	LInsertAfter LInsertPosition = "AFTER"
)

type ListCommand ¶ 

type ListCommand interface {
	// LIndex returns the element at index in the list stored at key.
	// The index is zero-based, so 0 means the first element, 1 the second element and so on.
	// Negative indices can be used to designate elements starting at the tail of the list.
	LIndex(ctx context.Context, key string, index int64) Result[[]byte]

	// LInsert inserts element in the list stored at key either before or after the reference value pivot.
	// Returns the length of the list after the insert operation, or -1 when the value pivot was not found.
	LInsert(ctx context.Context, key string, position LInsertPosition, pivot, element any) Result[int64]

	// LLen returns the length of the list stored at key.
	// If key does not exist, it is interpreted as an empty list and 0 is returned.
	LLen(ctx context.Context, key string) Result[int64]

	// LPop removes and returns the first element of the list stored at key.
	LPop(ctx context.Context, key string) Result[[]byte]

	// LPopCount removes and returns the first count elements of the list stored at key.
	LPopCount(ctx context.Context, key string, count int) Result[[][]byte]

	// LPush inserts all the specified values at the head of the list stored at key.
	// If key does not exist, it is created as empty list before performing the push operations.
	// Returns the length of the list after the push operations.
	LPush(ctx context.Context, key string, elements ...any) Result[int64]

	// LRange returns the specified elements of the list stored at key.
	// The offsets start and stop are zero-based indexes.
	// These offsets can be negative numbers indicating offsets starting at the end of the list.
	LRange(ctx context.Context, key string, start, stop int64) Result[[][]byte]

	// LRem removes the first count occurrences of elements equal to element from the list stored at key.
	// The count argument influences the operation in the following ways:
	// count > 0: Remove elements equal to element moving from head to tail.
	// count < 0: Remove elements equal to element moving from tail to head.
	// count = 0: Remove all elements equal to element.
	// Returns the number of removed elements.
	LRem(ctx context.Context, key string, count int64, element any) Result[int64]

	// LSet sets the list element at index to element.
	LSet(ctx context.Context, key string, index int64, element any) StatusResult

	// LTrim trims an existing list so that it will contain only the specified range of elements.
	// Both start and stop are zero-based indexes.
	LTrim(ctx context.Context, key string, start, stop int64) StatusResult

	// RPop removes and returns the last element of the list stored at key.
	RPop(ctx context.Context, key string) Result[[]byte]

	// RPopCount removes and returns the last count elements of the list stored at key.
	RPopCount(ctx context.Context, key string, count int) Result[[][]byte]

	// RPopLPush atomically returns and removes the last element (tail) of the list stored at source,
	// and pushes the element at the first element (head) of the list stored at destination.
	RPopLPush(ctx context.Context, source, destination string) Result[[]byte]

	// RPush inserts all the specified values at the tail of the list stored at key.
	// If key does not exist, it is created as empty list before performing the push operations.
	// Returns the length of the list after the push operations.
	RPush(ctx context.Context, key string, elements ...any) Result[int64]
}

ListCommand defines operations for Redis list data structure. Lists are sequences of strings sorted by insertion order.

type Result ¶ 

type Result[T any] interface {
	// SetErr sets the error on the result.
	// This is typically used by providers during error handling.
	SetErr(e error)

	// Err returns the error associated with the result.
	// Returns nil if the operation was successful.
	Err() error

	// SetVal sets the value on the result.
	// This is typically used by providers during successful operations.
	SetVal(v T)

	// Val returns the value stored in the result.
	// If an error is present, this may return the zero value for T.
	Val() T

	// Result returns both the value and error.
	// This is the most convenient way to handle the result in a single call.
	Result() (T, error)
}

Result provides a generic container for operation results with error handling. This interface allows providers to return values along with potential errors in a consistent way. The generic type T represents the type of the value returned by the operation.

type ScanResult ¶ 

type ScanResult struct {
	// Cursor is the cursor to use in the next scan call.
	// A cursor value of 0 indicates the iteration is complete.
	Cursor uint64
	// Elements contains the scanned elements.
	Elements [][]byte
}

ScanResult represents the result of a scan operation.

type SetArgs ¶ 

type SetArgs struct {
	// Mode can be `NX` or `XX` or empty.
	Mode string

	// Zero `TTL` or `Expiration` means that the key has no expiration time.
	TTL      time.Duration
	ExpireAt time.Time

	// When Get is true, the command returns the old value stored at key, or nil when key did not exist.
	Get bool

	// KeepTTL is a Redis KEEPTTL option to keep existing TTL, it requires your redis-server version >= 6.0,
	// otherwise you will receive an error: (error) ERR syntax error.
	KeepTTL bool
}

SetArgs provides arguments for the SetArgs function.

type SetCommand ¶ 

type SetCommand interface {
	// SAdd adds one or more members to a set.
	// Creates the set if it does not exist.
	// Returns the number of members that were added to the set,
	// not including members already present.
	SAdd(ctx context.Context, key string, members ...any) Result[int64]

	// SCard returns the number of members in a set.
	// Returns 0 if the key does not exist.
	SCard(ctx context.Context, key string) Result[int64]

	// SDiff returns the difference of multiple sets.
	// The difference is the members of the first set that do not exist in any of the other sets.
	SDiff(ctx context.Context, keys ...string) Result[[][]byte]

	// SDiffStore stores the difference of multiple sets in a destination set.
	// If the destination set already exists, it is overwritten.
	// Returns the number of members in the resulting set.
	SDiffStore(ctx context.Context, destination string, keys ...string) Result[int64]

	// SInter returns the intersection of multiple sets.
	// The intersection is the members that exist in all given sets.
	SInter(ctx context.Context, keys ...string) Result[[][]byte]

	// SInterStore stores the intersection of multiple sets in a destination set.
	// If the destination set already exists, it is overwritten.
	// Returns the number of members in the resulting set.
	SInterStore(ctx context.Context, destination string, keys ...string) Result[int64]

	// SIsMember determines whether a member belongs to a set.
	// Returns true if the member is a member of the set, false otherwise.
	SIsMember(ctx context.Context, key string, member any) Result[bool]

	// SMembers returns all members of a set.
	// Returns an empty slice if the set does not exist.
	SMembers(ctx context.Context, key string) Result[[][]byte]

	// SMove moves a member from one set to another.
	// If the source set does not exist or does not contain the member, no operation is performed.
	// Returns true if the member was moved, false otherwise.
	SMove(ctx context.Context, source, destination string, member any) Result[bool]

	// SPop removes and returns a random member from a set.
	// Returns nil if the set does not exist or is empty.
	SPop(ctx context.Context, key string) Result[[]byte]

	// SPopN removes and returns up to count random members from a set.
	// Returns an empty slice if the set does not exist or is empty.
	SPopN(ctx context.Context, key string, count int64) Result[[][]byte]

	// SRandMember returns a random member from a set without removing it.
	// Returns nil if the set does not exist or is empty.
	SRandMember(ctx context.Context, key string) Result[[]byte]

	// SRandMemberN returns count random members from a set without removing them.
	// If count is positive, returns an array with distinct members.
	// If count is negative, returns an array with possibly repeated members.
	// Returns an empty slice if the set does not exist or is empty.
	SRandMemberN(ctx context.Context, key string, count int64) Result[[][]byte]

	// SRem removes one or more members from a set.
	// Members that are not members of the set are ignored.
	// Returns the number of members that were removed from the set,
	// not including non-existing members.
	SRem(ctx context.Context, key string, members ...any) Result[int64]

	// SScan iterates over members of a set.
	// cursor is the cursor to start iteration from (0 to start).
	// match is a glob-style pattern to filter members (empty string for no filter).
	// count is a hint for how many members to return per iteration.
	// Returns the next cursor and a slice of members.
	SScan(ctx context.Context, key string, cursor uint64, match string, count int64) Result[ScanResult]

	// SUnion returns the union of multiple sets.
	// The union is all members that exist in at least one of the given sets.
	SUnion(ctx context.Context, keys ...string) Result[[][]byte]

	// SUnionStore stores the union of multiple sets in a destination set.
	// If the destination set already exists, it is overwritten.
	// Returns the number of members in the resulting set.
	SUnionStore(ctx context.Context, destination string, keys ...string) Result[int64]
}

SetCommand defines operations for Redis set data structure. Sets are unordered collections of unique strings.

type SortedSetCommand ¶ 

type SortedSetCommand interface {
	// ZAdd adds one or more members with scores to a sorted set.
	// If a member already exists, its score is updated.
	// Returns the number of members added (not including members whose score was updated).
	ZAdd(ctx context.Context, key string, members ...ZMember) Result[int64]

	// ZAddArgs adds members with additional options.
	// mode can be "NX" (only add new members), "XX" (only update existing members),
	// "GT" (only update if new score is greater), "LT" (only update if new score is less).
	// ch returns the number of members changed (added or updated) instead of just added.
	ZAddArgs(ctx context.Context, key string, mode string, ch bool, members ...ZMember) Result[int64]

	// ZCard returns the number of members in a sorted set.
	// Returns 0 if the key does not exist.
	ZCard(ctx context.Context, key string) Result[int64]

	// ZCount returns the number of members in a sorted set within a range of scores.
	// min and max can be inclusive or exclusive (use "(" prefix for exclusive).
	ZCount(ctx context.Context, key string, min, max string) Result[int64]

	// ZIncrBy increments the score of a member in a sorted set by increment.
	// If the member does not exist, it is added with increment as its score.
	// Returns the new score of the member.
	ZIncrBy(ctx context.Context, key string, increment float64, member string) Result[float64]

	// ZInter returns the intersection of multiple sorted sets.
	// The intersection contains members that exist in all given sets.
	ZInter(ctx context.Context, store ZStore) Result[[][]byte]

	// ZInterWithScores returns the intersection with scores.
	ZInterWithScores(ctx context.Context, store ZStore) Result[[]ZMember]

	// ZInterStore stores the intersection of multiple sorted sets in a destination key.
	// Returns the number of members in the resulting sorted set.
	ZInterStore(ctx context.Context, destination string, store ZStore) Result[int64]

	// ZRange returns members in a sorted set within a range of indexes.
	// start and stop are zero-based indexes (can be negative to indicate offsets from the end).
	// Returns members in ascending order by score.
	ZRange(ctx context.Context, key string, start, stop int64) Result[[][]byte]

	// ZRangeWithScores returns members with their scores.
	ZRangeWithScores(ctx context.Context, key string, start, stop int64) Result[[]ZMember]

	// ZRangeArgs returns members based on custom range arguments.
	ZRangeArgs(ctx context.Context, key string, args ZRangeArgs) Result[[][]byte]

	// ZRangeArgsWithScores returns members with scores based on custom range arguments.
	ZRangeArgsWithScores(ctx context.Context, key string, args ZRangeArgs) Result[[]ZMember]

	// ZRangeByScore returns members in a sorted set within a range of scores.
	// min and max can be inclusive or exclusive (use "(" prefix for exclusive).
	ZRangeByScore(ctx context.Context, key string, min, max string) Result[[][]byte]

	// ZRangeByScoreWithScores returns members with scores within a range of scores.
	ZRangeByScoreWithScores(ctx context.Context, key string, min, max string) Result[[]ZMember]

	// ZRank returns the rank (index) of a member in a sorted set ordered by ascending scores.
	// Ranks start at 0 for the member with the lowest score.
	// Returns -1 if the member does not exist.
	ZRank(ctx context.Context, key string, member string) Result[int64]

	// ZRankWithScore returns the rank and score of a member.
	ZRankWithScore(ctx context.Context, key string, member string) Result[ZRankScore]

	// ZRem removes one or more members from a sorted set.
	// Returns the number of members removed.
	ZRem(ctx context.Context, key string, members ...any) Result[int64]

	// ZRemRangeByRank removes members in a sorted set within a range of indexes.
	// start and stop are zero-based indexes (can be negative).
	// Returns the number of members removed.
	ZRemRangeByRank(ctx context.Context, key string, start, stop int64) Result[int64]

	// ZRemRangeByScore removes members in a sorted set within a range of scores.
	// min and max can be inclusive or exclusive (use "(" prefix for exclusive).
	// Returns the number of members removed.
	ZRemRangeByScore(ctx context.Context, key string, min, max string) Result[int64]

	// ZRevRange returns members in a sorted set within a range of indexes in reverse order.
	// Members are ordered by descending scores.
	ZRevRange(ctx context.Context, key string, start, stop int64) Result[[][]byte]

	// ZRevRangeWithScores returns members with scores in reverse order.
	ZRevRangeWithScores(ctx context.Context, key string, start, stop int64) Result[[]ZMember]

	// ZRevRangeByScore returns members in a sorted set within a range of scores in reverse order.
	ZRevRangeByScore(ctx context.Context, key string, max, min string) Result[[][]byte]

	// ZRevRangeByScoreWithScores returns members with scores within a range of scores in reverse order.
	ZRevRangeByScoreWithScores(ctx context.Context, key string, max, min string) Result[[]ZMember]

	// ZRevRank returns the rank (index) of a member in a sorted set ordered by descending scores.
	// Ranks start at 0 for the member with the highest score.
	// Returns -1 if the member does not exist.
	ZRevRank(ctx context.Context, key string, member string) Result[int64]

	// ZRevRankWithScore returns the rank and score of a member in reverse order.
	ZRevRankWithScore(ctx context.Context, key string, member string) Result[ZRankScore]

	// ZScan iterates over members and scores of a sorted set.
	// cursor is the cursor to start iteration from (0 to start).
	// match is a glob-style pattern to filter members (empty string for no filter).
	// count is a hint for how many members to return per iteration.
	// Returns the next cursor and a slice of members with scores.
	ZScan(ctx context.Context, key string, cursor uint64, match string, count int64) Result[ZScanResult]

	// ZScore returns the score of a member in a sorted set.
	// Returns an error if the member does not exist.
	ZScore(ctx context.Context, key string, member string) Result[float64]

	// ZUnion returns the union of multiple sorted sets.
	// The union contains all members that exist in at least one of the given sets.
	ZUnion(ctx context.Context, store ZStore) Result[[][]byte]

	// ZUnionWithScores returns the union with scores.
	ZUnionWithScores(ctx context.Context, store ZStore) Result[[]ZMember]

	// ZUnionStore stores the union of multiple sorted sets in a destination key.
	// Returns the number of members in the resulting sorted set.
	ZUnionStore(ctx context.Context, destination string, store ZStore) Result[int64]
}

SortedSetCommand defines operations for Redis sorted set data structure. Sorted sets (zsets) are collections of unique strings ordered by each string's associated score.

type StatusResult ¶ 

type StatusResult interface {
	Result[string]

	// Bytes returns the status value as a byte slice along with any error.
	// This is useful when you need the raw byte representation of the status.
	Bytes() ([]byte, error)
}

StatusResult specializes Result[string] for operations that return status messages. This interface is used for operations where the result is typically a status string (like "OK") but also provides access to the underlying byte representation.

func NewStatusResult ¶ 

func NewStatusResult(val []byte, err error) StatusResult

NewStatusResult creates a new statusResult with the given byte slice value and error. This is intended to be used by providers with their own error handling.

type StringCommand ¶ 

type StringCommand interface {
	// Decr decrements the integer value of a key by one.
	// If the key does not exist, it is set to 0 before performing the operation.
	// Returns an error if the key contains a value that cannot be interpreted as an integer.
	Decr(ctx context.Context, key string) Result[int64]

	// DecrBy decrements the integer value of a key by the specified amount.
	// If the key does not exist, it is set to 0 before performing the operation.
	// Returns an error if the key contains a value that cannot be interpreted as an integer.
	DecrBy(ctx context.Context, key string, value int64) Result[int64]

	// Get retrieves the value of a key.
	// Returns nil if the key does not exist.
	Get(ctx context.Context, key string) Result[[]byte]

	// Incr increments the integer value of a key by one.
	// If the key does not exist, it is set to 0 before performing the operation.
	// Returns an error if the key contains a value that cannot be interpreted as an integer.
	Incr(ctx context.Context, key string) Result[int64]

	// IncrBy increments the integer value of a key by the specified amount.
	// If the key does not exist, it is set to 0 before performing the operation.
	// Returns an error if the key contains a value that cannot be interpreted as an integer.
	IncrBy(ctx context.Context, key string, value int64) Result[int64]

	// IncrByFloat increments the float value of a key by the specified amount.
	// If the key does not exist, it is set to 0 before performing the operation.
	// Returns an error if the key contains a value that cannot be interpreted as a float.
	IncrByFloat(ctx context.Context, key string, value float64) Result[float64]

	// Set sets the value of a key with an optional expiration time.
	// expiration of 0 means the key has no expiration time.
	// Overwrites any existing value and clears any existing TTL.
	Set(ctx context.Context, key string, value any, expiration time.Duration) StatusResult

	// SetArgs sets the value of a key with advanced options specified in SetArgs.
	// Provides fine-grained control over set operations including mode (NX/XX), TTL, and Get options.
	SetArgs(ctx context.Context, key string, value any, args SetArgs) StatusResult

	// SetNX sets the value of a key only if the key does not exist.
	// Returns true if the key was set, false if the key already exists.
	// expiration of 0 means the key has no expiration time.
	SetNX(ctx context.Context, key string, value any, expiration time.Duration) Result[bool]

	// SetXX sets the value of a key only if the key already exists.
	// Returns true if the key was set, false if the key does not exist.
	// expiration of 0 means the key has no expiration time.
	SetXX(ctx context.Context, key string, value any, expiration time.Duration) Result[bool]

	// StrLen returns the length of the string value stored at a key.
	// Returns 0 if the key does not exist.
	StrLen(ctx context.Context, key string) Result[int64]

	// MGet retrieves the values of multiple keys.
	// For each key that does not exist, the corresponding value in the result map will be nil.
	// Returns a map where keys are the requested keys and values are their corresponding values.
	MGet(ctx context.Context, keys ...string) Result[map[string][]byte]

	// MSet sets the values of multiple keys to their corresponding values.
	// This operation is atomic: either all keys are set or none are.
	// Overwrites any existing values and clears any existing TTLs.
	MSet(ctx context.Context, values map[string]any) StatusResult

	// MSetNX sets the values of multiple keys to their corresponding values only if none of the keys exist.
	// This operation is atomic: either all keys are set or none are.
	// Returns true if all keys were set, false if any key already exists.
	MSetNX(ctx context.Context, values map[string]any) Result[bool]
}

StringCommand defines operations for string values in the cache. Strings are the most basic Redis data type and can contain text, JSON, serialized objects, or binary data. All string operations are atomic.

type ZMember ¶ 

type ZMember struct {
	// Member is the member value.
	Member []byte
	// Score is the score associated with the member.
	Score float64
}

ZMember represents a member with its score in a sorted set.

type ZRangeArgs ¶ 

type ZRangeArgs struct {
	// Start is the starting point of the range (can be index, score, or lex).
	Start any
	// Stop is the ending point of the range (can be index, score, or lex).
	Stop any
	// ByScore determines whether the range is by score or by rank (index).
	ByScore bool
	// ByLex determines whether the range is by lexicographical order.
	ByLex bool
	// Rev determines whether to return members in reverse order.
	Rev bool
	// Offset is the number of elements to skip (used with Limit).
	Offset int64
	// Count is the maximum number of elements to return (used with Limit, -1 for no limit).
	Count int64
}

ZRangeArgs provides arguments for range operations on sorted sets.

type ZRankScore ¶ 

type ZRankScore struct {
	// Rank is the rank (index) of the member.
	Rank int64
	// Score is the score of the member.
	Score float64
}

ZRankScore represents the rank and score of a member.

type ZScanResult ¶ 

type ZScanResult struct {
	// Cursor is the cursor to use in the next scan call.
	// A cursor value of 0 indicates the iteration is complete.
	Cursor uint64
	// Members contains the scanned members with their scores.
	Members []ZMember
}

ZScanResult represents the result of a zscan operation.

type ZStore ¶ 

type ZStore struct {
	// Keys are the keys of the sorted sets to operate on.
	Keys []string
	// Weights are the multiplication factors for scores from each sorted set.
	// If not specified, defaults to 1 for each set.
	Weights []float64
	// Aggregate specifies how to aggregate scores: "SUM", "MIN", or "MAX".
	// Defaults to "SUM".
	Aggregate string
}

ZStore specifies aggregation method for set operations.

Source Files ¶

View all Source files

Directories ¶

Path Synopsis
internal
error
providers
redis module
redka module

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.