@gentleduck/upload 0.2.5 → 0.3.0

package/dist/strategy.types-gg9ZStRe.d.ts

@@ -1,225 +0,0 @@
-//#region src/core/contracts/intent.types.d.ts
-/**
- * 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"`).
- */
-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.
- */
-type IntentMap = Record<string, IntentBase<string>>;
-/** Union of strategy keys for an intent map. */
-type StrategyKey<M extends IntentMap> = keyof M & string;
-/** Union of all intent variants for an intent map. */
-type AnyIntent<M extends IntentMap> = M[StrategyKey<M>];
-//#endregion
-//#region src/core/contracts/result.types.d.ts
-/**
- * Base shape for upload completion results returned by your backend.
- *
- * Extend this with any additional metadata you return (e.g. width/height, variants).
- */
-type UploadResultBase = {
-  /** Backend file identifier. */fileId: string; /** Storage key or path used for signed URLs. */
-  key: string;
-};
-//#endregion
-//#region src/core/contracts/backendApi.d.ts
-type WithSignal = {
-  signal?: AbortSignal;
-};
-interface UploadApi<M extends IntentMap, P extends string, R extends UploadResultBase = UploadResultBase> {
-  createIntent(args: {
-    purpose: P;
-    contentType: string;
-    size: number;
-    filename: string;
-    checksum?: string;
-  }, opts?: WithSignal): Promise<M[keyof M]>;
-  complete(args: {
-    fileId: string;
-  }, opts?: WithSignal): Promise<R>;
-  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?: {
-    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?: {
-    create(args: {
-      fileId: string;
-      size: number;
-      filename: string;
-      contentType: string;
-    }, opts?: WithSignal): Promise<{
-      uploadUrl: string;
-    }>;
-    getOffset(args: {
-      uploadUrl: string;
-    }, opts?: WithSignal): Promise<{
-      offset: number;
-    }>;
-  };
-}
-//#endregion
-//#region src/core/contracts/cursor.types.d.ts
-/**
- * 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.
- */
-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}).
- */
-type AnyCursor<C extends Record<string, unknown>> = { [K in keyof C & string]: {
-  strategy: K;
-  value?: C[K];
-} }[keyof C & string];
-//#endregion
-//#region src/core/contracts/transport/transport.types.d.ts
-/**
- * Abstraction layer for network operations.
- * Allows switching between XHR (browser) or other implementations (testing/Node).
- *
- * Designed to support:
- * - Deterministic progress tracking (requires XHR in browsers)
- * - Cancellation via AbortSignal
- * - Header parsing (ETag extraction)
- */
-interface UploadTransport {
-  /**
-   * Performs an HTTP PUT request (typically for S3 signed URLs).
-   */
-  put(args: {
-    url: string;
-    body: Blob;
-    headers?: Record<string, string>;
-    signal: AbortSignal;
-    onProgress?: (u: number, t: number) => void;
-  }): Promise<{
-    etag?: string;
-    headers?: Record<string, string>;
-  }>;
-  /**
-   * Performs an HTTP POST multipart request.
-   */
-  postForm(args: {
-    url: string;
-    fields: Record<string, string>;
-    file: File | Blob;
-    filename?: string;
-    signal: AbortSignal;
-    onProgress?: (uploadedBytes: number, totalBytes: number) => void;
-  }): Promise<{
-    etag?: string;
-    headers?: Record<string, string>;
-  }>;
-  /**
-   * Performs an HTTP request.
-   */
-  patch(args: {
-    url: string;
-    body: Blob | ArrayBuffer;
-    headers?: Record<string, string>;
-    signal: AbortSignal;
-    onProgress?: (u: number, t: number) => void;
-  }): Promise<{
-    headers?: Record<string, string>;
-  }>;
-}
-//#endregion
-//#region src/core/contracts/strategy.types.d.ts
-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;
-};
-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>;
-};
-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;
-}
-//#endregion
-export { AnyCursor as a, WithSignal as c, IntentBase as d, IntentMap as f, UploadTransport as i, UploadResultBase as l, StrategyRegistry as n, CursorMap as o, StrategyKey as p, UploadStrategy as r, UploadApi as s, StrategyCtx as t, AnyIntent as u };

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

@@ -1,77 +0,0 @@
-import type { UploadError, UploadValidationRules } from '../contracts'
-import {
-  DEFAULT_MAX_ATTEMPTS,
-  DEFAULT_MAX_CONCURRENT_UPLOADS,
-  DEFAULT_MAX_ITEMS,
-  DEFAULT_PROGRESS_THROTTLE_MS,
-} from '../utils/constants'
-import type { RetryDecision } from './retry.types'
-
-/**
- * Global upload engine configuration.
- *
- * @typeParam P - Union of allowed `purpose` strings for your app.
- */
-export type UploadConfig<P extends string> = {
-  /** Maximum concurrent uploads. */
-  maxConcurrentUploads: number
-
-  /**
-   * Auto-start uploads for specific purposes.
-   * - Array form: only those purposes auto-start
-   * - Function form: dynamic decision per purpose
-   */
-  autoStart?: readonly P[] | ((purpose: P) => boolean)
-
-  /** Progress event throttle in milliseconds. */
-  progressThrottleMs: number
-
-  /** Validation rules keyed by purpose. */
-  validation: Partial<Record<P, UploadValidationRules>>
-
-  /** Maximum number of retry attempts (per item / per phase depending on implementation). */
-  maxAttempts: number
-
-  /**
-   * Retry policy.
-   * Called whenever a phase fails and the engine needs a decision.
-   */
-  retryPolicy?: (ctx: { phase: 'intent' | 'upload' | 'complete'; attempt: number; error: UploadError }) => RetryDecision
-
-  /**
-   * Maximum number of items to keep in state.
-   * When exceeded, oldest completed/canceled items are removed automatically.
-   *
-   * Set to `undefined` for no limit (not recommended for long-running apps).
-   * Default often: `100`.
-   */
-  maxItems: number
-
-  /**
-   * Automatically remove completed items after this many milliseconds.
-   * Set to `undefined` to keep completed items indefinitely.
-   */
-  completedItemTTL?: number
-}
-
-/**
- * Config input shape accepted by store creation.
- * All fields are optional; defaults are applied by {@link resolveUploadConfig}.
- */
-export type UploadConfigInput<P extends string> = Partial<UploadConfig<P>>
-
-/**
- * Normalizes user config by applying sensible defaults.
- */
-export function resolveUploadConfig<P extends string>(input?: UploadConfigInput<P>): UploadConfig<P> {
-  return {
-    maxConcurrentUploads: Math.max(1, input?.maxConcurrentUploads ?? DEFAULT_MAX_CONCURRENT_UPLOADS),
-    autoStart: input?.autoStart,
-    progressThrottleMs: Math.max(0, input?.progressThrottleMs ?? DEFAULT_PROGRESS_THROTTLE_MS),
-    validation: input?.validation ?? {},
-    maxAttempts: Math.max(1, input?.maxAttempts ?? DEFAULT_MAX_ATTEMPTS),
-    retryPolicy: input?.retryPolicy,
-    maxItems: Math.max(1, input?.maxItems ?? DEFAULT_MAX_ITEMS),
-    completedItemTTL: input?.completedItemTTL,
-  }
-}

package/src/core/client/index.ts

@@ -1,4 +0,0 @@
-export * from './config.types'
-export * from './plugins.types'
-export * from './retry.types'
-export * from './uploadClient'

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

@@ -1,46 +0,0 @@
-import type { CursorMap, IntentMap, UploadResultBase } from '../contracts'
-import type { InternalEvent } from '../engine/internal-events.types'
-import type { UploadStore } from '../engine/store'
-
-/**
- * Optional hooks for observing internal behavior.
- *
- * Use these for diagnostics, analytics, logging, or devtools.
- */
-export type UploadHooks<
-  M extends IntentMap,
-  C extends CursorMap<M>,
-  P extends string,
-  R extends UploadResultBase = UploadResultBase,
-> = {
-  /**
-   * Called after internal events are processed (depending on your runtime wiring).
-   * Prefer this over subscribing to public events if you need full fidelity.
-   */
-  onInternalEvent?: (
-    event: InternalEvent<M, C, P, R>,
-    state: import('../engine/reducer').UploadState<M, C, P, R>,
-  ) => void
-}
-
-/**
- * Store plugins.
- *
- * Plugins can subscribe to store events and dispatch commands.
- * They should not reach into internal state mutably.
- */
-export type UploadPlugin<
-  M extends IntentMap,
-  C extends CursorMap<M>,
-  P extends string,
-  R extends UploadResultBase = UploadResultBase,
-> = {
-  /** Plugin name (for debugging). */
-  name: string
-
-  /**
-   * Setup callback called once when the store is created.
-   * The plugin can register event listeners and drive behavior.
-   */
-  setup: (ctx: Pick<UploadStore<M, C, P, R>, 'on' | 'dispatch' | 'getSnapshot'>) => void
-}

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

@@ -1,6 +0,0 @@
-/**
- * Output of the retry policy.
- *
- * `delayMs` should be a backoff delay before re-attempting the failed step.
- */
-export type RetryDecision = { retryable: false } | { retryable: true; delayMs: number }

package/src/core/client/uploadClient.ts

@@ -1,19 +0,0 @@
-import type { CursorMap, IntentMap, UploadResultBase } from '../contracts'
-import type { StoreOptions, UploadStore } from '../engine/store'
-import { createUploadStore } from '../engine/store'
-
-export type UploadClient<
-  M extends IntentMap,
-  C extends CursorMap<M>,
-  P extends string,
-  R extends UploadResultBase = UploadResultBase,
-> = UploadStore<M, C, P, R>
-
-export function createUploadClient<
-  M extends IntentMap,
-  C extends CursorMap<M>,
-  P extends string,
-  R extends UploadResultBase = UploadResultBase,
->(opts: StoreOptions<M, C, P, R>): UploadClient<M, C, P, R> {
-  return createUploadStore(opts)
-}

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 }