camille 1.7.0 → 1.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b7393e683a6c060b951c73b888a9e6723cf3333a6a2c1a338e525c95ba00050e
-  data.tar.gz: 86bd555f6ffdce50614ed180043bc9de94476e2b803896a3d0e15b3a84f90576
+  metadata.gz: b669731de34897fd2acb06cac773161fe3118a5203d4c9fd3ae41f5a6fca39e8
+  data.tar.gz: bdeca5f3af494575e42fece40de7682f441f43040ac11fe9e88d63516c0fdbc9
 SHA512:
-  metadata.gz: 3b9fa70ec2457f286d9627dc62f11d95d743f83b108f98b23f1f2446da9ca743216605f806fb129d12627792493b0a0328d6bcb582ecdb3ad24878bbcc58d8ad
-  data.tar.gz: 7d8d08956a4f43cde2bf7efc94955626efd983abbf98e2d8ae4c39d20a049f7e2055e08a800c4c67154f55d733109e45acf48545c35aa18deb1fd53eab178d9b
+  metadata.gz: d65f75dc0f47bb06962313132d639ed6acd876ef5524cdbc8fb7e9ec55643f3de5b7e7984c372de017e1e3ddfbd161deb7794ee0876f019ef13de401301a4e62
+  data.tar.gz: 92cab47708e350863586256efab349a85b4f16572f402b336802f4c035f0f2511cbc406d6215c9b9312cc4958d498d3c7bdd41556f6566118f0271e6ff59d326

data/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 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.0)
       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.

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

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: camille
 version: !ruby/object:Gem::Version
-  version: 1.7.0
+  version: 1.8.0
 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