@pistonite/pure 0.0.12

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2025 Michael
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,8 @@
+# pure
+
+Pure TypeScript utility library for browsers.
+
+These are meant to be only used by my projects so they
+are not stable by any means. However, feel free to use or reference them.
+
+See [GitHub](https://github.com/Pistonite/pure) for more information.

package/package.json

@@ -0,0 +1,33 @@
+{
+    "name": "@pistonite/pure",
+    "version": "0.0.12",
+    "description": "Pure TypeScript libraries for my projects",
+    "homepage": "https://github.com/Pistonite/pure",
+    "bugs": {
+        "url": "https://github.com/Pistonite/pure/issues"
+    },
+    "license": "MIT",
+    "author": "Pistonight <pistonknight@outlook.com>",
+    "files": [
+        "src/**/*"
+    ],
+    "exports": {
+        "./fs": "./src/fs/index.ts",
+        "./log": "./src/log/index.ts",
+        "./result": "./src/result/index.ts",
+        "./sync": "./src/sync/index.ts",
+        "./pref": "./src/pref/index.ts"
+    },
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/Pistonite/pure.git",
+        "directory": "packages/pure"
+    },
+    "dependencies": {
+        "denque": "2.1.0",
+        "file-saver": "2.0.5"
+    },
+    "devDependencies": {
+        "@types/file-saver": "^2.0.7"
+    }
+}

package/src/fs/FsError.ts

@@ -0,0 +1,55 @@
+import type { Result, Void } from "../result/index.ts";
+
+/** Result type for file system operations */
+export const FsErr = {
+    /** Generic error */
+    Fail: 1,
+    /** The operation does not apply to the root directory */
+    IsRoot: 2,
+    /** Invalid encoding */
+    InvalidEncoding: 3,
+    /** Not supported */
+    NotSupported: 4,
+    /** The operation does not apply to a file */
+    IsFile: 5,
+    /** The file was not modified since the last check */
+    NotModified: 6,
+    /** Permission error */
+    PermissionDenied: 7,
+    /** User abort */
+    UserAbort: 8,
+    /** Not found */
+    NotFound: 9,
+    /** Trying to do stuff to a closed file */
+    IsClosed: 10,
+    /** If the path is invalid, for example trying to get the parent of root */
+    InvalidPath: 11,
+    /** Trying to operate on a file that has been closed */
+    Closed: 12,
+    /** The operation does not apply to a directory */
+    IsDirectory: 5,
+} as const;
+
+/** Result type for file system operations */
+export type FsErr = (typeof FsErr)[keyof typeof FsErr];
+
+/** Fs error type with a code and message */
+export type FsError = {
+    readonly code: FsErr;
+    readonly message: string;
+};
+
+/** Helper to create a FsError */
+export function fsErr(code: FsErr, message: string): FsError {
+    return { code, message };
+}
+
+/** Helper to create a FsError with the code Fail */
+export function fsFail(message: string): FsError {
+    return fsErr(FsErr.Fail, message);
+}
+
+/** Helper result type for FsError */
+export type FsResult<T> = Result<T, FsError>;
+/** Helper result type for FsError with no value */
+export type FsVoid = Void<FsError>;

package/src/fs/FsFile.ts

@@ -0,0 +1,67 @@
+import type { FsResult, FsVoid } from "./FsError.ts";
+
+/** Interface for operating on a file in the loaded file system */
+export interface FsFile {
+    /** Path of the file relative to the root of the file system (the uploaded directory) */
+    readonly path: string;
+
+    /** Returns if the content of the file in memory is newer than the file on disk */
+    isDirty(): boolean;
+
+    /** Get the last modified time. May load it from file system if needed */
+    getLastModified(): Promise<FsResult<number>>;
+
+    /**
+     * Get the text content of the file
+     *
+     * If the file is not loaded, it will load it.
+     *
+     * If the file is not a text file, it will return InvalidEncoding
+     */
+    getText(): Promise<FsResult<string>>;
+
+    /** Get the content of the file */
+    getBytes(): Promise<FsResult<Uint8Array>>;
+
+    /**
+     * Set the content in memory. Does not save to disk.
+     * Does nothing if file is closed
+     */
+    setText(content: string): void;
+
+    /**
+     * Set the content in memory. Does not save to disk.
+     * Does nothing if file is closed
+     */
+    setBytes(content: Uint8Array): void;
+
+    /**
+     * Load the file's content if it's not newer than fs
+     *
+     * Returns Ok if the file is newer than fs
+     */
+    loadIfNotDirty(): Promise<FsVoid>;
+
+    /**
+     * Load the file's content from FS.
+     *
+     * Overwrites any unsaved changes in memory only if the file was modified
+     * at a later time than the last in memory modification.
+     *
+     * If it fails, the file's content in memory will not be changed
+     */
+    load(): Promise<FsVoid>;
+
+    /**
+     * Save the file's content to FS if it is dirty.
+     *
+     * If not dirty, returns Ok
+     */
+    writeIfNewer(): Promise<FsVoid>;
+
+    /**
+     * Close the file. In memory content will be lost.
+     * Further operations on the file will fail
+     */
+    close(): void;
+}

package/src/fs/FsFileImpl.ts

@@ -0,0 +1,225 @@
+import { tryAsync, errstr } from "../result/index.ts";
+
+import type { FsFile } from "./FsFile.ts";
+import type { FsFileSystemInternal } from "./FsFileSystemInternal.ts";
+import { FsErr, type FsResult, type FsVoid, fsErr, fsFail } from "./FsError.ts";
+
+/** Allocate a new file object */
+export function fsFile(fs: FsFileSystemInternal, path: string): FsFile {
+    return new FsFileImpl(fs, path);
+}
+
+function errclosed() {
+    return { err: fsErr(FsErr.Closed, "File is closed") } as const;
+}
+
+class FsFileImpl implements FsFile {
+    /** The path of the file */
+    public path: string;
+
+    private closed: boolean;
+
+    /** Reference to the file system so we can read/write */
+    private fs: FsFileSystemInternal;
+    /** If the file is text */
+    private isText: boolean;
+    /** Bytes of the file */
+    private buffer: Uint8Array | undefined;
+    /** If the content in the buffer is different from the content on FS */
+    private isBufferDirty: boolean;
+    /** The content string of the file */
+    private content: string | undefined;
+    /** If the content string is newer than the bytes */
+    private isContentNewer: boolean;
+    /** The last modified time of the file */
+    private lastModified: number | undefined;
+
+    constructor(fs: FsFileSystemInternal, path: string) {
+        this.closed = false;
+        this.fs = fs;
+        this.path = path;
+        this.isText = false;
+        this.buffer = undefined;
+        this.isBufferDirty = false;
+        this.content = undefined;
+        this.isContentNewer = false;
+        this.lastModified = undefined;
+    }
+
+    public close(): void {
+        this.closed = true;
+        this.fs.closeFile(this.path);
+    }
+
+    public isDirty(): boolean {
+        return this.isBufferDirty || this.isContentNewer;
+    }
+
+    public async getLastModified(): Promise<FsResult<number>> {
+        if (this.closed) {
+            return errclosed();
+        }
+        if (this.lastModified === undefined) {
+            const r = await this.loadIfNotDirty();
+            if (r.err) {
+                return r;
+            }
+        }
+        return { val: this.lastModified ?? 0 };
+    }
+
+    public async getText(): Promise<FsResult<string>> {
+        if (this.closed) {
+            return errclosed();
+        }
+        if (this.buffer === undefined) {
+            const r = await this.load();
+            if (r.err) {
+                return r;
+            }
+        }
+        if (!this.isText) {
+            const err = fsFail("File is not valid UTF-8");
+            return { err };
+        }
+        return { val: this.content ?? "" };
+    }
+
+    public async getBytes(): Promise<FsResult<Uint8Array>> {
+        if (this.closed) {
+            return errclosed();
+        }
+        this.updateBuffer();
+        if (this.buffer === undefined) {
+            const r = await this.load();
+            if (r.err) {
+                return r;
+            }
+        }
+        if (this.buffer === undefined) {
+            const err = fsFail(
+                "Read was successful, but content was undefined",
+            );
+            return { err };
+        }
+        return { val: this.buffer };
+    }
+
+    public setText(content: string): void {
+        if (this.closed) {
+            return;
+        }
+        if (this.content === content) {
+            return;
+        }
+        this.content = content;
+        this.isContentNewer = true;
+        this.lastModified = new Date().getTime();
+    }
+
+    public setBytes(content: Uint8Array): void {
+        if (this.closed) {
+            return;
+        }
+        this.buffer = content;
+        this.isBufferDirty = true;
+        this.decodeBuffer();
+        this.isContentNewer = true;
+        this.lastModified = new Date().getTime();
+    }
+
+    public async loadIfNotDirty(): Promise<FsVoid> {
+        if (this.closed) {
+            return errclosed();
+        }
+        if (this.isDirty()) {
+            return {};
+        }
+        return await this.load();
+    }
+
+    public async load(): Promise<FsVoid> {
+        if (this.closed) {
+            return errclosed();
+        }
+        const { val: file, err } = await this.fs.read(this.path);
+        if (err) {
+            return { err };
+        }
+
+        // check if the file has been modified since last loaded
+        if (this.lastModified !== undefined) {
+            if (file.lastModified <= this.lastModified) {
+                return {};
+            }
+        }
+        this.lastModified = file.lastModified;
+        // load the buffer
+        const buffer = await tryAsync(
+            async () => new Uint8Array(await file.arrayBuffer()),
+        );
+        if ("err" in buffer) {
+            const err = fsFail(errstr(buffer.err));
+            return { err };
+        }
+        this.buffer = buffer.val;
+        this.isBufferDirty = false;
+        // Try decoding the buffer as text
+        this.decodeBuffer();
+        this.isContentNewer = false;
+        return {};
+    }
+
+    public async writeIfNewer(): Promise<FsVoid> {
+        if (this.closed) {
+            return errclosed();
+        }
+        if (!this.isDirty()) {
+            return {};
+        }
+        return await this.write();
+    }
+
+    /**
+     * Write the content without checking if it's dirty. Overwrites the file currently on FS
+     *
+     * This is private - outside code should only use writeIfDirty
+     */
+    private async write(): Promise<FsVoid> {
+        this.updateBuffer();
+        const buffer = this.buffer;
+        if (this.content === undefined || buffer === undefined) {
+            // file was never read or modified
+            return {};
+        }
+        const result = await this.fs.write(this.path, buffer);
+        if (result.err) {
+            return result;
+        }
+        this.isBufferDirty = false;
+        return {};
+    }
+
+    private decodeBuffer() {
+        try {
+            this.content = new TextDecoder("utf-8", { fatal: true }).decode(
+                this.buffer,
+            );
+            this.isText = true;
+        } catch (_) {
+            this.content = undefined;
+            this.isText = false;
+        }
+    }
+
+    /** Encode the content to buffer if it is newer */
+    private updateBuffer() {
+        if (!this.isContentNewer || this.content === undefined) {
+            return;
+        }
+        const encoder = new TextEncoder();
+        this.buffer = encoder.encode(this.content);
+        this.isBufferDirty = true;
+        this.isContentNewer = false;
+    }
+}

package/src/fs/FsFileMgr.ts

@@ -0,0 +1,29 @@
+import type { FsFile } from "./FsFile.ts";
+import type { FsFileSystemInternal } from "./FsFileSystemInternal.ts";
+import { fsFile } from "./FsFileImpl.ts";
+
+/** Internal class to track opened files */
+export class FsFileMgr {
+    private opened: { [path: string]: FsFile };
+
+    public constructor() {
+        this.opened = {};
+    }
+
+    public get(fs: FsFileSystemInternal, path: string): FsFile {
+        let file = this.opened[path];
+        if (!file) {
+            file = fsFile(fs, path);
+            this.opened[path] = file;
+        }
+        return file;
+    }
+
+    public close(path: string): void {
+        delete this.opened[path];
+    }
+
+    public getOpenedPaths(): string[] {
+        return Object.keys(this.opened);
+    }
+}

package/src/fs/FsFileSystem.ts

@@ -0,0 +1,71 @@
+import type { FsFile } from "./FsFile.ts";
+import type { FsResult } from "./FsError.ts";
+
+/**
+ * File system before it is initialized
+ *
+ * This is an internal type used inside fsOpen functions
+ */
+export interface FsFileSystemUninit {
+    /// Initialize the file system
+    init(): Promise<FsResult<FsFileSystem>>;
+}
+
+/** Initialized file system */
+export interface FsFileSystem {
+    /**
+     * Get the root path of the file system for display
+     *
+     * The returned string has no significance in the file system itself.
+     * It should only be used as an indicator to the user.
+     */
+    readonly root: string;
+
+    /**
+     * Capabilities of this file system implementation
+     * See README.md for more information
+     */
+    readonly capabilities: FsCapabilities;
+
+    /**
+     * List files in a directory
+     *
+     * The input path should be relative to the root (of the uploaded directory).
+     *
+     * Returns a list of file names in the directory (not full paths).
+     * Directory names end with a slash.
+     *
+     * Returns Fail if the underlying file system operation fails.
+     */
+    listDir: (path: string) => Promise<FsResult<string[]>>;
+
+    /**
+     * Get a file object for operations
+     *
+     * The returned object can store temporary state for the file, such
+     * as newer content. Calling openFile with the same path will
+     * return the same object.
+     *
+     * Note that opening a file doesn't actually block the file
+     * from being modified by programs other than the browser.
+     *
+     * You can make the FsFileSystem forget about the file by
+     * calling `close` on the file object.
+     */
+    getFile: (path: string) => FsFile;
+
+    /** Get all paths that `getFile` has been called with but not `close`d */
+    getOpenedPaths: () => string[];
+}
+
+/** Capabilities of the file system implementation */
+export type FsCapabilities = {
+    /** Can the browser directly write to the file system */
+    write: boolean;
+    /**
+     * Can the browser detect live updates:
+     * - Change of modified time
+     * - Change of directory structure (new, renamed, deleted files)
+     */
+    live: boolean;
+};

package/src/fs/FsFileSystemInternal.ts

@@ -0,0 +1,30 @@
+import type { FsResult, FsVoid } from "./FsError.ts";
+
+/** Internal APIs for FsFileSystem */
+export interface FsFileSystemInternal {
+    /**
+     * Read the file as a File object
+     *
+     * Returns Fail if the underlying file system operation fails.
+     */
+    read: (path: string) => Promise<FsResult<File>>;
+
+    /**
+     * Write content to a file on disk
+     *
+     * Writes the content to the path specified.
+     * If the content is a string, UTF-8 encoding is used.
+     *
+     * Will overwrite existing file.
+     *
+     * Returns Fail if the underlying file system operation fails.
+     * Returns NotSupported if the browser does not support this
+     * Returns PermissionDenied if the operation is supported, but permission is not given
+     */
+    write: (path: string, content: Uint8Array) => Promise<FsVoid>;
+
+    /**
+     * Forget about a file
+     */
+    closeFile: (path: string) => void;
+}