taro 1.1.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 36e27c067e70b65d503a3c78b61e9efc05d8995f9927edfaf6f66ff4fae70b25
-  data.tar.gz: 131fc3d1bea432320046c4e5c220dff0a3ead87d8a2f3d12310cdd847b2e50c1
+  metadata.gz: 5007f07dcb3230a1a45011138c19cc0f233e0a0e0fa81d64d554ee3d5cc4a82e
+  data.tar.gz: 99dde57ec71bb2724a29005e644a0bb23d642df11fe4555bd9203340169814df
 SHA512:
-  metadata.gz: 9d44a2c33be8175c6b59b1426921fd339c4e4125bf7fa076da27f4b9c17bcf1efb69aa0233c8e91f16804b086f250b37fddb0e6e6dce2debbf0349fc96ac832d
-  data.tar.gz: 59d1a63e68b5560ee7cf0243ff3ccf6684376249745727e6695576821285e8dc1d64018a5f8e8a962f9d7dcea74c1e6bc9d27dd664662d327c257d81505b6c23
+  metadata.gz: abb5fb481da01a4a50b19e891c3373b42372c97993788ed24c51b07146e087e25d040bc4ea077606a14013633b30f6254f6ced2e939ba9b039b341d95f918211
+  data.tar.gz: b5dd6c2222598ad3d8ee64c64fd0fc6c40299c3f071b08317d17aa29c3f786924ae4b064f587b1e548ba102e0cc802b8a5adf7ccbadf033795974bfdaae5329a

data/CHANGELOG.md

@@ -1,8 +1,37 @@
 ## [Unreleased]
 
+## [1.2.0] - 2024-11-18
+
+### Added
+
+- Improved error messages
+- Option to define custom derived types
+- Option to use custom keys in paginated content
+- Option to deprecate individual fields, params, and types
+
+### Fixed
+
+- Fixed nullable enum fields raising for null input
+- Fixed auto-loading of return types
+- Fixed console spam when inspecting declarations
+- Fixed resolver method not being used when rendering a Hash
+- Fixed the ErrorsType template
+- Many fixes for OpenAPI export
+  - Fixed export of parameters for http methods without body
+  - Fixed export for PageType
+  - Fixed export for arrays of UUIDs, Dates, and Times
+  - Fixed export YML keys for namespaced controllers
+  - Reference plain types for repeated flat return types
+  - Made order of paths, verbs, responses and schemas deterministic
+
 ## [1.1.0] - 2024-11-16
 
+### Added
+
 - Response validation refined
+
+### Fixed
+
 - Bugfix for openapi export
 
 ## [1.0.0] - 2024-11-14

data/README.md

@@ -131,16 +131,18 @@ Taro.config.validate_responses = false
 The following type names are available by default and can be used as `type:`/`array_of:`/`page_of:` arguments:
 
 - `'Boolean'` - accepts and renders `true` or `false`
+- `'Date'` - accepts and renders a date string in ISO8601 format
+- `'DateTime'` - an alias for `'Time'`
 - `'Float'`
 - `'FreeForm'` - accepts and renders any JSON-serializable object, use with care
 - `'Integer'`
 - `'NoContent'` - renders an empty object, for use with `status: :no_content`
 - `'String'`
+- `'Time'` - accepts and renders a time string in ISO8601 format
 - `'Timestamp'` - renders a `Time` as unix timestamp integer and turns incoming integers into a `Time`
 - `'UUID'` - accepts and renders UUIDs
-- `'Date'` - accepts and renders a date string in ISO8601 format
-- `'Time'` - accepts and renders a time string in ISO8601 format
-- `'DateTime'` - an alias for `'Time'`
+
+Also, when using the generator, `ErrorsType` and `ErrorDetailsType` are generated as a starting point for unified error presentation. `ErrorsType` can render invalid `ActiveRecord` instances, `ActiveModel::Errors` and other data structures.
 
 ### Enums
 
@@ -168,7 +170,7 @@ end
 
 ### FAQ
 
-#### How to avoid repeating common error declarations?
+#### How do I avoid repeating common error declarations?
 
 Hook into the DSL in your base controller(s):
 
@@ -197,7 +199,7 @@ class AuthenticatedApiController < ApiBaseController
 end
 ```
 
-#### How to use context in my types?
+#### How do I use context in my types?
 
 Use [ActiveSupport::CurrentAttributes](https://api.rubyonrails.org/classes/ActiveSupport/CurrentAttributes.html).
 
@@ -211,13 +213,80 @@ class BikeType < ObjectType
 end
 ```
 
+#### How do I migrate from apipie-rails?
+
+First of all, if you don't need a better OpenAPI export, or better support for hashes and arrays, it might not be worth it.
+
+If you do:
+
+- note that `taro` currently only supports the latest OpenAPI standard (instead of v2 like `apipie-rails`)
+- extract complex param declarations into InputTypes
+- extract complex response declarations into ObjectTypes
+- replace `required: true` with `null: false` and `required: false` with `null: true`
+
+For a step-by-step migration, you might want to make `taro` use a different DSL then `apipie`:
+
+```ruby
+# config/initializers/taro.rb
+%i[api param returns].each do |m|
+  Taro::Rails::DSL.alias_method("taro_#{m}", m) # `taro_api` etc.
+  Taro::Rails::DSL.define_method(m) { |*a, **k, &b| super(*a, **k, &b) }
+end
+```
+
+#### How do I keep lengthy API descriptions out of my controller?
+
+```ruby
+module BikeUpdateDesc
+  extend ActiveSupport::Concern
+
+  included do
+    api 'Update a bike', description: 'Long description', tags: ['Bikes']
+    # lots of params and returns ...
+  end
+end
+
+class BikesController < ApplicationController
+  include BikeUpdateDesc
+  def update # ...
+end
+```
+
 #### Why do I have to use type name strings instead of the type constants?
 
 Why e.g. `field :id, type: 'UUID'` instead of `field :id, type: UUID`?
 
 The purpose of this is to reduce unnecessary autoloading of the whole type dependency tree in dev and test environments.
 
-This already works fo type classes – they don't trigger loading of referenced types unless used. The API declarations in controller classes still trigger auto-loading for now, but we aim to improve this in the future.
+#### Can I define my own derived types like `page_of` or `array_of`?
+
+Yes.
+
+```ruby
+# Implement ::derive_from in your custom type.
+class PreviewType < Taro::Types::Scalar::StringType
+  singleton_class.attr_reader :type_to_preview
+
+  def self.derive_from(other_type)
+    self.type_to_preview = other_type
+  end
+
+  def coerce_response
+    type_to_preview.new(object).coerce_response.to_s.truncate(100)
+  end
+end
+
+# Make it available in the DSL, e.g. in an initializer.
+Taro::Types::BaseType.define_derived_type :preview, 'PreviewType'
+
+# Usage:
+class MyController < ApplicationController
+  returns code: :ok, preview_of: 'BikeType'
+  def show
+    render json: BikeType.preview.render(Bike.find(params[:id]))
+  end
+end
+```
 
 ## Possible future features
 
@@ -227,7 +296,6 @@ This already works fo type classes – they don't trigger loading of referenced
 - sum types
 - api doc rendering based on export (e.g. rails engine with web ui)
 - [query logs metadata](https://github.com/rmosolgo/graphql-ruby/blob/dcaaed1cea47394fad61fceadf291ff3cb5f2932/lib/generators/graphql/install_generator.rb#L48-L52)
-- deprecation feature
 - maybe make `type:` optional for path params as they're always strings anyway
 - various openapi features
   - non-JSON content types (e.g. for file uploads)

data/lib/taro/errors.rb

@@ -1,7 +1,7 @@
 class Taro::Error < StandardError
   def message
     # clean up newlines introduced when setting the message with a heredoc
-    super.chomp.tr("\n", ' ')
+    super.chomp.sub(/\n(?=\S)/, ' ')
   end
 end
 

data/lib/taro/export/open_api_v3.rb

@@ -11,13 +11,13 @@ class Taro::Export::OpenAPIv3 < Taro::Export::Base # rubocop:disable Metrics/Cla
   def call(declarations:, title:, version:)
     @result = { openapi: '3.1.0', info: { title:, version: } }
     paths = export_paths(declarations)
-    @result[:paths] = paths if paths.any?
-    @result[:components] = { schemas: } if schemas.any?
+    @result[:paths] = paths.sort.to_h if paths.any?
+    @result[:components] = { schemas: schemas.sort.to_h } if schemas.any?
     self
   end
 
   def export_paths(declarations)
-    declarations.each_with_object({}) do |declaration, paths|
+    declarations.sort.each_with_object({}) do |declaration, paths|
       declaration.routes.each do |route|
         paths[route.openapi_path] ||= {}
         paths[route.openapi_path].merge! export_route(route, declaration)
@@ -31,30 +31,51 @@ class Taro::Export::OpenAPIv3 < Taro::Export::Base # rubocop:disable Metrics/Cla
         description: declaration.desc,
         summary: declaration.summary,
         tags: declaration.tags,
-        parameters: path_parameters(declaration, route),
+        parameters: route_parameters(declaration, route),
         requestBody: request_body(declaration, route),
         responses: responses(declaration),
       }.compact,
     }
   end
 
+  def route_parameters(declaration, route)
+    path_parameters(declaration, route) + query_parameters(declaration, route)
+  end
+
   def path_parameters(declaration, route)
     route.path_params.map do |param_name|
       param_field = declaration.params.fields[param_name] || raise(<<~MSG)
         Declaration missing for path param #{param_name} of route #{route.endpoint}
       MSG
 
-      {
-        name: param_field.name,
-        in: 'path',
-        description: param_field.desc,
-        required: true, # path params are always required in rails
-        schema: { type: param_field.openapi_type },
-      }.compact
+      # path params are always required in rails
+      export_parameter(param_field).merge(in: 'path', required: true)
     end
   end
 
+  def query_parameters(declaration, route)
+    return [] if route.can_have_request_body?
+
+    declaration.params.fields.filter_map do |name, param_field|
+      next if route.path_params.include?(name)
+
+      export_parameter(param_field).merge(in: 'query')
+    end
+  end
+
+  def export_parameter(field)
+    {
+      name: field.name,
+      deprecated: field.deprecated,
+      description: field.desc,
+      required: !field.null,
+      schema: { type: field.openapi_type },
+    }.compact
+  end
+
   def request_body(declaration, route)
+    return unless route.can_have_request_body?
+
     params = declaration.params
     body_param_fields = params.fields.reject do |name, _field|
       route.path_params.include?(name)
@@ -82,7 +103,7 @@ class Taro::Export::OpenAPIv3 < Taro::Export::Base # rubocop:disable Metrics/Cla
   end
 
   def responses(declaration)
-    declaration.returns.to_h do |code, type|
+    declaration.returns.sort.to_h do |code, type|
       [
         code.to_s,
         {
@@ -115,23 +136,29 @@ class Taro::Export::OpenAPIv3 < Taro::Export::Base # rubocop:disable Metrics/Cla
     # as it puts props like format together with the main type.
     # https://github.com/OAI/OpenAPI-Specification/issues/3148
     base = { oneOf: [base, { type: 'null' }] } if field.null
-    base[:description] = field.desc if field.desc
-    base[:default] = field.default if field.default_specified?
-    base[:enum] = field.enum if field.enum
-    base
+    base.merge(field_metadata(field))
   end
 
   def export_complex_field_ref(field)
     ref = extract_component_ref(field.type)
+    return ref if field_metadata(field).empty? && !field.null
+
     if field.null
       # RE nullable: https://stackoverflow.com/a/70658334
-      { description: field.desc, oneOf: [ref, { type: 'null' }] }.compact
-    elsif field.desc
+      { oneOf: [ref, { type: 'null' }] }
+    else # i.e. with metadata such as description or deprecated
       # https://github.com/OAI/OpenAPI-Specification/issues/2033
-      { description: field.desc, allOf: [ref] }
-    else
-      ref
-    end
+      { allOf: [ref] }
+    end.merge(field_metadata(field))
+  end
+
+  def field_metadata(field)
+    meta = {}
+    meta[:description] = field.desc if field.desc
+    meta[:deprecated] = field.deprecated unless field.deprecated.nil?
+    meta[:default] = field.default if field.default_specified?
+    meta[:enum] = field.enum if field.enum
+    meta
   end
 
   def extract_component_ref(type)
@@ -156,6 +183,7 @@ class Taro::Export::OpenAPIv3 < Taro::Export::Base # rubocop:disable Metrics/Cla
     required = type.fields.values.reject(&:null).map(&:name)
     {
       type: type.openapi_type,
+      deprecated: type.deprecated,
       description: type.desc,
       required: (required if required.any?),
       properties: type.fields.to_h { |name, f| [name, export_field(f)] },
@@ -166,6 +194,7 @@ class Taro::Export::OpenAPIv3 < Taro::Export::Base # rubocop:disable Metrics/Cla
   def enum_type_details(enum)
     {
       type: enum.item_type.openapi_type,
+      deprecated: enum.deprecated,
       description: enum.desc,
       enum: enum.values,
     }.compact
@@ -174,6 +203,7 @@ class Taro::Export::OpenAPIv3 < Taro::Export::Base # rubocop:disable Metrics/Cla
   def list_type_details(list)
     {
       type: 'array',
+      deprecated: list.deprecated,
       description: list.desc,
       items: export_type(list.item_type),
     }.compact

data/lib/taro/rails/declaration.rb

@@ -1,9 +1,9 @@
 class Taro::Rails::Declaration
-  attr_reader :desc, :summary, :params, :returns, :return_descriptions, :return_nestings, :routes, :tags
+  attr_reader :desc, :summary, :params, :return_defs, :return_descriptions, :return_nestings, :routes, :tags
 
   def initialize
     @params = Class.new(Taro::Types::InputType)
-    @returns = {}
+    @return_defs = {}
     @return_descriptions = {}
     @return_nestings = {}
   end
@@ -24,8 +24,11 @@ class Taro::Rails::Declaration
     status = self.class.coerce_status_to_int(code)
     raise_if_already_declared(status)
 
+    kwargs[:nesting] = nesting
+    check_return_kwargs(kwargs)
+
     kwargs[:defined_at] = caller_locations(1..2)[1]
-    returns[status] = return_type_from(nesting, **kwargs)
+    return_defs[status] = kwargs
 
     # response desc is required in openapi 3 – fall back to status code
     return_descriptions[status] = desc || code.to_s
@@ -34,14 +37,19 @@ class Taro::Rails::Declaration
     return_nestings[status] = nesting if nesting
   end
 
+  # Return types are evaluated lazily to avoid unnecessary autoloading
+  # of all types in dev/test envs.
+  def returns
+    @returns ||= evaluate_return_defs
+  end
+
   def raise_if_already_declared(status)
-    returns[status] &&
+    return_defs[status] &&
       raise(Taro::ArgumentError, "response for status #{status} already declared")
   end
 
   def parse_params(rails_params)
-    hash = params.new(rails_params.to_unsafe_h).coerce_input
-    hash
+    params.new(rails_params.to_unsafe_h).coerce_input
   end
 
   def finalize(controller_class:, action_name:)
@@ -67,10 +75,15 @@ class Taro::Rails::Declaration
   # TODO: these change when the controller class is renamed.
   # We might need a way to set `base`. Perhaps as a kwarg to `::api`?
   def add_openapi_names(controller_class:, action_name:)
-    base = "#{controller_class.name.chomp('Controller').sub('::', '_')}_#{action_name}"
+    base = "#{controller_class.name.chomp('Controller').gsub('::', '_')}_#{action_name}"
     params.openapi_name = "#{base}_Input"
+    params.define_singleton_method(:name) { openapi_name }
+
     returns.each do |status, return_type|
+      next if return_type.openapi_name? # only set for ad-hoc / nested return types
+
       return_type.openapi_name = "#{base}_#{status}_Response"
+      return_type.define_singleton_method(:name) { openapi_name }
     end
   end
 
@@ -86,19 +99,11 @@ class Taro::Rails::Declaration
 
   private
 
-  def return_type_from(nesting, **kwargs)
-    if nesting
-      # ad-hoc return type, requiring the actual return type to be nested
-      Class.new(Taro::Types::ObjectType).tap do |type|
-        type.field(nesting, null: false, **kwargs)
-      end
-    else
-      check_return_kwargs(kwargs)
-      Taro::Types::Coercion.call(kwargs)
-    end
-  end
-
   def check_return_kwargs(kwargs)
+    # For nested returns, evaluate_return_def calls ::field, which validates
+    # field options, but does not trigger type autoloading.
+    return evaluate_return_def(**kwargs) if kwargs[:nesting]
+
     if kwargs.key?(:null)
       raise Taro::ArgumentError, <<~MSG
         `null:` is not supported for top-level returns. If you want a nullable return
@@ -106,13 +111,32 @@ class Taro::Rails::Declaration
       MSG
     end
 
-    bad_keys = kwargs.keys - (Taro::Types::Coercion::KEYS + %i[code defined_at desc])
+    bad_keys = kwargs.keys - (Taro::Types::Coercion.keys + %i[code desc nesting])
     return if bad_keys.empty?
 
     raise Taro::ArgumentError, "Invalid `returns` options: #{bad_keys.join(', ')}"
   end
 
+  def evaluate_return_defs
+    return_defs.transform_values { |defi| evaluate_return_def(**defi) }
+  end
+
+  def evaluate_return_def(nesting:, **kwargs)
+    if nesting
+      # ad-hoc return type, requiring the actual return type to be nested
+      Class.new(Taro::Types::ObjectType).tap do |type|
+        type.field(nesting, null: false, **kwargs)
+      end
+    else
+      Taro::Types::Coercion.call(kwargs)
+    end
+  end
+
   def raise_missing_route(controller_class, action_name)
     raise(Taro::ArgumentError, "No route found for #{controller_class}##{action_name}")
   end
+
+  def <=>(other)
+    params.openapi_name <=> other.params.openapi_name
+  end
 end

data/lib/taro/rails/generators/install_generator.rb

@@ -12,7 +12,7 @@ class Taro::Rails::Generators::InstallGenerator < ::Rails::Generators::Base
   def create_type_files
     Dir["#{self.class.source_root}/**/*.erb"].each do |tmpl|
       dest_dir = options[:dir].chomp('/')
-      copy_file tmpl, "#{dest_dir}/#{File.basename(tmpl).sub('erb', 'rb')}"
+      template tmpl, "#{dest_dir}/#{File.basename(tmpl).sub('erb', 'rb')}"
     end
   end
   # :nocov:

data/lib/taro/rails/generators/templates/errors_type.erb

@@ -11,15 +11,20 @@ class ErrorsType < Taro::Types::ListType
   end
 
   def coerce_response
-    case object.class.name
-    when 'ActiveRecord::Base'
-      super(object.errors.errors)
-    when 'ActiveModel::Errors'
-      super(object.errors)
-    when 'Hash', 'Interactor::Context'
-      super(object[:errors])
-    else # e.g. Array
-      super(object)
-    end
+    list =
+      case object<%- if defined?(ActiveRecord) %>
+      when ActiveModel::Errors
+        object.errors
+      when ActiveRecord::Base
+        object.errors.errors<%- end %>
+      when Array
+        object
+      when Hash<%- if defined?(Interactor::Context) %>, Interactor::Context<%- end %>
+        object.to_h.fetch(:errors)
+      else
+        response_error("must be an Enumerable or an object with errors")
+      end
+
+    list.map { |el| self.class.item_type.new(el).coerce_response }
   end
 end

data/lib/taro/rails/normalized_route.rb

@@ -26,4 +26,12 @@ Taro::Rails::NormalizedRoute = Data.define(:rails_route) do
     controller, action = rails_route.requirements.values_at(:controller, :action)
     "#{controller}##{action}"
   end
+
+  def can_have_request_body?
+    %w[patch post put].include?(verb)
+  end
+
+  def inspect
+    %(#<#{self.class} "#{verb} #{openapi_path}">)
+  end
 end

data/lib/taro/rails/tasks/export.rake

@@ -10,6 +10,10 @@ task 'taro:export' => :environment do
     version: Taro.config.api_version,
   )
 
-  data = export.result.send("to_#{Taro.config.export_format}")
+  data = export.send("to_#{Taro.config.export_format}")
+
+  FileUtils.mkdir_p(File.dirname(Taro.config.export_path))
   File.write(Taro.config.export_path, data)
+
+  puts "Exported #{Taro.config.api_name} to #{Taro.config.export_path}"
 end

data/lib/taro/types/base_type.rb

@@ -9,6 +9,8 @@
 Taro::Types::BaseType = Data.define(:object) do
   require_relative "shared"
   extend Taro::Types::Shared::AdditionalProperties
+  extend Taro::Types::Shared::Deprecation
+  extend Taro::Types::Shared::DerivedTypes
   extend Taro::Types::Shared::Description
   extend Taro::Types::Shared::OpenAPIName
   extend Taro::Types::Shared::OpenAPIType

data/lib/taro/types/coercion.rb

@@ -1,42 +1,52 @@
 module Taro::Types::Coercion
-  KEYS = %i[type array_of page_of].freeze
-
   class << self
     def call(arg)
       validate_hash(arg)
       from_hash(arg)
     end
 
+    # Coercion keys can be expanded by the DerivedTypes module.
+    def keys
+      @keys ||= %i[type]
+    end
+
+    def derived_suffix
+      '_of'
+    end
+
     private
 
     def validate_hash(arg)
       arg.is_a?(Hash) || raise(Taro::ArgumentError, <<~MSG)
-        Type coercion argument must be a Hash, got: #{arg.inspect} (#{arg.class})
+        Type coercion argument must be a Hash, got: #{arg.class}
       MSG
 
-      types = arg.slice(*KEYS)
+      types = arg.slice(*keys)
       types.size == 1 || raise(Taro::ArgumentError, <<~MSG)
-        Exactly one of type, array_of, or page_of must be given, got: #{types}
+        Exactly one of #{keys.join(', ')} must be given, got: #{types}
       MSG
     end
 
     def from_hash(hash)
-      if hash[:type]
-        from_string(hash[:type])
-      elsif (inner_type = hash[:array_of])
-        from_string(inner_type).array
-      elsif (inner_type = hash[:page_of])
-        from_string(inner_type).page
-      else
-        raise NotImplementedError, 'Unsupported type coercion'
+      keys.each do |key|
+        next unless (value = hash[key])
+
+        # e.g. `returns type: 'MyType'` -> MyType
+        return from_string(value) if key == :type
+
+        # DerivedTypes
+        # e.g. `returns array_of: 'MyType'` -> MyType.array
+        return from_string(value).send(key.to_s.chomp(derived_suffix))
       end
+
+      raise NotImplementedError, "Unsupported type coercion #{hash}"
     end
 
     def from_string(arg)
       shortcuts[arg] || from_class(Object.const_get(arg.to_s))
     rescue NameError
       raise Taro::ArgumentError, <<~MSG
-        Unsupported type: #{arg}. It should be a type-class name
+        No such type: #{arg}. It should be a type-class name
         or one of #{shortcuts.keys.map(&:inspect).join(', ')}.
       MSG
     end

data/lib/taro/types/field.rb

@@ -1,11 +1,11 @@
 require_relative 'field_validation'
 
-Taro::Types::Field = Data.define(:name, :type, :null, :method, :default, :enum, :defined_at, :desc) do
+Taro::Types::Field = Data.define(:name, :type, :null, :method, :default, :enum, :defined_at, :desc, :deprecated) do
   include Taro::Types::FieldValidation
 
-  def initialize(name:, type:, null:, method: name, default: :none, enum: nil, defined_at: nil, desc: nil)
+  def initialize(name:, type:, null:, method: name, default: :none, enum: nil, defined_at: nil, desc: nil, deprecated: nil)
     enum = coerce_to_enum(enum)
-    super(name:, type:, null:, method:, default:, enum:, defined_at:, desc:)
+    super(name:, type:, null:, method:, default:, enum:, defined_at:, desc:, deprecated:)
   end
 
   def value_for_input(object)
@@ -40,14 +40,15 @@ Taro::Types::Field = Data.define(:name, :type, :null, :method, :default, :enum,
   end
 
   def retrieve_response_value(object, context, object_is_hash)
-    if object_is_hash
-      retrieve_hash_value(object)
-    elsif context&.resolve?(method)
+    if context&.resolve?(method)
       context.public_send(method)
+    elsif object_is_hash
+      retrieve_hash_value(object)
     elsif object.respond_to?(method, true)
       object.public_send(method)
     else
-      raise_response_coercion_error(object)
+      # Note that the ObjectCoercion module rescues this and adds context.
+      raise Taro::ResponseError, "No such method or resolver `:#{method}`."
     end
   end
 
@@ -65,14 +66,5 @@ Taro::Types::Field = Data.define(:name, :type, :null, :method, :default, :enum,
 
     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

@@ -18,7 +18,7 @@ module Taro::Types::FieldValidation
   end
 
   def validate_enum_inclusion(value, for_input)
-    return if enum.nil? || enum.include?(value)
+    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})

data/lib/taro/types/list_type.rb

@@ -2,7 +2,6 @@
 # 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
@@ -20,11 +19,10 @@ class Taro::Types::ListType < Taro::Types::BaseType
     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)
+  def self.default_openapi_name
+    "#{item_type.openapi_name}_List"
   end
+
+  define_derived_type :array, 'Taro::Types::ListType'
 end

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

@@ -1,6 +1,7 @@
 class Taro::Types::ObjectTypes::FreeFormType < Taro::Types::ObjectType
   self.desc = 'An arbitrary, unvalidated Hash or JSON object. Use with care.'
   self.additional_properties = true
+  self.openapi_name = 'FreeForm'
 
   def coerce_input
     object.is_a?(Hash) && object || input_error('must be a Hash')

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

@@ -1,5 +1,6 @@
 class Taro::Types::ObjectTypes::NoContentType < Taro::Types::ObjectType
   self.desc = 'An empty response'
+  self.openapi_name = 'NoContent'
 
   # render takes no arguments in this case
   def self.render

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

@@ -1,4 +1,6 @@
 class Taro::Types::ObjectTypes::PageInfoType < Taro::Types::ObjectType
+  self.openapi_name = 'PageInfo'
+
   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)'

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

@@ -4,42 +4,32 @@
 #
 # The gem rails_cursor_pagination must be installed to use this.
 #
-class Taro::Types::ObjectTypes::PageType < Taro::Types::BaseType
-  extend Taro::Types::Shared::DerivableType
+class Taro::Types::ObjectTypes::PageType < Taro::Types::ObjectType
   extend Taro::Types::Shared::ItemType
 
+  def self.derive_from(from_type)
+    super
+    field(:page, array_of: from_type.name, null: false)
+    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 coerce_response(after:, limit: 20, order_by: nil, order: nil)
-    list = RailsCursorPagination::Paginator.new(
-      object, limit:, order_by:, order:, after:
+  def self.render(relation, after:, limit: 20, order_by: nil, order: nil)
+    result = RailsCursorPagination::Paginator.new(
+      relation, 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
+    result[:page].map! { |el| el.fetch(:data) }
 
-    {
-      self.class.items_key => items,
-      page_info: Taro::Types::ObjectTypes::PageInfoType.new(list[:page_info]).coerce_response,
-    }
+    super(result)
   end
 
-  # support overrides, e.g. based on item_type
-  def self.items_key
-    :page
+  def self.default_openapi_name
+    "#{item_type.openapi_name}_Page"
   end
-end
 
-# add shortcut to other types
-class Taro::Types::BaseType
-  def self.page
-    Taro::Types::ObjectTypes::PageType.for(self)
-  end
+  define_derived_type :page, 'Taro::Types::ObjectTypes::PageType'
 end

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

@@ -1,5 +1,6 @@
 class Taro::Types::Scalar::ISO8601DateType < Taro::Types::ScalarType
   self.desc = 'Represents a time as Date in ISO8601 format.'
+  self.openapi_name = 'ISO8601Date'
   self.openapi_type = :string
 
   PATTERN = /\A\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])\z/

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

@@ -1,5 +1,6 @@
 class Taro::Types::Scalar::ISO8601DateTimeType < Taro::Types::ScalarType
   self.desc = 'Represents a time as DateTime in ISO8601 format.'
+  self.openapi_name = 'ISO8601DateTime'
   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/

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

@@ -1,5 +1,6 @@
 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_name = 'Timestamp'
   self.openapi_type = :integer
 
   def coerce_input

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

@@ -1,5 +1,6 @@
 class Taro::Types::Scalar::UUIDv4Type < Taro::Types::ScalarType
   self.desc = "A UUID v4 string"
+  self.openapi_name = 'UUIDv4'
   self.openapi_type = :string
 
   PATTERN = /\A\h{8}-?(?:\h{4}-?){3}\h{12}\z/

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

@@ -0,0 +1,3 @@
+module Taro::Types::Shared::Deprecation
+  attr_accessor :deprecated
+end

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

@@ -0,0 +1,27 @@
+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.
+  # 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)
+
+    ckey = :"#{name}#{Taro::Types::Coercion.derived_suffix}"
+    ckeys = Taro::Types::Coercion.keys
+    raise ArgumentError, "#{ckey} is already in use" if ckeys.include?(ckey)
+
+    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
+    end
+
+    ckeys << ckey
+  end
+
+  def derived_types
+    @derived_types ||= {}
+  end
+end

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

@@ -8,6 +8,8 @@ module Taro::Types::Shared::Errors
   end
 
   def coerce_error_message(msg)
-    "#{object.inspect} (#{object.class}) is not valid as #{self.class}: #{msg}"
+    type_desc = (self.class.name || self.class.superclass.name)
+                .sub(/^Taro::Types::.*?([^:]+)Type$/, '\1')
+    "#{object.class} is not valid as #{type_desc}: #{msg}"
   end
 end

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

@@ -2,7 +2,7 @@
 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.
+  # 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:)
@@ -27,11 +27,12 @@ module Taro::Types::Shared::Fields
     [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}")
+    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_key} must be a String for field #{name} at #{defined_at}")
+      raise(Taro::ArgumentError, "#{type_keys.first} must be a String for field #{name} at #{defined_at}")
   end
 
   def validate_no_override(name, defined_at:)
@@ -46,7 +47,7 @@ module Taro::Types::Shared::Fields
   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:)
+      Taro::Types::Field.new(**field_def.except(*Taro::Types::Coercion.keys), type:)
     end
   end
 

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

@@ -6,6 +6,7 @@ module Taro::Types::Shared::ItemType
     item_type.nil? || new_type == item_type || raise_mixed_types(new_type)
     @item_type = new_type
   end
+  alias_method :derive_from, :item_type=
 
   def raise_mixed_types(new_type)
     raise Taro::ArgumentError, <<~MSG

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

@@ -3,6 +3,8 @@ 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
 
@@ -11,6 +13,17 @@ 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,13 +5,19 @@ 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')
     @openapi_name = arg
   end
 
-  def default_openapi_name # rubocop:disable Metrics
+  def default_openapi_name
     if self < Taro::Types::EnumType ||
        self < Taro::Types::InputType ||
        self < Taro::Types::ObjectType
@@ -19,12 +25,8 @@ module Taro::Types::Shared::OpenAPIName
         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'
+      raise Taro::Error, 'no default_openapi_name implemented for this type'
     end
   end
 end

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

@@ -1,8 +1,8 @@
-# The `::render` method is intended for use in controllers.
-# Special types (e.g. PageType) may accept kwargs for `#coerce_response`.
 module Taro::Types::Shared::Rendering
-  def render(object, opts = {})
-    result = new(object).coerce_response(**opts)
+  # The `::render` method is intended for use in controllers.
+  # Overrides of this method must call super.
+  def render(object)
+    result = new(object).coerce_response
     self.last_render = [self, result.__id__]
     result
   end

data/lib/taro/version.rb

@@ -1,4 +1,4 @@
 # :nocov:
 module Taro
-  VERSION = "1.1.0"
+  VERSION = "1.2.0"
 end

data/tasks/benchmark.rake

@@ -13,7 +13,7 @@ task :benchmark do
     field :version, type: 'Float', null: false
   end
 
-  type = Taro::Types::ListType.for(item_type)
+  type = item_type.array
 
   # 143.889k (± 2.7%) i/s -    723.816k in   5.034247s
   Benchmark.ips do |x|

metadata

@@ -1,14 +1,15 @@
 --- !ruby/object:Gem::Specification
 name: taro
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.2.0
 platform: ruby
 authors:
 - Janosch Müller
+- Johannes Opper
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-11-16 00:00:00.000000000 Z
+date: 2024-11-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rack
@@ -27,7 +28,6 @@ dependencies:
 description: This library provides an object-based type system for RESTful Ruby APIs,
   with built-in parameter parsing, response rendering, and OpenAPI schema export.
 email:
-- janosch84@gmail.com
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -90,7 +90,8 @@ files:
 - lib/taro/types/shared.rb
 - lib/taro/types/shared/additional_properties.rb
 - lib/taro/types/shared/custom_field_resolvers.rb
-- lib/taro/types/shared/derivable_types.rb
+- lib/taro/types/shared/deprecation.rb
+- lib/taro/types/shared/derived_types.rb
 - lib/taro/types/shared/description.rb
 - lib/taro/types/shared/errors.rb
 - lib/taro/types/shared/fields.rb
@@ -125,7 +126,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.16
+rubygems_version: 3.5.22
 signing_key:
 specification_version: 4
 summary: Typed Api using Ruby Objects.

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

@@ -1,9 +0,0 @@
-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