@creator.co/wapi 1.2.4 → 1.2.6

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
@@ -150,18 +131,18 @@ export default class Proxy {
     console.debug('[Proxy] - [STOPPING]')
     return new Promise(resolve => {
       this.listener.close(_err => {
-        if (err || _err) console.log('[Proxy] - exit output:', err || _err)
+        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(

package/tests/API/Response.test.ts

@@ -1,6 +1,5 @@
-import { expect as j_expect } from '@jest/globals'
 import { APIGatewayEvent, Context } from 'aws-lambda'
-import { expect } from 'chai'
+import { expect as c_expect } from 'chai'
 
 import Response from '../../src/API/Response'
 import Transaction from '../../src/BaseEvent/Transaction'
@@ -11,11 +10,11 @@ async function testResponse(r: Response<any>, body: any, optCode?: number, optHe
   const t = observableTransaction()
   const context = t['context']
   const buildR = await r.build(context, t, false)
-  expect(buildR).to.be.undefined
-  j_expect(t.responseProxy).toBeCalledTimes(1)
-  j_expect(context.fail).not.toBeCalled()
-  j_expect(context.done).not.toBeCalled()
-  j_expect(context.succeed).toHaveBeenCalledWith({
+  c_expect(buildR).to.be.undefined
+  expect(t.responseProxy).toBeCalledTimes(1)
+  expect(context.fail).not.toBeCalled()
+  expect(context.done).not.toBeCalled()
+  expect(context.succeed).toHaveBeenCalledWith({
     statusCode: optCode || 400,
     headers: {
       ...defaultHeaders,
@@ -35,28 +34,28 @@ async function testResponse(r: Response<any>, body: any, optCode?: number, optHe
 describe('Response basics', () => {
   test('Null body', () => {
     const r = new Response<null>(200, null)
-    expect(r.getCode()).to.be.equals(200)
-    expect(r.getBody()).to.be.null
+    c_expect(r.getCode()).to.be.equals(200)
+    c_expect(r.getBody()).to.be.null
   })
 
   test('String body', () => {
     const r = new Response<string>(200, 'abc')
-    expect(r.getCode()).to.be.equals(200)
-    expect(r.getBody()).to.be.equals('abc')
+    c_expect(r.getCode()).to.be.equals(200)
+    c_expect(r.getBody()).to.be.equals('abc')
   })
 
   test('Generic body', () => {
     const r = new Response<any>(200, { name: 'abc' })
     r.appendIntoBody('name2', '123')
-    expect(r.getCode()).to.be.equals(200)
-    expect(r.getBody().name).to.be.equals('abc')
-    expect(r.getBody().name2).to.be.equals('123')
+    c_expect(r.getCode()).to.be.equals(200)
+    c_expect(r.getBody().name).to.be.equals('abc')
+    c_expect(r.getBody().name2).to.be.equals('123')
   })
 
   test('Append/validate header', () => {
     const r = new Response<any>(200, {})
     r.appendHeader('name2', '123')
-    expect(r['_headers']['name2']).to.be.equals('123')
+    c_expect(r['headers']['name2']).to.be.equals('123')
   })
 })
 
@@ -76,10 +75,10 @@ describe('Response build', () => {
     )
     const context = t['context']
     const buildR = await r.build(context, t, false)
-    expect(buildR).to.be.undefined
-    j_expect(context.fail).not.toBeCalled()
-    j_expect(context.done).not.toBeCalled()
-    j_expect(context.succeed).toHaveBeenCalledWith({
+    c_expect(buildR).to.be.undefined
+    expect(context.fail).not.toBeCalled()
+    expect(context.done).not.toBeCalled()
+    expect(context.succeed).toHaveBeenCalledWith({
       statusCode: 200,
       headers: {
         ...defaultHeaders,
@@ -98,10 +97,10 @@ describe('Response build', () => {
     const t = observableTransaction()
     const context = t['context']
     const buildR = await r.build(context, t, true)
-    expect(buildR).to.be.undefined
-    j_expect(context.fail).not.toBeCalled()
-    j_expect(context.done).not.toBeCalled()
-    j_expect(context.succeed).not.toBeCalled()
+    c_expect(buildR).to.be.undefined
+    expect(context.fail).not.toBeCalled()
+    expect(context.done).not.toBeCalled()
+    expect(context.succeed).not.toBeCalled()
   })
 
   test('Succeeds to transaction context as RAW', async () => {
@@ -112,10 +111,10 @@ describe('Response build', () => {
     const t = observableTransaction()
     const context = t['context']
     const buildR = await r.build(context, t, false)
-    expect(buildR).to.be.undefined
-    j_expect(context.fail).not.toBeCalled()
-    j_expect(context.done).not.toBeCalled()
-    j_expect(context.succeed).toHaveBeenCalledWith({
+    c_expect(buildR).to.be.undefined
+    expect(context.fail).not.toBeCalled()
+    expect(context.done).not.toBeCalled()
+    expect(context.succeed).toHaveBeenCalledWith({
       ...b,
       transactionID: 'unknown',
     })
@@ -130,11 +129,11 @@ describe('Response build', () => {
     const context = t['context']
     const buildR = await r.build(context, t, false)
     await r.build(context, t, false) //pipe twice, should not affect
-    expect(buildR).to.be.undefined
-    j_expect(context.fail).not.toBeCalled()
-    j_expect(context.done).not.toBeCalled()
-    j_expect(context.succeed).toHaveBeenCalledTimes(1)
-    j_expect(context.succeed).toHaveBeenCalledWith({
+    c_expect(buildR).to.be.undefined
+    expect(context.fail).not.toBeCalled()
+    expect(context.done).not.toBeCalled()
+    expect(context.succeed).toHaveBeenCalledTimes(1)
+    expect(context.succeed).toHaveBeenCalledWith({
       statusCode: 200,
       headers: {
         ...defaultHeaders,
@@ -153,10 +152,10 @@ describe('Response build', () => {
     const t = observableTransaction()
     const context = t['context']
     const buildR = await r.build(context, t, false)
-    expect(buildR).to.be.undefined
-    j_expect(context.done).not.toBeCalled()
-    j_expect(context.succeed).not.toBeCalled()
-    j_expect(context.fail).toHaveBeenCalledTimes(1)
+    c_expect(buildR).to.be.undefined
+    expect(context.done).not.toBeCalled()
+    expect(context.succeed).not.toBeCalled()
+    expect(context.fail).toHaveBeenCalledTimes(1)
   })
 
   test('Failure exception to transaction context as RAW', async () => {
@@ -174,11 +173,11 @@ describe('Response build', () => {
     } catch (e) {
       exception = e
     }
-    expect(buildR).to.be.null
-    expect(exception).to.not.be.null
-    j_expect(context.done).not.toBeCalled()
-    j_expect(context.succeed).not.toBeCalled()
-    j_expect(context.fail).not.toBeCalled()
+    c_expect(buildR).to.be.null
+    c_expect(exception).to.not.be.null
+    expect(context.done).not.toBeCalled()
+    expect(context.succeed).not.toBeCalled()
+    expect(context.fail).not.toBeCalled()
   })
 
   test('Failure exception to transaction context as RAW and null body', async () => {
@@ -196,11 +195,11 @@ describe('Response build', () => {
     } catch (e) {
       exception = e
     }
-    expect(buildR).to.be.null
-    expect(exception).to.not.be.null
-    j_expect(context.done).not.toBeCalled()
-    j_expect(context.succeed).not.toBeCalled()
-    j_expect(context.fail).not.toBeCalled()
+    c_expect(buildR).to.be.null
+    c_expect(exception).to.not.be.null
+    expect(context.done).not.toBeCalled()
+    expect(context.succeed).not.toBeCalled()
+    expect(context.fail).not.toBeCalled()
   })
 
   test('Failure exception to transaction context as RAW and custom ero', async () => {
@@ -218,11 +217,11 @@ describe('Response build', () => {
     } catch (e) {
       exception = e
     }
-    expect(buildR).to.be.null
-    expect(exception).to.not.be.null
-    j_expect(context.done).not.toBeCalled()
-    j_expect(context.succeed).not.toBeCalled()
-    j_expect(context.fail).not.toBeCalled()
+    c_expect(buildR).to.be.null
+    c_expect(exception).to.not.be.null
+    expect(context.done).not.toBeCalled()
+    expect(context.succeed).not.toBeCalled()
+    expect(context.fail).not.toBeCalled()
   })
 })
 
@@ -346,11 +345,11 @@ describe('Response shortcuts', () => {
     const context = t['context']
     const buildR = await r.build(context, t, false)
     await r.build(context, t, false) //pipe twice, should not affect
-    expect(buildR).to.be.undefined
-    j_expect(context.fail).not.toBeCalled()
-    j_expect(context.done).not.toBeCalled()
-    j_expect(context.succeed).toHaveBeenCalledTimes(1)
-    j_expect(context.succeed).toHaveBeenCalledWith({
+    c_expect(buildR).to.be.undefined
+    expect(context.fail).not.toBeCalled()
+    expect(context.done).not.toBeCalled()
+    expect(context.succeed).toHaveBeenCalledTimes(1)
+    expect(context.succeed).toHaveBeenCalledWith({
       statusCode: 200,
       headers: {
         ...defaultHeaders,