source: trip-planner-front/node_modules/base/README.md@ 76712b2

Last change on this file since 76712b2 was 6a3a178, checked in by Ema <ema_spirova@…>, 3 years ago

initial commit

  • Property mode set to 100644
File size: 16.5 KB
Line 
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
13Install with [npm](https://www.npmjs.com/):
14
15```sh
16$ npm install --save base
17```
18
19## What is Base?
20
21Base is a framework for rapidly creating high quality node.js applications, using plugins like building blocks.
22
23### Guiding principles
24
25The 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
37Base 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
47When deciding on method to add or remove, we try to answer these questions:
48
491. Will all or most Base applications need this method?
502. Will this method encourage practices or enforce conventions that are beneficial to implementors?
513. Can or should this be done in a plugin instead?
52
53### Composability
54
55**Plugin system**
56
57It couldn't be easier to extend Base with any features or custom functionality you can think of.
58
59Base plugins are just functions that take an instance of `Base`:
60
61```js
62var base = new Base();
63
64function plugin(base) {
65 // do plugin stuff, in pure JavaScript
66}
67// use the plugin
68base.use(plugin);
69```
70
71**Inheritance**
72
73Easily inherit Base using `.extend`:
74
75```js
76var Base = require('base');
77
78function MyApp() {
79 Base.call(this);
80}
81Base.extend(MyApp);
82
83var app = new MyApp();
84app.set('a', 'b');
85app.get('a');
86//=> 'b';
87```
88
89**Inherit or instantiate with a namespace**
90
91By 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
94var Base = require('base');
95// get and set values on the `base.cache` object
96var base = Base.namespace('cache');
97
98var app = base();
99app.set('foo', 'bar');
100console.log(app.cache.foo);
101//=> 'bar'
102```
103
104## API
105
106**Usage**
107
108```js
109var Base = require('base');
110var app = new Base();
111app.set('foo', 'bar');
112console.log(app.foo);
113//=> 'bar'
114```
115
116### [Base](index.js#L44)
117
118Create 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`
129var app = new Base({isApp: true}, {abc: true});
130app.set('foo', 'bar');
131
132// values defined with the given `config` object will be on the root of the instance
133console.log(app.baz); //=> undefined
134console.log(app.foo); //=> 'bar'
135// or use `.get`
136console.log(app.get('isApp')); //=> true
137console.log(app.get('foo')); //=> 'bar'
138
139// values defined with the given `options` object will be on `app.options
140console.log(app.options.abc); //=> true
141```
142
143### [.is](index.js#L107)
144
145Set 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
155app.is('foo');
156console.log(app._name);
157//=> 'foo'
158console.log(app.isFoo);
159//=> true
160app.is('bar');
161console.log(app.isFoo);
162//=> true
163console.log(app.isBar);
164//=> true
165console.log(app._name);
166//=> 'bar'
167```
168
169### [.isRegistered](index.js#L145)
170
171Returns true if a plugin has already been registered on an instance.
172
173Plugin implementors are encouraged to use this first thing in a plugin
174to prevent the plugin from being called more than once on the same
175instance.
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
190var base = new Base();
191base.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
197base.use(function(app) {
198 if (app.isRegistered('myPlugin', true)) return;
199 // do stuff to `app`
200});
201```
202
203### [.use](index.js#L175)
204
205Define 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
218var app = new Base()
219 .use(foo)
220 .use(bar)
221 .use(baz)
222```
223
224### [.define](index.js#L197)
225
226The `.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`
238app.define('render', function(str, locals) {
239 return _.template(str)(locals);
240});
241```
242
243### [.mixin](index.js#L222)
244
245Mix 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
256app.mixin('foo', function() {
257 // do stuff
258});
259```
260
261### [.base](index.js#L268)
262
263Getter/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
269var first = new Base();
270first.foo = 'bar'; // arbitrary property, to make it easier to see what's happening later
271
272// create another instance
273var second = new Base();
274// create a reference to the first instance (`first`)
275second.parent = first;
276
277// create another instance
278var third = new Base();
279// create a reference to the previous instance (`second`)
280// repeat this pattern every time a "child" instance is created
281third.parent = second;
282
283// we can always access the first instance using the `base` property
284console.log(first.base.foo);
285//=> 'bar'
286console.log(second.base.foo);
287//=> 'bar'
288console.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
295Static 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
305Base.use(function(app) {
306 app.foo = 'bar';
307});
308var app = new Base();
309console.log(app.foo);
310//=> 'bar'
311```
312
313### [#extend](index.js#L337)
314
315Static 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
326var extend = cu.extend(Parent);
327Parent.extend(Child);
328
329// optional methods
330Parent.extend(Child, {
331 foo: function() {},
332 bar: function() {}
333});
334```
335
336### [#mixin](index.js#L379)
337
338Used 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
348Base.mixin(function(proto) {
349 proto.foo = function(msg) {
350 return 'foo ' + msg;
351 };
352});
353```
354
355### [#mixins](index.js#L401)
356
357Static 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
367Base.extend(Child);
368Base.mixins(Child);
369```
370
371### [#inherit](index.js#L420)
372
373Similar 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
384Base.inherit(Foo, Bar);
385```
386
387## In the wild
388
389The 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```
400Statements : 98.91% ( 91/92 )
401Branches : 92.86% ( 26/28 )
402Functions : 100% ( 17/17 )
403Lines : 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
447Pull 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
463To 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
471Running 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
486Copyright © 2017, [Jon Schlinkert](https://github.com/jonschlinkert).
487Released 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._
Note: See TracBrowser for help on using the repository browser.