taro 1.2.0 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5007f07dcb3230a1a45011138c19cc0f233e0a0e0fa81d64d554ee3d5cc4a82e
-  data.tar.gz: 99dde57ec71bb2724a29005e644a0bb23d642df11fe4555bd9203340169814df
+  metadata.gz: d30f413c950e02e52f99ed96d234acdba122c92ec4e39dd2d35e87c899ed8a13
+  data.tar.gz: 5ed455623397ce6fbcb19412710bf98bc7ca2b6898db193a2cf858104a149327
 SHA512:
-  metadata.gz: abb5fb481da01a4a50b19e891c3373b42372c97993788ed24c51b07146e087e25d040bc4ea077606a14013633b30f6254f6ced2e939ba9b039b341d95f918211
-  data.tar.gz: b5dd6c2222598ad3d8ee64c64fd0fc6c40299c3f071b08317d17aa29c3f786924ae4b064f587b1e548ba102e0cc802b8a5adf7ccbadf033795974bfdaae5329a
+  metadata.gz: ba99529dd914238371708a80b5f3f6497a4884a042a0e11ec7e9b557107379d0bfa2232b6a71137623658651e5d920f8ad47ab683119ae5ce105261fa627b980
+  data.tar.gz: 26b2652184c485aa7970707373cfe4ebfdecd3141fc7e995066060b5a0a5452b1e749d6e16fdc3d99e34a199434ed9edc7400d89fe8f8ed32df442d764d06175

data/CHANGELOG.md

@@ -1,5 +1,26 @@
 ## [Unreleased]
 
+## [1.4.0] - 2024-11-27
+
+### Added
+
+- added operationId to OpenAPI export
+
+### Fixed
+
+- fixed potential ref name clashes in OpenAPI export
+  - e.g. `FooBar::BazController` & `Foo::BarBazController`
+
+## [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

data/README.md

@@ -305,8 +305,7 @@ end
   - 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/export/open_api_v3.rb

@@ -31,9 +31,10 @@ class Taro::Export::OpenAPIv3 < Taro::Export::Base # rubocop:disable Metrics/Cla
         description: declaration.desc,
         summary: declaration.summary,
         tags: declaration.tags,
+        operationId: route.openapi_operation_id,
         parameters: route_parameters(declaration, route),
         requestBody: request_body(declaration, route),
-        responses: responses(declaration),
+        responses: responses(declaration, route),
       }.compact,
     }
   end
@@ -64,15 +65,22 @@ class Taro::Export::OpenAPIv3 < Taro::Export::Base # rubocop:disable Metrics/Cla
   end
 
   def export_parameter(field)
+    validate_path_or_query_parameter(field)
+
     {
       name: field.name,
       deprecated: field.deprecated,
       description: field.desc,
       required: !field.null,
-      schema: { type: field.openapi_type },
+      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?
 
@@ -84,10 +92,10 @@ class Taro::Export::OpenAPIv3 < Taro::Export::Base # rubocop:disable Metrics/Cla
 
     body_input_type = Class.new(params)
     body_input_type.fields.replace(body_param_fields)
-    body_input_type.openapi_name = params.openapi_name
+    body_input_type.openapi_name = "#{route.openapi_operation_id}_Input"
 
     # 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:)
@@ -102,7 +110,9 @@ class Taro::Export::OpenAPIv3 < Taro::Export::Base # rubocop:disable Metrics/Cla
     end
   end
 
-  def responses(declaration)
+  def responses(declaration, route)
+    name_anonymous_return_types(declaration, route)
+
     declaration.returns.sort.to_h do |code, type|
       [
         code.to_s,
@@ -114,14 +124,26 @@ class Taro::Export::OpenAPIv3 < Taro::Export::Base # rubocop:disable Metrics/Cla
     end
   end
 
+  def name_anonymous_return_types(declaration, route)
+    declaration.returns.each do |code, type|
+      next if type.openapi_name?
+
+      type.openapi_name = "#{route.openapi_operation_id}_#{code}_Response"
+    end
+  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)
@@ -174,6 +196,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
@@ -209,6 +233,15 @@ class Taro::Export::OpenAPIv3 < Taro::Export::Base # rubocop:disable Metrics/Cla
     }.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

@@ -53,11 +53,6 @@ class Taro::Rails::Declaration
   end
 
   def finalize(controller_class:, action_name:)
-    add_routes(controller_class:, action_name:)
-    add_openapi_names(controller_class:, action_name:)
-  end
-
-  def add_routes(controller_class:, action_name:)
     routes = Taro::Rails::RouteFinder.call(controller_class:, action_name:)
     routes.any? || raise_missing_route(controller_class, action_name)
     self.routes = routes
@@ -72,21 +67,6 @@ class Taro::Rails::Declaration
     routes.size > 1
   end
 
-  # 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').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
-
   require 'rack'
   def self.coerce_status_to_int(status)
     # support using http status numbers directly
@@ -137,6 +117,6 @@ class Taro::Rails::Declaration
   end
 
   def <=>(other)
-    params.openapi_name <=> other.params.openapi_name
+    routes.first.openapi_operation_id <=> other.routes.first.openapi_operation_id
   end
 end

data/lib/taro/rails/normalized_route.rb

@@ -18,15 +18,26 @@ Taro::Rails::NormalizedRoute = Data.define(:rails_route) do
     rails_route.path.spec.to_s.gsub('(.:format)', '').gsub(/:(\w+)/, '{\1}')
   end
 
+  def openapi_operation_id
+    "#{verb}_#{action}_#{controller.gsub('/', '__')}"
+  end
+
   def path_params
     openapi_path.scan(/{(\w+)}/).flatten.map(&:to_sym)
   end
 
   def endpoint
-    controller, action = rails_route.requirements.values_at(:controller, :action)
     "#{controller}##{action}"
   end
 
+  def action
+    rails_route.requirements[:action]
+  end
+
+  def controller
+    rails_route.requirements[:controller]
+  end
+
   def can_have_request_body?
     %w[patch post put].include?(verb)
   end
@@ -34,4 +45,5 @@ Taro::Rails::NormalizedRoute = Data.define(:rails_route) do
   def inspect
     %(#<#{self.class} "#{verb} #{openapi_path}">)
   end
+  alias to_s inspect
 end

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

@@ -2,11 +2,10 @@ 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

@@ -2,11 +2,10 @@ 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/uuid_v4_type.rb

@@ -1,23 +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_name = 'UUIDv4'
-  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.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/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/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: taro
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.4.0
 platform: ruby
 authors:
 - Janosch Müller
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-11-18 00:00:00.000000000 Z
+date: 2024-11-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rack
@@ -99,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