@gentleduck/upload 0.2.1

package/src/core/engine/store/handlers/create-intent.ts

@@ -0,0 +1,76 @@
+import type { CursorMap, IntentMap, UploadError, UploadResultBase } from '../../../contracts'
+import { validateIntent } from '../../validation'
+import { normalizeError, retryDecision, sleep } from '../store.libs'
+import type { StoreRuntime } from '../store.types'
+
+export async function createIntent<
+  M extends IntentMap,
+  C extends CursorMap<M>,
+  P extends string,
+  R extends UploadResultBase,
+>(rt: StoreRuntime<M, C, P, R>, localId: string) {
+  const item = rt.state.items.get(localId)
+  if (!item || item.phase !== 'creating_intent') return
+  if (rt.inflightIntents.has(localId)) return
+
+  const controller = new AbortController()
+  rt.inflightIntents.set(localId, controller)
+
+  try {
+    const intent = await rt.opts.api.createIntent(
+      {
+        purpose: item.purpose,
+        contentType: item.file.type || 'application/octet-stream',
+        size: item.file.size,
+        filename: item.file.name,
+        checksum: item.fingerprint.checksum,
+      },
+      { signal: controller.signal },
+    )
+
+    rt.inflightIntents.delete(localId)
+
+    // Item might have been canceled while intent was creating
+    const current = rt.state.items.get(localId)
+    if (!current || current.phase !== 'creating_intent') return
+
+    // Validate intent from backend
+    const intentError = validateIntent(intent, intent.strategy)
+    if (intentError) {
+      const error: UploadError = {
+        code: 'validation_failed',
+        message: `Invalid intent from backend: ${intentError.message}`,
+        cause: intentError,
+        retryable: false,
+      }
+      rt.applyInternal({ type: 'intent.failed', localId, error, retryable: false })
+      return
+    }
+
+    rt.applyInternal({ type: 'intent.ok', localId, intent })
+  } catch (err: unknown) {
+    rt.inflightIntents.delete(localId)
+
+    if (controller.signal.aborted) {
+      // canceled
+      return
+    }
+
+    const error = normalizeError(err, rt.opts.errorNormalizer)
+    const errorWithContext: UploadError = {
+      ...error,
+      message: `${error.message} (file: ${item.fingerprint.name}, size: ${item.file.size} bytes, purpose: ${item.purpose})`,
+    }
+
+    const decision = retryDecision(rt.opts.config, { phase: 'intent', attempt: item.attempt, error: errorWithContext })
+
+    rt.applyInternal({ type: 'intent.failed', localId, error: errorWithContext, retryable: decision.retryable })
+
+    if (decision.retryable && decision.delayMs !== undefined) {
+      rt.enqueueEffect(async () => {
+        await sleep(decision.delayMs)
+        rt.dispatch({ type: 'retry', localId })
+      })
+    }
+  }
+}

package/src/core/engine/store/handlers/finalize.ts

@@ -0,0 +1,59 @@
+import type { CursorMap, IntentMap, UploadError, UploadResultBase } from '../../../contracts'
+import { hasIntent, normalizeError, retryDecision, sleep } from '../store.libs'
+import type { StoreRuntime } from '../store.types'
+
+export async function finalizeUpload<
+  M extends IntentMap,
+  C extends CursorMap<M>,
+  P extends string,
+  R extends UploadResultBase,
+>(rt: StoreRuntime<M, C, P, R>, localId: string) {
+  const item = rt.state.items.get(localId)
+  if (!item || item.phase !== 'completing') return
+  if (rt.inflightCompletes.has(localId)) return
+
+  const controller = new AbortController()
+  rt.inflightCompletes.set(localId, controller)
+
+  try {
+    // Final commit step (backend should verify upload, then mark/commit it).
+    // Strategy-specific API calls (multipart/tus) must happen inside the strategy itself.
+    const result = await rt.opts.api.complete({ fileId: item.intent.fileId }, { signal: controller.signal })
+    rt.inflightCompletes.delete(localId)
+
+    // Item might have been canceled
+    const current = rt.state.items.get(localId)
+    if (!current || current.phase !== 'completing') return
+
+    rt.applyInternal({ type: 'complete.ok', localId, result })
+  } catch (err: unknown) {
+    rt.inflightCompletes.delete(localId)
+
+    if (controller.signal.aborted) return
+
+    const error = normalizeError(err, rt.opts.errorNormalizer)
+
+    const itemForContext = rt.state.items.get(localId)
+    const errorWithContext: UploadError = itemForContext
+      ? {
+          ...error,
+          message: `${error.message} (file: ${itemForContext.fingerprint.name}, fileId: ${
+            (hasIntent(itemForContext) && itemForContext.intent?.fileId) ?? 'unknown'
+          })`,
+        }
+      : error
+
+    // Use actual attempt number from item state, defaulting to 1
+    const attempt = itemForContext && 'attempt' in itemForContext ? (itemForContext.attempt ?? 1) : 1
+    const decision = retryDecision(rt.opts.config, { phase: 'complete', attempt, error: errorWithContext })
+
+    rt.applyInternal({ type: 'complete.failed', localId, error: errorWithContext, retryable: decision.retryable })
+
+    if (decision.retryable && decision.delayMs !== undefined) {
+      rt.enqueueEffect(async () => {
+        await sleep(decision.delayMs)
+        rt.dispatch({ type: 'retry', localId })
+      })
+    }
+  }
+}

package/src/core/engine/store/handlers/index.ts

@@ -0,0 +1,7 @@
+export * from './add-file'
+export * from './cancel'
+export * from './clean-up'
+export * from './create-intent'
+export * from './finalize'
+export * from './pause'
+export * from './run-upload'

package/src/core/engine/store/handlers/pause.ts

@@ -0,0 +1,16 @@
+import type { CursorMap, IntentMap, UploadResultBase } from '../../../contracts'
+import type { StoreRuntime } from '../store.types'
+
+export function handlePause<M extends IntentMap, C extends CursorMap<M>, P extends string, R extends UploadResultBase>(
+  rt: StoreRuntime<M, C, P, R>,
+  localId: string,
+) {
+  const inflight = rt.inflightUploads.get(localId)
+  if (inflight) {
+    inflight.mode = 'pause'
+    inflight.controller.abort({ reason: 'pause' })
+    return
+  }
+
+  // If not inflight but queued, reducer already reverts it to ready.
+}

package/src/core/engine/store/handlers/run-upload.ts

@@ -0,0 +1,192 @@
+import type { AnyCursor, CursorMap, IntentMap, UploadError, UploadResultBase } from '../../../contracts'
+import { hasCursor, hasFile, hasIntent, normalizeError, retryDecision, sleep } from '../store.libs'
+import type { StoreRuntime } from '../store.types'
+
+export async function runUpload<
+  M extends IntentMap,
+  C extends CursorMap<M>,
+  P extends string,
+  R extends UploadResultBase,
+>(rt: StoreRuntime<M, C, P, R>, localId: string) {
+  const item = rt.state.items.get(localId)
+
+  // If the state moved on (or we never had a valid upload), drop any inflight entry.
+  if (!item || item.phase !== 'uploading' || !hasIntent(item)) {
+    rt.inflightUploads.delete(localId)
+    return
+  }
+
+  let inflight = rt.inflightUploads.get(localId)
+  if (!inflight) {
+    inflight = { controller: new AbortController(), mode: 'normal', started: false }
+    rt.inflightUploads.set(localId, inflight)
+  }
+
+  if (inflight.started) return
+  inflight.started = true
+
+  const controller = inflight.controller
+
+  const applyCanceled = () => {
+    const current = rt.state.items.get(localId)
+    if (!current || current.phase === 'canceled') return
+    rt.applyInternal({ type: 'canceled', localId, canceledAt: Date.now() })
+  }
+
+  const applyPaused = (cursor: AnyCursor<C>) => {
+    const current = rt.state.items.get(localId)
+    if (!current || current.phase === 'paused') return
+    rt.applyInternal({ type: 'paused', localId, cursor, pausedAt: Date.now() })
+  }
+
+  // If paused/canceled before the request begins, complete it immediately.
+  if (controller.signal.aborted) {
+    rt.inflightUploads.delete(localId)
+
+    if (inflight.mode === 'pause') {
+      const cur = rt.state.items.get(localId)
+      let strategy: (keyof M & string) | undefined
+      if (item && hasIntent(item)) {
+        strategy = item.intent.strategy
+      }
+
+      const cursor =
+        (cur && hasCursor(cur) ? cur.cursor : undefined) || (strategy ? { strategy, value: undefined } : undefined)
+
+      if (cursor) applyPaused(cursor)
+      return
+    }
+
+    if (inflight.mode === 'cancel') {
+      applyCanceled()
+      return
+    }
+
+    return
+  }
+
+  const strategyId = item.intent.strategy
+  if (!rt.opts.strategies.has(strategyId)) {
+    rt.inflightUploads.delete(localId)
+    const error: UploadError = {
+      code: 'strategy_missing',
+      message: `Strategy not found: ${strategyId}`,
+      strategy: String(strategyId),
+      retryable: false,
+    }
+    rt.applyInternal({ type: 'upload.failed', localId, error, retryable: false })
+    return
+  }
+
+  const strategy = rt.opts.strategies.get(strategyId)
+
+  if (!strategy) {
+    rt.inflightUploads.delete(localId)
+    const error: UploadError = {
+      code: 'strategy_missing',
+      message: `Strategy not found: ${item.intent.strategy}`,
+      strategy: String(item.intent.strategy),
+      retryable: false,
+    }
+    rt.applyInternal({ type: 'upload.failed', localId, error, retryable: false })
+    return
+  }
+
+  // Throttle progress events
+  let lastEmit = 0
+  const progressThrottle = rt.opts.config.progressThrottleMs
+
+  try {
+    await strategy.start({
+      file: item.file,
+      intent: item.intent,
+      signal: controller.signal,
+      transport: rt.opts.transport,
+      api: rt.opts.api,
+
+      readCursor: () => {
+        const cur = rt.state.items.get(localId)
+        if (!cur || !hasCursor(cur) || !cur.cursor) return undefined
+        if (cur.cursor.strategy !== strategyId) return undefined
+        return cur.cursor.value
+      },
+
+      persistCursor: (cursorValue) => {
+        const tagged: AnyCursor<C> = { strategy: strategyId, value: cursorValue }
+        rt.applyInternal({ type: 'cursor.updated', localId, cursor: tagged })
+      },
+
+      reportProgress: (p) => {
+        const now = Date.now()
+        if (now - lastEmit < progressThrottle) return
+
+        rt.applyInternal({
+          type: 'upload.progress',
+          localId,
+          uploadedBytes: p.uploadedBytes,
+          totalBytes: p.totalBytes,
+        })
+
+        lastEmit = now
+      },
+    })
+
+    rt.inflightUploads.delete(localId)
+
+    if (inflight?.mode === 'cancel') {
+      applyCanceled()
+      return
+    }
+    if (controller.signal.aborted && inflight?.mode === 'pause') {
+      // Paused at the end; reducer expects cursor - if not present, keep last-known or synthesize.
+      const cur = rt.state.items.get(localId)
+      const cursor = (cur && hasCursor(cur) ? cur.cursor : undefined) || { strategy: strategyId, value: undefined }
+      applyPaused(cursor)
+      return
+    }
+
+    // Normal completion -> completing
+    rt.applyInternal({ type: 'upload.ok', localId })
+    // finalizeUpload scheduled by scheduleWork() via completing phase
+  } catch (err: unknown) {
+    rt.inflightUploads.delete(localId)
+
+    if (controller.signal.aborted) {
+      if (inflight?.mode === 'pause') {
+        const cur = rt.state.items.get(localId)
+        const cursor = (cur && hasCursor(cur) ? cur.cursor : undefined) || { strategy: strategyId, value: undefined }
+        applyPaused(cursor)
+        return
+      }
+
+      if (inflight?.mode === 'cancel') {
+        applyCanceled()
+        return
+      }
+
+      // Unknown abort -> treat as cancel
+      applyCanceled()
+      return
+    }
+
+    const error = normalizeError(err, rt.opts.errorNormalizer)
+    const itemForContext = rt.state.items.get(localId)
+    const errorWithContext: UploadError = itemForContext
+      ? {
+          ...error,
+          message: `${error.message} (file: ${itemForContext.fingerprint.name}, size: ${
+            (hasFile(itemForContext) && itemForContext.file?.size) ?? 0
+          } bytes, phase: ${itemForContext.phase})`,
+        }
+      : error
+    const decision = retryDecision(rt.opts.config, { phase: 'upload', attempt: 1, error: errorWithContext })
+    rt.applyInternal({ type: 'upload.failed', localId, error: errorWithContext, retryable: decision.retryable })
+
+    if (decision.retryable && decision.delayMs !== undefined) {
+      rt.enqueueEffect(async () => {
+        await sleep(decision.delayMs)
+        rt.dispatch({ type: 'retry', localId })
+      })
+    }
+  }
+}

package/src/core/engine/store/index.ts

@@ -0,0 +1,123 @@
+import type { CursorMap, IntentMap, UploadResultBase } from '../../contracts'
+import type { UploadOutcome } from '../outcome.types'
+import { dispatch as internalDispatch } from './store.dispatch'
+import { createStoreRuntime } from './store.runtime'
+import type { StoreOptions, StoreRuntime, UploadStore } from './store.types'
+
+// TODO: add option for debug mode
+
+/**
+ * Creates an upload store instance.
+ *
+ * This is the main runtime object you interact with from the outside:
+ * - dispatch user commands (add files, start, pause, cancel, resume)
+ * - subscribe to state changes (for UI rendering)
+ * - subscribe to typed events (for progress, errors, and lifecycle)
+ *
+ * Plugins are initialized once during construction and receive a minimal store
+ * proxy (events, dispatch, snapshot access) to avoid tight coupling.
+ *
+ * @template M - Intent map type (keyed by strategy id)
+ * @template C - Cursor map type (keyed by strategy id)
+ * @template P - Purpose string union type
+ *
+ * @param opts - Store options (config, backend API, strategies, transport, hooks)
+ * @returns A configured {@link UploadStore} instance.
+ */
+export function createUploadStore<
+  M extends IntentMap,
+  C extends CursorMap<M>,
+  P extends string,
+  R extends UploadResultBase = UploadResultBase,
+>(opts: StoreOptions<M, C, P, R>): UploadStore<M, C, P, R> {
+  const rt = createStoreRuntime(opts)
+
+  // Wire dispatch for handlers that need retries without import cycles.
+  rt.dispatch = (cmd) => internalDispatch(rt, cmd)
+
+  const storeProxy: Pick<UploadStore<M, C, P, R>, 'on' | 'off' | 'dispatch' | 'getSnapshot'> = {
+    on: rt.emitter.on.bind(rt.emitter),
+    off: rt.emitter.off.bind(rt.emitter),
+    dispatch: rt.dispatch,
+    getSnapshot: () => rt.state,
+  }
+
+  // Plugin setup
+  for (const plugin of opts.plugins || []) {
+    try {
+      plugin.setup(storeProxy)
+    } catch (err) {
+      if (typeof window !== 'undefined' && process.env.NODE_ENV === 'development') {
+        console.error(`[UploadEngine] Plugin "${plugin.name}" failed to setup:`, err)
+      }
+    }
+  }
+
+  return {
+    ...storeProxy,
+    subscribe: (listener) => {
+      rt.listeners.add(listener)
+      return () => rt.listeners.delete(listener)
+    },
+    waitFor(localIds) {
+      return waitForOutcomes(rt, localIds)
+    },
+  }
+}
+
+export * from './store.types'
+
+function waitForOutcomes<M extends IntentMap, C extends CursorMap<M>, P extends string, R extends UploadResultBase>(
+  rt: StoreRuntime<M, C, P, R>,
+  localIds: string[],
+): Promise<Array<UploadOutcome<R>>> {
+  if (localIds.length === 0) return Promise.resolve([])
+
+  const pending = new Set(localIds)
+  const outcomes = new Map<string, UploadOutcome<R>>()
+
+  const update = () => {
+    for (const id of pending) {
+      const item = rt.state.items.get(id)
+      if (!item) {
+        outcomes.set(id, { localId: id, status: 'missing' })
+        pending.delete(id)
+        continue
+      }
+
+      if (item.phase === 'completed') {
+        outcomes.set(id, { localId: id, status: 'completed', completedBy: item.completedBy, result: item.result })
+        pending.delete(id)
+        continue
+      }
+
+      if (item.phase === 'error') {
+        outcomes.set(id, { localId: id, status: 'error', error: item.error })
+        pending.delete(id)
+        continue
+      }
+
+      if (item.phase === 'canceled') {
+        outcomes.set(id, { localId: id, status: 'canceled' })
+        pending.delete(id)
+      }
+    }
+  }
+
+  update()
+
+  if (pending.size === 0) {
+    return Promise.resolve(localIds.map((id) => outcomes.get(id) ?? { localId: id, status: 'missing' }))
+  }
+
+  return new Promise((resolve) => {
+    const listener = () => {
+      update()
+      if (pending.size === 0) {
+        rt.listeners.delete(listener)
+        resolve(localIds.map((id) => outcomes.get(id) ?? { localId: id, status: 'missing' }))
+      }
+    }
+    rt.listeners.add(listener)
+  })
+}

package/src/core/engine/store/store.dispatch.ts

@@ -0,0 +1,78 @@
+import type { CursorMap, IntentMap, UploadResultBase } from '../../contracts'
+import type { UploadCommand } from '../commands.types'
+import { handleAddFiles } from './handlers/add-file'
+import { handleCancel } from './handlers/cancel'
+import { handlePause } from './handlers/pause'
+import type { StoreRuntime } from './store.types'
+
+/**
+ * Dispatches a command against the runtime.
+ *
+ * Some commands are expanded into multiple operations (e.g. startAll/pauseAll/cancelAll).
+ * Some commands need imperative side effects (pause/cancel/addFiles) and therefore call
+ * handler functions before/after applying reducer transitions.
+ *
+ * @template M - Intent map type
+ * @template C - Cursor map type
+ * @template P - Purpose string union type
+ */
+export function dispatch<M extends IntentMap, C extends CursorMap<M>, P extends string, R extends UploadResultBase>(
+  rt: StoreRuntime<M, C, P, R>,
+  cmd: UploadCommand<P>,
+) {
+  // Bulk operations
+  if (cmd.type === 'startAll') {
+    const purpose = cmd.purpose
+    Array.from(rt.state.items.values())
+      .filter((item) => item.phase === 'ready' && (!purpose || item.purpose === purpose))
+      .forEach((item) => rt.dispatch({ type: 'start', localId: item.localId }))
+    return
+  }
+
+  if (cmd.type === 'pauseAll') {
+    const purpose = cmd.purpose
+    Array.from(rt.state.items.values())
+      .filter((item) => item.phase === 'uploading' && (!purpose || item.purpose === purpose))
+      .forEach((item) => rt.dispatch({ type: 'pause', localId: item.localId }))
+    return
+  }
+
+  if (cmd.type === 'cancelAll') {
+    const purpose = cmd.purpose
+    Array.from(rt.state.items.values())
+      .filter(
+        (item) => item.phase !== 'completed' && item.phase !== 'canceled' && (!purpose || item.purpose === purpose),
+      )
+      .forEach((item) => rt.dispatch({ type: 'cancel', localId: item.localId }))
+    return
+  }
+
+  if (cmd.type === 'addFiles') {
+    handleAddFiles(rt, cmd.files, cmd.purpose)
+    return
+  }
+
+  if (cmd.type === 'pause') {
+    handlePause(rt, cmd.localId)
+    rt.applyCommand(cmd)
+    return
+  }
+
+  if (cmd.type === 'cancel') {
+    handleCancel(rt, cmd.localId)
+    rt.applyCommand(cmd)
+    return
+  }
+
+  if (cmd.type === 'start') {
+    rt.applyCommand(cmd)
+    return
+  }
+
+  if (cmd.type === 'resume') {
+    rt.applyCommand(cmd)
+    return
+  }
+
+  rt.applyCommand(cmd)
+}