jj.js 0.8.8 → 0.10.0

package/jj.js

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

package/jsconfig.json

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

package/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',
+    }
+};

package/lib/app.js

@@ -1,48 +1,61 @@
-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';
-            }
-        }
-
-        const ms = new Date() - 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)));
-
-    // koa-body
-    cfg_app.koa_body && app.use(require('koa-body')(cfg_app.koa_body));
-
-    // router
-    app.use(router.routes()).use(router.allowedMethods());
-
-    // server
-    app.listen(...args);
-
-    // run once
-    delete app.run;
-}
-
-module.exports = app;
+const path = require('path');
+const Koa = require('koa');
+const {app: cfg_app} = require('./config');
+const Logger = require('./logger');
+const Response = require('./response');
+const router = require('./router');
+const pjson = require('../package.json');
+
+/**
+ * @extends Koa
+ */
+class App extends Koa
+{
+    /**
+     * @override
+     * @param {...any} args - listen(port, ip, callback(err){})
+     */
+    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 = Date.now() - ctx.APP_TIME;
+            Logger.http(`${ctx.method} ${ctx.status} ${ctx.url} - ${ms}ms`);
+        });
+
+        // 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 && this.use(require('koa-body')(cfg_app.koa_body));
+
+        // 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);
+    }
+}
+
+module.exports = App;

package/lib/cache.js

@@ -1,66 +1,119 @@
-const {cache: cfg_cache} = require('./config');
-
-class Cache
-{
-    constructor() {
-        if(new.target) {
-            class ChildCache extends this.constructor {}
-            ChildCache.cache = {};
-            ChildCache.timer = null;
-            ChildCache.setIntervalTime(cfg_cache.clear_time);
-            return ChildCache;
-        }
-    }
-
-    static get(key) {
-        if(key === undefined) {
-            return this.cache;
-        }
-        const now_time = Math.round(new Date() / 1000);
-        if(this.cache[key] && this.cache[key].time > now_time) {
-            return this.cache[key].data;
-        } else {
-            this.delete(key);
-            return undefined;
-        }
-    }
-
-    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};
-    }
-
-    static delete(key) {
-        if(key) {
-            delete this.cache[key];
-        } else {
-            this.cache = {};
-        }
-    }
-
-    static setIntervalTime(time) {
-        if(time) {
-            this.timer && clearInterval(this.timer);
-            this.timer = setInterval(() => {
-                const now_time = this.time();
-                for(let key in this.cache) {
-                    this.cache[key].time < now_time && this.delete(key);
-                }
-            }, time * 1000);
-        } else {
-            this.timer && clearInterval(this.timer);
-            this.timer = null;
-        }
-    }
-
-    static time() {
-        return Math.round(new Date() / 1000);
-    }
-}
-
-Cache.cache = {};
-Cache.timer = null;
-Cache.setIntervalTime(cfg_cache.clear_time);
-
+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(Date.now() / 1000);
+        if(this.cache[key] && this.cache[key].time > now_time) {
+            return this.cache[key].data;
+        } else {
+            this.delete(key);
+            return undefined;
+        }
+    }
+
+    /**
+     * 设置缓存
+     * @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) {
+                    this.cache[key].time < now_time && this.delete(key);
+                }
+            }, time * 1000);
+        } else {
+            this.timer && clearInterval(this.timer);
+            // @ts-ignore
+            this.timer = null;
+        }
+    }
+
+    /**
+     * 获取当前时间戳
+     * @public
+     * @static
+     * @returns {number}
+     */
+    static time() {
+        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;

package/lib/config.js

@@ -1,95 +1,99 @@
-const path = require('path');
-const loader = require('./loader');
-const {format} = require('./utils/date');
-
-const app = {
-    app_debug: true, // 调试模式
-    app_multi: false, // 是否开启多应用
-
-    default_app: 'app', // 默认应用
-    default_controller: 'index', //默认控制器
-    default_action: 'index', // 默认方法
-
-    common_app: 'common', // 公共应用，存放公共模型及逻辑
-    controller_folder: 'controller', //控制器目录名
-
-    static_dir: '', // 静态文件目录，相对于应用根目录，为空或false时，关闭静态访问
-
-    koa_body: null // koa-body配置参数，为''、null、false时，关闭koa-body
-}
-
-const view = {
-    view_folder: 'view', // 模板目录名
-    view_depr: '/', // 模版文件名分割符，'/'代表二级目录
-    view_ext: '.htm', // 模版后缀
-    view_engine: 'art-template', // 默认模版引擎，字符串或引擎类
-    view_filter: {}, // 模版函数
-}
-
-const db = {
-    default: {
-        type      : 'mysql', // 数据库类型
-        host      : '127.0.0.1', // 服务器地址
-        database  : 'jj', // 数据库名
-        user      : 'root', // 数据库用户名
-        password  : '', // 数据库密码
-        port      : '', // 数据库连接端口
-        charset   : 'utf8', // 数据库编码默认采用utf8
-        prefix    : 'jj_' // 数据库表前缀
-    }
-}
-
-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) {}
-}
-
-const cache = {
-    cache_time: 60 * 60 * 24, // 默认缓存时间（1天），为空或false则为10年
-    clear_time: undefined // (undefined: 清理一次, 0: 关闭自动清理, >0: 为自动清理周期)
-}
-
-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>'
-}
-
-const tpl = {
-    jump: require('./tpl/jump'),
-    exception: require('./tpl/exception')
-}
-
-const base_dir = path.dirname(module.parent.parent.parent.filename);
-const config = loader(path.join(base_dir, './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}
+const path = require('path');
+const loader = require('./loader');
+const {format} = require('./utils/date');
+
+const app = {
+    app_debug: true, // 调试模式
+    app_multi: false, // 是否开启多应用
+
+    default_app: 'app', // 默认应用
+    default_controller: 'index', //默认控制器
+    default_action: 'index', // 默认方法
+
+    common_app: 'common', // 公共应用，存放公共模型及逻辑
+    controller_folder: 'controller', //控制器目录名
+
+    static_dir: '', // 静态文件目录，相对于应用根目录，为空时，关闭静态访问
+
+    koa_body: null // koa-body配置参数，为null或空时，关闭koa-body
+}
+
+const view = {
+    view_folder: 'view', // 模板目录名
+    view_depr: '/', // 模版文件名分割符，'/'代表二级目录
+    view_ext: '.htm', // 模版后缀
+    view_engine: 'art-template', // 默认模版引擎，字符串或引擎类
+    view_filter: {}, // 模版函数
+}
+
+const db = {
+    default: {
+        type      : 'mysql', // 数据库类型
+        host      : '127.0.0.1', // 服务器地址
+        database  : 'jj', // 数据库名
+        user      : 'root', // 数据库用户名
+        password  : '', // 数据库密码
+        port      : '', // 数据库连接端口
+        charset   : 'utf8', // 数据库编码默认采用utf8
+        prefix    : 'jj_' // 数据库表前缀
+    }
+}
+
+const log = {
+    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)));}
+}
+
+const cache = {
+    cache_time: 60 * 60 * 24, // 默认缓存时间（1天），为空或false则为10年
+    clear_time: undefined // (undefined: 清理一次, 0: 关闭自动清理, >0: 为自动清理周期)
+}
+
+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>'
+}
+
+const tpl = {
+    jump: require('./tpl/jump'),
+    exception: require('./tpl/exception')
+}
+
+const base_dir = path.dirname(module.parent.parent.parent.filename);
+const base_config = loader(path.join(base_dir, './config'));
+
+/**
+ * @module config
+ * @type {import('../types').Config}
+ */
+module.exports = {
+    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}
 };

package/lib/context.js

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

package/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);