@tldraw/store 5.2.0-next.ee0fa4d6244f → 5.2.1

package/src/lib/devFreeze.test.ts

@@ -1,141 +1,111 @@
-import { afterAll, beforeEach, describe, expect, it, MockedFunction, vi } from 'vitest'
+import { beforeEach, describe, expect, it, MockedFunction, vi } from 'vitest'
 import { devFreeze } from './devFreeze'
 import { isDev } from './isDev'
 
-// Mock process.env for testing
-const originalEnv = process.env.NODE_ENV
+// Tests for SPEC.md §24 (devFreeze).
+// Rule IDs like [DF1] in test names refer to that document.
+
 vi.mock('./isDev', () => ({
 	isDev: vi.fn(() => true),
 }))
 
-describe('devFreeze', () => {
+describe('devFreeze in dev/test builds (DF)', () => {
 	beforeEach(() => {
-		// Reset any mocks
 		vi.restoreAllMocks()
+		;(isDev as MockedFunction<typeof isDev>).mockReturnValue(true)
+	})
+
+	it('[DF1] recursively freezes the object and returns it', () => {
+		const obj = {
+			a: 1,
+			b: { c: 2, d: { e: 3 } },
+			f: [1, { g: 4 }],
+		}
+
+		const result = devFreeze(obj)
+
+		expect(result).toBe(obj)
+		expect(Object.isFrozen(result)).toBe(true)
+		expect(Object.isFrozen(result.b)).toBe(true)
+		expect(Object.isFrozen(result.b.d)).toBe(true)
+		expect(Object.isFrozen(result.f)).toBe(true)
+		expect(Object.isFrozen(result.f[1])).toBe(true)
+	})
+
+	it('[DF1] mutating a frozen object afterwards throws in strict mode', () => {
+		'use strict'
+		const obj = devFreeze({ a: 1 })
+		expect(() => {
+			;(obj as any).a = 2
+		}).toThrow()
+	})
+
+	it('[DF2] allows arrays, plain objects, null-prototype objects, and structured-clone objects', () => {
+		const obj = { a: 1 }
+		expect(() => devFreeze(obj)).not.toThrow()
+		expect(Object.isFrozen(obj)).toBe(true)
+
+		const nullProtoObj = Object.create(null)
+		nullProtoObj.a = 1
+		expect(() => devFreeze(nullProtoObj)).not.toThrow()
+		expect(Object.isFrozen(nullProtoObj)).toBe(true)
+
+		const arr = [1, 2, 3]
+		expect(() => devFreeze(arr)).not.toThrow()
+		expect(Object.isFrozen(arr)).toBe(true)
+
+		const cloned = structuredClone({ a: 1 })
+		expect(() => devFreeze(cloned)).not.toThrow()
+		expect(Object.isFrozen(cloned)).toBe(true)
 	})
 
-	describe('production mode behavior', () => {
-		beforeEach(() => {
-			// Mock production environment
-			;(isDev as MockedFunction<typeof isDev>).mockReturnValue(false)
-		})
-
-		it('should return objects unchanged in production mode', () => {
-			const obj = { a: 1, b: { c: 2 } }
-			const result = devFreeze(obj)
-
-			expect(result).toBe(obj) // Same reference
-			expect(Object.isFrozen(result)).toBe(false)
-			expect(Object.isFrozen(result.b)).toBe(false)
-		})
-
-		it('should not validate prototypes in production mode', () => {
-			const _consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => {})
-
-			// Create object with custom prototype that would normally throw
-			class CustomClass {
-				value = 42
-			}
-			const obj = new CustomClass()
-
-			expect(() => devFreeze(obj)).not.toThrow()
-			expect(_consoleSpy).not.toHaveBeenCalled()
-		})
+	it('[DF2] throws for objects with non-plain prototypes', () => {
+		vi.spyOn(console, 'error').mockImplementation(() => {})
+
+		class CustomClass {
+			value = 42
+		}
+		expect(() => devFreeze(new CustomClass())).toThrow('cannot include non-js data in a record')
+		expect(() => devFreeze(new Date())).toThrow('cannot include non-js data in a record')
+		expect(() => devFreeze(/regex/)).toThrow('cannot include non-js data in a record')
+		expect(() => devFreeze(new Map())).toThrow('cannot include non-js data in a record')
+		expect(() => devFreeze(new Set())).toThrow('cannot include non-js data in a record')
+
+		// also when nested inside an otherwise valid object
+		expect(() => devFreeze({ valid: { a: 1 }, invalid: new Date() })).toThrow(
+			'cannot include non-js data in a record'
+		)
 	})
 
-	describe('development mode behavior', () => {
-		beforeEach(() => {
-			// Mock development environment
-			vi.stubGlobal('process', { env: { NODE_ENV: 'development' } })
-		})
-
-		it('should freeze objects recursively', () => {
-			const obj = {
-				a: 1,
-				b: {
-					c: 2,
-					d: {
-						e: 3,
-					},
-				},
-				f: [1, { g: 4 }],
-			}
-
-			const result = devFreeze(obj)
-
-			expect(result).toBe(obj) // Same reference
-			expect(Object.isFrozen(result)).toBe(true)
-			expect(Object.isFrozen(result.b)).toBe(true)
-			expect(Object.isFrozen(result.b.d)).toBe(true)
-			expect(Object.isFrozen(result.f)).toBe(true)
-			expect(Object.isFrozen(result.f[1])).toBe(true)
-		})
-
-		it('should reject primitives', () => {
-			const _consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => {})
-
-			// Primitives have built-in prototypes that aren't allowed
-			expect(() => devFreeze('string')).toThrow('cannot include non-js data in a record')
-			expect(() => devFreeze(42)).toThrow('cannot include non-js data in a record')
-			expect(() => devFreeze(true)).toThrow('cannot include non-js data in a record')
-
-			// null and undefined cause TypeError when Object.getPrototypeOf is called
-			expect(() => devFreeze(null)).toThrow('Cannot convert undefined or null to object')
-			expect(() => devFreeze(undefined)).toThrow('Cannot convert undefined or null to object')
-		})
-
-		it('should allow valid prototypes', () => {
-			// Object.prototype
-			const obj = { a: 1 }
-			expect(() => devFreeze(obj)).not.toThrow()
-			expect(Object.isFrozen(obj)).toBe(true)
-
-			// null prototype
-			const nullProtoObj = Object.create(null)
-			nullProtoObj.a = 1
-			expect(() => devFreeze(nullProtoObj)).not.toThrow()
-			expect(Object.isFrozen(nullProtoObj)).toBe(true)
-
-			// Arrays
-			const arr = [1, 2, 3]
-			expect(() => devFreeze(arr)).not.toThrow()
-			expect(Object.isFrozen(arr)).toBe(true)
-
-			// structuredClone objects
-			const cloned = structuredClone({ a: 1 })
-			expect(() => devFreeze(cloned)).not.toThrow()
-			expect(Object.isFrozen(cloned)).toBe(true)
-		})
-
-		it('should reject invalid prototypes', () => {
-			const _consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => {})
-
-			// Custom class instances
-			class CustomClass {
-				value = 42
-			}
-			expect(() => devFreeze(new CustomClass())).toThrow('cannot include non-js data in a record')
-
-			// Built-in object types
-			expect(() => devFreeze(new Date())).toThrow('cannot include non-js data in a record')
-			expect(() => devFreeze(/regex/)).toThrow('cannot include non-js data in a record')
-			expect(() => devFreeze(new Map())).toThrow('cannot include non-js data in a record')
-			expect(() => devFreeze(new Set())).toThrow('cannot include non-js data in a record')
-
-			// Nested invalid objects
-			const objWithInvalidNested = {
-				valid: { a: 1 },
-				invalid: new Date(),
-			}
-			expect(() => devFreeze(objWithInvalidNested)).toThrow(
-				'cannot include non-js data in a record'
-			)
-		})
+	it('[DF2] throws for primitives, whose prototypes are not plain', () => {
+		expect(() => devFreeze('string')).toThrow('cannot include non-js data in a record')
+		expect(() => devFreeze(42)).toThrow('cannot include non-js data in a record')
+		expect(() => devFreeze(true)).toThrow('cannot include non-js data in a record')
 	})
+})
+
+describe('devFreeze in production builds (DF)', () => {
+	beforeEach(() => {
+		vi.restoreAllMocks()
+		;(isDev as MockedFunction<typeof isDev>).mockReturnValue(false)
+	})
+
+	it('[DF3] returns the object unchanged without freezing', () => {
+		const obj = { a: 1, b: { c: 2 } }
+		const result = devFreeze(obj)
+
+		expect(result).toBe(obj)
+		expect(Object.isFrozen(result)).toBe(false)
+		expect(Object.isFrozen(result.b)).toBe(false)
+	})
+
+	it('[DF3] does not validate prototypes', () => {
+		const consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => {})
 
-	// Clean up after all tests
-	afterAll(() => {
-		// Restore original environment
-		vi.stubGlobal('process', { env: { NODE_ENV: originalEnv } })
+		class CustomClass {
+			value = 42
+		}
+		expect(() => devFreeze(new CustomClass())).not.toThrow()
+		expect(consoleSpy).not.toHaveBeenCalled()
 	})
 })

package/src/lib/executeQuery.test.ts

@@ -5,6 +5,10 @@ import { createRecordType } from './RecordType'
 import { Store } from './Store'
 import { StoreSchema } from './StoreSchema'
 
+// Tests for SPEC.md §14 (query execution). Rule IDs like [QE1] in describe names refer to
+// that document. The "reactive nested queries" section also exercises §12's nested-path
+// indexes ([QI5]) through the reactive ids() machinery.
+
 // Test record types
 interface Author extends BaseRecord<'author', RecordId<Author>> {
 	name: string
@@ -299,8 +303,8 @@ beforeEach(() => {
 	store.put([...Object.values(authors), ...Object.values(books), ...Object.values(reviews)])
 })
 
-describe('objectMatchesQuery', () => {
-	describe('equality matching (eq)', () => {
+describe('objectMatchesQuery (QE)', () => {
+	describe('[QE1] equality matching (eq)', () => {
 		it('should match when property equals the target value', () => {
 			const book = books.foundation
 			const query = { inStock: { eq: true } }
@@ -316,7 +320,7 @@ describe('objectMatchesQuery', () => {
 		})
 	})
 
-	describe('inequality matching (neq)', () => {
+	describe('[QE1] inequality matching (neq)', () => {
 		it('should match when property does not equal the target value', () => {
 			const book = books.foundation // category: 'sci-fi'
 			const query = { category: { neq: 'romance' } }
@@ -330,9 +334,22 @@ describe('objectMatchesQuery', () => {
 
 			expect(objectMatchesQuery(query, book)).toBe(false)
 		})
+
+		it('should not match when the property is missing, mirroring the indexes', () => {
+			const bookWithoutStatus = books.foundation // metadata.status is undefined
+			const query = { metadata: { status: { neq: 'published' } } }
+
+			expect(
+				objectMatchesQuery(
+					// @ts-expect-error - status is optional so the matcher type rejects it
+					query,
+					bookWithoutStatus
+				)
+			).toBe(false)
+		})
 	})
 
-	describe('greater than matching (gt)', () => {
+	describe('[QE1] greater than matching (gt)', () => {
 		it('should match when numeric property is greater than target', () => {
 			const book = books.neuromancer // publishedYear: 1984
 			const query = { publishedYear: { gt: 1980 } }
@@ -355,7 +372,7 @@ describe('objectMatchesQuery', () => {
 		})
 	})
 
-	describe('multiple criteria matching', () => {
+	describe('[QE2] multiple criteria matching', () => {
 		it('should match when all criteria are satisfied', () => {
 			const book = books.foundation // inStock: true, publishedYear: 1951, category: 'sci-fi'
 			const query = {
@@ -379,7 +396,7 @@ describe('objectMatchesQuery', () => {
 		})
 	})
 
-	describe('nested object matching', () => {
+	describe('[QE3] nested object matching', () => {
 		it('should match when nested property satisfies criteria', () => {
 			const query = { metadata: { sessionId: { eq: 'session:alpha' } } }
 
@@ -410,7 +427,7 @@ describe('objectMatchesQuery', () => {
 		})
 	})
 
-	describe('edge cases', () => {
+	describe('[QE3] [QE4] edge cases', () => {
 		it('should return true for empty query', () => {
 			const book = books.foundation
 			const query = {}
@@ -433,8 +450,8 @@ describe('objectMatchesQuery', () => {
 	})
 })
 
-describe('executeQuery', () => {
-	describe('equality queries (eq)', () => {
+describe('executeQuery (QE)', () => {
+	describe('[QE1] [QE5] equality queries (eq)', () => {
 		it('should find records with matching string values', () => {
 			const query = { category: { eq: 'sci-fi' } }
 			const result = executeQuery(store.query, 'book', query)
@@ -466,7 +483,7 @@ describe('executeQuery', () => {
 		})
 	})
 
-	describe('inequality queries (neq)', () => {
+	describe('[QE1] [QE5] inequality queries (neq)', () => {
 		it('should find records that do not match string values', () => {
 			const query = { category: { neq: 'sci-fi' } }
 			const result = executeQuery(store.query, 'book', query)
@@ -481,7 +498,7 @@ describe('executeQuery', () => {
 		})
 	})
 
-	describe('greater than queries (gt)', () => {
+	describe('[QE1] [QE5] greater than queries (gt)', () => {
 		it('should find records with values greater than threshold', () => {
 			const query = { publishedYear: { gt: 1970 } }
 			const result = executeQuery(store.query, 'book', query)
@@ -499,7 +516,7 @@ describe('executeQuery', () => {
 		})
 	})
 
-	describe('combined queries', () => {
+	describe('[QE2] combined queries', () => {
 		it('should handle mixed query types', () => {
 			const query = {
 				inStock: { eq: true },
@@ -519,7 +536,7 @@ describe('executeQuery', () => {
 		})
 	})
 
-	describe('nested object queries', () => {
+	describe('[QE3] [QE5] nested object queries', () => {
 		it('should filter records using nested properties', () => {
 			const query = { metadata: { sessionId: { eq: 'session:alpha' } } }
 			const result = executeQuery(store.query, 'book', query)
@@ -558,7 +575,7 @@ describe('executeQuery', () => {
 		})
 	})
 
-	describe('edge cases', () => {
+	describe('[QE4] edge cases', () => {
 		it('should handle empty query', () => {
 			const query = {}
 			const result = executeQuery(store.query, 'book', query)
@@ -586,7 +603,7 @@ describe('executeQuery', () => {
 		})
 	})
 
-	describe('store integration', () => {
+	describe('[QE5] store integration', () => {
 		it('should update results when store changes', () => {
 			const query = { category: { eq: 'mystery' } }
 
@@ -612,8 +629,8 @@ describe('executeQuery', () => {
 	})
 })
 
-describe('reactive nested queries', () => {
-	describe('adding records', () => {
+describe('reactive nested queries (QE3, QI5, QQ)', () => {
+	describe('[QQ1] adding records', () => {
 		it('should include newly added record that matches nested query', () => {
 			const query = { metadata: { sessionId: { eq: 'session:delta' } } }
 			const idsQuery = store.query.ids('book', () => query)
@@ -709,7 +726,7 @@ describe('reactive nested queries', () => {
 		})
 	})
 
-	describe('removing records', () => {
+	describe('[QQ1] [QQ3] removing records', () => {
 		it('should remove record from results when it is deleted', () => {
 			const query = { metadata: { sessionId: { eq: 'session:alpha' } } }
 			const idsQuery = store.query.ids('book', () => query)
@@ -729,14 +746,14 @@ describe('reactive nested queries', () => {
 			const query = { metadata: { sessionId: { eq: 'session:alpha' } } }
 			const idsQuery = store.query.ids('book', () => query)
 
-			const initialIds = new Set([books.foundation.id, books.hitchhiker.id, books.robots.id])
-			expect(idsQuery.get()).toEqual(initialIds)
+			const before = idsQuery.get()
+			expect(before).toEqual(new Set([books.foundation.id, books.hitchhiker.id, books.robots.id]))
 
 			// Remove a non-matching book
 			store.remove([books.neuromancer.id])
 
-			// Results should be unchanged
-			expect(idsQuery.get()).toEqual(initialIds)
+			// the same Set object stays in place — downstream consumers observe no change
+			expect(idsQuery.get()).toBe(before)
 		})
 
 		it('should handle removing all matching records', () => {
@@ -755,7 +772,7 @@ describe('reactive nested queries', () => {
 		})
 	})
 
-	describe('updating records', () => {
+	describe('[QQ1] [QQ3] updating records', () => {
 		it('should add record to results when nested property is updated to match', () => {
 			const query = { metadata: { sessionId: { eq: 'session:omega' } } }
 			const idsQuery = store.query.ids('book', () => query)
@@ -842,8 +859,8 @@ describe('reactive nested queries', () => {
 			const query = { metadata: { sessionId: { eq: 'session:alpha' } } }
 			const idsQuery = store.query.ids('book', () => query)
 
-			const initialIds = new Set([books.foundation.id, books.hitchhiker.id, books.robots.id])
-			expect(idsQuery.get()).toEqual(initialIds)
+			const before = idsQuery.get()
+			expect(before).toEqual(new Set([books.foundation.id, books.hitchhiker.id, books.robots.id]))
 
 			// Update a non-nested property (title) but keep nested property the same
 			store.put([
@@ -853,12 +870,12 @@ describe('reactive nested queries', () => {
 				},
 			])
 
-			// Results should be unchanged
-			expect(idsQuery.get()).toEqual(initialIds)
+			// the same Set object stays in place — downstream consumers observe no change
+			expect(idsQuery.get()).toBe(before)
 		})
 	})
 
-	describe('combined nested and top-level queries', () => {
+	describe('[QE2] [QE3] combined nested and top-level queries', () => {
 		it('should correctly update when top-level property changes', () => {
 			const query = {
 				inStock: { eq: true },
@@ -982,7 +999,7 @@ describe('reactive nested queries', () => {
 		})
 	})
 
-	describe('query operators with nested properties', () => {
+	describe('[QE1] [QI5] query operators with nested properties', () => {
 		it('should handle gt operator on nested properties', () => {
 			// Add some books with different copy counts
 			const bookLowCopies = Book.create({
@@ -1162,6 +1179,35 @@ describe('reactive nested queries', () => {
 			expect(idsQuery.get()).toEqual(new Set([bookWithArchivedStatus.id]))
 		})
 
+		it('[QE5] from-scratch and incremental evaluation agree for neq with missing values', () => {
+			const bookWithoutStatus = Book.create({
+				title: 'Book Without Status',
+				authorId: authors.herbert.id,
+				publishedYear: 2022,
+				inStock: true,
+				metadata: {
+					sessionId: 'session:test',
+					extras: { region: 'us' },
+				},
+			})
+			store.put([bookWithoutStatus])
+
+			const query = { metadata: { status: { neq: 'published' } } }
+			const idsQuery = store.query.ids(
+				'book',
+				// @ts-expect-error - status is optional so the matcher type rejects it
+				() => query
+			)
+
+			// from scratch: the record without a status is not included
+			expect(idsQuery.get().has(bookWithoutStatus.id)).toBe(false)
+
+			// an unrelated update to that record must not change its membership
+			// through the incremental path either
+			store.put([{ ...bookWithoutStatus, title: 'Renamed' }])
+			expect(idsQuery.get().has(bookWithoutStatus.id)).toBe(false)
+		})
+
 		it('should handle multiple nested criteria with updates', () => {
 			const query = {
 				metadata: {
@@ -1199,7 +1245,7 @@ describe('reactive nested queries', () => {
 		})
 	})
 
-	describe('multiple subscribers', () => {
+	describe('[QQ1] multiple subscribers', () => {
 		it('should update all subscribers when records change', () => {
 			const query = { metadata: { sessionId: { eq: 'session:theta' } } }
 			const idsQuery1 = store.query.ids('book', () => query)
@@ -1270,7 +1316,7 @@ describe('reactive nested queries', () => {
 		})
 	})
 
-	describe('batch operations', () => {
+	describe('[QQ1] batch operations', () => {
 		it('should handle batch updates affecting nested queries', () => {
 			const query = { metadata: { extras: { region: { eq: 'canada' } } } }
 			const idsQuery = store.query.ids('book', () => query)

package/src/lib/executeQuery.ts

@@ -90,7 +90,9 @@ export function objectMatchesQuery<T extends object>(query: QueryExpression<T>,
 		// matching logic
 		if (isQueryValueMatcher(matcher)) {
 			if ('eq' in matcher && value !== matcher.eq) return false
-			if ('neq' in matcher && value === matcher.neq) return false
+			// undefined values must not match neq: the indexes executeQuery reads only
+			// track defined values, and the two matching strategies have to agree
+			if ('neq' in matcher && (value === matcher.neq || value === undefined)) return false
 			if ('gt' in matcher && (typeof value !== 'number' || value <= matcher.gt)) return false
 			continue
 		}