https://github.com/base-repos/base-data
adds a `data` method to base-methods. 100% unit test coverage and browserify-friendly lazy-caching.
https://github.com/base-repos/base-data
base context data extend files glob merge object objects plugin read
Last synced: 5 months ago
JSON representation
adds a `data` method to base-methods. 100% unit test coverage and browserify-friendly lazy-caching.
- Host: GitHub
- URL: https://github.com/base-repos/base-data
- Owner: base-repos
- License: mit
- Created: 2015-10-02T09:16:54.000Z (about 10 years ago)
- Default Branch: master
- Last Pushed: 2020-04-01T00:06:45.000Z (over 5 years ago)
- Last Synced: 2025-05-07T06:04:32.837Z (5 months ago)
- Topics: base, context, data, extend, files, glob, merge, object, objects, plugin, read
- Language: JavaScript
- Homepage:
- Size: 77.1 KB
- Stars: 19
- Watchers: 2
- Forks: 1
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# base-data [](https://www.npmjs.com/package/base-data) [](https://npmjs.org/package/base-data) [](https://npmjs.org/package/base-data) [](https://travis-ci.org/node-base/base-data)
> adds a `data` method to base-methods.
- [Install](#install)
- [Usage](#usage)
- [API](#api)
- [Glob patterns](#glob-patterns)
- [Namespacing](#namespacing)
- [History](#history)
- [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 base-data
```
## Usage
Adds a `data` method to [base](https://github.com/node-base/base) that can be used for setting, getting and loading data onto a specified object in your application.
```js
var Base = require('base');
var data = require('base-data');
// instantiate `Base`
var base = new Base();
// add `data` as a plugin
base.use(data());
```
**Examples**
Add data:
```js
app.data('a', 'b');
app.data({c: 'd'});
app.data('e', ['f']);
console.log(app.cache.data);
//=> {a: 'b', c: 'd', e: ['f']}
```
**cache.data**
By default, all data is loaded onto `app.cache.data`. This can be customized by passing the property to use when the plugin is initialized.
For example, the following set `app.foo` as object for storing data:
```js
app.use(data('foo'));
app.data('a', 'b');
console.log(app.foo);
//=> {a: 'b'}
```
## API
### [.dataLoader](index.js#L66)
Register a data loader for loading data onto `app.cache.data`.
**Params**
* `ext` **{String}**: The file extension for to match to the loader
* `fn` **{Function}**: The loader function.
**Example**
```js
var yaml = require('js-yaml');
app.dataLoader('yml', function(str, fp) {
return yaml.safeLoad(str);
});
app.data('foo.yml');
//=> loads and parses `foo.yml` as yaml
```
### [.data](index.js#L101)
Load data onto `app.cache.data`
**Params**
* `key` **{String|Object}**: Key of the value to set, or object to extend.
* `val` **{any}**
* `returns` **{Object}**: Returns the instance of `Template` for chaining
**Example**
```js
console.log(app.cache.data);
//=> {};
app.data('a', 'b');
app.data({c: 'd'});
console.log(app.cache.data);
//=> {a: 'b', c: 'd'}
// set an array
app.data('e', ['f']);
// overwrite the array
app.data('e', ['g']);
// update the array
app.data('e', ['h'], true);
console.log(app.cache.data.e);
//=> ['g', 'h']
```
### [.data.extend](index.js#L252)
Shallow extend an object onto `app.cache.data`.
**Params**
* `key` **{String|Object}**: Property name or object to extend onto `app.cache.data`. Dot-notation may be used for extending nested properties.
* `value` **{Object}**: The object to extend onto `app.cache.data`
* `returns` **{Object}**: returns the instance for chaining
**Example**
```js
app.data({a: {b: {c: 'd'}}});
app.data.extend('a.b', {x: 'y'});
console.log(app.get('a.b'));
//=> {c: 'd', x: 'y'}
```
### [.data.merge](index.js#L285)
Deeply merge an object onto `app.cache.data`.
**Params**
* `key` **{String|Object}**: Property name or object to merge onto `app.cache.data`. Dot-notation may be used for merging nested properties.
* `value` **{Object}**: The object to merge onto `app.cache.data`
* `returns` **{Object}**: returns the instance for chaining
**Example**
```js
app.data({a: {b: {c: {d: {e: 'f'}}}}});
app.data.merge('a.b', {c: {d: {g: 'h'}}});
console.log(app.get('a.b'));
//=> {c: {d: {e: 'f', g: 'h'}}}
```
### [.data.union](index.js#L317)
Union the given value onto a new or existing array value on `app.cache.data`.
**Params**
* `key` **{String}**: Property name. Dot-notation may be used for nested properties.
* `array` **{Object}**: The array to add or union on `app.cache.data`
* `returns` **{Object}**: returns the instance for chaining
**Example**
```js
app.data({a: {b: ['c', 'd']}});
app.data.union('a.b', ['e', 'f']}});
console.log(app.get('a.b'));
//=> ['c', 'd', 'e', 'f']
```
### [.data.set](index.js#L337)
Set the given value onto `app.cache.data`.
**Params**
* `key` **{String|Object}**: Property name or object to merge onto `app.cache.data`. Dot-notation may be used for nested properties.
* `val` **{any}**: The value to set on `app.cache.data`
* `returns` **{Object}**: returns the instance for chaining
**Example**
```js
app.data.set('a.b', ['c', 'd']}});
console.log(app.get('a'));
//=> {b: ['c', 'd']}
```
### [.data.get](index.js#L360)
Get the value of `key` from `app.cache.data`. Dot-notation may be used for getting nested properties.
**Params**
* `key` **{String}**: The name of the property to get.
* `returns` **{any}**: Returns the value of `key`
**Example**
```js
app.data({a: {b: {c: 'd'}}});
console.log(app.get('a.b'));
//=> {c: 'd'}
```
## Glob patterns
Glob patterns may be passed as a string or array. All of these work:
```js
app.data('foo.json');
app.data('*.json');
app.data(['*.json']);
// pass options to node-glob
app.data(['*.json'], {dot: true});
```
## Namespacing
Namespacing allows you to load data onto a specific key, optionally using part of the file path as the key.
**Example**
Given that `foo.json` contains `{a: 'b'}`:
```js
app.data('foo.json');
console.log(app.cache.data);
//=> {a: 'b'}
app.data('foo.json', {namespace: true});
console.log(app.cache.data);
//=> {foo: {a: 'b'}}
app.data('foo.json', {
namespace: function(fp) {
return path.basename(fp);
}
});
console.log(app.cache.data);
//=> {'foo.json': {a: 'b'}}
```
## History
**v0.6.0**
* removes `renameKey` option for namespacing
* replaces [is-valid-instance](https://github.com/jonschlinkert/is-valid-instance) and [is-registered](https://github.com/jonschlinkert/is-registered) with [is-valid-app](https://github.com/node-base/is-valid-app)
**v0.5.0**
* uses [is-valid-instance](https://github.com/jonschlinkert/is-valid-instance) and [is-registered](https://github.com/jonschlinkert/is-registered) to ensure the smart plugin is registered on the correct objects.
**v0.4.0**
* _Refactored_
* adds methods to `.data` for getting and setting data.
**v0.3.6**
* adds a basic loader that only calls the `JSON.parse` method, if no other loaders are defined
* calls `.isRegistered` from [base](https://github.com/node-base/base) to ensure the plugin is only loaded once on an instance
## About
### Related projects
* [base-cli](https://www.npmjs.com/package/base-cli): Plugin for base-methods that maps built-in methods to CLI args (also supports methods from a… [more](https://github.com/node-base/base-cli) | [homepage](https://github.com/node-base/base-cli "Plugin for base-methods that maps built-in methods to CLI args (also supports methods from a few plugins, like 'base-store', 'base-options' and 'base-data'.")
* [base-config](https://www.npmjs.com/package/base-config): base-methods plugin that adds a `config` method for mapping declarative configuration values to other 'base… [more](https://github.com/node-base/base-config) | [homepage](https://github.com/node-base/base-config "base-methods plugin that adds a `config` method for mapping declarative configuration values to other 'base' methods or custom functions.")
* [base-option](https://www.npmjs.com/package/base-option): Adds a few options methods to base, like `option`, `enable` and `disable`. See the readme… [more](https://github.com/node-base/base-option) | [homepage](https://github.com/node-base/base-option "Adds a few options methods to base, like `option`, `enable` and `disable`. See the readme for the full API.")
* [base-pipeline](https://www.npmjs.com/package/base-pipeline): base-methods plugin that adds pipeline and plugin methods for dynamically composing streaming plugin pipelines. | [homepage](https://github.com/node-base/base-pipeline "base-methods plugin that adds pipeline and plugin methods for dynamically composing streaming plugin pipelines.")
* [base-plugins](https://www.npmjs.com/package/base-plugins): Adds 'smart plugin' support to your base application. | [homepage](https://github.com/node-base/base-plugins "Adds 'smart plugin' support to your base application.")
* [base-store](https://www.npmjs.com/package/base-store): Plugin for getting and persisting config values with your base-methods application. Adds a 'store' object… [more](https://github.com/node-base/base-store) | [homepage](https://github.com/node-base/base-store "Plugin for getting and persisting config values with your base-methods application. Adds a 'store' object that exposes all of the methods from the data-store library. Also now supports sub-stores!")
* [base](https://www.npmjs.com/package/base): Framework for rapidly creating high quality node.js applications, using plugins like building blocks | [homepage](https://github.com/node-base/base "Framework for rapidly creating high quality node.js applications, using plugins like building blocks")
### Contributing
Pull requests and stars are always welcome. For bugs and feature requests, [please create an issue](../../issues/new).
### Contributors
| **Commits** | **Contributor** |
| --- | --- |
| 69 | [jonschlinkert](https://github.com/jonschlinkert) |
| 10 | [doowb](https://github.com/doowb) |
### Building docs
_(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
```
### Running tests
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
```
### Author
**Jon Schlinkert**
* [github/jonschlinkert](https://github.com/jonschlinkert)
* [twitter/jonschlinkert](https://twitter.com/jonschlinkert)
### License
Copyright © 2017, [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 July 20, 2017._