[BAC-1490] Cut represent cost further: type dispatch and per-call preamble

[HolyWalley]

Follow-up to #26. That PR compiled a per-class represent plan; profiling afterwards showed the remaining cost was per-value type dispatch and per-call preamble work, not the plan. Four changes here, each measured in isolation before landing.

Targets feature/BAC-1484 so the diff is only the new work. Tracked in BAC-1490.

Results

Same fixture and spec as #26 (spec/performance, 5000 nested products). Ruby 4.0.1, activemodel 8.1.2, 5 spec runs per revision, each doing 5 timed iterations after 2 warmups. min is the best observed run, avg the mean of the reported averages.

	master	#26 (base)	this PR
Hash payload	83.9 / 93.1 ms	22.1 / 25.1 ms	17.7 / 19.7 ms
Entity object graph	71.6 / 77.4 ms	30.2 / 33.7 ms	19.2 / 20.0 ms
Allocations, hash	470,027	35,005	15,003
Allocations, entity	425,025	35,006	15,004

speedup	vs #26	vs master
Hash payload	1.25x min / 1.27x avg	4.74x min / 4.72x avg
Entity object graph	1.57x min / 1.68x avg	3.73x min / 3.87x avg

Allocations are down 57% against #26 and 31x against master.

The entity-object-graph path was the slower of the two on #26 (30.2 ms vs 22.1 ms) and is now level with the hash path.

What changed

1. Serialize pre-cast values with serialize_cast_value (8b539b4)

represent called type.serialize_with_options on every leaf, which re-runs the full cast — Boolean#serialize does a FALSE_VALUES Set lookup per value, Float#serialize re-runs Helpers::Numeric#cast. When the source is one of our own instances that work is redundant; the values were already cast by these exact types on assignment. ActiveModel models this as serialize_cast_value, which this gem already uses in attribute.rb.

The guard is instance_of?(self), not !is_a?(Hash) — an ActiveRecord model is not a Hash either, but its values were cast by AR's types, not ours (AR decimal → BigDecimal where the entity declares :float). Compatibility is resolved once at plan-compile time, since SerializeCastValue.serialize re-derives it behind a rescue per value.

2. Freeze the default options hash (d56d9cd)

default_represent_options returned a fresh { camelize: true } per call, and every nested entity calls it once — 10,001 hash allocations on this fixture, purely to read one key. Ruby 3.4's opt_hash_freeze makes a frozen static literal allocation-free. Preferred over memoising, which would have broken the documented ability to override the method; the method is still called every time.

3. Inline the field read, drop each_with_object (36156a7)

each_with_object allocates one object per call more than each with an explicit memo, and is ~29% slower on this loop shape. fetch_field_value re-tested is_a?(Hash) for every field though the answer is fixed per call, and re-derived name.to_sym on each symbol-key lookup. Hoisting the test and interning the symbol at plan-compile time is ~37% faster for symbol-keyed hashes and ~45% for object sources. String keys still take precedence. fetch_field_value is public API and stays, just off the hot path.

4. Represent arrays of entities in one pass (c77f57b)

Type::Array called Type::Entity#serialize_with_options per element, which called represent per element, re-running the whole preamble — options resolution, custom_serializers lookup, plan lookup — 5000 times for the same answer. represent_all resolves it once and loops.

Measured per element, the removed method frames are worth nothing (1151 ns vs 1163 ns); the hoisted preamble is the entire win, 1209 ns → 973 ns. build_representation takes the plan as an argument so represent and represent_all share one loop body rather than duplicating it. The dispatch checks the exact class, not is_a?, because a Type::Entity subclass may override serialize_with_options and routing around it would silently change behaviour.

This fires automatically for any attribute :xs, :array, of: "SomeEntity" — no caller changes. represent_all is also public, so collections built by hand outside an entity attribute can use it directly.

Correctness

Serialized output is byte-identical on master, #26 and this branch — the full 942 KB JSON hashes to f8d9c3ca… on all three.

Beyond the suite, the following were diffed before/after and are unchanged: nil array elements, empty and nil arrays, string- and symbol-keyed hashes, uncast/raw input ({ a: "7", b: 9 } still coerces to { "a" => 7, "b" => "9" }), subclass instances, mixed entity/hash arrays, custom serializes blocks, and camelize: false.

Suite: 53 examples, 1 failure — inspect_spec.rb:45, which fails identically on master and on #26 (a Rails 8 inspect-formatting change, unrelated). 3 specs added for represent_all. Rubocop reports the same 9 pre-existing offences as #26; no new ones.

Notes

• Both this branch and [BAC-1484] Speed up Entity.represent for large nested payloads (~3-4x) #26 forked at 41e5989, before [BAC-1482] Add read_only attribute support and the 0.15.1 version bump landed on master. Neither touches schemas/json.rb, so a rebase should be clean, but [BAC-1484] Speed up Entity.represent for large nested payloads (~3-4x) #26 wants rebasing before merge and this one after.
• No version bump here — assumed to belong with whatever release picks this up.

Deliberately not done

Measured and rejected, recorded in BAC-1490 so nobody repeats them:

• Building the JSON string directly instead of a Hash. Prototyped with pre-baked frozen "key": fragments, byte-identical output: 39.1 ms vs 27.3 ms and 2.4x the allocations. to_json over the finished hash is only ~13% of total; a Ruby traversal cannot beat the C generator. The intermediate hash is not the problem.
• Struct/Data as the represent output. Same allocation cost as the hash, and JSON.generate cannot serialize them natively.

Still open: a fast path for arrays of scalars (tags-style attributes still serialize element-by-element) needs pre_cast threaded through the serialize_with_options signature, and specs for uncast input first. A naive version silently breaks coercion and the current suite does not catch it.

---

🤖 Generated with Claude Code

https://claude.ai/code/session_01PWj42911KiUWpDA4BkpLPh