defuse/README.md

A poor man's module namespacing solution for the browser

# defuse

A poor man's module namespacing solution for the browser.  

```javascript
defuse.def('foo.bar', function(exports) {
    exports.baz = function() { return 'qux'; }
});

console.log(defuse.use('foo.bar').baz());
```

## Why?
For simple projects, I sometimes don't need the power offered by module loaders, bundlers or similar tools, and would prefer to just have a way of namespacing the project's modules, as opposed to a complete solution for `require`ing and using everything, vendor libraries included.

Browserify is really awesome, my only reason for not using it for every browser-based project is that I have yet to find a nice way of testing browserified projects using phantomjs. For projects that don't use the DOM, or projects which make sense both in node and the browser, browserify is perfect. The tests can be done from node, and each module to be tested can simply be `require`d.  Things aren't as simple when phantomjs is involved. Short of writing a very awkward `require` utility available in the tests, we need to test each module using the entire browserified bundle. This makes writing tests a bit more difficult, since the stack traces are less useful than if the modules were still separate files.

There are several namespacing patterns commonly used in browser-based projects that are simple enough to use without needing to bring in yet another library. For example:

```javascript
// thing.js
(function(exports) { ... })(window.thing = {});

// subthing.js
(function(exports) { ... })(window.thing.subthing = {});
```

The problem with simply using those patterns is that you end up needing to add each new script to the list of scripts to be concatenated in your Gruntfile/makefile/whatever you use. Simply using a glob pattern like `*.js` is out of the question, since *ordering matters* (for eg, `subthing.js` uses things defined in `thing.js`, so it needs to appear after `thing.js`). This isn't a major problem, so most people just live with it. What I really wanted was to avoid implicit dependencies amongst scripts (one of the things [AMD solves](http://requirejs.org/docs/whyamd.html#amd)), but boilerplate-free and as simple to use as CommonJS. defuse is my attempt at this, by only loading a module when you `use` it for the first time, as opposed to when it is `def`ined (lazy loading), but in a way that feels (to me) closer to CommonJS.

## API

### `defuse.def(name, loader)`
Defines a module.

```javascript
defuse.def('foo.bar', function(exports) {
    exports.baz = function() { return 'qux'; }
});
```

### `defuse.use(name)`
Returns the exports of a defined module.

```javascript
console.log(defuse.use('foo.bar').baz());
```

### `defuse.undef(name)`
Undefines a module.

```javascript
defuse.undef('foo.bar');
```

### `defuse.pollute()`
Assigns defuse's api methods to the global namespace. Excludes itself, `unpollute` and `exports`. If you would like these methods available globally out of the box, use the `defuse-global.js` or `defuse-global.min.js` builds.

```javascript
defuse.pollute();

// we can now do this:
def('foo.bar', function() { ... });
use('foo.bar');
```

### `defuse.unpollute()`
Restore properties the global object had and remove properties that the global object did not have before `pollute`.

```javascript
def = 'tones'

defuse.pollute();
def('foo.bar', function() { ... });

defuse.unpollute();
console.log(def);
// => 'tones'
```

### `defuse.exports()`
Returns a shallow copy of the defuse api. Useful for mixing in. Excludes itself, `pollute` and `unpollute`.

```javascript
_.mixin(defuse.exports());

// we can now do this:
_.def('foo.bar', function() { ... });
_.use('foo.bar');
```