factbase 0.4.0 → 0.5.0

data/benchmarks/simple.rb

@@ -0,0 +1,96 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Copyright (c) 2024-2025 Yegor Bugayenko
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the 'Software'), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+require 'benchmark'
+require 'time'
+require_relative '../lib/factbase'
+
+def insert(fb, total)
+  time =
+    Benchmark.measure do
+      total.times do |i|
+        fact = fb.insert
+        fact.id = i
+        fact.title = "Object Thinking #{i}"
+        fact.time = Time.now.iso8601
+        fact.cost = rand(1..100)
+        fact.foo = rand(0.0..100.0).round(3)
+        fact.bar = rand(100..300)
+        fact.seenBy = "User#{i}" if i.even?
+        fact.zzz = "Extra#{i}" if (i % 10).zero?
+      end
+    end
+  {
+    title: '`fb.insert()`',
+    time: time.real,
+    details: "Inserted #{total} facts"
+  }
+end
+
+def query(fb, query)
+  total = 0
+  runs = 10
+  time =
+    Benchmark.measure do
+      runs.times do
+        total = fb.query(query).each.to_a.size
+      end
+    end
+  {
+    title: "`#{query}`",
+    time: (time.real / runs).round(6),
+    details: "Found #{total} fact(s)"
+  }
+end
+
+def impex(fb)
+  size = 0
+  time =
+    Benchmark.measure do
+      bin = fb.export
+      size = bin.size
+      fb2 = Factbase.new
+      fb2.import(bin)
+    end
+  {
+    title: '`.export()` + `.import()`',
+    time: time.real,
+    details: "#{size} bytes"
+  }
+end
+
+fb = Factbase.new
+rows = [
+  insert(fb, 100_000),
+  query(fb, '(gt time \'2024-03-23T03:21:43Z\')'),
+  query(fb, '(gt cost 50)'),
+  query(fb, '(eq title \'Object Thinking 5000\')'),
+  query(fb, '(and (eq foo 42.998) (or (gt bar 200) (absent zzz)))'),
+  query(fb, '(eq id (agg (always) (max id)))'),
+  query(fb, '(join "c<=cost,b<=bar" (eq id (agg (always) (max id))))'),
+  impex(fb)
+].map { |r| "| #{r[:title]} | #{format('%0.3f', r[:time])} | #{r[:details]} |" }
+
+puts '| Action | Seconds | Details |'
+puts '| --- | --: | --- |'
+rows.each { |row| puts row }

data/factbase.gemspec

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# Copyright (c) 2024 Yegor Bugayenko
+# Copyright (c) 2024-2025 Yegor Bugayenko
 #
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the 'Software'), to deal

data/lib/factbase/accum.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# Copyright (c) 2024 Yegor Bugayenko
+# Copyright (c) 2024-2025 Yegor Bugayenko
 #
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the 'Software'), to deal
@@ -26,7 +26,7 @@ require_relative '../factbase'
 # Accumulator of props, a decorator of +Factbase::Fact+.
 #
 # Author:: Yegor Bugayenko (yegor256@gmail.com)
-# Copyright:: Copyright (c) 2024 Yegor Bugayenko
+# Copyright:: Copyright (c) 2024-2025 Yegor Bugayenko
 # License:: MIT
 class Factbase::Accum
   # Ctor.

data/lib/factbase/fact.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# Copyright (c) 2024 Yegor Bugayenko
+# Copyright (c) 2024-2025 Yegor Bugayenko
 #
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the 'Software'), to deal
@@ -33,20 +33,21 @@ require_relative '../factbase'
 # fact with a single key/value pair inside:
 #
 #  require 'factbase/fact'
-#  f = Factbase::Fact.new(Mutex.new, { 'foo' => [42, 256, 'Hello, world!'] })
+#  f = Factbase::Fact.new(Factbase.new, Mutex.new, { 'foo' => [42, 256, 'Hello, world!'] })
 #  assert_equal(42, f.foo)
 #
 # A fact is basically a key/value hash map, where values are non-empty
 # sets of values.
 #
 # Author:: Yegor Bugayenko (yegor256@gmail.com)
-# Copyright:: Copyright (c) 2024 Yegor Bugayenko
+# Copyright:: Copyright (c) 2024-2025 Yegor Bugayenko
 # License:: MIT
 class Factbase::Fact
   # Ctor.
   # @param [Mutex] mutex A mutex to use for maps synchronization
   # @param [Hash] map A map of key/value pairs
-  def initialize(mutex, map)
+  def initialize(fb, mutex, map)
+    @fb = fb
     @mutex = mutex
     @map = map
   end
@@ -80,6 +81,7 @@ class Factbase::Fact
         @map[kk] << v
         @map[kk].uniq!
       end
+      @fb.cache.clear
       nil
     elsif k == '[]'
       @map[args[1].to_s]

data/lib/factbase/flatten.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# Copyright (c) 2024 Yegor Bugayenko
+# Copyright (c) 2024-2025 Yegor Bugayenko
 #
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the 'Software'), to deal
@@ -25,7 +25,7 @@ require_relative '../factbase'
 # Make maps suitable for printing.
 #
 # Author:: Yegor Bugayenko (yegor256@gmail.com)
-# Copyright:: Copyright (c) 2024 Yegor Bugayenko
+# Copyright:: Copyright (c) 2024-2025 Yegor Bugayenko
 # License:: MIT
 class Factbase::Flatten
   # Constructor.

data/lib/factbase/inv.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# Copyright (c) 2024 Yegor Bugayenko
+# Copyright (c) 2024-2025 Yegor Bugayenko
 #
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the 'Software'), to deal
@@ -26,7 +26,7 @@ require_relative '../factbase'
 
 # A decorator of a Factbase, that checks invariants on every set.
 # Author:: Yegor Bugayenko (yegor256@gmail.com)
-# Copyright:: Copyright (c) 2024 Yegor Bugayenko
+# Copyright:: Copyright (c) 2024-2025 Yegor Bugayenko
 # License:: MIT
 class Factbase::Inv
   decoor(:fb)

data/lib/factbase/looged.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# Copyright (c) 2024 Yegor Bugayenko
+# Copyright (c) 2024-2025 Yegor Bugayenko
 #
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the 'Software'), to deal
@@ -29,7 +29,7 @@ require_relative 'syntax'
 
 # A decorator of a Factbase, that logs all operations.
 # Author:: Yegor Bugayenko (yegor256@gmail.com)
-# Copyright:: Copyright (c) 2024 Yegor Bugayenko
+# Copyright:: Copyright (c) 2024-2025 Yegor Bugayenko
 # License:: MIT
 class Factbase::Looged
   def initialize(fb, loog)
@@ -46,8 +46,9 @@ class Factbase::Looged
   end
 
   def insert
+    start = Time.now
     f = @fb.insert
-    @loog.debug("Inserted new fact ##{@fb.size}")
+    @loog.debug("Inserted new fact ##{@fb.size} in #{start.ago}")
     Fact.new(f, @loog)
   end
 
@@ -119,7 +120,7 @@ class Factbase::Looged
     end
 
     def one(params = {})
-      q = Factbase::Syntax.new(@expr).to_term.to_s
+      q = Factbase::Syntax.new(@fb, @expr).to_term.to_s
       r = nil
       tail =
         Factbase::Looged.elapsed do
@@ -134,7 +135,7 @@ class Factbase::Looged
     end
 
     def each(params = {}, &)
-      q = Factbase::Syntax.new(@expr).to_term.to_s
+      q = Factbase::Syntax.new(@fb, @expr).to_term.to_s
       if block_given?
         r = nil
         tail =

data/lib/factbase/pre.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# Copyright (c) 2024 Yegor Bugayenko
+# Copyright (c) 2024-2025 Yegor Bugayenko
 #
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the 'Software'), to deal
@@ -37,7 +37,7 @@ require_relative '../factbase'
 # one is the fact just inserted.
 #
 # Author:: Yegor Bugayenko (yegor256@gmail.com)
-# Copyright:: Copyright (c) 2024 Yegor Bugayenko
+# Copyright:: Copyright (c) 2024-2025 Yegor Bugayenko
 # License:: MIT
 class Factbase::Pre
   decoor(:fb)

data/lib/factbase/query.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# Copyright (c) 2024 Yegor Bugayenko
+# Copyright (c) 2024-2025 Yegor Bugayenko
 #
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the 'Software'), to deal
@@ -34,30 +34,38 @@ require_relative 'tee'
 # It is NOT thread-safe!
 #
 # Author:: Yegor Bugayenko (yegor256@gmail.com)
-# Copyright:: Copyright (c) 2024 Yegor Bugayenko
+# Copyright:: Copyright (c) 2024-2025 Yegor Bugayenko
 # License:: MIT
 class Factbase::Query
   # Constructor.
+  # @param [Factbase] fb Factbase
   # @param [Array<Fact>] maps Array of facts to start with
   # @param [Mutex] mutex Mutex to sync all modifications to the +maps+
   # @param [String] query The query as a string
-  def initialize(maps, mutex, query)
+  def initialize(fb, maps, mutex, query)
+    @fb = fb
     @maps = maps
     @mutex = mutex
     @query = query
   end
 
+  # Print it as a string.
+  # @return [String] The query as a string
+  def to_s
+    @query.to_s
+  end
+
   # Iterate facts one by one.
   # @param [Hash] params Optional params accessible in the query via the "$" symbol
   # @yield [Fact] Facts one-by-one
   # @return [Integer] Total number of facts yielded
   def each(params = {})
     return to_enum(__method__, params) unless block_given?
-    term = Factbase::Syntax.new(@query).to_term
+    term = Factbase::Syntax.new(@fb, @query).to_term
     yielded = 0
     @maps.each do |m|
       extras = {}
-      f = Factbase::Fact.new(@mutex, m)
+      f = Factbase::Fact.new(@fb, @mutex, m)
       params = params.transform_keys(&:to_s) if params.is_a?(Hash)
       f = Factbase::Tee.new(f, params)
       a = Factbase::Accum.new(f, extras, false)
@@ -76,7 +84,7 @@ class Factbase::Query
   # @param [Hash] params Optional params accessible in the query via the "$" symbol
   # @return The value evaluated
   def one(params = {})
-    term = Factbase::Syntax.new(@query).to_term
+    term = Factbase::Syntax.new(@fb, @query).to_term
     params = params.transform_keys(&:to_s) if params.is_a?(Hash)
     r = term.evaluate(Factbase::Tee.new(nil, params), @maps)
     unless %w[String Integer Float Time Array NilClass].include?(r.class.to_s)
@@ -88,11 +96,11 @@ class Factbase::Query
   # Delete all facts that match the query.
   # @return [Integer] Total number of facts deleted
   def delete!
-    term = Factbase::Syntax.new(@query).to_term
+    term = Factbase::Syntax.new(@fb, @query).to_term
     deleted = 0
     @mutex.synchronize do
       @maps.delete_if do |m|
-        f = Factbase::Fact.new(@mutex, m)
+        f = Factbase::Fact.new(@fb, @mutex, m)
         if term.evaluate(f, @maps)
           deleted += 1
           true

data/lib/factbase/query_once.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+# Copyright (c) 2024-2025 Yegor Bugayenko
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the 'Software'), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+require_relative '../factbase'
+
+# Query with a cache, a decorator of another query.
+#
+# It is NOT thread-safe!
+#
+# Author:: Yegor Bugayenko (yegor256@gmail.com)
+# Copyright:: Copyright (c) 2024-2025 Yegor Bugayenko
+# License:: MIT
+class Factbase::QueryOnce
+  # Constructor.
+  # @param [Factbase] fb Factbase
+  # @param [Factbase::Query] query Original query
+  # @param [Array<Hash>] maps Where to search
+  def initialize(fb, query, maps)
+    @fb = fb
+    @query = query
+    @maps = maps
+  end
+
+  # Iterate facts one by one.
+  # @param [Hash] params Optional params accessible in the query via the "$" symbol
+  # @yield [Fact] Facts one-by-one
+  # @return [Integer] Total number of facts yielded
+  def each(params = {}, &)
+    unless block_given?
+      return to_enum(__method__, params) if Factbase::Syntax.new(@fb, @query).to_term.abstract?
+      key = [@query.to_s, @maps.object_id]
+      before = @fb.cache[key]
+      @fb.cache[key] = to_enum(__method__, params).to_a if before.nil?
+      return @fb.cache[key]
+    end
+    @query.each(params, &)
+  end
+
+  # Read a single value.
+  # @param [Hash] params Optional params accessible in the query via the "$" symbol
+  # @return The value evaluated
+  def one(params = {})
+    @query.one(params)
+  end
+
+  # Delete all facts that match the query.
+  # @return [Integer] Total number of facts deleted
+  def delete!
+    @fb.cache.clear
+    @query.delete!
+  end
+end

data/lib/factbase/rules.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# Copyright (c) 2024 Yegor Bugayenko
+# Copyright (c) 2024-2025 Yegor Bugayenko
 #
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the 'Software'), to deal
@@ -38,7 +38,7 @@ require_relative '../factbase/syntax'
 #  end # Runtime exception here (transaction won't commit)
 #
 # Author:: Yegor Bugayenko (yegor256@gmail.com)
-# Copyright:: Copyright (c) 2024 Yegor Bugayenko
+# Copyright:: Copyright (c) 2024-2025 Yegor Bugayenko
 # License:: MIT
 class Factbase::Rules
   decoor(:fb)
@@ -134,7 +134,7 @@ class Factbase::Rules
     end
 
     def it(fact)
-      return if Factbase::Syntax.new(@expr).to_term.evaluate(fact, [])
+      return if Factbase::Syntax.new(Factbase.new, @expr).to_term.evaluate(fact, [])
       e = "#{@expr[0..32]}..." if @expr.length > 32
       raise "The fact doesn't match the #{e.inspect} rule: #{fact}"
     end

data/lib/factbase/syntax.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# Copyright (c) 2024 Yegor Bugayenko
+# Copyright (c) 2024-2025 Yegor Bugayenko
 #
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the 'Software'), to deal
@@ -24,6 +24,7 @@ require 'time'
 require_relative '../factbase'
 require_relative 'fact'
 require_relative 'term'
+require_relative 'term_once'
 
 # Syntax.
 #
@@ -34,19 +35,21 @@ require_relative 'term'
 # every term it meets in the query:
 #
 #  require 'factbase/syntax'
-#  t = Factbase::Syntax.new('(hello world)', MyTerm).to_term
+#  t = Factbase::Syntax.new(Factbase.new, '(hello world)', MyTerm).to_term
 #
 # The +MyTerm+ class should have a constructor with two arguments:
 # the operator and the list of operands (Array).
 #
 # Author:: Yegor Bugayenko (yegor256@gmail.com)
-# Copyright:: Copyright (c) 2024 Yegor Bugayenko
+# Copyright:: Copyright (c) 2024-2025 Yegor Bugayenko
 # License:: MIT
 class Factbase::Syntax
   # Ctor.
+  # @param [Factbase] fb Factbase
   # @param [String] query The query, for example "(eq id 42)"
   # @param [Class] term The class to instantiate to make every term
-  def initialize(query, term: Factbase::Term)
+  def initialize(fb, query, term: Factbase::Term)
+    @fb = fb
     @query = query
     @term = term
   end
@@ -61,7 +64,7 @@ class Factbase::Syntax
         t
       end
   rescue StandardError => e
-    err = "#{e.message} in \"#{@query}\""
+    err = "#{e.message} (#{e.backtrace[1]}) in \"#{@query}\""
     err = "#{err}, tokens: #{@tokens}" unless @tokens.nil?
     raise err
   end
@@ -106,20 +109,22 @@ class Factbase::Syntax
       operands << operand
       break if tokens[at] == :close
     end
-    [@term.new(op, operands), at + 1]
+    [Factbase::TermOnce.new(@term.new(@fb, op, operands), @fb.cache), at + 1]
   end
 
   # Turns a query into an array of tokens.
   def to_tokens
     list = []
     acc = ''
+    quotes = ['\'', '"']
+    spaces = [' ', ')']
     string = false
     comment = false
     @query.to_s.chars.each do |c|
       comment = true if !string && c == '#'
       comment = false if comment && c == "\n"
       next if comment
-      if ['\'', '"'].include?(c)
+      if quotes.include?(c)
         if string && acc[acc.length - 1] == '\\'
           acc = acc[0..-2]
         else
@@ -130,7 +135,7 @@ class Factbase::Syntax
         acc += c
         next
       end
-      if !acc.empty? && [' ', ')'].include?(c)
+      if !acc.empty? && spaces.include?(c)
         list << acc
         acc = ''
       end

data/lib/factbase/tee.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# Copyright (c) 2024 Yegor Bugayenko
+# Copyright (c) 2024-2025 Yegor Bugayenko
 #
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the 'Software'), to deal
@@ -26,7 +26,7 @@ require_relative '../factbase'
 # Tee of two facts.
 #
 # Author:: Yegor Bugayenko (yegor256@gmail.com)
-# Copyright:: Copyright (c) 2024 Yegor Bugayenko
+# Copyright:: Copyright (c) 2024-2025 Yegor Bugayenko
 # License:: MIT
 class Factbase::Tee
   # Ctor.

data/lib/factbase/term.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# Copyright (c) 2024 Yegor Bugayenko
+# Copyright (c) 2024-2025 Yegor Bugayenko
 #
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the 'Software'), to deal
@@ -34,8 +34,8 @@ require_relative 'tee'
 #
 #  require 'factbase/fact'
 #  require 'factbase/term'
-#  f = Factbase::Fact.new(Mutex.new, { 'foo' => [42, 256, 'Hello, world!'] })
-#  t = Factbase::Term.new(:lt, [:foo, 50])
+#  f = Factbase::Fact.new(Factbase.new, Mutex.new, { 'foo' => [42, 256, 'Hello, world!'] })
+#  t = Factbase::Term.new(Factbase.new, :lt, [:foo, 50])
 #  assert(t.evaluate(f))
 #
 # The design of this class may look ugly, since it has a large number of
@@ -48,7 +48,7 @@ require_relative 'tee'
 # and currently we implement most of them.
 #
 # Author:: Yegor Bugayenko (yegor256@gmail.com)
-# Copyright:: Copyright (c) 2024 Yegor Bugayenko
+# Copyright:: Copyright (c) 2024-2025 Yegor Bugayenko
 # License:: MIT
 class Factbase::Term
   attr_reader :op, :operands
@@ -87,9 +87,11 @@ class Factbase::Term
   include Factbase::Term::Debug
 
   # Ctor.
+  # @param [Factbase] fb Factbase
   # @param [Symbol] operator Operator
   # @param [Array] operands Operands
-  def initialize(operator, operands)
+  def initialize(fb, operator, operands)
+    @fb = fb
     @op = operator
     @operands = operands
   end
@@ -117,6 +119,32 @@ class Factbase::Term
     end
   end
 
+  # Does it have any dependencies on a fact?
+  #
+  # If a term is static, it will return the same value for +evaluate+,
+  # no matter what is the fact given.
+  #
+  # @return [Boolean] TRUE if static
+  def static?
+    return true if @op == :agg
+    @operands.each do |o|
+      return false if o.is_a?(Factbase::Term) && !o.static?
+      return false if o.is_a?(Symbol) && !o.to_s.start_with?('$')
+    end
+    true
+  end
+
+  # Does it have any variables (+$foo+, for example) inside?
+  #
+  # @return [Boolean] TRUE if abstract
+  def abstract?
+    @operands.each do |o|
+      return true if o.is_a?(Factbase::Term) && o.abstract?
+      return true if o.is_a?(Symbol) && o.to_s.start_with?('$')
+    end
+    false
+  end
+
   # Turns it into a string.
   # @return [String] The string of it
   def to_s

data/lib/factbase/term_once.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+# Copyright (c) 2024-2025 Yegor Bugayenko
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the 'Software'), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+require_relative '../factbase'
+
+# Term with a cache, a decorator of another term.
+#
+# It is NOT thread-safe!
+#
+# Author:: Yegor Bugayenko (yegor256@gmail.com)
+# Copyright:: Copyright (c) 2024-2025 Yegor Bugayenko
+# License:: MIT
+class Factbase::TermOnce < Factbase::Term
+  # Constructor.
+  # @param [Factbase::Term] term Original term
+  # @param [Hash] cache The cache
+  def initialize(term, cache)
+    super(nil, nil, nil) # just to please Rubocop
+    @term = term
+    @cache = cache
+    @text = @term.to_s
+    @cacheable = @term.static? && !@term.abstract?
+  end
+
+  # Does it match the fact?
+  # @param [Factbase::Fact] fact The fact
+  # @param [Array<Factbase::Fact>] maps All maps available
+  # @return [bool] TRUE if matches
+  def evaluate(fact, maps)
+    return @term.evaluate(fact, maps) unless @cacheable
+    key = [@text, maps.object_id]
+    before = @cache[key]
+    @cache[key] = @term.evaluate(nil, maps) if before.nil?
+    @cache[key]
+  end
+
+  # Simplify it if possible.
+  # @return [Factbase::Term] New term or itself
+  def simplify
+    @term.simplify
+  end
+
+  # Does it have any dependencies on a fact?
+  #
+  # If a term is static, it will return the same value for +evaluate+,
+  # no matter what is the fact given.
+  #
+  # @return [Boolean] TRUE if static
+  def static?
+    @term.static?
+  end
+
+  # Does it have any variables (+$foo+, for example) inside?
+  #
+  # @return [Boolean] TRUE if abstract
+  def abstract?
+    @term.abstract?
+  end
+
+  # Turns it into a string.
+  # @return [String] The string of it
+  def to_s
+    @term.to_s
+  end
+end