@themartiancompany/opfs 1.8.11

package/src/fs/opfs_core.ts

@@ -0,0 +1,413 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+/**    ----------------------------------------------------------------------
+ *     Copyright ©
+ *       Jiang Jie
+ *         2024, 2025
+ *       Pellegrino Prevete
+ *         2025
+ * 
+ *     All rights reserved
+ *     ----------------------------------------------------------------------
+ * 
+ *     This program is free software: you can redistribute it and/or modify
+ *     it under the terms of the GNU General Public License as published by
+ *     the Free Software Foundation, either version 3 of the License, or
+ *     (at your option) any later version.
+ * 
+ *     This program is distributed in the hope that it will be useful,
+ *     but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ *     GNU General Public License for more details.
+ * 
+ *     You should have received a copy of the GNU General Public License
+ *     along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+import { basename,
+         dirname,
+         join } from '@std/path/posix';
+import { Err,
+         Ok,
+         RESULT_VOID,
+         type AsyncIOResult,
+         type AsyncVoidIOResult } from 'happy-rusty';
+import { assertAbsolutePath } from './assertions.ts';
+import { NOT_FOUND_ERROR } from './constants.ts';
+import type { ReadDirEntry,
+              ReadDirOptions,
+              ReadFileContent,
+              ReadOptions,
+              WriteFileContent,
+              WriteOptions } from './defines.ts';
+import { getDirHandle,
+         getFileHandle,
+         isNotFoundError,
+         isRootPath } from './helpers.ts';
+import { isDirectoryHandle } from './utils.ts';
+
+/**
+ * Creates a new file at the specified path same as `touch`.
+ *
+ * @param filePath - The path of the file to create.
+ * @returns A promise that resolves to an `AsyncIOResult` indicating whether the file was successfully created.
+ */
+export async function
+  createFile(
+    filePath:
+      string):
+    AsyncVoidIOResult {
+    assertAbsolutePath(
+      filePath);
+    const
+      fileHandleRes =
+        await getFileHandle(
+          filePath,
+          { create:
+            true });
+    return fileHandleRes.and(
+      RESULT_VOID);
+}
+
+/**
+ * Creates a new directory at the specified path same as `mkdir -p`.
+ *
+ * @param dirPath - The path where the new directory will be created.
+ * @returns A promise that resolves to an `AsyncIOResult` indicating whether the directory was successfully created.
+ */
+export async function
+  mkdir(
+    dirPath:
+      string):
+    AsyncVoidIOResult {
+    assertAbsolutePath(
+      dirPath);
+    const
+      dirHandleRes =
+        await getDirHandle(
+          dirPath,
+          { create:
+              true,
+          });
+    return dirHandleRes.and(
+      RESULT_VOID);
+}
+
+/**
+ * Reads the contents of a directory at the specified path.
+ *
+ * @param dirPath - The path of the directory to read.
+ * @param options - Options of readdir.
+ * @returns A promise that resolves to an `AsyncIOResult` containing an async iterable iterator over the entries of the directory.
+ */
+export async function
+  readDir(
+    dirPath:
+      string,
+    options?:
+      ReadDirOptions):
+    AsyncIOResult<AsyncIterableIterator<ReadDirEntry>> {
+    assertAbsolutePath(
+      dirPath);
+    const
+      dirHandleRes =
+        await getDirHandle(
+          dirPath);
+    async function*
+      read(
+        dirHandle:
+          FileSystemDirectoryHandle,
+        subDirPath:
+          string):
+        AsyncIterableIterator<ReadDirEntry> {
+        const
+	  entries =
+            dirHandle.entries();
+        for await ( const [ name,
+                            handle ] of entries) {
+          // relative path from `dirPath`
+          const
+            path =
+              subDirPath === dirPath ? name : join(
+                                                subDirPath,
+                                                name);
+          yield {
+            path,
+            handle,
+          };
+          if ( isDirectoryHandle(
+                 handle) && options?.recursive ) {
+            yield* read(
+              await dirHandle.getDirectoryHandle(
+                name),
+                path);
+          }
+        }
+    }
+    return dirHandleRes.andThen(
+      x => Ok(
+             read(
+               x,
+               dirPath)));
+}
+
+/**
+ * Reads the content of a file at the specified path as a File.
+ *
+ * @param filePath - The path of the file to read.
+ * @param options - Read options specifying the 'blob' encoding.
+ * @returns A promise that resolves to an `AsyncIOResult` containing the file content as a File.
+ */
+export function
+  readFile(
+    filePath:
+      string,
+    options:
+      ReadOptions & { encoding:
+                        'blob'; }):
+    AsyncIOResult<File>;
+
+/**
+ * Reads the content of a file at the specified path as a string.
+ *
+ * @param filePath - The path of the file to read.
+ * @param options - Read options specifying the 'utf8' encoding.
+ * @returns A promise that resolves to an `AsyncIOResult` containing the file content as a string.
+ */
+export function
+  readFile(
+    filePath:
+      string,
+    options:
+      ReadOptions & { encoding:
+                        'utf8'; }):
+    AsyncIOResult<string>;
+
+/**
+ * Reads the content of a file at the specified path as an ArrayBuffer by default.
+ *
+ * @param filePath - The path of the file to read.
+ * @param options - Read options specifying the 'binary' encoding.
+ * @returns A promise that resolves to an `AsyncIOResult` containing the file content as an ArrayBuffer.
+ */
+export function
+  readFile(
+    filePath:
+      string,
+    options?:
+      ReadOptions & { encoding:
+                        'binary'; }):
+    AsyncIOResult<ArrayBuffer>;
+
+/**
+ * Reads the content of a file at the specified path with the specified options.
+ *
+ * @template T The type of the content to read from the file.
+ * @param filePath - The path of the file to read.
+ * @param options - Optional read options.
+ * @returns A promise that resolves to an `AsyncIOResult` containing the file content.
+ */
+export async function
+  readFile<T extends ReadFileContent>(
+    filePath:
+      string,
+    options?:
+      ReadOptions):
+    AsyncIOResult<T> {
+    assertAbsolutePath(
+      filePath);
+    const
+      fileHandleRes =
+        await getFileHandle(
+          filePath);
+    return fileHandleRes.andThenAsync(
+      async fileHandle => {
+        const
+          file =
+            await fileHandle.getFile();
+        switch ( options?.encoding ) {
+          case 'blob': {
+            return Ok(file as unknown as T);
+          }
+          case 'utf8': {
+            const
+              text =
+                await file.text();
+            return Ok(text as unknown as T);
+          }
+          default: {
+              const
+                data =
+                  await file.arrayBuffer();
+              return Ok(data as unknown as T);
+          }
+        }
+    });
+}
+
+/**
+ * Removes a file or directory at the specified path same as `rm -rf`.
+ *
+ * @param path - The path of the file or directory to remove.
+ * @returns A promise that resolves to an `AsyncIOResult` indicating whether the file or directory was successfully removed.
+ */
+export async function
+  remove(
+    path:
+      string):
+    AsyncVoidIOResult {
+    assertAbsolutePath(
+      path);
+    const
+      dirPath =
+        dirname(
+          path);
+    const
+      childName =
+        basename(
+          path);
+    const
+      dirHandleRes =
+        await getDirHandle(
+          dirPath);
+    return ( await dirHandleRes.andThenAsync(
+               async (
+                 dirHandle):
+                 AsyncVoidIOResult => {
+                 try {
+                   // root
+                   if ( isRootPath(
+                          dirPath) &&
+                        isRootPath(
+                          childName) ) {
+                     // TODO ts not support yet
+                     // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                     await ( dirHandle as any ).remove(
+                       { recursive:
+                           true });
+                   } else {
+                       await dirHandle.removeEntry(
+                         childName,
+                           { recursive:
+                               true });
+                   }
+                 } catch (
+                     _error) {
+                     return Err(_error as DOMException);
+                 }
+                 return RESULT_VOID;
+               })).orElse<Error>(
+                 _error => {
+                   // not found as success
+                   return isNotFoundError(
+                          _error) ? RESULT_VOID : Err(
+                                                    _error);
+               });
+}
+
+/**
+ * Retrieves the status of a file or directory at the specified path.
+ *
+ * @param path - The path of the file or directory to retrieve status for.
+ * @returns A promise that resolves to an `AsyncIOResult` containing the `FileSystemHandle`.
+ */
+export async function
+  stat(
+    path:
+      string):
+    AsyncIOResult<FileSystemHandle> {
+    assertAbsolutePath(
+      path);
+    const
+      dirPath =
+        dirname(
+          path);
+    const
+      childName =
+        basename(
+          path);
+    const
+      dirHandleRes =
+        await getDirHandle(
+          dirPath);
+    if ( !childName ) {
+        // root
+        return dirHandleRes;
+    }
+    return dirHandleRes.andThenAsync(
+      async dirHandle => {
+        // currently only rely on traversal inspection
+        for await ( const [ name,
+                            handle] of dirHandle.entries() ) {
+          if ( name === childName ) {
+            return Ok(
+              handle);
+          }
+        }
+        const
+          err =
+            new Error(
+              `${ NOT_FOUND_ERROR }: '${ childName }' ` +
+              `does not exist. Full path is '${ path }'.`);
+        err.name =
+          NOT_FOUND_ERROR;
+        return Err(
+          err);
+    });
+}
+
+/**
+ * Writes content to a file at the specified path.
+ *
+ * @param filePath - The path of the file to write to.
+ * @param contents - The content to write to the file.
+ * @param options - Optional write options.
+ * @returns A promise that resolves to an `AsyncIOResult` indicating whether the file was successfully written.
+ */
+export async function
+  writeFile(
+    filePath:
+      string,
+    contents:
+      WriteFileContent,
+    options?:
+      WriteOptions):
+    AsyncVoidIOResult {
+    assertAbsolutePath(
+      filePath);
+    // create as default
+    const { append = false, create = true } = options ?? {};
+    const
+      fileHandleRes =
+        await getFileHandle(
+          filePath,
+          { create });
+    return fileHandleRes.andThenAsync(
+      async fileHandle => {
+        const
+          writable =
+            await fileHandle.createWritable(
+              { keepExistingData:
+                  append });
+        const
+          params:
+            WriteParams =
+              { type:
+                  'write',
+                data:
+                  contents,
+              };
+        // append?
+        if ( append ) {
+          const
+            { size } =
+              await fileHandle.getFile();
+          params.position =
+            size;
+        }
+        await writable.write(
+          params);
+        await writable.close();
+        return RESULT_VOID;
+    });
+}

package/src/fs/opfs_download.ts

@@ -0,0 +1,174 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+/**    ----------------------------------------------------------------------
+ *     Copyright ©
+ *       Jiang Jie
+ *         2024, 2025
+ *       Pellegrino Prevete
+ *         2025
+ * 
+ *     All rights reserved
+ *     ----------------------------------------------------------------------
+ * 
+ *     This program is free software: you can redistribute it and/or modify
+ *     it under the terms of the GNU General Public License as published by
+ *     the Free Software Foundation, either version 3 of the License, or
+ *     (at your option) any later version.
+ * 
+ *     This program is distributed in the hope that it will be useful,
+ *     but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ *     GNU General Public License for more details.
+ * 
+ *     You should have received a copy of the GNU General Public License
+ *     along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+import { fetchT,
+         type FetchResponse,
+         type FetchTask } from '@happy-ts/fetch-t';
+import { extname } from '@std/path/posix';
+import { Err,
+         Ok } from 'happy-rusty';
+import { assertAbsolutePath,
+         assertFileUrl } from './assertions.ts';
+import type { DownloadFileTempResponse,
+              FsRequestInit } from './defines.ts';
+import { createAbortError } from './helpers.ts';
+import { writeFile } from './opfs_core.ts';
+import { generateTempPath } from './utils.ts';
+
+/**
+ * Downloads a file from a URL and saves it to a temporary file.
+ * The returned response will contain the temporary file path.
+ *
+ * @param fileUrl - The URL of the file to download.
+ * @param requestInit - Optional request initialization parameters.
+ * @returns A task that can be aborted and contains the result of the download.
+ */
+export function
+  downloadFile(
+    fileUrl:
+      string,
+    requestInit?:
+      FsRequestInit):
+    FetchTask<DownloadFileTempResponse>;
+
+/**
+ * Downloads a file from a URL and saves it to the specified path.
+ *
+ * @param fileUrl - The URL of the file to download.
+ * @param filePath - The path where the downloaded file will be saved.
+ * @param requestInit - Optional request initialization parameters.
+ * @returns A task that can be aborted and contains the result of the download.
+ */
+export function
+  downloadFile(
+    fileUrl:
+      string,
+    filePath:
+      string,
+    requestInit?:
+      FsRequestInit):
+    FetchTask<Response>;
+export function
+  downloadFile(
+    fileUrl:
+      string,
+    filePath?:
+      string | FsRequestInit,
+    requestInit?:
+      FsRequestInit):
+    FetchTask<Response | DownloadFileTempResponse> {
+    let
+      aborted:
+        boolean,
+      saveToTemp;
+    assertFileUrl(
+      fileUrl);
+    saveToTemp =
+      false;
+    if ( typeof filePath === 'string' ) {
+        assertAbsolutePath(
+          filePath);
+    }
+    else {
+      requestInit =
+        filePath;
+      // save to a temporary file, reserve the extension
+      filePath =
+        generateTempPath(
+          { extname:
+              extname(
+                fileUrl) });
+      saveToTemp =
+        true;
+    }
+    aborted =
+      false;
+    const
+      fetchTask =
+        fetchT(
+          fileUrl,
+          { redirect:
+              'follow',
+            ...requestInit,
+            abortable:
+              true });
+    const
+      response =
+        ( async ():
+            FetchResponse<Response> => {
+            const
+              responseRes =
+                await fetchTask.response;
+            return responseRes.andThenAsync(
+              async response => {
+                const
+                  blob =
+                    await response.blob();
+                // maybe aborted
+                if ( aborted ) {
+                  return Err(
+                    createAbortError());
+                }
+                const
+                  writeRes =
+                    await writeFile(filePath, blob);
+                return writeRes.and(
+                  Ok(response));
+              });
+    })();
+    return {
+      abort(
+        reason?:
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+          any):
+        void {
+        aborted =
+          true;
+        fetchTask.abort(
+          reason);
+        },
+      get aborted():
+        boolean {
+        return aborted;
+      },
+      get response():
+        FetchResponse<Response | DownloadFileTempResponse> {
+        return saveToTemp ?
+               response.then(
+                 res => {
+                   return res.map<DownloadFileTempResponse>(
+                     rawResponse => {
+                       return {
+                           tempFilePath:
+                             filePath,
+                           rawResponse,
+                       };
+                     });
+                 }) :
+               response;
+      },
+    };
+}