@pistonite/pure 0.0.19 → 0.21.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pistonite/pure",
-  "version": "0.0.19",
+  "version": "0.21.0",
   "type": "module",
   "description": "Pure TypeScript libraries for my projects",
   "homepage": "https://github.com/Pistonite/pure",
@@ -33,7 +33,7 @@
     "@types/file-saver": "^2.0.7",
     "eslint": "^9.19.0",
     "typescript": "^5.7.2",
-    "vitest": "^2.1.8",
+    "vitest": "^3.0.5",
     "mono-dev": "0.0.0"
   }
 }

package/src/memory/index.ts

@@ -0,0 +1,8 @@
+/**
+ * # pure/memory
+ * JS memory utilities
+ *
+ * @module
+ */
+export { cell, type CellConstructor, type Cell } from "./cell.ts";
+export { persist, type PersistConstructor, type Persist } from "./persist.ts";

package/src/memory/weak.ts

@@ -0,0 +1,139 @@
+export type ExternalWeakRef<TUnderlying, TType> = {
+    /**
+     * A marker value for the underlying object type.
+     *
+     * This is commonly a string literal or a symbol.
+     */
+    type: TType;
+
+    /**
+     * The underlying object reference.
+     */
+    ref: TUnderlying | undefined;
+
+    /**
+     * Free the underlying object.
+     */
+    free: () => void;
+
+    /**
+     * Update the underlying object reference.
+     *
+     * If the new reference is the same as the old one, nothing will happen.
+     * If the old reference is not undefined, it will be freed.
+     */
+    set: (value: TUnderlying | undefined) => void;
+};
+
+export type ExternalWeakRefConstructor<TUnderlying, TType> = {
+    /**
+     * A marker value for the underlying object type.
+     *
+     * This is commonly a string literal or a symbol.
+     */
+    marker: TType;
+
+    /**
+     * The function to free the underlying object.
+     */
+    free: (obj: TUnderlying) => void;
+};
+
+/**
+ * Create a weak reference type for managing externally memory-managed object. This means
+ * the objects needs to be freed manually by the external code.
+ *
+ * The `marker` option is used to distinguish between different types of weak references
+ * with the same underlying representation for the reference.
+ *
+ * Note that the underlying representation should not be undefined-able!
+ *
+ * ## Example
+ * ```typescript
+ * import { makeExternalWeakRefType } from "@pistonite/pure/memory";
+ *
+ * // assume `number` is the JS type used to represent the external object
+ * // for example, this can be a pointer to a C++ object
+ * declare function freeFoo(obj: number) => void;
+ *
+ * // some function that allocates a foo object externally and returns
+ * // a reference
+ * declare function getFoo(): number;
+ *
+ * const makeFooRef = makeExternalWeakRefType({
+ *     marker: "foo",
+ *     free: (obj) => {
+ *         freeFoo(obj);
+ *     }
+ * });
+ * type FooRef = ReturnType<typeof makeFooRef>;
+ *
+ * // create a reference to a foo object
+ * // now this reference can be passed around in JS,
+ * // as long as the ownership model is clear and the owner
+ * // remembers to free it
+ * const fooRef = makeFooRef(getFoo());
+ *
+ * // free the foo object when it is no longer needed
+ * fooRef.free();
+ *
+ * ## Updating the reference
+ * The `set` method will update the reference and free the old one if exists
+ * ```
+ * const fooRef = makeFooRef(getFoo());
+ * fooRef.set(getFoo()); // the old one will be freed, unless it is the same as the new one
+ * ```
+ *
+ * This has a major pitfall: If the ExternalWeakRef is shared, the new object will be accessible
+ * by code that has the old reference. In other words, when the reference is updated, code that
+ * already has the old reference will not able to know that it has changed.
+ *
+ * If this is a problem, you should use this pattern instead:
+ * ```typescript
+ * // track the "current" valid reference
+ * let currentRef = makeFooRef(undefined);
+ *
+ * export const getFooRef = (): FooRef => {
+ *     // because of this function, many other places can hold
+ *     // a valid reference to foo
+ *     return currentRef;
+ * }
+ *
+ * export const updateFooRef = (newFoo: number): void => {
+ *     // when updating the reference, we create a new weak ref and free the old one
+ *     if (currentRef.ref === newFoo) {
+ *         return; // always need to check if old and new are the same, otherwise we will be freeing the new one
+ *     }
+ *     const newRef = makeFooRef(newFoo);
+ *     currentRef.free();
+ *     currentRef = newRef;
+ *
+ *     // now other places that hold the old reference will see it's freed
+ * }
+ * ```
+ */
+export const makeExternalWeakRefType = <TUnderlying, TType>({
+    marker,
+    free,
+}: ExternalWeakRefConstructor<TUnderlying, TType>) => {
+    return (
+        obj: TUnderlying | undefined,
+    ): ExternalWeakRef<TUnderlying, TType> => {
+        const weakRefObj = {
+            type: marker,
+            ref: obj,
+            free: () => {
+                if (weakRefObj.ref !== undefined) {
+                    free(weakRefObj.ref);
+                }
+            },
+            set: (value: TUnderlying | undefined) => {
+                if (weakRefObj.ref !== undefined && weakRefObj.ref !== value) {
+                    free(weakRefObj.ref);
+                }
+                weakRefObj.ref = value;
+            },
+        };
+        return weakRefObj;
+    };
+};

package/src/pref/dark.ts

@@ -1,4 +1,4 @@
-import { persist } from "../sync/persist.ts";
+import { persist } from "../memory/persist.ts";
 import { injectStyle } from "./injectStyle.ts";
 
 const dark = persist({

package/src/pref/locale.ts

@@ -1,4 +1,4 @@
-import { persist } from "../sync/persist.ts";
+import { persist } from "../memory/persist.ts";
 
 let supportedLocales: readonly string[] = [];
 let defaultLocale: string = "";

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,8 +92,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>({
+export function batch<TFn extends AnyFn>({
     fn,
     batch,
     unbatch,
@@ -108,8 +112,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> = {
+export type BatchConstructor<TFn extends AnyFn> = {
     /** Function to be wrapped */
     fn: TFn;
     /** Function to batch the inputs across multiple calls */
@@ -135,15 +138,11 @@ 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> {
+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,
@@ -166,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.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,8 +83,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>({
+export function debounce<TFn extends AnyFn>({
     fn,
     interval,
     disregardExecutionTime,
@@ -114,14 +118,10 @@ export type DebounceConstructor<TFn> = {
     disregardExecutionTime?: boolean;
 };
 
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-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: unknown) => void;
     };
     constructor(
         private fn: TFn,

package/src/sync/index.ts

@@ -4,13 +4,19 @@
  *
  * @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

@@ -1,18 +1,64 @@
-import { expect, test } from "vitest";
+import { expect, test, describe } from "vitest";
 
 import { latest } from "./latest.ts";
 
-test("latest", async () => {
-    let counter = 0;
+describe("latest", () => {
+    test("returns latest result", async () => {
+        let counter = 0;
 
-    const execute = latest({
-        fn: () => {
-            return ++counter;
-        },
+        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);
     });
 
-    const result1 = execute();
-    const result2 = execute();
-    expect(await result1).toStrictEqual(2);
-    expect(await result2).toStrictEqual(2);
+    // 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,54 +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.
  */
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-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>;
 };
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-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.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,13 +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.
  */
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-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> = {
@@ -80,22 +76,18 @@ export type OnceConstructor<TFn> = {
     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;
+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/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,8 +133,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>({
+export function serial<TFn extends AnyFn>({
     fn,
     onCancel,
 }: SerialConstructor<TFn>) {
@@ -157,8 +157,7 @@ export type SerialConstructor<TFn> = {
     onCancel?: SerialEventCancelCallback;
 };
 
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-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

@@ -21,8 +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;