Gathering detailed insights and metrics for file-entry-cache
a robust, scalable, and maintained set of caching packages
Installations
npm install file-entry-cacheDeveloper Guide
BETA
Typescript
Yes
Module System
ESM
Node Version
22.12.0
NPM Version
10.9.0
Score
99.3
Supply Chain
99.5
Quality
87.7
Maintenance
100
Vulnerability
100
License
Releases
29
Contributors
83
Languages
3
TypeScript
JavaScript
CSS
TypeScript (99.1%)
JavaScript (0.64%)
CSS (0.26%)
Developer
Download Statistics
Total Downloads
6,615,736,605
Last Day
7,889,061
Last Week
41,006,288
Last Month
141,211,770
Last Year
1,885,451,472
GitHub Statistics
1,705 Stars
1,345 Commits
176 Forks
10 Watching
1 Branches
83 Contributors
Bundle Size
15.91 kB
Minified
4.66 kB
Minified + Gzipped
Maintainers
1
Package Meta Information
Latest Version
10.0.5
Package Id
file-entry-cache@10.0.5
Unpacked Size
48.87 kB
Size
9.41 kB
File Count
7
NPM Version
10.9.0
Node Version
22.12.0
Publised On
27 Dec 2024
Total Downloads
Cumulative downloads
Total Downloads
6,615,736,605
Last day
1.1%
7,889,061
Compared to previous day
Last week
1.6%
41,006,288
Compared to previous week
Last month
-19%
141,211,770
Compared to previous month
Last year
28.8%
1,885,451,472
Compared to previous year
Daily Downloads
Weekly Downloads
Monthly Downloads
Yearly Downloads
Dependencies
1
Dev Dependencies
7
Versions
file-entry-cache
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
Features
- Lightweight cache for file metadata
- Ideal for processes that work on a specific set of files
- Persists cache to Disk via
reconcile()orpersistIntervaloncacheoptions. - Uses
checksumto determine if a file has changed - Supports
relativeandabsolutepaths - Ability to rename keys in the cache. Useful when renaming directories.
- ESM and CommonJS support with Typescript
Table of Contents
- Installation
- Getting Started
- Changes from v9 to v10
- Global Default Functions
- FileEntryCache Options (FileEntryCacheOptions)
- API
- Get File Descriptor
- Using Checksums to Determine if a File has Changed (useCheckSum)
- Setting Additional Meta Data
- How to Contribute
- License and Copyright
Installation
1npm install file-entry-cache
Getting Started
1import fileEntryCache from 'file-entry-cache'; 2const cache = fileEntryCache.create('cache1'); 3let fileDescriptor = cache.getFileDescriptor('file.txt'); 4console.log(fileDescriptor.changed); // true as it is the first time 5fileDescriptor = cache.getFileDescriptor('file.txt'); 6console.log(fileDescriptor.changed); // false as it has not changed 7// do something to change the file 8fs.writeFileSync('file.txt', 'new data foo bar'); 9// check if the file has changed 10fileDescriptor = cache.getFileDescriptor('file.txt'); 11console.log(fileDescriptor.changed); // true
Save it to Disk and Reconsile files that are no longer found
1import fileEntryCache from 'file-entry-cache'; 2const cache = fileEntryCache.create('cache1'); 3let fileDescriptor = cache.getFileDescriptor('file.txt'); 4console.log(fileDescriptor.changed); // true as it is the first time 5fileEntryCache.reconcile(); // save the cache to disk and remove files that are no longer found
Load the cache from a file:
1import fileEntryCache from 'file-entry-cache'; 2const cache = fileEntryCache.createFromFile('/path/to/cache/file'); 3let fileDescriptor = cache.getFileDescriptor('file.txt'); 4console.log(fileDescriptor.changed); // false as it has not changed from the saved cache.
Changes from v9 to v10
There have been many features added and changes made to the file-entry-cache class. Here are the main changes:
- Added
cacheobject to the options to allow for more control over the cache - Added
hashAlgorithmto the options to allow for different checksum algorithms. Note that if you load from file it most likely will break if the value was something before. - Updated more on using Relative or Absolute paths. We now support both on
getFileDescriptor(). You can read more on this in theGet File Descriptorsection. - Migrated to Typescript with ESM and CommonJS support. This allows for better type checking and support for both ESM and CommonJS.
- Once options are passed in they get assigned as properties such as
hashAlgorithmandcurrentWorkingDirectory. This allows for better control and access to the options. For the Cache options they are assigned tocachesuch ascache.ttlandcache.lruSize. - Added
cache.persistIntervalto allow for saving the cache to disk at a specific interval. This will save the cache to disk at the interval specified instead of callingreconsile()to save. (offby default) - Added
getFileDescriptorsByPath(filePath: string): FileEntryDescriptor[]to get all the file descriptors that start with the path specified. This is useful when you want to get all the files in a directory or a specific path. - Added
renameAbsolutePathKeys(oldPath: string, newPath: string): voidwill rename the keys in the cache from the old path to the new path. This is useful when you rename a directory and want to update the cache without reanalyzing the files. - Using
flat-cachev6 which is a major update. This allows for better performance and more control over the cache. - On
FileEntryDescriptor.metaif using typescript you need to use themeta.datato set additional information. This is to allow for better type checking and to avoid conflicts with themetaobject which wasany.
Global Default Functions
create(cacheId: string, cacheDirectory?: string, useCheckSum?: boolean, currentWorkingDirectory?: string)- Creates a new instance of theFileEntryCacheclasscreateFromFile(cachePath: string, useCheckSum?: boolean, currentWorkingDirectory?: string)- Creates a new instance of theFileEntryCacheclass and loads the cache from a file.
FileEntryCache Options (FileEntryCacheOptions)
currentWorkingDirectory?- The current working directory. Used when resolving relative paths.useCheckSum?- Iftrueit will use a checksum to determine if the file has changed. Default isfalsehashAlgorithm?- The algorithm to use for the checksum. Default ismd5but can be any algorithm supported bycrypto.createHashcache.ttl?- The time to live for the cache in milliseconds. Default is0which means no expirationcache.lruSize?- The number of items to keep in the cache. Default is0which means no limitcache.useClone?- Iftrueit will clone the data before returning it. Default isfalsecache.expirationInterval?- The interval to check for expired items in the cache. Default is0which means no expirationcache.persistInterval?- The interval to save the data to disk. Default is0which means no persistencecache.cacheDir?- The directory to save the cache files. Default is./cachecache.cacheId?- The id of the cache. Default iscache1cache.parse?- The function to parse the data. Default isflatted.parsecache.stringify?- The function to stringify the data. Default isflatted.stringify
API
constructor(options?: FileEntryCacheOptions)- Creates a new instance of theFileEntryCacheclassuseCheckSum: boolean- Iftrueit will use a checksum to determine if the file has changed. Default isfalsehashAlgorithm: string- The algorithm to use for the checksum. Default ismd5but can be any algorithm supported bycrypto.createHashcurrentWorkingDirectory: string- The current working directory. Used when resolving relative paths.getHash(buffer: Buffer): string- Gets the hash of a buffer used for checksumscreateFileKey(filePath: string): string- Creates a key for the file path. This is used to store the data in the cache based on relative or absolute paths.deleteCacheFile(filePath: string): void- Deletes the cache filedestroy(): void- Destroys the cache. This will also delete the cache file. If using cache persistence it will stop the interval.removeEntry(filePath: string): void- Removes an entry from the cache. This can berelativeorabsolutepaths.reconcile(): void- Saves the cache to disk and removes any files that are no longer found.hasFileChanged(filePath: string): boolean- Checks if the file has changed. This will returntrueif the file has changed.getFileDescriptor(filePath: string, options?: { useCheckSum?: boolean, currentWorkingDirectory?: string }): FileEntryDescriptor- Gets the file descriptor for the file. Please refer to the entire section onGet File Descriptorfor more information.normalizeEntries(entries: FileEntryDescriptor[]): FileEntryDescriptor[]- Normalizes the entries to have the correct paths. This is used when loading the cache from disk.analyzeFiles(files: string[])will returnAnalyzedFilesobject withchangedFiles,notFoundFiles, andnotChangedFilesas FileDescriptor arrays.getUpdatedFiles(files: string[])will return an array ofFileEntryDescriptorobjects that have changed.getFileDescriptorsByPath(filePath: string): FileEntryDescriptor[]will return an array ofFileEntryDescriptorobjects that starts with the path specified.renameAbsolutePathKeys(oldPath: string, newPath: string): void- Renames the keys in the cache from the old path to the new path. This is useful when you rename a directory and want to update the cache without reanalyzing the files.
Get File Descriptor
The getFileDescriptor(filePath: string, options?: { useCheckSum?: boolean, currentWorkingDirectory?: string }): FileEntryDescriptor function is used to get the file descriptor for the file. This function will return a FileEntryDescriptor object that has the following properties:
key: string- The key for the file. This is the relative or absolute path of the file.changed: boolean- If the file has changed since the last time it was analyzed.notFound: boolean- If the file was not found.meta: FileEntryMeta- The meta data for the file. This has the following prperties:size,mtime,ctime,hash,data. Note thatdatais an object that can be used to store additional information.err- If there was an error analyzing the file.
We have added the ability to use relative or absolute paths. If you pass in a relative path it will use the currentWorkingDirectory to resolve the path. If you pass in an absolute path it will use the path as is. This is useful when you want to use relative paths but also want to use absolute paths.
If you do not pass in currentWorkingDirectory in the class options or in the getFileDescriptor function it will use the process.cwd() as the default currentWorkingDirectory.
1const fileEntryCache = new FileEntryCache(); 2const fileDescriptor = fileEntryCache.getFileDescriptor('file.txt', { currentWorkingDirectory: '/path/to/directory' });
Since this is a relative path it will use the currentWorkingDirectory to resolve the path. If you want to use an absolute path you can do the following:
1const fileEntryCache = new FileEntryCache(); 2const filePath = path.resolve('/path/to/directory', 'file.txt'); 3const fileDescriptor = fileEntryCache.getFileDescriptor(filePath);
This will save the key as the absolute path.
If there is an error when trying to get the file descriptor it will return an ``notFoundanderr` property with the error.
1const fileEntryCache = new FileEntryCache(); 2const fileDescriptor = fileEntryCache.getFileDescriptor('no-file'); 3if (fileDescriptor.err) { 4 console.error(fileDescriptor.err); 5} 6 7if (fileDescriptor.notFound) { 8 console.error('File not found'); 9}
Using Checksums to Determine if a File has Changed (useCheckSum)
By default the useCheckSum is false. This means that the FileEntryCache will use the mtime and ctime to determine if the file has changed. If you set useCheckSum to true it will use a checksum to determine if the file has changed. This is useful when you want to make sure that the file has not changed at all.
1const fileEntryCache = new FileEntryCache(); 2const fileDescriptor = fileEntryCache.getFileDescriptor('file.txt', { useCheckSum: true });
You can pass useCheckSum in the FileEntryCache options, as a property .useCheckSum to make it default for all files, or in the getFileDescriptor function. Here is an example where you set it globally but then override it for a specific file:
1const fileEntryCache = new FileEntryCache({ useCheckSum: true }); 2const fileDescriptor = fileEntryCache.getFileDescriptor('file.txt', { useCheckSum: false });
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.
1const fileEntryCache = new FileEntryCache(); 2const fileDescriptor = fileEntryCache.getFileDescriptor('file.txt'); 3fileDescriptor.meta.data = { myData: 'myData' }; //anything you want
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. This will talk about how to Open a Pull Request, Ask a Question, or Post an Issue.
License and Copyright
No vulnerabilities found.
No security vulnerabilities found.