taro 0.0.0 → 1.1.0

data/lib/taro/types/field.rb

@@ -0,0 +1,78 @@
+require_relative 'field_validation'
+
+Taro::Types::Field = Data.define(:name, :type, :null, :method, :default, :enum, :defined_at, :desc) do
+  include Taro::Types::FieldValidation
+
+  def initialize(name:, type:, null:, method: name, default: :none, enum: nil, defined_at: nil, desc: nil)
+    enum = coerce_to_enum(enum)
+    super(name:, type:, null:, method:, default:, enum:, defined_at:, desc:)
+  end
+
+  def value_for_input(object)
+    value = object[name] if object
+    value = coerce_value(value, true)
+    validated_value(value)
+  end
+
+  def value_for_response(object, context: nil, object_is_hash: true)
+    value = retrieve_response_value(object, context, object_is_hash)
+    value = coerce_value(value, false)
+    validated_value(value, false)
+  end
+
+  def default_specified?
+    !default.equal?(:none)
+  end
+
+  def openapi_type
+    type.openapi_type
+  end
+
+  private
+
+  def coerce_to_enum(arg)
+    return if arg.nil?
+
+    enum = arg.to_a
+    test = Class.new(Taro::Types::EnumType) { arg.each { |v| value(v) } }
+    test.raise_if_empty_enum
+    enum
+  end
+
+  def retrieve_response_value(object, context, object_is_hash)
+    if object_is_hash
+      retrieve_hash_value(object)
+    elsif context&.resolve?(method)
+      context.public_send(method)
+    elsif object.respond_to?(method, true)
+      object.public_send(method)
+    else
+      raise_response_coercion_error(object)
+    end
+  end
+
+  def retrieve_hash_value(object)
+    if object.key?(method.to_s)
+      object[method.to_s]
+    else
+      object[method]
+    end
+  end
+
+  def coerce_value(value, from_input)
+    return if value.nil? && null
+    return default if value.nil? && default_specified?
+
+    type_obj = type.new(value)
+    from_input ? type_obj.coerce_input : type_obj.coerce_response
+  rescue Taro::Error => e
+    raise e.class, "#{e.message}, after using method/key `:#{method}` to resolve field `#{name}`"
+  end
+
+  def raise_response_coercion_error(object)
+    raise Taro::ResponseError, <<~MSG
+      Failed to coerce value #{object.inspect} for field `#{name}` using method/key `:#{method}`.
+      It is not a valid #{type} value.
+    MSG
+  end
+end

data/lib/taro/types/field_validation.rb

@@ -0,0 +1,27 @@
+module Taro::Types::FieldValidation
+  # Validate the value against the field properties. This method will raise
+  # a Taro::InputError or Taro::ResponseError if the value is not matching.
+  def validated_value(value, for_input = true)
+    validate_null_and_ok?(value, for_input)
+    validate_enum_inclusion(value, for_input)
+    value
+  end
+
+  private
+
+  def validate_null_and_ok?(value, for_input)
+    return if null || !value.nil?
+
+    raise for_input ? Taro::InputError : Taro::ResponseError, <<~MSG
+      Field #{name} is not nullable (got #{value.inspect})
+    MSG
+  end
+
+  def validate_enum_inclusion(value, for_input)
+    return if enum.nil? || enum.include?(value)
+
+    raise for_input ? Taro::InputError : Taro::ResponseError, <<~MSG
+      Field #{name} has an invalid value #{value.inspect} (expected one of #{enum.inspect})
+    MSG
+  end
+end

data/lib/taro/types/input_type.rb

@@ -0,0 +1,13 @@
+# Abstract base class for input types, i.e. types without response rendering.
+class Taro::Types::InputType < Taro::Types::BaseType
+  require_relative "shared"
+  extend Taro::Types::Shared::Fields
+  include Taro::Types::Shared::CustomFieldResolvers
+  include Taro::Types::Shared::ObjectCoercion
+
+  self.openapi_type = :object
+
+  def coerce_response
+    response_error 'InputTypes cannot be used as response types'
+  end
+end

data/lib/taro/types/list_type.rb

@@ -0,0 +1,30 @@
+# Abstract base class for List types (arrays in OpenAPI terms).
+# Unlike other types, this one should not be manually inherited from,
+# but is used indirectly via `array_of: SomeType`.
+class Taro::Types::ListType < Taro::Types::BaseType
+  extend Taro::Types::Shared::DerivableType
+  extend Taro::Types::Shared::ItemType
+
+  self.openapi_type = :array
+
+  def coerce_input
+    object.instance_of?(Array) || input_error('must be an Array')
+
+    item_type = self.class.item_type
+    object.map { |el| item_type.new(el).coerce_input }
+  end
+
+  def coerce_response
+    object.respond_to?(:map) || response_error('must be an Enumerable')
+
+    item_type = self.class.item_type
+    object.map { |el| item_type.new(el).coerce_response }
+  end
+end
+
+# add shortcut to other types
+class Taro::Types::BaseType
+  def self.array
+    Taro::Types::ListType.for(self)
+  end
+end

data/lib/taro/types/object_type.rb

@@ -0,0 +1,19 @@
+# Abstract base class for renderable types with fields.
+class Taro::Types::ObjectType < Taro::Types::BaseType
+  require_relative "shared"
+  extend Taro::Types::Shared::Fields
+  include Taro::Types::Shared::CustomFieldResolvers
+  include Taro::Types::Shared::ObjectCoercion
+
+  self.openapi_type = :object
+
+  def self.inherited(subclass)
+    subclass.instance_variable_set(:@response_types, [Hash])
+    subclass.instance_variable_set(:@input_types, [Hash])
+    super
+  end
+end
+
+module Taro::Types::ObjectTypes
+  Dir[File.join(__dir__, 'object_types', '**', '*.rb')].each { |f| require f }
+end

data/lib/taro/types/object_types/free_form_type.rb

@@ -0,0 +1,13 @@
+class Taro::Types::ObjectTypes::FreeFormType < Taro::Types::ObjectType
+  self.desc = 'An arbitrary, unvalidated Hash or JSON object. Use with care.'
+  self.additional_properties = true
+
+  def coerce_input
+    object.is_a?(Hash) && object || input_error('must be a Hash')
+  end
+
+  def coerce_response
+    object.respond_to?(:as_json) && (res = object.as_json).is_a?(Hash) && res ||
+      response_error('must return a Hash from #as_json')
+  end
+end

data/lib/taro/types/object_types/no_content_type.rb

@@ -0,0 +1,16 @@
+class Taro::Types::ObjectTypes::NoContentType < Taro::Types::ObjectType
+  self.desc = 'An empty response'
+
+  # render takes no arguments in this case
+  def self.render
+    super(nil)
+  end
+
+  def coerce_input
+    input_error 'NoContentType cannot be used as input type'
+  end
+
+  def coerce_response
+    {}
+  end
+end

data/lib/taro/types/object_types/page_info_type.rb

@@ -0,0 +1,6 @@
+class Taro::Types::ObjectTypes::PageInfoType < Taro::Types::ObjectType
+  field :has_previous_page, type: 'Boolean', null: false, desc: 'Whether there is a previous page of results'
+  field :has_next_page, type: 'Boolean', null: false, desc: 'Whether there is another page of results'
+  field :start_cursor, type: 'String', null: true, desc: 'The first cursor in the current page of results (null if zero results)'
+  field :end_cursor, type: 'String', null: true, desc: 'The last cursor in the current page of results (null if zero results)'
+end

data/lib/taro/types/object_types/page_type.rb

@@ -0,0 +1,45 @@
+# Abstract base class for Page types (paginated ActiveRecord data).
+# Unlike other types, this one should not be manually inherited from,
+# but is used indirectly via `page_of: SomeType`.
+#
+# The gem rails_cursor_pagination must be installed to use this.
+#
+class Taro::Types::ObjectTypes::PageType < Taro::Types::BaseType
+  extend Taro::Types::Shared::DerivableType
+  extend Taro::Types::Shared::ItemType
+
+  def coerce_input
+    input_error 'PageTypes cannot be used as input types'
+  end
+
+  def coerce_response(after:, limit: 20, order_by: nil, order: nil)
+    list = RailsCursorPagination::Paginator.new(
+      object, limit:, order_by:, order:, after:
+    ).fetch
+    coerce_paginated_list(list)
+  end
+
+  def coerce_paginated_list(list)
+    item_type = self.class.item_type
+    items = list[:page].map do |item|
+      item_type.new(item[:data]).coerce_response
+    end
+
+    {
+      self.class.items_key => items,
+      page_info: Taro::Types::ObjectTypes::PageInfoType.new(list[:page_info]).coerce_response,
+    }
+  end
+
+  # support overrides, e.g. based on item_type
+  def self.items_key
+    :page
+  end
+end
+
+# add shortcut to other types
+class Taro::Types::BaseType
+  def self.page
+    Taro::Types::ObjectTypes::PageType.for(self)
+  end
+end

data/lib/taro/types/scalar/boolean_type.rb

@@ -0,0 +1,19 @@
+class Taro::Types::Scalar::BooleanType < Taro::Types::ScalarType
+  self.openapi_type = :boolean
+
+  def coerce_input
+    if object == true || object == false
+      object
+    else
+      input_error('must be true or false')
+    end
+  end
+
+  def coerce_response
+    if object == true || object == false
+      object
+    else
+      response_error('must be true or false')
+    end
+  end
+end

data/lib/taro/types/scalar/float_type.rb

@@ -0,0 +1,15 @@
+class Taro::Types::Scalar::FloatType < Taro::Types::ScalarType
+  self.openapi_type = :number
+
+  def coerce_input
+    object.instance_of?(Float) ? object : input_error('must be a Float')
+  end
+
+  def coerce_response
+    case object
+    when Float   then object
+    when Integer then object.to_f
+    else              response_error('must be a Float or Integer')
+    end
+  end
+end

data/lib/taro/types/scalar/integer_type.rb

@@ -0,0 +1,11 @@
+class Taro::Types::Scalar::IntegerType < Taro::Types::ScalarType
+  self.openapi_type = :integer
+
+  def coerce_input
+    object.instance_of?(Integer) ? object : input_error('must be an Integer')
+  end
+
+  def coerce_response
+    object.instance_of?(Integer) ? object : response_error('must be an Integer')
+  end
+end

data/lib/taro/types/scalar/iso8601_date_type.rb

@@ -0,0 +1,23 @@
+class Taro::Types::Scalar::ISO8601DateType < Taro::Types::ScalarType
+  self.desc = 'Represents a time as Date in ISO8601 format.'
+  self.openapi_type = :string
+
+  PATTERN = /\A\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])\z/
+
+  def coerce_input
+    if object.instance_of?(String) && object.match?(PATTERN)
+      Date.parse(object)
+    else
+      input_error("must be a ISO8601 formatted string")
+    end
+  end
+
+  def coerce_response
+    case object
+    when Date, DateTime, Time
+      object.strftime("%Y-%m-%d")
+    else
+      response_error("must be a Time, Date, or DateTime")
+    end
+  end
+end

data/lib/taro/types/scalar/iso8601_datetime_type.rb

@@ -0,0 +1,25 @@
+class Taro::Types::Scalar::ISO8601DateTimeType < Taro::Types::ScalarType
+  self.desc = 'Represents a time as DateTime in ISO8601 format.'
+  self.openapi_type = :string
+
+  PATTERN = /\A\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])T([01]\d|2[0-3]):[0-5]\d:[0-5]\d(Z|[+-](0[0-9]|1[0-4]):[0-5]\d)\z/
+
+  def coerce_input
+    if object.instance_of?(String) && object.match?(PATTERN)
+      DateTime.iso8601(object)
+    else
+      input_error("must be a ISO8601 formatted string")
+    end
+  end
+
+  def coerce_response
+    case object
+    when Date
+      object.to_datetime.utc.iso8601
+    when DateTime, Time
+      object.utc.iso8601
+    else
+      response_error("must be a Time, Date, or DateTime")
+    end
+  end
+end

data/lib/taro/types/scalar/string_type.rb

@@ -0,0 +1,15 @@
+class Taro::Types::Scalar::StringType < Taro::Types::ScalarType
+  self.openapi_type = :string
+
+  def coerce_input
+    object.instance_of?(String) ? object : input_error('must be a String')
+  end
+
+  def coerce_response
+    case object
+    when String then object
+    when Symbol then object.to_s
+    else response_error('must be a String or Symbol')
+    end
+  end
+end

data/lib/taro/types/scalar/timestamp_type.rb

@@ -0,0 +1,23 @@
+class Taro::Types::Scalar::TimestampType < Taro::Types::ScalarType
+  self.desc = 'Represents a time as Time on the server side and UNIX timestamp (integer) on the client side.'
+  self.openapi_type = :integer
+
+  def coerce_input
+    if object.instance_of?(Integer)
+      Time.at(object)
+    else
+      input_error("must be an Integer")
+    end
+  end
+
+  def coerce_response
+    case object
+    when Date, DateTime, Time
+      object.strftime('%s').to_i
+    when Integer
+      object
+    else
+      response_error("must be a Time, Date, DateTime, or Integer")
+    end
+  end
+end

data/lib/taro/types/scalar/uuid_v4_type.rb

@@ -0,0 +1,22 @@
+class Taro::Types::Scalar::UUIDv4Type < Taro::Types::ScalarType
+  self.desc = "A UUID v4 string"
+  self.openapi_type = :string
+
+  PATTERN = /\A\h{8}-?(?:\h{4}-?){3}\h{12}\z/
+
+  def coerce_input
+    if object.is_a?(String) && object.match?(PATTERN)
+      object
+    else
+      input_error("must be a UUID v4 string")
+    end
+  end
+
+  def coerce_response
+    if object.is_a?(String) && object.match?(PATTERN)
+      object
+    else
+      response_error("must be a UUID v4 string")
+    end
+  end
+end

data/lib/taro/types/scalar_type.rb

@@ -0,0 +1,7 @@
+# Abstract base class for scalar types, i.e. types without fields.
+class Taro::Types::ScalarType < Taro::Types::BaseType
+end
+
+module Taro::Types::Scalar
+  Dir[File.join(__dir__, 'scalar', '**', '*.rb')].each { |f| require f }
+end

data/lib/taro/types/shared/additional_properties.rb

@@ -0,0 +1,12 @@
+module Taro::Types::Shared::AdditionalProperties
+  attr_writer :additional_properties
+
+  def additional_properties?
+    !!@additional_properties
+  end
+
+  def inherited(subclass)
+    super
+    subclass.additional_properties = @additional_properties
+  end
+end

data/lib/taro/types/shared/custom_field_resolvers.rb

@@ -0,0 +1,33 @@
+# Allows implementing methods on types to override or implement the method
+# used to retrieve the value of a field.
+module Taro::Types::Shared::CustomFieldResolvers
+  def resolve?(method)
+    self.class.custom_resolvers.key?(method)
+  end
+
+  def self.included(mod)
+    mod.extend(ClassMethods)
+  end
+
+  module ClassMethods
+    def custom_resolvers
+      @custom_resolvers ||= {}
+    end
+
+    def method_added(name)
+      if name == :object
+        raise(Taro::ArgumentError, '#object is a reserved, internally used method name')
+      elsif ![:coerce_input, :coerce_response].include?(name) &&
+            !self.name.to_s.start_with?('Taro::Types::')
+        custom_resolvers[name] = true
+      end
+
+      super
+    end
+
+    def inherited(subclass)
+      subclass.instance_variable_set(:@custom_resolvers, custom_resolvers.dup)
+      super
+    end
+  end
+end

data/lib/taro/types/shared/derivable_types.rb

@@ -0,0 +1,9 @@
+module Taro::Types::Shared::DerivableType
+  def for(type)
+    derived_types[type] ||= Class.new(self).tap { |t| t.item_type = type }
+  end
+
+  def derived_types
+    @derived_types ||= {}
+  end
+end

data/lib/taro/types/shared/description.rb

@@ -0,0 +1,9 @@
+module Taro::Types::Shared::Description
+  def desc
+    @desc
+  end
+
+  def desc=(arg)
+    @desc = arg
+  end
+end

data/lib/taro/types/shared/errors.rb

@@ -0,0 +1,13 @@
+module Taro::Types::Shared::Errors
+  def input_error(msg)
+    raise Taro::InputError, coerce_error_message(msg)
+  end
+
+  def response_error(msg)
+    raise Taro::ResponseError, coerce_error_message(msg)
+  end
+
+  def coerce_error_message(msg)
+    "#{object.inspect} (#{object.class}) is not valid as #{self.class}: #{msg}"
+  end
+end

data/lib/taro/types/shared/fields.rb

@@ -0,0 +1,57 @@
+# Adds the `::field` method to object and input types.
+module Taro::Types::Shared::Fields
+  # Field types are set using class name Strings. The respective type classes
+  # are evaluated lazily to allow for circular or recursive type references,
+  # and to avoid unnecessary eager loading of all types in dev/test envs.
+  def field(name, **kwargs)
+    defined_at = kwargs[:defined_at] || caller_locations(1..1)[0]
+    validate_name(name, defined_at:)
+    validate_no_override(name, defined_at:)
+    validate_options(name, defined_at:, **kwargs)
+
+    field_defs[name] = { name:, defined_at:, **kwargs }
+  end
+
+  def fields
+    @fields ||= evaluate_field_defs
+  end
+
+  private
+
+  def validate_name(name, defined_at:)
+    name.is_a?(Symbol) ||
+      raise(Taro::ArgumentError, "field name must be a Symbol, got #{name.class} at #{defined_at}")
+  end
+
+  def validate_options(name, defined_at:, **kwargs)
+    [true, false].include?(kwargs[:null]) ||
+      raise(Taro::ArgumentError, "null has to be specified as true or false for field #{name} at #{defined_at}")
+
+    (type_keys = (kwargs.keys & Taro::Types::Coercion::KEYS)).size == 1 ||
+      raise(Taro::ArgumentError, "exactly one of type, array_of, or page_of must be given for field #{name} at #{defined_at}")
+
+    kwargs[type_keys.first].class == String ||
+      raise(Taro::ArgumentError, "#{type_key} must be a String for field #{name} at #{defined_at}")
+  end
+
+  def validate_no_override(name, defined_at:)
+    prev = field_defs[name]
+    prev && raise(Taro::ArgumentError, "field #{name} at #{defined_at} previously defined at #{prev[:defined_at]}")
+  end
+
+  def field_defs
+    @field_defs ||= {}
+  end
+
+  def evaluate_field_defs
+    field_defs.transform_values do |field_def|
+      type = Taro::Types::Coercion.call(field_def)
+      Taro::Types::Field.new(**field_def.except(*Taro::Types::Coercion::KEYS), type:)
+    end
+  end
+
+  def inherited(subclass)
+    subclass.instance_variable_set(:@field_defs, field_defs.dup)
+    super
+  end
+end

data/lib/taro/types/shared/item_type.rb

@@ -0,0 +1,16 @@
+# Provides coercion and validation for the "inner" type of enums and arrays.
+module Taro::Types::Shared::ItemType
+  attr_reader :item_type
+
+  def item_type=(new_type)
+    item_type.nil? || new_type == item_type || raise_mixed_types(new_type)
+    @item_type = new_type
+  end
+
+  def raise_mixed_types(new_type)
+    raise Taro::ArgumentError, <<~MSG
+      All items must be of the same type. Mixed types are not supported for now.
+      Expected another #{item_type} item but got a #{new_type} for #{self}.
+    MSG
+  end
+end

data/lib/taro/types/shared/object_coercion.rb

@@ -0,0 +1,16 @@
+# Provides input and response handling for types with fields.
+module Taro::Types::Shared::ObjectCoercion
+  def coerce_input
+    self.class.fields.transform_values do |field|
+      field.value_for_input(object)
+    end
+  end
+
+  # Render the object into a hash.
+  def coerce_response
+    object_is_hash = object.is_a?(Hash)
+    self.class.fields.transform_values do |field|
+      field.value_for_response(object, context: self, object_is_hash:)
+    end
+  end
+end

data/lib/taro/types/shared/openapi_name.rb

@@ -0,0 +1,30 @@
+# Provides a setter, getter and defaults for type classes' `openapi_name`,
+# for use in the OpenAPI export ($refs and corresponding component names).
+module Taro::Types::Shared::OpenAPIName
+  def openapi_name
+    @openapi_name ||= default_openapi_name
+  end
+
+  def openapi_name=(arg)
+    arg.nil? || arg.is_a?(String) ||
+      raise(Taro::ArgumentError, 'openapi_name must be a String')
+    @openapi_name = arg
+  end
+
+  def default_openapi_name # rubocop:disable Metrics
+    if self < Taro::Types::EnumType ||
+       self < Taro::Types::InputType ||
+       self < Taro::Types::ObjectType
+      name && name.chomp('Type').gsub('::', '_') ||
+        raise(Taro::Error, 'openapi_name must be set for anonymous type classes')
+    elsif self < Taro::Types::ScalarType
+      openapi_type
+    elsif self < Taro::Types::ListType
+      "#{item_type.openapi_name}_List"
+    elsif self < Taro::Types::ObjectTypes::PageType
+      "#{item_type.openapi_name}_Page"
+    else
+      raise NotImplementedError, 'no default_openapi_name for this type'
+    end
+  end
+end

data/lib/taro/types/shared/openapi_type.rb

@@ -0,0 +1,27 @@
+# Provides a setter and getter for type classes' `openapi_type`,
+# for use in the OpenAPI export.
+module Taro::Types::Shared::OpenAPIType
+  OPENAPI_TYPES = %i[
+    array
+    boolean
+    integer
+    number
+    object
+    string
+  ].freeze
+
+  def openapi_type
+    @openapi_type || raise(Taro::RuntimeError, "Type lacks openapi_type: #{self}")
+  end
+
+  def openapi_type=(arg)
+    OPENAPI_TYPES.include?(arg) ||
+      raise(Taro::ArgumentError, "openapi_type must be a Symbol, one of #{OPENAPI_TYPES}")
+    @openapi_type = arg
+  end
+
+  def inherited(subclass)
+    subclass.instance_variable_set(:@openapi_type, @openapi_type)
+    super
+  end
+end