Skip to content

gentleeduck/duck-ui / skills/duck-upload

duck-upload

Verified

Activate 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

ConceptDescription
UploadClientAlias for UploadStore. Created via createUploadClient(opts).
UploadStoreMinimal surface: getSnapshot(), subscribe(), dispatch(), on(), off(), waitFor().
UploadCommandUser intent dispatched to the store (discriminated union on type).
UploadItemDiscriminated union on phase — the state of a single upload.
UploadPhasevalidating -> creating_intent -> ready -> queued -> uploading -> completing -> completed. Also: paused, error, canceled.
IntentMapMaps strategy keys to intent types (backend-provided upload instructions).
CursorMapMaps strategy keys to cursor types (resume state, e.g. completed parts).
UploadStrategy{ id, resumable, start(ctx) } — executes the actual file transfer.
StrategyRegistryget(id), has(id), set(strategy) — holds registered strategies.
UploadApiBackend contract: createIntent(), complete(), optional multipart.*, tus.*.
UploadTransportNetwork layer: put(), postForm(), patch(). Default: XHR-based (createXHRTransport()).
PersistenceOptional 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.rejected
  • validation.ok, validation.failed
  • intent.creating, intent.created, intent.failed
  • upload.queued, upload.resumed, upload.started, upload.progress
  • upload.cursor, upload.paused, upload.canceled
  • upload.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

OptionDefault
maxConcurrentUploads3
progressThrottleMs100
maxAttempts3
maxItems100
completedItemTTLundefined (keep forever)

Coding style

  • Formatter: Biome — single quotes, no semicolons, 2-space indent, 120 line width, trailing commas
  • Imports: Use import type for type-only imports (enforced by Biome useImportType)
  • Generics: 4 type params everywhere: M extends IntentMap, C extends CursorMap<M>, P extends string, R extends UploadResultBase
  • Files: kebab-case, types in .types.ts files, strategy per directory
  • No classes: Pure functions and object literals
  • React: 'use client' directive on React files, React.useSyncExternalStore for store binding
  • Exports: Barrel files (index.ts) re-export with export * from

Do not

  • Do NOT use class for 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 UploadApi contract — the engine requires createIntent and complete
  • Do NOT assume File is always present on paused items — it may be undefined after persistence restore
  • Do NOT use fetch for upload transport in browsers — XHR is required for upload progress events
  • Do NOT hardcode strategy IDs — use the IntentMap type system
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 implementationStars: 322kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 322kUpdated Claude CodeCodexVerifiedInstall
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 fallbackStars: 322kUpdated Claude CodeCodexVerifiedInstall
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 alwaysStars: 322kUpdated Claude CodeCodexVerifiedInstall