<commit_before># cherish

[![npm version](https://badge.fury.io/js/cherish.svg)](http://badge.fury.io/js/cherish) [![Build Status](https://travis-ci.org/mieky/cherish.svg?branch=master)](https://travis-ci.org/mieky/cherish)

A minimal in-memory cache wrapper for all kinds of function calls. Tiny footprint, no runtime dependencies!

Useful for e.g. effortless caching of API calls with [node-fetch](https://github.com/bitinn/node-fetch).

Requires **Node 4.0** or newer, with npm 3.

## Installation

```
npm install --save cherish
```

Run tests with:

```
npm run test
```

## Getting started

`const myCachedFunction = cherish(myFunction, [options]);`

Simply wrap your function with `cherish(myFunction)`, and it will return you the same result for each subsequent function call with the same arguments.

By design, **you will always get back a Promise**. This is the same regardless of the type of your wrapped function.

### Options
You can specify the following options:

- `ttl`: how long to remember the results, in seconds (default: `300`)
- `get`: custom cache getter
- `set`: custom cache setter



## Usage examples

Remember results for specific arguments (same result with same arguments):

```js
const cherish = require("cherish");

function generateParticipantNumber(name) {
    return `${name} gets ${Math.round(Math.random() * 100)}`;
};

const rememberNumber = cherish(generateParticipantNumber);
const printResult = res => console.log(res);

rememberNumber("Alice").then(printResult); // "Alice gets 52"
rememberNumber("Bob").then(printResult);   // "Bob gets 74"
rememberNumber("Alice").then(printResult); // "Alice gets 52"
```

Remember the generated random number, but only for a second:
```js
const cherish = require("cherish");

function getRandomNumber() {
    return Math.round(Math.random() * 5000);
}

// Remember all calls to getRandomNumber() for one second
const promiseRandomNumber = cherish(getRandomNumber, { ttl: 1 });

// First calls will print the same result...
const printResult = res => console.log(res);
promiseRandomNumber().then(printResult);
promiseRandomNumber().then(printResult);
promiseRandomNumber().then(printResult);

// Try again after the cache has invalidated!
setTimeout(() => {
    console.log("Two seconds have passed!");
    promiseRandomNumber().then(printResult);
}, 2000);

// 264
// 264
// 264
// Two seconds have passed!
// 1296
```

You will get more output for debugging if you set the environment variable `DEBUG` to any non-falsy value.

## Changelog

- **0.4.0** Support argument-based caching.
- **0.3.0** Add backwards compatibility for Node 4.
- **0.2.0** Support anonymous functions, add basic tests.
- **0.1.1** Fix for properly handling unfinished calls.
- **0.1.0** First release.

## Acknowledgments

[![chilicorn](chilicorn.png)](http://futurice.com/blog/sponsoring-free-time-open-source-activities)

## License

[MIT](https://github.com/mieky/cherish/blob/master/LICENSE)<commit_msg>Update readme in preparation for 1.0<commit_after># cherish

[![npm version](https://badge.fury.io/js/cherish.svg)](http://badge.fury.io/js/cherish) [![Build Status](https://travis-ci.org/mieky/cherish.svg?branch=master)](https://travis-ci.org/mieky/cherish)

A simple, easy cache wrapper for all kinds of function calls. Tiny footprint, no runtime dependencies!

Effortless to use in all kinds of scenarios. Defaults to an in-memory database, but is easily set up to use e.g. with [node-localstorage](https://github.com/lmaccherone/node-localstorage) to persist results to disk.

The perfect companion for caching API calls made with [node-fetch](https://github.com/bitinn/node-fetch)!

## Installation

Requires **Node 4.0** or newer, with npm 3.

```
npm install --save cherish
```

Run tests with:

```
npm run test
```

## Getting started

Simply wrap your function with `cherish(myFunction)`, and it will return you the same result for each subsequent function call with the same arguments:

```js
const cherish = require("cherish");
const myCachedFunction = cherish(myFunction);
```

By design, **you will always get back a Promise**. This is the same regardless of the type of your wrapped function.

### Options

You can specify the following options:

- `ttl`: how long to remember the results, in seconds (default: `300`)
- `get`: custom cache getter (requires both get and set to work)
- `set`: custom cache setter (requires both get and set to work)

For more information, see [usage examples](#usage-examples) below.

You will get more output for debugging if you set the environment variable `DEBUG` to any non-falsy value.

## Usage examples

### Remember results for specific arguments (same result with same arguments):

```js
const cherish = require("cherish");

function generateParticipantNumber(name) {
    return `${name} gets ${Math.round(Math.random() * 100)}`;
};

const rememberNumber = cherish(generateParticipantNumber);
const printResult = res => console.log(res);

rememberNumber("Alice").then(printResult); // "Alice gets 52"
rememberNumber("Bob").then(printResult);   // "Bob gets 74"
rememberNumber("Alice").then(printResult); // "Alice gets 52"
```

### Remember the generated random number, but only for a second:

```js
function getRandomNumber() {
    return Math.round(Math.random() * 5000);
}

// Remember all calls to getRandomNumber() for one second
const promiseRandomNumber = cherish(getRandomNumber, { ttl: 1 });

// First calls will print the same result...
const printResult = res => console.log(res);
promiseRandomNumber().then(printResult);
promiseRandomNumber().then(printResult);
promiseRandomNumber().then(printResult);

// Try again after the cache has invalidated!
setTimeout(() => {
    console.log("Two seconds have passed!");
    promiseRandomNumber().then(printResult);
}, 2000);

// 264
// 264
// 264
// Two seconds have passed!
// 1296
```

### Specify a custom cache implementation

Here's the straightforward way of using node-localstorage to persist query results to disk:

```js
const localStorage = require("node-localstorage").LocalStorage("./cache");

const fetchTrelloURLCached = cherish(fetchTrelloURL, {
    ttl: 3600,
    get: key => JSON.parse(localStorage.getItem(key)),
    set: (key, value) => localStorage.setItem(key, JSON.stringify(value))
});
```


## Changelog

- **1.0.0** Support customizable storage.
    - CHANGED: initialization syntax, the second argument `ttlSeconds` should be now passed in the options, for example: `cherish(myFunction, { ttl: 60 })`
    - It's now ossible to define a custom cache instead of the default in-memory cache by specifying the `get` and `set` options upon [initialization](#options).

- **0.4.0** Support argument-based caching.
- **0.3.0** Add backwards compatibility for Node 4.
- **0.2.0** Support anonymous functions, add basic tests.
- **0.1.1** Fix for properly handling unfinished calls.
- **0.1.0** First release.

## Acknowledgments

[![chilicorn](chilicorn.png)](http://futurice.com/blog/sponsoring-free-time-open-source-activities)

## License

[MIT](https://github.com/mieky/cherish/blob/master/LICENSE)
{'fraction_non_alphanumeric': 0.13637644406875177, 'fraction_numerical': 0.016483516483516484, 'mean_word_length': 4.688301282051282, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 11, 'https://': 11, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '996796', 'n_tokens_mistral': 2257, 'n_tokens_neox': 2087, 'n_words': 710}