cuprum-collections 0.4.0 → 0.5.0

data/lib/cuprum/collections/rspec/deferred/resource_examples.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require 'rspec/sleeping_king_studios/deferred'
+
+require 'cuprum/collections/rspec/deferred'
+require 'cuprum/collections/rspec/deferred/relation_examples'
+
+module Cuprum::Collections::RSpec::Deferred
+  # Deferred examples for testing resources.
+  module ResourceExamples
+    include RSpec::SleepingKingStudios::Deferred::Provider
+
+    deferred_examples 'should be a Resource' do
+      include Cuprum::Collections::RSpec::Deferred::RelationExamples
+
+      include_deferred 'should be a Relation',
+        cardinality: true
+
+      include_deferred 'should define Relation cardinality'
+
+      include_deferred 'should define Relation primary key'
+
+      include_deferred 'should define Relation scope'
+    end
+  end
+end

data/lib/cuprum/collections/rspec/deferred.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require 'cuprum/collections/rspec'
+
+module Cuprum::Collections::RSpec
+  # Namespace for deferred example groups for validating collections.
+  module Deferred; end
+end

data/lib/cuprum/collections/scope.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require 'cuprum/collections'
+require 'cuprum/collections/scopes/criteria_scope'
+
+module Cuprum::Collections
+  # Generic scope class for defining collection-independent criteria scopes.
+  class Scope < Cuprum::Collections::Scopes::CriteriaScope
+    # @overload build(value = nil, &block)
+    #   (see Cuprum::Collections::Scopes::Criteria::ClassMethods.build)
+    def self.build(...)
+      new(...)
+    end
+
+    # @overload initialize(value = nil, &block)
+    #   @param value [Hash, nil] the keys and values to parse.
+    #
+    #   @return [Array] the generated criteria.
+    #
+    #   @yield the query block.
+    #
+    #   @yieldreturn [Hash] a Hash with String keys.
+    def initialize(*args, inverted: false, &block)
+      criteria = self.class.parse(*args, &block)
+
+      super(criteria:, inverted:)
+    end
+  end
+end

data/lib/cuprum/collections/scopes/all.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require 'cuprum/collections/scopes'
+
+module Cuprum::Collections::Scopes
+  # Functionality for implementing an all scope, which returns all data.
+  module All
+    # @overload and(hash = nil, &block)
+    #   Parses the hash or block and returns the parsed scope.
+    #
+    #   @see Cuprum::Collections::Scopes::Criteria::Parser#parse.
+    #
+    # @overload and(scope)
+    #   Returns the given scope.
+    def and(*args, &)
+      return self if scope?(args.first) && args.first.empty?
+
+      builder.build(*args, &)
+    end
+    alias where and
+
+    # @return [Boolean] false.
+    def empty?
+      false
+    end
+
+    # @return [Cuprum::Collections::Scopes::None] a none scope for the current
+    #   collection.
+    def invert
+      builder.build_none_scope
+    end
+
+    # @overload or(hash = nil, &block)
+    #   Parses the hash or block and returns the parsed scope.
+    #
+    #   @see Cuprum::Collections::Scopes::Criteria::Parser#parse.
+    #
+    # @overload or(scope)
+    #   Returns the given scope.
+    def or(*args, &)
+      return self if scope?(args.first) && args.first.empty?
+
+      builder.build(*args, &)
+    end
+
+    # (see Cuprum::Collections::Scopes::Base#type)
+    def type
+      :all
+    end
+  end
+end

data/lib/cuprum/collections/scopes/all_scope.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require 'cuprum/collections/scopes'
+require 'cuprum/collections/scopes/all'
+require 'cuprum/collections/scopes/base'
+
+module Cuprum::Collections::Scopes
+  # Generic scope class for defining collection-independent all scopes.
+  class AllScope < Cuprum::Collections::Scopes::Base
+    include Cuprum::Collections::Scopes::All
+
+    # @return [Cuprum::Collections::Scopes::AllScope] a cached instance of the
+    #   all scope.
+    def self.instance
+      @instance ||= new
+    end
+  end
+end

data/lib/cuprum/collections/scopes/base.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require 'cuprum/collections/scopes'
+require 'cuprum/collections/scopes/composition'
+
+module Cuprum::Collections::Scopes
+  # Abstract class representing a set of filters for a query.
+  class Base
+    include Cuprum::Collections::Scopes::Composition
+
+    # Exception raised when inverting an uninvertible scope.
+    class UninvertibleScopeException < StandardError; end
+
+    def initialize(**); end
+
+    # @param other [Object] the object to compare.
+    #
+    # @return [Boolean] true if the other object is a scope with matching type;
+    #   otherwise false.
+    def ==(other)
+      return false unless other.is_a?(Cuprum::Collections::Scopes::Base)
+
+      other.type == type
+    end
+
+    # @return [Hash{String=>Object}] a JSON-compatible representation of the
+    #   scope.
+    def as_json
+      { 'type' => type }
+    end
+
+    # :nocov:
+
+    # @private
+    #
+    # Generates a string representation of the scope.
+    def debug
+      debug_class_name(self)
+    end
+    # :nocov:
+
+    # @return [Boolean] false.
+    def empty?
+      false
+    end
+
+    # Generates and returns an inverted copy of the scope.
+    #
+    # @raise [UninvertibleScopeException] if the scope does not implement
+    #   #invert.
+    def invert
+      raise UninvertibleScopeException,
+        "Scope class #{self.class.name} does not implement #invert"
+    end
+
+    # @return [Symbol] the scope type.
+    def type
+      :abstract
+    end
+
+    private
+
+    def builder
+      Cuprum::Collections::Scopes::Builder.instance
+    end
+
+    # :nocov:
+    def debug_class_name(scope)
+      name     = scope.class.name.sub(/\ACuprum::Collections::/, '')
+      segments =
+        name.split(/(::)?Scopes(::)?/).reject { |s| s.empty? || s == '::' }
+
+      segments.join('::')
+    end
+    # :nocov:
+  end
+end
+
+require 'cuprum/collections/scopes/builder'

data/lib/cuprum/collections/scopes/builder.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require 'cuprum/collections/scopes'
+require 'cuprum/collections/scopes/building'
+
+module Cuprum::Collections::Scopes
+  # Builder for generating generic scopes.
+  class Builder
+    include Cuprum::Collections::Scopes::Building
+
+    private
+
+    def all_scope_class
+      Cuprum::Collections::Scopes::AllScope
+    end
+
+    def conjunction_scope_class
+      Cuprum::Collections::Scopes::ConjunctionScope
+    end
+
+    def criteria_scope_class
+      Cuprum::Collections::Scopes::CriteriaScope
+    end
+
+    def disjunction_scope_class
+      Cuprum::Collections::Scopes::DisjunctionScope
+    end
+
+    def none_scope_class
+      Cuprum::Collections::Scopes::NoneScope
+    end
+  end
+end
+
+require 'cuprum/collections/scopes/all_scope'
+require 'cuprum/collections/scopes/conjunction_scope'
+require 'cuprum/collections/scopes/criteria_scope'
+require 'cuprum/collections/scopes/disjunction_scope'
+require 'cuprum/collections/scopes/none_scope'

data/lib/cuprum/collections/scopes/building.rb

@@ -0,0 +1,221 @@
+# frozen_string_literal: true
+
+require 'cuprum/collections/scopes'
+require 'cuprum/collections/scopes/criteria'
+
+module Cuprum::Collections::Scopes
+  # Abstraction for generating scopes for a given collection.
+  module Building # rubocop:disable Metrics/ModuleLength
+    # Error raised when trying to call an abstract builder method.
+    class AbstractBuilderError < StandardError; end
+
+    # Error raised when trying to transform an unknown scope type.
+    class UnknownScopeTypeError < StandardError; end
+
+    # Class methods to extend when including the module.
+    module ClassMethods
+      # @return [Cuprum::Collections::Scopes::Builder] a singleton instance of
+      #   the builder class.
+      def instance
+        @instance ||= new
+      end
+    end
+
+    class << self
+      private
+
+      def included(other)
+        super
+
+        other.extend(ClassMethods)
+      end
+    end
+
+    # @overload build(hash = nil, &block)
+    #   Parses the hash or block and returns a criteria scope.
+    #
+    #   @see Cuprum::Collections::Scopes::Criteria::Parser#parse.
+    #
+    # @overload build(scope)
+    #   Returns a new scope with the same scope type and properties.
+    def build(*args, &)
+      if args.first.is_a?(Cuprum::Collections::Scopes::Base)
+        return transform_scope(scope: args.first)
+      end
+
+      criteria_scope_class.build(*args, &)
+    end
+
+    # Creates a new all scope.
+    def build_all_scope
+      all_scope_class.new
+    end
+
+    # Creates a new logical AND scope wrapping the given scopes.
+    #
+    # @param scopes [Array<Cuprum::Collections::Scopes::Base>] the scopes to
+    #   wrap in an AND scope.
+    # @param safe [Boolean] if true, validates and converts the scopes to match
+    #   the builder's scope classes. Defaults to true.
+    def build_conjunction_scope(scopes:, safe: true)
+      if safe
+        validate_scopes!(scopes)
+
+        scopes = transform_scopes(scopes)
+      end
+
+      conjunction_scope_class.new(scopes:)
+    end
+
+    # Creates a new scope wrapping the given criteria.
+    #
+    # @param criteria [Array] the criteria for the scope.
+    # @param inverted [Boolean] true if the criteria scope is inverted.
+    # @param safe [Boolean] if true, validates the criteria. Defaults to true.
+    def build_criteria_scope(criteria:, inverted: false, safe: true)
+      validate_criteria!(criteria) if safe
+
+      criteria_scope_class.new(criteria:, inverted:)
+    end
+
+    # Creates a new logical OR scope wrapping the given scopes.
+    #
+    # @param scopes [Array<Cuprum::Collections::Scopes::Base>] the scopes to
+    #   wrap in an AND scope.
+    # @param safe [Boolean] if true, validates and converts the scopes to match
+    #   the builder's scope classes. Defaults to true.
+    def build_disjunction_scope(scopes:, safe: true)
+      if safe
+        validate_scopes!(scopes)
+
+        scopes = transform_scopes(scopes)
+      end
+
+      disjunction_scope_class.new(scopes:)
+    end
+
+    # Creates a new none scope.
+    def build_none_scope
+      none_scope_class.new
+    end
+
+    # Creates a new scope with the same scope type and properties.
+    def transform_scope(scope:)
+      validate_scope!(scope)
+
+      build_transformed_scope(scope)
+    end
+
+    private
+
+    def all_scope_class
+      raise AbstractBuilderError,
+        "#{self.class.name} is an abstract class. Define a builder " \
+        'class and implement the #all_scope_class method.',
+        caller(1..-1)
+    end
+
+    def build_transformed_scope(original) # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength
+      case original.type
+      when :all
+        return original if original.is_a?(all_scope_class)
+
+        build_all_scope
+      when :conjunction
+        return original if original.is_a?(conjunction_scope_class)
+
+        build_conjunction_scope(
+          safe:   false,
+          scopes: transform_scopes(original.scopes)
+        )
+      when :criteria
+        return original if original.is_a?(criteria_scope_class)
+
+        build_criteria_scope(
+          criteria: original.criteria,
+          inverted: original.inverted?,
+          safe:     false
+        )
+      when :disjunction
+        return original if original.is_a?(disjunction_scope_class)
+
+        build_disjunction_scope(
+          safe:   false,
+          scopes: transform_scopes(original.scopes)
+        )
+      when :none
+        return original if original.is_a?(none_scope_class)
+
+        build_none_scope
+      else
+        error_message =
+          "#{self.class.name} cannot transform scopes of type " \
+          "#{original.type.inspect} (#{original.class.name})"
+
+        raise UnknownScopeTypeError, error_message
+      end
+    end
+
+    def conjunction_scope_class
+      raise AbstractBuilderError,
+        "#{self.class.name} is an abstract class. Define a builder " \
+        'class and implement the #conjunction_scope_class method.',
+        caller(1..-1)
+    end
+
+    def criteria_scope_class
+      raise AbstractBuilderError,
+        "#{self.class.name} is an abstract class. Define a builder " \
+        'class and implement the #criteria_scope_class method.',
+        caller(1..-1)
+    end
+
+    def disjunction_scope_class
+      raise AbstractBuilderError,
+        "#{self.class.name} is an abstract class. Define a builder " \
+        'class and implement the #disjunction_scope_class method.',
+        caller(1..-1)
+    end
+
+    def none_scope_class
+      raise AbstractBuilderError,
+        "#{self.class.name} is an abstract class. Define a builder " \
+        'class and implement the #none_scope_class method.',
+        caller(1..-1)
+    end
+
+    def transform_scopes(scopes)
+      scopes.map { |scope| build_transformed_scope(scope) }
+    end
+
+    def validate_criteria!(criteria)
+      unless criteria.is_a?(Array)
+        raise ArgumentError, 'criteria must be an Array', caller(1..-1)
+      end
+
+      return if criteria.all? do |criterion|
+        criterion.is_a?(Array) && criterion.size == 3
+      end
+
+      raise ArgumentError, 'criterion must be an Array of size 3', caller(1..-1)
+    end
+
+    def validate_scope!(scope)
+      return if scope.is_a?(Cuprum::Collections::Scopes::Base)
+
+      raise ArgumentError, 'scope must be a Scope instance', caller(1..-1)
+    end
+
+    def validate_scopes!(scopes)
+      unless scopes.is_a?(Array)
+        raise ArgumentError, 'scopes must be an Array', caller(1..-1)
+      end
+
+      return if scopes.all? do |scope|
+        scope.is_a?(Cuprum::Collections::Scopes::Base)
+      end
+
+      raise ArgumentError, 'scope must be a Scope instance', caller(1..-1)
+    end
+  end
+end

data/lib/cuprum/collections/scopes/composition.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+require 'cuprum/collections/scopes'
+
+module Cuprum::Collections::Scopes
+  # Defines a fluent interface for composing scopes.
+  module Composition
+    # @overload and(hash = nil, &block)
+    #   Parses the hash or block and combines using a logical AND.
+    #
+    #   @see Cuprum::Collections::Scopes::Criteria::Parser#parse.
+    #
+    # @overload and(scope)
+    #   Combines with the current scope using a logical AND.
+    #
+    #   Returns self if the given scope is empty.
+    def and(*args, &)
+      if scope?(args.first)
+        return and_scope(args.first) || and_generic_scope(args.first)
+      end
+
+      scope = builder.build(*args, &)
+
+      # We control the current and generated scopes, so we can skip validation
+      # and transformation.
+      builder.build_conjunction_scope(scopes: [self, scope], safe: false)
+    end
+    alias where and
+
+    # @overload not(hash = nil, &block)
+    #   Parses and inverts the hash or block and combines using a logical AND.
+    #
+    #   @see Cuprum::Collections::Scopes::Criteria::Parser#parse.
+    #
+    # @overload not(scope)
+    #   Inverts and combines with the current scope using a logical AND.
+    #
+    #   Returns self if the given scope is empty.
+    def not(...)
+      scope = builder.build(...).invert
+
+      self.and(scope)
+    end
+
+    # @overload and(hash = nil, &block)
+    #   Parses the hash or block and combines using a logical OR.
+    #
+    #   @see Cuprum::Collections::Scopes::Criteria::Parser#parse.
+    #
+    # @overload and(scope)
+    #   Combines with the current scope using a logical OR.
+    #
+    #   Returns self if the given scope is empty.
+    def or(*args, &)
+      if scope?(args.first)
+        return or_scope(args.first) || or_generic_scope(args.first)
+      end
+
+      scope = builder.build(*args, &)
+
+      # We control the current and generated scopes, so we can skip validation
+      # and transformation.
+      builder.build_disjunction_scope(scopes: [self, scope], safe: false)
+    end
+
+    private
+
+    def and_all_scope(_)
+      self
+    end
+
+    def and_criteria_scope(scope)
+      and_generic_scope(scope)
+    end
+
+    def and_conjunction_scope(scope)
+      scopes = scope.scopes.map do |inner|
+        builder.transform_scope(scope: inner)
+      end
+
+      builder.build_conjunction_scope(scopes: [self, *scopes], safe: false)
+    end
+
+    def and_disjunction_scope(scope)
+      and_generic_scope(scope)
+    end
+
+    def and_generic_scope(scope)
+      scope = builder.transform_scope(scope:)
+
+      # We control the current and generated scopes, so we can skip validation
+      # and transformation.
+      builder.build_conjunction_scope(scopes: [self, scope], safe: false)
+    end
+
+    def and_scope(scope) # rubocop:disable Metrics/MethodLength
+      return self if scope.empty?
+
+      case scope.type
+      when :all
+        and_all_scope(scope)
+      when :conjunction
+        and_conjunction_scope(scope)
+      when :criteria
+        and_criteria_scope(scope)
+      when :disjunction
+        and_disjunction_scope(scope)
+      when :none
+        scope
+      end
+    end
+
+    def or_all_scope(scope)
+      builder.transform_scope(scope:)
+    end
+
+    def or_conjunction_scope(scope)
+      or_generic_scope(scope)
+    end
+
+    def or_criteria_scope(scope)
+      or_generic_scope(scope)
+    end
+
+    def or_disjunction_scope(scope)
+      scopes = scope.scopes.map do |inner|
+        builder.transform_scope(scope: inner)
+      end
+
+      builder.build_disjunction_scope(scopes: [self, *scopes], safe: false)
+    end
+
+    def or_generic_scope(scope)
+      scope = builder.transform_scope(scope:)
+
+      # We control the current and generated scopes, so we can skip validation
+      # and transformation.
+      builder.build_disjunction_scope(scopes: [self, scope], safe: false)
+    end
+
+    def or_scope(scope) # rubocop:disable Metrics/MethodLength
+      return self if scope.empty?
+
+      case scope.type
+      when :all
+        or_all_scope(scope)
+      when :conjunction
+        or_conjunction_scope(scope)
+      when :criteria
+        or_criteria_scope(scope)
+      when :disjunction
+        or_disjunction_scope(scope)
+      when :none
+        self
+      end
+    end
+
+    def scope?(value)
+      value.is_a?(Cuprum::Collections::Scopes::Base)
+    end
+  end
+end

data/lib/cuprum/collections/scopes/conjunction.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require 'cuprum/collections/scopes'
+require 'cuprum/collections/scopes/container'
+
+module Cuprum::Collections::Scopes
+  # Functionality for implementing a logical AND scope.
+  module Conjunction
+    include Cuprum::Collections::Scopes::Container
+
+    # (see Cuprum::Collections::Scopes::Composition#and)
+    def and(*args, &)
+      return super if scope?(args.first)
+
+      with_scopes([*scopes, builder.build(*args, &)])
+    end
+    alias where and
+
+    # @return [Cuprum::Collections::Disjunction] a logical OR scope with the
+    #   constituent scopes inverted.
+    def invert
+      builder.build_disjunction_scope(scopes: scopes.map(&:invert))
+    end
+
+    # (see Cuprum::Collections::Scopes::Base#type)
+    def type
+      :conjunction
+    end
+
+    private
+
+    def and_conjunction_scope(scope)
+      scopes = scope.scopes.map do |inner|
+        builder.transform_scope(scope: inner)
+      end
+
+      with_scopes([*self.scopes, *scopes])
+    end
+
+    def and_generic_scope(scope)
+      with_scopes([*scopes, builder.transform_scope(scope:)])
+    end
+  end
+end

data/lib/cuprum/collections/scopes/conjunction_scope.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require 'cuprum/collections/scopes'
+require 'cuprum/collections/scopes/base'
+require 'cuprum/collections/scopes/conjunction'
+
+module Cuprum::Collections::Scopes
+  # Generic scope class for defining collection-independent logical AND scopes.
+  class ConjunctionScope < Cuprum::Collections::Scopes::Base
+    include Cuprum::Collections::Scopes::Conjunction
+  end
+end