fs-cache-fast/README.md

# 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' }
```