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

Type ValueComparisonStrategy¶

The way that two values can be compared for equality: "reference" - uses triple equals comparison (most often the default) "equalsFunction" - asserts that the two values have an equals() function that can used to compare (see "ComparableObject" type) "lodashDeep" - uses _.isEqual() for comparison custom function - define any function that returns if the two provided values are equal.

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

"equalsFunction" | "reference" | "lodashDeep" | CustomValueComparisonMethodHolder<T>['customValueComparison']

Source Code¶

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