[BAC-1484] Speed up Entity.represent for large nested payloads (~3-4x)

[taleh007]

What

Entity.represent was slow on large payloads. This PR makes it ~4x faster for hash sources and ~3x faster for entity object graphs, and adds an opt-in performance spec suite that documents the baseline.

Benchmark — one catalog entity holding 5000 products, each with regular fields plus a small nested entity (min / avg over 5 runs, same machine):

Source shape	Before	After	Speedup
Hash payload	712 / 731 ms	168 / 180 ms	4.2x
Entity object graph	601 / 623 ms	211 / 248 ms	2.8x

Why it works (in simple terms)

Representing a list of 5000 products means calling represent 10,001 times (the root + each product + each product's nested entity). The old code redid the same preparation inside every one of those calls — preparation whose result never changes:

1. It kept re-translating the same column names. Every product has the same attributes, and created_at camelizes to createdAt every single time — yet the inflector ran again for every attribute of every object (~50,000 times per call). Now each class computes its "represent plan" once — the output key, the type and the custom serializer for each attribute — and every later call just walks that precomputed list. Like a spreadsheet: you translate the header row once, not once per row. (Same trick as the compiled JSON assigner from BAC-1267 — and like it, the plan is built per exact class and invalidated if attribute / serializes is called later.)

2. It kept photocopying hashes just to read them. Every nested hash was wrapped in with_indifferent_access — a full copy — only so fields could be found whether the keys are strings or symbols. Now we simply try the string key first and the symbol key second; no copy at all. The one place that genuinely relies on the copy — serializes blocks, which receive the source hash and may look fields up either way — still gets it, so their behavior is unchanged.

3. It allocated option hashes nobody asked for. default_represent_options.merge(options) ran for every nested entity even when options was empty. The merge is now skipped when there is nothing to merge.

None of this changes what represent returns — it just stops paying per object for work that is per class. One observable nuance: untyped hash attributes now pass the original hash through instead of an indifferent-access copy (identical once rendered to JSON).

Performance specs

New opt-in suite, excluded from the default run (CI is unaffected):

PERFORMANCE=1 bundle exec rspec spec/performance

It represents the 5000-product catalog from both source shapes, asserts the output is correct, prints the timings, and fails only if a run exceeds a deliberately generous 2s budget — a catastrophic-regression guard (e.g. accidentally quadratic serialization), not a microbenchmark.

Jira

BAC-1484

🤖 Generated with Claude Code

[HolyWalley]

is it take much to run? maybe make them on by default?

[taleh007]

They add ~4.5s locally vs 0.08s for the unit suite (~50x slower), and more on CI — plus wall-clock assertions on shared CI runners are the classic flakiness source. That's why they're opt-in (PERFORMANCE=1 bundle exec rspec spec/performance). Happy to flip the default if you feel strongly — it's a one-liner.

[yard]

Does the dynamically emitted serialization/deserialization code still apply? Any optimizations to be made there?

[yard]

Since we are talking optimizations here, shall this “try this, then try that” be gone too?

[taleh007]

Measured it: on symbol-keyed sources (worst case — the string lookup always misses first) the fallback costs ~16ms per 5000 products (180ms vs 164ms for string-keyed, ~9%). There's no generic single lookup without knowing the hash's key style; we could sniff the style once per hash and pick one accessor, but that felt like extra branching for a second-order win. FWIW it's the same string-then-symbol convention the compiled from_json assigner already uses. Can do the sniff as a follow-up if you think it's worth it.

[yard]

Also pt. 2 (killing with_indifferent_access everywhere but for custom serilizer block) does look a tad weird, we probably don’t really gain much from it but now implement it ourselves

[taleh007]

@yard on your two review comments:

Does the dynamically emitted code still apply? Yes — the compiled from_json assigner is untouched; this PR only changes the serialization direction. represent could be code-generated the same way (inlining the key names per class instead of walking the plan array), but the remaining time is dominated by value fetching and serialize_with_options dispatch, so I'd expect only another ~5-10% from codegen. I'd rather file that as a follow-up ticket than grow this PR.

On dropping with_indifferent_access ("we probably don't really gain much") — I measured exactly that. Restoring the unconditional conversion while keeping the plan cache takes the hash path from 180ms back to 341ms at 5000 products — so removing the copy is a ~1.9x win on its own, roughly half of this PR's total improvement on hash payloads (it was deep-copying ~10k nested hashes per call). The hand-rolled part is three lines and follows the same string-then-symbol convention the compiled assigner already uses; the asymmetry (classes with serializes blocks keep the indifferent-access copy) exists only to avoid breaking the documented block contract.