wok-server 0.5.0 → 0.6.0

package/src/mysql/table-info.ts

@@ -0,0 +1,41 @@
+import { notBlank, ValidationOpts } from '../validation'
+
+/**
+ * 表信息. 表的字段分为三个部分：主键、普通列、时间列，分别对应的属性是：id、columns
+ * 和 createDate 还有 updatedDate，这三部分配置的字段名称不允许有重叠，否则会产生错误.
+ */
+export interface Table<T> {
+  /**
+   * 表名.
+   */
+  tableName: string
+  /**
+   * id 字段名称.
+   */
+  id: keyof T
+  /**
+   * 列字段名称.只有配置了名称的字段才会参与数据库的查询与更新，没有配置的其它字段可作其它用途。
+   * 注意：columns 配置的字段不能和 id 或更新时间和创建时间重叠，否则在更新时产生错误，将数据改错。
+   * 程序本身是不会做检查的，编写的时候必须要注意。
+   */
+  columns: Array<keyof T>
+  /**
+   * 创建时间字段信息.
+   */
+  createdDate?: {
+    column: keyof T
+    type: 'number' | 'date'
+  }
+  /**
+   * 更新时间字段信息.
+   */
+  updatedDate?: {
+    column: keyof T
+    type: 'number' | 'date'
+  }
+}
+
+export const tableValidation: ValidationOpts<Table<any>> = {
+  tableName: [notBlank('表名不能为空')],
+  id: [notBlank('id 不能为空')]
+}

package/src/task/daily.ts

@@ -0,0 +1,70 @@
+import { max, min, notNull, validate } from '../validation'
+import { Task, TaskController, execTask } from './task'
+
+/**
+ * 每日任务.
+ * @param hours 时
+ * @param minutes 分
+ * @param task 要执行的任务
+ * @param timeout 任务超时时间，单位毫秒
+ * @returns
+ */
+export function scheduleDailyTask(
+  hours: number,
+  minutes: number,
+  task: Task,
+  timeout?: number
+): TaskController {
+  // 校验
+  validate(
+    { hours, minutes },
+    {
+      hours: [notNull(), min(0), max(23)],
+      minutes: [notNull(), min(0), max(59)]
+    }
+  )
+  const taskController = new TaskController()
+  const delay = dailyTaskDelay(hours, minutes)
+  setTimeout(() => exec(hours, minutes, task, taskController, timeout), delay)
+  return taskController
+}
+/**
+ * 计算到下次指定时间点的延迟
+ * @param hours
+ * @param minutes
+ */
+export function dailyTaskDelay(hours: number, minutes: number): number {
+  const now = new Date()
+  let todayTime = new Date()
+  todayTime.setHours(hours)
+  todayTime.setMinutes(minutes)
+  todayTime.setSeconds(0)
+  todayTime.setMilliseconds(0)
+  // 如果今天还没有到指定的点，今天就执行，否则明天执行
+  if (todayTime > now) {
+    return todayTime.getTime() - now.getTime()
+  }
+  // 明天时间
+  const oneDayMilliseconds = 1000 * 3600 * 24
+  const tomorrowTime = todayTime.getTime() + oneDayMilliseconds
+  return tomorrowTime - now.getTime()
+}
+
+function exec(
+  hours: number,
+  minutes: number,
+  task: Task,
+  controller: TaskController,
+  timeout?: number
+) {
+  Promise.resolve()
+    .then(async () => {
+      if (controller.isStopped()) {
+        return
+      }
+      await execTask(task, timeout)
+      const delay = dailyTaskDelay(hours, minutes)
+      setTimeout(() => exec(hours, minutes, task, controller), delay)
+    })
+    .catch(console.error)
+}

package/src/task/fixed-delay.ts

@@ -0,0 +1,45 @@
+import { getLockManager } from '../lock'
+import { getLogger } from '../log'
+import { max, min, notNull, validate } from '../validation'
+import { Task, TaskController, execTask } from './task'
+
+/**
+ * 固定延迟执行任务
+ * @param initialDelay  第一次执行延迟的时间，单位秒
+ * @param delay 每次的延迟时间，单位秒
+ * @param task 任务
+ * @param timeout 任务超时时间，单位毫秒
+ */
+export function scheduleWithFixedDelay(
+  initialDelay: number,
+  delay: number,
+  task: Task,
+  timeout?: number
+): TaskController {
+  validate(
+    { initialDelay, delay },
+    {
+      initialDelay: [notNull(), min(0), max(3600 * 24)],
+      delay: [notNull(), min(1), max(3600 * 24)]
+    }
+  )
+  const controller = new TaskController()
+  setTimeout(() => exec(delay, task, controller, timeout), initialDelay * 1000)
+  return controller
+}
+
+function exec(delay: number, task: Task, controller: TaskController, timeout?: number) {
+  Promise.resolve()
+    .then(async () => {
+      if (controller.isStopped()) {
+        return
+      }
+      await execTask(task, timeout)
+      // 下次执行
+      setTimeout(() => exec(delay, task, controller), delay * 1000)
+    })
+    .catch(e => {
+      getLogger().error(`EXEC TASK ERROR: ${task.name}`, e)
+    })
+    .catch(console.error)
+}

package/src/task/fixed-rate.ts

@@ -0,0 +1,49 @@
+import { getLogger } from '../log'
+import { max, min, notNull, validate } from '../validation'
+import { Task, TaskController, execTask } from './task'
+
+/**
+ * 固定延迟执行任务
+ * @param initialDelay  第一次执行延迟的时间，单位秒
+ * @param period 每次的延迟时间，单位秒
+ * @param task 任务
+ * @param timeout 任务超时时间，单位毫秒
+ */
+export function scheduleWithFixedRate(
+  initialDelay: number,
+  period: number,
+  task: Task,
+  timeout?: number
+): TaskController {
+  validate(
+    { initialDelay, period },
+    {
+      initialDelay: [notNull(), min(0), max(3600 * 24)],
+      period: [notNull(), min(1), max(3600 * 24)]
+    }
+  )
+
+  const taskController = new TaskController()
+  setTimeout(() => exec(period, task, taskController, timeout), initialDelay * 1000)
+  return taskController
+}
+
+function exec(fixedDelay: number, task: Task, controller: TaskController, timeout?: number) {
+  Promise.resolve()
+    .then(async () => {
+      if (controller.isStopped()) {
+        return
+      }
+      const res = await execTask(task, timeout)
+      // 下次执行
+      let delay = res.start + fixedDelay * 1000 - new Date().getTime()
+      if (delay < 0) {
+        delay = 0
+      }
+      setTimeout(() => exec(fixedDelay, task, controller), delay)
+    })
+    .catch(e => {
+      getLogger().error(`EXEC TASK ERROR: ${task.name}`, e)
+    })
+    .catch(console.error)
+}

package/src/task/index.ts

@@ -0,0 +1,4 @@
+export { Task, TaskController } from './task'
+export * from './fixed-delay'
+export * from './fixed-rate'
+export * from './daily'

package/src/task/task.ts

@@ -0,0 +1,70 @@
+import { getLogger } from '../log'
+
+/**
+ * 任务.
+ */
+export interface Task {
+  /**
+   * 任务的名称，用于跟踪任务的执行情况，定位错误.
+   * 当任务执行时间过长或任务失败时，相关的错误提示信息会显示名称，以便于排查.
+   */
+  name: string
+  /**
+   * 任务运行.
+   * @returns
+   */
+  run: () => Promise<void>
+}
+
+/**
+ * 任务控制器
+ */
+export class TaskController {
+  #stopped = false
+  isStopped() {
+    return this.#stopped
+  }
+
+  stop() {
+    this.#stopped = true
+  }
+}
+
+/**
+ * 任务执行，封装任务执行过程中的一些通用信息输出和异常控制.
+ * @param task
+ * @param timeout 任务超时时间，单位毫秒
+ * @returns
+ */
+export async function execTask(
+  task: Task,
+  timeout?: number
+): Promise<{ start: number; cost: number; end: number }> {
+  const start = new Date().getTime()
+  try {
+    getLogger().debug(`START TASK：${task.name}`)
+    // 支持任务超时设置
+    if (timeout && timeout > 0) {
+      await Promise.race([
+        task.run(),
+        new Promise<void>((_, reject) => {
+          setTimeout(() => {
+            reject('The task has timed out.')
+          }, timeout)
+        })
+      ])
+    } else {
+      await task.run()
+    }
+  } catch (e) {
+    getLogger().error(`TASK ERROR: ${task.name}`, e)
+  }
+  const end = Date.now()
+  const cost = end - start
+  if (cost > 1000 * 60 * 5) {
+    getLogger().warn(`Task "${task.name}" takes too long ，cost ${cost}ms`)
+  } else {
+    getLogger().debug(`Task "${task.name}" has finished, taking a total of ${cost} milliseconds.`)
+  }
+  return { start, cost, end }
+}

package/src/validation/exception.ts

@@ -0,0 +1,27 @@
+/**
+ * 校验异常.
+ */
+export class ValidationException extends Error {
+  constructor(
+    /**
+     * 异常信息，如 “不能为空” 之类的.
+     */
+    readonly errMsg: string,
+    /**
+     * 校验器名称，如 length 、notNull 之类的.
+     */
+    readonly validator: string,
+    /**
+     * 校验出错的路径.
+     */
+    readonly propertyPath: string,
+    /**
+     * 值
+     */
+    readonly val: any
+  ) {
+    super(
+      `Field "${propertyPath}" failed to validate by validator ${validator} ，value：${val}，info：${errMsg}`
+    )
+  }
+}

package/src/validation/index.ts

@@ -0,0 +1,61 @@
+import { ValidationException } from './exception'
+/**
+ * 校验结果。message：错误信息，反馈给调用处；validator 校验器名称，用于记录错误信息来自哪个校验器，
+ * 以便于程序在出错时知道信息来自哪里。
+ */
+export type ValidationResult =
+  | { ok: true }
+  | {
+      ok: false
+      message: string
+      validator: string
+      /**
+       * 如果校验的是层级深的对象，内部的属性发生了错误，可用于标记属性的路径
+       */
+      propPath?: string[]
+    }
+/**
+ * 校验器.
+ */
+export type PropValidator<T> = (val: T) => ValidationResult
+
+/**
+ * 对象的校验选项
+ */
+export type ValidationOpts<T> = Partial<{ [key in keyof T]: PropValidator<T[key]>[] }>
+
+/**
+ * 校验对象.
+ * @param obj
+ */
+export function validate<T>(obj: T, opts: ValidationOpts<T>) {
+  for (const entry of Object.entries(opts)) {
+    const [prop, validators] = entry
+    const val = obj[prop as keyof T]
+    for (const validator of validators as PropValidator<any>[]) {
+      const result = validator(val)
+      if (!result.ok) {
+        const propPath = [prop]
+        if (result.propPath) {
+          propPath.push(...result.propPath)
+        }
+        const fullPath = propPath
+          .map((prop, idx) => {
+            if (idx === 0) {
+              return prop
+            }
+            if (prop.startsWith('[') && prop.endsWith(']')) {
+              return prop
+            }
+            return '.' + prop
+          })
+          .join('')
+        throw new ValidationException(result.message, result.validator, fullPath, val)
+      }
+    }
+  }
+}
+
+// 导出
+export * from './exception'
+export * from './validator'

package/src/validation/validator/array.ts

@@ -0,0 +1,32 @@
+import { PropValidator } from '..'
+import { getI18n } from '../../i18n'
+
+/**
+ * 校验数组的条目.
+ */
+export function array<T>(opts: PropValidator<T>[]): PropValidator<T[] | undefined> {
+  const validator = 'array'
+  return val => {
+    if (!val) {
+      return { ok: true }
+    }
+    if (!Array.isArray(val)) {
+      return { ok: false, validator, message: getI18n().buildMsg('validate-err-array') }
+    }
+    // 条目处理
+    for (let i = 0; i < val.length; i++) {
+      const item = val[i] as T
+      for (const validation of opts) {
+        const result = validation(item)
+        if (!result.ok) {
+          const propPath = [`[${i}]`]
+          if (result.propPath) {
+            propPath.push(...result.propPath)
+          }
+          return { ok: false, validator, message: result.message, propPath }
+        }
+      }
+    }
+    return { ok: true }
+  }
+}

package/src/validation/validator/enum.ts

@@ -0,0 +1,25 @@
+import { PropValidator } from '..'
+import { getI18n } from '../../i18n'
+/**
+ * 枚举，校验值必须是指定列表中的一个.
+ * @param list 支持的值列表，仅支持数字和字符串类型
+ * @param msg
+ * @returns
+ */
+export function enumerate<T>(list: (number | string)[], msg?: string): PropValidator<T> {
+  const validator = 'enumerate'
+  return val => {
+    if (!val) {
+      return { ok: true }
+    }
+    if (!list.some(item => item === val)) {
+      return {
+        ok: false,
+        validator,
+        // must be one of [1,2,3]
+        message: msg || getI18n().buildMsg('validate-err-enum', `[${list.join(',')}]`)
+      }
+    }
+    return { ok: true }
+  }
+}

package/src/validation/validator/index.ts

@@ -0,0 +1,11 @@
+export * from './not-null'
+export * from './not-blank'
+export * from './max'
+export * from './min'
+export * from './regexp'
+export * from './length'
+export * from './enum'
+export * from './array'
+export * from './plain-obj'
+export * from './max-length'
+export * from './min-length'

package/src/validation/validator/length.ts

@@ -0,0 +1,42 @@
+import { PropValidator } from '..'
+import { getI18n } from '../../i18n'
+
+/**
+ * length 校验，可用于字符串或数组.
+ * @returns
+ */
+export function length<T>(opts: {
+  min?: number
+  max?: number
+  message?: string
+}): PropValidator<T> {
+  const validator = 'length'
+  return val => {
+    // 不校验空
+    if (!val) {
+      return { ok: true }
+    }
+    if (typeof (val as any).length !== 'number') {
+      return { ok: false, validator, message: getI18n().buildMsg('validate-err-no-length') }
+    }
+    const { length } = val as any
+    if (typeof length !== 'number') {
+      return { ok: false, validator, message: getI18n().buildMsg('validate-err-length-not-number') }
+    }
+    if (typeof opts.min === 'number' && length < opts.min) {
+      return {
+        ok: false,
+        validator,
+        message: opts.message || getI18n().buildMsg('validate-err-min-length', `${opts.min}`)
+      }
+    }
+    if (typeof opts.max === 'number' && length > opts.max) {
+      return {
+        ok: false,
+        validator,
+        message: opts.message || getI18n().buildMsg('validate-err-max-length', `${opts.max}`)
+      }
+    }
+    return { ok: true }
+  }
+}

package/src/validation/validator/max-length.ts

@@ -0,0 +1,33 @@
+import { PropValidator } from '..'
+import { getI18n } from '../../i18n'
+
+/**
+ * 最大长度校验，可用于字符串或数组.
+ * @param maxLength
+ * @param message
+ * @returns
+ */
+export function maxLength<T>(maxLength: number, message?: string): PropValidator<T> {
+  const validator = 'maxLength'
+  return val => {
+    // 不校验空
+    if (!val) {
+      return { ok: true }
+    }
+    if (typeof (val as any).length !== 'number') {
+      return { ok: false, validator, message: getI18n().buildMsg('validate-err-no-length') }
+    }
+    const { length } = val as any
+    if (typeof length !== 'number') {
+      return { ok: false, validator, message: getI18n().buildMsg('validate-err-length-not-number') }
+    }
+    if (length > maxLength) {
+      return {
+        ok: false,
+        validator,
+        message: message || getI18n().buildMsg('validate-err-max-length', `${maxLength}`)
+      }
+    }
+    return { ok: true }
+  }
+}

package/src/validation/validator/max.ts

@@ -0,0 +1,26 @@
+import { PropValidator } from '..'
+import { getI18n } from '../../i18n'
+/**
+ * 最大值校验.
+ * @param max 最大值
+ * @param msg 错误消息
+ */
+export function max<T>(max: number, msg?: string): PropValidator<T> {
+  const validator = 'max'
+  return val => {
+    if (val == undefined || val === null) {
+      return { ok: true }
+    }
+    if (typeof val !== 'number') {
+      return { ok: false, validator, message: getI18n().buildMsg('validate-err-numer') }
+    }
+    if (val > max) {
+      return {
+        ok: false,
+        validator,
+        message: msg || getI18n().buildMsg('validate-err-max', `${max}`)
+      }
+    }
+    return { ok: true }
+  }
+}

package/src/validation/validator/min-length.ts

@@ -0,0 +1,31 @@
+import { PropValidator } from '..'
+import { getI18n } from '../../i18n'
+
+/**
+ * 最小长度校验，可用于字符串或数组.
+ * @returns
+ */
+export function minLength<T>(minLength: number, message?: string): PropValidator<T> {
+  const validator = 'minLength'
+  return val => {
+    // 不校验空
+    if (!val) {
+      return { ok: true }
+    }
+    if (typeof (val as any).length !== 'number') {
+      return { ok: false, validator, message: getI18n().buildMsg('validate-err-no-length') }
+    }
+    const { length } = val as any
+    if (typeof length !== 'number') {
+      return { ok: false, validator, message: getI18n().buildMsg('validate-err-length-not-number') }
+    }
+    if (length < minLength) {
+      return {
+        ok: false,
+        validator,
+        message: message || getI18n().buildMsg('validate-err-min-length', `${minLength}`)
+      }
+    }
+    return { ok: true }
+  }
+}

package/src/validation/validator/min.ts

@@ -0,0 +1,26 @@
+import { PropValidator } from '..'
+import { getI18n } from '../../i18n'
+/**
+ * 最小值校验.
+ * @param min 最小值
+ * @param msg 错误消息
+ */
+export function min<T>(min: number, msg?: string): PropValidator<T> {
+  const validator = 'min'
+  return val => {
+    if (val == undefined || val === null) {
+      return { ok: true }
+    }
+    if (typeof val !== 'number') {
+      return { ok: false, validator, message: getI18n().buildMsg('validate-err-numer') }
+    }
+    if (val < min) {
+      return {
+        ok: false,
+        validator,
+        message: msg || getI18n().buildMsg('validate-err-min', `${min}`)
+      }
+    }
+    return { ok: true }
+  }
+}

package/src/validation/validator/not-blank.ts

@@ -0,0 +1,31 @@
+import { PropValidator } from '..'
+import { getI18n } from '../../i18n'
+
+/**
+ * 字符串非空校验，以下的情况不会通过校验：undefined，null，非 string 类型，空白字符串.
+ * @param message
+ * @returns
+ */
+export function notBlank<T>(message?: string): PropValidator<T> {
+  const validator = 'notBlank'
+  return val => {
+    if (val === undefined || val === null) {
+      return {
+        ok: false,
+        validator,
+        message: message || getI18n().buildMsg('validate-err-empty')
+      }
+    }
+    if (typeof val !== 'string') {
+      return { ok: false, validator, message: getI18n().buildMsg('validate-err-string') }
+    }
+    if (!val.trim()) {
+      return {
+        ok: false,
+        validator,
+        message: message || getI18n().buildMsg('validate-err-empty')
+      }
+    }
+    return { ok: true }
+  }
+}

package/src/validation/validator/not-null.ts

@@ -0,0 +1,19 @@
+import { PropValidator } from '..'
+import { getI18n } from '../../i18n'
+
+/**
+ * 非空校验.
+ * @param message
+ */
+export function notNull<T>(message?: string): PropValidator<T> {
+  return val => {
+    if (val === null || val === undefined) {
+      return {
+        ok: false,
+        message: message || getI18n().buildMsg('validate-err-empty'),
+        validator: 'notNull'
+      }
+    }
+    return { ok: true }
+  }
+}

package/src/validation/validator/plain-obj.ts

@@ -0,0 +1,30 @@
+import { PropValidator, ValidationOpts } from '..'
+
+/**
+ * 普通对象校验.
+ * @param opts
+ * @returns
+ */
+export function plainObject<T>(opts: ValidationOpts<Exclude<T, undefined>>): PropValidator<T> {
+  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 as keyof T]
+      for (const validate of validators as PropValidator<any>[]) {
+        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 }
+  }
+}