factbase 0.17.0 → 0.18.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8e2593945542e79d93c93e662467bb704ad98d9a481887b5447341c700e4abf8
-  data.tar.gz: 5e13613617c829b0669235a275a1796c6556ca8cdced3ef9ee3502cbb2c300db
+  metadata.gz: 90b1ab3d82ed371b4de11b7eceb98137b2a7687bc2625e61d4d54a6538849b34
+  data.tar.gz: f9fd82d8254d7cfa646a742db6989790791ce157ce53d9e5a310f8f8f8c0db11
 SHA512:
-  metadata.gz: 22d7965bd3b3f60070ca8293e3c054ea5b2553913ccb091328f3d51f2aab3a42c3be56b5197536014c550eecceb708186a826cb1fe67b6e31deb636819ceb866
-  data.tar.gz: 5e5fef55d3e316d19d5d96c2de10b23d1788541c09a2331c8762cd73c1c4b15b468c7cb4c0ff4b4f33f3b296f0a875673568f7a1eca92744fbf54c2e0c042233
+  metadata.gz: ae0d064e075f304c9fae6f4903c961293d07e186ee6bdf4e180d5f407f5b166f2b3cc345cec612d8184675394a2ee504197d4c13d9ce0f480cffd850d7d10169
+  data.tar.gz: b53da29f44f9ad5520bed3602c9c7dadf882115856ddb344dfba95a32017cd2e89c4582a7a160baa2ed611ff37acd0ba39e8fb9a8aa8ed7bec62f0acf9f0ee70

data/Gemfile

@@ -12,12 +12,13 @@ gem 'minitest-reporters', '~>1.7', require: false
 gem 'os', '~>1.1', require: false
 gem 'qbash', '~>0.4', require: false
 gem 'rake', '~>13.2', require: false
-gem 'rdoc', '6.15.1', require: false # GPL
+gem 'rdoc', '6.17.0', require: false # GPL
 gem 'rubocop', '~>1.74', require: false
 gem 'rubocop-minitest', '~>0.38', require: false
 gem 'rubocop-performance', '~>1.25', require: false
 gem 'rubocop-rake', '~>0.7', require: false
 gem 'simplecov', '~>0.22', require: false
 gem 'simplecov-cobertura', '~>3.0', require: false
+gem 'stackprof', '~>0.2', require: false, platforms: [:ruby]
 gem 'threads', '~>0.4', require: false
 gem 'yard', '~>0.9', require: false

data/Gemfile.lock

@@ -30,7 +30,7 @@ GEM
       tago (~> 0.1)
     ellipsized (0.3.0)
     erb (6.0.0)
-    json (2.16.0)
+    json (2.17.1)
     language_server-protocol (3.17.0.5)
     lint_roller (1.1.0)
     logger (1.7.0)
@@ -68,7 +68,7 @@ GEM
     racc (1.8.1)
     rainbow (3.1.1)
     rake (13.3.1)
-    rdoc (6.15.1)
+    rdoc (6.17.0)
       erb
       psych (>= 4.0.0)
       tsort
@@ -109,7 +109,8 @@ GEM
       simplecov (~> 0.19)
     simplecov-html (0.13.2)
     simplecov_json_formatter (0.1.4)
-    stringio (3.1.8)
+    stackprof (0.2.27)
+    stringio (3.1.9)
     tago (0.4.0)
     threads (0.5.0)
       backtrace (~> 0)
@@ -119,7 +120,7 @@ GEM
       unicode-emoji (~> 4.1)
     unicode-emoji (4.1.0)
     yaml (0.4.0)
-    yard (0.9.37)
+    yard (0.9.38)
 
 PLATFORMS
   arm64-darwin-22
@@ -139,13 +140,14 @@ DEPENDENCIES
   os (~> 1.1)
   qbash (~> 0.4)
   rake (~> 13.2)
-  rdoc (= 6.15.1)
+  rdoc (= 6.17.0)
   rubocop (~> 1.74)
   rubocop-minitest (~> 0.38)
   rubocop-performance (~> 1.25)
   rubocop-rake (~> 0.7)
   simplecov (~> 0.22)
   simplecov-cobertura (~> 3.0)
+  stackprof (~> 0.2)
   threads (~> 0.4)
   yard (~> 0.9)
 

data/Rakefile

@@ -78,3 +78,19 @@ task :benchmark, [:name] do |_t, args|
     end
   end
 end
+
+# Run profiling on a benchmark and generate a flamegraph.
+# To run this task, you need to have stackprof installed.
+# https://github.com/tmm1/stackprof
+# To run profiling for a specific benchmark you can run:
+#   bundle exec rake flamegraph\[bench_slow_query\]
+desc 'Profile a benchmark (e.g., flamegraph[bench_slow_query])'
+task :flamegraph, [:name] do |_t, args|
+  require 'stackprof'
+  bname = args[:name] || 'all'
+  puts "Starting profiling for '#{bname}'..."
+  StackProf.run(mode: :cpu, out: 'stackprof-cpu-myapp.dump', raw: true) do
+    Rake::Task['benchmark'].invoke(bname)
+  end
+  `stackprof --d3-flamegraph stackprof-cpu-myapp.dump > flamegraph.html`
+end

data/lib/factbase/indexed/indexed_factbase.rb

@@ -57,9 +57,12 @@ class Factbase::IndexedFactbase
   # Run an ACID transaction.
   # @return [Factbase::Churn] How many facts have been changed (zero if rolled back)
   def txn
-    @origin.txn do |fbt|
-      yield Factbase::IndexedFactbase.new(fbt, @idx)
-    end
+    result =
+      @origin.txn do |fbt|
+        yield Factbase::IndexedFactbase.new(fbt, @idx)
+      end
+    @idx.clear
+    result
   end
 
   # Export it into a chain of bytes, including both data and index.

data/lib/factbase/lazy_taped.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: Copyright (c) 2024-2025 Yegor Bugayenko
+# SPDX-License-Identifier: MIT
+
+require_relative '../factbase'
+require_relative 'taped'
+require_relative 'lazy_taped_hash'
+
+# A lazy decorator of an Array with HashMaps that defers copying until modification.
+class Factbase::LazyTaped
+  def initialize(origin)
+    @origin = origin
+    @copied = false
+    @maps = nil
+    @pairs = nil
+    @inserted = []
+    @deleted = []
+    @added = []
+  end
+
+  # Returns a hash mapping copied maps to their originals.
+  # This is used during transaction commit to identify which original facts
+  # were modified, allowing the factbase to update the correct entries.
+  def pairs
+    return {} unless @pairs
+    result = {}.compare_by_identity
+    @pairs.each { |copied, original| result[copied] = original }
+    result
+  end
+
+  # Returns the unique object IDs of maps that were inserted (newly created).
+  # This is used during transaction commit to identify new facts that need
+  # to be added to the factbase.
+  def inserted
+    @inserted.uniq
+  end
+
+  # Returns the unique object IDs of maps that were deleted.
+  # This is used during transaction commit to identify facts that need
+  # to be removed from the factbase.
+  def deleted
+    @deleted.uniq
+  end
+
+  # Returns the unique object IDs of maps that were modified (properties added).
+  # This is used during transaction commit to track the churn (number of changes).
+  def added
+    @added.uniq
+  end
+
+  def find_by_object_id(oid)
+    (@maps || @origin).find { |m| m.object_id == oid }
+  end
+
+  def size
+    (@maps || @origin).size
+  end
+
+  def empty?
+    (@maps || @origin).empty?
+  end
+
+  def <<(map)
+    ensure_copied
+    @maps << map
+    @inserted.append(map.object_id)
+  end
+
+  def each
+    return to_enum(__method__) unless block_given?
+    if @copied
+      @maps.each do |m|
+        yield Factbase::Taped::TapedHash.new(m, @added)
+      end
+    else
+      @origin.each do |m|
+        yield LazyTapedHash.new(m, self, @added)
+      end
+    end
+  end
+
+  def delete_if
+    ensure_copied
+    @maps.delete_if do |m|
+      r = yield m
+      @deleted.append(@pairs[m].object_id) if r
+      r
+    end
+  end
+
+  def to_a
+    (@maps || @origin).to_a
+  end
+
+  def &(other)
+    if other == [] || (@maps || @origin).empty?
+      return Factbase::Taped.new([], inserted: @inserted, deleted: @deleted, added: @added)
+    end
+    join(other, &:&)
+  end
+
+  def |(other)
+    return Factbase::Taped.new(to_a, inserted: @inserted, deleted: @deleted, added: @added) if other == []
+    if (@maps || @origin).empty?
+      return Factbase::Taped.new(other, inserted: @inserted, deleted: @deleted, added: @added)
+    end
+    join(other, &:|)
+  end
+
+  def ensure_copied
+    return if @copied
+    @pairs = {}.compare_by_identity
+    @maps =
+      @origin.map do |m|
+        n = m.transform_values(&:dup)
+        @pairs[n] = m
+        n
+      end
+    @copied = true
+  end
+
+  def get_copied_map(original_map)
+    ensure_copied
+    @maps.find { |m| @pairs[m].equal?(original_map) }
+  end
+
+  private
+
+  def join(other)
+    n = yield (@maps || @origin).to_a, other.to_a
+    raise 'Cannot join with another Taped' if other.respond_to?(:inserted)
+    raise 'Can only join with array' unless other.is_a?(Array)
+    Factbase::Taped.new(
+      n,
+      inserted: @inserted,
+      deleted: @deleted,
+      added: @added
+    )
+  end
+end

data/lib/factbase/lazy_taped_array.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: Copyright (c) 2024-2025 Yegor Bugayenko
+# SPDX-License-Identifier: MIT
+
+require_relative '../factbase'
+
+class Factbase::LazyTaped
+  # Decorator of Array that triggers copy-on-write.
+  # @todo #424:30min Add dedicated unit tests for LazyTapedArray class.
+  #  Currently this class is tested indirectly through LazyTaped tests.
+  #  We should add explicit tests for all public methods including each, [],
+  #  to_a, any?, <<, and uniq! to ensure proper copy-on-write behavior.
+  class LazyTapedArray
+    # Creates a new lazy array wrapper.
+    # @param origin [Array] The original array to wrap
+    # @param key [String] The key in the parent hash where this array is stored
+    # @param taped_hash [LazyTapedHash] The parent hash wrapper that owns this array
+    # @param added [Array] Accumulator for tracking object IDs of modified facts
+    def initialize(origin, key, taped_hash, added)
+      @origin = origin
+      @key = key
+      @taped_hash = taped_hash
+      @added = added
+    end
+
+    def each(&)
+      return to_enum(__method__) unless block_given?
+      current_array.each(&)
+    end
+
+    def [](idx)
+      current_array[idx]
+    end
+
+    def to_a
+      current_array.to_a
+    end
+
+    def any?(pattern = nil, &)
+      pattern ? current_array.any?(pattern) : current_array.any?(&)
+    end
+
+    def <<(item)
+      @taped_hash.ensure_copied_map
+      @added.append(@taped_hash.tracking_id)
+      @taped_hash.get_copied_array(@key) << item
+    end
+
+    def uniq!
+      @taped_hash.ensure_copied_map
+      @added.append(@taped_hash.tracking_id)
+      @taped_hash.get_copied_array(@key).uniq!
+    end
+
+    private
+
+    def current_array
+      @taped_hash.copied? ? @taped_hash.get_copied_array(@key) : @origin
+    end
+  end
+end

data/lib/factbase/lazy_taped_hash.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: Copyright (c) 2024-2025 Yegor Bugayenko
+# SPDX-License-Identifier: MIT
+
+require_relative '../factbase'
+require_relative 'lazy_taped_array'
+
+class Factbase::LazyTaped
+  # Decorator of Hash that triggers copy-on-write.
+  # @todo #424:30min Add dedicated unit tests for LazyTapedHash class.
+  #  Currently this class is tested indirectly through LazyTaped tests.
+  #  We should add explicit tests for all public methods including keys, map,
+  #  bracket access, bracket assignment, and the copy-on-write behavior.
+  class LazyTapedHash
+    # Creates a new LazyTapedHash decorator.
+    # @param origin [Hash] The original hash being wrapped (not yet copied)
+    # @param lazy_taped [Factbase::LazyTaped] The parent LazyTaped instance that manages copy-on-write
+    # @param added [Array] Array to track object IDs of maps that have been modified
+    def initialize(origin, lazy_taped, added)
+      @origin = origin
+      @lazy_taped = lazy_taped
+      @added = added
+      @copied_map = nil
+    end
+
+    def keys
+      current_map.keys
+    end
+
+    def map(&)
+      current_map.map(&)
+    end
+
+    def [](key)
+      v = current_map[key]
+      v = LazyTapedArray.new(v, key, self, @added) if v.is_a?(Array)
+      v
+    end
+
+    def []=(key, value)
+      ensure_copied_map
+      @copied_map[key] = value
+      @added.append(@copied_map.object_id)
+    end
+
+    def ensure_copied_map
+      return if @copied_map
+      @copied_map = @lazy_taped.get_copied_map(@origin)
+    end
+
+    def get_copied_array(key)
+      ensure_copied_map
+      @copied_map[key]
+    end
+
+    def tracking_id
+      @copied_map ? @copied_map.object_id : @origin.object_id
+    end
+
+    def copied?
+      !@copied_map.nil?
+    end
+
+    private
+
+    def current_map
+      @copied_map || @origin
+    end
+
+    def method_missing(method, *, &)
+      current_map.send(method, *, &)
+    end
+
+    def respond_to_missing?(method, include_private = false)
+      current_map.respond_to?(method, include_private)
+    end
+  end
+end

data/lib/factbase/term.rb

@@ -52,6 +52,12 @@ require_relative 'terms/when'
 require_relative 'terms/either'
 require_relative 'terms/count'
 require_relative 'terms/first'
+require_relative 'terms/nth'
+require_relative 'terms/sum'
+require_relative 'terms/agg'
+require_relative 'terms/empty'
+require_relative 'terms/min'
+require_relative 'terms/max'
 
 # Term.
 #
@@ -80,7 +86,7 @@ require_relative 'terms/first'
 # Author:: Yegor Bugayenko (yegor256@gmail.com)
 # Copyright:: Copyright (c) 2024-2025 Yegor Bugayenko
 # License:: MIT
-class Factbase::Term
+class Factbase::Term < Factbase::TermBase
   # The operator of this term
   # @return [Symbol] The operator
   attr_reader :op
@@ -89,19 +95,11 @@ class Factbase::Term
   # @return [Array] The operands
   attr_reader :operands
 
-  require_relative 'terms/logical'
-  include Factbase::Logical
-
-  require_relative 'terms/aggregates'
-  include Factbase::Aggregates
-
-  require_relative 'terms/shared'
-  include Factbase::TermShared
-
   # Ctor.
   # @param [Symbol] operator Operator
   # @param [Array] operands Operands
   def initialize(operator, operands)
+    super()
     @op = operator
     @operands = operands
     @terms = {
@@ -149,7 +147,13 @@ class Factbase::Term
       when: Factbase::When.new(operands),
       either: Factbase::Either.new(operands),
       count: Factbase::Count.new(operands),
-      first: Factbase::First.new(operands)
+      first: Factbase::First.new(operands),
+      nth: Factbase::Nth.new(operands),
+      sum: Factbase::Sum.new(operands),
+      agg: Factbase::Agg.new(operands),
+      empty: Factbase::Empty.new(operands),
+      min: Factbase::Min.new(operands),
+      max: Factbase::Max.new(operands)
     }
   end
 
@@ -211,11 +215,15 @@ class Factbase::Term
   # Simplify it if possible.
   # @return [Factbase::Term] New term or itself
   def simplify
-    m = "#{@op}_simplify"
-    if respond_to?(m, true)
-      send(m)
+    if @terms.key?(@op) && @terms[@op].respond_to?(:simplify)
+      @terms[@op].simplify
     else
-      self
+      m = "#{@op}_simplify"
+      if respond_to?(m, true)
+        send(m)
+      else
+        self
+      end
     end
   end
 

data/lib/factbase/terms/agg.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: Copyright (c) 2024-2025 Yegor Bugayenko
+# SPDX-License-Identifier: MIT
+
+require_relative 'base'
+# The term 'agg' that aggregates.
+class Factbase::Agg < Factbase::TermBase
+  # Constructor.
+  # @param [Array] operands Operands
+  def initialize(operands = [])
+    super()
+    @operands = operands
+    @op = :agg
+  end
+
+  # Evaluate term on a fact.
+  # @param [Factbase::Fact] fact The fact
+  # @param [Array<Factbase::Fact>] maps All maps available
+  # @param [Factbase] fb Factbase to use for sub-queries
+  # @return [Object] The result of evaluation
+  def evaluate(fact, maps, fb)
+    assert_args(2)
+    selector = @operands[0]
+    unless selector.is_a?(Factbase::Term) || selector.is_a?(Factbase::TermBase)
+      raise "A term is expected, but '#{selector}' provided"
+    end
+    term = @operands[1]
+    unless term.is_a?(Factbase::Term) || term.is_a?(Factbase::TermBase)
+      raise "A term is expected, but '#{term}' provided"
+    end
+    subset = fb.query(selector, maps).each(fb, fact).to_a
+    term.evaluate(nil, subset, fb)
+  end
+end

data/lib/factbase/terms/and.rb

@@ -5,6 +5,7 @@
 
 require_relative 'base'
 require_relative 'boolean'
+require_relative 'simplified'
 # The 'and' term that represents a logical AND operation between multiple operands.
 class Factbase::And < Factbase::TermBase
   # Constructor.
@@ -25,4 +26,10 @@ class Factbase::And < Factbase::TermBase
     end
     true
   end
+
+  def simplify
+    unique = Factbase::Simplified.new(@operands).unique
+    return unique[0] if unique.size == 1
+    Factbase::Term.new(@op, unique)
+  end
 end

data/lib/factbase/terms/base.rb

@@ -10,8 +10,61 @@
 
 # Base class for all terms.
 class Factbase::TermBase
-  require_relative 'shared'
-  include Factbase::TermShared
+  # Turns it into a string.
+  # @return [String] The string of it
+  def to_s
+    @to_s ||=
+      begin
+        items = []
+        items << @op
+        items +=
+          @operands.map do |o|
+            if o.is_a?(String)
+              "'#{o.gsub("'", "\\\\'").gsub('"', '\\\\"')}'"
+            elsif o.is_a?(Time)
+              o.utc.iso8601
+            else
+              o.to_s
+            end
+          end
+        "(#{items.join(' ')})"
+      end
+  end
 
-  protected :assert_args, :_by_symbol, :_values, :to_s
+  private
+
+  def assert_args(num)
+    c = @operands.size
+    raise "Too many (#{c}) operands for '#{@op}' (#{num} expected)" if c > num
+    raise "Too few (#{c}) operands for '#{@op}' (#{num} expected)" if c < num
+  end
+
+  def _by_symbol(pos, fact)
+    o = @operands[pos]
+    raise "A symbol expected at ##{pos}, but '#{o}' (#{o.class}) provided" unless o.is_a?(Symbol)
+    k = o.to_s
+    fact[k]
+  end
+
+  # @return [Array|nil] Either array of values or NIL
+  def _values(pos, fact, maps, fb)
+    v = @operands[pos]
+    v = v.evaluate(fact, maps, fb) if v.is_a?(Factbase::Term)
+    v = v.evaluate(fact, maps, fb) if v.is_a?(Factbase::TermBase)
+    v = fact[v.to_s] if v.is_a?(Symbol)
+    return v if v.nil?
+    unless v.is_a?(Array)
+      v =
+        if v.respond_to?(:each)
+          v.to_a
+        else
+          [v]
+        end
+    end
+    raise 'Why not array?' unless v.is_a?(Array)
+    unless v.all? { |i| [Float, Integer, String, Time, TrueClass, FalseClass].any? { |t| i.is_a?(t) } }
+      raise 'Wrong type inside'
+    end
+    v
+  end
 end

data/lib/factbase/terms/best.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: Copyright (c) 2024-2025 Yegor Bugayenko
+# SPDX-License-Identifier: MIT
+
+# The 'best' term evaluates the best value for a given key.
+class Factbase::Best
+  def initialize(&block)
+    @criteria = block
+  end
+
+  def evaluate(key, maps)
+    raise "A symbol is expected, but #{key} provided" unless key.is_a?(Symbol)
+    best = nil
+    maps.each do |m|
+      vv = m[key.to_s]
+      next if vv.nil?
+      vv = [vv] unless vv.respond_to?(:to_a)
+      vv.each do |v|
+        best = v if best.nil? || @criteria.call(v, best)
+      end
+    end
+    best
+  end
+end

data/lib/factbase/terms/empty.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: Copyright (c) 2024-2025 Yegor Bugayenko
+# SPDX-License-Identifier: MIT
+
+require_relative 'base'
+
+# The 'empty' term checks for emptiness in the results of a query evaluation.
+class Factbase::Empty < Factbase::TermBase
+  # Constructor.
+  # @param [Array] operands Operands
+  def initialize(operands)
+    super()
+    @operands = operands
+    @op = :empty
+  end
+
+  # Evaluate term on a fact.
+  # @param [Factbase::Fact] fact The fact
+  # @param [Array<Factbase::Fact>] maps All maps available
+  # @param [Factbase] fb Factbase to use for sub-queries
+  # @return [Boolean] The result of the emptiness check
+  def evaluate(fact, maps, fb)
+    assert_args(1)
+    term = @operands[0]
+    unless term.is_a?(Factbase::Term) || term.is_a?(Factbase::TermBase)
+      raise "A term is expected, but '#{term}' provided"
+    end
+    # rubocop:disable Lint/UnreachableLoop
+    fb.query(term, maps).each(fb, fact) do
+      return false
+    end
+    # rubocop:enable Lint/UnreachableLoop
+    true
+  end
+end

data/lib/factbase/terms/max.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: Copyright (c) 2024-2025 Yegor Bugayenko
+# SPDX-License-Identifier: MIT
+
+require_relative '../../factbase'
+require_relative 'best'
+require_relative 'base'
+
+# The 'max' term.
+# This term calculates the max value among the evaluated operands.
+class Factbase::Max < Factbase::TermBase
+  MAX = Factbase::Best.new { |v, b| v > b }
+
+  # Constructor.
+  # @param [Array] operands Operands
+  def initialize(operands)
+    super()
+    @operands = operands
+    @op = :max
+  end
+
+  # Evaluate term on a fact.
+  # @param [Factbase::Fact] _fact The fact
+  # @param [Array<Factbase::Fact>] maps All maps available
+  # @param [Factbase] _fb Factbase to use for sub-queries
+  # @return [Object] The max value among the evaluated operands
+  def evaluate(_fact, maps, _fb)
+    assert_args(1)
+    MAX.evaluate(@operands[0], maps)
+  end
+end

data/lib/factbase/terms/min.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: Copyright (c) 2024-2025 Yegor Bugayenko
+# SPDX-License-Identifier: MIT
+
+require_relative '../../factbase'
+require_relative 'best'
+require_relative 'base'
+
+# The 'min' term.
+# This term calculates the minimum value among the evaluated operands.
+class Factbase::Min < Factbase::TermBase
+  MIN = Factbase::Best.new { |v, b| v < b }
+
+  # Constructor.
+  # @param [Array] operands Operands
+  def initialize(operands)
+    super()
+    @operands = operands
+    @op = :min
+  end
+
+  # Evaluate term on a fact.
+  # @param [Factbase::Fact] _fact The fact
+  # @param [Array<Factbase::Fact>] maps All maps available
+  # @param [Factbase] _fb Factbase to use for sub-queries
+  # @return [Object] The minimum value among the evaluated operands
+  def evaluate(_fact, maps, _fb)
+    assert_args(1)
+    MIN.evaluate(@operands[0], maps)
+  end
+end

data/lib/factbase/terms/nth.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: Copyright (c) 2024-2025 Yegor Bugayenko
+# SPDX-License-Identifier: MIT
+
+require_relative 'base'
+# Represents an 'nth' term in the Factbase.
+# Retrieves the value of a specified key from the nth map.
+class Factbase::Nth < Factbase::TermBase
+  # Constructor.
+  # @param [Array] operands Operands
+  def initialize(operands)
+    super()
+    @operands = operands
+    @op = :nth
+  end
+
+  # Evaluate term on a fact.
+  # @param [Factbase::Fact] _fact The fact
+  # @param [Array<Factbase::Fact>] maps All maps available
+  # @param [Factbase] _fb Factbase to use for sub-queries
+  # @return [Object] The value of the specified key from the nth map
+  def evaluate(_fact, maps, _fb)
+    assert_args(2)
+    pos = @operands[0]
+    raise "An integer is expected, but #{pos} provided" unless pos.is_a?(Integer)
+    k = @operands[1]
+    raise "A symbol is expected, but #{k} provided" unless k.is_a?(Symbol)
+    m = maps[pos]
+    return nil if m.nil?
+    m[k.to_s]
+  end
+end

data/lib/factbase/terms/or.rb

@@ -5,6 +5,7 @@
 
 require_relative 'base'
 require_relative 'boolean'
+require_relative 'simplified'
 # The 'or' term that represents a logical OR operation between multiple operands.
 class Factbase::Or < Factbase::TermBase
   # Constructor.
@@ -25,4 +26,10 @@ class Factbase::Or < Factbase::TermBase
     end
     false
   end
+
+  def simplify
+    unique = Factbase::Simplified.new(@operands).unique
+    return unique[0] if unique.size == 1
+    Factbase::Term.new(@op, unique)
+  end
 end

data/lib/factbase/terms/simplified.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: Copyright (c) 2024-2025 Yegor Bugayenko
+# SPDX-License-Identifier: MIT
+
+require_relative '../../factbase'
+
+# Simplified operands.
+#
+# Author:: Yegor Bugayenko (yegor256@gmail.com)
+# Copyright:: Copyright (c) 2024-2025 Yegor Bugayenko
+# License:: MIT
+class Factbase::Simplified
+  def initialize(operands)
+    @operands = operands
+  end
+
+  # Removes duplicate operands
+  def unique
+    strs = []
+    ops = []
+    @operands.each do |o|
+      o = o.simplify
+      s = o.to_s
+      next if strs.include?(s)
+      strs << s
+      ops << o
+    end
+    ops
+  end
+end

data/lib/factbase/terms/sum.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: Copyright (c) 2024-2025 Yegor Bugayenko
+# SPDX-License-Identifier: MIT
+
+require_relative 'base'
+
+# This class represents a specialized 'sum' term.
+# This term  calculates the sum of values for a specified key.
+class Factbase::Sum < Factbase::TermBase
+  # Constructor.
+  # @param [Array] operands Operands
+  def initialize(operands)
+    super()
+    @operands = operands
+    @op = :sum
+  end
+
+  # Evaluate term on a fact.
+  # @param [Factbase::Fact] _fact The fact
+  # @param [Array<Factbase::Fact>] maps All maps available
+  # @param [Factbase] _fb Factbase to use for sub-queries
+  # @return [Integer] The sum of values for the specified key across all maps
+  def evaluate(_fact, maps, _fb)
+    k = @operands[0]
+    raise "A symbol is expected, but '#{k}' provided" unless k.is_a?(Symbol)
+    sum = 0
+    maps.each do |m|
+      vv = m[k.to_s]
+      next if vv.nil?
+      vv = [vv] unless vv.respond_to?(:to_a)
+      vv.each do |v|
+        sum += v
+      end
+    end
+    sum
+  end
+end

data/lib/factbase/version.rb

@@ -9,5 +9,5 @@
 # License:: MIT
 class Factbase
   # Current version of the gem (changed by .rultor.yml on every release)
-  VERSION = '0.17.0' unless const_defined?(:VERSION)
+  VERSION = '0.18.0' unless const_defined?(:VERSION)
 end

data/lib/factbase.rb

@@ -164,17 +164,8 @@ class Factbase
   #
   # @return [Factbase::Churn] How many facts have been changed (zero if rolled back)
   def txn
-    pairs = {}
-    before =
-      @maps.map do |m|
-        n = m.transform_values(&:dup)
-        # rubocop:disable Lint/HashCompareByIdentity
-        pairs[n.object_id] = m.object_id
-        # rubocop:enable Lint/HashCompareByIdentity
-        n
-      end
-    require_relative 'factbase/taped'
-    taped = Factbase::Taped.new(before)
+    require_relative 'factbase/lazy_taped'
+    taped = Factbase::LazyTaped.new(@maps)
     require_relative 'factbase/churn'
     churn = Factbase::Churn.new
     catch :commit do
@@ -188,30 +179,32 @@ class Factbase
     rescue Factbase::Rollback
       return churn
     end
-    seen = []
-    garbage = []
+    seen = {}.compare_by_identity
+    garbage = {}.compare_by_identity
+    pairs = taped.pairs
     taped.deleted.each do |oid|
-      garbage << pairs[oid]
-      seen << oid
+      original = @maps.find { |m| m.object_id == oid }
+      next if original.nil?
+      garbage[original] = true
       churn.append(0, 1, 0)
     end
     taped.inserted.each do |oid|
-      next if seen.include?(oid)
       b = taped.find_by_object_id(oid)
       next if b.nil?
-      seen << oid
+      next if seen.key?(b)
+      seen[b] = true
       @maps << b
       churn.append(1, 0, 0)
     end
     taped.added.each do |oid|
-      next if seen.include?(oid)
       b = taped.find_by_object_id(oid)
       next if b.nil?
-      garbage << pairs[oid]
+      next if seen.key?(b)
+      garbage[pairs[b]] = true
       @maps << b
       churn.append(0, 0, 1)
     end
-    @maps.delete_if { |m| garbage.include?(m.object_id) } unless garbage.empty?
+    @maps.delete_if { |m| garbage.key?(m) } unless garbage.empty?
     churn
   end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: factbase
 version: !ruby/object:Gem::Version
-  version: 0.17.0
+  version: 0.18.0
 platform: ruby
 authors:
 - Yegor Bugayenko
@@ -195,6 +195,9 @@ files:
 - lib/factbase/indexed/indexed_term.rb
 - lib/factbase/indexed/indexed_unique.rb
 - lib/factbase/inv.rb
+- lib/factbase/lazy_taped.rb
+- lib/factbase/lazy_taped_array.rb
+- lib/factbase/lazy_taped_hash.rb
 - lib/factbase/light.rb
 - lib/factbase/logged.rb
 - lib/factbase/pre.rb
@@ -208,13 +211,14 @@ files:
 - lib/factbase/tee.rb
 - lib/factbase/term.rb
 - lib/factbase/terms/absent.rb
-- lib/factbase/terms/aggregates.rb
+- lib/factbase/terms/agg.rb
 - lib/factbase/terms/always.rb
 - lib/factbase/terms/and.rb
 - lib/factbase/terms/arithmetic.rb
 - lib/factbase/terms/as.rb
 - lib/factbase/terms/assert.rb
 - lib/factbase/terms/base.rb
+- lib/factbase/terms/best.rb
 - lib/factbase/terms/boolean.rb
 - lib/factbase/terms/compare.rb
 - lib/factbase/terms/concat.rb
@@ -222,6 +226,7 @@ files:
 - lib/factbase/terms/defn.rb
 - lib/factbase/terms/div.rb
 - lib/factbase/terms/either.rb
+- lib/factbase/terms/empty.rb
 - lib/factbase/terms/env.rb
 - lib/factbase/terms/eq.rb
 - lib/factbase/terms/exists.rb
@@ -231,23 +236,26 @@ files:
 - lib/factbase/terms/head.rb
 - lib/factbase/terms/inverted.rb
 - lib/factbase/terms/join.rb
-- lib/factbase/terms/logical.rb
 - lib/factbase/terms/lt.rb
 - lib/factbase/terms/lte.rb
 - lib/factbase/terms/many.rb
 - lib/factbase/terms/matches.rb
+- lib/factbase/terms/max.rb
+- lib/factbase/terms/min.rb
 - lib/factbase/terms/minus.rb
 - lib/factbase/terms/never.rb
 - lib/factbase/terms/nil.rb
 - lib/factbase/terms/not.rb
+- lib/factbase/terms/nth.rb
 - lib/factbase/terms/one.rb
 - lib/factbase/terms/or.rb
 - lib/factbase/terms/plus.rb
 - lib/factbase/terms/prev.rb
-- lib/factbase/terms/shared.rb
+- lib/factbase/terms/simplified.rb
 - lib/factbase/terms/size.rb
 - lib/factbase/terms/sorted.rb
 - lib/factbase/terms/sprintf.rb
+- lib/factbase/terms/sum.rb
 - lib/factbase/terms/times.rb
 - lib/factbase/terms/to_float.rb
 - lib/factbase/terms/to_integer.rb

data/lib/factbase/terms/aggregates.rb

@@ -1,86 +0,0 @@
-# frozen_string_literal: true
-
-# SPDX-FileCopyrightText: Copyright (c) 2024-2025 Yegor Bugayenko
-# SPDX-License-Identifier: MIT
-
-require_relative '../../factbase'
-
-# Aggregating terms.
-#
-# Author:: Yegor Bugayenko (yegor256@gmail.com)
-# Copyright:: Copyright (c) 2024-2025 Yegor Bugayenko
-# License:: MIT
-module Factbase::Aggregates
-  def min(_fact, maps, _fb)
-    assert_args(1)
-    _best(maps) { |v, b| v < b }
-  end
-
-  def max(_fact, maps, _fb)
-    assert_args(1)
-    _best(maps) { |v, b| v > b }
-  end
-
-  def nth(_fact, maps, _fb)
-    assert_args(2)
-    pos = @operands[0]
-    raise "An integer is expected, but #{pos} provided" unless pos.is_a?(Integer)
-    k = @operands[1]
-    raise "A symbol is expected, but #{k} provided" unless k.is_a?(Symbol)
-    m = maps[pos]
-    return nil if m.nil?
-    m[k.to_s]
-  end
-
-  def sum(_fact, maps, _fb)
-    k = @operands[0]
-    raise "A symbol is expected, but '#{k}' provided" unless k.is_a?(Symbol)
-    sum = 0
-    maps.each do |m|
-      vv = m[k.to_s]
-      next if vv.nil?
-      vv = [vv] unless vv.respond_to?(:to_a)
-      vv.each do |v|
-        sum += v
-      end
-    end
-    sum
-  end
-
-  def agg(fact, maps, fb)
-    assert_args(2)
-    selector = @operands[0]
-    raise "A term is expected, but '#{selector}' provided" unless selector.is_a?(Factbase::Term)
-    term = @operands[1]
-    raise "A term is expected, but '#{term}' provided" unless term.is_a?(Factbase::Term)
-    subset = fb.query(selector, maps).each(fb, fact).to_a
-    term.evaluate(nil, subset, fb)
-  end
-
-  def empty(fact, maps, fb)
-    assert_args(1)
-    term = @operands[0]
-    raise "A term is expected, but '#{term}' provided" unless term.is_a?(Factbase::Term)
-    # rubocop:disable Lint/UnreachableLoop
-    fb.query(term, maps).each(fb, fact) do
-      return false
-    end
-    # rubocop:enable Lint/UnreachableLoop
-    true
-  end
-
-  def _best(maps)
-    k = @operands[0]
-    raise "A symbol is expected, but #{k} provided" unless k.is_a?(Symbol)
-    best = nil
-    maps.each do |m|
-      vv = m[k.to_s]
-      next if vv.nil?
-      vv = [vv] unless vv.respond_to?(:to_a)
-      vv.each do |v|
-        best = v if best.nil? || yield(v, best)
-      end
-    end
-    best
-  end
-end

data/lib/factbase/terms/logical.rb

@@ -1,41 +0,0 @@
-# frozen_string_literal: true
-
-# SPDX-FileCopyrightText: Copyright (c) 2024-2025 Yegor Bugayenko
-# SPDX-License-Identifier: MIT
-
-require_relative '../../factbase'
-
-# Logical terms.
-#
-# Author:: Yegor Bugayenko (yegor256@gmail.com)
-# Copyright:: Copyright (c) 2024-2025 Yegor Bugayenko
-# License:: MIT
-module Factbase::Logical
-  # Simplifies AND or OR expressions by removing duplicates
-  # @return [Factbase::Term] Simplified term
-  def and_or_simplify
-    strs = []
-    ops = []
-    @operands.each do |o|
-      o = o.simplify
-      s = o.to_s
-      next if strs.include?(s)
-      strs << s
-      ops << o
-    end
-    return ops[0] if ops.size == 1
-    self.class.new(@op, ops)
-  end
-
-  # Simplifies AND expressions by removing duplicates
-  # @return [Factbase::Term] Simplified term
-  def and_simplify
-    and_or_simplify
-  end
-
-  # Simplifies OR expressions by removing duplicates
-  # @return [Factbase::Term] Simplified term
-  def or_simplify
-    and_or_simplify
-  end
-end

data/lib/factbase/terms/shared.rb

@@ -1,69 +0,0 @@
-# frozen_string_literal: true
-
-# SPDX-FileCopyrightText: Copyright (c) 2024-2025 Yegor Bugayenko
-# SPDX-License-Identifier: MIT
-
-# This module provides shared methods for Factbase terms, including argument validation,
-# symbol-based lookups, and handling of operand values.
-# @todo #302:30min Remove this module and move its methods to Factbase::TermBase.
-#  Currently, we use it because we are required to inject all thesse methods into Factbase::Term.
-#  When all the terms will inherit from Factbase::TermBase, we can remove this module.
-module Factbase::TermShared
-  # Turns it into a string.
-  # @return [String] The string of it
-  def to_s
-    @to_s ||=
-      begin
-        items = []
-        items << @op
-        items +=
-          @operands.map do |o|
-            if o.is_a?(String)
-              "'#{o.gsub("'", "\\\\'").gsub('"', '\\\\"')}'"
-            elsif o.is_a?(Time)
-              o.utc.iso8601
-            else
-              o.to_s
-            end
-          end
-        "(#{items.join(' ')})"
-      end
-  end
-
-  private
-
-  def assert_args(num)
-    c = @operands.size
-    raise "Too many (#{c}) operands for '#{@op}' (#{num} expected)" if c > num
-    raise "Too few (#{c}) operands for '#{@op}' (#{num} expected)" if c < num
-  end
-
-  def _by_symbol(pos, fact)
-    o = @operands[pos]
-    raise "A symbol expected at ##{pos}, but '#{o}' (#{o.class}) provided" unless o.is_a?(Symbol)
-    k = o.to_s
-    fact[k]
-  end
-
-  # @return [Array|nil] Either array of values or NIL
-  def _values(pos, fact, maps, fb)
-    v = @operands[pos]
-    v = v.evaluate(fact, maps, fb) if v.is_a?(Factbase::Term)
-    v = v.evaluate(fact, maps, fb) if v.is_a?(Factbase::TermBase)
-    v = fact[v.to_s] if v.is_a?(Symbol)
-    return v if v.nil?
-    unless v.is_a?(Array)
-      v =
-        if v.respond_to?(:each)
-          v.to_a
-        else
-          [v]
-        end
-    end
-    raise 'Why not array?' unless v.is_a?(Array)
-    unless v.all? { |i| [Float, Integer, String, Time, TrueClass, FalseClass].any? { |t| i.is_a?(t) } }
-      raise 'Wrong type inside'
-    end
-    v
-  end
-end