add typescript example and improve types

Author: Michael Kornelakis

examples/README.md

@@ -1,5 +1,4 @@
-Examples
-==================
+# Examples
 
 These examples run against the [test_db](https://github.com/datacharmer/test_db) dataset. It expects the database to be named `employees` and expects the root password to be `password`.
 
@@ -8,3 +7,11 @@ To run a docker container with this data and bound to the correct port, you can
 ```
 docker run -p 3306:3306 --name mysql_container -e MYSQL_ROOT_PASSWORD=password -d genschsa/mysql-employees
 ```
+
+### Typecript
+
+In the `typescript` folder there are the equivalent examples. In order to run them you can use `npm run ts-node` followed by the path of the file. So for example you can run `npm run ts-node ./examples/connection/typescript/query`
+
+### Note
+
+I am using `ts-node` in order to avoid including a bundler. If you try to compile the typescript files to javascript using ithe `outDir` option in `tsconfig` then you will get import errors beacuse we are pulling the `index` file form the root of the project.

examples/connection/typescript/employee.ts

@@ -0,0 +1 @@
+export type Employee = { first_name: string, last_name: string, emp_no: number };

examples/connection/typescript/mysqlWrapper.ts

@@ -0,0 +1,54 @@
+import Bluebird from 'bluebird';
+import * as mysql from '../../../index';
+
+async function runReturn() {
+    const connection = await mysql.createConnection({
+        user: 'root',
+        password: 'password',
+        database: 'employees',
+        mysqlWrapper: (mysqlInstance: mysql.mysqlModule) => wrapMysql(mysqlInstance, 'runReturn')
+    });
+
+    connection.end();
+}
+
+async function runPromise() {
+    const connection = await mysql.createConnection({
+        user: 'root',
+        password: 'password',
+        database: 'employees',
+        mysqlWrapper: (mysqlInstance: mysql.mysqlModule) => Bluebird.resolve(wrapMysql(mysqlInstance, 'runPromise')) as unknown as Promise<mysql.mysqlModule>
+    });
+
+    connection.end();
+}
+
+async function runCallback() {
+    const connection = await mysql.createConnection({
+        user: 'root',
+        password: 'password',
+        database: 'employees',
+        mysqlWrapper: (mysqlInstance: mysql.mysqlModule, callback) => callback?.(null, wrapMysql(mysqlInstance, 'runCallback'))
+    });
+
+    connection.end();
+}
+
+runReturn();
+runPromise();
+runCallback();
+
+
+function wrapMysql(mysqlInstance: mysql.mysqlModule, fnName: string) {
+    const createConnection = mysqlInstance.createConnection;
+
+    mysqlInstance.createConnection = function (...args) {
+        console.log(`createConnection called in ${fnName}!`);
+
+        mysqlInstance.createConnection = createConnection;
+
+        return createConnection(...args);
+    }
+
+    return mysqlInstance;
+}

examples/connection/typescript/query.ts

@@ -0,0 +1,41 @@
+import * as mysql from '../../../index';
+import { Employee } from './employee';
+
+async function run() {
+    let connection: mysql.Connection;
+
+    mysql.createConnection({
+        user: 'root',
+        password: 'password',
+        database: 'employees'
+    }).then((conn) => {
+        connection = conn;
+
+        return connection.query<Employee[]>('select * from employees limit 0, 10');
+    }).then((employees) => {
+        employees.forEach(employee => {
+            console.log(`The employee with the employee number ${employee.emp_no} is ${employee.first_name} ${employee.last_name}`);
+        });
+    
+        connection.end();
+    })
+}
+
+async function runAwait() {
+    const connection = await mysql.createConnection({
+        user: 'root',
+        password: 'password',
+        database: 'employees'
+    });
+
+    const employees = await connection.query<Employee[]>('select * from employees limit 0, 10');
+
+    employees.forEach(employee => {
+        console.log(`The employee with the employee number ${employee.emp_no} is ${employee.first_name} ${employee.last_name}`);
+    });
+
+    connection.end();
+}
+
+run();
+runAwait();

examples/connection/typescript/querystream.ts

@@ -0,0 +1,41 @@
+import * as mysql from '../../../index';
+import { Employee } from './employee';
+
+function run() {
+    mysql.createConnection({
+        user: 'root',
+        password: 'password',
+        database: 'employees'
+    }).then((connection) => {
+        const employees = connection.queryStream<Employee>('select * from employees limit 0, 10');
+
+        employees.on('result', (employee) => {
+            console.log(`The employee with the employee number ${employee.emp_no} is ${employee.first_name} ${employee.last_name}`);
+        });
+
+        employees.on('end', () => {
+            connection.end();
+        })
+    });
+}
+
+async function runAwait() {
+    const connection = await mysql.createConnection({
+        user: 'root',
+        password: 'password',
+        database: 'employees'
+    });
+
+    const employees = connection.queryStream<Employee>('select * from employees limit 0, 10');
+
+    employees.on('result', (employee) => {
+        console.log(`The employee with the employee number ${employee.emp_no} is ${employee.first_name} ${employee.last_name}`);
+    });
+
+    employees.on('end', () => {
+        connection.end();
+    })
+}
+
+run();
+runAwait();

examples/connection/typescript/returnArgumentsArray.ts

@@ -0,0 +1,62 @@
+import { FieldInfo, Query } from 'mysql';
+import mysql from '../../../index';
+import { Employee } from './employee';
+
+function run() {
+    let connection: mysql.Connection;
+
+    mysql.createConnection({
+        user: 'root',
+        password: 'password',
+        database: 'employees',
+        returnArgumentsArray: true
+    }).then((conn) => {
+        connection = conn;
+
+        return connection.query<[data: Employee[], fields: FieldInfo[], query: Query]>('select * from employees limit 0, 10');
+    }).then(([data, fields, query]) => {
+        console.log(`The SQL for the query was: ${query.sql}\n`);
+
+        console.log(`The table 'employees' contains the following fields:`)
+        fields.forEach(field => {
+            console.log(`    ${field.name}`);
+        })
+
+        console.log('\nThe data retrieved was:')
+
+        data.forEach(employee => {
+            console.log(`    Employee number ${employee.emp_no}: ${employee.first_name} ${employee.last_name}`);
+        });
+
+        connection.end();
+    });
+}
+
+async function runAwait() {
+    const connection = await mysql.createConnection({
+        user: 'root',
+        password: 'password',
+        database: 'employees',
+        returnArgumentsArray: true
+    });
+
+    const [data, fields, query] = await connection.query<[data: Employee[], fields: FieldInfo[], query: Query]>('select * from employees limit 0, 10');
+
+    console.log(`The SQL for the query was: ${query.sql}\n`);
+
+    console.log(`The table 'employees' contains the following fields:`)
+    fields.forEach(field => {
+        console.log(`    ${field.name}`);
+    })
+
+    console.log('\nThe data retrieved was:')
+
+    data.forEach(employee => {
+        console.log(`    Employee number ${employee.emp_no}: ${employee.first_name} ${employee.last_name}`);
+    });
+
+    connection.end();
+}
+
+run();
+runAwait();

index.d.ts

@@ -12,7 +12,7 @@ export { Types, escape, escapeId, format, raw, ConnectionOptions, PoolClusterCon
 export type mysqlModule = typeof mysql;
 
 export interface ConnectionConfig extends mysql.ConnectionConfig {
-    mysqlWrapper?: (mysql: mysqlModule, callback: (err: Error | null, success?: mysqlModule) => void) => mysqlModule | Promise<mysqlModule> | void;
+    mysqlWrapper?: (mysql: mysqlModule, callback?: (err: Error | null, success?: mysqlModule) => void) => mysqlModule | Promise<mysqlModule> | void;
     returnArgumentsArray?: boolean;
     reconnect?: boolean;
 }
@@ -23,16 +23,29 @@ export interface PoolConfig extends mysql.PoolConfig {
     reconnect?: boolean;
 }
 
-export interface QueryFunction<T> {
-    (query: mysql.Query | string | mysql.QueryOptions): T;
+export interface QueryFunction {
+    <T extends unknown>(query: mysql.Query | string | mysql.QueryOptions): T;
+
+    <T extends unknown>(options: string, values?: any): T;
+}
+
+export interface Query<T> extends mysql.Query {
+
+    on(ev: 'result', callback: (row: T, index: number) => void): mysql.Query;
+
+    on(ev: 'error', callback: (err: mysql.MysqlError) => void): mysql.Query;
+
+    on(ev: 'fields', callback: (fields: mysql.FieldInfo[], index: number) => void): mysql.Query;
+
+    on<T extends unknown>(ev: 'packet', callback: (packet: T) => void): mysql.Query;
 
-    (options: string, values: any): T;
+    on(ev: 'end', callback: () => void): mysql.Query;
 }
 
 export class Connection {
     constructor(config: string | ConnectionConfig, _connection?: Connection);
 
-    query: QueryFunction<Bluebird<any>>;
+    query: QueryFunction;
 
     beginTransaction(options?: mysql.QueryOptions): Bluebird<void>;
 
@@ -44,7 +57,7 @@ export class Connection {
 
     ping(options?: mysql.QueryOptions): Bluebird<void>;
 
-    queryStream: QueryFunction<mysql.Query>
+    queryStream<T extends unknown>(options: string, values?: any): Query<T>;
 
     statistics(options?: mysql.QueryOptions): Bluebird<void>;
 
@@ -78,7 +91,7 @@ export class Pool {
 
     getConnection(): Bluebird<PoolConnection>;
 
-    query: QueryFunction<Bluebird<any>>;
+    query: QueryFunction;
 
     end(options?: mysql.QueryOptions): Bluebird<void>;
 
@@ -94,7 +107,7 @@ export class Pool {
 
     on(ev: 'enqueue', callback: (err?: mysql.MysqlError) => void): mysql.Pool;
 
-    on(ev: string, callback: (...args: any[]) => void): mysql.Pool;
+    on<T extends unknown>(ev: string, callback: (...args: T[]) => void): mysql.Pool;
 }
 
 export class PoolCluster {
@@ -121,7 +134,7 @@ export class PoolCluster {
     /**
      * Set handler to be run on a certain event.
      */
-    on(ev: string, callback: (...args: any[]) => void): PoolCluster;
+    on<T extends unknown>(ev: string, callback: (...args: T[]) => void): PoolCluster;
 
     /**
      * Set handler to be run when a node is removed or goes offline.