@contextualize/lambda-router 0.0.18 → 0.0.21

package/dist/handler.d.ts

@@ -11,9 +11,30 @@ export default class Handler {
     private canDoBackground;
     private backgroundProcesses;
     private static executeRouter;
-    static handler(setup: HandlerSetup, cleanup?: HandlerCleanup): (event: APIGatewayEvent) => Promise<APIGatewayResponse<any>>;
+    /**
+     * Register a background process that can past a resolution being returned to the lambda handler
+     */
     background(process: BackgroundProcess | (() => BackgroundProcess)): void;
+    /**
+     * Wait for the promise to be resolved before killing the lambda.
+     *
+     * Can be run in standard handler
+     */
+    await(process: BackgroundProcess | (() => BackgroundProcess)): void;
     waitForBackgroundProcesses(): Promise<void>;
-    static serverHandler(setup: HandlerSetup, cleanup?: HandlerCleanup, props?: Parameters<typeof Server.serve>[1]): Promise<import("http").Server<typeof import("http").IncomingMessage, typeof import("http").ServerResponse> | import("https").Server<typeof import("http").IncomingMessage, typeof import("http").ServerResponse>>;
+    /**
+     * A standard handler. No response will be returned until all processes have completed
+     */
+    static handler(setup: HandlerSetup, cleanup?: HandlerCleanup): (event: APIGatewayEvent) => Promise<APIGatewayResponse<any>>;
+    /**
+     * An advanced handler that allows promises to keep running in the background.
+     * Allows for quick responses when triggering long running tasks.
+     */
     static backgroundHandler(setup: HandlerSetup, cleanup?: HandlerCleanup): import("aws-lambda").Handler<any, any>;
+    /**
+     * Starts a node native HTTP/S server
+     *
+     * **Alternatively:** Start the lambda using `lambda-router serve`
+     */
+    static serverHandler(setup: HandlerSetup, cleanup?: HandlerCleanup, props?: Parameters<typeof Server.serve>[1]): Promise<import("http").Server<typeof import("http").IncomingMessage, typeof import("http").ServerResponse> | import("https").Server<typeof import("http").IncomingMessage, typeof import("http").ServerResponse>>;
 }

package/dist/handler.js

@@ -18,25 +18,24 @@ class Handler {
             result = new response_1.default();
             result.status(500).json({ message: "An unhandled error was encountered" });
         }
-        handler.isInHandler = false;
         return result;
     }
-    static handler(setup, cleanup) {
-        const handler = new Handler();
-        handler.canDoBackground = false;
-        return async (event) => {
-            const result = await this.executeRouter(event, handler, setup);
-            if (cleanup) {
-                await cleanup(event);
-            }
-            return result;
-        };
-    }
+    /**
+     * Register a background process that can past a resolution being returned to the lambda handler
+     */
     background(process) {
         console.log("Registering background process");
         if (!this.canDoBackground) {
             throw new Error("Lambda handler not configured to use background processes");
         }
+        this.await(process);
+    }
+    /**
+     * Wait for the promise to be resolved before killing the lambda.
+     *
+     * Can be run in standard handler
+     */
+    await(process) {
         if (!this.isInHandler) {
             throw new Error("Cannot push a new background process outside of router execution");
         }
@@ -46,6 +45,7 @@ class Handler {
         this.backgroundProcesses.push(process);
     }
     async waitForBackgroundProcesses() {
+        this.isInHandler = false;
         this.canDoBackground = false;
         if (this.backgroundProcesses.length > 0) {
             console.log("Awaiting background processes");
@@ -58,21 +58,29 @@ class Handler {
             });
         }
     }
-    static serverHandler(setup, cleanup, props) {
+    /**
+     * A standard handler. No response will be returned until all processes have completed
+     */
+    static handler(setup, cleanup) {
         const handler = new Handler();
-        handler.canDoBackground = true;
-        return server_1.default.serve((async (event, response) => {
-            let result = await this.executeRouter(event, handler, setup);
-            response(result);
+        handler.canDoBackground = false;
+        return async (event) => {
+            const result = await this.executeRouter(event, handler, setup);
             await handler.waitForBackgroundProcesses();
             if (cleanup) {
                 await cleanup(event);
             }
-        }), props);
+            return result;
+        };
     }
+    /**
+     * An advanced handler that allows promises to keep running in the background.
+     * Allows for quick responses when triggering long running tasks.
+     */
     static backgroundHandler(setup, cleanup) {
-        return awslambda.streamifyResponse(async (event, responseStream, _context) => {
+        return awslambda.streamifyResponse(async (event, responseStream, context) => {
             const handler = new Handler();
+            context.callbackWaitsForEmptyEventLoop = false;
             handler.canDoBackground = true;
             let result = await this.executeRouter(event, handler, setup);
             responseStream.write(JSON.stringify(result));
@@ -83,5 +91,23 @@ class Handler {
             }
         });
     }
+    /**
+     * Starts a node native HTTP/S server
+     *
+     * **Alternatively:** Start the lambda using `lambda-router serve`
+     */
+    static serverHandler(setup, cleanup, props) {
+        return server_1.default.serve((async (event, response) => {
+            const handler = new Handler();
+            handler.canDoBackground = true;
+            handler.isInHandler = true;
+            let result = await this.executeRouter(event, handler, setup);
+            response(result);
+            await handler.waitForBackgroundProcesses();
+            if (cleanup) {
+                await cleanup(event);
+            }
+        }), props);
+    }
 }
 exports.default = Handler;

package/dist/router.js

@@ -66,8 +66,9 @@ class Router {
                 response.json({ message: exception.message });
             }
             else {
-                console.error(`Request experienced a critical error`);
-                throw exception;
+                console.error(`Request experienced a critical error: `, exception);
+                response.statusCode = 500;
+                response.json({ message: "Internal Server Error" });
             }
         }
         return response;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contextualize/lambda-router",
-  "version": "0.0.18",
+  "version": "0.0.21",
   "description": "Allows for the creation of Express-like APIs within AWS Lambda",
   "main": "dist/index.js",
   "bin": {

package/readme.md

@@ -2,8 +2,9 @@
 
 Allows for the creation of Express-like APIs within AWS Lambda.
 
-## Create Router
-
+## Routers
+Routers allow you to construct API paths for your application
+### Basic Usage
 ```js
 import { Router, Handler } from '@contextualize/lambda-router';
 
@@ -19,6 +20,113 @@ export const lambdaHandler = Handler.handler(()=>router);
 
 ```
 
+### Errors
+Lambda router has a number of built-in exceptions for common HTTP error codes. Rather than explicity sending an error response and returning from your endpoint code, you can just throw one of these exceptions.
+
+If your application throws an error that does not extend from `@contextualize/lambda-router/PublicError`, a HTTP 500 status is returned by default with 'Internal Server Error'
+
+```js
+router.post('/', (req, res)=>{
+    if(!("required" in req.body)){
+        // Ends execution
+        // Returns a HTTP 400 error to the user
+        // Error message is supplied to user in the response body as json
+        throw new BadRequestError("'required' must be in request body");
+    }
+
+    return res.status(200).json({
+        status: "ok"
+    });
+})
+
+```
+
+### Path Parameters
+Parameters can be passed in through the path using `{}`. Lambda Router will always prioritize named paths before attempting to use a parameterized path.
+```js
+router.get('/{myParam}', (req, res)=>{
+    return res.status(200).json({
+        status: "ok"
+        myParam: req.params['myParam']
+    });
+});
+
+
+router.get('/list', (req, res)=>{
+    return res.status(200).json({
+        status: "ok"
+        list: ['stuff', 'and', 'things']
+    });
+});
+```
+
+### Middleware
+Middleware allow you to run a block of code before all subsequent paths.
+
+
+```js
+// Not protected by token validation
+router.get('/', (req,res)=>{
+    return res.status(200).json({
+        message: "Welcome!"
+    });
+})
+
+// Check user token
+router.use((req)=>{
+    const token = req.headers['Authorization'];
+
+    // Do some token validation
+})
+
+// Protected by token validation
+router.get('/protected', (req, res)=>{
+    return res.status(200).json({
+        message: "You are authenticated"
+    });
+})
+```
+
+### Subrouting
+Subrouters allow you to organize like routes as well as define known states of the request a certain paths.
+
+```ts
+const router = new Router();
+
+router.get('/', (req, res)=>{
+
+    res.status(200).json({
+        message: 'Home'
+    })
+})
+
+type UserApp = {data: UserProfile}
+const userRouter = new Router<UserApp>();
+
+
+dataRouter.use(async (req)=>{
+    // Load user's profile from the database
+    req.app = {data: await User.load(req.params['username'])};
+});
+
+userRouter.get('/', (req, res)=>{
+    // Return user's data
+    res.status(200).json({
+        ...req.app.data
+    })
+})
+
+userRouter.get('/groups', (req, res)=>{
+    // Return user's groups
+    res.status(200).json({
+        groups: req.app.data.groups
+    })
+})
+
+
+router.subroute('/users/{username}', userRouter);
+```
+
 ## Background Handler
 Some lambdas may require tasks to run in the background after a request has been handled. `Handler.backgroundHandler` allows you to defer promises for after the lambda has returned a response to the client.
 
@@ -30,7 +138,8 @@ const router = new Router();
 router.get('/', (req, res)=>{
     req.handler.background(async ()=>{
 
-        // Assume this a request that is going to take a long time
+        // Assume this is a request that is going to take a long time
+        // i.e. uploading a file, running a put query
         await fetch('https://example.com')
     })