@pistonite/pure 0.0.18 → 0.0.20

package/package.json

@@ -1,35 +1,39 @@
 {
-    "name": "@pistonite/pure",
-    "version": "0.0.18",
-    "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/**/*",
-        "!src/**/*.test.ts"
-    ],
-    "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": {
-        "@types/file-saver": "^2.0.7",
-        "denque": "2.1.0",
-        "file-saver": "2.0.5"
-    },
-    "devDependencies": {
-        "vitest": "^2.1.8"
-    }
-}
+  "name": "@pistonite/pure",
+  "version": "0.0.20",
+  "type": "module",
+  "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/**/*",
+    "!src/**/*.test.ts"
+  ],
+  "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",
+    "eslint": "^9.19.0",
+    "typescript": "^5.7.2",
+    "vitest": "^3.0.5",
+    "mono-dev": "0.0.0"
+  }
+}

package/src/fs/FsFileMgr.ts

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

package/src/pref/dark.ts

@@ -1,5 +1,47 @@
+import { persist } from "../sync/persist.ts";
+import { injectStyle } from "./injectStyle.ts";
+
+const dark = persist({
+    initial: false,
+    key: "Pure.Dark",
+    storage: localStorage,
+    serialize: (value) => (value ? "1" : ""),
+    deserialize: (value) => !!value,
+});
+
 /**
- * Dark mode wrappers
+ * Returns if dark mode is prefered in the browser environment
+ *
+ * If `window.matchMedia` is not available, it will return `false`
+ */
+export const prefersDarkMode = (): boolean => {
+    return !!globalThis.matchMedia?.("(prefers-color-scheme: dark)").matches;
+};
+
+/** Value for the `color-scheme` CSS property */
+export type ColorScheme = "light" | "dark";
+/** Option for initializing dark mode */
+export type DarkOptions = {
+    /**
+     * Initial value for dark mode
+     *
+     * If not set, it will default to calling `prefersDarkMode()`.
+     *
+     * If `persist` is `true`, it will also check the value from localStorage
+     */
+    initial?: boolean;
+    /** Persist the dark mode preference to localStorage */
+    persist?: boolean;
+    /**
+     * The selector to set `color-scheme` property
+     *
+     * Defaults to `:root`. If set to empty string, CSS will not be updated
+     */
+    selector?: string;
+};
+
+/**
+ * Init Dark mode wrappers
  *
  * ## Detect user preference
  * User preference is detected with `matchMedia` API, if available.
@@ -46,59 +88,9 @@
  * // will set `.my-app { color-scheme: dark }`
  * initDark({ selector: ".my-app" });
  * ```
- *
- * @module
- */
-
-import { persist } from "../sync/persist.ts";
-import { injectStyle } from "./injectStyle.ts";
-
-const dark = persist({
-    initial: false,
-    key: "Pure.Dark",
-    storage: localStorage,
-    serialize: (value) => (value ? "1" : ""),
-    deserialize: (value) => !!value,
-});
-
-/**
- * Returns if dark mode is prefered in the browser environment
- *
- * If `window.matchMedia` is not available, it will return `false`
- */
-export const prefersDarkMode = (): boolean => {
-    return !!globalThis.matchMedia?.("(prefers-color-scheme: dark)").matches;
-};
-
-/** Value for the `color-scheme` CSS property */
-export type ColorScheme = "light" | "dark";
-/** Option for initializing dark mode */
-export type DarkOptions = {
-    /**
-     * Initial value for dark mode
-     *
-     * If not set, it will default to calling `prefersDarkMode()`.
-     *
-     * If `persist` is `true`, it will also check the value from localStorage
-     */
-    initial?: boolean;
-    /** Persist the dark mode preference to localStorage */
-    persist?: boolean;
-    /**
-     * The selector to set `color-scheme` property
-     *
-     * Defaults to `:root`. If set to empty string, CSS will not be updated
-     */
-    selector?: string;
-};
-
-/**
- * Initializes dark mode
- *
- * @param options Options for initializing dark mode
  */
 export const initDark = (options: DarkOptions = {}): void => {
-    let _dark = options.initial || prefersDarkMode();
+    const _dark = options.initial || prefersDarkMode();
 
     const selector = options.selector ?? ":root";
     if (selector) {

package/src/pref/locale.ts

@@ -1,58 +1,3 @@
-/**
- * Locale utilities and integration with i18next
- *
- * ## Initialization
- * `initLocale` must be called before using the other functions.
- *
- * ```typescript
- * import { initLocale } from "@pistonite/pure/pref";
- *
- * initLocale({
- *     // required
- *     supported: ["en", "zh-CN", "zh-TW"] as const,
- *     default: "en",
- *
- *     // optional
- *     persist: true, // save to localStorage
- *     initial: "en-US", // initial value, instead of detecting
- * });
- * ```
- *
- * ## Connecting with i18next
- * The typical usage for this component is to use i18next for localization.
- * This module provides 2 plugins:
- * - `detectLocale`:
- *   - Provide the current language to i18next (as a language detector)
- *   - Update the global locale state whenever `i18next.changeLanguage` is called
- * - `connectI18next`:
- *   - Call `i18next.changeLanguage` whenever `setLocale` is called
- *
- * You might only need one of these plugins, depending on your use case.
- * For example, if you will never call `setLocale` manually, then you don't need `connectI18next`.
- *
- * ```typescript
- * import i18next from "i18next";
- * import { initLocale, detectLocale, connectI18next } from "@pistonite/pure/pref";
- *
- * // initialize locale
- * initLocale({ supported: ["en", "es"], default: "en", persist: true });
- *
- * // connect with i18next
- * i18next.use(detectLocale).use(connectI18next).init({
- *   // ...other options not shown
- * });
- * ```
- *
- * ## Use with React
- * A React hook is provided in the [`pure-react`](https://jsr.io/@pistonite/pure-react/doc/pref) package
- * to get the current locale from React components.
- *
- * Changing the locale from React components is the same as from outside React,
- * with `setLocale` or `i18next.changeLanguage`, depending on your setup.
- *
- * @module
- */
-
 import { persist } from "../sync/persist.ts";
 
 let supportedLocales: readonly string[] = [];
@@ -114,7 +59,37 @@ export type LocaleOptions<TLocale extends string> = {
     persist?: boolean;
 };
 
-/** Initialize locale global state */
+/**
+ * Initialize Locale utilities
+ *
+ * `initLocale` must be called before using the other functions.
+ *
+ * ```typescript
+ * import { initLocale } from "@pistonite/pure/pref";
+ *
+ * initLocale({
+ *     // required
+ *     supported: ["en", "zh-CN", "zh-TW"] as const,
+ *     default: "en",
+ *
+ *     // optional
+ *     persist: true, // save to localStorage
+ *     initial: "en-US", // initial value, instead of detecting
+ * });
+ * ```
+ *
+ * ## Connecting with i18next
+ * The `@pistonite/pure-i18next` package provides additional wrapper
+ * for connecting with i18next. See the documentation there for more details.
+ * You will use `initLocaleWithI18next` instead of `initLocale`.
+ *
+ * ## Use with React
+ * A React hook is provided in the [`pure-react`](https://jsr.io/@pistonite/pure-react/doc/pref) package
+ * to get the current locale from React components.
+ *
+ * Changing the locale from React components is the same as from outside React,
+ * with `setLocale` or `i18next.changeLanguage`, depending on your setup.
+ */
 export const initLocale = <TLocale extends string>(
     options: LocaleOptions<TLocale>,
 ): void => {
@@ -236,62 +211,6 @@ export const addLocaleSubscriber = (
     return locale.subscribe(fn, notifyImmediately);
 };
 
-/**
- * Language detector plugin for i18next
- *
- * **Must call `initLocale` before initializaing i18next**
- *
- * This also sets the global locale state whenever `i18next.changeLanguage` is called.
- *
- * # Example
- * ```typescript
- * import i18next from "i18next";
- * import { initLocale, detectLocale } from "@pistonite/pure/pref";
- *
- * initLocale({ supported: ["en", "es"], default: "en", persist: true });
- *
- * i18next.use(detectLocale).init({
- *   // don't need to specify `lng` here
- *
- *   // ...other options not shown
- * });
- * ```
- *
- */
-export const detectLocale = {
-    type: "languageDetector" as const,
-    detect: (): string => locale.get(),
-    cacheUserLanguage: (lng: string): void => {
-        setLocale(lng);
-    },
-};
-
-/**
- * Bind the locale state to i18next, so whenever `setLocale`
- * is called, it will also call `i18next.changeLanguage`.
- *
- * # Example
- * ```typescript
- * import i18next from "i18next";
- * import { connectI18next, initLocale } from "@pistonite/pure/pref";
- *
- * initLocale({ supported: ["en", "es"], default: "en", persist: true });
- * i18next.use(connectI18next).init({
- *  // ...options
- * });
- *
- */
-export const connectI18next = {
-    type: "3rdParty" as const,
-    init: (i18next: any): void => {
-        addLocaleSubscriber((locale) => {
-            if (i18next.language !== locale) {
-                i18next.changeLanguage(locale);
-            }
-        }, true);
-    },
-};
-
 const localizedLanguageNames = new Map();
 
 /**
@@ -316,3 +235,6 @@ export const getLocalizedLanguageName = (language: string): string => {
     localizedLanguageNames.set(language, localized);
     return localized || language;
 };
+
+/** Get the array of supported locales passed to init */
+export const getSupportedLocales = (): readonly string[] => supportedLocales;

package/src/sync/RwLock.ts

@@ -44,12 +44,14 @@ export class RwLock<TRead, TWrite extends TRead = TRead> {
             if (this.writeWaiters.length > 0) {
                 if (this.readers === 0) {
                     // notify one writer
+                    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
                     this.writeWaiters.shift()!();
                 }
                 // don't notify anyone if there are still readers
             } else {
                 // notify all readers
                 while (this.readWaiters.length > 0) {
+                    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
                     this.readWaiters.shift()!();
                 }
             }
@@ -85,9 +87,11 @@ export class RwLock<TRead, TWrite extends TRead = TRead> {
             this.isWriting = false;
             if (this.readWaiters.length > 0) {
                 // notify one reader
+                // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
                 this.readWaiters.shift()!();
             } else if (this.writeWaiters.length > 0) {
                 // notify one writer
+                // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
                 this.writeWaiters.shift()!();
             }
         }

package/src/sync/batch.test.ts

@@ -0,0 +1,116 @@
+import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
+
+import { batch } from "./batch.ts";
+
+describe("batch", () => {
+    // sum the inputs
+    const batchFn = vi.fn((inputs: [number][]): [number] => {
+        const out = inputs.reduce((acc, [x]) => acc + x, 0);
+        return [out];
+    });
+    beforeEach(() => {
+        vi.useFakeTimers();
+    });
+    afterEach(() => {
+        vi.runAllTimers();
+        vi.useRealTimers();
+        batchFn.mockClear();
+    });
+    test("initial call executed immediately", async () => {
+        const fn = vi.fn();
+        const execute = batch({
+            fn: (x: number) => {
+                fn(x);
+                return x * 2;
+            },
+            batch: batchFn,
+            interval: 100,
+        });
+
+        const result = await execute(1);
+        expect(result).toStrictEqual(2);
+        expect(fn).toHaveBeenCalledTimes(1);
+        expect(batchFn).not.toHaveBeenCalled();
+    });
+    test("does not batch call executed after interval if only one", async () => {
+        const fn = vi.fn();
+        const execute = batch({
+            fn: (x: number) => {
+                fn(x);
+                return x * 2;
+            },
+            batch: batchFn,
+            interval: 100,
+        });
+
+        const result = await execute(1);
+        expect(result).toStrictEqual(2);
+        const promise2 = execute(2);
+        vi.advanceTimersByTime(99);
+        expect(fn).toHaveBeenCalledTimes(1);
+        vi.advanceTimersByTime(1);
+        expect(fn).toHaveBeenCalledTimes(2);
+        expect(await promise2).toStrictEqual(4);
+
+        expect(batchFn).not.toHaveBeenCalled();
+    });
+    test("batch call executed after interval if more than 1 call", async () => {
+        const fn = vi.fn();
+        const execute = batch({
+            fn: (x: number) => {
+                fn(x);
+                return x * 2;
+            },
+            batch: batchFn,
+            interval: 100,
+        });
+
+        const result = await execute(1);
+        expect(result).toStrictEqual(2);
+        const promise2 = execute(2);
+        const promise3 = execute(3);
+        vi.advanceTimersByTime(99);
+        expect(fn).toHaveBeenCalledTimes(1);
+        vi.advanceTimersByTime(1);
+        expect(fn).toHaveBeenCalledTimes(2);
+        expect(await promise2).toStrictEqual(10);
+        expect(await promise3).toStrictEqual(10);
+
+        expect(batchFn).toHaveBeenCalledTimes(1);
+        expect(batchFn.mock.calls[0][0]).toStrictEqual([[2], [3]]);
+    });
+    test("unbatch", async () => {
+        const fn = vi.fn();
+        const unbatch = vi.fn(
+            (inputs: [number][], output: number): number[] => {
+                // not actual meaningful unbatching
+                return [output / inputs.length, output / inputs.length];
+            },
+        );
+        const execute = batch({
+            fn: (x: number) => {
+                fn(x);
+                return x * 2;
+            },
+            batch: batchFn,
+            unbatch,
+            interval: 100,
+        });
+
+        const result = await execute(1);
+        expect(result).toStrictEqual(2);
+        const promise2 = execute(2);
+        const promise3 = execute(3);
+        vi.advanceTimersByTime(99);
+        expect(fn).toHaveBeenCalledTimes(1);
+        vi.advanceTimersByTime(1);
+        expect(fn).toHaveBeenCalledTimes(2);
+        expect(await promise2).toStrictEqual(5);
+        expect(await promise3).toStrictEqual(5);
+
+        expect(batchFn).toHaveBeenCalledTimes(1);
+        expect(unbatch).toHaveBeenCalledTimes(1);
+        expect(unbatch.mock.calls[0][0]).toStrictEqual([[2], [3]]);
+        expect(unbatch.mock.calls[0][1]).toStrictEqual(10);
+    });
+});

package/src/sync/batch.ts

@@ -1,4 +1,9 @@
-import { makePromise, type AwaitRet } from "./util.ts";
+import {
+    type AnyFn,
+    makePromise,
+    type PromiseHandle,
+    type AwaitRet,
+} from "./util.ts";
 
 /**
  * An async event wrapper that allows multiple calls in an interval
@@ -87,7 +92,7 @@ import { makePromise, type AwaitRet } from "./util.ts";
  * ```
  *
  */
-export function batch<TFn extends (...args: any[]) => any>({
+export function batch<TFn extends AnyFn>({
     fn,
     batch,
     unbatch,
@@ -107,7 +112,7 @@ export function batch<TFn extends (...args: any[]) => any>({
 /**
  * Options to construct a  `batch` function
  */
-export type BatchConstructor<TFn extends (...args: any[]) => any> = {
+export type BatchConstructor<TFn extends AnyFn> = {
     /** Function to be wrapped */
     fn: TFn;
     /** Function to batch the inputs across multiple calls */
@@ -133,14 +138,11 @@ export type BatchConstructor<TFn extends (...args: any[]) => any> = {
     disregardExecutionTime?: boolean;
 };
 
-class BatchImpl<TFn extends (...args: any[]) => any> {
+class BatchImpl<TFn extends AnyFn> {
     private idle: boolean;
-    private scheduled: {
+    private scheduled: (PromiseHandle<AwaitRet<TFn>> & {
         input: Parameters<TFn>;
-        promise: Promise<AwaitRet<TFn>>;
-        resolve: (value: AwaitRet<TFn>) => void;
-        reject: (error: unknown) => void;
-    }[];
+    })[];
 
     constructor(
         private fn: TFn,
@@ -163,7 +165,7 @@ class BatchImpl<TFn extends (...args: any[]) => any> {
             this.idle = false;
             return this.execute(...args);
         }
-        const { promise, reject, resolve } = makePromise<AwaitRet<TFn>>();
+        const { promise, resolve, reject } = makePromise<AwaitRet<TFn>>();
         this.scheduled.push({
             input: args,
             promise,

package/src/sync/debounce.test.ts

@@ -0,0 +1,123 @@
+import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
+
+import { debounce } from "./debounce.ts";
+
+describe("debounce", () => {
+    beforeEach(() => {
+        vi.useFakeTimers();
+    });
+    afterEach(() => {
+        vi.runAllTimers();
+        vi.useRealTimers();
+    });
+    test("initial call executed immediately", async () => {
+        const fn = vi.fn();
+        const execute = debounce({
+            fn: () => {
+                fn();
+                return 42;
+            },
+            interval: 100,
+        });
+        const result = await execute();
+        expect(result).toStrictEqual(42);
+        expect(fn).toHaveBeenCalledTimes(1);
+    });
+    test("debounce call executed after interval", async () => {
+        const fn = vi.fn();
+        const execute = debounce({
+            fn: () => {
+                fn();
+                return 42;
+            },
+            interval: 100,
+        });
+        await execute();
+        expect(fn).toHaveBeenCalledTimes(1);
+        const promise2 = execute();
+        expect(fn).toHaveBeenCalledTimes(1);
+        vi.advanceTimersByTime(99);
+        expect(fn).toHaveBeenCalledTimes(1);
+        vi.advanceTimersByTime(1);
+        expect(fn).toHaveBeenCalledTimes(2);
+        expect(await promise2).toStrictEqual(42);
+    });
+    test("discard extra calls", async () => {
+        const fn = vi.fn();
+        const execute = debounce({
+            fn: () => {
+                fn();
+                return 42;
+            },
+            interval: 100,
+        });
+        await execute();
+        expect(fn).toHaveBeenCalledTimes(1);
+        const promise2 = execute();
+        const promise3 = execute();
+        expect(fn).toHaveBeenCalledTimes(1);
+        vi.advanceTimersByTime(99);
+        expect(fn).toHaveBeenCalledTimes(1);
+        vi.advanceTimersByTime(1);
+        expect(fn).toHaveBeenCalledTimes(2); // not 3
+        expect(await promise2).toStrictEqual(42);
+        expect(await promise3).toStrictEqual(42);
+    });
+    test("function takes long to run", async () => {
+        const fn = vi.fn();
+        const execute = debounce({
+            fn: async (i: string) => {
+                fn(i);
+                await new Promise((resolve) => setTimeout(resolve, 150));
+                return i + "out";
+            },
+            interval: 100,
+        });
+
+        const promise1 = execute("");
+        expect(fn).toHaveBeenCalledTimes(1);
+        const promise2 = execute("2");
+        expect(fn).toHaveBeenCalledTimes(1);
+        vi.advanceTimersByTime(99);
+        expect(fn).toHaveBeenCalledTimes(1);
+        vi.advanceTimersByTime(1);
+        expect(fn).toHaveBeenCalledTimes(1); // 100 - not called yet
+        vi.advanceTimersByTime(149);
+        expect(fn).toHaveBeenCalledTimes(1); // 249 - not called yet
+        vi.advanceTimersByTime(1);
+        // 250 - 1 should be finished
+        expect(await promise1).toStrictEqual("out");
+        expect(fn).toHaveBeenCalledTimes(2);
+        // 2 should be fired now
+        vi.advanceTimersByTime(150);
+        await promise2;
+    });
+    test("function takes long to run, disregardExecutionTime", async () => {
+        const fn = vi.fn();
+        const execute = debounce({
+            fn: async (i: string) => {
+                fn(i);
+                await new Promise((resolve) => setTimeout(resolve, 150));
+                return i + "out";
+            },
+            interval: 100,
+            disregardExecutionTime: true,
+        });
+
+        // 0 - 1 called
+        // 100 - 2 called
+        // 150 - 1 finished
+        // 250 - 2 finished
+        const promise1 = execute("");
+        expect(fn).toHaveBeenCalledTimes(1);
+        const promise2 = execute("2");
+        vi.advanceTimersByTime(99);
+        expect(fn).toHaveBeenCalledTimes(1);
+        vi.advanceTimersByTime(100);
+        expect(fn).toHaveBeenCalledTimes(2);
+        vi.advanceTimersByTime(50);
+        await promise1;
+        vi.advanceTimersByTime(100);
+        await promise2;
+    });
+});

package/src/sync/debounce.ts

@@ -1,4 +1,9 @@
-import { type AwaitRet, makePromise } from "./util.ts";
+import {
+    type AnyFn,
+    type AwaitRet,
+    makePromise,
+    type PromiseHandle,
+} from "./util.ts";
 
 /**
  * An async event wrapper that is guaranteed to:
@@ -78,7 +83,7 @@ import { type AwaitRet, makePromise } from "./util.ts";
  * });
  * ```
  */
-export function debounce<TFn extends (...args: any[]) => any>({
+export function debounce<TFn extends AnyFn>({
     fn,
     interval,
     disregardExecutionTime,
@@ -113,13 +118,10 @@ export type DebounceConstructor<TFn> = {
     disregardExecutionTime?: boolean;
 };
 
-class DebounceImpl<TFn extends (...args: any[]) => any> {
+class DebounceImpl<TFn extends AnyFn> {
     private idle: boolean;
-    private next?: {
+    private next?: PromiseHandle<AwaitRet<TFn>> & {
         args: Parameters<TFn>;
-        promise: Promise<AwaitRet<TFn>>;
-        resolve: (result: AwaitRet<TFn>) => void;
-        reject: (error: any) => void;
     };
     constructor(
         private fn: TFn,

package/src/sync/index.ts

@@ -4,13 +4,21 @@
  *
  * @module
  */
-export { serial, type SerialConstructor } from "./serial.ts";
-export { latest, type LatestConstructor } from "./latest.ts";
+export {
+    serial,
+    type SerialConstructor,
+    type SerialEventCancelCallback,
+    type SerialCancelToken,
+} from "./serial.ts";
+export { latest, type LatestConstructor, type UpdateArgsFn } from "./latest.ts";
 export { debounce, type DebounceConstructor } from "./debounce.ts";
 export { batch, type BatchConstructor } from "./batch.ts";
 export { cell, type CellConstructor, type Cell } from "./cell.ts";
 export { persist, type PersistConstructor, type Persist } from "./persist.ts";
 export { once, type OnceConstructor } from "./once.ts";
 
+// types
+export type { AnyFn, AwaitRet } from "./util.ts";
+
 // unstable
 export { RwLock } from "./RwLock.ts";

package/src/sync/latest.test.ts

@@ -0,0 +1,64 @@
+import { expect, test, describe } from "vitest";
+
+import { latest } from "./latest.ts";
+
+describe("latest", () => {
+    test("returns latest result", async () => {
+        let counter = 0;
+
+        const execute = latest({
+            fn: () => {
+                return ++counter;
+            },
+        });
+
+        const result1 = execute();
+        const result2 = execute();
+        expect(await result1).toStrictEqual(2);
+        expect(await result2).toStrictEqual(2);
+    });
+
+    test("uses are args equal, args are equal", async () => {
+        let counter = 0;
+
+        const execute = latest({
+            fn: async (name: string) => {
+                ++counter;
+                await new Promise((resolve) => setTimeout(resolve, 50));
+                return "hello " + name;
+            },
+
+            areArgsEqual: ([nameA], [nameB]) => nameA === nameB,
+        });
+
+        const result1 = execute("foo");
+        const result2 = execute("foo");
+        // vi.advanceTimersByTime(50);
+        expect(await result1).toStrictEqual("hello foo");
+        expect(await result2).toStrictEqual("hello foo");
+        // should only be called once
+        expect(counter).toEqual(1);
+    });
+
+    // this test doesn't pass with fake timers for some reason
+    test("uses are args equal, args are not equal", async () => {
+        let counter = 0;
+
+        const execute = latest({
+            fn: async (name: string) => {
+                ++counter;
+                await new Promise((resolve) => setTimeout(resolve, 50));
+                return "hello " + name;
+            },
+
+            areArgsEqual: ([nameA], [nameB]) => nameA === nameB,
+        });
+
+        const result1 = execute("foo");
+        const result2 = execute("bar");
+        // returns latest - both resolved at same time
+        expect(await result1).toStrictEqual("hello bar");
+        expect(await result2).toStrictEqual("hello bar");
+        expect(counter).toEqual(2);
+    });
+});

package/src/sync/latest.ts

@@ -1,4 +1,9 @@
-import { makePromise } from "./util.ts";
+import {
+    type AnyFn,
+    type AwaitRet,
+    makePromise,
+    type PromiseHandle,
+} from "./util.ts";
 
 /**
  * An async event wrapper that always resolve to the result of the latest
@@ -26,52 +31,119 @@ import { makePromise } from "./util.ts";
  * console.log(await result1); // 2
  * console.log(await result2); // 2
  * ```
+ *
+ * ## Advanced Usage
+ * 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 (...args: any[]) => any>({
+export function latest<TFn extends AnyFn>({
     fn,
+    areArgsEqual,
+    updateArgs,
 }: LatestConstructor<TFn>) {
-    const impl = new LatestImpl(fn);
+    const impl = new LatestImpl(fn, areArgsEqual, updateArgs);
     return (...args: Parameters<TFn>) => impl.invoke(...args);
 }
 
-export type LatestConstructor<TFn> = {
+export type LatestConstructor<TFn extends AnyFn> = {
     /** Function to be wrapped */
     fn: TFn;
+
+    /**
+     * Optional function to compare if arguments of 2 calls are equal.
+     *
+     * By default, separate calls are considered different, and the result
+     * of the latest call will be returned. However, if the function is pure,
+     * and the argument of a new call is the same as the call being executed,
+     * then the result of the call being executed will be returned. In other words,
+     * the new call will not result in another execution of the function.
+     */
+    areArgsEqual?: (a: Parameters<TFn>, b: Parameters<TFn>) => boolean;
+
+    /**
+     * Optional function to update the arguments.
+     *
+     * By default, when new calls are made while the previous call is being executed,
+     * The function will be executed again with the latest arguments. This function
+     * is used to change this behavior and is called when new calls are made. In other words,
+     * the default value for this function is `(_current, _middle, latest) => latest`.
+     *
+     * The arguments are:
+     * - `current`: The arguments of the call currently being executed
+     * - `latest`: The argument of this new call
+     * - `middle`: If more than one call is made while the previous call is being executed,
+     *   this array contains arguments of the calls between `current` and `latest`
+     * - `next`: This is the returned value of the previous call to updateArgs, i.e. the args
+     *   to be executed next.
+     *
+     */
+    updateArgs?: UpdateArgsFn<TFn>;
 };
-export class LatestImpl<TFn extends (...args: any[]) => any> {
-    private hasNewer: boolean;
-    private pending?: {
-        promise: Promise<Awaited<ReturnType<TFn>>>;
-        resolve: (result: Awaited<ReturnType<TFn>>) => void;
-        reject: (error: unknown) => void;
-    };
+export type UpdateArgsFn<TFn extends AnyFn> = (
+    current: Parameters<TFn>,
+    middle: Parameters<TFn>[],
+    latest: Parameters<TFn>,
+    next: Parameters<TFn> | undefined,
+) => Parameters<TFn>;
+export class LatestImpl<TFn extends AnyFn> {
+    private pending?: PromiseHandle<AwaitRet<TFn>>;
+
+    /** current arguments. undefined means no current call */
+    private currentArgs?: Parameters<TFn>;
+    /** next arguments. undefined means no newer call */
+    private nextArgs?: Parameters<TFn>;
+
+    private middleArgs: Parameters<TFn>[];
 
-    constructor(private fn: TFn) {
-        this.hasNewer = false;
+    private areArgsEqual: (a: Parameters<TFn>, b: Parameters<TFn>) => boolean;
+    private updateArgs: UpdateArgsFn<TFn>;
+
+    constructor(
+        private fn: TFn,
+        areArgsEqual?: (a: Parameters<TFn>, b: Parameters<TFn>) => boolean,
+        updateArgs?: UpdateArgsFn<TFn>,
+    ) {
+        this.middleArgs = [];
+        this.areArgsEqual = areArgsEqual || (() => false);
+        this.updateArgs = updateArgs || ((_current, _middle, latest) => latest);
     }
 
-    public async invoke(
-        ...args: Parameters<TFn>
-    ): Promise<Awaited<ReturnType<TFn>>> {
+    public async invoke(...args: Parameters<TFn>): Promise<AwaitRet<TFn>> {
         if (this.pending) {
-            this.hasNewer = true;
+            // pending means currentArgs is not undefined
+            const currentArgs = this.currentArgs as Parameters<TFn>;
+            const nextArgs = this.updateArgs(
+                currentArgs,
+                this.middleArgs,
+                args,
+                this.nextArgs,
+            );
+            if (this.areArgsEqual(nextArgs, currentArgs)) {
+                // do not schedule new call
+                this.nextArgs = undefined;
+            } else {
+                this.nextArgs = nextArgs;
+            }
             return this.pending.promise;
         }
-        this.pending = makePromise<Awaited<ReturnType<TFn>>>();
+
+        // assign to next args to make the loop cleaner
+        this.nextArgs = args;
+
+        this.pending = makePromise();
         let error = undefined;
         let result;
-        while (true) {
-            this.hasNewer = false;
+        while (this.nextArgs) {
+            this.currentArgs = this.nextArgs;
+            this.nextArgs = undefined;
             try {
                 const fn = this.fn;
-                result = await fn(...args);
+                result = await fn(...this.currentArgs);
             } catch (e) {
                 error = e;
             }
-            if (!this.hasNewer) {
-                break;
-            }
         }
+        this.currentArgs = undefined;
         const pending = this.pending;
         this.pending = undefined;
         if (error) {

package/src/sync/once.test.ts

@@ -0,0 +1,19 @@
+import { expect, test } from "vitest";
+
+import { once } from "./once.ts";
+
+test("once", async () => {
+    let counter = 0;
+
+    const execute = once({
+        fn: async () => {
+            await new Promise((resolve) => setTimeout(resolve, 100));
+            return ++counter;
+        },
+    });
+
+    const result1 = execute();
+    const result2 = execute();
+    expect(await result1).toStrictEqual(1);
+    expect(await result2).toStrictEqual(1);
+});

package/src/sync/once.ts

@@ -1,4 +1,4 @@
-import { makePromise } from "./util";
+import { type AnyFn, type AwaitRet, makePromise } from "./util.ts";
 
 /**
  * An async event wrapper that ensures an async initialization is only ran once.
@@ -66,12 +66,9 @@ import { makePromise } from "./util";
  * 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 (...args: any[]) => any>({
-    fn,
-}: OnceConstructor<TFn>) {
+export function once<TFn extends AnyFn>({ fn }: OnceConstructor<TFn>) {
     const impl = new OnceImpl(fn);
-    return (...args: Parameters<TFn>): Promise<Awaited<ReturnType<TFn>>> =>
-        impl.invoke(...args);
+    return (...args: Parameters<TFn>) => impl.invoke(...args);
 }
 
 export type OnceConstructor<TFn> = {
@@ -79,21 +76,18 @@ export type OnceConstructor<TFn> = {
     fn: TFn;
 };
 
-export class OnceImpl<TFn extends (...args: any[]) => any> {
-    private promise: Promise<Awaited<ReturnType<TFn>>> | undefined;
+export class OnceImpl<TFn extends AnyFn> {
+    private promise: Promise<AwaitRet<TFn>> | undefined;
 
     constructor(private fn: TFn) {
         this.fn = fn;
     }
 
-    public async invoke(
-        ...args: Parameters<TFn>
-    ): Promise<Awaited<ReturnType<TFn>>> {
+    public async invoke(...args: Parameters<TFn>): Promise<AwaitRet<TFn>> {
         if (this.promise) {
             return this.promise;
         }
-        const { promise, resolve, reject } =
-            makePromise<Awaited<ReturnType<TFn>>>();
+        const { promise, resolve, reject } = makePromise<AwaitRet<TFn>>();
         this.promise = promise;
         try {
             const result = await this.fn(...args);

package/src/sync/persist.ts

@@ -88,7 +88,9 @@ class PersistImpl<T> implements Persist<T> {
                     value = loadedValue;
                 }
             }
-        } catch {}
+        } catch {
+            /* ignore */
+        }
         this.cell.set(value);
         this.unsubscribe = this.cell.subscribe((value) => {
             this.storage.setItem(this.key, serialize(value));

package/src/sync/serial.test.ts

@@ -0,0 +1,97 @@
+import { test, expect, expectTypeOf, vi } from "vitest";
+
+import { serial, type SerialCancelToken } from "./serial.ts";
+import type { Result } from "../result/index.ts";
+
+test("example", async () => {
+    // helper function to simulate async work
+    const wait = (ms: number) =>
+        new Promise((resolve) => setTimeout(resolve, ms));
+    // Create the wrapped function
+    const doWork = serial({
+        fn: (checkCancel) => async () => {
+            // this takes 1 seconds to complete
+            for (let i = 0; i < 10; i++) {
+                await wait(1);
+                checkCancel();
+            }
+            return 42;
+        },
+    });
+
+    // The cancellation mechanism uses the Result type
+    // and returns an error when it is cancelled
+    const promise1 = doWork();
+    await wait(3);
+    // calling event.run a second time will cause `shouldCancel` to return false
+    // the next time it's called by the first event
+    const promise2 = doWork();
+
+    expect(await promise1).toStrictEqual({ err: "cancel" });
+    expect(await promise2).toStrictEqual({ val: 42 });
+});
+
+test("passing in arguments", async () => {
+    const execute = serial({
+        fn: (_) => async (arg1: number, arg2: string) => {
+            expect(arg1).toStrictEqual(42);
+            expect(arg2).toStrictEqual("hello");
+        },
+    });
+
+    expectTypeOf(execute).toEqualTypeOf<
+        (arg1: number, arg2: string) => Promise<Result<void, SerialCancelToken>>
+    >();
+
+    await execute(42, "hello"); // no type error!
+});
+
+test("current serial number", async () => {
+    const execute = serial({
+        fn: (_, serial) => () => serial,
+    });
+
+    const one = await execute();
+    expect(one).toStrictEqual({ val: 1n });
+    const two = await execute();
+    expect(two).toStrictEqual({ val: 2n });
+});
+test("no manual cancel check", async () => {
+    const execute = serial({
+        fn: () => async () => {
+            await new Promise((resolve) => setTimeout(resolve, 0));
+            return 42;
+        },
+    });
+    const promise1 = execute();
+    const promise2 = execute();
+    expect(await promise1).toStrictEqual({ err: "cancel" });
+    expect(await promise2).toStrictEqual({ val: 42 });
+});
+
+test("cancel callback", async () => {
+    const onCancel = vi.fn();
+    const execute = serial({
+        fn: (checkCancel) => async () => {
+            await new Promise((resolve) => setTimeout(resolve, 0));
+            checkCancel();
+            return 42;
+        },
+        onCancel,
+    });
+    await Promise.all([execute(), execute()]);
+    expect(onCancel).toHaveBeenCalledTimes(1);
+});
+
+test("cancel callback, no manual check", async () => {
+    const onCancel = vi.fn();
+    const execute = serial({
+        fn: () => async () => {
+            await new Promise((resolve) => setTimeout(resolve, 0));
+            return 42;
+        },
+        onCancel,
+    });
+    await Promise.all([execute(), execute()]);
+    expect(onCancel).toHaveBeenCalledTimes(1);
+});

package/src/sync/serial.ts

@@ -1,4 +1,5 @@
 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.
@@ -132,7 +133,7 @@ import type { Result } from "../result/index.ts";
  * If the underlying function throws, the exception will be re-thrown to the caller.
  */
 
-export function serial<TFn extends (...args: any[]) => any>({
+export function serial<TFn extends AnyFn>({
     fn,
     onCancel,
 }: SerialConstructor<TFn>) {
@@ -156,7 +157,7 @@ export type SerialConstructor<TFn> = {
     onCancel?: SerialEventCancelCallback;
 };
 
-class SerialImpl<TFn extends (...args: any[]) => any> {
+class SerialImpl<TFn extends AnyFn> {
     private serial: SerialId;
     private fn: SerialFnCreator<TFn>;
     private onCancel: SerialEventCancelCallback;

package/src/sync/util.ts

@@ -1,7 +1,7 @@
 export const makePromise = <T>(): {
     promise: Promise<T>;
     resolve: (value: T | PromiseLike<T>) => void;
-    reject: (reason?: any) => void;
+    reject: (reason?: unknown) => void;
 } => {
     let resolve;
     let reject;
@@ -21,7 +21,14 @@ export const makePromise = <T>(): {
     };
 };
 
+export type PromiseHandle<T> = ReturnType<typeof makePromise<T>>;
+
 /** Shorthand for Awaited<ReturnType<T>> */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
 export type AwaitRet<T> = T extends (...args: any[]) => infer R
     ? Awaited<R>
     : never;
+
+/** Type for any function */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type AnyFn = (...args: any[]) => any;