apiwork 0.0.0.pre → 0.1.1

data/lib/apiwork/adapter/standard/includes_resolver.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module Adapter
+    class Standard
+      class IncludesResolver
+        attr_reader :representation_class
+
+        class << self
+          def resolve(representation_class, params = {}, include_always: false)
+            new(representation_class).resolve(params, include_always:)
+          end
+        end
+
+        def initialize(representation_class)
+          @representation_class = representation_class
+        end
+
+        def resolve(params = {}, include_always: false)
+          base = include_always ? always_included : {}
+          merged = merge(base, from_params(params))
+          format(merged)
+        end
+
+        def always_included(visited = Set.new)
+          associations = representation_class.associations.select { |_, a| a.include == :always }
+          extract_associations(associations, visited)
+        end
+
+        def from_params(params, visited = Set.new)
+          extract_from_hash(params, visited)
+        end
+
+        def merge(base, override)
+          return base if override.blank?
+
+          base.deep_merge(override.deep_symbolize_keys)
+        end
+
+        def format(hash)
+          return [] if hash.blank?
+
+          result = hash.map do |key, value|
+            if value.blank?
+              key
+            else
+              { key => format(value) }
+            end
+          end
+
+          result.size == 1 ? result.first : result
+        end
+
+        private
+
+        def extract_associations(associations, visited = Set.new)
+          return {} if visited.include?(representation_class.name)
+
+          visited = visited.dup.add(representation_class.name)
+
+          associations.transform_values do |association|
+            if association.representation_class
+              self.class.new(association.representation_class).always_included(visited)
+            else
+              {}
+            end
+          end
+        end
+
+        def extract_from_hash(hash, visited = Set.new)
+          return {} if hash.blank?
+          return {} if visited.include?(representation_class.name)
+
+          visited_with_current = visited.dup.add(representation_class.name)
+
+          if hash.is_a?(Array)
+            return hash.each_with_object({}) do |item, result|
+              result.deep_merge!(extract_from_hash(item, visited))
+            end
+          end
+
+          hash.each_with_object({}) do |(key, value), result|
+            key = key.to_sym
+
+            if [Capability::Filtering::Constants::OR, Capability::Filtering::Constants::AND].include?(key) && value.is_a?(Array)
+              value.each { |item| result.deep_merge!(extract_from_hash(item, visited)) }
+              next
+            elsif key == Capability::Filtering::Constants::NOT && value.is_a?(Hash)
+              result.deep_merge!(extract_from_hash(value, visited))
+              next
+            end
+
+            association = representation_class.associations[key]
+            next unless association
+
+            result[key] = if value.is_a?(Hash) && association.representation_class.respond_to?(:associations)
+                            self.class.new(association.representation_class).from_params(value, visited_with_current)
+                          else
+                            {}
+                          end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/apiwork/adapter/standard.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module Adapter
+    class Standard < Base
+      adapter_name :standard
+
+      resource_serializer Serializer::Resource::Default
+      error_serializer Serializer::Error::Default
+
+      member_wrapper Wrapper::Member::Default
+      collection_wrapper Wrapper::Collection::Default
+      error_wrapper Wrapper::Error::Default
+
+      capability Capability::Filtering
+      capability Capability::Including
+      capability Capability::Pagination
+      capability Capability::Sorting
+      capability Capability::Writing
+    end
+  end
+end

data/lib/apiwork/adapter/wrapper/base.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module Adapter
+    module Wrapper
+      class Base
+        class_attribute :shape_class
+        class_attribute :wrapper_type
+
+        # @api public
+        # The data for this wrapper.
+        #
+        # @return [Hash]
+        attr_reader :data
+
+        class << self
+          # @api public
+          # Defines the response shape for contract generation.
+          #
+          # @param klass_or_callable [Class<Shape>, Proc, nil] (nil)
+          #   A {Shape} subclass or callable.
+          # @yield block that defines the shape using the Shape DSL
+          # @return [Class<Shape>, nil]
+          def shape(klass_or_callable = nil, &block)
+            callable = block || klass_or_callable
+
+            if callable
+              self.shape_class = if callable.respond_to?(:call)
+                                   wrap_callable(callable)
+                                 else
+                                   callable
+                                 end
+            end
+
+            shape_class
+          end
+
+          def wrap(...)
+            new(...).wrap
+          end
+
+          private
+
+          def wrap_callable(callable)
+            Class.new(Shape) do
+              define_singleton_method(:callable) { callable }
+
+              def apply
+                block = self.class.callable
+                block.arity.positive? ? block.call(self) : instance_exec(&block)
+              end
+            end
+          end
+        end
+
+        def initialize(data)
+          @data = data
+        end
+
+        # @api public
+        # Transforms the data into the final response format.
+        #
+        # @return [Hash]
+        def wrap
+          raise NotImplementedError
+        end
+      end
+    end
+  end
+end

data/lib/apiwork/adapter/wrapper/collection/base.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module Adapter
+    module Wrapper
+      module Collection
+        # @api public
+        # Base class for collection response wrappers.
+        #
+        # Collection wrappers structure responses for index actions that return
+        # multiple records. Extend this class to customize how collections are
+        # wrapped in your API responses.
+        #
+        # @example Custom collection wrapper
+        #   class MyCollectionWrapper < Wrapper::Collection::Base
+        #     shape do
+        #       array(root_key.plural.to_sym) do |array|
+        #         array.reference(data_type)
+        #       end
+        #       object?(:meta)
+        #       metadata_type_names.each { |type_name| merge(type_name) }
+        #     end
+        #
+        #     def wrap
+        #       { root_key.plural.to_sym => data, meta: meta.presence, **metadata }.compact
+        #     end
+        #   end
+        class Base < Wrapper::Base
+          self.wrapper_type = :collection
+
+          # @!attribute [r] meta
+          #   @api public
+          #   The meta for this wrapper.
+          #
+          #   @return [Hash]
+          # @!attribute [r] metadata
+          #   @api public
+          #   The metadata for this wrapper.
+          #
+          #   @return [Hash]
+          # @!attribute [r] root_key
+          #   @api public
+          #   The root key for this wrapper.
+          #
+          #   @return [RootKey]
+          attr_reader :meta,
+                      :metadata,
+                      :root_key
+
+          def initialize(data, metadata, root_key, meta)
+            super(data)
+            @metadata = metadata
+            @root_key = root_key
+            @meta = meta
+          end
+        end
+      end
+    end
+  end
+end

data/lib/apiwork/adapter/wrapper/collection/default.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module Adapter
+    module Wrapper
+      module Collection
+        # @api public
+        # Default collection response wrapper.
+        #
+        # Wraps serialized records under a pluralized root key with optional meta and capability metadata.
+        #
+        # @example Configuration
+        #   class MyAdapter < Adapter::Base
+        #     collection_wrapper Wrapper::Collection::Default
+        #   end
+        #
+        # @example Output
+        #   {
+        #     "invoices": [
+        #       { "id": 1, "number": "INV-001" },
+        #       { "id": 2, "number": "INV-002" }
+        #     ],
+        #     "meta": { ... },
+        #     "pagination": { "current": 1, "total": 5 }
+        #   }
+        class Default < Base
+          shape do
+            array(root_key.plural.to_sym) do |array|
+              array.reference(data_type)
+            end
+
+            object?(:meta)
+            metadata_type_names.each { |type_name| merge(type_name) }
+          end
+
+          def wrap
+            {
+              root_key.plural.to_sym => data,
+              meta: meta.presence,
+              **metadata,
+            }.compact
+          end
+        end
+      end
+    end
+  end
+end

data/lib/apiwork/adapter/wrapper/error/base.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module Adapter
+    module Wrapper
+      module Error
+        # @api public
+        # Base class for error response wrappers.
+        #
+        # Error wrappers structure responses for validation errors and other
+        # error conditions. Extend this class to customize how errors are
+        # wrapped in your API responses.
+        #
+        # @example Custom error wrapper
+        #   class MyErrorWrapper < Wrapper::Error::Base
+        #     shape do
+        #       extends(data_type)
+        #     end
+        #
+        #     def wrap
+        #       data
+        #     end
+        #   end
+        class Base < Wrapper::Base
+          self.wrapper_type = :error
+        end
+      end
+    end
+  end
+end

data/lib/apiwork/adapter/wrapper/error/default.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module Adapter
+    module Wrapper
+      module Error
+        # @api public
+        # Default error response wrapper.
+        #
+        # Passes serialized error data through unchanged.
+        #
+        # @example Configuration
+        #   class MyAdapter < Adapter::Base
+        #     error_wrapper Wrapper::Error::Default
+        #   end
+        #
+        # @example Output
+        #   {
+        #     "issues": [{ "code": "blank", "detail": "can't be blank", ... }],
+        #     "layer": "domain"
+        #   }
+        class Default < Base
+          shape do
+            extends(data_type)
+          end
+
+          def wrap
+            data
+          end
+        end
+      end
+    end
+  end
+end

data/lib/apiwork/adapter/wrapper/member/base.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module Adapter
+    module Wrapper
+      module Member
+        # @api public
+        # Base class for member response wrappers.
+        #
+        # Member wrappers structure responses for show, create, and update actions
+        # that return a single record. Extend this class to customize how individual
+        # resources are wrapped in your API responses.
+        #
+        # @example Custom member wrapper
+        #   class MyMemberWrapper < Wrapper::Member::Base
+        #     shape do
+        #       reference(root_key.singular.to_sym, to: data_type)
+        #       object?(:meta)
+        #       metadata_type_names.each { |type_name| merge(type_name) }
+        #     end
+        #
+        #     def wrap
+        #       { root_key.singular.to_sym => data, meta: meta.presence, **metadata }.compact
+        #     end
+        #   end
+        class Base < Wrapper::Base
+          self.wrapper_type = :member
+
+          # @!attribute [r] meta
+          #   @api public
+          #   The meta for this wrapper.
+          #
+          #   @return [Hash]
+          # @!attribute [r] metadata
+          #   @api public
+          #   The metadata for this wrapper.
+          #
+          #   @return [Hash]
+          # @!attribute [r] root_key
+          #   @api public
+          #   The root key for this wrapper.
+          #
+          #   @return [RootKey]
+          attr_reader :meta,
+                      :metadata,
+                      :root_key
+
+          def initialize(data, metadata, root_key, meta)
+            super(data)
+            @metadata = metadata
+            @root_key = root_key
+            @meta = meta
+          end
+        end
+      end
+    end
+  end
+end

data/lib/apiwork/adapter/wrapper/member/default.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module Adapter
+    module Wrapper
+      module Member
+        # @api public
+        # Default member response wrapper.
+        #
+        # Wraps a serialized record under a singular root key with optional meta and capability metadata.
+        #
+        # @example Configuration
+        #   class MyAdapter < Adapter::Base
+        #     member_wrapper Wrapper::Member::Default
+        #   end
+        #
+        # @example Output
+        #   {
+        #     "invoice": { "id": 1, "number": "INV-001" },
+        #     "meta": { ... }
+        #   }
+        class Default < Base
+          shape do
+            reference(root_key.singular.to_sym, to: data_type)
+            object?(:meta)
+            metadata_type_names.each { |type_name| merge(type_name) }
+          end
+
+          def wrap
+            {
+              root_key.singular.to_sym => data,
+              meta: meta.presence,
+              **metadata,
+            }.compact
+          end
+        end
+      end
+    end
+  end
+end

data/lib/apiwork/adapter/wrapper/shape.rb

@@ -0,0 +1,203 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module Adapter
+    module Wrapper
+      # @api public
+      # Base class for wrapper shapes.
+      #
+      # Subclass to define response type structure for record or collection wrappers.
+      # The block is evaluated via instance_exec, providing access to type DSL methods
+      # and helpers like root_key and {#metadata_type_names}.
+      #
+      # @example Custom shape class
+      #   class MyShape < Wrapper::Shape
+      #     def apply
+      #       reference(:invoice)
+      #       object?(:meta)
+      #       metadata_type_names.each { |type_name| merge(type_name) }
+      #     end
+      #   end
+      #
+      # @example Inline shape block
+      #   shape do
+      #     reference(root_key.singular.to_sym)
+      #     object?(:meta)
+      #     metadata_type_names.each { |type_name| merge(type_name) }
+      #   end
+      class Shape
+        class << self
+          def apply(target, root_key, capabilities, representation_class, type, data_type: nil)
+            metadata_type_names = build_metadata_type_names(capabilities, representation_class, type)
+            new(target, root_key, metadata_type_names, data_type:).apply
+          end
+
+          private
+
+          def build_metadata_type_names(capabilities, representation_class, type)
+            capabilities.filter_map { |capability| capability.shape(representation_class, type) }
+          end
+        end
+
+        # @!attribute [r] data_type
+        #   @api public
+        #   The data type for this shape.
+        #
+        #   @return [Symbol, nil]
+        # @!attribute [r] metadata_type_names
+        #   @api public
+        #   The metadata type names for this shape.
+        #
+        #   Auto-generated type names from capability {Adapter::Capability::Operation::Base.metadata_shape}
+        #   definitions. Use with {#merge} to include capability metadata fields in the shape.
+        #
+        #   @return [Array<Symbol>]
+        # @!attribute [r] root_key
+        #   @api public
+        #   The root key for this shape.
+        #
+        #   @return [RootKey]
+        attr_reader :data_type,
+                    :metadata_type_names,
+                    :root_key
+
+        # @!method array(name, **options, &block)
+        #   @api public
+        #   @see API::Object#array
+        # @!method array?(name, **options, &block)
+        #   @api public
+        #   @see API::Object#array?
+        # @!method binary(name, **options)
+        #   @api public
+        #   @see API::Object#binary
+        # @!method binary?(name, **options)
+        #   @api public
+        #   @see API::Object#binary?
+        # @!method boolean(name, **options)
+        #   @api public
+        #   @see API::Object#boolean
+        # @!method boolean?(name, **options)
+        #   @api public
+        #   @see API::Object#boolean?
+        # @!method date(name, **options)
+        #   @api public
+        #   @see API::Object#date
+        # @!method date?(name, **options)
+        #   @api public
+        #   @see API::Object#date?
+        # @!method datetime(name, **options)
+        #   @api public
+        #   @see API::Object#datetime
+        # @!method datetime?(name, **options)
+        #   @api public
+        #   @see API::Object#datetime?
+        # @!method decimal(name, **options)
+        #   @api public
+        #   @see API::Object#decimal
+        # @!method decimal?(name, **options)
+        #   @api public
+        #   @see API::Object#decimal?
+        # @!method extends(type)
+        #   @api public
+        #   @see API::Object#extends
+        # @!method integer(name, **options)
+        #   @api public
+        #   @see API::Object#integer
+        # @!method integer?(name, **options)
+        #   @api public
+        #   @see API::Object#integer?
+        # @!method literal(name, value:, **options)
+        #   @api public
+        #   @see API::Object#literal
+        # @!method merge(other)
+        #   @api public
+        #   @see API::Object#merge
+        # @!method number(name, **options)
+        #   @api public
+        #   @see API::Object#number
+        # @!method number?(name, **options)
+        #   @api public
+        #   @see API::Object#number?
+        # @!method object(name, **options, &block)
+        #   @api public
+        #   @see API::Object#object
+        # @!method object?(name, **options, &block)
+        #   @api public
+        #   @see API::Object#object?
+        # @!method reference(name, **options)
+        #   @api public
+        #   @see API::Object#reference
+        # @!method reference?(name, **options)
+        #   @api public
+        #   @see API::Object#reference?
+        # @!method string(name, **options)
+        #   @api public
+        #   @see API::Object#string
+        # @!method string?(name, **options)
+        #   @api public
+        #   @see API::Object#string?
+        # @!method time(name, **options)
+        #   @api public
+        #   @see API::Object#time
+        # @!method time?(name, **options)
+        #   @api public
+        #   @see API::Object#time?
+        # @!method union(name, **options, &block)
+        #   @api public
+        #   @see API::Object#union
+        # @!method union?(name, **options, &block)
+        #   @api public
+        #   @see API::Object#union?
+        # @!method uuid(name, **options)
+        #   @api public
+        #   @see API::Object#uuid
+        # @!method uuid?(name, **options)
+        #   @api public
+        #   @see API::Object#uuid?
+        delegate :array,
+                 :array?,
+                 :binary,
+                 :binary?,
+                 :boolean,
+                 :boolean?,
+                 :date,
+                 :date?,
+                 :datetime,
+                 :datetime?,
+                 :decimal,
+                 :decimal?,
+                 :extends,
+                 :integer,
+                 :integer?,
+                 :literal,
+                 :merge,
+                 :number,
+                 :number?,
+                 :object,
+                 :object?,
+                 :reference,
+                 :reference?,
+                 :string,
+                 :string?,
+                 :time,
+                 :time?,
+                 :union,
+                 :union?,
+                 :uuid,
+                 :uuid?,
+                 to: :@target
+
+        def initialize(target, root_key, metadata_type_names, data_type: nil)
+          @target = target
+          @root_key = root_key
+          @metadata_type_names = metadata_type_names
+          @data_type = data_type
+        end
+
+        def apply
+          raise NotImplementedError
+        end
+      end
+    end
+  end
+end