pack_api 1.0.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 97d36561d79762a67e842fc092ff22d1d66de8c230e1abcb6adff3bedc86edf7
-  data.tar.gz: e4145510ed3cb11d94340c8b48d21dd454037dd8906ac00004f5bbbdc0b43d55
+  metadata.gz: f48730065ece9a8f8e18749b49d15d4f312c997148e86447f09ba8779bd5958d
+  data.tar.gz: 5670802d6da87396caf59e961240dd2bb2d4dcc5b7bf5dafcc4ba83a196add72
 SHA512:
-  metadata.gz: e0f38e85af2248f3898ebbf99fa534133fbc5c2e10c6e8958aa7919b75174150a1ad005f4a31ed267c1674d56f02c1ad0e58c484db523f83e486c695a38e0207
-  data.tar.gz: 1c5ab5ad08af202d504550d3266c539a65836f210e434caa9330dee911b2285f6fabb2b9d4507ff3bbcab33976f67f5b8ecd226c3f31f115222acac64aba0435
+  metadata.gz: 2aaf0603ed13870e685757e6f17d8e3e98db880bb2bf0c31785940b0333eb1720cd84c5e15eb54854e6dce2dceb3d5d8780b91ef0c361fa14a498701928ee72f
+  data.tar.gz: af308e82aee39b175b46e19c2ecaafab1a7eb12bb87cd072d2fd33bce808863c003f2b9796cf82329ebd3301cfb20ffd7b4f83145be72f6546a4d707d678037e

data/CHANGELOG.md

@@ -5,35 +5,15 @@ 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]
+## [1.0.1] - 2025-11-11
 
-## [0.1.0] - 2025-11-10
+### Fixed
+
+- Improved README to clarify motivations, features, and usage examples
+- Using Zeitwerk to autoload Gem modules
+
+## [1.0.0] - 2025-11-11
 
 ### 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
+- Initial release of PackAPI gem

data/README.md

@@ -12,6 +12,18 @@ PackAPI provides a comprehensive set of tools for building robust API layers on
 - **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
 
+## Motivation
+
+Separation of concerns and information hiding within the module. 
+
+In order to separate the public interface from the (private) implementation of our subsystems (modules), we needed to 
+create an API that did not depend on our ActiveRecord models. We chose to implement this separation using value objects
+(built using dry-types, but could have been built using Ruby Data type). Beyond the API methods, the public interface
+definition is then captured in the explicit attribute list of these value objects.
+
+However, building the mapping between the domain models and the API value objects can be tedious and error-prone. We
+created this gem to provide reusable building blocks to make this mapping easier to define and maintain.
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -55,11 +67,11 @@ The mapping module provides tools for transforming data between domain models an
 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
+- `CollectionQuery` - Query ActiveRecord collections based on arguments for pagination, 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
+- Base class filter implementations for boolean, enum, numeric, and range filters
 
 ### Pagination
 
@@ -67,16 +79,15 @@ 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)
+- `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
+- `BaseType` - Base type for value objects
 - `CollectionResultMetadata` - Metadata for paginated collections
-- `Result` - Generic result type
+- `Result` - Generic result type to be returned from your API methods
 - `AggregateType` - Composite types made of attributes from other types
 - Filter definition types for various data types
 
@@ -174,7 +185,9 @@ end
 
 ```
 
-3. Implement a query endpoint using the attribute map:
+3. Implement filters. 
+
+4. 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 = [])

data/lib/pack_api/version.rb

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

data/lib/pack_api.rb

@@ -1,5 +1,4 @@
 # frozen_string_literal: true
-
 require "active_model"
 require "active_record"
 require "dry-types"
@@ -8,65 +7,63 @@ require "brotli"
 
 require_relative "types"
 require_relative "pack_api/version"
-require_relative "pack_api/config/dry_types_initializer"
 
-# Load in dependency order
 module PackAPI
-  autoload :InternalError, "pack_api/models/internal_error"
-  autoload :ValuesInBatches, "pack_api/models/values_in_batches"
-  autoload :ValuesInBackgroundBatches, "pack_api/models/values_in_background_batches"
+  autoload :InternalError, "pack_api/internal_error"
+  autoload :ValuesInBatches, "pack_api/values_in_batches"
+  autoload :ValuesInBackgroundBatches, "pack_api/values_in_background_batches"
 
   module Mapping
-    autoload :AbstractTransformer, "pack_api/models/mapping/abstract_transformer"
-    autoload :AttributeHashTransformer, "pack_api/models/mapping/attribute_hash_transformer"
-    autoload :NullTransformer, "pack_api/models/mapping/null_transformer"
-    autoload :APIToModelAttributesTransformer, "pack_api/models/mapping/api_to_model_attributes_transformer"
-    autoload :ModelToAPIAttributesTransformer, "pack_api/models/mapping/model_to_api_attributes_transformer"
-    autoload :ErrorHashToAPIAttributesTransformer, "pack_api/models/mapping/error_hash_to_api_attributes_transformer"
-    autoload :NormalizedAPIAttribute, "pack_api/models/mapping/normalized_api_attribute"
-    autoload :AttributeMap, "pack_api/models/mapping/attribute_map"
-    autoload :AttributeMapRegistry, "pack_api/models/mapping/attribute_map_registry"
-    autoload :FilterMap, "pack_api/models/mapping/filter_map"
-    autoload :ValueObjectFactory, "pack_api/models/mapping/value_object_factory"
+    autoload :AbstractTransformer, "pack_api/mapping/abstract_transformer"
+    autoload :AttributeHashTransformer, "pack_api/mapping/attribute_hash_transformer"
+    autoload :NullTransformer, "pack_api/mapping/null_transformer"
+    autoload :APIToModelAttributesTransformer, "pack_api/mapping/api_to_model_attributes_transformer"
+    autoload :ModelToAPIAttributesTransformer, "pack_api/mapping/model_to_api_attributes_transformer"
+    autoload :ErrorHashToAPIAttributesTransformer, "pack_api/mapping/error_hash_to_api_attributes_transformer"
+    autoload :NormalizedAPIAttribute, "pack_api/mapping/normalized_api_attribute"
+    autoload :AttributeMap, "pack_api/mapping/attribute_map"
+    autoload :AttributeMapRegistry, "pack_api/mapping/attribute_map_registry"
+    autoload :FilterMap, "pack_api/mapping/filter_map"
+    autoload :ValueObjectFactory, "pack_api/mapping/value_object_factory"
   end
 
   module Pagination
-    autoload :OpaqueTokenV2, "pack_api/models/pagination/opaque_token_v2"
-    autoload :PaginatorCursor, "pack_api/models/pagination/paginator_cursor"
-    autoload :Paginator, "pack_api/models/pagination/paginator"
-    autoload :PaginatorBuilder, "pack_api/models/pagination/paginator_builder"
-    autoload :SnapshotPaginator, "pack_api/models/pagination/snapshot_paginator"
+    autoload :OpaqueTokenV2, "pack_api/pagination/opaque_token_v2"
+    autoload :PaginatorCursor, "pack_api/pagination/paginator_cursor"
+    autoload :Paginator, "pack_api/pagination/paginator"
+    autoload :PaginatorBuilder, "pack_api/pagination/paginator_builder"
+    autoload :SnapshotPaginator, "pack_api/pagination/snapshot_paginator"
   end
 
   module Querying
-    autoload :AbstractFilter, "pack_api/models/querying/abstract_filter"
-    autoload :AbstractBooleanFilter, "pack_api/models/querying/abstract_boolean_filter"
-    autoload :AbstractEnumFilter, "pack_api/models/querying/abstract_enum_filter"
-    autoload :AbstractNumericFilter, "pack_api/models/querying/abstract_numeric_filter"
-    autoload :AbstractRangeFilter, "pack_api/models/querying/abstract_range_filter"
-    autoload :DefaultFilter, "pack_api/models/querying/default_filter"
-    autoload :DiscoverableFilter, "pack_api/models/querying/discoverable_filter"
-    autoload :DynamicEnumFilter, "pack_api/models/querying/dynamic_enum_filter"
-    autoload :AttributeFilter, "pack_api/models/querying/attribute_filter"
-    autoload :AttributeFilterFactory, "pack_api/models/querying/attribute_filter_factory"
-    autoload :FilterFactory, "pack_api/models/querying/filter_factory"
-    autoload :ComposableQuery, "pack_api/models/querying/composable_query"
-    autoload :CollectionQuery, "pack_api/models/querying/collection_query"
-    autoload :SortHash, "pack_api/models/querying/sort_hash"
+    autoload :AbstractFilter, "pack_api/querying/abstract_filter"
+    autoload :AbstractBooleanFilter, "pack_api/querying/abstract_boolean_filter"
+    autoload :AbstractEnumFilter, "pack_api/querying/abstract_enum_filter"
+    autoload :AbstractNumericFilter, "pack_api/querying/abstract_numeric_filter"
+    autoload :AbstractRangeFilter, "pack_api/querying/abstract_range_filter"
+    autoload :DefaultFilter, "pack_api/querying/default_filter"
+    autoload :DiscoverableFilter, "pack_api/querying/discoverable_filter"
+    autoload :DynamicEnumFilter, "pack_api/querying/dynamic_enum_filter"
+    autoload :AttributeFilter, "pack_api/querying/attribute_filter"
+    autoload :AttributeFilterFactory, "pack_api/querying/attribute_filter_factory"
+    autoload :FilterFactory, "pack_api/querying/filter_factory"
+    autoload :ComposableQuery, "pack_api/querying/composable_query"
+    autoload :CollectionQuery, "pack_api/querying/collection_query"
+    autoload :SortHash, "pack_api/querying/sort_hash"
   end
 
   module Types
-    autoload :BaseType, "pack_api/models/types/base_type"
-    autoload :AggregateType, "pack_api/models/types/aggregate_type"
-    autoload :GloballyIdentifiable, "pack_api/models/types/globally_identifiable"
-    autoload :Result, "pack_api/models/types/result"
-    autoload :CollectionResultMetadata, "pack_api/models/types/collection_result_metadata"
-    autoload :FilterOption, "pack_api/models/types/filter_option"
-    autoload :SimpleFilterDefinition, "pack_api/models/types/simple_filter_definition"
-    autoload :BooleanFilterDefinition, "pack_api/models/types/boolean_filter_definition"
-    autoload :EnumFilterDefinition, "pack_api/models/types/enum_filter_definition"
-    autoload :NumericFilterDefinition, "pack_api/models/types/numeric_filter_definition"
-    autoload :RangeFilterDefinition, "pack_api/models/types/range_filter_definition"
-    autoload :CustomFilterDefinition, "pack_api/models/types/custom_filter_definition"
+    autoload :BaseType, "pack_api/types/base_type"
+    autoload :AggregateType, "pack_api/types/aggregate_type"
+    autoload :GloballyIdentifiable, "pack_api/types/globally_identifiable"
+    autoload :Result, "pack_api/types/result"
+    autoload :CollectionResultMetadata, "pack_api/types/collection_result_metadata"
+    autoload :FilterOption, "pack_api/types/filter_option"
+    autoload :SimpleFilterDefinition, "pack_api/types/simple_filter_definition"
+    autoload :BooleanFilterDefinition, "pack_api/types/boolean_filter_definition"
+    autoload :EnumFilterDefinition, "pack_api/types/enum_filter_definition"
+    autoload :NumericFilterDefinition, "pack_api/types/numeric_filter_definition"
+    autoload :RangeFilterDefinition, "pack_api/types/range_filter_definition"
+    autoload :CustomFilterDefinition, "pack_api/types/custom_filter_definition"
   end
-end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pack_api
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.0.1
 platform: ruby
 authors:
 - Flytedesk
@@ -185,13 +185,10 @@ dependencies:
     - - "<"
       - !ruby/object:Gem::Version
         version: '9.0'
-description: |
-  Building blocks used to implement an API around a domain pack. Includes:
-  - elements for passing data out of the API
-  - elements for describing the filters supported by query endpoints in the API
-  - elements for building the mapping between domain models and API models
-  - elements for building the query endpoints themselves, based on user inputs (sort, filter, pagination)
-  - elements for retrieving multiple pages of data from other query endpoints
+description: "Building blocks used to implement an API around a domain pack. Includes
+  tools for data transformation, \ndiscoverable filters, building ActiveRecord queries
+  from API arguments, breaking query results across pages, and\nfetching data from
+  API endpoints.\n"
 email:
 - dev@flytedesk.com
 executables: []
@@ -202,52 +199,51 @@ files:
 - LICENSE.txt
 - README.md
 - lib/pack_api.rb
-- lib/pack_api/config/dry_types_initializer.rb
-- lib/pack_api/models/internal_error.rb
-- lib/pack_api/models/mapping/abstract_transformer.rb
-- lib/pack_api/models/mapping/api_to_model_attributes_transformer.rb
-- lib/pack_api/models/mapping/attribute_hash_transformer.rb
-- lib/pack_api/models/mapping/attribute_map.rb
-- lib/pack_api/models/mapping/attribute_map_registry.rb
-- lib/pack_api/models/mapping/error_hash_to_api_attributes_transformer.rb
-- lib/pack_api/models/mapping/filter_map.rb
-- lib/pack_api/models/mapping/model_to_api_attributes_transformer.rb
-- lib/pack_api/models/mapping/normalized_api_attribute.rb
-- lib/pack_api/models/mapping/null_transformer.rb
-- lib/pack_api/models/mapping/value_object_factory.rb
-- lib/pack_api/models/pagination/opaque_token_v2.rb
-- lib/pack_api/models/pagination/paginator.rb
-- lib/pack_api/models/pagination/paginator_builder.rb
-- lib/pack_api/models/pagination/paginator_cursor.rb
-- lib/pack_api/models/pagination/snapshot_paginator.rb
-- lib/pack_api/models/querying/abstract_boolean_filter.rb
-- lib/pack_api/models/querying/abstract_enum_filter.rb
-- lib/pack_api/models/querying/abstract_filter.rb
-- lib/pack_api/models/querying/abstract_numeric_filter.rb
-- lib/pack_api/models/querying/abstract_range_filter.rb
-- lib/pack_api/models/querying/attribute_filter.rb
-- lib/pack_api/models/querying/attribute_filter_factory.rb
-- lib/pack_api/models/querying/collection_query.rb
-- lib/pack_api/models/querying/composable_query.rb
-- lib/pack_api/models/querying/default_filter.rb
-- lib/pack_api/models/querying/discoverable_filter.rb
-- lib/pack_api/models/querying/dynamic_enum_filter.rb
-- lib/pack_api/models/querying/filter_factory.rb
-- lib/pack_api/models/querying/sort_hash.rb
-- lib/pack_api/models/types/aggregate_type.rb
-- lib/pack_api/models/types/base_type.rb
-- lib/pack_api/models/types/boolean_filter_definition.rb
-- lib/pack_api/models/types/collection_result_metadata.rb
-- lib/pack_api/models/types/custom_filter_definition.rb
-- lib/pack_api/models/types/enum_filter_definition.rb
-- lib/pack_api/models/types/filter_option.rb
-- lib/pack_api/models/types/globally_identifiable.rb
-- lib/pack_api/models/types/numeric_filter_definition.rb
-- lib/pack_api/models/types/range_filter_definition.rb
-- lib/pack_api/models/types/result.rb
-- lib/pack_api/models/types/simple_filter_definition.rb
-- lib/pack_api/models/values_in_background_batches.rb
-- lib/pack_api/models/values_in_batches.rb
+- lib/pack_api/internal_error.rb
+- lib/pack_api/mapping/abstract_transformer.rb
+- lib/pack_api/mapping/api_to_model_attributes_transformer.rb
+- lib/pack_api/mapping/attribute_hash_transformer.rb
+- lib/pack_api/mapping/attribute_map.rb
+- lib/pack_api/mapping/attribute_map_registry.rb
+- lib/pack_api/mapping/error_hash_to_api_attributes_transformer.rb
+- lib/pack_api/mapping/filter_map.rb
+- lib/pack_api/mapping/model_to_api_attributes_transformer.rb
+- lib/pack_api/mapping/normalized_api_attribute.rb
+- lib/pack_api/mapping/null_transformer.rb
+- lib/pack_api/mapping/value_object_factory.rb
+- lib/pack_api/pagination/opaque_token_v2.rb
+- lib/pack_api/pagination/paginator.rb
+- lib/pack_api/pagination/paginator_builder.rb
+- lib/pack_api/pagination/paginator_cursor.rb
+- lib/pack_api/pagination/snapshot_paginator.rb
+- lib/pack_api/querying/abstract_boolean_filter.rb
+- lib/pack_api/querying/abstract_enum_filter.rb
+- lib/pack_api/querying/abstract_filter.rb
+- lib/pack_api/querying/abstract_numeric_filter.rb
+- lib/pack_api/querying/abstract_range_filter.rb
+- lib/pack_api/querying/attribute_filter.rb
+- lib/pack_api/querying/attribute_filter_factory.rb
+- lib/pack_api/querying/collection_query.rb
+- lib/pack_api/querying/composable_query.rb
+- lib/pack_api/querying/default_filter.rb
+- lib/pack_api/querying/discoverable_filter.rb
+- 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/types/aggregate_type.rb
+- lib/pack_api/types/base_type.rb
+- lib/pack_api/types/boolean_filter_definition.rb
+- lib/pack_api/types/collection_result_metadata.rb
+- lib/pack_api/types/custom_filter_definition.rb
+- lib/pack_api/types/enum_filter_definition.rb
+- lib/pack_api/types/filter_option.rb
+- lib/pack_api/types/globally_identifiable.rb
+- lib/pack_api/types/numeric_filter_definition.rb
+- lib/pack_api/types/range_filter_definition.rb
+- lib/pack_api/types/result.rb
+- lib/pack_api/types/simple_filter_definition.rb
+- lib/pack_api/values_in_background_batches.rb
+- lib/pack_api/values_in_batches.rb
 - lib/pack_api/version.rb
 - lib/types.rb
 homepage: https://github.com/flytedesk/pack_api

data/lib/pack_api/config/dry_types_initializer.rb

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