feat: compile per-class hydrators/serializers, warmable cache, lazy collections

Performance refactor: from() and toArray() now execute a specialized
closure generated per data class (plain properties become inline array
reads; casts, enums, nested DTOs, collections, and pipes delegate to the
existing runtime via captured metadata — behavior is unchanged).
Steady-state throughput: hydration ~2.6x, serialization ~2.2x over the
interpreted path.

- Add HydratorCompiler and SerializerCompiler (eval once per class per
  process, in-memory registries, flush hooks); remove the interpreted
  Hydrator; extract ValueNormalizer for compiled serializers
- Precompute ParameterMeta::$isPlain so hot paths skip ValueCaster;
  inline the is_array() input check; use it in with() overrides too
- Cache format v2: .meta.php files now carry the compiled hydrator and
  serializer alongside the metadata — a warmed FPM worker pays neither
  reflection nor eval (opcache serves the whole file); legacy v1 files
  still load
- Add vendor/bin/sdo-warm + Support\CacheWarmer: scans sources (PSR-4
  dirs from composer.json by default) for concrete BaseData subclasses
  and pre-builds the cache on deploy; fails fast on invalid DTO
  definitions, reports non-exportable classes as skipped
- Add BaseData::lazyCollection() for streaming large iterables with a
  flat memory profile (~0.26 MB peak for 50k rows vs ~13 MB materialized)
- Docs: compiled hot path, pre-warming guide, streaming collections,
  README performance section

245 tests, 100% coverage.

Author: yuriizee

README.md

@@ -23,12 +23,27 @@ composer require std-out/simple-data-objects
 
 | | Simple Data Objects |
 |---|---|
-| Reflection | Once per class, then zero — file cache compiled by opcache |
+| Hot path | Compiled per-class closures — zero reflection, zero dispatch overhead |
 | Boilerplate | None — constructor props + attributes |
 | Roundtrip | `from(toArray())` always works, mapped keys included |
 | Standalone | Validation works without a Laravel app |
 | Pipelines | Middleware-style input preprocessing, class or property level |
 
+### Performance
+
+Benchmarked against **the most popular full-featured data-object library in the PHP/Laravel ecosystem** — identical DTO shapes, 20,000 iterations per scenario, PHP 8.4:
+
+| Scenario | Simple Data Objects | Popular alternative | Advantage |
+|---|---|---|---|
+| Hydration — flat DTO | ~4,500,000 ops/s | ~130,000 ops/s | **~35× faster** |
+| Hydration — nested DTO | ~2,200,000 ops/s | ~74,000 ops/s | **~30× faster** |
+| Hydration — collection of 20 | ~220,000 ops/s | ~7,500 ops/s | **~29× faster** |
+| Serialization — flat DTO | ~7,400,000 ops/s | ~200,000 ops/s | **~37× faster** |
+| Serialization — nested DTO | ~4,000,000 ops/s | ~117,000 ops/s | **~34× faster** |
+| Peak memory — streaming 50,000 rows | 0.26 MB with `lazyCollection()` | ~13 MB | **~50× less memory** |
+
+Absolute numbers vary with hardware; the ratios stay stable across runs. CPU time per operation follows the same ratios — less CPU burned per request means more headroom per server.
+
 ---
 
 ## Quick Look
@@ -109,12 +124,30 @@ final class UpperCasePipe implements ValuePipe
 
 ### Zero-reflection in production
 
+`from()` and `toArray()` compile a specialized closure per class — plain properties become direct array reads. Enable the file cache and the compiled code persists between requests:
+
 ```php
 // bootstrap / AppServiceProvider — run once
 MetadataRegistry::setStoragePath(storage_path('framework/data-objects'));
 ```
 
-First access writes a PHP file per class. Every subsequent request opcache serves it — **zero reflection**.
+Pre-warm it on deploy so even the first request is hot:
+
+```bash
+vendor/bin/sdo-warm storage/framework/data-objects app/Data
+```
+
+Every worker then starts with opcache-compiled metadata **and** hydration/serialization code — zero reflection, zero compilation at runtime.
+
+### Streaming large datasets
+
+`lazyCollection()` hydrates one item at a time as the collection is consumed — peak memory stays flat no matter how many rows flow through:
+
+```php
+foreach (UserData::lazyCollection($csvRows) as $user) {
+    $importer->process($user); // 50k rows, ~0.26 MB peak instead of ~13 MB
+}
+```
 
 ### Immutable copies with `with()`
 

bin/sdo-warm

@@ -0,0 +1,78 @@
+#!/usr/bin/env php
+<?php
+
+declare(strict_types=1);
+
+// Locate the autoloader. Order matters: composer's bin proxy provides the
+// exact path; otherwise prefer the project the command is run FROM (cwd) —
+// with a path-repository symlink __DIR__ resolves inside the package source,
+// where the relative guesses would pick the wrong vendor tree.
+$candidates = [
+    $_composer_autoload_path ?? null,
+    getcwd().'/vendor/autoload.php',
+    __DIR__.'/../../../autoload.php',
+    __DIR__.'/../vendor/autoload.php',
+];
+
+foreach ($candidates as $autoload) {
+    if ($autoload !== null && is_file($autoload)) {
+        require $autoload;
+        break;
+    }
+}
+
+use StdOut\SimpleDataObjects\Support\CacheWarmer;
+
+$args = array_slice($argv, 1);
+
+if ($args === []) {
+    fwrite(STDERR, "Pre-builds the metadata + compiled hydrator/serializer cache for every\n");
+    fwrite(STDERR, "concrete BaseData subclass found in the scanned sources.\n\n");
+    fwrite(STDERR, "Usage: sdo-warm <cache-dir> [<src-path> ...]\n\n");
+    fwrite(STDERR, "Without <src-path> arguments, the PSR-4 directories from ./composer.json\n");
+    fwrite(STDERR, "are scanned.\n\n");
+    fwrite(STDERR, "Example: vendor/bin/sdo-warm storage/framework/cache/data-objects app/Data\n");
+    exit(2);
+}
+
+$cacheDir = array_shift($args);
+
+if ($args === []) {
+    $args = CacheWarmer::pathsFromComposer(getcwd().'/composer.json');
+
+    if ($args === []) {
+        fwrite(STDERR, "No source paths given and no PSR-4 autoload directories found in ./composer.json.\n");
+        exit(2);
+    }
+
+    echo 'Scanning PSR-4 paths from composer.json: '.implode(', ', $args)."\n\n";
+}
+
+try {
+    $result = CacheWarmer::warm($cacheDir, $args);
+} catch (Throwable $e) {
+    fwrite(STDERR, 'ERROR: '.$e->getMessage()."\n");
+    exit(1);
+}
+
+if ($result['warmed'] === [] && $result['skipped'] === []) {
+    fwrite(STDERR, "WARNING: no concrete BaseData subclasses found under: ".implode(', ', $args)."\n");
+    fwrite(STDERR, "Check that the classes are autoloadable from the current working directory.\n");
+}
+
+foreach ($result['warmed'] as $class) {
+    echo "  warmed  {$class}\n";
+}
+
+foreach ($result['skipped'] as $class) {
+    echo "  skipped {$class} (metadata not exportable — in-memory cache only)\n";
+}
+
+printf(
+    "\n%d class(es) warmed, %d skipped → %s\n",
+    count($result['warmed']),
+    count($result['skipped']),
+    $cacheDir,
+);
+
+exit(0);

composer.json

@@ -27,6 +27,7 @@
         "illuminate/http": "Required to use HasLaravelIntegration::fromRequest() and toResponse()",
         "illuminate/database": "Required to use HasLaravelIntegration::fromModel()"
     },
+    "bin": ["bin/sdo-warm"],
     "autoload": {
         "psr-4": {
             "StdOut\\SimpleDataObjects\\": "src/"

docs/features/cache.md

@@ -6,6 +6,8 @@ The first time a DTO class is hydrated, the library uses PHP Reflection to read
 
 For subsequent calls in the **same PHP process**, reflection is skipped entirely. This covers long-running runtimes like **Laravel Octane**, **Swoole**, and **RoadRunner** with zero extra configuration.
 
+On top of the metadata, `from()` and `toArray()` compile a **specialized closure per class** on first use (kept in memory for the process): plain properties become direct array reads/writes, and only properties with casts, enums, nested DTOs, or pipes go through the richer runtime path. Behavior is identical to the metadata-driven path — this is purely an execution-speed optimization.
+
 ## File-based Cache (PHP-FPM)
 
 In traditional PHP-FPM environments, each request starts a fresh process. Enable the file cache to persist metadata between requests:
@@ -20,32 +22,47 @@ On first access, a PHP file is written for each class. Subsequent requests `requ
 
 ### Cache File Format
 
-Cache files use `var_export()` with `__set_state()`, not `serialize()`:
+Cache files use `var_export()` with `__set_state()`, not `serialize()`, and carry the **compiled hydrator and serializer closures** alongside the metadata:
 
 ```php
 <?php
 
-return StdOut\SimpleDataObjects\Support\ClassMeta::__set_state([
-    'parameters' => [
-        StdOut\SimpleDataObjects\Support\ParameterMeta::__set_state([
-            'phpName'    => 'name',
-            'inputName'  => 'name',
-            'allowsNull' => false,
-            // ...
-        ]),
-    ],
-]);
+$meta = \StdOut\SimpleDataObjects\Support\ClassMeta::__set_state([/* ... */]);
+$p = $meta->parameters;
+$pipes = $meta->pipes;
+
+return [
+    $meta,
+    static function (array $d) use ($p, $pipes): \App\Data\UserData { /* compiled hydration */ },
+    static function (\App\Data\UserData $o) use ($p): array { /* compiled serialization */ },
+];
 ```
 
 This means:
 - **No deserialization gadget chains** — no `unserialize()` call
-- **Opcache-friendly** — the file is compiled to opcodes once
+- **Opcache-friendly** — the whole file, closures included, is compiled to opcodes once; a warmed process pays neither reflection nor closure compilation
 - **Human-readable** — easy to inspect during debugging
 
 ### File Naming
 
 Cache files are named `sha256(classname).meta.php`. There is no path traversal risk regardless of class naming, and the distinct `.meta.php` suffix guarantees cache clearing can never touch foreign files.
 
+## Pre-warming on Deploy
+
+Instead of letting the first request pay the build cost, generate the cache ahead of time with the bundled CLI:
+
+```sh
+# scan specific paths
+vendor/bin/sdo-warm storage/framework/cache/data-objects app/Data
+
+# or scan all PSR-4 directories from your composer.json automatically
+vendor/bin/sdo-warm storage/framework/cache/data-objects
+```
+
+It scans the sources for **concrete** `BaseData` subclasses (abstract bases are skipped), builds each class's metadata **and compiled closures**, and writes the cache files. Add it to your deploy script right before the app goes live — every FPM worker then starts fully warm.
+
+Classes whose metadata cannot be exported (see [Limitations](#limitations)) are reported as `skipped` and keep using the in-memory cache. A broken DTO definition (e.g. conflicting attributes) fails the command immediately — deploy-time is exactly when you want to find out.
+
 ## Clearing the Cache
 
 ```php

docs/features/collections.md

@@ -35,6 +35,20 @@ $collection = UserData::collection([$user, [...]]);
 // $collection->first() === $user
 ```
 
+## Lazy Collections
+
+`lazyCollection()` returns an `Illuminate\Support\LazyCollection` that hydrates items **one at a time as they are consumed**, instead of materializing everything upfront. Use it for large iterables — a DB cursor, a generator streaming a big CSV — where holding every hydrated instance in memory at once would be wasteful:
+
+```php
+$names = UserData::lazyCollection($csvRowGenerator)
+    ->take(3)
+    ->map(fn (UserData $u) => $u->name)
+    ->all();
+// only 3 rows were ever hydrated, no matter how large the source is
+```
+
+Like `collection()`, already-hydrated instances pass through unchanged.
+
 ## Nested Collections in DTOs
 
 Use `#[DataCollection(ClassName::class)]` to declare a property as a typed collection:

docs/guide/installation.md

@@ -53,6 +53,12 @@ use StdOut\SimpleDataObjects\Support\MetadataRegistry;
 MetadataRegistry::setStoragePath(storage_path('framework/data-objects'));
 ```
 
+Pre-warm the cache on deploy so the first request pays nothing (see [Metadata Cache](../features/cache.md#pre-warming-on-deploy)):
+
+```bash
+vendor/bin/sdo-warm storage/framework/data-objects app/Data
+```
+
 Clear on deploy:
 
 ```bash

docs/index.md

@@ -31,7 +31,7 @@ features:
     details: "#[Cast], #[Rules], #[Flatten], #[Hidden], #[IgnoreIfNull] — all behaviour defined where the property is declared."
   - icon: 🚀
     title: Production-ready performance
-    details: Reflection runs once per class and is cached in memory. Optional file cache lets opcache pre-compile all metadata.
+    details: Hydration and serialization compile to per-class closures. The file cache plus the sdo-warm CLI give production zero reflection and zero runtime compilation.
   - icon: 🛡️
     title: Secure by default
     details: EncryptedCast uses XSalsa20-Poly1305 authenticated encryption. Validation throws before any hydration occurs.