WAPI - Web Application Programming Interface

WAPI is a powerful API wrapper designed to streamline web application development. It offers opinionated abstractions, simplifying common web development tasks. At its core, WAPI revolves around the concept of transactions, which can be applied in diverse scenarios, including handling async events, managing message queues, running AWS Lambda functions, and creating hybrid HTTP servers that seamlessly blend serverless and container-based approaches.

Documentation available here

📖 Table of Contents

• 📖 Table of Contents
• 📍 Overview
• 📦 Features
• ⚙️ Modules
• 🚀 Getting Started
  • 🔧 Installation
  • 🤖 Running .
  • 🧪 Tests
• 🤝 Contributing

📍 Overview

The project is a TypeScript application that provides a collection of modules for handling transactions, managing processes, routing requests, sending emails, performing cryptographic operations, managing configuration settings, constructing HTTP responses, and providing utility functions and route definitions. It also includes tools for logging messages, validating data, and working with JSON Web Tokens. The core functionalities of the project revolve around helping developers build robust web applications and simplify common development tasks, such as handling requests, managing processes, and ensuring secure communication. Its value proposition lies in providing a comprehensive set of reusable components and abstractions that streamline the development process and improve the overall stability and security of web applications.

📦 Features

Opinionated Framework Wrapping: WAPI offers opinionated abstractions to simplify common web development tasks and guide developers towards best practices.

Transaction-Based Architecture: The core concept of transactions simplifies request and response handling, ensuring reliability and consistency.

Support for Async Events: WAPI excels at handling asynchronous events, making it ideal for managing background processes and event-driven workflows.

Message Queue Integration: Seamlessly integrate WAPI with message queues, simplifying the creation of distributed systems and asynchronous message processing.

AWS Lambda Functionality: Deploy your code as AWS Lambda functions with ease, providing scalability and flexibility for your applications.

Hybrid HTTP Servers: Create hybrid HTTP servers that seamlessly combine serverless and container-based architectures, allowing deployment in various environments.

Crypto Utilities: WAPI provides utility classes for cryptographic operations, including encryption and decryption using AWS KMS. Securely manage sensitive data with ease.

Email Sending: The Mailer class simplifies sending emails using AWS SES. Send both raw and templated emails with customizable parameters, enhancing communication capabilities.

⚙️ Modules

| File | Summary | | --- | --- | | .eslintrc.cjs | The code defines the linting rules for a TypeScript project. It extends recommended configurations, adds TypeScript-specific rules, and enables Prettier formatting. It also sets rules for imports ordering and disables certain rules. | | index.ts | This code provides modules for handling transactions, managing processes, processing events, routing requests, sending emails, performing cryptographic operations, handling JSON Web Tokens, managing configuration settings, constructing HTTP responses, and providing utility functions and route definitions. | | .eslintignore | The.eslintignore file specifies file and directory patterns to exclude from linting using ESLint. In this case, it excludes the node_modules directory and the dist directory from being checked for linting issues. | | jest.config.ts | This code is a Jest configuration file that sets up the testing environment for a TypeScript project. It includes options for generating code coverage reports in various formats, setting coverage thresholds, and configuring reporters for test results. |

| File | Summary | | --- | --- | | npmpublish.yml | This code is a GitHub workflow that runs when code is pushed to the "main" or "gabe/tweaks" branches. It uses a tool to publish an NPM package, using Node version 16.x. | | prs.yml | This code sets up a GitHub workflow that runs checks on pull requests (PRs) targeting the'master' or'main' branches. It uses a predefined workflow template called'prs-check.yml' and inherits secrets. The specified Node.js version is 16.x. |

| File | Summary | | --- | --- | | Globals.ts | The code in Globals.ts contains global constants and configurations for the application. It includes error messages, error codes, default values for HTTP listeners, and response messages and codes for exceptions. |

| File | Summary | | --- | --- | | JWT.ts | The code in JWT.ts provides functionalities to create and validate JSON Web Tokens (JWTs). It includes methods to generate a JWT given data and options, as well as to validate a JWT and return a response indicating its validity. The class has a constructor that sets the token secret and default expiration time. Overall, the code enables secure token generation and verification. | | Crypto.ts | The Crypto class provides encryption and decryption functionality using AWS KMS. It encrypts data using RSAES_OAEP_SHA_256 encryption algorithm and decrypts data using the same algorithm. The class requires an AWS region and a KMS key ID to perform encryption and decryption operations. |

| File | Summary | | --- | --- | | Logger.ts | The Logger class is used for logging messages with different log levels. It provides functions for logging debug, info, warning, and error messages. The class can be configured with a log level and sensitive filtering keywords. It also has a blacklist of sensitive strings that can be excluded from logs. The logger formats the log messages and logs them using the console object. |

| File | Summary | | --- | --- | | EnvironmentVar.ts | The code defines a class called EnvironmentVar that represents an environment variable. It has methods to resolve the value of the variable based on the environment type (local, plain remote, secure remote). It uses AWS SDK clients to retrieve the values from AWS SSM and Secrets Manager. | | Configuration.ts | The code in the Configuration.ts file defines a Configuration class that allows retrieving values from environment variables or cache. It utilizes a schema to determine the properties to retrieve and their attributes. The class supports both synchronous and asynchronous retrieval of values, and also provides caching functionality. |

| File | Summary | | --- | --- | | Publisher.ts | This code defines a Publisher class that can publish messages to an SNS topic. It establishes a connection to the SNS client and provides a method to publish messages on a specified topic. |

| File | Summary | | --- | --- | | Router.ts | The code is defining a Router class that handles routing logic for a web application. It includes functionalities such as configuring routes, listening on a port, setting a timeout, enabling CORS, and implementing a health check endpoint. The router can be used to handle different types of transactions and execute corresponding handlers. | | RouteResolver.ts | The code implements a RouteResolver class that resolves routes based on provided configurations. It builds a routing system using a Routes class to add and resolve routes. The resolveRoute method takes an HTTP method and path and returns the resolved route, or undefined if not found. The buildRoutes method constructs the routes based on the given configuration. |

| File | Summary | | --- | --- | | ContainerServer.ts | The ContainerServer class extends the Server class and handles serverless events. It utilizes a Proxy object for handling requests and responses. The class has methods for starting and stopping the server, as well as handling process events. The getExport method returns a callable function for exporting data. | | Server.ts | The Server class handles serverless events by executing transactions and resolving routes based on the event. It validates input, parses path parameters, and calls the appropriate route handler. |

| File | Summary | | --- | --- | | HealthHandler.ts | The code in HealthHandler.ts defines a function that handles a request and sends a response with the message'Healthy!'. It takes in a request object and a response object, and returns nothing. | | GenericHandler.ts | This code defines a function that handles HTTP requests by invoking a serverless function and processing the response. It also includes a helper function to translate the serverless response to HTTP and send it back to the client. | | Utils.ts | The code provides two functions for parsing query string parameters from a given URL.-parseMultiValueQueryStringParameters parses multi-value query parameters into an object, allowing multiple values for the same key.-parseQueryStringParameters parses query parameters into an object, without support for multiple values. | | GenericHandlerEvent.ts | The code is a TypeScript class that represents a generic handler event for serverless functions. It builds an APIGatewayProxyEvent object based on an HTTP request and provides methods to invoke the serverless handler function and build the context object for an AWS Lambda function. | | Proxy.ts | The code defines a Proxy class that handles routing and server functionality. It creates an Express application, sets up middleware, starts listeners, and installs routes. It also provides methods to load, unload, and stop the listeners. |

| File | Summary | | --- | --- | | Mailer.ts | The Mailer class is responsible for sending emails using AWS SES. It provides functions to send raw emails and templated emails with customizable parameters. It also includes methods for creating a new SMTP transporter and choosing the appropriate template based on the provided data. |

| File | Summary | | --- | --- | | Utils.ts | The Utils class contains various static methods for common operations. It includes functions to check if the application is running in a hybridless container, validate strings, parse strings into integers, parse JSON strings, validate numbers, and retrieve values from objects using case-insensitive key lookup. | | Response.ts | The code in the Response.ts file defines a class called Response, which represents an API response. It provides methods for manipulating and building the response, including handling errors, setting headers, and streaming the response. It also includes static methods for creating different types of API responses, such as success, error, redirect, and streaming responses. | | Request.ts | The code defines a class called Request that provides utility methods for accessing request information in an API Gateway event. It can retrieve query parameters, headers, path parameters, request body, HTTP method, and other request details. It also allows setting fixed path parameters. This class is designed to facilitate handling and processing of incoming requests in a serverless environment. |

| File | Summary | | --- | --- | | Process.ts | The Process class provides functionality to create and manage processes. It allows executing shell commands in a child process, streaming the output, and capturing the exit code. This class is useful for managing and monitoring external processes or running background tasks. | | ExecutionResult.ts | The ExecutionResult class represents the result of executing a process. It includes information such as the command that was executed, the exit code, and the standard output and error streams. This class is used for capturing and reporting the results of process execution. | | Transaction.ts | The Transaction class is a central part of WAPI. It encapsulates the core concept of transactions, allowing developers to handle complex sequences of events and actions. A transaction represents a unit of work that can include multiple steps, such as database queries, HTTP requests, and more. | | Executor.ts | The Executor class is responsible for executing a series of steps in a transaction. It manages the transaction's state, ensures that steps are executed in the correct order, and handles error recovery. This class plays a key role in orchestrating the execution of transactions. | | Events.ts | The Events class defines a set of event types that can be used within transactions. Events can be triggered, caught, and processed in various ways to implement business logic. This class provides a clear structure for managing events and actions within transactions. |

🚀 Getting Started

To get started with the WAPI project, follow these steps:

🔧 Installation

Install Dependencies: Navigate to the project's root directory and install the required dependencies.

cd your-repo-name
npm install

Set Up Configuration: Configure your environment by setting the necessary environment variables or AWS credentials, as required by the project.

Build the Project: Build the project using TypeScript.

npm run build

🧪 Tests

Run Tests: The project includes a comprehensive set of tests. You can run the tests using:

npm test

Additionally, there are tests for running the project in a local environment:

npm run test-dev

Congratulations! You now have WAPI up and running, and you're ready to start developing your web applications.

If you have any more questions or need further assistance, please don't hesitate to ask.