@gentleduck/upload 0.2.5 → 0.2.6

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

@@ -9,10 +9,7 @@ export { sleep } from '../../utils/async'
 
 import type { StoreOptions } from './store.types'
 
-/**
- * Calculates SHA256 checksum of a file for deduplication.
- * Uses Web Crypto API for efficient hashing.
- */
+/** SHA-256 checksum of `file` for deduplication. */
 export async function calculateFileChecksum(file: File): Promise<string> {
   const buffer = await file.arrayBuffer()
   const hashBuffer = await crypto.subtle.digest('SHA-256', buffer)
@@ -21,12 +18,8 @@ export async function calculateFileChecksum(file: File): Promise<string> {
 }
 
 /**
- * Determines whether items for a given purpose should auto-start.
- *
- * Supports three configuration shapes:
- * - `false | undefined`: never auto-start
- * - `P[]`: auto-start for purposes included in the list
- * - `(purpose: P) => boolean`: custom predicate
+ * Resolve auto-start config: `false | undefined` (never), `P[]` (in list), or
+ * `(purpose) => boolean` predicate.
  */
 export function isAutoStart<M extends IntentMap, C extends CursorMap<M>, P extends string, R extends UploadResultBase>(
   opts: StoreOptions<M, C, P, R>,
@@ -40,38 +33,31 @@ export function isAutoStart<M extends IntentMap, C extends CursorMap<M>, P exten
 }
 
 /**
- * Builds a lightweight fingerprint from a {@link File}.
- *
- * This fingerprint is used for display and basic identity. If you need stronger identity
- * (e.g. SHA-256), provide a custom {@link StoreOptions.fingerprint} function or let the
- * add-file handler compute a checksum asynchronously.
+ * Lightweight `File` fingerprint for display/identity. For stronger identity
+ * (SHA-256), pass {@link StoreOptions.fingerprint} or let add-file compute a
+ * checksum asynchronously.
  */
 export { computeFingerprint, fingerprintMatches }
 
 /**
- * Normalizes unknown thrown values into the engine's {@link UploadError} shape.
- *
- * You can provide a custom normalizer through {@link StoreOptions.errorNormalizer}.
- * Built-in behavior:
- * - detects abort errors and marks them non-retryable
- * - classifies common network and HTTP errors as retryable where appropriate
+ * Normalize a thrown value into an {@link UploadError}. Override via
+ * {@link StoreOptions.errorNormalizer}. Default: aborts → non-retryable;
+ * network errors → retryable; HTTP 5xx/429 → retryable.
  */
 export function normalizeError(err: unknown, customNormalizer?: (err: unknown) => UploadError): UploadError {
   if (customNormalizer) return customNormalizer(err)
 
-  // Transport abort errors can carry {code:'aborted', reason:'pause'|'cancel'}
+  // Transport aborts carry `{ code: 'aborted', reason: 'pause' | 'cancel' }`.
   if (isAbortError(err)) {
     return { code: 'aborted', message: 'Upload aborted', reason: String(err.reason ?? 'unknown'), retryable: false }
   }
 
   const msg = isRecord(err) && typeof err.message === 'string' ? err.message : 'Unknown error'
 
-  // Network errors
   if (String(msg).toLowerCase().includes('network') || String(msg).toLowerCase().includes('fetch')) {
     return { code: 'network', message: String(msg), cause: err, retryable: true }
   }
 
-  // HTTP errors
   if (isRecord(err) && (typeof err.status === 'number' || typeof err.statusCode === 'number')) {
     const status = (typeof err.status === 'number' ? err.status : err.statusCode) as number
     const retryable = status >= 500 || status === 429
@@ -81,42 +67,28 @@ export function normalizeError(err: unknown, customNormalizer?: (err: unknown) =
   return { code: 'unknown', message: String(msg), cause: err, retryable: false }
 }
 
-/**
- * Type guard for items that currently hold a concrete backend intent.
- */
+/** Item has a concrete backend intent. */
 export function hasIntent<M extends IntentMap, C extends CursorMap<M>, P extends string, R extends UploadResultBase>(
   item: UploadItem<M, C, P, R>,
 ): item is Extract<UploadItem<M, C, P, R>, { intent: M[keyof M] }> {
   return 'intent' in item && !!item.intent
 }
 
-/**
- * Type guard for items that currently have a bound {@link File}.
- *
- * Persisted items restored from storage may lack `file` until the UI re-binds it.
- */
+/** Item has a bound `File`. Persisted items may lack it until the UI re-binds. */
 export function hasFile<M extends IntentMap, C extends CursorMap<M>, P extends string, R extends UploadResultBase>(
   item: UploadItem<M, C, P, R>,
 ): item is Extract<UploadItem<M, C, P, R>, { file: File }> {
   return 'file' in item && !!item.file
 }
 
-/**
- * Type guard that narrows to item variants carrying a cursor field.
- *
- * Cursor presence depends on the current phase and the strategy.
- */
+/** Item variant carries a cursor field (depends on phase/strategy). */
 export function hasCursor<M extends IntentMap, C extends CursorMap<M>, P extends string, R extends UploadResultBase>(
   item: UploadItem<M, C, P, R>,
 ): item is Extract<UploadItem<M, C, P, R>, { cursor?: AnyCursor<C> }> {
   return 'cursor' in item
 }
 
-/**
- * Runtime guard for multipart intent objects.
- *
- * Used for best-effort abort calls when canceling multipart uploads.
- */
+/** Best-effort guard used to issue multipart-abort calls on cancel. */
 export function isMultipartIntent(
   intent: unknown,
 ): intent is { strategy: 'multipart'; fileId: string; uploadId: string; partSize: number } {
@@ -128,24 +100,14 @@ export function isMultipartIntent(
   )
 }
 
-/**
- * Runtime guard for abort errors produced by the transport/strategy layer.
- */
 export function isAbortError(err: unknown): err is { code: 'aborted'; reason?: unknown } {
   return isRecord(err) && err.code === 'aborted'
 }
 
 /**
- * Small helper to narrow unknown values to objects.
- */
-
-/**
- * Computes whether a failed operation should be retried and, if so, after what delay.
- *
- * If {@link UploadConfig.retryPolicy} is provided it is used as the source of truth.
- * Otherwise the default policy:
- * - never retries auth/validation/strategy_missing/aborted
- * - retries up to `maxAttempts` with exponential backoff and a fixed cap
+ * Decide whether to retry. Defers to `config.retryPolicy` when set.
+ * Default: never retries `auth`/`validation_failed`/`strategy_missing`/`aborted`;
+ * otherwise exponential backoff up to `maxAttempts`, capped at `DEFAULT_RETRY_DELAY_MAX_MS`.
  */
 export function retryDecision<P extends string>(
   config: UploadConfig<P>,
@@ -153,7 +115,6 @@ export function retryDecision<P extends string>(
 ) {
   if (config.retryPolicy) return config.retryPolicy(ctx)
 
-  // Default: retry network/server unknown errors, not auth/validation/strategy_missing
   if (ctx.error.code === 'auth') return { retryable: false }
   if (ctx.error.code === 'validation_failed') return { retryable: false }
   if (ctx.error.code === 'strategy_missing') return { retryable: false }
@@ -163,7 +124,6 @@ export function retryDecision<P extends string>(
   const retryable = ctx.attempt < maxAttempts
   if (!retryable) return { retryable: false }
 
-  // Exponential backoff with cap
   const delayMs = Math.min(DEFAULT_RETRY_DELAY_MAX_MS, DEFAULT_RETRY_DELAY_BASE_MS * 2 ** (ctx.attempt - 1))
   return { retryable: true, delayMs }
 }

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

@@ -12,18 +12,9 @@ import { scheduleWork } from './store.schedule'
 import type { InflightUpload, StoreOptions, StoreRuntime } from './store.types'
 
 /**
- * Creates a new runtime instance with initial state, emitter, reducer, and effect queue.
- *
- * Notes:
- * - Reducers remain pure: all async work is enqueued through {@link StoreRuntime.enqueueEffect}.
- * - {@link StoreRuntime.applyInternal} invokes hooks, performs cleanup, and then schedules more work.
- * - {@link StoreRuntime.dispatch} is intentionally assigned later to break import cycles.
- *
- * @template M - Intent map type
- * @template C - Cursor map type
- * @template P - Purpose string union type
- *
- * @param opts - Construction options for the store.
+ * Build the store runtime: state, emitter, reducer, and effect queue.
+ * Reducers stay pure — async work goes through {@link StoreRuntime.enqueueEffect}.
+ * `dispatch` is assigned later by `createUploadStore` to break an import cycle.
  */
 export function createStoreRuntime<
   M extends IntentMap,
@@ -34,8 +25,8 @@ export function createStoreRuntime<
   const resolvedOpts = resolveStoreOptions(opts)
   const persistence = resolvedOpts.persistence
 
-  // Debounced persistence flush. Persistence writes a single namespace `key`,
-  // and the adapter can choose how to store multiple item records under it.
+  // Debounced flush. Persistence writes under a single namespace `key`; the
+  // adapter decides how to encode multiple item records under that key.
   let persistTimer: ReturnType<typeof setTimeout> | null = null
   const persistDebounceMs = Math.max(0, persistence?.debounceMs ?? 200)
 
@@ -44,7 +35,7 @@ export function createStoreRuntime<
     try {
       const snap = (persistence.serialize ?? serializeSnapshot)(rt.state, persistence.version)
 
-      // If there's nothing to persist, clear the namespace to keep storage clean.
+      // Nothing to persist → clear the namespace.
       if (!snap.items || Object.keys(snap.items).length === 0) {
         await persistence.adapter.clear(persistence.key)
         return
@@ -158,14 +149,15 @@ export function createStoreRuntime<
       rt.processingEffects = false
     },
 
-    // replaced by createUploadStore
+    // Replaced by createUploadStore — runtime breaks the cycle.
     dispatch: () => {
       throw new Error('[UploadEngine] dispatch not initialized')
     },
   } satisfies StoreRuntime<M, C, P, R>
 
-  // Hydrate from persistence when no initialState was provided.
-  // For async adapters (IndexedDB), this happens after construction.
+  // Async adapters (IndexedDB) resolve after construction; only hydrate when no
+  // initialState was provided. Merge into an empty store only — never clobber
+  // user actions that arrived before the load resolved.
   if (persistence && !resolvedOpts.initialState && typeof window !== 'undefined') {
     try {
       const loaded = persistence.adapter.load(persistence.key)
@@ -178,8 +170,6 @@ export function createStoreRuntime<
         })
         if (!next) return
 
-        // Only merge into an empty store to avoid clobbering user actions
-        // that happened before the async load completed.
         if (rt.state.items.size === 0) {
           rt.state = next
         } else {

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

@@ -43,7 +43,7 @@ export function validateFile<P extends string>(file: File, purpose: P, config: U
           })
 
     const extMatches =
-      !!fileExt && extensions.length > 0 ? extensions.some((ext) => ext.toLowerCase() === fileExt) : false
+      fileExt && extensions.length > 0 ? extensions.some((ext) => ext.toLowerCase() === fileExt) : false
 
     // Determine if file passes type/extension check
     const hasTypeRules = allowed.length > 0

package/src/core/engine/validation.ts

@@ -0,0 +1,216 @@
+import type { Client } from '../client'
+import type { Contracts } from '../contracts'
+import { isRecord } from '../utils/guards'
+
+// ============================================================================
+// validateFile -- single-file rule check
+// ============================================================================
+
+/**
+ * Validate one file against `config.validation[purpose]` rules.
+ *
+ * Empty files are always rejected.
+ *
+ * @param file File to validate.
+ * @param purpose Purpose key used to look up rules.
+ * @param config Resolved upload config.
+ * @template P Purpose discriminator string.
+ * @returns `null` when valid, otherwise a {@link Contracts.RejectReason}.
+ * @author wildduck2 <https://github.com/wildduck2>
+ */
+export function validateFile<P extends string>(
+  file: File,
+  purpose: P,
+  config: Client.IUploadConfig<P>,
+): Contracts.RejectReason | null {
+  if (file.size === 0) return { code: 'empty_file' }
+
+  const rules = config.validation?.[purpose]
+  if (!rules) return null
+
+  if (rules.maxSizeBytes !== undefined && file.size > rules.maxSizeBytes) {
+    return { code: 'file_too_large', maxBytes: rules.maxSizeBytes, size: file.size }
+  }
+
+  if (rules.minSizeBytes !== undefined && file.size < rules.minSizeBytes) {
+    return { code: 'empty_file' }
+  }
+
+  if (rules.allowedTypes || rules.allowedExtensions) {
+    const allowed = rules.allowedTypes || []
+    const extensions = rules.allowedExtensions || []
+
+    const fileExt = file.name.split('.').pop()?.toLowerCase()
+    const mimeType = (file.type || '').toLowerCase()
+
+    const typeMatches =
+      allowed.length === 0
+        ? false
+        : allowed.some((type) => {
+            if (type.endsWith('/*')) {
+              const prefix = type.slice(0, -2).toLowerCase()
+              return mimeType.startsWith(`${prefix}/`)
+            }
+            return mimeType === type.toLowerCase()
+          })
+
+    const extMatches =
+      fileExt && extensions.length > 0 ? extensions.some((ext) => ext.toLowerCase() === fileExt) : false
+
+    const hasTypeRules = allowed.length > 0
+    const hasExtRules = extensions.length > 0
+
+    // When both rule kinds are present, either match is enough; otherwise the
+    // present one must 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,
+      }
+    }
+  }
+
+  return null
+}
+
+// ============================================================================
+// validateFileList -- batch validation with maxFiles cap
+// ============================================================================
+
+/**
+ * Validate a batch of files and split into accepted vs rejected.
+ *
+ * Enforces `maxFiles` against the existing count plus the running additions
+ * so a single `addFiles` call cannot overshoot.
+ *
+ * @param files Files to validate.
+ * @param purpose Purpose key used to look up rules.
+ * @param config Resolved upload config.
+ * @param existingCount Items already in the store for this purpose.
+ * @template P Purpose discriminator string.
+ * @returns Object with `valid` files and `rejected` files plus reasons.
+ * @author wildduck2 <https://github.com/wildduck2>
+ */
+export function validateFileList<P extends string>(
+  files: File[],
+  purpose: P,
+  config: Client.IUploadConfig<P>,
+  existingCount: number = 0,
+): { valid: File[]; rejected: Array<{ file: File; reason: Contracts.RejectReason }> } {
+  const rules = config.validation?.[purpose]
+  const valid: File[] = []
+  const rejected: Array<{ file: File; reason: Contracts.RejectReason }> = []
+
+  const maxFiles = rules?.maxFiles
+  let remaining = maxFiles !== undefined ? Math.max(0, maxFiles - existingCount) : Number.POSITIVE_INFINITY
+
+  for (const file of files) {
+    if (remaining <= 0) {
+      const limit = maxFiles ?? 0
+      rejected.push({ file, reason: { code: 'too_many_files', max: limit } })
+      continue
+    }
+
+    const reason = validateFile(file, purpose, config)
+    if (reason) {
+      rejected.push({ file, reason })
+      continue
+    }
+
+    valid.push(file)
+    remaining -= 1
+  }
+
+  return { valid, rejected }
+}
+
+// ============================================================================
+// validateIntent -- backend-intent shape check
+// ============================================================================
+
+/**
+ * Validate an intent payload returned by the backend before the engine
+ * commits to it.
+ *
+ * Rejects malformed shapes, protocol-foreign URLs, and cross-field
+ * inconsistencies (e.g. `partCount * partSize` cannot cover the file).
+ *
+ * @param intent Raw intent value from `createIntent`.
+ * @param strategy Expected `strategy` discriminator.
+ * @param fileSize File byte length; enables multipart cross-checks.
+ * @returns `Error` describing the failure, or `null` if valid.
+ * @author wildduck2 <https://github.com/wildduck2>
+ */
+export function validateIntent(intent: unknown, strategy: string, fileSize?: number): Error | null {
+  if (!isRecord(intent)) {
+    return new Error('Invalid intent: must be an object')
+  }
+
+  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')
+  }
+
+  if (strategy === 'post') {
+    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') {
+    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')
+    }
+    if ('partCount' in intent && intent.partCount !== undefined) {
+      if (typeof intent.partCount !== 'number' || !Number.isFinite(intent.partCount) || intent.partCount <= 0) {
+        return new Error('Invalid multipart intent: partCount must be a positive number')
+      }
+    }
+    if (typeof fileSize === 'number' && typeof intent.partCount === 'number' && intent.partCount > 0) {
+      const partSize = intent.partSize
+      const partCount = intent.partCount
+      const maxBytes = partCount * partSize
+      const minBytes = (partCount - 1) * partSize
+      if (maxBytes < fileSize) {
+        return new Error(
+          `Invalid multipart intent: partCount * partSize (${maxBytes}) is smaller than file size (${fileSize})`,
+        )
+      }
+      if (minBytes >= fileSize && partCount > 1) {
+        return new Error(
+          `Invalid multipart intent: partCount (${partCount}) exceeds what file size (${fileSize}) needs at partSize ${partSize}`,
+        )
+      }
+    }
+    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/utils/emitter/emitter.ts

@@ -0,0 +1,143 @@
+import type { Emitter } from './emitter.types'
+
+/**
+ * Listener-throw callback. Re-exported alias for the canonical
+ * {@link Emitter.ErrorHandler} type. Kept for backwards compatibility
+ * with R30 import paths; prefer `Emitter.ErrorHandler` in new code.
+ *
+ * @author wildduck2 <https://github.com/wildduck2>
+ */
+export type EmitterErrorHandler = Emitter.ErrorHandler
+
+/**
+ * Listener registry, bucketed by event type.
+ *
+ * @template E Event map.
+ */
+type ListenerMap<E extends Record<string, unknown>> = Partial<{
+  [K in keyof E & string]: Set<(payload: E[K]) => void>
+}>
+
+/**
+ * Soft cap on nested `emit` depth. A listener that synchronously dispatches a
+ * command which fires another emit is legal -- but unbounded re-entry usually
+ * means a feedback loop. The cap surfaces it in dev without aborting.
+ */
+const MAX_EMIT_DEPTH = 50
+
+/**
+ * Build a typed event emitter with listener-throw isolation.
+ *
+ * Listeners added or removed during an `emit` see a stable snapshot of the
+ * listener set; the mutation lands on the *next* emission.
+ *
+ * @param onError Optional error sink. Receives `(type, error, listener)` on
+ *   every listener throw. Falls back to dev-only `console.error` when omitted.
+ * @returns Configured emitter exposing `on` / `off` / `emit`.
+ * @template E Event map (`Record<eventName, payloadType>`).
+ * @example
+ * ```ts
+ * type Events = { 'file.added': { id: string }, 'upload.progress': { pct: number } }
+ * const emitter = createTypedEmitter<Events>()
+ * emitter.on('file.added', (p) => console.log(p.id))
+ * ```
+ * @author wildduck2 <https://github.com/wildduck2>
+ */
+export function createTypedEmitter<E extends Record<string, unknown>>(
+  onError?: EmitterErrorHandler,
+): Emitter.ITypedEmitter<E> {
+  const listeners: ListenerMap<E> = {}
+  // Memoized iteration snapshots per event type. Invalidated on `on`/`off`.
+  // Multi-listener `emit` would otherwise allocate a fresh array every call;
+  // for progress streams that adds up to one Set + spread per progress tick.
+  const snapshots = new Map<string, ReadonlyArray<(payload: unknown) => void>>()
+  let emitDepth = 0
+  let warnedDepth = false
+
+  const invalidate = (type: string) => {
+    if (snapshots.size > 0) snapshots.delete(type)
+  }
+
+  return {
+    on<K extends keyof E & string>(type: K, cb: (payload: E[K]) => void): () => void {
+      let set = listeners[type]
+      if (!set) {
+        set = new Set<(payload: E[K]) => void>()
+        listeners[type] = set
+      }
+      set.add(cb)
+      invalidate(type)
+
+      return () => {
+        const typeListeners = listeners[type]
+        if (!typeListeners) return
+        typeListeners.delete(cb)
+        invalidate(type)
+        if (typeListeners.size === 0) delete listeners[type]
+      }
+    },
+
+    off<K extends keyof E & string>(type: K, cb: (payload: E[K]) => void): void {
+      const typeListeners = listeners[type]
+      if (!typeListeners) return
+      typeListeners.delete(cb)
+      invalidate(type)
+      if (typeListeners.size === 0) delete listeners[type]
+    },
+
+    emit<K extends keyof E & string>(type: K, payload: E[K]): void {
+      const typeListeners = listeners[type]
+      if (!typeListeners || typeListeners.size === 0) return
+
+      const dispatch = (cb: (payload: E[K]) => void) => {
+        try {
+          cb(payload)
+        } catch (err) {
+          if (onError) {
+            try {
+              onError(type, err, cb as (...args: unknown[]) => void)
+            } catch {}
+            return
+          }
+          if (typeof window !== 'undefined' && process.env.NODE_ENV === 'development') {
+            console.error(`[UploadEngine] Error in event listener for "${type}":`, err)
+          }
+        }
+      }
+
+      emitDepth++
+      try {
+        if (emitDepth > MAX_EMIT_DEPTH && !warnedDepth && process.env.NODE_ENV !== 'production') {
+          warnedDepth = true
+          console.warn(
+            `[UploadEngine] emit depth exceeded ${MAX_EMIT_DEPTH} for "${type}". ` +
+              'A listener is likely dispatching a command that re-emits, forming a feedback loop. ' +
+              'Defer the dispatch with `queueMicrotask` to break the chain.',
+          )
+        }
+
+        // Size-1 fast path: skip the snapshot allocation when only one
+        // listener is attached. Hot path under busy progress streams where
+        // most subscribers attach exactly one listener per event type.
+        if (typeListeners.size === 1) {
+          const [only] = typeListeners
+          dispatch(only)
+          return
+        }
+
+        // Multi-listener path: reuse the memoized snapshot so `on()`/`off()`
+        // from inside a listener doesn't reshape iteration mid-flight AND
+        // back-to-back emits don't re-allocate the array.
+        let snapshot = snapshots.get(type) as ReadonlyArray<(payload: E[K]) => void> | undefined
+        if (!snapshot) {
+          snapshot = Array.from(typeListeners) as ReadonlyArray<(payload: E[K]) => void>
+          snapshots.set(type, snapshot as ReadonlyArray<(payload: unknown) => void>)
+        }
+        for (const cb of snapshot) dispatch(cb)
+      } finally {
+        emitDepth--
+        if (emitDepth === 0) warnedDepth = false
+      }
+    },
+  }
+}