Skip to content

Commit e23eaa9

Browse files
lpincalpinca
committed
[major] Rename some public methods
Renames `Primus#use` to `Primus#plugin` and `Primus#before` to `Primus#use`.
1 parent 324af13 commit e23eaa9

File tree

8 files changed

+116
-131
lines changed

8 files changed

+116
-131
lines changed

‎README.md

Lines changed: 12 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1447,9 +1447,9 @@ of components in Primus are implemented through middleware layers:
14471447
- `no-cache`: Add no-cache headers to every HTTP request.
14481448
- `x-xss`: Add `X-XSS-Protection` headers to every HTTP request.
14491449

1450-
#### Primus.before(name, fn, options, index)
1450+
#### Primus.use(name, fn, options, index)
14511451

1452-
The `primus.before` method is how you add middleware layers to your system. All
1452+
The `primus.use` method is how you add middleware layers to your system. All
14531453
middleware layers need to be named. This allows you to also enable, disable and
14541454
remove middleware layers. The supplied function can either be a pre-configured
14551455
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
14581458
and optionally, the options that got provided:
14591459

14601460
```js
1461-
primus.before('name', function () {
1461+
primus.use('name', function () {
14621462
var primus = this;
14631463

14641464
return function (req, res) {
@@ -1473,12 +1473,12 @@ the function directly:
14731473

14741474
```js
14751475
// sync middleware
1476-
primus.before('name', function (req, res) {
1476+
primus.use('name', function (req, res) {
14771477

14781478
});
14791479

14801480
// async middleware
1481-
primus.before('name', function (req, res, next) {
1481+
primus.use('name', function (req, res, next) {
14821482
doStuff();
14831483
});
14841484
```
@@ -1490,7 +1490,7 @@ property to the middleware function and set it to `false` if you don't want it
14901490
to be triggered.
14911491

14921492
```js
1493-
primus.before('name', function () {
1493+
primus.use('name', function () {
14941494
function middleware(req, res, next) {
14951495

14961496
}
@@ -1508,7 +1508,7 @@ argument.
15081508

15091509
```js
15101510
// add a middleware after the first two in the stack
1511-
primus.before('name', function (req, res) {
1511+
primus.use('name', function (req, res) {
15121512

15131513
}, 2);
15141514
```
@@ -1560,12 +1560,12 @@ Plugins are added on the server side in the form of an `Object`:
15601560
//
15611561
// Require a plugin directly.
15621562
//
1563-
primus.use('name', require('metroplex'));
1563+
primus.plugin('name', require('metroplex'));
15641564

15651565
//
15661566
// Or supply it manually with the required object structure
15671567
//
1568-
primus.use('name', {
1568+
primus.plugin('name', {
15691569
server: function (primus, options) {},
15701570
client: function (primus, options) {},
15711571
library: 'client side library'
@@ -1594,7 +1594,7 @@ var primus = new Primus(server, { plugin: 'metroplex, primus-emit' })
15941594
To remove added plugins you can use the `plugout` method:
15951595

15961596
```js
1597-
primus.use('name', require('metroplex'));
1597+
primus.plugin('name', require('metroplex'));
15981598
primus.plugout('name'); // returns true/false indicating successful removal.
15991599
```
16001600

@@ -1656,7 +1656,7 @@ easily add new functionality to the socket. For example adding join room
16561656
function would be as easy as:
16571657

16581658
```js
1659-
primus.use('rooms', {
1659+
primus.plugin('rooms', {
16601660
server: function (primus) {
16611661
var Spark = primus.Spark;
16621662

@@ -1700,7 +1700,7 @@ primus.transform('incoming', function (packet) {
17001700
These transformations can easily be done in the plugins:
17011701

17021702
```js
1703-
primus.use('name', {
1703+
primus.plugin('name', {
17041704
server: function (primus) {
17051705
primus.transform('outgoing', function (packet) {
17061706
packet.data = 'foo';

‎examples/middleware/index.js

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -59,8 +59,8 @@ var server = http.createServer(app)
5959
// first will populate `req.signedCookies` and the second `req.session` for the
6060
// requests captured by Primus.
6161
//
62-
primus.before('cookies', cookies);
63-
primus.before('session', primusSession, { store: store });
62+
primus.use('cookies', cookies);
63+
primus.use('session', primusSession, { store: store });
6464

6565
primus.on('connection', function connection(spark) {
6666
//

‎index.js

Lines changed: 25 additions & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -109,11 +109,11 @@ function Primus(server, options) {
109109
//
110110
if ('string' === typeof options.plugin) {
111111
options.plugin.split(/[, ]+/).forEach(function register(name) {
112-
primus.use(name, name);
112+
primus.plugin(name, name);
113113
});
114114
} else if ('object' === typeof options.plugin) {
115115
for (key in options.plugin) {
116-
this.use(key, options.plugin[key]);
116+
this.plugin(key, options.plugin[key]);
117117
}
118118
}
119119

@@ -319,13 +319,13 @@ Primus.readable('initialise', function initialise(Transformer, options) {
319319
//
320320
// Add our default middleware layers.
321321
//
322-
this.before('forwarded', require('./middleware/forwarded'));
323-
this.before('cors', require('./middleware/access-control'));
324-
this.before('primus.js', require('./middleware/primus'));
325-
this.before('spec', require('./middleware/spec'));
326-
this.before('x-xss', require('./middleware/xss'));
327-
this.before('no-cache', require('./middleware/no-cache'));
328-
this.before('authorization', require('./middleware/authorization'));
322+
this.use('forwarded', require('./middleware/forwarded'));
323+
this.use('cors', require('./middleware/access-control'));
324+
this.use('primus.js', require('./middleware/primus'));
325+
this.use('spec', require('./middleware/spec'));
326+
this.use('x-xss', require('./middleware/xss'));
327+
this.use('no-cache', require('./middleware/no-cache'));
328+
this.use('authorization', require('./middleware/authorization'));
329329

330330
//
331331
// 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) {
648648
* Register a new Primus plugin.
649649
*
650650
* ```js
651-
* primus.use('ack', {
651+
* primus.plugin('ack', {
652652
* //
653653
* // Only ran on the server.
654654
* //
@@ -672,21 +672,22 @@ Primus.readable('save', function save(path, fn) {
672672
*
673673
* @param {String} name The name of the plugin.
674674
* @param {Object} energon The plugin that contains client and server extensions.
675-
* @returns {Primus}
675+
* @returns {Mixed}
676676
* @api public
677677
*/
678-
Primus.readable('use', function use(name, energon) {
679-
if ('object' === typeof name && !energon) {
680-
energon = name;
681-
name = energon.name;
682-
}
683-
684-
if (!name) {
685-
throw new PrimusError('Plugin should be specified with a name', this);
678+
Primus.readable('plugin', function plugin(name, energon) {
679+
if (!name) return this.ark;
680+
681+
if (!energon) {
682+
if ('string' === typeof name) return this.ark[name];
683+
if ('object' === typeof name) {
684+
energon = name;
685+
name = energon.name;
686+
}
686687
}
687688

688-
if ('string' !== typeof name) {
689-
throw new PrimusError('Plugin names should be a string', this);
689+
if ('string' !== typeof name || !name) {
690+
throw new PrimusError('Plugin name must be a non empty string', this);
690691
}
691692

692693
if ('string' === typeof energon) {
@@ -705,15 +706,15 @@ Primus.readable('use', function use(name, energon) {
705706
// Plugin require a client, server or both to be specified in the object.
706707
//
707708
if (!energon.server && !energon.client) {
708-
throw new PrimusError('The plugin is missing a client or server function', this);
709+
throw new PrimusError('Plugin is missing a client or server function', this);
709710
}
710711

711712
//
712713
// Don't allow duplicate plugins or plugin override as this is most likely
713714
// unintentional.
714715
//
715716
if (name in this.ark) {
716-
throw new PrimusError('The plugin name was already defined', this);
717+
throw new PrimusError('Plugin name already defined', this);
717718
}
718719

719720
log('adding %s as new plugin', name);
@@ -728,25 +729,6 @@ Primus.readable('use', function use(name, energon) {
728729
return this;
729730
});
730731

731-
/**
732-
* Return the given plugin.
733-
*
734-
* @param {String} name The name of the plugin.
735-
* @returns {Mixed}
736-
* @api public
737-
*/
738-
Primus.readable('plugin', function plugin(name) {
739-
if (name) return this.ark[name];
740-
741-
var plugins = {};
742-
743-
for (name in this.ark) {
744-
plugins[name] = this.ark[name];
745-
}
746-
747-
return plugins;
748-
});
749-
750732
/**
751733
* Remove plugin from the ark.
752734
*
@@ -775,7 +757,7 @@ Primus.readable('plugout', function plugout(name) {
775757
* @returns {Primus}
776758
* @api public
777759
*/
778-
Primus.readable('before', function before(name, fn, options, level) {
760+
Primus.readable('use', function use(name, fn, options, level) {
779761
if ('function' === typeof name) {
780762
level = options;
781763
options = fn;

‎migration.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -41,7 +41,7 @@ npm install --save primus-rooms
4141
After installing you can add the plugin using:
4242

4343
```js
44-
primus.use('rooms', require('primus-rooms'));
44+
primus.plugin('rooms', require('primus-rooms'));
4545
```
4646

4747
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
8383
server using:
8484

8585
```js
86-
primus.use('emit', require('primus-emit'));
86+
primus.plugin('emit', require('primus-emit'));
8787
```

‎test/middleware.test.js

Lines changed: 17 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -20,23 +20,23 @@ describe('Middleware', function () {
2020
primus.destroy(done);
2121
});
2222

23-
describe('#before', function () {
23+
describe('#use', function () {
2424
it('is chainable', function () {
25-
expect(primus.before('foo', function (req, res) {})).to.equal(primus);
25+
expect(primus.use('foo', function (req, res) {})).to.equal(primus);
2626
});
2727

2828
it('throws when no function is provided', function (done) {
29-
try { primus.before('foo', new Date()); }
29+
try { primus.use('foo', new Date()); }
3030
catch (e) { done(); }
3131
});
3232

3333
it('throws when function doesnt accept req/res args', function (done) {
34-
try { primus.before('foo', function () { return function () {}; }); }
34+
try { primus.use('foo', function () { return function () {}; }); }
3535
catch (e) { done(); }
3636
});
3737

3838
it('calls the function if it has less then 2 arguments', function (done) {
39-
primus.before('example', function (options) {
39+
primus.use('example', function (options) {
4040
expect(this).to.equal(primus);
4141
expect(options).to.be.a('object');
4242
expect(options.foo).to.equal('bar');
@@ -50,15 +50,15 @@ describe('Middleware', function () {
5050
it('extracts a name if none is given', function () {
5151
expect(primus.indexOfLayer('connect')).to.equal(-1);
5252

53-
primus.before(function connect(req, res, bar) {});
53+
primus.use(function connect(req, res, bar) {});
5454
expect(primus.indexOfLayer('connect')).to.be.above(-1);
5555
});
5656

5757
it('stores the layer', function () {
5858
function foo(req, res, next) { }
5959
function bar(req, res) { }
6060

61-
primus.before('foo', foo).before('bar', bar);
61+
primus.use('foo', foo).use('bar', bar);
6262

6363
var index = primus.indexOfLayer('foo')
6464
, layer = primus.layers[index];
@@ -77,7 +77,7 @@ describe('Middleware', function () {
7777
function foo(req, res, next) { }
7878
function bar(req, res) { }
7979

80-
primus.before('foo', foo);
80+
primus.use('foo', foo);
8181

8282
var index = primus.indexOfLayer('foo')
8383
, layer = primus.layers[index];
@@ -87,7 +87,7 @@ describe('Middleware', function () {
8787
expect(layer.length).to.equal(3);
8888
expect(layer.fn).to.equal(foo);
8989

90-
primus.before('foo', bar);
90+
primus.use('foo', bar);
9191
expect(primus.indexOfLayer('foo')).to.equal(index);
9292

9393
index = primus.indexOfLayer('foo');
@@ -103,7 +103,7 @@ describe('Middleware', function () {
103103
function foo(req, res, next) { }
104104
function bar(req, res, next) { }
105105

106-
primus.before('foo', foo, 3);
106+
primus.use('foo', foo, 3);
107107

108108
var index = primus.indexOfLayer('foo')
109109
, layer = primus.layers[index];
@@ -114,7 +114,7 @@ describe('Middleware', function () {
114114
expect(layer.fn).to.equal(foo);
115115
expect(index).to.equal(3);
116116

117-
primus.before(bar, 4);
117+
primus.use(bar, 4);
118118

119119
index = primus.indexOfLayer('bar');
120120
layer = primus.layers[index];
@@ -125,7 +125,7 @@ describe('Middleware', function () {
125125
expect(layer.fn).to.equal(bar);
126126
expect(index).to.equal(4);
127127

128-
primus.before(function baz(options) {
128+
primus.use(function baz(options) {
129129
expect(this).to.equal(primus);
130130
expect(options).to.be.a('object');
131131
expect(options).to.eql({});
@@ -147,7 +147,7 @@ describe('Middleware', function () {
147147
it('returns the index based on name', function () {
148148
expect(primus.indexOfLayer('foo')).to.equal(-1);
149149

150-
primus.before('foo', function (req, res) {
150+
primus.use('foo', function (req, res) {
151151
throw new Error('Dont execute me');
152152
});
153153

@@ -157,8 +157,8 @@ describe('Middleware', function () {
157157

158158
describe('#remove', function () {
159159
it('removes the layer from the stack', function () {
160-
primus.before('bar', function (req, res) {});
161-
primus.before('foo', function (req, res) {
160+
primus.use('bar', function (req, res) {});
161+
primus.use('foo', function (req, res) {
162162
throw new Error('boom');
163163
});
164164

@@ -173,7 +173,7 @@ describe('Middleware', function () {
173173

174174
describe('#disable', function () {
175175
it('disables the middleware', function () {
176-
primus.before('foo', function (req, res) {});
176+
primus.use('foo', function (req, res) {});
177177

178178
var index = primus.indexOfLayer('foo')
179179
, layer = primus.layers[index];
@@ -186,7 +186,7 @@ describe('Middleware', function () {
186186

187187
describe('#enable', function () {
188188
it('enables the middleware', function () {
189-
primus.before('foo', function (req, res) {});
189+
primus.use('foo', function (req, res) {});
190190

191191
var index = primus.indexOfLayer('foo')
192192
, layer = primus.layers[index];

0 commit comments

Comments
 (0)