feature: introduce postgresql mapping context

Author: norberttech

documentation/components/libs/postgresql.md

@@ -370,6 +370,7 @@ The library ships two default mappers, both available via DSL functions, plus an
 | Mapper | Use for |
 | --- | --- |
 | [ConstructorMapper](/documentation/components/libs/postgresql/client-constructor-mapper.md) | Map row columns directly to constructor parameters by name (1:1). No type coercion. |
+| [StaticFactoryMapper](/documentation/components/libs/postgresql/client-static-factory-mapper.md) | Delegate row → object construction to a public static factory method (`self::fromRow(array $row)`). Useful when the target class has a private constructor or needs custom coercion inside the factory. |
 | [TypeMapper](/documentation/components/libs/postgresql/client-type-mapper.md) | Validate and coerce the row via [flow-php/types](/documentation/components/libs/types.md) (JSONB → structure, date string → `\DateTimeImmutable`, …). Optionally chains into another `RowMapper`. |
 | [PostgreSQL Valinor Bridge](/documentation/components/bridges/postgresql-valinor-bridge.md) ⚠️ | Strict object hydration of complex graphs via cuyz/valinor. **Requires the separate `flow-php/postgresql-valinor-bridge` package.** |
 
@@ -380,6 +381,8 @@ The library ships two default mappers, both available via DSL functions, plus an
 - [Fetching Data](/documentation/components/libs/postgresql/client-fetching.md) - fetch, fetchOne, fetchAll, fetchScalar
 - [ConstructorMapper](/documentation/components/libs/postgresql/client-constructor-mapper.md) - Map rows directly to
   constructor parameters
+- [StaticFactoryMapper](/documentation/components/libs/postgresql/client-static-factory-mapper.md) - Map rows via a
+  public static factory method on the target class
 - [TypeMapper](/documentation/components/libs/postgresql/client-type-mapper.md) - Validate and coerce rows via
   flow-php/types; chain into another mapper
 - [PostgreSQL Valinor Bridge](/documentation/components/bridges/postgresql-valinor-bridge.md) - Strict object

documentation/components/libs/postgresql/client-static-factory-mapper.md

@@ -0,0 +1,136 @@
+# StaticFactoryMapper
+
+- [⬅️ Back](/documentation/components/libs/postgresql.md)
+
+[TOC]
+
+`StaticFactoryMapper` delegates row → object construction to a **public static** factory method on the target class. Use it when:
+
+- The target class has a `private` constructor and a named static factory (`User::fromRow(...)`),
+- You want to keep row-to-object logic on the domain class itself instead of scattering it across mapper implementations,
+- You need custom coercion inside the factory (e.g. `created_at` string → `\DateTimeImmutable`, JSONB string → decoded array).
+
+The factory method **must** have this exact signature:
+
+```php
+public static function fromRow(array $row) : self;
+```
+
+The method **does not** receive the mapping `Context`. If your factory needs access to the originating `Query`, executing `Client`, or user-supplied data, implement [`RowMapper`](/documentation/components/libs/postgresql.md#row-mappers) directly — see the *Custom RowMapper* section of the [ConstructorMapper documentation](/documentation/components/libs/postgresql/client-constructor-mapper.md#custom-rowmapper).
+
+For simple 1:1 constructor-parameter mapping, use [`ConstructorMapper`](/documentation/components/libs/postgresql/client-constructor-mapper.md). For type-driven coercion via `flow-php/types`, use [`TypeMapper`](/documentation/components/libs/postgresql/client-type-mapper.md).
+
+## DSL
+
+```php
+static_factory_mapper(class-string<T> $class, non-empty-string $method) : StaticFactoryMapper<T>
+```
+
+Returns a `RowMapper<T>` ready for `fetchInto` / `fetchOneInto` / `fetchAllInto` / `Cursor::map()`.
+
+## Basic Usage
+
+```php
+<?php
+
+use function Flow\PostgreSql\DSL\{pgsql_client, pgsql_connection, static_factory_mapper};
+
+final readonly class User
+{
+    private function __construct(
+        public int $id,
+        public string $name,
+        public string $email,
+        public \DateTimeImmutable $createdAt,
+    ) {
+    }
+
+    /**
+     * @param array<string, mixed> $row
+     */
+    public static function fromRow(array $row) : self
+    {
+        return new self(
+            id: (int) $row['id'],
+            name: (string) $row['name'],
+            email: (string) $row['email'],
+            createdAt: new \DateTimeImmutable((string) $row['created_at']),
+        );
+    }
+}
+
+$client = pgsql_client(pgsql_connection('host=localhost dbname=mydb'));
+
+$user = $client->fetchOneInto(
+    static_factory_mapper(User::class, 'fromRow'),
+    'SELECT id, name, email, created_at FROM users WHERE id = $1',
+    [1],
+);
+```
+
+## fetchInto() — First Object or Null
+
+Returns the first row mapped via the factory, or `null` if no rows:
+
+```php
+<?php
+
+$user = $client->fetchInto(
+    static_factory_mapper(User::class, 'fromRow'),
+    'SELECT id, name, email, created_at FROM users WHERE email = $1',
+    ['john@example.com'],
+);
+```
+
+## fetchAllInto() — All Objects
+
+```php
+<?php
+
+/** @var User[] $users */
+$users = $client->fetchAllInto(
+    static_factory_mapper(User::class, 'fromRow'),
+    'SELECT id, name, email, created_at FROM users ORDER BY name',
+);
+
+foreach ($users as $user) {
+    echo $user->name;
+}
+```
+
+## Streaming via Cursor
+
+```php
+<?php
+
+$cursor = $client->cursor('SELECT id, name, email, created_at FROM large_users');
+
+foreach ($cursor->map(static_factory_mapper(User::class, 'fromRow')) as $user) {
+    processUser($user);
+}
+```
+
+See [Cursors](/documentation/components/libs/postgresql/client-cursor.md) for details.
+
+## Error Handling
+
+`StaticFactoryMapper` throws `Flow\PostgreSql\Client\Exception\MappingException` in these cases:
+
+| Condition                                         | Message pattern                                       |
+|---------------------------------------------------|-------------------------------------------------------|
+| `$class` does not exist                           | `Failed to map row to "<class>": Class does not exist`|
+| Factory method does not exist on `$class`         | `Static factory method "<class>::<method>()" does not exist` |
+| Factory method exists but is not declared `static`| `Factory method "<class>::<method>()" must be declared static` |
+| Factory method is declared but not `public`       | `Factory method "<class>::<method>()" must be declared public` |
+| Factory method throws any `\Throwable`            | `Failed to map row to "<class>": <original message>`, with the original exception available via `MappingException::getPrevious()` |
+
+Validation of `$class` / `$method` (existence, `static`, `public`) runs **eagerly in the constructor** — a misconfigured mapper fails fast at wiring time, not at query time. Exceptions thrown by the factory method itself surface on the matching `map()` call and are wrapped in a `MappingException` whose `getPrevious()` returns the original throwable.
+
+## When to Reach for Something Else
+
+| Need                                                                | Use                                                                                   |
+|---------------------------------------------------------------------|---------------------------------------------------------------------------------------|
+| 1:1 column-to-constructor-parameter mapping with no coercion        | [`ConstructorMapper`](/documentation/components/libs/postgresql/client-constructor-mapper.md) |
+| Row validation / coercion via `flow-php/types`                      | [`TypeMapper`](/documentation/components/libs/postgresql/client-type-mapper.md)       |
+| Access to `Context` (query / parameters / client / catalog) in your mapping logic | Implement [`RowMapper`](/documentation/components/libs/postgresql.md#row-mappers) directly |
+| Strict object hydration of complex graphs                           | [PostgreSQL Valinor Bridge](/documentation/components/bridges/postgresql-valinor-bridge.md) |

src/lib/postgresql/src/Flow/PostgreSql/Client/Exception/MappingException.php

@@ -6,6 +6,21 @@
 
 final class MappingException extends ClientException
 {
+    public static function factoryMethodNotFound(string $class, string $method) : self
+    {
+        return new self(\sprintf('Static factory method "%s::%s()" does not exist', $class, $method));
+    }
+
+    public static function factoryMethodNotPublic(string $class, string $method) : self
+    {
+        return new self(\sprintf('Factory method "%s::%s()" must be declared public', $class, $method));
+    }
+
+    public static function factoryMethodNotStatic(string $class, string $method) : self
+    {
+        return new self(\sprintf('Factory method "%s::%s()" must be declared static', $class, $method));
+    }
+
     public static function mappingFailed(string $class, string $reason, ?\Throwable $previous = null) : self
     {
         return new self(\sprintf('Failed to map row to "%s": %s', $class, $reason), 0, $previous);

src/lib/postgresql/src/Flow/PostgreSql/Client/RowMapper/ConstructorMapper.php

@@ -22,33 +22,42 @@
  */
 final readonly class ConstructorMapper implements RowMapper
 {
+    /** @var list<\ReflectionParameter> */
+    private array $parameters;
+
+    /** @var \ReflectionClass<T> */
+    private \ReflectionClass $reflection;
+
     /**
      * @param class-string<T> $class
+     *
+     * @throws MappingException
      */
     public function __construct(private string $class)
-    {
-    }
-
-    /**
-     * @return T
-     */
-    public function map(array $row, Context $context) : object
     {
         if (!\class_exists($this->class)) {
             throw MappingException::mappingFailed($this->class, 'Class does not exist');
         }
 
-        $reflection = new \ReflectionClass($this->class);
+        $this->reflection = new \ReflectionClass($this->class);
 
-        $constructor = $reflection->getConstructor();
+        $constructor = $this->reflection->getConstructor();
 
         if ($constructor === null) {
             throw MappingException::mappingFailed($this->class, 'Class has no constructor');
         }
 
+        $this->parameters = $constructor->getParameters();
+    }
+
+    /**
+     * @return T
+     */
+    public function map(array $row, Context $context) : object
+    {
         $args = [];
 
-        foreach ($constructor->getParameters() as $param) {
+        foreach ($this->parameters as $param) {
             $paramName = $param->getName();
 
             if (\array_key_exists($paramName, $row)) {
@@ -63,7 +72,7 @@ public function map(array $row, Context $context) : object
         }
 
         try {
-            return $reflection->newInstanceArgs($args);
+            return $this->reflection->newInstanceArgs($args);
         } catch (\Throwable $e) {
             throw MappingException::mappingFailed($this->class, $e->getMessage());
         }

src/lib/postgresql/src/Flow/PostgreSql/Client/RowMapper/StaticFactoryMapper.php

@@ -0,0 +1,69 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Flow\PostgreSql\Client\RowMapper;
+
+use Flow\PostgreSql\Client\Exception\MappingException;
+use Flow\PostgreSql\Client\RowMapper;
+
+/**
+ * Maps database rows to objects using a user-provided public static factory method.
+ *
+ * The factory method must:
+ * - be public,
+ * - be static,
+ * - accept a single parameter: array<string, mixed> $row,
+ * - return an instance of $class (or a subclass).
+ *
+ * If the factory needs access to the mapping Context (sql/parameters/client/catalog/user-data),
+ * implement Flow\PostgreSql\Client\RowMapper directly instead — this mapper intentionally hides Context.
+ *
+ * @template T of object
+ *
+ * @implements RowMapper<T>
+ */
+final readonly class StaticFactoryMapper implements RowMapper
+{
+    /**
+     * @param class-string<T> $class
+     * @param non-empty-string $method
+     *
+     * @throws MappingException
+     */
+    public function __construct(
+        private string $class,
+        private string $method,
+    ) {
+        if (!\class_exists($this->class)) {
+            throw MappingException::mappingFailed($this->class, 'Class does not exist');
+        }
+
+        if (!\method_exists($this->class, $this->method)) {
+            throw MappingException::factoryMethodNotFound($this->class, $this->method);
+        }
+
+        $reflection = new \ReflectionMethod($this->class, $this->method);
+
+        if (!$reflection->isStatic()) {
+            throw MappingException::factoryMethodNotStatic($this->class, $this->method);
+        }
+
+        if (!$reflection->isPublic()) {
+            throw MappingException::factoryMethodNotPublic($this->class, $this->method);
+        }
+    }
+
+    /**
+     * @return T
+     */
+    public function map(array $row, Context $context) : object
+    {
+        try {
+            /** @var T */
+            return $this->class::{$this->method}($row);
+        } catch (\Throwable $e) {
+            throw MappingException::mappingFailed($this->class, $e->getMessage(), $e);
+        }
+    }
+}

src/lib/postgresql/src/Flow/PostgreSql/DSL/client.php

@@ -10,7 +10,7 @@
 use Flow\PostgreSql\Client\{DsnParser, RowMapper};
 use Flow\PostgreSql\Client\Exception\ConnectionException;
 use Flow\PostgreSql\Client\Infrastructure\PgSql\PgSqlClient;
-use Flow\PostgreSql\Client\RowMapper\{ConstructorMapper, TypeMapper};
+use Flow\PostgreSql\Client\RowMapper\{ConstructorMapper, StaticFactoryMapper, TypeMapper};
 use Flow\PostgreSql\Client\Telemetry\{PostgreSqlTelemetryConfig, PostgreSqlTelemetryOptions, TraceableClient};
 use Flow\PostgreSql\Client\Types\{ValueConverters, ValueType};
 use Flow\PostgreSql\Schema\Catalog;
@@ -305,6 +305,26 @@ function type_mapper(FlowType $type, ?RowMapper $next = null) : TypeMapper
     return new TypeMapper($type, $next);
 }
 
+/**
+ * Create a row mapper backed by a public static factory method.
+ *
+ * The factory method must accept a single array<string, mixed> $row and return
+ * an instance of the target class. If your factory needs access to the mapping
+ * Context (sql/parameters/client/catalog/user-data), implement RowMapper directly.
+ *
+ * @template T of object
+ *
+ * @param class-string<T> $class
+ * @param non-empty-string $method
+ *
+ * @return StaticFactoryMapper<T>
+ */
+#[DocumentationDSL(module: Module::PG_QUERY, type: DSLType::HELPER)]
+function static_factory_mapper(string $class, string $method) : StaticFactoryMapper
+{
+    return new StaticFactoryMapper($class, $method);
+}
+
 /**
  * Wrap a value with explicit PostgreSQL type information for parameter binding.
  *

src/lib/postgresql/tests/Flow/PostgreSql/Tests/Unit/Client/RowMapper/ConstructorMapperTest.php

@@ -248,7 +248,7 @@ public function test_throws_for_class_without_constructor() : void
         $this->expectException(MappingException::class);
         $this->expectExceptionMessage('Class has no constructor');
 
-        (new ConstructorMapper(NoConstructorDto::class))->map(['id' => 1], MapperContextMother::any());
+        new ConstructorMapper(NoConstructorDto::class);
     }
 
     public function test_throws_for_missing_required_parameter() : void