@gentleduck/upload 0.2.6 → 0.3.0

package/src/core/persistence/index.ts

@@ -1,5 +1,5 @@
-export * from './adapters.indexeddb'
-export * from './adapters.local'
-export * from './adapters.memory'
-export * from './persistence'
-export * from './persistence.types'
+export { IndexedDBAdapter } from './adapters.indexeddb'
+export { LocalStorageAdapter } from './adapters.local'
+export { createMemoryAdapter, MemoryAdapter } from './adapters.memory'
+export { deserializeSnapshot, serializeSnapshot } from './persistence'
+export type { UploadPersistence } from './persistence.types'

package/src/core/persistence/persistence.ts

@@ -1,33 +1,31 @@
-import type { AnyCursor, AnyIntent, CursorMap, IntentMap, UploadResultBase } from '../contracts'
-import type { UploadItem } from '../engine/internal-events.types'
-import type { UploadState } from '../engine/reducer'
+import type { Contracts } from '../contracts'
+import type { Engine } from '../engine/engine.types'
 import { hasCursor, hasIntent } from '../engine/store/store.libs'
 import { isRecord } from '../utils/guards'
-import type { PersistedSnapshot, PersistedUploadItem } from './persistence.types'
+import type { UploadPersistence } from './persistence.types'
 
 /**
  * Serializes the current upload state into a JSON-safe structure.
  * Only serializes items that have a valid 'intent', as these are the only ones
  * that can be resumed cleanly.
+ * @author wildduck2 <https://github.com/wildduck2>
  */
 export function serializeSnapshot<
-  M extends IntentMap,
-  C extends CursorMap<M>,
+  M extends Contracts.Intent.Map,
+  C extends Contracts.Cursor.Map<M>,
   P extends string,
-  R extends UploadResultBase,
->(state: UploadState<M, C, P, R>, version: number): PersistedSnapshot<M, C, P> {
-  const items: Record<string, PersistedUploadItem<M, C, P>> = {}
+  R extends Contracts.Result.Base,
+>(state: Engine.State<M, C, P, R>, version: number): UploadPersistence.Snapshot<M, C, P> {
+  const items: Record<string, UploadPersistence.PersistedItem<M, C, P>> = {}
 
   for (const item of state.items.values()) {
     if (!hasIntent(item)) continue
 
     // Do not persist terminal items. Persistence is for resuming and recovery, not history.
-    if (
-      (item.phase as string) === 'completed' ||
-      (item.phase as string) === 'canceled' ||
-      (item.phase as string) === 'error'
-    )
+    const phase = item.phase as string
+    if (phase === 'completed' || phase === 'canceled' || phase === 'error') {
       continue
+    }
 
     const cursor = hasCursor(item) ? item.cursor : undefined
 
@@ -40,7 +38,7 @@ export function serializeSnapshot<
           }
         : undefined
 
-    const persisted: PersistedUploadItem<M, C, P> = {
+    const persisted: UploadPersistence.PersistedItem<M, C, P> = {
       id: item.localId,
       purpose: item.purpose,
       status: item.phase,
@@ -51,7 +49,7 @@ export function serializeSnapshot<
         lastModified: item.fingerprint.lastModified,
         checksum: item.fingerprint.checksum,
       },
-      intent: item.intent,
+      intent: item.intent as Contracts.Intent.Any<M>,
       cursor,
       progress,
     }
@@ -69,24 +67,18 @@ export function serializeSnapshot<
  * - Browser `File` objects cannot be restored from persistence.
  * - We restore resumable items (those with a cursor) into the `paused` phase,
  *   with `file` left undefined. Your UI can ask the user to rebind the file.
+ * @author wildduck2 <https://github.com/wildduck2>
  */
 export function deserializeSnapshot<
-  M extends IntentMap,
-  C extends CursorMap<M>,
+  M extends Contracts.Intent.Map,
+  C extends Contracts.Cursor.Map<M>,
   P extends string,
-  R extends UploadResultBase,
->(
-  raw: unknown,
-  opts: {
-    isPurpose?: (value: string) => value is P
-    isIntent?: (value: unknown) => value is M[keyof M]
-    hasStrategy: (value: string) => boolean
-  },
-): UploadState<M, C, P, R> | null {
-  if (!opts.isPurpose || !opts.isIntent) return null
+  R extends Contracts.Result.Base,
+>(raw: unknown, opts: UploadPersistence.DeserializeContext<M, P>): Engine.State<M, C, P, R> | null {
+  if (!opts.isPurpose || !opts.isIntent || !opts.hasStrategy) return null
   if (!isPersistedSnapshot(raw)) return null
 
-  const items = new Map<string, UploadItem<M, C, P, R>>()
+  const items = new Map<string, Engine.Item<M, C, P, R>>()
 
   for (const value of Object.values(raw.items)) {
     const parsed = parsePersistedItem(value)
@@ -95,7 +87,9 @@ export function deserializeSnapshot<
     if (!opts.isPurpose(parsed.purpose)) continue
     if (!opts.isIntent(parsed.intent)) continue
 
-    const strategy = parsed.intent.strategy
+    const intentObj = parsed.intent
+    if (!isRecord(intentObj)) continue
+    const strategy = intentObj.strategy
     if (typeof strategy !== 'string' || !opts.hasStrategy(strategy)) continue
 
     if (!parsed.cursor || !isCursorForRegistry<C>(parsed.cursor, opts.hasStrategy)) continue
@@ -113,7 +107,7 @@ export function deserializeSnapshot<
     items.set(parsed.id, {
       phase: 'paused',
       localId: parsed.id,
-      purpose: parsed.purpose,
+      purpose: parsed.purpose as P,
       fingerprint: {
         name: parsed.file.name,
         size: parsed.file.size,
@@ -121,54 +115,66 @@ export function deserializeSnapshot<
         lastModified: parsed.file.lastModified,
         checksum: parsed.file.checksum,
       },
-      intent: parsed.intent as AnyIntent<M>,
+      intent: parsed.intent as Contracts.Intent.Any<M>,
       cursor: parsed.cursor,
       progress: { uploadedBytes, totalBytes, pct },
       pausedAt: Date.now(),
       createdAt: raw.createdAt ?? Date.now(),
       file: undefined,
-    } as UploadItem<M, C, P, R>)
+      steps: [],
+      meta: {},
+    } as Engine.Item<M, C, P, R>)
   }
 
   return { items }
 }
 
-function isPersistedSnapshot(value: unknown): value is PersistedSnapshot<unknown, unknown, string> {
+function isFiniteNumber(v: unknown): v is number {
+  return typeof v === 'number' && Number.isFinite(v)
+}
+
+function isPersistedSnapshot(
+  value: unknown,
+): value is UploadPersistence.Snapshot<Contracts.Intent.Map, Contracts.Cursor.Map<Contracts.Intent.Map>, string> {
   if (!isRecord(value)) return false
-  if (typeof value.version !== 'number') return false
-  if (typeof value.createdAt !== 'number') return false
-  return isRecord(value.items)
+  if (!isFiniteNumber(value['version'])) return false
+  if (!isFiniteNumber(value['createdAt'])) return false
+  return isRecord(value['items'])
 }
 
 function parsePersistedItem(value: unknown): {
   id: string
   purpose: string
   status: string
-  file: { name: string; size: number; type: string; lastModified: number; checksum?: string }
+  file: { name: string; size: number; type: string; lastModified: number; checksum?: string | undefined }
   intent: unknown
-  cursor?: unknown
-  progress?: { uploadedBytes: number; totalBytes: number; pct?: number }
+  cursor?: Contracts.Cursor.Any<Contracts.Cursor.Map<Contracts.Intent.Map>> | undefined
+  progress?: { uploadedBytes: number; totalBytes: number; pct?: number | undefined } | undefined
 } | null {
   if (!isRecord(value)) return null
 
-  const id = typeof value.id === 'string' ? value.id : null
-  const purpose = typeof value.purpose === 'string' ? value.purpose : null
-  const status = typeof value.status === 'string' ? value.status : null
-  const intent = value.intent
+  const id = typeof value['id'] === 'string' ? value['id'] : null
+  const purpose = typeof value['purpose'] === 'string' ? value['purpose'] : null
+  const status = typeof value['status'] === 'string' ? value['status'] : null
+  const intent = value['intent']
 
   if (!id || !purpose || !status) return null
 
-  if (!isRecord(value.file)) return null
+  const fileObj = value['file']
+  if (!isRecord(fileObj)) return null
 
-  const name = typeof value.file.name === 'string' ? value.file.name : null
-  const size = typeof value.file.size === 'number' ? value.file.size : null
-  const type = typeof value.file.type === 'string' ? value.file.type : null
-  const lastModified = typeof value.file.lastModified === 'number' ? value.file.lastModified : null
-  const checksum = typeof value.file.checksum === 'string' ? value.file.checksum : undefined
+  const name = typeof fileObj['name'] === 'string' ? fileObj['name'] : null
+  const rawSize = fileObj['size']
+  const size = isFiniteNumber(rawSize) && rawSize >= 0 ? rawSize : null
+  const type = typeof fileObj['type'] === 'string' ? fileObj['type'] : null
+  const rawLastModified = fileObj['lastModified']
+  const lastModified = isFiniteNumber(rawLastModified) ? rawLastModified : null
+  const checksum = typeof fileObj['checksum'] === 'string' ? fileObj['checksum'] : undefined
 
-  if (!name || size === null || !type || lastModified === null) return null
+  if (!name || size === null || type === null || lastModified === null) return null
 
-  const progress = parseProgress(value.progress)
+  const progress = parseProgress(value['progress'])
+  const cursor = value['cursor'] as Contracts.Cursor.Any<Contracts.Cursor.Map<Contracts.Intent.Map>> | undefined
 
   return {
     id,
@@ -176,24 +182,31 @@ function parsePersistedItem(value: unknown): {
     status,
     file: { name, size, type, lastModified, checksum },
     intent,
-    cursor: value.cursor,
+    cursor,
     progress,
   }
 }
 
-function parseProgress(value: unknown): { uploadedBytes: number; totalBytes: number; pct?: number } | undefined {
+function parseProgress(
+  value: unknown,
+): { uploadedBytes: number; totalBytes: number; pct?: number | undefined } | undefined {
   if (!isRecord(value)) return undefined
-  if (typeof value.uploadedBytes !== 'number' || typeof value.totalBytes !== 'number') return undefined
-  const pct = typeof value.pct === 'number' ? value.pct : undefined
-  return { uploadedBytes: value.uploadedBytes, totalBytes: value.totalBytes, pct }
+  const uploadedBytes = value['uploadedBytes']
+  const totalBytes = value['totalBytes']
+  if (!isFiniteNumber(uploadedBytes) || !isFiniteNumber(totalBytes)) return undefined
+  if (uploadedBytes < 0 || totalBytes < 0) return undefined
+  const rawPct = value['pct']
+  const pct = isFiniteNumber(rawPct) ? rawPct : undefined
+  return { uploadedBytes, totalBytes, pct }
 }
 
 function isCursorForRegistry<C extends Record<string, unknown>>(
   value: unknown,
   hasStrategy: (value: string) => boolean,
-): value is AnyCursor<C> {
+): value is Contracts.Cursor.Any<C> {
   if (!isRecord(value)) return false
-  if (typeof value.strategy !== 'string') return false
-  if (!hasStrategy(value.strategy)) return false
+  const strategy = value['strategy']
+  if (typeof strategy !== 'string') return false
+  if (!hasStrategy(strategy)) return false
   return true
 }

package/src/core/persistence/persistence.types.ts

@@ -1,66 +1,146 @@
+import type { Contracts } from '../contracts'
+import type { Engine } from '../engine/engine.types'
+
 /**
- * A minimal, serializable representation of an upload item that is safe to store
- * in persistence (LocalStorage, IndexedDB, etc).
- *
- * This type is intentionally not the full {@link UploadItem} state.
- * It captures only the fields needed to:
- * - restore the UI list after refresh
- * - rebind an upload to its backend intent (if already created)
- * - resume an upload strategy from a known cursor (when supported)
- * - restore last-known progress and phase for UX continuity
- *
- * @typeParam M - Map of upload intent variants keyed by intent kind (e.g. `direct`, `multipart`).
- * @typeParam C - Map of cursor shapes keyed by {@link M}'s intent kinds.
- * @typeParam P - Union of allowed `purpose` strings for your app (e.g. `"avatar" | "document"`).
+ * Persistence layer interfaces and options.
+ * @author wildduck2 <https://github.com/wildduck2>
  */
-export type PersistedSnapshot<M, C, P extends string> = {
-  /** Persistence schema version (not app version). */
-  version: number
-  /** Unix epoch milliseconds when this snapshot was written. */
-  createdAt: number
-  /** List of persisted upload items. */
-  items: Record<string, PersistedUploadItem<M, C, P>>
-}
+export namespace UploadPersistence {
+  /**
+   * Type context handed to deserializers to validate dynamic properties during recovery.
+   *
+   * @template M - Intent map type
+   * @template P - Purpose string union type
+   */
+  export type DeserializeContext<M extends Contracts.Intent.Map, P extends string> = {
+    /** Guard checking if a purpose string is valid. */
+    isPurpose?: ((value: string) => value is P) | undefined
+    /** Guard checking if an intent matches expected schemas. */
+    isIntent?: ((value: unknown) => value is M[keyof M]) | undefined
+    /** Query to verify if a strategy discriminant is active in runtime strategies. */
+    hasStrategy?: ((value: string) => boolean) | undefined
+  }
+
+  /**
+   * Configuration options for the upload store persistence manager.
+   *
+   * @template M - Intent map type
+   * @template C - Cursor map type
+   * @template P - Purpose string union type
+   * @template R - Backend result shape
+   */
+  export type Options<
+    M extends Contracts.Intent.Map,
+    C extends Contracts.Cursor.Map<M>,
+    P extends string,
+    R extends Contracts.Result.Base,
+  > = {
+    /** Target key used to store the serialized string representation of snapshots. */
+    key: string
+
+    /** Schema version identifier. Increment when changing models to run safe migrations. */
+    version: number
+
+    /** Milliseconds to wait before writing changes to disk (throttling storage writes). */
+    debounceMs?: number
+
+    /** Target storage adapter (e.g. LocalStorageAdapter, IndexedDBAdapter). */
+    adapter: Adapter
+
+    /**
+     * Optional custom serialization mapper.
+     */
+    serialize?: (state: Engine.State<M, C, P, R>, version: number) => Snapshot<M, C, P>
+
+    /**
+     * Optional custom deserialization mapper.
+     */
+    deserialize?: (raw: unknown, ctx: DeserializeContext<M, P>) => Engine.State<M, C, P, R> | null
+
+    /**
+     * Runtime validation guard for purpose strings. Required if using the default deserializer.
+     */
+    isPurpose?: ((value: string) => value is P) | undefined
 
-export type PersistedUploadItem<M, C, P extends string> = {
-  /** Stable, client-generated ID for this upload in local state. */
-  id: string
-  /** File name. */
-  file: {
-    /** 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
+    /**
+     * Runtime validation guard for intent objects. Required if using the default deserializer.
+     */
+    isIntent?: ((value: unknown) => value is M[keyof M]) | undefined
   }
-  /** Backend-provided "intent" that describes how to upload (strategy, URLs, fields, etc). */
-  intent: M[keyof M]
-  /** Strategy cursor used to resume uploads that support continuation. */
-  cursor?: import('../contracts').AnyCursor<C & Record<string, unknown>>
-  /** Last-known progress for UX continuity after restoring from persistence. */
-  progress?: { uploadedBytes: number; totalBytes: number; pct?: number }
-  /** The last known state-machine phase at the time of persistence. */
-  status: string
-  /** Logical purpose for the upload (application-defined). */
-  purpose: P
-}
 
-/**
- * A persisted snapshot of the upload store.
- *
- * Snapshots are versioned to allow safe migrations when the persistence schema evolves.
- * They are time-stamped for diagnostics and garbage-collection policies.
- */
-export interface PersistenceAdapter {
-  /** Loads a snapshot from persistence. */
-  load(key: string): unknown | null | Promise<unknown | null>
-  /** Saves a snapshot to persistence. */
-  save(key: string, snapshot: unknown): void | Promise<void>
-  /** Clears a snapshot from persistence. */
-  clear(key: string): void | Promise<void>
+  /**
+   * Plain-object representation of a stored upload item.
+   * Files cannot be fully serialized; hence their binary metadata is stashed.
+   */
+  export type PersistedItem<M extends Contracts.Intent.Map, C extends Contracts.Cursor.Map<M>, P extends string> = {
+    /** Unique client-side file identifier. */
+    id: string
+    /** Upload purpose. */
+    purpose: P
+    /** Target status phase key (e.g. `'uploading'`, `'paused'`). */
+    status: string
+    /** Serialized metadata of the file. */
+    file: {
+      /** Base name. */
+      name: string
+      /** Size in bytes. */
+      size: number
+      /** Claimed MIME type. */
+      type: string
+      /** Mod date timestamp in ms. */
+      lastModified: number
+      /** Checksum fingerprint hash if calculated. */
+      checksum?: string | undefined
+    }
+    /** The active backend intent payload. */
+    intent: Contracts.Intent.Any<M>
+    /** Strategy-defined resume cursor state. */
+    cursor?: Contracts.Cursor.Any<C> | undefined
+    /** Current progress measurements. */
+    progress?:
+      | {
+          uploadedBytes: number
+          totalBytes: number
+          pct?: number | undefined
+        }
+      | undefined
+  }
+
+  /**
+   * A minimal, serializable representation of an upload item that is safe to store
+   * in persistence (LocalStorage, IndexedDB, etc).
+   *
+   * @typeParam M - Map of upload intent variants keyed by intent kind (e.g. `direct`, `multipart`).
+   * @typeParam C - Map of cursor shapes keyed by {@link M}'s intent kinds.
+   * @typeParam P - Union of allowed `purpose` strings for your app (e.g. `"avatar" | "document"`).
+   */
+  export type Snapshot<M extends Contracts.Intent.Map, C extends Contracts.Cursor.Map<M>, P extends string> = {
+    /** Persistence schema version (not app version). */
+    version: number
+    /** Unix epoch milliseconds when this snapshot was written. */
+    createdAt: number
+    /** List of persisted upload items. */
+    items: Record<string, PersistedItem<M, C, P>>
+  }
+
+  /**
+   * Driver interface for persisting upload store snapshots.
+   */
+  export type Adapter = {
+    /**
+     * Resolves and returns the stored snapshot payload.
+     * Can return null if no snapshot exists.
+     */
+    load(key: string): unknown | null | Promise<unknown | null>
+
+    /**
+     * Saves a snapshot payload to the target storage location.
+     */
+    save(key: string, snapshot: unknown): void | Promise<void>
+
+    /**
+     * Deletes the snapshot record.
+     */
+    clear(key: string): void | Promise<void>
+  }
 }

package/src/core/utils/__tests__/guards.test.ts

@@ -0,0 +1,93 @@
+import { describe, expect, test } from 'vitest'
+import { isRecord, stripDangerousKeys } from '../guards'
+
+describe('stripDangerousKeys', () => {
+  test('removes top-level __proto__ / constructor / prototype', () => {
+    const raw = JSON.parse('{"__proto__":{"polluted":true},"a":1,"constructor":{"x":1},"prototype":{"y":2}}')
+    const out = stripDangerousKeys(raw)
+    expect(out).toEqual({ a: 1 })
+    expect(Object.prototype.hasOwnProperty.call(out, '__proto__')).toBe(false)
+    expect(Object.prototype.hasOwnProperty.call(out, 'constructor')).toBe(false)
+    expect(Object.prototype.hasOwnProperty.call(out, 'prototype')).toBe(false)
+  })
+
+  test('removes nested __proto__ inside plain branches', () => {
+    const raw = JSON.parse('{"items":{"a":{"__proto__":{"polluted":true},"v":1}}}')
+    const out = stripDangerousKeys(raw) as { items: { a: Record<string, unknown> } }
+    expect(out.items.a).toEqual({ v: 1 })
+  })
+
+  test('walks arrays', () => {
+    const raw = JSON.parse('{"list":[{"__proto__":{"x":1},"v":1},{"v":2}]}')
+    const out = stripDangerousKeys(raw) as { list: Array<Record<string, unknown>> }
+    expect(out.list[0]).toEqual({ v: 1 })
+    expect(out.list[1]).toEqual({ v: 2 })
+  })
+
+  test('depth cap of 16  does not throw on deeply nested input, returns input as-is past the cap', () => {
+    type Node = { child?: Node; v?: number; __proto__?: unknown }
+    let depth = 0
+    let leaf: Node = { v: 0 }
+    const root: Node = leaf
+    for (let i = 0; i < 20; i++) {
+      const next: Node = {}
+      leaf.child = next
+      leaf = next
+      depth++
+    }
+    // place a dangerous key beyond the depth cap (level 19 ≥ 16 → untouched)
+    const dangerousLeaf = JSON.parse('{"__proto__":{"polluted":true},"v":99}')
+    leaf.child = dangerousLeaf as Node
+    expect(() => stripDangerousKeys(root)).not.toThrow()
+    expect(depth).toBe(20)
+  })
+
+  test('does not pollute Object.prototype', () => {
+    const raw = JSON.parse('{"__proto__":{"polluted":true}}')
+    stripDangerousKeys(raw)
+    expect(({} as Record<string, unknown>)['polluted']).toBeUndefined()
+  })
+
+  test('leaves exotic objects (Date, Map) untouched', () => {
+    const d = new Date(0)
+    const m = new Map([['k', 1]])
+    const raw = { d, m, v: 1 } as Record<string, unknown>
+    const out = stripDangerousKeys(raw) as Record<string, unknown>
+    expect(out['d']).toBe(d)
+    expect(out['m']).toBe(m)
+    expect(out['v']).toBe(1)
+  })
+
+  test('returns primitives and null unchanged', () => {
+    expect(stripDangerousKeys(null as unknown)).toBe(null)
+    expect(stripDangerousKeys(42 as unknown)).toBe(42)
+    expect(stripDangerousKeys('s' as unknown)).toBe('s')
+  })
+})
+
+describe('isRecord (plain-record tightening)', () => {
+  test('rejects arrays', () => {
+    expect(isRecord([])).toBe(false)
+    expect(isRecord([1, 2])).toBe(false)
+  })
+
+  test('rejects Date', () => {
+    expect(isRecord(new Date())).toBe(false)
+  })
+
+  test('rejects Map', () => {
+    expect(isRecord(new Map())).toBe(false)
+  })
+
+  test('rejects class instances', () => {
+    class Thing {
+      a = 1
+    }
+    expect(isRecord(new Thing())).toBe(false)
+  })
+
+  test('accepts plain object literal and null-prototype object', () => {
+    expect(isRecord({ a: 1 })).toBe(true)
+    expect(isRecord(Object.create(null))).toBe(true)
+  })
+})