Core Cache Operations

/**
 * Main class for file entry caching with configurable change detection
 * @param options - Configuration options for the cache instance
 */
class FileEntryCache {
  constructor(options?: FileEntryCacheOptions);
  
  // Properties
  cache: FlatCache;
  useCheckSum: boolean;
  useModifiedTime: boolean;
  currentWorkingDirectory: string | undefined;
  hashAlgorithm: string;
}

interface FileEntryCacheOptions {
  currentWorkingDirectory?: string;
  useModifiedTime?: boolean;
  useCheckSum?: boolean;
  hashAlgorithm?: string;
  cache?: FlatCacheOptions;
}

import { FileEntryCache } from "file-entry-cache";

// Basic cache with default settings
const cache = new FileEntryCache();

// Cache with checksum validation
const checksumCache = new FileEntryCache({
  useCheckSum: true,
  hashAlgorithm: "sha256"
});

// Cache with specific working directory
const projectCache = new FileEntryCache({
  currentWorkingDirectory: "/path/to/project",
  useModifiedTime: true
});

/**
 * Creates a new FileEntryCache instance with specified cache ID and directory
 * @param cacheId - Identifier for the cache file
 * @param cacheDirectory - Directory to store cache files (optional)
 * @param useCheckSum - Enable checksum-based change detection (optional)
 * @param currentWorkingDirectory - Working directory for relative paths (optional)
 * @returns New FileEntryCache instance
 */
function create(
  cacheId: string,
  cacheDirectory?: string,
  useCheckSum?: boolean,
  currentWorkingDirectory?: string
): FileEntryCache;

/**
 * Creates a FileEntryCache instance from an existing cache file
 * @param filePath - Path to existing cache file
 * @param useCheckSum - Enable checksum-based change detection (optional)
 * @param currentWorkingDirectory - Working directory for relative paths (optional)
 * @returns New FileEntryCache instance loaded from file
 */
function createFromFile(
  filePath: string,
  useCheckSum?: boolean,
  currentWorkingDirectory?: string
): FileEntryCache;

import { create, createFromFile } from "file-entry-cache";

// Create a new cache with ID
const cache = create("build-cache", "./cache");

// Load existing cache from file
const existingCache = createFromFile("./cache/build-cache");

// Create cache with checksum validation
const checksumCache = create("secure-cache", "./cache", true);

/**
 * Gets file descriptor containing metadata and change status
 * @param filePath - Path to file (relative or absolute)
 * @param options - Options for file analysis
 * @returns FileDescriptor with metadata and change information
 */
getFileDescriptor(filePath: string, options?: GetFileDescriptorOptions): FileDescriptor;

/**
 * Checks if a file has changed since last analysis
 * @param filePath - Path to file to check
 * @returns True if file has changed, false otherwise
 */
hasFileChanged(filePath: string): boolean;

interface GetFileDescriptorOptions {
  useCheckSum?: boolean;
  useModifiedTime?: boolean;
  currentWorkingDirectory?: string;
}

interface FileDescriptor {
  key: string;
  changed?: boolean;
  meta: FileDescriptorMeta;
  notFound?: boolean;
  err?: Error;
}

interface FileDescriptorMeta {
  size?: number;
  mtime?: number;
  hash?: string;
  data?: unknown;
}

import { create } from "file-entry-cache";

const cache = create("my-cache");

// Basic file checking
const descriptor = cache.getFileDescriptor("src/app.js");
if (descriptor.changed) {
  console.log("File has changed");
}

// Check with custom options
const checksumDescriptor = cache.getFileDescriptor("config.json", {
  useCheckSum: true,
  currentWorkingDirectory: "/project"
});

// Simple change check
if (cache.hasFileChanged("package.json")) {
  console.log("Package.json updated");
}

// Handle errors
const result = cache.getFileDescriptor("missing-file.txt");
if (result.notFound) {
  console.log("File not found");
}
if (result.err) {
  console.error("Error accessing file:", result.err);
}

/**
 * Saves cache to disk and removes entries for files that no longer exist
 */
reconcile(): void;

/**
 * Deletes the cache file from disk
 * @returns True if file was deleted successfully
 */
deleteCacheFile(): boolean;

/**
 * Destroys the cache instance and removes cache file
 * Stops any persistence intervals if enabled
 */
destroy(): void;

import { create } from "file-entry-cache";

const cache = create("build-cache");

// Process files...
cache.getFileDescriptor("src/file1.js");
cache.getFileDescriptor("src/file2.js");

// Save cache and clean up missing files
cache.reconcile();

// Clean up cache file when done
cache.deleteCacheFile();

// Or completely destroy the cache
cache.destroy();

/**
 * Removes a specific file entry from the cache
 * @param filePath - Path to file to remove (relative or absolute)
 * @param options - Options including working directory
 */
removeEntry(filePath: string, options?: { currentWorkingDirectory?: string }): void;

import { create } from "file-entry-cache";

const cache = create("my-cache");

// Remove specific file from cache
cache.removeEntry("deleted-file.js");

// Remove with specific working directory
cache.removeEntry("temp.txt", {
  currentWorkingDirectory: "/project/build"
});