@gentleduck/upload 0.2.1

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

@@ -0,0 +1,100 @@
+import { isRecord } from '../../utils/guards'
+
+// ============================================================================
+// ABORT HANDLING UTILITIES
+// ============================================================================
+
+export function abortReason(signal?: AbortSignal): unknown {
+  return signal?.reason
+}
+
+export function normalizeAbortReason(r: unknown): 'pause' | 'cancel' | 'unknown' {
+  if (!r) return 'unknown'
+
+  // Direct string match
+  if (typeof r === 'string') {
+    if (r === 'pause' || r === 'cancel') return r
+    return 'unknown'
+  }
+
+  // Object with 'reason' property (from controller.abort({ reason: 'pause' }))
+  if (isRecord(r) && 'reason' in r) {
+    const v = r.reason
+    if (v === 'pause' || v === 'cancel') return v
+  }
+
+  // Object with 'kind' property (alternative format)
+  if (isRecord(r) && 'kind' in r) {
+    const v = r.kind
+    if (v === 'pause' || v === 'cancel') return v
+  }
+
+  return 'unknown'
+}
+
+export class UploadAbortError extends Error {
+  readonly code: 'aborted' = 'aborted'
+  reason: 'pause' | 'cancel' | 'unknown'
+
+  constructor(reason: unknown) {
+    super('Upload aborted')
+    this.reason = normalizeAbortReason(reason)
+  }
+}
+
+export function makeAbortError(reason: unknown): UploadAbortError {
+  return new UploadAbortError(reason)
+}
+
+// ============================================================================
+// ERROR HANDLING HELPERS
+// ============================================================================
+
+/**
+ * Creates an error for network failures, including CORS detection.
+ *
+ * @param xhr - XMLHttpRequest instance to check status
+ * @param defaultMessage - Default error message if status is non-zero
+ *
+ * @returns {Error} Appropriate error message based on XHR status
+ */
+export function createNetworkError(xhr: XMLHttpRequest, defaultMessage: string): Error {
+  // Status 0 typically indicates CORS failure or network error
+  if (xhr.status === 0) {
+    return new Error(
+      'CORS error: The upload server does not allow requests from this origin. Please check CORS configuration.',
+    )
+  }
+  return new Error(`${defaultMessage} (status: ${xhr.status})`)
+}
+
+// ============================================================================
+// RESPONSE PARSING
+// ============================================================================
+
+/**
+ * Parses XHR response headers into a key-value object.
+ * Headers are normalized to lowercase keys.
+ *
+ * @param xhr - XMLHttpRequest instance
+ *
+ * @returns {Record<string, string>} Parsed headers object
+ */
+export function parseHeaders(xhr: XMLHttpRequest): Record<string, string> {
+  const headers: Record<string, string> = {}
+  const headerStr = xhr.getAllResponseHeaders()
+
+  headerStr
+    .split('\r\n')
+    .map((l) => l.trim())
+    .filter(Boolean)
+    .forEach((line) => {
+      const idx = line.indexOf(':')
+      if (idx <= 0) return
+      const key = line.slice(0, idx).trim().toLowerCase()
+      const value = line.slice(idx + 1).trim()
+      if (key) headers[key] = value
+    })
+
+  return headers
+}

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

@@ -0,0 +1,166 @@
+import { abortReason, createNetworkError, makeAbortError, parseHeaders } from './transport.libs'
+import type { UploadTransport } from './transport.types'
+
+type XhrCommonArgs = {
+  url: string
+  signal?: AbortSignal
+  headers?: Record<string, string>
+  onProgress?: (loaded: number, total: number) => void
+}
+
+function isAbsoluteHttpUrl(url: string) {
+  return /^https?:\/\//i.test(url)
+}
+
+function readEtag(xhr: XMLHttpRequest) {
+  // Needs CORS expose: Access-Control-Expose-Headers: ETag
+  const raw = xhr.getResponseHeader('ETag') ?? xhr.getResponseHeader('etag')
+  if (!raw) return undefined
+  return raw.replace(/"/g, '')
+}
+
+function xhrRequest(args: {
+  method: 'POST' | 'PUT' | 'PATCH'
+  url: string
+  body: Document | BodyInit | null
+  signal?: AbortSignal
+  headers?: Record<string, string>
+  onProgress?: (loaded: number, total: number) => void
+}) {
+  return new Promise<{ headers: Record<string, string>; etag?: string }>((resolve, reject) => {
+    if (!args.url || typeof args.url !== 'string') {
+      reject(new Error(`UploadTransport: missing url`))
+      return
+    }
+    if (!isAbsoluteHttpUrl(args.url)) {
+      reject(new Error(`UploadTransport: expected absolute URL, got: ${String(args.url)}`))
+      return
+    }
+
+    const xhr = new XMLHttpRequest()
+    let settled = false
+
+    const settle = (fn: () => void) => {
+      if (settled) return
+      settled = true
+      cleanup()
+      fn()
+    }
+
+    const onAbort = () => {
+      try {
+        xhr.abort()
+      } finally {
+        settle(() => reject(makeAbortError(abortReason(args.signal))))
+      }
+    }
+
+    const cleanup = () => {
+      if (args.signal) args.signal.removeEventListener('abort', onAbort)
+
+      xhr.upload.onprogress = null
+      xhr.onload = null
+      xhr.onerror = null
+      xhr.onabort = null
+    }
+
+    if (args.signal?.aborted) {
+      settle(() => reject(makeAbortError(abortReason(args.signal))))
+      return
+    }
+
+    if (args.signal) args.signal.addEventListener('abort', onAbort, { once: true })
+
+    if (args.onProgress) {
+      xhr.upload.onprogress = (e) => {
+        if (e.lengthComputable) args.onProgress?.(e.loaded, e.total)
+      }
+    }
+
+    xhr.onload = () => {
+      const status = xhr.status
+      // S3 multipart UploadPart returns 200, tus PATCH returns 204 typically.
+      if (status >= 200 && status < 300) {
+        settle(() =>
+          resolve({
+            headers: parseHeaders(xhr),
+            etag: readEtag(xhr),
+          }),
+        )
+      } else {
+        settle(() => reject(new Error(`Upload failed with status ${status}`)))
+      }
+    }
+
+    xhr.onerror = () => settle(() => reject(createNetworkError(xhr, 'Network error during upload')))
+
+    xhr.onabort = () =>
+      settle(() => reject(makeAbortError(args.signal?.aborted ? abortReason(args.signal) : 'unknown')))
+
+    xhr.open(args.method, args.url)
+
+    if (args.headers) {
+      for (const [k, v] of Object.entries(args.headers)) {
+        xhr.setRequestHeader(k, v)
+      }
+    }
+
+    xhr.send(args.body)
+  })
+}
+
+/**
+ * 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.
+ */
+export function createXHRTransport(): UploadTransport & {
+  // Optional: for tus strategies (PATCH)
+  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)
+      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')
+
+      const out = await xhrRequest({
+        method: 'POST',
+        url: args.url,
+        body: form,
+        signal: args.signal,
+        onProgress: args.onProgress,
+      })
+
+      return { headers: out.headers }
+    },
+
+    async put(args) {
+      const out = await xhrRequest({
+        method: 'PUT',
+        url: args.url,
+        body: args.body,
+        signal: args.signal,
+        headers: args.headers,
+        onProgress: args.onProgress,
+      })
+
+      // multipart needs ETag from each part
+      return { headers: out.headers, etag: out.etag }
+    },
+
+    // Optional for tus strategy (PATCH)
+    async patch(args) {
+      const out = await xhrRequest({
+        method: 'PATCH',
+        url: args.url,
+        body: args.body,
+        signal: args.signal,
+        headers: args.headers,
+        onProgress: args.onProgress,
+      })
+      return { headers: out.headers }
+    },
+  }
+}

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

@@ -0,0 +1,44 @@
+/**
+ * Abstraction layer for network operations.
+ * Allows switching between XHR (browser) or other implementations (testing/Node).
+ *
+ * Designed to support:
+ * - Deterministic progress tracking (requires XHR in browsers)
+ * - Cancellation via AbortSignal
+ * - Header parsing (ETag extraction)
+ */
+export interface UploadTransport {
+  /**
+   * Performs an HTTP PUT request (typically for S3 signed URLs).
+   */
+  put(args: {
+    url: string
+    body: Blob
+    headers?: Record<string, string>
+    signal: AbortSignal
+    onProgress?: (u: number, t: number) => void
+  }): Promise<{ etag?: string; headers?: Record<string, string> }>
+
+  /**
+   * Performs an HTTP POST multipart request.
+   */
+  postForm(args: {
+    url: string
+    fields: Record<string, string>
+    file: File | Blob
+    filename?: string
+    signal: AbortSignal
+    onProgress?: (uploadedBytes: number, totalBytes: number) => void
+  }): Promise<{ etag?: string; headers?: Record<string, string> }>
+
+  /**
+   * Performs an HTTP request.
+   */
+  patch(args: {
+    url: string
+    body: Blob | ArrayBuffer
+    headers?: Record<string, string>
+    signal: AbortSignal
+    onProgress?: (u: number, t: number) => void
+  }): Promise<{ headers?: Record<string, string> }>
+}

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

@@ -0,0 +1,17 @@
+/**
+ * Public commands accepted by the upload store.
+ *
+ * Reducer/effects should treat commands as "user intent".
+ */
+export type UploadCommand<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 }

package/src/core/engine/event-map.types.ts

@@ -0,0 +1,45 @@
+import type {
+  AnyCursor,
+  CursorMap,
+  FileFingerprint,
+  IntentMap,
+  RejectReason,
+  UploadError,
+  UploadResultBase,
+} from '../contracts'
+import type { UploadCompletionKind } from './outcome.types'
+
+/**
+ * Public event map emitted to consumers.
+ *
+ * Consumers subscribe via {@link TypedEmitter.on}.
+ */
+export type UploadEventMap<
+  M extends IntentMap,
+  C extends CursorMap<M>,
+  P extends string,
+  R extends UploadResultBase = UploadResultBase,
+> = {
+  'file.added': { localId: string; purpose: P; file: File; fingerprint: FileFingerprint }
+  'file.rejected': { file: File; reason: RejectReason }
+
+  'validation.ok': { localId: string }
+  'validation.failed': { localId: string; reason: RejectReason }
+
+  'intent.creating': { localId: string }
+  'intent.created': { localId: string; intent: M[keyof M] }
+  'intent.failed': { localId: string; error: UploadError; 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: AnyCursor<C> }
+  'upload.paused': { localId: string; cursor: AnyCursor<C> }
+  'upload.canceled': { localId: string }
+
+  'upload.completing': { localId: string }
+  'upload.completed': { localId: string; result: R; completedBy: UploadCompletionKind }
+
+  'upload.error': { localId: string; error: UploadError; retryable: boolean }
+}

package/src/core/engine/index.ts

@@ -0,0 +1,8 @@
+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'

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

@@ -0,0 +1,222 @@
+import type {
+  AnyCursor,
+  AnyIntent,
+  CursorMap,
+  FileFingerprint,
+  IntentMap,
+  RejectReason,
+  UploadError,
+  UploadResultBase,
+} from '../contracts'
+import type { UploadCompletionKind } from './outcome.types'
+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
+ */
+export type InternalEvent<
+  M extends IntentMap,
+  C extends CursorMap<M>,
+  P extends string,
+  R extends UploadResultBase = UploadResultBase,
+> =
+  | {
+      type: 'files.added'
+      items: Array<{ localId: string; purpose: P; file: File; fingerprint: FileFingerprint; createdAt: number }>
+    }
+  | { type: 'fingerprint.updated'; localId: string; fingerprint: FileFingerprint }
+  | { type: 'validation.ok'; localId: string }
+  | { type: 'validation.failed'; localId: string; reason: RejectReason }
+  | { type: 'intent.ok'; localId: string; intent: AnyIntent<M> }
+  | { type: 'intent.failed'; localId: string; error: UploadError; retryable: boolean }
+  | { type: 'upload.begin'; localId: string; startedAt: number }
+  | { type: 'upload.progress'; localId: string; uploadedBytes: number; totalBytes: number }
+  | { type: 'cursor.updated'; localId: string; cursor: AnyCursor<C> }
+  | { type: 'upload.ok'; localId: string }
+  | { type: 'upload.failed'; localId: string; error: UploadError; retryable: boolean }
+  | { type: 'dedupe.ok'; localId: string; result: R }
+  | { type: 'complete.ok'; localId: string; result: R }
+  | { type: 'complete.failed'; localId: string; error: UploadError; retryable: boolean }
+  /** Internal completion for pause requests. */
+  | { type: 'paused'; localId: string; cursor: AnyCursor<C>; pausedAt: number }
+  /** 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.
+ */
+export type UploadPhase =
+  | 'validating'
+  | 'creating_intent'
+  | 'ready'
+  | 'queued'
+  | 'uploading'
+  | 'paused'
+  | 'completing'
+  | 'completed'
+  | '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
+ */
+export type UploadItem<
+  M extends IntentMap,
+  C extends CursorMap<M>,
+  P extends string,
+  R extends UploadResultBase = UploadResultBase,
+> =
+  | {
+      /** Validating file against rules. */
+      phase: 'validating'
+      localId: string
+      purpose: P
+      fingerprint: FileFingerprint
+      file: File
+      createdAt: number
+    }
+  | {
+      /** Requesting upload intent from backend. */
+      phase: 'creating_intent'
+      localId: string
+      purpose: P
+      fingerprint: FileFingerprint
+      file: File
+      /** Current attempt number for this phase. */
+      attempt: number
+      createdAt: number
+    }
+  | {
+      /** Intent received, ready to start upload. */
+      phase: 'ready'
+      localId: string
+      purpose: P
+      fingerprint: FileFingerprint
+      file: File
+      intent: AnyIntent<M>
+      createdAt: number
+      cursor?: AnyCursor<C>
+      progress?: UploadProgress
+      attempt?: number
+    }
+  | {
+      /** Queued for upload (waiting for slot). */
+      phase: 'queued'
+      localId: string
+      purpose: P
+      fingerprint: FileFingerprint
+      file: File
+      intent: AnyIntent<M>
+      /** Timestamp when this item requested a concurrency slot. */
+      requestedAt: number
+      createdAt: number
+      cursor?: AnyCursor<C>
+      progress?: UploadProgress
+      attempt?: number
+    }
+  | {
+      /** Actively uploading bytes. */
+      phase: 'uploading'
+      localId: string
+      purpose: P
+      fingerprint: FileFingerprint
+      file: File
+      intent: AnyIntent<M>
+      startedAt: number
+      progress: UploadProgress
+      createdAt: number
+      cursor?: AnyCursor<C>
+      attempt?: number
+    }
+  | {
+      /** Upload paused (resumable). */
+      phase: 'paused'
+      localId: string
+      purpose: P
+      fingerprint: FileFingerprint
+      intent: AnyIntent<M>
+      cursor: AnyCursor<C>
+      progress: UploadProgress
+      pausedAt: number
+      createdAt: number
+      /**
+       * File is optional because a paused item can be restored from persistence without a File.
+       * Use `rebind` to attach the File again before resuming (when required).
+       */
+      file?: File
+      attempt?: number
+    }
+  | {
+      /** Bytes sent, finalizing with backend. */
+      phase: 'completing'
+      localId: string
+      purpose: P
+      fingerprint: FileFingerprint
+      file: File
+      intent: AnyIntent<M>
+      progress: UploadProgress
+      completingAt: number
+      createdAt: number
+      attempt?: number
+    }
+  | {
+      /** Upload completed successfully. */
+      phase: 'completed'
+      localId: string
+      file: File
+      purpose: P
+      fingerprint: FileFingerprint
+      intent?: AnyIntent<M>
+      completedBy: UploadCompletionKind
+      result: R
+      completedAt: number
+      createdAt: number
+      attempt?: number
+    }
+  | {
+      /** Upload failed (retryable or final). */
+      phase: 'error'
+      localId: string
+      purpose: P
+      fingerprint: FileFingerprint
+      error: UploadError
+      retryable: boolean
+      attempt: number
+      failedAt: number
+      createdAt: number
+      file?: File
+      intent?: AnyIntent<M>
+      cursor?: AnyCursor<C>
+      progress?: UploadProgress
+    }
+  | {
+      /** Upload canceled by user/system. */
+      phase: 'canceled'
+      localId: string
+      purpose: P
+      fingerprint: FileFingerprint
+      canceledAt: number
+      createdAt: number
+      file?: File
+      intent?: AnyIntent<M>
+      cursor?: AnyCursor<C>
+      progress?: UploadProgress
+      attempt?: number
+    }

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

@@ -0,0 +1,9 @@
+import type { UploadError, UploadResultBase } from '../contracts'
+
+export type UploadCompletionKind = 'upload' | 'dedupe'
+
+export type UploadOutcome<R extends UploadResultBase> =
+  | { localId: string; status: 'completed'; completedBy: UploadCompletionKind; result: R }
+  | { localId: string; status: 'error'; error: UploadError }
+  | { localId: string; status: 'canceled' }
+  | { localId: string; status: 'missing' }

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

@@ -0,0 +1,15 @@
+/**
+ * Upload progress snapshot.
+ *
+ * Invariants:
+ * - `totalBytes` should be `file.size` when known.
+ * - `pct` should be clamped to 0..100.
+ */
+export type UploadProgress = {
+  /** Bytes uploaded so far. */
+  uploadedBytes: number
+  /** Total bytes to upload. */
+  totalBytes: number
+  /** Percent complete (0..100). */
+  pct: number
+}