cuprum-collections 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dda6613af3def3463515616a0b448dce3ce0fb666b6b81b9c9d54cf9e4f6bef0
-  data.tar.gz: e8cae0cd8e96daf887268b0b467352d34a7a93357729c14115375f7d14d2e2d8
+  metadata.gz: 9a2dd2e704041cbdb689bca94afa13c5803ada5cb0601d7c0870cea1c6740830
+  data.tar.gz: 0fc7380322c9dbb547354408dbe8fd513ef792c7cb8ee0000aef2b94ef68f921
 SHA512:
-  metadata.gz: 138cf1bd095d6d03e196c90ac4779ee6d8dec8743f8cb321c4114117c707ef0124f378642653beef0e3db1c0d127cebd05967a4356ce5361cd3294bd298642e7
-  data.tar.gz: 968b185b8e1b0447b55acc093387ad527e0ba5154b0e4a24d2ace52cf258ca29939eefa0cc772451703d1b56286dce907c84402a735a360152d3573ea8cb5db7
+  metadata.gz: 34ed0e5a7d1f528466cc8de3cba741e53143d5defdae69bf1b6daaa5705f715444a92bd0b0b2d8e325c1a6c6ed6c5433760bcb3a6cb357dabf3cd8cf04771311
+  data.tar.gz: c4ff7c90ce097e3d59e21ac633157358f20571210eee14c4b5b279dc8e16adf05391d6aa1b7205773821775216e859952259f8becf21a054aae24c5d253f90c1

data/CHANGELOG.md

@@ -1,5 +1,53 @@
 # Changelog
 
+## 0.4.0
+
+### Associations
+
+Implemented `Cuprum::Collections::Association`, which represents an association between entity types.
+
+- Implemented `Cuprum::Collections::Associations::BelongsTo`.
+- Implemented `Cuprum::Collections::Associations::HasMany`.
+- Implemented `Cuprum::Collections::Associations::HasOne`.
+
+### Collections
+
+Defined standard interface for collections.
+
+- Implemented `Cuprum::Collections::Collection`.
+- Collections can now be initialized with any combination of collection name, entity class, and qualified name.
+
+Deprecated certain collection methods and corresponding constructor keywords:
+
+- `#collection_name`: Use `#name`.
+- `#member_name`: Use `#singular_name`.
+
+### Commands
+
+Implemented association Commands, which find or require association entities from a list of entities or keys.
+
+- `Commands::Associations::FindMany`
+- `Commands::Associations::RequireMany`
+
+### Relations
+
+Defined `Cuprum::Collections::Relation`, an abstract class representing a group or view of entities.
+
+### Repositories
+
+Defined standard interface for repositories.
+
+- Implemented `Repository#create`.
+- Implemented `Repository#find_or_create`.
+
+### Resources
+
+Defined `Cuprum::Collections::Resource`, representing a singular or plural resource of entities.
+
+### RSpec
+
+- **(Breaking Change)** Contracts have been refactored to use `RSpec::SleepingKingStudios::Contract`. Contract names and filenames have changed.
+
 ## 0.3.0
 
 ### Collections

data/DEVELOPMENT.md

@@ -8,8 +8,8 @@ Steps to add an operator:
 
 - Update Queries::Operators.
 - Update Queries::ParseBlock::Builder.
-- Define context(s) in RSpec::QUERYING_CONTEXTS.
-- Add test cases in RSpec::QUERYING_CONTRACT.
+- Define context(s) in QueryContracts::WithQueryContexts.
+- Add test cases in QueryContracts::ShouldPerformQueries.
 - Add implementations to Basic::QueryBuilder.
 
 ### ParseCriteria

data/README.md

@@ -68,8 +68,8 @@ Each collection provides three features:
 
 ```ruby
 collection = Cuprum::Collections::Basic.new(
-  collection_name: 'books',
-  data:            book_data,
+  name: 'books',
+  data: book_data,
 )
 
 # Add an item to the collection.
@@ -107,10 +107,12 @@ Because a collection can represent any sort of data, from a raw Ruby Hash to an
 
 Each collection also defines the following methods:
 
-- `#collection_name`: The collection name is a short description of what the collection contains. For example, a collection of `Book` objects might have a collection name of `'books'`, while a collection of `Authorization::Credentials::ApiKey` objects might have a collection name of `'api_keys'`.
+- `#name`: The collection name is a short description of what the collection contains. For example, a collection of `Book` objects might have a collection name of `'books'`, while a collection of `Authorization::Credentials::ApiKey` objects might have a collection name of `'api_keys'`.
+- `#entity_class`: The type of entity contained in the collection.
 - `#qualified_name`: The qualified name is a full description of the collection, and should be unique. For example, a collection of `Book` objects might have a qualified name of `'books'`, while a collection of `Authorization::Credentials::ApiKey` objects might have a qualified name of `'authorization/credentials/api_keys'`.
+- `#singular_name`: The name of an item in the collection.
 
-As a general rule, the `#collection_name` is used when displaying information to the user, while the `#qualified_name` is used to uniquely identify the collection (such as when adding to or retrieving from a [Repository](#repositories)).
+As a general rule, the `#name` is used when displaying information to the user, while the `#qualified_name` is used to uniquely identify the collection (such as when adding to or retrieving from a [Repository](#repositories)).
 
 <a id="commands"></a>
 
@@ -406,7 +408,7 @@ repository.key?('api_keys')
 repository.key?('authorization/credentials/api_keys')
 #=> false
 
-api_keys_collection.collection_name
+api_keys_collection.name
 #=> 'api_keys'
 api_keys_collection.qualified_name
 #=> 'authorization/credentials/api_keys'
@@ -432,14 +434,14 @@ The `Cuprum::Basic::Collection` provides a reference implementation of a collect
 
 ```ruby
 collection = Cuprum::Collections::Basic.new(
-  collection_name: 'books',
-  data:            book_data,
+  name: 'books',
+  data: book_data,
 )
 ```
 
 Initializing a basic collection requires, at a minumum, the following keywords:
 
-- The `:collection_name` parameter sets the name of the collection. It is used to create an envelope for query commands, such as the `FindMany`, `FindMatching` and `FindOne` commands.
+- The `:name` parameter sets the name of the collection. It is used to create an envelope for query commands, such as the `FindMany`, `FindMatching` and `FindOne` commands.
 - The `:data` parameter initializes the collection with existing data. The data must be either an empty array or an `Array` of `Hash`es with `String` keys.
 
 You can also specify some optional keywords:
@@ -471,7 +473,7 @@ repository = Cuprum::Collections::Basic::Repository.new(data: data)
 repository.keys
 #=> []
 
-repository.build(collection_name: 'books')
+repository.build(name: 'books')
 #=> an instance of Cuprum::Collections::Basic::Collection
 repository.keys
 #=> ['books']
@@ -593,8 +595,8 @@ A `Cuprum::Collections::Query` provides a low-level interface for performing que
 
 ```ruby
 collection = Cuprum::Collections::Basic.new(
-  collection_name: 'books',
-  data:            book_data,
+  name: 'books',
+  data: book_data,
 )
 query      = collection.query
 

data/lib/cuprum/collections/association.rb

@@ -0,0 +1,256 @@
+# frozen_string_literal: true
+
+require 'cuprum/collections'
+require 'cuprum/collections/resource'
+
+module Cuprum::Collections
+  # Class representing an association between resources.
+  class Association < Resource # rubocop:disable Metrics/ClassLength
+    # @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 inverse [Cuprum::Collections::Resource] the inverse association,
+    #     if any.
+    #   @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.
+    #
+    #   @option options foreign_key_name [String] the name of the foreign key
+    #     attribute.
+    #   @option options inverse_class [Class, String] the class of the inverse
+    #     association.
+    #   @option options inverse_name [String, Symbol] the name of the inverse
+    #     association.
+    #   @option options plural [Boolean] if true, the resource represents a
+    #     plural resource. Defaults to true. Can also be specified as :singular.
+    #   @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.
+    #   @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)
+
+      @inverse = params.delete(:inverse)
+
+      super(**params)
+    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.
+    # @param allow_nil [Boolean] if true, allows for nil keys. Defaults to
+    #   false.
+    # @param deduplicate [Boolean] if true, removes duplicate keys before
+    #   generating the query. Defaults to true.
+    #
+    # @return [Proc] the generated query.
+    def build_entities_query(*entities, allow_nil: false, deduplicate: true)
+      keys =
+        map_entities_to_keys(
+          *entities,
+          allow_nil:   allow_nil,
+          deduplicate: deduplicate,
+          strict:      true
+        )
+
+      build_keys_query(*keys, allow_nil: allow_nil, deduplicate: false)
+    end
+
+    # Generates a query for finding matching items by key.
+    #
+    # @param keys [Array] the primary or foreign keys to query for.
+    # @param allow_nil [Boolean] if true, allows for nil keys. Defaults to
+    #   false.
+    # @param deduplicate [Boolean] if true, removes duplicate keys before
+    #   generating the query. Defaults to true.
+    #
+    # @return [Proc] the generated query.
+    def build_keys_query(*keys, allow_nil: false, deduplicate: true)
+      keys     = keys.compact unless allow_nil
+      keys     = keys.uniq    if deduplicate
+      hash_key = query_key_name
+
+      if keys.empty?
+        -> { {} }
+      elsif keys.size == 1
+        -> { { hash_key => keys.first } }
+      else
+        -> { { hash_key => one_of(keys) } }
+      end
+    end
+
+    # @return [String] the name of the foreign key attribute.
+    def foreign_key_name
+      @foreign_key_name ||=
+        options
+          .fetch(:foreign_key_name) { default_foreign_key_name }
+          &.to_s
+    end
+
+    # @return [Class] the class of the inverse association, if any.
+    def inverse_class
+      @inverse_class ||=
+        options
+          .fetch(:inverse_class) { inverse&.entity_class }
+          .then do |value|
+            value.is_a?(String) ? Object.const_get(value) : value
+          end
+    end
+
+    # @return [String] the name of the inverse key.
+    def inverse_key_name
+      return foreign_key_name if primary_key_query?
+
+      primary_key_name
+    end
+
+    # @return [String] the name of the inverse association, if any.
+    def inverse_name
+      @inverse_name ||=
+        options
+          .fetch(:inverse_name) { default_inverse_name }
+          &.to_s
+    end
+
+    # Maps a list of entities to keys for performing a query.
+    #
+    # @param entities [Array] the entities to query for.
+    # @param allow_nil [Boolean] if true, allows for nil keys. Defaults to
+    #   false.
+    # @param deduplicate [Boolean] if true, removes duplicate keys before
+    #   generating the query. Defaults to true.
+    # @param strict [Boolean] if true, raises an exception if given an Array of
+    #   keys instead of entities.
+    #
+    # @return [Array] the primary or foreign keys to query for.
+    def map_entities_to_keys(
+      *entities,
+      allow_nil:   false,
+      deduplicate: true,
+      strict:      true
+    )
+      entities
+        .compact
+        .map { |entity| map_entity_to_key(entity, strict: strict) }
+        .then { |keys| allow_nil ? keys : keys.compact }
+        .then { |keys| deduplicate ? keys.uniq : keys }
+    end
+
+    # @return [Boolean] true if the association queries by primary key, e.g. a
+    #   :belongs_to association; false if the association queries by foreign
+    #   key, e.g. a :has_one or :has_many association.
+    def primary_key_query?
+      false
+    end
+
+    # @return [String] the name of the key used to perform the query.
+    def query_key_name
+      return primary_key_name if primary_key_query?
+
+      if foreign_key_name.nil? || foreign_key_name.empty?
+        raise ArgumentError, "foreign key name can't be blank"
+      end
+
+      foreign_key_name
+    end
+
+    # @return [String] the name of an entity in the inverse association.
+    def singular_inverse_name
+      @singular_inverse_name ||=
+        options
+          .fetch(:singular_inverse_name) { default_singular_inverse_name }
+          &.to_s
+    end
+
+    # Creates a copy of the association with the specified inverse association.
+    #
+    # @param inverse [Cuprum::Collections::Resource] the inverse association.
+    #
+    # @return [Cuprum::Collections::Association] the copied association.
+    def with_inverse(inverse)
+      dup.assign_inverse(inverse)
+    end
+
+    protected
+
+    def assign_inverse(inverse)
+      @inverse               = inverse
+      @inverse_class         = nil
+      @inverse_name          = nil
+      @foreign_key_name      = nil
+      @singular_inverse_name = nil
+
+      self
+    end
+
+    private
+
+    def default_foreign_key_name
+      singular_inverse_name&.then { |str| "#{str}_id" }
+    end
+
+    def default_inverse_name
+      inverse&.name
+    end
+
+    def default_singular_inverse_name
+      return inverse.singular_name if inverse
+
+      return tools.string_tools.singularize(inverse_name) if inverse_name
+
+      nil
+    end
+
+    def entity_key_name
+      primary_key_query? ? foreign_key_name : primary_key_name
+    end
+
+    def indexed?(value)
+      return false if value.is_a?(Integer)
+
+      return false if value.is_a?(String)
+
+      value.respond_to?(:[])
+    end
+
+    def map_entity_to_key(value, strict: false)
+      key = entity_key_name
+
+      return value[key] if indexed?(value)
+
+      return value.send(key) if value.respond_to?(key)
+
+      return value if !strict && value.is_a?(primary_key_type)
+
+      raise ArgumentError,
+        "undefined method :[] or :#{key} for #{value.inspect}"
+    end
+
+    def tools
+      SleepingKingStudios::Tools::Toolbelt.instance
+    end
+  end
+end

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

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require 'cuprum/collections/association'
+require 'cuprum/collections/associations'
+
+module Cuprum::Collections::Associations
+  # Object representing a belongs_to association, which inverts the foreign key.
+  class BelongsTo < Cuprum::Collections::Association
+    # (see Cuprum::Collections::Association#initialize)
+    def initialize(**params)
+      params.delete(:plural)
+      params.delete(:singular)
+
+      super(**params, singular: true)
+    end
+
+    # (see Cuprum::Collections::Association#primary_key_query?)
+    def primary_key_query?
+      true
+    end
+
+    private
+
+    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

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require 'cuprum/collections/association'
+require 'cuprum/collections/associations'
+
+module Cuprum::Collections::Associations
+  # Object representing a has_many association.
+  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])
+    end
+  end
+end

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

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require 'cuprum/collections/association'
+require 'cuprum/collections/associations'
+
+module Cuprum::Collections::Associations
+  # Object representing a has_one association.
+  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])
+    end
+  end
+end

data/lib/cuprum/collections/associations.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require 'cuprum/collections'
+
+module Cuprum::Collections
+  # Namespace for implementing specific association types.
+  module Associations
+    autoload :BelongsTo, 'cuprum/collections/associations/belongs_to'
+  end
+end

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

@@ -4,71 +4,45 @@ require 'cuprum/command_factory'
 
 require 'cuprum/collections/basic'
 require 'cuprum/collections/basic/commands'
+require 'cuprum/collections/collection'
 
 module Cuprum::Collections::Basic
   # Wraps an in-memory array of hashes data store as a Cuprum collection.
-  class Collection < Cuprum::CommandFactory
-    # @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 qualified_name [String] The qualified name of the collection, which
-    #   should be unique. Defaults to the collection name.
-    # @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,
-      qualified_name:   nil,
-      **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
-      @qualified_name   = qualified_name || @collection_name
+  class Collection < Cuprum::Collections::Collection
+    # @overload initialize(data: [], entity_class: nil, name: nil, qualified_name: nil, singular_name: nil, **options)
+    #   @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 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
+      )
+
+      @data = data
     end
 
-    # @return [String] the name of the collection.
-    attr_reader :collection_name
-
     # @return [Array<Hash>] the current data in the collection.
     attr_reader :data
 
-    # @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
-
-    # @return [String] the qualified name of the collection.
-    attr_reader :qualified_name
-
     command_class :assign_one do
       Cuprum::Collections::Basic::Commands::AssignOne
         .subclass(**command_options)
@@ -114,11 +88,11 @@ module Cuprum::Collections::Basic
         .subclass(**command_options)
     end
 
-    # @return [Integer] the count of items in the collection.
-    def count
-      query.count
+    # @return [Stannum::Constraints::Base, nil] the #   default contract for
+    #   validating items in the collection.
+    def default_contract
+      @options[:default_contract]
     end
-    alias size count
 
     # A new Query instance, used for querying against the collection data.
     #
@@ -127,22 +101,13 @@ module Cuprum::Collections::Basic
       Cuprum::Collections::Basic::Query.new(data)
     end
 
-    private
+    protected
 
     def command_options
-      @command_options ||= {
-        collection_name:  collection_name,
+      super().merge(
         data:             data,
-        default_contract: default_contract,
-        member_name:      member_name,
-        primary_key_name: primary_key_name,
-        primary_key_type: primary_key_type,
-        **options
-      }
-    end
-
-    def tools
-      SleepingKingStudios::Tools::Toolbelt.instance
+        default_contract: default_contract
+      )
     end
   end
 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) # rubocop:disable Layout/LineLength
+    # @!method call(primary_keys:, allow_partial: false, envelope: false, scope: nil)
     #   Queries the collection for the items with the given primary keys.
     #
     #   The command will find and return the entities with the given primary

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

@@ -13,7 +13,7 @@ module Cuprum::Collections::Basic::Commands
   class FindMatching < Cuprum::Collections::Basic::Command
     include Cuprum::Collections::Commands::AbstractFindMatching
 
-    # @!method call(envelope: false, limit: nil, offset: nil, order: nil, scope: nil, where: nil, &block)  # rubocop:disable Layout/LineLength
+    # @!method call(envelope: false, limit: nil, offset: nil, order: nil, scope: nil, where: nil, &block)
     #   Queries the collection for items matching the given conditions.
     #
     #   @param envelope [Boolean] If true, wraps the result value in a Hash.