Validator

Defined in: validator.ts:86, validator.ts:588

Validator for handling synchronous and asynchronous validations

Supports both sync and async validation handlers
Tracks validation state (isValidating)
Provides error access by key path
Supports nested validators

Types

AsyncHandler

AsyncHandler<T, Expr> = (expr: Expr, builder: ValidationErrorMapBuilder<T>, abortSignal: AbortSignal) => Promise<void>

Defined in: validator.ts:596

Async handler

Parameters

expr

Expr

The expression observed

builder

ValidationErrorMapBuilder<T>

The builder to build the errors

abortSignal

AbortSignal

The abort signal

Returns

Promise<void>

HandlerOptions

HandlerOptions<Expr> = object

Defined in: validator.ts:614

Handler options

Type Parameters

Expr

Expr = unknown

delayMs?

optional delayMs?: number

Defined in: validator.ts:626

Throttle reaction. [milliseconds]

Default

equals?

optional equals?: IEqualsComparer<Expr>

Defined in: validator.ts:632

The equality comparer for the expression.

Only effective for async handlers.

initialRun?

optional initialRun?: boolean

Defined in: validator.ts:620

Whether to run the handler immediately

Default

true

InstantHandler

InstantHandler<T> = (builder: ValidationErrorMapBuilder<T>) => void

Defined in: validator.ts:612

Instant handler

Parameters

builder

ValidationErrorMapBuilder<T>

The builder to build the errors

Returns

void

SyncHandler

SyncHandler<T> = (builder: ValidationErrorMapBuilder<T>) => void

Defined in: validator.ts:606

Sync handler

Parameters

builder

ValidationErrorMapBuilder<T>

The builder to build the errors

Returns

void

Static Members

defaultDelayMs

static defaultDelayMs: number = 100

Defined in: validator.ts:87

get()

static get<T>(target): Validator<T>

Defined in: validator.ts:108

Get a validator instance for the target object.

Type Parameters

T

T extends object

Parameters

target

T

Returns

Validator<T>

Remarks

Returns existing instance if one exists for the target
Creates new instance if none exists
Instances are cached, and garbage collected with the target only if everything their handlers observe is too

Throws

TypeError if the target is not an object.

getSafe()

static getSafe<T>(target): Validator<T> | null

Defined in: validator.ts:119

Get a validator instance for the target object.

Same as Validator.get but returns null instead of throwing an error.

Parameters

target

T

Returns

Validator<T> | null

Members

id

readonly id: string

Defined in: validator.ts:89

asyncState

Get Signature

get asyncState(): number

Defined in: validator.ts:309

The number of pending/running async jobs.

Returns

number

@computed

firstErrorMessage

Get Signature

get firstErrorMessage(): string | null

Defined in: validator.ts:198

Get the first error message (including nested objects)

Returns

string | null

@computed

invalidKeyCount

Get Signature

get invalidKeyCount(): number

Defined in: validator.ts:149

The number of invalid keys

Returns

number

@computed

invalidKeyPathCount

Get Signature

get invalidKeyPathCount(): number

Defined in: validator.ts:171

The number of invalid key paths

Returns

number

@computed

invalidKeyPaths

Get Signature

get invalidKeyPaths(): ReadonlySet<KeyPath>

Defined in: validator.ts:181

The key paths that have errors

Keys of nested objects are included.

Returns

ReadonlySet<KeyPath>

@computed

invalidKeys

Get Signature

get invalidKeys(): ReadonlySet<KeyPath>

Defined in: validator.ts:159

The keys that have errors

Keys of nested objects are NOT included.

Returns

ReadonlySet<KeyPath>

@computed

isValid

Get Signature

get isValid(): boolean

Defined in: validator.ts:143

Whether no errors are found

Returns

boolean

@computed

isValidating

Get Signature

get isValidating(): boolean

Defined in: validator.ts:321

Whether the validator is computing errors (including nested validators)

Returns

boolean

@computed

nested

Get Signature

get nested(): ReadonlyMap<KeyPath, Validator<any>>

Defined in: validator.ts:372

Nested validators

Returns

ReadonlyMap<KeyPath, Validator<any>>

reactionState

Get Signature

get reactionState(): number

Defined in: validator.ts:301

The number of pending/running reactions.

Returns

number

@computed

addAsyncHandler()

addAsyncHandler<Expr>(expr, handler, opt?): () => void

Defined in: validator.ts:468

@action

Add an async handler

Parameters

expr

() => Expr

The expression to observe

handler

Validator.AsyncHandler<T, NoInfer<Expr>>

The async handler to call when the expression changes

opt?

Validator.HandlerOptions<NoInfer<Expr>>

The handler options

Returns

A function to remove the handler

() => void

Remarks

Handler runs immediately when added for initial validation
Handler is called when the watched expression changes
Changes are throttled by default delay
Changes made while the handler is running are queued, not aborted: the latest value is validated after the running handler settles
Provides abort signal, which is aborted when the validator is reset or the handler is removed; the result of an aborted run is discarded, so the errors it collected are not applied

addSyncHandler()

addSyncHandler(handler, opt?): () => void

Defined in: validator.ts:429

Add a sync handler

Parameters

handler

Validator.SyncHandler<T>

The sync handler containing observable expressions

opt?

Validator.HandlerOptions<unknown>

Returns

A function to remove the handler

() => void

Remarks

Handler runs immediately when added for initial validation
Handler is called when observable expressions within it change
Changes are throttled by default delay

findErrors()

findErrors(searchKeyPath, prefixMatch?): Generator<[keyPath: KeyPath, error: ValidationError], void, any>

Defined in: validator.ts:229

Find errors for the key path

Can do exact or prefix matching
Returns all errors that match the key path
Includes errors from nested validators when using prefix match

Parameters

searchKeyPath

KeyPath

prefixMatch?

boolean = false

Returns

Generator<[keyPath: KeyPath, error: ValidationError], void, any>

getErrorMessages()

getErrorMessages(keyPath, prefixMatch?): Set<string>

Defined in: validator.ts:206

Get error messages for the key path

Parameters

keyPath

KeyPath

prefixMatch?

boolean = false

Returns

Set<string>

hasErrors()

hasErrors(keyPath, prefixMatch?): boolean

Defined in: validator.ts:215

Check if the validator has errors for the key path

Parameters

keyPath

KeyPath

prefixMatch?

boolean = false

Returns

boolean

reset()

reset(): void

Defined in: validator.ts:384

@action

Reset the validator

Use with caution.
Since validation is reactive, errors won't reappear until you make some changes.
Running async validations are aborted, and their results are discarded.

Returns

void

updateErrors()

updateErrors(key, handler): () => void

Defined in: validator.ts:403

@action

Update the errors immediately

Parameters

key

symbol

handler

Validator.InstantHandler<T>

Returns

A function to remove the errors

() => void

waitForValidation()

waitForValidation(opt?): Promise<void>

Defined in: validator.ts:352

Wait for the validation to complete

A shorthand for:

await when(() => !validator.isValidating);

Parameters

opt?

signal?

AbortSignal

Abort signal to stop waiting

Returns

Promise<void>

A promise that resolves once isValidating is false, or rejects with the reason of the signal if it is aborted first

Remarks

Resolves right away if nothing is being validated
Waits for nested validators as well, as isValidating includes them
Deadlocks when awaited in an async handler of this validator or of a nested one: the handler is part of the validation it waits for