{"id":44953,"library":"file-entry-cache","title":"file-entry-cache","description":"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.","status":"active","version":"11.1.3","language":"javascript","source_language":"en","source_url":"https://github.com/jaredwray/cacheable","tags":["javascript","file cache","task cache files","key par","key value","cache","typescript"],"install":[{"cmd":"npm install file-entry-cache","lang":"bash","label":"npm"},{"cmd":"yarn add file-entry-cache","lang":"bash","label":"yarn"},{"cmd":"pnpm add file-entry-cache","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"ESM default export in v11. For CommonJS, use dynamic import or downgrade to v10.","wrong":"const fileEntryCache = require('file-entry-cache')","symbol":"default","correct":"import fileEntryCache from 'file-entry-cache'"},{"note":"TypeScript type-only import. Do not use value import.","wrong":"import { FileEntryCacheOptions } from 'file-entry-cache'","symbol":"FileEntryCacheOptions","correct":"import type { FileEntryCacheOptions } from 'file-entry-cache'"},{"note":"getFileDescriptor is a method on the cache instance, not a named export.","wrong":"import { getFileDescriptor } from 'file-entry-cache'","symbol":"getFileDescriptor","correct":"import fileEntryCache from 'file-entry-cache';\nconst cache = fileEntryCache.create('myCache');\ncache.getFileDescriptor('./src/file.txt')"}],"quickstart":{"code":"import fileEntryCache from 'file-entry-cache';\nimport fs from 'fs';\n\n// Create or load a cache named 'myCache'\nconst cache = fileEntryCache.create('myCache');\n\n// Check a file (first run always changed)\nconst filePath = './test.txt';\nfs.writeFileSync(filePath, 'Hello');\nconst descriptor = cache.getFileDescriptor(filePath);\nconsole.log(descriptor.changed); // true\n\n// Second check (unchanged)\nconst descriptor2 = cache.getFileDescriptor(filePath);\nconsole.log(descriptor2.changed); // false\n\n// Modify and check again\nfs.writeFileSync(filePath, 'World');\nconst descriptor3 = cache.getFileDescriptor(filePath);\nconsole.log(descriptor3.changed); // true\n\n// Persist cache to disk\ncache.reconcile();\n\n// Remove temporary file\nfs.unlinkSync(filePath);","lang":"typescript","description":"Shows basic usage: create cache, detect changes, and persist to disk."},"warnings":[{"fix":"Use `const fileEntryCache = await import('file-entry-cache')` or upgrade to ESM.","message":"Version 11 changed from CommonJS to ESM-only default export. Dynamic import required for CommonJS projects.","severity":"breaking","affected_versions":">=11.0.0"},{"fix":"If using the default cache path, update code to handle new location. Ensure compatibility with v10 options.","message":"Version 10 changes: options object added to create(). Default path now uses current working directory instead of temp directory.","severity":"breaking","affected_versions":">=10.0.0"},{"fix":"To allow paths outside cwd, set `restrictAccessToCwd: false` in options.","message":"Path traversal protection: by default, getFileDescriptor restricts paths to within current working directory. Allows access outside via restrictAccessToCwd option.","severity":"gotcha","affected_versions":">=11.0.0"},{"fix":"Pass `{ useCheckSum: true }` in options when calling create().","message":"useCheckSum must be set at creation time to use checksums; cannot be changed later.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Use `cache.getFileDescriptor(path).setMeta(data)` and `.getMeta()` instead.","message":"set and get methods for custom metadata have been deprecated in favor of setMeta and getMeta on file descriptors.","severity":"deprecated","affected_versions":">=10.0.0"}],"env_vars":null,"search_vec":"'11':17 '2025':23 'api':42 'cach':4,9,62,64,70 'cacheabl':27 'chang':13 'checksum':30 'configur':32,47 'current':20 'detect':11 'determin':36 'differenti':40 'directori':49 'disk':43 'ecosystem':28 'entri':3 'esm/commonjs':55 'file':2,7,12,37,61,65 'file-entry-cach':1 'full':54 'handl':34 'javascript':60 'key':39,66,68 'lightweight':6 'metadata':8 'modif':38 'par':67 'part':24 'path':33,51 'persist':44 'reconcil':46 'releas':22 'run':15 'secur':52 'simpl':41 'stabl':21 'support':56 'task':63 'type':59 'typescript':58,71 'use':29 'valu':69 'version':16 'via':45 'work':48","created_at":"2026-06-07T12:52:39.477607+00:00","updated_at":"2026-06-07T12:52:39.477607+00:00","problems":[{"fix":"Change to `const fileEntryCache = await import('file-entry-cache');` or set `\"type\": \"module\"` in package.json.","cause":"Using ESM import in a CommonJS project without dynamic import.","error":"SyntaxError: Cannot use import statement outside a module"},{"fix":"Use `import fileEntryCache from 'file-entry-cache'` (default import).","cause":"Importing incorrectly, likely using named import for default export.","error":"TypeError: fileEntryCache.create is not a function"},{"fix":"Use relative paths within cwd or set `restrictAccessToCwd: false` in options.","cause":"Path traversal prevention blocks absolute paths or paths outside cwd.","error":"Error: The path is outside the configured current working directory"},{"fix":"Ensure you call `fileEntryCache.create('cacheName')` before using the cache.","cause":"Calling getFileDescriptor before creating cache with create().","error":"Error: Can't find cache with name"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null,"cli_version":null,"type":"library","homepage":"https://github.com/jaredwray/cacheable#readme","github":"https://github.com/jaredwray/cacheable","docs":null,"changelog":null,"pypi":null,"npm":"file-entry-cache","openapi_spec":null,"status_page":null,"smithery":null,"categories":["devops","testing"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-07","next_check":"2026-09-05","install_tag":null}}