deco

Composable decorators for ES6. You're Node.js code will never have been as organized, reusable, and pluggable.

Summary

• Provides class-like decorators and factories while avoiding problematic classical concepts like new, super, extends, and instanceof.
• Compose objects, factory functions, ES5 constructors, and/or ES6 classes with one simple interface.
• Write code in a style similar to partial classes.
• Optionally, set default options for each class.
• Easily create properties that use private data internally.

Usage Overview

The main functionality is provided by the Deco() function. It is used to compose decorators.

Decorators are defined when they are built. They are immutable.

const Deco = require('deco');
 
const Decorator = Deco({
  ƒ () { return 4 }
});

Decorators can decorate existing objects.

const existing = {
  g () { return 5 }
};
 
Decorator.call(existing);
expect(existing.ƒ()).to.equal(4);
expect(existing.g()).to.equal(5);

Decorators can be used as factories. Factories are functions that create objects but don't require using the new keyword.

const o = Decorator();
expect(o.ƒ()).to.equal(4);

Custom constructor logic can be supplied.

const Beer = Deco({
  constructor () {
    this.created = Date.now();
  }
});
 
const pint = Beer();
expect(pint.created).to.be.above(1469655052201);

Decorators can be composed into new decorators:

const Lager = Deco(Beer, {
  fermentation () { return 'bottom' }
});
 
const drink = Lager();
expect(drink.created).to.be.above(1469655052201);
expect(drink.fermentation()).to.equal('bottom');

Decorators execute the constructors of composed definitions sequentially.

const TastyBeer = Deco(Beer, {
  constructor (a) {
    this.a = a;
    this.tasted = this.created + 86400000;
  }
});
 
const tasty = TastyBeer(1);
expect(tasty.a).to.equal(1);
expect(tasty.created).to.be.above(1469655052201);
expect(tasty.tasted).to.be.above(1469741452201);

Partials / Loading from File

A directory of decorator files can be composed into a single decorator handily.

const Composed1 = Deco.loadFrom('./test/decorators');
expect(Composed1().flavor).to.equal('bitter');
expect(Composed1().type).to.equal('liqueur');

Specific files can be loaded from the directory in a specified order.

const Composed2 = Deco.loadFrom('./test/decorators', 'd2', 'd1');
expect(Composed2().flavor).to.equal('bitter');
expect(Composed2().type).to.equal('liqueur');

Use Deco.load instead of loadFrom to load definition files from the current directory.

Composition

You can have factories create objects of custom instances by passing in a constructor that returns an object.

const ErrorDecorator = Deco(Error);
expect(ErrorDecorator()).to.be.an.instanceof(Error);
 
// or...
 
const OtherDecorator = Deco(() => ({ a: 1 }));
const other = OtherDecorator();
expect(other.a).to.equal(1);
 
// and even...
 
const C = class {
  ƒ () { return 1 }
};
 
const CompatibleDecorator = Deco(C, {
  g () { return 2 }
});
 
const xyz = CompatibleDecorator();
 
expect(xyz).to.be.an.instanceof(C);
expect(xyz.ƒ()).to.equal(1);
expect(xyz.g()).to.equal(2);
 
// or compose several types of definitions in one go:
 
const AllAtOnce = Deco(C, function () { this.x = 'y' }, { z: 100 });
const all = AllAtOnce();
expect(all).to.be.an.instanceof(C);
expect(all.ƒ()).to.equal(1);
expect(all.x).to.equal('y');
expect(all.z).to.equal(100);

Defaults

Decorators can be associated with a defaults object. Here's an example using the defaults in a constructor.

const DecoratorWithDefaults = Deco({
  defaults: { a: 1, c: 4 }
});
 
const CheckDecoratorWithDefaults = Deco(DecoratorWithDefaults, {
  constructor (given) {
    const options = this.defaults(given);
    expect(options).to.equal({ a: 1, b: 2, c: 3 });
  }
});
 
CheckDecoratorWithDefaults({ b: 2, c: 3 });

Decorators have a defaults method which can be used to create a new immutable decorator by merging in new defaults.

const DecoratorNewDefaults = DecoratorWithDefaults.defaults({ a: 2, b: 2 });
const CheckDecoratorNewDefaults = Deco(DecoratorNewDefaults, {
  constructor () {
    expect(this.defaults()).to.equal({ a: 2, b: 2, c: 4 });
  }
});
 
CheckDecoratorNewDefaults();

Private Data

Deco provides an easy mechanism for creating properties backed with private data.

const hidden = Deco.hidden();
 
const DecoratorWithSecrets = Deco({
  get knox () {
    return hidden(this).knox
  },
  set knox (a) {
    hidden(this).knox = a + 1;
    return this.knox;
  }
});
 
const o1 = DecoratorWithSecrets();
expect(o1.knox).to.equal(undefined);
o1.knox = 1;
expect(o1.knox).to.equal(2);

Try deco in your project today!

Contact

• http://kun.io/
• @wprl
• [e-mail]

© 2016 Kun.io Labs