collectible 0.15.0 → 0.15.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8d86d4d1188c1b5dbaddc82a818e07eb7f4de752315982da7beed7eb1a7415e0
-  data.tar.gz: 4ec1b035fca482873ae814a3e1d2f69962294155dd4266fe76eadb5d724f23aa
+  metadata.gz: 3042afa746b23d3334c26f3e2d535fef1255f16d4d6c5282558e18a329212586
+  data.tar.gz: 3bfd916f142dc82e0ce02922b0291fbbf2c1aa3b6e81f5849ba9c7bfb4cc9056
 SHA512:
-  metadata.gz: 469459b0353175d294e496d98145402d5f5323981287fc5e8f093c8726276e722db15eacb990ad7709c49057ef01624dab4ceed65c309b62dbf378b584d1791a
-  data.tar.gz: ff43527d2bcff46488c7513387f88f60e69a813ebbb28d25b6b1993023f45c1d3910c432bc07af23bc4f3de3a1bb1cb4968b2acaa6363c67edbd8c080918693b
+  metadata.gz: ad7a87d8f7fba77e85faec60f7d73c0d03e462c1219b5926e7705a5c138b7476569263f3bcbbc9743aff626792f402a178fc6cec3a5b94d5450b3f74c7dbe6ed
+  data.tar.gz: 9882813663e2579a888c5dd7fcba670072cbf3d1b920ec988dc5bb8586db44767fd591d906c35500c687846222920f56864142af15f0919f927a4acd6f138046

data/lib/collectible.rb

@@ -1,7 +1,20 @@
 # frozen_string_literal: true
 
+require "active_support"
+require "active_support/core_ext/module"
+
+require "short_circu_it"
+
+require "tablesalt/stringable_object"
+require "tablesalt/uses_hash_for_equality"
+
 require "collectible/version"
 
+require "collectible/collection_base"
+
 module Collectible
-  # Your code goes here...
+  class ItemNotAllowedError < StandardError; end
+  class ItemTypeMismatchError < ItemNotAllowedError; end
+  class TypeEnforcementAlreadyDefined < StandardError; end
+  class MethodNotAllowedError < StandardError; end
 end

data/lib/collectible/collection/core.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Collectible
+  module Collection
+    module Core
+      extend ActiveSupport::Concern
+
+      included do
+        attr_reader :items
+
+        delegate :name, to: :class, prefix: true
+        delegate :to_a, :to_ary, :select, :map, :group_by, :partition, :as_json, to: :items
+      end
+
+      def initialize(*items)
+        @items = items.flatten
+      end
+
+      def hash
+        { class_name: class_name, items: items }.hash
+      end
+    end
+  end
+end

data/lib/collectible/collection/ensures_item_eligibility.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+module Collectible
+  module Collection
+    module EnsuresItemEligibility
+      extend ActiveSupport::Concern
+
+      ENSURE_TYPE_EQUALITY = :ENSURE_TYPE_EQUALITY
+
+      included do
+        ensure_item_validity_before :initialize, :push, :<<, :unshift, :insert, :concat, :prepend
+      end
+
+      delegate :item_class, to: :class
+
+      private
+
+      delegate :ensure_item_validity_with, to: :class
+
+      # Raises an error if any items fail the class' item validity block/class
+      def ensure_allowed_in_collection!(*new_items)
+        ensure_type_equality!(*new_items) and return if ensures_type_equality?
+
+        invalid_items = new_items.flatten.reject { |item| allows_item?(item) }
+        return if invalid_items.empty?
+
+        raise Collectible::ItemNotAllowedError,
+              "not allowed: #{invalid_items.first(3).map(&:inspect).join(", ")}#{"..." if invalid_items.length > 3}"
+      end
+
+      # @param item [*]
+      # @return [Boolean]
+      def allows_item?(item)
+        if ensure_item_validity_with.respond_to?(:call)
+          instance_exec(item, &ensure_item_validity_with)
+        elsif ensure_item_validity_with.present?
+          item.class <= ensure_item_validity_with
+        else
+          true
+        end
+      end
+
+      # @return [Boolean]
+      def ensures_type_equality?
+        ensure_item_validity_with == ENSURE_TYPE_EQUALITY
+      end
+
+      def ensure_type_equality!(*new_items)
+        new_items = new_items.flatten
+        first_item = items.blank? ? new_items.first : items.first
+
+        new_items.each do |item|
+          next if item.class == first_item.class
+
+          raise Collectible::ItemTypeMismatchError, "item mismatch: #{first_item.inspect}, #{item.inspect}"
+        end
+      end
+
+      class_methods do
+        # @return [Class] The class or superclass of all items in the collection
+        def item_class
+          item_enforcement.is_a?(Class) ? item_enforcement : name.gsub(%r{Collection.*}, "").safe_constantize
+        end
+
+        # @return [Class, Proc] Either a class that all collection items must belong to,
+        #                       or a proc that validates each item as it is inserted.
+        def ensure_item_validity_with
+          item_enforcement ||
+            (superclass.ensure_item_validity_with if superclass.respond_to?(:ensure_item_validity_with, true))
+        end
+
+        protected
+
+        # @example
+        #   # Allows any item that responds to :even? with a truthy value
+        #   allow_item { |item| item.even? }
+        #
+        # for block { |item| ... }
+        # @yield [*] Yields each inserted item to the provided block. The item will only be allowed into
+        #            the collection if the block resolves to a truthy value; otherwise, an error is raised.
+        #            The block shares the context of the collection +instance+, not the class.
+        def allow_item(&block)
+          raise Collectible::TypeEnforcementAlreadyDefined if item_enforcement.present?
+          raise ArgumentError, "must provide a block" unless block_given?
+
+          self.item_enforcement = block
+        end
+
+        # @example
+        #   # Allows any item where item.class <= TargetDate
+        #   ensures_item_class TargetDate
+        #
+        # @param klass [Class] A specific class all items are expected to be. Items of this type will be
+        #                      allowed into collection; otherwise, an error is raised.
+        def ensures_item_class(klass)
+          raise Collectible::TypeEnforcementAlreadyDefined if item_enforcement.present?
+
+          self.item_enforcement = klass
+        end
+
+        # Allows any object initially, but any subsequent item must be of the same class
+        #
+        # @example
+        #   collection << Meal.first
+        #   => #<ApplicationCollection items: [ #<Meal id: 1> ]
+        #
+        #   collection << User.first
+        #   => Collectible::ItemNotAllowedError: not allowed: #<User id: 1>
+        def ensures_type_equality
+          raise Collectible::TypeEnforcementAlreadyDefined if item_enforcement.present?
+
+          self.item_enforcement = ENSURE_TYPE_EQUALITY
+        end
+
+        # Inserts a check before each of the methods provided to validate inserted objects
+        #
+        # @param *methods [Array<Symbol>]
+        def ensure_item_validity_before(*methods)
+          methods.each do |method_name|
+            around_method(method_name, prevent_double_wrapping_for: "EnsureItemValidity") do |*items|
+              ensure_allowed_in_collection!(items)
+
+              super(*items)
+            end
+          end
+        end
+
+        attr_internal_accessor :item_enforcement
+        private :item_enforcement, :item_enforcement=
+      end
+    end
+  end
+end

data/lib/collectible/collection/finder.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Collectible
+  module Collection
+    module Finder
+      extend ActiveSupport::Concern
+
+      # @param attributes [Hash] A hash of arbitrary attributes to match against the collection
+      # @return [*] The first item in the collection that matches the specified attributes
+      def find_by(**attributes)
+        find do |item|
+          attributes.all? do |attribute, value|
+            item.public_send(attribute) == value
+          end
+        end
+      end
+
+      # @param attributes [Hash] A hash of arbitrary attributes to match against the collection
+      # @return [ApplicationCollection] A collection of all items in the collection that match the specified attributes
+      def where(**attributes)
+        select do |item|
+          attributes.all? do |attribute, value|
+            item.public_send(attribute) == value
+          end
+        end
+      end
+    end
+  end
+end

data/lib/collectible/collection/maintain_sort_order.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Collectible
+  module Collection
+    module MaintainSortOrder
+      extend ActiveSupport::Concern
+
+      included do
+        delegate :maintain_sort_order?, to: :class
+
+        disallow_when_sorted :insert, :unshift, :prepend
+        maintain_sorted_order_after :initialize, :push, :<<, :concat
+      end
+
+      class_methods do
+        def inherited(base)
+          base.maintain_sort_order if maintain_sort_order?
+          super
+        end
+
+        def maintain_sort_order?
+          @maintain_sort_order.present?
+        end
+
+        protected
+
+        def maintain_sort_order
+          @maintain_sort_order = true
+        end
+
+        private
+
+        def maintain_sorted_order_after(*methods)
+          methods.each do |method_name|
+            around_method(method_name, prevent_double_wrapping_for: "MaintainSortingOrder") do |*items|
+              super(*items).tap do
+                sort! if maintain_sort_order?
+              end
+            end
+          end
+        end
+
+        def disallow_when_sorted(*methods)
+          methods.each do |method_name|
+            around_method(method_name, prevent_double_wrapping_for: "MaintainSortingOrder") do |*arguments, &block|
+              raise Collectible::MethodNotAllowedError, "cannot call #{method_name} when sorted" if maintain_sort_order?
+
+              super(*arguments, &block)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/collectible/collection/wraps_collection_methods.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Collectible
+  module Collection
+    module WrapsCollectionMethods
+      extend ActiveSupport::Concern
+
+      PROXY_MODULE_NAME = "WrapCollectionMethods"
+
+      included do
+        collection_wrap_delegate :shift, :pop, :find, :index, :at, :[], :first, :last, :uniq, :uniq!, :sort!,
+                                 :unshift, :insert, :prepend, :push, :<<, :concat, :+, :-,
+                                 :any?, :empty?, :present?, :blank?, :length, :count,
+                                 :each, :reverse_each, :cycle
+
+        collection_wrap_on :collection_wrap, :select
+        collection_wrap_values_on :group_by, :partition
+      end
+
+      protected
+
+      def collection_wrap
+        yield
+      end
+
+      class_methods do
+        private
+
+        def collection_wrap_delegate(*methods)
+          methods.each do |method_name|
+            next if method_defined?(method_name)
+
+            define_method(method_name) do |*arguments, &block|
+              collection_wrap { items.public_send(method_name, *arguments, &block) }
+            end
+          end
+        end
+
+        def collection_wrap_on(*methods)
+          methods.each do |method_name|
+            around_method(method_name, prevent_double_wrapping_for: PROXY_MODULE_NAME) do |*args, &block|
+              result = super(*args, &block)
+
+              return self if result.equal?(items)
+
+              result.is_a?(Array) ? self.class.new(result) : result
+            end
+          end
+        end
+
+        def collection_wrap_values_on(*methods)
+          methods.each do |method_name|
+            around_method(method_name, prevent_double_wrapping_for: PROXY_MODULE_NAME) do |*args, &block|
+              result = super(*args, &block)
+
+              if result.respond_to?(:transform_values)
+                result.transform_values { |collection| collection_wrap { collection } }
+              elsif result.respond_to?(:map)
+                result.map { |collection| collection_wrap { collection } }
+              else
+                collection_wrap { result }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/collectible/collection_base.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require_relative "collection/core"
+require_relative "collection/wraps_collection_methods"
+require_relative "collection/ensures_item_eligibility"
+require_relative "collection/maintain_sort_order"
+require_relative "collection/finder"
+
+module Collectible
+  class CollectionBase
+    include ShortCircuIt
+
+    include Tablesalt::StringableObject
+    include Tablesalt::UsesHashForEquality
+
+    include Collectible::Collection::Core
+    include Collectible::Collection::WrapsCollectionMethods
+    include Collectible::Collection::EnsuresItemEligibility
+    include Collectible::Collection::MaintainSortOrder
+    include Collectible::Collection::Finder
+  end
+end

data/lib/collectible/version.rb

@@ -2,5 +2,5 @@
 
 module Collectible
   # This constant is managed by spicerack
-  VERSION = "0.15.0"
+  VERSION = "0.15.1"
 end

metadata

@@ -1,10 +1,11 @@
 --- !ruby/object:Gem::Specification
 name: collectible
 version: !ruby/object:Gem::Version
-  version: 0.15.0
+  version: 0.15.1
 platform: ruby
 authors:
 - Allen Rettberg
+- Eric Garside
 autorequire: 
 bindir: bin
 cert_chain: []
@@ -24,9 +25,38 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 5.2.1
+- !ruby/object:Gem::Dependency
+  name: short_circu_it
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.15.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.15.1
+- !ruby/object:Gem::Dependency
+  name: tablesalt
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.15.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.15.1
 description: Perform operations on and pass around explicit collections of objects
 email:
 - allen.rettberg@freshly.com
+- eric.garside@freshly.com
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -34,6 +64,12 @@ files:
 - LICENSE.txt
 - README.md
 - lib/collectible.rb
+- lib/collectible/collection/core.rb
+- lib/collectible/collection/ensures_item_eligibility.rb
+- lib/collectible/collection/finder.rb
+- lib/collectible/collection/maintain_sort_order.rb
+- lib/collectible/collection/wraps_collection_methods.rb
+- lib/collectible/collection_base.rb
 - lib/collectible/version.rb
 homepage: https://github.com/Freshly/spicerack/tree/master/collectible
 licenses: