@weapnl/js-junction 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -2,6 +2,9 @@
 
 ## Unreleased
 
+## v0.3.0
+- Added `chunkUploadsBySize` option on the `Api` class to automatically chunk file uploads across multiple requests when the total size exceeds the configured size.
+
 ## v0.2.0
 - Added `data` propery to `delete` function of a Request to allow sending json data in the delete request.
 - Added `extraData` property to `destroy` function of a Model to allow sending extra json data in the delete request.

package/README.md

@@ -13,6 +13,7 @@ This package has support for Typescript (TS).
     - [Performing Requests](#performing-requests)
     - [Applying Filters and Scopes](#applying-filters-and-scopes)
     - [Uploading Files with Spatie Medialibrary](#uploading-files-with-spatie-medialibrary)
+    - [Chunked Uploads](#chunked-uploads)
 
 ## Installation
 ```bash
@@ -439,3 +440,22 @@ employee.save();
 ```
 
 In this scenario, the uploaded files are linked to the `ProfilePicture` collection within the `Contact` relationship of the `Employee` model. When the `save()` method is called, the files are properly attached within the nested structure.
+
+### Chunked Uploads
+
+When uploading multiple files via the `upload` method, the total combined size may exceed the server's limit, or you may want to split large batches into smaller requests. Use `chunkUploadsBySize` to split files across multiple requests automatically.
+
+**Configuring chunk size:**
+```js
+api.chunkUploadsBySize(10 * 1024 * 1024); // 10 MB per request
+```
+
+**Resetting (single request for all files):**
+```js
+api.chunkUploadsBySize(null); // default behavior
+```
+
+**How it works:**
+- When set, the `upload` method groups files into chunks where the total file size per chunk does not exceed the configured size.
+- Each chunk is uploaded in a separate request; response data is combined automatically.
+- A single file that exceeds the size on its own is sent as its own request.

package/index.d.ts

@@ -9,6 +9,7 @@ declare class Api {
     constructor();
 
     host(host: string): this;
+    chunkUploadsBySize(bytes: number): this;
     suffix(suffix: string): this;
     readonly baseUrl: string;
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@weapnl/js-junction",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "This project allows you to easily consume API's built with Junction.",
   "main": "./src/index.js",
   "scripts": {

package/src/api.js

@@ -12,6 +12,7 @@ export default class Api {
         this.setHeader('X-Requested-With', 'XMLHttpRequest');
 
         this._requests = [];
+        this._chunkUploadSize = null;
 
         this.host('/').suffix('');
 
@@ -29,6 +30,20 @@ export default class Api {
         return this;
     }
 
+    /**
+     * Chunk file uploads into multiple requests when total size exceeds the given size.
+     * Useful when the API has a max upload limit, or to split large batches into smaller requests.
+     *
+     * @param {number} bytes Maximum total file size per request in bytes.
+     *
+     * @returns {this} The current instance.
+     */
+    chunkUploadsBySize (bytes) {
+        this._chunkUploadSize = bytes;
+
+        return this;
+    }
+
     /**
      * @param {string} suffix
      *

package/src/builder/model.js

@@ -302,20 +302,69 @@ export default class Model extends Request {
      */
     async upload (files, collection) {
         this._media ??= {};
-        const filesArray = (Array.isArray(files) ? files : [files]).filter((value) => value !== null);
+        files = _.flatMapDeep(Array.isArray(files) ? files : [files]).filter((value) => value instanceof File);
 
-        if (filesArray.length === 0) {
+        if (files.length === 0) {
             this._media[collection] = {};
             return;
         }
 
-        const request = await this.storeFiles({
-            files: _.flatMapDeep(filesArray),
-        }, {}, '/media/upload');
+        const chunkSize = this._connection.getChunkUploadSize();
 
-        this._media[collection] = request._response.data;
+        const chunks = chunkSize ? this._chunkFilesBySize(files, chunkSize) : [files];
 
-        return request._response.data;
+        let allResponseData = [];
+
+        for (const chunk of chunks) {
+            const request = await this.storeFiles({
+                files: chunk,
+            }, {}, '/media/upload');
+
+            if (request._response.data) {
+                allResponseData = allResponseData.concat(
+                    _.castArray(request._response.data),
+                );
+            }
+        }
+
+        this._media[collection] = allResponseData;
+
+        return allResponseData;
+    }
+
+    /**
+     * Split files into chunks that don't exceed the given max size.
+     * A single file that exceeds the limit will still be sent as its own chunk.
+     *
+     * @param {File[]} files
+     * @param {number} maxSize Maximum total file size per chunk in bytes.
+     *
+     * @returns {File[][]} Array of file arrays (chunks).
+     * @private
+     */
+    _chunkFilesBySize (files, maxSize) {
+        const chunks = [];
+        let currentChunk = [];
+        let currentSize = 0;
+
+        for (const file of files) {
+            const fileSize = file.size || 0;
+
+            if (currentChunk.length > 0 && currentSize + fileSize > maxSize) {
+                chunks.push(currentChunk);
+                currentChunk = [];
+                currentSize = 0;
+            }
+
+            currentChunk.push(file);
+            currentSize += fileSize;
+        }
+
+        if (currentChunk.length > 0) {
+            chunks.push(currentChunk);
+        }
+
+        return chunks;
     }
 
     /**

package/src/connection.js

@@ -33,6 +33,10 @@ export default class Connection {
         return this._config;
     }
 
+    getChunkUploadSize () {
+        return this._api?._chunkUploadSize ?? null;
+    }
+
     setConfig (config) {
         this._config = config;
     }