fs-cache-fast/README.md

186 lines
5.4 KiB
Markdown
Raw Permalink Normal View History

2024-09-20 10:31:25 +00:00
# fs-cache-fast
fs-cache-fast is a small, no dependancy, both promise and sync based file system cache storage.
This package is designed to be a smaller, lighter, drop-in replacement for [file-system-cache](https://www.npmjs.com/package/file-system-cache).
# Installation
Install with npm:
```bash
$ npm install --save fs-cache-fast
```
# Getting started
The api is extremely simple:
```javascript
import Cache from 'fs-cache-fast'
let cache = new Cache()
cache.setSync('my-key', { value: 'here' })
let item = cache.getSync('my-key', { fallback: 'here' })
await cache.set('another-key', 'Hi there')
let result = await cache.get('another-key')
```
# Api
### new Cache(options)
Create a new cache with the specified directory (if directory is skipped, it randomly generates one in fs.tmp on each run).
Possible values in options:
```javascript
{
prefix: 'myprefix', // Add a prefix to every cached filename that is generated
ns: 'myprefix', // Alternative name for prefix, for API compatibility with file-system-cache
hash_alg: 'sha256', // Use the specified hashing algorithm that is used to generate the filename
cache_dir: '/tmp/MY_CACHE', // The directory where all the cache gets stored, gets auto-created if not exist.
ttl: 60, // Expiration in seconds for each cache item.
}
```
The default options are as follow:
```javascript
{
prefix: '-',
hash_alg: 'md5',
cache_dir: path.join(os.tmpdir(), /* random id */),
ttl: 0,
}
```
### cache.get(key, fallback = null)
Promise get the cache value that exists with item `key` and if it doesn't exist or has expired, returns the fallback value instead.
```javascript
let myCache = await cache.get('mykey', null)
```
### cache.getSync(key, fallback = null)
Immediately get the cache value that exists with item `key` and if it doesn't exist or has expired, returns the fallback value instead.
```javascript
let myCache = cache.getSync('mykey', null)
```
### cache.set(key, content, ttl | { ttl: number } = null)
Promise store the content as cache with the specified key (with optional overwriting default ttl set on the cache constructor).
```javascript
await cache.set('mykey', { hello: 'world' })
```
### cache.setSync(key, content, ttl | { ttl: number } = null)
Immediately store the content as cache with the specified key (with optional overwriting default ttl set on the cache constructor).
```javascript
cache.setSync('mykey', { hello: 'world' }, 5 * 60) // Expire this after 5 minutes
```
### cache.setMany(items, ttl | { ttl: number } = null)
### cache.save(items, ttl | { ttl: number } = null)
Promise store multiple items all at once while optionally overwriting the ttl for these entries.
Items take form of an array of json objects with the following signature: `{ key, content }`
**Note**, for backwards compatibility with `file-system-cache` you can also use the property `value` instead of `content`.
```javascript
await cache.setMany([
{ key: 'one', content: 'Store this' },
{ key: 'two', content: { a: 'and also this' } },
])
await cache.save([
{ key: 'one', value: 'Store this' },
{ key: 'two', value: { a: 'and also this' } },
])
```
### cache.setManySync(items, ttl | { ttl: number } = null)
### cache.saveSync(items, ttl | { ttl: number } = null)
Immediately store multiple items all at once while optionally overwriting the ttl for these entries.
Items take form of an array of json objects with the following signature: `{ key, content }`
**Note**, for backwards compatibility with `file-system-cache` you can also use the property `value` instead of `content`.
**Note**, there's an alternative name for it called `.saveSync(...)` for retaining similar naming schema as `file-system-cache` (it does not provide this functionality).
```javascript
cache.setManySync([
{ key: 'one', content: 'Store this' },
{ key: 'two', content: { a: 'and also this' } },
], 10 * 60) // Expire all of these after 10 minutes.
cache.saveSync([
{ key: 'one', value: 'Store this' },
{ key: 'two', value: { a: 'and also this' } },
], 10 * 60) // Expire all of these after 10 minutes.
```
### cache.remove(key)
Promise remove a cache with the specified key.
```javascript
await cache.remove('mykey')
```
### cache.removeSync(key)
Immediately remove a cache with the specified key.
```javascript
cache.removeSync('mykey')
```
### cache.clear()
Promise remove all items in the cache directory that match the specified `prefix` or `ns` if you will.
```javascript
await cache.clear()
```
### cache.clearSync()
Immediately remove all items in the cache directory that match the specified `prefix` or `ns` if you will.
```javascript
cache.clearSync()
```
### cache.getAll()
Promise return all items currently residing in the cache that have valid ttl.
This returns an array of objects, each one with with following signature: `{ key, content, ttl }`
```javascript
let items = await cache.getAll()
// items[0] = { key: 'one', content: 'Store this' }
// items[1] = { key: 'two', content: { a: 'and also this' } }
```
### cache.load()
Promise return all items currently residing in the cache that have valid ttl.
This is an API compatible version with `file-system-cache` and returns the results slightly different to maintain compatibility.
Returns an object with key files that has an array of items with this signature: `{ path, value, key }`
```javascript
let items = await cache.load()
// items.files[0] = { path: '...', value: 'Store this', key: 'one' }
// items.files[1] = { path: '...', value: { a: 'and also this' }, key: 'two' }
```