@zeix/cause-effect 0.15.1 → 0.15.2

package/test/store.test.ts

@@ -3,12 +3,13 @@ import {
 	computed,
 	effect,
 	isStore,
+	type State,
 	type StoreAddEvent,
 	type StoreChangeEvent,
 	type StoreRemoveEvent,
+	type StoreSortEvent,
 	state,
 	store,
-	toSignal,
 	UNSET,
 } from '..'
 
@@ -46,12 +47,7 @@ describe('store', () => {
 				email: 'hannah@example.com',
 			})
 
-			/**
-			 * store() only accepts object map types for arrays
-			 */
-			const participants = store<{
-				[x: number]: { name: string; tags: string[] }
-			}>([
+			const participants = store<{ name: string; tags: string[] }[]>([
 				{ name: 'Alice', tags: ['friends', 'mates'] },
 				{ name: 'Bob', tags: ['friends'] },
 			])
@@ -59,18 +55,6 @@ describe('store', () => {
 				{ name: 'Alice', tags: ['friends', 'mates'] },
 				{ name: 'Bob', tags: ['friends'] },
 			])
-
-			/**
-			 * toSignal() converts arrays to object map types when creating stores
-			 */
-			const participants2 = toSignal<{ name: string; tags: string[] }[]>([
-				{ name: 'Alice', tags: ['friends', 'mates'] },
-				{ name: 'Bob', tags: ['friends'] },
-			])
-			expect(participants2.get()).toEqual([
-				{ name: 'Alice', tags: ['friends', 'mates'] },
-				{ name: 'Bob', tags: ['friends'] },
-			])
 		})
 	})
 
@@ -135,6 +119,19 @@ describe('store', () => {
 				name: 'Hannah',
 			})
 		})
+
+		test('add method prevents null values', () => {
+			const user = store<{ name: string; tags?: string[] }>({
+				name: 'Alice',
+			})
+
+			expect(() => {
+				// @ts-expect-error deliberate test that null values are not allowed
+				user.add('tags', null)
+			}).toThrow(
+				'Nullish signal values are not allowed in store for key "tags"',
+			)
+		})
 	})
 
 	describe('nested stores', () => {
@@ -489,7 +486,12 @@ describe('store', () => {
 			})
 
 			const originalSize = user.size.get()
-			user.add('email', 'new@example.com')
+
+			expect(() => {
+				user.add('email', 'new@example.com')
+			}).toThrow(
+				'Could not add store key "email" with value "new@example.com" because it already exists',
+			)
 
 			expect(user.email?.get()).toBe('original@example.com')
 			expect(user.size.get()).toBe(originalSize)
@@ -539,6 +541,189 @@ describe('store', () => {
 		})
 	})
 
+	describe('array-derived stores with computed sum', () => {
+		test('computes sum correctly and updates when items are added, removed, or changed', () => {
+			// Create a store with an array of numbers
+			const numbers = store([1, 2, 3, 4, 5])
+
+			// Create a computed that calculates the sum by accessing the array via .get()
+			// This ensures reactivity to both value changes and structural changes
+			const sum = computed(() => {
+				const array = numbers.get()
+				if (!Array.isArray(array)) return 0
+				return array.reduce((acc, num) => acc + num, 0)
+			})
+
+			// Initial sum should be 15 (1+2+3+4+5)
+			expect(sum.get()).toBe(15)
+			expect(numbers.size.get()).toBe(5)
+
+			// Test adding items
+			numbers.add(6) // Add 6 at index 5
+			expect(sum.get()).toBe(21) // 15 + 6 = 21
+			expect(numbers.size.get()).toBe(6)
+
+			numbers.add(7) // Add 7 at index 6
+			expect(sum.get()).toBe(28) // 21 + 7 = 28
+			expect(numbers.size.get()).toBe(7)
+
+			// Test changing a single value
+			numbers[2].set(10) // Change index 2 from 3 to 10
+			expect(sum.get()).toBe(35) // 28 - 3 + 10 = 35
+
+			// Test another value change
+			numbers[0].set(5) // Change index 0 from 1 to 5
+			expect(sum.get()).toBe(39) // 35 - 1 + 5 = 39
+
+			// Test removing items
+			numbers.remove(6) // Remove index 6 (value 7)
+			expect(sum.get()).toBe(32) // 39 - 7 = 32
+			expect(numbers.size.get()).toBe(6)
+
+			numbers.remove(0) // Remove index 0 (value 5)
+			expect(sum.get()).toBe(27) // 32 - 5 = 27
+			expect(numbers.size.get()).toBe(5)
+
+			// Verify the final array structure using .get()
+			const finalArray = numbers.get()
+			expect(Array.isArray(finalArray)).toBe(true)
+			expect(finalArray).toEqual([2, 10, 4, 5, 6])
+		})
+
+		test('handles empty array and single element operations', () => {
+			// Start with empty array
+			const numbers = store<number[]>([])
+
+			const sum = computed(() => {
+				const array = numbers.get()
+				if (!Array.isArray(array)) return 0
+				return array.reduce((acc, num) => acc + num, 0)
+			})
+
+			// Empty array sum should be 0
+			expect(sum.get()).toBe(0)
+			expect(numbers.size.get()).toBe(0)
+
+			// Add first element
+			numbers.add(42)
+			expect(sum.get()).toBe(42)
+			expect(numbers.size.get()).toBe(1)
+
+			// Change the only element
+			numbers[0].set(100)
+			expect(sum.get()).toBe(100)
+
+			// Remove the only element
+			numbers.remove(0)
+			expect(sum.get()).toBe(0)
+			expect(numbers.size.get()).toBe(0)
+		})
+
+		test('computed sum using store iteration with size tracking', () => {
+			const numbers = store([10, 20, 30])
+
+			// Use iteration but also track size to ensure reactivity to additions/removals
+			const sum = computed(() => {
+				// Access size to subscribe to structural changes
+				numbers.size.get()
+				let total = 0
+				for (const signal of numbers) {
+					total += signal.get()
+				}
+				return total
+			})
+
+			expect(sum.get()).toBe(60)
+
+			// Add more numbers
+			numbers.add(40)
+			expect(sum.get()).toBe(100)
+
+			// Modify existing values
+			numbers[1].set(25) // Change 20 to 25
+			expect(sum.get()).toBe(105) // 10 + 25 + 30 + 40
+
+			// Remove a value
+			numbers.remove(2) // Remove 30
+			expect(sum.get()).toBe(75) // 10 + 25 + 40
+		})
+
+		test('demonstrates array compaction behavior with remove operations', () => {
+			// Create a store with an array
+			const numbers = store([10, 20, 30, 40, 50])
+
+			// Create a computed using iteration approach with size tracking
+			const sumWithIteration = computed(() => {
+				// Access size to subscribe to structural changes
+				numbers.size.get()
+				let total = 0
+				for (const signal of numbers) {
+					total += signal.get()
+				}
+				return total
+			})
+
+			// Create a computed using .get() approach for comparison
+			const sumWithGet = computed(() => {
+				const array = numbers.get()
+				if (!Array.isArray(array)) return 0
+				return array.reduce((acc, num) => acc + num, 0)
+			})
+
+			// Initial state: [10, 20, 30, 40, 50], keys [0,1,2,3,4]
+			expect(sumWithIteration.get()).toBe(150)
+			expect(sumWithGet.get()).toBe(150)
+			expect(numbers.size.get()).toBe(5)
+
+			// Remove items - arrays should compact (not create sparse holes)
+			numbers.remove(1) // Remove 20, array becomes [10, 30, 40, 50]
+			expect(numbers.size.get()).toBe(4)
+			expect(numbers.get()).toEqual([10, 30, 40, 50])
+			expect(sumWithIteration.get()).toBe(130) // 10 + 30 + 40 + 50
+			expect(sumWithGet.get()).toBe(130)
+
+			numbers.remove(2) // Remove 40, array becomes [10, 30, 50]
+			expect(numbers.size.get()).toBe(3)
+			expect(numbers.get()).toEqual([10, 30, 50])
+			expect(sumWithIteration.get()).toBe(90) // 10 + 30 + 50
+			expect(sumWithGet.get()).toBe(90)
+
+			// Set a new array of same size (3 elements)
+			numbers.set([100, 200, 300])
+			expect(numbers.size.get()).toBe(3)
+			expect(numbers.get()).toEqual([100, 200, 300])
+
+			// Both approaches work correctly with compacted arrays
+			expect(sumWithGet.get()).toBe(600) // 100 + 200 + 300
+			expect(sumWithIteration.get()).toBe(600) // Both work correctly
+		})
+
+		test('verifies root cause: diff works on array representation but reconcile uses sparse keys', () => {
+			// Create a sparse array scenario
+			const numbers = store([10, 20, 30])
+
+			// Remove middle element to create sparse structure
+			numbers.remove(1) // Now has keys ["0", "2"] with values [10, 30]
+
+			// Verify the sparse structure
+			expect(numbers.get()).toEqual([10, 30])
+			expect(numbers.size.get()).toBe(2)
+
+			// Now set a new array of same length
+			// The diff should see [10, 30] -> [100, 200] as:
+			// - index 0: 10 -> 100 (change)
+			// - index 1: 30 -> 200 (change)
+			// But internally the keys are ["0", "2"], not ["0", "1"]
+			numbers.set([100, 200])
+
+			// With the fix: sparse array replacement now works correctly
+			const result = numbers.get()
+
+			// The fix ensures proper sparse array replacement
+			expect(result).toEqual([100, 200]) // This now passes with the diff fix!
+		})
+	})
+
 	describe('arrays and edge cases', () => {
 		test('handles arrays as store values', () => {
 			const data = store({ items: [1, 2, 3] })
@@ -743,4 +928,762 @@ describe('store', () => {
 			expect(spread.app.name.get()).toBe('UpdatedApp')
 		})
 	})
+
+	describe('JSON integration', () => {
+		test('seamless integration with JSON.parse() and JSON.stringify() for API workflows', async () => {
+			// Simulate loading data from a JSON API response
+			const jsonResponse = `{
+				"user": {
+					"id": 123,
+					"name": "John Doe",
+					"email": "john@example.com",
+					"preferences": {
+						"theme": "dark",
+						"notifications": true,
+						"language": "en"
+					}
+				},
+				"settings": {
+					"autoSave": true,
+					"timeout": 5000
+				},
+				"tags": ["developer", "javascript", "typescript"]
+			}`
+
+			// Parse JSON and create store - works seamlessly
+			const apiData = JSON.parse(jsonResponse)
+			const userStore = store<{
+				user: {
+					id: number
+					name: string
+					email: string
+					preferences: {
+						theme: string
+						notifications: boolean
+						language: string
+						fontSize?: number
+					}
+				}
+				settings: {
+					autoSave: boolean
+					timeout: number
+				}
+				tags: string[]
+				lastLogin?: Date
+			}>(apiData)
+
+			// Verify initial data is accessible and reactive
+			expect(userStore.user.name.get()).toBe('John Doe')
+			expect(userStore.user.preferences.theme.get()).toBe('dark')
+			expect(userStore.settings.autoSave.get()).toBe(true)
+			expect(userStore.get().tags).toEqual([
+				'developer',
+				'javascript',
+				'typescript',
+			])
+
+			// Simulate user interactions - update preferences
+			userStore.user.preferences.theme.set('light')
+			userStore.user.preferences.notifications.set(false)
+
+			// Add new preference
+			userStore.user.preferences.add('fontSize', 14)
+
+			// Update settings
+			userStore.settings.timeout.set(10000)
+
+			// Add new top-level property
+			userStore.add('lastLogin', new Date('2024-01-15T10:30:00Z'))
+
+			// Verify changes are reflected
+			expect(userStore.user.preferences.theme.get()).toBe('light')
+			expect(userStore.user.preferences.notifications.get()).toBe(false)
+			expect(userStore.settings.timeout.get()).toBe(10000)
+
+			// Get current state and verify it's JSON-serializable
+			const currentState = userStore.get()
+			expect(currentState.user.preferences.theme).toBe('light')
+			expect(currentState.user.preferences.notifications).toBe(false)
+			expect(currentState.settings.timeout).toBe(10000)
+			expect(currentState.tags).toEqual([
+				'developer',
+				'javascript',
+				'typescript',
+			])
+
+			// Convert back to JSON - seamless serialization
+			const jsonPayload = JSON.stringify(currentState)
+
+			// Verify the JSON contains our updates
+			const parsedBack = JSON.parse(jsonPayload)
+			expect(parsedBack.user.preferences.theme).toBe('light')
+			expect(parsedBack.user.preferences.notifications).toBe(false)
+			expect(parsedBack.user.preferences.fontSize).toBe(14)
+			expect(parsedBack.settings.timeout).toBe(10000)
+			expect(parsedBack.lastLogin).toBe('2024-01-15T10:30:00.000Z')
+
+			// Demonstrate update() for bulk changes
+			userStore.update(data => ({
+				...data,
+				user: {
+					...data.user,
+					email: 'john.doe@newcompany.com',
+					preferences: {
+						...data.user.preferences,
+						theme: 'auto',
+						language: 'fr',
+					},
+				},
+				settings: {
+					...data.settings,
+					autoSave: false,
+				},
+			}))
+
+			// Verify bulk update worked
+			expect(userStore.user.email.get()).toBe('john.doe@newcompany.com')
+			expect(userStore.user.preferences.theme.get()).toBe('auto')
+			expect(userStore.user.preferences.language.get()).toBe('fr')
+			expect(userStore.settings.autoSave.get()).toBe(false)
+
+			// Final JSON serialization for sending to server
+			const finalPayload = JSON.stringify(userStore.get())
+			expect(typeof finalPayload).toBe('string')
+			expect(finalPayload).toContain('john.doe@newcompany.com')
+			expect(finalPayload).toContain('"theme":"auto"')
+		})
+
+		test('handles complex nested structures and arrays from JSON', () => {
+			const complexJson = `{
+				"dashboard": {
+					"widgets": [
+						{"id": 1, "type": "chart", "config": {"color": "blue"}},
+						{"id": 2, "type": "table", "config": {"rows": 10}}
+					],
+					"layout": {
+						"columns": 3,
+						"responsive": true
+					}
+				},
+				"metadata": {
+					"version": "1.0.0",
+					"created": "2024-01-01T00:00:00Z",
+					"tags": null
+				}
+			}`
+
+			const data = JSON.parse(complexJson)
+
+			// Test that null values in initial JSON are filtered out (treated as UNSET)
+			const dashboardStore = store<{
+				dashboard: {
+					widgets: {
+						id: number
+						type: string
+						config: Record<string, string | number | boolean>
+					}[]
+					layout: {
+						columns: number
+						responsive: boolean
+					}
+				}
+				metadata: {
+					version: string
+					created: string
+					tags?: string[]
+				}
+			}>(data)
+
+			// Access nested array elements
+			expect(dashboardStore.dashboard.widgets.get()).toHaveLength(2)
+			expect(dashboardStore.dashboard.widgets[0].type.get()).toBe('chart')
+			expect(dashboardStore.dashboard.widgets[1].config.rows.get()).toBe(
+				10,
+			)
+
+			// Update array element
+			dashboardStore.set({
+				...dashboardStore.get(),
+				dashboard: {
+					...dashboardStore.dashboard.get(),
+					widgets: [
+						...dashboardStore.dashboard.widgets.get(),
+						{ id: 3, type: 'graph', config: { animate: true } },
+					],
+				},
+			})
+
+			// Verify array update
+			expect(dashboardStore.get().dashboard.widgets).toHaveLength(3)
+			expect(dashboardStore.get().dashboard.widgets[2].type).toBe('graph')
+
+			// Test that individual null additions are still prevented via add()
+			expect(() => {
+				// @ts-expect-error deliberate test case
+				dashboardStore.add('newProp', null)
+			}).toThrow(
+				'Nullish signal values are not allowed in store for key "newProp"',
+			)
+
+			// Test that individual property .set() operations prevent null values
+			expect(() => {
+				dashboardStore.update(data => ({
+					...data,
+					metadata: {
+						...data.metadata,
+						// @ts-expect-error deliberate test case
+						tags: null,
+					},
+				}))
+			}).toThrow(
+				'Nullish signal values are not allowed in store for key "tags"',
+			)
+
+			// Update null to actual value (this should work)
+			dashboardStore.update(data => ({
+				...data,
+				metadata: {
+					...data.metadata,
+					tags: ['production', 'v1'],
+				},
+			}))
+
+			expect(dashboardStore.get().metadata.tags).toEqual([
+				'production',
+				'v1',
+			])
+
+			// Verify JSON round-trip
+			const serialized = JSON.stringify(dashboardStore.get())
+			const reparsed = JSON.parse(serialized)
+			expect(reparsed.dashboard.widgets).toHaveLength(3)
+			expect(reparsed.metadata.tags).toEqual(['production', 'v1'])
+		})
+
+		test('demonstrates real-world form data management', () => {
+			// Simulate form data loaded from API
+			const formData = {
+				profile: {
+					firstName: '',
+					lastName: '',
+					email: '',
+					bio: '',
+				},
+				preferences: {
+					emailNotifications: true,
+					pushNotifications: false,
+					marketing: false,
+				},
+				address: {
+					street: '',
+					city: '',
+					country: 'US',
+					zipCode: '',
+				},
+			}
+
+			const formStore = store<{
+				profile: {
+					id?: number
+					createdAt?: string
+					firstName: string
+					lastName: string
+					email: string
+					bio: string
+				}
+				preferences: {
+					emailNotifications: boolean
+					pushNotifications: boolean
+					marketing: boolean
+				}
+				address: {
+					street: string
+					city: string
+					country: string
+					zipCode: string
+				}
+			}>(formData)
+
+			// Simulate user filling out form
+			formStore.profile.firstName.set('Jane')
+			formStore.profile.lastName.set('Smith')
+			formStore.profile.email.set('jane.smith@example.com')
+			formStore.profile.bio.set(
+				'Full-stack developer with 5 years experience',
+			)
+
+			// Update address
+			formStore.address.street.set('123 Main St')
+			formStore.address.city.set('San Francisco')
+			formStore.address.zipCode.set('94105')
+
+			// Toggle preferences
+			formStore.preferences.pushNotifications.set(true)
+			formStore.preferences.marketing.set(true)
+
+			// Get form data for submission - ready for JSON.stringify
+			const submissionData = formStore.get()
+
+			expect(submissionData.profile.firstName).toBe('Jane')
+			expect(submissionData.profile.email).toBe('jane.smith@example.com')
+			expect(submissionData.address.city).toBe('San Francisco')
+			expect(submissionData.preferences.pushNotifications).toBe(true)
+
+			// Simulate sending to API
+			const jsonPayload = JSON.stringify(submissionData)
+			expect(jsonPayload).toContain('jane.smith@example.com')
+			expect(jsonPayload).toContain('San Francisco')
+
+			// Simulate receiving updated data back from server
+			const serverResponse = {
+				...submissionData,
+				profile: {
+					...submissionData.profile,
+					id: 456,
+					createdAt: '2024-01-15T12:00:00Z',
+				},
+			}
+
+			// Update store with server response
+			formStore.set(serverResponse)
+
+			// Verify server data is integrated
+			expect(formStore.profile.id?.get()).toBe(456)
+			expect(formStore.profile.createdAt?.get()).toBe(
+				'2024-01-15T12:00:00Z',
+			)
+			expect(formStore.get().profile.firstName).toBe('Jane') // Original data preserved
+		})
+
+		describe('Symbol.isConcatSpreadable and polymorphic behavior', () => {
+			test('array-like stores have Symbol.isConcatSpreadable true and length property', () => {
+				const numbers = store([1, 2, 3])
+
+				// Should be concat spreadable
+				expect(numbers[Symbol.isConcatSpreadable]).toBe(true)
+
+				// Should have length property
+				expect(numbers.length).toBe(3)
+				expect(typeof numbers.length).toBe('number')
+
+				// Add an item and verify length updates
+				numbers.add(4)
+				expect(numbers.length).toBe(4)
+			})
+
+			test('object-like stores have Symbol.isConcatSpreadable false and no length property', () => {
+				const user = store({ name: 'John', age: 25 })
+
+				// Should not be concat spreadable
+				expect(user[Symbol.isConcatSpreadable]).toBe(false)
+
+				// Should not have length property
+				// @ts-expect-error deliberately accessing non-existent length property
+				expect(user.length).toBeUndefined()
+				expect('length' in user).toBe(false)
+			})
+
+			test('array-like stores iterate over signals only', () => {
+				const numbers = store([10, 20, 30])
+				const signals = [...numbers]
+
+				// Should yield signals, not [key, signal] pairs
+				expect(signals).toHaveLength(3)
+				expect(signals[0].get()).toBe(10)
+				expect(signals[1].get()).toBe(20)
+				expect(signals[2].get()).toBe(30)
+
+				// Verify they are signal objects
+				signals.forEach(signal => {
+					expect(typeof signal.get).toBe('function')
+				})
+			})
+
+			test('object-like stores iterate over [key, signal] pairs', () => {
+				const user = store({ name: 'Alice', age: 30 })
+				const entries = [...user]
+
+				// Should yield [key, signal] pairs
+				expect(entries).toHaveLength(2)
+
+				// Find the name entry
+				const nameEntry = entries.find(([key]) => key === 'name')
+				expect(nameEntry).toBeDefined()
+				expect(nameEntry?.[0]).toBe('name')
+				expect(nameEntry?.[1].get()).toBe('Alice')
+
+				// Find the age entry
+				const ageEntry = entries.find(([key]) => key === 'age')
+				expect(ageEntry).toBeDefined()
+				expect(ageEntry?.[0]).toBe('age')
+				expect(ageEntry?.[1].get()).toBe(30)
+			})
+
+			test('array-like stores support single-parameter add() method', () => {
+				const fruits = store(['apple', 'banana'])
+
+				// Should add to end without specifying key
+				fruits.add('cherry')
+
+				const result = fruits.get()
+				expect(result).toEqual(['apple', 'banana', 'cherry'])
+				expect(fruits.length).toBe(3)
+			})
+
+			test('object-like stores require key parameter for add() method', () => {
+				const config = store<{ debug: boolean; timeout?: number }>({
+					debug: true,
+				})
+
+				// Should require both key and value
+				config.add('timeout', 5000)
+
+				expect(config.get()).toEqual({ debug: true, timeout: 5000 })
+			})
+
+			test('concat works correctly with array-like stores', () => {
+				const numbers = store([2, 3])
+				const prefix = [state(1)]
+				const suffix = [state(4), state(5)]
+
+				// Should spread signals when concat-ed
+				const combined = prefix.concat(
+					numbers as unknown as ConcatArray<State<number>>,
+					suffix,
+				)
+
+				expect(combined).toHaveLength(5)
+				expect(combined[0].get()).toBe(1)
+				expect(combined[1].get()).toBe(2) // from store
+				expect(combined[2].get()).toBe(3) // from store
+				expect(combined[3].get()).toBe(4)
+				expect(combined[4].get()).toBe(5)
+			})
+
+			test('spread operator works correctly with array-like stores', () => {
+				const numbers = store([10, 20])
+
+				// Should spread signals
+				const spread = [state(5), ...numbers, state(30)]
+
+				expect(spread).toHaveLength(4)
+				expect(spread[0].get()).toBe(5)
+				expect(spread[1].get()).toBe(10) // from store
+				expect(spread[2].get()).toBe(20) // from store
+				expect(spread[3].get()).toBe(30)
+			})
+
+			test('array-like stores maintain numeric key ordering', () => {
+				const items = store(['first', 'second', 'third'])
+
+				// Get the keys
+				const keys = Object.keys(items)
+				expect(keys).toEqual(['0', '1', '2', 'length'])
+
+				// Iteration should be in order
+				const signals = [...items]
+				expect(signals[0].get()).toBe('first')
+				expect(signals[1].get()).toBe('second')
+				expect(signals[2].get()).toBe('third')
+			})
+
+			test('polymorphic behavior is determined at creation time', () => {
+				// Created as array - stays array-like
+				const arrayStore = store([1, 2])
+				expect(arrayStore[Symbol.isConcatSpreadable]).toBe(true)
+				expect(arrayStore.length).toBe(2)
+
+				// Created as object - stays object-like
+				const objectStore = store<{ a: number; b: number; c?: number }>(
+					{
+						a: 1,
+						b: 2,
+					},
+				)
+				expect(objectStore[Symbol.isConcatSpreadable]).toBe(false)
+				// @ts-expect-error deliberate access to non-existent length property
+				expect(objectStore.length).toBeUndefined()
+
+				// Even after modifications, behavior doesn't change
+				arrayStore.add(3)
+				expect(arrayStore[Symbol.isConcatSpreadable]).toBe(true)
+
+				objectStore.add('c', 3)
+				expect(objectStore[Symbol.isConcatSpreadable]).toBe(false)
+			})
+
+			test('runtime type detection using typeof length', () => {
+				const arrayStore = store([1, 2, 3])
+				const objectStore = store({ x: 1, y: 2 })
+
+				// Can distinguish at runtime
+				expect(typeof arrayStore.length === 'number').toBe(true)
+				// @ts-expect-error deliberately accessing non-existent length property
+				expect(typeof objectStore.length === 'number').toBe(false)
+			})
+
+			test('empty stores behave correctly', () => {
+				const emptyArray = store([])
+				const emptyObject = store({})
+
+				// Empty array store
+				expect(emptyArray[Symbol.isConcatSpreadable]).toBe(true)
+				expect(emptyArray.length).toBe(0)
+				expect([...emptyArray]).toEqual([])
+
+				// Empty object store
+				expect(emptyObject[Symbol.isConcatSpreadable]).toBe(false)
+				// @ts-expect-error deliberately accessing non-existent length property
+				expect(emptyObject.length).toBeUndefined()
+				expect([...emptyObject]).toEqual([])
+			})
+		})
+
+		test('debug length property issue', () => {
+			const numbers = store([1, 2, 3])
+
+			// Test length in computed context
+			const lengthComputed = computed(() => numbers.length)
+			numbers.add(4)
+
+			// Test if length property is actually reactive
+			expect(numbers.length).toBe(4)
+			expect(lengthComputed.get()).toBe(4)
+		})
+	})
+
+	describe('sort() method', () => {
+		test('sorts array-like store with numeric compareFn', () => {
+			const numbers = store([3, 1, 4, 1, 5])
+
+			// Capture old signal references
+			const oldSignals = [
+				numbers[0],
+				numbers[1],
+				numbers[2],
+				numbers[3],
+				numbers[4],
+			]
+
+			numbers.sort((a, b) => a - b)
+
+			// Check sorted order
+			expect(numbers.get()).toEqual([1, 1, 3, 4, 5])
+
+			// Verify signal references are preserved (moved, not recreated)
+			expect(numbers[0]).toBe(oldSignals[1]) // first 1 was at index 1
+			expect(numbers[1]).toBe(oldSignals[3]) // second 1 was at index 3
+			expect(numbers[2]).toBe(oldSignals[0]) // 3 was at index 0
+			expect(numbers[3]).toBe(oldSignals[2]) // 4 was at index 2
+			expect(numbers[4]).toBe(oldSignals[4]) // 5 was at index 4
+		})
+
+		test('sorts array-like store with string compareFn', () => {
+			const names = store(['Charlie', 'Alice', 'Bob'])
+
+			names.sort((a, b) => a.localeCompare(b))
+
+			expect(names.get()).toEqual(['Alice', 'Bob', 'Charlie'])
+		})
+
+		test('sorts record-like store by value', () => {
+			const users = store({
+				user1: { name: 'Charlie', age: 25 },
+				user2: { name: 'Alice', age: 30 },
+				user3: { name: 'Bob', age: 20 },
+			})
+
+			// Capture old signal references
+			const oldSignals = {
+				user1: users.user1,
+				user2: users.user2,
+				user3: users.user3,
+			}
+
+			// Sort by age
+			users.sort((a, b) => a.age - b.age)
+
+			// Check order via iteration
+			const keys = Array.from(users, ([key]) => key)
+			expect(keys).toEqual(['user3', 'user1', 'user2'])
+
+			// Verify signal references are preserved
+			expect(users.user1).toBe(oldSignals.user1)
+			expect(users.user2).toBe(oldSignals.user2)
+			expect(users.user3).toBe(oldSignals.user3)
+		})
+
+		test('emits store-sort event with new order', () => {
+			const numbers = store([30, 10, 20])
+			let sortEvent: StoreSortEvent | null = null
+
+			numbers.addEventListener('store-sort', event => {
+				sortEvent = event
+			})
+
+			numbers.sort((a, b) => a - b)
+
+			expect(sortEvent).not.toBeNull()
+			// biome-ignore lint/style/noNonNullAssertion: test
+			expect(sortEvent!.type).toBe('store-sort')
+			// Keys in new sorted order: [10, 20, 30] came from indices [1, 2, 0]
+			// biome-ignore lint/style/noNonNullAssertion: test
+			expect(sortEvent!.detail).toEqual(['1', '2', '0'])
+		})
+
+		test('sort is reactive - watchers are notified', () => {
+			const numbers = store([3, 1, 2])
+			let effectCount = 0
+			let lastValue: number[] = []
+
+			effect(() => {
+				lastValue = numbers.get()
+				effectCount++
+			})
+
+			// Initial effect run
+			expect(effectCount).toBe(1)
+			expect(lastValue).toEqual([3, 1, 2])
+
+			numbers.sort((a, b) => a - b)
+
+			// Effect should run again after sort
+			expect(effectCount).toBe(2)
+			expect(lastValue).toEqual([1, 2, 3])
+		})
+
+		test('nested signals remain reactive after sorting', () => {
+			const items = store([
+				{ name: 'Charlie', score: 85 },
+				{ name: 'Alice', score: 95 },
+				{ name: 'Bob', score: 75 },
+			])
+
+			// Sort by score
+			items.sort((a, b) => b.score - a.score) // descending
+
+			// Verify order
+			expect(items.get().map(item => item.name)).toEqual([
+				'Alice',
+				'Charlie',
+				'Bob',
+			])
+
+			// Modify a nested property
+			items[1].score.set(100) // Charlie's score
+
+			// Verify the change is reflected
+			expect(items.get()[1].score).toBe(100)
+			expect(items[1].name.get()).toBe('Charlie')
+		})
+
+		test('sort with complex nested structures', () => {
+			const posts = store([
+				{
+					id: 'post1',
+					title: 'Hello World',
+					meta: { views: 100, likes: 5 },
+				},
+				{
+					id: 'post2',
+					title: 'Getting Started',
+					meta: { views: 50, likes: 10 },
+				},
+				{
+					id: 'post3',
+					title: 'Advanced Topics',
+					meta: { views: 200, likes: 3 },
+				},
+			])
+
+			// Sort by likes (ascending)
+			posts.sort((a, b) => a.meta.likes - b.meta.likes)
+
+			const sortedTitles = posts.get().map(post => post.title)
+			expect(sortedTitles).toEqual([
+				'Advanced Topics',
+				'Hello World',
+				'Getting Started',
+			])
+
+			// Verify nested reactivity still works
+			posts[0].meta.likes.set(15)
+			expect(posts.get()[0].meta.likes).toBe(15)
+		})
+
+		test('sort preserves array length and size', () => {
+			const arr = store([5, 2, 8, 1])
+
+			expect(arr.length).toBe(4)
+			expect(arr.size.get()).toBe(4)
+
+			arr.sort((a, b) => a - b)
+
+			expect(arr.length).toBe(4)
+			expect(arr.size.get()).toBe(4)
+			expect(arr.get()).toEqual([1, 2, 5, 8])
+		})
+
+		test('sort with no compareFn uses default string sorting like Array.prototype.sort()', () => {
+			const items = store(['banana', 'cherry', 'apple', '10', '2'])
+
+			items.sort()
+
+			// Default sorting converts to strings and compares in UTF-16 order
+			expect(items.get()).toEqual(
+				['banana', 'cherry', 'apple', '10', '2'].sort(),
+			)
+		})
+
+		test('default sort handles numbers as strings like Array.prototype.sort()', () => {
+			const numbers = store([80, 9, 100])
+
+			numbers.sort()
+
+			// Numbers are converted to strings: "100", "80", "9"
+			// In UTF-16 order: "100" < "80" < "9"
+			expect(numbers.get()).toEqual([80, 9, 100].sort())
+		})
+
+		test('default sort handles mixed values with proper string conversion', () => {
+			const mixed = store(['b', 0, 'a', '', 'c'])
+
+			mixed.sort()
+
+			// String conversion: '' < '0' < 'a' < 'b' < 'c'
+			expect(mixed.get()).toEqual(['', 0, 'a', 'b', 'c'])
+		})
+
+		test('multiple sorts work correctly', () => {
+			const numbers = store([3, 1, 4, 1, 5])
+
+			// Sort ascending
+			numbers.sort((a, b) => a - b)
+			expect(numbers.get()).toEqual([1, 1, 3, 4, 5])
+
+			// Sort descending
+			numbers.sort((a, b) => b - a)
+			expect(numbers.get()).toEqual([5, 4, 3, 1, 1])
+		})
+
+		test('sort event contains correct movement mapping for records', () => {
+			const users = store({
+				alice: { age: 30 },
+				bob: { age: 20 },
+				charlie: { age: 25 },
+			})
+
+			let sortEvent: StoreSortEvent | null = null
+			users.addEventListener('store-sort', event => {
+				sortEvent = event
+			})
+
+			// Sort by age
+			users.sort((a, b) => b.age - a.age)
+
+			expect(sortEvent).not.toBeNull()
+			// biome-ignore lint/style/noNonNullAssertion: test
+			expect(sortEvent!.detail).toEqual(['alice', 'charlie', 'bob'])
+		})
+	})
 })