wok-server 0.1.0

package/dist/validation/validator/min.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.min = void 0;
+const i18n_1 = require("../../i18n");
+/**
+ * 最大值校验.
+ * @param max 最大值
+ * @param msg 错误消息
+ */
+function min(min, msg) {
+    const validator = 'min';
+    return val => {
+        if (val == undefined || val === null) {
+            return { ok: true };
+        }
+        if (typeof val !== 'number') {
+            return { ok: false, validator, message: (0, i18n_1.getI18n)().buildMsg('validate-err-numer') };
+        }
+        if (val < min) {
+            return {
+                ok: false,
+                validator,
+                message: msg || (0, i18n_1.getI18n)().buildMsg('validate-err-min', `${min}`)
+            };
+        }
+        return { ok: true };
+    };
+}
+exports.min = min;

package/dist/validation/validator/not-blank.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.notBlank = void 0;
+const i18n_1 = require("../../i18n");
+/**
+ * 字符串非空校验，以下的情况不会通过校验：undefined，null，非 string 类型，空白字符串.
+ * @param message
+ * @returns
+ */
+function notBlank(message) {
+    const validator = 'notBlank';
+    return val => {
+        if (val === undefined || val === null) {
+            return {
+                ok: false,
+                validator,
+                message: message || (0, i18n_1.getI18n)().buildMsg('validate-err-empty')
+            };
+        }
+        if (typeof val !== 'string') {
+            return { ok: false, validator, message: (0, i18n_1.getI18n)().buildMsg('validate-err-string') };
+        }
+        if (!val.trim()) {
+            return {
+                ok: false,
+                validator,
+                message: message || (0, i18n_1.getI18n)().buildMsg('validate-err-empty')
+            };
+        }
+        return { ok: true };
+    };
+}
+exports.notBlank = notBlank;

package/dist/validation/validator/not-null.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.notNull = void 0;
+const i18n_1 = require("../../i18n");
+/**
+ * 非空校验.
+ * @param message
+ */
+function notNull(message) {
+    return val => {
+        if (val === null || val === undefined) {
+            return {
+                ok: false,
+                message: message || (0, i18n_1.getI18n)().buildMsg('validate-err-empty'),
+                validator: 'notNull'
+            };
+        }
+        return { ok: true };
+    };
+}
+exports.notNull = notNull;

package/dist/validation/validator/plain-obj.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.plainObject = void 0;
+/**
+ * 普通对象校验.
+ * @param opts
+ * @returns
+ */
+function plainObject(opts) {
+    const validator = 'plainObject';
+    return val => {
+        if (!val) {
+            return { ok: true };
+        }
+        for (const entry of Object.entries(opts)) {
+            const [prop, validators] = entry;
+            const v = val[prop];
+            for (const validate of validators) {
+                const result = validate(v);
+                if (!result.ok) {
+                    const propPath = [prop];
+                    if (result.propPath) {
+                        propPath.push(...result.propPath);
+                    }
+                    return { ok: false, validator, message: result.message, propPath };
+                }
+            }
+        }
+        return { ok: true };
+    };
+}
+exports.plainObject = plainObject;

package/dist/validation/validator/regexp.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.regexp = void 0;
+const i18n_1 = require("../../i18n");
+/**
+ * 正则校验
+ * @param pattern 正则表达式
+ * @param msg 错误消息
+ * @returns
+ */
+function regexp(pattern, msg) {
+    const validator = 'regexp';
+    return val => {
+        if (val === undefined || val === null) {
+            return { ok: true };
+        }
+        if (typeof val !== 'string') {
+            return { ok: false, validator, message: (0, i18n_1.getI18n)().buildMsg('validate-err-string') };
+        }
+        if (!pattern.test(val)) {
+            return {
+                ok: false,
+                validator,
+                message: msg || (0, i18n_1.getI18n)().buildMsg('validate-err-incorrect-format')
+            };
+        }
+        return { ok: true };
+    };
+}
+exports.regexp = regexp;

package/documentation/en/index.md

@@ -0,0 +1 @@
+# node-server

package/documentation/zh-cn/cache.md

@@ -0,0 +1,59 @@
+# 缓存
+
+缓存组件提供了简单的内存缓存，采用随机淘汰的驱逐策略，支持过期时间。
+
+## 环境变量
+
+| 环境变量                        | 说明                                                                 |
+| :------------------------------ | :------------------------------------------------------------------- |
+| CACHE_DEFAULT_EXPIRE_IN_SECONDS | 默认的存活时长，取值：1-3600，默认 60                                |
+| CACHE_STAT_TASK_ENABLED         | 是否启用统计任务，启用后每隔指定的时间打印一次缓存统计信息，用于观察 |
+| CACHE_STAT_INTERVAL             | 统计任务执行的周期,单位秒.取值 1-86400                               |
+| CACHE_CLEANING_INTERVAL         | 过期数据清理间隔，单位秒.取值 1-3600，默认 60                        |
+| CACHE_MAX_ELEMENTS              | 最大元素数，取值 1- Number.MAX_VALUE，默认 1024                      |
+
+开启缓存的统计后，会按指定的周期，定时输出统计信息到日志。
+
+```
+[2023/09/27 11:31:35.690][INFO]Cache statistics，
+time window ：2023/09/27 11:31:35.442 - now， hit ：4/4，capacity：120/100
+```
+
+上面是统计日志的示例，内容包含了命中情况，以及容量使用情况。上面的示例中容量超出了，这是因为清理任务还没有来的及清理导致的，属于正常。
+统计是有时间窗口的，只统计这个周期内的情况，所以日志里会有窗口时间信息。
+
+## 性能相关问题
+
+CACHE_CLEANING_INTERVAL 用于控制缓存清理任务的周期，如果项目中缓存的内容较多，则必须需要设置的小一些，及时清理掉无效数据。
+缓存的数据过多，会影响 gc ，因为回收器无法回收被缓存的对象，为此所做的标记和整理内存工作却有很大的消耗。除了清理要频繁一些外，
+缓存记录时也尽可能将过期时间设置的短一些。
+
+为了减少开销，缓存组件采用随机淘汰的驱逐策略，暂不支持设置驱逐策略。
+
+如果需要大量数据的缓存，又不想不影响 gc，可以考虑其它方案，如堆外内存（Buffer），或者外部缓存服务（Redis 等）。
+内存缓存只适合缓存少量短期数据。
+
+## 示例
+
+通过 getCache 函数可以获取到全局的缓存对象，通过对象的相关方法来使用缓存。
+
+```ts
+// 获取缓存对象
+const cache = getCache()
+
+// 使用默认过期时间
+cache.put('abc', 123)
+let value = cache.get('abc') // 123
+
+// 指定过期时间（第三个参数，单位秒）
+cache.put('d', 2233, 1)
+// 删除缓存内容
+cache.remove('d')
+```
+
+缓存对象有个 computeIfAbsent 方法，可以指定生成缓存内容的方法，
+如果没有缓存数据则进行生成，有则直接返回缓存数据。
+
+```ts
+const user = await cache.computeIfAbsent(`get-user-${userId}`, findUserById(userId))
+```

package/documentation/zh-cn/config.md

@@ -0,0 +1,68 @@
+# 配置
+
+配置模块的主要作用是将配置对象与环境变量映射，提供给其它的模块来使用，
+可以和校验组件相结合用于扩展新功能。
+
+提供了两个函数：
+
+| 函数           | 功能说明                                                         |
+| :------------- | :--------------------------------------------------------------- |
+| registerConfig | 注册配置信息，注册会立即匹配环境变量并返回映射了属性后的配置对象 |
+| getConfig      | 获取配置信息                                                     |
+
+环境变量的映射需要有一个前缀，然后将对象的属性拼接前缀，再进行转换，去匹配环境变量。
+比如配置对象有个属性是 appId，设置的前缀是 cus ，那么匹配的环境变量就是 CUS_APP_ID。
+每次调用 registerConfig 函数会有日志输出，可以查看到匹配的情况，用于程序调试。
+
+registerConfig 函数使用示例：
+
+```ts
+/**
+ * 配置定义
+ */
+interface CustomConfig {
+  appId: string
+  appSecret: string
+  ssl: boolean
+  timeout: number
+}
+
+// 调用 registerConfig 与环境变量映射
+// 返回映射后的配置对象
+const config = registerConfig<CustomConfig>(
+  // 第一个参数是默认的配置对象，必须要有默认，在匹配不成功的情况下可以使用
+  { appId: '', appSecret: '', ssl: true, timeout: 5000 },
+  // 第二个参数是配置前缀
+  'custom',
+  // 第三个参数是校验规则，可选，详细可以参照校验组件
+  {
+    appId: [notBlank()],
+    appSecret: [notBlank()],
+    ssl: [notNull()],
+    timeout: [notNull(), min(1000), max(3600)]
+  }
+)
+```
+
+也可以不定义配置对象，直接写默认配置对象，通过第一个参数的默认配置对象可以完成自动类型推断，
+更简洁一些。
+
+```ts
+const config2 = registerConfig(
+  {
+    url: 'http://localhost/api',
+    account: 'Jack'
+  },
+  'c2',
+  {
+    url: [notBlank()]
+  }
+)
+```
+
+getConfig 函数仅一个参数，传递前缀，可以获取到配置对象。
+一般很少需要使用，推荐调用 registerConfig 时将返回的配置对象导出以供其它程序模块使用。
+
+```ts
+const config2 = getConfig('c2')
+```

package/documentation/zh-cn/http-client.md

@@ -0,0 +1,33 @@
+# HTTP 客户端
+
+HTTP 客户端是基于 Nodejs 内置的 http 和 https 模块封装的 http 请求发送工具，
+提供了三个函数。
+
+| 函数      | 作用                                     |
+| :-------- | :--------------------------------------- |
+| doRequest | 通用的 http 请求，可以自定义各种选项     |
+| postJson  | 发送 post 请求，获取 json 格式的响应数据 |
+| getJson   | 发送 get 请求，获取 json 格式的响应数据  |
+
+## 使用示例
+
+```ts
+// get 请求 json
+const list = await getJson<User[]>({
+  url: '/users'
+})
+
+// post 请求 json
+const res = await postJson<Result>({
+  url: '/data/save',
+  body: { name: 'jack', age: 33 }
+})
+
+// 使用 doRequest，自定义更多的选项
+await doRequest({
+  url: '/users/001',
+  method: 'DELETE',
+  timeout: 5000,
+  followRedirect: true
+})
+```

package/documentation/zh-cn/i18n.md

@@ -0,0 +1,154 @@
+# 国际化
+
+国际化组件提供了对多语言环境的支持，可支持扩展新的国际化内容，并自动保持语言一致。
+i18n 对象是全局的，在处理请求时如有异步操作，可通过绑定操作来保持一次请求的处理语言始终不变。
+
+## 无国际化处理
+
+默认情况下国际化组件会根据环境来自动更新语言，但是如果是在容器和虚拟中使用，
+那么很可能镜像默认使用的是英文。
+
+如果项目无做国际化的需要，并且要保证框架中的提示信息必须是中文，可以在程序中指定环境变量 LANG。
+
+```ts
+// 通过 process 更改环境变量 LANG，指定简体中文
+// 必须写在框架 import 之前
+process.env.LANG = 'zh-CN'
+// 前面变量改过了，再 import
+import {...} from 'wok-server'
+```
+
+如果使用的是容器，可直接为容器设置环境变量，这样就不需要改代码了。
+
+## 使用示例
+
+```ts
+// 通过 getI18n 函数获取 i18n 对象
+const i18n = getI18n()
+// getLang 方法可以获取当前使用的语言
+const currentLang = i18n.getLang()
+// setLang 方法可以切换语言，返回布尔类型，表示是否切换成功
+// 只有支持的语言标签可以被支持才会切换成功
+i18n.setLang('en')
+// buildMsg 方法可以根据当前语言构建消息
+// 第一个参数是 key （有类型约束）,后面可以填写0到多个模板参数
+// 更多的信息下面的配置新语言会介绍
+const msg = i18n.buildMsg('validate-err-max', '7')
+```
+
+## 语言标签与匹配规则
+
+目前只实现对语言加地区的格式的支持，如 en-US，en 表示英语，US 表示美国。
+其中地区是可选的，在配置的时候也可以只有语言，如 en 。在匹配时，大小写不区分。
+
+如果只配置了“en-US”，但是将语言设置为 “en-GB”，也是可以成功的。
+这是因为匹配的时候，如果没有找到语言和地区完全一致的配置，就寻找语言的默认，
+也就是 "en"，发现默认也没有，于是就从相同语言中寻找第一个配置，最终使用的是 "en-US"。
+
+在切换语言时如果匹配失败，则不进行切换，保持不变，**并不会使用默认语言**。
+默认语言统一是 en ，任何扩展的 i18n 对象都必须有一套英文作为默认，这是为了保持一致，保障程序的正常使用。
+但是程序初始化的时候会根据当前的环境变量来自动进行切换，如果设置了 LANG 或 LC_CTYPE 变量，
+则会根据环境变量的设置来完成切换。对于扩展的国际化内容则需要自行处理，详细请看下面关于扩展的内容。
+
+## 配置新的语言
+
+框架中已经内置了以下语言。
+
+| 语言标签 | 对应语言       |
+| :------- | :------------- |
+| en       | 英语，默认语言 |
+| zh-CN    | 简体中文       |
+| zh-TW    | 繁体中文       |
+| zh-HK    | 香港繁体中文   |
+| ja       | 日语           |
+| ko       | 韩语           |
+| ru       | 俄语           |
+| es       | 西班牙语       |
+| de       | 德语           |
+| fr       | 法语           |
+| ar       | 阿拉伯语       |
+| pt       | 葡萄牙语       |
+
+如果要使用的语言没有被内置，就需要自己进行配置，下面是示例代码。
+
+```ts
+const i18n = getI18n()
+// 调用 setMsgs 进行语言的设置，第一个参数是语言标签，第二个参数是消息模板
+i18n.setMsgs('ja', {
+  'validate-err-array': '値が配列ではありません',
+  'validate-err-enum': '値は {} の中のいずれかでなければなりません',
+  'validate-err-numer': '値が数字ではありません',
+  'validate-err-max': '{} 以下である必要があります',
+  'validate-err-min': '{} 以上である必要があります',
+  'validate-err-empty': '空であってはいけません',
+  'validate-err-string': '値が文字列のタイプではありません',
+  'validate-err-incorrect-format': '形式が正しくありません',
+  'validate-err-no-length': 'length属性が見当たりません',
+  'validate-err-length-not-number': 'lengthプロパティは数値ではありません',
+  'validate-err-min-length': '長さは {} 以上でなければりません',
+  'validate-err-max-length': '長さは {} 以下でなければなりません'
+})
+// 设置后就可以成功切换到自定义的语言了
+i18n.setLang('ja')
+```
+
+## 扩展新内容
+
+以上都是框架自带的国际化内容，实际项目开发中有很多业务相关的国际化，
+可以基于框架的 i18n 对象进行扩展新的内容。扩展得到的对象会与 i18n 全局对象
+的语言保持一致，在需要更改语言的时候，只需要调用全局对象 i18n 的 setLang 方法就可以了。
+
+```ts
+// 获取 i18n 对象
+const i18n = getI18n()
+// 新的语言模板定义
+interface ExtMsgs {
+  hello: string
+  world: string
+}
+// 扩展新的内容, 参数是英文模板，统一使用英文作为默认，文档前面已经有说明
+// 返回的是一个 I18n 类型的对象，方法与全局的 i18n 对象基本一致，只是没有 extend 方法
+const extI18n = i18n.extend<ExtMsgs>({ hello: 'hello', world: 'world' })
+// 为扩展内容添加中文
+extI18n.setMsgs('zh-cn', { hello: '你好', world: '世界' })
+
+// i18n 全局对象更改语言后，extI18n 也会改变
+// 在实际开发中，可根据情况在扩展完成后切换到合适的语言
+i18n.setLang('zh')
+
+i18n.getLang() // zh
+extI18n.getLang() // zh
+```
+
+在实际开发中，可以将 extI18n 对象导出以供其它模块使用。
+
+需要注意的是，新的语言模板，value 必须都是 string 类型，否则会报错。
+模板内容支持 0 到多个占位，比如 `{accountNotExist:"帐号{}不存在"}`，调用 `buildMsg('accountNotExist','jack')`
+得到 `"帐号jack不存在"`。
+
+## 绑定语言
+
+由于 i18n 对象是全局的，是共享的，在处理请求时，如果请求有异步操作，
+那么很可能一个请求更改了语言后执行异步操作，又被别的请求更改了语言，待异步完成后，
+语言可能是不正确的。
+
+这种情况可以使用绑定语言的功能。
+
+```ts
+// 处理请求，简单的演示，详细的可以看后面的 mvc 章节
+async function handleReq(exchange: RouterExchange): Promise<void> {
+  // 消息头，类型是 IncomingHttpHeaders，nodejs 内置的 http 模块原生类型
+  const headers = exchange.headers
+  // 绑定得到一个语言固定的 i18n 对象，extI18n 是上面演示中扩展的业务国际化对象
+  // bindByRequest 会根据消息头 'accept-language' 的值生成固定语言的 i18n 对象
+  const boundI18n = extI18n.bindByRequest(headers)
+  await query1()
+  await query2()
+  await query3()
+  // 构建的消息始终是和请求接受的语言相关
+  const hello = boundI18n.buildMsg('hello')
+}
+```
+
+此外还有 i18n 对象还有一个 switchByRequest 方法，参数也是 IncomingHttpHeaders 类型，
+作用是根据消息头切换语言。

package/documentation/zh-cn/index.md

@@ -0,0 +1,25 @@
+# node-server
+
+Nodejs 后端开发框架，简洁，易上手，功能够用。使用 Typescript 开发，有完整的类型定义，
+开发效率高。
+
+## 文档约定
+
+所有文档中出现的演示代码一律使用 Typescript，也只推荐在 Typescript 的项目中使用框架，因为框架很多功能都依赖类型推断。
+
+文档中不会列出每一个选项的信息，这样工作量太大了。但是，会尽可能的给出较为丰富的使用示例，具体的参数，
+在使用的时候，可以通过编辑器的文档预览和跳转功能查看定义文件。
+
+## 功能
+
+- [国际化](./i18n.md)
+- [校验](./validate.md)
+- [配置](./config.md)
+- [日志](./log.md)
+- [缓存](./cache.md)
+- [mysql](./mysql.md)
+- [mongodb](./mongodb.md)
+- [MVC](./mvc.md)
+- [任务](./task.md)
+- [Http 客户端](./http-client.md)
+- [单元测试](./test.md)

package/documentation/zh-cn/log.md

@@ -0,0 +1,40 @@
+# 日志
+
+日志用于记录信息，支持简单的级别控制，以及写入文件功能。
+
+## 环境变量
+
+| 环境变量名称      | 默认值 | 说明                                                                     |
+| :---------------- | :----- | :----------------------------------------------------------------------- |
+| LOG_LEVEL         | info   | 日志级别，低于设定级别的日志将不会输出，取值：DEBUG，INFO，WARN,ERROR    |
+| LOG_FILE          | false  | 取值 true 或 false ，表示是否开启文件                                    |
+| LOG_FILE_MAX_DAYS | 30     | 数文件的保留天数                                                         |
+| LOG_FILE_DIR      | logs   | 日志文件存储路径，支持相对路径和绝对路径，相对路径是相对于进程执行目录的 |
+
+## 使用
+
+通过 getLogger() 函数获取日志对象，然后调用日志对象的方法来输出日志。
+
+```ts
+const logger = getLogger()
+
+logger.info('普通日志信息')
+
+const err = new Error('错误信息测试')
+logger.error('错误日志输出信息', err)
+
+if (logger.isDebugEnabled()) {
+  logger.debug('调试日志输出', JSON.stringify(args))
+}
+```
+
+## 自定义日志存储
+
+通过函数 setLogStore 可以自定义日志的存储，一旦设置，将会覆盖掉文件存储，即使设置了开启文件，日志也不会输出到文件中。
+
+```ts
+setLogStore(log => {
+  // 可以根据需要将日志内容放入消息队列或独立的文件存储系统中
+  messageQueue.push(log)
+})
+```