Configuration & Utilities

interface FileEntryCacheOptions {
  /** Working directory for resolving relative paths */
  currentWorkingDirectory?: string;
  /** Whether to use file modification time for change detection (default: true) */
  useModifiedTime?: boolean;
  /** Whether to use checksums for change detection (default: false) */
  useCheckSum?: boolean;
  /** Hash algorithm for checksums (default: "md5") */
  hashAlgorithm?: string;
  /** Options for the underlying flat-cache instance */
  cache?: FlatCacheOptions;
}

interface FlatCacheOptions {
  /** Unique identifier for the cache */
  cacheId?: string;
  /** Directory to store cache files */
  cacheDir?: string;
  /** Time-to-live for cache entries in milliseconds */
  ttl?: number;
  /** Maximum number of entries to keep in memory */
  lruSize?: number;
  /** Whether to clone data when returning from cache */
  useClone?: boolean;
  /** Interval for checking expired entries */
  expirationInterval?: number;
  /** Interval for persisting cache to disk */
  persistInterval?: number;
}

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

// Basic configuration
const cache = new FileEntryCache({
  currentWorkingDirectory: "/path/to/project",
  useCheckSum: true,
  hashAlgorithm: "sha256"
});

// Advanced configuration with flat-cache options
const advancedCache = new FileEntryCache({
  useCheckSum: true,
  useModifiedTime: true,
  hashAlgorithm: "sha1",
  cache: {
    cacheId: "my-build-cache",
    cacheDir: "./build/cache",
    ttl: 3600000, // 1 hour
    persistInterval: 30000 // Save every 30 seconds
  }
});

// Access and modify configuration at runtime
cache.useCheckSum = false;
cache.hashAlgorithm = "md5";
cache.currentWorkingDirectory = "/new/project/path";

/**
 * Calculates hash of buffer content using the configured algorithm
 * @param buffer - Buffer containing data to hash
 * @returns Hexadecimal hash string
 */
getHash(buffer: Buffer): string;

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

const cache = new FileEntryCache({ hashAlgorithm: "sha256" });

// Hash file contents
const fileBuffer = fs.readFileSync("config.json");
const hash = cache.getHash(fileBuffer);
console.log("File hash:", hash);

// Compare with cached hash
const descriptor = cache.getFileDescriptor("config.json");
if (descriptor.meta.hash === hash) {
  console.log("File content matches cache");
} else {
  console.log("File content has changed");
}

// Hash arbitrary data
const textBuffer = Buffer.from("Hello, world!");
const textHash = cache.getHash(textBuffer);
console.log("Text hash:", textHash);

/**
 * Creates a cache key from a file path, handling relative/absolute path normalization
 * @param filePath - File path to create key from
 * @param options - Options including working directory for path resolution
 * @returns Normalized cache key string
 */
createFileKey(
  filePath: string,
  options?: { currentWorkingDirectory?: string }
): string;

/**
 * Checks if a file path is relative (not absolute)
 * @param filePath - Path to check
 * @returns True if path is relative, false if absolute
 */
isRelativePath(filePath: string): boolean;

/**
 * Converts relative paths to absolute using working directory
 * If path is already absolute, returns it unchanged
 * @param filePath - Path to convert
 * @param options - Options including working directory for resolution
 * @returns Absolute file path
 */
getAbsolutePath(
  filePath: string,
  options?: { currentWorkingDirectory?: string }
): string;

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

const cache = new FileEntryCache({
  currentWorkingDirectory: "/home/user/project"
});

// Create cache keys
const key1 = cache.createFileKey("src/app.js");
console.log("Cache key:", key1); // "src/app.js"

const key2 = cache.createFileKey("/home/user/project/src/app.js");
console.log("Cache key:", key2); // "src/app.js" (normalized)

// Check path types
console.log(cache.isRelativePath("src/file.js")); // true
console.log(cache.isRelativePath("/absolute/path.js")); // false

// Convert paths to absolute
const absolutePath = cache.getAbsolutePath("src/app.js");
console.log("Absolute path:", absolutePath); // "/home/user/project/src/app.js"

// Already absolute path
const stillAbsolute = cache.getAbsolutePath("/tmp/file.txt");
console.log("Still absolute:", stillAbsolute); // "/tmp/file.txt"

// Override working directory
const customKey = cache.createFileKey("test.js", {
  currentWorkingDirectory: "/different/path"
});

/**
 * Renames cache keys when directories are moved or renamed
 * Updates all cache keys that start with the old path
 * @param oldPath - Old path prefix to replace
 * @param newPath - New path prefix to use
 */
renameAbsolutePathKeys(oldPath: string, newPath: string): void;

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

const cache = new FileEntryCache();

// Add some files to cache
cache.getFileDescriptor("/old/project/src/app.js");
cache.getFileDescriptor("/old/project/src/utils.js");
cache.getFileDescriptor("/old/project/config.json");

// Project directory was moved
cache.renameAbsolutePathKeys("/old/project", "/new/project");

// Now the cache keys are updated:
// "/old/project/src/app.js" -> "/new/project/src/app.js"
// "/old/project/src/utils.js" -> "/new/project/src/utils.js"
// "/old/project/config.json" -> "/new/project/config.json"

// Verify the change
const descriptor = cache.getFileDescriptor("/new/project/src/app.js");
console.log("File found at new location:", !descriptor.notFound);

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

const isDevelopment = process.env.NODE_ENV === "development";

const cache = new FileEntryCache({
  useCheckSum: !isDevelopment, // Use checksums in production
  useModifiedTime: true,
  hashAlgorithm: isDevelopment ? "md5" : "sha256",
  cache: {
    persistInterval: isDevelopment ? 5000 : 0, // Auto-save in dev
    ttl: isDevelopment ? 0 : 3600000 // 1 hour TTL in production
  }
});

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

// Different caches for different purposes
const buildCache = create("build-cache", "./cache", false, "./src");
const lintCache = create("lint-cache", "./cache", true, "./"); // With checksums
const testCache = create("test-cache", "./cache", false, "./test");

// Configure after creation
lintCache.hashAlgorithm = "sha1";
testCache.useModifiedTime = true;

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

const cache = new FileEntryCache();

// Process files from different directories
const srcFiles = ["app.js", "utils.js"];
const testFiles = ["app.test.js", "utils.test.js"];

// Analyze src files
cache.currentWorkingDirectory = "./src";
const srcDescriptors = srcFiles.map(file => cache.getFileDescriptor(file));

// Analyze test files
cache.currentWorkingDirectory = "./test";
const testDescriptors = testFiles.map(file => cache.getFileDescriptor(file));

// Reset to project root
cache.currentWorkingDirectory = undefined;