docs: introduce documentation website

.eslintignore

@@ -0,0 +1 @@
+website/

.github/workflows/gh-pages.yml

@@ -0,0 +1,42 @@
+name: 'GitHub Pages'
+on:
+  push:
+    branches:
+      - master
+    paths:
+      - 'website/**'
+  workflow_dispatch:
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Actions - Checkout
+        uses: actions/checkout@v3
+
+      - name: Actions - Setup NodeJS
+        uses: actions/setup-node@v3
+        with:
+          node-version: '18.x'
+
+      - name: Cache dependencies
+        uses: actions/cache@v3
+        with:
+          path: ~/.npm
+          key: npm-${{ hashFiles('package-lock.json') }}
+          restore-keys: npm-
+
+      - name: Installing Dependencies
+        run: cd website && npm ci
+
+      - name: Checking Types
+        run: cd website && npm run typecheck
+
+      - name: Building Site
+        run: cd website && npm run build
+
+      - name: Deploy
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./website/build

.prettierignore

@@ -0,0 +1,4 @@
+website/build
+website/.docusaurus
+website/.cache-loader
+website/**/*.mdx

website/.gitignore

@@ -0,0 +1,20 @@
+# Dependencies
+/node_modules
+
+# Production
+/build
+
+# Generated files
+.docusaurus
+.cache-loader
+
+# Misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*

website/README.md

@@ -0,0 +1,25 @@
+# Website
+
+This website is built using [Docusaurus 3](https://docusaurus.io/), a modern static website generator.
+
+### Installation
+
+```bash
+npm i
+```
+
+### Local Development
+
+```bash
+npm start
+```
+
+This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
+
+### Build
+
+```bash
+npm run build
+```
+
+This command generates static content into the `build` directory and can be served using any static contents hosting service.

website/babel.config.js

@@ -0,0 +1,3 @@
+module.exports = {
+  presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
+};

website/docs/api-and-configurations.mdx

@@ -0,0 +1,12 @@
+# API and Configuration
+
+MySQL2 is mostly API compatible with [Node MySQL][node-mysql].
+{/* You should check their API documentation to see all available API options. */}
+
+One known incompatibility is that `DECIMAL` values are returned as strings whereas in [Node MySQL][node-mysql] they are returned as numbers. This includes the result of `SUM()` and `AVG()` functions when applied to `INTEGER` arguments. This is done deliberately to avoid loss of precision - see https://github.com/sidorares/node-mysql2/issues/935.
+
+:::info
+If you find any other incompatibility with [Node MySQL][node-mysql], Please report via Issue tracker. We will fix reported incompatibility on priority basis.
+:::
+
+[node-mysql]: https://github.com/mysqljs/mysql

website/docs/documentation/00-introduction.mdx

@@ -0,0 +1,59 @@
+# Introduction
+
+MySQL2 aims to be a drop in replacement for [node-mysql](https://github.com/mysqljs/mysql). Please check `node-mysql` for full documentation.
+
+**Note :** *If you see any API incompatibilities with `node-mysql`, please report via github issue.*
+
+Not only `Node-MySQL2` offers better performance over `node-mysql`, we also support these additional features.
+
+- [Prepared Statements](/docs/documentation/prepared-statements)
+- [Promise Wrapper](/docs/documentation/promise-wrapper)
+- [Authentication Switch](/docs/documentation/authentication-switch)
+- [More Features](/docs/documentation/extras)
+- [MySQL Server](/docs/documentation/mysql-server)
+- Pooling
+- SSL
+- MySQL Compression
+- Binary Log Protocol Client
+
+---
+
+## Examples
+
+Please check these [examples](/docs/examples) for `node-mysql2`.
+
+---
+
+## Known incompatibilities with `node-mysql`
+
+- `zeroFill` flag is ignored in type conversion.
+You need to check corresponding field's zeroFill flag and convert to string manually if this is of importance to you.
+
+- `DECIMAL` and `NEWDECIMAL` types always returned as `string` unless you pass this config option:
+```js
+{
+  decimalNumbers: true,
+}
+```
+
+:::note
+This option could lose precision on the number as Javascript Number is a Float!
+:::
+
+---
+
+## Other Resources
+
+- [Wire protocol documentation](http://dev.mysql.com/doc/internals/en/client-server-protocol.html)
+- [node-mysql](https://github.com/mysqljs/mysql) - Most popular node.js mysql client library
+- [node-mariasql](https://github.com/mscdex/node-mariasql/) - Bindings to libmariasql. One of the fastest clients
+- [node-libmysqlclient](https://github.com/Sannis/node-mysql-libmysqlclient) - Bindings to libmysqlclient
+- [go-mysql](https://github.com/siddontang/go-mysql) - MySQL Go client (prepared statements, binlog protocol, server)
+
+---
+
+## Benchmarks
+- https://gist.github.com/sidorares/ffe9ee9c423f763e3b6b
+- `npm run benchmarks`
+- [node-mysql-benchmarks](https://github.com/mscdex/node-mysql-benchmarks)
+- try to run example [benchmarks](https://github.com/sidorares/node-mysql2/tree/master/benchmarks) on your system

website/docs/documentation/authentication-switch.mdx

@@ -0,0 +1,109 @@
+# Authentication Switch Request
+
+During the connection phase the server may ask the client to switch to a different auth method.
+If the `authPlugins` connection config option is set, it must be an object where each key
+is the name of a potential authentication plugin requested by the server, and the corresponding
+value must be a function that optionally receives the connection config options and returns
+another function, which in turn, optionally receives the switch request data.
+
+The plugin is loaded with a `({user,password,...})` signature, and each call has a `(pluginData)`
+signature. Each call should make the plugin return any additional authentication data (`Buffer`)
+that should be sent back to the server, either synchronously or asynchronously using a `Promise`,
+or should yield an error accordingly.
+
+Example: (imaginary `ssh-key-auth` plugin) pseudo code
+
+```js
+const conn = mysql.createConnection({
+  user: 'test_user',
+  password: 'test',
+  database: 'test_database',
+  authPlugins: {
+    'ssh-key-auth': function ({password}) {
+      return function (pluginData) {
+        return getPrivate(key)
+          .then(key => {
+            const response = encrypt(key, password, pluginData);
+            // continue handshake by sending response data
+            return response;
+          })
+          .catch(err => {
+            // throw error to propagate error to connect/changeUser handlers
+          });
+      };
+    }
+  }
+});
+```
+
+There is also a deprecated API where if a `authSwitchHandler` connection config option is set
+it must be a function that receives switch request data and responds via a callback. In this case,
+the first invocation always has a `({pluginName, pluginData})` signature, following calls - `({pluginData})`.
+The client replies with an opaque blob matching the requested plugin via `callback(null, data: Buffer)`.
+
+```js
+const conn = mysql.createConnection({
+  user: 'test_user',
+  password: 'test',
+  database: 'test_database',
+  authSwitchHandler: function ({pluginName, pluginData}, cb) {
+    if (pluginName === 'ssh-key-auth') {
+      getPrivateKey(key => {
+        const response = encrypt(key, pluginData);
+        // continue handshake by sending response data
+        // respond with error to propagate error to connect/changeUser handlers
+        cb(null, response);
+      });
+    } else {
+      const err = new Error(`Unknown AuthSwitchRequest plugin name ${pluginName}`);
+      err.fatal = true;
+      cb(err);
+    }
+  }
+});
+```
+
+The initial handshake is always performed using `mysql_native_password` plugin. This will be possible to override in future versions.
+
+Note that if the `mysql_native_password` method is requested it will be handled internally according
+to [Authentication::Native41]( https://dev.mysql.com/doc/internals/en/secure-password-authentication.html#packet-Authentication::Native41)
+and no `authPlugins` function or the `authSwitchHandler` will be invoked.
+
+These MAY be called multiple times if the plugin algorithm requires multiple roundtrips of data
+exchange between client and server.
+
+## Multi-factor authentication
+
+If the user requires multi-factor authentication in the server, the client will receive a `AuthNextFactor`
+request, which is similar in structure to the regular authentication switch request and contains the name
+and possible initial data for the additional authentication factor plugin (up to 3). Additional passwords
+can be provided using the connection config options - `password2` and `password3`. Again, for each
+authentication factor, multiple roundtrips of data exchange can be required by the plugin algoritm.
+
+```js
+const conn = mysql.createConnection({
+  user: 'test_user',
+  password: 'secret1',
+  password2: 'secret2',
+  password3: 'secret3',
+  database: 'test_database',
+  authPlugins: {
+    // password1 === password
+    'auth-plugin1': function ({password1}) {
+      return function (serverPluginData) {
+        return clientPluginData(password1, serverPluginData);
+      };
+    },
+    'auth-plugin2': function ({password2}) {
+      return function (serverPluginData) {
+        return clientPluginData(password2, serverPluginData);
+      };
+    },
+    'auth-plugin3': function ({password3}) {
+      return function (serverPluginData) {
+        return clientPluginData(password3, serverPluginData);
+      };
+    }
+  }
+});
+```