@creator.co/wapi 1.2.4 → 1.2.6

package/src/BaseEvent/EventProcessor.ts

@@ -4,68 +4,48 @@ import Transaction, { TransactionConfig } from './Transaction'
 import Response, { ResponseErrorType } from '../API/Response'
 import Globals from '../Globals'
 
-// Handler
 /**
- * ${1:Description placeholder}
- *
- * @export
- * @typedef {EventProcessorExecution}
- * @template ResponseInnerType
+ * Type definition for an event processor execution function.
+ * @param {Transaction<null, ResponseInnerType | ResponseErrorType, SQSBatchResponse>} transaction - The transaction object.
+ * @param {string | object} recordContent - The content of the record being processed.
+ * @returns {Promise<Response<ResponseInnerType | ResponseErrorType> | SQSBatchResponse>} - A promise that resolves to the response or batch response.
  */
 export type EventProcessorExecution<ResponseInnerType> = (
-  transaction: Transaction<null, ResponseInnerType | ResponseErrorType, SQSBatchResponse>,
+  transaction: Transaction<null, ResponseInnerType | ResponseErrorType, SQSBatchResponse | null>,
   recordContent: string | object
-) => Promise<Response<ResponseInnerType | ResponseErrorType> | SQSBatchResponse>
+) => Promise<Response<ResponseInnerType | ResponseErrorType> | SQSBatchResponse | null>
 
 /**
- * ${1:Description placeholder}
- *
- * @export
- * @class EventProcessor
- * @typedef {EventProcessor}
- * @template ResponseInnerType
+ * EventProcessor class that processes events from an SQS queue.
+ * @template ResponseInnerType - The type of the inner response object.
  */
 export default class EventProcessor<ResponseInnerType> {
   /**
-   * ${1:Description placeholder}
-   *
-   * @private
+   * A boolean flag indicating whether failures are allowed or not.
    * @readonly
-   * @type {boolean}
    */
-  private readonly _allowFailure: boolean
+  private readonly allowFailure: boolean
   /**
-   * ${1:Description placeholder}
-   *
-   * @private
-   * @readonly
-   * @type {TransactionConfig}
+   * The configuration object for the API transaction.
    */
-  private readonly _apiConfig: TransactionConfig
+  private readonly config: TransactionConfig
   /**
-   * ${1:Description placeholder}
-   *
-   * @private
-   * @readonly
+   * The private readonly context property of the class.
    * @type {Context}
    */
-  private readonly _context: Context
+  private readonly context: Context
   /**
-   * ${1:Description placeholder}
-   *
-   * @private
-   * @readonly
-   * @type {SQSEvent}
+   * The SQS event object that triggered the Lambda function.
    */
-  private readonly _event: SQSEvent
+  private readonly event: SQSEvent
+
   /**
-   * Creates an instance of EventProcessor.
-   *
-   * @constructor
-   * @param {SQSEvent} event
-   * @param {Context} context
-   * @param {?TransactionConfig} [config]
-   * @param {?boolean} [allowFailure]
+   * Constructs a new instance of the class.
+   * @param {SQSEvent} event - The event object representing the incoming SQS message.
+   * @param {Context} context - The context object representing the AWS Lambda execution context.
+   * @param {TransactionConfig} [config] - Optional configuration object for the transaction.
+   * @param {boolean} [allowFailure] - Optional flag indicating whether to allow failure for the transaction.
+   * @returns None
    */
   constructor(
     event: SQSEvent,
@@ -73,26 +53,26 @@ export default class EventProcessor<ResponseInnerType> {
     config?: TransactionConfig,
     allowFailure?: boolean
   ) {
-    this._event = event
-    this._context = context
-    this._apiConfig = config || {}
-    this._allowFailure = allowFailure
+    this.event = event
+    this.context = context
+    this.config = config || {}
+    this.allowFailure = !!allowFailure
   }
+
   /**
-   * ${1:Description placeholder}
-   *
-   * @async
-   * @param {EventProcessorExecution<ResponseInnerType>} execution
-   * @param {?boolean} [doNotDecodeMessage]
-   * @returns {(Promise<Response<ResponseErrorType> | null | SQSBatchResponse>)}
+   * Processes an event using the provided execution object and returns a response.
+   * @param {EventProcessorExecution<ResponseInnerType>} execution - The execution object containing the event to process.
+   * @param {boolean} [doNotDecodeMessage] - Optional flag indicating whether to decode the message.
+   * @returns {Promise<Response<ResponseErrorType> | null | SQSBatchResponse>} - A promise that resolves to the response object, or null if no response is available.
+   * @throws {Error} - Throws an error if the response code is not within the range of 200 to 299 and failure is not allowed.
    */
   async processEvent(
     execution: EventProcessorExecution<ResponseInnerType>,
     doNotDecodeMessage?: boolean
-  ): Promise<Response<ResponseErrorType> | null | SQSBatchResponse> {
-    const resp = await this._processRawEvent(execution, !!doNotDecodeMessage)
+  ): Promise<Response<ResponseErrorType | null> | null | SQSBatchResponse> {
+    const resp = await this.processRawEvent(execution, !!doNotDecodeMessage)
     if (
-      !this._allowFailure &&
+      !this.allowFailure &&
       resp &&
       resp instanceof Response &&
       !(resp.getCode() >= 200 && resp.getCode() < 300)
@@ -101,31 +81,26 @@ export default class EventProcessor<ResponseInnerType> {
     else if (resp) return resp
     return null
   }
+
   /**
-   * ${1:Description placeholder}
-   *
-   * @async
-   * @param {EventProcessorExecution<ResponseInnerType>} execution
-   * @param {boolean} doNotDecodeMessage
-   * @returns {(Promise<Response<ResponseErrorType> | null | SQSBatchResponse>)}
+   * Processes a raw event by executing the provided execution function and handling any errors or failures.
+   * @param {EventProcessorExecution<ResponseInnerType>} execution - The execution function to process the event.
+   * @param {boolean} doNotDecodeMessage - Flag indicating whether to decode the message or not.
+   * @returns {Promise<Response<ResponseErrorType> | null | SQSBatchResponse>} - A promise that resolves to a response object, null, or a SQS batch response.
    */
-  async _processRawEvent(
+  private async processRawEvent(
     execution: EventProcessorExecution<ResponseInnerType>,
     doNotDecodeMessage: boolean
-  ): Promise<Response<ResponseErrorType> | null | SQSBatchResponse> {
-    if (this._event.Records && this._event.Records.length > 0) {
+  ): Promise<Response<ResponseErrorType | any> | null | SQSBatchResponse> {
+    if (this.event.Records && this.event.Records.length > 0) {
       //safe check for empty events?
       //init transaction for all records
-      return await new Transaction<null, ResponseErrorType, SQSBatchResponse>(
-        this._event,
-        this._context,
-        {
-          ...this._apiConfig,
-          syncReturn: true,
-        }
-      ).execute(async transaction => {
+      return await new Transaction<null, any, SQSBatchResponse | null>(this.event, this.context, {
+        ...this.config,
+        syncReturn: true,
+      }).execute(async transaction => {
         //Map records with decoded message when required
-        const decodedRecords: string[] | object[] = this._event.Records.map(eventRecord =>
+        const decodedRecords: string[] | object[] = this.event.Records.map(eventRecord =>
           doNotDecodeMessage ? eventRecord.body : JSON.parse(eventRecord.body)
         )
 
@@ -133,7 +108,7 @@ export default class EventProcessor<ResponseInnerType> {
         const failureIDs: Array<string> = []
         for (const eventRecordIdx in decodedRecords) {
           const eventRecord = decodedRecords[eventRecordIdx]
-          const message = this._event.Records[eventRecordIdx]
+          const message = this.event.Records[eventRecordIdx]
           //Call execution
           const resp = await execution(transaction, eventRecord)
           //check for failure
@@ -142,12 +117,12 @@ export default class EventProcessor<ResponseInnerType> {
             (resp instanceof Response && !(resp?.getCode() >= 200 && resp?.getCode() < 300))
           ) {
             //response with failures or fail hard at first
-            if (this._allowFailure) failureIDs.push(message.messageId)
+            if (this.allowFailure) failureIDs.push(message.messageId)
             else return resp
           }
         }
         //not errored and loop ended - succeeded (might have failures)
-        if (this._allowFailure)
+        if (this.allowFailure)
           return {
             batchItemFailures: failureIDs.map(id => ({ itemIdentifier: id })),
           }

package/src/BaseEvent/Process.ts

@@ -2,93 +2,68 @@ import { TransactionConfig } from './Transaction'
 import Logger from '../Logger/Logger'
 import Publisher from '../Publisher/Publisher'
 
-// Config
 /**
- * ${1:Description placeholder}
- *
- * @export
- * @typedef {ProcessConfig}
+ * A type that represents a modified version of the TransactionConfig type, excluding the 'throwOnErrors' and 'syncReturn' properties.
  */
 export type ProcessConfig = Omit<TransactionConfig, 'throwOnErrors' | 'syncReturn'>
 
 /**
- * ${1:Description placeholder}
- *
- * @export
- * @class Process
- * @typedef {Process}
+ * Represents a long-running process that executes a given function at a specified interval.
  */
 export default class Process {
   /**
-   * ${1:Description placeholder}
-   *
-   * @private
+   * Private member variable representing the interval value.
    * @type {number}
+   * @private
    */
-  private _interval: number
-  //
+  private interval: number
   /**
-   * ${1:Description placeholder}
-   *
-   * @public
+   * A logger object used for logging messages, errors, and other information.
    * @readonly
-   * @type {Logger}
    */
   public readonly logger: Logger
   /**
-   * ${1:Description placeholder}
-   *
-   * @public
-   * @readonly
-   * @type {Publisher}
+   * The publisher of the content.
    */
   public readonly publisher: Publisher
   /**
-   * ${1:Description placeholder}
-   *
-   * @public
-   * @type {NodeJS.Timeout}
+   * A reference to the NodeJS.Timeout object representing the interval timer.
    */
-  public interval: NodeJS.Timeout
+  public timeout: NodeJS.Timeout
+
   /**
-   * Creates an instance of Process.
-   *
-   * @constructor
-   * @param {ProcessConfig} config
-   * @param {number} interval
+   * Constructs a new instance of the LongRunningProcess class.
+   * @param {ProcessConfig} config - The configuration object for the process.
+   * @param {number} interval - The interval at which the process should run.
+   * @returns None
    */
   constructor(config: ProcessConfig, interval: number) {
-    this._interval = interval
+    this.interval = interval
     this.logger = new Logger(config.logger, 'long-running-process')
     this.publisher = new Publisher(config.publisher)
   }
 
-  //Main interface
   /**
-   * ${1:Description placeholder}
-   *
-   * @async
-   * @param {*} executionFunc
-   * @returns {*}
+   * Executes the provided execution function at a specified interval.
+   * @param {Function} executionFunc - The function to execute.
+   * @returns None
    */
-  async execute(executionFunc) {
+  public async execute(executionFunc) {
     this.logger.debug('Starting main process code')
     //Connect DB
     // if (this.db) await this.db.connect();
     //Program loop
-    this.interval = setInterval(async () => {
-      await this._execute(executionFunc)
-    }, this._interval)
+    this.timeout = setInterval(async () => {
+      await this.iexecute(executionFunc)
+    }, this.interval)
   }
-  //Executions
+
   /**
-   * ${1:Description placeholder}
-   *
-   * @async
-   * @param {*} executionFunc
-   * @returns {unknown}
+   * Executes the given execution function asynchronously and handles any exceptions that occur.
+   * @param {Function} executionFunc - The function to execute.
+   * @returns {boolean} - Returns true if the execution failed, false otherwise.
    */
-  async _execute(executionFunc) {
+  private async iexecute(executionFunc) {
     let executionFailed = true //failled til we say no!
     //safe execution handler
     try {

package/src/BaseEvent/Transaction.ts

@@ -2,15 +2,29 @@ import type { APIGatewayEvent, Context, SQSEvent } from 'aws-lambda'
 
 import Request from '../API/Request'
 import Response, { ResponseErrorType } from '../API/Response'
+import { DatabaseManager } from '../Database/DatabaseManager'
+import { DatabaseTransaction } from '../Database/DatabaseTransaction'
+import type { DatabaseTransactionType, DatabaseType, DbConfig } from '../Database/types'
 import Globals from '../Globals'
 import Logger, { LoggerConfig } from '../Logger/Logger'
 import Publisher, { PublisherConfig } from '../Publisher/Publisher'
 
-// Request
+/**
+ * Defines a type for executing a transaction and returning a promise with the response.
+ * @param {TransactionType} transaction - The transaction to execute.
+ * @returns A promise that resolves to the response of the transaction.
+ */
 export type TransactionExecution<TransactionType, ResponseInnerType, MiscRespType = null> = (
   transaction: TransactionType
 ) => Promise<Response<ResponseInnerType> | Response<ResponseErrorType> | MiscRespType>
-// Config
+/**
+ * Represents the configuration options for a transaction.
+ * @typedef {Object} TransactionConfig
+ * @property {boolean} [throwOnErrors] - Whether to throw an error if there are any errors during the transaction.
+ * @property {boolean} [syncReturn] - Whether to return the result of the transaction synchronously.
+ * @property {LoggerConfig} [logger] - The configuration options for the logger.
+ * @property {PublisherConfig} [publisher] - The configuration options for the publisher.
+ */
 export type TransactionConfig = {
   throwOnErrors?: boolean
   syncReturn?: boolean
@@ -19,22 +33,79 @@ export type TransactionConfig = {
   publisher?: PublisherConfig
 }
 
+/**
+ * Represents a transaction object that handles the execution of a request and manages the response.
+ * @template InputType - The type of the input data for the transaction.
+ * @template ResponseInnerType - The type of the inner response data for the transaction.
+ * @template MiscRespType - The type of miscellaneous response data for the transaction.
+ */
 export default class Transaction<
   InputType = object,
   ResponseInnerType = null,
   MiscRespType = null,
 > {
+  /**
+   * The instance of the DatabaseManager class used for managing the database.
+   */
+  private databaseManager: DatabaseManager = DatabaseManager.INSTANCE
+  /**
+   * An array of database transactions.
+   * @type {DatabaseTransaction[]}
+   */
+  private transactions: DatabaseTransaction[] = []
+  /**
+   * Represents an event object.
+   * @private
+   * @type {any}
+   */
   private event: any
+  /**
+   * The context object for the current instance.
+   */
   private context: Context
+  /**
+   * The response object that can hold different types of responses.
+   * @type {Response<ResponseInnerType | ResponseErrorType> | MiscRespType | null}
+   */
   private response: Response<ResponseInnerType | ResponseErrorType> | MiscRespType | null
+  /**
+   * A private boolean variable indicating whether the return value of a synchronous operation
+   * should be synchronized with the calling thread.
+   */
   private syncReturn: boolean
+  /**
+   * A boolean flag indicating whether retroactive errors are enabled or not.
+   * @private
+   */
   private retrowErrors: boolean
-  //
+  /**
+   * A logger object used for logging messages, errors, and other information.
+   * @readonly
+   */
   public readonly logger: Logger
+  /**
+   * The request object for making a request of type InputType.
+   * @readonly
+   */
   public readonly request: Request<InputType>
+  /**
+   * The publisher of the content.
+   */
   public readonly publisher: Publisher
-  public responseProxy: (response: Response<ResponseInnerType>) => Promise<void>
-  //
+  /**
+   * A function that acts as a response proxy for a given response object.
+   * @param {Response<ResponseInnerType>} response - The response object to proxy.
+   * @returns A promise that resolves to void.
+   */
+  public responseProxy: ((response: Response<ResponseInnerType>) => Promise<void>) | null
+
+  /**
+   * Constructs a new instance of the Transaction class.
+   * @param {APIGatewayEvent | SQSEvent} event - The event object passed to the Lambda function.
+   * @param {Context} context - The context object passed to the Lambda function.
+   * @param {TransactionConfig} [config] - Optional configuration object for the transaction.
+   * @returns None
+   */
   constructor(event: APIGatewayEvent | SQSEvent, context: Context, config?: TransactionConfig) {
     const transactionId = context.awsRequestId
       ? context.awsRequestId
@@ -56,14 +127,19 @@ export default class Transaction<
     this.publisher = new Publisher(config?.publisher)
   }
 
-  //Main interface
+  /**
+   * Executes a transaction using the provided execution function and returns a promise
+   * that resolves to the response or miscellaneous response.
+   * @param {TransactionExecution<Transaction<InputType, ResponseInnerType, MiscRespType>, ResponseInnerType, MiscRespType>} executionFunc - The execution function to be executed.
+   * @returns {Promise<Response<ResponseInnerType | ResponseErrorType> | MiscRespType>} - A promise that resolves to the response or miscellaneous response.
+   */
   public async execute(
     executionFunc: TransactionExecution<
       Transaction<InputType, ResponseInnerType, MiscRespType>,
       ResponseInnerType,
       MiscRespType
     >
-  ): Promise<Response<ResponseInnerType | ResponseErrorType> | MiscRespType> {
+  ): Promise<Response<ResponseInnerType | ResponseErrorType> | MiscRespType | null> {
     await this.executeLoggerFlush(async () => {
       await this.executeDBTransactions(async () => {
         return await this.iexecute(executionFunc)
@@ -74,7 +150,12 @@ export default class Transaction<
     // allow request to async succeed through lambda context
     return null
   }
-  //Executions
+
+  /**
+   * Executes a transaction using the provided execution function and handles the response.
+   * @param {TransactionExecution<Transaction<InputType, ResponseInnerType, MiscRespType>, ResponseInnerType, MiscRespType>} executionFunc - The function to execute the transaction.
+   * @returns {Promise<boolean>} - A promise that resolves to a boolean indicating whether the execution failed or not.
+   */
   private async iexecute(
     executionFunc: TransactionExecution<
       Transaction<InputType, ResponseInnerType, MiscRespType>,
@@ -119,32 +200,65 @@ export default class Transaction<
     }
     return executionFailed
   }
-  private async executeDBTransactions(safeExecution) {
+
+  /**
+   * Retrieves a database transaction for the specified database configuration.
+   * @async
+   * @param {DbConfig<S>} config - The configuration object for the database.
+   * @returns {Promise<DatabaseTransactionType<S>>} A promise that resolves to the database transaction.
+   */
+  public async getDbTransaction<S extends DatabaseType>(
+    config: DbConfig<S>
+  ): Promise<DatabaseTransactionType<S>> {
+    const db = this.databaseManager.create(config)
+    const dbTrans = await db.transaction()
+    this.transactions.push(dbTrans)
+    return dbTrans as any
+  }
+  /*
+   * Executes a series of database transactions in a safe manner.
+   * @param {Function} safeExecution - The function that contains the database transactions to be executed.
+   * @returns None
+   * @throws {Error} - If an exception occurs during the execution of the transactions and `retrowErrors` is true.
+   */
+  private async executeDBTransactions(safeExecution: () => Promise<boolean>): Promise<void> {
     try {
-      // //start DB
-      // if (this.db) await this.db.connect();
-      // //start transaction
-      // if (this.db) await this.db.beginTransaction();
-      // //
-      // let executionFailed =
-      await safeExecution()
-      // //Commit if not failed, rollback if failed
-      // if (!executionFailed) {
-      //   if (this.db) await this.db.commit();
-      // } else {
-      //   this.logger.log("Rolling back DB transactions. Main code failed!");
-      //   if (this.db) await this.db.rollback();
-      // }
-      // //Cleanup DB after execution
-      // if (this.db) await this.db.cleanup();
+      // Execute
+      const execFailed = await safeExecution()
+      for (const transaction of [...this.transactions].reverse()) {
+        try {
+          await transaction[execFailed ? 'closeFailure' : 'closeSuccess']()
+        } catch (e) {
+          // TODO: should we keep committing transactions even if one fails?
+          this.logger.error('Exception when closing DB transactions after success.')
+          this.logger.exception(e)
+        }
+      }
     } catch (e) {
+      /* this part of the code handle exceptions at transaction level,
+         so probably a bug but we still handle such */
+      for (const transaction of [...this.transactions].reverse()) {
+        try {
+          await transaction.closeFailure()
+        } catch (e) {
+          this.logger.error('Exception when closing DB transactions after failure.')
+          this.logger.exception(e)
+        }
+      }
       this.logger.error('Exception when executing DB transactions.')
       this.logger.log(e.stack)
       //retrow?
       if (this.retrowErrors) throw e
     }
   }
-  private async executeLoggerFlush(safeExecution) {
+
+  /**
+   * Executes a logger flush operation with error handling and logging.
+   * @param {Function} safeExecution - The function to execute safely.
+   * @returns None
+   * @throws {Error} - If `retrowErrors` is true and an error occurs during execution.
+   */
+  private async executeLoggerFlush(safeExecution): Promise<void> {
     try {
       await safeExecution()
     } catch (e) {
@@ -156,7 +270,13 @@ export default class Transaction<
       this.logger.debug('Transaction ended')
     }
   }
-  /* Response support */
+
+  /**
+   * Returns an error response with the specified error message and error code.
+   * @param {string} error - The error message.
+   * @param {string} code - The error code.
+   * @returns {Response<ResponseErrorType>} - The error response.
+   */
   private getErrorResponse(error: string, code: string): Response<ResponseErrorType> {
     return Response.BadRequestResponseWithRollback(error, code)
   }