prosody 0.5.1 → 0.6.0

data/lib/prosody/state/deque.rb

@@ -0,0 +1,253 @@
+# frozen_string_literal: true
+
+# The deque collection: the owned {Prosody::DequeState} handle and the
+# {Prosody::PublishedDeque} reader.
+
+module Prosody
+  # A deque keyed-state handle.
+  #
+  # Traversal is explicit: {#each}/{#reverse_each} yield single elements over a
+  # native scan, closing the scan via `ensure`. No aggregate-mixin methods are
+  # provided.
+  class DequeState < State::Handle
+    include State::Scanning
+
+    # Appends an element at the back.
+    #
+    # @param value [Object] the element (JSON, or a message)
+    # @return [void]
+    # @raise [PermanentStateError] if `value` is `nil` (use {#clear} to delete)
+    def push(value) = @native.push_back(value)
+
+    # Prepends an element at the front.
+    #
+    # @param value [Object] the element (JSON, or a message)
+    # @return [void]
+    # @raise [PermanentStateError] if `value` is `nil` (use {#clear} to delete)
+    def unshift(value) = @native.push_front(value)
+
+    # Removes and returns the back element.
+    #
+    # @return [Object, nil] the removed element, or `nil` when empty
+    def pop = @native.pop_back
+
+    # Removes and returns the front element.
+    #
+    # @return [Object, nil] the removed element, or `nil` when empty
+    def shift = @native.pop_front
+
+    # The number of live elements.
+    #
+    # @return [Integer]
+    def length = @native.len
+
+    alias_method :size, :length
+
+    # Whether the deque holds no live elements.
+    #
+    # @return [Boolean]
+    def empty? = @native.is_empty
+
+    # Removes every element.
+    #
+    # @return [void]
+    def clear = @native.clear
+
+    # Reads the element at `index`, resolving negatives Array-style (mirrors
+    # +Array#[]+'s read domain, without the indexer). A non-negative index
+    # reads from the front; `-1` is the back element, `-n` the nth from the end.
+    # `-1` fast-paths through {#last} (no length read); other negatives resolve
+    # against the current length (one length read + one element read),
+    # consistent because the deque has a single writer per attempt.
+    #
+    # @param index [Integer] the position (negative counts from the back)
+    # @return [Object, nil] the element, or `nil` outside the bounds
+    # @raise [TransientStateError] if `index` is not an Integer
+    def get(index)
+      unless index.is_a?(Integer)
+        raise TransientStateError, "get: index must be an Integer, got #{index.inspect}"
+      end
+      index.negative? ? at_negative(index) : @native.get(index)
+    end
+
+    # Traverses the live elements in index order.
+    #
+    # Without a block, returns an {Enumerator} over the native scan. Each step
+    # fiber-yields; the scan is closed via `ensure` on stop or exception.
+    #
+    # Accepts the position keywords documented on {State::Scanning}. Positions
+    # count from the front and must be non-negative. To read from the back,
+    # use {#reverse_each} with `limit:`.
+    #
+    # @param query [Hash] optional `from:`, `after:`, `to:`, `before:`,
+    #   `range:`, and `limit:` keywords
+    # @yieldparam element [Object]
+    # @return [Enumerator, void]
+    # @raise [ArgumentError, TypeError] if a query keyword is invalid
+    def each(**query, &block) = traverse(:scan, :forward, query, &block)
+
+    # Traverses the live elements in reverse index order.
+    #
+    # @param query [Hash] optional position keywords, as on {#each}
+    # @yieldparam element [Object]
+    # @return [Enumerator, void]
+    def reverse_each(**query, &block) = traverse(:scan, :backward, query, &block)
+
+    # --- idiomatic Array-style conveniences -----------------------------
+    # Composed from the canonical ops above; bounded reads only (no +to_a+,
+    # +map+, +sort+, or +Enumerable+ that would materialize the whole deque).
+    #
+    # Deliberately NOT provided: +[]+ and +at+. This is a remote deque; +get+
+    # and +fetch+ accept a single +Integer+ index (negatives resolve from the
+    # back, Array-style), but wearing +Array+'s +[]+/+at+ would invite a range
+    # read (+deque[0..2]+) that cannot be honored. Use the explicit {#get}, or
+    # {#first}/{#last} for the ends.
+
+    # Prepends +value+, returning +self+ for chaining (mirrors +Array#prepend+).
+    # A wrapper, not an alias: the native write returns +nil+.
+    #
+    # @param value [Object]
+    # @return [self]
+    def prepend(value)
+      unshift(value)
+      self
+    end
+
+    # Appends +value+, returning +self+ for chaining (mirrors +Array#append+).
+    # A wrapper, not an alias: the native write returns +nil+.
+    #
+    # @param value [Object]
+    # @return [self]
+    def append(value)
+      push(value)
+      self
+    end
+
+    # Appends +value+ and returns +self+ (mirrors +Array#<<+). Alias of
+    # {#append}.
+    alias_method :<<, :append
+
+    # The front element, or +nil+ when empty (mirrors +Array#first+). An
+    # endpoint-slot read in one round trip (no length read). Under a TTL an
+    # expired front slot yields +nil+ even when live interior elements remain —
+    # a peek never searches inward.
+    #
+    # @return [Object, nil]
+    def first = @native.peek_front
+
+    # The back element, or +nil+ when empty (mirrors +Array#last+). An
+    # endpoint-slot read in one round trip (no length read); same TTL-hole
+    # semantics as {#first}.
+    #
+    # @return [Object, nil]
+    def last = @native.peek_back
+
+    # Reads the element at +index+, raising or defaulting when out of range
+    # (mirrors +Array#fetch+). A +nil+ result is unambiguously "out of range"
+    # under the null ban. A negative index counts from the back, as in {#get}.
+    # A non-Integer index raises {TransientStateError}.
+    #
+    # @param index [Integer] the position (negative counts from the back)
+    # @param default [Object] returned when +index+ is out of range
+    # @yieldparam index [Integer] called (instead of +default+) when out of range
+    # @return [Object]
+    # @raise [IndexError] when out of range and no default or block is given
+    # @raise [TransientStateError] if +index+ is not an Integer
+    def fetch(index, *default, &block)
+      if default.length > 1
+        raise ArgumentError, "wrong number of arguments (given #{default.length + 1}, expected 1..2)"
+      end
+      unless index.is_a?(Integer)
+        raise TransientStateError, "fetch: index must be an Integer, got #{index.inspect}"
+      end
+      warn "warning: block supersedes default value argument" if block && !default.empty?
+
+      value = get(index)
+      case value
+      when nil
+        return block.call(index) if block
+        raise IndexError, "index #{index} outside deque bounds" if default.empty?
+
+        # Steep merges the overloads, so it cannot type the default as D.
+        default.fetch(0) #: untyped
+      else
+        value
+      end
+    end
+
+    private
+
+    # Resolves a negative Array-style index against the current length: +-1+
+    # fast-paths through {#last} (no length read), other negatives read the
+    # length and index from the front. Returns +nil+ when the index resolves
+    # before the front (past the far end of the deque).
+    def at_negative(index)
+      return @native.peek_back if index == -1
+
+      resolved = @native.len + index
+      resolved.negative? ? nil : @native.get(resolved)
+    end
+  end
+
+  # A read-only view of a published deque, opened by
+  # +client.state(subsystem, definition)+. Each read takes the user key and
+  # sees only committed state. A failed read raises the same state errors as
+  # an owned handle. A read in a forked child process raises +RuntimeError+.
+  class PublishedDeque
+    include State::Scanning
+
+    # @param native [Prosody::NativePublishedDeque] the native reader
+    def initialize(native) = @native = native
+
+    # Reads the committed element at +index+ in the deque for +key+. A
+    # negative index counts from the back, as in {DequeState#get}.
+    #
+    # @param index [Integer] the position (negative counts from the back)
+    # @return [Object, nil] the element, or +nil+ outside the bounds
+    # @raise [TransientStateError] if +index+ is not an Integer
+    def get(key, index)
+      unless index.is_a?(Integer)
+        raise TransientStateError, "get: index must be an Integer, got #{index.inspect}"
+      end
+
+      return @native.get(key, index) unless index.negative?
+      # This repeats DequeState#at_negative, because a reader needs the key.
+      return last(key) if index == -1
+
+      resolved = length(key) + index
+      resolved.negative? ? nil : @native.get(key, resolved)
+    end
+
+    # The number of committed elements in the deque for +key+.
+    #
+    # @return [Integer]
+    def length(key) = @native.length(key)
+    alias_method :size, :length
+
+    # Whether the deque for +key+ has no committed elements.
+    #
+    # @return [Boolean]
+    def empty?(key) = @native.is_empty(key)
+
+    # The front element of the deque for +key+.
+    #
+    # @return [Object, nil] the element, or +nil+ when the deque is empty
+    def first(key) = @native.peek_front(key)
+
+    # The back element of the deque for +key+.
+    #
+    # @return [Object, nil] the element, or +nil+ when the deque is empty
+    def last(key) = @native.peek_back(key)
+
+    # Traverses the committed elements for +key+ from front to back. Each
+    # traversal accepts the position keywords documented on {State::Scanning}.
+    #
+    # @return [Enumerator, void]
+    def each(key, **query, &block) = traverse(:scan, key, :forward, query, &block)
+
+    # Traverses the committed elements for +key+ from back to front.
+    #
+    # @return [Enumerator, void]
+    def reverse_each(key, **query, &block) = traverse(:scan, key, :backward, query, &block)
+  end
+end

data/lib/prosody/state/map.rb

@@ -0,0 +1,313 @@
+# frozen_string_literal: true
+
+# The map collection: the owned {Prosody::MapState} handle and the
+# {Prosody::PublishedMap} reader.
+
+module Prosody
+  # A `String`-keyed ordered-map keyed-state handle.
+  #
+  # Traversal is explicit: {#each_pair}/{#reverse_each_pair} yield `key, value`
+  # pairs over a native scan, closing the scan via `ensure`. The map has no
+  # aggregate mixin methods, because they would load the whole remote
+  # collection.
+  class MapState < State::Handle
+    include State::Scanning
+
+    # Reads the value for `key`.
+    #
+    # @param key [String] the map key
+    # @return [Object, nil] the value, or `nil` when the key is absent
+    def get(key) = @native.get(key)
+
+    # Reads several keys in a single isolated batch.
+    #
+    # @param keys [Array<String>] the keys to read, in order
+    # @return [Array<Object, nil>] one result per input key; `nil` for absent keys
+    def get_many(keys) = @native.get_many(keys)
+
+    # Tests several keys for presence in a single batch. Like {#key?}, it
+    # decodes no values.
+    #
+    # @param keys [Array<String>] the keys to test, in order
+    # @return [Array<Boolean>] one result per input key
+    def contains_many(keys) = @native.contains_many(keys)
+
+    # Whether the map holds no live entries (mirrors +Hash#empty?+).
+    #
+    # @return [Boolean]
+    def empty? = @native.is_empty
+
+    # Inserts or overwrites `key`.
+    #
+    # @param key [String] the map key
+    # @param value [Object] the value to store (JSON, or a message)
+    # @return [void]
+    # @raise [PermanentStateError] if `value` is `nil` (use {#delete} to remove)
+    def set(key, value) = @native.set(key, value)
+
+    # Removes `key`.
+    #
+    # Documented divergence from `Hash#delete`: this returns `nil`, never the
+    # removed value (the erased FFI seam does not surface it).
+    #
+    # @param key [String] the map key
+    # @return [nil]
+    def delete(key)
+      @native.remove(key)
+      nil
+    end
+
+    # Removes every entry.
+    #
+    # @return [void]
+    def clear = @native.clear
+
+    # Traverses the live entries in key order, yielding `key, value`.
+    #
+    # Without a block, returns an {Enumerator} over the native scan. Each step
+    # fiber-yields; the scan is closed via `ensure` on stop or exception. The
+    # enumerator is valid only within the current handler invocation.
+    #
+    # Every map traversal accepts the query keywords documented on
+    # {State::Scanning}. For keyset paging, pass the last key of the previous
+    # page as `after:` and the page size as `limit:`.
+    #
+    # @param query [Hash] optional `from:`, `after:`, `to:`, `before:`,
+    #   `range:`, `prefix:`, and `limit:` keywords
+    # @yieldparam key [String]
+    # @yieldparam value [Object]
+    # @return [Enumerator, void]
+    # @raise [ArgumentError, TypeError] if a query keyword is invalid
+    def each_pair(**query, &block) = traverse(:scan, :forward, query, &block)
+
+    # Traverses the live entries in reverse key order, yielding `key, value`.
+    #
+    # @param query [Hash] optional query keywords, as on {#each_pair}
+    # @yieldparam key [String]
+    # @yieldparam value [Object]
+    # @return [Enumerator, void]
+    def reverse_each_pair(**query, &block) = traverse(:scan, :backward, query, &block)
+
+    # Traverses the live keys in key order, yielding each key (mirrors
+    # +Hash#each_key+). The key scan decodes no values, so a message-backed map
+    # fetches no Kafka messages. It can still read the store. Without a block,
+    # it returns an {Enumerator} that reads on demand. The map has no +keys+
+    # array, because it would load the whole remote keyset. The block form
+    # returns +nil+, as {#each_pair} does.
+    #
+    # @param query [Hash] optional query keywords, as on {#each_pair}
+    # @yieldparam key [String]
+    # @return [Enumerator, void]
+    def each_key(**query, &block) = traverse(:keys, :forward, query, &block)
+
+    # Traverses the live keys in reverse key order, yielding each key.
+    #
+    # @param query [Hash] optional query keywords, as on {#each_pair}
+    # @yieldparam key [String]
+    # @return [Enumerator, void]
+    def reverse_each_key(**query, &block) = traverse(:keys, :backward, query, &block)
+
+    # Traverses the live values in key order (mirrors +Hash#each_value+).
+    #
+    # @param query [Hash] optional query keywords, as on {#each_pair}
+    # @yieldparam value [Object]
+    # @return [Enumerator, void]
+    def each_value(**query, &block) = traverse_values(:forward, query, &block)
+
+    # Traverses the live values in reverse key order.
+    #
+    # @param query [Hash] optional query keywords, as on {#each_pair}
+    # @yieldparam value [Object]
+    # @return [Enumerator, void]
+    def reverse_each_value(**query, &block) = traverse_values(:backward, query, &block)
+
+    # --- idiomatic Hash-style aliases and conveniences ------------------
+    # Each is composed from the canonical ops above and adds no capability
+    # the naming matrix lacks. Bounded reads only: there is deliberately no
+    # +keys+/+values+/+to_h+/+count+ or +Enumerable+, which would materialize
+    # the whole (potentially unbounded) remote collection.
+
+    # Reads +key+. Idiomatic alias of {#get} (mirrors +Hash#[]+).
+    alias_method :[], :get
+
+    # Writes +key+. Idiomatic alias of {#set} (mirrors +Hash#[]=+). As with any
+    # Ruby +[]=+, `map[key] = value` evaluates to +value+ regardless of return.
+    alias_method :[]=, :set
+
+    # Writes +key+, returning the stored +value+ (mirrors +Hash#store+). A
+    # wrapper, not an alias: a caller sees the return value of +store+, and
+    # the native write returns +nil+.
+    #
+    # @param key [String]
+    # @param value [Object]
+    # @return [Object] the stored +value+
+    def store(key, value)
+      set(key, value)
+      value
+    end
+
+    # Traverses live entries in key order. Idiomatic alias of {#each_pair}
+    # (mirrors +Hash#each+).
+    alias_method :each, :each_pair
+
+    # Reads several keys positionally (mirrors +Hash#values_at+).
+    #
+    # @param keys [Array<String>] the keys to read
+    # @return [Array<Object, nil>] one result per key; +nil+ for absent keys
+    def values_at(*keys) = get_many(keys)
+
+    # Reads +key+, raising or defaulting when absent (mirrors +Hash#fetch+).
+    # Performs a single read; a +nil+ result is unambiguously "absent" under
+    # the null ban.
+    #
+    # @param key [String]
+    # @param default [Object] returned when +key+ is absent
+    # @yieldparam key [String] called (instead of +default+) when +key+ is absent
+    # @return [Object]
+    # @raise [KeyError] when +key+ is absent and no default or block is given
+    def fetch(key, *default, &block)
+      if default.length > 1
+        raise ArgumentError, "wrong number of arguments (given #{default.length + 1}, expected 1..2)"
+      end
+      warn "warning: block supersedes default value argument" if block && !default.empty?
+
+      value = @native.get(key)
+      return value unless value.nil?
+      return block.call(key) if block
+      raise KeyError.new("key not found: #{key.inspect}", key: key, receiver: self) if default.empty?
+
+      # Steep merges the overloads, so it cannot type the default as D.
+      default.fetch(0) #: untyped
+    end
+
+    # Whether +key+ has a live value (mirrors +Hash#key?+). The check decodes
+    # no value, so a message-backed map fetches no Kafka message. It returns
+    # +true+ for an entry whose message cannot be fetched. A cache miss can
+    # still read the store.
+    #
+    # @param key [String]
+    # @return [Boolean]
+    def key?(key) = @native.contains_key(key)
+    alias_method :has_key?, :key?
+    alias_method :include?, :key?
+    alias_method :member?, :key?
+
+    # Reads +key+ and digs into the nested value (mirrors +Hash#dig+). A single
+    # bounded read; digging continues in the returned local value.
+    #
+    # @param key [String]
+    # @return [Object, nil]
+    # @raise [TypeError] if a nested value does not respond to +dig+
+    def dig(key, *rest)
+      value = @native.get(key)
+      return value if rest.empty? || value.nil?
+
+      unless value.respond_to?(:dig)
+        raise TypeError, "#{value.class} does not have #dig method"
+      end
+
+      value.dig(*rest)
+    end
+
+    # Reads +keys+ as a single bounded batch, returning a +Hash+ of only the
+    # keys that are present (mirrors +Hash#slice+). Absent keys are omitted.
+    #
+    # @param keys [Array<String>] the keys to read
+    # @return [Hash{String => Object}] present keys mapped to their values
+    def slice(*keys) = keys.zip(get_many(keys)).to_h.compact
+
+    # Reads +keys+ as a single bounded batch, requiring every key to be present
+    # (mirrors +Hash#fetch_values+). Without a block, a missing key raises
+    # {KeyError}; with a block, the block is called with each missing key and
+    # its result substituted.
+    #
+    # @param keys [Array<String>] the keys to read, in order
+    # @yieldparam key [String] called for each absent key
+    # @return [Array<Object>] one value per key, in order
+    # @raise [KeyError] when a key is absent and no block is given
+    def fetch_values(*keys, &block)
+      keys.zip(get_many(keys)).map do |key, value|
+        case value
+        when nil
+          next block.call(key) if block
+
+          raise KeyError.new("key not found: #{key.inspect}", key: key, receiver: self)
+        else
+          value
+        end
+      end
+    end
+  end
+
+  # A read-only view of a published map, opened by
+  # +client.state(subsystem, definition)+. Each read takes the user key and
+  # sees only committed state. A failed read raises the same state errors as
+  # an owned handle. A read in a forked child process raises +RuntimeError+.
+  class PublishedMap
+    include State::Scanning
+
+    # @param native [Prosody::NativePublishedMap] the native reader
+    def initialize(native) = @native = native
+
+    # Reads the committed entry for +map_key+ in the map for +key+.
+    #
+    # @return [Object, nil] the value, or +nil+ when the entry is absent
+    def get(key, map_key) = @native.get(key, map_key)
+
+    # Reads several entries of the map for +key+ in one batch.
+    #
+    # @return [Array<Object, nil>] one result per map key; +nil+ for an absent entry
+    def get_many(key, map_keys) = @native.get_many(key, map_keys)
+
+    # Whether the map for +key+ has a committed entry for +map_key+.
+    #
+    # @return [Boolean]
+    def key?(key, map_key) = @native.contains_key(key, map_key)
+    alias_method :has_key?, :key?
+    alias_method :include?, :key?
+    alias_method :member?, :key?
+
+    # Tests several entries of the map for +key+ in one batch.
+    #
+    # @return [Array<Boolean>] one result per map key
+    def contains_many(key, map_keys) = @native.contains_many(key, map_keys)
+
+    # Whether the map for +key+ has no committed entries.
+    #
+    # @return [Boolean]
+    def empty?(key) = @native.is_empty(key)
+
+    # Traverses the committed entries for +key+ in key order, yielding one
+    # +[map_key, value]+ pair for each entry. Each traversal accepts the query
+    # keywords documented on {State::Scanning}.
+    #
+    # @return [Enumerator, void]
+    def each_pair(key, **query, &block) = traverse(:scan, key, :forward, query, &block)
+
+    # Traverses the committed entries for +key+ in reverse key order.
+    #
+    # @return [Enumerator, void]
+    def reverse_each_pair(key, **query, &block) = traverse(:scan, key, :backward, query, &block)
+
+    # Traverses the committed map keys for +key+ in key order.
+    #
+    # @return [Enumerator, void]
+    def each_key(key, **query, &block) = traverse(:keys, key, :forward, query, &block)
+
+    # Traverses the committed map keys for +key+ in reverse key order.
+    #
+    # @return [Enumerator, void]
+    def reverse_each_key(key, **query, &block) = traverse(:keys, key, :backward, query, &block)
+
+    # Traverses the committed values for +key+ in key order.
+    #
+    # @return [Enumerator, void]
+    def each_value(key, **query, &block) = traverse_values(key, :forward, query, &block)
+
+    # Traverses the committed values for +key+ in reverse key order.
+    #
+    # @return [Enumerator, void]
+    def reverse_each_value(key, **query, &block) = traverse_values(key, :backward, query, &block)
+    alias_method :each, :each_pair
+  end
+end

data/lib/prosody/state/set.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module Prosody
+  # A presence-only ordered set of String members, vended by
+  # +context.state(Prosody.set(...))+. It mirrors Ruby's +Set+.
+  #
+  # Writes are buffered and made durable when the handler succeeds or by
+  # {#commit}. Every operation yields the fiber, never the thread. There is
+  # deliberately no +Enumerable+ or +to_a+: they would read the whole remote
+  # set. Traverse members with {#each} or {#reverse_each}.
+  class SetState < State::Handle
+    include State::Scanning
+
+    # Adds +member+ (mirrors +Set#add+).
+    #
+    # @param member [String]
+    # @return [self]
+    def add(member)
+      @native.insert(member)
+      self
+    end
+
+    alias_method :<<, :add
+
+    # Removes +member+ when present (mirrors +Set#delete+).
+    #
+    # @param member [String]
+    # @return [self]
+    def delete(member)
+      @native.remove(member)
+      self
+    end
+
+    # Whether +member+ belongs to the set (mirrors +Set#include?+).
+    #
+    # @param member [String]
+    # @return [Boolean]
+    def include?(member) = @native.contains(member)
+
+    alias_method :member?, :include?
+
+    # Tests several members in a single batch.
+    #
+    # @param members [Array<String>] the members to test, in order
+    # @return [Array<Boolean>] one result per input member
+    def contains_many(members) = @native.contains_many(members)
+
+    # Whether the set has no live members (mirrors +Set#empty?+).
+    #
+    # @return [Boolean]
+    def empty? = @native.is_empty
+
+    # Removes every member (mirrors +Set#clear+).
+    #
+    # @return [self]
+    def clear
+      @native.clear
+      self
+    end
+
+    # Traverses the live members in ascending order.
+    #
+    # Without a block, returns an {Enumerator} over the native scan. Accepts
+    # the query keywords documented on {State::Scanning}, including
+    # +prefix:+.
+    #
+    # @param query [Hash] optional query keywords
+    # @yieldparam member [String]
+    # @return [Enumerator, void]
+    # @raise [ArgumentError, TypeError] if a query keyword is invalid
+    def each(**query, &block) = traverse(:keys, :forward, query, &block)
+
+    # Traverses the live members in descending order.
+    #
+    # @param query [Hash] optional query keywords, as on {#each}
+    # @yieldparam member [String]
+    # @return [Enumerator, void]
+    def reverse_each(**query, &block) = traverse(:keys, :backward, query, &block)
+  end
+
+  # A read-only view of a published set, opened by
+  # +client.state(subsystem, definition)+. Each read takes the user key and
+  # sees only committed state. A failed read raises the same state errors as
+  # an owned handle. A read in a forked child process raises +RuntimeError+.
+  class PublishedSet
+    include State::Scanning
+
+    # @param native [Prosody::NativePublishedSet] the native reader
+    def initialize(native)
+      @native = native
+    end
+
+    # Whether +member+ belongs to the committed set for +key+.
+    #
+    # @return [Boolean]
+    def include?(key, member) = @native.contains(key, member)
+
+    alias_method :member?, :include?
+
+    # Tests several members of the committed set for +key+ in one batch.
+    #
+    # @return [Array<Boolean>] one result per input member
+    def contains_many(key, members) = @native.contains_many(key, members)
+
+    # Whether the committed set for +key+ has no members.
+    #
+    # @return [Boolean]
+    def empty?(key) = @native.is_empty(key)
+
+    # Traverses the committed members for +key+ in ascending order. Accepts
+    # the query keywords documented on {State::Scanning}.
+    #
+    # @return [Enumerator, void]
+    def each(key, **query, &block) = traverse(:keys, key, :forward, query, &block)
+
+    # Traverses the committed members for +key+ in descending order.
+    #
+    # @return [Enumerator, void]
+    def reverse_each(key, **query, &block) = traverse(:keys, key, :backward, query, &block)
+  end
+end