kitsonk / compose

A object composition library

dojo-compose

A composition library.

This library embraces the concepts of "composition" versus classical Object Oriented inheritance. The classical model follows a pattern whereby you add functionality to an ancestor by extending it. Subsequently all other descendants from that class will also inherit that functionality.

In a composition model, the preferred pattern is to create logical feature classes which are then composited together to create a resulting class. It is believed that this pattern increases code reuse, focuses on the engineering of self contained "features" with minimal cross dependency.

Also, all the classes generated by the library are "immutable". Any extension of the class will result in a new class constructor and prototype. This is in order to minimize the amount of unanticipated consequences of extension for anyone who is referencing a previous class.

Features

The examples below are provided in TypeScript syntax. The package does work under JavaScript, but for clarity, the examples will only include one syntax. See below for how to utilize the package under JavaScript.

Class Creation

The library supports creating a "base" class from ES6 Classes, JavaScript constructor functions, or an object literal prototype. In addition an initialization function can be provided.

Creation

The compose module's default export is a function which creates classes. This is also available as .create() which is decorated onto the compose function.

If you want to create a new class via a prototype and create an instance of it, you would want to do something like this:

import compose from 'dojo-compose/compose';

const Foo = compose({
	foo: function () {
		console.log('foo');
	},
	bar: 'bar',
	qat: 1
});

const foo = new Foo();

If you want to create a new class via an ES6/TypeScript class and create an instance of it, you would want to do something like this:

import compose from 'dojo-compose/compose';

class Foo {
	foo() {
		console.log('foo');
	};
	bar: string = 'bar';
	qat: number = 1;
}

const ComposeFoo = compose(Foo);

const foo = new ComposeFoo();

You can also subclass:

import compose from 'dojo-compose/compose';

const Foo = compose({
	foo: function () {
		console.log('foo');
	},
	bar: 'bar',
	qat: 1
});

const MyFoo = compose(Foo);

const foo = new MyFoo();

Creation with Initializer

During creation, compose takes a second optional argument, which is an initializer function. The constructor pattern for all compose classes is to take an optional options argument. Therefore the initialization function should take this optional argument:

import compose from 'dojo-compose/compose';

interface FooOptions {
	foo?: Function,
	bar?: string,
	qat?: number
}

function fooInit(options?: FooOptions) {
	if (options) {
		for (let key in options) {
			this[key] = options[key]
		}
	}
}

const Foo = compose({
	foo: function () {
		console.log('foo');
	},
	bar: 'bar',
	qat: 1
}, fooInit);

const foo1 = new Foo();
const foo2 = new Foo({
	bar: 'baz'
});

Class Extension

TODO: Complete

Mixing in Traits/State

TODO: Complete

Using Generics

compose utilizes TypeScript generics and type inference to type the resulting classes. Most of the time, this will work without any need to declare your types. There are situations though where you may want to be more explicit about your interfaces and compose can accommodate that by passing in generics when using the API.

TODO: Complete

Overlaying Functionality

TODO: Complete

How do I use this package?

For now, until the package is fully published you will need to clone the repository to your local machine:

$ git clone https://github.com/dojo/compose.git

Then you will need to navigate to the root of the repository and do an npm install:

$ npm install

If you don't have Grunt command line installed globally, you will need to also:

$ npm install grunt-cli -g

In order to get a build of the code which you can then use for runtime, you will need to:

$ grunt dist

Which will output UMD modules and a d.ts file for the library to dist. This library also is dependent run-time on dojo-core and includes a compiled version in _modules.

How do I contribute?

We appreciate your interest! Please see the Guidelines Repository for the Contributing Guidelines and Style Guide.

Testing

Test cases MUST be written using Intern using the Object test interface and Assert assertion interface.

90% branch coverage MUST be provided for all code submitted to this repository, as reported by Istanbul’s combined coverage results for all supported platforms.

© 2015 Dojo Foundation & contributors. New BSD license.