npm package: @flipflop/node
Description: Just Another IOC Library. This is the node.js flipflop library.
Author: Craig Lafferty craigplafferty@gmail.com
Latest version: 0.0.6

# flipflop/node

Just Another IOC Library

<img src="https://github.com/craigplafferty/flipflop-node/blob/master/docs/img/flipflop.png?raw=true" alt="flipflops">

flipflop node is a convenient wrapper around the flipflop core [package](https://www.npmjs.com/package/@flipflop/core). declare your (_**a**_)sync
dependencies easily without worrying about where they are or how they're loaded.

[![Build Status](https://travis-ci.org/craigplafferty/flipflop-node.svg?branch=master)](https://travis-ci.org/craigplafferty/flipflop-node)

### Install

```bash
npm install --save @flipflop/node
```

### Usage

Use flipflop node to find your dependencies for you instead of requiring them.

`example.js`

```js
// export names prefixed with @ to have flipflop create a named module
exports['@some-module'] = {
  value: 123
}

exports['@some-other-module'] = {
  dependencies: ['@some-module'],
  provider: (someModule)=>{
    console.log(someModule);
    return 456
  }
}

// export @ by itself to let flipflop node know that you want a raw flipflop core
// instance passed to you (you might want to do some custom stuff)
exports['@'] = flipflop => {
  flipflop.module({
    dependencies: ['#some-collection'],
    provider: someCollection=>{
      console.log(someCollection); // [...]
    }
  });
}

// export @@ by itself to let flipflop know that you want to create some modules
// without names
exports['@@'] = [
  {
    dependencies: ['@some-module', '@some-other-module'],
    memberOf: ['some-collection'],
    provider: (someModule, someOtherModule)=>{
      console.log(someModule + '' + someOtherModule); // 123456
      return 'foo';
    }
  },
  {
    dependencies: ['@some-module', '@some-other-module'],
    memberOf: ['some-collection'],
    provider: (someModule, someOtherModule)=>{
      console.log(someModule + someOtherModule); // 579
      return 'bar';
    }
  },
  {
    dependencies: ['@some-module', '@some-other-module'],
    provider: (someModule, someOtherModule)=>{
      console.log(someOtherModule - someModule); // 333
      return 'baz';
    }
  }
]
```

```js
let ff = require('@flipflop/node');

ff(['./example.js'])
  .then(flipflop=>{
    flipflop.load()
      .then(modules=>{
        // your loaded modules are resolved for debugging purposes
      })
      .catch(err=>{
        // if one of your modules blows up it will most likely show up here
      })
  })
```

flipflop node finds and loads all of the dependencies that you've defined. Just
tell flipflop node where to find them with a glob using the
[glob-all](https://www.npmjs.com/package/glob-all) package syntax.
flipflop node will find your modules and create a
[flipflop core](https://www.npmjs.com/package/@flipflop/core) instance with those
modules loaded into it.

```js
let ff = require('@flipflop/node');

ff(['./dist/**/*.js'])
  .then(flipflop=>{
    flipflop.load();
  })
```

### Why?

```js
require('../../../../../module.js');
```

That's a huge pain to refactor and can get messy quickly. Want to reorganize your
project? No problem, with flipflop you can just start moving things around.

Figuring out where your modules are and how to load them is something that your
computer can do pretty easily so quit wasting your time with `require()` statements.

### FlipflopCore

When you call flipflop node (`require('@flipflop/node')()`) a promise will be
returned that will resolve a [FlipflopCore](https://www.npmjs.com/package/@flipflop/core)
instance. Flipflop node tries not to abstract the core library too much so that
you have the same control that you do using the core library. All of the
same methods are available to you. You can checkout the full flipflop core API
[here](https://www.npmjs.com/package/@flipflop/core#api).

### Globs

Flipflop Node uses [glob-all](https://www.npmjs.com/package/glob-all) to find
your files. For glob questions reference the glob-all documentation.

> Relative paths probably won't work in most cases because of how glob-all is
being used so if in doubt use path.resolve() to prefix your globs.

### Load asynchronous dependencies

Make your module's value an [A+ compliant](https://promisesaplus.com/) thenable _(a promise)_ if your module has to do some async stuff


#### `dist/my-awesome-module.js`

```js
exports['@my-awesome-module'] = {
  dependencies: ['@my-other-module'],
  provider: (otherModule)=>{
    return new Promise((resolve, reject)=>{
      setTimeout(()=>{
        resolve(`This is otherModule's value: ${otherModule}`);
      }, 2000);
    });
  }
}
```

#### `dist/my-other-module.js`

```js
exports['@my-other-module'] = {
  name: 'my-other-module',
  value: new Promise((resolve, reject)=>{
    setTimeout(()=>{
      resolve('my async value');
    }, 2000);
  });
}
```

#### `dist/index.js`

```js
exports['@@'] = [
  {
    dependencies: ['@my-awesome-module'],
    provider: (awesomeModule)=>{
      console.log(awesomeModule);
      // after 4 seconds we get 'This is otherModule's value: my async value!'
    }
  }
]
```

#### `index.js`

```js
let ff = require('@flipflop/node');

ff(['./dist/*.js'])
  .then(flipflop=>{
    flipflop
      .load();
  });
```

### Use modules from another FlipflopNode or FlipflopCore instance

`require('@flipflop/node')(globArray [,flipflopInstances])`

You can pass an array of flipflopInstances as a second argument to flipflop node
and the modules from those instances will be merged into the created flipflop
instance. The items in the array can be a FlipflopCore instance, a promise that
resolves a FlipflopCore instance, or a string. The string should resolve to a
module that when `require()`'d will be either a FlipflopCore instance or a
Promise that resolves one.

#### `index.js`

```js
let ffn = require('@flipflop/node');
let ffc = require('@flipflop/core');
ffn([], ['test', ffn([]), new ffc()])
  .then(flipflop=>{
    flipflop
      .module({
        dependencies: ['@test.sayHi'],
        provider: sayHi=>{
          console.log(sayHi()); // hi!
        }
      })
      .load();
  });
```

#### `node_modules/test/index.js`

```js
let ff = require('@flipflop/core');

let flipflopCore = new ff();

flipflopCore.module({
  name: 'test.sayHi',
  value: ()=>{
    return 'hi!';
  }
})

module.exports = flipflopCore;
```

### Require fallback

flipflop node will automatically `require()` modules for you if you haven't
defined them yourself.

#### `fs.js`

Let's make a native fs module promise wrapper.

```js
exports['@fsp'] = {
  dependencies: ['@fs'],
  provider: (fs)=>{  // we didn't define 'fs' so it get required() by flipflop for us
    return {
      readFile: (path, encoding)=>{
        return new Promise((resolve, reject)=>{
          fs.readFile(path, encoding, (err, results)=>{
            if(err){
              return reject(err);
            }else{
              return resolve(results);
            }
          })
        });
      },
      ...
    };
  }
}
```

## `API`

### `flipflopNode(globArray [,flipflopInstances])` | Promise | FlipflopCore

Calling the flipflopNode function returns a Promise that resolves a new
FlipflopCore instance with modules loaded from modules defined in the the `globArray`

* `globArray` _optional_ __string__ | __Array__ a single glob string or an array of glob strings
* `flipflopInstances` __Array__ an array of FlipflopCore instances, Promises
that resolve FlipflopCore instances, or strings that resolve to either of the previous

```js
let flipflopNode = require('@flipflop/node');

// globString
flipflopNode('dist/*.js');

// globArray
flipflopNode([
  'dist/modules/*.js',
  'dist/components/*.js'
]);

// flipflopInstances
flipflopNode([], ['node-module', './local-module', flipflopNode(), new FlipflopCore]);


// return a promise that resolves a flipflop core instance
flipflopNode([])
  .then(flipflop=>{
    console.log(flipflop.isFlipflopCore); // true
  });
```