Skip to content

Validation

Overview

The definition file for "validators" used to validate values. This file holds associated logic that validates the schema of the "validator" object, as well as testing if a value adheres to the restrictions provided by a validator. See validate.js for usage with assertions to check that values are valid.

Examples:

A Validator that only accepts number values:

A Validator that only accepts the numbers "2" or "3":

A Validator that accepts any Object:

A Validator that accepts EnumerationDeprecated values (NOTE! This is deprecated, use the new class-based enumeration pattern as the valueType): { valueType: MyEnumeration } and/or

A Validator that accepts a string or a number greater than 2: { isValidValue: value => { typeof value === 'string' || (typeof value === 'number' && value > 2)} }

A Validator for a number that should be an even number greater than 10 { valueType: 'number', validators: [ { isValidValue: v => v > 10 }, { isValidValue: v => v%2 === 0 }] }

@author Sam Reid (PhET Interactive Simulations) @author Michael Kauzmann (PhET Interactive Simulations)

Class Validation

import { Validation } from 'scenerystack/axon';

Static Methods

getValidatorValidationError( validator : Validator<T> ) : string | null

@returns an error string if incorrect, otherwise null if valid

validateValidator( validator : Validator<T> )

containsValidatorKey( validator : IntentionalAny ) : boolean

@param validator - object which may or may not contain validation keys

isValueValid( value : T, validator : Validator<T>, providedOptions? : IsValidValueOptions ) : boolean

getValidationError( value : IntentionalAny, validator : Validator<T>, providedOptions? : IsValidValueOptions ) : string | null

Determines whether a value is valid (returning a boolean value), returning the problem as a string if invalid, otherwise returning null when valid.

equalsForValidationStrategy( a : T, b : T, valueComparisonStrategy : ValueComparisonStrategy<T> ) : boolean

Compare the two provided values for equality using the valueComparisonStrategy provided, see ValueComparisonStrategy type.

Static Properties

VALIDATOR_KEYS

(readonly)

STRING_WITHOUT_TEMPLATE_VARS_VALIDATOR : Validator<string>

(readonly)

General validator for validating that a string doesn't have template variables in it.

Type IsValidValueOptions

import type { IsValidValueOptions } from 'scenerystack/axon';
  • validateValidator?: boolean
    By default validation will always check the validity of the validator itself. However, for types like Property and Emitter re-checking the validator every time the Property value changes or the Emitter emits wastes cpu. Hence cases like those can opt-out

Type ValidationMessage

import type { ValidationMessage } from 'scenerystack/axon';

string | ( () => string )

Type Validator

import type { Validator } from 'scenerystack/axon';
  • valueType?: ValueType | ValueType[]
    Type of the value. If {function}, the function must be a constructor. If {string}, the string must be one of the primitive types listed in TYPEOF_STRINGS. If {null|undefined}, the value must be null (which doesn't make sense until the next line of doc) If {Array.<string|function|null|undefined>}, each item must be a legal value as explained in the above doc Unused if null. Examples: valueType: Vector2 valueType: 'string' valueType: 'number', valueType: [ 'number', null ] valueType: [ 'number', 'string', Node, null ]
  • validValues?: readonly T[]
    Valid values for this Property. Unused if null. Example: validValues: [ 'horizontal', 'vertical' ]
  • valueComparisonStrategy?: ValueComparisonStrategy<T>
    equalsFunction -> must have .equals() function on the type T
  • isValidValue?: ( v: T ) => boolean
    Function that validates the value. Single argument is the value, returns boolean. Unused if null. Example: isValidValue: function( value ) { return Number.isInteger( value ) && value >= 0; }
  • phetioType?: IOType
    An IOType used to specify the public typing for PhET-iO. Each IOType must have a validator key specified that can be used for validation. See IOType for an example.
  • validationMessage?: ValidationMessage
    if provided, this will provide supplemental information to the assertion/validation messages in addition to the validate-key-specific message that will be given.
  • validators?: Validator<T>[]
    A list of Validator objects, each of which must pass to be a valid value

Source Code

See the source for Validation.ts in the axon repository.