@pistonite/pure 0.28.0 → 0.29.0

package/src/sync/debounce.ts

@@ -1,7 +1,16 @@
 import { type AnyFn, type AwaitRet, makePromise, type PromiseHandle } from "./util.ts";
 
+/** Factory for debounced function. See {@link DebounceConstructor} for usage */
+export function debounce<TFn extends AnyFn>(args: DebounceConstructor<TFn>) {
+    const { fn, interval, disregardExecutionTime } = args;
+    const impl = new DebounceImpl(fn, interval, !!disregardExecutionTime);
+    return (...args: Parameters<TFn>) => impl.invoke(...args);
+}
+
 /**
- * An async event wrapper that is guaranteed to:
+ * Options for `debounce` function
+ *
+ * A debounced function is an async event wrapper that is guaranteed to:
  * - Not re-fire in a minimal interval after it's initialially fired.
  * - All calls will eventually fire
  *
@@ -78,19 +87,7 @@ import { type AnyFn, type AwaitRet, makePromise, type PromiseHandle } from "./ut
  * });
  * ```
  */
-export function debounce<TFn extends AnyFn>({
-    fn,
-    interval,
-    disregardExecutionTime,
-}: DebounceConstructor<TFn>) {
-    const impl = new DebounceImpl(fn, interval, !!disregardExecutionTime);
-    return (...args: Parameters<TFn>) => impl.invoke(...args);
-}
-
-/**
- * Options for `debounce` function
- */
-export type DebounceConstructor<TFn> = {
+export interface DebounceConstructor<TFn> {
     /** Function to be debounced */
     fn: TFn;
     /**
@@ -111,7 +108,7 @@ export type DebounceConstructor<TFn> = {
      * set this to true.
      */
     disregardExecutionTime?: boolean;
-};
+}
 
 class DebounceImpl<TFn extends AnyFn> {
     private idle: boolean;

package/src/sync/index.ts

@@ -1,6 +1,5 @@
 /**
- * # pure/sync
- * JS synchronization utilities
+ * Synchronization utilities
  *
  * @module
  */
@@ -10,7 +9,7 @@ export {
     type SerialEventCancelCallback,
     type SerialCancelToken,
 } from "./serial.ts";
-export { latest, type LatestConstructor, type UpdateArgsFn } from "./latest.ts";
+export { latest, type LatestConstructor, type LatestUpdateArgsFn } from "./latest.ts";
 export { debounce, type DebounceConstructor } from "./debounce.ts";
 export { batch, type BatchConstructor } from "./batch.ts";
 export { once, type OnceConstructor } from "./once.ts";

package/src/sync/latest.test.ts

@@ -1,4 +1,4 @@
-import { expect, test, describe } from "vitest";
+import { expect, test, describe } from "mono-dev/vitest";
 
 import { latest } from "./latest.ts";
 

package/src/sync/latest.ts

@@ -1,7 +1,18 @@
 import { type AnyFn, type AwaitRet, makePromise, type PromiseHandle } from "./util.ts";
 
 /**
- * An async event wrapper that always resolve to the result of the latest
+ * Factory for `latest`. See {@link LatestConstructor} for usage.
+ */
+export function latest<TFn extends AnyFn>(args: LatestConstructor<TFn>) {
+    const { fn, areArgsEqual, updateArgs } = args;
+    const impl = new LatestImpl(fn, areArgsEqual, updateArgs);
+    return (...args: Parameters<TFn>) => impl.invoke(...args);
+}
+
+/**
+ * Args for constructing `latest`
+ *
+ * `latest` is an async event wrapper that always resolve to the result of the latest
  * call
  *
  * ## Example
@@ -31,16 +42,7 @@ import { type AnyFn, type AwaitRet, makePromise, type PromiseHandle } from "./ut
  * See the constructor options for more advanced usage, for example,
  * control how arguments are updated when new calls are made.
  */
-export function latest<TFn extends AnyFn>({
-    fn,
-    areArgsEqual,
-    updateArgs,
-}: LatestConstructor<TFn>) {
-    const impl = new LatestImpl(fn, areArgsEqual, updateArgs);
-    return (...args: Parameters<TFn>) => impl.invoke(...args);
-}
-
-export type LatestConstructor<TFn extends AnyFn> = {
+export interface LatestConstructor<TFn extends AnyFn> {
     /** Function to be wrapped */
     fn: TFn;
 
@@ -72,9 +74,10 @@ export type LatestConstructor<TFn extends AnyFn> = {
      *   to be executed next.
      *
      */
-    updateArgs?: UpdateArgsFn<TFn>;
-};
-export type UpdateArgsFn<TFn extends AnyFn> = (
+    updateArgs?: LatestUpdateArgsFn<TFn>;
+}
+/** See {@link LatestConstructor} */
+export type LatestUpdateArgsFn<TFn extends AnyFn> = (
     current: Parameters<TFn>,
     middle: Parameters<TFn>[],
     latest: Parameters<TFn>,
@@ -91,12 +94,12 @@ export class LatestImpl<TFn extends AnyFn> {
     private middleArgs: Parameters<TFn>[];
 
     private areArgsEqual: (a: Parameters<TFn>, b: Parameters<TFn>) => boolean;
-    private updateArgs: UpdateArgsFn<TFn>;
+    private updateArgs: LatestUpdateArgsFn<TFn>;
 
     constructor(
         private fn: TFn,
         areArgsEqual?: (a: Parameters<TFn>, b: Parameters<TFn>) => boolean,
-        updateArgs?: UpdateArgsFn<TFn>,
+        updateArgs?: LatestUpdateArgsFn<TFn>,
     ) {
         this.middleArgs = [];
         this.areArgsEqual = areArgsEqual || (() => false);

package/src/sync/once.test.ts

@@ -1,4 +1,4 @@
-import { expect, test } from "vitest";
+import { expect, test } from "mono-dev/vitest";
 
 import { once } from "./once.ts";
 

package/src/sync/once.ts

@@ -1,7 +1,17 @@
 import { type AnyFn, type AwaitRet, makePromise } from "./util.ts";
 
 /**
- * An async event wrapper that ensures an async initialization is only ran once.
+ * Factory function for `once`. See {@link OnceConstructor} for usage
+ */
+export function once<TFn extends AnyFn>(args: OnceConstructor<TFn>) {
+    const impl = new OnceImpl(args.fn);
+    return (...args: Parameters<TFn>) => impl.invoke(...args);
+}
+
+/**
+ * Args for constructing a `once`
+ *
+ * `once` is an async event wrapper that ensures an async initialization is only ran once.
  * Any subsequent calls after the first call will return a promise that resolves/rejects
  * with the result of the first call.
  *
@@ -66,15 +76,10 @@ import { type AnyFn, type AwaitRet, makePromise } from "./util.ts";
  * This is not an issue if the resource doesn't leak other resources,
  * since it will eventually be GC'd.
  */
-export function once<TFn extends AnyFn>({ fn }: OnceConstructor<TFn>) {
-    const impl = new OnceImpl(fn);
-    return (...args: Parameters<TFn>) => impl.invoke(...args);
-}
-
-export type OnceConstructor<TFn> = {
+export interface OnceConstructor<TFn> {
     /** Function to be called only once */
     fn: TFn;
-};
+}
 
 export class OnceImpl<TFn extends AnyFn> {
     private promise: Promise<AwaitRet<TFn>> | undefined;

package/src/sync/serial.test.ts

@@ -1,4 +1,4 @@
-import { test, expect, expectTypeOf, vi } from "vitest";
+import { test, expect, expectTypeOf, vi } from "mono-dev/vitest";
 
 import { serial, type SerialCancelToken } from "./serial.ts";
 import type { Result } from "../result/index.ts";

package/src/sync/serial.ts

@@ -2,7 +2,18 @@ import type { Result } from "../result/index.ts";
 import type { AnyFn } from "./util.ts";
 
 /**
- * An async event wrapper that is cancelled when a new one starts.
+ * Factory function for `serial`. See {@link SerialConstructor} for usage
+ */
+export const serial = <TFn extends AnyFn>(args: SerialConstructor<TFn>) => {
+    const { fn, onCancel } = args;
+    const impl = new SerialImpl(fn, onCancel);
+    return (...args: Parameters<TFn>) => impl.invoke(...args);
+};
+
+/**
+ * Options for `serial` function
+ *
+ * `serial` is an async event wrapper that is cancelled when a new one starts.
  * When a new event is started, the previous caller will receive a
  * cancellation error, instead of being hung up indefinitely.
  *
@@ -132,16 +143,7 @@ import type { AnyFn } from "./util.ts";
  *
  * If the underlying function throws, the exception will be re-thrown to the caller.
  */
-
-export function serial<TFn extends AnyFn>({ fn, onCancel }: SerialConstructor<TFn>) {
-    const impl = new SerialImpl(fn, onCancel);
-    return (...args: Parameters<TFn>) => impl.invoke(...args);
-}
-
-/**
- * Options for `serial` function
- */
-export type SerialConstructor<TFn> = {
+export interface SerialConstructor<TFn> {
     /**
      * Function creator that returns the async function to be wrapped
      */
@@ -152,7 +154,7 @@ export type SerialConstructor<TFn> = {
      * This is guaranteed to be only called at most once per execution
      */
     onCancel?: SerialEventCancelCallback;
-};
+}
 
 class SerialImpl<TFn extends AnyFn> {
     private serial: SerialId;

package/src/sync/util.ts

@@ -18,11 +18,11 @@ export const makePromise = <T>(): PromiseHandle<T> => {
  * A handle of the promise that breaks down the promise object
  * and its resolve and reject functions
  */
-export type PromiseHandle<T> = {
+export interface PromiseHandle<T> {
     promise: Promise<T>;
     resolve: (value: T | PromiseLike<T>) => void;
     reject: (reason?: unknown) => void;
-};
+}
 
 /** Shorthand for Awaited<ReturnType<T>> */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any

package/src/fs/FsError.ts

@@ -1,55 +0,0 @@
-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

@@ -1,67 +0,0 @@
-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<ArrayBuffer>): 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

@@ -1,219 +0,0 @@
-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<ArrayBuffer> | 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<ArrayBuffer>): 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

@@ -1,29 +0,0 @@
-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: Map<string, FsFile>;
-
-    public constructor() {
-        this.opened = new Map();
-    }
-
-    public get(fs: FsFileSystemInternal, path: string): FsFile {
-        let file = this.opened.get(path);
-        if (!file) {
-            file = fsFile(fs, path);
-            this.opened.set(path, file);
-        }
-        return file;
-    }
-
-    public close(path: string): void {
-        this.opened.delete(path);
-    }
-
-    public getOpenedPaths(): string[] {
-        return Array.from(this.opened.keys());
-    }
-}

package/src/fs/FsFileStandalone.ts

@@ -1,21 +0,0 @@
-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>;
-}