@adtrackify/at-service-common 3.17.8 → 3.18.1

package/dist/esm/__tests__/clients/sqs-unbundle.spec.js

@@ -0,0 +1,786 @@
+import { unbundleRecords, unbundleMessage, isBundledEnvelope, } from '../../clients/generic/sqs-unbundle';
+import { CompressionAlgorithm, } from '../../clients/generic/sqs-bundled-client.types';
+import { compress, CompressionTimeoutError, CompressionOperation, } from '../../utils/compression';
+jest.mock('../../helpers/logging-helper', () => ({
+    Logger: {
+        debug: jest.fn(),
+        info: jest.fn(),
+        warn: jest.fn(),
+        error: jest.fn(),
+    },
+}));
+function makeTestEvent(id, name = 'test_event', value) {
+    return { eventId: id, name, value };
+}
+function makeSqsRecord(body, messageId = 'msg-1') {
+    return {
+        messageId,
+        body: typeof body === 'string' ? body : JSON.stringify(body),
+    };
+}
+function makeBundledEnvelope(items) {
+    return {
+        v: 1,
+        c: CompressionAlgorithm.NONE,
+        n: items.length,
+        s: JSON.stringify(items).length,
+        p: items,
+    };
+}
+async function makeCompressedEnvelope(items, level = 3) {
+    const json = JSON.stringify(items);
+    const compressed = await compress(Buffer.from(json, 'utf8'), CompressionAlgorithm.ZSTD, level);
+    const base64 = compressed.toString('base64');
+    return {
+        v: 1,
+        c: CompressionAlgorithm.ZSTD,
+        n: items.length,
+        s: json.length,
+        p: base64,
+    };
+}
+describe('isBundledEnvelope', () => {
+    it('returns true for valid bundled envelope with NONE compression', () => {
+        const envelope = makeBundledEnvelope([makeTestEvent('1')]);
+        expect(isBundledEnvelope(envelope)).toBe(true);
+    });
+    it('returns true for valid bundled envelope with ZSTD compression', async () => {
+        const envelope = await makeCompressedEnvelope([makeTestEvent('1')]);
+        expect(isBundledEnvelope(envelope)).toBe(true);
+    });
+    it('returns false for null', () => {
+        expect(isBundledEnvelope(null)).toBe(false);
+    });
+    it('returns false for undefined', () => {
+        expect(isBundledEnvelope(undefined)).toBe(false);
+    });
+    it('returns false for plain object (legacy message)', () => {
+        expect(isBundledEnvelope(makeTestEvent('1'))).toBe(false);
+    });
+    it('returns false for wrong version', () => {
+        const envelope = { v: 2, c: 'none', n: 1, p: [] };
+        expect(isBundledEnvelope(envelope)).toBe(false);
+    });
+    it('returns false for invalid compression algorithm', () => {
+        const envelope = { v: 1, c: 'gzip', n: 1, p: [] };
+        expect(isBundledEnvelope(envelope)).toBe(false);
+    });
+    it('returns false for missing count', () => {
+        const envelope = { v: 1, c: 'none', p: [] };
+        expect(isBundledEnvelope(envelope)).toBe(false);
+    });
+    it('returns false for missing payload', () => {
+        const envelope = { v: 1, c: 'none', n: 1 };
+        expect(isBundledEnvelope(envelope)).toBe(false);
+    });
+});
+describe('unbundleMessage', () => {
+    it('unbundles NONE compression envelope', async () => {
+        const items = [makeTestEvent('1'), makeTestEvent('2')];
+        const envelope = makeBundledEnvelope(items);
+        const result = await unbundleMessage(envelope);
+        expect(result).toHaveLength(2);
+        expect(result[0].eventId).toBe('1');
+        expect(result[1].eventId).toBe('2');
+    });
+    it('unbundles ZSTD compressed envelope', async () => {
+        const items = [makeTestEvent('1'), makeTestEvent('2'), makeTestEvent('3')];
+        const envelope = await makeCompressedEnvelope(items);
+        const result = await unbundleMessage(envelope);
+        expect(result).toHaveLength(3);
+        expect(result[0].eventId).toBe('1');
+        expect(result[1].eventId).toBe('2');
+        expect(result[2].eventId).toBe('3');
+    });
+    it('unbundles large batches with ZSTD compression', async () => {
+        const items = Array.from({ length: 500 }, (_, i) => makeTestEvent(`event-${i}`, `event_${i}`, i * 10));
+        const envelope = await makeCompressedEnvelope(items);
+        const result = await unbundleMessage(envelope);
+        expect(result).toHaveLength(500);
+        expect(result[0].eventId).toBe('event-0');
+        expect(result[499].eventId).toBe('event-499');
+    });
+    it('throws on unsupported bundle version', async () => {
+        const envelope = { v: 99, c: 'none', n: 1, p: [] };
+        await expect(unbundleMessage(envelope)).rejects.toThrow('Unsupported bundle version: 99');
+    });
+    it('throws on invalid payload type for NONE compression', async () => {
+        const envelope = { v: 1, c: 'none', n: 1, p: 'not-an-array' };
+        await expect(unbundleMessage(envelope)).rejects.toThrow('Invalid bundle: NONE compression but payload is not an array');
+    });
+    it('throws on invalid payload type for ZSTD compression', async () => {
+        const envelope = { v: 1, c: 'zstd', n: 1, p: [] };
+        await expect(unbundleMessage(envelope)).rejects.toThrow('Invalid bundle: zstd compression but payload is not a string');
+    });
+});
+describe('unbundleRecords', () => {
+    describe('legacy (non-bundled) messages', () => {
+        it('parses raw JSON message', async () => {
+            const event = makeTestEvent('raw-1', 'purchase');
+            const record = makeSqsRecord(event);
+            const { items, stats, failedMessageIds } = await unbundleRecords([record]);
+            expect(items).toHaveLength(1);
+            expect(items[0].eventId).toBe('raw-1');
+            expect(items[0].name).toBe('purchase');
+            expect(stats.legacyRecords).toBe(1);
+            expect(stats.bundledRecords).toBe(0);
+            expect(failedMessageIds).toHaveLength(0);
+        });
+        it('parses wrapped messageBody format', async () => {
+            const event = makeTestEvent('wrapped-1');
+            const record = makeSqsRecord({ messageBody: event });
+            const { items, stats } = await unbundleRecords([record]);
+            expect(items).toHaveLength(1);
+            expect(items[0].eventId).toBe('wrapped-1');
+            expect(stats.legacyRecords).toBe(1);
+        });
+        it('handles multiple legacy records', async () => {
+            const records = [
+                makeSqsRecord(makeTestEvent('1'), 'msg-1'),
+                makeSqsRecord(makeTestEvent('2'), 'msg-2'),
+                makeSqsRecord(makeTestEvent('3'), 'msg-3'),
+            ];
+            const { items, stats, recordMap } = await unbundleRecords(records);
+            expect(items).toHaveLength(3);
+            expect(stats.legacyRecords).toBe(3);
+            expect(stats.totalItems).toBe(3);
+            expect(recordMap.get(items[0])).toBe('msg-1');
+            expect(recordMap.get(items[1])).toBe('msg-2');
+            expect(recordMap.get(items[2])).toBe('msg-3');
+        });
+    });
+    describe('bundled messages (NONE compression)', () => {
+        it('unbundles wrapped messageBody envelope', async () => {
+            const items = [makeTestEvent('b1'), makeTestEvent('b2')];
+            const envelope = makeBundledEnvelope(items);
+            const record = makeSqsRecord({ messageBody: envelope });
+            const { items: result, stats } = await unbundleRecords([record]);
+            expect(result).toHaveLength(2);
+            expect(result[0].eventId).toBe('b1');
+            expect(result[1].eventId).toBe('b2');
+            expect(stats.bundledRecords).toBe(1);
+            expect(stats.legacyRecords).toBe(0);
+        });
+        it('unbundles raw envelope (not wrapped)', async () => {
+            const items = [makeTestEvent('r1'), makeTestEvent('r2')];
+            const envelope = makeBundledEnvelope(items);
+            const record = makeSqsRecord(envelope);
+            const { items: result, stats } = await unbundleRecords([record]);
+            expect(result).toHaveLength(2);
+            expect(stats.bundledRecords).toBe(1);
+        });
+        it('maps all items from bundle to same messageId', async () => {
+            const items = [makeTestEvent('x1'), makeTestEvent('x2'), makeTestEvent('x3')];
+            const envelope = makeBundledEnvelope(items);
+            const record = makeSqsRecord({ messageBody: envelope }, 'bundle-msg-1');
+            const { items: result, recordMap } = await unbundleRecords([record]);
+            expect(result).toHaveLength(3);
+            expect(recordMap.get(result[0])).toBe('bundle-msg-1');
+            expect(recordMap.get(result[1])).toBe('bundle-msg-1');
+            expect(recordMap.get(result[2])).toBe('bundle-msg-1');
+        });
+    });
+    describe('bundled messages (ZSTD compression)', () => {
+        it('unbundles ZSTD compressed envelope', async () => {
+            const items = [makeTestEvent('z1'), makeTestEvent('z2')];
+            const envelope = await makeCompressedEnvelope(items);
+            const record = makeSqsRecord({ messageBody: envelope });
+            const { items: result, stats } = await unbundleRecords([record]);
+            expect(result).toHaveLength(2);
+            expect(result[0].eventId).toBe('z1');
+            expect(result[1].eventId).toBe('z2');
+            expect(stats.bundledRecords).toBe(1);
+        });
+        it('handles large compressed bundles (500 items)', async () => {
+            const items = Array.from({ length: 500 }, (_, i) => makeTestEvent(`item-${i}`));
+            const envelope = await makeCompressedEnvelope(items);
+            const record = makeSqsRecord({ messageBody: envelope });
+            const { items: result, stats } = await unbundleRecords([record]);
+            expect(result).toHaveLength(500);
+            expect(stats.bundledRecords).toBe(1);
+            expect(stats.totalItems).toBe(500);
+        });
+    });
+    describe('mixed message formats', () => {
+        it('handles mix of legacy and bundled messages', async () => {
+            const legacyEvent = makeTestEvent('legacy-1');
+            const bundledItems = [makeTestEvent('bundled-1'), makeTestEvent('bundled-2')];
+            const bundleEnvelope = makeBundledEnvelope(bundledItems);
+            const records = [
+                makeSqsRecord(legacyEvent, 'msg-legacy'),
+                makeSqsRecord({ messageBody: bundleEnvelope }, 'msg-bundle'),
+            ];
+            const { items, stats, recordMap } = await unbundleRecords(records);
+            expect(items).toHaveLength(3);
+            expect(stats.legacyRecords).toBe(1);
+            expect(stats.bundledRecords).toBe(1);
+            expect(stats.totalItems).toBe(3);
+            expect(recordMap.get(items[0])).toBe('msg-legacy');
+            expect(recordMap.get(items[1])).toBe('msg-bundle');
+            expect(recordMap.get(items[2])).toBe('msg-bundle');
+        });
+        it('handles mix of NONE and ZSTD compressed bundles', async () => {
+            const noneItems = [makeTestEvent('none-1')];
+            const zstdItems = [makeTestEvent('zstd-1'), makeTestEvent('zstd-2')];
+            const noneEnvelope = makeBundledEnvelope(noneItems);
+            const zstdEnvelope = await makeCompressedEnvelope(zstdItems);
+            const records = [
+                makeSqsRecord({ messageBody: noneEnvelope }, 'msg-none'),
+                makeSqsRecord({ messageBody: zstdEnvelope }, 'msg-zstd'),
+            ];
+            const { items, stats } = await unbundleRecords(records);
+            expect(items).toHaveLength(3);
+            expect(stats.bundledRecords).toBe(2);
+            expect(stats.totalItems).toBe(3);
+        });
+    });
+    describe('error handling', () => {
+        it('returns failed messageId for invalid JSON', async () => {
+            const records = [
+                makeSqsRecord('not-valid-json{{{', 'msg-bad'),
+                makeSqsRecord(makeTestEvent('good'), 'msg-good'),
+            ];
+            const { items, failedMessageIds, stats } = await unbundleRecords(records);
+            expect(items).toHaveLength(1);
+            expect(items[0].eventId).toBe('good');
+            expect(failedMessageIds).toEqual(['msg-bad']);
+            expect(stats.failedRecords).toBe(1);
+            expect(stats.legacyRecords).toBe(1);
+        });
+        it('returns failed messageId for corrupt compressed data', async () => {
+            const corruptEnvelope = {
+                v: 1,
+                c: CompressionAlgorithm.ZSTD,
+                n: 10,
+                p: 'dGhpcyBpcyBub3QgdmFsaWQgenN0ZA==',
+            };
+            const records = [
+                makeSqsRecord({ messageBody: corruptEnvelope }, 'msg-corrupt'),
+                makeSqsRecord(makeTestEvent('valid'), 'msg-valid'),
+            ];
+            const { items, failedMessageIds, stats } = await unbundleRecords(records);
+            expect(items).toHaveLength(1);
+            expect(items[0].eventId).toBe('valid');
+            expect(failedMessageIds).toContain('msg-corrupt');
+            expect(stats.failedRecords).toBe(1);
+        });
+        it('returns empty result for all failed records', async () => {
+            const records = [
+                makeSqsRecord('invalid-1', 'msg-1'),
+                makeSqsRecord('invalid-2', 'msg-2'),
+            ];
+            const { items, failedMessageIds, stats } = await unbundleRecords(records);
+            expect(items).toHaveLength(0);
+            expect(failedMessageIds).toEqual(['msg-1', 'msg-2']);
+            expect(stats.failedRecords).toBe(2);
+            expect(stats.totalItems).toBe(0);
+        });
+        it('handles empty records array', async () => {
+            const { items, failedMessageIds, stats } = await unbundleRecords([]);
+            expect(items).toHaveLength(0);
+            expect(failedMessageIds).toHaveLength(0);
+            expect(stats.totalRecords).toBe(0);
+            expect(stats.totalItems).toBe(0);
+        });
+        it('rejects payload exceeding max decompressed size', async () => {
+            const largeItems = Array.from({ length: 1000 }, (_, i) => ({
+                id: `item-${i}`,
+                data: 'x'.repeat(1000),
+            }));
+            const envelope = await makeCompressedEnvelope(largeItems);
+            const record = makeSqsRecord({ messageBody: envelope }, 'msg-too-large');
+            const { failedMessageIds, stats } = await unbundleRecords([record], {
+                maxDecompressedSizeBytes: 100 * 1024,
+            });
+            expect(failedMessageIds).toContain('msg-too-large');
+            expect(stats.failedRecords).toBe(1);
+        });
+        it('fails on invalid base64 in compressed payload', async () => {
+            const badEnvelope = {
+                v: 1,
+                c: CompressionAlgorithm.ZSTD,
+                n: 1,
+                s: 100,
+                p: '!!!not-valid-base64!!!',
+            };
+            const record = makeSqsRecord({ messageBody: badEnvelope }, 'msg-bad-base64');
+            const { failedMessageIds } = await unbundleRecords([record]);
+            expect(failedMessageIds).toContain('msg-bad-base64');
+        });
+    });
+    describe('bundle format edge cases', () => {
+        it('successfully unbundles even when n does not match actual item count', async () => {
+            const envelope = {
+                v: 1,
+                c: CompressionAlgorithm.NONE,
+                n: 5,
+                s: 50,
+                p: [makeTestEvent('1'), makeTestEvent('2')],
+            };
+            const record = makeSqsRecord({ messageBody: envelope });
+            const { items } = await unbundleRecords([record]);
+            expect(items).toHaveLength(2);
+        });
+        it('treats envelope with unsupported version as legacy message', async () => {
+            const badEnvelope = { v: 99, c: 'none', n: 1, s: 10, p: [] };
+            const record = makeSqsRecord({ messageBody: badEnvelope }, 'msg-bad-version');
+            const { items, stats } = await unbundleRecords([record]);
+            expect(items).toHaveLength(1);
+            expect(items[0].v).toBe(99);
+            expect(stats.legacyRecords).toBe(1);
+            expect(stats.bundledRecords).toBe(0);
+        });
+    });
+    describe('timeout protection', () => {
+        it('respects timeoutMs option', async () => {
+            const items = [makeTestEvent('1')];
+            const envelope = await makeCompressedEnvelope(items);
+            const record = makeSqsRecord({ messageBody: envelope });
+            const { items: result, failedMessageIds } = await unbundleRecords([record], {
+                timeoutMs: 5000,
+            });
+            expect(result).toHaveLength(1);
+            expect(failedMessageIds).toHaveLength(0);
+        });
+        it('passes timeoutMs through to decompression', async () => {
+            const items = [makeTestEvent('1')];
+            const envelope = await makeCompressedEnvelope(items);
+            const record = makeSqsRecord({ messageBody: envelope });
+            await expect(unbundleRecords([record], { timeoutMs: 30000 })).resolves.toBeDefined();
+        });
+        it('CompressionTimeoutError is properly exported', () => {
+            const error = new CompressionTimeoutError(CompressionOperation.DECOMPRESS, 5000);
+            expect(error).toBeInstanceOf(Error);
+            expect(error.name).toBe('CompressionTimeoutError');
+            expect(error.operation).toBe('decompress');
+            expect(error.timeoutMs).toBe(5000);
+            expect(error.message).toContain('timed out after 5000ms');
+        });
+        it('includes timeout info in failure logging', async () => {
+            const corruptEnvelope = {
+                v: 1,
+                c: CompressionAlgorithm.ZSTD,
+                n: 1,
+                s: 100,
+                p: 'dGhpcyBpcyBub3QgdmFsaWQgenN0ZA==',
+            };
+            const record = makeSqsRecord({ messageBody: corruptEnvelope }, 'msg-timeout-test');
+            const { failedMessageIds } = await unbundleRecords([record], {
+                timeoutMs: 5000,
+            });
+            expect(failedMessageIds).toContain('msg-timeout-test');
+        });
+    });
+    describe('end-to-end: producer bundle → consumer unbundle', () => {
+        it('simulates full bundle → unbundle flow with compression', async () => {
+            const producerItems = Array.from({ length: 100 }, (_, i) => makeTestEvent(`event-${i}`, 'page_view', i * 1.5));
+            const envelope = await makeCompressedEnvelope(producerItems, 3);
+            const sqsMessageBody = { messageBody: envelope };
+            const consumerRecord = makeSqsRecord(sqsMessageBody, 'sqs-message-id-123');
+            const { items, recordMap, stats } = await unbundleRecords([consumerRecord]);
+            expect(items).toHaveLength(100);
+            expect(items[0]).toEqual({ eventId: 'event-0', name: 'page_view', value: 0 });
+            expect(items[99]).toEqual({ eventId: 'event-99', name: 'page_view', value: 148.5 });
+            expect(stats.bundledRecords).toBe(1);
+            expect(stats.legacyRecords).toBe(0);
+            expect(stats.totalItems).toBe(100);
+            for (const item of items) {
+                expect(recordMap.get(item)).toBe('sqs-message-id-123');
+            }
+        });
+        it('simulates mixed batch with legacy and bundled messages', async () => {
+            const legacyRecord1 = makeSqsRecord({ messageBody: makeTestEvent('legacy-1', 'purchase', 99.99) }, 'legacy-msg-1');
+            const legacyRecord2 = makeSqsRecord(makeTestEvent('legacy-2', 'add_to_cart', 29.99), 'legacy-msg-2');
+            const bundledItems = [
+                makeTestEvent('bundled-1', 'page_view'),
+                makeTestEvent('bundled-2', 'session_start'),
+                makeTestEvent('bundled-3', 'page_end'),
+            ];
+            const envelope = await makeCompressedEnvelope(bundledItems);
+            const bundledRecord = makeSqsRecord({ messageBody: envelope }, 'bundled-msg-1');
+            const records = [legacyRecord1, bundledRecord, legacyRecord2];
+            const { items, stats, recordMap } = await unbundleRecords(records);
+            expect(items).toHaveLength(5);
+            expect(stats.legacyRecords).toBe(2);
+            expect(stats.bundledRecords).toBe(1);
+            expect(stats.totalItems).toBe(5);
+            expect(recordMap.get(items[0])).toBe('legacy-msg-1');
+            expect(recordMap.get(items[1])).toBe('bundled-msg-1');
+            expect(recordMap.get(items[2])).toBe('bundled-msg-1');
+            expect(recordMap.get(items[3])).toBe('bundled-msg-1');
+            expect(recordMap.get(items[4])).toBe('legacy-msg-2');
+        });
+    });
+    describe('consumer edge cases - real sequences', () => {
+        it('handles 500 items in single compressed bundle with exact verification', async () => {
+            const originalItems = Array.from({ length: 500 }, (_, i) => ({
+                id: `item-${i}`,
+                name: `Event ${i}`,
+                data: { nested: { value: i * 1.5 } },
+                timestamp: Date.now() + i,
+            }));
+            const envelope = await makeCompressedEnvelope(originalItems);
+            const record = makeSqsRecord({ messageBody: envelope }, 'msg-500-items');
+            const { items, recordMap, stats } = await unbundleRecords([record]);
+            expect(items).toHaveLength(500);
+            expect(items[0]).toEqual(originalItems[0]);
+            expect(items[249]).toEqual(originalItems[249]);
+            expect(items[499]).toEqual(originalItems[499]);
+            expect(stats.bundledRecords).toBe(1);
+            expect(stats.totalItems).toBe(500);
+            for (let i = 0; i < 500; i++) {
+                expect(items[i].id).toBe(`item-${i}`);
+                expect(items[i].data.nested.value).toBe(i * 1.5);
+            }
+            for (const item of items) {
+                expect(recordMap.get(item)).toBe('msg-500-items');
+            }
+        });
+        it('handles multiple bundles in single batch with different item counts', async () => {
+            const counts = [10, 50, 100, 200, 300];
+            const records = [];
+            const expectedTotal = counts.reduce((sum, c) => sum + c, 0);
+            for (let bundleIdx = 0; bundleIdx < counts.length; bundleIdx++) {
+                const count = counts[bundleIdx];
+                const items = Array.from({ length: count }, (_, i) => ({
+                    bundleId: bundleIdx,
+                    itemIdx: i,
+                    payload: `bundle-${bundleIdx}-item-${i}`,
+                }));
+                const envelope = await makeCompressedEnvelope(items);
+                records.push(makeSqsRecord({ messageBody: envelope }, `msg-bundle-${bundleIdx}`));
+            }
+            const { items, recordMap, stats } = await unbundleRecords(records);
+            expect(items).toHaveLength(expectedTotal);
+            expect(stats.totalItems).toBe(expectedTotal);
+            expect(stats.bundledRecords).toBe(5);
+            expect(stats.legacyRecords).toBe(0);
+            expect(stats.failedRecords).toBe(0);
+            const itemsByBundle = new Map();
+            for (const item of items) {
+                const expectedMsgId = `msg-bundle-${item.bundleId}`;
+                expect(recordMap.get(item)).toBe(expectedMsgId);
+                itemsByBundle.set(item.bundleId, (itemsByBundle.get(item.bundleId) ?? 0) + 1);
+            }
+            expect(itemsByBundle.get(0)).toBe(10);
+            expect(itemsByBundle.get(1)).toBe(50);
+            expect(itemsByBundle.get(2)).toBe(100);
+            expect(itemsByBundle.get(3)).toBe(200);
+            expect(itemsByBundle.get(4)).toBe(300);
+        });
+        it('handles realistic 80% bundled / 20% legacy migration ratio', async () => {
+            const records = [];
+            const totalMessages = 100;
+            const bundledCount = 80;
+            const legacyCount = 20;
+            const itemsPerBundle = 25;
+            for (let i = 0; i < bundledCount; i++) {
+                const items = Array.from({ length: itemsPerBundle }, (_, j) => ({
+                    type: 'bundled',
+                    bundleIdx: i,
+                    itemIdx: j,
+                }));
+                const envelope = await makeCompressedEnvelope(items);
+                records.push(makeSqsRecord({ messageBody: envelope }, `msg-bundled-${i}`));
+            }
+            for (let i = 0; i < legacyCount; i++) {
+                const legacyEvent = {
+                    type: 'legacy',
+                    legacyIdx: i,
+                    itemIdx: 0,
+                };
+                records.push(makeSqsRecord(legacyEvent, `msg-legacy-${i}`));
+            }
+            const shuffled = [...records].sort(() => Math.random() - 0.5);
+            const { items, stats, recordMap } = await unbundleRecords(shuffled);
+            expect(stats.totalRecords).toBe(totalMessages);
+            expect(stats.bundledRecords).toBe(bundledCount);
+            expect(stats.legacyRecords).toBe(legacyCount);
+            expect(stats.failedRecords).toBe(0);
+            expect(items).toHaveLength(bundledCount * itemsPerBundle + legacyCount);
+            expect(stats.totalItems).toBe(2020);
+            const bundledItems = items.filter((i) => i.type === 'bundled');
+            const legacyItems = items.filter((i) => i.type === 'legacy');
+            expect(bundledItems).toHaveLength(bundledCount * itemsPerBundle);
+            expect(legacyItems).toHaveLength(legacyCount);
+            for (const item of bundledItems) {
+                expect(recordMap.get(item)).toBe(`msg-bundled-${item.bundleIdx}`);
+            }
+            for (const item of legacyItems) {
+                expect(recordMap.get(item)).toBe(`msg-legacy-${item.legacyIdx}`);
+            }
+        });
+        it('preserves Unicode characters through ZSTD compression', async () => {
+            const unicodeItems = [
+                {
+                    id: 'emoji',
+                    content: '🎉🚀💻🌍✨ Party time!',
+                    description: 'Emojis should survive compression',
+                },
+                {
+                    id: 'chinese',
+                    content: '中文测试：欢迎使用我们的服务',
+                    description: 'Chinese characters',
+                },
+                {
+                    id: 'arabic',
+                    content: 'العربية: مرحبا بكم في خدمتنا',
+                    description: 'Arabic text (RTL)',
+                },
+                {
+                    id: 'math',
+                    content: '∑∫∂∇ε → ∞ × ∈ ⊆ ∀∃',
+                    description: 'Mathematical symbols',
+                },
+                {
+                    id: 'mixed',
+                    content: 'Hello 世界 🌏 مرحبا ∑ Привет',
+                    description: 'Mixed scripts',
+                },
+                {
+                    id: 'special',
+                    content: '️️️️️️️️️️️️️️️️',
+                    description: 'Unicode edge cases',
+                },
+                {
+                    id: 'japanese',
+                    content: 'こんにちは世界 ひらがな カタカナ 漢字',
+                    description: 'Japanese hiragana, katakana, kanji',
+                },
+                {
+                    id: 'korean',
+                    content: '안녕하세요 세계',
+                    description: 'Korean hangul',
+                },
+                {
+                    id: 'cyrillic',
+                    content: 'Привет мир! Это тест.',
+                    description: 'Russian Cyrillic',
+                },
+                {
+                    id: 'combining',
+                    content: 'e\u0301 n\u0303 c\u0327',
+                    description: 'Combining diacritical marks',
+                },
+            ];
+            const envelope = await makeCompressedEnvelope(unicodeItems);
+            const record = makeSqsRecord({ messageBody: envelope }, 'msg-unicode');
+            const { items } = await unbundleRecords([record]);
+            expect(items).toHaveLength(unicodeItems.length);
+            for (let i = 0; i < unicodeItems.length; i++) {
+                expect(items[i].id).toBe(unicodeItems[i].id);
+                expect(items[i].content).toBe(unicodeItems[i].content);
+                expect(items[i].description).toBe(unicodeItems[i].description);
+                const originalBytes = Buffer.from(unicodeItems[i].content, 'utf8');
+                const recoveredBytes = Buffer.from(items[i].content, 'utf8');
+                expect(recoveredBytes.equals(originalBytes)).toBe(true);
+            }
+        });
+        it('preserves deeply nested structures (10 levels)', async () => {
+            function createDeepStructure(depth, maxDepth = 10) {
+                const node = {
+                    level: depth,
+                    data: `level-${depth}-data-${Math.random().toString(36).slice(2)}`,
+                };
+                if (depth < maxDepth) {
+                    node.child = createDeepStructure(depth + 1, maxDepth);
+                    node.siblings = [
+                        createDeepStructure(depth + 1, Math.min(depth + 3, maxDepth)),
+                        createDeepStructure(depth + 1, Math.min(depth + 2, maxDepth)),
+                    ];
+                }
+                return node;
+            }
+            const deepItems = Array.from({ length: 10 }, (_, i) => ({
+                id: `deep-${i}`,
+                nested: createDeepStructure(0, 10),
+                arrays: [
+                    [[[[['deeply', 'nested', 'array']]], [{ inner: { value: i } }]]],
+                ],
+            }));
+            const envelope = await makeCompressedEnvelope(deepItems);
+            const record = makeSqsRecord({ messageBody: envelope }, 'msg-deep');
+            const { items } = await unbundleRecords([record]);
+            expect(items).toHaveLength(10);
+            for (let i = 0; i < 10; i++) {
+                expect(JSON.stringify(items[i])).toBe(JSON.stringify(deepItems[i]));
+                expect(items[i].nested.level).toBe(0);
+                expect(items[i].nested.child?.level).toBe(1);
+                expect(items[i].nested.child?.child?.child?.level).toBe(3);
+                expect(items[i].arrays[0][0][0][0][0][0]).toBe('deeply');
+            }
+        });
+        it('handles binary-like string data (base64 encoded)', async () => {
+            const binaryItems = [
+                {
+                    id: 'small-binary',
+                    base64Data: Buffer.from('Small binary payload').toString('base64'),
+                    size: 'small',
+                },
+                {
+                    id: 'medium-binary',
+                    base64Data: Buffer.from('x'.repeat(1000)).toString('base64'),
+                    size: 'medium',
+                },
+                {
+                    id: 'image-simulation',
+                    base64Data: Buffer.from([
+                        0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0xff, 0xd8, 0xff, 0xe0,
+                    ]).toString('base64'),
+                    size: 'binary-header',
+                },
+                {
+                    id: 'random-bytes',
+                    base64Data: Buffer.from(Array.from({ length: 256 }, () => Math.floor(Math.random() * 256))).toString('base64'),
+                    size: 'random',
+                },
+                {
+                    id: 'all-byte-values',
+                    base64Data: Buffer.from(Array.from({ length: 256 }, (_, i) => i)).toString('base64'),
+                    size: 'full-range',
+                },
+            ];
+            const envelope = await makeCompressedEnvelope(binaryItems);
+            const record = makeSqsRecord({ messageBody: envelope }, 'msg-binary');
+            const { items } = await unbundleRecords([record]);
+            expect(items).toHaveLength(binaryItems.length);
+            for (let i = 0; i < binaryItems.length; i++) {
+                expect(items[i].id).toBe(binaryItems[i].id);
+                expect(items[i].base64Data).toBe(binaryItems[i].base64Data);
+                const originalDecoded = Buffer.from(binaryItems[i].base64Data, 'base64');
+                const recoveredDecoded = Buffer.from(items[i].base64Data, 'base64');
+                expect(recoveredDecoded.equals(originalDecoded)).toBe(true);
+            }
+        });
+        it('handles concurrent unbundling stress test (100 records in parallel)', async () => {
+            const recordCount = 100;
+            const records = [];
+            for (let i = 0; i < recordCount; i++) {
+                const itemsInBundle = 10 + (i % 20);
+                const items = Array.from({ length: itemsInBundle }, (_, j) => ({
+                    recordIdx: i,
+                    itemIdx: j,
+                    uniqueId: `r${i}-i${j}`,
+                    timestamp: Date.now() + i * 1000 + j,
+                    data: `payload-${i}-${j}-${Math.random().toString(36).slice(2)}`,
+                }));
+                const envelope = await makeCompressedEnvelope(items);
+                records.push(makeSqsRecord({ messageBody: envelope }, `stress-msg-${i}`));
+            }
+            const startTime = Date.now();
+            const { items, recordMap, stats, failedMessageIds } = await unbundleRecords(records);
+            const duration = Date.now() - startTime;
+            expect(failedMessageIds).toHaveLength(0);
+            expect(stats.failedRecords).toBe(0);
+            expect(stats.bundledRecords).toBe(recordCount);
+            const seenUniqueIds = new Set();
+            for (const item of items) {
+                expect(seenUniqueIds.has(item.uniqueId)).toBe(false);
+                seenUniqueIds.add(item.uniqueId);
+                const expectedMsgId = `stress-msg-${item.recordIdx}`;
+                expect(recordMap.get(item)).toBe(expectedMsgId);
+                expect(item.itemIdx).toBeGreaterThanOrEqual(0);
+                expect(item.itemIdx).toBeLessThan(30);
+            }
+            const expectedTotal = Array.from({ length: recordCount }, (_, i) => 10 + (i % 20)).reduce((a, b) => a + b, 0);
+            expect(items).toHaveLength(expectedTotal);
+            expect(stats.totalItems).toBe(expectedTotal);
+            console.log(`Unbundled ${recordCount} records (${stats.totalItems} items) in ${duration}ms`);
+        });
+        it('handles items with all JSON primitive types', async () => {
+            const primitiveItems = [
+                {
+                    id: 'primitives',
+                    stringVal: 'hello',
+                    numberVal: 42,
+                    floatVal: 3.14159265359,
+                    boolTrue: true,
+                    boolFalse: false,
+                    nullVal: null,
+                    emptyString: '',
+                    zero: 0,
+                    negativeNum: -999,
+                    largeNum: Number.MAX_SAFE_INTEGER,
+                    smallNum: Number.MIN_SAFE_INTEGER,
+                    scientificNotation: 1.23e10,
+                },
+                {
+                    id: 'arrays',
+                    emptyArray: [],
+                    numberArray: [1, 2, 3],
+                    mixedArray: [1, 'two', true, null],
+                    nestedArray: [[1, 2], [3, 4], [[5]]],
+                },
+                {
+                    id: 'objects',
+                    emptyObject: {},
+                    nestedObject: { a: { b: { c: 1 } } },
+                    arrayOfObjects: [{ x: 1 }, { y: 2 }],
+                },
+            ];
+            const envelope = await makeCompressedEnvelope(primitiveItems);
+            const record = makeSqsRecord({ messageBody: envelope }, 'msg-primitives');
+            const { items } = await unbundleRecords([record]);
+            expect(items).toHaveLength(3);
+            expect(JSON.stringify(items)).toBe(JSON.stringify(primitiveItems));
+        });
+        it('maintains item order across multiple bundles', async () => {
+            const records = [];
+            let globalIdx = 0;
+            for (let bundleIdx = 0; bundleIdx < 10; bundleIdx++) {
+                const itemCount = 10 + bundleIdx * 5;
+                const items = Array.from({ length: itemCount }, () => ({
+                    globalOrder: globalIdx++,
+                    bundle: bundleIdx,
+                }));
+                const envelope = await makeCompressedEnvelope(items);
+                records.push(makeSqsRecord({ messageBody: envelope }, `order-msg-${bundleIdx}`));
+            }
+            const { items } = await unbundleRecords(records);
+            const bundleGroups = new Map();
+            for (const item of items) {
+                if (!bundleGroups.has(item.bundle)) {
+                    bundleGroups.set(item.bundle, []);
+                }
+                bundleGroups.get(item.bundle)?.push(item.globalOrder);
+            }
+            for (const [, orders] of bundleGroups) {
+                for (let i = 1; i < orders.length; i++) {
+                    expect(orders[i]).toBeGreaterThan(orders[i - 1]);
+                }
+            }
+        });
+        it('handles edge case: single item bundles', async () => {
+            const records = await Promise.all(Array.from({ length: 50 }, async (_, i) => {
+                const items = [{ id: `single-${i}`, value: i }];
+                const envelope = await makeCompressedEnvelope(items);
+                return makeSqsRecord({ messageBody: envelope }, `single-msg-${i}`);
+            }));
+            const { items, stats, recordMap } = await unbundleRecords(records);
+            expect(items).toHaveLength(50);
+            expect(stats.bundledRecords).toBe(50);
+            expect(stats.totalItems).toBe(50);
+            for (let i = 0; i < 50; i++) {
+                const item = items.find((x) => x.value === i);
+                expect(item).toBeDefined();
+                if (!item)
+                    throw new Error(`Expected item with value ${i} to be found`);
+                expect(recordMap.get(item)).toMatch(/single-msg-\d+/);
+            }
+        });
+        it('handles edge case: empty arrays in bundles', async () => {
+            const emptyEnvelope = {
+                v: 1,
+                c: CompressionAlgorithm.NONE,
+                n: 0,
+                p: [],
+            };
+            const record = makeSqsRecord({ messageBody: emptyEnvelope }, 'msg-empty');
+            const { items, stats } = await unbundleRecords([record]);
+            expect(items).toHaveLength(0);
+            expect(stats.bundledRecords).toBe(1);
+            expect(stats.totalItems).toBe(0);
+        });
+    });
+});
+//# sourceMappingURL=sqs-unbundle.spec.js.map