jj.js 0.19.0 → 0.20.0

package/lib/db.js

@@ -4,13 +4,21 @@ const Context = require('./context');
 
 /**
  * @typedef {import('../types').KoaCtx} KoaCtx
+ * @typedef {import('../types').DbConfigItem} DbConfigItem
  * @typedef {import('../types').Pagination} Pagination
  * @typedef {import('../types').PaginationInstance} PaginationInstance
  * @typedef {import('../types').OkPacket} OkPacket
  * @typedef {import('../types').RowData} RowData
  * @typedef {import('../types').ListData} ListData
  * @typedef {import('../types').FieldInfo} FieldInfo
+ * @typedef {import('../types').Link} Link
+ * @typedef {import('../types').Operator} Operator
+ * @typedef {import('../types').Where} Where
+ * @typedef {import('../types').Sql} Sql
  * @typedef {import('../types').SqlInstance} SqlInstance
+ * @typedef {import('../types').Logger} Logger
+ * @typedef {import('../types')._DbOptions} _DbOptions
+ * @typedef {import('../types').Cache} Cache
  */
 
 /**
@@ -21,24 +29,41 @@ class Db extends Context
     /**
      * Initialize a new `Db`
      * @public
-     * @param {(object|KoaCtx)} [ctx]
-     * @param {(string|object)} [options] - 数据库配置标识或连接参数
+     * @param {object|KoaCtx} [ctx]
+     * @param {string|DbConfigItem} [options] - 数据库配置标识或连接参数
      */
     constructor(ctx, options) {
         ctx = ctx || {};
         super(ctx);
+        /**
+         * @type {DbConfigItem}
+         */
+        // @ts-ignore
         this._config = null;
         this._table = '';
+        /**
+         * @type {_DbOptions}
+         */
+        // @ts-ignore
         this._options = {};
         /**
          * @type {string}
          */
         this._queryStr = '';
-        this._tableField = {};
         /**
-         * @type {SqlInstance}
+         * @type {Map<string, string[]>}
+         */
+        this._tableField = new Map();
+        /**
+         * @type {SqlInstance} sql实例
          */
+        // @ts-ignore
         this._sql = null;
+        /**
+         * @type {String} sql语句
+         */
+        this.sql = '';
+
         this.connect(options);
     }
 
@@ -63,13 +88,14 @@ class Db extends Context
             allowField: false,
             prefix: this._config.prefix || ''
         };
+        this.sql = '';
         return this;
     }
 
     /**
      * 连接数据库连接池
      * @public
-     * @param {(string|object)} config - 数据库配置标识或连接参数
+     * @param {string|DbConfigItem} config - 数据库配置标识或连接参数
      * @returns {this}
      */
     connect(config='default') {
@@ -80,8 +106,9 @@ class Db extends Context
             this._sql = this._config.connect(this._config);
         } else {
             const sqltype = this._config.type;
+            /** @class {Sql} */
             const Sql = require(`./db/${sqltype}.js`);
-            this._sql = new Sql(this.ctx, this.$logger);
+            this._sql = new Sql(this.ctx, this._$logger);
             this._sql.connect(this._config);
         }
         
@@ -91,10 +118,11 @@ class Db extends Context
     /**
      * 关闭数据库连接池
      * @public
-     * @returns {Promise}
+     * @returns {Promise<this>}
      */
     async close() {
-        return await this._sql.close();
+        await this._sql.close();
+        return this;
     }
 
     /**
@@ -131,7 +159,7 @@ class Db extends Context
      * @param {string} sql - sql语句或参数
      * @param {*} params - sql参数
      * @param {*} [reset=true] - 是否重置参数
-     * @returns {Promise}
+     * @returns {Promise<*>}
      */
     async query(sql, params, reset=true) {
         params !== false && reset !== false && this.reset();
@@ -178,7 +206,7 @@ class Db extends Context
     /**
      * 设置查询字段，支持多次调用
      * @public
-     * @param {(string|array)} field - 表名前缀
+     * @param {string|string[]} field - 表字段
      * @returns {this}
      */
     field(field) {
@@ -194,9 +222,9 @@ class Db extends Context
     /**
      * 设置表连接，支持多次调用
      * @public
-     * @param {string} table - 要连接的表名
+     * @param {string} table - 要连接的表名，不带前缀
      * @param {string} on - 连接条件
-     * @param {string} [type=left] - 连接方式
+     * @param {string} [type=left] - 连接方式，left|right|inner|outer，默认left
      * @returns {this}
      */
     join(table, on, type='left') {
@@ -209,8 +237,8 @@ class Db extends Context
     /**
      * 设置查询条件，支持多次调用
      * @public
-     * @param {object} where - 查询条件
-     * @param {object} [logic] - 多次调用之间的连接逻辑，默认and
+     * @param {Where} where - 查询条件
+     * @param {Link} [logic] - 多次调用之间的连接逻辑，and|or，默认and
      * @returns {this}
      */
     where(where, logic) {
@@ -250,7 +278,7 @@ class Db extends Context
      * 设置排序方式，支持多次调用
      * @public
      * @param {string} field - 排序字段
-     * @param {string} [order] - 排序方式，默认asc
+     * @param {string} [order] - 排序方式，asc|desc，默认asc
      * @returns {this}
      */
     order(field, order='asc') {
@@ -263,14 +291,16 @@ class Db extends Context
     /**
      * 设置查询数量
      * @public
-     * @param {number} offset - 开始位置
+     * @param {number|string} offset - 开始位置
      * @param {number} [rows] - 行数，不传，则按offset
      * @returns {this}
      */
     limit(offset, rows) {
         if(typeof offset === 'undefined') return this;
-        offset = offset ? offset : 0;
-        rows = rows ? rows : null;
+        // @ts-ignore
+        offset = offset ? parseInt(offset) : 0;
+        // @ts-ignore
+        rows = rows ? parseInt(rows) : null;
         this._options.limit = 'limit ' + offset + (rows ? ',' + rows : '');
         return this;
     }
@@ -294,10 +324,10 @@ class Db extends Context
     /**
      * 设置查询结果缓存
      * @public
-     * @param {number} time - 为0则不缓存
+     * @param {number} time - 单位秒，为0则不缓存
      * @returns {this}
      */
-    cache(time) {
+    withCache(time) {
         this._options.cache_time = time;
         return this;
     }
@@ -305,7 +335,7 @@ class Db extends Context
     /**
      * 设置返回sql语句（最终会返回序列化后的sql，不会真实查询数据库）
      * @public
-     * @param {boolean} [fetch] - 是否返回sql
+     * @param {boolean} [fetch] - 是否返回sql，默认true
      * @returns {this}
      */
     getSql(fetch = true) {
@@ -314,9 +344,9 @@ class Db extends Context
     }
 
     /**
-     * 设置字段过滤（插入或更新数据时）
+     * 设置字段过滤（新增或更新数据时）
      * @public
-     * @param {(boolean|string|string[])} [field] - 允许保存字段，为true，则按数据表字段
+     * @param {boolean|string|string[]} [field] - 允许字段，为true，则按数据表字段
      * @returns {this}
      */
     allowField(field = true) {
@@ -330,9 +360,9 @@ class Db extends Context
     }
 
     /**
-     * 设置要插入或更新的数据
+     * 设置要新增或更新的数据
      * @public
-     * @param {object} data - 要插入或更新的数据
+     * @param {Object.<string, any>} data - 要新增或更新的数据
      * @returns {this}
      */
     data(data) {
@@ -345,20 +375,19 @@ class Db extends Context
     /**
      * 获取多条数据
      * @public
-     * @param {object} condition - 查询条件
-     * @returns {Promise<string|ListData>}
+     * @param {Where} [condition] - 查询条件，设置后将会替换where方法设置的条件
+     * @returns {Promise<ListData>}
      */
     async select(condition) {
         condition && (this._options.where = [], this._options.where.push([condition]));
 
-        let params = [];
         const table = this._parseTable();
         const distinct = this._options.distinct;
         const field = this._parseField();
         const join = this._parseJoin();
 
         const where = this._parseWhere();
-        params = params.concat(where[1]);
+        const params = where[1];
 
         const order = this._parseOrder();
 
@@ -370,18 +399,19 @@ class Db extends Context
 
         if(this._options.getSql) {
             this._options.getSql = false;
-            return this._sql.format(this._queryStr, params);
+            this.sql = this._sql.format(this._queryStr, params);
+            return;
         }
         
         if(this._options.cache_time) {
             const cache_time = this._options.cache_time;
             const cache_key = md5(this._sql.format(this._queryStr, params));
-            if(this.getCache(cache_key)) {
+            if(this._$cache.get(cache_key)) {
                 this.reset();
-                return this.getCache(cache_key);
+                return this._$cache.get(cache_key);
             }
             const result = await this.query(this._queryStr, params);
-            this.setCache(cache_key, result, cache_time);
+            this._$cache.set(cache_key, result, cache_time);
             return result;
         }
 
@@ -391,8 +421,8 @@ class Db extends Context
     /**
      * 获取一条数据
      * @public
-     * @param {object} condition - 查询条件
-     * @returns {Promise<?RowData>}
+     * @param {Where} [condition] - 查询条件
+     * @returns {Promise<(RowData|null)>}
      */
     async find(condition) {
         condition && (this._options.where = [], this._options.where.push([condition])); 
@@ -409,8 +439,8 @@ class Db extends Context
     /**
      * 获取一个字段值
      * @public
-     * @param {string} field - 字段
-     * @returns {Promise<*>}
+     * @param {string} field - 要查询的字段
+     * @returns {Promise<(any|null)>}
      */
     async value(field) {
         this._options.field = [];
@@ -479,7 +509,7 @@ class Db extends Context
      * @public
      * @param {string} field - 数据字段
      * @param {string} [key] - key字段，不设置返回数据数组，设置则返回{key: field}对象数组
-     * @returns {Promise<(ListData|object)>}
+     * @returns {Promise<(any[]|Object.<string, any>)>}
      */
     async column(field, key) {
         this._options.field = [];
@@ -490,34 +520,30 @@ class Db extends Context
             return await this.select();
         }
 
-        /**
-         * @type {ListData}
-         */
         const rows = await this.select();
-        const result = key ? {} : [];
-        rows.forEach(row => {
-            if(key) {
+        if(key) {
+            return rows.reduce((result, row) => {
                 result[row[key]] = row[field];
-            } else {
-                result.push(row[field]);
-            }
-        });
-        return result;
+                return result;
+            }, {});
+        } else {
+            return rows.map(row => row[field]);
+        }
     }
 
     /**
      * 获取多条数据（按分页）
      * @public
      * @param {object} [param0] - 分页参数
-     * @param {number} [param0.page] - 页码
-     * @param {number} [param0.page_size] - 每页行数
-     * @param {PaginationInstance} [param0.pagination] - 分页类实例
-     * @returns {Promise<array>} - [ListData, PaginationInstance]
+     * @param {number} [param0.page] - 页码，可通过page方法配置，默认从默认分页类获取
+     * @param {number} [param0.page_size] - 每页行数，可通过page方法配置，默认从config配置获取
+     * @param {PaginationInstance} [param0.pagination] - 分页类实例，为空时使用默认分页类
+     * @returns {Promise<[ListData, PaginationInstance]>} - [ListData, PaginationInstance]
      */
-    async pagination({page, page_size, pagination} = {}) {
+    async paginate({page, page_size, pagination} = {}) {
         !page && (page = this._options.page.page);
         !page_size && (page_size = this._options.page.pageSize);
-        !pagination && (pagination = this.$pagination);
+        !pagination && (pagination = this._$pagination);
 
         const options = {...this._options}; // 暂存options
         const total = await this.count();
@@ -530,6 +556,7 @@ class Db extends Context
         
         if(total) {
             this._options = options; // 恢复options
+            // @ts-ignore
             const result = await this.page(page, page_size).select();
             return [result, pagination];
         } else {
@@ -538,10 +565,10 @@ class Db extends Context
     }
 
     /**
-     * 插入一条数据
+     * 新增一条数据
      * @public
-     * @param {object} data - 待插入数据
-     * @returns {Promise<string|OkPacket>}
+     * @param {object} [data] - 待新增数据，会替换通过data方法传入的数据
+     * @returns {Promise<OkPacket>}
      */
     async insert(data) {
         data && (this._options.data = data);
@@ -553,7 +580,8 @@ class Db extends Context
         this._queryStr = `insert into ${table} ${sql}`;
         if(this._options.getSql) {
             this._options.getSql = false;
-            return this._sql.format(this._queryStr, params);
+            this.sql = this._sql.format(this._queryStr, params);
+            return;
         }
         return await this.query(this._queryStr, params);
     }
@@ -561,9 +589,9 @@ class Db extends Context
     /**
      * 更新数据
      * @public
-     * @param {object} data - 更新数据
-     * @param {object} condition - 更新条件
-     * @returns {Promise<string|OkPacket>}
+     * @param {object} [data] - 更新数据，会替换通过data方法传入的数据
+     * @param {Where} [condition] - 更新条件，会替换通过where方法传入的条件
+     * @returns {Promise<OkPacket>}
      */
     async update(data, condition) {
         data && (this._options.data = data);
@@ -576,7 +604,7 @@ class Db extends Context
         const [where, whereParams] = this._parseWhere();
         if(!where[0]) {
             const message = 'update方法必须传入where参数';
-            this.$logger.sql(message);
+            this._$logger.sql(message);
             throw new Error('DbError: ' + message);
         }
         const params = [...dataParams, ...whereParams];
@@ -584,7 +612,8 @@ class Db extends Context
         this._queryStr = `update ${table} set ${sql} ${where}`;
         if(this._options.getSql) {
             this._options.getSql = false;
-            return this._sql.format(this._queryStr, params);
+            this.sql = this._sql.format(this._queryStr, params);
+            return;
         }
         return await this.query(this._queryStr, params);
     }
@@ -593,10 +622,10 @@ class Db extends Context
      * 字段值增加
      * @public
      * @param {string} field - 字段
-     * @param {number} [step=1] - 增加值，默认1
-     * @returns {Promise<string|OkPacket>}
+     * @param {number} [step] - 增加值，默认1
+     * @returns {Promise<OkPacket>}
      */
-    async inc(field, step) {
+    async inc(field, step = 1) {
         return await this.update({[field]: ['inc', step]});
     }
 
@@ -604,10 +633,10 @@ class Db extends Context
      * 字段值减少
      * @public
      * @param {string} field - 字段
-     * @param {number} [step=1] - 减少值，默认1
-     * @returns {Promise<string|OkPacket>}
+     * @param {number} [step] - 减少值，默认1
+     * @returns {Promise<OkPacket>}
      */
-    async dec(field, step) {
+    async dec(field, step = 1) {
         return await this.update({[field]: ['dec', step]});
     }
 
@@ -616,7 +645,7 @@ class Db extends Context
      * @public
      * @param {string} field - 字段
      * @param {string} value - 自定义表达式
-     * @returns {Promise<string|OkPacket>}
+     * @returns {Promise<OkPacket>}
      */
     async exp(field, value) {
         return await this.update({[field]: ['exp', value]});
@@ -625,26 +654,26 @@ class Db extends Context
     /**
      * 删除数据
      * @public
-     * @param {object} condition - 删除条件
-     * @returns {Promise<string|OkPacket>}
+     * @param {Where} [condition] - 删除条件，会替换通过where方法传入的条件
+     * @returns {Promise<OkPacket>}
      */
     async delete(condition) {
         condition && (this._options.where = [], this._options.where.push([condition]));
 
-        let params = [];
         const table = this._parseTable();
         const where = this._parseWhere();
         if(!where[0]) {
             const message = 'delete方法必须传入where参数';
-            this.$logger.sql(message);
+            this._$logger.sql(message);
             throw new Error('DbError: ' + message);
         }
-        params = params.concat(where[1]);
+        const params = where[1];
 
         this._queryStr = `delete from ${table} ${where[0]}`;
         if(this._options.getSql) {
             this._options.getSql = false;
-            return this._sql.format(this._queryStr, params);
+            this.sql = this._sql.format(this._queryStr, params);
+            return;
         }
         return await this.query(this._queryStr, params);
     }
@@ -655,23 +684,24 @@ class Db extends Context
      * @param {string} sql - sql语句或参数
      * @param {*} params - sql参数
      * @param {*} [reset=true] - 是否重置参数
-     * @returns {Promise<string|OkPacket|ListData|RowData>}
+     * @returns {Promise<OkPacket|ListData|RowData>}
      */
     async execute(sql, params, reset=true) {
         this._queryStr = sql;
         if(this._options.getSql) {
             this._options.getSql = false;
-            return this._sql.format(this._queryStr, params);
+            this.sql = this._sql.format(this._queryStr, params);
+            return;
         }
 
         if(this._options.cache_time) {
             const cache_time = this._options.cache_time;
             const cache_key = md5(this._sql.format(this._queryStr, params));
-            if(this.getCache(cache_key)) {
-                return this.getCache(cache_key);
+            if(this._$cache.get(cache_key)) {
+                return this._$cache.get(cache_key);
             }
             const result = await this.query(this._queryStr, params);
-            this.setCache(cache_key, result, cache_time);
+            this._$cache.set(cache_key, result, cache_time);
             return result;
         }
         return await this.query(this._queryStr, params, reset);
@@ -702,11 +732,21 @@ class Db extends Context
         return table_info.map(item => item.Field);
     }
 
+    /**
+     * 解析数据表名字
+     * @public
+     * @returns {string} 包含``号的表名字
+     */
     _parseTable() {
         const table = this._table.replace(' ', '` `');
         return `\`${this._options.prefix}${table}\``;
     }
 
+    /**
+     * 解析join
+     * @public
+     * @returns {string} join字符串
+     */
     _parseJoin() {
         let join = '';
         Object.keys(this._options.join).forEach(key => {
@@ -717,7 +757,13 @@ class Db extends Context
         return join;
     }
 
+    /**
+     * 解析字段
+     * @public
+     * @returns {string} 字段字符串
+     */
     _parseField() {
+        /** @type {string[]} */
         let fields = [];
         this._options.field.forEach(value => {
             let field = value.split(' ');
@@ -727,21 +773,30 @@ class Db extends Context
                 alias = ' `' + field[length - 1] + '`';
                 field.pop();
             }
-            field = field.join(' ');
+            let field_str = field.join(' ');
             if(!~field.indexOf(')')) {
-                field = '`' + field.replace(/\./g, '`.`') + '`';
+                field_str = '`' + field_str.replace(/\./g, '`.`') + '`';
             }
-            field = field.replace('`*`', '*');
+            field_str = field_str.replace('`*`', '*');
             fields.push(field + alias);
         });
         return fields.join(',') || '*';
     }
 
+    /**
+     * 解析where参数
+     * @private
+     * @returns {[string, any[]]}
+     */
     _parseWhere() {
+        /** @type {Operator[]} */
         const logic = ['=', '<>', '!=', '>', '>=', '<', '<=', 'like', 'not like', 'in', 'not in', 'between', 'not between', 'is', 'is not', 'exp'];
+        /** @type {string[]} */
         const where = [];
+        /** @type {any[]} */
         const params = [];
         this._options.where.forEach(item => {
+            /** @type {Object.<string, any>} */
             const whereList = item[0];
             const whereLink = (item[1] && item[1].toLowerCase()) === 'or' ? 'or' : 'and';
             let whereChild = '';
@@ -792,6 +847,11 @@ class Db extends Context
         return [where.length ? 'where ' + where.join(' ') : '', params];
     }
 
+    /**
+     * 解析order参数
+     * @private
+     * @returns {string} 返回排序，类似order by id desc
+     */
     _parseOrder() {
         let order = '';
         Object.keys(this._options.order).forEach(key => {
@@ -802,9 +862,17 @@ class Db extends Context
         return order;
     }
 
+    /**
+     * 解析insert数据
+     * @private
+     * @returns {[string, any[]]}
+     */
     _parseInsertData() {
+        /** @type {string[]} */
         const fields = [];
+        /** @type {string[]} */
         const values = [];
+        /** @type {any[]} */
         const params = [];
         Object.keys(this._options.data).forEach(key => {
             const field = '`' + key.replace('.', '`.`') + '`';
@@ -816,8 +884,14 @@ class Db extends Context
         return [`(${fields.join(', ')}) values (${values.join(', ')})`, params];
     }
 
+    /**
+     * 解析update数据
+     * @private
+     * @returns {[string, any[]]}
+     */
     _parseUpdateData() {
         let data = '';
+        /** @type {any[]} */
         const params = [];
         Object.keys(this._options.data).forEach(key => {
             const field = '`' + key.replace('.', '`.`') + '`';
@@ -846,6 +920,11 @@ class Db extends Context
         return [data, params];
     }
 
+    /**
+     * 过滤数据
+     * @private
+     * @returns {Promise<Object.<string, any>>} 返回过滤后的数据
+     */
     async _filterData() {
         if(!this._options.allowField) {
             return this._options.data;
@@ -854,10 +933,10 @@ class Db extends Context
         let allowField = this._options.allowField;
         if(allowField === true) {
             const table_name = this._options.prefix + this._table;
-            if(!this._tableField[table_name]) {
-                this._tableField[table_name] = await this.tableField();
+            if(!this._tableField.get(table_name)) {
+                this._tableField.set(table_name, await this.tableField());
             }
-            allowField = this._tableField[table_name];
+            allowField = this._tableField.get(table_name) || [];
         }
 
         Object.keys(this._options.data).forEach(key => {
@@ -869,40 +948,79 @@ class Db extends Context
     }
 
     /**
-     * 获取sql缓存
-     * @param {string} [key]
-     * @returns {*}
+     * @type {Logger} Logger静态类
+     * @private
+     */
+    // @ts-ignore
+    __logger = null;
+
+    /**
+     * @type {Logger} Logger静态类
      */
-    getCache(key) {
-        return Db.cache.get(key);
+    get _$logger() {
+        if(this.__logger === null) {
+            if(this.$logger && this.$logger.__ISCLASS__) {
+                this.__logger = this.$logger;
+            } else if(this.$ && this.$.logger) {
+                this.__logger = this.$.logger;
+            } else {
+                this.__logger = require('./logger');
+            }
+        }
+        return this.__logger;
+    }
+
+    set _$logger(logger) {
+        this.setLogger(logger);
     }
 
     /**
-     * 设置sql缓存
-     * @param {string} key
+     * 设置日志器
+     * @param {Logger} logger
+     * @returns {this}
      */
-    setCache(key, data, cache_time) {
-        Db.cache.set(key, data, cache_time);
+    setLogger(logger) {
+        this.__logger = logger;
+        this._sql && this._sql.setLogger(logger);
+        return this;
     }
 
     /**
-     * 删除sql缓存
-     * @param {string} [key]
+     * 设置数据库缓存实例
+     * @type {PaginationInstance}
      */
-    deleteCache(key) {
-        Db.cache.delete(key);
+    // @ts-ignore
+    __pagination = null;
+
+    /**
+     * 获取分页器实例
+     * @returns {PaginationInstance}
+     */
+    get _$pagination() {
+        if(this.$pagination && this.$pagination.__ISCLASS__) {
+            this.__pagination = this.$pagination;
+        } else if(this.$ && this.$.pagination) {
+           this. __pagination = this.$.pagination;
+        } else {
+            this.__pagination = new (require('./pagination'))(this.ctx);
+        }
+        return this.__pagination;
     }
-}
 
-/**
- * 设置数据库缓存实例
- * @type {import('../types').Cache}
- */
-// @ts-ignore
-Db.cache = new (require('./cache'))();
-/**
- * 开启缓存自动清理
- */
-Db.cache.setIntervalTime(20 * 60 * 60);
+    /**
+     * 设置数据库缓存实例
+     * @type {Cache}
+     */
+    // @ts-ignore
+    static cache = new (require('./cache'))(new Map());
+
+    /**
+     * 数据库拥有一个独立的数据库缓存实例
+     * @returns {Cache}
+     */
+    get _$cache() {
+        return Db.cache;
+    }
+}
 
 module.exports = Db;