@devrev/ts-adaas 1.19.4 → 1.19.5

package/dist/multithreading/worker-adapter/worker-adapter.loading.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=worker-adapter.loading.test.d.ts.map

package/dist/multithreading/worker-adapter/worker-adapter.loading.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker-adapter.loading.test.d.ts","sourceRoot":"","sources":["../../../src/multithreading/worker-adapter/worker-adapter.loading.test.ts"],"names":[],"mappings":""}

package/dist/multithreading/worker-adapter/worker-adapter.loading.test.js

@@ -0,0 +1,598 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const state_1 = require("../../state/state");
+const jest_setup_1 = require("../../tests/jest.setup");
+const test_utils_1 = require("../../common/test-utils");
+const types_1 = require("../../types");
+const loading_1 = require("../../types/loading");
+const worker_adapter_1 = require("./worker-adapter");
+jest.mock('../../common/control-protocol', () => ({
+    emit: jest.fn().mockResolvedValue({}),
+}));
+jest.mock('../../mappers/mappers');
+jest.mock('../../uploader/uploader');
+jest.mock('../../repo/repo');
+jest.mock('node:worker_threads', () => ({
+    parentPort: { postMessage: jest.fn() },
+}));
+jest.mock('../../attachments-streaming/attachments-streaming-pool', () => ({
+    AttachmentsStreamingPool: jest.fn().mockImplementation(() => ({
+        streamAll: jest.fn().mockResolvedValue(undefined),
+    })),
+}));
+function makeAdapter(eventType) {
+    const event = (0, test_utils_1.createMockEvent)(jest_setup_1.mockServer.baseUrl, {
+        payload: { event_type: eventType },
+    });
+    const initialState = {
+        attachments: { completed: false },
+        lastSyncStarted: '',
+        lastSuccessfulSyncStarted: '',
+        snapInVersionId: '',
+        toDevRev: {
+            attachmentsMetadata: {
+                artifactIds: [],
+                lastProcessed: 0,
+                lastProcessedAttachmentsIdsList: [],
+            },
+        },
+    };
+    const adapterState = new state_1.State({ event, initialState });
+    const adapter = new worker_adapter_1.WorkerAdapter({ event, adapterState });
+    return { adapter, event, adapterState };
+}
+function makeLoaderItem(devrevId = 'dev-1') {
+    return {
+        id: { devrev: devrevId, external: 'ext-1' },
+        created_date: '',
+        modified_date: '',
+        data: {},
+    };
+}
+function setupLoaderFile(adapter, items, itemType = 'tasks') {
+    adapter['adapterState'].state.fromDevRev = {
+        filesToLoad: [
+            {
+                id: 'artifact-1',
+                file_name: 'file.json',
+                itemType,
+                count: items.length,
+                lineToProcess: 0,
+                completed: false,
+            },
+        ],
+    };
+    adapter['uploader'].getJsonObjectByArtifactId = jest
+        .fn()
+        .mockResolvedValue({ response: items });
+}
+describe(`${worker_adapter_1.WorkerAdapter.name}.loadItemTypes — timeout and unexpected errors`, () => {
+    let adapter;
+    let exitSpy;
+    let emitSpy;
+    beforeEach(() => {
+        jest.clearAllMocks();
+        ({ adapter } = makeAdapter(types_1.EventType.ContinueLoadingData));
+        exitSpy = jest
+            .spyOn(process, 'exit')
+            .mockImplementation(() => undefined);
+        emitSpy = jest.spyOn(adapter, 'emit').mockResolvedValue();
+    });
+    afterEach(() => {
+        exitSpy.mockRestore();
+        jest.restoreAllMocks();
+    });
+    it('should emit DataLoadingProgress and exit on timeout', async () => {
+        // Arrange
+        const items = [makeLoaderItem('dev-1'), makeLoaderItem('dev-2')];
+        setupLoaderFile(adapter, items);
+        adapter.isTimeout = true;
+        const itemTypesToLoad = [
+            { itemType: 'tasks', create: jest.fn(), update: jest.fn() },
+        ];
+        // Act
+        await adapter.loadItemTypes({ itemTypesToLoad });
+        // Assert
+        expect(emitSpy).toHaveBeenCalledWith(types_1.LoaderEventType.DataLoadingProgress);
+        expect(exitSpy).toHaveBeenCalledWith(0);
+    });
+    it('should emit DataLoadingProgress mid-loop when timeout arrives between items', async () => {
+        // Arrange
+        const items = [
+            makeLoaderItem('dev-1'),
+            makeLoaderItem('dev-2'),
+            makeLoaderItem('dev-3'),
+        ];
+        setupLoaderFile(adapter, items);
+        exitSpy.mockRestore();
+        exitSpy = jest.spyOn(process, 'exit').mockImplementation((() => {
+            throw new Error('process.exit');
+        }));
+        let loadItemCallCount = 0;
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/require-await
+        jest.spyOn(adapter, 'loadItem').mockImplementation(async () => {
+            loadItemCallCount++;
+            if (loadItemCallCount === 1) {
+                adapter.isTimeout = true;
+            }
+            return { report: { item_type: 'tasks', updated: 1 } };
+        });
+        const itemTypesToLoad = [
+            { itemType: 'tasks', create: jest.fn(), update: jest.fn() },
+        ];
+        // Act & Assert
+        await expect(adapter.loadItemTypes({ itemTypesToLoad })).rejects.toThrow('process.exit');
+        expect(loadItemCallCount).toBe(1);
+        expect(emitSpy).toHaveBeenCalledWith(types_1.LoaderEventType.DataLoadingProgress);
+    });
+    it('should emit DataLoadingError and exit(1) on unexpected error', async () => {
+        // Arrange
+        adapter['adapterState'].state.fromDevRev = {
+            filesToLoad: [
+                {
+                    id: 'artifact-1',
+                    file_name: 'file1.json',
+                    itemType: 'tasks',
+                    count: 1,
+                    lineToProcess: 0,
+                    completed: false,
+                },
+            ],
+        };
+        adapter['uploader'].getJsonObjectByArtifactId = jest
+            .fn()
+            .mockRejectedValue(new Error('Unexpected network failure'));
+        const itemTypesToLoad = [
+            { itemType: 'tasks', create: jest.fn(), update: jest.fn() },
+        ];
+        // Act
+        await adapter.loadItemTypes({ itemTypesToLoad });
+        // Assert
+        expect(emitSpy).toHaveBeenCalledWith(types_1.LoaderEventType.DataLoadingError, expect.objectContaining({
+            error: expect.objectContaining({
+                message: expect.stringContaining('Error during data loading'),
+            }),
+        }));
+        expect(exitSpy).toHaveBeenCalledWith(1);
+    });
+});
+describe(`${worker_adapter_1.WorkerAdapter.name}.loadItemTypes — loadItem branch coverage via public API`, () => {
+    let adapter;
+    let emitSpy;
+    let exitSpy;
+    const itemTypesToLoad = [
+        { itemType: 'tasks', create: jest.fn(), update: jest.fn() },
+    ];
+    beforeEach(() => {
+        jest.clearAllMocks();
+        ({ adapter } = makeAdapter(types_1.EventType.ContinueLoadingData));
+        emitSpy = jest.spyOn(adapter, 'emit').mockResolvedValue();
+        exitSpy = jest
+            .spyOn(process, 'exit')
+            .mockImplementation(() => undefined);
+        itemTypesToLoad[0].create = jest.fn();
+        itemTypesToLoad[0].update = jest.fn();
+    });
+    afterEach(() => {
+        exitSpy.mockRestore();
+        jest.restoreAllMocks();
+    });
+    it('should accumulate an UPDATED report when the connector updates the item and the mapper sync succeeds', async () => {
+        // Arrange
+        setupLoaderFile(adapter, [makeLoaderItem('dev-1')]);
+        adapter['_mappers'].getByTargetId = jest.fn().mockResolvedValue({
+            data: { sync_mapper_record: { id: 'smr-1' } },
+        });
+        adapter['_mappers'].update = jest.fn().mockResolvedValue({ data: {} });
+        itemTypesToLoad[0].update = jest
+            .fn()
+            .mockResolvedValue({ id: 'ext-updated-1' });
+        // Act
+        const { reports } = await adapter.loadItemTypes({ itemTypesToLoad });
+        // Assert
+        expect(reports).toEqual(expect.arrayContaining([
+            expect.objectContaining({
+                item_type: 'tasks',
+                [loading_1.ActionType.UPDATED]: 1,
+            }),
+        ]));
+        expect(emitSpy).not.toHaveBeenCalled();
+    });
+    it('should fall back to create and accumulate a CREATED report when the mapper record does not exist (404)', async () => {
+        // Arrange
+        setupLoaderFile(adapter, [makeLoaderItem('dev-2')]);
+        const axiosError = { isAxiosError: true, response: { status: 404 } };
+        adapter['_mappers'].getByTargetId = jest.fn().mockRejectedValue(axiosError);
+        adapter['_mappers'].create = jest.fn().mockResolvedValue({ data: {} });
+        itemTypesToLoad[0].create = jest
+            .fn()
+            .mockResolvedValue({ id: 'new-ext-id' });
+        // Act
+        const { reports } = await adapter.loadItemTypes({ itemTypesToLoad });
+        // Assert
+        expect(reports).toEqual(expect.arrayContaining([
+            expect.objectContaining({
+                item_type: 'tasks',
+                [loading_1.ActionType.CREATED]: 1,
+            }),
+        ]));
+        expect(emitSpy).not.toHaveBeenCalled();
+    });
+    it('should emit DataLoadingDelayed and stop processing when the connector signals a rate-limit delay', async () => {
+        // Arrange
+        setupLoaderFile(adapter, [makeLoaderItem('dev-3')]);
+        adapter['_mappers'].getByTargetId = jest.fn().mockResolvedValue({
+            data: { sync_mapper_record: { id: 'smr-1' } },
+        });
+        itemTypesToLoad[0].update = jest.fn().mockResolvedValue({ delay: 15 });
+        // Act
+        await adapter.loadItemTypes({ itemTypesToLoad });
+        // Assert
+        expect(emitSpy).toHaveBeenCalledWith(types_1.LoaderEventType.DataLoadingDelayed, expect.objectContaining({ delay: 15 }));
+    });
+    it('should count the item as FAILED when the update succeeds but the mapper sync throws', async () => {
+        // Arrange
+        setupLoaderFile(adapter, [makeLoaderItem('dev-4')]);
+        adapter['_mappers'].getByTargetId = jest.fn().mockResolvedValue({
+            data: { sync_mapper_record: { id: 'smr-1' } },
+        });
+        adapter['_mappers'].update = jest
+            .fn()
+            .mockRejectedValue(new Error('mapper down'));
+        itemTypesToLoad[0].update = jest.fn().mockResolvedValue({ id: 'ext-id' });
+        // Act
+        const { reports } = await adapter.loadItemTypes({ itemTypesToLoad });
+        // Assert
+        expect(emitSpy).not.toHaveBeenCalled();
+        expect(reports).toBeDefined();
+    });
+    it('should not emit for a non-404 Axios error from the mapper (recorded as item-level error)', async () => {
+        // Arrange
+        setupLoaderFile(adapter, [makeLoaderItem('dev-5')]);
+        const axiosError = {
+            isAxiosError: true,
+            message: 'internal server error',
+            response: { status: 500 },
+        };
+        adapter['_mappers'].getByTargetId = jest.fn().mockRejectedValue(axiosError);
+        // Act
+        await adapter.loadItemTypes({ itemTypesToLoad });
+        // Assert
+        expect(emitSpy).not.toHaveBeenCalled();
+    });
+    it('should handle a null sync_mapper_record gracefully and continue loading', async () => {
+        // Arrange
+        setupLoaderFile(adapter, [makeLoaderItem('dev-6')]);
+        adapter['_mappers'].getByTargetId = jest
+            .fn()
+            .mockResolvedValue({ data: null });
+        // Act
+        const { reports } = await adapter.loadItemTypes({ itemTypesToLoad });
+        // Assert
+        expect(emitSpy).not.toHaveBeenCalled();
+        expect(reports).toBeDefined();
+    });
+});
+describe(`${worker_adapter_1.WorkerAdapter.name}.loadItemTypes — additional branches`, () => {
+    let adapter;
+    let emitSpy;
+    beforeEach(() => {
+        jest.clearAllMocks();
+        ({ adapter } = makeAdapter(types_1.EventType.ContinueLoadingData));
+        emitSpy = jest.spyOn(adapter, 'emit').mockResolvedValue();
+    });
+    afterEach(() => {
+        jest.restoreAllMocks();
+    });
+    it('should return immediately with empty reports when filesToLoad is empty', async () => {
+        // Arrange
+        adapter['adapterState'].state.fromDevRev = { filesToLoad: [] };
+        // Act
+        const result = await adapter.loadItemTypes({
+            itemTypesToLoad: [
+                { itemType: 'tasks', create: jest.fn(), update: jest.fn() },
+            ],
+        });
+        // Assert
+        expect(result.reports).toEqual([]);
+        expect(emitSpy).not.toHaveBeenCalled();
+    });
+    it('should emit DataLoadingError when a file references an item type not in itemTypesToLoad', async () => {
+        // Arrange
+        adapter['adapterState'].state.fromDevRev = {
+            filesToLoad: [
+                {
+                    id: 'art-1',
+                    file_name: 'file.json',
+                    itemType: 'unknown-type',
+                    count: 1,
+                    lineToProcess: 0,
+                    completed: false,
+                },
+            ],
+        };
+        adapter['uploader'].getJsonObjectByArtifactId = jest
+            .fn()
+            .mockResolvedValue({ response: [makeLoaderItem()] });
+        // Act
+        await adapter.loadItemTypes({
+            itemTypesToLoad: [
+                { itemType: 'tasks', create: jest.fn(), update: jest.fn() },
+            ],
+        });
+        // Assert
+        expect(emitSpy).toHaveBeenCalledWith(types_1.LoaderEventType.DataLoadingError, expect.objectContaining({
+            error: expect.objectContaining({
+                message: expect.stringContaining('unknown-type'),
+            }),
+        }));
+    });
+});
+describe(`${worker_adapter_1.WorkerAdapter.name}.loadAttachments — timeout, transformer errors, unexpected errors`, () => {
+    let adapter;
+    let exitSpy;
+    let emitSpy;
+    function setupFilesToLoad(a, items) {
+        a['adapterState'].state.fromDevRev = {
+            filesToLoad: [
+                {
+                    id: 'artifact-1',
+                    file_name: 'attachments.json',
+                    itemType: 'attachment',
+                    count: items.length,
+                    lineToProcess: 0,
+                    completed: false,
+                },
+            ],
+        };
+        a['uploader'].getJsonObjectByArtifactId = jest
+            .fn()
+            .mockResolvedValue({ response: items });
+    }
+    beforeEach(() => {
+        jest.clearAllMocks();
+        ({ adapter } = makeAdapter(types_1.EventType.ContinueLoadingAttachments));
+        exitSpy = jest
+            .spyOn(process, 'exit')
+            .mockImplementation(() => undefined);
+        emitSpy = jest.spyOn(adapter, 'emit').mockResolvedValue();
+    });
+    afterEach(() => {
+        exitSpy.mockRestore();
+        jest.restoreAllMocks();
+    });
+    it('should emit AttachmentLoadingProgress and exit on timeout', async () => {
+        // Arrange
+        const items = [
+            {
+                reference_id: 'ref-1',
+                parent_type: 'task',
+                parent_reference_id: 'parent-1',
+                file_name: 'file.pdf',
+                file_type: 'application/pdf',
+                file_size: 100,
+                url: 'https://example.com/file.pdf',
+                valid_until: '',
+                created_by_id: 'user-1',
+                created_date: '',
+                modified_by_id: 'user-1',
+                modified_date: '',
+            },
+        ];
+        setupFilesToLoad(adapter, items);
+        adapter.isTimeout = true;
+        // Act
+        await adapter.loadAttachments({
+            create: jest.fn(),
+        });
+        // Assert
+        expect(emitSpy).toHaveBeenCalledWith(types_1.LoaderEventType.AttachmentLoadingProgress);
+        expect(exitSpy).toHaveBeenCalledWith(0);
+    });
+    it('should emit AttachmentLoadingError on transformer file error', async () => {
+        // Arrange
+        adapter['adapterState'].state.fromDevRev = {
+            filesToLoad: [
+                {
+                    id: 'bad-artifact',
+                    file_name: 'attachments.json',
+                    itemType: 'attachment',
+                    count: 1,
+                    lineToProcess: 0,
+                    completed: false,
+                },
+            ],
+        };
+        adapter['uploader'].getJsonObjectByArtifactId = jest
+            .fn()
+            .mockResolvedValue({
+            response: null,
+            error: new Error('Artifact not found'),
+        });
+        // Act
+        await adapter.loadAttachments({
+            create: jest.fn(),
+        });
+        // Assert
+        expect(emitSpy).toHaveBeenCalledWith(types_1.LoaderEventType.AttachmentLoadingError, expect.objectContaining({
+            error: expect.objectContaining({
+                message: expect.stringContaining('Transformer file not found'),
+            }),
+        }));
+    });
+    it('should emit AttachmentLoadingError and exit(1) on unexpected error', async () => {
+        // Arrange
+        const items = [
+            {
+                reference_id: 'ref-1',
+                parent_type: 'task',
+                parent_reference_id: 'parent-1',
+                file_name: 'file.pdf',
+                file_type: 'application/pdf',
+                file_size: 100,
+                url: 'https://example.com/file.pdf',
+                valid_until: '',
+                created_by_id: 'user-1',
+                created_date: '',
+                modified_by_id: 'user-1',
+                modified_date: '',
+            },
+        ];
+        setupFilesToLoad(adapter, items);
+        const mockCreate = jest
+            .fn()
+            .mockRejectedValue(new Error('Unexpected API failure'));
+        // Act
+        await adapter.loadAttachments({ create: mockCreate });
+        // Assert
+        expect(emitSpy).toHaveBeenCalledWith(types_1.LoaderEventType.AttachmentLoadingError, expect.objectContaining({
+            error: expect.objectContaining({
+                message: expect.stringContaining('Error during attachment loading'),
+            }),
+        }));
+        expect(exitSpy).toHaveBeenCalledWith(1);
+    });
+});
+describe(`${worker_adapter_1.WorkerAdapter.name}.loadAttachments — additional branches`, () => {
+    let adapter;
+    let emitSpy;
+    beforeEach(() => {
+        jest.clearAllMocks();
+        ({ adapter } = makeAdapter(types_1.EventType.ContinueLoadingAttachments));
+        emitSpy = jest.spyOn(adapter, 'emit').mockResolvedValue();
+    });
+    afterEach(() => {
+        jest.restoreAllMocks();
+    });
+    it('should return immediately with empty reports when fromDevRev is not set', async () => {
+        // Arrange
+        adapter['adapterState'].state.fromDevRev = undefined;
+        // Act
+        const result = await adapter.loadAttachments({ create: jest.fn() });
+        // Assert
+        expect(result.reports).toEqual([]);
+        expect(emitSpy).not.toHaveBeenCalled();
+    });
+    it('should emit AttachmentLoadingDelayed and stop the loop when the connector signals a rate-limit delay', async () => {
+        // Arrange
+        adapter['adapterState'].state.fromDevRev = {
+            filesToLoad: [
+                {
+                    id: 'art-1',
+                    file_name: 'attachments.json',
+                    itemType: 'attachment',
+                    count: 1,
+                    lineToProcess: 0,
+                    completed: false,
+                },
+            ],
+        };
+        adapter['uploader'].getJsonObjectByArtifactId = jest
+            .fn()
+            .mockResolvedValue({
+            response: [
+                {
+                    reference_id: 'ref-1',
+                    parent_type: 'task',
+                    parent_reference_id: 'parent-1',
+                    file_name: 'file.pdf',
+                    file_type: 'application/pdf',
+                    file_size: 100,
+                    url: 'https://example.com/file.pdf',
+                    valid_until: '',
+                    created_by_id: 'user-1',
+                    created_date: '',
+                    modified_by_id: 'user-1',
+                    modified_date: '',
+                },
+            ],
+        });
+        jest
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            .spyOn(adapter, 'loadAttachment')
+            .mockResolvedValue({ rateLimit: { delay: 20 } });
+        // Act
+        await adapter.loadAttachments({ create: jest.fn() });
+        // Assert
+        expect(emitSpy).toHaveBeenCalledWith(types_1.LoaderEventType.AttachmentLoadingDelayed, expect.objectContaining({ delay: 20 }));
+    });
+});
+describe(`${worker_adapter_1.WorkerAdapter.name}.loadAttachment`, () => {
+    let adapter;
+    beforeEach(() => {
+        jest.clearAllMocks();
+        ({ adapter } = makeAdapter(types_1.EventType.ContinueLoadingAttachments));
+    });
+    afterEach(() => {
+        jest.restoreAllMocks();
+    });
+    function makeAttachment() {
+        return {
+            reference_id: 'ref-1',
+            parent_type: 'task',
+            parent_reference_id: 'parent-1',
+            file_name: 'file.pdf',
+            file_type: 'application/pdf',
+            file_size: 100,
+            url: 'https://example.com/file.pdf',
+            valid_until: '',
+            created_by_id: 'user-1',
+            created_date: '',
+            modified_by_id: 'user-1',
+            modified_date: '',
+        };
+    }
+    it('should return a CREATED report when create succeeds', async () => {
+        var _a, _b;
+        // Arrange
+        adapter['_mappers'].create = jest.fn().mockResolvedValue({ data: {} });
+        const create = jest.fn().mockResolvedValue({ id: 'att-ext-1' });
+        // Act
+        const result = await adapter['loadAttachment']({
+            item: makeAttachment(),
+            create,
+        });
+        // Assert
+        expect((_a = result.report) === null || _a === void 0 ? void 0 : _a.item_type).toBe('attachment');
+        expect((_b = result.report) === null || _b === void 0 ? void 0 : _b[loading_1.ActionType.CREATED]).toBe(1);
+    });
+    it('should still return CREATED even when mapper create fails — attachment loading is resilient', async () => {
+        var _a;
+        // Arrange
+        adapter['_mappers'].create = jest
+            .fn()
+            .mockRejectedValue(new Error('mapper failed'));
+        const create = jest.fn().mockResolvedValue({ id: 'att-ext-1' });
+        // Act
+        const result = await adapter['loadAttachment']({
+            item: makeAttachment(),
+            create,
+        });
+        // Assert
+        expect((_a = result.report) === null || _a === void 0 ? void 0 : _a[loading_1.ActionType.CREATED]).toBe(1);
+    });
+    it('should propagate rate-limit delay when the connector signals one', async () => {
+        var _a;
+        // Arrange
+        const create = jest.fn().mockResolvedValue({ delay: 30 });
+        // Act
+        const result = await adapter['loadAttachment']({
+            item: makeAttachment(),
+            create,
+        });
+        // Assert
+        expect((_a = result.rateLimit) === null || _a === void 0 ? void 0 : _a.delay).toBe(30);
+    });
+    it('should return a FAILED report when create returns neither id nor delay', async () => {
+        var _a;
+        // Arrange
+        const create = jest.fn().mockResolvedValue({ id: null, delay: null });
+        // Act
+        const result = await adapter['loadAttachment']({
+            item: makeAttachment(),
+            create,
+        });
+        // Assert
+        expect((_a = result.report) === null || _a === void 0 ? void 0 : _a[loading_1.ActionType.FAILED]).toBe(1);
+    });
+});

package/dist/multithreading/worker-adapter/worker-adapter.serialization.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=worker-adapter.serialization.test.d.ts.map

package/dist/multithreading/worker-adapter/worker-adapter.serialization.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker-adapter.serialization.test.d.ts","sourceRoot":"","sources":["../../../src/multithreading/worker-adapter/worker-adapter.serialization.test.ts"],"names":[],"mappings":""}

package/dist/multithreading/worker-adapter/worker-adapter.serialization.test.js

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const js_jsonl_1 = require("js-jsonl");
+// Pin the serialization contract for items that reach the uploader.
+//
+// The SDK uploads items via Uploader.upload(), which calls jsonl.stringify() on
+// the input. That means user `create`/`update` callbacks and normalizers can
+// silently produce inputs that fail or lose information at the wire boundary:
+//
+//   - Circular references throw "Converting circular structure to JSON"
+//   - BigInt values throw "Do not know how to serialize a BigInt"
+//   - Date objects are converted to ISO strings (information loss: no Date on
+//     the other side, just a string)
+//   - undefined fields are dropped (null fields are preserved)
+//
+// These tests exist to catch regressions in the serialization layer (e.g.,
+// silently switching to a different serializer that masks BigInt or mangles
+// Dates) before they reach production.
+describe('serialization boundary for items uploaded via jsonl', () => {
+    it('throws when an item contains a circular reference', () => {
+        // Arrange
+        const item = { id: 'a' };
+        item.self = item;
+        // Act & Assert
+        expect(() => js_jsonl_1.jsonl.stringify([item])).toThrow(/circular/i);
+    });
+    it('throws when an item contains a BigInt field', () => {
+        // Arrange
+        const item = { id: 'a', counter: BigInt(1) };
+        // Act & Assert
+        expect(() => js_jsonl_1.jsonl.stringify([item])).toThrow(/BigInt/i);
+    });
+    it('serializes Date instances to ISO strings (information loss — consumer receives a string)', () => {
+        // Arrange
+        const item = {
+            id: 'a',
+            created: new Date('2025-01-01T00:00:00.000Z'),
+        };
+        // Act
+        const output = js_jsonl_1.jsonl.stringify([item]);
+        const parsed = JSON.parse(output);
+        // Assert
+        expect(parsed.created).toBe('2025-01-01T00:00:00.000Z');
+        expect(typeof parsed.created).toBe('string');
+    });
+    it('drops undefined fields but preserves null fields', () => {
+        // Arrange
+        const item = {
+            id: 'a',
+            present: null,
+            missing: undefined,
+        };
+        // Act
+        const output = js_jsonl_1.jsonl.stringify([item]);
+        const parsed = JSON.parse(output);
+        // Assert
+        expect(parsed).toEqual({ id: 'a', present: null });
+        expect(parsed).not.toHaveProperty('missing');
+    });
+    it('emits one newline-terminated line per item (jsonl format)', () => {
+        // Arrange
+        const items = [{ id: 'a' }, { id: 'b' }, { id: 'c' }];
+        // Act
+        const output = js_jsonl_1.jsonl.stringify(items);
+        const lines = output.split('\n').filter((l) => l.length > 0);
+        // Assert
+        expect(lines).toHaveLength(3);
+        expect(JSON.parse(lines[0])).toEqual({ id: 'a' });
+        expect(JSON.parse(lines[2])).toEqual({ id: 'c' });
+    });
+});