@pistonite/pure 0.29.0 → 0.29.1

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

@@ -0,0 +1,37 @@
+/**
+ * Client side log util
+ *
+ * This is rather simple logging stuff with the primary focus
+ * being easy-to-debug, instead of optimized for bundle size or performance.
+ *
+ * Because this library doesn't have global states, there is no "global" logger
+ * or any global logger settings. Instead, each library or component of the
+ * application can create their own instance of the logger, which stores
+ * settings like the name, color and level of that logger.
+ *
+ * ```typescript
+ * import { logger } from "@pistonite/pure";
+ *
+ * export const myLogger = logger("my-library", {
+ *     color: "#ff8800", // any CSS color (note that styling only works in browser)
+ * });
+ * ```
+ *
+ * It's recommended that a library exports the logger object
+ * so downstream app can modify the logging level if needed for debugging.
+ * ```typescript
+ * import { myLogger } from "my-library";
+ *
+ * myLogger.setLevel("debug");
+ * ```
+ *
+ * Due to the nature of JS, all logging calls, even when turned off, will incur
+ * some small runtime overhead. While we could remove debug calls
+ * for release build, that's currently not done (and it would require
+ * bundler to inline the call to remove the call completely, which might
+ * not be the case)
+ *
+ * @module
+ */
+export { type LogLevelStr, type LoggerConstructor, type Logger, logger } from "./logger.ts";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/log/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,OAAO,EAAE,KAAK,WAAW,EAAE,KAAK,iBAAiB,EAAE,KAAK,MAAM,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC"}

package/dist/_dts_/src/log/logger.d.ts

@@ -0,0 +1,27 @@
+export type LogLevelStr = "off" | "default" | "info" | "debug";
+/** Args for constructing a logger */
+export interface LoggerConstructor {
+    /** CSS Color for the logger, default is 'gray' */
+    color?: string;
+    /**
+     * Logging level, default is "default".
+     * The level can still be changed later with setLevel
+     */
+    level?: LogLevelStr;
+}
+/** The logger type */
+export interface Logger {
+    /** Set the level of the logger */
+    setLevel(level: LogLevelStr): void;
+    /** Log a debug message */
+    debug(obj: unknown): void;
+    /** Log an info message */
+    info(obj: unknown): void;
+    /** Log a warning message */
+    warn(obj: unknown): void;
+    /** Log an error message */
+    error(obj: unknown): void;
+}
+/** Create a logger creator. Use the factory methods to finish making the logger */
+export declare const logger: (name: string, args: LoggerConstructor) => Logger;
+//# sourceMappingURL=logger.d.ts.map

package/dist/_dts_/src/log/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../../../src/log/logger.ts"],"names":[],"mappings":"AAYA,MAAM,MAAM,WAAW,GAAG,KAAK,GAAG,SAAS,GAAG,MAAM,GAAG,OAAO,CAAC;AAS/D,qCAAqC;AACrC,MAAM,WAAW,iBAAiB;IAC9B,kDAAkD;IAClD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,KAAK,CAAC,EAAE,WAAW,CAAC;CACvB;AAED,sBAAsB;AACtB,MAAM,WAAW,MAAM;IACnB,kCAAkC;IAClC,QAAQ,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI,CAAC;IACnC,0BAA0B;IAC1B,KAAK,CAAC,GAAG,EAAE,OAAO,GAAG,IAAI,CAAC;IAC1B,0BAA0B;IAC1B,IAAI,CAAC,GAAG,EAAE,OAAO,GAAG,IAAI,CAAC;IACzB,4BAA4B;IAC5B,IAAI,CAAC,GAAG,EAAE,OAAO,GAAG,IAAI,CAAC;IACzB,2BAA2B;IAC3B,KAAK,CAAC,GAAG,EAAE,OAAO,GAAG,IAAI,CAAC;CAC7B;AAED,mFAAmF;AACnF,eAAO,MAAM,MAAM,GAAI,MAAM,MAAM,EAAE,MAAM,iBAAiB,KAAG,MAS9D,CAAC"}

package/dist/_dts_/src/memory/cell.d.ts

@@ -0,0 +1,25 @@
+/** Create a {@link Cell} */
+export declare const cell: <T>(args: CellConstructor<T>) => Cell<T>;
+/** Args for constructing a cell */
+export interface CellConstructor<T> {
+    /** Initial value */
+    initial: T;
+}
+/**
+ * A light weight storage wrapper around a value
+ * that can be subscribed to for changes
+ *
+ * Created via `cell()`
+ *
+ * ```typescript
+ * import { cell } from "@pistonite/pure/memory";
+ *
+ * const myCell = cell(true);
+ * ```
+ */
+export interface Cell<T> {
+    get(): T;
+    set(value: T): void;
+    subscribe(callback: (value: T) => void, notifyImmediately?: boolean): () => void;
+}
+//# sourceMappingURL=cell.d.ts.map

package/dist/_dts_/src/memory/cell.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cell.d.ts","sourceRoot":"","sources":["../../../../src/memory/cell.ts"],"names":[],"mappings":"AAAA,4BAA4B;AAC5B,eAAO,MAAM,IAAI,GAAI,CAAC,EAAE,MAAM,eAAe,CAAC,CAAC,CAAC,KAAG,IAAI,CAAC,CAAC,CAExD,CAAC;AAEF,mCAAmC;AACnC,MAAM,WAAW,eAAe,CAAC,CAAC;IAC9B,oBAAoB;IACpB,OAAO,EAAE,CAAC,CAAC;CACd;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,IAAI,CAAC,CAAC;IACnB,GAAG,IAAI,CAAC,CAAC;IACT,GAAG,CAAC,KAAK,EAAE,CAAC,GAAG,IAAI,CAAC;IACpB,SAAS,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,EAAE,iBAAiB,CAAC,EAAE,OAAO,GAAG,MAAM,IAAI,CAAC;CACpF"}

package/dist/_dts_/src/memory/emp.d.ts

@@ -0,0 +1,87 @@
+/**
+ * A non-null, **E**ngine-**m**anaged **P**ointer
+ *
+ * This uses the ECMA FinalizationRegistry, to free the resource,
+ * once this object is garbage-collected.
+ *
+ * The free function may be async.
+ *
+ * ## Use case
+ * When JS interoperates with a system language like C/C++ or Rust,
+ * it is often needed to transfer objects into JS context. If the object
+ * is big, copy-transfer could be expensive, so the more ideal solution
+ * is to transfer a "handle", or a pointer, to JS, and leaving the actual
+ * object in the native memory. Then, JS code and pass the pointer to external
+ * code to use or extract data from the object when needed.
+ *
+ * This approach is just like passing raw pointers in C, which means it is
+ * extremely succeptible to memory corruption bugs like double-free or
+ * use-after-free. Unlike C++ or Rust, JS also doesn't have destructors
+ * that run when an object leaves the scope (proposal for the `using` keyword exists,
+ * but you can actually double-free the object with `using`).
+ *
+ * C-style manual memory management might be sufficient for simple bindings,
+ * but for more complex scenarios, automatic memory management is needed,
+ * by tying the free call to the GC of a JS object.
+ *
+ * ## Recommended practice
+ * 1. The external code should transfer the ownership of the object
+ *    to JS when passing it to JS. JS will then put the handle into an Emp
+ *    to be automatically managed. This means the external code should now
+ *    never free the object, and let JS free it instead.
+ * 2. The inner value of the Emp must only be used for calling
+ *    external code, and the Emp must be kept alive for all runtimes, including
+ *    those with heavy optimization that may reclaim the Emp during the call,
+ *    if it's not referenced afterwards. See {@link scopedCapture}.
+ *    The inner value must not dangle around outside of the Emp that owns it.
+ *
+ * ## Pointer Size
+ * In 32-bit context like WASM32, the inner value can be a `number`.
+ * In 64-bit context, `number` might be fine for some systems, but `bigint`
+ * is recommended.
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * // First create a marker to distinguish between different Emp types for TypeScript.
+ * // This is not used at runtime
+ * const MyNativeType = Symbol("MyNativeType");
+ * export type MyNativeType = typeof MyNativeType;
+ *
+ * // Then use makeEmpType to create a factory function
+ * const makeMyNativeTypeEmp = makeEmpType({
+ *     marker: MyNativeType,
+ *     free: (ptr) => freeMyNativeType(ptr),
+ * });
+ *
+ * // Now acquire ownership of an object from external native code
+ * // and assign it to an Emp
+ * const myObjRawPtr = allocMyNativeType();
+ * const myObj = makeMyNativeTypeEmp(myObjRawPtr);
+ *
+ * // when myObj is GC'ed, it will be freed by calling freeMyNativeType
+ * ```
+ */
+export interface Emp<T, TRepr> {
+    /** The type marker for T. This only marks the type for TypeScript and does not exist at runtime */
+    readonly __phantom: T;
+    /** The underlying pointer value */
+    readonly value: TRepr;
+}
+/** Args for constructing a Emp type */
+export interface EmpConstructor<T, TRepr> {
+    /**
+     * The marker for the Emp type, used to distinguish between multiple Emp types
+     * in TypeScript
+     */
+    marker?: T;
+    /**
+     * Function to free the underlying object. Called when this Emp is garbage-collected
+     */
+    free: (ptr: TRepr) => void | Promise<void>;
+}
+/**
+ * Create a factory function for an Emp type. See {@link Emp}
+ */
+export declare const makeEmpType: <T, TRepr>(args: EmpConstructor<T, TRepr>) => ((ptr: TRepr) => Emp<T, TRepr>);
+//# sourceMappingURL=emp.d.ts.map

package/dist/_dts_/src/memory/emp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"emp.d.ts","sourceRoot":"","sources":["../../../../src/memory/emp.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+DG;AACH,MAAM,WAAW,GAAG,CAAC,CAAC,EAAE,KAAK;IACzB,mGAAmG;IACnG,QAAQ,CAAC,SAAS,EAAE,CAAC,CAAC;IACtB,mCAAmC;IACnC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;CACzB;AAED,uCAAuC;AACvC,MAAM,WAAW,cAAc,CAAC,CAAC,EAAE,KAAK;IACpC;;;OAGG;IACH,MAAM,CAAC,EAAE,CAAC,CAAC;IAEX;;OAEG;IACH,IAAI,EAAE,CAAC,GAAG,EAAE,KAAK,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9C;AAED;;GAEG;AACH,eAAO,MAAM,WAAW,GAAI,CAAC,EAAE,KAAK,EAChC,MAAM,cAAc,CAAC,CAAC,EAAE,KAAK,CAAC,KAC/B,CAAC,CAAC,GAAG,EAAE,KAAK,KAAK,GAAG,CAAC,CAAC,EAAE,KAAK,CAAC,CAQhC,CAAC"}

package/dist/_dts_/src/memory/idgen.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Return an id generator that will generate ids in order
+ * from 1 to n, wrapping around to 1 when it's n
+ */
+export declare const safeidgen: (n: number) => (() => number);
+/**
+ * Return an id generator that returns bigint,
+ * starting from 1n, and will always return a new bigint
+ */
+export declare const bidgen: () => (() => bigint);
+/**
+ * Returns an id generator that returns number staring from 1
+ * and always increasing. The number could become inaccurate
+ * (not integer) when exceeding Number.MAX_SAFE_INTEGER (which
+ * is 2^53 - 1
+ */
+export declare const idgen: () => (() => number);
+//# sourceMappingURL=idgen.d.ts.map

package/dist/_dts_/src/memory/idgen.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"idgen.d.ts","sourceRoot":"","sources":["../../../../src/memory/idgen.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,eAAO,MAAM,SAAS,GAAI,GAAG,MAAM,KAAG,CAAC,MAAM,MAAM,CASlD,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,MAAM,QAAO,CAAC,MAAM,MAAM,CAMtC,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,KAAK,QAAO,CAAC,MAAM,MAAM,CAMrC,CAAC"}

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

@@ -0,0 +1,10 @@
+/**
+ * Memory utilities
+ *
+ * @module
+ */
+export { cell, type CellConstructor, type Cell } from "./cell.ts";
+export { persist, type PersistConstructor, type Persist } from "./persist.ts";
+export * from "./emp.ts";
+export * from "./idgen.ts";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/memory/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,IAAI,EAAE,KAAK,eAAe,EAAE,KAAK,IAAI,EAAE,MAAM,WAAW,CAAC;AAClE,OAAO,EAAE,OAAO,EAAE,KAAK,kBAAkB,EAAE,KAAK,OAAO,EAAE,MAAM,cAAc,CAAC;AAC9E,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC"}

package/dist/_dts_/src/memory/persist.d.ts

@@ -0,0 +1,38 @@
+import { type Cell, type CellConstructor } from "./cell.ts";
+/**
+ * Create a cell that persists its value to a web storage
+ */
+export declare function persist<T>(args: PersistConstructor<T>): Persist<T>;
+/** Args for creating a persisted cell */
+export interface PersistConstructor<T> extends 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;
+}
+/** A cell that also persists its value */
+export interface Persist<T> extends 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;
+    /** Clear the value and disable the persistence */
+    disable(): void;
+}
+//# sourceMappingURL=persist.d.ts.map

package/dist/_dts_/src/memory/persist.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"persist.d.ts","sourceRoot":"","sources":["../../../../src/memory/persist.ts"],"names":[],"mappings":"AAAA,OAAO,EAAQ,KAAK,IAAI,EAAE,KAAK,eAAe,EAAE,MAAM,WAAW,CAAC;AAElE;;GAEG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,IAAI,EAAE,kBAAkB,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAYlE;AAED,yCAAyC;AACzC,MAAM,WAAW,kBAAkB,CAAC,CAAC,CAAE,SAAQ,eAAe,CAAC,CAAC,CAAC;IAC7D,6BAA6B;IAC7B,OAAO,EAAE,OAAO,CAAC;IAEjB,oCAAoC;IACpC,GAAG,EAAE,MAAM,CAAC;IAEZ;;;;OAIG;IACH,SAAS,CAAC,CAAC,KAAK,EAAE,CAAC,GAAG,MAAM,CAAC;IAC7B;;;;OAIG;IACH,WAAW,CAAC,CAAC,KAAK,EAAE,MAAM,GAAG,CAAC,GAAG,IAAI,CAAC;CACzC;AAED,0CAA0C;AAC1C,MAAM,WAAW,OAAO,CAAC,CAAC,CAAE,SAAQ,IAAI,CAAC,CAAC,CAAC;IACvC;;;;OAIG;IACH,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC;IACrB,uCAAuC;IACvC,KAAK,IAAI,IAAI,CAAC;IACd,kDAAkD;IAClD,OAAO,IAAI,IAAI,CAAC;CACnB"}

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

@@ -0,0 +1,191 @@
+/**
+ * Rust-like `Result<T, E>` type and error handling utils
+ *
+ * **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>;
+/** A success value */
+export interface Ok<T> {
+    val: T;
+    err?: never;
+}
+/** An error value */
+export interface 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 declare function tryCatch<T, E = Error>(fn: () => T): Result<T, E>;
+/** Wrap an async function with try-catch and return a Promise<Result>. */
+export declare function tryAsync<T, E = Error>(fn: () => Promise<T>): Promise<Result<T, E>>;
+/** Try best effort converting an error to a string */
+export declare function errstr(e: unknown, recursing?: boolean): string;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/result/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0JG;AAEH;;;;GAIG;AACH,MAAM,MAAM,MAAM,CAAC,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC;AAK1C,sBAAsB;AACtB,MAAM,WAAW,EAAE,CAAC,CAAC;IACjB,GAAG,EAAE,CAAC,CAAC;IACP,GAAG,CAAC,EAAE,KAAK,CAAC;CACf;AACD,qBAAqB;AACrB,MAAM,WAAW,GAAG,CAAC,CAAC;IAClB,GAAG,EAAE,CAAC,CAAC;IACP,GAAG,CAAC,EAAE,KAAK,CAAC;CACf;AAED;;;;GAIG;AACH,MAAM,MAAM,IAAI,CAAC,CAAC,IAAI;IAAE,GAAG,CAAC,EAAE,KAAK,CAAC;IAAC,GAAG,CAAC,EAAE,KAAK,CAAA;CAAE,GAAG;IAAE,GAAG,EAAE,CAAC,CAAA;CAAE,CAAC;AAChE,uCAAuC;AACvC,MAAM,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;AAE3C,0DAA0D;AAC1D,wBAAgB,QAAQ,CAAC,CAAC,EAAE,CAAC,GAAG,KAAK,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,CAMhE;AAED,0EAA0E;AAC1E,wBAAsB,QAAQ,CAAC,CAAC,EAAE,CAAC,GAAG,KAAK,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAMxF;AAED,sDAAsD;AACtD,wBAAgB,MAAM,CAAC,CAAC,EAAE,OAAO,EAAE,SAAS,CAAC,EAAE,OAAO,GAAG,MAAM,CAkC9D"}

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

@@ -0,0 +1,30 @@
+/**
+ * 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
+ *
+ * @deprecated unstable API
+ */
+export declare class RwLock<TRead, TWrite extends TRead = TRead> {
+    /**
+     * This is public so inner object can be accessed directly
+     * ONLY SAFE in sync context
+     */
+    inner: TWrite;
+    private readers;
+    private isWriting;
+    private readWaiters;
+    private writeWaiters;
+    constructor(t: TWrite);
+    /** Acquire a read (shared) lock and call fn with the value. Release the lock when fn returns or throws. */
+    scopedRead<R>(fn: (t: TRead) => Promise<R>): Promise<R>;
+    /**
+     * 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)`
+     */
+    scopedWrite<R>(fn: (t: TWrite, setter: (t: TWrite) => TWrite) => Promise<R>): Promise<R>;
+}
+//# sourceMappingURL=RwLock.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"RwLock.d.ts","sourceRoot":"","sources":["../../../../src/sync/RwLock.ts"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AACH,qBAAa,MAAM,CAAC,KAAK,EAAE,MAAM,SAAS,KAAK,GAAG,KAAK;IACnD;;;OAGG;IACI,KAAK,EAAE,MAAM,CAAC;IAErB,OAAO,CAAC,OAAO,CAAa;IAC5B,OAAO,CAAC,SAAS,CAAkB;IACnC,OAAO,CAAC,WAAW,CAAkC;IACrD,OAAO,CAAC,YAAY,CAAkC;gBAE1C,CAAC,EAAE,MAAM;IAIrB,2GAA2G;IAC9F,UAAU,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,KAAK,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAkCpE;;;;OAIG;IACU,WAAW,CAAC,CAAC,EACtB,EAAE,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,GAC7D,OAAO,CAAC,CAAC,CAAC;CA+BhB"}

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

@@ -0,0 +1,112 @@
+import { type AnyFn, type AwaitRet } from "./util.ts";
+/** Factory for batched function. See {@link BatchConstructor} for usage. */
+export declare function batch<TFn extends AnyFn>(args: BatchConstructor<TFn>): (...args: Parameters<TFn>) => Promise<AwaitRet<TFn>>;
+/**
+ * Options to construct a `batch` function
+ *
+ * A batch function is an async event wrapper that allows multiple calls in an interval
+ * to be batched together, and only call the underlying function once.
+ *
+ * Optionally, the output can be unbatched to match the inputs.
+ *
+ * ## Example
+ * The API is a lot like `debounce`, but with an additional `batch` function
+ * and an optional `unbatch` function.
+ * ```typescript
+ * import { batch } from "@pistonite/pure/sync";
+ *
+ * const execute = batch({
+ *     fn: (n: number) => {
+ *         console.log(n);
+ *     },
+ *     interval: 100,
+ *     // batch receives all the inputs and returns a single input
+ *     // here we just sums the inputs
+ *     batch: (args: [number][]): [number] => [args.reduce((acc, [n]) => acc + n, 0)],
+ * });
+ *
+ * await execute(1); // logs 1 immediately
+ * const p1 = execute(2); // will be resolved at 100ms
+ * const p2 = execute(3); // will be resolved at 100ms
+ * await Promise.all([p1, p2]); // logs 5 after 100ms
+ * ```
+ *
+ * ## Unbatching
+ * The optional `unbatch` function allows the output to be unbatched,
+ * so the promises are resolved as if the underlying function is called
+ * directly.
+ *
+ * Note that unbatching is usually slow and not required.
+ *
+ * ```typescript
+ * import { batch } from "@pistonite/pure/sync";
+ *
+ * type Message = {
+ *     id: number;
+ *     payload: string;
+ * }
+ *
+ * const execute = batch({
+ *     fn: (messages: Message[]): Message[] => {
+ *         console.log(messages.length);
+ *         return messages.map((m) => ({
+ *             id: m.id,
+ *             payload: m.payload + "out",
+ *         }));
+ *     },
+ *     batch: (args: [Message[]][]): [Message[]] => {
+ *         const out: Message[] = [];
+ *         for (const [messages] of args) {
+ *             out.push(...messages);
+ *         }
+ *         return [out];
+ *     },
+ *     unbatch: (inputs: [Message[]][], output: Message[]): Message[][] => {
+ *         // not efficient, but just for demonstration
+ *         const idToOutput = new Map();
+ *         for (const o of output) {
+ *             idToOutput.set(o.id, o);
+ *         }
+ *         return inputs.map(([messages]) => {
+ *             return messages.map(({id}) => {
+ *                 return idToOutput.get(m.id)!;
+ *             });
+ *         });
+ *     },
+ *     interval: 100,
+ * });
+ *
+ * const r1 = await execute([{id: 1, payload: "a"}]); // logs 1 immediately
+ * // r1 is [ {id: 1, payload: "aout"} ]
+ *
+ * const p1 = execute([{id: 2, payload: "b"}]); // will be resolved at 100ms
+ * const p2 = execute([{id: 3, payload: "c"}]); // will be resolved at 100ms
+ *
+ * const r2 = await p2; // 2 is logged
+ * // r1 is [ {id: 2, payload: "bout"} ]
+ * const r3 = await p3; // nothing is logged, as it's already resolved
+ * // r2 is [ {id: 3, payload: "cout"} ]
+ *
+ * ```
+ *
+ */
+export interface BatchConstructor<TFn extends AnyFn> {
+    /** Function to be wrapped */
+    fn: TFn;
+    /** Function to batch the inputs across multiple calls */
+    batch: (args: Parameters<TFn>[]) => Parameters<TFn>;
+    /**
+     * If provided, unbatch the output according to the inputs,
+     * so each call receives its own output.
+     *
+     * By default, each input will receive the same output from the batched call
+     */
+    unbatch?: (inputs: Parameters<TFn>[], output: AwaitRet<TFn>) => AwaitRet<TFn>[];
+    /**
+     * Interval between each batched call
+     */
+    interval: number;
+    /** See `debounce` for more information */
+    disregardExecutionTime?: boolean;
+}
+//# sourceMappingURL=batch.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"batch.d.ts","sourceRoot":"","sources":["../../../../src/sync/batch.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,KAAK,EAAmC,KAAK,QAAQ,EAAE,MAAM,WAAW,CAAC;AAEvF,4EAA4E;AAC5E,wBAAgB,KAAK,CAAC,GAAG,SAAS,KAAK,EAAE,IAAI,EAAE,gBAAgB,CAAC,GAAG,CAAC,IAGxD,GAAG,MAAM,UAAU,CAAC,GAAG,CAAC,4BACnC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwFG;AACH,MAAM,WAAW,gBAAgB,CAAC,GAAG,SAAS,KAAK;IAC/C,6BAA6B;IAC7B,EAAE,EAAE,GAAG,CAAC;IACR,yDAAyD;IACzD,KAAK,EAAE,CAAC,IAAI,EAAE,UAAU,CAAC,GAAG,CAAC,EAAE,KAAK,UAAU,CAAC,GAAG,CAAC,CAAC;IAEpD;;;;;OAKG;IACH,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,UAAU,CAAC,GAAG,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,CAAC,GAAG,CAAC,KAAK,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;IAEhF;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAC;IAEjB,0CAA0C;IAC1C,sBAAsB,CAAC,EAAE,OAAO,CAAC;CACpC"}

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pistonite/pure",
-  "version": "0.29.0",
+  "version": "0.29.1",
   "type": "module",
   "description": "Pure TypeScript libraries for my projects",
   "homepage": "https://github.com/Pistonite/pure",