orm: stabilize public API, fix examples, and inline templates

- Re-export DB primitives (DBError, make_mysql_factory) via db_compat
- Fix all ORM examples to rely only on orm.hpp
- Align QueryBuilder params binding with DbValue
- Inline template-only components (Mapper, Repository, UnitOfWork)
- Remove obsolete .cpp files for header-only ORM parts
- Clean CMake and example build consistency

Author: GaspardKirira

CMakeLists.txt

@@ -48,10 +48,7 @@ set(VIX_ORM_PUBLIC_HEADERS
 )
 
 set(VIX_ORM_SOURCES
-  src/Mapper.cpp
   src/QueryBuilder.cpp
-  src/Repository.cpp
-  src/UnitOfWork.cpp
 )
 
 # ------------------------------------------------------------------------------

examples/batch_insert_tx.cpp

@@ -11,24 +11,24 @@
  *  Vix.cpp
  */
 #include <vix/orm/orm.hpp>
-#include <vix/orm/ConnectionPool.hpp>
-#include <vix/orm/MySQLDriver.hpp>
 
+#include <cstdint>
 #include <iostream>
-#include <vector>
 #include <string>
+#include <vector>
 
 using namespace vix::orm;
 
 int main(int argc, char **argv)
 {
-  std::string host = (argc > 1 ? argv[1] : "tcp://127.0.0.1:3306");
-  std::string user = (argc > 2 ? argv[2] : "root");
-  std::string pass = (argc > 3 ? argv[3] : "");
-  std::string db = (argc > 4 ? argv[4] : "vixdb");
+  const std::string host = (argc > 1 ? argv[1] : "tcp://127.0.0.1:3306");
+  const std::string user = (argc > 2 ? argv[2] : "root");
+  const std::string pass = (argc > 3 ? argv[3] : "");
+  const std::string db = (argc > 4 ? argv[4] : "vixdb");
 
   try
   {
+    // DB factory (MySQL driver)
     auto factory = make_mysql_factory(host, user, pass, db);
 
     PoolConfig cfg;
@@ -38,6 +38,7 @@ int main(int argc, char **argv)
     ConnectionPool pool{factory, cfg};
     pool.warmup();
 
+    // Transaction (RAII rollback if not committed)
     Transaction tx(pool);
     auto &c = tx.conn();
 
@@ -50,7 +51,7 @@ int main(int argc, char **argv)
       int age;
     };
 
-    std::vector<Row> rows = {
+    const std::vector<Row> rows = {
         {"Zoe", "zoe@example.com", 23},
         {"Mina", "mina@example.com", 31},
         {"Omar", "omar@example.com", 35},
@@ -69,6 +70,11 @@ int main(int argc, char **argv)
     std::cout << "[OK] inserted rows = " << total << "\n";
     return 0;
   }
+  catch (const DBError &e)
+  {
+    std::cerr << "[DBError] " << e.what() << "\n";
+    return 1;
+  }
   catch (const std::exception &e)
   {
     std::cerr << "[ERR] " << e.what() << "\n";

examples/error_handling.cpp

@@ -11,39 +11,54 @@
  *  Vix.cpp
  */
 #include <vix/orm/orm.hpp>
+
 #include <iostream>
+#include <string>
 
 using namespace vix::orm;
 
 int main(int argc, char **argv)
 {
   (void)argc;
   (void)argv;
+
   try
   {
-    // Intentionally wrong DB name to show error
-    auto factory = make_mysql_factory("tcp://127.0.0.1:3306", "root", "", "db_does_not_exist");
+    // Intentionally wrong DB name to show error handling
+    const std::string host = "tcp://127.0.0.1:3306";
+    const std::string user = "root";
+    const std::string pass = "";
+    const std::string db = "db_does_not_exist";
+
+    auto factory = make_mysql_factory(host, user, pass, db);
+
     PoolConfig cfg;
     cfg.min = 1;
     cfg.max = 8;
 
     ConnectionPool pool{factory, cfg};
+
+    // will throw if factory returns invalid connection (recommended after our warmup fix),
+    // or later when first query fails.
     pool.warmup();
 
     UnitOfWork uow{pool};
     auto &con = uow.conn();
 
     auto st = con.prepare("SELECT 1");
-    st->exec();
+    (void)st->exec();
+
     std::cout << "[INFO] This message may not be reached if connection fails.\n";
+    return 0;
   }
   catch (const DBError &e)
   {
     std::cerr << "[DBError] " << e.what() << "\n";
+    return 1;
   }
   catch (const std::exception &e)
   {
     std::cerr << "[std::exception] " << e.what() << "\n";
+    return 1;
   }
-  return 0;
 }

examples/querybuilder_update.cpp

@@ -11,20 +11,19 @@
  *  Vix.cpp
  */
 #include <vix/orm/orm.hpp>
-#include <vix/orm/ConnectionPool.hpp>
-#include <vix/orm/MySQLDriver.hpp>
 
+#include <cstddef>
 #include <iostream>
 #include <string>
 
 using namespace vix::orm;
 
 int main(int argc, char **argv)
 {
-  std::string host = (argc > 1 ? argv[1] : "tcp://127.0.0.1:3306");
-  std::string user = (argc > 2 ? argv[2] : "root");
-  std::string pass = (argc > 3 ? argv[3] : "");
-  std::string db = (argc > 4 ? argv[4] : "vixdb");
+  const std::string host = (argc > 1 ? argv[1] : "tcp://127.0.0.1:3306");
+  const std::string user = (argc > 2 ? argv[2] : "root");
+  const std::string pass = (argc > 3 ? argv[3] : "");
+  const std::string db = (argc > 4 ? argv[4] : "vixdb");
 
   try
   {
@@ -47,12 +46,17 @@ int main(int argc, char **argv)
 
     const auto &ps = qb.params();
     for (std::size_t i = 0; i < ps.size(); ++i)
-      st->bind(i + 1, ps[i]);
+      st->bind(i + 1, any_to_dbvalue_or_throw(ps[i]));
 
-    auto affected = st->exec();
+    const auto affected = st->exec();
     std::cout << "[OK] affected rows = " << affected << "\n";
     return 0;
   }
+  catch (const DBError &e)
+  {
+    std::cerr << "[DBError] " << e.what() << "\n";
+    return 1;
+  }
   catch (const std::exception &e)
   {
     std::cerr << "[ERR] " << e.what() << "\n";

examples/repository_crud_full.cpp

@@ -12,12 +12,13 @@
  */
 
 #include <vix/orm/orm.hpp>
-#include <vix/orm/ConnectionPool.hpp>
-#include <vix/orm/MySQLDriver.hpp>
 
-#include <iostream>
+#include <any>
 #include <cstdint>
+#include <iostream>
 #include <string>
+#include <utility>
+#include <vector>
 
 struct User
 {
@@ -32,7 +33,15 @@ namespace vix::orm
   template <>
   struct Mapper<User>
   {
-    static User fromRow(const ResultRow &) { return {}; } // pending
+    static User fromRow(const ResultRow &row)
+    {
+      User u{};
+      u.id = row.getInt64Or(0, 0);
+      u.name = row.getStringOr(1, "");
+      u.email = row.getStringOr(2, "");
+      u.age = static_cast<int>(row.getInt64Or(3, 0));
+      return u;
+    }
 
     static std::vector<std::pair<std::string, std::any>>
     toInsertParams(const User &u)
@@ -60,10 +69,10 @@ int main(int argc, char **argv)
 {
   using namespace vix::orm;
 
-  std::string host = (argc > 1 ? argv[1] : "tcp://127.0.0.1:3306");
-  std::string user = (argc > 2 ? argv[2] : "root");
-  std::string pass = (argc > 3 ? argv[3] : "");
-  std::string db = (argc > 4 ? argv[4] : "vixdb");
+  const std::string host = (argc > 1 ? argv[1] : "tcp://127.0.0.1:3306");
+  const std::string user = (argc > 2 ? argv[2] : "root");
+  const std::string pass = (argc > 3 ? argv[3] : "");
+  const std::string db = (argc > 4 ? argv[4] : "vixdb");
 
   try
   {
@@ -79,20 +88,31 @@ int main(int argc, char **argv)
     BaseRepository<User> repo{pool, "users"};
 
     // Create
-    std::int64_t id = static_cast<std::int64_t>(
+    const std::int64_t id = static_cast<std::int64_t>(
         repo.create(User{0, "Bob", "gaspardkirira@example.com", 30}));
-    std::cout << "[OK] create → id=" << id << "\n";
+    std::cout << "[OK] create -> id=" << id << "\n";
 
     // Update
-    repo.updateById(id, User{id, "Adastra", "adastra@example.com", 31});
-    std::cout << "[OK] update → id=" << id << "\n";
+    (void)repo.updateById(id, User{id, "Adastra", "adastra@example.com", 31});
+    std::cout << "[OK] update -> id=" << id << "\n";
+
+    // (Optional) Read back
+    if (auto u = repo.findById(id))
+    {
+      std::cout << "[OK] findById -> name=" << u->name << " email=" << u->email << " age=" << u->age << "\n";
+    }
 
     // Delete
-    repo.removeById(id);
-    std::cout << "[OK] delete → id=" << id << "\n";
+    (void)repo.removeById(id);
+    std::cout << "[OK] delete -> id=" << id << "\n";
 
     return 0;
   }
+  catch (const DBError &e)
+  {
+    std::cerr << "[DBError] " << e.what() << "\n";
+    return 1;
+  }
   catch (const std::exception &e)
   {
     std::cerr << "[ERR] " << e.what() << "\n";

examples/tx_unit_of_work.cpp

@@ -12,20 +12,19 @@
  */
 
 #include <vix/orm/orm.hpp>
-#include <vix/orm/ConnectionPool.hpp>
-#include <vix/orm/MySQLDriver.hpp>
 
+#include <cstdint>
 #include <iostream>
 #include <string>
 
 using namespace vix::orm;
 
 int main(int argc, char **argv)
 {
-  std::string host = (argc > 1 ? argv[1] : "tcp://127.0.0.1:3306");
-  std::string user = (argc > 2 ? argv[2] : "root");
-  std::string pass = (argc > 3 ? argv[3] : "");
-  std::string db = (argc > 4 ? argv[4] : "vixdb");
+  const std::string host = (argc > 1 ? argv[1] : "tcp://127.0.0.1:3306");
+  const std::string user = (argc > 2 ? argv[2] : "root");
+  const std::string pass = (argc > 3 ? argv[3] : "");
+  const std::string db = (argc > 4 ? argv[4] : "vixdb");
 
   try
   {
@@ -43,17 +42,17 @@ int main(int argc, char **argv)
 
     {
       auto st = c.prepare("INSERT INTO users(name,email,age) VALUES(?,?,?)");
-      st->bind(1, std::string("Alice"));
-      st->bind(2, std::string("alice@example.com"));
+      st->bind(1, "Alice");
+      st->bind(2, "alice@example.com");
       st->bind(3, 27);
       st->exec();
     }
 
-    const auto userId = c.lastInsertId();
+    const std::uint64_t userId = c.lastInsertId();
 
     {
       auto st = c.prepare("INSERT INTO orders(user_id,total) VALUES(?,?)");
-      st->bind(1, static_cast<std::int64_t>(userId));
+      st->bind(1, userId);
       st->bind(2, 199.99);
       st->exec();
     }

examples/users_crud.cpp

@@ -12,19 +12,19 @@
  */
 
 #include <vix/orm/orm.hpp>
-#include <vix/orm/ConnectionPool.hpp>
-#include <vix/orm/MySQLDriver.hpp>
+
 #include <iostream>
+#include <string>
 #include <vector>
 
 using namespace vix::orm;
 
 int main(int argc, char **argv)
 {
-  std::string host = (argc > 1 ? argv[1] : "tcp://127.0.0.1:3306");
-  std::string user = (argc > 2 ? argv[2] : "root");
-  std::string pass = (argc > 3 ? argv[3] : "");
-  std::string db = (argc > 4 ? argv[4] : "vixdb");
+  const std::string host = (argc > 1 ? argv[1] : "tcp://127.0.0.1:3306");
+  const std::string user = (argc > 2 ? argv[2] : "root");
+  const std::string pass = (argc > 3 ? argv[3] : "");
+  const std::string db = (argc > 4 ? argv[4] : "vixdb");
 
   try
   {
@@ -48,7 +48,8 @@ int main(int argc, char **argv)
       const char *email;
       int age;
     };
-    std::vector<Row> rows = {
+
+    const std::vector<Row> rows = {
         {"Gaspard", "gaspardkirira@outlook.com", 23},
         {"Mina", "mina@example.com", 31},
         {"Omar", "omar@example.com", 35},

include/vix/orm/Mapper.hpp

@@ -13,20 +13,33 @@
 #ifndef VIX_MAPPER_HPP
 #define VIX_MAPPER_HPP
 
-#include <vix/db/Drivers.hpp>
+#include <any>
 #include <string>
+#include <utility>
 #include <vector>
-#include <any>
+
+#include <vix/db/core/Result.hpp>
 
 namespace vix::orm
 {
+  /**
+   * User-specialized mapper.
+   *
+   * Example:
+   * template<>
+   * struct Mapper<User> { ... };
+   */
   template <class T>
   struct Mapper
   {
     static T fromRow(const vix::db::ResultRow &row);
-    static std::vector<std::pair<std::string, std::any>> toInsertParams(const T &v);
-    static std::vector<std::pair<std::string, std::any>> toUpdateParams(const T &v);
+
+    static std::vector<std::pair<std::string, std::any>>
+    toInsertParams(const T &v);
+
+    static std::vector<std::pair<std::string, std::any>>
+    toUpdateParams(const T &v);
   };
-} // namespace Vix::orm
+} // namespace vix::orm
 
 #endif // VIX_MAPPER_HPP