@gentleduck/upload

中文文档
0.3.0发布于 2026/10/29TypeScriptES Module零依赖近 30 天下载 3082

@gentleduck/upload

中文使用文档
文档目录13 节
  1. 安装
  2. 快速启动
  3. 战略
  4. 反应
  5. 子路径导出
  6. 特征
  7. 持久性
  8. 写入自定义策略
  9. 图标
  10. 活动
  11. Bundler 要求
  12. 测试
  13. 许可证

@gentleduck/upload

@ gentleduck/ 上载

无头型,框架-不可知文件上载引擎,并配有打入的状态机,可插接策略和回放装订.

麻省理工学院 - 说吧 更改日志 - 说吧 捐款 - 说吧 文档

npm downloads MIT


纯减量核心, 持久性意识和再现, 有限制上传 与特定的后端或 UI 库相通和零相接. 发动机留下 协议不可知: 您的后端返回一个意图, 其上的引擎调度 strategy 字段 到移动字节的已注册策略.

安装

bun add @gentleduck/upload
# peer deps for the React bindings
bun add react react-dom

快速启动

import { createUploadStore } from '@gentleduck/upload/core'
import { PutStrategy, createStrategyRegistry } from '@gentleduck/upload/strategies'

type Intents = { put: PutStrategy.Intent }
type Cursors = { put?: PutStrategy.Cursor }
type Purpose = 'attachment'
type Result = { fileId: string; key: string }

const strategies = createStrategyRegistry<Intents, Cursors, Purpose, Result>()
strategies.set(PutStrategy({ allowedHosts: ['uploads.example.com'] }))

const store = createUploadStore<Intents, Cursors, Purpose, Result>({
  strategies,
  api: {
    // Ask your backend to presign the upload.
    async createIntent({ filename, contentType, size }) {
      const res = await fetch('/api/sign', {
        method: 'POST',
        body: JSON.stringify({ filename, contentType, size }),
      })
      return res.json() // -> { strategy: 'put', fileId, url, headers? }
    },
    // Finalize once the bytes are transferred.
    async complete({ fileId }) {
      return { fileId, key: `attachments/${fileId}` }
    },
  },
  config: { maxConcurrentUploads: 3, autoStart: ['attachment'] },
})

store.dispatch({ type: 'addFiles', files, purpose: 'attachment' })

这个 createXHRTransport() 浏览器传输自动安装 。 过 transport: createFetchTransport() 用于在节点/SSR/边缘/工人中运行.

战略

策略是将意图转化为网络呼叫的薄层. 建造了四艘船; 登记您需要的,并让 createIntent 选择每个文件.

战略工厂使用大小写可偿还
点PutStrategy(opts?)单个预签 PUT( S3) putObject,签名 PUT)没有
邮政PostStrategy(opts?)签名 multipart/form-data (S3 POST 政策)没有
多块multipartStrategy(opts?)大型文件,并行部分,每部分恢复对
sTusStrategy(opts?)可恢复上传到 Tus 协议对
import {
  PutStrategy,
  PostStrategy,
  multipartStrategy,
  TusStrategy,
  createStrategyRegistry,
} from '@gentleduck/upload/strategies'

const strategies = createStrategyRegistry<Intents, Cursors, Purpose, Result>()
strategies.set(PutStrategy({ allowedHosts: ['uploads.example.com'] }))
strategies.set(PostStrategy())
strategies.set(multipartStrategy({ maxPartConcurrency: 4 }))
strategies.set(TusStrategy({ allowedHosts: ['tus.example.com'] }))

每个后端提供的 URL (PUT / POST /多部分 / tus) 运行于 validateUploadUrl SSRF在任何字节离开客户端前进行守卫. 设定 allowedHosts 锁定主机; 保留 allowPrivateHosts 默认时 false 以阻断回转 / RFC1918 / 云-元数据目标. PutStrategy, (中文(简体) ), PostStrategy,以及 TusStrategy 重试瞬态网络失败 (超时 / 5xx / ECONNRESET与指数后退.

反应

import {
  UploadProvider,
  useUploader,
  useDropzone,
} from '@gentleduck/upload/react'

function Uploader() {
  const { getRootProps, getInputProps, isDragging } = useDropzone({
    purpose: 'attachment',
    accept: 'image/*,.pdf',
  })
  const { items, dispatch } = useUploader<Intents, Cursors, Purpose, Result>()

  return (
    <div {...getRootProps()} data-active={isDragging}>
      <input {...getInputProps()} />
      {items.map((item) => (
        <Row
          key={item.localId}
          item={item}
          onCancel={() => dispatch({ type: 'cancel', localId: item.localId })}
        />
      ))}
    </div>
  )
}

// Wrap once so descendants can reach the store.
<UploadProvider store={store}>
  <Uploader />
</UploadProvider>

反应导出 : UploadProvider, (中文(简体) ), useUploader, (中文(简体) ), useUploaderActions, (中文(简体) ), useDropzone, (中文(简体) ), createUploadFactory, (中文(简体) ), useUploadStore, (中文(简体) ), isUploadStore (加上纯洁的助手) fileMatchesAccept, (中文(简体) ), matchesAcceptToken, (中文(简体) ), selectFiles) (中文(简体) ).

子路径导出

import { createUploadStore, createFetchTransport } from '@gentleduck/upload/core'
import { UploadProvider, useUploader, useDropzone } from '@gentleduck/upload/react'
import { PutStrategy, TusStrategy, createStrategyRegistry } from '@gentleduck/upload/strategies'

特征

  • 纯减排器 ——指挥/活动驱动的状态机器;效果被隔离.
  • 输入端到端 - 意图、光标、目的和结果为四相线程 通过发动机(M, (中文(简体) ), C, (中文(简体) ), P, (中文(简体) ), R) (中文(简体) ).
  • 四项内在战略 ——PUT,POST,多部分,tus——加上自己的注册.
  • 两次运输 —— 说 createXHRTransport() (浏览器,真正的上传进度)和 createFetchTransport() (节点/标准标准/边缘/工人),可选 get() 流线 下载和 head()。 。 。 .
  • 刷新后继续 – 内存 / localStorage / 索引 DB 持久性适配器;光标意识 通过 rebind 命令.
  • 重试策略 ——每相位尝试升级的指数回放(意图/上传/ 完成),通过 config.retryPolicy。 。 。 .
  • 受约束货币 —— 说 config.maxConcurrentUploads 封顶平行上传;已队列的项目 等待一个空位.
  • 内容去除线程 - SHA-256小文件的散列检查和 在大型的网络工人中 checksumMaxSize 是边界,不是跳过.. 大文件在不冻结UI的情况下会被复制.
  • 无头反应 —— 说 useDropzone 给拖放 + 文件拾取器 道具获取器为零 标记或造型.
  • SSRF 警卫队 ——许可列表+协议+IPv4/IPv6私人+云-元数据+NAT64+ 6to4 + IPv4 上传的每个 URL 上的检查 .
  • 文件名 + MIME 硬化 ——NFKC常态化,控制带,Windows保留名称+ 255-char + 路径- sep 拒绝; 魔法字节嗅取 交叉检查所声称的 file.type。 。 。 .
  • 纳恩安全配置 - 每个数字选项夹 NaN 编号 : Infinity 负于其 默认; 拒绝持续快照 NaN 字段.
  • 没有 DOM 组合 ——运行于Workers,Node 22+,或浏览器.
  • 威胁模式+审计 - 坚固的 THREAT-MODEL.md 可重运行 AUDIT-RESULTS.md 检查了包裹.

持久性

恒定让一个被暂停或飞行中的上传幸存的新鲜:快照是存储的,a rebind 重新装入新鲜的 File (通过指纹验证) 所以一个可恢复的策略继续 从光标中.

import { createUploadStore, IndexedDBAdapter } from '@gentleduck/upload/core'

createUploadStore({
  strategies,
  api,
  persistence: {
    key: 'app:uploads',
    version: 1,
    adapter: IndexedDBAdapter, // or LocalStorageAdapter / createMemoryAdapter()
    isPurpose,
    isIntent,
  },
})

适配器 : IndexedDBAdapter 财务报告和审定财务报表 LocalStorageAdapter (共享单吨), MemoryAdapter (分摊)或 createMemoryAdapter() (每个店都隔离). 弹出 persistence.version 锁定 横跨标签/部署; 不同版本的快照被拒绝 deserializeSnapshot是因为 版本栅栏而不是加载.

写入自定义策略

战略实施 start() 反对: Contracts.Strategy.Me 合同. id 必须是平等的 意图 strategy 字段; resumable 是您 UI 的元数据。 荣誉 signal电话 reportProgress,并且——如果可以恢复的话—— persistCursor 在每一个安全边界.

import type { Contracts } from '@gentleduck/upload/core'

type Intents = { myput: { strategy: 'myput'; fileId: string; url: string } }
type Cursors = { myput?: Record<string, never> }
type Purpose = 'attachment'
type Result = { fileId: string; key: string }

const myPut: Contracts.Strategy.Me<Intents, Cursors, Purpose, Result, 'myput'> = {
  id: 'myput',
  resumable: false,
  async start(ctx) {
    await ctx.transport.put({
      url: ctx.intent.url,
      body: ctx.file,
      signal: ctx.signal,
      onProgress: (uploadedBytes, totalBytes) => ctx.reportProgress({ uploadedBytes, totalBytes }),
    })
  },
}

strategies.set(myPut)

start() 正在等待: 解决 ~ 引擎向 completing; 抛出 ~ 错误路径 结束 errorNormalizer + 键 retryPolicy编辑 ctx 还携带 intent, (中文(简体) ), api, (中文(简体) ), readCursor, (中文(简体) ), persistCursor, (中文(简体) ), attempt,并注入 transport (单位:千美元)put 编号 : postForm 编号 : patch 编辑 选项 get 编号 : head) (中文(简体) ). 使用 api.multipart.signPart 编号 : completeMultipart 用于后端 绕道飞行需要中途飞行.

图标

通过 store.dispatch(cmd)。 。 。 .

命令目的
addFiles验证 + 插入; 调度校验和 + 意图
start 编号 : startAll移动已准备好的项目到队列( 已选中)
pause 编号 : pauseAll停止飞行, 持续光标( 有争议)
resume重排已暂停的项目
cancel 编号 : cancelAll中止并标记已取消( 已辩论)
retry重新尝试失败的阶段, 撞倒尝试计数器
rebind重新添加一个新鲜的 File 刷新后( 指纹验证)
remove从状态丢弃项目

活动

通过 store.on(type, cb);有效载荷从发动机的事件地图上打出.

  • file.added, (中文(简体) ), file.rejected
  • validation.ok, (中文(简体) ), validation.failed
  • intent.creating, (中文(简体) ), intent.created, (中文(简体) ), intent.failed
  • upload.queued, (中文(简体) ), upload.started, (中文(简体) ), upload.progress, (中文(简体) ), upload.cursor
  • upload.paused, (中文(简体) ), upload.resumed, (中文(简体) ), upload.canceled
  • upload.completing, (中文(简体) ), upload.completed, (中文(简体) ), upload.error

Bundler 要求

引擎参考文献 process.env.NODE_ENV 以示警告。 虚拟/网络包装 Rspack / esbuild / rollup在建设时替换这个,并将一个分公司运到生产. 纯ESM 消费者必须在没有捆绑器的情况下装入源头 globalThis.process = { env: { NODE_ENV: 'production' } } 在导入软件包之前.

测试

bun run test

Vitest套房包括减速器状态机器、持久性、每个策略和运输、 递增的散列器,SSF/filename/MIME守护器,以及反应辅助器.

许可证

麻省理工学院

版本与发布记录

@gentleduck/upload 共发布 6 个版本,首次发布于 2026/03/12;过去 12 个月发布了 6 个版本。

版本发布日期距今
0.3.0latest2026/10/2917 天前
0.2.62026/05/205 个月前
0.2.52026/05/066 个月前
0.2.42026/05/066 个月前
0.2.22026/03/128 个月前
0.2.12026/03/128 个月前

关于 @gentleduck/upload 的常见问题

如何安装 @gentleduck/upload?

在项目目录运行 npm install @gentleduck/upload,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:react(^19.2.3)、react-dom(^19.2.3)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。

@gentleduck/upload 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@gentleduck/upload 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@gentleduck/upload 需要什么版本的 Node.js?

package.json 的 engines 字段要求 Node.js >=22.0.0。版本不符时 npm 默认只给出警告,开启 engine-strict 后会拒绝安装。

@gentleduck/upload 可以商用吗?

@gentleduck/upload 使用 未声明 许可。package.json 没有声明许可证。没有许可证的代码默认保留全部权利,商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括,不构成法律意见,请以许可原文为准。

@gentleduck/upload 的下载量有多少?

根据 npm 官方下载统计,@gentleduck/upload 在 2026/10/16 – 2026/11/14 这 30 天内被下载 3,082 次,日均约 103 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@gentleduck/upload 还在维护吗?

最新版本 0.3.0 发布于 2026/10/29(17 天前);至今共发布 6 个版本,其中过去 12 个月发布了 6 个;首次发布于 2026/03/12。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。