rstring

Documentation

Overview

Package rstring is a database-backed string repository. It provides methods to interact with strings in the database.

Index

• type DB
  • func New(s *store.Store) *DB
  • func (d *DB) Append(key string, value []byte) (int, error)
  • func (d *DB) Get(key string) (core.Value, error)
  • func (d *DB) GetMany(keys ...string) (map[string]core.Value, error)
  • func (d *DB) GetRange(key string, start, end int) (core.Value, error)
  • func (d *DB) Incr(key string, delta int) (int, error)
  • func (d *DB) IncrFloat(key string, delta float64) (float64, error)
  • func (d *DB) Set(key string, value any) error
  • func (d *DB) SetExpire(key string, value any, ttl time.Duration) error
  • func (d *DB) SetGet(key string, value any) (core.Value, error)
  • func (d *DB) SetKeepTTL(key string, value any) (bool, error)
  • func (d *DB) SetMany(items map[string]any) error
  • func (d *DB) SetNX(key string, value any) (bool, error)
  • func (d *DB) SetNXGet(key string, value any, ttl time.Duration) (core.Value, bool, error)
  • func (d *DB) SetNXWithTTL(key string, value any, ttl time.Duration) (bool, error)
  • func (d *DB) SetRange(key string, offset int, value []byte) (int, error)
  • func (d *DB) SetWith(key string, value any) SetCmd
  • func (d *DB) SetXX(key string, value any) (bool, error)
  • func (d *DB) SetXXGet(key string, value any, ttl time.Duration) (core.Value, bool, error)
  • func (d *DB) SetXXWithTTL(key string, value any, ttl time.Duration) (bool, error)
  • func (d *DB) StrLen(key string) (int, error)
  • func (d *DB) WithDB(dbIdx int) *DB
• type SetCmd
  • func (cmd SetCmd) At(t time.Time) SetCmd
  • func (cmd SetCmd) Exec() error
  • func (cmd SetCmd) Get() SetCmd
  • func (cmd SetCmd) IfExists() SetCmd
  • func (cmd SetCmd) IfNotExists() SetCmd
  • func (cmd SetCmd) KeepTTL() SetCmd
  • func (cmd SetCmd) Run() (SetResult, error)
  • func (cmd SetCmd) TTL(ttl time.Duration) SetCmd
• type SetOption
• type SetResult

Types

type DB

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

DB is a database-backed string repository. A string is a slice of bytes associated with a key. Use the string repository to work with individual strings.

This is a simplified architecture that directly uses store.Store without additional transaction wrappers. Each method handles its own transactions internally when needed.

func New

func New(s *store.Store) *DB

New connects to the string repository. Does not create the database schema.

func (*DB) Append

func (d *DB) Append(key string, value []byte) (int, error)

Append appends the value to the existing string value. Returns the length of the string after appending. This method uses transaction with row-level locking to prevent race conditions.

func (*DB) Get

func (d *DB) Get(key string) (core.Value, error)

Get returns the value of the key. If the key does not exist or is not a string, returns ErrNotFound.

func (*DB) GetMany

func (d *DB) GetMany(keys ...string) (map[string]core.Value, error)

GetMany returns a map of values for given keys. Ignores keys that do not exist or not strings, and does not return them in the map.

func (*DB) GetRange

func (d *DB) GetRange(key string, start, end int) (core.Value, error)

GetRange returns a substring of the string value. Start and end are zero-based offsets. If the key does not exist or is not a string, returns ErrNotFound.

func (*DB) Incr

func (d *DB) Incr(key string, delta int) (int, error)

Incr increments the integer key value by the specified amount. Returns the value after the increment. If the key does not exist, sets it to 0 before the increment. If the key value is not an integer, returns ErrValueType. If the key exists but is not a string, returns ErrKeyType.

Uses SELECT FOR UPDATE to prevent race conditions in concurrent access.

func (*DB) IncrFloat

func (d *DB) IncrFloat(key string, delta float64) (float64, error)

IncrFloat increments the float key value by the specified amount. Returns the value after the increment. If the key does not exist, sets it to 0 before the increment. If the key value is not an float, returns ErrValueType. If the key exists but is not a string, returns ErrKeyType.

func (*DB) Set

func (d *DB) Set(key string, value any) error

Set sets the key value that will not expire. Overwrites the value if the key already exists. If the key exists but is not a string, returns ErrKeyType.

func (*DB) SetExpire

func (d *DB) SetExpire(key string, value any, ttl time.Duration) error

SetExpire sets the key value with an optional expiration time (if ttl > 0). Overwrites the value and ttl if the key already exists. If the key exists but is not a string, returns ErrKeyType.

func (*DB) SetGet

func (d *DB) SetGet(key string, value any) (core.Value, error)

SetGet sets the key to hold string value and returns the previous value. Returns the previous value if the key existed, nil if the key did not exist. This is the Redis SET with GET option implementation (added in Redis 6.2). Time complexity: O(1)

func (*DB) SetKeepTTL

func (d *DB) SetKeepTTL(key string, value any) (bool, error)

SetKeepTTL sets the key to hold string value while keeping the existing TTL. Returns true if the key was updated, false if the key did not exist. This is the Redis SET with KEEPTTL option implementation (added in Redis 6.0). Time complexity: O(1)

func (*DB) SetMany

func (d *DB) SetMany(items map[string]any) error

SetMany sets the values of multiple keys. Overwrites values for keys that already exist and creates new keys/values for keys that do not exist. Removes the TTL for existing keys. If any of the keys exists but is not a string, returns ErrKeyType.

func (*DB) SetNX

func (d *DB) SetNX(key string, value any) (bool, error)

SetNX sets the key to hold string value if key does not exist. Returns true if the key was set, false if the key already exists. This is the Redis SETNX command implementation. Time complexity: O(1)

SetNX is short for "SET if Not eXists".

Design pattern: This can be used as a locking primitive. For example, to acquire a lock:

• Use SetNX to set the lock key with a unique value
• If SetNX returns true, the lock is acquired
• To release the lock, use Del (after verifying ownership)

Note: Starting from Redis 2.6.12, SET with NX argument is preferred over SETNX. This method provides direct SETNX semantics.

func (*DB) SetNXGet

func (d *DB) SetNXGet(key string, value any, ttl time.Duration) (core.Value, bool, error)

SetNXGet sets the key to hold string value if key does not exist. Returns the previous value and whether the key was created. This implements SET key value NX GET semantics.

func (*DB) SetNXWithTTL

func (d *DB) SetNXWithTTL(key string, value any, ttl time.Duration) (bool, error)

SetNXWithTTL sets the key to hold string value if key does not exist. If ttl > 0, sets the expiration time as well. Returns true if the key was set, false if the key already exists. This implements SET key value NX EX seconds / PX milliseconds.

func (*DB) SetRange

func (d *DB) SetRange(key string, offset int, value []byte) (int, error)

SetRange overwrites the part of the string starting at offset with the value. Returns the length of the string after modification. This method uses transaction with row-level locking to prevent race conditions.

func (*DB) SetWith

func (d *DB) SetWith(key string, value any) SetCmd

SetWith provides a builder pattern for setting values with additional options. Example: db.SetWith("key", "value").Expire(time.Hour).Exec()

func (*DB) SetXX

func (d *DB) SetXX(key string, value any) (bool, error)

SetXX sets the key to hold string value if key already exists. Returns true if the key was updated, false if the key does not exist. This is the Redis SET with XX option implementation. Time complexity: O(1)

func (*DB) SetXXGet

func (d *DB) SetXXGet(key string, value any, ttl time.Duration) (core.Value, bool, error)

SetXXGet sets the key to hold string value if key already exists. Returns the previous value and whether the key was updated. This implements SET key value XX GET semantics.

func (*DB) SetXXWithTTL

func (d *DB) SetXXWithTTL(key string, value any, ttl time.Duration) (bool, error)

SetXXWithTTL sets the key to hold string value if key already exists. If ttl > 0, sets the expiration time as well. Returns true if the key was updated, false if the key does not exist. This implements SET key value XX EX seconds / PX milliseconds.

func (*DB) StrLen

func (d *DB) StrLen(key string) (int, error)

StrLen returns the length of the string value. If the key does not exist or is not a string, returns ErrNotFound.

func (*DB) WithDB

func (d *DB) WithDB(dbIdx int) *DB

WithDB changes the logical database index in place and returns the same DB. It is safe for concurrent use; each TCP connection has its own DB instance.

type SetCmd

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

SetCmd is a builder for setting values with additional options.

func (SetCmd) At

func (cmd SetCmd) At(t time.Time) SetCmd

At sets the expiration timestamp for the key.

func (SetCmd) Exec

func (cmd SetCmd) Exec() error

Exec executes the set command (legacy compatibility).

func (SetCmd) Get

func (cmd SetCmd) Get() SetCmd

Get returns the previous value after setting.

func (SetCmd) IfExists

func (cmd SetCmd) IfExists() SetCmd

IfExists sets the IF EXISTS option (only update if key exists).

func (SetCmd) IfNotExists

func (cmd SetCmd) IfNotExists() SetCmd

IfNotExists sets the IF NOT EXISTS option (only create if key doesn't exist).

func (SetCmd) KeepTTL

func (cmd SetCmd) KeepTTL() SetCmd

KeepTTL keeps the existing TTL of the key.

func (SetCmd) Run

func (cmd SetCmd) Run() (SetResult, error)

Run executes the set command with the configured options. This implementation delegates to the individual methods for cleaner code.

func (SetCmd) TTL

func (cmd SetCmd) TTL(ttl time.Duration) SetCmd

TTL sets the expiration time for the key.

type SetOption

type SetOption func(*SetCmd)

SetOption represents a functional option for the SetCmd.

type SetResult

type SetResult struct {
	Updated bool
	Created bool
	Prev    core.Value
}

SetResult represents the result of a SET operation.