@gentleduck/upload 0.2.5 → 0.3.0

package/src/__tests__/transport-fetch.test.ts

@@ -0,0 +1,108 @@
+import { afterEach, describe, expect, test, vi } from 'vitest'
+import { createFetchTransport } from '../core/contracts/transport'
+import { UploadAbortError } from '../core/contracts/transport/transport.libs'
+
+const URL_OK = 'https://up.example.com/o'
+
+function stubFetch(impl: (url: string, init: RequestInit) => Promise<Response> | Response) {
+  const fn = vi.fn(impl)
+  vi.stubGlobal('fetch', fn)
+  return fn
+}
+
+afterEach(() => {
+  vi.unstubAllGlobals()
+})
+
+describe('createFetchTransport.put', () => {
+  test('PUTs the body and returns the ETag', async () => {
+    const fetchMock = stubFetch(() => new Response(null, { status: 200, headers: { ETag: '"deadbeef"' } }))
+    const t = createFetchTransport()
+    const onProgress = vi.fn()
+    const out = await t.put({
+      url: URL_OK,
+      body: new Blob([new Uint8Array(10)]),
+      headers: { 'Content-Type': 'application/octet-stream' },
+      signal: new AbortController().signal,
+      onProgress,
+    })
+
+    expect(out.etag).toBe('deadbeef')
+    const [url, init] = fetchMock.mock.calls[0] as [string, RequestInit]
+    expect(url).toBe(URL_OK)
+    expect(init.method).toBe('PUT')
+    // Terminal progress tick.
+    expect(onProgress).toHaveBeenCalledWith(10, 10)
+  })
+
+  test('rejects non-2xx with the status', async () => {
+    stubFetch(() => new Response('nope', { status: 500 }))
+    const t = createFetchTransport()
+    await expect(t.put({ url: URL_OK, body: new Blob(['x']), signal: new AbortController().signal })).rejects.toThrow(
+      /status 500/,
+    )
+  })
+
+  test('rejects a relative URL', async () => {
+    stubFetch(() => new Response(null, { status: 200 }))
+    const t = createFetchTransport()
+    await expect(
+      t.put({ url: '/relative', body: new Blob(['x']), signal: new AbortController().signal }),
+    ).rejects.toThrow(/absolute URL/)
+  })
+
+  test('maps an aborted signal to UploadAbortError', async () => {
+    stubFetch(() => new Response(null, { status: 200 }))
+    const controller = new AbortController()
+    controller.abort('cancel')
+    const t = createFetchTransport()
+    await expect(t.put({ url: URL_OK, body: new Blob(['x']), signal: controller.signal })).rejects.toBeInstanceOf(
+      UploadAbortError,
+    )
+  })
+})
+
+describe('createFetchTransport.postForm', () => {
+  test('sends multipart form data', async () => {
+    const fetchMock = stubFetch(() => new Response(null, { status: 204 }))
+    const t = createFetchTransport()
+    await t.postForm({
+      url: URL_OK,
+      fields: { key: 'v', policy: 'p' },
+      file: new File(['abc'], 'a.txt'),
+      signal: new AbortController().signal,
+    })
+    const [, init] = fetchMock.mock.calls[0] as [string, RequestInit]
+    expect(init.method).toBe('POST')
+    expect(init.body).toBeInstanceOf(FormData)
+  })
+})
+
+describe('createFetchTransport.get', () => {
+  test('streams the body and reports incremental progress', async () => {
+    const payload = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8])
+    stubFetch(
+      () =>
+        new Response(payload, {
+          status: 200,
+          headers: { 'Content-Length': String(payload.length), 'Content-Type': 'application/octet-stream' },
+        }),
+    )
+    const t = createFetchTransport()
+    const onProgress = vi.fn()
+    const out = await t.get?.({ url: URL_OK, signal: new AbortController().signal, onProgress })
+    expect(out?.status).toBe(200)
+    const bytes = new Uint8Array(await out!.blob.arrayBuffer())
+    expect(Array.from(bytes)).toEqual(Array.from(payload))
+    // Final progress equals total.
+    const last = onProgress.mock.calls.at(-1)
+    expect(last?.[0]).toBe(payload.length)
+    expect(last?.[1]).toBe(payload.length)
+  })
+
+  test('rejects a failed download', async () => {
+    stubFetch(() => new Response('nope', { status: 404 }))
+    const t = createFetchTransport()
+    await expect(t.get?.({ url: URL_OK, signal: new AbortController().signal })).rejects.toThrow(/status 404/)
+  })
+})

package/src/__tests__/transport-libs.test.ts

@@ -0,0 +1,42 @@
+import { describe, expect, test } from 'vitest'
+import { makeAbortError, normalizeAbortReason, UploadAbortError } from '../core/contracts/transport/transport.libs'
+
+describe('normalizeAbortReason', () => {
+  test('passes bare strings through when valid', () => {
+    expect(normalizeAbortReason('pause')).toBe('pause')
+    expect(normalizeAbortReason('cancel')).toBe('cancel')
+  })
+
+  test('unknown bare strings degrade to "unknown"', () => {
+    expect(normalizeAbortReason('shutdown')).toBe('unknown')
+    expect(normalizeAbortReason(undefined)).toBe('unknown')
+    expect(normalizeAbortReason(null)).toBe('unknown')
+  })
+
+  test('extracts .reason and .kind from object payloads', () => {
+    expect(normalizeAbortReason({ reason: 'pause' })).toBe('pause')
+    expect(normalizeAbortReason({ kind: 'cancel' })).toBe('cancel')
+  })
+
+  test('arrays do not crash and degrade to unknown', () => {
+    expect(normalizeAbortReason(['pause'])).toBe('unknown')
+  })
+})
+
+describe('UploadAbortError / makeAbortError', () => {
+  test('exposes a stable code', () => {
+    const e = makeAbortError('pause')
+    expect(e).toBeInstanceOf(UploadAbortError)
+    expect(e.code).toBe('aborted')
+    expect(e.reason).toBe('pause')
+  })
+
+  test('defaults unknown reasons', () => {
+    expect(makeAbortError(undefined).reason).toBe('unknown')
+  })
+
+  test('structured payloads with a known reason still normalize to pause/cancel', () => {
+    expect(new UploadAbortError({ reason: 'cancel', extra: 'meta' }).reason).toBe('cancel')
+    expect(new UploadAbortError({ kind: 'pause' }).reason).toBe('pause')
+  })
+})

package/src/__tests__/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/__tests__/errors.test.ts

@@ -0,0 +1,152 @@
+import { describe, expect, test } from 'vitest'
+import { UploadEngineError } from '../errors'
+
+const MALICIOUS_FILENAME = '<img src=x onerror=alert(1)>.png'
+
+describe('UploadEngineError', () => {
+  test('message is static, does NOT contain the raw filename', () => {
+    const err = new UploadEngineError('upload_failed', { context: { filename: MALICIOUS_FILENAME } })
+    expect(err.message).not.toContain(MALICIOUS_FILENAME)
+    expect(err.message).not.toContain('<img')
+    expect(err.message).toBe('upload transfer failed')
+  })
+
+  test('context.filename carries the raw filename intact', () => {
+    const err = new UploadEngineError('upload_failed', { context: { filename: MALICIOUS_FILENAME } })
+    expect(err.context?.['filename']).toBe(MALICIOUS_FILENAME)
+  })
+
+  test('is an instance of Error and UploadEngineError; code is preserved', () => {
+    const err = new UploadEngineError('intent_failed')
+    expect(err).toBeInstanceOf(Error)
+    expect(err).toBeInstanceOf(UploadEngineError)
+    expect(err.code).toBe('intent_failed')
+    expect(err.name).toBe('UploadEngineError')
+  })
+
+  test('cause is preserved on the ES2022 cause field', () => {
+    const original = new Error('boom')
+    const err = new UploadEngineError('upload_failed', { cause: original })
+    expect(err.cause).toBe(original)
+  })
+
+  test('unknown code falls back to a generic static message', () => {
+    const err = new UploadEngineError('something_new')
+    expect(err.message).toBe('upload error (something_new)')
+    expect(err.code).toBe('something_new')
+  })
+})
+
+describe('engine handlers filename-in-message inverse assertion', () => {
+  // The legacy contract was: `error.message.includes(filename)`. The new
+  // contract is the opposite: the filename MUST NOT appear in `message`. The
+  // handlers no longer interpolate filename into `message`; verifying that by
+  // exercising the handlers directly is covered by the integration suite, but
+  // we keep the contract pinned here so future refactors stay safe.
+  test('a structured error keeps the message clean and surfaces filename only on context', () => {
+    const base = { code: 'unknown' as const, message: 'Unknown error', retryable: false }
+    const error = {
+      ...base,
+      context: { filename: MALICIOUS_FILENAME, size: 12, purpose: 'avatar' },
+    }
+    expect(error.message).not.toContain(MALICIOUS_FILENAME)
+    expect(error.message).not.toContain('<img')
+    expect(error.context['filename']).toBe(MALICIOUS_FILENAME)
+  })
+})
+
+import {
+  UploadAbortError,
+  UploadAuthError,
+  UploadHttpError,
+  UploadNetworkError,
+  UploadRateLimitError,
+  UploadServerError,
+  UploadStrategyMissingError,
+  UploadTimeoutError,
+  UploadUnknownError,
+  UploadValidationError,
+} from '../errors'
+
+describe('UploadEngineError subclasses', () => {
+  test('UploadValidationError', () => {
+    const reason = { code: 'empty_file' as const }
+    const err = new UploadValidationError(reason)
+    expect(err).toBeInstanceOf(UploadEngineError)
+    expect(err.code).toBe('validation_failed')
+    expect(err.reason).toBe(reason)
+    expect(err.retryable).toBe(false)
+  })
+
+  test('UploadStrategyMissingError', () => {
+    const err = new UploadStrategyMissingError('custom')
+    expect(err).toBeInstanceOf(UploadEngineError)
+    expect(err.code).toBe('strategy_missing')
+    expect(err.strategy).toBe('custom')
+    expect(err.retryable).toBe(false)
+  })
+
+  test('UploadAbortError', () => {
+    const err = new UploadAbortError('pause')
+    expect(err).toBeInstanceOf(UploadEngineError)
+    expect(err.code).toBe('aborted')
+    expect(err.reason).toBe('pause')
+    expect(err.retryable).toBe(false)
+  })
+
+  test('UploadNetworkError', () => {
+    const err = new UploadNetworkError()
+    expect(err).toBeInstanceOf(UploadEngineError)
+    expect(err.code).toBe('network')
+    expect(err.retryable).toBe(true)
+  })
+
+  test('UploadHttpError', () => {
+    const err = new UploadHttpError(500, 'Internal Server Error', { statusText: 'Server Error' })
+    expect(err).toBeInstanceOf(UploadEngineError)
+    expect(err.code).toBe('http')
+    expect(err.status).toBe(500)
+    expect(err.statusText).toBe('Server Error')
+    expect(err.retryable).toBe(true)
+
+    const err400 = new UploadHttpError(400, 'Bad Request')
+    expect(err400.retryable).toBe(false)
+  })
+
+  test('UploadTimeoutError', () => {
+    const err = new UploadTimeoutError()
+    expect(err).toBeInstanceOf(UploadEngineError)
+    expect(err.code).toBe('timeout')
+    expect(err.retryable).toBe(true)
+  })
+
+  test('UploadAuthError', () => {
+    const err = new UploadAuthError()
+    expect(err).toBeInstanceOf(UploadEngineError)
+    expect(err.code).toBe('auth')
+    expect(err.retryable).toBe(false)
+  })
+
+  test('UploadRateLimitError', () => {
+    const err = new UploadRateLimitError('Too many requests', { retryAfterMs: 5000 })
+    expect(err).toBeInstanceOf(UploadEngineError)
+    expect(err.code).toBe('rate_limit')
+    expect(err.retryAfterMs).toBe(5000)
+    expect(err.retryable).toBe(true)
+  })
+
+  test('UploadServerError', () => {
+    const err = new UploadServerError('DB Error', { serverCode: 'DB_ERROR' })
+    expect(err).toBeInstanceOf(UploadEngineError)
+    expect(err.code).toBe('server')
+    expect(err.serverCode).toBe('DB_ERROR')
+    expect(err.retryable).toBe(true)
+  })
+
+  test('UploadUnknownError', () => {
+    const err = new UploadUnknownError('Something exploded')
+    expect(err).toBeInstanceOf(UploadEngineError)
+    expect(err.code).toBe('unknown')
+    expect(err.retryable).toBe(false)
+  })
+})

package/src/core/client.ts

@@ -0,0 +1,3 @@
+export { resolveUploadConfig } from './engine/engine.libs'
+export type { Store } from './engine/store'
+export { createUploadStore } from './engine/store'