Old README

Structuring for Composability

If you are writing a microjs style library with zero dependencies, then you don't have to do anything special at all. Just fork this library, and create a formula file for your library and make a pull request. We'll bring it straight in 99.9% if the time.

A proposed formula file is shown below, in this case for the eventing library eve:

# dsc: Tiny event helping JavaScript library.
# url: http://dmitry.baranovskiy.com/eve/
# bug: https://github.com/DmitryBaranovskiy/eve/issues

github://DmitryBaranovskiy/eve/eve.js

The formula file is a plain text file with hash comment lines that will be used to populate a simple online directory and search interface for compose-js.

But my library has dependencies

Let's face it, if we are all building 0 dependency libraries, then something is wrong and JS really isn't going to get that far. More than likely you are building on someone else's work and need that library available to do something meaningful. My thoughts for dealing with this is making two versions of your library available in your source repo. Firstly, one that includes all the prerequisite libraries in a single js file and another that has some flag comments saying which libraries are required when your library is being composed into a larger work. At this stage I'm thinking a single line comment, immediately following by a plus (+) character would do the job nicely.

For instance, here is what I'm thinking with regards to my experimental IoC library:

//+ eve
//+ underscore
//+ matchme

(function(glob) {
    var reAttributes = /^(.*)\[(.*)\]$/,
        reAttr = /^(\+)?(\w+)\=?(.*)$/;
    
    // removed :)
    
    var IoC = new ControlScope();
    
    (typeof module != "undefined" && module.exports) ? (module.exports = IoC) : (typeof define != "undefined" ? (define("IoC", [], function() { return IoC; })) : (glob.IoC = IoC));
})(this);

The compose command line tool would interpret these comments and replace them with the appropriate recipe includes (using cached copies where available to speed up the build process).

In the event that the IoC library was composed with another library that uses eve (for example) or with an application that required eve the two composition directives (//+ eve) would be replaced by a single directive and eve would only be included once. This is far from being a new or novel technique, but one that has typically not been done well with regards to online repositories and existing JS build solutions.

Summary

In summary, the purpose of this project is to increase the re-usability of JS libraries and to make a distinction between building and composing JS libraries and applications. By making this distinction a few things become easier to deal with, including the fact that some libraries may choose to include a compile step during the build process making use of languages such as coffee-script or roy.

If you have any thoughts on this, please feel free to leave an issue for discussion or hit me up on Twitter.

Potential Discussion Points

• Versioning using semver (via node-semver). Would require repo tagging etc for it to work well / at all.

This is not the first project that I've started to try and deal with this. Interleave takes a different approach and provides you the tools required to compile a standalone library from a number of separate files. After working with Interleave for a while, it become clear to me that while it was strong in some areas it was particularly weak in others.