@jmruthers/pace-core 0.5.75 → 0.5.77

package/src/components/DataTable/utils/__tests__/performanceUtils.test.ts

@@ -0,0 +1,466 @@
+/**
+ * @file Unit Tests for performanceUtils
+ * @package @jmruthers/pace-core
+ * @module Components/DataTable/Utils/__tests__
+ */
+
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import {
+  determinePaginationMode,
+  getOptimalPageSizeOptions,
+  chunkData,
+  DataChunkManager,
+  SearchIndex,
+  debounce,
+  throttle,
+  VisibilityTracker
+} from '../performanceUtils';
+import type { ChunkingConfig, SearchIndexConfig, DataRecord } from '../../types';
+
+describe('[unit] determinePaginationMode', () => {
+  it('returns client for small datasets', () => {
+    expect(determinePaginationMode(100)).toBe('client');
+    expect(determinePaginationMode(500)).toBe('client');
+    expect(determinePaginationMode(999)).toBe('client');
+  });
+
+  it('returns hybrid for medium datasets', () => {
+    expect(determinePaginationMode(1001)).toBe('hybrid');
+    expect(determinePaginationMode(5000)).toBe('hybrid');
+  });
+
+  it('returns server for large datasets', () => {
+    expect(determinePaginationMode(10001)).toBe('server');
+    expect(determinePaginationMode(50000)).toBe('server');
+  });
+
+  it('allows custom serverSideThreshold', () => {
+    expect(determinePaginationMode(5000, 10000)).toBe('hybrid');
+    expect(determinePaginationMode(10001, 10000)).toBe('server');
+  });
+
+  it('handles edge at threshold', () => {
+    expect(determinePaginationMode(5000, 5000)).toBe('hybrid');
+    expect(determinePaginationMode(5001, 5000)).toBe('server');
+  });
+});
+
+describe('[unit] getOptimalPageSizeOptions', () => {
+  it('returns correct options for client mode', () => {
+    const options100 = getOptimalPageSizeOptions('client', 100);
+    expect(options100).toEqual([10, 25, 50]);
+
+    const options200 = getOptimalPageSizeOptions('client', 200);
+    expect(options200).toEqual([10, 25, 50, 100]);
+  });
+
+  it('returns correct options for hybrid mode', () => {
+    const options = getOptimalPageSizeOptions('hybrid', 5000);
+    expect(options).toEqual([50, 100, 250, 500]);
+  });
+
+  it('returns correct options for server mode', () => {
+    const options = getOptimalPageSizeOptions('server', 10000);
+    expect(options).toEqual([25, 50, 100, 250]);
+  });
+
+  it('returns default options for invalid mode', () => {
+    const options = getOptimalPageSizeOptions('invalid' as any, 1000);
+    expect(options).toEqual([10, 25, 50, 100]);
+  });
+});
+
+describe('[unit] chunkData', () => {
+  const testData: DataRecord[] = Array.from({ length: 25 }, (_, i) => ({ id: i + 1 }));
+
+  it('splits data into correct chunks', () => {
+    const chunks = chunkData(testData, 10);
+
+    expect(chunks.length).toBe(3);
+    expect(chunks[0].length).toBe(10);
+    expect(chunks[1].length).toBe(10);
+    expect(chunks[2].length).toBe(5);
+  });
+
+  it('handles chunk size larger than data', () => {
+    const chunks = chunkData(testData, 100);
+
+    expect(chunks.length).toBe(1);
+    expect(chunks[0].length).toBe(25);
+  });
+
+  it('handles exact division', () => {
+    const chunks = chunkData(testData, 5);
+
+    expect(chunks.length).toBe(5);
+    chunks.forEach(chunk => {
+      expect(chunk.length).toBe(5);
+    });
+  });
+
+  it('handles empty data', () => {
+    const chunks = chunkData([], 10);
+
+    expect(chunks).toEqual([]);
+  });
+
+  it('handles chunk size of 1', () => {
+    const chunks = chunkData(testData, 1);
+
+    expect(chunks.length).toBe(25);
+    chunks.forEach(chunk => {
+      expect(chunk.length).toBe(1);
+    });
+  });
+});
+
+describe('[unit] DataChunkManager', () => {
+  let manager: DataChunkManager<DataRecord>;
+  const testData: DataRecord[] = Array.from({ length: 1000 }, (_, i) => ({ id: i + 1 }));
+  const config: ChunkingConfig = {
+    chunkSize: 100,
+    maxChunksInMemory: 3
+  };
+
+  beforeEach(() => {
+    manager = new DataChunkManager(config);
+  });
+
+  it('loads chunks on demand', () => {
+    const chunk = manager.getChunk(0, testData);
+
+    expect(chunk.length).toBe(100);
+    expect(chunk[0]).toEqual({ id: 1 });
+    expect(chunk[99]).toEqual({ id: 100 });
+  });
+
+  it('caches chunks in memory', () => {
+    const chunk1 = manager.getChunk(0, testData);
+    const chunk2 = manager.getChunk(0, testData);
+
+    // Should return same reference
+    expect(chunk1).toBe(chunk2);
+  });
+
+  it('evicts oldest chunks when at capacity', () => {
+    // Fill cache
+    manager.getChunk(0, testData); // Load chunk 0
+    manager.getChunk(1, testData); // Load chunk 1
+    manager.getChunk(2, testData); // Load chunk 2
+
+    // Now at capacity (3 chunks)
+    const chunk3 = manager.getChunk(3, testData); // Should evict chunk 0
+
+    expect(manager.getChunk(0, testData)).not.toBe(chunk3); // Chunk 0 was evicted
+  });
+
+  it('updates access order correctly', () => {
+    manager.getChunk(0, testData); // Oldest
+    manager.getChunk(1, testData); // Middle
+    manager.getChunk(2, testData); // Newest
+
+    manager.getChunk(0, testData); // Now 0 is most recently used
+
+    const chunk3 = manager.getChunk(3, testData); // Should evict 1 (now oldest)
+    expect(chunk3).toBeDefined();
+  });
+
+  it('handles last chunk correctly', () => {
+    const lastChunk = manager.getChunk(9, testData); // 10th chunk, 100 items each = last 100 items
+
+    expect(lastChunk.length).toBe(100);
+    expect(lastChunk[0]).toEqual({ id: 901 });
+    expect(lastChunk[99]).toEqual({ id: 1000 });
+  });
+
+  it('handles out of bounds chunk index', () => {
+    const chunk = manager.getChunk(20, testData); // Beyond data
+
+    expect(chunk.length).toBe(0);
+  });
+
+  it('clears all cached chunks', () => {
+    manager.getChunk(0, testData);
+    manager.getChunk(1, testData);
+
+    manager.clear();
+
+    // After clearing, the chunks should be recreated
+    const chunkAfterClear = manager.getChunk(0, testData);
+    // The chunk will be recreated, but we can't easily test the internal state
+    expect(chunkAfterClear.length).toBeGreaterThan(0); // Should reload
+  });
+
+  it('returns correct memory usage', () => {
+    manager.getChunk(0, testData);
+    manager.getChunk(1, testData);
+
+    const memoryUsage = manager.getMemoryUsage();
+
+    expect(typeof memoryUsage).toBe('number');
+    expect(memoryUsage).toBeGreaterThan(0);
+  });
+});
+
+describe('[unit] SearchIndex', () => {
+  let searchIndex: SearchIndex<DataRecord>;
+  const testData: DataRecord[] = [
+    { name: 'John Doe', email: 'john@example.com' },
+    { name: 'Jane Smith', email: 'jane@example.com' },
+    { name: 'Bob Johnson', email: 'bob@example.com' }
+  ];
+
+  const config: SearchIndexConfig = {
+    indexedFields: ['name', 'email'],
+    fuzzySearch: false
+  };
+
+  beforeEach(() => {
+    searchIndex = new SearchIndex(config);
+    searchIndex.buildIndex(testData);
+  });
+
+  it('builds index from data', () => {
+    // Index should be built in beforeEach
+    const results = searchIndex.search('John');
+
+    expect(results.length).toBeGreaterThan(0);
+  });
+
+  it('finds exact matches', () => {
+    const results = searchIndex.search('John Doe');
+
+    expect(results).toContain(0);
+  });
+
+  it('finds matches across multiple fields', () => {
+    const results = searchIndex.search('john@example.com');
+
+    expect(results).toContain(0);
+  });
+
+  it('handles empty search query', () => {
+    const results = searchIndex.search('');
+
+    expect(results).toEqual([]);
+  });
+
+  it('handles whitespace in query', () => {
+    const results = searchIndex.search('  John  ');
+
+    expect(results).toContain(0);
+  });
+
+  it('handles case-insensitive search', () => {
+    const results = searchIndex.search('JANE');
+
+    expect(results).toContain(1);
+  });
+
+  it('handles partial word matches', () => {
+    const results = searchIndex.search('Jane');
+
+    expect(results).toContain(1);
+  });
+
+  it('requires all search terms to match with multiple words', () => {
+    const results = searchIndex.search('Jane Smith');
+
+    expect(results).toContain(1);
+    
+    const noResults = searchIndex.search('Jane Johnson');
+    
+    expect(noResults).not.toContain(1);
+  });
+
+  it('handles special characters in search', () => {
+    const results = searchIndex.search('john@example');
+
+    expect(results).toContain(0);
+  });
+
+  it('finds no results for non-matching query', () => {
+    const results = searchIndex.search('NonExistentUser');
+
+    expect(results).toEqual([]);
+  });
+});
+
+describe('[unit] SearchIndex with Fuzzy Search', () => {
+  it('finds fuzzy matches when enabled', () => {
+    const testData: DataRecord[] = [
+      { name: 'JavaScript' },
+      { name: 'TypeScript' },
+      { name: 'Python' }
+    ];
+
+    const fuzzyConfig: SearchIndexConfig = {
+      indexedFields: ['name'],
+      fuzzySearch: true,
+      fuzzyThreshold: 0.6
+    };
+
+    const searchIndex = new SearchIndex(fuzzyConfig);
+    searchIndex.buildIndex(testData);
+
+    const results = searchIndex.search('JavScript'); // Typo
+
+    expect(results.length).toBeGreaterThan(0);
+  });
+
+  it('respects fuzzy threshold', () => {
+    const testData: DataRecord[] = [
+      { name: 'test' }
+    ];
+
+    const fuzzyConfig: SearchIndexConfig = {
+      indexedFields: ['name'],
+      fuzzySearch: true,
+      fuzzyThreshold: 0.8 // High threshold
+    };
+
+    const searchIndex = new SearchIndex(fuzzyConfig);
+    searchIndex.buildIndex(testData);
+
+    const results = searchIndex.search('testt');
+
+    // Should still match due to high similarity
+    expect(results.length).toBeGreaterThan(0);
+  });
+
+  it('does not match very different strings', () => {
+    const testData: DataRecord[] = [
+      { name: 'test' }
+    ];
+
+    const fuzzyConfig: SearchIndexConfig = {
+      indexedFields: ['name'],
+      fuzzySearch: true,
+      fuzzyThreshold: 0.8
+    };
+
+    const searchIndex = new SearchIndex(fuzzyConfig);
+    searchIndex.buildIndex(testData);
+
+    const results = searchIndex.search('completelydifferent');
+
+    expect(results.length).toBe(0);
+  });
+});
+
+describe('[unit] debounce', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it('delays function execution', () => {
+    const fn = vi.fn();
+    const debouncedFn = debounce(fn, 100);
+
+    debouncedFn();
+    expect(fn).not.toHaveBeenCalled();
+
+    vi.advanceTimersByTime(100);
+    expect(fn).toHaveBeenCalledTimes(1);
+  });
+
+  it('cancels previous calls when called multiple times', () => {
+    const fn = vi.fn();
+    const debouncedFn = debounce(fn, 100);
+
+    debouncedFn();
+    debouncedFn();
+    debouncedFn();
+
+    vi.advanceTimersByTime(100);
+    expect(fn).toHaveBeenCalledTimes(1);
+  });
+
+  it('preserves function arguments', () => {
+    const fn = vi.fn();
+    const debouncedFn = debounce(fn, 100);
+
+    debouncedFn('arg1', 'arg2');
+
+    vi.advanceTimersByTime(100);
+    expect(fn).toHaveBeenCalledWith('arg1', 'arg2');
+  });
+});
+
+describe('[unit] throttle', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it('limits function execution rate', () => {
+    const fn = vi.fn();
+    const throttledFn = throttle(fn, 100);
+
+    throttledFn();
+    expect(fn).toHaveBeenCalledTimes(1);
+
+    throttledFn();
+    throttledFn();
+    throttledFn();
+
+    // Should not be called again within throttle period
+    expect(fn).toHaveBeenCalledTimes(1);
+
+    // After throttle period
+    vi.advanceTimersByTime(100);
+    throttledFn();
+    expect(fn).toHaveBeenCalledTimes(2);
+  });
+
+  it('preserves function arguments', () => {
+    const fn = vi.fn();
+    const throttledFn = throttle(fn, 100);
+
+    throttledFn('arg1', 'arg2');
+    expect(fn).toHaveBeenCalledWith('arg1', 'arg2');
+  });
+});
+
+describe('[unit] VisibilityTracker', () => {
+  it('creates tracker successfully', () => {
+    const tracker = new VisibilityTracker();
+
+    expect(tracker).toBeDefined();
+  });
+
+  it('tracks visible elements count', () => {
+    const tracker = new VisibilityTracker();
+
+    // In test environment, IntersectionObserver may not be available
+    // So we can only test basic instantiation
+    expect(tracker.getVisibleCount()).toBe(0);
+  });
+
+  it('provides callback for visibility changes', () => {
+    const tracker = new VisibilityTracker();
+    const callback = vi.fn();
+
+    const unsubscribe = tracker.onVisibilityChange(callback);
+
+    // Cleanup
+    unsubscribe();
+  });
+
+  it('destroys tracker cleanly', () => {
+    const tracker = new VisibilityTracker();
+
+    tracker.destroy();
+
+    // Should not throw
+    expect(() => tracker.getVisibleCount()).not.toThrow();
+  });
+});
+

package/src/components/DataTable/utils/__tests__/rowUtils.test.ts

@@ -0,0 +1,251 @@
+/**
+ * @file Unit Tests for rowUtils
+ * @package @jmruthers/pace-core
+ * @module Components/DataTable/Utils/__tests__
+ */
+
+import { describe, it, expect } from 'vitest';
+import { getRowIdSafe, hasValidRowId } from '../rowUtils';
+import type { GetRowId, DataRecord } from '../../types';
+
+describe('[unit] getRowIdSafe', () => {
+  it('uses custom getRowId when provided', () => {
+    const customGetRowId: GetRowId<DataRecord> = (row: DataRecord) => `custom-${(row as any).id}`;
+    const row = { id: 'test-123' };
+
+    const result = getRowIdSafe(row, 0, customGetRowId);
+
+    expect(result).toBe('custom-test-123');
+  });
+
+  it('falls back to row.id when custom getRowId not provided', () => {
+    const row = { id: 'test-123' };
+
+    const result = getRowIdSafe(row, 0);
+
+    expect(result).toBe('test-123');
+  });
+
+  it('throws when row.id is undefined and no custom getRowId exists', () => {
+    const row = { name: 'Test' };
+
+    expect(() => getRowIdSafe(row as any, 0)).toThrow('[DataTable] Unable to determine a stable row id');
+  });
+
+  it('throws when row.id is null', () => {
+    const row = { id: null };
+
+    expect(() => getRowIdSafe(row as any, 5)).toThrow('[DataTable] Unable to determine a stable row id');
+  });
+
+  it('converts numeric IDs to strings', () => {
+    const row = { id: 123 };
+
+    const result = getRowIdSafe(row, 0);
+
+    expect(result).toBe('123');
+  });
+
+  it('converts zero to string', () => {
+    const row = { id: 0 };
+
+    const result = getRowIdSafe(row, 0);
+
+    expect(result).toBe('0');
+  });
+
+  it('handles empty string ID', () => {
+    const row = { id: '' };
+
+    const result = getRowIdSafe(row, 5);
+
+    expect(result).toBe(''); // Empty string is valid
+  });
+
+  it('handles custom getRowId that returns non-string', () => {
+    const customGetRowId = () => 123 as any;
+    const row = { id: 'test' };
+
+    const result = getRowIdSafe(row, 0, customGetRowId);
+
+    // getRowIdSafe always returns a string
+    expect(result).toBe('123');
+  });
+
+  it('preserves string IDs exactly', () => {
+    const row = { id: 'special-id_123' };
+
+    const result = getRowIdSafe(row, 0);
+
+    expect(result).toBe('special-id_123');
+  });
+});
+
+describe('[unit] hasValidRowId', () => {
+  it('returns true for valid string ID', () => {
+    const row = { id: 'valid-id-123' };
+
+    const result = hasValidRowId(row);
+
+    expect(result).toBe(true);
+  });
+
+  it('returns false when row lacks an id', () => {
+    const row = { name: 'Test' };
+
+    const result = hasValidRowId(row);
+
+    expect(result).toBe(false);
+  });
+
+  it('returns false for empty string ID', () => {
+    const row = { id: '' };
+
+    const result = hasValidRowId(row);
+
+    expect(result).toBe(false);
+  });
+
+  it('returns false for "undefined" string', () => {
+    const row = { id: 'undefined' };
+
+    const result = hasValidRowId(row);
+
+    expect(result).toBe(false);
+  });
+
+  it('returns false for "null" string', () => {
+    const row = { id: 'null' };
+
+    const result = hasValidRowId(row);
+
+    expect(result).toBe(false);
+  });
+
+  it('returns true for valid numeric ID as string', () => {
+    const row = { id: '123' };
+
+    const result = hasValidRowId(row);
+
+    expect(result).toBe(true);
+  });
+
+  it('returns true for UUID format ID', () => {
+    const row = { id: '550e8400-e29b-41d4-a716-446655440000' };
+
+    const result = hasValidRowId(row);
+
+    expect(result).toBe(true);
+  });
+
+  it('uses custom getRowId when provided', () => {
+    const customGetRowId: GetRowId<DataRecord> = () => 'custom-valid-id';
+    const row = { id: '' };
+
+    const result = hasValidRowId(row, customGetRowId);
+
+    expect(result).toBe(true);
+  });
+
+  it('returns false when custom getRowId returns invalid ID', () => {
+    const customGetRowId: GetRowId<DataRecord> = () => '0';
+    const row = { id: 'valid' };
+
+    const result = hasValidRowId(row, customGetRowId);
+
+    expect(result).toBe(false);
+  });
+
+  it('handles getRowId errors gracefully', () => {
+    const errorGetRowId = () => {
+      throw new Error('GetRowId failed');
+    };
+
+    const row = { id: 'test' };
+
+    const result = hasValidRowId(row, errorGetRowId as any);
+
+    expect(result).toBe(false);
+  });
+
+  it('returns true for complex valid IDs', () => {
+    const row = { id: 'user-123-item-456-action_789' };
+
+    const result = hasValidRowId(row);
+
+    expect(result).toBe(true);
+  });
+
+  it('returns false for edge case invalid IDs', () => {
+    const invalidIds = ['0', '', 'undefined', 'null'];
+    
+    invalidIds.forEach(invalidId => {
+      const row = { id: invalidId };
+      const result = hasValidRowId(row);
+      expect(result).toBe(false);
+    });
+  });
+
+  it('returns true for edge case valid IDs', () => {
+    const validIds = ['1', 'a', 'A', '123', 'abc-123'];
+    
+    validIds.forEach(validId => {
+      const row = { id: validId };
+      const result = hasValidRowId(row);
+      expect(result).toBe(true);
+    });
+  });
+
+  it('handles null and undefined in custom getRowId by falling back', () => {
+    const customGetRowId1: GetRowId<DataRecord> = () => null as any;
+    const customGetRowId2: GetRowId<DataRecord> = () => undefined as any;
+    const row = { id: 'test' };
+
+    // When custom getRowId returns null/undefined, it falls back to row.id
+    expect(hasValidRowId(row, customGetRowId1)).toBe(true); // row.id='test' is valid
+    expect(hasValidRowId(row, customGetRowId2)).toBe(true); // row.id='test' is valid
+
+    // Test with row that has no id
+    const rowNoId = { name: 'Test' };
+    expect(hasValidRowId(rowNoId, customGetRowId1)).toBe(false);
+    expect(hasValidRowId(rowNoId, customGetRowId2)).toBe(false);
+  });
+});
+
+describe('[unit] Integration', () => {
+  it('getRowIdSafe and hasValidRowId work together', () => {
+    const row = { id: 'test-id-123' };
+
+    const rowId = getRowIdSafe(row, 0);
+    const isValid = hasValidRowId(row);
+
+    expect(rowId).toBe('test-id-123');
+    expect(isValid).toBe(true);
+  });
+
+  it('hasValidRowId correctly identifies getRowIdSafe fallback cases', () => {
+    const rowWithValidId = { id: 'valid' };
+    const rowWithoutId = { name: 'Test' };
+
+    expect(hasValidRowId(rowWithValidId)).toBe(true);
+    expect(hasValidRowId(rowWithoutId)).toBe(false);
+  });
+
+  it('handles various row structures', () => {
+    const testCases = [
+      { row: { id: 'abc' }, expected: true },
+      { row: { id: '' }, expected: false },
+      { row: { id: '0' }, expected: false },
+      { row: { id: '1' }, expected: true },
+      { row: { id: null }, getRowId: undefined, expected: false },
+      { row: { id: undefined }, expected: false },
+      { row: { name: 'Test' }, expected: false },
+    ];
+
+    testCases.forEach(({ row, getRowId, expected }) => {
+      const result = hasValidRowId(row, getRowId);
+      expect(result).toBe(expected);
+    });
+  });
+});
+