docs: introduce TypeScript documentation

[wellwelwel]

I added an installation case for @types/node in README.md, but described its purpose in /documentation/en/TypeScript-Examples.md.

Every example in this documentation was tested 🤹🏻‍♀️

You can follow the documentation here.

---

Annotations:

• Create practical examples based on Issues in examples/typescript/
• Check spelling after completing the documentation

Every file that was changed has a direct relation to the documentation 🙋🏻‍♂️

[wellwelwel]

After several tests, I never got an OkPacket response.
Also searching through the code, all the uses of OK that I found are only used internally.

Instead, every query always returns RowDataPacket[], RowDataPacket[][], ResultSetHeader or ResultSetHeader[].

Including query().on('result', (result) => {})

Examples from source code (JS)

• Internal usage:
  

  node-mysql2/lib/connection.js

  Lines 882 to 887 in 8ca36c7

  	writeOk(args) {
  	if (!args) {
  	args = { affectedRows: 0 };
  	}
  	this.writePacket(Packets.OK.toPacket(args, this.serverConfig.encoding));
  	}

  • writeOk returns a void

• query:

  • node-mysql2/lib/commands/query.js

    Line 117 in 8ca36c7

    resultsetHeader(packet, connection) {

  • only exports row and ResultSetHeader

• execute:
  

  node-mysql2/lib/commands/execute.js

  Line 98 in 8ca36c7

  Execute.prototype.resultsetHeader = Query.prototype.resultsetHeader;

  • only exports row and ResultSetHeader

---

Handling it considering not to cause a break change

1. Set changedRows in ResultSetHeader as a required property

   Done ✅

• JS
  • In /lib/packets/resultset_header.js:

    if (m !== null) { 
      this.changedRows = parseInt(m[1], 10); 
  + } else {
  +   this.changedRows = 0;
    }

• TS
  • In typings/mysql/lib/protocol/packets/ResultSetHeader.d.ts:

  -   changedRows?: number;
  +   changedRows: number;
    }
  
    export { ResultSetHeader };

2. Add ResultSetHeader[] possibility to query and execute (for multipleStatements)

   Done ✅

3. Optional: comment in typings/mysql/lib/protocol/packets/OkPacket.d.ts

   If you agree with this, I will do it in another PR, after documentation

   + /** @deprecated */
     declare interface OkPacket {

   • Later, in a major version, remove the OkPacket and OkPacket[] from query and execute types.

---

That said, I don't propose to use the OkPacket type in TypeScript documentation.

For now, I will continue the TypeScript documentation, but ignoring the OkPacket.

[wellwelwel]

The documentation and the examples are ready 🕺🏻

I have created seven TypeScript examples based on Issues.
Tomorrow, I will review them before completing this PR.

[sidorares]

Thanks @wellwelwel!

I think the naming confusion comes from the fact it's called "OK_Packet" in the documentation and it's a ResultSetHeader here. We should probably only use ResultSetHeader name for consistency

changedRows is not defined at all in the protocol, but the property existed in mysqljs/mysql so we support it as well. It's basically just a "view" into a human-readable "info" part if the info contains "changed [number]" in it's text. I'm not sure if we should set it to 0 if it can't be parsed - wdyt @wellwelwel ?

[wellwelwel]

Hey, @sidorares 🙋🏻‍♂️

I have chosen 0 to not cause a breaking change.

I did a quick test and even a personal project would break if I changed from number to another type, like false or null, for example.

About keep it as it is...

I explain it better in my previous comment and complementing, the reason for this is to pattern the main difference between OkPacket and ResultSetHeader, especially to be able to explain the ResultSetHeader and its usability, ignoring the OkPacket in TypeScript documentation.

Just complementing (again), basically the changedRows appears in ResultSetHeader when an UPDATE query is performed.

Feel free to change it, I'm always open for ideas and suggestions 🤹🏻‍♀️

[wellwelwel]

For optional fields, especially in TypeScript, is recommended check if the field exists, and if yes, the changedRows expects for a number, if we change this:

• It would work perfectly, because it check for type:

typeof myResultSetHeader?.changedRows === 'number';

• Causing a breaking change:

'changedRows' in myResultSetHeader && myResultSetHeader.changedRows > 0;