Data Operations

/**
 * Gets the contents of the cached file with the given key
 * @param key - The cache key to retrieve
 * @param defaultValue - Optional default value if key doesn't exist
 * @returns Promise resolving to cached value or defaultValue
 */
get(key: string, defaultValue?: any): Promise<any>;

// Basic retrieval
const userData = await cache.get("user:123");

// With default value
const settings = await cache.get("app:settings", { theme: "light" });

// Type-safe retrieval with defaults
interface User {
  name: string;
  email: string;
}

const user: User = await cache.get("user:456", { 
  name: "Unknown", 
  email: "unknown@example.com" 
});

/**
 * Gets the contents of the cached file with the given key synchronously
 * @param key - The cache key to retrieve
 * @param defaultValue - Optional default value if key doesn't exist
 * @returns Cached value or defaultValue, or undefined if not found
 */
getSync(key: string, defaultValue?: any): any;

// Synchronous retrieval
const config = cache.getSync("app:config");

// With default value
const theme = cache.getSync("user:theme", "light");

// Error handling
try {
  const data = cache.getSync("critical:data");
  if (data === undefined) {
    console.log("Data not found in cache");
  }
} catch (error) {
  console.error("Cache read error:", error);
}

/**
 * Writes the given value to the file system cache
 * @param key - The cache key to store under
 * @param value - The value to cache (any serializable type)
 * @param ttl - Optional TTL override in seconds
 * @returns Promise resolving to object with file path
 */
set(key: string, value: any, ttl?: number): Promise<{path: string}>;

// Basic storage
await cache.set("user:789", { name: "Bob", active: true });

// With custom TTL (10 minutes)
const result = await cache.set("session:abc123", sessionData, 600);
console.log(`Stored at: ${result.path}`);

// Store complex data types
await cache.set("api:response", {
  data: [1, 2, 3],
  timestamp: new Date(),
  metadata: { version: "1.0" }
});

// Store with no expiration (override default TTL)
await cache.set("permanent:config", config, 0);

/**
 * Writes the given value to the file system cache synchronously
 * @param key - The cache key to store under
 * @param value - The value to cache (any serializable type)  
 * @param ttl - Optional TTL override in seconds
 * @returns The cache instance for method chaining
 */
setSync(key: string, value: any, ttl?: number): FileSystemCache;

// Basic synchronous storage
cache.setSync("counter", 42);

// Method chaining
cache
  .setSync("user:name", "Alice")
  .setSync("user:age", 30)
  .setSync("user:active", true);

// With TTL override
cache.setSync("temp:token", "abc123", 300); // 5 minutes

// Store and continue
cache.setSync("last:action", "login");
console.log("Action logged to cache");

/**
 * Removes the cached item with the given key from the file system
 * @param key - The cache key to remove
 * @returns Promise that resolves when removal is complete
 */
remove(key: string): Promise<void>;

// Remove specific item
await cache.remove("user:123");

// Remove session data
await cache.remove("session:expired");

// Remove multiple items
const keysToRemove = ["temp:data1", "temp:data2", "temp:data3"];
await Promise.all(keysToRemove.map(key => cache.remove(key)));

// Conditional removal
const userData = await cache.get("user:456");
if (userData && userData.expired) {
  await cache.remove("user:456");
}

// Primitives
await cache.set("string", "hello");
await cache.set("number", 42);
await cache.set("boolean", true);
await cache.set("null", null);

// Objects and arrays
await cache.set("object", { name: "Alice", tags: ["user", "admin"] });
await cache.set("array", [1, 2, 3, 4, 5]);

// Dates (special handling)
await cache.set("date", new Date());
const retrievedDate = await cache.get("date"); // Returns Date object

// Complex nested structures
await cache.set("complex", {
  users: [
    { id: 1, profile: { name: "Alice", settings: { theme: "dark" } } },
    { id: 2, profile: { name: "Bob", settings: { theme: "light" } } }
  ],
  metadata: {
    created: new Date(),
    version: "2.1.0"
  }
});

// Set item with 1 hour TTL
await cache.set("session", sessionData, 3600);

// Item automatically expires and returns undefined
setTimeout(async () => {
  const expired = await cache.get("session"); // undefined
}, 3600 * 1000 + 1000);

// Check before expiration
const fresh = await cache.get("session"); // Returns sessionData

// Handle missing keys gracefully
const user = await cache.get("nonexistent:user", { name: "Guest" });

// Handle cache key validation errors
try {
  await cache.set("", "empty key"); // Throws error
} catch (error) {
  console.error("Invalid cache key:", error.message);
}

// Handle file system errors
try {
  await cache.set("data", largeObject);
} catch (error) {
  if (error.code === 'ENOSPC') {
    console.error("Disk full, cannot write to cache");
  }
}