@gentleduck/upload 0.2.5 → 0.2.6

package/src/core/contracts/transport/transport.ts

@@ -110,17 +110,16 @@ function xhrRequest(args: {
 }
 
 /**
- * Creates a browser-native XHR transport.
- * We use XMLHttpRequest instead of fetch because fetch does not yet support
- * upload progress events in a standard cross-browser way.
+ * Browser-native XHR transport. Uses `XMLHttpRequest` over `fetch` because
+ * `fetch` lacks cross-browser upload-progress events.
  */
 export function createXHRTransport(): UploadTransport & {
-  // Optional: for tus strategies (PATCH)
+  /** Optional PATCH for tus-style strategies. */
   patch?: (args: XhrCommonArgs & { body: Blob | ArrayBuffer }) => Promise<{ headers: Record<string, string> }>
 } {
   return {
     async postForm(args) {
-      // Note: presigned POST is usually absolute already (MinIO/S3 URL)
+      // Presigned POST URLs are absolute (MinIO/S3).
       const form = new FormData()
       for (const [k, v] of Object.entries(args.fields)) form.append(k, v)
       form.append('file', args.file, args.filename ?? 'file')
@@ -146,11 +145,10 @@ export function createXHRTransport(): UploadTransport & {
         onProgress: args.onProgress,
       })
 
-      // multipart needs ETag from each part
+      // S3 multipart needs the ETag from each part response.
       return { headers: out.headers, etag: out.etag }
     },
 
-    // Optional for tus strategy (PATCH)
     async patch(args) {
       const out = await xhrRequest({
         method: 'PATCH',

package/src/core/engine/engine.types.ts

@@ -0,0 +1,364 @@
+import type { Contracts } from '../contracts'
+
+/**
+ * Engine-level type surface.
+ *
+ * @author wildduck2 <https://github.com/wildduck2>
+ */
+export namespace Engine {
+  // -------------------- Progress --------------------
+
+  /**
+   * Upload progress snapshot with `pct` clamped to 0..100.
+   *
+   * @author wildduck2 <https://github.com/wildduck2>
+   */
+  export interface IUploadProgress {
+    /** Bytes uploaded so far. */
+    uploadedBytes: number
+    /** Total bytes to upload. */
+    totalBytes: number
+    /** Percent complete (0..100). */
+    pct: number
+  }
+
+  // -------------------- Outcome --------------------
+
+  /**
+   * How a `completed` item finished.
+   *
+   * @author wildduck2 <https://github.com/wildduck2>
+   */
+  export type CompletionKind = 'upload' | 'dedupe'
+
+  /**
+   * Terminal outcome returned by `Store.IUploadStore.waitFor`.
+   *
+   * @template R Result type carried on successful completion.
+   * @author wildduck2 <https://github.com/wildduck2>
+   */
+  export type Outcome<R extends Contracts.IResultBase> =
+    | { localId: string; status: 'completed'; completedBy: CompletionKind; result: R }
+    | { localId: string; status: 'error'; error: Contracts.Error }
+    | { localId: string; status: 'canceled' }
+    | {
+        localId: string
+        status: 'missing'
+        /**
+         * Why the id is missing. Required so consumers exhaustively
+         * handle every cause via switch.
+         * - `'removed'`: explicit `dispatch({ type: 'remove' })`.
+         * - `'evicted'`: cleanup pass (`maxItems` / `completedItemTTL`).
+         * - `'never-existed'`: the id was never registered in this store.
+         * - `'destroyed'`: `store.destroy()` ran while the wait was pending.
+         */
+        reason: 'removed' | 'evicted' | 'never-existed' | 'destroyed'
+      }
+
+  // -------------------- Commands --------------------
+
+  /**
+   * Public commands accepted by `store.dispatch`.
+   *
+   * @template P Purpose discriminator string.
+   * @author wildduck2 <https://github.com/wildduck2>
+   */
+  export type Command<P extends string> =
+    | { type: 'addFiles'; files: File[]; purpose: P }
+    | { type: 'start'; localId: string }
+    | { type: 'startAll'; purpose?: P }
+    | { type: 'pause'; localId: string }
+    | { type: 'pauseAll'; purpose?: P }
+    | { type: 'resume'; localId: string }
+    | { type: 'cancel'; localId: string }
+    | { type: 'cancelAll'; purpose?: P }
+    | { type: 'retry'; localId: string }
+    | { type: 'rebind'; localId: string; file: File }
+    | { type: 'remove'; localId: string }
+
+  // -------------------- Phases / Items --------------------
+
+  /**
+   * Every upload phase; the `phase` discriminator of {@link Engine.Item}.
+   *
+   * @author wildduck2 <https://github.com/wildduck2>
+   */
+  export type Phase =
+    | 'validating'
+    | 'creating_intent'
+    | 'ready'
+    | 'queued'
+    | 'uploading'
+    | 'paused'
+    | 'completing'
+    | 'completed'
+    | 'error'
+    | 'canceled'
+
+  /**
+   * Enum-style const map of every {@link Phase} value.
+   *
+   * Reading `Phases.completing` matches the string literal at compile time
+   * AND gives consumers a single import point instead of N magic-string
+   * checks. Use whichever style fits the call site.
+   *
+   * @author wildduck2 <https://github.com/wildduck2>
+   */
+  export const Phases = {
+    validating: 'validating',
+    creating_intent: 'creating_intent',
+    ready: 'ready',
+    queued: 'queued',
+    uploading: 'uploading',
+    paused: 'paused',
+    completing: 'completing',
+    completed: 'completed',
+    error: 'error',
+    canceled: 'canceled',
+  } as const satisfies Record<Phase, Phase>
+
+  /**
+   * Discriminated union on `phase` describing a single upload's state.
+   *
+   * @template M Intent map keyed by strategy id.
+   * @template C Cursor map keyed by strategy id.
+   * @template P Purpose discriminator string.
+   * @template R Backend result payload.
+   * @author wildduck2 <https://github.com/wildduck2>
+   */
+  export type Item<
+    M extends Contracts.IntentMap,
+    C extends Contracts.CursorMap<M>,
+    P extends string,
+    R extends Contracts.IResultBase = Contracts.IResultBase,
+  > =
+    | {
+        phase: 'validating'
+        localId: string
+        purpose: P
+        fingerprint: Contracts.IFileFingerprint
+        file: File
+        createdAt: number
+      }
+    | {
+        phase: 'creating_intent'
+        localId: string
+        purpose: P
+        fingerprint: Contracts.IFileFingerprint
+        file: File
+        attempt: number
+        createdAt: number
+      }
+    | {
+        phase: 'ready'
+        localId: string
+        purpose: P
+        fingerprint: Contracts.IFileFingerprint
+        file: File
+        intent: Contracts.AnyIntent<M>
+        createdAt: number
+        cursor?: Contracts.AnyCursor<C>
+        progress?: IUploadProgress
+        attempt?: number
+      }
+    | {
+        phase: 'queued'
+        localId: string
+        purpose: P
+        fingerprint: Contracts.IFileFingerprint
+        file: File
+        intent: Contracts.AnyIntent<M>
+        requestedAt: number
+        createdAt: number
+        cursor?: Contracts.AnyCursor<C>
+        progress?: IUploadProgress
+        attempt?: number
+      }
+    | {
+        phase: 'uploading'
+        localId: string
+        purpose: P
+        fingerprint: Contracts.IFileFingerprint
+        file: File
+        intent: Contracts.AnyIntent<M>
+        startedAt: number
+        progress: IUploadProgress
+        createdAt: number
+        cursor?: Contracts.AnyCursor<C>
+        attempt?: number
+      }
+    | {
+        phase: 'paused'
+        localId: string
+        purpose: P
+        fingerprint: Contracts.IFileFingerprint
+        intent: Contracts.AnyIntent<M>
+        cursor: Contracts.AnyCursor<C>
+        progress: IUploadProgress
+        pausedAt: number
+        createdAt: number
+        file?: File
+        attempt?: number
+      }
+    | {
+        phase: 'completing'
+        localId: string
+        purpose: P
+        fingerprint: Contracts.IFileFingerprint
+        file: File
+        intent: Contracts.AnyIntent<M>
+        progress: IUploadProgress
+        completingAt: number
+        createdAt: number
+        attempt?: number
+      }
+    | {
+        phase: 'completed'
+        localId: string
+        file?: File
+        purpose: P
+        fingerprint: Contracts.IFileFingerprint
+        intent?: Contracts.AnyIntent<M>
+        completedBy: CompletionKind
+        result: R
+        completedAt: number
+        createdAt: number
+        attempt?: number
+      }
+    | {
+        phase: 'error'
+        localId: string
+        purpose: P
+        fingerprint: Contracts.IFileFingerprint
+        error: Contracts.Error
+        retryable: boolean
+        attempt: number
+        failedAt: number
+        createdAt: number
+        file?: File
+        intent?: Contracts.AnyIntent<M>
+        cursor?: Contracts.AnyCursor<C>
+        progress?: IUploadProgress
+      }
+    | {
+        phase: 'canceled'
+        localId: string
+        purpose: P
+        fingerprint: Contracts.IFileFingerprint
+        canceledAt: number
+        createdAt: number
+        file?: File
+        intent?: Contracts.AnyIntent<M>
+        cursor?: Contracts.AnyCursor<C>
+        progress?: IUploadProgress
+        attempt?: number
+      }
+
+  // -------------------- Internal events --------------------
+
+  /**
+   * Events emitted by effects and consumed by the reducer. Distinct from the
+   * public event surface -- these drive state transitions.
+   *
+   * @template M Intent map keyed by strategy id.
+   * @template C Cursor map keyed by strategy id.
+   * @template P Purpose discriminator string.
+   * @template R Backend result payload.
+   * @author wildduck2 <https://github.com/wildduck2>
+   */
+  export type InternalEvent<
+    M extends Contracts.IntentMap,
+    C extends Contracts.CursorMap<M>,
+    P extends string,
+    R extends Contracts.IResultBase = Contracts.IResultBase,
+  > =
+    | {
+        type: 'files.added'
+        items: Array<{
+          localId: string
+          purpose: P
+          file: File
+          fingerprint: Contracts.IFileFingerprint
+          createdAt: number
+        }>
+      }
+    | { type: 'fingerprint.updated'; localId: string; fingerprint: Contracts.IFileFingerprint }
+    | { type: 'validation.ok'; localId: string }
+    | { type: 'validation.failed'; localId: string; reason: Contracts.RejectReason }
+    | { type: 'intent.ok'; localId: string; intent: Contracts.AnyIntent<M> }
+    | { type: 'intent.failed'; localId: string; error: Contracts.Error; retryable: boolean }
+    | { type: 'upload.begin'; localId: string; startedAt: number }
+    | { type: 'upload.progress'; localId: string; uploadedBytes: number; totalBytes: number }
+    | { type: 'cursor.updated'; localId: string; cursor: Contracts.AnyCursor<C> }
+    | { type: 'upload.ok'; localId: string }
+    | { type: 'upload.failed'; localId: string; error: Contracts.Error; retryable: boolean }
+    | { type: 'dedupe.ok'; localId: string; result: R }
+    | { type: 'complete.ok'; localId: string; result: R }
+    | { type: 'complete.failed'; localId: string; error: Contracts.Error; retryable: boolean }
+    | { type: 'paused'; localId: string; cursor: Contracts.AnyCursor<C>; pausedAt: number }
+    | { type: 'canceled'; localId: string; canceledAt: number }
+
+  // -------------------- Public event map --------------------
+
+  /**
+   * Public event map emitted to consumers via `store.on(type, cb)`.
+   *
+   * @template M Intent map keyed by strategy id.
+   * @template C Cursor map keyed by strategy id.
+   * @template P Purpose discriminator string.
+   * @template R Backend result payload.
+   * @author wildduck2 <https://github.com/wildduck2>
+   */
+  export type EventMap<
+    M extends Contracts.IntentMap,
+    C extends Contracts.CursorMap<M>,
+    P extends string,
+    R extends Contracts.IResultBase = Contracts.IResultBase,
+  > = {
+    'file.added': { localId: string; purpose: P; file: File; fingerprint: Contracts.IFileFingerprint }
+    'file.rejected': { file: File; reason: Contracts.RejectReason }
+
+    'validation.ok': { localId: string }
+    'validation.failed': { localId: string; reason: Contracts.RejectReason }
+
+    'intent.creating': { localId: string }
+    'intent.created': { localId: string; intent: M[keyof M] }
+    'intent.failed': { localId: string; error: Contracts.Error; retryable: boolean }
+
+    'upload.queued': { localId: string }
+    'upload.resumed': { localId: string }
+    'upload.started': { localId: string }
+    'upload.progress': { localId: string; pct: number; uploadedBytes: number; totalBytes: number }
+    'upload.cursor': { localId: string; cursor: Contracts.AnyCursor<C> }
+    'upload.paused': { localId: string; cursor: Contracts.AnyCursor<C> }
+    'upload.canceled': { localId: string }
+
+    'upload.completing': { localId: string }
+    'upload.completed': { localId: string; result: R; completedBy: CompletionKind }
+
+    'upload.error': { localId: string; error: Contracts.Error; retryable: boolean }
+
+    /**
+     * Emitted whenever an item leaves state. `reason: 'user'` for an
+     * explicit `dispatch({ type: 'remove' })`; `reason: 'cleanup'` for
+     * an automatic eviction by `completedItemTTL` / `maxItems`. Lets
+     * consumers (waitFor, UI listeners, telemetry) react without polling
+     * the snapshot.
+     */
+    'upload.removed': { localId: string; reason: 'user' | 'cleanup' }
+
+    'rebind.ok': { localId: string }
+    'rebind.failed': { localId: string; reason: RebindReason }
+  }
+
+  /**
+   * Why a `rebind` command did not bind a file.
+   *
+   * @author wildduck2 <https://github.com/wildduck2>
+   */
+  export type RebindReason =
+    | { code: 'no_item' }
+    | { code: 'wrong_phase'; phase: string }
+    | { code: 'already_bound' }
+    | { code: 'fingerprint_mismatch'; expected: Contracts.IFileFingerprint; got: Contracts.IFileFingerprint }
+}

package/src/core/engine/internal-events.types.ts

@@ -13,11 +13,7 @@ import type { UploadProgress } from './progress.types'
 
 /**
  * Internal events emitted by effects and consumed by the reducer.
- *
- * These are not the same as public events. They are designed for correctness and state transitions.
- *
- * @typeParam M - Intent map
- * @typeParam C - Cursor map
+ * Distinct from the public event surface — these drive state transitions.
  */
 export type InternalEvent<
   M extends IntentMap,
@@ -47,15 +43,7 @@ export type InternalEvent<
   /** Internal completion for cancel requests. */
   | { type: 'canceled'; localId: string; canceledAt: number }
 
-// ============================================================================
-// UPLOAD ITEM (STATE MACHINE)
-// ============================================================================
-
-/**
- * All possible upload phases.
- *
- * Useful for constraints and UI filtering.
- */
+/** Every upload phase; the `phase` discriminator of {@link UploadItem}. */
 export type UploadPhase =
   | 'validating'
   | 'creating_intent'
@@ -68,15 +56,7 @@ export type UploadPhase =
   | 'error'
   | 'canceled'
 
-/**
- * State of a single upload item.
- *
- * This is a discriminated union on `phase`.
- *
- * @typeParam M - Intent map
- * @typeParam C - Cursor map
- * @typeParam P - Purpose union
- */
+/** Discriminated union on `phase` describing a single upload's state. */
 export type UploadItem<
   M extends IntentMap,
   C extends CursorMap<M>,

package/src/core/engine/reducer.ts

@@ -30,12 +30,11 @@ export function createReducer<
 
     const now = Date.now()
 
-    // Type guard: Commands don't have dots in their type, internal events do (e.g., 'intent.ok')
+    // 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> => {
       return 'type' in e && typeof e.type === 'string' && !e.type.includes('.')
     }
 
-    // Command handling
     if (isCommand(event)) {
       switch (event.type) {
         case 'addFiles': {
@@ -75,15 +74,14 @@ export function createReducer<
           const item = items.get(event.localId)
           if (!item) break
 
-          // If it's queued but not started, revert back to ready.
+          // Queued-but-not-started: revert to ready. Uploading: store aborts and
+          // emits 'paused' internally to move the item.
           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
         }
 
@@ -103,7 +101,7 @@ export function createReducer<
           if (!item.file) break
 
           if (item.intent) {
-            // If we have progress and intent, we were in completing phase - retry completing
+            // Progress at 100% with intent means we failed in 'completing' — retry that phase.
             if (item.progress && item.progress.pct === 100) {
               set(event.localId, {
                 ...item,
@@ -114,7 +112,6 @@ export function createReducer<
                 completingAt: now,
               })
             } else {
-              // Otherwise, retry from ready phase
               set(event.localId, {
                 ...item,
                 file: item.file,
@@ -123,7 +120,7 @@ export function createReducer<
               })
             }
           } else {
-            // For intent creation failures, increment attempt on retry
+            // Intent-creation failure path; bump attempt counter.
             set(event.localId, {
               ...item,
               phase: 'creating_intent',
@@ -163,7 +160,6 @@ export function createReducer<
       return { items }
     }
 
-    // Internal event handling
     switch (event.type) {
       case 'files.added': {
         const ev = event
@@ -390,7 +386,6 @@ export function createReducer<
         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, {
@@ -409,7 +404,6 @@ export function createReducer<
   }
 }
 
-// Helpers
 function toCanceled<M extends IntentMap, C extends CursorMap<M>, P extends string, R extends UploadResultBase>(
   item: UploadItem<M, C, P, R>,
   canceledAt: number,

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

@@ -5,19 +5,8 @@ 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
+ * Sync: validate + insert. Async (queued): checksum, dedupe lookup,
+ * and the final validation transition.
  */
 export function handleAddFiles<
   M extends IntentMap,
@@ -45,26 +34,23 @@ export function handleAddFiles<
     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
+        // Checksum failure is non-fatal — continue without dedupe.
         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
+      // 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) {
-            // 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 })
@@ -72,21 +58,20 @@ export function handleAddFiles<
             }
           }
         } catch (err) {
-          // If findByChecksum fails, continue with normal upload flow
+          // 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)
           }
         }
       }
 
-      // 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)
+      // Re-run config validation per-file in case the caller skipped validateFileList.
       const cfgReason = validateFile(file, purpose, rt.opts.config)
       if (cfgReason) {
         rt.applyInternal({ type: 'validation.failed', localId, reason: cfgReason })

package/src/core/engine/store/handlers/run-upload.ts

@@ -10,7 +10,7 @@ export async function runUpload<
 >(rt: StoreRuntime<M, C, P, R>, localId: string) {
   const item = rt.state.items.get(localId)
 
-  // If the state moved on (or we never had a valid upload), drop any inflight entry.
+  // State moved on (or never valid) — drop any stale inflight entry.
   if (!item || item.phase !== 'uploading' || !hasIntent(item)) {
     rt.inflightUploads.delete(localId)
     return
@@ -39,7 +39,7 @@ export async function runUpload<
     rt.applyInternal({ type: 'paused', localId, cursor, pausedAt: Date.now() })
   }
 
-  // If paused/canceled before the request begins, complete it immediately.
+  // Paused/canceled before the request begins: short-circuit to the right terminal state.
   if (controller.signal.aborted) {
     rt.inflightUploads.delete(localId)
 
@@ -92,7 +92,7 @@ export async function runUpload<
     return
   }
 
-  // Throttle progress events
+  // Throttle progress events to limit re-renders and reducer churn.
   let lastEmit = 0
   const progressThrottle = rt.opts.config.progressThrottleMs
 
@@ -138,16 +138,16 @@ export async function runUpload<
       return
     }
     if (controller.signal.aborted && inflight?.mode === 'pause') {
-      // Paused at the end; reducer expects cursor - if not present, keep last-known or synthesize.
+      // Paused after strategy returned: reducer requires a cursor — synthesize an
+      // empty one if the strategy never persisted progress.
       const cur = rt.state.items.get(localId)
       const cursor = (cur && hasCursor(cur) ? cur.cursor : undefined) || { strategy: strategyId, value: undefined }
       applyPaused(cursor)
       return
     }
 
-    // Normal completion -> completing
+    // 'completing' phase; finalizeUpload runs via scheduleWork().
     rt.applyInternal({ type: 'upload.ok', localId })
-    // finalizeUpload scheduled by scheduleWork() via completing phase
   } catch (err: unknown) {
     rt.inflightUploads.delete(localId)
 
@@ -164,7 +164,7 @@ export async function runUpload<
         return
       }
 
-      // Unknown abort -> treat as cancel
+      // Abort with no mode set: treat as cancel.
       applyCanceled()
       return
     }