[RMBWEB-2780] Support for structured validation results

dumi/docs/concepts/state/index.md

@@ -29,6 +29,8 @@ export interface IState<V> {
   error: ValidationError
   /** The state's own error info, regardless of child states. */
   ownError: ValidationError
+  /** The state's own error info, includes ValidationErrorObject error type, regardless of child states. */
+  rawError: ValidationRawError
   /** Append validator(s). */
   withValidator(...validators: Array<Validator<V>>): this
   /** Fire a validation behavior imperatively. */
@@ -67,11 +69,11 @@ Validation is the process of validating user input values.
 Validation is important for cases like:
 
 * When user inputs, we display error tips if validation not passed, so users see that and correct the input
-* Before form submiiting, we check if all value is valid, so invalid requests to the server can be avoided
+* Before form submitting, we check if all value is valid, so invalid requests to the server can be avoided
 
 That's why validation should provide such features:
 
-* It should run automatically, when users changed the value, or when some other data change influcend the value validity
+* It should run automatically, when users changed the value, or when some other data change influenced the value validity
 * It should produce details such as a meaningful message, so users can get friendly hint
 
 With formstate-x, we define validators and append them to states with `withValidator`. formstate-x will do validation for us. Through `validateStatus` & `error`, we can access the validate status and result.
@@ -97,6 +99,10 @@ States will not be auto-validated until it becomes **activated**. And they will
 
 `ownError` & `hasOwnError` are special fields especially for composed states. You can check details about them in issue [#71](https://github.com/qiniu/formstate-x/issues/71).
 
+### Raw Error
+
+The state's own raw error info, regardless of child states. The difference compared to `ownError` is that it contains the type of `ValidationErrorObject`. You can check details about them in issue [#82](https://github.com/qiniu/formstate-x/issues/82).
+
 ### Disable State
 
 You may find that we defined method `disableWhen` to configure when a state should be disabled. It is useful in some specific cases. You can check details in section [Disable State](/guide/advanced#disable-state).

dumi/docs/concepts/validator/index.md

@@ -32,6 +32,10 @@ export type ValidationResult =
   | null
   | undefined
   | false
+  | ValidationErrorObject
+
+/** Object type validation result. */
+export type ValidationErrorObject = { message: string }
 
 /** Return value of validator. */
 export type ValidatorReturned = 

src/adapter/v2.spec.ts

@@ -639,7 +639,7 @@ describe('toV2', () => {
       const validateRet = state.validate()
       expect(state._validateStatus).toBe(v3.ValidateStatus.Validating)
       const validated = await validateRet
-      expect(validated).toEqual({ hasError: true, error: 'empty' })
+      expect(validated).toEqual({ hasError: true, error: 'empty', rawError: 'empty' })
       expect(state._validateStatus).toBe(v3.ValidateStatus.Validated)
     })
 
@@ -705,6 +705,7 @@ describe('toV2', () => {
       touched = false
       ownError = undefined
       error = undefined
+      rawError = undefined
       activated = false
       validateStatus = v3.ValidateStatus.NotValidated
       async validate() {

src/adapter/v2.ts

@@ -3,6 +3,7 @@ import * as v2 from 'formstate-x-v2'
 import { BaseState } from '../state'
 import * as v3 from '..'
 import Disposable from '../disposable'
+import { isPromiseLike, normalizeError, normalizeRawError } from '../utils'
 
 interface IV3StateFromV2<T extends v2.ComposibleValidatable<unknown, V>, V> extends v3.IState<V> {
   /** The original ([email protected]) state */
@@ -27,6 +28,7 @@ class Upgrader<T extends v2.ComposibleValidatable<unknown, V>, V> extends BaseSt
   @computed get ownError() {
     return getV3OwnError(this.stateV2)
   }
+  @computed get rawError() { return this.ownError }
   @computed get error() { return this.stateV2.error }
   @computed get activated() { return this.stateV2._activated }
   @computed get validateStatus() {
@@ -47,7 +49,7 @@ class Upgrader<T extends v2.ComposibleValidatable<unknown, V>, V> extends BaseSt
       isV2FieldState(this.stateV2)
       || isV2FormState(this.stateV2)
     ) {
-      this.stateV2.validators(...validators)
+      this.stateV2.validators(...portV2Validators(...validators))
       return this
     }
     throwNotSupported()
@@ -64,7 +66,23 @@ class Upgrader<T extends v2.ComposibleValidatable<unknown, V>, V> extends BaseSt
   }
 }
 
-/** Convets [email protected] state to [email protected] state */
+function portV2Validators<V>(...validators: Array<v3.Validator<V>>): Array<v2.Validator<V>> {
+  const normalizeRet = (v: any) => (
+    normalizeError(normalizeRawError(v))
+  )
+  return validators.map(validator => {
+    return (value: V) => {
+      const returned = validator(value)
+      if (isPromiseLike(returned)) {
+        return returned.then(normalizeRet)
+      } else {
+        return normalizeRet(returned)
+      }
+    }
+  })
+}
+
+/** Converts [email protected] state to [email protected] state */
 export function fromV2<T extends v2.ComposibleValidatable<unknown, unknown>>(stateV2: T): IV3StateFromV2<T, T['value']> {
   return new Upgrader(stateV2)
 }

src/debouncedState.spec.ts

@@ -175,6 +175,20 @@ describe('DebouncedState validation', () => {
     expect(state.error).toBe('empty')
     expect(state.ownError).toBe('empty')
   })
+
+  it('should work well with resolved error object', async () => {
+    const fooState = new FieldState('')
+    const formState = new FormState({ foo: fooState })
+    const state = new DebouncedState(formState, defaultDelay).withValidator(
+      () => ({ message: 'mock msg' })
+    )
+
+    await state.validate()
+    expect(state.hasError).toBe(true)
+    expect(state.ownError).toBe('mock msg')
+    expect(state.error).toBe('mock msg')
+    expect(state.rawError).toEqual({ message: 'mock msg' })
+  })
 })
 
 function createFieldState<T>(initialValue: T, delay = defaultDelay) {
@@ -607,4 +621,18 @@ describe('DebouncedFieldState validation', () => {
     expect(validator).toBeCalled()
     expect(state.validateStatus).toBe(ValidateStatus.Validated)
   })
+
+  it('should work well with resolved error object', async () => {
+    const state = createFieldState(0).withValidator(
+      _ => ({ message: 'empty' })
+    )
+
+    state.validate()
+
+    await delay()
+    expect(state.hasError).toBe(true)
+    expect(state.error).toBe('empty')
+    expect(state.ownError).toBe('empty')
+    expect(state.rawError).toEqual({ message: 'empty' })
+  })
 })

src/debouncedState.ts

@@ -2,7 +2,7 @@ import { action, computed, makeObservable, observable, override, reaction } from
 import { FieldState } from './fieldState'
 import { ValidatableState } from './state'
 import { IState, ValidateStatus, ValueOf } from './types'
-import { debounce } from './utils'
+import { debounce, normalizeError } from './utils'
 
 const defaultDelay = 200 // ms
 
@@ -52,7 +52,7 @@ export class DebouncedState<S extends IState<V>, V = ValueOf<S>> extends Validat
 
   @override override get ownError() {
     if (this.disabled) return undefined
-    if (this._error) return this._error
+    if (this._error) return normalizeError(this._error)
     return this.original.ownError
   }
 

src/fieldState.spec.ts

@@ -373,4 +373,31 @@ describe('FieldState validation', () => {
       assertType<string>(res.value)
     }
   })
+
+  describe('should work well with resolved error object', () => {
+    it('should work well with sync resolved', async () => {
+      const state = new FieldState('').withValidator(
+        _ => ({ message: 'error-object-msg'})
+      )
+
+      const res = await state.validate()
+      expect(state.hasError).toBe(true)
+      expect(state.error).toBe('error-object-msg')
+      expect(state.rawError).toEqual({ message: 'error-object-msg'})
+      expect(res).toEqual({ hasError: true, error: 'error-object-msg', rawError: { message: 'error-object-msg' }})
+    })
+
+    it('should work well with async resolved', async () => {
+      const state = new FieldState('').withValidator(
+        _ => null,
+        _ => delayValue({ message: 'error-object-msg' }, 100)
+      )
+
+      const res = await state.validate()
+      expect(state.hasError).toBe(true)
+      expect(state.error).toBe('error-object-msg')
+      expect(state.rawError).toEqual({ message: 'error-object-msg'})
+      expect(res).toEqual({ hasError: true, error: 'error-object-msg', rawError: { message: 'error-object-msg' }})
+    })
+  })
 })

src/formState.spec.ts

@@ -607,6 +607,59 @@ describe('FormState (mode: object) validation', () => {
       assertType<{ foo: string }>(res.value)
     }
   })
+
+  describe('should work well with resolved error object', () => {
+    it('should work well with mixed sync and async resolved error object', async () => {
+      const initialValue = { foo: '123', bar: '123' }
+      const state = new FormState({
+        foo: new FieldState(initialValue.foo),
+        bar: new FieldState(initialValue.bar)
+      }).withValidator(
+        ({ foo, bar }) => delayValue(foo === bar && { message: 'same' }),
+        ({ foo }) => foo === '' && { message: 'empty' }
+      )
+      state.validate()
+
+      await delay()
+      expect(state.hasError).toBe(true)
+      expect(state.error).toBe('same')
+      expect(state.ownError).toBe('same')
+      expect(state.rawError).toEqual({ message: 'same' })
+
+      state.$.foo.onChange('')
+
+      await delay()
+      expect(state.hasError).toBe(true)
+      expect(state.error).toBe('empty')
+      expect(state.ownError).toBe('empty')
+      expect(state.rawError).toEqual({ message: 'empty' })
+
+      state.$.foo.onChange('456')
+
+      await delay()
+      expect(state.hasError).toBe(false)
+      expect(state.error).toBeUndefined()
+      expect(state.rawError).toBeUndefined()
+    })
+
+    it('should work well with child states resolved error object', async () => {
+      const state = new FormState({
+        foo: new FieldState(''),
+        bar: new FieldState('').withValidator(
+          v => v === '' && { message: 'empty' }
+        )
+      })
+      state.validate()
+      await delay()
+      expect(state.hasError).toBe(true)
+      expect(state.error).toBe('empty')
+      expect(state.rawError).toBeUndefined()
+      expect(state.ownError).toBeUndefined()
+      expect(state.$.bar.hasError).toBe(true)
+      expect(state.$.bar.error).toBe('empty')
+      expect(state.$.bar.rawError).toEqual({ message: 'empty' })
+    })
+  })
 })
 
 describe('FormState (mode: array)', () => {

src/state.ts

@@ -1,7 +1,7 @@
 import { action, autorun, computed, makeObservable, observable, when } from 'mobx'
-import { ValidationError, IState, Validation, ValidateResult, ValidateStatus, Validator } from './types'
+import { ValidationRawError, ValidationError, IState, Validation, ValidateResult, ValidateStatus, Validator } from './types'
 import Disposable from './disposable'
-import { applyValidators, isValid, isPromiseLike } from './utils'
+import { applyValidators, isPromiseLike, normalizeRawError, normalizeError } from './utils'
 
 /** Extraction for some basic features of State */
 export abstract class BaseState extends Disposable implements Pick<
@@ -56,10 +56,14 @@ export abstract class ValidatableState<V> extends BaseState implements IState<V>
   /**
    * The original error info of validation.
    */
-  @observable protected _error: ValidationError
+  @observable protected _error: ValidationRawError
+
+  @computed get rawError() {
+    return  this.disabled ? undefined : this._error
+  }
 
   @computed get ownError() {
-    return this.disabled ? undefined : this._error
+    return normalizeError(this.rawError)
   }
 
   @computed get error() {
@@ -69,7 +73,7 @@ export abstract class ValidatableState<V> extends BaseState implements IState<V>
   /**
    * Set error info.
    */
-  @action setError(error: ValidationError) {
+  @action setError(error: ValidationRawError) {
     this._error = error
   }
 
@@ -104,14 +108,14 @@ export abstract class ValidatableState<V> extends BaseState implements IState<V>
     action('end-validation', () => {
       this.validation = undefined
       this._validateStatus = ValidateStatus.Validated
-      this.setError(isValid(result) ? undefined : result)
+      this.setError(normalizeRawError(result))
     })()
   }
 
   @computed protected get validateResult(): ValidateResult<V> {
     return (
       this.error
-      ? { hasError: true, error: this.error } as const
+      ? { hasError: true, error: this.error, rawError: this.rawError } as const
       : { hasError: false, value: this.value } as const
     )
   }

src/transformedState.spec.ts

@@ -389,6 +389,19 @@ describe('TransformedState (for FieldState) validation', () => {
     expect(state.ownError).toBe('non positive')
   })
 
+  it('should work well with resolved error object', async () => {
+    const state = createNumState(0).withValidator(
+      _ => ({ message: 'empty' })
+    )
+
+    state.validate()
+
+    await delay()
+    expect(state.hasError).toBe(true)
+    expect(state.error).toBe('empty')
+    expect(state.ownError).toBe('empty')
+    expect(state.rawError).toEqual({ message: 'empty' })
+  })
 })
 
 interface Host {
@@ -738,4 +751,18 @@ describe('TransformedState (for FormState) validation', () => {
     expect(state.hasOwnError).toBe(false)
     expect(state.ownError).toBeUndefined()
   })
+
+  it('should work well with resolved error object', async () => {
+    const state = createHostState('127.0.0.1').withValidator(
+      _ => ({ message: 'mock msg'})
+    )
+
+    state.validate()
+
+    await delay()
+    expect(state.hasError).toBe(true)
+    expect(state.error).toBe('mock msg')
+    expect(state.ownError).toBe('mock msg')
+    expect(state.rawError).toEqual({ message: 'mock msg' })
+  })
 })

src/transformedState.ts

@@ -27,6 +27,10 @@ export class TransformedState<S extends IState<$V>, V, $V = ValueOf<S>> extends
     return this.$.ownError
   }
 
+  @computed get rawError() {
+    return this.$.rawError
+  }
+
   @computed get error() {
     return this.$.error
   }

src/types.ts

@@ -4,6 +4,7 @@ export type ValidationResult =
   | null
   | undefined
   | false
+  | ValidationErrorObject
 
 /** Return value of validator. */
 export type ValidatorReturned = 
@@ -18,9 +19,11 @@ export type Validation<TValue> = {
   returned: ValidatorReturned // result of applying validators
 }
 
+export type ValidationErrorObject = { message: string }
 export type ValidationError = string | undefined
+export type ValidationRawError = ValidationErrorObject | ValidationError
 
-export type ValidateResultWithError = { hasError: true, error: NonNullable<ValidationError> }
+export type ValidateResultWithError = { hasError: true, rawError: ValidationRawError, error: NonNullable<ValidationError> }
 export type ValidateResultWithValue<T> = { hasError: false, value: T }
 export type ValidateResult<T> = ValidateResultWithError | ValidateResultWithValue<T>
 
@@ -36,6 +39,8 @@ export interface IState<V = unknown> {
   hasError: boolean
   /** The state's own error info, regardless of child states. */
   ownError: ValidationError
+  /** Ihe state's own error info, includes ValidationErrorObject error type, regardless of child states. */
+  rawError: ValidationRawError
   /** If the state contains its own error info. */
   hasOwnError: boolean
   /** If activated (with auto-validation). */