# simply-caching

> Super simple in memory and file-based caching

Latest version **1.1.2** (published 2022-03-05) · MIT license · 0 weekly downloads

## Install

```sh
npm install simply-caching
pnpm add simply-caching
yarn add simply-caching
bun add simply-caching
```

## Health

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

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.1.2 |
| Published | 2022-03-05 |
| First published | 2020-01-26 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >=12.13.0 |
| Dependencies | 3 |
| Unpacked size | 26.2 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | Joshua Evans |
| Maintainers | thejoshuaevans |
| Keywords | cache, simple, filesystem, memory |

## Links

- npm: https://www.npmjs.com/package/simply-caching
- Repository: https://github.com/TheJoshuaEvans/simply-caching
- Homepage: https://github.com/TheJoshuaEvans/simply-caching#readme
- Issues: https://github.com/TheJoshuaEvans/simply-caching/issues
- npm.io page: https://npm.io/package/simply-caching

## Dependencies (3)

- [lodash.merge](https://npm.io/package/lodash.merge.md) ^4.6.2
- [lodash.isequal](https://npm.io/package/lodash.isequal.md) ^4.5.0
- [lodash.clonedeep](https://npm.io/package/lodash.clonedeep.md) ^4.5.0

## Alternatives

- [memory-cache](https://npm.io/package/memory-cache.md) — 795.0K weekly downloads
- [@httptoolkit/proxy-agent](https://npm.io/package/@httptoolkit/proxy-agent.md) — 11.2K weekly downloads
- [express-cache-controller](https://npm.io/package/express-cache-controller.md) — 5.3K weekly downloads
- [http-cache-middleware](https://npm.io/package/http-cache-middleware.md) — 4.5K weekly downloads
- [cache2](https://npm.io/package/cache2.md) — 1.5K weekly downloads

## Recent versions

- 1.1.2 (latest) — 2022-03-05
- 1.1.1 — 2020-06-27
- 1.1.0 — 2020-02-01
- 1.0.6 — 2020-02-01
- 1.0.5 — 2020-01-26
- 1.0.4 — 2020-01-26
- 1.0.3 — 2020-01-26
- 1.0.2 — 2020-01-26
- 1.0.1 — 2020-01-26
- 1.0.0 — 2020-01-26

## README

# Simply Caching
Super simple caching system. Designed to be lightweight and easy to use

# Installation
```
npm install --save simply-caching
```

# Simple Example
```js
const SimplyCaching = require('simply-caching');

// Create a cache object with default settings
const cache = new SimplyCaching();

// Set an item into the cache
await cache.setCache('key', data);

// Get an item from the cache
const retrievedData = await cache.getCache('key');

// Clear an item form the cache
await cache.clearCache('key')
```

# Methods
This module uses promises and is designed to be used with the `async/await` pattern

Instances of this module only have three methods: `setCache`, `getCache`, and `clearCache`. Every method requires a string "key" as its first parameter, and the `setCache` method takes a "data" object as its second parameter. Each method also takes an "opts" parameter that can be used to overwrite configurations set on the parent instance

## [setCache](./src/control/set-cache.js)
```js
await setCache(key, data, opts = {}) 
```
The `setCache` method saves the provided data to the cache. Only object, number, and string data types are explicitly supported by all cache types

Throws an error if `general.overwrite` is set to `false` and data with the provided key already exists in the cache

## [getCache](./src/control/get-cache.js)
```js
const cachedData = await getCache(key, opts = {})
```
The `getCache` method retrieves data from the cache with a provided key. If multiple caches are enabled, the caches will be searched in order until the data is found and returned

Throws an error if data with the provided key cannot be found after searching all enabled caches

## [clearCache](./src/control/clear-cache.js)
```js
await clearCache(key, opts = {})
```
The `clearCache` method removes data from the cache with the provided key. If the empty string (`''`) is provided, all of the cached data in the configured cache root will be cleared

# Configuration
When creating a new cache instance, you can pass an object to the constructor with the following configurations. See the [default config file](./.simplycachingrc.default.js) for object formatting, documentation, and default values

# Cache Types
This module can use a few different methods of caching data. Use the `general.caches` configuration to choose which methods you wish to use. The order of the provided array will determine which caches are searched first when getting data. Set and clear operations are always performed asynchronously

## Memory
Methods: [set](./src/units/save-to-memory.js) | [get](./src/units/get-from-memory.js) | [clear](./src/units/clear-memory.js)

Enabled by default

The `memory` cache type stores data within an in-memory object. This data object can be made mutable with the `memory.mutable` option, meaning the data can be changed from outside the cache. The `memory.static` option can be set to use a static memory store that can share information between cache instances

## File - Enabled by default
Methods: [set](./src/units/save-to-file.js) | [get](./src/units/get-from-file.js) | [clear](./src/units/clear-file.js)

Enabled by default

The `file` cache type stores data in the local file system. By default, files will be stored alongside the module's install location (typically within the `node_moduels` directory). Use the `file.root` configuration to define your own cache directory. It is recommended that absolute paths are used. If a relative path is provided, the path will be made relative to the current working directory. Note that this cache type **will alter** files not made by this module

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