documentaton

Author: gms1

memory-bank/development.md

@@ -75,7 +75,8 @@ test/
 ├── unicode.test.js      # Unicode handling tests
 ├── update_hook.test.js  # Update hook tests
 ├── upsert.test.js       # UPSERT tests
-└── verbose.test.js      # Verbose mode tests
+├── verbose.test.js      # Verbose mode tests
+└── promise.test.js      # Promise API tests
 ```
 
 ### Running Specific Tests
@@ -138,6 +139,47 @@ db.on('profile', (sql, time) => {
 });
 ```
 
+## Promise API
+
+The project includes Promise-based wrappers for modern async/await support:
+
+### Using Promise API
+
+```javascript
+const { SqliteDatabase } = require('@homeofthings/sqlite3/promise');
+
+// Static factory method
+const db = await SqliteDatabase.open(':memory:');
+
+// Run queries
+const result = await db.run('CREATE TABLE foo (id INT, name TEXT)');
+const row = await db.get('SELECT * FROM foo WHERE id = ?', [1]);
+const rows = await db.all('SELECT * FROM foo');
+
+// Transactions
+await db.beginTransaction();
+await db.run('INSERT INTO foo VALUES (1, "test")');
+await db.commitTransaction();
+
+// Prepared statements
+const stmt = await db.prepare('INSERT INTO foo VALUES (?, ?)');
+await stmt.run(1, 'test');
+await stmt.finalize();
+
+// Close
+await db.close();
+```
+
+### Promise Classes
+
+| Class             | Description                     |
+|-------------------|---------------------------------|
+| `SqliteDatabase`  | Promise wrapper for `Database`  |
+| `SqliteStatement` | Promise wrapper for `Statement` |
+| `SqliteBackup`    | Promise wrapper for `Backup`    |
+
+See [`lib/promise/`](../lib/promise/) for implementation details.
+
 ## Code Style
 
 ### Linting

memory-bank/project-overview.md

@@ -18,7 +18,12 @@ node-sqlite3/
 │   ├── sqlite3.js          # Main module entry point
 │   ├── sqlite3-binding.js  # Native binding loader
 │   ├── sqlite3.d.ts        # TypeScript declarations
-│   └── trace.js            # Stack trace augmentation for verbose mode
+│   ├── trace.js            # Stack trace augmentation for verbose mode
+│   └── promise/            # Promise-based API wrappers
+│       ├── index.js        # Promise module exports
+│       ├── database.js     # SqliteDatabase class
+│       ├── statement.js    # SqliteStatement class
+│       └── backup.js       # SqliteBackup class
 ├── src/                    # C++ native addon
 │   ├── node_sqlite3.cc     # Main addon entry
 │   ├── database.cc/h       # Database class
@@ -52,6 +57,13 @@ node-sqlite3/
 - **trace.js**: Stack trace augmentation for verbose mode
   - Extends error stack traces to include operation context
 
+- **promise/**: Promise-based API wrappers (modern async/await support)
+  - `SqliteDatabase` class: `open()`, `close()`, `run()`, `get()`, `all()`, `each()`, `exec()`, `prepare()`, `backup()`
+  - `SqliteStatement` class: `bind()`, `reset()`, `finalize()`, `run()`, `get()`, `all()`, `each()`
+  - `SqliteBackup` class: `step()`, `finish()`
+  - Transaction support: `beginTransaction()`, `commitTransaction()`, `rollbackTransaction()`
+  - Static factory: `SqliteDatabase.open(filename, mode)`
+
 ### Native Layer (src/)
 
 - **node_sqlite3.cc**: Module initialization, exports `Database`, `Statement`, `Backup` classes