@squiz/db-lib 1.76.0 → 1.77.0

package/lib/externalized/ExternalizedDynamoDbRepository.spec.js

@@ -0,0 +1,218 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const ExternalizedDynamoDbRepository_1 = require("./ExternalizedDynamoDbRepository");
+class TestItem {
+    constructor(input = {}) {
+        this.id = input.id || '';
+        this.name = input.name || '';
+        this.data = input.data || [];
+        // Note: storageLocation is intentionally not set from input to simulate model stripping it
+    }
+}
+// Test entity definition
+const testEntityDefinition = {
+    keys: {
+        pk: {
+            attributeName: 'pk',
+            format: 'ITEM#${id}',
+        },
+        sk: {
+            attributeName: 'sk',
+            format: 'ITEM#${id}',
+        },
+    },
+    indexes: {},
+    fieldsAsJsonString: ['data'],
+};
+// Concrete test repository
+class TestRepo extends ExternalizedDynamoDbRepository_1.ExternalizedDynamoDbRepository {
+    constructor(dbManager, storage, overrides = {}) {
+        super('test-table', dbManager, 'test_item', { ...testEntityDefinition, ...overrides }, TestItem, storage);
+    }
+    // Override updateItem to allow mocking super.updateItem
+    async updateItem(value) {
+        if (this.mockSuperUpdateItem) {
+            // Use mock if provided
+            const previousLocation = await this.fetchStoredLocation(value);
+            const updatedItem = await this.mockSuperUpdateItem(value);
+            if (!updatedItem) {
+                return undefined;
+            }
+            const newLocation = updatedItem.storageLocation;
+            if (previousLocation && previousLocation.key !== (newLocation === null || newLocation === void 0 ? void 0 : newLocation.key)) {
+                await this.storage.delete(previousLocation);
+            }
+            return updatedItem;
+        }
+        return super.updateItem(value);
+    }
+}
+const createDbManager = (clientOverrides = {}) => ({
+    client: {
+        get: jest.fn(),
+        put: jest.fn(),
+        delete: jest.fn(),
+        update: jest.fn(),
+        ...clientOverrides,
+    },
+    repositories: {},
+    executeInTransaction: async (fn) => fn({}),
+    addWriteTransactionItem: jest.fn(),
+});
+const createStorage = () => ({
+    save: jest.fn(),
+    load: jest.fn(),
+    delete: jest.fn(),
+});
+const createTestItem = (overrides = {}) => {
+    const item = new TestItem({
+        id: 'item-1',
+        name: 'Test',
+        data: [{ key: 'sample', value: { main: [] } }],
+        ...overrides,
+    });
+    return item;
+};
+describe('ExternalizedDynamoDbRepository', () => {
+    it('externalizes data to S3 when prepareValueForStorage is called', async () => {
+        const storage = {
+            ...createStorage(),
+            save: jest.fn().mockResolvedValue({ location: { type: 's3', key: 'item-key' }, size: 500 }),
+        };
+        const repo = new TestRepo(createDbManager(), storage);
+        const item = createTestItem();
+        const storedValue = await repo.prepareValueForStorage(item);
+        expect(storage.save).toHaveBeenCalled();
+        // storedValue is a minimal payload - original item is NOT mutated
+        expect(storedValue.data).toEqual([]);
+        expect(storedValue.storageLocation).toEqual({ type: 's3', key: 'item-key' });
+    });
+    it('creates item with storageLocation preserved', async () => {
+        const client = createDbManager().client;
+        client.put.mockResolvedValue({});
+        const storage = {
+            ...createStorage(),
+            save: jest.fn().mockResolvedValue({ location: { type: 's3', key: 'item-key' }, size: 500 }),
+        };
+        const repo = new TestRepo({ client }, storage);
+        const item = createTestItem();
+        // Use prepareValueForStorage to externalize data and set storageLocation
+        const preparedItem = await repo.prepareValueForStorage(item);
+        // Verify the prepared value has minimal payload (empty data)
+        expect(preparedItem.data).toEqual([]);
+        expect(preparedItem.storageLocation).toEqual({ type: 's3', key: 'item-key' });
+        // Original item should NOT be mutated
+        expect(item.storageLocation).toBeUndefined();
+    });
+    it('loads payload from external storage when storageLocation is set', async () => {
+        const storage = createStorage();
+        const fullData = {
+            id: 'item-1',
+            name: 'From S3',
+            data: [{ key: 'sample', value: { main: [] } }],
+        };
+        storage.load.mockResolvedValue(fullData);
+        const repo = new TestRepo(createDbManager({ get: jest.fn() }), storage);
+        const result = await repo.hydrateFromExternalStorage({
+            id: 'item-1',
+            name: 'Placeholder',
+            data: [],
+            storageLocation: { type: 's3', key: 'item-key' },
+        });
+        expect(storage.load).toHaveBeenCalledWith({ type: 's3', key: 'item-key' });
+        expect(result === null || result === void 0 ? void 0 : result.name).toBe('From S3');
+        expect(result === null || result === void 0 ? void 0 : result.data).toEqual([{ key: 'sample', value: { main: [] } }]);
+    });
+    it('deletes externalized payloads when deleting items', async () => {
+        const client = createDbManager({
+            get: jest.fn().mockResolvedValue({ Item: { storageLocation: { type: 's3', key: 'item-key' } } }),
+            delete: jest.fn().mockResolvedValue({}),
+        }).client;
+        const storage = createStorage();
+        const repo = new TestRepo({ client }, storage);
+        await repo.deleteItem({ id: 'item-1' });
+        expect(storage.delete).toHaveBeenCalledWith({ type: 's3', key: 'item-key' });
+    });
+    it('returns inline data when no storageLocation is present', async () => {
+        const storage = createStorage();
+        const repo = new TestRepo(createDbManager({ get: jest.fn() }), storage);
+        const inlineRecord = {
+            id: 'item-1',
+            name: 'Inline Item',
+            data: [{ key: 'sample', value: { main: [] } }],
+        };
+        const result = await repo.hydrateFromExternalStorage(inlineRecord);
+        expect(storage.load).not.toHaveBeenCalled();
+        expect(result).toBeDefined();
+        expect(result === null || result === void 0 ? void 0 : result.name).toBe('Inline Item');
+        expect(result === null || result === void 0 ? void 0 : result.data).toEqual([{ key: 'sample', value: { main: [] } }]);
+    });
+    it('cleans up old S3 file when updating with new storageLocation', async () => {
+        const oldLocation = { type: 's3', key: 'old-key' };
+        const newLocation = { type: 's3', key: 'new-key' };
+        const client = createDbManager({
+            get: jest.fn().mockResolvedValue({
+                Item: {
+                    id: 'item-1',
+                    name: 'Test',
+                    storageLocation: oldLocation,
+                },
+            }),
+            update: jest.fn().mockResolvedValue({
+                Attributes: {
+                    id: 'item-1',
+                    name: 'Updated',
+                    storageLocation: newLocation,
+                },
+            }),
+        }).client;
+        const storage = createStorage();
+        const repo = new TestRepo({ client }, storage);
+        // Update without storageLocation (it will be fetched from DynamoDB)
+        const updateValue = {
+            id: 'item-1',
+            name: 'Updated',
+        };
+        // Create an updated item with the new storageLocation
+        const updatedItem = createTestItem({ id: 'item-1', name: 'Updated' });
+        updatedItem.storageLocation = newLocation;
+        // Mock super.updateItem using the custom mock hook
+        repo.mockSuperUpdateItem = jest.fn().mockResolvedValue(updatedItem);
+        await repo.updateItem(updateValue);
+        expect(storage.delete).toHaveBeenCalledWith(oldLocation);
+    });
+    it('does not delete S3 file when storageLocation is unchanged', async () => {
+        const location = { type: 's3', key: 'same-key' };
+        const client = createDbManager({
+            get: jest.fn().mockResolvedValue({
+                Item: {
+                    id: 'item-1',
+                    name: 'Test',
+                    storageLocation: location,
+                },
+            }),
+            update: jest.fn().mockResolvedValue({
+                Attributes: {
+                    id: 'item-1',
+                    name: 'Updated',
+                    storageLocation: location,
+                },
+            }),
+        }).client;
+        const storage = createStorage();
+        const repo = new TestRepo({ client }, storage);
+        // Update without storageLocation (it will be fetched from DynamoDB)
+        const updateValue = {
+            id: 'item-1',
+            name: 'Updated',
+        };
+        // Create an updated item with the same storageLocation
+        const updatedItem = createTestItem({ id: 'item-1', name: 'Updated' });
+        updatedItem.storageLocation = location;
+        // Mock super.updateItem using the custom mock hook
+        repo.mockSuperUpdateItem = jest.fn().mockResolvedValue(updatedItem);
+        await repo.updateItem(updateValue);
+        expect(storage.delete).not.toHaveBeenCalled();
+    });
+});
+//# sourceMappingURL=ExternalizedDynamoDbRepository.spec.js.map

package/lib/externalized/ExternalizedDynamoDbRepository.spec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ExternalizedDynamoDbRepository.spec.js","sourceRoot":"","sources":["../../src/externalized/ExternalizedDynamoDbRepository.spec.ts"],"names":[],"mappings":"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"}

package/lib/index.d.ts

@@ -12,4 +12,6 @@ export * from './error/MissingKeyValuesError';
 export * from './error/InvalidDbSchemaError';
 export * from './PostgresErrorCodes';
 export { Pool, PoolClient } from 'pg';
+export * from './s3/S3ExternalStorage';
+export * from './externalized/ExternalizedDynamoDbRepository';
 //# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,sBAAsB,CAAC;AACrC,cAAc,qBAAqB,CAAC;AACpC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,uCAAuC,CAAC;AACtD,cAAc,+BAA+B,CAAC;AAC9C,cAAc,YAAY,CAAC;AAC3B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,qBAAqB,CAAC;AACpC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,0BAA0B,CAAC;AACzC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,8BAA8B,CAAC;AAG7C,cAAc,sBAAsB,CAAC;AAErC,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,IAAI,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,sBAAsB,CAAC;AACrC,cAAc,qBAAqB,CAAC;AACpC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,uCAAuC,CAAC;AACtD,cAAc,+BAA+B,CAAC;AAC9C,cAAc,YAAY,CAAC;AAC3B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,qBAAqB,CAAC;AACpC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,0BAA0B,CAAC;AACzC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,8BAA8B,CAAC;AAG7C,cAAc,sBAAsB,CAAC;AAErC,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,IAAI,CAAC;AAGtC,cAAc,wBAAwB,CAAC;AACvC,cAAc,+CAA+C,CAAC"}

package/lib/index.js

@@ -31,4 +31,7 @@ __exportStar(require("./error/InvalidDbSchemaError"), exports);
 __exportStar(require("./PostgresErrorCodes"), exports);
 var pg_1 = require("pg");
 Object.defineProperty(exports, "Pool", { enumerable: true, get: function () { return pg_1.Pool; } });
+// S3 External Storage
+__exportStar(require("./s3/S3ExternalStorage"), exports);
+__exportStar(require("./externalized/ExternalizedDynamoDbRepository"), exports);
 //# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;AAAA,uDAAqC;AACrC,sDAAoC;AACpC,6DAA2C;AAC3C,wEAAsD;AACtD,gEAA8C;AAC9C,6CAA2B;AAC3B,iDAA+B;AAC/B,sDAAoC;AACpC,6DAA2C;AAC3C,2DAAyC;AACzC,gEAA8C;AAC9C,+DAA6C;AAE7C,WAAW;AACX,uDAAqC;AAErC,yBAAsC;AAA7B,0FAAA,IAAI,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;AAAA,uDAAqC;AACrC,sDAAoC;AACpC,6DAA2C;AAC3C,wEAAsD;AACtD,gEAA8C;AAC9C,6CAA2B;AAC3B,iDAA+B;AAC/B,sDAAoC;AACpC,6DAA2C;AAC3C,2DAAyC;AACzC,gEAA8C;AAC9C,+DAA6C;AAE7C,WAAW;AACX,uDAAqC;AAErC,yBAAsC;AAA7B,0FAAA,IAAI,OAAA;AAEb,sBAAsB;AACtB,yDAAuC;AACvC,gFAA8D"}

package/lib/s3/S3ExternalStorage.d.ts

@@ -0,0 +1,66 @@
+/*!
+ * @file S3ExternalStorage.ts
+ * @description This file contains the S3ExternalStorage class, which is used to store and retrieve page contents from S3.
+ * @author Dean Heffernan
+ * @copyright 2025 Squiz
+ */
+import { S3Client } from '@aws-sdk/client-s3';
+/**
+ * Represents the storage location of page contents in S3.
+ */
+export interface S3StorageLocation {
+    type: 's3';
+    key: string;
+}
+/**
+ * The S3ExternalStorage class is used to store and retrieve page contents from S3.
+ * @class S3ExternalStorage
+ * @constructor
+ * @param {string} bucket - The name of the S3 bucket to use for storing page contents.
+ * @param {number} thresholdBytes - The threshold in bytes above which page contents will be stored externally.
+ * @param {S3Client} s3Client - The S3 client to use for storing and retrieving page contents.
+ * @returns {S3ExternalStorage} A new instance of the S3ExternalStorage class.
+ */
+export declare class S3ExternalStorage {
+    /**
+     * The config to use for storing and retrieving page contents.
+     * @type {Config}
+     */
+    private readonly tenantId;
+    /**
+     * The name of the S3 bucket to use for storing page contents.
+     * @type {string}
+     */
+    private readonly bucket;
+    /**
+     * The S3 client to use for storing and retrieving page contents.
+     * @type {S3Client}
+     */
+    private readonly s3Client;
+    /**
+     * Creates a new instance of the S3ExternalStorage class.
+     * @constructor
+     * @param {S3Client} s3Client - The S3 client to use for storing and retrieving page contents.
+     * @returns {S3ExternalStorage} A new instance of the S3ExternalStorage class.
+     */
+    constructor(tenantId: string, s3Client: S3Client, bucket: string);
+    /**
+     * Saves a payload to S3.
+     * @param {string} entityName - The name of the entity to save the payload for.
+     * @param {string} referenceId - The reference ID of the payload.
+     * @param {object} payload - The payload to save.
+     * @returns {Promise<{ location: S3StorageLocation; size: number }>} A promise that resolves to the location and size of the saved payload.
+     */
+    save(entityName: string, referenceId: string, payload: object): Promise<{
+        location: S3StorageLocation;
+        size: number;
+    }>;
+    /**
+     * Loads a payload from S3.
+     * @param location - The location of the payload to load.
+     * @returns {Promise<Record<string, unknown>>} A promise that resolves to the loaded payload.
+     */
+    load(location: S3StorageLocation): Promise<Record<string, unknown>>;
+    delete(location?: S3StorageLocation): Promise<void>;
+}
+//# sourceMappingURL=S3ExternalStorage.d.ts.map

package/lib/s3/S3ExternalStorage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"S3ExternalStorage.d.ts","sourceRoot":"","sources":["../../src/s3/S3ExternalStorage.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAA2D,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAEvG;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,IAAI,CAAC;IACX,GAAG,EAAE,MAAM,CAAC;CACb;AAED;;;;;;;;GAQG;AACH,qBAAa,iBAAiB;IAC5B;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAW;IAEpC;;;;;OAKG;gBACS,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM;IAMhE;;;;;;OAMG;IACU,IAAI,CACf,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC;QAAE,QAAQ,EAAE,iBAAiB,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IAoBzD;;;;OAIG;IACU,IAAI,CAAC,QAAQ,EAAE,iBAAiB,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAcnE,MAAM,CAAC,QAAQ,CAAC,EAAE,iBAAiB;CAWjD"}

package/lib/s3/S3ExternalStorage.js

@@ -0,0 +1,84 @@
+"use strict";
+/*!
+ * @file S3ExternalStorage.ts
+ * @description This file contains the S3ExternalStorage class, which is used to store and retrieve page contents from S3.
+ * @author Dean Heffernan
+ * @copyright 2025 Squiz
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.S3ExternalStorage = void 0;
+// External
+const client_s3_1 = require("@aws-sdk/client-s3");
+/**
+ * The S3ExternalStorage class is used to store and retrieve page contents from S3.
+ * @class S3ExternalStorage
+ * @constructor
+ * @param {string} bucket - The name of the S3 bucket to use for storing page contents.
+ * @param {number} thresholdBytes - The threshold in bytes above which page contents will be stored externally.
+ * @param {S3Client} s3Client - The S3 client to use for storing and retrieving page contents.
+ * @returns {S3ExternalStorage} A new instance of the S3ExternalStorage class.
+ */
+class S3ExternalStorage {
+    /**
+     * Creates a new instance of the S3ExternalStorage class.
+     * @constructor
+     * @param {S3Client} s3Client - The S3 client to use for storing and retrieving page contents.
+     * @returns {S3ExternalStorage} A new instance of the S3ExternalStorage class.
+     */
+    constructor(tenantId, s3Client, bucket) {
+        this.tenantId = tenantId;
+        this.bucket = bucket;
+        this.s3Client = s3Client;
+    }
+    /**
+     * Saves a payload to S3.
+     * @param {string} entityName - The name of the entity to save the payload for.
+     * @param {string} referenceId - The reference ID of the payload.
+     * @param {object} payload - The payload to save.
+     * @returns {Promise<{ location: S3StorageLocation; size: number }>} A promise that resolves to the location and size of the saved payload.
+     */
+    async save(entityName, referenceId, payload) {
+        const body = JSON.stringify(payload);
+        const key = `${this.tenantId}/${entityName}/${referenceId}.json`;
+        await this.s3Client.send(new client_s3_1.PutObjectCommand({
+            Bucket: this.bucket,
+            Key: key,
+            Body: body,
+            ContentType: 'application/json',
+        }));
+        return {
+            location: {
+                type: 's3',
+                key,
+            },
+            size: Buffer.byteLength(body, 'utf8'),
+        };
+    }
+    /**
+     * Loads a payload from S3.
+     * @param location - The location of the payload to load.
+     * @returns {Promise<Record<string, unknown>>} A promise that resolves to the loaded payload.
+     */
+    async load(location) {
+        const response = await this.s3Client.send(new client_s3_1.GetObjectCommand({
+            Bucket: this.bucket,
+            Key: location.key,
+        }));
+        if (!response.Body) {
+            throw new Error(`Failed to load externalised items from S3 object ${location.key}`);
+        }
+        const contents = await response.Body.transformToString();
+        return JSON.parse(contents);
+    }
+    async delete(location) {
+        if (!location || !this.bucket) {
+            return;
+        }
+        await this.s3Client.send(new client_s3_1.DeleteObjectCommand({
+            Bucket: this.bucket,
+            Key: location.key,
+        }));
+    }
+}
+exports.S3ExternalStorage = S3ExternalStorage;
+//# sourceMappingURL=S3ExternalStorage.js.map

package/lib/s3/S3ExternalStorage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"S3ExternalStorage.js","sourceRoot":"","sources":["../../src/s3/S3ExternalStorage.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;AAEH,WAAW;AACX,kDAAuG;AAUvG;;;;;;;;GAQG;AACH,MAAa,iBAAiB;IAiB5B;;;;;OAKG;IACH,YAAY,QAAgB,EAAE,QAAkB,EAAE,MAAc;QAC9D,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAC3B,CAAC;IAED;;;;;;OAMG;IACI,KAAK,CAAC,IAAI,CACf,UAAkB,EAClB,WAAmB,EACnB,OAAe;QAEf,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;QACrC,MAAM,GAAG,GAAG,GAAG,IAAI,CAAC,QAAQ,IAAI,UAAU,IAAI,WAAW,OAAO,CAAC;QACjE,MAAM,IAAI,CAAC,QAAQ,CAAC,IAAI,CACtB,IAAI,4BAAgB,CAAC;YACnB,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,GAAG,EAAE,GAAG;YACR,IAAI,EAAE,IAAI;YACV,WAAW,EAAE,kBAAkB;SAChC,CAAC,CACH,CAAC;QACF,OAAO;YACL,QAAQ,EAAE;gBACR,IAAI,EAAE,IAAI;gBACV,GAAG;aACJ;YACD,IAAI,EAAE,MAAM,CAAC,UAAU,CAAC,IAAI,EAAE,MAAM,CAAC;SACtC,CAAC;IACJ,CAAC;IAED;;;;OAIG;IACI,KAAK,CAAC,IAAI,CAAC,QAA2B;QAC3C,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,IAAI,CACvC,IAAI,4BAAgB,CAAC;YACnB,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,GAAG,EAAE,QAAQ,CAAC,GAAG;SAClB,CAAC,CACH,CAAC;QACF,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC;YACnB,MAAM,IAAI,KAAK,CAAC,oDAAoD,QAAQ,CAAC,GAAG,EAAE,CAAC,CAAC;QACtF,CAAC;QACD,MAAM,QAAQ,GAAG,MAAM,QAAQ,CAAC,IAAI,CAAC,iBAAiB,EAAE,CAAC;QACzD,OAAO,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;IAC9B,CAAC;IAEM,KAAK,CAAC,MAAM,CAAC,QAA4B;QAC9C,IAAI,CAAC,QAAQ,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;YAC9B,OAAO;QACT,CAAC;QACD,MAAM,IAAI,CAAC,QAAQ,CAAC,IAAI,CACtB,IAAI,+BAAmB,CAAC;YACtB,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,GAAG,EAAE,QAAQ,CAAC,GAAG;SAClB,CAAC,CACH,CAAC;IACJ,CAAC;CACF;AA1FD,8CA0FC"}

package/lib/s3/S3ExternalStorage.spec.d.ts

@@ -0,0 +1,12 @@
+type S3MockSet = {
+    sendMock: jest.Mock;
+    putObjectCommandMock: jest.Mock;
+    getObjectCommandMock: jest.Mock;
+    deleteObjectCommandMock: jest.Mock;
+    headBucketCommandMock: jest.Mock;
+};
+declare global {
+    var __s3MockSet: S3MockSet | undefined;
+}
+export {};
+//# sourceMappingURL=S3ExternalStorage.spec.d.ts.map

package/lib/s3/S3ExternalStorage.spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"S3ExternalStorage.spec.d.ts","sourceRoot":"","sources":["../../src/s3/S3ExternalStorage.spec.ts"],"names":[],"mappings":"AAMA,KAAK,SAAS,GAAG;IACf,QAAQ,EAAE,IAAI,CAAC,IAAI,CAAC;IACpB,oBAAoB,EAAE,IAAI,CAAC,IAAI,CAAC;IAChC,oBAAoB,EAAE,IAAI,CAAC,IAAI,CAAC;IAChC,uBAAuB,EAAE,IAAI,CAAC,IAAI,CAAC;IACnC,qBAAqB,EAAE,IAAI,CAAC,IAAI,CAAC;CAClC,CAAC;AAEF,OAAO,CAAC,MAAM,CAAC;IAEb,IAAI,WAAW,EAAE,SAAS,GAAG,SAAS,CAAC;CACxC"}

package/lib/s3/S3ExternalStorage.spec.js

@@ -0,0 +1,130 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const S3ExternalStorage_1 = require("./S3ExternalStorage");
+const client_s3_1 = require("@aws-sdk/client-s3");
+const TEST_TENANT_ID = 'test-tenant';
+const TEST_BUCKET = 'dx-test-us-db-fallback';
+jest.mock('@aws-sdk/client-s3', () => {
+    const buildCommandMock = (name) => jest.fn().mockImplementation((input) => ({
+        name,
+        input,
+    }));
+    const state = {
+        sendMock: jest.fn(),
+        putObjectCommandMock: buildCommandMock('PutObjectCommand'),
+        getObjectCommandMock: buildCommandMock('GetObjectCommand'),
+        deleteObjectCommandMock: buildCommandMock('DeleteObjectCommand'),
+        headBucketCommandMock: buildCommandMock('HeadBucketCommand'),
+    };
+    global.__s3MockSet = state;
+    return {
+        S3Client: jest.fn().mockImplementation(() => ({
+            send: state.sendMock,
+        })),
+        PutObjectCommand: state.putObjectCommandMock,
+        GetObjectCommand: state.getObjectCommandMock,
+        DeleteObjectCommand: state.deleteObjectCommandMock,
+        HeadBucketCommand: state.headBucketCommandMock,
+    };
+});
+const { sendMock, putObjectCommandMock, getObjectCommandMock, deleteObjectCommandMock, headBucketCommandMock } = global.__s3MockSet;
+jest.mock('crypto', () => ({
+    randomUUID: jest.fn(() => 'fixed-uuid'),
+}));
+describe('S3ExternalStorage', () => {
+    beforeEach(() => {
+        sendMock.mockReset();
+        putObjectCommandMock.mockClear();
+        getObjectCommandMock.mockClear();
+        deleteObjectCommandMock.mockClear();
+        headBucketCommandMock.mockClear();
+    });
+    const createStorage = () => new S3ExternalStorage_1.S3ExternalStorage(TEST_TENANT_ID, new client_s3_1.S3Client({ region: 'us-west-2' }), TEST_BUCKET);
+    it('saves payloads to S3 and returns location metadata', async () => {
+        const storage = createStorage();
+        const payload = { foo: 'bar' };
+        sendMock.mockResolvedValueOnce({}); // put object
+        const result = await storage.save('test_entity', 'abc', payload);
+        expect(putObjectCommandMock).toHaveBeenCalledWith(expect.objectContaining({
+            Bucket: 'dx-test-us-db-fallback',
+            Body: JSON.stringify(payload),
+            ContentType: 'application/json',
+            Key: result.location.key,
+        }));
+        expect(result.location).toMatchObject({
+            type: 's3',
+        });
+        expect(result.location.key).toBe('test-tenant/test_entity/abc.json');
+        expect(result.size).toBe(JSON.stringify(payload).length);
+    });
+    it('loads payloads from S3 and parses JSON', async () => {
+        const storage = createStorage();
+        const storedPayload = { baz: 'qux' };
+        const transformer = jest.fn().mockResolvedValue(JSON.stringify(storedPayload));
+        sendMock.mockResolvedValueOnce({
+            Body: {
+                transformToString: transformer,
+            },
+        });
+        const location = { type: 's3', key: 'items/foo/bar.json' };
+        const result = await storage.load(location);
+        expect(getObjectCommandMock).toHaveBeenCalledWith({
+            Bucket: 'dx-test-us-db-fallback',
+            Key: 'items/foo/bar.json',
+        });
+        expect(transformer).toHaveBeenCalled();
+        expect(result).toEqual(storedPayload);
+    });
+    it('deletes payloads from S3 when a location is provided', async () => {
+        const storage = createStorage();
+        const location = { type: 's3', key: 'items/foo.json' };
+        sendMock.mockResolvedValueOnce({}); // delete
+        await storage.delete(location);
+        expect(deleteObjectCommandMock).toHaveBeenCalledWith({
+            Bucket: 'dx-test-us-db-fallback',
+            Key: 'items/foo.json',
+        });
+    });
+    it('handles S3 errors when saving', async () => {
+        const storage = createStorage();
+        const payload = { foo: 'bar' };
+        const s3Error = Object.assign(new Error('AccessDenied'), {
+            name: 'AccessDenied',
+            $metadata: { httpStatusCode: 403 },
+        });
+        sendMock.mockRejectedValueOnce(s3Error);
+        await expect(storage.save('test_entity', 'first', payload)).rejects.toThrow('AccessDenied');
+    });
+    it('does not delete when location is undefined', async () => {
+        const storage = createStorage();
+        await storage.delete(undefined);
+        expect(deleteObjectCommandMock).not.toHaveBeenCalled();
+    });
+    it('generates unique S3 keys for different entity types', async () => {
+        const storage = createStorage();
+        sendMock.mockResolvedValue({});
+        const result1 = await storage.save('entity_type_a', 'id-1', { data: 'test' });
+        const result2 = await storage.save('entity_type_b', 'id-2', { data: 'test' });
+        expect(result1.location.key).toContain('entity_type_a/id-1');
+        expect(result2.location.key).toContain('entity_type_b/id-2');
+    });
+    it('throws error when S3 response has no body', async () => {
+        const storage = createStorage();
+        sendMock.mockResolvedValueOnce({ Body: undefined });
+        const location = { type: 's3', key: 'items/foo/bar.json' };
+        await expect(storage.load(location)).rejects.toThrow('Failed to load externalised items from S3 object items/foo/bar.json');
+    });
+    it('handles S3 errors gracefully when loading', async () => {
+        const storage = createStorage();
+        sendMock.mockRejectedValueOnce(new Error('S3 GetObject failed'));
+        const location = { type: 's3', key: 'items/foo/bar.json' };
+        await expect(storage.load(location)).rejects.toThrow('S3 GetObject failed');
+    });
+    it('handles S3 errors gracefully when deleting', async () => {
+        const storage = createStorage();
+        sendMock.mockRejectedValueOnce(new Error('S3 DeleteObject failed'));
+        const location = { type: 's3', key: 'items/foo.json' };
+        await expect(storage.delete(location)).rejects.toThrow('S3 DeleteObject failed');
+    });
+});
+//# sourceMappingURL=S3ExternalStorage.spec.js.map

package/lib/s3/S3ExternalStorage.spec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"S3ExternalStorage.spec.js","sourceRoot":"","sources":["../../src/s3/S3ExternalStorage.spec.ts"],"names":[],"mappings":";;AAAA,2DAA2E;AAC3E,kDAA8C;AAE9C,MAAM,cAAc,GAAG,aAAa,CAAC;AACrC,MAAM,WAAW,GAAG,wBAAwB,CAAC;AAe7C,IAAI,CAAC,IAAI,CAAC,oBAAoB,EAAE,GAAG,EAAE;IACnC,MAAM,gBAAgB,GAAG,CAAC,IAAY,EAAE,EAAE,CACxC,IAAI,CAAC,EAAE,EAAE,CAAC,kBAAkB,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;QACvC,IAAI;QACJ,KAAK;KACN,CAAC,CAAC,CAAC;IACN,MAAM,KAAK,GAAc;QACvB,QAAQ,EAAE,IAAI,CAAC,EAAE,EAAE;QACnB,oBAAoB,EAAE,gBAAgB,CAAC,kBAAkB,CAAC;QAC1D,oBAAoB,EAAE,gBAAgB,CAAC,kBAAkB,CAAC;QAC1D,uBAAuB,EAAE,gBAAgB,CAAC,qBAAqB,CAAC;QAChE,qBAAqB,EAAE,gBAAgB,CAAC,mBAAmB,CAAC;KAC7D,CAAC;IACD,MAAc,CAAC,WAAW,GAAG,KAAK,CAAC;IAEpC,OAAO;QACL,QAAQ,EAAE,IAAI,CAAC,EAAE,EAAE,CAAC,kBAAkB,CAAC,GAAG,EAAE,CAAC,CAAC;YAC5C,IAAI,EAAE,KAAK,CAAC,QAAQ;SACrB,CAAC,CAAC;QACH,gBAAgB,EAAE,KAAK,CAAC,oBAAoB;QAC5C,gBAAgB,EAAE,KAAK,CAAC,oBAAoB;QAC5C,mBAAmB,EAAE,KAAK,CAAC,uBAAuB;QAClD,iBAAiB,EAAE,KAAK,CAAC,qBAAqB;KAC/C,CAAC;AACJ,CAAC,CAAC,CAAC;AAEH,MAAM,EAAE,QAAQ,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,uBAAuB,EAAE,qBAAqB,EAAE,GAC5G,MACD,CAAC,WAAwB,CAAC;AAE3B,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,GAAG,EAAE,CAAC,CAAC;IACzB,UAAU,EAAE,IAAI,CAAC,EAAE,CAAC,GAAG,EAAE,CAAC,YAAY,CAAC;CACxC,CAAC,CAAC,CAAC;AAEJ,QAAQ,CAAC,mBAAmB,EAAE,GAAG,EAAE;IACjC,UAAU,CAAC,GAAG,EAAE;QACd,QAAQ,CAAC,SAAS,EAAE,CAAC;QACrB,oBAAoB,CAAC,SAAS,EAAE,CAAC;QACjC,oBAAoB,CAAC,SAAS,EAAE,CAAC;QACjC,uBAAuB,CAAC,SAAS,EAAE,CAAC;QACpC,qBAAqB,CAAC,SAAS,EAAE,CAAC;IACpC,CAAC,CAAC,CAAC;IAEH,MAAM,aAAa,GAAG,GAAG,EAAE,CAAC,IAAI,qCAAiB,CAAC,cAAc,EAAE,IAAI,oBAAQ,CAAC,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC,EAAE,WAAW,CAAC,CAAC;IAEtH,EAAE,CAAC,oDAAoD,EAAE,KAAK,IAAI,EAAE;QAClE,MAAM,OAAO,GAAG,aAAa,EAAE,CAAC;QAChC,MAAM,OAAO,GAAG,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC;QAC/B,QAAQ,CAAC,qBAAqB,CAAC,EAAE,CAAC,CAAC,CAAC,aAAa;QAEjD,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,aAAa,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC;QAEjE,MAAM,CAAC,oBAAoB,CAAC,CAAC,oBAAoB,CAC/C,MAAM,CAAC,gBAAgB,CAAC;YACtB,MAAM,EAAE,wBAAwB;YAChC,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC;YAC7B,WAAW,EAAE,kBAAkB;YAC/B,GAAG,EAAE,MAAM,CAAC,QAAQ,CAAC,GAAG;SACzB,CAAC,CACH,CAAC;QACF,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,aAAa,CAAC;YACpC,IAAI,EAAE,IAAI;SACX,CAAC,CAAC;QACH,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,kCAAkC,CAAC,CAAC;QACrE,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC;IAC3D,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,wCAAwC,EAAE,KAAK,IAAI,EAAE;QACtD,MAAM,OAAO,GAAG,aAAa,EAAE,CAAC;QAChC,MAAM,aAAa,GAAG,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC;QACrC,MAAM,WAAW,GAAG,IAAI,CAAC,EAAE,EAAE,CAAC,iBAAiB,CAAC,IAAI,CAAC,SAAS,CAAC,aAAa,CAAC,CAAC,CAAC;QAC/E,QAAQ,CAAC,qBAAqB,CAAC;YAC7B,IAAI,EAAE;gBACJ,iBAAiB,EAAE,WAAW;aAC/B;SACF,CAAC,CAAC;QAEH,MAAM,QAAQ,GAAsB,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,oBAAoB,EAAE,CAAC;QAC9E,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QAE5C,MAAM,CAAC,oBAAoB,CAAC,CAAC,oBAAoB,CAAC;YAChD,MAAM,EAAE,wBAAwB;YAChC,GAAG,EAAE,oBAAoB;SAC1B,CAAC,CAAC;QACH,MAAM,CAAC,WAAW,CAAC,CAAC,gBAAgB,EAAE,CAAC;QACvC,MAAM,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC;IACxC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,sDAAsD,EAAE,KAAK,IAAI,EAAE;QACpE,MAAM,OAAO,GAAG,aAAa,EAAE,CAAC;QAChC,MAAM,QAAQ,GAAsB,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,gBAAgB,EAAE,CAAC;QAC1E,QAAQ,CAAC,qBAAqB,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS;QAE7C,MAAM,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QAE/B,MAAM,CAAC,uBAAuB,CAAC,CAAC,oBAAoB,CAAC;YACnD,MAAM,EAAE,wBAAwB;YAChC,GAAG,EAAE,gBAAgB;SACtB,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,+BAA+B,EAAE,KAAK,IAAI,EAAE;QAC7C,MAAM,OAAO,GAAG,aAAa,EAAE,CAAC;QAChC,MAAM,OAAO,GAAG,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC;QAC/B,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,cAAc,CAAC,EAAE;YACvD,IAAI,EAAE,cAAc;YACpB,SAAS,EAAE,EAAE,cAAc,EAAE,GAAG,EAAE;SACnC,CAAC,CAAC;QAEH,QAAQ,CAAC,qBAAqB,CAAC,OAAO,CAAC,CAAC;QAExC,MAAM,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,aAAa,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,cAAc,CAAC,CAAC;IAC9F,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,4CAA4C,EAAE,KAAK,IAAI,EAAE;QAC1D,MAAM,OAAO,GAAG,aAAa,EAAE,CAAC;QAEhC,MAAM,OAAO,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;QAEhC,MAAM,CAAC,uBAAuB,CAAC,CAAC,GAAG,CAAC,gBAAgB,EAAE,CAAC;IACzD,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,qDAAqD,EAAE,KAAK,IAAI,EAAE;QACnE,MAAM,OAAO,GAAG,aAAa,EAAE,CAAC;QAChC,QAAQ,CAAC,iBAAiB,CAAC,EAAE,CAAC,CAAC;QAE/B,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,eAAe,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;QAC9E,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,eAAe,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;QAE9E,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,SAAS,CAAC,oBAAoB,CAAC,CAAC;QAC7D,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,SAAS,CAAC,oBAAoB,CAAC,CAAC;IAC/D,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,2CAA2C,EAAE,KAAK,IAAI,EAAE;QACzD,MAAM,OAAO,GAAG,aAAa,EAAE,CAAC;QAChC,QAAQ,CAAC,qBAAqB,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC,CAAC;QAEpD,MAAM,QAAQ,GAAsB,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,oBAAoB,EAAE,CAAC;QAE9E,MAAM,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAClD,qEAAqE,CACtE,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,2CAA2C,EAAE,KAAK,IAAI,EAAE;QACzD,MAAM,OAAO,GAAG,aAAa,EAAE,CAAC;QAChC,QAAQ,CAAC,qBAAqB,CAAC,IAAI,KAAK,CAAC,qBAAqB,CAAC,CAAC,CAAC;QAEjE,MAAM,QAAQ,GAAsB,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,oBAAoB,EAAE,CAAC;QAE9E,MAAM,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,qBAAqB,CAAC,CAAC;IAC9E,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,4CAA4C,EAAE,KAAK,IAAI,EAAE;QAC1D,MAAM,OAAO,GAAG,aAAa,EAAE,CAAC;QAChC,QAAQ,CAAC,qBAAqB,CAAC,IAAI,KAAK,CAAC,wBAAwB,CAAC,CAAC,CAAC;QAEpE,MAAM,QAAQ,GAAsB,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,gBAAgB,EAAE,CAAC;QAE1E,MAAM,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,wBAAwB,CAAC,CAAC;IACnF,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@squiz/db-lib",
-  "version": "1.76.0",
+  "version": "1.77.0",
   "description": "",
   "main": "lib/index.js",
   "private": false,
@@ -19,19 +19,20 @@
     "@types/node": "22.10.5",
     "@types/pg": "^8.11.8",
     "aws-sdk-client-mock": "^4.0.0",
-    "aws-sdk-client-mock-jest": "4.0.0",
+    "aws-sdk-client-mock-jest": "4.1.0",
     "jest": "29.4.1",
     "ts-jest": "29.0.5",
     "typescript": "^5.7.2"
   },
   "dependencies": {
-    "@aws-sdk/client-dynamodb": "^3.651.1",
-    "@aws-sdk/client-secrets-manager": "3.651.1",
-    "@aws-sdk/lib-dynamodb": "^3.651.1",
+    "@aws-sdk/client-dynamodb": "^3.946.0",
+    "@aws-sdk/client-s3": "^3.946.0",
+    "@aws-sdk/client-secrets-manager": "^3.946.0",
+    "@aws-sdk/lib-dynamodb": "^3.946.0",
     "@opentelemetry/api": "^1.6.0",
     "@squiz/dx-common-lib": "^1.69.1",
     "@squiz/dx-logger-lib": "^1.65.1",
-    "dotenv": "16.0.3",
+    "dotenv": "16.6.1",
     "pg": "^8.12.0"
   }
 }

package/src/dynamodb/AbstractDynamoDbRepository.spec.ts

@@ -21,7 +21,8 @@ import {
 } from '@aws-sdk/lib-dynamodb';
 import { ConditionalCheckFailedException } from '@aws-sdk/client-dynamodb';
 import { DynamoDbManager, Transaction } from './DynamoDbManager';
-import { MissingKeyValuesError, InvalidDbSchemaError } from '..';
+import { MissingKeyValuesError } from '../error/MissingKeyValuesError';
+import { InvalidDbSchemaError } from '../error/InvalidDbSchemaError';
 
 import { mockClient } from 'aws-sdk-client-mock';
 import 'aws-sdk-client-mock-jest';

package/src/dynamodb/AbstractDynamoDbRepository.ts

@@ -10,7 +10,9 @@ import {
   BatchGetCommandOutput,
 } from '@aws-sdk/lib-dynamodb';
 
-import { Transaction, DynamoDbManager, MissingKeyValuesError, InvalidDbSchemaError } from '..';
+import { Transaction, DynamoDbManager } from './DynamoDbManager';
+import { MissingKeyValuesError } from '../error/MissingKeyValuesError';
+import { InvalidDbSchemaError } from '../error/InvalidDbSchemaError';
 import { InvalidDataFormatError } from '../error/InvalidDataFormatError';
 import { UnknownKeyAttributeError } from '../error/UnknownKeyAttributeError';