Flat Cache

import { FlatCache, create, createFromFile, clearCacheById, clearAll, FlatCacheOptions, FlatCacheEvents } from "flat-cache";
import type { CacheableMemory } from "cacheable";

const { FlatCache, create, createFromFile, clearCacheById, clearAll } = require("flat-cache");

import FlatCacheDefault from "flat-cache";
const cache = FlatCacheDefault.create();

import { create, FlatCacheOptions } from "flat-cache";

// Create a cache with default options
const cache = create();

// Create a cache with custom options
const cache = create({
  cacheDir: "./my-cache",
  cacheId: "my-app-cache",
  ttl: 300000, // 5 minutes
  persistInterval: 10000 // auto-save every 10 seconds
});

// Set and get values
cache.set("key1", { data: "value1" });
cache.set("key2", "value2", 60000); // with 60 second TTL

const value1 = cache.get("key1");
const value2 = cache.get<string>("key2"); // with type parameter

// Persistence
cache.save(); // manually save to disk
cache.load(); // load from disk

class FlatCache {
  /**
   * Creates new FlatCache instance with optional configuration
   * @param options - Optional configuration options for the cache
   */
  constructor(options?: FlatCacheOptions);
}

/**
 * Create new FlatCache instance and automatically load from disk if exists
 * @param options - Configuration options for the cache
 * @returns FlatCache instance
 */
function create(options?: FlatCacheOptions): FlatCache;

/**
 * Create FlatCache instance and load from specific file
 * @param filePath - Path to the cache file to load
 * @param options - Configuration options for the cache
 * @returns FlatCache instance
 */
function createFromFile(filePath: string, options?: FlatCacheOptions): FlatCache;

class FlatCache {
  /**
   * Sets a key to a given value
   * @param key - The key to set
   * @param value - The value to store (any serializable object)
   * @param ttl - Optional time to live in milliseconds
   */
  set(key: string, value: any, ttl?: number | string): void;

  /**
   * Return the value of the provided key
   * @param key - The name of the key to retrieve
   * @returns The value from the key with type T
   */
  get<T>(key: string): T;

  /**
   * Remove a given key from the cache
   * @param key - The key to remove from the object
   */
  delete(key: string): void;

  /**
   * Returns an array with all the keys in the cache
   * @returns Array of all cache keys
   */
  keys(): string[];

  /**
   * Returns the entire persisted object
   * @returns Object containing all key-value pairs
   */
  all(): Record<string, any>;
}

class FlatCache {
  /**
   * Save the state of the cache to disk as a JSON structure
   * @param force - Force save even if no changes since last save
   */
  save(force?: boolean): void;

  /**
   * Load a cache identified by the given Id from disk
   * @param cacheId - The id of the cache, also used as filename
   * @param cacheDir - Directory for the cache entry
   */
  load(cacheId?: string, cacheDir?: string): void;

  /**
   * Load the cache from the provided file
   * @param pathToFile - The path to the file containing the cache data
   */
  loadFile(pathToFile: string): void;

  /**
   * Load cache using streams for large files with progress tracking
   * @param pathToFile - Path to the cache file
   * @param onProgress - Callback for progress updates (loaded, total)
   * @param onEnd - Callback when loading is complete
   * @param onError - Optional error callback
   */
  loadFileStream(
    pathToFile: string,
    onProgress: (progress: number, total: number) => void,
    onEnd: () => void,
    onError?: (error: Error) => void
  ): void;
}

class FlatCache {
  /**
   * Clear the cache and save the state to disk
   */
  clear(): void;

  /**
   * Destroy the cache, removing files and clearing memory
   * @param includeCacheDirectory - If true, remove the entire cache directory
   */
  destroy(includeCacheDirectory?: boolean): void;

  /**
   * Remove the file where the cache is persisted
   * @returns True if file was successfully deleted
   */
  removeCacheFile(): boolean;
}

/**
 * Clear specific cache by ID from disk (not memory)
 * @param cacheId - The id of the cache to clear
 * @param cacheDirectory - Optional directory for the cache entry
 */
function clearCacheById(cacheId: string, cacheDirectory?: string): void;

/**
 * Clear entire cache directory
 * @param cacheDirectory - Optional directory to clear (defaults to ".cache")
 */
function clearAll(cacheDirectory?: string): void;

class FlatCache {
  /**
   * Start the auto persist interval
   */
  startAutoPersist(): void;

  /**
   * Stop the auto persist interval
   */
  stopAutoPersist(): void;
}

class FlatCache {
  /**
   * Add an event listener for a specific event
   * @param eventName - The name of the event to listen for
   * @param handler - The function to call when the event is emitted
   */
  on(eventName: string, handler: Function): this;

  /**
   * Remove an event listener for a specific event
   * @param eventName - The name of the event
   * @param handler - The handler function to remove
   */
  off(eventName: string, handler: Function): this;

  /**
   * Add a one-time event listener that removes itself after first execution
   * @param eventName - The name of the event to listen for
   * @param handler - The function to call when the event is emitted
   */
  once(eventName: string, handler: Function): this;

  /**
   * Add an event listener to the beginning of the listeners array
   * @param eventName - The name of the event to listen for
   * @param handler - The function to call when the event is emitted
   */
  prependListener(eventName: string, handler: Function): this;

  /**
   * Add a one-time event listener to the beginning of the listeners array
   * @param eventName - The name of the event to listen for
   * @param handler - The function to call when the event is emitted
   */
  prependOnceListener(eventName: string, handler: Function): this;

  /**
   * Remove all listeners for a specific event, or all events if no event specified
   * @param eventName - Optional event name to remove listeners for
   */
  removeAllListeners(eventName?: string): this;

  /**
   * Get array of listener functions for a specific event
   * @param eventName - The name of the event
   * @returns Array of listener functions
   */
  listeners(eventName: string): Function[];

  /**
   * Get array of all event names that have listeners
   * @returns Array of event names
   */
  eventNames(): string[];

  /**
   * Get the number of listeners for a specific event
   * @param eventName - The name of the event
   * @returns Number of listeners
   */
  listenerCount(eventName: string): number;

  /**
   * Set the maximum number of listeners for this instance
   * @param maxListeners - Maximum number of listeners
   */
  setMaxListeners(maxListeners: number): this;

  /** Controls whether errors during event emission should be thrown */
  throwOnEmitError: boolean;
}

class FlatCache {
  /** The underlying in-memory cache instance */
  readonly cache: CacheableMemory;

  /** Directory for cache files (get/set) */
  cacheDir: string;

  /** Cache identifier (get/set) */
  cacheId: string;

  /** Flag indicating unsaved changes (readonly) */
  readonly changesSinceLastSave: boolean;

  /** Auto-persist interval in milliseconds (get/set) */
  persistInterval: number;

  /** All cache items as array with key, value, expires timestamp (readonly) */
  readonly items: Array<{key: string, value: any, expires?: number}>;

  /** Full path to cache file (readonly) */
  readonly cacheFilePath: string;

  /** Full path to cache directory (readonly) */
  readonly cacheDirPath: string;
}

class FlatCache {
  /**
   * @deprecated Use get() instead
   */
  getKey<T>(key: string): T;

  /**
   * @deprecated Use set() instead
   */
  setKey(key: string, value: any, ttl?: number | string): void;

  /**
   * @deprecated Use delete() instead
   */
  removeKey(key: string): void;
}

/**
 * Legacy default export class providing static utility methods
 * @deprecated Use named imports instead
 */
class FlatCacheDefault {
  static create: typeof create;
  static createFromFile: typeof createFromFile;
  static clearCacheById: typeof clearCacheById;
  static clearAll: typeof clearAll;
}

type FlatCacheOptions = {
  /** Time to live for cache items in milliseconds */
  ttl?: number | string;
  /** Whether to clone data before returning */
  useClone?: boolean;
  /** Maximum number of items in cache (LRU eviction) */
  lruSize?: number;
  /** Interval to check for expired items in milliseconds */
  expirationInterval?: number;
  /** Interval to auto-save cache to disk in milliseconds */
  persistInterval?: number;
  /** Directory for cache files (default: ".cache") */
  cacheDir?: string;
  /** Identifier for cache file (default: "cache1") */
  cacheId?: string;
  /** Custom deserialization function */
  deserialize?: (data: string) => any;
  /** Custom serialization function */
  serialize?: (data: any) => string;
};

enum FlatCacheEvents {
  SAVE = "save",      // Emitted when cache is saved to disk
  LOAD = "load",      // Emitted when cache is loaded from disk
  DELETE = "delete",  // Emitted when a key is deleted (receives key as parameter)
  CLEAR = "clear",    // Emitted when cache is cleared
  DESTROY = "destroy", // Emitted when cache is destroyed
  ERROR = "error",    // Emitted when an error occurs (receives Error as parameter)
  EXPIRED = "expired" // Emitted when items expire (receives key as parameter)
}

// Event handler type signatures based on actual implementation
type SaveHandler = () => void;
type LoadHandler = () => void;
type DeleteHandler = (key: string) => void;
type ClearHandler = () => void;
type DestroyHandler = () => void;
type ErrorHandler = (error: Error) => void;
type ExpiredHandler = (key: string) => void;

// CacheableMemory interface (from cacheable dependency)
interface CacheableMemory {
  get(key: string): any;
  set(key: string, value: any, ttl?: number | string): void;
  delete(key: string): void;
  clear(): void;
  keys: string[];
  size: number;
  items: Array<{key: string, value: any, expires?: number}>;
}

import { create, FlatCacheEvents } from "flat-cache";

const cache = create({ cacheDir: "./cache", cacheId: "my-cache" });

// Listen to cache events
cache.on(FlatCacheEvents.SAVE, () => {
  console.log("Cache saved to disk");
});

cache.on(FlatCacheEvents.ERROR, (error) => {
  console.error("Cache error:", error);
});

cache.on(FlatCacheEvents.DELETE, (key) => {
  console.log(`Key deleted: ${key}`);
});

import { createFromFile } from "flat-cache";

const cache = createFromFile("./large-cache-file");

cache.loadFileStream(
  "./very-large-cache.json",
  (progress, total) => {
    console.log(`Loading: ${Math.round((progress / total) * 100)}%`);
  },
  () => {
    console.log("Cache loaded successfully");
  },
  (error) => {
    console.error("Error loading cache:", error);
  }
);

import { create } from "flat-cache";

const cache = create({
  persistInterval: 30000, // auto-save every 30 seconds
  ttl: 300000, // 5 minute default TTL
  lruSize: 1000 // max 1000 items
});

// Cache will automatically save every 30 seconds
cache.set("data", { important: "value" });

// Stop auto-persistence when done
cache.stopAutoPersist();

import { create } from "flat-cache";

// Use custom JSON serialization instead of flatted
const cache = create({
  serialize: (data) => JSON.stringify(data),
  deserialize: (data) => JSON.parse(data)
});