docs: introduce documentation website

.eslintignore

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

.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

.github/workflows/website.yml

@@ -0,0 +1,37 @@
+name: 'CI - Website'
+on:
+  pull_request:
+    paths:
+      - 'website/**'
+  workflow_dispatch:
+
+jobs:
+  build:
+    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: Lint Checking
+        run: cd website && npm run lintcheck
+
+      - name: Checking Types
+        run: cd website && npm run typecheck
+
+      - name: Checking Build
+        run: cd website && npm run build

.prettierignore

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

website/.eslintignore

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

website/.eslintrc.json

@@ -0,0 +1,129 @@
+{
+  "root": true,
+  "parser": "@typescript-eslint/parser",
+  "plugins": ["@typescript-eslint", "import", "react", "react-hooks"],
+  "extends": [
+    "eslint:recommended",
+    "plugin:@typescript-eslint/recommended",
+    "plugin:import/errors",
+    "plugin:import/warnings",
+    "plugin:react-hooks/recommended",
+    "plugin:react/jsx-runtime"
+  ],
+  "parserOptions": {
+    "ecmaVersion": "latest",
+    "sourceType": "module",
+    "ecmaFeatures": {
+      "jsx": true
+    }
+  },
+  "rules": {
+    "import/no-cycle": ["error", { "maxDepth": "∞" }],
+    "import/no-unresolved": ["error", { "ignore": ["^@docusaurus/"] }],
+    "no-restricted-syntax": [
+      "error",
+      {
+        "selector": "ImportDeclaration[source.value=/^\\./][source.value!=/\\.(js(on(c)?)?|(s)?css|svg|ico)$/]",
+        "message": "Local imports must have the explicit extension"
+      }
+    ],
+    "max-len": [
+      "error",
+      {
+        "code": 120,
+        "ignoreComments": true,
+        "ignoreTrailingComments": true,
+        "ignoreUrls": true,
+        "ignoreStrings": true,
+        "ignoreTemplateLiterals": true,
+        "ignoreRegExpLiterals": true
+      }
+    ],
+    "eol-last": ["error", "always"],
+    "eqeqeq": [2, "always"],
+    "no-var": 2,
+    "block-scoped-var": 2,
+    "no-async-promise-executor": 2,
+    "no-bitwise": [2, { "allow": ["~"] }],
+    "no-duplicate-imports": [2, { "includeExports": true }],
+    "no-eq-null": 2,
+    "no-multiple-empty-lines": [2, { "max": 1, "maxEOF": 0 }],
+    "no-template-curly-in-string": 2,
+    "no-unneeded-ternary": 2,
+    "quote-props": [2, "as-needed"],
+    "require-await": 2,
+    "rest-spread-spacing": [2, "never"],
+    "semi-spacing": 2,
+    "space-before-function-paren": [
+      2,
+      { "anonymous": "always", "named": "never", "asyncArrow": "always" }
+    ],
+    "space-unary-ops": 2,
+    "yoda": 2,
+    "no-const-assign": 2,
+    "no-extra-semi": 2,
+    "for-direction": 2,
+    "no-eval": 2,
+    "indent": ["error", 2, { "offsetTernaryExpressions": true }],
+    "no-empty": ["error", { "allowEmptyCatch": true }]
+  },
+  "env": {
+    "browser": true,
+    "node": true
+  },
+  "overrides": [
+    {
+      "files": ["*.ts", "*.tsx"],
+      "rules": {
+        "@typescript-eslint/semi": ["error", "always"],
+        "@typescript-eslint/quotes": [
+          "error",
+          "single",
+          { "avoidEscape": true, "allowTemplateLiterals": true }
+        ],
+        "@typescript-eslint/no-empty-function": [
+          "error",
+          { "allow": ["arrowFunctions"] }
+        ],
+        "@typescript-eslint/indent": [
+          "error",
+          2,
+          { "offsetTernaryExpressions": true }
+        ]
+      }
+    },
+    {
+      "files": ["*.js"],
+      "parserOptions": {
+        "project": null
+      },
+      "rules": {
+        "semi": ["error", "always"],
+        "quotes": [
+          "error",
+          "single",
+          { "avoidEscape": true, "allowTemplateLiterals": true }
+        ],
+        "no-unused-vars": 2
+      }
+    },
+    {
+      "files": ["static/**/*"],
+      "rules": {
+        "import/no-unresolved": "off",
+        "@typescript-eslint/no-var-requires": "off",
+        "@typescript-eslint/no-unused-vars": "off",
+        "no-unused-vars": "off",
+        "no-bitwise": "off"
+      }
+    }
+  ],
+  "settings": {
+    "import/resolver": {
+      "typescript": {
+        "alwaysTryTypes": true,
+        "extensions": [".js", ".ts", "*.jsx", ".tsx"]
+      }
+    }
+  }
+}

website/.gitignore

@@ -0,0 +1,22 @@
+# Dependencies
+/node_modules
+
+# Production
+/build
+
+# Generated files
+.docusaurus
+.cache-loader
+i18n/**/docusaurus-theme-classic/navbar.json
+i18n/**/code.json
+
+# Misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*

website/.prettierignore

@@ -0,0 +1,5 @@
+/build
+/.docusaurus
+/.cache-loader
+# /**/*.mdx
+package-lock.json

website/.prettierrc

@@ -0,0 +1,17 @@
+{
+  "printWidth": 80,
+  "tabWidth": 2,
+  "semi": true,
+  "singleQuote": true,
+  "quoteProps": "as-needed",
+  "jsxSingleQuote": true,
+  "trailingComma": "es5",
+  "bracketSpacing": true,
+  "bracketSameLine": false,
+  "arrowParens": "always",
+  "proseWrap": "preserve",
+  "htmlWhitespaceSensitivity": "css",
+  "endOfLine": "auto",
+  "embeddedLanguageFormatting": "auto",
+  "singleAttributePerLine": false
+}

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/acknowledgements.mdx

@@ -0,0 +1,7 @@
+# Acknowledgements
+
+- Internal protocol is written by @sidorares [MySQL-Native](https://github.com/sidorares/nodejs-mysql-native)
+- Constants, SQL parameters interpolation, Pooling, `ConnectionConfig` class taken from [node-mysql](https://github.com/mysqljs/mysql)
+- SSL upgrade code based on @TooTallNate [code](https://gist.github.com/TooTallNate/848444)
+- Secure connection / compressed connection api flags compatible to [MariaSQL](https://github.com/mscdex/node-mariasql/) client.
+- [Contributors](https://github.com/sidorares/node-mysql2/graphs/contributors)

website/docs/api-and-configurations.mdx

@@ -0,0 +1,11 @@
+# API and Configuration
+
+MySQL2 is mostly API compatible with [Node MySQL][node-mysql].
+
+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/contributing/00-index.mdx

@@ -0,0 +1,13 @@
+---
+slug: /contributing
+title: MySQL2
+---
+
+import { PageTitle } from '@site/src/components/PageTitle';
+
+<PageTitle title='Contributing' />
+
+# Contributing
+
+Want to improve something in **MySQL2**?
+Please check [Contributing.md](https://github.com/sidorares/node-mysql2/blob/master/Contributing.md) for detailed instruction on how to get started.