gentleeduck/duck-ui / skills/duck-upload
duck-upload
VerifiedActivate when the user is working with @gentleduck/upload — the file upload engine for React. Covers creating upload clients, configuring strategies (multipart, POST), implementing the UploadApi backend contract, wiring React hooks (useUploader, UploadProvider), progress tracking, persistence, and the upload state machine phases.
@gentleduck/upload
A type-safe, strategy-based file upload engine for React with resumable uploads, progress tracking, persistence, and a pluggable backend contract.
Package exports
import { ... } from '@gentleduck/upload' // everything
import { ... } from '@gentleduck/upload/core' // engine, store, contracts, persistence, utils
import { ... } from '@gentleduck/upload/react' // UploadProvider, useUploader, useUploaderActions, createUploadFactory
import { ... } from '@gentleduck/upload/strategies' // multipartStrategy, PostStrategy, createStrategyRegistry
Architecture overview
createUploadClient(opts)
-> createUploadStore(opts)
-> StoreRuntime { state, reducer, emitter, scheduler, effect queue }
-> dispatch(cmd: UploadCommand) -> reducer -> effects -> notify listeners
Core concepts
| Concept | Description |
|---|---|
| UploadClient | Alias for UploadStore. Created via createUploadClient(opts). |
| UploadStore | Minimal surface: getSnapshot(), subscribe(), dispatch(), on(), off(), waitFor(). |
| UploadCommand | User intent dispatched to the store (discriminated union on type). |
| UploadItem | Discriminated union on phase — the state of a single upload. |
| UploadPhase | validating -> creating_intent -> ready -> queued -> uploading -> completing -> completed. Also: paused, error, canceled. |
| IntentMap | Maps strategy keys to intent types (backend-provided upload instructions). |
| CursorMap | Maps strategy keys to cursor types (resume state, e.g. completed parts). |
| UploadStrategy | { id, resumable, start(ctx) } — executes the actual file transfer. |
| StrategyRegistry | get(id), has(id), set(strategy) — holds registered strategies. |
| UploadApi | Backend contract: createIntent(), complete(), optional multipart.*, tus.*. |
| UploadTransport | Network layer: put(), postForm(), patch(). Default: XHR-based (createXHRTransport()). |
| Persistence | Optional adapter (localStorage, IndexedDB, memory) for surviving page reloads. |
Upload commands
type UploadCommand<P extends string> =
| { type: 'addFiles'; files: File[]; purpose: P }
| { type: 'start'; localId: string }
| { type: 'startAll'; purpose?: P }
| { type: 'pause'; localId: string }
| { type: 'pauseAll'; purpose?: P }
| { type: 'resume'; localId: string }
| { type: 'cancel'; localId: string }
| { type: 'cancelAll'; purpose?: P }
| { type: 'retry'; localId: string }
| { type: 'rebind'; localId: string; file: File }
| { type: 'remove'; localId: string }
Setting up a client
import { createUploadClient, createXHRTransport } from '@gentleduck/upload/core'
import { createStrategyRegistry, multipartStrategy, PostStrategy } from '@gentleduck/upload/strategies'
// 1. Define your intent and cursor maps
type MyIntentMap = {
multipart: MultipartIntent
post: PostIntent
}
type MyCursorMap = {
multipart?: MultipartCursor
post?: PostCursor
}
type Purpose = 'avatar' | 'document'
// 2. Create strategy registry
const strategies = createStrategyRegistry<MyIntentMap, MyCursorMap, Purpose>()
strategies.set(multipartStrategy())
strategies.set(PostStrategy())
// 3. Create the client
const uploadClient = createUploadClient<MyIntentMap, MyCursorMap, Purpose>({
strategies,
transport: createXHRTransport(),
api: {
createIntent: async (args, opts) => {
// POST to your backend, return the intent
const res = await fetch('/api/uploads/intent', {
method: 'POST',
body: JSON.stringify(args),
signal: opts?.signal,
})
return res.json()
},
complete: async (args, opts) => {
const res = await fetch(`/api/uploads/${args.fileId}/complete`, {
method: 'POST',
signal: opts?.signal,
})
return res.json()
},
multipart: {
signPart: async (args, opts) => { /* ... */ },
completeMultipart: async (args, opts) => { /* ... */ },
},
},
config: {
maxConcurrentUploads: 3,
progressThrottleMs: 100,
maxAttempts: 3,
maxItems: 100,
autoStart: ['avatar'], // auto-start for specific purposes
validation: {
avatar: { maxSize: 5 * 1024 * 1024, allowedTypes: ['image/*'] },
},
},
})
React integration
UploadProvider
import { UploadProvider } from '@gentleduck/upload/react'
function App() {
return (
<UploadProvider store={uploadClient}>
<UploadDropzone />
</UploadProvider>
)
}
useUploader hook
Returns reactive state and dispatch. Works with context or explicit store.
import { useUploader } from '@gentleduck/upload/react'
function UploadDropzone() {
const { items, uploading, completed, failed, ready, paused, dispatch, on, off } = useUploader()
const handleFiles = (files: File[]) => {
dispatch({ type: 'addFiles', files, purpose: 'avatar' })
}
// items: UploadItem[] — all items
// uploading/completed/failed/ready/paused — filtered by phase
// dispatch — send commands
// on/off — subscribe to typed events
}
useUploaderActions hook
Stable imperative surface (no reactive state). Good for callbacks.
import { useUploaderActions } from '@gentleduck/upload/react'
function UploadButton() {
const { dispatch, on, store } = useUploaderActions()
// dispatch and on are stable refs
}
createUploadFactory
Creates a typed hook bound to a specific store instance.
import { createUploadFactory } from '@gentleduck/upload/react'
const useMyUploader = createUploadFactory(uploadClient)
function Component() {
const { items, dispatch } = useMyUploader()
}
Events
Subscribe via store.on() or the on from useUploader():
const unsub = store.on('upload.progress', ({ localId, pct, uploadedBytes, totalBytes }) => {
console.log(`${localId}: ${pct.toFixed(1)}%`)
})
Event types:
file.added,file.rejectedvalidation.ok,validation.failedintent.creating,intent.created,intent.failedupload.queued,upload.resumed,upload.started,upload.progressupload.cursor,upload.paused,upload.canceledupload.completing,upload.completed,upload.error
Strategies
Multipart (S3/MinIO style, resumable)
import { multipartStrategy } from '@gentleduck/upload/strategies'
const strategy = multipartStrategy({ maxPartConcurrency: 4 })
// id: 'multipart', resumable: true
Requires api.multipart.signPart() and api.multipart.completeMultipart().
Cursor tracks completed parts with ETags for resume.
POST (presigned form, non-resumable)
import { PostStrategy } from '@gentleduck/upload/strategies'
const strategy = PostStrategy()
// id: 'post', resumable: false
Uses transport.postForm() with presigned URL and form fields from the intent.
Custom strategy
const myStrategy: UploadStrategy<MyIntentMap, MyCursorMap, Purpose, MyResult, 'custom'> = {
id: 'custom',
resumable: false,
async start(ctx) {
// ctx.file, ctx.intent, ctx.signal, ctx.transport, ctx.api
// ctx.reportProgress({ uploadedBytes, totalBytes })
// ctx.readCursor(), ctx.persistCursor(cursor)
await ctx.transport.put({
url: ctx.intent.uploadUrl,
body: ctx.file,
signal: ctx.signal,
onProgress: (loaded, total) => ctx.reportProgress({ uploadedBytes: loaded, totalBytes: total }),
})
},
}
UploadApi contract
The backend must implement this interface:
interface UploadApi<M extends IntentMap, P extends string, R extends UploadResultBase> {
createIntent(args: {
purpose: P
contentType: string
size: number
filename: string
checksum?: string
}, opts?: WithSignal): Promise<M[keyof M]>
complete(args: { fileId: string }, opts?: WithSignal): Promise<R>
// Optional
getSignedPreviewUrl?(args: { fileId: string; key: string; purpose: P }, opts?: WithSignal): Promise<string>
findByChecksum?(args: { checksum: string; purpose: P }, opts?: WithSignal): Promise<R | null>
multipart?: {
signPart(args: { fileId: string; uploadId: string; partNumber: number; checksum?: string }, opts?: WithSignal): Promise<{ url: string; headers?: Record<string, string> }>
completeMultipart(args: { fileId: string; uploadId: string; parts: Array<{ partNumber: number; etag: string }> }, opts?: WithSignal): Promise<unknown>
listParts?(args: { fileId: string; uploadId: string }, opts?: WithSignal): Promise<Array<{ partNumber: number; etag?: string; size?: number }>>
abort?(args: { fileId: string; uploadId: string }, opts?: WithSignal): Promise<void>
}
tus?: {
create(args: { fileId: string; size: number; filename: string; contentType: string }, opts?: WithSignal): Promise<{ uploadUrl: string }>
getOffset(args: { uploadUrl: string }, opts?: WithSignal): Promise<{ offset: number }>
}
}
UploadResultBase is { fileId: string; key: string }. Extend it for your app.
Persistence
import { LocalStorageAdapter, IndexedDBAdapter, MemoryAdapter } from '@gentleduck/upload/core'
const client = createUploadClient({
// ...
persistence: {
key: 'my-uploads',
version: 1,
debounceMs: 200,
adapter: LocalStorageAdapter, // or IndexedDBAdapter, MemoryAdapter
},
})
Paused items survive page reloads. Use rebind command to re-attach the File object after restore.
Plugins
const debugPlugin: UploadPlugin<MyIntentMap, MyCursorMap, Purpose> = {
name: 'debug',
setup(ctx) {
ctx.on('upload.progress', (e) => console.log(e))
ctx.on('upload.completed', (e) => console.log('Done:', e.localId))
},
}
const client = createUploadClient({
// ...
plugins: [debugPlugin],
})
Progress tracking
UploadProgress shape on every uploading item:
type UploadProgress = {
uploadedBytes: number
totalBytes: number
pct: number // 0..100
}
Access via item.progress or listen to upload.progress events.
Throttled by config.progressThrottleMs (default 100ms).
waitFor
const outcomes = await store.waitFor(['id1', 'id2'])
// UploadOutcome[] — each is { localId, status: 'completed' | 'error' | 'canceled' | 'missing', ... }
Configuration defaults
| Option | Default |
|---|---|
maxConcurrentUploads | 3 |
progressThrottleMs | 100 |
maxAttempts | 3 |
maxItems | 100 |
completedItemTTL | undefined (keep forever) |
Coding style
- Formatter: Biome — single quotes, no semicolons, 2-space indent, 120 line width, trailing commas
- Imports: Use
import typefor type-only imports (enforced by BiomeuseImportType) - Generics: 4 type params everywhere:
M extends IntentMap, C extends CursorMap<M>, P extends string, R extends UploadResultBase - Files: kebab-case, types in
.types.tsfiles, strategy per directory - No classes: Pure functions and object literals
- React:
'use client'directive on React files,React.useSyncExternalStorefor store binding - Exports: Barrel files (
index.ts) re-export withexport * from
Do not
- Do NOT use
classfor strategies or stores — use factory functions returning plain objects - Do NOT import from internal paths like
core/engine/store/store.runtime— use the public exports - Do NOT mutate state directly — always dispatch commands
- Do NOT skip the
UploadApicontract — the engine requirescreateIntentandcomplete - Do NOT assume
Fileis always present on paused items — it may beundefinedafter persistence restore - Do NOT use
fetchfor upload transport in browsers — XHR is required for upload progress events - Do NOT hardcode strategy IDs — use the
IntentMaptype system
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |