typing & documentation update for prepared statements

Author: xWTF

documentation/Prepared-Statements.md

@@ -27,8 +27,9 @@ connection.prepare('select ? + ? as tests', (err, statement) => {
     // -> [ { tests: 3 } ]
   });
 
+  // do not use statement.close(), use connection.unprepare() to remove lru cache properly.
   // note that there is no callback here. There is no statement close ack at protocol level.
-  statement.close();
+  connection.unprepare('select ? + ? as tests');
 });
 ```
 Note that you should not use statement after connection reset (`changeUser()` or disconnect). Statement scope is connection, you need to prepare statement for each new connection in order to use it.

promise.d.ts

@@ -62,7 +62,8 @@ export interface Connection extends EventEmitter {
     values: any | any[] | { [param: string]: any }
   ): Promise<[T, FieldPacket[]]>;
 
-  unprepare(sql: string): void;
+  prepare(options: string | QueryOptions): Promise<PreparedStatementInfo>;
+  unprepare(sql: string | QueryOptions): void;
 
   end(options?: any): Promise<void>;
 
@@ -137,3 +138,11 @@ export function createConnection(
   config: ConnectionOptions
 ): Promise<Connection>;
 export function createPool(config: PoolOptions): Pool;
+
+export interface PreparedStatementInfo {
+  /**
+   * Close the prepared statement. This method DO NOT REMOVE the statement cache, and should only be used internally. Use {@link Connection.unprepare} instead when you've done with prepared statement.
+   */
+  close(): Promise<void>;
+  execute(parameters: any[]): Promise<[RowDataPacket[][] | RowDataPacket[] | OkPacket | OkPacket[] | ResultSetHeader, FieldPacket[]]>;
+}