factbase 0.8.0 → 0.9.1

data/lib/factbase/fact.rb

@@ -10,28 +10,27 @@ require_relative '../factbase'
 
 # A single fact in a factbase.
 #
-# This is an internal class, it is not supposed to be instantiated directly,
-# by the +Factbase+ class.
+# This is an internal class, it is supposed to be instantiated only by the
+# +Factbase+ class.
 # However, it is possible to use it for testing directly, for example to make a
 # fact with a single key/value pair inside:
 #
 #  require 'factbase/fact'
-#  f = Factbase::Fact.new(Factbase.new, Mutex.new, { 'foo' => [42, 256, 'Hello, world!'] })
+#  f = Factbase::Fact.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.
 #
+# It is NOT thread-safe!
+#
 # Author:: Yegor Bugayenko (yegor256@gmail.com)
 # 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(fb, mutex, map)
-    @fb = fb
-    @mutex = mutex
+  def initialize(map)
     @map = map
   end
 
@@ -48,6 +47,10 @@ class Factbase::Fact
   end
 
   # When a method is missing, this method is called.
+  # Method missing handler for dynamic property access and setting
+  # @param [Symbol] method The method name being called
+  # @param [Array] args Method arguments
+  # @return [Object] The value retrieved or nil if setting a value
   others do |*args|
     k = args[0].to_s
     if k.end_with?('=')
@@ -59,12 +62,9 @@ class Factbase::Fact
       raise "The value of '#{kk}' can't be empty" if v == ''
       raise "The type '#{v.class}' of '#{kk}' is not allowed" unless [String, Integer, Float, Time].include?(v.class)
       v = v.utc if v.is_a?(Time)
-      @mutex.synchronize do
-        @map[kk] = [] if @map[kk].nil?
-        @map[kk] << v
-        @map[kk].uniq!
-      end
-      @fb.cache.clear
+      @map[kk] = [] if @map[kk].nil?
+      @map[kk] << v
+      @map[kk].uniq!
       nil
     elsif k == '[]'
       @map[args[1].to_s]

data/lib/factbase/indexed/indexed_fact.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: Copyright (c) 2024-2025 Yegor Bugayenko
+# SPDX-License-Identifier: MIT
+
+require 'others'
+require_relative '../../factbase'
+
+# A single fact in a factbase, which is sentitive to changes.
+#
+# Author:: Yegor Bugayenko (yegor256@gmail.com)
+# Copyright:: Copyright (c) 2024-2025 Yegor Bugayenko
+# License:: MIT
+class Factbase::IndexedFact
+  # Ctor.
+  # @param [Factbase::Fact] origin The original fact
+  # @param [Hash] idx The index
+  def initialize(origin, idx)
+    @origin = origin
+    @idx = idx
+  end
+
+  # When a method is missing, this method is called.
+  others do |*args|
+    @idx.clear if args[0].to_s.end_with?('=')
+    @origin.send(*args)
+  end
+end

data/lib/factbase/indexed/indexed_factbase.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: Copyright (c) 2024-2025 Yegor Bugayenko
+# SPDX-License-Identifier: MIT
+
+require 'decoor'
+require_relative '../../factbase'
+require_relative '../../factbase/syntax'
+require_relative 'indexed_fact'
+require_relative 'indexed_query'
+require_relative 'indexed_term'
+
+# A factbase with an index.
+#
+# Author:: Yegor Bugayenko (yegor256@gmail.com)
+# Copyright:: Copyright (c) 2024-2025 Yegor Bugayenko
+# License:: MIT
+class Factbase::IndexedFactbase
+  decoor(:origin)
+
+  # Constructor.
+  # @param [Factbase] origin Original factbase to decorate
+  # @param [Hash] idx Index to use
+  def initialize(origin, idx = {})
+    raise 'Wront type of original' unless origin.respond_to?(:query)
+    @origin = origin
+    raise 'Wront type of index' unless idx.is_a?(Hash)
+    @idx = idx
+  end
+
+  # Insert a new fact and return it.
+  # @return [Factbase::Fact] The fact just inserted
+  def insert
+    @idx.clear
+    Factbase::IndexedFact.new(@origin.insert, @idx)
+  end
+
+  # Convert a query to a term.
+  # @param [String] query The query to convert
+  # @return [Factbase::Term] The term
+  def to_term(query)
+    t = @origin.to_term(query)
+    t.redress!(Factbase::IndexedTerm, idx: @idx)
+    t
+  end
+
+  # Create a query capable of iterating.
+  # @param [String] term The term to use
+  # @param [Array<Hash>] maps Possible maps to use
+  def query(term, maps = nil)
+    term = to_term(term) if term.is_a?(String)
+    q = @origin.query(term, maps)
+    q = Factbase::IndexedQuery.new(q, @idx, self) if term.abstract?
+    q
+  end
+
+  # 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
+  end
+end

data/lib/factbase/indexed/indexed_query.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: Copyright (c) 2024-2025 Yegor Bugayenko
+# SPDX-License-Identifier: MIT
+
+require_relative '../../factbase'
+require_relative 'indexed_fact'
+
+# Query with an index, a decorator of another query.
+#
+# Author:: Yegor Bugayenko (yegor256@gmail.com)
+# Copyright:: Copyright (c) 2024-2025 Yegor Bugayenko
+# License:: MIT
+class Factbase::IndexedQuery
+  # Constructor.
+  # @param [Factbase::Query] origin Original query
+  # @param [Hash] idx The index
+  def initialize(origin, idx, fb)
+    @origin = origin
+    @idx = idx
+    @fb = fb
+  end
+
+  # Print it as a string.
+  # @return [String] The query as a string
+  def to_s
+    @origin.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(fb = @fb, params = {})
+    return to_enum(__method__, fb, params) unless block_given?
+    @origin.each(fb, params) do |f|
+      yield Factbase::IndexedFact.new(f, @idx)
+    end
+  end
+
+  # Read a single value.
+  # @param [Factbase] fb The factbase
+  # @param [Hash] params Optional params accessible in the query via the "$" symbol
+  # @return [String|Integer|Float|Time|Array|NilClass] The value evaluated
+  def one(fb = @fb, params = nil)
+    @origin.one(fb, params)
+  end
+
+  # Delete all facts that match the query.
+  # @param [Factbase] fb The factbase
+  # @return [Integer] Total number of facts deleted
+  def delete!(fb = @fb)
+    @idx.clear
+    @origin.delete!(fb)
+  end
+end

data/lib/factbase/indexed/indexed_term.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: Copyright (c) 2024-2025 Yegor Bugayenko
+# SPDX-License-Identifier: MIT
+
+require_relative '../../factbase'
+
+# Term with an index.
+#
+# Author:: Yegor Bugayenko (yegor256@gmail.com)
+# Copyright:: Copyright (c) 2024-2025 Yegor Bugayenko
+# License:: MIT
+module Factbase::IndexedTerm
+  def predict(maps, params)
+    case @op
+    when :eq
+      if @operands[0].is_a?(Symbol) && _scalar?(@operands[1])
+        key = [maps.object_id, @operands[0], @op]
+        if @idx[key].nil?
+          @idx[key] = {}
+          maps.to_a.each do |m|
+            m[@operands[0].to_s]&.each do |v|
+              @idx[key][v] = [] if @idx[key][v].nil?
+              @idx[key][v].append(m)
+            end
+          end
+        end
+        vv =
+          if @operands[1].is_a?(Symbol)
+            sym = @operands[1].to_s.gsub(/^\$/, '')
+            params[sym] || []
+          else
+            [@operands[1]]
+          end
+        vv.map { |v| @idx[key][v] || [] }.reduce(&:|)
+      else
+        maps.to_a
+      end
+    when :and
+      parts = @operands.map { |o| o.predict(maps, params) }
+      if parts.include?(nil)
+        maps
+      else
+        parts.reduce(&:&)
+      end
+    when :or
+      @operands.map { |o| o.predict(maps, params) }.reduce(&:|)
+    when :join, :as
+      nil
+    else
+      maps.to_a
+    end
+  end
+
+  private
+
+  def _scalar?(item)
+    item.is_a?(String) || item.is_a?(Time) || item.is_a?(Integer) || item.is_a?(Float) || item.is_a?(Symbol)
+  end
+end

data/lib/factbase/inv.rb

@@ -8,6 +8,17 @@ require 'decoor'
 require_relative '../factbase'
 
 # A decorator of a Factbase, that checks invariants on every set.
+#
+# For example, you can use this decorator if you want to check that every
+# fact has +when+:
+#
+#  fb = Factbase::Inv.new(Factbase.new) do |f, fbt|
+#    assert !f['when'].nil?
+#  end
+#
+# The second argument passed to the block is the factbase, while the first
+# one is the fact just touched.
+#
 # Author:: Yegor Bugayenko (yegor256@gmail.com)
 # Copyright:: Copyright (c) 2024-2025 Yegor Bugayenko
 # License:: MIT
@@ -23,8 +34,8 @@ class Factbase::Inv
     Fact.new(@fb.insert, @block)
   end
 
-  def query(query)
-    Query.new(@fb.query(query), @block)
+  def query(query, maps = nil)
+    Query.new(@fb.query(query, maps), @block, self)
   end
 
   def txn
@@ -65,14 +76,15 @@ class Factbase::Inv
   class Query
     decoor(:query)
 
-    def initialize(query, block)
+    def initialize(query, block, fb)
       @query = query
       @block = block
+      @fb = fb
     end
 
-    def each
-      return to_enum(__method__) unless block_given?
-      @query.each do |f|
+    def each(fb = @fb, params = {})
+      return to_enum(__method__, fb, params) unless block_given?
+      @query.each(fb, params) do |f|
         yield Fact.new(f, @block)
       end
     end

data/lib/factbase/light.rb

@@ -11,11 +11,8 @@ require_relative '../factbase'
 # Copyright:: Copyright (c) 2024-2025 Yegor Bugayenko
 # License:: MIT
 class Factbase::Light
-  attr_reader :cache
-
-  def initialize(fb, cache)
+  def initialize(fb)
     @fb = fb
-    @cache = cache
   end
 
   def size
@@ -26,7 +23,11 @@ class Factbase::Light
     @fb.insert
   end
 
-  def query(query)
-    @fb.query(query)
+  def to_term(query)
+    @fb.to_term(query)
+  end
+
+  def query(query, maps = nil)
+    @fb.query(query, maps)
   end
 end

data/lib/factbase/logged.rb

@@ -6,33 +6,43 @@
 require 'decoor'
 require 'others'
 require 'time'
-require 'loog'
 require 'tago'
 require_relative 'syntax'
 
 # A decorator of a Factbase, that logs all operations.
+#
 # Author:: Yegor Bugayenko (yegor256@gmail.com)
 # Copyright:: Copyright (c) 2024-2025 Yegor Bugayenko
 # License:: MIT
 class Factbase::Logged
-  def initialize(fb, loog)
+  # Ctor.
+  # @param [Factbase] fb The factbase to decorate
+  # @param [Object] log The logging facility
+  # @param [Integer] time_tolerate How many seconds are OK per request
+  # @param [Print] tube The tube to use, if log is NIL
+  def initialize(fb, log = nil, time_tolerate: 1, tube: nil)
     raise 'The "fb" is nil' if fb.nil?
-    @fb = fb
-    raise 'The "loog" is nil' if loog.nil?
-    @loog = loog
+    @origin = fb
+    if log.nil?
+      raise 'Either "log" or "tube" must be non-NIL' if tube.nil?
+      @tube = tube
+    else
+      @tube = Tube.new(log, time_tolerate:)
+    end
   end
 
-  decoor(:fb)
+  decoor(:origin)
 
   def insert
     start = Time.now
-    f = @fb.insert
-    @loog.debug("Inserted new fact ##{@fb.size} in #{start.ago}")
-    Fact.new(f, @loog)
+    f = @origin.insert
+    @tube.say(start, "Inserted new fact ##{@origin.size} in #{start.ago}")
+    Fact.new(f, tube: @tube)
   end
 
-  def query(query)
-    Query.new(@fb, query, @loog)
+  def query(term, maps = nil)
+    term = to_term(term) if term.is_a?(String)
+    Query.new(term, maps, @tube, @origin)
   end
 
   def txn
@@ -40,21 +50,38 @@ class Factbase::Logged
     id = nil
     rollback = false
     r =
-      @fb.txn do |fbt|
+      @origin.txn do |fbt|
         id = fbt.object_id
-        yield Factbase::Logged.new(fbt, @loog)
+        yield Factbase::Logged.new(fbt, tube: @tube)
       rescue Factbase::Rollback => e
         rollback = true
         raise e
       end
     if rollback
-      Factbase::Logged.log_it(@loog, start, "Txn ##{id} rolled back in #{start.ago}")
+      @tube.say(start, "Txn ##{id} rolled back in #{start.ago}")
     else
-      Factbase::Logged.log_it(@loog, start, "Txn ##{id} touched #{r} in #{start.ago}")
+      @tube.say(start, "Txn ##{id} touched #{r} in #{start.ago}")
     end
     r
   end
 
+  # Printer of log messages.
+  class Tube
+    def initialize(log, time_tolerate: 1)
+      @log = log
+      @time_tolerate = time_tolerate
+    end
+
+    def say(start, msg)
+      m = :debug
+      if Time.now - start > @time_tolerate
+        msg = "#{msg} (slow!)"
+        m = :warn
+      end
+      @log.send(m, msg)
+    end
+  end
+
   # Fact decorator.
   #
   # This is an internal class, it is not supposed to be instantiated directly.
@@ -62,9 +89,14 @@ class Factbase::Logged
   class Fact
     MAX_LENGTH = 64
 
-    def initialize(fact, loog)
+    def initialize(fact, tube: nil, log: nil)
       @fact = fact
-      @loog = loog
+      @tube =
+        if log.nil?
+          tube
+        else
+          Tube.new(log)
+        end
     end
 
     def to_s
@@ -76,13 +108,14 @@ class Factbase::Logged
     end
 
     others do |*args|
+      start = Time.now
       r = @fact.method_missing(*args)
       k = args[0].to_s
       v = args[1]
       s = v.is_a?(Time) ? v.utc.iso8601 : v.to_s
       s = v.to_s.inspect if v.is_a?(String)
       s = "#{s[0..MAX_LENGTH / 2]}...#{s[-MAX_LENGTH / 2..]}" if s.length > MAX_LENGTH
-      @loog.debug("Set '#{k[0..-2]}' to #{s} (#{v.class})") if k.end_with?('=')
+      @tube.say(start, "Set '#{k[0..-2]}' to #{s} (#{v.class})") if k.end_with?('=')
       r
     end
   end
@@ -90,78 +123,79 @@ class Factbase::Logged
   # Query decorator.
   #
   # This is an internal class, it is not supposed to be instantiated directly.
-  #
   class Query
-    def initialize(fb, expr, loog)
+    def initialize(term, maps, tube, fb)
+      @term = term
+      @maps = maps
+      @tube = tube
       @fb = fb
-      @expr = expr
-      @loog = loog
     end
 
-    def one(params = {})
+    def each(fb = nil, params = {}, &)
+      return to_enum(__method__, fb, params) unless block_given?
       start = Time.now
-      q = Factbase::Syntax.new(@fb, @expr).to_term.to_s
-      r = nil
-      tail =
-        Factbase::Logged.elapsed do
-          r = @fb.query(@expr).one(params)
-        end
-      if r.nil?
-        Factbase::Logged.log_it(@loog, start, "Nothing found by '#{q}' #{tail}")
-      else
-        Factbase::Logged.log_it(@loog, start, "Found #{r} (#{r.class}) by '#{q}' #{tail}")
-      end
-      r
-    end
-
-    def each(params = {}, &)
-      start = Time.now
-      q = Factbase::Syntax.new(@fb, @expr).to_term.to_s
+      q = Factbase::Syntax.new(@term).to_term.to_s
       if block_given?
         r = nil
         tail =
           Factbase::Logged.elapsed do
-            r = @fb.query(@expr).each(params, &)
+            r = @fb.query(@term, @maps).each(@fb, params, &)
           end
-        raise ".each of #{@expr.class} returned #{r.class}" unless r.is_a?(Integer)
+        raise ".each of #{@term.class} returned #{r.class}" unless r.is_a?(Integer)
         if r.zero?
-          Factbase::Logged.log_it(@loog, start, "Nothing found by '#{q}' #{tail}")
+          @tube.say(start, "Nothing found by '#{q}' #{tail}")
         else
-          Factbase::Logged.log_it(@loog, start, "Found #{r} fact(s) by '#{q}' #{tail}")
+          @tube.say(start, "Found #{r} fact(s) by '#{q}' #{tail}")
         end
         r
       else
         array = []
         tail =
           Factbase::Logged.elapsed do
-            @fb.query(@expr).each(params) do |f|
+            @fb.query(@term, @maps).each(@fb, params) do |f|
               array << f
             end
           end
         if array.empty?
-          Factbase::Logged.log_it(@loog, start, "Nothing found by '#{q}' #{tail}")
+          @tube.say(start, "Nothing found by '#{q}' #{tail}")
         else
-          Factbase::Logged.log_it(@loog, start, "Found #{array.size} fact(s) by '#{q}' #{tail}")
+          @tube.say(start, "Found #{array.size} fact(s) by '#{q}' #{tail}")
         end
         array
       end
     end
 
-    def delete!
+    def one(_fb = nil, params = {})
+      start = Time.now
+      q = Factbase::Syntax.new(@term).to_term.to_s
+      r = nil
+      tail =
+        Factbase::Logged.elapsed do
+          r = @fb.query(@term, @maps).one(@fb, params)
+        end
+      if r.nil?
+        @tube.say(start, "Nothing found by '#{q}' #{tail}")
+      else
+        @tube.say(start, "Found #{r} (#{r.class}) by '#{q}' #{tail}")
+      end
+      r
+    end
+
+    def delete!(_fb = nil)
       r = nil
       start = Time.now
       before = @fb.size
       tail =
         Factbase::Logged.elapsed do
-          r = @fb.query(@expr).delete!
+          r = @fb.query(@term).delete!(@fb)
         end
-      raise ".delete! of #{@expr.class} returned #{r.class}" unless r.is_a?(Integer)
+      raise ".delete! of #{@term.class} returned #{r.class}" unless r.is_a?(Integer)
       if before.zero?
-        Factbase::Logged.log_it(@loog, start, "There were no facts, nothing deleted by '#{@expr}' #{tail}")
+        @tube.say(start, "There were no facts, nothing deleted by '#{@term}' #{tail}")
       elsif r.zero?
-        Factbase::Logged.log_it(@loog, start, "No facts out of #{before} deleted by '#{@expr}' #{tail}")
+        @tube.say(start, "No facts out of #{before} deleted by '#{@term}' #{tail}")
       else
-        Factbase::Logged.log_it(@loog, start, "Deleted #{r} fact(s) out of #{before} by '#{@expr}' #{tail}")
+        @tube.say(start, "Deleted #{r} fact(s) out of #{before} by '#{@term}' #{tail}")
       end
       r
     end
@@ -172,13 +206,4 @@ class Factbase::Logged
     yield
     "in #{start.ago}"
   end
-
-  def self.log_it(loog, start, msg)
-    m = :debug
-    if Time.now - start > 1
-      msg = "#{msg} (slow!)"
-      m = :warn
-    end
-    loog.send(m, msg)
-  end
 end