mongoid-cached-json 1.6.0 → 1.7.0

data/CHANGELOG.md

@@ -1,103 +1,97 @@
-1.6.1 (Next)
-------------
+### 1.7.1 (Next)
 
 * Your contribution here.
 
-1.6.0 (2019/05/31)
-------------
+### 1.7.0 (2026/10/16)
 
-* [#20](https://github.com/mongoid/mongoid-cached-json/pull/20): Compatibility with Ruby 2.3, 2.4, 2.5 and 2.6 - [@yuki24](http://github.com/yuki24).
-* [#20](https://github.com/mongoid/mongoid-cached-json/pull/20): Compatibility with Mongoid 6 - [@yuki24](http://github.com/yuki24).
-* [#20](https://github.com/mongoid/mongoid-cached-json/pull/20): No longer test against Ruby 1.9.3 - [@yuki24](http://github.com/yuki24).
-* [#22](https://github.com/mongoid/mongoid-cached-json/pull/22): Compatibility with Mongoid 7 - [@yuki24](https://github.com/yuki24)
+* [#33](https://github.com/mongoid/mongoid-cached-json/pull/33): Allow per-model cache bypass with `json_fields disable_caching: true` - [@dblock](https://github.com/dblock).
+* [#32](https://github.com/mongoid/mongoid-cached-json/pull/32): Support opt-in declaration-time expansion of all stored fields with explicit overrides and computed fields - [@dblock](https://github.com/dblock).
+* [#31](https://github.com/mongoid/mongoid-cached-json/pull/31): Add explicit per-model schema cache versions, independent of API versions - [@dblock](https://github.com/dblock).
+* [#39](https://github.com/mongoid/mongoid-cached-json/pull/39): Check pull request changelogs with Danger and report results in PR comments - [@dblock](https://github.com/dblock).
+* [#34](https://github.com/mongoid/mongoid-cached-json/pull/34): Support `cache: false` on individual JSON fields - [@dblock](https://github.com/dblock).
+* [#36](https://github.com/mongoid/mongoid-cached-json/pull/36): Document cache invalidation boundaries for callback-bypassing and concurrent writes - [@dblock](https://github.com/dblock).
+* [#35](https://github.com/mongoid/mongoid-cached-json/pull/35): Omit hidden child references while preserving `nil` for missing references (see [UPGRADING](UPGRADING.md) for migration notes) - [@dblock](https://github.com/dblock).
+* [#38](https://github.com/mongoid/mongoid-cached-json/pull/38): Fix a `:reference` field returning `nil` instead of `false` when its definition evaluates to a false-y, non-nil value - [@mzikherman](https://github.com/mzikherman).
+* [#30](https://github.com/mongoid/mongoid-cached-json/pull/30): Replace the obsolete quality badge with Coveralls, generate real SimpleCov coverage in one modern CI job, and scope badges to upstream master - [@dblock](https://github.com/dblock).
+* [#30](https://github.com/mongoid/mongoid-cached-json/pull/30): Modernize CI with GitHub Actions, testing representative Ruby/Mongoid/MongoDB combinations through Ruby 4.0, Mongoid 9, and MongoDB Server 8.0, with modern memcached cache integration - [@dblock](https://github.com/dblock).
 
-1.5.3 (2015/09/17)
-------------------
+### 1.6.0 (2019/05/31)
 
-* Compatibility with Mongoid 5 - [@dblock](http://github.com/dblock).
+* [#20](https://github.com/mongoid/mongoid-cached-json/pull/20): Compatibility with Ruby 2.3, 2.4, 2.5 and 2.6 - [@yuki24](https://github.com/yuki24).
+* [#20](https://github.com/mongoid/mongoid-cached-json/pull/20): Compatibility with Mongoid 6 - [@yuki24](https://github.com/yuki24).
+* [#20](https://github.com/mongoid/mongoid-cached-json/pull/20): No longer test against Ruby 1.9.3 - [@yuki24](https://github.com/yuki24).
+* [#22](https://github.com/mongoid/mongoid-cached-json/pull/22): Compatibility with Mongoid 7 - [@yuki24](https://github.com/yuki24).
 
-1.5.2 (2014/29/12)
-------------------
+### 1.5.3 (2015/09/17)
 
-* Fixed support for Ruby 2.2.0 - [@dblock](http://github.com/dblock).
-* Implemented RuboCop, Ruby-style linter - [@dblock](http://github.com/dblock).
-* Upgraded to RSpec 3.1 - [@dblock](http://github.com/dblock).
-* Removed Jeweler - [@dblock](http://github.com/dblock).
+* Compatibility with Mongoid 5 - [@dblock](https://github.com/dblock).
 
-1.5.1 (2013/05/07)
---------------------
+### 1.5.2 (2014/12/29)
 
-* Fixed `read_multi` calls so as to enable proper cache reading behavior in stores other than `ActiveSupport::Cache::DalliStore` - [@macreery](http://github.com/macreery).
+* Fixed support for Ruby 2.2.0 - [@dblock](https://github.com/dblock).
+* Implemented RuboCop, Ruby-style linter - [@dblock](https://github.com/dblock).
+* Upgraded to RSpec 3.1 - [@dblock](https://github.com/dblock).
+* Removed Jeweler - [@dblock](https://github.com/dblock).
 
-1.5 (2013/04/13)
-----------------
+### 1.5.1 (2013/05/07)
+
+* Fixed `read_multi` calls so as to enable proper cache reading behavior in stores other than `ActiveSupport::Cache::DalliStore` - [@macreery](https://github.com/macreery).
+
+### 1.5.0 (2013/04/13)
 
 * Added `:reference_properties` that disables dynamic selection of the type of JSON to return for a reference - [@dblock](https://github.com/dblock).
 
-1.4.3 (2013/01/25)
-------------------
+### 1.4.3 (2013/01/25)
 
 * For caches that support `read_multi`, do not attempt to fetch JSON a second time via `fetch`, write it directly to cache - [@dblock](https://github.com/dblock).
 
-1.4.2 (2013/01/24)
-------------------
-
-* Fix: calling `as_json` on a destroyed Mongoid 3.1 object with a HABTM relationship raises `undefined method 'map' for nil:NilClass` - [@dblock](http://github.com/dblock).
+### 1.4.2 (2013/01/24)
 
-1.4.1 (2013/01/22)
-------------------
+* Fix: calling `as_json` on a destroyed Mongoid 3.1 object with a HABTM relationship raises `undefined method 'map' for nil:NilClass` - [@dblock](https://github.com/dblock).
 
-* Invalidate cache in `after_destroy` - [@dblock](http://github.com/dblock).
-* Do not invalidate cache when the document is created - [@dblock](http://github.com/dblock).
-* Invalidate cache in `after_update` instead of `before_update` - [@dblock](http://github.com/dblock).
+### 1.4.1 (2013/01/22)
 
-1.4 (2013/01/20)
----------------
+* Invalidate cache in `after_destroy` - [@dblock](https://github.com/dblock).
+* Do not invalidate cache when the document is created - [@dblock](https://github.com/dblock).
+* Invalidate cache in `after_update` instead of `before_update` - [@dblock](https://github.com/dblock).
 
-* Collect a JSON partial representation first, then fetch data from cache only once per-key - [@dblock](http://github.com/dblock), [@macreery](http://github.com/macreery).
-* Use `read_multi` if the cache store supports it to fetch data from cache in bulk - [@dblock](http://github.com/dblock), [@macreery](http://github.com/macreery).
-* Added a benchmark test suite - [@dblock](http://github.com/dblock), [@macreery](http://github.com/macreery).
+### 1.4.0 (2013/01/20)
 
-1.3 (2012/11/12)
-----------------
+* Collect a JSON partial representation first, then fetch data from cache only once per-key - [@dblock](https://github.com/dblock), [@macreery](https://github.com/macreery).
+* Use `read_multi` if the cache store supports it to fetch data from cache in bulk - [@dblock](https://github.com/dblock), [@macreery](https://github.com/macreery).
+* Added a benchmark test suite - [@dblock](https://github.com/dblock), [@macreery](https://github.com/macreery).
 
-* Removed requirement for `bson_ext`, support for Mongoid 3.0 - [@dblock](http://github.com/dblock).
+### 1.3.0 (2012/11/12)
 
-1.2.3 (2012/07/03)
-------------------
+* Removed requirement for `bson_ext`, support for Mongoid 3.0 - [@dblock](https://github.com/dblock).
 
-* Fix: including a `referenced_in` field in `json_fields` within a child `embedded_in` a parent causes an "access to the collection is not allowed since it is an embedded document" error - [@dblock](http://github.com/dblock).
+### 1.2.3 (2012/07/03)
 
-1.2.2 (2012/07/03)
-------------------
+* Fix: including a `referenced_in` field in `json_fields` within a child `embedded_in` a parent causes an "access to the collection is not allowed since it is an embedded document" error - [@dblock](https://github.com/dblock).
 
-* Fix [#6](https://github.com/mongoid/mongoid-cached-json/issues/6): including parent in `json_fields` within a polymorphic reference fails with an "uninitialized constant" error - [@dblock](http://github.com/dblock).
+### 1.2.2 (2012/07/03)
 
-1.2.1 (2012/06/12)
-------------------
+* Fix [#6](https://github.com/mongoid/mongoid-cached-json/issues/6): including parent in `json_fields` within a polymorphic reference fails with an "uninitialized constant" error - [@dblock](https://github.com/dblock).
 
-* Allow `nil` parameter in as_json - [@dblock](http://github.com/dblock).
+### 1.2.1 (2012/06/12)
 
-1.2.0 (2012/05/28)
-------------------
+* Allow `nil` parameter in as_json - [@dblock](https://github.com/dblock).
 
-* Fix: cache key generation bug when using Mongoid 3 - [@marbemac](http://github.com/marbemac).
+### 1.2.0 (2012/05/28)
 
-1.1.1 (2012/03/21)
-------------------
+* Fix: cache key generation bug when using Mongoid 3 - [@marbemac](https://github.com/marbemac).
 
-* Fix: caching/invalidating referenced polymorphic documents - [@macreery](http://github.com/macreery).
+### 1.1.1 (2012/03/21)
 
-1.1 (2012/02/29)
-----------------
+* Fix: caching/invalidating referenced polymorphic documents - [@macreery](https://github.com/macreery).
 
-* Added support for versioning - [@dblock](http://github.com/dblock).
+### 1.1.0 (2012/02/29)
 
-1.0 (2012/02/20)
-----------------
+* Added support for versioning - [@dblock](https://github.com/dblock).
 
-* Initial release - [@aaw](http://github.com/aaw).
-* Retired support for `:markdown` in favor of `Mongoid::CachedJson::transform` - [@dblock](http://github.com/dblock).
-* Added `Mongoid::CachedJson::configure` - [@dblock](http://github.com/dblock).
-* Added support for `:markdown` - [@macreery](http://github.com/macreery).
+### 1.0.0 (2012/02/20)
 
+* Initial release - [@aaw](https://github.com/aaw).
+* Retired support for `:markdown` in favor of `Mongoid::CachedJson::transform` - [@dblock](https://github.com/dblock).
+* Added `Mongoid::CachedJson::configure` - [@dblock](https://github.com/dblock).
+* Added support for `:markdown` - [@macreery](https://github.com/macreery).

data/CONTRIBUTING.md

@@ -63,6 +63,8 @@ Document any external behavior in the [README](README.md).
 
 Add a line to [CHANGELOG](CHANGELOG.md) under *Next Release*. Make it look like every other line, including your name and link to your Github account.
 
+Danger checks pull requests with `danger-changelog` and reports missing changelog entries in a PR comment. Include the pull request number in your entry once it is available.
+
 #### Commit Changes
 
 Make sure git knows your name and email address:

data/Dangerfile

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+danger.import_dangerfile(gem: 'danger-pr-comment')
+
+changelog.check!

data/Gemfile

@@ -1,30 +1,27 @@
-source 'http://rubygems.org'
+source 'https://rubygems.org'
 
 gemspec
 
-case version = ENV['MONGOID_VERSION'] || '~> 5.0'
-when /7/
-  gem 'mongoid', '~> 7.0'
-when /6/
-  gem 'mongoid', '~> 6.0'
-when /5/
-  gem 'mongoid', '~> 5.0'
-when /4/
-  gem 'mongoid', '~> 4.0'
-when /3/
-  gem 'mongoid', '~> 3.1'
-else
-  gem 'mongoid', version
-end
+version = ENV['MONGOID_VERSION'] || '9'
+gem 'bigdecimal' if RUBY_VERSION >= '3.4'
+gem 'logger' if RUBY_VERSION >= '3.4'
+gem 'mongoid', version =~ /\A\d+\z/ ? "~> #{version}.0" : version
 
 group :development do
-  gem 'dalli', '~> 2.6'
+  if RUBY_VERSION >= '2.7'
+    gem 'danger'
+    gem 'danger-changelog', require: false
+    gem 'danger-pr-comment', require: false
+  end
+  gem 'dalli', RUBY_VERSION >= '3.0' ? '~> 3.0' : '~> 2.6'
   gem 'rake'
-  gem 'rubocop'
+  gem 'rdoc', RUBY_VERSION >= '3.0' ? '>= 6' : '~> 4.2'
+  gem 'rubocop', ENV.fetch('RUBOCOP_VERSION', '>= 0')
   gem 'yard', '~> 0.6'
 end
 
 group :test do
   gem 'mongoid-compatibility'
   gem 'rspec', '~> 3.1'
+  gem 'simplecov', '~> 0.22' if ENV['COVERAGE'] == 'true'
 end

data/README.md

@@ -2,8 +2,10 @@ Mongoid::CachedJson
 ===================
 
 [![Gem Version](https://badge.fury.io/rb/mongoid-cached-json.svg)](http://badge.fury.io/rb/mongoid-cached-json)
-[![Build Status](https://travis-ci.org/mongoid/mongoid-cached-json.svg?branch=master)](https://travis-ci.org/mongoid/mongoid-cached-json)
-[![Code Climate](https://codeclimate.com/github/mongoid/mongoid-cached-json.svg)](https://codeclimate.com/github/mongoid/mongoid-cached-json)
+[![Test](https://github.com/mongoid/mongoid-cached-json/actions/workflows/test.yml/badge.svg?branch=master)](https://github.com/mongoid/mongoid-cached-json/actions/workflows/test.yml?query=branch%3Amaster)
+[![Coverage Status](https://coveralls.io/repos/github/mongoid/mongoid-cached-json/badge.svg?branch=master)](https://coveralls.io/github/mongoid/mongoid-cached-json?branch=master)
+
+The Ruby 4.0 CI job measures library line coverage with SimpleCov and submits `coverage/.resultset.json` to Coveralls using GitHub's automatic token. Other matrix jobs do not submit duplicate reports. Run `COVERAGE=true bundle install` followed by `COVERAGE=true bundle exec rake spec` for a local report. The default-branch badge requires Coveralls to accept an upstream `master` build; configuring this workflow does not activate the external service.
 
 Typical `as_json` definitions may involve lots of database point queries and method calls. When returning collections of objects, a single call may yield hundreds of database queries that can take seconds. This library mitigates the problem by implementing a module called `CachedJson`.
 
@@ -11,16 +13,12 @@ Typical `as_json` definitions may involve lots of database point queries and met
 
 Using `Mongoid::CachedJson` we were able to cut our JSON API average response time by about a factor of 10.
 
-Compatibility
--------------
-
-This gem is compatible with Mongoid 3, 4, 5, 6, and 7.
-
 Resources
 ---------
 
 * [Need Help? Google Group](http://groups.google.com/group/mongoid-cached-json)
 * [Source Code](http://github.com/mongoid/mongoid-cached-json)
+* [Upgrading](UPGRADING.md)
 
 Quickstart
 ----------
@@ -101,7 +99,7 @@ Defining Fields
 
 `Mongoid::CachedJson` supports the following options:
 
-* `:hide_as_child_json_when` is an optional function that hides the child JSON from `as_json` parent objects, eg. `cached_json hide_as_child_json_when: lambda { |instance| ! instance.secret? }`
+* `:hide_as_child_json_when` is an optional function that omits the child key from `as_json` parent objects when it returns true, eg. `cached_json hide_as_child_json_when: lambda { |instance| ! instance.secret? }`. A missing relationship remains a `nil` value.
 
 `Mongoid::CachedJson` field definitions support the following options:
 
@@ -110,8 +108,66 @@ Defining Fields
 * `:properties` can be one of `:short`, `:public`, `:all`, in this order
 * `:version` can be a single version for this field to appear in
 * `:versions` can be an array of versions for this field to appear in
+* `:cache` defaults to `true`; set it to `false` to recompute a field on every serialization (see below)
 * `:reference_properties` can be one of `:short`, `:public`, `:all`, default will select the reference properties format dynamically (see below)
 
+Per-Field Caching
+-----------------
+
+Use `cache: false` for a field whose value should be evaluated on every `as_json` call, even when the rest of the object's JSON comes from the cache. The field is excluded from the cached fragment and merged into the response after that fragment is fetched. Its `definition`, property/version filters, and configured transformations still apply.
+
+``` ruby
+class Product
+  include Mongoid::Document
+  include Mongoid::CachedJson
+
+  field :name
+  field :stock, type: Integer
+
+  json_fields \
+    name: {},
+    stock: { cache: false }
+end
+
+product = Product.create!(name: 'Widget', stock: 10)
+product.as_json # => { name: 'Widget', stock: 10 }
+
+# Unsaved changes illustrate which fields are recomputed on a cache hit.
+product.name = 'Renamed widget'
+product.stock = 9
+product.as_json # => { name: 'Widget', stock: 9 }
+```
+
+The cached `name` stays unchanged until its cache entry expires or is invalidated (for example, by saving the product); `stock` is read from the current model instance each time. This option does not reload the model from MongoDB: reload a stale instance yourself if another process has changed its stored values.
+
+For a `type: :reference` field, `cache: false` bypasses reads and writes of the referenced object's own JSON fragment through that relationship. The parent's other fields remain cached:
+
+``` ruby
+class Order
+  include Mongoid::Document
+  include Mongoid::CachedJson
+
+  field :number
+  belongs_to :product
+
+  json_fields \
+    number: {},
+    product: { type: :reference, cache: false }
+end
+
+order = Order.create!(number: '123', product: product)
+order.as_json # => { number: '123', product: { name: 'Renamed widget', stock: 9 } }
+```
+
+The `product` reference is recomputed even if the product has a cached JSON fragment from another serialization. This does not disable caching on the `Product` model itself: `product.as_json` and other relationships to that product still use their normal cache policies. References nested inside the product also retain their own cache policies; the bypass is not recursive.
+
+All Stored Fields
+-----------------
+
+Use `json_fields :all, display_name: { definition: :display_name }` to expand every Mongoid field declared so far (including `_id`) into an ordinary JSON field, then merge explicit definitions. An explicit definition overrides the generated definition for the same symbol key; for example, `json_fields :all, secret: { properties: :all }` restricts that field to the `:all` representation.
+
+Declare Mongoid fields before `json_fields :all`. Later declarations, dynamic attributes, and associations are not added automatically; declare references explicitly with `type: :reference`. This is opt-in and may expose sensitive stored data or foreign keys, so prefer an explicit allowlist for public APIs. Runtime `as_json(methods: ...)` selection remains unsupported: declare computed methods in `json_fields`.
+
 Reference Properties
 --------------------
 
@@ -119,7 +175,7 @@ When calling `as_json` on a model that contains references to other models the v
 
 * Use the value of the `:reference_properties` option, if specified.
 * For `:short` JSON, use `:short`.
-* For `:public` JSON, use `:short`.
+* For `:public` JSON, use `:public`.
 * For `:all` JSON, use `:all`.
 
 The dynamic selection where `:public` generates `:short` references allows to return smaller embedded collections, while `:all` allows to fetch deep data. Another way of looking at this is to say that a field in a `:short` JSON appears in collections, a field declared in the `:public` JSON appears for all users and the field declared in the `:all` JSON appears for object owners only.
@@ -177,6 +233,13 @@ person.as_json(version: :v2) # { first: 'John', middle: 'F.', last: 'Kennedy', n
 person.as_json(version: :v3) # { first: 'John', middle: 'F.', last: 'Kennedy', name: 'John F. Kennedy', born: 'May 29, 1917' }
 ```
 
+Schema Cache Versions
+---------------------
+
+Declare `json_fields cache_version: 2, name: {}` to add a model-specific schema namespace to its cache keys. Increment it when changing fields, computed values, or transformations in a deployment. This is independent of the API `version:` passed to `as_json`; callers need not change. Omitting `cache_version` preserves existing keys.
+
+New code stops reading old fragments, including referenced fragments of that model. Old entries are not deleted and remain until eviction or a cache-store TTL. The gem does not set a default TTL; configure `expires_in` on your cache store if needed. Updates expire only the current namespace. For rolling deployments or rollbacks, do not reuse a namespace containing stale values: coordinate invalidation or choose another version.
+
 Transformations
 ---------------
 
@@ -213,6 +276,28 @@ Turning Caching Off
 
 You can set `Mongoid::CachedJson.config.disable_caching = true`. It may be a good idea to set it to `ENV['DISABLE_JSON_CACHING']`, in case this turns out not to be The Solution To All Of Your Performance Problems (TM).
 
+To bypass shared-cache reads and writes for one model while retaining its JSON fields, versions, and property hierarchy, declare `json_fields disable_caching: true, name: {}`. This applies when the model is serialized directly, in collections, or as a reference. Other models, including its parent and referenced children, keep their own caching policy. Changes to an uncached child are visible even when its parent's scalar fields are cached.
+
+Cache Invalidation Boundaries
+-----------------------------
+
+Normal model updates and destroys expire that document's JSON fragments through Mongoid callbacks. Bulk or raw collection updates that bypass model callbacks cannot invalidate the cache automatically. Explicitly expire each affected document after such a write:
+
+``` ruby
+User.where(id: user_id).update_all(status: 'active')
+User.find(user_id).expire_cached_json
+```
+
+Concurrent writes have a separate boundary: an older in-memory instance can repopulate a fragment after another instance has saved newer values and expired the cache. Reload stale instances before serializing them, and expire their fragments if a stale writer may already have repopulated the cache:
+
+``` ruby
+user.reload
+user.expire_cached_json
+user.as_json
+```
+
+Reloading and expiring are not an atomic cross-process operation. This gem does not provide a distributed revision or compare-and-set protocol for cache stores. Applications requiring strict consistency across concurrent writers should coordinate persistence and cache invalidation themselves or disable caching for the affected data.
+
 Testing JSON
 ------------
 

data/UPGRADING.md

@@ -0,0 +1,59 @@
+# Upgrading
+
+## Upgrading to 1.7.0
+
+### Hidden child references
+
+[#35](https://github.com/mongoid/mongoid-cached-json/pull/35) changes how a single child reference is serialized when the child's `hide_as_child_json_when` predicate returns `true`. Previously, an existing but hidden child and a missing child both appeared as `child: nil` (`"child": null` in JSON), so clients could not distinguish them. Now, an existing but hidden child's key is omitted; a missing child still appears as `child: nil`.
+
+Here, `parent` is a `SecretParent` document with a `has_one` relationship to a `SometimesSecret` document. The parent exposes that relationship as the JSON field `child`; the hiding predicate is defined on the child model:
+
+```ruby
+class SecretParent
+  include Mongoid::Document
+  include Mongoid::CachedJson
+
+  field :name
+  has_one :sometimes_secret
+
+  json_fields \
+    name: {},
+    child: { definition: :sometimes_secret, type: :reference }
+end
+
+class SometimesSecret
+  include Mongoid::Document
+  include Mongoid::CachedJson
+
+  field :secret
+  field :should_tell_secret, type: Boolean
+  belongs_to :secret_parent
+
+  json_fields \
+    hide_as_child_json_when: lambda { |child| !child.should_tell_secret },
+    secret: {}
+end
+
+parent = SecretParent.create!(name: 'Parent')
+parent.create_sometimes_secret!(secret: 'Afraid of the dark', should_tell_secret: false)
+
+# The child exists, but its hiding predicate returns true.
+# Before 1.7.0:
+parent.as_json(properties: :short)
+# => { name: 'Parent', child: nil }
+
+# From 1.7.0:
+parent.as_json(properties: :short)
+# => { name: 'Parent' }
+
+# By contrast, a parent with no child still includes an explicit nil.
+parent_without_child = SecretParent.create!(name: 'No child')
+parent_without_child.as_json(properties: :short)
+# => { name: 'No child', child: nil }
+```
+
+A genuinely missing relationship still includes `child: nil`. Requests using `properties: :all` and serialization of the child itself are unchanged.
+
+Update clients and response schemas that require the child key to allow its absence. In Ruby, `json[:child]` still returns `nil` for either case; use `json.key?(:child)` to distinguish an omitted key from an explicit `nil`.
+
+Invalidate existing cached JSON fragments when deploying this change so cached results use the new representation. If the cache is shared with other applications, invalidate only this application's cached JSON entries rather than clearing the entire store.

data/lib/mongoid-cached-json/cached_json.rb

@@ -1,14 +1,19 @@
 # encoding: utf-8
 module Mongoid
   module CachedJson
+    HIDDEN_JSON = :__mongoid_cached_json_hidden__
+
     extend ActiveSupport::Concern
 
     included do
       class_attribute :all_json_properties
       class_attribute :all_json_versions
       class_attribute :cached_json_field_defs
+      class_attribute :cached_json_uncached_field_defs
       class_attribute :cached_json_reference_defs
       class_attribute :hide_as_child_json_when
+      class_attribute :cached_json_cache_version
+      class_attribute :cached_json_disable_caching
     end
 
     module ClassMethods
@@ -17,11 +22,17 @@ module Mongoid
       # @param [ hash ] defs JSON field definition.
       #
       # @since 1.0
-      def json_fields(defs)
+      def json_fields(defs, additions = {})
+        if defs == :all
+          defs = Hash[fields.keys.map { |field| [field.to_sym, {}] }].merge(additions)
+        end
+        self.cached_json_cache_version = defs.delete(:cache_version)
+        self.cached_json_disable_caching = defs.delete(:disable_caching)
         self.hide_as_child_json_when = defs.delete(:hide_as_child_json_when) || lambda { |_a| false }
         self.all_json_properties = [:short, :public, :all]
         cached_json_defs = Hash[defs.map { |k, v| [k, { type: :callable, properties: :short, definition: k }.merge(v)] }]
         self.cached_json_field_defs = {}
+        self.cached_json_uncached_field_defs = {}
         self.cached_json_reference_defs = {}
         # Collect all versions for clearing cache
         self.all_json_versions = cached_json_defs.map do |_field, definition|
@@ -29,7 +40,10 @@ module Mongoid
         end.flatten.compact.uniq
         all_json_properties.each_with_index do |property, i|
           cached_json_field_defs[property] = Hash[cached_json_defs.find_all do |_field, definition|
-            all_json_properties.find_index(definition[:properties]) <= i && definition[:type] == :callable
+            all_json_properties.find_index(definition[:properties]) <= i && definition[:type] == :callable && definition[:cache] != false
+          end]
+          cached_json_uncached_field_defs[property] = Hash[cached_json_defs.find_all do |_field, definition|
+            all_json_properties.find_index(definition[:properties]) <= i && definition[:type] == :callable && definition[:cache] == false
           end]
           cached_json_reference_defs[property] = Hash[cached_json_defs.find_all do |_field, definition|
             all_json_properties.find_index(definition[:properties]) <= i && definition[:type] == :reference
@@ -49,8 +63,10 @@ module Mongoid
       def materialize_cached_json(clazz, id, object_reference, options)
         is_top_level_json = options[:is_top_level_json] || false
         object_reference = clazz.where(_id: id).first unless object_reference
-        if !object_reference || (!is_top_level_json && options[:properties] != :all && clazz.hide_as_child_json_when.call(object_reference))
+        if !object_reference
           nil
+        elsif !is_top_level_json && options[:properties] != :all && clazz.hide_as_child_json_when.call(object_reference)
+          HIDDEN_JSON
         else
           Hash[clazz.cached_json_field_defs[options[:properties]].map do |field, definition|
             # version match
@@ -65,6 +81,22 @@ module Mongoid
         end
       end
 
+      # Materialize JSON fields that opt out of shared caching.
+      def materialize_uncached_json(clazz, id, object_reference, options)
+        object_reference = clazz.where(_id: id).first unless object_reference
+        return {} unless object_reference
+
+        Hash[clazz.cached_json_uncached_field_defs[options[:properties]].map do |field, definition|
+          versions = ([definition[:version]] | Array(definition[:versions])).compact
+          next unless versions.empty? || versions.include?(options[:version])
+          json_value = (definition[:definition].is_a?(Symbol) ? object_reference.send(definition[:definition]) : definition[:definition].call(object_reference))
+          Mongoid::CachedJson.config.transform.each do |t|
+            json_value = t.call(field, definition, json_value)
+          end
+          [field, json_value]
+        end.compact]
+      end
+
       # Given an object definition in the form of either an object or a class, id pair,
       # grab the as_json representation from the cache if possible, otherwise create
       # the as_json representation by loading the object from the database. For any
@@ -84,7 +116,8 @@ module Mongoid
           id = object_def[:id]
         end
         key = cached_json_key(options, clazz, id)
-        json = { _ref: { _clazz: self, _key: key, _materialize_cached_json: [clazz, id, object_reference, options] } }
+        json = { _ref: { _clazz: self, _key: key, _disable_caching: clazz.cached_json_disable_caching,
+                        _materialize_cached_json: [clazz, id, object_reference, options] } }
         keys = KeyReferences.new
         keys.set_and_add(key, json)
         reference_defs = clazz.cached_json_reference_defs[options[:properties]]
@@ -98,6 +131,12 @@ module Mongoid
                 ref[:_parent] = json
                 ref[:_field] = field
               end
+              if definition[:cache] == false
+                references = reference.is_a?(Array) ? reference : [reference]
+                references.each do |item|
+                  item[:_ref][:_disable_caching] = true if item.is_a?(Hash) && item[:_ref]
+                end
+              end
               keys.merge_set(reference_keys)
               [field, reference]
             end])
@@ -109,7 +148,8 @@ module Mongoid
       # Cache key.
       def cached_json_key(options, cached_class, cached_id)
         base_class_name = cached_class.collection_name.to_s.singularize.camelize
-        "as_json/#{options[:version]}/#{base_class_name}/#{cached_id}/#{options[:properties]}/#{!!options[:is_top_level_json]}"
+        key = "as_json/#{options[:version]}/#{base_class_name}/#{cached_id}/#{options[:properties]}/#{!!options[:is_top_level_json]}"
+        cached_class.cached_json_cache_version.nil? ? key : "#{key}/schema/#{cached_class.cached_json_cache_version}"
       end
 
       # If the reference is a symbol, we may be lucky and be able to figure out the as_json
@@ -151,13 +191,11 @@ module Mongoid
           reference_def_definition = reference_def[:definition]
           reference = reference_def_definition.is_a?(Symbol) ? object.send(reference_def_definition) : reference_def_definition.call(object)
           reference_json = nil
-          if reference
-            if reference.respond_to?(:as_json_partial)
-              reference_keys, reference_json = reference.as_json_partial(options)
-              keys = keys ? keys.merge_set(reference_keys) : reference_keys
-            else
-              reference_json = reference.as_json(options)
-            end
+          if reference.respond_to?(:as_json_partial)
+            reference_keys, reference_json = reference.as_json_partial(options)
+            keys = keys ? keys.merge_set(reference_keys) : reference_keys
+          else
+            reference_json = reference.as_json(options)
           end
         end
         [keys, reference_json]
@@ -166,8 +204,10 @@ module Mongoid
 
     # Check whether the cache supports :read_multi and prefetch the data if it does.
     def self.materialize_json_references_with_read_multi(key_refs, partial_json)
-      unfrozen_keys = key_refs.keys.to_a.map(&:dup) if key_refs # see https://github.com/mperham/dalli/pull/320
-      read_multi = unfrozen_keys && Mongoid::CachedJson.config.cache.respond_to?(:read_multi)
+      if key_refs
+        unfrozen_keys = key_refs.select { |_key, refs| refs.any? { |ref| !ref[:_ref][:_disable_caching] } }.keys.map(&:dup)
+      end
+      read_multi = unfrozen_keys && !unfrozen_keys.empty? && Mongoid::CachedJson.config.cache.respond_to?(:read_multi)
       local_cache = read_multi ? Mongoid::CachedJson.config.cache.read_multi(*unfrozen_keys) : {}
       Mongoid::CachedJson.materialize_json_references(key_refs, local_cache, read_multi) if key_refs
       partial_json
@@ -180,7 +220,9 @@ module Mongoid
           _ref = ref.delete(:_ref)
           key = _ref[:_key]
           fetched_json = local_cache[key] if local_cache.key?(key)
-          unless fetched_json
+          if _ref[:_disable_caching]
+            fetched_json = _ref[:_clazz].materialize_cached_json(* _ref[:_materialize_cached_json])
+          elsif !fetched_json
             if read_multi
               # no value in cache, materialize and write
               fetched_json = (local_cache[key] = _ref[:_clazz].materialize_cached_json(* _ref[:_materialize_cached_json]))
@@ -192,8 +234,11 @@ module Mongoid
               end)
             end
           end
-          if fetched_json
+          if fetched_json == HIDDEN_JSON
+            _ref[:_parent].delete(_ref[:_field]) if _ref[:_parent]
+          elsif fetched_json
             ref.merge! fetched_json
+            ref.merge! _ref[:_clazz].materialize_uncached_json(* _ref[:_materialize_cached_json])
           elsif _ref[:_parent]
             # a single _ref that resolved to a nil
             _ref[:_parent][_ref[:_field]] = nil

data/lib/mongoid-cached-json/version.rb

@@ -1,5 +1,5 @@
 module Mongoid
   module CachedJson
-    VERSION = '1.6.0'
+    VERSION = '1.7.0'
   end
 end