docs: add and improve examples of connections, queries and more (#2337)

* chore: prevent large package-lock.json modifications

* ci: add unit tests

* docs: `SELECT` examples using  Prepared Statement

* chore: update Docusaurus

* ci: include unit tests

* ci: check for doc files extensions

* docs: adapting examples for both JS and TS

* docs: `INSERT` examples using Prepared Statement

* docs: `UPDATE` examples using Prepared Statement

* docs: `DELETE` examples using Prepared Statement

* docs: fix broken links

* ci: throw for broken links

* docs: include tags

* ci: rename website CI and include unit tests

* docs: `SELECT` query examples

* docs: `INSERT` query examples

* docs: `UPDATE` query examples

* docs: `DELETE` query examples

* docs: introduce connection examples

* docs: `createConnection` examples

* docs: `createPool` examples

* docs: `createPoolCluster` examples

* docs: group queries examples

* docs: unify, group and reorganize examples

* docs: fix broken links

* docs: suggest examples in their respective sections in home

* docs: add Row as Array query example

* docs: polish examples

* docs: add `ExternalCodeEmbed` component to website contributing

.github/workflows/website.yml → .github/workflows/ci-website.yml

@@ -33,5 +33,8 @@ jobs:
       - name: Checking Types
         run: cd website && npm run typecheck
 
+      - name: Run Unit Tests
+        run: cd website && npm run test:unit
+
       - name: Checking Build
         run: cd website && npm run build

.github/workflows/gh-pages.yml

@@ -32,6 +32,9 @@ jobs:
       - name: Checking Types
         run: cd website && npm run typecheck
 
+      - name: Run Unit Tests
+        run: cd website && npm run test:unit
+
       - name: Building Site
         run: cd website && npm run build
 

website/.eslintignore

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

website/.eslintrc.json

@@ -8,7 +8,8 @@
     "plugin:import/errors",
     "plugin:import/warnings",
     "plugin:react-hooks/recommended",
-    "plugin:react/jsx-runtime"
+    "plugin:react/jsx-runtime",
+    "plugin:@docusaurus/recommended"
   ],
   "parserOptions": {
     "ecmaVersion": "latest",

website/.prettierignore

@@ -2,4 +2,3 @@
 /.docusaurus
 /.cache-loader
 # /**/*.mdx
-package-lock.json

website/docs/contributing/website.mdx

@@ -5,6 +5,7 @@ title: Documentation Site
 import { FAQ } from '@site/src/components/FAQ';
 import { History } from '@site/src/components/History';
 import { Stability } from '@site/src/components/Stability';
+import { ExternalCodeEmbed } from '@site/src/components/ExternalCodeEmbed';
 
 # Website Contributing Guidelines
 
@@ -145,7 +146,8 @@ import { FAQ } from '@site/src/components/FAQ';
 
 - The **FAQ** component can be utilized in any section or page.
 - Code blocks are compatible and can be used within the **FAQ** component.
-  :::
+
+:::
 
 <FAQ title='Example'>
   <FAQ title='Title'>
@@ -157,6 +159,42 @@ import { FAQ } from '@site/src/components/FAQ';
 
 ---
 
+### ExternalCodeEmbed
+
+{/* prettier-ignore-start */}
+```tsx
+import { ExternalCodeEmbed } from '@site/src/components/ExternalCodeEmbed';
+
+<ExternalCodeEmbed
+  url='https://github.com/sidorares/node-mysql2/blob/75b05f0765c9edd0c0be8f18d85be05618770cca/.prettierrc'
+  language='json'
+/>
+
+<ExternalCodeEmbed
+  url='https://raw.githubusercontent.com/sidorares/node-mysql2/master/tools/parse-row.js'
+  language='js'
+  extractMethod='parseC'
+  methodType='function'
+/>
+```
+{/* prettier-ignore-end */}
+
+<FAQ title='Example'>
+  <ExternalCodeEmbed
+    url='https://raw.githubusercontent.com/sidorares/node-mysql2/master/.prettierrc'
+    language='json'
+  />
+
+  <ExternalCodeEmbed
+    url='https://raw.githubusercontent.com/sidorares/node-mysql2/master/tools/parse-row.js'
+    language='js'
+    extractMethod='parseC'
+    methodType='function'
+  />
+</FAQ>
+
+---
+
 ## Running Tests
 
 ```bash

website/docs/documentation/prepared-statements.mdx

@@ -1,3 +1,7 @@
+---
+tags: [Prepared Statements, execute]
+---
+
 # Prepared Statements
 
 ## Automatic creation, cached and re-used by connection
@@ -39,11 +43,11 @@ connection.prepare('select ? + ? as tests', (err, statement) => {
 
 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.
 
-# Configuration
+## Configuration
 
 `maxPreparedStatements` : We keep the cached statements in a [lru-cache](https://github.com/isaacs/node-lru-cache). Default size is `16000` but you can use this option to override it. Any statements that are dropped from cache will be `closed`.
 
-# Serialization of bind parameters
+## Serialization of bind parameters
 
 The bind parameter values passed to `execute` are serialized JS -> MySQL as:
 
@@ -57,3 +61,36 @@ The bind parameter values passed to `execute` are serialized JS -> MySQL as:
 - Other -> `VAR_STRING`
 
 Passing in `undefined` or a `function` will result in an error.
+
+## Prepared Statements Helper
+
+MySQL2 provides `execute` helper which will prepare and query the statement. You can also manually prepare / unprepare statement with `prepare` / `unprepare` methods.
+
+```js
+connection.execute(
+  'select ?+1 as qqq, ? as rrr, ? as yyy',
+  [1, null, 3],
+  (err, rows, fields) => {
+    console.log(err, rows, fields);
+    connection.execute(
+      'select ?+1 as qqq, ? as rrr, ? as yyy',
+      [3, null, 3],
+      (err, rows, fields) => {
+        console.log(err, rows, fields);
+        connection.unprepare('select ?+1 as qqq, ? as rrr, ? as yyy');
+        connection.execute(
+          'select ?+1 as qqq, ? as rrr, ? as yyy',
+          [3, null, 3],
+          (err, rows, fields) => {
+            console.log(err, rows, fields);
+          }
+        );
+      }
+    );
+  }
+);
+```
+
+## Examples
+
+For Prepared Statements examples, please see [here](http://localhost:3000/node-mysql2/docs/examples/queries/prepared-statements).

website/docs/documentation/promise-wrapper.mdx

@@ -72,4 +72,4 @@ co(function* () {
 });
 ```
 
-Examples in [/examples/promise-co-await](/docs/examples/promise-co-await)
+Examples in [/examples/promise-co-await](/docs/examples/promise-wrapper/co-await)

website/docs/documentation/typescript-examples.mdx

@@ -401,10 +401,10 @@ For `ProcedureCallPacket<RowDataPacket[]>`, please see the following examples.
 
 You can also check some code examples using **MySQL2** and **TypeScript** to understand advanced concepts:
 
-- [Extending and using **Interfaces** with `RowDataPacket`](/docs/examples/typescript/row-data/row-data-packet)
+- [Extending and using **Interfaces** with `RowDataPacket`](/docs/examples/typescript/row-data/index)
 - [Extending and using **Interfaces** with `RowDataPacket` and `rowAsArray`](/docs/examples/typescript/row-data/row-as-array)
 - [Extending and using **Interfaces** with `RowDataPacket` and `multipleStatements`](/docs/examples/typescript/row-data/multi-statements)
 - [Extending and using **Interfaces** with `RowDataPacket`, `rowAsArray` and `multipleStatements`](/docs/examples/typescript/row-data/row-as-array-multi-statements)
-- [Checking for `ResultSetHeader`, extending and using **Interfaces** with `RowDataPacket` from `ProcedureCallPacket`](/docs/examples/typescript/procedure-call/procedure-call-packet)
+- [Checking for `ResultSetHeader`, extending and using **Interfaces** with `RowDataPacket` from `ProcedureCallPacket`](/docs/examples/typescript/procedure-call/index)
 - [Checking for `ResultSetHeader`, extending and using **Interfaces** with `RowDataPacket` and `rowAsArray` from `ProcedureCallPacket`](/docs/examples/typescript/procedure-call/row-as-array)
 - [Creating a basic custom **MySQL2** **Class**](/docs/examples/typescript/basic-custom-class)