taro 2.3.0 → 2.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c96d6fd71ad22df31d5ab4cefb09389fd7ed5b41b5dd8821132fa2c5fa322837
-  data.tar.gz: f56362229e93f2f8c51a5490245d4a37e224015fecd42bb86a35926a01e8d776
+  metadata.gz: d8f629d8573ed34c2d60303a387e99cae4cc9fcb0b14901d7080def1e27d0d90
+  data.tar.gz: 40c3ae606ade65922c5b69f9dd86353f2740d061b6d7094f61abe906e5f9198f
 SHA512:
-  metadata.gz: 34ad2aedee3c3a21973420ca5e1185024c7d6b127ee9ca914b847134939bcd136e70f10130607b8392ce8044dfcb7c8014fa306d00d81b81266d68fcdad19b95
-  data.tar.gz: 1bec2fbada3a23267f87195323b2b112297c21e78c22281071bd2ec84a7359f78836ed250e85ae3f3d1765f428dd7ff1bdaaf92f5df2bd17883abed11b7a39eb
+  metadata.gz: 34b8e8d9ef5c2f016f56a887b674fa243ae6074fc59e4d29a1cb1873c4dfc3e87d8c24a37dd93a461ad71fc0fd38849462360bed7f6f9a1cca89e37fb3ad192b
+  data.tar.gz: d99f3bdc2e40e555a1a0b54dcac6a62d5774b6ae2c7c0d5e05c5ee0f1457864af696b37949173d8189769b03b5d9ce589eb1f49d855209c5c2bccadf32b51d84

data/CHANGELOG.md

@@ -1,5 +1,17 @@
 ## [Unreleased]
 
+## [2.5.0] - 2025-04-16
+
+### Added
+
+- Support for setting `openapi_format` for types and during export
+
+## [2.4.0] - 2025-03-11
+
+### Added
+
+- `PageWithTotalCountType` for paginated responses with a total count
+
 ## [2.3.0] - 2025-02-24
 
 ### Added

data/README.md

@@ -65,7 +65,7 @@ class BikesController < ApplicationController
 
   # Support for arrays and paginated lists is built-in.
   api     'List all bikes'
-  returns code: :ok, array_of: 'BikeType', desc: 'list of bikes'
+  returns code: :ok, array_of: 'BikeType', desc: 'List of bikes'
   def index
     render json: BikeType.array.render(Bike.all)
   end
@@ -89,9 +89,6 @@ class BikeType < ObjectType
   # Fields can reference other types and arrays of values
   field :users, array_of: 'UserType', null: false
 
-  # Pagination is built-in for big lists
-  field :parts, page_of: 'PartType', null: false
-
   # Custom methods can be chosen to resolve fields
   field :has_brand, type: 'Boolean', null: false, method: :brand?
 
@@ -273,6 +270,32 @@ class BikeType < ObjectType
 end
 ```
 
+### Pagination
+
+Use `page_of:` to declare a paginated response. Call `page.render` on a type to render a page of records.
+
+```ruby
+api     'List all bikes'
+param   :cursor, type: 'String', null: true, desc: 'Show bikes after this cursor'
+returns code: :ok, page_of: 'BikeType', desc: 'A page of bikes'
+def index
+  render json: BikeType.page.render(Bike.all, after: params[:cursor])
+end
+```
+
+By default, the response does not include a total count. To include it, use `page_with_total_count`:
+
+```ruby
+api     'List all bikes'
+param   :cursor, type: 'String', null: true, desc: 'Show bikes after this cursor'
+returns code: :ok, page_with_total_count_of: 'BikeType', desc: 'A page of bikes'
+def index
+  render json: BikeType.page_with_total_count.render(Bike.all, after: params[:cursor])
+end
+```
+
+See also: [Derived types](#derived-types).
+
 ## FAQ
 
 ### How do I render API docs?
@@ -343,6 +366,7 @@ 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.
 
+<a name="derived-types"></a>
 ### Can I define my own derived types like `page_of` or `array_of`?
 
 Yes.
@@ -386,7 +410,6 @@ end
   - mixed arrays
   - mixed enums
   - nullable enums
-  - string format specifications (e.g. binary, int64, password ...)
   - 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

@@ -129,7 +129,7 @@ class Taro::Export::OpenAPIv3 < Taro::Export::Base # rubocop:disable Metrics/Cla
 
   def export_type(type)
     if type < Taro::Types::ScalarType && !custom_scalar_type?(type)
-      { type: type.openapi_type }
+      { type: type.openapi_type, format: type.openapi_format }.compact
     else
       extract_component_ref(type)
     end
@@ -148,7 +148,7 @@ class Taro::Export::OpenAPIv3 < Taro::Export::Base # rubocop:disable Metrics/Cla
   end
 
   def export_scalar_field(field)
-    base = { type: field.openapi_type }
+    base = { type: field.openapi_type, format: field.openapi_format }.compact
     # Using oneOf seems more correct than an array of types
     # as it puts props like format together with the main type.
     # https://github.com/OAI/OpenAPI-Specification/issues/3148

data/lib/taro/types/base_type.rb

@@ -17,6 +17,7 @@ Taro::Types::BaseType = Struct.new(:object) do
   extend Taro::Types::Shared::Description
   extend Taro::Types::Shared::Equivalence
   extend Taro::Types::Shared::Name
+  extend Taro::Types::Shared::OpenAPIFormat
   extend Taro::Types::Shared::OpenAPIName
   extend Taro::Types::Shared::OpenAPIType
   extend Taro::Types::Shared::Rendering

data/lib/taro/types/field.rb

@@ -30,6 +30,10 @@ Taro::Types::Field = Data.define(:name, :type, :null, :method, :default, :enum,
     type.openapi_type
   end
 
+  def openapi_format
+    type.openapi_format
+  end
+
   private
 
   def coerce_to_enum(arg)

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

@@ -13,14 +13,16 @@ class Taro::Types::ObjectTypes::PageType < Taro::Types::ResponseType
     field(:page_info, type: 'Taro::Types::ObjectTypes::PageInfoType', null: false)
   end
 
-  def self.render(relation, after:, limit: 20, order_by: nil, order: nil)
+  def self.render(relation, **)
+    super(paginate(relation, **))
+  end
+
+  def self.paginate(relation, after:, limit: 20, order_by: nil, order: nil)
     result = RailsCursorPagination::Paginator.new(
       relation, limit:, order_by:, order:, after:
     ).fetch
-
     result[:page].map! { |el| el.fetch(:data) }
-
-    super(result)
+    result
   end
 
   def self.default_openapi_name

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

@@ -0,0 +1,26 @@
+# This is an expanded `PageType` that adds a `total_count` field
+# to show the total number of records in the paginated relation.
+# It is not recommended for very large relations where counting might be slow.
+#
+# Usage:
+# - `returns code: :ok, page_with_total_count_of: 'UserType'`
+# - `UserType.page_with_total_count.render(User.all, after: params[:cursor])`
+#
+# The gem rails_cursor_pagination must be installed to use this.
+#
+class Taro::Types::ObjectTypes::PageWithTotalCountType < Taro::Types::ObjectTypes::PageType
+  def self.derive_from(from_type)
+    super
+    field(:total_count, type: 'Integer', null: false)
+  end
+
+  def self.paginate(relation, **)
+    super.merge(total_count: relation.count)
+  end
+
+  def self.default_openapi_name
+    "#{item_type.openapi_name}_PageWithTotalCount"
+  end
+
+  define_derived_type :page_with_total_count, 'Taro::Types::ObjectTypes::PageWithTotalCountType'
+end

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

@@ -0,0 +1,61 @@
+# Provides a setter and getter for type classes' `openapi_format`,
+# for use in the OpenAPI export.
+module Taro::Types::Shared::OpenAPIFormat
+  OPENAPI_STRING_FORMATS = %i[
+    date
+    date-time
+    password
+    byte
+    binary
+    email
+    uuid
+    uri
+    hostname
+    ipv4
+    ipv6
+  ].freeze
+
+  OPENAPI_INTEGER_FORMATS = %i[
+    int32
+    int64
+  ].freeze
+
+  OPENAPI_NUMBER_FORMATS = %i[
+    float
+    double
+  ].freeze
+
+  def openapi_format
+    return unless @openapi_format
+
+    unless valid_formats_for_openapi_type.include?(@openapi_format)
+      raise(Taro::ArgumentError, "openapi_format #{@openapi_format.inspect} is invalid for openapi_type #{@openapi_type.inspect}, must be one for #{valid_formats_for_openapi_type}")
+    end
+
+    @openapi_format
+  end
+
+  def openapi_format=(arg)
+    @openapi_format = arg
+  end
+
+  def inherited(subclass)
+    subclass.instance_variable_set(:@openapi_format, @openapi_format)
+    super
+  end
+
+  private
+
+  def valid_formats_for_openapi_type
+    case @openapi_type
+    when :string
+      OPENAPI_STRING_FORMATS
+    when :integer
+      OPENAPI_INTEGER_FORMATS
+    when :number
+      OPENAPI_NUMBER_FORMATS
+    else
+      []
+    end
+  end
+end

data/lib/taro/version.rb

@@ -1,4 +1,4 @@
 # :nocov:
 module Taro
-  VERSION = "2.3.0"
+  VERSION = "2.5.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: taro
 version: !ruby/object:Gem::Version
-  version: 2.3.0
+  version: 2.5.0
 platform: ruby
 authors:
 - Janosch Müller
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-02-24 00:00:00.000000000 Z
+date: 2025-04-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rack
@@ -89,6 +89,7 @@ files:
 - lib/taro/types/object_types/no_content_type.rb
 - lib/taro/types/object_types/page_info_type.rb
 - lib/taro/types/object_types/page_type.rb
+- lib/taro/types/object_types/page_with_total_count_type.rb
 - lib/taro/types/rails_params_type.rb
 - lib/taro/types/response_type.rb
 - lib/taro/types/scalar/boolean_type.rb
@@ -114,6 +115,7 @@ files:
 - lib/taro/types/shared/item_type.rb
 - lib/taro/types/shared/name.rb
 - lib/taro/types/shared/object_coercion.rb
+- lib/taro/types/shared/openapi_format.rb
 - lib/taro/types/shared/openapi_name.rb
 - lib/taro/types/shared/openapi_type.rb
 - lib/taro/types/shared/pattern.rb
@@ -145,7 +147,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.22
+rubygems_version: 3.5.16
 signing_key:
 specification_version: 4
 summary: Typed Api using Ruby Objects.