taro 1.4.0 → 2.0.0

data/lib/taro/types/field_def.rb

@@ -0,0 +1,62 @@
+# Lazily-evaluated field definition.
+class Taro::Types::FieldDef
+  attr_reader :attributes, :defined_at
+
+  def initialize(defined_at: nil, **attributes)
+    @attributes = attributes
+    @defined_at = defined_at
+    validate
+  end
+
+  def evaluate
+    Taro::Types::Field.new(
+      **attributes.except(*Taro::Types::Coercion.keys),
+      defined_at:,
+      type: Taro::Types::Coercion.call(attributes),
+    )
+  end
+
+  def name
+    attributes[:name]
+  end
+
+  def ==(other)
+    other.is_a?(self.class) && attributes == other.attributes
+  end
+
+  private
+
+  def validate
+    validate_name
+    validate_null
+    validate_type_key
+  end
+
+  def validate_name
+    name.is_a?(Symbol) || raise(Taro::ArgumentError, <<~MSG)
+      field name must be a Symbol, got #{name.class} at #{defined_at}
+    MSG
+  end
+
+  def validate_null
+    [true, false].include?(attributes[:null]) || raise(Taro::ArgumentError, <<~MSG)
+      null has to be specified as true or false for field #{name} at #{defined_at}"
+    MSG
+  end
+
+  def validate_type_key
+    attributes[type_key].class == String || raise(Taro::ArgumentError, <<~MSG)
+      #{type_key} must be a String for field #{name} at #{defined_at}
+    MSG
+  end
+
+  def type_key
+    possible_keys = Taro::Types::Coercion.keys
+    keys = attributes.keys & possible_keys
+    keys.size == 1 || raise(Taro::ArgumentError, <<~MSG)
+      Exactly one of #{possible_keys.join(', ')} must be given
+      for field #{name} at #{defined_at}
+    MSG
+    keys.first
+  end
+end

data/lib/taro/types/field_validation.rb

@@ -12,16 +12,14 @@ module Taro::Types::FieldValidation
   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
+    msg = 'field is not nullable'
+    for_input ? input_error(msg, value) : response_error(msg, value)
   end
 
   def validate_enum_inclusion(value, for_input)
     return if enum.nil? || null && value.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
+    msg = "field expects one of #{enum.inspect}, got #{value.inspect}"
+    for_input ? input_error(msg, value) : response_error(msg, value)
   end
 end

data/lib/taro/types/input_type.rb

@@ -1,13 +1,8 @@
-# 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
+require_relative 'object_type'
 
+# Abstract base class for input types, i.e. types without response rendering.
+class Taro::Types::InputType < Taro::Types::ObjectType
   def coerce_response
-    response_error 'InputTypes cannot be used as response types'
+    response_error "#{self.class.name} is an InputType and cannot be used as response type"
   end
 end

data/lib/taro/types/nested_response_type.rb

@@ -0,0 +1,16 @@
+require_relative 'response_type'
+
+# @api private - this type is only for internal use in Declarations.
+class Taro::Types::NestedResponseType < Taro::Types::ResponseType
+  def self.nesting_field
+    fields.size == 1 || raise(
+      Taro::InvariantError, "#{self} should have 1 field, got #{fields}"
+    )
+    fields.each_value.first
+  end
+
+  def self.default_openapi_name
+    field = nesting_field
+    "#{field.type.openapi_name}_in_#{field.name}_Response"
+  end
+end

data/lib/taro/types/object_type.rb

@@ -6,14 +6,9 @@ class Taro::Types::ObjectType < Taro::Types::BaseType
   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 }
+  require_relative 'response_type'
+  Dir[File.join(__dir__, 'object_types', '**', '*.rb')].each { |f| require_relative f }
 end

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

@@ -1,4 +1,4 @@
-class Taro::Types::ObjectTypes::NoContentType < Taro::Types::ObjectType
+class Taro::Types::ObjectTypes::NoContentType < Taro::Types::ResponseType
   self.desc = 'An empty response'
   self.openapi_name = 'NoContent'
 
@@ -7,10 +7,6 @@ class Taro::Types::ObjectTypes::NoContentType < Taro::Types::ObjectType
     super(nil)
   end
 
-  def coerce_input
-    input_error 'NoContentType cannot be used as input type'
-  end
-
   def coerce_response
     {}
   end

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

@@ -1,4 +1,4 @@
-class Taro::Types::ObjectTypes::PageInfoType < Taro::Types::ObjectType
+class Taro::Types::ObjectTypes::PageInfoType < Taro::Types::ResponseType
   self.openapi_name = 'PageInfo'
 
   field :has_previous_page, type: 'Boolean', null: false, desc: 'Whether there is a previous page of results'

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

@@ -4,7 +4,7 @@
 #
 # The gem rails_cursor_pagination must be installed to use this.
 #
-class Taro::Types::ObjectTypes::PageType < Taro::Types::ObjectType
+class Taro::Types::ObjectTypes::PageType < Taro::Types::ResponseType
   extend Taro::Types::Shared::ItemType
 
   def self.derive_from(from_type)
@@ -13,10 +13,6 @@ class Taro::Types::ObjectTypes::PageType < Taro::Types::ObjectType
     field(:page_info, type: 'Taro::Types::ObjectTypes::PageInfoType', null: false)
   end
 
-  def coerce_input
-    input_error 'PageTypes cannot be used as input types'
-  end
-
   def self.render(relation, after:, limit: 20, order_by: nil, order: nil)
     result = RailsCursorPagination::Paginator.new(
       relation, limit:, order_by:, order:, after:

data/lib/taro/types/response_type.rb

@@ -0,0 +1,8 @@
+require_relative 'object_type'
+
+# Abstract base class for response types, i.e. types without input parsing.
+class Taro::Types::ResponseType < Taro::Types::ObjectType
+  def coerce_input
+    input_error "#{self.class.name} is a ResponseType and cannot be used as input type"
+  end
+end

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

@@ -0,0 +1,15 @@
+# @api private – relaxed Integer type for use with path & query params,
+# which Rails provides as Strings in ActionController::Parameters.
+class Taro::Types::Scalar::IntegerParamType < Taro::Types::ScalarType
+  self.openapi_type = :integer
+
+  def coerce_input
+    if object.is_a?(Integer)
+      object
+    elsif object.is_a?(String) && object.match?(/\A\d+\z/)
+      object.to_i
+    else
+      input_error('must be an Integer')
+    end
+  end
+end

data/lib/taro/types/scalar_type.rb

@@ -4,5 +4,5 @@ class Taro::Types::ScalarType < Taro::Types::BaseType
 end
 
 module Taro::Types::Scalar
-  Dir[File.join(__dir__, 'scalar', '**', '*.rb')].each { |f| require f }
+  Dir[File.join(__dir__, 'scalar', '**', '*.rb')].each { |f| require_relative f }
 end

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

@@ -15,9 +15,9 @@ module Taro::Types::Shared::CustomFieldResolvers
     end
 
     def method_added(name)
-      if [:object, :pattern].include?(name)
+      if %i[input_error object pattern response_error].include?(name)
         raise(Taro::ArgumentError, "##{name} is a reserved, internally used method name")
-      elsif ![:coerce_input, :coerce_response].include?(name) &&
+      elsif !%i[coerce_input coerce_response].include?(name) &&
             !self.name.to_s.start_with?('Taro::Types::')
         custom_resolvers[name] = true
       end

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

@@ -1,27 +1,46 @@
 module Taro::Types::Shared::DerivedTypes
   # Adds `name` as a method to all type classes and adds
-  # `name`_of as a supported key to the Coercion module.
+  # :`name`_of as a supported key to the Coercion module.
   # When `name` is called on a type class T, it returns a new subclass
   # S inheriting from `type` and passes T to S::derive_from.
-  def define_derived_type(name, type)
-    root = Taro::Types::BaseType
-    raise ArgumentError, "#{name} is already in use" if root.respond_to?(name)
+  def define_derived_type(name, derivable_type)
+    add_coercion_key(name)
+    add_derivation_method(name, derivable_type)
+  end
 
-    ckey = :"#{name}#{Taro::Types::Coercion.derived_suffix}"
-    ckeys = Taro::Types::Coercion.keys
-    raise ArgumentError, "#{ckey} is already in use" if ckeys.include?(ckey)
+  def derived_types
+    Taro::Types::Shared::DerivedTypes.map[self] ||= {}
+  end
 
-    root.define_singleton_method(name) do
-      derived_types[type] ||= begin
-        type_class = Taro::Types::Coercion.call(type:)
-        Class.new(type_class).tap { |t| t.derive_from(self) }
-      end
+  def self.map
+    @map ||= {}
+  end
+
+  private
+
+  def add_coercion_key(base_name)
+    new_key = :"#{base_name}#{Taro::Types::Coercion.derived_suffix}"
+    if Taro::Types::Coercion.keys.include?(new_key)
+      raise ArgumentError, "#{new_key} is already in use"
     end
 
-    ckeys << ckey
+    Taro::Types::Coercion.keys << new_key
   end
 
-  def derived_types
-    @derived_types ||= {}
+  def add_derivation_method(method_name, type)
+    root = Taro::Types::BaseType
+    if root.respond_to?(method_name)
+      raise ArgumentError, "#{method_name} is already in use"
+    end
+
+    root.define_singleton_method(method_name) do
+      derived_types[type] ||= begin
+        type_class = Taro::Types::Coercion.call(type:)
+        new_type = Class.new(type_class)
+        new_type.define_name("#{self.name}.#{method_name}")
+        new_type.derive_from(self)
+        new_type
+      end
+    end
   end
 end

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

@@ -0,0 +1,15 @@
+module Taro::Types::Shared::Equivalence
+  def equivalent?(other)
+    equal?(other) || equal_properties?(other)
+  end
+
+  def equal_properties?(other)
+    return false unless other.openapi_type == openapi_type
+
+    # @fields is lazy-loaded. Comparing @field_defs suffices.
+    ignored = %i[@fields]
+    props = instance_variables - ignored
+    props == (other.instance_variables - ignored) &&
+      props.all? { |p| instance_variable_get(p) == other.instance_variable_get(p) }
+  end
+end

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

@@ -1,15 +1,15 @@
 module Taro::Types::Shared::Errors
-  def input_error(msg)
-    raise Taro::InputError, coerce_error_message(msg)
+  def input_error(msg, value = object)
+    raise Taro::InputError.new(coerce_error_message(msg, value), value, self)
   end
 
-  def response_error(msg)
-    raise Taro::ResponseError, coerce_error_message(msg)
+  def response_error(msg, value = object)
+    raise Taro::ResponseError.new(coerce_error_message(msg, value), value, self)
   end
 
-  def coerce_error_message(msg)
-    type_desc = (self.class.name || self.class.superclass.name)
-                .sub(/^Taro::Types::.*?([^:]+)Type$/, '\1')
-    "#{object.class} is not valid as #{type_desc}: #{msg}"
+  def coerce_error_message(msg, value)
+    type_class = is_a?(Taro::Types::Field) ? self.type : self.class
+    type_desc = type_class.name.sub(/^Taro::Types::.*?([^:]+)$/, '\1')
+    "#{value.class} is not valid as #{type_desc}: #{msg}"
   end
 end

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

@@ -3,54 +3,28 @@ 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 autoloading 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)
+  def field(name, **attributes)
+    attributes[:defined_at] ||= caller_locations(1..1)[0]
+    field_def = Taro::Types::FieldDef.new(name:, **attributes)
 
-    field_defs[name] = { name:, defined_at:, **kwargs }
+    (prev = field_defs[name]) && raise(Taro::ArgumentError, <<~MSG)
+      field #{name} at #{field_def.defined_at}
+      previously defined at #{prev.defined_at}.
+    MSG
+
+    field_defs[name] = field_def
   end
 
   def fields
-    @fields ||= evaluate_field_defs
+    @fields ||= field_defs.transform_values(&:evaluate)
   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}")
-
-    c_keys = Taro::Types::Coercion.keys
-    (type_keys = (kwargs.keys & c_keys)).size == 1 ||
-      raise(Taro::ArgumentError, "exactly one of #{c_keys.join(', ')} must be given for field #{name} at #{defined_at}")
-
-    kwargs[type_keys.first].class == String ||
-      raise(Taro::ArgumentError, "#{type_keys.first} 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

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

@@ -0,0 +1,14 @@
+module Taro::Types::Shared::Name
+  def define_name(name)
+    instance_eval(<<~RUBY, __FILE__, __LINE__ + 1)
+      def name
+        #{name.inspect}
+      end
+      alias to_s name
+
+      def inspect
+        "#<#{name}>"
+      end
+    RUBY
+  end
+end

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

@@ -3,8 +3,6 @@ module Taro::Types::Shared::ObjectCoercion
   def coerce_input
     self.class.fields.transform_values do |field|
       field.value_for_input(object)
-    rescue Taro::Error => e
-      raise_enriched_coercion_error(e, field)
     end
   end
 
@@ -13,17 +11,6 @@ module Taro::Types::Shared::ObjectCoercion
     object_is_hash = object.is_a?(Hash)
     self.class.fields.transform_values do |field|
       field.value_for_response(object, context: self, object_is_hash:)
-    rescue Taro::Error => e
-      raise_enriched_coercion_error(e, field)
     end
   end
-
-  def raise_enriched_coercion_error(error, field)
-    # The indentation is on purpose. These errors can be recursively rescued
-    # and re-raised by a tree of object types, which should be made apparent.
-    raise error.class, <<~MSG
-      Failed to read #{self.class.name} field `#{field.name}` from #{object.class}:
-      #{error.message.lines.map { |line| "  #{line}" }.join}
-    MSG
-  end
 end

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

@@ -5,12 +5,6 @@ module Taro::Types::Shared::OpenAPIName
     @openapi_name ||= default_openapi_name
   end
 
-  def openapi_name?
-    !!openapi_name
-  rescue Taro::Error
-    false
-  end
-
   def openapi_name=(arg)
     arg.nil? || arg.is_a?(String) ||
       raise(Taro::ArgumentError, 'openapi_name must be a String')

data/lib/taro/types/shared.rb

@@ -1,3 +1,3 @@
 module Taro::Types::Shared
-  Dir[File.join(__dir__, "shared", "*.rb")].each { |f| require f }
+  Dir[File.join(__dir__, "shared", "*.rb")].each { |f| require_relative f }
 end

data/lib/taro/types.rb

@@ -1,3 +1,3 @@
 module Taro::Types
-  Dir[File.join(__dir__, "types", "*.rb")].each { |f| require f }
+  Dir[File.join(__dir__, "types", "*.rb")].each { |f| require_relative f }
 end

data/lib/taro/version.rb

@@ -1,4 +1,4 @@
 # :nocov:
 module Taro
-  VERSION = "1.4.0"
+  VERSION = "2.0.0"
 end

data/lib/taro.rb

@@ -1,3 +1,8 @@
 module Taro
-  Dir[File.join(__dir__, "taro", "*.rb")].each { |f| require f }
+  Dir[File.join(__dir__, "taro", "*.rb")].each { |f| require_relative f }
+
+  def self.reset
+    declarations.reset
+    Taro::Types::BaseType.last_render = nil
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: taro
 version: !ruby/object:Gem::Version
-  version: 1.4.0
+  version: 2.0.0
 platform: ruby
 authors:
 - Janosch Müller
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-11-27 00:00:00.000000000 Z
+date: 2024-12-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rack
@@ -39,11 +39,15 @@ files:
 - README.md
 - Rakefile
 - lib/taro.rb
+- lib/taro/common_returns.rb
 - lib/taro/config.rb
+- lib/taro/declaration.rb
+- lib/taro/declarations.rb
 - lib/taro/errors.rb
 - lib/taro/export.rb
 - lib/taro/export/base.rb
 - lib/taro/export/open_api_v3.rb
+- lib/taro/none.rb
 - lib/taro/rails.rb
 - lib/taro/rails/active_declarations.rb
 - lib/taro/rails/declaration.rb
@@ -57,6 +61,7 @@ files:
 - lib/taro/rails/generators/templates/input_type.erb
 - lib/taro/rails/generators/templates/no_content_type.erb
 - lib/taro/rails/generators/templates/object_type.erb
+- lib/taro/rails/generators/templates/response_type.erb
 - lib/taro/rails/generators/templates/scalar_type.erb
 - lib/taro/rails/normalized_route.rb
 - lib/taro/rails/param_parsing.rb
@@ -65,21 +70,28 @@ files:
 - lib/taro/rails/response_validator.rb
 - lib/taro/rails/route_finder.rb
 - lib/taro/rails/tasks/export.rake
+- lib/taro/return_def.rb
+- lib/taro/route.rb
+- lib/taro/status_code.rb
 - lib/taro/types.rb
 - lib/taro/types/base_type.rb
 - lib/taro/types/coercion.rb
 - lib/taro/types/enum_type.rb
 - lib/taro/types/field.rb
+- lib/taro/types/field_def.rb
 - lib/taro/types/field_validation.rb
 - lib/taro/types/input_type.rb
 - lib/taro/types/list_type.rb
+- lib/taro/types/nested_response_type.rb
 - lib/taro/types/object_type.rb
 - lib/taro/types/object_types/free_form_type.rb
 - lib/taro/types/object_types/no_content_type.rb
 - lib/taro/types/object_types/page_info_type.rb
 - lib/taro/types/object_types/page_type.rb
+- lib/taro/types/response_type.rb
 - lib/taro/types/scalar/boolean_type.rb
 - lib/taro/types/scalar/float_type.rb
+- lib/taro/types/scalar/integer_param_type.rb
 - lib/taro/types/scalar/integer_type.rb
 - lib/taro/types/scalar/iso8601_date_type.rb
 - lib/taro/types/scalar/iso8601_datetime_type.rb
@@ -93,9 +105,11 @@ files:
 - lib/taro/types/shared/deprecation.rb
 - lib/taro/types/shared/derived_types.rb
 - lib/taro/types/shared/description.rb
+- lib/taro/types/shared/equivalence.rb
 - lib/taro/types/shared/errors.rb
 - lib/taro/types/shared/fields.rb
 - lib/taro/types/shared/item_type.rb
+- lib/taro/types/shared/name.rb
 - lib/taro/types/shared/object_coercion.rb
 - lib/taro/types/shared/openapi_name.rb
 - lib/taro/types/shared/openapi_type.rb