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.

Installation

Install with npm:

$ npm install --save fs-cache-fast

Getting started

The api is extremely simple:

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:

{
  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:

{
  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.

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.

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).

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).

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.

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).

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.

await cache.remove('mykey')

cache.removeSync(key)

Immediately remove a cache with the specified key.

cache.removeSync('mykey')

cache.clear()

Promise remove all items in the cache directory that match the specified prefix or ns if you will.

await cache.clear()

cache.clearSync()

Immediately remove all items in the cache directory that match the specified prefix or ns if you will.

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 }

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 }

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