![](\"./docs/images/sculptor.jpg\")
\n\nProgramming is an activity very prone to human error, especially if you have\nmultiple developers changing the same code-base at the same time.\nAs more and more features are implemented by different programmers, progress will\noften slow to a crawl. Programmers can easily lose overview and step on each others\ntoes when their code is spread across the code base surrounded by\nthe code of others.\n\n*delta.js* helps you organize your JavaScript code in terms of *features*.\nAs it turns out, files, modules, objects, functions (and so on), are not\nthe right abstractions for describing a feature. But they are very good at\nother stuff! This library introduces the notion of a *delta*, which complements\nthose other constructs.\n\nA delta is the place to gather all the code belonging to a specific feature.\nBasically, for each piece of code, you instruct the delta to put that code in\nthe file, module, object or function where it belongs. That way, the code\ncan *physically* be gathered in one place, and therefore be easy to maintain.\n\nThis has other benefits as well. By having some deltas be explicitly applied\n*after* others, you give them permission to overwrite things.\nIf two deltas that are *unordered* try to overwrite each others code,\nyou will get a friendly error message. Moreover, by separating your features\nso explicitly, you will be able to turn them on or off with a switch, for\neither debugging or production.\n\nThis might all seem overly complicated at first. But once you get started,\nyou'll soon fall in love with this approach.\n\nAt this time, delta.js is a runtime library. But in concept, deltas could be\napplied by a preprocessor. This will be supported by a future version.\n\n\n## Installation\n\n![](\"./docs/images/foundation.jpg\")
\n\nThis 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.\n\n\n### Install using Bower\n\n`delta.js` is available as a [Bower](http://bower.io/) package:\n\n```shell\nbower install delta.js\n```\n\nUnfortunately, 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.\n\n\n### Install using NPM\n\n`delta.js` is available as an [NPM](https://www.npmjs.org) package:\n\n```shell\nnpm install delta.js\n```\n\n## Importing `DeltaJs`\n\nThe delta.js package offers a [UMD](https://github.com/umdjs/umd) API, so it supports\nAMD ([RequireJS](http://requirejs.org/)), CommonJS and script-tags:\n\n```javascript\nrequirejs(['lib/delta.js/dist/delta.js'], function (DeltaJs) {\n // use DeltaJs\n});\n```\n\n```javascript\nvar DeltaJs = require('lib/delta.js/dist/delta.js')\n// use DeltaJs\n```\n\n```html\n\n\n```\n\n\n###Files\n\nThe `dist` directory offers different files for use in different circumstances.\nUse the following table to determine which file to use in your situation.\n\n| File | Description |\n| ----------------------------- | -------------------------------------------------------------------------------- |\n| `delta.js`,![](\"./docs/images/selection.jpg\")
\n\n`DeltaJs` is a class that can be instantiated:\n\n```javascript\nvar deltaJs = new DeltaJs();\n```\n\n`deltaJs` is a context within which all new types of delta operation and all project-specific\nfeatures are localized. It is also home to a core *delta model*, which is the structure that\norganizes and orders a set of deltas.\nUsing multiple `DeltaJs` instances allows you to use different sets of deltas and rules in\nthe same project that work independently from each other. But you'll usually need only one.\n\n\n## The `DeltaJs` API\n\n![](\"./docs/images/coder-generic.jpg\")
\n\nGiven a `DeltaJs` instance, the following methods are available:\n\n### `.vp(name, initialValue)`\n\nThis method creates a *variation point*. It should be used in your code-base wherever\ndeltas may need to make changes. Each variation point needs a unique name for\ndeltas to refer to. The method modifies a value 'in place', and does not make\na copy. For example:\n\n```javascript\nfunction MyClass() {\n this.someMethod = function () {};\n this.someField = 'some value';\n};\ndeltaJs.vp('MyClass', MyClass);\n```\n\nThis allows the selected deltas to modify the `MyClass` class, as well as all of its\nproperties. The `.vp` method also returns the new value. So the following is equivalent\nto the example above:\n\n```javascript\nvar MyClass = deltaJs.vp('MyClass', function MyClass() {\n this.someMethod = function () {};\n this.someField = 'some value';\n});\n```\n\n\n### `.do(name, [options])`\n\nThis function returns a `Proxy` interface that may be used to easily create\nnew deltas / operations in a core delta model that can then target specific\nvariation points:\n\n```javascript\nvar proxy = deltaJs.do('cool-feature', {\n // options\n});\n```\n\nThis `proxy` variable can then be used to specify the modifications its\ncorresponding delta should perform, and where to perform them. For example:\n\n```javascript\nproxy.add('MyClass.prototype.coolMethod', function () {\n\t// do something cool\n}).insert('MyClass.prototype.construct', function () {\n\tthis.coolMethod();\n});\n```\n\nSo when the `'cool-feature'` is selected, this delta adds the new `coolMethod` method\nto `MyClass`, and ensures that it is called by the existing `construct` method.\nA comprehensive list of these operations and how to use them follows later in this document.\n\nLike variation points, deltas in a delta model need a unique name. But deltas and variation\npoints have separate namespaces. In other words: you may give a delta and a variation\npoint the same name. (Thought if you find yourself doing this often, you may not have\nfully understood the point of delta.js.)\n\nNote: For the sake of simplicity, you may assume that deltas and features are the same thing. More advanced users may have reasons to see them as separate entities by providing the option feature: false, but because this option defaults to true, the code above defines both a feature and a delta with the name 'cool-feature', and links them one-to-one. Usually, you don't need to be aware of this, and may treat features and deltas as interchangeable concepts. |
\n\nDeltas can modify values in any number of ways, from completely\nreplacing them with other values, to making fine-grained modifications in a deeply nested\nobject. It does so through well-defined *operations*, which you can specify through the\nvarious methods of a `Proxy` instance.\n\nEvery delta *targets* a specific JavaScript object, which we'll denote as `target` in the\ndescriptions below. All operations of that delta act on one of the properties of `target`.\nThe deltas constructed directly from the delta model target an imaginary root object that\ncontains all variation points as properties. We'll denote this object as `root`.\n\n\n### `.modify(key)`\n\nThis method returns another `Proxy` object that targets `target[key]`,\nallowing us to *step into* a sub-object to make fine-grained modifications\ninside:\n\n```javascript\nvar d1 = deltaJs.do('my-delta'); // d1 targets 'root'\nvar d2 = d1.modify('vp1'); // d2 targets 'root.vp1'\nvar d3 = d2.modify('foo').modify('bar'); // d3 targets 'root.vp1.foo.bar'\n```\n\nFor convenience, the `key` can also be given as a dot-separated list:\n\n```javascript\nvar d4 = d1.modify('vp1.foo.bar'); // d4 also targets 'root.vp1.foo.bar'\n```\n\nThe `key` is then usually referred to as a *path*.\nThis also works for the all the other operations below. It implicitly\nconstructs a `.modify` chain to reach the right-most key.\n\nNote: Because of this shorthand notation, property names that actually\ncontain the . character are not supported (at least for now). If there is any need for this to change, please open a GitHub issue. |
![](\"./docs/images/factory.jpg\")
\n\nHere is an incomplete list of future plans for this library:\n\n* support for changing HTML and CSS with deltas\n* transpiler to resolve deltas at build-time\n\n