@karpeleslab/klbfw 0.2.15 → 0.2.17

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@karpeleslab/klbfw",
-  "version": "0.2.15",
+  "version": "0.2.17",
   "description": "Frontend Framework",
   "main": "index.js",
   "types": "index.d.ts",

package/upload.js

@@ -266,10 +266,355 @@ const utils = {
   }
 };
 
+/**
+ * Simple file upload for Node.js consumers
+ *
+ * This function provides a straightforward way to upload a file and get a Promise
+ * that resolves when the upload is complete. It doesn't use global state or the
+ * upload.run() process.
+ *
+ * @param {string} api - API endpoint path (e.g., 'Misc/Debug:testUpload')
+ * @param {Buffer|ArrayBuffer|Uint8Array|File|Object} buffer - File to upload. Can be:
+ *   - A Node.js Buffer
+ *   - An ArrayBuffer
+ *   - A Uint8Array or other TypedArray
+ *   - A browser File object
+ *   - A file-like object with { name, size, type, content, lastModified }
+ *   - A string (will be converted to UTF-8 bytes)
+ * @param {string} [method='POST'] - HTTP method for the initial API call
+ * @param {Object} [params={}] - Additional parameters to send with the upload.
+ *   Can include `filename` and `type` to override defaults.
+ * @param {Object} [context=null] - Request context (uses default context if not provided)
+ * @returns {Promise<Object>} - Resolves with the upload result data
+ *
+ * @example
+ * // Upload a buffer with filename
+ * const buffer = Buffer.from('Hello, World!');
+ * const result = await uploadFile('Misc/Debug:testUpload', buffer, 'POST', {
+ *   filename: 'hello.txt',
+ *   type: 'text/plain'
+ * });
+ *
+ * @example
+ * // Upload with defaults
+ * const result = await uploadFile('Misc/Debug:testUpload', buffer);
+ *
+ * @example
+ * // Upload a File object (browser)
+ * const result = await uploadFile('Misc/Debug:testUpload', fileInput.files[0]);
+ */
+async function uploadFile(api, buffer, method, params, context) {
+    // Handle default values
+    method = method || 'POST';
+    params = params || {};
+
+    // Get context from framework if not provided, and add available values
+    if (!context) {
+        context = fwWrapper.getContext();
+    } else {
+        // Merge with default context values if available
+        const defaultContext = fwWrapper.getContext();
+        if (defaultContext) {
+            context = { ...defaultContext, ...context };
+        }
+    }
+
+    // Normalize buffer to a file-like object
+    let fileObj;
+
+    // Handle string input
+    if (typeof buffer === 'string') {
+        const encoder = new TextEncoder();
+        const uint8Array = encoder.encode(buffer);
+        fileObj = {
+            name: params.filename || 'file.txt',
+            size: uint8Array.length,
+            type: params.type || 'text/plain',
+            lastModified: Date.now(),
+            content: uint8Array.buffer
+        };
+    }
+    // Handle ArrayBuffer
+    else if (buffer instanceof ArrayBuffer) {
+        fileObj = {
+            name: params.filename || 'file.bin',
+            size: buffer.byteLength,
+            type: params.type || 'application/octet-stream',
+            lastModified: Date.now(),
+            content: buffer
+        };
+    }
+    // Handle TypedArray (Uint8Array, etc.)
+    else if (buffer && buffer.buffer instanceof ArrayBuffer) {
+        fileObj = {
+            name: params.filename || 'file.bin',
+            size: buffer.byteLength,
+            type: params.type || 'application/octet-stream',
+            lastModified: Date.now(),
+            content: buffer
+        };
+    }
+    // Handle Node.js Buffer
+    else if (typeof Buffer !== 'undefined' && buffer instanceof Buffer) {
+        fileObj = {
+            name: params.filename || 'file.bin',
+            size: buffer.length,
+            type: params.type || 'application/octet-stream',
+            lastModified: Date.now(),
+            content: buffer
+        };
+    }
+    // Handle browser File object
+    else if (env.isBrowser && typeof File !== 'undefined' && buffer instanceof File) {
+        fileObj = {
+            name: buffer.name || params.filename || 'file.bin',
+            size: buffer.size,
+            type: buffer.type || params.type || 'application/octet-stream',
+            lastModified: buffer.lastModified || Date.now(),
+            browserFile: buffer  // Keep reference to original File for reading
+        };
+    }
+    // Handle file-like object with content property
+    else if (buffer && buffer.content !== undefined) {
+        fileObj = {
+            name: buffer.name || params.filename || 'file.bin',
+            size: buffer.size || buffer.content.byteLength || buffer.content.length,
+            type: buffer.type || params.type || 'application/octet-stream',
+            lastModified: buffer.lastModified || Date.now(),
+            content: buffer.content
+        };
+    }
+    else {
+        throw new Error('Invalid file: must be a Buffer, ArrayBuffer, Uint8Array, File, string, or file-like object with content');
+    }
+
+    // Merge params with file metadata (file metadata takes precedence for these fields)
+    const uploadParams = { ...params };
+    uploadParams.filename = fileObj.name;
+    uploadParams.size = fileObj.size;
+    uploadParams.lastModified = fileObj.lastModified / 1000;
+    uploadParams.type = fileObj.type;
+
+    // Initialize upload with the server
+    const response = await rest.rest(api, method, uploadParams, context);
+    const data = response.data;
+
+    // Method 1: AWS signed multipart upload
+    if (data.Cloud_Aws_Bucket_Upload__) {
+        return doAwsUpload(fileObj, data, context);
+    }
+
+    // Method 2: Direct PUT upload
+    if (data.PUT) {
+        return doPutUpload(fileObj, data, context);
+    }
+
+    throw new Error('Invalid upload response format: no upload method available');
+}
+
+/**
+ * Perform a direct PUT upload (simple upload method)
+ * @private
+ */
+async function doPutUpload(file, uploadInfo, context) {
+    const blockSize = uploadInfo.Blocksize || file.size;
+    const blocks = Math.ceil(file.size / blockSize);
+
+    // Upload blocks with concurrency limit
+    const maxConcurrent = 3;
+
+    // Process blocks in batches
+    for (let i = 0; i < blocks; i += maxConcurrent) {
+        const batch = [];
+        for (let j = i; j < Math.min(i + maxConcurrent, blocks); j++) {
+            batch.push(uploadPutBlock(file, uploadInfo, j, blockSize));
+        }
+
+        await Promise.all(batch);
+    }
+
+    // All blocks done, call completion
+    const completeResponse = await rest.rest(uploadInfo.Complete, 'POST', {}, context);
+    return completeResponse.data;
+}
+
+/**
+ * Upload a single block via PUT
+ * @private
+ */
+async function uploadPutBlock(file, uploadInfo, blockNum, blockSize) {
+    const startByte = blockNum * blockSize;
+    const endByte = Math.min(startByte + blockSize, file.size);
+
+    const arrayBuffer = await readFileSlice(file, startByte, endByte);
+
+    const headers = {
+        'Content-Type': file.type || 'application/octet-stream'
+    };
+
+    // Add Content-Range for multipart PUT
+    const totalBlocks = Math.ceil(file.size / blockSize);
+    if (totalBlocks > 1) {
+        headers['Content-Range'] = `bytes ${startByte}-${endByte - 1}/*`;
+    }
+
+    const response = await utils.fetch(uploadInfo.PUT, {
+        method: 'PUT',
+        body: arrayBuffer,
+        headers: headers
+    });
+
+    if (!response.ok) {
+        throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+    }
+
+    await response.text();
+}
+
+/**
+ * Perform an AWS multipart upload
+ * @private
+ */
+async function doAwsUpload(file, uploadInfo, context) {
+    // Calculate optimal block size (min 5MB for AWS, target ~10k parts)
+    let blockSize = Math.ceil(file.size / 10000);
+    if (blockSize < 5242880) blockSize = 5242880;
+
+    const blocks = Math.ceil(file.size / blockSize);
+
+    // Initialize multipart upload
+    const initResponse = await awsReq(
+        uploadInfo,
+        'POST',
+        'uploads=',
+        '',
+        { 'Content-Type': file.type || 'application/octet-stream', 'X-Amz-Acl': 'private' },
+        context
+    );
+    const initXml = await initResponse.text();
+    const dom = utils.parseXML(initXml);
+    const uploadId = dom.querySelector('UploadId').innerHTML;
+
+    // Upload all parts with concurrency limit
+    const etags = {};
+    const maxConcurrent = 3;
+
+    for (let i = 0; i < blocks; i += maxConcurrent) {
+        const batch = [];
+        for (let j = i; j < Math.min(i + maxConcurrent, blocks); j++) {
+            batch.push(
+                uploadAwsBlock(file, uploadInfo, uploadId, j, blockSize, context)
+                    .then(etag => { etags[j] = etag; })
+            );
+        }
+
+        await Promise.all(batch);
+    }
+
+    // Complete multipart upload
+    let xml = '<CompleteMultipartUpload>';
+    for (let i = 0; i < blocks; i++) {
+        xml += `<Part><PartNumber>${i + 1}</PartNumber><ETag>${etags[i]}</ETag></Part>`;
+    }
+    xml += '</CompleteMultipartUpload>';
+
+    const completeResponse = await awsReq(uploadInfo, 'POST', `uploadId=${uploadId}`, xml, null, context);
+    await completeResponse.text();
+
+    // Call server-side completion handler
+    const finalResponse = await rest.rest(
+        `Cloud/Aws/Bucket/Upload/${uploadInfo.Cloud_Aws_Bucket_Upload__}:handleComplete`,
+        'POST',
+        {},
+        context
+    );
+
+    return finalResponse.data;
+}
+
+/**
+ * Upload a single block to AWS S3
+ * @private
+ */
+async function uploadAwsBlock(file, uploadInfo, uploadId, blockNum, blockSize, context) {
+    const startByte = blockNum * blockSize;
+    const endByte = Math.min(startByte + blockSize, file.size);
+    const awsPartNumber = blockNum + 1; // AWS uses 1-based part numbers
+
+    const arrayBuffer = await readFileSlice(file, startByte, endByte);
+
+    const response = await awsReq(
+        uploadInfo,
+        'PUT',
+        `partNumber=${awsPartNumber}&uploadId=${uploadId}`,
+        arrayBuffer,
+        null,
+        context
+    );
+
+    if (!response.ok) {
+        throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+    }
+
+    const etag = response.headers.get('ETag');
+    await response.text();
+    return etag;
+}
+
+/**
+ * Read a slice of a file as ArrayBuffer
+ * @private
+ */
+function readFileSlice(file, start, end) {
+    return new Promise((resolve, reject) => {
+        // Handle browser File objects
+        if (file.browserFile) {
+            const slice = file.browserFile.slice(start, end);
+            const reader = new FileReader();
+            reader.addEventListener('loadend', () => resolve(reader.result));
+            reader.addEventListener('error', (e) => reject(e));
+            reader.readAsArrayBuffer(slice);
+            return;
+        }
+
+        if (!file.content) {
+            reject(new Error('Cannot read file content - no content property'));
+            return;
+        }
+
+        const content = file.content;
+
+        if (content instanceof ArrayBuffer) {
+            if (start === 0 && end === content.byteLength) {
+                resolve(content);
+            } else {
+                resolve(content.slice(start, end));
+            }
+        } else if (content.buffer instanceof ArrayBuffer) {
+            // TypedArray (Uint8Array, etc.)
+            resolve(content.buffer.slice(content.byteOffset + start, content.byteOffset + end));
+        } else if (typeof Buffer !== 'undefined' && content instanceof Buffer) {
+            // Node.js Buffer
+            const arrayBuffer = content.buffer.slice(
+                content.byteOffset + start,
+                content.byteOffset + Math.min(end, content.byteLength)
+            );
+            resolve(arrayBuffer);
+        } else if (typeof content === 'string') {
+            // String content
+            const encoder = new TextEncoder();
+            const uint8Array = encoder.encode(content.slice(start, end));
+            resolve(uint8Array.buffer);
+        } else {
+            reject(new Error('Unsupported content type'));
+        }
+    });
+}
+
 /**
  * AWS S3 request handler
  * Performs a signed request to AWS S3 using a signature obtained from the server
- * 
+ *
  * @param {Object} upInfo - Upload info including bucket endpoint and key
  * @param {string} method - HTTP method (GET, POST, PUT)
  * @param {string} query - Query parameters
@@ -1168,4 +1513,7 @@ module.exports.upload = (function () {
     };
 
     return upload;
-}());
+}());
+
+// Export simple upload function for Node.js consumers
+module.exports.uploadFile = uploadFile;