oj_serializers 2.0.0.pre.beta.1 → 2.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4ebc24ba352b46585589ae760b579009e18e9de772b1d015eb0fdfa465a39b93
-  data.tar.gz: 475283ebe5897716eb1812a474358ddc3775746e1e0f8ff011204fc3ff76219e
+  metadata.gz: e8fd87262444d89cfbbe11a1b6ae6201de6d71ed996edcd8a4a9ae224320ad7c
+  data.tar.gz: bfe507b6e02c01087d99381ab8ef971547e0062085eb4bfb9c9551ceb2796c18
 SHA512:
-  metadata.gz: e4a0c4e060fbac9cc04ef2e6ce31406fa5aa83052989a272e2bba6c1b7c30767e82bd22aa51b016716adfff8bb039442a7725f25ddf7093ca4b33de646360181
-  data.tar.gz: d0d41a7a283e26831222a99b96669498eb01b14dac383da008db053c769052ca0e91b1078f1c0d9c797faadd082b3ecaeabce37fa267d617bc2bc039a05dcaec
+  metadata.gz: 060b791a7d8c2f204adab9313873b950b89eb1a80400b26355b1382ab6e08d0efa3e48efeef1ececc96cb8f42729f8f4cea50b37d579ab1acc333b393b060c0d
+  data.tar.gz: a7ea8370d3155f8bfd99f9d1cffe67fe05f896930277a0e69a81b3e4eda2b0088a8901730ec2fb910e564dcf3f29ea3200f5cc70d8321dd1892b72c9f9b75bf4

data/CHANGELOG.md

@@ -1,3 +1,31 @@
+## Oj Serializers 2.0.1 (2023-04-02)
+
+### Features ✨
+
+- [Automatically mark `id` as an identifier (rendered first)](https://github.com/ElMassimo/oj_serializers/commit/c4c6de7)
+- [Fail on typos in attribute and association options](https://github.com/ElMassimo/oj_serializers/commit/afd80ac)
+
+### Fixes 🐞
+
+- [Aliased attributes should be sorted by the output key](https://github.com/ElMassimo/oj_serializers/commit/fc6f4c1)
+
+## [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

@@ -2,11 +2,10 @@
 Oj Serializers
 <p align="center">
 <a href="https://github.com/ElMassimo/oj_serializers/actions"><img alt="Build Status" src="https://github.com/ElMassimo/oj_serializers/workflows/build/badge.svg"/></a>
-<a href="https://inch-ci.org/github/ElMassimo/oj_serializers"><img alt="Inline docs" src="https://inch-ci.org/github/ElMassimo/oj_serializers.svg"/></a>
 <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 +18,17 @@ 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
+[TypeScript]: https://www.typescriptlang.org/
+[types_from_serializers]: https://github.com/ElMassimo/types_from_serializers
 
 ## Why? 🤔
 
@@ -39,11 +41,12 @@ 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
+- [Generate TypeScript interfaces automatically][types_from_serializers]
 
 ## Installation 💿
 
@@ -66,8 +69,7 @@ attributes should be serialized.
 class AlbumSerializer < Oj::Serializer
   attributes :name, :genres
 
-  serialize
-  def release
+  attribute :release do
     album.release_date.strftime('%B %d, %Y')
   end
 
@@ -139,48 +141,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 +166,222 @@ 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`.
-
-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
+  # or
 
-  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
+
+  attributes title: {as: :name}
 
-  # You can also compose serializers using `flat_one`.
-  flat_one :song, serializer: SongMetadataSerializer
+  # 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
+
+  # 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
 
-  attribute :title, as: :name
+  # shortcut for
+  transform_keys -> (key) { key.to_s.camelize(:lower) }
 end
 ```
 
-### Rendering an attribute conditionally
+This has no performance impact, as keys will be transformed at load time.
 
-All the attributes and association methods can take an `if` option to render conditionally.
+### 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 AlbumSerializer < Oj::Serializer
-  mongo_attributes :release_date, if: -> { album.released? }
+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 🛣
 
-  has_many :songs, serializer: SongSerializer, if: -> { 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
 
-  # You can achieve the same by manually defining a method:
-  def include_songs?
-    album.songs.any?
+  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`.
+
+### Generating TypeScript automatically 🤖
+
+It's easy for the backend and the frontend to become out of sync. Traditionally, preventing bugs requires writing extensive integration tests.
+
+[TypeScript] is a great tool to catch this kind of bugs and mistakes, as it can detect incorrect usages and missing fields, but writing types manually is cumbersome, and they can become stale over time, giving a false sense of confidence.
+
+[`types_from_serializers`][types_from_serializers] extends this library to allow embedding type information, as well as inferring types from the SQL schema when available, and uses this information to automatically generate TypeScript interfaces from your serializers.
 
-Serializers are designed to be stateless so that an instanced can be reused, but sometimes it's convenient to store intermediate calculations.
+As a result, it's posible to easily detect mismatches between the backend and the frontend, as well as make the fields more discoverable and provide great autocompletion in the frontend, without having to manually write the types.
+
+### 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.
 
@@ -377,7 +389,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 +404,86 @@ private
 end
 ```
 
-### Writing directly to JSON
+### `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"}
+```
 
-In some corner cases it might be faster to serialize using a `Oj::StringWriter`.
+### `mongo_attributes` 🚀
 
-You can toggle this mode at a serializer level by using `default_format :json`,
-or configure it globally from your base serializer.
+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 +569,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 +581,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 +598,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

@@ -19,7 +19,22 @@ require 'oj_serializers/json_value'
 class OjSerializers::Serializer
   # Public: Used to validate incorrect memoization during development. Users of
   # this library might add additional options as needed.
-  ALLOWED_INSTANCE_VARIABLES = %w[memo object options]
+  ALLOWED_INSTANCE_VARIABLES = %w[
+    memo
+    object
+    options
+    _routes
+  ]
+
+  KNOWN_ATTRIBUTE_OPTIONS = %i[
+    attribute
+    association
+    identifier
+    if
+    optional
+    type
+    serializer
+  ].to_set
 
   CACHE = (defined?(Rails) && Rails.cache) ||
           (defined?(ActiveSupport::Cache::MemoryStore) ? ActiveSupport::Cache::MemoryStore.new : OjSerializers::Memo.new)
@@ -43,7 +58,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
@@ -85,29 +100,40 @@ protected
   class << self
     # 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)
+    #
+    # This setting is inherited from parent classes.
+    def default_format(format)
+      define_singleton_method(:_default_format) { format }
+      define_serialization_shortcuts
     end
 
-    # Public: Allows to sort fields by name instead.
-    def sort_attributes_by(value)
-      @_sort_attributes_by = case value
-      when :name then ->(name, options) { options[:identifier] ? "__#{name}" : name }
-      when Proc then value
+    # Public: Allows to sort fields by name instead of by definition order, or
+    # pass a Proc to apply a custom order.
+    #
+    # This setting is inherited from parent classes.
+    def sort_attributes_by(strategy)
+      case strategy
+      when :name, :definition, Proc
+        define_singleton_method(:_sort_attributes_by) { strategy }
       else
-        raise ArgumentError, "Unknown sorting option: #{value.inspect}"
+        raise ArgumentError, "Unknown sorting option: #{strategy.inspect}"
       end
     end
 
-    # Public: Allows to sort fields by name instead.
-    def transform_keys(transformer = nil, &block)
-      @_transform_keys = case (transformer ||= block)
-      when :camelize, :camel_case then ->(key) { key.to_s.camelize(:lower) }
-      when Symbol then transformer.to_proc
-      when Proc then transformer
+    # Public: Allows to transform the JSON keys to camelCase, or pass a Proc
+    # to apply a custom transformation.
+    #
+    # This setting is inherited from parent classes.
+    def transform_keys(strategy = nil, &block)
+      transformer = case (strategy ||= block)
+      when :camelize, :camel_case then ->(key) { key.camelize(:lower) }
+      when :none then nil
+      when Symbol then strategy.to_proc
+      when Proc then strategy
       else
-        raise(ArgumentError, "Expected transform_keys to be callable, got: #{transformer.inspect}")
+        raise(ArgumentError, "Expected transform_keys to be callable, got: #{strategy.inspect}")
       end
+      define_singleton_method(:_transform_keys) { transformer }
     end
 
     # Public: Creates an alias for the internal object.
@@ -125,6 +151,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 +224,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 +237,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 +334,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)
-      add_attribute(name, association: :many, as: as, serializer: serializer, **options)
+    def has_many(name, serializer:, **options, &block)
+      define_method(name, &block) if block
+      add_attribute(name, association: :many, 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)
-      add_attribute(name, association: :one, as: as, serializer: serializer, **options)
+    def has_one(name, serializer:, **options, &block)
+      define_method(name, &block) if block
+      add_attribute(name, association: :one, 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
@@ -243,9 +365,8 @@ protected
 
     # Public: Specify which attributes are going to be obtained from indexing
     # the object.
-    def hash_attributes(*method_names, **options)
-      options = { **options, attribute: :hash }
-      method_names.each { |name| _attributes[name] = options }
+    def hash_attributes(*attr_names, **options)
+      attributes(*attr_names, **options, attribute: :hash)
     end
 
     # Public: Specify which attributes are going to be obtained from indexing
@@ -254,48 +375,58 @@ protected
     # Automatically renames `_id` to `id` for Mongoid models.
     #
     # 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)
+    def mongo_attributes(*attr_names, **options)
+      identifier(:_id, as: :id, attribute: :mongoid, **options) if attr_names.delete(:id)
+      attributes(*attr_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(*attr_names, **methods_with_options)
+      attr_options = methods_with_options.extract!(:if, :as, :attribute)
+      attr_options[:attribute] ||= :method
+
+      attr_names.each do |attr_name|
+        add_attribute(attr_name, **attr_options)
+      end
+
+      methods_with_options.each do |attr_name, options|
+        options = { as: options } if options.is_a?(Symbol)
+        add_attribute(attr_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)
+    def serializer_attributes(*attr_names, **options)
+      attributes(*attr_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
 
@@ -303,43 +434,34 @@ protected
     # calling a method in the serializer, or using `read_attribute_for_serialization`.
     #
     # NOTE: Prefer to use `attributes` or `serializer_attributes` explicitly.
-    def ams_attributes(*method_names, **options)
-      method_names.each do |method_name|
-        define_method(method_name) { @object.read_attribute_for_serialization(method_name) } unless method_defined?(method_name)
+    def ams_attributes(*attr_names, **options)
+      attr_names.each do |attr_name|
+        define_method(attr_name) { @object.read_attribute_for_serialization(attr_name) } unless method_defined?(attr_name)
       end
-      add_attributes(method_names, **options, attribute: :serializer)
+      attributes(*attr_names, **options, attribute: :serializer)
     end
 
-    # Internal: The strategy to use when sorting the fields.
-    #
-    # This setting is inherited from parent classes.
-    def _sort_attributes_by
-      @_sort_attributes_by = superclass.try(:_sort_attributes_by) unless defined?(@_sort_attributes_by)
-      @_sort_attributes_by
-    end
+  private
 
-    # Internal: The converter to use for serializer keys.
-    #
-    # This setting is inherited from parent classes.
-    def _transform_keys
-      @_transform_keys = superclass.try(:_transform_keys) unless defined?(@_transform_keys)
-      @_transform_keys
-    end
+    def add_attribute(value_from, root: nil, as: nil, **options)
+      # Because it's so common, automatically mark id as an identifier.
+      options[:identifier] = true if value_from == :id && !options.key?(:identifier)
 
-  private
+      # Hash attributes could be numbers or symbols.
+      value_from = value_from.to_s unless options[:attribute] == :hash
 
-    def add_attributes(names, options)
-      names.each { |name| add_attribute(name, options) }
-    end
+      # Obtain the JSON key to use for the attribute.
+      key = (root || as || value_from).to_s
 
-    def add_attribute(name, options)
-      _attributes[name.to_s.freeze] = options
-    end
+      # Should be able to add "duplicate" flat associations.
+      key += _attributes.count.to_s if options[:association] == :flat
 
-    # Internal: Transforms the keys using the provided strategy.
-    def key_for(method_name, options)
-      key = options.fetch(:as, method_name)
-      _transform_keys ? _transform_keys.call(key) : key
+      # Check for typos in options.
+      if DEV_MODE && (option, = options.find { |option, _value| !KNOWN_ATTRIBUTE_OPTIONS.include?(option) })
+        raise ArgumentError, "Unknown option #{option.inspect} for attribute #{value_from.inspect} in #{name}. Please check for typos."
+      end
+
+      _attributes[key.freeze] = { value_from: value_from, **options }.freeze
     end
 
     # Internal: Whether the object should be serialized as a collection.
@@ -355,19 +477,19 @@ protected
     #
     # As a result, the performance is the same as writing the most efficient
     # code by hand.
-    def code_to_write_to_json
+    def code_to_write_to_json(attributes)
       <<~WRITE_TO_JSON
         # Public: Writes this serializer content to a provided Oj::StringWriter.
         def write_to_json(writer, item, options = nil)
           @object = item
           @options = options
           @memo.clear if defined?(@memo)
-          #{ _attributes.map { |method_name, options|
-            code_to_write_conditional(method_name, options) {
+          #{ attributes.map { |key, options|
+            code_to_write_conditionally(options) {
               if options[:association]
-                code_to_write_association(method_name, options)
+                code_to_write_association(key, options)
               else
-                code_to_write_attribute(method_name, options)
+                code_to_write_attribute(key, options)
               end
             }
           }.join("\n  ") }#{code_to_rescue_no_method if DEV_MODE}
@@ -381,7 +503,7 @@ protected
     #
     # As a result, the performance is the same as writing the most efficient
     # code by hand.
-    def code_to_render_as_hash
+    def code_to_render_as_hash(attributes)
       <<~RENDER_AS_HASH
         # Public: Writes this serializer content to a Hash.
         def render_as_hash(item, options = nil)
@@ -389,12 +511,12 @@ protected
           @options = options
           @memo.clear if defined?(@memo)
           {
-            #{_attributes.map { |method_name, options|
-              code_to_render_conditionally(method_name, options) {
+            #{attributes.map { |key, options|
+              code_to_render_conditionally(options) {
                 if options[:association]
-                  code_to_render_association(method_name, options)
+                  code_to_render_association(key, options)
                 else
-                  code_to_render_attribute(method_name, options)
+                  code_to_render_attribute(key, options)
                 end
               }
             }.join(",\n    ")}
@@ -409,7 +531,7 @@ protected
         rescue NoMethodError => e
           key = e.name.to_s.inspect
           message = if respond_to?(e.name)
-            raise e, "Perhaps you meant to call \#{key} in \#{self.class} instead?\nTry using `serializer_attributes :\#{key}` or `attribute def \#{key}`.\n\#{e.message}"
+            raise e, "Perhaps you meant to call \#{key} in \#{self.class} instead?\nTry using `attribute :\#{key} do` or `attribute def \#{key}`.\n\#{e.message}"
           elsif @object.respond_to?(e.name)
             raise e, "Perhaps you meant to call \#{key} in \#{@object.class} instead?\nTry using `attributes :\#{key}`.\n\#{e.message}"
           else
@@ -420,18 +542,28 @@ 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(options)
+      value_from = options.fetch(:value_from)
+      include_method_name = "include_#{value_from}#{'?' unless value_from.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)
+    def code_to_write_conditionally(options)
+      if (include_method_name = check_conditional_method(options))
         "if #{include_method_name};#{yield};end\n"
       else
         yield
@@ -439,56 +571,52 @@ protected
     end
 
     # Internal: Returns the code for the association method.
-    def code_to_write_attribute(method_name, options)
-      key = key_for(method_name, options).to_s.inspect
+    def code_to_write_attribute(key, options)
+      value_from = options.fetch(:value_from)
 
-      case strategy = options.fetch(:attribute)
+      value = case (strategy = options.fetch(:attribute))
       when :serializer
         # Obtains the value by calling a method in the serializer.
-        "writer.push_value(#{method_name}, #{key})"
+        value_from
       when :method
         # Obtains the value by calling a method in the object, and writes it.
-        "writer.push_value(@object.#{method_name}, #{key})"
+        "@object.#{value_from}"
       when :hash
         # Writes a Hash value to JSON, works with String or Symbol keys.
-        "writer.push_value(@object[#{method_name.inspect}], #{key})"
+        "@object[#{value_from.inspect}]"
       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?"
+        "@object.attributes['#{value_from}']"
       else
         raise ArgumentError, "Unknown attribute strategy: #{strategy.inspect}"
       end
+
+      "writer.push_value(#{value}, #{key.inspect})"
     end
 
     # Internal: Returns the code for the association method.
-    def code_to_write_association(method_name, options)
+    def code_to_write_association(key, options)
       # Use a serializer method if defined, else call the association in the object.
-      association_method = method_defined?(method_name) ? method_name : "@object.#{method_name}"
-      key = key_for(method_name, options)
+      value_from = options.fetch(:value_from)
+      value = method_defined?(value_from) ? value_from : "@object.#{value_from}"
       serializer_class = options.fetch(:serializer)
 
       case type = options.fetch(:association)
       when :one
         <<~WRITE_ONE
-          if associated_object = #{association_method}
+          if __value = #{value}
             writer.push_key('#{key}')
-            #{serializer_class}.write_one(writer, associated_object)
+            #{serializer_class}.write_one(writer, __value)
           end
         WRITE_ONE
       when :many
         <<~WRITE_MANY
           writer.push_key('#{key}')
-          #{serializer_class}.write_many(writer, #{association_method})
+          #{serializer_class}.write_many(writer, #{value})
         WRITE_MANY
       when :flat
         <<~WRITE_FLAT
-          #{serializer_class}.write_to_json(writer, #{association_method})
+          #{serializer_class}.write_to_json(writer, #{value})
         WRITE_FLAT
       else
         raise ArgumentError, "Unknown association type: #{type.inspect}"
@@ -500,14 +628,8 @@ 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)
+    def code_to_render_conditionally(options)
+      if (include_method_name = check_conditional_method(options))
         "**(#{include_method_name} ? {#{yield}} : {})"
       else
         yield
@@ -515,38 +637,39 @@ protected
     end
 
     # Internal: Returns the code for the attribute method.
-    def code_to_render_attribute(method_name, options)
-      key = key_for(method_name, options)
-      case strategy = options.fetch(:attribute)
+    def code_to_render_attribute(key, options)
+      value_from = options.fetch(:value_from)
+
+      value = case (strategy = options.fetch(:attribute))
       when :serializer
-        "#{key}: #{method_name}"
+        value_from
       when :method
-        "#{key}: @object.#{method_name}"
+        "@object.#{value_from}"
       when :hash
-        "#{key}: @object[#{method_name.inspect}]"
+        "@object[#{value_from.inspect}]"
       when :mongoid
-        "#{key}: @object.attributes['#{method_name}']"
-      when :id
-        "**(@object.new_record? ? {} : {id: @object.attributes['_id']})"
+        "@object.attributes['#{value_from}']"
       else
         raise ArgumentError, "Unknown attribute strategy: #{strategy.inspect}"
       end
+
+      "#{key}: #{value}"
     end
 
     # Internal: Returns the code for the association method.
-    def code_to_render_association(method_name, options)
+    def code_to_render_association(key, options)
       # Use a serializer method if defined, else call the association in the object.
-      association = method_defined?(method_name) ? method_name : "@object.#{method_name}"
-      key = key_for(method_name, options)
+      value_from = options.fetch(:value_from)
+      value = method_defined?(value_from) ? value_from : "@object.#{value_from}"
       serializer_class = options.fetch(:serializer)
 
       case type = options.fetch(:association)
       when :one
-        "#{key}: (one_item = #{association}) ? #{serializer_class}.one_as_hash(one_item) : nil"
+        "#{key}: (__value = #{value}) ? #{serializer_class}.one_as_hash(__value) : nil"
       when :many
-        "#{key}: #{serializer_class}.many_as_hash(#{association})"
+        "#{key}: #{serializer_class}.many_as_hash(#{value})"
       when :flat
-        "**#{serializer_class}.one_as_hash(#{association})"
+        "**#{serializer_class}.one_as_hash(#{value})"
       else
         raise ArgumentError, "Unknown association type: #{type.inspect}"
       end
@@ -567,25 +690,36 @@ protected
       @instance_key ||= begin
         # We take advantage of the fact that this method will always be called
         # before instantiating a serializer, to apply last minute adjustments.
-        _prepare_serializer
+        prepare_serializer
         "#{name.underscore}_instance_#{object_id}".to_sym
       end
     end
 
     # Internal: Generates write_to_json and render_as_hash methods optimized for
     # the specified configuration.
-    def _prepare_serializer
-      if _sort_attributes_by
-        @_attributes = _attributes.sort_by { |key, options|
-          _sort_attributes_by.call(key, options)
-        }.to_h
+    def prepare_serializer
+      attributes = prepare_attributes
+      class_eval(code_to_write_to_json(attributes))
+      class_eval(code_to_render_as_hash(attributes))
+    end
+
+    # Internal: Returns attributes sorted and with keys transformed using
+    # the specified strategies.
+    def prepare_attributes(transform_keys: try(:_transform_keys), sort_by: try(:_sort_attributes_by))
+      attributes = _attributes
+      attributes = attributes.transform_keys(&transform_keys) if transform_keys
+
+      if sort_by == :name
+        sort_by = ->(name, options, _) { options[:identifier] ? "__#{name}" : name }
+      elsif !sort_by || sort_by == :definition
+        sort_by = ->(name, options, index) { options[:identifier] ? "__#{name}" : "zzz#{index}" }
       end
-      class_eval(code_to_write_to_json)
-      class_eval(code_to_render_as_hash)
+
+      attributes.sort_by.with_index { |(name, options), index| sort_by.call(name, options, index) }.to_h
     end
   end
 
-  define_serialization_shortcuts(:hash)
+  default_format :hash
 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.1'
 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.1
 platform: ruby
 authors:
 - Maximo Mussini
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-03-20 00:00:00.000000000 Z
+date: 2023-04-02 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: