pack_api 1.0.1 → 1.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f48730065ece9a8f8e18749b49d15d4f312c997148e86447f09ba8779bd5958d
-  data.tar.gz: 5670802d6da87396caf59e961240dd2bb2d4dcc5b7bf5dafcc4ba83a196add72
+  metadata.gz: 246f379e82f7226306211a320a9f7ec9d7f9d251be0f2817c815a071b8159422
+  data.tar.gz: 939d5be377373d26a4e62ba7fb2870c595aadb52c7527f01c89c512d8af77856
 SHA512:
-  metadata.gz: 2aaf0603ed13870e685757e6f17d8e3e98db880bb2bf0c31785940b0333eb1720cd84c5e15eb54854e6dce2dceb3d5d8780b91ef0c361fa14a498701928ee72f
-  data.tar.gz: af308e82aee39b175b46e19c2ecaafab1a7eb12bb87cd072d2fd33bce808863c003f2b9796cf82329ebd3301cfb20ffd7b4f83145be72f6546a4d707d678037e
+  metadata.gz: 58ac5c88da900f602058aa151a38193bbda938baafd761380c1257079b7ded5e9b107c065dc251b4bc66e39e87fd1f6f623222798c9f50e3cb4dae251a02e6b2
+  data.tar.gz: eaf29a74517055cf5c97596da942d0d2f42197791b53931a2b59d67130e2afa2a6b0db8efa11a24d7c938279e2e111728440aabdef08e9a9282370ba390a001b

data/README.md

@@ -228,6 +228,55 @@ def query_blog_posts(cursor = nil, search = nil, sort = nil, page_size = 50, fil
 end
 ```
 
+## Testing with Shared Examples
+
+PackAPI includes RSpec shared examples to help test your API query methods. These are opt-in and only need to be loaded if you're using RSpec.
+
+### Loading Shared Examples
+
+In your `spec_helper.rb` or `rails_helper.rb`, require the shared examples you need:
+
+```ruby
+# Load all shared examples
+require 'pack_api/rspec/shared_examples_for_api_query_methods'
+require 'pack_api/rspec/shared_examples_for_paginated_results'
+
+# Or load them individually as needed
+require 'pack_api/rspec/shared_examples_for_api_query_methods'
+```
+
+### Using the Shared Examples
+
+**Testing API Query Methods:**
+
+```ruby
+RSpec.describe 'query_blog_posts' do
+  let(:api_query_method) { method(:query_blog_posts) }
+  let(:resources) { BlogPost.all }
+
+  it_behaves_like 'an API query method'
+
+  # With custom options
+  it_behaves_like 'an API query method',
+    model_id_attribute: :uuid,
+    supports_search: true do
+    let(:search_terms) { "searchable text" }
+    let(:matched_resources) { BlogPost.where("title LIKE ?", "%searchable%") }
+  end
+end
+```
+
+**Testing Paginated Methods:**
+
+```ruby
+RSpec.describe 'paginated query' do
+  let(:paginated_api_query_method) { method(:query_blog_posts) }
+  let(:paginated_resources) { BlogPost.all }
+
+  it_behaves_like 'a paginated API method', model_id_attribute: :external_id
+end
+```
+
 ## Development
 
 After checking out the repo, run:

data/lib/pack_api/frozen_empty.rb

@@ -0,0 +1,4 @@
+class PackAPI::FrozenEmpty
+  ARRAY = [].freeze
+  HASH = {}.freeze
+end

data/lib/pack_api/mapping/abstract_transformer.rb

@@ -10,7 +10,7 @@ module PackAPI::Mapping
       @api_type = config[:api_type]
       @model_type = config[:model_type]
       @transform_value = config[:transform_value]
-      @options = {}
+      @options = PackAPI::FrozenEmpty::HASH
     end
 
     ###
@@ -20,7 +20,7 @@ module PackAPI::Mapping
     end
 
     def options=(value)
-      @options = value.presence || {}
+      @options = value.presence || PackAPI::FrozenEmpty::HASH
     end
 
     protected
@@ -30,8 +30,10 @@ module PackAPI::Mapping
     end
 
     def model_attribute(api_attribute)
+      # support _destroy and other special attributes used by Rails
       return api_attribute if api_attribute.start_with?('_')
 
+      # prevent api_attributes from being used unless they are in the public type definition
       unless mappings.key?(api_attribute)
         raise ActiveModel::UnknownAttributeError.new(@model_type.name, api_attribute)
       end

data/lib/pack_api/mapping/api_to_model_attributes_transformer.rb

@@ -5,23 +5,16 @@ module PackAPI::Mapping
   # Specialized attribute transformer allowing API attributes be converted to the attribute names needed to
   # creating/updating an ActiveRecord model.
   class APIToModelAttributesTransformer < AbstractTransformer
-
     def execute
       result = {}
       attribute_names = NormalizedAPIAttribute.new(api_attribute_names)
       data_source.each do |api_attribute, api_value|
         normalized_api_attribute = attribute_names.normalize(api_attribute)
         model_attribute = model_attribute(normalized_api_attribute)
-        model_value = model_value(normalized_api_attribute, api_value)
-        result.deep_merge!({ model_attribute => model_value })
+        model_value = transform_value(normalized_api_attribute, api_value)
+        result[model_attribute] = model_value
       end
       result
     end
-
-    private
-
-    def model_value(api_attribute, api_value)
-      transform_value(api_attribute, api_value)
-    end
   end
 end

data/lib/pack_api/mapping/attribute_hash_transformer.rb

@@ -9,7 +9,6 @@ module PackAPI::Mapping
   # Converts model attributes to API attributes
   # Converts API attributes to model attributes
   class AttributeHashTransformer < AbstractTransformer
-
     def execute
       options.fetch(:contains_model_attributes, true) ?
         model_attributes_to_api_attributes :

data/lib/pack_api/mapping/attribute_map.rb

@@ -26,8 +26,6 @@
 #       associate the error with the "user_id" attribute (not the "user" attribute).
 module PackAPI::Mapping
   class AttributeMap
-    FROZEN_EMPTY_HASH = {}.freeze
-
     attr_reader :config, :options
 
     class << self
@@ -225,25 +223,36 @@ module PackAPI::Mapping
       end
 
       def call(attribute_map, attribute_value)
-        proc ?
-          attribute_map.instance_exec(attribute_value, **@kwargs, &proc) :
-          attribute_map.send(instance_method.name, attribute_value, **@kwargs)
+        if @kwargs
+          proc ?
+            attribute_map.instance_exec(attribute_value, **@kwargs, &proc) :
+            attribute_map.send(instance_method.name, attribute_value, **@kwargs)
+        else
+          proc ?
+            attribute_map.instance_exec(attribute_value, &proc) :
+            attribute_map.send(instance_method.name, attribute_value)
+        end
       end
 
       def kwargs=(new_kwargs)
-        @kwargs = supported_kwargs(new_kwargs)
+        @kwargs = new_kwargs == DEFAULT_OPTIONS || new_kwargs.blank? ?
+                    nil :
+                  supported_kwargs(new_kwargs)
       end
 
       private
 
       def supported_kwargs(kwargs)
-        return FROZEN_EMPTY_HASH if kwargs.blank?
+        return if parameters.empty?
+
+        overlap = parameters.any? { |p| kwargs.key?(p) }
+        return unless overlap
 
-        kwargs.select { |kwarg| parameters.any? { |parameter| parameter.last == kwarg } }
+        kwargs.slice(*parameters)
       end
 
       def parameters
-        @parameters ||= (proc || instance_method).parameters
+        @parameters ||= (proc || instance_method).parameters.map(&:last)
       end
     end
 

data/lib/pack_api/mapping/filter_map.rb

@@ -1,9 +1,6 @@
 # frozen_string_literal: true
 
 module PackAPI::Mapping
-  FROZEN_EMPTY_ARRAY = [].freeze
-  FROZEN_EMPTY_HASH = {}.freeze
-
   ##
   # This class is responsible for transforming API filter names into model filters. It also produces filter definitions
   # in API terms for those filters that are supported by the model.
@@ -43,7 +40,7 @@ module PackAPI::Mapping
 
     def api_attribute_filter_names
       @api_attribute_filter_names ||= attribute_map_class.nil? ?
-                                        FROZEN_EMPTY_ARRAY :
+                                        PackAPI::FrozenEmpty::ARRAY :
                                         attribute_map_class.api_type.filterable_attributes.keys
     end
 
@@ -51,7 +48,7 @@ module PackAPI::Mapping
     # Map from a backend filter name to an API filter name for default attribute filters.
     def api_attribute_filter_name_map
       return @api_attribute_filter_name_map if defined?(@api_attribute_filter_name_map)
-      return FROZEN_EMPTY_HASH if attribute_map_class.nil?
+      return PackAPI::FrozenEmpty::HASH if attribute_map_class.nil?
 
       names = {}
       api_attribute_filter_names.each { |name| names[name] = name }

data/lib/pack_api/mapping/model_to_api_attributes_transformer.rb

@@ -5,7 +5,6 @@ module PackAPI::Mapping
   # Specialized attribute transformer converting an ActiveRecord model attributes to the attribute names needed
   # to create a ValueObject in the public API.
   class ModelToAPIAttributesTransformer < AbstractTransformer
-
     def options=(options)
       super
       @optional_attributes_to_include = nil
@@ -17,15 +16,17 @@ module PackAPI::Mapping
         model_attribute = model_attribute(api_attribute)
         next unless include_model_attribute?(model_attribute)
 
-        value = unless optional_api_attribute?(api_attribute) && !include_api_attribute?(api_attribute)
-                  api_value(api_attribute, model_value(model_attribute))
-                end
-        result[api_attribute] = value
+        api_value = transform_value(api_attribute, model_value(model_attribute)) if include_api_attribute?(api_attribute)
+        result[api_attribute] = api_value
       end
     end
 
     protected
 
+    def include_api_attribute?(api_attribute)
+      !optional_api_attribute?(api_attribute) || include_optional_api_attribute?(api_attribute)
+    end
+
     def model_attributes_of_interest
       @model_attributes_of_interest ||= options[:model_attributes_of_interest]
     end
@@ -38,7 +39,7 @@ module PackAPI::Mapping
       api_type_optional_attributes.include?(api_attribute_name)
     end
 
-    def include_api_attribute?(api_attribute_name)
+    def include_optional_api_attribute?(api_attribute_name)
       return false if optional_attributes_to_include.nil?
       return false if optional_attributes_to_include.respond_to?(:exclude?) &&
                       optional_attributes_to_include.exclude?(api_attribute_name)
@@ -53,15 +54,11 @@ module PackAPI::Mapping
     end
 
     def api_type_optional_attributes
-      @api_type_optional_attributes ||= api_type.optional_attributes || []
+      @api_type_optional_attributes ||= api_type.optional_attributes || PackAPI::FrozenEmpty::ARRAY
     end
 
     def model_value(model_attribute)
       data_source.public_send(model_attribute)
     end
-
-    def api_value(api_attribute, model_value)
-      transform_value(api_attribute, model_value)
-    end
   end
 end

data/lib/pack_api/mapping/value_object_factory.rb

@@ -2,7 +2,6 @@
 
 module PackAPI::Mapping
   class ValueObjectFactory
-
     class << self
       attr_reader :attribute_map_registry, :value_object_attributes
 

data/lib/pack_api/querying/dynamic_enum_filter.rb

@@ -2,8 +2,6 @@
 
 module PackAPI::Querying
   module DynamicEnumFilter
-    FROZEN_EMPTY_ARRAY = [].freeze
-
     extend ActiveSupport::Concern
     class_methods do
       def type = :dynamic_enum
@@ -14,7 +12,7 @@ module PackAPI::Querying
 
       private
 
-      def filter_options(**) = FROZEN_EMPTY_ARRAY
+      def filter_options(**) = PackAPI::FrozenEmpty::ARRAY
     end
   end
 end

data/lib/pack_api/rspec/shared_examples_for_api_query_methods.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+module PackAPI
+  ###
+  # Assumes the following variables are defined:
+  # - api_query_method: the method to call
+  # - resources: the resources to compare against (must be more than 1)
+  #
+  # If the options contain a key :model_id_attribute, then the public id will be mapped to the given model attribute.
+  # Otherwise, it defaults to :external_id.
+  #
+  # If the options contain a key: `supports_search` set to `true`, then
+  # the following variables are also required:
+  # - search_terms: a string, representing the search terms to use
+  # - matched_resources: *at least 2* resources that will be returned by the search
+  RSpec.shared_examples 'an API query method' do |**options|
+    let(:model_id_attribute) { options[:model_id_attribute] || :external_id }
+
+    context 'with no id' do
+      it 'returns a successful result with all resources' do
+        # when
+        result = api_query_method.call
+
+        # then
+        expect(result.success).to be_truthy, -> { result.errors }
+        expect(result.errors).to be_nil
+        expect(result.value).not_to be_nil
+        expect(result.value).to have(resources.count).items
+        expect(result.value.pluck(:id).sort).to match_array(resources.pluck(model_id_attribute).sort)
+      end
+    end
+
+    context 'with nil id' do
+      it 'returns a successful result with all resources' do
+        # when
+        result = api_query_method.call(id: nil)
+
+        # then
+        expect(result.success).to be_truthy, -> { result.errors }
+        expect(result.errors).to be_nil
+        expect(result.value).not_to be_nil
+        expect(result.value).to have(resources.count).items
+        expect(result.value.pluck(:id).sort).to match_array(resources.pluck(model_id_attribute).sort)
+      end
+    end
+
+    context 'with an empty string id' do
+      it 'returns a successful result with no resources' do
+        # when
+        result = api_query_method.call(id: '')
+
+        # then
+        expect(result.success).to be_truthy, -> { result.errors }
+        expect(result.errors).to be_nil
+        expect(result.value).not_to be_nil
+        expect(result.value).to have(0).items
+      end
+    end
+
+    context 'with an empty array id' do
+      it 'returns a successful result with no resources' do
+        # when
+        result = api_query_method.call(id: [])
+
+        # then
+        expect(result.success).to be_truthy, -> { result.errors }
+        expect(result.errors).to be_nil
+        expect(result.value).not_to be_nil
+        expect(result.value).to have(0).items
+      end
+    end
+
+    context 'with an unknown id' do
+      it 'returns an empty success result' do
+        result = api_query_method.call(id: 'unknown')
+        expect(result.success).to be_truthy, -> { result.errors }
+        expect(result.value).to have(0).items
+      end
+    end
+
+    context 'with a known id' do
+      it 'returns a success result with the resource' do
+        value = api_query_method.call(id: resources.first[model_id_attribute])
+        expect(value.success).to be_truthy, -> { result.errors }
+        expect(value.value).to have(1).item
+        expect(value.value.first.id).to eq(resources.first[model_id_attribute])
+      end
+    end
+
+    it_behaves_like 'a paginated API method', model_id_attribute: options[:model_id_attribute] || :external_id do
+      let(:paginated_api_query_method) { api_query_method }
+      let(:paginated_resources) { resources }
+    end
+
+    context 'with search terms', if: options[:supports_search] do
+      it 'limits results to matching resources' do
+        # when
+        result = api_query_method.call(search_terms:)
+        # then
+        expect(result.success).to be_truthy, -> { result.errors }
+        expect(result.value).to have(matched_resources.size).item
+        matched_resource_ids = matched_resources.pluck(model_id_attribute)
+        result.value.each do |resource|
+          expect(matched_resource_ids).to include(resource.id)
+        end
+      end
+
+      it_behaves_like 'a paginated API method', model_id_attribute: options[:model_id_attribute] || :external_id do
+        let(:paginated_api_query_method) do
+          ->(**args) { api_query_method.call(search_terms:, **args) }
+        end
+        let(:paginated_resources) { matched_resources }
+      end
+    end
+
+    it 'supports sorting by API attributes only' do
+      resources.each_with_index { |resource, index| resource.update(model_id_attribute => format('%02d', index + 1)) }
+      # when - sort by API attribute `id` in descending order
+      results = api_query_method.call(sort: { id: :desc })
+      # then - results should be in model_id_attribute in descending order
+      expect(results.success).to be_truthy, -> { results.errors }
+      expect(results.value.first.id).to eq(resources.last[model_id_attribute])
+      expect(results.value.last.id).to eq(resources.first[model_id_attribute])
+    end
+  end
+end

data/lib/pack_api/rspec/shared_examples_for_paginated_results.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module PackAPI
+  ###
+  # Assumes the following variables are defined:
+  # - paginated_api_query_method: the method to call
+  # - paginated_resources: the resources to compare against (must be more than 1)
+  #
+  # If the options contain a key :model_id_attribute, then the public id will be mapped to the given model attribute.
+  # Otherwise, it defaults to :external_id.
+  # If the options contain a key :public_id_attribute, that will be used to access the resource identifier in the results.
+  RSpec.shared_examples 'a paginated API method' do |**options|
+    let(:public_id_attribute) { options[:public_id_attribute] || :id }
+    let(:model_id_attribute) { options[:model_id_attribute] || :external_id }
+
+    it 'can access the resources page-by-page' do
+      returned_object_ids = []
+
+      page_one_results = paginated_api_query_method.call(per_page: 1)
+      expect(page_one_results.success).to be_truthy, -> { page_one_results.errors }
+      expect(page_one_results.value).to have(1).item
+      expect(page_one_results.collection_metadata.next_page_cursor).not_to be_nil
+      returned_object_ids << page_one_results.value.first.send(public_id_attribute)
+      next_page_cursor = page_one_results.collection_metadata.next_page_cursor
+
+      (paginated_resources.count - 1).times do |index|
+        next_page_results = paginated_api_query_method.call(per_page: 1, cursor: next_page_cursor)
+        expect(next_page_results.success).to be_truthy, -> { next_page_results.errors }
+        expect(next_page_results.value).to have(1).item
+        if index < paginated_resources.count - 2 # if not last page
+          expect(next_page_results.collection_metadata.next_page_cursor).not_to be_nil, 'next page cursor should not be nil'
+          next_page_cursor = next_page_results.collection_metadata.next_page_cursor
+        else
+          expect(next_page_results.collection_metadata.next_page_cursor).to be_nil, 'next page cursor should be nil'
+        end
+        returned_object_ids << next_page_results.value.first.send(public_id_attribute)
+      end
+
+      # verify all objects were returned
+      expect(returned_object_ids.sort).to match_array(paginated_resources.pluck(model_id_attribute).sort)
+    end
+
+    it 'can access the metadata (without data)' do
+      results = paginated_api_query_method.call(per_page: 0)
+      expect(results.success).to be_truthy, -> { results.errors }
+      expect(results.value).to be_empty
+      expect(results.collection_metadata).not_to be_nil
+      expect(results.collection_metadata.total_items).to eq(paginated_resources.count)
+    end
+  end
+end

data/lib/pack_api/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module PackAPI
-  VERSION = "1.0.1"
+  VERSION = "1.0.3"
 end

data/lib/pack_api.rb

@@ -9,6 +9,7 @@ require_relative "types"
 require_relative "pack_api/version"
 
 module PackAPI
+  autoload :FrozenEmpty, "pack_api/frozen_empty"
   autoload :InternalError, "pack_api/internal_error"
   autoload :ValuesInBatches, "pack_api/values_in_batches"
   autoload :ValuesInBackgroundBatches, "pack_api/values_in_background_batches"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pack_api
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.0.3
 platform: ruby
 authors:
 - Flytedesk
@@ -199,6 +199,7 @@ files:
 - LICENSE.txt
 - README.md
 - lib/pack_api.rb
+- lib/pack_api/frozen_empty.rb
 - lib/pack_api/internal_error.rb
 - lib/pack_api/mapping/abstract_transformer.rb
 - lib/pack_api/mapping/api_to_model_attributes_transformer.rb
@@ -230,6 +231,8 @@ files:
 - lib/pack_api/querying/dynamic_enum_filter.rb
 - lib/pack_api/querying/filter_factory.rb
 - lib/pack_api/querying/sort_hash.rb
+- lib/pack_api/rspec/shared_examples_for_api_query_methods.rb
+- lib/pack_api/rspec/shared_examples_for_paginated_results.rb
 - lib/pack_api/types/aggregate_type.rb
 - lib/pack_api/types/base_type.rb
 - lib/pack_api/types/boolean_filter_definition.rb