@themartiancompany/opfs 1.8.11

package/src/fs/utils.ts

@@ -0,0 +1,176 @@
+// 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 { join,
+         SEPARATOR } from '@std/path/posix';
+import { TMP_DIR } from './constants.ts';
+import type { FileSystemFileHandleLike,
+              FileSystemHandleLike,
+              TempOptions } from './defines.ts';
+
+/**
+ * Generate a temporary path but not create it.
+ *
+ * @param options - Options and flags.
+ * @returns The temporary path.
+ */
+export function
+  generateTempPath(
+    options?:
+      TempOptions):
+    string {
+    const
+      { isDirectory = false,
+        basename = 'tmp',
+        extname = '' } = options ?? {};
+    const
+      base =
+        basename ? `${ basename }-` : '';
+    const
+      ext =
+        isDirectory ? '' : extname;
+    // use uuid to generate a unique name
+    return join(
+      TMP_DIR,
+      `${ base }${ crypto.randomUUID() }${ ext }`);
+}
+
+/**
+ * Check whether the path is a temporary path.
+ * @param path - The path to check.
+ * @returns `true` if the path is a temporary path otherwise `false`.
+ */
+export function
+  isTempPath(
+    path:
+      string):
+    boolean {
+    return path.startsWith(
+      `${ TMP_DIR }${ SEPARATOR }`);
+}
+
+/**
+ * Serialize a `FileSystemHandle` to plain object.
+ * @param handle - `FileSystemHandle` object.
+ * @returns Serializable version of FileSystemHandle that is FileSystemHandleLike.
+ */
+export async function
+  toFileSystemHandleLike(
+    handle:
+      FileSystemHandle):
+    Promise<FileSystemHandleLike> {
+    const
+      { name,
+        kind } =
+        handle;
+    if ( isFileHandle(
+           handle) ) {
+      const
+        file =
+          await handle.getFile();
+      const
+        { size,
+          lastModified,
+	  type } =
+          file;
+      const
+        fileHandle:
+          FileSystemFileHandleLike = {
+          name,
+          kind,
+          type,
+          size,
+          lastModified,
+      };
+      return fileHandle;
+    }
+    const
+      handleLike:
+        FileSystemHandleLike= {
+        name,
+        kind,
+    };
+    return handleLike;
+}
+
+/**
+ * Whether the handle is a file.
+ * @param handle - The handle which is a FileSystemHandle.
+ * @returns `true` if the handle is a file, otherwise `false`.
+ */
+export function
+  isFileHandle(
+    handle:
+      FileSystemHandle):
+    handle is FileSystemFileHandle {
+    return handle.kind === 'file';
+}
+
+/**
+ * Whether the handle is a directory.
+ * @param handle - The handle which is a FileSystemHandle.
+ * @returns `true` if the handle is a directory, otherwise `false`.
+ */
+export function
+  isDirectoryHandle(
+    handle:
+      FileSystemHandle):
+    handle is FileSystemDirectoryHandle {
+    return handle.kind === 'directory';
+}
+
+/**
+ * Whether the handle is a file-like.
+ * @param handle -  The handle which is a FileSystemHandleLike.
+ * @returns `true` if the handle is a file, otherwise `false`.
+ */
+export function
+  isFileHandleLike(
+    handle:
+      FileSystemHandleLike):
+    handle is FileSystemFileHandleLike {
+    return handle.kind === 'file';
+}
+
+/**
+ * Gets the data of a file handle.
+ * @param handle - The file handle.
+ * @returns A promise that resolves to the data of the file.
+ */
+export async function
+  getFileDataByHandle(
+    handle:
+      FileSystemFileHandle):
+    Promise<Uint8Array> {
+    const
+      file =
+        await handle.getFile();
+    const
+      ab =
+        await file.arrayBuffer();
+    return new Uint8Array(
+      ab);
+}

package/src/mod.ts

@@ -0,0 +1,41 @@
+// 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/>.
+ */
+
+export * from './fs/assertions.ts';
+export * from './fs/constants.ts';
+export * from './fs/defines.ts';
+export * from './fs/opfs_core.ts';
+export * from './fs/opfs_download.ts';
+export * from './fs/opfs_ext.ts';
+export * from './fs/opfs_tmp.ts';
+export * from './fs/opfs_unzip.ts';
+export * from './fs/opfs_upload.ts';
+export * from './fs/opfs_zip.ts';
+export * from './fs/support.ts';
+export * from './fs/utils.ts';
+export * from './worker/opfs_worker.ts';
+export * from './worker/opfs_worker_adapter.ts';
+export type { SyncMessenger } from './worker/shared.ts';

package/src/worker/helpers.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 { TIMEOUT_ERROR } from '../fs/constants.ts';
+import type { ErrorLike,
+              FileLike } from '../fs/defines.ts';
+
+/**
+ * Serialize an `Error` to plain object.
+ * @param error - `Error` object.
+ * @returns Serializable version of Error.
+ */
+export
+  function
+    serializeError(
+      error:
+        Error |
+        null):
+      ErrorLike |
+      null {
+    return error ?
+           { name:
+               error.name,
+             message:
+               error.message } :
+           error;
+}
+
+/**
+ * Deserialize an `Error` from plain object.
+ * @param error - Serializable version of Error.
+ * @returns `Error` object.
+ */
+export
+  function
+    deserializeError(
+      error:
+        ErrorLike):
+      Error {
+    const
+      err =
+        new Error(
+          error.message);
+    err.name =
+      error.name;
+    return err;
+}
+
+/**
+ * Serialize a `File` to plain object.
+ * @param file - `File` object.
+ * @returns Serializable version of File.
+ */
+export
+  async function
+    serializeFile(
+      file:
+        File):
+      Promise<FileLike> {
+    const
+      ab =
+        await file.arrayBuffer();
+    return {
+      name:
+        file.name,
+      type:
+        file.type,
+      lastModified:
+        file.lastModified,
+      size:
+        ab.byteLength,
+      data:
+        ab,
+    };
+}
+
+/**
+ * Deserialize a `File` from plain object.
+ * @param file - Serializable version of File.
+ * @returns `File` object.
+ */
+export
+  function
+    deserializeFile(
+      file:
+        FileLike):
+      File {
+      const
+        blob =
+          new Blob(
+            [ file.data ]);
+    return new File(
+      [ blob ],
+      file.name,
+      { type:
+          file.type,
+        lastModified:
+          file.lastModified });
+}
+
+/**
+ * Global timeout of per sync I/O operation.
+ */
+let
+  globalOpTimeout =
+    1000;
+
+/**
+ * Set global timeout of per sync I/O operation.
+ * @param timeout - Timeout in milliseconds.
+ */
+export
+  function
+    setGlobalOpTimeout(
+      timeout:
+        number):
+      void {
+    globalOpTimeout =
+      timeout;
+}
+
+/**
+ * Sleep until a condition is met.
+ * @param condition - Condition to be met.
+ */
+export
+  function
+    sleepUntil(
+      condition:
+        () => boolean) {
+      const
+        start =
+          Date.now();
+      while ( !condition() ) {
+        if ( Date.now() - start > globalOpTimeout ) {
+          const
+            error =
+              new Error(
+                'Operating Timeout');
+          error.name =
+            TIMEOUT_ERROR;
+          throw error;
+        }
+    }
+}

package/src/worker/opfs_worker.ts

@@ -0,0 +1,298 @@
+// 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 { IOResult } from 'happy-rusty';
+import type { ReadDirEntry,
+              ReadDirEntrySync } from '../fs/defines.ts';
+import { createFile,
+         mkdir,
+         readDir,
+         remove,
+         stat,
+         writeFile } from '../fs/opfs_core.ts';
+import { appendFile,
+         copy,
+         emptyDir,
+         exists,
+         move,
+         readBlobFile } from '../fs/opfs_ext.ts';
+import { deleteTemp,
+         mkTemp,
+         pruneTemp } from '../fs/opfs_tmp.ts';
+import { unzip } from '../fs/opfs_unzip.ts';
+import { zip } from '../fs/opfs_zip.ts';
+import { toFileSystemHandleLike } from '../fs/utils.ts';
+import { serializeError,
+         serializeFile } from './helpers.ts';
+import { decodeFromBuffer,
+         encodeToBuffer,
+         respondToMainFromWorker,
+         SyncMessenger,
+         WorkerAsyncOp } from './shared.ts';
+
+/**
+ * Async I/O operations which allow to call from main thread.
+ */
+const
+  asyncOps = {
+    [ WorkerAsyncOp.createFile ]:
+      createFile,
+    [ WorkerAsyncOp.mkdir ]:
+      mkdir,
+    [ WorkerAsyncOp.move ]:
+      move,
+    [ WorkerAsyncOp.readDir ]:
+      readDir,
+    [ WorkerAsyncOp.remove ]:
+      remove,
+    [ WorkerAsyncOp.stat ]:
+      stat,
+    [ WorkerAsyncOp.writeFile ]:
+      writeFile,
+    [ WorkerAsyncOp.appendFile ]:
+      appendFile,
+    [ WorkerAsyncOp.copy ]:
+      copy,
+    [ WorkerAsyncOp.emptyDir ]:
+      emptyDir,
+    [ WorkerAsyncOp.exists ]:
+      exists,
+    [ WorkerAsyncOp.deleteTemp ]:
+      deleteTemp,
+    [ WorkerAsyncOp.mkTemp ]:
+      mkTemp,
+    [ WorkerAsyncOp.pruneTemp ]:
+      pruneTemp,
+    [ WorkerAsyncOp.readBlobFile ]:
+      readBlobFile,
+    [ WorkerAsyncOp.unzip ]:
+      unzip,
+    [ WorkerAsyncOp.zip ]:
+      zip,
+};
+
+/**
+ * Cache the messenger instance.
+ */
+let
+  messenger:
+    SyncMessenger;
+
+/**
+ * Start worker agent.
+ * Listens to postMessage from main thread.
+ * Start runner loop.
+ */
+export
+  function
+    startSyncAgent() {
+    if ( typeof window !== 'undefined' ) {
+      throw new Error(
+        'Only can use in worker');
+    }
+    if ( messenger ) {
+      throw new Error(
+        'Worker messenger already started');
+    }
+    addEventListener(
+      'message',
+      (event:
+         MessageEvent<SharedArrayBuffer>) => {
+        // created at main thread and transfer to worker
+        const
+          sab =
+            event.data;
+
+        if ( ! (sab instanceof SharedArrayBuffer) ) {
+          throw new TypeError(
+            'Only can post SharedArrayBuffer to Worker');
+        }
+        messenger =
+          new SyncMessenger(sab);
+        // notify main thread that worker is ready
+        postMessage(
+          true);
+        // start waiting for request
+        runWorkerLoop();
+      });
+}
+
+/**
+ * Run worker loop.
+ */
+async function
+  runWorkerLoop():
+    Promise<void> {
+    // loop forever
+    while ( true ) {
+      try {
+        await respondToMainFromWorker(
+          messenger,
+          async (data) => {
+            const
+              [op, ...args] =
+                decodeFromBuffer(
+                  data) as [ WorkerAsyncOp,
+                             ...Parameters<typeof asyncOps[
+                                                    WorkerAsyncOp]> ];
+            // handling unequal parameters for serialization and deserialization
+            if ( op === WorkerAsyncOp.writeFile ||
+                 op === WorkerAsyncOp.appendFile) {
+              // actually is an byte array
+              if ( Array.isArray(
+                     args[
+                       1]) ) {
+                args[
+                  1] =
+                  new Uint8Array(
+                    args[1]);
+              }
+            }
+            else if ( op === WorkerAsyncOp.pruneTemp ) {
+              // actually is a Date string
+              args[
+                0] =
+                new Date(
+                  args[
+                    0] as Date);
+            }
+            let
+              response:
+                Uint8Array;
+            const
+              handle =
+                asyncOps[
+                  op];
+            try {
+              // The linter shows not to work well here
+              // as it cant disable a block of lines.
+              // eslint-disable-next-line @typescript-eslint/no-explicit-any
+              const res: IOResult<any> = await ( handle as any )(
+                    ...args);
+              if ( res.isErr() ) {
+                // without result success
+                response =
+                  encodeToBuffer(
+                    [ serializeError(
+                        res.unwrapErr()) ]);
+              }
+              else {
+                // manually serialize response
+                let
+                  rawResponse;
+                if ( op === WorkerAsyncOp.readBlobFile ) {
+                  const
+                    file:
+                      File =
+                      res.unwrap();
+                  const
+                    fileLike =
+                      await serializeFile(
+                        file);
+                  rawResponse =
+                    { ...fileLike,
+                      // for serialize
+                      data:
+                        [ ...new Uint8Array(
+                               fileLike.data ) ] };
+                }
+                else if ( op === WorkerAsyncOp.readDir ) {
+                  const
+                    iterator:
+                      AsyncIterableIterator<ReadDirEntry> =
+                      res.unwrap();
+                  const
+                    entries:
+                      ReadDirEntrySync[] =
+                      [];
+                  for await ( const { path,
+                                      handle } of iterator) {
+                      const
+                        handleLike =
+                          await toFileSystemHandleLike(
+                            handle);
+                      entries.push(
+                        { path,
+                          handle:
+                            handleLike });
+                  }
+                  rawResponse =
+                    entries;
+                }
+                else if ( op === WorkerAsyncOp.stat ) {
+                  const
+                    handle:
+                      FileSystemHandle =
+                      res.unwrap();
+                  const
+                    data =
+                      await toFileSystemHandleLike(
+                        handle);
+                  rawResponse =
+                    data;
+                }
+                else if ( op === WorkerAsyncOp.zip ) {
+                  const
+                    data:
+                      Uint8Array |
+                      undefined =
+                      res.unwrap();
+                  rawResponse =
+                    data instanceof Uint8Array ?
+                    [ ...data ] :
+                    data;
+                }
+                else {
+                  // others are all boolean
+                  rawResponse =
+                    res.unwrap();
+                }
+                // without error
+                response =
+                  encodeToBuffer(
+                    [ null,
+                      rawResponse ]);
+              }
+            }
+            catch (
+              _error) {
+              response =
+                encodeToBuffer(
+                  [ serializeError(
+                      _error as Error) ]);
+            }
+            return response;
+        });
+      }
+      catch (
+        _error) {
+          console.error(
+            _error instanceof Error ?
+            _error.stack :
+            _error);
+      }
+    }
+}