apiwork 0.0.0.pre → 0.1.2

data/lib/apiwork/representation/deserializer.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module Representation
+    class Deserializer
+      class << self
+        def deserialize(representation_class, payload)
+          new(representation_class).deserialize(payload)
+        end
+      end
+
+      def initialize(representation_class)
+        @representation_class = representation_class
+      end
+
+      def deserialize(payload)
+        if payload.is_a?(Array)
+          payload.map { |hash| deserialize_hash(hash) }
+        else
+          deserialize_hash(payload)
+        end
+      end
+
+      def deserialize_hash(hash)
+        return hash unless hash.is_a?(Hash)
+
+        result = hash.dup
+
+        transform_type_columns(result)
+
+        @representation_class.attributes.each do |name, attribute|
+          next unless result.key?(name)
+
+          result[name] = attribute.decode(result[name])
+        end
+
+        @representation_class.associations.each do |name, association|
+          next unless result.key?(name)
+
+          nested_representation_class = association.representation_class
+          next unless nested_representation_class
+
+          value = result[name]
+          result[name] = if association.collection? && value.is_a?(Array)
+                           value.map { |item| nested_representation_class.deserialize(item) }
+                         elsif value.is_a?(Hash)
+                           nested_representation_class.deserialize(value)
+                         else
+                           value
+                         end
+        end
+
+        result
+      end
+
+      private
+
+      def transform_type_columns(hash)
+        transform_sti_type(hash)
+        transform_polymorphic_types(hash)
+      end
+
+      def transform_sti_type(hash)
+        inheritance_config = @representation_class.subclass? ? @representation_class.superclass.inheritance : @representation_class.inheritance
+        return unless inheritance_config&.transform?
+
+        column = inheritance_config.column
+        return unless hash.key?(column)
+
+        api_value = hash[column]
+        db_value = inheritance_config.mapping[api_value]
+        hash[column] = db_value if db_value
+      end
+
+      def transform_polymorphic_types(hash)
+        @representation_class.attributes.each_key do |name|
+          next unless hash.key?(name)
+
+          association = @representation_class.polymorphic_association_for_type_column(name)
+          next unless association
+
+          api_value = hash[name]
+          next unless api_value.is_a?(String)
+
+          polymorphic_representation = association.polymorphic.find do |representation|
+            representation.polymorphic_name == api_value
+          end
+          next unless polymorphic_representation
+
+          hash[name] = polymorphic_representation.model_class.polymorphic_name
+        end
+      end
+    end
+  end
+end

data/lib/apiwork/representation/element.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module Representation
+    # @api public
+    # Block context for defining JSON blob structure in representation attributes.
+    #
+    # Used inside attribute blocks to define the shape of JSON/JSONB columns,
+    # Rails store attributes, or any serialized data structure.
+    #
+    # Only complex types are allowed at the top level:
+    # - {#object} for key-value structures
+    # - {#array} for ordered collections
+    # - {#union} for polymorphic structures
+    #
+    # Inside these blocks, the full type DSL is available including
+    # nested objects, arrays, primitives, and unions.
+    #
+    # @see API::Element Block context for array elements
+    # @see API::Object Block context for object fields
+    # @see API::Union Block context for union variants
+    #
+    # @example Object structure
+    #   attribute :settings do
+    #     object do
+    #       string :theme
+    #       boolean :notifications
+    #       integer :max_items, min: 1, max: 100
+    #     end
+    #   end
+    #
+    # @example Array of objects
+    #   attribute :addresses do
+    #     array do
+    #       object do
+    #         string :street
+    #         string :city
+    #         string :zip
+    #         boolean :primary
+    #       end
+    #     end
+    #   end
+    #
+    # @example Nested structures
+    #   attribute :config do
+    #     object do
+    #       string :name
+    #       array :tags do
+    #         string
+    #       end
+    #       object :metadata do
+    #         datetime :created_at
+    #         datetime :updated_at
+    #       end
+    #     end
+    #   end
+    #
+    # @example Union for polymorphic data
+    #   attribute :payment_details do
+    #     union discriminator: :type do
+    #       variant tag: 'card' do
+    #         object do
+    #           string :last_four
+    #           string :brand
+    #         end
+    #       end
+    #       variant tag: 'bank' do
+    #         object do
+    #           string :account_number
+    #           string :routing_number
+    #         end
+    #       end
+    #     end
+    #   end
+    class Element < Apiwork::Element
+      def validate!
+        raise ConfigurationError, 'must define exactly one type (object, array, or union)' unless @defined
+      end
+
+      # @api public
+      # Defines the element type.
+      #
+      # Only complex types (:object, :array, :union) are allowed.
+      #
+      # @param type [Symbol] [:array, :object, :union]
+      #   The element type.
+      # @param discriminator [Symbol, nil] (nil)
+      #   The discriminator field name. Unions only.
+      # @yield block for defining nested structure (instance_eval style)
+      # @yieldparam shape [API::Object, API::Union, API::Element]
+      # @return [void]
+      # @raise [ArgumentError] if object, array, or union type is missing block
+      def of(type, discriminator: nil, &block)
+        case type
+        when :object
+          raise ConfigurationError, 'object requires a block' unless block
+
+          builder = API::Object.new
+          block.arity.positive? ? yield(builder) : builder.instance_eval(&block)
+          @type = :object
+          @shape = builder
+          @defined = true
+        when :array
+          raise ConfigurationError, 'array requires a block' unless block
+
+          inner = API::Element.new
+          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
+
+          builder = API::Union.new(discriminator:)
+          block.arity.positive? ? yield(builder) : builder.instance_eval(&block)
+          @type = :union
+          @shape = builder
+          @discriminator = discriminator
+          @defined = true
+        else
+          raise ConfigurationError, "Representation::Element only supports :object, :array, :union - got #{type.inspect}"
+        end
+      end
+    end
+  end
+end

data/lib/apiwork/representation/inheritance.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module Representation
+    # @api public
+    # Tracks STI subclass representations for a base representation.
+    #
+    # Created automatically when a representation's model uses STI.
+    # Provides resolution of records to their correct subclass representation.
+    #
+    # @example
+    #   ClientRepresentation.inheritance.column # => :type
+    #   ClientRepresentation.inheritance.subclasses # => [PersonClientRepresentation, ...]
+    #   ClientRepresentation.inheritance.resolve(record) # => PersonClientRepresentation
+    class Inheritance
+      # @!attribute [r] base_class
+      #   @api public
+      #   The base class for this inheritance.
+      #
+      #   @return [Class<Representation::Base>]
+      # @!attribute [r] subclasses
+      #   @api public
+      #   The subclasses for this inheritance.
+      #
+      #   @return [Array<Class<Representation::Base>>]
+      attr_reader :base_class,
+                  :subclasses
+
+      def initialize(base_class)
+        @base_class = base_class
+        @subclasses = []
+      end
+
+      # @api public
+      # The column for this inheritance.
+      #
+      # @return [Symbol]
+      def column
+        @base_class.model_class.inheritance_column.to_sym
+      end
+
+      # @api public
+      # Resolves a record to its subclass representation.
+      #
+      # @param record [ActiveRecord::Base]
+      #   The record to resolve.
+      # @return [Class<Representation::Base>, nil]
+      def resolve(record)
+        type_value = record.public_send(column)
+        @subclasses.find { |klass| klass.model_class.sti_name == type_value }
+      end
+
+      # @api public
+      # Whether this inheritance requires type transformation.
+      #
+      # @return [Boolean]
+      def transform?
+        @subclasses.any? { |klass| klass.sti_name != klass.model_class.sti_name }
+      end
+
+      # @api public
+      # Mapping of API names to database type values.
+      #
+      # @return [Hash{String => String}]
+      def mapping
+        @subclasses.to_h { |klass| [klass.sti_name, klass.model_class.sti_name] }
+      end
+
+      def register(representation_class)
+        @subclasses << representation_class
+      end
+
+      def subclass?(representation_class)
+        @subclasses.include?(representation_class)
+      end
+    end
+  end
+end

data/lib/apiwork/representation/model_detector.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module Representation
+    class ModelDetector
+      def initialize(representation_class)
+        @representation_class = representation_class
+      end
+
+      def detect
+        return nil if @representation_class.abstract?
+
+        full_name = @representation_class.name
+        return nil unless full_name
+
+        representation_name = full_name.demodulize
+        model_name = representation_name.delete_suffix('Representation')
+        return nil if model_name.blank?
+
+        resolve_model_class(full_name, model_name)
+      end
+
+      def sti_base?(model_class)
+        return false if model_class.abstract_class?
+
+        column = model_class.inheritance_column
+        return false unless column
+
+        begin
+          return false unless model_class.column_names.include?(column.to_s)
+        rescue ActiveRecord::StatementInvalid, ActiveRecord::NoDatabaseError, ActiveRecord::ConnectionNotEstablished
+          return false
+        end
+
+        model_class == model_class.base_class
+      end
+
+      def sti_subclass?(model_class)
+        return false if model_class.abstract_class?
+
+        model_class != model_class.base_class
+      end
+
+      def superclass_is_sti_base?(model_class)
+        parent_model = @representation_class.superclass.model_class
+        return false unless parent_model
+
+        parent_model == model_class.base_class
+      end
+
+      private
+
+      def resolve_model_class(full_name, model_name)
+        namespace = full_name.deconstantize
+        model_class = if namespace.present?
+                        "#{namespace}::#{model_name}".safe_constantize || model_name.safe_constantize
+                      else
+                        model_name.safe_constantize
+                      end
+
+        if model_class.is_a?(Class) && model_class < ActiveRecord::Base
+          model_class
+        else
+          raise ConfigurationError.new(
+            code: :model_not_found,
+            detail: "Could not find model '#{model_name}' for #{full_name}. " \
+                    "Either create the model, declare it explicitly with 'model YourModel', " \
+                    "or mark this representation as abstract with 'abstract!'",
+            path: [],
+          )
+        end
+      end
+    end
+  end
+end

data/lib/apiwork/representation/root_key.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module Representation
+    # @api public
+    # Represents the JSON root key for a representation.
+    #
+    # Root keys wrap response data in a named container.
+    # Used by adapters to structure JSON responses.
+    #
+    # @example
+    #   root_key = InvoiceRepresentation.root_key
+    #   root_key.singular # => "invoice"
+    #   root_key.plural # => "invoices"
+    class RootKey
+      # @!attribute [r] plural
+      #   @api public
+      #   The plural root key.
+      #
+      #   @return [String]
+      # @!attribute [r] singular
+      #   @api public
+      #   The singular root key.
+      #
+      #   @return [String]
+      attr_reader :plural,
+                  :singular
+
+      def initialize(singular, plural = singular.pluralize)
+        @singular = singular
+        @plural   = plural
+      end
+    end
+  end
+end

data/lib/apiwork/representation/serializer.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module Representation
+    class Serializer
+      class << self
+        def serialize(representation, includes)
+          new(representation, includes).serialize
+        end
+      end
+
+      def initialize(representation, includes)
+        @representation = representation
+        @representation_class = representation.class
+        @includes = includes
+      end
+
+      def serialize
+        fields = {}
+
+        add_discriminator_field(fields) if @representation_class.subclass?
+
+        @representation_class.attributes.each do |name, attribute|
+          value = @representation.respond_to?(name) ? @representation.public_send(name) : @representation.record.public_send(name)
+          value = map_type_column_output(name, value)
+          value = attribute.encode(value)
+          fields[name] = value
+        end
+
+        @representation_class.associations.each do |name, association|
+          next unless include_association?(name, association)
+
+          fields[name] = serialize_association(name, association)
+        end
+
+        fields
+      end
+
+      private
+
+      def add_discriminator_field(fields)
+        parent_representation = @representation_class.superclass
+        return unless parent_representation.inheritance
+
+        fields[parent_representation.inheritance.column] = @representation_class.sti_name
+      end
+
+      def map_type_column_output(attribute_name, value)
+        return value if value.nil?
+
+        association = @representation_class.polymorphic_association_for_type_column(attribute_name)
+        if association
+          found_class = association.find_representation_for_type(value)
+          return found_class.polymorphic_name if found_class
+        end
+
+        inheritance = @representation_class.inheritance_for_column(attribute_name)
+        if inheritance
+          klass = inheritance.subclasses.find { |subclass| subclass.model_class.sti_name == value }
+          return klass.sti_name if klass
+        end
+
+        value
+      end
+
+      def serialize_association(name, association)
+        target = @representation.respond_to?(name) ? @representation.public_send(name) : @representation.record.public_send(name)
+        return nil if target.nil?
+
+        target_representation_class = association.representation_class
+        return nil unless target_representation_class
+
+        nested_includes = @includes[name] || @includes[name.to_s] || @includes[name.to_sym] if @includes.is_a?(Hash)
+
+        if association.collection?
+          target.map { |record| serialize_variant_aware(record, target_representation_class, nested_includes) }
+        else
+          serialize_variant_aware(target, target_representation_class, nested_includes)
+        end
+      end
+
+      def serialize_variant_aware(record, target_representation_class, nested_includes)
+        if target_representation_class.inheritance&.subclasses&.any?
+          subclass_representation_class = target_representation_class.inheritance.resolve(record)
+        end
+        representation_class = subclass_representation_class || target_representation_class
+
+        representation_class.new(record, context: @representation.context, include: nested_includes).as_json
+      end
+
+      def include_association?(name, association)
+        return explicitly_included?(name) unless association.include == :always
+        return true unless circular_reference?(association)
+
+        false
+      end
+
+      def circular_reference?(association)
+        return false unless association.representation_class
+
+        association.representation_class.associations.values.any? do |nested_association|
+          nested_association.include == :always && nested_association.representation_class == @representation_class
+        end
+      end
+
+      def explicitly_included?(name)
+        return false if @includes.nil?
+
+        case @includes
+        when Symbol, String
+          @includes.to_sym == name
+        when Array
+          include_symbols.include?(name)
+        when Hash
+          name = name.to_sym
+          @includes.key?(name) || @includes.key?(name.to_s)
+        else
+          false
+        end
+      end
+
+      def include_symbols
+        @include_symbols ||= @includes.map(&:to_sym)
+      end
+    end
+  end
+end

data/lib/apiwork/request.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Apiwork
+  # @api public
+  # Immutable value object representing a request.
+  #
+  # Encapsulates query and body parameters. Transformations return
+  # new instances, preserving immutability.
+  #
+  # @example Creating a request
+  #   request = Request.new(query: { page: 1 }, body: { title: "Hello" })
+  #   request.query # => { page: 1 }
+  #   request.body # => { title: "Hello" }
+  #
+  # @example Transforming keys
+  #   request.transform { |data| normalize(data) }
+  class Request
+    # @!attribute [r] query
+    #   @api public
+    #   The query for this request.
+    #
+    #   @return [Hash]
+    # @!attribute [r] body
+    #   @api public
+    #   The body for this request.
+    #
+    #   @return [Hash]
+    attr_reader :body,
+                :query
+
+    # @api public
+    # Creates a new request context.
+    #
+    # @param body [Hash]
+    #   The body parameters.
+    # @param query [Hash]
+    #   The query parameters.
+    def initialize(body:, query:)
+      @query = query
+      @body = body
+    end
+
+    # @api public
+    # Transforms both query and body with the same block.
+    #
+    # @yield [Hash] each field (query, then body)
+    # @return [Request]
+    #
+    # @example
+    #   request.transform { |data| normalize(data) }
+    def transform
+      self.class.new(body: yield(body), query: yield(query))
+    end
+
+    # @api public
+    # Transforms only the query.
+    #
+    # @yield [Hash] the query parameters
+    # @return [Request]
+    #
+    # @example
+    #   request.transform_query { |query| normalize(query) }
+    def transform_query
+      self.class.new(body: body, query: yield(query))
+    end
+
+    # @api public
+    # Transforms only the body.
+    #
+    # @yield [Hash] the body parameters
+    # @return [Request]
+    #
+    # @example
+    #   request.transform_body { |body| prepare(body) }
+    def transform_body
+      self.class.new(body: yield(body), query: query)
+    end
+  end
+end

data/lib/apiwork/response.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Apiwork
+  # @api public
+  # Immutable value object representing a response.
+  #
+  # Encapsulates body parameters. Transformations return new instances,
+  # preserving immutability.
+  #
+  # @example Creating a response
+  #   response = Response.new(body: { id: 1, title: "Hello" })
+  #   response.body # => { id: 1, title: "Hello" }
+  #
+  # @example Transforming keys
+  #   response.transform { |data| camelize(data) }
+  class Response
+    # @api public
+    # The body for this response.
+    #
+    # @return [Hash]
+    attr_reader :body
+
+    # @api public
+    # Creates a new response context.
+    #
+    # @param body [Hash]
+    #   The body parameters.
+    def initialize(body:)
+      @body = body
+    end
+
+    # @api public
+    # Transforms the body parameters.
+    #
+    # @yield [Hash] the body parameters
+    # @return [Response]
+    #
+    # @example
+    #   response.transform { |data| camelize(data) }
+    def transform
+      self.class.new(body: yield(body))
+    end
+
+    # @api public
+    # Transforms the body parameters.
+    #
+    # @yield [Hash] the body parameters
+    # @return [Response]
+    #
+    # @example
+    #   response.transform_body { |data| camelize(data) }
+    def transform_body
+      self.class.new(body: yield(body))
+    end
+  end
+end