sqlite: add tagged template support

Adding tagged template and LRU cache for prepared
statements in SQLite.

Author: 0hmX

doc/api/sqlite.md

@@ -347,6 +347,66 @@ added: v22.5.0
 Compiles a SQL statement into a [prepared statement][]. This method is a wrapper
 around [`sqlite3_prepare_v2()`][].
 
+### `database.createSqlTagStore([maxSize])`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* `maxSize` {integer} The maximum number of prepared statements to cache.
+  **Default:** `1000`.
+* Returns: {SqlTagStore} A new SQL tag store for caching prepared statements.
+
+Creates a new `SqlTagStore`, which is an LRU (Least Recently Used) cache for
+storing prepared statements. This allows for the efficient reuse of prepared
+statements by tagging them with a unique identifier.
+
+When a tagged SQL literal is executed, the `SqlTagStore` checks if a prepared
+statement for that specific SQL string already exists in the cache. If it does,
+the cached statement is used. If not, a new prepared statement is created,
+executed, and then stored in the cache for future use. This mechanism helps to
+avoid the overhead of repeatedly parsing and preparing the same SQL statements.
+
+The `maxSize` parameter determines the maximum number of prepared statements
+that can be held in the LRU cache at any given time. When the cache is full, the
+least recently used statement is evicted to make room for a new one.
+
+The returned `SqlTagStore` object has the following methods, which correspond to
+the methods on the `StatementSync` class:
+
+* `all`
+* `get`
+* `iterate`
+* `run`
+
+Each of these methods takes a tagged SQL literal as its argument.
+
+```mjs
+import { DatabaseSync } from 'node:sqlite';
+
+const db = new DatabaseSync(':memory:');
+const sql = db.createSqlTagStore();
+
+db.exec('CREATE TABLE users (id INT, name TEXT)');
+
+// Using the 'run' method to insert data.
+// The tagged literal is used to identify the prepared statement.
+sql.run`INSERT INTO users VALUES (1, 'Alice')`;
+sql.run`INSERT INTO users VALUES (2, 'Bob')`;
+
+// Using the 'get' method to retrieve a single row.
+const user = sql.get`SELECT * FROM users WHERE id = 1`;
+console.log(user); // { id: 1, name: 'Alice' }
+
+// Using the 'all' method to retrieve all rows.
+const allUsers = sql.all`SELECT * FROM users ORDER BY id`;
+console.log(allUsers);
+// [
+//   { id: 1, name: 'Alice' },
+//   { id: 2, name: 'Bob' }
+// ]
+```
+
 ### `database.createSession([options])`
 
 <!-- YAML
@@ -490,6 +550,107 @@ times with different bound values. Parameters also offer protection against
 [SQL injection][] attacks. For these reasons, prepared statements are preferred
 over hand-crafted SQL strings when handling user input.
 
+## Class: `SqlTagStore`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+This class represents a single \[LRU (Least Recently Used) cache]\[] for storing
+prepared statements. This class cannot be instantiated via its constructor.
+Instead, instances are created via the `database.createSqlTagStore()` method.
+All APIs exposed by this class execute synchronously.
+
+The store saves the prepared statement in respect to the SQL query provided, and
+returns the same prepared statement when it sees it again. It has a `maxSize`
+which defaults to 1000 but can also be passed in
+`database.createSqlTagStore(100)`.
+
+### `sqlTagStore.all(sqlTemplate[, ...values])`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* `sqlTemplate` {Template Literal} A template literal containing the SQL query.
+* `...values` {any} Values to be interpolated into the template literal.
+* Returns: {Array} An array of objects representing the rows returned by the query.
+
+Executes the given SQL query and returns all resulting rows as an array of objects.
+
+### `sqlTagStore.get(sqlTemplate[, ...values])`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* `sqlTemplate` {Template Literal} A template literal containing the SQL query.
+* `...values` {any} Values to be interpolated into the template literal.
+* Returns: {Object | undefined} An object representing the first row returned by
+  the query, or `undefined` if no rows are returned.
+
+Executes the given SQL query and returns the first resulting row as an object.
+
+### `sqlTagStore.iterate(sqlTemplate[, ...values])`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* `sqlTemplate` {Template Literal} A template literal containing the SQL query.
+* `...values` {any} Values to be interpolated into the template literal.
+* Returns: {Iterator} An iterator that yields objects representing the rows returned by the query.
+
+Executes the given SQL query and returns an iterator over the resulting rows.
+
+### `sqlTagStore.run(sqlTemplate[, ...values])`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* `sqlTemplate` {Template Literal} A template literal containing the SQL query.
+* `...values` {any} Values to be interpolated into the template literal.
+* Returns: {Object} An object containing information about the execution, including `changes` and `lastInsertRowid`.
+
+Executes the given SQL query, which is expected to not return any rows (e.g., INSERT, UPDATE, DELETE).
+
+### `sqlTagStore.size()`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* Returns: {integer} The number of prepared statements currently in the cache.
+
+A read-only property that returns the number of prepared statements currently in the cache.
+
+### `sqlTagStore.capacity()`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* Returns: {integer} The maximum number of prepared statements the cache can hold.
+
+A read-only property that returns the maximum number of prepared statements the cache can hold.
+
+### `sqlTagStore.reset()`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+Resets the LRU cache, clearing all stored prepared statements.
+
+### `sqlTagStore.clear()`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+An alias for `sqlTagStore.reset()`.
+
 ### `statement.all([namedParameters][, ...anonymousParameters])`
 
 <!-- YAML

src/lru_cache-inl.h

@@ -0,0 +1,65 @@
+#ifndef SRC_LRU_CACHE_INL_H_
+#define SRC_LRU_CACHE_INL_H_
+
+#include <list>
+#include <unordered_map>
+#include <utility>
+
+template <typename key_t, typename value_t>
+class LruCache {
+ public:
+  using key_value_pair_t = typename std::pair<key_t, value_t>;
+  using iterator = typename std::list<key_value_pair_t>::iterator;
+
+  explicit LruCache(size_t capacity) : capacity_(capacity) {}
+
+  void put(const key_t& key, const value_t& value) {
+    auto it = lookup_map_.find(key);
+    if (it != lookup_map_.end()) {
+      lru_list_.erase(it->second);
+      lookup_map_.erase(it);
+    }
+
+    lru_list_.push_front(std::make_pair(key, value));
+    lookup_map_[key] = lru_list_.begin();
+
+    if (lookup_map_.size() > capacity_) {
+      auto last = lru_list_.end();
+      last--;
+      lookup_map_.erase(last->first);
+      lru_list_.pop_back();
+    }
+  }
+
+  value_t& get(const key_t& key) {
+    auto it = lookup_map_.find(key);
+    lru_list_.splice(lru_list_.begin(), lru_list_, it->second);
+    return it->second->second;
+  }
+
+  void erase(const key_t& key) {
+    auto it = lookup_map_.find(key);
+    if (it != lookup_map_.end()) {
+      lru_list_.erase(it->second);
+      lookup_map_.erase(it);
+    }
+  }
+
+  bool exists(const key_t& key) const { return lookup_map_.count(key) > 0; }
+
+  size_t size() const { return lookup_map_.size(); }
+
+  size_t capacity() const { return capacity_; }
+
+  void clear() {
+    lru_list_.clear();
+    lookup_map_.clear();
+  }
+
+ private:
+  std::list<key_value_pair_t> lru_list_;
+  std::unordered_map<key_t, iterator> lookup_map_;
+  size_t capacity_;
+};
+
+#endif  // SRC_LRU_CACHE_INL_H_