Panko Serializer

Panko is a high-performance library designed for serializing ActiveRecord and Ruby objects into JSON strings. It is inspired by ActiveModelSerializers 0.9 but optimized for speed.

To achieve high performance, Panko utilizes several key strategies:

• Oj Integration: Uses the Oj gem for fast, incremental serialization via Oj::StringWriter.
• Serialization Descriptors: Computes most metadata ahead of time to minimize overhead during the actual serialization process.
• Self-contained Type Casting: Performs its own type casting rather than relying on the slower ActiveRecord implementation.

Panko is a high-performance library designed for serializing ActiveRecord and Ruby objects to JSON strings. It is inspired by ActiveModelSerializers 0.9 but optimized for speed.

To achieve its performance goals, Panko utilizes:

• Oj: It relies on the Oj library for fast, incremental serialization using Oj::StringWriter.
• Serialization Descriptors: Most metadata is computed ahead of time to minimize overhead during the actual serialization process.
• Self-contained Type Casting: Panko performs its own type casting rather than relying on ActiveRecord, reducing latency.

Panko achieves high performance through three primary design choices:

1. Oj::StringWriter: Instead of building intermediate Ruby hashes (which is memory and CPU intensive), Panko uses Oj::StringWriter to incrementally serialize values directly into a JSON string in C.
2. Ahead-of-time Metadata (Serialization Descriptor): Panko builds a Serialization Descriptor during initialization. This descriptor pre-calculates which fields are properties, which are methods, and handles only/except filtering. This minimizes the number of questions asked during the actual serialization loop.
3. C-level Type Casting: Panko performs type casting in C to avoid the overhead of ActiveRecord's Ruby-based type casting. It avoids expensive operations like duplicating strings or converting time strings into full Ruby Time objects if they can be formatted directly for JSON.

Panko can automatically detect the correct serializer by looking at the relationship name, allowing you to omit the serializer: or each_serializer: option.

Inference Logic:

1. Take the relationship name (e.g., :author or :comments).
2. Singularize and camelize the name.
3. Look for a constant defined with that name followed by the Serializer suffix (using Object.const_get).

Example:

class PostSerializer < Panko::Serializer
  attributes :title, :body

  has_one :author
  has_many :comments
end

Error Handling: If Panko cannot find the inferred serializer, it will throw an error at startup time, such as: Can't find serializer for PostSerializer.author has_one relationship.

Panko optimizes time serialization by targeting the final JSON requirement: a UTC ISO8601 formatted string. Instead of converting database strings into Ruby Time objects, it uses optimized logic:

• If a string ends with Z and matches the UTC ISO8601 regex, it is returned as-is.
• If a string is in a standard database timestamp format, Panko uses regex and string concatenation to convert it to UTC ISO8601 directly in C.
• If neither condition is met, it falls back to ActiveRecord's standard type casting.

Define a serializer by inheriting from Panko::Serializer. Use the attributes method to specify which fields to include. You can also define associations using has_many or has_one, specifying the target serializer if necessary.

class PostSerializer < Panko::Serializer
  attributes :title
end

class UserSerializer < Panko::Serializer
  attributes :id, :name, :age

  has_many :posts, serializer: PostSerializer
end

To install Panko, add the gem to your Gemfile and run bundle install in your terminal.

gem "panko_serializer"

bundle install

Panko is a high-performance serializer specifically for ActiveRecord objects. It uses a declarative syntax inspired by ActiveModelSerializers to define which attributes and methods should be included in the JSON output.

To use Panko:

1. Define a serializer class inheriting from Panko::Serializer.
2. Use the attributes method to specify fields.
3. Define custom methods within the serializer to handle complex logic or combined fields.
4. Instantiate the serializer and call serialize_to_json(object).

Note: Panko cannot serialize objects other than ActiveRecord objects.

class UserSerializer < Panko::Serializer
  attributes :name, :age, :email

  def name
    "#{object.first_name} #{object.last_name}"
  end
end

# Usage
user = User.first
serializer = UserSerializer.new
json_string = serializer.serialize_to_json(user)

When constructing a JSON payload that includes Panko serialization results, using standard Ruby hashes can result in a JSON string being nested inside another JSON string (double encoding). Panko::Response solves this by correctly handling Panko serializer objects within a response hash, ensuring they are serialized as part of the main JSON structure rather than as pre-encoded strings.

To serialize a collection, pass the Panko::ArraySerializer instance directly into the Panko::Response.new constructor.

class PostsController < ApplicationController
  def index
   posts = Post.all
   render json: Panko::Response.new(
     success: true,
     total_count: posts.count,
     posts: Panko::ArraySerializer.new(posts, each_serializer: PostSerializer)
   )
  end
end