@admni/file-uploader

浏览器端文件上传 SDK（TypeScript），按 v1.0.md 设计基线实现，支持：

• 上传队列与并发调度（UploadQueue）
• 单文件完整生命周期（FileUploader）
• 直传 / 分片上传（滑动窗口并发）
• 暂停 / 继续 / 取消（含网络自动暂停恢复）
• 秒传（identical_storage）与同 hash 去重
• 业务 code 拦截（onConfigResponse）与 bizCode 透传
• Worker hash 并行计算（hashConcurrency）

内部维护文档见 INTERNAL.md；完整规范源见 ../file-upload/v1.0.md。

安装

npm i @admni/file-uploader

快速开始

import { UploadQueue, UploadBizError } from "@admni/file-uploader"

const queue = new UploadQueue({
  concurrency: 3,
  hashConcurrency: 2,
  onTaskChange(task) {
    console.log(task.taskId, task.fileName, task.state, task.progress)
  },
  // 可选：统一处理服务端 code
  onConfigResponse: async (response, retry, ctx) => {
    if (response.code === 0 && response.data) return response.data
    if (response.code === 1012) return retry() // 例如 token 刷新后重试
    throw new UploadBizError(
      "CONFIG_FAILED",
      response.message || `config failed: ${response.code}`,
      response.code,
      { ctx, response },
    )
  },
})

const taskId = queue.add(file, {
  async getUploadConfig({ fileHash, fileName, fileSize, fileType }) {
    const res = await fetch("/api/upload/config", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ fileHash, fileName, fileSize, fileType }),
    })
    return await res.json()
  },
  async notifyComplete(params) {
    await fetch("/api/upload/complete", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify(params),
    })
  },
})

// 控制任务
queue.pause(taskId)
queue.resume(taskId)
queue.cancel(taskId)

核心能力

• 状态机：pending -> hashing -> configuring -> uploading -> (merging) -> notifying -> success
• 秒传：identical_storage=true 时跳过 uploading/merging
• 可插拔策略：onConfigResponse 可处理业务码、重试、终止
• 存储适配：内置 OBS / S3 / Custom（fetch PUT）
• 可观测性：插件钩子（step start/end/error, network change）

API 速览

• new UploadQueue(options)
• queue.add(file, options)
• queue.pause(taskId) / queue.resume(taskId) / queue.cancel(taskId)
• queue.pauseAll() / queue.resumeAll() / queue.getTasks() / queue.destroy()

发布到 npm（维护者）

npm login
npm run typecheck
npm run build
npm run pack:check
npm publish --access public