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

package/README.md

@@ -72,6 +72,23 @@ fileDescriptor = cache.getFileDescriptor('./src/file.txt');
 console.log(fileDescriptor.changed); // true
 ```
 
+Using `create()` with options for more control:
+```javascript
+import fileEntryCache from 'file-entry-cache';
+
+// Create cache with options
+const cache = fileEntryCache.create('myCache', './.cache', {
+  useCheckSum: true,              // Use checksums for more reliable change detection
+  cwd: '/path/to/project',        // Custom working directory
+  restrictAccessToCwd: false,     // Allow access outside cwd (use with caution)
+  useAbsolutePathAsKey: false     // Store relative paths in cache
+});
+
+let fileDescriptor = cache.getFileDescriptor('./src/file.txt');
+console.log(fileDescriptor.changed); // true
+console.log(fileDescriptor.meta.hash); // checksum hash
+```
+
 Save it to Disk and Reconcile files that are no longer found
 ```javascript
 import fileEntryCache from 'file-entry-cache';
@@ -85,20 +102,80 @@ Load the cache from a file:
 
 ```javascript
 import fileEntryCache from 'file-entry-cache';
+
+// Basic usage
 const cache = fileEntryCache.createFromFile('/path/to/cache/file');
 let fileDescriptor = cache.getFileDescriptor('./src/file.txt');
 console.log(fileDescriptor.changed); // false as it has not changed from the saved cache.
+
+// With options
+const cache2 = fileEntryCache.createFromFile('/path/to/cache/file', {
+  useCheckSum: true,
+  cwd: '/path/to/project'
+});
 ```
 
 
 # Changes from v10 to v11
 
 **BREAKING CHANGES:**
-- **`strictPaths` now defaults to `true`** - Path traversal protection is enabled by default for security. To restore v10 behavior, explicitly set `strictPaths: false`
+
+- **`create()` and `createFromFile()` now use `CreateOptions` object** - The function signatures have changed to accept an options object instead of individual parameters for better extensibility and clarity.
+
+  **Old API (v10):**
+  ```javascript
+  // v10 - positional parameters
+  const cache = fileEntryCache.create(cacheId, cacheDirectory, useCheckSum, cwd);
+  const cache2 = fileEntryCache.createFromFile(filePath, useCheckSum, cwd);
+  ```
+
+  **New API (v11):**
+  ```javascript
+  // v11 - options object
+  const cache = fileEntryCache.create(cacheId, cacheDirectory, {
+    useCheckSum: true,
+    cwd: '/path/to/project',
+    restrictAccessToCwd: false
+  });
+
+  const cache2 = fileEntryCache.createFromFile(filePath, {
+    useCheckSum: true,
+    cwd: '/path/to/project',
+    restrictAccessToCwd: false
+  });
+  ```
+
+- **Renamed `strictPaths` to `restrictAccessToCwd`** - For better clarity and self-documentation, the option that restricts file access to the current working directory has been renamed.
+
+  **Migration:**
+  ```javascript
+  // Old
+  const cache = new FileEntryCache({ strictPaths: true });
+  cache.strictPaths = false;
+
+  // New
+  const cache = new FileEntryCache({ restrictAccessToCwd: true });
+  cache.restrictAccessToCwd = false;
+  ```
+
+- **Renamed `currentWorkingDirectory` to `cwd`** - For consistency with common conventions and brevity, the property has been renamed to `cwd`.
+
+  **Migration:**
+  ```javascript
+  // Old
+  const cache = new FileEntryCache({ currentWorkingDirectory: '/path/to/project' });
+  cache.currentWorkingDirectory = '/new/path';
+
+  // New
+  const cache = new FileEntryCache({ cwd: '/path/to/project' });
+  cache.cwd = '/new/path';
+  ```
 
 **NEW FEATURES:**
 - **Added `cwd` option** - You can now specify a custom current working directory for resolving relative paths
-- **Added `strictPaths` option** - Provides protection against path traversal attacks (enabled by default)
+- **Added `restrictAccessToCwd` option** - Provides protection against path traversal attacks (disabled by default for backwards compatibility)
+- **Added `useAbsolutePathAsKey` option** - When `true`, cache keys use absolute paths instead of the provided paths. Default is `false` for better cache portability with relative paths
+- **Added `logger` option** - Support for Pino-compatible logger instances to enable debugging and monitoring of cache operations. See [Logger Support](#logger-support) section for details
 - **Improved cache portability** - When using relative paths with the same `cwd`, cache files are portable across different environments
 
 # Changes from v9 to v10
@@ -114,15 +191,24 @@ There have been many features added and changes made to the `file-entry-cache` c
 - On `FileEntryDescriptor.meta` if using typescript you need to use the `meta.data` to set additional information. This is to allow for better type checking and to avoid conflicts with the `meta` object which was `any`.
 
 # Global Default Functions
-- `create(cacheId: string, cacheDirectory?: string, useCheckSum?: boolean, cwd?: string)` - Creates a new instance of the `FileEntryCache` class
-- `createFromFile(cachePath: string, useCheckSum?: boolean, cwd?: string)` - Creates a new instance of the `FileEntryCache` class and loads the cache from a file.
+- `create(cacheId: string, cacheDirectory?: string, options?: CreateOptions)` - Creates a new instance of the `FileEntryCache` class
+- `createFromFile(filePath: string, options?: CreateOptions)` - Creates a new instance of the `FileEntryCache` class and loads the cache from a file.
+
+## CreateOptions Type
+All options from `FileEntryCacheOptions` except `cache`:
+- `useCheckSum?` - If `true` it will use a checksum to determine if the file has changed. Default is `false`
+- `hashAlgorithm?` - The algorithm to use for the checksum. Default is `md5`
+- `cwd?` - The current working directory for resolving relative paths. Default is `process.cwd()`
+- `restrictAccessToCwd?` - If `true` restricts file access to within `cwd` boundaries. Default is `false`
+- `useAbsolutePathAsKey?` - If `true` uses absolute paths as cache keys. Default is `false`
+- `logger?` - A logger instance for debugging. Default is `undefined`
 
 # FileEntryCache Options (FileEntryCacheOptions)
 - `useModifiedTime?` - If `true` it will use the modified time to determine if the file has changed. Default is `true`
 - `useCheckSum?` - If `true` it will use a checksum to determine if the file has changed. Default is `false`
 - `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`
+- `restrictAccessToCwd?` - 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
@@ -141,9 +227,10 @@ There have been many features added and changes made to the `file-entry-cache` c
 - `hashAlgorithm: string` - The algorithm to use for the checksum. Default is `md5` but can be any algorithm supported by `crypto.createHash`
 - `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`
+- `restrictAccessToCwd: boolean` - If `true` restricts file access to within `cwd` boundaries. Default is `true`
+- `useAbsolutePathAsKey: boolean` - If `true` uses absolute paths as cache keys. Default is `false` to maintain better cache portability
 - `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).
+- `createFileKey(filePath: string): string` - Returns the cache key for the file path (returns the path exactly as provided when `useAbsolutePathAsKey` is `false`, otherwise returns the absolute path).
 - `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.
 - `removeEntry(filePath: string): void` - Removes an entry from the cache.
@@ -154,8 +241,8 @@ There have been many features added and changes made to the `file-entry-cache` c
 - `analyzeFiles(files: string[])` will return `AnalyzedFiles` object with `changedFiles`, `notFoundFiles`, and `notChangedFiles` as FileDescriptor arrays.
 - `getUpdatedFiles(files: string[])` will return an array of `FileEntryDescriptor` objects that have changed.
 - `getFileDescriptorsByPath(filePath: string): FileEntryDescriptor[]` will return an array of `FileEntryDescriptor` objects that starts with the path prefix specified.
-- `getAbsolutePath(filePath: string): string` - Resolves a relative path to absolute using the configured `cwd`. Returns absolute paths unchanged. When `strictPaths` is enabled, throws an error if the path resolves outside `cwd`.
-- `getAbsolutePathWithCwd(filePath: string, cwd: string): string` - Resolves a relative path to absolute using a custom working directory. When `strictPaths` is enabled, throws an error if the path resolves outside the provided `cwd`.
+- `getAbsolutePath(filePath: string): string` - Resolves a relative path to absolute using the configured `cwd`. Returns absolute paths unchanged. When `restrictAccessToCwd` is enabled, throws an error if the path resolves outside `cwd`.
+- `getAbsolutePathWithCwd(filePath: string, cwd: string): string` - Resolves a relative path to absolute using a custom working directory. When `restrictAccessToCwd` is enabled, throws an error if the path resolves outside the provided `cwd`.
 
 # Get File Descriptor
 
@@ -175,9 +262,12 @@ The cache stores paths exactly as they are provided (relative or absolute). When
 // Default: uses process.cwd()
 const cache1 = fileEntryCache.create('cache1');
 
-// Custom working directory
-const cache2 = fileEntryCache.create('cache2', './cache', false, '/project/root');
-// Or with options object
+// Custom working directory using options object
+const cache2 = fileEntryCache.create('cache2', './cache', {
+  cwd: '/project/root'
+});
+
+// Or using the class constructor directly
 const cache3 = new FileEntryCache({ cwd: '/project/root' });
 
 // The cache key is always the provided path
@@ -192,12 +282,16 @@ Using relative paths with a consistent `cwd` (defaults to `process.cwd()`) makes
 
 ```javascript
 // On machine A (project at /home/user/project)
-const cacheA = fileEntryCache.create('build-cache', './cache', false, '/home/user/project');
+const cacheA = fileEntryCache.create('build-cache', './cache', {
+  cwd: '/home/user/project'
+});
 cacheA.getFileDescriptor('./src/index.js'); // Resolves to /home/user/project/src/index.js
 cacheA.reconcile();
 
 // On machine B (project at /workspace/project)
-const cacheB = fileEntryCache.create('build-cache', './cache', false, '/workspace/project');
+const cacheB = fileEntryCache.create('build-cache', './cache', {
+  cwd: '/workspace/project'
+});
 cacheB.getFileDescriptor('./src/index.js'); // Resolves to /workspace/project/src/index.js
 // Cache hit! File hasn't changed since machine A
 ```
@@ -208,11 +302,9 @@ For maximum cache portability across different environments, use checksums (`use
 
 ```javascript
 // Development machine
-const devCache = fileEntryCache.create(
-    '.buildcache',
-    './cache',                 // cache directory
-    true                      // Use checksums for content-based comparison
-);
+const devCache = fileEntryCache.create('.buildcache', './cache', {
+  useCheckSum: true  // Use checksums for content-based comparison
+});
 
 // Process files using relative paths
 const descriptor = devCache.getFileDescriptor('./src/index.js');
@@ -223,12 +315,10 @@ if (descriptor.changed) {
 devCache.reconcile(); // Save cache
 
 // CI/CD Pipeline or another developer's machine
-const ciCache = fileEntryCache.create(
-    '.buildcache',
-    './node_modules/.cache',
-    true,                      // Same checksum setting
-    process.cwd()              // Different absolute path, same relative structure
-);
+const ciCache = fileEntryCache.create('.buildcache', './node_modules/.cache', {
+  useCheckSum: true,      // Same checksum setting
+  cwd: process.cwd()      // Different absolute path, same relative structure
+});
 
 // Same relative path works across environments
 const descriptor2 = ciCache.getFileDescriptor('./src/index.js');
@@ -244,12 +334,18 @@ Cache remains valid even when projects are moved or renamed:
 
 ```javascript
 // Original location: /projects/my-app
-const cache1 = fileEntryCache.create('.cache', './cache', true, '/projects/my-app');
+const cache1 = fileEntryCache.create('.cache', './cache', {
+  useCheckSum: true,
+  cwd: '/projects/my-app'
+});
 cache1.getFileDescriptor('./src/app.js');
 cache1.reconcile();
 
 // After moving project to: /archived/2024/my-app
-const cache2 = fileEntryCache.create('.cache', './cache', true, '/archived/2024/my-app');
+const cache2 = fileEntryCache.create('.cache', './cache', {
+  useCheckSum: true,
+  cwd: '/archived/2024/my-app'
+});
 cache2.getFileDescriptor('./src/app.js'); // Still finds cached entry!
 // Cache valid as long as relative structure unchanged
 ```
@@ -270,12 +366,12 @@ if (fileDescriptor.notFound) {
 
 # Path Security and Traversal Prevention
 
-The `strictPaths` option provides security against path traversal attacks by restricting file access to within the configured `cwd` boundaries. **This is enabled by default (since v11)** to ensure secure defaults when processing untrusted input or when running in security-sensitive environments.
+The `restrictAccessToCwd` option provides security against path traversal attacks by restricting file access to within the configured `cwd` boundaries. **This is enabled by default (since v11)** to ensure secure defaults when processing untrusted input or when running in security-sensitive environments.
 
 ## Basic Usage
 
 ```javascript
-// strictPaths is enabled by default for security
+// restrictAccessToCwd is enabled by default for security
 const cache = new FileEntryCache({
     cwd: '/project/root'
 });
@@ -293,13 +389,13 @@ try {
 // To allow parent directory access (not recommended for untrusted input)
 const unsafeCache = new FileEntryCache({
     cwd: '/project/root',
-    strictPaths: false  // Explicitly disable protection
+    restrictAccessToCwd: false  // Explicitly disable protection
 });
 ```
 
 ## Security Features
 
-When `strictPaths` is enabled:
+When `restrictAccessToCwd` is enabled:
 - **Path Traversal Prevention**: Blocks attempts to access files outside the working directory using `../` sequences
 - **Null Byte Protection**: Automatically removes null bytes from paths to prevent injection attacks
 - **Path Normalization**: Cleans and normalizes paths to prevent bypass attempts
@@ -309,15 +405,11 @@ When `strictPaths` is enabled:
 ### Build Tools with Untrusted Input
 ```javascript
 // Secure build tool configuration
-const cache = fileEntryCache.create(
-    '.buildcache',
-    './cache',
-    true,  // useCheckSum
-    process.cwd()
-);
-
-// Enable strict path checking for security
-cache.strictPaths = true;
+const cache = fileEntryCache.create('.buildcache', './cache', {
+  useCheckSum: true,
+  cwd: process.cwd(),
+  restrictAccessToCwd: true  // Enable strict path checking for security
+});
 
 // Process user-provided file paths safely
 function processUserFile(userProvidedPath) {
@@ -340,7 +432,7 @@ function processUserFile(userProvidedPath) {
 // Strict security for CI/CD pipelines
 const cache = new FileEntryCache({
     cwd: process.env.GITHUB_WORKSPACE || process.cwd(),
-    strictPaths: true,  // Prevent access outside workspace
+    restrictAccessToCwd: true,  // Prevent access outside workspace
     useCheckSum: true   // Content-based validation
 });
 
@@ -355,20 +447,20 @@ cache.getFileDescriptor('../../../root'); // ✗ Blocked (path traversal)
 const cache = new FileEntryCache({ cwd: '/safe/directory' });
 
 // Start with relaxed mode for trusted operations
-cache.strictPaths = false;
+cache.restrictAccessToCwd = false;
 processInternalFiles();
 
 // Enable strict mode for untrusted input
-cache.strictPaths = true;
+cache.restrictAccessToCwd = true;
 processUserUploadedPaths();
 
 // Return to relaxed mode if needed
-cache.strictPaths = false;
+cache.restrictAccessToCwd = false;
 ```
 
 ## Default Behavior
 
-**As of v11, `strictPaths` is enabled by default** to provide secure defaults. This means:
+**As of v11, `restrictAccessToCwd` is enabled by default** to provide secure defaults. This means:
 - Path traversal attempts using `../` are blocked
 - File access is restricted to within the configured `cwd`
 - Null bytes in paths are automatically sanitized
@@ -380,11 +472,11 @@ If you're upgrading from v10 or earlier and need to maintain the previous behavi
 ```javascript
 const cache = new FileEntryCache({
     cwd: process.cwd(),
-    strictPaths: false  // Restore v10 behavior
+    restrictAccessToCwd: false  // Restore v10 behavior
 });
 ```
 
-However, we strongly recommend keeping `strictPaths: true` and adjusting your code to work within the security boundaries, especially when processing any untrusted input.
+However, we strongly recommend keeping `restrictAccessToCwd: true` and adjusting your code to work within the security boundaries, especially when processing any untrusted input.
 
 # Using Checksums to Determine if a File has Changed (useCheckSum)
 

package/dist/index.cjs

@@ -1 +1 @@
-"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});
+"use strict";var k=Object.create;var u=Object.defineProperty;var w=Object.getOwnPropertyDescriptor;var A=Object.getOwnPropertyNames;var v=Object.getPrototypeOf,z=Object.prototype.hasOwnProperty;var D=(o,e)=>{for(var s in e)u(o,s,{get:e[s],enumerable:!0})},F=(o,e,s,i)=>{if(e&&typeof e=="object"||typeof e=="function")for(let t of A(e))!z.call(o,t)&&t!==s&&u(o,t,{get:()=>e[t],enumerable:!(i=w(e,t))||i.enumerable});return o};var p=(o,e,s)=>(s=o!=null?k(v(o)):{},F(e||!o||!o.__esModule?u(s,"default",{value:o,enumerable:!0}):s,o)),T=o=>F(u({},"__esModule",{value:!0}),o);var K={};D(K,{FileEntryCache:()=>m,create:()=>f,createFromFile:()=>C,default:()=>d});module.exports=T(K);var _=p(require("crypto"),1),g=p(require("fs"),1),c=p(require("path"),1),h=require("flat-cache");function C(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}`;g.default.existsSync(r)&&(t.cache=(0,h.createFromFile)(r,i.cache))}return t}var d=class{static create=f;static createFromFile=C},m=class{_cache=new h.FlatCache({useClone:!1});_useCheckSum=!1;_hashAlgorithm="md5";_cwd=process.cwd();_restrictAccessToCwd=!1;_logger;_useAbsolutePathAsKey=!1;_useModifiedTime=!0;constructor(e){e?.cache&&(this._cache=new h.FlatCache(e.cache)),e?.useCheckSum&&(this._useCheckSum=e.useCheckSum),e?.hashAlgorithm&&(this._hashAlgorithm=e.hashAlgorithm),e?.cwd&&(this._cwd=e.cwd),e?.useModifiedTime!==void 0&&(this._useModifiedTime=e.useModifiedTime),e?.restrictAccessToCwd!==void 0&&(this._restrictAccessToCwd=e.restrictAccessToCwd),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 useModifiedTime(){return this._useModifiedTime}set useModifiedTime(e){this._useModifiedTime=e}get restrictAccessToCwd(){return this._restrictAccessToCwd}set restrictAccessToCwd(e){this._restrictAccessToCwd=e}get useAbsolutePathAsKey(){return this._useAbsolutePathAsKey}set useAbsolutePathAsKey(e){this._useAbsolutePathAsKey=e}getHash(e){return _.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 n=this.getAbsolutePath(e);this._logger?.trace({absolutePath:n},"Resolved absolute path");let l=s?.useCheckSum??this._useCheckSum;this._logger?.debug({useCheckSum:l},"Using checksum setting");let b=s?.useModifiedTime??this.useModifiedTime;this._logger?.debug({useModifiedTime:b},"Using modified time (mtime) setting");try{if(i=g.default.statSync(n),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"),l){let a=g.default.readFileSync(n);t.meta.hash=this.getHash(a),this._logger?.trace({hash:t.meta.hash},"Calculated file hash")}}catch(a){this._logger?.error({filePath:e,error:a},"Error reading file"),this.removeEntry(e);let y=!1;return a.message.includes("ENOENT")&&(y=!0,this._logger?.debug({filePath:e},"File not found")),{key:t.key,err:a,notFound:y,meta:{}}}return r?(b&&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")),l&&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._restrictAccessToCwd){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._restrictAccessToCwd){let r=c.default.normalize(t),n=c.default.normalize(s);if(!(r===n||r.startsWith(n+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),n=this._cache.getKey(t);this._cache.removeKey(t),this._cache.setKey(r,n)}}};0&&(module.exports={FileEntryCache,create,createFromFile});

package/dist/index.d.cts

@@ -27,7 +27,7 @@ type FileEntryCacheOptions = {
     /** Current working directory for resolving relative paths (default: process.cwd()) */
     cwd?: string;
     /** Restrict file access to within cwd boundaries (default: true) */
-    strictPaths?: boolean;
+    restrictAccessToCwd?: boolean;
     /** Whether to use absolute path as cache key (default: false) */
     useAbsolutePathAsKey?: boolean;
     /** Logger instance for logging (default: undefined) */
@@ -38,6 +38,8 @@ type FileEntryCacheOptions = {
 type GetFileDescriptorOptions = {
     /** Whether to use checksum for this specific file check instead of modified time (mtime) (overrides instance setting) */
     useCheckSum?: boolean;
+    /** Whether to use file modified time for change detection (default: true) */
+    useModifiedTime?: boolean;
 };
 type FileDescriptor = {
     /** The cache key for this file (typically the file path) */
@@ -96,9 +98,10 @@ declare class FileEntryCache {
     private _useCheckSum;
     private _hashAlgorithm;
     private _cwd;
-    private _strictPaths;
+    private _restrictAccessToCwd;
     private _logger?;
     private _useAbsolutePathAsKey;
+    private _useModifiedTime;
     /**
      * Create a new FileEntryCache instance
      * @param options - The options for the FileEntryCache (all properties are optional with defaults)
@@ -154,16 +157,26 @@ declare class FileEntryCache {
      * @param {string} value - The value to set
      */
     set cwd(value: string);
+    /**
+     * Get whether to use modified time for change detection
+     * @returns {boolean} Whether modified time (mtime) is used for change detection (default: true)
+     */
+    get useModifiedTime(): boolean;
+    /**
+     * Set whether to use modified time for change detection
+     * @param {boolean} value - The value to set
+     */
+    set useModifiedTime(value: boolean);
     /**
      * Get whether to restrict paths to cwd boundaries
      * @returns {boolean} Whether strict path checking is enabled (default: true)
      */
-    get strictPaths(): boolean;
+    get restrictAccessToCwd(): boolean;
     /**
      * Set whether to restrict paths to cwd boundaries
      * @param {boolean} value - The value to set
      */
-    set strictPaths(value: boolean);
+    set restrictAccessToCwd(value: boolean);
     /**
      * Get whether to use absolute path as cache key
      * @returns {boolean} Whether cache keys use absolute paths (default: false)
@@ -262,21 +275,21 @@ declare class FileEntryCache {
     getFileDescriptorsByPath(filePath: string): FileDescriptor[];
     /**
      * 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.
+     * When restrictAccessToCwd 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
+     * @throws {Error} When restrictAccessToCwd is true and path would resolve outside cwd
      */
     getAbsolutePath(filePath: string): string;
     /**
      * 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.
+     * When restrictAccessToCwd 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
+     * @throws {Error} When restrictAccessToCwd is true and path would resolve outside the provided cwd
      */
     getAbsolutePathWithCwd(filePath: string, cwd: string): string;
     /**

package/dist/index.d.ts

@@ -27,7 +27,7 @@ type FileEntryCacheOptions = {
     /** Current working directory for resolving relative paths (default: process.cwd()) */
     cwd?: string;
     /** Restrict file access to within cwd boundaries (default: true) */
-    strictPaths?: boolean;
+    restrictAccessToCwd?: boolean;
     /** Whether to use absolute path as cache key (default: false) */
     useAbsolutePathAsKey?: boolean;
     /** Logger instance for logging (default: undefined) */
@@ -38,6 +38,8 @@ type FileEntryCacheOptions = {
 type GetFileDescriptorOptions = {
     /** Whether to use checksum for this specific file check instead of modified time (mtime) (overrides instance setting) */
     useCheckSum?: boolean;
+    /** Whether to use file modified time for change detection (default: true) */
+    useModifiedTime?: boolean;
 };
 type FileDescriptor = {
     /** The cache key for this file (typically the file path) */
@@ -96,9 +98,10 @@ declare class FileEntryCache {
     private _useCheckSum;
     private _hashAlgorithm;
     private _cwd;
-    private _strictPaths;
+    private _restrictAccessToCwd;
     private _logger?;
     private _useAbsolutePathAsKey;
+    private _useModifiedTime;
     /**
      * Create a new FileEntryCache instance
      * @param options - The options for the FileEntryCache (all properties are optional with defaults)
@@ -154,16 +157,26 @@ declare class FileEntryCache {
      * @param {string} value - The value to set
      */
     set cwd(value: string);
+    /**
+     * Get whether to use modified time for change detection
+     * @returns {boolean} Whether modified time (mtime) is used for change detection (default: true)
+     */
+    get useModifiedTime(): boolean;
+    /**
+     * Set whether to use modified time for change detection
+     * @param {boolean} value - The value to set
+     */
+    set useModifiedTime(value: boolean);
     /**
      * Get whether to restrict paths to cwd boundaries
      * @returns {boolean} Whether strict path checking is enabled (default: true)
      */
-    get strictPaths(): boolean;
+    get restrictAccessToCwd(): boolean;
     /**
      * Set whether to restrict paths to cwd boundaries
      * @param {boolean} value - The value to set
      */
-    set strictPaths(value: boolean);
+    set restrictAccessToCwd(value: boolean);
     /**
      * Get whether to use absolute path as cache key
      * @returns {boolean} Whether cache keys use absolute paths (default: false)
@@ -262,21 +275,21 @@ declare class FileEntryCache {
     getFileDescriptorsByPath(filePath: string): FileDescriptor[];
     /**
      * 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.
+     * When restrictAccessToCwd 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
+     * @throws {Error} When restrictAccessToCwd is true and path would resolve outside cwd
      */
     getAbsolutePath(filePath: string): string;
     /**
      * 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.
+     * When restrictAccessToCwd 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
+     * @throws {Error} When restrictAccessToCwd is true and path would resolve outside the provided cwd
      */
     getAbsolutePathWithCwd(filePath: string, cwd: string): string;
     /**

package/dist/index.js

@@ -1 +1 @@
-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};
+import b from"crypto";import l from"fs";import o from"path";import{createFromFile as y,FlatCache as p}from"flat-cache";function F(n,e){let s=o.basename(n),r=o.dirname(n);return f(s,r,e)}function f(n,e,s){let r={...s,cache:{cacheId:n,cacheDir:e}},t=new g(r);if(e){let i=`${e}/${n}`;l.existsSync(i)&&(t.cache=y(i,r.cache))}return t}var u=class{static create=f;static createFromFile=F},g=class{_cache=new p({useClone:!1});_useCheckSum=!1;_hashAlgorithm="md5";_cwd=process.cwd();_restrictAccessToCwd=!1;_logger;_useAbsolutePathAsKey=!1;_useModifiedTime=!0;constructor(e){e?.cache&&(this._cache=new p(e.cache)),e?.useCheckSum&&(this._useCheckSum=e.useCheckSum),e?.hashAlgorithm&&(this._hashAlgorithm=e.hashAlgorithm),e?.cwd&&(this._cwd=e.cwd),e?.useModifiedTime!==void 0&&(this._useModifiedTime=e.useModifiedTime),e?.restrictAccessToCwd!==void 0&&(this._restrictAccessToCwd=e.restrictAccessToCwd),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 useModifiedTime(){return this._useModifiedTime}set useModifiedTime(e){this._useModifiedTime=e}get restrictAccessToCwd(){return this._restrictAccessToCwd}set restrictAccessToCwd(e){this._restrictAccessToCwd=e}get useAbsolutePathAsKey(){return this._useAbsolutePathAsKey}set useAbsolutePathAsKey(e){this._useAbsolutePathAsKey=e}getHash(e){return b.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 h=s?.useCheckSum??this._useCheckSum;this._logger?.debug({useCheckSum:h},"Using checksum setting");let d=s?.useModifiedTime??this.useModifiedTime;this._logger?.debug({useModifiedTime:d},"Using modified time (mtime) 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"),h){let a=l.readFileSync(c);t.meta.hash=this.getHash(a),this._logger?.trace({hash:t.meta.hash},"Calculated file hash")}}catch(a){this._logger?.error({filePath:e,error:a},"Error reading file"),this.removeEntry(e);let m=!1;return a.message.includes("ENOENT")&&(m=!0,this._logger?.debug({filePath:e},"File not found")),{key:t.key,err:a,notFound:m,meta:{}}}return i?(d&&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")),h&&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._restrictAccessToCwd){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._restrictAccessToCwd){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{g as FileEntryCache,f as create,F as createFromFile,u as default};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "file-entry-cache",
-  "version": "11.0.0-beta.5",
+  "version": "11.1.0",
   "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,7 +30,7 @@
   ],
   "devDependencies": {
     "@biomejs/biome": "^2.2.5",
-    "@types/node": "^24.7.1",
+    "@types/node": "^24.7.2",
     "@vitest/coverage-v8": "^3.2.4",
     "pino": "^10.0.0",
     "rimraf": "^6.0.1",