fix: types for query values (#3985)

* fix: types for query values

* docs: add TypeScript documentation for QueryValues

* fix: support named placeholders in QueryValues type

* Update website/docs/documentation/typescript-examples.mdx

---------

Co-authored-by: Weslley Araújo <46850407+wellwelwel@users.noreply.github.com>

Author: uPaymeiFixit

typings/mysql/lib/protocol/sequences/Query.d.ts

@@ -3,6 +3,18 @@ import { OkPacket, RowDataPacket, FieldPacket } from '../packets/index.js';
 import { Readable } from 'stream';
 import { TypeCast } from '../../parsers/typeCast.js';
 
+export type QueryValues =
+  | string
+  | number
+  | bigint
+  | boolean
+  | Date
+  | null
+  | Blob
+  | Buffer
+  | ({} | null)[]
+  | { [key: string]: QueryValues };
+
 export interface QueryOptions {
   /**
    * The SQL for the query
@@ -12,7 +24,7 @@ export interface QueryOptions {
   /**
    * The values for the query
    */
-  values?: any | any[] | { [param: string]: any };
+  values?: QueryValues;
 
   /**
    * This overrides the namedPlaceholders option set at the connection level.

typings/mysql/lib/protocol/sequences/promise/ExecutableBase.d.ts

@@ -1,5 +1,5 @@
 import { FieldPacket, QueryResult } from '../../packets/index.js';
-import { QueryOptions, QueryableConstructor } from '../Query.js';
+import { QueryOptions, QueryableConstructor, QueryValues } from '../Query.js';
 
 export declare function ExecutableBase<T extends QueryableConstructor>(
   Base?: T
@@ -8,14 +8,14 @@ export declare function ExecutableBase<T extends QueryableConstructor>(
     execute<T extends QueryResult>(sql: string): Promise<[T, FieldPacket[]]>;
     execute<T extends QueryResult>(
       sql: string,
-      values: any
+      values: QueryValues
     ): Promise<[T, FieldPacket[]]>;
     execute<T extends QueryResult>(
       options: QueryOptions
     ): Promise<[T, FieldPacket[]]>;
     execute<T extends QueryResult>(
       options: QueryOptions,
-      values: any
+      values: QueryValues
     ): Promise<[T, FieldPacket[]]>;
   };
 } & T;

website/docs/documentation/typescript-examples.mdx

@@ -381,6 +381,46 @@ For `ProcedureCallPacket<RowDataPacket[]>`, please see the following examples.
 
 <hr />
 
+### QueryValues
+
+<Stability level={2} />
+
+The `QueryValues` type represents the allowed types for query parameter values:
+
+```ts
+import mysql, { RowDataPacket, QueryValues } from 'mysql2';
+
+const conn = mysql.createConnection({
+  user: 'test',
+  database: 'test',
+});
+
+const values: QueryValues = [1, 'test', null];
+
+conn.query<RowDataPacket[]>(
+  'SELECT * FROM users WHERE id = ? AND name = ? AND deleted_at = ?',
+  values,
+  (_err, rows) => {
+    console.log(rows);
+  }
+);
+```
+
+The `QueryValues` type includes the following types:
+
+- `string`
+- `number`
+- `bigint`
+- `boolean`
+- `Date`
+- `null`
+- `Blob`
+- `Buffer`
+- `({} | null)[]` (array of values)
+- `{ [key: string]: QueryValues }` (named placeholders)
+
+<hr />
+
 ### OkPacket
 
 <Stability