oj_serializers 1.0.2 → 2.0.0

data/README.md

@@ -6,29 +6,33 @@ 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>
 
-JSON serializers for Ruby, built on top of the powerful [`oj`][oj] library.
+Faster JSON serializers for Ruby, built on top of the powerful [`oj`][oj] library.
 
 [oj]: https://github.com/ohler55/oj
 [mongoid]: https://github.com/mongodb/mongoid
 [ams]: https://github.com/rails-api/active_model_serializers
 [jsonapi]: https://github.com/jsonapi-serializer/jsonapi-serializer
 [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? 🤔
 
-[`ActiveModel::Serializer`][ams] has a nice DSL, but it allocates many objects leading
-to memory bloat, time spent on GC, and lower performance.
+[`ActiveModel::Serializer`][ams] has a nice DSL, but it allocates many objects
+leading to memory bloat, time spent on GC, and lower performance.
 
 `Oj::Serializer` provides a similar API, with [better performance][benchmarks].
 
@@ -36,12 +40,11 @@ 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
-- Caching
 
 ## Installation 💿
 
@@ -58,13 +61,13 @@ And then run:
 ## Usage 🚀
 
 You can define a serializer by subclassing `Oj::Serializer`, and specify which
-attributes should be serialized to JSON.
+attributes should be serialized.
 
 ```ruby
 class AlbumSerializer < Oj::Serializer
   attributes :name, :genres
 
-  attribute \
+  attr
   def release
     album.release_date.strftime('%B %d, %Y')
   end
@@ -76,129 +79,84 @@ end
 <details>
   <summary>Example Output</summary>
 
-```json
+```ruby
 {
-  "name": "Abraxas",
-  "genres": [
+  name: "Abraxas",
+  genres: [
     "Pyschodelic Rock",
     "Blues Rock",
     "Jazz Fusion",
-    "Latin Rock"
+    "Latin Rock",
   ],
-  "release": "September 23, 1970",
-  "songs": [
+  release: "September 23, 1970",
+  songs: [
     {
-      "track": 1,
-      "name": "Sing Winds, Crying Beasts",
-      "composers": [
-        "Michael Carabello"
-      ]
+      track: 1,
+      name: "Sing Winds, Crying Beasts",
+      composers: ["Michael Carabello"],
     },
     {
-      "track": 2,
-      "name": "Black Magic Woman / Gypsy Queen",
-      "composers": [
-        "Peter Green",
-        "Gábor Szabó"
-      ]
+      track: 2,
+      name: "Black Magic Woman / Gypsy Queen",
+      composers: ["Peter Green", "Gábor Szabó"],
     },
     {
-      "track": 3,
-      "name": "Oye como va",
-      "composers": [
-        "Tito Puente"
-      ]
+      track: 3,
+      name: "Oye como va",
+      composers: ["Tito Puente"],
     },
     {
-      "track": 4,
-      "name": "Incident at Neshabur",
-      "composers": [
-        "Alberto Gianquinto",
-        "Carlos Santana"
-      ]
+      track: 4,
+      name: "Incident at Neshabur",
+      composers: ["Alberto Gianquinto", "Carlos Santana"],
     },
     {
-      "track": 5,
-      "name": "Se acabó",
-      "composers": [
-        "José Areas"
-      ]
+      track: 5,
+      name: "Se acabó",
+      composers: ["José Areas"],
     },
     {
-      "track": 6,
-      "name": "Mother's Daughter",
-      "composers": [
-        "Gregg Rolie"
-      ]
+      track: 6,
+      name: "Mother's Daughter",
+      composers: ["Gregg Rolie"],
     },
     {
-      "track": 7,
-      "name": "Samba pa ti",
-      "composers": [
-        "Santana"
-      ]
+      track: 7,
+      name: "Samba pa ti",
+      composers: ["Santana"],
     },
     {
-      "track": 8,
-      "name": "Hope You're Feeling Better",
-      "composers": [
-        "Rolie"
-      ]
+      track: 8,
+      name: "Hope You're Feeling Better",
+      composers: ["Rolie"],
     },
     {
-      "track": 9,
-      "name": "El Nicoya",
-      "composers": [
-        "Areas"
-      ]
-    }
-  ]
+      track: 9,
+      name: "El Nicoya",
+      composers: ["Areas"],
+    },
+  ],
 }
 ```
 </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`.
-
-## Render DSL 🛠
+## Rendering 🖨
 
-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: {
@@ -207,173 +165,212 @@ render json: {
 }
 ```
 
-You can use these serializers inside arrays, hashes, or even inside `ActiveModel::Serializer` by using a method in the serializer.
-
-Follow [this discussion][raw_json] to find out more about [the `raw_json` extensions][raw_json] that made this high level of interoperability possible.
-
-## 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.
-
-
-You may call [`serializer_attributes`](https://github.com/ElMassimo/oj_serializers/blob/master/spec/support/serializers/song_serializer.rb#L13-L15) or use the `attribute` inline syntax:
+You can serialize custom values by specifying that a method is an `attribute`:
 
 ```ruby
 class PlayerSerializer < Oj::Serializer
-  attribute \
-  def full_name
+  attribute :name do
     "#{player.first_name} #{player.last_name}"
   end
-end
-```
-
-Instance methods can access the object by the serializer name without the
-`Serializer` suffix, `player` in the example above, or directly as `@object`.
-
-You can customize this by using [`object_as`](https://github.com/ElMassimo/oj_serializers#using-a-different-alias-for-the-internal-object).
 
-### `ams_attributes` 🐌
+  # or
 
-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 more concise and achieves better performance, so prefer to use it instead of manually definining attributes:
+### Conditional attributes ❔
+
+You can render attributes and associations conditionally by using `:if`.
 
 ```ruby
-class SongSerializer < SongMetadataSerializer
-  attribute \
-  def album
-    AlbumSerializer.one(song.album)
-  end
+class PlayerSerializer < Oj::Serializer
+  attributes :first_name, :last_name, if: -> { player.display_name? }
 
-  attribute \
-  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`.
+  attribute
   def latest_albums
     artist.albums.desc(:year)
   end
 end
 ```
 
-### Rendering an attribute conditionally
+### Identifier attributes
 
-All the attributes and association methods can take an `if` option to render conditionally.
+The `identifier` method allows you to only include an identifier if the record
+or document has been persisted.
 
 ```ruby
 class AlbumSerializer < Oj::Serializer
-  mongo_attributes :release_date, if: -> { album.released? }
+  identifier
+
+  # or if it's a different field
+  identifier :uuid
+end
+```
+
+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.
+
+Use `transform_keys` to handle that conversion.
+
+```ruby
+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 📶
 
-  has_many :songs, serializer: SongSerializer, if: -> { album.songs.any? }
+By default attributes are rendered in the order they are defined.
 
-  # You can achieve the same by manually defining a method:
-  def include_songs?
-    album.songs.any?
+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.
+
+### Path helpers 🛣
+
+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`.
 
-Serializers are designed to be stateless so that an instanced can be reused, but sometimes it's convenient to store intermediate calculations.
+### 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.
 
 Use `memo` for memoization and storing temporary information.
 
@@ -381,7 +378,7 @@ Use `memo` for memoization and storing temporary information.
 class DownloadSerializer < Oj::Serializer
   attributes :filename, :size
 
-  attribute \
+  attribute
   def progress
     "#{ last_event&.progress || 0 }%"
   end
@@ -396,9 +393,50 @@ private
 end
 ```
 
+### `hash_attributes` 🚀
+
+Very convenient when serializing Hash-like structures, this strategy uses the `[]` operator.
+
+```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 📦
 
-Use `cached` to leverage key-based caching, which calls `cache_key` in the object. You can also provide a lambda to `cached_with_key` to define a custom key:
+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
@@ -408,33 +446,164 @@ class CachedUserSerializer < UserSerializer
 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`.
+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
+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.
+
+> **Note**
+>
+> This was the default behavior in `oj_serializers` v1, but was replaced with
+`default_format :hash` in v2.
+
+<details>
+  <summary>Example Output</summary>
+
+```json
+{
+  "name": "Abraxas",
+  "genres": [
+    "Pyschodelic Rock",
+    "Blues Rock",
+    "Jazz Fusion",
+    "Latin Rock"
+  ],
+  "release": "September 23, 1970",
+  "songs": [
+    {
+      "track": 1,
+      "name": "Sing Winds, Crying Beasts",
+      "composers": [
+        "Michael Carabello"
+      ]
+    },
+    {
+      "track": 2,
+      "name": "Black Magic Woman / Gypsy Queen",
+      "composers": [
+        "Peter Green",
+        "Gábor Szabó"
+      ]
+    },
+    {
+      "track": 3,
+      "name": "Oye como va",
+      "composers": [
+        "Tito Puente"
+      ]
+    },
+    {
+      "track": 4,
+      "name": "Incident at Neshabur",
+      "composers": [
+        "Alberto Gianquinto",
+        "Carlos Santana"
+      ]
+    },
+    {
+      "track": 5,
+      "name": "Se acabó",
+      "composers": [
+        "José Areas"
+      ]
+    },
+    {
+      "track": 6,
+      "name": "Mother's Daughter",
+      "composers": [
+        "Gregg Rolie"
+      ]
+    },
+    {
+      "track": 7,
+      "name": "Samba pa ti",
+      "composers": [
+        "Santana"
+      ]
+    },
+    {
+      "track": 8,
+      "name": "Hope You're Feeling Better",
+      "composers": [
+        "Rolie"
+      ]
+    },
+    {
+      "track": 9,
+      "name": "El Nicoya",
+      "composers": [
+        "Areas"
+      ]
+    }
+  ]
+}
+```
+</details>
 
-Usually serialization happens so fast that __turning caching on can be slower__. Always benchmark to make sure it's worth it, and use caching only for time-consuming or deeply nested structures.
+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
-JSON, this implementation uses `Oj::StringWriter` to write JSON directly,
+JSON, this implementation can use `Oj::StringWriter` to write JSON directly,
 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.
 
-Other libraries such as [`jsonapi-serializer`][jsonapi] evaluate serializers in the context of
-a `class` instead of an `instance` of a class. Although it is efficient in terms
-of memory usage, the downside is that you can't use instance methods or local
-memoization, and any mixins must be applied to the class itself.
+Other libraries such as [`blueprinter`][blueprinter] [`jsonapi-serializer`][jsonapi]
+evaluate serializers in the context of a `class` instead of an `instance` of a class.
+The downside is that you can't use instance methods or local memoization, and any
+mixins must be applied to the class itself.
 
 [`panko-serializer`][panko] also uses `Oj::StringWriter`, but it has the big downside of having to own the entire render tree. Putting a serializer inside a Hash or an Active Model Serializer and serializing that to JSON doesn't work, making a gradual migration harder to achieve. Also, it's optimized for Active Record but I needed good Mongoid support.
 
 `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.
 
-As a result, migrating from `active_model_serializers` is relatively straightforward because instance methods, inheritance, and mixins work as usual.
+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 📏