Validator

Defined in: validator.ts:76, validator.ts:583

Validator for handling synchronous and asynchronous validations

Supports both sync and async validation handlers
Tracks validation state (isValidating)
Looks up errors by key path pattern
Supports nested validators

Types

AsyncHandler

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

Defined in: validator.ts:591

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:609

Handler options

Type Parameters

Expr

Expr = unknown

delayMs?

optional delayMs?: number

Defined in: validator.ts:621

Throttle reaction. [milliseconds]

Default

equals?

optional equals?: IEqualsComparer<Expr>

Defined in: validator.ts:627

The equality comparer for the expression.

Only effective for async handlers.

initialRun?

optional initialRun?: boolean

Defined in: validator.ts:615

Whether to run the handler immediately

Default

true

InstantHandler

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

Defined in: validator.ts:607

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:601

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:77

get()

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

Defined in: validator.ts:98

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 by the identity of the target, so an object inheriting from a validated one gets its own
Nothing is written to the target, so frozen, sealed and non-extensible objects are supported
Instances are 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:109

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:79

asyncState

Get Signature

get asyncState(): number

Defined in: validator.ts:283

The number of pending/running async jobs.

Returns

number

@computed

firstErrorMessage

Get Signature

get firstErrorMessage(): string | null

Defined in: validator.ts:188

Get the first error message (including nested objects)

Returns

string | null

@computed

invalidKeyCount

Get Signature

get invalidKeyCount(): number

Defined in: validator.ts:139

The number of invalid keys

Returns

number

@computed

invalidKeyPathCount

Get Signature

get invalidKeyPathCount(): number

Defined in: validator.ts:161

The number of invalid key paths

Returns

number

@computed

invalidKeyPaths

Get Signature

get invalidKeyPaths(): ReadonlySet<KeyPath>

Defined in: validator.ts:171

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:149

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:133

Whether no errors are found

Returns

boolean

@computed

isValidating

Get Signature

get isValidating(): boolean

Defined in: validator.ts:295

Whether the validator is computing errors (including nested validators)

Returns

boolean

@computed

nested

Get Signature

get nested(): Generator<StandardNestedFetcher.Entry<Validator<any>>, void, unknown>

Defined in: validator.ts:359

Nested validators

Remarks

A fresh iterator over the @nested entries, in annotation order and then in collection order. Each entry carries the name of the annotated member in key ("items"), the address of the nested object in keyPath ("items.0") and its validator in data.
Each read starts a new iteration, and an iterator is consumed once, so a second pass needs a second read.
There is no lookup by name: entries are not unique by key path. To reach the validator of one nested object, go through the property — Validator.get(target.child) is cached per subject, so it is the very instance yielded here — or iterate and match entry.key, which is KeyPath.Self for a @nested.hoist member rather than the name it is declared with. Errors are looked up by pattern with findErrors, which searches nested validators itself.

Returns

Generator<StandardNestedFetcher.Entry<Validator<any>>, void, unknown>

reactionState

Get Signature

get reactionState(): number

Defined in: validator.ts:275

The number of pending/running reactions.

Returns

number

@computed

addAsyncHandler()

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

Defined in: validator.ts:455

@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:416

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(...patterns): Generator<[keyPath: KeyPath, error: ValidationError], void, any>

Defined in: validator.ts:221

Find the errors of the key paths matching any of the patterns

Yields each error once, with its key path relative to this validator, however many patterns match it
Searches nested validators, including hoisted ones, for the rest of the patterns
Reads only the @nested members the patterns can reach, which is all of them when one starts with a wildcard

Parameters

patterns

...KeyPathPattern[]

Returns

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

See

KeyPathPattern for the syntax

getErrorMessages()

getErrorMessages(...patterns): Set<string>

Defined in: validator.ts:196

Get the error messages of the key paths matching any of the patterns

Parameters

patterns

...KeyPathPattern[]

Returns

Set<string>

hasErrors()

hasErrors(...patterns): boolean

Defined in: validator.ts:205

Check if any key path matching any of the patterns has errors

Parameters

patterns

...KeyPathPattern[]

Returns

boolean

reset()

reset(): void

Defined in: validator.ts:371

@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:390

@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:326

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