https://github.com/vvscode/file-memoize
A higher-order function in Node.js that caches results to JSON files in the OS temporary directory
https://github.com/vvscode/file-memoize
Last synced: 9 months ago
JSON representation
A higher-order function in Node.js that caches results to JSON files in the OS temporary directory
- Host: GitHub
- URL: https://github.com/vvscode/file-memoize
- Owner: vvscode
- License: mit
- Created: 2025-04-16T14:53:23.000Z (about 1 year ago)
- Default Branch: master
- Last Pushed: 2025-04-16T16:48:25.000Z (about 1 year ago)
- Last Synced: 2025-05-05T01:15:49.606Z (about 1 year ago)
- Language: TypeScript
- Size: 102 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# file-memoize
[](https://www.npmjs.com/package/file-memoize)
[](https://github.com/vvscode/file-memoize/actions)
A simple and efficient TypeScript higher-order function to cache asynchronous function results to JSON files in the OS temporary directory. Designed for Node.js, it persists cached results across runs using parameter-based keys and customizable cache file naming.
---
## Features
- Cache async function results to JSON files on disk
- Uses OS temporary directory for cache storage
- Supports single string or multiple parameters as cache keys
- Cache file named using `CI_COMMIT_SHA` environment variable and function name
- Automatically loads and saves cache on function calls
- Written in TypeScript with full type safety
---
## Installation
```bash
npm install file-memoize
# or
yarn add file-memoize
```
---
## Usage
```typescript
import { fileMemoize } from 'file-memoize';
// Example async function
async function fetchData(param: string): Promise {
// Simulate an async operation
return `Data for ${param}`;
}
// Create a memoized version of the function
const memoizedFetchData = fileMemoize(fetchData, 'fetchData');
async function run() {
// First call: runs the original function and caches result
console.log(await memoizedFetchData('books')); // Output: Data for books
// Second call with same param: returns cached result instantly
console.log(await memoizedFetchData('books')); // Output: Data for books
}
run();
```
---
## API
### `fileMemoize(fn, functionName, getFileName?)`
Creates a memoized version of an async function `fn` that caches results to a JSON file.
| Parameter | Type | Description |
|---------------|----------------------------------|--------------------------------------------------------------------------------------------------|
| `fn` | `(...args: any[]) => Promise` | The async function to memoize. |
| `functionName`| `string` | Name of the function, used in cache file naming. |
| `getFileName` | `() => string` (optional) | Optional function to customize cache file path. Defaults to `${tmpdir}/${CI_COMMIT_SHA}_${functionName}.json`. |
**Returns:** A function with the same signature as `fn` that caches results on disk.
---
## How it works
- On first invocation, the cache file is loaded if it exists.
- Function call arguments are serialized to form cache keys:
- If a single string argument is passed, it is used directly as the key.
- Otherwise, the arguments array is JSON-stringified.
- If a cached result exists for the key, it is returned immediately.
- Otherwise, the original function is called, the result cached, and saved to file.
---
## Environment Variables
- `CI_COMMIT_SHA`: Used as part of the cache filename to isolate cache per commit or environment. Defaults to `'default'` if unset.
---
## Testing
The package includes Jest tests covering:
- Cache hit and miss behavior
- Cache persistence to disk
- Handling of multiple parameters
- Graceful error handling on file read/write failures
Run tests with:
```bash
npm test
```
---
## Contributing
Contributions, issues, and feature requests are welcome! Feel free to open issues or pull requests.
---