feat: Implement Nitro's getExternalMemorySize (#261)

* feat: implement Nitro's `getExternalMemorySize`

* Update package/cpp/specs/HybridNitroSQLiteQueryResult.cpp

Co-authored-by: Marc Rousavy <me@mrousavy.com>

* Update package/cpp/specs/HybridNitroSQLiteQueryResult.cpp

Co-authored-by: Marc Rousavy <me@mrousavy.com>

* fix: remove unnecessary memory size calculation for `HybridNitroSQLite` class

* fix: improve memory size calculation based on @mrousavy's review

* fix: add back empty line

---------

Co-authored-by: Marc Rousavy <me@mrousavy.com>

Author: chrispader

package/cpp/specs/HybridNitroSQLiteQueryResult.cpp

@@ -8,6 +8,60 @@
 
 namespace margelo::nitro::rnnitrosqlite {
 
+namespace {
+
+  /**
+   * Compute the approximate external memory size of a single result row.
+   * This includes:
+   * - Column name string capacities,
+   * - Heap usage for the actual SQLiteValue contents.
+   */
+  size_t getRowExternalMemorySize(const SQLiteQueryResultRow& row) {
+    size_t bucketMemory = row.bucket_count() * sizeof(void*);
+    constexpr size_t nodePadding = 24;
+    size_t nodesMemory = row.size() * (sizeof(std::pair<std::string, SQLiteValue>) * nodePadding);
+    return bucketMemory + nodesMemory;
+  }
+
+  /**
+   * Compute the approximate external memory size of the full result set.
+   * We add:
+   * - The vector's backing storage,
+   * - All rows (column names + values).
+   */
+  size_t getResultsExternalMemorySize(const SQLiteQueryResults& results) {
+    size_t size = sizeof(SQLiteQueryResults);
+
+    const auto resultCapacity = results.capacity();
+    size += resultCapacity * sizeof(SQLiteQueryResultRow);
+
+    for (const auto& row : results) {
+      size += getRowExternalMemorySize(row);
+    }
+
+    return size;
+  }
+
+  /**
+   * Compute the approximate external memory size of the table metadata.
+   * We include:
+   * - Column name string capacities (map keys),
+   * - Metadata contents, especially the `name` string on each metadata entry.
+   */
+  size_t getMetadataExternalMemorySize(const SQLiteQueryTableMetadata& metadata) {
+    size_t size = 0;
+
+    for (const auto& [columnName, columnMeta] : metadata) {
+
+      size += columnName.capacity();
+      size += columnMeta.name.capacity();
+    }
+
+    return size;
+  }
+
+} // namespace
+
 std::optional<double> HybridNitroSQLiteQueryResult::getInsertId() {
   return _insertId;
 }
@@ -24,4 +78,16 @@ std::optional<SQLiteQueryTableMetadata> HybridNitroSQLiteQueryResult::getMetadat
   return _metadata;
 }
 
+size_t HybridNitroSQLiteQueryResult::getExternalMemorySize() noexcept {
+  size_t size = sizeof(*this);
+
+  size += getResultsExternalMemorySize(_results);
+
+  if (_metadata) {
+    size += getMetadataExternalMemorySize(*_metadata);
+  }
+
+  return size;
+}
+
 } // namespace margelo::nitro::rnnitrosqlite

package/cpp/specs/HybridNitroSQLiteQueryResult.hpp

@@ -27,6 +27,21 @@ class HybridNitroSQLiteQueryResult : public HybridNitroSQLiteQueryResultSpec {
   double getRowsAffected() override;
   SQLiteQueryResults getResults() override;
   std::optional<SQLiteQueryTableMetadata> getMetadata() override;
+
+  /**
+   * Approximate the native memory used by this query result.
+   *
+   * We account for:
+   * - The size of this C++ object (`sizeof(*this)`),
+   * - All rows and columns (including column name strings),
+   * - String values stored in the result set,
+   * - ArrayBuffers used for BLOB columns (object overhead + raw byte size),
+   * - Column metadata strings.
+   *
+   * This is a best-effort estimate and intentionally focuses on external
+   * heap allocations that can put pressure on the JS GC.
+   */
+  size_t getExternalMemorySize() noexcept override;
 };
 
 } // namespace margelo::nitro::rnnitrosqlite