@qrvey/data-persistence

Installation

You can install the package using npm or yarn:

npm install @qrvey/data-persistence

Or with yarn:

yarn add @qrvey/data-persistence

Peer Dependencies

This package has the following peer dependencies:

• @aws-sdk/client-dynamodb (v3.x) and @aws-sdk/lib-dynamodb (v3.x) for interacting with DynamoDB.
• pg (v8.x) and pg-format (v1.x) for interacting with PostgreSQL databases.

Concepts

CrudService:

This class serves as the foundation for interacting with your database. It exposes methods for performing CRUD operations on entities (data objects).

Basic Functions

• create(entity: T): Creates a new entity in the database.
• find(options: IFindOptions): Retrieves entities based on specified options (filters, sorting, pagination).
• findAll(options: IFindOptions): Retrieves all entities based on specified options, this function make an internal pagination to load all data.
• findItem (options: IFindOptions): Fetches a single entity by a specified filter.
• update(filters: IFilter[], data: Partial<T>): Updates entities matching the provided filters with the given data.
• remove(filters: IFilter[]): Deletes entities that satisfy the specified filters.

Helper Functions:

These methods assist in constructing filters, query indexes, and sorting criteria for use within your CRUD operations.

• buildFilter(attribute: string, value: string, operator = 'EQUAL'): Creates a filter object for a specific attribute.
• buildQueryIndex(indexName: string, columns: string[]): Constructs a query index for efficient data retrieval.
• buildSort(column: string, direction: SortDirection): Generates a sorting object for ordering results.

CrudSchema:

This interface defines the structure of a database table. It allows you to specify the table name, columns, and optional schema and pool usage.

Properties:

• static table: string | ITableName: This property defines the name of the database table that the CrudService will interact with. It can be a simple string (e.g., "users") or an object implementing the ITableName interface (discussed later).

• static columns: ITableColumns: This property represents an array of column definitions for the table. It should conform to the ITableColumns interface (discussed later). Each column definition likely specifies details like column name, data type, and potentially constraints.

• static usePool?: boolean = false: This optional boolean property (defaulting to false) indicates whether to use a connection pool for database interactions. Setting it to true can improve performance for frequent queries.

• static schema: string | null = null: This optional string property allows specifying the schema name (if applicable) where the table resides. It can be a string (e.g., "public") or null if the default schema is used.

Supported Filter Operators

This library provides a set of filter operators for performing comparisons on entity attributes within your database. These operators allow you to construct filters for your CRUD operations.

Available Operators

The FilterOperator enum defines the following operators:

• EQUAL.
• NOT_EQUAL.
• CONTAINS: This operator checks if the attribute value contains the specified string as a substring. -NOT_CONTAINS: This operator checks if the attribute value does not contain the specified string as a substring.
• GREATER_THAN.
• GREATER_THAN_EQUAL.
• LESS_THAN.
• LESS_THAN_EQUAL.
• IN: This operator checks if the attribute value is present within a specified list of values.
• STARTS_WITH: This operator checks if the attribute value starts with the provided string. It uses parameterized query syntax for security.
• EXIST: This operator verifies whether the attribute value exists. In PostgreSQL, it validates whether the attribute value is NOT null when the attribute is defined in the table columns.
• NOT_EXIST: This operator checks if the attribute value does not exist in the document. In PostgreSQL, it validates whether the attribute value is null when the attribute is defined in the table columns.
• BETWEEN: This operator checks if the attribute value is within a specified range.