README.md
1 # 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) 2 3 > Basic object cache with `get`, `set`, `del`, and `has` methods for node.js/javascript projects. 4 5 ## Install 6 7 Install with [npm](https://www.npmjs.com/): 8 9 ```sh 10 $ npm install --save cache-base 11 ``` 12 13 ## Usage 14 15 ```js 16 var Cache = require('cache-base'); 17 18 // instantiate 19 var app = new Cache(); 20 21 // set values 22 app.set('a', 'b'); 23 app.set('c.d', 'e'); 24 25 // get values 26 app.get('a'); 27 //=> 'b' 28 app.get('c'); 29 //=> {d: 'e'} 30 31 console.log(app.cache); 32 //=> {a: 'b'} 33 ``` 34 35 **Inherit** 36 37 ```js 38 var util = require('util'); 39 var Cache = require('cache-base'); 40 41 function MyApp() { 42 Cache.call(this); 43 } 44 util.inherits(MyApp, Cache); 45 46 var app = new MyApp(); 47 app.set('a', 'b'); 48 app.get('a'); 49 //=> 'b' 50 ``` 51 52 **Namespace** 53 54 Define a custom property for storing values. 55 56 ```js 57 var Cache = require('cache-base').namespace('data'); 58 var app = new Cache(); 59 app.set('a', 'b'); 60 console.log(app.data); 61 //=> {a: 'b'} 62 ``` 63 64 ## API 65 66 ### [namespace](index.js#L29) 67 68 Create a `Cache` constructor that when instantiated will store values on the given `prop`. 69 70 **Params** 71 72 * `prop` **{String}**: The property name to use for storing values. 73 * `returns` **{Function}**: Returns a custom `Cache` constructor 74 75 **Example** 76 77 ```js 78 var Cache = require('cache-base').namespace('data'); 79 var cache = new Cache(); 80 81 cache.set('foo', 'bar'); 82 //=> {data: {foo: 'bar'}} 83 ``` 84 85 ### [Cache](index.js#L43) 86 87 Create a new `Cache`. Internally the `Cache` constructor is created using the `namespace` function, with `cache` defined as the storage object. 88 89 **Params** 90 91 * `cache` **{Object}**: Optionally pass an object to initialize with. 92 93 **Example** 94 95 ```js 96 var app = new Cache(); 97 ``` 98 99 ### [.set](index.js#L84) 100 101 Assign `value` to `key`. Also emits `set` with the key and value. 102 103 **Params** 104 105 * `key` **{String}** 106 * `value` **{any}** 107 * `returns` **{Object}**: Returns the instance for chaining. 108 109 **Events** 110 111 * `emits`: `set` with `key` and `value` as arguments. 112 113 **Example** 114 115 ```js 116 app.on('set', function(key, val) { 117 // do something when `set` is emitted 118 }); 119 120 app.set(key, value); 121 122 // also takes an object or array 123 app.set({name: 'Halle'}); 124 app.set([{foo: 'bar'}, {baz: 'quux'}]); 125 console.log(app); 126 //=> {name: 'Halle', foo: 'bar', baz: 'quux'} 127 ``` 128 129 ### [.union](index.js#L114) 130 131 Union `array` to `key`. Also emits `set` with the key and value. 132 133 **Params** 134 135 * `key` **{String}** 136 * `value` **{any}** 137 * `returns` **{Object}**: Returns the instance for chaining. 138 139 **Example** 140 141 ```js 142 app.union('a.b', ['foo']); 143 app.union('a.b', ['bar']); 144 console.log(app.get('a')); 145 //=> {b: ['foo', 'bar']} 146 ``` 147 148 ### [.get](index.js#L144) 149 150 Return the value of `key`. Dot notation may be used to get [nested property values](https://github.com/jonschlinkert/get-value). 151 152 **Params** 153 154 * `key` **{String}**: The name of the property to get. Dot-notation may be used. 155 * `returns` **{any}**: Returns the value of `key` 156 157 **Events** 158 159 * `emits`: `get` with `key` and `value` as arguments. 160 161 **Example** 162 163 ```js 164 app.set('a.b.c', 'd'); 165 app.get('a.b'); 166 //=> {c: 'd'} 167 168 app.get(['a', 'b']); 169 //=> {c: 'd'} 170 ``` 171 172 ### [.has](index.js#L171) 173 174 Return true if app has a stored value for `key`, false only if value is `undefined`. 175 176 **Params** 177 178 * `key` **{String}** 179 * `returns` **{Boolean}** 180 181 **Events** 182 183 * `emits`: `has` with `key` and true or false as arguments. 184 185 **Example** 186 187 ```js 188 app.set('foo', 'bar'); 189 app.has('foo'); 190 //=> true 191 ``` 192 193 ### [.del](index.js#L199) 194 195 Delete one or more properties from the instance. 196 197 **Params** 198 199 * `key` **{String|Array}**: Property name or array of property names. 200 * `returns` **{Object}**: Returns the instance for chaining. 201 202 **Events** 203 204 * `emits`: `del` with the `key` as the only argument. 205 206 **Example** 207 208 ```js 209 app.del(); // delete all 210 // or 211 app.del('foo'); 212 // or 213 app.del(['foo', 'bar']); 214 ``` 215 216 ### [.clear](index.js#L218) 217 218 Reset the entire cache to an empty object. 219 220 **Example** 221 222 ```js 223 app.clear(); 224 ``` 225 226 ### [.visit](index.js#L235) 227 228 Visit `method` over the properties in the given object, or map 229 visit over the object-elements in an array. 230 231 **Params** 232 233 * `method` **{String}**: The name of the `base` method to call. 234 * `val` **{Object|Array}**: The object or array to iterate over. 235 * `returns` **{Object}**: Returns the instance for chaining. 236 237 ## About 238 239 ### Related projects 240 241 * [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`.") 242 * [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.") 243 * [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.") 244 * [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.") 245 * [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.") 246 * [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.") 247 248 ### Contributing 249 250 Pull requests and stars are always welcome. For bugs and feature requests, [please create an issue](../../issues/new). 251 252 ### Contributors 253 254 | **Commits** | **Contributor** | 255 | --- | --- | 256 | 54 | [jonschlinkert](https://github.com/jonschlinkert) | 257 | 2 | [wtgtybhertgeghgtwtg](https://github.com/wtgtybhertgeghgtwtg) | 258 259 ### Building docs 260 261 _(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.)_ 262 263 To generate the readme, run the following command: 264 265 ```sh 266 $ npm install -g verbose/verb#dev verb-generate-readme && verb 267 ``` 268 269 ### Running tests 270 271 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: 272 273 ```sh 274 $ npm install && npm test 275 ``` 276 277 ### Author 278 279 **Jon Schlinkert** 280 281 * [github/jonschlinkert](https://github.com/jonschlinkert) 282 * [twitter/jonschlinkert](https://twitter.com/jonschlinkert) 283 284 ### License 285 286 Copyright © 2017, [Jon Schlinkert](https://github.com/jonschlinkert). 287 Released under the [MIT License](LICENSE). 288 289 *** 290 291 _This file was generated by [verb-generate-readme](https://github.com/verbose/verb-generate-readme), v0.6.0, on July 22, 2017._