/**
 * Manual Test Instructions for CacheService
 *
 * Since Cloudflare Workers Cache API is only available in the Workers runtime,
 * these tests must be run in a Cloudflare Workers environment or using Miniflare.
 *
 * Test 1: Basic Cache Operations
 * -------------------------------
 * 1. Deploy to Cloudflare Workers development environment
 * 2. Initialize cache: const cache = new CacheService(300);
 * 3. Set data: await cache.set('test-key', { foo: 'bar' }, 60);
 * 4. Get data: const result = await cache.get('test-key');
 * 5. Expected: result.data.foo === 'bar', cache_age_seconds ≈ 0
 *
 * Test 2: Cache Key Generation
 * -----------------------------
 * 1. Generate key: const key = cache.generateKey({ provider: 'linode', region: 'us-east' });
 * 2. Expected: key === 'https://cache.internal/instances?provider=linode&region=us-east'
 * 3. Verify sorting: cache.generateKey({ z: 1, a: 2 }) should have 'a' before 'z'
 *
 * Test 3: Cache Miss
 * ------------------
 * 1. Request non-existent key: const result = await cache.get('non-existent');
 * 2. Expected: result === null
 *
 * Test 4: Cache Expiration
 * ------------------------
 * 1. Set with short TTL: await cache.set('expire-test', { data: 'test' }, 2);
 * 2. Immediate get: await cache.get('expire-test') → should return data
 * 3. Wait 3 seconds
 * 4. Get again: await cache.get('expire-test') → should return null (expired)
 *
 * Test 5: Cache Age Tracking
 * --------------------------
 * 1. Set data: await cache.set('age-test', { data: 'test' }, 300);
 * 2. Wait 5 seconds
 * 3. Get data: const result = await cache.get('age-test');
 * 4. Expected: result.cache_age_seconds ≈ 5
 *
 * Test 6: Cache Deletion
 * ----------------------
 * 1. Set data: await cache.set('delete-test', { data: 'test' }, 300);
 * 2. Delete: const deleted = await cache.delete('delete-test');
 * 3. Expected: deleted === true
 * 4. Get data: const result = await cache.get('delete-test');
 * 5. Expected: result === null
 *
 * Test 7: Error Handling (Graceful Degradation)
 * ----------------------------------------------
 * 1. Test with invalid cache response (manual mock required)
 * 2. Expected: No errors thrown, graceful null return
 * 3. Verify logs show error message
 *
 * Test 8: Integration with Instance API
 * --------------------------------------
 * 1. Create cache instance in instance endpoint handler
 * 2. Generate key from query params: cache.generateKey(query)
 * 3. Check cache: const cached = await cache.get<InstanceData[]>(key);
 * 4. If cache hit: return cached.data with cache metadata
 * 5. If cache miss: fetch from database, cache result, return data
 * 6. Verify cache hit on second request
 *
 * Performance Validation:
 * -----------------------
 * 1. Measure database query time (first request)
 * 2. Measure cache hit time (second request)
 * 3. Expected: Cache hit 10-50x faster than database query
 * 4. Verify cache age increases on subsequent requests
 *
 * TTL Strategy Validation:
 * ------------------------
 * Filtered queries (5 min TTL):
 *   - cache.set(key, data, 300)
 *   - Verify expires after 5 minutes
 *
 * Full dataset (1 hour TTL):
 *   - cache.set(key, data, 3600)
 *   - Verify expires after 1 hour
 *
 * Post-sync invalidation:
 *   - After sync operation, call cache.delete(key) for all relevant keys
 *   - Verify next request fetches fresh data from database
 *
 * Test 9: clearAll Method
 * -----------------------
 * 1. Set multiple cache entries:
 *    - await cache.set('key1', { data: 'test1' }, 300)
 *    - await cache.set('key2', { data: 'test2' }, 300)
 *    - await cache.set('key3', { data: 'test3' }, 300)
 * 2. Call clearAll: const count = await cache.clearAll()
 * 3. Expected: count === 0 (enumeration not supported)
 * 4. Expected: Log message about TTL-based expiration
 * 5. Note: Individual entries will expire based on TTL
 *
 * Test 10: clearAll with Prefix
 * ------------------------------
 * 1. Set entries with different prefixes:
 *    - await cache.set('https://cache.internal/instances?foo=bar', data1)
 *    - await cache.set('https://cache.internal/pricing?foo=bar', data2)
 * 2. Call with prefix: await cache.clearAll('https://cache.internal/instances')
 * 3. Expected: count === 0, log shows prefix parameter
 * 4. Note: Prefix is logged but enumeration not supported by Cache API
 *
 * Test 11: clearByEndpoint Method
 * --------------------------------
 * 1. Set endpoint cache: await cache.set('https://cache.internal/instances', data, 300)
 * 2. Clear by endpoint: const deleted = await cache.clearByEndpoint('instances')
 * 3. Expected: deleted === true if cache entry existed
 * 4. Get data: const result = await cache.get('https://cache.internal/instances')
 * 5. Expected: result === null (entry deleted)
 * 6. Note: Only exact matches deleted, parameterized queries remain cached
 *
 * Test 12: clearByEndpoint with Non-existent Endpoint
 * ----------------------------------------------------
 * 1. Clear non-existent: const deleted = await cache.clearByEndpoint('non-existent')
 * 2. Expected: deleted === false
 * 3. Expected: Log message about non-existent endpoint
 *
 * Test 13: Cache Invalidation Strategy
 * -------------------------------------
 * 1. Set parameterized cache entries:
 *    - cache.generateKey({ provider: 'linode', region: 'us-east' })
 *    - cache.generateKey({ provider: 'linode', region: 'eu-west' })
 *    - cache.generateKey({ provider: 'vultr', region: 'us-east' })
 * 2. After schema change or full sync, call clearAll()
 * 3. Verify entries expire based on TTL
 * 4. For production: Consider using KV-backed cache index for enumeration
 *
 * Test 14: Error Handling in clearAll
 * ------------------------------------
 * 1. Mock cache.delete to throw error
 * 2. Call clearAll: await cache.clearAll()
 * 3. Expected: Error is logged and re-thrown
 * 4. Verify error message includes context
 *
 * Test 15: Error Handling in clearByEndpoint
 * -------------------------------------------
 * 1. Mock cache.delete to throw error
 * 2. Call clearByEndpoint: await cache.clearByEndpoint('instances')
 * 3. Expected: Returns false, error logged
 * 4. Application continues without crashing
 */

import { CacheService } from './cache';
import type { InstanceData } from '../types';

/**
 * Example: Using CacheService in API endpoint
 */
async function exampleInstanceEndpointWithCache(
  queryParams: Record<string, unknown>,
  fetchFromDatabase: () => Promise<InstanceData[]>
): Promise<{ data: InstanceData[]; cached?: boolean; cache_age?: number }> {
  const cache = new CacheService(300); // 5 minutes default TTL

  // Generate cache key from query parameters
  const cacheKey = cache.generateKey(queryParams);

  // Try to get from cache
  const cached = await cache.get<InstanceData[]>(cacheKey);

  if (cached) {
    console.log(`[API] Cache hit (age: ${cached.cache_age_seconds}s)`);
    return {
      data: cached.data,
      cached: true,
      cache_age: cached.cache_age_seconds,
    };
  }

  // Cache miss - fetch from database
  console.log('[API] Cache miss - fetching from database');
  const data = await fetchFromDatabase();

  // Determine TTL based on query complexity
  const hasFilters = Object.keys(queryParams).length > 0;
  const ttl = hasFilters ? 300 : 3600; // 5 min for filtered, 1 hour for full

  // Store in cache
  await cache.set(cacheKey, data, ttl);

  return {
    data,
    cached: false,
  };
}

/**
 * Example: Cache invalidation after sync
 */
async function exampleCacheInvalidationAfterSync(
  syncedProviders: string[]
): Promise<void> {
  const cache = new CacheService();

  // Invalidate all instance caches for synced providers
  for (const provider of syncedProviders) {
    // Note: Since Cloudflare Workers Cache API doesn't support pattern matching,
    // you need to maintain a list of active cache keys or use KV for indexing
    const key = cache.generateKey({ provider });
    await cache.delete(key);
    console.log(`[Sync] Invalidated cache for provider: ${provider}`);
  }

  console.log('[Sync] Cache invalidation complete');
}

/**
 * Example: Using clearAll after schema changes
 */
async function exampleClearAllAfterSchemaChange(): Promise<void> {
  const cache = new CacheService();

  // After major schema changes or data migrations
  console.log('[Migration] Clearing all cache entries');
  const count = await cache.clearAll();

  console.log(`[Migration] Cache clear requested. Entries will expire based on TTL.`);
  console.log('[Migration] Consider using KV-backed cache index for enumeration in production.');
}

/**
 * Example: Using clearByEndpoint for targeted invalidation
 */
async function exampleClearByEndpointAfterUpdate(endpoint: string): Promise<void> {
  const cache = new CacheService();

  // Clear cache for specific endpoint after data update
  console.log(`[Update] Clearing cache for endpoint: ${endpoint}`);
  const deleted = await cache.clearByEndpoint(endpoint);

  if (deleted) {
    console.log(`[Update] Successfully cleared ${endpoint} cache`);
  } else {
    console.log(`[Update] No cache entry found for ${endpoint}`);
  }
}

/**
 * Example: Force cache refresh strategy
 */
async function exampleForceCacheRefresh(
  endpoint: string,
  fetchFunction: () => Promise<unknown>
): Promise<void> {
  const cache = new CacheService();

  // Strategy 1: Clear specific endpoint
  await cache.clearByEndpoint(endpoint);

  // Strategy 2: Clear with prefix (logged but not enumerated)
  await cache.clearAll(`https://cache.internal/${endpoint}`);

  // Strategy 3: Fetch fresh data and update cache
  const freshData = await fetchFunction();
  const cacheKey = `https://cache.internal/${endpoint}`;
  await cache.set(cacheKey, freshData, 3600);

  console.log(`[Refresh] Cache refreshed for ${endpoint}`);
}

export {
  exampleInstanceEndpointWithCache,
  exampleCacheInvalidationAfterSync,
  exampleClearAllAfterSchemaChange,
  exampleClearByEndpointAfterUpdate,
  exampleForceCacheRefresh
};