Class: Familia::ListKey

Inherits:
DataType show all
Includes:
DataType::CollectionBase
Defined in:
lib/familia/data_type/types/listkey.rb

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

Instance Method Summary collapse

Methods included from DataType::CollectionBase

#collection_type?, #each_record

Methods included from Features::Autoloader

autoload_files, included, normalize_to_config_name

Methods included from DataType::Serialization

#deserialize_value, #deserialize_values, #deserialize_values_with_nil, #serialize_value

Methods included from DataType::DatabaseCommands

#current_expiration, #delete!, #echo, #exists?, #expire, #expireat, #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, #to_s, #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.

Instance Method Details

#<<(val) ⇒ Object Also known as: add_element, add 



36
37
38
 
# File 'lib/familia/data_type/types/listkey.rb', line 36

def <<(val)
  push(val)
end

#[](idx, count = nil) ⇒ Object Also known as: slice 



86
87
88
89
90
91
92
93
94
95
96
97
98
 
# File 'lib/familia/data_type/types/listkey.rb', line 86

def [](idx, count = nil)
  if idx.is_a? Range
    range idx.first, idx.last
  elsif count
    case count <=> 0
    when 1  then range(idx, idx + count - 1)
    when 0  then []
    when -1 then nil
    end
  else
    at idx
  end
end

#at(idx) ⇒ Object 



190
191
192
 
# File 'lib/familia/data_type/types/listkey.rb', line 190

def at(idx)
  deserialize_value dbclient.lindex(dbkey, idx)
end

#collectraw ⇒ Object 



182
183
184
 
# File 'lib/familia/data_type/types/listkey.rb', line 182

def collectraw(&)
  rangeraw.collect(&)
end

#each(batch_size: 100) {|element| ... } ⇒ Enumerator, self

Iterates over elements of the list.

Uses LRANGE pagination for memory-efficient iteration over large lists. Unlike sets, Redis lists do not support SCAN, so we paginate through the list using index ranges.

Examples:

Iterate all elements

history.each { |event| process(event) }

Use as Enumerator

history.each.with_index { |event, idx| puts "#{idx}: #{event}" }

Parameters:

  • batch_size (Integer) (defaults to: 100) —

    Number of elements to fetch per LRANGE call

Yields:

  • (element) —

    Each deserialized element

Returns:

  • (Enumerator, self) —

    Returns Enumerator if no block given, self otherwise



155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
 
# File 'lib/familia/data_type/types/listkey.rb', line 155

def each(batch_size: 100, &block)
  return to_enum(:each, batch_size: batch_size) unless block

  offset = 0
  loop do
    # LRANGE is inclusive on both ends, so end_idx = offset + batch_size - 1
    elements = range(offset, offset + batch_size - 1)
    break if elements.empty?

    elements.each(&block)
    offset += elements.size

    # If we got fewer than batch_size, we've reached the end
    break if elements.size < batch_size
  end

  self
end

#eachraw ⇒ Object 



174
175
176
 
# File 'lib/familia/data_type/types/listkey.rb', line 174

def eachraw(&)
  rangeraw.each(&)
end

#eachraw_with_index ⇒ Object 



178
179
180
 
# File 'lib/familia/data_type/types/listkey.rb', line 178

def eachraw_with_index(&)
  rangeraw.each_with_index(&)
end

#element_count ⇒ Integer Also known as: size, length, count

Returns the number of elements in the list

Returns:

  • (Integer) —

    number of elements



11
12
13
 
# File 'lib/familia/data_type/types/listkey.rb', line 11

def element_count
  dbclient.llen dbkey
end

#empty? ⇒ Boolean

Returns:

  • (Boolean) 


18
19
20
 
# File 'lib/familia/data_type/types/listkey.rb', line 18

def empty?
  element_count.zero?
end

#first ⇒ Object 



291
292
293
 
# File 'lib/familia/data_type/types/listkey.rb', line 291

def first
  at 0
end

#insert(position, pivot, value) ⇒ Integer Also known as: linsert

Inserts an element before or after a pivot element

Parameters:

  • position (:before, :after) —

    Where to insert relative to pivot

  • pivot —

    The pivot element to search for

  • value —

    The value to insert

Returns:

  • (Integer) —

    Length of list after insert, or -1 if pivot not found



224
225
226
227
228
229
230
231
232
233
234
235
 
# File 'lib/familia/data_type/types/listkey.rb', line 224

def insert(position, pivot, value)
  warn_if_dirty!
  pos = case position
        when :before, 'BEFORE' then 'BEFORE'
        when :after, 'AFTER' then 'AFTER'
        else
          raise ArgumentError, "position must be :before or :after, got #{position.inspect}"
        end
  result = dbclient.linsert dbkey, pos, serialize_value(pivot), serialize_value(value)
  update_expiration if Familia.positive?(result) == true
  result
end

#last ⇒ Object 



295
296
297
 
# File 'lib/familia/data_type/types/listkey.rb', line 295

def last
  at(-1)
end

#member?(value) ⇒ Boolean

Returns:

  • (Boolean) 


101
102
103
 
# File 'lib/familia/data_type/types/listkey.rb', line 101

def member?(value)
  !dbclient.lpos(dbkey, serialize_value(value)).nil?
end

#members(count = -1)) ⇒ Object Also known as: all, to_a 



126
127
128
129
130
 
# File 'lib/familia/data_type/types/listkey.rb', line 126

def members(count = -1)
  echo :members, Familia.pretty_stack(limit: 1) if Familia.debug
  count -= 1 if count.positive?
  range 0, count
end

#membersraw(count = -1)) ⇒ Object 



134
135
136
137
 
# File 'lib/familia/data_type/types/listkey.rb', line 134

def membersraw(count = -1)
  count -= 1 if count.positive?
  rangeraw 0, count
end

#move(destination, wherefrom, whereto) ⇒ Object? Also known as: lmove

Moves an element from this list to another list atomically

Parameters:

  • destination (ListKey, String) —

    Destination list (ListKey or key string)

  • wherefrom (:left, :right) —

    Which end to pop from source

  • whereto (:left, :right) —

    Which end to push to destination

Returns:

  • (Object, nil) —

    The moved element, or nil if source is empty



243
244
245
246
247
248
249
250
251
252
253
254
255
256
 
# File 'lib/familia/data_type/types/listkey.rb', line 243

def move(destination, wherefrom, whereto)
  warn_if_dirty!
  dest_key = destination.respond_to?(:dbkey) ? destination.dbkey : destination
  from = wherefrom.to_s.upcase
  to = whereto.to_s.upcase

  unless %w[LEFT RIGHT].include?(from) && %w[LEFT RIGHT].include?(to)
    raise ArgumentError, 'wherefrom and whereto must be :left or :right'
  end

  result = dbclient.lmove dbkey, dest_key, from, to
  update_expiration
  deserialize_value result
end

#pop(count = nil) ⇒ Object, ...

Removes and returns the last element(s) from the list

Parameters:

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

    Number of elements to pop (Redis 6.2+)

Returns:

  • (Object, Array<Object>, nil) —

    Single element or array if count specified



59
60
61
62
63
64
65
66
67
68
69
 
# File 'lib/familia/data_type/types/listkey.rb', line 59

def pop(count = nil)
  warn_if_dirty!
  ret = if count
          result = dbclient.rpop(dbkey, count)
          result.nil? ? nil : deserialize_values(*result)
        else
          deserialize_value dbclient.rpop(dbkey)
        end
  update_expiration
  ret
end

#push(*values) ⇒ Object Also known as: append

Note:

This method executes a Redis RPUSH 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.



25
26
27
28
29
30
31
32
33
 
# File 'lib/familia/data_type/types/listkey.rb', line 25

def push *values
  warn_if_dirty!
  echo :push, Familia.pretty_stack(limit: 1) if Familia.debug
  serialized = values.flatten.compact.map { |v| serialize_value(v) }
  dbclient.rpush(dbkey, serialized) unless serialized.empty?
  dbclient.ltrim dbkey, -@opts[:maxlength], -1 if @opts[:maxlength]
  update_expiration
  self
end

#pushx(*values) ⇒ Integer Also known as: rpushx

Pushes values only if the list already exists

Parameters:

  • values —

    Values to push to the tail of the list

Returns:

  • (Integer) —

    Length of list after push, or 0 if list doesn't exist



262
263
264
265
266
267
268
269
270
271
272
 
# File 'lib/familia/data_type/types/listkey.rb', line 262

def pushx(*values)
  return 0 if values.empty?

  serialized_values = values.flatten.compact.map { |v| serialize_value(v) }
  return 0 if serialized_values.empty?

  warn_if_dirty!
  result = dbclient.rpushx(dbkey, serialized_values)
  update_expiration if Familia.positive?(result) == true
  result
end

#range(sidx = 0, eidx = -1)) ⇒ Object 



117
118
119
120
 
# File 'lib/familia/data_type/types/listkey.rb', line 117

def range(sidx = 0, eidx = -1)
  elements = rangeraw sidx, eidx
  deserialize_values(*elements)
end

#rangeraw(sidx = 0, eidx = -1)) ⇒ Object 



122
123
124
 
# File 'lib/familia/data_type/types/listkey.rb', line 122

def rangeraw(sidx = 0, eidx = -1)
  dbclient.lrange(dbkey, sidx, eidx)
end

#remove_element(value, count = 0) ⇒ Integer Also known as: remove

Removes elements equal to value from the list

Parameters:

  • value —

    The value to remove

  • count (Integer) (defaults to: 0) —

    Number of elements to remove (0 means all)

Returns:

  • (Integer) —

    The number of removed elements



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

def remove_element(value, count = 0)
  warn_if_dirty!
  ret = dbclient.lrem dbkey, count, serialize_value(value)
  update_expiration
  ret
end

#selectraw ⇒ Object 



186
187
188
 
# File 'lib/familia/data_type/types/listkey.rb', line 186

def selectraw(&)
  rangeraw.select(&)
end

#set(index, value) ⇒ String Also known as: lset

Sets the element at the specified index

Parameters:

  • index (Integer) —

    Index to set (0-based, negative counts from end)

  • value —

    The value to set

Returns:

  • (String) —

    "OK" on success

Raises:

  • (Redis::CommandError) —

    if index is out of range



211
212
213
214
215
216
 
# File 'lib/familia/data_type/types/listkey.rb', line 211

def set(index, value)
  warn_if_dirty!
  result = dbclient.lset dbkey, index, serialize_value(value)
  update_expiration
  result
end

#shift(count = nil) ⇒ Object, ...

Removes and returns the first element(s) from the list

Parameters:

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

    Number of elements to shift (Redis 6.2+)

Returns:

  • (Object, Array<Object>, nil) —

    Single element or array if count specified



74
75
76
77
78
79
80
81
82
83
84
 
# File 'lib/familia/data_type/types/listkey.rb', line 74

def shift(count = nil)
  warn_if_dirty!
  ret = if count
          result = dbclient.lpop(dbkey, count)
          result.nil? ? nil : deserialize_values(*result)
        else
          deserialize_value dbclient.lpop(dbkey)
        end
  update_expiration
  ret
end

#trim(start, stop) ⇒ String Also known as: ltrim

Trims the list to the specified range

Parameters:

  • start (Integer) —

    Start index (0-based, negative counts from end)

  • stop (Integer) —

    End index (inclusive, negative counts from end)

Returns:

  • (String) —

    "OK" on success



198
199
200
201
202
203
 
# File 'lib/familia/data_type/types/listkey.rb', line 198

def trim(start, stop)
  warn_if_dirty!
  result = dbclient.ltrim dbkey, start, stop
  update_expiration
  result
end

#unshift(*values) ⇒ Object Also known as: prepend

Note:

This method executes a Redis LPUSH 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.



45
46
47
48
49
50
51
52
53
 
# File 'lib/familia/data_type/types/listkey.rb', line 45

def unshift *values
  warn_if_dirty!
  serialized = values.flatten.compact.map { |v| serialize_value(v) }
  dbclient.lpush(dbkey, serialized) unless serialized.empty?
  # TODO: test maxlength
  dbclient.ltrim dbkey, 0, @opts[:maxlength] - 1 if @opts[:maxlength]
  update_expiration
  self
end

#unshiftx(*values) ⇒ Integer Also known as: lpushx

Pushes values to the head only if the list already exists

Parameters:

  • values —

    Values to push to the head of the list

Returns:

  • (Integer) —

    Length of list after push, or 0 if list doesn't exist



278
279
280
281
282
283
284
285
286
287
288
 
# File 'lib/familia/data_type/types/listkey.rb', line 278

def unshiftx(*values)
  return 0 if values.empty?

  serialized_values = values.flatten.compact.map { |v| serialize_value(v) }
  return 0 if serialized_values.empty?

  warn_if_dirty!
  result = dbclient.lpushx(dbkey, serialized_values)
  update_expiration if Familia.positive?(result) == true
  result
end