@squiz/db-lib 1.77.0 → 1.77.2

package/src/externalized/ExternalizedDynamoDbRepository.spec.ts

@@ -43,11 +43,34 @@ const testEntityDefinition: EntityDefinition = {
 // Concrete test repository
 class TestRepo extends ExternalizedDynamoDbRepository<TestItemShape, TestItem> {
   public mockSuperUpdateItem?: jest.Mock;
+  public mockSuperGetItem?: jest.Mock;
+  public mockSuperCreateItem?: jest.Mock;
 
   constructor(dbManager: DynamoDbManager<any>, storage: S3ExternalStorage, overrides: Partial<EntityDefinition> = {}) {
     super('test-table', dbManager, 'test_item', { ...testEntityDefinition, ...overrides }, TestItem, storage);
   }
 
+  // Expose protected methods for testing
+  public async testPrepareValueForStorage(value: TestItem): Promise<TestItem> {
+    return await (this as any).prepareValueForStorage(value);
+  }
+
+  public async testHydrateFromExternalStorage(record?: TestItem): Promise<TestItem | undefined> {
+    return await (this as any).hydrateFromExternalStorage(record);
+  }
+
+  public testIsDynamoItemSizeLimitError(error: unknown): boolean {
+    return (this as any).isDynamoItemSizeLimitError(error);
+  }
+
+  public testIsContentInS3(item: TestItem): boolean {
+    return (this as any).isContentInS3(item);
+  }
+
+  public testGetKeyFieldsValues(obj: Record<string, unknown>): Record<string, unknown> {
+    return (this as any).getKeyFieldsValues(obj);
+  }
+
   // Override updateItem to allow mocking super.updateItem
   public async updateItem(value: Partial<TestItemShape>): Promise<TestItem | undefined> {
     if (this.mockSuperUpdateItem) {
@@ -74,6 +97,7 @@ const createDbManager = (clientOverrides: Record<string, jest.Mock> = {}) =>
       put: jest.fn(),
       delete: jest.fn(),
       update: jest.fn(),
+      query: jest.fn(),
       ...clientOverrides,
     },
     repositories: {} as any,
@@ -99,176 +123,454 @@ const createTestItem = (overrides: Partial<TestItem> = {}): TestItem => {
 };
 
 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 }),
-    } as unknown as S3ExternalStorage;
-    const repo = new TestRepo(createDbManager(), storage);
-    const item = createTestItem();
-
-    const storedValue = await (repo as any).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' });
+  describe('prepareValueForStorage', () => {
+    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 }),
+      } as unknown as S3ExternalStorage;
+      const repo = new TestRepo(createDbManager(), storage);
+      const item = createTestItem();
+
+      const storedValue = await repo.testPrepareValueForStorage(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('removes existing storageLocation before saving to S3', async () => {
+      const storage = {
+        ...createStorage(),
+        save: jest.fn().mockResolvedValue({ location: { type: 's3', key: 'new-key' }, size: 500 }),
+      } as unknown as S3ExternalStorage;
+      const repo = new TestRepo(createDbManager(), storage);
+      const item = createTestItem();
+      (item as any).storageLocation = { type: 's3', key: 'old-key' };
+
+      await repo.testPrepareValueForStorage(item);
+
+      // Verify save was called without storageLocation in the payload
+      const savedPayload = (storage.save as jest.Mock).mock.calls[0][2];
+      expect(savedPayload.storageLocation).toBeUndefined();
+    });
   });
 
-  it('creates item with storageLocation preserved', async () => {
-    const client = createDbManager().client as any;
-    (client.put as jest.Mock).mockResolvedValue({});
-    const storage = {
-      ...createStorage(),
-      save: jest.fn().mockResolvedValue({ location: { type: 's3', key: 'item-key' }, size: 500 }),
-    } as unknown as S3ExternalStorage;
+  describe('createItem', () => {
+    it('creates item with storageLocation preserved', async () => {
+      const client = createDbManager().client as any;
+      (client.put as jest.Mock).mockResolvedValue({});
+      const storage = {
+        ...createStorage(),
+        save: jest.fn().mockResolvedValue({ location: { type: 's3', key: 'item-key' }, size: 500 }),
+        load: jest.fn().mockResolvedValue(createTestItem()),
+      } as unknown as S3ExternalStorage;
+
+      const repo = new TestRepo({ client } as any, storage);
+      const item = createTestItem();
+
+      // Use prepareValueForStorage to externalize data and set storageLocation
+      const preparedItem = await repo.testPrepareValueForStorage(item);
 
-    const repo = new TestRepo({ client } as any, storage);
-    const item = createTestItem();
+      // Verify the prepared value has minimal payload (empty data)
+      expect(preparedItem.data).toEqual([]);
+      expect(preparedItem.storageLocation).toEqual({ type: 's3', key: 'item-key' });
 
-    // Use prepareValueForStorage to externalize data and set storageLocation
-    const preparedItem = await (repo as any).prepareValueForStorage(item);
+      // Original item should NOT be mutated
+      expect(item.storageLocation).toBeUndefined();
+    });
 
-    // Verify the prepared value has minimal payload (empty data)
-    expect(preparedItem.data).toEqual([]);
-    expect(preparedItem.storageLocation).toEqual({ type: 's3', key: 'item-key' });
+    it('automatically externalizes to S3 when createItem exceeds DynamoDB size limit', async () => {
+      const client = createDbManager().client as any;
+      let callCount = 0;
+      (client.put as jest.Mock).mockImplementation(() => {
+        callCount++;
+        if (callCount === 1) {
+          // First call fails with size limit error
+          const error = new Error('Item size has exceeded the maximum allowed size');
+          (error as any).code = 'ValidationException';
+          throw error;
+        }
+        // Second call succeeds
+        return Promise.resolve({});
+      });
+
+      const storage = {
+        ...createStorage(),
+        save: jest.fn().mockResolvedValue({ location: { type: 's3', key: 'auto-key' }, size: 500 }),
+        load: jest.fn().mockResolvedValue(createTestItem()),
+      } as unknown as S3ExternalStorage;
+
+      const repo = new TestRepo({ client } as any, storage);
+      const item = createTestItem({ data: [{ key: 'large', value: { content: 'x'.repeat(500000) } }] });
+
+      await repo.createItem(item);
+
+      // Should have called save to externalize
+      expect(storage.save).toHaveBeenCalled();
+      // Should have retried the put
+      expect(client.put).toHaveBeenCalledTimes(2);
+    });
 
-    // Original item should NOT be mutated
-    expect(item.storageLocation).toBeUndefined();
+    it('cleans up old S3 file when overrideExisting is true', async () => {
+      const oldLocation = { type: 's3' as const, key: 'old-key' };
+      const newLocation = { type: 's3' as const, key: 'new-key' };
+
+      const client = createDbManager({
+        get: jest.fn().mockResolvedValue({
+          Item: {
+            id: 'item-1',
+            name: 'Old',
+            storageLocation: oldLocation,
+          },
+        }),
+        put: jest.fn().mockResolvedValue({}),
+      }).client as any;
+
+      const storage = {
+        ...createStorage(),
+        save: jest.fn().mockResolvedValue({ location: newLocation, size: 500 }),
+        load: jest.fn().mockResolvedValue(createTestItem()),
+      } as unknown as S3ExternalStorage;
+
+      const repo = new TestRepo({ client } as any, storage);
+      const item = createTestItem();
+      const preparedItem = await repo.testPrepareValueForStorage(item);
+
+      await repo.createItem(preparedItem, {}, {}, { overrideExisting: true });
+
+      expect(storage.delete).toHaveBeenCalledWith(oldLocation);
+    });
   });
 
-  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 as jest.Mock).mockResolvedValue(fullData);
-
-    const repo = new TestRepo(createDbManager({ get: jest.fn() as any }), storage);
-    const result = await (repo as any).hydrateFromExternalStorage({
-      id: 'item-1',
-      name: 'Placeholder',
-      data: [],
-      storageLocation: { type: 's3', key: 'item-key' },
+  describe('updateItem', () => {
+    it('cleans up old S3 file when updating with new storageLocation', async () => {
+      const oldLocation = { type: 's3' as const, key: 'old-key' };
+      const newLocation = { type: 's3' as const, 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 as any;
+
+      const storage = createStorage();
+      const repo = new TestRepo({ client } as any, storage);
+
+      const updateValue = {
+        id: 'item-1',
+        name: 'Updated',
+      };
+
+      const updatedItem = createTestItem({ id: 'item-1', name: 'Updated' });
+      (updatedItem as any).storageLocation = newLocation;
+
+      repo.mockSuperUpdateItem = jest.fn().mockResolvedValue(updatedItem as any);
+
+      await repo.updateItem(updateValue);
+
+      expect(storage.delete).toHaveBeenCalledWith(oldLocation);
     });
 
-    expect(storage.load).toHaveBeenCalledWith({ type: 's3', key: 'item-key' });
-    expect(result?.name).toBe('From S3');
-    expect(result?.data).toEqual([{ key: 'sample', value: { main: [] } }]);
+    it('does not delete S3 file when storageLocation is unchanged', async () => {
+      const location = { type: 's3' as const, 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 as any;
+
+      const storage = createStorage();
+      const repo = new TestRepo({ client } as any, storage);
+
+      const updateValue = {
+        id: 'item-1',
+        name: 'Updated',
+      };
+
+      const updatedItem = createTestItem({ id: 'item-1', name: 'Updated' });
+      (updatedItem as any).storageLocation = location;
+
+      repo.mockSuperUpdateItem = jest.fn().mockResolvedValue(updatedItem as any);
+
+      await repo.updateItem(updateValue);
+
+      expect(storage.delete).not.toHaveBeenCalled();
+    });
   });
 
-  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 as any;
-    const storage = createStorage();
-    const repo = new TestRepo({ client } as any, storage);
+  describe('getItem', () => {
+    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 as jest.Mock).mockResolvedValue(fullData);
+
+      const repo = new TestRepo(createDbManager({ get: jest.fn() as any }), storage);
+      const result = await repo.testHydrateFromExternalStorage({
+        id: 'item-1',
+        name: 'Placeholder',
+        data: [],
+        storageLocation: { type: 's3', key: 'item-key' },
+      } as TestItem);
+
+      expect(storage.load).toHaveBeenCalledWith({ type: 's3', key: 'item-key' });
+      expect(result?.name).toBe('From S3');
+      expect(result?.data).toEqual([{ key: 'sample', value: { main: [] } }]);
+    });
 
-    await repo.deleteItem({ id: 'item-1' });
+    it('returns inline data when no storageLocation is present', async () => {
+      const storage = createStorage();
+      const repo = new TestRepo(createDbManager({ get: jest.fn() as any }), storage);
+      const inlineRecord = {
+        id: 'item-1',
+        name: 'Inline Item',
+        data: [{ key: 'sample', value: { main: [] } }],
+      } as TestItem;
+
+      const result = await repo.testHydrateFromExternalStorage(inlineRecord);
+
+      expect(storage.load).not.toHaveBeenCalled();
+      expect(result).toBeDefined();
+      expect(result?.name).toBe('Inline Item');
+      expect(result?.data).toEqual([{ key: 'sample', value: { main: [] } }]);
+    });
+
+    it('never includes storageLocation in response', async () => {
+      const storage = createStorage();
+      const fullData = {
+        id: 'item-1',
+        name: 'From S3',
+        data: [{ key: 'sample', value: { main: [] } }],
+      };
+      (storage.load as jest.Mock).mockResolvedValue(fullData);
+
+      const repo = new TestRepo(createDbManager(), storage);
+      const result = await repo.testHydrateFromExternalStorage({
+        id: 'item-1',
+        name: 'Placeholder',
+        data: [],
+        storageLocation: { type: 's3', key: 'item-key' },
+      } as TestItem);
+
+      // storageLocation is an internal implementation detail and should never be exposed
+      expect(result?.storageLocation).toBeUndefined();
+      expect(result?.name).toBe('From S3');
+      expect(result?.data).toEqual([{ key: 'sample', value: { main: [] } }]);
+    });
 
-    expect(storage.delete).toHaveBeenCalledWith({ type: 's3', key: 'item-key' });
+    it('returns empty content when S3 storage is missing or fails to load', async () => {
+      const storage = createStorage();
+      const s3Error = new Error('The specified key does not exist');
+      (s3Error as any).code = 'NoSuchKey';
+      (storage.load as jest.Mock).mockRejectedValue(s3Error);
+
+      const consoleWarnSpy = jest.spyOn(console, 'warn').mockImplementation();
+
+      const repo = new TestRepo(createDbManager(), storage);
+      const result = await repo.testHydrateFromExternalStorage({
+        id: 'item-1',
+        name: 'Test Item',
+        data: [],
+        storageLocation: { type: 's3', key: 'missing-key' },
+      } as TestItem);
+
+      // Should attempt to load from S3
+      expect(storage.load).toHaveBeenCalledWith({ type: 's3', key: 'missing-key' });
+
+      // Should log warning about failed load
+      expect(consoleWarnSpy).toHaveBeenCalledWith(
+        'Failed to load content from S3 for test_item:',
+        'The specified key does not exist',
+      );
+
+      // Should return item with empty content (graceful degradation)
+      expect(result).toBeDefined();
+      expect(result?.id).toBe('item-1');
+      expect(result?.name).toBe('Test Item');
+      expect(result?.data).toEqual([]);
+
+      // storageLocation should be removed to avoid confusion
+      expect(result?.storageLocation).toBeUndefined();
+
+      consoleWarnSpy.mockRestore();
+    });
   });
 
-  it('returns inline data when no storageLocation is present', async () => {
-    const storage = createStorage();
-    const repo = new TestRepo(createDbManager({ get: jest.fn() as any }), storage);
-    const inlineRecord = {
-      id: 'item-1',
-      name: 'Inline Item',
-      data: [{ key: 'sample', value: { main: [] } }],
-    };
-
-    const result = await (repo as any).hydrateFromExternalStorage(inlineRecord);
-
-    expect(storage.load).not.toHaveBeenCalled();
-    expect(result).toBeDefined();
-    expect(result?.name).toBe('Inline Item');
-    expect(result?.data).toEqual([{ key: 'sample', value: { main: [] } }]);
+  describe('deleteItem', () => {
+    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 as any;
+      const storage = createStorage();
+      const repo = new TestRepo({ client } as any, storage);
+
+      await repo.deleteItem({ id: 'item-1' });
+
+      expect(storage.delete).toHaveBeenCalledWith({ type: 's3', key: 'item-key' });
+    });
+
+    it('does not attempt to delete S3 when item has no storageLocation', async () => {
+      const client = createDbManager({
+        get: jest.fn().mockResolvedValue({ Item: { id: 'item-1', name: 'Test' } }),
+        delete: jest.fn().mockResolvedValue({}),
+      }).client as any;
+      const storage = createStorage();
+      const repo = new TestRepo({ client } as any, storage);
+
+      await repo.deleteItem({ id: 'item-1' });
+
+      expect(storage.delete).not.toHaveBeenCalled();
+    });
   });
 
-  it('cleans up old S3 file when updating with new storageLocation', async () => {
-    const oldLocation = { type: 's3' as const, key: 'old-key' };
-    const newLocation = { type: 's3' as const, 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 as any;
-
-    const storage = createStorage();
-    const repo = new TestRepo({ client } as any, 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 as any).storageLocation = newLocation;
-
-    // Mock super.updateItem using the custom mock hook
-    repo.mockSuperUpdateItem = jest.fn().mockResolvedValue(updatedItem as any);
-
-    await repo.updateItem(updateValue);
-
-    expect(storage.delete).toHaveBeenCalledWith(oldLocation);
+  describe('isDynamoItemSizeLimitError', () => {
+    it('detects ValidationException with size message', () => {
+      const repo = new TestRepo(createDbManager(), createStorage());
+      const error = {
+        code: 'ValidationException',
+        message: 'Item size has exceeded the maximum allowed size',
+      };
+
+      expect(repo.testIsDynamoItemSizeLimitError(error)).toBe(true);
+    });
+
+    it('detects TransactionCanceledException with size in cancellation reasons', () => {
+      const repo = new TestRepo(createDbManager(), createStorage());
+      const error = {
+        code: 'TransactionCanceledException',
+        CancellationReasons: [
+          {
+            Code: 'ValidationException',
+            Message: 'Item size exceeded 400 KB limit',
+          },
+        ],
+      };
+
+      expect(repo.testIsDynamoItemSizeLimitError(error)).toBe(true);
+    });
+
+    it('detects size keywords in error message', () => {
+      const repo = new TestRepo(createDbManager(), createStorage());
+      const error = {
+        message: 'The item size exceeds the maximum allowed size',
+      };
+
+      expect(repo.testIsDynamoItemSizeLimitError(error)).toBe(true);
+    });
+
+    it('returns false for non-size-related errors', () => {
+      const repo = new TestRepo(createDbManager(), createStorage());
+      const error = {
+        code: 'ResourceNotFoundException',
+        message: 'Table not found',
+      };
+
+      expect(repo.testIsDynamoItemSizeLimitError(error)).toBe(false);
+    });
+
+    it('returns false for null/undefined errors', () => {
+      const repo = new TestRepo(createDbManager(), createStorage());
+
+      expect(repo.testIsDynamoItemSizeLimitError(null)).toBe(false);
+      expect(repo.testIsDynamoItemSizeLimitError(undefined)).toBe(false);
+    });
   });
 
-  it('does not delete S3 file when storageLocation is unchanged', async () => {
-    const location = { type: 's3' as const, 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 as any;
-
-    const storage = createStorage();
-    const repo = new TestRepo({ client } as any, 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 as any).storageLocation = location;
-
-    // Mock super.updateItem using the custom mock hook
-    repo.mockSuperUpdateItem = jest.fn().mockResolvedValue(updatedItem as any);
-
-    await repo.updateItem(updateValue);
-
-    expect(storage.delete).not.toHaveBeenCalled();
+  describe('isContentInS3', () => {
+    it('returns true when storageLocation exists and large content fields are empty', () => {
+      const repo = new TestRepo(createDbManager(), createStorage());
+      const item = createTestItem({ data: [] });
+      (item as any).storageLocation = { type: 's3', key: 'item-key' };
+
+      expect(repo.testIsContentInS3(item)).toBe(true);
+    });
+
+    it('returns false when storageLocation exists but large content fields have data', () => {
+      const repo = new TestRepo(createDbManager(), createStorage());
+      const item = createTestItem({ data: [{ key: 'sample', value: { main: [] } }] });
+      (item as any).storageLocation = { type: 's3', key: 'item-key' };
+
+      expect(repo.testIsContentInS3(item)).toBe(false);
+    });
+
+    it('returns false when no storageLocation', () => {
+      const repo = new TestRepo(createDbManager(), createStorage());
+      const item = createTestItem();
+
+      expect(repo.testIsContentInS3(item)).toBe(false);
+    });
+  });
+
+  describe('getKeyFieldsValues', () => {
+    it('preserves key fields and small metadata', () => {
+      const repo = new TestRepo(createDbManager(), createStorage());
+      const obj = {
+        id: 'item-1',
+        name: 'Test',
+        data: [{ key: 'large', value: { content: 'big' } }],
+      };
+
+      const result = repo.testGetKeyFieldsValues(obj);
+
+      expect(result.id).toBe('item-1');
+      expect(result.name).toBe('Test');
+    });
+
+    it('empties large content fields (fieldsAsJsonString)', () => {
+      const repo = new TestRepo(createDbManager(), createStorage());
+      const obj = {
+        id: 'item-1',
+        name: 'Test',
+        data: [{ key: 'large', value: { content: 'big' } }],
+      };
+
+      const result = repo.testGetKeyFieldsValues(obj);
+
+      // data is in fieldsAsJsonString, so should be empty array
+      expect(result.data).toEqual([]);
+    });
+
+    it('removes storageLocation from result', () => {
+      const repo = new TestRepo(createDbManager(), createStorage());
+      const obj = {
+        id: 'item-1',
+        name: 'Test',
+        data: [],
+        storageLocation: { type: 's3', key: 'item-key' },
+      };
+
+      const result = repo.testGetKeyFieldsValues(obj);
+
+      expect(result.storageLocation).toBeUndefined();
+    });
   });
 });