mdbxmou 0.3.5 → 0.3.7

package/README.md

@@ -24,29 +24,33 @@ CommonJS:
 ```javascript
 const { MDBX_Env, MDBX_Param } = require('mdbxmou');
 
-// Create environment
-const env = new MDBX_Env();
-await env.open({ 
-  path: './data',
-  keyFlag: MDBX_Param.keyFlag.string,    // Default key encoding (optional)
-  valueFlag: MDBX_Param.valueFlag.string // Default value encoding (optional)
-});
+async function main() {
+  // Create environment
+  const env = new MDBX_Env();
+  await env.open({ 
+    path: './data',
+    keyFlag: MDBX_Param.keyFlag.string,    // Default key encoding (optional)
+    valueFlag: MDBX_Param.valueFlag.string // Default value encoding (optional)
+  });
 
-// Write data
-const txn = env.startWrite();
-const dbi = txn.createMap(MDBX_Param.keyMode.ordinal);
-dbi.put(txn, 1, "hello");
-dbi.put(txn, 2, "world");
-txn.commit();
+  // Write data
+  const txn = env.startWrite();
+  const dbi = txn.createMap(MDBX_Param.keyMode.ordinal);
+  dbi.put(txn, 1, "hello");
+  dbi.put(txn, 2, "world");
+  txn.commit();
 
-// Read data
-const readTxn = env.startRead();
-const readDbi = readTxn.openMap(BigInt(MDBX_Param.keyMode.ordinal));
-const value = readDbi.get(readTxn, 1);
-console.log(value); // "hello"
-readTxn.commit();
+  // Read data
+  const readTxn = env.startRead();
+  const readDbi = readTxn.openMap(BigInt(MDBX_Param.keyMode.ordinal));
+  const value = readDbi.get(readTxn, 1);
+  console.log(value); // "hello"
+  readTxn.commit();
 
-await env.close();
+  await env.close();
+}
+
+main().catch(console.error);
 ```
 
 ESM:
@@ -185,8 +189,9 @@ const result = await env.query([
 #### Methods
 
 **createMap([db_name | keyMode], [keyMode | valueMode], [valueMode]) → DBI**
+**createMap({ name, keyFlag, valueFlag, keyMode, valueMode }) → DBI**
 ```javascript
-// No arguments - default DB with string keys
+// No arguments - default DB with env key/value flags (buffer if not set)
 const dbi = txn.createMap();
 
 // One argument - keyMode only
@@ -203,13 +208,23 @@ const namedDbi = txn.createMap("my-table", MDBX_Param.keyMode.ordinal);
 
 // Three arguments - db_name + keyMode + valueMode  
 const namedDbi = txn.createMap("my-table", MDBX_Param.keyMode.ordinal, MDBX_Param.valueMode.multi);
+
+// Object form - explicit flags/modes
+const dbi = txn.createMap({
+  name: "my-table",
+  keyFlag: MDBX_Param.keyFlag.string,
+  valueFlag: MDBX_Param.valueFlag.string,
+  keyMode: MDBX_Param.keyMode.reverse,
+  valueMode: MDBX_Param.valueMode.multi
+});
 ```
 
 > **Note**: Use `createMap` in write transactions - it will create the database if it doesn't exist, or open it if it does. This is safer for new environments.
 
 **openMap([db_name | keyMode], [keyMode]) → DBI**
+**openMap({ name, keyFlag, valueFlag, keyMode, valueMode }) → DBI**
 ```javascript
-// No arguments - default DB with string keys
+// No arguments - default DB with env key/value flags (buffer if not set)
 const dbi = txn.openMap();
 
 // One argument - keyMode only
@@ -224,6 +239,15 @@ const namedDbi = txn.openMap("my-table");
 // Two arguments - db_name + keyMode
 const namedDbi = txn.openMap("my-table", MDBX_Param.keyMode.ordinal);
 const namedDbiBigInt = txn.openMap("my-table", BigInt(MDBX_Param.keyMode.ordinal));
+
+// Object form - explicit flags/modes
+const dbi = txn.openMap({
+  name: "my-table",
+  keyFlag: MDBX_Param.keyFlag.string,
+  valueFlag: MDBX_Param.valueFlag.string,
+  keyMode: MDBX_Param.keyMode.reverse,
+  valueMode: MDBX_Param.valueMode.multi
+});
 ```
 
 > **Note**: Use `openMap` in read transactions or when you're sure the database already exists. For write transactions on new environments, prefer `createMap`.
@@ -231,6 +255,7 @@ const namedDbiBigInt = txn.openMap("my-table", BigInt(MDBX_Param.keyMode.ordinal
 > **Note**: When using ordinal keyMode, the key type in results depends on how you specify keyMode:
 > - `keyMode: number` → keys returned as `number`
 > - `keyMode: BigInt(number)` → keys returned as `BigInt`
+> - When you pass `keyMode.ordinal` as a positional argument (Number/BigInt), it also updates `keyFlag` to number/bigint unless a numeric keyFlag was already set in env or explicitly provided.
 
 **commit()**
 ```javascript
@@ -607,6 +632,9 @@ async function asyncExample() {
   readTxn.commit();
   await env.close();
 }
+
+syncExample();
+asyncExample().catch(console.error);
 ```
 
 ### Key Type Behavior
@@ -649,6 +677,8 @@ function keyTypesExample() {
 
   env.closeSync();
 }
+
+keyTypesExample();
 ```
 
 ### Cursor Operations
@@ -702,6 +732,8 @@ function cursorExample() {
   readTxn.commit();
   env.closeSync();
 }
+
+cursorExample();
 ```
 
 ### Query API (Advanced Async)
@@ -721,7 +753,7 @@ async function queryExample() {
   // Async query with DBI object (not database name)
   const results = await env.query([
     {
-      dbi: dbi,
+      dbi,
       mode: MDBX_Param.queryMode.insertUnique,
       item: [
         { key: 1, value: JSON.stringify({ name: "Alice" }) },
@@ -729,7 +761,7 @@ async function queryExample() {
       ]
     },
     {
-      dbi: dbi,
+      dbi,
       mode: MDBX_Param.queryMode.get,
       item: [
         { key: 1 },
@@ -741,6 +773,8 @@ async function queryExample() {
   console.log('Query results:', JSON.stringify(results, null, 2));
   await env.close();
 }
+
+queryExample().catch(console.error);
 ```
 
 ### Async Keys API
@@ -767,7 +801,7 @@ async function keysExample() {
   console.log("All keys:", allKeys);
 
   // Get keys with DBI object parameter  
-  const allKeys2 = await env.keys({ dbi: dbi });
+  const allKeys2 = await env.keys({ dbi });
   console.log("All keys (object):", allKeys2);
 
   // Get keys from multiple DBIs
@@ -776,32 +810,54 @@ async function keysExample() {
 
   // Get limited keys from specific position
   const limitedKeys = await env.keys([
-    { dbi: dbi, limit: 3, from: 5 }
+    { dbi, limit: 3, from: 5 }
   ]);
   console.log("Limited keys:", limitedKeys);
 
   await env.close();
 }
+
+keysExample().catch(console.error);
 ```
 
 ## Error Handling
 
 ```javascript
-try {
-  const env = new MDBX_Env();
-  await env.open({ path: './data' });
-  
-  const txn = env.startWrite();
-  const dbi = txn.createMap(MDBX_Param.keyMode.ordinal);
-  
-  // This might throw if key already exists with MDBX_NOOVERWRITE
-  dbi.put(txn, 123, "value");
-  
-  txn.commit();
-} catch (error) {
-  console.error('Database error:', error.message);
-  if (txn) txn.abort();
+async function errorHandlingExample() {
+  let txn;
+  try {
+    const env = new MDBX_Env();
+    await env.open({ path: './data' });
+    
+    txn = env.startWrite();
+    const dbi = txn.createMap(MDBX_Param.keyMode.ordinal);
+    
+    // This might throw if key already exists with MDBX_NOOVERWRITE
+    dbi.put(txn, 123, "value");
+    
+    txn.commit();
+  } catch (error) {
+    console.error('Database error:', error.message);
+    if (txn) txn.abort();
+  }
 }
+
+errorHandlingExample().catch(console.error);
+```
+
+## Runnable README Tests
+
+The examples above have matching runnable tests in `test/`. You can execute them directly:
+
+```bash
+node test/readme-quick-start.js
+node test/readme-sync-example.js
+node test/readme-async-example.js
+node test/readme-key-types.js
+node test/readme-cursor-example.js
+node test/readme-query-example.js
+node test/readme-keys-example.js
+node test/readme-error-handling.js
 ```
 
 ## Configuration Options

package/package.json

@@ -65,7 +65,7 @@
   },
   "gypfile": true,
   "name": "mdbxmou",
-  "version": "0.3.5",
+  "version": "0.3.7",
   "description": "Node bindings for mdbx",
   "repository": {
     "type": "git",

package/src/dbi.cpp

@@ -44,7 +44,6 @@ bool dbi::del(MDBX_txn* txn, const keymou& key)
     return true;
 }
 
-
 cursormou_managed dbi::open_cursor(MDBX_txn* txn) const
 {
     return open_cursor(txn, mdbx::map_handle{id_});

package/src/txnmou.cpp

@@ -102,6 +102,7 @@ Napi::Value txnmou::get_dbi(const Napi::Object& arg0, db_mode db_mode)
 {
     auto env = arg0.Env();
     auto conf = get_env_userctx(*env_);
+    // параметры по умолчанию из окружения
     auto key_flag = conf->key_flag;
     auto value_flag = conf->value_flag;
     key_mode key_mode{};