apiwork 0.0.0.pre → 0.1.1

data/lib/apiwork/contract/element.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module Contract
+    # @api public
+    # Block context for defining a single type expression.
+    #
+    # Used inside `array do` and `variant do` blocks where
+    # exactly one element type must be defined.
+    #
+    # @see Contract::Object Block context for object params
+    # @see Contract::Union Block context for union variants
+    #
+    # @example instance_eval style
+    #   array :ids do
+    #     integer
+    #   end
+    #
+    # @example yield style
+    #   array :ids do |element|
+    #     element.integer
+    #   end
+    #
+    # @example Array of references
+    #   array :items do |element|
+    #     element.reference :item
+    #   end
+    class Element < Apiwork::Element
+      def initialize(contract_class)
+        super()
+        @contract_class = contract_class
+      end
+
+      # @api public
+      # Defines the element type.
+      #
+      # This is the verbose form. Prefer sugar methods (string, integer, etc.)
+      # for static definitions. Use `of` for dynamic element generation.
+      #
+      # @param type [Symbol] [:array, :binary, :boolean, :date, :datetime, :decimal, :integer, :literal, :number, :object, :string, :time, :union, :uuid]
+      #   The element type. Custom type references are also allowed.
+      # @param discriminator [Symbol, nil] (nil)
+      #   The discriminator field name. Unions only.
+      # @param enum [Array, Symbol, nil] (nil)
+      #   The allowed values or enum reference. Strings and integers only.
+      # @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 `:decimal`, `:integer`, `:number`: value. For `:string`: length.
+      # @param min [Integer, nil] (nil)
+      #   The minimum. For `:decimal`, `:integer`, `:number`: value. For `:string`: length.
+      # @param value [Object, nil] (nil)
+      #   The literal value. Literals only.
+      # @yield block for defining nested structure (instance_eval style)
+      # @yieldparam shape [Contract::Object, Contract::Union, Contract::Element]
+      # @return [void]
+      # @raise [ArgumentError] if object, array, or union type is missing block
+      #
+      # @example Dynamic element type
+      #   element_type = :string
+      #   array :values do
+      #     of element_type
+      #   end
+      #
+      # @example Object with block
+      #   array :tags do
+      #     of :object do
+      #       string :name
+      #       string :color
+      #     end
+      #   end
+      def of(type, discriminator: nil, enum: nil, format: nil, max: nil, min: nil, value: nil, &block)
+        resolved_enum = enum.is_a?(Symbol) ? resolve_enum(enum) : enum
+
+        case type
+        when :string, :integer, :decimal, :boolean, :number, :datetime, :date, :uuid, :time, :binary
+          set_type(type, format:, max:, min:, enum: resolved_enum)
+        when :literal
+          @type = :literal
+          @value = value
+          @defined = true
+        when :object
+          @type = :object
+          if block
+            shape = Object.new(@contract_class)
+            block.arity.positive? ? yield(shape) : shape.instance_eval(&block)
+            @shape = shape
+          end
+          @defined = true
+        when :array
+          raise ConfigurationError, 'array requires a block' unless block
+
+          inner = Element.new(@contract_class)
+          block.arity.positive? ? yield(inner) : inner.instance_eval(&block)
+          inner.validate!
+          @type = :array
+          @inner = inner
+          @shape = inner.shape
+          @defined = true
+        when :union
+          raise ConfigurationError, 'union requires a block' unless block
+
+          shape = Union.new(@contract_class, discriminator:)
+          block.arity.positive? ? yield(shape) : shape.instance_eval(&block)
+          @type = :union
+          @shape = shape
+          @discriminator = discriminator
+          @defined = true
+        else
+          @type = type
+          @custom_type = type
+          @defined = true
+        end
+      end
+
+      private
+
+      def resolve_enum(enum)
+        return nil if enum.nil?
+        return enum if enum.is_a?(Array)
+
+        raise ConfigurationError, "Enum :#{enum} not found." unless @contract_class.enum?(enum)
+
+        enum
+      end
+    end
+  end
+end

data/lib/apiwork/contract/object/coercer.rb

@@ -0,0 +1,194 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module Contract
+    class Object
+      class Coercer
+        PRIMITIVES = {
+          boolean: lambda { |value|
+            return value if [true, false].include?(value)
+            return true if %w[true 1 yes].include?(value.to_s.downcase)
+            return false if %w[false 0 no].include?(value.to_s.downcase)
+
+            nil
+          },
+          date: lambda { |value|
+            return value if value.is_a?(Date)
+
+            Date.parse(value) if value.is_a?(String)
+          },
+          datetime: lambda { |value|
+            return value if value.is_a?(Time) || value.is_a?(DateTime) || value.is_a?(ActiveSupport::TimeWithZone)
+
+            Time.zone.parse(value) if value.is_a?(String)
+          },
+          decimal: lambda { |value|
+            return value if value.is_a?(BigDecimal)
+
+            BigDecimal(value.to_s) if value.is_a?(Numeric) || value.is_a?(String)
+          },
+          integer: lambda { |value|
+            return value if value.is_a?(Integer)
+
+            Integer(value) if value.is_a?(String) && value.match?(/\A-?\d+\z/)
+          },
+          number: lambda { |value|
+            return value if value.is_a?(Float) || value.is_a?(Integer)
+            return nil if value.is_a?(String) && value.blank?
+
+            Float(value) if value.is_a?(String)
+          },
+          string: lambda { |value|
+            return value if value.is_a?(String)
+
+            value.to_s
+          },
+          time: lambda { |value|
+            return value if value.is_a?(Time) || value.is_a?(DateTime) || value.is_a?(ActiveSupport::TimeWithZone)
+
+            Time.zone.parse("2000-01-01T#{value}") if value.is_a?(String) && value.match?(/\A\d{2}:\d{2}(:\d{2})?\z/)
+          },
+          uuid: lambda { |value|
+            return value if value.is_a?(String) && value.match?(/\A[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\z/i)
+
+            nil
+          },
+        }.freeze
+
+        class << self
+          def coerce(shape, hash)
+            new(shape).coerce(hash)
+          end
+        end
+
+        def initialize(shape)
+          @shape = shape
+          @type_cache = {}
+        end
+
+        def coerce(hash)
+          coerced = hash.dup
+
+          @shape.params.each do |name, param_options|
+            next unless coerced.key?(name)
+
+            coerced[name] = coerce_value(coerced[name], param_options)
+          end
+
+          coerced
+        end
+
+        private
+
+        def coerce_value(value, param_options)
+          type = param_options[:type]
+
+          return coerce_union(value, param_options[:union]) if type == :union
+          return coerce_array(value, param_options) if type == :array && value.is_a?(Array)
+          return Coercer.coerce(param_options[:shape], value) if param_options[:shape] && value.is_a?(Hash)
+
+          if value.is_a?(Hash) && type && !PRIMITIVES.key?(type)
+            custom_shape = resolve_custom_shape(type)
+            return Coercer.coerce(custom_shape, value) if custom_shape
+          end
+
+          coerced = coerce_primitive(value, type)
+          coerced.nil? ? value : coerced
+        end
+
+        def coerce_array(array, param_options)
+          custom_shape = nil
+          of = param_options[:of]
+          of_type = of&.type
+          of_shape = of&.shape
+
+          custom_shape = resolve_custom_shape(of_type) if of_type && !PRIMITIVES.key?(of_type)
+
+          array.map do |item|
+            if of_shape && item.is_a?(Hash)
+              Coercer.coerce(of_shape, item)
+            elsif of_type && PRIMITIVES.key?(of_type)
+              coerced = coerce_primitive(item, of_type)
+              coerced.nil? ? item : coerced
+            elsif of_type == :array && item.is_a?(Array) && of&.inner
+              coerce_array(item, { of: of.inner })
+            elsif custom_shape && item.is_a?(Hash)
+              Coercer.coerce(custom_shape, item)
+            else
+              item
+            end
+          end
+        end
+
+        def coerce_union(value, union)
+          if union.variants.any? { |variant| variant[:type] == :boolean }
+            coerced = coerce_primitive(value, :boolean)
+            return coerced unless coerced.nil?
+          end
+
+          discriminator = union.discriminator
+
+          if discriminator && value.is_a?(Hash)
+            discriminator_value = value[discriminator]
+            matching_variant = union.variants.find do |variant|
+              variant[:tag].to_s == discriminator_value.to_s
+            end
+
+            if matching_variant
+              custom_shape = resolve_custom_shape(matching_variant[:type])
+              return Coercer.coerce(custom_shape, value) if custom_shape
+            end
+          end
+
+          union.variants.each do |variant|
+            variant_type = variant[:type]
+            variant_of = variant[:of]
+            variant_of_type = variant_of&.type
+
+            if variant_type == :array && value.is_a?(Array) && variant_of_type
+              custom_shape = resolve_custom_shape(variant_of_type)
+              if custom_shape
+                return value.map do |item|
+                  item.is_a?(Hash) ? Coercer.coerce(custom_shape, item) : item
+                end
+              end
+            end
+
+            next if discriminator
+
+            custom_shape = resolve_custom_shape(variant_type)
+            next unless custom_shape
+
+            return Coercer.coerce(custom_shape, value) if value.is_a?(Hash)
+          end
+
+          value
+        end
+
+        def coerce_primitive(value, type)
+          return nil if value.nil?
+
+          coercer = PRIMITIVES[type]
+          return nil unless coercer
+
+          begin
+            coercer.call(value)
+          rescue ArgumentError, TypeError
+            nil
+          end
+        end
+
+        def resolve_custom_shape(type_name)
+          return @type_cache[type_name] if @type_cache.key?(type_name)
+
+          type_definition = @shape.contract_class.resolve_custom_type(type_name)
+          return @type_cache[type_name] = nil unless type_definition
+
+          @type_cache[type_name] = Object.new(@shape.contract_class).tap do |type_shape|
+            type_shape.copy_type_definition_params(type_definition, type_shape)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/apiwork/contract/object/deserializer.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module Contract
+    class Object
+      class Deserializer
+        class << self
+          def deserialize(shape, hash)
+            new(shape).deserialize(hash)
+          end
+        end
+
+        def initialize(shape)
+          @shape = shape
+        end
+
+        def deserialize(hash)
+          deserialized = hash.dup
+
+          @shape.params.each do |name, param_options|
+            next unless deserialized.key?(name)
+
+            value = deserialized[name]
+
+            deserialized[name] = deserialize_value(value, param_options)
+          end
+
+          deserialized
+        end
+
+        private
+
+        def deserialize_value(value, param_options)
+          if param_options[:union] && value.is_a?(Hash)
+            deserialize_union(value, param_options[:union])
+          elsif param_options[:shape] && value.is_a?(Hash)
+            deserialize_shape(value, param_options[:shape])
+          elsif param_options[:type] == :array && value.is_a?(Array)
+            deserialize_array(value, param_options)
+          else
+            value
+          end
+        end
+
+        def deserialize_shape(hash, nested_shape)
+          representation_class = nested_shape.contract_class.representation_class
+          return representation_class.deserialize(hash) if representation_class && nested_shape.params.none? { |_, options| options[:union] }
+
+          Deserializer.deserialize(nested_shape, hash)
+        end
+
+        def deserialize_union(hash, union)
+          variant = resolve_variant(hash, union)
+          return hash unless variant
+
+          if variant[:shape]
+            representation_class = variant[:shape].contract_class.representation_class
+            return representation_class.deserialize(hash) if representation_class
+
+            Deserializer.deserialize(variant[:shape], hash)
+          elsif variant[:custom_type]
+            deserialize_custom_type(hash, variant[:custom_type])
+          else
+            hash
+          end
+        end
+
+        def resolve_variant(hash, union)
+          discriminator = union.discriminator
+          return union.variants.first unless discriminator
+
+          tag = hash[discriminator]
+          union.variants.find { |v| v[:tag].to_s == tag.to_s }
+        end
+
+        def deserialize_custom_type(hash, type_name)
+          type_definition = @shape.contract_class.resolve_custom_type(type_name)
+          return hash unless type_definition
+
+          representation_class = (type_definition.scope || @shape.contract_class).representation_class
+
+          return representation_class.deserialize(hash) if representation_class
+
+          hash
+        end
+
+        def deserialize_array(array, param_options)
+          array.map do |item|
+            next item unless item.is_a?(Hash)
+
+            if param_options[:shape]
+              Deserializer.deserialize(param_options[:shape], item)
+            else
+              item
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/apiwork/contract/object/transformer.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module Contract
+    class Object
+      class Transformer
+        class << self
+          def transform(shape, params)
+            new(shape).transform(params)
+          end
+        end
+
+        def initialize(shape)
+          @shape = shape
+        end
+
+        def transform(params)
+          return params unless params.is_a?(Hash)
+
+          transformed = params.dup
+
+          @shape.params.each do |name, param_options|
+            next unless transformed.key?(name)
+
+            value = transformed[name]
+
+            if param_options[:as]
+              transformed[param_options[:as]] = transformed.delete(name)
+              name = param_options[:as]
+              value = transformed[name]
+            end
+
+            if param_options[:shape] && value.is_a?(Hash)
+              transformed[name] = Transformer.transform(param_options[:shape], value)
+            elsif param_options[:type] == :array && value.is_a?(Array)
+              of = param_options[:of]
+              of_shape = of&.shape
+
+              if of_shape
+                transformed[name] = value.map do |item|
+                  item.is_a?(Hash) ? Transformer.transform(of_shape, item) : item
+                end
+              elsif of && (array_result = transform_custom_type_array(value, param_options))
+                transformed[name] = array_result
+              end
+            end
+          end
+
+          transformed
+        end
+
+        private
+
+        def transform_custom_type_array(value, param_options)
+          of = param_options[:of]
+          type_name = of&.type
+          custom_type_shape = resolve_custom_type_shape(type_name)
+          return nil unless custom_type_shape
+
+          value.map do |item|
+            item.is_a?(Hash) ? Transformer.transform(custom_type_shape, item) : item
+          end
+        end
+
+        def resolve_custom_type_shape(type_name)
+          contract_class = @shape.contract_class
+          type_definition = contract_class.resolve_custom_type(type_name)
+          return nil unless type_definition
+
+          scope_contract_class = type_definition.scope || contract_class
+
+          if type_definition.object?
+            build_type_shape(type_definition, scope_contract_class)
+          elsif type_definition.union?
+            first_variant = type_definition.variants.first
+            return nil unless first_variant
+
+            variant_type_definition = scope_contract_class.resolve_custom_type(first_variant[:type])
+            return nil unless variant_type_definition
+            return nil unless variant_type_definition.object?
+
+            variant_contract_class = variant_type_definition.scope || scope_contract_class
+            build_type_shape(variant_type_definition, variant_contract_class)
+          end
+        end
+
+        def build_type_shape(type_definition, contract_class)
+          type_shape = Object.new(contract_class, action_name: @shape.action_name)
+          type_shape.copy_type_definition_params(type_definition, type_shape)
+          type_shape
+        end
+      end
+    end
+  end
+end

data/lib/apiwork/contract/object/validator/result.rb

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