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_hkdf_salt, #encryption_hkdf_salt_history, #encryption_keys, #encryption_personalization, #encryption_personalization_history, #logical_database, #prefix, #raise_on_unsaved_parent_write, #schema_path, #schema_validator, #schemas, #strict_write_order, #suffix, #transaction_mode

Class Method Summary collapse

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, #strip_legacy_json_encoding

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=, #with_connection_scope

Methods included from Settings

#configure, #default_suffix, #dirty_write_warnings, #dirty_write_warnings=, #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.

Class Method Details

.supports_max_length? ⇒ Boolean

ListKey implements :max_length (capped collection, issue #351) with per-end semantics — intentionally not unified with SortedSet's score-based trim: #push trims from the head (keeps the newest tail, LTRIM -max_length -1), while #unshift trims from the tail (keeps the newest head, LTRIM 0 max_length-1). Either way the max_length most recently written elements survive. NOT capped: pushx/unshiftx, insert, set, move destinations, and external writers.

Returns:

  • (Boolean)


16
17
18
# File 'lib/familia/data_type/types/listkey.rb', line 16

def self.supports_max_length?
  true
end

Instance Method Details

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



61
62
63
# File 'lib/familia/data_type/types/listkey.rb', line 61

def <<(val)
  push(val)
end

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

Returns the element at +idx+, or the elements of the range or count. Inside a transaction or pipeline, the LINDEX or LRANGE Future (resolves to the raw element or elements).

Parameters:

  • idx (Integer, Range) —

    an index, or a range of indexes

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

    number of elements from +idx+

Returns:

  • (Object, Array<Object>, nil, Redis::Future) —

    the element at +idx+, or the elements of the range or count. Inside a transaction or pipeline, the LINDEX or LRANGE Future (resolves to the raw element or elements).



133
134
135
136
137
138
139
140
141
142
143
144
145
# File 'lib/familia/data_type/types/listkey.rb', line 133

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



267
268
269
# File 'lib/familia/data_type/types/listkey.rb', line 267

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

#collectraw ⇒ Object



257
258
259
260
# File 'lib/familia/data_type/types/listkey.rb', line 257

def collectraw(&)
  Familia.assert_replies_available!('ListKey#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



224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
# File 'lib/familia/data_type/types/listkey.rb', line 224

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

  Familia.assert_replies_available!('ListKey#each')

  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

The raw iterators need the LRANGE reply to iterate over, so they raise Familia::OperationModeError inside a transaction or pipeline.



247
248
249
250
# File 'lib/familia/data_type/types/listkey.rb', line 247

def eachraw(&)
  Familia.assert_replies_available!('ListKey#eachraw')
  rangeraw.each(&)
end

#eachraw_with_index ⇒ Object



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

def eachraw_with_index(&)
  Familia.assert_replies_available!('ListKey#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



22
23
24
# File 'lib/familia/data_type/types/listkey.rb', line 22

def element_count
  dbclient.llen dbkey
end

#empty? ⇒ Boolean, Redis::Future

Returns whether the list has no elements. Inside a transaction or pipeline, the LLEN Future (resolves to the count).

Returns:

  • (Boolean, Redis::Future) —

    whether the list has no elements. Inside a transaction or pipeline, the LLEN Future (resolves to the count).



32
33
34
# File 'lib/familia/data_type/types/listkey.rb', line 32

def empty?
  Familia.transform_reply(element_count, &:zero?)
end

#enforce_max_length!(keep: :tail) ⇒ Integer, Redis::Future

Trims an already-oversized list down to its :max_length cap. Capped writes enforce the cap going forward, but nothing runs at definition time: adding max_length: to a live collection leaves the existing overage in place until the next push/unshift. Call this once, e.g. as a migration step, to enforce the cap immediately.

The cap's per-end semantics belong to the write method (push keeps the tail, unshift keeps the head), so a manual trim must be told which end to keep: keep: :tail matches a push-fed list (the default), keep: :head an unshift-fed one.

LLEN and LTRIM run in one MULTI so the removed count is exact even under concurrent writes. Inside a caller transaction or pipeline the pair is queued bare and the pre-trim length's future is returned instead of a count.

Parameters:

  • keep (:tail, :head) (defaults to: :tail) —

    which end of the list survives the trim

Returns:

  • (Integer, Redis::Future) —

    number of elements removed (0 when already within cap); inside a caller transaction or pipeline, the future of the pre-trim length instead

Raises:



304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
# File 'lib/familia/data_type/types/listkey.rb', line 304

def enforce_max_length!(keep: :tail)
  max = require_max_length!
  start, stop = case keep
                when :tail then [-max, -1]
                when :head then [0, max - 1]
                else
                  raise ArgumentError, "keep must be :tail or :head, got #{keep.inspect}"
  end
  warn_if_dirty!
  length = execute_capped_write do |conn|
    ret = conn.llen(dbkey)
    conn.ltrim(dbkey, start, stop)
    ret
  end
  update_expiration
  length.is_a?(Integer) ? [length - max, 0].max : length
end

#first ⇒ Object



421
422
423
# File 'lib/familia/data_type/types/listkey.rb', line 421

def first
  at 0
end

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

Inserts an element before or after a pivot element

Refreshes the TTL only when the element was inserted. Inside a transaction or pipeline the insert and the refresh are queued as one EVAL that makes the same decision when it runs, so a missing pivot leaves the list's TTL unchanged there too.

Parameters:

  • position (:before, :after) —

    Where to insert relative to pivot

  • pivot —

    The pivot element to search for

  • value —

    The value to insert

Returns:

  • (Integer, Redis::Future) —

    Length of list after insert, -1 if pivot not found, or 0 if the list does not exist. Inside a transaction or pipeline, the EVAL Future, which resolves to that Integer.



349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
# File 'lib/familia/data_type/types/listkey.rb', line 349

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
  conn = dbclient
  if queued_connection?(conn)
    return queue_conditional_write(conn, :linsert, pos, serialize_value(pivot), serialize_value(value))
  end

  result = conn.linsert dbkey, pos, serialize_value(pivot), serialize_value(value)
  update_expiration_if_written(Familia.positive?(result))
  result
end

#last ⇒ Object



425
426
427
# File 'lib/familia/data_type/types/listkey.rb', line 425

def last
  at(-1)
end

#member?(value) ⇒ Boolean, Redis::Future

Returns whether the list contains +value+. Inside a transaction or pipeline, the LPOS Future (resolves to the index or nil).

Returns:

  • (Boolean, Redis::Future) —

    whether the list contains +value+. Inside a transaction or pipeline, the LPOS Future (resolves to the index or nil).



151
152
153
# File 'lib/familia/data_type/types/listkey.rb', line 151

def member?(value)
  Familia.transform_reply(dbclient.lpos(dbkey, serialize_value(value))) { |pos| !pos.nil? }
end

#members(count = -1)) ⇒ Array<Object>, Redis::Future Also known as: all

Returns deserialized elements. Inside a transaction or pipeline, the LRANGE Future (resolves to raw strings).

Parameters:

  • count (Integer) (defaults to: -1)) —

    number of elements to return (-1 for all)

Returns:

  • (Array<Object>, Redis::Future) —

    deserialized elements. Inside a transaction or pipeline, the LRANGE Future (resolves to raw strings).



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

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



203
204
205
206
# File 'lib/familia/data_type/types/listkey.rb', line 203

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



373
374
375
376
377
378
379
380
381
382
383
384
385
386
# File 'lib/familia/data_type/types/listkey.rb', line 373

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, Redis::Future) —

    Single element or array if count specified. Inside a transaction or pipeline, the RPOP Future (resolves to the raw reply).



96
97
98
99
100
101
102
103
104
105
106
107
# File 'lib/familia/data_type/types/listkey.rb', line 96

def pop(count = nil)
  warn_if_dirty!
  ret = if count
    Familia.transform_reply(dbclient.rpop(dbkey, count)) do |result|
      result.nil? ? nil : deserialize_values(*result)
    end
  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.



39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
# File 'lib/familia/data_type/types/listkey.rb', line 39

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) }
  unless serialized.empty?
    if (max = @opts[:max_length])
      # Keep the tail: RPUSH appends there, so trimming from the head
      # retains the max_length newest elements.
      execute_capped_write do |conn|
        ret = conn.rpush(dbkey, serialized)
        conn.ltrim(dbkey, -max, -1)
        ret
      end
    else
      dbclient.rpush(dbkey, serialized)
    end
  end
  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



392
393
394
395
396
397
398
399
400
401
402
# File 'lib/familia/data_type/types/listkey.rb', line 392

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_written(Familia.positive?(result))
  result
end

#range(sidx = 0, eidx = -1)) ⇒ Array<Object>, Redis::Future

Returns deserialized elements. Inside a transaction or pipeline, the LRANGE Future (resolves to raw strings).

Returns:

  • (Array<Object>, Redis::Future) —

    deserialized elements. Inside a transaction or pipeline, the LRANGE Future (resolves to raw strings).



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

def range(sidx = 0, eidx = -1)
  Familia.transform_reply(rangeraw(sidx, eidx)) do |elements|
    deserialize_values(*elements)
  end
end

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



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

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



159
160
161
162
163
164
# File 'lib/familia/data_type/types/listkey.rb', line 159

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

#selectraw ⇒ Object



262
263
264
265
# File 'lib/familia/data_type/types/listkey.rb', line 262

def selectraw(&)
  Familia.assert_replies_available!('ListKey#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



327
328
329
330
331
332
# File 'lib/familia/data_type/types/listkey.rb', line 327

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, Redis::Future) —

    Single element or array if count specified. Inside a transaction or pipeline, the LPOP Future (resolves to the raw reply).



114
115
116
117
118
119
120
121
122
123
124
125
# File 'lib/familia/data_type/types/listkey.rb', line 114

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

#to_a(count = -1)) ⇒ Array<Object>

Ruby's conversion to an Array, used by splat and Array(). A conversion method must return its type, so inside a block to_a refuses instead of returning a Redis::Future; #members passes the Future through.

Parameters:

  • count (Integer) (defaults to: -1)) —

    number of elements to return (-1 for all)

Returns:

  • (Array<Object>) —

    the deserialized elements

Raises:



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

def to_a(count = -1)
  Familia.assert_replies_available!('ListKey#to_a')

  members(count)
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



275
276
277
278
279
280
# File 'lib/familia/data_type/types/listkey.rb', line 275

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.



70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
# File 'lib/familia/data_type/types/listkey.rb', line 70

def unshift(*values)
  warn_if_dirty!
  serialized = values.flatten.compact.map { |v| serialize_value(v) }
  unless serialized.empty?
    if (max = @opts[:max_length])
      # Keep the head: LPUSH prepends there, so trimming from the tail
      # retains the max_length newest elements.
      execute_capped_write do |conn|
        ret = conn.lpush(dbkey, serialized)
        conn.ltrim(dbkey, 0, max - 1)
        ret
      end
    else
      dbclient.lpush(dbkey, serialized)
    end
  end
  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



408
409
410
411
412
413
414
415
416
417
418
# File 'lib/familia/data_type/types/listkey.rb', line 408

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_written(Familia.positive?(result))
  result
end