v0.9.0

CHANGELOG.md

@@ -0,0 +1,13 @@
+# v0.9.0 / 2024-02-06
+1. 支持jsdoc，完善vscode代码提示
+2. 系统核心库app由对象改为class，使用const app = new App() 
+3. 修复Logger类输出格式化bug，log函数参数调换
+4. 系统日志配置，默认输出['app', 'error']级别的日志
+5. 系统级屏蔽favicon.ico请求
+6. 系统loader支持并优先加载文件
+7. 依赖升级@koa/router v10.1.1 -> v12.0.1
+8. 依赖升级koa v2.13.4 -> v2.15.0
+9. node版本要求 >= v12.7.0
+
+# v0.8.8 / 2022-09-07
+1. 第一个tag

jj.js

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

jsconfig.json

@@ -0,0 +1,9 @@
+{
+    "compilerOptions": {
+        "module": "commonjs",
+        "target": "es6",
+        "resolveJsonModule": true,
+        "checkJs": true
+    },
+    "exclude": ["node_modules", "docs", "./lib/ctx.js"]
+  }

jsdoc.conf.js

@@ -0,0 +1,17 @@
+module.exports = {
+    source: {
+        include: ['./jj.js', './lib'],
+        includePattern: '.+\\.js(doc)?$',
+    },
+    plugins: [
+        "jsdoc-tsimport-plugin"
+    ],
+    templates: {
+        cleverLinks: true,
+        monospaceLinks: true,
+    },
+    opts: {
+        recurse: true,
+        destination: './docs',
+    }
+};

lib/app.js

@@ -1,48 +1,53 @@
 const path = require('path');
 const Koa = require('koa');
-const app = new Koa();
 const {app: cfg_app} = require('./config');
 const Logger = require('./logger');
 const Response = require('./response');
 const router = require('./router');
 const pjson = require('../package.json');
 
-app.run = (...args) => {
-    // exception
-    app.use(async (ctx, next) => {
-        ctx.APP_TIME = new Date();
-        ctx.APP_VERSION = pjson.version;
-
-        try {
-            await next();
-        } catch (err) {
-            Logger.error(...err.stack.split("\n"));
-            if(cfg_app.app_debug) {
-                new Response(ctx).exception(err);
-            } else {
-                ctx.response.status = err.statusCode || err.status || 500;
-                ctx.body = 'Internal Server Error';
+/**
+ * @extends Koa
+ */
+class App extends Koa
+{
+    /**
+     * @override
+     */
+    listen(...args) {
+        // exception
+        this.use(async (ctx, next) => {
+            ctx.APP_TIME = Date.now();
+            ctx.APP_VERSION = pjson.version;
+
+            try {
+                await next();
+            } catch (err) {
+                Logger.error(...err.stack.split("\n"));
+                if(cfg_app.app_debug) {
+                    new Response(ctx).exception(err);
+                } else {
+                    ctx.response.status = err.statusCode || err.status || 500;
+                    ctx.body = 'Internal Server Error';
+                }
             }
-        }
 
-        const ms = new Date() - ctx.APP_TIME;
-        Logger.http(`${ctx.method} ${ctx.status} ${ctx.url} - ${ms}ms`);
-    });
+            const ms = Date.now() - ctx.APP_TIME;
+            Logger.http(`${ctx.method} ${ctx.status} ${ctx.url} - ${ms}ms`);
+        });
 
-    // static
-    cfg_app.static_dir && app.use(require('koa-static')(path.join(cfg_app.base_dir, cfg_app.static_dir)));
+        // static
+        cfg_app.static_dir && this.use(require('koa-static')(path.join(cfg_app.base_dir, cfg_app.static_dir)));
 
-    // koa-body
-    cfg_app.koa_body && app.use(require('koa-body')(cfg_app.koa_body));
+        // koa-body
+        cfg_app.koa_body && this.use(require('koa-body')(cfg_app.koa_body));
 
-    // router
-    app.use(router.routes()).use(router.allowedMethods());
+        // router
+        this.use(router.routes()).use(router.allowedMethods());
 
-    // server
-    app.listen(...args);
-
-    // run once
-    delete app.run;
+        // server
+        return super.listen(...args);
+    }
 }
 
-module.exports = app;
+module.exports = App;

lib/cache.js

@@ -2,21 +2,34 @@ const {cache: cfg_cache} = require('./config');
 
 class Cache
 {
+    /**
+     * Creat a new `Cache` class
+     * @public
+     */
     constructor() {
         if(new.target) {
+            // @ts-ignore
             class ChildCache extends this.constructor {}
             ChildCache.cache = {};
             ChildCache.timer = null;
+            // @ts-ignore
             ChildCache.setIntervalTime(cfg_cache.clear_time);
             return ChildCache;
         }
     }
 
+    /**
+     * 获取缓存
+     * @public
+     * @static
+     * @param {string} [key] - 为空时，返回所有缓存
+     * @returns {*}
+     */
     static get(key) {
         if(key === undefined) {
             return this.cache;
         }
-        const now_time = Math.round(new Date() / 1000);
+        const now_time = Math.round(Date.now() / 1000);
         if(this.cache[key] && this.cache[key].time > now_time) {
             return this.cache[key].data;
         } else {
@@ -25,23 +38,45 @@ class Cache
         }
     }
 
+    /**
+     * 设置缓存
+     * @public
+     * @static
+     * @param {string} key - 缓存键
+     * @param {*} data - 缓存值
+     * @param {number} [cache_time] 单位秒，默认10年
+     */
     static set(key, data, cache_time) {
         cache_time || (cache_time = cfg_cache.cache_time || 60 * 60 * 24 * 365 * 10);
         const now_time = this.time();
         this.cache[key] = {data: data, time: cache_time + now_time};
     }
 
+    /**
+     * 删除或清理缓存
+     * @public
+     * @static
+     * @param {string} [key] - 为空时，清理所有缓存
+     */
     static delete(key) {
         if(key) {
             delete this.cache[key];
         } else {
+            // @ts-ignore
             this.cache = {};
         }
     }
 
+    /**
+     * 设置缓存自动清理
+     * @public
+     * @static
+     * @param {number} [time] - 清理周期，单位秒；为空或0，则关闭自动清理功能
+     */
     static setIntervalTime(time) {
         if(time) {
             this.timer && clearInterval(this.timer);
+            // @ts-ignore
             this.timer = setInterval(() => {
                 const now_time = this.time();
                 for(let key in this.cache) {
@@ -50,17 +85,35 @@ class Cache
             }, time * 1000);
         } else {
             this.timer && clearInterval(this.timer);
+            // @ts-ignore
             this.timer = null;
         }
     }
 
+    /**
+     * 获取当前时间戳
+     * @public
+     * @static
+     * @returns {number}
+     */
     static time() {
-        return Math.round(new Date() / 1000);
+        return Math.round(Date.now() / 1000);
     }
 }
 
+/**
+ * 缓存store
+ */
+// @ts-ignore
 Cache.cache = {};
+/**
+ * 缓存自动清理定时器
+ */
+// @ts-ignore
 Cache.timer = null;
+/**
+ * 开启缓存自动清理
+ */
 Cache.setIntervalTime(cfg_cache.clear_time);
 
 module.exports = Cache;

lib/config.js

@@ -40,8 +40,8 @@ const db = {
 }
 
 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) {}
+    log_level: ['app', 'error'], // [app, 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)));}
 }
 
 const cache = {
@@ -80,16 +80,20 @@ const tpl = {
 }
 
 const base_dir = path.dirname(module.parent.parent.parent.filename);
-const config = loader(path.join(base_dir, './config'));
+const base_config = loader(path.join(base_dir, './config'));
 
+/**
+ * @module config
+ * @type {import('./types').Config}
+ */
 module.exports = {
-    app: {...app, ...config.app, base_dir},
-    view: {...view, ...config.view},
-    db: {...db, ...config.db},
-    log: {...log, ...config.log},
-    cache: {...cache, ...config.cache},
-    page: {...page, ...config.page},
-    routes: config.routes,
-    cookie: config.cookie,
-    tpl: {...tpl, ...config.tpl}
+    app: {...app, ...base_config.app, base_dir},
+    view: {...view, ...base_config.view},
+    db: {...db, ...base_config.db},
+    log: {...log, ...base_config.log},
+    cache: {...cache, ...base_config.cache},
+    page: {...page, ...base_config.page},
+    routes: base_config.routes,
+    cookie: base_config.cookie,
+    tpl: {...tpl, ...base_config.tpl}
 };

lib/context.js

@@ -1,7 +1,15 @@
 const Ctx = require('./ctx');
 
+/**
+ * @extends Ctx
+ */
 class Context extends Ctx
 {
+    /**
+     * Initialize a new `Context`
+     * @public
+     * @param {import('./types').Context} ctx
+     */
     constructor(ctx) {
         super();
         this.ctx = ctx;

lib/controller.js

@@ -1,31 +1,57 @@
 const Middleware = require('./middleware');
 
+/**
+ * @extends Middleware
+ */
 class Controller extends Middleware
 {
-    // 赋值模版数据
+    /**
+     * 模版数据赋值
+     * @public
+     * @param {string} name
+     * @param {any} value 
+     * @returns {this}
+     */
     $assign(name, value) {
         this.$view.assign(name, value);
         return this;
     }
 
-    // 获取模版数据
+    /**
+     * 获取模版数据
+     * @public
+     * @param {string} [name]
+     * @returns {object}
+     */
     $data(name) {
         return this.$view.data(name);
     }
 
-    // 直接文件输出
+    /**
+     * 获取文件内容并输出
+     * @public
+     * @param {string} [template]
+     */
     async $load(template) {
         const content = await this.$view.load(template);
         this.$show(content);
     }
 
-    // 渲染内容输出
-    async $render(data) {
-        const content = await this.$view.render(data);
-        this.$show(content);
+    /**
+     * 渲染(解析数据)内容并输出
+     * @public
+     * @param {string} content
+     */
+    async $render(content) {
+        const html = await this.$view.render(content);
+        this.$show(html);
     }
 
-    // 渲染文件输出
+    /**
+     * 渲染(解析数据)文件并输出
+     * @public
+     * @param {string} [template]
+     */
     async $fetch(template) {
         const content = await this.$view.fetch(template);
         this.$show(content);