Merge branch 'cacheable---fix-updating-types-in-tests' of https://github.com/jaredwray/cacheable into cacheable---fix-updating-types-in-tests

Author: jaredwray

.gitignore

@@ -24,3 +24,4 @@ packages/website/site/docs/*.md
 packages/cacheable-request/test/testdb.sqlite
 packages/flat-cache/.cache
 packages/file-entry-cache/.cache
+packages/file-entry-cache/test/test-logger-file.txt

packages/file-entry-cache/README.md

@@ -36,6 +36,12 @@
 - [Path Security and Traversal Prevention](#path-security-and-traversal-prevention)
 - [Using Checksums to Determine if a File has Changed (useCheckSum)](#using-checksums-to-determine-if-a-file-has-changed-usechecksum)
 - [Setting Additional Meta Data](#setting-additional-meta-data)
+- [Logger Support](#logger-support)
+  - [Logger Interface](#logger-interface)
+  - [Using Pino Logger](#using-pino-logger)
+  - [Log Levels](#log-levels)
+  - [Example with Custom Log Levels](#example-with-custom-log-levels)
+  - [Debugging Cache Operations](#debugging-cache-operations)
 - [How to Contribute](#how-to-contribute)
 - [License and Copyright](#license-and-copyright)
 
@@ -117,6 +123,7 @@ There have been many features added and changes made to the `file-entry-cache` c
 - `hashAlgorithm?` - The algorithm to use for the checksum. Default is `md5` but can be any algorithm supported by `crypto.createHash`
 - `cwd?` - The current working directory for resolving relative paths. Default is `process.cwd()`
 - `strictPaths?` - If `true` restricts file access to within `cwd` boundaries, preventing path traversal attacks. Default is `true`
+- `logger?` - A logger instance compatible with Pino logger interface for debugging and monitoring. Default is `undefined`
 - `cache.ttl?` - The time to live for the cache in milliseconds. Default is `0` which means no expiration
 - `cache.lruSize?` - The number of items to keep in the cache. Default is `0` which means no limit
 - `cache.useClone?` - If `true` it will clone the data before returning it. Default is `false`
@@ -135,6 +142,7 @@ There have been many features added and changes made to the `file-entry-cache` c
 - `getHash(buffer: Buffer): string` - Gets the hash of a buffer used for checksums
 - `cwd: string` - The current working directory for resolving relative paths. Default is `process.cwd()`
 - `strictPaths: boolean` - If `true` restricts file access to within `cwd` boundaries. Default is `true`
+- `logger: ILogger | undefined` - A logger instance for debugging and monitoring cache operations
 - `createFileKey(filePath: string): string` - Returns the cache key for the file path (returns the path exactly as provided).
 - `deleteCacheFile(): boolean` - Deletes the cache file from disk
 - `destroy(): void` - Destroys the cache. This will clear the cache in memory. If using cache persistence it will stop the interval.
@@ -396,13 +404,132 @@ const fileDescriptor = fileEntryCache.getFileDescriptor('file.txt', { useCheckSu
 
 # Setting Additional Meta Data
 
-In the past we have seen people do random values on the `meta` object. This can cause issues with the `meta` object. To avoid this we have `data` which can be anything. 
+In the past we have seen people do random values on the `meta` object. This can cause issues with the `meta` object. To avoid this we have `data` which can be anything.
 
-```javascript 
+```javascript
 const fileEntryCache = new FileEntryCache();
 const fileDescriptor = fileEntryCache.getFileDescriptor('file.txt');
 fileDescriptor.meta.data = { myData: 'myData' }; //anything you want
 ```
+
+# Logger Support
+
+The `FileEntryCache` supports logging through a Pino-compatible logger interface. This is useful for debugging and monitoring cache operations in production environments.
+
+## Logger Interface
+
+The logger must implement the following interface:
+
+```typescript
+interface ILogger {
+  level?: string;
+  trace: (message: string | object, ...args: unknown[]) => void;
+  debug: (message: string | object, ...args: unknown[]) => void;
+  info: (message: string | object, ...args: unknown[]) => void;
+  warn: (message: string | object, ...args: unknown[]) => void;
+  error: (message: string | object, ...args: unknown[]) => void;
+  fatal: (message: string | object, ...args: unknown[]) => void;
+}
+```
+
+## Using Pino Logger
+
+You can pass a Pino logger instance to the `FileEntryCache` constructor or set it via the `logger` property:
+
+```javascript
+import pino from 'pino';
+import fileEntryCache from 'file-entry-cache';
+
+// Create a Pino logger
+const logger = pino({
+  level: 'debug',
+  transport: {
+    target: 'pino-pretty',
+    options: {
+      colorize: true
+    }
+  }
+});
+
+// Pass logger in constructor
+const cache = new fileEntryCache.FileEntryCache({
+  logger,
+  cacheId: 'my-cache'
+});
+
+// Or set it after creation
+cache.logger = logger;
+
+// Now all cache operations will be logged
+const descriptor = cache.getFileDescriptor('./src/file.txt');
+```
+
+## Log Levels
+
+The logger will output different levels of information:
+
+- **trace**: Detailed internal operations (key creation, cached meta lookup, file stats)
+- **debug**: Method entry, checksum settings, change detection, file status
+- **info**: Important state changes (file has changed)
+- **error**: File read errors and exceptions
+
+## Example with Custom Log Levels
+
+```javascript
+import pino from 'pino';
+import { FileEntryCache } from 'file-entry-cache';
+
+// Create logger with specific level
+const logger = pino({ level: 'info' });
+
+const cache = new FileEntryCache({
+  logger,
+  useCheckSum: true
+});
+
+// This will log at info level when files change
+const files = ['./src/index.js', './src/utils.js'];
+files.forEach(file => {
+  const descriptor = cache.getFileDescriptor(file);
+  if (descriptor.changed) {
+    console.log(`Processing changed file: ${file}`);
+  }
+});
+
+cache.reconcile();
+```
+
+## Debugging Cache Operations
+
+For detailed debugging, set the logger level to `debug` or `trace`:
+
+```javascript
+import pino from 'pino';
+import { FileEntryCache } from 'file-entry-cache';
+
+const logger = pino({
+  level: 'trace',
+  transport: {
+    target: 'pino-pretty'
+  }
+});
+
+const cache = new FileEntryCache({
+  logger,
+  useCheckSum: true,
+  cwd: '/project/root'
+});
+
+// Will log detailed information about:
+// - File path resolution
+// - Cache key creation
+// - Cached metadata lookup
+// - File stats reading
+// - Hash calculation (if using checksums)
+// - Change detection logic
+const descriptor = cache.getFileDescriptor('./src/app.js');
+```
+
 # How to Contribute
 
 You can contribute by forking the repo and submitting a pull request. Please make sure to add tests and update the documentation. To learn more about how to contribute go to our main README [https://github.com/jaredwray/cacheable](https://github.com/jaredwray/cacheable). This will talk about how to `Open a Pull Request`, `Ask a Question`, or `Post an Issue`.

packages/file-entry-cache/package.json

@@ -40,6 +40,7 @@
 		"@biomejs/biome": "^2.2.5",
 		"@types/node": "^24.7.0",
 		"@vitest/coverage-v8": "^3.2.4",
+		"pino": "^10.0.0",
 		"rimraf": "^6.0.1",
 		"tsup": "^8.5.0",
 		"typescript": "^5.9.3",

packages/file-entry-cache/src/index.ts

@@ -8,6 +8,23 @@ import {
 	type FlatCacheOptions,
 } from "flat-cache";
 
+export type ILogger = {
+	/** Current log level */
+	level?: string;
+	/** Trace level logging */
+	trace: (message: string | object, ...args: unknown[]) => void;
+	/** Debug level logging */
+	debug: (message: string | object, ...args: unknown[]) => void;
+	/** Info level logging */
+	info: (message: string | object, ...args: unknown[]) => void;
+	/** Warning level logging */
+	warn: (message: string | object, ...args: unknown[]) => void;
+	/** Error level logging */
+	error: (message: string | object, ...args: unknown[]) => void;
+	/** Fatal level logging */
+	fatal: (message: string | object, ...args: unknown[]) => void;
+};
+
 export type FileEntryCacheOptions = {
 	/** Whether to use file modified time for change detection (default: true) */
 	useModifiedTime?: boolean;
@@ -19,6 +36,8 @@ export type FileEntryCacheOptions = {
 	cwd?: string;
 	/** Restrict file access to within cwd boundaries (default: true) */
 	strictPaths?: boolean;
+	/** Logger instance for logging (default: undefined) */
+	logger?: ILogger;
 	/** Options for the underlying flat cache */
 	cache?: FlatCacheOptions;
 };
@@ -127,6 +146,7 @@ export class FileEntryCache {
 	private _hashAlgorithm = "md5";
 	private _cwd: string = process.cwd();
 	private _strictPaths = true;
+	private _logger?: ILogger;
 
 	/**
 	 * Create a new FileEntryCache instance
@@ -152,6 +172,10 @@ export class FileEntryCache {
 		if (options?.strictPaths !== undefined) {
 			this._strictPaths = options.strictPaths;
 		}
+
+		if (options?.logger) {
+			this._logger = options.logger;
+		}
 	}
 
 	/**
@@ -170,6 +194,22 @@ export class FileEntryCache {
 		this._cache = cache;
 	}
 
+	/**
+	 * Get the logger
+	 * @returns {ILogger | undefined} The logger instance
+	 */
+	public get logger(): ILogger | undefined {
+		return this._logger;
+	}
+
+	/**
+	 * Set the logger
+	 * @param {ILogger | undefined} logger - The logger to set
+	 */
+	public set logger(logger: ILogger | undefined) {
+		this._logger = logger;
+	}
+
 	/**
 	 * Use the hash to check if the file has changed
 	 * @returns {boolean} if the hash is used to check if the file has changed (default: false)
@@ -337,39 +377,62 @@ export class FileEntryCache {
 		filePath: string,
 		options?: GetFileDescriptorOptions,
 	): FileDescriptor {
+		this._logger?.debug({ filePath, options }, "Getting file descriptor");
+
 		let fstat: fs.Stats;
 		const result: FileDescriptor = {
 			key: this.createFileKey(filePath),
 			changed: false,
 			meta: {},
 		};
 
+		this._logger?.trace({ key: result.key }, "Created file key");
+
 		const metaCache = this._cache.getKey<FileDescriptorMeta>(result.key);
 
+		if (metaCache) {
+			this._logger?.trace({ metaCache }, "Found cached meta");
+		} else {
+			this._logger?.trace("No cached meta found");
+		}
+
 		// Start with cached meta to preserve custom properties
 		result.meta = metaCache ? { ...metaCache } : {};
 
 		// Convert to absolute path for file system operations
 		const absolutePath = this.getAbsolutePath(filePath);
+		this._logger?.trace({ absolutePath }, "Resolved absolute path");
 
 		const useCheckSumValue = options?.useCheckSum ?? this._useCheckSum;
+		this._logger?.debug(
+			{ useCheckSum: useCheckSumValue },
+			"Using checksum setting",
+		);
 
 		try {
 			fstat = fs.statSync(absolutePath);
 			// Update the file stats while preserving existing meta properties
 			result.meta.size = fstat.size;
 			result.meta.mtime = fstat.mtime.getTime();
 
+			this._logger?.trace(
+				{ size: result.meta.size, mtime: result.meta.mtime },
+				"Read file stats",
+			);
+
 			if (useCheckSumValue) {
 				// Get the file hash
 				const buffer = fs.readFileSync(absolutePath);
 				result.meta.hash = this.getHash(buffer);
+				this._logger?.trace({ hash: result.meta.hash }, "Calculated file hash");
 			}
 		} catch (error) {
+			this._logger?.error({ filePath, error }, "Error reading file");
 			this.removeEntry(filePath);
 			let notFound = false;
 			if ((error as Error).message.includes("ENOENT")) {
 				notFound = true;
+				this._logger?.debug({ filePath }, "File not found");
 			}
 
 			return {
@@ -384,25 +447,43 @@ export class FileEntryCache {
 		if (!metaCache) {
 			result.changed = true;
 			this._cache.setKey(result.key, result.meta);
+			this._logger?.debug({ filePath }, "File not in cache, marked as changed");
 			return result;
 		}
 
 		// If the file is in the cache, check if the file has changed
-		/* c8 ignore next 3 */
 		if (useCheckSumValue === false && metaCache?.mtime !== result.meta?.mtime) {
 			result.changed = true;
+			this._logger?.debug(
+				{ filePath, oldMtime: metaCache.mtime, newMtime: result.meta.mtime },
+				"File changed: mtime differs",
+			);
 		}
 
 		if (metaCache?.size !== result.meta?.size) {
 			result.changed = true;
+			this._logger?.debug(
+				{ filePath, oldSize: metaCache.size, newSize: result.meta.size },
+				"File changed: size differs",
+			);
 		}
 
 		if (useCheckSumValue && metaCache?.hash !== result.meta?.hash) {
 			result.changed = true;
+			this._logger?.debug(
+				{ filePath, oldHash: metaCache.hash, newHash: result.meta.hash },
+				"File changed: hash differs",
+			);
 		}
 
 		this._cache.setKey(result.key, result.meta);
 
+		if (result.changed) {
+			this._logger?.info({ filePath }, "File has changed");
+		} else {
+			this._logger?.debug({ filePath }, "File unchanged");
+		}
+
 		return result;
 	}