@pistonite/pure 0.0.13 → 0.0.14

package/src/sync/debounce.ts

@@ -0,0 +1,179 @@
+import { type AwaitRet, makePromise } from "./util.ts";
+
+/**
+ * An async event wrapper that is guaranteed to:
+ * - Not re-fire in a minimal interval after it's initialially fired.
+ * - All calls will eventually fire
+ *
+ * The caller will get a promise that resolves the next time the event is fired
+ * and resolved.
+ *
+ * Unlike the naive implementation with a setTimeout, this implementation
+ * will not starve the event. If it's constantly being called,
+ * it will keep firing the event at at least the minimum interval (might
+ * take longer if the underlying function takes longer to execute
+ *
+ * ## Simple Example
+ *
+ * Multiple calls will be debounced to the minimum interval
+ * ```typescript
+ * import { debounce } from "@pistonite/pure/sync";
+ *
+ * const execute = debounce({
+ *     fn: () => {
+ *         console.log("called");
+ *     }
+ *     interval: 100,
+ * });
+ * await execute(); // resolved immediately
+ * await execute(); // resolved after 100ms
+ * ```
+ *
+ * ## Discarding extra calls
+ * When making multiple calls, if the call is currently being debounced
+ * (i.e. executed and the minimum interval hasn't passed), new calls
+ * will replace the previous call.
+ *
+ * If you want to the in-between calls to be preserved,
+ * use `batch` instead.
+ *
+ * ```typescript
+ * import { debounce } from "@pistonite/pure/sync";
+ *
+ * const execute = debounce({
+ *     fn: (n: number) => {
+ *         console.log(n);
+ *     }
+ *     interval: 100,
+ * });
+ * await execute(1); // logs 1 immediately
+ * const p1 = execute(2); // will be resolved at 100ms
+ * await new Promise((resolve) => setTimeout(resolve, 50));
+ * await Promise.all[p1, execute(3)]; // will be resolved at 100ms, discarding the 2nd call
+ * // 1, 3 will be logged
+ * ```
+ *
+ * ## Slow function
+ * By default, the debouncer takes into account the time
+ * it takes for the underlying function to execute. It starts
+ * the next cycle as soon as both the minimul interval has passed
+ * and the function has finished executing. This ensures only
+ * 1 call is being executed at a time.
+ *
+ * However, if you want the debouncer to always debounce at the set interval,
+ * regardless of if the previous call has finished, set `disregardExecutionTime`
+ * to true.
+ *
+ * ```typescript
+ * import { debounce } from "@pistonite/pure/sync";
+ *
+ * const execute = debounce({
+ *     fn: async (n: number) => {
+ *         await new Promise((resolve) => setTimeout(resolve, 150));
+ *         console.log(n);
+ *     },
+ *     interval: 100,
+ *     // without this, will debounce at the interval of 150ms
+ *     disregardExecutionTime: true,
+ * });
+ * ```
+ */
+export function debounce<TFn extends (...args: any[]) => any>({
+    fn,
+    interval,
+    disregardExecutionTime,
+}: DebounceConstructor<TFn>) {
+    const impl = new DebounceImpl(fn, interval, !!disregardExecutionTime);
+    return (...args: Parameters<TFn>) => impl.invoke(...args);
+}
+
+/**
+ * Options for `debounce` function
+ */
+export type DebounceConstructor<TFn> = {
+    /** Function to be debounced */
+    fn: TFn;
+    /**
+     * Minimum interval between each call
+     *
+     * Setting this to <= 0 will make the debounce function
+     * a pure pass-through, not actually debouncing the function
+     */
+    interval: number;
+
+    /**
+     * By default, the debouncer takes in account the time
+     * the underlying function executes. i.e. the actual debounce
+     * interval is `max(interval, executionTime)`. This default
+     * behavior guanrantees that no 2 calls will be executed concurrently.
+     *
+     * If you want the debouncer to always debounce at the set interval,
+     * set this to true.
+     */
+    disregardExecutionTime?: boolean;
+};
+
+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;
+    };
+    constructor(
+        private fn: TFn,
+        private interval: number,
+        private disregardExecutionTime: boolean,
+    ) {
+        this.idle = true;
+    }
+
+    public invoke(...args: Parameters<TFn>): Promise<AwaitRet<TFn>> {
+        if (this.idle) {
+            this.idle = false;
+            return this.execute(...args);
+        }
+        if (!this.next) {
+            this.next = { args, ...makePromise<AwaitRet<TFn>>() };
+        } else {
+            this.next.args = args;
+        }
+        return this.next.promise;
+    }
+
+    private scheduleNext() {
+        const next = this.next;
+        if (next) {
+            this.next = undefined;
+            const { args, resolve, reject } = next;
+            void this.execute(...args).then(resolve, reject);
+            return;
+        }
+        this.idle = true;
+    }
+
+    private async execute(...args: Parameters<TFn>): Promise<AwaitRet<TFn>> {
+        const fn = this.fn;
+        let done = this.disregardExecutionTime;
+        setTimeout(() => {
+            if (done) {
+                this.scheduleNext();
+            } else {
+                done = true;
+            }
+        }, this.interval);
+        try {
+            return await fn(...args);
+        } finally {
+            if (!this.disregardExecutionTime) {
+                if (done) {
+                    // interval already passed, we need to call it
+                    this.scheduleNext();
+                } else {
+                    done = true;
+                }
+            }
+        }
+    }
+}

package/src/sync/index.ts

@@ -4,9 +4,12 @@
  *
  * @module
  */
-export { RwLock } from "./RwLock.ts";
-export { Serial } from "./Serial.ts";
+export { serial, type SerialConstructor } from "./serial.ts";
+export { latest, type LatestConstructor } 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";
 
 // unstable
-export { Latest } from "./Latest.ts";
-export { Debounce } from "./Debounce.ts";
+export { RwLock } from "./RwLock.ts";

package/src/sync/latest.ts

@@ -0,0 +1,85 @@
+import { makePromise } from "./util.ts";
+
+/**
+ * An async event wrapper that always resolve to the result of the latest
+ * call
+ *
+ * ## Example
+ * In the example below, both call will return the result
+ * of the second call (2)
+ * ```typescript
+ * import { latest } from "@pistonite/pure/sync";
+ *
+ * let counter = 0;
+ *
+ * const execute = latest({
+ *     fn: async () => {
+ *         counter++;
+ *         await new Promise((resolve) => setTimeout(() => {
+ *             resolve(counter);
+ *         }, 1000));
+ *     }
+ * });
+ *
+ * const result1 = execute();
+ * const result2 = execute();
+ * console.log(await result1); // 2
+ * console.log(await result2); // 2
+ * ```
+ */
+export function latest<TFn extends (...args: any[]) => any>({
+    fn,
+}: LatestConstructor<TFn>) {
+    const impl = new LatestImpl(fn);
+    return (...args: Parameters<TFn>) => impl.invoke(...args);
+}
+
+export type LatestConstructor<TFn> = {
+    /** Function to be wrapped */
+    fn: 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;
+    };
+
+    constructor(private fn: TFn) {
+        this.hasNewer = false;
+    }
+
+    public async invoke(
+        ...args: Parameters<TFn>
+    ): Promise<Awaited<ReturnType<TFn>>> {
+        if (this.pending) {
+            this.hasNewer = true;
+            return this.pending.promise;
+        }
+        this.pending = makePromise<Awaited<ReturnType<TFn>>>();
+        let error = undefined;
+        let result;
+        while (true) {
+            this.hasNewer = false;
+            try {
+                const fn = this.fn;
+                result = await fn(...args);
+            } catch (e) {
+                error = e;
+            }
+            if (!this.hasNewer) {
+                break;
+            }
+        }
+        const pending = this.pending;
+        this.pending = undefined;
+        if (error) {
+            pending.reject(error);
+            throw error;
+        } else {
+            pending.resolve(result);
+            return result;
+        }
+    }
+}

package/src/sync/persist.ts

@@ -0,0 +1,122 @@
+import { cell, type Cell, type CellConstructor } from "./cell.ts";
+
+/**
+ * Create a cell that persists its value to a web storage
+ */
+export function persist<T>({
+    storage,
+    key,
+    serialize = JSON.stringify,
+    deserialize,
+    initial,
+}: PersistConstructor<T>): Persist<T> {
+    const deser =
+        deserialize ??
+        ((value: string) => {
+            try {
+                return JSON.parse(value);
+            } catch {
+                return null;
+            }
+        });
+    return new PersistImpl(storage, key, serialize, deser, initial);
+}
+
+export type PersistConstructor<T> = CellConstructor<T> & {
+    /** The web storage to use */
+    storage: Storage;
+
+    /** The key to use in the storage */
+    key: string;
+
+    /**
+     * Serialize the value to store in the storage
+     *
+     * By default, it will use `JSON.stringify`
+     */
+    serialize?(value: T): string;
+    /**
+     * Deserialize the value from the storage
+     *
+     * By default, it will use `JSON.parse` wrapped with try-catch
+     */
+    deserialize?(value: string): T | null;
+};
+
+export type Persist<T> = Cell<T> & {
+    /**
+     * Load the value initially, and notify all the current subscribers
+     *
+     * Optionally, you can pass an initial value to override the current value
+     */
+    init(initial?: T): T;
+    /** Clear the value from the storage */
+    clear(): void;
+    /** Clera the value and disable the persistence */
+    disable(): void;
+};
+
+class PersistImpl<T> implements Persist<T> {
+    private cell: Cell<T>;
+    private unsubscribe: () => void;
+
+    constructor(
+        private storage: Storage,
+        private key: string,
+        private serialize: (value: T) => string,
+        private deserialize: (value: string) => T | null,
+        initial: T,
+    ) {
+        this.cell = cell({ initial });
+        this.unsubscribe = () => {};
+    }
+
+    public init(initial?: T): T {
+        const serialize = this.serialize;
+        const deserialize = this.deserialize;
+        let value: T;
+        if (initial !== undefined) {
+            value = initial;
+        } else {
+            value = this.cell.get();
+        }
+        try {
+            const data = this.storage.getItem(this.key);
+            if (data !== null) {
+                const loadedValue = deserialize(data);
+                if (loadedValue !== null) {
+                    value = loadedValue;
+                    this.cell.set(value);
+                }
+            }
+        } catch {}
+        this.unsubscribe = this.cell.subscribe((value) => {
+            this.storage.setItem(this.key, serialize(value));
+        });
+        return value;
+    }
+
+    public get(): T {
+        return this.cell.get();
+    }
+
+    public set(value: T): void {
+        this.cell.set(value);
+    }
+
+    public subscribe(
+        callback: (value: T) => void,
+        notifyImmediately?: boolean,
+    ): () => void {
+        return this.cell.subscribe(callback, notifyImmediately);
+    }
+
+    public clear() {
+        this.storage.removeItem(this.key);
+    }
+
+    public disable() {
+        this.clear();
+        this.unsubscribe();
+    }
+}

package/src/sync/serial.ts

@@ -0,0 +1,220 @@
+import type { Result } from "../result/index.ts";
+
+/**
+ * An async event wrapper that is cancelled when a new one starts.
+ * When a new event is started, the previous caller will receive a
+ * cancellation error, instead of being hung up indefinitely.
+ *
+ * If you want every caller to receive the latest result
+ * instead of a cancellation error, use `latest` instead.
+ *
+ * ## Example
+ *
+ * ```typescript
+ * import { serial } from "@pistonite/pure/sync";
+ *
+ * // helper function to simulate async work
+ * const wait = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
+ *
+ * // Create the wrapped function
+ * const execute = serial({
+ *     // This has to be curried for type inferrence
+ *     fn: (checkCancel) => async () => {
+ *         for (let i = 0; i < 10; i++) {
+ *             await wait(1000);
+ *             // The cancellation mechanism throws an error if is cancelled
+ *             checkCancel();
+ *         }
+ *         return 42;
+ *     }
+ * });
+ *
+ * // execute it the first time
+ * const promise1 = execute();
+ * await wait(3000);
+ *
+ * // calling event.run a second time will cause `checkCancel` to return false
+ * // the next time it's called by the first event
+ * const promise2 = execute();
+ *
+ * console.log(await promise1); // { err: "cancel" }
+ * console.log(await promise2); // { val: 42 }
+ * ```
+ *
+ * ## Passing in arguments
+ * TypeScript magic is used to ensure full type-safety when passing in arguments.
+ *
+ * ```typescript
+ * import { serial, type SerialCancelToken } from "@pistonite/pure/sync";
+ * import type { Result } from "@pistonite/pure/result";
+ *
+ * const execute = serial({
+ *    fn: (checkCancel) => async (arg1: number, arg2: string) => {
+ *
+ *        // do something with arg1 and arg2
+ *        console.log(arg1, arg2);
+ *
+ *        // ...
+ *    }
+ * });
+ *
+ * expectTypeOf(execute)
+ *     .toEqualTypeOf<
+ *         (arg1: number, arg2: string) => Promise<Result<void, SerialCancelToken>>
+ *      >();
+ *
+ * await execute(42, "hello"); // no type error!
+ * ```
+ *
+ * ## Getting the current serial number
+ * The serial number has type `bigint` and is incremented every time `run` is called.
+ *
+ * You can have an extra argument after `checkCancel`, that will receive the current serial number,
+ * if you need it for some reason.
+ * ```typescript
+ * import { serial } from "@pistonite/pure/sync";
+ *
+ * const execute = serial({
+ *     fn: (checkCancel, serial) => () => { console.log(serial); }
+ * });
+ *
+ * await execute(); // 1n
+ * await execute(); // 2n
+ * ```
+ *
+ * ## Checking for cancel
+ * It's the event handler's responsibility to check if the event is cancelled by
+ * calling the `checkCancel` function. This function will throw if the event
+ * is cancelled, and the error will be caught by the wrapper and returned as an `Err`
+ *
+ * Note that even if you don't check it, there is one final check before the result is returned.
+ * So you will never get a result from a cancelled event. Also note that you only need to check
+ * after any `await` calls. If there's no `await`, everything is executed synchronously,
+ * and it's theoretically impossible to cancel the event. However, this depends on
+ * the runtime's implementation of promises.
+ *
+ * ## Handling cancelled event
+ * To check if an event is completed or cancelled, simply `await`
+ * on the promise check the `err`
+ * ```typescript
+ * import { serial } from "@pistonite/pure/sync";
+ *
+ * const execute = serial({
+ *     fn: (checkCancel) => async () => {
+ *         // your code here ...
+ *     }
+ * });
+ * const result = await execute();
+ * if (result.err === "cancel") {
+ *     console.log("event was cancelled");
+ * } else {
+ *     console.log("event completed");
+ * }
+ * ```
+ *
+ * You can also pass in a callback to the constructor, which will be called
+ * when the event is cancelled. The cancel callback is guaranteed to only fire at most once per run
+ * ```typescript
+ * import { serial } from "@pistonite/pure/sync";
+ *
+ * const onCancel = (current: bigint, latest: bigint) => {
+ *     console.log(`Event with serial ${current} is cancelled because the latest serial is ${latest}`);
+ * };
+ *
+ * const execute = new Serial({
+ *     fn: ...,
+ *     onCancel,
+ * });
+ * ```
+ *
+ * ## Exception handling
+ *
+ * If the underlying function throws, the exception will be re-thrown to the caller.
+ */
+
+export function serial<TFn extends (...args: any[]) => any>({
+    fn,
+    onCancel,
+}: SerialConstructor<TFn>) {
+    const impl = new SerialImpl(fn, onCancel);
+    return (...args: Parameters<TFn>) => impl.invoke(...args);
+}
+
+/**
+ * Options for `serial` function
+ */
+export type SerialConstructor<TFn> = {
+    /**
+     * Function creator that returns the async function to be wrapped
+     */
+    fn: (checkCancel: CheckCancelFn, current: SerialId) => TFn;
+    /**
+     * Optional callback to be called when the event is cancelled
+     *
+     * This is guaranteed to be only called at most once per execution
+     */
+    onCancel?: SerialEventCancelCallback;
+};
+
+class SerialImpl<TFn extends (...args: any[]) => any> {
+    private serial: SerialId;
+    private fn: SerialFnCreator<TFn>;
+    private onCancel: SerialEventCancelCallback;
+
+    constructor(
+        fn: SerialFnCreator<TFn>,
+        onCancel?: SerialEventCancelCallback,
+    ) {
+        this.fn = fn;
+        this.serial = 0n;
+        if (onCancel) {
+            this.onCancel = onCancel;
+        } else {
+            this.onCancel = () => {};
+        }
+    }
+
+    public async invoke(
+        ...args: Parameters<TFn>
+    ): Promise<Result<Awaited<ReturnType<TFn>>, SerialCancelToken>> {
+        let cancelled = false;
+        const currentSerial = ++this.serial;
+        const checkCancel = () => {
+            if (currentSerial !== this.serial) {
+                if (!cancelled) {
+                    cancelled = true;
+                    this.onCancel(currentSerial, this.serial);
+                }
+                throw new Error("cancelled");
+            }
+        };
+        const fn = this.fn;
+        // note: no typechecking for "result"
+        try {
+            const result = await fn(checkCancel, currentSerial)(...args);
+            checkCancel();
+            return { val: result };
+        } catch (e) {
+            if (currentSerial !== this.serial) {
+                return { err: "cancel" };
+            }
+            throw e;
+        }
+    }
+}
+
+type SerialId = bigint;
+type CheckCancelFn = () => void;
+type SerialFnCreator<T> = (checkCancel: CheckCancelFn, serial: SerialId) => T;
+
+/**
+ * The callback type passed to SerialEvent constructor to be called
+ * when the event is cancelled
+ */
+export type SerialEventCancelCallback = (
+    current: SerialId,
+    latest: SerialId,
+) => void;
+
+/** The error type received by caller when an event is cancelled */
+export type SerialCancelToken = "cancel";

package/src/sync/util.ts

@@ -0,0 +1,23 @@
+export const makePromise = <T>() => {
+    let resolve;
+    let reject;
+    const promise = new Promise<T>((res, rej) => {
+        resolve = res;
+        reject = rej;
+    });
+    if (!resolve || !reject) {
+        throw new Error(
+            "Promise callbacks not set. This is a bug in the JS engine!",
+        );
+    }
+    return {
+        promise,
+        resolve,
+        reject,
+    };
+};
+
+/** Shorthand for Awaited<ReturnType<T>> */
+export type AwaitRet<T> = T extends (...args: any[]) => infer R
+    ? Awaited<R>
+    : never;

package/src/sync/Debounce.ts

@@ -1,35 +0,0 @@
-/**
- * Debounce executes an action after a certain delay. Any
- * call to the action during this delay resets the timer.
- *
- * ## Warning
- * The implementation is naive and does not handle the case
- * where the action keeps getting called before the delay,
- * in which case the action will never be executed. This
- * will be improved in the future...
- */
-export class Debounce<TResult> {
-    private timer: number | undefined;
-    constructor(
-        private fn: () => Promise<TResult>,
-        private delay: number,
-    ) {
-        this.timer = undefined;
-    }
-
-    public execute(): Promise<TResult> {
-        if (this.timer !== undefined) {
-            clearTimeout(this.timer);
-        }
-        return new Promise<TResult>((resolve, reject) => {
-            this.timer = setTimeout(async () => {
-                this.timer = undefined;
-                try {
-                    resolve(await this.fn());
-                } catch (error) {
-                    reject(error);
-                }
-            }, this.delay);
-        });
-    }
-}