@gentleduck/upload 0.2.6 → 0.3.0

package/src/core/contracts/backendApi.ts

@@ -1,62 +0,0 @@
-import type { IntentMap } from './intent.types'
-import type { UploadResultBase } from './result.types'
-
-export type WithSignal = { signal?: AbortSignal }
-
-// Backend API contract (typed, injected)
-export interface UploadApi<M extends IntentMap, P extends string, R extends UploadResultBase = UploadResultBase> {
-  // Create upload intent - backend decides strategy, bucket, key
-  createIntent(
-    args: {
-      purpose: P
-      contentType: string
-      size: number
-      filename: string
-      checksum?: string
-    },
-    opts?: WithSignal,
-  ): Promise<M[keyof M]>
-
-  // Finalize upload (mark as complete in DB, return metadata)
-  complete(args: { fileId: string }, opts?: WithSignal): Promise<R>
-
-  // Get signed preview URL
-  getSignedPreviewUrl?(args: { fileId: string; key: string; purpose: P }, opts?: WithSignal): Promise<string>
-
-  /**
-   * Optional support for finding existing files by checksum for deduplication.
-   * If implemented, the upload engine will check for existing files before uploading.
-   * If a file with the same checksum exists, the upload will be skipped and the existing file will be linked.
-   */
-  findByChecksum?(args: { checksum: string; purpose: P }, opts?: WithSignal): Promise<R | null>
-
-  // Multipart-specific operations (optional, for multipart strategy)
-  multipart?: {
-    signPart(
-      args: { fileId: string; uploadId: string; partNumber: number; checksum?: string },
-      opts?: WithSignal,
-    ): Promise<{ url: string; headers?: Record<string, string> }>
-
-    completeMultipart(
-      args: { fileId: string; uploadId: string; parts: Array<{ partNumber: number; etag: string }> },
-      opts?: WithSignal,
-    ): Promise<unknown>
-
-    listParts?(
-      args: { fileId: string; uploadId: string },
-      opts?: WithSignal,
-    ): Promise<Array<{ partNumber: number; etag?: string; size?: number }>>
-
-    abort?(args: { fileId: string; uploadId: string }, opts?: WithSignal): Promise<void>
-  }
-
-  // TUS-specific operations (optional, for tus strategy)
-  tus?: {
-    create(
-      args: { fileId: string; size: number; filename: string; contentType: string },
-      opts?: WithSignal,
-    ): Promise<{ uploadUrl: string }>
-
-    getOffset(args: { uploadUrl: string }, opts?: WithSignal): Promise<{ offset: number }>
-  }
-}

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

@@ -1,23 +0,0 @@
-import type { IntentMap, StrategyKey } from './intent.types'
-
-/**
- * Registry of cursor payload types mapped by strategy name.
- *
- * A "cursor" is strategy-defined resume state (ex: multipart uploaded parts, next byte offset).
- * Use `unknown` here and define concrete cursor payload types in your app.
- *
- * @typeParam M - The intent map, used to constrain strategy keys.
- */
-export type CursorMap<M extends IntentMap> = Partial<Record<StrategyKey<M>, unknown>>
-
-/**
- * Discriminated union of all cursor variants.
- *
- * The cursor is always tagged with a `strategy` so it can be routed back to the correct strategy
- * on resume/rebind.
- *
- * @typeParam C - Cursor registry (usually {@link CursorMap}).
- */
-export type AnyCursor<C extends Record<string, unknown>> = {
-  [K in keyof C & string]: { strategy: K; value?: C[K] }
-}[keyof C & string]

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

@@ -1,67 +0,0 @@
-/**
- * File rejection reasons produced by client-side validation.
- *
- * These should be safe to show in UI.
- */
-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 interface for custom errors.
- *
- * If you want to add domain-specific fields, extend this and intersect in {@link UploadError}.
- */
-export interface UploadErrorBase {
-  /** 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.
- *
- * Keep these narrow and explicit so reducer logic can rely on `code` as a discriminant.
- */
-export type BuiltInUploadError =
-  | { 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.
- *
- * You can extend this by intersecting your own shape with {@link UploadErrorBase}
- * to add fields (example: `{ endpoint: string }`).
- */
-export type UploadError = BuiltInUploadError | (UploadErrorBase & Record<string, unknown>)
-
-/**
- * Validation rules applied on `addFiles` before an item enters the upload pipeline.
- */
-export type UploadValidationRules = {
-  /** 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[]
-}

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

@@ -1,18 +0,0 @@
-/**
- * Deterministic client-side identity for a file.
- *
- * Used to match the same file across refreshes (for rebind) and to deduplicate.
- * If you include `checksum`, it should be stable and computed consistently.
- */
-export type FileFingerprint = {
-  /** File name. */
-  name: string
-  /** File size in bytes. */
-  size: number
-  /** File MIME type. */
-  type: string
-  /** File lastModified timestamp (ms). */
-  lastModified: number
-  /** Optional checksum (example: SHA-256 hex). */
-  checksum?: string
-}

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

@@ -1,39 +0,0 @@
-/**
- * Base shape for all upload intents.
- *
- * An "intent" is data provided by your backend that tells the client how to upload a file
- * (for example: a presigned POST, presigned PUT, multipart upload IDs, part URLs, headers, etc).
- *
- * Every intent must include:
- * - `strategy`: a discriminant used to select an upload strategy implementation
- * - `fileId`: a stable backend identifier for the file being uploaded
- *
- * @typeParam K - Strategy key / discriminant string (example: `"direct" | "multipart"`).
- */
-export type IntentBase<K extends string = string> = {
-  /** Strategy name (discriminant). */
-  strategy: K
-  /** Unique backend file identifier. */
-  fileId: string
-}
-
-/**
- * Registry of intent types mapped by strategy name.
- *
- * Example:
- * ```ts
- * type MyIntents = {
- *   direct: DirectIntent
- *   multipart: MultipartIntent
- * }
- * ```
- *
- * `M[keyof M]` is used throughout the engine as the "any intent" union.
- */
-export type IntentMap = Record<string, IntentBase<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>]

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

@@ -1,11 +0,0 @@
-/**
- * Base shape for upload completion results returned by your backend.
- *
- * Extend this with any additional metadata you return (e.g. width/height, variants).
- */
-export type UploadResultBase = {
-  /** Backend file identifier. */
-  fileId: string
-  /** Storage key or path used for signed URLs. */
-  key: string
-}

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

@@ -1,45 +0,0 @@
-import type { UploadApi } from './backendApi'
-import type { CursorMap } from './cursor.types'
-import type { IntentMap } from './intent.types'
-import type { UploadResultBase } from './result.types'
-import type { UploadTransport } from './transport/transport.types'
-
-export type StrategyCtx<
-  M extends IntentMap,
-  C extends CursorMap<M>,
-  P extends string,
-  R extends UploadResultBase,
-  K extends keyof M & string,
-> = {
-  file: File
-  intent: M[K]
-  signal: AbortSignal
-  transport: UploadTransport
-  api: UploadApi<M, P, R>
-  reportProgress: (p: { uploadedBytes: number; totalBytes: number }) => void
-  readCursor: () => C[K] | undefined
-  persistCursor: (cursor: C[K] | undefined) => void
-}
-
-export type UploadStrategy<
-  M extends IntentMap,
-  C extends CursorMap<M>,
-  P extends string,
-  R extends UploadResultBase,
-  K extends keyof M & string,
-> = {
-  id: K
-  resumable: boolean
-  start(ctx: StrategyCtx<M, C, P, R, K>): Promise<void>
-}
-
-export interface StrategyRegistry<
-  M extends IntentMap,
-  C extends CursorMap<M>,
-  P extends string = string,
-  R extends UploadResultBase = UploadResultBase,
-> {
-  get<K extends keyof M & string>(id: K): UploadStrategy<M, C, P, R, K> | undefined
-  has(id: string): id is keyof M & string
-  set<K extends keyof M & string>(strategy: UploadStrategy<M, C, P, R, K>): void
-}

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

@@ -1,17 +0,0 @@
-/**
- * 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

@@ -1,45 +0,0 @@
-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/internal-events.types.ts

@@ -1,202 +0,0 @@
-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.
- * Distinct from the public event surface — these drive state transitions.
- */
-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 }
-
-/** Every upload phase; the `phase` discriminator of {@link UploadItem}. */
-export type UploadPhase =
-  | 'validating'
-  | 'creating_intent'
-  | 'ready'
-  | 'queued'
-  | 'uploading'
-  | 'paused'
-  | 'completing'
-  | 'completed'
-  | 'error'
-  | 'canceled'
-
-/** Discriminated union on `phase` describing a single upload's state. */
-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

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

@@ -1,15 +0,0 @@
-/**
- * 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
-}