taro 1.1.0 → 1.3.0

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,11 +1,11 @@
 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/
+  self.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)
+    if object.instance_of?(String) && object.match?(pattern)
       Date.parse(object)
     else
       input_error("must be a ISO8601 formatted string")

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

@@ -1,11 +1,11 @@
 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/
+  self.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)
+    if object.instance_of?(String) && object.match?(pattern)
       DateTime.iso8601(object)
     else
       input_error("must be a ISO8601 formatted string")

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

@@ -2,14 +2,25 @@ 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')
+    object.instance_of?(String) || input_error('must be a String')
+
+    pattern.nil? || pattern.match?(object) ||
+      input_error("must match pattern #{pattern.inspect}")
+
+    object
   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
+    str =
+      case object
+      when String then object
+      when Symbol then object.to_s
+      else response_error('must be a String or Symbol')
+      end
+
+    pattern.nil? || pattern.match?(str) ||
+      response_error("must match pattern #{pattern.inspect}")
+
+    str
   end
 end

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,22 +1,5 @@
-class Taro::Types::Scalar::UUIDv4Type < Taro::Types::ScalarType
+class Taro::Types::Scalar::UUIDv4Type < Taro::Types::Scalar::StringType
   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
+  self.openapi_name = 'UUIDv4'
+  self.pattern = /\A\h{8}-?(?:\h{4}-?){3}\h{12}\z/
 end

data/lib/taro/types/scalar_type.rb

@@ -1,5 +1,6 @@
 # Abstract base class for scalar types, i.e. types without fields.
 class Taro::Types::ScalarType < Taro::Types::BaseType
+  include Taro::Types::Shared::Pattern
 end
 
 module Taro::Types::Scalar

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

@@ -15,8 +15,8 @@ module Taro::Types::Shared::CustomFieldResolvers
     end
 
     def method_added(name)
-      if name == :object
-        raise(Taro::ArgumentError, '#object is a reserved, internally used method name')
+      if [:object, :pattern].include?(name)
+        raise(Taro::ArgumentError, "##{name} 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

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/pattern.rb

@@ -0,0 +1,69 @@
+module Taro::Types::Shared::Pattern
+  def pattern
+    self.class.pattern
+  end
+
+  def self.included(base)
+    base.extend(ClassMethods)
+  end
+
+  module ClassMethods
+    attr_reader :pattern, :openapi_pattern
+
+    def pattern=(regexp)
+      openapi_type == :string ||
+        raise(Taro::RuntimeError, 'pattern requires openapi_type :string')
+
+      @pattern = regexp
+      @openapi_pattern = Taro::Types::Shared::Pattern.to_es262(regexp)
+    end
+  end
+
+  def self.to_es262(regexp)
+    validate(regexp).source.gsub(
+      /#{NOT_ESCAPED}\\[Ahz]/,
+      { '\\A' => '^', '\\h' => '[0-9a-fA-F]', '\\z' => '$' }
+    )
+  end
+
+  def self.validate(regexp)
+    validate_no_flags(regexp)
+    validate_not_empty(regexp)
+    validate_no_advanced_syntax(regexp)
+    regexp
+  end
+
+  def self.validate_no_flags(regexp)
+    (flags = regexp.inspect[%r{/\w+\z}]) &&
+      raise(Taro::ArgumentError, "pattern flags (#{flags}) are not supported")
+  end
+
+  def self.validate_not_empty(regexp)
+    regexp.source.empty? &&
+      raise(Taro::ArgumentError, 'pattern cannot be empty')
+  end
+
+  def self.validate_no_advanced_syntax(regexp)
+    return unless (match = regexp.source.match(ADVANCED_RUBY_REGEXP_SYNTAX_REGEXP))
+
+    feature = match.named_captures.find { |k, v| break k if v }
+    raise Taro::ArgumentError, <<~MSG
+      pattern uses non-JS syntax #{match} (#{feature}) at index #{match.begin(0)}
+    MSG
+  end
+
+  NOT_ESCAPED = /(?<!\\)(?:\\\\)*\K/
+
+  # This is not 100% accurate, e.g. /[?+]/ is a false positive, but it should be
+  # good enough so we don't need regexp_parser or js_regex as a dependency.
+  ADVANCED_RUBY_REGEXP_SYNTAX_REGEXP = /
+    #{NOT_ESCAPED}
+    (?:
+        (?<a special group or lookaround> \(\?[^:] )
+      | (?<a Ruby-specific escape> \\[a-zA-Z&&[^bBdDsSwWAzfhnrv]] )
+      | (?<an advanced quantifier> [?*+}][?+] )
+      | (?<a nested set> \[[^\]]*(?<!\\)\[ )
+      | (?<a set intersection> && )
+    )
+  /x
+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.3.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.3.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-25 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
@@ -98,6 +99,7 @@ files:
 - lib/taro/types/shared/object_coercion.rb
 - lib/taro/types/shared/openapi_name.rb
 - lib/taro/types/shared/openapi_type.rb
+- lib/taro/types/shared/pattern.rb
 - lib/taro/types/shared/rendering.rb
 - lib/taro/version.rb
 - tasks/benchmark.rake
@@ -125,7 +127,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