@jaypie/express 0.1.0

package/.eslintignore

@@ -0,0 +1 @@
+dist/

package/README.md

@@ -0,0 +1,24 @@
+# Jaypie Express 🐦‍⬛🧋
+
+Express Jaypie handler for AWS Lambda
+
+## 📋 Usage
+
+### Installation
+
+```bash
+npm install @jaypie/express
+```
+
+See [Jaypie documentation](https://github.com/finlaysonstudio/jaypie) for usage.
+
+## 📝 Changelog
+
+| Date       | Version | Summary        |
+| ---------- | ------- | -------------- |
+|  5/19/2024 |   0.1.0 | Initial deploy |
+|  5/12/2024 |   0.0.1 | Initial commit |
+
+## 📜 License
+
+Published by Finlayson Studio. All rights reserved

package/dist/module.cjs.js

@@ -0,0 +1,10 @@
+'use strict';
+
+//
+//
+// Export
+//
+
+var index = {};
+
+module.exports = index;

package/dist/module.esm.js

@@ -0,0 +1,8 @@
+//
+//
+// Export
+//
+
+var index = {};
+
+export { index as default };

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@jaypie/express",
+  "version": "0.1.0",
+  "author": "Finlayson Studio",
+  "type": "module",
+  "exports": {
+    ".": {
+      "default": {
+        "require": "./dist/module.cjs.js",
+        "default": "./src/index.js"
+      }
+    }
+  },
+  "main": "src/index.js",
+  "scripts": {
+    "build": "rollup --config",
+    "format": "npm run format:package && npm run format:lint",
+    "format:lint": "eslint --fix .",
+    "format:package": "sort-package-json ./package.json",
+    "init:deploy": "hygen jaypie workflow-npm",
+    "lint": "eslint .",
+    "new": "hygen jaypie vite",
+    "new:command": "hygen jaypie command",
+    "new:constants": "hygen jaypie constants",
+    "new:hygen": "hygen jaypie hygen",
+    "new:index": "hygen jaypie index",
+    "new:model": "hygen jaypie model",
+    "new:test": "hygen jaypie vitest",
+    "prepublish": "npm run build",
+    "test": "vitest",
+    "test:spec:decorateResponse.helper": "vitest run ./src/__tests__/decorateResponse.helper.spec.js",
+    "test:spec:expressHandler": "vitest run ./src/__tests__/expressHandler.spec.js",
+    "test:spec:getCurrentInvokeUuid.adapter": "vitest run ./src/__tests__/getCurrentInvokeUuid.adapter.spec.js",
+    "test:spec:index": "vitest run ./src/__tests__/index.spec.js",
+    "test:spec:summarizeRequest.helper": "vitest run ./src/__tests__/summarizeRequest.helper.spec.js",
+    "test:spec:summarizeResponse.helper": "vitest run ./src/__tests__/summarizeResponse.helper.spec.js",
+    "test:spec:supertest": "vitest run ./src/__tests__/supertest.spec.js"
+  },
+  "dependencies": {
+    "@codegenie/serverless-express": "^4.14.1",
+    "@jaypie/core": "^1.0.34",
+    "@jaypie/testkit": "^1.0.19",
+    "mock-express-response": "^0.3.0"
+  },
+  "devDependencies": {
+    "@rollup/plugin-commonjs": "^25.0.7",
+    "@rollup/plugin-node-resolve": "^15.2.3",
+    "eslint": "^8.57.0",
+    "eslint-config-prettier": "^9.1.0",
+    "eslint-plugin-import": "^2.29.1",
+    "eslint-plugin-prettier": "^5.1.3",
+    "eslint-plugin-vitest": "^0.5.4",
+    "express": "^4.19.2",
+    "hygen": "^6.2.11",
+    "jest-extended": "^4.0.2",
+    "prettier": "^3.2.5",
+    "rollup": "^4.17.2",
+    "rollup-plugin-auto-external": "^2.0.0",
+    "sort-package-json": "^2.10.0",
+    "supertest": "^7.0.0",
+    "vitest": "^1.6.0"
+  }
+}

package/rollup.config.mjs

@@ -0,0 +1,22 @@
+import autoExternal from "rollup-plugin-auto-external";
+import commonjs from "@rollup/plugin-commonjs";
+import resolve from "@rollup/plugin-node-resolve";
+
+export default {
+  input: "src/index.js", // Path to your main JavaScript file
+  output: [
+    {
+      file: "dist/module.cjs.js", // Output file for CommonJS
+      format: "cjs", // CommonJS format
+    },
+    {
+      file: "dist/module.esm.js", // Output file for ES Module
+      format: "es", // ES Module format
+    },
+  ],
+  plugins: [
+    autoExternal(), // Automatically exclude dependencies from the bundle
+    resolve(), // Tells Rollup how to find node modules
+    commonjs(), // Converts CommonJS modules to ES6
+  ],
+};

package/src/decorateResponse.helper.js

@@ -0,0 +1,90 @@
+import { HTTP, JAYPIE, log as publicLogger } from "@jaypie/core";
+import getCurrentInvokeUuid from "./getCurrentInvokeUuid.adapter.js";
+
+//
+//
+// Main
+//
+
+const decorateResponse = (
+  res,
+  { handler = "", version = process.env.PROJECT_VERSION } = {},
+) => {
+  const log = publicLogger.lib({
+    lib: JAYPIE.LIB.EXPRESS,
+  });
+
+  //
+  //
+  // Validate
+  //
+  if (typeof res !== "object" || res === null) {
+    log.warn("decorateResponse called but response is not an object");
+    return; // eslint-disable-line no-useless-return
+  }
+
+  try {
+    //
+    //
+    // Decorate Headers
+    //
+
+    // X-Powered-By, override "Express" but nothing else
+    if (
+      !res.get(HTTP.HEADER.POWERED_BY) ||
+      res.get(HTTP.HEADER.POWERED_BY) === "Express"
+    ) {
+      res.set(HTTP.HEADER.POWERED_BY, JAYPIE.LIB.EXPRESS);
+    }
+
+    // X-Project-Environment
+    if (process.env.PROJECT_ENV) {
+      res.setHeader(HTTP.HEADER.PROJECT.ENVIRONMENT, process.env.PROJECT_ENV);
+    }
+
+    // X-Project-Handler
+    if (handler) {
+      res.setHeader(HTTP.HEADER.PROJECT.HANDLER, handler);
+    }
+
+    // X-Project-Invocation
+    const currentInvoke = getCurrentInvokeUuid();
+    if (currentInvoke) {
+      res.setHeader(HTTP.HEADER.PROJECT.INVOCATION, currentInvoke);
+    }
+
+    // X-Project-Key
+    if (process.env.PROJECT_KEY) {
+      res.setHeader(HTTP.HEADER.PROJECT.KEY, process.env.PROJECT_KEY);
+    }
+
+    // X-Project-Version
+    if (version) {
+      res.setHeader(HTTP.HEADER.PROJECT.VERSION, version);
+    }
+
+    //
+    //
+    // Error Handling
+    //
+  } catch (error) {
+    log.warn("decorateResponse caught an internal error");
+    log.var({ error });
+  }
+};
+
+//
+//
+// Export
+//
+
+export default decorateResponse;
+
+//
+//
+// Footnotes
+//
+
+// This is a "utility" function but it needs a lot of "context"
+// about the environment's secret parameters, the special adapter,
+// HTTP, etc.  There must be a better way to organize this

package/src/expressHandler.js

@@ -0,0 +1,258 @@
+import {
+  force,
+  HTTP,
+  JAYPIE,
+  jaypieHandler,
+  log as publicLogger,
+  UnhandledError,
+  validate as validateIs,
+} from "@jaypie/core";
+
+import getCurrentInvokeUuid from "./getCurrentInvokeUuid.adapter.js";
+import decorateResponse from "./decorateResponse.helper.js";
+import summarizeRequest from "./summarizeRequest.helper.js";
+import summarizeResponse from "./summarizeResponse.helper.js";
+
+//
+//
+// Main
+//
+
+const expressHandler = (
+  handler,
+  { locals, name, setup = [], teardown = [], unavailable, validate } = {},
+) => {
+  //
+  //
+  // Validate
+  //
+  validateIs.function(handler);
+  validateIs.optional.object(locals);
+  setup = force.array(setup); // allows a single item
+  teardown = force.array(teardown); // allows a single item
+
+  //
+  //
+  // Setup
+  //
+
+  let jaypieFunction;
+
+  return async (req, res, ...params) => {
+    // * This is the first line of code that runs when a request is received
+
+    // Update the public logger with the request ID
+    publicLogger.tag({ invoke: getCurrentInvokeUuid() });
+
+    // Very low-level, internal sub-trace details
+    const libLogger = publicLogger.lib({
+      lib: JAYPIE.LIB.EXPRESS,
+    });
+    libLogger.trace("[jaypie] Express init");
+
+    // Top-level, important details that run at the same level as the main logger
+    const log = publicLogger.lib({
+      level: publicLogger.level,
+      lib: JAYPIE.LIB.EXPRESS,
+    });
+
+    // Set req.locals if it doesn't exist
+    if (!req.locals) req.locals = {};
+    if (!req.locals._jaypie) req.locals._jaypie = {};
+
+    // Set res.locals if it doesn't exist
+    if (!res.locals) res.locals = {};
+    if (!res.locals._jaypie) res.locals._jaypie = {};
+
+    const originalRes = {
+      attemptedCall: undefined,
+      attemptedParams: undefined,
+      end: res.end,
+      json: res.json,
+      send: res.send,
+      status: res.status,
+      statusSent: false,
+    };
+    res.end = (...params) => {
+      originalRes.attemptedCall = originalRes.end;
+      originalRes.attemptedParams = params;
+      log.warn(
+        "[jaypie] Illegal call to res.end(); prefer Jaypie response conventions",
+      );
+    };
+    res.json = (...params) => {
+      originalRes.attemptedCall = originalRes.json;
+      originalRes.attemptedParams = params;
+      log.warn(
+        "[jaypie] Illegal call to res.json(); prefer Jaypie response conventions",
+      );
+    };
+    res.send = (...params) => {
+      originalRes.attemptedCall = originalRes.send;
+      originalRes.attemptedParams = params;
+      log.warn(
+        "[jaypie] Illegal call to res.send(); prefer Jaypie response conventions",
+      );
+    };
+    res.status = (...params) => {
+      originalRes.statusSent = true;
+      return originalRes.status(...params);
+    };
+
+    //
+    //
+    // Preprocess
+    //
+
+    if (locals) {
+      // Locals
+      const keys = Object.keys(locals);
+      if (keys.length > 0) {
+        const localsSetup = async () => {
+          libLogger.trace("[jaypie] Locals");
+          for (let i = 0; i < keys.length; i += 1) {
+            const key = keys[i];
+            if (typeof locals[key] === "function") {
+              // eslint-disable-next-line no-await-in-loop
+              req.locals[key] = await locals[key](req, res);
+            } else {
+              req.locals[key] = locals[key];
+            }
+          }
+        };
+        setup.push(localsSetup);
+      }
+    }
+
+    if (!jaypieFunction) {
+      // Initialize after logging is set up
+      jaypieFunction = jaypieHandler(handler, {
+        name,
+        setup,
+        teardown,
+        unavailable,
+        validate,
+      });
+    }
+
+    let response;
+    let status;
+
+    try {
+      libLogger.trace("[jaypie] Lambda execution");
+      log.info.var({ req: summarizeRequest(req) });
+
+      //
+      //
+      // Process
+      //
+
+      response = await jaypieFunction(req, res, ...params);
+
+      //
+      //
+      // Error Handling
+      //
+    } catch (error) {
+      // In theory jaypieFunction has handled all errors
+      if (error.status) {
+        status = error.status;
+      }
+      if (typeof error.json === "function") {
+        response = error.json();
+      } else {
+        // This should never happen
+        const unhandledError = new UnhandledError();
+        response = unhandledError.json();
+        status = unhandledError.status;
+      }
+    }
+
+    //
+    //
+    // Postprocess
+    //
+
+    // Restore original res functions
+    res.end = originalRes.end;
+    res.json = originalRes.json;
+    res.send = originalRes.send;
+    res.status = originalRes.status;
+
+    // Decorate response
+    decorateResponse(res, { handler: name });
+
+    // Send response
+    try {
+      // Status
+      if (status && !originalRes.statusSent) {
+        res.status(status);
+      }
+
+      if (!originalRes.attemptedCall) {
+        // Body
+        if (response) {
+          if (typeof response === "object") {
+            if (typeof response.json === "function") {
+              res.json(response.json());
+            } else {
+              res.json(response);
+            }
+          } else if (typeof response === "string") {
+            try {
+              res.json(JSON.parse(response));
+            } catch (error) {
+              res.send(response);
+            }
+          } else if (response === true) {
+            res.status(HTTP.CODE.CREATED);
+            res.send();
+          } else {
+            res.send(response);
+          }
+        } else {
+          // No response
+          res.status(HTTP.CODE.NO_CONTENT).send();
+        }
+      } else {
+        // Resolve illegal call to res.end(), res.json(), or res.send()
+        log.debug("[jaypie] Resolving illegal call to res");
+        log.var({
+          attemptedCall: {
+            name: originalRes.attemptedCall.name,
+            params: originalRes.attemptedParams,
+          },
+        });
+        // Call the original function with the original parameters and the original `this` (res)
+        originalRes.attemptedCall.call(res, ...originalRes.attemptedParams);
+      }
+    } catch (error) {
+      log.fatal("Express encountered an error while sending the response");
+      log.var({ responseError: error });
+    }
+
+    // Log response
+    const extras = {};
+    if (response) extras.body = response;
+    log.info.var({
+      res: summarizeResponse(res, extras),
+    });
+
+    // Clean up the public logger
+    publicLogger.untag("handler");
+
+    //
+    //
+    // Return
+    //
+
+    return response;
+  };
+};
+
+//
+//
+// Export
+//
+
+export default expressHandler;

package/src/getCurrentInvokeUuid.adapter.js

@@ -0,0 +1,33 @@
+import { getCurrentInvoke } from "@codegenie/serverless-express";
+
+//
+//
+// Helper Functions
+//
+
+// Adapter for the "@codegenie/serverless-express" uuid
+function getServerlessExpressUuid() {
+  const currentInvoke = getCurrentInvoke();
+  if (
+    currentInvoke &&
+    currentInvoke.context &&
+    currentInvoke.context.awsRequestId
+  ) {
+    return currentInvoke.context.awsRequestId;
+  }
+  return undefined;
+}
+
+//
+//
+// Main
+//
+
+const getCurrentInvokeUuid = () => getServerlessExpressUuid();
+
+//
+//
+// Export
+//
+
+export default getCurrentInvokeUuid;

package/src/index.js

@@ -0,0 +1,6 @@
+//
+//
+// Export
+//
+
+export default {};

package/src/summarizeRequest.helper.js

@@ -0,0 +1,28 @@
+//
+//
+// Function Definition
+//
+
+function summarizeRequest(req) {
+  // If body is a buffer, convert it to a string
+  let { body } = req;
+  if (Buffer.isBuffer(body)) {
+    body = body.toString();
+  }
+
+  return {
+    baseUrl: req.baseUrl,
+    body,
+    headers: req.headers,
+    method: req.method,
+    query: req.query,
+    url: req.url,
+  };
+}
+
+//
+//
+// Export
+//
+
+export default summarizeRequest;

package/src/summarizeResponse.helper.js

@@ -0,0 +1,25 @@
+//
+//
+// Function Definition
+//
+
+function summarizeResponse(res, extras) {
+  const response = {
+    statusCode: res.statusCode,
+    statusMessage: res.statusMessage,
+  };
+  if (typeof res.getHeaders === "function") {
+    response.headers = res.getHeaders();
+  }
+  if (typeof extras === "object" && extras !== null) {
+    Object.assign(response, extras);
+  }
+  return response;
+}
+
+//
+//
+// Export
+//
+
+export default summarizeResponse;