@themartiancompany/opfs 1.8.11

package/src/fs/opfs_unzip.ts

@@ -0,0 +1,168 @@
+// 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 } from '@happy-ts/fetch-t';
+import { join,
+         SEPARATOR } from '@std/path/posix';
+import * as fflate from 'fflate/browser';
+import { Err,
+         type AsyncVoidIOResult,
+         type VoidIOResult } from 'happy-rusty';
+import { Future } from 'tiny-future';
+import { assertAbsolutePath,
+         assertFileUrl } from './assertions.ts';
+import type { FsRequestInit } from './defines.ts';
+import { getFinalResult } from './helpers.ts';
+import { readFile,
+         writeFile } from './opfs_core.ts';
+
+/**
+ * Unzip a buffer then write to the target path.
+ * @param buffer - Zipped ArrayBuffer.
+ * @param targetPath - Target directory path.
+ */
+async function
+  unzipBufferToTarget(
+    buffer:
+      ArrayBuffer,
+    targetPath:
+      string):
+    AsyncVoidIOResult {
+    const
+      data =
+        new Uint8Array(
+          buffer);
+    const
+      future =
+        new Future<VoidIOResult>();
+    fflate.unzip(
+      data,
+      async (err, unzipped) => {
+        if (err) {
+          future.resolve(
+            Err(
+              err));
+          return;
+        }
+        const
+          tasks:
+            AsyncVoidIOResult[] =
+            [];
+        for ( const path in unzipped ) {
+          // ignore directory
+          if ( path.at(
+                 -1) !== SEPARATOR ) {
+            tasks.push(
+              writeFile(
+                join(
+                  targetPath,
+                  path),
+                unzipped[
+                  path]));
+          }
+        }
+        future.resolve(
+          getFinalResult(
+            tasks));
+      });
+    return await future.promise;
+}
+
+/**
+ * Unzip a zip file to a directory.
+ * Equivalent to `unzip -o <zipFilePath> -d <targetPath>
+ *
+ * Usees [fflate](https://github.com/101arrowz/fflate) as the unzip backend.
+ * @param zipFilePath - Zip file path.
+ * @param targetPath - The directory to unzip to.
+ * @returns A promise that resolves to an `AsyncIOResult`
+ *          indicating whether the zip file was successfully unzipped.
+ */
+export
+  async function
+    unzip(
+      zipFilePath:
+        string,
+      targetPath:
+        string):
+      AsyncVoidIOResult {
+      assertAbsolutePath(
+        targetPath);
+    const
+      fileRes =
+        await readFile(
+          zipFilePath);
+    return fileRes.andThenAsync(
+      buffer => {
+        return unzipBufferToTarget(
+          buffer,
+          targetPath);
+      });
+}
+
+/**
+ * Unzip a remote zip file to a directory.
+ * Equivalent to `unzip -o <zipFilePath> -d <targetPath>
+ *
+ * Use [fflate](https://github.com/101arrowz/fflate) as the unzip backend.
+ * @param zipFileUrl - Zip file url.
+ * @param targetPath - The directory to unzip to.
+ * @param requestInit - Optional request initialization parameters.
+ * @returns A promise that resolves to an `AsyncIOResult`
+ *          indicating whether the zip file was successfully unzipped.
+ */
+export
+  async function
+    unzipFromUrl(
+      zipFileUrl:
+        string,
+      targetPath:
+        string,
+      requestInit?:
+        FsRequestInit):
+      AsyncVoidIOResult {
+      assertFileUrl(
+        zipFileUrl);
+      assertAbsolutePath(
+        targetPath);
+    const
+      fetchRes =
+        await fetchT(
+          zipFileUrl,
+          { redirect:
+              'follow',
+            ...requestInit,
+            responseType:
+              'arraybuffer',
+            abortable:
+              false });
+    return fetchRes.andThenAsync(
+      buffer => {
+        return unzipBufferToTarget(
+          buffer,
+          targetPath);
+      });
+}

package/src/fs/opfs_upload.ts

@@ -0,0 +1,126 @@
+// 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 { basename } from '@std/path/posix';
+import { Err } from 'happy-rusty';
+import { assertFileUrl } from './assertions.ts';
+import type { UploadRequestInit } from './defines.ts';
+import { createAbortError } from './helpers.ts';
+import { readBlobFile } from './opfs_ext.ts';
+
+/**
+ * Uploads a file from the specified path to a URL.
+ *
+ * @param filePath - The path of the file to upload.
+ * @param fileUrl - The URL where the file will be uploaded.
+ * @param requestInit - Optional request initialization parameters.
+ * @returns A promise that resolves to an `AsyncIOResult`
+ *          indicating whether the file was successfully uploaded.
+ */
+export function
+  uploadFile(
+    filePath:
+      string,
+    fileUrl:
+      string,
+    requestInit?:
+      UploadRequestInit):
+    FetchTask<Response> {
+    type T =
+      Response;
+    let
+      aborted:
+        boolean;
+    let
+      fetchTask:
+        FetchTask<T>;
+    assertFileUrl(
+      fileUrl);
+    aborted =
+      false;
+    const
+      response =
+      ( async ():
+          FetchResponse<Response> => {
+          const
+            fileRes =
+              await readBlobFile(
+                filePath);
+          return fileRes.andThenAsync(
+            async file => {
+              // maybe aborted
+              if ( aborted ) {
+                  return Err(
+                    createAbortError());
+              }
+              const
+                { // default file name
+                  filename = basename(filePath),
+                  ...rest } =
+                  requestInit ??
+                    {};
+              const
+                formData =
+                  new FormData();
+              formData.append(
+                filename,
+                file,
+                filename);
+              fetchTask =
+                fetchT(
+                fileUrl,
+                { method:
+                    'POST',
+                  ...rest,
+                  abortable:
+                    true,
+                  body:
+                    formData });
+              return fetchTask.response;
+          });
+        })();
+    return {
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      abort(reason?: any):
+        void {
+        aborted =
+          true;
+          fetchTask?.abort(
+            reason);
+        },
+        get aborted():
+          boolean {
+          return aborted;
+        },
+        get response():
+          FetchResponse<Response> {
+          return response;
+      },
+    };
+}

package/src/fs/opfs_zip.ts

@@ -0,0 +1,314 @@
+// 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 } from '@happy-ts/fetch-t';
+import { basename,
+         join } from '@std/path/posix';
+import * as fflate from 'fflate/browser';
+import { Err,
+         Ok,
+         type AsyncIOResult,
+         type AsyncVoidIOResult,
+         type IOResult } from 'happy-rusty';
+import { Future } from 'tiny-future';
+import { assertAbsolutePath,
+         assertFileUrl } from './assertions.ts';
+import type { FsRequestInit,
+              ZipOptions } from './defines.ts';
+import { readDir,
+         stat,
+         writeFile } from './opfs_core.ts';
+import { getFileDataByHandle,
+         isFileHandle } from './utils.ts';
+
+/**
+ * Zip a zippable data then write to the target path.
+ * @param zippable - Zippable data.
+ * @param zipFilePath - Target zip file path.
+ */
+async function
+  zipTo<T>(
+    zippable:
+      fflate.AsyncZippable,
+    zipFilePath?:
+      string):
+    AsyncIOResult<T> {
+    const
+      future =
+        new Future<IOResult<T>>();
+    fflate.zip(
+      zippable,
+      { consume:
+          true },
+        async (err,
+               u8a) => {
+          if ( err ) {
+            future.resolve(
+              Err(
+                err));
+              return;
+          }
+          // whether to write to file
+          if ( zipFilePath ) {
+              const
+                res =
+                  await writeFile(
+                    zipFilePath,
+                    u8a);
+              future.resolve(
+                res as IOResult<T>);
+          }
+          else {
+            future.resolve(
+              Ok( u8a as T ));
+          }
+        });
+    return await future.promise;
+}
+
+/**
+ * Zip a file or directory and write to a zip file.
+ * Equivalent to `zip -r <zipFilePath> <targetPath>`.
+ *
+ * Use [fflate](https://github.com/101arrowz/fflate) as the zip backend.
+ * @param sourcePath - The path to be zipped.
+ * @param zipFilePath - The path to the zip file.
+ * @param options - Options of zip.
+ * @returns A promise that resolves to an `AsyncIOResult`
+ *          indicating whether the source was successfully zipped.
+ */
+export
+  async function
+    zip(
+      sourcePath:
+        string,
+      zipFilePath:
+        string,
+      options?:
+        ZipOptions):
+      AsyncVoidIOResult;
+
+/**
+ * Zip a file or directory and return the zip file data.
+ * Equivalent to `zip -r <zipFilePath> <targetPath>`.
+ *
+ * Use [fflate](https://github.com/101arrowz/fflate) as the zip backend.
+ * @param sourcePath - The path to be zipped.
+ * @param options - Options of zip.
+ * @returns A promise that resolves to an `AsyncIOResult` indicating
+ *          whether the source was successfully zipped.
+ */
+export
+  async function
+    zip(
+      sourcePath:
+        string,
+      options?:
+        ZipOptions):
+      AsyncIOResult<Uint8Array>;
+export
+  async function
+    zip<T>(
+      sourcePath:
+        string,
+      zipFilePath?:
+        string |
+        ZipOptions,
+      options?:
+        ZipOptions):
+      AsyncIOResult<T> {
+      if ( typeof zipFilePath === 'string' ) {
+        assertAbsolutePath(
+          zipFilePath);
+      }
+      else {
+        options =
+          zipFilePath;
+        zipFilePath =
+          undefined;
+      }
+      const
+        statRes =
+          await stat(
+            sourcePath);
+    return statRes.andThenAsync(
+      async handle => {
+        const
+          sourceName =
+            basename(
+              sourcePath);
+        const
+          zippable:
+            fflate.AsyncZippable =
+            {};
+        if ( isFileHandle(
+               handle) ) {
+            // file
+          const
+            data =
+              await getFileDataByHandle(
+                handle);
+          zippable[
+            sourceName] =
+              data;
+        }
+	else {
+          // directory
+          const
+            readDirRes =
+              await readDir(
+                sourcePath,
+                { recursive:
+                    true });
+          if ( readDirRes.isErr() ) {
+            return readDirRes.asErr();
+          }
+          // default to preserve root
+          const
+            preserveRoot =
+              options?.preserveRoot ??
+                true;
+          for await ( const { path,
+                              handle } of readDirRes.unwrap()) {
+            // path
+            if ( isFileHandle(
+                   handle) ) {
+              const
+                entryName =
+                  preserveRoot ?
+                  join(
+                    sourceName,
+                    path) :
+                  path;
+              const
+                data =
+                  await getFileDataByHandle(
+                    handle);
+              zippable[
+                entryName] =
+                  data;
+            }
+          }
+        }
+        return zipTo(
+          zippable,
+          zipFilePath);
+      });
+}
+
+/**
+ * Zip a remote file and write to a zip file.
+ *
+ * Use [fflate](https://github.com/101arrowz/fflate) as the zip backend.
+ * @param sourceUrl - The url to be zipped.
+ * @param zipFilePath - The path to the zip file.
+ * @param requestInit - Optional request initialization parameters.
+ * @returns A promise that resolves to an `AsyncIOResult`
+ *          indicating whether the source was successfully zipped.
+ */
+export
+  async function
+    zipFromUrl(
+      sourceUrl:
+        string,
+      zipFilePath:
+        string,
+      requestInit?:
+        FsRequestInit):
+      AsyncVoidIOResult;
+
+/**
+ * Zip a remote file and return the zip file data.
+ *
+ * Use [fflate](https://github.com/101arrowz/fflate) as the zip backend.
+ * @param sourceUrl - The url to be zipped.
+ * @param requestInit - Optional request initialization parameters.
+ * @returns A promise that resolves to an `AsyncIOResult` indicating
+ *          whether the source was successfully zipped.
+ */
+export
+  async function
+    zipFromUrl(
+      sourceUrl:
+        string,
+      requestInit?:
+        FsRequestInit):
+      AsyncIOResult<Uint8Array>;
+
+export
+  async function
+    zipFromUrl<T>(
+      sourceUrl:
+        string,
+      zipFilePath?:
+        string |
+        FsRequestInit,
+      requestInit?:
+        FsRequestInit):
+      AsyncIOResult<T> {
+      assertFileUrl(
+        sourceUrl);
+    if ( typeof zipFilePath === 'string' ) {
+      assertAbsolutePath(
+        zipFilePath);
+    }
+    else {
+      requestInit =
+        zipFilePath;
+      zipFilePath =
+        undefined;
+    }
+    const
+      fetchRes =
+        await fetchT(
+          sourceUrl,
+          { redirect:
+              'follow',
+            ...requestInit,
+            responseType:
+              'arraybuffer',
+            abortable:
+              false,
+          });
+    return fetchRes.andThenAsync(
+      buffer => {
+        const
+          sourceName =
+            basename(
+              sourceUrl);
+        const
+          zippable:
+            fflate.AsyncZippable =
+            {};
+        zippable[
+          sourceName] =
+          new Uint8Array(
+            buffer);
+        return zipTo(
+          zippable,
+          zipFilePath);
+      });
+}

package/src/fs/support.ts

@@ -0,0 +1,36 @@
+// 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/>.
+ */
+
+/**
+ * Checks if the Origin Private File System (OPFS) is supported in the current environment.
+ *
+ * @returns A boolean indicating whether OPFS is supported.
+ */
+export function
+  isOPFSSupported():
+    boolean {
+    return typeof navigator?.storage?.getDirectory === 'function';
+}