`dcl`

A minimalistic yet complete JavaScript package for node.js and modern browsers that implements OOP with mixins + AOP at both "class" and object level. Implements C3 MRO to support a Python-like multiple inheritance, efficient supercalls, chaining, full set of advices, and provides some useful generic building blocks. The whole package comes with an extensive test set, and it is fully compatible with the strict mode.

The package was written with debuggability of your code in mind. It comes with a special debug module that explains mistakes, verifies created objects, and helps to keep track of AOP advices. Because the package uses direct static calls to super methods, you don't need to step over unnecessary stubs. In places where stubs are unavoidable (chains or advices) they are small, and intuitive.

Based on ES5, the dcl 2.x works on Node and all ES5-compatible browsers. It fully supports property descriptors, including AOP advices for getters and setters, as well as regular values. If your project needs to support legacy browsers, please consider dcl 1.x.

The library includes a small library of useful base classes, mixins, and advices.

The main hub of everything dcl-related is dcljs.org, which hosts extensive documentation.

Examples

Create simple class:

var A = dcl({
  constructor: function (x) { this.x = x; },
  m: function () { return this.x; }
});

Single inheritance:

var B = dcl(A, {
  // no constructor
  // constructor of A will be called automatically

  m: function () { return this.x + 1; }
});

Multiple inheritance with mixins:

var M = dcl({
  sqr: function () { var x = this.m(); return x * x; }
});

var AM = dcl([A, M]);
var BM = dcl([B, M]);

var am = new AM(2);
console.log(am.sqr()); // 4

var bm = new BM(2);
console.log(bm.sqr()); // 9

Super call:

var AMSuper = dcl([A, M], {
  m: dcl.superCall(function (sup) {
    return function () {
      return sup.call(this) + 1;
    };
  })
});

var ams = new AMSuper(3);
console.log(ams.sqr()); // 16

AOP advices:

var C = dcl(AMSuper, {
  constructor: dcl.advise({
    before: function (x) {
      console.log('ctr arg:', x);
    },
    after: function () {
      console.log('this.x:', this.x);
    }
  }),
  m: dcl.after(function (args, result, makeReturn) {
    console.log('m() returned:', result);
    // let's fix it
    makeReturn(5);
  })
});

var c = new C(1);
// prints:
// ctr arg: 1
// this.x: 1
console.log(c.sqr());
// prints:
// m() returned: 2
// 25

Super call with getters:

var G = dcl({
  constructor: function (x) { this._x = x; },
  get x () { return this._x; }
});

var g = new G(1);
console.log(g.x); // 1

var F = dcl(G, {
  x: dcl.prop({
    get: dcl.superCall(function (sup) {
      return function () {
        return sup.call(this) + 1;
      };
    })
  })
});

var f = new F(1);
console.log(f.x); // 2

Advise an object:

function D (x) { this.x = x; }
D.prototype.m = function (y) { return this.x + y; }

var d = new D(1);
console.log(d.m(2)); // 3

advise(d, 'm', {
  before: function (y) { console.log('y:', y); },
  around: function (sup) {
    return function (y) {
      console.log('around');
      return 2 * sup.call(this, y + 1);
    };
  },
  after: function (args, result) {
    console.log('# of args:', args.length);
    console.log('args[0]:', args[0]);
    console.log('result:', result);
  }
});

console.log(d.m(2));
// prints:
// y: 2
// around
// # of args: 1
// args[0]: 2
// result: 8

Additionally dcl provides a small library of predefined base classes, mixins, and useful advices. Check them out too.

For more examples, details, howtos, and why, please read the docs.

How to install

With npm:

npm install --save dcl

With yarn:

yarn add dcl

With bower:

bower install --save dcl

How to use

dcl can be installed with npm, yarn, or bower with files available from node_modules/ or bower_components/. By default, it uses UMD, and ready to be used with Node's require():

// if you run node.js, or CommonJS-compliant system
var dcl = require('dcl');
var advise = require('dcl/advise');

Babel can have problems while compiling UMD modules, because it appears to generate calls to require() dynamically. Specifically for that dcl comes with a special ES6 distribution located in "/es6/" directory:

// ES6 FTW!
import dcl from 'dcl/es6/dcl';
import advise from 'dcl/es6/advise';

Warning: make sure that when you use Babel you include dcl/es6 sources into the compilation set usually by adding node_modules/dcl/es6 directory.

It can be used with AMD out of box:

// if you use dcl in a browser with AMD (like RequireJS):
require(['dcl'], function (dcl) {
    // the same code that uses dcl
});

// or when you define your own module:
define(['dcl'], function (dcl) {
    // your dcl-using code goes here
});

If you prefer to use globals in a browser, include files with <script> from /dist/:

<script src='node_modules/dcl/dist/dcl.js'></script>

Alternatively, you can use https://unpkg.com/ with AMD or globals. For example:

<script src='https://unpkg.com/dcl@latest/dist/dcl.js'></script>

Documentation

dcl is extensively documented in the docs.

Versions

2.x

2.0.11 — Technical release.
2.0.10 — Refreshed dev dependencies.
2.0.9 — Refreshed dev dependencies, removed yarn.lock.
2.0.8 — Added AMD distro.
2.0.7 — A bugfix. Thx Bill Keese!
2.0.6 — Bugfixes. Thx Bill Keese!
2.0.5 — Regenerated ES6 distro.
2.0.4 — Refreshed dev dependencies, fixed ES6 distro.
2.0.3 — Added ES6 distro.
2.0.2 — Small stability fix + new utility: registry.
2.0.1 — Small corrections to README.
2.0.0 — The initial release of 2.x.

1.x

1.1.3 — 1.x version before forking for 2.x

License

BSD or AFL — your choice.

uhop / dcl

readme