@pistonite/pure 0.0.13 → 0.0.14

package/src/sync/Latest.ts

@@ -1,75 +0,0 @@
-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/Serial.ts

@@ -1,170 +0,0 @@
-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";