@gentleduck/upload 0.2.5 → 0.3.0

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

@@ -1,53 +1,102 @@
-import type { AnyIntent, CursorMap, IntentMap, UploadError, UploadResultBase } from '../../../contracts'
+import type { Contracts } from '../../../contracts'
+import type { UploadError } from '../../../errors'
+import { UploadValidationError } from '../../../errors'
+import { isRecord } from '../../../utils/guards'
+import { sanitizeFilename } from '../../../utils/sanitize-filename'
 import { validateIntent } from '../../validation'
-import { normalizeError, retryDecision, sleep } from '../store.libs'
-import type { StoreRuntime } from '../store.types'
+import {
+  buildApiContext,
+  normalizeError,
+  parseCreateIntentDedupeResult,
+  retryDecision,
+  sleep,
+  tryDedupeByChecksum,
+} from '../store.libs'
+import type { Store } from '../store.types'
 
 export async function createIntent<
-  M extends IntentMap,
-  C extends CursorMap<M>,
+  M extends Contracts.Intent.Map,
+  C extends Contracts.Cursor.Map<M>,
   P extends string,
-  R extends UploadResultBase,
->(rt: StoreRuntime<M, C, P, R>, localId: string) {
+  R extends Contracts.Result.Base,
+>(rt: Store.Runtime<M, C, P, R>, localId: string) {
   const item = rt.state.items.get(localId)
-  if (!item || item.phase !== 'creating_intent') return
+  if (item?.phase !== 'creating_intent') return
   if (rt.inflightIntents.has(localId)) return
 
+  const sanitised = sanitizeFilename(item.file.name)
+  if (!sanitised.safe) {
+    const error = new UploadValidationError(
+      { code: 'filename_rejected', reason: sanitised.reason },
+      'filename rejected',
+      { context: { original: item.file.name, reason: sanitised.reason } },
+    )
+    rt.applyInternal({
+      type: 'intent.failed',
+      localId,
+      error,
+      retryable: false,
+    })
+    return
+  }
+
   const controller = new AbortController()
   rt.inflightIntents.set(localId, controller)
 
   try {
+    if (await tryDedupeByChecksum(rt, localId, item.fingerprint.checksum, item.purpose, ['creating_intent'])) {
+      return
+    }
+
+    const intentArgs: {
+      purpose: P
+      contentType: string
+      size: number
+      filename: string
+      checksum?: string
+      attempt: number
+    } = {
+      purpose: item.purpose,
+      contentType: item.file.type || 'application/octet-stream',
+      size: item.file.size,
+      filename: sanitised.normalised,
+      attempt: item.attempt ?? 1,
+    }
+    if (item.fingerprint.checksum !== undefined) {
+      intentArgs.checksum = item.fingerprint.checksum
+    }
+
     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 },
+      intentArgs,
+      buildApiContext(item, { signal: controller.signal }) as Contracts.Api.CreateIntentContext<P, M>,
     )
 
     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
+    if (current?.phase !== 'creating_intent') return
+
+    const dedupeResult = parseCreateIntentDedupeResult<R>(intent)
+    if (dedupeResult) {
+      rt.applyInternal({ type: 'dedupe.ok', localId, result: dedupeResult })
+      return
+    }
 
     // Validate intent from backend
-    const intentError = validateIntent(intent, intent.strategy)
+    const strategy = isRecord(intent) && typeof intent.strategy === 'string' ? intent.strategy : ''
+    const intentError = validateIntent(intent, strategy)
     if (intentError) {
-      const error: UploadError = {
-        code: 'validation_failed',
-        message: `Invalid intent from backend: ${intentError.message}`,
-        cause: intentError,
+      rt.applyInternal({
+        type: 'intent.failed',
+        localId,
+        error: intentError,
         retryable: false,
-      }
-      rt.applyInternal({ type: 'intent.failed', localId, error, retryable: false })
+      })
       return
     }
 
-    rt.applyInternal({ type: 'intent.ok', localId, intent: intent as AnyIntent<M> })
+    rt.applyInternal({ type: 'intent.ok', localId, intent: intent as Contracts.Intent.Any<M> })
   } catch (err: unknown) {
     rt.inflightIntents.delete(localId)
 
@@ -59,10 +108,16 @@ export async function createIntent<
     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})`,
+      context: {
+        ...((error as { context?: Record<string, unknown> }).context ?? {}),
+        filename: item.fingerprint.name,
+        size: item.file.size,
+        purpose: item.purpose,
+      },
     }
 
-    const decision = retryDecision(rt.opts.config, { phase: 'intent', attempt: item.attempt, error: errorWithContext })
+    const attempt = item.attempt ?? 1
+    const decision = retryDecision(rt.opts.config, { phase: 'intent', attempt, error: errorWithContext })
 
     rt.applyInternal({ type: 'intent.failed', localId, error: errorWithContext, retryable: decision.retryable })
 

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

@@ -1,15 +1,20 @@
-import type { CursorMap, IntentMap, UploadError, UploadResultBase } from '../../../contracts'
-import { hasIntent, normalizeError, retryDecision, sleep } from '../store.libs'
-import type { StoreRuntime } from '../store.types'
+import type { Contracts } from '../../../contracts'
+import type { UploadError } from '../../../errors'
+import { buildApiContext, hasIntent, normalizeError, retryDecision, sleep } from '../store.libs'
+import type { Store } from '../store.types'
+
+function hasContext(e: UploadError): e is UploadError & { context: Record<string, unknown> } {
+  return typeof e === 'object' && e !== null && 'context' in e && typeof e.context === 'object' && e.context !== null
+}
 
 export async function finalizeUpload<
-  M extends IntentMap,
-  C extends CursorMap<M>,
+  M extends Contracts.Intent.Map,
+  C extends Contracts.Cursor.Map<M>,
   P extends string,
-  R extends UploadResultBase,
->(rt: StoreRuntime<M, C, P, R>, localId: string) {
+  R extends Contracts.Result.Base,
+>(rt: Store.Runtime<M, C, P, R>, localId: string) {
   const item = rt.state.items.get(localId)
-  if (!item || item.phase !== 'completing') return
+  if (item?.phase !== 'completing') return
   if (rt.inflightCompletes.has(localId)) return
 
   const controller = new AbortController()
@@ -18,12 +23,22 @@ export async function finalizeUpload<
   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 })
+    const result = await rt.opts.api.complete(
+      {
+        fileId: item.intent.fileId,
+        filename: item.fingerprint.name,
+        contentType: item.file.type || 'application/octet-stream',
+        size: item.fingerprint.size,
+        ...(item.fingerprint.checksum !== undefined ? { checksum: item.fingerprint.checksum } : {}),
+        attempt: item.attempt ?? 1,
+      },
+      buildApiContext(item, { signal: controller.signal }) as Contracts.Api.CompleteContext<P, M>,
+    )
     rt.inflightCompletes.delete(localId)
 
     // Item might have been canceled
     const current = rt.state.items.get(localId)
-    if (!current || current.phase !== 'completing') return
+    if (current?.phase !== 'completing') return
 
     rt.applyInternal({ type: 'complete.ok', localId, result })
   } catch (err: unknown) {
@@ -37,9 +52,11 @@ export async function finalizeUpload<
     const errorWithContext: UploadError = itemForContext
       ? {
           ...error,
-          message: `${error.message} (file: ${itemForContext.fingerprint.name}, fileId: ${
-            (hasIntent(itemForContext) && itemForContext.intent?.fileId) ?? 'unknown'
-          })`,
+          context: {
+            ...(hasContext(error) ? error.context : {}),
+            filename: itemForContext.fingerprint.name,
+            fileId: (hasIntent(itemForContext) && itemForContext.intent?.fileId) ?? 'unknown',
+          },
         }
       : error
 

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

@@ -1,7 +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'
+export { handleAddFiles } from './add-file'
+export { handleCancel } from './cancel'
+export { cleanupOldItems } from './clean-up'
+export { createIntent } from './create-intent'
+export { finalizeUpload } from './finalize'
+export { handlePause } from './pause'
+export { runUpload } from './run-upload'

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

@@ -1,10 +1,12 @@
-import type { CursorMap, IntentMap, UploadResultBase } from '../../../contracts'
-import type { StoreRuntime } from '../store.types'
+import type { Contracts } from '../../../contracts'
+import type { Store } 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,
-) {
+export function handlePause<
+  M extends Contracts.Intent.Map,
+  C extends Contracts.Cursor.Map<M>,
+  P extends string,
+  R extends Contracts.Result.Base,
+>(rt: Store.Runtime<M, C, P, R>, localId: string) {
   const inflight = rt.inflightUploads.get(localId)
   if (inflight) {
     inflight.mode = 'pause'

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

@@ -1,17 +1,19 @@
-import type { AnyCursor, CursorMap, IntentMap, UploadError, UploadResultBase } from '../../../contracts'
+import type { Contracts } from '../../../contracts'
+import type { UploadError } from '../../../errors'
+import { UploadStrategyMissingError } from '../../../errors'
 import { hasCursor, hasFile, hasIntent, normalizeError, retryDecision, sleep } from '../store.libs'
-import type { StoreRuntime } from '../store.types'
+import type { Store } from '../store.types'
 
 export async function runUpload<
-  M extends IntentMap,
-  C extends CursorMap<M>,
+  M extends Contracts.Intent.Map,
+  C extends Contracts.Cursor.Map<M>,
   P extends string,
-  R extends UploadResultBase,
->(rt: StoreRuntime<M, C, P, R>, localId: string) {
+  R extends Contracts.Result.Base,
+>(rt: Store.Runtime<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)) {
+  // State moved on (or never valid)  drop any stale inflight entry.
+  if (item?.phase !== 'uploading' || !hasIntent(item)) {
     rt.inflightUploads.delete(localId)
     return
   }
@@ -33,25 +35,24 @@ export async function runUpload<
     rt.applyInternal({ type: 'canceled', localId, canceledAt: Date.now() })
   }
 
-  const applyPaused = (cursor: AnyCursor<C>) => {
+  const applyPaused = (cursor: Contracts.Cursor.Any<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.
+  const strategyId = item.intent.strategy
+
+  // Paused/canceled before the request begins: short-circuit to the right terminal state.
   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)
+        (cur && hasCursor(cur) ? cur.cursor : undefined) ||
+        ({ strategy: strategyId, value: undefined } as Contracts.Cursor.Any<C>)
 
       if (cursor) applyPaused(cursor)
       return
@@ -65,16 +66,15 @@ export async function runUpload<
     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),
+    const error = new UploadStrategyMissingError(String(strategyId))
+    rt.applyInternal({
+      type: 'upload.failed',
+      localId,
+      error,
       retryable: false,
-    }
-    rt.applyInternal({ type: 'upload.failed', localId, error, retryable: false })
+    })
     return
   }
 
@@ -82,27 +82,35 @@ export async function runUpload<
 
   if (!strategy) {
     rt.inflightUploads.delete(localId)
-    const error: UploadError = {
-      code: 'strategy_missing',
-      message: `Strategy not found: ${item.intent.strategy}`,
-      strategy: String(item.intent.strategy),
+    const error = new UploadStrategyMissingError(String(item.intent.strategy))
+    rt.applyInternal({
+      type: 'upload.failed',
+      localId,
+      error,
       retryable: false,
-    }
-    rt.applyInternal({ type: 'upload.failed', localId, error, retryable: false })
+    })
     return
   }
 
-  // Throttle progress events
+  // Throttle progress events to limit re-renders and reducer churn.
   let lastEmit = 0
   const progressThrottle = rt.opts.config.progressThrottleMs
 
   try {
     await strategy.start({
+      localId,
+      purpose: item.purpose,
       file: item.file,
       intent: item.intent,
       signal: controller.signal,
       transport: rt.opts.transport,
       api: rt.opts.api,
+      fingerprint: item.fingerprint,
+      attempt: item.attempt ?? 1,
+      createdAt: item.createdAt,
+      steps: item.steps,
+      meta: item.meta,
+      lastError: [...item.steps].reverse().find((s) => s.error)?.error,
 
       readCursor: () => {
         const cur = rt.state.items.get(localId)
@@ -112,7 +120,7 @@ export async function runUpload<
       },
 
       persistCursor: (cursorValue) => {
-        const tagged: AnyCursor<C> = { strategy: strategyId, value: cursorValue }
+        const tagged = { strategy: strategyId, value: cursorValue } as Contracts.Cursor.Any<C>
         rt.applyInternal({ type: 'cursor.updated', localId, cursor: tagged })
       },
 
@@ -138,23 +146,27 @@ export async function runUpload<
       return
     }
     if (controller.signal.aborted && inflight?.mode === 'pause') {
-      // Paused at the end; reducer expects cursor - if not present, keep last-known or synthesize.
+      // Paused after strategy returned: reducer requires a cursor  synthesize an
+      // empty one if the strategy never persisted progress.
       const cur = rt.state.items.get(localId)
-      const cursor = (cur && hasCursor(cur) ? cur.cursor : undefined) || { strategy: strategyId, value: undefined }
+      const cursor =
+        (cur && hasCursor(cur) ? cur.cursor : undefined) ||
+        ({ strategy: strategyId, value: undefined } as Contracts.Cursor.Any<C>)
       applyPaused(cursor)
       return
     }
 
-    // Normal completion -> completing
+    // 'completing' phase; finalizeUpload runs via scheduleWork().
     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 }
+        const cursor =
+          (cur && hasCursor(cur) ? cur.cursor : undefined) ||
+          ({ strategy: strategyId, value: undefined } as Contracts.Cursor.Any<C>)
         applyPaused(cursor)
         return
       }
@@ -164,7 +176,7 @@ export async function runUpload<
         return
       }
 
-      // Unknown abort -> treat as cancel
+      // Abort with no mode set: treat as cancel.
       applyCanceled()
       return
     }
@@ -174,9 +186,12 @@ export async function runUpload<
     const errorWithContext: UploadError = itemForContext
       ? {
           ...error,
-          message: `${error.message} (file: ${itemForContext.fingerprint.name}, size: ${
-            (hasFile(itemForContext) && itemForContext.file?.size) ?? 0
-          } bytes, phase: ${itemForContext.phase})`,
+          context: {
+            ...((error as { context?: Record<string, unknown> }).context ?? {}),
+            filename: itemForContext.fingerprint.name,
+            size: (hasFile(itemForContext) && itemForContext.file?.size) ?? 0,
+            phase: itemForContext.phase,
+          },
         }
       : error
     const decision = retryDecision(rt.opts.config, { phase: 'upload', attempt: 1, error: errorWithContext })

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

@@ -1,8 +1,9 @@
-import type { CursorMap, IntentMap, UploadResultBase } from '../../contracts'
-import type { UploadOutcome } from '../outcome.types'
+import type { Contracts } from '../../contracts'
+import { isDevEnv } from '../../utils/guards'
+import type { Engine } from '../engine.types'
 import { dispatch as internalDispatch } from './store.dispatch'
 import { createStoreRuntime } from './store.runtime'
-import type { StoreOptions, StoreRuntime, UploadStore } from './store.types'
+import type { Store } from './store.types'
 
 // TODO: add option for debug mode
 
@@ -22,20 +23,21 @@ import type { StoreOptions, StoreRuntime, UploadStore } from './store.types'
  * @template P - Purpose string union type
  *
  * @param opts - Store options (config, backend API, strategies, transport, hooks)
- * @returns A configured {@link UploadStore} instance.
+ * @returns A configured {@link Store.UploadStore} instance.
+ * @author wildduck2 <https://github.com/wildduck2>
  */
 export function createUploadStore<
-  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,
->(opts: StoreOptions<M, C, P, R>): UploadStore<M, C, P, R> {
+  R extends Contracts.Result.Base = Contracts.Result.Base,
+>(opts: Store.Options<M, C, P, R>): Store.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'> = {
+  const storeProxy: Pick<Store.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,
@@ -47,7 +49,7 @@ export function createUploadStore<
     try {
       plugin.setup(storeProxy)
     } catch (err) {
-      if (typeof window !== 'undefined' && process.env.NODE_ENV === 'development') {
+      if (isDevEnv()) {
         console.error(`[UploadEngine] Plugin "${plugin.name}" failed to setup:`, err)
       }
     }
@@ -55,32 +57,34 @@ export function createUploadStore<
 
   return {
     ...storeProxy,
-    subscribe: (listener) => {
+    subscribe: (listener: () => void) => {
       rt.listeners.add(listener)
       return () => rt.listeners.delete(listener)
     },
-    waitFor(localIds) {
+    waitFor(localIds: string[]) {
       return waitForOutcomes(rt, localIds)
     },
   }
 }
 
-export * from './store.types'
+export type { Store } 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>>> {
+function waitForOutcomes<
+  M extends Contracts.Intent.Map,
+  C extends Contracts.Cursor.Map<M>,
+  P extends string,
+  R extends Contracts.Result.Base,
+>(rt: Store.Runtime<M, C, P, R>, localIds: string[]): Promise<Array<Engine.Outcome<R>>> {
   if (localIds.length === 0) return Promise.resolve([])
 
   const pending = new Set(localIds)
-  const outcomes = new Map<string, UploadOutcome<R>>()
+  const outcomes = new Map<string, Engine.Outcome<R>>()
 
   const update = () => {
     for (const id of pending) {
       const item = rt.state.items.get(id)
       if (!item) {
-        outcomes.set(id, { localId: id, status: 'missing' })
+        outcomes.set(id, { localId: id, status: 'missing', reason: 'never-existed' })
         pending.delete(id)
         continue
       }
@@ -107,7 +111,9 @@ function waitForOutcomes<M extends IntentMap, C extends CursorMap<M>, P extends
   update()
 
   if (pending.size === 0) {
-    return Promise.resolve(localIds.map((id) => outcomes.get(id) ?? { localId: id, status: 'missing' }))
+    return Promise.resolve(
+      localIds.map((id) => outcomes.get(id) ?? { localId: id, status: 'missing', reason: 'never-existed' }),
+    )
   }
 
   return new Promise((resolve) => {
@@ -115,7 +121,7 @@ function waitForOutcomes<M extends IntentMap, C extends CursorMap<M>, P extends
       update()
       if (pending.size === 0) {
         rt.listeners.delete(listener)
-        resolve(localIds.map((id) => outcomes.get(id) ?? { localId: id, status: 'missing' }))
+        resolve(localIds.map((id) => outcomes.get(id) ?? { localId: id, status: 'missing', reason: 'never-existed' }))
       }
     }
     rt.listeners.add(listener)

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

@@ -1,9 +1,9 @@
-import type { CursorMap, IntentMap, UploadResultBase } from '../../contracts'
-import type { UploadCommand } from '../commands.types'
+import type { Contracts } from '../../contracts'
+import type { Engine } from '../engine.types'
 import { handleAddFiles } from './handlers/add-file'
 import { handleCancel } from './handlers/cancel'
 import { handlePause } from './handlers/pause'
-import type { StoreRuntime } from './store.types'
+import type { Store } from './store.types'
 
 /**
  * Dispatches a command against the runtime.
@@ -16,10 +16,12 @@ import type { StoreRuntime } from './store.types'
  * @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>,
-) {
+export function dispatch<
+  M extends Contracts.Intent.Map,
+  C extends Contracts.Cursor.Map<M>,
+  P extends string,
+  R extends Contracts.Result.Base,
+>(rt: Store.Runtime<M, C, P, R>, cmd: Engine.Command<P>) {
   // Bulk operations
   if (cmd.type === 'startAll') {
     const purpose = cmd.purpose
@@ -54,7 +56,7 @@ export function dispatch<M extends IntentMap, C extends CursorMap<M>, P extends
   }
 
   if (cmd.type === 'addFiles') {
-    handleAddFiles(rt, cmd.files, cmd.purpose)
+    handleAddFiles(rt, cmd.files, cmd.purpose, cmd.meta ?? {})
     return
   }