@creator.co/wapi 1.3.19 → 1.4.0-alpha1

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

@@ -1,51 +1,84 @@
 import { Knex } from 'knex'
 
 import { KnexDatabase } from './KnexDatabase'
+import { Database } from '../../Database'
 import { DatabaseTransaction } from '../../DatabaseTransaction'
 
 /**
- * A type alias for a Knex transaction object.
- * @typedef {KnexTransactionImpl & Knex.Transaction} KnexTransaction
+ * Represents a Knex transaction, combining the functionality of KnexTransactionImpl
+ * and Knex.Transaction types.
  */
 export type KnexTransaction = KnexTransactionImpl & Knex.Transaction
 
 /**
- * Implementation of a Knex transaction that extends the DatabaseTransaction class.
+ * Represents a Knex database transaction implementation that extends 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.
+   * The Knex instance used for writing operations.
+   * @type {Knex}
+   */
+  public readonly writer: Knex
+  /**
+   * Represents a transaction in Knex, a SQL query builder for Node.js.
+   * This property is used to perform a series of database operations as a single unit of work.
+   * @type {Knex.Transaction} - The transaction object provided by Knex.
+   */
+  protected transaction: Knex.Transaction
+  /**
+   * A protected property representing the database connection using KnexTransaction.
+   * @type {Database<KnexTransaction>}
+   */
+  protected database: Database<KnexTransaction>
+
+  /**
+   * Constructs a new instance of the class with the provided Knex writer and database.
+   * @param {Knex} writer - The Knex instance used for writing to the database.
+   * @param {KnexDatabase} database - The KnexDatabase instance used for database operations.
    * @returns None
    */
-  private constructor(delegate: Knex.Transaction, database: KnexDatabase) {
-    super(delegate, database)
+  private constructor(writer: Knex, database: KnexDatabase) {
+    super(writer, database)
+  }
+
+  /**
+   * Creates a new database transaction using the provided Knex instance and database configuration.
+   * @param {Knex} write - The Knex instance used for read and write operations.
+   * @param {KnexDatabase} database - The database configuration for the transaction.
+   * @returns {Promise<KnexTransaction>} A promise that resolves to a new database transaction.
+   */
+  public static async newTransaction(
+    write: Knex,
+    database: KnexDatabase
+  ): Promise<KnexTransaction> {
+    const tx = new KnexTransactionImpl(write, database)
+    await tx.begin()
+    return DatabaseTransaction.proxyInstance(tx) as any
   }
 
   /**
-   * 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.
+   * Initiates a transaction using the writer and assigns it to the 'transaction' property.
+   * @returns {Promise<Transaction>} A promise that resolves to the transaction object.
    */
-  public static wrapDelegate(delegate: Knex.Transaction, database: KnexDatabase): KnexTransaction {
-    return DatabaseTransaction.wrapInstance(new KnexTransactionImpl(delegate, database)) as any
+  protected doBegin = async () => {
+    this.transaction = await this.writer.transaction()
+    return this.transaction
   }
 
   /**
-   * Commits the changes made by the delegate object.
+   * Commits the current transaction.
    * @returns None
    */
   protected doCommit = () => {
-    return this.delegate.commit()
+    return this.transaction.commit()
   }
 
   /**
-   * Performs a rollback operation by calling the rollback method of the delegate object.
-   * @returns None
+   * Rollback the current transaction.
+   * @returns The result of the rollback operation.
    */
   protected doRollback = () => {
-    return this.delegate.rollback()
+    return this.transaction.rollback()
   }
 }

package/src/Database/integrations/kysely/KyselyDatabase.ts

@@ -0,0 +1,87 @@
+import { Kysely, PostgresDialect } from 'kysely'
+import { Pool } from 'pg'
+
+import { KyselyTransaction, KyselyTransactionImpl } from './KyselyTransaction'
+import { Database } from '../../Database'
+import type { DbConfig } from '../../types'
+
+/**
+ * Represents a database connection using the Kysely library with support for transactions.
+ * @template DBSchema - The schema type for the database.
+ */
+export class KyselyDatabase<DBSchema> extends Database<KyselyTransaction<DBSchema>> {
+  /**
+   * Represents a PostgreSQL provider for querying data using the PostgresDialect.
+   * @type {PostgresDialect}
+   */
+  public static kyselyPgProvider = PostgresDialect
+  /**
+   * A public static property that provides access to the Kysely class.
+   * This property can be accessed without creating an instance of the class.
+   */
+  public static kyselyProvider = Kysely
+  /**
+   * A static property that represents a connection pool for PostgreSQL database connections.
+   * @type {Pool}
+   */
+  public static pgProvider = Pool
+  /**
+   * Represents a PostgreSQL client using the PostgresDialect.
+   */
+  public readonly pgClient: PostgresDialect
+  /**
+   * Represents a client for querying the database with the specified schema.
+   * @type {Kysely<DBSchema>} client - The client for querying the database.
+   */
+  public readonly client: Kysely<DBSchema>
+  /**
+   * Optional property representing the Postgres dialect for reading in a database client.
+   */
+  public readonly pgReadClient?: PostgresDialect
+  /**
+   * Represents a client for reading from the database.
+   * @type {Kysely<DBSchema> | undefined} - The client for reading from the database.
+   */
+  public readonly readClient?: Kysely<DBSchema>
+
+  /**
+   * Constructor for creating a database connection using the provided configuration.
+   * @param {DbConfig<'kysely'>} config - The configuration object for the database connection.
+   * @returns None
+   */
+  public constructor(config: DbConfig<'kysely'>) {
+    super(config)
+    this.pgClient = new KyselyDatabase.kyselyPgProvider({
+      pool: new KyselyDatabase.pgProvider({
+        host: config.host,
+        port: config.port,
+        user: config.username,
+        password: config.password,
+        database: config.database,
+        max: config.maxConnections,
+      }),
+    })
+    this.client = new KyselyDatabase.kyselyProvider<DBSchema>({ dialect: this.pgClient })
+    if (config.readReplica) {
+      this.pgReadClient = new KyselyDatabase.kyselyPgProvider({
+        pool: new KyselyDatabase.pgProvider({
+          host: config.readReplica.host,
+          port: config.readReplica.port,
+          user: config.readReplica.username,
+          password: config.readReplica.password,
+          database: config.readReplica.database,
+          max: config.readReplica.maxConnections,
+        }),
+      })
+      this.readClient = new KyselyDatabase.kyselyProvider<DBSchema>({ dialect: this.pgReadClient })
+    }
+  }
+
+  /**
+   * Override method that starts a new transaction using the provided client and read client.
+   * @returns A Promise that resolves to a KyselyTransaction object for the specified database schema.
+   */
+  public override async transaction(): Promise<KyselyTransaction<DBSchema>> {
+    return KyselyTransactionImpl.newTransaction<DBSchema>(this.client, this, this.readClient)
+  }
+}

package/src/Database/integrations/kysely/KyselyTransaction.ts

@@ -0,0 +1,172 @@
+import { Kysely, Transaction } from 'kysely'
+
+import { KyselyDatabase } from './KyselyDatabase'
+import { Database } from '../../Database'
+import { DatabaseTransaction } from '../../DatabaseTransaction'
+
+/**
+ * Represents a transaction for querying a database with a specific schema.
+ * @typeparam DBSchema - The schema of the database.
+ * @type {KyselyTransactionImpl<DBSchema> & Transaction<DBSchema>}
+ */
+export type KyselyTransaction<DBSchema> = KyselyTransactionImpl<DBSchema> & Transaction<DBSchema>
+/**
+ * Represents a transaction in a Postgres database.
+ */
+export class KyselyTransactionImpl<DBSchema> extends DatabaseTransaction {
+  /**
+   * A readonly property representing a writer for a Kysely object.
+   * @type {Kysely<any>}
+   */
+  public readonly writer: Kysely<any>
+  /**
+   * A readonly property representing a reader of type Kysely<any>.
+   * This property allows reading data of any type using the Kysely interface.
+   */
+  public readonly reader: Kysely<any>
+  /**
+   * A protected property representing a transaction of type any.
+   */
+  protected transaction: Transaction<any>
+  /**
+   * A protected property representing a database instance.
+   * @type {Database<KyselyTransaction<DBSchema>>}
+   */
+  protected database: Database<KyselyTransaction<DBSchema>>
+  /**
+   * A private property that represents a deferred object.
+   * @type {Deferred<any>}
+   */
+  private txWrapper: Deferred<any>
+  /**
+   * Constructs a new instance of the class.
+   * @param {Kysely<DBSchema>} delegate - The delegate object for the database query.
+   * @param {KyselyDatabase<DBSchema>} database - The database object for the query.
+   * @param {Kysely<DBSchema>} [reader] - An optional reader object for the query.
+   * @returns None
+   */
+  private constructor(
+    delegate: Kysely<DBSchema>,
+    database: KyselyDatabase<DBSchema>,
+    reader?: Kysely<DBSchema>
+  ) {
+    super(delegate, database, reader)
+  }
+
+  /**
+   * Creates a new database transaction for the given database schema.
+   * @param {Kysely<DBSchema>} connection - The connection object for the transaction.
+   * @param {KyselyDatabase<DBSchema>} database - The database object for the transaction.
+   * @param {Kysely<DBSchema>} [reader] - An optional reader object for the transaction.
+   * @returns {Promise<KyselyTransaction<DBSchema>>} A promise that resolves to the created transaction.
+   */
+  public static async newTransaction<DBSchema>(
+    connection: Kysely<DBSchema>,
+    database: KyselyDatabase<DBSchema>,
+    reader?: Kysely<DBSchema>
+  ): Promise<KyselyTransaction<DBSchema>> {
+    const tx = new KyselyTransactionImpl<DBSchema>(connection, database, reader)
+    await tx.begin()
+    return DatabaseTransaction.proxyInstance(tx) as any
+  }
+
+  /**
+   * Asynchronously begins a transaction using a writer and resolves the transaction once it is executed.
+   * @returns A Promise that resolves with the transaction object once the transaction is executed.
+   */
+  protected doBegin = async () => {
+    this.txWrapper = new Deferred<any>()
+    return new Promise(resolve => {
+      this.writer
+        .transaction()
+        .execute(async trx => {
+          this.transaction = trx
+          resolve(trx) // resolve with tx
+          return this.txWrapper.promise // wait for wrapper to be solved
+        })
+        .catch(() => {
+          // Don't do anything here. Just swallow the exception.
+        })
+    })
+  }
+
+  /**
+   * Executes the commit operation by resolving the transaction wrapper and returning a resolved Promise.
+   * @returns A Promise that resolves to null.
+   */
+  protected doCommit = () => {
+    this.txWrapper.resolve(null)
+    return Promise.resolve()
+  }
+
+  /**
+   * Performs a rollback operation by rejecting the transaction wrapper with an error.
+   * @returns A resolved Promise after the rollback operation is completed.
+   */
+  protected doRollback = () => {
+    this.txWrapper.reject(new Error('Rollback'))
+    return Promise.resolve()
+  }
+}
+
+/**
+ * Represents a deferred promise that can be resolved or rejected at a later time.
+ * @template T - The type of the value that the promise will resolve to.
+ */
+class Deferred<T> {
+  /**
+   * A private readonly Promise object that resolves to type T.
+   */
+  private readonly _promise: Promise<T>
+  /**
+   * A private property that holds a function to resolve a Promise with a value of type T.
+   * @param {T | PromiseLike<T>} value - The value or promise to be resolved.
+   */
+  private _resolve?: (value: T | PromiseLike<T>) => void
+  /**
+   * A function that can be called to reject a promise with an optional reason.
+   * @param {any} [reason] - An optional reason for rejecting the promise.
+   */
+  private _reject?: (reason?: any) => void
+
+  /**
+   * Constructor for creating a new Promise instance with resolve and reject functions.
+   * @constructor
+   */
+  constructor() {
+    this._promise = new Promise<T>((resolve, reject) => {
+      this._reject = reject
+      this._resolve = resolve
+    })
+  }
+
+  /**
+   * Getter method to retrieve the Promise object.
+   * @returns {Promise<T>} A Promise object of type T.
+   */
+  public get promise(): Promise<T> {
+    return this._promise
+  }
+
+  /**
+   * Resolves the Promise with the given value.
+   * @param {T | PromiseLike<T>} value - The value to resolve the Promise with.
+   * @returns void
+   */
+  public resolve(value: T | PromiseLike<T>): void {
+    if (this._resolve) {
+      this._resolve(value)
+    }
+  }
+
+  /**
+   * Rejects the Promise with the given reason, if the reject function is available.
+   * @param {any} reason - The reason for rejecting the Promise.
+   * @returns void
+   */
+  public reject(reason?: any): void {
+    if (this._reject) {
+      this._reject(reason)
+    }
+  }
+}

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

@@ -5,24 +5,28 @@ import { Database } from '../../Database'
 import type { DbConfig } from '../../types'
 
 /**
- * Represents a Postgres database connection.
+ * Represents a Postgres database connection that extends the Database class.
  * @extends Database<PostgresTransaction>
  */
 export class PostgresDatabase extends Database<PostgresTransaction> {
   /**
-   * A private static property that represents a connection pool for a PostgreSQL database.
+   * A public static property that represents a connection pool for a PostgreSQL database.
+   * This property is used to manage and provide connections to the PostgreSQL database.
    */
-  private static pgProvider = Pool
+  public static pgProvider = Pool
   /**
-   * The client property represents a connection pool to a database.
-   * @private
-   * @type {Pool}
+   * Represents a connection pool to manage multiple client connections to the database.
    */
-  private client: Pool
+  public readonly client: Pool
+  /**
+   * A private property that represents a connection pool for clients.
+   * @type {Pool | undefined}
+   */
+  public readonly readClient?: Pool
 
   /**
-   * Constructs a new instance of the class with the given database configuration.
-   * @param {DbConfig<'pg'>} config - The configuration object for the PostgreSQL database.
+   * Constructor for creating a new instance of a database connection using Postgres.
+   * @param {DbConfig<'pg'>} config - The configuration object for the Postgres database.
    * @returns None
    */
   public constructor(config: DbConfig<'pg'>) {
@@ -35,15 +39,23 @@ export class PostgresDatabase extends Database<PostgresTransaction> {
       database: config.database,
       max: config.maxConnections,
     })
+    if (config.readReplica) {
+      this.readClient = new PostgresDatabase.pgProvider({
+        host: config.readReplica.host,
+        port: config.readReplica.port,
+        user: config.readReplica.username,
+        password: config.readReplica.password,
+        database: config.readReplica.database,
+        max: config.readReplica.maxConnections,
+      })
+    }
   }
 
   /**
-   * Initiates a new transaction in the PostgreSQL database.
-   * @returns {Promise<PostgresTransaction>} A promise that resolves to a PostgresTransaction object representing the new transaction.
+   * Creates a new Postgres transaction using the provided client and read client.
+   * @returns {Promise<PostgresTransaction>} A promise that resolves to a new PostgresTransaction object.
    */
   public override async transaction(): Promise<PostgresTransaction> {
-    const delegate = await this.client.connect()
-    await delegate.query('BEGIN')
-    return PostgresTransactionImpl.wrapDelegate(delegate, this)
+    return PostgresTransactionImpl.newTransaction(this.client, this, this.readClient)
   }
 }

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

@@ -1,6 +1,7 @@
-import { PoolClient } from 'pg'
+import { Pool, PoolClient } from 'pg'
 
 import { PostgresDatabase } from './PostgresDatabase'
+import { Database } from '../../Database'
 import { DatabaseTransaction } from '../../DatabaseTransaction'
 
 /**
@@ -14,41 +15,73 @@ export type PostgresTransaction = PostgresTransactionImpl & PoolClient
  */
 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
+   * A Pool object used for writing operations.
+   * @readonly
    */
-  private constructor(delegate: PoolClient, database: PostgresDatabase) {
-    super(delegate, database)
+  public readonly writer: Pool
+  /**
+   * A readonly property representing a pool reader.
+   */
+  public readonly reader: Pool
+  /**
+   * Represents a database transaction using a PoolClient.
+   * @type {PoolClient}
+   */
+  protected transaction: PoolClient
+  /**
+   * A protected property representing a database of type Database<PostgresTransaction>.
+   * This property is used to interact with a Postgres database using transactions.
+   */
+  protected database: Database<PostgresTransaction>
+  /**
+   * Constructs a new instance of the class with the provided writer, database, and optional reader.
+   * @param {Pool} writer - The writer pool for database operations.
+   * @param {PostgresDatabase} database - The Postgres database instance.
+   * @param {Pool} [reader] - The reader pool for database operations (optional).
+   */
+  private constructor(writer: Pool, database: PostgresDatabase, reader?: Pool) {
+    super(writer, database, reader)
+  }
+
+  /**
+   * Creates a new database transaction using the provided writer and database instances.
+   * @param {Pool} writer - The writer instance for the transaction.
+   * @param {PostgresDatabase} database - The database instance for the transaction.
+   * @param {Pool} [reader] - Optional reader instance for the transaction.
+   * @returns {Promise<PostgresTransaction>} A promise that resolves to a new PostgresTransaction instance.
+   */
+  public static async newTransaction(
+    writer: Pool,
+    database: PostgresDatabase,
+    reader?: Pool
+  ): Promise<PostgresTransaction> {
+    const tx = new PostgresTransactionImpl(writer, database, reader)
+    await tx.begin() // defaults to opened
+    return DatabaseTransaction.proxyInstance(tx) as any
   }
 
   /**
-   * 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.
+   * Initiates a transaction by connecting to the writer and executing a 'BEGIN' query.
+   * @returns {Promise<void>} A promise that resolves when the transaction is successfully initiated.
    */
-  public static wrapDelegate(
-    delegate: PoolClient,
-    database: PostgresDatabase
-  ): PostgresTransaction {
-    return DatabaseTransaction.wrapInstance(new PostgresTransactionImpl(delegate, database)) as any
+  protected doBegin = async () => {
+    this.transaction = await this.writer.connect()
+    return this.transaction.query('BEGIN')
   }
 
   /**
-   * Commits the current transaction.
-   * @returns A promise that resolves when the commit is successful.
+   * Executes a COMMIT query to commit the current transaction.
+   * @returns A Promise that resolves when the COMMIT query is successfully executed.
    */
   protected doCommit = () => {
-    return this.delegate.query('COMMIT')
+    return this.transaction.query('COMMIT')
   }
 
   /**
-   * Performs a rollback operation in the database.
-   * @returns A promise that resolves when the rollback operation is completed.
+   * Rolls back the current transaction by executing a 'ROLLBACK' query.
+   * @returns A Promise that resolves when the rollback is successful.
    */
   protected doRollback = () => {
-    return this.delegate.query('ROLLBACK')
+    return this.transaction.query('ROLLBACK')
   }
 }

package/src/Database/types.ts

@@ -1,45 +1,60 @@
 import { Database } from './Database'
 import { DATABASES } from './DatabaseManager'
+import { KnexDatabase } from './integrations/knex/KnexDatabase'
+import { KyselyDatabase } from './integrations/kysely/KyselyDatabase'
+import { PostgresDatabase } from './integrations/pgsql/PostgresDatabase'
 
 /**
- * Represents the available types of databases.
+ * Represents the possible types of databases available in the system.
  * @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.
+ * Defines a type for a database class that includes instances for Knex, Postgres, and Kysely databases.
+ * @template T - The type of data the KyselyDatabase instance will handle.
+ * @property {new (...args: any[]) => KnexDatabase} knex - Constructor for KnexDatabase instances.
+ * @property {new (...args: any[]) => PostgresDatabase} pg - Constructor for PostgresDatabase instances.
+ * @property {new (...args: any[]) => KyselyDatabase<T>} kysely - Constructor for KyselyDatabase instances with type T.
  */
-export type DatabaseImplType<Type extends DatabaseType> = InstanceType<(typeof DATABASES)[Type]>
+export type DatabaseClass<T> = {
+  knex: new (...args: any[]) => KnexDatabase
+  pg: new (...args: any[]) => PostgresDatabase
+  kysely: new (...args: any[]) => KyselyDatabase<T>
+}
 
 /**
- * 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.
+ * Represents a specific implementation type for a database based on the provided DatabaseType.
+ * @param {DatabaseType} Type - The type of database to implement.
+ * @param {T} T - The generic type for the database implementation.
+ * @returns An instance of the specified database class for the given type.
  */
-export type DatabaseTransactionType<Type extends DatabaseType> =
-  DatabaseImplType<Type> extends Database<infer TransactionType> ? TransactionType : never
+export type DatabaseImplType<Type extends DatabaseType, T> = InstanceType<DatabaseClass<T>[Type]>
 
 /**
- * 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.
- * @property {boolean} [convertCamelToSnake] - Whether or not to convert camel case to snake case for column names.
- * @returns The transaction type associated with the specified database type.
+ * Defines the type of transaction for a specific database type and schema.
+ * @param {DatabaseType} Type - The type of the database.
+ * @param {DBSchema} DBSchema - The schema of the database.
+ * @returns The transaction type associated with the database type and schema.
  */
-export type DbConfig<S extends DatabaseType> = {
-  type: S
-  driver: string
+export type DatabaseTransactionType<Type extends DatabaseType, DBSchema> =
+  DatabaseImplType<Type, DBSchema> extends Database<infer TransactionType> ? TransactionType : never
+
+/**
+ * Defines the configuration options for different types of databases.
+ * @typedef {Object} DbBaseConfig
+ * @property {string} host - The host of the database.
+ * @property {number} port - The port number of the database.
+ * @property {string} username - The username for accessing the database.
+ * @property {string} password - The password for accessing the database.
+ * @property {string} database - The name of the database.
+ * @property {boolean} autoCommit - Flag indicating whether auto-commit is enabled.
+ * @property {number} maxConnections - The maximum number of connections allowed.
+ *
+ * @typedef {Object} DbConfig
+ * @property {string} type - The type of
+ */
+type DbBaseConfig = {
   host: string
   port: number
   username: string
@@ -47,8 +62,15 @@ export type DbConfig<S extends DatabaseType> = {
   database: string
   autoCommit: boolean
   maxConnections: number
-} & (S extends 'knex'
-  ? {
-      convertCamelToSnake?: boolean
-    }
-  : any)
+}
+export type DbConfig<S extends DatabaseType> = DbBaseConfig & { type: S } & (S extends 'knex'
+    ? {
+        driver?: string
+        convertCamelToSnake?: boolean
+      }
+    : unknown) &
+  (S extends 'pg' | 'kysely'
+    ? {
+        readReplica?: DbBaseConfig
+      }
+    : unknown)