Rename app.use() to app.encapsulate()

docs/App.md

@@ -1,7 +1,7 @@
 # App
 
 A new `app` is created by calling the [`medley` factory function](Medley.md). Sub-apps—created
-with [`app.use()`](#use)—are apps that inherit from the `app` that created them. Both an *app*
+with [`app.encapsulate()`](#encapsulate)—are apps that inherit from the `app` that created them. Both an *app*
 and a *sub-app* may be referred to as an *app instance*.
 
 ```js
@@ -22,6 +22,7 @@ const app = medley();
 + [`.decorate(name, value)`](#decorate)
 + [`.decorateRequest(name, value)`](#decorate-request)
 + [`.decorateResponse(name, value)`](#decorate-response)
++ [`.encapsulate([prefix,] subAppFn)`](#encapsulate)
 + [`.inject(options [, callback])`](#inject)
 + [`.listen(port [, host][, backlog][, callback])`](#listen)
 + [`.load([callback])`](#load)
@@ -32,7 +33,6 @@ const app = medley();
 + [`.route(options)`](#route)
 + [`.setErrorHandler(handler)`](#set-error-handler)
 + [`.setNotFoundHandler([options,] handler)`](#set-not-found-handler)
-+ [`.use([prefix,] subAppFn)`](#use)
 
 
 ## Properties
@@ -43,10 +43,10 @@ const app = medley();
 The path that will be prefixed to routes in a sub-app. Example:
 
 ```js
-app.use('/v1', (subApp) => {
+app.encapsulate('/v1', (subApp) => {
   console.log(subApp.basePath); // '/v1'
 
-  subApp.use('/user', (subSubApp) => {
+  subApp.encapsulate('/user', (subSubApp) => {
     console.log(subSubApp.basePath); // '/v1/user'
   });
 });
@@ -111,6 +111,61 @@ Safely adds a new property to the [`Request`](Request.md) object for the current
 Safely adds a new property to the [`Response`](Response.md) object for the current
 `app` instance. See the [Decorators](Decorators.md) documentation.
 
+<a id="encapsulate"></a>
+### `app.encapsulate([prefix,] subAppFn)`
+
++ `prefix` *(string)* - A prefix for all routes defined in the sub-app (e.g `'/v1'`).
++ `subAppFn(subApp)` *(function)* - A function that will be called immediately with the created sub-app.
+
+Creates a new sub-app and passes it to the `subAppFn` function. Optionally,
+a `prefix` string can be specified which will be the prefix for all routes
+defined on the `subApp`. Prefixes are compounded for nested sub-apps.
+
+```js
+const medley = require('@medley/medley');
+const app = medley();
+
+app.encapsulate((subApp) => {
+  subApp.addHook('onRequest', (req, res, next) => {
+    // This hook only runs for routes defined on this sub-app
+    next();
+  });
+
+  subApp.get('/status', (req, res) => res.send('OK'));
+});
+
+app.encapsulate('/api', (apiSubApp) => {
+  apiSubApp.addHook('onRequest', (req, res, next) => {
+    // This hook only runs for routes defined within the apiSubApp
+    next();
+  });
+
+  apiSubApp.get('/user', (req, res) => { // Route URL is: /api/user
+    // Get user
+  });
+
+  apiSubApp.encapsulate('/v1', (v1SubApp) => {
+    v1SubApp.post('/user', (req, res) => { // Route URL is: /api/v1/user
+      // Create a new user
+    });
+  });
+});
+```
+
+See the [Route Prefixing](Routes.md#route-prefixing) section for details on
+how the `prefix` option affects routes.
+
+Note that the `subAppFn` is executed immediately:
+
+```js
+app.encapsulate((subApp) => {
+  // This code runs first
+});
+
+// This code runs second
+app.decorate('a', {});
+```
+
 <a id="inject"></a>
 ### `app.inject(options [, callback])`
 
@@ -316,64 +371,9 @@ app.setNotFoundHandler((req, res) => {
   // Default not-found handler
 });
 
-app.use('/v1', (subApp) => {
+app.encapsulate('/v1', (subApp) => {
   subApp.setNotFoundHandler((req, res) => {
     // Handle unmatched requests to URLs that begin with '/v1'
   });
 });
 ```
-
-<a id="use"></a>
-### `app.use([prefix,] subAppFn)`
-
-+ `prefix` *(string)* - A prefix for all routes defined in the sub-app (e.g `'/v1'`).
-+ `subAppFn(subApp)` *(function)* - A function that will be called immediately with the created sub-app.
-
-Creates a new sub-app and passes it to the `subAppFn` function. Optionally,
-a `prefix` string can be specified which will be the prefix for all routes
-defined on the `subApp`. Prefixes are compounded for nested sub-apps.
-
-```js
-const medley = require('@medley/medley');
-const app = medley();
-
-app.use((subApp) => {
-  subApp.addHook('onRequest', (req, res, next) => {
-    // This hook only runs for routes defined on this sub-app
-    next();
-  });
-
-  subApp.get('/status', (req, res) => res.send('OK'));
-});
-
-app.use('/api', (apiSubApp) => {
-  apiSubApp.addHook('onRequest', (req, res, next) => {
-    // This hook only runs for routes defined within the apiSubApp
-    next();
-  });
-
-  apiSubApp.get('/user', (req, res) => { // Route URL is: /api/user
-    // Get user
-  });
-
-  apiSubApp.use('/v1', (v1SubApp) => {
-    v1SubApp.post('/user', (req, res) => { // Route URL is: /api/v1/user
-      // Create a new user
-    });
-  });
-});
-```
-
-See the [Route Prefixing](Routes.md#route-prefixing) section for details on
-how the `prefix` option affects routes.
-
-Note that the `subAppFn` is executed immediately:
-
-```js
-app.use((subApp) => {
-  // This code runs first
-});
-
-// This code runs second
-app.decorate('a', {});
-```

docs/Decorators.md

@@ -51,15 +51,15 @@ be available to that sub-app and its own sub-apps.
 ```js
 app.decorate('top', true);
 
-app.use((subApp1) => {
+app.encapsulate((subApp1) => {
   subApp1.decorate('one', 1);
 
   console.log(subApp1.top); // true
   console.log(subApp1.one); // 1
   console.log(subApp1.two); // undefined
 });
 
-app.use((subApp2) => {
+app.encapsulate((subApp2) => {
   subApp2.decorate('two', 2);
 
   console.log(subApp2.top); // true

docs/Getting-Started.md

@@ -141,14 +141,14 @@ See the [`Serialization` documentation](Serialization.md) for more information.
 
 Hooks, [body parsers](BodyParser.md), and app decorators can be encapsulated within sub-apps to
 isolate different functionality to specific parts of an application. Sub-apps are registered with
-the [`app.use()`](App.md#use) method.
+the [`app.encapsulate()`](App.md#encapsulate) method.
 
 **app.js**
 ```js
 const medley = require('@medley/medley');
 const app = medley();
 
-app.use(require('./userRoutes'));
+app.encapsulate(require('./userRoutes'));
 ```
 
 **userRoutes.js**
@@ -159,7 +159,7 @@ module.exports = function userRoutes(app) {
 };
 ```
 
-See [`app.use()`](App.md#use), [Hooks Encapsulation](Hooks.md#encapsulation),
+See [`app.encapsulate()`](App.md#encapsulate), [Hooks Encapsulation](Hooks.md#encapsulation),
 [`app.decorate()`](Decorators.md#decorate), and [Route Prefixing](Routes.md#route-prefixing)
 for details.
 

docs/Hooks.md

@@ -234,7 +234,7 @@ app.addHook('onRequest', (req, res, next) => {
   next();
 });
 
-app.use((subApp1) => {
+app.encapsulate((subApp1) => {
   subApp1.addHook('onRequest', (req, res, next) => {
     req.one = 1; // Only runs for routes in `subApp1`
     next();
@@ -248,7 +248,7 @@ app.use((subApp1) => {
   });
 });
 
-app.use((subApp2) => {
+app.encapsulate((subApp2) => {
   subApp2.addHook('onRequest', (req, res, next) => {
     req.two = 2; // Only runs for routes in `subApp2`
     next();

docs/Routes.md

@@ -232,16 +232,16 @@ way to accomplish this would be to include the prefix in every route declaration
 app.get('/v1/user', (req, res) => { ... })
 ```
 
-But an alternative would be to use [`app.use()`](App.md#use) to create separate
+But an alternative would be to use [`app.encapsulate()`](App.md#encapsulate) to create separate
 sub-apps with a different prefix for each group of routes:
 
 **app.js**
 ```js
 const medley = require('@medley/medley');
 const app = medley();
 
-app.use('/v1', require('./routes/v1/user'));
-app.use('/v2', require('./routes/v2/user'));
+app.encapsulate('/v1', require('./routes/v1/user'));
+app.encapsulate('/v2', require('./routes/v2/user'));
 
 app.listen(3000);
 ```

medley.js

@@ -76,7 +76,7 @@ function medley(options) {
     server,
     _onStreamError: options.onStreamError || function noop() {},
 
-    use, // For creating sub-apps
+    encapsulate, // For creating sub-apps
     _subApps: [],
 
     // Decorator methods
@@ -159,7 +159,7 @@ function medley(options) {
 
   return app
 
-  function use(prefix, subAppFn) {
+  function encapsulate(prefix, subAppFn) {
     if (subAppFn === undefined) {
       subAppFn = prefix
       prefix = ''
@@ -171,7 +171,6 @@ function medley(options) {
     if (prefix !== '' && prefix[0] !== '/') {
       throw new Error(`'prefix' must start with a '/' character. Got: '${prefix}'`)
     }
-
     if (typeof subAppFn !== 'function') {
       throw new TypeError(`'subAppFn' must be a function. Got a value of type '${typeof subAppFn}': ${subAppFn}`)
     }

test/404s.test.js

@@ -141,7 +141,7 @@ test('setting a custom 404 handler multiple times is an error', (t) => {
 
     const app = medley()
 
-    app.use('/prefix', (subApp) => {
+    app.encapsulate('/prefix', (subApp) => {
       subApp.setNotFoundHandler(() => {})
 
       t.throws(
@@ -158,7 +158,7 @@ test('setting a custom 404 handler multiple times is an error', (t) => {
 
     app.setNotFoundHandler(() => {})
 
-    app.use((subApp) => {
+    app.encapsulate((subApp) => {
       t.throws(
         () => subApp.setNotFoundHandler(() => {}),
         new Error("Not found handler already set for app instance with prefix: '/'")
@@ -171,7 +171,7 @@ test('setting a custom 404 handler multiple times is an error', (t) => {
 
     const app = medley()
 
-    app.use((subApp) => {
+    app.encapsulate((subApp) => {
       subApp.setNotFoundHandler(() => {})
     })
 
@@ -188,10 +188,10 @@ test('setting a custom 404 handler multiple times is an error', (t) => {
 
     app.setNotFoundHandler(() => {})
 
-    app.use('/prefix', (subApp) => {
+    app.encapsulate('/prefix', (subApp) => {
       subApp.setNotFoundHandler(() => {})
 
-      subApp.use((subApp2) => {
+      subApp.encapsulate((subApp2) => {
         t.throws(
           () => subApp2.setNotFoundHandler(() => {}),
           new Error("Not found handler already set for app instance with prefix: '/prefix'")
@@ -205,12 +205,12 @@ test('setting a custom 404 handler multiple times is an error', (t) => {
 
     const app = medley()
 
-    app.use('/prefix', (subApp) => {
-      subApp.use((subApp2A) => {
+    app.encapsulate('/prefix', (subApp) => {
+      subApp.encapsulate((subApp2A) => {
         subApp2A.setNotFoundHandler(() => {})
       })
 
-      subApp.use((subApp2B) => {
+      subApp.encapsulate((subApp2B) => {
         t.throws(
           () => subApp2B.setNotFoundHandler(() => {}),
           new Error("Not found handler already set for app instance with prefix: '/prefix'")
@@ -235,19 +235,19 @@ test('encapsulated 404', (t) => {
     res.status(404).send('this was not found')
   })
 
-  app.use('/test', (subApp) => {
+  app.encapsulate('/test', (subApp) => {
     subApp.setNotFoundHandler(function(req, res) {
       res.status(404).send('this was not found 2')
     })
   })
 
-  app.use('/test2', (subApp) => {
+  app.encapsulate('/test2', (subApp) => {
     subApp.setNotFoundHandler(function(req, res) {
       res.status(404).send('this was not found 3')
     })
   })
 
-  app.use('/test3/', (subApp) => {
+  app.encapsulate('/test3/', (subApp) => {
     subApp.setNotFoundHandler(function(req, res) {
       res.status(404).send('this was not found 4')
     })
@@ -452,7 +452,7 @@ test('run hooks with encapsulated 404', (t) => {
     t.ok(response, 'onFinished called')
   })
 
-  app.use('/test', (subApp) => {
+  app.encapsulate('/test', (subApp) => {
     subApp.setNotFoundHandler((request, response) => {
       response.status(404).send('this was not found 2')
     })
@@ -500,7 +500,7 @@ test('encapsulated custom 404 without prefix has the right encapsulation context
   app.decorateRequest('foo', 42)
   app.decorateResponse('foo', 42)
 
-  app.use((subApp) => {
+  app.encapsulate((subApp) => {
     subApp.decorateRequest('bar', 84)
 
     subApp.addHook('onRequest', (request, response, next) => {
@@ -584,14 +584,14 @@ test('encapsulated custom 404 handler without a prefix is the handler for the en
 
   const app = medley()
 
-  app.use((subApp) => {
+  app.encapsulate((subApp) => {
     subApp.setNotFoundHandler((request, response) => {
       response.status(404).send('custom handler')
     })
   })
 
-  app.use('/prefixed', (subApp) => {
-    subApp.use((subApp2) => {
+  app.encapsulate('/prefixed', (subApp) => {
+    subApp.encapsulate((subApp2) => {
       subApp2.setNotFoundHandler((request, response) => {
         response.status(404).send('custom handler 2')
       })

test/500s.test.js

@@ -90,7 +90,7 @@ test('encapsulated 500', (t) => {
     response.error(new Error('kaboom'))
   })
 
-  app.use('/test', function(subApp) {
+  app.encapsulate('/test', function(subApp) {
     subApp.get('/', function(req, response) {
       response.error(new Error('kaboom'))
     })