cache-base
Advanced tools
Comparing version 2.0.2 to 3.0.0
@@ -36,2 +36,9 @@ # Release history | ||
## [3.0.0] - 2018-01-27 | ||
**Changed** | ||
- adds `.prime()` and `.default()` methods | ||
## [2.0.0] - 2017-12-17 | ||
@@ -44,2 +51,3 @@ | ||
## [1.0.1] - 2017-07-22 | ||
@@ -49,6 +57,3 @@ | ||
## [1.0.0] - 2017-02-25 | ||
- | ||
## [0.8.5] - 2017-02-25 | ||
@@ -121,3 +126,2 @@ | ||
- first commit | ||
- remove namespace stuff | ||
@@ -129,2 +133,6 @@ - update fixtures | ||
## 0.1.0 | ||
- first commit | ||
[2.0.0]: https://github.com/jonschlinkert/cache-base/compare/1.0.1...2.0.0 | ||
@@ -131,0 +139,0 @@ [1.0.1]: https://github.com/jonschlinkert/cache-base/compare/1.0.0...1.0.1 |
358
index.js
'use strict'; | ||
const isObject = require('isobject'); | ||
const typeOf = require('kind-of'); | ||
const Emitter = require('@sellside/emitter'); | ||
const visit = require('collection-visit'); | ||
const hasOwn = require('has-own-deep'); | ||
const union = require('union-value'); | ||
@@ -12,9 +13,9 @@ const del = require('unset-value'); | ||
/** | ||
* Create a new `Cache`. Internally the `Cache` constructor is created using | ||
* the `namespace` function, with `cache` defined as the storage object. | ||
* Create an instance of `CacheBase`. | ||
* | ||
* ```js | ||
* const cache = new Cache(); | ||
* const app = new CacheBase(); | ||
* ``` | ||
* @param {Object} `cache` Optionally pass an object to initialize with. | ||
* @param {String|Object} `prop` (optional) Property name to use for the cache, or the object to initialize with. | ||
* @param {Object} `cache` (optional) An object to initialize with. | ||
* @constructor | ||
@@ -24,13 +25,14 @@ * @api public | ||
class Cache extends Emitter { | ||
class CacheBase extends Emitter { | ||
constructor(prop, cache) { | ||
super(); | ||
if (typeof prop === 'string') { | ||
Reflect.defineProperty(this, 'prop', { value: prop }); | ||
this[this.prop] = {}; | ||
} else { | ||
if (typeof prop !== 'string') { | ||
cache = prop || cache; | ||
prop = 'cache'; | ||
} | ||
Reflect.defineProperty(this, 'prop', { value: prop }); | ||
this[this.prop] = {}; | ||
if (cache) { | ||
@@ -42,22 +44,20 @@ this.set(cache); | ||
/** | ||
* Assign `value` to `key`. Also emits `set` with | ||
* the key and value. | ||
* Assign `value` to `key`. Also emits `set` with the key and value. | ||
* | ||
* ```js | ||
* cache.on('set', function(key, val) { | ||
* app.on('set', function(key, val) { | ||
* // do something when `set` is emitted | ||
* }); | ||
* | ||
* cache.set(key, value); | ||
* app.set('admin', true); | ||
* | ||
* // also takes an object or array | ||
* cache.set({name: 'Halle'}); | ||
* cache.set([{foo: 'bar'}, {baz: 'quux'}]); | ||
* console.log(cache); | ||
* //=> {name: 'Halle', foo: 'bar', baz: 'quux'} | ||
* // 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' } | ||
* ``` | ||
* | ||
* @name .set | ||
* @emits `set` with `key` and `value` as arguments. | ||
* @param {String|Array} `key` The name of the property to set. Dot-notation or an array of object path segments may be used. | ||
* @param {String|Array} `key` The name of the property to set. Dot-notation may be used to set nested properties. | ||
* @param {any} `value` | ||
@@ -68,12 +68,9 @@ * @return {Object} Returns the instance for chaining. | ||
set(key, val) { | ||
if (Array.isArray(key) && arguments.length === 2) { | ||
key = key.join('.'); | ||
} | ||
set(key, ...rest) { | ||
if (isObject(key) || Array.isArray(key)) { | ||
this.visit('set', key); | ||
} else { | ||
set(this.prop ? this[this.prop] : this, key, val); | ||
this.emit('set', key, val); | ||
return this.visit('set', key, ...rest); | ||
} | ||
set(this[this.prop], key, ...rest); | ||
this.emit('set', key, ...rest); | ||
return this; | ||
@@ -83,14 +80,42 @@ } | ||
/** | ||
* Union `array` to `key`. Also emits `set` with | ||
* the key and value. | ||
* Return the value of `key`. | ||
* | ||
* ```js | ||
* cache.union('a.b', ['foo']); | ||
* cache.union('a.b', ['bar']); | ||
* console.log(cache.get('a')); | ||
* //=> {b: ['foo', 'bar']} | ||
* app.set('a.b.c', 'd'); | ||
* app.get('a.b'); | ||
* //=> { c: 'd' } | ||
* ``` | ||
* @name .union | ||
* @param {String|Array} `key` The name of the property to union. Dot-notation or an array of object path segments may be used. | ||
* @param {any} `value` | ||
* @name .get | ||
* @emits `get` with `key` and `value` as arguments. | ||
* @param {String|Array} `key` The name of the property to get. Dot-notation may be used to set nested properties. | ||
* @return {any} Returns the value of `key` | ||
* @api public | ||
*/ | ||
get(key) { | ||
let val = get(this[this.prop], key); | ||
if (typeof val === 'undefined' && this.defaults) { | ||
val = get(this.defaults, key); | ||
} | ||
this.emit('get', key, val); | ||
return val; | ||
} | ||
/** | ||
* Create a property on the cache with the given `value` only if it doesn't | ||
* already exist. | ||
* | ||
* ```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' } | ||
* ``` | ||
* @name .prime | ||
* @param {String} `key` Property name or object path notation. | ||
* @param {any} `val` | ||
* @return {Object} Returns the instance for chaining. | ||
@@ -100,9 +125,9 @@ * @api public | ||
union(key, val) { | ||
if (Array.isArray(key) && arguments.length === 2) { | ||
key = key.join('.'); | ||
prime(key, ...rest) { | ||
if (isObject(key) || Array.isArray(key)) { | ||
return this.visit('prime', key, ...rest); | ||
} | ||
const ctx = this.prop ? this[this.prop] : this; | ||
union(ctx, key, val); | ||
this.emit('union', val); | ||
if (!this.has(key)) { | ||
this.set(key, ...rest); | ||
} | ||
return this; | ||
@@ -112,47 +137,90 @@ } | ||
/** | ||
* Return the value of `key`. Dot notation may be used to | ||
* get [nested property values][get-value]. | ||
* 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. | ||
* | ||
* ```js | ||
* cache.set('a.b.c', 'd'); | ||
* cache.get('a.b'); | ||
* //=> { c: 'd' } | ||
* app.set('foo', 'xxx'); | ||
* app.default('foo', 'one'); | ||
* app.default('bar', 'two'); | ||
* app.default('baz', 'three'); | ||
* app.set('baz', 'zzz'); | ||
* | ||
* cache.get(['a', 'b']); | ||
* //=> { c: 'd' } | ||
* 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' } } | ||
* ``` | ||
* | ||
* @name .get | ||
* @emits `get` with `key` and `value` as arguments. | ||
* @param {String|Array} `key` The name of the property to get. Dot-notation or an array of object path segments may be used. | ||
* @return {any} Returns the value of `key` | ||
* @name .default | ||
* @param {String|Array} `key` The name of the property to set. Dot-notation may be used to set nested properties. | ||
* @param {any} `value` (optional) The value to set on the defaults object. | ||
* @return {Object} Returns the instance for chaining. | ||
* @api public | ||
*/ | ||
get(key) { | ||
if (Array.isArray(key)) key = key.join('.'); | ||
if (arguments.length > 1) { | ||
key = [].concat.apply([], arguments).join('.'); | ||
default(key, ...rest) { | ||
this.defaults = this.defaults || {}; | ||
if (isObject(key) || Array.isArray(key)) { | ||
return this.visit('default', key, ...rest); | ||
} | ||
const ctx = this.prop ? this[this.prop] : this; | ||
const val = get(ctx, key); | ||
if (!isString(key)) { | ||
throw new TypeError('expected "key" to be a string, object or array'); | ||
} | ||
this.emit('get', key, val); | ||
return val; | ||
if (rest.length === 0) { | ||
return get(this.defaults, key); | ||
} | ||
set(this.defaults, key, ...rest); | ||
this.emit('default', key, rest); | ||
return this; | ||
} | ||
/** | ||
* Return true if cache has a stored value for `key`, | ||
* false only if value is `undefined`. | ||
* Set an array of unique values on cache `key`. | ||
* | ||
* ```js | ||
* cache.set('foo', 'bar'); | ||
* cache.has('foo'); | ||
* //=> true | ||
* 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'] } } | ||
* ``` | ||
* @name .union | ||
* @param {String|Array} `key` The name of the property to union. Dot-notation may be used to set nested properties. | ||
* @param {any} `value` | ||
* @return {Object} Returns the instance for chaining. | ||
* @api public | ||
*/ | ||
union(key, ...rest) { | ||
union(this[this.prop], key, ...rest); | ||
this.emit('union', ...rest); | ||
return this; | ||
} | ||
/** | ||
* Return true if the value of property `key` is not `undefined`. | ||
* | ||
* ```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 | ||
* ``` | ||
* @name .has | ||
* @emits `has` with `key` and true or false as arguments. | ||
* @param {String|Array} `key` The name of the property to check. Dot-notation or an array of object path segments may be used. | ||
* @param {String|Array} `key` The name of the property to check. Dot-notation may be used to set nested properties. | ||
* @return {Boolean} | ||
@@ -163,10 +231,33 @@ * @api public | ||
has(key) { | ||
if (Array.isArray(key)) key = key.join('.'); | ||
return typeof get(this[this.prop], key) !== 'undefined'; | ||
} | ||
const ctx = this.prop ? this[this.prop] : this; | ||
const val = get(ctx, key); | ||
/** | ||
* 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`. | ||
* | ||
* ```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 | ||
* ``` | ||
* @name .hasOwn | ||
* @param {String} `key` | ||
* @return {Boolean} Returns true if object `key` exists. Dot-notation may be used to set nested properties. | ||
* @api public | ||
*/ | ||
const has = typeof val !== 'undefined'; | ||
this.emit('has', key, has); | ||
return has; | ||
hasOwn(key) { | ||
return hasOwn(this[this.prop], key); | ||
} | ||
@@ -178,11 +269,15 @@ | ||
* ```js | ||
* cache.del(); // delete all | ||
* // 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 | ||
* cache.del('foo'); | ||
* // or | ||
* cache.del(['foo', 'bar']); | ||
* app.del('foo'); | ||
* // or an array of keys | ||
* app.del(['foo', 'bar']); | ||
* ``` | ||
* @name .del | ||
* @emits `del` with the `key` as the only argument. | ||
* @param {String|Array} `key` The name of the property to delete. Dot-notation or an array of object path segments may be used. | ||
* @param {String|Array} `key` The name of the property to delete. Dot-notation may be used to set nested properties. | ||
* @return {Object} Returns the instance for chaining. | ||
@@ -193,8 +288,8 @@ * @api public | ||
del(key) { | ||
if (!key) return this.clear(); | ||
if (Array.isArray(key)) { | ||
this.visit('del', key); | ||
} else { | ||
del(this.prop ? this[this.prop] : this, key); | ||
this.emit('del', key); | ||
return this.visit('del', key); | ||
} | ||
del(this[this.prop], key); | ||
this.emit('del', key); | ||
return this; | ||
@@ -204,7 +299,26 @@ } | ||
/** | ||
* Visit `method` over the properties in the given object, or map | ||
* visit over the object-elements in an array. | ||
* 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. | ||
* | ||
* ```js | ||
* // clear "defaults" whenever the cache is cleared | ||
* app.on('clear', key => (app.defaults = {})); | ||
* app.clear(); | ||
* ``` | ||
* @name .clear | ||
* @api public | ||
*/ | ||
clear() { | ||
this[this.prop] = {}; | ||
this.emit('clear'); | ||
return this; | ||
} | ||
/** | ||
* Visit (or map visit) the specified method (`key`) over the properties in the | ||
* given object or array. | ||
* | ||
* @name .visit | ||
* @param {String|Array} `key` The name of the method to visit. Dot-notation or an array of object path segments may be used. | ||
* @param {String|Array} `key` The name of the method to visit. | ||
* @param {Object|Array} `val` The object or array to iterate over. | ||
@@ -215,7 +329,4 @@ * @return {Object} Returns the instance for chaining. | ||
visit(key, val) { | ||
if (Array.isArray(key)) { | ||
key = key.join('.'); | ||
} | ||
visit(this, key, val); | ||
visit(key, ...rest) { | ||
visit(this, key, ...rest); | ||
return this; | ||
@@ -225,25 +336,60 @@ } | ||
/** | ||
* Reset the entire cache to an empty object. | ||
* Gets an array of names of all enumerable properties on the cache. | ||
* | ||
* ```js | ||
* cache.clear(); | ||
* const app = new CacheBase(); | ||
* app.set('user', true); | ||
* app.set('admin', false); | ||
* | ||
* console.log(app.keys); | ||
* //=> ['user', 'admin'] | ||
* ``` | ||
* @name .keys | ||
* @api public | ||
*/ | ||
clear() { | ||
if (this.prop) { | ||
this[this.prop] = {}; | ||
} else { | ||
for (const key of Object.keys(this)) { | ||
delete this[key]; | ||
} | ||
} | ||
get keys() { | ||
return Object.keys(this[this.prop]); | ||
} | ||
/** | ||
* Gets the length of [keys](#keys). | ||
* | ||
* ```js | ||
* const app = new CacheBase(); | ||
* app.set('user', true); | ||
* app.set('admin', false); | ||
* | ||
* console.log(app.size); | ||
* //=> 2 | ||
* ``` | ||
* @name .size | ||
* @api public | ||
*/ | ||
get size() { | ||
return this.keys.length; | ||
} | ||
} | ||
/** | ||
* Expose `Cache` | ||
* Returns true if `value` is a non-empty string. | ||
*/ | ||
module.exports = Cache; | ||
function isString(value) { | ||
return typeof value === 'string' && value !== ''; | ||
} | ||
/** | ||
* Returns true if `value` is an object | ||
*/ | ||
function isObject(value) { | ||
return typeOf(value) === 'object'; | ||
} | ||
/** | ||
* Expose `CacheBase` | ||
*/ | ||
module.exports = CacheBase; |
{ | ||
"name": "cache-base", | ||
"description": "Basic object cache with `get`, `set`, `del`, and `has` methods for node.js/javascript projects.", | ||
"version": "2.0.2", | ||
"version": "3.0.0", | ||
"homepage": "https://github.com/jonschlinkert/cache-base", | ||
@@ -21,6 +21,6 @@ "author": "Jon Schlinkert (https://github.com/jonschlinkert)", | ||
"engines": { | ||
"node": ">=0.10.0" | ||
"node": ">=6" | ||
}, | ||
"scripts": { | ||
"test": "mocha" | ||
"test": "nyc --reporter=text --reporter=html mocha" | ||
}, | ||
@@ -30,5 +30,6 @@ "dependencies": { | ||
"collection-visit": "^1.0.0", | ||
"get-value": "^2.0.6", | ||
"isobject": "^3.0.1", | ||
"set-value": "^2.0.0", | ||
"get-value": "^3.0.1", | ||
"has-own-deep": "^1.1.0", | ||
"kind-of": "^6.0.2", | ||
"set-value": "^3.0.0", | ||
"union-value": "^1.0.0", | ||
@@ -39,3 +40,4 @@ "unset-value": "^1.0.0" | ||
"gulp-format-md": "^1.0.0", | ||
"mocha": "^3.5.3" | ||
"mocha": "^3.5.3", | ||
"nyc": "^11.6.0" | ||
}, | ||
@@ -57,3 +59,3 @@ "keywords": [ | ||
"run": true, | ||
"toc": false, | ||
"toc": true, | ||
"layout": "default", | ||
@@ -60,0 +62,0 @@ "tasks": [ |
381
README.md
@@ -7,2 +7,10 @@ # cache-base [![NPM version](https://img.shields.io/npm/v/cache-base.svg?style=flat)](https://www.npmjs.com/package/cache-base) [![NPM monthly downloads](https://img.shields.io/npm/dm/cache-base.svg?style=flat)](https://npmjs.org/package/cache-base) [![NPM total downloads](https://img.shields.io/npm/dt/cache-base.svg?style=flat)](https://npmjs.org/package/cache-base) [![Linux Build Status](https://img.shields.io/travis/jonschlinkert/cache-base.svg?style=flat&label=Travis)](https://travis-ci.org/jonschlinkert/cache-base) | ||
- [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 | ||
@@ -16,124 +24,145 @@ | ||
## Usage | ||
## Quickstart | ||
```js | ||
const Cache = require('cache-base'); | ||
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' | ||
``` | ||
**Instantiate** | ||
More [usage examples](#usage-examples) below. | ||
```js | ||
// instantiate | ||
const cache = new Cache(); | ||
## API | ||
// set values | ||
cache.set('a', 'b'); | ||
cache.set('c.d', 'e'); | ||
**Params** | ||
// get values | ||
console.log(cache.get('a')); | ||
//=> 'b' | ||
console.log(cache.get('c')); | ||
//=> { d: 'e' } | ||
console.log(cache); | ||
//=> Cache { a: 'b' } | ||
``` | ||
* `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. | ||
**Initialize with an object** | ||
**Example** | ||
```js | ||
// instantiate | ||
const cache = new Cache({ a: 'b', c: { d: 'e' } }); | ||
// get values | ||
console.log(cache.get('a')); | ||
//=> 'b' | ||
console.log(cache.get('c')); | ||
//=> { d: 'e' } | ||
console.log(cache.get('c.d')); | ||
//=> 'e' | ||
console.log(cache); | ||
//=> Cache { a: 'b' } | ||
const app = new CacheBase(); | ||
``` | ||
**Inherit** | ||
### [.set](index.js#L65) | ||
```js | ||
class MyApp extends Cache {} | ||
Assign `value` to `key`. Also emits `set` with the key and value. | ||
var cache = new MyApp(); | ||
cache.set('a', 'b'); | ||
console.log(cache.get('a')); | ||
//=> 'b' | ||
``` | ||
**Params** | ||
**Custom namespace** | ||
* `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. | ||
Define a custom property name for storing values. By default, values are stored directly on the instance (for example, when `cache.set('foo', 'bar')` is used, `cache.foo` would be `bar`). | ||
**Events** | ||
* `emits`: `set` with `key` and `value` as arguments. | ||
**Example** | ||
```js | ||
const Cache = require('cache-base'); | ||
const cache = new Cache('data', { a: 'b' }); | ||
cache.set('c.d', 'e'); | ||
app.on('set', function(key, val) { | ||
// do something when `set` is emitted | ||
}); | ||
// get values | ||
console.log(cache.get('a')); | ||
//=> 'b' | ||
console.log(cache.get('c')); | ||
//=> { d: 'e' } | ||
console.log(cache.data); | ||
//=> { a: 'b', c: { d: 'e' } } | ||
console.log(cache); | ||
//=> Cache { data: { a: 'b', c: { d: 'e' } } } | ||
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' } | ||
``` | ||
## API | ||
### [.get](index.js#L90) | ||
Return the value of `key`. | ||
**Params** | ||
* `cache` **{Object}**: Optionally pass an object to initialize with. | ||
* `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 | ||
const cache = new Cache(); | ||
app.set('a.b.c', 'd'); | ||
app.get('a.b'); | ||
//=> { c: 'd' } | ||
``` | ||
### [.set](index.js#L65) | ||
### [.prime](index.js#L120) | ||
Assign `value` to `key`. Also emits `set` with the key and value. | ||
Create a property on the cache with the given `value` only if it doesn't already exist. | ||
**Params** | ||
* `key` **{String|Array}**: The name of the property to set. Dot-notation or an array of object path segments may be used. | ||
* `value` **{any}** | ||
* `key` **{String}**: Property name or object path notation. | ||
* `val` **{any}** | ||
* `returns` **{Object}**: Returns the instance for chaining. | ||
**Events** | ||
**Example** | ||
* `emits`: `set` with `key` and `value` as arguments. | ||
```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 | ||
cache.on('set', function(key, val) { | ||
// do something when `set` is emitted | ||
}); | ||
app.set('foo', 'xxx'); | ||
app.default('foo', 'one'); | ||
app.default('bar', 'two'); | ||
app.default('baz', 'three'); | ||
app.set('baz', 'zzz'); | ||
cache.set(key, value); | ||
console.log(app.get('foo')); | ||
//=> 'xxx' | ||
// also takes an object or array | ||
cache.set({name: 'Halle'}); | ||
cache.set([{foo: 'bar'}, {baz: 'quux'}]); | ||
console.log(cache); | ||
//=> {name: 'Halle', foo: 'bar', baz: 'quux'} | ||
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#L95) | ||
### [.union](index.js#L199) | ||
Union `array` to `key`. Also emits `set` with the key and value. | ||
Set an array of unique values on cache `key`. | ||
**Params** | ||
* `key` **{String|Array}**: The name of the property to union. Dot-notation or an array of object path segments may be used. | ||
* `key` **{String|Array}**: The name of the property to union. Dot-notation may be used to set nested properties. | ||
* `value` **{any}** | ||
@@ -145,54 +174,58 @@ * `returns` **{Object}**: Returns the instance for chaining. | ||
```js | ||
cache.union('a.b', ['foo']); | ||
cache.union('a.b', ['bar']); | ||
console.log(cache.get('a')); | ||
//=> {b: ['foo', 'bar']} | ||
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'] } } | ||
``` | ||
### [.get](index.js#L125) | ||
### [.has](index.js#L223) | ||
Return the value of `key`. Dot notation may be used to get [nested property values](https://github.com/jonschlinkert/get-value). | ||
Return true if the value of property `key` is not `undefined`. | ||
**Params** | ||
* `key` **{String|Array}**: The name of the property to get. Dot-notation or an array of object path segments may be used. | ||
* `returns` **{any}**: Returns the value of `key` | ||
* `key` **{String|Array}**: The name of the property to check. Dot-notation may be used to set nested properties. | ||
* `returns` **{Boolean}** | ||
**Events** | ||
* `emits`: `get` with `key` and `value` as arguments. | ||
**Example** | ||
```js | ||
cache.set('a.b.c', 'd'); | ||
cache.get('a.b'); | ||
//=> { c: 'd' } | ||
app.set('foo', true); | ||
app.set('baz', null); | ||
app.set('bar', undefined); | ||
cache.get(['a', 'b']); | ||
//=> { c: 'd' } | ||
app.has('foo'); //=> true | ||
app.has('bar'); //=> true | ||
app.has('baz'); //=> false | ||
``` | ||
### [.has](index.js#L155) | ||
### [.hasOwn](index.js#L253) | ||
Return true if cache has a stored value for `key`, false only if value is `undefined`. | ||
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|Array}**: The name of the property to check. Dot-notation or an array of object path segments may be used. | ||
* `returns` **{Boolean}** | ||
* `key` **{String}** | ||
* `returns` **{Boolean}**: Returns true if object `key` exists. Dot-notation may be used to set nested properties. | ||
**Events** | ||
* `emits`: `has` with `key` and true or false as arguments. | ||
**Example** | ||
```js | ||
cache.set('foo', 'bar'); | ||
cache.has('foo'); | ||
//=> true | ||
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#L183) | ||
### [.del](index.js#L278) | ||
@@ -203,3 +236,3 @@ Delete one or more properties from the instance. | ||
* `key` **{String|Array}**: The name of the property to delete. Dot-notation or an array of object path segments may be used. | ||
* `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. | ||
@@ -214,26 +247,135 @@ | ||
```js | ||
cache.del(); // delete all | ||
// 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 | ||
cache.del('foo'); | ||
// or | ||
cache.del(['foo', 'bar']); | ||
app.del('foo'); | ||
// or an array of keys | ||
app.del(['foo', 'bar']); | ||
``` | ||
### [.visit](index.js#L204) | ||
### [.clear](index.js#L301) | ||
Visit `method` over the properties in the given object, or map | ||
visit over the object-elements in an array. | ||
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. Dot-notation or an array of object path segments may be used. | ||
* `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 | ||
cache.clear(); | ||
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 | ||
@@ -258,2 +400,3 @@ | ||
</details> | ||
<details> | ||
@@ -277,3 +420,3 @@ <summary><strong>Building docs</strong></summary> | ||
* [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 (`a.b.c`) to get a nested value from an object. | [homepage](https://github.com/jonschlinkert/get-value "Use property paths (`a.b.c`) to get a nested value from an object.") | ||
* [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.") | ||
@@ -288,3 +431,3 @@ * [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.") | ||
| --- | --- | | ||
| 64 | [jonschlinkert](https://github.com/jonschlinkert) | | ||
| 67 | [jonschlinkert](https://github.com/jonschlinkert) | | ||
| 2 | [wtgtybhertgeghgtwtg](https://github.com/wtgtybhertgeghgtwtg) | | ||
@@ -296,9 +439,9 @@ | ||
* [linkedin/in/jonschlinkert](https://linkedin.com/in/jonschlinkert) | ||
* [github/jonschlinkert](https://github.com/jonschlinkert) | ||
* [twitter/jonschlinkert](https://twitter.com/jonschlinkert) | ||
* [LinkedIn Profile](https://linkedin.com/in/jonschlinkert) | ||
* [GitHub Profile](https://github.com/jonschlinkert) | ||
* [Twitter Profile](https://twitter.com/jonschlinkert) | ||
### License | ||
Copyright © 2017, [Jon Schlinkert](https://github.com/jonschlinkert). | ||
Copyright © 2018, [Jon Schlinkert](https://github.com/jonschlinkert). | ||
Released under the [MIT License](LICENSE). | ||
@@ -308,2 +451,2 @@ | ||
_This file was generated by [verb-generate-readme](https://github.com/verbose/verb-generate-readme), v0.6.0, on December 19, 2017._ | ||
_This file was generated by [verb-generate-readme](https://github.com/verbose/verb-generate-readme), v0.6.0, on March 23, 2018._ |
Sorry, the diff of this file is not supported yet
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
Major refactor
Supply chain riskPackage has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.
Found 1 instance in 1 package
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
28531
339
442
8
3
1
+ Addedhas-own-deep@^1.1.0
+ Addedkind-of@^6.0.2
+ Addedget-value@3.0.1(transitive)
+ Addedhas-own-deep@1.1.0(transitive)
+ Addedkind-of@6.0.3(transitive)
+ Addedset-value@3.0.3(transitive)
- Removedisobject@^3.0.1
Updatedget-value@^3.0.1
Updatedset-value@^3.0.0