Registry / devops / file-entry-cache

file-entry-cache

library11.1.3jsnpmunverified

A lightweight file metadata cache for detecting file changes between runs. Version 11 is the current stable release (2025), part of the Cacheable ecosystem. Uses checksums and configurable path handling to determine file modifications. Key differentiators: simple API, disk persistence via reconcile(), configurable working directory and path security, and full ESM/CommonJS support with TypeScript types.

devops testing

npm install file-entry-cache

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · FILE-ENTRY-CACHE

file-entry-cache

devopsjavascriptv11.1.3

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

default

✓ import fileEntryCache from 'file-entry-cache'

✗ const fileEntryCache = require('file-entry-cache')

ESM default export in v11. For CommonJS, use dynamic import or downgrade to v10.

FileEntryCacheOptions

✓ import type { FileEntryCacheOptions } from 'file-entry-cache'

✗ import { FileEntryCacheOptions } from 'file-entry-cache'

TypeScript type-only import. Do not use value import.

getFileDescriptor

✓ import fileEntryCache from 'file-entry-cache'; const cache = fileEntryCache.create('myCache'); cache.getFileDescriptor('./src/file.txt')

✗ import { getFileDescriptor } from 'file-entry-cache'

getFileDescriptor is a method on the cache instance, not a named export.

Shows basic usage: create cache, detect changes, and persist to disk.

import fileEntryCache from 'file-entry-cache'; import fs from 'fs'; // Create or load a cache named 'myCache' const cache = fileEntryCache.create('myCache'); // Check a file (first run always changed) const filePath = './test.txt'; fs.writeFileSync(filePath, 'Hello'); const descriptor = cache.getFileDescriptor(filePath); console.log(descriptor.changed); // true // Second check (unchanged) const descriptor2 = cache.getFileDescriptor(filePath); console.log(descriptor2.changed); // false // Modify and check again fs.writeFileSync(filePath, 'World'); const descriptor3 = cache.getFileDescriptor(filePath); console.log(descriptor3.changed); // true // Persist cache to disk cache.reconcile(); // Remove temporary file fs.unlinkSync(filePath);

Debug

Known issues

breakingVersion 11 changed from CommonJS to ESM-only default export. Dynamic import required for CommonJS projects.

fix

Use `const fileEntryCache = await import('file-entry-cache')` or upgrade to ESM.

affects: >=11.0.0

breakingVersion 10 changes: options object added to create(). Default path now uses current working directory instead of temp directory.

fix

If using the default cache path, update code to handle new location. Ensure compatibility with v10 options.

affects: >=10.0.0

gotchaPath traversal protection: by default, getFileDescriptor restricts paths to within current working directory. Allows access outside via restrictAccessToCwd option.

fix

To allow paths outside cwd, set `restrictAccessToCwd: false` in options.

affects: >=11.0.0

gotchauseCheckSum must be set at creation time to use checksums; cannot be changed later.

fix

Pass `{ useCheckSum: true }` in options when calling create().

affects: >=1.0.0

deprecatedset and get methods for custom metadata have been deprecated in favor of setMeta and getMeta on file descriptors.

fix

Use `cache.getFileDescriptor(path).setMeta(data)` and `.getMeta()` instead.

affects: >=10.0.0

Errors

Common errors & fixes

SyntaxError: Cannot use import statement outside a module

Using ESM import in a CommonJS project without dynamic import.

fix

Change to `const fileEntryCache = await import('file-entry-cache');` or set `"type": "module"` in package.json.

TypeError: fileEntryCache.create is not a function

Importing incorrectly, likely using named import for default export.

fix

Use `import fileEntryCache from 'file-entry-cache'` (default import).

Error: The path is outside the configured current working directory

Path traversal prevention blocks absolute paths or paths outside cwd.

fix

Use relative paths within cwd or set `restrictAccessToCwd: false` in options.

Error: Can't find cache with name

Calling getFileDescriptor before creating cache with create().

fix

Ensure you call `fileEntryCache.create('cacheName')` before using the cache.

Upgrade

Version history

11.1.3latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/jaredwray/cacheable ↗

packagefile-entry-cache ↗

homepagehttps://github.com/jaredwray/cacheable#readme ↗