apiwork 0.0.0.pre → 0.1.1

data/lib/apiwork/adapter/builder/contract/base.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module Adapter
+    module Builder
+      module Contract
+        # @api public
+        # Base class for Contract-phase type builders.
+        #
+        # Contract phase runs once per contract with representation at registration time.
+        # Use it to generate contract-specific types based on the representation.
+        #
+        # @example
+        #   module Builder
+        #     class Contract < Adapter::Builder::Contract::Base
+        #       def build
+        #         object(representation_class.root_key.singular.to_sym) do |object|
+        #           object.string(:id)
+        #           object.string(:name)
+        #         end
+        #       end
+        #     end
+        #   end
+        class Base
+          attr_reader :representation_class
+
+          # @!method api_class
+          #   @api public
+          #   @see Contract::Base.api_class
+          # @!method enum(name, values:, **options, &block)
+          #   @api public
+          #   @see Contract::Base#enum
+          # @!method enum?(name)
+          #   @api public
+          #   @see Contract::Base#enum?
+          # @!method contract_for(representation_class)
+          #   @api public
+          #   @see Contract::Base.contract_for
+          # @!method import(type_name, from:)
+          #   @api public
+          #   @see Contract::Base#import
+          # @!method object(name, **options, &block)
+          #   @api public
+          #   @see Contract::Base#object
+          # @!method scoped_enum_name(name)
+          #   @api public
+          #   @see Contract::Base#scoped_enum_name
+          # @!method scoped_type_name(name)
+          #   @api public
+          #   @see Contract::Base#scoped_type_name
+          # @!method type?(name)
+          #   @api public
+          #   @see Contract::Base#type?
+          # @!method union(name, **options, &block)
+          #   @api public
+          #   @see Contract::Base#union
+          delegate :api_class,
+                   :contract_for,
+                   :enum,
+                   :enum?,
+                   :import,
+                   :object,
+                   :scoped_enum_name,
+                   :scoped_type_name,
+                   :type?,
+                   :union,
+                   to: :@contract_class
+
+          def initialize(contract_class, representation_class)
+            @contract_class = contract_class
+            @representation_class = representation_class
+          end
+
+          # @api public
+          # Builds contract-level types.
+          #
+          # Override this method to generate types based on the representation.
+          # @return [void]
+          def build
+            raise NotImplementedError
+          end
+        end
+      end
+    end
+  end
+end

data/lib/apiwork/adapter/capability/api/base.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module Adapter
+    module Capability
+      module API
+        # @api public
+        # Base class for capability API builders.
+        #
+        # Provides access to capability options and aggregated configuration
+        # across all representations.
+        class Base < Builder::API::Base
+          # @!attribute [r] scope
+          #   @api public
+          #   The scope for this API.
+          #
+          #   @return [Scope]
+          # @!attribute [r] options
+          #   @api public
+          #   The options for this API.
+          #
+          #   @return [Configuration]
+          attr_reader :options,
+                      :scope
+
+          def initialize(api_class, capability_name: nil, options: nil)
+            super(api_class)
+            @capability_name = capability_name
+            @scope = Scope.new(api_class)
+            @options = options
+          end
+
+          # @api public
+          # The configured values for a key.
+          #
+          # @param key [Symbol]
+          #   The configuration key.
+          # @return [Set]
+          #
+          # @example Check if any representation uses cursor pagination
+          #   if configured(:strategy).include?(:cursor)
+          #     # build cursor pagination schema
+          #   end
+          def configured(key)
+            scope.configured(@capability_name, key)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/apiwork/adapter/capability/api/scope.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module Adapter
+    module Capability
+      module API
+        # @api public
+        # Aggregated scope for capability API builders.
+        #
+        # Provides access to data collected across all representations in the API.
+        # Use this to query API-wide state when building shared types.
+        class Scope
+          def initialize(api_class)
+            @representation_registry = api_class.representation_registry
+            @root_resource = api_class.root_resource
+          end
+
+          # @!method index_actions?
+          #   @api public
+          #   Returns whether any resource has index actions.
+          #   @return [Boolean]
+          delegate :index_actions?, to: :@root_resource
+
+          # @!method filter_types
+          #   @api public
+          #   Returns all filterable types across representations.
+          #   @return [Set<Symbol>]
+          #
+          # @!method nullable_filter_types
+          #   @api public
+          #   Returns filterable types that can be null.
+          #   @return [Set<Symbol>]
+          #
+          # @!method filterable?
+          #   @api public
+          #   Returns whether any representation has filterable attributes.
+          #   @return [Boolean]
+          #
+          # @!method sortable?
+          #   @api public
+          #   Returns whether any representation has sortable attributes.
+          #   @return [Boolean]
+          delegate :filter_types,
+                   :filterable?,
+                   :nullable_filter_types,
+                   :sortable?,
+                   to: :@representation_registry
+
+          # @api public
+          # The configured values for a capability.
+          #
+          # @param capability [Symbol]
+          #   The capability name.
+          # @param key [Symbol]
+          #   The configuration key.
+          # @return [Set]
+          def configured(capability, key)
+            @representation_registry.options_for(capability, key)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,291 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module Adapter
+    module Capability
+      # @api public
+      # Base class for adapter capabilities.
+      #
+      # A capability encapsulates a specific feature (filtering, pagination, sorting)
+      # with its own configuration, transformers, builders, and operations. While each
+      # capability is self-contained, all capabilities operate on the same response data
+      # in sequence, so their effects combine.
+      #
+      # @see Adapter::Base#capability
+      # @see Configurable#option
+      #
+      # @example Filtering capability
+      #   class Filtering < Adapter::Capability::Base
+      #     capability_name :filtering
+      #
+      #     option :strategy, type: :symbol, default: :simple
+      #
+      #     request_transformer RequestTransformer
+      #     api_builder APIBuilder
+      #     contract_builder ContractBuilder
+      #     operation Operation
+      #   end
+      class Base
+        include Configurable
+
+        class_attribute :_api_builder
+        class_attribute :_api_builder_block
+        class_attribute :_contract_builder
+        class_attribute :_contract_builder_block
+        class_attribute :_operation_class
+        class_attribute :_operation_block
+
+        class << self
+          # @api public
+          # The name for this capability.
+          #
+          # Used for configuration options, translation keys, and {Adapter::Base.skip_capability}.
+          #
+          # @param value [Symbol, nil] (nil)
+          #   The capability name.
+          # @return [Symbol, nil]
+          def capability_name(value = nil)
+            @capability_name = value.to_sym if value
+            @capability_name
+          end
+
+          # @api public
+          # Registers a request transformer for this capability.
+          #
+          # @param transformer_class [Class<Transformer::Request::Base>]
+          #   The transformer class.
+          # @return [void]
+          # @see Transformer::Request::Base
+          def request_transformer(transformer_class)
+            @request_transformers ||= []
+            @request_transformers << transformer_class
+          end
+
+          # @api public
+          # Registers a response transformer for this capability.
+          #
+          # @param transformer_class [Class<Transformer::Response::Base>]
+          #   The transformer class.
+          # @return [void]
+          # @see Transformer::Response::Base
+          def response_transformer(transformer_class)
+            @response_transformers ||= []
+            @response_transformers << transformer_class
+          end
+
+          # @api public
+          # Registers an API builder for this capability.
+          #
+          # API builders run once per API at initialization time to register
+          # shared types used across all contracts.
+          #
+          # @param klass [Class<Builder::API::Base>, nil] (nil)
+          #   The builder class.
+          # @yield block evaluated in {Builder::API::Base} context
+          # @return [void]
+          # @see Builder::API::Base
+          def api_builder(klass = nil, &block)
+            if klass
+              self._api_builder = klass
+            elsif block
+              self._api_builder_block = block
+            end
+          end
+
+          # @api public
+          # Registers a contract builder for this capability.
+          #
+          # Contract builders run per contract to add capability-specific
+          # parameters and response shapes.
+          #
+          # @param klass [Class<Builder::Contract::Base>, nil] (nil)
+          #   The builder class.
+          # @yield block evaluated in {Builder::Contract::Base} context
+          # @return [void]
+          # @see Builder::Contract::Base
+          def contract_builder(klass = nil, &block)
+            if klass
+              self._contract_builder = klass
+            elsif block
+              self._contract_builder_block = block
+            end
+          end
+
+          # @api public
+          # Registers an operation for this capability.
+          #
+          # Operations run at request time to process data based on
+          # request parameters.
+          #
+          # @param klass [Class<Operation::Base>, nil] (nil)
+          #   The operation class.
+          # @yield block evaluated in {Operation::Base} context
+          # @return [void]
+          # @see Operation::Base
+          def operation(klass = nil, &block)
+            if klass
+              self._operation_class = klass
+            elsif block
+              self._operation_block = block
+            end
+          end
+
+          def request_transformers
+            @request_transformers || []
+          end
+
+          def response_transformers
+            @response_transformers || []
+          end
+
+          def wrap_api_builder_block(callable)
+            Class.new(Builder::API::Base) do
+              define_method(:build) do
+                callable.arity.positive? ? callable.call(self) : instance_exec(&callable)
+              end
+            end
+          end
+
+          def wrap_contract_builder_block(callable)
+            Class.new(Builder::Contract::Base) do
+              define_method(:build) do
+                callable.arity.positive? ? callable.call(self) : instance_exec(&callable)
+              end
+            end
+          end
+
+          def wrap_operation_block(callable)
+            Class.new(Operation::Base) do
+              define_method(:apply) do
+                callable.arity.positive? ? callable.call(self) : instance_exec(&callable)
+              end
+            end
+          end
+
+          def api_builder_class
+            return _api_builder if _api_builder
+            return wrap_api_builder_block(_api_builder_block) if _api_builder_block
+
+            nil
+          end
+
+          def contract_builder_class
+            return _contract_builder if _contract_builder
+            return wrap_contract_builder_block(_contract_builder_block) if _contract_builder_block
+
+            nil
+          end
+
+          def operation_class
+            return _operation_class if _operation_class
+            return wrap_operation_block(_operation_block) if _operation_block
+
+            nil
+          end
+        end
+
+        attr_reader :adapter_name,
+                    :config
+
+        def initialize(config = {}, adapter_name: nil)
+          merged = self.class.default_options.deep_merge(config)
+          @config = Configuration.new(self.class, merged)
+          @adapter_name = adapter_name
+        end
+
+        def api_types(api_class)
+          builder_class = self.class.api_builder_class
+          return unless builder_class
+
+          builder_class.new(
+            api_class,
+            capability_name: self.class.capability_name,
+            options: config,
+          ).build
+        end
+
+        def contract_types(contract_class, representation_class, actions)
+          builder_class = self.class.contract_builder_class
+          return unless builder_class
+
+          builder_class.new(contract_class, representation_class, actions, merged_config(representation_class)).build
+        end
+
+        def shape(representation_class, type)
+          klass = self.class.operation_class
+          return nil unless klass
+
+          metadata_shape_class = klass.metadata_shape
+          return nil unless metadata_shape_class
+
+          scope = klass.target
+          return nil if scope && scope != type
+
+          object = ::Apiwork::API::Object.new
+          metadata_shape_class.apply(object, merged_config(representation_class))
+          return nil if object.params.empty?
+
+          type_name = resolve_metadata_type_name(representation_class)
+          register_metadata_fragment(
+            representation_class.api_class,
+            type_name,
+            metadata_shape_class,
+            merged_config(representation_class),
+          )
+          type_name
+        end
+
+        def apply(data, representation_class, request, wrapper_type:)
+          klass = self.class.operation_class
+          return Result.new(data:) unless klass
+
+          scope = klass.target
+          return Result.new(data:) if scope && scope != wrapper_type
+
+          klass.new(
+            data,
+            representation_class,
+            merged_config(representation_class),
+            request,
+            translation_context: build_translation_context(representation_class),
+          ).apply
+        end
+
+        private
+
+        def merged_config(representation_class)
+          capability_name = self.class.capability_name
+          return config unless capability_name
+
+          representation_config = representation_class.adapter_config.public_send(capability_name).to_h
+          config.merge(representation_config)
+        rescue ConfigurationError
+          config
+        end
+
+        def resolve_metadata_type_name(representation_class)
+          prefix = representation_class.name.demodulize.delete_suffix('Representation').underscore
+          [prefix, self.class.capability_name, 'metadata'].join('_').to_sym
+        end
+
+        def register_metadata_fragment(api_class, type_name, metadata_shape_class, config)
+          return if api_class.type_registry.key?(type_name)
+
+          api_class.type_registry.register(type_name, fragment: true, kind: :object) do |shape|
+            metadata_shape_class.apply(shape, config)
+          end
+        end
+
+        def build_translation_context(representation_class)
+          locale_key = representation_class.api_class.locale_key
+
+          {
+            locale_key:,
+            adapter_name: adapter_name,
+            capability_name: self.class.capability_name,
+          }
+        end
+      end
+    end
+  end
+end

data/lib/apiwork/adapter/capability/contract/base.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module Adapter
+    module Capability
+      module Contract
+        # @api public
+        # Base class for capability Contract phase.
+        #
+        # Contract phase runs once per contract with representation at registration time.
+        # Use it to generate contract-specific types based on the representation.
+        class Base < Builder::Contract::Base
+          # @!attribute [r] scope
+          #   @api public
+          #   The scope for this contract.
+          #
+          #   @return [Scope]
+          # @!attribute [r] options
+          #   @api public
+          #   The options for this contract.
+          #
+          #   @return [Configuration]
+          attr_reader :options,
+                      :scope
+
+          delegate :action, to: :@contract_class
+
+          def initialize(contract_class, representation_class, actions, options)
+            super(contract_class, representation_class)
+            @scope = Scope.new(representation_class, actions)
+            @options = options
+          end
+        end
+      end
+    end
+  end
+end

data/lib/apiwork/adapter/capability/contract/scope.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module Adapter
+    module Capability
+      module Contract
+        # @api public
+        # Scope for capability contract builders.
+        #
+        # Provides access to the representation and actions for this contract.
+        # Use this to query contract-specific state when building types.
+        class Scope
+          # @api public
+          # The actions for this scope.
+          #
+          # @return [Hash{Symbol => Resource::Action}]
+          attr_reader :actions
+
+          attr_reader :representation_class
+
+          def initialize(representation_class, actions)
+            @representation_class = representation_class
+            @actions = actions
+          end
+
+          # @api public
+          # The collection actions for this scope.
+          #
+          # @return [Hash{Symbol => Resource::Action}]
+          def collection_actions
+            @collection_actions ||= actions.select { |_name, action| action.collection? }
+          end
+
+          # @api public
+          # The member actions for this scope.
+          #
+          # @return [Hash{Symbol => Resource::Action}]
+          def member_actions
+            @member_actions ||= actions.select { |_name, action| action.member? }
+          end
+
+          # @api public
+          # The CRUD actions for this scope.
+          #
+          # @return [Hash{Symbol => Resource::Action}]
+          def crud_actions
+            @crud_actions ||= actions.select { |_name, action| action.crud? }
+          end
+
+          # @api public
+          # Whether this scope includes the given action.
+          #
+          # @param name [Symbol]
+          #   The action name.
+          # @return [Boolean]
+          def action?(name)
+            actions.key?(name.to_sym)
+          end
+
+          # @api public
+          # The filterable attributes for this scope.
+          #
+          # @return [Array<Representation::Attribute>]
+          def filterable_attributes
+            @filterable_attributes ||= attributes.values.select(&:filterable?)
+          end
+
+          # @api public
+          # The sortable attributes for this scope.
+          #
+          # @return [Array<Representation::Attribute>]
+          def sortable_attributes
+            @sortable_attributes ||= attributes.values.select(&:sortable?)
+          end
+
+          # @api public
+          # The writable attributes for this scope.
+          #
+          # @return [Array<Representation::Attribute>]
+          def writable_attributes
+            @writable_attributes ||= attributes.values.select(&:writable?)
+          end
+
+          # @!method associations
+          #   @api public
+          #   The associations for this scope.
+          #
+          #   @return [Hash{Symbol => Representation::Association}]
+          #
+          # @!method attributes
+          #   @api public
+          #   The attributes for this scope.
+          #
+          #   @return [Hash{Symbol => Representation::Attribute}]
+          #
+          # @!method root_key
+          #   @api public
+          #   The root key for this scope.
+          #
+          #   @return [Representation::RootKey]
+          delegate :adapter_config,
+                   :associations,
+                   :attributes,
+                   :root_key,
+                   to: :representation_class
+        end
+      end
+    end
+  end
+end