@gentleduck/upload 0.2.6 → 0.3.0

package/src/core/engine/index.ts

@@ -1,8 +1,3 @@
-export * from './commands.types'
-export * from './event-map.types'
-export * from './internal-events.types'
-export * from './outcome.types'
-export * from './progress.types'
-export * from './reducer'
-export * from './store'
-export * from './validation'
+export { Engine } from './engine.types'
+export type { Store } from './store'
+export { createUploadStore } from './store'

package/src/core/engine/reducer.ts

@@ -1,37 +1,56 @@
-import type { CursorMap, IntentMap, UploadResultBase } from '../contracts'
+import type { Contracts } from '../contracts'
+import { UploadValidationError } from '../errors'
 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'
+import type { Engine } from './engine.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>>
+function stripError(err: { code: string; message: string; retryable?: boolean }): Contracts.StepError {
+  const result: Contracts.StepError = { code: err.code, message: err.message }
+  if (err.retryable !== undefined) result.retryable = err.retryable
+  return result
+}
+
+function closeStep(steps: Contracts.UploadStep[], leftAt: number): Contracts.UploadStep[] {
+  if (!steps.length) return steps
+  const last = steps[steps.length - 1]
+  if (!last || last.leftAt !== undefined) return steps
+  const closed: Contracts.UploadStep = {
+    phase: last.phase,
+    enteredAt: last.enteredAt,
+    leftAt,
+    attempt: last.attempt,
+    ...(last.error !== undefined ? { error: last.error } : {}),
+  }
+  return [...steps.slice(0, -1), closed]
+}
+
+function openStep(
+  steps: Contracts.UploadStep[],
+  phase: string,
+  attempt: number,
+  enteredAt: number,
+  error?: Contracts.StepError,
+): Contracts.UploadStep[] {
+  return [...closeStep(steps, enteredAt), { phase, enteredAt, attempt, error }]
 }
 
 export function createReducer<
-  M extends IntentMap,
-  C extends CursorMap<M>,
+  M extends Contracts.Intent.Map,
+  C extends Contracts.Cursor.Map<M>,
   P extends string,
-  R extends UploadResultBase = UploadResultBase,
+  R extends Contracts.Result.Base = Contracts.Result.Base,
 >() {
   return function reduce(
-    state: UploadState<M, C, P, R>,
-    event: UploadCommand<P> | InternalEvent<M, C, P, R>,
-  ): UploadState<M, C, P, R> {
+    state: Engine.State<M, C, P, R>,
+    event: Engine.Command<P> | Engine.Event<M, C, P, R>,
+  ): Engine.State<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 set = (localId: string, next: Engine.Item<M, C, P, R>) => items.set(localId, next)
 
     const now = Date.now()
 
     // Commands have no 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> => {
+    const isCommand = (e: Engine.Command<P> | Engine.Event<M, C, P, R>): e is Engine.Command<P> => {
       return 'type' in e && typeof e.type === 'string' && !e.type.includes('.')
     }
 
@@ -51,6 +70,7 @@ export function createReducer<
             ...item,
             phase: 'queued',
             requestedAt: now,
+            steps: openStep(item.steps, 'queued', item.attempt ?? 1, now),
           })
           break
         }
@@ -66,6 +86,7 @@ export function createReducer<
             file: item.file,
             phase: 'queued',
             requestedAt: now,
+            steps: openStep(item.steps, 'queued', item.attempt ?? 1, now),
           })
           break
         }
@@ -80,6 +101,7 @@ export function createReducer<
             set(event.localId, {
               ...item,
               phase: 'ready',
+              steps: openStep(item.steps, 'ready', item.attempt ?? 1, now),
             })
           }
           break
@@ -101,7 +123,7 @@ export function createReducer<
           if (!item.file) break
 
           if (item.intent) {
-            // Progress at 100% with intent means we failed in 'completing' — retry that phase.
+            // Progress at 100% with intent means we failed in 'completing'  retry that phase.
             if (item.progress && item.progress.pct === 100) {
               set(event.localId, {
                 ...item,
@@ -110,6 +132,7 @@ export function createReducer<
                 file: item.file,
                 phase: 'completing',
                 completingAt: now,
+                steps: openStep(item.steps, 'completing', item.attempt ?? 1, now),
               })
             } else {
               set(event.localId, {
@@ -117,15 +140,18 @@ export function createReducer<
                 file: item.file,
                 intent: item.intent,
                 phase: 'ready',
+                steps: openStep(item.steps, 'ready', item.attempt ?? 1, now),
               })
             }
           } else {
             // Intent-creation failure path; bump attempt counter.
+            const nextAttempt = (item.attempt ?? 1) + 1
             set(event.localId, {
               ...item,
               phase: 'creating_intent',
               file: item.file,
-              attempt: (item.attempt ?? 1) + 1,
+              attempt: nextAttempt,
+              steps: openStep(item.steps, 'creating_intent', nextAttempt, now),
             })
           }
           break
@@ -172,6 +198,8 @@ export function createReducer<
               file: item.file,
               fingerprint: item.fingerprint,
               createdAt: item.createdAt,
+              meta: item.meta,
+              steps: [{ phase: 'validating', enteredAt: now, attempt: 1 }],
             })
           }
         }
@@ -189,12 +217,13 @@ export function createReducer<
 
       case 'validation.ok': {
         const item = items.get(event.localId)
-        if (!item || item.phase !== 'validating') break
+        if (item?.phase !== 'validating') break
 
         set(event.localId, {
           ...item,
           phase: 'creating_intent',
           attempt: 1,
+          steps: openStep(item.steps, 'creating_intent', 1, now),
         })
         break
       }
@@ -202,15 +231,17 @@ export function createReducer<
       case 'validation.failed': {
         const ev = event
         const item = items.get(ev.localId)
-        if (!item || item.phase !== 'validating') break
+        if (item?.phase !== 'validating') break
 
+        const err = new UploadValidationError(ev.reason)
         set(ev.localId, {
           ...item,
           phase: 'error',
-          error: { code: 'validation_failed', reason: ev.reason, message: String(ev.reason) },
+          error: err,
           retryable: false,
           attempt: 1,
           failedAt: now,
+          steps: openStep(item.steps, 'error', 1, now, stripError(err)),
         })
         break
       }
@@ -218,12 +249,13 @@ export function createReducer<
       case 'intent.ok': {
         const ev = event
         const item = items.get(ev.localId)
-        if (!item || item.phase !== 'creating_intent') break
+        if (item?.phase !== 'creating_intent') break
 
         set(ev.localId, {
           ...item,
           phase: 'ready',
           intent: ev.intent,
+          steps: openStep(item.steps, 'ready', item.attempt ?? 1, now),
         })
         break
       }
@@ -231,7 +263,7 @@ export function createReducer<
       case 'intent.failed': {
         const ev = event
         const item = items.get(ev.localId)
-        if (!item || item.phase !== 'creating_intent') break
+        if (item?.phase !== 'creating_intent') break
 
         set(ev.localId, {
           ...item,
@@ -239,6 +271,7 @@ export function createReducer<
           error: ev.error,
           retryable: ev.retryable,
           failedAt: now,
+          steps: openStep(item.steps, 'error', item.attempt ?? 1, now, stripError(ev.error)),
         })
         break
       }
@@ -246,12 +279,12 @@ export function createReducer<
       case 'upload.begin': {
         const ev = event
         const item = items.get(ev.localId)
-        if (!item || item.phase !== 'queued') break
+        if (item?.phase !== 'queued') break
 
         const total = item.file.size
-        const carried: UploadProgress | undefined = item.progress
+        const carried: Engine.Progress | undefined = item.progress
 
-        const progress: UploadProgress = carried
+        const progress: Engine.Progress = carried
           ? { ...carried, totalBytes: total, pct: pct(carried.uploadedBytes, total) }
           : { uploadedBytes: 0, totalBytes: total, pct: 0 }
 
@@ -260,6 +293,7 @@ export function createReducer<
           phase: 'uploading',
           progress,
           startedAt: ev.startedAt,
+          steps: openStep(item.steps, 'uploading', item.attempt ?? 1, ev.startedAt),
         })
         break
       }
@@ -267,9 +301,9 @@ export function createReducer<
       case 'upload.progress': {
         const ev = event
         const item = items.get(ev.localId)
-        if (!item || item.phase !== 'uploading') break
+        if (item?.phase !== 'uploading') break
 
-        const progress: UploadProgress = {
+        const progress: Engine.Progress = {
           uploadedBytes: ev.uploadedBytes,
           totalBytes: ev.totalBytes,
           pct: pct(ev.uploadedBytes, ev.totalBytes),
@@ -297,13 +331,14 @@ export function createReducer<
       case 'upload.ok': {
         const ev = event
         const item = items.get(ev.localId)
-        if (!item || item.phase !== 'uploading') break
+        if (item?.phase !== 'uploading') break
 
         set(ev.localId, {
           ...item,
           phase: 'completing',
           progress: { uploadedBytes: item.file.size, totalBytes: item.file.size, pct: 100 },
           completingAt: now,
+          steps: openStep(item.steps, 'completing', item.attempt ?? 1, now),
         })
         break
       }
@@ -311,7 +346,7 @@ export function createReducer<
       case 'upload.failed': {
         const ev = event
         const item = items.get(ev.localId)
-        if (!item || item.phase !== 'uploading') break
+        if (item?.phase !== 'uploading') break
 
         set(ev.localId, {
           ...item,
@@ -320,6 +355,7 @@ export function createReducer<
           retryable: ev.retryable,
           attempt: 1,
           failedAt: now,
+          steps: openStep(item.steps, 'error', item.attempt ?? 1, now, stripError(ev.error)),
         })
         break
       }
@@ -327,13 +363,14 @@ export function createReducer<
       case 'paused': {
         const ev = event
         const item = items.get(ev.localId)
-        if (!item || item.phase !== 'uploading') break
+        if (item?.phase !== 'uploading') break
 
         set(ev.localId, {
           ...item,
           phase: 'paused',
           cursor: ev.cursor,
           pausedAt: ev.pausedAt,
+          steps: openStep(item.steps, 'paused', item.attempt ?? 1, ev.pausedAt),
         })
         break
       }
@@ -350,7 +387,7 @@ export function createReducer<
       case 'complete.ok': {
         const ev = event
         const item = items.get(ev.localId)
-        if (!item || item.phase !== 'completing') break
+        if (item?.phase !== 'completing') break
 
         set(ev.localId, {
           ...item,
@@ -358,6 +395,7 @@ export function createReducer<
           completedBy: 'upload',
           result: ev.result,
           completedAt: now,
+          steps: openStep(item.steps, 'completed', item.attempt ?? 1, now),
         })
         break
       }
@@ -365,18 +403,20 @@ export function createReducer<
       case 'dedupe.ok': {
         const ev = event
         const item = items.get(ev.localId)
-        if (!item || item.phase !== 'validating') break
+        if (!item || (item.phase !== 'validating' && item.phase !== 'creating_intent')) break
 
         set(ev.localId, {
           phase: 'completed',
           localId: item.localId,
-          file: item.file,
+          file: 'file' in item ? item.file : undefined,
           purpose: item.purpose,
           fingerprint: item.fingerprint,
           result: ev.result,
           completedBy: 'dedupe',
           completedAt: now,
           createdAt: item.createdAt,
+          meta: item.meta,
+          steps: openStep(item.steps, 'completed', item.attempt ?? 1, now),
         })
         break
       }
@@ -384,7 +424,7 @@ export function createReducer<
       case 'complete.failed': {
         const ev = event
         const item = items.get(ev.localId)
-        if (!item || item.phase !== 'completing') break
+        if (item?.phase !== 'completing') break
 
         const nextAttempt = (item.attempt ?? 1) + 1
 
@@ -395,6 +435,7 @@ export function createReducer<
           retryable: ev.retryable,
           attempt: nextAttempt,
           failedAt: now,
+          steps: openStep(item.steps, 'error', nextAttempt, now, stripError(ev.error)),
         })
         break
       }
@@ -404,10 +445,13 @@ export function createReducer<
   }
 }
 
-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> {
+function toCanceled<
+  M extends Contracts.Intent.Map,
+  C extends Contracts.Cursor.Map<M>,
+  P extends string,
+  R extends Contracts.Result.Base,
+>(item: Engine.Item<M, C, P, R>, canceledAt: number): Engine.Item<M, C, P, R> {
+  const attempt = ('attempt' in item ? item.attempt : undefined) ?? 1
   return {
     phase: 'canceled',
     localId: item.localId,
@@ -420,6 +464,8 @@ function toCanceled<M extends IntentMap, C extends CursorMap<M>, P extends strin
     cursor: 'cursor' in item ? item.cursor : undefined,
     progress: 'progress' in item ? item.progress : undefined,
     attempt: 'attempt' in item ? item.attempt : undefined,
+    meta: item.meta,
+    steps: openStep(item.steps, 'canceled', attempt, canceledAt),
   }
 }
 

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

@@ -1,19 +1,20 @@
-import type { CursorMap, FileFingerprint, IntentMap, UploadResultBase } from '../../../contracts'
+import type { Contracts } from '../../../contracts'
+import { isDevEnv } from '../../../utils/guards'
 import { generateId } from '../../../utils/id'
-import { validateFile, validateFileList } from '../../validation'
-import { calculateFileChecksum, computeFingerprint } from '../store.libs'
-import type { StoreRuntime } from '../store.types'
+import { validateFile, validateFileList, validateMimeSignature } from '../../validation'
+import { calculateFileChecksum, computeFingerprint, tryDedupeByChecksum } from '../store.libs'
+import type { Store } from '../store.types'
 
 /**
  * Sync: validate + insert. Async (queued): checksum, dedupe lookup,
  * and the final validation transition.
  */
 export function handleAddFiles<
-  M extends IntentMap,
-  C extends CursorMap<M>,
+  M extends Contracts.Intent.Map,
+  C extends Contracts.Cursor.Map<M>,
   P extends string,
-  R extends UploadResultBase,
->(rt: StoreRuntime<M, C, P, R>, files: File[], purpose: P) {
+  R extends Contracts.Result.Base,
+>(rt: Store.Runtime<M, C, P, R>, files: File[], purpose: P, meta: Record<string, unknown> = {}) {
   const existingCount = Array.from(rt.state.items.values()).filter(
     (item) => item.purpose === purpose && item.phase !== 'canceled',
   ).length
@@ -25,44 +26,40 @@ export function handleAddFiles<
   }
 
   const now = Date.now()
-  const toAdd: Array<{ localId: string; purpose: P; file: File; fingerprint: FileFingerprint; createdAt: number }> = []
+  const toAdd: Array<{
+    localId: string
+    purpose: P
+    file: File
+    fingerprint: Contracts.FingerprintFile
+    createdAt: number
+    meta: Record<string, unknown>
+  }> = []
 
   for (const file of valid) {
     const localId = generateId()
     const fingerprint = (rt.opts.fingerprint ?? computeFingerprint)(file)
 
-    toAdd.push({ localId, purpose, file, fingerprint, createdAt: now })
+    toAdd.push({ localId, purpose, file, fingerprint, createdAt: now, meta })
 
     rt.enqueueEffect(async () => {
       let checksum: string | undefined
       try {
-        checksum = await calculateFileChecksum(file)
+        // Hashes files of any size (small: native Web Crypto; large:
+        // incremental, off-thread when possible). Failures fall through to the
+        // catch and simply skip dedupe.
+        checksum = await calculateFileChecksum(file, rt.opts.config.checksumMaxSize)
         const updatedFingerprint = { ...fingerprint, checksum }
         rt.applyInternal({ type: 'fingerprint.updated', localId, fingerprint: updatedFingerprint })
       } catch (err) {
-        // Checksum failure is non-fatal — continue without dedupe.
-        if (typeof window !== 'undefined' && process.env.NODE_ENV === 'development') {
+        // Checksum failure is non-fatal  continue without dedupe.
+        if (isDevEnv()) {
           console.warn('[UploadEngine] Failed to calculate checksum:', err)
         }
       }
 
       // Dedupe: skip upload entirely when the backend already has the file.
-      if (checksum && rt.opts.api.findByChecksum) {
-        try {
-          const existingFile = await rt.opts.api.findByChecksum({ checksum, purpose })
-          if (existingFile) {
-            const currentItem = rt.state.items.get(localId)
-            if (currentItem && currentItem.phase === 'validating') {
-              rt.applyInternal({ type: 'dedupe.ok', localId, result: existingFile })
-              return
-            }
-          }
-        } catch (err) {
-          // Dedupe failure is non-fatal — fall through to normal upload.
-          if (typeof window !== 'undefined' && process.env.NODE_ENV === 'development') {
-            console.warn('[UploadEngine] Failed to check for existing file:', err)
-          }
-        }
+      if (await tryDedupeByChecksum(rt, localId, checksum, purpose, ['validating'])) {
+        return
       }
 
       const reason = rt.opts.validateFile?.(file, purpose)
@@ -78,6 +75,19 @@ export function handleAddFiles<
         return
       }
 
+      try {
+        const mimeReason = await validateMimeSignature(file, rt.opts.config.strictMimeMatch === true)
+        if (mimeReason) {
+          rt.applyInternal({ type: 'validation.failed', localId, reason: mimeReason })
+          return
+        }
+      } catch (err) {
+        // Sniff failure is non-fatal  fall through.
+        if (isDevEnv()) {
+          console.warn('[UploadEngine] MIME sniff failed:', err)
+        }
+      }
+
       rt.applyInternal({ type: 'validation.ok', localId })
     })
   }

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

@@ -1,6 +1,6 @@
-import type { CursorMap, IntentMap, UploadResultBase } from '../../../contracts'
-import { hasIntent, isMultipartIntent } from '../store.libs'
-import type { StoreRuntime } from '../store.types'
+import type { Contracts } from '../../../contracts'
+import { buildApiContext, hasIntent, isMultipartIntent } from '../store.libs'
+import type { Store } from '../store.types'
 
 /**
  * Cancels a single upload item and aborts related inflight operations.
@@ -8,10 +8,12 @@ import type { StoreRuntime } from '../store.types'
  * 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,
-) {
+export function handleCancel<
+  M extends Contracts.Intent.Map,
+  C extends Contracts.Cursor.Map<M>,
+  P extends string,
+  R extends Contracts.Result.Base,
+>(rt: Store.Runtime<M, C, P, R>, localId: string) {
   const item = rt.state.items.get(localId)
 
   // Abort inflight intent
@@ -43,7 +45,10 @@ export function handleCancel<M extends IntentMap, C extends CursorMap<M>, P exte
         try {
           const abort = rt.opts.api.multipart?.abort
           if (abort) {
-            await abort({ fileId: intent.fileId, uploadId: intent.uploadId })
+            await abort(
+              { fileId: intent.fileId, uploadId: intent.uploadId },
+              buildApiContext(item) as Contracts.Api.AbortContext<P, M>,
+            )
           }
         } catch {
           // ignore

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

@@ -1,13 +1,13 @@
-import type { CursorMap, IntentMap, UploadResultBase } from '../../../contracts'
-import type { UploadState } from '../../reducer'
-import type { StoreOptions } from '../store.types'
+import type { Contracts } from '../../../contracts'
+import type { Engine } from '../../engine.types'
+import type { Store } from '../store.types'
 
 export function cleanupOldItems<
-  M extends IntentMap,
-  C extends CursorMap<M>,
+  M extends Contracts.Intent.Map,
+  C extends Contracts.Cursor.Map<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 {
+  R extends Contracts.Result.Base,
+>(opts: Store.Options<M, C, P, R>, state: Engine.State<M, C, P, R>): Engine.State<M, C, P, R> | null {
   const maxItems = opts.config?.maxItems
   const completedTTL = opts.config?.completedItemTTL
   const now = Date.now()
@@ -50,7 +50,10 @@ export function cleanupOldItems<
 
     const excess = remainingItems.length - maxItems
     for (let i = 0; i < excess && i < completedOrCanceled.length; i++) {
-      toRemove.push(completedOrCanceled[i][0])
+      const entry = completedOrCanceled[i]
+      if (entry) {
+        toRemove.push(entry[0])
+      }
     }
   }