mdbxmou 0.2.7 → 0.3.1

package/CMakeLists.txt

@@ -24,6 +24,7 @@ add_library(${PROJECT_NAME} SHARED
     "src/envmou.cpp" 
     "src/txnmou.cpp"
     "src/dbimou.cpp"
+    "src/cursormou.cpp"
     "src/dbi.cpp")
 
 # Gives our library file a .node extension without any "lib" prefix

package/README.md

@@ -9,7 +9,7 @@ High-performance Node.js binding for libmdbx — a fast, lightweight, embedded k
 - **Transactions** — ACID transactions with read/write modes
 - **Multiple key/value types** — String, binary, ordinal (integer) keys
 - **Batch operations** — Efficient multi-key read/write
-- **Memory-mapped** — Zero-copy data access
+- **Memory-mapped** — High-performance memory-mapped I/O
 
 ## Installation
 
@@ -266,6 +266,199 @@ dbi.drop(txn, true);
 dbi.drop(txn);
 ```
 
+### Cursor (MDBX_Cursor)
+
+Cursors provide low-level control for database traversal with positioning and iteration capabilities.
+
+#### Creating a Cursor
+```javascript
+const txn = env.startRead();
+const dbi = txn.openMap();
+const cursor = txn.openCursor(dbi);
+```
+
+#### Navigation Methods
+
+**first() → {key, value} | undefined**
+```javascript
+const item = cursor.first();
+if (item) {
+  console.log(item.key, item.value);
+}
+```
+
+**last() → {key, value} | undefined**
+```javascript
+const item = cursor.last();
+```
+
+**next() → {key, value} | undefined**
+```javascript
+const item = cursor.next();
+```
+
+**prev() → {key, value} | undefined**
+```javascript
+const item = cursor.prev();
+```
+
+**current() → {key, value} | undefined**
+```javascript
+const item = cursor.current();
+```
+
+#### Search Methods
+
+**seek(key) → {key, value} | undefined**
+
+Exact key match. Returns `undefined` if key not found.
+```javascript
+const item = cursor.seek('user:123');
+if (item) {
+  console.log('Found:', item.value);
+}
+```
+
+**seekGE(key) → {key, value} | undefined**
+
+Find first key greater or equal to given key (lower_bound).
+```javascript
+const item = cursor.seekGE('user:100');
+// Returns first key >= 'user:100'
+```
+
+#### Modification Methods
+
+**put(key, value, [flags])**
+
+Insert or update a record at cursor position.
+```javascript
+cursor.put('newKey', 'newValue');
+
+// With flags (MDBX_NOOVERWRITE, etc.)
+cursor.put('key', 'value', MDBX_Param.queryMode.insertUnique);
+```
+
+**del([flags]) → boolean**
+
+Delete record at current cursor position. Returns `true` if deleted, `false` if not found.
+```javascript
+cursor.seek('keyToDelete');
+const deleted = cursor.del();
+```
+
+#### Control Methods
+
+**close()**
+```javascript
+cursor.close();
+```
+
+#### Cursor Examples
+
+**Iterate all records:**
+```javascript
+const cursor = txn.openCursor(dbi);
+
+for (let item = cursor.first(); item; item = cursor.next()) {
+  console.log(item.key, item.value.toString());
+}
+
+cursor.close();
+txn.abort();
+```
+
+**Range iteration:**
+```javascript
+const cursor = txn.openCursor(dbi);
+
+// Find all keys starting with 'user:'
+for (let item = cursor.seekGE('user:'); item; item = cursor.next()) {
+  if (!item.key.startsWith('user:')) break;
+  console.log(item.key, item.value.toString());
+}
+
+cursor.close();
+```
+
+**Pagination:**
+```javascript
+function getPage(cursor, offset, limit) {
+  const results = [];
+  
+  let item = cursor.first();
+  
+  // Skip offset
+  for (let i = 0; i < offset && item; i++) {
+    item = cursor.next();
+  }
+  
+  // Collect limit items
+  for (let i = 0; i < limit && item; i++) {
+    results.push({ key: item.key, value: item.value.toString() });
+    item = cursor.next();
+  }
+  
+  return results;
+}
+
+const txn = env.startRead();
+const dbi = txn.openMap();
+const cursor = txn.openCursor(dbi);
+
+const page1 = getPage(cursor, 0, 10);   // First 10 items
+const page2 = getPage(cursor, 10, 10);  // Next 10 items
+
+cursor.close();
+txn.abort();
+```
+
+**Reverse iteration:**
+```javascript
+const cursor = txn.openCursor(dbi);
+
+for (let item = cursor.last(); item; item = cursor.prev()) {
+  console.log(item.key, item.value.toString());
+}
+
+cursor.close();
+```
+
+**Bulk insert with cursor:**
+```javascript
+const txn = env.startWrite();
+const dbi = txn.createMap();
+const cursor = txn.openCursor(dbi);
+
+for (let i = 0; i < 1000; i++) {
+  cursor.put(`key${i}`, `value${i}`);
+}
+
+cursor.close();
+txn.commit();
+```
+
+**Delete with cursor:**
+```javascript
+const txn = env.startWrite();
+const dbi = txn.openMap();
+const cursor = txn.openCursor(dbi);
+
+// Delete specific key
+if (cursor.seek('keyToDelete')) {
+  cursor.del();
+}
+
+// Delete range
+for (let item = cursor.seekGE('prefix:'); item; item = cursor.next()) {
+  if (!item.key.startsWith('prefix:')) break;
+  cursor.del();
+}
+
+cursor.close();
+txn.commit();
+```
+
 ## Key and Value Types
 
 ### Key Modes (MDBX_Param.keyMode)
@@ -623,7 +816,7 @@ Note: For ordinal (integer) keys, use keyFlag.number or keyFlag.bigint to specif
 1. **Use ordinal keys** for integer data - much faster than string keys
 2. **Batch operations** - Use query API for bulk operations
 3. **Reuse transactions** - Keep read transactions open for multiple operations
-4. **Memory mapping** - MDBX uses memory-mapped files for zero-copy access
+4. **Memory mapping** - MDBX uses memory-mapped files for fast I/O
 5. **Transaction scope** - Always pass transaction object to DBI methods
 
 ## License

package/package.json

@@ -46,8 +46,7 @@
   ],
   "dependencies": {
     "cmake-js": "^7.3.1",
-    "node-addon-api": "^8.5.0",
-    "uuid": "^13.0.0"
+    "node-addon-api": "^8.5.0"
   },
   "devDependencies": {
     "@types/node": "^22.10.2",
@@ -66,7 +65,7 @@
   },
   "gypfile": true,
   "name": "mdbxmou",
-  "version": "0.2.7",
+  "version": "0.3.1",
   "description": "Node bindings for mdbx",
   "repository": {
     "type": "git",

package/src/async/envmou_async.cpp

@@ -0,0 +1,450 @@
+#include "envmou.hpp"
+#include "txnmou.hpp"
+#include "async/envmou_copy_to.hpp"
+#include "async/envmou_query.hpp"
+#include "async/envmou_open.hpp"
+#include "async/envmou_keys.hpp"
+#include "async/envmou_close.hpp"
+
+#ifdef _WIN32
+#include <windows.h>
+#else
+#include <pthread.h>
+#endif
+
+namespace mdbxmou {
+
+Napi::FunctionReference envmou::ctor{};
+
+void envmou::init(const char *class_name, Napi::Env env, Napi::Object exports)
+{
+    auto func = DefineClass(env, class_name, {
+        InstanceMethod("open", &envmou::open),
+        InstanceMethod("openSync", &envmou::open_sync),
+        InstanceMethod("close", &envmou::close),
+        InstanceMethod("closeSync", &envmou::close_sync),
+        InstanceMethod("copyTo", &envmou::copy_to),
+        InstanceMethod("copyToSync", &envmou::copy_to_sync),
+        InstanceMethod("version", &envmou::get_version),
+        InstanceMethod("startRead", &envmou::start_read),
+        InstanceMethod("startWrite", &envmou::start_write),
+        InstanceMethod("query", &envmou::query),
+        InstanceMethod("keys", &envmou::keys)
+    });
+    ctor = Napi::Persistent(func);
+    ctor.SuppressDestruct();
+    exports.Set(class_name, func);
+}
+
+mdbx::env::geometry envmou::parse_geometry(const Napi::Value& arg0) 
+{
+    mdbx::env::geometry geom{};
+
+    auto obj = arg0.As<Napi::Object>();
+
+    if (obj.Has("fixedSize")) {
+        auto value = obj.Get("fixedSize").As<Napi::Number>();
+        auto fixed_size = static_cast<intptr_t>(value.Int64Value());
+        return geom.make_fixed(fixed_size);
+    } else if (obj.Has("dynamicSize")) {
+        auto arr = obj.Get("dynamicSize").As<Napi::Array>();
+        if (arr.Length() != 2) {
+            throw Napi::TypeError::New(obj.Env(), "dynamicSize must be an array of two numbers");
+        }
+        auto v1 = arr.Get(0u).As<Napi::Number>();
+        auto v2 = arr.Get(1u).As<Napi::Number>();
+        auto size_lower = static_cast<intptr_t>(v1.Int64Value());
+        auto size_upper = static_cast<intptr_t>(v2.Int64Value());
+        return geom.make_dynamic(size_lower, size_upper);
+    } else {
+        if (obj.Has("sizeNow")) {
+            auto value = obj.Get("sizeNow").As<Napi::Number>();
+            geom.size_now = static_cast<intptr_t>(value.Int64Value());
+        }
+        if (obj.Has("sizeUpper")) {
+            auto value = obj.Get("sizeUpper").As<Napi::Number>();
+            geom.size_upper = static_cast<intptr_t>(value.Int64Value());
+        }
+        if (obj.Has("growthStep")) {
+            auto value = obj.Get("growthStep").As<Napi::Number>();
+            geom.growth_step = static_cast<intptr_t>(value.Int64Value());
+        }
+        if (obj.Has("shrinkThreshold")) {
+            auto value = obj.Get("shrinkThreshold").As<Napi::Number>();
+            geom.shrink_threshold = static_cast<intptr_t>(value.Int64Value());
+        }
+        if (obj.Has("pageSize")) {
+            auto value = obj.Get("pageSize").As<Napi::Number>();
+            geom.pagesize = static_cast<intptr_t>(value.Int64Value());
+        }
+    }
+    return geom;
+}
+
+env_arg0 envmou::parse(const Napi::Value& arg0)
+{
+    env_arg0 rc;
+
+    auto obj = arg0.As<Napi::Object>();
+
+    rc.path = obj.Get("path").As<Napi::String>().Utf8Value();
+    if (obj.Has("maxDbi")) {
+        auto value = obj.Get("maxDbi").As<Napi::Number>();
+        rc.max_dbi = static_cast<MDBX_dbi>(value.Uint32Value());
+    } 
+
+    if (obj.Has("geometry")) {
+        rc.geom = parse_geometry(obj.Get("geometry"));
+    }
+
+    if (obj.Has("flags")) {
+        rc.flag = env_flag::parse(obj.Get("flags"));
+    }
+
+    if (obj.Has("mode")) {
+        auto value = obj.Get("mode").As<Napi::Number>();
+        rc.file_mode = static_cast<mdbx_mode_t>(value.Int32Value());
+    }
+
+    if (obj.Has("keyFlag")) {
+        rc.key_flag = base_flag::parse_key(obj.Get("keyFlag"));
+    }
+
+    if (obj.Has("valueFlag")) {
+        rc.value_flag = base_flag::parse_value(obj.Get("valueFlag"));
+    }
+
+    return rc;
+}
+
+Napi::Value envmou::open(const Napi::CallbackInfo& info)
+{
+    auto env = info.Env();
+    auto arg0 = parse(info[0].As<Napi::Object>());
+
+    try {
+        // асинхронный вызов разлочится внутри worker'a
+        if (!try_lock()) {
+            throw std::runtime_error("in progress");
+        }
+
+        if (is_open()) {
+            throw std::runtime_error("already opened");
+        }          
+
+        auto* worker = new async_open(env, *this, arg0);
+        Napi::Promise promise = worker->GetPromise();
+        worker->Queue();
+        return promise;
+    } catch (const std::exception& e) {
+        unlock();
+        throw Napi::Error::New(env, e.what());
+    } catch (...) {
+        unlock();
+        throw;
+    }
+
+    return env.Undefined();
+}
+
+Napi::Value envmou::open_sync(const Napi::CallbackInfo& info)
+{
+    auto env = info.Env();
+    auto arg0 = parse(info[0].As<Napi::Object>());
+
+    try {
+        lock_guard l(*this);
+        if (is_open()) {
+            throw std::runtime_error("already opened");
+        }
+        attach(create_and_open(arg0), arg0);
+    } catch (const std::exception& e) {
+        throw Napi::Error::New(env, e.what());
+    }
+
+    return env.Undefined();
+}
+
+MDBX_env* envmou::create_and_open(const env_arg0& arg0)
+{
+    MDBX_env *env;
+    auto rc = mdbx_env_create(&env);
+    if (rc != MDBX_SUCCESS) {
+        throw std::runtime_error(mdbx_strerror(rc));
+    }
+
+    rc = mdbx_env_set_maxdbs(env, arg0.max_dbi);
+    if (rc != MDBX_SUCCESS) {
+        mdbx_env_close(env);
+        throw std::runtime_error(mdbx_strerror(rc));
+    }
+
+    rc = mdbx_env_set_maxreaders(env, arg0.max_readers);
+    if (rc != MDBX_SUCCESS) {
+        mdbx_env_close(env);
+        throw std::runtime_error(mdbx_strerror(rc));
+    }
+
+    auto& geom = arg0.geom;
+    rc = mdbx_env_set_geometry(env, geom.size_lower, geom.size_now, 
+        geom.size_upper, geom.growth_step, geom.shrink_threshold, geom.pagesize);
+    if (rc != MDBX_SUCCESS) {
+        mdbx_env_close(env);
+        throw std::runtime_error(mdbx_strerror(rc));
+    }
+
+#ifdef _WIN32
+    auto id = static_cast<std::uint32_t>(GetCurrentThreadId());
+#else
+    auto id = static_cast<std::uint32_t>(pthread_self());
+#endif
+    // выдадим параметры mode, flag и id потока в котором открывается env
+    rc = mdbx_env_open(env, arg0.path.c_str(), arg0.flag, arg0.file_mode);
+    if (rc != MDBX_SUCCESS) {
+        mdbx_env_close(env);
+        throw std::runtime_error(mdbx_strerror(rc));
+    }
+
+    return env;
+}
+
+void envmou::attach(MDBX_env* env, const env_arg0& arg0)
+{
+    arg0_ = arg0;
+    
+    auto rc = mdbx_env_set_userctx(env, &arg0_);
+    if (rc != MDBX_SUCCESS) {
+        mdbx_env_close(env);
+        throw std::runtime_error(mdbx_strerror(rc));
+    }
+
+    env_.reset(env);
+}
+
+Napi::Value envmou::close(const Napi::CallbackInfo& info)
+{
+    auto env = info.Env();
+    try {
+        // асинхронный вызов разлочится внутри worker'a
+        if (!try_lock()) {
+            throw std::runtime_error("in progress");
+        }
+
+        if (!is_open()) {
+            return env.Undefined();
+        }
+
+        if (trx_count_.load() > 0) {
+            throw std::runtime_error("active transactions");
+        }
+
+        auto* worker = new async_close(env, *this);
+        Napi::Promise promise = worker->GetPromise();
+        worker->Queue();
+        return promise;
+    } catch (const std::exception& e) {
+        unlock();
+        throw Napi::Error::New(env, e.what());
+    } catch (...) {
+        unlock();
+        throw;
+    }
+
+    return env.Undefined();
+}
+
+Napi::Value envmou::close_sync(const Napi::CallbackInfo& info)
+{
+    auto env = info.Env();
+    try {
+        lock_guard l(*this);
+
+        do_close();
+
+    } catch (const std::exception& e) {
+        throw Napi::Error::New(env, e.what());
+    }
+    return env.Undefined();
+}
+
+Napi::Value envmou::copy_to_sync(const Napi::CallbackInfo& info) 
+{
+    auto env = info.Env();
+
+    if (info.Length() < 1 || !info[0].IsString()) {
+        throw Napi::TypeError::New(env, "expected a string argument for the destination path");
+    }
+
+    MDBX_copy_flags_t flags{MDBX_CP_COMPACT};
+    if ((info.Length() > 1) && info[1].IsNumber()) {
+        flags = static_cast<MDBX_copy_flags_t>(info[1].As<Napi::Number>().Uint32Value());
+    }
+
+    try {
+        auto dest_path = info[0].As<Napi::String>().Utf8Value();
+
+        lock_guard l(*this);
+
+        check();
+
+        auto rc = mdbx_env_copy(*this, dest_path.c_str(), flags);
+        if (rc != MDBX_SUCCESS) {
+            throw Napi::Error::New(env, mdbx_strerror(rc));
+        }
+
+    } catch (const std::exception& e) {
+        throw Napi::Error::New(env, e.what());
+    }
+
+    return env.Undefined();
+}
+
+Napi::Value envmou::copy_to(const Napi::CallbackInfo& info) 
+{
+    Napi::Env env = info.Env();
+
+    if (info.Length() < 1 || !info[0].IsString()) {
+        throw Napi::TypeError::New(env, "copyTo(path: string[, flags?: number]) -> Promise<void>");
+    }
+
+    MDBX_copy_flags_t flags{MDBX_CP_COMPACT};
+    if (info.Length() > 1 && info[1].IsNumber()) {
+        flags = static_cast<MDBX_copy_flags_t>(info[1].As<Napi::Number>().Uint32Value());
+    }
+
+    try {
+        auto dest = info[0].As<Napi::String>().Utf8Value();
+
+        if (!try_lock()) {
+            throw std::runtime_error("in progress");
+        }
+
+        check();
+
+        auto* worker = new mdbxmou::async_copy(env, *this, std::move(dest), flags);
+        Napi::Promise promise = worker->GetPromise();
+        worker->Queue();
+        return promise;
+    } catch (const std::exception& e) {
+        throw Napi::Error::New(env, e.what());
+    }
+
+    return env.Undefined();
+}
+
+Napi::Value envmou::get_version(const Napi::CallbackInfo& info) 
+{
+    std::string version = "mdbx v" + std::to_string(MDBX_VERSION_MAJOR);
+    version += "." + std::to_string(MDBX_VERSION_MINOR);
+    return Napi::Value::From(info.Env(), version);
+}
+
+Napi::Value envmou::start_transaction(const Napi::CallbackInfo& info, txn_mode mode) 
+{
+    auto env = info.Env();
+    
+    try {
+        lock_guard l(*this);
+
+        check();
+
+        MDBX_txn* txn;
+        auto rc = mdbx_txn_begin(*this, nullptr, mode, &txn);
+        if (rc != MDBX_SUCCESS) {
+            throw Napi::Error::New(env, std::string("Env: ") + mdbx_strerror(rc));
+        }
+
+        // Создаем новый объект txnmou
+        auto txn_obj = txnmou::ctor.New({});
+        auto txn_wrapper = txnmou::Unwrap(txn_obj);
+        txn_wrapper->attach(*this, txn, mode, nullptr);
+
+        return txn_obj;
+    } catch (const std::exception& e) {
+        throw Napi::Error::New(env, e.what());
+    }
+}
+
+Napi::Value envmou::query(const Napi::CallbackInfo& info)
+{
+    Napi::Env env = info.Env();
+
+    txn_mode mode{};
+
+    if (info.Length() < 1) {
+        throw Napi::TypeError::New(env, "expected array of requests");
+    }
+
+    if (info.Length() > 1 || info[1].IsNumber()) {
+        mode = txn_mode::parse(info[1].As<Napi::Number>());
+    }
+
+    try
+    {
+        lock_guard lock(*this);
+
+        check();
+
+        auto conf = get_env_userctx(*this);
+
+        auto arg0 = info[0];
+        query_request query = parse_query(mode, arg0);
+        auto* worker = new async_query(env, *this, mode, 
+            std::move(query), arg0.IsObject());
+        auto promise = worker->GetPromise();
+        worker->Queue();
+        
+        // Увеличиваем счетчик транзакций после успешного создания
+        ++(*this);
+
+        return promise;
+    } catch (const std::exception& e) {
+        throw Napi::Error::New(env, e.what());
+    } catch (...) {
+        throw Napi::Error::New(env, "envmou::query");
+    }
+    return env.Undefined();
+}
+
+Napi::Value envmou::keys(const Napi::CallbackInfo& info)
+{
+    Napi::Env env = info.Env();
+
+    txn_mode mode{};
+
+    if (info.Length() < 1) {
+        throw Napi::TypeError::New(env, 
+            "expected array of requests: [{ db: String, db_mode: Number, key_mode: Number, key_flag: Number, value_mode: Number, value_flag: Number }, ...]");
+    }
+
+    if (info.Length() > 1 || info[1].IsNumber()) {
+        mode = txn_mode::parse(info[1].As<Napi::Number>());
+    }
+
+    try
+    {
+        lock_guard lock(*this);
+
+        check();
+
+        auto arg0 = info[0];
+        keys_request query = parse_keys(arg0);
+
+        auto* worker = new async_keys(env, *this, mode, 
+            std::move(query), arg0.IsObject());
+        auto promise = worker->GetPromise();
+        worker->Queue();
+        
+        // Увеличиваем счетчик транзакций после успешного создания
+        ++(*this);
+
+        return promise;
+    } catch (const std::exception& e) {
+        throw Napi::Error::New(env, e.what());
+    } catch (...) {
+        throw Napi::Error::New(env, "envmou::keys");
+    }
+    return env.Undefined();
+}
+
+} // namespace mdbxmou

package/src/async/envmou_async.hpp

@@ -0,0 +1,116 @@
+#pragma once
+
+#include "txnmou.hpp"
+#include <memory>
+#include <atomic>
+#include <mutex>
+
+namespace mdbxmou {
+
+// Forward declaration
+class txnmou;
+
+class envmou final
+    : public Napi::ObjectWrap<envmou>
+{  
+    static Napi::FunctionReference ctor;
+    static mdbx::env::geometry parse_geometry(const Napi::Value& obj);
+    static env_arg0 parse(const Napi::Value& obj);
+
+    struct free_env {
+        void operator()(MDBX_env* env) const {
+            auto rc = mdbx_env_close(env);
+            if (rc != MDBX_SUCCESS) {
+                fprintf(stderr, "mdbx_env_close %s\n", mdbx_strerror(rc));
+            }
+        }
+    };
+        
+    std::unique_ptr<MDBX_env, free_env> env_{};
+    std::atomic<std::size_t> trx_count_{};
+    env_arg0 arg0_{};
+    std::mutex lock_{};
+
+    bool is_open() const {
+        return env_ != nullptr;
+    }
+
+    // Inline метод для проверки что база данных открыта
+    void check() const {
+        if (!is_open()) {
+            throw std::runtime_error("closed");
+        }
+    }
+
+    // Общий метод для создания транзакций
+    Napi::Value start_transaction(const Napi::CallbackInfo& info, txn_mode mode);
+
+public:    
+    envmou(const Napi::CallbackInfo& i)
+        : ObjectWrap{i}
+    {   }
+
+    static MDBX_env* create_and_open(const env_arg0& arg0);
+    void attach(MDBX_env* env, const env_arg0& arg0);
+
+    operator MDBX_env*() const noexcept {
+        return env_.get();
+    }
+
+    static void init(const char *class_name, Napi::Env env, Napi::Object exports);
+
+    envmou& operator++() noexcept {
+        ++trx_count_;
+        return *this;
+    }
+
+    envmou& operator--() noexcept {
+        --trx_count_;
+        return *this;
+    }
+
+    Napi::Value open(const Napi::CallbackInfo&);
+    Napi::Value open_sync(const Napi::CallbackInfo&);
+    Napi::Value close(const Napi::CallbackInfo&);
+    Napi::Value close_sync(const Napi::CallbackInfo&);
+    Napi::Value get_version(const Napi::CallbackInfo&);
+    Napi::Value copy_to_sync(const Napi::CallbackInfo&);
+    Napi::Value copy_to(const Napi::CallbackInfo&);
+    // метод для групповых вставок или чтения
+    // внутри транзакция, получение db и чтение/запись
+    Napi::Value query(const Napi::CallbackInfo&);
+    Napi::Value keys(const Napi::CallbackInfo&);
+    
+    // Методы для создания транзакций
+    Napi::Value start_read(const Napi::CallbackInfo& info) {
+        return start_transaction(info, {txn_mode::ro});
+    }
+    Napi::Value start_write(const Napi::CallbackInfo& info) {
+        return start_transaction(info, {});
+    }
+
+    using lock_guard = std::lock_guard<envmou>;
+    //  для защиты асинхронных операций
+    void lock() {
+        auto rc = lock_.try_lock();
+        if (!rc) {
+            throw std::runtime_error("operation in progress");
+        }
+    }
+    void unlock()  {
+        lock_.unlock();
+    }
+    bool try_lock() {
+        bool locked = lock_.try_lock();
+        return locked;
+    }
+
+    void do_close() {
+        if (trx_count_.load() > 0) {
+            throw std::runtime_error("transaction in progress");
+        }
+        env_.reset();
+    }
+};
+
+} // namespace mdbxmou

package/src/cursormou.cpp

@@ -0,0 +1,316 @@
+#include "cursormou.hpp"
+#include "dbimou.hpp"
+#include "txnmou.hpp"
+
+namespace mdbxmou {
+
+Napi::FunctionReference cursormou::ctor{};
+
+void cursormou::init(const char *class_name, Napi::Env env)
+{
+    auto func = DefineClass(env, class_name, {
+        InstanceMethod("first", &cursormou::first),
+        InstanceMethod("last", &cursormou::last),
+        InstanceMethod("next", &cursormou::next),
+        InstanceMethod("prev", &cursormou::prev),
+        InstanceMethod("seek", &cursormou::seek),
+        InstanceMethod("seekGE", &cursormou::seek_ge),
+        InstanceMethod("current", &cursormou::current),
+        InstanceMethod("put", &cursormou::put),
+        InstanceMethod("del", &cursormou::del),
+        InstanceMethod("forEach", &cursormou::for_each),
+        InstanceMethod("close", &cursormou::close),
+    });
+
+    ctor = Napi::Persistent(func);
+    ctor.SuppressDestruct();
+}
+
+void cursormou::do_close() noexcept
+{
+    if (cursor_) {
+        ::mdbx_cursor_close(std::exchange(cursor_, nullptr));
+        if (txn_) {
+            --(*txn_);
+        }
+    }
+}
+
+cursormou::~cursormou() 
+{
+    do_close();
+}
+
+void cursormou::attach(txnmou& txn, dbimou& dbi, MDBX_cursor* cursor)
+{
+    txn_ = &txn;
+    dbi_ = &dbi;
+    cursor_ = cursor;
+    ++(*txn_);
+}
+
+// Внутренний хелпер для навигации
+Napi::Value cursormou::move(const Napi::Env& env, MDBX_cursor_op op)
+{
+    if (!cursor_) {
+        throw Napi::Error::New(env, "cursor closed");
+    }
+    
+    keymou key{};
+    valuemou val{};   
+    auto rc = mdbx_cursor_get(cursor_, key, val, op);
+    if (rc == MDBX_NOTFOUND) {
+        return env.Undefined();
+    }
+    
+    if (rc != MDBX_SUCCESS) {
+        throw Napi::Error::New(env, mdbx_strerror(rc));
+    }
+    
+    // Возвращаем {key, value}
+    auto result = Napi::Object::New(env);
+    
+    auto key_mode = dbi_->get_key_mode();
+    auto key_flag = dbi_->get_key_flag();
+    auto value_flag = dbi_->get_value_flag();
+    
+    // Ключ
+    if (key_mode.val & key_mode::ordinal) {
+        if (key_flag.val & base_flag::bigint) {
+            result.Set("key", key.to_bigint(env));
+        } else {
+            result.Set("key", key.to_number(env));
+        }
+    } else {
+        result.Set("key", key.to_string(env));
+    }
+    
+    // Значение
+    if (value_flag.val & base_flag::string) {
+        result.Set("value", val.to_string(env));
+    } else {
+        result.Set("value", val.to_buffer(env));
+    }
+    
+    return result;
+}
+
+Napi::Value cursormou::first(const Napi::CallbackInfo& info) {
+    return move(info.Env(), MDBX_FIRST);
+}
+
+Napi::Value cursormou::last(const Napi::CallbackInfo& info) {
+    return move(info.Env(), MDBX_LAST);
+}
+
+Napi::Value cursormou::next(const Napi::CallbackInfo& info) {
+    return move(info.Env(), MDBX_NEXT);
+}
+
+Napi::Value cursormou::prev(const Napi::CallbackInfo& info) {
+    return move(info.Env(), MDBX_PREV);
+}
+
+Napi::Value cursormou::current(const Napi::CallbackInfo& info) {
+    return move(info.Env(), MDBX_GET_CURRENT);
+}
+
+// Хелпер для поиска
+Napi::Value cursormou::seek_impl(const Napi::CallbackInfo& info, MDBX_cursor_op op)
+{
+    Napi::Env env = info.Env();
+    
+    if (!cursor_) {
+        throw Napi::Error::New(env, "cursor closed");
+    }
+    
+    if (info.Length() < 1) {
+        throw Napi::Error::New(env, "key required");
+    }
+    
+    auto key_mode = dbi_->get_key_mode();
+    
+    keymou key = (key_mode.val & key_mode::ordinal) ?
+        keymou::from(info[0], env, key_num_) : 
+        keymou::from(info[0], env, key_buf_);
+    
+    valuemou val{};
+    auto rc = mdbx_cursor_get(cursor_, key, val, op);
+    if (MDBX_NOTFOUND == rc) {
+        return env.Undefined();
+    }
+
+    if (MDBX_SUCCESS != rc) {
+        throw Napi::Error::New(env, mdbx_strerror(rc));
+    }
+    
+    // Возвращаем {key, value}
+    auto result = Napi::Object::New(env);
+    
+    auto key_flag = dbi_->get_key_flag();
+    auto value_flag = dbi_->get_value_flag();
+    
+    // Ключ
+    if (key_mode.val & key_mode::ordinal) {
+        if (key_flag.val & base_flag::bigint) {
+            result.Set("key", key.to_bigint(env));
+        } else {
+            result.Set("key", key.to_number(env));
+        }
+    } else {
+        result.Set("key", key.to_string(env));
+    }
+    
+    // Значение
+    if (value_flag.val & base_flag::string) {
+        result.Set("value", val.to_string(env));
+    } else {
+        result.Set("value", val.to_buffer(env));
+    }
+    
+    return result;
+}
+
+Napi::Value cursormou::seek(const Napi::CallbackInfo& info) {
+    return seek_impl(info, MDBX_SET_KEY);
+}
+
+Napi::Value cursormou::seek_ge(const Napi::CallbackInfo& info) {
+    return seek_impl(info, MDBX_SET_RANGE);
+}
+
+Napi::Value cursormou::put(const Napi::CallbackInfo& info) {
+    Napi::Env env = info.Env();
+    
+    if (!cursor_) {
+        throw Napi::Error::New(env, "cursor closed");
+    }
+    
+    if (info.Length() < 2) {
+        throw Napi::Error::New(env, "key and value required");
+    }
+    
+    auto key_mode = dbi_->get_key_mode();
+    
+    keymou key = (key_mode.val & key_mode::ordinal) ?
+        keymou::from(info[0], env, key_num_) : 
+        keymou::from(info[0], env, key_buf_);
+    
+    valuemou val = valuemou::from(info[1], env, val_buf_);
+    
+    // Опциональный флаг put_mode (по умолчанию MDBX_UPSERT)
+    MDBX_put_flags_t flags = MDBX_UPSERT;
+    if (info.Length() > 2 && info[2].IsNumber()) {
+        flags = static_cast<MDBX_put_flags_t>(info[2].As<Napi::Number>().Int32Value());
+    }
+    
+    auto rc = mdbx_cursor_put(cursor_, key, val, flags);
+    if (MDBX_SUCCESS != rc) {
+        throw Napi::Error::New(env, mdbx_strerror(rc));
+    }
+    
+    return env.Undefined();
+}
+
+Napi::Value cursormou::del(const Napi::CallbackInfo& info) {
+    Napi::Env env = info.Env();
+    
+    if (!cursor_) {
+        throw Napi::Error::New(env, "cursor closed");
+    }
+    
+    // Опциональный флаг (MDBX_NODUPDATA для удаления только текущего значения в multi-value)
+    MDBX_put_flags_t flags = MDBX_CURRENT;
+    if (info.Length() > 0 && info[0].IsNumber()) {
+        flags = static_cast<MDBX_put_flags_t>(info[0].As<Napi::Number>().Int32Value());
+    }
+    
+    auto rc = mdbx_cursor_del(cursor_, flags);
+    if (MDBX_NOTFOUND == rc) {
+        return Napi::Boolean::New(env, false);
+    }
+    
+    if (MDBX_SUCCESS != rc) {
+        throw Napi::Error::New(env, mdbx_strerror(rc));
+    }
+    
+    return Napi::Boolean::New(env, true);
+}
+
+// forEach(callback, backward = false)
+// callback({key, value}) => true продолжить, false/undefined остановить
+Napi::Value cursormou::for_each(const Napi::CallbackInfo& info) {
+    Napi::Env env = info.Env();
+    
+    if (!cursor_) {
+        throw Napi::Error::New(env, "cursor closed");
+    }
+    
+    if (info.Length() < 1 || !info[0].IsFunction()) {
+        throw Napi::TypeError::New(env, "forEach: callback function required");
+    }
+    
+    auto callback = info[0].As<Napi::Function>();
+    bool backward = info.Length() > 1 && info[1].ToBoolean().Value();
+    
+    auto key_mode = dbi_->get_key_mode();
+    auto key_flag = dbi_->get_key_flag();
+    auto value_flag = dbi_->get_value_flag();
+    
+    MDBX_cursor_op start_op = backward ? MDBX_LAST : MDBX_FIRST;
+    MDBX_cursor_op move_op = backward ? MDBX_PREV : MDBX_NEXT;
+    
+    keymou key{};
+    valuemou val{};
+    // Первое позиционирование
+    auto rc = mdbx_cursor_get(cursor_, key, val, start_op);
+    while (MDBX_SUCCESS == rc) 
+    {
+        auto result = Napi::Object::New(env);
+        
+        // Ключ
+        if (key_mode.val & key_mode::ordinal) {
+            if (key_flag.val & base_flag::bigint) {
+                result.Set("key", key.to_bigint(env));
+            } else {
+                result.Set("key", key.to_number(env));
+            }
+        } else {
+            result.Set("key", key.to_string(env));
+        }
+        
+        // Значение
+        if (value_flag.val & base_flag::string) {
+            result.Set("value", val.to_string(env));
+        } else {
+            result.Set("value", val.to_buffer(env));
+        }
+        
+        // Вызов callback
+        auto ret = callback.Call({result});
+        
+        // Если вернул false или undefined - остановить
+        if (ret.IsBoolean() && !ret.As<Napi::Boolean>().Value()) {
+            break;
+        }
+        if (ret.IsUndefined() || ret.IsNull()) {
+            // undefined/null = продолжаем (как forEach в JS)
+        }
+        
+        // Следующий элемент
+        rc = mdbx_cursor_get(cursor_, key, val, move_op);
+    }
+    
+    if (rc != MDBX_SUCCESS && rc != MDBX_NOTFOUND) {
+        throw Napi::Error::New(env, mdbx_strerror(rc));
+    }
+    
+    return env.Undefined();
+}
+
+Napi::Value cursormou::close(const Napi::CallbackInfo& info) {
+    do_close();
+    return info.Env().Undefined();
+}
+
+} // namespace mdbxmou

package/src/cursormou.hpp

@@ -0,0 +1,69 @@
+#pragma once
+
+#include "typemou.hpp"
+#include "valuemou.hpp"
+
+namespace mdbxmou {
+
+class dbimou;
+class txnmou;
+
+class cursormou final 
+    : public Napi::ObjectWrap<cursormou>
+{
+private:
+    txnmou* txn_{nullptr};
+    dbimou* dbi_{nullptr};
+    MDBX_cursor* cursor_{nullptr};
+    
+    // Буферы для ключей/значений
+    buffer_type key_buf_{};
+    buffer_type val_buf_{};
+    std::uint64_t key_num_{};
+
+    // Внутренний хелпер для навигации
+    Napi::Value move(const Napi::Env& env, MDBX_cursor_op op);
+    
+    // Хелпер для поиска
+    Napi::Value seek_impl(const Napi::CallbackInfo& info, MDBX_cursor_op op);
+    
+    // Закрытие курсора
+    void do_close() noexcept;
+
+public:    
+    static Napi::FunctionReference ctor;
+    static void init(const char *class_name, Napi::Env env);
+
+    cursormou(const Napi::CallbackInfo& info)
+        : Napi::ObjectWrap<cursormou>(info) 
+    {   }
+
+    ~cursormou();
+
+    // Навигация
+    Napi::Value first(const Napi::CallbackInfo&);
+    Napi::Value last(const Napi::CallbackInfo&);
+    Napi::Value next(const Napi::CallbackInfo&);
+    Napi::Value prev(const Napi::CallbackInfo&);
+    
+    // Поиск
+    Napi::Value seek(const Napi::CallbackInfo&);      // exact match
+    Napi::Value seek_ge(const Napi::CallbackInfo&);   // >= key (lower_bound)
+    
+    // Текущая позиция
+    Napi::Value current(const Napi::CallbackInfo&);
+    
+    // Модификация
+    Napi::Value put(const Napi::CallbackInfo&);
+    Napi::Value del(const Napi::CallbackInfo&);
+    
+    // Итерация
+    Napi::Value for_each(const Napi::CallbackInfo&);
+    
+    // Закрытие
+    Napi::Value close(const Napi::CallbackInfo&);
+    
+    void attach(txnmou& txn, dbimou& dbi, MDBX_cursor* cursor);
+};
+
+} // namespace mdbxmou

package/src/modulemou.cpp

@@ -1,4 +1,5 @@
 #include "envmou.hpp"
+#include "cursormou.hpp"
 
 using namespace Napi;
 
@@ -106,6 +107,7 @@ Napi::Object Init(Napi::Env env, Napi::Object exports)
     mdbxmou::envmou::init("MDBX_Env", env, exports);
     mdbxmou::txnmou::init("MDBX_Txn", env);
     mdbxmou::dbimou::init("MDBX_Dbi", env);
+    mdbxmou::cursormou::init("MDBX_Cursor", env);
 
     return exports;
 }

package/src/txnmou.cpp

@@ -1,5 +1,6 @@
 #include "txnmou.hpp"
 #include "envmou.hpp"
+#include "cursormou.hpp"
 
 namespace mdbxmou {
 
@@ -11,6 +12,7 @@ void txnmou::init(const char *class_name, Napi::Env env) {
         InstanceMethod("abort", &txnmou::abort),
         InstanceMethod("openMap", &txnmou::open_map),
         InstanceMethod("createMap", &txnmou::create_map),
+        InstanceMethod("openCursor", &txnmou::open_cursor),
         InstanceMethod("isActive", &txnmou::is_active),
     });
 
@@ -25,6 +27,11 @@ Napi::Value txnmou::commit(const Napi::CallbackInfo& info) {
         throw Napi::Error::New(env, "txn already completed");
     }
     
+    if (cursor_count_ > 0) {
+        throw Napi::Error::New(env, 
+            "txn commit: " + std::to_string(cursor_count_) + " cursor(s) still open");
+    }
+    
     dec_counter();
     auto rc = mdbx_txn_commit(txn_.release());
     if (rc != MDBX_SUCCESS) {
@@ -41,6 +48,11 @@ Napi::Value txnmou::abort(const Napi::CallbackInfo& info) {
         throw Napi::Error::New(env, "txn already completed");
     }
     
+    if (cursor_count_ > 0) {
+        throw Napi::Error::New(env, 
+            "txn abort: " + std::to_string(cursor_count_) + " cursor(s) still open");
+    }
+    
     dec_counter();
     auto rc = mdbx_txn_abort(txn_.release());
     if (rc != MDBX_SUCCESS) {
@@ -124,6 +136,37 @@ Napi::Value txnmou::get_dbi(const Napi::CallbackInfo& info, db_mode db_mode)
     return obj;
 }
 
+Napi::Value txnmou::open_cursor(const Napi::CallbackInfo& info) {
+    Napi::Env env = info.Env();
+    
+    if (!txn_) {
+        throw Napi::Error::New(env, "txn not active");
+    }
+    
+    if (info.Length() < 1 || !info[0].IsObject()) {
+        throw Napi::Error::New(env, "dbi required");
+    }
+    
+    auto arg0 = info[0].As<Napi::Object>();
+    if (!arg0.InstanceOf(dbimou::ctor.Value())) {
+        throw Napi::TypeError::New(env, "openCursor: first argument must be MDBX_Dbi instance");
+    }
+    
+    auto* dbi = dbimou::Unwrap(arg0);
+    
+    MDBX_cursor* cursor{};
+    int rc = mdbx_cursor_open(txn_.get(), dbi->get_id(), &cursor);
+    
+    if (rc != MDBX_SUCCESS) {
+        throw Napi::Error::New(env, std::string("mdbx_cursor_open: ") + mdbx_strerror(rc));
+    }
+    
+    auto obj = cursormou::ctor.New({});
+    auto ptr = cursormou::Unwrap(obj);
+    ptr->attach(*this, *dbi, cursor);
+    return obj;
+}
+
 Napi::Value txnmou::is_active(const Napi::CallbackInfo& info) {
     Napi::Env env = info.Env();
     return Napi::Boolean::New(env, txn_ != nullptr);

package/src/txnmou.hpp

@@ -22,6 +22,7 @@ private:
 
     std::unique_ptr<MDBX_txn, free_txn> txn_{};
     txn_mode mode_{};
+    std::size_t cursor_count_{};
     
     // Уменьшает счетчик транзакций
     void dec_counter() noexcept;
@@ -51,11 +52,18 @@ public:
     Napi::Value create_map(const Napi::CallbackInfo& info) {
         return get_dbi(info, {db_mode::create});
     }
+    
+    Napi::Value open_cursor(const Napi::CallbackInfo&);
 
     operator MDBX_txn*() noexcept {
         return txn_.get();
     }
 
+    // Cursor counting
+    txnmou& operator++() noexcept { ++cursor_count_; return *this; }
+    txnmou& operator--() noexcept { --cursor_count_; return *this; }
+    std::size_t cursor_count() const noexcept { return cursor_count_; }
+
     Napi::Value is_active(const Napi::CallbackInfo&);
 
     void attach(envmou& env, MDBX_txn* txn, txn_mode mode);

package/src/valuemou.hpp

@@ -46,10 +46,10 @@ struct valuemou
             throw Napi::Error::New(env, "napi_get_value_string_utf8 length");
         }
         
-        mem.reserve(length + 1);
+        mem.resize(length + 1);
 
         status = napi_get_value_string_utf8(
-            env, arg0, mem.data(), mem.capacity(), nullptr);
+            env, arg0, mem.data(), mem.size(), nullptr);
         if (status != napi_ok) {
             throw Napi::Error::New(env, "napi_get_value_string_utf8 copyout");
         }