apiwork 0.0.0.pre → 0.1.1

data/lib/apiwork/introspection/param/uuid.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module Introspection
+    module Param
+      # @api public
+      # UUID param representing universally unique identifier values.
+      #
+      # @example Basic usage
+      #   param.type # => :uuid
+      #   param.scalar? # => true
+      #   param.uuid? # => true
+      #
+      # @example Capabilities
+      #   param.formattable? # => false
+      #
+      # @example Enum
+      #   if param.enum?
+      #     param.enum # => ["550e8400-e29b-41d4-a716-446655440000"]
+      #     param.enum_reference? # => false
+      #   end
+      class UUID < Base
+        # @api public
+        # Whether this param is scalar.
+        #
+        # @return [Boolean]
+        def scalar?
+          true
+        end
+
+        # @api public
+        # Whether this param has an enum.
+        #
+        # @return [Boolean]
+        def enum?
+          @dump[:enum].present?
+        end
+
+        # @api public
+        # The enum for this param.
+        #
+        # @return [Array<String>, Symbol, nil]
+        def enum
+          @dump[:enum]
+        end
+
+        # @api public
+        # Whether this param is an enum reference.
+        #
+        # @return [Boolean]
+        def enum_reference?
+          @dump[:enum].is_a?(Symbol)
+        end
+
+        # @api public
+        # Whether this param is a UUID.
+        #
+        # @return [Boolean]
+        def uuid?
+          true
+        end
+
+        # @api public
+        # Whether this param is formattable.
+        #
+        # @return [Boolean]
+        def formattable?
+          false
+        end
+      end
+    end
+  end
+end

data/lib/apiwork/introspection/param.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module Introspection
+    module Param
+      class << self
+        def build(dump)
+          case dump[:type]
+          when :string then String.new(dump)
+          when :integer then Integer.new(dump)
+          when :number then Number.new(dump)
+          when :decimal then Decimal.new(dump)
+          when :boolean then Boolean.new(dump)
+          when :datetime then DateTime.new(dump)
+          when :date then Date.new(dump)
+          when :time then Time.new(dump)
+          when :uuid then UUID.new(dump)
+          when :binary then Binary.new(dump)
+          when :unknown then Unknown.new(dump)
+          when :array then Array.new(dump)
+          when :object then Object.new(dump)
+          when :union then Union.new(dump)
+          when :literal then Literal.new(dump)
+          when :reference then Reference.new(dump)
+          else Unknown.new(dump)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/apiwork/introspection/type.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module Introspection
+    # @api public
+    # Wraps custom type definitions.
+    #
+    # Types can be objects (with shapes) or unions (with variants).
+    #
+    # @example Object type
+    #   api.types[:address].object? # => true
+    #   api.types[:address].shape[:city] # => Param for city field
+    #
+    # @example Union type
+    #   api.types[:payment_method].union? # => true
+    #   api.types[:payment_method].variants # => [Param, ...]
+    #   api.types[:payment_method].discriminator # => :type
+    class Type
+      def initialize(dump)
+        @dump = dump
+      end
+
+      # @api public
+      # The type for this type.
+      #
+      # @return [Symbol, nil]
+      def type
+        @dump[:type]
+      end
+
+      # @api public
+      # Whether this type is an object.
+      #
+      # @return [Boolean]
+      def object?
+        type == :object
+      end
+
+      # @api public
+      # Whether this type is a union.
+      #
+      # @return [Boolean]
+      def union?
+        type == :union
+      end
+
+      # @api public
+      # The shape for this type.
+      #
+      # @return [Hash{Symbol => Param}]
+      def shape
+        @shape ||= @dump[:shape].transform_values { |dump| Param.build(dump) }
+      end
+
+      # @api public
+      # The variants for this type.
+      #
+      # @return [Array<Param>]
+      def variants
+        @variants ||= @dump[:variants].map { |variant| Param.build(variant) }
+      end
+
+      # @api public
+      # The discriminator for this type.
+      #
+      # @return [Symbol, nil]
+      def discriminator
+        @dump[:discriminator]
+      end
+
+      # @api public
+      # The description for this type.
+      #
+      # @return [String, nil]
+      def description
+        @dump[:description]
+      end
+
+      # @api public
+      # The extends for this type.
+      #
+      # @return [Array<Symbol>]
+      def extends
+        @dump[:extends]
+      end
+
+      # @api public
+      # Whether this type extends other types.
+      #
+      # @return [Boolean]
+      def extends?
+        extends.any?
+      end
+
+      # @api public
+      # The example for this type.
+      #
+      # @return [Object, nil]
+      def example
+        @dump[:example]
+      end
+
+      # @api public
+      # Whether this type is deprecated.
+      #
+      # @return [Boolean]
+      def deprecated?
+        @dump[:deprecated]
+      end
+
+      # @api public
+      # Converts this type to a hash.
+      #
+      # @return [Hash]
+      def to_h
+        {
+          deprecated: deprecated?,
+          description: description,
+          discriminator: discriminator,
+          example: example,
+          extends: extends,
+          shape: shape.transform_values(&:to_h),
+          type: type,
+          variants: variants.map(&:to_h),
+        }
+      end
+    end
+  end
+end

data/lib/apiwork/introspection.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module Introspection
+    class << self
+      def api(api_class, locale: nil)
+        with_locale(locale) { API.new(Dump.api(api_class)) }
+      end
+
+      def contract(contract_class, expand: false, locale: nil)
+        with_locale(locale) { Contract.new(Dump.contract(contract_class, expand:)) }
+      end
+
+      private
+
+      def with_locale(locale, &block)
+        return yield unless locale
+
+        unless I18n.available_locales.include?(locale)
+          raise ConfigurationError,
+                "locale must be one of #{I18n.available_locales.inspect}, got #{locale.inspect}"
+        end
+
+        I18n.with_locale(locale, &block)
+      end
+    end
+  end
+end

data/lib/apiwork/issue.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Apiwork
+  # @api public
+  # Represents a validation issue found during request parsing.
+  #
+  # Issues are returned when request parameters fail validation,
+  # coercion, or constraint checks. Access via `contract.issues`.
+  class Issue
+    # @!attribute [r] code
+    #   @api public
+    #   The code for this issue.
+    #
+    #   @return [Symbol]
+    # @!attribute [r] detail
+    #   @api public
+    #   The detail for this issue.
+    #
+    #   @return [String]
+    # @!attribute [r] meta
+    #   @api public
+    #   The meta for this issue.
+    #
+    #   @return [Hash]
+    # @!attribute [r] path
+    #   @api public
+    #   The path for this issue.
+    #
+    #   @return [Array<Symbol, Integer>]
+    attr_reader :code,
+                :detail,
+                :meta,
+                :path
+
+    def initialize(code, detail, meta: {}, path: [])
+      @code = code
+      @detail = detail
+      @path = path.map { |element| element.is_a?(Integer) ? element : element.to_sym }
+      @meta = meta
+    end
+
+    # @api public
+    # The pointer for this issue.
+    #
+    # @return [String]
+    def pointer
+      @pointer ||= JSONPointer.new(*path).to_s
+    end
+
+    # @api public
+    # Converts this issue to a hash.
+    #
+    # @return [Hash]
+    def to_h
+      {
+        code: code,
+        detail: detail,
+        meta: meta,
+        path: path.map(&:to_s),
+        pointer: pointer,
+      }
+    end
+
+    # @api public
+    # Converts this issue to a hash for JSON serialization.
+    #
+    # @return [Hash]
+    def as_json
+      to_h
+    end
+
+    # @api public
+    # Converts this issue to a string.
+    #
+    # @return [String]
+    def to_s
+      "[#{code}]#{path.any? ? " at #{pointer}" : ''} #{detail}"
+    end
+  end
+end

data/lib/apiwork/json_pointer.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Apiwork
+  class JSONPointer
+    def initialize(*path)
+      @path = path
+    end
+
+    def to_s
+      return '' if @path.empty?
+
+      "/#{@path.map { |component| escape(component.to_s) }.join('/')}"
+    end
+
+    private
+
+    def escape(component)
+      component.gsub('~', '~0').gsub('/', '~1')
+    end
+  end
+end