oj_serializers 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 807a53bcbe017c0279d9be8f654044a0c8834d289dd2e34646121833923ab4c1
+  data.tar.gz: b5f77a958e54273c9729e42a8d9270d4859f1c3aaa338efcbdff0357b3bdc8a5
+SHA512:
+  metadata.gz: 0753030fff469265ce72aecab4b8f7289d626bc15355f847dd0c57dccda3c3abbaa269e4154017bf12c9e1e3f0335df02bf62e31faf105f4cd2bd2a40c34b4ea
+  data.tar.gz: ad791006f8d82f9a1bba0ce8179d414372d2581fd2181920e9362fdad77b0e707f271a8c9a259e115deedcea9a576dca434b2332aef060502b8b530c69f25c3d

data/CHANGELOG.md

@@ -0,0 +1,3 @@
+## Oj Serializers 1.0.0 (2020-11-05) ##
+
+*   Initial Release.

data/README.md

@@ -0,0 +1,465 @@
+<h1 align="center">
+Oj Serializers
+<p align="center">
+<!-- <a href="https://travis-ci.org/ElMassimo/oj_serializers"><img alt="Build Status" src="https://travis-ci.org/ElMassimo/oj_serializers.svg"/></a>
+<a href="http://inch-ci.org/github/ElMassimo/oj_serializers"><img alt="Inline docs" src="http://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>
+</p>
+</h1>
+
+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
+[benchmarks]: https://github.com/ElMassimo/oj_serializers/tree/master/benchmarks
+[raw_benchmarks]: https://github.com/ElMassimo/oj_serializers/blob/master/benchmarks/document_benchmark.rb
+[migration guide]: https://github.com/ElMassimo/oj_serializers/blob/master/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/
+
+## Why? 🤔
+
+[`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].
+
+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]
+- 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 💿
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'oj_serializers'
+```
+
+And then run:
+
+    $ bundle install
+
+## Usage 🚀
+
+You can define a serializer by subclassing `Oj::Serializer`, and specify which
+attributes should be serialized to JSON.
+
+```ruby
+class AlbumSerializer < Oj::Serializer
+  attributes :name, :genres
+
+  attribute \
+  def release
+    album.release_date.strftime('%B %d, %Y')
+  end
+
+  has_many :songs, serializer: SongSerializer
+end
+```
+
+<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>
+
+<br/>
+
+To use the serializer, the recommended approach is:
+
+```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`:
+
+```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 🛠
+
+In order to efficiently reuse the instances, serializers can't be instantiated directly. Use `one` and `many` to serialize objects or enumerables:
+
+```ruby
+render json: {
+  favorite_album: AlbumSerializer.one(album),
+  purchased_albums: AlbumSerializer.many(albums),
+}
+```
+
+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 🛠
+
+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.
+
+The internal design is simple and extensible, so creating new strategies requires very little code.
+Please open an issue if you need help 😃
+
+### `attributes`
+
+Obtains the attribute value by calling a method in the object being serialized.
+
+```ruby
+class PlayerSerializer < Oj::Serializer
+  attributes :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:
+
+```ruby
+class PlayerSerializer < Oj::Serializer
+  attribute \
+  def full_name
+    "#{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` 🐌
+
+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')
+  end
+end
+```
+
+Should only be used when migrating from Active Model Serializers, as it's slower and can create confusion.
+
+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.
+
+### `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
+```
+
+## Associations DSL 🛠
+
+Use `has_one` to serialize individual objects, and `has_many` to serialize a collection.
+
+The value for the association is obtained from a serializer method if defined, or by calling the method in the object being serialized.
+
+You must specificy which serializer to use with the `serializer` option.
+
+```ruby
+class SongSerializer < Oj::Serializer
+  has_one :album, serializer: AlbumSerializer
+  has_many :composers, serializer: ComposerSerializer
+
+  # You can also compose serializers using `flat_one`.
+  flat_one :song, serializer: SongMetadataSerializer
+end
+```
+
+The associations DSL is more concise and achieves better performance, so prefer to use it instead of manually definining attributes:
+
+```ruby
+class SongSerializer < SongMetadataSerializer
+  attribute \
+  def album
+    AlbumSerializer.one(song.album)
+  end
+
+  attribute \
+  def composers
+    ComposerSerializer.many(song.composers)
+  end
+end
+```
+
+## Other DSL 🛠
+
+### 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:
+
+```ruby
+class DiscographySerializer < Oj::Serializer
+  object_as :artist
+
+  # Now we can use `artist` instead of `object` or `discography`.
+  def latest_albums
+    artist.albums.desc(:year)
+  end
+end
+```
+
+### Rendering an attribute conditionally
+
+All the attributes and association methods can take an `if` option to render conditionally.
+
+```ruby
+class AlbumSerializer < Oj::Serializer
+  mongo_attributes :release_date, if: -> { album.released? }
+
+  has_many :songs, serializer: SongSerializer, if: -> { album.songs.any? }
+
+  # You can achieve the same by manually defining a method:
+  def include_songs?
+    album.songs.any?
+  end
+end
+```
+
+### 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.
+
+```ruby
+class DownloadSerializer < Oj::Serializer
+  attributes :filename, :size
+
+  attribute \
+  def progress
+    "#{ last_event&.progress || 0 }%"
+  end
+
+private
+
+  def last_event
+    memo.fetch(:last_event) {
+      download.events.desc(:created_at).first
+    }
+  end
+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:
+
+```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`.
+
+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.
+
+## Design 📐
+
+Unlike `ActiveModel::Serializer`, which builds a Hash that then gets encoded to
+JSON, this implementation uses `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.
+
+### 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.
+
+[`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.
+
+## 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].
+
+```ruby
+class AlbumSerializer < Oj::Serializer
+  attributes(
+    :genres,
+    :name,
+    :release_date,
+  )
+end
+```
+
+It will make things clearer, minimize the amount of git conflicts, and keep the history a lot cleaner and more meaningful when using `git blame`.
+
+## Special Thanks 🙏
+
+This library wouldn't be possible without the wonderful and performant [`oj`](https://github.com/ohler55/oj) library. Thanks [Peter](https://github.com/ohler55)! 😃
+
+Also, thanks to the libraries that inspired this one:
+
+- [`active_model_serializers`][ams]: For the DSL
+- [`panko-serializer`][panko]: For validating that using `Oj::StringWriter` was indeed fast
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/oj_serializers.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require 'oj'
+require 'oj_serializers/version'
+require 'oj_serializers/setup'
+require 'oj_serializers/serializer'

data/lib/oj_serializers/compat.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require 'active_model_serializers'
+
+# Extensions: To ensure JsonStringEncoder can process ActiveModel::Serializer
+# as well.
+class ActiveModel::Serializer
+  # JsonStringEncoder: Used internally to write a single object to JSON.
+  def self.write_one(writer, object, options)
+    writer.push_value(new(object, options))
+  end
+
+  # JsonStringEncoder: Used internally to write an array of objects to JSON.
+  def self.write_many(writer, array, options)
+    writer.push_array
+    array.each do |object|
+      write_one(writer, object, options)
+    end
+    writer.pop
+  end
+
+  # JsonStringEncoder: Used internally to instantiate an Oj::StringWriter.
+  def self.new_json_writer
+    OjSerializers::Serializer.send(:new_json_writer)
+  end
+end
+
+require 'oj_serializers'
+require 'oj_serializers/sugar'

data/lib/oj_serializers/controller_serialization.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require 'oj_serializers/json_string_encoder'
+
+# Internal: Allows to pass Oj serializers as options in `render`.
+module OjSerializers::ControllerSerialization
+  extend ActiveSupport::Concern
+  include ActionController::Renderers
+
+  # Internal: Allows to use Oj::Serializer as `serializer` and `each_serializer`
+  # as with ActiveModelSerializers.
+  #
+  #   render json: items, each_serializer: ItemSerializer
+  #   render json: item, serializer: ItemSerializer
+  #
+  # NOTE: In practice, it should be preferable to simply do:
+  #
+  #   render json: ItemSerializer.many(items)
+  #   render json: ItemSerializer.one(item)
+  #
+  # which is more performant.
+  %i[_render_option_json _render_with_renderer_json].each do |renderer_method|
+    define_method renderer_method do |resource, **options|
+      serializer_class = options[:serializer] || options[:each_serializer]
+      if serializer_class && serializer_class < OjSerializers::Serializer
+        super(OjSerializers::JsonStringEncoder.encode_to_json(resource, options), options.except(:root, :serializer, :each_serializer))
+      else
+        super(resource, **options)
+      end
+    end
+  end
+end

data/lib/oj_serializers/json_string_encoder.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+# Public: Contains utility functions to render objects to JSON.
+#
+# Useful to instantiate a single `JsonWriter` when rendering new serializers.
+module OjSerializers::JsonStringEncoder
+  class << self
+    # Public: Allows to use Oj::Serializer in `serializer` and `each_serializer`
+    # as with ActiveModelSerializers.
+    #   render json: items, each_serializer: ItemSerializer
+    #   render json: item, serializer: ItemSerializer
+    #
+    # Returns a JSON string.
+    #
+    # NOTE: Unlike the default encoder, this one will use the `root` option
+    # regardless of whether a serializer is specified or not.
+    def encode_to_json(object, root: nil, serializer: nil, each_serializer: nil, **extras)
+      # NOTE: Serializers may override `new_json_writer` to modify the behavior.
+      writer = (serializer || each_serializer || OjSerializers::Serializer).send(:new_json_writer)
+
+      if root
+        writer.push_object
+        writer.push_key(root.to_s)
+      end
+
+      if serializer
+        serializer.write_one(writer, object, extras)
+      elsif each_serializer
+        each_serializer.write_many(writer, object, extras)
+      elsif object.is_a?(String)
+        return object unless root
+
+        writer.push_json(object)
+      else
+        writer.push_value(object)
+      end
+
+      writer.pop if root
+
+      writer.to_json
+    end
+
+    # Allows to detect misusage of the options during development.
+    if OjSerializers::Serializer::DEV_MODE
+      alias actual_encode_to_json encode_to_json
+      def encode_to_json(object, root: nil, serializer: nil, each_serializer: nil, **extras)
+        if serializer && serializer < OjSerializers::Serializer
+          raise ArgumentError, 'You must use `each_serializer` when serializing collections' if object.respond_to?(:each)
+        end
+        if each_serializer && each_serializer < OjSerializers::Serializer
+          raise ArgumentError, 'You must use `serializer` when serializing a single object' unless object.respond_to?(:each)
+        end
+        actual_encode_to_json(object, root: root, serializer: serializer, each_serializer: each_serializer, **extras)
+      end
+    end
+  end
+end

data/lib/oj_serializers/json_value.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+# Public: Allows to prevent double encoding an existing JSON string.
+#
+# NOTE: Oj's raw_json option means there's no performance overhead, as it would
+# occur with the previous alternative of parsing the JSON string.
+class OjSerializers::JsonValue
+  # Helper: Expects an Array of JSON-encoded strings and wraps them in a JSON array.
+  def self.array(json_rows)
+    new("[#{json_rows.join(',')}]")
+  end
+
+  def initialize(json)
+    @json = json
+  end
+
+  # Public: Return the internal json when using string interpolation.
+  def to_s
+    @json
+  end
+
+  # Internal: Used by Oj::Rails::Encoder because we use the `raw_json` option.
+  def raw_json(*)
+    @json
+  end
+
+  # Internal: Used by Oj::Rails::Encoder when found inside a Hash or Array.
+  def as_json(_options = nil)
+    self
+  end
+end

data/lib/oj_serializers/memo.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+# Internal: Provides a simple API on top of Hash for memoization purposes.
+class OjSerializers::Memo
+  def initialize
+    @cache = {}
+  end
+
+  def clear
+    @cache.clear
+  end
+
+  def fetch(key)
+    @cache.fetch(key) { @cache[key] = yield }
+  end
+end

data/lib/oj_serializers/serializer.rb

@@ -0,0 +1,465 @@
+# frozen_string_literal: true
+
+require 'active_support/core_ext/module/delegation'
+require 'active_support/core_ext/object/try'
+require 'active_support/core_ext/string/inflections'
+
+require 'oj'
+require 'oj_serializers/memo'
+require 'oj_serializers/json_value'
+
+# Public: Implementation of an "ActiveModelSerializer"-like DSL, but with a
+# design that allows replacing the internal object, which greatly reduces object
+# allocation.
+#
+# Unlike ActiveModelSerializer, which builds a Hash which then gets encoded to
+# JSON, this implementation allows to use Oj::StringWriter to write directly to
+# JSON, greatly reducing the overhead of allocating and garbage collecting the
+# hashes.
+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].freeze
+
+  CACHE = (defined?(Rails) && Rails.cache) ||
+          (defined?(ActiveSupport::Cache::MemoryStore) ? ActiveSupport::Cache::MemoryStore.new : OjSerializers::Memo.new)
+
+  # Internal: The environment the app is currently running on.
+  environment = ENV['RACK_ENV'] || ENV['RAILS_ENV'] || 'production'
+
+  # Internal: Used to display warnings or detect misusage during development.
+  DEV_MODE = %w[test development].include?(environment) && !ENV['BENCHMARK']
+
+  DEFAULT_OPTIONS = {}.freeze
+
+  # Backwards Compatibility: Allows to access options passed through `render json`,
+  # in the same way than ActiveModel::Serializers.
+  def options
+    @object.try(:options) || DEFAULT_OPTIONS
+  end
+
+  # Internal: Used internally to write attributes and associations to JSON.
+  #
+  # NOTE: Binds this instance to the specified object and options and writes
+  # to json using the provided writer.
+  def write_flat(writer, item)
+    @memo.clear if defined?(@memo)
+    @object = item
+    write_to_json(writer)
+  end
+
+  # NOTE: Helps developers to remember to keep serializers stateless.
+  if DEV_MODE
+    prepend(Module.new do
+      def write_flat(writer, item)
+        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(',')}"
+        end
+        super
+      end
+    end)
+  end
+
+  # Internal: Used internally to write a single object to JSON.
+  #
+  # writer - writer used to serialize results
+  # item - item to serialize results for
+  # options - list of external options to pass to the serializer (available as `options`)
+  #
+  # NOTE: Binds this instance to the specified object and options and writes
+  # to json using the provided writer.
+  def write_one(writer, item, options = nil)
+    item.define_singleton_method(:options) { options } if options
+    writer.push_object
+    write_flat(writer, item)
+    writer.pop
+  end
+
+  # Internal: Used internally to write an array of objects to JSON.
+  #
+  # writer - writer used to serialize results
+  # items - items to serialize results for
+  # options - list of external options to pass to the serializer (available as `options`)
+  def write_many(writer, items, options = nil)
+    writer.push_array
+    items.each do |item|
+      write_one(writer, item, options)
+    end
+    writer.pop
+  end
+
+protected
+
+  # Internal: An internal cache that can be used for temporary memoization.
+  def memo
+    defined?(@memo) ? @memo : @memo = OjSerializers::Memo.new
+  end
+
+private
+
+  # Strategy: 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).
+  def write_value_using_id_strategy(writer, _key)
+    writer.push_value(@object.attributes['_id'], 'id') unless @object.new_record?
+  end
+
+  # Strategy: Writes an Mongoid attribute to JSON, this is the fastest strategy.
+  def write_value_using_mongoid_strategy(writer, key)
+    writer.push_value(@object.attributes[key], key)
+  end
+
+  # Strategy: Writes a Hash value to JSON, works with String or Symbol keys.
+  def write_value_using_hash_strategy(writer, key)
+    writer.push_value(@object[key], key.to_s)
+  end
+
+  # Strategy: Obtains the value by calling a method in the object, and writes it.
+  def write_value_using_method_strategy(writer, key)
+    writer.push_value(@object.send(key), key)
+  end
+
+  # Strategy: Obtains the value by calling a method in the serializer.
+  def write_value_using_serializer_strategy(writer, key)
+    writer.push_value(send(key), key)
+  end
+
+  # Override to detect missing attribute errors locally.
+  if DEV_MODE
+    alias original_write_value_using_method_strategy write_value_using_method_strategy
+    def write_value_using_method_strategy(writer, key)
+      original_write_value_using_method_strategy(writer, key)
+    rescue NoMethodError => e
+      raise e, "Perhaps you meant to call #{key.inspect} in #{self.class.name} instead?\nTry using `serializer_attributes :#{key}` or `attribute def #{key}`.\n#{e.message}"
+    end
+
+    alias original_write_value_using_mongoid_strategy write_value_using_mongoid_strategy
+    def write_value_using_mongoid_strategy(writer, key)
+      original_write_value_using_mongoid_strategy(writer, key).tap do
+        # Apply a fake selection when 'only' is not used, so that we allow
+        # read_attribute to fail on typos, renamed, and removed fields.
+        @object.__selected_fields = @object.fields.merge(@object.relations.select { |_key, value| value.embedded? }).transform_values { 1 } unless @object.__selected_fields
+        @object.read_attribute(key) # Raise a missing attribute exception if it's missing.
+      end
+    rescue StandardError => e
+      raise ActiveModel::MissingAttributeError, "#{e.message} in #{self.class} for #{@object.inspect}"
+    end
+  end
+
+  class << self
+    # Internal: We want to discourage instantiating serializers directly, as it
+    # prevents the possibility of reusing an instance.
+    #
+    # NOTE: `one` serves as a replacement for `new` in these serializers.
+    private :new
+
+    # Internal: Delegates to the instance methods, the advantage is that we can
+    # reuse the same serializer instance to serialize different objects.
+    delegate :write_one, :write_many, :write_flat, 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 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 non_cached_write_many write_many
+
+    # Helper: Serializes the item unless it's nil.
+    def one_if(item, options = nil)
+      one(item, options) if item
+    end
+
+    # Public: Serializes the configured attributes for the specified object.
+    #
+    # item - the item to serialize
+    # options - list of external options to pass to the sub class (available in `item.options`)
+    #
+    # Returns an Oj::StringWriter instance, which is encoded as raw json.
+    def one(item, options = nil)
+      writer = new_json_writer
+      write_one(writer, item, options)
+      writer
+    end
+
+    # Public: Serializes an array of items using this serializer.
+    #
+    # items - Must respond to `each`.
+    # options - list of external options to pass to the sub class (available in `item.options`)
+    #
+    # Returns an Oj::StringWriter instance, which is encoded as raw json.
+    def many(items, options = nil)
+      writer = new_json_writer
+      write_many(writer, items, options)
+      writer
+    end
+
+    # Public: Creates an alias for the internal object.
+    def object_as(name)
+      define_method(name) { @object }
+    end
+
+    # 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)
+      super
+    end
+
+    # Internal: List of attributes to be serialized.
+    #
+    # Any attributes defined in parent classes are inherited.
+    def _attributes
+      @_attributes = superclass.try(:_attributes)&.dup || {} unless defined?(@_attributes)
+      @_attributes
+    end
+
+    # Internal: List of associations to be serialized.
+    # Any associations defined in parent classes are inherited.
+    def _associations
+      @_associations = superclass.try(:_associations)&.dup || {} unless defined?(@_associations)
+      @_associations
+    end
+
+    # Internal: Iterating arrays is faster than iterating hashes.
+    attr_reader :_attributes_entries, :_associations_entries
+
+  protected
+
+    # 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
+
+      # 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
+    end
+    alias cached_with_key cached
+
+    # Internal: The writer to use to write to json
+    def new_json_writer
+      Oj::StringWriter.new(mode: :rails)
+    end
+
+    # Public: Specify a collection of objects that should be serialized using
+    # the specified serializer.
+    def has_many(name, root: name, serializer:, **options)
+      add_association(name, write_method: :write_many, root: root, serializer: serializer, **options)
+    end
+
+    # Public: Specify an object that should be serialized using the serializer.
+    def has_one(name, root: name, serializer:, **options)
+      add_association(name, write_method: :write_one, root: root, serializer: serializer, **options)
+    end
+
+    # Public: Specify an object that should be serialized using the serializer,
+    # but unlike `has_one`, this one will write the attributes directly without
+    # wrapping it in an object.
+    def flat_one(name, root: false, serializer:, **options)
+      add_association(name, write_method: :write_flat, root: root, serializer: serializer, **options)
+    end
+
+    # Public: Specify which attributes are going to be obtained from indexing
+    # the object.
+    def hash_attributes(*method_names, **options)
+      options = { **options, strategy: :write_value_using_hash_strategy }
+      method_names.each { |name| _attributes[name] = options }
+    end
+
+    # Public: Specify which attributes are going to be obtained from indexing
+    # a Mongoid model's `attributes` hash directly, for performance.
+    #
+    # Automatically renames `_id` to `id` for Mongoid models.
+    #
+    # See ./benchmarks/document_benchmark.rb
+    def mongo_attributes(*method_names, **options)
+      add_attribute('id', **options, strategy: :write_value_using_id_strategy) if method_names.delete(:id)
+      add_attributes(method_names, **options, strategy: :write_value_using_mongoid_strategy)
+    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, strategy: :write_value_using_method_strategy)
+    end
+
+    # 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, strategy: :write_value_using_serializer_strategy)
+    end
+
+    # Syntax Sugar: Allows to use it before a method name.
+    #
+    # Example:
+    #   attribute \
+    #   def full_name
+    #     "#{ first_name } #{ last_name }"
+    #   end
+    alias attribute serializer_attributes
+
+    # Backwards Compatibility: Meant only to replace Active Model Serializers,
+    # 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)
+      end
+      add_attributes(method_names, **options, strategy: :write_value_using_serializer_strategy)
+    end
+
+  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
+
+    def add_association(name, options)
+      _associations[name.to_s.freeze] = options
+    end
+
+    # Internal: We generate code for the serializer to avoid the overhead of
+    # using variables for method names, having to iterate the list of attributes
+    # and associations, and the overhead of using `send` with dynamic methods.
+    #
+    # As a result, the performance is the same as writing the most efficient
+    # code by hand.
+    def write_to_json_body
+      <<~WRITE_TO_JSON
+        # Public: Writes this serializer content to a provided Oj::StringWriter.
+        def write_to_json(writer)
+          #{ _attributes.map { |method_name, attribute_options|
+            write_conditional_body(method_name, attribute_options) {
+              <<-WRITE_ATTRIBUTE
+                #{attribute_options.fetch(:strategy)}(writer, #{method_name.inspect})
+              WRITE_ATTRIBUTE
+            }
+          }.join }
+          #{ _associations.map { |method_name, association_options|
+            write_conditional_body(method_name, association_options) {
+              write_association_body(method_name, association_options)
+            }
+          }.join}
+        end
+      WRITE_TO_JSON
+    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 write_conditional_body(method_name, options)
+      include_method_name = "include_#{method_name}?"
+      if render_if = options[:if]
+        define_method(include_method_name, &render_if)
+      end
+
+      if method_defined?(include_method_name)
+        "if #{include_method_name};#{yield};end\n"
+      else
+        yield
+      end
+    end
+
+    # Internal: Returns the code for the association method.
+    def write_association_body(method_name, association_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}"
+      association_root = association_options[:root]
+      serializer_class = association_options.fetch(:serializer)
+
+      case write_method = association_options.fetch(:write_method)
+      when :write_one
+        <<-WRITE_ONE
+        if associated_object = #{association_method}
+          writer.push_key(#{association_root.to_s.inspect})
+          #{serializer_class}.write_one(writer, associated_object)
+        end
+        WRITE_ONE
+      when :write_many
+        <<-WRITE_MANY
+        writer.push_key(#{association_root.to_s.inspect})
+        #{serializer_class}.write_many(writer, #{association_method})
+        WRITE_MANY
+      when :write_flat
+        <<-WRITE_FLAT
+        #{serializer_class}.write_flat(writer, #{association_method})
+        WRITE_FLAT
+      else
+        raise ArgumentError, "Unknown write_method #{write_method}"
+      end
+    end
+
+    # Internal: Allows to obtain a pre-existing instance and binds it to the
+    # specified object.
+    #
+    # NOTE: Each class is only instantiated once to reduce object allocation.
+    # For that reason, serializers must be completely stateless (or use global
+    # state).
+    def instance
+      Thread.current[instance_key] ||= new
+    end
+
+    # Internal: Cache key to set a thread-local instance.
+    def instance_key
+      unless defined?(@instance_key)
+        @instance_key = "#{name.underscore}_instance".to_sym
+        # We take advantage of the fact that this method will always be called
+        # before instantiating a serializer to define the write_to_json method.
+        class_eval(write_to_json_body)
+        raise ArgumentError, "You must use `cached ->(object) { ... }` in order to specify a different cache key when subclassing #{name}." if method_defined?(:cache_key) || respond_to?(:cache_key)
+      end
+      @instance_key
+    end
+  end
+end
+
+Oj::Serializer = OjSerializers::Serializer unless defined?(Oj::Serializer)

data/lib/oj_serializers/setup.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require 'oj'
+
+# NOTE: We automatically set the necessary configuration unless it had been
+# explicitly set beforehand.
+unless Oj.default_options[:use_raw_json]
+  require 'rails'
+  Oj.optimize_rails
+  Oj.default_options = { mode: :rails, use_raw_json: true }
+end
+
+# NOTE: Add an optimization to make it easier to work with a StringWriter
+# transparently in different scenarios.
+class Oj::StringWriter
+  # Patch: ActiveSupport can pass an options argument to `as_json` when
+  # serializing a Hash or Array.
+  alias_method :original_as_json, :as_json
+  def as_json(_options = nil)
+    original_as_json
+  end
+
+  # Optimization: We can use `to_s` directly, this is not important but gives a
+  # slight boost to a few use cases that use it for caching in Memcached.
+  def to_json(_options = nil)
+    to_s.delete_suffix("\n")
+  end
+end

data/lib/oj_serializers/sugar.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require 'rails/railtie'
+require 'action_controller'
+require 'action_controller/railtie'
+
+require 'oj_serializers'
+require 'oj_serializers/controller_serialization'
+
+# Internal: Allows to pass Oj serializers as options in `render`.
+class OjSerializers::Railtie < Rails::Railtie
+  initializer 'oj_serializers.action_controller' do
+    ActiveSupport.on_load(:action_controller) do
+      include(OjSerializers::ControllerSerialization)
+    end
+  end
+end

data/lib/oj_serializers/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module OjSerializers
+  VERSION = '1.0.0'
+end

metadata

@@ -0,0 +1,103 @@
+--- !ruby/object:Gem::Specification
+name: oj_serializers
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Maximo Mussini
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2020-11-07 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: oj
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 3.8.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 3.8.0
+- !ruby/object:Gem::Dependency
+  name: actionpack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.0'
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.0'
+description: oj_serializers leverages the performance of the oj JSON serialization
+  library, and minimizes object allocations, all while provding a similar API to Active
+  Model Serializers.
+email:
+- maximomussini@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- README.md
+- lib/oj_serializers.rb
+- lib/oj_serializers/compat.rb
+- lib/oj_serializers/controller_serialization.rb
+- lib/oj_serializers/json_string_encoder.rb
+- lib/oj_serializers/json_value.rb
+- lib/oj_serializers/memo.rb
+- lib/oj_serializers/serializer.rb
+- lib/oj_serializers/setup.rb
+- lib/oj_serializers/sugar.rb
+- lib/oj_serializers/version.rb
+homepage: https://github.com/ElMassimo/oj_serializers
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/ElMassimo/oj_serializers
+  source_code_uri: https://github.com/ElMassimo/oj_serializers
+  changelog_uri: https://github.com/ElMassimo/oj_serializers/blob/master/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.3.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.1.2
+signing_key:
+specification_version: 4
+summary: A lighter JSON serializer for Ruby Objects in Rails. Easily migrate away
+  from Active Model Serializers.
+test_files: []