@gentleduck/upload 0.2.5 → 0.3.0

package/src/react/use-dropzone.tsx

@@ -0,0 +1,226 @@
+import type * as React from 'react'
+import { useCallback, useMemo, useRef, useState } from 'react'
+import type { Contracts } from '../core'
+import type { Store } from '../core/engine/store'
+import { useUploadStore } from './upload-provider'
+
+/**
+ * Test a file against one token from an `accept` string. A token is a MIME type
+ * (`image/png`), a MIME wildcard (`image/*`), or a filename extension (`.pdf`).
+ * @internal exported for tests.
+ */
+export function matchesAcceptToken(file: File, token: string): boolean {
+  const t = token.trim().toLowerCase()
+  if (!t) return false
+
+  if (t.startsWith('.')) {
+    return file.name.toLowerCase().endsWith(t)
+  }
+
+  const type = (file.type || '').toLowerCase()
+  if (t.endsWith('/*')) {
+    return type.startsWith(`${t.slice(0, -1)}`) // "image/" prefix
+  }
+  return type === t
+}
+
+/**
+ * True when `file` satisfies an `accept` list (comma-separated tokens). An empty
+ * or absent list accepts everything.
+ * @internal exported for tests.
+ */
+export function fileMatchesAccept(file: File, accept?: string): boolean {
+  if (!accept) return true
+  const tokens = accept
+    .split(',')
+    .map((s) => s.trim())
+    .filter(Boolean)
+  if (tokens.length === 0) return true
+  return tokens.some((tok) => matchesAcceptToken(file, tok))
+}
+
+/**
+ * Filter a dropped/selected file list by `accept` and collapse to a single file
+ * when `multiple` is false.
+ * @internal exported for tests.
+ */
+export function selectFiles(
+  files: File[],
+  opts: { accept?: string | undefined; multiple?: boolean | undefined },
+): File[] {
+  const accepted = files.filter((f) => fileMatchesAccept(f, opts.accept))
+  return opts.multiple === false ? accepted.slice(0, 1) : accepted
+}
+
+/** Options for {@link useDropzone}. */
+export type UseDropzoneOptions<P extends string> = {
+  /** Purpose forwarded to the `addFiles` command. */
+  purpose: P
+  /** Optional caller metadata forwarded to every backend API call. */
+  meta?: Record<string, unknown>
+  /**
+   * Comma-separated `accept` list (`"image/*,.pdf"`). Filters dropped files and
+   * populates the input's `accept` attribute. Absent = accept everything.
+   */
+  accept?: string
+  /** Allow multiple files. Defaults to `true`. */
+  multiple?: boolean
+  /** Disable all interaction (no drop, no click-to-open). Defaults to `false`. */
+  disabled?: boolean
+  /** Do not open the file dialog when the root is clicked. Defaults to `false`. */
+  noClick?: boolean
+  /**
+   * Override the default dispatch. When provided, accepted files are handed here
+   * instead of being dispatched as `addFiles` to the store.
+   */
+  onFiles?: (files: File[]) => void
+  /** Store instance to dispatch to. Falls back to the `<UploadProvider>` store. */
+  store?: Store.UploadStore<Contracts.Intent.Map, Contracts.Cursor.Map<Contracts.Intent.Map>, P, Contracts.Result.Base>
+}
+
+/** Return value of {@link useDropzone}. */
+export type UseDropzoneReturn = {
+  /** True while files are being dragged over the root. */
+  isDragging: boolean
+  /** Programmatically open the native file picker. */
+  open: () => void
+  /** Ref to attach to the hidden `<input type="file">`. */
+  inputRef: React.RefObject<HTMLInputElement | null>
+  /** Spread onto the drop-target element. */
+  getRootProps: (extra?: React.HTMLAttributes<HTMLElement>) => React.HTMLAttributes<HTMLElement>
+  /** Spread onto the hidden `<input type="file">`. */
+  getInputProps: (
+    extra?: React.InputHTMLAttributes<HTMLInputElement>,
+  ) => React.InputHTMLAttributes<HTMLInputElement> & { ref: React.Ref<HTMLInputElement> }
+}
+
+/**
+ * Headless drag-and-drop / file-picker hook.
+ *
+ * Wires drop and file-input events to the upload store's `addFiles` command
+ * (or a custom `onFiles` handler). Returns prop-getters for the drop target and
+ * a hidden file input plus a live `isDragging` flag — styling and markup are
+ * entirely yours.
+ *
+ * @example
+ * ```tsx
+ * function Drop() {
+ *   const { getRootProps, getInputProps, isDragging, open } = useDropzone({
+ *     purpose: 'attachment',
+ *     accept: 'image/*',
+ *   });
+ *   return (
+ *     <div {...getRootProps()} data-active={isDragging}>
+ *       <input {...getInputProps()} />
+ *       <button type="button" onClick={open}>Choose files</button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ * @author wildduck2 <https://github.com/wildduck2>
+ */
+export function useDropzone<P extends string>(options: UseDropzoneOptions<P>): UseDropzoneReturn {
+  const { purpose, meta, accept, multiple = true, disabled = false, noClick = false, onFiles } = options
+
+  // Read the context store unconditionally (hooks rule); prefer an explicit one.
+  const contextStore = useUploadStore<
+    Contracts.Intent.Map,
+    Contracts.Cursor.Map<Contracts.Intent.Map>,
+    P,
+    Contracts.Result.Base
+  >()
+  const store = options.store ?? contextStore
+
+  const inputRef = useRef<HTMLInputElement | null>(null)
+  const [isDragging, setIsDragging] = useState(false)
+  // Depth counter so nested dragenter/dragleave don't flicker the flag.
+  const dragDepth = useRef(0)
+
+  const handleFiles = useCallback(
+    (list: FileList | null) => {
+      if (!list || list.length === 0) return
+      const chosen = selectFiles(Array.from(list), { accept, multiple })
+      if (chosen.length === 0) return
+      if (onFiles) {
+        onFiles(chosen)
+      } else {
+        store.dispatch({ type: 'addFiles', files: chosen, purpose, meta })
+      }
+    },
+    [accept, multiple, onFiles, store, purpose, meta],
+  )
+
+  const open = useCallback(() => {
+    if (disabled) return
+    inputRef.current?.click()
+  }, [disabled])
+
+  const getRootProps = useCallback<UseDropzoneReturn['getRootProps']>(
+    (extra = {}) => ({
+      ...extra,
+      onDragEnter: (e) => {
+        extra.onDragEnter?.(e)
+        if (disabled) return
+        e.preventDefault()
+        e.stopPropagation()
+        dragDepth.current += 1
+        setIsDragging(true)
+      },
+      onDragOver: (e) => {
+        extra.onDragOver?.(e)
+        if (disabled) return
+        // Required so the browser fires `drop` instead of navigating.
+        e.preventDefault()
+        e.stopPropagation()
+      },
+      onDragLeave: (e) => {
+        extra.onDragLeave?.(e)
+        if (disabled) return
+        e.preventDefault()
+        e.stopPropagation()
+        dragDepth.current = Math.max(0, dragDepth.current - 1)
+        if (dragDepth.current === 0) setIsDragging(false)
+      },
+      onDrop: (e) => {
+        extra.onDrop?.(e)
+        if (disabled) return
+        e.preventDefault()
+        e.stopPropagation()
+        dragDepth.current = 0
+        setIsDragging(false)
+        handleFiles(e.dataTransfer?.files ?? null)
+      },
+      onClick: (e) => {
+        extra.onClick?.(e)
+        if (disabled || noClick) return
+        open()
+      },
+    }),
+    [disabled, noClick, open, handleFiles],
+  )
+
+  const getInputProps = useCallback<UseDropzoneReturn['getInputProps']>(
+    (extra = {}) => ({
+      ...extra,
+      ref: inputRef,
+      type: 'file',
+      multiple,
+      disabled,
+      ...(accept ? { accept } : {}),
+      // Visually hidden; caller styles can extend but not un-hide by accident.
+      style: { display: 'none', ...extra.style },
+      onChange: (e) => {
+        extra.onChange?.(e)
+        handleFiles(e.target.files)
+        // Reset so selecting the same file again re-fires change.
+        e.target.value = ''
+      },
+    }),
+    [multiple, disabled, accept, handleFiles],
+  )
+
+  return useMemo(
+    () => ({ isDragging, open, inputRef, getRootProps, getInputProps }),
+    [isDragging, open, getRootProps, getInputProps],
+  )
+}

package/src/react/use-uploader.tsx

@@ -1,108 +1,90 @@
-'use client'
-
 import * as React from 'react'
-import type {
-  CursorMap,
-  IntentMap,
-  UploadCommand,
-  UploadEventMap,
-  UploadItem,
-  UploadPhase,
-  UploadResultBase,
-} from '../core'
-import type { UploadStore } from '../core/engine/store'
-import { useOptionalUploadStore, useUploadStore } from './upload-provider'
-
-export function createUploadFactory<
-  M extends IntentMap,
-  C extends CursorMap<M>,
-  P extends string,
-  R extends UploadResultBase = UploadResultBase,
->(store: UploadStore<M, C, P, R>) {
-  return () => useUploader<M, C, P, R>(store)
-}
-
-export type PickItemsByPhase<Phase extends UploadPhase> = Extract<
-  UploadItem<IntentMap, CursorMap<IntentMap>, string, UploadResultBase>,
-  { phase: Phase }
->
-
-type Uploader<M extends IntentMap, C extends CursorMap<M>, P extends string, R extends UploadResultBase> = {
-  items: UploadItem<M, C, P, R>[]
-  byPhase: Record<string, UploadItem<M, C, P, R>[]>
-  dispatch: (cmd: UploadCommand<P>) => void
-  on: <K extends keyof UploadEventMap<M, C, P, R> & string>(
-    type: K,
-    cb: (payload: UploadEventMap<M, C, P, R>[K]) => void,
-  ) => () => void
-  off: <K extends keyof UploadEventMap<M, C, P, R> & string>(
-    type: K,
-    cb: (payload: UploadEventMap<M, C, P, R>[K]) => void,
-  ) => () => void
-  uploading: UploadItem<M, C, P, R>[]
-  paused: UploadItem<M, C, P, R>[]
-  completed: UploadItem<M, C, P, R>[]
-  failed: UploadItem<M, C, P, R>[]
-  ready: UploadItem<M, C, P, R>[]
-}
+import { useMemo, useSyncExternalStore } from 'react'
+import type { Contracts, Engine } from '../core'
+import type { Store } from '../core/engine/store'
+import { useUploadStore } from './upload-provider'
+import type { Uploader } from './uploader.types'
 
 /**
- * Stable action surface for React consumers that need imperative store access.
+ * Hook to consume the upload store state, track files, and interact with the upload engine.
  *
- * This is declared explicitly instead of relying on an inferred object return
- * type so the generated package declarations do not leak the internal generic
- * names created by `store.on.bind(store)`.
+ * Exposes files, categorizes items by status phase (ready, uploading, paused, completed, failed),
+ * and registers action dispatchers.
+ *
+ * Can optionally be passed a specific store instance directly. Otherwise, it will read the store from context.
+ *
+ * @example
+ * ```tsx
+ * function UploadForm() {
+ *   const { items, uploading, dispatch } = useUploader();
+ *
+ *   const onFileChange = (e: React.ChangeEvent<HTMLInputElement>) => {
+ *     if (e.target.files) {
+ *       dispatch({ type: 'addFiles', files: Array.from(e.target.files), purpose: 'avatar' });
+ *     }
+ *   };
+ *
+ *   return (
+ *     <div>
+ *       <input type="file" onChange={onFileChange} multiple />
+ *       <ul>
+ *         {items.map(item => (
+ *           <li key={item.localId}>{item.fingerprint.name} - {item.phase}</li>
+ *         ))}
+ *       </ul>
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @template M - Intent map type
+ * @template C - Cursor map type
+ * @template P - Purpose string union type
+ * @template R - Backend result shape
+ * @author wildduck2 <https://github.com/wildduck2>
  */
-export type UploaderActions<
-  M extends IntentMap,
-  C extends CursorMap<M>,
-  P extends string,
-  R extends UploadResultBase = UploadResultBase,
-> = Pick<UploadStore<M, C, P, R>, 'dispatch' | 'on'> & {
-  store: UploadStore<M, C, P, R>
-}
-
 export function useUploader<
-  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,
->(): Uploader<M, C, P, R>
-export function useUploader<
-  M extends IntentMap,
-  C extends CursorMap<M>,
-  P extends string,
-  R extends UploadResultBase = UploadResultBase,
->(store: UploadStore<M, C, P, R>): Uploader<M, C, P, R>
-export function useUploader<
-  M extends IntentMap,
-  C extends CursorMap<M>,
-  P extends string,
-  R extends UploadResultBase = UploadResultBase,
->(providedStore?: UploadStore<M, C, P, R> | undefined) {
-  const contextStore = useOptionalUploadStore<M, C, P, R>()
+  R extends Contracts.Result.Base = Contracts.Result.Base,
+>(providedStore?: Store.UploadStore<M, C, P, R> | undefined): Uploader.State<M, C, P, R> {
+  const contextStore = useUploadStore<M, C, P, R>()
   const store = providedStore ?? contextStore
+
   if (!store) {
-    throw new Error('useUploader must be used within UploadProvider when no store argument is provided')
+    throw new Error('useUploader must be used within an <UploadProvider> or passed a store instance directly.')
   }
 
-  const snapshot = React.useSyncExternalStore(
-    store.subscribe.bind(store),
-    store.getSnapshot.bind(store),
-    store.getSnapshot.bind(store),
+  const state = useSyncExternalStore(
+    store.subscribe,
+    store.getSnapshot,
+    store.getSnapshot, // SSR fallback placeholder.
   )
 
-  const items = React.useMemo(() => {
-    return Array.from(snapshot.items.values())
-  }, [snapshot.items])
+  const items = useMemo(() => {
+    return Array.from(state.items.values())
+  }, [state])
 
-  const byPhase = React.useMemo(() => {
-    const result: Record<string, UploadItem<M, C, P, R>[]> = {}
+  const byPhase = useMemo(() => {
+    const result: Record<Engine.Phase, Array<Engine.Item<M, C, P, R>>> = {
+      validating: [],
+      creating_intent: [],
+      ready: [],
+      queued: [],
+      uploading: [],
+      paused: [],
+      completing: [],
+      completed: [],
+      error: [],
+      canceled: [],
+    }
     items.forEach((item) => {
-      if (!result[item.phase]) {
-        result[item.phase] = []
+      const phase = item.phase
+      if (!result[phase]) {
+        result[phase] = []
       }
-      result[item.phase].push(item)
+      result[phase].push(item)
     })
     return result
   }, [items])
@@ -121,12 +103,19 @@ export function useUploader<
   }
 }
 
+/**
+ * Returns the store's imperative actions (dispatch, event bindings) along with a direct
+ * reference to the store instance. Does not trigger React re-renders on upload progress or state changes.
+ *
+ * Use this when you only need to trigger commands or subscribe to events without binding UI lists.
+ * @author wildduck2 <https://github.com/wildduck2>
+ */
 export function useUploaderActions<
-  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,
->(): UploaderActions<M, C, P, R> {
+  R extends Contracts.Result.Base = Contracts.Result.Base,
+>(): Uploader.IActions<M, C, P, R> {
   const store = useUploadStore<M, C, P, R>()
 
   const dispatch = React.useMemo(() => store.dispatch.bind(store), [store])
@@ -134,3 +123,18 @@ export function useUploaderActions<
 
   return { dispatch, on, store }
 }
+
+/**
+ * Creates a bound `useUploader` hook pre-configured for a specific store instance.
+ *
+ * Useful for building static multi-uploader widgets or context-free setups.
+ * @author wildduck2 <https://github.com/wildduck2>
+ */
+export function createUploadFactory<
+  M extends Contracts.Intent.Map,
+  C extends Contracts.Cursor.Map<M>,
+  P extends string,
+  R extends Contracts.Result.Base = Contracts.Result.Base,
+>(store: Store.UploadStore<M, C, P, R>) {
+  return () => useUploader<M, C, P, R>(store)
+}

package/src/strategies/_shared/__tests__/retry.test.ts

@@ -0,0 +1,120 @@
+import { describe, expect, it, vi } from 'vitest'
+import { DEFAULT_MAX_RETRIES, isAbort, isRetryable, withRetry } from '../retry'
+
+describe('isAbort', () => {
+  it('detects AbortError by name', () => {
+    const err = new Error('cancelled')
+    err.name = 'AbortError'
+    expect(isAbort(err)).toBe(true)
+  })
+
+  it('detects abort by message', () => {
+    expect(isAbort(new Error('request was aborted'))).toBe(true)
+  })
+
+  it('is false for plain errors and non-errors', () => {
+    expect(isAbort(new Error('network down'))).toBe(false)
+    expect(isAbort('abort')).toBe(false)
+  })
+})
+
+describe('isRetryable', () => {
+  it('matches transient network wording and codes', () => {
+    expect(isRetryable(new Error('network error'))).toBe(true)
+    expect(isRetryable(new Error('socket timeout'))).toBe(true)
+    expect(isRetryable(new Error('Upload failed with status 503'))).toBe(true)
+    expect(isRetryable(new Error('read ECONNRESET'))).toBe(true)
+    expect(isRetryable(new Error('connect EHOSTUNREACH'))).toBe(true)
+  })
+
+  it('is false for non-transient errors', () => {
+    expect(isRetryable(new Error('validation failed'))).toBe(false)
+    expect(isRetryable(new Error('Upload failed with status 403'))).toBe(false)
+  })
+})
+
+describe('withRetry', () => {
+  it('returns first-attempt result without retrying', async () => {
+    const fn = vi.fn(async () => 'ok')
+    await expect(withRetry(fn)).resolves.toBe('ok')
+    expect(fn).toHaveBeenCalledTimes(1)
+  })
+
+  it('retries transient failures then succeeds', async () => {
+    let calls = 0
+    const fn = vi.fn(async () => {
+      calls++
+      if (calls < 3) throw new Error('network glitch')
+      return calls
+    })
+    await expect(withRetry(fn, { maxRetries: 5 })).resolves.toBe(3)
+    expect(fn).toHaveBeenCalledTimes(3)
+  })
+
+  it('passes the zero-based attempt index to fn', async () => {
+    const seen: number[] = []
+    let calls = 0
+    await withRetry(
+      async (attempt) => {
+        seen.push(attempt)
+        calls++
+        if (calls < 3) throw new Error('timeout')
+        return null
+      },
+      { maxRetries: 5 },
+    )
+    expect(seen).toEqual([0, 1, 2])
+  })
+
+  it('gives up after maxRetries and rethrows', async () => {
+    const fn = vi.fn(async () => {
+      throw new Error('network down')
+    })
+    await expect(withRetry(fn, { maxRetries: 2 })).rejects.toThrow('network down')
+    // first attempt + 2 retries
+    expect(fn).toHaveBeenCalledTimes(3)
+  })
+
+  it('does not retry non-retryable errors', async () => {
+    const fn = vi.fn(async () => {
+      throw new Error('validation failed')
+    })
+    await expect(withRetry(fn)).rejects.toThrow('validation failed')
+    expect(fn).toHaveBeenCalledTimes(1)
+  })
+
+  it('does not retry aborts', async () => {
+    const err = new Error('aborted')
+    err.name = 'AbortError'
+    const fn = vi.fn(async () => {
+      throw err
+    })
+    await expect(withRetry(fn)).rejects.toThrow('aborted')
+    expect(fn).toHaveBeenCalledTimes(1)
+  })
+
+  it('stops immediately when the signal is already aborted', async () => {
+    const controller = new AbortController()
+    controller.abort()
+    const fn = vi.fn(async () => {
+      throw new Error('network down')
+    })
+    await expect(withRetry(fn, { signal: controller.signal })).rejects.toThrow('network down')
+    expect(fn).toHaveBeenCalledTimes(1)
+  })
+
+  it('honors a custom retryable predicate', async () => {
+    let calls = 0
+    const fn = vi.fn(async () => {
+      calls++
+      if (calls < 2) throw new Error('please retry me')
+      return 'done'
+    })
+    await expect(withRetry(fn, { retryable: (e) => /retry me/.test(String(e)) })).resolves.toBe('done')
+    expect(fn).toHaveBeenCalledTimes(2)
+  })
+
+  it('exposes a sane default retry count', () => {
+    expect(DEFAULT_MAX_RETRIES).toBe(3)
+  })
+})

package/src/strategies/_shared/retry.ts

@@ -0,0 +1,79 @@
+/**
+ * Shared retry helpers used by upload strategies.
+ *
+ * Centralizes the abort detection, transient-error classification, and
+ * exponential-backoff loop that `multipart` grew inline and that `post` and
+ * `tus` reuse.
+ * @author wildduck2 <https://github.com/wildduck2>
+ */
+
+import { sleep } from '../../core/utils/async'
+
+/** Default number of retries (attempts after the first) for transient failures. */
+export const DEFAULT_MAX_RETRIES = 3
+
+/** Base backoff in ms; delay for retry `n` (0-indexed) is `2 ** n * BASE`. */
+const BACKOFF_BASE_MS = 500
+
+/**
+ * True when `err` represents an aborted request (either an `AbortError` or a
+ * message mentioning "abort"). Aborts are never retried.
+ */
+export function isAbort(err: unknown): boolean {
+  return err instanceof Error && (err.name === 'AbortError' || /abort/i.test(err.message))
+}
+
+/**
+ * Classify an error as a transient network failure worth retrying. Matches
+ * network/timeout wording, 5xx status codes, and common Node socket errnos.
+ */
+export function isRetryable(err: unknown): boolean {
+  const msg = err instanceof Error ? err.message : String(err)
+  return (
+    /network/i.test(msg) ||
+    /timeout/i.test(msg) ||
+    /5\d\d/.test(msg) ||
+    /ECONNRESET/i.test(msg) ||
+    /EHOSTUNREACH/i.test(msg)
+  )
+}
+
+/** Options for {@link withRetry}. */
+export type WithRetryOptions = {
+  /** Retries after the first attempt. Defaults to {@link DEFAULT_MAX_RETRIES}. */
+  maxRetries?: number
+  /**
+   * Abort signal. When aborted (or the error is an abort) the loop stops
+   * immediately and rethrows without further retries.
+   */
+  signal?: AbortSignal
+  /**
+   * Custom retry predicate. Defaults to {@link isRetryable}. Aborts are always
+   * terminal regardless of this predicate.
+   */
+  retryable?: (err: unknown) => boolean
+}
+
+/**
+ * Run `fn` and retry transient failures with exponential backoff.
+ *
+ * Aborts (signal aborted, or an abort-shaped error) short-circuit and rethrow
+ * immediately. Non-retryable errors rethrow on first failure. `fn` receives the
+ * zero-based attempt index.
+ */
+export async function withRetry<T>(fn: (attempt: number) => Promise<T>, opts: WithRetryOptions = {}): Promise<T> {
+  const maxRetries = Math.max(0, opts.maxRetries ?? DEFAULT_MAX_RETRIES)
+  const retryable = opts.retryable ?? isRetryable
+
+  let attempt = 0
+  for (;;) {
+    try {
+      return await fn(attempt)
+    } catch (err) {
+      if (opts.signal?.aborted || isAbort(err)) throw err
+      if (attempt >= maxRetries || !retryable(err)) throw err
+      await sleep(2 ** attempt * BACKOFF_BASE_MS)
+      attempt++
+    }
+  }
+}

package/src/strategies/index.ts

@@ -1,15 +1,9 @@
-/**
- * @fileoverview Public exports for upload strategies.
- *
- * Re-exports all strategy implementations and types for convenient importing.
- *
- * Available strategies:
- * - PostStrategy: Simple POST uploads (presigned forms)
- * - multipartStrategy: Chunked multipart uploads (S3-style, resumable)
- *
- * @module upload-strategies
- */
-
-export * from './multipart'
-export * from './post'
-export * from './registry'
+export type { MultipartStrategy } from './multipart'
+export { multipartStrategy } from './multipart'
+export type { PostIntent } from './post'
+export { PostStrategy } from './post'
+export type { PutIntent } from './put'
+export { PutStrategy } from './put'
+export { createStrategyRegistry } from './registry'
+export type { TusIntent } from './tus'
+export { TusStrategy } from './tus'