@ikonintegration/ikapi 4.0.1 → 5.0.0

package/src/BaseEvent/Process.ts

@@ -0,0 +1,78 @@
+import { TransactionConfig } from './Transaction.js'
+import Logger from '../Logger/Logger.js'
+import Publisher from '../Publisher/Publisher.js'
+
+/**
+ * A type that represents a modified version of the TransactionConfig type, excluding the 'throwOnErrors' and 'syncReturn' properties.
+ */
+export type ProcessConfig = Omit<TransactionConfig, 'throwOnErrors' | 'syncReturn'>
+
+/**
+ * Represents a long-running process that executes a given function at a specified interval.
+ */
+export default class Process {
+  /**
+   * Private member variable representing the interval value.
+   * @type {number}
+   * @private
+   */
+  private interval: number
+  /**
+   * A logger object used for logging messages, errors, and other information.
+   * @readonly
+   */
+  public readonly logger: Logger
+  /**
+   * The publisher of the content.
+   */
+  public readonly publisher: Publisher
+  /**
+   * A reference to the NodeJS.Timeout object representing the interval timer.
+   */
+  public timeout: NodeJS.Timeout
+
+  /**
+   * 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.logger = new Logger(config.logger, 'long-running-process')
+    this.publisher = new Publisher(config.publisher)
+  }
+
+  /**
+   * Executes the provided execution function at a specified interval.
+   * @param {Function} executionFunc - The function to execute.
+   * @returns None
+   */
+  public async execute(executionFunc) {
+    this.logger.debug('Starting main process code')
+    //Program loop
+    this.timeout = setInterval(async () => {
+      await this.iexecute(executionFunc)
+    }, this.interval)
+  }
+
+  /**
+   * 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.
+   */
+  private async iexecute(executionFunc) {
+    let executionFailed = true //failed til we say no!
+    // safe execution handler
+    try {
+      // Execute
+      await executionFunc(this)
+      executionFailed = false
+    } catch (e) {
+      /* EXECUTION FAIL */
+      this.logger.error('Exception when executing main process code. Rolling back DB!')
+      this.logger.exception(e)
+    }
+    return executionFailed
+  }
+}

package/src/BaseEvent/StepTransaction.ts

@@ -0,0 +1,35 @@
+import type { Context } from 'aws-lambda'
+
+import Transaction, { TransactionConfig } from './Transaction.js'
+import Response, { ResponseErrorType } from '../API/Response.js'
+
+/**
+ * Represents a step transaction that extends the Transaction class.
+ */
+export default class StepTransaction extends Transaction {
+  /**
+   * Constructor for creating a new Transaction object.
+   * @param {any} event - The event object.
+   * @param {Context} context - The context object.
+   * @param {TransactionConfig} [config] - Optional configuration for the transaction.
+   * @returns None
+   */
+  constructor(event: any, context: Context, config?: TransactionConfig) {
+    super(event, context, {
+      syncReturn: true,
+      throwOnErrors: true,
+      // allow override
+      ...(config || {}),
+    })
+  }
+
+  /**
+   * Generates an error response with the provided error message and error code.
+   * @param {string} error - The error message to include in the response.
+   * @param {string} code - The error code associated with the error.
+   * @returns {Response<ResponseErrorType>} - The error response object.
+   */
+  protected getErrorResponse(error: string, code: string): Response<ResponseErrorType> {
+    return Response.StepFunctionResponse({ err: error, errCode: code }, 400)
+  }
+}

package/src/BaseEvent/Transaction.ts

@@ -0,0 +1,323 @@
+import type { APIGatewayEvent, Context, DynamoDBStreamEvent, SQSEvent } from 'aws-lambda'
+
+import Request from '../API/Request.js'
+import Response, { ResponseErrorType } from '../API/Response.js'
+import { DatabaseManager } from '../Database/DatabaseManager.js'
+import { DatabaseTransaction } from '../Database/DatabaseTransaction.js'
+import type {
+  DatabaseImplType,
+  DatabaseTransactionType,
+  DatabaseType,
+  DbConfig,
+} from '../Database/types.js'
+import Globals from '../Globals.js'
+import Logger, { LoggerConfig } from '../Logger/Logger.js'
+import Publisher, { PublisherConfig } from '../Publisher/Publisher.js'
+
+/**
+ * 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 = never> = (
+  transaction: TransactionType
+) => Promise<Response<ResponseInnerType> | Response<ResponseErrorType> | MiscRespType>
+
+/**
+ * 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 {boolean} [skipCleanTmp] - Whether to skip cleaning the temporary folder, in EventProcessor.
+ * @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
+  skipCleanTmp?: boolean
+  //
+  logger?: LoggerConfig
+  publisher?: PublisherConfig
+}
+
+/**
+ * Represents a simple string dictionary with string values
+ */
+export type StringMap = { [key: string]: string | null }
+
+/**
+ * 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 = never,
+  ResponseInnerType = null,
+  MiscRespType = never,
+  PathParamsType = StringMap,
+  QueryParamsType = StringMap,
+> {
+  /**
+   * 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
+  /**
+   * 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, PathParamsType, QueryParamsType>
+  /**
+   * The publisher of the content.
+   */
+  public readonly publisher: Publisher
+  /**
+   * 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 | DynamoDBStreamEvent} 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 | DynamoDBStreamEvent,
+    context: Context,
+    config?: TransactionConfig
+  ) {
+    const transactionId = context.awsRequestId
+      ? context.awsRequestId
+      : (<APIGatewayEvent>event).requestContext
+        ? (<APIGatewayEvent>event).requestContext.requestId
+        : 'unknown'
+    // transaction ctx
+    this.event = event
+    this.context = context
+    // when set, this will be called with the response context right before calling the context suceed/fail - useful for writing the resp for example.
+    this.responseProxy = null
+    // transaction flags
+    this.syncReturn = !!config?.syncReturn
+    this.retrowErrors = !!config?.throwOnErrors /* retrow internal errors */
+    // components
+    this.logger = new Logger(config?.logger, transactionId)
+    this.request = new Request<InputType, PathParamsType, QueryParamsType>(
+      this.event,
+      this.context,
+      this.logger
+    )
+    this.publisher = new Publisher(config?.publisher)
+  }
+
+  /**
+   * 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, PathParamsType, QueryParamsType>,
+      ResponseInnerType,
+      MiscRespType
+    >
+  ): Promise<Response<ResponseInnerType | ResponseErrorType> | MiscRespType | null> {
+    await this.executeLoggerFlush(async () => {
+      await this.executeDBTransactions(async () => {
+        return await this.iexecute(executionFunc)
+      })
+    })
+    // return raw response if sync return is requested
+    if (this.syncReturn) return this.response
+    // allow request to async succeed through lambda context
+    return null
+  }
+
+  /**
+   * 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, PathParamsType, QueryParamsType>,
+      ResponseInnerType,
+      MiscRespType
+    >
+  ): Promise<boolean> {
+    let executionFailed = true //failed til we say no!
+    //safe execution handler
+    try {
+      //Execute
+      this.logger.debug('Starting main request code')
+      this.response = await executionFunc(this)
+      //Answer client
+      if (this.response && this.response instanceof Response) {
+        await this.response.build(this.context, this, this.syncReturn)
+        executionFailed = !!(this.response.getBody() && this.response.getBody()['rollback'])
+      } else if (this.syncReturn && this.response) {
+        this.logger.log('Sync return with different response object')
+        this.logger.debug(this.response)
+        executionFailed = false
+      } else {
+        this.response = this.getErrorResponse(
+          Globals.ErrorResponseInvalidServerResponse,
+          Globals.ErrorCode_APIError
+        )
+        await this.response.build(this.context, this, this.syncReturn)
+        this.logger.error('Invalid response object from main request code.')
+      }
+    } catch (e) {
+      /*EXECUTION FAIL*/
+      this.logger.error('Exception when executing main request code.')
+      this.logger.exception(e)
+      //retrow?
+      if (this.retrowErrors) throw e
+      //envelope exception?
+      this.response = this.getErrorResponse(
+        Globals.ErrorResponseUnhandledError,
+        Globals.ErrorCode_APIError
+      )
+      await this.response.build(this.context, this, this.syncReturn)
+    }
+    return executionFailed
+  }
+
+  /**
+   * Retrieves a database transaction based on the provided database configuration.
+   * @param {DbConfig<S>} config - The configuration object for the database.
+   * @returns {Promise<DatabaseTransactionType<S, DBSchema>>} A promise that resolves to the database transaction.
+   */
+  public async getDbTransaction<S extends DatabaseType, DBSchema>(
+    config: DbConfig<S>
+  ): Promise<DatabaseTransactionType<S, DBSchema>> {
+    const db = this.getDatabase<S, DBSchema>(config)
+    const dbTrans = await db.transaction()
+    this.transactions.push(dbTrans)
+    return dbTrans as any
+  }
+
+  /**
+   * Retrieves a database instance based on the provided configuration.
+   * @param {DbConfig<S>} config - The configuration object specifying the type of database.
+   * @returns {DatabaseImplType<S, DBSchema>} A database instance based on the provided configuration.
+   */
+  public getDatabase<S extends DatabaseType, DBSchema>(
+    config: DbConfig<S>
+  ): DatabaseImplType<S, DBSchema> {
+    return this.databaseManager.create<S, DBSchema>(config)
+  }
+
+  /**
+   * Get the remaining time in milliseconds for the current execution context.
+   * @returns {number} The remaining time in milliseconds, or -1 if the time is not available.
+   */
+  public getRemainingTimeInMillis() {
+    return this.context?.getRemainingTimeInMillis?.() || -1
+  }
+
+  /*
+   * 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 {
+      // Execute
+      const execFailed = await safeExecution()
+      for (const transaction of [...this.transactions].reverse()) {
+        try {
+          await transaction[execFailed ? 'closeFailure' : 'closeSuccess']()
+        } catch (e) {
+          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
+    }
+  }
+
+  /**
+   * 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) {
+      this.logger.error('Exception when flushing logs.')
+      this.logger.exception(e)
+      //retrow?
+      if (this.retrowErrors) throw e
+    } finally {
+      this.logger.debug('Transaction ended')
+    }
+  }
+
+  /**
+   * Generates an error response with the provided error message and code.
+   * @param {string} error - The error message to include in the response.
+   * @param {string} code - The error code associated with the response.
+   * @returns {Response<ResponseErrorType>} - The error response object.
+   */
+  protected getErrorResponse(error: string, code: string): Response<ResponseErrorType> {
+    return Response.BadRequestResponseWithRollback(error, code)
+  }
+}

package/src/Cache/Redis.ts

@@ -0,0 +1,89 @@
+import { RedisClientType, RedisClusterType, createCluster, createClient } from 'redis'
+
+import { CacheConfig } from './types.js'
+import AsyncSingleton from '../Util/AsyncSingleton.js'
+/**
+ * Represents a Redis cache connection class.
+ */
+export default class Redis {
+  private static singleton = new AsyncSingleton<
+    RedisClientType | RedisClusterType,
+    CacheConfig<'redis'>
+  >(Redis.connectionFactory, async c => c.isOpen)
+
+  /**
+   * A private static property that holds a reference to the redis.createClient function.
+   * This property is used to create client.
+   */
+  private static ClientFactory = createClient
+
+  /**
+   * A private static property that references the createCluster function.
+   * This property can be used to create clusters within the class.
+   */
+  private static ClusterFactory = createCluster
+
+  public static connection(
+    config: CacheConfig<'redis'>
+  ): Promise<RedisClientType | RedisClusterType> {
+    return Redis.singleton.instance(config)
+  }
+
+  private static async connectionFactory(
+    config: CacheConfig<'redis'>
+  ): Promise<RedisClientType | RedisClusterType> {
+    if (config.clusterMode) return Redis.redisClusterConnection(config)
+    else return Redis.redisClientConnection(config)
+  }
+
+  /**
+   * Establishes a connection to a Redis client based on the provided configuration
+   * and holds it for reusability. If connection is detected closed, new connection is
+   * initialized and established.
+   * @param {CacheConfig<'redis'>} config - The configuration object for connecting to the Redis client.
+   * @returns {Promise<RedisClientType>} A promise that resolves to the Redis client connection.
+   */
+  private static async redisClientConnection(
+    config: CacheConfig<'redis'>
+  ): Promise<RedisClientType> {
+    console.debug('Starting remote client cache connection')
+    const connection = Redis.ClientFactory({
+      username: config.username,
+      ...(config.password ? { password: config.password } : {}),
+      disableOfflineQueue: true,
+      socket: {
+        host: config.hostname,
+        tls: config.enableTLS,
+        connectTimeout: 10000,
+      },
+    })
+    await connection.connect()
+
+    return connection as any
+  }
+
+  private static async redisClusterConnection(
+    config: CacheConfig<'redis'>
+  ): Promise<RedisClusterType> {
+    console.debug('Starting remote cluster cache connection')
+    const connection = Redis.ClusterFactory({
+      defaults: {
+        username: config.username,
+        ...(config.password ? { password: config.password } : {}),
+        socket: {
+          tls: config.enableTLS,
+          connectTimeout: 10000,
+        },
+      },
+      rootNodes: [
+        {
+          url: `redis://${config.username}:${config.username}@${config.hostname}:6379`,
+          disableOfflineQueue: true,
+        },
+      ],
+    })
+    await connection.connect()
+
+    return connection as any
+  }
+}

package/src/Cache/types.ts

@@ -0,0 +1,33 @@
+import Redis from './Redis.js'
+
+/**
+ * Defines a type alias for specifying the cache type as 'redis'.
+ */
+export type CacheType = 'redis'
+
+/**
+ * Defines a CacheClass type that has a 'redis' property which is a constructor function
+ * that takes in any number of arguments and returns an instance of Redis.
+ */
+export type CacheClass = {
+  redis: new (...args: any[]) => Redis
+}
+
+/**
+ * Represents the base configuration for a cache, including host, username, password, and TLS settings.
+ */
+export type CacheBaseConfig = {
+  hostname: string
+  username: string
+  password?: string
+  enableTLS: boolean
+  clusterMode?: boolean
+}
+
+/**
+ * Defines a CacheConfig type that extends CacheBaseConfig and includes a specific cache type.
+ * @template S - The specific cache type to be included in the CacheConfig.
+ * @extends CacheBaseConfig
+ * @property {S} type - The specific cache type included in the CacheConfig.
+ */
+export type CacheConfig<S extends CacheType> = CacheBaseConfig & { type: S }