easy-mysql-tools v0.0.12
Easy-MySQL-Tools
介绍
MySQL 常用的增删改查工具合集，提升 MySQL 在 TypeScript 中的使用体验
- 基于 TypeScript 和 MySQL2
- 包含了简单的增删改查等基本功能
- 使用了
MySQL2模块 的escape功能，避免注入 - 根据数据库的类型，自动生成查询的配置以及结果类型，也就是让
TypeScript识别出查询的结果类型，而非一直是any
安装
yarn add easy-mysql-tools
# 或者
npm i easy-mysql-tools使用
简单三个步骤：
- 使用
type定义你的数据库结构，不要使用interface - 使用
createTools创建查询工具合集 - 使用
insert、select、update、remove、count等五种方法进行查询
注意：使用 createTools 时必须提供数据库的类型，否则这个模块便失去了意义
import { createTools } from "easy-mysql-tools"
// 定义你的数据库结构，不要使用 interface
type MyDatabase = {
userTable: {
id: number,
username: string,
age: number,
phone: number,
email: string,
intrd?: string
},
articleTable: {
id: number,
title: string,
content: string
}
}
// 配置同 MySQL2 的配置
// 必须提供数据库的类型，否则这个模块便失去了意义
const tools = createTools<MyDatabase>({
host: "x.x.x.x",
user: "root",
password: "password",
database: "mydatabase"
})
// 取出五种方法
const { insert, select, update, remove, count } = tools
// 使用 select 方法
select({
// 这里会自动提供所有的表名供你使用
tableName: "userTable",
// 这里会自动提供已选表所有的字段供你使用
where: {
// 你可以直接提供一个值，表示等于的情况
id: 123,
// 也可以使用对象来表示，小于大于等比较运算符
age: {
equal: ">=",
value: 18
},
intrd: {
equal: "!=",
value: null
}
},
order: {
// 这里会自动提供已选表所有的字段供你使用
field: "age",
// desc 或者 asc，默认为 asc
method: "desc"
},
limit: {
offset: 6,
count: 2
},
// 这里会自动提供已选表所有的字段供你使用
// 如果你使用 whiteList，只会选取列表中字段
whiteList: ["id", "username", "email"],
// 如果你想要将 MySQL 返回的 null 数据自动转换为 undefined，可以开启这一项，默认不开启
transformNullToUndefined: true
}).then(data => {
// TypeScript 可以自动识别出查询 data 的类型
typeof data = {
id: number,
username: string,
email: string
}
})insert、select、update、remove、count 五个方法的使用方式均一样，传入一个配置文件即可，比如 count(config)
配置
type QueryConfig = {
tableName: TableName,
data?: Data,
where?: Where,
order?: Order,
limit?: Limit,
whiteList?: WhiteList,
transformNullToUndefined?: TransformNullToUndefined
}tableName
type TableName = "userTable" | "articleTable"必填项，类型为传入的数据库类型的所有数据表表名
data
type Data = {
[Key in keyof MyDatabase["userTable"]]?: MyDatabase["userTable"][Key] | null
}可选项，在 insert 方法中，data 便是新增记录的数据，在 update 方法中，data 便是希望符合条件数据更新之后变成的值
where
type SingleWhere = {
[Key in keyof MyDatabase["userTable"]]: MyDatabase["userTable"][Key] | null | {
equal: "<" | "<=" | "=" | "!=" | ">=" | ">",
value: MyDatabase["userTable"][Key]
}
}
type Where = SingleWhere | SingleWhere[]可选项，有两种形式，对于单个查询条件来说（where 是一个 SingleWhere 对象），键名为已选数据库的字段，每个字段之间的关系是 且 或者说 And，键值有两种形式
直接提供一个值，表示等于的情况
const config = { tableName: "userTable", where: { id: 123, age: 18 } }此时表示，查询
id等于123且age等于18的数据。对于键值为null的情况，会自动转换为id is null使用对象来表示，小于大于等比较运算符
const config = { tableName: "userTable", where: { id: { equal: "<=", value: 123 } } }equal的类型为"<" | "<=" | "=" | "!=" | ">=" | ">"，此时表示，查询id小于等于123的数据。对于键值为
null的情况如果比较运算符为
=，则视为id is null如果比较运算符为
"<" | "!=" | ">"，则视为id is not null如果比较运算符为
"<=" | ">="，则忽略这一条件。
当然，你可以提供多个查询条件（where 是一个 SingleWhere[] 数组），每个条件之间的关系是 或 或者说 Or
{
where: [
{ id: 1 },
{ age: { equal: ">=", value: 18 } }
]
}上述代码代表，查询 id 为 1 或者 age 大于等于 18 的记录
order
type SingleOrder = {
field: keyof MyDatabase["userTable"],
// 默认为 asc
method?: "asc" | "desc"
}
type Order= SingleOrder | SingleOrder[]可选项，默认排序方式为 asc，可以是单个排序方式，也可以是多个排序方式组成的数组
limit
type Limit = {
offset?: number,
count: number
}可选项，offset 默认为 0
whiteList
type WhiteList = (keyof MyDatabase["userTable"])[]可选项，指定提取出来的字段，默认为全部字段
transformNullToUndefined
type TransformNullToUndefined = boolen可选项，是否将结果中的所有 null 转换为 undefined，默认不开启
方法
所有的方法都在由 createTools 创建的对象中，使用 createTools 必须提供泛型参数以及函数参数。泛型为你的数据库类型（不要使用 interface，请使用 type 定义），函数参数同 MySQL2 的配置
import { createTools } from "easy-mysql-tools"
// 定义你的数据库结构，不要使用 interface
type MyDatabase = {
userTable: {
id: number,
username: string,
age: number,
phone: number,
email: string,
intrd?: string
},
articleTable: {
id: number,
title: string,
content: string
}
}
// 配置同 MySQL2 的配置，传入数据库类型以及数据库配置
// 必须提供数据库的类型，否则这个模块便失去了意义
const tools = createTools<MyDatabase>({
host: "x.x.x.x",
user: "root",
password: "password",
database: "mydatabase"
})
const { pool, promisePool, query, insert, select, update, remove, count } = toolsMySQL2 的导出对象
pool、promisePool、query 这三者是使用 MySQL2 模块创建的对象或者方法
pool 等于 mysql.createPool(options)，promisePool 等于 pool.promise()，query 等于 promisePool.query。当你不满足于使用 easy-mysql-tools 的几种方法时，可以使用 MySQL2 的对象或者方法
Easy-MySQL-Tools 的导出方法
insert、select、update、remove、count 这五个是 easy-mysql-tools 提供的方法。
这几种方法参数类型相同，均可以提供两个参数：
第一个参数：配置QueryConfig，必须提供
第二个参数：回调函数Callback，可选，为进阶功能
注意：这个五个方法内部都捕捉了错误，因此，即使查询出错，也会有默认的返回值，如果有抛出错误或者其他高级需求，请看回调函数Callback
下面介绍只提供第一个 Config 参数的情况下，五个函数的返回值类型：
插入 · insert(config)
返回值类型为 Promise<number | undefined>，插入成功返回插入的 insertId 值，也就是那一条新纪录的 id 值，插入失败或者报错返回 Promise<undefined>
选取 · select(config)
返回值为记录的数组 Promise<singleRecord[]>，当提供了 whiteList 时，每条记录只包含 whiteList 所含字段，如果没有则包含数据表所有的字段，查询失败或者报错返回空数组 Promise<[]>
更新 · update(config)
返回值为 Promise<number>，更新成功则返回更新的记录数 affectedRows 值，更新失败或者报错返回 Promise<0>
删除 · remove(config)
返回值为 Promise<number>，删除成功则返回删除的记录数 affectedRows 值，删除失败或者报错返回 Promise<0>
计数 · count(config)
返回值为 Promise<number>，统计符合条件的记录数，统计失败或者报错返回 Promise<0>
回调函数
type Callback<T, K> = (error?: any, result?: [mysql.RowDataPacket[] | mysql.RowDataPacket[][] | mysql.OkPacket | mysql.OkPacket[] | mysql.ResultSetHeader, mysql.FieldPacket[]] | null, value?: K) => T如果你对 easy-mysql-tools 的默认捕获错误行为不满意，又或者对于他的数据处理方式不满意，可以在上方的五个方法，提供第二个参数，也就是回调函数。当你使用了回调函数以后，回调函数的返回值将作为查询方法的返回值。以下是回调函数的三个参数
- error
查询过程中被 try {...} catch(error) {...} 捕获的错误，如果没有错误被捕获则是 null
- result
使用 MySQL2 模块查询的原生返回结果，你可以使用这个结果，来进行你想要的数据处理，查询出错时，为 null
- data
查询方法在没有使用 callback 的情况下应该返回的值，比如你只是想要打印一下错误，并不想做其他的事，你可以这样写：
insert(config, (error, result, data) => {
if (error) {
console.log(error)
}
// 注意：回调函数的返回值，将会是查询方法的返回值
return data
})当然，TypeScript 依旧能够识别回调函数的返回值类型
默认配置
import { setDefaultConfig } from "easy-mysql-tools"
type DefaultCOnfig = {
transformNullToUndefined?: boolen
}
setDefaultConfig({
transformNullToUndefined: true
})暂时只支持 transformNullToUndefined 的默认配置