@gentleduck/upload 0.2.5 → 0.2.6

package/src/__test__/transport.test.ts

@@ -0,0 +1,182 @@
+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest'
+import { createXHRTransport } from '../core/contracts/transport'
+import { UploadAbortError } from '../core/contracts/transport/transport.libs'
+
+/**
+ * Minimal `XMLHttpRequest` mock. Captures method/url/headers/body and exposes
+ * hooks to simulate `onload` / `onerror` / `onabort` and per-progress events.
+ */
+class MockXHR {
+  static instances: MockXHR[] = []
+
+  method = ''
+  url = ''
+  body: unknown = null
+  headers: Record<string, string> = {}
+  status = 0
+  upload = { onprogress: null as ((e: ProgressEvent) => void) | null }
+  onload: ((e: Event) => void) | null = null
+  onerror: ((e: Event) => void) | null = null
+  onabort: ((e: Event) => void) | null = null
+  responseHeadersRaw = ''
+  responseHeaders: Record<string, string> = {}
+
+  constructor() {
+    MockXHR.instances.push(this)
+  }
+
+  open(method: string, url: string) {
+    this.method = method
+    this.url = url
+  }
+
+  setRequestHeader(name: string, value: string) {
+    this.headers[name.toLowerCase()] = value
+  }
+
+  send(body: unknown) {
+    this.body = body
+  }
+
+  abort() {
+    this.onabort?.(new Event('abort'))
+  }
+
+  getResponseHeader(name: string): string | null {
+    return this.responseHeaders[name.toLowerCase()] ?? null
+  }
+
+  getAllResponseHeaders(): string {
+    return this.responseHeadersRaw
+  }
+
+  // Test helpers
+  fireSuccess(status: number, headers: Record<string, string> = {}) {
+    this.status = status
+    this.responseHeaders = Object.fromEntries(Object.entries(headers).map(([k, v]) => [k.toLowerCase(), v]))
+    this.responseHeadersRaw = Object.entries(headers)
+      .map(([k, v]) => `${k}: ${v}`)
+      .join('\r\n')
+    this.onload?.(new Event('load'))
+  }
+
+  fireError(status = 0) {
+    this.status = status
+    this.onerror?.(new Event('error'))
+  }
+}
+
+const originalXHR = (globalThis as { XMLHttpRequest?: unknown }).XMLHttpRequest
+
+beforeEach(() => {
+  MockXHR.instances = []
+  ;(globalThis as unknown as { XMLHttpRequest: typeof MockXHR }).XMLHttpRequest = MockXHR
+})
+
+afterEach(() => {
+  if (originalXHR) (globalThis as { XMLHttpRequest?: unknown }).XMLHttpRequest = originalXHR
+  else delete (globalThis as { XMLHttpRequest?: unknown }).XMLHttpRequest
+})
+
+describe('createXHRTransport.put', () => {
+  test('resolves on 2xx and parses ETag', async () => {
+    const t = createXHRTransport()
+    const ctl = new AbortController()
+    const promise = t.put({
+      url: 'https://example.com/part',
+      body: new Blob(['x']),
+      signal: ctl.signal,
+      headers: { 'x-foo': 'bar' },
+    })
+
+    const xhr = MockXHR.instances[0]
+    expect(xhr.method).toBe('PUT')
+    expect(xhr.url).toBe('https://example.com/part')
+    expect(xhr.headers['x-foo']).toBe('bar')
+
+    xhr.fireSuccess(200, { ETag: '"abc"' })
+    const result = await promise
+    expect(result.etag).toBe('abc')
+  })
+
+  test('rejects with a status-tagged Error on non-2xx status', async () => {
+    const t = createXHRTransport()
+    const ctl = new AbortController()
+    const promise = t.put({ url: 'https://example.com/part', body: new Blob(['x']), signal: ctl.signal })
+
+    const xhr = MockXHR.instances[0]
+    xhr.fireSuccess(503)
+    await expect(promise).rejects.toThrow(/status 503/)
+  })
+
+  test('rejects with a CORS-tagged Error when status=0', async () => {
+    const t = createXHRTransport()
+    const ctl = new AbortController()
+    const promise = t.put({ url: 'https://example.com/part', body: new Blob(['x']), signal: ctl.signal })
+
+    const xhr = MockXHR.instances[0]
+    xhr.fireError(0)
+    await expect(promise).rejects.toThrow(/CORS/)
+  })
+
+  test('rejects with UploadAbortError when the signal aborts', async () => {
+    const t = createXHRTransport()
+    const ctl = new AbortController()
+    const promise = t.put({ url: 'https://example.com/part', body: new Blob(['x']), signal: ctl.signal })
+
+    ctl.abort('cancel')
+    await expect(promise).rejects.toBeInstanceOf(UploadAbortError)
+    await expect(promise).rejects.toMatchObject({ code: 'aborted', reason: 'cancel' })
+  })
+
+  test('rejects non-absolute URLs', async () => {
+    const t = createXHRTransport()
+    const ctl = new AbortController()
+    await expect(t.put({ url: '/relative/path', body: new Blob(['x']), signal: ctl.signal })).rejects.toThrow(
+      /absolute URL/,
+    )
+  })
+
+  test('forwards upload progress events', async () => {
+    const t = createXHRTransport()
+    const ctl = new AbortController()
+    const onProgress = vi.fn()
+    const promise = t.put({
+      url: 'https://example.com/part',
+      body: new Blob(['x']),
+      signal: ctl.signal,
+      onProgress,
+    })
+
+    const xhr = MockXHR.instances[0]
+    xhr.upload.onprogress?.({ lengthComputable: true, loaded: 5, total: 10 } as ProgressEvent)
+    expect(onProgress).toHaveBeenCalledWith(5, 10)
+
+    xhr.fireSuccess(200)
+    await promise
+  })
+})
+
+describe('createXHRTransport.postForm', () => {
+  test('builds FormData with fields + file and POSTs', async () => {
+    const t = createXHRTransport()
+    const ctl = new AbortController()
+    const file = new File(['payload'], 'a.txt')
+    const promise = t.postForm({
+      url: 'https://example.com/upload',
+      fields: { key: 'avatar/a.txt', acl: 'private' },
+      file,
+      signal: ctl.signal,
+    })
+
+    const xhr = MockXHR.instances[0]
+    expect(xhr.method).toBe('POST')
+    expect(xhr.body).toBeInstanceOf(FormData)
+    const form = xhr.body as FormData
+    expect(form.get('key')).toBe('avatar/a.txt')
+    expect(form.get('acl')).toBe('private')
+
+    xhr.fireSuccess(204)
+    await promise
+  })
+})

package/src/core/client/client.ts

@@ -0,0 +1,50 @@
+import { Defaults } from '../utils/constants'
+import type { Client } from './client.types'
+
+/**
+ * Apply defaults to a partial {@link Client.IUploadConfig}.
+ *
+ * @param input Partial config from the caller. Nested groups
+ *   (e.g. `effectQueueCompaction`) accept their own partial shape.
+ * @returns Fully populated config with each numeric field clamped to a sane
+ *   minimum.
+ * @template P Purpose string union.
+ * @author wildduck2 <https://github.com/wildduck2>
+ */
+export function resolveUploadConfig<P extends string>(input?: Client.UploadConfigInput<P>): Client.IUploadConfig<P> {
+  return {
+    maxConcurrentUploads: Math.max(1, input?.maxConcurrentUploads ?? Defaults.MAX_CONCURRENT_UPLOADS),
+    autoStart: input?.autoStart,
+    progressThrottleMs: Math.max(0, input?.progressThrottleMs ?? Defaults.PROGRESS_THROTTLE_MS),
+    validation: input?.validation ?? {},
+    maxAttempts: Math.max(1, input?.maxAttempts ?? Defaults.MAX_ATTEMPTS),
+    retryPolicy: input?.retryPolicy,
+    maxItems: input?.maxItems === null ? null : Math.max(1, input?.maxItems ?? Defaults.MAX_ITEMS),
+    completedItemTTL: input?.completedItemTTL,
+    effectConcurrency: Math.max(1, input?.effectConcurrency ?? Defaults.EFFECT_CONCURRENCY),
+    effectTimeoutMs: Math.max(0, input?.effectTimeoutMs ?? Defaults.EFFECT_TIMEOUT_MS),
+    errorContextInMessage: input?.errorContextInMessage ?? false,
+    keepRawCause: input?.keepRawCause ?? false,
+    effectQueueCompaction: {
+      minHead: Math.max(1, input?.effectQueueCompaction?.minHead ?? 64),
+      ratioDenom: Math.max(2, input?.effectQueueCompaction?.ratioDenom ?? 2),
+      maxQueueLength:
+        input?.effectQueueCompaction?.maxQueueLength === null
+          ? null
+          : Math.max(1, input?.effectQueueCompaction?.maxQueueLength ?? 10_000),
+    },
+    checksumMaxSize:
+      input?.checksumMaxSize === undefined
+        ? null
+        : input.checksumMaxSize === null
+          ? null
+          : Math.max(0, input.checksumMaxSize),
+    checksumChunkBytes:
+      input?.checksumChunkBytes === undefined
+        ? null
+        : input.checksumChunkBytes === null
+          ? null
+          : Math.max(1, input.checksumChunkBytes),
+    strictRebindType: input?.strictRebindType ?? false,
+  }
+}

package/src/core/client/client.types.ts

@@ -0,0 +1,184 @@
+import type { Contracts } from '../contracts'
+import type { Engine } from '../engine/engine.types'
+import type { Reducer } from '../engine/reducer'
+import type { Store } from '../engine/store'
+import type { PersistenceError } from '../persistence/persistence.types'
+
+/**
+ * Client-facing configuration, hooks, plugins, and retry policy types.
+ *
+ * @author wildduck2 <https://github.com/wildduck2>
+ */
+export namespace Client {
+  // -------------------- Retry --------------------
+
+  /** Output of the retry policy. `delayMs` is a backoff before re-attempt. */
+  export type RetryDecision = { retryable: false } | { retryable: true; delayMs: number }
+
+  // -------------------- Config --------------------
+
+  /** Effect-queue compaction tuning knobs. */
+  export interface IEffectQueueCompaction {
+    /** Absolute head-count floor before compaction. Default 64. */
+    minHead: number
+    /** Triggers compaction when `head * denom > length`. Default 2. */
+    ratioDenom: number
+    /**
+     * Hard upper bound on queue length. New effects past this cap are
+     * dropped + logged. Defends against a pathological dispatch storm that
+     * grows the queue faster than compaction drains. `null` disables.
+     * Default `10_000`.
+     */
+    maxQueueLength: number | null
+  }
+
+  /** Global upload engine configuration. */
+  export interface IUploadConfig<P extends string> {
+    /** Maximum concurrent in-flight uploads. Default `3`. */
+    maxConcurrentUploads: number
+    /** Auto-start `ready` items. */
+    autoStart?: readonly P[] | ((purpose: P) => boolean)
+    /** Throttle for `upload.progress` events in ms. Default `100`. */
+    progressThrottleMs: number
+    /** Per-purpose validation rules. */
+    validation: Partial<Record<P, Contracts.IValidationRules>>
+    /** Maximum attempts per phase before a failure is final. Default `3`. */
+    maxAttempts: number
+    /** Override the default retry policy. */
+    retryPolicy?: (ctx: {
+      phase: 'intent' | 'upload' | 'complete'
+      attempt: number
+      error: Contracts.Error
+    }) => RetryDecision
+    /** Cap on items kept in state. Set to `null` for no cap. Default `100`. */
+    maxItems: number | null
+    /** Auto-remove `completed`/`canceled` items after this many ms. */
+    completedItemTTL?: number
+    /** Concurrency cap for side-effects. Default `8`. */
+    effectConcurrency: number
+    /** Per-effect watchdog timeout in ms. `0` disables. Default `60000`. */
+    effectTimeoutMs: number
+    /** Include file context in persisted error messages. Default `false` (PII). */
+    errorContextInMessage: boolean
+    /** Keep raw thrown value as `error.cause`. Default `false` (PII). */
+    keepRawCause: boolean
+    /** Effect-queue compaction tuning. */
+    effectQueueCompaction: IEffectQueueCompaction
+    /**
+     * Skip `crypto.subtle.digest` (and the dedupe lookup that depends on it)
+     * for files larger than this byte threshold. The browser has no streaming
+     * SHA-256, so digesting a 10GB file allocates 10GB of heap; the cap lets
+     * the consumer trade dedupe coverage for memory. Default `null` (no cap).
+     */
+    checksumMaxSize: number | null
+    /**
+     * Hash only the first N bytes of each file. Yields a fast approximate
+     * fingerprint at the cost of strict uniqueness: files that share the
+     * leading window collide. Combine with `size + lastModified + chunk
+     * checksum` on the backend to form a unique dedupe key. Default
+     * `null` (full-file hash, exact match).
+     *
+     * @remarks Set to a small value (e.g. `1024 * 64`) for fast
+     * checksums on very large files where exact dedupe is not
+     * required.
+     */
+    checksumChunkBytes: number | null
+    /**
+     * When `true`, `rebind` requires the rebound `File.type` to match the
+     * paused item's fingerprint type. Default `false` because browsers
+     * disagree on MIME detection (Safari often omits MIME types Chrome
+     * attaches). Enable when both sessions are guaranteed to run in the
+     * same browser/runtime.
+     */
+    strictRebindType: boolean
+  }
+
+  /**
+   * Partial form accepted by `createUploadStore`. Nested config groups
+   * (e.g. `effectQueueCompaction`) accept their own partial shape so
+   * callers can override one knob without restating the rest.
+   */
+  export type UploadConfigInput<P extends string> = Partial<Omit<IUploadConfig<P>, 'effectQueueCompaction'>> & {
+    effectQueueCompaction?: Partial<IEffectQueueCompaction>
+  }
+
+  // -------------------- Hooks --------------------
+
+  /** Optional observability hooks. Diagnostics / analytics / devtools / Sentry. */
+  export interface IUploadHooks<
+    M extends Contracts.IntentMap,
+    C extends Contracts.CursorMap<M>,
+    P extends string,
+    R extends Contracts.IResultBase = Contracts.IResultBase,
+  > {
+    /** Fires after every internal event applied by the reducer. */
+    onInternalEvent?: (event: Engine.InternalEvent<M, C, P, R>, state: Reducer.IState<M, C, P, R>) => void
+    /** Fires when a persistence adapter operation fails. */
+    onPersistenceError?: (error: PersistenceError) => void
+    /** Fires on listener / plugin / emitter / batch throws. */
+    onListenerError?: (
+      error: unknown,
+      context: { kind: 'subscriber' | 'plugin-setup' | 'emitter' | 'batch'; name?: string },
+    ) => void
+    /**
+     * Fires when the effect queue rejects a new effect because it is at
+     * `effectQueueCompaction.maxQueueLength`. Production telemetry hook so
+     * dropped effects are not silently swallowed. Passes the current queue
+     * length (`queueLength`), active in-flight effect count (`active`), the
+     * hard cap (`cap`), and the optional `localId` of the upload that
+     * triggered the enqueue (when the caller threaded it through).
+     */
+    onEffectDropped?: (context: { queueLength: number; active: number; cap: number; localId?: string }) => void
+    /**
+     * Fires when `scheduleWork`'s re-entrant pass loop hits the soft cap
+     * (default 100). Production telemetry hook so a runaway feedback
+     * loop is visible even when dev-mode `console.error` is gated out.
+     */
+    onScheduleStarved?: (context: { passes: number }) => void
+    /**
+     * Fires when `flushPersistence`'s trailing-flush loop hits the soft
+     * cap. A pathological feedback loop (e.g. `onPersistenceError`
+     * dispatching state changes that schedule another flush) would
+     * otherwise spin forever. Defaults to 100 trailing iterations.
+     */
+    onPersistenceLoopStarved?: (context: { passes: number }) => void
+  }
+
+  // -------------------- Plugin --------------------
+
+  /** Store plugin. Subscribed once at construction with a narrow store view. */
+  export interface IUploadPlugin<
+    M extends Contracts.IntentMap,
+    C extends Contracts.CursorMap<M>,
+    P extends string,
+    R extends Contracts.IResultBase = Contracts.IResultBase,
+  > {
+    /** Plugin name (used in debugging output + `onListenerError` context). */
+    name: string
+    /**
+     * Called once at construction. May return a `Promise` to delay
+     * `store.ready` until the plugin finishes initializing (e.g. fetching
+     * remote feature flags). Sync throws and async rejections are both
+     * routed through `onListenerError`.
+     *
+     * Wider surface than R23: plugins now also see `flush` / `cleanup` /
+     * `purge` / `has` / `waitFor` / `subscribe` so a plugin can await
+     * durability, do bulk operations, or subscribe via the public
+     * mechanism instead of holding raw `rt` references.
+     */
+    setup: (
+      ctx: Pick<
+        Store.IUploadStore<M, C, P, R>,
+        'on' | 'off' | 'dispatch' | 'getSnapshot' | 'subscribe' | 'waitFor' | 'flush' | 'cleanup' | 'purge' | 'has'
+      >,
+    ) => void | Promise<void>
+    /**
+     * Called once during `store.destroy()` so the plugin can release its
+     * own resources (timers, external subscriptions, network handles).
+     * May return a `Promise` -- `destroy()` awaits all plugin disposes
+     * before resolving. Sync throws and async rejections route through
+     * `onListenerError` and never reject `destroy()`.
+     */
+    dispose?: () => void | Promise<void>
+  }
+}

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

@@ -0,0 +1,179 @@
+/**
+ * Public contract types grouped under the `Contracts` namespace.
+ *
+ * Each sub-namespace owns one concern (Intent, Cursor, Result, Fingerprint,
+ * Errors, Validation, Strategy, BackendApi).
+ *
+ * @author wildduck2 <https://github.com/wildduck2>
+ */
+export namespace Contracts {
+  // -------------------- Intent --------------------
+
+  /** Base shape for all upload intents. */
+  export interface IIntentBase<K extends string = string> {
+    /** Strategy name (discriminant). */
+    strategy: K
+    /** Unique backend file identifier. */
+    fileId: string
+  }
+
+  /** Registry of intent types mapped by strategy name. */
+  export type IntentMap = Record<string, IIntentBase<string>>
+
+  /** Union of strategy keys for an intent map. */
+  export type StrategyKey<M extends IntentMap> = keyof M & string
+
+  /** Union of all intent variants for an intent map. */
+  export type AnyIntent<M extends IntentMap> = M[StrategyKey<M>]
+
+  // -------------------- Cursor --------------------
+
+  /** Registry of cursor payload types mapped by strategy name. */
+  export type CursorMap<M extends IntentMap> = Partial<Record<StrategyKey<M>, unknown>>
+
+  /** Discriminated union of all cursor variants. */
+  export type AnyCursor<C extends Record<string, unknown>> = {
+    [K in keyof C & string]: { strategy: K; value?: C[K] }
+  }[keyof C & string]
+
+  // -------------------- Result --------------------
+
+  /** Base shape for upload completion results returned by your backend. */
+  export interface IResultBase {
+    /** Backend file identifier. */
+    fileId: string
+    /** Storage key or path used for signed URLs. */
+    key: string
+  }
+
+  // -------------------- Fingerprint --------------------
+
+  /** Deterministic client-side identity for a file. */
+  export interface IFileFingerprint {
+    /** File name. */
+    name: string
+    /** File size in bytes. */
+    size: number
+    /** File MIME type. */
+    type: string
+    /** File lastModified timestamp (ms). */
+    lastModified: number
+    /** Optional checksum (e.g. SHA-256 hex). */
+    checksum?: string
+  }
+
+  // -------------------- Errors --------------------
+
+  /** File rejection reasons produced by client-side validation. */
+  export type RejectReason =
+    | { code: 'empty_file' }
+    | { code: 'file_too_large'; maxBytes: number; size: number }
+    | { code: 'type_not_allowed'; allowed: string[]; got: string }
+    | { code: 'too_many_files'; max: number }
+
+  /** Base shape for custom errors. */
+  export interface IErrorBase {
+    /** Stable error code. */
+    code: string
+    /** Human-friendly message (safe for UI). */
+    message: string
+    /** Optional cause (original error, response, etc.). */
+    cause?: unknown
+    /** Whether the error should be retried. */
+    retryable?: boolean
+  }
+
+  /** Built-in engine errors. */
+  export type BuiltInError =
+    | { code: 'validation_failed'; message: string; reason: RejectReason; retryable?: false }
+    | { code: 'strategy_missing'; message: string; strategy: string; retryable?: false }
+    | { code: 'aborted'; message: string; reason: 'pause' | 'cancel' | 'unknown'; cause?: unknown; retryable?: false }
+    | { code: 'network'; message: string; cause?: unknown; retryable?: boolean }
+    | { code: 'http'; message: string; status: number; statusText?: string; cause?: unknown; retryable?: boolean }
+    | { code: 'timeout'; message: string; cause?: unknown; retryable?: boolean }
+    | { code: 'auth'; message: string; cause?: unknown; retryable?: false }
+    | { code: 'rate_limit'; message: string; retryAfterMs?: number; cause?: unknown; retryable?: boolean }
+    | { code: 'server'; message: string; serverCode?: string; cause?: unknown; retryable?: boolean }
+    | { code: 'unknown'; message: string; cause?: unknown; retryable?: boolean }
+
+  /** The error type used everywhere in the engine. */
+  export type Error = BuiltInError | (IErrorBase & Record<string, unknown>)
+
+  // -------------------- Validation --------------------
+
+  /** Validation rules applied on `addFiles`. */
+  export interface IValidationRules {
+    /** Maximum number of files allowed. */
+    maxFiles?: number
+    /** Maximum file size in bytes. */
+    maxSizeBytes?: number
+    /** Minimum file size in bytes. */
+    minSizeBytes?: number
+    /** Allowed MIME types. */
+    allowedTypes?: string[]
+    /** Allowed file extensions. */
+    allowedExtensions?: string[]
+  }
+
+  // -------------------- Backend API --------------------
+
+  /** Common options object for backend calls. */
+  export type WithSignal = { signal?: AbortSignal }
+
+  /** Backend adapter the engine calls into. */
+  export interface IUploadApi<M extends IntentMap, P extends string, R extends IResultBase = IResultBase> {
+    /**
+     * Create an upload intent. The backend decides the strategy and any
+     * presigned URLs / form fields.
+     */
+    createIntent(
+      args: { purpose: P; contentType: string; size: number; filename: string; checksum?: string },
+      opts?: WithSignal,
+    ): Promise<M[keyof M]>
+
+    /** Finalize an upload after all bytes are on the server. */
+    complete(args: { fileId: string }, opts?: WithSignal): Promise<R>
+
+    /** Optional helper to mint a signed preview URL for a finished upload. */
+    getSignedPreviewUrl?(args: { fileId: string; key: string; purpose: P }, opts?: WithSignal): Promise<string>
+
+    /** Optional checksum-based dedupe lookup. */
+    findByChecksum?(args: { checksum: string; purpose: P }, opts?: WithSignal): Promise<R | null>
+
+    /** Multipart-strategy operations. Required when using the multipart strategy. */
+    multipart?: {
+      /** Sign one part for upload. */
+      signPart(
+        args: { fileId: string; uploadId: string; partNumber: number; checksum?: string },
+        opts?: WithSignal,
+      ): Promise<{ url: string; headers?: Record<string, string> }>
+
+      /** Tell the backend to assemble the parts into the final object. */
+      completeMultipart(
+        args: { fileId: string; uploadId: string; parts: Array<{ partNumber: number; etag: string }> },
+        opts?: WithSignal,
+      ): Promise<unknown>
+
+      /** Optional: list already-uploaded parts (used by resume diagnostics). */
+      listParts?(
+        args: { fileId: string; uploadId: string },
+        opts?: WithSignal,
+      ): Promise<Array<{ partNumber: number; etag?: string; size?: number }>>
+
+      /** Optional: abort an in-progress multipart session on the backend. */
+      abort?(args: { fileId: string; uploadId: string }, opts?: WithSignal): Promise<void>
+    }
+
+    /** TUS-strategy operations. */
+    tus?: {
+      /** Create a TUS upload session, returning its URL. */
+      create(
+        args: { fileId: string; size: number; filename: string; contentType: string },
+        opts?: WithSignal,
+      ): Promise<{ uploadUrl: string }>
+
+      /** Read the current TUS upload offset (used for resume). */
+      getOffset(args: { uploadUrl: string }, opts?: WithSignal): Promise<{ offset: number }>
+    }
+  }
+}

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

@@ -1,29 +1,26 @@
 import { isRecord } from '../../utils/guards'
 
-// ============================================================================
-// ABORT HANDLING UTILITIES
-// ============================================================================
-
 export function abortReason(signal?: AbortSignal): unknown {
   return signal?.reason
 }
 
+/**
+ * Map `controller.abort(reason)` payloads to `'pause' | 'cancel'`. Accepts a
+ * bare string, `{ reason }`, or `{ kind }` shape.
+ */
 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
@@ -46,20 +43,9 @@ 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
- */
+/** XHR network error with `status === 0` heuristic for CORS detection. */
 export function createNetworkError(xhr: XMLHttpRequest, defaultMessage: string): Error {
-  // Status 0 typically indicates CORS failure or network error
+  // status 0 → CORS failure or transport-level 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.',
@@ -68,18 +54,7 @@ export function createNetworkError(xhr: XMLHttpRequest, defaultMessage: string):
   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
- */
+/** Parse XHR headers into a lowercase-keyed record. */
 export function parseHeaders(xhr: XMLHttpRequest): Record<string, string> {
   const headers: Record<string, string> = {}
   const headerStr = xhr.getAllResponseHeaders()