@object-ui/data-objectstack 0.3.1 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@object-ui/data-objectstack",
-  "version": "0.3.1",
+  "version": "0.5.0",
   "description": "ObjectStack Data Adapter for Object UI",
   "license": "MIT",
   "type": "module",
@@ -20,9 +20,9 @@
     "README.md"
   ],
   "dependencies": {
-    "@objectstack/client": "^0.3.3",
-    "@object-ui/types": "0.3.1",
-    "@object-ui/core": "0.3.1"
+    "@objectstack/client": "^0.9.1",
+    "@object-ui/core": "0.5.0",
+    "@object-ui/types": "0.5.0"
   },
   "devDependencies": {
     "tsup": "^8.0.1",

package/src/cache/MetadataCache.test.ts

@@ -0,0 +1,426 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { MetadataCache } from './MetadataCache';
+
+describe('MetadataCache', () => {
+  let cache: MetadataCache;
+
+  beforeEach(() => {
+    cache = new MetadataCache({ maxSize: 3, ttl: 1000 }); // Small size and TTL for testing
+  });
+
+  describe('Cache Hit/Miss Scenarios', () => {
+    it('should return cached value on cache hit', async () => {
+      const fetcher = vi.fn(async () => ({ name: 'users', fields: [] }));
+      
+      // First call - cache miss
+      const result1 = await cache.get('users', fetcher);
+      expect(result1).toEqual({ name: 'users', fields: [] });
+      expect(fetcher).toHaveBeenCalledTimes(1);
+      
+      // Second call - cache hit
+      const result2 = await cache.get('users', fetcher);
+      expect(result2).toEqual({ name: 'users', fields: [] });
+      expect(fetcher).toHaveBeenCalledTimes(1); // Not called again
+      
+      const stats = cache.getStats();
+      expect(stats.hits).toBe(1);
+      expect(stats.misses).toBe(1);
+      expect(stats.hitRate).toBe(0.5);
+    });
+
+    it('should call fetcher on cache miss', async () => {
+      const fetcher = vi.fn(async () => ({ data: 'test' }));
+      
+      const result = await cache.get('test-key', fetcher);
+      
+      expect(result).toEqual({ data: 'test' });
+      expect(fetcher).toHaveBeenCalledTimes(1);
+      
+      const stats = cache.getStats();
+      expect(stats.misses).toBe(1);
+      expect(stats.hits).toBe(0);
+    });
+
+    it('should handle multiple different keys', async () => {
+      const fetcher1 = vi.fn(async () => ({ type: 'users' }));
+      const fetcher2 = vi.fn(async () => ({ type: 'posts' }));
+      
+      const result1 = await cache.get('users', fetcher1);
+      const result2 = await cache.get('posts', fetcher2);
+      
+      expect(result1).toEqual({ type: 'users' });
+      expect(result2).toEqual({ type: 'posts' });
+      expect(fetcher1).toHaveBeenCalledTimes(1);
+      expect(fetcher2).toHaveBeenCalledTimes(1);
+      
+      // Get again - both should be cached
+      await cache.get('users', fetcher1);
+      await cache.get('posts', fetcher2);
+      
+      expect(fetcher1).toHaveBeenCalledTimes(1);
+      expect(fetcher2).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  describe('TTL Expiration', () => {
+    it('should expire entries after TTL', async () => {
+      const cache = new MetadataCache({ maxSize: 10, ttl: 100 }); // 100ms TTL
+      const fetcher = vi.fn(async () => ({ data: 'test' }));
+      
+      // First fetch
+      await cache.get('test', fetcher);
+      expect(fetcher).toHaveBeenCalledTimes(1);
+      
+      // Immediate second fetch - should be cached
+      await cache.get('test', fetcher);
+      expect(fetcher).toHaveBeenCalledTimes(1);
+      
+      // Wait for TTL to expire
+      await new Promise(resolve => setTimeout(resolve, 150));
+      
+      // Should fetch again after expiration
+      await cache.get('test', fetcher);
+      expect(fetcher).toHaveBeenCalledTimes(2);
+    });
+
+    it('should update timestamp on cache hit', async () => {
+      const cache = new MetadataCache({ maxSize: 10, ttl: 200 });
+      const fetcher = vi.fn(async () => ({ data: 'test' }));
+      
+      await cache.get('test', fetcher);
+      
+      // Access again after 100ms
+      await new Promise(resolve => setTimeout(resolve, 100));
+      await cache.get('test', fetcher);
+      
+      // Access again after another 110ms (total 210ms from first, ensuring TTL has passed)
+      await new Promise(resolve => setTimeout(resolve, 110));
+      
+      // Should still be in cache because we're checking timestamp, not last accessed
+      // Actually, the implementation uses timestamp for expiration, not lastAccessed
+      // So after 210ms total (> 200ms TTL), it should expire
+      await cache.get('test', fetcher);
+      
+      // Should have been called twice - initial + after expiration
+      expect(fetcher).toHaveBeenCalledTimes(2);
+    });
+
+    it('should not return expired entries via has()', async () => {
+      const cache = new MetadataCache({ maxSize: 10, ttl: 100 });
+      const fetcher = vi.fn(async () => ({ data: 'test' }));
+      
+      await cache.get('test', fetcher);
+      
+      expect(cache.has('test')).toBe(true);
+      
+      // Wait for expiration
+      await new Promise(resolve => setTimeout(resolve, 150));
+      
+      expect(cache.has('test')).toBe(false);
+    });
+  });
+
+  describe('LRU Eviction', () => {
+    it('should evict least recently used entry when maxSize is reached', async () => {
+      // Cache size is 3
+      const fetcher1 = vi.fn(async () => ({ id: 1 }));
+      const fetcher2 = vi.fn(async () => ({ id: 2 }));
+      const fetcher3 = vi.fn(async () => ({ id: 3 }));
+      const fetcher4 = vi.fn(async () => ({ id: 4 }));
+      
+      // Fill cache
+      await cache.get('key1', fetcher1);
+      await cache.get('key2', fetcher2);
+      await cache.get('key3', fetcher3);
+      
+      expect(cache.getStats().size).toBe(3);
+      
+      // Add fourth item - should evict key1 (least recently used)
+      await cache.get('key4', fetcher4);
+      
+      expect(cache.getStats().size).toBe(3);
+      expect(cache.getStats().evictions).toBe(1);
+      
+      // key1 should not be in cache anymore
+      await cache.get('key1', fetcher1);
+      expect(fetcher1).toHaveBeenCalledTimes(2); // Called again
+      
+      // After re-adding key1, key2 should have been evicted
+      // So cache now has: key3, key4, key1
+      
+      // key3, key4 should still be cached
+      await cache.get('key3', fetcher3);
+      await cache.get('key4', fetcher4);
+      expect(fetcher3).toHaveBeenCalledTimes(1);
+      expect(fetcher4).toHaveBeenCalledTimes(1);
+      
+      // key2 should have been evicted when key1 was re-added
+      await cache.get('key2', fetcher2);
+      expect(fetcher2).toHaveBeenCalledTimes(2);
+    });
+
+    it('should update LRU order on access', async () => {
+      const fetcher1 = vi.fn(async () => ({ id: 1 }));
+      const fetcher2 = vi.fn(async () => ({ id: 2 }));
+      const fetcher3 = vi.fn(async () => ({ id: 3 }));
+      const fetcher4 = vi.fn(async () => ({ id: 4 }));
+      
+      // Fill cache: key1, key2, key3
+      await cache.get('key1', fetcher1);
+      await cache.get('key2', fetcher2);
+      await cache.get('key3', fetcher3);
+      
+      // Access key1 again - should move it to the end (most recently used)
+      // Cache order: key2, key3, key1
+      await cache.get('key1', fetcher1);
+      
+      // Add key4 - should evict key2 (now the LRU)
+      // Cache order: key3, key1, key4
+      await cache.get('key4', fetcher4);
+      
+      // Verify key2 was evicted
+      await cache.get('key2', fetcher2);
+      expect(fetcher2).toHaveBeenCalledTimes(2);
+      
+      // After re-adding key2, key3 should have been evicted
+      // Cache order: key1, key4, key2
+      
+      // key1, key4 should still be cached
+      await cache.get('key1', fetcher1);
+      await cache.get('key4', fetcher4);
+      expect(fetcher1).toHaveBeenCalledTimes(1); // Only called once initially (re-access was a cache hit)
+      expect(fetcher4).toHaveBeenCalledTimes(1);
+      
+      // key3 should have been evicted when key2 was re-added
+      await cache.get('key3', fetcher3);
+      expect(fetcher3).toHaveBeenCalledTimes(2);
+    });
+  });
+
+  describe('Concurrent Access', () => {
+    it('should handle concurrent requests for the same key', async () => {
+      let fetchCount = 0;
+      const fetcher = vi.fn(async () => {
+        fetchCount++;
+        await new Promise(resolve => setTimeout(resolve, 50));
+        return { data: 'test', fetchCount };
+      });
+      
+      // Make multiple concurrent requests
+      const results = await Promise.all([
+        cache.get('test', fetcher),
+        cache.get('test', fetcher),
+        cache.get('test', fetcher),
+      ]);
+      
+      // All should return the same data
+      // Note: Due to async nature, the first call will fetch and others might also fetch
+      // if they check before the first one completes. This is acceptable behavior.
+      // But at least one should be cached if they complete after the first one.
+      expect(results[0]).toBeDefined();
+      expect(results[1]).toBeDefined();
+      expect(results[2]).toBeDefined();
+    });
+
+    it('should handle concurrent requests for different keys', async () => {
+      const fetcher1 = vi.fn(async () => {
+        await new Promise(resolve => setTimeout(resolve, 30));
+        return { id: 1 };
+      });
+      const fetcher2 = vi.fn(async () => {
+        await new Promise(resolve => setTimeout(resolve, 30));
+        return { id: 2 };
+      });
+      const fetcher3 = vi.fn(async () => {
+        await new Promise(resolve => setTimeout(resolve, 30));
+        return { id: 3 };
+      });
+      
+      const results = await Promise.all([
+        cache.get('key1', fetcher1),
+        cache.get('key2', fetcher2),
+        cache.get('key3', fetcher3),
+      ]);
+      
+      expect(results[0]).toEqual({ id: 1 });
+      expect(results[1]).toEqual({ id: 2 });
+      expect(results[2]).toEqual({ id: 3 });
+      expect(fetcher1).toHaveBeenCalledTimes(1);
+      expect(fetcher2).toHaveBeenCalledTimes(1);
+      expect(fetcher3).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  describe('Cache Management', () => {
+    it('should invalidate specific key', async () => {
+      const fetcher = vi.fn(async () => ({ data: 'test' }));
+      
+      await cache.get('test', fetcher);
+      expect(fetcher).toHaveBeenCalledTimes(1);
+      
+      cache.invalidate('test');
+      
+      await cache.get('test', fetcher);
+      expect(fetcher).toHaveBeenCalledTimes(2);
+    });
+
+    it('should invalidate all keys', async () => {
+      const fetcher1 = vi.fn(async () => ({ id: 1 }));
+      const fetcher2 = vi.fn(async () => ({ id: 2 }));
+      
+      await cache.get('key1', fetcher1);
+      await cache.get('key2', fetcher2);
+      
+      cache.invalidate(); // No key = invalidate all
+      
+      await cache.get('key1', fetcher1);
+      await cache.get('key2', fetcher2);
+      
+      expect(fetcher1).toHaveBeenCalledTimes(2);
+      expect(fetcher2).toHaveBeenCalledTimes(2);
+    });
+
+    it('should clear cache and reset stats', async () => {
+      const fetcher = vi.fn(async () => ({ data: 'test' }));
+      
+      await cache.get('key1', fetcher);
+      await cache.get('key2', fetcher);
+      await cache.get('key1', fetcher); // Hit
+      
+      const statsBefore = cache.getStats();
+      expect(statsBefore.size).toBe(2);
+      expect(statsBefore.hits).toBe(1);
+      expect(statsBefore.misses).toBe(2);
+      
+      cache.clear();
+      
+      const statsAfter = cache.getStats();
+      expect(statsAfter.size).toBe(0);
+      expect(statsAfter.hits).toBe(0);
+      expect(statsAfter.misses).toBe(0);
+      expect(statsAfter.evictions).toBe(0);
+    });
+  });
+
+  describe('Statistics', () => {
+    it('should track cache statistics correctly', async () => {
+      const fetcher = vi.fn(async () => ({ data: 'test' }));
+      
+      // Initial stats
+      let stats = cache.getStats();
+      expect(stats.size).toBe(0);
+      expect(stats.maxSize).toBe(3);
+      expect(stats.hits).toBe(0);
+      expect(stats.misses).toBe(0);
+      expect(stats.evictions).toBe(0);
+      expect(stats.hitRate).toBe(0);
+      
+      // First access - miss
+      await cache.get('key1', fetcher);
+      stats = cache.getStats();
+      expect(stats.size).toBe(1);
+      expect(stats.misses).toBe(1);
+      expect(stats.hitRate).toBe(0);
+      
+      // Second access - hit
+      await cache.get('key1', fetcher);
+      stats = cache.getStats();
+      expect(stats.hits).toBe(1);
+      expect(stats.hitRate).toBe(0.5);
+      
+      // Third access - hit
+      await cache.get('key1', fetcher);
+      stats = cache.getStats();
+      expect(stats.hits).toBe(2);
+      expect(stats.hitRate).toBeCloseTo(0.667, 2);
+    });
+
+    it('should track evictions', async () => {
+      const fetcher = vi.fn(async () => ({ data: 'test' }));
+      
+      // Fill cache to max
+      await cache.get('key1', fetcher);
+      await cache.get('key2', fetcher);
+      await cache.get('key3', fetcher);
+      
+      let stats = cache.getStats();
+      expect(stats.evictions).toBe(0);
+      
+      // Trigger eviction
+      await cache.get('key4', fetcher);
+      
+      stats = cache.getStats();
+      expect(stats.evictions).toBe(1);
+      
+      // Trigger more evictions
+      await cache.get('key5', fetcher);
+      await cache.get('key6', fetcher);
+      
+      stats = cache.getStats();
+      expect(stats.evictions).toBe(3);
+    });
+  });
+
+  describe('Edge Cases', () => {
+    it('should handle fetcher that throws error', async () => {
+      const fetcher = vi.fn(async () => {
+        throw new Error('Fetch failed');
+      });
+      
+      await expect(cache.get('test', fetcher)).rejects.toThrow('Fetch failed');
+      
+      // Should not cache the error
+      const stats = cache.getStats();
+      expect(stats.size).toBe(0);
+    });
+
+    it('should handle null/undefined values', async () => {
+      const fetcher1 = vi.fn(async () => null);
+      const fetcher2 = vi.fn(async () => undefined);
+      
+      const result1 = await cache.get('null-key', fetcher1);
+      const result2 = await cache.get('undefined-key', fetcher2);
+      
+      expect(result1).toBeNull();
+      expect(result2).toBeUndefined();
+      
+      // Should still cache these values
+      await cache.get('null-key', fetcher1);
+      await cache.get('undefined-key', fetcher2);
+      
+      expect(fetcher1).toHaveBeenCalledTimes(1);
+      expect(fetcher2).toHaveBeenCalledTimes(1);
+    });
+
+    it('should handle empty string key', async () => {
+      const fetcher = vi.fn(async () => ({ data: 'test' }));
+      
+      const result = await cache.get('', fetcher);
+      expect(result).toEqual({ data: 'test' });
+      
+      await cache.get('', fetcher);
+      expect(fetcher).toHaveBeenCalledTimes(1);
+    });
+
+    it('should handle very large cache', async () => {
+      const largeCache = new MetadataCache({ maxSize: 10000, ttl: 60000 });
+      
+      // Add many entries
+      for (let i = 0; i < 1000; i++) {
+        await largeCache.get(`key-${i}`, async () => ({ id: i }));
+      }
+      
+      const stats = largeCache.getStats();
+      expect(stats.size).toBe(1000);
+      expect(stats.evictions).toBe(0);
+    });
+  });
+});

package/src/cache/MetadataCache.ts

@@ -0,0 +1,229 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+/**
+ * Represents a cached schema entry with metadata
+ */
+interface CachedSchema {
+  data: unknown;
+  timestamp: number;
+  accessCount: number;
+  lastAccessed: number;
+}
+
+/**
+ * Cache statistics for monitoring
+ */
+export interface CacheStats {
+  size: number;
+  maxSize: number;
+  hits: number;
+  misses: number;
+  evictions: number;
+  hitRate: number;
+}
+
+/**
+ * MetadataCache - LRU cache with TTL expiration for schema metadata
+ * 
+ * Features:
+ * - LRU (Least Recently Used) eviction policy
+ * - TTL (Time To Live) based expiration (fixed from creation, not sliding)
+ * - Memory limit controls
+ * - Async-safe operations
+ * - Performance statistics tracking
+ * 
+ * Note: Concurrent requests for the same uncached key may result in multiple
+ * fetcher calls. For production use cases requiring request deduplication,
+ * consider wrapping the cache with a promise-based deduplication layer.
+ * 
+ * @example
+ * ```typescript
+ * const cache = new MetadataCache({ maxSize: 100, ttl: 300000 });
+ * 
+ * const schema = await cache.get('users', async () => {
+ *   return await fetchSchemaFromServer('users');
+ * });
+ * 
+ * console.log(cache.getStats());
+ * ```
+ */
+export class MetadataCache {
+  private cache: Map<string, CachedSchema>;
+  private maxSize: number;
+  private ttl: number;
+  private stats: {
+    hits: number;
+    misses: number;
+    evictions: number;
+  };
+
+  /**
+   * Create a new MetadataCache instance
+   * 
+   * @param options - Configuration options
+   * @param options.maxSize - Maximum number of entries (default: 100)
+   * @param options.ttl - Time to live in milliseconds (default: 5 minutes)
+   */
+  constructor(options: { maxSize?: number; ttl?: number } = {}) {
+    this.cache = new Map();
+    this.maxSize = options.maxSize || 100;
+    this.ttl = options.ttl || 5 * 60 * 1000; // 5 minutes default
+    this.stats = {
+      hits: 0,
+      misses: 0,
+      evictions: 0,
+    };
+  }
+
+  /**
+   * Get a value from cache or fetch it using the provided fetcher function
+   * 
+   * @param key - Cache key
+   * @param fetcher - Async function to fetch data if not in cache
+   * @returns Promise resolving to the cached or fetched data
+   */
+  async get<T = unknown>(key: string, fetcher: () => Promise<T>): Promise<T> {
+    const now = Date.now();
+    const cached = this.cache.get(key);
+
+    // Check if cache entry exists and is not expired
+    if (cached) {
+      const age = now - cached.timestamp;
+      
+      if (age < this.ttl) {
+        // Cache hit - update access metadata
+        cached.accessCount++;
+        cached.lastAccessed = now;
+        this.stats.hits++;
+        
+        // Move to end (most recently used) by re-inserting
+        this.cache.delete(key);
+        this.cache.set(key, cached);
+        
+        return cached.data as T;
+      } else {
+        // Expired entry - remove it
+        this.cache.delete(key);
+      }
+    }
+
+    // Cache miss - fetch the data
+    this.stats.misses++;
+    const data = await fetcher();
+
+    // Store in cache
+    this.set(key, data);
+
+    return data;
+  }
+
+  /**
+   * Set a value in the cache
+   * 
+   * @param key - Cache key
+   * @param data - Data to cache
+   */
+  private set(key: string, data: unknown): void {
+    const now = Date.now();
+
+    // Check if we need to evict entries
+    if (this.cache.size >= this.maxSize && !this.cache.has(key)) {
+      this.evictLRU();
+    }
+
+    // Add or update the entry
+    this.cache.set(key, {
+      data,
+      timestamp: now,
+      accessCount: 1,
+      lastAccessed: now,
+    });
+  }
+
+  /**
+   * Evict the least recently used entry
+   */
+  private evictLRU(): void {
+    // The first entry in the Map is the least recently used
+    // (since we move accessed items to the end)
+    const firstKey = this.cache.keys().next().value;
+    
+    if (firstKey !== undefined) {
+      this.cache.delete(firstKey);
+      this.stats.evictions++;
+    }
+  }
+
+  /**
+   * Invalidate a specific cache entry or all entries
+   * 
+   * @param key - Optional key to invalidate. If omitted, invalidates all entries
+   */
+  invalidate(key?: string): void {
+    if (key) {
+      this.cache.delete(key);
+    } else {
+      this.cache.clear();
+    }
+  }
+
+  /**
+   * Clear all cache entries and reset statistics
+   */
+  clear(): void {
+    this.cache.clear();
+    this.stats = {
+      hits: 0,
+      misses: 0,
+      evictions: 0,
+    };
+  }
+
+  /**
+   * Get cache statistics
+   * 
+   * @returns Cache statistics including hit rate
+   */
+  getStats(): CacheStats {
+    const total = this.stats.hits + this.stats.misses;
+    const hitRate = total > 0 ? this.stats.hits / total : 0;
+
+    return {
+      size: this.cache.size,
+      maxSize: this.maxSize,
+      hits: this.stats.hits,
+      misses: this.stats.misses,
+      evictions: this.stats.evictions,
+      hitRate: hitRate,
+    };
+  }
+
+  /**
+   * Check if a key exists in the cache (and is not expired)
+   * 
+   * @param key - Cache key to check
+   * @returns true if the key exists and is not expired
+   */
+  has(key: string): boolean {
+    const cached = this.cache.get(key);
+    
+    if (!cached) {
+      return false;
+    }
+
+    const age = Date.now() - cached.timestamp;
+    
+    if (age >= this.ttl) {
+      this.cache.delete(key);
+      return false;
+    }
+
+    return true;
+  }
+}