@tldraw/validate 5.1.0 → 5.2.0-canary.05c017c18b15

package/src/test/objects.test.ts

@@ -0,0 +1,137 @@
+import * as T from '../lib/validation'
+
+describe('§10 Objects', () => {
+	it('[O1] object validates each configured property, prefixing the property name', () => {
+		const validator = T.object({ name: T.string, age: T.number })
+		const value = { name: 'Alice', age: 25 }
+		expect(validator.validate(value)).toBe(value)
+
+		expect(() => validator.validate({ name: 'Alice', age: 'old' })).toThrow(
+			'At age: Expected number, got a string'
+		)
+	})
+
+	it('[O1] a missing property is validated as undefined', () => {
+		const validator = T.object({ name: T.string, age: T.number })
+		expect(() => validator.validate({ name: 'Alice' })).toThrow(
+			'At age: Expected number, got undefined'
+		)
+	})
+
+	it('[O2] unknown properties are rejected', () => {
+		expect(() => T.object({ moo: T.literal('cow') }).validate({ moo: 'cow', cow: 'moo' })).toThrow(
+			'At cow: Unexpected property'
+		)
+	})
+
+	it('[O3] allowUnknownProperties returns a new validator accepting unvalidated extras', () => {
+		const strict = T.object({ name: T.string })
+		const loose = strict.allowUnknownProperties()
+
+		const value = { name: 'Alice', extra: () => {} }
+		expect(loose.validate(value)).toBe(value)
+
+		// the original validator is unchanged
+		expect(() => strict.validate({ name: 'Alice', extra: 1 })).toThrow(
+			'At extra: Unexpected property'
+		)
+	})
+
+	it('[O4] non-objects and null are rejected', () => {
+		const validator = T.object({ a: T.number })
+		expect(() => validator.validate(null)).toThrow('Expected object, got null')
+		expect(() => validator.validate('x')).toThrow('Expected object, got a string')
+		expect(() => validator.validate(undefined)).toThrow('Expected object, got undefined')
+	})
+
+	it('[O4] arrays pass the object check', () => {
+		const empty: never[] = []
+		expect(T.object({}).validate(empty)).toBe(empty)
+		expect(() => T.object({}).validate([1])).toThrow('At 0: Unexpected property')
+		expect(() => T.object({ a: T.number }).validate([])).toThrow(
+			'At a: Expected number, got undefined'
+		)
+	})
+
+	it('[O5] extend merges configs, with extension keys overriding', () => {
+		const base = T.object({ a: T.number, b: T.number })
+		const extended = base.extend({ b: T.string as any as T.Validatable<number>, c: T.boolean })
+
+		const value = { a: 1, b: 'x', c: true }
+		expect(extended.validate(value as any)).toBe(value)
+		expect(() => extended.validate({ a: 1, b: 2, c: true } as any)).toThrow(
+			'At b: Expected string, got a number'
+		)
+
+		// the base validator is unchanged
+		expect(base.validate({ a: 1, b: 2 })).toEqual({ a: 1, b: 2 })
+	})
+
+	it('[O5] the extended validator rejects unknown properties even when the receiver allowed them', () => {
+		const validator = T.object({ a: T.number }).allowUnknownProperties().extend({ b: T.string })
+		expect(() => validator.validate({ a: 1, b: 'x', c: true })).toThrow('At c: Unexpected property')
+	})
+
+	it('[O6] known-good validation returns the known-good object when nothing changed', () => {
+		const validator = T.object({ a: T.number, nested: T.object({ b: T.string }) })
+		const knownGood = validator.validate({ a: 1, nested: { b: 'x' } })
+
+		// new outer and inner objects, structurally equal
+		expect(validator.validateUsingKnownGoodVersion(knownGood, { a: 1, nested: { b: 'x' } })).toBe(
+			knownGood
+		)
+	})
+
+	it('[O6] known-good validation returns the new object when a property changed, revalidating only changes', () => {
+		let calls = 0
+		const counting = new T.Validator<number>((value) => {
+			calls++
+			return T.number.validate(value)
+		})
+		const validator = T.object({ a: counting, b: counting })
+		const knownGood = validator.validate({ a: 1, b: 2 })
+		calls = 0
+
+		const next = { a: 1, b: 3 }
+		expect(validator.validateUsingKnownGoodVersion(knownGood, next)).toBe(next)
+		expect(calls).toBe(1)
+
+		expect(() => validator.validateUsingKnownGoodVersion(knownGood, { a: 1, b: 'x' })).toThrow(
+			'At b: Expected number, got a string'
+		)
+	})
+
+	it('[O6] known-good validation rejects non-objects and added unknown properties', () => {
+		const validator = T.object({ a: T.number })
+		const knownGood = validator.validate({ a: 1 })
+		expect(() => validator.validateUsingKnownGoodVersion(knownGood, 'x')).toThrow(
+			'Expected object, got a string'
+		)
+		expect(() => validator.validateUsingKnownGoodVersion(knownGood, { a: 1, b: 2 })).toThrow(
+			'At b: Unexpected property'
+		)
+	})
+
+	it('[O8] known-good validation detects changes to unknown properties', () => {
+		const validator = T.object({ a: T.number }).allowUnknownProperties()
+
+		const knownGood = validator.validate({ a: 1, extra: 1 })
+		expect(validator.validateUsingKnownGoodVersion(knownGood, { a: 1, extra: 1 })).toBe(knownGood)
+
+		const changed = { a: 1, extra: 2 }
+		expect(validator.validateUsingKnownGoodVersion(knownGood, changed)).toBe(changed)
+
+		const added = { a: 1, extra: 1, more: true }
+		expect(validator.validateUsingKnownGoodVersion(knownGood, added)).toBe(added)
+
+		const removed = { a: 1 }
+		expect(validator.validateUsingKnownGoodVersion(knownGood, removed)).toBe(removed)
+	})
+
+	it('[O7] known-good validation detects removed keys', () => {
+		const validator = T.object({ a: T.number, b: T.number.optional() })
+		const knownGood = validator.validate({ a: 1, b: 2 })
+		const next = { a: 1 }
+		expect(validator.validateUsingKnownGoodVersion(knownGood, next)).toBe(next)
+	})
+})

package/src/test/or.test.ts

@@ -0,0 +1,13 @@
+import * as T from '../lib/validation'
+
+describe('§17 Either-of', () => {
+	it('[OR1] returns the first validator’s result when it passes, else the second’s', () => {
+		const stringOrNumber = T.or(T.string, T.number)
+		expect(stringOrNumber.validate('hello')).toBe('hello')
+		expect(stringOrNumber.validate(42)).toBe(42)
+	})
+
+	it('[OR2] when both fail, the second validator’s error propagates', () => {
+		expect(() => T.or(T.string, T.number).validate(true)).toThrow('Expected number, got a boolean')
+	})
+})

package/src/test/primitives.test.ts

@@ -0,0 +1,67 @@
+import * as T from '../lib/validation'
+
+describe('§6 Primitives', () => {
+	it('[P1] string, boolean, and bigint validate by typeof', () => {
+		expect(T.string.validate('hello')).toBe('hello')
+		expect(T.string.validate('')).toBe('')
+		expect(() => T.string.validate(123)).toThrow('Expected string, got a number')
+
+		expect(T.boolean.validate(true)).toBe(true)
+		expect(T.boolean.validate(false)).toBe(false)
+		expect(() => T.boolean.validate('true')).toThrow('Expected boolean, got a string')
+
+		expect(T.bigint.validate(123n)).toBe(123n)
+		expect(() => T.bigint.validate(123)).toThrow('Expected bigint, got a number')
+	})
+
+	it('[P2] type-mismatch messages describe the actual value', () => {
+		expect(() => T.string.validate(null)).toThrow('Expected string, got null')
+		expect(() => T.string.validate(undefined)).toThrow('Expected string, got undefined')
+		expect(() => T.string.validate([1])).toThrow('Expected string, got an array')
+		expect(() => T.string.validate({})).toThrow('Expected string, got an object')
+		expect(() => T.string.validate(1)).toThrow('Expected string, got a number')
+		expect(() => T.string.validate(true)).toThrow('Expected string, got a boolean')
+		expect(() => T.string.validate(1n)).toThrow('Expected string, got a bigint')
+		expect(() => T.string.validate(() => {})).toThrow('Expected string, got a function')
+		expect(() => T.string.validate(Symbol('s'))).toThrow('Expected string, got a symbol')
+	})
+
+	it('[P3] unknown and any accept every value as-is', () => {
+		const obj = { a: 1 }
+		expect(T.unknown.validate(obj)).toBe(obj)
+		expect(T.unknown.validate(undefined)).toBe(undefined)
+		expect(T.unknown.validate(null)).toBe(null)
+		expect(T.any.validate(obj)).toBe(obj)
+		expect(T.any.validate(undefined)).toBe(undefined)
+	})
+
+	it('[P4] literal accepts exactly the expected value', () => {
+		expect(T.literal('active').validate('active')).toBe('active')
+		expect(T.literal(1).validate(1)).toBe(1)
+		expect(T.literal(true).validate(true)).toBe(true)
+
+		expect(() => T.literal('a').validate('b')).toThrow('Expected a, got "b"')
+		expect(() => T.literal(1).validate(2)).toThrow('Expected 1, got 2')
+		expect(() => T.literal(1).validate(undefined)).toThrow('Expected 1, got undefined')
+	})
+
+	it('[P5] array accepts any array without validating items', () => {
+		const arr = [1, 'two', null, () => {}]
+		expect(T.array.validate(arr)).toBe(arr)
+		expect(() => T.array.validate('not array')).toThrow('Expected an array, got a string')
+		expect(() => T.array.validate({})).toThrow('Expected an array, got an object')
+	})
+
+	it('[P6] unknownObject accepts any non-null object and rejects null and primitives', () => {
+		const obj = { any: 'properties' }
+		expect(T.unknownObject.validate(obj)).toBe(obj)
+		expect(() => T.unknownObject.validate(null)).toThrow('Expected object, got null')
+		expect(() => T.unknownObject.validate('x')).toThrow('Expected object, got a string')
+		expect(() => T.unknownObject.validate(5)).toThrow('Expected object, got a number')
+	})
+
+	it('[P6] unknownObject accepts arrays', () => {
+		const arr = [1, 2, 3]
+		expect(T.unknownObject.validate(arr)).toBe(arr)
+	})
+})

package/src/test/refine-check.test.ts

@@ -0,0 +1,82 @@
+import * as T from '../lib/validation'
+import { ValidationError } from '../lib/validation'
+
+describe('§4 Refinement: refine and check', () => {
+	it('[RC1] refine transforms the validated value, including to a new type', () => {
+		const stringToNumber = T.string.refine((str) => parseInt(str, 10))
+		expect(stringToNumber.validate('42')).toBe(42)
+
+		const prefixedString = T.string.refine((str) =>
+			str.startsWith('prefix:') ? str : `prefix:${str}`
+		)
+		expect(prefixedString.validate('test')).toBe('prefix:test')
+		expect(prefixedString.validate('prefix:existing')).toBe('prefix:existing')
+	})
+
+	it('[RC1] a ValidationError thrown by the refinement propagates with path context', () => {
+		const stringToNumber = T.string.refine((str) => {
+			const num = parseInt(str, 10)
+			if (isNaN(num)) throw new ValidationError('Invalid number format')
+			return num
+		})
+
+		expect(() => stringToNumber.validate('not-a-number')).toThrow('Invalid number format')
+
+		const nested = T.object({ count: stringToNumber })
+		expect(() => nested.validate({ count: 'nope' })).toThrow('At count: Invalid number format')
+	})
+
+	it('[RC2] known-good validation skips the refinement when the base reports no change', () => {
+		let calls = 0
+		const validator = T.arrayOf(T.number).refine((arr) => {
+			calls++
+			return arr
+		})
+
+		const knownGood = validator.validate([1, 2])
+		expect(calls).toBe(1)
+
+		expect(validator.validateUsingKnownGoodVersion(knownGood, [1, 2])).toBe(knownGood)
+		expect(calls).toBe(1)
+
+		const next = [1, 3]
+		expect(validator.validateUsingKnownGoodVersion(knownGood, next)).toBe(next)
+		expect(calls).toBe(2)
+	})
+
+	it('[RC3] known-good validation accepts a new value Object.is-equal to the previous output without input validation', () => {
+		const stringToNumber = T.string.refine((str) => parseInt(str, 10))
+		// 42 is not a valid input (not a string), but it equals the previous output.
+		expect(stringToNumber.validateUsingKnownGoodVersion(42, 42)).toBe(42)
+	})
+
+	it('[RC4] an unnamed check passes the value through and adds no path segment', () => {
+		const evenNumber = T.number.check((value) => {
+			if (value % 2 !== 0) throw new ValidationError('Expected even number')
+		})
+
+		expect(evenNumber.validate(4)).toBe(4)
+		expect(evenNumber.validate(0)).toBe(0)
+
+		try {
+			evenNumber.validate(3)
+			throw new Error('should have thrown')
+		} catch (error) {
+			expect(error).toBeInstanceOf(ValidationError)
+			expect((error as ValidationError).rawMessage).toBe('Expected even number')
+			expect((error as ValidationError).path).toEqual([])
+		}
+	})
+
+	it('[RC5] a named check prefixes failures with a (check name) segment', () => {
+		const positive = T.number.check('positive', (value) => {
+			if (value <= 0) throw new ValidationError('Must be positive')
+		})
+
+		expect(positive.validate(5)).toBe(5)
+		expect(() => positive.validate(-1)).toThrow('At (check positive): Must be positive')
+
+		const nested = T.object({ x: positive })
+		expect(() => nested.validate({ x: -1 })).toThrow('At x(check positive): Must be positive')
+	})
+})

package/src/test/unions.test.ts

@@ -0,0 +1,147 @@
+import * as T from '../lib/validation'
+
+const cat = T.object({ type: T.literal('cat'), id: T.string, meow: T.boolean })
+const dog = T.object({ type: T.literal('dog'), id: T.string, bark: T.boolean })
+const animal = T.union('type', { cat, dog })
+
+describe('§12 Discriminated unions', () => {
+	it('[U1] selects the variant by discriminator and returns the input on success', () => {
+		const value = { type: 'cat', id: 'abc123', meow: true }
+		expect(animal.validate(value)).toBe(value)
+	})
+
+	it('[U2] rejects non-object inputs', () => {
+		expect(() => animal.validate('cat')).toThrow('Expected an object, got a string')
+		expect(() => animal.validate(null)).toThrow('Expected an object, got null')
+	})
+
+	it('[U3] rejects a missing or non-string discriminator', () => {
+		expect(() => animal.validate({})).toThrow('Expected a string for key "type", got undefined')
+		expect(() => animal.validate({ type: 1 })).toThrow(
+			'Expected a string for key "type", got a number'
+		)
+	})
+
+	it('[U4] rejects unmatched variants, listing the known ones at the discriminator path', () => {
+		expect(() =>
+			T.object({ animal }).validate({ animal: { type: 'cow', moo: true, id: 'abc123' } })
+		).toThrow('At animal.type: Expected one of "cat" or "dog", got "cow"')
+	})
+
+	it('[U5] prefixes variant validation failures with the (key = variant) segment', () => {
+		expect(() =>
+			T.object({ animal }).validate({ animal: { type: 'cat', meow: 'yes', id: 'abc123' } })
+		).toThrow('At animal(type = cat).meow: Expected boolean, got a string')
+
+		expect(() =>
+			T.model('animal', animal).validate({ type: 'cat', moo: true, id: 'abc123' })
+		).toThrow('At animal(type = cat).meow: Expected boolean, got undefined')
+	})
+
+	it('[U6] validateUnknownVariants handles unmatched variants with the handler result', () => {
+		let seenVariant = ''
+		const lenient = animal.validateUnknownVariants((value, variant) => {
+			seenVariant = variant
+			return value as any
+		})
+
+		const unknownValue = { type: 'cow', moo: true }
+		expect(lenient.validate(unknownValue)).toBe(unknownValue)
+		expect(seenVariant).toBe('cow')
+
+		// known variants still validate normally
+		expect(() => lenient.validate({ type: 'cat', id: 'x', meow: 'yes' })).toThrow(
+			'At (type = cat).meow: Expected boolean, got a string'
+		)
+	})
+
+	it('[U6] a handler returning a new object trips the dev same-value check on the validate path', () => {
+		const lenient = animal.validateUnknownVariants((value) => ({ ...value }) as any)
+		expect(() => lenient.validate({ type: 'cow' })).toThrow(
+			'Validator functions must return the same value they were passed'
+		)
+
+		// the known-good path does not run that check
+		const out = lenient.validateUsingKnownGoodVersion({ type: 'cow' } as any, { type: 'emu' })
+		expect(out).toEqual({ type: 'emu' })
+	})
+
+	it('[U7] known-good validation with an unchanged discriminator preserves identity', () => {
+		const knownGood = animal.validate({ type: 'cat', id: 'x', meow: true })
+		expect(
+			animal.validateUsingKnownGoodVersion(knownGood, { type: 'cat', id: 'x', meow: true })
+		).toBe(knownGood)
+
+		const next = { type: 'cat', id: 'x', meow: false }
+		expect(animal.validateUsingKnownGoodVersion(knownGood, next)).toBe(next)
+		expect(() =>
+			animal.validateUsingKnownGoodVersion(knownGood, { type: 'cat', id: 'x', meow: 'no' })
+		).toThrow('At (type = cat).meow: Expected boolean, got a string')
+	})
+
+	it('[U7] a changed discriminator falls back to a full validation of the new variant', () => {
+		const knownGood = animal.validate({ type: 'cat', id: 'x', meow: true })
+		const next = { type: 'dog', id: 'x', bark: true }
+		expect(animal.validateUsingKnownGoodVersion(knownGood, next)).toBe(next)
+		expect(() => animal.validateUsingKnownGoodVersion(knownGood, { type: 'dog', id: 'x' })).toThrow(
+			'At (type = dog).bark: Expected boolean, got undefined'
+		)
+	})
+
+	it('[U7] known-good validation rejects a non-object on either side', () => {
+		const knownGood = animal.validate({ type: 'cat', id: 'x', meow: true })
+		expect(() => animal.validateUsingKnownGoodVersion(knownGood, 'x')).toThrow(
+			'Expected an object, got a string'
+		)
+		expect(() =>
+			animal.validateUsingKnownGoodVersion(null as any, { type: 'cat', id: 'x', meow: true })
+		).toThrow('Expected an object, got null')
+	})
+
+	describe('numberUnion', () => {
+		const versioned = T.numberUnion('version', {
+			1: T.object({ version: T.literal(1), data: T.string }),
+			2: T.object({ version: T.literal(2), data: T.string }),
+		})
+
+		it('[U8] validates variants keyed by finite number discriminators', () => {
+			const v1 = { version: 1, data: 'hello' }
+			const v2 = { version: 2, data: 'world' }
+			expect(versioned.validate(v1)).toBe(v1)
+			expect(versioned.validate(v2)).toBe(v2)
+		})
+
+		it('[U8] rejects Infinity, -Infinity, NaN, and non-numeric discriminators', () => {
+			expect(() => versioned.validate({ version: Infinity, data: 'x' })).toThrow(
+				'Expected a number for key "version", got "Infinity"'
+			)
+			expect(() => versioned.validate({ version: -Infinity, data: 'x' })).toThrow(
+				'Expected a number for key "version", got "-Infinity"'
+			)
+			expect(() => versioned.validate({ version: NaN, data: 'x' })).toThrow(
+				'Expected a number for key "version", got "NaN"'
+			)
+			expect(() => versioned.validate({ version: 'two', data: 'x' })).toThrow(
+				'Expected a number for key "version", got "two"'
+			)
+			expect(() => versioned.validate({ data: 'x' })).toThrow(
+				'Expected a number for key "version", got "undefined"'
+			)
+		})
+
+		it('[U9] looks the variant up by string coercion, so string-numeric discriminators select the variant', () => {
+			expect(() => versioned.validate({ version: '1', data: 'x' })).toThrow(
+				'At (version = 1).version: Expected 1, got "1"'
+			)
+		})
+
+		it('[U9] unmatched finite numbers are rejected as unknown variants', () => {
+			expect(() => versioned.validate({ version: 1.5, data: 'x' })).toThrow(
+				'At version: Expected one of "1" or "2", got 1.5'
+			)
+			expect(() => versioned.validate({ version: 3, data: 'x' })).toThrow(
+				'At version: Expected one of "1" or "2", got 3'
+			)
+		})
+	})
+})

package/src/test/urls.test.ts

@@ -0,0 +1,59 @@
+import * as T from '../lib/validation'
+
+describe('§15 URL validators', () => {
+	it('[UR1] linkUrl accepts the empty string and http/https/mailto urls', () => {
+		expect(T.linkUrl.validate('')).toBe('')
+		expect(T.linkUrl.validate('https://example.com')).toBe('https://example.com')
+		expect(T.linkUrl.validate('http://example.com')).toBe('http://example.com')
+		expect(T.linkUrl.validate('mailto:user@example.com')).toBe('mailto:user@example.com')
+
+		expect(() => T.linkUrl.validate('javascript:alert(1)')).toThrow(
+			'Expected a valid url, got "javascript:alert(1)" (invalid protocol)'
+		)
+		expect(() => T.linkUrl.validate('asset:abc')).toThrow('(invalid protocol)')
+		expect(() => T.linkUrl.validate('not a url')).toThrow('Expected a valid url, got "not a url"')
+	})
+
+	it('[UR2] srcUrl accepts the empty string and http/https/data/asset urls', () => {
+		expect(T.srcUrl.validate('')).toBe('')
+		expect(T.srcUrl.validate('https://example.com/image.png')).toBe('https://example.com/image.png')
+		expect(T.srcUrl.validate('data:image/png;base64,iVBORw0')).toBe('data:image/png;base64,iVBORw0')
+		expect(T.srcUrl.validate('asset:abc123')).toBe('asset:abc123')
+
+		expect(() => T.srcUrl.validate('mailto:user@example.com')).toThrow('(invalid protocol)')
+		expect(() => T.srcUrl.validate('javascript:alert(1)')).toThrow('(invalid protocol)')
+	})
+
+	it('[UR3] httpUrl accepts the empty string and only http/https urls', () => {
+		expect(T.httpUrl.validate('')).toBe('')
+		expect(T.httpUrl.validate('https://api.example.com')).toBe('https://api.example.com')
+		expect(T.httpUrl.validate('http://localhost:3000')).toBe('http://localhost:3000')
+
+		expect(() => T.httpUrl.validate('ftp://files.example.com')).toThrow('(invalid protocol)')
+		expect(() => T.httpUrl.validate('mailto:user@example.com')).toThrow('(invalid protocol)')
+		expect(() => T.httpUrl.validate('data:text/plain,hi')).toThrow('(invalid protocol)')
+	})
+
+	it('[UR4] strings starting with / or ./ validate; other relative forms do not', () => {
+		expect(T.linkUrl.validate('/foo')).toBe('/foo')
+		expect(T.linkUrl.validate('./foo')).toBe('./foo')
+		expect(T.srcUrl.validate('/foo')).toBe('/foo')
+		expect(T.srcUrl.validate('./foo')).toBe('./foo')
+		expect(T.httpUrl.validate('/foo')).toBe('/foo')
+		expect(T.httpUrl.validate('./foo')).toBe('./foo')
+
+		expect(() => T.linkUrl.validate('../foo')).toThrow('Expected a valid url, got "../foo"')
+		expect(() => T.linkUrl.validate('foo')).toThrow('Expected a valid url, got "foo"')
+	})
+
+	it('[UR5] protocol matching is case-insensitive', () => {
+		expect(T.linkUrl.validate('HTTP://example.com')).toBe('HTTP://example.com')
+		expect(() => T.linkUrl.validate('JAVASCRIPT:alert(1)')).toThrow('(invalid protocol)')
+	})
+
+	it('[UR6] non-strings are rejected as strings', () => {
+		expect(() => T.linkUrl.validate(5)).toThrow('Expected string, got a number')
+		expect(() => T.srcUrl.validate(null)).toThrow('Expected string, got null')
+		expect(() => T.httpUrl.validate(undefined)).toThrow('Expected string, got undefined')
+	})
+})

package/src/test/validator.test.ts

@@ -0,0 +1,60 @@
+import * as T from '../lib/validation'
+import { ValidationError } from '../lib/validation'
+
+describe('§3 The validator core', () => {
+	it('[V1] validate returns exactly the value it was passed', () => {
+		const validator = T.object({
+			name: T.string,
+			items: T.arrayOf(T.string.nullable()),
+		})
+
+		const value = {
+			name: 'toad',
+			items: ['toad', 'berd', null, 'bot'],
+		}
+
+		expect(validator.validate(value)).toBe(value)
+	})
+
+	it('[V1] validate does not mutate or freeze the value', () => {
+		const value = { name: 'toad', items: [1, 2] }
+		T.object({ name: T.string, items: T.arrayOf(T.number) }).validate(value)
+
+		expect(value).toEqual({ name: 'toad', items: [1, 2] })
+		expect(Object.isFrozen(value)).toBe(false)
+		expect(Object.isFrozen(value.items)).toBe(false)
+	})
+
+	it('[V2] a non-transforming validator returning a different value throws in dev', () => {
+		const validator = new T.Validator((value) => ({ ...(value as object) }))
+
+		expect(() => validator.validate({ a: 1 })).toThrow(
+			'Validator functions must return the same value they were passed'
+		)
+	})
+
+	it('[V3] isValid returns a boolean and never throws', () => {
+		expect(T.number.isValid(1)).toBe(true)
+		expect(T.number.isValid('one')).toBe(false)
+		expect(T.object({ a: T.string }).isValid(null)).toBe(false)
+	})
+
+	it('[V4] validateUsingKnownGoodVersion returns the known-good value without validating when Object.is-equal', () => {
+		let calls = 0
+		const counting = new T.Validator<number>((value) => {
+			calls++
+			if (typeof value !== 'number') throw new ValidationError('Expected number')
+			return value
+		})
+
+		expect(counting.validateUsingKnownGoodVersion(42, 42)).toBe(42)
+		expect(calls).toBe(0)
+	})
+
+	it('[V5] validateUsingKnownGoodVersion falls back to a full validate without a known-good implementation', () => {
+		expect(T.string.validateUsingKnownGoodVersion('a', 'b')).toBe('b')
+		expect(() => T.string.validateUsingKnownGoodVersion('a', 5)).toThrow(
+			'Expected string, got a number'
+		)
+	})
+})