@grest-ts/db-mysql 0.0.5

package/src/GGMysql.ts

@@ -0,0 +1,142 @@
+import mysql, {Pool, ResultSetHeader, RowDataPacket} from 'mysql2/promise';
+import {GGLocator, GGLocatorServiceType} from '@grest-ts/locator';
+import {GGLog} from '@grest-ts/logger';
+import {GGMysqlConnection} from './GGMysqlConnection';
+import type {GGMysqlConfig} from "./GGMysqlConfig";
+
+export class GGMysql {
+
+    private readonly config: GGMysqlConfig;
+
+    private started = false;
+
+    private pool: Pool | undefined = null;
+    private unwatchHost: (() => void) | undefined = undefined;
+    private unwatchUser: (() => void) | undefined = undefined;
+
+    constructor(config: GGMysqlConfig) {
+        this.config = config
+
+        this.unwatchHost = this.config.host.watch(() => this.connect().catch(() => {}));
+        this.unwatchUser = this.config.user.watch(() => this.connect().catch(() => {}));
+
+        GGLocator.getScope().setWithLifecycle(this.config.token, this, {
+            type: GGLocatorServiceType.DATABASE,
+            start: () => this.start(),
+            teardown: () => this.teardown(),
+        });
+    }
+
+    private async connect(): Promise<void> {
+        if (!this.started) {
+            return;
+        }
+
+        const config = this.config.host.get();
+        const user = this.config.user.reveal();
+        const connectionsLimit = config.connectionLimit ?? 20;
+
+        const newPool: Pool = mysql.createPool({
+            host: config.host ?? "localhost",
+            port: config.port ?? 3306,
+            user: user.username,
+            password: user.password,
+            database: config.database,
+            connectionLimit: connectionsLimit,
+            waitForConnections: true,
+            queueLimit: connectionsLimit * 2,
+            decimalNumbers: true,
+            dateStrings: true,
+        });
+
+        try {
+            const conn = await newPool.getConnection();
+            await conn.ping();
+            conn.release();
+        } catch (err) {
+            GGLog.critical(this, 'Failed to connect to database!', {
+                database: config.database,
+                host: config.host,
+                error: err instanceof Error ? err.message : String(err)
+            });
+            await newPool.end();
+            throw err;
+        }
+
+        if (this.pool) {
+            this.pool.end().catch(err => {
+                GGLog.warn(this, 'Config change: error closing old pool', {
+                    error: err instanceof Error ? err.message : String(err)
+                });
+            });
+        }
+
+        this.pool = newPool;
+
+        GGLog.info(this, 'Mysql connected!', {database: config.database});
+    }
+
+    private async start(): Promise<void> {
+        this.started = true;
+        await this.connect();
+    }
+
+    private async teardown(): Promise<void> {
+        this.unwatchHost();
+        this.unwatchHost = undefined;
+        this.unwatchUser();
+        this.unwatchUser = undefined;
+        if (this.pool) {
+            await this.pool.end();
+            this.pool = undefined;
+            GGLog.debug(this, 'disconnected');
+        }
+    }
+
+    private getPool(): Pool {
+        if (!this.pool) {
+            throw new Error(`Mysql '${this.config.name}' not connected. Are you calling this before runtime.start()?`);
+        }
+        return this.pool;
+    }
+
+    public async query<T extends RowDataPacket[]>(sql: string, params?: unknown[]): Promise<T> {
+        GGLog.debug(this, 'query', {sql, params});
+        const [rows] = await this.getPool().query<T>(sql, params);
+        GGLog.debug(this, 'query result', {rowCount: rows.length});
+        return rows;
+    }
+
+    public async execute(sql: string, params?: unknown[]): Promise<ResultSetHeader> {
+        GGLog.debug(this, 'execute', {sql, params});
+        const [result] = await this.getPool().execute<ResultSetHeader>(sql, params);
+        GGLog.debug(this, 'execute result', {affectedRows: result.affectedRows, insertId: result.insertId});
+        return result;
+    }
+
+    // ==================== Connection for transactions ====================
+
+    /**
+     * Get a dedicated connection from the pool.
+     * Use this for transactions or when you need multiple queries on the same connection.
+     *
+     * IMPORTANT: Always call release() on the connection when done.
+     */
+    public async getConnection(): Promise<GGMysqlConnection> {
+        const poolConn = await this.getPool().getConnection();
+        return new GGMysqlConnection(poolConn);
+    }
+
+    /**
+     * Run a callback within a transaction.
+     * Automatically handles connection lifecycle, commits on success, rolls back on failure.
+     */
+    public async runInTransaction<T>(callback: (conn: GGMysqlConnection) => Promise<T>): Promise<T> {
+        const conn = await this.getConnection();
+        try {
+            return await conn.runInTransaction(() => callback(conn));
+        } finally {
+            conn.release();
+        }
+    }
+}

package/src/GGMysqlConfig.ts

@@ -0,0 +1,39 @@
+import {GGResource, GGSecret} from "@grest-ts/config";
+import {GGMysql} from "./GGMysql";
+import {IsNumber, IsObject, IsString} from "@grest-ts/schema";
+import {GGLocatorKey} from "@grest-ts/locator";
+
+const IsMysqlResource = IsObject({
+    host: IsString.orUndefined,
+    port: IsNumber.orUndefined,
+    database: IsString,
+    connectionLimit: IsNumber.orUndefined
+});
+export type GGMysqlHostData = typeof IsMysqlResource.infer
+
+const IsMysqlUserData = IsObject({
+    username: IsString.orUndefined,
+    password: IsString.orUndefined
+});
+export type GGMysqlUserData = typeof IsMysqlUserData.infer
+
+export class GGMysqlConfig {
+
+    public readonly name: string;
+    public readonly token: GGLocatorKey<GGMysql>;
+    public readonly host: GGResource<GGMysqlHostData>;
+    public readonly user: GGSecret<GGMysqlUserData>;
+    public readonly schemaFile?: string;
+
+    constructor(name: string, schemaFile?: string) {
+        this.name = name;
+        this.token = new GGLocatorKey<GGMysql>(`Mysql:${name}`);
+        this.host = new GGResource(name + "/host", IsMysqlResource, "Mysql host configuration")
+        this.user = new GGSecret(name + "/user", IsMysqlUserData, "Mysql user credentials")
+        this.schemaFile = schemaFile;
+    }
+
+    public newMysqlPool() {
+        return new GGMysql(this);
+    }
+}

package/src/GGMysqlConnection.ts

@@ -0,0 +1,156 @@
+import { PoolConnection, RowDataPacket, ResultSetHeader } from 'mysql2/promise';
+import { GGLog } from '@grest-ts/logger';
+
+/**
+ * MysqlConnection - A single connection from the pool.
+ *
+ * Use this when you need:
+ * - Transactions (BEGIN, COMMIT, ROLLBACK)
+ * - Multiple queries that must use the same connection
+ *
+ * IMPORTANT: Always call release() when done to return the connection to the pool.
+ *
+ * @example
+ * ```typescript
+ * const conn = await db.getConnection();
+ * try {
+ *     await conn.beginTransaction();
+ *     await conn.execute('INSERT INTO users ...', [...]);
+ *     await conn.execute('INSERT INTO profiles ...', [...]);
+ *     await conn.commit();
+ * } catch (err) {
+ *     await conn.rollback();
+ *     throw err;
+ * } finally {
+ *     conn.release();
+ * }
+ * ```
+ */
+export class GGMysqlConnection {
+    private conn: PoolConnection;
+    private released = false;
+
+    constructor(conn: PoolConnection) {
+        this.conn = conn;
+    }
+
+    /**
+     * Execute a SELECT query and return rows.
+     */
+    async query<T extends RowDataPacket[]>(sql: string, params?: unknown[]): Promise<T> {
+        this.checkReleased();
+        GGLog.debug(this, 'query', { sql, params });
+        try {
+            const [rows] = await this.conn.query<T>(sql, params);
+            GGLog.debug(this, 'query result', { rowCount: rows.length });
+            return rows;
+        } catch (err: any) {
+            const msg = err?.message || String(err);
+            throw new Error(`SQL query failed: ${msg}\n  Query: ${sql}` + (params?.length ? `\n  Params: ${JSON.stringify(params)}` : ''));
+        }
+    }
+
+    /**
+     * Execute an INSERT, UPDATE, or DELETE query.
+     */
+    async execute(sql: string, params?: unknown[]): Promise<ResultSetHeader> {
+        this.checkReleased();
+        GGLog.debug(this, 'execute', { sql, params });
+        try {
+            const [result] = await this.conn.execute<ResultSetHeader>(sql, params);
+            GGLog.debug(this, 'execute result', { affectedRows: result.affectedRows, insertId: result.insertId });
+            return result;
+        } catch (err: any) {
+            const msg = err?.message || String(err);
+            throw new Error(`SQL execute failed: ${msg}\n  Query: ${sql}` + (params?.length ? `\n  Params: ${JSON.stringify(params)}` : ''));
+        }
+    }
+
+    // ==================== Transaction methods ====================
+
+    /**
+     * Run a callback within a transaction.
+     * Automatically commits on success, rolls back on failure.
+     *
+     * Note: Does NOT release the connection. Call release() when done.
+     *
+     * @example
+     * ```typescript
+     * const conn = await db.getConnection();
+     * try {
+     *     const result = await conn.runInTransaction(async () => {
+     *         await conn.execute('INSERT INTO orders ...', [...]);
+     *         await conn.execute('UPDATE inventory ...', [...]);
+     *         return orderId;
+     *     });
+     * } finally {
+     *     conn.release();
+     * }
+     * ```
+     */
+    async runInTransaction<T>(callback: () => Promise<T>): Promise<T> {
+        this.checkReleased();
+        await this.conn.beginTransaction();
+        GGLog.debug(this, 'beginTransaction');
+        try {
+            const result = await callback();
+            await this.conn.commit();
+            GGLog.debug(this, 'commit');
+            return result;
+        } catch (err) {
+            await this.conn.rollback();
+            GGLog.debug(this, 'rollback', { error: err });
+            throw err;
+        }
+    }
+
+    /**
+     * Start a transaction.
+     */
+    async beginTransaction(): Promise<void> {
+        this.checkReleased();
+        GGLog.debug(this, 'beginTransaction');
+        await this.conn.beginTransaction();
+    }
+
+    /**
+     * Commit the current transaction.
+     */
+    async commit(): Promise<void> {
+        this.checkReleased();
+        GGLog.debug(this, 'commit');
+        await this.conn.commit();
+    }
+
+    /**
+     * Rollback the current transaction.
+     */
+    async rollback(): Promise<void> {
+        this.checkReleased();
+        GGLog.debug(this, 'rollback');
+        await this.conn.rollback();
+    }
+
+    // ==================== Lifecycle ====================
+
+    /**
+     * Release this connection back to the pool.
+     * MUST be called when done with the connection.
+     */
+    release(): void {
+        if (!this.released) {
+            this.conn.release();
+            this.released = true;
+            GGLog.debug(this, 'released');
+        }
+    }
+
+    /**
+     * Check if connection has been released.
+     */
+    private checkReleased(): void {
+        if (this.released) {
+            throw new Error('Connection has been released. Cannot perform operations on a released connection.');
+        }
+    }
+}

package/src/index-node.ts

@@ -0,0 +1,4 @@
+export * from './GGMysql';
+export * from "./GGMysqlConfig";
+export * from './GGMysqlConnection';
+export type {RowDataPacket, ResultSetHeader, FieldPacket} from 'mysql2/promise';

package/src/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "//": "THIS FILE IS GENERATED - DO NOT EDIT",
+  "extends": "../../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": ".",
+    "lib": [
+      "ES2022"
+    ],
+    "types": [
+      "node"
+    ]
+  },
+  "include": [
+    "**/*"
+  ]
+}