.config/coc/extensions/node_modules/coc-prettier/node_modules/base/README.md

   1 <p align="center">
   2   <a href="https://github.com/node-base/base">
   3     <img height="250" width="250" src="https://raw.githubusercontent.com/node-base/base/master/docs/logo.png">
   4   </a>
   5 </p>
   6
   7 # base [![NPM version](https://img.shields.io/npm/v/base.svg?style=flat)](https://www.npmjs.com/package/base) [![NPM monthly downloads](https://img.shields.io/npm/dm/base.svg?style=flat)](https://npmjs.org/package/base)  [![NPM total downloads](https://img.shields.io/npm/dt/base.svg?style=flat)](https://npmjs.org/package/base) [![Linux Build Status](https://img.shields.io/travis/node-base/base.svg?style=flat&label=Travis)](https://travis-ci.org/node-base/base)
   8
   9 > base 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`.
  10
  11 ## Install
  12
  13 Install with [npm](https://www.npmjs.com/):
  14
  15 ```sh
  16 $ npm install --save base
  17 ```
  18
  19 ## What is Base?
  20
  21 Base is a framework for rapidly creating high quality node.js applications, using plugins like building blocks.
  22
  23 ### Guiding principles
  24
  25 The core team follows these principles to help guide API decisions:
  26
  27 * **Compact API surface**: The smaller the API surface, the easier the library will be to learn and use.
  28 * **Easy to extend**: Implementors can use any npm package, and write plugins in pure JavaScript. If you're building complex apps, Base simplifies inheritance.
  29 * **Easy to test**: No special setup should be required to unit test `Base` or base plugins
  30
  31 ### Minimal API surface
  32
  33 [The API](#api) was designed to provide only the minimum necessary functionality for creating a useful application, with or without [plugins](#plugins).
  34
  35 **Base core**
  36
  37 Base itself ships with only a handful of [useful methods](#api), such as:
  38
  39 * `.set`: for setting values on the instance
  40 * `.get`: for getting values from the instance
  41 * `.has`: to check if a property exists on the instance
  42 * `.define`: for setting non-enumerable values on the instance
  43 * `.use`: for adding plugins
  44
  45 **Be generic**
  46
  47 When deciding on method to add or remove, we try to answer these questions:
  48
  49 1. Will all or most Base applications need this method?
  50 2. Will this method encourage practices or enforce conventions that are beneficial to implementors?
  51 3. Can or should this be done in a plugin instead?
  52
  53 ### Composability
  54
  55 **Plugin system**
  56
  57 It couldn't be easier to extend Base with any features or custom functionality you can think of.
  58
  59 Base plugins are just functions that take an instance of `Base`:
  60
  61 ```js
  62 var base = new Base();
  63
  64 function plugin(base) {
  65   // do plugin stuff, in pure JavaScript
  66 }
  67 // use the plugin
  68 base.use(plugin);
  69 ```
  70
  71 **Inheritance**
  72
  73 Easily inherit Base using `.extend`:
  74
  75 ```js
  76 var Base = require('base');
  77
  78 function MyApp() {
  79   Base.call(this);
  80 }
  81 Base.extend(MyApp);
  82
  83 var app = new MyApp();
  84 app.set('a', 'b');
  85 app.get('a');
  86 //=> 'b';
  87 ```
  88
  89 **Inherit or instantiate with a namespace**
  90
  91 By default, the `.get`, `.set` and `.has` methods set and get values from the root of the `base` instance. You can customize this using the `.namespace` method exposed on the exported function. For example:
  92
  93 ```js
  94 var Base = require('base');
  95 // get and set values on the `base.cache` object
  96 var base = Base.namespace('cache');
  97
  98 var app = base();
  99 app.set('foo', 'bar');
 100 console.log(app.cache.foo);
 101 //=> 'bar'
 102 ```
 103
 104 ## API
 105
 106 **Usage**
 107
 108 ```js
 109 var Base = require('base');
 110 var app = new Base();
 111 app.set('foo', 'bar');
 112 console.log(app.foo);
 113 //=> 'bar'
 114 ```
 115
 116 ### [Base](index.js#L44)
 117
 118 Create an instance of `Base` with the given `config` and `options`.
 119
 120 **Params**
 121
 122 * `config` **{Object}**: If supplied, this object is passed to [cache-base](https://github.com/jonschlinkert/cache-base) to merge onto the the instance upon instantiation.
 123 * `options` **{Object}**: If supplied, this object is used to initialize the `base.options` object.
 124
 125 **Example**
 126
 127 ```js
 128 // initialize with `config` and `options`
 129 var app = new Base({isApp: true}, {abc: true});
 130 app.set('foo', 'bar');
 131
 132 // values defined with the given `config` object will be on the root of the instance
 133 console.log(app.baz); //=> undefined
 134 console.log(app.foo); //=> 'bar'
 135 // or use `.get`
 136 console.log(app.get('isApp')); //=> true
 137 console.log(app.get('foo')); //=> 'bar'
 138
 139 // values defined with the given `options` object will be on `app.options
 140 console.log(app.options.abc); //=> true
 141 ```
 142
 143 ### [.is](index.js#L107)
 144
 145 Set the given `name` on `app._name` and `app.is*` properties. Used for doing lookups in plugins.
 146
 147 **Params**
 148
 149 * `name` **{String}**
 150 * `returns` **{Boolean}**
 151
 152 **Example**
 153
 154 ```js
 155 app.is('foo');
 156 console.log(app._name);
 157 //=> 'foo'
 158 console.log(app.isFoo);
 159 //=> true
 160 app.is('bar');
 161 console.log(app.isFoo);
 162 //=> true
 163 console.log(app.isBar);
 164 //=> true
 165 console.log(app._name);
 166 //=> 'bar'
 167 ```
 168
 169 ### [.isRegistered](index.js#L145)
 170
 171 Returns true if a plugin has already been registered on an instance.
 172
 173 Plugin implementors are encouraged to use this first thing in a plugin
 174 to prevent the plugin from being called more than once on the same
 175 instance.
 176
 177 **Params**
 178
 179 * `name` **{String}**: The plugin name.
 180 * `register` **{Boolean}**: If the plugin if not already registered, to record it as being registered pass `true` as the second argument.
 181 * `returns` **{Boolean}**: Returns true if a plugin is already registered.
 182
 183 **Events**
 184
 185 * `emits`: `plugin` Emits the name of the plugin being registered. Useful for unit tests, to ensure plugins are only registered once.
 186
 187 **Example**
 188
 189 ```js
 190 var base = new Base();
 191 base.use(function(app) {
 192   if (app.isRegistered('myPlugin')) return;
 193   // do stuff to `app`
 194 });
 195
 196 // to also record the plugin as being registered
 197 base.use(function(app) {
 198   if (app.isRegistered('myPlugin', true)) return;
 199   // do stuff to `app`
 200 });
 201 ```
 202
 203 ### [.use](index.js#L175)
 204
 205 Define a plugin function to be called immediately upon init. Plugins are chainable and expose the following arguments to the plugin function:
 206
 207 * `app`: the current instance of `Base`
 208 * `base`: the [first ancestor instance](#base) of `Base`
 209
 210 **Params**
 211
 212 * `fn` **{Function}**: plugin function to call
 213 * `returns` **{Object}**: Returns the item instance for chaining.
 214
 215 **Example**
 216
 217 ```js
 218 var app = new Base()
 219   .use(foo)
 220   .use(bar)
 221   .use(baz)
 222 ```
 223
 224 ### [.define](index.js#L197)
 225
 226 The `.define` method is used for adding non-enumerable property on the instance. Dot-notation is **not supported** with `define`.
 227
 228 **Params**
 229
 230 * `key` **{String}**: The name of the property to define.
 231 * `value` **{any}**
 232 * `returns` **{Object}**: Returns the instance for chaining.
 233
 234 **Example**
 235
 236 ```js
 237 // arbitrary `render` function using lodash `template`
 238 app.define('render', function(str, locals) {
 239   return _.template(str)(locals);
 240 });
 241 ```
 242
 243 ### [.mixin](index.js#L222)
 244
 245 Mix property `key` onto the Base prototype. If base is inherited using `Base.extend` this method will be overridden by a new `mixin` method that will only add properties to the prototype of the inheriting application.
 246
 247 **Params**
 248
 249 * `key` **{String}**
 250 * `val` **{Object|Array}**
 251 * `returns` **{Object}**: Returns the `base` instance for chaining.
 252
 253 **Example**
 254
 255 ```js
 256 app.mixin('foo', function() {
 257   // do stuff
 258 });
 259 ```
 260
 261 ### [.base](index.js#L268)
 262
 263 Getter/setter used when creating nested instances of `Base`, for storing a reference to the first ancestor instance. This works by setting an instance of `Base` on the `parent` property of a "child" instance. The `base` property defaults to the current instance if no `parent` property is defined.
 264
 265 **Example**
 266
 267 ```js
 268 // create an instance of `Base`, this is our first ("base") instance
 269 var first = new Base();
 270 first.foo = 'bar'; // arbitrary property, to make it easier to see what's happening later
 271
 272 // create another instance
 273 var second = new Base();
 274 // create a reference to the first instance (`first`)
 275 second.parent = first;
 276
 277 // create another instance
 278 var third = new Base();
 279 // create a reference to the previous instance (`second`)
 280 // repeat this pattern every time a "child" instance is created
 281 third.parent = second;
 282
 283 // we can always access the first instance using the `base` property
 284 console.log(first.base.foo);
 285 //=> 'bar'
 286 console.log(second.base.foo);
 287 //=> 'bar'
 288 console.log(third.base.foo);
 289 //=> 'bar'
 290 // and now you know how to get to third base ;)
 291 ```
 292
 293 ### [#use](index.js#L293)
 294
 295 Static method for adding global plugin functions that will be added to an instance when created.
 296
 297 **Params**
 298
 299 * `fn` **{Function}**: Plugin function to use on each instance.
 300 * `returns` **{Object}**: Returns the `Base` constructor for chaining
 301
 302 **Example**
 303
 304 ```js
 305 Base.use(function(app) {
 306   app.foo = 'bar';
 307 });
 308 var app = new Base();
 309 console.log(app.foo);
 310 //=> 'bar'
 311 ```
 312
 313 ### [#extend](index.js#L337)
 314
 315 Static method for inheriting the prototype and static methods of the `Base` class. This method greatly simplifies the process of creating inheritance-based applications. See [static-extend](https://github.com/jonschlinkert/static-extend) for more details.
 316
 317 **Params**
 318
 319 * `Ctor` **{Function}**: constructor to extend
 320 * `methods` **{Object}**: Optional prototype properties to mix in.
 321 * `returns` **{Object}**: Returns the `Base` constructor for chaining
 322
 323 **Example**
 324
 325 ```js
 326 var extend = cu.extend(Parent);
 327 Parent.extend(Child);
 328
 329 // optional methods
 330 Parent.extend(Child, {
 331   foo: function() {},
 332   bar: function() {}
 333 });
 334 ```
 335
 336 ### [#mixin](index.js#L379)
 337
 338 Used for adding methods to the `Base` prototype, and/or to the prototype of child instances. When a mixin function returns a function, the returned function is pushed onto the `.mixins` array, making it available to be used on inheriting classes whenever `Base.mixins()` is called (e.g. `Base.mixins(Child)`).
 339
 340 **Params**
 341
 342 * `fn` **{Function}**: Function to call
 343 * `returns` **{Object}**: Returns the `Base` constructor for chaining
 344
 345 **Example**
 346
 347 ```js
 348 Base.mixin(function(proto) {
 349   proto.foo = function(msg) {
 350     return 'foo ' + msg;
 351   };
 352 });
 353 ```
 354
 355 ### [#mixins](index.js#L401)
 356
 357 Static method for running global mixin functions against a child constructor. Mixins must be registered before calling this method.
 358
 359 **Params**
 360
 361 * `Child` **{Function}**: Constructor function of a child class
 362 * `returns` **{Object}**: Returns the `Base` constructor for chaining
 363
 364 **Example**
 365
 366 ```js
 367 Base.extend(Child);
 368 Base.mixins(Child);
 369 ```
 370
 371 ### [#inherit](index.js#L420)
 372
 373 Similar to `util.inherit`, but copies all static properties, prototype properties, and getters/setters from `Provider` to `Receiver`. See [class-utils](https://github.com/jonschlinkert/class-utils#inherit) for more details.
 374
 375 **Params**
 376
 377 * `Receiver` **{Function}**: Receiving (child) constructor
 378 * `Provider` **{Function}**: Providing (parent) constructor
 379 * `returns` **{Object}**: Returns the `Base` constructor for chaining
 380
 381 **Example**
 382
 383 ```js
 384 Base.inherit(Foo, Bar);
 385 ```
 386
 387 ## In the wild
 388
 389 The following node.js applications were built with `Base`:
 390
 391 * [assemble](https://github.com/assemble/assemble)
 392 * [verb](https://github.com/verbose/verb)
 393 * [generate](https://github.com/generate/generate)
 394 * [scaffold](https://github.com/jonschlinkert/scaffold)
 395 * [boilerplate](https://github.com/jonschlinkert/boilerplate)
 396
 397 ## Test coverage
 398
 399 ```
 400 Statements   : 98.91% ( 91/92 )
 401 Branches     : 92.86% ( 26/28 )
 402 Functions    : 100% ( 17/17 )
 403 Lines        : 98.9% ( 90/91 )
 404 ```
 405
 406 ## History
 407
 408 ### v0.11.2
 409
 410 * fixes https://github.com/micromatch/micromatch/issues/99
 411
 412 ### v0.11.0
 413
 414 **Breaking changes**
 415
 416 * Static `.use` and `.run` methods are now non-enumerable
 417
 418 ### v0.9.0
 419
 420 **Breaking changes**
 421
 422 * `.is` no longer takes a function, a string must be passed
 423 * all remaining `.debug` code has been removed
 424 * `app._namespace` was removed (related to `debug`)
 425 * `.plugin`, `.use`, and `.define` no longer emit events
 426 * `.assertPlugin` was removed
 427 * `.lazy` was removed
 428
 429 ## About
 430
 431 ### Related projects
 432
 433 * [base-cwd](https://www.npmjs.com/package/base-cwd): Base plugin that adds a getter/setter for the current working directory. | [homepage](https://github.com/node-base/base-cwd "Base plugin that adds a getter/setter for the current working directory.")
 434 * [base-data](https://www.npmjs.com/package/base-data): adds a `data` method to base-methods. | [homepage](https://github.com/node-base/base-data "adds a `data` method to base-methods.")
 435 * [base-fs](https://www.npmjs.com/package/base-fs): base-methods plugin that adds vinyl-fs methods to your 'base' application for working with the file… [more](https://github.com/node-base/base-fs) | [homepage](https://github.com/node-base/base-fs "base-methods plugin that adds vinyl-fs methods to your 'base' application for working with the file system, like src, dest, copy and symlink.")
 436 * [base-generators](https://www.npmjs.com/package/base-generators): Adds project-generator support to your `base` application. | [homepage](https://github.com/node-base/base-generators "Adds project-generator support to your `base` application.")
 437 * [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.")
 438 * [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.")
 439 * [base-pkg](https://www.npmjs.com/package/base-pkg): Plugin for adding a `pkg` method that exposes pkg-store to your base application. | [homepage](https://github.com/node-base/base-pkg "Plugin for adding a `pkg` method that exposes pkg-store to your base application.")
 440 * [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.")
 441 * [base-questions](https://www.npmjs.com/package/base-questions): Plugin for base-methods that adds methods for prompting the user and storing the answers on… [more](https://github.com/node-base/base-questions) | [homepage](https://github.com/node-base/base-questions "Plugin for base-methods that adds methods for prompting the user and storing the answers on a project-by-project basis.")
 442 * [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!")
 443 * [base-task](https://www.npmjs.com/package/base-task): base plugin that provides a very thin wrapper around [https://github.com/doowb/composer](https://github.com/doowb/composer) for adding task methods to… [more](https://github.com/node-base/base-task) | [homepage](https://github.com/node-base/base-task "base plugin that provides a very thin wrapper around <https://github.com/doowb/composer> for adding task methods to your application.")
 444
 445 ### Contributing
 446
 447 Pull requests and stars are always welcome. For bugs and feature requests, [please create an issue](../../issues/new).
 448
 449 ### Contributors
 450
 451 | **Commits** | **Contributor** |
 452 | --- | --- |
 453 | 141 | [jonschlinkert](https://github.com/jonschlinkert) |
 454 | 30  | [doowb](https://github.com/doowb) |
 455 | 3   | [charlike](https://github.com/charlike) |
 456 | 1   | [criticalmash](https://github.com/criticalmash) |
 457 | 1   | [wtgtybhertgeghgtwtg](https://github.com/wtgtybhertgeghgtwtg) |
 458
 459 ### Building docs
 460
 461 _(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.)_
 462
 463 To generate the readme, run the following command:
 464
 465 ```sh
 466 $ npm install -g verbose/verb#dev verb-generate-readme && verb
 467 ```
 468
 469 ### Running tests
 470
 471 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:
 472
 473 ```sh
 474 $ npm install && npm test
 475 ```
 476
 477 ### Author
 478
 479 **Jon Schlinkert**
 480
 481 * [github/jonschlinkert](https://github.com/jonschlinkert)
 482 * [twitter/jonschlinkert](https://twitter.com/jonschlinkert)
 483
 484 ### License
 485
 486 Copyright © 2017, [Jon Schlinkert](https://github.com/jonschlinkert).
 487 Released under the [MIT License](LICENSE).
 488
 489 ***
 490
 491 _This file was generated by [verb-generate-readme](https://github.com/verbose/verb-generate-readme), v0.6.0, on September 07, 2017._