From 7070090dcd18a2e513f5216faa23d202c0c99d5a Mon Sep 17 00:00:00 2001 From: Starbeamrainbowlabs Date: Mon, 13 Jan 2020 00:18:19 +0000 Subject: [PATCH] Add more code examples --- README.md | 20 +++++++++++++++++++- Server/Router.mjs | 30 ++++++++++++++++++++++++++++++ package.json | 2 +- 3 files changed, 50 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 089b706..eedf2b7 100644 --- a/README.md +++ b/README.md @@ -45,6 +45,14 @@ const router = new ClientRouter({ verbose: false, // Whether to be verbose in console.log() messages listen_pushstate: true, // Whether to react to browser pushstate events (excluding those generated by powahroot itself, because that would cause an infinite loop :P) }); + +// Add a page +router.add_page("/add/vegetable/:name/:weight", (params) => { + console.log(`We added a ${params.name} with a weight of ${params.weight}g.`); +}); + +// Explicitly navigate to a page: +router.navigate("/add/carrot/frederick/10001"); ``` ### Server @@ -56,9 +64,17 @@ import ServerRouter from 'powahroot/Server.mjs'; // .... const router = new ServerRouter(); -router.on_all(async (context, next) => { console.debug(context.url); await next()}) +// Logging middle ware +router.on_all(async (context, next) => { + console.debug(context.url); + await next(); +}); +// Regular handlere router.get("/files/::filepath", (context, _next) => context.send.plain(200, `You requested ${context.params.filepath}`)); // ..... + +// Later, when you've got a request / response pair to handle: +router.handle(request, response); ``` The `context` argument there is of type `RouterContext`. Check out the API reference (link below) to learn about the other useful properties it has. @@ -68,6 +84,8 @@ API docs are generated automatically. View them here: +It contains full documentation on how to use everything, along with code examples to help you get started. + ## Contributing Contributions are welcome! Simply fork this repository, make your changes, and submit a [Pull Request](https://help.github.com/en/articles/about-pull-requests) (issues are welcome too!). diff --git a/Server/Router.mjs b/Server/Router.mjs index 281946e..c6826ea 100644 --- a/Server/Router.mjs +++ b/Server/Router.mjs @@ -44,18 +44,31 @@ class ServerRouter * Shortcut function for attaching an action to head requests. Full function: on * @param {string|RegExp} pathspec The pathspec that the route should match against. * @param {Fuction} action The function to execute. + * @example + * router.head("/location/:name/status", (context, _next) => { + * context.send.plain(200, `Coming in from ${context.params.type} - status ok!`); + * }); */ head(pathspec, action) { this.on(["head"], pathspec, action); } /** * Shortcut function for attaching an action to get requests. Full function: on * @param {string|RegExp} pathspec The pathspec that the route should match against. * @param {Fuction} action The function to execute. + * @example + * router.get("/tree/:type", (context, _next) => { + * context.send.plain(200, `Hello, I am a ${context.params.type}`); + * }); */ get(pathspec, action) { this.on(["get"], pathspec, action); } /** * Shortcut function for attaching an action to post requests. Full function: on * @param {string|RegExp} pathspec The pathspec that the route should match against. * @param {Fuction} action The function to execute. + * @example + * router.post("/loaction/:name/update", (context, _next) => { + * context.send.plain(501, `Hello from ${context.params.name}! I don't yet support updating my firmware.\nYou asked me to update to version ${context.post_data.version}.`); + * // See https://github.com/sbrl/powahroot/blob/master/examples/parse_post_data.mjs for an example of parsing post data with middleware that works with the above (context.post_data is not created automatically by powahroot) + * }); */ post(pathspec, action) { this.on(["post"], pathspec, action); } /** @@ -74,6 +87,10 @@ class ServerRouter * Shortcut function for attaching an action to options requests. Full function: on * @param {string|RegExp} pathspec The pathspec that the route should match against. * @param {Fuction} action The function to execute. + * @example + * router.options("/location/:name/status", (context, _next) => { + * context.send.plain(200, `I support these actions:\n - GET: Get my status\n - POST: Set my status\n - OPTIONS: Show this message`);; + * }); */ options(pathspec, action) { this.on(["options"], pathspec, action); } @@ -83,6 +100,10 @@ class ServerRouter * @param {array} methods The HTTP methods to run the action for. Include '*' to specify all methods. * @param {string|regex} pathspec The specification of the paths that this action should match against. May be a regular expression. * @param {Function} action The action to execute. Will be passed the parameters `context` (RouterContext) and `next` (Function). + * @example + * router.on(["get"], "/garden/:vegetable", (context) => { + * context.send(201, `Planted ${context.params.vegetable}`); + * }); */ on(methods, pathspec, action) { let regex_info = pathspec instanceof RegExp ? {regex: pathspec, tokens: [] } : pathspec_to_regex(pathspec); @@ -111,6 +132,10 @@ class ServerRouter * Adds a route that matches against every request. * Usually useful for middleware (e.g. error handlers, request loggers, authentication handlers, etc.). * @param {Function} action The function to execute. + * @example + * router.on_all((context) => { + * context.send.plain(200, "Hello, world!"); + * }); */ on_all(action) { this.actions.push(action); @@ -138,6 +163,11 @@ class ServerRouter * @param {http.ClientRequest} request The request to handle. * @param {http.ServerResponse} response The response object to use to send the response. * @return {[type]} [description] + * @example + * const server = http.createServer((request, response) => { + * router.handle(request, response); + * }); + * server.listen(3500, "127.0.0.1", () => console.log("Listening on http://127.0.0.1:3500/")); */ async handle(request, response) { let context = new RouterContext(request, response), diff --git a/package.json b/package.json index eaa7f7d..417176f 100644 --- a/package.json +++ b/package.json @@ -19,7 +19,7 @@ "bugs": { "url": "https://github.com/sbrl/powerroot/issues" }, - "homepage": "https://github.com/sbrl/powerroot#readme", + "homepage": "https://github.com/sbrl/powahroot#readme", "dependencies": { "cookie": "^0.4.0", "nightink": "^0.1.3"