@pistonite/pure 0.28.0 → 0.29.1

package/dist/_dts_/src/sync/capture.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Execute an async closure `fn`, and guarantee that `obj` will not be
+ * garbage-collected, until the promise is resolved.
+ */
+export declare const scopedCapture: <T>(fn: () => Promise<T>, obj: unknown) => Promise<T>;
+/**
+ * Execute a closure `fn`, and guarantee that `obj` will not be
+ * garbage-collected during the execution
+ */
+export declare const scopedCaptureSync: <T>(fn: () => T, obj: unknown) => T;
+//# sourceMappingURL=capture.d.ts.map

package/dist/_dts_/src/sync/capture.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capture.d.ts","sourceRoot":"","sources":["../../../../src/sync/capture.ts"],"names":[],"mappings":"AAIA;;;GAGG;AACH,eAAO,MAAM,aAAa,GAAU,CAAC,EAAE,IAAI,MAAM,OAAO,CAAC,CAAC,CAAC,EAAE,KAAK,OAAO,KAAG,OAAO,CAAC,CAAC,CAYpF,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,iBAAiB,GAAI,CAAC,EAAE,IAAI,MAAM,CAAC,EAAE,KAAK,OAAO,KAAG,CAQhE,CAAC"}

package/dist/_dts_/src/sync/debounce.d.ts

@@ -0,0 +1,105 @@
+import { type AnyFn, type AwaitRet } from "./util.ts";
+/** Factory for debounced function. See {@link DebounceConstructor} for usage */
+export declare function debounce<TFn extends AnyFn>(args: DebounceConstructor<TFn>): (...args: Parameters<TFn>) => Promise<AwaitRet<TFn>>;
+/**
+ * Options for `debounce` function
+ *
+ * A debounced function is 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 interface 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;
+}
+//# sourceMappingURL=debounce.d.ts.map

package/dist/_dts_/src/sync/debounce.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"debounce.d.ts","sourceRoot":"","sources":["../../../../src/sync/debounce.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,KAAK,EAAE,KAAK,QAAQ,EAAmC,MAAM,WAAW,CAAC;AAEvF,gFAAgF;AAChF,wBAAgB,QAAQ,CAAC,GAAG,SAAS,KAAK,EAAE,IAAI,EAAE,mBAAmB,CAAC,GAAG,CAAC,IAG9D,GAAG,MAAM,UAAU,CAAC,GAAG,CAAC,4BACnC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+EG;AACH,MAAM,WAAW,mBAAmB,CAAC,GAAG;IACpC,+BAA+B;IAC/B,EAAE,EAAE,GAAG,CAAC;IACR;;;;;OAKG;IACH,QAAQ,EAAE,MAAM,CAAC;IAEjB;;;;;;;;OAQG;IACH,sBAAsB,CAAC,EAAE,OAAO,CAAC;CACpC"}

package/dist/_dts_/src/sync/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Synchronization utilities
+ *
+ * @module
+ */
+export { serial, type SerialConstructor, type SerialEventCancelCallback, type SerialCancelToken, } from "./serial.ts";
+export { latest, type LatestConstructor, type LatestUpdateArgsFn } from "./latest.ts";
+export { debounce, type DebounceConstructor } from "./debounce.ts";
+export { batch, type BatchConstructor } from "./batch.ts";
+export { once, type OnceConstructor } from "./once.ts";
+export { makePromise, type PromiseHandle } from "./util.ts";
+export { scopedCapture, scopedCaptureSync } from "./capture.ts";
+export type { AnyFn, AwaitRet } from "./util.ts";
+export { RwLock } from "./RwLock.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/_dts_/src/sync/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/sync/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EACH,MAAM,EACN,KAAK,iBAAiB,EACtB,KAAK,yBAAyB,EAC9B,KAAK,iBAAiB,GACzB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,MAAM,EAAE,KAAK,iBAAiB,EAAE,KAAK,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACtF,OAAO,EAAE,QAAQ,EAAE,KAAK,mBAAmB,EAAE,MAAM,eAAe,CAAC;AACnE,OAAO,EAAE,KAAK,EAAE,KAAK,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAC1D,OAAO,EAAE,IAAI,EAAE,KAAK,eAAe,EAAE,MAAM,WAAW,CAAC;AACvD,OAAO,EAAE,WAAW,EAAE,KAAK,aAAa,EAAE,MAAM,WAAW,CAAC;AAC5D,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAGhE,YAAY,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAGjD,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC"}

package/dist/_dts_/src/sync/latest.d.ts

@@ -0,0 +1,86 @@
+import { type AnyFn, type AwaitRet } from "./util.ts";
+/**
+ * Factory for `latest`. See {@link LatestConstructor} for usage.
+ */
+export declare function latest<TFn extends AnyFn>(args: LatestConstructor<TFn>): (...args: Parameters<TFn>) => Promise<AwaitRet<TFn>>;
+/**
+ * Args for constructing `latest`
+ *
+ * `latest` is 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
+ * ```
+ *
+ * ## Advanced Usage
+ * See the constructor options for more advanced usage, for example,
+ * control how arguments are updated when new calls are made.
+ */
+export interface 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?: LatestUpdateArgsFn<TFn>;
+}
+/** See {@link LatestConstructor} */
+export type LatestUpdateArgsFn<TFn extends AnyFn> = (current: Parameters<TFn>, middle: Parameters<TFn>[], latest: Parameters<TFn>, next: Parameters<TFn> | undefined) => Parameters<TFn>;
+export declare class LatestImpl<TFn extends AnyFn> {
+    private fn;
+    private pending?;
+    /** current arguments. undefined means no current call */
+    private currentArgs?;
+    /** next arguments. undefined means no newer call */
+    private nextArgs?;
+    private middleArgs;
+    private areArgsEqual;
+    private updateArgs;
+    constructor(fn: TFn, areArgsEqual?: (a: Parameters<TFn>, b: Parameters<TFn>) => boolean, updateArgs?: LatestUpdateArgsFn<TFn>);
+    invoke(...args: Parameters<TFn>): Promise<AwaitRet<TFn>>;
+}
+//# sourceMappingURL=latest.d.ts.map

package/dist/_dts_/src/sync/latest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"latest.d.ts","sourceRoot":"","sources":["../../../../src/sync/latest.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,KAAK,EAAE,KAAK,QAAQ,EAAmC,MAAM,WAAW,CAAC;AAEvF;;GAEG;AACH,wBAAgB,MAAM,CAAC,GAAG,SAAS,KAAK,EAAE,IAAI,EAAE,iBAAiB,CAAC,GAAG,CAAC,IAG1D,GAAG,MAAM,UAAU,CAAC,GAAG,CAAC,4BACnC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,MAAM,WAAW,iBAAiB,CAAC,GAAG,SAAS,KAAK;IAChD,6BAA6B;IAC7B,EAAE,EAAE,GAAG,CAAC;IAER;;;;;;;;OAQG;IACH,YAAY,CAAC,EAAE,CAAC,CAAC,EAAE,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,UAAU,CAAC,GAAG,CAAC,KAAK,OAAO,CAAC;IAEnE;;;;;;;;;;;;;;;;OAgBG;IACH,UAAU,CAAC,EAAE,kBAAkB,CAAC,GAAG,CAAC,CAAC;CACxC;AACD,oCAAoC;AACpC,MAAM,MAAM,kBAAkB,CAAC,GAAG,SAAS,KAAK,IAAI,CAChD,OAAO,EAAE,UAAU,CAAC,GAAG,CAAC,EACxB,MAAM,EAAE,UAAU,CAAC,GAAG,CAAC,EAAE,EACzB,MAAM,EAAE,UAAU,CAAC,GAAG,CAAC,EACvB,IAAI,EAAE,UAAU,CAAC,GAAG,CAAC,GAAG,SAAS,KAChC,UAAU,CAAC,GAAG,CAAC,CAAC;AACrB,qBAAa,UAAU,CAAC,GAAG,SAAS,KAAK;IAcjC,OAAO,CAAC,EAAE;IAbd,OAAO,CAAC,OAAO,CAAC,CAA+B;IAE/C,yDAAyD;IACzD,OAAO,CAAC,WAAW,CAAC,CAAkB;IACtC,oDAAoD;IACpD,OAAO,CAAC,QAAQ,CAAC,CAAkB;IAEnC,OAAO,CAAC,UAAU,CAAoB;IAEtC,OAAO,CAAC,YAAY,CAAsD;IAC1E,OAAO,CAAC,UAAU,CAA0B;gBAGhC,EAAE,EAAE,GAAG,EACf,YAAY,CAAC,EAAE,CAAC,CAAC,EAAE,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,UAAU,CAAC,GAAG,CAAC,KAAK,OAAO,EAClE,UAAU,CAAC,EAAE,kBAAkB,CAAC,GAAG,CAAC;IAO3B,MAAM,CAAC,GAAG,IAAI,EAAE,UAAU,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;CAyCxE"}

package/dist/_dts_/src/sync/mutex.d.ts

@@ -0,0 +1,14 @@
+export {};
+/**
+ * Non-reentrant mutex
+ *
+ * This allows only one context to enter a block at a time in a FIFO manner.
+ *
+ * This mutex is non-reentrant. Trying to lock it again while the same
+ * context already owns the lock will cause a dead lock.
+ *
+ * While a context id can be used to implement reentrant locks,
+ * it is very cumbersome to use. https://github.com/tc39/proposal-async-context
+ * will allow for a cleaner implementation.
+ */
+//# sourceMappingURL=mutex.d.ts.map

package/dist/_dts_/src/sync/mutex.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mutex.d.ts","sourceRoot":"","sources":["../../../../src/sync/mutex.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;GAWG"}

package/dist/_dts_/src/sync/once.d.ts

@@ -0,0 +1,84 @@
+import { type AnyFn, type AwaitRet } from "./util.ts";
+/**
+ * Factory function for `once`. See {@link OnceConstructor} for usage
+ */
+export declare function once<TFn extends AnyFn>(args: OnceConstructor<TFn>): (...args: Parameters<TFn>) => Promise<AwaitRet<TFn>>;
+/**
+ * Args for constructing a `once`
+ *
+ * `once` is 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.
+ */
+export interface OnceConstructor<TFn> {
+    /** Function to be called only once */
+    fn: TFn;
+}
+export declare class OnceImpl<TFn extends AnyFn> {
+    private fn;
+    private promise;
+    constructor(fn: TFn);
+    invoke(...args: Parameters<TFn>): Promise<AwaitRet<TFn>>;
+}
+//# sourceMappingURL=once.d.ts.map

package/dist/_dts_/src/sync/once.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"once.d.ts","sourceRoot":"","sources":["../../../../src/sync/once.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,KAAK,EAAE,KAAK,QAAQ,EAAe,MAAM,WAAW,CAAC;AAEnE;;GAEG;AACH,wBAAgB,IAAI,CAAC,GAAG,SAAS,KAAK,EAAE,IAAI,EAAE,eAAe,CAAC,GAAG,CAAC,IAEtD,GAAG,MAAM,UAAU,CAAC,GAAG,CAAC,4BACnC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmEG;AACH,MAAM,WAAW,eAAe,CAAC,GAAG;IAChC,sCAAsC;IACtC,EAAE,EAAE,GAAG,CAAC;CACX;AAED,qBAAa,QAAQ,CAAC,GAAG,SAAS,KAAK;IAGvB,OAAO,CAAC,EAAE;IAFtB,OAAO,CAAC,OAAO,CAAqC;gBAEhC,EAAE,EAAE,GAAG;IAId,MAAM,CAAC,GAAG,IAAI,EAAE,UAAU,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;CAexE"}

package/dist/_dts_/src/sync/serial.d.ts

@@ -0,0 +1,162 @@
+import type { Result } from "../result/index.ts";
+import type { AnyFn } from "./util.ts";
+/**
+ * Factory function for `serial`. See {@link SerialConstructor} for usage
+ */
+export declare const serial: <TFn extends AnyFn>(args: SerialConstructor<TFn>) => (...args: Parameters<TFn>) => Promise<Result<Awaited<ReturnType<TFn>>, "cancel">>;
+/**
+ * Options for `serial` function
+ *
+ * `serial` is 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 interface 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;
+}
+type SerialId = bigint;
+type CheckCancelFn = () => void;
+/**
+ * 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";
+export {};
+//# sourceMappingURL=serial.d.ts.map

package/dist/_dts_/src/sync/serial.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serial.d.ts","sourceRoot":"","sources":["../../../../src/sync/serial.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,WAAW,CAAC;AAEvC;;GAEG;AACH,eAAO,MAAM,MAAM,GAAI,GAAG,SAAS,KAAK,EAAE,MAAM,iBAAiB,CAAC,GAAG,CAAC,MAG1D,GAAG,MAAM,UAAU,CAAC,GAAG,CAAC,wDACnC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoIG;AACH,MAAM,WAAW,iBAAiB,CAAC,GAAG;IAClC;;OAEG;IACH,EAAE,EAAE,CAAC,WAAW,EAAE,aAAa,EAAE,OAAO,EAAE,QAAQ,KAAK,GAAG,CAAC;IAC3D;;;;OAIG;IACH,QAAQ,CAAC,EAAE,yBAAyB,CAAC;CACxC;AA8CD,KAAK,QAAQ,GAAG,MAAM,CAAC;AACvB,KAAK,aAAa,GAAG,MAAM,IAAI,CAAC;AAGhC;;;GAGG;AACH,MAAM,MAAM,yBAAyB,GAAG,CAAC,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,KAAK,IAAI,CAAC;AAEtF,mEAAmE;AACnE,MAAM,MAAM,iBAAiB,GAAG,QAAQ,CAAC"}

package/dist/_dts_/src/sync/util.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Make a {@link PromiseHandle} with the promise object separate from
+ * its resolve and reject methods
+ */
+export declare const makePromise: <T>() => PromiseHandle<T>;
+/**
+ * A handle of the promise that breaks down the promise object
+ * and its resolve and reject functions
+ */
+export interface PromiseHandle<T> {
+    promise: Promise<T>;
+    resolve: (value: T | PromiseLike<T>) => void;
+    reject: (reason?: unknown) => void;
+}
+/** Shorthand for Awaited<ReturnType<T>> */
+export type AwaitRet<T> = T extends (...args: any[]) => infer R ? Awaited<R> : never;
+/** Type for any function */
+export type AnyFn = (...args: any[]) => any;
+//# sourceMappingURL=util.d.ts.map

package/dist/_dts_/src/sync/util.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"util.d.ts","sourceRoot":"","sources":["../../../../src/sync/util.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,eAAO,MAAM,WAAW,GAAI,CAAC,OAAK,aAAa,CAAC,CAAC,CAUhD,CAAC;AAEF;;;GAGG;AACH,MAAM,WAAW,aAAa,CAAC,CAAC;IAC5B,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;IACpB,OAAO,EAAE,CAAC,KAAK,EAAE,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC;IAC7C,MAAM,EAAE,CAAC,MAAM,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;CACtC;AAED,2CAA2C;AAE3C,MAAM,MAAM,QAAQ,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC;AAErF,4BAA4B;AAE5B,MAAM,MAAM,KAAK,GAAG,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,CAAC"}

package/dist/log/index.js

@@ -0,0 +1,57 @@
+import { errstr as e } from "../result/index.js";
+//#region src/log/logger.ts
+var t = {
+	off: 0,
+	default: 1,
+	info: 2,
+	debug: 3
+}, n = (e, n) => {
+	let { color: a, level: o } = n, s = t[o || "off"] || t.off;
+	return globalThis.process ? new r(e, s) : new i(e, a || "gray", s);
+}, r = class {
+	constructor(e, t) {
+		this.name = e, this.level = t;
+	}
+	setLevel(e) {
+		this.level = t[e] || t.off;
+	}
+	debug(e) {
+		this.level === t.debug && console.debug(`DEBUG [${this.name}] ${e}`);
+	}
+	info(e) {
+		this.level < t.info || console.info(`INFO [${this.name}] ${e}`);
+	}
+	warn(e) {
+		this.level < t.default || console.warn(`WARN [${this.name}] ${e}`);
+	}
+	error(n) {
+		if (this.level < t.default) return;
+		let r = e(n);
+		console.error(`ERROR [${this.name}] ${r}`), r !== n && console.error(n);
+	}
+}, i = class {
+	constructor(e, t, n) {
+		this.name = e, this.color = t, this.level = n;
+	}
+	setLevel(e) {
+		this.level = t[e] || t.off;
+	}
+	debug(e) {
+		this.level === t.debug && console.debug(`%cDEBUG%c${this.name}%c ${e}`, "background:gray;color:white;padding:0 3px", this.color, "color:inherit;background:inherit");
+	}
+	info(e) {
+		this.level < t.info || console.info(`%cINFO%c${this.name}%c ${e}`, "background:green;color:white;padding:0 3px", this.color, "color:inherit;background:inherit");
+	}
+	warn(e) {
+		this.level < t.default || console.warn(`%cWARN%c${this.name}%c ${e}`, "background:orange;color:white;padding:0 3px", this.color, "color:inherit;background:inherit");
+	}
+	error(n) {
+		if (this.level < t.default) return;
+		let r = e(n);
+		console.error(`%cERROR%c${this.name}%c ${r}`, "background:darkred;color:white;padding:0 3px", this.color, "color:inherit;background:inherit"), r !== n && console.error(n);
+	}
+};
+//#endregion
+export { n as logger };
+
+//# sourceMappingURL=index.js.map

package/dist/log/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../../src/log/logger.ts"],"sourcesContent":["import { errstr } from \"../result/index.ts\";\n\n/**\n * String-enum for logging levels\n *\n * off - no logging at all\n * default - warning and errors only\n * info - warning, errors, info\n * debug - warning, errors, info, debug\n */\n\nconst LogLevel = { off: 0, default: 1, info: 2, debug: 3 } as const;\nexport type LogLevelStr = \"off\" | \"default\" | \"info\" | \"debug\";\nif (import.meta.vitest) {\n    const { test, expectTypeOf } = import.meta.vitest;\n    test(\"type LogLevelStr\", () => {\n        expectTypeOf<LogLevelStr>().toEqualTypeOf<keyof typeof LogLevel>();\n    });\n}\ntype LogLevel = (typeof LogLevel)[LogLevelStr];\n\n/** Args for constructing a logger */\nexport interface LoggerConstructor {\n    /** CSS Color for the logger, default is 'gray' */\n    color?: string;\n    /**\n     * Logging level, default is \"default\".\n     * The level can still be changed later with setLevel\n     */\n    level?: LogLevelStr;\n}\n\n/** The logger type */\nexport interface Logger {\n    /** Set the level of the logger */\n    setLevel(level: LogLevelStr): void;\n    /** Log a debug message */\n    debug(obj: unknown): void;\n    /** Log an info message */\n    info(obj: unknown): void;\n    /** Log a warning message */\n    warn(obj: unknown): void;\n    /** Log an error message */\n    error(obj: unknown): void;\n}\n\n/** Create a logger creator. Use the factory methods to finish making the logger */\nexport const logger = (name: string, args: LoggerConstructor): Logger => {\n    const { color, level } = args;\n    const levelObj = LogLevel[level || \"off\"] || LogLevel.off;\n    // eslint-disable-next-line @typescript-eslint/no-explicit-any\n    if ((globalThis as any).process) {\n        return new BareLoggerImpl(name, levelObj);\n    }\n    const color2 = color || \"gray\";\n    return new CssLoggerImpl(name, color2, levelObj);\n};\n\nclass BareLoggerImpl implements Logger {\n    constructor(\n        private name: string,\n        private level: LogLevel,\n    ) {}\n    setLevel(level: LogLevelStr): void {\n        this.level = LogLevel[level] || LogLevel[\"off\"];\n    }\n    debug(obj: unknown): void {\n        if (this.level !== LogLevel.debug) {\n            return;\n        }\n        console.debug(`DEBUG [${this.name}] ${obj}`);\n    }\n    info(obj: unknown): void {\n        if (this.level < LogLevel.info) {\n            return;\n        }\n        console.info(`INFO [${this.name}] ${obj}`);\n    }\n    warn(obj: unknown): void {\n        if (this.level < LogLevel.default) {\n            return;\n        }\n        console.warn(`WARN [${this.name}] ${obj}`);\n    }\n    error(obj: unknown): void {\n        if (this.level < LogLevel.default) {\n            return;\n        }\n        const msg = errstr(obj);\n        console.error(`ERROR [${this.name}] ${msg}`);\n        if (msg !== obj) {\n            console.error(obj);\n        }\n    }\n}\n\nclass CssLoggerImpl implements Logger {\n    constructor(\n        private name: string,\n        private color: string,\n        private level: LogLevel,\n    ) {}\n    setLevel(level: LogLevelStr): void {\n        this.level = LogLevel[level] || LogLevel[\"off\"];\n    }\n    debug(obj: unknown): void {\n        if (this.level !== LogLevel.debug) {\n            return;\n        }\n        console.debug(\n            `%cDEBUG%c${this.name}%c ${obj}`,\n            \"background:gray;color:white;padding:0 3px\",\n            this.color,\n            \"color:inherit;background:inherit\",\n        );\n    }\n    info(obj: unknown): void {\n        if (this.level < LogLevel.info) {\n            return;\n        }\n        console.info(\n            `%cINFO%c${this.name}%c ${obj}`,\n            \"background:green;color:white;padding:0 3px\",\n            this.color,\n            \"color:inherit;background:inherit\",\n        );\n    }\n    warn(obj: unknown): void {\n        if (this.level < LogLevel.default) {\n            return;\n        }\n        console.warn(\n            `%cWARN%c${this.name}%c ${obj}`,\n            \"background:orange;color:white;padding:0 3px\",\n            this.color,\n            \"color:inherit;background:inherit\",\n        );\n    }\n    error(obj: unknown): void {\n        if (this.level < LogLevel.default) {\n            return;\n        }\n        const msg = errstr(obj);\n        console.error(\n            `%cERROR%c${this.name}%c ${msg}`,\n            \"background:darkred;color:white;padding:0 3px\",\n            this.color,\n            \"color:inherit;background:inherit\",\n        );\n        if (msg !== obj) {\n            console.error(obj);\n        }\n    }\n}\n"],"mappings":";;AAWA,IAAM,IAAW;CAAE,KAAK;CAAG,SAAS;CAAG,MAAM;CAAG,OAAO;CAAG,EAoC7C,KAAU,GAAc,MAAoC;CACrE,IAAM,EAAE,UAAO,aAAU,GACnB,IAAW,EAAS,KAAS,UAAU,EAAS;AAMtD,QAJK,WAAmB,UACb,IAAI,EAAe,GAAM,EAAS,GAGtC,IAAI,EAAc,GADV,KAAS,QACe,EAAS;GAG9C,IAAN,MAAuC;CACnC,YACI,GACA,GACF;AADU,EADA,KAAA,OAAA,GACA,KAAA,QAAA;;CAEZ,SAAS,GAA0B;AAC/B,OAAK,QAAQ,EAAS,MAAU,EAAS;;CAE7C,MAAM,GAAoB;AAClB,OAAK,UAAU,EAAS,SAG5B,QAAQ,MAAM,UAAU,KAAK,KAAK,IAAI,IAAM;;CAEhD,KAAK,GAAoB;AACjB,OAAK,QAAQ,EAAS,QAG1B,QAAQ,KAAK,SAAS,KAAK,KAAK,IAAI,IAAM;;CAE9C,KAAK,GAAoB;AACjB,OAAK,QAAQ,EAAS,WAG1B,QAAQ,KAAK,SAAS,KAAK,KAAK,IAAI,IAAM;;CAE9C,MAAM,GAAoB;AACtB,MAAI,KAAK,QAAQ,EAAS,QACtB;EAEJ,IAAM,IAAM,EAAO,EAAI;AAEvB,EADA,QAAQ,MAAM,UAAU,KAAK,KAAK,IAAI,IAAM,EACxC,MAAQ,KACR,QAAQ,MAAM,EAAI;;GAKxB,IAAN,MAAsC;CAClC,YACI,GACA,GACA,GACF;AADU,EAFA,KAAA,OAAA,GACA,KAAA,QAAA,GACA,KAAA,QAAA;;CAEZ,SAAS,GAA0B;AAC/B,OAAK,QAAQ,EAAS,MAAU,EAAS;;CAE7C,MAAM,GAAoB;AAClB,OAAK,UAAU,EAAS,SAG5B,QAAQ,MACJ,YAAY,KAAK,KAAK,KAAK,KAC3B,6CACA,KAAK,OACL,mCACH;;CAEL,KAAK,GAAoB;AACjB,OAAK,QAAQ,EAAS,QAG1B,QAAQ,KACJ,WAAW,KAAK,KAAK,KAAK,KAC1B,8CACA,KAAK,OACL,mCACH;;CAEL,KAAK,GAAoB;AACjB,OAAK,QAAQ,EAAS,WAG1B,QAAQ,KACJ,WAAW,KAAK,KAAK,KAAK,KAC1B,+CACA,KAAK,OACL,mCACH;;CAEL,MAAM,GAAoB;AACtB,MAAI,KAAK,QAAQ,EAAS,QACtB;EAEJ,IAAM,IAAM,EAAO,EAAI;AAOvB,EANA,QAAQ,MACJ,YAAY,KAAK,KAAK,KAAK,KAC3B,gDACA,KAAK,OACL,mCACH,EACG,MAAQ,KACR,QAAQ,MAAM,EAAI"}