factbase 0.19.10 → 0.19.11

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4b573b12e8a04a0b69a2e4c33c6ccd17c21c1c14a52a644c87564738388de546
-  data.tar.gz: b4c888226e04aee8054ff26d056cc04f34fd3a1fb29455ff6c77ce4dd2103d45
+  metadata.gz: 712cd682bc9457b563afc7a855e56cad191d2a302406e0e4e9f886ce7fa83af3
+  data.tar.gz: cd3a312b78a152b7c9631777473e7465648e6b57d31d713d37d93c63834048ed
 SHA512:
-  metadata.gz: a96ff08cc40deb0d17e25cc7c30f8e67d5c09b0179e623d7e941ade194ac7c52c2135730fb4a813faf7370097a1d151db74e1559de81a619bf572becb1eec408
-  data.tar.gz: 1f57d718a82c2c8d107c033c3d8b59440170822f5810fadfc3b99837cf4072493e96ec8a39bff41c73a913cc3dba75837a9f4ecc0804976da37ebe02c09b1777
+  metadata.gz: 013ff487bbd8d2379224361b7794d5219d3235c9c66f645ebe1d6dd928d2298f1a411240328839ea48e08f7dd4c1161cde173530c52f5f8a5afdab52c66cce98
+  data.tar.gz: cf57ff6a8f881224a2124306871d245cab380331905fd0ec1acecd381a46d636a7877867a8f1ef27611f1dafe4f1e777c1a01aa57f08b35eb3486682aef22ad3

data/Gemfile.lock

@@ -38,7 +38,7 @@ GEM
     loog (0.8.0)
       ellipsized
       logger (~> 1.0)
-    minitest (6.0.5)
+    minitest (6.0.6)
       drb (~> 2.0)
       prism (~> 1.5)
     minitest-reporters (1.8.0)
@@ -64,7 +64,7 @@ GEM
     psych (5.3.1)
       date
       stringio
-    qbash (0.8.3)
+    qbash (0.8.4)
       backtrace (> 0)
       elapsed (> 0)
       loog (> 0)

data/README.md

@@ -129,8 +129,7 @@ There are some boolean terms available in a query
 * `(not b)` is the inverse of `b`
 * `(or b1 b2 ...)` is `true` if at least one argument is `true`
 * `(and b1 b2 ...)` — if all arguments are `true`
-* `(when b1 b2)` — if `b1` is `true` and `b2` is `true`
-or `b1` is `false`
+* `(when b1 b2)` — true if `b1` is `false`, or if both `b1` and `b2` are `true`
 * `(exists p)` — if `p` property exists
 * `(absent p)` — if `p` property is absent
 * `(zero v)` — if any `v` equals to zero
@@ -145,6 +144,9 @@ There are string manipulators:
 * `(concat v1 v2 v3 ...)` — concatenates all `v`
 * `(sprintf v v1 v2 ...)` — creates a string by `v` format with params
 * `(matches v s)` — if any `v` matches the `s` regular expression
+* `(contains v s)` — if any value of `v` contains any value of `s` (substring match)
+* `(starts_with v s)` — if any `v` starts with `s`
+* `(ends_with v s)` — if any `v` ends with `s`
 
 There are a few terms that return non-boolean values:
 
@@ -152,7 +154,7 @@ There are a few terms that return non-boolean values:
 * `(size v)` is the cardinality of `v` (zero if `v` is `nil`)
 * `(type v)` is the type of `v`
 (`"String"`, `"Integer"`, `"Float"`, `"Time"`, or `"Array"`)
-* `(either v1 v1)` is `v2` if `v1` is `nil`
+* `(either v1 v2)` is `v2` if `v1` is `nil`
 
 It's possible to modify the facts retrieved, on fly:
 
@@ -227,6 +229,80 @@ There are some system-level terms:
 * `(env v1 v2)` returns the value of environment variable `v1` or the string
 `v2` if it's not set
 
+## Architecture
+
+The entire database is a single flat [Ruby](https://www.ruby-lang.org/en/)
+  `Array` of `Hash` objects held in RAM (`Factbase#@maps`). There are no
+  tables, schemas, or type enforcement beyond four scalar types: `Integer`,
+  `Float`, `String`, and `Time`. This contrasts with
+  [SQLite](https://sqlite.org/) (fixed-column tables on disk) and
+  [MongoDB](https://www.mongodb.com/) (typed document collections). New
+  programmers must understand that all data vanishes on process exit unless
+  `export`/`import` is called explicitly.
+
+Each property of a fact is a non-empty ordered set of values rather than a
+  single value. Assigning `f.foo = 1` then `f.foo = 2` produces
+  `f['foo'] == [1, 2]`; each assignment appends. Reading `f.foo` returns
+  the first element; `f['foo']` returns the full array. This accumulative
+  semantics differs from [SQL](https://www.iso.org/standard/76583.html)
+  (one value per column) and most NoSQL stores where assignment overwrites.
+  New programmers must expect multi-element arrays on every property read.
+
+Queries use a custom Lisp-style
+  [S-expression](https://en.wikipedia.org/wiki/S-expression) language:
+  `(and (eq kind 'book') (gt age 10))`. `Factbase::Syntax` tokenizes and
+  parses a query string into an AST of `Factbase::Term` objects;
+  `Factbase::Query#each` evaluates that AST against every fact. This
+  differs from [SQL](https://www.iso.org/standard/76583.html),
+  [XPath](https://www.w3.org/TR/xpath-31/), and
+  [JSONPath](https://datatracker.ietf.org/doc/html/rfc9535). New
+  programmers add operators by implementing a term class, not by modifying
+  parser grammar.
+
+Each query operator (`eq`, `gt`, `agg`, `join`, etc.) is a separate class
+  under `lib/factbase/terms/`. `Factbase::Term` holds a dispatch hash
+  (`@terms`) mapping operator symbols to instances and delegates `evaluate`
+  and `predict` calls there. This is not a class hierarchy — adding a new
+  operator requires a new file in `terms/` and a registration line in the
+  `Factbase::Term` constructor. New programmers extending the query
+  language must follow this two-step pattern.
+
+Transactions are ACID and implemented via lazy copy-on-write journaling.
+  `Factbase#txn` wraps the array in `Factbase::LazyTaped`, which defers
+  physical duplication of hash objects until the first write. Inserts,
+  deletes, and property additions are tracked by Ruby `object_id`. On
+  commit the journal is replayed into the main array; raising
+  `Factbase::Rollback` discards it. Nesting transactions is explicitly
+  forbidden by `Factbase::Light`. This differs from SQLite's
+  [WAL](https://sqlite.org/wal.html) and PostgreSQL's
+  [MVCC](https://www.postgresql.org/docs/current/mvcc.html).
+
+Cross-cutting capabilities — thread safety, indexing, constraint
+  validation, logging, and change counting — are added via decorators:
+  `Factbase::SyncFactbase`, `Factbase::IndexedFactbase`,
+  `Factbase::Rules`, `Factbase::Logged`, and `Factbase::Tallied`. The
+  [`decoor`](https://github.com/yegor256/decoor) gem provides delegation
+  boilerplate. The bare `Factbase` class is not thread-safe; new
+  programmers must wrap it with `SyncFactbase` before sharing across
+  threads.
+
+Persistence uses Ruby's
+  [`Marshal`](https://ruby-doc.org/core/Marshal.html), serializing the
+  internal array of hashes to a binary blob via `Marshal.dump`. The format
+  is Ruby-version-specific and not portable across major Ruby versions or
+  platforms, unlike [JSON](https://www.json.org/json-en.html) or
+  [Protocol Buffers](https://protobuf.dev/). Output-only decorators
+  `Factbase::ToJSON`, `Factbase::ToXML`, and `Factbase::ToYAML` exist but
+  do not support round-trip import.
+
+`Factbase::IndexedFactbase` lazily builds a hash-based inverted index for
+  equality queries, keyed by array `object_id`, property name, and
+  operator. The index is built incrementally on each query and invalidated
+  entirely on any mutation (delete or property addition). Without this
+  decorator every `query#each` call performs a full linear scan over all
+  facts. New programmers should add `IndexedFactbase` whenever the
+  factbase holds more than a few thousand facts.
+
 ## How to contribute
 
 Read
@@ -250,24 +326,24 @@ This is the result of the benchmark:
 <!-- benchmark_begin -->
 ```text
                                                                    user
-void scan                                                      0.001102
-20k facts: export: 2991KB                                      0.854774
-20k facts: import: 2991KB                                      1.035671
-50k facts: read                                                0.000138
-50k facts: read in txn                                         0.002754
-50k facts: insert                                              0.000090
-50k facts: insert in txn                                       0.000243
-50k facts: modify                                              1.085214
-50k facts: modify in txn                                       2.480409
-12k facts: large query: match 3k                              14.187596
-12k facts: large query: match 3k in txn                       19.396334
-12k facts: large query: match zero                            15.139695
-12k facts: large query: match zero in txn                     21.046074
+void scan                                                      0.001049
+20k facts: export: 2980KB                                      0.840193
+20k facts: import: 2980KB                                      1.033492
+50k facts: read                                                0.000179
+50k facts: read in txn                                         0.002282
+50k facts: insert                                              0.000082
+50k facts: insert in txn                                       0.000613
+50k facts: modify                                              1.427349
+50k facts: modify in txn                                       2.773065
+12k facts: large query: match 3k                              13.166170
+12k facts: large query: match 3k in txn                       18.502015
+12k facts: large query: match zero                            14.234812
+12k facts: large query: match zero in txn                     19.847547
 ```
 
 The results were calculated in [this GHA job][benchmark-gha]
-on 2026-04-16 at 17:08,
+on 2026-05-23 at 03:40,
 on Linux with 4 CPUs.
 <!-- benchmark_end -->
 
-[benchmark-gha]: https://github.com/yegor256/factbase/actions/runs/24523476155
+[benchmark-gha]: https://github.com/yegor256/factbase/actions/runs/26322478578

data/lib/factbase/syntax.rb

@@ -142,7 +142,7 @@ class Factbase::Syntax
         t[1..-2]
       elsif t.match?(/^(\+|-)?[0-9]+$/)
         t.to_i
-      elsif t.match?(/^(\+|-)?[0-9]+\.[0-9]+(e\+[0-9]+)?$/)
+      elsif t.match?(/^(\+|-)?[0-9]+\.[0-9]+(e(\+|-)[0-9]+)?$/)
         t.to_f
       elsif t.match?(/^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z$/)
         Time.parse(t)

data/lib/factbase/tallied.rb

@@ -8,7 +8,7 @@ require 'others'
 require_relative '../factbase'
 require_relative 'churn'
 
-# A decorator of a Factbase, that count all operations and then returns
+# A decorator of a Factbase, that counts all operations and then returns
 # an instance of Factbase::Churn.
 #
 # Author:: Yegor Bugayenko (yegor256@gmail.com)

data/lib/factbase/term.rb

@@ -12,6 +12,9 @@ require_relative 'terms/prev'
 require_relative 'terms/concat'
 require_relative 'terms/sprintf'
 require_relative 'terms/matches'
+require_relative 'terms/contains'
+require_relative 'terms/starts_with'
+require_relative 'terms/ends_with'
 require_relative 'terms/traced'
 require_relative 'terms/assert'
 require_relative 'terms/env'
@@ -108,6 +111,9 @@ class Factbase::Term < Factbase::TermBase
       concat: Factbase::Concat.new(operands),
       sprintf: Factbase::Sprintf.new(operands),
       matches: Factbase::Matches.new(operands),
+      contains: Factbase::Contains.new(operands),
+      starts_with: Factbase::StartsWith.new(operands),
+      ends_with: Factbase::EndsWith.new(operands),
       traced: Factbase::Traced.new(operands),
       assert: Factbase::Assert.new(operands),
       env: Factbase::Env.new(operands),

data/lib/factbase/terms/base.rb

@@ -3,12 +3,10 @@
 # SPDX-FileCopyrightText: Copyright (c) 2024-2026 Yegor Bugayenko
 # SPDX-License-Identifier: MIT
 
-# Test for unique term.
+# Base class for all terms.
 # Author:: Volodya Lombrozo (volodya.lombrozo@gmail.com)
 # Copyright:: Copyright (c) 2024-2026 Yegor Bugayenko
 # License:: MIT
-
-# Base class for all terms.
 class Factbase::TermBase
   # Turns it into a string.
   # @return [String] The string of it

data/lib/factbase/terms/compare.rb

@@ -31,8 +31,23 @@ class Factbase::Compare < Factbase::TermBase
       l = l.floor if l.is_a?(Time) && @op == :==
       rights.any? do |r|
         r = r.floor if r.is_a?(Time) && @op == :==
-        l.send(@op, r)
+        _compare(l, r)
       end
     end
   end
+
+  private
+
+  # Compare values with a contextual error if Ruby rejects the operands.
+  # @param [Object] left Left value
+  # @param [Object] right Right value
+  # @return [Boolean] The result of the comparison
+  def _compare(left, right)
+    left.send(@op, right)
+  rescue ArgumentError => e
+    raise(
+      "Cannot compare #{left.inspect} (#{left.class}) " \
+      "with #{right.inspect} (#{right.class}) using (compare #{@op}): #{e.message}"
+    )
+  end
 end

data/lib/factbase/terms/contains.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: Copyright (c) 2024-2026 Yegor Bugayenko
+# SPDX-License-Identifier: MIT
+
+require_relative 'base'
+require_relative 'compare'
+
+# Represents a 'contains' term in the Factbase.
+# Returns true if any value of the left operand contains any value of the right
+# as a substring. Operates on string values via `String#include?`.
+class Factbase::Contains < Factbase::TermBase
+  # Constructor.
+  # @param [Array] operands Operands
+  def initialize(operands)
+    super()
+    @op = Factbase::Compare.new(:include?, operands)
+  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] True if any left value includes any right value
+  def evaluate(fact, maps, fb)
+    @op.evaluate(fact, maps, fb)
+  end
+end

data/lib/factbase/terms/ends_with.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: Copyright (c) 2024-2026 Yegor Bugayenko
+# SPDX-License-Identifier: MIT
+
+require_relative 'base'
+require_relative 'compare'
+
+# Represents an 'ends_with' term in the Factbase.
+# Returns true if any value of the left operand ends with any value of the right.
+class Factbase::EndsWith < Factbase::TermBase
+  # Constructor.
+  # @param [Array] operands Operands
+  def initialize(operands)
+    super()
+    @op = Factbase::Compare.new(:end_with?, operands)
+  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] True if any left value ends with any right value
+  def evaluate(fact, maps, fb)
+    @op.evaluate(fact, maps, fb)
+  end
+end

data/lib/factbase/terms/matches.rb

@@ -14,6 +14,7 @@ class Factbase::Matches < Factbase::TermBase
   def initialize(operands)
     super()
     @operands = operands
+    @regexps = {}
   end
 
   # Evaluate term on a fact.
@@ -29,6 +30,15 @@ class Factbase::Matches < Factbase::TermBase
     re = _values(1, fact, maps, fb)
     raise 'Regexp is nil' if re.nil?
     raise 'Exactly one regexp is expected' unless re.size == 1
-    str[0].to_s.match?(re[0])
+    str[0].to_s.match?(regexp(re[0]))
+  end
+
+  private
+
+  def regexp(pattern)
+    key = pattern.to_s
+    @regexps[key] ||= Regexp.new(key)
+  rescue RegexpError => e
+    raise "Invalid regexp '#{key}': #{e.message}"
   end
 end

data/lib/factbase/terms/sprintf.rb

@@ -24,6 +24,14 @@ class Factbase::Sprintf < Factbase::TermBase
   def evaluate(fact, maps, fb)
     fmt = _values(0, fact, maps, fb)[0]
     ops = (1..(@operands.length - 1)).map { |i| _values(i, fact, maps, fb)&.first }
+    formatted(fmt, ops)
+  end
+
+  private
+
+  def formatted(fmt, ops)
     format(*([fmt] + ops))
+  rescue ArgumentError => e
+    raise "Cannot format #{ops.inspect} with '#{fmt}' in (sprintf ...): #{e.message}"
   end
 end

data/lib/factbase/terms/starts_with.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: Copyright (c) 2024-2026 Yegor Bugayenko
+# SPDX-License-Identifier: MIT
+
+require_relative 'base'
+require_relative 'compare'
+
+# Represents a 'starts_with' term in the Factbase.
+# Returns true if any value of the left operand starts with any value of the right.
+class Factbase::StartsWith < Factbase::TermBase
+  # Constructor.
+  # @param [Array] operands Operands
+  def initialize(operands)
+    super()
+    @op = Factbase::Compare.new(:start_with?, operands)
+  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] True if any left value starts with any right value
+  def evaluate(fact, maps, fb)
+    @op.evaluate(fact, maps, fb)
+  end
+end

data/lib/factbase/terms/sum.rb

@@ -6,7 +6,7 @@
 require_relative 'base'
 
 # This class represents a specialized 'sum' term.
-# This term  calculates the sum of values for a specified key.
+# This term calculates the sum of values for a specified key.
 class Factbase::Sum < Factbase::TermBase
   # Constructor.
   # @param [Array] operands Operands

data/lib/factbase/terms/to_time.rb

@@ -23,6 +23,14 @@ class Factbase::ToTime < Factbase::TermBase
     assert_args(1)
     vv = _values(0, fact, maps, fb)
     return nil if vv.nil?
-    Time.parse(vv[0].to_s)
+    parse(vv[0])
+  end
+
+  private
+
+  def parse(value)
+    Time.parse(value.to_s)
+  rescue ArgumentError => e
+    raise "Cannot parse '#{value}' as Time in (to_time ...): #{e.message}"
   end
 end

data/lib/factbase/terms/when.rb

@@ -22,8 +22,7 @@ class Factbase::When < Factbase::TermBase
   # @return [Boolean] True if first operand is false OR both are true
   def evaluate(fact, maps, fb)
     assert_args(2)
-    a = @operands[0]
-    b = @operands[1]
-    !a.evaluate(fact, maps, fb) || (a.evaluate(fact, maps, fb) && b.evaluate(fact, maps, fb))
+    return true unless @operands[0].evaluate(fact, maps, fb)
+    @operands[1].evaluate(fact, maps, fb)
   end
 end

data/lib/factbase/to_json.rb

@@ -9,7 +9,7 @@ require_relative '../factbase/flatten'
 
 # Factbase to JSON converter.
 #
-# This class helps converting an entire Factbase to YAML format, for example:
+# This class helps converting an entire Factbase to JSON format, for example:
 #
 #  require 'factbase/to_json'
 #  fb = Factbase.new

data/lib/factbase/to_xml.rb

@@ -10,7 +10,7 @@ require_relative '../factbase/flatten'
 
 # Factbase to XML converter.
 #
-# This class helps converting an entire Factbase to YAML format, for example:
+# This class helps converting an entire Factbase to XML format, for example:
 #
 #  require 'factbase/to_xml'
 #  fb = Factbase.new

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.19.10' unless const_defined?(:VERSION)
+  VERSION = '0.19.11' unless const_defined?(:VERSION)
 end

data/lib/factbase.rb

@@ -102,9 +102,6 @@ class Factbase
   #
   # A fact, when inserted, is empty. It doesn't contain any properties.
   #
-  # The operation is thread-safe, meaning that different threads may
-  # insert facts in parallel without breaking the consistency of the factbase.
-  #
   # @return [Factbase::Fact] The fact just inserted
   def insert
     map = {}

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: factbase
 version: !ruby/object:Gem::Version
-  version: 0.19.10
+  version: 0.19.11
 platform: ruby
 authors:
 - Yegor Bugayenko
@@ -222,11 +222,13 @@ files:
 - lib/factbase/terms/boolean.rb
 - lib/factbase/terms/compare.rb
 - lib/factbase/terms/concat.rb
+- lib/factbase/terms/contains.rb
 - lib/factbase/terms/count.rb
 - lib/factbase/terms/defn.rb
 - lib/factbase/terms/div.rb
 - lib/factbase/terms/either.rb
 - lib/factbase/terms/empty.rb
+- lib/factbase/terms/ends_with.rb
 - lib/factbase/terms/env.rb
 - lib/factbase/terms/eq.rb
 - lib/factbase/terms/exists.rb
@@ -255,6 +257,7 @@ files:
 - lib/factbase/terms/size.rb
 - lib/factbase/terms/sorted.rb
 - lib/factbase/terms/sprintf.rb
+- lib/factbase/terms/starts_with.rb
 - lib/factbase/terms/sum.rb
 - lib/factbase/terms/times.rb
 - lib/factbase/terms/to_float.rb