Docs: README

README.md

@@ -9,9 +9,113 @@
 
 Part of the [Overlook framework](https://overlookjs.github.io/).
 
+## Abstract
+
+Plugin which delegates handling of requests either to this route, or children, based on matching the request path.
+
+Similar to [express](https://expressjs.com/)'s routing.
+
 ## Usage
 
-This module is under development and not ready for use yet.
+### Building route paths
+
+Extend routes with this plugin and then define the "path part" for each route via `[PATH_PART]` property or `[GET_PATH_PART]()` method. If neither is defined, `.name` is taken as path part.
+
+Each route's path is its parent's path + the new path part. `/user` + `login` -> `/user/login`.
+
+```js
+const Route = require('@overlook/route');
+const pathPlugin = require('@overlook/plugin-path');
+const { PATH } = pathPlugin;
+
+const PathRoute = Route.extend( pathPlugin );
+
+// URL: /
+const root = new PathRoute();
+
+// URL: /bands
+const bands = new PathRoute( { name: 'bands' } );
+root.attachChild( bands );
+
+// URL: /bands/:bandId
+const band = new PathRoute( {
+  name: 'band',
+  [PATH_PART]: ':bandId'
+} );
+bands.attachChild( band );
+
+// URL: /bands/:bandId/albums
+const albums = new PathRoute( { name: 'albums' } );
+band.attachChild( albums );
+
+// URL: /bands/:bandId/albums/:albumId
+const album = new PathRoute( {
+  name: 'album',
+  [PATH_PART]: ':albumId'
+} );
+albums.attachChild( album );
+```
+
+A request for `http://example.com/bands/the-cure/albums/wish` will be routed to the `album` route.
+
+#### Matching order
+
+Routes can be added in any order, and the plugin will order them by priority automatically. Static matches (e.g. `bands`) take priority over parameterized matches (e.g. `:id`). The lowest priority is wildcard matches (`*`).
+
+### Handing requests
+
+To handle requests, define/extend the `[HANDLE_ROUTE]()` method.
+
+If a route matches exactly, `[HANDLE_ROUTE]()` will be called with the request. If it only matches in part, the request will be forwarded on to the route's children to match.
+
+`[HANDLE_ROUTE]` symbol is exported by [@overlook/plugin-match](https://www.npmjs.com/package/@overlook/plugin-match) (which this plugin extends).
+
+```js
+const Route = require('@overlook/route');
+const pathPlugin = require('@overlook/plugin-path');
+const { HANDLE_ROUTE } = require('@overlook/plugin-match');
+const { PATH } = pathPlugin;
+
+const PathRoute = Route.extend( pathPlugin );
+
+class BandsRoute extends PathRoute {
+  [GET_PATH_PART]() {
+    return 'bands';
+  }
+
+  [HANDLE_ROUTE]( req ) {
+    // Handle the request
+    // `req` = request object
+  }
+}
+```
+
+### Params
+
+For parameterized routes (i.e. `:something`), the parameters can be accessed as `req[PARAMS]`.
+
+```js
+const { GET_PATH_PART, PARAMS } = require('@overlook/plugin-path');
+
+class BandRoute extends PathRoute {
+  [GET_PATH_PART]() {
+    return ':bandId';
+  }
+
+  [HANDLE_ROUTE]( req ) {
+    const params = req[PARAMS];
+    // If URL = '/bands/the-cure'
+    // params = { bandId: 'the-cure' }
+  }
+}
+```
+
+### Wildcard matching
+
+For a wildcard match (i.e. match entire rest of path) use either:
+
+* `[PATH_PART] = '*'`: Param will be called `*`
+* `[PART_PATH] = '*something'`: Param will be called `something`
 
 ## Versioning