@gentleduck/upload 0.2.1

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

@@ -0,0 +1,250 @@
+import type { UploadConfig, UploadConfigInput, UploadHooks, UploadPlugin } from '../../client'
+import type {
+  CursorMap,
+  FileFingerprint,
+  IntentMap,
+  RejectReason,
+  StrategyRegistry,
+  UploadApi,
+  UploadError,
+  UploadResultBase,
+  UploadTransport,
+} from '../../contracts'
+import type { PersistedSnapshot, PersistenceAdapter } from '../../persistence'
+import type { TypedEmitter } from '../../utils/emitter'
+import type { UploadCommand } from '../commands.types'
+import type { UploadEventMap } from '../event-map.types'
+import type { InternalEvent } from '../internal-events.types'
+import type { UploadOutcome } from '../outcome.types'
+import type { createReducer, UploadState } from '../reducer'
+
+/**
+ * Upload store interface used by UI adapters and application code.
+ *
+ * The store is intentionally minimal:
+ * - state is read through {@link UploadStore.getSnapshot}
+ * - updates are observed through {@link UploadStore.subscribe} and {@link UploadStore.on}
+ * - actions are performed through {@link UploadStore.dispatch}
+ *
+ * @template M - Intent map type (keyed by strategy id)
+ * @template C - Cursor map type (keyed by strategy id)
+ * @template P - Purpose string union type
+ */
+export interface UploadStore<
+  M extends IntentMap,
+  C extends CursorMap<M>,
+  P extends string,
+  R extends UploadResultBase = UploadResultBase,
+> {
+  /**
+   * Returns the current immutable state snapshot.
+   * Useful for React loops or debugging.
+   */
+  getSnapshot(): UploadState<M, C, P, R>
+  /**
+   * Subscribes to ANY state change.
+   * The listener is called after the reducer has run and effects have been scheduled.
+   * @param listener - Listener function to call on state change
+   */
+  subscribe(listener: () => void): () => void
+  /**
+   * Main entry point for user actions.
+   * Converts external commands into internal state transitions and side effects.
+   *
+   * @param cmd The command to execute (e.g. 'addFiles', 'start', 'pause')
+   */
+  dispatch(cmd: UploadCommand<P>): void
+  /**
+   * Subscribes to specific events (like 'file.added', 'upload.progress').
+   * Wraps the internal typed emitter.
+   */
+  on: <K extends keyof UploadEventMap<M, C, P, R> & string>(
+    type: K,
+    cb: (payload: UploadEventMap<M, C, P, R>[K]) => void,
+  ) => () => void
+
+  /**
+   * Unsubscribes from specific events (like 'file.added', 'upload.progress').
+   * Wraps the internal typed emitter.
+   */
+  off: <K extends keyof UploadEventMap<M, C, P, R> & string>(
+    type: K,
+    cb: (payload: UploadEventMap<M, C, P, R>[K]) => void,
+  ) => () => void
+
+  /**
+   * Waits for the given localIds to reach a terminal state.
+   */
+  waitFor(localIds: string[]): Promise<Array<UploadOutcome<R>>>
+}
+
+/**
+ * Options used to construct a store runtime.
+ *
+ * In practice you provide:
+ * - a backend adapter ({@link UploadApi}) that creates intents and finalizes uploads
+ * - a transport implementation (XHR, fetch, etc.) used by strategies
+ * - a strategy registry describing what upload strategies exist and how to run them
+ * - configuration rules for validation, concurrency, retries, and progress throttling
+ *
+ * Hooks and plugins are optional and let you observe or extend behavior without forking
+ * the engine.
+ *
+ * @template M - Intent map type (keyed by strategy id)
+ * @template C - Cursor map type (keyed by strategy id)
+ * @template P - Purpose string union type
+ */
+export interface StoreOptions<
+  M extends IntentMap,
+  C extends CursorMap<M>,
+  P extends string,
+  R extends UploadResultBase = UploadResultBase,
+> {
+  /** Initial state to hydrate from (e.g. from localStorage) */
+  initialState?: UploadState<M, C, P, R>
+  /** Static configuration rules (defaults are applied). */
+  config?: UploadConfigInput<P>
+  /** Persistence adapter and options */
+  persistence?: PersistenceOptions<M, C, P, R>
+  /** Backend API adapter for creating intents and finalizing uploads */
+  api: UploadApi<M, P, R>
+  /** Network transport (XHR/Fetch) for the actual file data transfer */
+  transport?: UploadTransport
+  /** Registry of available upload strategies (multipart, simple, etc.) */
+  strategies: StrategyRegistry<M, C, P, R>
+  /** Optional plugins to extend functionality (e.g. debugging, metrics) */
+  plugins?: Array<UploadPlugin<M, C, P, R>>
+  /** Lifecycle hooks for observing internal events */
+  hooks?: UploadHooks<M, C, P, R>
+  /**
+   * Optional custom fingerprinting (e.g. include sha256).
+   * Must be synchronous to keep addFiles fast.
+   */
+  fingerprint?: (file: File) => FileFingerprint
+  /**
+   * If returns non-null, it rejects the file.
+   * Runs after built-in config validation.
+   */
+  validateFile?: (file: File, purpose: P) => RejectReason | null
+  /**
+   * Optional custom error normalizer.
+   * Convert raw errors (from fetch, XHR, etc.) into your custom UploadError shape.
+   */
+  errorNormalizer?: (err: unknown) => UploadError
+}
+
+/**
+ * Persistence options.
+ *
+ * Used to configure the upload store persistence layer.
+ */
+export type DeserializeContext<M extends IntentMap, C extends CursorMap<M>, P extends string> = {
+  isPurpose?: (value: string) => value is P
+  isIntent?: (value: unknown) => value is M[keyof M]
+  hasStrategy: (value: string) => boolean
+}
+
+export type PersistenceOptions<
+  M extends IntentMap,
+  C extends CursorMap<M>,
+  P extends string,
+  R extends UploadResultBase,
+> = {
+  /** Persistence key (e.g. localStorage key) */
+  key: string
+  /** Persistence schema version (not app version) */
+  version: number
+  /** Debounce delay in milliseconds (default: 200) */
+  debounceMs?: number
+  /** Persistence adapter */
+  adapter: PersistenceAdapter
+
+  /**
+   * Optional custom snapshot serializer.
+   * Convert the upload state into a JSON-safe snapshot.
+   */
+  serialize?: (state: UploadState<M, C, P, R>, version: number) => PersistedSnapshot<M, C, P>
+  /**
+   * Optional custom snapshot deserializer.
+   * Convert a JSON-safe snapshot into the upload state.
+   */
+  deserialize?: (raw: unknown, ctx: DeserializeContext<M, C, P>) => UploadState<M, C, P, R> | null
+
+  /**
+   * Runtime guard for purpose strings when using the default deserializer.
+   */
+  isPurpose?: (value: string) => value is P
+
+  /**
+   * Runtime guard for intent objects when using the default deserializer.
+   */
+  isIntent?: (value: unknown) => value is M[keyof M]
+}
+
+/**
+ * Internal record describing a currently running upload request.
+ *
+ * The store keeps one inflight entry per `localId` while the strategy's `start()` is running.
+ * The {@link AbortController} is used to pause/cancel, while `mode` tracks which user intent
+ * caused the abort so the handler can map it back into a correct state transition.
+ */
+export type InflightUpload = {
+  controller: AbortController
+  mode: 'normal' | 'pause' | 'cancel'
+  started: boolean
+}
+
+/**
+ * Internal runtime container shared across dispatch, scheduler, and handlers.
+ *
+ * @template M - Intent map type
+ * @template C - Cursor map type
+ * @template P - Purpose string union type
+ */
+export type StoreRuntime<
+  M extends IntentMap,
+  C extends CursorMap<M>,
+  P extends string,
+  R extends UploadResultBase = UploadResultBase,
+> = {
+  /** Store options */
+  opts: StoreOptions<M, C, P, R> & { config: UploadConfig<P>; transport: UploadTransport }
+  /** Current state */
+  state: UploadState<M, C, P, R>
+
+  /** Listeners for external events */
+  listeners: Set<() => void>
+  /** Typed event emitter */
+  emitter: TypedEmitter<UploadEventMap<M, C, P, R>>
+  /** Reducer */
+  reduce: ReturnType<typeof createReducer<M, C, P, R>>
+
+  /** In-flight uploads */
+  inflightUploads: Map<string, InflightUpload>
+  /** In-flight intents */
+  inflightIntents: Map<string, AbortController>
+  /** In-flight completes */
+  inflightCompletes: Map<string, AbortController>
+
+  /** Effect queue */
+  effectQueue: Array<() => Promise<void>>
+  /** Effect queue processing */
+  processingEffects: boolean
+  /** Effect queue scheduling */
+  scheduling: boolean
+
+  /** Notifies listeners */
+  notify: () => void
+  /** Schedules work */
+  scheduleWork: () => void
+  /** Applies an internal event */
+  applyInternal: (event: InternalEvent<M, C, P, R>) => void
+  /** Applies a command */
+  applyCommand: (cmd: UploadCommand<P>) => void
+  /** Enqueues an effect */
+  enqueueEffect: (effect: () => Promise<void>) => void
+  /** Processes effects */
+  processEffects: () => Promise<void>
+  /** Set by createUploadStore after construction; used by handlers for retries etc. */
+  dispatch: (cmd: UploadCommand<P>) => void
+}

package/src/core/engine/validation/file.ts

@@ -0,0 +1,77 @@
+import type { UploadConfig } from '../../client'
+import type { RejectReason } from '../../contracts'
+
+export function validateFile<P extends string>(file: File, purpose: P, config: UploadConfig<P>): RejectReason | null {
+  // Get rules for this purpose, skip validation if no rules defined
+  const rules = config.validation?.[purpose]
+  if (!rules) return null
+
+  // Check for empty file
+  if (file.size === 0) return { code: 'empty_file' }
+
+  // Check maximum size limit
+  if (rules.maxSizeBytes !== undefined && file.size > rules.maxSizeBytes) {
+    return { code: 'file_too_large', maxBytes: rules.maxSizeBytes, size: file.size }
+  }
+
+  // Check minimum size limit (treated as empty for simplicity)
+  if (rules.minSizeBytes !== undefined && file.size < rules.minSizeBytes) {
+    return { code: 'empty_file' }
+  }
+
+  // Check file type and extension restrictions
+  if (rules.allowedTypes || rules.allowedExtensions) {
+    const allowed = rules.allowedTypes || []
+    const extensions = rules.allowedExtensions || []
+
+    // Extract file extension (lowercase, without dot)
+    const fileExt = file.name.split('.').pop()?.toLowerCase()
+    // File MIME type (may be empty string for unknown types)
+    const mimeType = (file.type || '').toLowerCase()
+
+    const typeMatches =
+      allowed.length === 0
+        ? false
+        : allowed.some((type) => {
+            if (type.endsWith('/*')) {
+              // Wildcard match: 'image/*' matches 'image/jpeg', 'image/png', etc.
+              const prefix = type.slice(0, -2).toLowerCase()
+              return mimeType.startsWith(prefix + '/')
+            }
+            // Exact match
+            return mimeType === type.toLowerCase()
+          })
+
+    const extMatches =
+      !!fileExt && extensions.length > 0 ? extensions.some((ext) => ext.toLowerCase() === fileExt) : false
+
+    // Determine if file passes type/extension check
+    const hasTypeRules = allowed.length > 0
+    const hasExtRules = extensions.length > 0
+
+    // If both rules exist, allow either to match (OR logic)
+    // If only one exists, require it to match
+    const ok = (hasTypeRules ? typeMatches : true) && (hasExtRules ? extMatches : true)
+    const okEither = hasTypeRules && hasExtRules ? typeMatches || extMatches : ok
+
+    if (!okEither) {
+      return {
+        code: 'type_not_allowed',
+        allowed: [...allowed, ...extensions],
+        got: file.type || file.name,
+      }
+    }
+  }
+
+  // All checks passed
+  return null
+}
+
+/**
+ * Validates a batch of files, filtering them into 'valid' and 'rejected' lists.
+ * Also enforces the `maxFiles` limit relative to the existing count.
+ *
+ * @param files Array of files to validate
+ * @param purpose Upload purpose
+ * @param existingCount Number of files already uploaded (to enforce maxFiles)
+ */

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

@@ -0,0 +1,3 @@
+export { validateFile } from './file'
+export { validateIntent } from './intent'
+export { validateFileList } from './list'

package/src/core/engine/validation/intent.ts

@@ -0,0 +1,55 @@
+import { isRecord } from '../../utils/guards'
+
+export function validateIntent(intent: unknown, strategy: string): Error | null {
+  if (!isRecord(intent)) {
+    return new Error('Invalid intent: must be an object')
+  }
+
+  // Check required fields
+  if (typeof intent.strategy !== 'string') {
+    return new Error('Invalid intent: missing or invalid strategy field')
+  }
+
+  if (intent.strategy !== strategy) {
+    return new Error(`Invalid intent: strategy mismatch (expected ${strategy}, got ${intent.strategy})`)
+  }
+
+  if (typeof intent.fileId !== 'string' || !intent.fileId) {
+    return new Error('Invalid intent: missing or invalid fileId')
+  }
+
+  // Strategy-specific validation
+  if (strategy === 'post') {
+    // POST strategy requires url and fields
+    if (typeof intent.url !== 'string' || !intent.url) {
+      return new Error('Invalid post intent: missing or invalid url')
+    }
+    try {
+      const url = new URL(intent.url)
+      if (!['http:', 'https:'].includes(url.protocol)) {
+        return new Error('Invalid post intent: url must use http or https protocol')
+      }
+    } catch {
+      return new Error('Invalid post intent: url is not a valid URL')
+    }
+    if (!intent.fields || typeof intent.fields !== 'object') {
+      return new Error('Invalid post intent: missing or invalid fields')
+    }
+  } else if (strategy === 'multipart') {
+    // Multipart strategy requires uploadId and partSize
+    if (typeof intent.uploadId !== 'string' || !intent.uploadId) {
+      return new Error('Invalid multipart intent: missing or invalid uploadId')
+    }
+    if (typeof intent.partSize !== 'number' || intent.partSize <= 0) {
+      return new Error('Invalid multipart intent: missing or invalid partSize')
+    }
+    // Parts array is optional (can be fetched later)
+    if ('parts' in intent && intent.parts !== undefined) {
+      if (!Array.isArray(intent.parts)) {
+        return new Error('Invalid multipart intent: parts must be an array if provided')
+      }
+    }
+  }
+
+  return null
+}

package/src/core/engine/validation/list.ts

@@ -0,0 +1,50 @@
+import type { UploadConfig } from '../../client'
+import type { RejectReason } from '../../contracts'
+import { validateFile } from './file'
+
+export function validateFileList<P extends string>(
+  files: File[],
+  purpose: P,
+  config: UploadConfig<P>,
+  existingCount: number = 0,
+): { valid: File[]; rejected: Array<{ file: File; reason: RejectReason }> } {
+  const rules = config.validation?.[purpose]
+  const valid: File[] = []
+  const rejected: Array<{ file: File; reason: RejectReason }> = []
+
+  // Calculate remaining slots based on maxFiles limit
+  const maxFiles = rules?.maxFiles
+  let remaining = maxFiles !== undefined ? Math.max(0, maxFiles - existingCount) : Number.POSITIVE_INFINITY
+
+  for (const file of files) {
+    // Check if we've reached the file limit
+    if (remaining <= 0) {
+      const limit = maxFiles ?? 0
+      rejected.push({ file, reason: { code: 'too_many_files', max: limit } })
+      continue
+    }
+
+    // Run individual file validation
+    const reason = validateFile(file, purpose, config)
+    if (reason) {
+      rejected.push({ file, reason })
+      continue
+    }
+
+    // File is valid, add to list and decrement remaining slots
+    valid.push(file)
+    remaining -= 1
+  }
+
+  return { valid, rejected }
+}
+
+/**
+ * Validates an intent object from the backend.
+ * Ensures required fields are present and URLs are valid.
+ *
+ * @param intent - Intent object to validate
+ * @param strategy - Expected strategy type (from the intent itself)
+ *
+ * @returns {Error | null} Error if validation fails, null if valid
+ */

package/src/core/index.ts

@@ -0,0 +1,5 @@
+export * from './client'
+export * from './contracts'
+export * from './engine'
+export * from './persistence'
+export * from './utils'

package/src/core/persistence/adapters.indexeddb.ts

@@ -0,0 +1,92 @@
+import type { PersistenceAdapter } from './persistence.types'
+
+const DB_NAME = 'upload-engine'
+const STORE = 'snapshots'
+const VERSION = 1
+
+function openDB(): Promise<IDBDatabase> {
+  return new Promise((resolve, reject) => {
+    const req = indexedDB.open(DB_NAME, VERSION)
+    req.onupgradeneeded = () => {
+      const db = req.result
+      if (!db.objectStoreNames.contains(STORE)) {
+        db.createObjectStore(STORE)
+      }
+    }
+    req.onsuccess = () => resolve(req.result)
+    req.onerror = () => reject(req.error)
+  })
+}
+
+function reqToPromise<T>(req: IDBRequest<T>): Promise<T> {
+  return new Promise((resolve, reject) => {
+    req.onsuccess = () => resolve(req.result)
+    req.onerror = () => reject(req.error)
+  })
+}
+
+function txDone(tx: IDBTransaction): Promise<void> {
+  return new Promise((resolve, reject) => {
+    tx.oncomplete = () => resolve()
+    tx.onabort = () => reject(tx.error ?? new Error('IndexedDB transaction aborted'))
+    tx.onerror = () => reject(tx.error ?? new Error('IndexedDB transaction error'))
+  })
+}
+
+export const IndexedDBAdapter: PersistenceAdapter = {
+  async load(key) {
+    if (typeof indexedDB === 'undefined') return null
+    const db = await openDB()
+    const tx = db.transaction(STORE, 'readonly')
+    const store = tx.objectStore(STORE)
+
+    try {
+      const value = await reqToPromise(store.get(key))
+      await txDone(tx)
+      return value ?? null
+    } catch {
+      try {
+        await txDone(tx)
+      } catch {
+        // ignore
+      }
+      return null
+    }
+  },
+
+  async save(key, snapshot) {
+    if (typeof indexedDB === 'undefined') return
+    const db = await openDB()
+    const tx = db.transaction(STORE, 'readwrite')
+    const store = tx.objectStore(STORE)
+
+    try {
+      store.put(snapshot, key)
+      await txDone(tx)
+    } catch {
+      try {
+        tx.abort()
+      } catch {
+        // ignore
+      }
+    }
+  },
+
+  async clear(key) {
+    if (typeof indexedDB === 'undefined') return
+    const db = await openDB()
+    const tx = db.transaction(STORE, 'readwrite')
+    const store = tx.objectStore(STORE)
+
+    try {
+      store.delete(key)
+      await txDone(tx)
+    } catch {
+      try {
+        tx.abort()
+      } catch {
+        // ignore
+      }
+    }
+  },
+}

package/src/core/persistence/adapters.local.ts

@@ -0,0 +1,22 @@
+import type { PersistenceAdapter } from './persistence.types'
+
+export const LocalStorageAdapter: PersistenceAdapter = {
+  load(key) {
+    if (typeof localStorage === 'undefined') return null
+    const raw = localStorage.getItem(key)
+    if (!raw) return null
+    try {
+      return JSON.parse(raw)
+    } catch {
+      return null
+    }
+  },
+  save(key, snapshot) {
+    if (typeof localStorage === 'undefined') return
+    localStorage.setItem(key, JSON.stringify(snapshot))
+  },
+  clear(key) {
+    if (typeof localStorage === 'undefined') return
+    localStorage.removeItem(key)
+  },
+}

package/src/core/persistence/adapters.memory.ts

@@ -0,0 +1,15 @@
+import type { PersistenceAdapter } from './persistence.types'
+
+const store = new Map<string, unknown>()
+
+export const MemoryAdapter: PersistenceAdapter = {
+  load(key) {
+    return store.get(key) ?? null
+  },
+  save(key, snapshot) {
+    store.set(key, snapshot)
+  },
+  clear(key) {
+    store.delete(key)
+  },
+}

package/src/core/persistence/index.ts

@@ -0,0 +1,5 @@
+export * from './adapters.indexeddb'
+export * from './adapters.local'
+export * from './adapters.memory'
+export * from './persistence'
+export * from './persistence.types'