pack_api 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 97d36561d79762a67e842fc092ff22d1d66de8c230e1abcb6adff3bedc86edf7
+  data.tar.gz: e4145510ed3cb11d94340c8b48d21dd454037dd8906ac00004f5bbbdc0b43d55
+SHA512:
+  metadata.gz: e0f38e85af2248f3898ebbf99fa534133fbc5c2e10c6e8958aa7919b75174150a1ad005f4a31ed267c1674d56f02c1ad0e58c484db523f83e486c695a38e0207
+  data.tar.gz: 1c5ab5ad08af202d504550d3266c539a65836f210e434caa9330dee911b2285f6fabb2b9d4507ff3bbcab33976f67f5b8ecd226c3f31f115222acac64aba0435

data/CHANGELOG.md

@@ -0,0 +1,39 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2025-11-10
+
+### Added
+
+- Initial release of PackAPI gem
+- Mapping module for transforming data between domain models and API representations
+  - AttributeMap for defining bidirectional mappings
+  - AttributeMapRegistry for centralized mapping management
+  - ModelToAPIAttributesTransformer and APIToModelAttributesTransformer
+  - ValueObjectFactory for creating value objects
+- Querying module for building flexible query interfaces
+  - ComposableQuery and CollectionQuery
+  - Filter implementations (boolean, enum, numeric, range)
+  - FilterFactory for dynamic filter creation
+  - SortHash for handling sorting parameters
+- Pagination module with multiple strategies
+  - Paginator for standard pagination
+  - SnapshotPaginator for consistent results
+  - PaginatorBuilder for custom configurations
+  - OpaqueTokenV2 for secure cursor tokens
+- Types module with dry-types integration
+  - BaseType and AggregateType
+  - Result and CollectionResultMetadata
+  - Filter definition types
+- Batch operation utilities
+  - ValuesInBatches for synchronous batch processing
+  - ValuesInBackgroundBatches for asynchronous batch processing
+
+[Unreleased]: https://github.com/flytedesk/pack_api/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/flytedesk/pack_api/releases/tag/v0.1.0

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Flytedesk
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,238 @@
+# PackAPI
+
+Building blocks for implementing APIs around domain models.
+
+## Overview
+
+PackAPI provides a comprehensive set of tools for building robust API layers on top of domain models. It includes utilities for:
+
+- **Data transformation** - Elements for passing data out of the API
+- **Filter definitions** - Elements for describing the filters supported by query endpoints in the API
+- **Attribute mapping** - Elements for building the mapping between domain models and API models
+- **Query building** - Elements for building query endpoints based on user inputs (sort, filter, pagination)
+- **Batch operations** - Elements for retrieving multiple pages of data from other query endpoints
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'pack_api'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself as:
+
+```bash
+gem install pack_api
+```
+
+## Requirements
+
+- Ruby >= 3.0.0
+- ActiveRecord >= 7.0
+- dry-types ~> 1.8
+
+## Features
+
+### Mapping
+
+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
+- `ModelToAPIAttributesTransformer` - Transform model attributes to API format
+- `APIToModelAttributesTransformer` - Transform API attributes to model format
+- `ValueObjectFactory` - Create value objects from raw data
+
+### Querying
+
+Build flexible query interfaces with support for filtering, sorting, and pagination:
+
+- `ComposableQuery` - Build complex queries from simpler components
+- `CollectionQuery` - Query collections with filtering and sorting
+- `AbstractFilter` - Base class for custom filters
+- Filter implementations for boolean, enum, numeric, and range filters
+- `FilterFactory` - Create filters dynamically based on query method arguments
+- `SortHash` - Handle sorting parameters
+
+### Pagination
+
+Enable paginated access to resources across the API:
+
+- `Paginator` - Standard pagination implementation
+- `PaginatorBuilder` - Build paginators with custom configurations
+- `SnapshotPaginator` - Enable record iteration (one by one) across results in a page, 
+even when the underlying records change state (and may no longer be at the same position in the result set)
+
+### Types
+
+Type definitions and validation using dry-types:
+
+- `BaseType` - Base type for API models
+- `CollectionResultMetadata` - Metadata for paginated collections
+- `Result` - Generic result type
+- `AggregateType` - Composite types made of attributes from other types
+- Filter definition types for various data types
+
+### Batch Operations
+
+Utilities for processing large datasets efficiently:
+
+- `ValuesInBatches` - Process values in batches
+- `ValuesInBackgroundBatches` - Process values in background batches
+
+## Usage
+
+### Basic Example
+
+See the test files for more detailed examples, but here's a simple usage example. 
+
+Let's assume your system has Author, Comment and BlogPost ActiveRecord models.
+
+1. Define value objects to contain the data passed out of the API:
+
+```ruby
+
+# public/author_type.rb
+class AuthorType < PackAPI::Types::BaseType
+  attribute :id, ::Types::String
+  attribute :name, ::Types::String
+end
+
+# public/comment_type.rb
+class CommentType < PackAPI::Types::BaseType
+  attribute :text, ::Types::String
+end
+
+# public/blog_post_type.rb
+class BlogPostType < PackAPI::Types::BaseType
+  attribute :id, ::Types::String
+  attribute :legacy_id, ::Types::String
+  attribute :title, ::Types::String
+  attribute :persisted, ::Types::Bool
+  attribute :contents, ::Types::String.optional
+  optional_attribute :associated, AuthorType
+  optional_attribute :notes, ::Types::Array.of(CommentType)
+  optional_attribute :earnings_float, ::Types::Coercible::Float
+end
+```
+
+2. Define the rules for mapping between the domain models and the API value objects:
+
+```ruby
+# api/author_attribute_map.rb
+class AuthorAttributeMap < PackAPI::Mapping::AttributeMap
+  api_type AuthorType
+  model_type Author
+  map :name, to: :name
+  map :id, to: :external_id
+  map :blog_posts
+end
+
+# api/comment_attribute_map.rb
+class CommentAttributeMap < PackAPI::Mapping::AttributeMap
+  api_type CommentType
+  model_type Comment
+  map :text, to: :txt
+end
+
+# api/blog_post_attribute_map.rb
+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
+
+  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
+
+  # example of API association mapped to a model association
+  # (the association_id can also be passed in, and reported on during error cases)
+  map :associated, to: :author,
+      from_api_attribute: ->(author_id) { Author.find_by(external_id: author_id) }
+
+  map :notes, to: :comments, transform_nested_attributes_with: CommentAttributeMap
+
+  # example of OPTIONAL API attribute (association) mapped to a model method (bidirectional)
+  map :earnings_float, to: :earnings_float
+end
+
+```
+
+3. Implement a query endpoint using the attribute map:
+
+```ruby
+def query_blog_posts(cursor = nil, search = nil, sort = nil, page_size = 50, filters = {}, optional_attributes = [])
+  collection = BlogPost.all
+  
+  # avoid N+1 queries for optional attributes that are associations
+  if optional_attributes.include?(:associated)
+    collection = collection.includes(:author)
+  end
+  
+  # convert the search terms to something used by the CollectionQuery to perform searches (hash of model attributes to search terms)
+  if search.present?
+    # search through blog post title and comments
+    collection = collection.includes(:comments)
+    model_search = {
+      'title' => search,
+      "#{Comment.table_name}.txt" => search,
+    }
+  end
+  
+  # convert the API sort to model sort
+  model_sort = BlogPostAttributeMap.model_attribute_keys(PackAPI::Querying::SortHash.new(sort))
+
+  # convert the API filters to model filters
+  model_filters = BlogPostFilterMap.new.from_api_filters(filters)
+
+  # build and execute the query
+  query = PackAPI::Querying::CollectionQuery.new(collection:)
+  query.filter_factory = Filters::BlogPost::FilterFactory.new
+  query.call(cursor:, per_page: page_size, sort: model_sort, search: model_search, filters: model_filters)
+  
+  # build and return the result
+  PackAPI::Types::Result.from_collection(models: query.results,
+                                         value_object_factory: ValueObjectFactory.new,
+                                         optional_attributes:,
+                                         sort: BlogPostAttributeMap.api_attribute_keys(query.sort),
+                                         paginator: query.paginator)
+end
+```
+
+## Development
+
+After checking out the repo, run:
+
+```bash
+bundle install
+```
+
+Run the test suite:
+
+```bash
+bundle exec rspec
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/flytedesk/pack_api.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/pack_api/config/dry_types_initializer.rb

@@ -0,0 +1 @@
+require_relative '../../types'

data/lib/pack_api/models/internal_error.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module PackAPI
+  ###
+  # Error class for passing errors from the model to the API logic
+  class InternalError < StandardError
+    attr_reader :object, :options
+
+    def initialize(msg = nil, object: nil, options: {})
+      super(msg)
+      @object = object
+      @options = options
+    end
+
+    def message
+      to_s
+    end
+
+    def to_s
+      return super unless object.present?
+
+      "#{super} - #{object.inspect}"
+    end
+  end
+end

data/lib/pack_api/models/mapping/abstract_transformer.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module PackAPI::Mapping
+  class AbstractTransformer
+    attr_accessor :mappings, :api_type, :model_type, :data_source
+    attr_reader :options
+
+    def initialize(config)
+      @mappings = config[:mappings]
+      @api_type = config[:api_type]
+      @model_type = config[:model_type]
+      @transform_value = config[:transform_value]
+      @options = {}
+    end
+
+    ###
+    # @abstract
+    def execute
+      raise NotImplementedError
+    end
+
+    def options=(value)
+      @options = value.presence || {}
+    end
+
+    protected
+
+    def transform_value(api_attribute, value)
+      @transform_value.call(api_attribute, value)
+    end
+
+    def model_attribute(api_attribute)
+      return api_attribute if api_attribute.start_with?('_')
+
+      unless mappings.key?(api_attribute)
+        raise ActiveModel::UnknownAttributeError.new(@model_type.name, api_attribute)
+      end
+
+      mappings[api_attribute]
+    end
+
+    def api_attribute_names
+      api_type.attribute_names
+    end
+  end
+end

data/lib/pack_api/models/mapping/api_to_model_attributes_transformer.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+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 })
+      end
+      result
+    end
+
+    private
+
+    def model_value(api_attribute, api_value)
+      transform_value(api_attribute, api_value)
+    end
+  end
+end

data/lib/pack_api/models/mapping/attribute_hash_transformer.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module PackAPI::Mapping
+  ###
+  # Specialized attribute transformer converting attribute Hashes
+  #
+  # Does not work with models (only Hashes)
+  # Does not convert values
+  # 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 :
+        api_attributes_to_model_attributes
+    end
+
+    protected
+
+    def api_attributes_to_model_attributes
+      attribute_names = NormalizedAPIAttribute.new(api_attribute_names)
+      result = {}
+      data_source.each_key do |api_attribute|
+        normalized_api_attribute = attribute_names.normalize(api_attribute)
+        next unless mappings.key?(normalized_api_attribute)
+
+        model_attribute = model_attribute(normalized_api_attribute)
+        result[model_attribute] = data_source[api_attribute]
+      end
+      result
+    end
+
+    def model_attributes_to_api_attributes
+      reversed_mappings = mappings.invert
+      result = {}
+      data_source.each_key do |model_attribute|
+        next unless reversed_mappings.key?(model_attribute)
+
+        api_attribute = reversed_mappings[model_attribute]
+        result[api_attribute] = data_source[model_attribute]
+      end
+      result
+    end
+  end
+end