brikz/README.md

Brikz

Reconfigurable micro composition system.

Why

The motivation for creating bricks was splitting big monolithic code into pieces. I wanted the tool that builds up an equvivalent of big legacy object (containing working code as well as API) from small parts. Additionally, I wanted to be able to change the parts involved at runtime (like, loading the system, then taking loader away). This is important not primarily from memory or performance PoV, even if it can help for embedded devices, but primarily from the design PoV. The less parts are actually needed to successfully run the system, the less spaghetti the code is. I also believe that trying to achieve this, I must do the refactorings that fix lots of other things in the code as a by-product.

What

Brikz is the system that assembles the resulting object (API) from parts. These parts are simply put into the brikz object. At any time you can reconfigure the parts (by simple assigment/deletion) and ask brikz object to rebuild; the rebuilding process reassembles the API object on the fly.

How

Brikz aims to be minimal, so just copy it and include it where appropriate (it is just one Brikz constructor). Then instantiate it:

  var api = /* skeleton of my object */;
  var brikz = new Brikz(api);

Then, you should have some parts:

function Foo(brikz, api) {
  this.internalFoo = function () { ... }:
  api.publishedFoo = function () { ... }:
}

function Bar(brikz, api) {
  this.internalBar = function () { ... };
  api.publishedBar = function () {
    ...;
    // use brikz.foo and brikz.foo.internalFoo as you see fit
    // it now contains the object, not the factory
    // You can _not_ use api.publishedFoo directly in Bar,
    // but you can use it in any code to be run later.
    ...;
  };
}
Bar.deps = ["foo"];

The deps array synchronously tries to process part named foo before processing bar. Thus, if you have circular dependencies, you end up with stack overflow. Don't have them. :wink:

You then put the parts in brikz object, rebuild it and you have api ready for use:

  brikz.foo = Foo;
  brikz.bar = Bar;
  brikz.rebuild();

  api.publishedBar(...);

You can add / delete / change parts later and call rebuild again. Parts that are not functions, are left as is (their internal as well as API part); parts that are functions are instantiated again and merged in. Parts that are nulled are removed.

Advanced use

TBD