@worktif/purews
Version:
Work TIF TypeScript-based AWS infrastructure toolkit featuring DynamoDB integration, AppSync support, SES functionality, and GraphQL capabilities with comprehensive audit logging and AWS Signature V4 authentication.
165 lines (164 loc) • 10.3 kB
TypeScript
import 'reflect-metadata';
import { BeforeInstance, LoggerInterface, Maybe, QueryByAttrOptions } from '@worktif/utils';
import { Logger } from '@aws-lambda-powertools/logger';
import { DeleteCommandInput, DynamoDBDocument, GetCommandInput, NativeAttributeValue, PutCommandInput, QueryCommandInput, ScanCommandInput, UpdateCommandInput } from '@aws-sdk/lib-dynamodb';
import { EnvConfigPurews } from '@config/env.config.purews';
import { DynamoEntity } from './dynamo.db.types';
export declare abstract class DynamoDbService implements LoggerInterface {
protected envConfig: EnvConfigPurews;
/**
* Represents the name of a database table.
*
* @typedef {string} tableName
*/
abstract tableName: string;
/**
* Represents an instance of a logger.
*
* @typedef {Object} LoggerInstance
* @property {string} serviceName - The name of the service associated with the logger instance.
*
* @param {Object} config - The configuration for the logger instance.
* @param {string} config.serviceName - The name of the service associated with the logger instance.
* @returns {LoggerInstance} An instance of the logger.
*
* @example
* const loggerInstance = logger({ serviceName: 'integrations/zuoraHttpClient' });
*/
loggerInstance: Logger;
/**
* Represents a private property holding an instance of DynamoDBDocumentClient.
*/
protected dynamoDB: DynamoDBDocument;
/**
* Represents the DynamoDB client to interact with the DynamoDB table using a document interface.
* @typedef {Object} DynamoDBDocumentClient
*/
private dynamoDBClient;
constructor(envConfig: EnvConfigPurews);
/**
* Creates update parameters for updating an item in a DynamoDB table.
*
* @param {Partial<DynamoEntity<T>>} payload - The partial DynamoDB entity containing the attributes to update. Must include the `id` property.
* @param {(keyof DynamoEntity<T>)[]} [listAttributes] - An optional list of attributes to include in the update expression.
* @param {BeforeInstance} [beforeInstance] - Optional instance for logging or performing actions before creating the update parameters.
* @return {Promise<UpdateCommandInput>} Returns a promise that resolves to the update parameters for a DynamoDB UpdateCommand.
* @throws {CustomException} Throws an internal error exception if the `id` property is missing in the payload.
*/
createUpdateParams<T>(payload: Partial<DynamoEntity<T>>, listAttributes?: (keyof DynamoEntity<T>)[], beforeInstance?: BeforeInstance): Promise<UpdateCommandInput>;
/**
* Queries records from a DynamoDB table based on the specified attribute(s) and options.
*
* @param {QueryByAttrOptions} options - Object containing parameters for the query operation:
* - `tableName` {string}: The name of the DynamoDB table to query.
* - `attributeName` {string | string[]}: The attribute name or array of attribute names to query against.
* - `attributeValue` {any | any[]}: The value or array of values corresponding to the attribute names.
* - `indexName` {string} [optional]: The name of the secondary index to use for the query, if any.
* @param {BeforeInstance} [beforeInstance] - Optional instance used for logging and pre-processing.
* @return {Promise<Maybe<T[]>>} - A promise that resolves to an array of records that match the query, or `null` or `undefined` if there's no match.
*/
queryByAttribute<T>({ tableName, attributeName, attributeValue, indexName }: QueryByAttrOptions, beforeInstance?: BeforeInstance): Promise<Maybe<T[]>>;
/**
* Queries a DynamoDB table based on the provided input parameters and retrieves all matching items.
* If pagination exists, it handles the continuation for fetching remaining items recursively.
*
* @param {QueryCommandInput} queryCommandInput - The input parameters for the query, including table name,
* key conditions, filter expressions, and other query options.
* @param {Maybe<Record<string, NativeAttributeValue>>} [exclusiveStartKey=void 0] - The key indicating where to start in paginated results.
* If it's undefined,*/
queryAll<T>(queryCommandInput: QueryCommandInput, exclusiveStartKey?: Maybe<Record<string, NativeAttributeValue>>, beforeInstance?: BeforeInstance): Promise<Maybe<T[]>>;
/**
* Retrieves an item from the DynamoDB table based on the provided ID.
*
* @param {string} id - The unique identifier of the item to be fetched.
* @param {BeforeInstance} [beforeInstance] - Optional parameter to include any additional operations or hooks before retrieving the item.
* @return {Promise<Maybe<T>>} A promise that resolves to the retrieved item if found, or `undefined` if the item does not exist.
*/
get<T>(id: string, beforeInstance?: BeforeInstance): Promise<Maybe<T>>;
/**
* Deletes a single item in the DynamoDB table based on the provided payload.
*
* @param {Partial<T>} payload The partial entity object that identifies the item to be deleted.
* @param {BeforeInstance} [beforeInstance] Optional before instance used for logging or other pre-processing tasks.
* @return {Promise<Maybe<Partial<T>>>} A promise resolving to the deleted payload object or undefined.
*/
delete<T extends DynamoEntity<object>>(payload: Partial<T>, beforeInstance?: BeforeInstance): Promise<Maybe<Partial<T>>>;
/**
* Inserts or replaces a single item in the DynamoDB table.
*
* @param {Partial<DynamoEntity<T>>} payload - The partial payload of the DynamoDB entity to be inserted or replaced.
**/
put<T extends object>(payload: Partial<DynamoEntity<T>>, beforeInstance?: BeforeInstance): Promise<Maybe<T>>;
/**
* Executes a scan operation on a DynamoDB table and retrieves items.
*
* @param {BeforeInstance} [beforeInstance] - Optional parameter to handle pre-operation logic, such as logging or additional processing.
* @return {Promise<Maybe<T[]>>} - A promise that resolves to an array of scanned items, or an empty value if no items are found.
*/
scanFinder<T extends object>(beforeInstance?: BeforeInstance): Promise<Maybe<T[]>>;
/**
* Updates a DynamoDB item with the provided payload and optional pre-processing.
*
* @param {Partial<DynamoEntity<T>>} payload - The partial payload used to update the DynamoDB item. It contains the attributes to be updated.
* @param {BeforeInstance} [beforeInstance] - Optional instance for pre-update processing or validation.
* @return {Promise<Maybe<T>>} A promise that resolves to the updated DynamoDB item or undefined if no attributes are returned.
*/
update<T extends DynamoEntity<object>>(payload: Partial<DynamoEntity<T>>, beforeInstance?: BeforeInstance): Promise<Maybe<T>>;
/**
* Retrieves a list of batch items by their corresponding ID list.
*
* @param {string[]} merchantIdList - An array of merchant IDs to query in batch.
* @param {string} fieldName - The name of the field to use as the key for the batch query.
* @param {BeforeInstance} [beforeInstance] - Optional instance for pre-processing or logging actions.
* @return {Promise<Maybe<T>[]>} A promise that resolves with an array of results, or an empty array if none are found.
*/
protected getBatchListByIdList<T>(merchantIdList: string[], fieldName: string, beforeInstance?: BeforeInstance): Promise<Maybe<T>[]>;
/**
* Executes a query operation on DynamoDB based on the provided query parameters and returns the result.
*
* @param {QueryCommandInput} queryCommandInput - The input parameters for the DynamoDB query operation.
* @param {Maybe<Record<string, NativeAttributeValue>>} [exclusiveStartKey=void 0] - (Optional) The exclusive start key for continuing pagination.
* @param {BeforeInstance} [beforeInstance] - (Optional) An instance to handle logging or actions before/after the operation.
* @return {Promise<T>} A promise that resolves to the result of the query operation.
*/
private query;
/**
* Generates an expression for updating attributes in a payload object.
*
* @param {Partial<T>} payload - The partial payload object to update.
* @param {Array<keyof T>} [listAttributes] - Optional list of attributes that should be treated as lists.
* @returns {{ updateExpression: string; expressionAttributeValues: Record<string, unknown> }} - Object containing the update expression and expression attribute values.
*/
static generateExpressionForUpdate<T>(payload: Partial<DynamoEntity<T>>, listAttributes?: (keyof DynamoEntity<T>)[]): {
updateExpression: string;
expressionAttributeValues: Record<string, unknown>;
};
/**
* Creates the parameters required for the 'get' command.
*
* @param {string} id - The identifier for the record to retrieve.
* @return {GetCommandInput} The parameters object for the 'get' command.
*/
protected createGetParams(id: string): GetCommandInput;
/**
* Creates the PutCommandInput parameters for inserting an item into a table.
*
* @param {Object} payload - The data object to be inserted into the table.
* @return {PutCommandInput} - The PutCommandInput object containing the table name, item data, and other attributes.
*/
protected createPutParams<T extends object>(payload: Partial<DynamoEntity<T>>): PutCommandInput;
/**
* Creates ScanCommandInput object with provided payload.
*
* @param {Partial<DynamoEntity<T>>} payload - The payload to be used for creating ScanCommandInput.
* @return {ScanCommandInput} - The ScanCommandInput object with the TableName set.
*/
protected createScanParams(): ScanCommandInput;
/**
* Creates the parameters required for a DynamoDB delete command.
*
* @param payload A partial object of type T that represents the key attributes to identify the item to delete.
* @return The parameters to use with a DynamoDB DeleteCommandInput, including the table name and key.
*/
protected createDeleteParams<T extends DynamoEntity<object>>(payload: Partial<T>): DeleteCommandInput;
}