taro 1.1.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 36e27c067e70b65d503a3c78b61e9efc05d8995f9927edfaf6f66ff4fae70b25
-  data.tar.gz: 131fc3d1bea432320046c4e5c220dff0a3ead87d8a2f3d12310cdd847b2e50c1
+  metadata.gz: 41f14035882a39e03a7bae9c799a42c9fa63414e4201fbbab7f876d54d8d214b
+  data.tar.gz: 768b505506f8ad58792d0d86b6152f1aa60da98419aef111b9fc187ee74eab42
 SHA512:
-  metadata.gz: 9d44a2c33be8175c6b59b1426921fd339c4e4125bf7fa076da27f4b9c17bcf1efb69aa0233c8e91f16804b086f250b37fddb0e6e6dce2debbf0349fc96ac832d
-  data.tar.gz: 59d1a63e68b5560ee7cf0243ff3ccf6684376249745727e6695576821285e8dc1d64018a5f8e8a962f9d7dcea74c1e6bc9d27dd664662d327c257d81505b6c23
+  metadata.gz: 27607c95ed9c5a7ab2c4d579dec41357657f24c694f43eac06b15677a82e491fd5986c5cad8b7bf999ee23ee456d75cc2c90debee47e93d02cdc901b4e45f498
+  data.tar.gz: f99bfdfe66f7a09ac1746c23e2671bcec7f20cfee23e980db76561f14e1ea082bc2fcc59e4650af8732d7e608a8b7c012473dc0f862bb15ff9d89501a641c825

data/CHANGELOG.md

@@ -1,8 +1,47 @@
 ## [Unreleased]
 
+## [1.3.0] - 2024-11-25
+
+### Added
+
+- Support for string patterns (on StringType children and in export)
+
+### Fixed
+
+- Fixed OpenAPI export of params with enum (inline & type-based)
+
+## [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)
@@ -237,8 +305,7 @@ This already works fo type classes – they don't trigger loading of referenced
   - mixed enums
   - nullable enums
   - string format specifications (e.g. binary, int64, password ...)
-  - string pattern specifications
-  - string minLength and maxLength
+  - string minLength and maxLength (substitute: `self.pattern = /\A.{3,5}\z/`)
   - number minimum, exclusiveMinimum, maximum, multipleOf
   - readOnly, writeOnly
 

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,58 @@ 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)
+    validate_path_or_query_parameter(field)
+
+    {
+      name: field.name,
+      deprecated: field.deprecated,
+      description: field.desc,
+      required: !field.null,
+      schema: export_field(field).except(:deprecated, :description),
+    }.compact
+  end
+
+  def validate_path_or_query_parameter(field)
+    [:array, :object].include?(field.type.openapi_type) &&
+      raise("Unexpected object as path/query param #{field.name}: #{field.type}")
+  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)
@@ -66,7 +94,7 @@ class Taro::Export::OpenAPIv3 < Taro::Export::Base # rubocop:disable Metrics/Cla
     body_input_type.openapi_name = params.openapi_name
 
     # For polymorphic routes (more than one for the same declaration),
-    # we can't use refs because they request body might differ.
+    # we can't use refs because their request body might differ:
     # Different params might be in the path vs. in the request body.
     use_refs = !declaration.polymorphic_route?
     schema = request_body_schema(body_input_type, use_refs:)
@@ -82,7 +110,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,
         {
@@ -94,13 +122,17 @@ class Taro::Export::OpenAPIv3 < Taro::Export::Base # rubocop:disable Metrics/Cla
   end
 
   def export_type(type)
-    if type < Taro::Types::ScalarType
+    if type < Taro::Types::ScalarType && !custom_scalar_type?(type)
       { type: type.openapi_type }
     else
       extract_component_ref(type)
     end
   end
 
+  def custom_scalar_type?(type)
+    type < Taro::Types::ScalarType && (type.openapi_pattern || type.deprecated)
+  end
+
   def export_field(field)
     if field.type < Taro::Types::ScalarType
       export_scalar_field(field)
@@ -115,23 +147,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)
@@ -147,6 +185,8 @@ class Taro::Export::OpenAPIv3 < Taro::Export::Base # rubocop:disable Metrics/Cla
       enum_type_details(type)
     elsif type < Taro::Types::ListType
       list_type_details(type)
+    elsif custom_scalar_type?(type)
+      custom_scalar_type_details(type)
     else
       raise NotImplementedError, "Unsupported type: #{type}"
     end
@@ -156,6 +196,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 +207,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,11 +216,21 @@ 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
   end
 
+  def custom_scalar_type_details(scalar)
+    {
+      type: scalar.openapi_type,
+      deprecated: scalar.deprecated,
+      description: scalar.desc,
+      pattern: scalar.openapi_pattern,
+    }.compact
+  end
+
   def assert_unique_openapi_name(type)
     @name_to_type_map ||= {}
     if (prev = @name_to_type_map[type.openapi_name]) && type != prev

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