apiwork 0.0.0.pre → 0.1.2

data/lib/apiwork/configuration.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module Apiwork
+  # @api public
+  # Typed access to configuration values with automatic defaults.
+  #
+  # @see API::Base#adapter_config
+  # @see Representation::Base.adapter_config
+  #
+  # @example Reading values
+  #   config.pagination.default_size # => 20
+  #   config.pagination.strategy # => :offset
+  #
+  # @example Using dig for dynamic access
+  #   config.dig(:pagination, :default_size) # => 20
+  class Configuration
+    def initialize(options_source, storage = {})
+      @options = extract_options(options_source)
+      @storage = storage
+    end
+
+    def method_missing(name, *args, &block)
+      option = @options[name]
+      raise ConfigurationError, "Unknown option: #{name}" unless option
+
+      if args.empty? && !block
+        stored = @storage[name]
+
+        if option.nested?
+          nested_storage = stored || {}
+          return Configuration.new(option, nested_storage)
+        end
+
+        return stored.nil? ? option.default : stored
+      end
+
+      value = args.first
+      if block && option.nested?
+        @storage[name] ||= {}
+        nested = Configuration.new(option, @storage[name])
+        block.arity.positive? ? yield(nested) : nested.instance_eval(&block)
+      else
+        option.validate!(value)
+        @storage[name] = value
+      end
+    end
+
+    def respond_to_missing?(name, include_private = false)
+      @options.key?(name) || super
+    end
+
+    def merge(hash)
+      Configuration.new(@options, @storage.deep_merge(hash))
+    end
+
+    # @api public
+    # Accesses nested configuration values by key path.
+    #
+    # @param keys [Symbol]
+    #   One or more keys to traverse.
+    #
+    # @example
+    #   config.dig(:pagination) # => #<Apiwork::Configuration:...>
+    #   config.dig(:pagination, :strategy) # => :offset
+    def dig(*keys)
+      keys.compact.reduce(self) { |config, key| config.public_send(key) }
+    end
+
+    # @api public
+    # Converts the configuration to a hash.
+    #
+    # @return [Hash]
+    #
+    # @example
+    #   config.to_h # => { pagination: { strategy: :offset, default_size: 20 } }
+    def to_h
+      @options.each_with_object({}) do |(name, option), result|
+        if option.nested?
+          result[name] = Configuration.new(option, @storage[name] || {}).to_h
+        else
+          stored = @storage[name]
+          result[name] = stored.nil? ? option.default : stored
+        end
+      end
+    end
+
+    private
+
+    def extract_options(source)
+      return source if source.is_a?(Hash)
+
+      source.respond_to?(:options) ? source.options : source.children
+    end
+  end
+end

data/lib/apiwork/configuration_error.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Apiwork
+  class ConfigurationError < Error
+  end
+end

data/lib/apiwork/constraint_error.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Apiwork
+  class ConstraintError < Error
+    attr_reader :issues
+
+    def initialize(issues)
+      @issues = Array(issues)
+      super(@issues.map(&:detail).join('; '))
+    end
+
+    def error_code
+      @error_code ||= ErrorCode.find!(:bad_request)
+    end
+
+    def status
+      error_code.status
+    end
+  end
+end

data/lib/apiwork/contract/action/request.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module Contract
+    class Action
+      # @api public
+      # Defines query and body for a request.
+      #
+      # Returns {Contract::Object} via `query` and `body`.
+      class Request
+        attr_reader :action_name,
+                    :contract_class
+
+        def initialize(contract_class, action_name)
+          @contract_class = contract_class
+          @action_name = action_name
+          @query = nil
+          @body = nil
+        end
+
+        # @api public
+        # Defines query parameters for this request.
+        #
+        # Query parameters are parsed from the URL query string.
+        #
+        # @yield block for defining query params (instance_eval style)
+        # @yieldparam query [Contract::Object]
+        # @return [Contract::Object]
+        #
+        # @example instance_eval style
+        #   query do
+        #     integer? :page
+        #     string? :status, enum: :status
+        #   end
+        #
+        # @example yield style
+        #   query do |query|
+        #     query.integer? :page
+        #     query.string? :status, enum: :status
+        #   end
+        def query(&block)
+          @query ||= Object.new(@contract_class, action_name: @action_name)
+          if block
+            block.arity.positive? ? yield(@query) : @query.instance_eval(&block)
+          end
+          @query
+        end
+
+        # @api public
+        # Defines the request body for this request.
+        #
+        # Body is parsed from the JSON request body.
+        #
+        # @yield block for defining body params (instance_eval style)
+        # @yieldparam body [Contract::Object]
+        # @return [Contract::Object]
+        #
+        # @example instance_eval style
+        #   body do
+        #     string :title
+        #     decimal :amount
+        #   end
+        #
+        # @example yield style
+        #   body do |body|
+        #     body.string :title
+        #     body.decimal :amount
+        #   end
+        def body(&block)
+          @body ||= Object.new(@contract_class, action_name: @action_name)
+          if block
+            block.arity.positive? ? yield(@body) : @body.instance_eval(&block)
+          end
+          @body
+        end
+      end
+    end
+  end
+end

data/lib/apiwork/contract/action/response.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module Contract
+    class Action
+      # @api public
+      # Defines body for a response.
+      #
+      # Returns {Contract::Object} via `body`.
+      class Response
+        attr_reader :action_name,
+                    :contract_class
+
+        attr_accessor :result_wrapper
+
+        def initialize(contract_class, action_name)
+          @contract_class = contract_class
+          @action_name = action_name
+          @body = nil
+          @result_wrapper = nil
+          @no_content = false
+        end
+
+        # @api public
+        # Whether this response has no content.
+        #
+        # @return [Boolean]
+        def no_content?
+          @no_content
+        end
+
+        # @api public
+        # Declares this response as 204 No Content.
+        #
+        # Use for actions that don't return a response body,
+        # like DELETE or actions that only perform side effects.
+        #
+        # @return [void]
+        #
+        # @example
+        #   action :destroy do
+        #     response { no_content! }
+        #   end
+        #
+        # @example Archive action
+        #   action :archive do
+        #     response { no_content! }
+        #   end
+        def no_content!
+          @no_content = true
+        end
+
+        # @api public
+        # Defines the response body for this response.
+        #
+        # @yield block for defining body params (instance_eval style)
+        # @yieldparam body [Contract::Object]
+        # @return [Contract::Object]
+        #
+        # @example instance_eval style
+        #   body do
+        #     integer :id
+        #     string :title
+        #     decimal :amount
+        #   end
+        #
+        # @example yield style
+        #   body do |body|
+        #     body.integer :id
+        #     body.string :title
+        #     body.decimal :amount
+        #   end
+        def body(&block)
+          if block
+            @body ||= Object.new(
+              @contract_class,
+              action_name: @action_name,
+              wrapped: true,
+            )
+            block.arity.positive? ? yield(@body) : @body.instance_eval(&block)
+          end
+          @body
+        end
+      end
+    end
+  end
+end

data/lib/apiwork/contract/action.rb

@@ -0,0 +1,258 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module Contract
+    # @api public
+    # Defines request/response structure for an action.
+    #
+    # Returns {Action::Request} via `request` and {Action::Response} via `response`.
+    class Action
+      attr_reader :contract_class,
+                  :name
+
+      def initialize(contract_class, name, replace: false)
+        @name = name
+        @contract_class = contract_class
+        @reset_request = replace
+        @reset_response = replace
+        @request = nil
+        @response = nil
+        @raises = []
+        @summary = nil
+        @description = nil
+        @tags = nil
+        @deprecated = nil
+        @operation_id = nil
+      end
+
+      # @api public
+      # The summary for this action.
+      #
+      # Used in generated specs as the operation summary.
+      #
+      # @param value [String, nil] (nil)
+      #   The summary.
+      # @return [String, nil]
+      #
+      # @example
+      #   action :create do
+      #     summary 'Create a new invoice'
+      #   end
+      def summary(value = nil)
+        return @summary if value.nil?
+
+        @summary = value
+      end
+
+      # @api public
+      # The description for this action.
+      #
+      # Used in generated specs as the operation description.
+      # Supports Markdown formatting.
+      #
+      # @param value [String, nil] (nil)
+      #   The description.
+      # @return [String, nil]
+      #
+      # @example
+      #   action :create do
+      #     description 'Creates a new invoice and sends notification email.'
+      #   end
+      def description(value = nil)
+        return @description if value.nil?
+
+        @description = value
+      end
+
+      # @api public
+      # The tags for this action.
+      #
+      # Tags help organize actions in generated documentation.
+      #
+      # @param tags [Array<String, Symbol>]
+      #   The tag names.
+      # @return [Array<Symbol>, nil]
+      #
+      # @example
+      #   action :create do
+      #     tags :billing, :invoices
+      #   end
+      def tags(*tags)
+        @tags = tags.flatten if tags.any?
+        @tags
+      end
+
+      # @api public
+      # Marks this action as deprecated.
+      #
+      # @return [void]
+      #
+      # @example
+      #   action :legacy_create do
+      #     deprecated!
+      #   end
+      def deprecated!
+        @deprecated = true
+      end
+
+      # @api public
+      # Whether this action is deprecated.
+      #
+      # @return [Boolean]
+      def deprecated?
+        @deprecated == true
+      end
+
+      # @api public
+      # The operation ID for this action.
+      #
+      # @param value [String, nil] (nil)
+      #   The operation ID.
+      # @return [String, nil]
+      #
+      # @example
+      #   action :create do
+      #     operation_id 'createNewInvoice'
+      #   end
+      def operation_id(value = nil)
+        return @operation_id if value.nil?
+
+        @operation_id = value
+      end
+
+      # @api public
+      # Declares the raised error codes for this action.
+      #
+      # @param error_code_keys [Symbol]
+      #   The error code keys.
+      # @return [void]
+      # @raise [ConfigurationError] if error code is not registered
+      #
+      # @example
+      #   raises :not_found
+      #   raises :forbidden
+      #
+      # @example
+      #   action :show do
+      #     raises :not_found, :forbidden
+      #   end
+      def raises(*error_code_keys)
+        error_code_keys = error_code_keys.flatten
+        error_code_keys.each do |error_code_key|
+          unless error_code_key.is_a?(Symbol)
+            hint = error_code_key.is_a?(Integer) ? " Use :#{ErrorCode.key_for_status(error_code_key)} instead." : ''
+            raise ConfigurationError, "raises must be symbols, got #{error_code_key.class}: #{error_code_key}.#{hint}"
+          end
+
+          next if ErrorCode.exists?(error_code_key)
+
+          raise ConfigurationError,
+                "Unknown error code :#{error_code_key}. Register it with: " \
+                "Apiwork::ErrorCode.register :#{error_code_key}, status: <status>"
+        end
+        @raises |= error_code_keys
+      end
+
+      # @api public
+      # Defines the request structure for this action.
+      #
+      # Use the block to define query parameters and request body.
+      #
+      # @param replace [Boolean] (false)
+      #   Whether to replace inherited definition.
+      # @yield block for defining query and body (instance_eval style)
+      # @yieldparam request [Action::Request]
+      # @return [Action::Request]
+      #
+      # @example instance_eval style
+      #   action :create do
+      #     request do
+      #       query do
+      #         boolean? :dry_run
+      #       end
+      #       body do
+      #         string :title
+      #       end
+      #     end
+      #   end
+      #
+      # @example yield style
+      #   action :create do
+      #     request do |request|
+      #       request.query do |query|
+      #         query.boolean? :dry_run
+      #       end
+      #       request.body do |body|
+      #         body.string :title
+      #       end
+      #     end
+      #   end
+      def request(replace: false, &block)
+        @reset_request = replace if replace
+
+        @request ||= Request.new(contract_class, name)
+
+        if block
+          block.arity.positive? ? yield(@request) : @request.instance_eval(&block)
+        end
+
+        @request
+      end
+
+      # @api public
+      # Defines the response structure for this action.
+      #
+      # Use the block to define response body or declare no_content.
+      #
+      # @param replace [Boolean] (false)
+      #   Whether to replace inherited definition.
+      # @yield block for defining body or no_content (instance_eval style)
+      # @yieldparam response [Action::Response]
+      # @return [Action::Response]
+      #
+      # @example instance_eval style
+      #   action :show do
+      #     response do
+      #       body do
+      #         uuid :id
+      #         string :title
+      #       end
+      #     end
+      #   end
+      #
+      # @example yield style
+      #   action :show do
+      #     response do |response|
+      #       response.body do |body|
+      #         body.uuid :id
+      #         body.string :title
+      #       end
+      #     end
+      #   end
+      #
+      # @example No content response
+      #   action :destroy do
+      #     response { no_content! }
+      #   end
+      def response(replace: false, &block)
+        @reset_response = replace if replace
+
+        @response ||= Response.new(contract_class, name)
+
+        if block
+          block.arity.positive? ? yield(@response) : @response.instance_eval(&block)
+        end
+
+        @response
+      end
+
+      def resets_request?
+        @reset_request
+      end
+
+      def resets_response?
+        @reset_response
+      end
+    end
+  end
+end