pack_api 1.0.17 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d2ad9f8208ab7d473868cdfb1f5ea2c1a1331c8312cb24a41d105e2a1601d5c5
-  data.tar.gz: f96b4024f722cbec40c1a2846a6d11b6dcfcf1779dea45c32b256079ed5f0834
+  metadata.gz: 62245994a5ffa0d342e05ee798356a0c6d61063a513accacd43195ab74e39416
+  data.tar.gz: 8be813a9fc9f0dcbdec802796cc632c680ae1273d104acc46f1c401da21ede88
 SHA512:
-  metadata.gz: 73ddd88c532c6dd6357ba55a2783272390b3841a04f1e9b36bb1a833d5ba9a013b855a54b949a808e6c711ef0a5c63ccbe7c519b8ef70b067bbfe42534886213
-  data.tar.gz: 3b943634599761edb3abdb651ba02ca7e679770b39ffb6a1d9197440c5064703bbf2147fa492aaca60ae95fc63da3eb7f9307836ad06674b63e979e692ae84c4
+  metadata.gz: 53c8cdb641ca26ef408e57e2fffa5e7d414f96f3f59a5ae030b18912b86c21bf85dd76ac53dc5c8ef38f42b4f58ceeec007d08f9e7eaba41634f4ab1a6ed08fb
+  data.tar.gz: 6a2dfbf4e5914dacc384f4206fbd207f85f149df6cfc8d9ac2a0c8599566b0bdac866f2fa56396a10b8ec6446c2939d26145a1ce3477b8e8f23c88dd78fb3451

data/README.md

@@ -57,7 +57,7 @@ gem install pack_api
 The mapping module provides tools for transforming data between domain models and API representations:
 
 - `AttributeMap` - Define bidirectional mappings between model and API attributes
-- `AttributeMapRegistry` - Centralized registry for attribute mappings
+- `AttributeMapRegistry` - Finds the attribute map for a model, by naming convention or explicit registration
 - `ModelToAPIAttributesTransformer` - Transform model attributes to API format
 - `APIToModelAttributesTransformer` - Transform API attributes to model format
 - `ValueObjectFactory` - Create value objects from raw data
@@ -141,9 +141,8 @@ end
 class AuthorAttributeMap < PackAPI::Mapping::AttributeMap
   api_type AuthorType
   model_type Author
-  map :name, to: :name
   map :id, to: :external_id
-  map :blog_posts
+  # name and blog_posts share their names with the model attributes, so they need no map
 end
 
 # api/comment_attribute_map.rb
@@ -158,17 +157,16 @@ class BlogPostAttributeMap < PackAPI::Mapping::AttributeMap
   api_type BlogPostType
   model_type BlogPost
 
-  # example API attribute mapped to a model attribute of the same name
-  map :title
+  # API attributes with the same name as the model attribute (title) need no map
+
+  # example of API attribute ending in "_id" (mapped explicitly for documentation; the default would be identical)
+  map :legacy_id
 
   map :contents, from_model_attribute: ->(attachment) { attachment&.blob }
 
   # example API attribute mapped to a model attribute of a different name
   map :id, to: :external_id
 
-  # example of API attribute ending in "_id"
-  map :legacy_id
-
   # example of API attribute mapped to a model method (unidirectional)
   map :persisted, to: :persisted?, readonly: true
 
@@ -185,7 +183,36 @@ end
 
 ```
 
-3. Implement filters. 
+3. Implement filters and register them in a filter factory. Attributes marked `filterable: true` on the value object
+   type get an `AttributeFilter` each via `register_attribute_filters`; anything else is a filter class of its own:
+
+```ruby
+# models/filters/blog_post/filter_factory.rb
+module Filters::BlogPost
+  class FilterFactory < PackAPI::Querying::FilterFactory
+    def initialize
+      super
+      register_attribute_filters(BlogPostAttributeMap)
+      register_filter(AuthorFilter) # keyed by AuthorFilter.filter_name
+    end
+  end
+end
+
+# api/blog_post_filter_map.rb
+# resolves Filters::BlogPost::FilterFactory and BlogPostAttributeMap from its own name
+class BlogPostFilterMap < PackAPI::Mapping::FilterMap; end
+```
+
+The registry and value object factory follow the same pattern, so they are usually empty classes too
+(see [Naming Conventions](#naming-conventions)):
+
+```ruby
+# api/attribute_map_registry.rb
+class AttributeMapRegistry < PackAPI::Mapping::AttributeMapRegistry; end
+
+# api/value_object_factory.rb
+class ValueObjectFactory < PackAPI::Mapping::ValueObjectFactory; end
+```
 
 4. Implement a query endpoint using the attribute map:
 
@@ -228,6 +255,35 @@ def query_blog_posts(cursor = nil, search = nil, sort = nil, page_size = 50, fil
 end
 ```
 
+## Naming Conventions
+
+PackAPI infers collaborators from class names so that the classes a pack needs are mostly declarations of intent
+with empty bodies. Every convention is a **default**, not a requirement: pass the argument or make the registration
+explicitly and the convention is never consulted. A project that names things differently keeps working unchanged.
+
+Given a pack namespace `Blogging` and a resource `Post`:
+
+| Class | Infers | Explicit alternative |
+|---|---|---|
+| `Blogging::PostFilterMap < Mapping::FilterMap` | `filter_factory` = `Blogging::Filters::Post::FilterFactory.new`<br>`attribute_map_class` = `Blogging::PostAttributeMap` (nil when absent) | `super(filter_factory: ..., attribute_map_class: ...)` in `initialize` |
+| `Blogging::AttributeMapRegistry < Mapping::AttributeMapRegistry` | attribute map for model `Blogging::Post` = `Blogging::PostAttributeMap`<br>nested models resolve to nested maps: `Blogging::Post::Draft` -> `Blogging::PostAttributeMap::Draft` | `register_attribute_map(SomeAttributeMap)`; an explicit registration always wins over the convention |
+| `Blogging::ValueObjectFactory < Mapping::ValueObjectFactory` | `attribute_map_registry` = `Blogging::AttributeMapRegistry` | `set_attribute_map_registry(SomeRegistry)` |
+| any `Mapping::AttributeMap` with an `api_type` | an identity mapping (`map :title`) for every attribute of the api type | `map :title, to: :headline` (or any other `map` option) overrides the identity mapping for that attribute |
+| `Querying::FilterFactory#register_filter(klass)` | filter name = `klass.filter_name` | `register_filter(klass, name: :other)` or `register_filter(name:, klass:)` |
+| `Querying::FilterFactory#register_attribute_filters(attribute_map_class)` | one `AttributeFilter` per attribute marked `filterable: true` on the api type | register attribute filters by hand |
+
+Notes:
+
+- The identity mapping has no opt-out because it never changes behaviour: an api attribute without a mapping was
+  already rejected as an `unknown attribute` on both read and write, so any working attribute map mapped every api
+  attribute explicitly. The default only fills those mandatory entries.
+- Several api attributes may map to one model attribute (a rename next to the identity mapping, e.g.
+  `map :filename, to: :file` beside `file`). A nested attribute error on that model attribute is reported on the
+  api attribute with the same name when there is one, otherwise on the first mapping declared for it.
+- Conventions resolve constants lazily, on first use, so autoloading (Zeitwerk) works without eager registration.
+- A namespace is the class name minus its last segment (`Blogging::PostFilterMap` -> `Blogging`). Top-level classes
+  resolve top-level collaborators (`PostFilterMap` -> `Filters::Post::FilterFactory`).
+
 ## 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.

data/lib/pack_api/mapping/attribute_map.rb

@@ -56,15 +56,25 @@ module PackAPI::Mapping
       end
 
       def config
+        mappings = identity_mappings.merge(@mappings || {})
         {
-          mappings: @mappings,
-          from_api_attributes: @from_api_attributes,
-          from_model_attributes: @from_model_attributes,
-          transform_nested_attributes_with: @transform_nested_attributes_with,
+          mappings:,
+          from_api_attributes: @from_api_attributes || {},
+          from_model_attributes: @from_model_attributes || {},
+          transform_nested_attributes_with: @transform_nested_attributes_with || {},
           api_type: @api_type,
           model_type: @model_type
         }
       end
+
+      private
+
+      # every api type attribute maps to a model attribute of the same name
+      def identity_mappings
+        return {} unless @api_type
+
+        @api_type.attribute_names.index_with(&:itself)
+      end
     end
 
     def self.model_attribute_keys(hash)

data/lib/pack_api/mapping/attribute_map_registry.rb

@@ -1,21 +1,34 @@
 # frozen_string_literal: true
 
 module PackAPI::Mapping
+  ###
+  # Finds the attribute map for a model class. A registry named "<Namespace>::AttributeMapRegistry" resolves
+  # "<Namespace>::<Model>AttributeMap" by convention (nested models resolve to nested attribute maps, e.g.
+  # <Namespace>::Post::Draft -> <Namespace>::PostAttributeMap::Draft); register_attribute_map covers the exceptions.
   class AttributeMapRegistry
 
     class << self
-      attr_reader :attribute_maps
+      def attribute_maps
+        @attribute_maps ||= {}
+      end
 
       def register_attribute_map(attribute_map_class)
-        @attribute_maps ||= {}
-        @attribute_maps[attribute_map_class.model_type] = attribute_map_class
+        attribute_maps[attribute_map_class.model_type] = attribute_map_class
       end
     end
 
     def attribute_map_class(model_class)
-      raise "No attribute map defined for #{model_class}" unless self.class.attribute_maps.key?(model_class)
+      self.class.attribute_maps[model_class] ||
+        conventional_attribute_map_class(model_class) ||
+        raise("No attribute map defined for #{model_class}")
+    end
+
+    private
 
-      self.class.attribute_maps[model_class]
+    def conventional_attribute_map_class(model_class)
+      namespace = self.class.name.deconstantize
+      model, *nested = model_class.name.delete_prefix("#{namespace}::").split('::')
+      [namespace.presence, "#{model}AttributeMap", *nested].compact.join('::').safe_constantize
     end
   end
 end

data/lib/pack_api/mapping/error_hash_to_api_attributes_transformer.rb

@@ -35,13 +35,19 @@ module PackAPI::Mapping
         child_model_attribute = match_data[:child].to_sym
         child_api_attribute = child_model_attribute
         if child_attribute_map_class
-          mapping = child_attribute_map_class.config[:mappings].find { |_k, v| v == child_model_attribute }
-          child_api_attribute = mapping.first if mapping
+          child_api_attribute = api_attribute_for(child_attribute_map_class.config[:mappings], child_model_attribute)
         end
         "#{parent_api_attribute}[#{match_data[:index]}].#{child_api_attribute}"
       end
     end
 
+    # several api attributes may map to one model attribute (e.g. a rename next to the identity mapping);
+    # the error belongs to the api attribute named like the model attribute when there is one
+    def api_attribute_for(mappings, model_attribute)
+      candidates = mappings.filter_map { |api_attribute, mapped| api_attribute if mapped == model_attribute }
+      candidates.find { |api_attribute| api_attribute == model_attribute } || candidates.first || model_attribute
+    end
+
     def nested_attribute_error_key?(error_key)
       NESTED_ATTRIBUTE_ERROR_KEY.match?(error_key.to_s)
     end

data/lib/pack_api/mapping/filter_map.rb

@@ -4,10 +4,13 @@ module PackAPI::Mapping
   ##
   # 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.
+  #
+  # A subclass named "<Namespace>::<Resource>FilterMap" resolves its collaborators by convention:
+  # "<Namespace>::Filters::<Resource>::FilterFactory" and "<Namespace>::<Resource>AttributeMap" (if it exists).
   class FilterMap
     attr_reader :filter_factory, :attribute_map_class
 
-    def initialize(filter_factory:, attribute_map_class: nil)
+    def initialize(filter_factory: default_filter_factory, attribute_map_class: default_attribute_map_class)
       @filter_factory = filter_factory
       @attribute_map_class = attribute_map_class
     end
@@ -29,6 +32,22 @@ module PackAPI::Mapping
 
     private
 
+    def default_filter_factory
+      conventional_constant('Filters', resource_name, 'FilterFactory').constantize.new
+    end
+
+    def default_attribute_map_class
+      conventional_constant("#{resource_name}AttributeMap").safe_constantize
+    end
+
+    def conventional_constant(*segments)
+      [self.class.name.deconstantize.presence, *segments].compact.join('::')
+    end
+
+    def resource_name
+      self.class.name.demodulize.delete_suffix('FilterMap')
+    end
+
     def attribute_filter_definition(filter_name, filter_class)
       api_filter_name = api_attribute_filter_name_map[filter_name]
       filter_class.definition.merge(name: api_filter_name)

data/lib/pack_api/mapping/value_object_factory.rb

@@ -3,16 +3,21 @@
 module PackAPI::Mapping
   class ValueObjectFactory
     class << self
-      attr_reader :attribute_map_registry, :value_object_attributes
+      # defaults to "<Namespace>::AttributeMapRegistry" for a factory named "<Namespace>::ValueObjectFactory"
+      def attribute_map_registry
+        @attribute_map_registry ||= "#{name.deconstantize}::AttributeMapRegistry".safe_constantize
+      end
 
       def set_attribute_map_registry(registry)
         @attribute_map_registry = registry
+      end
+
+      def value_object_attributes
         @value_object_attributes ||= {}
       end
 
       def model_attributes_containing_value_objects(*attributes, model_class:)
-        @value_object_attributes ||= {}
-        @value_object_attributes[model_class] = attributes
+        value_object_attributes[model_class] = attributes
       end
     end
 

data/lib/pack_api/pagination/opaque_token_v2.rb

@@ -4,8 +4,12 @@ require 'brotli'
 
 module PackAPI::Pagination
   class OpaqueTokenV2
+    # brotli's default quality (11) is tuned for large static assets; cursor payloads are a few hundred bytes of
+    # JSON, where quality 5 yields the same size for a fraction of the CPU. Inflate does not depend on quality.
+    QUALITY = 5
+
     def self.create(unencoded)
-      Base64.strict_encode64(Brotli.deflate(unencoded.to_json))
+      Base64.strict_encode64(Brotli.deflate(unencoded.to_json, quality: QUALITY))
     end
 
     def self.parse(encoded)

data/lib/pack_api/querying/filter_factory.rb

@@ -8,8 +8,13 @@ module PackAPI::Querying
       @filter_classes = Hash.new { |_hash, key| raise NotImplementedError, "Unsupported filter #{key}" }
     end
 
-    def register_filter(name:, klass:)
-      filter_classes[name] = klass
+    def register_filter(filter_class = nil, name: nil, klass: filter_class)
+      filter_classes[name || klass.filter_name] = klass
+    end
+
+    # registers an AttributeFilter for each filterable attribute of the attribute map's api type
+    def register_attribute_filters(attribute_map_class)
+      AttributeFilterFactory.new(attribute_map_class).from_api_type { register_filter(it) }
     end
 
     def create_filters(filter_hash)

data/lib/pack_api/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pack_api
 version: !ruby/object:Gem::Version
-  version: 1.0.17
+  version: 1.1.0
 platform: ruby
 authors:
 - Flytedesk
@@ -269,7 +269,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.6
+rubygems_version: 4.0.16
 specification_version: 4
 summary: Building blocks for implementing APIs around domain models
 test_files: []