jj.js 0.9.0 → 0.11.0

package/CHANGELOG.md

@@ -1,3 +1,13 @@
+# v0.11.0 / 2024-02-26
+1. 基于`AsyncLocalStorage`重构核心类
+2. 空控制器和空方法名改为`_empty`
+
+# 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

@@ -6,15 +6,15 @@ A super simple lightweight NodeJS MVC framework（一个超级简单轻量的Nod
 
 ## 项目介绍
 
-本框架依赖koa2、@koa/router、art-template、mysql，基于proxy实现了代码自动加载及懒加载技术，最低运行依赖仅仅为koa和koa-router，非常轻量。
+无论什么语言什么框架的程序，类库的使用都离不开require、import、include等导入模块，不用时，还得删除。而本框架基于proxy实现了类库自动加载、懒加载和Class自动实例化及单例化技术，所有的类库，想用直接调用，系统会自动导入。
 
 ### 项目特性
 
-1. 系统架构模仿Thinkphp5，很容易上手
-2. 系统类库、用户类库都支持自动加载、懒加载、自动生成单实例
+1. 系统架构为经典的MVC模式，模仿Thinkphp5，很容易上手
+2. 系统类库、用户类库都支持自动加载、懒加载、Class自动生成单实例
 3. 支持应用级、路由级、控制器级三级中间件，方便插件及二次开发
 4. 支持单应用和多应用两种运行模式
-5. jsdoc支持，完善vscode代码提示
+5. 基于jsdoc，提供完整的代码提示，自动生成应用端types类型文件
 
 ### 项目地址
 
@@ -230,17 +230,6 @@ const app = {
 }
 module.exports = app;
 ```
-- 模板配置`./config/view.js`：
-```javascript
-const view = {
-    view_folder: 'view', // 模板目录名
-    view_depr: '/', // 模版文件名分割符，'/'代表二级目录
-    view_ext: '.htm', // 模版文件后缀
-    view_engine: 'art-template', // 默认模版引擎，字符串或引擎类，咱不支持更换
-    view_filter: {}, // 模版函数，配置注入模板的函数，默认会自动注入url函数
-}
-module.exports = view;
-```
 - 数据库配置`./config/db.js`：可以配置多个，方便程序里切换使用。
 ```javascript
 const db = {
@@ -257,67 +246,7 @@ const db = {
 }
 module.exports = db;
 ```
-- 日志配置`./config/log.js`：log_handle可以自定义日志handle
-```javascript
-const log = {
-    log_level: [], // [error, warning, info, debug, http, sql]
-    log_handle: function(msg, level) {console.log(`[${format('YY-mm-dd HH:ii:ss')}] [${level}] ${typeof msg == 'String' ? msg : JSON.stringify(msg)}`);} //function(msg, level) {}
-}
-module.exports = log;
-```
-- 缓存配置`./config/cache.js`：
-```javascript
-const cache = {
-    cache_time: 60 * 60 * 24, // 默认缓存时间（1天），为空或false则为10年
-    clear_time: undefined // (undefined: 一天清理一次, 0: 关闭自动清理, >0: 为自动清理周期)
-}
-module.exports = cache;
-```
-- 分页配置`./config/page.js`：
-```javascript
-const page = {
-    page_key    : 'page', // 默认分页标识
-    key_origin    : 'query', // query 或 params
-    page_size   : 10, // 默认分页大小
-    page_length : 5, // 默认分页长度，数字页码链接数量
-
-    //网址规则，可为空，可为路由名字，可用参数：页码${page}
-    //样例：':name'
-    //样例：'/list_${page}.html'
-    url_page    : '',
-    url_index   : '',
-
-    //模块样式 可用参数：网址${url}，页码${page}，总数${total_page}，总页数${total_page}
-    index_tpl   : '<li class="index"><a href="${url}">首页</a></li>',
-    end_tpl     : '<li class="end"><a href="${url}">末页</a></li>',
-    prev_tpl    : '<li class="prev"><a href="${url}">上一页</a></li>',
-    next_tpl    : '<li class="next"><a href="${url}">下一页</a></li>',
-    list_tpl    : '<li><a href="${url}">${page}</a></li>',
-    active_tpl  : '<li class="active"><a href="${url}">${page}</a></li>',
-    info_tpl    : '<span class="info">共${total_page}页，${total}条记录</span>',
-
-    //渲染模版
-    template   : '<div class="pagination"><ul class="page">${index}${prev}${list}${next}${end}</ul>${info}</div>'
-}
-module.exports = page;
-```
-- 跳转模板配置`./config/tpl.js`：模板可以配置为自定义的
-```javascript
-const tpl = {
-    jump: require('./tpl/jump'), // 跳转模板
-    exception: require('./tpl/exception') //  异常页面模板
-}
-module.exports = tpl;
-```
-- 自定义配置`./config/self.js`：自定义配置同样可以直接通过`this.$config.self`使用。
-```javascript
-const self = {
-    option1: ''
-    option2: ''
-    ...
-}
-module.exports = self;
-```
+
 - 路由配置`./config/routes.js`：
 路由功能基于`@koa/router`开发，关于url匹配规则可以参考官方文档：[文档地址](https://www.npmjs.com/package/@koa/router)
 
@@ -338,26 +267,22 @@ module.exports = routes;
 ```
 > 注意：本路由配置示例前两条规则为常规用法，后面的非常规用法，不建议使用。如果是单应用模式，可以去掉path参数里的app。
 
-### 应用入口文件
-
-应用入口文件放在项目的根目录，名字可以任意改。
-
-示例文件 `./server.js`
+- 自定义配置`./config/self.js`：自定义配置同样可以直接通过`this.$config.self`使用。
 ```javascript
-const {app, Logger} = require('jj.js');
-
-app.run(3000, '127.0.0.1', function(err){
-    !err && Logger.info('http server is ready on 3000');
-});
+const self = {
+    option1: ''
+    option2: ''
+    ...
+}
+module.exports = self;
 ```
-其中`app`是一个koa实例，可以使用`use`方法添加应用级中间件，使用方法参考koa文档。`app`的`run`方法经过了封装，仅允许调用一次。其中`Logger`因为是一个静态类，所以可以直接调用`info`方法输出日志。
+- 其他配置项，请参考系统配置文件`jj.js/lib/config.js`
+
+### 编码命名规范
 
-## 总结
+类名使用大驼峰，方法名使用小驼峰，私有方法使用下划线前缀。
+控制器文件名使用小写下划线。
 
-通过以上文档，可以看到：
-1. jj.js是一个轻量的mvc框架，几乎所有文件不使用就不会调用。
-2. 同时也是个功能强大的框架，支持应用级、路由级、控制器级三级中间件。
-3. 类库自动加载，只要是继承自`Context`的类库，都可以在方法内使用包含`$`前缀的属性自动加载其他资源。
 
 ## 应用案例
 

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, config}
  * @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

@@ -4,6 +4,7 @@ const {app: cfg_app} = require('./config');
 const Logger = require('./logger');
 const Response = require('./response');
 const router = require('./router');
+const storage = require('./storage');
 const pjson = require('../package.json');
 
 /**
@@ -13,8 +14,16 @@ class App extends Koa
 {
     /**
      * @override
+     * @param {...any} args - listen(port, ip, callback(err){})
      */
     listen(...args) {
+        // storage
+        this.use(async (ctx, next) => {
+            await storage.run({}, async() => {
+                await next();
+            });
+        });
+
         // exception
         this.use(async (ctx, next) => {
             ctx.APP_TIME = Date.now();
@@ -45,6 +54,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

@@ -1,57 +1,55 @@
 // @ts-nocheck
-const loader = require('./loader');
+const storage = require('./storage');
 
 /**
- * @typedef {typeof import('./types')} Ctx
- */
-
-/**
- * @class Ctx
- * @type {Ctx}
+ * 开发jj.js库本身时，可以设置为import('../types')
+ * @type {typeof import('../../../types')}
  */
 const Ctx = new Proxy(class {}, {
         construct() {
             return new Proxy({__proto__: arguments[2].prototype}, {
-                get: (target, prop, receiver) => {
-                    if(prop in target || typeof prop == 'symbol' || prop == 'inspect') {
-                        return Reflect.get(target, prop, receiver);
+                get: (target, $prop, receiver) => {
+                    if($prop in target || typeof $prop == 'symbol' || $prop == 'inspect') {
+                        return Reflect.get(target, $prop, receiver);
                     }
-                    if(prop == '$' || prop == '_') {
-                        return target.ctx && target.ctx[prop]
-                            || prop == '$' && (target.$ || (target.$ = loader('../'))) && target.$
-                            || undefined;
+
+                    const store = storage.getStore();
+                    const $ = store.$;
+                    const _ = store._;
+                    if($prop == '$' || $prop == '_') {
+                        return store[$prop];
                     }
-                    if(prop.slice(0, 1) != '$') {
+                    if($prop.slice(0, 1) != '$') {
                         return undefined;
                     }
-                    const pp = prop.slice(1);
-                    const ctx = target.ctx;
-                    if(ctx && ctx._) {
-                        const _ = ctx._;
-                        const APP = ctx.APP;
-                        const COMMON = _.config.app.common_app;
-                        if(_[APP][prop] === undefined) {
-                            if(_[APP][pp] && _[COMMON] && _[COMMON][pp]) {
-                                _[APP][prop] = new Proxy({}, {
-                                    get: (...args) => {
-                                        return _[APP][pp][args[1]] || _[COMMON][pp][args[1]];
-                                    }
-                                });
-                            } else if(_[APP][pp]) {
-                                _[APP][prop] = _[APP][pp];
-                            } else if(_[COMMON] && _[COMMON][pp]) {
-                                _[APP][prop] = _[COMMON][pp];
-                            } else {
-                                _[APP][prop] = null;
-                            }
-                            if(~['view', 'response'].indexOf(pp) && _[APP][prop] && _[APP][prop].__node && !_[APP][prop].__node.isClass && ctx.$ && ctx.$[pp]) {
-                                _[APP][prop] = ctx.$[pp];
-                            }
+
+                    const prop = $prop.slice(1);
+                    const APP = store.APP;
+                    const COMMON = store.COMMON;
+
+                    // 缓存
+                    if(_[APP][$prop] === undefined) {
+                        if(_[APP][prop] && _[COMMON] && _[COMMON][prop]) {
+                            _[APP][$prop] = new Proxy({}, {
+                                get: (...args) => {
+                                    return _[APP][prop][args[1]] || _[COMMON][prop][args[1]];
+                                }
+                            });
+                        } else if(_[APP][prop]) {
+                            _[APP][$prop] = _[APP][prop];
+                        } else if(_[COMMON] && _[COMMON][prop]) {
+                            _[APP][$prop] = _[COMMON][prop];
+                        } else {
+                            _[APP][$prop] = null;
+                        }
+                        // lib调用，防止覆盖
+                        if(['logger', 'pagination', 'response', 'url', 'view'].includes(prop) && _[APP][$prop] && _[APP][$prop].__node && !_[APP][$prop].__node.isClass && $[prop]) {
+                            _[APP][$prop] = $[prop];
                         }
-                        return _[APP][prop] || _[pp] || (ctx.$ && ctx.$[pp]) || undefined;
-                    } else {
-                        return (target.$ || (target.$ = loader('../'))) && target.$[pp];
                     }
+
+                    // 屏蔽部分lib
+                    return _[APP][$prop] || _[prop] || (!['app', 'loader', 'router', 'run', 'storage', 'types'].includes(prop) && $[prop]) || undefined;
                 }
             });
         }

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) {
@@ -699,14 +699,10 @@ class Db extends Context
     async pagination({page, page_size, pagination} = {}) {
         !page && (page = this._options.page.page);
         !page_size && (page_size = this._options.page.pageSize);
-        if(!pagination) {
-            pagination = this.$pagination.__node && this.$pagination.__node.isClass ? this.$pagination : this.$.pagination;
-        }
+        !pagination && (pagination = this.$pagination);
 
         const options = {...this._options}; // 暂存options
-        // @ts-ignore
         const total = await this.count();
-        // @ts-ignore
         pagination.total(total);
 
         // @ts-ignore
@@ -727,7 +723,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 +749,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 +784,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 +795,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 +806,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 +816,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 +845,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 +1058,7 @@ class Db extends Context
 
     /**
      * 获取sql缓存
-     * @param {string} key
+     * @param {string} [key]
      * @returns {*}
      */
     getCache(key) {
@@ -1079,7 +1075,7 @@ class Db extends Context
 
     /**
      * 删除sql缓存
-     * @param {string} key
+     * @param {string} [key]
      */
     deleteCache(key) {
         Db.cache.delete(key);
@@ -1088,7 +1084,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);