lutaml-store 0.2.2 → 0.2.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4917f68f56456a19670424157dd5001d243b9bd6d97618f445d306a7998e2a9f
-  data.tar.gz: 7076d765cf18cc91bfa9cf252bb0117ea8870c915bf1e7421648d9490de7e6a5
+  metadata.gz: b6093f17ea0bca9240b608835a29b8f060a0c8c41be950e93fc0713e8c1b9444
+  data.tar.gz: f0f9ee8ace22fa22ec62408425ba7fa479648c57158c92967bc8e235fd037285
 SHA512:
-  metadata.gz: 897f40bf4972373587528a80afcc44ab2b0c159f2bba63a97f39cb997eff97d3633d7e34cabeb0dac37e1b337781f0aef60b9ffaae2b3a3426d5624b35fb7950
-  data.tar.gz: 1b79b56672ace97f0b6e57715b1b56b7f4638b1d426db57b8f57c5ed21eb461a7fd2ff4181f57afaa094d85c9b7da37f9e3d4771c04afecfcef0c268e86ddcd7
+  metadata.gz: 97a8aa5dc0d52617b1f4d97bd8378664eead01e299410d8dd506b775be23d69616008cde2e053b6a649819726048afdd2b227a455979630b2f07d04e76deed6d
+  data.tar.gz: b80834cd232f87d378c0a3a5f7ea17ef2c7ea2d68103d890756eabb2f2c85e20e1b1f193ec64cd0198fdb4235c0ff68ca6de87e788b7aabaa26b49a081e2023e

data/.rubocop_todo.yml

@@ -1,6 +1,6 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2026-06-05 09:38:49 UTC using RuboCop version 1.87.0.
+# on 2026-06-10 09:02:53 UTC using RuboCop version 1.87.0.
 # The point is for the user to remove these configuration records
 # one by one as the offenses are removed from the code base.
 # Note that changes in the inspected code, or installation of new
@@ -11,54 +11,63 @@ Gemspec/RequiredRubyVersion:
   Exclude:
     - 'lutaml-store.gemspec'
 
-# Offense count: 29
+# Offense count: 38
 # Configuration parameters: AllowedMethods, AllowedPatterns, CountRepeatedAttributes.
 Metrics/AbcSize:
   Max: 112
 
-# Offense count: 57
+# Offense count: 63
 # Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
 # AllowedMethods: refine
 Metrics/BlockLength:
   Max: 387
 
-# Offense count: 16
+# Offense count: 17
 # Configuration parameters: CountComments, CountAsOne.
 Metrics/ClassLength:
-  Max: 379
+  Max: 516
 
-# Offense count: 9
+# Offense count: 15
 # Configuration parameters: AllowedMethods, AllowedPatterns.
 Metrics/CyclomaticComplexity:
-  Max: 12
+  Max: 13
 
-# Offense count: 79
+# Offense count: 89
 # Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
 Metrics/MethodLength:
   Max: 84
 
-# Offense count: 5
+# Offense count: 6
 # Configuration parameters: CountKeywordArgs, MaxOptionalParameters.
 Metrics/ParameterLists:
   Max: 8
 
-# Offense count: 4
+# Offense count: 8
 # Configuration parameters: AllowedMethods, AllowedPatterns.
 Metrics/PerceivedComplexity:
-  Max: 12
+  Max: 14
 
 # Offense count: 1
 Naming/AccessorMethodName:
   Exclude:
     - 'lib/lutaml/store/adapter/sqlite.rb'
 
-# Offense count: 3
+# Offense count: 1
+# This cop supports unsafe autocorrection (--autocorrect-all).
+# Configuration parameters: EnforcedStyleForLeadingUnderscores.
+# SupportedStylesForLeadingUnderscores: disallowed, required, optional
+Naming/MemoizedInstanceVariableName:
+  Exclude:
+    - 'lib/lutaml/store/query.rb'
+
+# Offense count: 4
 # Configuration parameters: MinNameLength, AllowNamesEndingInNumbers, AllowedNames, ForbiddenNames.
 # AllowedNames: as, at, by, cc, db, id, if, in, io, ip, of, on, os, pp, to
 Naming/MethodParameterName:
   Exclude:
     - 'demo/vcard_models.rb'
     - 'demo/vcard_store_demo.rb'
+    - 'lib/lutaml/store/adapter/sqlite.rb'
 
 # Offense count: 1
 # Configuration parameters: NamePrefix, ForbiddenPrefixes, AllowedMethods, MethodDefinitionMacros, UseSorbetSigs.
@@ -84,7 +93,7 @@ Security/MarshalLoad:
   Exclude:
     - 'lib/lutaml/store/format/marshal_format.rb'
 
-# Offense count: 36
+# Offense count: 51
 # Configuration parameters: AllowedConstants.
 Style/Documentation:
   Enabled: false

data/lib/lutaml/store/adapter/base.rb

@@ -8,6 +8,8 @@ module Lutaml
           @config = config
         end
 
+        # ── Key-value operations ──
+
         def get(key)
           raise NotImplementedError
         end
@@ -60,6 +62,32 @@ module Lutaml
           keys.each_with_object({}) { |k, h| h[k] = delete(k) }
         end
 
+        # ── Query operations ──
+
+        # Execute a query specification.
+        # Returns array of [storage_key, hash_data] pairs, sorted and paginated.
+        # Returns nil to indicate "not supported — fall back to in-memory scan".
+        def execute_query(_query)
+          nil
+        end
+
+        # Count matching records without returning data.
+        # Returns nil to indicate "not supported — count execute_query results".
+        def count_query(_query)
+          nil
+        end
+
+        # Fetch a batch of [storage_key, hash_data] pairs for keyset pagination.
+        # Returns nil to indicate "not supported — fall back to in-memory".
+        def batch_query(_query, _after: nil, _limit: 1000)
+          nil
+        end
+
+        # Execute a block atomically. No-op for adapters without transaction support.
+        def transaction
+          yield
+        end
+
         def stats
           { adapter: self.class.name }
         end

data/lib/lutaml/store/adapter/memory.rb

@@ -3,136 +3,145 @@
 module Lutaml
   module Store
     module Adapter
+      # In-memory key-value adapter optimized for read-heavy workloads.
+      # Writes are synchronized; reads are lock-free using snapshot copies.
       class Memory < Base
         def initialize(config = {})
           super
           @data = {}
-          @mutex = Mutex.new
+          @write_mutex = Mutex.new
+          @read_snapshot = {}.freeze
+          @snapshot_stale = true
           @ttl_enabled = @config.fetch(:ttl_enabled, false)
-          @ttl_data = {} if @ttl_enabled
+          @ttl_data = @ttl_enabled ? {} : nil
           @default_ttl = @config[:default_ttl] || 3600
         end
 
+        # ── Read operations (lock-free via snapshot) ──
+
         def get(key)
-          @mutex.synchronize do
-            return nil unless @data.key?(key)
+          cleanup_expired_if_needed
+          snapshot[key]
+        end
 
-            if @ttl_enabled && expired?(key)
-              @data.delete(key)
-              @ttl_data.delete(key)
-              return nil
-            end
+        def exists?(key)
+          cleanup_expired_if_needed
+          snapshot.key?(key)
+        end
+
+        def all
+          cleanup_expired_if_needed
+          snapshot.dup
+        end
+
+        def size
+          cleanup_expired_if_needed
+          snapshot.size
+        end
+
+        def keys
+          cleanup_expired_if_needed
+          snapshot.keys
+        end
 
-            @data[key]
+        def each_key(&block)
+          cleanup_expired_if_needed
+          snapshot.each_key(&block)
+        end
+
+        def bulk_get(keys)
+          cleanup_expired_if_needed
+          snap = snapshot
+          keys.each_with_object({}) do |k, h|
+            h[k] = snap[k]
           end
         end
 
+        # ── Write operations (synchronized) ──
+
         def set(key, value, metadata = {})
-          @mutex.synchronize do
+          @write_mutex.synchronize do
             @data[key] = value
+            invalidate_snapshot
 
             if @ttl_enabled
               ttl_value = metadata[:ttl] || @default_ttl
               @ttl_data[key] = Time.now + ttl_value if ttl_value
             end
-
-            value
           end
+          value
         end
 
         def delete(key)
-          @mutex.synchronize do
+          @write_mutex.synchronize do
             existed = @data.key?(key)
             @data.delete(key)
-            @ttl_data.delete(key) if @ttl_enabled
+            @ttl_data&.delete(key)
+            invalidate_snapshot
             existed
           end
         end
 
-        def exists?(key)
-          @mutex.synchronize do
-            return false unless @data.key?(key)
-
-            if @ttl_enabled && expired?(key)
-              @data.delete(key)
-              @ttl_data.delete(key)
-              return false
-            end
-
-            true
-          end
-        end
-
-        def all
-          @mutex.synchronize do
-            cleanup_expired if @ttl_enabled
-            @data.dup
-          end
-        end
-
         def clear
-          @mutex.synchronize do
+          @write_mutex.synchronize do
             count = @data.size
             @data.clear
-            @ttl_data.clear if @ttl_enabled
+            @ttl_data&.clear
+            invalidate_snapshot
             count
           end
         end
 
-        def size
-          @mutex.synchronize do
-            cleanup_expired if @ttl_enabled
-            @data.size
+        def close
+          @write_mutex.synchronize do
+            @data.clear
+            @ttl_data&.clear
+            invalidate_snapshot
           end
         end
 
-        def keys
-          @mutex.synchronize do
-            cleanup_expired if @ttl_enabled
-            @data.keys
-          end
-        end
+        def bulk_set(key_value_pairs, ttl: nil)
+          @write_mutex.synchronize do
+            key_value_pairs.each do |key, value|
+              @data[key] = value
 
-        def each_key(&block)
-          current_keys = @mutex.synchronize do
-            cleanup_expired if @ttl_enabled
-            @data.keys
+              if @ttl_enabled
+                ttl_value = ttl || @default_ttl
+                @ttl_data[key] = Time.now + ttl_value if ttl_value
+              end
+            end
+            invalidate_snapshot
           end
-          current_keys.each(&block)
         end
 
-        def close
-          @mutex.synchronize do
-            @data.clear
-            @ttl_data.clear if @ttl_enabled
+        def bulk_delete(keys)
+          @write_mutex.synchronize do
+            result = {}
+            keys.each do |key|
+              result[key] = @data.delete(key)
+              @ttl_data&.delete(key)
+            end
+            invalidate_snapshot
+            result
           end
         end
 
-        def stats
-          @mutex.synchronize do
-            cleanup_expired if @ttl_enabled
-            super.merge(
-              size: @data.size,
-              ttl_enabled: @ttl_enabled,
-              expired_keys: @ttl_enabled ? count_expired_keys : 0
-            )
-          end
-        end
+        # ── TTL operations ──
 
         def cleanup_expired
           return unless @ttl_enabled
 
-          @mutex.synchronize do
-            expired_keys = []
-            @ttl_data.each do |key, expiry_time|
-              expired_keys << key if Time.now > expiry_time
+          @write_mutex.synchronize do
+            now = Time.now
+            expired_keys = @ttl_data.each_with_object([]) do |(key, expiry_time), arr|
+              arr << key if now > expiry_time
             end
 
             expired_keys.each do |key|
               @data.delete(key)
               @ttl_data.delete(key)
             end
-
+            invalidate_snapshot unless expired_keys.empty?
             expired_keys.size
           end
         end
@@ -140,7 +149,7 @@ module Lutaml
         def set_ttl(key, ttl)
           return false unless @ttl_enabled
 
-          @mutex.synchronize do
+          @write_mutex.synchronize do
             return false unless @data.key?(key)
 
             if ttl
@@ -148,7 +157,7 @@ module Lutaml
             else
               @ttl_data.delete(key)
             end
-
+            invalidate_snapshot
             true
           end
         end
@@ -156,76 +165,159 @@ module Lutaml
         def get_ttl(key)
           return nil unless @ttl_enabled
 
-          @mutex.synchronize do
-            return nil unless @ttl_data.key?(key)
+          snap = snapshot
+          return nil unless snap.key?(key)
+          return nil unless @ttl_data.key?(key)
+
+          remaining = @ttl_data[key] - Time.now
+          remaining.positive? ? remaining : nil
+        end
+
+        # ── Query operations (lock-free via snapshot) ──
+
+        def execute_query(query)
+          cleanup_expired_if_needed
+          snap = snapshot
+          model_name = query.model_class.name
+          preds = query.predicates
+
+          results = []
+          snap.each do |key, value|
+            parsed = StorageKey.parse(key.to_s)
+            next unless parsed.class_name == model_name
+            next unless preds_all_match?(preds, value)
 
-            expiry_time = @ttl_data[key]
-            remaining = expiry_time - Time.now
-            remaining.positive? ? remaining : nil
+            results << [key, value]
           end
+
+          results = apply_sort(results, query.orders)
+          results = apply_pagination(results, query.limit_value, query.offset_value)
         end
 
-        def bulk_set(key_value_pairs, ttl: nil)
-          @mutex.synchronize do
-            key_value_pairs.each do |key, value|
-              @data[key] = value
+        def count_query(query)
+          cleanup_expired_if_needed
+          snap = snapshot
+          model_name = query.model_class.name
+          preds = query.predicates
 
-              if @ttl_enabled
-                ttl_value = ttl || @default_ttl
-                @ttl_data[key] = Time.now + ttl_value if ttl_value
-              end
-            end
+          count = 0
+          snap.each do |key, value|
+            parsed = StorageKey.parse(key.to_s)
+            next unless parsed.class_name == model_name
+            next unless preds_all_match?(preds, value)
+
+            count += 1
           end
+          count
         end
 
-        def bulk_get(keys)
-          @mutex.synchronize do
-            result = {}
-            keys.each do |key|
-              if @data.key?(key)
-                if @ttl_enabled && expired?(key)
-                  @data.delete(key)
-                  @ttl_data.delete(key)
-                  result[key] = nil
-                else
-                  result[key] = @data[key]
-                end
-              else
-                result[key] = nil
-              end
-            end
-            result
+        def batch_query(query, after: nil, limit: 1000)
+          cleanup_expired_if_needed
+          snap = snapshot
+          model_name = query.model_class.name
+          preds = query.predicates
+
+          sorted_keys = snap.keys.sort_by(&:to_s)
+          sorted_keys = sorted_keys.select { |k| k.to_s > after } if after
+
+          results = []
+          sorted_keys.each do |key|
+            parsed = StorageKey.parse(key.to_s)
+            next unless parsed.class_name == model_name
+
+            value = snap[key]
+            next unless value
+            next unless preds_all_match?(preds, value)
+
+            results << [key.to_s, value]
+            break if results.size >= limit
           end
+          results
         end
 
-        def bulk_delete(keys)
-          @mutex.synchronize do
-            result = {}
-            keys.each do |key|
-              result[key] = @data.delete(key)
-              @ttl_data.delete(key) if @ttl_enabled
+        def stats
+          cleanup_expired_if_needed
+          snap = snapshot
+          super.merge(
+            size: snap.size,
+            ttl_enabled: @ttl_enabled,
+            expired_keys: @ttl_enabled ? count_expired_keys : 0
+          )
+        end
+
+        private
+
+        # Frozen snapshot — lock-free reads. Rebuilt lazily after writes.
+        def snapshot
+          if @snapshot_stale
+            @write_mutex.synchronize do
+              if @snapshot_stale
+                @read_snapshot = @data.dup.freeze
+                @snapshot_stale = false
+              end
             end
-            result
           end
+          @read_snapshot
         end
 
-        private
+        def invalidate_snapshot
+          @snapshot_stale = true
+        end
 
-        def expired?(key)
-          return false unless @ttl_enabled
-          return false unless @ttl_data.key?(key)
+        def cleanup_expired_if_needed
+          return unless @ttl_enabled
+
+          now = Time.now
+          return unless @ttl_data.any? { |_k, expiry| now > expiry }
 
-          Time.now > @ttl_data[key]
+          cleanup_expired
         end
 
         def count_expired_keys
           return 0 unless @ttl_enabled
 
-          count = 0
-          @ttl_data.each_value do |expiry_time|
-            count += 1 if Time.now > expiry_time
+          now = Time.now
+          @ttl_data.count { |_k, expiry| now > expiry }
+        end
+
+        # Inline predicate evaluation — avoids method dispatch overhead in tight loops
+        def preds_all_match?(predicates, value)
+          predicates.all? { |p| p.match?(value) }
+        end
+
+        def apply_sort(results, orders)
+          return results if orders.empty?
+
+          results.sort do |a, b|
+            orders.reduce(0) do |cmp, o|
+              break cmp unless cmp.zero?
+
+              va = a.last.is_a?(Hash) ? a.last[o.field.to_s] : nil
+              vb = b.last.is_a?(Hash) ? b.last[o.field.to_s] : nil
+
+              cmp_val = compare_values(va, vb)
+              o.direction == :desc ? -cmp_val : cmp_val
+            end
           end
-          count
+        end
+
+        def compare_values(val_a, val_b)
+          if val_a.nil? && val_b.nil?
+            0
+          elsif val_a.nil?
+            1
+          elsif val_b.nil?
+            -1
+          else
+            val_a <=> val_b || 0
+          end
+        end
+
+        def apply_pagination(results, limit, offset)
+          start = offset || 0
+          results = results[start..] || []
+          results = results.first(limit) if limit
+          results
         end
       end
     end