cuprum-collections 0.4.0 → 0.5.0

data/lib/cuprum/collections/relations/primary_keys.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require 'cuprum/collections/relations'
+
+module Cuprum::Collections::Relations
+  # Methods for specifying a relation's primary key.
+  module PrimaryKeys
+    # @return [String] the name of the primary key attribute. Defaults to
+    #   'id'.
+    def primary_key_name
+      @primary_key_name ||= options.fetch(:primary_key_name, 'id').to_s
+    end
+
+    # @return [Class, Stannum::Constraint] the type of the primary key
+    #   attribute. Defaults to Integer.
+    def primary_key_type
+      @primary_key_type ||=
+        options
+          .fetch(:primary_key_type, Integer)
+          .then { |obj| obj.is_a?(String) ? Object.const_get(obj) : obj }
+    end
+  end
+end

data/lib/cuprum/collections/relations/scope.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require 'cuprum/collections/relations'
+
+module Cuprum::Collections::Relations
+  # Methods for defining a scope for a relation.
+  module Scope
+    # @overload initialize(scope: nil, **)
+    #   @param scope [Cuprum::Collections::Scopes::Base, Hash, Proc, nil] the
+    #     configured scope for the relation.
+    def initialize(scope: nil, **parameters)
+      super(**parameters)
+
+      @scope = apply_scope(default_scope, scope)
+    end
+
+    # @return [Cuprum::Collections::Scopes::Base] the configured scope for the
+    #   relation.
+    attr_reader :scope
+
+    # @overload with_scope(scope)
+    #   Copies the relation and applies the scope to the copy.
+    #
+    #   @param scope [Cuprum::Collections::Scopes::Base, Hash, Proc] the scope
+    #     to apply. The scope will be combined with the existing scope on the
+    #     relation, if any.
+    #
+    #   @return [Cuprum::Collections::Relations::Scope] the copy of the
+    #     relation.
+    #
+    # @overload with_scope(&block)
+    #   Copies the relation and applies the scope to the copy.
+    #
+    #   @yieldparam query
+    #     [Cuprum::Collections::Scopes::Criteria::Parser::BlockParser] the
+    #     receiver for the scope block.
+    #   @yieldreturn [Hash] the query hash for the scope.
+    #
+    #   @return [Cuprum::Collections::Relations::Scope] the copy of the
+    #     relation.
+    def with_scope(value = nil, &block)
+      dup.tap { |copy| copy.scope = apply_scope(scope, value || block) }
+    end
+
+    protected
+
+    attr_writer :scope
+
+    private
+
+    def apply_scope(current_scope, scope)
+      if scope.is_a?(Proc)
+        current_scope.and(&scope)
+      elsif scope
+        current_scope.and(scope)
+      else
+        current_scope
+      end
+    end
+
+    def default_scope
+      Cuprum::Collections::Scopes::AllScope.new
+    end
+  end
+end

data/lib/cuprum/collections/relations.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require 'cuprum/collections'
+
+module Cuprum::Collections
+  # Namespace for Relation-specific functionality.
+  module Relations
+    autoload :Cardinality, 'cuprum/collections/relations/cardinality'
+    autoload :Options,     'cuprum/collections/relations/options'
+    autoload :Parameters,  'cuprum/collections/relations/parameters'
+    autoload :PrimaryKeys, 'cuprum/collections/relations/primary_keys'
+    autoload :Scope,       'cuprum/collections/relations/scope'
+  end
+end

data/lib/cuprum/collections/repository.rb

@@ -3,7 +3,7 @@
 require 'forwardable'
 
 require 'cuprum/collections'
-require 'cuprum/collections/relation'
+require 'cuprum/collections/relations/parameters'
 
 module Cuprum::Collections
   # A repository represents a group of collections.
@@ -101,7 +101,7 @@ module Cuprum::Collections
     def create(force: false, **options)
       collection = build_collection(**options)
 
-      add(collection, force: force)
+      add(collection, force:)
 
       collection
     end
@@ -153,13 +153,13 @@ module Cuprum::Collections
     end
 
     def qualified_name_for(**parameters)
-      Cuprum::Collections::Relation::Disambiguation
-        .resolve_parameters(parameters, name: :collection_name)
+      Cuprum::Collections::Relations::Parameters
+        .resolve_parameters(parameters)
         .fetch(:qualified_name)
     end
 
     def valid_collection?(collection)
-      collection.respond_to?(:collection_name)
+      collection.respond_to?(:qualified_name)
     end
 
     def validate_collection!(collection)

data/lib/cuprum/collections/resource.rb

@@ -2,19 +2,21 @@
 
 require 'cuprum/collections'
 require 'cuprum/collections/relation'
+require 'cuprum/collections/relations/cardinality'
+require 'cuprum/collections/relations/primary_keys'
+require 'cuprum/collections/relations/scope'
 
 module Cuprum::Collections
   # Class representing a singular or plural resource of entities.
   class Resource < Cuprum::Collections::Relation
-    include Cuprum::Collections::Relation::Cardinality
-    include Cuprum::Collections::Relation::Disambiguation
-    include Cuprum::Collections::Relation::PrimaryKeys
+    include Cuprum::Collections::Relations::Cardinality
+    include Cuprum::Collections::Relations::PrimaryKeys
+    include Cuprum::Collections::Relations::Scope
 
     # @overload initialize(entity_class: nil, name: nil, qualified_name: nil, singular_name: nil, **options)
     #   @param entity_class [Class, String] the class of entity represented by
     #     the resource.
-    #   @param name [String] the name of the resource. Aliased as
-    #     :resource_name.
+    #   @param name [String] the name of the resource.
     #   @param qualified_name [String] a scoped name for the resource.
     #   @param singular_name [String] the name of an entity in the resource.
     #   @param options [Hash] additional options for the resource.
@@ -25,41 +27,8 @@ module Cuprum::Collections
     #     attribute. Defaults to 'id'.
     #   @option primary_key_type [Class, Stannum::Constraint] the type of
     #     the primary key attribute. Defaults to Integer.
-    def initialize(**params)
-      params  = disambiguate_keyword(params, :entity_class, :resource_class)
-      params  = disambiguate_keyword(params, :name, :resource_name)
-      params  = disambiguate_keyword(
-        params,
-        :singular_name,
-        :singular_resource_name
-      )
-      @plural = resolve_plurality(**params)
-
-      super(**params)
-    end
-
-    # @return [Class] the class of entity represented by the resource.
-    def resource_class
-      tools.core_tools.deprecate '#resource_class method',
-        message: 'Use #entity_class instead'
-
-      entity_class
-    end
-
-    # @return [String] the name of the resource.
-    def resource_name
-      tools.core_tools.deprecate '#resource_name method',
-        message: 'Use #name instead'
-
-      name
-    end
-
-    # @return[String] the name of an entity in the resource.
-    def singular_resource_name
-      tools.core_tools.deprecate '#singular_resource_name method',
-        message: 'Use #singular_name instead'
-
-      singular_name
-    end
+    #   @option options scope
+    #     [Cuprum::Collections::Scopes::Base, Hash, Proc, nil] the configured
+    #     scope for the relation.
   end
 end