T

See source code
Table of contents

Properties

any

Validator that accepts any value and types it as 'any'. This should generally be avoided as it bypasses type safety, but can be used as an escape hatch for prototyping.

any: Validator<any>

Example

const result = T.any.validate(anything) // Returns the value as any
// result is typed as any - use with caution!

array

Validator that ensures a value is an array. Does not validate the contents of the array. Use T.arrayOf() to validate both the array structure and its contents.

array: Validator<unknown[]>

Example

const items = T.array.validate([1, 'hello', true]) // Returns unknown[]
T.array.validate('not array') // Throws ValidationError: "Expected an array, got a string"

// For typed arrays, use T.arrayOf:
const numbers = T.arrayOf(T.number).validate([1, 2, 3]) // Returns number[]

bigint

Validator that ensures a value is a bigint.

bigint: Validator<bigint>

Example

const largeNumber = T.bigint.validate(123n) // Returns 123n
T.bigint.validate(123) // Throws ValidationError: "Expected bigint, got a number"

boolean

Validator that ensures a value is a boolean.

boolean: Validator<boolean>

Example

const isActive = T.boolean.validate(true) // Returns true
const isEnabled = T.boolean.validate(false) // Returns false
T.boolean.validate('true') // Throws ValidationError: "Expected boolean, got a string"

httpUrl

Validator for HTTP and HTTPS URLs only. Rejects all other protocols.

httpUrl: Validator<string>

Example

const apiUrl = T.httpUrl.validate('https://api.example.com') // Valid
const httpUrl = T.httpUrl.validate('http://localhost:3000') // Valid
T.httpUrl.validate('') // Valid (empty string allowed)
T.httpUrl.validate('ftp://files.example.com') // Throws ValidationError (not http/https)

indexKey

Validator for IndexKey values used in tldraw's indexing system. An IndexKey is a string that meets specific format requirements for use as a database index.

indexKey: Validator<IndexKey>

Example

const key = T.indexKey.validate('valid_index_key') // Returns IndexKey
T.indexKey.validate('invalid key!') // Throws ValidationError (invalid format)

integer

Validator that ensures a value is an integer (whole number).

integer: Validator<number>

Example

const count = T.integer.validate(42) // Returns 42
T.integer.validate(3.14) // Throws ValidationError: "Expected an integer, got 3.14"
T.integer.validate(-5) // Returns -5 (negative integers are valid)

jsonValue

Validator that ensures a value is valid JSON (string, number, boolean, null, array, or plain object). Rejects functions, undefined, symbols, and other non-JSON values.

jsonValue: Validator<JsonValue>

Example

const data = T.jsonValue.validate({
  name: 'Alice',
  scores: [1, 2, 3],
  active: true,
})
T.jsonValue.validate(undefined) // Throws ValidationError
T.jsonValue.validate(() => {}) // Throws ValidationError

linkUrl

Validator for URLs that are safe to use as user-facing links. Accepts http, https, and mailto protocols. This validator provides security by rejecting potentially dangerous protocols like javascript:.

linkUrl: Validator<string>

Example

const link = T.linkUrl.validate('https://example.com') // Valid
const email = T.linkUrl.validate('mailto:user@example.com') // Valid
T.linkUrl.validate('') // Valid (empty string allowed)
T.linkUrl.validate('javascript:alert(1)') // Throws ValidationError (unsafe protocol)

nonZeroInteger

Validator that ensures a value is a positive integer (> 0). Rejects zero and negative integers.

nonZeroInteger: Validator<number>

Example

const itemCount = T.nonZeroInteger.validate(1) // Returns 1
T.nonZeroInteger.validate(0) // Throws ValidationError: "Expected a non-zero positive integer, got 0"
T.nonZeroInteger.validate(-5) // Throws ValidationError: "Expected a non-zero positive integer, got -5"

nonZeroNumber

Validator that ensures a value is a positive number (> 0). Rejects zero and negative numbers.

nonZeroNumber: Validator<number>

Example

const quantity = T.nonZeroNumber.validate(0.01) // Returns 0.01
T.nonZeroNumber.validate(0) // Throws ValidationError: "Expected a non-zero positive number, got 0"
T.nonZeroNumber.validate(-5) // Throws ValidationError: "Expected a non-zero positive number, got -5"

number

Validator that ensures a value is a finite, non-NaN number. Rejects Infinity, -Infinity, and NaN.

number: Validator<number>

Example

const count = T.number.validate(42) // Returns 42 as number
T.number.validate(NaN) // Throws ValidationError: "Expected a number, got NaN"
T.number.validate(Infinity) // Throws ValidationError: "Expected a finite number, got Infinity"

positiveInteger

Validator that ensures a value is a non-negative integer (>= 0). Despite the name "positive", this validator accepts zero.

positiveInteger: Validator<number>

Example

const index = T.positiveInteger.validate(5) // Returns 5
const start = T.positiveInteger.validate(0) // Returns 0 (valid)
T.positiveInteger.validate(-1) // Throws ValidationError: "Expected a positive integer, got -1"
T.positiveInteger.validate(3.14) // Throws ValidationError: "Expected an integer, got 3.14"

positiveNumber

Validator that ensures a value is a non-negative number (>= 0). Despite the name "positive", this validator accepts zero.

positiveNumber: Validator<number>

Example

const price = T.positiveNumber.validate(29.99) // Returns 29.99
const free = T.positiveNumber.validate(0) // Returns 0 (valid)
T.positiveNumber.validate(-1) // Throws ValidationError: "Expected a positive number, got -1"

srcUrl

Validator for URLs that are safe to use as asset sources. Accepts http, https, data, and asset protocols. The asset: protocol refers to tldraw's local IndexedDB object store.

srcUrl: Validator<string>

Example

const imageUrl = T.srcUrl.validate('https://example.com/image.png') // Valid
const dataUrl = T.srcUrl.validate('data:image/png;base64,iVBORw0...') // Valid
const assetUrl = T.srcUrl.validate('asset:abc123') // Valid (local asset reference)
T.srcUrl.validate('') // Valid (empty string allowed)

string

Validator that ensures a value is a string.

string: Validator<string>

Example

const name = T.string.validate('hello') // Returns "hello" as string
T.string.validate(123) // Throws ValidationError: "Expected string, got a number"

unknown

Validator that accepts any value without type checking. Useful as a starting point for building custom validations or when you need to accept truly unknown data.

unknown: Validator<unknown>

Example

const result = T.unknown.validate(anything) // Returns the value as-is
// result is typed as unknown

unknownObject

Validator that ensures a value is an object (non-null, non-array). Does not validate the properties of the object.

unknownObject: Validator<Record<string, unknown>>

Example

const obj = T.unknownObject.validate({ any: 'properties' }) // Returns Record<string, unknown>
T.unknownObject.validate(null) // Throws ValidationError: "Expected object, got null"
T.unknownObject.validate([1, 2, 3]) // Throws ValidationError: "Expected object, got an array"

Methods

arrayOf( )

Creates a validator for arrays where each element is validated using the provided validator.

function arrayOf<T>(itemValidator: Validatable<T>): ArrayOfValidator<T>

Example

const numberArray = T.arrayOf(T.number)
numberArray.validate([1, 2, 3]) // Returns number[]
numberArray.validate([1, '2', 3]) // Throws ValidationError at index 1

const userArray = T.arrayOf(T.object({ name: T.string, age: T.number }))

Parameters

NameDescription

itemValidator

Validatable<T>

Validator to use for each array element

Returns

ArrayOfValidator<T>

An ArrayOfValidator that validates both array structure and element types

dict( )

Creates a validator for dictionary objects where both keys and values are validated. Useful for validating objects used as key-value maps.

function dict<Key extends string, Value>(
  keyValidator: Validatable<Key>,
  valueValidator: Validatable<Value>
): DictValidator<Key, Value>

Example

const scores = T.dict(T.string, T.number)
scores.validate({ alice: 100, bob: 85 }) // Valid

const userPrefs = T.dict(
  T.string,
  T.object({
    theme: T.literalEnum('light', 'dark'),
    notifications: T.boolean,
  })
)

Parameters

NameDescription

keyValidator

Validatable<Key>

Validator for object keys

valueValidator

Validatable<Value>

Validator for object values

Returns

DictValidator<Key, Value>

A DictValidator that validates all keys and values

jsonDict( )

Creates a validator for JSON dictionaries (objects with string keys and JSON-serializable values).

function jsonDict(): DictValidator<string, JsonValue>

Example

const config = T.jsonDict().validate({
  setting1: 'value',
  setting2: 42,
  setting3: ['a', 'b', 'c'],
  setting4: { nested: true },
})

literal( )

Creates a validator that only accepts a specific literal value.

function literal<T extends boolean | number | string>(
  expectedValue: T
): Validator<T>

Example

const trueValidator = T.literal(true)
trueValidator.validate(true) // Returns true
trueValidator.validate(false) // Throws ValidationError

const statusValidator = T.literal('active')
statusValidator.validate('active') // Returns "active"
statusValidator.validate('inactive') // Throws ValidationError

Parameters

NameDescription

expectedValue

T

The exact value that must be matched

Returns

Validator<T>

A validator that only accepts the specified literal value

literalEnum( )

Creates a validator that only accepts one of the provided literal values. This is a convenience function that creates a setEnum from the provided values.

function literalEnum<const Values extends readonly unknown[]>(
  ...values: Values
): Validator<Values[number]>

Example

const themeValidator = T.literalEnum('light', 'dark', 'auto')
themeValidator.validate('light') // Returns 'light'
themeValidator.validate('blue') // Throws ValidationError: Expected "light" or "dark" or "auto", got blue

Parameters

NameDescription

values

Values

The allowed literal values

Returns

Validator<Values[number]>

A validator that only accepts the provided literal values

model( )

Creates a validator for named model objects with enhanced error reporting. The model name will be included in error messages to provide better debugging context.

function model<
  T extends {
    readonly id: string
  },
>(name: string, validator: Validatable<T>): Validator<T>

Example

const userModel = T.model(
  'User',
  T.object({
    id: T.string,
    name: T.string,
    email: T.linkUrl,
  })
)

// Error message will be: "At User.email: Expected a valid url, got 'invalid-email'"

Parameters

NameDescription

name

string

The name of the model (used in error messages)

validator

Validatable<T>

The validator for the model structure

Returns

Validator<T>

A Validator with enhanced error reporting that includes the model name

nullable( )

Creates a validator that accepts either the validated type or null.

function nullable<T>(validator: Validatable<T>): Validator<null | T>

Example

const nullableString = T.nullable(T.string)
nullableString.validate('hello') // Returns "hello"
nullableString.validate(null) // Returns null
nullableString.validate(undefined) // Throws ValidationError

Parameters

NameDescription

validator

Validatable<T>

The base validator to make nullable

Returns

Validator<null | T>

A validator that accepts T or null

object( )

Creates a validator for objects with a defined shape. Each property is validated using its corresponding validator from the config object.

function object<Shape extends object>(config: {
  readonly [K in keyof Shape]: Validatable<Shape[K]>
}): ObjectValidator<MakeUndefinedOptional<Shape>>

Example

const userValidator = T.object({
  name: T.string,
  age: T.number,
  email: T.string.optional(),
  isActive: T.boolean,
})

const user = userValidator.validate({
  name: 'Alice',
  age: 25,
  email: 'alice@example.com',
  isActive: true,
})
// user is typed with full type safety

Parameters

NameDescription

config

{
  readonly [K in keyof Shape]: Validatable<Shape[K]>
}

Object mapping property names to their validators

Returns

ObjectValidator<MakeUndefinedOptional<Shape>>

An ObjectValidator that validates the object structure and all properties

optional( )

Creates a validator that accepts either the validated type or undefined.

function optional<T>(validator: Validatable<T>): Validator<T | undefined>

Example

const optionalString = T.optional(T.string)
optionalString.validate('hello') // Returns "hello"
optionalString.validate(undefined) // Returns undefined
optionalString.validate(null) // Throws ValidationError

Parameters

NameDescription

validator

Validatable<T>

The base validator to make optional

Returns

Validator<T | undefined>

A validator that accepts T or undefined

or( )

Creates a validator that accepts values matching either of two validators. Tries the first validator, and if it fails, tries the second validator.

function or<T1, T2>(
  v1: Validatable<T1>,
  v2: Validatable<T2>
): Validator<T1 | T2>

Example

const stringOrNumber = T.or(T.string, T.number)
stringOrNumber.validate('hello') // Returns "hello" as string
stringOrNumber.validate(42) // Returns 42 as number
stringOrNumber.validate(true) // Throws ValidationError from number validator

Parameters

NameDescription

v1

Validatable<T1>

The first validator to try

v2

Validatable<T2>

The second validator to try if the first fails

Returns

Validator<T1 | T2>

A validator that accepts values matching either validator

setEnum( )

Creates a validator that only accepts values from a given Set of allowed values.

function setEnum<T>(values: ReadonlySet<T>): Validator<T>

Example

const allowedColors = new Set(['red', 'green', 'blue'] as const)
const colorValidator = T.setEnum(allowedColors)
colorValidator.validate('red') // Returns 'red'
colorValidator.validate('yellow') // Throws ValidationError

Parameters

NameDescription

values

ReadonlySet<T>

Set containing the allowed values

Returns

Validator<T>

A validator that only accepts values from the provided set

union( )

Creates a validator for discriminated union types. Validates objects that can be one of several variants, distinguished by a discriminator property.

function union<
  Key extends string,
  Config extends UnionValidatorConfig<Key, Config>,
>(key: Key, config: Config): UnionValidator<Key, Config>

Example

const shapeValidator = T.union('type', {
  circle: T.object({ type: T.literal('circle'), radius: T.number }),
  square: T.object({ type: T.literal('square'), size: T.number }),
  triangle: T.object({
    type: T.literal('triangle'),
    base: T.number,
    height: T.number,
  }),
})

const circle = shapeValidator.validate({ type: 'circle', radius: 5 })
// circle is typed as { type: 'circle'; radius: number }

Parameters

NameDescription

key

Key

The discriminator property name used to determine the variant

config

Config

Object mapping variant names to their validators

Returns

UnionValidator<Key, Config>

A UnionValidator that validates based on the discriminator value