flipflop/node

Just Another IOC Library

flipflop node is a convenient wrapper around the flipflop core package. declare your (a)sync dependencies easily without worrying about where they are or how they're loaded.

Install

npm install --save @flipflop/node

Usage

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

example.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';
    }
  }
]

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 package syntax. flipflop node will find your modules and create a flipflop core instance with those modules loaded into it.

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

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

Why?

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 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.

Globs

Flipflop Node uses 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 thenable (a promise) if your module has to do some async stuff

dist/my-awesome-module.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

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

dist/index.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

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

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

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.

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

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
  });