cuprum-collections 0.1.0

data/lib/cuprum/collections/base.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require 'cuprum/command_factory'
+
+require 'cuprum/collections'
+
+module Cuprum::Collections
+  # Abstract base class for Collection factories.
+  class Base < Cuprum::CommandFactory
+  end
+end

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

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+require 'cuprum/command_factory'
+
+require 'cuprum/collections/basic'
+require 'cuprum/collections/basic/commands'
+
+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 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
+
+    # @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
+
+    command_class :assign_one do
+      Cuprum::Collections::Basic::Commands::AssignOne
+        .subclass(**command_options)
+    end
+
+    command_class :build_one do
+      Cuprum::Collections::Basic::Commands::BuildOne
+        .subclass(**command_options)
+    end
+
+    command_class :destroy_one do
+      Cuprum::Collections::Basic::Commands::DestroyOne
+        .subclass(**command_options)
+    end
+
+    command_class :find_many do
+      Cuprum::Collections::Basic::Commands::FindMany
+        .subclass(**command_options)
+    end
+
+    command_class :find_matching do
+      Cuprum::Collections::Basic::Commands::FindMatching
+        .subclass(**command_options)
+    end
+
+    command_class :find_one do
+      Cuprum::Collections::Basic::Commands::FindOne
+        .subclass(**command_options)
+    end
+
+    command_class :insert_one do
+      Cuprum::Collections::Basic::Commands::InsertOne
+        .subclass(**command_options)
+    end
+
+    command_class :update_one do
+      Cuprum::Collections::Basic::Commands::UpdateOne
+        .subclass(**command_options)
+    end
+
+    command_class :validate_one do
+      Cuprum::Collections::Basic::Commands::ValidateOne
+        .subclass(**command_options)
+    end
+
+    # A new Query instance, used for querying against the collection data.
+    #
+    # @return [Cuprum::Collections::Basic::Query] the query.
+    def query
+      Cuprum::Collections::Basic::Query.new(data)
+    end
+
+    private
+
+    def command_options
+      @command_options ||= {
+        collection_name:  collection_name,
+        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
+    end
+  end
+end

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

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require 'stannum/constraints/types/array_type'
+
+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
+
+    # @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
+
+    private
+
+    def primary_key_contract
+      type = primary_key_type
+
+      @primary_key_contract ||= Stannum::Contracts::ParametersContract.new do
+        keyword :primary_key, type
+      end
+    end
+
+    def primary_keys_contract
+      type = primary_key_type
+
+      @primary_keys_contract ||= Stannum::Contracts::ParametersContract.new do
+        keyword :primary_keys,
+          Stannum::Constraints::Types::ArrayType.new(item_type: type)
+      end
+    end
+
+    def tools
+      SleepingKingStudios::Tools::Toolbelt.instance
+    end
+
+    def validate_primary_key(primary_key)
+      match_parameters_to_contract(
+        contract:    primary_key_contract,
+        keywords:    { primary_key: primary_key },
+        method_name: :call
+      )
+    end
+
+    def validate_primary_keys(primary_keys)
+      match_parameters_to_contract(
+        contract:    primary_keys_contract,
+        keywords:    { primary_keys: primary_keys },
+        method_name: :call
+      )
+    end
+  end
+end

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

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require 'stannum/constraints/types/hash_with_indifferent_keys'
+require 'stannum/constraints/types/hash_with_string_keys'
+
+require 'cuprum/collections/basic/command'
+require 'cuprum/collections/basic/commands'
+
+module Cuprum::Collections::Basic::Commands
+  # Command for assigning attributes to a collection entity.
+  class AssignOne < Cuprum::Collections::Basic::Command
+    # @!method call(attributes:, entity:)
+    #   Assigns the given attributes to the entity.
+    #
+    #   Any attributes on the entity that are not part of the given attributes
+    #   hash are unchanged.
+    #
+    #   @param attributes [Hash] The attributes and values to update.
+    #   @param entity [Hash] The collection entity to update.
+    #
+    #   @return [Hash] a copy of the entity, merged with the given attributes.
+    #
+    #   @example Assigning attributes
+    #     entity = {
+    #       'title'    => 'The Hobbit',
+    #       'author'   => 'J.R.R. Tolkien',
+    #       'series'   => nil,
+    #       'category' => 'Science Fiction and Fantasy'
+    #     }
+    #     attributes = { title: 'The Silmarillion' }
+    #     command = AssignOne.new(collection_name: 'books', data: books)
+    #     command.call(attributes: attributes, entity: entity)
+    #     #=> {
+    #       'title'    => 'The Silmarillion',
+    #       'author'   => 'J.R.R. Tolkien',
+    #       '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
+
+    private
+
+    def process(attributes:, entity:)
+      attributes = tools.hsh.convert_keys_to_strings(attributes)
+
+      entity.merge(attributes)
+    end
+  end
+end

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

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require 'stannum/constraints/types/hash_with_indifferent_keys'
+
+require 'cuprum/collections/basic/command'
+require 'cuprum/collections/basic/commands'
+
+module Cuprum::Collections::Basic::Commands
+  # Command for generating a collection entity from an attributes hash.
+  class BuildOne < Cuprum::Collections::Basic::Command
+    # @!method call(attributes:, entity:)
+    #   Builds a new entity with the given attributes.
+    #
+    #   @param attributes [Hash] The attributes and values to assign.
+    #
+    #   @return [Hash] the newly built entity.
+    #
+    #   @example Building an entity
+    #     attributes = {
+    #       'title'    => 'The Hobbit',
+    #       'author'   => 'J.R.R. Tolkien',
+    #       'series'   => nil,
+    #       'category' => 'Science Fiction and Fantasy'
+    #     }
+    #     command    = BuildOne.new(collection_name: 'books', data: books)
+    #     result     = command.call(attributes: attributes)
+    #     result.value
+    #     #=> {
+    #       'title'    => 'The Silmarillion',
+    #       'author'   => 'J.R.R. Tolkien',
+    #       'series'   => nil,
+    #       'category' => 'Science Fiction and Fantasy'
+    #     }
+    validate_parameters :call do
+      keyword :attributes,
+        Stannum::Constraints::Types::HashWithIndifferentKeys.new
+    end
+
+    private
+
+    def process(attributes:)
+      tools.hsh.convert_keys_to_strings(attributes)
+    end
+  end
+end

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

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require 'cuprum/collections/basic/command'
+require 'cuprum/collections/basic/commands'
+require 'cuprum/collections/errors/not_found'
+
+module Cuprum::Collections::Basic::Commands
+  # Command for destroying one collection item by primary key.
+  class DestroyOne < Cuprum::Collections::Basic::Command
+    # @!method call(primary_key:)
+    #   Finds and destroys the item with the given primary key.
+    #
+    #   The command will find the entity with the given primary key and remove
+    #   it from the collection. If the entity is not found, the command will
+    #   fail and return a NotFound error.
+    #
+    #   @param primary_key [Object] The primary key of the requested item.
+    #
+    #   @return [Cuprum::Result<Hash{String, Object}>] a result with the
+    #     destroyed item.
+    validate_parameters :call do
+      keyword :primary_key, Object
+    end
+
+    private
+
+    def handle_missing_item(index:, primary_key:)
+      return if index
+
+      error = Cuprum::Collections::Errors::NotFound.new(
+        collection_name:    collection_name,
+        primary_key_name:   primary_key_name,
+        primary_key_values: [primary_key]
+      )
+      Cuprum::Result.new(error: 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) }
+
+      data.delete_at(index)
+    end
+  end
+end

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

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require 'stannum/constraints/boolean'
+
+require 'cuprum/collections/basic/command'
+require 'cuprum/collections/basic/commands'
+require 'cuprum/collections/commands/abstract_find_many'
+
+module Cuprum::Collections::Basic::Commands
+  # Command for finding multiple collection items by primary key.
+  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
+    #   Queries the collection for the items with the given primary keys.
+    #
+    #   The command will find and return the entities with the given primary
+    #   keys. If any of the items are not found, the command will fail and
+    #   return a NotFound error. If the :allow_partial option is set, the
+    #   command will return a partial result unless none of the requested items
+    #   are found.
+    #
+    #   When the :envelope option is true, the command wraps the items in a
+    #   Hash, using the name of the collection as the key.
+    #
+    #   @param allow_partial [Boolean] If true, passes if any of the items are
+    #     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
+
+    private
+
+    def build_query
+      Cuprum::Collections::Basic::Query.new(data)
+    end
+
+    def items_with_primary_keys(items:)
+      # :nocov:
+      items.map { |item| [item[primary_key_name.to_s], item] }.to_h
+      # :nocov:
+    end
+
+    def process(
+      primary_keys:,
+      allow_partial: false,
+      envelope:      false,
+      scope:         nil
+    )
+      step { validate_primary_keys(primary_keys) }
+
+      super
+    end
+  end
+end

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

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+require 'stannum/constraints/boolean'
+
+require 'cuprum/collections/basic/command'
+require 'cuprum/collections/basic/commands'
+require 'cuprum/collections/basic/query'
+require 'cuprum/collections/commands/abstract_find_matching'
+require 'cuprum/collections/constraints/ordering'
+
+module Cuprum::Collections::Basic::Commands
+  # Command for querying filtered, ordered data from a basic collection.
+  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
+    #   Queries the collection for items matching the given conditions.
+    #
+    #   @param envelope [Boolean] If true, wraps the result value in a Hash.
+    #   @param limit [Integer] The maximum number of results to return.
+    #   @param offset [Integer] The initial ordered items to skip.
+    #   @param order [Array<String, Symbol>, Hash<{String, Symbol => Symbol}>]
+    #     The sort order of the returned items. Should be either an array of
+    #     attribute names or a hash of attribute names and directions.
+    #   @param scope [Cuprum::Collections::Basic::Query, nil] Optional scope for
+    #     the query. Items must match the scope as well as the :where filters.
+    #   @param where [Object] Additional filters for selecting data. The command
+    #     will only return data matching these filters.
+    #   @yield The given block is passed to a QueryBuilder, which converts the
+    #     block to query criteria and generates a new query using those
+    #     criteria.
+    #   @yieldreturn [Hash] The filters to apply to the query. The hash keys
+    #     should be the names of attributes or columns, and the corresponding
+    #     values should be either the literal value for that attribute or a
+    #     method call for a valid operation defined for the query.
+    #
+    #   @example Querying all items in the collection.
+    #     command = FindMatching.new(collection_name: 'books', data: books)
+    #     command.call
+    #     #=> an enumerable iterating all items in the collection
+    #
+    #   @example Querying all items matching some critera:
+    #     command.call { { author: 'Nnedi Okorafor' } }
+    #     #=> an enumerable iterating all items in the collection whose author
+    #         is 'Nnedi Okorafor'
+    #
+    #   @example Ordering query results
+    #     command.call(order: :title) { { author: 'Nnedi Okorafor' } }
+    #     #=> an enumerable iterating all items in the collection whose author
+    #     #   is 'Nnedi Okorafor', sorted by :title in ascending order
+    #
+    #   @example Advanced filtering
+    #     command.call do
+    #       {
+    #         category: eq('Science Fiction and Fantasy'),
+    #         author:   ne('J.R.R. Tolkien')
+    #       }
+    #     end
+    #     #=> an enumerable iterating all items in the collection whose category
+    #     #   is 'Science Fiction and Fantasy', and whose author is not
+    #     #   'J.R.R. Tolkien'.
+    #
+    #   @example Advanced ordering
+    #     order = { author: :asc, genre: :desc }
+    #     command.call(order: order) { { author: 'Nnedi Okorafor' } }
+    #     #=> an enumerable iterating all items in the collection whose author
+    #     #   is 'Nnedi Okorafor', sorted first by :author in ascending order
+    #     #   and within the same author by genre in descending order
+    #
+    #   @example Filtering, ordering, and subsets
+    #     command.call(offset: 50, limit: 10, order: :author) do
+    #       { category: 'Science Fiction and Fantasy' }
+    #     end
+    #     #=> an enumerable iterating the 51st through 60th items in the
+    #     #   collection whose category is 'Science Fiction and Fantasy', sorted
+    #     #   by :author in ascending order.
+    #
+    #   @example Wrapping the result in an envelope
+    #     command =
+    #       FindMatching.new(
+    #         collection_name: 'books',
+    #         data:            books
+    #       )
+    #     command.call(envelope: true)
+    #     #=> {
+    #       'books' => [] # an array containing the matching items
+    #     }
+    #
+    #   @overload call(limit: nil, offset: nil, order: nil, &block)
+    #     When the :envelope option is false (default), the command returns an
+    #     Enumerator which can be iterated to return the matching items.
+    #
+    #     @return [Cuprum::Result<Enumerator>] the matching items in the
+    #       specified order as an Enumerator.
+    #
+    #   @overload call(limit: nil, offset: nil, order: nil, &block)
+    #     When the :envelope option is true, the command immediately evaluates
+    #     the query and wraps the resulting array in a Hash, using the name of
+    #     the collection as the key.
+    #
+    #     @return [Cuprum::Result<Hash{String, Array<Hash{String, Object}>}>] a
+    #       hash with the collection name as key and the matching items as
+    #       value.
+
+    validate_parameters :call do
+      keyword :envelope,
+        Stannum::Constraints::Boolean.new,
+        default: true
+      keyword :limit, Integer, optional: true
+      keyword :offset, Integer, optional: true
+      keyword :order,
+        Cuprum::Collections::Constraints::Ordering.new,
+        optional: true
+      keyword :scope,
+        Cuprum::Collections::Basic::Query,
+        optional: true
+      keyword :where, Object, optional: true
+    end
+
+    private
+
+    def build_query
+      Cuprum::Collections::Basic::Query.new(data)
+    end
+  end
+end

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

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require 'stannum/constraints/boolean'
+
+require 'cuprum/collections/basic/command'
+require 'cuprum/collections/basic/commands'
+require 'cuprum/collections/commands/abstract_find_one'
+
+module Cuprum::Collections::Basic::Commands
+  # Command for finding one collection item by primary key.
+  class FindOne < Cuprum::Collections::Basic::Command
+    include Cuprum::Collections::Commands::AbstractFindOne
+
+    # @!method call(primary_key:, envelope: false, scope: nil)
+    #   Queries the collection for the item with the given primary key.
+    #
+    #   The command will find and return the entity with the given primary key.
+    #   If the entity is not found, the command will fail and return a NotFound
+    #   error.
+    #
+    #   When the :envelope option is true, the command wraps the item in a Hash,
+    #   using the singular name of the collection as the key.
+    #
+    #   @param envelope [Boolean] If true, wraps the result value in a Hash.
+    #   @param primary_key [Object] The primary key of the requested item.
+    #   @param scope [Cuprum::Collections::Basic::Query, nil] Optional scope for
+    #     the query. The item must match the scope as well as the primary key.
+    #
+    #   @return [Cuprum::Result<Hash{String, Object}>] a result with the
+    #     requested item.
+    validate_parameters :call do
+      keyword :envelope,    Stannum::Constraints::Boolean.new, default: true
+      keyword :primary_key, Object
+      keyword :scope,       Cuprum::Collections::Basic::Query, optional: true
+    end
+
+    private
+
+    def build_query
+      Cuprum::Collections::Basic::Query.new(data)
+    end
+
+    def process(primary_key:, envelope: false, scope: nil)
+      step { validate_primary_key(primary_key) }
+
+      super
+    end
+  end
+end