@pistonite/pure 0.0.12

package/src/fs/FsOpen.ts

@@ -0,0 +1,307 @@
+import { tryCatch, tryAsync, errstr } from "../result/index.ts";
+
+import type { FsFileSystem, FsFileSystemUninit } from "./FsFileSystem.ts";
+import {
+    FsErr,
+    type FsError,
+    type FsResult,
+    fsErr,
+    fsFail,
+} from "./FsError.ts";
+import { fsGetSupportStatus } from "./FsSupportStatus.ts";
+import { FsImplFileAPI } from "./FsImplFileAPI.ts";
+import { FsImplEntryAPI } from "./FsImplEntryAPI.ts";
+import { FsImplHandleAPI } from "./FsImplHandleAPI.ts";
+
+/** Handle for handling top level open errors, and decide if the operation should be retried */
+export type FsOpenRetryHandler = (
+    error: FsError,
+    attempt: number,
+) => Promise<FsResult<boolean>>;
+
+const MAX_RETRY = 10;
+
+/** Open a file system for read-only access with a directory picker dialog */
+export async function fsOpenRead(
+    retryHandler?: FsOpenRetryHandler,
+): Promise<FsResult<FsFileSystem>> {
+    const fs = await createWithPicker(false, retryHandler);
+    if (fs.err) {
+        return fs;
+    }
+    return await init(fs.val, retryHandler);
+}
+
+/** Open a file system for read-write access with a directory picker dialog */
+export async function fsOpenReadWrite(
+    retryHandler?: FsOpenRetryHandler,
+): Promise<FsResult<FsFileSystem>> {
+    const fs = await createWithPicker(true, retryHandler);
+    if (fs.err) {
+        return fs;
+    }
+    return await init(fs.val, retryHandler);
+}
+
+/** Open a file system for read-only access from a DataTransferItem from a drag and drop event */
+export async function fsOpenReadFrom(
+    item: DataTransferItem,
+    retryHandler?: FsOpenRetryHandler,
+): Promise<FsResult<FsFileSystem>> {
+    const fs = await createFromDataTransferItem(item, false, retryHandler);
+    if (fs.err) {
+        return fs;
+    }
+    return await init(fs.val, retryHandler);
+}
+
+/** Open a file system for read-write access from a DataTransferItem from a drag and drop event */
+export async function fsOpenReadWriteFrom(
+    item: DataTransferItem,
+    retryHandler?: FsOpenRetryHandler,
+): Promise<FsResult<FsFileSystem>> {
+    const fs = await createFromDataTransferItem(item, true, retryHandler);
+    if (fs.err) {
+        return fs;
+    }
+    return await init(fs.val, retryHandler);
+}
+
+async function createWithPicker(
+    write: boolean,
+    retryHandler: FsOpenRetryHandler | undefined,
+): Promise<FsResult<FsFileSystemUninit>> {
+    for (let attempt = 1; attempt <= MAX_RETRY; attempt++) {
+        const { implementation } = fsGetSupportStatus();
+        if (implementation === "FileSystemAccess") {
+            const handle = await tryAsync(() => showDirectoryPicker(write));
+            if (handle.val) {
+                return createFromFileSystemHandle(handle.val, write);
+            }
+            if (retryHandler) {
+                const error = isAbortError(handle.err)
+                    ? fsErr(FsErr.UserAbort, "User cancelled the operation")
+                    : fsFail(errstr(handle.err));
+                const shouldRetry = await retryHandler(error, attempt);
+                if (shouldRetry.err) {
+                    // retry handler failed
+                    return shouldRetry;
+                }
+                if (!shouldRetry.val) {
+                    // don't retry
+                    return { err: error };
+                }
+            }
+            // Retry with FileSystemAccess API
+            continue;
+        }
+
+        // FileEntry API only supported through drag and drop
+        // so fallback to File API
+        const inputElement = document.createElement("input");
+        inputElement.id = "temp";
+        inputElement.style.display = "none";
+        document.body.appendChild(inputElement);
+        inputElement.type = "file";
+        inputElement.webkitdirectory = true;
+
+        const fsUninit = await new Promise<FsResult<FsFileSystemUninit>>(
+            (resolve) => {
+                inputElement.addEventListener("change", (event) => {
+                    const files = (event.target as HTMLInputElement).files;
+                    if (!files) {
+                        const err = fsFail(
+                            "Failed to get files from input element",
+                        );
+                        return resolve({ err });
+                    }
+                    resolve(createFromFileList(files));
+                });
+                inputElement.click();
+            },
+        );
+        inputElement.remove();
+
+        if (fsUninit.val) {
+            return fsUninit;
+        }
+
+        if (retryHandler) {
+            const shouldRetry = await retryHandler(fsUninit.err, attempt);
+            if (shouldRetry.err) {
+                // retry handler failed
+                return shouldRetry;
+            }
+            if (!shouldRetry.val) {
+                // don't retry
+                return fsUninit;
+            }
+            // fall through to retry
+        }
+    }
+    return { err: fsFail("Max retry count reached") };
+}
+
+async function createFromDataTransferItem(
+    item: DataTransferItem,
+    write: boolean,
+    retryHandler: FsOpenRetryHandler | undefined,
+): Promise<FsResult<FsFileSystemUninit>> {
+    for (let attempt = 1; attempt <= MAX_RETRY; attempt++) {
+        let error: FsError | undefined = undefined;
+        const { implementation } = fsGetSupportStatus();
+        // Prefer File System Access API since it supports writing
+        if (
+            "getAsFileSystemHandle" in item &&
+            implementation === "FileSystemAccess"
+        ) {
+            const handle = await tryAsync(() => getAsFileSystemHandle(item));
+            if (handle.val) {
+                return createFromFileSystemHandle(handle.val, write);
+            }
+            error = fsFail(
+                "Failed to get handle from DataTransferItem: " +
+                    errstr(handle.err),
+            );
+        } else if (
+            "webkitGetAsEntry" in item &&
+            implementation === "FileEntry"
+        ) {
+            const entry = tryCatch(() => webkitGetAsEntry(item));
+            if (entry.val) {
+                return createFromFileSystemEntry(entry.val);
+            }
+            error = fsFail(
+                "Failed to get entry from DataTransferItem: " +
+                    errstr(entry.err),
+            );
+        }
+        if (!error) {
+            const err = fsErr(
+                FsErr.NotSupported,
+                "No supported API found on the DataTransferItem",
+            );
+            return { err };
+        }
+        // handle error
+        if (retryHandler) {
+            const shouldRetry = await retryHandler(error, attempt);
+            if (shouldRetry.err) {
+                // retry handler failed
+                return shouldRetry;
+            }
+            if (!shouldRetry.val) {
+                // don't retry
+                return { err: error };
+            }
+            // fall through to retry
+        }
+    }
+    return { err: fsFail("Max retry count reached") };
+}
+
+async function init(
+    fs: FsFileSystemUninit,
+    retryHandler: FsOpenRetryHandler | undefined,
+): Promise<FsResult<FsFileSystem>> {
+    let attempt = -1;
+    while (true) {
+        attempt++;
+        const inited = await fs.init();
+        if (!inited.err) {
+            return inited;
+        }
+        if (!retryHandler) {
+            return inited;
+        }
+        const shouldRetry = await retryHandler(inited.err, attempt);
+        if (shouldRetry.err) {
+            // retry handler failed
+            return shouldRetry;
+        }
+        if (!shouldRetry.val) {
+            // should not retry
+            return inited;
+        }
+    }
+}
+
+/** Wrapper for window.showDirectoryPicker */
+function showDirectoryPicker(write: boolean): Promise<FileSystemHandle> {
+    // @ts-expect-error showDirectoryPicker is not in the TS lib
+    return globalThis.showDirectoryPicker({
+        mode: write ? "readwrite" : "read",
+    });
+}
+
+/**
+ * Check if an error is an AbortError from Chromium
+ *
+ * @param e The error to check
+ */
+function isAbortError(e: unknown): boolean {
+    return (
+        !!e && typeof e === "object" && "name" in e && e.name === "AbortError"
+    );
+}
+
+/** Wrapper for DataTransferItem.getAsFileSystemHandle */
+async function getAsFileSystemHandle(
+    item: DataTransferItem,
+): Promise<FileSystemHandle> {
+    // @ts-expect-error getAsFileSystemHandle is not in the TS lib
+    const handle = await item.getAsFileSystemHandle();
+    if (!handle) {
+        throw new Error("handle is null");
+    }
+    return handle;
+}
+
+/** Wrapper for DataTransferItem.webkitGetAsEntry */
+function webkitGetAsEntry(item: DataTransferItem): FileSystemEntry {
+    const entry = item.webkitGetAsEntry();
+    if (!entry) {
+        throw new Error("entry is null");
+    }
+    return entry;
+}
+
+function createFromFileSystemHandle(
+    handle: FileSystemHandle,
+    write: boolean,
+): FsResult<FsFileSystemUninit> {
+    if (handle.kind !== "directory") {
+        const err = fsErr(FsErr.IsFile, "Expected directory");
+        return { err };
+    }
+
+    const fs = new FsImplHandleAPI(
+        handle.name,
+        handle as FileSystemDirectoryHandle,
+        write,
+    );
+
+    return { val: fs };
+}
+
+function createFromFileSystemEntry(
+    entry: FileSystemEntry,
+): FsResult<FsFileSystemUninit> {
+    if (entry.isFile || !entry.isDirectory) {
+        const err = fsErr(FsErr.IsFile, "Expected directory");
+        return { err };
+    }
+    const fs = new FsImplEntryAPI(
+        entry.name,
+        entry as FileSystemDirectoryEntry,
+    );
+    return { val: fs };
+}
+
+function createFromFileList(files: FileList): FsResult<FsFileSystemUninit> {
+    if (!files.length) {
+        const err = fsFail("Expected at least one file");
+        return { err };
+    }
+    return { val: new FsImplFileAPI(files) };
+}

package/src/fs/FsPath.ts

@@ -0,0 +1,137 @@
+/**
+ * Path utilities
+ *
+ * The library has the following path standard:
+ * - All paths are relative (without leading /) to the root
+ *   of the file system (i.e. the uploaded directory)
+ * - Paths are always separated by /
+ * - Empty string denotes root
+ * - Paths cannot lead outside of root
+ *
+ *   @module
+ */
+
+import { FsErr, type FsResult, fsErr } from "./FsError.ts";
+
+/** Get the root path. Current implementation is empty string. */
+export function fsRoot(): string {
+    return "";
+}
+
+/** Check if a path is the root directory, also handles badly formatted paths like ".///../" */
+export function fsIsRoot(p: string): boolean {
+    if (!p) {
+        return true;
+    }
+    for (let i = 0; i < p.length; i++) {
+        if (p[i] !== "/" || p[i] !== "." || p[i] !== "\\") {
+            return false;
+        }
+    }
+    return true;
+}
+
+/**
+ * Get the base name of a path (i.e. remove the last component)
+ *
+ * If this path is the root directory, return InvalidPath.
+ */
+export function fsGetBase(p: string): FsResult<string> {
+    if (fsIsRoot(p)) {
+        const err = fsErr(FsErr.InvalidPath, "Trying to get the base of root");
+        return { err };
+    }
+    const i = Math.max(p.lastIndexOf("/"), p.lastIndexOf("\\"));
+    if (i < 0) {
+        return { val: fsRoot() };
+    }
+    return { val: p.substring(0, i) };
+}
+
+/**
+ * Get the name of a path (i.e. the last component)
+ *
+ * Returns the last component of the path.
+ * Does not include leading or trailing slashes.
+ *
+ * If this path is the root directory, return IsRoot.
+ */
+export function fsGetName(p: string): FsResult<string> {
+    p = stripTrailingSlashes(p);
+    if (fsIsRoot(p)) {
+        const err = fsErr(FsErr.IsRoot, "Root directory has no name");
+        return { err };
+    }
+    const i = Math.max(p.lastIndexOf("/"), p.lastIndexOf("\\"));
+    if (i < 0) {
+        return { val: p };
+    }
+    return { val: p.substring(i + 1) };
+}
+
+/**
+ * Normalize .. and . in a path
+ *
+ * Returns InvalidPath if the path tries to escape the root directory.
+ */
+export function fsNormalize(p: string): FsResult<string> {
+    let s = fsRoot();
+    for (const comp of fsComponents(p)) {
+        if (comp === "..") {
+            const base = fsGetBase(s);
+            if (base.err) {
+                return base;
+            }
+            s = base.val;
+            continue;
+        }
+        s = fsJoin(s, comp);
+    }
+    return { val: s };
+}
+
+/** Join two paths */
+export function fsJoin(p1: string, p2: string): string {
+    if (fsIsRoot(p1)) {
+        return p2;
+    }
+    return p1 + "/" + p2;
+}
+
+/** Iterate through the components of a path. Empty components and . are skipped */
+export function* fsComponents(p: string): Iterable<string> {
+    let i = 0;
+    while (i < p.length) {
+        let nextSlash = p.indexOf("/", i);
+        if (nextSlash < 0) {
+            nextSlash = p.length;
+        }
+        let nextBackslash = p.indexOf("\\", i);
+        if (nextBackslash < 0) {
+            nextBackslash = p.length;
+        }
+        let j = Math.min(nextSlash, nextBackslash);
+        if (j < 0) {
+            j = p.length;
+        }
+        const c = p.substring(i, j);
+        if (c && c !== ".") {
+            yield c;
+        }
+        i = j + 1;
+    }
+}
+
+/** Remove trailing slashes from a path */
+function stripTrailingSlashes(p: string): string {
+    let i = p.length - 1;
+    for (; i >= 0; i--) {
+        if (p[i] !== "/" && p[i] !== "\\") {
+            break;
+        }
+    }
+    if (i === p.length - 1) {
+        return p;
+    }
+    return p.substring(0, i + 1);
+}

package/src/fs/FsSave.ts

@@ -0,0 +1,12 @@
+// workaround for CommonJS
+import pkg from "file-saver";
+const { saveAs } = pkg;
+
+/** Save (download) a file using Blob */
+export function fsSave(content: string | Uint8Array, filename: string) {
+    const blob = new Blob([content], {
+        // maybe lying, but should be fine
+        type: "text/plain;charset=utf-8",
+    });
+    saveAs(blob, filename);
+}

package/src/fs/FsSupportStatus.ts

@@ -0,0 +1,91 @@
+/** What is supported by the current environment */
+export type FsSupportStatus = {
+    /** Returned by window.isSecureContext */
+    isSecureContext: boolean;
+
+    /**
+     * The implementation for FsFileSystem used
+     *
+     * See README.md for more information
+     */
+    implementation: "File" | "FileSystemAccess" | "FileEntry";
+};
+
+/** Get which implementation will be used for the current environment */
+export function fsGetSupportStatus(): FsSupportStatus {
+    if (isFileSystemAccessSupported()) {
+        return {
+            isSecureContext: globalThis.isSecureContext,
+            implementation: "FileSystemAccess",
+        };
+    }
+    if (isFileEntrySupported()) {
+        return {
+            isSecureContext: globalThis.isSecureContext,
+            implementation: "FileEntry",
+        };
+    }
+
+    return {
+        isSecureContext: !!globalThis && globalThis.isSecureContext,
+        implementation: "File",
+    };
+}
+
+function isFileSystemAccessSupported() {
+    if (!globalThis) {
+        return false;
+    }
+    if (!globalThis.isSecureContext) {
+        // In Chrome, you can still access the APIs but they just crash the page entirely
+        return false;
+    }
+    if (!globalThis.FileSystemDirectoryHandle) {
+        return false;
+    }
+
+    if (!globalThis.FileSystemFileHandle) {
+        return false;
+    }
+
+    // since TSlib doesn't have these, let's check here
+
+    // @ts-expect-error FileSystemDirectoryHandle should have a values() method
+    if (!globalThis.FileSystemDirectoryHandle.prototype.values) {
+        return false;
+    }
+
+    // @ts-expect-error window should have showDirectoryPicker
+    if (!globalThis.showDirectoryPicker) {
+        return false;
+    }
+
+    return true;
+}
+
+function isFileEntrySupported(): boolean {
+    if (!globalThis) {
+        return false;
+    }
+
+    // Chrome/Edge has this but it's named DirectoryEntry
+    // AND, they don't work (I forgot how exactly they don't work)
+
+    if (
+        navigator &&
+        navigator.userAgent &&
+        navigator.userAgent.includes("Chrome")
+    ) {
+        return false;
+    }
+
+    if (!globalThis.FileSystemDirectoryEntry) {
+        return false;
+    }
+
+    if (!globalThis.FileSystemFileEntry) {
+        return false;
+    }
+
+    return true;
+}

package/src/fs/index.ts

@@ -0,0 +1,129 @@
+/**
+ * High level browser to file system integration library.
+ *
+ * This library integrates the `File`, `FileEntry` and `FileSystemAccess` API
+ * to provide different levels of integration with file system in web apps.
+ *
+ * Basically, user can select a directory as a mount point, and browser can access
+ * read and sometimes write in the directory.
+ *
+ * ## Support
+ * Use `fsGetSupportStatus()` to inspect which implementation will be used.
+ *
+ * ```typescript
+ * import { fsGetSupportStatus } from "@pistonite/pure/fs";
+ *
+ * const { implementation, isSecureContext } = fsGetSupportStatus();
+ * ```
+ *
+ * `implementation` can be 3 values:
+ * 1. `FileSystemAccess`: This is used for Google Chrome and Edge, and possibly other browsers, under secure context.
+ * 2. `FileEntry`: This is used for Firefox when the FS is mounted through a drag-and-drop interface.
+ * 3. `File`: This is used for Firefox when the FS is mounted by a directory picker dialog
+ *
+ * The implementation is also chosen in this order and the first supported one is selected. If you are on Chrome/Edge and `FileSystemAccess` is not used, you can use `isSecureContext` to narrow down the reason.
+ *
+ * If you are wondering why Safari is not mentioned, it's because Apple made it so I have to buy a Mac to test, which I didn't.
+ *
+ * After you get an instance of `FsFileSystem`, you can use `capabilities` to inspect
+ * what is and is not supported.
+ *
+ * See `FsCapabilities` for more info. This is the support matrix:
+ * |Implementation|`write`?|`live`?|
+ * |--------------|--------|-------|
+ * |`FileSystemAccess`|Yes*|Yes    |
+ * |`FileEntry`   |No      |Yes    |
+ * |`File`        |No      |No     |
+ *
+ * `*` = Need to request permission from user.
+ *
+ *
+ * ## Usage
+ * First you need to get an instance of `FsFileSystem`. You can:
+ * 1. Call `fsOpenRead()` or `fsOpenReadWrite()` to show a directory picker,
+ * 2. Call `fsOpenReadFrom` or `fsOpenReadWriteFrom()` and pass in a `DataTransferItem` from a drag-and-drop interface.
+ *
+ * NOTE: `fsOpenReadWrite` does not guarantee the implementation supports writing. You should check
+ * with `capabilities` afterward.
+ *
+ * This is an example drop zone implementation in TypeScript
+ * ```typescript
+ * import { fsOpenReadWriteFrom } from "@pistonite/pure/fs";
+ *
+ * const div = document.createElement("div");
+ *
+ * div.addEventListener("dragover", (e) => {
+ *     if (e.dataTransfer) {
+ *         // setting this will allow dropping
+ *         e.dataTransfer.dropEffect = "link";
+ *     }
+ * });
+ *
+ * div.addEventListener("drop", async (e) => {
+ *     const item = e.dataTransfer?.items[0];
+ *     if (!item) {
+ *         console.error("no item");
+ *         return;
+ *     }
+ *
+ *     const result = await fsOpenReadWriteFrom(item);
+ *     if (result.err) {
+ *         console.error(result.err);
+ *         return;
+ *     }
+ *
+ *     const fs = result.val;
+ *     const { write, live } = fs.capabilities;
+ *     // check capabilities and use fs
+ *     // ...
+ * });
+ * ```
+ *
+ * ## Retry open
+ * You can pass in a retry handler and return true to retry, when opening fails.
+ * The handler is async so you can ask user.
+ *
+ * ```typescript
+ * import { FsError, FsResult } from "@pistonite/pure/fs";
+ *
+ * async function shouldRetry(error: FsError, attempt: number): Promise<FsResult<boolean>> {
+ *     if (attempt < 10 && error === FsError.PermissionDenied) {
+ *         alert("you must give permission to use this feature!");
+ *         return { val: true };
+ *     }
+ *     return { val: false };
+ * }
+ *
+ * const result = await fsOpenReadWrite(shouldRetry);
+ * ```
+ *
+ * @module
+ */
+export { fsSave } from "./FsSave.ts";
+export {
+    fsOpenRead,
+    fsOpenReadWrite,
+    fsOpenReadFrom,
+    fsOpenReadWriteFrom,
+} from "./FsOpen.ts";
+export { fsGetSupportStatus } from "./FsSupportStatus.ts";
+export {
+    fsRoot,
+    fsIsRoot,
+    fsGetBase,
+    fsGetName,
+    fsNormalize,
+    fsJoin,
+    fsComponents,
+} from "./FsPath.ts";
+export { FsErr, fsErr, fsFail } from "./FsError.ts";
+
+export type { FsOpenRetryHandler } from "./FsOpen.ts";
+export type { FsSupportStatus } from "./FsSupportStatus.ts";
+export type {
+    FsFileSystem,
+    FsFileSystemUninit,
+    FsCapabilities,
+} from "./FsFileSystem.ts";
+export type { FsFile } from "./FsFile.ts";
+export type { FsError, FsResult, FsVoid } from "./FsError.ts";