@creator.co/wapi 1.2.4 → 1.2.6

package/src/Database/DatabaseTransaction.ts

@@ -0,0 +1,118 @@
+import { Database } from './Database'
+
+/**
+ * Abstract class representing a database transaction.
+ * @class DatabaseTransaction
+ */
+export abstract class DatabaseTransaction {
+  private _isOpen: boolean = true
+  protected delegate: any
+  protected database: Database<any>
+
+  /**
+   * Returns a boolean value indicating whether the transaction is open or not.
+   * @returns {boolean} - true if the object is open, false otherwise.
+   */
+  public get isOpen(): boolean {
+    return this._isOpen
+  }
+
+  /**
+   * Constructs a new instance of the class.
+   * @param {any} delegate - The delegate object.
+   * @param {Database<any>} database - The database object.
+   * @protected
+   */
+  protected constructor(delegate: any, database: Database<any>) {
+    this.delegate = delegate
+    this.database = database
+  }
+
+  /**
+   * Wraps an instance of a subclass of DatabaseTransaction with a Proxy object.
+   * The Proxy object intercepts method calls and delegates to the target instance.
+   * If the method is on the target instance, it is called directly.
+   * If the method is not on the target instance and the transaction is open, it is called on the target's delegate implementation.
+   * If the method is not on the target instance and the transaction is closed, an error is thrown.
+   * @param {T} subclass - The subclass instance to wrap with a Proxy.
+   * @returns {T} - The wrapped subclass instance.
+   * @throws {Error} - If the target instance is closed.
+   */
+  protected static wrapInstance<T extends DatabaseTransaction>(subclass: T): T {
+    const bind = (target: any, key: string | symbol) =>
+      typeof target[key] === 'function' ? target[key].bind(target) : target[key]
+
+    return new Proxy<T>(subclass, {
+      get(target: T, p: string | symbol): any {
+        if (target[p] !== undefined) {
+          return bind(target, p)
+        } else if (target._isOpen) {
+          return bind(target.delegate, p)
+        }
+        return undefined
+      },
+    })
+  }
+
+  /**
+   * Commits the transaction.
+   * @throws {Error} - If the transaction is already closed.
+   * @returns None
+   */
+  public async commit(): Promise<void> {
+    if (!this._isOpen) {
+      throw new Error('Cannot commit, transaction is already closed!')
+    }
+    await this.doCommit()
+    this._isOpen = false
+  }
+
+  /**
+   * Rollbacks the current transaction.
+   * @throws {Error} - If the transaction is already closed.
+   * @returns {Promise<void>} - A promise that resolves once the rollback is complete.
+   */
+  public async rollback(): Promise<void> {
+    if (!this._isOpen) {
+      throw new Error('Cannot rollback, transaction is already closed!')
+    }
+    await this.doRollback()
+    this._isOpen = false
+  }
+
+  /**
+   * Closes the transaction after a successful execution.
+   * @returns {Promise<void>} - A promise that resolves once the necessary actions are completed.
+   */
+  public async closeSuccess() {
+    if (this._isOpen) {
+      if (this.database.config.autoCommit) {
+        await this.doCommit()
+      } else {
+        await this.doRollback()
+      }
+    }
+  }
+
+  /**
+   * Closes the transaction after a failed execution.
+   * @returns {Promise<void>} - A promise that resolves once the necessary actions are completed.
+   */
+  public async closeFailure() {
+    if (this._isOpen) {
+      await this.doRollback()
+    }
+  }
+
+  /**
+   * An abstract method that performs the commit operation.
+   * @returns {Promise<any>} A promise that resolves when the commit operation is completed.
+   */
+  protected abstract doCommit(): Promise<any>
+
+  /**
+   * An abstract method that performs a rollback operation.
+   * @returns A Promise that resolves when the rollback operation is complete.
+   */
+  protected abstract doRollback(): Promise<any>
+}

package/src/Database/integrations/knex/KnexDatabase.ts

@@ -0,0 +1,47 @@
+import knex, { Knex } from 'knex'
+
+import { KnexTransaction, KnexTransactionImpl } from './KnexTransaction'
+import { Database } from '../../Database'
+import type { DbConfig } from '../../types'
+
+/**
+ * Represents a Knex database connection.
+ * @extends Database<KnexTransaction>
+ */
+export class KnexDatabase extends Database<KnexTransaction> {
+  private static knexProvider: (config: knex.Knex.Config<any>) => knex.Knex<any, unknown[]> = knex
+
+  private client: Knex
+
+  /**
+   * Constructs a new instance of the database class using the provided configuration.
+   * @param {DbConfig<'knex'>} config - The configuration object for the database.
+   * @returns None
+   */
+  public constructor(config: DbConfig<'knex'>) {
+    super(config)
+    this.client = KnexDatabase.knexProvider({
+      client: config.driver,
+      connection: {
+        host: config.host,
+        port: config.port,
+        user: config.username,
+        password: config.password,
+        database: config.database,
+      },
+      pool: {
+        min: 1,
+        max: config.maxConnections,
+      },
+    })
+  }
+
+  /**
+   * Initiates a transaction using the underlying database client.
+   * @returns {Promise<KnexTransaction>} A promise that resolves to a KnexTransaction object representing the transaction.
+   */
+  public override async transaction(): Promise<KnexTransaction> {
+    const delegate = await this.client.transaction()
+    return KnexTransactionImpl.wrapDelegate(delegate, this)
+  }
+}

package/src/Database/integrations/knex/KnexTransaction.ts

@@ -0,0 +1,51 @@
+import { Knex } from 'knex'
+
+import { KnexDatabase } from './KnexDatabase'
+import { DatabaseTransaction } from '../../DatabaseTransaction'
+
+/**
+ * A type alias for a Knex transaction object.
+ * @typedef {KnexTransactionImpl & Knex.Transaction} KnexTransaction
+ */
+export type KnexTransaction = KnexTransactionImpl & Knex.Transaction
+
+/**
+ * Implementation of a Knex transaction that extends the DatabaseTransaction class.
+ */
+export class KnexTransactionImpl extends DatabaseTransaction {
+  /**
+   * Constructs a new instance of the private class.
+   * @param {Knex.Transaction} delegate - The delegate transaction object.
+   * @param {KnexDatabase} database - The database object.
+   * @returns None
+   */
+  private constructor(delegate: Knex.Transaction, database: KnexDatabase) {
+    super(delegate, database)
+  }
+
+  /**
+   * Wraps a delegate transaction object with a custom implementation of the KnexTransaction interface.
+   * @param {Knex.Transaction} delegate - The delegate transaction object to wrap.
+   * @param {KnexDatabase} database - The KnexDatabase instance associated with the transaction.
+   * @returns {KnexTransaction} - The wrapped transaction object.
+   */
+  public static wrapDelegate(delegate: Knex.Transaction, database: KnexDatabase): KnexTransaction {
+    return DatabaseTransaction.wrapInstance(new KnexTransactionImpl(delegate, database)) as any
+  }
+
+  /**
+   * Commits the changes made by the delegate object.
+   * @returns None
+   */
+  protected doCommit() {
+    return this.delegate.commit()
+  }
+
+  /**
+   * Performs a rollback operation by calling the rollback method of the delegate object.
+   * @returns None
+   */
+  protected doRollback() {
+    return this.delegate.rollback()
+  }
+}

package/src/Database/integrations/pgsql/PostgresDatabase.ts

@@ -0,0 +1,49 @@
+import { Pool } from 'pg'
+
+import { PostgresTransaction, PostgresTransactionImpl } from './PostgresTransaction'
+import { Database } from '../../Database'
+import type { DbConfig } from '../../types'
+
+/**
+ * Represents a Postgres database connection.
+ * @extends Database<PostgresTransaction>
+ */
+export class PostgresDatabase extends Database<PostgresTransaction> {
+  /**
+   * A private static property that represents a connection pool for a PostgreSQL database.
+   */
+  private static pgProvider = Pool
+  /**
+   * The client property represents a connection pool to a database.
+   * @private
+   * @type {Pool}
+   */
+  private client: Pool
+
+  /**
+   * Constructs a new instance of the class with the given database configuration.
+   * @param {DbConfig<'pg'>} config - The configuration object for the PostgreSQL database.
+   * @returns None
+   */
+  public constructor(config: DbConfig<'pg'>) {
+    super(config)
+    this.client = new PostgresDatabase.pgProvider({
+      host: config.host,
+      port: config.port,
+      user: config.username,
+      password: config.password,
+      database: config.database,
+      max: config.maxConnections,
+    })
+  }
+
+  /**
+   * Initiates a new transaction in the PostgreSQL database.
+   * @returns {Promise<PostgresTransaction>} A promise that resolves to a PostgresTransaction object representing the new transaction.
+   */
+  public override async transaction(): Promise<PostgresTransaction> {
+    const delegate = await this.client.connect()
+    await delegate.query('BEGIN')
+    return PostgresTransactionImpl.wrapDelegate(delegate, this)
+  }
+}

package/src/Database/integrations/pgsql/PostgresTransaction.ts

@@ -0,0 +1,54 @@
+import { PoolClient } from 'pg'
+
+import { PostgresDatabase } from './PostgresDatabase'
+import { DatabaseTransaction } from '../../DatabaseTransaction'
+
+/**
+ * A type alias representing a Postgres transaction. It extends the `PostgresTransactionImpl`
+ * interface and includes the `PoolClient` interface.
+ */
+export type PostgresTransaction = PostgresTransactionImpl & PoolClient
+
+/**
+ * Represents a transaction in a Postgres database.
+ */
+export class PostgresTransactionImpl extends DatabaseTransaction {
+  /**
+   * Constructs a new instance of the private class.
+   * @param {PoolClient} delegate - The delegate object.
+   * @param {PostgresDatabase} database - The database object.
+   * @returns None
+   */
+  private constructor(delegate: PoolClient, database: PostgresDatabase) {
+    super(delegate, database)
+  }
+
+  /**
+   * Static factory method for creating a new instance, wrapping a delegate PoolClient.
+   * @param {PoolClient} delegate - The delegate client to wrap.
+   * @param {PostgresDatabase} database - The PostgresDatabase instance associated with the transaction.
+   * @returns {PostgresTransaction} - A wrapped PostgresTransaction instance.
+   */
+  public static wrapDelegate(
+    delegate: PoolClient,
+    database: PostgresDatabase
+  ): PostgresTransaction {
+    return DatabaseTransaction.wrapInstance(new PostgresTransactionImpl(delegate, database)) as any
+  }
+
+  /**
+   * Commits the current transaction.
+   * @returns A promise that resolves when the commit is successful.
+   */
+  protected doCommit() {
+    return this.delegate.query('COMMIT')
+  }
+
+  /**
+   * Performs a rollback operation in the database.
+   * @returns A promise that resolves when the rollback operation is completed.
+   */
+  protected doRollback() {
+    return this.delegate.query('ROLLBACK')
+  }
+}

package/src/Database/types.d.ts

@@ -0,0 +1,49 @@
+import { Database } from './Database'
+import { DATABASES } from './DatabaseManager'
+
+/**
+ * Represents the available types of databases.
+ * @typedef {keyof typeof DATABASES} DatabaseType
+ */
+export type DatabaseType = keyof typeof DATABASES
+
+/**
+ * Represents the instance type of the specified database implementation.
+ * @param {Type} Type - The type of the database implementation.
+ */
+export type DatabaseImplType<Type extends DatabaseType> = InstanceType<(typeof DATABASES)[Type]>
+
+/**
+ * Defines a type for a database transaction based on the specified database type.
+ * @param {Type} - The database type.
+ * @returns The transaction type associated with the specified database type.
+ */
+export type DatabaseTransactionType<Type extends DatabaseType> =
+  DatabaseImplType<Type> extends Database<infer TransactionType> ? TransactionType : never
+
+/**
+ * Represents the configuration for a database connection.
+ * @template S - The type of the database (e.g. "mysql", "postgres", etc.)
+ * @interface DbConfig
+ * @property {S} type - The type of the database.
+ * @property {string} driver - The driver to use for the database connection.
+ * @property {string} host - The host of the database server.
+ * @property {number} port - The port number of the database server.
+ * @property {string} username - The username for the database connection.
+ * @property {string} password - The password for the database connection.
+ * @property {string} database - The name of the database to connect to.
+ * @property {boolean} autoCommit - Whether or not to automatically commit transactions.
+ * @property {number} maxConnections - The maximum number of connections to the database.
+ * @returns The transaction type associated with the specified database type.
+ */
+export interface DbConfig<S extends DatabaseType> {
+  type: S
+  driver: string
+  host: string
+  port: number
+  username: string
+  password: string
+  database: string
+  autoCommit: boolean
+  maxConnections: number
+}

package/src/Globals.ts

@@ -4,168 +4,100 @@ import Utils from './API/Utils'
 
 // important for dev env to load .env file
 dotenv.config()
+
 /**
- * Description placeholder
- *
- * @export
- * @class Globals
- * @typedef {Globals}
+ * Class containing global constants and configurations for the application.
  */
 export default class Globals {
   /**
-   * Description placeholder
-   *
-   * @public
-   * @static
-   * @type {string}
+   * A constant string representing an error message for input validation failure.
    */
   public static ErrorResponseValidationFail = 'Input validation failed: ' //400
   /**
-   * Description placeholder
-   *
-   * @public
-   * @static
-   * @type {string}
+   * A constant string representing an error response for an invalid server response.
    */
   public static ErrorResponseInvalidServerResponse = 'No valid response, this is a system error.' //400
   /**
-   * Description placeholder
-   *
-   * @public
-   * @static
-   * @type {string}
+   * The error message for an unhandled error when processing a request.
    */
   public static ErrorResponseUnhandledError = 'Unhandled error when processing request.' //400
   /**
-   * Description placeholder
-   *
-   * @public
-   * @static
-   * @type {string}
+   * A static string representing an error response when there are no records to be processed.
    */
   public static ErrorResponseNoRecords = 'No events to be processed.' //400
   /**
-   * Description placeholder
-   *
-   * @public
-   * @static
+   * Represents an error code for a missing parameter.
    * @type {string}
    */
   public static ErrorCode_MissingParam = 'MISSING_PARAM'
   /**
-   * Description placeholder
-   *
-   * @public
-   * @static
+   * Represents an error code for invalid input.
    * @type {string}
    */
   public static ErrorCode_InvalidInput = 'INVALID_INPUT'
   /**
-   * Description placeholder
-   *
-   * @public
-   * @static
+   * Represents an error code for an API error.
    * @type {string}
    */
   public static ErrorCode_APIError = 'API_ERROR'
   /**
-   * Description placeholder
-   *
-   * @public
-   * @static
+   * Represents the error code for when there are no records found.
    * @type {string}
    */
   public static ErrorCode_NoRecords = 'EMPTY_EVENT'
 
   /**
-   * Description placeholder
-   *
-   * @public
-   * @static
-   * @type {*}
+   * Retrieves the default port number for HTTP listeners.
+   * The port number is obtained from the environment variable "PORT" and parsed as an integer.
+   * If the environment variable is not set or cannot be parsed as an integer, the default port number 9000 is used.
+   * @returns {number} - The default port number for HTTP listeners.
    */
   public static Listener_HTTP_DefaultPort = Utils.parseIntNullIfNaN(process.env.PORT) || 9000
-
   /**
-   * Description placeholder
-   *
-   * @public
-   * @static
-   * @type {string}
+   * The default host for the HTTP listener.
    */
   public static Listener_HTTP_DefaultHost = 'localhost'
   /**
-   * Description placeholder
-   *
-   * @public
-   * @static
+   * The HTTP proxy route listener for all routes.
    * @type {string}
    */
   public static Listener_HTTP_ProxyRoute = '*'
   /**
-   * Description placeholder
-   *
-   * @public
-   * @static
-   * @type {*}
+   * Retrieves the default timeout value for HTTP listeners.
+   * @returns {number} The default timeout value in milliseconds.
    */
   public static Listener_HTTP_DefaultTimeout = Utils.parseIntNullIfNaN(process.env.TIMEOUT) || 30000
   /**
-   * Description placeholder
-   *
-   * @public
-   * @static
-   * @type {*}
+   * The default health check route for the HTTP listener.
+   * @type {string}
    */
   public static Listener_HTTP_DefaultHealthCheckRoute = process.env.HEALTH_ROUTE || '/health'
-  //Resps
+
   /**
-   * Description placeholder
-   *
-   * @public
-   * @static
-   * @type {string}
+   * The response message for an exception that occurred during request execution in the Proxy.
    */
   public static Resp_MSG_EXCEPTION = '[Proxy]: Exception during request execution!'
   /**
-   * Description placeholder
-   *
-   * @public
-   * @static
-   * @type {string}
+   * The response code for an exception that occurred during execution.
    */
   public static Resp_CODE_EXCEPTION = 'EXEC_EXCEPTION'
   /**
-   * Description placeholder
-   *
-   * @public
-   * @static
-   * @type {number}
+   * The HTTP response status code for an exception scenario.
    */
   public static Resp_STATUSCODE_EXCEPTION = 502
 
   /**
-   * Description placeholder
-   *
-   * @public
-   * @static
-   * @type {string}
+   * The error message for an invalid response from the server.
    */
   public static Resp_MSG_INVALIDRESP = '[Proxy]: Invalid response from server!'
   /**
-   * Description placeholder
-   *
-   * @public
-   * @static
-   * @type {string}
+   * Represents the response code for an invalid response.
    */
   public static Resp_CODE_INVALIDRESP = 'EMPTY_RESPONSE'
   /**
-   * Description placeholder
-   *
-   * @public
-   * @static
+   * The HTTP response status code for an invalid response.
    * @type {number}
+   * @default 400
    */
   public static Resp_STATUSCODE_INVALIDRESP = 400
 }