Programming is an activity very prone to human error, especially if you have
multiple developers changing the same code-base at the same time.
As more and more features are implemented by different programmers, progress will
often slow to a crawl. Programmers can easily lose overview and step on each others
toes when their code is spread across the code base surrounded by
the code of others.
*delta.js* helps you organize your JavaScript code in terms of *features*.
As it turns out, files, modules, objects, functions (and so on), are not
the right abstractions for describing a feature. But they are very good at
other stuff! This library introduces the notion of a *delta*, which complements
those other constructs.
A delta is the place to gather all the code belonging to a specific feature.
Basically, for each piece of code, you instruct the delta to put that code in
the file, module, object or function where it belongs. That way, the code
can *physically* be gathered in one place, and therefore be easy to maintain.
This has other benefits as well. By having some deltas be explicitly applied
*after* others, you give them permission to overwrite things.
If two deltas that are *unordered* try to overwrite each others code,
you will get a friendly error message. Moreover, by separating your features
so explicitly, you will be able to turn them on or off with a switch, for
either debugging or production.
This might all seem overly complicated at first. But once you get started,
you'll soon fall in love with this approach.
At this time, delta.js is a runtime library. But in concept, deltas could be
applied by a preprocessor. This will be supported by a future version.
## Installation
This library depends only on the [Babel ES6 polyfill](https://babeljs.io/docs/usage/polyfill/). For your convenience, a delta.js version is provided with this polyfill already baked in, but you also have the option of providing it yourself.
### Install using Bower
`delta.js` is available as a [Bower](http://bower.io/) package:
```shell
bower install delta.js
```
Unfortunately, the Babel polyfill is [not distributed through Bower](https://github.com/babel/babel/issues/315). So you'll have to either use the version of delta.js with the polyfill baked in, or you'll have to get the polyfill from someplace else, like NPM.
### Install using NPM
`delta.js` is available as an [NPM](https://www.npmjs.org) package:
```shell
npm install delta.js
```
## Importing `DeltaJs`
The delta.js package offers a [UMD](https://github.com/umdjs/umd) API, so it supports
AMD ([RequireJS](http://requirejs.org/)), CommonJS and script-tags:
```javascript
requirejs(['lib/delta.js/dist/delta.js'], function (DeltaJs) {
// use DeltaJs
});
```
```javascript
var DeltaJs = require('lib/delta.js/dist/delta.js')
// use DeltaJs
```
```html
```
###Files
The `dist` directory offers different files for use in different circumstances.
Use the following table to determine which file to use in your situation.
| File | Description |
| ----------------------------- | -------------------------------------------------------------------------------- |
| `delta.js`,DeltaJs#Feature
* [.newOperationType(name, DeltaSubclass, ProxySubclass)](#DeltaJs#newOperationType)
* [.vp(name, val)](#DeltaJs#vp) ⇒ \*
* [.do()](#DeltaJs#do) ⇒ DeltaJs#Proxy
-----
### Classes
This class offers every functionality you need from delta modeling. Each instance offers its own operation types and variation points and acts as a facade (as in design pattern) to the more specific subsystems of delta.js.
Using multiple DeltaJs instances allows you to use different sets
of deltas and rules in the same project that work independently
from each other. But you will usually need only one DeltaJs
instance per application.
DeltaJs#Proxy{@public}{@method}
string | method name |
| handler | function | a function that takes method arguments, and returns a new `DeltaJs#Delta` instance |
-----
#### *deltaJs*.newFeature(name, options) ⇒ DeltaJs#Feature
| Param | Type | Description |
| --- | --- | --- |
| name | string | the name of the new feature |
| options | object | the (optional) options for the new feature |
**Returns**: DeltaJs#Feature - - the object representing the new feature
-----
#### *deltaJs*.newOperationType(name, DeltaSubclass, ProxySubclass)
This method allows you to tell delta.js about a new kind of delta operation.
This was also done for existing operations like `modify`, `add`, `remove`, and so on.
| Param | Type | Description |
| --- | --- | --- |
| name | string | name of the new operation type |
| DeltaSubclass | function | the new operation class |
| ProxySubclass | function | the optional custom `Proxy` subclass for this operation-type |
-----
#### *deltaJs*.vp(name, val) ⇒ \*
This method indicates a variation point.
| Param | Type | Description |
| --- | --- | --- |
| name | string | a hook by which operations from the core delta model can be applied |
| val | \* | the initial value of this variation point |
**Returns**: \* - - the value of this variation point after applying the appropriate deltas
-----
#### *deltaJs*.do() ⇒ DeltaJs#Proxy
A {DeltaJs} instance has one fundamental {DeltaJs#DeltaModel} instance, which is applied
to any variation points that are encountered. This method is an alias to the eponymous
method on that 'root' delta model. It returns the proxy that allows new delta operations
to be added more easily. It presets the 'feature' option to 'true', but this can be
overwritten manually.
**Returns**: DeltaJs#Proxy - - the proxy to this delta, for easily adding operations
-----
### do(args) ⇒ DeltaJs#Proxy
{@public}{@method}
| Param | Type |
| --- | --- |
| args | Array.<\*> |
-----
## License
`delta.js` is released under the terms of the [MIT license](http://en.wikipedia.org/wiki/MIT_License).
It permits reuse within both open and proprietary software, provided
all copies of the licensed software include a copy of the MIT License
terms and the copyright notice.
## Future Plans
Here is an incomplete list of future plans for this library:
* support for changing HTML and CSS with deltas
* transpiler to resolve deltas at build-time