From 73dfa4aceae7ca8b4900f6a60595e0a67d1dc342 Mon Sep 17 00:00:00 2001 From: Manthan Mallikarjun Date: Mon, 3 Jun 2019 14:15:24 -0700 Subject: [PATCH] update guides and docs --- docs/boom/create-error.md | 6 +++++ docs/docs.json | 14 +++++++++++- docs/light.md | 6 +++++ docs/micro/buffer.md | 6 +++++ docs/micro/json.md | 6 +++++ docs/micro/run.md | 6 +++++ docs/micro/send-error.md | 6 +++++ docs/micro/send.md | 6 +++++ docs/micro/text.md | 6 +++++ guides/error-handling.md | 42 ++++++++++++++++++++++++++++++++++- guides/getting-started.md | 2 +- guides/methods.md | 43 ++++++++++++++++++++++++++++++++++-- website/src/pages/docs.jsx | 17 +++++++++----- website/src/pages/guides.jsx | 17 +++++++++----- 14 files changed, 166 insertions(+), 17 deletions(-) create mode 100644 docs/boom/create-error.md create mode 100644 docs/light.md create mode 100644 docs/micro/buffer.md create mode 100644 docs/micro/json.md create mode 100644 docs/micro/run.md create mode 100644 docs/micro/send-error.md create mode 100644 docs/micro/send.md create mode 100644 docs/micro/text.md diff --git a/docs/boom/create-error.md b/docs/boom/create-error.md new file mode 100644 index 00000000..81618d56 --- /dev/null +++ b/docs/boom/create-error.md @@ -0,0 +1,6 @@ +--- +title: createError +subtitle: micro-boom's create-error function +--- + +## Coming soon diff --git a/docs/docs.json b/docs/docs.json index 475a935f..a50eb50f 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -1,5 +1,17 @@ { "server": "server", "query": "query", - "params": "params" + "params": "params", + "route/light": "light", + "micro": { + "buffer": "micro/buffer", + "text": "micro/text", + "json": "micro/json", + "run": "micro/run", + "send": "micro/send", + "sendError": "micro/send-error" + }, + "boom": { + "createError": "boom/create-error" + } } diff --git a/docs/light.md b/docs/light.md new file mode 100644 index 00000000..9b1cbc3d --- /dev/null +++ b/docs/light.md @@ -0,0 +1,6 @@ +--- +title: light +subtitle: the main function for routes +--- + +## Coming soon diff --git a/docs/micro/buffer.md b/docs/micro/buffer.md new file mode 100644 index 00000000..64700965 --- /dev/null +++ b/docs/micro/buffer.md @@ -0,0 +1,6 @@ +--- +title: buffer +subtitle: micro's buffer function +--- + +## Coming soon diff --git a/docs/micro/json.md b/docs/micro/json.md new file mode 100644 index 00000000..daf5597b --- /dev/null +++ b/docs/micro/json.md @@ -0,0 +1,6 @@ +--- +title: json +subtitle: micro's json function +--- + +## Coming soon diff --git a/docs/micro/run.md b/docs/micro/run.md new file mode 100644 index 00000000..b9963a83 --- /dev/null +++ b/docs/micro/run.md @@ -0,0 +1,6 @@ +--- +title: run +subtitle: micro's run function +--- + +## Coming soon diff --git a/docs/micro/send-error.md b/docs/micro/send-error.md new file mode 100644 index 00000000..b2b41914 --- /dev/null +++ b/docs/micro/send-error.md @@ -0,0 +1,6 @@ +--- +title: sendError +subtitle: micro's send-error function +--- + +## Coming soon diff --git a/docs/micro/send.md b/docs/micro/send.md new file mode 100644 index 00000000..c97fd248 --- /dev/null +++ b/docs/micro/send.md @@ -0,0 +1,6 @@ +--- +title: send +subtitle: micro's send function +--- + +## Coming soon diff --git a/docs/micro/text.md b/docs/micro/text.md new file mode 100644 index 00000000..c24d8870 --- /dev/null +++ b/docs/micro/text.md @@ -0,0 +1,6 @@ +--- +title: text +subtitle: micro's text function +--- + +## Coming soon diff --git a/guides/error-handling.md b/guides/error-handling.md index e2f55277..b6da66b7 100644 --- a/guides/error-handling.md +++ b/guides/error-handling.md @@ -3,4 +3,44 @@ title: error handling subtitle: easily return errors from inside your endpoint --- -## Coming Soon +## Introduction + +Error handling is done mostly by throwing a new Error. Each route is wrapped with a try/catch block so that you can safely throw at any point. The reason throwing for errors is nice is because it allows you to escape from any point in your code! + +## Usage + +Simply import [`createError`](/docs/boom/create-error) and throw it at any point. createError will create a boom error resulting in a pretty JSON output. + +```js +const { light, createError } = require('light'); + +module.exports = light({ + path: '/', + async handler(req, res) { + throw createError(401, 'sorry, you cannot access this route'); + return { + hello: 'world', + }; + }, +}); +``` + +This will result in JSON which looks like this: + +```json +{ + "statusCode": 401, + "error": "Unauthorized", + "message": "sorry, you cannot access this route" +} +``` + +## Error Object + +You can also throw a standard JavaScript `Error` object with a `message` and `statusCode` (defaults to 500). + +```js +const err = new Error('Rate limit exceeded') +err.statusCode = 429 +throw err +``` diff --git a/guides/getting-started.md b/guides/getting-started.md index f5674b6b..e80647bf 100644 --- a/guides/getting-started.md +++ b/guides/getting-started.md @@ -8,7 +8,7 @@ subtitle: a quick guide on how to start with light ### Prerequisites - Node >= `8.0.0` -- NPM >= `8.0.0` +- NPM >= `5.0.0` ### Install diff --git a/guides/methods.md b/guides/methods.md index d3e5e26a..3d0db50d 100644 --- a/guides/methods.md +++ b/guides/methods.md @@ -3,6 +3,45 @@ title: methods subtitle: respond to custom methods when in server mode --- -**Please note that methods are environment specific. The details documented below only apply to [server mode](/guides/server-vs-serverless#server) and serverless environment will have their own method handling** +**Please note that methods are environment specific. The details documented below only apply to [server mode](/guides/server-vs-serverless#server) since serverless environment will have their own method handling** -## Coming Soon +## Introduction + +Under the hood, light uses [find-my-way](https://github.com/delvedor/find-my-way) to route in server mode. find-my-way supports the following HTTP methods: + +- `get` +- `delete` +- `head` +- `patch` +- `post` +- `put` +- `options` +- `all` + +**NOTE: Each serverless provider will have a different way to handle route method, but most just default to `all` for all routes.** + +## Usage + +When in server mode, you can define a custom method. + +```js +const light = require('light'); + +module.exports = light({ + path: '/', + method: 'get', // your method here + async handler() { + // ... + }, +}); +``` + +Additionally, you can provide an array if you want to support multiple methods. + +```js +{ + // ... + method: ['get', 'post', 'options'], // your methods here + // ... +}; +``` diff --git a/website/src/pages/docs.jsx b/website/src/pages/docs.jsx index b0d039da..0f58147f 100644 --- a/website/src/pages/docs.jsx +++ b/website/src/pages/docs.jsx @@ -8,10 +8,15 @@ import Hero from '../components/Hero'; import Sidebar from '../components/Sidebar'; export default class Posts extends React.Component { - static async getInitialProps({ query }) { + static async getInitialProps({ query, req, res }) { let { title } = query; if (!title) { - title = 'server'; + if (req) { + res.writeHead(302, { Location: '/docs/server' }); + return res.end(); + } + + return Router.push('/docs/server'); } const fetchPost = await fetch(join(process.env.BASE_URL, `docs/${title}.md`)); @@ -21,12 +26,12 @@ export default class Posts extends React.Component { const metadata = split.shift().trim(); const content = split.join('---').trim(); - const res = {}; - res.content = content; + const response = {}; + response.content = content; metadata.split('\n').forEach((line) => { const [attr, val] = line.split(':'); - res[attr.trim()] = val.trim(); + response[attr.trim()] = val.trim(); }); const fetchSidebar = await fetch(join(process.env.BASE_URL, `docs/docs.json`)); @@ -36,7 +41,7 @@ export default class Posts extends React.Component { query, menu, path: title, - ...res, + ...response, }; } diff --git a/website/src/pages/guides.jsx b/website/src/pages/guides.jsx index dcac7ed0..83a3c7fa 100644 --- a/website/src/pages/guides.jsx +++ b/website/src/pages/guides.jsx @@ -8,10 +8,15 @@ import Hero from '../components/Hero'; import Sidebar from '../components/Sidebar'; export default class Posts extends React.Component { - static async getInitialProps({ query }) { + static async getInitialProps({ query, req, res }) { let { title } = query; if (!title) { - title = 'getting-started'; + if (req) { + res.writeHead(302, { Location: '/guides/getting-started' }); + return res.end(); + } + + return Router.push('/guides/getting-started'); } const fetchPost = await fetch(join(process.env.BASE_URL, `guides/${title}.md`)); @@ -21,12 +26,12 @@ export default class Posts extends React.Component { const metadata = split.shift().trim(); const content = split.join('---').trim(); - const res = {}; - res.content = content; + const response = {}; + response.content = content; metadata.split('\n').forEach((line) => { const [attr, val] = line.split(':'); - res[attr.trim()] = val.trim(); + response[attr.trim()] = val.trim(); }); const fetchSidebar = await fetch(join(process.env.BASE_URL, `guides/guides.json`)); @@ -36,7 +41,7 @@ export default class Posts extends React.Component { query, menu, path: title, - ...res, + ...response, }; }