npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

breadboard

v9.0.3

Published

Lightweight IOC container for Node.js

Downloads

61

Readme

Breadboard

Code Climate Test Coverage Build Status

Breadboard is an opinionated inversion of control container for Node.js applications.

Motivation

  • Working with require is less than ideal.
    • The same module will have a different key depending on the path of the requiring module.
    • Testing a module in isolation, ie. mocking its dependencies, requires hacky solutions that hijack require calls. This approach is indeterministic, depending on various seemingly unrelated conditions around how the the module you want to mock was defined.
  • Discouraging managing state of the app through side effects when requireing.
  • Single function call to auto-mock a module's dependencies in your tests.

Breadboard will lazily require all your application's dependencies defined in package.json, all Node native modules and all of your application's modules and store them in a dependencies object. The object is exposed to your application's modules by calling the modules as functions, passing the dependencies as an argument. As such, your modules are expected to be wrapped in an extra function returning the desired export value, which Breadboard then calls on application start.

Install

npm install breadboard

Example of a module in your application

Consider this CommonJS module:

//startServer.js

const d = require('debug')('myApp');
const createServer = require('./lib/createServer');

module.exports = () => {
  const server = createServer();

  server.listen(80, () => {
    d('Server listening on port 80');
  });

  return server;
};

The Breadboard equivalent would be:

//startServer.js

// wrap module in factory function
module.exports = ({ // destructure dependencies to get the modules needed
    debug,
    '/lib/createServer': createServer
  }) => {
  // return the core functionality of the module as a function
  return () => {
    const server = createServer();
    const d = debug('myApp');

    server.listen(80, () => {
      d('Server listening on port 80');
    });

    return server;
  };
};

To start your application:


const breadboard = require('breadboard');

breadboard({
  entry: '/index',
  containerRoot: 'app',
  initialState: {
    arbitrary: 'state data'
  },
  blacklist: ['newrelic']
}).then(({deps, entryResolveValue}) => {
  console.log('Application started', deps, entryResolveValue);
});

Further examples

Take a look at examples/kitchen. To run, npm install then npm start.

Module keys

Module keys in a Breadboard app are static, ie. are always relative to the container's root folder, starting with /, and always using / as path separators, no matter the platform. Consider these example module keys:

/lib/getUser
/middleware/getUser
/logger

Keys for native Node.js modules and 3rd party modules remain the same as if you were using require. Breadboard also loads all JSON files. To access them, append .json to the end of the key, eg. /data/userPasswords.json.

API

breadboard(options)

Returns a promise chained to the return value of your application's entry point, which might be another promise or a concrete value.

options

options.entry (String | Function<Object>)

String

Module key for the entry point of the application.

Function<Object>

Will be called as the entry point module, with resolved dependencies as the argument.

options.containerRoot (String)

Path relative to the current working directory, from which all module keys will be resolved

options.initialState (Object)

The argument the entry function will be called with.

options.blacklist (Array<String>)

List of modules from your package.json which you wish Breadboard not to load. If you want to defer a require call to a 3rd party module, put it in the blacklist and require manually in your code.

options.substitutes (Object)

A Breadboard module-key to module mapping to indicate which modules you want to substitute across the whole application with your custom implementation. Useful when testing integration of multiple modules. You could substitute eg. a database connector with a stub to remove a running database as a dependency of your tests.

Testing

In tests require your Breadboard modules as if they were CommonJS modules. You can then supply your own stubs and spies as test doubles. Consider the following example:

Test subject module /index

module.exports = (deps) => {
  return () => {
    const {
      '/widgets/createDough': createDough,
      '/pasta/createPapardelle': createPapardelle,
      'debug': debug
    } = deps;
    const d = debug('pasta');

    d(createPapardelle(createDough()));
  };
};

Test for /index

import { expect } from 'chai';
import mainFactory from '../../app/index';
import sinon from 'sinon';

describe('Main', () => {
  const sandbox = sinon.sandbox.create();
  const debugSpy = sandbox.spy();
  const mockDough = 'dough';
  const mockDependencies = {
    debug: sandbox.stub().returns(debugSpy),
    '/widgets/createDough': sandbox.stub().returns(mockDough),
    '/pasta/createPapardelle': sandbox.spy()
  };
  let main;

  beforeEach(() => {
    main = mainFactory(mockDependencies);
  });
  afterEach(() => {
    sandbox.reset();
  });
  it('calls debug', () => {
    main();
    expect(mockDependencies.debug.calledOnce).to.be.true;
  });
  it('calls createDough', () => {
    main();
    expect(mockDependencies['/widgets/createDough'].calledOnce).to.be.true;
  });
  it('calls createPapardelle with createDough return value', () => {
    main();
    expect(mockDependencies['/pasta/createPapardelle'].calledWith(mockDough)).to.be.true;
  });
});

autoMock

autoMock automatically replaces every dependency of a given Breadboard module with a Sinon.JS stub.

autoMock API

autoMock(factory, options)

factory (Function)

The Breadboard factory function to build the subject to test.

options (Object)

options.mocks (Object)

A Breadboard module-key to module mapping to indicate which modules you want to mock manually.

returns Object<subject, deps, sandbox>

subject

The module returned by factory.

deps

The mock dependencies injected into subject.

sandbox

Instance of a Sinon.JS sandbox.

autoMock example

Test subject module /index

module.exports = (deps) => {
  return function main() {
    const {
      '/widgets/createDough': createDough,
      '/pasta/createPapardelle': createPapardelle,
      'debug': debug
    } = deps;
    const d = debug('pasta');

    d(createPapardelle(createDough()));
  };
};

Test for module /index

import { expect } from 'chai';
import mainFactory from '../../app/index';
import autoMock from 'breadboard/lib/autoMock';

const mockDough = 'dough';
const {subject: main, sandbox, deps} = autoMock(mainFactory);
const debugSpy = sandbox.spy();

deps.debug.returns(debugSpy);
deps['/widgets/createDough'].returns(mockDough);
describe('Main', () => {
  afterEach(() => {
    sandbox.reset();
  });
  it('calls debug', () => {
    main();
    expect(deps.debug.calledOnce).to.be.true;
  });
  it('calls createDough', () => {
    main();
    expect(deps['/widgets/createDough'].calledOnce).to.be.true;
  });
  it('calls createPapardelle with createDough return value', () => {
    main();
    expect(deps['/pasta/createPapardelle'].calledWith(mockDough)).to.be.true;
  });
});