# gulp-cache

> A cache proxy plugin for Gulp

Latest version **1.1.3** (published 2019-08-10) · MIT license · 0 weekly downloads

## Install

```sh
npm install gulp-cache
pnpm add gulp-cache
yarn add gulp-cache
bun add gulp-cache
```

## Health

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

Positive: has types package; no vulnerabilities.

Warnings: low downloads; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.1.3 |
| Published | 2019-08-10 |
| First published | 2014-01-11 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | separate (@types/gulp-cache) |
| Module format | CommonJS |
| Node | >=8.0.0 |
| Dependencies | 7 |
| Unpacked size | 57.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 132 |
| Author | Jacob Gable |
| Maintainers | dangreen, jgable, shinnn |
| Keywords | gulpplugin, gulp, cache |

## Links

- npm: https://www.npmjs.com/package/gulp-cache
- Repository: https://github.com/jgable/gulp-cache
- Issues: https://github.com/jgable/gulp-cache/issues
- npm.io page: https://npm.io/package/gulp-cache

## Dependencies (7)

- [vinyl](https://npm.io/package/vinyl.md) ^2.2.0
- [core-js](https://npm.io/package/core-js.md) 3
- [through2](https://npm.io/package/through2.md) 3.0.1
- [cache-swap](https://npm.io/package/cache-swap.md) ^0.3.0
- [object.pick](https://npm.io/package/object.pick.md) ^1.3.0
- [plugin-error](https://npm.io/package/plugin-error.md) ^1.0.1
- [@babel/runtime](https://npm.io/package/@babel/runtime.md) ^7.5.5

## 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.3 (latest) — 2019-08-10
- 1.1.2 — 2019-06-08
- 1.1.1 — 2019-01-23
- 1.1.0 — 2019-01-07
- 1.0.2 — 2017-12-30
- 1.0.1 — 2017-11-03
- 1.0.0 — 2017-11-03
- 0.5.0 — 2017-10-18
- 0.4.6 — 2017-03-02
- 0.4.5 — 2016-05-11
- 0.4.4 — 2016-04-08
- 0.4.3 — 2016-03-16
- 0.4.2 — 2016-02-01
- 0.4.1 — 2015-11-28
- 0.4.0 — 2015-11-03
- … 28 more at https://npm.io/package/gulp-cache/versions

## README

# gulp-cache

[![NPM version][npm]][npm-url]
[![Node version][node]][node-url]
[![Dependencies status][deps]][deps-url]
[![Build status][build]][build-url]
[![Coverage status][coverage]][coverage-url]

[npm]: https://img.shields.io/npm/v/gulp-cache.svg
[npm-url]: https://www.npmjs.com/package/gulp-cache

[node]: https://img.shields.io/node/v/gulp-cache.svg
[node-url]: https://nodejs.org

[deps]: https://img.shields.io/david/jgable/gulp-cache.svg
[deps-url]: https://david-dm.org/jgable/gulp-cache

[build]: https://travis-ci.org/jgable/gulp-cache.svg?branch=master
[build-url]: https://travis-ci.org/jgable/gulp-cache

[coverage]: https://img.shields.io/coveralls/jgable/gulp-cache.svg
[coverage-url]: https://coveralls.io/r/jgable/gulp-cache

A temp file based caching proxy task for [gulp](http://gulpjs.com/).

## Install

```bash
npm i -D gulp-cache
# or
yarn add -D gulp-cache
```

## Usage

```js
import gulp from 'gulp';
import favicons from 'gulp-favicons';
import srcset from 'gulp-srcset';
import cache from 'gulp-cache';

gulp.task('favicon', () =>
    gulp.src('src/favicon.svg')
        .pipe(cache(
            // Target plugin, the output of which will be cached.
            favicons(faviconsConfig),
            // Options for `gulp-cache` plugin.
            {
                // Bucket to store favicons in cache.
                name: 'favicons'
            }
        ))
        .pipe(gulp.dest('./favicons'))
);

gulp.task('images', () =>
    gulp.src('src/**/*.{jpg,png,svg}')
        .pipe(cache(
            // Target plugin, the output of which will be cached.
            srcset(srcsetRules),
            // Options for `gulp-cache` plugin.
            {
                // Bucket to store images in cache.
                name: 'images'
            }
        ))
        .pipe(gulp.dest('./images'))
);
```

<details>
    <summary>Complex usage example</summary>

```js
import fs from 'fs';
import gulp from 'gulp';
import jshint from 'gulp-jshint';
import cache from 'gulp-cache';

const jsHintVersion = '2.4.1';
const jshintOptions = fs.readFileSync('.jshintrc');

function makeHashKey(file) {
    // Key off the file contents, jshint version and options
    return `${file.contents.toString('utf8')}${jshintVersion}${jshintOptions}`;
}

gulp.task('lint', () =>
    gulp.src('src/**/*.js')
        .pipe(cache(
            // Target plugin, the output of which will be cached.
            jshint('.jshintrc'),
            // Options for `gulp-cache` plugin.
            {
                key: makeHashKey,
                // What on the result indicates it was successful
                success(jshintedFile) {
                    return jshintedFile.jshint.success;
                },
                // What to store as the result of the successful action
                value(jshintedFile) {
                    // Will be extended onto the file object on a cache hit next time task is ran
                    return {
                        jshint: jshintedFile.jshint
                    };
                }
            }
        ))
        .pipe(jshint.reporter('default'))
});
```

</details>

## API

### `cache(pluginToCache [, options])`

#### `pluginToCache`

Target plugin, the output of which will be cached.

#### `options`

Options for `gulp-cache` plugin.

##### `options.fileCache`

> [Optional] Where to store the cache objects

- Defaults to `new Cache({ cacheDirName: 'gulp-cache' })`

- Create your own with [`new cache.Cache({ cacheDirName: 'custom-cache' })`](https://github.com/jgable/cache-swap)

##### `options.name`

> [Optional] The name of the bucket which stores the cached objects

- Defaults to `default`

##### `options.key`

> [Optional] What to use to determine the uniqueness of an input file for this task.

- Can return a string or a `Promise` that resolves to a string.  

- The result of this method is converted to a unique MD5 hash automatically; no need to do this yourself.

- Defaults to `file.contents` if a Buffer, or `undefined` if a Stream.

##### `options.success`

> [Optional] How to determine if the resulting file was successful.

- Must return a truthy value that is used to determine whether to cache the result of the task. `Promise` is supported.

- Defaults to true, so any task results will be cached.

##### `options.value`

> [Optional] What to store as the cached result of the task.

- Can be a function that returns an Object or a `Promise` that resolves to an Object.

- Can also be set to a string that will be picked of the task result file.

- The result of this method is run through `JSON.stringify` and stored in a temp file for later retrieval.

- Defaults to `'contents'` which will grab the resulting file.contents and store them as a string.

## Clearing the cache

If you find yourself needing to clear the cache, there is a handy dandy `cache.clearAll()` method:

```js
import cache from 'gulp-cache';

gulp.task('clear', () =>
    cache.clearAll()
);
```

You can then run it with `gulp clear`.

## One-to-many caching

To support one-to-many caching in Your Gulp-plugin, you should:

* Use `clone` method, to save `_cachedKey` property:
```js
const outputFile1 = inputFile.clone({ contents: false });
const outputFile2 = inputFile.clone({ contents: false });

outputFile1.contents = new Buffer(...);
outputFile2.contents = new Buffer(...);

const outputFiles = [
    outputFile1,
    outputFile2,
    ...
];
```
* Or, do it manually:
```js
const outputFiles = [
    new Vinyl({..., _cachedKey: inputFile._cachedKey}),
    new Vinyl({..., _cachedKey: inputFile._cachedKey}),
    ...
];
```

## License

[The MIT License (MIT)](./LICENSE)

Copyright (c) 2014 - present [Jacob Gable](http://jacobgable.com)

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