NOTE: This package is no longer being maintained. If you are interested in taking over as maintainer or are interested in the npm package name, get in touch by creating an issue.

Synopsis

mixed is a minimalist, lightweight, ES3-compatible function to mix Constructor functions and their prototypes into instance objects.

Rationale

There are seem to be two common approaches to dealing with mixins:

1. Mixins are special constructor functions that take an optional instance argument to augment an existing instance rather than the this context. This makes for very nice syntax, but requires the author to support mixing intentionally.

2. Mixins are just collections of methods. In this case mixing is practically equivalent to the functionality already provided by aug or jQuery's $.extend function.

The first approach (used by many libraries in component) provides a lot of power and flexibility, representing the same functionality mixins provide in class-based languages. However, the overhead of providing a mixin mechanism for each constructor individually seems obviously redundant.

Additionally, modifying the constructor's argument list to allow using it as a mixin seems both intrusive and limitting, as many constructors would normally expect to be passed a configuration object or initial parameters.

mixed tries to solve this issue by both providing a standalone mixin function, to allow mixing any given constructor into any given object, and also providing a thin wrapper interface to turn any plain old argument-free constructor function into a component-style mixin that can be called either as a constructor (with the new keyword) or with an object to mix into (as the sole argument).

Install

Node.js

With NPM

npm install mixed

From source

git clone https://github.com/pluma/mixed.git
cd mixed
npm install
make && make dist

Browser

With component

component install pluma/mixed

Learn more about component.

With bower

bower install mixed

Learn more about bower.

With a CommonJS module loader

Download the latest minified CommonJS release and add it to your project.

Learn more about CommonJS modules.

With an AMD module loader

Download the latest minified AMD release and add it to your project.

Learn more about AMD modules.

As a standalone library

Download the latest minified standalone release and add it to your project.

<script src="/your/js/path/mixed.globals.min.js"></script>

This makes the mixed module available in the global namespace.

Basic mixin usage example

function Liquor() {
    this.alcoholContent = 0.8;
}
Liquor.prototype = {
    burn: function() {
        this.alcoholContent *= 0.5;
        if (this.alcoholContent > 0.2) {
            console.log('*FOOSH*');
        } else {
            console.log('*fizzle*');
        }
    }
};

var cocktail = {};
console.log(cocktail.alcoholContent); // undefined
console.log(cocktail.burn); // undefined

mixed.mixin(Liquor, cocktail);
console.log(cocktail.alcoholContent); // 0.8
cocktail.burn(); // *FOOSH*
console.log(cocktail.alcoholContent); // 0.4

Basic mixable usage example

function Liquor() {
    this.alcoholContent = 0.8;
}
Liquor.prototype = {
    burn: function() {
        this.alcoholContent *= 0.5;
        if (this.alcoholContent > 0.2) {
            console.log('*FOOSH*');
        } else {
            console.log('*fizzle*');
        }
    }
};
Liquor = mixed.mixable(Liquor);

var cocktail = {};
console.log(cocktail.alcoholContent); // undefined
console.log(cocktail.burn); // undefined

Liquor(cocktail);
console.log(cocktail.alcoholContent); // 0.8
cocktail.burn(); // *FOOSH*
console.log(cocktail.alcoholContent); // 0.4

API

mixin(ctor:Function, obj, args…):Object

Applies the given constructor to the given object and returns the object.

Copies each of the constructor's prototype's properties to the given object, then calls the constructor as a function with the object as its context (this).

Any additional arguments will be passed to the constructor function.

NOTE: If you simply want to merge two instances rather than messing with constructors and prototypes, consider using aug instead.

mixable(ctor:Function, args…):Function

Creates a wrapper around the given constructor function that can be called either as a constructor (using the new keyword) or as a mixin (with the object to mix into as the sole argument). The constructor's prototype will be copied over to the wrapper function.

If called as a mixin, this wrapper behaves exactly as if mixin was called directly.

Acknowledgments

This library was influenced by TJ Holowaychuk's work on component.

Unlicense

This is free and unencumbered public domain software. For more information, see http://unlicense.org/ or the accompanying UNLICENSE file.