@pistonite/pure 0.28.0 → 0.29.0

package/src/fs/index.ts

@@ -1,123 +0,0 @@
-/**
- * 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 { fsOpenFile, fsOpenFileMultiple } from "./FsOpenFile.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 * from "./FsOpenFile.ts";
-export type { FsSupportStatus } from "./FsSupportStatus.ts";
-export type { FsFileSystem, FsFileSystemUninit, 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/log/internal.ts

@@ -1,14 +0,0 @@
-import { resettableLogger } from "./logger.ts";
-
-const { logger, off, debug, info } = resettableLogger("pure", "gray");
-
-export const ilog = logger;
-
-/** Set the internal log level of calls in this library to off */
-export const internalLogOff = off;
-
-/** Set the internal log level of calls in this library to debug */
-export const internalLogDebug = debug;
-
-/** Set the internal log level of calls in this library to info */
-export const internalLogInfo = info;

package/src/memory/async_erc.ts

@@ -1,186 +0,0 @@
-/**
- * A holder for an externally ref-counted object, where free and addref
- * operations are asynchronous.
- *
- * See {@link makeErcType} for how to use
- *
- * @deprecated use Emp
- */
-export type AsyncErc<TName, TRepr = number> = {
-    readonly type: TName;
-
-    /**
-     * Underlying object representation.
-     *
-     * The repr should not be undefinable. undefined means nullptr
-     */
-    readonly value: TRepr | undefined;
-
-    /**
-     * Free the underlying object.
-     *
-     * All weak references will be immediately invalidated, and this Erc becomes
-     * empty. Awaiting on the promise will ensure that the object is freed externally
-     */
-    free: () => Promise<void>;
-
-    /**
-     * Assign a new value to this Erc.
-     *
-     * The old value will be freed, and all weak references will be invalidated.
-     */
-    assign: (value: TRepr | undefined) => Promise<void>;
-
-    /**
-     * Take the inner value without freeing it.
-     *
-     * All weak references will be invalidated, and this Erc will become
-     * empty
-     */
-    take: () => TRepr | undefined;
-
-    /**
-     * Create a weak reference to the inner value.
-     *
-     * When this Erc is freed, all weak references will be invalidated.
-     */
-    getWeak: () => AsyncErcRef<TName, TRepr>;
-
-    /**
-     * Create a strong reference to the inner value, essentially
-     * incrementing the ref count.
-     */
-    getStrong: () => Promise<AsyncErc<TName, TRepr>>;
-};
-
-/**
- * Weak reference to an externally ref-counted object.
- *
- * See {@link makeErcType} for how to use
- *
- * @deprecated use Emp
- */
-export type AsyncErcRef<TName, TRepr = number> = {
-    readonly type: TName;
-
-    /**
-     * The underlying object representation.
-     *
-     * This may become undefined across async calls if the weak reference
-     * is invalidated
-     */
-    readonly value: TRepr | undefined;
-
-    /**
-     * Create a strong reference to the inner value, essentially
-     * incrementing the ref count.
-     */
-    getStrong: () => Promise<AsyncErc<TName, TRepr>>;
-};
-
-/**
- * @deprecated use Emp
- */
-export type AsyncErcRefType<T> =
-    T extends AsyncErc<infer TName, infer TRepr> ? AsyncErcRef<TName, TRepr> : never;
-
-/**
- * @deprecated use Emp
- */
-export type AsyncErcTypeConstructor<TName, TRepr> = {
-    /**
-     * A marker value for the underlying object type.
-     *
-     * This is commonly a string literal or a symbol.
-     */
-    marker: TName;
-
-    /**
-     * The function to free the underlying object.
-     */
-    free: (value: TRepr) => Promise<void> | void;
-
-    /**
-     * Given a value, increase the ref count and return the new reference.
-     * The returned representation should be a different value if double indirection
-     * is used (each value is a pointer to the smart pointer), or the same value
-     * if single indirection is used (the value is pointing to the object itself).
-     */
-    addRef: (value: TRepr) => Promise<TRepr> | TRepr;
-};
-
-/**
- * @deprecated use Emp
- */
-export const makeAsyncErcType = <TName, TRepr>({
-    marker,
-    free,
-    addRef,
-}: AsyncErcTypeConstructor<TName, TRepr>): ((
-    value: TRepr | undefined,
-) => AsyncErc<TName, TRepr>) => {
-    const createStrongRef = (value: TRepr | undefined): AsyncErc<TName, TRepr> => {
-        let weakRef: (AsyncErcRef<TName, TRepr> & { invalidate: () => void }) | undefined =
-            undefined;
-        const invalidateWeakRef = () => {
-            if (!weakRef) {
-                return;
-            }
-            const oldWeakRef = weakRef;
-            weakRef = undefined;
-            oldWeakRef.invalidate();
-        };
-        const createWeakRef = (initialValue: TRepr | undefined) => {
-            const weak = {
-                type: marker,
-                value: initialValue,
-                invalidate: () => {
-                    weak.value = undefined;
-                },
-                getStrong: async () => {
-                    if (weak.value === undefined) {
-                        return createStrongRef(undefined);
-                    }
-                    return createStrongRef(await addRef(weak.value));
-                },
-            };
-            return weak;
-        };
-        const erc = {
-            type: marker,
-            value,
-            free: async () => {
-                if (erc.value !== undefined) {
-                    invalidateWeakRef();
-                    const freePromise = free(erc.value);
-                    erc.value = undefined;
-                    await freePromise;
-                }
-            },
-            assign: async (newValue: TRepr | undefined) => {
-                await erc.free();
-                erc.value = newValue;
-            },
-            take: () => {
-                invalidateWeakRef();
-                const oldValue = erc.value;
-                erc.value = undefined;
-                return oldValue;
-            },
-            getWeak: () => {
-                if (!weakRef) {
-                    weakRef = createWeakRef(erc.value);
-                }
-                return weakRef;
-            },
-            getStrong: async () => {
-                if (erc.value === undefined) {
-                    return createStrongRef(undefined);
-                }
-                return createStrongRef(await addRef(erc.value));
-            },
-        };
-        return erc;
-    };
-    return createStrongRef;
-};

package/src/memory/erc.test.ts

@@ -1,258 +0,0 @@
-import { describe, afterEach, expect, it } from "vitest";
-
-import { type Erc, makeErcType } from "./erc.ts";
-
-type Rc = { value: string; refCount: number };
-const Marker = Symbol("test");
-type Marker = typeof Marker;
-class Allocator {
-    private mockMemory: (Rc | undefined)[] = [];
-    public makeTestErc: (ptr: number) => Erc<Marker>;
-
-    // double indirection means each Erc holds a pointer to the external smart pointer,
-    // which also means external smart pointers all need to be heap allocated
-    // addRef() will return a pointer to a new external smart pointer
-    //
-    // single indirection on the other hand, means each Erc holds a pointer
-    // to the object directly. and addRef() will return the same pointer
-    //
-    // The Erc implementation must work with both
-    constructor(isDoubleIndirection: boolean) {
-        this.makeTestErc = makeErcType({
-            marker: Marker,
-            free: (ptr: number) => {
-                if (ptr < 0 || ptr >= this.mockMemory.length) {
-                    throw new Error(
-                        `Invalid index into mock memory. Length is ${this.mockMemory.length} but index is ${ptr}`,
-                    );
-                }
-
-                const rc = this.mockMemory[ptr];
-                if (!rc) {
-                    throw new Error("Double free detected");
-                }
-
-                rc.refCount--;
-                if (isDoubleIndirection) {
-                    this.mockMemory[ptr] = undefined;
-                    return;
-                }
-
-                if (rc.refCount === 0) {
-                    this.mockMemory[ptr] = undefined;
-                }
-            },
-            addRef: (value: number) => {
-                if (value < 0 || value >= this.mockMemory.length) {
-                    throw new Error(
-                        `Invalid index into mock memory. Length is ${this.mockMemory.length} but index is ${value}`,
-                    );
-                }
-
-                const rc = this.mockMemory[value];
-                if (!rc) {
-                    throw new Error("AddRef on freed memory detected");
-                }
-                rc.refCount++;
-                if (isDoubleIndirection) {
-                    for (let i = 0; i < this.mockMemory.length; i++) {
-                        if (this.mockMemory[i] === undefined) {
-                            this.mockMemory[i] = rc;
-                            return i;
-                        }
-                    }
-                    this.mockMemory.push(rc);
-                    return this.mockMemory.length - 1;
-                }
-
-                return value;
-            },
-        });
-    }
-
-    allocValue(value: string): number {
-        const rc: Rc = { value, refCount: 1 };
-        for (let i = 0; i < this.mockMemory.length; i++) {
-            if (this.mockMemory[i] === undefined) {
-                this.mockMemory[i] = rc;
-                return i;
-            }
-        }
-        this.mockMemory.push(rc);
-        return this.mockMemory.length - 1;
-    }
-
-    getValue(ptr: number | undefined): string {
-        if (ptr === undefined) {
-            throw new Error("Dereference of nullptr");
-        }
-        if (ptr < 0 || ptr >= this.mockMemory.length) {
-            throw new Error(
-                `Invalid index into mock memory. Length is ${this.mockMemory.length} but index is ${ptr}`,
-            );
-        }
-
-        const rc = this.mockMemory[ptr];
-        if (!rc) {
-            throw new Error("Dangling pointer");
-        }
-        return rc.value;
-    }
-
-    expectNoLeak(): void {
-        for (let i = 0; i < this.mockMemory.length; i++) {
-            const rc = this.mockMemory[i];
-            if (rc) {
-                throw new Error(
-                    `Memory leak detected at index ${i}. Value: ${rc.value}, RefCount: ${rc.refCount}`,
-                );
-            }
-        }
-    }
-
-    cleanup(): void {
-        this.mockMemory = [];
-    }
-}
-
-describe.each`
-    indirection | allocator
-    ${"single"} | ${new Allocator(false)}
-    ${"double"} | ${new Allocator(true)}
-`("Erc - $indirection indirection", ({ allocator }: { allocator: Allocator }) => {
-    afterEach(() => {
-        allocator.cleanup();
-    });
-
-    it("allocate and deallocate correctly", () => {
-        const test = allocator.makeTestErc(allocator.allocValue("Hello"));
-        expect(allocator.getValue(test.value)).toBe("Hello");
-        test.free();
-        allocator.expectNoLeak();
-    });
-
-    it("frees if assigned new value", () => {
-        const test = allocator.makeTestErc(allocator.allocValue("Hello"));
-        test.assign(allocator.allocValue("World"));
-        expect(allocator.getValue(test.value)).toBe("World");
-        test.free();
-        allocator.expectNoLeak();
-    });
-
-    it("does not free when taking value", () => {
-        const test = allocator.makeTestErc(allocator.allocValue("Hello"));
-        const raw = test.take();
-        expect(allocator.getValue(raw)).toBe("Hello");
-        expect(test.value).toBeUndefined();
-        if (raw === undefined) {
-            throw new Error("Raw value is undefined");
-        }
-        allocator.makeTestErc(raw).free();
-        allocator.expectNoLeak();
-    });
-
-    it("invalidates weak references on free", () => {
-        const test = allocator.makeTestErc(allocator.allocValue("Hello"));
-        const testWeak = test.getWeak();
-        expect(allocator.getValue(testWeak.value)).toBe("Hello");
-        test.free();
-        expect(testWeak.value).toBeUndefined();
-        allocator.expectNoLeak();
-    });
-
-    it("invalidates weak references on assign", () => {
-        const test = allocator.makeTestErc(allocator.allocValue("Hello"));
-        const testWeak = test.getWeak();
-        expect(allocator.getValue(testWeak.value)).toBe("Hello");
-        test.assign(allocator.allocValue("World"));
-        expect(testWeak.value).toBeUndefined();
-        test.free();
-        allocator.expectNoLeak();
-    });
-
-    it("handles assign and take of different references correctly", () => {
-        const test1 = allocator.makeTestErc(allocator.allocValue("Hello"));
-        const test2 = allocator.makeTestErc(allocator.allocValue("World"));
-        expect(allocator.getValue(test1.value)).toBe("Hello");
-        expect(allocator.getValue(test2.value)).toBe("World");
-        test1.assign(test2.take());
-        expect(allocator.getValue(test1.value)).toBe("World");
-        test1.free();
-        allocator.expectNoLeak();
-    });
-
-    it("handles assign and take of same references correctly", () => {
-        const test1 = allocator.makeTestErc(allocator.allocValue("Hello"));
-        const test2 = test1.getStrong();
-        test1.assign(test2.take());
-        expect(allocator.getValue(test1.value)).toBe("Hello");
-        test1.free();
-        test2.free(); // should be no-op
-        allocator.expectNoLeak();
-    });
-
-    it("assigning another Erc directly should cause double free", async () => {
-        const test1 = allocator.makeTestErc(allocator.allocValue("Hello"));
-        const test2 = test1.getStrong();
-        test1.assign(test2.value);
-        expect(allocator.getValue(test1.value)).toBe("Hello");
-        test1.free();
-
-        const freeTest2 = async () => {
-            test2.free();
-        };
-        await expect(freeTest2).rejects.toThrow("Double free detected");
-        allocator.expectNoLeak();
-    });
-
-    it("handles assign and take of same references correctly (same Erc)", () => {
-        const test1 = allocator.makeTestErc(allocator.allocValue("Hello"));
-        test1.assign(test1.take());
-        expect(allocator.getValue(test1.value)).toBe("Hello");
-        test1.free();
-        allocator.expectNoLeak();
-    });
-
-    it("assigning another Erc directly should cause double free (same Erc)", async () => {
-        const test1 = allocator.makeTestErc(allocator.allocValue("Hello"));
-        test1.assign(test1.value);
-        const getTest1Value = async () => {
-            allocator.getValue(test1.value);
-        };
-        await expect(getTest1Value).rejects.toThrow("Dangling pointer");
-
-        const freeTest1 = async () => {
-            test1.free();
-        };
-        await expect(freeTest1).rejects.toThrow("Double free detected");
-        allocator.expectNoLeak();
-    });
-
-    it("inc ref count with strong reference", () => {
-        const test = allocator.makeTestErc(allocator.allocValue("Hello"));
-        const test2 = test.getStrong();
-        expect(allocator.getValue(test.value)).toBe("Hello");
-        expect(allocator.getValue(test2.value)).toBe("Hello");
-        test.free();
-        expect(allocator.getValue(test2.value)).toBe("Hello");
-        test2.free();
-        allocator.expectNoLeak();
-    });
-
-    it("inc ref count with strong reference from weak reference", () => {
-        const test = allocator.makeTestErc(allocator.allocValue("Hello"));
-        const testWeak = test.getWeak();
-        expect(allocator.getValue(testWeak.value)).toBe("Hello");
-        const test2 = testWeak.getStrong();
-        expect(allocator.getValue(testWeak.value)).toBe("Hello");
-        expect(allocator.getValue(test2.value)).toBe("Hello");
-        const test2Weak = test2.getWeak();
-        test.free();
-        expect(testWeak.value).toBeUndefined();
-        expect(allocator.getValue(test2.value)).toBe("Hello");
-        expect(allocator.getValue(test2Weak.value)).toBe("Hello");
-        test2.free();
-        expect(test2Weak.value).toBeUndefined();
-        allocator.expectNoLeak();
-    });
-});