updated docs and removed health checker

Author: g2px1

CMakeLists.txt

@@ -45,11 +45,7 @@ file(GLOB_RECURSE UPQ_SOURCES CONFIGURE_DEPENDS
         ${CMAKE_CURRENT_SOURCE_DIR}/src/upq/*.cpp
 )
 
-add_library(upq ${UPQ_SOURCES} ${UPQ_HEADERS}
-        include/upq/PgNotificationMultiplexer.h
-        include/upq/PgHealthChecker.h
-        src/upq/PgHealthChecker.cpp
-        include/upq/PgReflect.h)
+add_library(upq ${UPQ_SOURCES} ${UPQ_HEADERS})
 add_library(usub::upq ALIAS upq)
 
 target_include_directories(upq

docs/index.md

@@ -10,21 +10,53 @@ It’s designed for **uvent**, built around coroutines, and avoids libpqxx and b
 - Coroutine-based queries
 - Clean separation between pool, connection, and transaction
 - Minimal allocations and zero unnecessary copies
+- Opt-in reflection for ergonomic reads/writes (zero boilerplate, positional mapping)
 
 ## Components
 
-| Component             | Purpose                                            |
-|-----------------------|----------------------------------------------------|
-| **PgPool**            | Global connection pool, manages `PGconn` instances |
-| **PgConnectionLibpq** | Async low-level PostgreSQL connection wrapper      |
-| **PgTransaction**     | Transaction wrapper built on pooled connections    |
-| **QueryResult**       | Lightweight query result container                 |
+| Component             | Purpose                                                   |
+|-----------------------|-----------------------------------------------------------|
+| **PgPool**            | Global connection pool, manages `PGconn` instances        |
+| **PgConnectionLibpq** | Async low-level PostgreSQL connection wrapper             |
+| **PgTransaction**     | Transaction wrapper built on pooled connections           |
+| **QueryResult**       | Lightweight query result container                        |
+| **PgReflect**         | Header-only reflect helpers and mappers (positional only) |
+
+## Features
+
+- **Reflect-aware SELECT** → `std::vector<T>` / `std::optional<T>`  
+  Positional mapping: column order in `SELECT` must match the field order of `T` (or tuple elements).
+- **Reflect-aware params** for `INSERT/UPDATE`:
+    - Aggregates/tuples are expanded into multiple `$1..$N` parameters.
+    - Containers (`std::vector`, `std::array`, `T[N]`, `initializer_list`) are sent as a single typed PostgreSQL array
+      parameter.
+    - `std::optional<T>` maps to `NULL` or a value.
+- Stays close to libpq semantics; no hidden background threads, no magic.
+
+**Tiny example**
+
+```cpp
+struct User { int64_t id; std::string name; std::optional<std::string> password; };
+
+// Read many
+auto users = co_await pool.query_reflect<User>(
+    "SELECT id, name, password FROM users ORDER BY id LIMIT 100"
+);
+
+// Insert from aggregate
+struct NewUser { std::string name; std::optional<std::string> password; std::vector<int> roles; };
+NewUser nu{"alice", std::nullopt, {1,2}};
+co_await pool.exec_reflect(
+    "INSERT INTO users(name, password, roles) VALUES ($1,$2,$3)",
+    nu
+);
+```
 
 ## What it *doesn’t* do
 
-- No ORM or reflection mapping
-- No query builders or migration tools
-- No automatic reconnection or retry logic
-- No external dependencies besides `libpq` and `uvent`
+* No ORM
+* No query builders or migration tools
+* No automatic reconnection or retry logic
+* No external dependencies besides `libpq` and `uvent`
 
 The philosophy: **use coroutines, keep it minimal, and let the compiler inline everything**.

docs/pool.md

@@ -16,6 +16,7 @@ Primary high-level entrypoint for queries in **upq**.
 - Safe recycling with dirty-connection handling
 - Structured errors (`QueryResult`)
 - Optional periodic health checks (`PgPoolHealthConfig`)
+- Reflect-aware SELECT/EXEC helpers (`query_reflect`, `exec_reflect`)
 - Compatible with high-volume ops exposed on `PgConnectionLibpq`:
     - `COPY ... FROM STDIN` / `COPY ... TO STDOUT`
     - server-side cursors with chunked fetch
@@ -137,7 +138,73 @@ Both APIs return `QueryResult` with `ok`, `code`, `error`, `rows`, `rows_valid`.
 
 ---
 
-### Pipelined query execution
+## Reflect-aware API
+
+Reflection-based helpers provide direct mapping between SQL and C++ aggregates.
+
+### SELECT → `std::vector<T>` or `std::optional<T>`
+
+```cpp
+struct UserRow {
+    int64_t id;
+    std::string name;
+    std::optional<std::string> password;
+    std::vector<int> roles;
+    std::vector<std::string> tags;
+};
+
+// Multiple rows
+auto users = co_await pool.query_reflect<UserRow>(
+    "SELECT id, name, password, roles, tags FROM users ORDER BY id;"
+);
+
+// Single row
+auto one = co_await pool.query_reflect_one<UserRow>(
+    "SELECT id, name, password, roles, tags FROM users WHERE id = 1;"
+);
+```
+
+### INSERT/UPDATE from aggregates
+
+```cpp
+struct NewUser {
+    std::string name;
+    std::optional<std::string> password;
+    std::vector<int> roles;
+    std::vector<std::string> tags;
+};
+
+NewUser nu{ "bob", std::nullopt, {1, 2}, {"vip"} };
+
+auto res = co_await pool.exec_reflect(
+    "INSERT INTO users(name, password, roles, tags) VALUES ($1,$2,$3,$4);",
+    nu
+);
+```
+
+### API summary
+
+| Method                               | Description                                                  |
+|--------------------------------------|--------------------------------------------------------------|
+| `query_reflect<T>(sql)`              | SELECT → `std::vector<T>`                                    |
+| `query_reflect_one<T>(sql)`          | SELECT one → `std::optional<T>`                              |
+| `exec_reflect(sql, obj)`             | Executes using fields of an aggregate or tuple as parameters |
+| `query_on_reflect<T>(conn, sql)`     | Same as above, bound to existing connection                  |
+| `query_on_reflect_one<T>(conn, sql)` | Single-row variant                                           |
+| `exec_reflect_on(conn, sql, obj)`    | Aggregate parameter execution on given connection            |
+
+### Mapping rules
+
+* Field order in `SELECT` must match member order in the struct.
+* `std::optional<T>` → NULL or value.
+* Containers (`vector`, `array`, etc.) → PostgreSQL arrays.
+* Aggregate or tuple expands into multiple `$1..$N` parameters.
+* Non-aggregate containers are sent as a single typed array parameter.
+* Pointers (except `char*`) are unsupported.
+
+---
+
+## Pipelined query execution
 
 All `query*()` methods support **PostgreSQL pipelining** via a compile-time template flag.
 
@@ -253,15 +320,6 @@ task::Awaitable<void> cursor_stream_example()
 
 `PgCursorChunk` is described in `results.md`.
 
-This approach:
-
-* Opens a cursor (`DECLARE ... CURSOR FOR <query>`)
-* Fetches N rows at a time using `FETCH FORWARD <N> FROM <cursor>`
-* Closes cursor and commits
-
-The pool’s recycling logic ensures that after this multi-step usage, the connection is either safely recycled (if
-drained) or retired and replaced.
-
 ---
 
 ## Error model
@@ -288,5 +346,8 @@ Pool self-heals by retiring broken connections and opening new ones on demand.
 | Dirty handling       | Drain on async release, otherwise retire                        |
 | Health checks        | Optional periodic probes with `checked/alive/reconnected` stats |
 | COPY & cursors       | Via `PgConnectionLibpq`, safe to return to pool                 |
+| Reflect API          | `query_reflect` / `exec_reflect` for aggregates & structs       |
 | Structured errors    | Clear non-exceptional failure reporting                         |
-| Pipeline execution   | Compile-time toggle `<true>` for batched async queries          |
+| Pipeline execution   | Compile-time toggle `<true>` for batched async queries          |
+
+```

docs/quickstart.md

@@ -43,7 +43,9 @@ task::Awaitable<void> create_schema()
         "CREATE TABLE IF NOT EXISTS users("
         "id SERIAL PRIMARY KEY,"
         "name TEXT,"
-        "password TEXT);"
+        "password TEXT,"
+        "roles INT[],"
+        "tags TEXT[]);"
     );
 
     if (!res.ok)
@@ -111,9 +113,75 @@ task::Awaitable<void> get_user(int user_id)
 
 ---
 
-## 5. Diagnostics
+## 5. Reflect-based queries (struct mapping)
 
-Every query now returns structured error information:
+Reflection allows automatic binding of aggregates and tuples to query parameters,
+and automatic mapping of query results into structs.
+
+### SELECT → `std::vector<T>` or `std::optional<T>`
+
+```cpp
+struct UserRow
+{
+    int64_t id;
+    std::string name;
+    std::optional<std::string> password;
+    std::vector<int> roles;
+    std::vector<std::string> tags;
+};
+
+task::Awaitable<void> get_all()
+{
+    auto& pool = usub::pg::PgPool::instance();
+
+    auto rows = co_await pool.query_reflect<UserRow>(
+        "SELECT id, name, password, roles, tags FROM users ORDER BY id;"
+    );
+
+    for (auto& r : rows)
+        std::cout << "user=" << r.name << "\n";
+    co_return;
+}
+```
+
+### Aggregate → parameters
+
+```cpp
+struct NewUser
+{
+    std::string name;
+    std::optional<std::string> password;
+    std::vector<int> roles;
+    std::vector<std::string> tags;
+};
+
+task::Awaitable<void> insert_user()
+{
+    NewUser u{ "bob", std::nullopt, {1, 2}, {"vip"} };
+
+    auto res = co_await usub::pg::PgPool::instance().exec_reflect(
+        "INSERT INTO users(name, password, roles, tags) VALUES ($1,$2,$3,$4);",
+        u
+    );
+
+    if (!res.ok)
+        std::cout << "Insert failed: " << res.error << "\n";
+    co_return;
+}
+```
+
+### Rules
+
+* Field order in `SELECT` must match the order of members in the struct.
+* `std::optional<T>` → NULL or value.
+* Containers (`vector`, `array`, etc.) → PostgreSQL arrays.
+* Aggregate/tuple expands into multiple `$1..$N` parameters.
+
+---
+
+## 6. Diagnostics
+
+Every query returns structured error information:
 
 ```cpp
 auto res = co_await pool.query_awaitable("SELECT * FROM nonexistent;");

docs/results.md

@@ -13,6 +13,44 @@ Each type includes consistent fields: `ok`, `code`, `error`, and `err_detail`.
 
 ---
 
+## Reflect integration
+
+When using the reflect-based API (`query_reflect`, `query_reflect_one`, `exec_reflect`,  
+`select_reflect`, `select_one_reflect`), you usually **don’t access `QueryResult` directly**.
+
+Instead, data is automatically mapped:
+
+| Operation                 | Return type        | Description                                                  |
+|---------------------------|--------------------|--------------------------------------------------------------|
+| `query_reflect<T>()`      | `std::vector<T>`   | Maps rows positionally to struct/tuple fields                |
+| `query_reflect_one<T>()`  | `std::optional<T>` | Returns one row or `std::nullopt`                            |
+| `exec_reflect()`          | `QueryResult`      | Executes `INSERT/UPDATE` using aggregate or tuple parameters |
+| `select_reflect<T>()`     | `std::vector<T>`   | Transactional SELECT → struct list                           |
+| `select_one_reflect<T>()` | `std::optional<T>` | Transactional SELECT single row                              |
+
+### Example
+
+```cpp
+struct User {
+    int64_t id;
+    std::string name;
+    std::optional<std::string> password;
+};
+
+auto users = co_await pool.query_reflect<User>(
+    "SELECT id, name, password FROM users;"
+);
+
+for (auto& u : users)
+    std::cout << "id=" << u.id << " name=" << u.name << "\n";
+```
+
+Under the hood, the library still produces an internal `QueryResult`
+and uses it to construct your mapped objects. For debugging or mixed workflows,
+you can still call `query_awaitable()` to access raw result rows.
+
+---
+
 ## PgErrorCode
 
 Every result type references `PgErrorCode` for classification:
@@ -32,7 +70,7 @@ enum class PgErrorCode : uint32_t {
     AwaitCanceled,
     Unknown
 };
-````
+```
 
 **Meaning:**
 
@@ -264,4 +302,6 @@ struct PgCursorChunk
 * Use `empty()` to detect successful queries with no rows.
 * Use `has_rows()` for success with results.
 * `rows_valid == false` → truncated/unsafe result.
-* No exceptions; all information is explicit and type-safe.
+* No exceptions; all information is explicit and type-safe.
+
+```

docs/roadmap.md

@@ -83,7 +83,7 @@ CREATE TABLE cron_jobs
     last_run    timestamptz,
     query       text
 );
-```
+````
 
 Each job is periodically executed by a background coroutine.
 
@@ -120,7 +120,7 @@ Migration system using SQL files (`migrations/*.sql`) with transactional apply/r
 * Fully coroutine-compatible.
 
 **Goal:** schema management built into runtime.
-**Status:** Planned after TypeRegistry.
+**Status:** Planned after TypeRegistry & ReflectSystem.
 
 ---
 
@@ -157,7 +157,7 @@ Foundation for future ORM-style or codegen tooling.
 
 ---
 
-## 10. PgTestHarness — Transactional Testing Utility
+## 11. PgTestHarness — Transactional Testing Utility
 
 Test helper for SQL regression and snapshot testing.
 
@@ -178,7 +178,7 @@ Test helper for SQL regression and snapshot testing.
 |-------|----------------------------------------------|----------------------------------|
 | **1** | ReconnectSupervisor, StatsRegistry           | Stability & observability        |
 | **2** | PreparedStatementRegistry, ChannelDispatcher | Throughput & reactive events     |
-| **3** | CronScheduler, TypeRegistry                  | Automation & binary performance  |
+| **3** | CronScheduler, TypeRegistry, ReflectSystem   | Automation & binary performance  |
 | **4** | Migrator, TransactionScope                   | Schema control & DX improvements |
 | **5** | Introspector, TestHarness                    | Ecosystem & developer tooling    |