Design Choices

Panko is a serializer for ActiveRecord objects (it can serialize plain Ruby objects too, but its fast paths are built around ActiveRecord) that aims for high performance behind a small, simple API.

Its speed comes from these ideas, each explained below:

  • Code generation. Panko compiles a specialized serializer, in plain Ruby, once per serializer class, so the per-record work is straight-line code instead of a metadata-driven loop.
  • Per-model specialization. For each ActiveRecord class a serializer meets, Panko compiles a variant that reads columns straight from the model’s attribute storage.
  • Incremental JSON. JSON is built incrementally with Oj::StringWriter, without an intermediate Hash.
  • Ahead-of-time metadata. Everything Panko can figure out about a serializer (which fields are columns, which are methods, which associations exist) is resolved when the class is first used, not inside the serialization loop.

Panko used to ship a C extension. It no longer does: the engine is now pure Ruby that Panko generates and the Ruby VM (with YJIT) compiles. There is nothing to build when you install the gem.

Serialization overview

Let’s say we want to serialize a User object that has first_name, last_name, age, and email columns.

The serializer looks like this:

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

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

And using it:

user = User.first
UserSerializer.new.serialize_to_json(user)

Here is what Panko does behind the scenes.

First use of the class. The DSL (attributes, has_one, has_many, …) is accumulated into an immutable description of the serializer’s shape, which answers questions like:

  • Which values are plain columns? Here, age and email.
  • Which values are methods? Here, name (because a method with that name is defined).
  • Which associations exist, and what is each one’s shape?

From that description Panko generates a specialized Ruby class and compiles it once. It caches the compiled class per serializer and per output mode (:json vs :hash), so this cost is paid a single time, not per record.

Each serialization. The generated class walks the record and writes each field directly: reading columns through ActiveRecord’s own attribute readers, invoking your method attributes, and recursing into associations. In :json mode it writes straight into an Oj::StringWriter; in :hash mode it builds a Hash with string keys.

The result is either a JSON string (serialize_to_json) or a Ruby Hash (serialize).

The interesting parts

Code generation

Most Ruby serializers interpret their configuration on every record: for each field they ask “is this a method or a column?”, “is it filtered out?”, “what serializer handles this association?”. Those questions have the same answers for every record, but they get re-asked millions of times.

Panko answers them once, when it first sees a serializer class, and then generates a small, purpose-built Ruby class that hard-codes the answers. There are no per-field branches on the hot path: the generated code for UserSerializer reads age, reads email, and calls name, in a straight line.

Generating plain Ruby (rather than interpreting a data structure, or shipping C) has two payoffs:

  • The VM optimizes it. The emitted methods are small and monomorphic and keep a stable object shape, which is exactly what YJIT specializes well.
  • It stays debuggable. It’s Ruby you can read; backtraces point at real method calls, not at a generic interpreter frame.

You never see any of this. You keep writing ordinary Panko serializers; the code generation is entirely internal.

What the generated code looks like

To make this concrete, here is the code Panko generates for a small serializer:

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

Panko compiles a subclass whose JSON writer is straight-line. It reads each value off the record and pushes it into the writer, with one branch for plain-Hash records versus objects:

def _write_one(record, writer, context, scope, filters)
  if record.is_a?(Hash)
    writer.push_object
    writer.push_value(record["id"], "id")
    writer.push_value(record["title"], "title")
    writer.push_value(record["body"], "body")
    writer.pop
  else
    writer.push_object
    writer.push_value(record.id, "id")
    writer.push_value(record.title, "title")
    writer.push_value(record.body, "body")
    writer.pop
  end
end

There are no per-field lookups or conditionals on the hot path: the field names are baked into the method, and each value is read with ActiveRecord’s own reader (record.title) and pushed as-is. You can inspect this for any serializer by passing its descriptor to Panko::CodeGen.dump:

Panko::CodeGen.dump(PostSerializer.descriptor, output: :json, path: "post_serializer_generated.rb")

(The real output also wraps each field in an only/except filter check, elided here for readability.)

Specializing per record class

The generated class above is generic: it reads fields the same way whatever object you hand it. Panko goes one step further for ActiveRecord: the first time a serializer meets a given record class (say, Post), it compiles a specialized variant hard-wired to that model.

A specialized variant knows things the generic code can’t:

  • How each column is stored. Columns are read straight out of ActiveRecord’s attribute storage rather than through reader-method dispatch, and each column’s type is known at compile time, so, for example, datetime formatting is decided once, not re-checked per value. Anything you’ve overridden (a reader method you defined on the model) still goes through your method.
  • The shape of its associations. The model’s reflections fill in the record class of each has_one / has_many, so nested serializers get specialized variants too.

Each variant starts with an instance_of? guard: a record of a different class falls back to the generic code, so heterogeneous collections stay correct. Plain Hashes and non-ActiveRecord objects always use the generic path.

All of this is automatic and bounded: a serializer keeps a limited number of variants (16 per output mode by default) and routes everything past the cap to the generic path. The cap, and specialization itself, can be tuned or turned off; see Configuration.

Incremental JSON

A typical Ruby JSON pipeline does three passes:

  1. Get an array of records (User.all).
  2. Build an array of Hashes, one per record.
  3. Hand that array to a JSON encoder, which walks it and produces a string.

Steps 2 and 3 allocate a lot (a Hash and several intermediate objects per record) and cost CPU to build and re-walk. Panko skips the intermediate Hash entirely by using Oj’s Oj::StringWriter:

  1. Get an array of records (User.all).
  2. Push values into an Oj::StringWriter as they’re read; it appends to the output string incrementally.
  3. Ask the writer for the finished string, which is essentially free, because it’s already built.

For the :hash output mode there is no writer; Panko builds the Hash directly.

Reading values

Panko reads each attribute with ActiveRecord’s own reader (record.title for an object, record["title"] for a plain Hash) and writes the value straight out. It does not re-implement type casting: the value you’d get from record.title is the value Panko serializes.

A specialized variant reads the same cast value straight from the attribute storage, and still calls a reader you overrode on the model. One exception: it writes json and jsonb columns as their stored text, as 0.8 did, rather than decoding and re-encoding them.

The one transform Panko applies is on the way out the door, so the two output modes agree on their shape:

  • In :json mode, values are pushed into Oj::StringWriter untouched; Oj (in mode: :rails) applies Rails’ as_json conventions as it writes: a Time / Date / TimeWithZone becomes an ISO-8601 string, a Symbol becomes a String, and so on.
  • In :hash mode there is no writer, so Panko applies the same convention itself: a value that is already a JSON primitive (String, Integer, finite Float, nil, booleans) passes through untouched, and anything else goes through its own #as_json: datetimes become the same ISO-8601 string, a Symbol becomes a String, a Hash returned by a method attribute comes back string-keyed. This keeps serialize and serialize_to_json producing matching values, and matches Panko 0.8.5’s Hash output. (The as_json methods come from ActiveSupport, which Rails always loads; in a plain non-Rails process, values without an as_json pass through raw.)

Compiling ahead of time, and reusing instances

Two smaller choices round out the performance story:

  • Compile once, per class. The generated class is built and cached the first time a serializer is used, and each specialized variant the first time its record class is seen. Every later call reuses them, so the generation cost never appears in your request path after warm-up.
  • Pooled instances. Serializing checks a generated instance out of a small pool and returns it afterward, which avoids allocating a fresh object graph for every call. On return the instance drops the record, context, scope, and every instance variable your serializer’s methods set, so a memo such as @label ||= ... lasts one serialize call. Within one Panko::ArraySerializer call the records share one instance, so a memo set for the first record is still there for the next, as in 0.8.

Together these keep the steady-state cost of serializing a record close to the irreducible work of reading its values and writing them out.



Copyright © 2026 Panko Serializer. Distributed under the MIT License.

This site uses Just the Docs, a documentation theme for Jekyll.