## :notebook_with_decorative_cover: Table of Contents
- [Package Details](#star2-package-details)
- [Usage](#eyes-usage)
- [Run Locally](#running-run-locally)
- [Contributing](#wave-contributing)
- [License](#warning-license)
- [Support](#sos-support)
- [Acknowledgments](#yellow_heart-acknowledgments)
## :star2: Package Details
A Node.js library for caching arbitrary data to disk and restoring cache in between runs. Used by [figmarine](https://github.com/Sidnioulz/figmarine) to cache REST API return values.
- Disk-based memory store
- Configurable store location
- Configurable TTL, cache size and refresh rate
- Allows you to wrap functions for automatic caching
## :eyes: Usage
Install the package with the following command:
```bash
pnpm i @figmarine/cache
```
Then, import `makeCache` and call it:
```javascript
import { makeCache, type MakeCacheOptions } from '@figmarine/cache';
const { cache, shutdownGracefully } = makeCache({
// A relative path creates a subfolder in /tmp/@figmarine/cache.
location: 'rest',
// Pass -1 to push the TTL to its limit (one year TTL).
ttl: -1,
});
```
You can use the disk cache directly if you want to write into it and handle it manually.
```javascript
await cache.set('myKey', 'My value');
const value = await cache.get('myKey');
console.log(value); // 'My value'
await cache.delete(key);
const value = await cache.get('myKey');
console.log(value); // 'undefined'
```
You can also wrap existing functions with `.getCache().wrap()`. When a wrapped function is called,
its return value is cached using the function parameters as a cache key. On the second call
with the same parameters, the cached value will be returned instantly and the function body
won't need to be called ( provided the cached content hasn't expired).
```javascript
const queryFoo = (key) => axios.get(`/foo?ID=${key}`);
const cachedQueryFoo = cache.getCache().wrap(queryFoo, { key: 'uniqueKeyForThisFunction' });
console.time('First call');
const first = cachedQueryFoo('1234');
console.timeEnd('First call');
// First call: 1081.284912109375 ms
console.time('Second call');
const second = cachedQueryFoo('1234');
console.timeEnd('Second call');
// Second call: 0.108056640625 ms
```
## :running: Run Locally
Clone the project
```bash
git clone https://github.com/Sidnioulz/figmarine.git
```
Go to the project directory
```bash
cd packages/cache
```
Install dependencies
```bash
pnpm install
```
Build the code as you make changes
```bash
pnpm dev
```
Check that tests run as you make changes
```bash
pnpm test:dev
```
## :wave: Contributing
See [how to contribute](https://github.com/Sidnioulz/figmarine/tree/main?tab=readme-ov-file#package-contributing).
## :warning: License
Distributed under the [MIT License](https://github.com/Sidnioulz/figmarine/tree/main?tab=MIT-1-ov-file).
## :sos: Support
Please open a conversation in the [discussion space](https://github.com/Sidnioulz/figmarine/discussions) to ask a question.
Please [open an issue](https://github.com/Sidnioulz/figmarine/issues/new?labels=pkg-cache) for bug reports or code suggestions.
## :yellow_heart: Acknowledgments
- [cache-manager](https://github.com/jaredwray/cacheable/tree/main/packages/cache-manager)
- [cache-manager store for filesystem](https://github.com/rolandstarke/node-cache-manager-fs-hash)
