feat(vae): 注释完善

fjc0k · Jun 6, 2024 · e054afd · e054afd
1 parent af0b19d
commit e054afd
Show file tree

Hide file tree

Showing 12 changed files with 219 additions and 0 deletions.
diff --git a/src/vae/VaeArraySchema.ts b/src/vae/VaeArraySchema.ts
@@ -29,6 +29,9 @@ export class VaeArraySchema<
     }
   }
 
+  /**
+   * 数组元素定义
+   */
   element(element: VaeArraySchemaElementOf<T>) {
     return this.check({
       fn: element,
@@ -37,6 +40,9 @@ export class VaeArraySchema<
     })
   }
 
+  /**
+   * 数组非空，即长度应大于 0
+   */
   nonempty(message: VaeLocaleMessage = VaeLocale.array.nonempty) {
     return this.check({
       fn: v => v.length > 0,
@@ -45,6 +51,9 @@ export class VaeArraySchema<
     })
   }
 
+  /**
+   * 数组最小长度
+   */
   min(value: number, message: VaeLocaleMessage = VaeLocale.array.min) {
     return this.check({
       fn: v => v.length >= value,
@@ -56,6 +65,9 @@ export class VaeArraySchema<
     })
   }
 
+  /**
+   * 数组最大长度
+   */
   max(value: number, message: VaeLocaleMessage = VaeLocale.array.max) {
     return this.check({
       fn: v => v.length <= value,
@@ -67,6 +79,9 @@ export class VaeArraySchema<
     })
   }
 
+  /**
+   * 数组固定长度
+   */
   length(value: number, message: VaeLocaleMessage = VaeLocale.array.length) {
     return this.check({
       fn: v => v.length === value,

diff --git a/src/vae/VaeBooleanSchema.ts b/src/vae/VaeBooleanSchema.ts
@@ -16,6 +16,9 @@ export class VaeBooleanSchema<
     })
   }
 
+  /**
+   * 应为 true
+   */
   true(message: VaeLocaleMessage = VaeLocale.boolean.true) {
     return this.check({
       fn: v => v === true,
@@ -24,6 +27,9 @@ export class VaeBooleanSchema<
     })
   }
 
+  /**
+   * 应为 false
+   */
   false(message: VaeLocaleMessage = VaeLocale.boolean.false) {
     return this.check({
       fn: v => v === false,

diff --git a/src/vae/VaeDateSchema.ts b/src/vae/VaeDateSchema.ts
@@ -16,6 +16,9 @@ export class VaeDateSchema<
     })
   }
 
+  /**
+   * 最小日期
+   */
   min(
     value: Date | string | number,
     message: VaeLocaleMessage = VaeLocale.date.min,
@@ -32,6 +35,9 @@ export class VaeDateSchema<
     })
   }
 
+  /**
+   * 最大日期
+   */
   max(
     value: Date | string | number,
     message: VaeLocaleMessage = VaeLocale.date.max,

diff --git a/src/vae/VaeError.ts b/src/vae/VaeError.ts
@@ -12,6 +12,9 @@ export class VaeError extends Error {
     super(VaeError.messageFromIssues(issues))
   }
 
+  /**
+   * 从问题里导出信息
+   */
   static messageFromIssues(issues: VaeIssue[]) {
     return issues.map(issue => issue.message).join('; ')
   }

diff --git a/src/vae/VaeIssue.ts b/src/vae/VaeIssue.ts
@@ -1,6 +1,12 @@
 import { VaeSchemaPath } from './VaeSchema'
 
 export type VaeIssue = {
+  /**
+   * issue 产生的路径
+   */
   path: VaeSchemaPath
+  /**
+   * issue 信息
+   */
   message: string
 }
diff --git a/src/vae/VaeLocale.ts b/src/vae/VaeLocale.ts
@@ -2,9 +2,21 @@ import { formatDate } from '../date'
 import { VaeSchemaPath } from './VaeSchema'
 
 export type VaeLocaleMessagePayload = {
+  /**
+   * 标签
+   */
   label?: string
+  /**
+   * 路径
+   */
   path: VaeSchemaPath
+  /**
+   * 值
+   */
   value: any
+  /**
+   * 参数
+   */
   params: Record<string, any>
 }
 

diff --git a/src/vae/VaeNumberSchema.ts b/src/vae/VaeNumberSchema.ts
@@ -16,6 +16,9 @@ export class VaeNumberSchema<
     }).transform(toNumber as any)
   }
 
+  /**
+   * 最小值
+   */
   min(value: number, message: VaeLocaleMessage = VaeLocale.number.min) {
     return this.check({
       fn: v => v >= value,
@@ -27,6 +30,9 @@ export class VaeNumberSchema<
     })
   }
 
+  /**
+   * 最大值
+   */
   max(value: number, message: VaeLocaleMessage = VaeLocale.number.max) {
     return this.check({
       fn: v => v <= value,
@@ -38,6 +44,9 @@ export class VaeNumberSchema<
     })
   }
 
+  /**
+   * 小于
+   */
   lessThan(
     value: number,
     message: VaeLocaleMessage = VaeLocale.number.lessThan,
@@ -52,6 +61,9 @@ export class VaeNumberSchema<
     })
   }
 
+  /**
+   * 大于
+   */
   moreThan(
     value: number,
     message: VaeLocaleMessage = VaeLocale.number.moreThan,
@@ -66,6 +78,9 @@ export class VaeNumberSchema<
     })
   }
 
+  /**
+   * 整数，即 -100, -1, 0, 1, 2, 100, ...
+   */
   integer(message: VaeLocaleMessage = VaeLocale.number.integer) {
     return this.check({
       fn: isInteger,
@@ -74,6 +89,9 @@ export class VaeNumberSchema<
     })
   }
 
+  /**
+   * 正数，即 0.01, 0.1, 1, 2, 3, ...
+   */
   positive(message: VaeLocaleMessage = VaeLocale.number.positive) {
     return this.check({
       fn: v => v > 0,
@@ -82,6 +100,9 @@ export class VaeNumberSchema<
     })
   }
 
+  /**
+   * 非正数，即 0, -0.01, -1, -100, ...
+   */
   nonpositive(message: VaeLocaleMessage = VaeLocale.number.nonpositive) {
     return this.check({
       fn: v => v <= 0,
@@ -90,6 +111,9 @@ export class VaeNumberSchema<
     })
   }
 
+  /**
+   * 负数，即 -0.01, -1, -100, ...
+   */
   negative(message: VaeLocaleMessage = VaeLocale.number.negative) {
     return this.check({
       fn: v => v < 0,
@@ -98,6 +122,9 @@ export class VaeNumberSchema<
     })
   }
 
+  /**
+   * 非负数，即 0, 0.01, 0.1, 1, 2.1, 100, ...
+   */
   nonnegative(message: VaeLocaleMessage = VaeLocale.number.nonnegative) {
     return this.check({
       fn: v => v >= 0,
@@ -106,6 +133,9 @@ export class VaeNumberSchema<
     })
   }
 
+  /**
+   * 正整数，即 1, 2, 3, 4, 5, ...
+   */
   positiveInteger(
     message: VaeLocaleMessage = VaeLocale.number.positiveInteger,
   ) {
@@ -116,6 +146,9 @@ export class VaeNumberSchema<
     })
   }
 
+  /**
+   * ID，即正整数，即 1, 2, 3, 4, 5, ...
+   */
   id(message: VaeLocaleMessage = VaeLocale.number.positiveInteger) {
     return this.positiveInteger(message)
   }

diff --git a/src/vae/VaeObjectSchema.ts b/src/vae/VaeObjectSchema.ts
@@ -36,6 +36,9 @@ export class VaeObjectSchema<
     }
   }
 
+  /**
+   * 对象定义
+   */
   shape(shape: VaeObjectSchemaShapeOf<T>) {
     const keys = Object.keys(shape)
     this._options.objectKeys = keys
@@ -50,6 +53,9 @@ export class VaeObjectSchema<
     return this
   }
 
+  /**
+   * 原地挑选给定字段
+   */
   pickFields<K extends keyof T>(keys: K[]): VaeObjectSchema<Pick<T, K>> {
     this._options.processors = this._options.processors.filter(item =>
       typeof item === 'object' && startsWith(item.tag, 'field_')
@@ -63,6 +69,9 @@ export class VaeObjectSchema<
     return this as any
   }
 
+  /**
+   * 原地剔除给定字段
+   */
   omitFields<K extends keyof T>(keys: K[]): VaeObjectSchema<Omit<T, K>> {
     this._options.processors = this._options.processors.filter(item =>
       typeof item === 'object' && startsWith(item.tag, 'field_')
@@ -73,7 +82,13 @@ export class VaeObjectSchema<
     return this as any
   }
 
+  /**
+   * 原地将给定字段设为可选
+   */
   optionalFields<K extends keyof T>(keys: K[]): VaeObjectSchema<PartialBy<T, K>>
+  /**
+   * 原地将所有字段设为可选
+   */
   optionalFields(): VaeObjectSchema<Partial<T>>
   optionalFields(keys?: string[]): any {
     this._options.processors.forEach(item => {
@@ -88,9 +103,15 @@ export class VaeObjectSchema<
     return this
   }
 
+  /**
+   * 原地将给定字段设为必填
+   */
   requiredFields<K extends keyof T>(
     keys: K[],
   ): VaeObjectSchema<RequiredBy<T, K>>
+  /**
+   * 原地将所有字段设为必填
+   */
   requiredFields(): VaeObjectSchema<Required<T>>
   requiredFields(keys?: string[]): any {
     this._options.processors.forEach(item => {
@@ -105,9 +126,15 @@ export class VaeObjectSchema<
     return this
   }
 
+  /**
+   * 返回给定字段的定义
+   */
   shapeOfFields<K extends keyof T>(
     keys: K[],
   ): VaeObjectSchemaShapeOf<Pick<T, K>>
+  /**
+   * 返回全部字段的定义
+   */
   shapeOfFields(): VaeObjectSchemaShapeOf<T>
   shapeOfFields(keys?: string[]) {
     const shape: Record<any, any> = {}
@@ -123,6 +150,9 @@ export class VaeObjectSchema<
     return shape
   }
 
+  /**
+   * 给定字段中至少有一个必填
+   */
   requiredFieldsAtLeastOne<K extends keyof T>(
     keys: K[],
     message: VaeLocaleMessage = VaeLocale.object.requiredFieldsAtLeastOne,