npm package: @nsrd/file-storage-sdk
Description: an encapsulation of a file store.
Author: baiyx@neuqsoft
Latest version: 1.1.0-alpha.7

# 文件存储file-storage-sdk
- vite 打包

- typescript 语法

- 支持多入口打包 详见 `vite.build.mjs` - `entryList`

- 对接文件存储服务

## 使用

### 说明

该组件库依赖于 `axios` `spark-md5`, 安装依赖时会自动安装，异常情况请确认依赖已安装

### 安装

npm `npm install @nsrd/file-storage-sdk -S`

yarn `yarn add @nsrd/file-storage-sdk`

pnpm `pnpm install @nsrd/file-storage-sdk -S`

### 引入

- 第一种`import FileStorage from "@nsrd/file-storage-sdk"` 【推荐】

- 第二种 `const FileStorage = require("@nsrd/file-storage-sdk")`

### 使用示例

```javascript
import FileStorage from "@nsrd/file-storage-sdk";

const FS = new FileStorage({
  base: 'http://172.30.3.152/file-storage/rest/v2'
})

const voucherId = "asdad213qdwasd123" // 业务系统提供的操作凭证

FS.upload({
    chunk: true,
    voucherId: voucherId,
    file: file.value,
    onProgress: (res) => {
        console.log(res);
    }
}).then(res => {
    console.log('upload result', res);
})
```

### API

#### 构造函数

```javascript
const FS = new FileStorage(options)
```

- **`options(constructor)`**:  `object`构造函数参数

| 属性名        | 类型   | 是否必填 | 默认值  | 说明                                                         |
| ------------- | ------ | -------- | ------- | ------------------------------------------------------------ |
| base          | string | 否       | `./`    | 文件存储地址服务地址，支持相对地址、绝对地址、完整地址。<br />例如 `http://172.30.3.152/file-storage/rest/v2`。 |
| chunkSize     | number | 否       | 5242880 | 分片上传时分片大小默认5MB，请输入大于5MB的字节数             |
| errorNum      | number | 否       | 20      | 允许的上传出现错误总数 默认 20                               |
| chunkErrorNum | number | 否       | 5       | 同一分片上传错误次数 默认 5                                  |
| timeout       | number | 否       | 60000   | 单个接口超时时间 默认60s                                     |

#### 方法

##### 1.`upload` 上传

```javascript
FS.upload(options)
```

- **`options`**:  `object`上传函数参数

| 属性名        | 类型     | 是否必填 | 默认值 | 说明                                                    |
| ------------- | -------- | -------- | ------ | ------------------------------------------------------- |
| voucherId     | string   | 是       | -      | 业务系统获取的操作凭证                                  |
| file          | File     | 是       | -      | 要上传的文件                                            |
| errorNum      | number   | 否       | -      | 允许上传出现错误总数,默认为 `options.errorNum`          |
| chunkErrorNum | number   | 否       | -      | 允许同一分片上传错误次数,默认为 `options.chunkErrorNum` |
| onProgress    | Function | 否       | -      | 上传进度回调返回值详见下文`onProgress`                  |
- **options.onProgress#返回值** : `object`

| 属性名  | 类型                                      | 是否必填 | 默认值 | 说明                                                    |
| ------- | ----------------------------------------- | -------- | ------ | ------------------------------------------------------- |
| status  | 'preloading' \| 'uploading' \| 'complete' | 是       | -      | preloading: 前置处理中 uploading: 上传中 complete: 完成 |
| current | number                                    | 否       | -      | 当前已完成分片数                                        |
| total   | number                                    | 否       | -      | 总分片数                                                |

- **返回值** **`FS.upload`** : `Promise<object>` 

  - `fulfilled`
  
  | 属性名           | 类型   | 是否必填 | 默认值 | 说明                              |
  | ---------------- | ------ | -------- | ------ | --------------------------------- |
  | code             | string | 是       | -      | 状态码：'00000'：正常；其他异常   |
  | message          | string | 是       | -      | 接口说明                          |
  | uniqueId         | string | 是       | -      | 文件标识                          |
  | publicUniqueName | string | 否       | -      | 文件公开访问标识用于文件`url`访问 |
  
  - `rejected`
  
  | 属性名  | 类型   | 是否必填 | 默认值 | 说明               |
  | ------- | ------ | -------- | ------ | ------------------ |
  | code    | string | 是       | -      | 状态码：非 "00000" |
  | message | string | 是       | -      | 接口说明           |

##### 2.`download`  下载

```javascript
FS.download(options)
```

- **`options`**:  `object`下载函数参数

| 属性名           | 类型    | 是否必填                            | 默认值 | 说明                                        |
| ---------------- | ------- | ----------------------------------- | ------ | ------------------------------------------- |
| stream           | boolean | 否                                  | false  | `true`:获取文件`File`；`false`:直接下载文件 |
| voucherId        | string  | voucherId/publicUniqueName 存在一个 | -      | 下载操作凭证                                |
| publicUniqueName | string  | voucherId/publicUniqueName 存在一个 | -      | 公开访问标识                                |

- **返回值** **`FS.download`**:  `Promise<object>`
  - `fulfilled`
  
    | 属性名  | 类型   | 是否必填 | 默认值 | 说明                            |
    | ------- | ------ | -------- | ------ | ------------------------------- |
    | code    | string | 是       | -      | 状态码：'00000'：正常；其他异常 |
    | message | string | 是       | -      | 接口说明                        |
    | url     | string | 否       | -      | 下载地址                        |
    | file    | File   | 否       | -      | 下载的文件                      |

  - `rejected`
  
    | 属性名  | 类型   | 是否必填 | 默认值 | 说明               |
    | ------- | ------ | -------- | ------ | ------------------ |
    | code    | string | 是       | -      | 状态码：非 '00000' |
    | message | string | 是       | -      | 接口说明           |

##### 3.`getDownloadUri` 获取下载地址

```javascript
FS.getDownloadUri(options)
```

- **`options`**:  `object`获取下载地址函数参数

| 属性名           | 类型   | 是否必填                           | 默认值 | 说明         |
| ---------------- | ------ | ---------------------------------- | ------ | ------------ |
| voucherId | string | voucherId/publicUniqueName 存在一个 | -      | 下载操作凭证 |
| publicUniqueName | string   | voucherId/publicUniqueName 存在一个 | -      | 公开访问标识 |

- **返回值** **`FS.getDownloadUri`**: `Promise<object>`
  
  - `fulfilled`
  
    | 属性名  | 类型   | 是否必填 | 默认值 | 说明                            |
    | ------- | ------ | -------- | ------ | ------------------------------- |
    | code    | string | 是       | -      | 状态码：'00000'：正常；其他异常 |
    | message | string | 是       | -      | 接口说明                        |
    | url     | string | 是       | -      | 下载地址                        |
  - `rejected`
  
    | 属性名  | 类型   | 是否必填 | 默认值 | 说明               |
    | ------- | ------ | -------- | ------ | ------------------ |
    | code    | string | 是       | -      | 状态码：非 '00000' |
    | message | string | 是       | -      | 接口说明           |
  

## develop

1. scripts命令

   ```json
   {
       "alpha": "打签：alpha 版本",
       "build": "仓库打包",
       "commit": "提交代码",
       "dev": "启动项目",
       "eslint": "eslint格式化代码",
       "postinstallmac": "苹果环境配置",
       "pre-commit": "预提交",
       "prepare": "环境配置",
       "release": "打签：release 版本",
       "sort": "package.json排序"
   }
   ```

2. 安装依赖

   ```shell
   yarn install
   # npm install
   # pnpm install
   ```

3. 本地启动

   ```shell
   npm run dev
   ```

4. 代码提交

   预提交检查代码

   ```shell
   npm run pre-commit
   ```
   提交代码

   ```shell
   npm run commit
   ```

5. 发布

- tag 

  `alpha`版本

  ```shell
  npm run alpha
  ```

  `release`版本

  ```shell
  npm run release
  ```

  

- publish

  ```shell
  npm publish
  ```