Class: Familia::StringKey

Inherits:
DataType show all
Includes:
DataType::ScalarBase
Defined in:
lib/familia/data_type/types/stringkey.rb

Direct Known Subclasses

Counter, Lock

Instance Attribute Summary collapse

Attributes included from Settings

#current_key_version, #default_expiration, #delim, #encryption_keys, #encryption_personalization, #logical_database, #prefix, #schema_path, #schema_validator, #schemas, #strict_write_order, #suffix, #transaction_mode

Class Method Summary collapse

Instance Method Summary collapse

Methods included from DataType::ScalarBase

#scalar_type?

Methods included from Features::Autoloader

autoload_files, included, normalize_to_config_name

Methods included from DataType::Serialization

#deserialize_values, #deserialize_values_with_nil

Methods included from DataType::DatabaseCommands

#current_expiration, #delete!, #echo, #exists?, #expire, #expireat, #move, #persist, #rename, #renamenx, #type

Methods included from DataType::Connection

#dbclient, #dbkey, #uri

Methods included from Connection::Behavior

#connect, #create_dbclient, #multi, #normalize_uri, #pipeline, #pipelined, #transaction, #uri=, #url, #url=

Methods included from Settings

#configure, #default_suffix, #pipelined_mode, #pipelined_mode=

Methods included from Base

add_feature, #as_json, #expired?, #expires?, find_feature, #generate_id, #to_json, #ttl, #update_expiration, #uuid

Constructor Details

This class inherits a constructor from Familia::DataType

Instance Attribute Details

#features_enabled ⇒ Object (readonly) Originally defined in module Features

Returns the value of attribute features_enabled.

#logical_database(val = nil) ⇒ Object Originally defined in module DataType::ClassMethods

#parent ⇒ Object Originally defined in module DataType::ClassMethods

Returns the value of attribute parent.

#prefix ⇒ Object Originally defined in module DataType::ClassMethods

Returns the value of attribute prefix.

#suffix ⇒ Object Originally defined in module DataType::ClassMethods

Returns the value of attribute suffix.

#uri(val = nil) ⇒ Object Originally defined in module DataType::ClassMethods

Returns the value of attribute uri.

Class Method Details

.bitop(operation, destkey, *keys, client: nil) ⇒ Integer

Note:

This method is a raw Redis passthrough and does NOT apply Familia's serialization pipeline or expiration hooks. All key arguments are used as-is (no dbkey prefixing). The destination key will not have a TTL applied automatically.

Perform bitwise operations between strings and store result

Examples:

StringKey.bitop(:and, 'result', 'key1', 'key2')

Parameters:

  • operation (String, Symbol) —

    Bitwise operation: AND, OR, XOR, NOT

  • destkey (String) —

    Destination key to store result

  • keys (Array<String>) —

    Source keys for the operation

  • client (Redis, nil) (defaults to: nil) —

    Optional Redis client (uses Familia.dbclient if nil)

Returns:

  • (Integer) —

    Size of the resulting string in bytes



305
306
307
308
 
# File 'lib/familia/data_type/types/stringkey.rb', line 305

def bitop(operation, destkey, *keys, client: nil)
  client ||= Familia.dbclient
  client.bitop(operation.to_s.upcase, destkey, *keys)
end

.mget(*keys, client: nil) ⇒ Array

Note:

This method is a raw Redis passthrough and does NOT apply Familia's serialization pipeline. Keys are used as-is (no dbkey prefixing) and returned values are raw Redis strings. If you need round-trip compatibility with StringKey instances, read via the instance #value getter or a Familia.dbclient.get(instance.dbkey) call.

Get values for multiple keys

Examples:

StringKey.mget('user:1:name', 'user:2:name')

Parameters:

  • keys (Array<String>) —

    Full Redis key names

  • client (Redis, nil) (defaults to: nil) —

    Optional Redis client (uses Familia.dbclient if nil)

Returns:

  • (Array) —

    Values for each key (nil for non-existent keys)



252
253
254
255
 
# File 'lib/familia/data_type/types/stringkey.rb', line 252

def mget(*keys, client: nil)
  client ||= Familia.dbclient
  client.mget(*keys)
end

.mset(hash, client: nil) ⇒ String

Note:

This method is a raw Redis passthrough and does NOT apply Familia's serialization pipeline or expiration hooks. Keys are used as-is (no dbkey prefixing) and values are written as-is. For round-trip compatibility with StringKey instances, write via the instance #value= setter (which calls serialize_value and update_expiration).

Set multiple keys atomically. Keys and values are extracted from the hash for the Redis MSET command.

Examples:

StringKey.mset('user:1:name' => 'Alice', 'user:2:name' => 'Bob')

Parameters:

  • hash (Hash) —

    Key-value pairs to set

  • client (Redis, nil) (defaults to: nil) —

    Optional Redis client (uses Familia.dbclient if nil)

Returns:

  • (String) —

    "OK" on success



270
271
272
273
 
# File 'lib/familia/data_type/types/stringkey.rb', line 270

def mset(hash, client: nil)
  client ||= Familia.dbclient
  client.mset(*hash.flatten)
end

.msetnx(hash, client: nil) ⇒ Boolean

Note:

This method is a raw Redis passthrough and does NOT apply Familia's serialization pipeline or expiration hooks. Keys are used as-is (no dbkey prefixing) and values are written as-is. For round-trip compatibility with StringKey instances, write via the instance #value= setter (which calls serialize_value and update_expiration).

Set multiple keys only if none of them exist. Keys and values are extracted from the hash for the Redis MSETNX command.

Examples:

StringKey.msetnx('user:1:name' => 'Alice', 'user:2:name' => 'Bob')

Parameters:

  • hash (Hash) —

    Key-value pairs to set

  • client (Redis, nil) (defaults to: nil) —

    Optional Redis client (uses Familia.dbclient if nil)

Returns:

  • (Boolean) —

    true if all keys were set, false if none were set



288
289
290
291
 
# File 'lib/familia/data_type/types/stringkey.rb', line 288

def msetnx(hash, client: nil)
  client ||= Familia.dbclient
  client.msetnx(*hash.flatten)
end

Instance Method Details

#append(val) ⇒ Object Also known as: << 



109
110
111
112
113
 
# File 'lib/familia/data_type/types/stringkey.rb', line 109

def append(val)
  ret = dbclient.append dbkey, val
  update_expiration
  ret
end

#bitcount(start_pos = nil, end_pos = nil) ⇒ Integer

Count the number of set bits (population counting)

Parameters:

  • start_pos (Integer, nil) (defaults to: nil) —

    Start byte position (optional)

  • end_pos (Integer, nil) (defaults to: nil) —

    End byte position (optional)

Returns:

  • (Integer) —

    Number of bits set to 1



196
197
198
199
200
201
202
203
204
 
# File 'lib/familia/data_type/types/stringkey.rb', line 196

def bitcount(start_pos = nil, end_pos = nil)
  if start_pos && end_pos
    dbclient.bitcount(dbkey, start_pos, end_pos)
  elsif start_pos
    dbclient.bitcount(dbkey, start_pos)
  else
    dbclient.bitcount(dbkey)
  end
end

#bitfield(*args) ⇒ Array

Perform bitfield operations on this string

Examples:

Get an unsigned 8-bit integer at offset 0

str.bitfield('GET', 'u8', 0)

Set and increment

str.bitfield('SET', 'u8', 0, 100, 'INCRBY', 'i5', 100, 1)

Parameters:

  • args (Array) —

    Bitfield subcommands and arguments

Returns:

  • (Array) —

    Results of the bitfield operations



228
229
230
231
232
 
# File 'lib/familia/data_type/types/stringkey.rb', line 228

def bitfield(*args)
  ret = dbclient.bitfield(dbkey, *args)
  update_expiration
  ret
end

#bitpos(bit, start_pos = nil, end_pos = nil) ⇒ Integer

Find the position of the first bit set to 0 or 1

Parameters:

  • bit (Integer) —

    The bit value to search for (0 or 1)

  • start_pos (Integer, nil) (defaults to: nil) —

    Start byte position (optional)

  • end_pos (Integer, nil) (defaults to: nil) —

    End byte position (optional)

Returns:

  • (Integer) —

    Position of the first bit, or -1 if not found



211
212
213
214
215
216
217
218
219
 
# File 'lib/familia/data_type/types/stringkey.rb', line 211

def bitpos(bit, start_pos = nil, end_pos = nil)
  if start_pos && end_pos
    dbclient.bitpos(dbkey, bit, start_pos, end_pos)
  elsif start_pos
    dbclient.bitpos(dbkey, bit, start_pos)
  else
    dbclient.bitpos(dbkey, bit)
  end
end

#char_count ⇒ Integer Also known as: size, length

Returns the number of elements in the list

Returns:

  • (Integer) —

    number of elements



35
36
37
 
# File 'lib/familia/data_type/types/stringkey.rb', line 35

def char_count
  to_s.size
end

#decrement ⇒ Object Also known as: decr 



95
96
97
98
99
 
# File 'lib/familia/data_type/types/stringkey.rb', line 95

def decrement
  ret = dbclient.decr dbkey
  update_expiration
  ret
end

#decrementby(val) ⇒ Object Also known as: decrby 



102
103
104
105
106
 
# File 'lib/familia/data_type/types/stringkey.rb', line 102

def decrementby(val)
  ret = dbclient.decrby dbkey, val.to_i
  update_expiration
  ret
end

#del ⇒ Object 



234
235
236
237
 
# File 'lib/familia/data_type/types/stringkey.rb', line 234

def del
  ret = dbclient.del dbkey
  Familia.positive?(ret)
end

#deserialize_value(val) ⇒ Object

StringKey returns raw values (not JSON parsed)



27
28
29
30
31
 
# File 'lib/familia/data_type/types/stringkey.rb', line 27

def deserialize_value(val)
  return val if val.is_a?(Redis::Future)
  return @opts[:default] if val.nil?
  val
end

#empty? ⇒ Boolean

Returns:

  • (Boolean) 


41
42
43
 
# File 'lib/familia/data_type/types/stringkey.rb', line 41

def empty?
  char_count.zero?
end

#getbit(offset) ⇒ Object 



116
117
118
 
# File 'lib/familia/data_type/types/stringkey.rb', line 116

def getbit(offset)
  dbclient.getbit dbkey, offset
end

#getdel ⇒ String?

Atomically get and delete the value

Returns:

  • (String, nil) —

    The value before deletion, or nil if key didn't exist



144
145
146
 
# File 'lib/familia/data_type/types/stringkey.rb', line 144

def getdel
  dbclient.getdel(dbkey)
end

#getex(ex: nil, px: nil, exat: nil, pxat: nil, persist: false) ⇒ String?

Get value and optionally set expiration atomically

Parameters:

  • ex (Integer, nil) (defaults to: nil) —

    Set expiration in seconds

  • px (Integer, nil) (defaults to: nil) —

    Set expiration in milliseconds

  • exat (Integer, nil) (defaults to: nil) —

    Set expiration at Unix timestamp (seconds)

  • pxat (Integer, nil) (defaults to: nil) —

    Set expiration at Unix timestamp (milliseconds)

  • persist (Boolean) (defaults to: false) —

    Remove existing expiration

Returns:

  • (String, nil) —

    The value



155
156
157
158
159
160
161
162
163
164
 
# File 'lib/familia/data_type/types/stringkey.rb', line 155

def getex(ex: nil, px: nil, exat: nil, pxat: nil, persist: false)
  options = {}
  options[:ex] = ex if ex
  options[:px] = px if px
  options[:exat] = exat if exat
  options[:pxat] = pxat if pxat
  options[:persist] = persist if persist

  dbclient.getex(dbkey, **options)
end

#getrange(spoint, epoint) ⇒ Object 



126
127
128
 
# File 'lib/familia/data_type/types/stringkey.rb', line 126

def getrange(spoint, epoint)
  dbclient.getrange dbkey, spoint, epoint
end

#getset(val) ⇒ Object 



136
137
138
139
140
 
# File 'lib/familia/data_type/types/stringkey.rb', line 136

def getset(val)
  ret = dbclient.getset dbkey, val
  update_expiration
  ret
end

#incrbyfloat(val) ⇒ Float Also known as: incrfloat

Increment value by a float amount

Parameters:

  • val (Float, Numeric) —

    The amount to increment by

Returns:

  • (Float) —

    The new value after increment



169
170
171
172
173
 
# File 'lib/familia/data_type/types/stringkey.rb', line 169

def incrbyfloat(val)
  ret = dbclient.incrbyfloat(dbkey, val.to_f)
  update_expiration
  ret
end

#increment ⇒ Object Also known as: incr 



81
82
83
84
85
 
# File 'lib/familia/data_type/types/stringkey.rb', line 81

def increment
  ret = dbclient.incr(dbkey)
  update_expiration
  ret
end

#incrementby(val) ⇒ Object Also known as: incrby 



88
89
90
91
92
 
# File 'lib/familia/data_type/types/stringkey.rb', line 88

def incrementby(val)
  ret = dbclient.incrby(dbkey, val.to_i)
  update_expiration
  ret
end

#init ⇒ Object 



9
 
# File 'lib/familia/data_type/types/stringkey.rb', line 9

def init; end

#psetex(milliseconds, val) ⇒ String

Set value with expiration in milliseconds

Parameters:

  • milliseconds (Integer) —

    Expiration time in milliseconds

  • val (Object) —

    The value to set

Returns:

  • (String) —

    "OK" on success



188
189
190
 
# File 'lib/familia/data_type/types/stringkey.rb', line 188

def psetex(milliseconds, val)
  dbclient.psetex(dbkey, milliseconds.to_i, serialize_value(val))
end

#serialize_value(val) ⇒ Object

StringKey uses raw string serialization (not JSON) because Redis string operations like INCR, DECR, APPEND operate on raw values. This overrides the base JSON serialization from DataType.



14
15
16
17
18
19
20
21
22
23
24
 
# File 'lib/familia/data_type/types/stringkey.rb', line 14

def serialize_value(val)
  Familia.trace :TOREDIS, nil, "#{val}<#{val.class}>" if Familia.debug?

  # Handle Familia object references - extract identifier
  if val.is_a?(Familia::Base) || (val.is_a?(Class) && val.ancestors.include?(Familia::Base))
    return val.is_a?(Class) ? val.name : val.identifier
  end

  # StringKey uses raw string conversion for Redis compatibility
  val.to_s
end

#setbit(offset, val) ⇒ Object 



120
121
122
123
124
 
# File 'lib/familia/data_type/types/stringkey.rb', line 120

def setbit(offset, val)
  ret = dbclient.setbit dbkey, offset, val
  update_expiration
  ret
end

#setex(seconds, val) ⇒ String

Set value with expiration in seconds

Parameters:

  • seconds (Integer) —

    Expiration time in seconds

  • val (Object) —

    The value to set

Returns:

  • (String) —

    "OK" on success



180
181
182
 
# File 'lib/familia/data_type/types/stringkey.rb', line 180

def setex(seconds, val)
  dbclient.setex(dbkey, seconds.to_i, serialize_value(val))
end

#setnx(val) ⇒ Object 



75
76
77
78
79
 
# File 'lib/familia/data_type/types/stringkey.rb', line 75

def setnx(val)
  ret = dbclient.setnx(dbkey, serialize_value(val))
  update_expiration
  ret
end

#setrange(offset, val) ⇒ Object 



130
131
132
133
134
 
# File 'lib/familia/data_type/types/stringkey.rb', line 130

def setrange(offset, val)
  ret = dbclient.setrange dbkey, offset, val
  update_expiration
  ret
end

#to_i ⇒ Object 



59
60
61
 
# File 'lib/familia/data_type/types/stringkey.rb', line 59

def to_i
  value.to_i
end

#to_s ⇒ Object 



53
54
55
56
57
 
# File 'lib/familia/data_type/types/stringkey.rb', line 53

def to_s
  return super if value.to_s.empty?

  value.to_s
end

#value ⇒ Object Also known as: content, get 



45
46
47
48
49
 
# File 'lib/familia/data_type/types/stringkey.rb', line 45

def value
  echo :value, Familia.pretty_stack(limit: 1) if Familia.debug
  dbclient.setnx dbkey, @opts[:default] if @opts[:default]
  deserialize_value dbclient.get(dbkey)
end

#value=(val) ⇒ Object Also known as: replace, set

Note:

This method executes a Redis SET immediately, unlike scalar field setters which are deferred until save. If the parent object has unsaved scalar field changes, consider calling save first to avoid split-brain state.



66
67
68
69
70
71
 
# File 'lib/familia/data_type/types/stringkey.rb', line 66

def value=(val)
  warn_if_dirty!
  ret = dbclient.set(dbkey, serialize_value(val))
  update_expiration
  ret
end