feat: add appendExistingFiles to unify multi-source file tracking (#45)

Adds appendExistingFiles method to useUploadKit for appending pre-existing
remote files without replacing current files. Eliminates need for separate
file arrays when combining files from local picker, media library, and other
sources into a single managed collection.

Key features:
- Deduplicates by storageKey to prevent duplicates
- Respects maxFiles limit
- Emits file:added for consistency with other file operations
- Returns files actually added for UI feedback

Includes comprehensive tests covering edge cases and integration with
existing features like removeFile and upload.

Documentation updated with usage examples and comparison to initializeExistingFiles.

Co-authored-by: Claude Haiku 4.5 <noreply@anthropic.com>

Author: genu

docs/content/2.usage/1.overview.md

@@ -206,15 +206,35 @@ uploader.reorderFile(0, 2) // Move first file to third position
 
 ### Initialization
 
-#### `initializeExistingFiles(files: Partial<UploadFile>[]): Promise<void>`
+#### `initializeExistingFiles(files: InitialFileInput[]): Promise<void>`
 
-Load existing files (e.g., from a database) into the uploader.
+Load existing files (e.g., from a database) into the uploader. **Replaces** the current file list.
 
 ```ts
 // Load previously uploaded files
-await uploader.initializeExistingFiles([{ id: "existing-file-1.jpg" }, { id: "existing-file-2.png" }])
+await uploader.initializeExistingFiles([{ storageKey: "uploads/file-1.jpg" }, { storageKey: "uploads/file-2.png" }])
 ```
 
+#### `appendExistingFiles(files: InitialFileInput[]): Promise<UploadFile[]>`
+
+Append pre-existing remote files **without replacing** current files. Returns the files that were actually added.
+
+- Skips files already present (matched by `storageKey`)
+- Respects `maxFiles` limit
+- Emits `file:added` for each appended file
+
+```ts
+// User picks files from a media library — inject them into the upload manager
+const added = await uploader.appendExistingFiles([
+  { storageKey: "library/photo-1.jpg" },
+  { storageKey: "library/photo-2.jpg" },
+])
+
+console.log(`${added.length} files added`)
+```
+
+This is useful when files come from multiple sources (local picker, media library, external integrations) and you want all files managed as first-class citizens in a single `files` ref.
+
 ### Plugins
 
 #### `addPlugin(plugin: Plugin): void`

docs/content/5.advanced/4.lifecycle.md

@@ -180,8 +180,11 @@ This:
 Load files from your database:
 
 ```ts
-// Provide file IDs
-await uploader.initializeExistingFiles([{ id: "path/to/file1.jpg" }, { id: "path/to/file2.png", preview: "custom-preview-url" }])
+// Replaces the file list with these remote files
+await uploader.initializeExistingFiles([
+  { storageKey: "path/to/file1.jpg" },
+  { storageKey: "path/to/file2.png" },
+])
 ```
 
 The storage plugin's `getRemoteFile` hook fetches metadata:
@@ -196,6 +199,33 @@ The storage plugin's `getRemoteFile` hook fetches metadata:
 }
 ```
 
+## Appending Existing Files
+
+Use `appendExistingFiles` when you need to add remote files **alongside** files the user has already selected — for example, when a user picks items from a media library:
+
+```ts
+// User already added local files via file picker
+await uploader.addFiles(localFiles)
+
+// Later, user picks files from a media library
+const added = await uploader.appendExistingFiles([
+  { storageKey: "library/photo-1.jpg" },
+  { storageKey: "library/photo-2.jpg" },
+])
+```
+
+Key differences from `initializeExistingFiles`:
+
+| | `initializeExistingFiles` | `appendExistingFiles` |
+|---|---|---|
+| **Behavior** | Replaces all files | Adds to existing files |
+| **Deduplication** | No | Skips files already present by `storageKey` |
+| **maxFiles** | Not checked | Respected (truncates to fit) |
+| **Events** | None | Emits `file:added` per file |
+| **Returns** | `void` | `UploadFile[]` (files actually added) |
+
+This lets all files — local, remote, from any source — live as first-class citizens in a single `files` ref, eliminating the need for separate tracking arrays.
+
 ## Memory Management
 
 Nuxt Upload Kit automatically manages memory:

src/runtime/composables/useUploadKit/index.ts

@@ -132,17 +132,20 @@ export const useUploadKit = <TUploadResult = any>(_options: UploadOptions = {})
     files.value = files.value.map((file) => (file.id === fileId ? ({ ...file, ...updatedFile } as UploadFile) : file))
   }
 
-  const initializeExistingFiles = async (initialFiles: InitialFileInput[]) => {
-    const initializedfiles = await Promise.all(
+  /**
+   * Resolve an array of InitialFileInput into RemoteUploadFile objects via the storage plugin.
+   */
+  const resolveRemoteFiles = async (initialFiles: InitialFileInput[]): Promise<UploadFile<TUploadResult>[]> => {
+    const storagePlugin = getStoragePlugin()
+    if (!storagePlugin?.hooks.getRemoteFile) {
+      throw new Error("Storage plugin with getRemoteFile hook is required to resolve remote files")
+    }
+
+    const resolved = await Promise.all(
       initialFiles.map(async (file) => {
         const storageKey = file.storageKey
         if (!storageKey) return null
 
-        const storagePlugin = getStoragePlugin()
-        if (!storagePlugin?.hooks.getRemoteFile) {
-          throw new Error("Storage plugin with getRemoteFile hook is required to initialize existing files")
-        }
-
         const context = createPluginContext(storagePlugin.id, files.value, options, emitter, storagePlugin)
         const remoteFileData = await storagePlugin.hooks.getRemoteFile(storageKey, context)
 
@@ -170,8 +173,41 @@ export const useUploadKit = <TUploadResult = any>(_options: UploadOptions = {})
       }),
     )
 
-    const filteredFiles = initializedfiles.filter((f) => f !== null) as UploadFile[]
-    files.value = [...filteredFiles]
+    return resolved.filter((f) => f !== null) as UploadFile<TUploadResult>[]
+  }
+
+  const initializeExistingFiles = async (initialFiles: InitialFileInput[]) => {
+    const resolvedFiles = await resolveRemoteFiles(initialFiles)
+    files.value = [...resolvedFiles]
+  }
+
+  /**
+   * Append pre-existing remote files without replacing current files.
+   * Skips files already present (matched by storageKey) and respects maxFiles.
+   */
+  const appendExistingFiles = async (initialFiles: InitialFileInput[]): Promise<UploadFile<TUploadResult>[]> => {
+    // Deduplicate: skip files already present by storageKey
+    const existingKeys = new Set(files.value.map((f) => f.storageKey).filter(Boolean))
+    let filesToAdd = initialFiles.filter((f) => f.storageKey && !existingKeys.has(f.storageKey))
+
+    if (filesToAdd.length === 0) return []
+
+    // Respect maxFiles limit
+    if (options.maxFiles !== false && options.maxFiles !== undefined) {
+      const available = options.maxFiles - files.value.length
+      if (available <= 0) return []
+      filesToAdd = filesToAdd.slice(0, available)
+    }
+
+    const resolvedFiles = await resolveRemoteFiles(filesToAdd)
+
+    files.value.push(...resolvedFiles)
+
+    resolvedFiles.forEach((file) => {
+      emitter.emit("file:added", file)
+    })
+
+    return resolvedFiles
   }
 
   const addFile = async (file: File) => {
@@ -359,6 +395,7 @@ export const useUploadKit = <TUploadResult = any>(_options: UploadOptions = {})
     replaceFileData: fileOps.replaceFileData,
     updateFile,
     initializeExistingFiles,
+    appendExistingFiles,
 
     // Utilities
     addPlugin,

test/unit/useUploadKit.test.ts

@@ -789,6 +789,211 @@ describe("useUploadKit", () => {
     })
   })
 
+  describe("appendExistingFiles", () => {
+    const defaultGetRemoteFileFn = async (storageKey: string) => ({
+      size: 2048,
+      mimeType: storageKey.endsWith(".png") ? "image/png" : "image/jpeg",
+      remoteUrl: `https://storage.example.com/${storageKey}`,
+    })
+
+    it("should append remote files without replacing existing local files", async () => {
+      const storage = createMockStoragePlugin({ getRemoteFileFn: defaultGetRemoteFileFn })
+      const uploader = useUploadKit({ storage })
+
+      await uploader.addFile(createMockFile("local.jpg"))
+      const added = await uploader.appendExistingFiles([{ storageKey: "remote-1.png" }, { storageKey: "remote-2.png" }])
+
+      expect(added).toHaveLength(2)
+      expect(uploader.files.value).toHaveLength(3)
+
+      // Original local file preserved at index 0
+      expect(uploader.files.value[0]!.source).toBe("local")
+      expect(uploader.files.value[0]!.name).toBe("local.jpg")
+
+      // Appended files are complete remote files
+      const appended = uploader.files.value.slice(1)
+      for (const file of appended) {
+        expect(file.source).toBe("storage")
+        expect(file.status).toBe("complete")
+        expect(file.progress.percentage).toBe(100)
+        expect(file.data).toBeNull()
+        expect(file.remoteUrl).toMatch(/^https:\/\/storage\.example\.com\//)
+      }
+    })
+
+    it("should set correct metadata from storage plugin on appended files", async () => {
+      const storage = createMockStoragePlugin({
+        getRemoteFileFn: async (storageKey) => ({
+          size: 4096,
+          mimeType: "image/webp",
+          remoteUrl: `https://cdn.example.com/${storageKey}`,
+          preview: `https://cdn.example.com/thumbs/${storageKey}`,
+          uploadResult: { storageKey, bucket: "media" },
+        }),
+      })
+      const uploader = useUploadKit({ storage })
+
+      const added = await uploader.appendExistingFiles([{ storageKey: "photos/pic.webp" }])
+
+      expect(added).toHaveLength(1)
+      const file = added[0]!
+      expect(file.size).toBe(4096)
+      expect(file.mimeType).toBe("image/webp")
+      expect(file.name).toBe("pic.webp")
+      expect(file.storageKey).toBe("photos/pic.webp")
+      expect(file.remoteUrl).toBe("https://cdn.example.com/photos/pic.webp")
+      expect(file.preview).toBe("https://cdn.example.com/thumbs/photos/pic.webp")
+      expect(file.uploadResult).toEqual({ storageKey: "photos/pic.webp", bucket: "media" })
+    })
+
+    it("should skip duplicates already present by storageKey", async () => {
+      const getRemoteFileFn = vi.fn(defaultGetRemoteFileFn)
+      const storage = createMockStoragePlugin({ getRemoteFileFn })
+      const uploader = useUploadKit({ storage })
+
+      await uploader.initializeExistingFiles([{ storageKey: "existing.png" }])
+      getRemoteFileFn.mockClear()
+
+      const added = await uploader.appendExistingFiles([{ storageKey: "existing.png" }, { storageKey: "new.png" }])
+
+      expect(added).toHaveLength(1)
+      expect(added[0]!.storageKey).toBe("new.png")
+      expect(uploader.files.value).toHaveLength(2)
+      // Should only call getRemoteFile for the non-duplicate
+      expect(getRemoteFileFn).toHaveBeenCalledTimes(1)
+      expect(getRemoteFileFn).toHaveBeenCalledWith("new.png")
+    })
+
+    it("should deduplicate against uploaded local files that have storageKey", async () => {
+      const storage = createMockStoragePlugin({
+        getRemoteFileFn: defaultGetRemoteFileFn,
+        uploadFn: async () => ({
+          url: "https://storage.example.com/uploads/local.jpg",
+          storageKey: "uploads/local.jpg",
+        }),
+      })
+      const uploader = useUploadKit({ storage })
+
+      // Add and upload a local file so it gets a storageKey
+      await uploader.addFile(createMockFile("local.jpg"))
+      await uploader.upload()
+      expect(uploader.files.value[0]!.storageKey).toBe("uploads/local.jpg")
+
+      // Appending the same storageKey should be deduplicated
+      const added = await uploader.appendExistingFiles([{ storageKey: "uploads/local.jpg" }])
+
+      expect(added).toHaveLength(0)
+      expect(uploader.files.value).toHaveLength(1)
+    })
+
+    it("should respect maxFiles limit and preserve insertion order", async () => {
+      const storage = createMockStoragePlugin({ getRemoteFileFn: defaultGetRemoteFileFn })
+      const uploader = useUploadKit({ storage, maxFiles: 3 })
+
+      await uploader.addFile(createMockFile("file1.jpg"))
+      await uploader.addFile(createMockFile("file2.jpg"))
+
+      // Only 1 slot available — should take the first from the input
+      const added = await uploader.appendExistingFiles([
+        { storageKey: "remote-1.jpg" },
+        { storageKey: "remote-2.jpg" },
+        { storageKey: "remote-3.jpg" },
+      ])
+
+      expect(added).toHaveLength(1)
+      expect(added[0]!.storageKey).toBe("remote-1.jpg")
+      expect(uploader.files.value).toHaveLength(3)
+    })
+
+    it("should return empty array when maxFiles is already reached", async () => {
+      const getRemoteFileFn = vi.fn(defaultGetRemoteFileFn)
+      const storage = createMockStoragePlugin({ getRemoteFileFn })
+      const uploader = useUploadKit({ storage, maxFiles: 1 })
+
+      await uploader.addFile(createMockFile("file1.jpg"))
+      getRemoteFileFn.mockClear()
+
+      const added = await uploader.appendExistingFiles([{ storageKey: "remote-1.jpg" }])
+
+      expect(added).toHaveLength(0)
+      // Should not make any network calls when limit is reached
+      expect(getRemoteFileFn).not.toHaveBeenCalled()
+    })
+
+    it("should emit file:added for each appended file", async () => {
+      const storage = createMockStoragePlugin({ getRemoteFileFn: defaultGetRemoteFileFn })
+      const uploader = useUploadKit({ storage })
+      const handler = vi.fn()
+
+      uploader.on("file:added", handler)
+      await uploader.appendExistingFiles([{ storageKey: "remote-1.jpg" }, { storageKey: "remote-2.jpg" }])
+
+      expect(handler).toHaveBeenCalledTimes(2)
+      expect(handler).toHaveBeenCalledWith(expect.objectContaining({ storageKey: "remote-1.jpg" }))
+      expect(handler).toHaveBeenCalledWith(expect.objectContaining({ storageKey: "remote-2.jpg" }))
+    })
+
+    it("should not emit file:added when all files are duplicates", async () => {
+      const storage = createMockStoragePlugin({ getRemoteFileFn: defaultGetRemoteFileFn })
+      const uploader = useUploadKit({ storage })
+
+      await uploader.initializeExistingFiles([{ storageKey: "file-a.jpg" }])
+
+      const handler = vi.fn()
+      uploader.on("file:added", handler)
+      const added = await uploader.appendExistingFiles([{ storageKey: "file-a.jpg" }])
+
+      expect(added).toHaveLength(0)
+      expect(handler).not.toHaveBeenCalled()
+    })
+
+    it("should handle multiple sequential appends correctly", async () => {
+      const storage = createMockStoragePlugin({ getRemoteFileFn: defaultGetRemoteFileFn })
+      const uploader = useUploadKit({ storage })
+
+      await uploader.appendExistingFiles([{ storageKey: "batch-1.jpg" }])
+      await uploader.appendExistingFiles([{ storageKey: "batch-2.jpg" }])
+      await uploader.appendExistingFiles([{ storageKey: "batch-1.jpg" }, { storageKey: "batch-3.jpg" }])
+
+      expect(uploader.files.value).toHaveLength(3)
+      expect(uploader.files.value.map((f) => f.storageKey)).toEqual(["batch-1.jpg", "batch-2.jpg", "batch-3.jpg"])
+    })
+
+    it("should throw if no storage plugin with getRemoteFile is configured", async () => {
+      const uploader = useUploadKit()
+
+      await expect(uploader.appendExistingFiles([{ storageKey: "remote.jpg" }])).rejects.toThrow(
+        "Storage plugin with getRemoteFile hook is required",
+      )
+    })
+
+    it("should skip entries with empty storageKey without calling storage", async () => {
+      const getRemoteFileFn = vi.fn(defaultGetRemoteFileFn)
+      const storage = createMockStoragePlugin({ getRemoteFileFn })
+      const uploader = useUploadKit({ storage })
+
+      const added = await uploader.appendExistingFiles([{ storageKey: "" }, { storageKey: "valid.jpg" }])
+
+      expect(added).toHaveLength(1)
+      expect(added[0]!.storageKey).toBe("valid.jpg")
+      expect(getRemoteFileFn).toHaveBeenCalledTimes(1)
+    })
+
+    it("should allow removal of appended files via removeFile", async () => {
+      const removeHook = vi.fn()
+      const storage = createMockStoragePlugin({ getRemoteFileFn: defaultGetRemoteFileFn, removeFn: removeHook })
+      const uploader = useUploadKit({ storage })
+
+      const added = await uploader.appendExistingFiles([{ storageKey: "library/photo.jpg" }])
+      expect(uploader.files.value).toHaveLength(1)
+
+      await uploader.removeFile(added[0]!.id)
+
+      expect(uploader.files.value).toHaveLength(0)
+      expect(removeHook).toHaveBeenCalledWith(expect.objectContaining({ storageKey: "library/photo.jpg" }))
+    })
+  })
+
   describe("event system", () => {
     it("should allow registering and receiving events", async () => {
       const uploader = useUploadKit()