# file-system-cache

> A super-fast, promise-based cache that reads and writes to the file-system.

Latest version **3.0.0-alpha.8** (published 2024-08-26) · MIT license · 0 weekly downloads

## Install

```sh
npm install file-system-cache
pnpm add file-system-cache
yarn add file-system-cache
bun add file-system-cache
```

## Health

**Score 30/100 (F)** — status: abandoned.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 3.0.0-alpha.8 |
| Published | 2024-08-26 |
| First published | 2015-09-28 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 0 |
| Unpacked size | 735.2 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 66 |
| Author | Phil Cockfield |
| Maintainers | philcockfield |
| Keywords | cache, fs, file-system |

## Links

- npm: https://www.npmjs.com/package/file-system-cache
- Repository: https://github.com/philcockfield/file-system-cache
- Issues: https://github.com/philcockfield/file-system-cache/issues
- npm.io page: https://npm.io/package/file-system-cache

## Alternatives

- [unionfs](https://npm.io/package/unionfs.md) — 2.2M weekly downloads
- [path-starts-with](https://npm.io/package/path-starts-with.md) — 35.9K weekly downloads
- [redzip](https://npm.io/package/redzip.md) — 1.2K weekly downloads
- [vscode-anymatch](https://npm.io/package/vscode-anymatch.md) — 848 weekly downloads
- [@ledgerhq/coin-filecoin](https://npm.io/package/@ledgerhq/coin-filecoin.md) — 793 weekly downloads

## Recent versions

- 3.0.0-alpha.8 (latest) — 2024-08-26
- 3.0.0-alpha.7 — 2024-07-25
- 3.0.0-alpha.6 — 2024-07-24
- 3.0.0-alpha.5 — 2024-07-24
- 3.0.0-alpha.4 — 2024-07-24
- 3.0.0-alpha.3 — 2024-07-24
- 3.0.0-alpha.2 — 2024-07-24
- 3.0.0-alpha.1 — 2024-07-24
- 3.0.0 — 2024-07-16
- 2.4.7 — 2024-07-16
- 2.4.6 — 2024-07-16
- 2.4.5 — 2024-07-15
- 2.4.4 — 2023-08-10
- 2.4.3 — 2023-07-27
- 2.4.2 — 2023-07-08
- … 15 more at https://npm.io/package/file-system-cache/versions

## README

[![ci(esm)](https://github.com/philcockfield/file-system-cache/actions/workflows/node.esm.yml/badge.svg)](https://github.com/philcockfield/file-system-cache/actions/workflows/node.esm.yml)

# file-system-cache

A super-fast, promise-based cache that reads and writes to the file-system.


## Installation

    npm install --save file-system-cache

Import

```ts
import Cache from 'file-system-cache';

   // or ↑↓ (equivalent)

import { Cache } from 'file-system-cache';
```

## Usage (API)

Create an instance of the cache optionally giving it a folder location to store files within.

```js
import Cache from "file-system-cache";

const cache = Cache({
  basePath: "./.cache", // (optional) Path where cache files are stored (default).
  ns: "my-namespace",   // (optional) A grouping namespace for items.
  hash: "sha1",         // (optional) A hashing algorithm used within the cache key.
  ttl: 60,              // (optional) A time-to-live (in secs) on how long an item remains cached.
});
```

> Reference `default` for CommonJS, e.g: `const Cache = require('file-system-cache').default
`

The optional `ns` ("namespace") allows for multiple groupings of files to reside within the one cache folder.  When you have multiple caches with different namespaces you can re-use the same keys and they will not collide.

The optional `ttl` ("time to live") allows you to set a default expiration for the cache key, in seconds. For example if you
set this value to 60 then cache hits to any cache key made beyond the limit of that 60 seconds will result in cache misses.

### get(key, defaultValue)
Retrieves the contents of a cached file.

```js
cache.get("foo")
  .then(result => /* Success */)
  .catch(err => /* Fail */);
```

or use modern `async/await` syntactic sugar of course:

```js
const value = await cache.get("foo");
```

Use `getSync` for a synchronous version.  
Pass a `defaultValue` parameter to use if the key does not exist within the cache.


### set(key, value, ttl)
Write a value to the cache.

```js
/* This will apply the default TTL to this cache key */
cache.set("foo", "...value...")
  .then(result => /* Success */)

/* This will set a specific TTL for this cache key */
cache.set("bar", "...baz", 60)
  .then(result => /* Success */)
```

Value types are stored and respected on subsequent calls to `get`.  For examples, passing in Object will return that in its parsed object state.

Use `setSync` for a synchronous version.

### remove(key)
Deletes the specified cache item from the file-system.
```js
cache.remove("foo")
  .then(() => /* Removed */)
```

### clear()
Clears all cached items from the file-system.
```js
cache.clear()
  .then(() => /* All items deleted */)
```


### save()
Saves (sets) several items to the cache in one operation.
```js
cache.save([{ key:"one", value:"hello" }, { key:"two", value:222 }])
  .then(result => /* All items saved. */)
```

### load()
Loads all files within the cache's namespace.
```js
cache.load()
  .then(result => /* The complete of cached files (for the ns). */)
```



## Test
    # Run tests.
    npm test

---
_Source: https://npm.io/package/file-system-cache · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._