oj_serializers 2.0.0.pre.beta.1 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4ebc24ba352b46585589ae760b579009e18e9de772b1d015eb0fdfa465a39b93
-  data.tar.gz: 475283ebe5897716eb1812a474358ddc3775746e1e0f8ff011204fc3ff76219e
+  metadata.gz: 281e961cd6a9da8c3723dd56ce7e1aa8ec112c57d13ab15e763ecef98eb1f659
+  data.tar.gz: cd9a42db1ea64aac9c75755550ce0bb3123646ac85020056a4d3bc5dae7e9251
 SHA512:
-  metadata.gz: e4a0c4e060fbac9cc04ef2e6ce31406fa5aa83052989a272e2bba6c1b7c30767e82bd22aa51b016716adfff8bb039442a7725f25ddf7093ca4b33de646360181
-  data.tar.gz: d0d41a7a283e26831222a99b96669498eb01b14dac383da008db053c769052ca0e91b1078f1c0d9c797faadd082b3ecaeabce37fa267d617bc2bc039a05dcaec
+  metadata.gz: c3816ef19190cf4dbddfa942d205b21cb0d639ed33cf9ff34a9972038179d677cfabe659fc36f1780e6fb64fb8c7145a756012bfc1a8de3bc4cb0256e419917a
+  data.tar.gz: 364da01e189d7c00b4abcbaa490c2e8a0432acf9f126a0db67ccab3d1a2c7a1b1724267ec084980ba706ad43fb89c1964749a4684736d72888f6ddb5fe970f3f

data/CHANGELOG.md

@@ -1,3 +1,20 @@
+## [Oj Serializers 2.0.0 (2023-03-27)](https://github.com/ElMassimo/oj_serializers/pull/9)
+
+### Features ✨
+
+- Improved performance (20% to 40% faster than v1)
+- Added `render_as_hash` to efficiently build a Hash from the serializer
+- `transform_keys :camelize`: a built-in setting to convert keys, in a way that does not affect runtime performance
+- `sort_keys_by :name`: allows to sort the response alphabetically, without affecting runtime performance
+- `render` shortcut, unifying `one` and `many`
+- `attribute` as an easier approach to define serializer attributes
+
+### Breaking Changes
+
+Since returning a `Hash` is more convenient than returning a `Oj::StringWriter`, and performance is comparable, `default_format :hash` is now the default.
+
+The previous APIs will still be available as `one_as_json` and `many_as_json`, as well as `default_format :json` to make the library work like in version 1.
+
 ## Oj Serializers 1.0.2 (2023-03-01) ##
 
 *   [fix: avoid freezing `ALLOWED_INSTANCE_VARIABLES`](https://github.com/ElMassimo/oj_serializers/commit/ade0302)

data/README.md

@@ -6,7 +6,7 @@ Oj Serializers
 <a href="https://codeclimate.com/github/ElMassimo/oj_serializers"><img alt="Maintainability" src="https://codeclimate.com/github/ElMassimo/oj_serializers/badges/gpa.svg"/></a>
 <a href="https://codeclimate.com/github/ElMassimo/oj_serializers"><img alt="Test Coverage" src="https://codeclimate.com/github/ElMassimo/oj_serializers/badges/coverage.svg"/></a>
 <a href="https://rubygems.org/gems/oj_serializers"><img alt="Gem Version" src="https://img.shields.io/gem/v/oj_serializers.svg?colorB=e9573f"/></a>
-<a href="https://github.com/ElMassimo/oj_serializers/blob/master/LICENSE.txt"><img alt="License" src="https://img.shields.io/badge/license-MIT-428F7E.svg"/></a>
+<a href="https://github.com/ElMassimo/oj_serializers/blob/main/LICENSE.txt"><img alt="License" src="https://img.shields.io/badge/license-MIT-428F7E.svg"/></a>
 </p>
 </h1>
 
@@ -19,14 +19,15 @@ Faster JSON serializers for Ruby, built on top of the powerful [`oj`][oj] librar
 [panko]: https://github.com/panko-serializer/panko_serializer
 [blueprinter]: https://github.com/procore/blueprinter
 [benchmarks]: https://github.com/ElMassimo/oj_serializers/tree/master/benchmarks
-[raw_benchmarks]: https://github.com/ElMassimo/oj_serializers/blob/master/benchmarks/document_benchmark.rb
-[sugar]: https://github.com/ElMassimo/oj_serializers/blob/master/lib/oj_serializers/sugar.rb#L14
-[migration guide]: https://github.com/ElMassimo/oj_serializers/blob/master/MIGRATION_GUIDE.md
+[raw_benchmarks]: https://github.com/ElMassimo/oj_serializers/blob/main/benchmarks/document_benchmark.rb
+[sugar]: https://github.com/ElMassimo/oj_serializers/blob/main/lib/oj_serializers/sugar.rb#L14
+[migration guide]: https://github.com/ElMassimo/oj_serializers/blob/main/MIGRATION_GUIDE.md
 [design]: https://github.com/ElMassimo/oj_serializers#design-
 [raw_json]: https://github.com/ohler55/oj/issues/542
 [trailing_commas]: https://maximomussini.com/posts/trailing-commas/
 [render dsl]: https://github.com/ElMassimo/oj_serializers#render-dsl-
 [sorbet]: https://sorbet.org/
+[Discussion]: https://github.com/ElMassimo/oj_serializers/discussions
 
 ## Why? 🤔
 
@@ -39,8 +40,8 @@ Learn more about [how this library achieves its performance][design].
 
 ## Features ⚡️
 
-- Declaration syntax similar to Active Model Serializers
-- Reduced memory allocation and [improved performance][benchmarks]
+- Declaration syntax [similar to Active Model Serializers][migration guide]
+- Reduced [memory allocation][benchmarks] and [improved performance][benchmarks]
 - Support for `has_one` and `has_many`, compose with `flat_one`
 - Useful development checks to avoid typos and mistakes
 - Integrates nicely with Rails controllers
@@ -66,7 +67,7 @@ attributes should be serialized.
 class AlbumSerializer < Oj::Serializer
   attributes :name, :genres
 
-  serialize
+  attr
   def release
     album.release_date.strftime('%B %d, %Y')
   end
@@ -139,48 +140,23 @@ end
 ```
 </details>
 
-<br/>
-
-To use the serializer, the recommended approach is:
+You can then use your new serializer to render an object or collection:
 
 ```ruby
 class AlbumsController < ApplicationController
   def show
-    album = Album.find(params[:id])
     render json: AlbumSerializer.one(album)
   end
 
   def index
-    albums = Album.all
     render json: { albums: AlbumSerializer.many(albums) }
   end
 end
 ```
 
-If you are using Rails you can also use something closer to Active Model Serializers by adding [`sugar`][sugar]:
-
-```ruby
-require 'oj_serializers/sugar'
-
-class AlbumsController < ApplicationController
-  def show
-    album = Album.find(params[:id])
-    render json: album, serializer: AlbumSerializer
-  end
-
-  def index
-    albums = Album.all
-    render json: albums, each_serializer: AlbumSerializer, root: :albums
-  end
-end
-```
-
-It's recommended to create your own `BaseSerializer` class in order to easily
-add custom extensions, specially when migrating from `active_model_serializers`.
+## Rendering 🖨
 
-## Render DSL 🛠
-
-In order to efficiently reuse the instances, serializers can't be instantiated directly. Use `one` and `many` to serialize objects or enumerables:
+Use `one` to serialize objects, and `many` to serialize enumerables:
 
 ```ruby
 render json: {
@@ -189,187 +165,212 @@ render json: {
 }
 ```
 
-You can use these serializers inside arrays, hashes, or even inside `ActiveModel::Serializer` by using a method in the serializer.
-
-## Attributes DSL 🛠
+Serializers can be rendered arrays, hashes, or even inside `ActiveModel::Serializer`
+by using a method in the serializer, making it very easy to combine with other
+libraries and migrate incrementally.
 
-Attributes methods can be used to define which model attributes should be serialized
-to JSON. Each method provides a different strategy to obtain the values to serialize.
+You can use `render` as a shortcut for `one` and `many`, but it might be less readable:
 
-The internal design is simple and extensible, so creating new strategies requires very little code.
-Please open an issue if you need help 😃
+```ruby
+render json: {
+  favorite_album: AlbumSerializer.render(album),
+  purchased_albums: AlbumSerializer.render(albums),
+}
+```
 
-### `attributes`
+## Attributes DSL 🪄
 
-Obtains the attribute value by calling a method in the object being serialized.
+Specify which attributes should be rendered by calling a method in the object to serialize.
 
 ```ruby
 class PlayerSerializer < Oj::Serializer
-  attributes :full_name
+  attributes :first_name, :last_name, :full_name
 end
 ```
 
-Have in mind that unlike Active Model Serializers, it will _not_ take into
-account methods defined in the serializer. Being explicit about where the
-attribute is coming from makes the serializers easier to understand and more
-maintainable.
-
-### `serializer_attributes`
-
-Obtains the attribute value by calling a method defined in the serializer.
-
-Simply call `serialize` right before defining the method, and it will be serialized:
+You can serialize custom values by specifying that a method is an `attribute`:
 
 ```ruby
 class PlayerSerializer < Oj::Serializer
-  serialize
-  def full_name
+  attribute :name do
     "#{player.first_name} #{player.last_name}"
   end
-end
-```
-
-> This inline syntax was inspired by how types are defined in [`sorbet`][sorbet].
 
-Instance methods can access the object by the serializer name without the
-`Serializer` suffix, `player` in the example above, or directly as `@object`.
+  # or
 
-You can customize this by using [`object_as`](#using-a-different-alias-for-the-internal-object).
-
-### `ams_attributes` 🐌
-
-Works like `attributes` in Active Model Serializers, by calling a method in the serializer if defined, or calling `read_attribute_for_serialization` in the model.
-
-```ruby
-class AlbumSerializer < Oj::Serializer
-  ams_attributes :name, :release
-
-  def release
-    album.release_date.strftime('%B %d, %Y')
+  attribute
+  def name
+    "#{player.first_name} #{player.last_name}"
   end
 end
 ```
 
-Should only be used when migrating from Active Model Serializers, as it's slower and can create confusion.
+> **Note**
+>
+> In this example, `player` was inferred from `PlayerSerializer`.
+>
+> You can customize this by using [`object_as`](#using-a-different-alias-for-the-internal-object).
 
-Instead, use `attributes` for model methods, and the inline `attribute` for serializer attributes. Being explicit makes serializers easier to understand, and to maintain.
 
-Please refer to the [migration guide] for more information.
+### Associations 🔗
 
-### `hash_attributes` 🚀
+Use `has_one` to serialize individual objects, and `has_many` to serialize a collection.
 
-Very convenient when serializing Hash-like structures, this strategy uses the `[]` operator.
+You must specificy which serializer to use with the `serializer` option.
 
 ```ruby
-class PersonSerializer < Oj::Serializer
-  hash_attributes 'first_name', :last_name
+class SongSerializer < Oj::Serializer
+  has_one :album, serializer: AlbumSerializer
+  has_many :composers, serializer: ComposerSerializer
 end
-
-PersonSerializer.one('first_name' => 'Mary', :middle_name => 'Jane', :last_name => 'Watson')
-# {"first_name":"Mary","last_name":"Watson"}
 ```
 
-### `mongo_attributes` 🚀
-
-Reads data directly from `attributes` in a [Mongoid] document.
-
-By skipping type casting, coercion, and defaults, it [achieves the best performance][raw_benchmarks].
-
-Although there are some downsides, depending on how consistent your schema is,
-and which kind of consumer the API has, it can be really powerful.
+Specify a different value for the association by providing a block:
 
 ```ruby
-class AlbumSerializer < Oj::Serializer
-  mongo_attributes :id, :name
+class SongSerializer < Oj::Serializer
+  has_one :album, serializer: AlbumSerializer do
+    Album.find_by(song_ids: song.id)
+  end
 end
 ```
 
-## Associations DSL 🛠
+In case you need to pass options, you can call the serializer manually:
 
-Use `has_one` to serialize individual objects, and `has_many` to serialize a collection.
+```ruby
+class SongSerializer < Oj::Serializer
+  attribute :album do
+    AlbumSerializer.one(song.album, for_song: song)
+  end
+end
+```
 
-The value for the association is obtained from a serializer method if defined,
-or by calling the method in the object being serialized.
+### Aliasing or renaming attributes ↔️
 
-You must specificy which serializer to use with the `serializer` option.
+You can pass `as` when defining an attribute or association to serialize it
+using a different key:
 
 ```ruby
 class SongSerializer < Oj::Serializer
-  has_one :album, serializer: AlbumSerializer
-  has_many :composers, serializer: ComposerSerializer
+  has_one :album, as: :first_release, serializer: AlbumSerializer
 
-  # You can also compose serializers using `flat_one`.
-  flat_one :song, serializer: SongMetadataSerializer
+  attributes title: {as: :name}
+
+  # or as a shortcut
+  attributes title: :name
 end
 ```
 
-The associations DSL is essentially a shortcut for defining attributes manually:
+### Conditional attributes ❔
+
+You can render attributes and associations conditionally by using `:if`.
 
 ```ruby
-class SongSerializer < SongMetadataSerializer
-  serialize
-  def album
-    AlbumSerializer.one(song.album)
-  end
+class PlayerSerializer < Oj::Serializer
+  attributes :first_name, :last_name, if: -> { player.display_name? }
 
-  serialize
-  def composers
-    ComposerSerializer.many(song.composers)
-  end
+  has_one :album, serializer: AlbumSerializer, if: -> { player.album }
 end
 ```
 
-## Other DSL 🛠
+This is useful in cases where you don't want to `null` values to be in the response.
+
+## Advanced Usage 🧙‍♂️
 
 ### Using a different alias for the internal object
 
-You can use `object_as` to create an alias for the serialized object to access it from instance methods:
+In most cases, the default alias for the `object` will be convenient enough.
+
+However, if you would like to specify it manually, use `object_as`:
 
 ```ruby
 class DiscographySerializer < Oj::Serializer
   object_as :artist
 
   # Now we can use `artist` instead of `object` or `discography`.
-  serialize
+  attribute
   def latest_albums
     artist.albums.desc(:year)
   end
 end
 ```
 
-### Aliasing or renaming attributes
+### Identifier attributes
 
-You can pass `as` when defining an attribute or association to serialize it
-using a different key:
+The `identifier` method allows you to only include an identifier if the record
+or document has been persisted.
 
 ```ruby
-class SongSerializer < Oj::Serializer
-  has_one :album, as: :latest_album, serializer: AlbumSerializer
+class AlbumSerializer < Oj::Serializer
+  identifier
 
-  attribute :title, as: :name
+  # or if it's a different field
+  identifier :uuid
 end
 ```
 
-### Rendering an attribute conditionally
+Additionally, identifier fields are always rendered first, even when sorting
+fields alphabetically.
+
+### Transforming attribute keys 🗝
+
+When serialized data will be consumed from a client language that has different
+naming conventions, it can be convenient to transform keys accordingly.
+
+For example, when rendering an API to be consumed from the browser via JavaScript,
+where properties are traditionally named using camel case.
 
-All the attributes and association methods can take an `if` option to render conditionally.
+Use `transform_keys` to handle that conversion.
 
 ```ruby
-class AlbumSerializer < Oj::Serializer
-  mongo_attributes :release_date, if: -> { album.released? }
+class BaseSerializer < Oj::Serializer
+  transform_keys :camelize
+
+  # shortcut for
+  transform_keys -> (key) { key.to_s.camelize(:lower) }
+end
+```
+
+This has no performance impact, as keys will be transformed at load time.
+
+### Sorting attributes 📶
+
+By default attributes are rendered in the order they are defined.
+
+If you would like to sort attributes alphabetically, you can specify it at a
+serializer level:
+
+```ruby
+class BaseSerializer < Oj::Serializer
+  sort_attributes_by :name # or a Proc
+end
+```
+
+This has no performance impact, as attributes will be sorted at load time.
 
-  has_many :songs, serializer: SongSerializer, if: -> { album.songs.any? }
+### Path helpers 🛣
 
-  # You can achieve the same by manually defining a method:
-  def include_songs?
-    album.songs.any?
+In case you need to access path helpers in your serializers, you can use the
+following:
+
+```ruby
+class BaseSerializer < Oj::Serializer
+  include Rails.application.routes.url_helpers
+
+  def default_url_options
+    Rails.application.routes.default_url_options
   end
 end
 ```
 
-### Memoization & Local State
+One slight variation that might make it easier to maintain in the long term is
+to use a separate singleton service to provide the url helpers and options, and
+make it available as `urls`.
+
+### Memoization & local state
 
-Serializers are designed to be stateless so that an instanced can be reused, but sometimes it's convenient to store intermediate calculations.
+Serializers are designed to be stateless so that an instanced can be reused, but
+sometimes it's convenient to store intermediate calculations.
 
 Use `memo` for memoization and storing temporary information.
 
@@ -377,7 +378,7 @@ Use `memo` for memoization and storing temporary information.
 class DownloadSerializer < Oj::Serializer
   attributes :filename, :size
 
-  serialize
+  attribute
   def progress
     "#{ last_event&.progress || 0 }%"
   end
@@ -392,23 +393,86 @@ private
 end
 ```
 
-### Writing directly to JSON
+### `hash_attributes` 🚀
 
-In some corner cases it might be faster to serialize using a `Oj::StringWriter`.
+Very convenient when serializing Hash-like structures, this strategy uses the `[]` operator.
 
-You can toggle this mode at a serializer level by using `default_format :json`,
-or configure it globally from your base serializer.
+```ruby
+class PersonSerializer < Oj::Serializer
+  hash_attributes 'first_name', :last_name
+end
+
+PersonSerializer.one('first_name' => 'Mary', :middle_name => 'Jane', :last_name => 'Watson')
+# {first_name: "Mary", last_name: "Watson"}
+```
+
+### `mongo_attributes` 🚀
+
+Reads data directly from `attributes` in a [Mongoid] document.
+
+By skipping type casting, coercion, and defaults, it [achieves the best performance][raw_benchmarks].
+
+Although there are some downsides, depending on how consistent your schema is,
+and which kind of consumer the API has, it can be really powerful.
+
+```ruby
+class AlbumSerializer < Oj::Serializer
+  mongo_attributes :id, :name
+end
+```
+
+### Caching 📦
+
+Usually rendering is so fast that __turning caching on can be slower__.
+
+However, in cases of deeply nested structures, unpredictable query patterns, or
+methods that take a long time to run, caching can improve performance.
+
+To enable caching, use `cached`, which calls `cache_key` in the object:
+
+```ruby
+class CachedUserSerializer < UserSerializer
+  cached
+end
+```
+
+You can also provide a lambda to `cached_with_key` to define a custom key:
+
+```ruby
+class CachedUserSerializer < UserSerializer
+  cached_with_key ->(user) {
+    "#{ user.id }/#{ user.current_sign_in_at }"
+  }
+end
+```
+
+It will leverage `fetch_multi` when serializing a collection with `many` or
+`has_many`, to minimize the amount of round trips needed to read and write all
+items to cache.
+
+This works specially well if your cache store also supports `write_multi`.
+
+### Writing to JSON
+
+In some corner cases it might be faster to serialize using a `Oj::StringWriter`,
+which you can access by using `one_as_json` and `many_as_json`.
+
+Alternatively, you can toggle this mode at a serializer level by using
+`default_format :json`, or configure it globally from your base serializer:
 
 ```ruby
 class BaseSerializer < Oj::Serializer
-  default_format :json # :hash is the default
+  default_format :json
 end
 ```
 
 This will change the default shortcuts (`render`, `one`, `one_if`, and `many`),
 so that the serializer writes directly to JSON instead of returning a Hash.
 
-Follow [this discussion][raw_json] to find out more about [the `raw_json` extensions][raw_json] that made this high level of interoperability possible.
+> **Note**
+>
+> This was the default behavior in `oj_serializers` v1, but was replaced with
+`default_format :hash` in v2.
 
 <details>
   <summary>Example Output</summary>
@@ -494,6 +558,9 @@ Follow [this discussion][raw_json] to find out more about [the `raw_json` extens
 ```
 </details>
 
+Even when using this mode, you can still use rendered values inside arrays,
+hashes, and other serializers, thanks to [the `raw_json` extensions][raw_json].
+
 ## Design 📐
 
 Unlike `ActiveModel::Serializer`, which builds a Hash that then gets encoded to
@@ -503,6 +570,10 @@ greatly reducing the overhead of allocating and garbage collecting the hashes.
 It also allocates a single instance per serializer class, which makes it easy
 to use, while keeping memory usage under control.
 
+The internal design is simple and extensible, and because the library is written
+in Ruby, creating new serialization strategies requires very little code.
+Please open a [Discussion] if you need help 😃
+
 ### Comparison with other libraries
 
 `ActiveModel::Serializer` instantiates one serializer object per item to be serialized.
@@ -516,9 +587,24 @@ mixins must be applied to the class itself.
 
 `Oj::Serializer` combines some of these ideas, by using instances, but reusing them to avoid object allocations. Serializing 10,000 items instantiates a single serializer. Unlike `panko-serializer`, it doesn't suffer from [double encoding problems](https://panko.dev/docs/response-bag) so it's easier to use.
 
+Follow [this discussion][raw_json] to find out more about [the `raw_json` extensions][raw_json] that made this high level of interoperability possible.
+
 As a result, migrating from `active_model_serializers` is relatively
 straightforward because instance methods, inheritance, and mixins work as usual.
 
+### Benchmarks 📊
+
+This library includes some [benchmarks] to compare performance with similar libraries.
+
+See [this pull request](https://github.com/ElMassimo/oj_serializers/pull/9) for a quick comparison,
+or check the CI to see the latest results.
+
+### Migrating from other libraries
+
+Please refer to the [migration guide] for a full discussion of the compatibility
+modes available to make it easier to migrate from `active_model_serializers` and
+similar libraries.
+
 ## Formatting 📏
 
 Even though most of the examples above use a single-line style to be succint, I highly recommend writing one attribute per line, sorting them alphabetically (most editors can do it for you), and [always using a trailing comma][trailing_commas].

data/lib/oj_serializers/serializer.rb

@@ -43,7 +43,7 @@ class OjSerializers::Serializer
     def _check_instance_variables
       if instance_values.keys.any? { |key| !ALLOWED_INSTANCE_VARIABLES.include?(key) }
         bad_keys = instance_values.keys.reject { |key| ALLOWED_INSTANCE_VARIABLES.include?(key) }
-        raise ArgumentError, "Serializer instances are reused so they must be stateless. Use `memo.fetch` for memoization purposes instead. Bad keys: #{bad_keys.join(',')}"
+        raise ArgumentError, "Serializer instances are reused so they must be stateless. Use `memo.fetch` for memoization purposes instead. Bad keys: #{bad_keys.join(',')} in #{self.class}"
       end
     end
   end
@@ -86,7 +86,8 @@ protected
     # Public: Allows the user to specify `default_format :json`, as a simple
     # way to ensure that `.one` and `.many` work as in Version 1.
     def default_format(value)
-      define_serialization_shortcuts(value)
+      @_default_format = value
+      define_serialization_shortcuts
     end
 
     # Public: Allows to sort fields by name instead.
@@ -125,6 +126,14 @@ protected
     # reuse the same serializer instance to serialize different objects.
     delegate :write_one, :write_many, :write_to_json, to: :instance
 
+    # Internal: Keep a reference to the default `write_one` method so that we
+    # can use it inside cached overrides and benchmark tests.
+    alias_method :non_cached_write_one, :write_one
+
+    # Internal: Keep a reference to the default `write_many` method so that we
+    # can use it inside cached overrides and benchmark tests.
+    alias_method :non_cached_write_many, :write_many
+
     # Helper: Serializes one or more items.
     def render(item, options = nil)
       many?(item) ? many(item, options) : one(item, options)
@@ -190,7 +199,7 @@ protected
     # Internal: Will alias the object according to the name of the wrapper class.
     def inherited(subclass)
       object_alias = subclass.name.demodulize.chomp('Serializer').underscore
-      subclass.object_as(object_alias) unless method_defined?(object_alias)
+      subclass.object_as(object_alias) unless method_defined?(object_alias) || object_alias == 'base'
       super
     end
 
@@ -203,7 +212,88 @@ protected
 
   protected
 
-    def define_serialization_shortcuts(format)
+    # Internal: Calculates the cache_key used to cache one serialized item.
+    def item_cache_key(item, cache_key_proc)
+      ActiveSupport::Cache.expand_cache_key(cache_key_proc.call(item))
+    end
+
+    # Public: Allows to define a cache key strategy for the serializer.
+    # Defaults to calling cache_key in the object if no key is provided.
+    #
+    # NOTE: Benchmark it, sometimes caching is actually SLOWER.
+    def cached(cache_key_proc = :cache_key.to_proc)
+      cache_options = { namespace: "#{name}#write_to_json", version: OjSerializers::VERSION }.freeze
+      cache_hash_options = { namespace: "#{name}#render_as_hash", version: OjSerializers::VERSION }.freeze
+
+      # Internal: Redefine `one_as_hash` to use the cache for the serialized hash.
+      define_singleton_method(:one_as_hash) do |item, options = nil|
+        CACHE.fetch(item_cache_key(item, cache_key_proc), cache_hash_options) do
+          instance.render_as_hash(item, options)
+        end
+      end
+
+      # Internal: Redefine `many_as_hash` to use the cache for the serialized hash.
+      define_singleton_method(:many_as_hash) do |items, options = nil|
+        # We define a one-off method for the class to receive the entire object
+        # inside the `fetch_multi` block. Otherwise we would only get the cache
+        # key, and we would need to build a Hash to retrieve the object.
+        #
+        # NOTE: The assignment is important, as queries would return different
+        # objects when expanding with the splat in fetch_multi.
+        items = items.entries.each do |item|
+          item_key = item_cache_key(item, cache_key_proc)
+          item.define_singleton_method(:cache_key) { item_key }
+        end
+
+        # Fetch all items at once by leveraging `read_multi`.
+        #
+        # NOTE: Memcached does not support `write_multi`, if we switch the cache
+        # store to use Redis performance would improve a lot for this case.
+        CACHE.fetch_multi(*items, cache_hash_options) do |item|
+          instance.render_as_hash(item, options)
+        end.values
+      end
+
+      # Internal: Redefine `write_one` to use the cache for the serialized JSON.
+      define_singleton_method(:write_one) do |external_writer, item, options = nil|
+        cached_item = CACHE.fetch(item_cache_key(item, cache_key_proc), cache_options) do
+          writer = new_json_writer
+          non_cached_write_one(writer, item, options)
+          writer.to_json
+        end
+        external_writer.push_json("#{cached_item}\n") # Oj.dump expects a new line terminator.
+      end
+
+      # Internal: Redefine `write_many` to use fetch_multi from cache.
+      define_singleton_method(:write_many) do |external_writer, items, options = nil|
+        # We define a one-off method for the class to receive the entire object
+        # inside the `fetch_multi` block. Otherwise we would only get the cache
+        # key, and we would need to build a Hash to retrieve the object.
+        #
+        # NOTE: The assignment is important, as queries would return different
+        # objects when expanding with the splat in fetch_multi.
+        items = items.entries.each do |item|
+          item_key = item_cache_key(item, cache_key_proc)
+          item.define_singleton_method(:cache_key) { item_key }
+        end
+
+        # Fetch all items at once by leveraging `read_multi`.
+        #
+        # NOTE: Memcached does not support `write_multi`, if we switch the cache
+        # store to use Redis performance would improve a lot for this case.
+        cached_items = CACHE.fetch_multi(*items, cache_options) do |item|
+          writer = new_json_writer
+          non_cached_write_one(writer, item, options)
+          writer.to_json
+        end.values
+        external_writer.push_json("#{OjSerializers::JsonValue.array(cached_items)}\n") # Oj.dump expects a new line terminator.
+      end
+
+      define_serialization_shortcuts
+    end
+    alias_method :cached_with_key, :cached
+
+    def define_serialization_shortcuts(format = _default_format)
       case format
       when :json, :hash
         singleton_class.alias_method :one, :"one_as_#{format}"
@@ -219,20 +309,27 @@ protected
     end
 
     # Public: Identifiers are always serialized first.
+    #
+    # NOTE: We skip the id for non-persisted documents, since it doesn't
+    # actually identify the document (it will change once it's persisted).
     def identifier(name = :id, **options)
-      add_attribute(name, **options, attribute: :method, identifier: true, if: -> { !@object.new_record? })
+      add_attribute(name, attribute: :method, if: -> { !@object.new_record? }, **options, identifier: true)
     end
 
     # Public: Specify a collection of objects that should be serialized using
     # the specified serializer.
-    def has_many(name, serializer:, root: name, as: root, **options)
+    def has_many(name, serializer:, root: name, as: root, **options, &block)
+      define_method(name, &block) if block
       add_attribute(name, association: :many, as: as, serializer: serializer, **options)
     end
 
     # Public: Specify an object that should be serialized using the serializer.
-    def has_one(name, serializer:, root: name, as: root, **options)
+    def has_one(name, serializer:, root: name, as: root, **options, &block)
+      define_method(name, &block) if block
       add_attribute(name, association: :one, as: as, serializer: serializer, **options)
     end
+    # Alias: From a serializer perspective, the association type does not matter.
+    alias_method :belongs_to, :has_one
 
     # Public: Specify an object that should be serialized using the serializer,
     # but unlike `has_one`, this one will write the attributes directly without
@@ -255,47 +352,57 @@ protected
     #
     # See ./benchmarks/document_benchmark.rb
     def mongo_attributes(*method_names, **options)
-      add_attribute('id', **options, attribute: :id, identifier: true) if method_names.delete(:id)
-      add_attributes(method_names, **options, attribute: :mongoid)
+      identifier(:_id, as: :id, attribute: :mongoid, **options) if method_names.delete(:id)
+      attributes(*method_names, **options, attribute: :mongoid)
     end
 
     # Public: Specify which attributes are going to be obtained by calling a
     # method in the object.
-    def attributes(*method_names, **options)
-      add_attributes(method_names, **options, attribute: :method)
+    def attributes(*method_names, **methods_with_options)
+      attr_options = methods_with_options.extract!(:if, :as, :attribute)
+      attr_options[:attribute] ||= :method
+
+      method_names.each do |name|
+        add_attribute(name, attr_options)
+      end
+
+      methods_with_options.each do |name, options|
+        options = { as: options } if options.is_a?(Symbol)
+        add_attribute(name, options)
+      end
     end
-    alias_method :attribute, :attributes
 
     # Public: Specify which attributes are going to be obtained by calling a
     # method in the serializer.
-    #
-    # NOTE: This can be one of the slowest strategies, when in doubt, measure.
     def serializer_attributes(*method_names, **options)
-      add_attributes(method_names, **options, attribute: :serializer)
+      attributes(*method_names, **options, attribute: :serializer)
     end
 
     # Syntax Sugar: Allows to use it before a method name.
     #
     # Example:
-    #   serialize
+    #   attribute
     #   def full_name
     #     "#{ first_name } #{ last_name }"
     #   end
-    def serialize(name = nil, **options)
+    def attribute(name = nil, **options, &block)
+      options[:attribute] = :serializer
       if name
-        serializer_attributes(name, **options)
+        define_method(name, &block) if block
+        add_attribute(name, options)
       else
-        @_current_attribute = options
+        @_current_attribute_options = options
       end
     end
+    alias_method :attr, :attribute
 
     # Internal: Intercept a method definition, tying a type that was
     # previously specified to the name of the attribute.
     def method_added(name)
       super(name)
-      if @_current_attribute
-        serializer_attributes(name, **@_current_attribute)
-        @_current_attribute = nil
+      if @_current_attribute_options
+        add_attribute(name, @_current_attribute_options)
+        @_current_attribute_options = nil
       end
     end
 
@@ -307,7 +414,13 @@ protected
       method_names.each do |method_name|
         define_method(method_name) { @object.read_attribute_for_serialization(method_name) } unless method_defined?(method_name)
       end
-      add_attributes(method_names, **options, attribute: :serializer)
+      attributes(*method_names, **options, attribute: :serializer)
+    end
+
+    # Internal: The default format to use for `render`, `one`, and `many`.
+    def _default_format
+      @_default_format = superclass.try(:_default_format) || :hash unless defined?(@_default_format)
+      @_default_format
     end
 
     # Internal: The strategy to use when sorting the fields.
@@ -328,10 +441,6 @@ protected
 
   private
 
-    def add_attributes(names, options)
-      names.each { |name| add_attribute(name, options) }
-    end
-
     def add_attribute(name, options)
       _attributes[name.to_s.freeze] = options
     end
@@ -420,18 +529,27 @@ protected
       RESCUE_NO_METHOD
     end
 
+    # Internal: Detects any include methods defined in the serializer, or defines
+    # one by using the lambda passed in the `if` option, if any.
+    def check_conditional_method(method_name, options)
+      include_method_name = "include_#{method_name}#{'?' unless method_name.to_s.ends_with?('?')}"
+      if render_if = options[:if]
+        if render_if.is_a?(Symbol)
+          alias_method(include_method_name, render_if)
+        else
+          define_method(include_method_name, &render_if)
+        end
+      end
+      include_method_name if method_defined?(include_method_name)
+    end
+
     # Internal: Returns the code to render an attribute or association
     # conditionally.
     #
     # NOTE: Detects any include methods defined in the serializer, or defines
     # one by using the lambda passed in the `if` option, if any.
     def code_to_write_conditional(method_name, options)
-      include_method_name = "include_#{method_name}#{'?' unless method_name.ends_with?('?')}"
-      if render_if = options[:if]
-        define_method(include_method_name, &render_if)
-      end
-
-      if method_defined?(include_method_name)
+      if (include_method_name = check_conditional_method(method_name, options))
         "if #{include_method_name};#{yield};end\n"
       else
         yield
@@ -455,12 +573,6 @@ protected
       when :mongoid
         # Writes an Mongoid attribute to JSON, this is the fastest strategy.
         "writer.push_value(@object.attributes['#{method_name}'], #{key})"
-      when :id
-        # Writes an _id value to JSON using `id` as the key instead.
-        #
-        # NOTE: We skip the id for non-persisted documents, since it doesn't actually
-        # identify the document (it will change once it's persisted).
-        "writer.push_value(@object.attributes['_id'], 'id') unless @object.new_record?"
       else
         raise ArgumentError, "Unknown attribute strategy: #{strategy.inspect}"
       end
@@ -501,13 +613,7 @@ protected
     # NOTE: Detects any include methods defined in the serializer, or defines
     # one by using the lambda passed in the `if` option, if any.
     def code_to_render_conditionally(method_name, options)
-      include_method_name = "include_#{method_name}#{'?' unless method_name.ends_with?('?')}"
-
-      if render_if = options[:if]
-        define_method(include_method_name, &render_if)
-      end
-
-      if method_defined?(include_method_name)
+      if (include_method_name = check_conditional_method(method_name, options))
         "**(#{include_method_name} ? {#{yield}} : {})"
       else
         yield
@@ -526,8 +632,6 @@ protected
         "#{key}: @object[#{method_name.inspect}]"
       when :mongoid
         "#{key}: @object.attributes['#{method_name}']"
-      when :id
-        "**(@object.new_record? ? {} : {id: @object.attributes['_id']})"
       else
         raise ArgumentError, "Unknown attribute strategy: #{strategy.inspect}"
       end
@@ -585,7 +689,7 @@ protected
     end
   end
 
-  define_serialization_shortcuts(:hash)
+  define_serialization_shortcuts
 end
 
 Oj::Serializer = OjSerializers::Serializer unless defined?(Oj::Serializer)

data/lib/oj_serializers/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module OjSerializers
-  VERSION = '2.0.0-beta.1'
+  VERSION = '2.0.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: oj_serializers
 version: !ruby/object:Gem::Version
-  version: 2.0.0.pre.beta.1
+  version: 2.0.0
 platform: ruby
 authors:
 - Maximo Mussini
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-03-20 00:00:00.000000000 Z
+date: 2023-03-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: oj
@@ -64,9 +64,9 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: 2.7.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">"
+  - - ">="
     - !ruby/object:Gem::Version
-      version: 1.3.1
+      version: '0'
 requirements: []
 rubygems_version: 3.2.32
 signing_key: