pack_api 1.0.0

data/lib/pack_api/models/querying/attribute_filter.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module PackAPI::Querying
+  class AttributeFilter < DiscoverableFilter
+    attr_accessor :value
+
+    def self.type
+      :attribute
+    end
+
+    def self.data_type
+      raise NotImplementedError
+    end
+
+    def self.definition(**)
+      PackAPI::Types::SimpleFilterDefinition.new(name: filter_name, data_type:)
+    end
+
+    def initialize(value)
+      super()
+      @value = value
+    end
+
+    def present?
+      !value.nil?
+    end
+
+    def to_h
+      { filter_name => value }
+    end
+
+    def apply_to(query)
+      query.add(query.build.where(to_h))
+    end
+  end
+end

data/lib/pack_api/models/querying/attribute_filter_factory.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module PackAPI::Querying
+  class AttributeFilterFactory
+    include Enumerable
+
+    DATA_TYPE_REGEXP = /\S+$/
+    private_constant :DATA_TYPE_REGEXP
+
+    def self.attribute_filter_cache
+      @attribute_filter_cache ||= Concurrent::Map.new
+    end
+
+    attr_reader :attribute_map_class
+
+    def initialize(attribute_map_class)
+      @attribute_map_class = attribute_map_class
+    end
+
+    def from_api_type
+      filterable_attributes.each do |attribute_name, attribute_type|
+        yield define_filter(attribute_name, attribute_type)
+      end
+    end
+
+    private
+
+    def filterable_attributes
+      @filterable_attributes ||= attribute_map_class.api_type.filterable_attributes
+    end
+
+    def model_attribute_names
+      return @model_attribute_names if defined?(@model_attribute_names)
+
+      names = {}
+      filterable_attributes.each_key { |name| names[name] = name }
+      @model_attribute_names = attribute_map_class.model_attribute_keys(names).invert
+    end
+
+    def data_type(attribute_type)
+      return 'Bool' if attribute_type.name.end_with?('TrueClass | FalseClass')
+
+      attribute_type.name.include?(' | ') ?
+        attribute_type.name[DATA_TYPE_REGEXP] :
+        attribute_type.name
+    end
+
+    def define_filter(attribute_name, attribute_type)
+      filter_name = model_attribute_names[attribute_name]
+      data_type = data_type(attribute_type)
+      self.class
+          .attribute_filter_cache
+          .compute_if_absent(filter_name) { Concurrent::Map.new }
+          .compute_if_absent(data_type) do
+        Class.new(AttributeFilter) do
+          define_singleton_method(:filter_name) { filter_name }
+          define_singleton_method(:data_type) { data_type }
+        end
+      end
+    end
+  end
+end

data/lib/pack_api/models/querying/collection_query.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module PackAPI::Querying
+  ###
+  # This is a generic query that can be used to query any collection of ActiveRecord models and then
+  # expose the results as a collection of value objects.
+  #
+  # It allows paginated queries, as well as record iteration
+  # queries (using snapshot cursors). In order to enable record iteration mode, the query must be called with
+  # both a snapshot cursor and a primary key filter.
+  class CollectionQuery
+    attr_accessor :collection, :collection_key, :filter_factory, :default_sort, :paginator, :sort, :results
+
+    ###
+    # Create the query object.
+    #
+    # @ param [ActiveRecord::Relation] collection The collection to query
+    # @ param [Object] value_object_factory The factory to use to convert model objects to value objects
+    # @ param [String|Symbol|Hash|Arel] default_sort The default sort to use if none is specified in the query
+    # @ param [String|Symbol] collection_key Unique and indexed key to use for the collection.
+    #  Used for tie-breaker sort criteria and drives the record id lookup when in record iteration mode.
+    def initialize(collection:, collection_key: nil, default_sort: nil)
+      @collection = collection
+      @collection_key = (collection_key || collection.primary_key).to_sym
+      @default_sort = default_sort
+      @filter_factory = FilterFactory.new
+      @filter_factory.use_default_filter = true
+    end
+
+    ###
+    # Perform the query.
+    #
+    # @param [String] cursor A pagination cursor referencing a page of records in a recordset
+    # @param [Integer|Symbol] per_page A count of how many items to include on each page, or :all to skip pagination
+    # @param [String|Symbol|Hash|Arel] sort ActiveRecord `order` arguments.
+    # @param [Hash] search Attribute/value pairs that define the bounds of the recordset using wildcard matching (attribute LIKE %value%)
+    # @param [Hash] filters the keys are names of filters, the values are arguments to the filters
+    def call(cursor: nil, per_page: nil, sort: nil, search: nil, filters: {})
+      record_id = filters.delete(collection_key) if cursor.present? && filters[collection_key].present?
+      build_paginator(cursor, filters, per_page, search, sort)
+      build_active_record_query(record_id)
+    end
+
+    def to_sql
+      @query.to_sql
+    end
+
+    def reset
+      @results = nil
+      @query = nil
+      @paginator = nil
+      @sort = nil
+      @current_page_snapshot_cursor = nil
+    end
+
+    def current_page_snapshot_cursor
+      @current_page_snapshot_cursor ||= PackAPI::Pagination::SnapshotPaginator.cursor_for_results(results,
+                                                                                                  table_name: collection.klass.table_name,
+                                                                                                  collection_key:)
+    end
+
+    private
+
+    def build_active_record_query(record_id)
+      @query = collection
+      if paginator.query&.fetch(:search, nil).present?
+        apply_search(search: paginator.query[:search])
+      end
+      if paginator.query&.fetch(:filters, nil).present?
+        apply_filters(filters: paginator.query[:filters])
+      end
+
+      @sort = paginator.sort
+      paginator.total_items = @query.count
+      @query = @query.order(paginator.sort)
+                     .offset(paginator.offset)
+                     .limit(paginator.limit)
+
+      if PackAPI::Pagination::SnapshotPaginator.generated?(paginator)
+        snapshot_paginator = PackAPI::Pagination::SnapshotPaginator.new(paginator)
+        @query = snapshot_paginator.apply_to(@query, record_id:)
+        @results = snapshot_paginator.results
+        @current_page_snapshot_cursor = snapshot_paginator.cursor
+      end
+
+      @results ||= @query.to_a
+    end
+
+    def build_paginator(cursor, filters, per_page, search, sort)
+      @paginator = PackAPI::Pagination::PaginatorBuilder.build do |builder|
+        cursor.present? ?
+          builder.set_cursor(cursor:) :
+          builder.set_params(sort: stable_sort(default_sort)) # set a default sort for a new query
+
+        builder.set_params(sort: stable_sort(sort.presence)) if sort.present?
+        builder.set_params(query: { filters: }) if filters.present?
+        builder.set_params(query: { search: }) if search.present?
+        builder.set_params(per_page:) if per_page.present?
+      end
+    end
+
+    def apply_search(search:)
+      search.keys.each_with_index do |column, index|
+        value = search[column]
+        @query = index.positive? ?
+                   @query.or(collection.where("LOWER(#{column}) LIKE LOWER(?)", "%#{value}%")) :
+                   @query.where("LOWER(#{column}) LIKE LOWER(?)", "%#{value}%")
+      end
+    end
+
+    def apply_filters(filters:)
+      filtered_query = ComposableQuery.new(@query)
+      filter_factory.create_filters(filters).each { |filter| filter.apply_to(filtered_query) }
+      @query = filtered_query.build
+    end
+
+    def stable_sort(sort)
+      return sort if sort.is_a?(Arel::Nodes::SqlLiteral)
+
+      SortHash.new(sort).tap do |sort_hash|
+        sort_hash[collection_key] = :asc unless sort_hash.key?(collection_key)
+      end
+    end
+  end
+end

data/lib/pack_api/models/querying/composable_query.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module PackAPI::Querying
+  class ComposableQuery
+    def initialize(initial_query)
+      @query = initial_query
+    end
+
+    def add(query_clause)
+      @query = @query.merge(query_clause)
+      self
+    end
+
+    def build
+      @query
+    end
+
+    def to_sql
+      @query.to_sql
+    end
+  end
+end

data/lib/pack_api/models/querying/default_filter.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module PackAPI::Querying
+  class DefaultFilter < AbstractFilter
+    attr_accessor :arguments
+
+    def initialize(arguments)
+      super()
+      @arguments = arguments
+    end
+
+    def present?
+      arguments.present?
+    end
+
+    def apply_to(query)
+      query.add(query.build.where(arguments))
+    end
+  end
+end

data/lib/pack_api/models/querying/discoverable_filter.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module PackAPI::Querying
+  ##
+  # This class is the base class for all discoverable filters, which can produce a definition that specifies usage.
+  class DiscoverableFilter < AbstractFilter
+    include ActiveModel::Validations
+
+    def filter_name
+      self.class.filter_name
+    end
+
+    def self.filter_name
+      raise NotImplementedError
+    end
+
+    def type
+      self.class.type
+    end
+
+    def self.type
+      raise NotImplementedError
+    end
+
+    def to_h
+      raise NotImplementedError
+    end
+
+    def self.definition(**)
+      raise NotImplementedError
+    end
+  end
+end

data/lib/pack_api/models/querying/dynamic_enum_filter.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module PackAPI::Querying
+  module DynamicEnumFilter
+    FROZEN_EMPTY_ARRAY = [].freeze
+
+    extend ActiveSupport::Concern
+    class_methods do
+      def type = :dynamic_enum
+
+      def can_exclude? = false
+
+      def search_for_options(relation:, search:) = raise NotImplementedError
+
+      private
+
+      def filter_options(**) = FROZEN_EMPTY_ARRAY
+    end
+  end
+end

data/lib/pack_api/models/querying/filter_factory.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module PackAPI::Querying
+  class FilterFactory
+    attr_accessor :filter_classes, :use_default_filter
+
+    def initialize
+      @filter_classes = Hash.new { |_hash, key| raise NotImplementedError, "Unsupported filter #{key}" }
+    end
+
+    def register_filter(name:, klass:)
+      filter_classes[name] = klass
+    end
+
+    def create_filters(filter_hash)
+      filter_objects(filter_hash).select(&:present?)
+    end
+
+    private
+
+    def filter_objects(filter_options)
+      if filter_options.is_a?(Hash)
+        filter_objects_from_hash(filter_options)
+      elsif use_default_filter
+        [DefaultFilter.new(filter_options)]
+      else
+        raise ArgumentError, "Unsupported filter configuration: #{filter_options}"
+      end
+
+    end
+
+    def filter_objects_from_hash(filter_options)
+      filter_options.deep_symbolize_keys.map(&method(:filter_object_by_name))
+    end
+
+    def filter_object_by_name(filter_name, options)
+      if filter_classes.key?(filter_name)
+        registered_filter_object(filter_name, options)
+      elsif use_default_filter
+        DefaultFilter.new(filter_name => options)
+      else
+        raise NotImplementedError, "Unsupported filter: #{filter_name}"
+      end
+    end
+
+    def registered_filter_object(filter_name, options)
+      options.is_a?(Hash) ?
+        filter_classes[filter_name].new(**options) :
+        filter_classes[filter_name].new(options)
+    rescue ArgumentError => e
+      raise ArgumentError, "Invalid filter options for #{filter_name}: #{options} (#{e})"
+    end
+  end
+end

data/lib/pack_api/models/querying/sort_hash.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module PackAPI::Querying
+  class SortHash < Hash
+
+    ###
+    # Normalize a hash object to be used to control the sorting of a collection of objects
+    #
+    # @param [Hash|Symbol|String] sort_arg When provided with a string or a symbol, the sort hash will treat that
+    # as the name of the attribute to sort by, and will sort in ascending order. When provided with a hash, the keys
+    # of the hash should be the names of the attributes to sort by, and the values should be either `:asc` or `:desc`
+    def initialize(sort_arg)
+      super()
+      case sort_arg
+      when Arel::Nodes::SqlLiteral, nil
+        hash_entries = []
+      when Hash
+        hash_entries = sort_arg.to_a
+      when Symbol
+        hash_entries = [[sort_arg, :asc]]
+      when String
+        hash_entries = sort_arg.split(',').map do |sort_term|
+          sort_term_parts = sort_term.split
+          [sort_term_parts[0].to_sym, sort_term_parts[1]&.to_sym || :asc]
+        end
+      end
+
+      hash_entries.each do |key, value|
+        next unless key.present?
+
+        self[key] = value
+      end
+      deep_transform_values! { it.downcase.to_sym }
+    end
+  end
+end

data/lib/pack_api/models/types/aggregate_type.rb

@@ -0,0 +1,202 @@
+# frozen_string_literal: true
+
+module PackAPI::Types
+  ###
+  # Define a type that blends attributes from multiple resources into a single data structure.
+  # For each kind of input resource, pass a block to the `combine_attributes` method, wherein are enumerated the
+  # attributes in the output data structure which originate from that input resource.
+  #
+  # Example:
+  #
+  # class MyAggregateType < PackAPI::Types::AggregateType
+  #   combine_attributes from: :resource_one do
+  #     attribute :id, Types::String
+  #     attribute :name, Types::String
+  #   end
+  #   combine_attributes from: :resource_two do
+  #     attribute :description, Types::String
+  #     attribute :created_at, Types::Time
+  #   end
+  # end
+  #
+  # This will create a type with attributes `id`, `name`, `description`, and `created_at`, where:
+  #   - `id` and `name` come from `resource_one`
+  #   - `description` and `created_at` come from `resource_two`
+  #
+  # For each input resource, helper methods must be defined to enable the CRUD operations:
+  #   - query_<resource>s(**params) - returns a hash of resources, indexed by their IDs
+  #   - get_<resource>(id) - returns a single resource, identified by its ID
+  #   - create_<resource>(params) - creates a new resource and returns it
+  #   - update_<resource>(id, params) - updates an existing resource and returns it
+  #   - delete_<resource>(id)
+  #
+  # For example, for the above example, you would need to define:
+  #   - query_resource_ones
+  #   - get_resource_one
+  #   - create_resource_one
+  #   - update_resource_one
+  #   - delete_resource_one
+  #
+  # @note: There are 2 kinds of resources:
+  #   - primary resources
+  #   - secondary resources
+  #
+  # The first resource drawn from via `combine_attributes` is considered the primary resource.
+  class AggregateType < BaseType
+    @attribute_sources = {}
+    @attribute_sources = {}
+    @next_attribute_list = nil
+
+    class << self
+      def inherited(subclass)
+        subclass.instance_variable_set(:@attribute_sources, {})
+        subclass.instance_variable_set(:@next_attribute_list, nil)
+        super
+      end
+
+      def attribute(name, type = Undefined, &block)
+        super
+        @next_attribute_list << name if @next_attribute_list
+      end
+
+      def combine_attributes(from:, &block)
+        @next_attribute_list = []
+        block.call
+        @attribute_sources[from] = @next_attribute_list
+        @next_attribute_list = nil
+      end
+
+      def query(**params)
+        attribute_blender.query(**params).map { new(it) }
+      end
+
+      def get(id)
+        new(attribute_blender.get(id))
+      end
+
+      def update(id, params)
+        new(attribute_blender.update(id, params))
+      end
+
+      def create(params)
+        new(attribute_blender.create(params))
+      end
+
+      def delete(id)
+        attribute_blender.delete(id)
+      end
+
+      private
+
+      def attribute_blender
+        @attribute_blender ||= AttributeBlender.new(@attribute_sources, self)
+      end
+    end
+
+    class AttributeBlender
+      attr_reader :attribute_sources, :combined_attributes, :aggregate_type
+
+      def initialize(attribute_sources, aggregate_type)
+        @attribute_sources = attribute_sources
+        @aggregate_type = aggregate_type
+        @combined_attributes = {}
+      end
+
+      def query(**params)
+        primary_source, primary_resource_attributes = attribute_sources.first
+        resource_method = :"query_#{primary_source}s"
+        primary_resource_results = aggregate_type.send(resource_method, **params)
+        combined_attributes = primary_resource_results.transform_values do |primary_resource|
+          primary_resource.to_h.slice(*primary_resource_attributes)
+        end
+        primary_result_ids = primary_resource_results.keys
+        attribute_sources.drop(1).each do |resource_name, resource_attributes|
+          resource_method = :"query_#{resource_name}s"
+          aggregate_type.send(resource_method, id: primary_result_ids)
+                        .each do |primary_resource_id, secondary_resource|
+            secondary_attributes = secondary_resource.to_h.slice(*resource_attributes)
+            combined_attributes[primary_resource_id].merge!(secondary_attributes)
+          end
+        end
+
+        combined_attributes.values
+      end
+
+      def get(id)
+        attribute_sources.each do |resource_name, attribute_names|
+          resource_method = :"get_#{resource_name}"
+          resource = aggregate_type.send(resource_method, id)
+          combined_attributes.merge!(resource.to_h.slice(*attribute_names))
+        end
+        combined_attributes
+      end
+
+      def update(id, params)
+        initial_state = get(id)
+        @combined_attributes = initial_state.to_h
+        attribute_sources_updated = []
+        attribute_sources.each do |resource_name, resource_attributes|
+          resource_params = resource_params(params, resource_attributes)
+          next unless resource_params.any?
+
+          resource_method = :"update_#{resource_name}"
+          resource = aggregate_type.send(resource_method, id, resource_params)
+          combined_attributes.merge!(resource.to_h.slice(*resource_attributes))
+        end
+        combined_attributes
+      rescue PackAPI::InternalError
+        rollback_update(attribute_sources_updated, id, initial_state)
+        raise
+      end
+
+      def create(params)
+        attribute_sources_created = []
+        primary_resource_id = nil
+        attribute_sources.each do |resource_name, resource_attributes|
+          resource_method = :"create_#{resource_name}"
+          args = [resource_params(params, resource_attributes)]
+          args << primary_resource_id if primary_resource_id
+          resource = aggregate_type.send(resource_method, *args)
+          primary_resource_id ||= resource.id
+          combined_attributes.merge!(resource.to_h.slice(*resource_attributes))
+        end
+        combined_attributes
+      rescue PackAPI::InternalError
+        rollback_create(attribute_sources_created, primary_resource_id)
+        raise
+      end
+
+      def delete(id)
+        attribute_sources.each_key do |resource_name|
+          resource_method = :"delete_#{resource_name}"
+          aggregate_type.send(resource_method, id)
+        rescue PackAPI::InternalError => e
+          Rails.logger.error("Failed to delete #{resource_name} with id: #{id}")
+          Rails.logger.error(e.backtrace.join("\n"))
+        end
+      end
+
+      private
+
+      def resource_params(params, resource_attributes)
+        normalizer = PackAPI::Mapping::NormalizedAPIAttribute.new(resource_attributes)
+        params.filter { |key| resource_attributes.include?(normalizer.normalize(key)) }
+      end
+
+      def rollback_update(attribute_sources_updated, id, initial_state)
+        attribute_sources_updated.reverse_each do |resource_name|
+          resource_method = :"update_#{resource_name}"
+          attribute_names = attribute_sources[resource_name]
+          aggregate_type.send(resource_method, id, initial_state.to_h.slice(*attribute_names))
+        end
+      end
+
+      def rollback_create(attribute_sources_created, primary_resource_id)
+        attribute_sources_created.reverse_each do |resource_name|
+          resource_method = :"delete_#{resource_name}"
+          aggregate_type.send(resource_method, primary_resource_id)
+        end
+      end
+    end
+  end
+end

data/lib/pack_api/models/types/base_type.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module PackAPI::Types
+  class BaseType < Dry::Struct
+    @optional_attributes = []
+    @filterable_attributes = {}
+
+    def self.inherited(subclass)
+      subclass.instance_variable_set(:@optional_attributes, [])
+      super
+    end
+
+    def self.optional_attribute(name, type = Undefined, &block)
+      attribute?(name, type.optional, &block)
+      @optional_attributes << name
+    end
+
+    def self.optional_attributes
+      @optional_attributes.to_a
+    end
+
+    def to_data(**other_attributes)
+      merged_attributes = to_h.merge(other_attributes)
+      Data.define(*merged_attributes.keys).new(**merged_attributes)
+    end
+
+    def merge(**other_attributes)
+      self.class.new(to_h.merge(other_attributes))
+    end
+
+    ##
+    # This method returns a mapping of attribute names to `Dry::Type::*` objects that describe the attributes that have
+    # been designated as filterable, as in the following example:
+    #   attribute :id, Types::String.meta(filterable: true)
+    #
+    # NOTE: According to the documentation, `Dry::Types::Schema::Key` is part of a private API, but we haven't found a
+    # better way to access an attribute's metadata or type:
+    # - https://www.rubydoc.info/github/dry-rb/dry-types/main/Dry/Types/Schema/Key
+    # - https://discourse.dry-rb.org/t/how-to-access-meta-fields-in-structs/989
+    def self.filterable_attributes
+      schema.keys.each_with_object({}) do |schema_key, result|
+        result[schema_key.name] = schema_key.type if schema_key.meta[:filterable]
+      end
+    end
+  end
+end

data/lib/pack_api/models/types/boolean_filter_definition.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module PackAPI::Types
+  class BooleanFilterDefinition < BaseType
+    attribute :name, Types::Symbol
+    attribute :type, Types::Symbol.default(:tri_state_boolean)
+    attribute :options, Types::Array.of(FilterOption)
+  end
+end