@tldraw/tlschema 4.1.0-next.b6dfe9bccde9 → 4.1.0-next.cb6f90590225

package/src/records/TLAsset.test.ts

@@ -0,0 +1,234 @@
+import { describe, expect, it } from 'vitest'
+import { getTestMigration } from '../__tests__/migrationTestUtils'
+import {
+	assetMigrations,
+	AssetRecordType,
+	assetValidator,
+	assetVersions,
+	TLAssetId,
+} from './TLAsset'
+
+describe('TLAsset', () => {
+	describe('assetValidator', () => {
+		it('should validate different asset types using discriminated union', () => {
+			const imageAsset = {
+				id: 'asset:test_image',
+				typeName: 'asset' as const,
+				type: 'image' as const,
+				props: {
+					w: 100,
+					h: 100,
+					name: 'test.jpg',
+					isAnimated: false,
+					mimeType: 'image/jpeg',
+					src: 'https://example.com/test.jpg',
+				},
+				meta: {},
+			}
+
+			const videoAsset = {
+				id: 'asset:test_video',
+				typeName: 'asset' as const,
+				type: 'video' as const,
+				props: {
+					w: 640,
+					h: 480,
+					name: 'test.mp4',
+					isAnimated: true,
+					mimeType: 'video/mp4',
+					src: 'https://example.com/test.mp4',
+				},
+				meta: {},
+			}
+
+			const bookmarkAsset = {
+				id: 'asset:test_bookmark',
+				typeName: 'asset' as const,
+				type: 'bookmark' as const,
+				props: {
+					title: 'Test Site',
+					description: 'A test bookmark',
+					image: 'https://example.com/image.png',
+					favicon: 'https://example.com/favicon.ico',
+					src: 'https://example.com',
+				},
+				meta: {},
+			}
+
+			expect(() => assetValidator.validate(imageAsset)).not.toThrow()
+			expect(() => assetValidator.validate(videoAsset)).not.toThrow()
+			expect(() => assetValidator.validate(bookmarkAsset)).not.toThrow()
+
+			expect(assetValidator.validate(imageAsset).type).toBe('image')
+			expect(assetValidator.validate(videoAsset).type).toBe('video')
+			expect(assetValidator.validate(bookmarkAsset).type).toBe('bookmark')
+		})
+
+		it('should reject invalid asset types', () => {
+			const invalidAsset = {
+				id: 'asset:invalid',
+				typeName: 'asset' as const,
+				type: 'invalid_type' as any,
+				props: {
+					w: 100,
+					h: 100,
+					name: 'test.jpg',
+				},
+				meta: {},
+			}
+
+			expect(() => assetValidator.validate(invalidAsset)).toThrow()
+		})
+
+		it('should require valid asset structure', () => {
+			// Wrong typeName
+			const wrongTypeName = {
+				id: 'asset:wrong_typename',
+				typeName: 'shape' as const,
+				type: 'image' as const,
+				props: {
+					w: 100,
+					h: 100,
+					name: 'test.jpg',
+					isAnimated: false,
+					mimeType: 'image/jpeg',
+					src: 'https://example.com/test.jpg',
+				},
+				meta: {},
+			}
+			expect(() => assetValidator.validate(wrongTypeName)).toThrow()
+
+			// Missing meta
+			const noMeta = {
+				id: 'asset:no_meta',
+				typeName: 'asset' as const,
+				type: 'image' as const,
+				props: {
+					w: 100,
+					h: 100,
+					name: 'test.jpg',
+					isAnimated: false,
+					mimeType: 'image/jpeg',
+					src: 'https://example.com/test.jpg',
+				},
+			}
+			expect(() => assetValidator.validate(noMeta)).toThrow()
+
+			// Wrong ID prefix
+			const wrongId = {
+				id: 'shape:wrong_prefix',
+				typeName: 'asset' as const,
+				type: 'image' as const,
+				props: {
+					w: 100,
+					h: 100,
+					name: 'test.jpg',
+					isAnimated: false,
+					mimeType: 'image/jpeg',
+					src: 'https://example.com/test.jpg',
+				},
+				meta: {},
+			}
+			expect(() => assetValidator.validate(wrongId)).toThrow()
+		})
+	})
+
+	describe('assetMigrations', () => {
+		it('should have correct migration structure', () => {
+			expect(assetMigrations.sequenceId).toBe('com.tldraw.asset')
+			expect(assetMigrations.sequence).toHaveLength(1)
+			expect(assetMigrations.sequence[0].id).toBe(assetVersions.AddMeta)
+		})
+	})
+
+	describe('AddMeta migration', () => {
+		const { up } = getTestMigration(assetVersions.AddMeta)
+
+		it('should add empty meta property', () => {
+			const assetWithoutMeta = {
+				id: 'asset:test',
+				typeName: 'asset',
+				type: 'image',
+				props: {
+					w: 100,
+					h: 100,
+					name: 'test.jpg',
+					isAnimated: false,
+					mimeType: 'image/jpeg',
+					src: 'https://example.com/test.jpg',
+				},
+			}
+
+			const result = up(assetWithoutMeta)
+			expect(result.meta).toEqual({})
+			expect(result.props).toEqual(assetWithoutMeta.props)
+		})
+
+		it('should overwrite existing meta property', () => {
+			const assetWithMeta = {
+				id: 'asset:test',
+				typeName: 'asset',
+				type: 'image',
+				props: {
+					w: 100,
+					h: 100,
+					name: 'test.jpg',
+					isAnimated: false,
+					mimeType: 'image/jpeg',
+					src: 'https://example.com/test.jpg',
+				},
+				meta: { existing: 'data' },
+			}
+
+			const result = up(assetWithMeta)
+			expect(result.meta).toEqual({}) // Migration always sets to empty object
+		})
+
+		it('should preserve other properties during migration', () => {
+			const assetWithExtraProps = {
+				id: 'asset:extra_props',
+				typeName: 'asset',
+				type: 'image',
+				props: {
+					w: 200,
+					h: 150,
+					name: 'extra.png',
+					isAnimated: false,
+					mimeType: 'image/png',
+					src: 'https://example.com/extra.png',
+				},
+				customProperty: 'should be preserved',
+			}
+
+			const result = up(assetWithExtraProps)
+			expect(result.meta).toEqual({})
+			expect(result.customProperty).toBe('should be preserved')
+		})
+	})
+
+	describe('AssetRecordType', () => {
+		it('should have correct configuration', () => {
+			expect(AssetRecordType.typeName).toBe('asset')
+			expect(AssetRecordType.scope).toBe('document')
+			expect(AssetRecordType.validator).toBe(assetValidator)
+		})
+
+		it('should create records with default meta property', () => {
+			const assetRecord = AssetRecordType.create({
+				id: 'asset:test' as TLAssetId,
+				type: 'image',
+				props: {
+					w: 100,
+					h: 100,
+					name: 'test.jpg',
+					isAnimated: false,
+					mimeType: 'image/jpeg',
+					src: 'https://example.com/test.jpg',
+				},
+			})
+
+			expect(assetRecord.meta).toEqual({})
+			expect(assetRecord.typeName).toBe('asset')
+		})
+	})
+})

package/src/records/TLAsset.ts

@@ -11,10 +11,48 @@ import { imageAssetValidator, TLImageAsset } from '../assets/TLImageAsset'
 import { TLVideoAsset, videoAssetValidator } from '../assets/TLVideoAsset'
 import { TLShape } from './TLShape'
 
-/** @public */
+/**
+ * Union type representing all possible asset types in tldraw.
+ * Assets represent external resources like images, videos, or bookmarks that can be referenced by shapes.
+ *
+ * @example
+ * ```ts
+ * const imageAsset: TLAsset = {
+ *   id: 'asset:image123',
+ *   typeName: 'asset',
+ *   type: 'image',
+ *   props: {
+ *     src: 'https://example.com/image.jpg',
+ *     w: 800,
+ *     h: 600,
+ *     mimeType: 'image/jpeg',
+ *     isAnimated: false
+ *   },
+ *   meta: {}
+ * }
+ * ```
+ *
+ * @public
+ */
 export type TLAsset = TLImageAsset | TLVideoAsset | TLBookmarkAsset
 
-/** @public */
+/**
+ * Validator for TLAsset records that ensures runtime type safety.
+ * Uses a discriminated union based on the 'type' field to validate different asset types.
+ *
+ * @example
+ * ```ts
+ * // Validation happens automatically when assets are stored
+ * try {
+ *   const validatedAsset = assetValidator.validate(assetData)
+ *   store.put([validatedAsset])
+ * } catch (error) {
+ *   console.error('Asset validation failed:', error.message)
+ * }
+ * ```
+ *
+ * @public
+ */
 export const assetValidator: T.Validator<TLAsset> = T.model(
 	'asset',
 	T.union('type', {
@@ -24,12 +62,37 @@ export const assetValidator: T.Validator<TLAsset> = T.model(
 	})
 )
 
-/** @public */
+/**
+ * Migration version identifiers for asset record schema evolution.
+ * Each version represents a breaking change that requires data migration.
+ *
+ * @example
+ * ```ts
+ * // Check if a migration is needed
+ * const needsMigration = currentVersion < assetVersions.AddMeta
+ * ```
+ *
+ * @public
+ */
 export const assetVersions = createMigrationIds('com.tldraw.asset', {
 	AddMeta: 1,
 } as const)
 
-/** @public */
+/**
+ * Migration sequence for evolving asset record structure over time.
+ * Handles converting asset records from older schema versions to current format.
+ *
+ * @example
+ * ```ts
+ * // Migration is applied automatically when loading old documents
+ * const migratedStore = migrator.migrateStoreSnapshot({
+ *   schema: oldSchema,
+ *   store: oldStoreSnapshot
+ * })
+ * ```
+ *
+ * @public
+ */
 export const assetMigrations = createRecordMigrationSequence({
 	sequenceId: 'com.tldraw.asset',
 	recordType: 'asset',
@@ -43,7 +106,27 @@ export const assetMigrations = createRecordMigrationSequence({
 	],
 })
 
-/** @public */
+/**
+ * Partial type for TLAsset allowing optional properties except id and type.
+ * Useful for creating or updating assets where not all properties need to be specified.
+ *
+ * @example
+ * ```ts
+ * // Create a partial asset for updating
+ * const partialAsset: TLAssetPartial<TLImageAsset> = {
+ *   id: 'asset:image123',
+ *   type: 'image',
+ *   props: {
+ *     w: 800 // Only updating width
+ *   }
+ * }
+ *
+ * // Use in asset updates
+ * editor.updateAssets([partialAsset])
+ * ```
+ *
+ * @public
+ */
 export type TLAssetPartial<T extends TLAsset = TLAsset> = T extends T
 	? {
 			id: TLAssetId
@@ -53,7 +136,31 @@ export type TLAssetPartial<T extends TLAsset = TLAsset> = T extends T
 		} & Partial<Omit<T, 'type' | 'id' | 'props' | 'meta'>>
 	: never
 
-/** @public */
+/**
+ * Record type definition for TLAsset with validation and default properties.
+ * Configures assets as document-scoped records that persist across sessions.
+ *
+ * @example
+ * ```ts
+ * // Create a new asset record
+ * const assetRecord = AssetRecordType.create({
+ *   id: 'asset:image123',
+ *   type: 'image',
+ *   props: {
+ *     src: 'https://example.com/image.jpg',
+ *     w: 800,
+ *     h: 600,
+ *     mimeType: 'image/jpeg',
+ *     isAnimated: false
+ *   }
+ * })
+ *
+ * // Store the asset
+ * store.put([assetRecord])
+ * ```
+ *
+ * @public
+ */
 export const AssetRecordType = createRecordType<TLAsset>('asset', {
 	validator: assetValidator,
 	scope: 'document',
@@ -61,8 +168,58 @@ export const AssetRecordType = createRecordType<TLAsset>('asset', {
 	meta: {},
 }))
 
-/** @public */
+/**
+ * Branded string type for asset record identifiers.
+ * Prevents mixing asset IDs with other types of record IDs at compile time.
+ *
+ * @example
+ * ```ts
+ * import { createAssetId } from '@tldraw/tlschema'
+ *
+ * // Create a new asset ID
+ * const assetId: TLAssetId = createAssetId()
+ *
+ * // Use in asset records
+ * const asset: TLAsset = {
+ *   id: assetId,
+ *   // ... other properties
+ * }
+ *
+ * // Reference in shapes
+ * const imageShape: TLImageShape = {
+ *   props: {
+ *     assetId: assetId,
+ *     // ... other properties
+ *   }
+ * }
+ * ```
+ *
+ * @public
+ */
 export type TLAssetId = RecordId<TLBaseAsset<any, any>>
 
-/** @public */
+/**
+ * Union type of all shapes that reference assets through an assetId property.
+ * Includes image shapes, video shapes, and any other shapes that depend on external assets.
+ *
+ * @example
+ * ```ts
+ * // Function that works with any asset-based shape
+ * function handleAssetShape(shape: TLAssetShape) {
+ *   const assetId = shape.props.assetId
+ *   if (assetId) {
+ *     const asset = editor.getAsset(assetId)
+ *     // Handle the asset...
+ *   }
+ * }
+ *
+ * // Use with image or video shapes
+ * const imageShape: TLImageShape = { props: { assetId: 'asset:img1' } }
+ * const videoShape: TLVideoShape = { props: { assetId: 'asset:vid1' } }
+ * handleAssetShape(imageShape) // Works
+ * handleAssetShape(videoShape) // Works
+ * ```
+ *
+ * @public
+ */
 export type TLAssetShape = Extract<TLShape, { props: { assetId: TLAssetId } }>

package/src/records/TLBinding.test.ts

@@ -0,0 +1,22 @@
+import { describe, expect, it } from 'vitest'
+import { createBindingId, rootBindingMigrations } from './TLBinding'
+
+describe('TLBinding', () => {
+	describe('createBindingId function', () => {
+		it('should generate IDs starting with binding:', () => {
+			const id = createBindingId()
+			expect(id.startsWith('binding:')).toBe(true)
+		})
+
+		it('should use custom ID when provided', () => {
+			expect(createBindingId('test')).toBe('binding:test')
+		})
+	})
+
+	describe('rootBindingMigrations', () => {
+		it('should have correct structure', () => {
+			expect(rootBindingMigrations.sequenceId).toBe('com.tldraw.binding')
+			expect(Array.isArray(rootBindingMigrations.sequence)).toBe(true)
+		})
+	})
+})