@gentleduck/upload 0.2.1

package/src/core/persistence/persistence.ts

@@ -0,0 +1,194 @@
+import type { AnyCursor, CursorMap, IntentMap, UploadResultBase } from '../contracts'
+import type { UploadItem } from '../engine/internal-events.types'
+import type { UploadState } from '../engine/reducer'
+import { hasCursor, hasIntent } from '../engine/store/store.libs'
+import { isRecord } from '../utils/guards'
+import type { PersistedSnapshot, PersistedUploadItem } from './persistence.types'
+
+/**
+ * Serializes the current upload state into a JSON-safe structure.
+ * Only serializes items that have a valid 'intent', as these are the only ones
+ * that can be resumed cleanly.
+ */
+export function serializeSnapshot<
+  M extends IntentMap,
+  C extends CursorMap<M>,
+  P extends string,
+  R extends UploadResultBase,
+>(state: UploadState<M, C, P, R>, version: number): PersistedSnapshot<M, C, P> {
+  const items: Record<string, PersistedUploadItem<M, C, P>> = {}
+
+  for (const item of state.items.values()) {
+    if (!hasIntent(item)) continue
+
+    // Do not persist terminal items. Persistence is for resuming and recovery, not history.
+    if (item.phase === 'completed' || item.phase === 'canceled' || item.phase === 'error') continue
+
+    const cursor = hasCursor(item) ? item.cursor : undefined
+
+    const progress =
+      'progress' in item && item.progress
+        ? {
+            uploadedBytes: item.progress.uploadedBytes,
+            totalBytes: item.progress.totalBytes,
+            pct: item.progress.pct,
+          }
+        : undefined
+
+    const persisted: PersistedUploadItem<M, C, P> = {
+      id: item.localId,
+      purpose: item.purpose,
+      status: item.phase,
+      file: {
+        name: item.fingerprint.name,
+        size: item.fingerprint.size,
+        type: item.fingerprint.type,
+        lastModified: item.fingerprint.lastModified,
+        checksum: item.fingerprint.checksum,
+      },
+      intent: item.intent,
+      cursor,
+      progress,
+    }
+
+    items[persisted.id] = persisted
+  }
+
+  return { version, createdAt: Date.now(), items }
+}
+
+/**
+ * Deserializes a persisted snapshot back into a store state.
+ *
+ * Important:
+ * - Browser `File` objects cannot be restored from persistence.
+ * - We restore resumable items (those with a cursor) into the `paused` phase,
+ *   with `file` left undefined. Your UI can ask the user to rebind the file.
+ */
+export function deserializeSnapshot<
+  M extends IntentMap,
+  C extends CursorMap<M>,
+  P extends string,
+  R extends UploadResultBase,
+>(
+  raw: unknown,
+  opts: {
+    isPurpose?: (value: string) => value is P
+    isIntent?: (value: unknown) => value is M[keyof M]
+    hasStrategy: (value: string) => boolean
+  },
+): UploadState<M, C, P, R> | null {
+  if (!opts.isPurpose || !opts.isIntent) return null
+  if (!isPersistedSnapshot(raw)) return null
+
+  const items = new Map<string, UploadItem<M, C, P, R>>()
+
+  for (const value of Object.values(raw.items)) {
+    const parsed = parsePersistedItem(value)
+    if (!parsed) continue
+
+    if (!opts.isPurpose(parsed.purpose)) continue
+    if (!opts.isIntent(parsed.intent)) continue
+
+    const strategy = parsed.intent.strategy
+    if (typeof strategy !== 'string' || !opts.hasStrategy(strategy)) continue
+
+    if (!parsed.cursor || !isCursorForRegistry<C>(parsed.cursor, opts.hasStrategy)) continue
+    if (parsed.cursor.strategy !== strategy) continue
+
+    const totalBytes = parsed.progress?.totalBytes ?? parsed.file.size
+    const uploadedBytes = parsed.progress?.uploadedBytes ?? 0
+    const pct =
+      typeof parsed.progress?.pct === 'number'
+        ? parsed.progress.pct
+        : totalBytes > 0
+          ? Math.min(100, Math.max(0, (uploadedBytes / totalBytes) * 100))
+          : 0
+
+    items.set(parsed.id, {
+      phase: 'paused',
+      localId: parsed.id,
+      purpose: parsed.purpose,
+      fingerprint: {
+        name: parsed.file.name,
+        size: parsed.file.size,
+        type: parsed.file.type,
+        lastModified: parsed.file.lastModified,
+        checksum: parsed.file.checksum,
+      },
+      intent: parsed.intent,
+      cursor: parsed.cursor,
+      progress: { uploadedBytes, totalBytes, pct },
+      pausedAt: Date.now(),
+      createdAt: raw.createdAt ?? Date.now(),
+      file: undefined,
+    })
+  }
+
+  return { items }
+}
+
+function isPersistedSnapshot(value: unknown): value is PersistedSnapshot<unknown, unknown, string> {
+  if (!isRecord(value)) return false
+  if (typeof value.version !== 'number') return false
+  if (typeof value.createdAt !== 'number') return false
+  return isRecord(value.items)
+}
+
+function parsePersistedItem(value: unknown): {
+  id: string
+  purpose: string
+  status: string
+  file: { name: string; size: number; type: string; lastModified: number; checksum?: string }
+  intent: unknown
+  cursor?: unknown
+  progress?: { uploadedBytes: number; totalBytes: number; pct?: number }
+} | null {
+  if (!isRecord(value)) return null
+
+  const id = typeof value.id === 'string' ? value.id : null
+  const purpose = typeof value.purpose === 'string' ? value.purpose : null
+  const status = typeof value.status === 'string' ? value.status : null
+  const intent = value.intent
+
+  if (!id || !purpose || !status) return null
+
+  if (!isRecord(value.file)) return null
+
+  const name = typeof value.file.name === 'string' ? value.file.name : null
+  const size = typeof value.file.size === 'number' ? value.file.size : null
+  const type = typeof value.file.type === 'string' ? value.file.type : null
+  const lastModified = typeof value.file.lastModified === 'number' ? value.file.lastModified : null
+  const checksum = typeof value.file.checksum === 'string' ? value.file.checksum : undefined
+
+  if (!name || size === null || !type || lastModified === null) return null
+
+  const progress = parseProgress(value.progress)
+
+  return {
+    id,
+    purpose,
+    status,
+    file: { name, size, type, lastModified, checksum },
+    intent,
+    cursor: value.cursor,
+    progress,
+  }
+}
+
+function parseProgress(value: unknown): { uploadedBytes: number; totalBytes: number; pct?: number } | undefined {
+  if (!isRecord(value)) return undefined
+  if (typeof value.uploadedBytes !== 'number' || typeof value.totalBytes !== 'number') return undefined
+  const pct = typeof value.pct === 'number' ? value.pct : undefined
+  return { uploadedBytes: value.uploadedBytes, totalBytes: value.totalBytes, pct }
+}
+
+function isCursorForRegistry<C extends Record<string, unknown>>(
+  value: unknown,
+  hasStrategy: (value: string) => boolean,
+): value is AnyCursor<C> {
+  if (!isRecord(value)) return false
+  if (typeof value.strategy !== 'string') return false
+  if (!hasStrategy(value.strategy)) return false
+  return true
+}

package/src/core/persistence/persistence.types.ts

@@ -0,0 +1,66 @@
+/**
+ * A minimal, serializable representation of an upload item that is safe to store
+ * in persistence (LocalStorage, IndexedDB, etc).
+ *
+ * This type is intentionally not the full {@link UploadItem} state.
+ * It captures only the fields needed to:
+ * - restore the UI list after refresh
+ * - rebind an upload to its backend intent (if already created)
+ * - resume an upload strategy from a known cursor (when supported)
+ * - restore last-known progress and phase for UX continuity
+ *
+ * @typeParam M - Map of upload intent variants keyed by intent kind (e.g. `direct`, `multipart`).
+ * @typeParam C - Map of cursor shapes keyed by {@link M}'s intent kinds.
+ * @typeParam P - Union of allowed `purpose` strings for your app (e.g. `"avatar" | "document"`).
+ */
+export type PersistedSnapshot<M, C, P extends string> = {
+  /** Persistence schema version (not app version). */
+  version: number
+  /** Unix epoch milliseconds when this snapshot was written. */
+  createdAt: number
+  /** List of persisted upload items. */
+  items: Record<string, PersistedUploadItem<M, C, P>>
+}
+
+export type PersistedUploadItem<M, C, P extends string> = {
+  /** Stable, client-generated ID for this upload in local state. */
+  id: string
+  /** File name. */
+  file: {
+    /** File name. */
+    name: string
+    /** File size in bytes. */
+    size: number
+    /** File MIME type. */
+    type: string
+    /** File lastModified timestamp (ms). */
+    lastModified: number
+    /** Optional checksum (example: SHA-256 hex). */
+    checksum?: string
+  }
+  /** Backend-provided "intent" that describes how to upload (strategy, URLs, fields, etc). */
+  intent: M[keyof M]
+  /** Strategy cursor used to resume uploads that support continuation. */
+  cursor?: import('../contracts').AnyCursor<C>
+  /** Last-known progress for UX continuity after restoring from persistence. */
+  progress?: { uploadedBytes: number; totalBytes: number; pct?: number }
+  /** The last known state-machine phase at the time of persistence. */
+  status: string
+  /** Logical purpose for the upload (application-defined). */
+  purpose: P
+}
+
+/**
+ * A persisted snapshot of the upload store.
+ *
+ * Snapshots are versioned to allow safe migrations when the persistence schema evolves.
+ * They are time-stamped for diagnostics and garbage-collection policies.
+ */
+export interface PersistenceAdapter {
+  /** Loads a snapshot from persistence. */
+  load(key: string): unknown | null | Promise<unknown | null>
+  /** Saves a snapshot to persistence. */
+  save(key: string, snapshot: unknown): void | Promise<void>
+  /** Clears a snapshot from persistence. */
+  clear(key: string): void | Promise<void>
+}

package/src/core/utils/async.ts

@@ -0,0 +1,3 @@
+export function sleep(ms: number) {
+  return new Promise<void>((resolve) => setTimeout(resolve, ms))
+}

package/src/core/utils/constants.ts

@@ -0,0 +1,32 @@
+/**
+ * Default retry delay base in milliseconds.
+ * Used for exponential backoff calculation: base * 2^(attempt - 1)
+ */
+export const DEFAULT_RETRY_DELAY_BASE_MS = 500
+
+/**
+ * Maximum retry delay in milliseconds.
+ * Caps exponential backoff to prevent excessive delays.
+ */
+export const DEFAULT_RETRY_DELAY_MAX_MS = 10_000
+
+/**
+ * Default progress event throttle in milliseconds.
+ * Prevents excessive progress updates from overwhelming the UI.
+ */
+export const DEFAULT_PROGRESS_THROTTLE_MS = 100
+
+/**
+ * Default maximum number of retry attempts.
+ */
+export const DEFAULT_MAX_ATTEMPTS = 3
+
+/**
+ * Default maximum number of concurrent uploads.
+ */
+export const DEFAULT_MAX_CONCURRENT_UPLOADS = 3
+
+/**
+ * Default maximum number of items to keep in memory.
+ */
+export const DEFAULT_MAX_ITEMS = 100

package/src/core/utils/emitter/emitter.types.ts

@@ -0,0 +1,23 @@
+/**
+ * Minimal typed event emitter interface.
+ *
+ * Use this to expose strongly-typed events from your store.
+ *
+ * @typeParam E - Event map (`eventName -> payload`).
+ */
+export type TypedEmitter<E extends Record<string, unknown>> = {
+  /**
+   * Subscribe to an event.
+   * @returns Unsubscribe function.
+   */
+  on<K extends keyof E & string>(type: K, cb: (payload: E[K]) => void): () => void
+
+  /**
+   * Unsubscribe from an event.
+   * @returns Unsubscribe function.
+   */
+  off<K extends keyof E & string>(type: K, cb: (payload: E[K]) => void): () => void
+
+  /** Emit an event to all listeners. */
+  emit<K extends keyof E & string>(type: K, payload: E[K]): void
+}

package/src/core/utils/emitter/index.ts

@@ -0,0 +1,68 @@
+import type { TypedEmitter } from './emitter.types'
+
+/**
+ * Creates a lightweight, typed event emitter.
+ * We use this instead of `EventEmitter` or `EventTarget` to ensure:
+ * 1. Strict typing of event payloads (via generic E)
+ * 2. No dependency on Node.js built-ins (browser compatible)
+ * 3. Exception safety (user listeners don't crash the loop)
+ *
+ * @template E - Event map type (Record<eventName, payloadType>)
+ *
+ * @returns {TypedEmitter<E>} Typed emitter instance
+ *
+ * @example
+ * ```ts
+ * type Events = { 'file.added': { id: string }, 'upload.progress': { pct: number } }
+ * const emitter = createTypedEmitter<Events>()
+ * emitter.on('file.added', (payload) => console.log(payload.id))
+ * ```
+ */
+type ListenerMap<E extends Record<string, unknown>> = Partial<{
+  [K in keyof E & string]: Set<(payload: E[K]) => void>
+}>
+
+export function createTypedEmitter<E extends Record<string, unknown>>(): TypedEmitter<E> {
+  const listeners: ListenerMap<E> = {}
+
+  return {
+    on<K extends keyof E & string>(type: K, cb: (payload: E[K]) => void): () => void {
+      // Create listener set for this event type if it doesn't exist
+      const set = listeners[type] ?? (listeners[type] = new Set<(payload: E[K]) => void>())
+      set.add(cb)
+
+      // Return unsubscribe function
+      return () => {
+        const typeListeners = listeners[type]
+        if (!typeListeners) return
+        typeListeners.delete(cb)
+        if (typeListeners.size === 0) delete listeners[type]
+      }
+    },
+
+    off<K extends keyof E & string>(type: K, cb: (payload: E[K]) => void): () => void {
+      const typeListeners = listeners[type]
+      if (!typeListeners) return () => {}
+      typeListeners.delete(cb)
+      if (typeListeners.size === 0) delete listeners[type]
+      return () => {}
+    },
+
+    emit<K extends keyof E & string>(type: K, payload: E[K]): void {
+      const typeListeners = listeners[type]
+      if (!typeListeners) return
+
+      typeListeners.forEach((cb) => {
+        try {
+          cb(payload)
+        } catch (err) {
+          // Do not crash upload engine due to user callbacks
+          // In production, this should be sent to error tracking service
+          if (typeof window !== 'undefined' && process.env.NODE_ENV === 'development') {
+            console.error(`[UploadEngine] Error in event listener for "${type}":`, err)
+          }
+        }
+      })
+    },
+  }
+}

package/src/core/utils/fingerprint.ts

@@ -0,0 +1,20 @@
+import type { FileFingerprint } from '../contracts'
+
+/**
+ * Builds a lightweight fingerprint from a {@link File}.
+ */
+export function computeFingerprint(file: File): FileFingerprint {
+  return {
+    name: file.name,
+    size: file.size,
+    type: file.type,
+    lastModified: file.lastModified,
+  }
+}
+
+/**
+ * Compares two file fingerprints.
+ */
+export function fingerprintMatches(a: FileFingerprint, b: FileFingerprint): boolean {
+  return a.name === b.name && a.size === b.size && a.lastModified === b.lastModified
+}

package/src/core/utils/guards.ts

@@ -0,0 +1,3 @@
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === 'object'
+}

package/src/core/utils/id.ts

@@ -0,0 +1,3 @@
+export function generateId(): string {
+  return `upload_${Date.now()}_${Math.random().toString(36).slice(2)}`
+}

package/src/core/utils/index.ts

@@ -0,0 +1,6 @@
+export * from './async'
+export * from './constants'
+export * from './emitter'
+export * from './fingerprint'
+export * from './guards'
+export * from './id'

package/src/index.ts

@@ -0,0 +1,3 @@
+export * from './core'
+export * from './react'
+export * from './strategies'

package/src/react/index.ts

@@ -0,0 +1,2 @@
+export * from './upload-provider'
+export * from './use-uploader'

package/src/react/upload-provider.tsx

@@ -0,0 +1,96 @@
+'use client'
+
+/**
+ * @fileoverview React context provider for the upload store.
+ *
+ * Provides the upload store instance to all child components via React Context.
+ * This allows components to access the store without prop drilling.
+ *
+ * @module upload-provider
+ */
+
+import { createContext, type ReactNode, useContext } from 'react'
+import { type CursorMap, type IntentMap, isRecord, type UploadResultBase } from '../core'
+import type { UploadStore } from '../core/engine/store'
+
+/**
+ * React context for the upload store.
+ * Initialized as null and must be provided via UploadProvider.
+ *
+ * Note: Context cannot be generic at the type level in React, so we use a base type.
+ * The useUploadStore hook provides type safety through type assertion which is safe
+ * because the provider ensures the correct type is stored.
+ */
+const UploadContext = createContext<unknown | null>(null)
+
+/**
+ * Provider component that makes the upload store available to child components.
+ *
+ * @template M - Intent map type
+ * @template C - Cursor map type
+ * @template P - Purpose type
+ *
+ * @param props - Provider props
+ * @param props.store - Upload store instance to provide
+ * @param props.children - Child components that can access the store
+ *
+ * @returns {JSX.Element} Context provider wrapping children
+ *
+ * @example
+ * ```tsx
+ * <UploadProvider store={store}>
+ *   <UploadDropzone purpose="avatar" />
+ * </UploadProvider>
+ * ```
+ */
+export function UploadProvider<
+  M extends IntentMap,
+  C extends CursorMap<M>,
+  P extends string,
+  R extends UploadResultBase = UploadResultBase,
+>({ store, children }: { store: UploadStore<M, C, P, R>; children: ReactNode }): React.JSX.Element {
+  return <UploadContext.Provider value={store}>{children}</UploadContext.Provider>
+}
+
+/**
+ * Hook to access the upload store from React context.
+ *
+ * @template M - Intent map type
+ * @template C - Cursor map type
+ * @template P - Purpose type
+ *
+ * @returns {UploadStore<M, C, P>} The upload store instance
+ * @throws {Error} If called outside of UploadProvider
+ *
+ * @example
+ * ```tsx
+ * const store = useUploadStore()
+ * const snapshot = store.getSnapshot()
+ * ```
+ */
+export function useUploadStore<
+  M extends IntentMap,
+  C extends CursorMap<M>,
+  P extends string,
+  R extends UploadResultBase = UploadResultBase,
+>(): UploadStore<M, C, P, R> {
+  const store = useContext(UploadContext)
+  if (!store || !isUploadStore<M, C, P, R>(store)) {
+    throw new Error('useUploadStore must be used within UploadProvider')
+  }
+  return store
+}
+
+function isUploadStore<M extends IntentMap, C extends CursorMap<M>, P extends string, R extends UploadResultBase>(
+  value: unknown,
+): value is UploadStore<M, C, P, R> {
+  if (!isRecord(value)) return false
+  return (
+    typeof value.getSnapshot === 'function' &&
+    typeof value.subscribe === 'function' &&
+    typeof value.dispatch === 'function' &&
+    typeof value.on === 'function' &&
+    typeof value.off === 'function' &&
+    typeof value.waitFor === 'function'
+  )
+}

package/src/react/use-uploader.tsx

@@ -0,0 +1,115 @@
+'use client'
+
+import * as React from 'react'
+import type {
+  CursorMap,
+  IntentMap,
+  UploadCommand,
+  UploadEventMap,
+  UploadItem,
+  UploadPhase,
+  UploadResultBase,
+} from '../core'
+import type { UploadStore } from '../core/engine/store'
+import { useUploadStore } from './upload-provider'
+
+export function createUploadFactory<
+  M extends IntentMap,
+  C extends CursorMap<M>,
+  P extends string,
+  R extends UploadResultBase = UploadResultBase,
+>(store: UploadStore<M, C, P, R>) {
+  return () => useUploader<M, C, P, R>(store)
+}
+
+export type PickItemsByPhase<Phase extends UploadPhase> = Extract<
+  UploadItem<IntentMap, CursorMap<IntentMap>, string, UploadResultBase>,
+  { phase: Phase }
+>
+
+type Uploader<M extends IntentMap, C extends CursorMap<M>, P extends string, R extends UploadResultBase> = {
+  items: UploadItem<M, C, P, R>[]
+  byPhase: Record<string, UploadItem<M, C, P, R>[]>
+  dispatch: (cmd: UploadCommand<P>) => void
+  on: <K extends keyof UploadEventMap<M, C, P, R> & string>(
+    type: K,
+    cb: (payload: UploadEventMap<M, C, P, R>[K]) => void,
+  ) => () => void
+  off: <K extends keyof UploadEventMap<M, C, P, R> & string>(
+    type: K,
+    cb: (payload: UploadEventMap<M, C, P, R>[K]) => void,
+  ) => () => void
+  uploading: UploadItem<M, C, P, R>[]
+  paused: UploadItem<M, C, P, R>[]
+  completed: UploadItem<M, C, P, R>[]
+  failed: UploadItem<M, C, P, R>[]
+  ready: UploadItem<M, C, P, R>[]
+}
+
+export function useUploader<
+  M extends IntentMap,
+  C extends CursorMap<M>,
+  P extends string,
+  R extends UploadResultBase = UploadResultBase,
+>(): Uploader<M, C, P, R>
+export function useUploader<
+  M extends IntentMap,
+  C extends CursorMap<M>,
+  P extends string,
+  R extends UploadResultBase = UploadResultBase,
+>(store: UploadStore<M, C, P, R>): Uploader<M, C, P, R>
+export function useUploader<
+  M extends IntentMap,
+  C extends CursorMap<M>,
+  P extends string,
+  R extends UploadResultBase = UploadResultBase,
+>(_store?: UploadStore<M, C, P, R> | undefined) {
+  const store = _store ?? useUploadStore<M, C, P, R>()
+  const snapshot = React.useSyncExternalStore(
+    store.subscribe.bind(store),
+    store.getSnapshot.bind(store),
+    store.getSnapshot.bind(store),
+  )
+
+  const items = React.useMemo(() => {
+    return Array.from(snapshot.items.values())
+  }, [snapshot.items])
+
+  const byPhase = React.useMemo(() => {
+    const result: Record<string, UploadItem<M, C, P, R>[]> = {}
+    items.forEach((item) => {
+      if (!result[item.phase]) {
+        result[item.phase] = []
+      }
+      result[item.phase].push(item)
+    })
+    return result
+  }, [items])
+
+  return {
+    items,
+    byPhase,
+    dispatch: store.dispatch.bind(store),
+    on: store.on.bind(store),
+    off: store.off.bind(store),
+    uploading: byPhase.uploading || [],
+    paused: byPhase.paused || [],
+    completed: byPhase.completed || [],
+    failed: byPhase.error || [],
+    ready: byPhase.ready || [],
+  }
+}
+
+export function useUploaderActions<
+  M extends IntentMap,
+  C extends CursorMap<M>,
+  P extends string,
+  R extends UploadResultBase = UploadResultBase,
+>() {
+  const store = useUploadStore<M, C, P, R>()
+
+  const dispatch = React.useMemo(() => store.dispatch.bind(store), [store])
+  const on = React.useMemo(() => store.on.bind(store), [store])
+
+  return { dispatch, on, store }
+}

package/src/strategies/index.ts

@@ -0,0 +1,15 @@
+/**
+ * @fileoverview Public exports for upload strategies.
+ *
+ * Re-exports all strategy implementations and types for convenient importing.
+ *
+ * Available strategies:
+ * - PostStrategy: Simple POST uploads (presigned forms)
+ * - multipartStrategy: Chunked multipart uploads (S3-style, resumable)
+ *
+ * @module upload-strategies
+ */
+
+export * from './multipart'
+export * from './post'
+export * from './registry'