taro 2.0.0 → 2.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 62127cdef8f44e34831cb4dec7d900bfa25c3c00994e750624de1f486c6880ab
-  data.tar.gz: 40bd31112d3e8fb3fe96bfa282acd6ad909c60f66431aa556e01052b3098ab44
+  metadata.gz: d73348290387aeef3de0558f6557af6572326043dff427ee295386a12e8bf6a6
+  data.tar.gz: 89b0a6c8efae50665d43385b0b4182fba6b07e5f97e933d3add5d0e1ba19f421
 SHA512:
-  metadata.gz: a609041860bc3516a70a1ebd2f073d031cac39a04f9ff5562ff7c6d0711b1c5dc3a900cfa4842ff77f6ab573ab0fa2164282cf68fff58133071a7b842201cecc
-  data.tar.gz: 4942e27cdc067cb5c46ae7f726743d1cf54282536195b892d93507757820e0c53db46ebfb5a40ad25cc13c60ef2eac6b493cb1e2d8b9cfa195a0db782734d765
+  metadata.gz: 67a0d0a5d2464c7ec6954143c95311b92b1a4a78041b298449815b1e57340de7091ac89235fd9e674ee1d3e99ed531049e99207ec62498fa94687b7c91956edd
+  data.tar.gz: '0768d75380ee9b18de093bebf1952b4eeac1e7965fea8c3a0cb5fbec3ef84ec6a27d5e141a837bf6a0f9d698e5b2ceff9ba2e30a33143edd434ebd25812a933a'

data/CHANGELOG.md

@@ -1,5 +1,19 @@
 ## [Unreleased]
 
+## [2.2.0] - 2025-02-22
+
+### Added
+
+- error message when incorrectly chaining `with_cache`
+
+## [2.1.0] - 2025-02-21
+
+### Added
+
+- added support for caching on type level and when calling render
+  - default cache will be set to Rails.cache in the railtie
+  - cache_key can be a string, an array, a hash or a proc
+
 ## [2.0.0] - 2024-12-15
 
 ### Changed

data/README.md

@@ -1,5 +1,8 @@
 # Taro - Typed Api using Ruby Objects
 
+[![Gem Version](https://badge.fury.io/rb/taro.svg)](https://rubygems.org/gems/taro)
+[![Build Status](https://github.com/taro-rb/taro/actions/workflows/main.yml/badge.svg)](https://github.com/taro-rb/taro/actions)
+
 This library provides an object-based type system for RESTful Ruby APIs, with built-in parameter parsing, response rendering, and OpenAPI schema export.
 
 It is inspired by [`apipie-rails`](https://github.com/Apipie/apipie-rails) and [`graphql-ruby`](https://github.com/rmosolgo/graphql-ruby).
@@ -34,7 +37,7 @@ class BikesController < ApplicationController
   api     'Update a bike', desc: 'My longer text', tags: ['Bikes']
 
   # Params can come from the path, e.g. /bike/:id.
-  # Some types, like UUID in this case, are predefined. See below for more.
+  # Some types, like UUID in this case, are predefined. See below for more types.
   param   :id, type: 'UUID', null: false, desc: 'ID of the bike to update'
 
   # Params can also come from the query string or request body.
@@ -139,7 +142,14 @@ Taro.config.parse_params = false
 
 #### Response validation
 
-Responses are automatically validated to have used the correct type for rendering, which guarantees that they match the declaration.
+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:
+
+```ruby
+returns code: :ok, array_of: 'String', desc: 'Bike names'
+def index
+  render json: ['Super bike', 'Slow bike']
+end
+```
 
 An error is also raised if a documented endpoint renders an undocumented status code, e.g.:
 
@@ -151,7 +161,7 @@ def create
 end
 ```
 
-However, all HTTP error codes except 422 can be rendered without prior declaration. E.g.:
+HTTP error codes, except 422, are an exception. They can be rendered without prior declaration. E.g.:
 
 ```ruby
 returns code: :ok, type: 'BikeType'
@@ -162,12 +172,12 @@ end
 
 The reason for this is that Rack and Rails commonly render codes like 400, 404, 500 and various others, but you might not want to have that fact documented on every single endpoint.
 
-However, if you do declare an error code, responses with this code are validated:
+However, if you do declare an error code, responses with this code *are* validated:
 
 ```ruby
-returns code: :not_found, type: 'ExpectedType'
+returns code: :not_found, type: 'ExpectedErrorType'
 def show
-  render json: WrongType.render(foo), status: :not_found
+  render json: WrongErrorType.render(foo), status: :not_found
   # => type mismatch, raises response validation error
 end
 ```
@@ -194,7 +204,7 @@ end
 
 ### Included type options
 
-The following type names are available by default and can be used as `type:`/`array_of:`/`page_of:` arguments:
+The following type names are available by default and can be used as `type:`, `array_of:`, or `page_of:` arguments:
 
 - `'Boolean'` - accepts and renders `true` or `false`
 - `'Date'` - accepts and renders a date string in ISO8601 format
@@ -208,7 +218,7 @@ The following type names are available by default and can be used as `type:`/`ar
 - `'Timestamp'` - renders a `Time` as unix timestamp integer and turns incoming integers into a `Time`
 - `'UUID'` - accepts and renders UUIDs
 
-Also, when using the generator, `ErrorsType` and `ErrorDetailsType` are generated as a starting point for unified error presentation. `ErrorsType` can render invalid `ActiveRecord` instances, `ActiveModel::Errors` and other data structures.
+Also, when using the rails generator, `ErrorsType` and `ErrorDetailsType` are generated as a starting point for unified error presentation. `ErrorsType` can render invalid `ActiveRecord` instances, `ActiveModel::Errors` and other data structures.
 
 ### Enums
 
@@ -234,13 +244,34 @@ class ErrorType < ObjectType
 end
 ```
 
-### FAQ
+### Caching
 
-#### How do I render API docs?
+Taro provides support for caching. The cache instance can be configured by setting `Taro::Cache.cache_instance`. By default, the railtie will set it to `Rails.cache`.
 
-Rendering docs is outside of the scope of this project. You can use the OpenAPI export to generate docs with tools such as RapiDoc, ReDoc, or Swagger UI.
+It supports configuring an ad hoc cache when using a render call, e.g.
 
-#### How do I use context in my types?
+```ruby
+bike = Bike.find(params[:id])
+BikeType.with_cache(cache_key: bike.cache_key, expires_in: 3.minutes).render(bike)
+```
+
+Or by configuring the cache rule on a per type basis, e.g.
+
+```ruby
+class BikeType < ObjectType
+  self.cache_key = ->(bike) { bike.cache_key_with_version }
+  self.expires_in = 1.hour
+  # ...
+end
+```
+
+## FAQ
+
+### How do I render API docs?
+
+Rendering docs is outside of the scope of this project. You can use the OpenAPI export to generate docs with tools such as RapiDoc, ReDoc, Swagger UI, and [many others](https://tools.openapis.org/categories/documentation.html).
+
+### How do I use context in my types?
 
 Use [ActiveSupport::CurrentAttributes](https://api.rubyonrails.org/classes/ActiveSupport/CurrentAttributes.html).
 
@@ -254,18 +285,23 @@ class BikeType < ObjectType
 end
 ```
 
-#### How do I migrate from apipie-rails?
+### How do I migrate from apipie-rails?
 
 First of all, if you don't need a better OpenAPI export, or better support for hashes and arrays, or less repetitive definitions, it might not be worth it.
 
-If you do:
+Please also note the following:
+
+- `taro` currently only supports the latest OpenAPI standard (instead of v2 like `apipie-rails`)
+- `taro` does not support arbitrary validations - only those that can be expressed in the OpenAPI schema
+- `taro` does not render API docs, as mentioned above
+
+If you want to migrate anyway:
 
-- note that `taro` currently only supports the latest OpenAPI standard (instead of v2 like `apipie-rails`)
 - extract complex param declarations into InputTypes
 - extract complex response declarations into ObjectTypes or ResponseTypes
 - replace `required: true` with `null: false` and `required: false` with `null: true`
 
-Taro uses some of the same DSL as `apipie`, so for a step-by-step migration, you might want to make `taro` use a different one:
+Taro uses some of the same DSL as `apipie`, so for a step-by-step migration, you might want to make `taro` use a different one. This initializer will change the `taro` DSL to `taro_api`, `taro_param`, and `taro_returns` and leave `api`, `param`, and `returns` to `apipie`:
 
 ```ruby
 # config/initializers/taro.rb
@@ -275,7 +311,7 @@ Taro uses some of the same DSL as `apipie`, so for a step-by-step migration, you
 end
 ```
 
-#### How do I keep lengthy API descriptions out of my controller?
+### How do I keep lengthy API descriptions out of my controller?
 
 ```ruby
 module BikeUpdateDesc
@@ -293,13 +329,13 @@ class BikesController < ApplicationController
 end
 ```
 
-#### Why do I have to use type name strings instead of the type constants?
+### Why do I have to use type name strings instead of the type constants?
 
 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.
 
-#### Can I define my own derived types like `page_of` or `array_of`?
+### Can I define my own derived types like `page_of` or `array_of`?
 
 Yes.
 

data/lib/taro/cache.rb

@@ -0,0 +1,14 @@
+module Taro::Cache
+  singleton_class.attr_accessor :cache_instance
+
+  def self.call(object, cache_key: nil, expires_in: nil)
+    case cache_key
+    when nil
+      yield
+    when Hash, Proc
+      call(object, cache_key: cache_key[object], expires_in: expires_in) { yield }
+    else
+      cache_instance.fetch(cache_key, expires_in: expires_in) { yield }
+    end
+  end
+end

data/lib/taro/rails/generators/install_generator.rb

@@ -12,7 +12,7 @@ class Taro::Rails::Generators::InstallGenerator < ::Rails::Generators::Base
   def create_type_files
     Dir["#{self.class.source_root}/**/*.erb"].each do |tmpl|
       dest_dir = options[:dir].chomp('/')
-      template tmpl, "#{dest_dir}/#{File.basename(tmpl).sub('erb', 'rb')}"
+      template tmpl, "#{dest_dir}/#{File.basename(tmpl, '.erb')}.rb"
     end
   end
   # :nocov:

data/lib/taro/rails/generators/templates/errors_type.erb

@@ -25,6 +25,6 @@ class ErrorsType < Taro::Types::ListType
         response_error("must be an Enumerable or an object with errors")
       end
 
-    list.map { |el| self.class.item_type.new(el).coerce_response }
+    list.map { |el| self.class.item_type.new(el).cached_coerce_response }
   end
 end

data/lib/taro/rails/railtie.rb

@@ -9,6 +9,10 @@ class Taro::Rails::Railtie < ::Rails::Railtie
     app.reloader.to_prepare do
       Taro::Rails.reset
     end
+
+    app.config.after_initialize do
+      Taro::Cache.cache_instance = Rails.cache
+    end
   end
 
   rake_tasks { Dir["#{__dir__}/tasks/**/*.rake"].each { |f| load f } }

data/lib/taro/rails/response_validator.rb

@@ -1,6 +1,6 @@
 Taro::Rails::ResponseValidator = Struct.new(:controller, :declaration, :rendered) do
-  def self.call(*args)
-    new(*args).call
+  def self.call(controller, declaration, rendered)
+    new(controller, declaration, rendered).call
   end
 
   def call
@@ -79,7 +79,7 @@ Taro::Rails::ResponseValidator = Struct.new(:controller, :declaration, :rendered
 
   def check_enum(type, value)
     # coercion checks non-emptyness + enum match
-    type.new(value).coerce_response
+    type.new(value).cached_coerce_response
   rescue Taro::Error => e
     fail_with(e.message)
   end

data/lib/taro/rails/route_finder.rb

@@ -17,13 +17,11 @@ module Taro::Rails::RouteFinder
 
     def build_cache
       # Build a Hash like
-      # { 'users#show' } => [#<NormalizedRoute>, #<NormalizedRoute>] }
-      rails_routes.each_with_object({}) do |rails_route, hash|
-        route = Taro::Rails::NormalizedRoute.new(rails_route)
-        next if route.ignored?
-
-        (hash[route.endpoint] ||= []) << route
-      end
+      # { 'users#show' => [#<NormalizedRoute>, #<NormalizedRoute>] }
+      rails_routes
+        .map { |r| Taro::Rails::NormalizedRoute.new(r) }
+        .reject(&:ignored?)
+        .group_by(&:endpoint)
     end
 
     def rails_routes

data/lib/taro/types/base_type.rb

@@ -20,5 +20,7 @@ Taro::Types::BaseType = Struct.new(:object) do
   extend Taro::Types::Shared::OpenAPIName
   extend Taro::Types::Shared::OpenAPIType
   extend Taro::Types::Shared::Rendering
+  include Taro::Types::Shared::Caching
   include Taro::Types::Shared::Errors
+  include Taro::Types::Shared::TypeClass
 end

data/lib/taro/types/coercion.rb

@@ -64,7 +64,7 @@ module Taro::Types::Coercion
     require 'date'
     def shortcuts
       @shortcuts ||= {
-        # rubocop:disable Layout/HashAlignment - buggy cop
+        # rubocop:disable Layout/HashAlignment
         'Boolean'   => Taro::Types::Scalar::BooleanType,
         'Date'      => Taro::Types::Scalar::ISO8601DateType,
         'DateTime'  => Taro::Types::Scalar::ISO8601DateTimeType,
@@ -76,7 +76,7 @@ module Taro::Types::Coercion
         'Time'      => Taro::Types::Scalar::ISO8601DateTimeType,
         'Timestamp' => Taro::Types::Scalar::TimestampType,
         'UUID'      => Taro::Types::Scalar::UUIDv4Type,
-        # rubocop:enable Layout/HashAlignment - buggy cop
+        # rubocop:enable Layout/HashAlignment
       }.freeze
     end
   end

data/lib/taro/types/enum_type.rb

@@ -24,7 +24,7 @@ class Taro::Types::EnumType < Taro::Types::BaseType
 
   def coerce_response
     self.class.raise_if_empty_enum
-    value = self.class.item_type.new(object).coerce_response
+    value = self.class.item_type.new(object).cached_coerce_response
     if self.class.values.include?(value)
       value
     else

data/lib/taro/types/field.rb

@@ -3,6 +3,7 @@ require_relative 'field_validation'
 Taro::Types::Field = Data.define(:name, :type, :null, :method, :default, :enum, :defined_at, :desc, :deprecated) do
   include Taro::Types::FieldValidation
   include Taro::Types::Shared::Errors
+  include Taro::Types::Shared::TypeClass
 
   def initialize(name:, type:, null:, method: name, default: Taro::None, enum: nil, defined_at: nil, desc: nil, deprecated: nil)
     enum = coerce_to_enum(enum)
@@ -65,7 +66,7 @@ Taro::Types::Field = Data.define(:name, :type, :null, :method, :default, :enum,
     return default if value.nil? && default_specified?
 
     type_obj = type.new(value)
-    from_input ? type_obj.coerce_input : type_obj.coerce_response
+    from_input ? type_obj.coerce_input : type_obj.cached_coerce_response
   rescue Taro::ValidationError => e
     reraise_recursively_with_path_info(e)
   end

data/lib/taro/types/list_type.rb

@@ -17,7 +17,7 @@ class Taro::Types::ListType < Taro::Types::BaseType
     object.respond_to?(:map) || response_error('must be an Enumerable')
 
     item_type = self.class.item_type
-    object.map { |el| item_type.new(el).coerce_response }
+    object.map { |el| item_type.new(el).cached_coerce_response }
   end
 
   def self.default_openapi_name

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

@@ -0,0 +1,31 @@
+module Taro::Types::Shared::Caching
+  def cached_coerce_response
+    Taro::Cache.call(object, cache_key: self.class.cache_key, expires_in: self.class.expires_in) do
+      coerce_response
+    end
+  end
+
+  def self.included(klass)
+    klass.extend(ClassMethods)
+    klass.singleton_class.attr_accessor :expires_in
+    klass.singleton_class.attr_reader :cache_key
+  end
+
+  module ClassMethods
+    def cache_key=(arg)
+      arg.nil? || arg.is_a?(Proc) && arg.arity == 1 || arg.is_a?(Hash) ||
+        raise(Taro::ArgumentError, "Type.cache_key must be a Proc with arity 1, a Hash, or nil")
+
+      @cache_key = arg
+    end
+
+    def with_cache(cache_key:, expires_in: nil)
+      klass = dup
+      klass.cache_key = cache_key.is_a?(Proc) ? cache_key : ->(_) { cache_key }
+      klass.expires_in = expires_in
+      this = self
+      klass.define_singleton_method(:type_class) { this }
+      klass
+    end
+  end
+end

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

@@ -35,9 +35,11 @@ module Taro::Types::Shared::DerivedTypes
 
     root.define_singleton_method(method_name) do
       derived_types[type] ||= begin
-        type_class = Taro::Types::Coercion.call(type:)
-        new_type = Class.new(type_class)
-        new_type.define_name("#{self.name}.#{method_name}")
+        name || raise(Taro::ArgumentError, 'Cannot derive from anonymous type')
+
+        coerced_type = Taro::Types::Coercion.call(type:)
+        new_type = Class.new(coerced_type)
+        new_type.define_name("#{name}.#{method_name}")
         new_type.derive_from(self)
         new_type
       end

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

@@ -8,8 +8,7 @@ module Taro::Types::Shared::Equivalence
 
     # @fields is lazy-loaded. Comparing @field_defs suffices.
     ignored = %i[@fields]
-    props = instance_variables - ignored
-    props == (other.instance_variables - ignored) &&
-      props.all? { |p| instance_variable_get(p) == other.instance_variable_get(p) }
+    (instance_variables - ignored).to_h { |i| [i, instance_variable_get(i)] } ==
+      (other.instance_variables - ignored).to_h { |i| [i, other.instance_variable_get(i)] }
   end
 end

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

@@ -1,9 +1,11 @@
 module Taro::Types::Shared::Rendering
   # 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__]
+  def render(object, cache_attrs = {})
+    result = Taro::Cache.call(object, **cache_attrs) do
+      new(object).cached_coerce_response
+    end
+    self.last_render = [type_class, result.__id__]
     result
   end
 

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

@@ -0,0 +1,12 @@
+# `type_class` is a convenience method to get the type class of types,
+# of with_cache-types, of type instances, and of fields in the same way.
+module Taro::Types::Shared::TypeClass
+  def self.included(klass)
+    if klass.instance_methods.include?(:type) # Field
+      klass.alias_method                 :type_class, :type
+    else # BaseType
+      klass.singleton_class.alias_method :type_class, :itself
+      klass.alias_method                 :type_class, :class
+    end
+  end
+end

data/lib/taro/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: taro
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 2.2.0
 platform: ruby
 authors:
 - Janosch Müller
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-12-15 00:00:00.000000000 Z
+date: 2025-02-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rack
@@ -39,6 +39,7 @@ files:
 - README.md
 - Rakefile
 - lib/taro.rb
+- lib/taro/cache.rb
 - lib/taro/common_returns.rb
 - lib/taro/config.rb
 - lib/taro/declaration.rb
@@ -101,6 +102,7 @@ files:
 - lib/taro/types/scalar_type.rb
 - lib/taro/types/shared.rb
 - lib/taro/types/shared/additional_properties.rb
+- lib/taro/types/shared/caching.rb
 - lib/taro/types/shared/custom_field_resolvers.rb
 - lib/taro/types/shared/deprecation.rb
 - lib/taro/types/shared/derived_types.rb
@@ -115,6 +117,7 @@ files:
 - lib/taro/types/shared/openapi_type.rb
 - lib/taro/types/shared/pattern.rb
 - lib/taro/types/shared/rendering.rb
+- lib/taro/types/shared/type_class.rb
 - lib/taro/version.rb
 - tasks/benchmark.rake
 - tasks/benchmark_1kb.json