taro 2.2.0 → 2.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d73348290387aeef3de0558f6557af6572326043dff427ee295386a12e8bf6a6
-  data.tar.gz: 89b0a6c8efae50665d43385b0b4182fba6b07e5f97e933d3add5d0e1ba19f421
+  metadata.gz: 9c7750f1403fa65519d22915908d5aeb6cf5bbeec5497d68369bf5a4e37fb0e8
+  data.tar.gz: 0b6d6b440c1f4fcdb965af8fb1aaf2d26f2ca3a9d2a2fb924bfe9456cb811090
 SHA512:
-  metadata.gz: 67a0d0a5d2464c7ec6954143c95311b92b1a4a78041b298449815b1e57340de7091ac89235fd9e674ee1d3e99ed531049e99207ec62498fa94687b7c91956edd
-  data.tar.gz: '0768d75380ee9b18de093bebf1952b4eeac1e7965fea8c3a0cb5fbec3ef84ec6a27d5e141a837bf6a0f9d698e5b2ceff9ba2e30a33143edd434ebd25812a933a'
+  metadata.gz: 1f37ffe80f9f14ef49bd3131f0a64f5254219c4851de19ec6523143d508440cb263741c2ca56858eeff917cf0a4d1002b642b4e6f87498e47b62b3ffc5fbc4c8
+  data.tar.gz: 59fbfef1126825880c2d5b64b1d2a3799c25502d094f9758fa9181d7e1e3fa44b2b2504ccbf24c1d18925a5e53ceef1e1ca309cd8980f8950d385d1f3197aadb

data/CHANGELOG.md

@@ -1,5 +1,17 @@
 ## [Unreleased]
 
+## [2.4.0] - 2025-03-11
+
+### Added
+
+- `PageWithTotalCountType` for paginated responses with a total count
+
+## [2.3.0] - 2025-02-24
+
+### Added
+
+- `Taro.config.raise_for_undeclared_params`
+
 ## [2.2.0] - 2025-02-22
 
 ### 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?
 
@@ -140,6 +137,14 @@ Requests are automatically validated to match the declared input schema, unless
 Taro.config.parse_params = false
 ```
 
+There is also an option to raise an error if any undeclared params are submitted:
+
+```ruby
+Taro.config.raise_for_undeclared_params = true
+```
+
+This option is similar to `action_on_unpermitted_parameters = :raise` in Rails and is most useful in dev and test environments. The railtie enables it automatically in these environments.
+
 #### Response validation
 
 Responses are automatically validated to have used the correct type for rendering, which guarantees that they match the declaration. This means you have to use the types to render complex responses, and manually building a Hash that conforms to the schema will raise an error. Primitive/scalar types are an exception, e.g. you *can* do:
@@ -265,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?
@@ -335,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.
@@ -367,7 +399,6 @@ end
 
 ## Possible future features
 
-- warning/raising for undeclared input params (currently they are ignored)
 - usage without rails is possible but not convenient yet
 - rspec matchers for testing
 - sum types

data/lib/taro/config.rb

@@ -5,6 +5,7 @@ module Taro::Config
     :export_format,
     :export_path,
     :parse_params,
+    :raise_for_undeclared_params,
     :validate_response,
   )
 
@@ -14,6 +15,7 @@ module Taro::Config
   self.export_format = :yaml
   self.export_path = 'api.yml'
   self.parse_params = true
+  self.raise_for_undeclared_params = false # may be overridden by railtie
   self.validate_response = true
 end
 

data/lib/taro/declaration.rb

@@ -5,7 +5,7 @@ class Taro::Declaration
   attr_reader :desc, :summary, :params, :return_defs, :return_descriptions, :tags
 
   def initialize(for_klass = nil)
-    @params = Class.new(Taro::Types::InputType)
+    @params = Class.new(Taro::Types::RailsParamsType)
     @return_defs = {}
     @return_descriptions = {}
 

data/lib/taro/rails/railtie.rb

@@ -1,5 +1,7 @@
 class Taro::Rails::Railtie < ::Rails::Railtie
   initializer("taro") do |app|
+    Taro.config.raise_for_undeclared_params = %w[development test].include?(Rails.env)
+
     # The `:action_controller` hook fires for both ActionController::API
     # and ActionController::Base, executing the block in their context.
     ActiveSupport.on_load(:action_controller) do

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

@@ -0,0 +1,10 @@
+require_relative 'object_type'
+
+# Abstract base class for rails declaration params. Internal use only.
+class Taro::Types::RailsParamsType < Taro::Types::InputType
+  # Skip validation of base params because they contain rails "additions"
+  # like controller, action, routing-related stuff, de-nested values, etc.
+  def validate_no_undeclared_params?
+    false
+  end
+end

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

@@ -1,6 +1,7 @@
 # Provides input and response handling for types with fields.
 module Taro::Types::Shared::ObjectCoercion
   def coerce_input
+    validate_no_undeclared_params
     self.class.fields.transform_values do |field|
       field.value_for_input(object)
     end
@@ -13,4 +14,17 @@ module Taro::Types::Shared::ObjectCoercion
       field.value_for_response(object, context: self, object_is_hash:)
     end
   end
+
+  private
+
+  def validate_no_undeclared_params
+    return unless validate_no_undeclared_params?
+
+    undeclared = object.to_h.keys.map(&:to_sym) - self.class.send(:field_defs).keys
+    undeclared.any? && input_error("Undeclared params: #{undeclared.join(', ')}")
+  end
+
+  def validate_no_undeclared_params?
+    Taro.config.raise_for_undeclared_params
+  end
 end

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

@@ -1,10 +1,8 @@
 module Taro::Types::Shared::Rendering
   # The `::render` method is intended for use in controllers.
   # Overrides of this method must call super.
-  def render(object, cache_attrs = {})
-    result = Taro::Cache.call(object, **cache_attrs) do
-      new(object).cached_coerce_response
-    end
+  def render(object)
+    result = new(object).cached_coerce_response
     self.last_render = [type_class, result.__id__]
     result
   end

data/lib/taro/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: taro
 version: !ruby/object:Gem::Version
-  version: 2.2.0
+  version: 2.4.0
 platform: ruby
 authors:
 - Janosch Müller
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-02-22 00:00:00.000000000 Z
+date: 2025-03-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rack
@@ -89,6 +89,8 @@ 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
 - lib/taro/types/scalar/float_type.rb