mdbxmou 0.2.4 → 0.2.6

package/README.md

@@ -132,8 +132,11 @@ const result = await env.query([
 
 #### Methods
 
-**createMap(db_name | keyMode, [keyMode | valueMode], [valueMode]) → DBI**
+**createMap([db_name | keyMode], [keyMode | valueMode], [valueMode]) → DBI**
 ```javascript
+// No arguments - default DB with string keys
+const dbi = txn.createMap();
+
 // One argument - keyMode only
 const dbi = txn.createMap(MDBX_Param.keyMode.ordinal);
 
@@ -152,8 +155,11 @@ const namedDbi = txn.createMap("my-table", MDBX_Param.keyMode.ordinal, MDBX_Para
 
 > **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([db_name | keyMode], [keyMode]) → DBI**
 ```javascript
+// No arguments - default DB with string keys
+const dbi = txn.openMap();
+
 // One argument - keyMode only
 // Number keyMode - keys returned as numbers
 const dbi = txn.openMap(MDBX_Param.keyMode.ordinal);

package/build.js

@@ -13,14 +13,15 @@ function exec(cmd) {
     }
 }
 
-// Create VERSION.json for libmdbx (needed for npm package)
+// Create VERSION.json for libmdbx (needed for npm packages, which don't ship git metadata).
+// In a git checkout/submodule we must NOT create it, since libmdbx rejects multiple version sources.
 const versionFile = 'deps/libmdbx/VERSION.json';
 const libmdbxGitMarker = 'deps/libmdbx/.git';
-if (!fs.existsSync(versionFile)) {
+if (!fs.existsSync(libmdbxGitMarker) && !fs.existsSync(versionFile)) {
     console.log('Creating VERSION.json for libmdbx...');
     const versionJson = {
         "git_describe": "v0.13.7",
-        "git_timestamp": "2025-07-30T12:00:00Z", 
+        "git_timestamp": "2025-07-30T12:00:00Z",
         "git_tree": "npm-package",
         "git_commit": "npm-package",
         "semver": "0.13.7"

package/lib/async.d.cts

@@ -0,0 +1,69 @@
+import type { MDBXDbiStat, MDBXEnvOpenOptions, MDBXKey, MDBXValue } from "./types";
+
+export interface MDBXAsyncMapOpenOptions {
+  name?: string;
+  keyMode?: number;
+  valMode?: number;
+  flags?: number;
+  create?: boolean;
+}
+
+export interface MDBXAsyncDbiMeta {
+  name: string;
+  keyMode: number;
+  valMode: number;
+}
+
+export interface MDBXAsyncGetBatchResultItem {
+  key: MDBXKey;
+  value: string | null;
+  found: boolean;
+}
+
+export interface MDBXAsyncPutBatchResultItem {
+  key: MDBXKey;
+  success: boolean;
+  error?: string;
+}
+
+export interface MDBXAsyncDelBatchResultItem {
+  key: MDBXKey;
+  deleted: boolean;
+  error?: string;
+}
+
+declare class MDBX_Async_Dbi {
+  readonly meta: MDBXAsyncDbiMeta;
+
+  put(key: MDBXKey, value: MDBXValue, flags?: number): Promise<boolean>;
+  get(key: MDBXKey): Promise<string | null | undefined>;
+  del(key: MDBXKey): Promise<boolean>;
+  stat(): Promise<MDBXDbiStat>;
+
+  forEach(cb: (key: MDBXKey, value: MDBXValue, index: number) => void): Promise<void>;
+
+  getBatch(keys: MDBXKey[]): Promise<MDBXAsyncGetBatchResultItem[]>;
+  putBatch(items: Array<{ key: MDBXKey; value: MDBXValue }>, flags?: number): Promise<MDBXAsyncPutBatchResultItem[]>;
+  delBatch(keys: MDBXKey[]): Promise<MDBXAsyncDelBatchResultItem[]>;
+}
+
+declare class MDBX_Async_Txn {
+  openMap(opts?: MDBXAsyncMapOpenOptions): Promise<MDBX_Async_Dbi>;
+  commit(): Promise<void>;
+  abort(): Promise<void>;
+}
+
+declare class MDBX_Async_Env {
+  constructor(workerCount?: number);
+  open(opts: MDBXEnvOpenOptions): Promise<void>;
+  close(): Promise<void>;
+  terminate(): Promise<void>;
+  startWrite(): Promise<MDBX_Async_Txn>;
+  startRead(): Promise<MDBX_Async_Txn>;
+}
+
+declare const exportsCjs: {
+  MDBX_Async_Env: typeof MDBX_Async_Env;
+};
+
+export = exportsCjs;

package/lib/async.d.mts

@@ -0,0 +1,65 @@
+import type { MDBXDbiStat, MDBXEnvOpenOptions, MDBXKey, MDBXValue } from "./types.js";
+
+export interface MDBXAsyncMapOpenOptions {
+  name?: string;
+  keyMode?: number;
+  valMode?: number;
+  flags?: number;
+  create?: boolean;
+}
+
+export interface MDBXAsyncDbiMeta {
+  name: string;
+  keyMode: number;
+  valMode: number;
+}
+
+export interface MDBXAsyncGetBatchResultItem {
+  key: MDBXKey;
+  value: string | null;
+  found: boolean;
+}
+
+export interface MDBXAsyncPutBatchResultItem {
+  key: MDBXKey;
+  success: boolean;
+  error?: string;
+}
+
+export interface MDBXAsyncDelBatchResultItem {
+  key: MDBXKey;
+  deleted: boolean;
+  error?: string;
+}
+
+export declare class MDBX_Async_Dbi {
+  readonly meta: MDBXAsyncDbiMeta;
+
+  put(key: MDBXKey, value: MDBXValue, flags?: number): Promise<boolean>;
+  get(key: MDBXKey): Promise<string | null | undefined>;
+  del(key: MDBXKey): Promise<boolean>;
+  stat(): Promise<MDBXDbiStat>;
+
+  forEach(cb: (key: MDBXKey, value: MDBXValue, index: number) => void): Promise<void>;
+
+  getBatch(keys: MDBXKey[]): Promise<MDBXAsyncGetBatchResultItem[]>;
+  putBatch(items: Array<{ key: MDBXKey; value: MDBXValue }>, flags?: number): Promise<MDBXAsyncPutBatchResultItem[]>;
+  delBatch(keys: MDBXKey[]): Promise<MDBXAsyncDelBatchResultItem[]>;
+}
+
+export declare class MDBX_Async_Txn {
+  openMap(opts?: MDBXAsyncMapOpenOptions): Promise<MDBX_Async_Dbi>;
+  commit(): Promise<void>;
+  abort(): Promise<void>;
+}
+
+export declare class MDBX_Async_Env {
+  constructor(workerCount?: number);
+  open(opts: MDBXEnvOpenOptions): Promise<void>;
+  close(): Promise<void>;
+  terminate(): Promise<void>;
+  startWrite(): Promise<MDBX_Async_Txn>;
+  startRead(): Promise<MDBX_Async_Txn>;
+}
+
+export default MDBX_Async_Env;

package/lib/index.d.mts

@@ -0,0 +1,7 @@
+import type { MDBX_Native } from "./types.js";
+
+export * from "./types.js";
+export { MDBX_Async_Env } from "./async.mjs";
+
+declare const native: MDBX_Native;
+export default native;

package/lib/nativemou.d.cts

@@ -0,0 +1,4 @@
+import type { MDBX_Native } from "./types";
+
+declare const native: MDBX_Native;
+export = native;

package/lib/nativemou.d.mts

@@ -0,0 +1,5 @@
+import type { MDBX_Native } from "./types.js";
+
+declare const native: MDBX_Native;
+export default native;
+

package/lib/types.d.ts

@@ -0,0 +1,260 @@
+/// <reference types="node" />
+
+export type MDBXKey = Buffer | string | number | bigint;
+export type MDBXValue = Buffer | string;
+
+export type MDBXCursorMode =
+  | number
+  | "first"
+  | "last"
+  | "next"
+  | "prev"
+  | "keyLesser"
+  | "keyLesserThan"
+  | "key_lesser_than"
+  | "keyLesserOrEqual"
+  | "key_lesser_or_equal"
+  | "keyEqual"
+  | "key_equal"
+  | "keyGreaterOrEqual"
+  | "key_greater_or_equal"
+  | "keyGreater"
+  | "keyGreaterThan"
+  | "key_greater_than"
+  | "multiExactKeyValueLesserThan"
+  | "multi_exactkey_value_lesser_than"
+  | "multiExactKeyValueLesserOrEqual"
+  | "multi_exactkey_value_lesser_or_equal"
+  | "multiExactKeyValueEqual"
+  | "multi_exactkey_value_equal"
+  | "multiExactKeyValueGreaterOrEqual"
+  | "multi_exactkey_value_greater_or_equal"
+  | "multiExactKeyValueGreater"
+  | "multi_exactkey_value_greater";
+
+export interface MDBXEnvGeometryFixed {
+  fixedSize: number;
+}
+
+export interface MDBXEnvGeometryDynamic {
+  dynamicSize: [number, number];
+}
+
+export interface MDBXEnvGeometryCustom {
+  sizeNow?: number;
+  sizeUpper?: number;
+  growthStep?: number;
+  shrinkThreshold?: number;
+  pageSize?: number;
+}
+
+export type MDBXEnvGeometry =
+  | MDBXEnvGeometryFixed
+  | MDBXEnvGeometryDynamic
+  | MDBXEnvGeometryCustom;
+
+export interface MDBXEnvOpenOptions {
+  path: string;
+  flags?: number;
+  keyFlag?: number;
+  valueFlag?: number;
+  maxDbi?: number;
+  mode?: number;
+  geometry?: MDBXEnvGeometry;
+}
+
+export interface MDBXDbiStat {
+  pageSize: number;
+  depth: number;
+  branchPages: number;
+  leafPages: number;
+  overflowPages: number;
+  entries: number;
+  modTxnId: number;
+}
+
+export interface MDBX_Dbi<K extends MDBXKey = MDBXKey, V extends MDBXValue = MDBXValue> {
+  readonly id: bigint;
+  readonly dbMode: number;
+  readonly keyMode: number;
+  readonly valueMode: number;
+  readonly keyFlag: number;
+  readonly valueFlag: number;
+
+  put(txn: MDBX_Txn, key: K, value: MDBXValue): void;
+  get(txn: MDBX_Txn, key: K): V | undefined;
+  del(txn: MDBX_Txn, key: K): boolean;
+  has(txn: MDBX_Txn, key: K): boolean;
+
+  forEach(txn: MDBX_Txn, cb: (key: K, value: V, index: number) => boolean | void): number;
+  forEach(
+    txn: MDBX_Txn,
+    fromKey: K,
+    cb: (key: K, value: V, index: number) => boolean | void
+  ): number;
+  forEach(
+    txn: MDBX_Txn,
+    fromKey: K,
+    cursorMode: MDBXCursorMode,
+    cb: (key: K, value: V, index: number) => boolean | void
+  ): number;
+
+  stat(txn: MDBX_Txn): MDBXDbiStat;
+  keys(txn: MDBX_Txn): K[];
+  keysFrom(txn: MDBX_Txn, fromKey: K, limit?: number, cursorMode?: MDBXCursorMode): K[];
+  drop(txn: MDBX_Txn, deleteDb?: boolean): void;
+}
+
+export interface MDBX_Txn {
+  commit(): void;
+  abort(): void;
+
+  openMap(keyMode: number | bigint): MDBX_Dbi;
+  openMap(name: string): MDBX_Dbi;
+  openMap(name: string, keyMode: number | bigint): MDBX_Dbi;
+
+  createMap(keyMode: number | bigint): MDBX_Dbi;
+  createMap(name: string): MDBX_Dbi;
+  createMap(keyMode: number | bigint, valueMode: number): MDBX_Dbi;
+  createMap(name: string, keyMode: number | bigint): MDBX_Dbi;
+  createMap(name: string, keyMode: number | bigint, valueMode: number): MDBX_Dbi;
+
+  isActive(): boolean;
+  isTopLevel(): boolean;
+
+  startTransaction?: () => MDBX_Txn;
+  getChildrenCount?: () => number;
+}
+
+export interface MDBXQueryItem {
+  key: MDBXKey;
+  value?: MDBXValue;
+}
+
+export interface MDBXQueryRequest {
+  dbi: MDBX_Dbi;
+  mode?: number;
+  queryMode?: number;
+  item: MDBXQueryItem[];
+}
+
+export interface MDBXQueryResultItem {
+  key: MDBXKey;
+  value?: MDBXValue | null;
+  found?: boolean;
+}
+
+export type MDBXQueryResult = MDBXQueryResultItem[] | MDBXQueryResultItem[][];
+
+export interface MDBXKeysRequestObject {
+  dbi: MDBX_Dbi;
+  from?: MDBXKey;
+  limit?: number;
+  cursorMode?: MDBXCursorMode;
+}
+
+export type MDBXKeysRequest = MDBX_Dbi | MDBXKeysRequestObject;
+export type MDBXKeysResult = MDBXKey[] | MDBXKey[][];
+
+export declare class MDBX_Env {
+  constructor();
+
+  open(options: MDBXEnvOpenOptions): Promise<void>;
+  openSync(options: MDBXEnvOpenOptions): void;
+
+  close(): Promise<void>;
+  closeSync(): void;
+
+  copyTo(path: string, flags?: number): Promise<void>;
+  copyToSync(path: string, flags?: number): void;
+
+  version(): string;
+
+  startRead(): MDBX_Txn;
+  startWrite(): MDBX_Txn;
+
+  query(request: MDBXQueryRequest | MDBXQueryRequest[], txnMode?: number): Promise<MDBXQueryResult>;
+  keys(request: MDBXKeysRequest | MDBXKeysRequest[], txnMode?: number): Promise<MDBXKeysResult>;
+}
+
+export interface MDBX_Param {
+  readonly envFlag: {
+    readonly validation: number;
+    readonly rdonly: number;
+    readonly exclusive: number;
+    readonly accede: number;
+    readonly writemap: number;
+    readonly nostickythreads: number;
+    readonly nordahead: number;
+    readonly nomeminit: number;
+    readonly liforeclaim: number;
+    readonly nometasync: number;
+    readonly safeNosync: number;
+    readonly utterlyNosync: number;
+  };
+
+  readonly txnMode: {
+    readonly ro: number;
+  };
+
+  readonly keyMode: {
+    readonly reverse: number;
+    readonly ordinal: number;
+  };
+
+  readonly keyFlag: {
+    readonly string: number;
+    readonly number: number;
+    readonly bigint: number;
+  };
+
+  readonly valueMode: {
+    readonly multi: number;
+    readonly multiReverse: number;
+    readonly multiSamelength: number;
+    readonly multiOrdinal: number;
+    readonly multiReverseSamelength: number;
+  };
+
+  readonly valueFlag: {
+    readonly string: number;
+  };
+
+  readonly dbMode: {
+    readonly create: number;
+    readonly accede: number;
+  };
+
+  readonly queryMode: {
+    readonly upsert: number;
+    readonly update: number;
+    readonly insertUnique: number;
+    readonly get: number;
+    readonly del: number;
+  };
+
+  readonly cursorMode: {
+    readonly first: number;
+    readonly last: number;
+    readonly next: number;
+    readonly prev: number;
+    readonly keyLesserThan: number;
+    readonly keyLesserOrEqual: number;
+    readonly keyEqual: number;
+    readonly keyGreaterOrEqual: number;
+    readonly keyGreaterThan: number;
+    readonly multiExactKeyValueLesserThan: number;
+    readonly multiExactKeyValueLesserOrEqual: number;
+    readonly multiExactKeyValueEqual: number;
+    readonly multiExactKeyValueGreaterOrEqual: number;
+    readonly multiExactKeyValueGreater: number;
+  };
+}
+
+export declare const MDBX_Param: MDBX_Param;
+
+export interface MDBX_Native {
+  MDBX_Env: typeof MDBX_Env;
+  MDBX_Param: MDBX_Param;
+}
+

package/package.json

@@ -1,15 +1,37 @@
 {
   "main": "lib/nativemou.js",
+  "types": "./lib/index.d.mts",
   "exports": {
     ".": {
-      "import": "./lib/index.mjs",
-      "require": "./lib/nativemou.js"
+      "import": {
+        "types": "./lib/index.d.mts",
+        "default": "./lib/index.mjs"
+      },
+      "require": {
+        "types": "./lib/nativemou.d.cts",
+        "default": "./lib/nativemou.js"
+      }
     },
     "./async": {
-      "import": "./lib/async.mjs",
-      "require": "./lib/mdbx_evn_async.js"
+      "import": {
+        "types": "./lib/async.d.mts",
+        "default": "./lib/async.mjs"
+      },
+      "require": {
+        "types": "./lib/async.d.cts",
+        "default": "./lib/mdbx_evn_async.js"
+      }
+    },
+    "./nativemou": {
+      "import": {
+        "types": "./lib/nativemou.d.mts",
+        "default": "./lib/nativemou.js"
+      },
+      "require": {
+        "types": "./lib/nativemou.d.cts",
+        "default": "./lib/nativemou.js"
+      }
     },
-    "./nativemou": "./lib/nativemou.js",
     "./package.json": "./package.json"
   },
   "files": [
@@ -26,19 +48,24 @@
     "cmake-js": "^7.3.1",
     "node-addon-api": "^8.5.0"
   },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "typescript": "^5.6.3"
+  },
   "scripts": {
     "e3": "node ./test/e3.js",
     "e33": "node ./test/e33.js",
     "e4": "node ./test/e4.js",
     "e4async": "node ./test/e4async.mjs",
     "e5": "node ./test/e5.js",
+    "test:types": "node ./test/types/run.mjs",
     "build": "node build.js",
     "build-dev": "node build-dev.js",
     "install": "node build.js"
   },
   "gypfile": true,
   "name": "mdbxmou",
-  "version": "0.2.4",
+  "version": "0.2.6",
   "description": "Node bindings for mdbx",
   "repository": {
     "type": "git",