@pistonite/pure 0.22.2 → 0.23.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pistonite/pure",
-  "version": "0.22.2",
+  "version": "0.23.0",
   "type": "module",
   "description": "Pure TypeScript libraries for my projects",
   "homepage": "https://github.com/Pistonite/pure",
@@ -32,8 +32,6 @@
   },
   "devDependencies": {
     "@types/file-saver": "^2.0.7",
-    "eslint": "^9.19.0",
-    "typescript": "^5.7.2",
     "vitest": "^3.0.5",
     "mono-dev": "0.0.0"
   }

package/src/env.d.ts

@@ -0,0 +1 @@
+/// <reference lib="dom" />

package/src/fs/FsFileImpl.ts

@@ -206,7 +206,7 @@ class FsFileImpl implements FsFile {
                 this.buffer,
             );
             this.isText = true;
-        } catch (_) {
+        } catch {
             this.content = undefined;
             this.isText = false;
         }

package/src/fs/FsFileStandalone.ts

@@ -0,0 +1,21 @@
+import type { FsResult, FsVoid } from "./FsError.ts";
+
+/**
+ * Interface for operating on a file opened standalone (without opening a file system
+ */
+export interface FsFileStandalone {
+    /** The name of the file */
+    readonly name: string;
+    /** If the file is writable. May prompt user for permission */
+    isWritable(): Promise<boolean>;
+    /** Get the size of the file */
+    getSize(): Promise<FsResult<number>>;
+    /** Get the content of the file as a byte array */
+    getBytes(): Promise<FsResult<Uint8Array>>;
+    /** Get the last modified time of the file */
+    getLastModified(): Promise<FsResult<number>>;
+    /** Get the text content of the file*/
+    getText(): Promise<FsResult<string>>;
+    /** Write content to the file if the implementation supports writing, and permission is granted*/
+    write(content: Uint8Array | string): Promise<FsVoid>;
+}

package/src/fs/FsFileStandaloneImplFileAPI.ts

@@ -0,0 +1,53 @@
+import { errstr } from "../result";
+
+import { fsErr, FsErr, fsFail, type FsVoid, type FsResult } from "./FsError.ts";
+import type { FsFileStandalone } from "./FsFileStandalone.ts";
+
+export class FsFileStandaloneImplFileAPI implements FsFileStandalone {
+    public name: string;
+    private size: number;
+    private lastModified: number;
+    private file: File;
+
+    constructor(file: File) {
+        this.name = file.name;
+        this.size = file.size;
+        this.lastModified = file.lastModified;
+        this.file = file;
+    }
+
+    public async isWritable(): Promise<boolean> {
+        return false;
+    }
+
+    public async getSize(): Promise<FsResult<number>> {
+        return { val: this.size };
+    }
+
+    public async getBytes(): Promise<FsResult<Uint8Array>> {
+        try {
+            const data = await this.file.bytes();
+            return { val: data };
+        } catch (e) {
+            console.error(e);
+            return { err: fsFail(errstr(e)) };
+        }
+    }
+    public async getLastModified(): Promise<FsResult<number>> {
+        return { val: this.lastModified };
+    }
+    public async getText(): Promise<FsResult<string>> {
+        try {
+            const data = await this.file.text();
+            return { val: data };
+        } catch (e) {
+            console.error(e);
+            return { err: fsFail(errstr(e)) };
+        }
+    }
+    public async write(): Promise<FsVoid> {
+        return {
+            err: fsErr(FsErr.NotSupported, "Write not supported in File API"),
+        };
+    }
+}

package/src/fs/FsFileStandaloneImplHandleAPI.ts

@@ -0,0 +1,152 @@
+import { errstr } from "../result";
+
+import { fsErr, FsErr, fsFail, type FsVoid, type FsResult } from "./FsError.ts";
+import type { FsFileStandalone } from "./FsFileStandalone.ts";
+
+export class FsFileStandaloneImplHandleAPI implements FsFileStandalone {
+    name: string;
+    private handle: FileSystemFileHandle;
+    constructor(handle: FileSystemFileHandle) {
+        this.name = handle.name;
+        this.handle = handle;
+    }
+
+    public async isWritable(): Promise<boolean> {
+        if (
+            !("queryPermission" in this.handle) ||
+            !(typeof this.handle.queryPermission === "function")
+        ) {
+            return false;
+        }
+        try {
+            const permission = await this.handle.queryPermission({
+                mode: "readwrite",
+            });
+            if (permission === "granted") {
+                return true;
+            }
+            if (permission === "denied") {
+                return false;
+            }
+            if (
+                !("requestPermission" in this.handle) ||
+                !(typeof this.handle.requestPermission === "function")
+            ) {
+                return false;
+            }
+            const requestedPermission = await this.handle.requestPermission({
+                mode: "readwrite",
+            });
+            return requestedPermission === "granted";
+        } catch (e) {
+            console.error(e);
+            return false;
+        }
+    }
+
+    private async getFile(): Promise<FsResult<File>> {
+        try {
+            return { val: await this.handle.getFile() };
+        } catch (e) {
+            if (e && typeof e === "object" && "name" in e) {
+                if (e.name === "NotAllowedError") {
+                    return {
+                        err: fsErr(FsErr.PermissionDenied, "Permission denied"),
+                    };
+                }
+                if (e.name === "NotFoundError") {
+                    return { err: fsErr(FsErr.NotFound, "File not found") };
+                }
+            }
+            console.error(e);
+            return { err: fsFail(errstr(e)) };
+        }
+    }
+
+    public async getSize(): Promise<FsResult<number>> {
+        const file = await this.getFile();
+        if (file.err) {
+            return file;
+        }
+        return { val: file.val.size };
+    }
+    public async getBytes(): Promise<FsResult<Uint8Array>> {
+        const file = await this.getFile();
+        if (file.err) {
+            return file;
+        }
+        try {
+            const data = await file.val.bytes();
+            return { val: data };
+        } catch (e) {
+            console.error(e);
+            return { err: fsFail(errstr(e)) };
+        }
+    }
+    public async getLastModified(): Promise<FsResult<number>> {
+        const file = await this.getFile();
+        if (file.err) {
+            return file;
+        }
+        return { val: file.val.lastModified };
+    }
+    public async getText(): Promise<FsResult<string>> {
+        const file = await this.getFile();
+        if (file.err) {
+            return file;
+        }
+        try {
+            const data = await file.val.text();
+            return { val: data };
+        } catch (e) {
+            console.error(e);
+            return { err: fsFail(errstr(e)) };
+        }
+    }
+    public async write(content: Uint8Array | string): Promise<FsVoid> {
+        const writable = await this.isWritable();
+        if (!writable) {
+            return {
+                err: fsErr(
+                    FsErr.NotSupported,
+                    "Permission was not granted or API not supported",
+                ),
+            };
+        }
+        try {
+            const stream = await this.handle.createWritable();
+            await stream.write(content);
+            await stream.close();
+            return {};
+        } catch (e) {
+            if (e && typeof e === "object" && "name" in e) {
+                if (e.name === "NotAllowedError") {
+                    return {
+                        err: fsErr(FsErr.PermissionDenied, "Permission denied"),
+                    };
+                }
+                if (e.name === "NotFoundError") {
+                    return { err: fsErr(FsErr.NotFound, "File not found") };
+                }
+                if (e.name === "NoMidificationAllowedError") {
+                    return {
+                        err: fsErr(
+                            FsErr.PermissionDenied,
+                            "Failed to acquire write lock",
+                        ),
+                    };
+                }
+                if (e.name === "AbortError") {
+                    return { err: fsErr(FsErr.UserAbort, "User abort") };
+                }
+                if (e.name === "QuotaExceededError") {
+                    return {
+                        err: fsErr(FsErr.PermissionDenied, "Quota exceeded"),
+                    };
+                }
+            }
+            console.error(e);
+            return { err: fsFail(errstr(e)) };
+        }
+    }
+}

package/src/fs/FsOpen.ts

@@ -117,6 +117,14 @@ async function createWithPicker(
                     }
                     resolve(createFromFileList(files));
                 });
+                inputElement.addEventListener("cancel", () => {
+                    resolve({
+                        err: fsErr(
+                            FsErr.UserAbort,
+                            "User cancelled the operation",
+                        ),
+                    });
+                });
                 inputElement.click();
             },
         );

package/src/fs/FsOpenFile.ts

@@ -0,0 +1,264 @@
+import { errstr } from "../result";
+
+import { fsErr, FsErr, fsFail, type FsResult } from "./FsError.ts";
+import type { FsFileStandalone } from "./FsFileStandalone.ts";
+import { FsFileStandaloneImplFileAPI } from "./FsFileStandaloneImplFileAPI.ts";
+import { FsFileStandaloneImplHandleAPI } from "./FsFileStandaloneImplHandleAPI.ts";
+
+/**
+ * Prompt user to open a file
+ *
+ * FileSystemAccess API is used on supported platforms, which allows writing after
+ * user grants the permission once at the time of writing to the file. If failed or not supported,
+ * the DOM input element is used as a fallback.
+ */
+export const fsOpenFile = async (
+    options?: FsFileOpenOptions,
+): Promise<FsResult<FsFileStandalone>> => {
+    const result = await fsOpenFileInternal(false, options || {});
+    if (result.err) {
+        return result;
+    }
+    if (!result.val.length) {
+        return { err: fsErr(FsErr.UserAbort, "No files selected") };
+    }
+    return { val: result.val[0] };
+};
+
+/**
+ * Prompt user to open multiple files
+ *
+ * FileSystemAccess API is used on supported platforms, which allows writing after
+ * user grants the permission once at the time of writing to the file. If failed or not supported,
+ * the DOM input element is used as a fallback.
+ *
+ * The returned array is guaranteed to have at least 1 file.
+ */
+export const fsOpenFileMultiple = async (
+    options?: FsFileOpenOptions,
+): Promise<FsResult<FsFileStandalone[]>> => {
+    const result = await fsOpenFileInternal(true, options || {});
+    if (result.err) {
+        return result;
+    }
+    if (!result.val.length) {
+        return { err: fsErr(FsErr.UserAbort, "No files selected") };
+    }
+    return result;
+};
+
+const fsOpenFileInternal = async (
+    multiple: boolean,
+    options: FsFileOpenOptions,
+): Promise<FsResult<FsFileStandalone[]>> => {
+    if (isFileSystemAccessAPISupportedForStandaloneFileOpen()) {
+        const result = await fsOpenFileWithFileSystemAccessAPI(
+            multiple,
+            options,
+        );
+        if (result.val || result.err.code === FsErr.UserAbort) {
+            return result;
+        }
+    }
+    // fallback if FileSystemAccessAPI is not supported or fails
+    return fsOpenFileWithFileAPI(multiple, options);
+};
+
+const fsOpenFileWithFileAPI = async (
+    multiple: boolean,
+    { types }: FsFileOpenOptions,
+): Promise<FsResult<FsFileStandalone[]>> => {
+    const element = document.createElement("input");
+    element.type = "file";
+    if (multiple) {
+        element.multiple = true;
+    }
+    if (types?.length) {
+        const accept = new Set<string>();
+        const len = types.length;
+        for (let i = 0; i < len; i++) {
+            const acceptArray = types[i].accept;
+            const acceptLen = acceptArray.length;
+            for (let j = 0; j < acceptLen; j++) {
+                const acceptValue = acceptArray[j];
+                if (typeof acceptValue === "string") {
+                    accept.add(acceptValue);
+                } else {
+                    const { mime, extensions } = acceptValue;
+                    if (mime) {
+                        accept.add(mime);
+                    }
+                    if (extensions.length) {
+                        extensions.forEach((ext) => {
+                            if (ext) {
+                                accept.add(ext);
+                            }
+                        });
+                    }
+                }
+            }
+        }
+        element.accept = Array.from(accept).join(",");
+    }
+    try {
+        return new Promise((resolve) => {
+            element.addEventListener("cancel", () => {
+                resolve({
+                    err: fsErr(FsErr.UserAbort, "cancel listener invoked"),
+                });
+            });
+            element.addEventListener("change", () => {
+                if (!element.files?.length) {
+                    resolve({
+                        err: fsErr(FsErr.UserAbort, "no files selected"),
+                    });
+                    return;
+                }
+                const array = [];
+                for (let i = 0; i < element.files.length; i++) {
+                    array.push(
+                        new FsFileStandaloneImplFileAPI(element.files[i]),
+                    );
+                }
+                resolve({ val: array });
+            });
+            element.click();
+        });
+    } catch (e) {
+        return { err: fsFail(errstr(e)) };
+    }
+};
+
+const fsOpenFileWithFileSystemAccessAPI = async (
+    multiple: boolean,
+    { id, types, disallowWildcard }: FsFileOpenOptions,
+): Promise<FsResult<FsFileStandalone[]>> => {
+    const convertedTypes = types?.map((type) => {
+        const { description, accept } = type;
+        const convertedAccept: Record<string, string[]> = {};
+        const anyMimeType = [];
+        const len = accept.length;
+        for (let i = 0; i < len; i++) {
+            const acceptValue = accept[i];
+            if (typeof acceptValue === "string") {
+                if (acceptValue) {
+                    anyMimeType.push(acceptValue);
+                }
+                continue;
+            }
+            const { mime, extensions } = acceptValue;
+            if (!mime || mime === "*/*") {
+                anyMimeType.push(...extensions);
+                continue;
+            }
+            if (mime in convertedAccept) {
+                convertedAccept[mime].push(...extensions);
+            } else {
+                convertedAccept[mime] = [...extensions];
+            }
+        }
+        if (anyMimeType.length) {
+            convertedAccept["*/*"] = anyMimeType;
+        }
+        return {
+            description,
+            accept: convertedAccept,
+        };
+    });
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const output = await (globalThis as any).showOpenFilePicker({
+            id,
+            excludeAcceptAllOption: types && types.length && disallowWildcard,
+            multiple,
+            types: convertedTypes,
+        });
+        const len = output.length;
+        const convertedOutput = [];
+        for (let i = 0; i < len; i++) {
+            convertedOutput.push(new FsFileStandaloneImplHandleAPI(output[i]));
+        }
+        return { val: convertedOutput };
+    } catch (e) {
+        if (e && typeof e === "object" && "name" in e) {
+            if (e.name === "AbortError") {
+                return { err: fsErr(FsErr.UserAbort, "User abort") };
+            }
+            if (e.name === "SecurityError") {
+                return { err: fsErr(FsErr.PermissionDenied, "Security error") };
+            }
+        }
+        return { err: fsFail(errstr(e)) };
+    }
+};
+
+export type FsFileOpenOptions = {
+    /**
+     * ID for the file open operation
+     *
+     * Supported implementation can use this to open the picker in the same
+     * directory for the same ID
+     */
+    id?: string;
+
+    /**
+     * If the "*.*" file type should be hidden in the picker.
+     *
+     * In unsupported implementations, this will be ignored, and the "*.*"
+     * file type will always be visible.
+     *
+     * By default, this is false
+     */
+    disallowWildcard?: boolean;
+
+    /** List of file types to accept */
+    types?: FsFileOpenType[];
+};
+
+export type FsFileOpenType = {
+    /**
+     * Optional description for the type, which may display in the file picker
+     *
+     * In unsupported implementations, this will be ignored.
+     */
+    description?: string;
+
+    /**
+     * List of file mime types or extensions to accept for this file type
+     *
+     * String elements are file extensions, with the "." prefix. More context
+     * can be provided with an object element with mime type and extensions to
+     * have better file type descriptions in the picker (if supported).
+     */
+    accept: (FsFileOpenTypeAccept | string)[];
+};
+
+export type FsFileOpenTypeAccept = {
+    /** Optional mime type, which the browser can be used to display file type descriptions */
+    mime?: string;
+    /** extensions to accept (with the "." prefix) */
+    extensions: string[];
+};
+
+const isFileSystemAccessAPISupportedForStandaloneFileOpen = () => {
+    if (!globalThis || !globalThis.isSecureContext) {
+        return false;
+    }
+    if (
+        !("showOpenFilePicker" in globalThis) ||
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        typeof (globalThis as any).showOpenFilePicker !== "function"
+    ) {
+        return false;
+    }
+    if (!globalThis.FileSystemFileHandle) {
+        return false;
+    }
+    if (!globalThis.FileSystemFileHandle.prototype.getFile) {
+        return false;
+    }
+    if (!globalThis.FileSystemFileHandle.prototype.createWritable) {
+        return false;
+    }
+    return true;
+};

package/src/fs/index.ts

@@ -106,6 +106,7 @@ export {
     fsOpenReadFrom,
     fsOpenReadWriteFrom,
 } from "./FsOpen.ts";
+export { fsOpenFile, fsOpenFileMultiple } from "./FsOpenFile.ts";
 export { fsGetSupportStatus } from "./FsSupportStatus.ts";
 export {
     fsRoot,
@@ -119,6 +120,7 @@ export {
 export { FsErr, fsErr, fsFail } from "./FsError.ts";
 
 export type { FsOpenRetryHandler } from "./FsOpen.ts";
+export type * from "./FsOpenFile.ts";
 export type { FsSupportStatus } from "./FsSupportStatus.ts";
 export type {
     FsFileSystem,
@@ -126,4 +128,5 @@ export type {
     FsCapabilities,
 } from "./FsFileSystem.ts";
 export type { FsFile } from "./FsFile.ts";
+export type { FsFileStandalone } from "./FsFileStandalone.ts";
 export type { FsError, FsResult, FsVoid } from "./FsError.ts";

package/src/pref/injectStyle.ts

@@ -4,7 +4,7 @@
  * Will remove the old style tag(s) if exist
  */
 export function injectStyle(id: string, style: string) {
-    const styleTags = document.querySelectorAll(`style[data-inject="${id}"`);
+    const styleTags = document.querySelectorAll(`style[data-inject="${id}"]`);
     if (styleTags.length !== 1) {
         const styleTag = document.createElement("style");
         styleTag.setAttribute("data-inject", id);