oj_serializers 1.0.2 → 2.0.0.pre.beta.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a03657fa651d7b3309e4d182dc2a8446733190cd92833ebcfd20a3bc24efeb9b
-  data.tar.gz: fa3169a06d80fbc73324eda88866a3f549f59ccf5d75085ac988a6e571d7d8a2
+  metadata.gz: 4ebc24ba352b46585589ae760b579009e18e9de772b1d015eb0fdfa465a39b93
+  data.tar.gz: 475283ebe5897716eb1812a474358ddc3775746e1e0f8ff011204fc3ff76219e
 SHA512:
-  metadata.gz: 3b1fe6d00cec3052d51bb4f508731a458d52b23645e936e83992f144d638d381abaa95cbb0adbb8280bf41f2f13e2fcdbe6916556a9d5ecbac8135ceffc37f00
-  data.tar.gz: 77372418c201970662770f7ab1bbfeeca7a9260bf155ff2431cae7003dbd6dbed5d1dafaf9e149347ec452015d1656b2430089688316e41b1d837d0b5e971cfc
+  metadata.gz: e4a0c4e060fbac9cc04ef2e6ce31406fa5aa83052989a272e2bba6c1b7c30767e82bd22aa51b016716adfff8bb039442a7725f25ddf7093ca4b33de646360181
+  data.tar.gz: d0d41a7a283e26831222a99b96669498eb01b14dac383da008db053c769052ca0e91b1078f1c0d9c797faadd082b3ecaeabce37fa267d617bc2bc039a05dcaec

data/README.md

@@ -10,13 +10,14 @@ Oj Serializers
 </p>
 </h1>
 
-JSON serializers for Ruby, built on top of the powerful [`oj`][oj] library.
+Faster JSON serializers for Ruby, built on top of the powerful [`oj`][oj] library.
 
 [oj]: https://github.com/ohler55/oj
 [mongoid]: https://github.com/mongodb/mongoid
 [ams]: https://github.com/rails-api/active_model_serializers
 [jsonapi]: https://github.com/jsonapi-serializer/jsonapi-serializer
 [panko]: https://github.com/panko-serializer/panko_serializer
+[blueprinter]: https://github.com/procore/blueprinter
 [benchmarks]: https://github.com/ElMassimo/oj_serializers/tree/master/benchmarks
 [raw_benchmarks]: https://github.com/ElMassimo/oj_serializers/blob/master/benchmarks/document_benchmark.rb
 [sugar]: https://github.com/ElMassimo/oj_serializers/blob/master/lib/oj_serializers/sugar.rb#L14
@@ -24,11 +25,13 @@ JSON serializers for Ruby, built on top of the powerful [`oj`][oj] library.
 [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/
 
 ## Why? 🤔
 
-[`ActiveModel::Serializer`][ams] has a nice DSL, but it allocates many objects leading
-to memory bloat, time spent on GC, and lower performance.
+[`ActiveModel::Serializer`][ams] has a nice DSL, but it allocates many objects
+leading to memory bloat, time spent on GC, and lower performance.
 
 `Oj::Serializer` provides a similar API, with [better performance][benchmarks].
 
@@ -41,7 +44,6 @@ Learn more about [how this library achieves its performance][design].
 - Support for `has_one` and `has_many`, compose with `flat_one`
 - Useful development checks to avoid typos and mistakes
 - Integrates nicely with Rails controllers
-- Caching
 
 ## Installation 💿
 
@@ -58,13 +60,13 @@ And then run:
 ## Usage 🚀
 
 You can define a serializer by subclassing `Oj::Serializer`, and specify which
-attributes should be serialized to JSON.
+attributes should be serialized.
 
 ```ruby
 class AlbumSerializer < Oj::Serializer
   attributes :name, :genres
 
-  attribute \
+  serialize
   def release
     album.release_date.strftime('%B %d, %Y')
   end
@@ -76,83 +78,63 @@ end
 <details>
   <summary>Example Output</summary>
 
-```json
+```ruby
 {
-  "name": "Abraxas",
-  "genres": [
+  name: "Abraxas",
+  genres: [
     "Pyschodelic Rock",
     "Blues Rock",
     "Jazz Fusion",
-    "Latin Rock"
+    "Latin Rock",
   ],
-  "release": "September 23, 1970",
-  "songs": [
+  release: "September 23, 1970",
+  songs: [
     {
-      "track": 1,
-      "name": "Sing Winds, Crying Beasts",
-      "composers": [
-        "Michael Carabello"
-      ]
+      track: 1,
+      name: "Sing Winds, Crying Beasts",
+      composers: ["Michael Carabello"],
     },
     {
-      "track": 2,
-      "name": "Black Magic Woman / Gypsy Queen",
-      "composers": [
-        "Peter Green",
-        "Gábor Szabó"
-      ]
+      track: 2,
+      name: "Black Magic Woman / Gypsy Queen",
+      composers: ["Peter Green", "Gábor Szabó"],
     },
     {
-      "track": 3,
-      "name": "Oye como va",
-      "composers": [
-        "Tito Puente"
-      ]
+      track: 3,
+      name: "Oye como va",
+      composers: ["Tito Puente"],
     },
     {
-      "track": 4,
-      "name": "Incident at Neshabur",
-      "composers": [
-        "Alberto Gianquinto",
-        "Carlos Santana"
-      ]
+      track: 4,
+      name: "Incident at Neshabur",
+      composers: ["Alberto Gianquinto", "Carlos Santana"],
     },
     {
-      "track": 5,
-      "name": "Se acabó",
-      "composers": [
-        "José Areas"
-      ]
+      track: 5,
+      name: "Se acabó",
+      composers: ["José Areas"],
     },
     {
-      "track": 6,
-      "name": "Mother's Daughter",
-      "composers": [
-        "Gregg Rolie"
-      ]
+      track: 6,
+      name: "Mother's Daughter",
+      composers: ["Gregg Rolie"],
     },
     {
-      "track": 7,
-      "name": "Samba pa ti",
-      "composers": [
-        "Santana"
-      ]
+      track: 7,
+      name: "Samba pa ti",
+      composers: ["Santana"],
     },
     {
-      "track": 8,
-      "name": "Hope You're Feeling Better",
-      "composers": [
-        "Rolie"
-      ]
+      track: 8,
+      name: "Hope You're Feeling Better",
+      composers: ["Rolie"],
     },
     {
-      "track": 9,
-      "name": "El Nicoya",
-      "composers": [
-        "Areas"
-      ]
-    }
-  ]
+      track: 9,
+      name: "El Nicoya",
+      composers: ["Areas"],
+    },
+  ],
 }
 ```
 </details>
@@ -209,8 +191,6 @@ render json: {
 
 You can use these serializers inside arrays, hashes, or even inside `ActiveModel::Serializer` by using a method in the serializer.
 
-Follow [this discussion][raw_json] to find out more about [the `raw_json` extensions][raw_json] that made this high level of interoperability possible.
-
 ## Attributes DSL 🛠
 
 Attributes methods can be used to define which model attributes should be serialized
@@ -238,22 +218,23 @@ maintainable.
 
 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:
+Simply call `serialize` right before defining the method, and it will be serialized:
 
 ```ruby
 class PlayerSerializer < Oj::Serializer
-  attribute \
+  serialize
   def full_name
     "#{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`](https://github.com/ElMassimo/oj_serializers#using-a-different-alias-for-the-internal-object).
+You can customize this by using [`object_as`](#using-a-different-alias-for-the-internal-object).
 
 ### `ams_attributes` 🐌
 
@@ -307,7 +288,8 @@ end
 
 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.
+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.
 
@@ -321,16 +303,16 @@ class SongSerializer < Oj::Serializer
 end
 ```
 
-The associations DSL is more concise and achieves better performance, so prefer to use it instead of manually definining attributes:
+The associations DSL is essentially a shortcut for defining attributes manually:
 
 ```ruby
 class SongSerializer < SongMetadataSerializer
-  attribute \
+  serialize
   def album
     AlbumSerializer.one(song.album)
   end
 
-  attribute \
+  serialize
   def composers
     ComposerSerializer.many(song.composers)
   end
@@ -348,12 +330,26 @@ class DiscographySerializer < Oj::Serializer
   object_as :artist
 
   # Now we can use `artist` instead of `object` or `discography`.
+  serialize
   def latest_albums
     artist.albums.desc(:year)
   end
 end
 ```
 
+### Aliasing or renaming attributes
+
+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, as: :latest_album, serializer: AlbumSerializer
+
+  attribute :title, as: :name
+end
+```
+
 ### Rendering an attribute conditionally
 
 All the attributes and association methods can take an `if` option to render conditionally.
@@ -381,7 +377,7 @@ Use `memo` for memoization and storing temporary information.
 class DownloadSerializer < Oj::Serializer
   attributes :filename, :size
 
-  attribute \
+  serialize
   def progress
     "#{ last_event&.progress || 0 }%"
   end
@@ -396,26 +392,112 @@ private
 end
 ```
 
-### Caching 📦
+### Writing directly to JSON
+
+In some corner cases it might be faster to serialize using a `Oj::StringWriter`.
 
-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:
+You can toggle this mode at a serializer level by using `default_format :json`,
+or configure it globally from your base serializer.
 
 ```ruby
-class CachedUserSerializer < UserSerializer
-  cached_with_key ->(user) {
-    "#{ user.id }/#{ user.current_sign_in_at }"
-  }
+class BaseSerializer < Oj::Serializer
+  default_format :json # :hash is the default
 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`.
+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.
 
-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.
+Follow [this discussion][raw_json] to find out more about [the `raw_json` extensions][raw_json] that made this high level of interoperability possible.
+
+<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>
 
 ## Design 📐
 
 Unlike `ActiveModel::Serializer`, which builds a Hash that then gets encoded to
-JSON, this implementation uses `Oj::StringWriter` to write JSON directly,
+JSON, this implementation can use `Oj::StringWriter` to write JSON directly,
 greatly reducing the overhead of allocating and garbage collecting the hashes.
 
 It also allocates a single instance per serializer class, which makes it easy
@@ -425,16 +507,17 @@ to use, while keeping memory usage under control.
 
 `ActiveModel::Serializer` instantiates one serializer object per item to be serialized.
 
-Other libraries such as [`jsonapi-serializer`][jsonapi] evaluate serializers in the context of
-a `class` instead of an `instance` of a class. Although it is efficient in terms
-of memory usage, the downside is that you can't use instance methods or local
-memoization, and any mixins must be applied to the class itself.
+Other libraries such as [`blueprinter`][blueprinter] [`jsonapi-serializer`][jsonapi]
+evaluate serializers in the context of a `class` instead of an `instance` of a class.
+The downside is that you can't use instance methods or local memoization, and any
+mixins must be applied to the class itself.
 
 [`panko-serializer`][panko] also uses `Oj::StringWriter`, but it has the big downside of having to own the entire render tree. Putting a serializer inside a Hash or an Active Model Serializer and serializing that to JSON doesn't work, making a gradual migration harder to achieve. Also, it's optimized for Active Record but I needed good Mongoid support.
 
 `Oj::Serializer` combines some of these ideas, by using instances, but reusing them to avoid object allocations. Serializing 10,000 items instantiates a single serializer. Unlike `panko-serializer`, it doesn't suffer from [double encoding problems](https://panko.dev/docs/response-bag) so it's easier to use.
 
-As a result, migrating from `active_model_serializers` is relatively straightforward because instance methods, inheritance, and mixins work as usual.
+As a result, migrating from `active_model_serializers` is relatively
+straightforward because instance methods, inheritance, and mixins work as usual.
 
 ## Formatting 📏
 

data/lib/oj_serializers/compat.rb

@@ -6,28 +6,13 @@ require 'active_model_serializers'
 # as well.
 class ActiveModel::Serializer
   # JsonStringEncoder: Used internally to write a single object to JSON.
-  #
-  # Returns nothing.
-  def self.write_one(writer, object, options)
-    writer.push_value(new(object, options))
+  def self.one(object, options = nil)
+    new(object, options)
   end
 
   # JsonStringEncoder: Used internally to write an array of objects to JSON.
-  #
-  # Returns nothing.
-  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.
-  #
-  # Returns an Oj::StringWriter.
-  def self.new_json_writer
-    OjSerializers::Serializer.send(:new_json_writer)
+  def self.many(array, options = nil)
+    array.map { |object| new(object, options) }
   end
 end
 

data/lib/oj_serializers/controller_serialization.rb

@@ -20,10 +20,10 @@ module OjSerializers::ControllerSerialization
   #
   # which is more performant.
   %i[_render_option_json _render_with_renderer_json].each do |renderer_method|
-    define_method renderer_method do |resource, **options|
+    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))
+        super(OjSerializers::JsonStringEncoder.encode_to_json(resource, **options), options.except(:root, :serializer, :each_serializer))
       else
         super(resource, **options)
       end

data/lib/oj_serializers/json_string_encoder.rb

@@ -14,43 +14,27 @@ module OjSerializers::JsonStringEncoder
     # regardless of whether a serializer is specified or not.
     #
     # Returns a JSON string.
-    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)
+    def encode_to_json(object, root: nil, serializer: nil, each_serializer: nil, **options)
+      result = if serializer
+        serializer.one(object, options)
       elsif each_serializer
-        each_serializer.write_many(writer, object, extras)
+        each_serializer.many(object, options)
       elsif object.is_a?(String)
-        return object unless root
-
-        writer.push_json(object)
+        OjSerializers::JsonValue.new(object)
       else
-        writer.push_value(object)
+        object
       end
-
-      writer.pop if root
-
-      writer.to_json
+      Oj.dump(root ? { root => result } : result)
     end
 
     if OjSerializers::Serializer::DEV_MODE
       alias actual_encode_to_json encode_to_json
       # Internal: Allows to detect misusage of the options during development.
-      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)
+      def encode_to_json(object, root: nil, serializer: nil, each_serializer: nil, **options)
+        raise ArgumentError, 'You must use `each_serializer` when serializing collections' if serializer && serializer < OjSerializers::Serializer && object.respond_to?(:map)
+        raise ArgumentError, 'You must use `serializer` when serializing a single object' if each_serializer && each_serializer < OjSerializers::Serializer && !object.respond_to?(:map)
+
+        actual_encode_to_json(object, root: root, serializer: serializer, each_serializer: each_serializer, **options)
       end
     end
   end

data/lib/oj_serializers/serializer.rb

@@ -19,7 +19,7 @@ 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]
+  ALLOWED_INSTANCE_VARIABLES = %w[memo object options]
 
   CACHE = (defined?(Rails) && Rails.cache) ||
           (defined?(ActiveSupport::Cache::MemoryStore) ? ActiveSupport::Cache::MemoryStore.new : OjSerializers::Memo.new)
@@ -35,30 +35,17 @@ class OjSerializers::Serializer
   # 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)
+    @options || DEFAULT_OPTIONS
   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
+    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(',')}"
       end
-    end)
+    end
   end
 
   # Internal: Used internally to write a single object to JSON.
@@ -70,9 +57,8 @@ class OjSerializers::Serializer
   # 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)
+    write_to_json(writer, item, options)
     writer.pop
   end
 
@@ -93,61 +79,42 @@ 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)
+    @memo ||= OjSerializers::Memo.new
   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
+  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)
+    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
+    # 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
+      else
+        raise ArgumentError, "Unknown sorting option: #{value.inspect}"
+      end
+    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.
+    # 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
+      else
+        raise(ArgumentError, "Expected transform_keys to be callable, got: #{transformer.inspect}")
       end
-    rescue StandardError => e
-      raise ActiveModel::MissingAttributeError, "#{e.message} in #{self.class} for #{@object.inspect}"
     end
-  end
 
-  class << self
+    # Public: Creates an alias for the internal object.
+    def object_as(name, **)
+      define_method(name) { @object }
+    end
+
     # Internal: We want to discourage instantiating serializers directly, as it
     # prevents the possibility of reusing an instance.
     #
@@ -156,15 +123,17 @@ private
 
     # 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
+    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 non_cached_write_one write_one
+    # Helper: Serializes one or more items.
+    def render(item, options = nil)
+      many?(item) ? many(item, options) : one(item, options)
+    end
 
-    # 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 one or more items.
+    def render_as_hash(item, options = nil)
+      many?(item) ? many_as_hash(item, options) : one_as_hash(item, options)
+    end
 
     # Helper: Serializes the item unless it's nil.
     def one_if(item, options = nil)
@@ -177,7 +146,7 @@ private
     # 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)
+    def one_as_json(item, options = nil)
       writer = new_json_writer
       write_one(writer, item, options)
       writer
@@ -189,15 +158,33 @@ private
     # 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)
+    def many_as_json(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 }
+    # Public: Renders the configured attributes for the specified object,
+    # without serializing to JSON.
+    #
+    # item - the item to serialize
+    # options - list of external options to pass to the sub class (available in `item.options`)
+    #
+    # Returns a Hash, with the attributes specified in the serializer.
+    def one_as_hash(item, options = nil)
+      instance.render_as_hash(item, options)
+    end
+
+    # Public: Renders an array of items using this serializer, without
+    # serializing to JSON.
+    #
+    # items - Must respond to `each`.
+    # options - list of external options to pass to the sub class (available in `item.options`)
+    #
+    # Returns an Array of Hash, each with the attributes specified in the serializer.
+    def many_as_hash(items, options = nil)
+      serializer = instance
+      items.map { |item| serializer.render_as_hash(item, options) }
     end
 
     # Internal: Will alias the object according to the name of the wrapper class.
@@ -211,95 +198,53 @@ private
     #
     # 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
+      @_attributes ||= superclass.try(:_attributes)&.dup || {}
     end
 
   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.
+    def define_serialization_shortcuts(format)
+      case format
+      when :json, :hash
+        singleton_class.alias_method :one, :"one_as_#{format}"
+        singleton_class.alias_method :many, :"many_as_#{format}"
+      else
+        raise ArgumentError, "Unknown serialization format: #{format.inspect}"
       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: Identifiers are always serialized first.
+    def identifier(name = :id, **options)
+      add_attribute(name, **options, attribute: :method, identifier: true, if: -> { !@object.new_record? })
+    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)
+    def has_many(name, serializer:, root: name, as: root, **options)
+      add_attribute(name, association: :many, as: as, serializer: serializer, **options)
     end
 
     # Public: Specify an object that should be serialized using the serializer.
-    def has_one(name, root: name, serializer:, **options)
-      add_association(name, write_method: :write_one, root: root, serializer: serializer, **options)
+    def has_one(name, serializer:, root: name, as: root, **options)
+      add_attribute(name, association: :one, as: as, 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)
+    def flat_one(name, serializer:, **options)
+      add_attribute(name, association: :flat, 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 }
+      options = { **options, attribute: :hash }
       method_names.each { |name| _attributes[name] = options }
     end
 
@@ -310,32 +255,49 @@ private
     #
     # 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)
+      add_attribute('id', **options, attribute: :id, identifier: true) if method_names.delete(:id)
+      add_attributes(method_names, **options, attribute: :mongoid)
     end
 
     # Public: Specify which attributes are going to be obtained by calling a
     # method in the object.
     def attributes(*method_names, **options)
-      add_attributes(method_names, **options, strategy: :write_value_using_method_strategy)
+      add_attributes(method_names, **options, attribute: :method)
     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, strategy: :write_value_using_serializer_strategy)
+      add_attributes(method_names, **options, attribute: :serializer)
     end
 
     # Syntax Sugar: Allows to use it before a method name.
     #
     # Example:
-    #   attribute \
+    #   serialize
     #   def full_name
     #     "#{ first_name } #{ last_name }"
     #   end
-    alias attribute serializer_attributes
+    def serialize(name = nil, **options)
+      if name
+        serializer_attributes(name, **options)
+      else
+        @_current_attribute = options
+      end
+    end
+
+    # 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
+      end
+    end
 
     # Backwards Compatibility: Meant only to replace Active Model Serializers,
     # calling a method in the serializer, or using `read_attribute_for_serialization`.
@@ -345,7 +307,23 @@ private
       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)
+      add_attributes(method_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
+
+    # 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
 
   private
@@ -358,8 +336,17 @@ private
       _attributes[name.to_s.freeze] = options
     end
 
-    def add_association(name, options)
-      _associations[name.to_s.freeze] = options
+    # 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
+    end
+
+    # Internal: Whether the object should be serialized as a collection.
+    def many?(item)
+      item.is_a?(Array) ||
+        (defined?(ActiveRecord::Relation) && item.is_a?(ActiveRecord::Relation)) ||
+        (defined?(Mongoid::Association::Many) && item.is_a?(Mongoid::Association::Many))
     end
 
     # Internal: We generate code for the serializer to avoid the overhead of
@@ -368,33 +355,78 @@ private
     #
     # As a result, the performance is the same as writing the most efficient
     # code by hand.
-    def write_to_json_body
+    def code_to_write_to_json
       <<~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)
+        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) {
+              if options[:association]
+                code_to_write_association(method_name, options)
+              else
+                code_to_write_attribute(method_name, options)
+              end
             }
-          }.join}
+          }.join("\n  ") }#{code_to_rescue_no_method if DEV_MODE}
         end
       WRITE_TO_JSON
     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 code_to_render_as_hash
+      <<~RENDER_AS_HASH
+        # Public: Writes this serializer content to a Hash.
+        def render_as_hash(item, options = nil)
+          @object = item
+          @options = options
+          @memo.clear if defined?(@memo)
+          {
+            #{_attributes.map { |method_name, options|
+              code_to_render_conditionally(method_name, options) {
+                if options[:association]
+                  code_to_render_association(method_name, options)
+                else
+                  code_to_render_attribute(method_name, options)
+                end
+              }
+            }.join(",\n    ")}
+          }#{code_to_rescue_no_method if DEV_MODE}
+        end
+      RENDER_AS_HASH
+    end
+
+    def code_to_rescue_no_method
+      <<~RESCUE_NO_METHOD
+
+        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}"
+          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
+            raise e
+          end
+        ensure
+          _check_instance_variables
+      RESCUE_NO_METHOD
+    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}?"
+    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
@@ -407,31 +439,116 @@ private
     end
 
     # Internal: Returns the code for the association method.
-    def write_association_body(method_name, association_options)
+    def code_to_write_attribute(method_name, options)
+      key = key_for(method_name, options).to_s.inspect
+
+      case strategy = options.fetch(:attribute)
+      when :serializer
+        # Obtains the value by calling a method in the serializer.
+        "writer.push_value(#{method_name}, #{key})"
+      when :method
+        # Obtains the value by calling a method in the object, and writes it.
+        "writer.push_value(@object.#{method_name}, #{key})"
+      when :hash
+        # Writes a Hash value to JSON, works with String or Symbol keys.
+        "writer.push_value(@object[#{method_name.inspect}], #{key})"
+      when :mongoid
+        # Writes an Mongoid attribute to JSON, this is the fastest strategy.
+        "writer.push_value(@object.attributes['#{method_name}'], #{key})"
+      when :id
+        # Writes an _id value to JSON using `id` as the key instead.
+        #
+        # NOTE: We skip the id for non-persisted documents, since it doesn't actually
+        # identify the document (it will change once it's persisted).
+        "writer.push_value(@object.attributes['_id'], 'id') unless @object.new_record?"
+      else
+        raise ArgumentError, "Unknown attribute strategy: #{strategy.inspect}"
+      end
+    end
+
+    # Internal: Returns the code for the association method.
+    def code_to_write_association(method_name, 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
+      key = key_for(method_name, options)
+      serializer_class = options.fetch(:serializer)
+
+      case type = options.fetch(:association)
+      when :one
+        <<~WRITE_ONE
+          if associated_object = #{association_method}
+            writer.push_key('#{key}')
+            #{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})
+      when :many
+        <<~WRITE_MANY
+          writer.push_key('#{key}')
+          #{serializer_class}.write_many(writer, #{association_method})
         WRITE_MANY
-      when :write_flat
-        <<-WRITE_FLAT
-        #{serializer_class}.write_flat(writer, #{association_method})
+      when :flat
+        <<~WRITE_FLAT
+          #{serializer_class}.write_to_json(writer, #{association_method})
         WRITE_FLAT
       else
-        raise ArgumentError, "Unknown write_method #{write_method}"
+        raise ArgumentError, "Unknown association type: #{type.inspect}"
+      end
+    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_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)
+        "**(#{include_method_name} ? {#{yield}} : {})"
+      else
+        yield
+      end
+    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)
+      when :serializer
+        "#{key}: #{method_name}"
+      when :method
+        "#{key}: @object.#{method_name}"
+      when :hash
+        "#{key}: @object[#{method_name.inspect}]"
+      when :mongoid
+        "#{key}: @object.attributes['#{method_name}']"
+      when :id
+        "**(@object.new_record? ? {} : {id: @object.attributes['_id']})"
+      else
+        raise ArgumentError, "Unknown attribute strategy: #{strategy.inspect}"
+      end
+    end
+
+    # Internal: Returns the code for the association method.
+    def code_to_render_association(method_name, 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)
+      serializer_class = options.fetch(:serializer)
+
+      case type = options.fetch(:association)
+      when :one
+        "#{key}: (one_item = #{association}) ? #{serializer_class}.one_as_hash(one_item) : nil"
+      when :many
+        "#{key}: #{serializer_class}.many_as_hash(#{association})"
+      when :flat
+        "**#{serializer_class}.one_as_hash(#{association})"
+      else
+        raise ArgumentError, "Unknown association type: #{type.inspect}"
       end
     end
 
@@ -447,16 +564,28 @@ private
 
     # Internal: Cache key to set a thread-local instance.
     def instance_key
-      unless defined?(@instance_key)
-        @instance_key = "#{name.underscore}_instance_#{object_id}".to_sym
+      @instance_key ||= begin
         # 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)
+        # before instantiating a serializer, to apply last minute adjustments.
+        _prepare_serializer
+        "#{name.underscore}_instance_#{object_id}".to_sym
       end
-      @instance_key
+    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
+      end
+      class_eval(code_to_write_to_json)
+      class_eval(code_to_render_as_hash)
     end
   end
+
+  define_serialization_shortcuts(: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 = '1.0.2'
+  VERSION = '2.0.0-beta.1'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: oj_serializers
 version: !ruby/object:Gem::Version
-  version: 1.0.2
+  version: 2.0.0.pre.beta.1
 platform: ruby
 authors:
 - Maximo Mussini
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-03-01 00:00:00.000000000 Z
+date: 2023-03-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: oj
@@ -16,42 +16,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 3.8.0
+        version: 3.14.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'
+        version: 3.14.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.
@@ -80,6 +52,7 @@ 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
+  rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: []
 require_paths:
@@ -88,12 +61,12 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.3.0
+      version: 2.7.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - ">"
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 1.3.1
 requirements: []
 rubygems_version: 3.2.32
 signing_key: