@pistonite/pure 0.0.17 → 0.0.19

package/package.json

@@ -1,35 +1,39 @@
 {
-    "name": "@pistonite/pure",
-    "version": "0.0.17",
-    "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.19",
+  "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": "^2.1.8",
+    "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

@@ -87,6 +87,7 @@ import { makePromise, type AwaitRet } from "./util.ts";
  * ```
  *
  */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
 export function batch<TFn extends (...args: any[]) => any>({
     fn,
     batch,
@@ -107,6 +108,7 @@ export function batch<TFn extends (...args: any[]) => any>({
 /**
  * Options to construct a  `batch` function
  */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
 export type BatchConstructor<TFn extends (...args: any[]) => any> = {
     /** Function to be wrapped */
     fn: TFn;
@@ -133,6 +135,7 @@ export type BatchConstructor<TFn extends (...args: any[]) => any> = {
     disregardExecutionTime?: boolean;
 };
 
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
 class BatchImpl<TFn extends (...args: any[]) => any> {
     private idle: boolean;
     private scheduled: {

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

@@ -78,6 +78,7 @@ import { type AwaitRet, makePromise } from "./util.ts";
  * });
  * ```
  */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
 export function debounce<TFn extends (...args: any[]) => any>({
     fn,
     interval,
@@ -113,13 +114,14 @@ export type DebounceConstructor<TFn> = {
     disregardExecutionTime?: boolean;
 };
 
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
 class DebounceImpl<TFn extends (...args: any[]) => any> {
     private idle: boolean;
     private next?: {
         args: Parameters<TFn>;
         promise: Promise<AwaitRet<TFn>>;
         resolve: (result: AwaitRet<TFn>) => void;
-        reject: (error: any) => void;
+        reject: (error: unknown) => void;
     };
     constructor(
         private fn: TFn,

package/src/sync/index.ts

@@ -10,6 +10,7 @@ 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";
 
 // unstable
 export { RwLock } from "./RwLock.ts";

package/src/sync/latest.test.ts

@@ -0,0 +1,18 @@
+import { expect, test } from "vitest";
+
+import { latest } from "./latest.ts";
+
+test("latest", 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);
+});

package/src/sync/latest.ts

@@ -27,6 +27,7 @@ import { makePromise } from "./util.ts";
  * console.log(await result2); // 2
  * ```
  */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
 export function latest<TFn extends (...args: any[]) => any>({
     fn,
 }: LatestConstructor<TFn>) {
@@ -38,6 +39,7 @@ export type LatestConstructor<TFn> = {
     /** Function to be wrapped */
     fn: TFn;
 };
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
 export class LatestImpl<TFn extends (...args: any[]) => any> {
     private hasNewer: boolean;
     private pending?: {

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

@@ -0,0 +1,109 @@
+import { makePromise } from "./util";
+
+/**
+ * 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.
+ *
+ * ## Example
+ * ```typescript
+ * import { once } from "@pistonite/pure/sync";
+ *
+ * const getLuckyNumber = once({
+ *     fn: async () => {
+ *          console.log("running expensive initialization...")
+ *          await new Promise((resolve) => setTimeout(resolve, 100));
+ *          console.log("done")
+ *          return 42;
+ *     }
+ * });
+ *
+ * const result1 = getLuckyNumber();
+ * const result2 = getLuckyNumber();
+ * console.log(await result1);
+ * console.log(await result2);
+ * // logs:
+ * // running expensive initialization...
+ * // done
+ * // 42
+ * // 42
+ * ```
+ *
+ * ## Caveat with HMR
+ * Some initialization might require clean up, such as unregister
+ * event handlers and/or timers. In this case, a production build might
+ * work fine but a HMR (Hot Module Reload) development server might not
+ * do this for you automatically.
+ *
+ * One way to work around this during development is to store the cleanup
+ * as a global object
+ * ```typescript
+ * const getResourceThatNeedsCleanup = once({
+ *     fn: async () => {
+ *         if (__DEV__) { // Configure your bundler to inject this
+ *             // await if you need async clean up
+ *             await (window as any).cleanupMyResource?.();
+ *         }
+ *
+ *         let resource: MyResource;
+ *         if (__DEV__) {
+ *             (window as any).cleanupMyResource = async () => {
+ *                 await resource?.cleanup();
+ *             };
+ *         }
+ *
+ *         resource = await initResource();
+ *         return resource;
+ *     }
+ * });
+ * ```
+ *
+ * An alternative solution is to not use `once` but instead tie the initialization
+ * of the resource to some other lifecycle event that gets cleaned up during HMR.
+ * For example, A framework that supports HMR for React components might unmount
+ * the component before reloading, which gives you a chance to clean up the resource.
+ *
+ * This is not an issue if the resource doesn't leak other resources,
+ * since it will eventually be GC'd.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function once<TFn extends (...args: any[]) => any>({
+    fn,
+}: OnceConstructor<TFn>) {
+    const impl = new OnceImpl(fn);
+    return (...args: Parameters<TFn>): Promise<Awaited<ReturnType<TFn>>> =>
+        impl.invoke(...args);
+}
+
+export type OnceConstructor<TFn> = {
+    /** Function to be called only once */
+    fn: TFn;
+};
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export class OnceImpl<TFn extends (...args: any[]) => any> {
+    private promise: Promise<Awaited<ReturnType<TFn>>> | undefined;
+
+    constructor(private fn: TFn) {
+        this.fn = fn;
+    }
+
+    public async invoke(
+        ...args: Parameters<TFn>
+    ): Promise<Awaited<ReturnType<TFn>>> {
+        if (this.promise) {
+            return this.promise;
+        }
+        const { promise, resolve, reject } =
+            makePromise<Awaited<ReturnType<TFn>>>();
+        this.promise = promise;
+        try {
+            const result = await this.fn(...args);
+            resolve(result);
+            return result;
+        } catch (e) {
+            reject(e);
+            throw e;
+        }
+    }
+}

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

@@ -132,6 +132,7 @@ import type { Result } from "../result/index.ts";
  * If the underlying function throws, the exception will be re-thrown to the caller.
  */
 
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
 export function serial<TFn extends (...args: any[]) => any>({
     fn,
     onCancel,
@@ -156,6 +157,7 @@ export type SerialConstructor<TFn> = {
     onCancel?: SerialEventCancelCallback;
 };
 
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
 class SerialImpl<TFn extends (...args: any[]) => any> {
     private serial: SerialId;
     private fn: SerialFnCreator<TFn>;

package/src/sync/util.ts

@@ -1,4 +1,8 @@
-export const makePromise = <T>() => {
+export const makePromise = <T>(): {
+    promise: Promise<T>;
+    resolve: (value: T | PromiseLike<T>) => void;
+    reject: (reason?: unknown) => void;
+} => {
     let resolve;
     let reject;
     const promise = new Promise<T>((res, rej) => {
@@ -18,6 +22,7 @@ export const 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;