@contextualize/lambda-router 0.0.19 → 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/package.json

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

package/readme.md

@@ -65,10 +65,7 @@ Middleware allow you to run a block of code before all subsequent paths.
 
 
 ```js
-import { Router, Handler } from '@contextualize/lambda-router';
-
-const router = new Router();
-
+// Not protected by token validation
 router.get('/', (req,res)=>{
     return res.status(200).json({
         message: "Welcome!"
@@ -82,14 +79,52 @@ router.use((req)=>{
     // 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
+    })
+})
 
-export const lambdaHandler = Handler.handler(()=>router);
 
+router.subroute('/users/{username}', userRouter);
 ```
 
 ## Background Handler