taro 2.3.0 → 2.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c96d6fd71ad22df31d5ab4cefb09389fd7ed5b41b5dd8821132fa2c5fa322837
-  data.tar.gz: f56362229e93f2f8c51a5490245d4a37e224015fecd42bb86a35926a01e8d776
+  metadata.gz: 9c7750f1403fa65519d22915908d5aeb6cf5bbeec5497d68369bf5a4e37fb0e8
+  data.tar.gz: 0b6d6b440c1f4fcdb965af8fb1aaf2d26f2ca3a9d2a2fb924bfe9456cb811090
 SHA512:
-  metadata.gz: 34ad2aedee3c3a21973420ca5e1185024c7d6b127ee9ca914b847134939bcd136e70f10130607b8392ce8044dfcb7c8014fa306d00d81b81266d68fcdad19b95
-  data.tar.gz: 1bec2fbada3a23267f87195323b2b112297c21e78c22281071bd2ec84a7359f78836ed250e85ae3f3d1765f428dd7ff1bdaaf92f5df2bd17883abed11b7a39eb
+  metadata.gz: 1f37ffe80f9f14ef49bd3131f0a64f5254219c4851de19ec6523143d508440cb263741c2ca56858eeff917cf0a4d1002b642b4e6f87498e47b62b3ffc5fbc4c8
+  data.tar.gz: 59fbfef1126825880c2d5b64b1d2a3799c25502d094f9758fa9181d7e1e3fa44b2b2504ccbf24c1d18925a5e53ceef1e1ca309cd8980f8950d385d1f3197aadb

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 ## [Unreleased]
 
+## [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.

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

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: taro
 version: !ruby/object:Gem::Version
-  version: 2.3.0
+  version: 2.4.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-03-11 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