@gentleduck/upload 0.2.5 → 0.2.6

package/src/react/upload-provider.tsx

@@ -1,48 +1,14 @@
 'use client'
 
-/**
- * @fileoverview React context provider for the upload store.
- *
- * Provides the upload store instance to all child components via React Context.
- * This allows components to access the store without prop drilling.
- *
- * @module upload-provider
- */
-
 import { createContext, type ReactNode, useContext } from 'react'
 import { type CursorMap, type IntentMap, isRecord, type UploadResultBase } from '../core'
 import type { UploadStore } from '../core/engine/store'
 
-/**
- * React context for the upload store.
- * Initialized as null and must be provided via UploadProvider.
- *
- * Note: Context cannot be generic at the type level in React, so we use a base type.
- * The useUploadStore hook provides type safety through type assertion which is safe
- * because the provider ensures the correct type is stored.
- */
+// React Context can't carry generics, so the runtime value is `unknown`; the
+// hooks below re-narrow with `isUploadStore`.
 const UploadContext = createContext<unknown | null>(null)
 
-/**
- * Provider component that makes the upload store available to child components.
- *
- * @template M - Intent map type
- * @template C - Cursor map type
- * @template P - Purpose type
- *
- * @param props - Provider props
- * @param props.store - Upload store instance to provide
- * @param props.children - Child components that can access the store
- *
- * @returns {JSX.Element} Context provider wrapping children
- *
- * @example
- * ```tsx
- * <UploadProvider store={store}>
- *   <UploadDropzone purpose="avatar" />
- * </UploadProvider>
- * ```
- */
+/** Provides an upload store to descendants. */
 export function UploadProvider<
   M extends IntentMap,
   C extends CursorMap<M>,
@@ -53,11 +19,9 @@ export function UploadProvider<
 }
 
 /**
- * Hook to access the upload store from React context when present.
- *
- * Some higher-level hooks support either an explicit store argument or context.
- * They use this helper so the context read stays unconditional without throwing
- * when a caller intentionally passes a store instance.
+ * Read the upload store from context if provided. Returns `null` outside a
+ * provider so higher-level hooks can keep their context read unconditional
+ * while still accepting an explicit store argument.
  */
 export function useOptionalUploadStore<
   M extends IntentMap,
@@ -77,22 +41,7 @@ export function useOptionalUploadStore<
   return store
 }
 
-/**
- * Hook to access the upload store from React context.
- *
- * @template M - Intent map type
- * @template C - Cursor map type
- * @template P - Purpose type
- *
- * @returns {UploadStore<M, C, P>} The upload store instance
- * @throws {Error} If called outside of UploadProvider
- *
- * @example
- * ```tsx
- * const store = useUploadStore()
- * const snapshot = store.getSnapshot()
- * ```
- */
+/** Read the upload store from context. Throws when called outside `UploadProvider`. */
 export function useUploadStore<
   M extends IntentMap,
   C extends CursorMap<M>,

package/src/react/uploader.types.ts

@@ -0,0 +1,83 @@
+import type { Contracts, Engine } from '../core'
+import type { Store } from '../core/engine/store'
+
+/**
+ * React `useUploader` surface types.
+ *
+ * Houses the public typings consumed by the React hooks so generated
+ * `.d.ts` files do not leak internal generic names.
+ *
+ * @author wildduck2 <https://github.com/wildduck2>
+ */
+export namespace Uploader {
+  /**
+   * Pick the variant of `Engine.Item` matching a phase.
+   *
+   * @template Phase Phase literal to filter on.
+   * @returns The item variant whose `phase` matches `Phase`.
+   * @author wildduck2 <https://github.com/wildduck2>
+   */
+  export type PickItemsByPhase<Phase extends Engine.Phase> = Extract<
+    Engine.Item<Contracts.IntentMap, Contracts.CursorMap<Contracts.IntentMap>, string, Contracts.IResultBase>,
+    { phase: Phase }
+  >
+
+  /**
+   * Object returned by `useUploader`.
+   *
+   * @template M Intent map.
+   * @template C Cursor map.
+   * @template P Purpose union.
+   * @template R Backend result shape.
+   * @author wildduck2 <https://github.com/wildduck2>
+   */
+  export interface IUploader<
+    M extends Contracts.IntentMap,
+    C extends Contracts.CursorMap<M>,
+    P extends string,
+    R extends Contracts.IResultBase,
+  > {
+    items: Engine.Item<M, C, P, R>[]
+    /**
+     * Items grouped by phase. `Partial<Record<Engine.Phase, ...>>` so consumers
+     * get autocomplete for the eleven known phases and a missing group reads
+     * as `undefined`.
+     */
+    byPhase: Partial<Record<Engine.Phase, Engine.Item<M, C, P, R>[]>>
+    dispatch: (cmd: Engine.Command<P>) => void
+    on: <K extends keyof Engine.EventMap<M, C, P, R> & string>(
+      type: K,
+      cb: (payload: Engine.EventMap<M, C, P, R>[K]) => void,
+    ) => () => void
+    off: <K extends keyof Engine.EventMap<M, C, P, R> & string>(
+      type: K,
+      cb: (payload: Engine.EventMap<M, C, P, R>[K]) => void,
+    ) => void
+    uploading: Engine.Item<M, C, P, R>[]
+    paused: Engine.Item<M, C, P, R>[]
+    completed: Engine.Item<M, C, P, R>[]
+    failed: Engine.Item<M, C, P, R>[]
+    ready: Engine.Item<M, C, P, R>[]
+  }
+
+  /**
+   * Imperative action surface returned by `useUploaderActions`.
+   *
+   * Declared explicitly so generated `.d.ts` files do not leak internal
+   * generic names.
+   *
+   * @template M Intent map.
+   * @template C Cursor map.
+   * @template P Purpose union.
+   * @template R Backend result shape; defaults to `Contracts.IResultBase`.
+   * @author wildduck2 <https://github.com/wildduck2>
+   */
+  export type IActions<
+    M extends Contracts.IntentMap,
+    C extends Contracts.CursorMap<M>,
+    P extends string,
+    R extends Contracts.IResultBase = Contracts.IResultBase,
+  > = Pick<Store.IUploadStore<M, C, P, R>, 'dispatch' | 'on'> & {
+    store: Store.IUploadStore<M, C, P, R>
+  }
+}

package/src/react/use-uploader.tsx

@@ -47,11 +47,8 @@ type Uploader<M extends IntentMap, C extends CursorMap<M>, P extends string, R e
 }
 
 /**
- * Stable action surface for React consumers that need imperative store access.
- *
- * 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)`.
+ * Imperative action surface. Declared explicitly (not inferred) so generated
+ * .d.ts files do not leak internal generic names created by `store.on.bind(store)`.
  */
 export type UploaderActions<
   M extends IntentMap,

package/src/strategies/multipart/index.ts

@@ -1,6 +1,7 @@
 /**
- * Multipart strategy implementation (S3/MinIO style).
- * Signs each part on demand (signPart), uploads via PUT, then completes with ETags.
+ * S3/MinIO-style multipart strategy: sign each part on demand via `signPart`,
+ * PUT, then finalize with `completeMultipart` using collected ETags. Resumable —
+ * persists ETags in the cursor and skips already-completed sessions.
  */
 
 import type { CursorMap, IntentMap, UploadResultBase, UploadStrategy } from '../../core/contracts'
@@ -58,21 +59,19 @@ export function multipartStrategy<
       const totalBytes = ctx.file.size
       const partSize = Math.max(1, intent.partSize)
 
-      // Trust backend partCount if provided (important for maxParts rules)
+      // Trust backend `partCount` when provided — S3-style backends enforce a maxParts rule.
       const totalParts = Math.max(1, intent.partCount ?? Math.ceil(totalBytes / partSize))
 
-      // Restore cursor
       const cursor = ctx.readCursor()
       const done = new Map<number, { etag: string; size: number }>()
       if (cursor?.done) {
         for (const p of cursor.done) done.set(p.partNumber, { etag: p.etag, size: p.size })
       }
 
-      // If we already completed the multipart session in a previous run, do not re-complete.
-      // (The store will still run its generic finalization step.)
+      // Skip re-completing if a previous run already finalized the multipart
+      // session. The store still runs its generic finalization step.
       const alreadyCompleted = cursor?.completed === true
 
-      // Progress
       const inflightBytes = new Map<number, number>()
       let finishedBytes = 0
       for (const v of done.values()) finishedBytes += v.size
@@ -83,7 +82,6 @@ export function multipartStrategy<
         ctx.reportProgress({ uploadedBytes: finishedBytes + inflight, totalBytes })
       }
 
-      // Build queue
       const partsToUpload: Array<{ partNumber: number; start: number; end: number }> = []
       for (let partNumber = 1; partNumber <= totalParts; partNumber++) {
         if (done.has(partNumber)) continue
@@ -102,11 +100,10 @@ export function multipartStrategy<
       const running = new Set<Promise<void>>()
 
       const getSignedPart = async (partNumber: number) => {
-        // Legacy fast path: intent.parts provided
+        // Legacy fast path: backend pre-signed all parts in `intent.parts`.
         const fromIntent = intent.parts?.find((x) => x.partNumber === partNumber)
         if (fromIntent) return fromIntent
 
-        // Normal path: ask backend for this part url
         if (!ctx.api.multipart?.signPart) {
           throw new Error(
             'multipart.signPart is missing in UploadApi. Implement it to call your backend sign-part endpoint.',
@@ -167,7 +164,7 @@ export function multipartStrategy<
 
           if (ctx.signal?.aborted || isAbort(err)) throw err
 
-          // basic retry for network-ish failures
+          // Retry transient network errors with exponential backoff.
           if (retryCount < maxRetries) {
             const msg = err instanceof Error ? err.message : String(err)
             const retryable =
@@ -229,7 +226,7 @@ export function multipartStrategy<
           { signal: ctx.signal },
         )
 
-        // Persist "completed" marker so resume doesn't re-complete.
+        // Persist `completed: true` so resume after this point does not re-call `completeMultipart`.
         const snapshot: MultipartCursor = {
           done: Array.from(done.entries())
             .map(([partNumber, v]) => ({ partNumber, etag: v.etag, size: v.size }))

package/src/strategies/post/index.ts

@@ -1,50 +1,26 @@
 /**
- * @fileoverview POST strategy implementation for simple file uploads.
- *
- * Implements the presigned POST upload strategy, suitable for:
- * - Small to medium files (< 100MB typically)
- * - Simple uploads without resume capability
- * - Direct form-based uploads to S3 or similar storage
- *
- * The strategy uses multipart/form-data POST requests with presigned
- * form fields provided by the backend. This is the simplest upload
- * method and doesn't support resumable uploads.
- *
- * @module upload-strategies/post
+ * Presigned-POST strategy: a single `multipart/form-data` POST with
+ * server-provided fields. Non-resumable; suitable for small/medium files.
  */
 
 import type { CursorMap, IntentMap, UploadResultBase, UploadStrategy } from '../../core/contracts'
 
-// ============================================================================
-// POST INTENT TYPE
-// ============================================================================
-
 export type PostIntent = {
-  /** Strategy identifier - must be 'post' */
   strategy: 'post'
-  /** Backend file identifier */
   fileId: string
-  /** Presigned POST URL (form action) */
+  /** Presigned POST URL (form action). */
   url: string
-  /** Form fields to include before the file */
+  /** Form fields to include before the file. */
   fields: Record<string, string>
-  /** Optional expiration timestamp for the presigned URL */
+  /** Optional expiry of the presigned URL. */
   expiresAt?: string
 }
 
-// ============================================================================
-// POST CURSOR TYPE
-// ============================================================================
-
 export type PostCursor = {
-  /** Bytes uploaded (for progress display only) */
+  /** Bytes uploaded — progress display only; not used for resume. */
   uploadedBytes: number
 }
 
-// ============================================================================
-// POST STRATEGY
-// ============================================================================
-
 export function PostStrategy<
   M extends IntentMap & { post: PostIntent },
   C extends CursorMap<M> & { post?: PostCursor },
@@ -52,38 +28,22 @@ export function PostStrategy<
   R extends UploadResultBase = UploadResultBase,
 >(): UploadStrategy<M, C, P, R, 'post'> {
   return {
-    /** Strategy identifier */
     id: 'post',
-
-    /** POST uploads are not resumable */
     resumable: false,
 
-    /**
-     * Execute the POST upload.
-     *
-     * @param ctx - Strategy context
-     * @throws Error if intent is missing URL
-     */
     async start(ctx) {
       const intent = ctx.intent
 
-      // Validate intent has required URL
       if (!intent.url) {
         throw new Error('Direct strategy: intent missing url/uploadUrl')
       }
 
-      // Upload using form POST
       await ctx.transport.postForm({
         url: intent.url,
         file: ctx.file,
         fields: intent.fields,
         filename: ctx.file.name,
         signal: ctx.signal,
-        /**
-         * Report progress during upload.
-         * @param uploadedBytes - Bytes uploaded so far
-         * @param totalBytes - Total file size
-         */
         onProgress(uploadedBytes, totalBytes) {
           ctx.reportProgress({ uploadedBytes, totalBytes })
         },