jj.js 0.9.0 → 0.10.0

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+# v0.10.0 / 2024-02-26
+1. 类型文件位置调整及优化
+2. 自动生成应用端类型文件（开启app_debug，并且根目录下存在jsconfig.json文件）
+3. utils工具fs库方法优化，保留部分，其他方法建议使用fs.promises库
+4. 系统级别调整，app类改为system，默认输出['system', 'error']级别的日志
+
 # v0.9.0 / 2024-02-06
 1. 支持jsdoc，完善vscode代码提示
 2. 系统核心库app由对象改为class，使用const app = new App() 

package/README.md

@@ -14,7 +14,7 @@ A super simple lightweight NodeJS MVC framework（一个超级简单轻量的Nod
 2. 系统类库、用户类库都支持自动加载、懒加载、自动生成单实例
 3. 支持应用级、路由级、控制器级三级中间件，方便插件及二次开发
 4. 支持单应用和多应用两种运行模式
-5. jsdoc支持，完善vscode代码提示
+5. 基于jsdoc，提供完整的代码提示。支持自动生成应用端jsdoc文件
 
 ### 项目地址
 

package/jj.js

@@ -1,12 +1,12 @@
 /**
  * jj.js核心库<br/>
- * {App, Controller, Db, Model, Pagination, View, Logger, Cookie, Response, Upload, Url, Middleware, Cache, Context, View, utils}
+ * {App, Cache, Context, Controller, Cookie, Ctx, Db, Logger, Middleware, Model, Pagination, Response, Upload, Url, View, utils}
  * @module core
- * @type {import('./lib/types').Core}
+ * @type {import('./types').Core}
  */
 module.exports = new Proxy({}, {
     get: (target, prop) => {
-        if(prop in target || typeof prop == 'symbol' || prop == 'inspect'){
+        if(prop in target || typeof prop == 'symbol' || ['inspect', 'router', 'run', 'types'].includes(prop)) {
             return target[prop];
         }
         prop = prop.toLowerCase();

package/lib/app.js

@@ -13,6 +13,7 @@ class App extends Koa
 {
     /**
      * @override
+     * @param {...any} args - listen(port, ip, callback(err){})
      */
     listen(...args) {
         // exception
@@ -45,6 +46,13 @@ class App extends Koa
         // router
         this.use(router.routes()).use(router.allowedMethods());
 
+        // types
+        if(cfg_app.app_debug) {
+            const {isFileSync} = require('./utils/fs');
+            const jsconfigFile = path.join(cfg_app.base_dir, 'jsconfig.json');
+            isFileSync(jsconfigFile) && require('./types')();
+        }
+
         // server
         return super.listen(...args);
     }

package/lib/config.js

@@ -13,9 +13,9 @@ const app = {
     common_app: 'common', // 公共应用，存放公共模型及逻辑
     controller_folder: 'controller', //控制器目录名
 
-    static_dir: '', // 静态文件目录，相对于应用根目录，为空或false时，关闭静态访问
+    static_dir: '', // 静态文件目录，相对于应用根目录，为空时，关闭静态访问
 
-    koa_body: null // koa-body配置参数，为''、null、false时，关闭koa-body
+    koa_body: null // koa-body配置参数，为null或空时，关闭koa-body
 }
 
 const view = {
@@ -40,7 +40,7 @@ const db = {
 }
 
 const log = {
-    log_level: ['app', 'error'], // [app, error, warning, info, debug, http, sql]
+    log_level: ['system', 'error'], // [system, error, warning, info, debug, http, sql]
     log_handle: function(level, ...args) {console.log(`[${format('YY-mm-dd HH:ii:ss')}] [${level}]`, ...args.map(msg => typeof msg == 'string' ? msg : JSON.stringify(msg)));}
 }
 
@@ -84,7 +84,7 @@ const base_config = loader(path.join(base_dir, './config'));
 
 /**
  * @module config
- * @type {import('./types').Config}
+ * @type {import('../types').Config}
  */
 module.exports = {
     app: {...app, ...base_config.app, base_dir},

package/lib/context.js

@@ -1,3 +1,7 @@
+/**
+ * 开发jj.js库本身时，可以设置为import('../types')
+ * @type {typeof import('../../../types')}
+ */
 const Ctx = require('./ctx');
 
 /**
@@ -8,7 +12,7 @@ class Context extends Ctx
     /**
      * Initialize a new `Context`
      * @public
-     * @param {import('./types').Context} ctx
+     * @param {import('../types').KoaCtx} [ctx]
      */
     constructor(ctx) {
         super();

package/lib/ctx.js

@@ -2,12 +2,8 @@
 const loader = require('./loader');
 
 /**
- * @typedef {typeof import('./types')} Ctx
- */
-
-/**
- * @class Ctx
- * @type {Ctx}
+ * 开发jj.js库本身时，可以设置为import('../types')
+ * @type {typeof import('../../../types')}
  */
 const Ctx = new Proxy(class {}, {
         construct() {

package/lib/db.js

@@ -3,17 +3,17 @@ const md5 = require('./utils/md5');
 const Context = require('./context');
 
 /**
- * @typedef {import('./types').Pagination} Pagination
- * @typedef {import('./types').PaginationInstance} PaginationInstance
- * @typedef {import('./types').Pool} Pool
- * @typedef {import('./types').PoolConfig} PoolConfig
- * @typedef {import('./types').PoolConnection} PoolConnection
- * @typedef {import('./types').QueryOptions} QueryOptions
- * @typedef {import('./types').OkPacket} OkPacket
- * @typedef {import('./types').RowData} RowData
- * @typedef {import('./types').ListData} ListData
- * @typedef {import('./types').FieldInfo} FieldInfo
- * @typedef {import('./types').PoolMap} PoolMap
+ * @typedef {import('../types').Pagination} Pagination
+ * @typedef {import('../types').PaginationInstance} PaginationInstance
+ * @typedef {import('../types').Pool} Pool
+ * @typedef {import('../types').PoolConfig} PoolConfig
+ * @typedef {import('../types').PoolConnection} PoolConnection
+ * @typedef {import('../types').QueryOptions} QueryOptions
+ * @typedef {import('../types').OkPacket} OkPacket
+ * @typedef {import('../types').RowData} RowData
+ * @typedef {import('../types').ListData} ListData
+ * @typedef {import('../types').FieldInfo} FieldInfo
+ * @typedef {import('../types').PoolMap} PoolMap
  */
 
 //连接池
@@ -34,7 +34,7 @@ class Db extends Context
     /**
      * Initialize a new `Db`
      * @public
-     * @param {(import('./types').Context|object)} ctx
+     * @param {import('../types').KoaCtx} [ctx]
      * @param {(string|PoolConfig)} [options] - 数据库配置标识或连接参数
      */
     constructor(ctx, options) {
@@ -531,7 +531,7 @@ class Db extends Context
      * 获取多条数据
      * @public
      * @param {object} condition - 查询条件
-     * @returns {Promise<(string|ListData)>}
+     * @returns {Promise<ListData>}
      */
     async select(condition) {
         condition && (this._options.where = [], this._options.where.push([condition]));
@@ -577,7 +577,7 @@ class Db extends Context
      * 获取一条数据
      * @public
      * @param {object} condition - 查询条件
-     * @returns {Promise<(RowData|null)>}
+     * @returns {Promise<?RowData>}
      */
     async find(condition) {
         condition && (this._options.where = [], this._options.where.push([condition])); 
@@ -595,7 +595,7 @@ class Db extends Context
      * 获取一个字段值
      * @public
      * @param {string} field - 字段
-     * @returns {Promise<(string|number|null)>}
+     * @returns {Promise<*>}
      */
     async value(field) {
         this._options.field = [];
@@ -613,7 +613,7 @@ class Db extends Context
      * 获取总数
      * @public
      * @param {string} [field] - 字段
-     * @returns {Promise<(string|number|0)>}
+     * @returns {Promise<number>}
      */
     async count(field='*') {
         return await this.value(`count(${field})`) || 0;
@@ -623,7 +623,7 @@ class Db extends Context
      * 获取字段最大值
      * @public
      * @param {string} field - 字段
-     * @returns {Promise<(string|number|0)>}
+     * @returns {Promise<number>}
      */
     async max(field) {
         return await this.value(`max(${field})`);
@@ -633,7 +633,7 @@ class Db extends Context
      * 获取字段最小值
      * @public
      * @param {string} field - 字段
-     * @returns {Promise<(string|number|0)>}
+     * @returns {Promise<number>}
      */
     async min(field) {
         return await this.value(`min(${field})`);
@@ -643,7 +643,7 @@ class Db extends Context
      * 获取字段平均值
      * @public
      * @param {string} field - 字段
-     * @returns {Promise<(string|number|0)>}
+     * @returns {Promise<number>}
      */
     async avg(field) {
         return await this.value(`avg(${field})`);
@@ -653,7 +653,7 @@ class Db extends Context
      * 获取字段总和
      * @public
      * @param {string} field - 字段
-     * @returns {Promise<(string|number|0)>}
+     * @returns {Promise<number>}
      */
     async sum(field) {
         return await this.value(`sum(${field})`);
@@ -664,7 +664,7 @@ class Db extends Context
      * @public
      * @param {string} field - 数据字段
      * @param {string} [key] - key字段，不设置返回数据数组，设置则返回{key: field}对象数组
-     * @returns {Promise<(string|ListData|object)>}
+     * @returns {Promise<(ListData|object)>}
      */
     async column(field, key) {
         this._options.field = [];
@@ -675,7 +675,7 @@ class Db extends Context
             return await this.select();
         }
 
-        const rows = /** @type {ListData} */(await this.select());
+        const rows = await this.select();
         const result = key ? {} : [];
         rows.forEach(row => {
             if(key) {
@@ -704,9 +704,7 @@ class Db extends Context
         }
 
         const options = {...this._options}; // 暂存options
-        // @ts-ignore
         const total = await this.count();
-        // @ts-ignore
         pagination.total(total);
 
         // @ts-ignore
@@ -727,7 +725,7 @@ class Db extends Context
      * 插入一条数据
      * @public
      * @param {object} data - 待插入数据
-     * @returns {Promise<(string|OkPacket)>}
+     * @returns {Promise<OkPacket>}
      */
     async insert(data) {
         data && (this._options.data = data);
@@ -753,7 +751,7 @@ class Db extends Context
      * @public
      * @param {object} data - 更新数据
      * @param {object} condition - 更新条件
-     * @returns {Promise<(string|OkPacket)>}
+     * @returns {Promise<OkPacket>}
      */
     async update(data, condition) {
         data && (this._options.data = data);
@@ -788,7 +786,7 @@ class Db extends Context
      * @public
      * @param {string} field - 字段
      * @param {number} [step=1] - 增加值，默认1
-     * @returns {Promise<(string|OkPacket)>}
+     * @returns {Promise<OkPacket>}
      */
     async inc(field, step) {
         return await this.update({[field]: ['inc', step]});
@@ -799,7 +797,7 @@ class Db extends Context
      * @public
      * @param {string} field - 字段
      * @param {number} [step=1] - 减少值，默认1
-     * @returns {Promise<(string|OkPacket)>}
+     * @returns {Promise<OkPacket>}
      */
     async dec(field, step) {
         return await this.update({[field]: ['dec', step]});
@@ -810,7 +808,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]});
@@ -820,7 +818,7 @@ class Db extends Context
      * 删除数据
      * @public
      * @param {object} condition - 山粗条件
-     * @returns {Promise<(string|OkPacket)>}
+     * @returns {Promise<OkPacket>}
      */
     async delete(condition) {
         condition && (this._options.where = [], this._options.where.push([condition]));
@@ -849,7 +847,7 @@ 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;
@@ -1062,7 +1060,7 @@ class Db extends Context
 
     /**
      * 获取sql缓存
-     * @param {string} key
+     * @param {string} [key]
      * @returns {*}
      */
     getCache(key) {
@@ -1079,7 +1077,7 @@ class Db extends Context
 
     /**
      * 删除sql缓存
-     * @param {string} key
+     * @param {string} [key]
      */
     deleteCache(key) {
         Db.cache.delete(key);
@@ -1088,7 +1086,7 @@ class Db extends Context
 
 /**
  * 设置数据库缓存实例
- * @type {typeof import('./cache')}
+ * @type {import('../types').Cache}
  */
 // @ts-ignore
 Db.cache = new (require('./cache'))();

package/lib/logger.js

@@ -1,7 +1,7 @@
 const {app: cfg_app, log: cfg_log} = require('./config');
 
 /**
- * @typedef {import('./types').LogHandle} LogHandle
+ * @typedef {import('../types').LogHandle} LogHandle
  */
 
 class Logger
@@ -22,6 +22,16 @@ class Logger
         }
     }
 
+    /**
+     * 输出system日志
+     * @public
+     * @static
+     * @param  {...any} args
+     */
+    static system(...args) {
+        this.log('system', ...args);
+    }
+
     /**
      * 输出error日志
      * @public

package/lib/middleware.js

@@ -8,8 +8,8 @@ class Middleware extends Context
     /**
      * Initialize a new `Middleware`
      * @public
-     * @param {import('./types').Context} ctx
-     * @param {import('./types').Middleware} [next]
+     * @param {import('../types').KoaCtx} ctx
+     * @param {import('../types').AsyncNext} [next]
      */
     constructor(ctx, next) {
         super(ctx);

package/lib/model.js

@@ -2,9 +2,9 @@ const Context = require('./context');
 const {toLine} = require('./utils/str');
 
 /**
- * @typedef {import('./types').OkPacket} OkPacket
- * @typedef {import('./types').RowData} RowData
- * @typedef {import('./types').ListData} ListData
+ * @typedef {import('../types').OkPacket} OkPacket
+ * @typedef {import('../types').RowData} RowData
+ * @typedef {import('../types').ListData} ListData
  */
 
 /**
@@ -15,7 +15,7 @@ class Model extends Context
     /**
      * Initialize a new `Model`
      * @public
-     * @param {import('./types').Context} ctx
+     * @param {import('../types').KoaCtx} ctx
      */
     constructor(ctx) {
         super(ctx);
@@ -32,7 +32,6 @@ class Model extends Context
      * @returns {Promise<OkPacket>}
      */
     async add(data) {
-        // @ts-ignore
         return await this.db.allowField().insert(data);
     }
 
@@ -49,7 +48,6 @@ class Model extends Context
                 condition[this.pk] = data[this.pk];
                 delete data[this.pk];
             }
-            // @ts-ignore
             return await this.db.allowField().update(data, condition);
         }
 
@@ -64,7 +62,6 @@ class Model extends Context
      * @returns {Promise<OkPacket>}
      */
     async del(condition) {
-        // @ts-ignore
         return await this.db.delete(condition);
     }
 
@@ -85,13 +82,12 @@ class Model extends Context
      * @returns {Promise<(ListData)>}
      */
     async all(condition) {
-        // @ts-ignore
         return await this.db.select(condition);
     }
 
     /**
      * 数据库实例
-     * @type {typeof import('./db').prototype}
+     * @type {import('../types').DbInstance}
      */
     get db() {
         if(!this._db){

package/lib/pagination.js

@@ -9,7 +9,7 @@ class Pagination extends Context
     /**
      * Initialize a new `Pagination`
      * @public
-     * @param {import('./types').Context} ctx
+     * @param {import('../types').KoaCtx} ctx
      */
     constructor(ctx) {
         super(ctx);
@@ -23,12 +23,12 @@ class Pagination extends Context
     /**
      * 分页配置
      * @public
-     * @param {import('./types').PageConfig} [options]
+     * @param {import('../types').PageConfig} [options]
      * @returns {this}
      */
     init(options) {
         /**
-         * @type {import('./types').PageConfig}
+         * @type {import('../types').PageConfig}
          * @private
          */
         this.options = {...cfg_page, ...options};

package/lib/response.js

@@ -10,7 +10,7 @@ class Response extends Context
     /**
      * Initialize a new `Response`
      * @public
-     * @param {import('./types').Context} ctx
+     * @param {import('../types').KoaCtx} ctx
      */
     constructor(ctx) {
         super(ctx);

package/lib/run.js

@@ -1,6 +1,6 @@
 const path = require('path');
 const loader = require('./loader');
-const {readFile} = require('./utils/fs');
+const {readFile} = require('fs').promises;
 const {toHump} = require('./utils/str');
 const {app: cfg_app, view: cfg_view, db, page, log, cache, cookie, tpl} = require('./config');
 const compose = require('koa-compose');
@@ -8,11 +8,11 @@ const Logger = require('./logger');
 
 async function run(ctx, next, control_type=cfg_app.controller_folder) {
     if(cfg_app.app_debug) {
-        Logger.debug(ctx.request);
-        Logger.debug(`Router(${control_type}): {APP: '${ctx.APP}', CONTROLLER: '${ctx.CONTROLLER}', ACTION: '${ctx.ACTION}'}`);
-        Object.keys(ctx.params).length && Logger.debug({Params: ctx.params});
-        Object.keys(ctx.query).length && Logger.debug({Get: ctx.query});
-        Object.keys(ctx.request.body || {}).length && Logger.debug({Post: ctx.request.body});
+        Logger.http('Request:', ctx.request);
+        Logger.http(`Router(${control_type}): {APP: '${ctx.APP}', CONTROLLER: '${ctx.CONTROLLER}', ACTION: '${ctx.ACTION}'}`);
+        Object.keys(ctx.params).length && Logger.http('Params:', ctx.params);
+        Object.keys(ctx.query).length && Logger.http('Get:', ctx.query);
+        Object.keys(ctx.request.body || {}).length && Logger.http('Post:', ctx.request.body);
     }
     
     // 设置根加载器

package/lib/tpl/types.js

@@ -0,0 +1,22 @@
+module.exports = `/**
+* @type {typeof import('jj.js/types')}
+*/
+const JJCtx = require('jj.js').Ctx;
+
+/**
+ * @typedef {import('jj.js/types').Config} JJConfig
+ */
+
+__TYPES__
+
+/**
+ * @class Ctx
+ */
+class Ctx extends JJCtx {
+__PROPERTY__
+}
+
+/**
+ * @module types
+ */
+module.exports = Ctx;`;