cuprum-collections 0.4.0 → 0.5.0

data/lib/cuprum/collections.rb

@@ -6,15 +6,20 @@ require 'cuprum'
 module Cuprum
   # A data abstraction layer based on the Cuprum library.
   module Collections
-    autoload :Association,  'cuprum/collections/association'
-    autoload :Associations, 'cuprum/collections/associations'
-    autoload :Basic,        'cuprum/collections/basic'
-    autoload :Collection,   'cuprum/collections/collection'
-    autoload :Command,      'cuprum/collections/command'
-    autoload :Errors,       'cuprum/collections/errors'
-    autoload :Relation,     'cuprum/collections/relation'
-    autoload :Repository,   'cuprum/collections/repository'
-    autoload :Resource,     'cuprum/collections/resource'
+    autoload :Association,       'cuprum/collections/association'
+    autoload :Associations,      'cuprum/collections/associations'
+    autoload :Basic,             'cuprum/collections/basic'
+    autoload :Collection,        'cuprum/collections/collection'
+    autoload :CollectionCommand, 'cuprum/collections/collection_command'
+    autoload :Commands,          'cuprum/collections/commands'
+    autoload :Errors,            'cuprum/collections/errors'
+    autoload :Query,             'cuprum/collections/query'
+    autoload :Relation,          'cuprum/collections/relation'
+    autoload :Relations,         'cuprum/collections/relations'
+    autoload :Repository,        'cuprum/collections/repository'
+    autoload :Resource,          'cuprum/collections/resource'
+    autoload :Scope,             'cuprum/collections/scope'
+    autoload :Scopes,            'cuprum/collections/scopes'
 
     # @return [String] the absolute path to the gem directory.
     def self.gem_path

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: cuprum-collections
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Rob "Merlin" Smith
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-12-14 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: cuprum
@@ -70,11 +69,18 @@ files:
 - lib/cuprum/collections/basic/commands/update_one.rb
 - lib/cuprum/collections/basic/commands/validate_one.rb
 - lib/cuprum/collections/basic/query.rb
-- lib/cuprum/collections/basic/query_builder.rb
 - lib/cuprum/collections/basic/repository.rb
 - lib/cuprum/collections/basic/rspec.rb
+- lib/cuprum/collections/basic/scopes.rb
+- lib/cuprum/collections/basic/scopes/all_scope.rb
+- lib/cuprum/collections/basic/scopes/base.rb
+- lib/cuprum/collections/basic/scopes/builder.rb
+- lib/cuprum/collections/basic/scopes/conjunction_scope.rb
+- lib/cuprum/collections/basic/scopes/criteria_scope.rb
+- lib/cuprum/collections/basic/scopes/disjunction_scope.rb
+- lib/cuprum/collections/basic/scopes/none_scope.rb
 - lib/cuprum/collections/collection.rb
-- lib/cuprum/collections/command.rb
+- lib/cuprum/collections/collection_command.rb
 - lib/cuprum/collections/commands.rb
 - lib/cuprum/collections/commands/abstract_find_many.rb
 - lib/cuprum/collections/commands/abstract_find_matching.rb
@@ -84,6 +90,7 @@ files:
 - lib/cuprum/collections/commands/associations/require_many.rb
 - lib/cuprum/collections/commands/create.rb
 - lib/cuprum/collections/commands/find_one_matching.rb
+- lib/cuprum/collections/commands/query_command.rb
 - lib/cuprum/collections/commands/update.rb
 - lib/cuprum/collections/commands/upsert.rb
 - lib/cuprum/collections/constraints.rb
@@ -108,25 +115,66 @@ files:
 - lib/cuprum/collections/errors/unknown_operator.rb
 - lib/cuprum/collections/queries.rb
 - lib/cuprum/collections/queries/ordering.rb
-- lib/cuprum/collections/queries/parse.rb
-- lib/cuprum/collections/queries/parse_block.rb
-- lib/cuprum/collections/queries/parse_strategy.rb
 - lib/cuprum/collections/query.rb
-- lib/cuprum/collections/query_builder.rb
 - lib/cuprum/collections/relation.rb
+- lib/cuprum/collections/relations.rb
+- lib/cuprum/collections/relations/cardinality.rb
+- lib/cuprum/collections/relations/options.rb
+- lib/cuprum/collections/relations/parameters.rb
+- lib/cuprum/collections/relations/primary_keys.rb
+- lib/cuprum/collections/relations/scope.rb
 - lib/cuprum/collections/repository.rb
 - lib/cuprum/collections/resource.rb
 - lib/cuprum/collections/rspec.rb
 - lib/cuprum/collections/rspec/contracts.rb
 - lib/cuprum/collections/rspec/contracts/association_contracts.rb
 - lib/cuprum/collections/rspec/contracts/basic.rb
-- lib/cuprum/collections/rspec/contracts/basic/command_contracts.rb
 - lib/cuprum/collections/rspec/contracts/collection_contracts.rb
 - lib/cuprum/collections/rspec/contracts/command_contracts.rb
 - lib/cuprum/collections/rspec/contracts/query_contracts.rb
 - lib/cuprum/collections/rspec/contracts/relation_contracts.rb
 - lib/cuprum/collections/rspec/contracts/repository_contracts.rb
+- lib/cuprum/collections/rspec/contracts/scope_contracts.rb
+- lib/cuprum/collections/rspec/contracts/scopes.rb
+- lib/cuprum/collections/rspec/contracts/scopes/builder_contracts.rb
+- lib/cuprum/collections/rspec/contracts/scopes/composition_contracts.rb
+- lib/cuprum/collections/rspec/contracts/scopes/criteria_contracts.rb
+- lib/cuprum/collections/rspec/contracts/scopes/logical_contracts.rb
+- lib/cuprum/collections/rspec/deferred.rb
+- lib/cuprum/collections/rspec/deferred/association_examples.rb
+- lib/cuprum/collections/rspec/deferred/collection_examples.rb
+- lib/cuprum/collections/rspec/deferred/command_examples.rb
+- lib/cuprum/collections/rspec/deferred/commands.rb
+- lib/cuprum/collections/rspec/deferred/commands/assign_one_examples.rb
+- lib/cuprum/collections/rspec/deferred/commands/build_one_examples.rb
+- lib/cuprum/collections/rspec/deferred/commands/destroy_one_examples.rb
+- lib/cuprum/collections/rspec/deferred/commands/find_many_examples.rb
+- lib/cuprum/collections/rspec/deferred/commands/find_matching_examples.rb
+- lib/cuprum/collections/rspec/deferred/commands/find_one_examples.rb
+- lib/cuprum/collections/rspec/deferred/commands/insert_one_examples.rb
+- lib/cuprum/collections/rspec/deferred/commands/update_one_examples.rb
+- lib/cuprum/collections/rspec/deferred/commands/validate_one_examples.rb
+- lib/cuprum/collections/rspec/deferred/relation_examples.rb
+- lib/cuprum/collections/rspec/deferred/resource_examples.rb
 - lib/cuprum/collections/rspec/fixtures.rb
+- lib/cuprum/collections/scope.rb
+- lib/cuprum/collections/scopes.rb
+- lib/cuprum/collections/scopes/all.rb
+- lib/cuprum/collections/scopes/all_scope.rb
+- lib/cuprum/collections/scopes/base.rb
+- lib/cuprum/collections/scopes/builder.rb
+- lib/cuprum/collections/scopes/building.rb
+- lib/cuprum/collections/scopes/composition.rb
+- lib/cuprum/collections/scopes/conjunction.rb
+- lib/cuprum/collections/scopes/conjunction_scope.rb
+- lib/cuprum/collections/scopes/container.rb
+- lib/cuprum/collections/scopes/criteria.rb
+- lib/cuprum/collections/scopes/criteria/parser.rb
+- lib/cuprum/collections/scopes/criteria_scope.rb
+- lib/cuprum/collections/scopes/disjunction.rb
+- lib/cuprum/collections/scopes/disjunction_scope.rb
+- lib/cuprum/collections/scopes/none.rb
+- lib/cuprum/collections/scopes/none_scope.rb
 - lib/cuprum/collections/version.rb
 homepage: http://sleepingkingstudios.com
 licenses:
@@ -135,23 +183,21 @@ metadata:
   bug_tracker_uri: https://github.com/sleepingkingstudios/cuprum-collections/issues
   source_code_uri: https://github.com/sleepingkingstudios/cuprum-collections
   rubygems_mfa_required: 'true'
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - "~>"
     - !ruby/object:Gem::Version
-      version: 2.7.0
+      version: '3.1'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.21
-signing_key:
+rubygems_version: 3.6.9
 specification_version: 4
 summary: A data abstraction layer based on the Cuprum library.
 test_files: []

data/lib/cuprum/collections/basic/query_builder.rb

@@ -1,69 +0,0 @@
-# frozen_string_literal: true
-
-require 'cuprum/collections/basic'
-require 'cuprum/collections/query_builder'
-
-module Cuprum::Collections::Basic
-  # Concrete implementation of QueryBuilder for a basic query.
-  class QueryBuilder < Cuprum::Collections::QueryBuilder
-    # @param base_query [Cuprum::Collections::Basic::Query] The original
-    #   query.
-    def initialize(base_query)
-      super
-
-      @filters = base_query.send(:filters)
-    end
-
-    private
-
-    attr_reader :filters
-
-    def build_filters(criteria)
-      criteria.map do |(attribute, operator, value)|
-        send(operator, attribute, value)
-      end
-    end
-
-    def build_query(criteria)
-      super.send(:with_filters, build_filters(criteria))
-    end
-
-    def equal(attribute, value)
-      ->(actual) { actual[attribute.to_s] == value }
-    end
-    alias eq equal
-
-    def greater_than(attribute, value)
-      ->(actual) { actual[attribute.to_s] > value }
-    end
-    alias gt greater_than
-
-    def greater_than_or_equal_to(attribute, value)
-      ->(actual) { actual[attribute.to_s] >= value }
-    end
-    alias gte greater_than_or_equal_to
-
-    def less_than(attribute, value)
-      ->(actual) { actual[attribute.to_s] < value }
-    end
-    alias lt less_than
-
-    def less_than_or_equal_to(attribute, value)
-      ->(actual) { actual[attribute.to_s] <= value }
-    end
-    alias lte less_than_or_equal_to
-
-    def not_equal(attribute, value)
-      ->(actual) { actual[attribute.to_s] != value }
-    end
-    alias ne not_equal
-
-    def not_one_of(attribute, value)
-      ->(actual) { !value.include?(actual[attribute.to_s]) }
-    end
-
-    def one_of(attribute, value)
-      ->(actual) { value.include?(actual[attribute.to_s]) }
-    end
-  end
-end

data/lib/cuprum/collections/command.rb

@@ -1,26 +0,0 @@
-# frozen_string_literal: true
-
-require 'stannum/parameter_validation'
-
-require 'cuprum/collections'
-require 'cuprum/collections/errors/invalid_parameters'
-
-module Cuprum::Collections
-  # Abstract base class for Cuprum::Collection commands.
-  class Command < Cuprum::Command
-    extend  Stannum::ParameterValidation
-    include Stannum::ParameterValidation
-
-    private
-
-    def handle_invalid_parameters(errors:, method_name:)
-      return super unless method_name == :call
-
-      error = Cuprum::Collections::Errors::InvalidParameters.new(
-        command: self,
-        errors:  errors
-      )
-      failure(error)
-    end
-  end
-end

data/lib/cuprum/collections/queries/parse.rb

@@ -1,22 +0,0 @@
-# frozen_string_literal: true
-
-require 'cuprum/collections/queries'
-require 'cuprum/collections/queries/parse_strategy'
-
-module Cuprum::Collections::Queries
-  # Command to parse parameters passed to Query#where into criteria.
-  class Parse < Cuprum::Command
-    private
-
-    def process(where:, strategy: nil)
-      command = step do
-        Cuprum::Collections::Queries::ParseStrategy.new.call(
-          strategy: strategy,
-          where:    where
-        )
-      end
-
-      command.call(where: where)
-    end
-  end
-end

data/lib/cuprum/collections/queries/parse_block.rb

@@ -1,206 +0,0 @@
-# frozen_string_literal: true
-
-require 'forwardable'
-
-require 'cuprum/errors/uncaught_exception'
-require 'stannum/contracts/parameters_contract'
-
-require 'cuprum/collections/command'
-require 'cuprum/collections/constraints/query_hash'
-require 'cuprum/collections/errors/invalid_query'
-require 'cuprum/collections/errors/unknown_operator'
-require 'cuprum/collections/queries'
-
-module Cuprum::Collections::Queries
-  # Command for parsing a Query#where block into criteria.
-  #
-  # @example An Empty Query
-  #   command = Cuprum::Collections::Queries::ParseBlock.new
-  #   result  = command.call { {} }
-  #   result.value #=> []
-  #
-  # @example A Value Query
-  #   command = Cuprum::Collections::Queries::ParseBlock.new
-  #   result  = command.call do
-  #     {
-  #       author: 'Nnedi Okorafor',
-  #       series: 'Binti',
-  #       genre:  'Africanfuturism'
-  #     }
-  #   end
-  #   result.value #=>
-  #   # [
-  #   #   ['author', :eq, 'Nnedi Okorafor'],
-  #   #   ['series', :eq, 'Binti'],
-  #   #   ['genre',  :eq, 'Africanfuturism']
-  #   # ]
-  #
-  # @example A Query With Operators
-  #   command = Cuprum::Collections::Queries::ParseBlock.new
-  #   result  = command.call do
-  #     {
-  #       author: equal('Nnedi Okorafor'),
-  #       series: not_equal('Binti')
-  #     }
-  #   end
-  #   result.value #=>
-  #   # [
-  #   #   ['author', :eq, 'Nnedi Okorafor'],
-  #   #   ['series', :ne, 'Binti']
-  #   # ]
-  class ParseBlock < Cuprum::Collections::Command
-    # Evaluation context for query blocks.
-    class Builder < BasicObject
-      # Generates an equality criterion.
-      #
-      # @return [Array] the equality criterion.
-      def equals(value)
-        [nil, Operators::EQUAL, value]
-      end
-      alias equal equals
-      alias eq equals
-
-      # Generates a greater than comparison criterion.
-      #
-      # @return [Array] the greater than criterion.
-      def greater_than(value)
-        [nil, Operators::GREATER_THAN, value]
-      end
-      alias gt greater_than
-
-      # Generates a greater than or equal to comparison criterion.
-      #
-      # @return [Array] the greater than or equal to criterion.
-      def greater_than_or_equal_to(value)
-        [nil, Operators::GREATER_THAN_OR_EQUAL_TO, value]
-      end
-      alias gte greater_than_or_equal_to
-
-      # Generates a less than comparison criterion.
-      #
-      # @return [Array] the less than criterion.
-      def less_than(value)
-        [nil, Operators::LESS_THAN, value]
-      end
-      alias lt less_than
-
-      # Generates a less than or equal to comparison criterion.
-      #
-      # @return [Array] the less than or equal to criterion.
-      def less_than_or_equal_to(value)
-        [nil, Operators::LESS_THAN_OR_EQUAL_TO, value]
-      end
-      alias lte less_than_or_equal_to
-
-      # Generates a negated equality criterion.
-      #
-      # @return [Array] the negated equality criterion.
-      def not_equal(value)
-        [nil, Operators::NOT_EQUAL, value]
-      end
-      alias ne not_equal
-
-      # Generates a negated inclusion criterion.
-      #
-      # @return [Array] the negated inclusion criterion.
-      def not_one_of(value)
-        [nil, Operators::NOT_ONE_OF, value]
-      end
-
-      # Generates an inclusion criterion.
-      #
-      # @return [Array] the inclusion criterion.
-      def one_of(value)
-        [nil, Operators::ONE_OF, value]
-      end
-    end
-
-    class << self
-      extend Forwardable
-
-      def_delegators :validation_contract,
-        :errors_for,
-        :match,
-        :matches?
-
-      private
-
-      def validation_contract
-        self::MethodValidations.contracts.fetch(:call)
-      end
-    end
-
-    validate_parameters :call do
-      keyword :where, Proc
-    end
-
-    private
-
-    def call_block(&block)
-      handle_unknown_operator { Builder.new.instance_exec(&block) }
-    rescue StandardError => exception
-      error = Cuprum::Errors::UncaughtException.new(
-        exception: exception,
-        message:   'uncaught exception when parsing query block'
-      )
-
-      failure(error)
-    end
-
-    def generate_criteria(hsh)
-      hsh.map do |key, value|
-        unless partial_criterion?(value)
-          next [key.to_s, Cuprum::Collections::Queries::Operators::EQUAL, value]
-        end
-
-        value.tap { |ary| ary[0] = key.to_s }
-      end
-    end
-
-    def handle_unknown_operator
-      yield
-    rescue NoMethodError => exception
-      error = Cuprum::Collections::Errors::UnknownOperator.new(
-        operator: exception.name
-      )
-
-      failure(error)
-    end
-
-    def invalid_query_error(errors:, message: nil)
-      Cuprum::Collections::Errors::InvalidQuery.new(
-        errors:   errors,
-        message:  message,
-        strategy: :block
-      )
-    end
-
-    def partial_criterion?(obj)
-      return false unless obj.is_a?(Array) && obj.size == 3
-
-      attribute, operator, _value = obj
-
-      return false unless attribute.nil?
-
-      Cuprum::Collections::Queries::VALID_OPERATORS.include?(operator)
-    end
-
-    def process(where:)
-      hsh = step { call_block(&where) }
-
-      step { validate_hash(hsh) }
-
-      generate_criteria(hsh)
-    end
-
-    def validate_hash(obj)
-      constraint    = Cuprum::Collections::Constraints::QueryHash.new
-      match, errors = constraint.match(obj)
-
-      return if match
-
-      message = 'query block returned invalid value'
-      failure(invalid_query_error(errors: errors, message: message))
-    end
-  end
-end

data/lib/cuprum/collections/queries/parse_strategy.rb

@@ -1,91 +0,0 @@
-# frozen_string_literal: true
-
-require 'cuprum/collections/queries'
-require 'cuprum/collections/queries/parse_block'
-require 'cuprum/collections/errors/invalid_query'
-
-module Cuprum::Collections::Queries
-  # Command to select the parsing strategy for parsing Query#where parameters.
-  class ParseStrategy < Cuprum::Command
-    STRATEGIES = {
-      block: Cuprum::Collections::Queries::ParseBlock
-    }.freeze
-    private_constant :STRATEGIES
-
-    # The :type of the error generated for an unknown parsing strategy.
-    UNKNOWN_STRATEGY_ERROR =
-      'cuprum.collections.errors.queries.unknown_strategy'
-
-    private
-
-    def find_and_validate_strategy(strategy:, where:)
-      command_class = step { find_strategy_by_key(strategy: strategy) }
-      parameters    = {
-        arguments: [],
-        block:     nil,
-        keywords:  { where: where }
-      }
-
-      return command_class if command_class.matches?(parameters)
-
-      errors = command_class.errors_for(parameters)
-
-      failure(invalid_parameters_error(errors: errors, strategy: strategy))
-    end
-
-    def find_strategy(strategy:, where:)
-      if strategy
-        return find_and_validate_strategy(strategy: strategy, where: where)
-      end
-
-      command_class = find_strategy_by_parameters(where: where)
-
-      return command_class if command_class
-
-      failure(unknown_strategy_error(strategy: strategy))
-    end
-
-    def find_strategy_by_key(strategy:)
-      STRATEGIES.fetch(strategy) do
-        failure(unknown_strategy_error(strategy: strategy))
-      end
-    end
-
-    def find_strategy_by_parameters(where:)
-      STRATEGIES
-        .values
-        .find do |command_class|
-          command_class.matches?(
-            arguments: [],
-            block:     nil,
-            keywords:  { where: where }
-          )
-        end
-    end
-
-    def invalid_parameters_error(errors:, strategy:)
-      Cuprum::Collections::Errors::InvalidQuery.new(
-        errors:   errors,
-        strategy: strategy
-      )
-    end
-
-    def process(strategy: nil, where: nil)
-      command_class = step do
-        find_strategy(strategy: strategy, where: where)
-      end
-
-      command_class.new
-    end
-
-    def unknown_strategy_error(strategy:)
-      errors = Stannum::Errors.new
-      errors[:strategy].add(UNKNOWN_STRATEGY_ERROR, strategy: strategy)
-
-      Cuprum::Collections::Errors::InvalidQuery.new(
-        errors:   errors,
-        strategy: strategy
-      )
-    end
-  end
-end

data/lib/cuprum/collections/query_builder.rb

@@ -1,61 +0,0 @@
-# frozen_string_literal: true
-
-require 'cuprum/collections'
-require 'cuprum/collections/queries/parse'
-
-module Cuprum::Collections
-  # Internal class that handles parsing and applying criteria to a query.
-  class QueryBuilder
-    # Exception class to be raised when the query cannot be parsed.
-    class ParseError < RuntimeError; end
-
-    # @param base_query [Cuprum::Collections::Query] The original query.
-    def initialize(base_query)
-      @base_query = base_query
-    end
-
-    # @return [Cuprum::Collections::Query] the original query.
-    attr_reader :base_query
-
-    # Returns a copy of the query updated with the generated criteria.
-    #
-    # Classifies the parameters to determine parsing strategy, then uses that
-    # strategy to parse the parameters into an array of criteria. Then, copies
-    # the original query and updates the copy with the parsed criteria.
-    #
-    # @param strategy [Symbol, nil] The specified strategy for parsing the given
-    #   filter into criteria. If nil, the builder will attempt to guess the
-    #   strategy based on the given filter.
-    # @param where [Object] The filter used to match items in the collection.
-    #
-    # @return [Cuprum::Collections::Query] the copied and updated query.
-    def call(where:, strategy: nil)
-      criteria =
-        if strategy == :unsafe
-          where
-        else
-          parse_criteria(strategy: strategy, where: where)
-        end
-
-      build_query(criteria)
-    end
-
-    private
-
-    def build_query(criteria)
-      base_query
-        .dup
-        .send(:with_criteria, criteria)
-    end
-
-    def parse_criteria(strategy:, where:)
-      result = Cuprum::Collections::Queries::Parse
-        .new
-        .call(strategy: strategy, where: where)
-
-      return result.value if result.success?
-
-      raise ParseError, result.error.message
-    end
-  end
-end