chapter 1: your first upload

Install @gentleduck/upload

bunnpmpnpmyarn

---

npm install @gentleduck/upload

bunnpmpnpmyarn

---

npm install @gentleduck/upload

This is the only package you need. It includes the core engine, React bindings, and all built-in strategies. It works with npm, yarn, pnpm, and bun.

Define your types

Create src/upload.ts. First, define the intent map, cursor map, purpose union, and result type that describe your upload pipeline:

import type { UploadApi, UploadResultBase } from '@gentleduck/upload'
import { PostIntent, PostCursor } from '@gentleduck/upload'
 
// Intent map: which strategies exist and what data they need
type PhotoIntentMap = {
  post: PostIntent
}
 
// Cursor map: resume state per strategy
type PhotoCursorMap = {
  post: PostCursor
}
 
// Purpose: what kind of upload is this?
type PhotoPurpose = 'photo'
 
// Result: what the backend returns on completion
type PhotoResult = UploadResultBase & {
  url: string
}

import type { UploadApi, UploadResultBase } from '@gentleduck/upload'
import { PostIntent, PostCursor } from '@gentleduck/upload'
 
// Intent map: which strategies exist and what data they need
type PhotoIntentMap = {
  post: PostIntent
}
 
// Cursor map: resume state per strategy
type PhotoCursorMap = {
  post: PostCursor
}
 
// Purpose: what kind of upload is this?
type PhotoPurpose = 'photo'
 
// Result: what the backend returns on completion
type PhotoResult = UploadResultBase & {
  url: string
}

The intent map defines all upload strategies your app supports. Each key is a strategy name, and the value is the data shape your backend returns. For now we use the built-in PostIntent.

The purpose is a string union that categorizes uploads. PhotoDuck only has 'photo' for now, but a real app might have 'avatar' | 'cover' | 'attachment'.

Implement the UploadApi

The UploadApi is the contract between the upload engine and your backend. It has two required methods: createIntent and complete. For now, we mock them:

const api: UploadApi<PhotoIntentMap, PhotoPurpose, PhotoResult> = {
  async createIntent({ purpose, contentType, size, filename }) {
    // In a real app, this calls your backend to get a presigned POST URL
    console.log(`Creating intent for ${filename} (${size} bytes, ${contentType})`)
 
    return {
      strategy: 'post',
      fileId: `file-${Date.now()}`,
      url: 'https://your-bucket.s3.amazonaws.com',
      fields: {
        key: `uploads/${filename}`,
        'Content-Type': contentType,
      },
    }
  },
 
  async complete({ fileId }) {
    // In a real app, this tells your backend the upload finished
    console.log(`Completing upload for ${fileId}`)
    return {
      fileId,
      key: `uploads/${fileId}`,
      url: `https://cdn.example.com/uploads/${fileId}`,
    }
  },
}

const api: UploadApi<PhotoIntentMap, PhotoPurpose, PhotoResult> = {
  async createIntent({ purpose, contentType, size, filename }) {
    // In a real app, this calls your backend to get a presigned POST URL
    console.log(`Creating intent for ${filename} (${size} bytes, ${contentType})`)
 
    return {
      strategy: 'post',
      fileId: `file-${Date.now()}`,
      url: 'https://your-bucket.s3.amazonaws.com',
      fields: {
        key: `uploads/${filename}`,
        'Content-Type': contentType,
      },
    }
  },
 
  async complete({ fileId }) {
    // In a real app, this tells your backend the upload finished
    console.log(`Completing upload for ${fileId}`)
    return {
      fileId,
      key: `uploads/${fileId}`,
      url: `https://cdn.example.com/uploads/${fileId}`,
    }
  },
}

createIntent is called when a file enters the pipeline. Your backend decides the strategy, generates presigned URLs, and returns an intent object. The engine then hands this intent to the matching strategy.

complete is called after the bytes are transferred. Your backend can mark the file as uploaded in the database, generate thumbnails, or return metadata.

Create the upload client

Now wire everything together with createUploadClient:

import {
  createUploadClient,
  createStrategyRegistry,
  PostStrategy,
  createXHRTransport,
} from '@gentleduck/upload'
import type { UploadApi, UploadResultBase } from '@gentleduck/upload'
import { PostIntent, PostCursor } from '@gentleduck/upload'
 
// ... types and api from above ...
 
const strategies = createStrategyRegistry<PhotoIntentMap, PhotoCursorMap, PhotoPurpose, PhotoResult>()
strategies.set(PostStrategy<PhotoIntentMap, PhotoCursorMap, PhotoPurpose, PhotoResult>())
 
export const uploadClient = createUploadClient<PhotoIntentMap, PhotoCursorMap, PhotoPurpose, PhotoResult>({
  api,
  strategies,
  transport: createXHRTransport(),
})

import {
  createUploadClient,
  createStrategyRegistry,
  PostStrategy,
  createXHRTransport,
} from '@gentleduck/upload'
import type { UploadApi, UploadResultBase } from '@gentleduck/upload'
import { PostIntent, PostCursor } from '@gentleduck/upload'
 
// ... types and api from above ...
 
const strategies = createStrategyRegistry<PhotoIntentMap, PhotoCursorMap, PhotoPurpose, PhotoResult>()
strategies.set(PostStrategy<PhotoIntentMap, PhotoCursorMap, PhotoPurpose, PhotoResult>())
 
export const uploadClient = createUploadClient<PhotoIntentMap, PhotoCursorMap, PhotoPurpose, PhotoResult>({
  api,
  strategies,
  transport: createXHRTransport(),
})

createStrategyRegistry creates a registry where you register strategy implementations. PostStrategy() creates the built-in POST strategy for simple file uploads. createXHRTransport() creates a browser-native XHR transport with upload progress support.

Add files and start uploading

Create src/main.ts:

import { uploadClient } from './upload'
 
// Add files to the pipeline
const file = new File(['hello world'], 'photo.jpg', { type: 'image/jpeg' })
uploadClient.dispatch({ type: 'addFiles', files: [file], purpose: 'photo' })
 
// Listen to progress events
uploadClient.on('upload.progress', (event) => {
  console.log(`Progress: ${event.pct.toFixed(1)}% (${event.uploadedBytes}/${event.totalBytes})`)
})
 
// Listen to completion
uploadClient.on('upload.completed', (event) => {
  console.log(`Upload completed: ${event.localId}`, event.result)
})
 
// Listen to errors
uploadClient.on('upload.error', (event) => {
  console.log(`Upload failed: ${event.localId}`, event.error.message)
})
 
// Start all uploads
uploadClient.dispatch({ type: 'startAll' })

import { uploadClient } from './upload'
 
// Add files to the pipeline
const file = new File(['hello world'], 'photo.jpg', { type: 'image/jpeg' })
uploadClient.dispatch({ type: 'addFiles', files: [file], purpose: 'photo' })
 
// Listen to progress events
uploadClient.on('upload.progress', (event) => {
  console.log(`Progress: ${event.pct.toFixed(1)}% (${event.uploadedBytes}/${event.totalBytes})`)
})
 
// Listen to completion
uploadClient.on('upload.completed', (event) => {
  console.log(`Upload completed: ${event.localId}`, event.result)
})
 
// Listen to errors
uploadClient.on('upload.error', (event) => {
  console.log(`Upload failed: ${event.localId}`, event.error.message)
})
 
// Start all uploads
uploadClient.dispatch({ type: 'startAll' })

dispatch is the single entry point for all commands. addFiles puts files into the pipeline. startAll begins uploading every file that is in the ready phase.