cuprum-collections 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9a2dd2e704041cbdb689bca94afa13c5803ada5cb0601d7c0870cea1c6740830
-  data.tar.gz: 0fc7380322c9dbb547354408dbe8fd513ef792c7cb8ee0000aef2b94ef68f921
+  metadata.gz: 9a123357ad584d32ba68c2b37f5b8a66b40ff3c17ccd516cdb2cbe9b3a03aa49
+  data.tar.gz: b585c2ad781f2fb534bfaccc9999c039519f4a612aaa5c6ad153c4f74fe8f821
 SHA512:
-  metadata.gz: 34ed0e5a7d1f528466cc8de3cba741e53143d5defdae69bf1b6daaa5705f715444a92bd0b0b2d8e325c1a6c6ed6c5433760bcb3a6cb357dabf3cd8cf04771311
-  data.tar.gz: c4ff7c90ce097e3d59e21ac633157358f20571210eee14c4b5b279dc8e16adf05391d6aa1b7205773821775216e859952259f8becf21a054aae24c5d253f90c1
+  metadata.gz: 78fd0fe599f33cf43bf2bd31adadd0d5a086e4770593deceed206e6dc990378547cae6d6c1f18e16fecb96e13558793a32af3b32777296c9d0bad0ac1ea1001b
+  data.tar.gz: 18aef11051a058e8ed51ebed3263e0280339f279f22485fe5069bc3d5c2830d8bc18b3fab961e2204f2c967f4a12d70ec4f10fb4625f0f634f9c57db8e2e24a9

data/CHANGELOG.md

@@ -1,5 +1,78 @@
 # Changelog
 
+## 0.5.0
+
+Major refactoring of Queries. This update is **not** backwards compatible.
+
+### Collections
+
+Collection commands no longer define the command subclass, e.g. `rockets_collection::Launch`. Instances of the command can still be created using `rockets_collection#launch`.
+
+### Commands
+
+Refactored commands to use more lightweight parameter validation from `SleepingKingStudios::Tools`.
+
+### Queries
+
+Query result filtering now uses composable scopes.
+
+- Implemented `Query#scope`.
+- Implemented composable methods `Query#and`, `Query#or`, `Query#not`.
+
+Performing block queries with an implicit receiver is now deprecated. Instead of:
+
+`where { { author: eq('J.R.R. Tolkien) } }`
+
+An explicit receiver must be passed to be block in order to use operators:
+
+`where { |query| { author: query.eq('J.R.R. Tolkien) } }`
+
+### Relations
+
+Extracted `Cuprum::Collections::Relations` concerns.
+
+- Added `#scope` support to `Cuprum::Collections::Resource`.
+
+### RSpec
+
+Migrated shared contract objects to deferred example groups:
+
+- `Cuprum::Collections::RSpec::Deferred::AssociationExamples`
+- `Cuprum::Collections::RSpec::Deferred::CollectionExamples`
+- `Cuprum::Collections::RSpec::Deferred::CommandExamples`
+- `Cuprum::Collections::RSpec::Deferred::Commands::*`
+- `Cuprum::Collections::RSpec::Deferred::RelationExamples`
+- `Cuprum::Collections::RSpec::Deferred::ResourceExamples`
+
+The corresponding contracts are now deprecated.
+
+### Scopes
+
+Implemented `Cuprum::Collections::Scopes`. A scope object represents a filter that can be used to select a subset of a collection.
+
+`Cuprum::Collections` defines generic scope classes for defining scopes in a collection-independant fashion. Each collection must also implement the filtering behavior for each scope type.
+
+#### Criteria Scopes
+
+Criteria scopes use a list of criteria to filter data. Each criterion has an attribute name, an operator (such as "equals", "greater than" or "not in"), and an expected value.
+
+#### Logical Scopes
+
+Conjunction scopes wrap one or more other scopes with a logical AND operation.
+
+Disjunction scopes wrap one or more other scopes with a logical OR operation.
+
+#### Scope Inversion
+
+Scopes are responsible for defining their own inverse. An inverted scope should match on a collection item if and only if the base scope does not match that item.
+
+### Other Changes
+
+Remove deprecations from previous versions:
+
+- Removed `Cuprum::Collections::Relation::Disambiguation`.
+- Removed initializing an `AbstractFindError` subclass with `primary_key_name` and `primary_key_values` keywords.
+
 ## 0.4.0
 
 ### Associations

data/README.md

@@ -26,7 +26,7 @@ The Ruby ecosystem has a wide variety of tools and libraries for managing data a
 
 ### Compatibility
 
-Cuprum::Collections is tested against Ruby (MRI) 2.7 through 3.2.
+Cuprum::Collections is tested against Ruby (MRI) 3.1 through 3.4.
 
 ### Documentation
 
@@ -34,7 +34,7 @@ Documentation is generated using [YARD](https://yardoc.org/), and can be generat
 
 ### License
 
-Copyright (c) 2020-2023 Rob Smith
+Copyright (c) 2020-2025 Rob Smith
 
 Cuprum::Collections is released under the [MIT License](https://opensource.org/licenses/MIT).
 
@@ -882,11 +882,11 @@ query.each.map(&:author).uniq
 The simplest way to filter results is by passing a `Hash` to `#where`. The keys of the Hash should be the names of the attributes to filter by, and the values the expected value of that attribute. However, passing a Hash directly only supports equality comparisons. To use advanced operators, use the block form:
 
 ```ruby
-query = collection.query.where do
+query = collection.query.where do |scope|
   {
     author:       'Ursula K. LeGuin',
-    series:       equal('Earthsea'),
-    published_at: greater_than('1970-01-01')
+    series:       scope.equal('Earthsea'),
+    published_at: scope.greater_than('1970-01-01')
   }
 end
 query.count

data/lib/cuprum/collections/association.rb

@@ -31,33 +31,14 @@ module Cuprum::Collections
     #   @option options singular_inverse_name [String, Symbol] the name of an
     #     entity in the inverse association.
     def initialize(**params)
-      params = disambiguate_keyword(params, :entity_class, :association_class)
-      params = disambiguate_keyword(params, :name, :association_name)
+      super(**params.except(:inverse))
 
-      @inverse = params.delete(:inverse)
-
-      super(**params)
+      @inverse = params[:inverse]
     end
 
     # @return [Cuprum::Collections::Resource] the inverse association, if any.
     attr_reader :inverse
 
-    # @return [Class] the class of entity represented by the resource.
-    def association_class
-      tools.core_tools.deprecate '#association_class method',
-        message: 'Use #entity_class instead'
-
-      entity_class
-    end
-
-    # @return [String] the name of the resource.
-    def association_name
-      tools.core_tools.deprecate '#association_name method',
-        message: 'Use #name instead'
-
-      name
-    end
-
     # Generates a query for finding matching items.
     #
     # @param entities [Array] the entities to query for.
@@ -71,12 +52,12 @@ module Cuprum::Collections
       keys =
         map_entities_to_keys(
           *entities,
-          allow_nil:   allow_nil,
-          deduplicate: deduplicate,
+          allow_nil:,
+          deduplicate:,
           strict:      true
         )
 
-      build_keys_query(*keys, allow_nil: allow_nil, deduplicate: false)
+      build_keys_query(*keys, allow_nil:, deduplicate: false)
     end
 
     # Generates a query for finding matching items by key.
@@ -94,11 +75,11 @@ module Cuprum::Collections
       hash_key = query_key_name
 
       if keys.empty?
-        -> { {} }
+        ->(_) { {} }
       elsif keys.size == 1
-        -> { { hash_key => keys.first } }
+        ->(_) { { hash_key => keys.first } }
       else
-        -> { { hash_key => one_of(keys) } }
+        ->(scope) { { hash_key => scope.one_of(keys) } }
       end
     end
 
@@ -154,7 +135,7 @@ module Cuprum::Collections
     )
       entities
         .compact
-        .map { |entity| map_entity_to_key(entity, strict: strict) }
+        .map { |entity| map_entity_to_key(entity, strict:) }
         .then { |keys| allow_nil ? keys : keys.compact }
         .then { |keys| deduplicate ? keys.uniq : keys }
     end

data/lib/cuprum/collections/associations/belongs_to.rb

@@ -8,10 +8,7 @@ module Cuprum::Collections::Associations
   class BelongsTo < Cuprum::Collections::Association
     # (see Cuprum::Collections::Association#initialize)
     def initialize(**params)
-      params.delete(:plural)
-      params.delete(:singular)
-
-      super(**params, singular: true)
+      super(**params.except(:plural), singular: true)
     end
 
     # (see Cuprum::Collections::Association#primary_key_query?)
@@ -24,9 +21,5 @@ module Cuprum::Collections::Associations
     def default_foreign_key_name
       singular_name&.then { |str| "#{str}_id" }
     end
-
-    def ignored_parameters
-      @ignored_parameters ||= Set.new(IGNORED_PARAMETERS + %i[singular])
-    end
   end
 end

data/lib/cuprum/collections/associations/has_many.rb

@@ -8,16 +8,7 @@ module Cuprum::Collections::Associations
   class HasMany < Cuprum::Collections::Association
     # (see Cuprum::Collections::Association#initialize)
     def initialize(**params)
-      params.delete(:plural)
-      params.delete(:singular)
-
-      super(**params, singular: false)
-    end
-
-    private
-
-    def ignored_parameters
-      @ignored_parameters ||= Set.new(IGNORED_PARAMETERS + %i[singular])
+      super(**params.except(:plural), singular: false)
     end
   end
 end

data/lib/cuprum/collections/associations/has_one.rb

@@ -8,16 +8,7 @@ module Cuprum::Collections::Associations
   class HasOne < Cuprum::Collections::Association
     # (see Cuprum::Collections::Association#initialize)
     def initialize(**params)
-      params.delete(:plural)
-      params.delete(:singular)
-
-      super(**params, singular: true)
-    end
-
-    private
-
-    def ignored_parameters
-      @ignored_parameters ||= Set.new(IGNORED_PARAMETERS + %i[singular])
+      super(**params.except(:plural), singular: true)
     end
   end
 end

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

@@ -4,6 +4,7 @@ require 'cuprum/command_factory'
 
 require 'cuprum/collections/basic'
 require 'cuprum/collections/basic/commands'
+require 'cuprum/collections/basic/scopes/all_scope'
 require 'cuprum/collections/collection'
 
 module Cuprum::Collections::Basic
@@ -13,29 +14,20 @@ module Cuprum::Collections::Basic
     #   @param data [Array<Hash>] the current data in the collection.
     #   @param entity_class [Class, String] the class of entity represented by
     #     the relation.
-    #   @param name [String] the name of the relation. Aliased as
-    #     :collection_name.
+    #   @param name [String] the name of the relation.
     #   @param qualified_name [String] a scoped name for the relation.
     #   @param singular_name [String] the name of an entity in the relation.
-    #     Aliased as :member_name.
     #   @param options [Hash] additional options for the relation.
     #
     #   @option options primary_key_name [String] the name of the primary key
     #     attribute. Defaults to 'id'.
-    #   @option primary_key_type [Class, Stannum::Constraint] the type of
-    #     the primary key attribute. Defaults to Integer.
-    def initialize(data: [], entity_class: Hash, **parameters)
-      qualified_name = parameters.fetch(:qualified_name) do
-        next nil unless entity_class == Hash
-
-        parameters.fetch(:collection_name, parameters[:name])
-      end
-
-      super(
-        entity_class:   entity_class,
-        qualified_name: qualified_name,
-        **parameters
-      )
+    #   @option options primary_key_type [Class, Stannum::Constraint] the type
+    #     of the primary key attribute. Defaults to Integer.
+    #   @option options scope
+    #     [Cuprum::Collections::Scopes::Base, Hash, Proc, nil] the configured
+    #     scope for the relation.
+    def initialize(data: [], **parameters)
+      super(**normalize_parameters(**parameters))
 
       @data = data
     end
@@ -43,49 +35,40 @@ module Cuprum::Collections::Basic
     # @return [Array<Hash>] the current data in the collection.
     attr_reader :data
 
-    command_class :assign_one do
-      Cuprum::Collections::Basic::Commands::AssignOne
-        .subclass(**command_options)
+    command :assign_one do
+      Cuprum::Collections::Basic::Commands::AssignOne.new(collection: self)
     end
 
-    command_class :build_one do
-      Cuprum::Collections::Basic::Commands::BuildOne
-        .subclass(**command_options)
+    command :build_one do
+      Cuprum::Collections::Basic::Commands::BuildOne.new(collection: self)
     end
 
-    command_class :destroy_one do
-      Cuprum::Collections::Basic::Commands::DestroyOne
-        .subclass(**command_options)
+    command :destroy_one do
+      Cuprum::Collections::Basic::Commands::DestroyOne.new(collection: self)
     end
 
-    command_class :find_many do
-      Cuprum::Collections::Basic::Commands::FindMany
-        .subclass(**command_options)
+    command :find_many do
+      Cuprum::Collections::Basic::Commands::FindMany.new(collection: self)
     end
 
-    command_class :find_matching do
-      Cuprum::Collections::Basic::Commands::FindMatching
-        .subclass(**command_options)
+    command :find_matching do
+      Cuprum::Collections::Basic::Commands::FindMatching.new(collection: self)
     end
 
-    command_class :find_one do
-      Cuprum::Collections::Basic::Commands::FindOne
-        .subclass(**command_options)
+    command :find_one do
+      Cuprum::Collections::Basic::Commands::FindOne.new(collection: self)
     end
 
-    command_class :insert_one do
-      Cuprum::Collections::Basic::Commands::InsertOne
-        .subclass(**command_options)
+    command :insert_one do
+      Cuprum::Collections::Basic::Commands::InsertOne.new(collection: self)
     end
 
-    command_class :update_one do
-      Cuprum::Collections::Basic::Commands::UpdateOne
-        .subclass(**command_options)
+    command :update_one do
+      Cuprum::Collections::Basic::Commands::UpdateOne.new(collection: self)
     end
 
-    command_class :validate_one do
-      Cuprum::Collections::Basic::Commands::ValidateOne
-        .subclass(**command_options)
+    command :validate_one do
+      Cuprum::Collections::Basic::Commands::ValidateOne.new(collection: self)
     end
 
     # @return [Stannum::Constraints::Base, nil] the #   default contract for
@@ -98,16 +81,40 @@ module Cuprum::Collections::Basic
     #
     # @return [Cuprum::Collections::Basic::Query] the query.
     def query
-      Cuprum::Collections::Basic::Query.new(data)
+      Cuprum::Collections::Basic::Query.new(data, scope:)
     end
 
     protected
 
-    def command_options
-      super().merge(
-        data:             data,
-        default_contract: default_contract
+    def comparable_options
+      @comparable_options ||= super.merge(
+        data:,
+        default_contract:
       )
     end
+
+    private
+
+    def default_scope
+      Cuprum::Collections::Basic::Scopes::AllScope.new
+    end
+
+    def normalize_parameters(**parameters) # rubocop:disable Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
+      return parameters if parameters.key?(:entity_class)
+
+      return parameters unless parameters[:name] || parameters[:qualified_name]
+
+      parameters = parameters.merge(entity_class: Hash)
+
+      if parameters.key?(:name) && parameters.key?(:qualified_name)
+        parameters
+      elsif parameters.key?(:name)
+        parameters.merge(qualified_name: parameters[:name])
+      elsif parameters.key?(:qualified_name)
+        name = parameters[:qualified_name].split('/').last
+
+        parameters.merge(name:)
+      end
+    end
   end
 end

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

@@ -6,107 +6,41 @@ require 'cuprum/collections/basic'
 
 module Cuprum::Collections::Basic
   # Abstract base class for basic collection commands.
-  class Command < Cuprum::Collections::Command
-    # Creates a subclass with the given parameters applied to the constructor.
-    def self.subclass(**default_options)
-      Class.new(self) do
-        define_method(:initialize) do |**options|
-          super(**default_options.merge(options))
-        end
-      end
-    end
-
-    # @param collection_name [String, Symbol] The name of the collection.
-    # @param data [Array<Hash>] The current data in the collection.
-    # @param default_contract [Stannum::Constraints::Base, nil] The default
-    #   contract for validating items in the collection.
-    # @param member_name [String] The name of a collection entity.
-    # @param primary_key_name [Symbol] The name of the primary key attribute.
-    #   Defaults to :id.
-    # @param primary_key_type [Class, Stannum::Constraint] The type of the
-    #   primary key attribute. Defaults to Integer.
-    # @param options [Hash<Symbol>] Additional options for the command.
-    def initialize( # rubocop:disable Metrics/ParameterLists
-      collection_name:,
-      data:,
-      default_contract: nil,
-      member_name:      nil,
-      primary_key_name: :id,
-      primary_key_type: Integer,
-      **options
-    )
-      super()
-
-      @collection_name  = collection_name.to_s
-      @data             = data
-      @default_contract = default_contract
-      @member_name      =
-        member_name ? member_name.to_s : tools.str.singularize(@collection_name)
-      @options          = options
-      @primary_key_name = primary_key_name
-      @primary_key_type = primary_key_type
-    end
-
-    # @return [String] the name of the collection.
-    attr_reader :collection_name
-
+  class Command < Cuprum::Collections::CollectionCommand
     # @return [Array<Hash>] the current data in the collection.
-    attr_reader :data
+    def data
+      collection.data
+    end
 
     # @return [Stannum::Constraints::Base, nil] the default contract for
     #   validating items in the collection.
-    attr_reader :default_contract
-
-    # @return [String] the name of a collection entity.
-    attr_reader :member_name
-
-    # @return [Hash<Symbol>] additional options for the command.
-    attr_reader :options
-
-    # @return [Symbol] the name of the primary key attribute.
-    attr_reader :primary_key_name
-
-    # @return [Class, Stannum::Constraint] the type of the primary key
-    #   attribute.
-    attr_reader :primary_key_type
+    def default_contract
+      @default_contract ||= collection.default_contract
+    end
 
     private
 
-    def primary_key_contract
-      type = primary_key_type
+    def validate_entity(value, as: 'entity') # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+      return error_message_for(as:, expected: Hash) unless value.is_a?(Hash)
 
-      @primary_key_contract ||= Stannum::Contracts::ParametersContract.new do
-        keyword :primary_key, type
-      end
-    end
+      return [] if value.empty?
 
-    def primary_keys_contract
-      type = primary_key_type
+      validator = tools.assertions.aggregator_class.new
 
-      @primary_keys_contract ||= Stannum::Contracts::ParametersContract.new do
-        keyword :primary_keys,
-          Stannum::Constraints::Types::ArrayType.new(item_type: type)
-      end
-    end
+      value.each_key do |key|
+        unless key.nil? || key.is_a?(String)
+          validator << error_message_for(
+            as:       "#{as}[#{key.inspect}] key",
+            expected: String
+          )
 
-    def tools
-      SleepingKingStudios::Tools::Toolbelt.instance
-    end
+          next
+        end
 
-    def validate_primary_key(primary_key)
-      match_parameters_to_contract(
-        contract:    primary_key_contract,
-        keywords:    { primary_key: primary_key },
-        method_name: :call
-      )
-    end
+        validator.validate_presence(key, as: "#{as}[#{key.inspect}] key")
+      end
 
-    def validate_primary_keys(primary_keys)
-      match_parameters_to_contract(
-        contract:    primary_keys_contract,
-        keywords:    { primary_keys: primary_keys },
-        method_name: :call
-      )
+      validator.each.to_a
     end
   end
 end

data/lib/cuprum/collections/basic/commands/assign_one.rb

@@ -36,12 +36,8 @@ module Cuprum::Collections::Basic::Commands
     #       'series'   => nil,
     #       'category' => 'Science Fiction and Fantasy'
     #     }
-    validate_parameters :call do
-      keyword :attributes,
-        Stannum::Constraints::Types::HashWithIndifferentKeys.new
-      keyword :entity,
-        Stannum::Constraints::Types::HashWithStringKeys.new
-    end
+    validate :attributes
+    validate :entity
 
     private
 

data/lib/cuprum/collections/basic/commands/build_one.rb

@@ -31,10 +31,7 @@ module Cuprum::Collections::Basic::Commands
     #       'series'   => nil,
     #       'category' => 'Science Fiction and Fantasy'
     #     }
-    validate_parameters :call do
-      keyword :attributes,
-        Stannum::Constraints::Types::HashWithIndifferentKeys.new
-    end
+    validate :attributes
 
     private
 

data/lib/cuprum/collections/basic/commands/destroy_one.rb

@@ -18,9 +18,7 @@ module Cuprum::Collections::Basic::Commands
     #
     #   @return [Cuprum::Result<Hash{String, Object}>] a result with the
     #     destroyed item.
-    validate_parameters :call do
-      keyword :primary_key, Object
-    end
+    validate :primary_key
 
     private
 
@@ -30,18 +28,16 @@ module Cuprum::Collections::Basic::Commands
       error = Cuprum::Collections::Errors::NotFound.new(
         attribute_name:  primary_key_name,
         attribute_value: primary_key,
-        collection_name: collection_name,
+        collection_name:,
         primary_key:     true
       )
-      Cuprum::Result.new(error: error)
+      Cuprum::Result.new(error:)
     end
 
     def process(primary_key:)
-      step { validate_primary_key(primary_key) }
-
       index = data.index { |item| item[primary_key_name.to_s] == primary_key }
 
-      step { handle_missing_item(index: index, primary_key: primary_key) }
+      step { handle_missing_item(index:, primary_key:) }
 
       data.delete_at(index)
     end

data/lib/cuprum/collections/basic/commands/find_many.rb

@@ -11,7 +11,7 @@ module Cuprum::Collections::Basic::Commands
   class FindMany < Cuprum::Collections::Basic::Command
     include Cuprum::Collections::Commands::AbstractFindMany
 
-    # @!method call(primary_keys:, allow_partial: false, envelope: false, scope: nil)
+    # @!method call(primary_keys:, allow_partial: false, envelope: false)
     #   Queries the collection for the items with the given primary keys.
     #
     #   The command will find and return the entities with the given primary
@@ -27,39 +27,19 @@ module Cuprum::Collections::Basic::Commands
     #     found.
     #   @param envelope [Boolean] If true, wraps the result value in a Hash.
     #   @param primary_keys [Array] The primary keys of the requested items.
-    #   @param scope [Cuprum::Collections::Basic::Query, nil] Optional scope for
-    #     the query. Items must match the scope as well as the primary keys.
     #
     #   @return [Cuprum::Result<Array<Hash{String, Object}>>] a result with the
     #     requested items.
-    validate_parameters :call do
-      keyword :allow_partial, Stannum::Constraints::Boolean.new, default: true
-      keyword :envelope,      Stannum::Constraints::Boolean.new, default: true
-      keyword :primary_keys,  Array
-      keyword :scope,         Cuprum::Collections::Basic::Query, optional: true
-    end
+    validate :allow_partial, :boolean, optional: true
+    validate :envelope,      :boolean, optional: true
+    validate :primary_keys
 
     private
 
-    def build_query
-      Cuprum::Collections::Basic::Query.new(data)
-    end
-
     def items_with_primary_keys(items:)
       # :nocov:
       items.to_h { |item| [item[primary_key_name.to_s], item] }
       # :nocov:
     end
-
-    def process(
-      primary_keys:,
-      allow_partial: false,
-      envelope:      false,
-      scope:         nil
-    )
-      step { validate_primary_keys(primary_keys) }
-
-      super
-    end
   end
 end