@creator.co/wapi 1.2.5 → 1.2.6

package/src/Server/lib/ContainerServer.ts

@@ -3,38 +3,30 @@ import Server from './Server'
 import { RouterConfig } from '../Router'
 
 /**
- * ${1:Description placeholder}
- *
- * @export
- * @class ContainerServer
- * @typedef {ContainerServer}
- * @extends {Server}
+ * Represents a server container that extends the Server class and handles serverless events.
  */
 export default class ContainerServer extends Server {
   /**
-   * ${1:Description placeholder}
-   *
-   * @protected
-   * @readonly
+   * The proxy object used for handling requests and responses.
    * @type {Proxy}
+   * @protected
    */
   protected readonly proxy: Proxy
+
   /**
-   * Creates an instance of ContainerServer.
-   *
-   * @constructor
-   * @param {RouterConfig} config
+   * Constructs a new instance of the Router class.
+   * @param {RouterConfig} config - The configuration object for the router.
+   * @returns None
    */
   constructor(config: RouterConfig) {
     super(config)
     this.proxy = new Proxy(config, this.handleServerlessEvent.bind(this))
     this.listenProcessEvents()
   }
+
   /**
-   * ${1:Description placeholder}
-   *
-   * @public
-   * @returns {CallableFunction}
+   * Returns a callable function that can be used to export data.
+   * @returns {CallableFunction} - A callable function that can be used to export data.
    */
   public getExport(): CallableFunction {
     // start server socket
@@ -42,32 +34,28 @@ export default class ContainerServer extends Server {
     // return empty function, we are all done
     return () => {}
   }
-  /* private */
+
   /**
-   * ${1:Description placeholder}
-   *
-   * @public
-   * @async
-   * @returns {*}
+   * Starts the application by loading the proxy.
+   * @returns {Promise<void>} - A promise that resolves when the proxy is loaded.
    */
   public async start() {
     await this.proxy.load()
   }
+
   /**
-   * ${1:Description placeholder}
-   *
-   * @public
-   * @async
-   * @param {?*} [err]
-   * @returns {*}
+   * Stops the execution of the program and unloads the proxy.
+   * @param {any} [err] - Optional error object to pass to the unload method.
+   * @returns {Promise<void>} - A promise that resolves once the proxy is unloaded.
    */
   public async stop(err?: any) {
     await this.proxy.unload(err)
   }
+
   /**
-   * ${1:Description placeholder}
-   *
+   * Listens for process events and handles them accordingly.
    * @private
+   * @returns None
    */
   private listenProcessEvents() {
     // start process listeners

package/src/Server/lib/Server.ts

@@ -1,5 +1,5 @@
 import { APIGatewayProxyEvent, Context } from 'aws-lambda'
-import * as pathToRegexp from 'path-to-regexp'
+import { pathToRegexp } from 'path-to-regexp'
 
 import Request from '../../API/Request'
 import Response from '../../API/Response'
@@ -9,35 +9,26 @@ import { RouterConfig } from '../Router'
 import RouteResolver from '../RouteResolver'
 
 /**
- * ${1:Description placeholder}
- *
- * @export
- * @class Server
- * @typedef {Server}
+ * Represents a server that handles serverless events and routes them to appropriate handlers.
  */
 export default class Server {
   /**
-   * ${1:Description placeholder}
-   *
-   * @protected
+   * The configuration object for the router.
    * @readonly
    * @type {RouterConfig}
    */
   protected readonly config: RouterConfig
   /**
-   * ${1:Description placeholder}
-   *
-   * @protected
-   * @readonly
+   * A protected property that holds a RouteResolver object.
+   * The RouteResolver is responsible for resolving routes and returning the appropriate response.
    * @type {RouteResolver}
    */
   protected readonly routeResolver: RouteResolver
 
   /**
-   * Creates an instance of Server.
-   *
-   * @constructor
-   * @param {RouterConfig} config
+   * Constructs a new instance of the Router class.
+   * @param {RouterConfig} config - The configuration object for the router.
+   * @returns None
    */
   constructor(config: RouterConfig) {
     this.config = config
@@ -45,23 +36,18 @@ export default class Server {
   }
 
   /**
-   * ${1:Description placeholder}
-   *
-   * @public
-   * @returns {CallableFunction}
+   * Returns a callable function that is bound to the `handleServerlessEvent` method of the current object.
+   * @returns {CallableFunction} - A callable function that is bound to the `handleServerlessEvent` method.
    */
   public getExport(): CallableFunction {
     return this.handleServerlessEvent.bind(this)
   }
 
   /**
-   * ${1:Description placeholder}
-   *
-   * @public
-   * @async
-   * @param {APIGatewayProxyEvent} event
-   * @param {Context} context
-   * @returns {*}
+   * Handles a serverless event by executing a transaction and resolving the route based on the event.
+   * @param {APIGatewayProxyEvent} event - The serverless event object.
+   * @param {Context} context - The serverless context object.
+   * @returns None
    */
   public async handleServerlessEvent(event: APIGatewayProxyEvent, context: Context) {
     // init transaction
@@ -86,16 +72,15 @@ export default class Server {
   }
 
   /**
-   * ${1:Description placeholder}
-   *
-   * @private
-   * @param {Request<any>} req
-   * @param {string} routePath
+   * Parses the path parameters from the request URL based on the given route path.
+   * @param {Request<any>} req - The request object.
+   * @param {string} routePath - The route path pattern to match against.
+   * @returns None
    */
   private parsePathParams(req: Request<any>, routePath: string) {
     const path = req.getPath()
     const keys = []
     const result = pathToRegexp(routePath, keys).exec(path)
-    req.setFixedPathParams(keys, result)
+    if (result) req.setFixedPathParams(keys, result)
   }
 }

package/src/Server/lib/container/GenericHandler.ts

@@ -5,7 +5,18 @@ import Utils from '../../../API/Utils'
 import Globals from '../../../Globals'
 import Server from '../Server'
 
+/**
+ * Creates an async function that handles serverless events and sends a response.
+ * @param {Server['handleServerlessEvent']} serverlessHandler - The serverless handler function.
+ * @returns {Function} - An async function that handles the request and sends a response.
+ */
 export default (serverlessHandler: Server['handleServerlessEvent']) => {
+  /**
+   * Handles an HTTP request by invoking a serverless function and processing the response.
+   * @param {Request} request - The HTTP request object.
+   * @param {Response} res - The HTTP response object.
+   * @returns None
+   */
   return async (request: Request, res: Response) => {
     const startTime = Date.now()
     try {
@@ -27,10 +38,13 @@ export default (serverlessHandler: Server['handleServerlessEvent']) => {
     console.debug(`[Proxy] - Request took ${Date.now() - startTime}ms`)
   }
 }
+
 /**
- * ${1:Description placeholder}
- *
- **/
+ * Processes the response received from a serverless function invocation and sends the appropriate response back to the client.
+ * @param {GenericHandlerEventResponse} invokation - The response object received from the serverless function invocation.
+ * @param {Response} res - The response object to send back to the client.
+ * @returns The response object to send back to the client.
+ */
 const processServerlessResponse = (invokation: GenericHandlerEventResponse, res: Response) => {
   // translate answer to http layer
   if (invokation && invokation.err) {

package/src/Server/lib/container/GenericHandlerEvent.ts

@@ -5,54 +5,45 @@ import { Request } from 'express'
 import { parseMultiValueQueryStringParameters, parseQueryStringParameters } from './Utils'
 import Globals from '../../../Globals'
 import Server from '../Server'
-//
+
 /**
- * ${1:Description placeholder}
- *
- * @export
- * @typedef {GenericHandlerEventResponse}
+ * Represents the response object returned by a generic event handler.
+ * @typedef {Object} GenericHandlerEventResponse
+ * @property {Error | string} [err] - An optional error object or error message.
+ * @property {*} [data] - An optional data object.
  */
 export type GenericHandlerEventResponse = { err?: Error | string; data?: any }
-//
+
 /**
- * ${1:Description placeholder}
- *
- * @export
- * @class GenericHandlerEvent
- * @typedef {GenericHandlerEvent}
+ * Represents a generic handler event for serverless functions.
  */
 export default class GenericHandlerEvent {
   /**
-   * ${1:Description placeholder}
-   *
-   * @public
-   * @type {Request}
+   * Represents an HTTP request.
+   * @property {Request} request - The HTTP request object.
    */
   public request: Request
   /**
-   * ${1:Description placeholder}
-   *
-   * @public
-   * @type {Server["handleServerlessEvent"]}
+   * The handler function for serverless events in a server.
+   * @param {Server['handleServerlessEvent']} serverlessHandler - The function that handles serverless events.
+   * @returns None
    */
   public serverlessHandler: Server['handleServerlessEvent']
+
   /**
-   * Creates an instance of GenericHandlerEvent.
-   *
-   * @constructor
-   * @param {Request} request
-   * @param {Server["handleServerlessEvent"]} serverlessHandler
+   * Constructs a new instance of the class.
+   * @param {Request} request - The request object.
+   * @param {Server['handleServerlessEvent']} serverlessHandler - The serverless handler function.
+   * @returns None
    */
   constructor(request: Request, serverlessHandler: Server['handleServerlessEvent']) {
     this.request = request
     this.serverlessHandler = serverlessHandler
   }
+
   /**
-   * ${1:Description placeholder}
-   *
-   * @public
-   * @async
-   * @returns {Promise<GenericHandlerEventResponse>}
+   * Invokes the handler function asynchronously and returns a promise that resolves to a GenericHandlerEventResponse.
+   * @returns {Promise<GenericHandlerEventResponse>} A promise that resolves to a GenericHandlerEventResponse.
    */
   public async invoke(): Promise<GenericHandlerEventResponse> {
     // eslint-disable-next-line no-async-promise-executor
@@ -70,12 +61,10 @@ export default class GenericHandlerEvent {
       }
     })
   }
-  /* private */
+
   /**
-   * ${1:Description placeholder}
-   *
-   * @private
-   * @returns {APIGatewayProxyEvent}
+   * Builds and returns an APIGatewayProxyEvent object based on the current request.
+   * @returns {APIGatewayProxyEvent} - The constructed APIGatewayProxyEvent object.
    */
   private buildEvent(): APIGatewayProxyEvent {
     return {
@@ -91,13 +80,13 @@ export default class GenericHandlerEvent {
         ? parseQueryStringParameters(this.request.query)
         : null,
       requestContext: {
-        accountId: process.env.AWS_ACCOUNT_ID || null,
-        apiId: null,
+        accountId: process.env.AWS_ACCOUNT_ID || 'undefined',
+        apiId: '',
         authorizer: null,
-        domainName: null,
-        domainPrefix: null,
+        domainName: undefined,
+        domainPrefix: undefined,
         extendedRequestId: cuid(),
-        httpMethod: this.request.method ? this.request.method.toUpperCase() : null,
+        httpMethod: this.request.method ? this.request.method.toUpperCase() : '',
         identity: {
           accessKey: null,
           accountId: process.env.AWS_ACCOUNT_ID || null,
@@ -111,9 +100,11 @@ export default class GenericHandlerEvent {
           cognitoIdentityPoolId: null,
           principalOrgId: null,
           sourceIp:
-            <string>this.request.headers?.['x-forwarded-for'] || this.request.socket?.remoteAddress,
+            <string>this.request.headers?.['x-forwarded-for'] ||
+            this.request.socket?.remoteAddress ||
+            '',
           user: null,
-          userAgent: this.request.headers?.['user-agent'],
+          userAgent: this.request.headers?.['user-agent'] || null,
           userArn: null,
         },
         path: this.request.path,
@@ -121,21 +112,20 @@ export default class GenericHandlerEvent {
         requestId: `${cuid()}-${cuid()}`,
         requestTime: new Date().toISOString(),
         requestTimeEpoch: Date.now(),
-        resourceId: null,
+        resourceId: '',
         resourcePath: Globals.Listener_HTTP_ProxyRoute,
-        stage: process.env.STAGE,
+        stage: process.env.STAGE || '',
       },
       resource: Globals.Listener_HTTP_ProxyRoute,
       stageVariables: null,
     }
   }
+
   /**
-   * ${1:Description placeholder}
-   *
-   * @private
-   * @param {APIGatewayProxyEvent} event
-   * @param {(err?: Error | string, data?: any) => void} callback
-   * @returns {Context}
+   * Builds and returns a context object for an AWS Lambda function.
+   * @param {APIGatewayProxyEvent} event - The event object passed to the Lambda function.
+   * @param {(err?: Error | string, data?: any) => void} callback - The callback function to be called when the Lambda function completes.
+   * @returns {Context} - The context object for the Lambda function.
    */
   private buildContext(
     event: APIGatewayProxyEvent,
@@ -149,13 +139,13 @@ export default class GenericHandlerEvent {
       },
       done: (err, data) => callback(err, data),
       fail: err => callback(err),
-      succeed: res => callback(null, res),
-      functionName: null,
+      succeed: res => callback(undefined, res),
+      functionName: 'container-function',
       functionVersion: 'LATEST',
-      invokedFunctionArn: null,
+      invokedFunctionArn: 'none',
       memoryLimitInMB: '-1',
-      logGroupName: null,
-      logStreamName: null,
+      logGroupName: 'undefined',
+      logStreamName: 'undefined',
     }
   }
 }

package/src/Server/lib/container/HealthHandler.ts

@@ -1,5 +1,11 @@
 import { Request, Response } from 'express'
 
+/**
+ * Handles a request and sends a response with the message 'Healthy!'.
+ * @param {Request} _request - The request object.
+ * @param {Response} res - The response object.
+ * @returns None
+ */
 export default async (_request: Request, res: Response) => {
   res.send('Healthy!')
 }

package/src/Server/lib/container/Proxy.ts

@@ -12,57 +12,41 @@ import Globals from '../../../Globals'
 import { RouterConfig } from '../../Router'
 
 /**
- * ${1:Description placeholder}
- *
- * @export
- * @class Proxy
- * @typedef {Proxy}
+ * Represents a Proxy class that handles routing and server functionality.
  */
 export default class Proxy {
   /**
-   * ${1:Description placeholder}
-   *
-   * @private
-   * @type {boolean}
+   * A boolean flag indicating whether the process is currently stopping or not.
    */
   private stopping: boolean
   /**
-   * ${1:Description placeholder}
-   *
-   * @private
-   * @readonly
-   * @type {RouterConfig}
+   * The configuration object for the router.
    */
   private readonly config: RouterConfig
   /**
-   * ${1:Description placeholder}
-   *
-   * @private
+   * The Express application instance for the server.
    * @readonly
    * @type {express.Express}
    */
   private readonly app: express.Express
   /**
-   * ${1:Description placeholder}
-   *
-   * @private
-   * @readonly
-   * @type {Server["handleServerlessEvent"]}
+   * The handler function for serverless events in the Server class.
+   * @param {ServerlessEvent} event - The serverless event object.
+   * @returns None
    */
   private readonly serverlessHandler: Server['handleServerlessEvent']
   /**
-   * ${1:Description placeholder}
-   *
+   * Represents a listener for an HTTP server.
    * @private
    * @type {HTTPServer}
    */
   private listener: HTTPServer
+
   /**
-   * Creates an instance of Proxy.
-   *
-   * @constructor
-   * @param {RouterConfig} config
-   * @param {Server["handleServerlessEvent"]} serverlessHandler
+   * Constructs a new instance of the Router class.
+   * @param {RouterConfig} config - The configuration object for the router.
+   * @param {Server['handleServerlessEvent']} serverlessHandler - The handler function for serverless events.
+   * @returns None
    */
   constructor(config: RouterConfig, serverlessHandler: Server['handleServerlessEvent']) {
     this.stopping = false
@@ -93,42 +77,41 @@ export default class Proxy {
     // this.listener.listener.keepAliveTimeout = 120e3
     // this.listener.listener.headersTimeout = 120e3
   }
+
   /**
-   * ${1:Description placeholder}
-   *
-   * @async
-   * @returns {*}
+   * Loads the necessary components and initializes the application.
+   * @returns None
    */
   async load() {
-    await this.startListeners()
     this.installRoutes()
+    await this.startListeners()
   }
+
   /**
-   * ${1:Description placeholder}
-   *
-   * @async
-   * @param {?*} [err]
-   * @returns {*}
+   * Unloads the current module, stopping any active listeners.
+   * @param {any} [err] - Optional error object to pass to the stopListeners method.
+   * @returns {Promise<void>} - A promise that resolves once the listeners have been stopped.
    */
   async unload(err?: any) {
     await this.stopListeners(err)
   }
-  /* lifecycle */
+
   /**
-   * ${1:Description placeholder}
-   *
-   * @private
-   * @async
-   * @returns {Promise<void>}
+   * Starts the listeners for the proxy server.
+   * @returns {Promise<void>} A promise that resolves when the listeners have started.
    */
   private async startListeners(): Promise<void> {
-    return new Promise(resolve => {
+    // eslint-disable-next-line no-async-promise-executor
+    return new Promise(async resolve => {
       const port = this.config.port || Globals.Listener_HTTP_DefaultPort
       console.log(`[Proxy] - [STARTING] - v.${appVersion} - :${port}`)
       // Create Server
       this.listener = createServer(this.app)
       // Set defaults
       this.listener.setTimeout(this.config.timeout || Globals.Listener_HTTP_DefaultTimeout)
+      // Call hook if available
+      if (this.config.containerSetupHook)
+        await this.config.containerSetupHook(this.listener, this.app)
       // Start Server
       this.listener.listen(port, () => {
         console.log(`[Proxy] - [STARTED]`)
@@ -136,13 +119,11 @@ export default class Proxy {
       })
     })
   }
+
   /**
-   * ${1:Description placeholder}
-   *
-   * @private
-   * @async
-   * @param {?*} [err]
-   * @returns {unknown}
+   * Stops the listeners and exits the process.
+   * @param {any} [err] - Optional error object.
+   * @returns {Promise<void>} - A promise that resolves when the listeners are stopped and the process is exited.
    */
   private async stopListeners(err?: any) {
     if (this.stopping) return
@@ -153,16 +134,15 @@ export default class Proxy {
         const err2 = err || _err
         if (err2) console.log('[Proxy] - exit output:', err2)
         console.log('[Proxy] - [STOPPED]')
-        process.exit(err || _err ? 1 : 0)
+        process.exit(err2 ? 1 : 0)
         resolve(null)
       })
     })
   }
-  /* routing */
+
   /**
-   * ${1:Description placeholder}
-   *
-   * @private
+   * Installs the routes for the proxy server.
+   * @returns None
    */
   private installRoutes() {
     //Health check route -- This is a bypass route to only check if

package/src/Server/lib/container/Utils.ts

@@ -1,9 +1,7 @@
 /**
- * ${1:Description placeholder}
- *
- * @export
- * @param {string} url
- * @returns {*}
+ * Parses the multi-value query string parameters from the given URL.
+ * @param {string} url - The URL containing the query string parameters.
+ * @returns {Object} - An object representing the parsed query string parameters.
  */
 export function parseMultiValueQueryStringParameters(url: string) {
   // dummy placeholder url for the WHATWG URL constructor
@@ -20,12 +18,11 @@ export function parseMultiValueQueryStringParameters(url: string) {
   }
   return Object.fromEntries(map)
 }
+
 /**
- * ${1:Description placeholder}
- *
- * @export
- * @param {*} url
- * @returns {*}
+ * Parses the query string parameters from a given URL.
+ * @param {string} url - The URL to parse the query string parameters from.
+ * @returns {object | null} - An object containing the parsed query string parameters, or null if there are no parameters.
  */
 export function parseQueryStringParameters(url) {
   // dummy placeholder url for the WHATWG URL constructor

package/src/Validation/Validator.ts

@@ -4,27 +4,24 @@ import Response, { ResponseErrorType } from '../API/Response'
 import Globals from '../Globals'
 
 /**
- * Description placeholder
- *
- * @export
- * @class Validator
- * @typedef {Validator}
+ * Validates the given data against the provided schema.
+ * @param {any} data - The data to be validated.
+ * @param {z.ZodObject<any>} schema - The schema to validate against.
+ * @returns {boolean | Response<ResponseErrorType>} - Returns true if the data is valid, otherwise returns a response object with an error message.
  */
 export default class Validator {
   /**
-   * Description placeholder
-   *
-   * @public
-   * @static
-   * @param {*} data
-   * @param {z.ZodObject<any>} schema
-   * @returns {(boolean | Response<ResponseErrorType>)}
+   * Validates the given data against the provided schema.
+   * @param {any} data - The data to be validated.
+   * @param {z.ZodObject<any> | z.ZodUnion<any>} schema - The schema to validate against.
+   * @returns {boolean | Response<ResponseErrorType>} - Returns either true if the data is valid or a Response object with an error message if validation fails.
    */
   public static validateSchema(
     data: any,
-    schema: z.ZodObject<any>
+    schema: z.ZodObject<any> | z.ZodUnion<any>
   ): boolean | Response<ResponseErrorType> {
     let error, validatedInput
+
     // Validate body against known zod schema
     try {
       validatedInput = schema.parse(data) as typeof schema
@@ -32,6 +29,7 @@ export default class Validator {
       if (err instanceof z.ZodError) error = JSON.parse(err.message)
       else error = 'Unknown validation error!' //unhandled case, hard to test
     }
+
     // Error validation
     if (!validatedInput || error) {
       return Response.BadRequestResponse(