对接 KODO 新上传 API (#448)

* 对接 new api

* 更新文档 & 修改说明

* 更新文档说明

* 更新文档说明

* 修复 uploadId 导致的上传出错 & 调整部分文档及代码

* fix review

* fix review part-2

* fix review part-3

* review end

Author: winddies

.babelrc

@@ -6,7 +6,8 @@
         "useBuiltIns": "usage", // 在文件需要的位置单独按需引入 polyfill
         "targets": {
           "browsers": ["last 2 versions", "ie >= 8"]
-        }
+        },
+        "modules": "commonjs"
       }
     ]
   ],
@@ -18,5 +19,6 @@
       }
     ],
     "@babel/proposal-object-rest-spread"
-  ]
+  ],
+  "ignore": ["**/*.d.ts", "**/*.js.map"]
 }

.gitignore

@@ -8,3 +8,4 @@ dist
 test/config.json
 coverage
 lib
+esm

README.md

@@ -2,7 +2,7 @@
 
 基于七牛 API 开发的前端 JavaScript SDK
 
-## 当前版本为 2.x，查看 1.x 的文档请点击[这里](https://github.com/qiniu/js-sdk/tree/1.x)
+## 当前版本为 3.x，旧版本文档：[2.x](https://github.com/qiniu/js-sdk/tree/2.x)，[1.x](https://github.com/qiniu/js-sdk/tree/1.x)
 
 ## 快速导航
 
@@ -133,7 +133,7 @@ qiniu.compressImage(file, options).then(data => {
 ```
 ## API Reference Interface
 
-### qiniu.upload(file: File, key: string, token: string, putExtra: object, config: object): observable
+### qiniu.upload(file: File, key: string, token: string, putExtra?: object, config?: object): observable
 
   * **observable**: 为一个带有 subscribe 方法的类实例
 
@@ -154,10 +154,14 @@ qiniu.compressImage(file, options).then(data => {
           }
         }
         ```
-        * next: 接收上传进度信息，res是一个带有 `total` 字段的 `object`，包含`loaded`、`total`、`percent`三个属性，提供上传进度信息。
-          * total.loaded: `number`，已上传大小，单位为字节。
-          * total.total: `number`，本次上传的总量控制信息，单位为字节，注意这里的 total 跟文件大小并不一致。
-          * total.percent: `number`，当前上传进度，范围：0～100。
+        * next: 接收上传进度信息的回调函数，回调函数参数值为 `object`，包含字段信息如下：
+          * uploadInfo: `object`，只有分片上传时才返回该字段
+            * uploadInfo.id: 上传任务的唯一标识。
+            * uploadInfo.url: 上传地址。
+          * total: 包含`loaded`、`total`、`percent`三个属性:
+            * total.loaded: `number`，已上传大小，单位为字节。
+            * total.total: `number`，本次上传的总量控制信息，单位为字节，注意这里的 total 跟文件大小并不一致。
+            * total.percent: `number`，当前上传进度，范围：0～100。
 
         * error: 上传错误后触发；自动重试本身并不会触发该错误，而当重试次数到达上限后则可以触发。当不是 xhr 请求错误时，会把当前错误产生原因直接抛出，诸如 JSON 解析异常等；当产生 xhr 请求错误时，参数 err 为一个包含 `code`、`message`、`isRequestError` 三个属性的 `object`：
           * err.isRequestError: 用于区分是否 xhr 请求错误；当 xhr 请求出现错误并且后端通过 HTTP 状态码返回了错误信息时，该参数为 `true`；否则为 `undefined` 。
@@ -169,10 +173,11 @@ qiniu.compressImage(file, options).then(data => {
 
       * subscription: 为一个带有 `unsubscribe` 方法的类实例，通过调用 `subscription.unsubscribe()` 停止当前文件上传。
 
+  * **bucket**: 上传的目标空间
   * **file**: `File` 对象，上传的文件
   * **key**: 文件资源名
   * **token**: 上传验证信息，前端通过接口请求后端获得
-  * **config**: `object`
+  * **config**: `object`，其中的每一项都为可选
 
     ```JavaScript
     const config = {
@@ -189,39 +194,24 @@ qiniu.compressImage(file, options).then(data => {
     * config.concurrentRequestLimit: 分片上传的并发请求量，`number`，默认为3；因为浏览器本身也会限制最大并发量，所以最大并发量与浏览器有关。
     * config.checkByMD5: 是否开启 MD5 校验，为布尔值；在断点续传时，开启 MD5 校验会将已上传的分片与当前分片进行 MD5 值比对，若不一致，则重传该分片，避免使用错误的分片。读取分片内容并计算 MD5 需要花费一定的时间，因此会稍微增加断点续传时的耗时，默认为 false，不开启。
     * config.forceDirect: 是否上传全部采用直传方式，为布尔值；为 `true` 时则上传方式全部为直传 form 方式，禁用断点续传，默认 `false`。
+    * config.chunkSize: `number`，分片上传时每片的大小，必须为正整数，单位为 `MB`，且最大不能超过 1024，默认值 4。因为 chunk 数最大 10000，所以如果文件以你所设的 `chunkSize` 进行分片并且 chunk 数超过 10000，我们会把你所设的 `chunkSize` 扩大二倍，如果仍不符合则继续扩大，直到符合条件。
 
-  * **putExtra**:
+  * **putExtra**: `object`，其中的每一项都为可选
 
     ```JavaScript
     const putExtra = {
-      fname: "",
-      params: {},
-      mimeType: [] || null
+      fname: "qiniu.txt",
+      mimeType: "text/plain",
+      customVars: { 'x:test': 'qiniu', ... },
+      metadata: { 'x-qn-meta': 'qiniu', ... },
     };
     ```
 
-    * fname: `string`，文件原文件名
-    * params: `object`，用来放置自定义变量，变量名必须以 `x:` 开始，自定义变量格式及说明请参考[文档](https://developer.qiniu.com/kodo/manual/1235/vars)
-    * mimeType: `null || array`，用来限制上传文件类型，为 `null` 时表示不对文件类型限制；限制类型放到数组里：
-    `["image/png", "image/jpeg", "image/gif"]`
-
-### qiniu.createMkFileUrl(url: string, file: File, key: string, putExtra: object): string
-
-  返回创建文件的 url；当分片上传时，我们需要把分片返回的 ctx 信息拼接后通过该 url 上传给七牛以创建文件。
-
-  * **url**: 上传域名，可以通过qiniu.getUploadUrl()获得
-  * **file**: 文件对象
-  * **key**: 文件资源名
-  * **putExtra**: 同上
-
-  ```JavaScript
-  const requestUrl = qiniu.createMkFileUrl(
-    uploadUrl,
-    file,
-    key,
-    putExtra
-  );
-  ```
+    * fname: `string`，文件原始文件名，若未指定，则魔法变量中无法使用 fname、ext、suffix
+    * customVars: `object`，用来放置自定义变量，变量名必须以 `x:` 开始，自定义变量格式及说明请参考[文档](https://developer.qiniu.com/kodo/manual/1235/vars)
+    * metadata: `object`，用来防止自定义 meta，变量名必须以 `x-qn-meta-`开始，自定义资源信息格式及说明请参考
+    [文档](https://developer.qiniu.com/kodo/api/1252/chgm)
+    * mimeType: `string`，指定所传的文件类型
 
 ### qiniu.region: object
 
@@ -248,31 +238,10 @@ qiniu.compressImage(file, options).then(data => {
   const headers = qiniu.getHeadersForChunkUpload(token)
   ```
 
-### qiniu.getHeadersForMkFile(token: string): object
+### qiniu.deleteUploadedChunks(token: string, key: stting, uploadInfo: object): Promise<void>
+  删除指定上传任务中已上传完成的片，`key` 为目标文件名，`uploadInfo` 可通过 `next` 的返回获取，`token` 由服务端生成
 
-  返回 `object`，包含用来获得文件创建的头信息，参数为 `token` 字符串；当分片上传完需要把 ctx 信息传给七牛用来创建文件时，请求需要带该函数返回的头信息
-
-  ```JavaScript
-  const headers = qiniu.getHeadersForMkFile(token)
-  ```
-
-### qiniu.getResumeUploadedSize(file: File): number
-  断点续传时返回文件之前已上传的字节数，为 0 代表当前并无该文件的断点信息
-
-### qiniu.filterParams(params: object): array
-
-  返回[[k, v],...]格式的数组，k 为自定义变量 `key` 名，v 为自定义变量值，用来提取 `putExtra.params` 包含的自定义变量
-
-  ```JavaScript
-  const customVarList = qiniu.filterParams(putExtra.params)
-
-  for (let i = 0; i < customVarList.length; i++) {
-    const k = customVarList[i]
-    multipart_params_obj[k[0]] = k[1]
-  }
-  ```
-###
-### qiniu.compressImage(file: File, options: object) : Promise (上传前图片压缩)
+### qiniu.compressImage(file: File, options: object): Promise<CompressResult> (上传前图片压缩)
 
   ```JavaScript
   const imgLink = qiniu.compressImage(file, options).then(res => {
@@ -291,6 +260,10 @@ qiniu.compressImage(file, options).then(data => {
     * options.maxHeight: `number`，压缩图片的最大高度值
     （注意：当 `maxWidth` 和 `maxHeight` 都不设置时，则采用原图尺寸大小）
     * options.noCompressIfLarger: `boolean`，为 `true` 时如果发现压缩后图片大小比原来还大，则返回源图片（即输出的 dist 直接返回了输入的 file）；默认 `false`，即保证图片尺寸符合要求，但不保证压缩后的图片体积一定变小
+  * CompressResult: `object`，包含如下字段：
+    * dist: 压缩后输出的 File 对象，或原始的 file，具体看下面的 options 配置
+    * width: 压缩后的图片宽度
+    * height: 压缩后的图片高度
 
 ### qiniu.watermark(options: object, key?: string, domain?: string): string（水印）