@pistonite/pure 0.28.0 → 0.29.1

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2024-2025 Michael
+Copyright (c) 2024-2026 Michael
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,8 +1,27 @@
 # pure
 
-Pure TypeScript utility library for browsers.
+Pure TypeScript utility libraries for my projects
 
-These are meant to be only used by my projects so they
-are not stable by any means. However, feel free to use or reference them.
+## Documentation
 
-See [GitHub](https://github.com/Pistonite/pure) for more information.
+https://pure.pistonite.dev
+
+## Setup
+
+Install the package from NPM
+
+```bash
+npm install @pistonite/pure
+```
+
+For React hooks
+
+```bash
+npm install @pistonite/pure-react
+```
+
+Import the things you need
+
+```typescript
+import type { Result } from "@pistonite/pure/result";
+```

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"}