@rpldy/uploader - npm Package Compare versions

Comparing version 0.1.7 to 0.1.8

package.json

 {
-  "version": "0.1.7",
+  "version": "0.1.8",
   "name": "@rpldy/uploader",
@@ -21,7 +21,7 @@ "description": "",
     "@rpldy/sender": "^0.1.7",
-    "@rpldy/shared": "^0.1.7",
-    "immer": "^6.0.3"
+    "@rpldy/shared": "^0.1.7"
   },
   "devDependencies": {
-    "flow-bin": "^0.121.0"
+    "flow-bin": "^0.121.0",
+    "immer": "^6.0.3"
   },
@@ -31,3 +31,3 @@ "publishConfig": {
   },
-  "gitHead": "0ac67a2893ef3a684b8cf1834590035065340366"
+  "gitHead": "20fa09a7a5ffa89c05d892175d5d0d9b4d6821cf"
 }

README.md

@@ -6,3 +6,3 @@ # Uploader
 It will handle the processing and send the files to be uploaded to the server.
-Uploader fires Batch & BatchItem lifecycle events that can be listened to as well cancel uploads dynamically. 
+Uploader fires Batch & BatchItem lifecycle [events](#events) that can be listened to as well cancel uploads dynamically. 
 
@@ -13,3 +13,2 @@
 ```shell
-
    $ yarn add @rpldy/uploader
@@ -21,6 +20,27 @@ ```
 ```shell
-
    $ npm i @rpldy/uploader
 ```
 
+## Usage
+
+When in React, you don't need to use this package directly. Uploady will take care of initialization and other aspects (ie: event registration) for you.
+In case you want to create your own uploader instance, you can do it like so:
+
+```javascript
+import createUploader, { UPLOADER_EVENTS } from "@rpldy/uploader";
+
+const uploader = createUploader({ 
+    autoUpload: false,
+    grouped: true,
+    //...
+});
+
+uploader.on(UPLOADER_EVENTS.ITEM_START, (item) => {
+     console.log(`item ${item.id} started uploading`);  
+});
+
+uploader.add(myFile);
+
+```
+
 ## Upload Options
@@ -47,15 +67,210 @@
 
+## Uploader API
 
+### add
+
+_(files: UploadInfo | UploadInfo[], options?: ?UploadOptions) => void_
+
+The way to add file(s) to be uploaded. Second parameters allows to pass different options than
+the ones the instance currently uses for this specific batch. These options will be merged with current instance options.
+ 
+### upload
+
+_() => void_
+
+For batches that were added with autoUpload = false, the upload method must be called for the files to begin uploading.
+
+### abort
+
+_(id?: string) => void_
+
+abort all files being uploaded or a single item by its ID
+   
+### abortBatch
+
+_(id: string) => void_
+
+abort a specific batch by its ID
+
+### update
+ 
+_(options: UploadOptions) => UploaderType_
+
+options parameter will be merged with the instance's existing options
+Returns the uploader instance
+
+###	getOptions
+
+_() => CreateOptions_
+
+get the instance's upload options
+
+###	getPending
+
+_() => [PendingBatch[]](src/types.js#L15)_
+
+get pending batches that were added with autoUpload = false.
+
+###	clearPending
+
+_() => void_
+
+remove all batches that were added with autoUpload = false 
+and were not sent to upload yet.
+
+### on 
+
+_[OnAndOnceMethod](../life-events/src/types.js#29)_
+
+register an event handler
+
+### once 
+
+_[OnAndOnceMethod](../life-events/src/types.js#29)_
+
+register an event handler that will be called only once
+
+### off
+_[OffMethod](../life-events/src/types.js#27)_
+
+unregister an existing event handler
+    
+### registerExtension
+
+_(name: any, Object) => void_
+
+Extensions can only be registered by [enhancers](../../README.md#enhancer).
+If registerExtension is called outside an enhancer, an error will be thrown
+Name must be unique. If not, an error will be thrown
+
+### getExtension
+ 
+_(name: any) => ?Object__
+
+Retrieve a registered extension by its name
+
 ## Events
 
-	[UPLOADER_EVENTS.BATCH_START],
-    [UPLOADER_EVENTS.BATCH_FINISH],
-    [UPLOADER_EVENTS.BATCH_CANCEL],
-    [UPLOADER_EVENTS.BATCH_ABORT],
-    [UPLOADER_EVENTS.ITEM_START],
-    [UPLOADER_EVENTS.ITEM_FINISH],
-    [UPLOADER_EVENTS.ITEM_CANCEL],
-    [UPLOADER_EVENTS.ITEM_ERROR],
-    [UPLOADER_EVENTS.REQUEST_PRE_SEND],
+The Uploader will trigger for batch and batch-item lifecycle events.
 
+Registering to handle events can be done using the uploader's _on()_ and _once()_ methods.
+Unregistering can be done using _off()_ or by the return value of both on and once.
+
+```javascript
+const batchAddHandler = (batch) => {};
+
+const unregister = uploader.on(UPLOADER_EVENTS.BATCH_ADD, batchAddHandler);
+
+unregister(); //is equivalent to the line below
+uploader.off(UPLOADER_EVENTS.BATCH_ADD, batchAddHandler);
+```
+
+### UPLOADER_EVENTS.BATCH_ADD
+
+Triggered when a new batch is added.
+
+- Parameters: _(batch, uploadOptions)_ 
+
+> This event is _[cancellable](#cancellable-events)_
+
+### UPLOADER_EVENTS.BATCH_START
+
+Triggered when batch items start uploading
+
+- Parameters: _(batch)_
+
+> This event is _[cancellable](#cancellable-events)_
+
+### UPLOADER_EVENTS.BATCH_PROGRESS
+
+Triggered every time progress data is received from the upload request(s)
+
+- Parameters: _(batch)_
+
+### UPLOADER_EVENTS.BATCH_FINISH
+
+Triggered when batch items finished uploading
+
+- Parameters: _(batch)_
+ 
+### UPLOADER_EVENTS.BATCH_CANCEL
+
+Triggered in case batch was cancelled from BATCH_START event handler
+
+- Parameters: _(batch)_
+
+### UPLOADER_EVENTS.BATCH_ABORT
+
+Triggered in case the batch was [aborted](#abortBatch)
+
+- Parameters: _(batch)_
+
+### UPLOADER_EVENTS.ITEM_START
+
+Triggered when item starts uploading (just before)
+
+- Parameters: _(item)_
+
+### UPLOADER_EVENTS.ITEM_FINISH
+
+Triggered when item finished uploading
+
+- Parameters: _(item)_
+
+> The server response can be accessed through the item's uploadResponse property.
+
+### UPLOADER_EVENTS.ITEM_PROGRESS
+
+Triggered every time progress data is received for this file upload
+
+- Parameters: _(item)_
+
+> progress info is accessed through the item's "completed" (percentage) and "loaded" (bytes) properties.
+
+### UPLOADER_EVENTS.ITEM_CANCEL
+
+Triggered in case item was cancelled from [ITEM_START](#UPLOADER_EVENTS.ITEM_START) event handler
+
+- Parameters: _(item)_
+
+### UPLOADER_EVENTS.ITEM_ERROR
+
+Triggered in case item upload failed
+
+- Parameters: _(item)_
+
+> The server response can be accessed through the item's uploadResponse property.
+
+### UPLOADER_EVENTS.ITEM_ABORT
+    
+Triggered in case [abort](#abort) was called
+
+- Parameters: _(item)_
+
+### UPLOADER_EVENTS.REQUEST_PRE_SEND
+
+Triggered before a group of items is going to be uploaded
+Group will contain a single item unless "grouped" option is set to true.
+
+Handler receives the item(s) in the group and the upload options that were used.
+The handler can change data inside the items and in the options by returning different data than received.
+See this [guide](../../guides/DynamicParameters.md) for more details.
+
+- Parameters: _(items, options)_
+
 ## Cancellable Events
+
+These are events that allow the client to cancel their respective upload object (batch or batch item)
+To cancel the upload, the handler can return false.
+
+```javascript
+uploader.on(UPLOADER_EVENTS.ITEM_START, (item) => {
+    let result;
+    
+    if (item.file.name.endsWith(".xml")) {
+        result = false; //only false will cause a cancel.
+    }
+
+    return result;
+});
+```

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Major refactor

Supply chain risk

Package has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

1026048

increased by326.37%

Dependency count

3

decreased by-25%

Number of package files

56

increased by3.7%

Lines of code

9519

increased by556.03%

Number of lines in readme file

272

increased by368.97%

Worsened metrics

Dev dependency count

2

increased by100%

Number of medium supply chain risk alerts

1

increased byInfinity%

Dependency changes

• - Removedimmer@^6.0.3

• - Removedimmer@6.0.9(transitive)