camille 1.7.0 → 1.8.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b7393e683a6c060b951c73b888a9e6723cf3333a6a2c1a338e525c95ba00050e
-  data.tar.gz: 86bd555f6ffdce50614ed180043bc9de94476e2b803896a3d0e15b3a84f90576
+  metadata.gz: 43d1b00b15c6fb8dd557ad587bc0113f56328571ae309bf01e9f16a90cf6cc6e
+  data.tar.gz: f2f994348c8466586b6444885ea225446f15e45fac89f2942aa88ab135287195
 SHA512:
-  metadata.gz: 3b9fa70ec2457f286d9627dc62f11d95d743f83b108f98b23f1f2446da9ca743216605f806fb129d12627792493b0a0328d6bcb582ecdb3ad24878bbcc58d8ad
-  data.tar.gz: 7d8d08956a4f43cde2bf7efc94955626efd983abbf98e2d8ae4c39d20a049f7e2055e08a800c4c67154f55d733109e45acf48545c35aa18deb1fd53eab178d9b
+  metadata.gz: be0fba9d87641faa8df13542937860f4d04d2cbfb5ec65b7e3ace488aff7d373f6c83d5601fe1aa046e6d6b0df6ab565cc8a5fbe9669a4084613822a6af3c328
+  data.tar.gz: 426ab4e50a688e656552d512bed7b9f324bab52e23165d461abdba7843228a80ab9e2956d7232664a0e0b9f953061316104f4e59544dfdc569b4455e6c0e2efe

data/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 1.8.1
+
+### Fixed
+
+* `Record`, `Pick` and `Omit` now implement `check_params`, so nested objects inside them get their camelCase keys converted instead of failing with errors like `Expected array, got nil`. Record keys are still not converted.
+* `response.data` in `camille/testing` no longer type checks non-200 responses, matching `Camille::Controller#render`, which only checks and converts keys for 200 responses. Non-200 bodies are returned as-is.
+
+## 1.8.0
+
+### Added
+
+* Added `render!` to every type (`Camille::Types::Product.render!(value)`), which checks a value and returns a `Camille::Rendered`, raising `Camille::BasicType::RenderError` on a type mismatch. A `Rendered` can be cached and placed into a later response, where the type accepts it by fingerprint without re-checking and its JSON is spliced verbatim. See "Caching rendered fragments" in the README.
+* `Camille::Rendered` now marshals as `[fingerprint, json]`, so entries stored with the default `Rails.cache` coder stay valid across changes to the class.
+
+### Changed
+
+* Renamed `Camille::Controller::InvalidRenderArgumentError` to `Camille::Controller::RenderArgumentError`, matching the naming of the other controller errors. The old name remains as an alias.
+
 ## 1.7.0
 
 ### Fixed

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    camille (1.7.0)
+    camille (1.8.1)
       rails (>= 6.1, < 8.1)
 
 GEM

data/README.md

@@ -259,6 +259,30 @@ object:
     array[2]: Expected number, got "3".
 ```
 
+### Caching rendered fragments
+
+Type checking and key conversion run on every `render`. For data that is expensive to build and shared across requests, you can check it once and cache the result as a `Camille::Rendered`:
+
+```ruby
+rendered = Camille::Types::Product.render!(serialize(product))
+# => Camille::Rendered with the type's fingerprint and the final JSON string
+Rails.cache.write("product/#{product.id}/#{Camille::Types::Product.new.fingerprint}", rendered)
+```
+
+`render!` raises `Camille::BasicType::RenderError` if the value doesn't match the type. A `Rendered` can be placed anywhere a value of that type is expected:
+
+```ruby
+render json: {
+  products: Rails.cache.read_multi(*keys).values  # Product[]
+}
+```
+
+The type accepts it by comparing fingerprints instead of re-checking, and `to_json` splices the stored string verbatim, so no parsing or re-serialization happens on the cached fragments.
+
+A `Rendered` is immutable and opaque. If a fragment needs to be modified before rendering, cache the plain hash instead and let Camille check it as usual; the two forms are a per-fragment choice. Keep volatile or per-user fields outside cached fragments, and include the type's `fingerprint` in the cache key so entries are invalidated when the type changes.
+
+`Rendered` defines `marshal_dump`/`marshal_load` as `[fingerprint, json]`, so the default `Rails.cache` coder stores just the two strings. If you use the `:message_pack` cache serializer, register the class with `ActiveSupport::MessagePack::CacheSerializer` using the same pair.
+
 ### Reloading
 
 Everything in `config/camille/types` and `config/camille/schemas` will automatically reload after changes in development environment, just like other files in Rails.
@@ -280,7 +304,7 @@ get '/products/data'
 expect(response.data[:product][:available_stock]).to eq(1)
 ```
 
-If the response body fails the type check the helper raises `Camille::Testing::ResponseTypeError`. If the route has no Camille endpoint it raises `Camille::Testing::MissingEndpointError`.
+Since `Camille::Controller#render` only type checks and converts keys for 200 responses, `response.data` returns non-200 bodies as-is without validation. If a 200 response body fails the type check the helper raises `Camille::Testing::ResponseTypeError`. If the route has no Camille endpoint it raises `Camille::Testing::MissingEndpointError`.
 
 ## Versioning
 

data/camille.gemspec

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require_relative "lib/camille/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "camille"
+  spec.version = Camille::VERSION
+  spec.authors = ["merely"]
+  spec.email = ["git@merely.ca"]
+  spec.license = "MIT"
+
+  spec.summary = "Typed API schema for Rails with TypeScript codegen"
+  spec.description = ""
+  spec.homepage = "https://github.com/onyxblade/camille"
+  spec.required_ruby_version = ">= 2.6.0"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/onyxblade/camille"
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (f == __FILE__) || f.match(%r{\A(?:(?:test|spec|features)/|\.(?:git|travis|circleci)|appveyor)})
+    end
+  end
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  # Uncomment to register a new dependency of your gem
+  spec.add_dependency "rails", ">= 6.1", "< 8.1"
+
+  # For more information and examples about making a new gem, checkout our
+  # guide at: https://bundler.io/guides/creating_gem.html
+end

data/lib/camille/basic_type.rb

@@ -4,6 +4,7 @@ module Camille
   # This class specifies the methods available for all types includeing built-in and custom ones.
   class BasicType
     class InvalidTypeError < ::ArgumentError; end
+    class RenderError < ::StandardError; end
 
     module CheckRendered
       def check value
@@ -25,6 +26,19 @@ module Camille
       @fingerprint = Digest::MD5.hexdigest self.class.name
     end
 
+    # Checks `value` and returns a `Camille::Rendered`, raising `RenderError` with
+    # the printed type error if the check fails.
+    def render! value
+      result = check(value)
+      if result.type_error?
+        string_io = StringIO.new
+        Camille::TypeErrorPrinter.new(result).print(string_io)
+        raise RenderError.new("\nType check failed for render!.\n#{string_io.string}")
+      else
+        result.render
+      end
+    end
+
     def | other
       Camille::Types::Union.new(self, other)
     end

data/lib/camille/controller.rb

@@ -3,7 +3,8 @@ module Camille
     class TypeError < ::StandardError; end
     class ParamsTypeError < TypeError; end
     class ResponseTypeError < TypeError; end
-    class InvalidRenderArgumentError < ::ArgumentError; end
+    class RenderArgumentError < ::ArgumentError; end
+    InvalidRenderArgumentError = RenderArgumentError
     class MissingRenderError < ::StandardError; end
 
     def camille_schema
@@ -31,7 +32,7 @@ module Camille
               super(json: rendered)
             end
           else
-            raise InvalidRenderArgumentError.new("Expected key :json for `render` call.")
+            raise RenderArgumentError.new("Expected key :json for `render` call.")
           end
         else
           super

data/lib/camille/pick_and_omit.rb

@@ -25,6 +25,10 @@ module Camille
       processed_object.check(value)
     end
 
+    def check_params value
+      processed_object.check_params(value)
+    end
+
     def literal
       "#{klass_name}<#{@type.literal}, #{keys_in_literal}>"
     end

data/lib/camille/rendered.rb

@@ -1,4 +1,9 @@
 module Camille
+  # A JSON string that has already passed a type check for the type identified by
+  # `fingerprint`. Any type will accept a `Rendered` with a matching fingerprint
+  # without re-checking it, and `to_json` splices the string verbatim, so a
+  # `Rendered` can be stored (e.g. in `Rails.cache`) and placed into a later
+  # response as an opaque, immutable fragment.
   class Rendered
     attr_reader :fingerprint, :json
 
@@ -10,5 +15,16 @@ module Camille
     def to_json options = nil
       @json
     end
+
+    # Marshal (and therefore the default `Rails.cache` coder) stores only the two
+    # strings, so cached entries stay valid across changes to this class's
+    # internals.
+    def marshal_dump
+      [@fingerprint, @json]
+    end
+
+    def marshal_load array
+      @fingerprint, @json = array
+    end
   end
-end
+end

data/lib/camille/testing.rb

@@ -24,6 +24,10 @@ module Camille
             "No camille endpoint for #{controller_class_name}##{action}."
         end
 
+        # Camille::Controller#render only type checks and converts keys for
+        # 200 responses, so mirror that here and return non-200 bodies as-is.
+        return deep_indifferent(parsed_body) unless status == 200
+
         result = endpoint.response_type.check_params(parsed_body)
         if result.type_error?
           io = StringIO.new

data/lib/camille/type.rb

@@ -35,6 +35,10 @@ module Camille
       new.check_params value
     end
 
+    def self.render! value
+      new.render! value
+    end
+
     def self.klass_name
       name.gsub(/^Camille::Types::/, '')
     end

data/lib/camille/types/record.rb

@@ -11,28 +11,14 @@ module Camille
       end
 
       def check value
-        if value.is_a? ::Hash
-
-          results = value.map.with_index do |(k, v), index|
-            [index, check_pair(k, v)]
-          end
-
-          errors = results.map do |index, result|
-            if result.instance_of?(Camille::TypeError)
-              ["record[#{index}]", result]
-            else
-              nil
-            end
-          end.compact
+        check_with_method(value, :check)
+      end
 
-          if errors.empty?
-            Camille::Checked.new(fingerprint, results.map{|_, result| [result[0].value, result[1].value]}.to_h)
-          else
-            Camille::TypeError.new(**errors.to_h)
-          end
-        else
-          Camille::TypeError.new("Expected hash, got #{value.inspect}.")
-        end
+      # Record keys are dynamic, so they are never converted between
+      # camelCase and snake_case. Only the values are checked with
+      # `check_params` so nested objects get their keys converted.
+      def check_params value
+        check_with_method(value, :check_params)
       end
 
       def self.[] key, value
@@ -44,9 +30,34 @@ module Camille
       end
 
       private
-        def check_pair key, value
+        def check_with_method value, method_name
+          if value.is_a? ::Hash
+
+            results = value.map.with_index do |(k, v), index|
+              [index, check_pair(k, v, method_name)]
+            end
+
+            errors = results.map do |index, result|
+              if result.instance_of?(Camille::TypeError)
+                ["record[#{index}]", result]
+              else
+                nil
+              end
+            end.compact
+
+            if errors.empty?
+              Camille::Checked.new(fingerprint, results.map{|_, result| [result[0].value, result[1].value]}.to_h)
+            else
+              Camille::TypeError.new(**errors.to_h)
+            end
+          else
+            Camille::TypeError.new("Expected hash, got #{value.inspect}.")
+          end
+        end
+
+        def check_pair key, value, method_name
           key_result = @key.check key
-          value_result = @value.check value
+          value_result = @value.public_send(method_name, value)
 
           if key_result.checked? && value_result.checked?
             [key_result, value_result]

data/lib/camille/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Camille
-  VERSION = "1.7.0"
+  VERSION = "1.8.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: camille
 version: !ruby/object:Gem::Version
-  version: 1.7.0
+  version: 1.8.1
 platform: ruby
 authors:
 - merely
@@ -48,6 +48,7 @@ files:
 - benchmarks/returning_multiple_values.rb
 - bin/console
 - bin/setup
+- camille.gemspec
 - gemfiles/rails-7.2
 - gemfiles/rails-8.0
 - lib/camille.rb