@pistonite/pure 0.0.12

package/src/result/index.ts

@@ -0,0 +1,215 @@
+/**
+ * **I once had a fancy error object with TypeScript magic that tries
+ * to reduce allocation while maintaining Result-safety. It turns out
+ * that was slower than allocating plain objects for every return, because
+ * of how V8 optimizes things.**
+ *
+ * Don't even use `isErr()` helper functions to abstract. They are slower than
+ * directly property access in my testing.
+ *
+ * ## Function that can fail
+ * Instead of having functions `throw`, make it `return` instead.
+ * ```typescript
+ * // Instead of
+ * function doSomethingCanFail() {
+ *     if (Math.random() < 0.5) {
+ *         return 42;
+ *     }
+ *     throw "oops";
+ * }
+ * // Do this
+ * import type { Result } from "pure/result";
+ *
+ * function doSomethingCanFail(): Result<number, string> {
+ *     if (Math.random() < 0.5) {
+ *         return { val: 42 };
+ *     }
+ *     return { err: "oops" };
+ * }
+ * ```
+ * This is similar to Rust:
+ * ```rust
+ * fn do_something_can_fail() -> Result<u32, String> {
+ *     if ... {
+ *         return Ok(42);
+ *     }
+ *
+ *     Err("oops".to_string())
+ * }
+ * ```
+ *
+ * ## Calling function that can fail
+ * The recommended pattern is
+ * ```typescript
+ * const x = doTheCall(); // x is Result<T, E>;
+ * if (x.err) {
+ *     // x.err is E, handle it
+ *     return ...
+ * }
+ * // x.val is T
+ * // ...
+ * ```
+ * If your `E` type covers falsy values that are valid, use `"err" in x` instead of `x.err`.
+ * A well-known case is `Result<T, unknown>`. `if(r.err)` cannot narrow the else case to `Ok`,
+ * but `if("err" in r)` can.
+ *
+ * A full example:
+ * ```typescript
+ * function getParam(name: string): Result<number, Error> {
+ *     if (name === "a") {
+ *         return { val: 13 };
+ *     }
+ *     if (name === "b") {
+ *         return { val: 42 };
+ *     }
+ *     return { err: new Error("bad name") };
+ * }
+ *
+ * function multiplyFormat(
+ *     name1: string,
+ *     name2: string,
+ *     prefix: string
+ * ): Result<string, Error> {
+ *     const v1 = getParam(name1);
+ *     if (v1.err) {
+ *         console.error(v1.err);
+ *         return v1;
+ *     }
+ *     const v2 = getParam(name1);
+ *     if (v2.err) {
+ *         console.error(v2.err);
+ *         return v2;
+ *     }
+ *
+ *     const formatted = `${prefix}${v1.val * v2.val}`;
+ *     return { val: formatted };
+ * }
+ * ```
+ *
+ * ## Interop with throwing functions
+ * This library also has `tryCatch` to interop with throwing functions,
+ * and `tryAsync` for async functions.
+ *
+ * ```typescript
+ * import { tryCatch, tryAsync } from "pure/result";
+ *
+ * // synchronous
+ * const result1: Result<MyData, unknown> = tryCatch(() => JSON.parse<MyData>(...));
+ * // or you can specify the error type:
+ * const result2 = tryCatch<MyData, SyntaxError>(() => JSON.parse(...));
+ *
+ * // asynchronous
+ * async function doSomethingCanFail() {
+ *     if (Math.random() < 0.5) {
+ *         return 42;
+ *     }
+ *     throw "oops";
+ * }
+ * const result = await tryAsync<number, string>(() => doStuff);
+ * ```
+ *
+ * ## Returning void
+ * Use `Void<E>` as the return type if the function returns `void` on success
+ * ```typescript
+ * const x = doSomethingThatVoidsOnSuccess();
+ * if (x.err) {
+ *     return x;
+ * }
+ * // type of x is Record<string, never>, i.e. empty object
+ * ```
+ *
+ * ## Why is there no `match`/`map`/`mapErr`, etc?
+ *
+ * If you are thinking this is a great idea:
+ * ```typescript
+ * const result = foo(bar);
+ * match(result,
+ *     (okValue) => {
+ *         // handle ok case
+ *     },
+ *     (errValue) => {
+ *         // handle err case
+ *     },
+ * );
+ * ```
+ * The vanilla `if` doesn't allocate the closures, and has less code, and you can
+ * control the flow properly inside the blocks with `return`/`break`/`continue`
+ * ```typescript
+ * const result = foo(bar);
+ * if (result.err) {
+ *     // handle err case
+ * } else {
+ *     // handle ok case
+ * }
+ * ```
+ *
+ * As for the other utility functions from Rust's Result type, they really only benefit
+ * because you can early return with `?` AND those abstractions are zero-cost in Rust.
+ * Neither is true in JavaScript.
+ *
+ * You can also easily write them yourself if you really want to.
+ *
+ * @module
+ */
+
+/**
+ * A value that either a success (Ok) or an error (Err)
+ *
+ * Construct a success with { val: ... } and an error with { err: ... }
+ */
+export type Result<T, E> = Ok<T> | Err<E>;
+
+// If these look weird, it's because TypeScript is weird
+// This is to get type narrowing to work most of the time
+
+/** A success value */
+export type Ok<T> = { val: T; err?: never };
+/** An error value */
+export type Err<E> = { err: E; val?: never };
+
+/**
+ * A value that is either `void` or an error
+ *
+ * Construct success with `{}` and an error with `{ err: ... }`
+ */
+export type Void<E> = { val?: never; err?: never } | { err: E };
+/** A value that is a success `void` */
+export type VoidOk = Record<string, never>;
+
+/** Wrap a function with try-catch and return a Result. */
+export function tryCatch<T, E = unknown>(fn: () => T): Result<T, E> {
+    try {
+        return { val: fn() };
+    } catch (e) {
+        return { err: e as E };
+    }
+}
+
+/** Wrap an async function with try-catch and return a Promise<Result>. */
+export async function tryAsync<T, E = unknown>(
+    fn: () => Promise<T>,
+): Promise<Result<T, E>> {
+    try {
+        return { val: await fn() };
+    } catch (e) {
+        return { err: e as E };
+    }
+}
+
+/** Try best effort converting an error to a string */
+export function errstr(e: unknown): string {
+    if (typeof e === "string") {
+        return e;
+    }
+    if (e) {
+        if (typeof e === "object" && "message" in e) {
+            if (typeof e.message === "string") {
+                return e.message;
+            }
+        }
+        if (typeof e === "object" && "toString" in e) {
+            return e.toString();
+        }
+    }
+    return `${e}`;
+}

package/src/sync/Debounce.ts

@@ -0,0 +1,35 @@
+/**
+ * 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);
+        });
+    }
+}

package/src/sync/Latest.ts

@@ -0,0 +1,75 @@
+import type { Result } from "../result/index.ts";
+
+/**
+ * Latest is a synchronization utility to allow
+ * only one async operation to be executed at a time,
+ * and any call will only return the result of the latest
+ * operation.
+ *
+ * ## 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 operation = async () => {
+ *     counter++;
+ *     await new Promise((resolve) => setTimeout(() => {
+ *         resolve(counter);
+ *     }, 1000));
+ * }
+ *
+ * const call = new Latest(operation);
+ *
+ * const result1 = call.execute();
+ * const result2 = call.execute();
+ * console.log(await result1); // 2
+ * console.log(await result2); // 2
+ * ```
+ */
+export class Latest<TResult> {
+    private isRunning = false;
+    private pending: {
+        resolve: (result: TResult) => void;
+        reject: (error: unknown) => void;
+    }[] = [];
+
+    constructor(private fn: () => Promise<TResult>) {}
+
+    public async execute(): Promise<TResult> {
+        if (this.isRunning) {
+            return new Promise<TResult>((resolve, reject) => {
+                this.pending.push({ resolve, reject });
+            });
+        }
+        this.isRunning = true;
+        const alreadyPending = [];
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        let result: Result<TResult, unknown> = { err: "not executed" };
+        // eslint-disable-next-line no-constant-condition
+        while (true) {
+            try {
+                const fn = this.fn;
+                result = { val: await fn() };
+            } catch (error) {
+                result = { err: error };
+            }
+            if (this.pending.length) {
+                alreadyPending.push(...this.pending);
+                this.pending = [];
+                continue;
+            }
+            break;
+        }
+        this.isRunning = false;
+        if ("err" in result) {
+            alreadyPending.forEach(({ reject }) => reject(result.err));
+            throw result.err;
+        } else {
+            alreadyPending.forEach(({ resolve }) => resolve(result.val));
+            return result.val;
+        }
+    }
+}

package/src/sync/RwLock.ts

@@ -0,0 +1,95 @@
+import Deque from "denque";
+
+/**
+ * Ensure you have exclusive access in concurrent code
+ *
+ * Only guaranteed if no one else has reference to the inner object
+ *
+ * It can take a second type parameter to specify interface with write methods
+ */
+export class RwLock<TRead, TWrite extends TRead = TRead> {
+    /**
+     * This is public so inner object can be accessed directly
+     * ONLY SAFE in sync context
+     */
+    public inner: TWrite;
+
+    private readers: number = 0;
+    private isWriting: boolean = false;
+    private readWaiters: Deque<() => void> = new Deque();
+    private writeWaiters: Deque<() => void> = new Deque();
+
+    constructor(t: TWrite) {
+        this.inner = t;
+    }
+
+    /** Acquire a read (shared) lock and call fn with the value. Release the lock when fn returns or throws. */
+    public async scopedRead<R>(fn: (t: TRead) => Promise<R>): Promise<R> {
+        if (this.isWriting) {
+            await new Promise<void>((resolve) => {
+                // need to check again to make sure it's not already done
+                if (this.isWriting) {
+                    this.readWaiters.push(resolve);
+                    return;
+                }
+                resolve();
+            });
+        }
+        // acquired
+        this.readers++;
+        try {
+            return await fn(this.inner);
+        } finally {
+            this.readers--;
+            if (this.writeWaiters.length > 0) {
+                if (this.readers === 0) {
+                    // notify one writer
+                    this.writeWaiters.shift()!();
+                }
+                // don't notify anyone if there are still readers
+            } else {
+                // notify all readers
+                while (this.readWaiters.length > 0) {
+                    this.readWaiters.shift()!();
+                }
+            }
+        }
+    }
+
+    /**
+     * Acquire a write (exclusive) lock and call fn with the value. Release the lock when fn returns or throws.
+     *
+     * fn takes a setter function as second parameter, which you can use to update the value like `x = set(newX)`
+     */
+    public async scopedWrite<R>(
+        fn: (t: TWrite, setter: (t: TWrite) => TWrite) => Promise<R>,
+    ): Promise<R> {
+        if (this.isWriting || this.readers > 0) {
+            await new Promise<void>((resolve) => {
+                // need to check again to make sure it's not already done
+                if (this.isWriting || this.readers > 0) {
+                    this.writeWaiters.push(resolve);
+                    return;
+                }
+                resolve();
+            });
+        }
+        // acquired
+        this.isWriting = true;
+        try {
+            return await fn(this.inner, (t: TWrite) => {
+                this.inner = t;
+                return t;
+            });
+        } finally {
+            this.isWriting = false;
+            if (this.readWaiters.length > 0) {
+                // notify one reader
+                this.readWaiters.shift()!();
+            } else if (this.writeWaiters.length > 0) {
+                // notify one writer
+                this.writeWaiters.shift()!();
+            }
+        }
+    }
+}

package/src/sync/Serial.ts

@@ -0,0 +1,170 @@
+import type { Void, Err, VoidOk } from "../result/index.ts";
+
+/**
+ * An async event that can be cancelled when a new one starts
+ *
+ * ## 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 event
+ * const event = new Serial();
+ *
+ * // The cancellation system uses the Result type
+ * // and returns an error when it is cancelled
+ * const promise1 = event.run(async (shouldCancel) => {
+ *     for (let i = 0; i < 10; i++) {
+ *          await wait(1000);
+ *          const cancelResult = shouldCancel();
+ *          if (cancelResult.err) {
+ *              return cancelResult;
+ *          }
+ *     }
+ *     return { val: 42 };
+ * });
+ *
+ * await wait(3000);
+ *
+ * // calling event.run a second time will cause `shouldCancel` to return false
+ * // the next time it's called by the first event
+ * const promise2 = event.run(async (shouldCancel) => {
+ *     for (let i = 0; i < 10; i++) {
+ *          await wait(1000);
+ *          const cancelResult = shouldCancel();
+ *          if (cancelResult.err) {
+ *              return cancelResult;
+ *          }
+ *     }
+ *     return { val: 43 };
+ * });
+ *
+ * console.log(await promise1); // { err: "cancel" }
+ * console.log(await promise2); // { val: 43 }
+ * ```
+ *
+ * ## Getting the current serial number
+ * The serial number has type `bigint` and is incremented every time `run` is called.
+ *
+ * The callback function receives the current serial number as the second argument, if you need it
+ * ```typescript
+ * import { Serial } from "@pistonite/pure/sync";
+ *
+ * const event = new Serial();
+ * const promise = event.run(async (shouldCancel, serial) => {
+ *    console.log(serial);
+ *    return {};
+ * });
+ * ```
+ *
+ * ## Checking for cancel
+ * It's the event handler's responsibility to check if the event is cancelled by
+ * calling the `shouldCancel` function. This function returns an `Err` if it should be cancelled.
+ *
+ * ```typescript
+ * import { Serial } from "@pistonite/pure/sync";
+ *
+ * const event = new Serial();
+ * await event.run(async (shouldCancel, serial) => {
+ *     // do some operations
+ *     ...
+ *
+ *     const cancelResult = shouldCancel();
+ *     if (cancelResult.err) {
+ *         return cancelResult;
+ *     }
+ *
+ *     // not cancelled, continue
+ *     ...
+ * });
+ * ```
+ * It's possible the operation is cheap enough that an outdated event should probably be let finish.
+ * It's ok in that case to not call `shouldCancel`. The `Serial` class checks it one
+ * last time before returning the result after the callback finishes.
+ *
+ * ## Handling cancelled event
+ * To check if an event is completed or cancelled, simply `await`
+ * on the promise returned by `event.run` and check the `err`
+ * ```typescript
+ * import { Serial } from "@pistonite/pure/sync";
+ *
+ * const event = new Serial();
+ * const result = await event.run(async (shouldCancel) => {
+ *     // your code here ...
+ * );
+ * 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. This event is guaranteed to fire at most once per run
+ * ```typescript
+ * import { Serial } from "@pistonite/pure/sync";
+ *
+ * const event = new Serial((current, latest) => {
+ *     console.log(`Event with serial ${current} is cancelled because the latest serial is ${latest}`);
+ * });
+ * ```
+ *
+ *
+ */
+export class Serial {
+    private serial: bigint;
+    private onCancel: SerialEventCancelCallback;
+
+    constructor(onCancel?: SerialEventCancelCallback) {
+        this.serial = 0n;
+        if (onCancel) {
+            this.onCancel = onCancel;
+        } else {
+            this.onCancel = () => {};
+        }
+    }
+
+    public async run<T = VoidOk>(
+        callback: SerialEventCallback<T>,
+    ): Promise<T | Err<SerialEventCancelToken>> {
+        let cancelled = false;
+        const currentSerial = ++this.serial;
+        const shouldCancel = () => {
+            if (currentSerial !== this.serial) {
+                if (!cancelled) {
+                    cancelled = true;
+                    this.onCancel(currentSerial, this.serial);
+                }
+                return { err: "cancel" as const };
+            }
+            return {};
+        };
+        const result = await callback(shouldCancel, currentSerial);
+        const cancelResult = shouldCancel();
+        if (cancelResult.err) {
+            return cancelResult;
+        }
+        return result;
+    }
+}
+
+/**
+ * The callback type passed to SerialEvent constructor to be called
+ * when the event is cancelled
+ */
+export type SerialEventCancelCallback = (
+    current: bigint,
+    latest: bigint,
+) => void;
+
+/** The callback type passed to SerialEvent.run */
+export type SerialEventCallback<T = VoidOk> = (
+    shouldCancel: () => Void<SerialEventCancelToken>,
+    current: bigint,
+) => Promise<T | Err<SerialEventCancelToken>>;
+
+/** The error type received by caller when an event is cancelled */
+export type SerialEventCancelToken = "cancel";

package/src/sync/index.ts

@@ -0,0 +1,12 @@
+/**
+ * # pure/sync
+ * JS synchronization utilities
+ *
+ * @module
+ */
+export { RwLock } from "./RwLock.ts";
+export { Serial } from "./Serial.ts";
+
+// unstable
+export { Latest } from "./Latest.ts";
+export { Debounce } from "./Debounce.ts";