global-configuration

Purpose

Provide what is essentially an explicitly set of frozen global variables which can then be required by any module that needs them.

This can be preferable to having to pass any configuration all the way through your node application, which in turn is usually better than setting global variables.

Installation

$ npm install global-configuration

API

setConfiguration( configuration [, options] )

import setConfiguration from 'global-configuration/set';

• configuration whatever you want to be made available when subsequently importing / requiring global-configuration.
• options object optionally containing the following
  • options.freeze default: true - used to prevent the freezing of the configuration object.
  • options.assign default: false - causes the passed configuration object to have its properties assigned to the existing configuration, rather than replacing it.

clearConfiguration()

import clearConfiguration from 'global-configuration/clear';

This is a testing utility that removes the existing configuration from the require cache. By calling this, calling setConfiguration(configuration) and then re-requiring any target file, that target file will then be returned from require with the new configuration applied.

Example Usage

Server Side

service.js (initiation of server side process)

import setConfiguration from 'global-configuration/set';
// Assuming ./app here exports an express application.
import MyApplication from './app';

// This should probably be the only place you read in environment vars IMO.
setConfiguration({ foo: 'bar' });

new MyApplication();

appLogic.js (somewhere inside the application)

import configuration from 'global-configuration';

function qux() {
    return configuration.foo;
}

qux(); // bar

export default qux;

// If we were to import setConfiguration again and try and set it an error would be thrown:
// once set the configuration cannot be changed unless explicitly stated the first time it is called.

// Equally if we were to import configuration before setConfiguration had been called an error would get thrown at compile time.
// This (the compile time error) is probably the main reason why this package was written.

Client Side

client.js (initiation of client side js, assume compiled via browserify / similar)

import React from 'react';
import Page from './page.jsx';
import setConfiguration from 'global-configuration/set';

(function clientJS() {
    setConfiguration(window.BOOTSTRAP_DATA.configuration);
    React.render(<Page/>, document);
}());

component.js (somewhere inside the client side app)

import React from 'react';
import configuration from 'global-configuration';

const Component = React.createClass({
    render: function render() {
        return (
            <div>{ configuration.foo }</div>
        );
    }
});

export default Component;

Testing

gulp/test.js

import gulp from 'gulp';
import mocha from 'gulp-mocha';
import setConfiguration from 'global-configuration/set';

setConfiguration({ foo: 'baz' }, { freeze: false });

gulp.task('test', function gulpTest() {
    return (
        gulp
            .src([ 'app/**.test.*' ], { read: false })
            .pipe(mocha())
    );
});

appLogic.test.js

import setConfiguration from 'global-configuration/set';
import clearConfiguration from 'global-configuration/clear';
import assert from 'assert';

describe('appLogic', () => {
    it('should return foo from configuration', () => {
        const foos = [ 'alpha', 'beta', 'gamma' ];
        foos.forEach((foo) => {
            // This only works because `freeze: false` was set the first time set was called (in gulp/test.js).
            setConfiguration({ foo: foo });
            const appLogic = require('./appLogic');
            assert(appLogic() === foo);
        });
    });

    afterEach(() => {
        clearConfiguration();
    });
});