wok-server 0.4.13 → 0.6.0

package/README.en.md

@@ -0,0 +1,61 @@
+[简体中文](./README.md) | English
+
+# Wok Server
+
+[![npm version](https://img.shields.io/npm/v/wok-server)](https://www.npmjs.com/package/wok-server)
+[![license](https://img.shields.io/npm/l/wok-server)](https://github.com/nicepkg/wok-server/blob/master/LICENSE)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue)](https://www.typescriptlang.org/)
+
+A lightweight, restrained backend framework for Node.js and TypeScript.
+
+## Features
+
+- **Infrastructure** — Configuration, Logging, i18n, Caching
+- **Web Layer** — Routing, Validation, MVC
+- **Database** — MySQL, MongoDB
+- **Others** — Scheduled Tasks
+
+## Why Wok Server
+
+- Functional-first with minimal OOP, low learning curve
+- Deliberately restrained — no decorators, proxies, or metaprogramming
+- Lightweight wrapper, compatible with the broader HTTP ecosystem
+- Full TypeScript definitions with IDE IntelliSense support
+- Self-documenting code with detailed method and parameter annotations
+- Built-in i18n with extensible language support
+
+## Quick Start
+
+```bash
+npm i wok-server
+```
+
+```ts
+import { startWebServer } from 'wok-server'
+
+startWebServer({
+  routers: {
+    '/': async exchange => exchange.respondText('Hello world!')
+  }
+}).catch(e => {
+  console.error('Start server failed', e)
+})
+```
+
+Visit `http://localhost:8080` to see the output.
+
+For more configuration via environment variables, see the [full documentation](https://gitee.com/tai/wok-server/blob/master/documentation/zh-cn/index.md).
+
+### Install AI Skills
+
+wok-server provides AI skills that help AI coding assistants better understand and use wok-server components.
+
+```bash
+npx skills add peaktai/wok-server --all
+```
+
+If GitHub access is slow, use the Gitee mirror:
+
+```bash
+npx skills add https://gitee.com/tai/wok-server.git --all
+```

package/README.md

@@ -1,57 +1,72 @@
+[English](./README.en.md) | 简体中文
+
 # Wok Server
 
-一个简洁易用的 Nodejs 后端框架，使用 Typescript 开发，有完整的类型约束和定义，注释详细，文档齐全，支持国际化。
+[![npm version](https://img.shields.io/npm/v/wok-server)](https://www.npmjs.com/package/wok-server)
+[![license](https://img.shields.io/npm/l/wok-server)](https://github.com/nicepkg/wok-server/blob/master/LICENSE)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue)](https://www.typescriptlang.org/)
 
-主要功能：配置，日志，国际化，校验，缓存，MVC，mysql，mongodb ，周期任务 。
+一个基于 Node.js 和 TypeScript 的后端框架，轻量、克制、简洁。
 
-[查看文档](https://gitee.com/tai/wok-server/blob/master/documentation/zh-cn/index.md)
+## 功能概览
 
-## 优点
+- **基础设施** — 配置管理、日志、国际化、缓存
+- **Web 层** — 路由、参数校验、MVC
+- **数据库** — MySQL、MongoDB
+- **其他** — 周期任务
 
-- 学习成本较低，函数式为主，少量面向对象，未使用代理和装饰器等增强技术
-- 功能简单，使用方便，保持克制，不引入太多特性
-- 轻量封装，最大限度兼容已有生态，支持集成第三方 http 相关的库来处理请求
-- 支持国际化，自带多种语言的支持，国际化内容支持扩展
-- 有完整的类型约束和定义，结合 IDE 的代码补全功能，开发效率高
-- 注释详细，文档就在代码中，方法和参数都有详细说明，可在 IDE 的辅助下方便查看
+## 为什么选择 Wok Server
 
-## Hello world
+- 函数式为主，少量面向对象，学习成本低
+- 保持克制，不引入代理、装饰器等增强技术
+- 轻量封装，兼容第三方 HTTP 生态
+- 完整的类型定义，配合 IDE 智能补全，开发效率高
+- 注释即文档，方法及参数均有详细说明
+- 内置国际化支持，可扩展多语言
 
-安装：
+## 快速开始
 
+```bash
+npm i wok-server
 ```
-npm i wok-server --save
-```
-
-入口文件：
 
 ```ts
 import { startWebServer } from 'wok-server'
 
 startWebServer({
   routers: {
-    '/': async exchange => exchange.respondText('Hello world !')
+    '/': async exchange => exchange.respondText('Hello world!')
   }
 }).catch(e => {
   console.error('Start server failed', e)
 })
 ```
 
-上面的代码启动了 web 服务，访问路径 `http://localhost:8080` 将输出文本 “Hello world !”。
+启动后访问 `http://localhost:8080` 即可看到输出。
+
+更多配置通过环境变量设置，详见[完整文档](https://gitee.com/tai/wok-server/blob/master/documentation/zh-cn/index.md)。
+
+### AI 技能安装
+
+wok-server 提供了 AI 技能，安装后可以让 AI 编程助手更好地理解和使用 wok-server 组件。
 
-相关的设置可以通过环境变量来修改，查看[完整文档](https://gitee.com/tai/wok-server/blob/master/documentation/zh-cn/index.md)了解细节。
 
-## 一些问题的说明
+```bash
+npx skills add peaktai/wok-server --all
+```
+
+国内用户访问 github 速度慢，可以使用 gitee 仓库地址来安装。
+
+```bash
+npx skills add https://gitee.com/tai/wok-server.git --all
+```
+
+## FAQ
 
-### 为什么直接集成依赖库
+### 为什么内置 MySQL 和 MongoDB 驱动？
 
-项目中对 mysql 客户端和 mongodb 的驱动直接打包集成了，也没有将这两个组件
-单独拆分成一个独立的包以供按需引入。这样做是为了方便，不需要安装那么多包，安装的包多了
-之后，还有可能需要解决依赖冲突问题，找到版本匹配的包，使用和维护都麻烦。对于后端程序来说，
-体积大一些问题也不大。
+mysql2 和 mongodb 驱动已直接集成，安装一个包即可使用，避免多个包的版本冲突和维护成本。对于后端应用，包体积的增加影响有限。
 
-### 为什么部分可选功能需要第三方库，而又没有集成
+### 为什么 WebSocket、文件上传等功能需要自行引入？
 
-对于 wesocket 和文件上传等功能，框架没有实现，而是需要使用者引入第三方库，框架没有集成这些库。
-这些库是基于 Nodejs 内置的模块 http，不用担心与框架的兼容性问题，框架只要保持支持即可，
-也可以充分利用已有的生态，不需要专门为框架编写扩展。
+这些功能基于 Node.js 原生 `http` 模块，天然兼容框架，无需专门适配。由用户按需引入第三方库，可以充分利用社区生态，同时减少框架的维护负担。

package/dist/cache/cache.js

@@ -1,98 +1,98 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.Cache = void 0;
-const config_1 = require("./config");
-class Cache {
-    valueMap;
-    stat;
-    /**
-     * promise 表，作用是处理异步并发问题，如果有相同的 key 同时请求，保证异步的 provider 只执行一次
-     */
-    promiseMap = new Map();
-    constructor(valueMap, stat) {
-        this.valueMap = valueMap;
-        this.stat = stat;
-    }
-    /**
-     * 放入缓存
-     * @param key
-     * @param val
-     * @param expiresInSeconds
-     */
-    put(key, val, expiresInSeconds) {
-        const finalExpiresInSeconds = typeof expiresInSeconds === 'number' ? expiresInSeconds : config_1.config.defaultExpireInSeconds;
-        this.valueMap.set(key, {
-            val,
-            expireAt: new Date().getTime() + finalExpiresInSeconds * 1000
-        });
-    }
-    /**
-     * 获取缓存值
-     * @param key
-     * @returns
-     */
-    get(key) {
-        const content = this.valueMap.get(key);
-        if (!content) {
-            this.stat?.addGet(false);
-            return undefined;
-        }
-        if (content.expireAt < new Date().getTime()) {
-            this.stat?.addGet(false);
-            this.valueMap.delete(key);
-            return undefined;
-        }
-        this.stat?.addGet(true);
-        return content.val;
-    }
-    /**
-     * 清除所有缓存
-     */
-    clear() {
-        this.valueMap.clear();
-        this.stat?.clear();
-    }
-    /**
-     * 删除.
-     * @param key
-     */
-    remove(key) {
-        this.valueMap.delete(key);
-    }
-    /**
-     * 在缓存值不存在时计算缓存的值，然后放入并返回.
-     * @param key
-     * @param provider
-     * @param expiresInSeconds
-     */
-    async computeIfAbsent(key, provider, expiresInSeconds) {
-        const content = this.valueMap.get(key);
-        if (content && content.expireAt >= new Date().getTime()) {
-            this.stat?.addGet(true);
-            return content.val;
-        }
-        this.stat?.addGet(false);
-        // 如果已经在处理中，则直接返回 promise
-        const ep = this.promiseMap.get(key);
-        if (ep) {
-            return ep;
-        }
-        // 创建新的异步流程
-        const promise = Promise.resolve().then(async () => {
-            try {
-                const finalExpireInSeconds = typeof expiresInSeconds === 'number' ? expiresInSeconds : config_1.config.defaultExpireInSeconds;
-                // 计算值
-                const res = provider();
-                const val = res instanceof Promise ? await res : res;
-                this.put(key, val, finalExpireInSeconds);
-                return val;
-            }
-            finally {
-                this.promiseMap.delete(key);
-            }
-        });
-        this.promiseMap.set(key, promise);
-        return promise;
-    }
-}
-exports.Cache = Cache;
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Cache = void 0;
+const config_1 = require("./config");
+class Cache {
+    valueMap;
+    stat;
+    /**
+     * promise 表，作用是处理异步并发问题，如果有相同的 key 同时请求，保证异步的 provider 只执行一次
+     */
+    promiseMap = new Map();
+    constructor(valueMap, stat) {
+        this.valueMap = valueMap;
+        this.stat = stat;
+    }
+    /**
+     * 放入缓存
+     * @param key
+     * @param val
+     * @param expiresInSeconds
+     */
+    put(key, val, expiresInSeconds) {
+        const finalExpiresInSeconds = typeof expiresInSeconds === 'number' ? expiresInSeconds : config_1.config.defaultExpireInSeconds;
+        this.valueMap.set(key, {
+            val,
+            expireAt: new Date().getTime() + finalExpiresInSeconds * 1000
+        });
+    }
+    /**
+     * 获取缓存值
+     * @param key
+     * @returns
+     */
+    get(key) {
+        const content = this.valueMap.get(key);
+        if (!content) {
+            this.stat?.addGet(false);
+            return undefined;
+        }
+        if (content.expireAt < new Date().getTime()) {
+            this.stat?.addGet(false);
+            this.valueMap.delete(key);
+            return undefined;
+        }
+        this.stat?.addGet(true);
+        return content.val;
+    }
+    /**
+     * 清除所有缓存
+     */
+    clear() {
+        this.valueMap.clear();
+        this.stat?.clear();
+    }
+    /**
+     * 删除.
+     * @param key
+     */
+    remove(key) {
+        this.valueMap.delete(key);
+    }
+    /**
+     * 在缓存值不存在时计算缓存的值，然后放入并返回.
+     * @param key
+     * @param provider
+     * @param expiresInSeconds
+     */
+    async computeIfAbsent(key, provider, expiresInSeconds) {
+        const content = this.valueMap.get(key);
+        if (content && content.expireAt >= new Date().getTime()) {
+            this.stat?.addGet(true);
+            return content.val;
+        }
+        this.stat?.addGet(false);
+        // 如果已经在处理中，则直接返回 promise
+        const ep = this.promiseMap.get(key);
+        if (ep) {
+            return ep;
+        }
+        // 创建新的异步流程
+        const promise = Promise.resolve().then(async () => {
+            try {
+                const finalExpireInSeconds = typeof expiresInSeconds === 'number' ? expiresInSeconds : config_1.config.defaultExpireInSeconds;
+                // 计算值
+                const res = provider();
+                const val = res instanceof Promise ? await res : res;
+                this.put(key, val, finalExpireInSeconds);
+                return val;
+            }
+            finally {
+                this.promiseMap.delete(key);
+            }
+        });
+        this.promiseMap.set(key, promise);
+        return promise;
+    }
+}
+exports.Cache = Cache;

package/dist/cache/config.js

@@ -1,19 +1,19 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.config = void 0;
-const config_1 = require("../config");
-const validation_1 = require("../validation");
-const ENV_PREFIX = 'CACHE';
-exports.config = (0, config_1.registerConfig)({
-    defaultExpireInSeconds: 60,
-    statTaskEnabled: false,
-    statInterval: 300,
-    maxElements: 1024,
-    cleaningInterval: 60
-}, ENV_PREFIX, {
-    defaultExpireInSeconds: [(0, validation_1.notNull)(), (0, validation_1.min)(1), (0, validation_1.max)(3600)],
-    statTaskEnabled: [(0, validation_1.notNull)()],
-    statInterval: [(0, validation_1.notNull)(), (0, validation_1.min)(1), (0, validation_1.max)(3600 * 24)],
-    maxElements: [(0, validation_1.notNull)(), (0, validation_1.min)(1), (0, validation_1.max)(Number.MAX_VALUE)],
-    cleaningInterval: [(0, validation_1.notNull)(), (0, validation_1.min)(1), (0, validation_1.max)(3600)]
-});
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.config = void 0;
+const config_1 = require("../config");
+const validation_1 = require("../validation");
+const ENV_PREFIX = 'CACHE';
+exports.config = (0, config_1.registerConfig)({
+    defaultExpireInSeconds: 60,
+    statTaskEnabled: false,
+    statInterval: 300,
+    maxElements: 1024,
+    cleaningInterval: 60
+}, ENV_PREFIX, {
+    defaultExpireInSeconds: [(0, validation_1.notNull)(), (0, validation_1.min)(1), (0, validation_1.max)(3600)],
+    statTaskEnabled: [(0, validation_1.notNull)()],
+    statInterval: [(0, validation_1.notNull)(), (0, validation_1.min)(1), (0, validation_1.max)(3600 * 24)],
+    maxElements: [(0, validation_1.notNull)(), (0, validation_1.min)(1), (0, validation_1.max)(Number.MAX_VALUE)],
+    cleaningInterval: [(0, validation_1.notNull)(), (0, validation_1.min)(1), (0, validation_1.max)(3600)]
+});

package/dist/cache/index.js

@@ -1,27 +1,27 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.getCache = void 0;
-const task_1 = require("../task");
-const cache_1 = require("./cache");
-const config_1 = require("./config");
-const purge_task_1 = require("./purge-task");
-const stat_1 = require("./stat");
-const valueMap = new Map();
-const stat = config_1.config.statTaskEnabled ? new stat_1.CacheStat(valueMap) : undefined;
-const cache = new cache_1.Cache(valueMap, stat);
-// 清理任务
-(0, task_1.scheduleWithFixedDelay)(config_1.config.cleaningInterval, config_1.config.cleaningInterval, new purge_task_1.PurgeTask(valueMap));
-// 统计任务
-if (config_1.config.statTaskEnabled) {
-    (0, task_1.scheduleWithFixedDelay)(config_1.config.statInterval, config_1.config.statInterval, {
-        name: 'Cache statistics',
-        async run() {
-            stat?.log();
-            stat?.clear();
-        }
-    });
-}
-function getCache() {
-    return cache;
-}
-exports.getCache = getCache;
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getCache = void 0;
+const task_1 = require("../task");
+const cache_1 = require("./cache");
+const config_1 = require("./config");
+const purge_task_1 = require("./purge-task");
+const stat_1 = require("./stat");
+const valueMap = new Map();
+const stat = config_1.config.statTaskEnabled ? new stat_1.CacheStat(valueMap) : undefined;
+const cache = new cache_1.Cache(valueMap, stat);
+// 清理任务
+(0, task_1.scheduleWithFixedDelay)(config_1.config.cleaningInterval, config_1.config.cleaningInterval, new purge_task_1.PurgeTask(valueMap));
+// 统计任务
+if (config_1.config.statTaskEnabled) {
+    (0, task_1.scheduleWithFixedDelay)(config_1.config.statInterval, config_1.config.statInterval, {
+        name: 'Cache statistics',
+        async run() {
+            stat?.log();
+            stat?.clear();
+        }
+    });
+}
+function getCache() {
+    return cache;
+}
+exports.getCache = getCache;

package/dist/cache/purge-task.js

@@ -1,46 +1,46 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.PurgeTask = void 0;
-const log_1 = require("../log");
-const config_1 = require("./config");
-/**
- * 缓存清理任务
- */
-class PurgeTask {
-    valueMap;
-    name = 'Cache purge';
-    constructor(valueMap) {
-        this.valueMap = valueMap;
-    }
-    async run() {
-        let removeCount = 0;
-        for (const entry of this.valueMap.entries()) {
-            const [key, value] = entry;
-            if (value.expireAt < new Date().getTime()) {
-                this.valueMap.delete(key);
-                removeCount++;
-            }
-        }
-        if (removeCount > 0) {
-            (0, log_1.getLogger)().info(`A total of ${removeCount} expired cache ${removeCount > 1 ? 'records' : 'record'} have been cleared.`);
-        }
-        // 如果过期的都清理掉，但是元素总数仍然超出，则删除多余元素，删除是从头开始删除的
-        // 看上去是按put顺序清理最早的，实际上随机的，重复 set 相同的 key，key 的位置是不会变的，不保证 key 的顺序
-        // 所以，缓存是随机驱逐的
-        // 目前没有考虑支持其它的策略，因为需要额外记录信息，清理的逻辑也可能更复杂
-        // nodejs 是单线程模式的，规模上去后，可能需要执行较长的时间带来阻塞
-        if (this.valueMap.size > config_1.config.maxElements) {
-            let diff = this.valueMap.size - config_1.config.maxElements;
-            let evictedCount = 0;
-            for (const key of this.valueMap.keys()) {
-                this.valueMap.delete(key);
-                evictedCount++;
-                if (evictedCount >= diff) {
-                    break;
-                }
-            }
-            (0, log_1.getLogger)().info(`A total of ${evictedCount} cache ${evictedCount > 1 ? 'records' : 'record'} have been evicted.`);
-        }
-    }
-}
-exports.PurgeTask = PurgeTask;
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PurgeTask = void 0;
+const log_1 = require("../log");
+const config_1 = require("./config");
+/**
+ * 缓存清理任务
+ */
+class PurgeTask {
+    valueMap;
+    name = 'Cache purge';
+    constructor(valueMap) {
+        this.valueMap = valueMap;
+    }
+    async run() {
+        let removeCount = 0;
+        for (const entry of this.valueMap.entries()) {
+            const [key, value] = entry;
+            if (value.expireAt < new Date().getTime()) {
+                this.valueMap.delete(key);
+                removeCount++;
+            }
+        }
+        if (removeCount > 0) {
+            (0, log_1.getLogger)().info(`A total of ${removeCount} expired cache ${removeCount > 1 ? 'records' : 'record'} have been cleared.`);
+        }
+        // 如果过期的都清理掉，但是元素总数仍然超出，则删除多余元素，删除是从头开始删除的
+        // 看上去是按put顺序清理最早的，实际上随机的，重复 set 相同的 key，key 的位置是不会变的，不保证 key 的顺序
+        // 所以，缓存是随机驱逐的
+        // 目前没有考虑支持其它的策略，因为需要额外记录信息，清理的逻辑也可能更复杂
+        // nodejs 是单线程模式的，规模上去后，可能需要执行较长的时间带来阻塞
+        if (this.valueMap.size > config_1.config.maxElements) {
+            let diff = this.valueMap.size - config_1.config.maxElements;
+            let evictedCount = 0;
+            for (const key of this.valueMap.keys()) {
+                this.valueMap.delete(key);
+                evictedCount++;
+                if (evictedCount >= diff) {
+                    break;
+                }
+            }
+            (0, log_1.getLogger)().info(`A total of ${evictedCount} cache ${evictedCount > 1 ? 'records' : 'record'} have been evicted.`);
+        }
+    }
+}
+exports.PurgeTask = PurgeTask;

package/dist/cache/stat.js

@@ -1,47 +1,47 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.CacheStat = void 0;
-const log_1 = require("../log");
-const date_1 = require("../log/date");
-const config_1 = require("./config");
-/**
- * 缓存统计.
- */
-class CacheStat {
-    valueMap;
-    /**
-     * 开始统计时间
-     */
-    start;
-    totalGet = 0;
-    totalHit = 0;
-    constructor(valueMap) {
-        this.valueMap = valueMap;
-        this.start = new Date();
-    }
-    /**
-     * 添加 get 次数
-     * @param hit 是否命中
-     */
-    addGet(hit) {
-        this.totalGet++;
-        if (hit) {
-            this.totalHit++;
-        }
-    }
-    /**
-     * 清空统计信息，重新开始统计.
-     */
-    clear() {
-        this.start = new Date();
-        this.totalGet = 0;
-        this.totalHit = 0;
-    }
-    /**
-     * 输出日志
-     */
-    log() {
-        (0, log_1.getLogger)().info(`Cache statistics，time window ：${(0, date_1.formatDateTime)(this.start)} - now， hit ：${this.totalHit}/${this.totalGet}，capacity：${this.valueMap.size}/${config_1.config.maxElements}`);
-    }
-}
-exports.CacheStat = CacheStat;
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CacheStat = void 0;
+const log_1 = require("../log");
+const date_1 = require("../log/date");
+const config_1 = require("./config");
+/**
+ * 缓存统计.
+ */
+class CacheStat {
+    valueMap;
+    /**
+     * 开始统计时间
+     */
+    start;
+    totalGet = 0;
+    totalHit = 0;
+    constructor(valueMap) {
+        this.valueMap = valueMap;
+        this.start = new Date();
+    }
+    /**
+     * 添加 get 次数
+     * @param hit 是否命中
+     */
+    addGet(hit) {
+        this.totalGet++;
+        if (hit) {
+            this.totalHit++;
+        }
+    }
+    /**
+     * 清空统计信息，重新开始统计.
+     */
+    clear() {
+        this.start = new Date();
+        this.totalGet = 0;
+        this.totalHit = 0;
+    }
+    /**
+     * 输出日志
+     */
+    log() {
+        (0, log_1.getLogger)().info(`Cache statistics，time window ：${(0, date_1.formatDateTime)(this.start)} - now， hit ：${this.totalHit}/${this.totalGet}，capacity：${this.valueMap.size}/${config_1.config.maxElements}`);
+    }
+}
+exports.CacheStat = CacheStat;