dce-reactkit 3.1.13 → 3.1.15

package/dist/esm/types/helpers/genRouteHandler.d.ts

@@ -7,10 +7,15 @@ import ParamType from '../types/ParamType';
  *   included in the request (map: param name => type)
  * @param opts.handler function that processes the request
  * @returns express route handler that takes the following arguments:
- *   params (map: param name => value), handleSuccess (function for handling
- *   successful requests), handleError (function for handling failed requests),
- *   req (express request object), res (express response object),
- *   next (express next function). Params also has userId, userFirstName,
+ *   params (map: param name => value),
+ *   req (express request object),
+ *   next (express next function),
+ *   send (a function that sends a string to the client),
+ *   redirect (takes a url and redirects the user to that url),
+ *   renderErrorPage (shows a static error page to the user),
+ *   and returns the value to send to the client as a JSON API response, or
+ *   calls next() or redirect(...) or send(...) or renderErrorPage(...).
+ *   Note: params also has userId, userFirstName,
  *   userLastName, isLearner, isTTM, isAdmin, and any other variables that
  *   are directly added to the session
  */
@@ -23,8 +28,16 @@ declare const genRouteHandler: (opts: {
             [k: string]: any;
         };
         req: any;
-        res: any;
         next: () => void;
+        redirect: (pathOrURL: string) => void;
+        send: (text: string, status?: number | undefined) => void;
+        renderErrorPage: (opts?: {
+            title?: string | undefined;
+            description?: string | undefined;
+            code?: string | undefined;
+            pageTitle?: string | undefined;
+            status?: number | undefined;
+        } | undefined) => void;
     }) => any;
 }) => (req: any, res: any, next: () => void) => Promise<undefined>;
 export default genRouteHandler;

package/dist/esm/types/html/genErrorPage.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Generate a static error page
+ * @author Gabe Abrams
+ * @param opts object containing all arguments
+ * @param [opts.title=An Error Occurred] title of the error box
+ * @param [opts.description=An unknown server error occurred. Please contact support.]
+ *   a human-readable description of the error
+ * @param [opts.code=ReactKitErrorCode.NoCode] error code to show
+ * @param [opts.pageTitle=opts.title] title of the page/tab if it differs from
+ *   the title of the error
+ * @returns html of the page
+ */
+declare const genErrorPage: (opts?: {
+    title?: string;
+    description?: string;
+    code?: string;
+    pageTitle?: string;
+}) => string;
+export default genErrorPage;

package/dist/index.d.ts

@@ -510,10 +510,15 @@ declare enum ParamType {
  *   included in the request (map: param name => type)
  * @param opts.handler function that processes the request
  * @returns express route handler that takes the following arguments:
- *   params (map: param name => value), handleSuccess (function for handling
- *   successful requests), handleError (function for handling failed requests),
- *   req (express request object), res (express response object),
- *   next (express next function). Params also has userId, userFirstName,
+ *   params (map: param name => value),
+ *   req (express request object),
+ *   next (express next function),
+ *   send (a function that sends a string to the client),
+ *   redirect (takes a url and redirects the user to that url),
+ *   renderErrorPage (shows a static error page to the user),
+ *   and returns the value to send to the client as a JSON API response, or
+ *   calls next() or redirect(...) or send(...) or renderErrorPage(...).
+ *   Note: params also has userId, userFirstName,
  *   userLastName, isLearner, isTTM, isAdmin, and any other variables that
  *   are directly added to the session
  */
@@ -526,8 +531,16 @@ declare const genRouteHandler: (opts: {
             [k: string]: any;
         };
         req: any;
-        res: any;
         next: () => void;
+        redirect: (pathOrURL: string) => void;
+        send: (text: string, status?: number | undefined) => void;
+        renderErrorPage: (opts?: {
+            title?: string | undefined;
+            description?: string | undefined;
+            code?: string | undefined;
+            pageTitle?: string | undefined;
+            status?: number | undefined;
+        } | undefined) => void;
     }) => any;
 }) => (req: any, res: any, next: () => void) => Promise<undefined>;
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dce-reactkit",
-  "version": "3.1.13",
+  "version": "3.1.15",
   "description": "Shared components for Harvard DCE apps",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",

package/src/helpers/genRouteHandler.ts

@@ -8,6 +8,15 @@ import ParamType from '../types/ParamType';
 // Import helpers
 import handleError from './handleError';
 import handleSuccess from './handleSuccess';
+import genErrorPage from '../html/genErrorPage';
+
+/*------------------------------------------------------------------------*/
+/*                                 Helpers                                */
+/*------------------------------------------------------------------------*/
+
+/*------------------------------------------------------------------------*/
+/*                                  Main                                  */
+/*------------------------------------------------------------------------*/
 
 /**
  * Generate an express API route handler
@@ -17,10 +26,15 @@ import handleSuccess from './handleSuccess';
  *   included in the request (map: param name => type)
  * @param opts.handler function that processes the request
  * @returns express route handler that takes the following arguments:
- *   params (map: param name => value), handleSuccess (function for handling
- *   successful requests), handleError (function for handling failed requests),
- *   req (express request object), res (express response object),
- *   next (express next function). Params also has userId, userFirstName,
+ *   params (map: param name => value),
+ *   req (express request object),
+ *   next (express next function),
+ *   send (a function that sends a string to the client),
+ *   redirect (takes a url and redirects the user to that url),
+ *   renderErrorPage (shows a static error page to the user),
+ *   and returns the value to send to the client as a JSON API response, or
+ *   calls next() or redirect(...) or send(...) or renderErrorPage(...).
+ *   Note: params also has userId, userFirstName,
  *   userLastName, isLearner, isTTM, isAdmin, and any other variables that
  *   are directly added to the session
  */
@@ -35,8 +49,18 @@ const genRouteHandler = (
           [k: string]: any
         },
         req: any,
-        res: any,
         next: () => void,
+        redirect: (pathOrURL: string) => void,
+        send: (text: string, status?: number) => void,
+        renderErrorPage: (
+          opts?: {
+            title?: string,
+            description?: string,
+            code?: string,
+            pageTitle?: string,
+            status?: number,
+          },
+        ) => void,
       },
     ) => any,
   },
@@ -376,17 +400,53 @@ const genRouteHandler = (
     /*                              Call handler                              */
     /*------------------------------------------------------------------------*/
 
-    // Keep track of whether "next" was called
-    let nextCalled = false;
+    // Keep track of whether a response was already sent
+    let responseSent = false;
 
     /**
-     * Call the "next" function and keep track of the call so responses
-     *   are not sent
+     * Redirect the user to another path or url
      * @author Gabe Abrams
+     * @param pathOrURL the path or url to redirect to
      */
-    const nextWithTracking = () => {
-      nextCalled = true;
-      next();
+    const redirect = (pathOrURL: string) => {
+      responseSent = true;
+      res.redirect(pathOrURL);
+    };
+
+    /**
+     * Send text to the client (with an optional status code)
+     * @author Gabe Abrams
+     * @param text the text to send to the client
+     * @parm [status=200] the http status code to send
+     */
+    const send = (text: string, status: number = 200) => {
+      responseSent = true;
+      res.status(status).send(text);
+    };
+
+    /**
+     * Render an error page
+     * @author Gabe Abrams
+     * @param opts object containing all arguments
+     * @param [opts.title=An Error Occurred] title of the error box
+     * @param [opts.description=An unknown server error occurred. Please contact support.]
+     *   a human-readable description of the error
+     * @param [opts.code=ReactKitErrorCode.NoCode] error code to show
+     * @param [opts.pageTitle=opts.title] title of the page/tab if it differs from
+     *   the title of the error
+     * @param [opts.status=500] http status code
+     */
+    const renderErrorPage = (
+      opts: {
+        title?: string,
+        description?: string,
+        code?: string,
+        pageTitle?: string,
+        status?: number,
+      } = {},
+    ) => {
+      const html = genErrorPage(opts);
+      send(html, opts.status ?? 500);
     };
 
     // Call the handler
@@ -394,19 +454,27 @@ const genRouteHandler = (
       const results = await opts.handler({
         params: output,
         req,
-        res,
-        next: nextWithTracking,
+        send,
+        next: () => {
+          responseSent = true;
+          next();
+        },
+        redirect,
+        renderErrorPage,
       });
 
       // Send results to client (only if next wasn't called)
-      if (!nextCalled) {
+      if (!responseSent) {
         return handleSuccess(res, results ?? undefined);
       }
     } catch (err) {
       // Send error to client (only if next wasn't called)
-      if (!nextCalled) {
+      if (!responseSent) {
         return handleError(res, err);
       }
+
+      // Log error that was not responded with
+      console.log('Error occurred but could not be sent to client because a response was already sent:', err);
     }
   };
 };

package/src/html/genErrorPage.ts

@@ -0,0 +1,141 @@
+// Import shared types
+import ReactKitErrorCode from '../types/ReactKitErrorCode';
+
+/**
+ * Generate a static error page
+ * @author Gabe Abrams
+ * @param opts object containing all arguments
+ * @param [opts.title=An Error Occurred] title of the error box
+ * @param [opts.description=An unknown server error occurred. Please contact support.]
+ *   a human-readable description of the error
+ * @param [opts.code=ReactKitErrorCode.NoCode] error code to show
+ * @param [opts.pageTitle=opts.title] title of the page/tab if it differs from
+ *   the title of the error
+ * @returns html of the page
+ */
+const genErrorPage = (
+  opts: {
+    title?: string,
+    description?: string,
+    code?: string,
+    pageTitle?: string,
+  } = {},
+): string => {
+  const title = (opts.title ?? 'An Error Occurred');
+  const pageTitle = (opts.pageTitle ?? title);
+  const description = (
+    opts.description
+    ?? 'An unknown server error occurred. Please contact support.'
+  );
+  const code = (opts.code ?? ReactKitErrorCode.NoCode);
+
+  return `
+<head>
+  <!-- Metadata -->
+  <meta
+    name="viewport"
+    content="width=device-width, height=device-height, initial-scale=1.0, minimum-scale=1.0"
+  >
+
+  <!-- Title -->
+  <title>${pageTitle}</title>
+
+  <!-- Bootstrap -->
+  <link
+    rel="stylesheet"
+    href="https://cdnjs.cloudflare.com/ajax/libs/bootstrap/5.2.1/css/bootstrap.min.css"
+    integrity="sha512-siwe/oXMhSjGCwLn+scraPOWrJxHlUgMBMZXdPe2Tnk3I0x3ESCoLz7WZ5NTH6SZrywMY+PB1cjyqJ5jAluCOg=="
+    crossorigin="anonymous"
+    referrerpolicy="no-referrer"
+  />
+  <script
+    src="https://cdnjs.cloudflare.com/ajax/libs/bootstrap/5.2.1/js/bootstrap.min.js"
+    integrity="sha512-vyRAVI0IEm6LI/fVSv/Wq/d0KUfrg3hJq2Qz5FlfER69sf3ZHlOrsLriNm49FxnpUGmhx+TaJKwJ+ByTLKT+Yg=="
+    crossorigin="anonymous"
+    referrerpolicy="no-referrer"
+  ></script>
+
+  <!-- FontAwesome -->
+  <link
+    rel="stylesheet"
+    href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.2.0/css/all.min.css"
+    integrity="sha512-xh6O/CkQoPOWDdYTDqeRdPCVd1SpvCA9XXcUnZS2FmJNp1coAFzvtCN9BmamE+4aHK8yyUHUSCcJHgXloTyT2A=="
+    crossorigin="anonymous"
+    referrerpolicy="no-referrer"
+  />
+
+  <!-- Style -->
+  <style>
+    .DCEReactKit-pop-in {
+      animation-name: DCEReactKit-pop-in;
+      animation-duration: 0.5s;
+      animation-iteration-count: 1;
+      animation-timing-function: ease-out;
+      animation-fill-mode: both;
+
+      transform-origin: center;
+    }
+
+    @keyframes DCEReactKit-pop-in {
+      0% {
+        opacity: 0;
+        transform: scale(0.9);
+      }
+      100% {
+        opacity: 1;
+        transform: scale(1);
+      }
+    }
+
+    .DCEReactKit-slide-in {
+      animation-name: DCEReactKit-slide-in;
+      animation-duration: 1s;
+      animation-iteration-count: 1;
+      animation-timing-function: ease-out;
+      animation-fill-mode: both;
+      animation-delay: 0.2s;
+    }
+
+    @keyframes DCEReactKit-slide-in {
+      0% {
+        opacity: 0;
+        transform: translate(0, 0.3em);
+      }
+      100% {
+        opacity: 1;
+        transform: translate(0, 0);
+      }
+    }
+  </style>
+</head>
+
+<!-- Body -->
+<body class="bg-dark text-center pt-3 ps-3 pe-3">
+  <!-- Alert -->
+  <div
+    class="DCEReactKit-pop-in alert alert-warning d-inline-block"
+    style="width: 50em; max-width: 100%"
+  >
+    <!-- Title -->
+    <h2>
+      <i class="me-1 fa-solid fa-triangle-exclamation"></i>
+      ${title}
+    </h2>
+    <!-- Description -->
+    <div>
+      ${description}
+    </div>
+  </div>
+
+  <!-- Error Code -->
+  <div class="DCEReactKit-slide-in text-light">
+    <strong>
+      Error Code:
+    </strong>
+    ${code}
+  </div>
+</body>
+  `;
+};
+
+export default genErrorPage;

package/tsconfig.json

@@ -5,7 +5,6 @@
     "forceConsistentCasingInFileNames": true,
     "strict": true,
     "skipLibCheck": true,
-
     "jsx": "react",
     "module": "ESNext",
     "declaration": true,