# stash-it-plugin-debug

> Debug plugin for stash-it.

Latest version **2.0.0-rc.3** (published 2018-07-05) · MIT license · 0 weekly downloads

## Install

```sh
npm install stash-it-plugin-debug
pnpm add stash-it-plugin-debug
yarn add stash-it-plugin-debug
bun add stash-it-plugin-debug
```

## 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 | 2.0.0-rc.3 |
| Published | 2018-07-05 |
| First published | 2017-07-31 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 1 |
| Unpacked size | 14.2 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | Jacek Smolak |
| Maintainers | jaceks |
| Keywords | cache, plugin, debug, stash-it |

## Links

- npm: https://www.npmjs.com/package/stash-it-plugin-debug
- Repository: https://github.com/smolak/stash-it-plugin-debug
- Homepage: https://github.com/smolak/stash-it-plugin-debug#readme
- Issues: https://github.com/smolak/stash-it-plugin-debug/issues
- npm.io page: https://npm.io/package/stash-it-plugin-debug

## Dependencies (1)

- [ramda](https://npm.io/package/ramda.md) ^0.25.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

- 2.0.0-rc.3 (latest) — 2018-07-05
- 2.0.0-rc.2 — 2018-06-04
- 2.0.0-rc.1 — 2018-05-15
- 1.1.1 — 2017-09-19
- 1.1.0 — 2017-08-08
- 1.0.2 — 2017-08-08
- 1.0.1 — 2017-08-06
- 1.0.0 — 2017-07-31

## README

![logo-stash-it-color-dark 2x](https://user-images.githubusercontent.com/1819138/30385483-99fd209c-98a7-11e7-85e2-595791d8d894.png)

# stash-it-plugin-debug

[![build status](https://img.shields.io/travis/smolak/stash-it-plugin-debug/master.svg?style=flat-square)](https://travis-ci.org/smolak/stash-it-plugin-debug)
[![Coverage Status](https://coveralls.io/repos/github/smolak/stash-it-plugin-debug/badge.svg?branch=master)](https://coveralls.io/github/smolak/stash-it-plugin-debug?branch=master)

Debug plugin for [stash-it](https://www.npmjs.com/package/stash-it).

This module is best used in development. It helps finding out what is
set in cache and how this data changes (or not) upon any action taken.

It also provides a method to run diagnostics against used storage.
Diagnostics include adding, checking, modifying, removing data in cache
to see if stash-it works with given storage without any problems.

## Installation

```sh
npm install stash-it-plugin-debug --save-dev
```

## Usage

##### Installation

```javascript
import { createCache } from 'stash-it';
import createMemoryAdapter from 'stash-it-adapter-memory'; // you can use any adapter you like
import createDebugPlugin from 'stash-it-plugin-debug';

const adapter = createMemoryAdapter({ namespace: 'someNamespace' });
const cache = createCache(adapter);

// I am using console.log here, but you are free to use any callback /
// logger you want. Checkout API section for more info.
const logger = console.log;
const debugPlugin = createDebugPlugin(logger);
const cacheWithPlugins = cache.registerPlugins([ debugPlugin ]);
```

##### Usage example 1:

```javascript
cacheWithPlugins.setItem('key', 'value');
```

This will log few informations about cache instance and data flow throughout `setItem`'s lifecycle, those will be: preSetItem, preBuildKey, postBuildKey, postSetItem.

Any other method used (getItem, hasItem, removeItem, ...) will produce similar logs with data flow for their lifecycle.

What are lifecycles? See the [lifecycle of methods docs](https://jaceks.gitbooks.io/stash-it/content/advanced-usage/lifecycle-of-methods.html).

##### Usage example 2:

```javascript
cacheWithPlugins.runDiagnostics('key', 'value', { some: 'extraData' });
```

This will log many times as well checking if, for used adapter, all base actions work and cache is capable of setting, getting, checking for existence and removing things from storage used by adapter.

It's recommended to run this before given storage will be used.

## API

### createDebugPlugin(callback, withCacheInstance = false)

Calling this method will return a plugin, ready to use with `stash-it`.

What is a plugin, and how do you write one? Checkout the
[plugins](https://jaceks.gitbooks.io/stash-it/content/advanced-usage/plugins.html)
docs.

#### callback

`callback` needs to be passed as a function. That function will be passed
one argument upon each call. Passed argument will be either and object or a string.

##### For hooks

For hooks, it will be passed objects with data that is passed through stash-it's
lifecycle methods. Object consists of two properties:

 - `event` - that holds the event name, e.g. `preSetItem`
 - `args` - arguments that are passed to that event's handler

Whole object will look like this:

```javascript
{
    event: 'eventName',
    args: { ... }
}
```


For instance. If you use `console.log` as a callback,
for hooks, for `setItem` method, you should see something like:

```sh
{ event: 'preSetItem',
  args: { key: 'key', value: 'value', extra: {} } }
{ event: 'preBuildKey', args: { key: 'key' } }
{ event: 'postBuildKey', args: { key: 'namespace.key' } }
{ event: 'postSetItem',
  args:
   { key: 'key',
     value: 'value',
     extra: {},
     item:
      { key: 'namespace.key',
        value: 'value',
        namespace: 'namespace',
        extra: {} } } }
```

As `setItem` uses internally `buildKey` method and all methods have
`pre` and `post` events, that is why you can see logging of `preBuildKey` and `postBuildKey` and data passed to handlers of those events.

See [lifecycle of setItem](https://jaceks.gitbooks.io/stash-it/content/api/cacheinstance.html#setitemkey-value-extra) method for more information.


##### For runDiagnostics

For `runDiagnostics` it will be passed a string with information about
given step runDiagnostics performs. For example, this is how the whole
diagnostics report might look like:

```
(1/9) Item set successfully.
(2/9) Item is present in cache.
(3/9) Item got from cache successfully.
(4/9) Items are equal.
(5/9) Extra got from cache successfully.
(6/9) Extra added to cache successfully.
(7/9) Extra set in cache successfully.
(8/9) Item removed successfully.
(9/9) Item is not present in cache.
Finished: SUCCESS.
```

Should any step fail, you will be told so and the last argument to the
callback will be `Funished: FAILURE.`.

#### withCacheInstance = false

By default `cacheInstance` property passed in `args` will not be logged.
That is because it is, in most - if not all - cases, not needed.

If you need to log the `cacheInstance` object simply pass this argument as `true` when creating the plugin.


## Tips and tricks

As the very same callback is used for both `hooks` and `runDiagnostics`,
and as runDiagnostics runs all of the methods, then each method will
produce logging of `{ event, args }` data as well - that could result in a very, very long data log.

Let's say that you only need to check if storage works, but you don't want to see logs for events and their handlers.

For that, you need to pass a more robust callback. Here is one:

```javascript
const callback = (value) => {
    // remember that runDiagnostics passes string to callback
    if (typeof value === 'string') {
        console.log(value);
    }
};
```

And also, the other way around. If you don't want to log `event` and `args`, but only part of that data, you can do it as well. Here's how:

```javascript
const callback = (value) => {
    if (typeof value === 'object') {
        // log whatever you want from either value.event or value.args
    }
};
```

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