@jclanker/dbmanager 1.0.0

package/README.md

@@ -0,0 +1,82 @@
+# dbmanager
+
+A small promise-based wrapper around [better-sqlite3](https://github.com/WiseLibs/better-sqlite3).
+
+- Opens the database in WAL mode.
+- Every method returns a Promise, so it drops into async code that expects an async DB API.
+- Batch helpers run one prepared statement over many parameter sets, inside a single transaction.
+- Optional per-query timing logs.
+
+## Install
+
+```sh
+npm install @jclanker/dbmanager
+```
+
+## Usage
+
+```js
+const DbManager = require('@jclanker/dbmanager')
+
+const db = new DbManager('./data.db', true)   // (path, showLogs = false)
+
+await db.runQuery('CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, name TEXT)')
+
+const { lastID, changes } = await db.runQuery('INSERT INTO users (name) VALUES (?)', ['alice'])
+const { result: user } = await db.getQuery('SELECT * FROM users WHERE id = ?', [lastID])
+const { result: users } = await db.allQuery('SELECT * FROM users')
+
+// Named parameters work too
+await db.runQuery('UPDATE users SET name = @name WHERE id = @id', { id: 1, name: 'bob' })
+
+db.close()
+```
+
+### Batches
+
+```js
+// One transaction; if any row fails, the whole batch is rolled back
+const { changes } = await db.statementRun(
+    'INSERT INTO users (name) VALUES (?)',
+    [['carol'], ['dave']]
+)
+
+// Returns the rowid of each inserted row (no transaction; see note below)
+const { lastIDs, changesList } = await db.statementRunReturningIds(
+    'INSERT INTO users (name) VALUES (?)',
+    [['erin'], ['frank']]
+)
+
+// Runs the query once per parameter set, in one transaction, and concatenates the rows
+const { result } = await db.statementAll(
+    'SELECT * FROM users WHERE name = ?',
+    [['carol'], ['erin']]
+)
+```
+
+## API
+
+| Method | Resolves to |
+| --- | --- |
+| `new DbManager(path, showLogs = false)` | Opens (or creates) the database and enables WAL |
+| `runQuery(sql, params = [])` | `{ changes, lastID, result: null }` |
+| `getQuery(sql, params = [])` | `{ result }`: the first row, or `undefined` |
+| `allQuery(sql, params = [])` | `{ result }`: an array of rows |
+| `statementRun(sql, paramsList)` | `{ changes }`: total changes, in one transaction |
+| `statementRunReturningIds(sql, paramsList)` | `{ lastIDs, changesList, changes }` |
+| `statementAll(sql, paramsList)` | `{ result }`: concatenated rows, in one transaction |
+| `close()` | Closes the database (synchronous) |
+| `db` | The underlying better-sqlite3 `Database`, for anything else |
+
+Errors (SQL errors, constraint violations) reject the returned Promise.
+
+**Note:** better-sqlite3 is synchronous: each query runs and blocks when you call the method, and
+the returned Promise is already settled. The Promise wrapper gives you an async-style interface;
+it doesn't move work off the main thread.
+
+`statementRunReturningIds` does not wrap its rows in a transaction, so rows inserted before a
+failure stay inserted. Wrap the call in `db.db.transaction(...)` yourself if you need it atomic.
+
+## License
+
+ISC

package/index.d.ts

@@ -0,0 +1,46 @@
+import type BetterSqlite3 from 'better-sqlite3'
+
+declare class DbManager {
+    constructor(path: string, showLogs?: boolean)
+    readonly db: BetterSqlite3.Database
+    showLogs: boolean
+    close(): void
+    runQuery(sql: string, params?: DbManager.Params): Promise<DbManager.RunResult>
+    getQuery<T = any>(sql: string, params?: DbManager.Params): Promise<DbManager.GetResult<T>>
+    allQuery<T = any>(sql: string, params?: DbManager.Params): Promise<DbManager.AllResult<T>>
+    statementRun(sql: string, params: DbManager.Params[]): Promise<DbManager.StatementRunResult>
+    statementRunReturningIds(sql: string, params: DbManager.Params[]): Promise<DbManager.StatementRunReturningIdsResult>
+    statementAll<T = any>(sql: string, params: DbManager.Params[]): Promise<DbManager.AllResult<T>>
+}
+
+declare namespace DbManager {
+    export { DbManager, DbManager as default }
+
+    export type Params = unknown[] | Record<string, unknown>
+
+    export interface RunResult {
+        changes: number
+        lastID: number | bigint
+        result: null
+    }
+
+    export interface GetResult<T = any> {
+        result: T | undefined
+    }
+
+    export interface AllResult<T = any> {
+        result: T[]
+    }
+
+    export interface StatementRunResult {
+        changes: number
+    }
+
+    export interface StatementRunReturningIdsResult {
+        lastIDs: Array<number | bigint>
+        changesList: number[]
+        changes: number
+    }
+}
+
+export = DbManager

package/index.js

@@ -0,0 +1,90 @@
+const Database = require('better-sqlite3')
+
+class DbManager {
+    constructor(path, showLogs = false) {
+        this.db = new Database(path)
+        this.showLogs = showLogs
+        this.db.pragma('journal_mode = WAL')
+        if (this.showLogs) {
+            console.log('better-sqlite3 db init', path)
+        }
+    }
+
+    close() {
+        this.db.close()
+    }
+
+    _exec(label, sql, logParams, fn) {
+        return new Promise((resolve, reject) => {
+            try {
+                const t1 = this.showLogs ? performance.now() : 0
+                const result = fn(this.db.prepare(sql))
+                if (this.showLogs) {
+                    const t2 = performance.now()
+                    console.log(label, sql, logParams, `(${t2 - t1}ms)`)
+                }
+                resolve(result)
+            } catch (err) {
+                reject(err)
+            }
+        })
+    }
+
+    runQuery(sql, params = []) {
+        return this._exec('run', sql, params, (statement) => {
+            const { changes, lastInsertRowid } = statement.run(params)
+            return { changes, lastID: lastInsertRowid, result: null }
+        })
+    }
+
+    getQuery(sql, params = []) {
+        return this._exec('get', sql, params, (statement) => ({ result: statement.get(params) }))
+    }
+
+    allQuery(sql, params = []) {
+        return this._exec('all', sql, params, (statement) => ({ result: statement.all(params) }))
+    }
+
+    statementRun(sql, params) {
+        return this._exec('statementRun', sql, params.length, (statement) => {
+            const runMany = this.db.transaction((items) => {
+                let totalChanges = 0
+                for (const item of items) {
+                    totalChanges += statement.run(item).changes
+                }
+                return totalChanges
+            })
+            return { changes: runMany(params) }
+        })
+    }
+
+    statementRunReturningIds(sql, params) {
+        return this._exec('statementRunReturningIds', sql, params.length, (statement) => {
+            const lastIDs = []
+            const changesList = []
+            for (const item of params) {
+                const { lastInsertRowid, changes } = statement.run(item)
+                lastIDs.push(lastInsertRowid)
+                changesList.push(changes)
+            }
+            return { lastIDs, changesList, changes: lastIDs.length }
+        })
+    }
+
+    statementAll(sql, params) {
+        return this._exec('statementAll', sql, params.length, (statement) => {
+            const getMany = this.db.transaction((items) => {
+                const allResults = []
+                for (const item of items) {
+                    allResults.push(...statement.all(item))
+                }
+                return allResults
+            })
+            return { result: getMany(params) }
+        })
+    }
+}
+
+module.exports = DbManager
+module.exports.DbManager = DbManager
+module.exports.default = DbManager

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@jclanker/dbmanager",
+  "version": "1.0.0",
+  "description": "Small promise-based wrapper around better-sqlite3 with WAL mode, batched transactional statements and optional query timing logs",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jclanker/dbmanager.git"
+  },
+  "author": "jclanker",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "files": [
+    "index.js",
+    "index.d.ts"
+  ],
+  "scripts": {
+    "test": "node --test"
+  },
+  "keywords": [
+    "sqlite",
+    "sqlite3",
+    "better-sqlite3",
+    "database",
+    "promise",
+    "wal"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "better-sqlite3": "^12.10.0",
+    "@types/better-sqlite3": "^9.6.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "ISC"
+}