From 46971675af905cf1bac6b03bff8309e9783e2312 Mon Sep 17 00:00:00 2001
From: Priyadi Iman Nurcahyo <1102197+priyadi@users.noreply.github.com>
Date: Mon, 19 Feb 2024 16:23:07 +0700
Subject: [PATCH] docs: Improve sales pitch

---
 README.md | 65 ++++++++++++++++++++++++++++++++++++++-----------------
 1 file changed, 45 insertions(+), 20 deletions(-)

diff --git a/README.md b/README.md
index d8b6b3bc..dc16368f 100644
--- a/README.md
+++ b/README.md
@@ -63,43 +63,66 @@ a few keystrokes.
 
 ## Features
 
+### General
+
 * Automatically lists the properties of the source and target, detects their
   types, and maps them accordingly.
-* By default, does not attempt to circumvent your class constraints. Reads only
-  from and writes only to public properties, getters, setters. Does not
-  instantiate objects without their constructor.
-* Override the mapping logic using a custom property mapper.
+* Reads the type from PHP type declaration and PHPDoc annotations, including
+  the type of the nested objects.
+* Does not attempt to circumvent your class constraints. Reads only from and
+  writes only to public properties, getters, setters. Does not instantiate
+  objects without their constructor.
 * Constructor initialization.
 * Handles nested objects.
 * Handles recursion and circular references.
 * Inheritance support. Maps to abstract classes and interfaces using an
   inheritance map attribute.
-* Reads the type from PHP type declaration and PHPDoc annotations, including
-  the type of the nested objects.
+
+### Custom Mapping
+
+* Override the mapping of a specific property using a custom property mapper.
+* Override the mapping between two specific classes using a custom object
+  mapper.
+* Extend the mapper by creating new transformers, or decorating the existing
+  ones.
+* Match classes using attributes in your transformers, in addition to using
+  class names.
+
+### Object Lazy-Loading
+
 * If possible, target objects are lazy-loaded. The mapping does not take place
-  until the target is accessed.
+  until the target is accessed, and will never take place if it is never
+  accessed.
 * Attempts to detect identifier properties on the source side. Those properties
-  on the target side will be mapped eagerly, and will not trigger the hydration.
-  Thus, API Platform will be able to generate IRIs without causing the hydration
-  of the entire object graph.
-* Handles the mapping between `array` or array-like objects, as well as using an
-  adder method.
+  will be mapped eagerly to the target side, as they should not trigger the
+  hydration of the source. As an example, API Platform will be able to generate
+  IRIs without causing the hydration of the entire object graph.
+
+### Arrays and Array-Like Objects
+
+* Handles the mapping between `array` or array-like objects.
+* Handles adder methods on the target side.
 * Handles non-string & non-integer keys in array-like objects, including
   `SplObjectStorage`.
-* Lazy loading & lazy stream mapping with collection types. Consumes less memory
-  & avoids hydrating a Doctrine collection prematurely.
+
+### Array-Like Lazy-Loading
+
+* Lazy loading if the target is type-hinted with `ArrayAccess`, `Traversable` or
+  `CollectionInterface`. The target will not iterate the source object until it
+  is accessed, or never if it is never accessed.
+* Stream mapping. Maps the source members to the target side as they are being
+  iterated. This may consume less memory.
 * With lazy loading, if the source is a `Countable`, then the target will also
   be a `Countable`. With an extra-lazy Doctrine Collection, the consumer will be
   able to count the target without causing a full hydration of the source.
-* Manual mapping using a class method.
-* Easy to extend by creating new transformers, or decorating the existing ones.
-* Match classes using attributes in your transformers, in addition to using
-  class names.
+
+### Development Experience (DX)
+
 * Helpful exception messages.
 * Console commands for debugging.
 * Data collector and profiler integration.
 * Coded from the start using PHP 8, strict types, and maxed-out PHPStan and
-  Psalm.
+  Psalm level.
 
 ## To-Do List
 
@@ -110,7 +133,9 @@ a few keystrokes.
 * `MapFrom` and `MapTo` attributes.
 * Support `ramsey/uuid`
 * Improve non-framework usage.
-* Warm up proxies from the list of classes provided by the user.
+* Warm up proxies on build time from the list of classes provided by the user.
+* Lazy-loading using Doctrine `Collection` type hint on the target side.
+* `PresetTransformer`. Transforms objects using a predetermined table of values.
 
 ## Documentation