@gentleduck/upload 0.2.1

package/src/core/engine/reducer.ts

@@ -0,0 +1,435 @@
+import type { CursorMap, IntentMap, UploadResultBase } from '../contracts'
+import { computeFingerprint, fingerprintMatches } from '../utils/fingerprint'
+import type { UploadCommand } from './commands.types'
+import type { InternalEvent, UploadItem } from './internal-events.types'
+import type { UploadProgress } from './progress.types'
+
+export type UploadState<
+  M extends IntentMap,
+  C extends CursorMap<M>,
+  P extends string,
+  R extends UploadResultBase = UploadResultBase,
+> = {
+  /** Map of uploads by localId for O(1) lookups */
+  items: Map<string, UploadItem<M, C, P, R>>
+}
+
+export function createReducer<
+  M extends IntentMap,
+  C extends CursorMap<M>,
+  P extends string,
+  R extends UploadResultBase = UploadResultBase,
+>() {
+  return function reduce(
+    state: UploadState<M, C, P, R>,
+    event: UploadCommand<P> | InternalEvent<M, C, P, R>,
+  ): UploadState<M, C, P, R> {
+    const items = new Map(state.items)
+
+    const set = (localId: string, next: UploadItem<M, C, P, R>) => items.set(localId, next)
+
+    const now = Date.now()
+
+    // Type guard: Commands don't have dots in their type, internal events do (e.g., 'intent.ok')
+    const isCommand = (e: UploadCommand<P> | InternalEvent<M, C, P, R>): e is UploadCommand<P> => {
+      return 'type' in e && typeof e.type === 'string' && !e.type.includes('.')
+    }
+
+    // Command handling
+    if (isCommand(event)) {
+      switch (event.type) {
+        case 'addFiles': {
+          // handled in store (creates items + emits events)
+          break
+        }
+
+        case 'start': {
+          const item = items.get(event.localId)
+          if (!item) break
+          if (item.phase !== 'ready') break
+
+          set(event.localId, {
+            ...item,
+            phase: 'queued',
+            requestedAt: now,
+          })
+          break
+        }
+
+        case 'resume': {
+          const item = items.get(event.localId)
+          if (!item) break
+          if (item.phase !== 'paused') break
+          if (!item.file) break
+
+          set(event.localId, {
+            ...item,
+            file: item.file,
+            phase: 'queued',
+            requestedAt: now,
+          })
+          break
+        }
+
+        case 'pause': {
+          const item = items.get(event.localId)
+          if (!item) break
+
+          // If it's queued but not started, revert back to ready.
+          if (item.phase === 'queued') {
+            set(event.localId, {
+              ...item,
+              phase: 'ready',
+            })
+          }
+
+          // If it's uploading, store will abort and an internal 'paused' event will move it.
+          break
+        }
+
+        case 'cancel': {
+          const item = items.get(event.localId)
+          if (!item) break
+          if (item.phase === 'completed' || item.phase === 'canceled') break
+
+          set(event.localId, toCanceled(item, now))
+          break
+        }
+
+        case 'retry': {
+          const item = items.get(event.localId)
+          if (!item) break
+          if (item.phase !== 'error' || !item.retryable) break
+          if (!item.file) break
+
+          if (item.intent) {
+            // If we have progress and intent, we were in completing phase - retry completing
+            if (item.progress && item.progress.pct === 100) {
+              set(event.localId, {
+                ...item,
+                progress: item.progress,
+                intent: item.intent,
+                file: item.file,
+                phase: 'completing',
+                completingAt: now,
+              })
+            } else {
+              // Otherwise, retry from ready phase
+              set(event.localId, {
+                ...item,
+                file: item.file,
+                intent: item.intent,
+                phase: 'ready',
+              })
+            }
+          } else {
+            // For intent creation failures, increment attempt on retry
+            set(event.localId, {
+              ...item,
+              phase: 'creating_intent',
+              file: item.file,
+              attempt: (item.attempt ?? 1) + 1,
+            })
+          }
+          break
+        }
+
+        case 'rebind': {
+          const item = items.get(event.localId)
+          if (!item) break
+
+          if (item.phase === 'paused' && !item.file) {
+            const fp = computeFingerprint(event.file)
+            if (fingerprintMatches(fp, item.fingerprint)) {
+              set(event.localId, { ...item, file: event.file })
+            }
+          }
+          break
+        }
+
+        case 'remove': {
+          items.delete(event.localId)
+          break
+        }
+
+        case 'startAll':
+        case 'pauseAll':
+        case 'cancelAll': {
+          // handled in store
+          break
+        }
+      }
+
+      return { items }
+    }
+
+    // Internal event handling
+    switch (event.type) {
+      case 'files.added': {
+        const ev = event
+        for (const item of ev.items) {
+          if (!items.has(item.localId)) {
+            set(item.localId, {
+              phase: 'validating',
+              localId: item.localId,
+              purpose: item.purpose,
+              file: item.file,
+              fingerprint: item.fingerprint,
+              createdAt: item.createdAt,
+            })
+          }
+        }
+        break
+      }
+
+      case 'fingerprint.updated': {
+        const ev = event
+        const item = items.get(ev.localId)
+        if (!item) break
+
+        set(ev.localId, { ...item, fingerprint: ev.fingerprint })
+        break
+      }
+
+      case 'validation.ok': {
+        const item = items.get(event.localId)
+        if (!item || item.phase !== 'validating') break
+
+        set(event.localId, {
+          ...item,
+          phase: 'creating_intent',
+          attempt: 1,
+        })
+        break
+      }
+
+      case 'validation.failed': {
+        const ev = event
+        const item = items.get(ev.localId)
+        if (!item || item.phase !== 'validating') break
+
+        set(ev.localId, {
+          ...item,
+          phase: 'error',
+          error: { code: 'validation_failed', reason: ev.reason, message: String(ev.reason) },
+          retryable: false,
+          attempt: 1,
+          failedAt: now,
+        })
+        break
+      }
+
+      case 'intent.ok': {
+        const ev = event
+        const item = items.get(ev.localId)
+        if (!item || item.phase !== 'creating_intent') break
+
+        set(ev.localId, {
+          ...item,
+          phase: 'ready',
+          intent: ev.intent,
+        })
+        break
+      }
+
+      case 'intent.failed': {
+        const ev = event
+        const item = items.get(ev.localId)
+        if (!item || item.phase !== 'creating_intent') break
+
+        set(ev.localId, {
+          ...item,
+          phase: 'error',
+          error: ev.error,
+          retryable: ev.retryable,
+          failedAt: now,
+        })
+        break
+      }
+
+      case 'upload.begin': {
+        const ev = event
+        const item = items.get(ev.localId)
+        if (!item || item.phase !== 'queued') break
+
+        const total = item.file.size
+        const carried: UploadProgress | undefined = item.progress
+
+        const progress: UploadProgress = carried
+          ? { ...carried, totalBytes: total, pct: pct(carried.uploadedBytes, total) }
+          : { uploadedBytes: 0, totalBytes: total, pct: 0 }
+
+        set(ev.localId, {
+          ...item,
+          phase: 'uploading',
+          progress,
+          startedAt: ev.startedAt,
+        })
+        break
+      }
+
+      case 'upload.progress': {
+        const ev = event
+        const item = items.get(ev.localId)
+        if (!item || item.phase !== 'uploading') break
+
+        const progress: UploadProgress = {
+          uploadedBytes: ev.uploadedBytes,
+          totalBytes: ev.totalBytes,
+          pct: pct(ev.uploadedBytes, ev.totalBytes),
+        }
+
+        set(ev.localId, { ...item, progress })
+        break
+      }
+
+      case 'cursor.updated': {
+        const ev = event
+        const item = items.get(ev.localId)
+        if (!item) break
+
+        if (item.phase === 'uploading') {
+          set(ev.localId, { ...item, cursor: ev.cursor })
+        } else if (item.phase === 'queued') {
+          set(ev.localId, { ...item, cursor: ev.cursor })
+        } else if (item.phase === 'paused') {
+          set(ev.localId, { ...item, cursor: ev.cursor })
+        }
+        break
+      }
+
+      case 'upload.ok': {
+        const ev = event
+        const item = items.get(ev.localId)
+        if (!item || item.phase !== 'uploading') break
+
+        set(ev.localId, {
+          ...item,
+          phase: 'completing',
+          progress: { uploadedBytes: item.file.size, totalBytes: item.file.size, pct: 100 },
+          completingAt: now,
+        })
+        break
+      }
+
+      case 'upload.failed': {
+        const ev = event
+        const item = items.get(ev.localId)
+        if (!item || item.phase !== 'uploading') break
+
+        set(ev.localId, {
+          ...item,
+          phase: 'error',
+          error: ev.error,
+          retryable: ev.retryable,
+          attempt: 1,
+          failedAt: now,
+        })
+        break
+      }
+
+      case 'paused': {
+        const ev = event
+        const item = items.get(ev.localId)
+        if (!item || item.phase !== 'uploading') break
+
+        set(ev.localId, {
+          ...item,
+          phase: 'paused',
+          cursor: ev.cursor,
+          pausedAt: ev.pausedAt,
+        })
+        break
+      }
+
+      case 'canceled': {
+        const ev = event
+        const item = items.get(ev.localId)
+        if (!item) break
+
+        set(ev.localId, toCanceled(item, ev.canceledAt))
+        break
+      }
+
+      case 'complete.ok': {
+        const ev = event
+        const item = items.get(ev.localId)
+        if (!item || item.phase !== 'completing') break
+
+        set(ev.localId, {
+          ...item,
+          phase: 'completed',
+          completedBy: 'upload',
+          result: ev.result,
+          completedAt: now,
+        })
+        break
+      }
+
+      case 'dedupe.ok': {
+        const ev = event
+        const item = items.get(ev.localId)
+        if (!item || item.phase !== 'validating') break
+
+        set(ev.localId, {
+          phase: 'completed',
+          localId: item.localId,
+          file: item.file,
+          purpose: item.purpose,
+          fingerprint: item.fingerprint,
+          result: ev.result,
+          completedBy: 'dedupe',
+          completedAt: now,
+          createdAt: item.createdAt,
+        })
+        break
+      }
+
+      case 'complete.failed': {
+        const ev = event
+        const item = items.get(ev.localId)
+        if (!item || item.phase !== 'completing') break
+
+        // Increment attempt number for retry tracking
+        const nextAttempt = (item.attempt ?? 1) + 1
+
+        set(ev.localId, {
+          ...item,
+          phase: 'error',
+          error: ev.error,
+          retryable: ev.retryable,
+          attempt: nextAttempt,
+          failedAt: now,
+        })
+        break
+      }
+    }
+
+    return { items }
+  }
+}
+
+// Helpers
+function toCanceled<M extends IntentMap, C extends CursorMap<M>, P extends string, R extends UploadResultBase>(
+  item: UploadItem<M, C, P, R>,
+  canceledAt: number,
+): UploadItem<M, C, P, R> {
+  return {
+    phase: 'canceled',
+    localId: item.localId,
+    purpose: item.purpose,
+    fingerprint: item.fingerprint,
+    canceledAt,
+    createdAt: item.createdAt,
+    file: 'file' in item ? item.file : undefined,
+    intent: 'intent' in item ? item.intent : undefined,
+    cursor: 'cursor' in item ? item.cursor : undefined,
+    progress: 'progress' in item ? item.progress : undefined,
+    attempt: 'attempt' in item ? item.attempt : undefined,
+  }
+}
+
+function pct(uploaded: number, total: number) {
+  if (total <= 0) return 0
+  return Math.min(100, (uploaded / total) * 100)
+}

package/src/core/engine/store/handlers/add-file.ts

@@ -0,0 +1,103 @@
+import type { CursorMap, FileFingerprint, IntentMap, UploadResultBase } from '../../../contracts'
+import { generateId } from '../../../utils/id'
+import { validateFile, validateFileList } from '../../validation'
+import { calculateFileChecksum, computeFingerprint } from '../store.libs'
+import type { StoreRuntime } from '../store.types'
+
+/**
+ * Handles the `addFiles` command.
+ *
+ * This function performs fast synchronous work immediately (validation + state insertion)
+ * and then schedules additional async work through the runtime effect queue
+ * (checksum computation, de-dupe checks, and final validation transitions).
+ *
+ * @template M - Intent map type
+ * @template C - Cursor map type
+ * @template P - Purpose string union type
+ *
+ * @param rt - Store runtime
+ * @param files - Files selected by the user
+ * @param purpose - Upload purpose used for validation/routing
+ */
+export function handleAddFiles<
+  M extends IntentMap,
+  C extends CursorMap<M>,
+  P extends string,
+  R extends UploadResultBase,
+>(rt: StoreRuntime<M, C, P, R>, files: File[], purpose: P) {
+  const existingCount = Array.from(rt.state.items.values()).filter(
+    (item) => item.purpose === purpose && item.phase !== 'canceled',
+  ).length
+
+  const { valid, rejected } = validateFileList(files, purpose, rt.opts.config, existingCount)
+
+  for (const { file, reason } of rejected) {
+    rt.emitter.emit('file.rejected', { reason, file })
+  }
+
+  const now = Date.now()
+  const toAdd: Array<{ localId: string; purpose: P; file: File; fingerprint: FileFingerprint; createdAt: number }> = []
+
+  for (const file of valid) {
+    const localId = generateId()
+    const fingerprint = (rt.opts.fingerprint ?? computeFingerprint)(file)
+
+    toAdd.push({ localId, purpose, file, fingerprint, createdAt: now })
+
+    rt.enqueueEffect(async () => {
+      // Calculate checksum for deduplication
+      let checksum: string | undefined
+      try {
+        checksum = await calculateFileChecksum(file)
+        // Update fingerprint with checksum
+        const updatedFingerprint = { ...fingerprint, checksum }
+        rt.applyInternal({ type: 'fingerprint.updated', localId, fingerprint: updatedFingerprint })
+      } catch (err) {
+        // If checksum calculation fails, continue without checksum
+        if (typeof window !== 'undefined' && process.env.NODE_ENV === 'development') {
+          console.warn('[UploadEngine] Failed to calculate checksum:', err)
+        }
+      }
+
+      // Check for existing file by checksum if available
+      if (checksum && rt.opts.api.findByChecksum) {
+        try {
+          const existingFile = await rt.opts.api.findByChecksum({ checksum, purpose })
+          if (existingFile) {
+            // File already exists, skip upload and mark as completed
+            const currentItem = rt.state.items.get(localId)
+            if (currentItem && currentItem.phase === 'validating') {
+              rt.applyInternal({ type: 'dedupe.ok', localId, result: existingFile })
+              return
+            }
+          }
+        } catch (err) {
+          // If findByChecksum fails, continue with normal upload flow
+          if (typeof window !== 'undefined' && process.env.NODE_ENV === 'development') {
+            console.warn('[UploadEngine] Failed to check for existing file:', err)
+          }
+        }
+      }
+
+      // Allow extra sync validation hook
+      const reason = rt.opts.validateFile?.(file, purpose)
+      if (reason) {
+        rt.applyInternal({ type: 'validation.failed', localId, reason })
+        return
+      }
+
+      // Still run config validation per-file (covers case where caller skipped validateFileList)
+      const cfgReason = validateFile(file, purpose, rt.opts.config)
+      if (cfgReason) {
+        rt.applyInternal({ type: 'validation.failed', localId, reason: cfgReason })
+        return
+      }
+
+      rt.applyInternal({ type: 'validation.ok', localId })
+    })
+  }
+
+  if (toAdd.length > 0) {
+    rt.applyInternal({ type: 'files.added', items: toAdd })
+  }
+}

package/src/core/engine/store/handlers/cancel.ts

@@ -0,0 +1,56 @@
+import type { CursorMap, IntentMap, UploadResultBase } from '../../../contracts'
+import { hasIntent, isMultipartIntent } from '../store.libs'
+import type { StoreRuntime } from '../store.types'
+
+/**
+ * Cancels a single upload item and aborts related inflight operations.
+ *
+ * This function is intentionally best-effort: abort calls can throw or be unsupported,
+ * and server-side multipart abort is attempted only when the adapter provides it.
+ */
+export function handleCancel<M extends IntentMap, C extends CursorMap<M>, P extends string, R extends UploadResultBase>(
+  rt: StoreRuntime<M, C, P, R>,
+  localId: string,
+) {
+  const item = rt.state.items.get(localId)
+
+  // Abort inflight intent
+  const intentCtl = rt.inflightIntents.get(localId)
+  if (intentCtl) {
+    intentCtl.abort({ reason: 'cancel' })
+    rt.inflightIntents.delete(localId)
+  }
+
+  // Abort inflight complete
+  const completeCtl = rt.inflightCompletes.get(localId)
+  if (completeCtl) {
+    completeCtl.abort({ reason: 'cancel' })
+    rt.inflightCompletes.delete(localId)
+  }
+
+  // Abort inflight upload
+  const inflight = rt.inflightUploads.get(localId)
+  if (inflight) {
+    inflight.mode = 'cancel'
+    inflight.controller.abort({ reason: 'cancel' })
+  }
+
+  // Best-effort server abort for multipart uploads
+  if (item && hasIntent(item) && item.intent.strategy === 'multipart' && rt.opts.api.multipart?.abort) {
+    const intent = item.intent
+    if (isMultipartIntent(intent)) {
+      rt.enqueueEffect(async () => {
+        try {
+          const abort = rt.opts.api.multipart?.abort
+          if (abort) {
+            await abort({ fileId: intent.fileId, uploadId: intent.uploadId })
+          }
+        } catch {
+          // ignore
+        }
+      })
+    }
+  }
+
+  // If not inflight, reducer will mark canceled.
+}

package/src/core/engine/store/handlers/clean-up.ts

@@ -0,0 +1,66 @@
+import type { CursorMap, IntentMap, UploadResultBase } from '../../../contracts'
+import type { UploadState } from '../../reducer'
+import type { StoreOptions } from '../store.types'
+
+export function cleanupOldItems<
+  M extends IntentMap,
+  C extends CursorMap<M>,
+  P extends string,
+  R extends UploadResultBase,
+>(opts: StoreOptions<M, C, P, R>, state: UploadState<M, C, P, R>): UploadState<M, C, P, R> | null {
+  const maxItems = opts.config.maxItems
+  const completedTTL = opts.config.completedItemTTL
+  const now = Date.now()
+
+  // Collect items to remove
+  const toRemove: string[] = []
+  const items = Array.from(state.items.entries())
+
+  // Remove items that exceed TTL
+  if (completedTTL !== undefined) {
+    for (const [localId, item] of items) {
+      if (
+        (item.phase === 'completed' || item.phase === 'canceled') &&
+        'completedAt' in item &&
+        typeof item.completedAt === 'number' &&
+        now - item.completedAt > completedTTL
+      ) {
+        toRemove.push(localId)
+      } else if (
+        item.phase === 'canceled' &&
+        'canceledAt' in item &&
+        typeof item.canceledAt === 'number' &&
+        now - item.canceledAt > completedTTL
+      ) {
+        toRemove.push(localId)
+      }
+    }
+  }
+
+  // If still over limit, remove oldest completed/canceled items
+  const remainingItems = items.filter(([id]) => !toRemove.includes(id))
+  if (remainingItems.length > maxItems) {
+    const completedOrCanceled = remainingItems
+      .filter(([, item]) => item.phase === 'completed' || item.phase === 'canceled')
+      .sort(([, a], [, b]) => {
+        const aTime = 'completedAt' in a ? a.completedAt : 'canceledAt' in a ? a.canceledAt : 0
+        const bTime = 'completedAt' in b ? b.completedAt : 'canceledAt' in b ? b.canceledAt : 0
+        return aTime - bTime
+      })
+
+    const excess = remainingItems.length - maxItems
+    for (let i = 0; i < excess && i < completedOrCanceled.length; i++) {
+      toRemove.push(completedOrCanceled[i][0])
+    }
+  }
+
+  // Remove items
+  if (toRemove.length === 0) return null
+
+  const nextItems = new Map(state.items)
+  for (const localId of toRemove) {
+    nextItems.delete(localId)
+  }
+
+  return { ...state, items: nextItems }
+}