From f930f6e0453f6ffb62f46dec40825f0bff2307a1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Weslley=20Ara=C3=BAjo?= <46850407+wellwelwel@users.noreply.github.com> Date: Wed, 7 Jun 2023 03:40:38 -0300 Subject: [PATCH] documentation: update documentation path pattern and add all `*.md` to lint checker (#2049) * documentation: move to `documentation` * documentation: update the README documentation links * documentation: update the zh-cn README documentation links * documentation: update the Readme documentation links * documentation: change the README documentation links to local branch * documentation: change the Promise-Wrapper links to local branch * documentation: change the zh-cn README documentation links to local branch * documentation: change the documentation Readme links to local branch * documentation: update the Promise-Wrapper link * documentation: update the documentation link to `en` * fix: eslint markdown rules * fix: check for README.md in `lint:docs` script --- .eslintrc | 14 ++++++++++ README.md | 27 ++++++++++--------- documentation/.eslintrc | 10 ------- .../{ => en}/Authentication-Switch.md | 0 documentation/{ => en}/Examples.md | 0 documentation/{ => en}/Extras.md | 0 documentation/{ => en}/MySQL-Server.md | 0 documentation/{ => en}/Prepared-Statements.md | 0 documentation/{ => en}/Promise-Wrapper.md | 2 +- documentation/{ => en}/Readme.md | 14 +++++----- .../zh-cn}/README.md | 27 ++++++++++--------- lib/commands/query.js | 2 +- package.json | 2 +- 13 files changed, 52 insertions(+), 46 deletions(-) delete mode 100644 documentation/.eslintrc rename documentation/{ => en}/Authentication-Switch.md (100%) rename documentation/{ => en}/Examples.md (100%) rename documentation/{ => en}/Extras.md (100%) rename documentation/{ => en}/MySQL-Server.md (100%) rename documentation/{ => en}/Prepared-Statements.md (100%) rename documentation/{ => en}/Promise-Wrapper.md (93%) rename documentation/{ => en}/Readme.md (68%) rename {documentation_zh-cn => documentation/zh-cn}/README.md (88%) diff --git a/.eslintrc b/.eslintrc index aae4877b1c..bbfedacf49 100644 --- a/.eslintrc +++ b/.eslintrc @@ -46,6 +46,20 @@ "prettier" ], "plugins": ["@typescript-eslint"] + }, + { + "files": ["**/*.md/*js"], + "rules": { + "no-undef": "off", + "no-unused-vars": "off", + "no-console": "off", + "no-unused-labels": "off", + "strict": "off", + "prefer-arrow-callback": "off" + }, + "parserOptions": { + "sourceType": "module" + } } ] } diff --git a/README.md b/README.md index 7f7e8fed43..75f92f9bde 100644 --- a/README.md +++ b/README.md @@ -8,9 +8,9 @@ [![Windows Build][appveyor-image]][appveyor-url] [![License][license-image]][license-url] -English | [简体中文](./documentation_zh-cn/) +English | [简体中文](./documentation/zh-cn/) -> MySQL client for Node.js with focus on performance. Supports prepared statements, non-utf8 encodings, binary log protocol, compression, ssl [much more](https://github.com/sidorares/node-mysql2/tree/master/documentation) +> MySQL client for Node.js with focus on performance. Supports prepared statements, non-utf8 encodings, binary log protocol, compression, ssl [much more](./documentation/en) __Table of contents__ @@ -32,14 +32,14 @@ MySQL2 project is a continuation of [MySQL-Native][mysql-native]. Protocol parse MySQL2 is mostly API compatible with [mysqljs][node-mysql] and supports majority of features. MySQL2 also offers these additional features - Faster / Better Performance - - [Prepared Statements](https://github.com/sidorares/node-mysql2/tree/master/documentation/Prepared-Statements.md) + - [Prepared Statements](./documentation/en/Prepared-Statements.md) - MySQL Binary Log Protocol - - [MySQL Server](https://github.com/sidorares/node-mysql2/tree/master/documentation/MySQL-Server.md) + - [MySQL Server](./documentation/en/MySQL-Server.md) - Extended support for Encoding and Collation - - [Promise Wrapper](https://github.com/sidorares/node-mysql2/tree/master/documentation/Promise-Wrapper.md) + - [Promise Wrapper](./documentation/en/Promise-Wrapper.md) - Compression - - SSL and [Authentication Switch](https://github.com/sidorares/node-mysql2/tree/master/documentation/Authentication-Switch.md) - - [Custom Streams](https://github.com/sidorares/node-mysql2/tree/master/documentation/Extras.md) + - SSL and [Authentication Switch](./documentation/en/Authentication-Switch.md) + - [Custom Streams](./documentation/en/Extras.md) - [Pooling](#using-connection-pools) ## Installation @@ -145,7 +145,7 @@ You can use the pool in the same way as connections (using `pool.query()` and `p ```js // For pool initialization, see above pool.query("SELECT field FROM atable", function(err, rows, fields) { - // Connection is automatically released when query resolves + // Connection is automatically released when query resolves }) ``` @@ -153,10 +153,10 @@ Alternatively, there is also the possibility of manually acquiring a connection ```js // For pool initialization, see above pool.getConnection(function(err, conn) { - // Do something with the connection - conn.query(/* ... */); - // Don't forget to release the connection when finished! - pool.releaseConnection(conn); + // Do something with the connection + conn.query(/* ... */); + // Don't forget to release the connection when finished! + pool.releaseConnection(conn); }) ``` @@ -204,6 +204,7 @@ async function main() { const promisePool = pool.promise(); // query database using promises const [rows,fields] = await promisePool.query("SELECT 1"); +} ``` MySQL2 exposes a .promise() function on Connections, to "upgrade" an existing non-promise connection to use promise @@ -258,7 +259,7 @@ If you find any other incompatibility with [Node MySQL][node-mysql], Please repo ## Documentation -You can find more detailed documentation [here](https://github.com/sidorares/node-mysql2/tree/master/documentation). You should also check various code [examples](https://github.com/sidorares/node-mysql2/tree/master/examples) to understand advanced concepts. +You can find more detailed documentation [here](./documentation/en). You should also check various code [examples](./examples) to understand advanced concepts. ## Acknowledgements diff --git a/documentation/.eslintrc b/documentation/.eslintrc deleted file mode 100644 index 17ae522a51..0000000000 --- a/documentation/.eslintrc +++ /dev/null @@ -1,10 +0,0 @@ -{ - "rules": { - "no-undef": "off", - "no-unused-vars": "off", - "no-console": "off", - "no-unused-labels": "off", - "strict": "off" - } - } - \ No newline at end of file diff --git a/documentation/Authentication-Switch.md b/documentation/en/Authentication-Switch.md similarity index 100% rename from documentation/Authentication-Switch.md rename to documentation/en/Authentication-Switch.md diff --git a/documentation/Examples.md b/documentation/en/Examples.md similarity index 100% rename from documentation/Examples.md rename to documentation/en/Examples.md diff --git a/documentation/Extras.md b/documentation/en/Extras.md similarity index 100% rename from documentation/Extras.md rename to documentation/en/Extras.md diff --git a/documentation/MySQL-Server.md b/documentation/en/MySQL-Server.md similarity index 100% rename from documentation/MySQL-Server.md rename to documentation/en/MySQL-Server.md diff --git a/documentation/Prepared-Statements.md b/documentation/en/Prepared-Statements.md similarity index 100% rename from documentation/Prepared-Statements.md rename to documentation/en/Prepared-Statements.md diff --git a/documentation/Promise-Wrapper.md b/documentation/en/Promise-Wrapper.md similarity index 93% rename from documentation/Promise-Wrapper.md rename to documentation/en/Promise-Wrapper.md index 035f7668da..646f7d5b22 100644 --- a/documentation/Promise-Wrapper.md +++ b/documentation/en/Promise-Wrapper.md @@ -57,4 +57,4 @@ co(function * () { yield c.end(); }); ``` -Examples in [/examples/promise-co-await](https://github.com/sidorares/node-mysql2/tree/master/examples/promise-co-await) +Examples in [/examples/promise-co-await](../../examples/promise-co-await) diff --git a/documentation/Readme.md b/documentation/en/Readme.md similarity index 68% rename from documentation/Readme.md rename to documentation/en/Readme.md index b274f312d2..1f8fd848ca 100644 --- a/documentation/Readme.md +++ b/documentation/en/Readme.md @@ -8,11 +8,11 @@ Not only `Node-MySQL2` offers better performance over `node-mysql`, we also support these additional features. -- [Prepared Statements](https://github.com/sidorares/node-mysql2/tree/master/documentation/Prepared-Statements.md) -- [Promise Wrapper](https://github.com/sidorares/node-mysql2/tree/master/documentation/Promise-Wrapper.md) -- [Authentication Switch](https://github.com/sidorares/node-mysql2/tree/master/documentation/Authentication-Switch.md) -- [More Features](https://github.com/sidorares/node-mysql2/tree/master/documentation/Extras.md) -- [MySQL Server](https://github.com/sidorares/node-mysql2/tree/master/documentation/MySQL-Server.md) +- [Prepared Statements](./Prepared-Statements.md) +- [Promise Wrapper](./Promise-Wrapper.md) +- [Authentication Switch](./Authentication-Switch.md) +- [More Features](./Extras.md) +- [MySQL Server](./MySQL-Server.md) - Pooling - SSL - MySQL Compression @@ -20,7 +20,7 @@ Not only `Node-MySQL2` offers better performance over `node-mysql`, we also supp ## Examples -Please check these [examples](https://github.com/sidorares/node-mysql2/tree/master/documentation/Examples.md) for `node-mysql2`. +Please check these [examples](./Examples.md) for `node-mysql2`. ## Known incompatibilities with `node-mysql` @@ -48,4 +48,4 @@ You need to check corresponding field's zeroFill flag and convert to string manu - 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 + - try to run example [benchmarks](../../benchmarks) on your system diff --git a/documentation_zh-cn/README.md b/documentation/zh-cn/README.md similarity index 88% rename from documentation_zh-cn/README.md rename to documentation/zh-cn/README.md index db420eb84f..670a478866 100644 --- a/documentation_zh-cn/README.md +++ b/documentation/zh-cn/README.md @@ -8,9 +8,9 @@ [![Windows Build][appveyor-image]][appveyor-url] [![License][license-image]][license-url] -[English](../README.md) | 简体中文 +[English](../..) | 简体中文 -> 适用于Node.js的MySQL客户端，专注于性能优化。支持SQL预处理、非UTF-8编码支持、二进制文件编码支持、压缩和SSL等等 [查看更多](https://github.com/sidorares/node-mysql2/tree/master/documentation) +> 适用于Node.js的MySQL客户端，专注于性能优化。支持SQL预处理、非UTF-8编码支持、二进制文件编码支持、压缩和SSL等等 [查看更多](../en) __目录__ @@ -32,14 +32,14 @@ MySQL2 项目是 [MySQL-Native][mysql-native] 的延续。 协议解析器代码 MySQL2 大部分 API 与 [mysqljs][node-mysql] 兼容，并支持大部分功能。 MySQL2 还提供了更多的附加功能 - 更快、更好的性能 - - [支持预处理](https://github.com/sidorares/node-mysql2/tree/master/documentation/Prepared-Statements.md) + - [支持预处理](../en/documentation/en/Prepared-Statements.md) - MySQL二进制日志协议 - - [MySQL Server](https://github.com/sidorares/node-mysql2/tree/master/documentation/MySQL-Server.md) + - [MySQL Server](../en/documentation/en/MySQL-Server.md) - 对编码和排序规则有很好的支持 - - [Promise封装](https://github.com/sidorares/node-mysql2/tree/master/documentation/Promise-Wrapper.md) + - [Promise封装](../en/documentation/en/Promise-Wrapper.md) - 支持压缩 - - SSL 和 [Authentication Switch](https://github.com/sidorares/node-mysql2/tree/master/documentation/Authentication-Switch.md) - - [自定义流](https://github.com/sidorares/node-mysql2/tree/master/documentation/Extras.md) + - SSL 和 [Authentication Switch](../en/documentation/en/Authentication-Switch.md) + - [自定义流](../en/documentation/en/Extras.md) - [连接池](#using-connection-pools) ## 安装 @@ -143,7 +143,7 @@ const pool = mysql.createPool({ ```js // For pool initialization, see above pool.query("SELECT field FROM atable", function(err, rows, fields) { - // Connection is automatically released when query resolves + // Connection is automatically released when query resolves }) ``` @@ -151,10 +151,10 @@ pool.query("SELECT field FROM atable", function(err, rows, fields) { ```js // For pool initialization, see above pool.getConnection(function(err, conn) { - // Do something with the connection - conn.query(/* ... */); - // Don't forget to release the connection when finished! - pool.releaseConnection(conn); + // Do something with the connection + conn.query(/* ... */); + // Don't forget to release the connection when finished! + pool.releaseConnection(conn); }) ``` @@ -202,6 +202,7 @@ async function main() { const promisePool = pool.promise(); // query database using promises const [rows,fields] = await promisePool.query("SELECT 1"); +} ``` MySQL2 在 Connections 上公开了一个 .promise*()函数，以“升级”现有的 non-promise 连接以使用 Promise @@ -254,7 +255,7 @@ MySQL2大部分的API与 [Node MySQL][node-mysql] 基本上相同，你应该查 ## 文档 -你可以在[这里](https://github.com/sidorares/node-mysql2/tree/master/documentation)获得更多的详细文档，并且你应该查阅各种代码[示例](https://github.com/sidorares/node-mysql2/tree/master/examples)来获得更高级的概念。 +你可以在[这里](../en/documentation/en)获得更多的详细文档，并且你应该查阅各种代码[示例](../en/examples)来获得更高级的概念。 ## 鸣谢 diff --git a/lib/commands/query.js b/lib/commands/query.js index e51da3c13e..8d643bdc4b 100644 --- a/lib/commands/query.js +++ b/lib/commands/query.js @@ -37,7 +37,7 @@ class Query extends Command { then() { const err = - "You have tried to call .then(), .catch(), or invoked await on the result of query that is not a promise, which is a programming error. Try calling con.promise().query(), or require('mysql2/promise') instead of 'mysql2' for a promise-compatible version of the query interface. To learn how to use async/await or Promises check out documentation at https://www.npmjs.com/package/mysql2#using-promise-wrapper, or the mysql2 documentation at https://github.com/sidorares/node-mysql2/tree/master/documentation/Promise-Wrapper.md"; + "You have tried to call .then(), .catch(), or invoked await on the result of query that is not a promise, which is a programming error. Try calling con.promise().query(), or require('mysql2/promise') instead of 'mysql2' for a promise-compatible version of the query interface. To learn how to use async/await or Promises check out documentation at https://www.npmjs.com/package/mysql2#using-promise-wrapper, or the mysql2 documentation at https://github.com/sidorares/node-mysql2/tree/master/documentation/en/Promise-Wrapper.md"; // eslint-disable-next-line console.log(err); throw new Error(err); diff --git a/package.json b/package.json index 3693dfe317..f93b19a280 100644 --- a/package.json +++ b/package.json @@ -10,7 +10,7 @@ "scripts": { "lint": "npm run lint:docs && npm run lint:code", "lint:code": "eslint index.js promise.js \"lib/**/*.js\" \"test/**/*.js\" \"benchmarks/**/*.js\"", - "lint:docs": "eslint Contributing.md \"documentation/**/*.md\" \"examples/*.js\"", + "lint:docs": "eslint Contributing.md README.md \"documentation/**/*.md\" \"examples/*.js\"", "test": "node ./test/run.js", "test:tsc-build": "cd \"test/tsc-build\" && npx tsc -p \"tsconfig.json\"", "coverage-test": "c8 -r cobertura -r lcov -r text node ./test/run.js",