@squiz/db-lib 1.76.0 → 1.77.1

package/lib/externalized/ExternalizedDynamoDbRepository.d.ts

@@ -0,0 +1,166 @@
+/*!
+ * @file ExternalizedDynamoDbRepository.ts
+ * @description This file contains the ExternalizedDynamoDbRepository class, which is used to store and retrieve externalized items from DynamoDB and S3.
+ * @author Dean Heffernan
+ * @copyright 2025 Squiz
+ */
+import { AbstractDynamoDbRepository, EntityDefinition, QueryOptions } from '../dynamodb/AbstractDynamoDbRepository';
+import { DynamoDbManager, Transaction } from '../dynamodb/DynamoDbManager';
+import { S3ExternalStorage, S3StorageLocation } from '../s3/S3ExternalStorage';
+/**
+ * The ExternalizedDynamoDbRepository class is used to store and retrieve externalized items from DynamoDB and S3.
+ * @class ExternalizedDynamoDbRepository
+ * @extends {AbstractDynamoDbRepository<SHAPE, DATA_CLASS>}
+ * @param {string} tableName - The name of the DynamoDB table to use for storing externalized items.
+ * @param {ContentDynamodbDbManager} dbManager - The DynamoDB database manager to use for storing externalized items.
+ * @param {string} entityName - The name of the entity to store externalized items for.
+ * @param {EntityDefinition} entityDefinition - The entity definition to use for storing externalized items.
+ * @param {DATA_CLASS} classRef - The class to use for storing externalized items.
+ * @param {S3ExternalStorage} storage - The S3 storage to use for storing externalized items.
+ * @returns {ExternalizedDynamoDbRepository} A new instance of the ExternalizedDynamoDbRepository class.
+ */
+export declare abstract class ExternalizedDynamoDbRepository<SHAPE extends object, DATA_CLASS extends SHAPE & {
+    storageLocation?: S3StorageLocation;
+}> extends AbstractDynamoDbRepository<SHAPE, DATA_CLASS> {
+    private readonly storage;
+    /**
+     * Creates a new instance of the ExternalizedDynamoDbRepository class.
+     * @constructor
+     * @param {string} tableName - The name of the DynamoDB table to use for storing externalized items.
+     * @param {DynamoDbManager} dbManager - The DynamoDB database manager to use for storing externalized items.
+     * @param {string} entityName - The name of the entity to store externalized items for.
+     * @param {EntityDefinition} entityDefinition - The entity definition to use for storing externalized items.
+     * @param {DATA_CLASS} classRef - The class to use for storing externalized items.
+     * @param {S3ExternalStorage} storage - The S3 storage to use for storing externalized items.
+     * @returns {ExternalizedDynamoDbRepository} A new instance of the ExternalizedDynamoDbRepository class.
+     */
+    constructor(tableName: string, dbManager: DynamoDbManager<any>, entityName: string, entityDefinition: EntityDefinition, classRef: {
+        new (data?: Record<string, unknown>): DATA_CLASS;
+    }, storage: S3ExternalStorage);
+    /**
+     * Removes storageLocation from the response.
+     * storageLocation is an internal S3 storage implementation detail that should never be exposed to API consumers.
+     * @param {DATA_CLASS} item - The item to process.
+     * @returns {DATA_CLASS} The item without storageLocation.
+     */
+    private removeStorageLocationFromResponse;
+    /**
+     * Creates a new item in the repository.
+     * If the item exceeds DynamoDB's size limit, it will automatically externalize the content to S3.
+     * @param {DATA_CLASS} value - The value to create the item for.
+     * @param {Transaction} transaction - The transaction to use for creating the item.
+     * @param {Partial<SHAPE>} additionalValue - Additional value to use for creating the item.
+     * @param {Object} options - The options to use for creating the item.
+     * @returns {Promise<DATA_CLASS>} A promise that resolves to the created item.
+     */
+    createItem(value: DATA_CLASS, transaction?: Transaction, additionalValue?: Partial<SHAPE>, options?: {
+        overrideExisting?: boolean;
+    }): Promise<DATA_CLASS>;
+    /**
+     * Internal method to create an item in the repository.
+     * @param {DATA_CLASS} value - The value to create the item for.
+     * @param {Transaction} transaction - The transaction to use for creating the item.
+     * @param {Partial<SHAPE>} additionalValue - Additional value to use for creating the item.
+     * @param {Object} options - The options to use for creating the item.
+     * @returns {Promise<DATA_CLASS>} A promise that resolves to the created item.
+     */
+    private createItemInternal;
+    /**
+     * Updates an item in the repository.
+     * If the item exceeds DynamoDB's size limit, it will automatically externalize the content to S3.
+     * @param {Partial<SHAPE>} value - The value to update the item with.
+     * @returns {Promise<DATA_CLASS | undefined>} A promise that resolves to the updated item.
+     */
+    updateItem(value: Partial<SHAPE>): Promise<DATA_CLASS | undefined>;
+    /**
+     * Internal method to update an item in the repository.
+     * @param {Partial<SHAPE>} value - The value to update the item with.
+     * @returns {Promise<DATA_CLASS | undefined>} A promise that resolves to the updated item.
+     */
+    private updateItemInternal;
+    /**
+     * Gets an item from the repository.
+     * @param {Partial<SHAPE>} item - The item to get.
+     * @returns {Promise<DATA_CLASS | undefined>} A promise that resolves to the item.
+     */
+    getItem(item: Partial<SHAPE>): Promise<DATA_CLASS | undefined>;
+    /**
+     * Gets items from the repository.
+     * @param {Partial<SHAPE>[]} items - The items to get.
+     * @returns {Promise<DATA_CLASS[]>} A promise that resolves to the items.
+     */
+    getItems(items: Partial<SHAPE>[]): Promise<DATA_CLASS[]>;
+    /**
+     * Queries items from the repository.
+     * @param {Partial<SHAPE>} item - The item to query.
+     * @param {QueryOptions} options - The options to use for querying the items.
+     * @returns {Promise<DATA_CLASS[]>} A promise that resolves to the items.
+     */
+    queryItems(item: Partial<SHAPE>, options?: QueryOptions): Promise<DATA_CLASS[]>;
+    /**
+     * Deletes an item from the repository.
+     * @param {Partial<SHAPE>} partialItem - The item to delete.
+     * @param {Transaction} transaction - The transaction to use for deleting the item.
+     * @returns {Promise<number>} A promise that resolves to the number of items deleted.
+     */
+    deleteItem(partialItem: Partial<SHAPE>, transaction?: Transaction): Promise<number>;
+    /**
+     * Deletes items from the repository.
+     * @param {Partial<SHAPE>[]} items - The items to delete.
+     * @returns {Promise<void>} A promise that resolves when the items are deleted.
+     */
+    deleteItems(items: Partial<SHAPE>[]): Promise<void>;
+    /**
+     * Prepares a value for storage by externalizing large content to S3.
+     * @param {DATA_CLASS} value - The value to prepare for storage.
+     * @returns {Promise<DATA_CLASS>} A promise that resolves to the prepared value for DynamoDB.
+     * @throws {Error} If S3 storage is not configured or if saving to S3 fails.
+     */
+    prepareValueForStorage(value: DATA_CLASS): Promise<DATA_CLASS>;
+    /**
+     * Extracts only the key field values from an object based on the entity definition.
+     * Large content fields (defined in fieldsAsJsonString) are set to empty values.
+     * All other fields (key fields and small metadata) are preserved.
+     *
+     * @param {Record<string, unknown>} obj - The source object to extract key fields from.
+     * @returns {Record<string, unknown>} An object containing only the key field values.
+     */
+    protected getKeyFieldsValues(obj: Record<string, unknown>): Record<string, unknown>;
+    /**
+     * Override parent's hydrateItem to preserve storageLocation
+     * The parent's hydrateItem creates a new instance which strips storageLocation
+     */
+    protected hydrateItem(item: Record<string, unknown>): DATA_CLASS;
+    /**
+     * Checks if content is actually stored in S3 by examining if large content fields are empty.
+     * When content is externalized to S3, fieldsAsJsonString fields are set to empty objects/arrays.
+     * @param {DATA_CLASS} item - The item to check.
+     * @returns {boolean} True if content is in S3, false if content is in DynamoDB.
+     */
+    private isContentInS3;
+    /**
+     * Hydrates a record from external storage.
+     * @param {DATA_CLASS} record - The record to hydrate.
+     * @returns {Promise<DATA_CLASS | undefined>} A promise that resolves to the hydrated record (without storageLocation).
+     */
+    private hydrateFromExternalStorage;
+    /**
+     * Fetches the stored location of an item.
+     * @param {Partial<SHAPE>} partialItem - The item to fetch the stored location for.
+     * @returns {Promise<S3StorageLocation | undefined>} A promise that resolves to the stored location.
+     */
+    private fetchStoredLocation;
+    /**
+     * Check if the error is due to DynamoDB item size limit being exceeded.
+     * @param {unknown} error - The error to check.
+     * @returns {boolean} True if the error is due to DynamoDB item size limit being exceeded, false otherwise.
+     */
+    protected isDynamoItemSizeLimitError(error: unknown): boolean;
+    /**
+     * Check if the message contains the DynamoDB size keyword.
+     * @param {string} message - The message to check.
+     * @returns {boolean} True if the message contains the DynamoDB size keyword, false otherwise.
+     */
+    private hasDynamoSizeKeyword;
+}
+//# sourceMappingURL=ExternalizedDynamoDbRepository.d.ts.map

package/lib/externalized/ExternalizedDynamoDbRepository.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ExternalizedDynamoDbRepository.d.ts","sourceRoot":"","sources":["../../src/externalized/ExternalizedDynamoDbRepository.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAOH,OAAO,EAAE,0BAA0B,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,wCAAwC,CAAC;AACpH,OAAO,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAG3E,OAAO,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAE/E;;;;;;;;;;;GAWG;AACH,8BAAsB,8BAA8B,CAClD,KAAK,SAAS,MAAM,EACpB,UAAU,SAAS,KAAK,GAAG;IAAE,eAAe,CAAC,EAAE,iBAAiB,CAAA;CAAE,CAClE,SAAQ,0BAA0B,CAAC,KAAK,EAAE,UAAU,CAAC;IAkBnD,OAAO,CAAC,QAAQ,CAAC,OAAO;IAjB1B;;;;;;;;;;OAUG;gBAED,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,eAAe,CAAC,GAAG,CAAC,EAC/B,UAAU,EAAE,MAAM,EAClB,gBAAgB,EAAE,gBAAgB,EAClC,QAAQ,EAAE;QAAE,KAAK,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,UAAU,CAAA;KAAE,EAC7C,OAAO,EAAE,iBAAiB;IAK7C;;;;;OAKG;IACH,OAAO,CAAC,iCAAiC;IAQzC;;;;;;;;OAQG;IACU,UAAU,CACrB,KAAK,EAAE,UAAU,EACjB,WAAW,GAAE,WAAgB,EAC7B,eAAe,GAAE,OAAO,CAAC,KAAK,CAAM,EACpC,OAAO,GAAE;QAAE,gBAAgB,CAAC,EAAE,OAAO,CAAA;KAAgC,GACpE,OAAO,CAAC,UAAU,CAAC;IAkBtB;;;;;;;OAOG;YACW,kBAAkB;IAkGhC;;;;;OAKG;IACU,UAAU,CAAC,KAAK,EAAE,OAAO,CAAC,KAAK,CAAC,GAAG,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC;IAkB/E;;;;OAIG;YACW,kBAAkB;IA0HhC;;;;OAIG;IACU,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,KAAK,CAAC,GAAG,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC;IAK3E;;;;OAIG;IACU,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC,KAAK,CAAC,EAAE,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IAKrE;;;;;OAKG;IACU,UAAU,CAAC,IAAI,EAAE,OAAO,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IAK5F;;;;;OAKG;IACU,UAAU,CAAC,WAAW,EAAE,OAAO,CAAC,KAAK,CAAC,EAAE,WAAW,GAAE,WAAgB,GAAG,OAAO,CAAC,MAAM,CAAC;IASpG;;;;OAIG;IACU,WAAW,CAAC,KAAK,EAAE,OAAO,CAAC,KAAK,CAAC,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAMhE;;;;;OAKG;IACU,sBAAsB,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC;IA6B3E;;;;;;;OAOG;IACH,SAAS,CAAC,kBAAkB,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IA6BnF;;;OAGG;IACH,SAAS,CAAC,WAAW,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,UAAU;IAehE;;;;;OAKG;IACH,OAAO,CAAC,aAAa;IAmBrB;;;;OAIG;YACW,0BAA0B;IAUxC;;;;OAIG;YACW,mBAAmB;IAmBjC;;;;OAIG;IACH,SAAS,CAAC,0BAA0B,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO;IA8B7D;;;;OAIG;IACH,OAAO,CAAC,oBAAoB;CAa7B"}