@tldraw/store 4.1.0-canary.af5f4bce7236 → 4.1.0-canary.b34d5b101192

package/src/lib/StoreQueries.ts

@@ -16,30 +16,92 @@ import { RecordsDiff } from './RecordsDiff'
 import { diffSets } from './setUtils'
 import { CollectionDiff } from './Store'
 
-/** @public */
+/**
+ * A type representing the diff of changes to a reactive store index.
+ * Maps property values to the collection differences for record IDs that have that property value.
+ *
+ * @example
+ * ```ts
+ * // For an index on book titles, the diff might look like:
+ * const titleIndexDiff: RSIndexDiff<Book, 'title'> = new Map([
+ *   ['The Lathe of Heaven', { added: new Set(['book:1']), removed: new Set() }],
+ *   ['Animal Farm', { added: new Set(), removed: new Set(['book:2']) }]
+ * ])
+ * ```
+ *
+ * @public
+ */
 export type RSIndexDiff<
 	R extends UnknownRecord,
 	Property extends string & keyof R = string & keyof R,
 > = Map<R[Property], CollectionDiff<IdOf<R>>>
 
-/** @public */
+/**
+ * A type representing a reactive store index as a map from property values to sets of record IDs.
+ * This is used to efficiently look up records by a specific property value.
+ *
+ * @example
+ * ```ts
+ * // Index mapping book titles to the IDs of books with that title
+ * const titleIndex: RSIndexMap<Book, 'title'> = new Map([
+ *   ['The Lathe of Heaven', new Set(['book:1'])],
+ *   ['Animal Farm', new Set(['book:2', 'book:3'])]
+ * ])
+ * ```
+ *
+ * @public
+ */
 export type RSIndexMap<
 	R extends UnknownRecord,
 	Property extends string & keyof R = string & keyof R,
 > = Map<R[Property], Set<IdOf<R>>>
 
-/** @public */
+/**
+ * A reactive computed index that provides efficient lookups of records by property values.
+ * Returns a computed value containing an RSIndexMap with diffs for change tracking.
+ *
+ * @example
+ * ```ts
+ * // Create an index on book authors
+ * const authorIndex: RSIndex<Book, 'authorId'> = store.query.index('book', 'authorId')
+ *
+ * // Get all books by a specific author
+ * const leguinBooks = authorIndex.get().get('author:leguin')
+ * ```
+ *
+ * @public
+ */
 export type RSIndex<
 	R extends UnknownRecord,
 	Property extends string & keyof R = string & keyof R,
 > = Computed<RSIndexMap<R, Property>, RSIndexDiff<R, Property>>
 
 /**
- * A class that provides a 'namespace' for the various kinds of indexes one may wish to derive from
- * the record store.
+ * A class that provides reactive querying capabilities for a record store.
+ * Offers methods to create indexes, filter records, and perform efficient lookups with automatic cache management.
+ * All queries are reactive and will automatically update when the underlying store data changes.
+ *
+ * @example
+ * ```ts
+ * // Create a store with books
+ * const store = new Store({ schema: StoreSchema.create({ book: Book, author: Author }) })
+ *
+ * // Get reactive queries for books
+ * const booksByAuthor = store.query.index('book', 'authorId')
+ * const inStockBooks = store.query.records('book', () => ({ inStock: { eq: true } }))
+ * ```
+ *
  * @public
  */
 export class StoreQueries<R extends UnknownRecord> {
+	/**
+	 * Creates a new StoreQueries instance.
+	 *
+	 * recordMap - The atom map containing all records in the store
+	 * history - The atom tracking the store's change history with diffs
+	 *
+	 * @internal
+	 */
 	constructor(
 		private readonly recordMap: AtomMap<IdOf<R>, R>,
 		private readonly history: Atom<number, RecordsDiff<R>>
@@ -60,10 +122,25 @@ export class StoreQueries<R extends UnknownRecord> {
 	private historyCache = new Map<string, Computed<number, RecordsDiff<R>>>()
 
 	/**
-	 * Create a derivation that contains the history for a given type
+	 * Creates a reactive computed that tracks the change history for records of a specific type.
+	 * The returned computed provides incremental diffs showing what records of the given type
+	 * have been added, updated, or removed.
+	 *
+	 * @param typeName - The type name to filter the history by
+	 * @returns A computed value containing the current epoch and diffs of changes for the specified type
+	 *
+	 * @example
+	 * ```ts
+	 * // Track changes to book records only
+	 * const bookHistory = store.query.filterHistory('book')
+	 *
+	 * // React to book changes
+	 * react('book-changes', () => {
+	 *   const currentEpoch = bookHistory.get()
+	 *   console.log('Books updated at epoch:', currentEpoch)
+	 * })
+	 * ```
 	 *
-	 * @param typeName - The name of the type to filter by.
-	 * @returns A derivation that returns the ids of all records of the given type.
 	 * @public
 	 */
 	public filterHistory<TypeName extends R['typeName']>(
@@ -156,10 +233,28 @@ export class StoreQueries<R extends UnknownRecord> {
 	}
 
 	/**
-	 * Create a derivation that returns an index on a property for the given type.
+	 * Creates a reactive index that maps property values to sets of record IDs for efficient lookups.
+	 * The index automatically updates when records are added, updated, or removed, and results are cached
+	 * for performance.
+	 *
+	 * @param typeName - The type name of records to index
+	 * @param property - The property name to index by
+	 * @returns A reactive computed containing the index map with change diffs
+	 *
+	 * @example
+	 * ```ts
+	 * // Create an index of books by author ID
+	 * const booksByAuthor = store.query.index('book', 'authorId')
+	 *
+	 * // Get all books by a specific author
+	 * const authorBooks = booksByAuthor.get().get('author:leguin')
+	 * console.log(authorBooks) // Set<RecordId<Book>>
+	 *
+	 * // Index by title for quick title lookups
+	 * const booksByTitle = store.query.index('book', 'title')
+	 * const booksLatheOfHeaven = booksByTitle.get().get('The Lathe of Heaven')
+	 * ```
 	 *
-	 * @param typeName - The name of the type.
-	 * @param property - The name of the property.
 	 * @public
 	 */
 	public index<
@@ -180,10 +275,13 @@ export class StoreQueries<R extends UnknownRecord> {
 	}
 
 	/**
-	 * Create a derivation that returns an index on a property for the given type.
+	 * Creates a new index without checking the cache. This method performs the actual work
+	 * of building the reactive index computation that tracks property values to record ID sets.
+	 *
+	 * @param typeName - The type name of records to index
+	 * @param property - The property name to index by
+	 * @returns A reactive computed containing the index map with change diffs
 	 *
-	 * @param typeName - The name of the type?.
-	 * @param property - The name of the property?.
 	 * @internal
 	 */
 	__uncached_createIndex<
@@ -293,13 +391,26 @@ export class StoreQueries<R extends UnknownRecord> {
 	}
 
 	/**
-	 * Create a derivation that will return a signle record matching the given query.
+	 * Creates a reactive query that returns the first record matching the given query criteria.
+	 * Returns undefined if no matching record is found. The query automatically updates
+	 * when records change.
+	 *
+	 * @param typeName - The type name of records to query
+	 * @param queryCreator - Function that returns the query expression object to match against
+	 * @param name - Optional name for the query computation (used for debugging)
+	 * @returns A computed value containing the first matching record or undefined
+	 *
+	 * @example
+	 * ```ts
+	 * // Find the first book with a specific title
+	 * const bookLatheOfHeaven = store.query.record('book', () => ({ title: { eq: 'The Lathe of Heaven' } }))
+	 * console.log(bookLatheOfHeaven.get()?.title) // 'The Lathe of Heaven' or undefined
 	 *
-	 * It will return undefined if there is no matching record
+	 * // Find any book in stock
+	 * const anyInStockBook = store.query.record('book', () => ({ inStock: { eq: true } }))
+	 * ```
 	 *
-	 * @param typeName - The name of the type?
-	 * @param queryCreator - A function that returns the query expression.
-	 * @param name - (optional) The name of the query.
+	 * @public
 	 */
 	record<TypeName extends R['typeName']>(
 		typeName: TypeName,
@@ -318,11 +429,28 @@ export class StoreQueries<R extends UnknownRecord> {
 	}
 
 	/**
-	 * Create a derivation that will return an array of records matching the given query
+	 * Creates a reactive query that returns an array of all records matching the given query criteria.
+	 * The array automatically updates when records are added, updated, or removed.
+	 *
+	 * @param typeName - The type name of records to query
+	 * @param queryCreator - Function that returns the query expression object to match against
+	 * @param name - Optional name for the query computation (used for debugging)
+	 * @returns A computed value containing an array of all matching records
+	 *
+	 * @example
+	 * ```ts
+	 * // Get all books in stock
+	 * const inStockBooks = store.query.records('book', () => ({ inStock: { eq: true } }))
+	 * console.log(inStockBooks.get()) // Book[]
 	 *
-	 * @param typeName - The name of the type?
-	 * @param queryCreator - A function that returns the query expression.
-	 * @param name - (optinal) The name of the query.
+	 * // Get all books by a specific author
+	 * const leguinBooks = store.query.records('book', () => ({ authorId: { eq: 'author:leguin' } }))
+	 *
+	 * // Get all books (no filter)
+	 * const allBooks = store.query.records('book')
+	 * ```
+	 *
+	 * @public
 	 */
 	records<TypeName extends R['typeName']>(
 		typeName: TypeName,
@@ -344,11 +472,29 @@ export class StoreQueries<R extends UnknownRecord> {
 	}
 
 	/**
-	 * Create a derivation that will return the ids of all records of the given type.
+	 * Creates a reactive query that returns a set of record IDs matching the given query criteria.
+	 * This is more efficient than `records()` when you only need the IDs and not the full record objects.
+	 * The set automatically updates with collection diffs when records change.
+	 *
+	 * @param typeName - The type name of records to query
+	 * @param queryCreator - Function that returns the query expression object to match against
+	 * @param name - Optional name for the query computation (used for debugging)
+	 * @returns A computed value containing a set of matching record IDs with collection diffs
+	 *
+	 * @example
+	 * ```ts
+	 * // Get IDs of all books in stock
+	 * const inStockBookIds = store.query.ids('book', () => ({ inStock: { eq: true } }))
+	 * console.log(inStockBookIds.get()) // Set<RecordId<Book>>
 	 *
-	 * @param typeName - The name of the type.
-	 * @param queryCreator - A function that returns the query expression.
-	 * @param name - (optinal) The name of the query.
+	 * // Get all book IDs (no filter)
+	 * const allBookIds = store.query.ids('book')
+	 *
+	 * // Use with other queries for efficient lookups
+	 * const authorBookIds = store.query.ids('book', () => ({ authorId: { eq: 'author:leguin' } }))
+	 * ```
+	 *
+	 * @public
 	 */
 	ids<TypeName extends R['typeName']>(
 		typeName: TypeName,
@@ -446,6 +592,27 @@ export class StoreQueries<R extends UnknownRecord> {
 		)
 	}
 
+	/**
+	 * Executes a one-time query against the current store state and returns matching records.
+	 * This is a non-reactive query that returns results immediately without creating a computed value.
+	 * Use this when you need a snapshot of data at a specific point in time.
+	 *
+	 * @param typeName - The type name of records to query
+	 * @param query - The query expression object to match against
+	 * @returns An array of records that match the query at the current moment
+	 *
+	 * @example
+	 * ```ts
+	 * // Get current in-stock books (non-reactive)
+	 * const currentInStockBooks = store.query.exec('book', { inStock: { eq: true } })
+	 * console.log(currentInStockBooks) // Book[]
+	 *
+	 * // Unlike records(), this won't update when the data changes
+	 * const staticBookList = store.query.exec('book', { authorId: { eq: 'author:leguin' } })
+	 * ```
+	 *
+	 * @public
+	 */
 	exec<TypeName extends R['typeName']>(
 		typeName: TypeName,
 		query: QueryExpression<Extract<R, { typeName: TypeName }>>

package/src/lib/StoreSchema.test.ts

@@ -0,0 +1,226 @@
+import { describe, expect, it, vi } from 'vitest'
+import { BaseRecord, RecordId } from './BaseRecord'
+import { createRecordType } from './RecordType'
+import { Store } from './Store'
+import { StoreSchema } from './StoreSchema'
+import { createMigrationSequence } from './migrate'
+
+// Test record types
+interface Book extends BaseRecord<'book', RecordId<Book>> {
+	title: string
+	author: string
+	publishedYear: number
+	genre?: string
+	inStock?: boolean
+}
+
+const Book = createRecordType<Book>('book', {
+	validator: { validate: (book) => book as Book },
+	scope: 'document',
+}).withDefaultProperties(() => ({
+	inStock: true,
+	publishedYear: 2023,
+}))
+
+interface Author extends BaseRecord<'author', RecordId<Author>> {
+	name: string
+	birthYear: number
+	isAlive?: boolean
+}
+
+const Author = createRecordType<Author>('author', {
+	validator: { validate: (author) => author as Author },
+	scope: 'document',
+}).withDefaultProperties(() => ({
+	isAlive: true,
+}))
+
+describe('StoreSchema', () => {
+	describe('create', () => {
+		it('validates migration dependencies during creation', () => {
+			const invalidMigrations = createMigrationSequence({
+				sequenceId: 'com.tldraw.book',
+				sequence: [
+					{
+						id: 'com.tldraw.book/1',
+						scope: 'record',
+						dependsOn: ['com.tldraw.book/999'],
+						up: (record: any) => record,
+					},
+				],
+			})
+
+			expect(() => {
+				StoreSchema.create({ book: Book }, { migrations: [invalidMigrations] })
+			}).toThrow()
+		})
+
+		it('prevents duplicate migration sequence IDs', () => {
+			const migration1 = createMigrationSequence({
+				sequenceId: 'com.tldraw.book',
+				sequence: [
+					{
+						id: 'com.tldraw.book/1',
+						scope: 'record',
+						up: (record: any) => record,
+					},
+				],
+			})
+
+			const migration2 = createMigrationSequence({
+				sequenceId: 'com.tldraw.book', // Same ID
+				sequence: [
+					{
+						id: 'com.tldraw.book/1',
+						scope: 'record',
+						up: (record: any) => record,
+					},
+				],
+			})
+
+			expect(() => {
+				StoreSchema.create({ book: Book }, { migrations: [migration1, migration2] })
+			}).toThrow('Duplicate migration sequenceId com.tldraw.book')
+		})
+	})
+
+	describe('validateRecord', () => {
+		it('throws for invalid record without validation failure handler', () => {
+			// Create a validator that actually throws
+			const StrictBook = createRecordType<Book>('book', {
+				validator: {
+					validate: (book) => {
+						if (!(book as any).title || !(book as any).author) {
+							throw new Error('Missing required fields')
+						}
+						return book as Book
+					},
+				},
+				scope: 'document',
+			})
+
+			const schema = StoreSchema.create({ book: StrictBook })
+			const store = new Store({ schema, props: {} })
+
+			// Missing required fields
+			const invalidBook = {
+				id: StrictBook.createId(),
+				typeName: 'book' as const,
+				// Missing title, author, publishedYear
+			} as any
+
+			expect(() => {
+				schema.validateRecord(store, invalidBook, 'createRecord', null)
+			}).toThrow('Missing required fields')
+		})
+
+		it('calls validation failure handler for invalid record', () => {
+			const onValidationFailure = vi.fn().mockReturnValue({
+				id: Book.createId(),
+				typeName: 'book' as const,
+				title: 'Fixed Title',
+				author: 'Fixed Author',
+				publishedYear: 2023,
+				inStock: true,
+			})
+
+			// Create a validator that throws
+			const StrictBook = createRecordType<Book>('book', {
+				validator: {
+					validate: (book) => {
+						if (!(book as any).title || !(book as any).author) {
+							throw new Error('Missing required fields')
+						}
+						return book as Book
+					},
+				},
+				scope: 'document',
+			})
+
+			const schema = StoreSchema.create({ book: StrictBook }, { onValidationFailure })
+			const store = new Store({ schema, props: {} })
+
+			const invalidBook = {
+				id: StrictBook.createId(),
+				typeName: 'book' as const,
+			} as any
+
+			const result = schema.validateRecord(store, invalidBook, 'createRecord', null)
+
+			expect(onValidationFailure).toHaveBeenCalledWith({
+				store,
+				record: invalidBook,
+				phase: 'createRecord',
+				recordBefore: null,
+				error: expect.any(Error),
+			})
+			expect(result.title).toBe('Fixed Title')
+		})
+
+		it('throws for unknown record type', () => {
+			const schema = StoreSchema.create({ book: Book })
+			const store = new Store({ schema, props: {} })
+
+			const unknownRecord = {
+				id: 'unknown:1',
+				typeName: 'unknown',
+			} as any
+
+			expect(() => {
+				schema.validateRecord(store, unknownRecord, 'createRecord', null)
+			}).toThrow('Missing definition for record type unknown')
+		})
+	})
+
+	describe('createIntegrityChecker', () => {
+		it('calls createIntegrityChecker option when provided', () => {
+			const createIntegrityChecker = vi.fn()
+			const schema = StoreSchema.create({ book: Book }, { createIntegrityChecker })
+			const store = new Store({ schema, props: {} })
+
+			schema.createIntegrityChecker(store)
+
+			expect(createIntegrityChecker).toHaveBeenCalledWith(store)
+		})
+	})
+
+	describe('serialize', () => {
+		it('serializes schema with current migration versions', () => {
+			const bookMigrations = createMigrationSequence({
+				sequenceId: 'com.tldraw.book',
+				sequence: [
+					{ id: 'com.tldraw.book/1', scope: 'record', up: (r: any) => r },
+					{ id: 'com.tldraw.book/2', scope: 'record', up: (r: any) => r },
+				],
+			})
+
+			const authorMigrations = createMigrationSequence({
+				sequenceId: 'com.tldraw.author',
+				sequence: [{ id: 'com.tldraw.author/1', scope: 'record', up: (r: any) => r }],
+			})
+
+			const schema = StoreSchema.create(
+				{ book: Book, author: Author },
+				{ migrations: [bookMigrations, authorMigrations] }
+			)
+
+			const serialized = schema.serialize()
+
+			expect(serialized).toEqual({
+				schemaVersion: 2,
+				sequences: {
+					'com.tldraw.book': 2,
+					'com.tldraw.author': 1,
+				},
+			})
+		})
+	})
+
+	describe('getType', () => {
+		it('throws for invalid type name', () => {
+			const schema = StoreSchema.create({ book: Book })
+
+			expect(() => schema.getType('nonexistent')).toThrow('record type does not exists')
+		})
+	})
+})