@weapnl/js-junction 0.0.11 → 0.1.0

package/CHANGELOG.md

@@ -2,6 +2,9 @@
 
 ## Unreleased
 
+## v0.1.0
+- Added the Temporary Media Upload functionality.
+
 ## v0.0.11
 - Fixed a bug where cancelled requests would cause issues when cancelling subsequent requests.
 

package/README.md

@@ -12,6 +12,7 @@ This package has support for Typescript (TS).
     - [Creating Models](#creating-models)
     - [Performing Requests](#performing-requests)
     - [Applying Filters and Scopes](#applying-filters-and-scopes)
+    - [Uploading Files with Spatie Medialibrary](#uploading-files-with-spatie-medialibrary)
 
 ## Installation
 ```bash
@@ -371,3 +372,53 @@ api.removeHeader('HEADER NAME HERE'); // Removes the header.
 **Sample response**
 
 After executing a request, the property `response` contains a `Response` object, which has properties `statusCode`, `data` and `validation`.
+
+### Uploading Files with [Spatie Medialibrary](https://spatie.be/docs/laravel-medialibrary/v11/introduction)
+
+#### Step 1: Uploading Files to a Model
+To upload files to a model, use the `upload` function available on the model instance. This function requires two arguments:
+
+1. **Uploaded Files**: An array of files, typically obtained from an input field of `type="file"`.
+2. **Collection Name**: The name of the media [collection](https://spatie.be/docs/laravel-medialibrary/v11/working-with-media-collections/simple-media-collections) to which the files should be attached. This corresponds to the collection defined in your Laravel model.
+
+**Example Usage:**
+```js
+// Retrieve the employee model instance (e.g., Employee with ID 3)
+const employee = Employee.show(3);
+
+// Upload the files to the 'IdentityFiles' collection
+employee.upload(uploadedFiles, 'IdentityFiles');
+```
+
+In this example, `uploadedFiles` is an array of files from an input field, and `'IdentityFiles'` is the name of the media collection on the `Employee` model where these files should be stored.
+
+#### Step 2: Handling the Uploaded Files
+Once the `upload` function is called, the files are sent to the API. The API temporarily stores these files in the media library and returns the media IDs associated with each file. These media IDs are automatically set on the model instance.
+
+#### Step 3: Saving the Model with Attached Media
+After uploading the files, you can call the `.save()` method on the model instance. This step finalizes the process by permanently attaching the uploaded files to the specified media collection on the model. The media IDs stored on the model are now linked to the correct collection in the database.
+
+**Example of Saving the Model:**
+```js
+// Save the employee model with the uploaded files attached
+employee.save();
+```
+
+When the `save()` method is invoked, the model is updated or created (depending on whether it was previously persisted), and the uploaded media files are attached to the correct collection as defined in the earlier steps.
+
+#### Advanced Usage: Uploading Files in Nested Structures
+If your model contains nested relationships, such as an `Employee` model with a `Contact` relationship, you can still use the `upload` function to attach files to the appropriate collection within the nested structure.
+
+**Example with Nested Structure:**
+```js
+// Retrieve the employee model instance
+const employee = Employee.show(3);
+
+// Upload a profile picture to the 'ProfilePicture' collection within the 'Contact' relationship
+employee.contact.upload(uploadedFiles, 'ProfilePicture');
+
+// Save the employee model, including the nested contact with the attached profile picture
+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.

package/index.d.ts

@@ -81,7 +81,7 @@ declare class Request extends Mixins {
     put(data?: object): Promise<this>;
     setKey(key: string): this;
     delete(): Promise<this>;
-    storeFiles(files?: object, data?: object): Promise<this>;
+    storeFiles(files?: object, data?: object, url?: string|null): Promise<this>;
     readonly bodyParameters: object;
     onSuccess<T = any>(callback?: (result: T, data: any) => void): this;
     onError(callback?: (response: Response) => void): this;
@@ -112,6 +112,8 @@ export class Model extends Request {
 
     static relations(): JsonMap;
 
+    static mediaCollections(): JsonMap;
+
     static readonly endpoint: string;
 
     readonly _identifier: number | string;
@@ -128,6 +130,8 @@ export class Model extends Request {
 
     save(extraData?: JsonMap): Promise<Model>;
 
+    upload(files: object|object[], collection: string): Promise<this>;
+
     clone(): Model;
 
     _queryString(identifier?: number | string): string;

package/package.json

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

package/src/builder/model.js

@@ -2,6 +2,7 @@ import Accessors from './properties/accessors';
 import Attributes from './properties/attributes';
 import Counts from './properties/counts';
 import Relations from './properties/relations';
+import MediaCollections from './properties/mediaCollections';
 import Request from '../request';
 
 export default class Model extends Request {
@@ -12,6 +13,7 @@ export default class Model extends Request {
         this._attributes = new Attributes(this);
         this._counts = new Counts(this);
         this._relations = new Relations(this);
+        this._mediaCollections = new MediaCollections(this);
 
         this.setApi(api);
         this.fill(defaults);
@@ -46,6 +48,7 @@ export default class Model extends Request {
             ...this._attributes.toJson(this),
             ...this._counts.toJson(this),
             ...this._relations.toJson(this),
+            ...this._mediaCollections.toJson(this),
         };
     }
 
@@ -96,6 +99,15 @@ export default class Model extends Request {
         return {};
     }
 
+     /**
+     * The media collections of the model
+     *
+     * @returns {Object.<any, Object>}
+     */
+    static mediaCollections () {
+        return {};
+    }
+
     /**
      * @returns {string} Endpoint of the model for the API.
      */
@@ -182,7 +194,7 @@ export default class Model extends Request {
 
         this._response = await this._connection.post(
             this._queryString(),
-            { ...this._attributes.toJson(this), ...extraData },
+            { ...this._attributes.toJson(this), ...this._mediaCollections.toJson(this), ...extraData },
         );
 
         this._connection.removeRequest(this);
@@ -210,7 +222,7 @@ export default class Model extends Request {
 
         this._response = await this._connection.put(
             this._queryString(this._identifier),
-            { ...this._attributes.toJson(this), ...extraData },
+            { ...this._attributes.toJson(this), ...this._mediaCollections.toJson(this), ...extraData },
         );
 
         this._connection.removeRequest(this);
@@ -245,6 +257,32 @@ export default class Model extends Request {
         return !! this._response.data;
     }
 
+    /**
+     * Upload an temporary media file to the API.
+     *
+     * @param {array|File} [files] The uploaded file or files.
+     * @param {string} [collection] The name of the file collection.
+     *
+     * @returns {array} The received media ids.
+     */
+    async upload (files, collection) {
+        this._media ??= {};
+        const filesArray = (Array.isArray(files) ? files : [files]).filter((value) => value !== null);
+
+        if (filesArray.length === 0) {
+            this._media[collection] = {};
+            return;
+        }
+
+        const request = await this.storeFiles({
+            files: _.flatMapDeep(filesArray),
+        }, {}, '/media/upload');
+
+        this._media[collection] = request._response.data;
+
+        return request._response.data;
+    }
+
     /**
      * Save the current model. Based on the value of the identifier `store` or `update` will be called.
      *

package/src/builder/properties/mediaCollections.js

@@ -0,0 +1,28 @@
+/**
+ * @implements {Property}
+ */
+export default class MediaCollections {
+    /**
+     * @param {Model} model Instance of the model.
+     */
+    constructor (model) {
+    }
+
+    /**
+     * @param {Model} model
+     *
+     * @return {Object} The attributes casted to a json object.
+     */
+    toJson (model) {
+        const json = {};
+
+        _.each(model.constructor.mediaCollections(), (options, key) => {
+            const mediaPrefix = '_media.';
+            let value = _.get(model, options.jsonKey ?? mediaPrefix + key, _.get(model, mediaPrefix + _.camelCase(key)));
+
+            _.set(json, mediaPrefix + key, value ?? []);
+        });
+
+        return json;
+    }
+}

package/src/request.js

@@ -165,11 +165,12 @@ export default class Request {
     /**
      * @param {Object} files
      * @param {Object} data
+     * @param {string|null} url
      *
      * @returns {this} The current instance.
      */
-    async storeFiles (files = {}, data = {}) {
-        const url = this.url ?? this.constructor.endpoint;
+    async storeFiles (files = {}, data = {}, url = null) {
+        let queryUrl = url ?? this.url ?? this.constructor.endpoint;
 
         this._connection.cancelRunning(this);
 
@@ -181,13 +182,23 @@ export default class Request {
 
         const formData = this._createFormData(_.merge({}, files, data));
 
+        if (! _.isEmpty(this.bodyParameters)) {
+            queryUrl = `${queryUrl}?${this.bodyParameters}`;
+        }
+
         this._response = await this._connection.post(
-            `${url}?${this.bodyParameters}`,
+            queryUrl,
             formData,
         );
 
         this._connection.removeRequest(this);
 
+        this.setConfig({
+            headers: {
+                'Content-Type': 'application/json',
+            },
+        });
+
         await this.triggerResponseEvents(this._response);
 
         return this;