wok-server 0.1.0

package/types/cache/cache.d.ts

@@ -0,0 +1,52 @@
+import { CacheStat } from './stat';
+/**
+ * 缓存内容
+ */
+export interface CacheContent {
+    /**
+     * 保存的值
+     */
+    val: any;
+    /**
+     * 过期时间
+     */
+    expireAt: number;
+}
+export declare class Cache {
+    private readonly valueMap;
+    private readonly stat;
+    /**
+     * promise 表，作用是处理异步并发问题，如果有相同的 key 同时请求，保证异步的 provider 只执行一次
+     */
+    private promiseMap;
+    constructor(valueMap: Map<string, CacheContent>, stat: CacheStat);
+    /**
+     * 放入缓存
+     * @param key
+     * @param val
+     * @param expiresInSeconds
+     */
+    put(key: string, val: any, expiresInSeconds?: number): void;
+    /**
+     * 获取缓存值
+     * @param key
+     * @returns
+     */
+    get<T>(key: string): T | undefined;
+    /**
+     * 清除所有缓存
+     */
+    clear(): void;
+    /**
+     * 删除.
+     * @param key
+     */
+    remove(key: string): void;
+    /**
+     * 在缓存值不存在时计算缓存的值，然后放入并返回.
+     * @param key
+     * @param provider
+     * @param expiresInSeconds
+     */
+    computeIfAbsent<T>(key: string, provider: () => Promise<T> | T, expiresInSeconds?: number): Promise<T>;
+}

package/types/cache/config.d.ts

@@ -0,0 +1,32 @@
+/**
+ * 缓存的配置
+ */
+interface CacheConfig {
+    /**
+     * 默认的存活时长，取值：1-3600，默认 60。存活时间应该尽可能的短，尤其是当缓存的内容比较大时，
+     * 否则缓存的内容长时间占用内存，会对 gc 造成影响。
+     */
+    defaultExpireInSeconds: number;
+    /**
+     * 是否启用统计任务，启用后每隔指定的时间打印一次缓存统计信息，用于了解缓存的情况.
+     */
+    statTaskEnabled: boolean;
+    /**
+     * 统计任务执行的周期,单位秒，取值 60-3600。统计周期也即是时间窗口，
+     * 每个周期都是独立的，只统计这个周期内的缓存使用情况。
+     */
+    statInterval: number;
+    /**
+     * 最大元素数量，为了控制缓存占用的内存空间，可以将 maxElements 设置的低一些。
+     */
+    maxElements: number;
+    /**
+     * 数据清理任务执行周期，单位秒.取值 1-3600，清理任务完成两件事：删除过期数据和驱逐多余记录。
+     * 如果项目规模小，缓存的内容非常少，可以将间隔设置长一些，降低频率.
+     * 如果缓存的内容很多，频率需要高一些，及时将无效数据清理掉。
+     * 否则缓存会长时间占用很高的内存无法被回收，回收器完成检查却需要很长时间，影响gc效率.
+     */
+    cleaningInterval: number;
+}
+export declare const config: CacheConfig;
+export {};

package/types/cache/index.d.ts

@@ -0,0 +1,2 @@
+import { Cache } from './cache';
+export declare function getCache(): Cache;

package/types/cache/purge-task.d.ts

@@ -0,0 +1,11 @@
+import { Task } from '../task';
+import { CacheContent } from './cache';
+/**
+ * 缓存清理任务
+ */
+export declare class PurgeTask implements Task {
+    private readonly valueMap;
+    readonly name = "cache purge";
+    constructor(valueMap: Map<string, CacheContent>);
+    run(): Promise<void>;
+}

package/types/cache/stat.d.ts

@@ -0,0 +1,26 @@
+/**
+ * 缓存统计.
+ */
+export declare class CacheStat {
+    private readonly valueMap;
+    /**
+     * 开始统计时间
+     */
+    private start;
+    private totalGet;
+    private totalHit;
+    constructor(valueMap: Map<string, any>);
+    /**
+     * 添加 get 次数
+     * @param hit 是否命中
+     */
+    addGet(hit: boolean): void;
+    /**
+     * 清空统计信息，重新开始统计.
+     */
+    clear(): void;
+    /**
+     * 输出日志
+     */
+    log(): void;
+}

package/types/config/convert.d.ts

@@ -0,0 +1,6 @@
+/**
+ * 转换值.
+ * @param val
+ * @param defaultVal
+ */
+export declare function convert(val: string, defaultVal: any): string | number | boolean;

package/types/config/exception.d.ts

@@ -0,0 +1,7 @@
+/**
+ * 配置异常.
+ */
+export declare class ConfigException extends Error {
+    readonly message: string;
+    constructor(message: string);
+}

package/types/config/index.d.ts

@@ -0,0 +1,15 @@
+import { ValidationOpts } from '../validation';
+/**
+ * 获取配置
+ * @param envPrefix
+ */
+export declare function getConfig<T>(envPrefix: string): T | undefined;
+/**
+ * 注册配置信息.
+ * @param defaultConfig 默认值, 模块会根据默认值来映射环境变量，默认值所有的属性都不能是 undefined，否则无法映射.
+ * @param envPrefix 环境变量前缀.
+ * @param validation 校验规则，如果有值，初始化的时候会对配置进行校验
+ * @returns 映射了环境变量后的配置
+ */
+export declare function registerConfig<T extends {}>(defaultConfig: T, envPrefix: string, validation?: ValidationOpts<T>): T;
+export * from './exception';

package/types/http-client/index.d.ts

@@ -0,0 +1,71 @@
+/// <reference types="node" />
+/// <reference types="node" />
+import { IncomingHttpHeaders } from 'http';
+/**
+ * 请求选项.
+ */
+export interface HttpRequestOpts {
+    /**
+     * 链接地址.
+     */
+    url: string;
+    /**
+     * 查询参数，附加在链接地址上
+     */
+    query?: Record<string, string[] | string>;
+    /**
+     * 正文，可以是序列化好的字符串或二进制内容.
+     */
+    body?: string | Buffer;
+    /**
+     * 消息头
+     */
+    headers?: IncomingHttpHeaders;
+    /**
+     * 请求方法
+     */
+    method: 'GET' | 'HEAD' | 'POST' | 'PUT' | 'DELETE' | 'CONNECT' | 'OPTIONS' | 'TRACE' | 'PATCH';
+    /**
+     * 超时时间，单位毫秒，默认 5000
+     */
+    timeout?: number;
+    /**
+     * 是否跟随重定向
+     */
+    followRedirect?: boolean;
+}
+/**
+ * 响应信息.
+ */
+export interface HttpResponseInfo {
+    /**
+     * 状态码
+     */
+    status: number;
+    /**
+     * 消息头.
+     */
+    headers: IncomingHttpHeaders;
+    /**
+     * 响应正文
+     */
+    body: Buffer;
+}
+/**
+ * 发送 http 请求.
+ * @param opts
+ * @returns
+ */
+export declare function doRequest(opts: HttpRequestOpts): Promise<HttpResponseInfo>;
+/**
+ * 发送 json 格式的 post 请求，body 是未序列化的普通对象，表示要发送的请求数据.
+ * @param opts
+ */
+export declare function postJson<T>(opts: Pick<HttpRequestOpts, 'url' | 'query' | 'headers' | 'timeout'> & {
+    body: any;
+}): Promise<T>;
+/**
+ * get 请求获取 json 格式数据.
+ * @param opts
+ */
+export declare function getJson<T>(opts: Pick<HttpRequestOpts, 'url' | 'query' | 'headers' | 'timeout'>): Promise<T>;

package/types/i18n/ar.d.ts

@@ -0,0 +1,2 @@
+import { I18nMsgs } from './msg';
+export declare const ar: I18nMsgs;

package/types/i18n/de.d.ts

@@ -0,0 +1,2 @@
+import { I18nMsgs } from './msg';
+export declare const de: I18nMsgs;

package/types/i18n/en-us.d.ts

@@ -0,0 +1,2 @@
+import { I18nMsgs } from './msg';
+export declare const enUS: I18nMsgs;

package/types/i18n/es.d.ts

@@ -0,0 +1,2 @@
+import { I18nMsgs } from './msg';
+export declare const es: I18nMsgs;

package/types/i18n/fr.d.ts

@@ -0,0 +1,2 @@
+import { I18nMsgs } from './msg';
+export declare const fr: I18nMsgs;

package/types/i18n/i18n.d.ts

@@ -0,0 +1,102 @@
+/// <reference types="node" />
+import { IncomingHttpHeaders } from 'http';
+/**
+ * 绑定语言的 i18n 类型，不可切换语言.
+ */
+export declare class BoundI18n<T> {
+    private readonly lang;
+    private readonly msgs;
+    constructor(lang: string, msgs: T);
+    /**
+     * 获取当前语言
+     */
+    getLang(): string;
+    /**
+     * 构建国际化消息.
+     * @param key 消息模板的 key
+     * @param args 参数，如果 key 对应的消息模板有占位符号（{}）可以使用参数来填充
+     */
+    buildMsg(key: keyof T, ...args: string[]): string;
+}
+/**
+ * 国际化，提供不同语言消息构建的功能，默认英文.
+ */
+export declare class I18n<T> {
+    readonly enMsgs: T;
+    /**
+     * 当前语言
+     */
+    private lang;
+    /**
+     * 消息模板表，与当前语言是对应的
+     */
+    private msgs;
+    /**
+     * 消息表，key 是语言，value 是一个 key 为地区，value 为 消息模板的 map，两层 map 为的是能够快速匹配.
+     * 地区为空的情况下，缺省值为 - 。语言和地区的 key 全转成小写存储。
+     */
+    private msgsMap;
+    /**
+     * 构造 i18n 对象，必须指定英文的消息模板作为默认。
+     * @param enMsgs 英文的消息模板
+     */
+    constructor(enMsgs: T);
+    protected findMsgsByLang(langTag: string): T | undefined;
+    /**
+     * 设置一种语言对应的消息模板，支持异步，可以做动态加载
+     * @param langTag
+     * @param msgs
+     */
+    setMsgs(langTag: string, msgs: T): void;
+    /**
+     * 给定一个语言标签列表，获得可以被支持的标签列表
+     * @param tags
+     */
+    getSupportedLanguageTags(...tags: string[]): string[];
+    /**
+     * 设置当前语言，如果指定的语言不被支持，则修改无效
+     * @param lang 语言本标签，如 en-US
+     * @returns 是否成功，如果语言不支持则返回 false，不会改变现有语言
+     */
+    setLang(lang: string): boolean;
+    /**
+     * 获取当前语言
+     */
+    getLang(): string;
+    /**
+     * 构建国际化消息.
+     * @param key 消息模板的 key
+     * @param args 参数，如果 key 对应的消息模板有占位符号（{}）可以使用参数来填充
+     */
+    buildMsg(key: keyof T, ...args: string[]): string;
+    /**
+     * 绑定一种语言，生成新的 i18n 对象，该对象仅能使用某一种语言.
+     * @param langTag 语言标签，无值则表示绑定当前语言
+     * @returns 返回一个语言受限的 i18n 对象.
+     */
+    bindLang(langTag?: string): BoundI18n<T>;
+    /**
+     * 根据请求进行语言切换，解析消息头 'accept-language' ，如果 'accept-language' 中没有包含能够支持的语言则使用默认的英文.
+     * @param headers 消息头
+     */
+    switchByRequest(headers: IncomingHttpHeaders): void;
+    private parseAcceptLanguage;
+    /**
+     * 根据请求进行语言绑定，解析消息头 'accept-language'，绑定受支持的第一个语言，如果没有可以被支持的语言，则使用默认的英文.
+     * @param headers 消息头
+     */
+    bindByRequest(headers: IncomingHttpHeaders): BoundI18n<T>;
+}
+/**
+ * 可扩展的 i18n ，增加扩展新 i18n 对象的功能，记录扩展的新对象，同步 setLang 操作
+ */
+export declare class ExtensibleI18n<T extends object> extends I18n<T> {
+    private extendedI18ns;
+    setLang(lang: string): boolean;
+    /**
+     * 扩展国际化内容，生成一个新的 i18n 对象，与当前的 i18n 对象语言保持一致，可在新对象中设置扩展部分的语言。
+     * <K> 新的消息模板类型
+     * @param enMsgs
+     */
+    extend<K extends object>(enMsgs: K): I18n<K>;
+}

package/types/i18n/index.d.ts

@@ -0,0 +1,9 @@
+import { ExtensibleI18n } from './i18n';
+import { I18nMsgs } from './msg';
+/**
+ * 获取 i18n 对象
+ * @returns
+ */
+export declare function getI18n(): ExtensibleI18n<I18nMsgs>;
+export * from './i18n';
+export * from './msg';

package/types/i18n/ja.d.ts

@@ -0,0 +1,2 @@
+import { I18nMsgs } from './msg';
+export declare const ja: I18nMsgs;

package/types/i18n/ko.d.ts

@@ -0,0 +1,2 @@
+import { I18nMsgs } from './msg';
+export declare const ko: I18nMsgs;

package/types/i18n/msg.d.ts

@@ -0,0 +1,50 @@
+export interface I18nMsgs {
+    /**
+     * 校验错误，不是数组
+     */
+    'validate-err-array': string;
+    /**
+     * 校验错误：不是数字
+     */
+    'validate-err-numer': string;
+    /**
+     * 校验错误：不得大于
+     */
+    'validate-err-max': string;
+    /**
+     * 校验错误：不得小于
+     */
+    'validate-err-min': string;
+    /**
+     * 枚举校验错误，值不在范围内
+     */
+    'validate-err-enum': string;
+    /**
+     * 校验错误：不能为空
+     */
+    'validate-err-empty': string;
+    /**
+     * 校验错误：不是字符串
+     */
+    'validate-err-string': string;
+    /**
+     * 校验错误：格式不正确
+     */
+    'validate-err-incorrect-format': string;
+    /**
+     * 校验错误，没有 length 属性
+     */
+    'validate-err-no-length': string;
+    /**
+     * 校验错误，length 不是数字
+     */
+    'validate-err-length-not-number': string;
+    /**
+     * 校验错误：最小长度
+     */
+    'validate-err-min-length': string;
+    /**
+     * 校验错误：最大长度
+     */
+    'validate-err-max-length': string;
+}

package/types/i18n/pt.d.ts

@@ -0,0 +1,2 @@
+import { I18nMsgs } from './msg';
+export declare const pt: I18nMsgs;

package/types/i18n/ru.d.ts

@@ -0,0 +1,2 @@
+import { I18nMsgs } from './msg';
+export declare const ru: I18nMsgs;

package/types/i18n/tag.d.ts

@@ -0,0 +1,11 @@
+export interface LangTag {
+    lang: string;
+    region?: string;
+}
+/**
+ * 解析语言标签，语言标签格式非常多，这里仅支持语言加地区的形式，如 zh-CN。
+ * 更多信息可以查看 https://www.rfc-editor.org/rfc/bcp/bcp47.txt 。
+ * @param tag
+ * @returns 语言和地区信息，为了方便匹配，全转小写
+ */
+export declare function parseLangTag(tag: string): LangTag;

package/types/i18n/zh-HK.d.ts

@@ -0,0 +1,2 @@
+import { I18nMsgs } from "./msg";
+export declare const zhHK: I18nMsgs;

package/types/i18n/zh-TW.d.ts

@@ -0,0 +1,2 @@
+import { I18nMsgs } from './msg';
+export declare const zhTW: I18nMsgs;

package/types/i18n/zh-cn.d.ts

@@ -0,0 +1,2 @@
+import { I18nMsgs } from './msg';
+export declare const zhCN: I18nMsgs;

package/types/index.d.ts

@@ -0,0 +1,10 @@
+export * from './log';
+export * from './i18n';
+export * from './validation';
+export * from './config';
+export * from './cache';
+export * from './task';
+export * from './mvc';
+export * from './mysql';
+export * from './http-client';
+export * from './mongodb';

package/types/log/config.d.ts

@@ -0,0 +1,27 @@
+import { LogLevel } from './level';
+/**
+ * 日志配置的定义
+ */
+export interface LogConfig {
+    /**
+     * 是否输出到文件，如果为 true ，则会在根目录下生成 logs 目录存放日志文件.
+     */
+    file: boolean;
+    /**
+     * 文件目录
+     */
+    fileDir: string;
+    /**
+     * 文件最大保存天数.需要开启文件才有效.
+     */
+    fileMaxDays: number;
+    /**
+     * 要输出的日志级别.
+     */
+    level: LogLevel;
+}
+/**
+ * 默认配置信息.
+ */
+declare const config: LogConfig;
+export { config };

package/types/log/date.d.ts

@@ -0,0 +1,2 @@
+export declare function currentDateTimeStr(): string;
+export declare function formatDateTime(date: Date): string;

package/types/log/file.d.ts

@@ -0,0 +1,5 @@
+/**
+ * 文件存储.
+ * @param log
+ */
+export declare function fileStore(log: string): void;

package/types/log/index.d.ts

@@ -0,0 +1,34 @@
+/**
+ * 获取日志对象.
+ * @returns
+ */
+export declare function getLogger(): Readonly<{
+    /**
+     * debug 日志
+     */
+    debug(message: string): void;
+    isDebugEnabled(): boolean;
+    /**
+     * info 日志
+     * @param message
+     */
+    info(message: string): void;
+    isInfoEnabled(): boolean;
+    /**
+     * 警告日志
+     * @param message
+     * @param error
+     */
+    warn(message: string, error?: any): void;
+    isWarnEnabled(): boolean;
+    /**
+     * 错误日志
+     * @param message
+     * @param error
+     */
+    error(message: string, error?: any): void;
+    isErrorEnabled(): boolean;
+}>;
+export * from './config';
+export * from './level';
+export { setLogStore } from './store';

package/types/log/level.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 日志级别.
+ */
+export declare enum LogLevel {
+    DEBUG = "DEBUG",
+    INFO = "INFO",
+    WARN = "WARN",
+    ERROR = "ERROR"
+}
+export declare const LogLevelVals: Record<LogLevel, number>;
+/**
+ * 解析日志级别
+ * @param level
+ */
+export declare function parseLogLevel(level: string): LogLevel;

package/types/log/store.d.ts

@@ -0,0 +1,12 @@
+/**
+ * 日志存储函数
+ */
+export interface LogStore {
+    (log: string): void;
+}
+/**
+ * 设置日志存储.
+ * @param store
+ */
+export declare function setLogStore(store: LogStore): void;
+export declare function getLogStore(): LogStore | undefined;

package/types/mongodb/collection.d.ts

@@ -0,0 +1,25 @@
+/**
+ * mogodb 集合信息
+ *
+ * <T> 数据类型，不能包含有 _id 字段，主键字段名称固定，不可以设置
+ */
+export interface MongoCollection<T> {
+    /**
+     * 集合名称.
+     */
+    collectionName: string;
+    /**
+     * 创建时间字段信息,设置后在创建时会自动更新该字段
+     */
+    createdDate?: {
+        field: keyof T;
+        type: 'number' | 'date';
+    };
+    /**
+     * 更新时间字段信息，设置后在更新记录时会自动维护该字段
+     */
+    updatedDate?: {
+        field: keyof T;
+        type: 'number' | 'date';
+    };
+}

package/types/mongodb/config.d.ts

@@ -0,0 +1,45 @@
+import { ValidationOpts } from '../validation';
+/**
+ * MongoDB 配置.
+ */
+export interface MongoDBConfig {
+    /**
+     * 连接地址.
+     * 示例：mongodb+srv://<user>:<password>@<cluster-url>?retryWrites=true&writeConcern=majority
+     */
+    uri: string;
+    /** The maximum number of connections in the connection pool. */
+    maxPoolSize: number;
+    /** The minimum number of connections in the connection pool. */
+    minPoolSize: number;
+    /** The maximum number of connections that may be in the process of being established concurrently by the connection pool. */
+    maxConnecting: number;
+    /** The maximum number of milliseconds that a connection can remain idle in the pool before being removed and closed. */
+    maxIdleTimeMS: number;
+    /** The maximum time in milliseconds that a thread can wait for a connection to become available. */
+    waitQueueTimeoutMS: number;
+    /**
+     * 开启慢查询警告，默认开启
+     */
+    slowQueryWarn: boolean;
+    /**
+     * 慢查询毫秒数，默认 200
+     */
+    slowQueryMs: number;
+    /**
+     *事务超时时间，单位毫秒，默认 5000，设置为0的值表示不限制
+     */
+    transactionTimeout: number;
+    /**
+     * 事务严格模式
+     */
+    transactionStrict: boolean;
+}
+/**
+ * 默认配置.
+ */
+export declare const defaultConfig: MongoDBConfig;
+/**
+ * 配置校验
+ */
+export declare const configValidation: ValidationOpts<MongoDBConfig>;

package/types/mongodb/doc.d.ts

@@ -0,0 +1,11 @@
+import { ObjectId } from 'mongodb';
+/**
+ * 文档 id
+ */
+export type MongoDocId = string | ObjectId;
+/**
+ * 带 id 的文档。<T> 是自定义的集合类型，不包含主键字段。
+ */
+export type MongoDocWithId<T> = T & {
+    _id: MongoDocId;
+};

package/types/mongodb/exception.d.ts

@@ -0,0 +1,7 @@
+/**
+ * MongoDB 异常.
+ */
+export declare class MongoDBException extends Error {
+    readonly message: string;
+    constructor(message: string);
+}