@themartiancompany/opfs 1.8.11

package/src/fs/defines.ts

@@ -0,0 +1,352 @@
+// 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 type { FetchInit } from '@happy-ts/fetch-t';
+
+/**
+ * Represents the possible content types that can be written to a file.
+ */
+export type WriteFileContent =
+  BufferSource |
+  Blob |
+  string;
+
+/**
+ * Represents the possible content types that can be
+ * written synchronously to a file.
+ */
+export type WriteSyncFileContent =
+  BufferSource |
+  string;
+
+/**
+ * Represents the possible content types that can be read from a file.
+ */
+export type ReadFileContent =
+  ArrayBuffer |
+  File |
+  string;
+
+/**
+ * Options for reading files with specified encoding.
+ */
+export interface ReadOptions {
+  /**
+   * The encoding to use for reading the file's content.
+   * @defaultValue `'binary'`
+   */
+  encoding?:
+    FileEncoding;
+}
+
+/**
+ * Options for writing files, including flags for creation
+ * and appending.
+ */
+export interface WriteOptions {
+  /**
+   * Whether to create the file if it does not exist.
+   * @defaultValue `true`
+   */
+  create?:
+    boolean;
+  /**
+   * Whether to append to the file if it already exists.
+   * @defaultValue `false`
+   */
+  append?:
+    boolean;
+}
+
+/**
+ * Options to determine the existence of a file or directory.
+ */
+export interface ExistsOptions {
+  /**
+   * Whether to check for the existence of a directory.
+   * @defaultValue `false`
+   */
+  isDirectory?:
+    boolean;
+  /**
+   * Whether to check for the existence of a file.
+   * @defaultValue `false`
+   */
+  isFile?:
+    boolean;
+}
+
+/**
+ * Supported file encodings for reading and writing files.
+ */
+export type FileEncoding =
+  'binary' |
+  'utf8' |
+  'blob';
+
+/**
+ * fetch-t options for download and upload.
+ */
+export type FsRequestInit =
+  Omit<FetchInit,
+       'abortable' |
+       'responseType'>
+
+/**
+ * fetch-t request options for uploading files.
+ */
+export interface UploadRequestInit extends FsRequestInit {
+  /**
+   * The filename to use when uploading the file.
+   */
+  filename?:
+    string;
+}
+
+/**
+ * Options for reading directories.
+ */
+export interface ReadDirOptions {
+  /**
+   * Whether to recursively read the contents of directories.
+   */
+  recursive:
+    boolean;
+}
+
+/**
+ * An entry returned by `readDir`.
+ */
+export interface ReadDirEntry {
+  /**
+   * The relative path of the entry from readDir the path parameter.
+   */
+  path:
+    string;
+  /**
+   * The handle of the entry.
+   */
+  handle:
+    FileSystemHandle;
+}
+
+/**
+ * An entry returned by `readDirSync`.
+ */
+export interface ReadDirEntrySync {
+  /**
+   * The relative path of the entry from readDir the path parameter.
+   */
+  path:
+    string;
+  /**
+   * The handle of the entry.
+   */
+  handle:
+    FileSystemHandleLike;
+}
+
+/**
+ * A handle to a file or directory returned by `statSync`.
+ */
+export interface FileSystemHandleLike {
+  /**
+   * The name of the entry.
+   */
+  name:
+    string;
+  /**
+   * The kind of the entry.
+   */
+  kind:
+    FileSystemHandleKind;
+}
+
+export interface FileSystemFileHandleLike extends FileSystemHandleLike {
+  /**
+   * The type of the file.
+   */
+  type:
+    string;
+  /**
+   * The size of the file.
+   */
+  size:
+    number;
+  /**
+   * The last modified time of the file.
+   */
+  lastModified:
+    number;
+}
+
+/**
+ * Serializable version of Error.
+ */
+export interface ErrorLike {
+  /**
+   * The name of the error.
+   */
+  name:
+    string;
+  /**
+   * The message of the error.
+   */
+  message:
+    string;
+}
+
+/**
+ * Serializable version of File.
+ */
+export interface FileLike {
+  /**
+   * The name of the file.
+   */
+  name:
+    string;
+  /**
+   * The type of the file.
+   */
+  type:
+    string;
+  /**
+   * The last modified time of the file.
+   */
+  lastModified:
+    number;
+  /**
+   * The size of the file.
+   */
+  size:
+    number;
+  /**
+   * The binary data of the file.
+   */
+  data:
+    ArrayBuffer;
+}
+
+/**
+ * Setup options of `connectSyncAgent`.
+ */
+export interface SyncAgentOptions {
+  /**
+   * The worker to communicate with.
+   */
+  worker:
+    Worker |
+    URL |
+    string;
+  /**
+   * The length of the buffer to use for communication.
+  */
+  bufferLength?:
+    number;
+  /**
+   * The timeout for operations.
+   */
+  opTimeout?:
+    number;
+}
+
+/**
+ * Options for `zip`.
+ */
+export interface ZipOptions {
+  /**
+   * Whether to preserve the root directory in the zip file.
+   * @defaultValue `true`
+   */
+  preserveRoot:
+    boolean;
+}
+
+/**
+ * Options for `mkTemp`.
+ */
+export interface TempOptions {
+  /**
+   * Whether to create a directory.
+   * eg: `mktemp -d`
+   * @defaultValue `false`
+   */
+  isDirectory?:
+    boolean;
+  /**
+   * The basename of the file or directory.
+   * eg: `mktemp -t basename.XXX`
+   * @defaultValue `tmp`
+   */
+  basename?:
+    string;
+  /**
+   * The extension of the file.
+   * eg: `mktemp --suffix .txt`
+   */
+  extname?:
+    string;
+}
+
+/**
+ * Options for `copy`.
+ */
+export interface CopyOptions {
+  /**
+   * Whether to overwrite the destination file if it already exists.
+   * @defaultValue `true`
+   */
+  overwrite?:
+    boolean;
+}
+
+/**
+ * Result of `downloadFile` when the file is saved to a temporary path.
+ */
+export interface DownloadFileTempResponse {
+  /**
+   * The temporary path of the downloaded file to be saved.
+   */
+  tempFilePath:
+    string;
+  /**
+   * The raw response.
+   */
+  rawResponse:
+    Response;
+}
+
+/**
+ * Options for `move`.
+ */
+export interface MoveOptions {
+  /**
+   * Whether to overwrite the destination file if it already exists.
+   * @defaultValue `true`
+   */
+  overwrite?:
+    boolean;
+}

package/src/fs/helpers.ts

@@ -0,0 +1,338 @@
+// 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 { SEPARATOR,
+         basename,
+         dirname } from '@std/path/posix';
+import { Err,
+         Ok,
+         RESULT_VOID,
+         type AsyncIOResult,
+         type AsyncVoidIOResult } from 'happy-rusty';
+import { ABORT_ERROR,
+         CURRENT_DIR,
+         NOT_FOUND_ERROR,
+         ROOT_DIR } from './constants.ts';
+
+/**
+ * The root directory handle of the file system.
+ */
+let
+  fsRoot:
+    FileSystemDirectoryHandle;
+
+/**
+ * Retrieves the root directory handle of the file system.
+ *
+ * @returns A promise that resolves to the
+ *          `FileSystemDirectoryHandle` of
+ *          the root directory.
+ */
+async function
+  getFsRoot():
+    Promise<FileSystemDirectoryHandle> {
+    fsRoot ??=
+      await navigator.storage.getDirectory();
+    return fsRoot;
+}
+
+/**
+ * Checks if the provided path is the root directory path.
+ *
+ * @param path - The path to check.
+ * @returns A boolean indicating whether the path is the root directory path.
+ */
+export function
+  isRootPath(
+    path:
+      string):
+    boolean {
+    return path === ROOT_DIR;
+}
+
+/**
+ * Checks if the provided directory path is the current directory.
+ *
+ * @param dirPath - The directory path to check.
+ * @returns A boolean indicating whether the directory path is the current directory.
+ */
+export function
+  isCurrentDir(
+    dirPath:
+      string):
+    boolean {
+    return dirPath === CURRENT_DIR;
+}
+
+/**
+ * Asynchronously obtains a handle to a child directory from the given parent directory handle.
+ *
+ * @param dirHandle - The handle to the parent directory.
+ * @param dirName - The name of the child directory to retrieve.
+ * @param options - Optional parameters that specify options such as whether to create the directory if it does not exist.
+ * @returns A promise that resolves to an `AsyncIOResult` containing the `FileSystemDirectoryHandle` for the child directory.
+ */
+async function
+  getChildDirHandle(
+    dirHandle:
+      FileSystemDirectoryHandle,
+    dirName:
+      string,
+    options?:
+      FileSystemGetDirectoryOptions):
+    AsyncIOResult<FileSystemDirectoryHandle> {
+    try {
+      const
+        handle =
+          await dirHandle.getDirectoryHandle(
+            dirName,
+            options);
+      return Ok(
+        handle);
+    } catch (
+        e) {
+        const
+          err =
+            e as DOMException;
+        const
+          error =
+            new Error(
+              `${ err.name }: ${ err.message } ` +
+              `When get child directory '${ dirName }' ` +
+	      `from directory '${ dirHandle.name || ROOT_DIR }'.`);
+        error.name =
+          err.name;
+        return Err(
+          error);
+    }
+}
+
+/**
+ * Retrieves a file handle for a child file within a directory.
+ *
+ * @param dirHandle - The directory handle to search within.
+ * @param fileName - The name of the file to retrieve.
+ * @param options - Optional parameters for getting the file handle.
+ * @returns A promise that resolves to an `AsyncIOResult` containing the `FileSystemFileHandle`.
+ */
+async function
+  getChildFileHandle(
+    dirHandle:
+      FileSystemDirectoryHandle,
+    fileName:
+      string,
+    options?:
+      FileSystemGetFileOptions):
+    AsyncIOResult<FileSystemFileHandle> {
+    try {
+      const
+        handle =
+          await dirHandle.getFileHandle(
+            fileName,
+            options);
+        return Ok(handle);
+    } catch (
+      e) {
+        const
+          err =
+            e as DOMException;
+        const
+          error =
+            new Error(
+              `${ err.name }: ${ err.message } ` +
+              `When get child file '${ fileName }' ` +
+	      `from directory '${ dirHandle.name || ROOT_DIR }'.`);
+        error.name =
+          err.name;
+        return Err(
+          error);
+    }
+}
+
+/**
+ * Retrieves a directory handle given a path.
+ *
+ * @param dirPath - The path of the directory to retrieve.
+ * @param options - Optional parameters for getting the directory handle.
+ * @returns A promise that resolves to an `AsyncIOResult` containing the `FileSystemDirectoryHandle`.
+ */
+export async function
+  getDirHandle(
+    dirPath:
+      string,
+    options?:
+      FileSystemGetDirectoryOptions):
+    AsyncIOResult<FileSystemDirectoryHandle> {
+    // create from root
+    let
+      dirHandle =
+        await getFsRoot();
+    if ( isRootPath(
+           dirPath) ) {
+      // root is already the a handle
+      return Ok(
+        dirHandle);
+    }
+    // start with /
+    let
+      childDirPath =
+        dirPath.slice(
+          1);
+    while ( childDirPath ) {
+      let
+        dirName =
+          '';
+      const
+        index =
+          childDirPath.indexOf(
+            SEPARATOR);
+      if (index === -1) {
+          dirName =
+            childDirPath;
+          childDirPath =
+            '';
+      }
+      else {
+        dirName =
+          childDirPath.slice(
+            0,
+            index);
+        childDirPath =
+          childDirPath.slice(
+            index + 1);
+        // skip //
+        if ( index === 0 ) {
+          continue;
+        }
+      }
+      const
+        dirHandleRes =
+          await getChildDirHandle(
+            dirHandle,
+            dirName,
+            options);
+      if ( dirHandleRes.isErr() ) {
+        // stop
+        return dirHandleRes;
+      }
+      dirHandle =
+        dirHandleRes.unwrap();
+    }
+    return Ok(
+      dirHandle);
+}
+
+/**
+ * Retrieves a file handle given a file path.
+ *
+ * @param filePath - The path of the file to retrieve.
+ * @param options - Optional parameters for getting the file handle.
+ * @returns A promise that resolves to an `AsyncIOResult` containing the `FileSystemFileHandle`.
+ */
+export async function
+  getFileHandle(
+    filePath:
+      string,
+    options?:
+    FileSystemGetFileOptions):
+    AsyncIOResult<FileSystemFileHandle> {
+    const
+      isCreate =
+        options?.create ?? false;
+    const
+      dirPath =
+        dirname(
+          filePath);
+    const
+      fileName =
+        basename(
+          filePath);
+    const
+      dirHandleRes =
+        await getDirHandle(
+          dirPath,
+          { create:
+              isCreate,
+          });
+    return dirHandleRes.andThenAsync(
+      dirHandle => {
+        return getChildFileHandle(
+          dirHandle,
+          fileName,
+          { create:
+              isCreate });
+    });
+}
+
+/**
+ * Whether the error is a `NotFoundError`.
+ * @param err - The error to check.
+ * @returns `true` if the error is a `NotFoundError`, otherwise `false`.
+ */
+export function
+  isNotFoundError(
+    err:
+      Error):
+    boolean {
+    return err.name === NOT_FOUND_ERROR;
+}
+
+/**
+ * Gets the final result from a list of AsyncVoidIOResult tasks.
+ * @param tasks - The list of tasks to get the final result from.
+ * @returns The final result from the list of tasks.
+ */
+export async function
+  getFinalResult(
+    tasks:
+      AsyncVoidIOResult[]):
+    AsyncVoidIOResult {
+    const
+      allRes =
+        await Promise.all(
+          tasks);
+    // anyone failed?
+    const
+      fail =
+        allRes.find(
+          x => x.isErr());
+    return fail ?? RESULT_VOID;
+}
+
+/**
+ * Creates an `AbortError` Error.
+ * @returns An `AbortError` Error.
+ */
+export function
+  createAbortError():
+    Error {
+    const
+      error =
+        new Error();
+    error.name =
+      ABORT_ERROR;
+    return error;
+}