apiwork 0.0.0.pre → 0.1.1

data/lib/apiwork/representation/association.rb

@@ -0,0 +1,391 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module Representation
+    # @api public
+    # Represents an association defined on a representation.
+    #
+    # Associations map to model relationships and define serialization behavior.
+    # Used by adapters to build contracts and serialize records.
+    #
+    # @example
+    #   association = InvoiceRepresentation.associations[:customer]
+    #   association.name # => :customer
+    #   association.type # => :belongs_to
+    #   association.representation_class # => CustomerRepresentation
+    class Association
+      # @!attribute [r] description
+      #   @api public
+      #   The description for this association.
+      #
+      #   @return [String, nil]
+      # @!attribute [r] example
+      #   @api public
+      #   The example for this association.
+      #
+      #   @return [Object, nil]
+      # @!attribute [r] include
+      #   @api public
+      #   The inclusion strategy for this association.
+      #
+      #   @return [Symbol]
+      # @!attribute [r] name
+      #   @api public
+      #   The name for this association.
+      #
+      #   @return [Symbol]
+      # @!attribute [r] polymorphic
+      #   @api public
+      #   The polymorphic representations for this association.
+      #
+      #   @return [Array<Class<Representation::Base>>, nil]
+      # @!attribute [r] type
+      #   @api public
+      #   The type for this association.
+      #
+      #   @return [Symbol]
+      # @!attribute [r] model_class
+      #   @api public
+      #   The model class for this association.
+      #
+      #   @return [Class<ActiveRecord::Base>]
+      attr_reader :allow_destroy,
+                  :description,
+                  :discriminator,
+                  :example,
+                  :include,
+                  :model_class,
+                  :name,
+                  :polymorphic,
+                  :type
+
+      def initialize(
+        name,
+        type,
+        owner_representation_class,
+        allow_destroy: false,
+        deprecated: false,
+        description: nil,
+        example: nil,
+        filterable: false,
+        include: :optional,
+        nullable: nil,
+        polymorphic: nil,
+        representation: nil,
+        sortable: false,
+        writable: false
+      )
+        @name = name
+        @type = type
+        @owner_representation_class = owner_representation_class
+        @model_class = owner_representation_class.model_class
+        @representation_class = representation
+        validate_representation!
+        @polymorphic = normalize_polymorphic(polymorphic)
+
+        @filterable = filterable
+        @sortable = sortable
+        @include = include
+        @writable = writable
+        @allow_destroy = allow_destroy
+        @nullable = nullable
+        @description = description
+        @example = example
+        @deprecated = deprecated
+
+        detect_polymorphic_discriminator! if @polymorphic
+
+        validate_include_option!
+        validate_association_exists!
+        validate_polymorphic!
+        validate_nested_attributes!
+        validate_query_options!
+      end
+
+      # @api public
+      # Whether this association is deprecated.
+      #
+      # @return [Boolean]
+      def deprecated?
+        @deprecated
+      end
+
+      # @api public
+      # Whether this association is filterable.
+      #
+      # @return [Boolean]
+      def filterable?
+        @filterable
+      end
+
+      # @api public
+      # Whether this association is sortable.
+      #
+      # @return [Boolean]
+      def sortable?
+        @sortable
+      end
+
+      # @api public
+      # Whether this association is writable.
+      #
+      # @return [Boolean]
+      # @see #writable_for?
+      def writable?
+        [true, :create, :update].include?(@writable)
+      end
+
+      # @api public
+      # Whether this association is writable for the given action.
+      #
+      # @param action [Symbol] [:create, :update]
+      #   The action.
+      # @return [Boolean]
+      # @see #writable?
+      def writable_for?(action)
+        [true, action].include?(@writable)
+      end
+
+      # @api public
+      # Whether this association is a collection.
+      #
+      # @return [Boolean]
+      def collection?
+        @type == :has_many
+      end
+
+      # @api public
+      # Whether this association is singular.
+      #
+      # @return [Boolean]
+      def singular?
+        %i[has_one belongs_to].include?(@type)
+      end
+
+      # @api public
+      # Whether this association is polymorphic.
+      #
+      # @return [Boolean]
+      def polymorphic?
+        @polymorphic.present?
+      end
+
+      # @api public
+      # Whether this association is nullable.
+      #
+      # @return [Boolean]
+      def nullable?
+        return @nullable unless @nullable.nil?
+
+        case @type
+        when :belongs_to
+          return false unless @model_class
+
+          foreign_key = detect_foreign_key
+          column = column_for(foreign_key)
+          return false unless column
+
+          column.null
+        when :has_one, :has_many
+          false
+        end
+      end
+
+      # @api public
+      # Uses explicit `representation:` if set, otherwise inferred from the model.
+      #
+      # @return [Class<Representation::Base>, nil]
+      def representation_class
+        @representation_class || inferred_representation_class
+      end
+
+      def representation_class_name
+        @representation_class_name ||= @owner_representation_class
+          .name
+          .demodulize
+          .delete_suffix('Representation')
+          .underscore
+      end
+
+      def find_representation_for_type(type_value)
+        return nil unless @polymorphic
+
+        @polymorphic.find do |representation_class|
+          representation_class.model_class.polymorphic_name == type_value
+        end
+      end
+
+      private
+
+      def inferred_representation_class
+        return nil if polymorphic?
+        return nil unless @model_class
+
+        reflection = @model_class.reflect_on_association(@name)
+        return nil if reflection.nil? || reflection.polymorphic?
+
+        namespace = @owner_representation_class.name.deconstantize
+        "#{namespace}::#{reflection.klass.name.demodulize}Representation".safe_constantize
+      end
+
+      def normalize_polymorphic(value)
+        return nil unless value
+        return nil unless value.is_a?(Array)
+
+        value.each do |item|
+          validate_polymorphic_item!(item)
+        end
+
+        value
+      end
+
+      def validate_polymorphic_item!(item)
+        return if item.is_a?(Class) && item < Apiwork::Representation::Base
+
+        if item.is_a?(Symbol)
+          raise ConfigurationError,
+                'polymorphic requires representation classes, not symbols. ' \
+                "Use `polymorphic: [#{item.to_s.camelize}Representation]` instead of `polymorphic: [:#{item}]`"
+        elsif item.is_a?(String)
+          raise ConfigurationError,
+                'polymorphic requires representation classes, not strings. ' \
+                "Use `polymorphic: [#{item.split('::').last}]` instead of `polymorphic: ['#{item}']`"
+        else
+          raise ConfigurationError,
+                "polymorphic requires representation classes, got #{item.class}"
+        end
+      end
+
+      def validate_representation!
+        return unless @representation_class
+        return if @representation_class.is_a?(Class) && @representation_class < Apiwork::Representation::Base
+
+        case @representation_class
+        when Symbol
+          raise ConfigurationError,
+                'representation must be a Representation class, not a symbol. ' \
+                "Use: representation: #{@representation_class.to_s.camelize}Representation (not :#{@representation_class})"
+        when String
+          raise ConfigurationError,
+                'representation must be a Representation class, not a string. ' \
+                "Use: representation: #{@representation_class.split('::').last} (not '#{@representation_class}')"
+        when Class
+          raise ConfigurationError,
+                'representation must be a Representation class (subclass of Apiwork::Representation::Base), ' \
+                "got #{@representation_class}"
+        else
+          raise ConfigurationError,
+                "representation must be a Representation class, got #{@representation_class.class}"
+        end
+      end
+
+      def column_for(name)
+        @model_class.columns_hash[name.to_s]
+      end
+
+      def detect_foreign_key
+        reflection = @model_class.reflect_on_association(@name)
+        return "#{@name}_id" unless reflection
+
+        reflection.foreign_key
+      end
+
+      def detect_polymorphic_discriminator!
+        return unless @model_class
+
+        reflection = @model_class.reflect_on_association(@name)
+        return unless reflection
+        return unless reflection.foreign_type
+
+        @discriminator = reflection.foreign_type.to_sym
+      end
+
+      def validate_polymorphic!
+        return unless polymorphic?
+
+        raise_polymorphic_error(:filterable) if @filterable
+        raise_polymorphic_error(:sortable) if @sortable
+        raise_polymorphic_error(:writable, suffix: '. Rails does not support accepts_nested_attributes_for on polymorphic associations') if writable?
+      end
+
+      def raise_polymorphic_error(option, suffix: '')
+        raise ConfigurationError.new(
+          code: :invalid_polymorphic_option,
+          detail: "Polymorphic association '#{@name}' cannot use #{option}: true#{suffix}",
+          path: [@name],
+        )
+      end
+
+      def validate_include_option!
+        valid_options = %i[always optional]
+        return if valid_options.include?(@include)
+
+        detail = "Invalid include option ':#{@include}' for association '#{@name}'. " \
+                 'Must be :always or :optional'
+        error = ConfigurationError.new(
+          detail:,
+          code: :invalid_include_option,
+          path: [@name],
+        )
+
+        raise error
+      end
+
+      def validate_association_exists!
+        return if @owner_representation_class.abstract?
+        return if @model_class.nil?
+        return if @representation_class
+
+        reflection = @model_class.reflect_on_association(@name)
+        return if reflection
+
+        detail = "Undefined association '#{@name}' in #{@owner_representation_class.name}: no association on model"
+        error = ConfigurationError.new(
+          detail:,
+          code: :invalid_association,
+          path: [@name],
+        )
+
+        raise error
+      end
+
+      def validate_nested_attributes!
+        return unless @model_class
+        return unless writable?
+
+        nested_attribute_method = "#{@name}_attributes="
+        unless @model_class.instance_methods.include?(nested_attribute_method.to_sym)
+          detail = "#{@model_class.name} doesn't accept nested attributes for #{@name}. " \
+                   "Add: accepts_nested_attributes_for :#{@name}"
+          error = ConfigurationError.new(
+            detail:,
+            code: :missing_nested_attributes,
+            path: [@name],
+          )
+
+          raise error
+        end
+
+        nested_options = @model_class.nested_attributes_options[@name]
+        return unless nested_options
+
+        @allow_destroy = nested_options[:allow_destroy]
+      end
+
+      def validate_query_options!
+        return unless @filterable || @sortable
+        return if @owner_representation_class.abstract?
+        return unless @model_class
+
+        reflection = @model_class.reflect_on_association(@name)
+        return if reflection
+
+        raise ConfigurationError.new(
+          code: :query_option_requires_association,
+          detail: "Association #{@name}: filterable/sortable requires an ActiveRecord association for JOINs",
+          path: [@name],
+        )
+      end
+    end
+  end
+end

data/lib/apiwork/representation/attribute.rb

@@ -0,0 +1,335 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module Representation
+    # @api public
+    # Represents an attribute defined on a representation.
+    #
+    # Attributes map to model columns and define serialization behavior.
+    # Used by adapters to build contracts and serialize records.
+    #
+    # @example
+    #   attribute = InvoiceRepresentation.attributes[:title]
+    #   attribute.name # => :title
+    #   attribute.type # => :string
+    #   attribute.filterable? # => true
+    class Attribute
+      ALLOWED_FORMATS = {
+        decimal: %i[float double],
+        integer: %i[int32 int64],
+        number: %i[float double],
+        string: %i[email uuid url date datetime ipv4 ipv6 password hostname],
+      }.freeze
+
+      # @!attribute [r] description
+      #   @api public
+      #   The description for this attribute.
+      #
+      #   @return [String, nil]
+      # @!attribute [r] enum
+      #   @api public
+      #   The enum for this attribute.
+      #
+      #   @return [Array<Object>, nil]
+      # @!attribute [r] example
+      #   @api public
+      #   The example for this attribute.
+      #
+      #   @return [Object, nil]
+      # @!attribute [r] format
+      #   @api public
+      #   The format for this attribute.
+      #
+      #   @return [Symbol, nil]
+      # @!attribute [r] max
+      #   @api public
+      #   The maximum for this attribute.
+      #
+      #   @return [Integer, nil]
+      # @!attribute [r] min
+      #   @api public
+      #   The minimum for this attribute.
+      #
+      #   @return [Integer, nil]
+      # @!attribute [r] name
+      #   @api public
+      #   The name for this attribute.
+      #
+      #   @return [Symbol]
+      # @!attribute [r] of
+      #   @api public
+      #   The of for this attribute.
+      #
+      #   @return [Symbol, nil]
+      # @!attribute [r] preload
+      #   @api public
+      #   The preload for this attribute.
+      #
+      #   @return [Symbol, Array, Hash, nil]
+      # @!attribute [r] type
+      #   @api public
+      #   The type for this attribute.
+      #
+      #   @return [Symbol]
+      attr_reader :description,
+                  :element,
+                  :empty,
+                  :enum,
+                  :example,
+                  :format,
+                  :max,
+                  :min,
+                  :name,
+                  :of,
+                  :optional,
+                  :preload,
+                  :type
+
+      def initialize(
+        name,
+        owner_representation_class,
+        decode: nil,
+        deprecated: false,
+        description: nil,
+        empty: false,
+        encode: nil,
+        enum: nil,
+        example: nil,
+        filterable: false,
+        format: nil,
+        max: nil,
+        min: nil,
+        nullable: nil,
+        optional: nil,
+        preload: nil,
+        sortable: false,
+        type: nil,
+        writable: false,
+        &block
+      )
+        @name = name
+        @owner_representation_class = owner_representation_class
+        @of = nil
+
+        if block
+          element = Element.new
+          block.arity.positive? ? yield(element) : element.instance_eval(&block)
+          element.validate!
+          @element = element
+          type = element.type
+          @of = element.inner&.type if element.type == :array
+        end
+
+        if owner_representation_class.model_class.present?
+          @model_class = owner_representation_class.model_class
+
+          begin
+            @db_column = @model_class.column_names.include?(name.to_s)
+
+            detected_enum = detect_enum_values(name)
+            enum ||= detected_enum
+            type ||= detect_type(name) if @db_column
+            type = :string if detected_enum && type == :integer
+            optional = detect_optional(name) if optional.nil?
+            nullable = detect_nullable(name) if nullable.nil?
+          rescue ActiveRecord::StatementInvalid, ActiveRecord::NoDatabaseError, ActiveRecord::ConnectionNotEstablished
+            @db_column = false
+          end
+        end
+
+        optional = false if optional.nil?
+        nullable = false if nullable.nil?
+
+        @filterable = filterable
+        @preload = preload
+        @sortable = sortable
+        @writable = writable
+        @encode = encode
+        @decode = decode
+        @empty = empty
+        @nullable = nullable
+        @optional = optional
+        @type = type || :unknown
+        @enum = enum
+        @min = min
+        @max = max
+        @description = description
+        @example = example
+        @format = format
+        @deprecated = deprecated
+
+        validate_min_max_range!
+        validate_format!
+        validate_empty!
+      end
+
+      # @api public
+      # Whether this attribute is deprecated.
+      #
+      # @return [Boolean]
+      def deprecated?
+        @deprecated
+      end
+
+      # @api public
+      # Whether this attribute is filterable.
+      #
+      # @return [Boolean]
+      def filterable?
+        @filterable
+      end
+
+      # @api public
+      # Whether this attribute is sortable.
+      #
+      # @return [Boolean]
+      def sortable?
+        @sortable
+      end
+
+      # @api public
+      # Whether this attribute is optional.
+      #
+      # @return [Boolean]
+      def optional?
+        @optional
+      end
+
+      # @api public
+      # Whether this attribute is nullable.
+      #
+      # @return [Boolean]
+      def nullable?
+        return false if @empty
+
+        @nullable
+      end
+
+      # @api public
+      # Whether this attribute is writable.
+      #
+      # @return [Boolean]
+      # @see #writable_for?
+      def writable?
+        [true, :create, :update].include?(@writable)
+      end
+
+      # @api public
+      # Whether this attribute is writable for the given action.
+      #
+      # @param action [Symbol] [:create, :update]
+      #   The action.
+      # @return [Boolean]
+      # @see #writable?
+      def writable_for?(action)
+        [true, action].include?(@writable)
+      end
+
+      def encode(value)
+        result = @empty && value.nil? ? '' : value
+        @encode ? @encode.call(result) : result
+      end
+
+      def decode(value)
+        result = @decode ? @decode.call(value) : value
+        @empty ? result.presence : result
+      end
+
+      def representation_class_name
+        @representation_class_name ||= @owner_representation_class
+          .name
+          .demodulize
+          .delete_suffix('Representation')
+          .underscore
+      end
+
+      private
+
+      def detect_enum_values(name)
+        return nil unless @model_class.defined_enums.key?(name.to_s)
+
+        @model_class.defined_enums[name.to_s].keys
+      end
+
+      def detect_type(name)
+        raw_type = @model_class.type_for_attribute(name).type
+        normalize_db_type(raw_type)
+      end
+
+      def normalize_db_type(type)
+        case type
+        when :text then :string
+        when :jsonb, :json then :unknown
+        when :float then :number
+        else type
+        end
+      end
+
+      def detect_optional(name)
+        return false unless @model_class
+        return false unless db_column?
+
+        column = column_for(name)
+        return false unless column
+
+        return true if column.default.present?
+
+        column.null
+      end
+
+      def detect_nullable(name)
+        return false unless @model_class
+        return false unless db_column?
+
+        column = column_for(name)
+        return false unless column
+
+        column.null
+      end
+
+      def column_for(name)
+        @model_class.columns_hash[name.to_s]
+      end
+
+      def db_column?
+        @db_column
+      end
+
+      def validate_min_max_range!
+        return if @min.nil?
+        return if @max.nil?
+        return unless @min > @max
+
+        raise ConfigurationError,
+              "Attribute #{@name}: min (#{@min}) cannot be greater than max (#{@max})"
+      end
+
+      def validate_format!
+        return if @format.nil?
+        return if @type == :unknown
+
+        allowed_formats = ALLOWED_FORMATS[@type]
+
+        unless allowed_formats
+          raise ConfigurationError,
+                "Attribute #{@name}: format option is not supported for type :#{@type}"
+        end
+
+        return if allowed_formats.include?(@format.to_sym)
+
+        raise ConfigurationError,
+              "Attribute #{@name}: format :#{@format} is not valid for type :#{@type}. " \
+              "Allowed formats: #{allowed_formats.join(', ')}"
+      end
+
+      def validate_empty!
+        return unless @empty
+        return if @type == :unknown
+        return if @type == :string
+
+        raise ConfigurationError,
+              "Attribute #{@name}: empty option is only supported for type :string"
+      end
+    end
+  end
+end