Document BDR factory and PostFetch in README

Author: koriym

README.md

@@ -78,11 +78,129 @@ The return type of the interface method selects how the HTTP response is handled
 | `string`                | Raw response body                   |
 | PSR-7 `MessageInterface`| The HTTP message object             |
 
+### Mapping responses to a domain object
+
+Instead of a raw array, a method can return typed, immutable domain objects.
+Give `#[WebQuery]` a `factory` (and a `type`) — this is the same factory
+mechanism `ray/media-query` provides for `#[DbQuery]`, applied to HTTP
+responses.
+
+```php
+<?php
+use Ray\MediaQuery\Annotation\WebQuery;
+
+interface ProductApiInterface
+{
+    #[WebQuery('product_item', type: 'row', factory: ProductFactory::class)]
+    public function get(string $id): Product;
+
+    #[WebQuery('product_list', factory: ProductFactory::class)]
+    /** @return array<Product> */
+    public function list(string $status): array;
+}
+```
+
+The factory is resolved through the DI injector, so it can depend on domain
+services and apply business logic while building the object:
+
+```php
+<?php
+final class ProductFactory
+{
+    public function __construct(
+        private TaxCalculator $tax,
+    ) {
+    }
+
+    public function factory(string $name, int $price): Product
+    {
+        return new Product($name, $this->tax->applyTax($price));
+    }
+}
+
+final class Product
+{
+    public function __construct(
+        public readonly string $name,
+        public readonly int $price,
+    ) {
+    }
+}
+```
+
+The decoded JSON is passed to the factory method as **named arguments**: each
+JSON key is matched to a parameter by name, unknown keys are ignored, and a
+missing required argument throws `InvalidWebFactoryKeyException`. (This is the
+web counterpart of media-query's positional `PDO::FETCH_FUNC` binding.)
+
+`type` selects single object vs. list:
+
+| `type`       | JSON response            | Result          |
+|--------------|--------------------------|-----------------|
+| `'row'`      | object `{...}`           | one object      |
+| `'row_list'` | array `[{...}, {...}]`   | `array<Object>` |
+
+`type` defaults to `'row_list'`. A `'row'` method whose response is a list
+takes the first element; a `'row_list'` method whose response is a single
+object wraps it into a one-element list.
+
+You can also map straight to an entity **without** a factory: when the return
+type (or the `@return array<Entity>` docblock) is a class, each response is
+hydrated through the entity constructor — or through public properties if the
+class has no constructor.
+
+```php
+#[WebQuery('product_item', type: 'row')]
+public function get(string $id): Product; // built via Product::__construct
+```
+
+### Composing results with PostFetch
+
+To wrap or aggregate the fetched objects into another type (totals, metadata,
+…), let the return type implement `PostFetchInterface`. Its static
+`fromContext()` receives the fetch result and returns the final object. It runs
+after the factory, carries no dependencies by design, and is the web analogue
+of media-query's `PostQueryInterface` (named *PostFetch* because a web call is a
+single fetch, with no multi-statement query context to span).
+
+```php
+<?php
+use Ray\MediaQuery\PostFetchContext;
+use Ray\MediaQuery\PostFetchInterface;
+
+final class ProductList implements PostFetchInterface
+{
+    /** @param array<Product> $items */
+    public function __construct(
+        public readonly array $items,
+        public readonly int $total,
+    ) {
+    }
+
+    public static function fromContext(PostFetchContext $context): static
+    {
+        /** @var array<Product> $items */
+        $items = is_array($context->result) ? $context->result : [];
+
+        return new self($items, count($items));
+    }
+}
+```
+
+```php
+#[WebQuery('product_list', factory: ProductFactory::class)]
+public function listAggregate(string $status): ProductList;
+```
+
+`PostFetchContext` exposes the fetch `result`, the original method arguments
+(`query`), and the `#[WebQuery]` annotation (`webQuery`).
+
 ## Features
 
 - **Web API Queries**: Execute HTTP requests via interface methods
 - **URI Template Support**: Dynamic URL parameter binding with `{param}` syntax
 - **Multiple Response Types**: JSON array, string, or PSR-7 message
+- **Domain Object Mapping (BDR)**: Map responses to typed domain objects via an injectable factory, with optional `PostFetch` composition
 - **Parameter Injection**: Automatic parameter conversion and injection
 - **HTTP Client Integration**: Built on the Guzzle HTTP client