Permalink
Browse files

[major] Rename some public methods

Renames `Primus#use` to `Primus#plugin` and `Primus#before` to
`Primus#use`.
  • Loading branch information...
lpinca committed Jun 20, 2016
1 parent 324af13 commit e23eaa9d13aa4312f022a7592f9d5e487065732b
Showing with 116 additions and 131 deletions.
  1. +12 −12 README.md
  2. +2 −2 examples/middleware/index.js
  3. +25 −43 index.js
  4. +2 −2 migration.md
  5. +17 −17 test/middleware.test.js
  6. +35 −31 test/plugin.test.js
  7. +22 −23 test/primus.test.js
  8. +1 −1 test/transformer.base.js
View
@@ -1447,9 +1447,9 @@ of components in Primus are implemented through middleware layers:
- `no-cache`: Add no-cache headers to every HTTP request.
- `x-xss`: Add `X-XSS-Protection` headers to every HTTP request.
-#### Primus.before(name, fn, options, index)
+#### Primus.use(name, fn, options, index)
-The `primus.before` method is how you add middleware layers to your system. All
+The `primus.use` method is how you add middleware layers to your system. All
middleware layers need to be named. This allows you to also enable, disable and
remove middleware layers. The supplied function can either be a pre-configured
function that is ready to answer request/response or an unconfigured
@@ -1458,7 +1458,7 @@ We execute this function automatically with `Primus` as context of the function
and optionally, the options that got provided:
```js
-primus.before('name', function () {
+primus.use('name', function () {
var primus = this;
return function (req, res) {
@@ -1473,12 +1473,12 @@ the function directly:
```js
// sync middleware
-primus.before('name', function (req, res) {
+primus.use('name', function (req, res) {
});
// async middleware
-primus.before('name', function (req, res, next) {
+primus.use('name', function (req, res, next) {
doStuff();
});
```
@@ -1490,7 +1490,7 @@ property to the middleware function and set it to `false` if you don't want it
to be triggered.
```js
-primus.before('name', function () {
+primus.use('name', function () {
function middleware(req, res, next) {
}
@@ -1508,7 +1508,7 @@ argument.
```js
// add a middleware after the first two in the stack
-primus.before('name', function (req, res) {
+primus.use('name', function (req, res) {
}, 2);
```
@@ -1560,12 +1560,12 @@ Plugins are added on the server side in the form of an `Object`:
//
// Require a plugin directly.
//
-primus.use('name', require('metroplex'));
+primus.plugin('name', require('metroplex'));
//
// Or supply it manually with the required object structure
//
-primus.use('name', {
+primus.plugin('name', {
server: function (primus, options) {},
client: function (primus, options) {},
library: 'client side library'
@@ -1594,7 +1594,7 @@ var primus = new Primus(server, { plugin: 'metroplex, primus-emit' })
To remove added plugins you can use the `plugout` method:
```js
-primus.use('name', require('metroplex'));
+primus.plugin('name', require('metroplex'));
primus.plugout('name'); // returns true/false indicating successful removal.
```
@@ -1656,7 +1656,7 @@ easily add new functionality to the socket. For example adding join room
function would be as easy as:
```js
-primus.use('rooms', {
+primus.plugin('rooms', {
server: function (primus) {
var Spark = primus.Spark;
@@ -1700,7 +1700,7 @@ primus.transform('incoming', function (packet) {
These transformations can easily be done in the plugins:
```js
-primus.use('name', {
+primus.plugin('name', {
server: function (primus) {
primus.transform('outgoing', function (packet) {
packet.data = 'foo';
@@ -59,8 +59,8 @@ var server = http.createServer(app)
// first will populate `req.signedCookies` and the second `req.session` for the
// requests captured by Primus.
//
-primus.before('cookies', cookies);
-primus.before('session', primusSession, { store: store });
+primus.use('cookies', cookies);
+primus.use('session', primusSession, { store: store });
primus.on('connection', function connection(spark) {
//
View
@@ -109,11 +109,11 @@ function Primus(server, options) {
//
if ('string' === typeof options.plugin) {
options.plugin.split(/[, ]+/).forEach(function register(name) {
- primus.use(name, name);
+ primus.plugin(name, name);
});
} else if ('object' === typeof options.plugin) {
for (key in options.plugin) {
- this.use(key, options.plugin[key]);
+ this.plugin(key, options.plugin[key]);
}
}
@@ -319,13 +319,13 @@ Primus.readable('initialise', function initialise(Transformer, options) {
//
// Add our default middleware layers.
//
- this.before('forwarded', require('./middleware/forwarded'));
- this.before('cors', require('./middleware/access-control'));
- this.before('primus.js', require('./middleware/primus'));
- this.before('spec', require('./middleware/spec'));
- this.before('x-xss', require('./middleware/xss'));
- this.before('no-cache', require('./middleware/no-cache'));
- this.before('authorization', require('./middleware/authorization'));
+ this.use('forwarded', require('./middleware/forwarded'));
+ this.use('cors', require('./middleware/access-control'));
+ this.use('primus.js', require('./middleware/primus'));
+ this.use('spec', require('./middleware/spec'));
+ this.use('x-xss', require('./middleware/xss'));
+ this.use('no-cache', require('./middleware/no-cache'));
+ this.use('authorization', require('./middleware/authorization'));
//
// Emit the initialised event after the next tick so we have some time to
@@ -648,7 +648,7 @@ Primus.readable('save', function save(path, fn) {
* Register a new Primus plugin.
*
* ```js
- * primus.use('ack', {
+ * primus.plugin('ack', {
* //
* // Only ran on the server.
* //
@@ -672,21 +672,22 @@ Primus.readable('save', function save(path, fn) {
*
* @param {String} name The name of the plugin.
* @param {Object} energon The plugin that contains client and server extensions.
- * @returns {Primus}
+ * @returns {Mixed}
* @api public
*/
-Primus.readable('use', function use(name, energon) {
- if ('object' === typeof name && !energon) {
- energon = name;
- name = energon.name;
- }
-
- if (!name) {
- throw new PrimusError('Plugin should be specified with a name', this);
+Primus.readable('plugin', function plugin(name, energon) {
+ if (!name) return this.ark;
+
+ if (!energon) {
+ if ('string' === typeof name) return this.ark[name];
+ if ('object' === typeof name) {
+ energon = name;
+ name = energon.name;
+ }
}
- if ('string' !== typeof name) {
- throw new PrimusError('Plugin names should be a string', this);
+ if ('string' !== typeof name || !name) {
+ throw new PrimusError('Plugin name must be a non empty string', this);
}
if ('string' === typeof energon) {
@@ -705,15 +706,15 @@ Primus.readable('use', function use(name, energon) {
// Plugin require a client, server or both to be specified in the object.
//
if (!energon.server && !energon.client) {
- throw new PrimusError('The plugin is missing a client or server function', this);
+ throw new PrimusError('Plugin is missing a client or server function', this);
}
//
// Don't allow duplicate plugins or plugin override as this is most likely
// unintentional.
//
if (name in this.ark) {
- throw new PrimusError('The plugin name was already defined', this);
+ throw new PrimusError('Plugin name already defined', this);
}
log('adding %s as new plugin', name);
@@ -728,25 +729,6 @@ Primus.readable('use', function use(name, energon) {
return this;
});
-/**
- * Return the given plugin.
- *
- * @param {String} name The name of the plugin.
- * @returns {Mixed}
- * @api public
- */
-Primus.readable('plugin', function plugin(name) {
- if (name) return this.ark[name];
-
- var plugins = {};
-
- for (name in this.ark) {
- plugins[name] = this.ark[name];
- }
-
- return plugins;
-});
-
/**
* Remove plugin from the ark.
*
@@ -775,7 +757,7 @@ Primus.readable('plugout', function plugout(name) {
* @returns {Primus}
* @api public
*/
-Primus.readable('before', function before(name, fn, options, level) {
+Primus.readable('use', function use(name, fn, options, level) {
if ('function' === typeof name) {
level = options;
options = fn;
View
@@ -41,7 +41,7 @@ npm install --save primus-rooms
After installing you can add the plugin using:
```js
-primus.use('rooms', require('primus-rooms'));
+primus.plugin('rooms', require('primus-rooms'));
```
And now you can join and leave rooms again. Manually leaving rooms when the
@@ -83,5 +83,5 @@ And the only thing we need to do to use it to add the plugin to the Primus
server using:
```js
-primus.use('emit', require('primus-emit'));
+primus.plugin('emit', require('primus-emit'));
```
View
@@ -20,23 +20,23 @@ describe('Middleware', function () {
primus.destroy(done);
});
- describe('#before', function () {
+ describe('#use', function () {
it('is chainable', function () {
- expect(primus.before('foo', function (req, res) {})).to.equal(primus);
+ expect(primus.use('foo', function (req, res) {})).to.equal(primus);
});
it('throws when no function is provided', function (done) {
- try { primus.before('foo', new Date()); }
+ try { primus.use('foo', new Date()); }
catch (e) { done(); }
});
it('throws when function doesnt accept req/res args', function (done) {
- try { primus.before('foo', function () { return function () {}; }); }
+ try { primus.use('foo', function () { return function () {}; }); }
catch (e) { done(); }
});
it('calls the function if it has less then 2 arguments', function (done) {
- primus.before('example', function (options) {
+ primus.use('example', function (options) {
expect(this).to.equal(primus);
expect(options).to.be.a('object');
expect(options.foo).to.equal('bar');
@@ -50,15 +50,15 @@ describe('Middleware', function () {
it('extracts a name if none is given', function () {
expect(primus.indexOfLayer('connect')).to.equal(-1);
- primus.before(function connect(req, res, bar) {});
+ primus.use(function connect(req, res, bar) {});
expect(primus.indexOfLayer('connect')).to.be.above(-1);
});
it('stores the layer', function () {
function foo(req, res, next) { }
function bar(req, res) { }
- primus.before('foo', foo).before('bar', bar);
+ primus.use('foo', foo).use('bar', bar);
var index = primus.indexOfLayer('foo')
, layer = primus.layers[index];
@@ -77,7 +77,7 @@ describe('Middleware', function () {
function foo(req, res, next) { }
function bar(req, res) { }
- primus.before('foo', foo);
+ primus.use('foo', foo);
var index = primus.indexOfLayer('foo')
, layer = primus.layers[index];
@@ -87,7 +87,7 @@ describe('Middleware', function () {
expect(layer.length).to.equal(3);
expect(layer.fn).to.equal(foo);
- primus.before('foo', bar);
+ primus.use('foo', bar);
expect(primus.indexOfLayer('foo')).to.equal(index);
index = primus.indexOfLayer('foo');
@@ -103,7 +103,7 @@ describe('Middleware', function () {
function foo(req, res, next) { }
function bar(req, res, next) { }
- primus.before('foo', foo, 3);
+ primus.use('foo', foo, 3);
var index = primus.indexOfLayer('foo')
, layer = primus.layers[index];
@@ -114,7 +114,7 @@ describe('Middleware', function () {
expect(layer.fn).to.equal(foo);
expect(index).to.equal(3);
- primus.before(bar, 4);
+ primus.use(bar, 4);
index = primus.indexOfLayer('bar');
layer = primus.layers[index];
@@ -125,7 +125,7 @@ describe('Middleware', function () {
expect(layer.fn).to.equal(bar);
expect(index).to.equal(4);
- primus.before(function baz(options) {
+ primus.use(function baz(options) {
expect(this).to.equal(primus);
expect(options).to.be.a('object');
expect(options).to.eql({});
@@ -147,7 +147,7 @@ describe('Middleware', function () {
it('returns the index based on name', function () {
expect(primus.indexOfLayer('foo')).to.equal(-1);
- primus.before('foo', function (req, res) {
+ primus.use('foo', function (req, res) {
throw new Error('Dont execute me');
});
@@ -157,8 +157,8 @@ describe('Middleware', function () {
describe('#remove', function () {
it('removes the layer from the stack', function () {
- primus.before('bar', function (req, res) {});
- primus.before('foo', function (req, res) {
+ primus.use('bar', function (req, res) {});
+ primus.use('foo', function (req, res) {
throw new Error('boom');
});
@@ -173,7 +173,7 @@ describe('Middleware', function () {
describe('#disable', function () {
it('disables the middleware', function () {
- primus.before('foo', function (req, res) {});
+ primus.use('foo', function (req, res) {});
var index = primus.indexOfLayer('foo')
, layer = primus.layers[index];
@@ -186,7 +186,7 @@ describe('Middleware', function () {
describe('#enable', function () {
it('enables the middleware', function () {
- primus.before('foo', function (req, res) {});
+ primus.use('foo', function (req, res) {});
var index = primus.indexOfLayer('foo')
, layer = primus.layers[index];
Oops, something went wrong.

0 comments on commit e23eaa9

Please sign in to comment.