qix- / eloquent

Make expressive APIs easily and cleanly

Eloquent

Easily build up chaining structures

Example

var eloquent = require('eloquent');

var structure = {
	_constructor: function () { this.flag = false; },

	signal: {
		_getter: function () { this.flag = true; }
	},

	clear: {
		_getter: function () { this.flag = false; }
	},

	util: {
		signalIf: {
			_method: function (cond) {
				if (cond) {
					this.flag = true;
				}
			}
		}
	},

	hasFlag: {
		_returns: true, /* the method should not be wrapped */
		_method: function () {
			return !!this.flag;
		}
	},

	status: {
		_returns: true, /* the getter should not be wrapped */
		_getter: function () {
			return !!this.flag;
		}
	},

	emit: {
		_method: function () {
			if (this.flag) {
				console.log('Signal!');
			}
		}
	}
};

var Signaler = eloquent(structure);

Signaler().emit().signal.emit() // emits
	.clear.emit()
	.signal.clear.emit()
	.util.signalIf(5 > 1).emit(); // emits
// The above statement logs 'Signal!' twice.

console.log(Signaler().signal.hasFlag()); //-> true
console.log(Signaler().util.signalIf(true).status); //-> true

To-Do

Some things that still need to be done

• DRYing out the implementation
• Review/revise the underscore-prefix API (as suggested by Sindre Sorhus)
• Add better ability to mix dynamic properties with non-dynamic properties
• Performance increases (static prototype buildup at creation of Eloquent structure, etc.)

License

Licensed under the MIT License. You can find a copy of it in LICENSE.

eloquent's Issues

Allow `_setter:`

Need to allow _setter to happen.

_alias: []

Allow for getters/methods to have aliases.

var structure = {
  util:
    _alias: ['utility'],  // or non-array, for single member
    /* . . . */
};

/*
     structure.util.xyz
     structure.utility.xyz
*/

_dynamic: true

It'd be nice if we could specify that a getter or method's return value is actually a new chain structure to use. That means we can query an object at call-time and make a completely new structure out of it, instead of having to know about it at the structure definition.

getLabels = -> ['foobar']

structure =
  lookup:
    _dynamic: yes
    _method: -> return "#{(getLabels())[0]}": _getter:-> console.log 'woo!'

Dynamic = eloquent structure

Dynamic().lookup().foobar #-> woo!

.constructor should be non-enumerable

.constructor should not be showing up in the properties list for the generated object.

Allow both _getter and _method

With the implicit need to correct whatever the _getter does, it shouldn't be a restriction to have both _getter and _method properties.

Allow the passage of `this` directly instead of new

Need to be able to allow the passing of a this object directly instead of making eloquent perform new under the hood. This should be enabled via an option.

Returning null from a dynamic handler should fallback to default chain

In _dynamic handlers, if they return null or some other falsey value, then the original chain should be used as a fallback.