refactor!: split file handles into seperate function

Signed-off-by: Jon Koops <[email protected]>

BREAKING CHANGE: Arrays of `FileSystemFileHandle` are now handled in a dedicated `fromFileHandles()` function.

Author: jonkoops

README.md

@@ -107,16 +107,13 @@ input.addEventListener("change", async (event) => {
 Convert [FileSystemFileHandle](https://developer.mozilla.org/en-US/docs/Web/API/FileSystemFileHandle) items to File objects:
 
 ```js
-import { fromEvent } from "file-selector";
+import { fromFileHandles } from "file-selector";
 
 const handles = await window.showOpenFilePicker({ multiple: true });
-const files = await fromEvent(handles);
+const files = await fromFileHandles(handles);
 console.log(files);
 ```
 
-> [!NOTE]
-> The above is experimental and subject to change.
-
 ## Browser Support
 
 Most browser support basic File selection with drag 'n' drop or file input:

src/file-selector.spec.ts

@@ -1,5 +1,5 @@
 import { FileWithPath } from "./file.js";
-import { fromEvent } from "./file-selector.js";
+import { fromEvent, fromFileHandles } from "./file-selector.js";
 
 it("returns a Promise", async () => {
   const evt = new Event("test");
@@ -46,27 +46,29 @@ it("should return an empty array if the evt {target} has no {files} prop", async
   expect(files).toHaveLength(0);
 });
 
-it("should return files if the arg is a list of FileSystemFileHandle", async () => {
-  const name = "test.json";
-  const [mockFile, mockHandle] = createFileSystemFileHandle(
-    name,
-    { ping: true },
-    {
-      type: "application/json",
-    },
-  );
+describe("fromFileHandles", () => {
+  it("retrieves files from file handles", async () => {
+    const name = "test.json";
+    const [mockFile, mockHandle] = createFileSystemFileHandle(
+      name,
+      { ping: true },
+      {
+        type: "application/json",
+      },
+    );
 
-  const files = await fromEvent([mockHandle]);
-  expect(files).toHaveLength(1);
-  expect(files.every((file) => file instanceof File)).toBe(true);
+    const files = await fromFileHandles([mockHandle]);
+    expect(files).toHaveLength(1);
+    expect(files.every((file) => file instanceof File)).toBe(true);
 
-  const [file] = files as FileWithPath[];
+    const [file] = files as FileWithPath[];
 
-  expect(file.name).toBe(mockFile.name);
-  expect(file.type).toBe(mockFile.type);
-  expect(file.size).toBe(mockFile.size);
-  expect(file.lastModified).toBe(mockFile.lastModified);
-  expect(file.path).toBe(`./${name}`);
+    expect(file.name).toBe(mockFile.name);
+    expect(file.type).toBe(mockFile.type);
+    expect(file.size).toBe(mockFile.size);
+    expect(file.lastModified).toBe(mockFile.lastModified);
+    expect(file.path).toBe(`./${name}`);
+  });
 });
 
 it("should return an empty array if the passed event is not a DragEvent", async () => {

src/file-selector.ts

@@ -11,9 +11,6 @@ const FILES_TO_IGNORE = [
  * NOTE: If some of the items are folders,
  * everything will be flattened and placed in the same list but the paths will be kept as a {path} property.
  *
- * EXPERIMENTAL: A list of https://developer.mozilla.org/en-US/docs/Web/API/FileSystemHandle objects can also be passed as an arg
- * and a list of File objects will be returned.
- *
  * @param evt
  */
 export async function fromEvent(
@@ -23,11 +20,6 @@ export async function fromEvent(
     return getDataTransferFiles(evt.dataTransfer, evt.type);
   } else if (isChangeEvt(evt)) {
     return getInputFiles(evt);
-  } else if (
-    Array.isArray(evt) &&
-    evt.every((item) => "getFile" in item && typeof item.getFile === "function")
-  ) {
-    return getFsHandleFiles(evt);
   }
   return [];
 }
@@ -52,10 +44,32 @@ function getInputFiles(event: Event): FileWithPath[] {
   return Array.from(event.target.files).map((file) => toFileWithPath(file));
 }
 
-// Ee expect each handle to be https://developer.mozilla.org/en-US/docs/Web/API/FileSystemFileHandle
-async function getFsHandleFiles(handles: any[]) {
-  const files = await Promise.all(handles.map((h) => h.getFile()));
-  return files.map((file) => toFileWithPath(file));
+/**
+ * Retrieves files from an array of `FileSystemHandle` objects from the File System API.
+ *
+ * @param handles The array of handles to convert.
+ * @returns A promise that resolves to an array of files retrieved from the handles.
+ *
+ * @example
+ * ```js
+ * const handles = await window.showOpenFilePicker({ multiple: true });
+ * const files = await fromFileHandles(handles);
+ * ```
+ *
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/File_System_API|MDN - File System API}
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/FileSystemHandle|MDN - `FileSystemHandle`}
+ */
+export function fromFileHandles(
+  handles: FileSystemFileHandle[],
+): Promise<FileWithPath[]> {
+  return Promise.all(handles.map((handle) => fromFileHandle(handle)));
+}
+
+async function fromFileHandle(
+  handle: FileSystemFileHandle,
+): Promise<FileWithPath> {
+  const file = await handle.getFile();
+  return toFileWithPath(file);
 }
 
 async function getDataTransferFiles(dataTransfer: DataTransfer, type: string) {

src/index.ts

@@ -1,2 +1,2 @@
-export { fromEvent } from "./file-selector.js";
+export { fromEvent, fromFileHandles } from "./file-selector.js";
 export { FileWithPath } from "./file.js";