search-engine-core cpp-api-patterns.instructions.md

C++ API Patterns - Zero-Error Rules

Never guess API usage. Use these patterns to prevent compilation errors.

Result Interface

// ❌ WRONG - These methods DON'T EXIST
if (result.isSuccess()) { }
result.getError(); result.getValue();
Result<T>::success(value); Result<T>::failure(message);

// ✅ CORRECT
if (result.success) { }
result.message
result.value
Result<T>::Success(value, "msg")
Result<T>::Failure("error")

MongoDB BSON String Access

// ❌ WRONG
element.get_utf8().value.to_string()
element.key().to_string()

// ✅ CORRECT
std::string(element.get_string().value)
std::string(element.key())

MongoDB Aggregation

// ❌ WRONG
auto pipeline = document{} << "pipeline" << array{...} << finalize;
collection.aggregate(pipeline.view())

// ✅ CORRECT
mongocxx::pipeline pipeline;
pipeline.match(document{} << "field" << "value" << finalize);
pipeline.group(document{} << "_id" << "$field" << finalize);
collection.aggregate(pipeline)

Optional / Result Checks

// ❌ WRONG
if (result) { }  // run_command
if (!result) { } // find_one

// ✅ CORRECT
if (!result.empty()) { }      // run_command
if (!result.has_value()) { } // find_one (std::optional)

Quick Reference

if (result.success) { auto v = result.value; }
std::string str = std::string(element.get_string().value);
mongocxx::pipeline pipe; pipe.match(filter).group(grouping);
if (findResult.has_value()) { }

Code Template Checklist (Before Implementing)

• Use Result<T>::Success() and Result<T>::Failure() (capital letters)
• Include MongoDB singleton: MongoDBInstance::getInstance()
• Use lazy initialization for controller services
• Pair res->onData() with res->onAborted() for POST endpoints
• Use LOG_DEBUG() instead of std::cout
• Check BSON strings with std::string(element.get_string().value)
• Use mongocxx::pipeline for aggregations
• Use basic builder with .extract() for complex MongoDB updates