Documentation questions

[silva96]

Hey! After reading the documentation, I was wondering what's the difference between all these options, in terms of the output they give and the performance of each.

In a rails controller:

# 1. "new(...).to_json"
render json: {
  users: Panko::ArraySerializer.new(users, each_serializer: UserSerializer).to_json
}

# 2. "new.serialize_to_json(...)"
render json: {
  users: Panko::ArraySerializer.new.serialize_to_json(users, each_serializer: UserSerializer)
}

# 3. "new.serialize(...)"
render json: {
  users: Panko::ArraySerializer.new.serialize(users, each_serializer: UserSerializer)
}

# 4. "new.serialize(...).to_json"
render json: {
  users: Panko::ArraySerializer.new.serialize(users, each_serializer: UserSerializer).to_json
}

# 5. "Panko::Response"
render json: Panko::Response.new(
  users: Panko::ArraySerializer.new(users, each_serializer: UserSerializer)
)

Thanks in advance!

[yosiat]

Hey!

"new(...).to_json" / "new.serialize_to_json(...)" - will return a JSON serialized String, so if you do render json: { .. } you will get an output of object with value as string, this is something I don't think you expect. The way to solve this String issue, is with Panko::Response (option 5).

"new.serialize(...)" / "new.serialize(...).to_json" - serialize creates an array of hashes, together with to_json will return a JSON string on it. For performance reasons it's not recommended to use it, since:

• Panko iterates the users and convert the AR objects to Array of Hashes
• And another iteration is required to convert Array of Hashes to JSON while with serialize_to_json / to_json - You do it on one pass, See https://panko.dev/docs/design-choices#ojstringwriter for more explanation.

Let me know if you have more questions.

[silva96]

Thanks! very clear.

[metalelf0]

Hey @yosiat , thanks for this answer - I think it deserves a place in the documentation on its own :) What's the equivalent for single object serialization?

ObjectSerializer.new.serialize_to_json(object) is preferable over ObjectSerializer.new.serialize(object).to_json, right? In the "getting started" documentation I don't think it's clear which one is recommended.

I think existing documentation could greatly benefit from a page with common use cases, like:

• serialize a single object in a Rails controller;
• serialize an ActiveRecord collection in a Rails controller;
• serialize nested relations (e.g. User with many Comments) and eager loading;
• serialize an array of objects;
• serialize an array of objects using ActiveSupport::Cache as a cache backend;
• and so on.

I know most of these things are outside the scope of a serialization library, but they could give hints about possible ways of integrating Panko with the existing rails ecosystem for starters.

Thanks for the great work on this gem!

[yosiat]

@metalelf0 I agree with you here that there are too many options to serialize an array and single object. The next major version of Panko (no ETA) should address this with breaking API changes.

For now, I will mark it as documentation label and will accept PRs for clarifying the documentation.

[yosiat]

I'll close this issue, if there any more questions about this topic, please open discussion. If you find bugs - please open new issue.