@karpeleslab/klbfw 0.2.20 → 0.2.22

package/README.md

@@ -50,6 +50,48 @@ npm run test:integration
 - **Standardized Naming**: Consistent use of camelCase with backward compatibility for legacy APIs
 - **Enhanced Error Handling**: More robust error handling and reporting
 
+## Migrating from upload.append() to uploadFile()
+
+The new `uploadFile()` function provides a simpler Promise-based API for file uploads. Here are the key differences when migrating:
+
+### Return Value
+
+**Legacy `upload.append()`** resolves with an upload object containing the result in `.final`:
+```javascript
+upload.append('Misc/Debug:testUpload', file)
+  .then(result => {
+    console.log(result.final);  // The completion response data
+  });
+```
+
+**New `uploadFile()`** resolves with the full REST response:
+```javascript
+uploadFile('Misc/Debug:testUpload', buffer)
+  .then(response => {
+    console.log(response.data);  // The completion response data
+  });
+```
+
+### Migration Example
+
+Before:
+```javascript
+upload.append('Misc/Debug:testUpload', file, params, context)
+  .then(up => {
+    const data = up.final;
+    // use data
+  });
+```
+
+After:
+```javascript
+uploadFile('Misc/Debug:testUpload', file, 'POST', params, context)
+  .then(response => {
+    const data = response.data;
+    // use data
+  });
+```
+
 # API
 
 ## REST API Methods

package/index.d.ts

@@ -35,7 +35,38 @@ declare function restGet(name: string, params?: Record<string, any>): Promise<an
 declare function restSSE(name: string, method: 'GET', params?: Record<string, any>, context?: Record<string, any>): EventSource;
 
 // Upload module types
-interface UploadOptions {
+
+/** File input types supported by uploadFile */
+type UploadFileInput =
+  | ArrayBuffer
+  | Uint8Array
+  | File
+  | string
+  | { name?: string; size?: number; type?: string; content: ArrayBuffer | Uint8Array | string; lastModified?: number }
+  | NodeJS.ReadableStream;
+
+/** Options for uploadFile */
+interface UploadFileOptions {
+  /** Progress callback (0-1) */
+  onProgress?: (progress: number) => void;
+  /** Error callback - resolve to retry, reject to fail */
+  onError?: (error: Error, context: { phase: string; blockNum?: number; attempt: number }) => Promise<void>;
+}
+
+/** Options for uploadManyFiles */
+interface UploadManyFilesOptions extends UploadFileOptions {
+  /** Progress callback with file-level details */
+  onProgress?: (progress: { fileIndex: number; fileCount: number; fileProgress: number; totalProgress: number }) => void;
+  /** Called when each file completes */
+  onFileComplete?: (info: { fileIndex: number; fileCount: number; result: any }) => void;
+  /** Error callback - context includes fileIndex */
+  onError?: (error: Error, context: { fileIndex: number; phase: string; blockNum?: number; attempt: number }) => Promise<void>;
+  /** Maximum concurrent uploads (1-10, default 3) */
+  concurrency?: number;
+}
+
+/** @deprecated Use uploadFile() instead */
+interface UploadLegacyOptions {
   progress?: (progress: number) => void;
   endpoint?: string;
   headers?: Record<string, string>;
@@ -44,7 +75,40 @@ interface UploadOptions {
   params?: Record<string, any>;
 }
 
-declare function upload(file: File, options?: UploadOptions): Promise<any>;
+/** @deprecated Use uploadFile() instead */
+declare const upload: {
+  init(path: string, params?: Record<string, any>, notify?: (status: any) => void): Promise<any> | ((files: any) => Promise<any>);
+  append(path: string, file: File | object, params?: Record<string, any>, context?: Record<string, any>): Promise<any>;
+  run(): void;
+  getStatus(): { queue: any[]; running: any[]; failed: any[] };
+  resume(): void;
+  cancelItem(uploadId: number): void;
+  deleteItem(uploadId: number): void;
+  pauseItem(uploadId: number): void;
+  resumeItem(uploadId: number): void;
+  retryItem(uploadId: number): void;
+  onprogress?: (status: { queue: any[]; running: any[]; failed: any[] }) => void;
+};
+
+/** Upload a single file. Resolves with the full REST response. */
+declare function uploadFile(
+  api: string,
+  buffer: UploadFileInput,
+  method?: string,
+  params?: Record<string, any>,
+  context?: Record<string, any>,
+  options?: UploadFileOptions
+): Promise<any>;
+
+/** Upload multiple files with concurrency control */
+declare function uploadManyFiles(
+  api: string,
+  files: UploadFileInput[],
+  method?: string,
+  params?: Record<string, any>,
+  context?: Record<string, any>,
+  options?: UploadManyFilesOptions
+): Promise<any[]>;
 
 // Utility types
 declare function getI18N(key: string, args?: Record<string, any>): string;
@@ -78,6 +142,11 @@ export {
   restGet,
   restSSE,
   upload,
+  uploadFile,
+  uploadManyFiles,
   getI18N,
-  trimPrefix
+  trimPrefix,
+  UploadFileInput,
+  UploadFileOptions,
+  UploadManyFilesOptions
 };

package/package.json

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

package/upload.js

@@ -37,7 +37,7 @@ const { env, utils, awsReq, readChunkFromStream, readFileSlice } = require('./up
  * @param {Function} [options.onError] - Error callback(error, context). Can return a Promise
  *   that, if resolved, will cause the failed operation to be retried. Context contains
  *   { phase, blockNum, attempt } for block uploads or { phase, attempt } for other operations.
- * @returns {Promise<Object>} - Resolves with the upload result data
+ * @returns {Promise<Object>} - Resolves with the full REST response
  *
  * @example
  * // Upload a buffer with filename
@@ -290,7 +290,7 @@ async function doPutUpload(file, uploadInfo, context, options) {
         attempt++;
         try {
             const completeResponse = await rest.rest(uploadInfo.Complete, 'POST', {}, context);
-            return completeResponse.data;
+            return completeResponse;
         } catch (error) {
             if (onError) {
                 await onError(error, { phase: 'complete', attempt });
@@ -542,7 +542,7 @@ async function doAwsUpload(file, uploadInfo, context, options) {
                 {},
                 context
             );
-            return finalResponse.data;
+            return finalResponse;
         } catch (error) {
             if (onError) {
                 await onError(error, { phase: 'handleComplete', attempt: handleAttempt });