Chapter 8: Production Patterns

Extend Contracts.Result.Base

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

// Contracts.Result.Base = { fileId: string; key: string }
export type PhotoDuckResult = Contracts.Result.Base & {
  url: string
  thumbnailUrl: string
  width: number
  height: number
}

R flows through the whole store. With createUploadStore<M, C, P, PhotoDuckResult>, every completed item exposes item.result: PhotoDuckResult — no casts.

Type the intent and cursor maps

Build intents on Contracts.Intent.Base; the cursor map holds raw cursor types.

import type { Contracts } from '@gentleduck/upload/core'
import type { PostStrategy, MultipartStrategy } from '@gentleduck/upload/strategies'

export type PhotoDuckIntents = {
  post: PostStrategy.Intent
  multipart: MultipartStrategy.Intent
}
export type PhotoDuckCursors = {
  post?: PostStrategy.Cursor
  multipart?: MultipartStrategy.Cursor
}
export type PhotoDuckPurpose = 'photo' | 'avatar' | 'document'

These guarantee: createIntent returns a valid intent shape, a paused item's cursor matches its strategy, addFiles({ purpose: 'invalid' }) is a compile error, and item.result is PhotoDuckResult.

Implement the typed contract

Every method takes args and ctx; use ctx.signal to stay cancelable.

import type { Contracts } from '@gentleduck/upload/core'
import type { PhotoDuckIntents, PhotoDuckPurpose, PhotoDuckResult } from '../types/upload'

export const photoDuckApi: Contracts.Api.Me<PhotoDuckIntents, PhotoDuckPurpose, PhotoDuckResult> = {
  async createIntent({ purpose, contentType, size, filename, checksum }, ctx) {
    const res = await fetch('/api/uploads/intent', {
      method: 'POST',
      headers: { 'content-type': 'application/json' },
      body: JSON.stringify({ purpose, contentType, size, filename, checksum }),
      signal: ctx.signal,
    })
    if (!res.ok) throw new Error(`intent failed: ${res.status}`)
    return res.json() // PostStrategy.Intent | MultipartStrategy.Intent
  },
  async complete({ fileId, filename, contentType, size }, ctx) {
    const res = await fetch(`/api/uploads/${fileId}/complete`, {
      method: 'POST',
      headers: { 'content-type': 'application/json' },
      body: JSON.stringify({ filename, contentType, size }),
      signal: ctx.signal,
    })
    if (!res.ok) throw new Error(`complete failed: ${res.status}`)
    return res.json() // PhotoDuckResult
  },
  async findByChecksum({ checksum, purpose }, ctx) {
    const res = await fetch(`/api/uploads/find?checksum=${checksum}&purpose=${purpose}`, {
      signal: ctx.signal,
    })
    if (!res.ok) return null
    return (await res.json()) as PhotoDuckResult | null
  },
  multipart: {
    async signPart({ fileId, uploadId, partNumber }, ctx) {
      const res = await fetch('/api/uploads/multipart/sign', {
        method: 'POST',
        headers: { 'content-type': 'application/json' },
        body: JSON.stringify({ fileId, uploadId, partNumber }),
        signal: ctx.signal,
      })
      return res.json()
    },
    async completeMultipart({ fileId, uploadId, parts }, ctx) {
      await fetch('/api/uploads/multipart/complete', {
        method: 'POST',
        headers: { 'content-type': 'application/json' },
        body: JSON.stringify({ fileId, uploadId, parts }),
        signal: ctx.signal,
      })
    },
  },
}

createIntent is the backend's decision point: it inspects size/purpose and returns the right intent. The engine never picks the strategy — the backend does.

Deduplicate by checksum

If the fingerprint carries a checksum and findByChecksum is implemented, the engine checks for an existing file during validation and, on a match, completes the item instantly with completedBy: 'dedupe' — no intent, no bytes.

The default fingerprint has no checksum, and the fingerprint option must be synchronous. So compute hashes before adding files, then look them up in fingerprint:

async function sha256Hex(file: File): Promise<string> {
  const buf = await crypto.subtle.digest('SHA-256', await file.arrayBuffer())
  return [...new Uint8Array(buf)].map((b) => b.toString(16).padStart(2, '0')).join('')
}

const checksums = new Map<File, string>()

export async function addWithChecksum(files: File[], purpose: PhotoDuckPurpose) {
  await Promise.all(files.map(async (f) => checksums.set(f, await sha256Hex(f))))
  store.dispatch({ type: 'addFiles', files, purpose })
}

// In the store:
// fingerprint: (file) => ({
//   name: file.name, size: file.size, type: file.type,
//   lastModified: file.lastModified, checksum: checksums.get(file),
// }),

Contracts.FingerprintFile is { name, size, type, lastModified, checksum? }. For very large files, respect config.checksumMaxSize (the built-in checksum step skips files above it).

Multiple purposes

Each purpose gets its own rules, and autoStart can target specific ones:

createUploadStore<PhotoDuckIntents, PhotoDuckCursors, PhotoDuckPurpose, PhotoDuckResult>({
  api: photoDuckApi,
  strategies,
  config: {
    maxConcurrentUploads: 3,
    autoStart: (purpose) => purpose === 'avatar', // or ['avatar']
    validation: {
      photo:    { maxFiles: 50, maxSizeBytes: 10 * 1024 * 1024, allowedTypes: ['image/*'] },
      avatar:   { maxFiles: 1,  maxSizeBytes: 2 * 1024 * 1024,  allowedTypes: ['image/jpeg', 'image/png', 'image/webp'] },
      document: { maxFiles: 10, maxSizeBytes: 50 * 1024 * 1024, allowedTypes: ['application/pdf'], allowedExtensions: ['pdf'] },
    },
  },
})

Scope batch commands by purpose, and filter items by purpose in the UI:

dispatch({ type: 'startAll', purpose: 'photo' })
const photos = items.filter((i) => i.purpose === 'photo')