Concepts of a Containers Std.Lib.

My Containers.rbs

# Basics

module Container[V, E = V]: _Container[V, E]
  include Enumerable[E]
  
  interface _Container[V, E = V]
    def self.from: (Enumerable[E] other) -> instance
    
    def include?: (V value) -> bool
    def add?: (E entry) -> E?
    
    def delete: (V value) -> V?
    def delete_all: (V value) -> Container[V]
    def select!: () { (E entry) -> bool } -> self?
    
    def size: () -> Integer
  end
  
  def self.[]: (*E entries) -> instance # from(entries)
  def <<: (E entry) -> self # tap { it.add? entry }
  def empty?: () -> bool # size.zero?
  def reject!  : () { (E entry) -> bool } -> self? # select { !blk.(it) }
  def keep_if  : () { (E entry) -> bool } -> self # tap { it.select!(&) }
  def delete_if: () { (E entry) -> bool } -> self # tap { it.reject!(&) }
  def clear: () -> self
end

module RandomAccess[K, V, E = V]: _RandomAccess[K, V, E]
  include Container[V, E]
  
  interface _RandomAccess[K, V, L = K, E = V]
    include _Container[V, E]
    def []: (L key) -> V?
    def []=: (L key, V value) -> V
    
    def index?: (K key) -> bool
    def find: (V value) -> K?
    def delete_at: (*L key) -> Container[V]
  end
  
  def fetch: # index? ? self[key] : …
    (K key) -> V # … raise IndexError
  | (K key, V default) -> V # … default
  | (K key) { (K missing_key) -> V } -> V # … blk.(key)
  def fetch_values: (*K keys) -> Enumerable[V] # keys.map { self.fetch it }
end


# Queues

module Deque[V, E = V]: _Deque[V, E]
  include Container[V, E]
  
  interface _SinglySequenced[V, E = V]
    interface _Container[V, E]
    def first: () -> V?
    def shift: () -> V?
  end
  
  interface _Sequenced[V, E]
    include _SinglySequenced[V, E]
    def last : () -> V?
    def pop : () -> V?
  end
  interface _Deque[V, E = V]
    include _Sequenced[V, E]
    def push   : (E) -> E
    def unshift: (E) -> E
    def reverse!: () -> instance
  end
  
  def reverse: () -> instance # dup.reverse!
end

class BlockingQueue[V]
  include Container[V]
  include _SinglySequenced[V]
  def shift: (timeout: _ToF?) -> V? | ...
  # ...
end

module IndexCache[
  V, I < Comparable::_WithSpaceshipOperator = V, E = V
]: _SinglySequenced[V, E]
  include Container[E]
  private def convert: (V value) -> I # value
  def rekey: () -> void # nil
end
class PriorityQueue[V, I < Comparable::_WithSpaceshipOperator = V]
  include IndexCache[V, I]
  include _Container[V, E]
  # ...
end

class LinkedList[V]
  include Deque[V]
  class Node[E]
    # ...
  end
  # ...
end
class Array[V]
  include Deque[V]
  include RandomAccess[Integer, V, Integer | Range[Integer]]
  # ...
end


# Sets

module Set[E]: _Container[E]
  include Container[E]
  def &: (Container[E] other) -> instance
    # self.class.from other.select {self.include? it}
  def |: (Container[E] other) -> instance
    # other.each_with_object(dup) { _2.add _1 }
  def ^: (Set[E] other) -> instance
end

class SortedSet[V, I < Comparable::_WithSpaceshipOperator = V]
  interface _SortedSet[V, I < Comparable::_WithSpaceshipOperator = V]
    include Set[V]
    include _Sequenced[V]
    include IndexCache[V, I]
  end
  include _SortedSet[V]
  # ...
end
class EnumSet[V = Integer]
  include SortedSet::_SortedSet[V, Integer]
  # ...
end

class HashSet[V]
  module HashContainer[V, E = V]: _SinglySequenced[V, E]
    include IndexCache[V, Integer]
    def initialize: (?Integer initial_capacity)
    def capacity: () -> Integer
    private def convert: ... # super.hash
  end
  include Set[V]
  include HashContainer[V]
  # ...
end


# Set Helpers

class Set::InsertionOrder[V, S < Set[Node[V]] = HashSet[Node[V]]]
  class Node[V] < LinkedList::Node[V]
    # ...
  end
  include Set[V]
  include Deque[V]
  attr_reader backing_set : S
  attr_reader backing_list: LinkedList[V]
  def initialize: (?singleton(Set) set_klass) -> void
    # @backing_set = set_klass.new
  # ...
end
class Set::Multi[V, S < Set[[K, V]]] < Container[V]
  attr_reader tallies: Map[V, Integer, S]
  def initialize: (?singleton(Set) set_klass) -> void
    # tallies = Map.new set_klass
end

class Map[K, V, S < Set[[K, V]]] < RandomAccess[K, V, [K, V]]
  attr_reader pair_set: S
  # ...
  def self.new: (?singleton(Set) set_klass) -> instance # new set_klass.new
              | ...
  def initialize: (?(singleton(Set)|S) pair_set) -> void
  # ...
  
  class Multi[
    K, V, S < Set[[K, L]], M < Map[K, L, S], L < Container[V] = Array[V]
  ] < RandomAccess[K, V, [K, V]]
    attr_reader backing_map: M
    def initialize: (?singleton(Set) set_klass) -> void
      # backing_map = Map.new set_klass
  end
end