@trayio/commons 5.19.0 → 5.21.0

package/dist/http/Http.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Http.d.ts","sourceRoot":"","sources":["../../src/http/Http.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"Http.d.ts","sourceRoot":"","sources":["../../src/http/Http.ts"],"names":[],"mappings":"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"}

package/dist/http/Http.js

@@ -43,20 +43,71 @@ exports.MultipartHttpRequestBody = {
         if (value === null || typeof value !== 'object') {
             return TE.left(Error('Multipart body must be an object'));
         }
-        const fields = {};
-        const fileDescriptors = [];
-        Object.entries(value).forEach(([key, val]) => {
-            if (File_1.FileDescriptor.isFileDescriptor(val)) {
-                fileDescriptors.push(val);
-            }
-            else if (!_.isObject(val)) {
-                fields[key] = val;
+        /**
+         * Recursively traverses an object to find FileDescriptors at any nesting level.
+         * Returns an array of paths to FileDescriptors and the descriptors themselves.
+         */
+        const findFileDescriptors = (obj, currentPath = []) => {
+            const result = [];
+            for (const [key, val] of Object.entries(obj)) {
+                const path = [...currentPath, key];
+                if (File_1.FileDescriptor.isFileDescriptor(val)) {
+                    result.push({ path, descriptor: val });
+                }
+                else if (_.isObject(val) && !Array.isArray(val)) {
+                    result.push(...findFileDescriptors(val, path));
+                }
             }
-            else {
-                return TE.left(Error(`Multipart body field '${key}' must be a string, number, boolean or file reference`));
+            return result;
+        };
+        /**
+         * Converts nested object to flat fields structure, skipping objects that
+         * would contain FileDescriptors.
+         */
+        const extractFields = (obj, currentPath = []) => {
+            const fields = {};
+            for (const [key, val] of Object.entries(obj)) {
+                const path = [...currentPath, key];
+                if (File_1.FileDescriptor.isFileDescriptor(val)) {
+                    // Skip FileDescriptors - do nothing
+                }
+                else if (Array.isArray(val)) {
+                    // Serialize arrays as comma-separated strings
+                    const fieldKey = path.join('.');
+                    fields[fieldKey] = val.map(String).join(',');
+                }
+                else if (_.isObject(val)) {
+                    // Recursively extract fields from nested objects
+                    const nestedFields = extractFields(val, path);
+                    Object.assign(fields, nestedFields);
+                }
+                else {
+                    // Primitive values: use dot notation for nested paths
+                    const fieldKey = path.join('.');
+                    fields[fieldKey] = String(val);
+                }
             }
-        });
-        return (0, function_1.pipe)(TE.sequenceArray(fileDescriptors.map((fileReference) => (0, function_1.pipe)(fileStorage.read(fileReference.key), TE.map((file) => ({ key: file.reference.key, file }))))), TE.map((files) => {
+            return fields;
+        };
+        const fileDescriptorPaths = findFileDescriptors(value);
+        // Extract fields, using dot notation for nested structures
+        const fields = extractFields(value);
+        return (0, function_1.pipe)(TE.sequenceArray(fileDescriptorPaths.map(({ path, descriptor }) => (0, function_1.pipe)(fileStorage.read(descriptor.key), TE.map((file) => ({
+            // Use the object path (not the file key) as the form field name
+            // This tells the server where to place the FileDescriptor in the reconstructed object
+            key: path.join('.'),
+            file: {
+                ...file,
+                reference: {
+                    ...file.reference,
+                    // Preserve metadata from original descriptor (especially contentType)
+                    metadata: {
+                        ...file.reference.metadata,
+                        ...descriptor.metadata,
+                    },
+                },
+            },
+        }))))), TE.map((files) => {
             const filesRecord = {};
             files.forEach(({ key, file }) => {
                 filesRecord[key] = file;

package/dist/http/MultipartHttpRequestBody.integration.test.d.ts

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

package/dist/http/MultipartHttpRequestBody.integration.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MultipartHttpRequestBody.integration.test.d.ts","sourceRoot":"","sources":["../../src/http/MultipartHttpRequestBody.integration.test.ts"],"names":[],"mappings":""}

package/dist/http/MultipartHttpRequestBody.integration.test.js

@@ -0,0 +1,520 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const stream_1 = require("stream");
+const http_1 = require("http");
+const formidable_1 = __importDefault(require("formidable"));
+const fs = __importStar(require("fs/promises"));
+const path = __importStar(require("path"));
+const crypto = __importStar(require("crypto"));
+const NodeFsFileStorage_1 = require("../file/NodeFsFileStorage");
+const Http_1 = require("./Http");
+/**
+ * Tests for MultipartHttpRequestBody using a server to receive the requests.
+ *
+ * These tests verify the complete roundtrip:
+ * 1. Client creates multipart body with nested FileDescriptors and fields (flattened to dot-notation)
+ * 2. Client sends HTTP POST with multipart/form-data
+ * 3. Server receives and parses the multipart body (fields remain flat)
+ * 4. File content is byte-for-byte identical (SHA-256 verified)
+ */
+describe('MultipartHttpRequestBody - E2E', () => {
+    let clientStorage;
+    let clientTmpDir;
+    let serverTmpDir;
+    let serverPort;
+    let serverUrl;
+    let server;
+    jest.setTimeout(30000);
+    beforeAll(async () => {
+        // Setup client and server storage directories
+        clientTmpDir = path.join('/tmp', `e2e-client-${Date.now()}-${Math.random().toString(36).substring(7)}`);
+        serverTmpDir = path.join('/tmp', `e2e-server-${Date.now()}-${Math.random().toString(36).substring(7)}`);
+        await fs.mkdir(clientTmpDir, { recursive: true });
+        await fs.mkdir(serverTmpDir, { recursive: true });
+        clientStorage = new NodeFsFileStorage_1.NodeFsFileStorage(clientTmpDir);
+        // Start HTTP server that can receive multipart requests
+        serverPort = 3000 + Math.floor(Math.random() * 1000);
+        serverUrl = `http://localhost:${serverPort}`;
+        server = (0, http_1.createServer)(async (req, res) => {
+            if (req.method === 'POST' && req.url === '/upload') {
+                try {
+                    const form = (0, formidable_1.default)({
+                        uploadDir: serverTmpDir,
+                        keepExtensions: true,
+                        maxFileSize: 100 * 1024 * 1024, // 100MB
+                    });
+                    const [fields, files] = await form.parse(req);
+                    // Flatten formidable fields (array values) to simple strings
+                    const flattenedFields = {};
+                    for (const [key, value] of Object.entries(fields)) {
+                        flattenedFields[key] = Array.isArray(value)
+                            ? value[0]
+                            : value || '';
+                    }
+                    // Read file contents and compute hashes
+                    const fileData = {};
+                    for (const [key, fileArray] of Object.entries(files)) {
+                        if (fileArray && fileArray[0]) {
+                            const file = fileArray[0];
+                            // eslint-disable-next-line no-await-in-loop
+                            const content = await fs.readFile(file.filepath, 'utf-8');
+                            const hash = crypto
+                                .createHash('sha256')
+                                .update(content)
+                                .digest('hex');
+                            fileData[key] = { content, hash };
+                        }
+                    }
+                    res.writeHead(200, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({
+                        fields: flattenedFields,
+                        files: fileData,
+                    }));
+                }
+                catch (error) {
+                    res.writeHead(500, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ error: error.message }));
+                }
+            }
+            else {
+                res.writeHead(404);
+                res.end('Not Found');
+            }
+        });
+        await new Promise((resolve) => {
+            server.listen(serverPort, () => {
+                // eslint-disable-next-line no-console
+                console.log(`E2E test server listening on port ${serverPort}`);
+                resolve();
+            });
+        });
+    });
+    afterAll(async () => {
+        // Cleanup
+        if (server) {
+            await new Promise((resolve) => {
+                server.close(() => resolve());
+            });
+        }
+        try {
+            await fs.rm(clientTmpDir, { recursive: true, force: true });
+            await fs.rm(serverTmpDir, { recursive: true, force: true });
+        }
+        catch (error) {
+            // Ignore cleanup errors
+        }
+    });
+    describe('File Transfer with Nested FileDescriptors', () => {
+        it('should send nested FileDescriptor and receive identical file content', async () => {
+            // 1. Create test file with known content
+            const originalContent = 'This is test file content for E2E validation! 🚀';
+            const originalHash = crypto
+                .createHash('sha256')
+                .update(originalContent)
+                .digest('hex');
+            const fileDescriptor = {
+                _tag: 'FileDescriptor',
+                key: 'test-image-key',
+                metadata: {
+                    name: 'test-image.png',
+                    size: originalContent.length,
+                    contentType: 'image/png',
+                },
+            };
+            // Write file to client storage
+            const writeResult = await clientStorage.write({
+                reference: fileDescriptor,
+                content: stream_1.Readable.from(originalContent),
+            }, undefined)();
+            expect(writeResult._tag).toBe('Right');
+            // 2. Create multipart body with NESTED FileDescriptor
+            const bodyWithNestedFile = {
+                fileName: 'test-image.png',
+                overrideIfPresent: true,
+                imageContent: {
+                    reference: fileDescriptor, // NESTED structure
+                },
+            };
+            const multipartResult = await Http_1.MultipartHttpRequestBody.create(bodyWithNestedFile, clientStorage)();
+            expect(multipartResult._tag).toBe('Right');
+            if (multipartResult._tag === 'Left') {
+                throw new Error(`Failed to create multipart body: ${multipartResult.left.message}`);
+            }
+            const multipartBody = multipartResult.right;
+            // Verify the file was detected in the nested structure
+            // Files are now keyed by their object path, not storage key
+            expect(Object.keys(multipartBody.files)).toContain('imageContent.reference');
+            expect(multipartBody.fields).toHaveProperty('fileName', 'test-image.png');
+            expect(multipartBody.fields).toHaveProperty('overrideIfPresent', 'true');
+            // 3. Send HTTP POST with multipart data
+            // eslint-disable-next-line global-require
+            const FormData = require('form-data');
+            const formData = new FormData();
+            // Add fields
+            for (const [key, value] of Object.entries(multipartBody.fields)) {
+                formData.append(key, value);
+            }
+            // Add files
+            for (const [key, file] of Object.entries(multipartBody.files)) {
+                const chunks = [];
+                // eslint-disable-next-line no-await-in-loop
+                for await (const chunk of file.content) {
+                    chunks.push(Buffer.from(chunk));
+                }
+                const buffer = Buffer.concat(chunks);
+                formData.append(key, buffer, {
+                    filename: file.reference.metadata.name,
+                    contentType: file.reference.metadata.contentType,
+                });
+            }
+            const response = await new Promise((resolve, reject) => {
+                formData.submit(`${serverUrl}/upload`, (err, res) => {
+                    if (err) {
+                        reject(err);
+                        return;
+                    }
+                    let body = '';
+                    res.on('data', (chunk) => {
+                        body += chunk.toString();
+                    });
+                    res.on('end', () => {
+                        try {
+                            const parsed = JSON.parse(body);
+                            if (res.statusCode === 200) {
+                                resolve(parsed);
+                            }
+                            else {
+                                reject(new Error(`Server error: ${parsed.error}`));
+                            }
+                        }
+                        catch (e) {
+                            reject(new Error(`Failed to parse response: ${body}`));
+                        }
+                    });
+                    res.on('error', reject);
+                });
+            });
+            // 4. Verify server received the file correctly
+            // Files are now keyed by object path, not storage key
+            expect(response.files).toBeDefined();
+            expect(response.files['imageContent.reference']).toBeDefined();
+            const receivedFile = response.files['imageContent.reference'];
+            expect(receivedFile.content).toBe(originalContent);
+            expect(receivedFile.hash).toBe(originalHash);
+            // 5. Verify fields were sent correctly
+            expect(response.fields.fileName).toBe('test-image.png');
+            expect(response.fields.overrideIfPresent).toBe('true');
+            // eslint-disable-next-line no-console
+            console.log('✅ Nested FileDescriptor successfully sent and received with identical content!');
+        });
+        it('should handle multiple nested FileDescriptors at different levels', async () => {
+            // Create two test files
+            const content1 = 'First file content';
+            const content2 = 'Second file content';
+            const hash1 = crypto.createHash('sha256').update(content1).digest('hex');
+            const hash2 = crypto.createHash('sha256').update(content2).digest('hex');
+            const fileDescriptor1 = {
+                _tag: 'FileDescriptor',
+                key: 'file-1',
+                metadata: {
+                    name: 'file1.txt',
+                    size: content1.length,
+                    contentType: 'text/plain',
+                },
+            };
+            const fileDescriptor2 = {
+                _tag: 'FileDescriptor',
+                key: 'file-2',
+                metadata: {
+                    name: 'file2.txt',
+                    size: content2.length,
+                    contentType: 'text/plain',
+                },
+            };
+            // Write files to client storage
+            await clientStorage.write({ reference: fileDescriptor1, content: stream_1.Readable.from(content1) }, undefined)();
+            await clientStorage.write({ reference: fileDescriptor2, content: stream_1.Readable.from(content2) }, undefined)();
+            // Create body with multiple nested FileDescriptors
+            const bodyWithMultipleFiles = {
+                rootFile: fileDescriptor1,
+                nested: {
+                    deepFile: {
+                        reference: fileDescriptor2, // Nested level
+                    },
+                },
+                description: 'Multiple files test',
+            };
+            const multipartResult = await Http_1.MultipartHttpRequestBody.create(bodyWithMultipleFiles, clientStorage)();
+            expect(multipartResult._tag).toBe('Right');
+            if (multipartResult._tag === 'Left') {
+                throw new Error(`Failed to create multipart body: ${multipartResult.left.message}`);
+            }
+            const multipartBody = multipartResult.right;
+            // Verify both files were detected
+            // Files are now keyed by their object paths, not storage keys
+            expect(Object.keys(multipartBody.files)).toHaveLength(2);
+            expect(multipartBody.files['rootFile']).toBeDefined();
+            expect(multipartBody.files['nested.deepFile.reference']).toBeDefined();
+            // Send to server
+            // eslint-disable-next-line global-require
+            const FormData = require('form-data');
+            const formData = new FormData();
+            for (const [key, value] of Object.entries(multipartBody.fields)) {
+                formData.append(key, value);
+            }
+            for (const [key, file] of Object.entries(multipartBody.files)) {
+                const chunks = [];
+                // eslint-disable-next-line no-await-in-loop
+                for await (const chunk of file.content) {
+                    chunks.push(Buffer.from(chunk));
+                }
+                const buffer = Buffer.concat(chunks);
+                formData.append(key, buffer, {
+                    filename: file.reference.metadata.name,
+                });
+            }
+            const response = await new Promise((resolve, reject) => {
+                formData.submit(`${serverUrl}/upload`, (err, res) => {
+                    if (err) {
+                        reject(err);
+                        return;
+                    }
+                    let body = '';
+                    res.on('data', (chunk) => {
+                        body += chunk.toString();
+                    });
+                    res.on('end', () => {
+                        try {
+                            const parsed = JSON.parse(body);
+                            if (res.statusCode === 200) {
+                                resolve(parsed);
+                            }
+                            else {
+                                reject(new Error(`Server error: ${parsed.error}`));
+                            }
+                        }
+                        catch (e) {
+                            reject(new Error(`Failed to parse response: ${body}`));
+                        }
+                    });
+                });
+            });
+            // Verify both files received correctly
+            // Files are now keyed by object path, not storage key
+            expect(response.files['rootFile'].content).toBe(content1);
+            expect(response.files['rootFile'].hash).toBe(hash1);
+            expect(response.files['nested.deepFile.reference'].content).toBe(content2);
+            expect(response.files['nested.deepFile.reference'].hash).toBe(hash2);
+            // eslint-disable-next-line no-console
+            console.log('✅ Multiple nested files successfully transferred!');
+        });
+    });
+    describe('Nested Field Structures', () => {
+        it('should properly flatten and unflatten nested field structures', async () => {
+            // Create a test file
+            const fileDescriptor = {
+                _tag: 'FileDescriptor',
+                key: 'test-doc',
+                metadata: { name: 'doc.txt', size: 100, contentType: 'text/plain' },
+            };
+            await clientStorage.write({
+                reference: fileDescriptor,
+                content: stream_1.Readable.from('document content'),
+            }, undefined)();
+            // Create request body with nested structures AND a file
+            const bodyWithNestedStructure = {
+                title: 'Test Document',
+                enabled: true,
+                metadata: {
+                    author: 'John Doe',
+                    version: '1.0',
+                    tags: {
+                        category: 'documentation',
+                        priority: 'high',
+                    },
+                },
+                document: fileDescriptor,
+            };
+            const multipartResult = await Http_1.MultipartHttpRequestBody.create(bodyWithNestedStructure, clientStorage)();
+            expect(multipartResult._tag).toBe('Right');
+            if (multipartResult._tag === 'Left') {
+                throw new Error(`Failed: ${multipartResult.left.message}`);
+            }
+            const multipartBody = multipartResult.right;
+            // Verify client-side flattening happened
+            expect(multipartBody.fields['metadata.author']).toBe('John Doe');
+            expect(multipartBody.fields['metadata.version']).toBe('1.0');
+            expect(multipartBody.fields['metadata.tags.category']).toBe('documentation');
+            expect(multipartBody.fields['metadata.tags.priority']).toBe('high');
+            // Send to server
+            // eslint-disable-next-line global-require
+            const FormData = require('form-data');
+            const formData = new FormData();
+            for (const [key, value] of Object.entries(multipartBody.fields)) {
+                formData.append(key, value);
+            }
+            for (const [key, file] of Object.entries(multipartBody.files)) {
+                const chunks = [];
+                // eslint-disable-next-line no-await-in-loop
+                for await (const chunk of file.content) {
+                    chunks.push(Buffer.from(chunk));
+                }
+                const buffer = Buffer.concat(chunks);
+                formData.append(key, buffer, {
+                    filename: file.reference.metadata.name,
+                });
+            }
+            const response = await new Promise((resolve, reject) => {
+                formData.submit(`${serverUrl}/upload`, (err, res) => {
+                    if (err) {
+                        reject(err);
+                        return;
+                    }
+                    let body = '';
+                    res.on('data', (chunk) => {
+                        body += chunk.toString();
+                    });
+                    res.on('end', () => {
+                        try {
+                            const parsed = JSON.parse(body);
+                            if (res.statusCode === 200) {
+                                resolve(parsed);
+                            }
+                            else {
+                                reject(new Error(`Server error: ${parsed.error}`));
+                            }
+                        }
+                        catch (e) {
+                            reject(new Error(`Parse error: ${body}`));
+                        }
+                    });
+                });
+            });
+            // Verify fields were sent correctly (flat dot-notation)
+            expect(response.fields.title).toBe('Test Document');
+            expect(response.fields.enabled).toBe('true');
+            // Key assertion: nested fields are flattened with dot notation
+            expect(response.fields['metadata.author']).toBe('John Doe');
+            expect(response.fields['metadata.version']).toBe('1.0');
+            expect(response.fields['metadata.tags.category']).toBe('documentation');
+            expect(response.fields['metadata.tags.priority']).toBe('high');
+            // eslint-disable-next-line no-console
+            console.log('✅ Nested field structure properly flattened with dot notation!');
+        });
+        it('should handle Library Service uploadAssetImage scenario', async () => {
+            // Simulates Library Service uploadAssetImage with additional metadata
+            const fileDescriptor = {
+                _tag: 'FileDescriptor',
+                key: 'asset-123',
+                metadata: { name: 'logo.png', size: 2048, contentType: 'image/png' },
+            };
+            await clientStorage.write({
+                reference: fileDescriptor,
+                content: stream_1.Readable.from('image data'),
+            }, undefined)();
+            const bodyLikeLibraryService = {
+                fileName: 'logo.png',
+                overrideIfPresent: true,
+                uploadMetadata: {
+                    source: 'admin-panel',
+                    uploadedBy: {
+                        userId: '123',
+                        userName: 'admin',
+                    },
+                    timestamp: '2026-04-27T00:00:00Z',
+                },
+                imageContent: fileDescriptor,
+            };
+            const multipartResult = await Http_1.MultipartHttpRequestBody.create(bodyLikeLibraryService, clientStorage)();
+            expect(multipartResult._tag).toBe('Right');
+            if (multipartResult._tag === 'Left') {
+                throw new Error(`Failed: ${multipartResult.left.message}`);
+            }
+            const multipartBody = multipartResult.right;
+            // Verify flattening
+            expect(multipartBody.fields['uploadMetadata.source']).toBe('admin-panel');
+            expect(multipartBody.fields['uploadMetadata.uploadedBy.userId']).toBe('123');
+            expect(multipartBody.fields['uploadMetadata.uploadedBy.userName']).toBe('admin');
+            // Send to server
+            // eslint-disable-next-line global-require
+            const FormData = require('form-data');
+            const formData = new FormData();
+            for (const [key, value] of Object.entries(multipartBody.fields)) {
+                formData.append(key, value);
+            }
+            for (const [key, file] of Object.entries(multipartBody.files)) {
+                const chunks = [];
+                // eslint-disable-next-line no-await-in-loop
+                for await (const chunk of file.content) {
+                    chunks.push(Buffer.from(chunk));
+                }
+                const buffer = Buffer.concat(chunks);
+                formData.append(key, buffer, {
+                    filename: file.reference.metadata.name,
+                });
+            }
+            const response = await new Promise((resolve, reject) => {
+                formData.submit(`${serverUrl}/upload`, (err, res) => {
+                    if (err) {
+                        reject(err);
+                        return;
+                    }
+                    let body = '';
+                    res.on('data', (chunk) => {
+                        body += chunk.toString();
+                    });
+                    res.on('end', () => {
+                        try {
+                            const parsed = JSON.parse(body);
+                            if (res.statusCode === 200) {
+                                resolve(parsed);
+                            }
+                            else {
+                                reject(new Error(`Server error: ${parsed.error}`));
+                            }
+                        }
+                        catch (e) {
+                            reject(new Error(`Parse error: ${body}`));
+                        }
+                    });
+                });
+            });
+            // Verify fields were sent correctly (flat dot-notation)
+            expect(response.fields.fileName).toBe('logo.png');
+            expect(response.fields.overrideIfPresent).toBe('true');
+            // Nested metadata flattened with dot notation
+            expect(response.fields['uploadMetadata.source']).toBe('admin-panel');
+            expect(response.fields['uploadMetadata.uploadedBy.userId']).toBe('123');
+            expect(response.fields['uploadMetadata.uploadedBy.userName']).toBe('admin');
+            expect(response.fields['uploadMetadata.timestamp']).toBe('2026-04-27T00:00:00Z');
+            // eslint-disable-next-line no-console
+            console.log('✅ Library Service-like nested structure flattened correctly!');
+        });
+    });
+});

package/dist/http/MultipartHttpRequestBody.unit.test.d.ts

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

package/dist/http/MultipartHttpRequestBody.unit.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MultipartHttpRequestBody.unit.test.d.ts","sourceRoot":"","sources":["../../src/http/MultipartHttpRequestBody.unit.test.ts"],"names":[],"mappings":""}

package/dist/http/MultipartHttpRequestBody.unit.test.js

@@ -0,0 +1,426 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const stream_1 = require("stream");
+const NodeFsFileStorage_1 = require("../file/NodeFsFileStorage");
+const Http_1 = require("./Http");
+/**
+ * Unit tests for MultipartHttpRequestBody.create() function.
+ * These tests verify the client-side flattening logic without HTTP roundtrips.
+ */
+describe('MultipartHttpRequestBody.create', () => {
+    let clientStorage;
+    let tmpDir;
+    beforeAll(async () => {
+        tmpDir = `/tmp/multipart-unit-test-${Date.now()}`;
+        const fs = await Promise.resolve().then(() => __importStar(require('fs/promises')));
+        await fs.mkdir(tmpDir, { recursive: true });
+        clientStorage = new NodeFsFileStorage_1.NodeFsFileStorage(tmpDir);
+    });
+    afterAll(async () => {
+        const fs = await Promise.resolve().then(() => __importStar(require('fs/promises')));
+        try {
+            await fs.rm(tmpDir, { recursive: true, force: true });
+        }
+        catch (error) {
+            // Ignore cleanup errors
+        }
+    });
+    describe('Nested FileDescriptor Detection', () => {
+        it('should detect FileDescriptor at root level', async () => {
+            const fileDescriptor = {
+                _tag: 'FileDescriptor',
+                key: 'root-file',
+                metadata: { name: 'file.txt', size: 100, contentType: 'text/plain' },
+            };
+            await clientStorage.write({ reference: fileDescriptor, content: stream_1.Readable.from('content') }, undefined)();
+            const result = await Http_1.MultipartHttpRequestBody.create({ file: fileDescriptor }, clientStorage)();
+            expect(result._tag).toBe('Right');
+            if (result._tag === 'Right') {
+                // Files are now keyed by object path, not storage key
+                expect(Object.keys(result.right.files)).toContain('file');
+            }
+        });
+        it('should detect FileDescriptor nested one level deep', async () => {
+            const fileDescriptor = {
+                _tag: 'FileDescriptor',
+                key: 'nested-file',
+                metadata: { name: 'file.txt', size: 100, contentType: 'text/plain' },
+            };
+            await clientStorage.write({ reference: fileDescriptor, content: stream_1.Readable.from('content') }, undefined)();
+            const result = await Http_1.MultipartHttpRequestBody.create({
+                data: {
+                    file: fileDescriptor,
+                },
+            }, clientStorage)();
+            expect(result._tag).toBe('Right');
+            if (result._tag === 'Right') {
+                // Files are now keyed by object path, not storage key
+                expect(Object.keys(result.right.files)).toContain('data.file');
+            }
+        });
+        it('should detect FileDescriptor nested multiple levels deep', async () => {
+            const fileDescriptor = {
+                _tag: 'FileDescriptor',
+                key: 'deep-file',
+                metadata: { name: 'file.txt', size: 100, contentType: 'text/plain' },
+            };
+            await clientStorage.write({ reference: fileDescriptor, content: stream_1.Readable.from('content') }, undefined)();
+            const result = await Http_1.MultipartHttpRequestBody.create({
+                level1: {
+                    level2: {
+                        level3: {
+                            file: fileDescriptor,
+                        },
+                    },
+                },
+            }, clientStorage)();
+            expect(result._tag).toBe('Right');
+            if (result._tag === 'Right') {
+                // Files are now keyed by object path, not storage key
+                expect(Object.keys(result.right.files)).toContain('level1.level2.level3.file');
+            }
+        });
+        it('should detect multiple FileDescriptors at different levels', async () => {
+            const file1 = {
+                _tag: 'FileDescriptor',
+                key: 'file-1',
+                metadata: { name: 'file1.txt', size: 100, contentType: 'text/plain' },
+            };
+            const file2 = {
+                _tag: 'FileDescriptor',
+                key: 'file-2',
+                metadata: { name: 'file2.txt', size: 100, contentType: 'text/plain' },
+            };
+            await clientStorage.write({ reference: file1, content: stream_1.Readable.from('content1') }, undefined)();
+            await clientStorage.write({ reference: file2, content: stream_1.Readable.from('content2') }, undefined)();
+            const result = await Http_1.MultipartHttpRequestBody.create({
+                rootFile: file1,
+                nested: {
+                    deepFile: file2,
+                },
+            }, clientStorage)();
+            expect(result._tag).toBe('Right');
+            if (result._tag === 'Right') {
+                expect(Object.keys(result.right.files)).toHaveLength(2);
+                // Files are now keyed by object path, not storage key
+                expect(result.right.files['rootFile']).toBeDefined();
+                expect(result.right.files['nested.deepFile']).toBeDefined();
+            }
+        });
+    });
+    describe('Field Flattening', () => {
+        it('should flatten nested fields with dot notation', async () => {
+            const result = await Http_1.MultipartHttpRequestBody.create({
+                title: 'Test',
+                metadata: {
+                    author: 'John',
+                    version: '1.0',
+                },
+            }, clientStorage)();
+            expect(result._tag).toBe('Right');
+            if (result._tag === 'Right') {
+                expect(result.right.fields.title).toBe('Test');
+                expect(result.right.fields['metadata.author']).toBe('John');
+                expect(result.right.fields['metadata.version']).toBe('1.0');
+            }
+        });
+        it('should flatten deeply nested fields', async () => {
+            const result = await Http_1.MultipartHttpRequestBody.create({
+                level1: {
+                    level2: {
+                        level3: {
+                            value: 'deep',
+                        },
+                    },
+                },
+            }, clientStorage)();
+            expect(result._tag).toBe('Right');
+            if (result._tag === 'Right') {
+                expect(result.right.fields['level1.level2.level3.value']).toBe('deep');
+            }
+        });
+        it('should handle primitive values at root level', async () => {
+            const result = await Http_1.MultipartHttpRequestBody.create({
+                string: 'text',
+                number: 123,
+                boolean: true,
+                null: null,
+            }, clientStorage)();
+            expect(result._tag).toBe('Right');
+            if (result._tag === 'Right') {
+                expect(result.right.fields.string).toBe('text');
+                expect(result.right.fields.number).toBe('123');
+                expect(result.right.fields.boolean).toBe('true');
+                expect(result.right.fields.null).toBe('null');
+            }
+        });
+    });
+    describe('Array Support', () => {
+        it('should serialize arrays as comma-separated strings', async () => {
+            const result = await Http_1.MultipartHttpRequestBody.create({
+                title: 'Test',
+                tags: ['tag1', 'tag2', 'tag3'],
+                nested: {
+                    items: ['a', 'b', 'c'],
+                },
+            }, clientStorage)();
+            expect(result._tag).toBe('Right');
+            if (result._tag === 'Right') {
+                expect(result.right.fields.title).toBe('Test');
+                expect(result.right.fields.tags).toBe('tag1,tag2,tag3');
+                expect(result.right.fields['nested.items']).toBe('a,b,c');
+            }
+        });
+        it('should handle empty arrays', async () => {
+            const result = await Http_1.MultipartHttpRequestBody.create({
+                title: 'Test',
+                tags: [],
+            }, clientStorage)();
+            expect(result._tag).toBe('Right');
+            if (result._tag === 'Right') {
+                expect(result.right.fields.title).toBe('Test');
+                expect(result.right.fields.tags).toBe(''); // Empty array becomes empty string
+            }
+        });
+        it('should handle arrays with mixed types', async () => {
+            const result = await Http_1.MultipartHttpRequestBody.create({
+                values: [1, 'text', true, null],
+            }, clientStorage)();
+            expect(result._tag).toBe('Right');
+            if (result._tag === 'Right') {
+                // All values converted to strings and joined
+                expect(result.right.fields.values).toBe('1,text,true,null');
+            }
+        });
+    });
+    describe('Metadata Preservation', () => {
+        it('should preserve contentType from original descriptor', async () => {
+            const fileDescriptor = {
+                _tag: 'FileDescriptor',
+                key: 'test-file',
+                metadata: {
+                    name: 'image.png',
+                    size: 1024,
+                    contentType: 'image/png',
+                },
+            };
+            await clientStorage.write({ reference: fileDescriptor, content: stream_1.Readable.from('data') }, undefined)();
+            const result = await Http_1.MultipartHttpRequestBody.create({ file: fileDescriptor }, clientStorage)();
+            expect(result._tag).toBe('Right');
+            if (result._tag === 'Right') {
+                // Files are now keyed by object path, not storage key
+                const { file } = result.right.files;
+                expect(file.reference.metadata.contentType).toBe('image/png');
+                expect(file.reference.metadata.name).toBe('image.png');
+            }
+        });
+    });
+    describe('Mixed Structures', () => {
+        it('should handle body with both fields and FileDescriptors', async () => {
+            const fileDescriptor = {
+                _tag: 'FileDescriptor',
+                key: 'doc',
+                metadata: {
+                    name: 'doc.pdf',
+                    size: 2048,
+                    contentType: 'application/pdf',
+                },
+            };
+            await clientStorage.write({ reference: fileDescriptor, content: stream_1.Readable.from('pdf data') }, undefined)();
+            const result = await Http_1.MultipartHttpRequestBody.create({
+                title: 'Document',
+                category: 'report',
+                metadata: {
+                    author: 'Alice',
+                    tags: ['important', 'confidential'],
+                },
+                document: fileDescriptor,
+            }, clientStorage)();
+            expect(result._tag).toBe('Right');
+            if (result._tag === 'Right') {
+                // Check fields
+                expect(result.right.fields.title).toBe('Document');
+                expect(result.right.fields.category).toBe('report');
+                expect(result.right.fields['metadata.author']).toBe('Alice');
+                expect(result.right.fields['metadata.tags']).toBe('important,confidential');
+                // Check file - Files are now keyed by object path, not storage key
+                expect(result.right.files.document).toBeDefined();
+                expect(result.right.files.document.reference.metadata.contentType).toBe('application/pdf');
+            }
+        });
+    });
+    describe('File Field Naming with Object Paths', () => {
+        it('should use object path (not file key) as the form field name for root-level files', async () => {
+            const fileDescriptor = {
+                _tag: 'FileDescriptor',
+                key: 'some-storage-key-123',
+                metadata: {
+                    name: 'document.pdf',
+                    size: 1024,
+                    contentType: 'application/pdf',
+                },
+            };
+            await clientStorage.write({ reference: fileDescriptor, content: stream_1.Readable.from('file content') }, undefined)();
+            const result = await Http_1.MultipartHttpRequestBody.create({
+                file: fileDescriptor,
+            }, clientStorage)();
+            expect(result._tag).toBe('Right');
+            if (result._tag === 'Right') {
+                // The file should be keyed by the object path 'file', not the storage key
+                expect(Object.keys(result.right.files)).toContain('file');
+                expect(result.right.files['file']).toBeDefined();
+            }
+        });
+        it('should use nested object path as form field name for nested files', async () => {
+            const fileDescriptor = {
+                _tag: 'FileDescriptor',
+                key: 'storage-key-456',
+                metadata: {
+                    name: 'attachment.png',
+                    size: 2048,
+                    contentType: 'image/png',
+                },
+            };
+            await clientStorage.write({ reference: fileDescriptor, content: stream_1.Readable.from('image data') }, undefined)();
+            const result = await Http_1.MultipartHttpRequestBody.create({
+                data: {
+                    attachment: fileDescriptor,
+                },
+            }, clientStorage)();
+            expect(result._tag).toBe('Right');
+            if (result._tag === 'Right') {
+                // The file should be keyed by 'data.attachment', not the storage key
+                expect(Object.keys(result.right.files)).toContain('data.attachment');
+                expect(result.right.files['data.attachment']).toBeDefined();
+            }
+        });
+        it('should use deeply nested object path as form field name', async () => {
+            const fileDescriptor = {
+                _tag: 'FileDescriptor',
+                key: 'deep-storage-key',
+                metadata: {
+                    name: 'report.pdf',
+                    size: 5000,
+                    contentType: 'application/pdf',
+                },
+            };
+            await clientStorage.write({ reference: fileDescriptor, content: stream_1.Readable.from('report content') }, undefined)();
+            const result = await Http_1.MultipartHttpRequestBody.create({
+                project: {
+                    documents: {
+                        reports: {
+                            annual: fileDescriptor,
+                        },
+                    },
+                },
+            }, clientStorage)();
+            expect(result._tag).toBe('Right');
+            if (result._tag === 'Right') {
+                // The file should be keyed by the full object path
+                expect(Object.keys(result.right.files)).toContain('project.documents.reports.annual');
+                expect(result.right.files['project.documents.reports.annual']).toBeDefined();
+            }
+        });
+        it('should use correct object paths for multiple files at different levels', async () => {
+            const file1 = {
+                _tag: 'FileDescriptor',
+                key: 'key-1',
+                metadata: {
+                    name: 'file1.txt',
+                    size: 100,
+                    contentType: 'text/plain',
+                },
+            };
+            const file2 = {
+                _tag: 'FileDescriptor',
+                key: 'key-2',
+                metadata: {
+                    name: 'file2.txt',
+                    size: 200,
+                    contentType: 'text/plain',
+                },
+            };
+            const file3 = {
+                _tag: 'FileDescriptor',
+                key: 'key-3',
+                metadata: {
+                    name: 'file3.txt',
+                    size: 300,
+                    contentType: 'text/plain',
+                },
+            };
+            await clientStorage.write({ reference: file1, content: stream_1.Readable.from('content1') }, undefined)();
+            await clientStorage.write({ reference: file2, content: stream_1.Readable.from('content2') }, undefined)();
+            await clientStorage.write({ reference: file3, content: stream_1.Readable.from('content3') }, undefined)();
+            const result = await Http_1.MultipartHttpRequestBody.create({
+                avatar: file1,
+                data: {
+                    document: file2,
+                    nested: {
+                        attachment: file3,
+                    },
+                },
+            }, clientStorage)();
+            expect(result._tag).toBe('Right');
+            if (result._tag === 'Right') {
+                // Each file should be keyed by its object path, not its storage key
+                expect(Object.keys(result.right.files)).toHaveLength(3);
+                expect(result.right.files['avatar']).toBeDefined();
+                expect(result.right.files['data.document']).toBeDefined();
+                expect(result.right.files['data.nested.attachment']).toBeDefined();
+                // Verify storage keys are NOT used as field names
+                expect(result.right.files['key-1']).toBeUndefined();
+                expect(result.right.files['key-2']).toBeUndefined();
+                expect(result.right.files['key-3']).toBeUndefined();
+            }
+        });
+        it('should preserve metadata when using object path as field name', async () => {
+            const fileDescriptor = {
+                _tag: 'FileDescriptor',
+                key: 'some-key',
+                metadata: {
+                    name: 'important.pdf',
+                    size: 999,
+                    contentType: 'application/pdf',
+                },
+            };
+            await clientStorage.write({ reference: fileDescriptor, content: stream_1.Readable.from('pdf data') }, undefined)();
+            const result = await Http_1.MultipartHttpRequestBody.create({
+                nested: {
+                    file: fileDescriptor,
+                },
+            }, clientStorage)();
+            expect(result._tag).toBe('Right');
+            if (result._tag === 'Right') {
+                const file = result.right.files['nested.file'];
+                expect(file).toBeDefined();
+                expect(file.reference.metadata.name).toBe('important.pdf');
+                expect(file.reference.metadata.size).toBe(999);
+                expect(file.reference.metadata.contentType).toBe('application/pdf');
+            }
+        });
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trayio/commons",
-  "version": "5.19.0",
+  "version": "5.21.0",
   "description": "Extensions to the standard/core libraries and basic features",
   "exports": {
     "./*": "./dist/*.js"