lutaml-store 0.2.2 → 0.3.0

data/lib/lutaml/store/predicate.rb

@@ -0,0 +1,248 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Store
+    module Predicate
+      class Base
+        attr_reader :field, :value
+
+        def initialize(field, value = nil)
+          @field = field.to_sym
+          @value = value
+        end
+
+        def match?(_target)
+          raise NotImplementedError
+        end
+
+        def negate
+          raise NotImplementedError
+        end
+
+        def hash_evaluable?(hash_data)
+          hash_data.key?(@field.to_s)
+        end
+
+        private
+
+        def extract(target)
+          target.is_a?(Hash) ? target[@field.to_s] : target.public_send(@field)
+        end
+      end
+
+      class Equal < Base
+        def match?(target)
+          extract(target) == @value
+        end
+
+        def negate
+          NotEqual.new(@field, @value)
+        end
+      end
+
+      class NotEqual < Base
+        def match?(target)
+          extract(target) != @value
+        end
+
+        def negate
+          Equal.new(@field, @value)
+        end
+      end
+
+      class GreaterThan < Base
+        def match?(target)
+          val = extract(target)
+          return false if val.nil?
+
+          val > @value
+        end
+
+        def negate
+          LessThanOrEqual.new(@field, @value)
+        end
+      end
+
+      class LessThan < Base
+        def match?(target)
+          val = extract(target)
+          return false if val.nil?
+
+          val < @value
+        end
+
+        def negate
+          GreaterThanOrEqual.new(@field, @value)
+        end
+      end
+
+      class GreaterThanOrEqual < Base
+        def match?(target)
+          val = extract(target)
+          return false if val.nil?
+
+          val >= @value
+        end
+
+        def negate
+          LessThan.new(@field, @value)
+        end
+      end
+
+      class LessThanOrEqual < Base
+        def match?(target)
+          val = extract(target)
+          return false if val.nil?
+
+          val <= @value
+        end
+
+        def negate
+          GreaterThan.new(@field, @value)
+        end
+      end
+
+      class Between < Base
+        def match?(target)
+          val = extract(target)
+          return false if val.nil?
+
+          @value.cover?(val)
+        end
+
+        def negate
+          NotBetween.new(@field, @value)
+        end
+      end
+
+      class NotBetween < Base
+        def match?(target)
+          val = extract(target)
+          return false if val.nil?
+
+          !@value.cover?(val)
+        end
+
+        def negate
+          Between.new(@field, @value)
+        end
+      end
+
+      class In < Base
+        def match?(target)
+          val = extract(target)
+          return false if val.nil?
+
+          @value.include?(val)
+        end
+
+        def negate
+          NotIn.new(@field, @value)
+        end
+      end
+
+      class NotIn < Base
+        def match?(target)
+          val = extract(target)
+          return false if val.nil?
+
+          !@value.include?(val)
+        end
+
+        def negate
+          In.new(@field, @value)
+        end
+      end
+
+      class Matches < Base
+        def match?(target)
+          val = extract(target)
+          return false if val.nil?
+
+          @value.match?(val.to_s)
+        end
+
+        def negate
+          NotMatches.new(@field, @value)
+        end
+      end
+
+      class NotMatches < Base
+        def match?(target)
+          val = extract(target)
+          return true if val.nil?
+
+          !@value.match?(val.to_s)
+        end
+
+        def negate
+          Matches.new(@field, @value)
+        end
+      end
+
+      class Nil < Base
+        def match?(target)
+          extract(target).nil?
+        end
+
+        def negate
+          NotNil.new(@field)
+        end
+      end
+
+      class NotNil < Base
+        def match?(target)
+          !extract(target).nil?
+        end
+
+        def negate
+          Nil.new(@field)
+        end
+      end
+
+      # ── Factory methods ──
+
+      def self.gt(field, value)
+        GreaterThan.new(field, value)
+      end
+
+      def self.lt(field, value)
+        LessThan.new(field, value)
+      end
+
+      def self.gte(field, value)
+        GreaterThanOrEqual.new(field, value)
+      end
+
+      def self.lte(field, value)
+        LessThanOrEqual.new(field, value)
+      end
+
+      def self.not(field, value)
+        NotEqual.new(field, value)
+      end
+
+      def self.matches(field, pattern)
+        Matches.new(field, pattern)
+      end
+
+      def self.nil(field)
+        Nil.new(field)
+      end
+
+      def self.not_nil(field)
+        NotNil.new(field)
+      end
+
+      def self.build_from_hash(conditions)
+        conditions.map do |field, value|
+          case value
+          when Range then Between.new(field, value)
+          when Array then In.new(field, value)
+          else Equal.new(field, value)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/lutaml/store/query.rb

@@ -0,0 +1,259 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Store
+    # Lazy, chainable query object — inspired by ActiveRecord::Relation.
+    # Collects predicates, sort orders, limit, and offset. Nothing executes
+    # until a terminal method is called (to_a, each, first, count, etc.).
+    class Query
+      include Enumerable
+
+      attr_reader :model_class, :predicates, :orders, :limit_value, :offset_value
+
+      def initialize(store, model_class, predicates: [], orders: [],
+                     limit_value: nil, offset_value: nil)
+        @store = store
+        @model_class = model_class
+        @predicates = predicates.dup.freeze
+        @orders = orders.dup.freeze
+        @limit_value = limit_value
+        @offset_value = offset_value
+      end
+
+      # ── Chainable methods (return new Query) ──
+
+      def where(*predicates_or_conditions, **kwargs)
+        conditions = kwargs
+        new_predicates = []
+
+        predicates_or_conditions.each do |arg|
+          if arg.is_a?(Predicate::Base)
+            new_predicates << arg
+          elsif arg.is_a?(Hash)
+            conditions = conditions.merge(arg)
+          else
+            raise ArgumentError, "where accepts Predicate objects or Hash conditions, got #{arg.class}"
+          end
+        end
+
+        new_predicates.concat(Predicate.build_from_hash(conditions)) unless conditions.empty?
+        chain(predicates: @predicates + new_predicates)
+      end
+
+      def not(conditions = {}, **kwargs)
+        conditions = conditions.merge(kwargs)
+        negated = Predicate.build_from_hash(conditions).map(&:negate)
+        chain(predicates: @predicates + negated)
+      end
+
+      def order(*specs)
+        new_orders = parse_order_specs(specs)
+        chain(orders: @orders + new_orders)
+      end
+
+      def limit(count)
+        chain(limit_value: count)
+      end
+
+      def offset(count)
+        chain(offset_value: count)
+      end
+
+      def reverse_order
+        reversed = @orders.map { |o| Order.new(o.field, o.direction == :asc ? :desc : :asc) }
+        chain(orders: reversed)
+      end
+
+      # ── Terminal methods (execute the query) ──
+
+      def to_a
+        @to_a_result ||= @store.execute_query(self)
+      end
+
+      def each(&block)
+        to_a.each(&block)
+      end
+
+      def first
+        self.class.new(@store, @model_class, predicates: @predicates,
+                                             orders: @orders, limit_value: 1,
+                                             offset_value: @offset_value).to_a.first
+      end
+
+      def last
+        reversed = @orders.map { |o| Order.new(o.field, o.direction == :asc ? :desc : :asc) }
+        self.class.new(@store, @model_class, predicates: @predicates,
+                                             orders: reversed, limit_value: 1,
+                                             offset_value: @offset_value).to_a.first
+      end
+
+      def find_by(**conditions)
+        where(**conditions).first
+      end
+
+      def find_by!(**conditions)
+        result = find_by(**conditions)
+        raise ModelNotRegisteredError, "No #{@model_class} found matching #{conditions}" unless result
+
+        result
+      end
+
+      def count
+        return to_a.size if @limit_value || @offset_value
+
+        @store.count_query(self)
+      end
+
+      alias size count
+      alias length count
+
+      def exists?
+        self.class.new(@store, @model_class, predicates: @predicates,
+                                             orders: [], limit_value: 1, offset_value: nil).to_a.any?
+      end
+
+      def empty?
+        !exists?
+      end
+
+      def any?
+        exists?
+      end
+
+      def none?
+        !exists?
+      end
+
+      def one?
+        self.class.new(@store, @model_class, predicates: @predicates,
+                                             orders: [], limit_value: 2, offset_value: nil).to_a.size == 1
+      end
+
+      def many?
+        self.class.new(@store, @model_class, predicates: @predicates,
+                                             orders: [], limit_value: 2, offset_value: nil).to_a.size > 1
+      end
+
+      # ── Calculation shortcuts ──
+
+      def pluck(*fields)
+        to_a.map do |model|
+          if fields.size == 1
+            model.public_send(fields.first)
+          else
+            fields.map { |f| model.public_send(f) }
+          end
+        end
+      end
+
+      def distinct(field = nil)
+        if field
+          to_a.map { |m| m.public_send(field) }.uniq
+        else
+          to_a.uniq
+        end
+      end
+
+      def sum(field)
+        to_a.sum { |m| m.public_send(field) }
+      end
+
+      def average(field)
+        values = to_a.map { |m| m.public_send(field) }.compact
+        return 0.0 if values.empty?
+
+        values.sum.to_f / values.size
+      end
+
+      def minimum(field)
+        to_a.min_by { |m| m.public_send(field) }
+      end
+
+      def maximum(field)
+        to_a.max_by { |m| m.public_send(field) }
+      end
+
+      # ── Batch processing ──
+
+      def find_each(batch_size: 1000, &block)
+        raise ArgumentError, "find_each does not support limit/offset" if @limit_value || @offset_value
+
+        cursor = nil
+        loop do
+          batch = @store.fetch_batch(self, after: cursor, limit: batch_size)
+          break if batch.empty?
+
+          batch.each(&block)
+          cursor = @store.last_storage_key_from(batch, @model_class)
+        end
+      end
+
+      def in_batches(of: 1000)
+        raise ArgumentError, "in_batches does not support limit/offset" if @limit_value || @offset_value
+
+        cursor = nil
+        loop do
+          batch = @store.fetch_batch(self, after: cursor, limit: of)
+          break if batch.empty?
+
+          yield batch
+          cursor = @store.last_storage_key_from(batch, @model_class)
+        end
+      end
+
+      # ── Scopes ──
+
+      def apply(scope_name, *args, **kwargs)
+        scope_body = @store.scope_for(scope_name)
+        instance_exec(*args, **kwargs, &scope_body)
+      end
+
+      def inspect
+        parts = [@model_class.to_s]
+        parts << "WHERE #{@predicates.map(&:inspect).join(" AND ")}" if @predicates.any?
+        parts << "ORDER BY #{@orders.map { |o| "#{o.field} #{o.direction}" }.join(", ")}" if @orders.any?
+        parts << "LIMIT #{@limit_value}" if @limit_value
+        parts << "OFFSET #{@offset_value}" if @offset_value
+        "#<Query #{parts.join(" ")}>"
+      end
+
+      private
+
+      def chain(**overrides)
+        self.class.new(
+          @store,
+          @model_class,
+          predicates: overrides.fetch(:predicates, @predicates),
+          orders: overrides.fetch(:orders, @orders),
+          limit_value: overrides.fetch(:limit_value, @limit_value),
+          offset_value: overrides.fetch(:offset_value, @offset_value)
+        )
+      end
+
+      def parse_order_specs(specs)
+        orders = []
+        i = 0
+        while i < specs.size
+          item = specs[i]
+          case item
+          when Hash
+            item.each { |field, dir| orders << Order.new(field, dir) }
+          when Symbol, String
+            next_val = specs[i + 1]
+            if next_val.is_a?(Symbol) && %i[asc desc].include?(next_val)
+              orders << Order.new(item, next_val)
+              i += 1
+            else
+              orders << Order.new(item, :asc)
+            end
+          end
+          i += 1
+        end
+        orders
+      end
+    end
+
+    # Sort specification value object
+    Order = Struct.new(:field, :direction)
+  end
+end

data/lib/lutaml/store/repository.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+require "cgi"
+require "digest"
+require "fileutils"
+require "json"
+
+module Lutaml
+  module Store
+    # The uniform consumer facade: one read API whether the repository is a
+    # local package, a downloaded distribution, a temp-folder cache, or the
+    # cloud API. Backends are chosen by explicit composition — the
+    # repository never guesses, never falls back, and never hides which
+    # layer answered.
+    #
+    #   # cloud, with an explicit local package cache
+    #   repo = Repository.new(
+    #     source:   Source.for(:rest, base_url: "https://api.relaton.org",
+    #                                collection: "ietf"),
+    #     cache:    Source.for(:directory, path: "~/.cache/relaton/ietf"),
+    #   )
+    #
+    #   # a downloaded official package (zip) — identical read API
+    #   repo = Repository.new(source: Source.for(:zip, path: "ietf.zip"))
+    #
+    #   # a local GCR-style checkout
+    #   repo = Repository.new(source: Source.for(:directory, path: "~/gcr/ietf"))
+    #
+    # Modes are explicit:
+    #   :online  — read cache first, then the source (default)
+    #   :offline — never touch the source; absent keys raise NotFoundError
+    class Repository
+      MODES = %i[online offline].freeze
+
+      # @param source [Source::Base] the authoritative repository
+      # @param cache [Source::Directory, nil] explicit read-through local
+      #   package (same layout as Mirror#pull writes); nil disables caching
+      # @param mode [Symbol] :online or :offline
+      def initialize(source:, cache: nil, mode: :online)
+        raise ConfigurationError, "mode must be one of #{MODES.inspect}" unless MODES.include?(mode)
+        raise ConfigurationError, "offline mode requires a cache source" if mode == :offline && cache.nil?
+
+        @source = source
+        @cache = cache
+        @mode = mode
+      end
+
+      # Read-through convenience constructors — still explicit about every
+      # backend, just shorter.
+      def self.for_cloud(base_url:, collection:, cache: nil, **source_options)
+        new(source: Source.for(:rest, base_url: base_url, collection: collection,
+                                      **source_options), cache: cache)
+      end
+
+      def self.for_package(path, type: :directory, **source_options)
+        new(source: Source.for(type, path: path, **source_options))
+      end
+
+      attr_reader :source, :cache, :mode
+
+      # @return [String] the record's bytes
+      def read(key)
+        if @cache
+          begin
+            return @cache.read(key)
+          rescue NotFoundError
+            raise if @mode == :offline
+          end
+          body = @source.read(key)
+          write_cache_entry(key, body)
+          return body
+        end
+
+        @source.read(key)
+      end
+
+      # @return the model instance built by the consumer's model class
+      def get(key, model_class)
+        format_for(key).deserialize(read(key), model_class)
+      end
+
+      def exist?(key)
+        read(key)
+        true
+      rescue NotFoundError
+        false
+      end
+
+      def keys
+        @source.keys
+      end
+
+      def each_key(&block)
+        keys.each(&block)
+      end
+
+      def manifest
+        @source.manifest
+      end
+
+      # Filters the collection's manifest entries by metadata key/values.
+      # The store is field-agnostic: it matches the literal metadata hash —
+      # the domain (relaton pubid, Glossarist concepts) narrows semantics.
+      #
+      #   repo.search(doctype: "rfc", stream: "IETF")
+      #   repo.search(docid: "RFC 7231")
+      #
+      # @param filter [Hash<String=>String>] ALL key/values must match
+      # @return [Array<Manifest::Entry>] matching entries (empty if none)
+      def search(**filter)
+        return [] if filter.empty?
+
+        manifest.entries.select do |entry|
+          filter.all? do |k, v|
+            mv = entry.metadata[k.to_s]
+            mv.is_a?(String) ? mv.casecmp?(v.to_s) : mv == v
+          end
+        end
+      end
+
+      # Mirror the whole source into a local package (the cache layout).
+      # Returns a Repository over the written package.
+      def pull!(into:, collection: nil, force: false)
+        pulled = Mirror.pull(@source, into: into, collection: collection, force: force)
+        Repository.new(source: pulled, mode: @mode)
+      end
+
+      private
+
+      # The write-through target is a Directory package (the Mirror layout);
+      # anything else is a configuration error, not a duck-type guess. The
+      # package manifest is maintained on every write so later reads —
+      # including reference resolution and offline mode — see the entry.
+      def write_cache_entry(key, body)
+        unless @cache.is_a?(Source::Directory)
+          raise ConfigurationError,
+                "cache must be a Source::Directory package, got #{@cache.class}"
+        end
+
+        location = "entries/#{Source.encode_key(key)}"
+        FileUtils.mkdir_p(::File.join(@cache.package_root, "entries"))
+        ::File.binwrite(::File.join(@cache.package_root, location), body)
+
+        manifest = begin
+          @cache.manifest
+        rescue NotFoundError
+          Lutaml::Store::Manifest.build([])
+        end
+        # The source manifest's metadata (e.g. the domain docid) rides
+        # along — offline reference resolution depends on it.
+        declared = begin
+          @source.manifest.entry_for(key)
+        rescue StandardError
+          nil
+        end
+        entry = Manifest::Entry.new(
+          key: key, location: location,
+          digest: "sha256:#{Digest::SHA256.hexdigest(body)}",
+          metadata: declared&.metadata || {}
+        )
+        entries = manifest.entries.reject { |e| e.key == key } + [entry]
+        updated = Manifest.build(entries, shards: manifest.shards)
+        ::File.write(
+          ::File.join(@cache.package_root, "manifest.json"),
+          JSON.pretty_generate(updated.to_hash)
+        )
+      end
+
+      def format_for(key)
+        fmt = Format.for_extension(::File.extname(key.to_s))
+        fmt ||= @source.options[:default_format] &&
+                Format.resolve(@source.options[:default_format])
+        fmt || raise(ConfigurationError,
+                     "cannot determine the format of #{key.inspect}: pass default_format:")
+      end
+    end
+  end
+end