cache-base
Version:
Basic object cache with `get`, `set`, `del`, and `has` methods for node.js/javascript projects.
442 lines (301 loc) • 12.4 kB
Markdown
# cache-base [](https://www.npmjs.com/package/cache-base) [](https://npmjs.org/package/cache-base) [](https://npmjs.org/package/cache-base) [](https://travis-ci.org/jonschlinkert/cache-base)
> Basic object cache with `get`, `set`, `del`, and `has` methods for node.js/javascript projects.
Please consider following this project's author, [Jon Schlinkert](https://github.com/jonschlinkert), and consider starring the project to show your :heart: and support.
- [Install](#install)
- [Quickstart](#quickstart)
- [API](#api)
- [Usage examples](#usage-examples)
- [About](#about)
_(TOC generated by [verb](https://github.com/verbose/verb) using [markdown-toc](https://github.com/jonschlinkert/markdown-toc))_
## Install
Install with [npm](https://www.npmjs.com/):
```sh
$ npm install --save cache-base
```
## Quickstart
```js
const CacheBase = require('cache-base');
const app = new CacheBase();
app.set('a.b', 'c');
console.log(app.cache.a); //=> { b: 'c' }
console.log(app.cache.a.b); //=> 'c'
console.log(app.get('a')); //=> { b: 'c' }
console.log(app.get('a.b')); //=> 'c'
```
More [usage examples](#usage-examples) below.
## API
**Params**
* `prop` **{String|Object}**: (optional) Property name to use for the cache, or the object to initialize with.
* `cache` **{Object}**: (optional) An object to initialize with.
**Example**
```js
const app = new CacheBase();
```
### [.set](index.js#L65)
Assign `value` to `key`. Also emits `set` with the key and value.
**Params**
* `key` **{String|Array}**: The name of the property to set. Dot-notation may be used to set nested properties.
* `value` **{any}**
* `returns` **{Object}**: Returns the instance for chaining.
**Events**
* `emits`: `set` with `key` and `value` as arguments.
**Example**
```js
app.on('set', function(key, val) {
// do something when `set` is emitted
});
app.set('admin', true);
// also takes an object or an array of objects
app.set({ name: 'Brian' });
app.set([{ foo: 'bar' }, { baz: 'quux' }]);
console.log(app);
//=> { name: 'Brian', foo: 'bar', baz: 'quux' }
```
### [.get](index.js#L90)
Return the value of `key`.
**Params**
* `key` **{String|Array}**: The name of the property to get. Dot-notation may be used to set nested properties.
* `returns` **{any}**: Returns the value of `key`
**Events**
* `emits`: `get` with `key` and `value` as arguments.
**Example**
```js
app.set('a.b.c', 'd');
app.get('a.b');
//=> { c: 'd' }
```
### [.prime](index.js#L120)
Create a property on the cache with the given `value` only if it doesn't already exist.
**Params**
* `key` **{String}**: Property name or object path notation.
* `val` **{any}**
* `returns` **{Object}**: Returns the instance for chaining.
**Example**
```js
console.log(app.cache); //=> {}
app.set('one', { foo: 'bar' });
app.prime('one', { a: 'b' });
app.prime('two', { c: 'd' });
console.log(app.cache.one); //=> { foo: 'bar' }
console.log(app.cache.two); //=> { c: 'd' }
```
### [.default](index.js#L162)
Set a default value to be used when `.get()` is called and the value is not defined on the cache. Returns a value from the defaults when only a key is passed.
**Params**
* `key` **{String|Array}**: The name of the property to set. Dot-notation may be used to set nested properties.
* `value` **{any}**: (optional) The value to set on the defaults object.
* `returns` **{Object}**: Returns the instance for chaining.
**Example**
```js
app.set('foo', 'xxx');
app.default('foo', 'one');
app.default('bar', 'two');
app.default('baz', 'three');
app.set('baz', 'zzz');
console.log(app.get('foo'));
//=> 'xxx'
console.log(app.get('bar'));
//=> 'two'
console.log(app.get('baz'));
//=> 'zzz'
console.log(app);
// CacheBase {
// cache: { foo: 'xxx', bar: 'two', baz: 'zzz' },
// defaults: { foo: 'one', bar: 'two', baz: 'three' } }
```
### [.union](index.js#L199)
Set an array of unique values on cache `key`.
**Params**
* `key` **{String|Array}**: The name of the property to union. Dot-notation may be used to set nested properties.
* `value` **{any}**
* `returns` **{Object}**: Returns the instance for chaining.
**Example**
```js
app.union('a.b.c', 'foo');
app.union('a.b.c', 'bar');
app.union('a.b.c', ['bar', 'baz']);
console.log(app.get('a'));
//=> { b: { c: ['foo', 'bar', 'baz'] } }
```
### [.has](index.js#L223)
Return true if the value of property `key` is not `undefined`.
**Params**
* `key` **{String|Array}**: The name of the property to check. Dot-notation may be used to set nested properties.
* `returns` **{Boolean}**
**Example**
```js
app.set('foo', true);
app.set('baz', null);
app.set('bar', undefined);
app.has('foo'); //=> true
app.has('bar'); //=> true
app.has('baz'); //=> false
```
### [.hasOwn](index.js#L253)
Returns true if the specified property is an own (not inherited) property. Similar to [.has()](#has), but returns true if the key exists, even if the value is `undefined`.
**Params**
* `key` **{String}**
* `returns` **{Boolean}**: Returns true if object `key` exists. Dot-notation may be used to set nested properties.
**Example**
```js
app.set('a.b.c', 'd');
app.set('x', false);
app.set('y', null);
app.set('z', undefined);
app.hasOwn('a'); //=> true
app.hasOwn('b'); //=> true
app.hasOwn('c'); //=> true
app.hasOwn('a.b.c'); //=> true
app.hasOwn('x'); //=> true
app.hasOwn('y'); //=> true
app.hasOwn('z'); //=> true
app.hasOwn('lslsls'); //=> false
```
### [.del](index.js#L278)
Delete one or more properties from the instance.
**Params**
* `key` **{String|Array}**: The name of the property to delete. Dot-notation may be used to set nested properties.
* `returns` **{Object}**: Returns the instance for chaining.
**Events**
* `emits`: `del` with the `key` as the only argument.
**Example**
```js
// setup a listener to update a property with a default
// value when it's deleted by the user
app.on('del', key => app.set(key, app.default(key)));
app.del(); // delete all properties on the cache
// or
app.del('foo');
// or an array of keys
app.del(['foo', 'bar']);
```
### [.clear](index.js#L301)
Reset the entire cache to an empty object. Note that this does not also clear the `defaults` object, since you can manually do `cache.defaults = {}` if you want to reset that object as well.
**Example**
```js
// clear "defaults" whenever the cache is cleared
app.on('clear', key => (app.defaults = {}));
app.clear();
```
### [.visit](index.js#L318)
Visit (or map visit) the specified method (`key`) over the properties in the
given object or array.
**Params**
* `key` **{String|Array}**: The name of the method to visit.
* `val` **{Object|Array}**: The object or array to iterate over.
* `returns` **{Object}**: Returns the instance for chaining.
### [.keys](index.js#L338)
Gets an array of names of all enumerable properties on the cache.
**Example**
```js
const app = new CacheBase();
app.set('user', true);
app.set('admin', false);
console.log(app.keys);
//=> ['user', 'admin']
```
### [.size](index.js#L357)
Gets the length of [keys](#keys).
**Example**
```js
const app = new CacheBase();
app.set('user', true);
app.set('admin', false);
console.log(app.size);
//=> 2
```
## Usage examples
**Create an instance of cache-base**
```js
const app = new CacheBase();
app.set('a', 'b');
app.set('c.d', 'e');
console.log(app.get('a'));
//=> 'b'
console.log(app.get('c'));
//=> { d: 'e' }
console.log(app);
//=> CacheBase { a: 'b' }
```
**Initialize with an object**
```js
const app = new CacheBase({ a: 'b', c: { d: 'e' } });
console.log(app.get('a'));
//=> 'b'
console.log(app.get('c'));
//=> { d: 'e' }
console.log(app.get('c.d'));
//=> 'e'
console.log(app);
//=> CacheBase { cache: { a: 'b' } }
```
**Inherit**
```js
class MyApp extends CacheBase {}
const app = new MyApp();
app.set('a', 'b');
app.set('c', 'd');
console.log(app.get('a'));
//=> 'b'
console.log(app);
//=> MyApp { cache: { a: 'b', c: 'd' } }
```
**Custom namespace**
Pass a string as the first value to the contructor to define a custom property name to use for the cache. By default values are stored on the `cache` property.
```js
const CacheBase = require('cache-base');
const app = new CacheBase('data', { a: 'b' });
app.set('c.d', 'e');
// get values
console.log(app.get('a'));
//=> 'b'
console.log(app.get('c'));
//=> { d: 'e' }
console.log(app.data);
//=> { a: 'b', c: { d: 'e' } }
console.log(app);
//=> CacheBase { data: { a: 'b', c: { d: 'e' } } }
```
## About
<details>
<summary><strong>Contributing</strong></summary>
Pull requests and stars are always welcome. For bugs and feature requests, [please create an issue](../../issues/new).
</details>
<details>
<summary><strong>Running Tests</strong></summary>
Running and reviewing unit tests is a great way to get familiarized with a library and its API. You can install dependencies and run tests with the following command:
```sh
$ npm install && npm test
```
</details>
<details>
<summary><strong>Building docs</strong></summary>
_(This project's readme.md is generated by [verb](https://github.com/verbose/verb-generate-readme), please don't edit the readme directly. Any changes to the readme must be made in the [.verb.md](.verb.md) readme template.)_
To generate the readme, run the following command:
```sh
$ npm install -g verbose/verb#dev verb-generate-readme && verb
```
</details>
### Related projects
You might also be interested in these projects:
* [base-methods](https://www.npmjs.com/package/base-methods): base-methods is the foundation for creating modular, unit testable and highly pluggable node.js applications, starting… [more](https://github.com/jonschlinkert/base-methods) | [homepage](https://github.com/jonschlinkert/base-methods "base-methods is the foundation for creating modular, unit testable and highly pluggable node.js applications, starting with a handful of common methods, like `set`, `get`, `del` and `use`.")
* [get-value](https://www.npmjs.com/package/get-value): Use property paths like 'a.b.c' to get a nested value from an object. Even works… [more](https://github.com/jonschlinkert/get-value) | [homepage](https://github.com/jonschlinkert/get-value "Use property paths like 'a.b.c' to get a nested value from an object. Even works when keys have dots in them (no other dot-prop library can do this!).")
* [has-value](https://www.npmjs.com/package/has-value): Returns true if a value exists, false if empty. Works with deeply nested values using… [more](https://github.com/jonschlinkert/has-value) | [homepage](https://github.com/jonschlinkert/has-value "Returns true if a value exists, false if empty. Works with deeply nested values using object paths.")
* [option-cache](https://www.npmjs.com/package/option-cache): Simple API for managing options in JavaScript applications. | [homepage](https://github.com/jonschlinkert/option-cache "Simple API for managing options in JavaScript applications.")
* [set-value](https://www.npmjs.com/package/set-value): Create nested values and any intermediaries using dot notation (`'a.b.c'`) paths. | [homepage](https://github.com/jonschlinkert/set-value "Create nested values and any intermediaries using dot notation (`'a.b.c'`) paths.")
* [unset-value](https://www.npmjs.com/package/unset-value): Delete nested properties from an object using dot notation. | [homepage](https://github.com/jonschlinkert/unset-value "Delete nested properties from an object using dot notation.")
### Contributors
| **Commits** | **Contributor** |
| --- | --- |
| 67 | [jonschlinkert](https://github.com/jonschlinkert) |
| 2 | [wtgtybhertgeghgtwtg](https://github.com/wtgtybhertgeghgtwtg) |
### Author
**Jon Schlinkert**
* [LinkedIn Profile](https://linkedin.com/in/jonschlinkert)
* [GitHub Profile](https://github.com/jonschlinkert)
* [Twitter Profile](https://twitter.com/jonschlinkert)
### License
Copyright © 2018, [Jon Schlinkert](https://github.com/jonschlinkert).
Released under the [MIT License](LICENSE).
***
_This file was generated by [verb-generate-readme](https://github.com/verbose/verb-generate-readme), v0.6.0, on March 23, 2018._