file-entry-cache 11.0.0-beta.3 → 11.0.0-beta.5

package/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`.

package/dist/index.cjs

@@ -1,464 +1 @@
-"use strict";
-var __create = Object.create;
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __getProtoOf = Object.getPrototypeOf;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, { get: all[name], enumerable: true });
-};
-var __copyProps = (to, from, except, desc) => {
-  if (from && typeof from === "object" || typeof from === "function") {
-    for (let key of __getOwnPropNames(from))
-      if (!__hasOwnProp.call(to, key) && key !== except)
-        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
-  }
-  return to;
-};
-var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
-  // If the importer is in node compatibility mode or this is not an ESM
-  // file that has been converted to a CommonJS file using a Babel-
-  // compatible transform (i.e. "__esModule" has not been set), then set
-  // "default" to the CommonJS "module.exports" for node compatibility.
-  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
-  mod
-));
-var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-
-// src/index.ts
-var index_exports = {};
-__export(index_exports, {
-  FileEntryCache: () => FileEntryCache,
-  create: () => create,
-  createFromFile: () => createFromFile,
-  default: () => FileEntryDefault
-});
-module.exports = __toCommonJS(index_exports);
-var import_node_crypto = __toESM(require("crypto"), 1);
-var import_node_fs = __toESM(require("fs"), 1);
-var import_node_path = __toESM(require("path"), 1);
-var import_flat_cache = require("flat-cache");
-function createFromFile(filePath, useCheckSum, cwd) {
-  const fname = import_node_path.default.basename(filePath);
-  const directory = import_node_path.default.dirname(filePath);
-  return create(fname, directory, useCheckSum, cwd);
-}
-function create(cacheId, cacheDirectory, useCheckSum, cwd) {
-  const options = {
-    useCheckSum,
-    cwd,
-    cache: {
-      cacheId,
-      cacheDir: cacheDirectory
-    }
-  };
-  const fileEntryCache = new FileEntryCache(options);
-  if (cacheDirectory) {
-    const cachePath = `${cacheDirectory}/${cacheId}`;
-    if (import_node_fs.default.existsSync(cachePath)) {
-      fileEntryCache.cache = (0, import_flat_cache.createFromFile)(cachePath, options.cache);
-    }
-  }
-  return fileEntryCache;
-}
-var FileEntryDefault = class {
-  static create = create;
-  static createFromFile = createFromFile;
-};
-var FileEntryCache = class {
-  _cache = new import_flat_cache.FlatCache({ useClone: false });
-  _useCheckSum = false;
-  _hashAlgorithm = "md5";
-  _cwd = process.cwd();
-  _strictPaths = true;
-  /**
-   * Create a new FileEntryCache instance
-   * @param options - The options for the FileEntryCache (all properties are optional with defaults)
-   */
-  constructor(options) {
-    if (options?.cache) {
-      this._cache = new import_flat_cache.FlatCache(options.cache);
-    }
-    if (options?.useCheckSum) {
-      this._useCheckSum = options.useCheckSum;
-    }
-    if (options?.hashAlgorithm) {
-      this._hashAlgorithm = options.hashAlgorithm;
-    }
-    if (options?.cwd) {
-      this._cwd = options.cwd;
-    }
-    if (options?.strictPaths !== void 0) {
-      this._strictPaths = options.strictPaths;
-    }
-  }
-  /**
-   * Get the cache
-   * @returns {FlatCache} The cache
-   */
-  get cache() {
-    return this._cache;
-  }
-  /**
-   * Set the cache
-   * @param {FlatCache} cache - The cache to set
-   */
-  set cache(cache) {
-    this._cache = cache;
-  }
-  /**
-   * 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)
-   */
-  get useCheckSum() {
-    return this._useCheckSum;
-  }
-  /**
-   * Set the useCheckSum value
-   * @param {boolean} value - The value to set
-   */
-  set useCheckSum(value) {
-    this._useCheckSum = value;
-  }
-  /**
-   * Get the hash algorithm
-   * @returns {string} The hash algorithm (default: 'md5')
-   */
-  get hashAlgorithm() {
-    return this._hashAlgorithm;
-  }
-  /**
-   * Set the hash algorithm
-   * @param {string} value - The value to set
-   */
-  set hashAlgorithm(value) {
-    this._hashAlgorithm = value;
-  }
-  /**
-   * Get the current working directory
-   * @returns {string} The current working directory (default: process.cwd())
-   */
-  get cwd() {
-    return this._cwd;
-  }
-  /**
-   * Set the current working directory
-   * @param {string} value - The value to set
-   */
-  set cwd(value) {
-    this._cwd = value;
-  }
-  /**
-   * Get whether to restrict paths to cwd boundaries
-   * @returns {boolean} Whether strict path checking is enabled (default: true)
-   */
-  get strictPaths() {
-    return this._strictPaths;
-  }
-  /**
-   * Set whether to restrict paths to cwd boundaries
-   * @param {boolean} value - The value to set
-   */
-  set strictPaths(value) {
-    this._strictPaths = value;
-  }
-  /**
-   * Given a buffer, calculate md5 hash of its content.
-   * @method getHash
-   * @param  {Buffer} buffer   buffer to calculate hash on
-   * @return {String}          content hash digest
-   */
-  getHash(buffer) {
-    return import_node_crypto.default.createHash(this._hashAlgorithm).update(buffer).digest("hex");
-  }
-  /**
-   * Create the key for the file path used for caching.
-   * @method createFileKey
-   * @param {String} filePath
-   * @return {String}
-   */
-  createFileKey(filePath) {
-    return filePath;
-  }
-  /**
-   * Check if the file path is a relative path
-   * @method isRelativePath
-   * @param filePath - The file path to check
-   * @returns {boolean} if the file path is a relative path, false otherwise
-   */
-  isRelativePath(filePath) {
-    return !import_node_path.default.isAbsolute(filePath);
-  }
-  /**
-   * Delete the cache file from the disk
-   * @method deleteCacheFile
-   * @return {boolean}       true if the file was deleted, false otherwise
-   */
-  deleteCacheFile() {
-    return this._cache.removeCacheFile();
-  }
-  /**
-   * Remove the cache from the file and clear the memory cache
-   * @method destroy
-   */
-  destroy() {
-    this._cache.destroy();
-  }
-  /**
-   * Remove and Entry From the Cache
-   * @method removeEntry
-   * @param filePath - The file path to remove from the cache
-   */
-  removeEntry(filePath) {
-    const key = this.createFileKey(filePath);
-    this._cache.removeKey(key);
-  }
-  /**
-   * Reconcile the cache
-   * @method reconcile
-   */
-  reconcile() {
-    const { items } = this._cache;
-    for (const item of items) {
-      const fileDescriptor = this.getFileDescriptor(item.key);
-      if (fileDescriptor.notFound) {
-        this._cache.removeKey(item.key);
-      }
-    }
-    this._cache.save();
-  }
-  /**
-   * Check if the file has changed
-   * @method hasFileChanged
-   * @param filePath - The file path to check
-   * @returns {boolean} if the file has changed, false otherwise
-   */
-  hasFileChanged(filePath) {
-    let result = false;
-    const fileDescriptor = this.getFileDescriptor(filePath);
-    if ((!fileDescriptor.err || !fileDescriptor.notFound) && fileDescriptor.changed) {
-      result = true;
-    }
-    return result;
-  }
-  /**
-   * Get the file descriptor for the file path
-   * @method getFileDescriptor
-   * @param filePath - The file path to get the file descriptor for
-   * @param options - The options for getting the file descriptor
-   * @returns The file descriptor
-   */
-  getFileDescriptor(filePath, options) {
-    let fstat;
-    const result = {
-      key: this.createFileKey(filePath),
-      changed: false,
-      meta: {}
-    };
-    result.meta = this._cache.getKey(result.key) ?? {};
-    const absolutePath = this.getAbsolutePath(filePath);
-    const useCheckSumValue = options?.useCheckSum ?? this._useCheckSum;
-    try {
-      fstat = import_node_fs.default.statSync(absolutePath);
-      result.meta = {
-        size: fstat.size
-      };
-      result.meta.mtime = fstat.mtime.getTime();
-      if (useCheckSumValue) {
-        const buffer = import_node_fs.default.readFileSync(absolutePath);
-        result.meta.hash = this.getHash(buffer);
-      }
-    } catch (error) {
-      this.removeEntry(filePath);
-      let notFound = false;
-      if (error.message.includes("ENOENT")) {
-        notFound = true;
-      }
-      return {
-        key: result.key,
-        err: error,
-        notFound,
-        meta: {}
-      };
-    }
-    const metaCache = this._cache.getKey(result.key);
-    if (!metaCache) {
-      result.changed = true;
-      this._cache.setKey(result.key, result.meta);
-      return result;
-    }
-    if (result.meta.data === void 0) {
-      result.meta.data = metaCache.data;
-    }
-    if (useCheckSumValue === false && metaCache?.mtime !== result.meta?.mtime) {
-      result.changed = true;
-    }
-    if (metaCache?.size !== result.meta?.size) {
-      result.changed = true;
-    }
-    if (useCheckSumValue && metaCache?.hash !== result.meta?.hash) {
-      result.changed = true;
-    }
-    this._cache.setKey(result.key, result.meta);
-    return result;
-  }
-  /**
-   * Get the file descriptors for the files
-   * @method normalizeEntries
-   * @param files?: string[] - The files to get the file descriptors for
-   * @returns The file descriptors
-   */
-  normalizeEntries(files) {
-    const result = [];
-    if (files) {
-      for (const file of files) {
-        const fileDescriptor = this.getFileDescriptor(file);
-        result.push(fileDescriptor);
-      }
-      return result;
-    }
-    const keys = this.cache.keys();
-    for (const key of keys) {
-      const fileDescriptor = this.getFileDescriptor(key);
-      if (!fileDescriptor.notFound && !fileDescriptor.err) {
-        result.push(fileDescriptor);
-      }
-    }
-    return result;
-  }
-  /**
-   * Analyze the files
-   * @method analyzeFiles
-   * @param files - The files to analyze
-   * @returns {AnalyzedFiles} The analysis of the files
-   */
-  analyzeFiles(files) {
-    const result = {
-      changedFiles: [],
-      notFoundFiles: [],
-      notChangedFiles: []
-    };
-    const fileDescriptors = this.normalizeEntries(files);
-    for (const fileDescriptor of fileDescriptors) {
-      if (fileDescriptor.notFound) {
-        result.notFoundFiles.push(fileDescriptor.key);
-      } else if (fileDescriptor.changed) {
-        result.changedFiles.push(fileDescriptor.key);
-      } else {
-        result.notChangedFiles.push(fileDescriptor.key);
-      }
-    }
-    return result;
-  }
-  /**
-   * Get the updated files
-   * @method getUpdatedFiles
-   * @param files - The files to get the updated files for
-   * @returns {string[]} The updated files
-   */
-  getUpdatedFiles(files) {
-    const result = [];
-    const fileDescriptors = this.normalizeEntries(files);
-    for (const fileDescriptor of fileDescriptors) {
-      if (fileDescriptor.changed) {
-        result.push(fileDescriptor.key);
-      }
-    }
-    return result;
-  }
-  /**
-   * Get the file descriptors by path prefix
-   * @method getFileDescriptorsByPath
-   * @param filePath - the path prefix to match
-   * @returns {FileDescriptor[]} The file descriptors
-   */
-  getFileDescriptorsByPath(filePath) {
-    const result = [];
-    const keys = this._cache.keys();
-    for (const key of keys) {
-      if (key.startsWith(filePath)) {
-        const fileDescriptor = this.getFileDescriptor(key);
-        result.push(fileDescriptor);
-      }
-    }
-    return result;
-  }
-  /**
-   * Get the Absolute Path. If it is already absolute it will return the path as is.
-   * When strictPaths is enabled, ensures the resolved path stays within cwd boundaries.
-   * @method getAbsolutePath
-   * @param filePath - The file path to get the absolute path for
-   * @returns {string}
-   * @throws {Error} When strictPaths is true and path would resolve outside cwd
-   */
-  getAbsolutePath(filePath) {
-    if (this.isRelativePath(filePath)) {
-      const sanitizedPath = filePath.replace(/\0/g, "");
-      const resolved = import_node_path.default.resolve(this._cwd, sanitizedPath);
-      if (this._strictPaths) {
-        const normalizedResolved = import_node_path.default.normalize(resolved);
-        const normalizedCwd = import_node_path.default.normalize(this._cwd);
-        const isWithinCwd = normalizedResolved === normalizedCwd || normalizedResolved.startsWith(normalizedCwd + import_node_path.default.sep);
-        if (!isWithinCwd) {
-          throw new Error(
-            `Path traversal attempt blocked: "${filePath}" resolves outside of working directory "${this._cwd}"`
-          );
-        }
-      }
-      return resolved;
-    }
-    return filePath;
-  }
-  /**
-   * Get the Absolute Path with a custom working directory. If it is already absolute it will return the path as is.
-   * When strictPaths is enabled, ensures the resolved path stays within the provided cwd boundaries.
-   * @method getAbsolutePathWithCwd
-   * @param filePath - The file path to get the absolute path for
-   * @param cwd - The custom working directory to resolve relative paths from
-   * @returns {string}
-   * @throws {Error} When strictPaths is true and path would resolve outside the provided cwd
-   */
-  getAbsolutePathWithCwd(filePath, cwd) {
-    if (this.isRelativePath(filePath)) {
-      const sanitizedPath = filePath.replace(/\0/g, "");
-      const resolved = import_node_path.default.resolve(cwd, sanitizedPath);
-      if (this._strictPaths) {
-        const normalizedResolved = import_node_path.default.normalize(resolved);
-        const normalizedCwd = import_node_path.default.normalize(cwd);
-        const isWithinCwd = normalizedResolved === normalizedCwd || normalizedResolved.startsWith(normalizedCwd + import_node_path.default.sep);
-        if (!isWithinCwd) {
-          throw new Error(
-            `Path traversal attempt blocked: "${filePath}" resolves outside of working directory "${cwd}"`
-          );
-        }
-      }
-      return resolved;
-    }
-    return filePath;
-  }
-  /**
-   * Rename cache keys that start with a given path prefix.
-   * @method renameCacheKeys
-   * @param oldPath - The old path prefix to rename
-   * @param newPath - The new path prefix to rename to
-   */
-  renameCacheKeys(oldPath, newPath) {
-    const keys = this._cache.keys();
-    for (const key of keys) {
-      if (key.startsWith(oldPath)) {
-        const newKey = key.replace(oldPath, newPath);
-        const meta = this._cache.getKey(key);
-        this._cache.removeKey(key);
-        this._cache.setKey(newKey, meta);
-      }
-    }
-  }
-};
-// Annotate the CommonJS export names for ESM import in node:
-0 && (module.exports = {
-  FileEntryCache,
-  create,
-  createFromFile
-});
+"use strict";var k=Object.create;var g=Object.defineProperty;var C=Object.getOwnPropertyDescriptor;var w=Object.getOwnPropertyNames;var v=Object.getPrototypeOf,A=Object.prototype.hasOwnProperty;var z=(o,e)=>{for(var s in e)g(o,s,{get:e[s],enumerable:!0})},y=(o,e,s,i)=>{if(e&&typeof e=="object"||typeof e=="function")for(let t of w(e))!A.call(o,t)&&t!==s&&g(o,t,{get:()=>e[t],enumerable:!(i=C(e,t))||i.enumerable});return o};var p=(o,e,s)=>(s=o!=null?k(v(o)):{},y(e||!o||!o.__esModule?g(s,"default",{value:o,enumerable:!0}):s,o)),D=o=>y(g({},"__esModule",{value:!0}),o);var K={};z(K,{FileEntryCache:()=>m,create:()=>f,createFromFile:()=>_,default:()=>d});module.exports=D(K);var F=p(require("crypto"),1),u=p(require("fs"),1),c=p(require("path"),1),l=require("flat-cache");function _(o,e){let s=c.default.basename(o),i=c.default.dirname(o);return f(s,i,e)}function f(o,e,s){let i={...s,cache:{cacheId:o,cacheDir:e}},t=new m(i);if(e){let r=`${e}/${o}`;u.default.existsSync(r)&&(t.cache=(0,l.createFromFile)(r,i.cache))}return t}var d=class{static create=f;static createFromFile=_},m=class{_cache=new l.FlatCache({useClone:!1});_useCheckSum=!1;_hashAlgorithm="md5";_cwd=process.cwd();_strictPaths=!1;_logger;_useAbsolutePathAsKey=!1;constructor(e){e?.cache&&(this._cache=new l.FlatCache(e.cache)),e?.useCheckSum&&(this._useCheckSum=e.useCheckSum),e?.hashAlgorithm&&(this._hashAlgorithm=e.hashAlgorithm),e?.cwd&&(this._cwd=e.cwd),e?.strictPaths!==void 0&&(this._strictPaths=e.strictPaths),e?.useAbsolutePathAsKey!==void 0&&(this._useAbsolutePathAsKey=e.useAbsolutePathAsKey),e?.logger&&(this._logger=e.logger)}get cache(){return this._cache}set cache(e){this._cache=e}get logger(){return this._logger}set logger(e){this._logger=e}get useCheckSum(){return this._useCheckSum}set useCheckSum(e){this._useCheckSum=e}get hashAlgorithm(){return this._hashAlgorithm}set hashAlgorithm(e){this._hashAlgorithm=e}get cwd(){return this._cwd}set cwd(e){this._cwd=e}get strictPaths(){return this._strictPaths}set strictPaths(e){this._strictPaths=e}get useAbsolutePathAsKey(){return this._useAbsolutePathAsKey}set useAbsolutePathAsKey(e){this._useAbsolutePathAsKey=e}getHash(e){return F.default.createHash(this._hashAlgorithm).update(e).digest("hex")}createFileKey(e){let s=e;return this._useAbsolutePathAsKey&&this.isRelativePath(e)&&(s=this.getAbsolutePathWithCwd(e,this._cwd)),s}isRelativePath(e){return!c.default.isAbsolute(e)}deleteCacheFile(){return this._cache.removeCacheFile()}destroy(){this._cache.destroy()}removeEntry(e){let s=this.createFileKey(e);this._cache.removeKey(s)}reconcile(){let{items:e}=this._cache;for(let s of e)this.getFileDescriptor(s.key).notFound&&this._cache.removeKey(s.key);this._cache.save()}hasFileChanged(e){let s=!1,i=this.getFileDescriptor(e);return(!i.err||!i.notFound)&&i.changed&&(s=!0),s}getFileDescriptor(e,s){this._logger?.debug({filePath:e,options:s},"Getting file descriptor");let i,t={key:this.createFileKey(e),changed:!1,meta:{}};this._logger?.trace({key:t.key},"Created file key");let r=this._cache.getKey(t.key);r?this._logger?.trace({metaCache:r},"Found cached meta"):this._logger?.trace("No cached meta found"),t.meta=r?{...r}:{};let a=this.getAbsolutePath(e);this._logger?.trace({absolutePath:a},"Resolved absolute path");let n=s?.useCheckSum??this._useCheckSum;this._logger?.debug({useCheckSum:n},"Using checksum setting");try{if(i=u.default.statSync(a),t.meta.size=i.size,t.meta.mtime=i.mtime.getTime(),this._logger?.trace({size:t.meta.size,mtime:t.meta.mtime},"Read file stats"),n){let h=u.default.readFileSync(a);t.meta.hash=this.getHash(h),this._logger?.trace({hash:t.meta.hash},"Calculated file hash")}}catch(h){this._logger?.error({filePath:e,error:h},"Error reading file"),this.removeEntry(e);let b=!1;return h.message.includes("ENOENT")&&(b=!0,this._logger?.debug({filePath:e},"File not found")),{key:t.key,err:h,notFound:b,meta:{}}}return r?(n===!1&&r?.mtime!==t.meta?.mtime&&(t.changed=!0,this._logger?.debug({filePath:e,oldMtime:r.mtime,newMtime:t.meta.mtime},"File changed: mtime differs")),r?.size!==t.meta?.size&&(t.changed=!0,this._logger?.debug({filePath:e,oldSize:r.size,newSize:t.meta.size},"File changed: size differs")),n&&r?.hash!==t.meta?.hash&&(t.changed=!0,this._logger?.debug({filePath:e,oldHash:r.hash,newHash:t.meta.hash},"File changed: hash differs")),this._cache.setKey(t.key,t.meta),t.changed?this._logger?.info({filePath:e},"File has changed"):this._logger?.debug({filePath:e},"File unchanged"),t):(t.changed=!0,this._cache.setKey(t.key,t.meta),this._logger?.debug({filePath:e},"File not in cache, marked as changed"),t)}normalizeEntries(e){let s=[];if(e){for(let t of e){let r=this.getFileDescriptor(t);s.push(r)}return s}let i=this.cache.keys();for(let t of i){let r=this.getFileDescriptor(t);!r.notFound&&!r.err&&s.push(r)}return s}analyzeFiles(e){let s={changedFiles:[],notFoundFiles:[],notChangedFiles:[]},i=this.normalizeEntries(e);for(let t of i)t.notFound?s.notFoundFiles.push(t.key):t.changed?s.changedFiles.push(t.key):s.notChangedFiles.push(t.key);return s}getUpdatedFiles(e){let s=[],i=this.normalizeEntries(e);for(let t of i)t.changed&&s.push(t.key);return s}getFileDescriptorsByPath(e){let s=[],i=this._cache.keys();for(let t of i)if(t.startsWith(e)){let r=this.getFileDescriptor(t);s.push(r)}return s}getAbsolutePath(e){if(this.isRelativePath(e)){let s=e.replace(/\0/g,""),i=c.default.resolve(this._cwd,s);if(this._strictPaths){let t=c.default.normalize(i),r=c.default.normalize(this._cwd);if(!(t===r||t.startsWith(r+c.default.sep)))throw new Error(`Path traversal attempt blocked: "${e}" resolves outside of working directory "${this._cwd}"`)}return i}return e}getAbsolutePathWithCwd(e,s){if(this.isRelativePath(e)){let i=e.replace(/\0/g,""),t=c.default.resolve(s,i);if(this._strictPaths){let r=c.default.normalize(t),a=c.default.normalize(s);if(!(r===a||r.startsWith(a+c.default.sep)))throw new Error(`Path traversal attempt blocked: "${e}" resolves outside of working directory "${s}"`)}return t}return e}renameCacheKeys(e,s){let i=this._cache.keys();for(let t of i)if(t.startsWith(e)){let r=t.replace(e,s),a=this._cache.getKey(t);this._cache.removeKey(t),this._cache.setKey(r,a)}}};0&&(module.exports={FileEntryCache,create,createFromFile});

package/dist/index.d.cts

@@ -1,6 +1,22 @@
 import { Buffer } from 'node:buffer';
 import { FlatCacheOptions, FlatCache } from 'flat-cache';
 
+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;
+};
 type FileEntryCacheOptions = {
     /** Whether to use file modified time for change detection (default: true) */
     useModifiedTime?: boolean;
@@ -12,6 +28,10 @@ type FileEntryCacheOptions = {
     cwd?: string;
     /** Restrict file access to within cwd boundaries (default: true) */
     strictPaths?: boolean;
+    /** Whether to use absolute path as cache key (default: false) */
+    useAbsolutePathAsKey?: boolean;
+    /** Logger instance for logging (default: undefined) */
+    logger?: ILogger;
     /** Options for the underlying flat cache */
     cache?: FlatCacheOptions;
 };
@@ -40,6 +60,8 @@ type FileDescriptorMeta = {
     hash?: string;
     /** Custom data associated with the file (e.g., lint results, metadata) */
     data?: unknown;
+    /** Allow any additional custom properties */
+    [key: string]: unknown;
 };
 type AnalyzedFiles = {
     /** Array of file paths that have changed since last cache */
@@ -52,20 +74,19 @@ type AnalyzedFiles = {
 /**
  * Create a new FileEntryCache instance from a file path
  * @param filePath - The path to the cache file
- * @param useCheckSum - Whether to use checksum to detect file changes (default: false)
- * @param cwd - The current working directory for resolving relative paths (default: process.cwd())
+ * @param options - create options such as useChecksum, cwd, and more
  * @returns A new FileEntryCache instance
  */
-declare function createFromFile(filePath: string, useCheckSum?: boolean, cwd?: string): FileEntryCache;
+declare function createFromFile(filePath: string, options?: CreateOptions): FileEntryCache;
+type CreateOptions = Omit<FileEntryCacheOptions, "cache">;
 /**
  * Create a new FileEntryCache instance
  * @param cacheId - The cache file name
  * @param cacheDirectory - The directory to store the cache file (default: undefined, cache won't be persisted)
- * @param useCheckSum - Whether to use checksum to detect file changes (default: false)
- * @param cwd - The current working directory for resolving relative paths (default: process.cwd())
+ * @param options - Whether to use checksum to detect file changes (default: false)
  * @returns A new FileEntryCache instance
  */
-declare function create(cacheId: string, cacheDirectory?: string, useCheckSum?: boolean, cwd?: string): FileEntryCache;
+declare function create(cacheId: string, cacheDirectory?: string, options?: CreateOptions): FileEntryCache;
 declare class FileEntryDefault {
     static create: typeof create;
     static createFromFile: typeof createFromFile;
@@ -76,6 +97,8 @@ declare class FileEntryCache {
     private _hashAlgorithm;
     private _cwd;
     private _strictPaths;
+    private _logger?;
+    private _useAbsolutePathAsKey;
     /**
      * Create a new FileEntryCache instance
      * @param options - The options for the FileEntryCache (all properties are optional with defaults)
@@ -91,6 +114,16 @@ declare class FileEntryCache {
      * @param {FlatCache} cache - The cache to set
      */
     set cache(cache: FlatCache);
+    /**
+     * Get the logger
+     * @returns {ILogger | undefined} The logger instance
+     */
+    get logger(): ILogger | undefined;
+    /**
+     * Set the logger
+     * @param {ILogger | undefined} logger - The logger to set
+     */
+    set logger(logger: ILogger | undefined);
     /**
      * 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)
@@ -131,6 +164,16 @@ declare class FileEntryCache {
      * @param {boolean} value - The value to set
      */
     set strictPaths(value: boolean);
+    /**
+     * Get whether to use absolute path as cache key
+     * @returns {boolean} Whether cache keys use absolute paths (default: false)
+     */
+    get useAbsolutePathAsKey(): boolean;
+    /**
+     * Set whether to use absolute path as cache key
+     * @param {boolean} value - The value to set
+     */
+    set useAbsolutePathAsKey(value: boolean);
     /**
      * Given a buffer, calculate md5 hash of its content.
      * @method getHash
@@ -245,4 +288,4 @@ declare class FileEntryCache {
     renameCacheKeys(oldPath: string, newPath: string): void;
 }
 
-export { type AnalyzedFiles, type FileDescriptor, type FileDescriptorMeta, FileEntryCache, type FileEntryCacheOptions, type GetFileDescriptorOptions, create, createFromFile, FileEntryDefault as default };
+export { type AnalyzedFiles, type CreateOptions, type FileDescriptor, type FileDescriptorMeta, FileEntryCache, type FileEntryCacheOptions, type GetFileDescriptorOptions, type ILogger, create, createFromFile, FileEntryDefault as default };

package/dist/index.d.ts

@@ -1,6 +1,22 @@
 import { Buffer } from 'node:buffer';
 import { FlatCacheOptions, FlatCache } from 'flat-cache';
 
+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;
+};
 type FileEntryCacheOptions = {
     /** Whether to use file modified time for change detection (default: true) */
     useModifiedTime?: boolean;
@@ -12,6 +28,10 @@ type FileEntryCacheOptions = {
     cwd?: string;
     /** Restrict file access to within cwd boundaries (default: true) */
     strictPaths?: boolean;
+    /** Whether to use absolute path as cache key (default: false) */
+    useAbsolutePathAsKey?: boolean;
+    /** Logger instance for logging (default: undefined) */
+    logger?: ILogger;
     /** Options for the underlying flat cache */
     cache?: FlatCacheOptions;
 };
@@ -40,6 +60,8 @@ type FileDescriptorMeta = {
     hash?: string;
     /** Custom data associated with the file (e.g., lint results, metadata) */
     data?: unknown;
+    /** Allow any additional custom properties */
+    [key: string]: unknown;
 };
 type AnalyzedFiles = {
     /** Array of file paths that have changed since last cache */
@@ -52,20 +74,19 @@ type AnalyzedFiles = {
 /**
  * Create a new FileEntryCache instance from a file path
  * @param filePath - The path to the cache file
- * @param useCheckSum - Whether to use checksum to detect file changes (default: false)
- * @param cwd - The current working directory for resolving relative paths (default: process.cwd())
+ * @param options - create options such as useChecksum, cwd, and more
  * @returns A new FileEntryCache instance
  */
-declare function createFromFile(filePath: string, useCheckSum?: boolean, cwd?: string): FileEntryCache;
+declare function createFromFile(filePath: string, options?: CreateOptions): FileEntryCache;
+type CreateOptions = Omit<FileEntryCacheOptions, "cache">;
 /**
  * Create a new FileEntryCache instance
  * @param cacheId - The cache file name
  * @param cacheDirectory - The directory to store the cache file (default: undefined, cache won't be persisted)
- * @param useCheckSum - Whether to use checksum to detect file changes (default: false)
- * @param cwd - The current working directory for resolving relative paths (default: process.cwd())
+ * @param options - Whether to use checksum to detect file changes (default: false)
  * @returns A new FileEntryCache instance
  */
-declare function create(cacheId: string, cacheDirectory?: string, useCheckSum?: boolean, cwd?: string): FileEntryCache;
+declare function create(cacheId: string, cacheDirectory?: string, options?: CreateOptions): FileEntryCache;
 declare class FileEntryDefault {
     static create: typeof create;
     static createFromFile: typeof createFromFile;
@@ -76,6 +97,8 @@ declare class FileEntryCache {
     private _hashAlgorithm;
     private _cwd;
     private _strictPaths;
+    private _logger?;
+    private _useAbsolutePathAsKey;
     /**
      * Create a new FileEntryCache instance
      * @param options - The options for the FileEntryCache (all properties are optional with defaults)
@@ -91,6 +114,16 @@ declare class FileEntryCache {
      * @param {FlatCache} cache - The cache to set
      */
     set cache(cache: FlatCache);
+    /**
+     * Get the logger
+     * @returns {ILogger | undefined} The logger instance
+     */
+    get logger(): ILogger | undefined;
+    /**
+     * Set the logger
+     * @param {ILogger | undefined} logger - The logger to set
+     */
+    set logger(logger: ILogger | undefined);
     /**
      * 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)
@@ -131,6 +164,16 @@ declare class FileEntryCache {
      * @param {boolean} value - The value to set
      */
     set strictPaths(value: boolean);
+    /**
+     * Get whether to use absolute path as cache key
+     * @returns {boolean} Whether cache keys use absolute paths (default: false)
+     */
+    get useAbsolutePathAsKey(): boolean;
+    /**
+     * Set whether to use absolute path as cache key
+     * @param {boolean} value - The value to set
+     */
+    set useAbsolutePathAsKey(value: boolean);
     /**
      * Given a buffer, calculate md5 hash of its content.
      * @method getHash
@@ -245,4 +288,4 @@ declare class FileEntryCache {
     renameCacheKeys(oldPath: string, newPath: string): void;
 }
 
-export { type AnalyzedFiles, type FileDescriptor, type FileDescriptorMeta, FileEntryCache, type FileEntryCacheOptions, type GetFileDescriptorOptions, create, createFromFile, FileEntryDefault as default };
+export { type AnalyzedFiles, type CreateOptions, type FileDescriptor, type FileDescriptorMeta, FileEntryCache, type FileEntryCacheOptions, type GetFileDescriptorOptions, type ILogger, create, createFromFile, FileEntryDefault as default };

package/dist/index.js

@@ -1,430 +1 @@
-// src/index.ts
-import crypto from "crypto";
-import fs from "fs";
-import path from "path";
-import {
-  createFromFile as createFlatCacheFile,
-  FlatCache
-} from "flat-cache";
-function createFromFile(filePath, useCheckSum, cwd) {
-  const fname = path.basename(filePath);
-  const directory = path.dirname(filePath);
-  return create(fname, directory, useCheckSum, cwd);
-}
-function create(cacheId, cacheDirectory, useCheckSum, cwd) {
-  const options = {
-    useCheckSum,
-    cwd,
-    cache: {
-      cacheId,
-      cacheDir: cacheDirectory
-    }
-  };
-  const fileEntryCache = new FileEntryCache(options);
-  if (cacheDirectory) {
-    const cachePath = `${cacheDirectory}/${cacheId}`;
-    if (fs.existsSync(cachePath)) {
-      fileEntryCache.cache = createFlatCacheFile(cachePath, options.cache);
-    }
-  }
-  return fileEntryCache;
-}
-var FileEntryDefault = class {
-  static create = create;
-  static createFromFile = createFromFile;
-};
-var FileEntryCache = class {
-  _cache = new FlatCache({ useClone: false });
-  _useCheckSum = false;
-  _hashAlgorithm = "md5";
-  _cwd = process.cwd();
-  _strictPaths = true;
-  /**
-   * Create a new FileEntryCache instance
-   * @param options - The options for the FileEntryCache (all properties are optional with defaults)
-   */
-  constructor(options) {
-    if (options?.cache) {
-      this._cache = new FlatCache(options.cache);
-    }
-    if (options?.useCheckSum) {
-      this._useCheckSum = options.useCheckSum;
-    }
-    if (options?.hashAlgorithm) {
-      this._hashAlgorithm = options.hashAlgorithm;
-    }
-    if (options?.cwd) {
-      this._cwd = options.cwd;
-    }
-    if (options?.strictPaths !== void 0) {
-      this._strictPaths = options.strictPaths;
-    }
-  }
-  /**
-   * Get the cache
-   * @returns {FlatCache} The cache
-   */
-  get cache() {
-    return this._cache;
-  }
-  /**
-   * Set the cache
-   * @param {FlatCache} cache - The cache to set
-   */
-  set cache(cache) {
-    this._cache = cache;
-  }
-  /**
-   * 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)
-   */
-  get useCheckSum() {
-    return this._useCheckSum;
-  }
-  /**
-   * Set the useCheckSum value
-   * @param {boolean} value - The value to set
-   */
-  set useCheckSum(value) {
-    this._useCheckSum = value;
-  }
-  /**
-   * Get the hash algorithm
-   * @returns {string} The hash algorithm (default: 'md5')
-   */
-  get hashAlgorithm() {
-    return this._hashAlgorithm;
-  }
-  /**
-   * Set the hash algorithm
-   * @param {string} value - The value to set
-   */
-  set hashAlgorithm(value) {
-    this._hashAlgorithm = value;
-  }
-  /**
-   * Get the current working directory
-   * @returns {string} The current working directory (default: process.cwd())
-   */
-  get cwd() {
-    return this._cwd;
-  }
-  /**
-   * Set the current working directory
-   * @param {string} value - The value to set
-   */
-  set cwd(value) {
-    this._cwd = value;
-  }
-  /**
-   * Get whether to restrict paths to cwd boundaries
-   * @returns {boolean} Whether strict path checking is enabled (default: true)
-   */
-  get strictPaths() {
-    return this._strictPaths;
-  }
-  /**
-   * Set whether to restrict paths to cwd boundaries
-   * @param {boolean} value - The value to set
-   */
-  set strictPaths(value) {
-    this._strictPaths = value;
-  }
-  /**
-   * Given a buffer, calculate md5 hash of its content.
-   * @method getHash
-   * @param  {Buffer} buffer   buffer to calculate hash on
-   * @return {String}          content hash digest
-   */
-  getHash(buffer) {
-    return crypto.createHash(this._hashAlgorithm).update(buffer).digest("hex");
-  }
-  /**
-   * Create the key for the file path used for caching.
-   * @method createFileKey
-   * @param {String} filePath
-   * @return {String}
-   */
-  createFileKey(filePath) {
-    return filePath;
-  }
-  /**
-   * Check if the file path is a relative path
-   * @method isRelativePath
-   * @param filePath - The file path to check
-   * @returns {boolean} if the file path is a relative path, false otherwise
-   */
-  isRelativePath(filePath) {
-    return !path.isAbsolute(filePath);
-  }
-  /**
-   * Delete the cache file from the disk
-   * @method deleteCacheFile
-   * @return {boolean}       true if the file was deleted, false otherwise
-   */
-  deleteCacheFile() {
-    return this._cache.removeCacheFile();
-  }
-  /**
-   * Remove the cache from the file and clear the memory cache
-   * @method destroy
-   */
-  destroy() {
-    this._cache.destroy();
-  }
-  /**
-   * Remove and Entry From the Cache
-   * @method removeEntry
-   * @param filePath - The file path to remove from the cache
-   */
-  removeEntry(filePath) {
-    const key = this.createFileKey(filePath);
-    this._cache.removeKey(key);
-  }
-  /**
-   * Reconcile the cache
-   * @method reconcile
-   */
-  reconcile() {
-    const { items } = this._cache;
-    for (const item of items) {
-      const fileDescriptor = this.getFileDescriptor(item.key);
-      if (fileDescriptor.notFound) {
-        this._cache.removeKey(item.key);
-      }
-    }
-    this._cache.save();
-  }
-  /**
-   * Check if the file has changed
-   * @method hasFileChanged
-   * @param filePath - The file path to check
-   * @returns {boolean} if the file has changed, false otherwise
-   */
-  hasFileChanged(filePath) {
-    let result = false;
-    const fileDescriptor = this.getFileDescriptor(filePath);
-    if ((!fileDescriptor.err || !fileDescriptor.notFound) && fileDescriptor.changed) {
-      result = true;
-    }
-    return result;
-  }
-  /**
-   * Get the file descriptor for the file path
-   * @method getFileDescriptor
-   * @param filePath - The file path to get the file descriptor for
-   * @param options - The options for getting the file descriptor
-   * @returns The file descriptor
-   */
-  getFileDescriptor(filePath, options) {
-    let fstat;
-    const result = {
-      key: this.createFileKey(filePath),
-      changed: false,
-      meta: {}
-    };
-    result.meta = this._cache.getKey(result.key) ?? {};
-    const absolutePath = this.getAbsolutePath(filePath);
-    const useCheckSumValue = options?.useCheckSum ?? this._useCheckSum;
-    try {
-      fstat = fs.statSync(absolutePath);
-      result.meta = {
-        size: fstat.size
-      };
-      result.meta.mtime = fstat.mtime.getTime();
-      if (useCheckSumValue) {
-        const buffer = fs.readFileSync(absolutePath);
-        result.meta.hash = this.getHash(buffer);
-      }
-    } catch (error) {
-      this.removeEntry(filePath);
-      let notFound = false;
-      if (error.message.includes("ENOENT")) {
-        notFound = true;
-      }
-      return {
-        key: result.key,
-        err: error,
-        notFound,
-        meta: {}
-      };
-    }
-    const metaCache = this._cache.getKey(result.key);
-    if (!metaCache) {
-      result.changed = true;
-      this._cache.setKey(result.key, result.meta);
-      return result;
-    }
-    if (result.meta.data === void 0) {
-      result.meta.data = metaCache.data;
-    }
-    if (useCheckSumValue === false && metaCache?.mtime !== result.meta?.mtime) {
-      result.changed = true;
-    }
-    if (metaCache?.size !== result.meta?.size) {
-      result.changed = true;
-    }
-    if (useCheckSumValue && metaCache?.hash !== result.meta?.hash) {
-      result.changed = true;
-    }
-    this._cache.setKey(result.key, result.meta);
-    return result;
-  }
-  /**
-   * Get the file descriptors for the files
-   * @method normalizeEntries
-   * @param files?: string[] - The files to get the file descriptors for
-   * @returns The file descriptors
-   */
-  normalizeEntries(files) {
-    const result = [];
-    if (files) {
-      for (const file of files) {
-        const fileDescriptor = this.getFileDescriptor(file);
-        result.push(fileDescriptor);
-      }
-      return result;
-    }
-    const keys = this.cache.keys();
-    for (const key of keys) {
-      const fileDescriptor = this.getFileDescriptor(key);
-      if (!fileDescriptor.notFound && !fileDescriptor.err) {
-        result.push(fileDescriptor);
-      }
-    }
-    return result;
-  }
-  /**
-   * Analyze the files
-   * @method analyzeFiles
-   * @param files - The files to analyze
-   * @returns {AnalyzedFiles} The analysis of the files
-   */
-  analyzeFiles(files) {
-    const result = {
-      changedFiles: [],
-      notFoundFiles: [],
-      notChangedFiles: []
-    };
-    const fileDescriptors = this.normalizeEntries(files);
-    for (const fileDescriptor of fileDescriptors) {
-      if (fileDescriptor.notFound) {
-        result.notFoundFiles.push(fileDescriptor.key);
-      } else if (fileDescriptor.changed) {
-        result.changedFiles.push(fileDescriptor.key);
-      } else {
-        result.notChangedFiles.push(fileDescriptor.key);
-      }
-    }
-    return result;
-  }
-  /**
-   * Get the updated files
-   * @method getUpdatedFiles
-   * @param files - The files to get the updated files for
-   * @returns {string[]} The updated files
-   */
-  getUpdatedFiles(files) {
-    const result = [];
-    const fileDescriptors = this.normalizeEntries(files);
-    for (const fileDescriptor of fileDescriptors) {
-      if (fileDescriptor.changed) {
-        result.push(fileDescriptor.key);
-      }
-    }
-    return result;
-  }
-  /**
-   * Get the file descriptors by path prefix
-   * @method getFileDescriptorsByPath
-   * @param filePath - the path prefix to match
-   * @returns {FileDescriptor[]} The file descriptors
-   */
-  getFileDescriptorsByPath(filePath) {
-    const result = [];
-    const keys = this._cache.keys();
-    for (const key of keys) {
-      if (key.startsWith(filePath)) {
-        const fileDescriptor = this.getFileDescriptor(key);
-        result.push(fileDescriptor);
-      }
-    }
-    return result;
-  }
-  /**
-   * Get the Absolute Path. If it is already absolute it will return the path as is.
-   * When strictPaths is enabled, ensures the resolved path stays within cwd boundaries.
-   * @method getAbsolutePath
-   * @param filePath - The file path to get the absolute path for
-   * @returns {string}
-   * @throws {Error} When strictPaths is true and path would resolve outside cwd
-   */
-  getAbsolutePath(filePath) {
-    if (this.isRelativePath(filePath)) {
-      const sanitizedPath = filePath.replace(/\0/g, "");
-      const resolved = path.resolve(this._cwd, sanitizedPath);
-      if (this._strictPaths) {
-        const normalizedResolved = path.normalize(resolved);
-        const normalizedCwd = path.normalize(this._cwd);
-        const isWithinCwd = normalizedResolved === normalizedCwd || normalizedResolved.startsWith(normalizedCwd + path.sep);
-        if (!isWithinCwd) {
-          throw new Error(
-            `Path traversal attempt blocked: "${filePath}" resolves outside of working directory "${this._cwd}"`
-          );
-        }
-      }
-      return resolved;
-    }
-    return filePath;
-  }
-  /**
-   * Get the Absolute Path with a custom working directory. If it is already absolute it will return the path as is.
-   * When strictPaths is enabled, ensures the resolved path stays within the provided cwd boundaries.
-   * @method getAbsolutePathWithCwd
-   * @param filePath - The file path to get the absolute path for
-   * @param cwd - The custom working directory to resolve relative paths from
-   * @returns {string}
-   * @throws {Error} When strictPaths is true and path would resolve outside the provided cwd
-   */
-  getAbsolutePathWithCwd(filePath, cwd) {
-    if (this.isRelativePath(filePath)) {
-      const sanitizedPath = filePath.replace(/\0/g, "");
-      const resolved = path.resolve(cwd, sanitizedPath);
-      if (this._strictPaths) {
-        const normalizedResolved = path.normalize(resolved);
-        const normalizedCwd = path.normalize(cwd);
-        const isWithinCwd = normalizedResolved === normalizedCwd || normalizedResolved.startsWith(normalizedCwd + path.sep);
-        if (!isWithinCwd) {
-          throw new Error(
-            `Path traversal attempt blocked: "${filePath}" resolves outside of working directory "${cwd}"`
-          );
-        }
-      }
-      return resolved;
-    }
-    return filePath;
-  }
-  /**
-   * Rename cache keys that start with a given path prefix.
-   * @method renameCacheKeys
-   * @param oldPath - The old path prefix to rename
-   * @param newPath - The new path prefix to rename to
-   */
-  renameCacheKeys(oldPath, newPath) {
-    const keys = this._cache.keys();
-    for (const key of keys) {
-      if (key.startsWith(oldPath)) {
-        const newKey = key.replace(oldPath, newPath);
-        const meta = this._cache.getKey(key);
-        this._cache.removeKey(key);
-        this._cache.setKey(newKey, meta);
-      }
-    }
-  }
-};
-export {
-  FileEntryCache,
-  create,
-  createFromFile,
-  FileEntryDefault as default
-};
+import f from"crypto";import l from"fs";import o from"path";import{createFromFile as b,FlatCache as m}from"flat-cache";function y(a,e){let s=o.basename(a),r=o.dirname(a);return p(s,r,e)}function p(a,e,s){let r={...s,cache:{cacheId:a,cacheDir:e}},t=new u(r);if(e){let i=`${e}/${a}`;l.existsSync(i)&&(t.cache=b(i,r.cache))}return t}var g=class{static create=p;static createFromFile=y},u=class{_cache=new m({useClone:!1});_useCheckSum=!1;_hashAlgorithm="md5";_cwd=process.cwd();_strictPaths=!1;_logger;_useAbsolutePathAsKey=!1;constructor(e){e?.cache&&(this._cache=new m(e.cache)),e?.useCheckSum&&(this._useCheckSum=e.useCheckSum),e?.hashAlgorithm&&(this._hashAlgorithm=e.hashAlgorithm),e?.cwd&&(this._cwd=e.cwd),e?.strictPaths!==void 0&&(this._strictPaths=e.strictPaths),e?.useAbsolutePathAsKey!==void 0&&(this._useAbsolutePathAsKey=e.useAbsolutePathAsKey),e?.logger&&(this._logger=e.logger)}get cache(){return this._cache}set cache(e){this._cache=e}get logger(){return this._logger}set logger(e){this._logger=e}get useCheckSum(){return this._useCheckSum}set useCheckSum(e){this._useCheckSum=e}get hashAlgorithm(){return this._hashAlgorithm}set hashAlgorithm(e){this._hashAlgorithm=e}get cwd(){return this._cwd}set cwd(e){this._cwd=e}get strictPaths(){return this._strictPaths}set strictPaths(e){this._strictPaths=e}get useAbsolutePathAsKey(){return this._useAbsolutePathAsKey}set useAbsolutePathAsKey(e){this._useAbsolutePathAsKey=e}getHash(e){return f.createHash(this._hashAlgorithm).update(e).digest("hex")}createFileKey(e){let s=e;return this._useAbsolutePathAsKey&&this.isRelativePath(e)&&(s=this.getAbsolutePathWithCwd(e,this._cwd)),s}isRelativePath(e){return!o.isAbsolute(e)}deleteCacheFile(){return this._cache.removeCacheFile()}destroy(){this._cache.destroy()}removeEntry(e){let s=this.createFileKey(e);this._cache.removeKey(s)}reconcile(){let{items:e}=this._cache;for(let s of e)this.getFileDescriptor(s.key).notFound&&this._cache.removeKey(s.key);this._cache.save()}hasFileChanged(e){let s=!1,r=this.getFileDescriptor(e);return(!r.err||!r.notFound)&&r.changed&&(s=!0),s}getFileDescriptor(e,s){this._logger?.debug({filePath:e,options:s},"Getting file descriptor");let r,t={key:this.createFileKey(e),changed:!1,meta:{}};this._logger?.trace({key:t.key},"Created file key");let i=this._cache.getKey(t.key);i?this._logger?.trace({metaCache:i},"Found cached meta"):this._logger?.trace("No cached meta found"),t.meta=i?{...i}:{};let c=this.getAbsolutePath(e);this._logger?.trace({absolutePath:c},"Resolved absolute path");let n=s?.useCheckSum??this._useCheckSum;this._logger?.debug({useCheckSum:n},"Using checksum setting");try{if(r=l.statSync(c),t.meta.size=r.size,t.meta.mtime=r.mtime.getTime(),this._logger?.trace({size:t.meta.size,mtime:t.meta.mtime},"Read file stats"),n){let h=l.readFileSync(c);t.meta.hash=this.getHash(h),this._logger?.trace({hash:t.meta.hash},"Calculated file hash")}}catch(h){this._logger?.error({filePath:e,error:h},"Error reading file"),this.removeEntry(e);let d=!1;return h.message.includes("ENOENT")&&(d=!0,this._logger?.debug({filePath:e},"File not found")),{key:t.key,err:h,notFound:d,meta:{}}}return i?(n===!1&&i?.mtime!==t.meta?.mtime&&(t.changed=!0,this._logger?.debug({filePath:e,oldMtime:i.mtime,newMtime:t.meta.mtime},"File changed: mtime differs")),i?.size!==t.meta?.size&&(t.changed=!0,this._logger?.debug({filePath:e,oldSize:i.size,newSize:t.meta.size},"File changed: size differs")),n&&i?.hash!==t.meta?.hash&&(t.changed=!0,this._logger?.debug({filePath:e,oldHash:i.hash,newHash:t.meta.hash},"File changed: hash differs")),this._cache.setKey(t.key,t.meta),t.changed?this._logger?.info({filePath:e},"File has changed"):this._logger?.debug({filePath:e},"File unchanged"),t):(t.changed=!0,this._cache.setKey(t.key,t.meta),this._logger?.debug({filePath:e},"File not in cache, marked as changed"),t)}normalizeEntries(e){let s=[];if(e){for(let t of e){let i=this.getFileDescriptor(t);s.push(i)}return s}let r=this.cache.keys();for(let t of r){let i=this.getFileDescriptor(t);!i.notFound&&!i.err&&s.push(i)}return s}analyzeFiles(e){let s={changedFiles:[],notFoundFiles:[],notChangedFiles:[]},r=this.normalizeEntries(e);for(let t of r)t.notFound?s.notFoundFiles.push(t.key):t.changed?s.changedFiles.push(t.key):s.notChangedFiles.push(t.key);return s}getUpdatedFiles(e){let s=[],r=this.normalizeEntries(e);for(let t of r)t.changed&&s.push(t.key);return s}getFileDescriptorsByPath(e){let s=[],r=this._cache.keys();for(let t of r)if(t.startsWith(e)){let i=this.getFileDescriptor(t);s.push(i)}return s}getAbsolutePath(e){if(this.isRelativePath(e)){let s=e.replace(/\0/g,""),r=o.resolve(this._cwd,s);if(this._strictPaths){let t=o.normalize(r),i=o.normalize(this._cwd);if(!(t===i||t.startsWith(i+o.sep)))throw new Error(`Path traversal attempt blocked: "${e}" resolves outside of working directory "${this._cwd}"`)}return r}return e}getAbsolutePathWithCwd(e,s){if(this.isRelativePath(e)){let r=e.replace(/\0/g,""),t=o.resolve(s,r);if(this._strictPaths){let i=o.normalize(t),c=o.normalize(s);if(!(i===c||i.startsWith(c+o.sep)))throw new Error(`Path traversal attempt blocked: "${e}" resolves outside of working directory "${s}"`)}return t}return e}renameCacheKeys(e,s){let r=this._cache.keys();for(let t of r)if(t.startsWith(e)){let i=t.replace(e,s),c=this._cache.getKey(t);this._cache.removeKey(t),this._cache.setKey(i,c)}}};export{u as FileEntryCache,p as create,y as createFromFile,g as default};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "file-entry-cache",
-  "version": "11.0.0-beta.3",
+  "version": "11.0.0-beta.5",
   "description": "A lightweight cache for file metadata, ideal for processes that work on a specific set of files and only need to reprocess files that have changed since the last run",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -30,8 +30,9 @@
   ],
   "devDependencies": {
     "@biomejs/biome": "^2.2.5",
-    "@types/node": "^24.6.2",
+    "@types/node": "^24.7.1",
     "@vitest/coverage-v8": "^3.2.4",
+    "pino": "^10.0.0",
     "rimraf": "^6.0.1",
     "tsup": "^8.5.0",
     "typescript": "^5.9.3",
@@ -45,7 +46,7 @@
     "license"
   ],
   "scripts": {
-    "build": "rimraf ./dist && tsup src/index.ts --format cjs,esm --dts --clean",
+    "build": "rimraf ./dist && tsup src/index.ts --format cjs,esm --dts --clean --minify",
     "prepublish": "pnpm build",
     "lint": "biome check --write --error-on-warnings",
     "test": "pnpm lint && vitest run --coverage",