apiwork 0.0.0.pre → 0.1.1

data/lib/apiwork/adapter/serializer/resource/base.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module Adapter
+    module Serializer
+      module Resource
+        # @api public
+        # Base class for resource serializers.
+        #
+        # Resource serializers handle serialization of records and collections
+        # and define resource types at the contract level.
+        #
+        # @example
+        #   class MyResourceSerializer < Serializer::Resource::Base
+        #     contract_builder Builder::Contract
+        #
+        #     def serialize(resource, context:, serialize_options:)
+        #       representation_class.serialize(resource, context:)
+        #     end
+        #   end
+        class Base
+          class << self
+            def serialize(representation_class, resource, context:, serialize_options:)
+              new(representation_class).serialize(resource, context:, serialize_options:)
+            end
+
+            # @api public
+            # The data type for this serializer.
+            #
+            # @param block [Proc, nil] (nil)
+            #   Block that receives representation_class and returns type name.
+            # @return [Proc, nil]
+            def data_type(&block)
+              @data_type = block if block
+              @data_type
+            end
+
+            # @api public
+            # The contract builder for this serializer.
+            #
+            # @param klass [Class<Builder::Contract::Base>, nil] (nil)
+            #   The builder class.
+            # @return [Class<Builder::Contract::Base>, nil]
+            def contract_builder(klass = nil)
+              @contract_builder = klass if klass
+              @contract_builder
+            end
+          end
+
+          # @api public
+          # The representation class for this serializer.
+          #
+          # @return [Class<Representation::Base>]
+          attr_reader :representation_class
+
+          def initialize(representation_class)
+            @representation_class = representation_class
+          end
+
+          def contract_types(contract_class)
+            builder_class = self.class.contract_builder
+            return unless builder_class
+
+            builder_class.new(contract_class, representation_class).build
+          end
+
+          # @api public
+          # Serializes a resource.
+          #
+          # @param resource [Object]
+          #   The resource to serialize.
+          # @param context [Hash]
+          #   The serialization context.
+          # @param serialize_options [Hash]
+          #   The options (e.g., include).
+          # @return [Hash]
+          def serialize(resource, context:, serialize_options:)
+            raise NotImplementedError
+          end
+        end
+      end
+    end
+  end
+end

data/lib/apiwork/adapter/serializer/resource/default/contract_builder.rb

@@ -0,0 +1,209 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module Adapter
+    module Serializer
+      module Resource
+        class Default < Base
+          class ContractBuilder < Adapter::Builder::Contract::Base
+            def build
+              build_enums
+              resource_type_name
+            end
+
+            def resource_type_name
+              if sti_base_representation?
+                build_sti_response_union_type
+              else
+                register_type(representation_class.root_key.singular.to_sym) unless type?(scoped_type_name(nil))
+
+                scoped_type_name(nil)
+              end
+            end
+
+            def import_association_contract(association_representation, visited)
+              return nil if visited.include?(association_representation)
+
+              association_contract = contract_for(association_representation)
+              return nil unless association_contract
+
+              alias_name = association_representation.root_key.singular.to_sym
+              import(association_contract, as: alias_name)
+              alias_name
+            end
+
+            private
+
+            def build_enums
+              representation_class.attributes.each do |name, attribute|
+                next unless attribute.enum&.any?
+
+                enum(name, values: attribute.enum)
+              end
+            end
+
+            def register_type(type_name)
+              association_type_map = {}
+              representation_class.associations.each do |name, association|
+                association_type_map[name] = build_association_type(association)
+              end
+
+              object(
+                type_name,
+                description: representation_class.description,
+                example: representation_class.example,
+              ) do |object|
+                if representation_class.subclass?
+                  discriminator_name = representation_class.superclass.inheritance.column
+                  object.literal(discriminator_name, value: representation_class.sti_name)
+                end
+
+                representation_class.attributes.each do |name, attribute|
+                  param_options = {
+                    deprecated: attribute.deprecated?,
+                    description: attribute.description,
+                    example: attribute.example,
+                    format: attribute.format,
+                    nullable: attribute.nullable?,
+                    type: attribute.type,
+                    **(attribute.enum ? { enum: name } : {}),
+                    **(attribute.of ? { of: attribute.of } : {}),
+                  }
+
+                  element = attribute.element
+                  if element
+                    if element.type == :array
+                      param_options[:of] = element.inner
+                    else
+                      param_options[:shape] = element.shape
+                      param_options[:discriminator] = element.discriminator if element.discriminator
+                    end
+                  end
+
+                  object.param(name, **param_options)
+                end
+
+                representation_class.associations.each do |name, association|
+                  association_type = association_type_map[name]
+
+                  base_options = {
+                    deprecated: association.deprecated?,
+                    description: association.description,
+                    example: association.example,
+                    nullable: association.nullable?,
+                    optional: association.include != :always,
+                  }
+
+                  if association.singular?
+                    object.param(name, type: association_type || :object, **base_options)
+                  elsif association.collection?
+                    if association_type
+                      object.param(name, type: :array, **base_options) do |param|
+                        param.of(association_type)
+                      end
+                    else
+                      object.param(name, type: :array, **base_options)
+                    end
+                  end
+                end
+              end
+            end
+
+            def sti_base_representation?
+              inheritance = representation_class.inheritance
+              inheritance&.subclasses&.any? && inheritance.base_class == representation_class
+            end
+
+            def build_sti_union(union_type_name:, visited: Set.new)
+              representation_inheritance = representation_class.inheritance
+              return nil unless representation_inheritance.subclasses.any?
+
+              discriminator_name = representation_inheritance.column
+
+              variant_types = representation_inheritance.subclasses.filter_map do |subclass|
+                variant_type = yield(subclass)
+                { tag: subclass.sti_name, type: variant_type } if variant_type
+              end
+
+              union(union_type_name, discriminator: discriminator_name) do |union|
+                variant_types.each do |variant_type|
+                  union.variant(tag: variant_type[:tag]) do |variant|
+                    variant.reference(variant_type[:type])
+                  end
+                end
+              end
+
+              union_type_name
+            end
+
+            def build_sti_response_union_type(visited: Set.new)
+              union_type_name = representation_class.root_key.singular.to_sym
+
+              build_sti_union(union_type_name:, visited:) do |variant_representation_class|
+                variant_contract = contract_for(variant_representation_class)
+                next nil unless variant_contract
+
+                alias_name = variant_representation_class.root_key.singular.to_sym
+                import(variant_contract, as: alias_name)
+
+                alias_name
+              end
+            end
+
+            def build_association_type(association, visited: Set.new)
+              return build_polymorphic_association_type(association, visited:) if association.polymorphic?
+
+              association_info = resolve_association(association)
+              return nil unless association_info
+
+              representation_class = association_info[:representation_class]
+
+              return import_association_contract(representation_class, visited) if association_info[:sti]
+              return nil if visited.include?(representation_class)
+
+              association_contract = contract_for(representation_class)
+              return nil unless association_contract
+
+              type_name = representation_class.root_key.singular.to_sym
+              import(association_contract, as: type_name)
+              type_name
+            end
+
+            def build_polymorphic_association_type(association, visited: Set.new)
+              polymorphic = association.polymorphic
+              return nil unless polymorphic.any?
+
+              union_type_name = association.name
+
+              existing_type = type?(union_type_name)
+              return union_type_name if existing_type
+
+              union(union_type_name, discriminator: association.discriminator) do |union|
+                polymorphic.each do |polymorphic_representation_class|
+                  tag = polymorphic_representation_class.polymorphic_name
+                  alias_name = import_association_contract(polymorphic_representation_class, visited)
+                  next unless alias_name
+
+                  union.variant(tag:) do |variant|
+                    variant.reference(alias_name)
+                  end
+                end
+              end
+
+              union_type_name
+            end
+
+            def resolve_association(association)
+              return nil if association.polymorphic?
+
+              representation_class = association.representation_class
+              return nil unless representation_class
+
+              { representation_class:, sti: representation_class.inheritance&.subclasses&.any? }
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/apiwork/adapter/serializer/resource/default.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module Adapter
+    module Serializer
+      module Resource
+        # @api public
+        # Default resource serializer.
+        #
+        # Delegates serialization to the representation class using its root key as data type.
+        #
+        # @example Configuration
+        #   class MyAdapter < Adapter::Base
+        #     serializer Serializer::Resource::Default
+        #   end
+        #
+        # @example Output
+        #   {
+        #     "id": 1,
+        #     "number": "INV-001",
+        #     "customer": { "id": 5, "name": "Acme" }
+        #   }
+        class Default < Base
+          data_type { |representation_class| representation_class.root_key.singular.to_sym }
+
+          contract_builder ContractBuilder
+
+          def serialize(resource, context:, serialize_options:)
+            representation_class.serialize(
+              resource,
+              context:,
+              include: serialize_options[:include],
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/apiwork/adapter/standard/capability/filtering/api_builder.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module Adapter
+    class Standard
+      module Capability
+        class Filtering
+          class APIBuilder < Adapter::Capability::API::Base
+            def build
+              return unless scope.filterable?
+
+              scope.filter_types.each { |type| register_filter(type, nullable: false) }
+              scope.nullable_filter_types.each { |type| register_filter(type, nullable: true) }
+            end
+
+            private
+
+            def register_filter(type, nullable:)
+              type_name = type_name(type, nullable:)
+              return if type?(type_name)
+
+              operators = operators_for(type)
+              register_between(type) if operators.include?(:between)
+
+              object(type_name) do |object|
+                operators.each { |operator| add_operator(object, operator, type) }
+                object.boolean?(:null) if nullable
+              end
+            end
+
+            def add_operator(object, operator, type)
+              case operator
+              when :in
+                object.array?(:in) { |array| array.of(type) }
+              when :between
+                object.reference?(:between, to: between_type_name(type))
+              else
+                object.param(operator, type:, optional: true)
+              end
+            end
+
+            def register_between(type)
+              type_name = between_type_name(type)
+              return if type?(type_name)
+
+              object(type_name) do |object|
+                object.param(:from, type:, optional: true)
+                object.param(:to, type:, optional: true)
+              end
+            end
+
+            def operators_for(type)
+              case type
+              when :string, :binary then Constants::STRING_OPERATORS
+              when :date, :datetime, :time then Constants::DATE_OPERATORS
+              when :integer, :decimal, :number then Constants::NUMERIC_OPERATORS
+              when :uuid then Constants::UUID_OPERATORS
+              when :boolean then Constants::BOOLEAN_OPERATORS
+              else Constants::STRING_OPERATORS
+              end
+            end
+
+            def type_name(type, nullable:)
+              nullable ? [:nullable, type, :filter].join('_').to_sym : [type, :filter].join('_').to_sym
+            end
+
+            def between_type_name(type)
+              [type, :filter, :between].join('_').to_sym
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/apiwork/adapter/standard/capability/filtering/constants.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module Adapter
+    class Standard
+      module Capability
+        class Filtering < Adapter::Capability::Base
+          module Constants
+            AND = :AND
+            OR = :OR
+            NOT = :NOT
+            LOGICAL_OPERATORS = [AND, OR, NOT].freeze
+
+            EQUALITY_OPERATORS = %i[eq].freeze
+            COMPARISON_OPERATORS = %i[gt gte lt lte].freeze
+            RANGE_OPERATORS = %i[between].freeze
+            COLLECTION_OPERATORS = %i[in].freeze
+            STRING_SPECIFIC_OPERATORS = %i[contains starts_with ends_with].freeze
+            NULL_OPERATORS = %i[null].freeze
+
+            STRING_OPERATORS = (EQUALITY_OPERATORS + COLLECTION_OPERATORS + STRING_SPECIFIC_OPERATORS).freeze
+            DATE_OPERATORS = (EQUALITY_OPERATORS + COMPARISON_OPERATORS + RANGE_OPERATORS + COLLECTION_OPERATORS).freeze
+            NUMERIC_OPERATORS = (EQUALITY_OPERATORS + COMPARISON_OPERATORS + RANGE_OPERATORS + COLLECTION_OPERATORS).freeze
+            UUID_OPERATORS = (EQUALITY_OPERATORS + COLLECTION_OPERATORS).freeze
+            BOOLEAN_OPERATORS = EQUALITY_OPERATORS.freeze
+
+            NULLABLE_STRING_OPERATORS = (STRING_OPERATORS + NULL_OPERATORS).freeze
+            NULLABLE_DATE_OPERATORS = (DATE_OPERATORS + NULL_OPERATORS).freeze
+            NULLABLE_NUMERIC_OPERATORS = (NUMERIC_OPERATORS + NULL_OPERATORS).freeze
+            NULLABLE_UUID_OPERATORS = (UUID_OPERATORS + NULL_OPERATORS).freeze
+            NULLABLE_BOOLEAN_OPERATORS = (BOOLEAN_OPERATORS + NULL_OPERATORS).freeze
+          end
+        end
+      end
+    end
+  end
+end

data/lib/apiwork/adapter/standard/capability/filtering/contract_builder.rb

@@ -0,0 +1,193 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module Adapter
+    class Standard
+      module Capability
+        class Filtering
+          class ContractBuilder < Adapter::Capability::Contract::Base
+            TYPE_NAME = :filter
+            UNFILTERABLE_TYPES = %i[unknown array object union].freeze
+
+            def build
+              return unless filterable?
+
+              representation_class.attributes.each do |name, attribute|
+                next unless attribute.filterable? && attribute.enum
+
+                type_name = [name, TYPE_NAME].join('_').to_sym
+                next if type?(type_name)
+
+                build_enum_filter_union(type_name, scoped_enum_name(name))
+              end
+
+              build_polymorphic_type_filters
+              build_sti_type_filters
+
+              attributes = representation_class.attributes.filter_map do |name, attribute|
+                next unless attribute.filterable? && UNFILTERABLE_TYPES.exclude?(attribute.type)
+
+                filter_type = filter_type_for(attribute)
+                has_custom_filter = attribute.enum || polymorphic_type_column?(attribute) || sti_type_column?(attribute)
+                shorthand = !has_custom_filter && !%i[object array union].include?(attribute.type)
+                [name, attribute.type, filter_type, shorthand]
+              end
+
+              associations = representation_class.associations.filter_map do |name, association|
+                next unless association.filterable?
+                next if association.polymorphic?
+
+                representation = association.representation_class
+                next unless representation
+
+                contract = contract_for(representation)
+                next unless contract
+
+                alias_name = representation.root_key.singular.to_sym
+                import(contract, as: alias_name)
+
+                filter_type = [alias_name, TYPE_NAME].join('_').to_sym
+                next unless type?(filter_type)
+
+                [name, filter_type]
+              end
+
+              object(TYPE_NAME) do |object|
+                object.array?(Constants::AND) do |element|
+                  element.reference(TYPE_NAME)
+                end
+                object.array?(Constants::OR) do |element|
+                  element.reference(TYPE_NAME)
+                end
+                object.reference?(Constants::NOT, to: TYPE_NAME)
+
+                attributes.each do |name, type, filter_type, shorthand|
+                  if shorthand
+                    object.union?(name) do |union|
+                      union.variant do |element|
+                        element.of(type)
+                      end
+                      union.variant do |element|
+                        element.reference(filter_type)
+                      end
+                    end
+                  else
+                    object.reference?(name, to: filter_type)
+                  end
+                end
+
+                associations.each do |name, filter_type|
+                  object.reference?(name, to: filter_type)
+                end
+              end
+
+              return unless type?(TYPE_NAME)
+
+              action(:index) do |act|
+                act.request do |request|
+                  request.query do |query|
+                    query.union?(TYPE_NAME) do |union|
+                      union.variant do |element|
+                        element.reference(TYPE_NAME)
+                      end
+                      union.variant do |element|
+                        element.array do |array|
+                          array.reference(TYPE_NAME)
+                        end
+                      end
+                    end
+                  end
+                end
+              end
+            end
+
+            private
+
+            def build_polymorphic_type_filters
+              representation_class.attributes.each do |name, attribute|
+                next unless attribute.filterable?
+
+                association = representation_class.polymorphic_association_for_type_column(name)
+                next unless association
+
+                type_name = [name, TYPE_NAME].join('_').to_sym
+                next if type?(type_name)
+
+                enum name, values: association.polymorphic.map(&:polymorphic_name)
+                build_enum_filter_union(type_name, scoped_enum_name(name))
+              end
+            end
+
+            def build_sti_type_filters
+              return if representation_class.subclass?
+
+              representation_class.attributes.each do |name, attribute|
+                next unless attribute.filterable?
+
+                inheritance = representation_class.inheritance_for_column(name)
+                next unless inheritance
+
+                type_name = [name, TYPE_NAME].join('_').to_sym
+                next if type?(type_name)
+
+                enum(name, values: inheritance.subclasses.map(&:sti_name))
+                build_enum_filter_union(type_name, scoped_enum_name(name))
+              end
+            end
+
+            def build_enum_filter_union(type_name, enum_name)
+              union(type_name) do |union|
+                union.variant do |element|
+                  element.reference(enum_name)
+                end
+                union.variant(partial: true) do |element|
+                  element.object do |object|
+                    object.reference(:eq, to: enum_name)
+                    object.array(:in) do |array|
+                      array.reference(enum_name)
+                    end
+                  end
+                end
+              end
+            end
+
+            def polymorphic_type_column?(attribute)
+              representation_class.polymorphic_association_for_type_column(attribute.name).present?
+            end
+
+            def sti_type_column?(attribute)
+              representation_class.inheritance_for_column(attribute.name).present?
+            end
+
+            def filter_type_for(attribute)
+              custom_type = [attribute.name, TYPE_NAME].join('_').to_sym
+              return custom_type if attribute.enum
+              return custom_type if polymorphic_type_column?(attribute)
+              return custom_type if sti_type_column?(attribute)
+
+              type = case attribute.type
+                     when :string, :binary then :string_filter
+                     when :date then :date_filter
+                     when :datetime then :datetime_filter
+                     when :time then :time_filter
+                     when :integer then :integer_filter
+                     when :decimal then :decimal_filter
+                     when :number then :number_filter
+                     when :uuid then :uuid_filter
+                     when :boolean then :boolean_filter
+                     else :string_filter
+                     end
+
+              attribute.nullable? ? [:nullable, type].join('_').to_sym : type
+            end
+
+            def filterable?
+              representation_class.attributes.values.any? { |attribute| attribute.filterable? && UNFILTERABLE_TYPES.exclude?(attribute.type) } ||
+                representation_class.associations.values.any?(&:filterable?)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/apiwork/adapter/standard/capability/filtering/operation/filter/builder.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module Adapter
+    class Standard
+      module Capability
+        class Filtering
+          class Operation
+            class Filter
+              class Builder
+                attr_reader :allowed_types,
+                            :column,
+                            :field_name
+
+                def initialize(column, field_name, allowed_types:)
+                  @column = column
+                  @field_name = field_name
+                  @allowed_types = Array(allowed_types)
+                end
+
+                def build(value, normalizer: nil, valid_operators:, &block)
+                  value = normalize_value(value, normalizer) if normalizer
+                  return nil unless valid_value_type?(value)
+
+                  builder = OperatorBuilder.new(column, field_name, valid_operators:)
+                  builder.build(value, &block)
+                end
+
+                private
+
+                def normalize_value(value, normalizer)
+                  normalizer.call(value)
+                end
+
+                def valid_value_type?(value)
+                  return true if allowed_types.empty?
+
+                  allowed_types.any? { |type| value.is_a?(type) }
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end