docs(bench): refresh the results with the json source and the extension

The read path changed the most: a JSON stream is now read through a generated
`json` -> class mapper instead of being decoded to an intermediate shape, so
deserializing a single object goes from ~101 to ~13.5 µs (~11x faster than the
Symfony streamer) and reading a 20k collection from ~3 s to ~0.15-0.25 s
(~16-27x faster), while streaming keeps a bounded peak.

On the write side the generated `json` mappers brought the per element cost from
~4.0 to ~2.2 µs, and streaming a nested collection now peaks exactly like the
Symfony writer.

Also document that `json_stream_decode()` is ~6.7x faster with the `json_stream`
extension than with the polyfill, since every read number assumes the extension.

Author: joelwurtz

bench/README.md

@@ -118,29 +118,31 @@ where it is measured (see `src/Factory/MapperFactory.php`):
 - **eval** — `EvalLoader`, no on-disk cache (mappers eval'd into the process).
 - **no constructor** — `ConstructorStrategy::NEVER` (writes properties directly).
 - **no attribute checking** — `attributeChecking: false`, `mapPrivateProperties: false`.
+- **no checking** — the above plus `groupChecking: false`.
 
 ## Results
 
-Indicative numbers on PHP 8.5 (your absolute numbers will differ; the *ratios* are
-the point). Lower is better.
+Numbers below were measured on PHP 8.5 with the `json_stream` extension loaded (see
+[the note on the extension](#the-json_stream-extension-matters-on-the-read-path)).
+Your absolute numbers will differ; the *ratios* are the point. Lower is better.
 
 ### Single object — denormalize (array → object, no JSON)
 
 | Approach | Time | vs AutoMapper |
 |----------|-----:|--------------:|
-| AutoMapper, no attribute checking | ~3.0 µs | fastest mapper |
-| AutoMapper (default) | ~7.4 µs | 1× |
-| AutoMapper, eval loader | ~7.3 µs | — |
-| AutoMapper, no constructor | ~7.4 µs | — |
-| Symfony Serializer (`denormalize`) | ~167 µs | **~23× slower** |
+| AutoMapper, no attribute checking | ~2.9 µs | fastest mapper |
+| AutoMapper, eval loader | ~7.1 µs | — |
+| AutoMapper, no constructor | ~7.1 µs | — |
+| AutoMapper (default) | ~7.2 µs | 1× |
+| Symfony Serializer (`denormalize`) | ~165 µs | **~23× slower** |
 
 ### Single object — normalize (object → array, no JSON)
 
 | Approach | Time |
 |----------|-----:|
-| AutoMapper, no attribute checking | ~2.9 µs |
-| AutoMapper (default) | ~8.2 µs |
-| Symfony Serializer (`normalize`) | ~66 µs |
+| AutoMapper, no attribute checking | ~2.5 µs |
+| AutoMapper (default) | ~8.0 µs |
+| Symfony Serializer (`normalize`) | ~63 µs |
 
 ### Single object — deserialize (JSON → object)
 
@@ -149,185 +151,165 @@ fields) so the work is comparable — see the fairness note below.
 
 | Approach | Time |
 |----------|-----:|
-| `json_decode` (array only, no hydration — *pure floor*) | ~2.4 µs |
 | **Manual** (`json_decode` + hand-written hydration — *fair floor*) | ~3.3 µs |
-| AutoMapper, no attribute checking (`json_decode` + map) | ~6 µs |
-| AutoMapper (`json_decode` + map) | ~11 µs |
-| AutoMapper JSON streamer, no attribute checking | ~91 µs |
-| AutoMapper JSON streamer | ~101 µs |
-| Symfony JSON streamer | ~155 µs |
-| Symfony Serializer | ~167 µs |
-
-> **Fairness note.** Symfony's `JsonStreamReader::read()` on a `Type::object`
-> returns a *lazy ghost* whose hydration is deferred until a property is read, so a
-> subject that never touched the result would clock ~13 µs while actually doing
-> almost nothing. Reading the whole graph forces that deferred work, and the fully
-> hydrated cost is ~155 µs. The AutoMapper JSON streamer, which hands back a fully
-> mapped object up front, is actually *faster* than the stock streamer once both
-> produce a usable object.
-
-Note the two JSON streamers are an order of magnitude slower than plain `map()` for a
-single object: they exist to stream **large collections** at flat memory (see below),
-and pay a heavy per-call overhead that only amortizes over big inputs. For single
-objects, `map()` + native `json_decode` is the right tool.
+| AutoMapper, no checking (`json_decode` + map) | ~5.8 µs |
+| AutoMapper JSON streamer, no attribute checking | ~8.2 µs |
+| AutoMapper (`json_decode` + map) | ~10.6 µs |
+| AutoMapper JSON streamer | ~13.5 µs |
+| Symfony JSON streamer | ~156 µs |
+| Symfony Serializer | ~169 µs |
+
+The AutoMapper JSON streamer is now **~11× faster than Symfony's** on this shape, and
+within ~1.3× of a plain `json_decode` + `map()`. It reads straight from the decoded
+document through a generated `json` → class mapper, so nothing is materialized twice.
+
+> **Fairness note.** Symfony's `JsonStreamReader::read()` on a `Type::object` returns a
+> *lazy ghost* whose hydration is deferred until a property is read, so a subject that
+> never touched the result would clock ~13 µs while actually doing almost nothing.
+> Reading the whole graph forces that deferred work.
 
 ### Single object — serialize (object → JSON)
 
 | Approach | Time |
 |----------|-----:|
-| `json_encode` (array only, no traversal — *pure floor*) | ~0.8 µs |
-| **Manual** (hand-written normalization + `json_encode` — *fair floor*) | ~1.2 µs |
-| AutoMapper, no attribute checking (map + `json_encode`) | ~3.9 µs |
-| AutoMapper JSON streamer, no attribute checking | ~8 µs |
-| Symfony JSON streamer | ~9 µs |
-| AutoMapper (map + `json_encode`) | ~10 µs |
-| AutoMapper JSON streamer | ~14 µs |
-| Symfony Serializer | ~66 µs |
-
-The AutoMapper JSON streamer writer was ~25 µs here until its `__toString()` was
-changed to encode the lazy structure in one native `json_encode` call (both
-`LazyMap` and `LazyCollection` are `JsonSerializable`) instead of concatenating
-hand-built chunks — a ~1.85× speed-up (2.5× with attribute checking off), with
-byte-identical output. Chunk streaming is still used when the result is *iterated*
-(`getIterator`), for callers writing to an output stream.
-
-The **manual** row is the fair baseline: it produces/consumes the same `Person`
-graph the libraries do, just by hand (see `src/ManualMapper.php`). The pure
-`json_*` rows never touch a `Person`, so they only show the JSON cost in isolation.
+| **Manual** (hand-written normalization + `json_encode` — *fair floor*) | ~1.3 µs |
+| AutoMapper, no attribute checking (map + `json_encode`) | ~3.6 µs |
+| AutoMapper, no checking (map + `json_encode`) | ~3.8 µs |
+| AutoMapper JSON streamer, no attribute checking | ~7.4 µs |
+| Symfony JSON streamer | ~9.2 µs |
+| AutoMapper (map + `json_encode`) | ~9.5 µs |
+| AutoMapper JSON streamer | ~14.2 µs |
+| Symfony Serializer | ~69 µs |
+
+The **manual** row is the fair baseline: it produces/consumes the same `Person` graph
+the libraries do, just by hand (see `src/ManualMapper.php`).
 
 ### Object to object
 
 | Approach | Time |
 |----------|-----:|
-| Manual (hand-written) | ~0.2 µs |
+| Manual (hand-written) | ~0.23 µs |
 | AutoMapper, no attribute checking | ~1.6 µs |
-| AutoMapper | ~4.9 µs |
-| AutoMapper ObjectMapper bridge | ~5.4 µs |
-| Symfony ObjectMapper | ~48 µs (**~10× slower**) |
-
-### Collection — peak memory (the headline)
-
-Reading a JSON array of `Person` objects, **every object fully hydrated** (the loop
-reads a nested field so each library does the same work — see the note below).
-Peak memory (`mem_peak`) and time for 20 000 items:
-
-| Approach | 1 000 items | 20 000 items | time (20k) |
-|----------|------------:|-------------:|-----------:|
-| `json_decode` (array only, no objects) | 11 MB | 90 MB | 0.10 s |
-| AutoMapper `mapCollection` (eager) | 14 MB | 107 MB | 0.29 s |
-| Symfony Serializer | 14 MB | 101 MB | 3.44 s |
-| Symfony JSON streamer, **iterable** (lazy) | 9.8 MB | **9.8 MB** | 4.11 s |
-| Symfony JSON streamer, `list` (materialized) | 43 MB | 681 MB | 4.50 s |
-| AutoMapper JSON streamer, buffered | 12 MB | 51 MB | 3.16 s |
-| AutoMapper JSON streamer, buffered, no attr checking | 12 MB | 51 MB | 2.96 s |
-| **AutoMapper JSON streamer, `STREAM` mode** | **9.8 MB** | **9.8 MB** | 3.06 s |
-| **AutoMapper JSON streamer, `STREAM`, no attr checking** | **9.8 MB** | **9.8 MB** | 3.11 s |
-
-Disabling attribute checking barely moves the streamer here (buffered 3.16 → 2.96 s,
-`STREAM` ~unchanged): unlike the plain `map()` path — where it's a ~2–3× win — the
-streamer's time is dominated by Symfony's userland JSON tokenizer decoding each
-element, so the AutoMapper mapping step it speeds up is only a small slice. Memory is
-identical, since attribute checking is a code-generation concern, not a runtime one.
-
-Both truly-streaming readers — Symfony's `iterable` shape and AutoMapper's `STREAM`
-mode — keep a **flat ~10 MB** peak regardless of collection size, because they yield
-one object at a time and never hold the whole collection in memory. Streaming trades
-throughput for memory: it is slower per element than the eager mappers, so use it
-when the input is large enough that memory — not wall time — is the constraint.
-AutoMapper's streaming reader is a little faster here and, unlike Symfony's raw
-reader, runs each element through the full AutoMapper pipeline (renames, transformers,
-`#[MapTo]`, private properties, discriminators, …).
+| AutoMapper | ~5.0 µs |
+| AutoMapper ObjectMapper bridge | ~5.5 µs |
+| Symfony ObjectMapper | ~49 µs (**~10× slower**) |
+
+### Collection — read a list of `Person` (`src/CollectionBench.php`)
+
+Reading a JSON array of `Person`, **every object fully hydrated** (the loop reads a
+nested field so each library does the same work). Peak memory (`mem_peak`) and time:
+
+| Approach | 1 000 | 20 000 | time (20k) |
+|----------|------:|-------:|-----------:|
+| `json_decode` (array only, no objects) | 14 MB | 93 MB | 0.09 s |
+| AutoMapper `mapCollection`, no checking (eager) | 16 MB | 108 MB | 0.21 s |
+| AutoMapper `mapCollection` (eager) | 15 MB | 107 MB | 0.29 s |
+| **AutoMapper JSON streamer, `STREAM`, no checking** | 11 MB | **21 MB** | **0.15 s** |
+| **AutoMapper JSON streamer, `STREAM`** | 11 MB | **21 MB** | 0.25 s |
+| AutoMapper JSON streamer, buffered, no attr checking | 18 MB | 183 MB | 0.25 s |
+| AutoMapper JSON streamer, buffered | 18 MB | 183 MB | 0.37 s |
+| Symfony Serializer | 14 MB | 101 MB | 3.45 s |
+| Symfony JSON streamer, **iterable** (lazy) | 10 MB | **10 MB** | 4.14 s |
+| Symfony JSON streamer, `list` (materialized) | 43 MB | 682 MB | 4.82 s |
+
+This is where the `json` source pays off the most: streaming through the AutoMapper is
+**~16–27× faster than Symfony's streamer** (0.15–0.25 s vs 4.14 s) while staying within
+~2× of its memory, and it is *also faster than eagerly decoding the whole array* with
+`mapCollection`. Unlike on the read path before, disabling the checks now matters again
+(0.25 s → 0.15 s), because the decoding is no longer the bottleneck.
+
+Use `STREAM` for large inputs: buffered mode memoizes every mapped object (183 MB at
+20k) to stay countable and re-iterable, while `STREAM` keeps a bounded peak at the cost
+of being single-pass.
 
 #### `iterable` vs `list`: the type drives whether Symfony actually streams
 
-The same JSON array read by the same reader costs **~10 MB or ~680 MB** depending
-only on the requested type:
+The same JSON array read by the same Symfony reader costs **~10 MB or ~682 MB**
+depending only on the requested type:
 
 - **`Type::iterable(Type::object(Person::class), Type::int())`** → `read()` returns a
   `Generator` that decodes and yields one hydrated `Person` at a time. Flat, ~10 MB.
 - **`Type::list(Type::object(Person::class))`** → the generated reader ends with
   `iterator_to_array(...)`, materializing the whole collection. Each element is a
   `ReflectionClass::newLazyGhost()` whose initializer closure captures its own
   *suspended* boundary generator (lexer + stream state). At 20 000 elements that is
-  ~20 000 ghosts + ~20 000 live generators retained at once — ~30 KB each, hence the
-  ~679 MB peak. It holds even if the ghosts are never hydrated. **Prefer `iterable`.**
+  ~20 000 ghosts + ~20 000 live generators retained at once. It holds even if the
+  ghosts are never hydrated. **Prefer `iterable`.**
 
 The `int` key type is what tells Symfony to read a JSON array (`[…]`) rather than an
 object (`{…}`) — omit it and the reader expects `{…}` and throws on a list.
 
-> **Fairness note.** The `list` reader returns lazy ghosts, so a benchmark loop that
-> never reads a property would measure it deferring all the hydration work the
-> other mappers do up front. Every subject in `CollectionBench` therefore reads
-> `$person->address->city` to force full realization, so timings are comparable.
+### Collection — write a list of `Person` (`src/WriteCollectionBench.php`)
 
-> The `STREAM` option (`AutoMapper\MapperContext::STREAM => true`) also makes the
-> collection single-pass (it cannot be re-iterated). Without it, the reader buffers
-> mapped instances so the collection is countable and re-iterable, at the cost of
-> holding them all in memory.
-
-### Collection — write, a list of `Person` (`src/WriteCollectionBench.php`)
-
-The write-side counterpart of the read collection: serialize a list of `Person` to
-JSON, comparing the two JSON stream **writer** implementations. AutoMapper's writer
-now handles a top-level list of objects (it maps each element through the AutoMapper
-pipeline and streams the JSON array; with `STREAM=true` it never buffers the mapped
-elements). Peak memory (`mem_peak`) and time:
+Serializing a list of `Person` (fed from a generator) to JSON, comparing the two JSON
+stream **writer** implementations:
 
 | Writer / consumption | 1 000 | 20 000 | time (20k) |
 |----------------------|------:|-------:|-----------:|
-| AutoMapper JSON streamer — `__toString()` (buffered) | 15 MB | 180 MB | 0.63 s |
-| **AutoMapper JSON streamer — `STREAM=true` (streamed)** | 8.3 MB | 37 MB | 0.49 s |
-| Symfony JSON streamer — `__toString()` | 8.6 MB | 45 MB | 0.10 s |
-| **Symfony JSON streamer — `getIterator()` (streamed)** | **8.3 MB** | **36 MB** | **0.07 s** |
+| **Symfony JSON streamer — `getIterator()` (streamed)** | **7.2 MB** | **7.2 MB** | **0.10 s** |
+| Symfony JSON streamer — `__toString()` | 7.5 MB | 16 MB | 0.12 s |
+| AutoMapper `mapCollection` + `json_encode` (eager) | 11 MB | 77 MB | 0.14 s |
+| **AutoMapper JSON streamer — `STREAM=true` (streamed)** | 7.8 MB | **7.8 MB** | 0.15 s |
+| AutoMapper JSON streamer — `__toString()` | 8.2 MB | 17 MB | 0.17 s |
 
-Streamed, AutoMapper reaches the **same flat memory as Symfony** (~37 MB at 20k —
-essentially just the source list) but is **~6× slower** (0.49 s vs 0.07 s), the same
-per-element gap as the wide-object case. Buffered `__toString()` is worse still —
-~180 MB, because it resolves the whole list into an array-of-arrays before encoding,
-whereas Symfony encodes straight from the objects (~45 MB). So AutoMapper's list
-writer is worth it only when you need AutoMapper's mapping on the way out *and* want
-bounded memory (use `STREAM`); for a plain list, Symfony's writer is far faster.
+Both streamed writers keep a **flat peak** whatever the collection size, and the
+AutoMapper one is now within ~1.5× of Symfony's while running every element through the
+full mapping pipeline. The eager `mapCollection` + `json_encode` path is comparable in
+time but allocates the whole array-of-arrays (77 MB at 20k).
 
-### Collection — write, one object with a big nested collection (`src/WriteWideObjectBench.php`)
+### Collection — write one object with a big nested collection (`src/WriteWideObjectBench.php`)
 
-This is the only shape that exercises the **AutoMapper** JSON stream writer's own
-streaming (a single `Person` whose `addresses` is huge). The `STREAM` option applies
-on the way out. Peak memory (`mem_peak`):
+A single `Person` whose `addresses` is huge, so the nested collection is what streams:
 
 | Writer / consumption | 5 000 | 50 000 | time (50k) |
 |----------------------|------:|-------:|-----------:|
-| AutoMapper — `__toString()` (buffered) | 18 MB | 113 MB | 0.17 s |
-| AutoMapper — `__toString()`, no attr checking | 18 MB | 113 MB | 0.11 s |
-| AutoMapper — `getIterator()` `STREAM=true` | 8.9 MB | 23 MB | 0.21 s |
-| AutoMapper — `getIterator()` `STREAM=true`, no attr | 8.9 MB | 23 MB | 0.16 s |
-| **Symfony JSON streamer — `__toString()`** | 9 MB | 27 MB | **0.047 s** |
-| **Symfony JSON streamer — `getIterator()`** | **8.9 MB** | **23 MB** | **0.036 s** |
-
-`STREAM=true` yields the JSON chunk by chunk and never buffers the mapped
-collection, so peak stays low (the residual ~23 MB at 50k is the source object's own
-materialized `addresses` array). It is single-pass. Disabling attribute checking
-gives a **real ~30 % write-side speed-up** here (unlike the read side), because
-encoding is pure AutoMapper — map to a lazy array, then `json_encode`/chunk — with no
-Symfony JSON tokenizer in the path to dominate the time.
-
-#### Why Symfony's writer is so much faster at collection scale
-
-For a *single* small object the two writers look close (single-object serialize:
-AutoMapper JSON writer ~14 µs vs Symfony ~9 µs), so the collection gap seems
-surprising. It comes down to **per-element cost**, which a collection multiplies by
+| **Symfony JSON streamer — `getIterator()`** | **9.5 MB** | **23 MB** | **0.038 s** |
+| Symfony JSON streamer — `__toString()` | 9.8 MB | 27 MB | 0.047 s |
+| AutoMapper — `getIterator()` `STREAM=true`, no attr | 9.5 MB | 23 MB | 0.052 s |
+| AutoMapper — `__toString()`, no attr checking | 9.8 MB | 27 MB | 0.062 s |
+| AutoMapper — `getIterator()` `STREAM=true` | 9.5 MB | 23 MB | 0.10 s |
+| AutoMapper — `__toString()` (buffered) | 9.8 MB | 27 MB | 0.11 s |
+
+Memory is now **identical to Symfony** in both consumption modes: the nested collection
+is streamed through the sub-mappers instead of being encoded whole. Disabling attribute
+checking gives a **~2× write-side speed-up** here, because encoding is pure AutoMapper
+with no decoding in the path.
+
+#### Why Symfony's writer is still faster at collection scale
+
+For a *single* small object the two writers are close (serialize: ~14 µs vs ~9 µs), so
+the collection gap comes down to **per-element cost**, which a collection multiplies by
 `N`. Measured marginal cost per extra nested element:
 
-| | fixed (0 elements) | per element |
-|---|------:|------:|
-| AutoMapper writer (`STREAM`) | ~15 µs | **~4.0 µs** |
-| Symfony writer (`getIterator`) | ~7 µs | **~0.8 µs** |
-
-So AutoMapper pays ~5× more *per element*. At single-object scale that gap is a fixed
-~8 µs that's easy to miss; at 50 000 elements it becomes 50 000 × ~3.2 µs ≈ 160 ms —
-the whole difference. The reason: for each element AutoMapper builds a `LazyMap`,
-runs the per-item mapping closure, `iterator_to_array()`s it, then `json_encode`s
-each scalar field and yields it through nested generators. Symfony's compiled,
-type-specialized writer inlines the field encoding straight from the object with none
-of that per-element machinery. Reach for the AutoMapper JSON writer when you need its
-mapping features (renames, transformers, `#[MapTo]`, …) on the way out; for a plain
-object graph, Symfony's writer is the faster tool.
+| | per element |
+|---|------:|
+| AutoMapper writer (`STREAM`) | **~2.2 µs** |
+| Symfony writer (`getIterator`) | **~0.9 µs** |
+
+AutoMapper pays ~2.4× more per element (it was ~5× before the generated `json` mappers
+replaced the lazy-structure walk). Symfony emits from a compiled, type-specialized
+writer that reads fields straight off the object; the AutoMapper one additionally runs
+each element through the mapping pipeline. Reach for it when you need that pipeline
+(renames, transformers, `#[MapTo]`, private properties, discriminators, …); for a plain
+object graph with no mapping, Symfony's writer is still the faster tool.
+
+### The `json_stream` extension matters on the read path
+
+`json_stream_decode()` comes either from the
+[`json_stream` PHP extension](https://github.com/joelwurtz/php-json-stream) or from the
+pure-PHP [polyfill](https://github.com/joelwurtz/php-json-stream-polyfill) that ships
+with the AutoMapper. Same single-object read, same code:
+
+| Decoder | Time |
+|---------|-----:|
+| `json_stream` extension | ~14 µs |
+| polyfill (pure PHP) | ~93 µs |
+
+That is a **~6.7× difference on the read path**, so all the read numbers above assume
+the extension. Install it with [pie](https://github.com/php/pie):
+
+```shell
+pie install joelwurtz/json-stream
+```
+
+The write path does not decode anything and is unaffected.