|
|
// 创建一个空的对象（原型为空），用于存储后续加载的类，避免重复加载相同的类，起到一种缓存类的作用。
|
|
|
var Classes = Object.create(null);
|
|
|
|
|
|
/**
|
|
|
* Create a new Connection instance.
|
|
|
* 创建一个新的数据库连接（Connection）实例。
|
|
|
* 接收一个配置参数，可以是一个对象形式的配置信息或者是一个连接字符串，用于配置新的MySQL连接相关设置，最终返回一个新创建的MySQL连接实例。
|
|
|
*
|
|
|
* @param {object|string} config Configuration or connection string for new MySQL connection 用于新的MySQL连接的配置信息，可以是对象或者字符串形式。
|
|
|
* @return {Connection} A new MySQL connection 返回一个新创建的MySQL连接实例。
|
|
|
* @public
|
|
|
*/
|
|
|
exports.createConnection = function createConnection(config) {
|
|
|
// 调用 `loadClass` 函数（内部私有函数，用于加载指定名称的类）加载名为 `Connection` 的类，获取对应的类构造函数或已导出的对象，后续用于创建实例。
|
|
|
var Connection = loadClass('Connection');
|
|
|
// 同样调用 `loadClass` 函数加载名为 `ConnectionConfig` 的类，用于创建连接配置相关的对象。
|
|
|
var ConnectionConfig = loadClass('ConnectionConfig');
|
|
|
|
|
|
// 使用加载到的 `Connection` 类的构造函数创建一个新的实例，传入一个配置对象，该配置对象中的 `config` 属性值是通过 `ConnectionConfig` 类根据传入的 `config` 参数创建的新的连接配置对象，最终返回创建好的连接实例。
|
|
|
return new Connection({config: new ConnectionConfig(config)});
|
|
|
};
|
|
|
|
|
|
/**
|
|
|
* Create a new Pool instance.
|
|
|
* 创建一个新的数据库连接池（Pool）实例。
|
|
|
* 接收一个配置参数，该参数可以是对象形式的配置信息或者是一个连接字符串，用于配置新的MySQL连接池相关设置，最终返回一个新创建的MySQL连接池实例。
|
|
|
*
|
|
|
* @param {object|string} config Configuration or connection string for new MySQL connections 用于新的MySQL连接池的配置信息，可以是对象或者字符串形式。
|
|
|
* @return {Pool} A new MySQL pool 返回一个新创建的MySQL连接池实例。
|
|
|
* @public
|
|
|
*/
|
|
|
exports.createPool = function createPool(config) {
|
|
|
// 调用 `loadClass` 函数加载名为 `Pool` 的类，获取对应的类构造函数或已导出的对象，用于后续创建实例。
|
|
|
var Pool = loadClass('Pool');
|
|
|
// 调用 `loadClass` 函数加载名为 `PoolConfig` 的类，用于创建连接池配置相关的对象。
|
|
|
var PoolConfig = loadClass('PoolConfig');
|
|
|
|
|
|
// 使用加载到的 `Pool` 类的构造函数创建一个新的实例，传入一个配置对象，该配置对象中的 `config` 属性值是通过 `PoolConfig` 类根据传入的 `config` 参数创建的新的连接池配置对象，最终返回创建好的连接池实例。
|
|
|
return new Pool({config: new PoolConfig(config)});
|
|
|
};
|
|
|
|
|
|
/**
|
|
|
* Create a new PoolCluster instance.
|
|
|
* 创建一个新的数据库连接池集群（PoolCluster）实例。
|
|
|
* 接收一个可选的配置对象参数，用于配置新的MySQL连接池集群相关设置，最终返回一个新创建的MySQL连接池集群实例。
|
|
|
*
|
|
|
* @param {object} [config] Configuration for pool cluster 用于新的MySQL连接池集群的配置信息，是一个可选的对象参数。
|
|
|
* @return {PoolCluster} New MySQL pool cluster 返回一个新创建的MySQL连接池集群实例。
|
|
|
* @public
|
|
|
*/
|
|
|
exports.createPoolCluster = function createPoolCluster(config) {
|
|
|
// 调用 `loadClass` 函数加载名为 `PoolCluster` 的类，获取对应的类构造函数或已导出的对象，用于后续创建实例。
|
|
|
var PoolCluster = loadClass('PoolCluster');
|
|
|
|
|
|
// 使用加载到的 `PoolCluster` 类的构造函数创建一个新的实例，传入传入的 `config` 参数（如果有的话），最终返回创建好的连接池集群实例。
|
|
|
return new PoolCluster(config);
|
|
|
};
|
|
|
|
|
|
/**
|
|
|
* Create a new Query instance.
|
|
|
* 创建一个新的查询（Query）对象实例。
|
|
|
* 接收SQL语句字符串、可选的占位符对应的值数组以及可选的查询完成后的回调函数，用于构建一个新的查询对象，便于后续执行查询操作等。
|
|
|
*
|
|
|
* @param {string} sql The SQL for the query 要执行的SQL语句字符串。
|
|
|
* @param {array} [values] Any values to insert into placeholders in sql 可选参数，用于填充SQL语句中占位符的值的数组。
|
|
|
* @param {function} [callback] The callback to use when query is complete 可选参数，查询完成后要调用的回调函数。
|
|
|
* @return {Query} New query object 返回一个新创建的查询对象实例。
|
|
|
* @public
|
|
|
*/
|
|
|
exports.createQuery = function createQuery(sql, values, callback) {
|
|
|
// 调用 `loadClass` 函数加载名为 `Connection` 的类，获取对应的类构造函数或已导出的对象，后续利用该类来创建查询对象。
|
|
|
var Connection = loadClass('Connection');
|
|
|
|
|
|
// 通过加载到的 `Connection` 类的静态方法 `createQuery`（假设存在该静态方法，具体功能依赖于 `Connection` 类的实现）创建一个新的查询对象实例，传入相应的参数（SQL语句、值数组、回调函数），并返回创建好的查询对象。
|
|
|
return Connection.createQuery(sql, values, callback);
|
|
|
};
|
|
|
|
|
|
/**
|
|
|
* Escape a value for SQL.
|
|
|
* 对要插入到SQL语句中的值进行转义处理，使其符合SQL语法要求，避免出现语法错误或安全漏洞（如SQL注入问题），最终返回转义后的字符串形式的值。
|
|
|
*
|
|
|
* @param {*} value The value to escape 要进行转义处理的任意类型的值，可以是字符串、数字、对象等各种类型，具体转义逻辑会根据不同类型进行相应处理。
|
|
|
* @param {boolean} [stringifyObjects=false] Setting if objects should be stringified 可选参数，一个布尔值，用于指定是否将对象类型的值转换为字符串形式进行转义处理，默认值为 `false`。
|
|
|
* @param {string} [timeZone=local] Setting for time zone to use for Date conversion 可选参数，指定用于日期类型值转换时所使用的时区设置，默认值为 `local`（本地时区，具体含义依赖于实现）。
|
|
|
* @return {string} Escaped string value 返回转义后的字符串形式的值，可安全地插入到SQL语句中对应的位置。
|
|
|
* @public
|
|
|
*/
|
|
|
exports.escape = function escape(value, stringifyObjects, timeZone) {
|
|
|
// 调用 `loadClass` 函数加载名为 `SqlString` 的类，获取对应的类构造函数或已导出的对象，后续利用该类中的转义方法来处理值。
|
|
|
var SqlString = loadClass('SqlString');
|
|
|
|
|
|
// 调用 `SqlString` 类的 `escape` 方法（具体转义逻辑在该类中实现），传入要转义的值以及可选的 `stringifyObjects` 和 `timeZone` 参数，进行转义处理，并返回转义后的字符串结果。
|
|
|
return SqlString.escape(value, stringifyObjects, timeZone);
|
|
|
};
|
|
|
|
|
|
/**
|
|
|
* Escape an identifier for SQL.
|
|
|
* 对SQL语句中的标识符（例如表名、列名等）进行转义处理，确保其符合SQL语法规范，避免出现语法错误或因特殊字符导致的问题，最终返回转义后的字符串形式的标识符。
|
|
|
*
|
|
|
* @param {*} value The value to escape 要进行转义处理的标识符，可以是字符串等类型，具体转义逻辑会根据标识符的特点进行相应处理。
|
|
|
* @param {boolean} [forbidQualified=false] Setting to treat '.' as part of identifier 可选参数，一个布尔值，用于指定是否将 `.`（点号）视为标识符的一部分来进行处理，默认值为 `false`。
|
|
|
* @return {string} Escaped string value 返回转义后的字符串形式的标识符，可安全地在SQL语句中使用。
|
|
|
* @public
|
|
|
*/
|
|
|
exports.escapeId = function escapeId(value, forbidQualified) {
|
|
|
// 调用 `loadClass` 函数加载名为 `SqlString` 的类，获取对应的类构造函数或已导出的对象，后续利用该类中的标识符转义方法来处理标识符。
|
|
|
var SqlString = loadClass('SqlString');
|
|
|
|
|
|
// 调用 `SqlString` 类的 `escapeId` 方法（具体转义逻辑在该类中实现），传入要转义的标识符以及可选的 `forbidQualified` 参数，进行转义处理，并返回转义后的字符串结果。
|
|
|
return SqlString.escapeId(value, forbidQualified);
|
|
|
};
|
|
|
|
|
|
/**
|
|
|
* Format SQL and replacement values into a SQL string.
|
|
|
* 将SQL语句和对应的占位符替换值进行格式化处理，生成最终可以直接在数据库中执行的完整SQL语句字符串，方便后续执行数据库操作。
|
|
|
*
|
|
|
* @param {string} sql The SQL for the query 要进行格式化的SQL语句字符串，其中可能包含占位符等需要替换的内容。
|
|
|
* @param {array} [values] Any values to insert into placeholders in sql 可选参数，用于填充SQL语句中占位符的值的数组。
|
|
|
* @param {boolean} [stringifyObjects=false] Setting if objects should be stringified 可选参数，一个布尔值，用于指定是否将对象类型的值转换为字符串形式进行格式化处理，默认值为 `false`。
|
|
|
* @param {timeZone=local} [Setting for time zone to use for Date conversion] 可选参数，指定用于日期类型值转换时所使用的时区设置，默认值为 `local`（本地时区，具体含义依赖于实现）。
|
|
|
* @return {string} Formatted SQL string 返回格式化后的完整SQL语句字符串，可直接用于数据库执行操作。
|
|
|
* @public
|
|
|
*/
|
|
|
exports.format = function format(sql, values, stringifyObjects, timeZone) {
|
|
|
// 调用 `loadClass` 函数加载名为 `SqlString` 的类，获取对应的类构造函数或已导出的对象，后续利用该类中的格式化方法来处理SQL语句和值。
|
|
|
var SqlString = loadClass('SqlString');
|
|
|
|
|
|
// 调用 `SqlString` 类的 `format` 方法（具体格式化逻辑在该类中实现），传入要格式化的SQL语句、值数组以及可选的 `stringifyObjects` 和 `timeZone` 参数，进行格式化处理，并返回格式化后的SQL语句字符串结果。
|
|
|
return SqlString.format(sql, values, stringifyObjects, timeZone);
|
|
|
};
|
|
|
|
|
|
/**
|
|
|
* Wrap raw SQL strings from escape overriding.
|
|
|
* 将原始的SQL语句字符串进行包装处理（具体包装逻辑依赖于 `SqlString` 类的实现），返回包装后的对象，可能用于特殊的SQL处理场景或者满足特定的使用需求。
|
|
|
*
|
|
|
* @param {string} sql The raw SQL 要进行包装的原始SQL语句字符串。
|
|
|
* @return {object} Wrapped object 返回包装后的对象，具体结构和属性由包装逻辑决定。
|
|
|
* @public
|
|
|
*/
|
|
|
exports.raw = function raw(sql) {
|
|
|
// 调用 `loadClass` 函数加载名为 `SqlString` 的类，获取对应的类构造函数或已导出的对象，后续利用该类中的包装方法来处理原始SQL语句。
|
|
|
var SqlString = loadClass('SqlString');
|
|
|
|
|
|
// 调用 `SqlString` 类的 `raw` 方法（具体包装逻辑在该类中实现），传入要包装的原始SQL语句字符串，进行包装处理，并返回包装后的对象结果。
|
|
|
return SqlString.raw(sql);
|
|
|
};
|
|
|
|
|
|
/**
|
|
|
* The type constants.
|
|
|
* 定义一个名为 `Types` 的属性，通过 `Object.defineProperty` 方法设置其 `get` 访问器属性，使得在访问该属性时会调用 `loadClass` 函数加载名为 `Types` 的类，获取对应的类构造函数或已导出的对象。
|
|
|
* 这样可以以一种动态加载的方式获取类型相关的常量（具体常量内容依赖于 `Types` 类的实现），方便外部代码获取和使用这些常量。
|
|
|
* @public
|
|
|
*/
|
|
|
Object.defineProperty(exports, 'Types', {
|
|
|
get: loadClass.bind(null, 'Types')
|
|
|
});
|
|
|
|
|
|
/**
|
|
|
* Load the given class.
|
|
|
* 加载指定名称的类，首先会检查之前是否已经加载过该类（通过在 `Classes` 对象中查找），如果已加载则直接返回对应的类构造函数或已导出的对象；
|
|
|
* 如果未加载，则根据类名称通过 `switch` 语句进行不同的 `require` 操作来加载相应的模块，获取类的定义，并将加载后的类存储到 `Classes` 对象中，避免下次重复加载，最后返回加载到的类。
|
|
|
*
|
|
|
* @param {string} className Name of class to default 要加载的类的名称，用于确定加载哪个模块获取对应的类定义。
|
|
|
* @return {function|object} Class constructor or exports 返回对应的类构造函数（如果是构造函数形式的类定义）或者已导出的对象（如果模块导出的是对象形式），用于后续创建实例或其他操作。
|
|
|
* @private
|
|
|
*/
|
|
|
function loadClass(className) {
|
|
|
var Class = Classes[className];
|
|
|
|
|
|
if (Class!== undefined) {
|
|
|
return Class;
|
|
|
}
|
|
|
|
|
|
// This uses a switch for static require analysis
|
|
|
switch (className) {
|
|
|
case 'Connection':
|
|
|
Class = require('./lib/Connection');
|
|
|
break;
|
|
|
case 'ConnectionConfig':
|
|
|
Class = require('./lib/ConnectionConfig');
|
|
|
break;
|
|
|
case 'Pool':
|
|
|
Class = require('./lib/Pool');
|
|
|
break;
|
|
|
case 'PoolCluster':
|
|
|
Class = require('./lib/PoolCluster');
|
|
|
break;
|
|
|
case 'PoolConfig':
|
|
|
Class = require('./lib/PoolConfig');
|
|
|
break;
|
|
|
case 'SqlString':
|
|
|
Class = require('./lib/protocol/SqlString');
|
|
|
break;
|
|
|
case 'Types':
|
|
|
Class = require('./lib/protocol/constants/types');
|
|
|
break;
|
|
|
default:
|
|
|
throw new Error('Cannot find class \'' + className + '\'');
|
|
|
}
|
|
|
|
|
|
// Store to prevent invoking require()
|
|
|
Classes[className] = Class;
|
|
|
|
|
|
return Class;
|
|
|
} |
