@benjosivo/mysql 1.0.3

package/README.md

@@ -0,0 +1,110 @@
+# @benjosivo/mysql
+
+Shared MySQL client (pooling, automatic retry on deadlock/lock-timeout, transaction helpers) for use across multiple projects. Nothing connects until you call `init()` — the package has no side effects at import time and no dependency on any particular env var naming.
+
+## Install
+
+This package is published to **GitHub Packages**, not the public npm registry, so every machine needs a one-time setup before `npm install` will work — even though the repo and package are public. GitHub Packages never allows anonymous installs; a valid GitHub token is always required.
+
+### One-time setup (per machine)
+
+1. **Create a GitHub Personal Access Token.**
+   GitHub → click your avatar → **Settings** → **Developer settings** → **Personal access tokens** → **Tokens (classic)** → **Generate new token (classic)**.
+   Scope needed: **`read:packages`**. Copy the token — GitHub only shows it once.
+
+2. **Add two lines to your global npm config.**
+   Find the file path:
+   ```
+   npm config get globalconfig
+   ```
+   It's typically `C:\Users\<you>\AppData\Roaming\npm\etc\npmrc` on Windows. Open that file in a text editor and add:
+   ```
+   @benjosivo:registry=https://npm.pkg.github.com
+   //npm.pkg.github.com/:_authToken=YOUR_TOKEN_HERE
+   ```
+   Editing the file directly is more reliable than `npm config set` — on some npm versions, `npm config set @benjosivo:registry=... --global` fails with a cryptic `` `` is not a valid npm option `` error. If you'd rather use the CLI, use the space-separated form instead of `=`:
+   ```
+   npm config set @benjosivo:registry https://npm.pkg.github.com --global
+   ```
+
+3. **Verify both lines took effect:**
+   ```
+   npm config list
+   ```
+   You should see both `@benjosivo:registry = "https://npm.pkg.github.com"` and `//npm.pkg.github.com/:_authToken = (protected)` in the output.
+
+### Install
+
+```
+npm install @benjosivo/mysql
+```
+
+### Troubleshooting
+
+- **`404 Not Found - GET https://registry.npmjs.org/@benjosivo%2fmysql`** — npm is checking the default npm registry instead of GitHub Packages. This means the `@benjosivo:registry` line from step 2 above isn't set (check with `npm config get @benjosivo:registry`). Add it and retry.
+- **401/403 or `ENEEDAUTH`** — the auth token is missing, expired, or lacks `read:packages` scope. Regenerate a token and re-add it.
+
+## Usage
+
+```ts
+import { init, executeMySQLQuery, closeMySQLConnection } from '@benjosivo/mysql';
+
+await init({
+    host: process.env.DB_HOST!,
+    user: process.env.DB_USER!,
+    password: process.env.DB_PASSWORD!,
+    database: process.env.DB_NAME!,
+    onError: (error, context) => myLogger.error(context, error), // optional, defaults to console.error
+});
+
+const rows = await executeMySQLQuery('SELECT * FROM users WHERE id = ?', [userId]);
+
+// on shutdown
+await closeMySQLConnection();
+```
+
+Call `init()` once per process, at startup. Each consuming project supplies its own credentials and (optionally) its own error reporting — this package has no opinion on either.
+
+### Config
+
+| Field | Required | Default | Description |
+|---|---|---|---|
+| `host`, `user`, `password`, `database` | yes | — | MySQL connection details |
+| `waitForConnections` | no | `true` | passed through to `mysql2` pool |
+| `connectionLimit` | no | `50` | passed through to `mysql2` pool |
+| `queueLimit` | no | `0` | passed through to `mysql2` pool |
+| `multipleStatements` | no | `true` | passed through to `mysql2` pool |
+| `staleTransactionMs` | no | `300000` (5 min) | idle transactions older than this are auto rolled back |
+| `onError` | no | `console.error` | called with `(error, context)` whenever the client can't throw the error directly (e.g. background retry loops) |
+
+Calling `init()` again (e.g. to reconfigure) closes the previous pool first.
+
+### Queries
+
+```ts
+executeMySQLQuery(query, values?, returnFieldTypes?, connKey?)
+```
+
+Returns the rows directly on success. On failure it returns `{ error, values, connKey }` instead of throwing (matches `mysql2`'s row-result shape so existing call sites don't need try/catch).
+
+### Transactions
+
+```ts
+const { connKey, error } = await executeMySQLQuery2({ query: 'INSERT ...', values, connKey: true });
+if (error) { /* handle */ }
+
+await executeMySQLQuery2({ query: 'UPDATE ...', values, connKey }); // reuse the same transaction
+
+await connectionCommit(connKey);
+// or: await connectionRollback(connKey);
+```
+
+Transactions left open longer than `staleTransactionMs` are automatically rolled back by a background sweep.
+
+### Shutdown
+
+```ts
+await closeMySQLConnection();
+```
+
+Rolls back any open transactions, ends the pool, and stops the background sweep. Safe to call even if `init()` was never called.

package/dist/index.d.ts

@@ -0,0 +1,32 @@
+export interface MySQLClientConfig {
+    host: string;
+    user: string;
+    password: string;
+    database: string;
+    waitForConnections?: boolean;
+    connectionLimit?: number;
+    queueLimit?: number;
+    multipleStatements?: boolean;
+    /** How long an open transaction can sit idle before it's automatically rolled back. Default: 5 minutes. */
+    staleTransactionMs?: number;
+    /** Called whenever this client encounters an error it can't throw directly (e.g. inside retry loops). Defaults to console.error. */
+    onError?: (error: unknown, context: string) => void;
+}
+export declare function init(clientConfig: MySQLClientConfig): Promise<void>;
+export declare function closeMySQLConnection(): Promise<void>;
+export declare function loopKillOpenTRX(): void;
+export declare function stopLoopKillOpenTRX(): void;
+export declare function executeMySQLQuery(query: string, values?: any[], returnFieldTypes?: boolean, connKey?: boolean | string): Promise<any>;
+export declare function executeMySQLQuery2(opt: {
+    query: string;
+    values?: any[];
+    connKey?: boolean | string;
+    returnFieldTypes?: boolean;
+    returnListTables?: boolean | string;
+}): Promise<any>;
+export declare function connectionCommit(keyConn: string): Promise<{
+    error?: unknown;
+}>;
+export declare function connectionRollback(keyConn: string): Promise<{
+    error?: unknown;
+}>;

package/dist/index.js

@@ -0,0 +1,423 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.init = init;
+exports.closeMySQLConnection = closeMySQLConnection;
+exports.loopKillOpenTRX = loopKillOpenTRX;
+exports.stopLoopKillOpenTRX = stopLoopKillOpenTRX;
+exports.executeMySQLQuery = executeMySQLQuery;
+exports.executeMySQLQuery2 = executeMySQLQuery2;
+exports.connectionCommit = connectionCommit;
+exports.connectionRollback = connectionRollback;
+const crypto_1 = require("crypto");
+const parserModule = __importStar(require("node-sql-parser"));
+const promise_1 = __importDefault(require("mysql2/promise"));
+let config;
+let pool;
+let lastConnectionCheck = 0;
+function defaultOnError(error, context) {
+    console.error(`[mysql-client] ${context}`, error);
+}
+function handleError(error, context) {
+    (config?.onError ?? defaultOnError)(error, context);
+}
+function requireConfig() {
+    if (!config)
+        throw new Error('MySQL client not initialized. Call init(config) before using this package.');
+    return config;
+}
+function requirePool() {
+    if (!pool)
+        throw new Error('MySQL client not initialized. Call init(config) before using this package.');
+    return pool;
+}
+function createPool() {
+    const cfg = requireConfig();
+    pool = promise_1.default.createPool({
+        host: cfg.host,
+        user: cfg.user,
+        password: cfg.password,
+        database: cfg.database,
+        waitForConnections: cfg.waitForConnections ?? true,
+        connectionLimit: cfg.connectionLimit ?? 50,
+        queueLimit: cfg.queueLimit ?? 0,
+        multipleStatements: cfg.multipleStatements ?? true,
+    });
+}
+async function init(clientConfig) {
+    if (pool)
+        await closeMySQLConnection();
+    config = clientConfig;
+    createPool();
+    loopKillOpenTRX();
+}
+async function closeMySQLConnection() {
+    stopLoopKillOpenTRX();
+    if (!pool)
+        return;
+    const rollbackPromises = [...listTransaction.keys()].map(connectionRollback);
+    await Promise.all(rollbackPromises);
+    try {
+        await pool.end();
+    }
+    catch { }
+    pool = undefined;
+    config = undefined;
+    lastConnectionCheck = 0;
+}
+const listTransaction = new Map();
+let killOpenTRXInterval = null;
+async function killOpenTRX() {
+    const staleTransactionMs = config?.staleTransactionMs ?? 5 * 60000;
+    const rollbackPromises = [];
+    for (const [key, value] of listTransaction) {
+        if (value.timestamp + staleTransactionMs < Date.now()) {
+            rollbackPromises.push(connectionRollback(key));
+        }
+    }
+    await Promise.all(rollbackPromises);
+}
+function loopKillOpenTRX() {
+    if (killOpenTRXInterval)
+        return;
+    killOpenTRXInterval = setInterval(killOpenTRX, 1000);
+}
+function stopLoopKillOpenTRX() {
+    if (!killOpenTRXInterval)
+        return;
+    clearInterval(killOpenTRXInterval);
+    killOpenTRXInterval = null;
+}
+async function ensurePool() {
+    try {
+        const conn = await requirePool().getConnection();
+        conn.release();
+        lastConnectionCheck = Date.now();
+    }
+    catch {
+        try {
+            await requirePool().end();
+        }
+        catch { }
+        try {
+            createPool();
+        }
+        catch (err) {
+            handleError(err, 'MySQL: ensurePool — could not recreate pool');
+        }
+    }
+}
+async function executeMySQLQuery(query, values = [], returnFieldTypes = false, connKey) {
+    return executeMySQLQuery2({ query, values, returnFieldTypes, connKey });
+}
+async function executeMySQLQuery2(opt) {
+    requireConfig();
+    const { query, values = [], returnFieldTypes = false, returnListTables = false } = opt;
+    let { connKey } = opt;
+    async function executeWithRetry(opt) {
+        /**
+         * Executes a query with automatic retry on deadlock and lock timeout.
+         *
+         * - `callerOwnsConnection`: caller holds a transaction and manages commit/rollback.
+         *     - Deadlock   → transaction already rolled back by MySQL, throw immediately.
+         *     - Timeout    → statement rolled back, transaction still alive — wait and retry
+         *                    up to MAX_EXECUTE_ATTEMPTS; throw on last attempt so caller rollbacks.
+         * - `createsNewTransaction`: we own the transaction internally.
+         *     - Deadlock   → rollback + recreate transaction, retry.
+         *     - Timeout    → rollback + recreate transaction, retry with longer delay.
+         * - Neither (plain pool):
+         *     - Both       → wait (with appropriate delay) and retry against the pool.
+         */
+        const { query, values, callerOwnsConnection, createsNewTransaction } = opt;
+        let { conn, connKey } = opt;
+        function isConnectionLost(error) {
+            return (error?.code === 'PROTOCOL_CONNECTION_LOST' ||
+                error?.code === 'ECONNRESET' ||
+                error?.code === 'ECONNREFUSED' ||
+                error?.code === 'PROTOCOL_ENQUEUE_AFTER_FATAL_ERROR' ||
+                error?.fatal === true);
+        }
+        for (let attempt = 1; attempt <= MAX_EXECUTE_ATTEMPTS; attempt++) {
+            try {
+                const [rows, fields] = await (conn ?? requirePool()).execute(query, values);
+                if (conn && connKey) {
+                    const activeTr = listTransaction.get(connKey);
+                    if (activeTr) {
+                        activeTr.lastValidConn = conn;
+                    }
+                }
+                return { rows, fields: fields, connKey };
+            }
+            catch (error) {
+                const isDeadlock = error?.code === 'ER_LOCK_DEADLOCK';
+                const isLockTimeout = error?.code === 'ER_LOCK_WAIT_TIMEOUT';
+                const isLockError = isDeadlock || isLockTimeout;
+                const isConnLost = isConnectionLost(error);
+                if (attempt === MAX_EXECUTE_ATTEMPTS) {
+                    if (createsNewTransaction && connKey) {
+                        try {
+                            await connectionRollback(connKey);
+                        }
+                        catch { }
+                    }
+                    throw error;
+                }
+                // Fatal connection loss requires cleanup.
+                if (isConnLost) {
+                    if (createsNewTransaction && connKey) {
+                        try {
+                            await connectionRollback(connKey);
+                        }
+                        catch { }
+                        conn = undefined;
+                        const reqTr = await createTransaction();
+                        if ('error' in reqTr)
+                            throw new Error('Failed to recreate transaction after lost connection');
+                        conn = reqTr.conn;
+                        connKey = reqTr.connKey;
+                        continue;
+                    }
+                    if (callerOwnsConnection) {
+                        throw error;
+                    }
+                    await ensurePool();
+                    continue;
+                }
+                // Deadlock + caller-owned: MySQL already rolled back the entire transaction,
+                // retrying on the same connection is not possible — throw so the caller rollbacks.
+                if (isDeadlock && callerOwnsConnection) {
+                    if (connKey)
+                        connectionRollback(connKey);
+                    throw error;
+                }
+                // Non-lock error: re-check the pool and retry
+                if (!isLockError) {
+                    if (!conn)
+                        await ensurePool(); // pool health is irrelevant when we own a connection
+                    continue;
+                }
+                // Timeout + caller-owned: only the statement was rolled back, the transaction
+                // is still alive — wait and retry the statement on the same connection.
+                // The caller will rollback the transaction itself if we ultimately throw.
+                if (isLockTimeout && callerOwnsConnection) {
+                    await new Promise((r) => setTimeout(r, LOCK_TIMEOUT_RETRY_DELAY_MS * attempt));
+                    continue;
+                }
+                // Deadlock: MySQL already rolled back the transaction — retry quickly.
+                // Timeout:  something is holding a lock — wait longer before retrying.
+                const retryDelay = isDeadlock ? DEADLOCK_RETRY_DELAY_MS : LOCK_TIMEOUT_RETRY_DELAY_MS;
+                await new Promise((r) => setTimeout(r, retryDelay * attempt));
+                if (createsNewTransaction) {
+                    // For both error types, our transaction is no longer usable — recreate it
+                    try {
+                        conn?.release();
+                    }
+                    catch { }
+                    conn = undefined;
+                    const reqTr = await createTransaction();
+                    if ('error' in reqTr)
+                        throw new Error(`Failed to recreate transaction after ${isDeadlock ? 'deadlock' : 'lock timeout'}`);
+                    conn = reqTr.conn;
+                    connKey = reqTr.connKey;
+                }
+            }
+        }
+        throw new Error('MySQL: executeWithRetry reached unexpected end');
+    }
+    function checkStoredProcedureResult(rows, query) {
+        const message = rows?.[0]?.[0]?.['@message'] ?? '';
+        if (!message.toLowerCase().startsWith('ok')) {
+            return message || `No message returned from procedure: ${query}`;
+        }
+        return null;
+    }
+    function resolveFieldTypes(fields) {
+        if (!promise_1.default.Types)
+            throw new Error('mysql.Types is not available');
+        return fields.map((field) => {
+            const typeName = Object.keys(promise_1.default.Types).find((key) => promise_1.default.Types[key] === field.type);
+            return { fieldName: field.name, fieldType: typeName ?? '' };
+        });
+    }
+    function getTablesFromQuery(query) {
+        try {
+            const { Parser } = parserModule.default ?? parserModule;
+            const parser = new Parser();
+            const { tableList } = parser.parse(query);
+            const cleanTableList = tableList.map((table) => {
+                const parts = table.split('::');
+                return parts[parts.length - 1];
+            });
+            return cleanTableList;
+        }
+        catch {
+            return [];
+        }
+    }
+    const DEADLOCK_RETRY_DELAY_MS = 100;
+    const LOCK_TIMEOUT_RETRY_DELAY_MS = 500;
+    const MAX_EXECUTE_ATTEMPTS = 5;
+    const createsNewTransaction = connKey === true;
+    const usesExistingTransaction = !!connKey && typeof connKey === 'string';
+    if (lastConnectionCheck + 5 * 60000 <= Date.now() && !usesExistingTransaction) {
+        await ensurePool();
+    }
+    let conn;
+    try {
+        if (createsNewTransaction) {
+            const reqTr = await createTransaction();
+            if ('error' in reqTr)
+                return { error: reqTr.error };
+            connKey = reqTr.connKey;
+            conn = reqTr.conn;
+        }
+        else if (usesExistingTransaction && typeof connKey === 'string') {
+            const tr = listTransaction.get(connKey);
+            if (!tr) {
+                const msg = `Transaction key not found: ${connKey}`;
+                handleError(msg, 'MySQL: executeMySQLQuery2');
+                return { error: msg };
+            }
+            tr.lastUpdate = Date.now();
+            conn = tr.conn;
+        }
+        const { rows, fields, connKey: updatedConnKey, } = await executeWithRetry({
+            query,
+            values,
+            conn,
+            connKey: typeof connKey === 'string' ? connKey : undefined,
+            callerOwnsConnection: usesExistingTransaction,
+            createsNewTransaction,
+        });
+        if (updatedConnKey)
+            connKey = updatedConnKey;
+        if (query.trim().toLowerCase().startsWith('call')) {
+            const procError = checkStoredProcedureResult(rows, query);
+            if (procError) {
+                if (createsNewTransaction && typeof connKey === 'string') {
+                    try {
+                        await connectionRollback(connKey);
+                    }
+                    catch { }
+                }
+                return { error: procError, values };
+            }
+        }
+        const fieldsType = returnFieldTypes ? resolveFieldTypes(fields) : [];
+        const tables = returnListTables ? getTablesFromQuery(query) : [];
+        if (createsNewTransaction || returnFieldTypes || returnListTables) {
+            return { rows, fieldsType, connKey, tables };
+        }
+        return rows;
+    }
+    catch (error) {
+        try {
+            const errorMsg = String(error?.message ?? error);
+            const queryStr = query.length > 200 ? `${query.substring(0, 200)}...` : query;
+            if (connKey && typeof connKey === 'string' && errorMsg.includes('new command when connection is in closed state')) {
+                const activeTr = listTransaction.get(connKey);
+                if (activeTr) {
+                    console.log(`lastValidConn (lastUpdate : ${activeTr.lastUpdate}) : `);
+                    console.log(activeTr.lastValidConn);
+                    console.log(`conn (creation : ${activeTr.creation})  : `);
+                    console.log(conn);
+                }
+            }
+            handleError(error, `MySQL${error?.code ? ` [${error.code}]` : ''}${connKey ? ' (using connection)' : ''}\n${errorMsg}\n\nparams: ${values}\n\nquery: ${queryStr}`);
+        }
+        catch (handlingError) {
+            handleError(handlingError, 'MySQL: error inside error handler');
+        }
+        if (error?.code === 'ER_LOCK_DEADLOCK' || error?.code === 'ER_LOCK_WAIT_TIMEOUT') {
+            return { error: 'A lock error occurred, please retry', values, connKey: connKey ?? null };
+        }
+        return { error: error?.message ?? error, values, connKey: connKey ?? null };
+    }
+}
+async function createTransaction() {
+    const keyConn = (0, crypto_1.randomUUID)();
+    try {
+        await ensurePool();
+        const conn = await requirePool().getConnection();
+        await conn.beginTransaction();
+        listTransaction.set(keyConn, { conn, timestamp: Date.now(), lastUpdate: Date.now(), lastValidConn: conn, creation: Date.now() });
+        return { conn, connKey: keyConn };
+    }
+    catch (error) {
+        handleError(error, 'MySQL: createTransaction');
+        try {
+            listTransaction.delete(keyConn);
+        }
+        catch { }
+        return { error };
+    }
+}
+async function connectionCommit(keyConn) {
+    const tr = listTransaction.get(keyConn);
+    if (!tr) {
+        const msg = `Transaction key not found: ${keyConn}`;
+        handleError(msg, 'MySQL: connectionCommit');
+        return { error: msg };
+    }
+    try {
+        await tr.conn.commit();
+        await tr.conn.release();
+        listTransaction.delete(keyConn);
+        return {};
+    }
+    catch (error) {
+        handleError(error, 'MySQL: connectionCommit');
+        return { error };
+    }
+}
+async function connectionRollback(keyConn) {
+    const tr = listTransaction.get(keyConn);
+    if (!tr) {
+        handleError(`Transaction key not found: ${keyConn}`, 'MySQL: connectionRollback');
+        return { error: `Transaction key not found: ${keyConn}` };
+    }
+    try {
+        await tr.conn.rollback();
+        await tr.conn.release();
+        listTransaction.delete(keyConn);
+        return {};
+    }
+    catch (error) {
+        return { error };
+    }
+}

package/package.json

@@ -0,0 +1,22 @@
+{
+    "name": "@benjosivo/mysql",
+    "version": "1.0.3",
+    "main": "dist/index.js",
+    "types": "dist/index.d.ts",
+    "files": [
+        "dist"
+    ],
+    "scripts": {
+        "build": "tsc",
+        "prepublishOnly": "npm run build"
+    },
+    "dependencies": {
+        "mysql2": "^3.x",
+        "node-sql-parser": "^5.4.0"
+    },
+    "devDependencies": {
+        "@types/node": "^26.1.2",
+        "typescript": "^7.0.2"
+    },
+    "license": "MIT"
+}