apiwork 0.0.0.pre → 0.1.1

data/lib/apiwork/contract/object.rb

@@ -0,0 +1,566 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module Contract
+    # @api public
+    # Block context for defining request/response structure.
+    #
+    # Accessed via `body do` and `query do` inside contract actions,
+    # or `object :name do` at contract level to define reusable types.
+    #
+    # @see API::Object Block context for reusable types
+    #
+    # @example instance_eval style
+    #   body do
+    #     string :title
+    #     decimal :amount
+    #   end
+    #
+    # @example yield style
+    #   body do |body|
+    #     body.string :title
+    #     body.decimal :amount
+    #   end
+    class Object < Apiwork::Object
+      attr_reader :action_name,
+                  :contract_class
+
+      def params
+        return @params if @merged.empty?
+
+        expanded = @params.dup
+        @merged.each do |type_name|
+          merged_type = @contract_class.api_class&.type_registry&.[](type_name)
+          next unless merged_type&.params
+
+          merged_type.params.each do |name, param_options|
+            expanded[name] ||= param_options
+          end
+        end
+        expanded
+      end
+
+      def initialize(contract_class, action_name: nil, visited_types: nil, wrapped: false)
+        super()
+        @contract_class = contract_class
+        @action_name = action_name
+        @wrapped = wrapped
+        @visited_types = visited_types
+      end
+
+      # @api public
+      # Defines a param with explicit type.
+      #
+      # This is the verbose form. Prefer sugar methods (string, integer, etc.)
+      # for static definitions.
+      #
+      # @param name [Symbol]
+      #   The param name.
+      # @param type [Symbol, nil] (nil) [:array, :binary, :boolean, :date, :datetime, :decimal, :integer, :literal, :number, :object, :string, :time, :union, :uuid]
+      #   The param type.
+      # @param as [Symbol, nil] (nil)
+      #   The target attribute name.
+      # @param default [Object, nil] (nil)
+      #   The default value.
+      # @param deprecated [Boolean] (false)
+      #   Whether deprecated. Metadata included in exports.
+      # @param description [String, nil] (nil)
+      #   The description. Metadata included in exports.
+      # @param discriminator [Symbol, nil] (nil)
+      #   The discriminator param name. Unions only.
+      # @param enum [Array, Symbol, nil] (nil)
+      #   The allowed values or enum reference.
+      # @param example [Object, nil] (nil)
+      #   The example value. Metadata included in exports.
+      # @param format [Symbol, nil] (nil) [:date, :datetime, :double, :email, :float, :hostname, :int32, :int64, :ipv4, :ipv6, :password, :url, :uuid]
+      #   Format hint for exports. Does not change the type, but exports may add validation or documentation based on it.
+      #   Valid formats by type: `:decimal`/`:number` (`:double`, `:float`), `:integer` (`:int32`, `:int64`),
+      #   `:string` (`:date`, `:datetime`, `:email`, `:hostname`, `:ipv4`, `:ipv6`, `:password`, `:url`, `:uuid`).
+      # @param max [Integer, nil] (nil)
+      #   The maximum. For `:array`: size. For `:decimal`, `:integer`, `:number`: value. For `:string`: length.
+      # @param min [Integer, nil] (nil)
+      #   The minimum. For `:array`: size. For `:decimal`, `:integer`, `:number`: value. For `:string`: length.
+      # @param nullable [Boolean] (false)
+      #   Whether the value can be `null`.
+      # @param of [Symbol, Hash, nil] (nil)
+      #   The element type. Arrays only.
+      # @param optional [Boolean] (false)
+      #   Whether the param is optional.
+      # @param required [Boolean] (false)
+      #   Whether the param is required.
+      # @param shape [Contract::Object, Contract::Union, nil] (nil)
+      #   The pre-built shape.
+      # @param value [Object, nil] (nil)
+      #   The literal value.
+      # @yield block for nested structure
+      # @yieldparam shape [Contract::Object, Contract::Union, Contract::Element]
+      # @return [void]
+      #
+      # @example Dynamic param generation
+      #   param_type = :string
+      #   param :title, type: param_type
+      #
+      # @example Object with block
+      #   param :address, type: :object do
+      #     string :street
+      #     string :city
+      #   end
+      def param(
+        name,
+        type: nil,
+        as: nil,
+        default: nil,
+        deprecated: false,
+        description: nil,
+        discriminator: nil,
+        enum: nil,
+        example: nil,
+        format: nil,
+        max: nil,
+        min: nil,
+        nullable: false,
+        of: nil,
+        optional: false,
+        required: false,
+        shape: nil,
+        value: nil,
+        &block
+      )
+        options = {
+          deprecated:,
+          description:,
+          example:,
+          format:,
+          max:,
+          min:,
+          nullable:,
+          required:,
+        }
+
+        raise ConfigurationError, 'discriminator can only be used with type: :union' if discriminator && type != :union
+
+        visited_types ||= @visited_types
+        visited_types ||= Set.new
+
+        resolved_enum = resolve_enum(enum)
+
+        case type
+        when :literal
+          define_literal_param(name, as:, default:, deprecated:, description:, optional:, value:)
+        when :union
+          define_union_param(
+            name,
+            as:,
+            default:,
+            discriminator:,
+            optional:,
+            options:,
+            resolved_enum:,
+            &block
+          )
+        else
+          define_regular_param(
+            name,
+            as:,
+            default:,
+            of:,
+            optional:,
+            options:,
+            resolved_enum:,
+            shape:,
+            type:,
+            visited_types:,
+            &block
+          )
+        end
+      end
+
+      # @api public
+      # Defines an array param with element type.
+      #
+      # @param name [Symbol]
+      #   The param name.
+      # @param as [Symbol, nil] (nil)
+      #   The target attribute name.
+      # @param default [Object, nil] (nil)
+      #   The default value.
+      # @param deprecated [Boolean] (false)
+      #   Whether deprecated. Metadata included in exports.
+      # @param description [String, nil] (nil)
+      #   The description. Metadata included in exports.
+      # @param nullable [Boolean] (false)
+      #   Whether the value can be `null`.
+      # @param optional [Boolean] (false)
+      #   Whether the param is optional.
+      # @param required [Boolean] (false)
+      #   Whether the param is required.
+      # @yield block for defining element type
+      # @yieldparam element [Contract::Element]
+      # @return [void]
+      #
+      # @example instance_eval style
+      #   array :tags do
+      #     string
+      #   end
+      #
+      # @example yield style
+      #   array :tags do |element|
+      #     element.string
+      #   end
+      def array(
+        name,
+        as: nil,
+        default: nil,
+        deprecated: false,
+        description: nil,
+        nullable: false,
+        optional: false,
+        required: false,
+        &block
+      )
+        raise ConfigurationError, 'array requires a block' unless block
+
+        element = Element.new(@contract_class)
+        block.arity.positive? ? yield(element) : element.instance_eval(&block)
+        element.validate!
+
+        param(
+          name,
+          as:,
+          default:,
+          deprecated:,
+          description:,
+          nullable:,
+          optional:,
+          required:,
+          of: element,
+          type: :array,
+        )
+      end
+
+      def wrapped?
+        @wrapped
+      end
+
+      def validate(data, current_depth: 0, max_depth: 10, path: [])
+        Validator.validate(self, data, current_depth:, max_depth:, path:)
+      end
+
+      def coerce(data)
+        Coercer.coerce(self, data)
+      end
+
+      def deserialize(data)
+        Deserializer.deserialize(self, data)
+      end
+
+      def transform(data)
+        Transformer.transform(self, data)
+      end
+
+      def copy_type_definition_params(type_definition, target_param)
+        return unless type_definition.object?
+
+        type_definition.params.each do |param_name, param_options|
+          nested_shape = param_options[:shape]
+
+          if param_options[:type] == :array && nested_shape.is_a?(Apiwork::API::Object)
+            target_param.param(param_name, **param_options.except(:name))
+          elsif nested_shape.is_a?(API::Object)
+            copy_nested_object_param(target_param, param_name, param_options, nested_shape)
+          elsif nested_shape.is_a?(API::Union)
+            copy_nested_union_param(target_param, param_name, param_options, nested_shape)
+          else
+            target_param.param(param_name, **param_options.except(:name, :shape))
+          end
+        end
+      end
+
+      private
+
+      def copy_nested_object_param(target_param, param_name, param_options, nested_shape)
+        target_param.param(
+          param_name,
+          type: param_options[:type],
+          **param_options.except(:name, :type, :shape),
+        ) do
+          nested_shape.params.each do |nested_name, nested_param_options|
+            param(nested_name, **nested_param_options.except(:name, :shape))
+          end
+        end
+      end
+
+      def copy_nested_union_param(target_param, param_name, param_options, nested_shape)
+        target_param.param(
+          param_name,
+          type: param_options[:type],
+          **param_options.except(:name, :type, :shape),
+        ) do
+          nested_shape.variants.each do |variant|
+            if variant[:shape].is_a?(API::Object)
+              variant tag: variant[:tag] do
+                object do
+                  variant[:shape].params.each do |name, param_options|
+                    param(name, **param_options.except(:name, :shape))
+                  end
+                end
+              end
+            elsif variant[:custom_type]
+              variant tag: variant[:tag] do
+                reference variant[:custom_type]
+              end
+            else
+              variant tag: variant[:tag] do
+                send(variant[:type])
+              end
+            end
+          end
+        end
+      end
+
+      def define_literal_param(name, as:, default:, deprecated:, description:, optional:, value:)
+        raise ConfigurationError, 'Literal type requires a value parameter' if value.nil?
+
+        @params[name] = (@params[name] || {}).merge(
+          {
+            as:,
+            default:,
+            deprecated:,
+            description:,
+            name:,
+            optional:,
+            value:,
+            type: :literal,
+          }.compact,
+        )
+      end
+
+      def define_union_param(name, as:, default:, discriminator:, optional:, options:, resolved_enum:, &block)
+        raise ConfigurationError, 'Union type requires a block with variant definitions' unless block_given?
+
+        union = Union.new(@contract_class, discriminator:)
+        block.arity.positive? ? yield(union) : union.instance_eval(&block)
+
+        @params[name] = (@params[name] || {}).merge(
+          {
+            as:,
+            default:,
+            discriminator:,
+            enum: resolved_enum,
+            name:,
+            optional:,
+            type: :union,
+            union:,
+            **options,
+          }.compact,
+        )
+      end
+
+      def define_regular_param(name, as:, default:, of:, optional:, options:, resolved_enum:, shape:, type:, visited_types:, &block)
+        type_definition = @contract_class.resolve_custom_type(type)
+
+        if type_definition
+          expansion_key = [@contract_class.object_id, type]
+
+          type_definition = nil if visited_types.include?(expansion_key)
+        end
+
+        if type_definition&.object?
+          define_custom_type_param(
+            name,
+            as:,
+            default:,
+            of:,
+            optional:,
+            options:,
+            resolved_enum:,
+            type:,
+            type_definition:,
+            visited_types:,
+            &block
+          )
+        elsif type_definition&.union?
+          define_custom_union_type_param(
+            name,
+            as:,
+            default:,
+            optional:,
+            options:,
+            resolved_enum:,
+            type:,
+            type_definition:,
+          )
+        else
+          define_standard_param(
+            name,
+            as:,
+            default:,
+            of:,
+            optional:,
+            options:,
+            resolved_enum:,
+            shape:,
+            type:,
+            &block
+          )
+        end
+      end
+
+      def define_custom_union_type_param(
+        name,
+        type:,
+        type_definition:,
+        resolved_enum:,
+        optional:,
+        default:,
+        as:,
+        options:
+      )
+        union = Union.new(@contract_class, discriminator: type_definition.discriminator)
+
+        type_definition.variants.each do |variant|
+          if variant[:shape].is_a?(API::Object)
+            union.variant tag: variant[:tag] do
+              object do
+                variant[:shape].params.each do |name, param_options|
+                  param(name, **param_options.except(:name, :shape))
+                end
+              end
+            end
+          elsif variant[:custom_type]
+            union.variant tag: variant[:tag] do
+              reference variant[:custom_type]
+            end
+          else
+            union.variant tag: variant[:tag] do
+              send(variant[:type])
+            end
+          end
+        end
+
+        @params[name] = (@params[name] || {}).merge(
+          {
+            as:,
+            custom_type: type,
+            default:,
+            discriminator: type_definition.discriminator,
+            enum: resolved_enum,
+            name:,
+            optional:,
+            type: :union,
+            union:,
+            **options,
+          }.compact,
+        )
+      end
+
+      def define_custom_type_param(
+        name,
+        type:,
+        type_definition:,
+        resolved_enum:,
+        optional:,
+        default:,
+        of:,
+        as:,
+        visited_types:,
+        options:,
+        &block
+      )
+        shape = Object.new(
+          @contract_class,
+          action_name: @action_name,
+          visited_types: visited_types.dup.add([@contract_class.object_id, type]),
+        )
+
+        copy_type_definition_params(type_definition, shape)
+
+        if block_given?
+          block.arity.positive? ? yield(shape) : shape.instance_eval(&block)
+        end
+
+        @params[name] = (@params[name] || {}).merge(
+          {
+            as:,
+            custom_type: type,
+            default:,
+            enum: resolved_enum,
+            name:,
+            of:,
+            optional:,
+            shape:,
+            type: :object,
+            **options,
+          }.compact,
+        )
+      end
+
+      def define_standard_param(name, as:, default:, of:, optional:, options:, resolved_enum:, shape:, type:, &block)
+        resolved_of = resolve_of(of, type, &block)
+        resolved_shape = resolve_shape(shape, type, &block)
+
+        @params[name] = (@params[name] || {}).merge(
+          {
+            as:,
+            default:,
+            enum: resolved_enum,
+            name:,
+            of: resolved_of,
+            optional:,
+            type:,
+            **options,
+          }.compact,
+        )
+
+        @params[name][:shape] = resolved_shape if resolved_shape
+      end
+
+      def resolve_of(of, type, &block)
+        return nil unless type == :array
+
+        if block_given?
+          element = Element.new(@contract_class)
+          block.arity.positive? ? yield(element) : element.instance_eval(&block)
+          element.validate!
+          element
+        elsif of.is_a?(Symbol)
+          wrap_symbol_in_element(of)
+        else
+          of
+        end
+      end
+
+      def resolve_shape(shape, type, &block)
+        return nil if type == :array
+
+        if shape
+          shape
+        elsif block_given?
+          nested_shape = Object.new(@contract_class, action_name: @action_name)
+          block.arity.positive? ? yield(nested_shape) : nested_shape.instance_eval(&block)
+          nested_shape
+        end
+      end
+
+      def wrap_symbol_in_element(type_symbol)
+        element = Element.new(@contract_class)
+        element.of(type_symbol)
+        element
+      end
+
+      def resolve_enum(enum)
+        return nil if enum.nil?
+        return enum if enum.is_a?(Array)
+
+        raise ConfigurationError, "enum must be a Symbol (reference) or Array (inline values), got #{enum.class}" unless enum.is_a?(Symbol)
+
+        unless @contract_class.enum?(enum)
+          raise ConfigurationError,
+                "Enum :#{enum} not found. Define it using `enum :#{enum}, %w[...]` in definition scope."
+        end
+
+        enum
+      end
+    end
+  end
+end

data/lib/apiwork/contract/request_parser/result.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module Contract
+    class RequestParser
+      class Result
+        attr_reader :issues,
+                    :request
+
+        def initialize(issues: [], request:)
+          @request = request
+          @issues = issues
+        end
+
+        def valid?
+          issues.empty?
+        end
+
+        def invalid?
+          issues.any?
+        end
+      end
+    end
+  end
+end

data/lib/apiwork/contract/request_parser.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module Contract
+    class RequestParser
+      class << self
+        def parse(contract_class, action_name, request, coerce: false)
+          new(contract_class, action_name).parse(request, coerce:)
+        end
+      end
+
+      def initialize(contract_class, action_name)
+        @contract_class = contract_class
+        @action_name = action_name.to_sym
+      end
+
+      def parse(request, coerce: false)
+        request = coerce_request(request) if coerce
+
+        parsed_query, query_issues = parse_part(request.query, :query)
+        parsed_body, body_issues = parse_part(request.body, :body)
+
+        Result.new(
+          issues: query_issues + body_issues,
+          request: Request.new(body: parsed_body, query: parsed_query),
+        )
+      end
+
+      private
+
+      def coerce_request(request)
+        request
+          .transform_query { |query| coerce(query, shape_for(:query)) }
+          .transform_body { |body| coerce(body, shape_for(:body)) }
+      end
+
+      def parse_part(data, part_type)
+        shape = shape_for(part_type)
+        return [{}, []] if shape.nil? && data.blank?
+        return [data, []] unless shape
+
+        validated = shape.validate(data)
+
+        return [{}, validated.issues] if validated.invalid?
+
+        [shape.transform(shape.deserialize(validated.params)), []]
+      end
+
+      def action
+        @action ||= @contract_class.action_for(@action_name)
+      end
+
+      def shape_for(part_type)
+        return unless action
+
+        case part_type
+        when :query
+          action.request.query
+        when :body
+          action.request.body
+        end
+      end
+
+      def coerce(data, shape)
+        return data unless shape
+        return data unless data.is_a?(Hash)
+
+        shape.coerce(data)
+      end
+    end
+  end
+end

data/lib/apiwork/contract/response_parser/result.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module Contract
+    class ResponseParser
+      class Result
+        attr_reader :issues,
+                    :response
+
+        def initialize(issues: [], response:)
+          @response = response
+          @issues = issues
+        end
+
+        def valid?
+          issues.empty?
+        end
+
+        def invalid?
+          issues.any?
+        end
+      end
+    end
+  end
+end