@evolu/common 5.4.8 → 6.0.0

package/dist/src/Number.d.ts

@@ -0,0 +1,42 @@
+import { NonEmptyReadonlyArray } from "./Array.js";
+import { Result } from "./Result.js";
+import { NonNegativeInt, PositiveInt } from "./Type.js";
+import { IsBranded, Predicate, WidenLiteral } from "./Types.js";
+export declare const increment: (n: number) => number;
+export declare const decrement: (n: number) => number;
+/** Clamps a number within a given range. */
+export declare const clamp: (min: number, max: number) => (n: number) => number;
+/**
+ * Creates a predicate that checks if a number is within a range, inclusive.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const isBetween10And20 = isBetween(10, 20);
+ * console.log(isBetween10And20(15)); // true
+ * console.log(isBetween10And20(25)); // false
+ * ```
+ */
+export declare const isBetween: (min: number, max: number) => Predicate<number>;
+/** Returns the minimum value, preserving branded type if applicable. */
+export declare const min: <T extends number>(...values: [T, ...ReadonlyArray<T>]) => IsBranded<T> extends true ? T : WidenLiteral<T>;
+/** Returns the maximum value, preserving branded type if applicable. */
+export declare const max: <T extends number>(...values: [T, ...ReadonlyArray<T>]) => IsBranded<T> extends true ? T : WidenLiteral<T>;
+/**
+ * Divides items into buckets as evenly as possible, ensuring each bucket has at
+ * least the minimum number of items. Returns a success result if the minimum is
+ * met, or an error result with the required number of items if not.
+ *
+ * ### Example
+ *
+ * ```ts
+ * computeBalancedBuckets(10, 3, 2); // Returns ok([4, 7, 10])
+ * computeBalancedBuckets(5, 3, 2); // Returns err(6)
+ * ```
+ */
+export declare const computeBalancedBuckets: (numberOfItems: NonNegativeInt, 
+/** Default: 16 */
+numberOfBuckets?: PositiveInt, 
+/** Default: 2 */
+minNumberOfItemsPerBucket?: PositiveInt) => Result<NonEmptyReadonlyArray<PositiveInt>, PositiveInt>;
+//# sourceMappingURL=Number.d.ts.map

package/dist/src/Number.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Number.d.ts","sourceRoot":"","sources":["../../src/Number.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAEnD,OAAO,EAAW,MAAM,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACxD,OAAO,EAEL,SAAS,EACT,SAAS,EACT,YAAY,EACb,MAAM,YAAY,CAAC;AAEpB,eAAO,MAAM,SAAS,GAAI,GAAG,MAAM,KAAG,MAAe,CAAC;AAEtD,eAAO,MAAM,SAAS,GAAI,GAAG,MAAM,KAAG,MAAe,CAAC;AAEtD,4CAA4C;AAC5C,eAAO,MAAM,KAAK,GACf,KAAK,MAAM,EAAE,KAAK,MAAM,MACxB,GAAG,MAAM,KAAG,MACoB,CAAC;AAEpC;;;;;;;;;;GAUG;AACH,eAAO,MAAM,SAAS,GACnB,KAAK,MAAM,EAAE,KAAK,MAAM,KAAG,SAAS,CAAC,MAAM,CAEd,CAAC;AAEjC,wEAAwE;AACxE,eAAO,MAAM,GAAG,GAAI,CAAC,SAAS,MAAM,EAClC,GAAG,QAAQ,CAAC,CAAC,EAAE,GAAG,aAAa,CAAC,CAAC,CAAC,CAAC,KAClC,SAAS,CAAC,CAAC,CAAC,SAAS,IAAI,GAAG,CAAC,GAAG,YAAY,CAAC,CAAC,CACa,CAAC;AAE/D,wEAAwE;AACxE,eAAO,MAAM,GAAG,GAAI,CAAC,SAAS,MAAM,EAClC,GAAG,QAAQ,CAAC,CAAC,EAAE,GAAG,aAAa,CAAC,CAAC,CAAC,CAAC,KAClC,SAAS,CAAC,CAAC,CAAC,SAAS,IAAI,GAAG,CAAC,GAAG,YAAY,CAAC,CAAC,CACa,CAAC;AAE/D;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,sBAAsB,GACjC,eAAe,cAAc;AAE7B,kBAAkB;AAClB,kBAAwB,WAAW;AAEnC,iBAAiB;AACjB,4BAAiC,WAAW,KAC3C,MAAM,CAAC,qBAAqB,CAAC,WAAW,CAAC,EAAE,WAAW,CAoBxD,CAAC"}

package/dist/src/Number.js

@@ -0,0 +1,55 @@
+import { assertNonEmptyReadonlyArray } from "./Assert.js";
+import { err, ok } from "./Result.js";
+export const increment = (n) => n + 1;
+export const decrement = (n) => n - 1;
+/** Clamps a number within a given range. */
+export const clamp = (min, max) => (n) => Math.min(Math.max(n, min), max);
+/**
+ * Creates a predicate that checks if a number is within a range, inclusive.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const isBetween10And20 = isBetween(10, 20);
+ * console.log(isBetween10And20(15)); // true
+ * console.log(isBetween10And20(25)); // false
+ * ```
+ */
+export const isBetween = (min, max) => (value) => value >= min && value <= max;
+/** Returns the minimum value, preserving branded type if applicable. */
+export const min = (...values) => values.reduce((a, b) => (a < b ? a : b));
+/** Returns the maximum value, preserving branded type if applicable. */
+export const max = (...values) => values.reduce((a, b) => (a > b ? a : b));
+/**
+ * Divides items into buckets as evenly as possible, ensuring each bucket has at
+ * least the minimum number of items. Returns a success result if the minimum is
+ * met, or an error result with the required number of items if not.
+ *
+ * ### Example
+ *
+ * ```ts
+ * computeBalancedBuckets(10, 3, 2); // Returns ok([4, 7, 10])
+ * computeBalancedBuckets(5, 3, 2); // Returns err(6)
+ * ```
+ */
+export const computeBalancedBuckets = (numberOfItems, 
+/** Default: 16 */
+numberOfBuckets = 16, 
+/** Default: 2 */
+minNumberOfItemsPerBucket = 2) => {
+    const minRequiredItems = numberOfBuckets * minNumberOfItemsPerBucket;
+    if (numberOfItems < minRequiredItems)
+        return err(minRequiredItems);
+    const indexes = [];
+    const itemsPerBucket = Math.floor(numberOfItems / numberOfBuckets);
+    const extraItems = numberOfItems % numberOfBuckets;
+    let bucketBoundary = 0;
+    for (let i = 0; i < numberOfBuckets; i++) {
+        const hasExtraItem = i < extraItems;
+        const itemsInThisBucket = itemsPerBucket + (hasExtraItem ? 1 : 0);
+        bucketBoundary += itemsInThisBucket;
+        indexes.push(bucketBoundary);
+    }
+    assertNonEmptyReadonlyArray(indexes);
+    return ok(indexes);
+};

package/dist/src/Object.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Checks if a value is a plain object (e.g., created with `{}` or `Object`).
+ *
+ * ### Example
+ *
+ * ```ts
+ * isPlainObject({}); // true
+ * isPlainObject(new Date()); // false
+ * isPlainObject([]); // false
+ * isPlainObject(null); // false
+ * ```
+ */
+export declare const isPlainObject: (value: unknown) => value is Record<string, unknown>;
+/**
+ * A read-only `Record<K, V>` with `K extends keyof any` to preserve branded key
+ * types (e.g., in {@link mapObject}).
+ */
+export type ReadonlyRecord<K extends keyof any, V> = Readonly<Record<K, V>>;
+type StringKeyOf<T> = Extract<keyof T, string>;
+/**
+ * Converts a record to entries, preserving branded string key types (e.g.,
+ * `type Id = 'id' & string`) via `StringKeyOf<T>`, unlike `Object.entries`
+ * which widens keys to `string`.
+ */
+export declare const objectToEntries: <T extends Record<string, any>>(record: T) => Array<[StringKeyOf<T>, T[StringKeyOf<T>]]>;
+/**
+ * Maps a `ReadonlyRecord<K, V>` to a new `ReadonlyRecord<K, U>`, preserving
+ * branded key types (e.g., `type Id = 'id' & string`) lost by `Object.entries`.
+ * Uses `K extends string` for precision.
+ */
+export declare const mapObject: <K extends string, V, U>(record: ReadonlyRecord<K, V>, fn: (value: V, key: K) => U) => ReadonlyRecord<K, U>;
+/** Conditionally excludes a property from an object. */
+export declare const excludeProp: <T extends object, K extends keyof T>(obj: T, prop: K, condition?: boolean) => typeof condition extends true ? T : Omit<T, K>;
+export {};
+//# sourceMappingURL=Object.d.ts.map

package/dist/src/Object.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Object.d.ts","sourceRoot":"","sources":["../../src/Object.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,aAAa,GACxB,OAAO,OAAO,KACb,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAC2B,CAAC;AAE9D;;;GAGG;AACH,MAAM,MAAM,cAAc,CAAC,CAAC,SAAS,MAAM,GAAG,EAAE,CAAC,IAAI,QAAQ,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;AAG5E,KAAK,WAAW,CAAC,CAAC,IAAI,OAAO,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,CAAC;AAE/C;;;;GAIG;AACH,eAAO,MAAM,eAAe,GAAI,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC3D,QAAQ,CAAC,KACR,KAAK,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,CAC0B,CAAC;AAEvE;;;;GAIG;AACH,eAAO,MAAM,SAAS,GAAI,CAAC,SAAS,MAAM,EAAE,CAAC,EAAE,CAAC,EAC9C,QAAQ,cAAc,CAAC,CAAC,EAAE,CAAC,CAAC,EAC5B,IAAI,CAAC,KAAK,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,KAAK,CAAC,KAC1B,cAAc,CAAC,CAAC,EAAE,CAAC,CAMK,CAAC;AAE5B,wDAAwD;AACxD,eAAO,MAAM,WAAW,GAAI,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,MAAM,CAAC,EAC7D,KAAK,CAAC,EACN,MAAM,CAAC,EACP,YAAY,OAAO,KAClB,OAAO,SAAS,SAAS,IAAI,GAAG,CAAC,GAAG,IAAI,CAAC,CAAC,EAAE,CAAC,CAM/C,CAAC"}

package/dist/src/Object.js

@@ -0,0 +1,36 @@
+/**
+ * Checks if a value is a plain object (e.g., created with `{}` or `Object`).
+ *
+ * ### Example
+ *
+ * ```ts
+ * isPlainObject({}); // true
+ * isPlainObject(new Date()); // false
+ * isPlainObject([]); // false
+ * isPlainObject(null); // false
+ * ```
+ */
+export const isPlainObject = (value) => Object.prototype.toString.call(value) === "[object Object]";
+/**
+ * Converts a record to entries, preserving branded string key types (e.g.,
+ * `type Id = 'id' & string`) via `StringKeyOf<T>`, unlike `Object.entries`
+ * which widens keys to `string`.
+ */
+export const objectToEntries = (record) => Object.entries(record);
+/**
+ * Maps a `ReadonlyRecord<K, V>` to a new `ReadonlyRecord<K, U>`, preserving
+ * branded key types (e.g., `type Id = 'id' & string`) lost by `Object.entries`.
+ * Uses `K extends string` for precision.
+ */
+export const mapObject = (record, fn) => Object.fromEntries(Object.entries(record).map(([key, value]) => [
+    key,
+    fn(value, key),
+]));
+/** Conditionally excludes a property from an object. */
+export const excludeProp = (obj, prop, condition) => {
+    if (condition) {
+        return { ...obj };
+    }
+    const { [prop]: _, ...rest } = obj;
+    return rest;
+};

package/dist/src/Order.d.ts

@@ -0,0 +1,90 @@
+/**
+ * 🔢
+ *
+ * @module
+ */
+/**
+ * Compares two values of type `A` and returns their ordering.
+ *
+ * Ordering functions start with an 'order' prefix, e.g., `orderNumber`.
+ *
+ * - Returns `-1` if `x` is less than `y`.
+ * - Returns `0` if `x` is equal to `y`.
+ * - Returns `1` if `x` is greater than `y`.
+ */
+export type Order<in A> = (x: A, y: A) => Ordering;
+/**
+ * A type representing the result of an ordering operation.
+ *
+ * Compatible with the return values expected by `Array.prototype.sort`.
+ */
+export type Ordering = -1 | 0 | 1;
+/**
+ * Creates an ordering function from a "less than" comparator.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const orderNumber = createOrder<number>((x, y) => x < y);
+ * expect(orderNumber(1, 2)).toEqual(-1);
+ * expect(orderNumber(2, 1)).toEqual(1);
+ * expect(orderNumber(1, 1)).toEqual(0);
+ * ```
+ */
+export declare const createOrder: <A>(isLessThan: (x: A, y: A) => boolean) => Order<A>;
+/**
+ * Returns an order that reverses the order of the given order.
+ *
+ * ### Example
+ *
+ * ```ts
+ * reverseOrder(orderNumber)(1, 2); // 1
+ * reverseOrder(orderNumber)(2, 1); // -1
+ * reverseOrder(orderNumber)(1, 1); // 0
+ * ```
+ */
+export declare const reverseOrder: <A>(order: Order<A>) => Order<A>;
+/**
+ * An order for `string` values in ascending order.
+ *
+ * ### Example
+ *
+ * ```ts
+ * orderString("a", "b"); // -1
+ * orderString("b", "a"); // 1
+ * orderString("a", "a"); // 0
+ * ["c", "b", "a"].toSorted(orderString); // ["a", "b", "c"]
+ * ```
+ */
+export declare const orderString: Order<string>;
+/**
+ * An order for numbers in ascending order.
+ *
+ * ### Example
+ *
+ * ```ts
+ * orderNumber(1, 2); // -1
+ * orderNumber(2, 1); // 1
+ * orderNumber(1, 1); // 0
+ * [2, 1, 3].toSorted(orderNumber); // [1, 2, 3]
+ * reverseOrder(orderNumber)(1, 2); // 1
+ * reverseOrder(orderNumber)(2, 1); // -1
+ * reverseOrder(orderNumber)(1, 1); // 0
+ * ```
+ */
+export declare const orderNumber: Order<number>;
+/**
+ * An order for bigints in ascending order.
+ *
+ * ### Example
+ *
+ * ```ts
+ * orderBigInt(1n, 2n); // -1
+ * orderBigInt(2n, 1n); // 1
+ * orderBigInt(1n, 1n); // 0
+ * [2n, 1n, 3n].toSorted(orderBigInt); // [1n, 2n, 3n]
+ * ```
+ */
+export declare const orderBigInt: Order<bigint>;
+export declare const orderUint8Array: Order<globalThis.Uint8Array>;
+//# sourceMappingURL=Order.d.ts.map

package/dist/src/Order.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Order.d.ts","sourceRoot":"","sources":["../../src/Order.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;;;GAQG;AACH,MAAM,MAAM,KAAK,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,KAAK,QAAQ,CAAC;AAEnD;;;;GAIG;AACH,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;AAElC;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,WAAW,GACrB,CAAC,EAAE,YAAY,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,KAAK,OAAO,KAAG,KAAK,CAAC,CAAC,CAER,CAAC;AAE5C;;;;;;;;;;GAUG;AACH,eAAO,MAAM,YAAY,GACtB,CAAC,EAAE,OAAO,KAAK,CAAC,CAAC,CAAC,KAAG,KAAK,CAAC,CAAC,CAEhB,CAAC;AAEhB;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,WAAW,EAAE,KAAK,CAAC,MAAM,CAAgC,CAAC;AAEvE;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,WAAW,eAAuC,CAAC;AAEhE;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,WAAW,eAAuC,CAAC;AAEhE,eAAO,MAAM,eAAe,EAAE,KAAK,CAAC,UAAU,CAAC,UAAU,CAUxD,CAAC"}

package/dist/src/Order.js

@@ -0,0 +1,85 @@
+/**
+ * 🔢
+ *
+ * @module
+ */
+/**
+ * Creates an ordering function from a "less than" comparator.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const orderNumber = createOrder<number>((x, y) => x < y);
+ * expect(orderNumber(1, 2)).toEqual(-1);
+ * expect(orderNumber(2, 1)).toEqual(1);
+ * expect(orderNumber(1, 1)).toEqual(0);
+ * ```
+ */
+export const createOrder = (isLessThan) => (x, y) => x === y ? 0 : isLessThan(x, y) ? -1 : 1;
+/**
+ * Returns an order that reverses the order of the given order.
+ *
+ * ### Example
+ *
+ * ```ts
+ * reverseOrder(orderNumber)(1, 2); // 1
+ * reverseOrder(orderNumber)(2, 1); // -1
+ * reverseOrder(orderNumber)(1, 1); // 0
+ * ```
+ */
+export const reverseOrder = (order) => (a, b) => order(b, a);
+/**
+ * An order for `string` values in ascending order.
+ *
+ * ### Example
+ *
+ * ```ts
+ * orderString("a", "b"); // -1
+ * orderString("b", "a"); // 1
+ * orderString("a", "a"); // 0
+ * ["c", "b", "a"].toSorted(orderString); // ["a", "b", "c"]
+ * ```
+ */
+export const orderString = createOrder((a, b) => a < b);
+/**
+ * An order for numbers in ascending order.
+ *
+ * ### Example
+ *
+ * ```ts
+ * orderNumber(1, 2); // -1
+ * orderNumber(2, 1); // 1
+ * orderNumber(1, 1); // 0
+ * [2, 1, 3].toSorted(orderNumber); // [1, 2, 3]
+ * reverseOrder(orderNumber)(1, 2); // 1
+ * reverseOrder(orderNumber)(2, 1); // -1
+ * reverseOrder(orderNumber)(1, 1); // 0
+ * ```
+ */
+export const orderNumber = createOrder((a, b) => a < b);
+/**
+ * An order for bigints in ascending order.
+ *
+ * ### Example
+ *
+ * ```ts
+ * orderBigInt(1n, 2n); // -1
+ * orderBigInt(2n, 1n); // 1
+ * orderBigInt(1n, 1n); // 0
+ * [2n, 1n, 3n].toSorted(orderBigInt); // [1n, 2n, 3n]
+ * ```
+ */
+export const orderBigInt = createOrder((a, b) => a < b);
+export const orderUint8Array = (a, b) => {
+    if (a.byteLength > b.byteLength)
+        return 1;
+    if (a.byteLength < b.byteLength)
+        return -1;
+    for (let i = 0; i < a.byteLength; i++) {
+        if (a[i] < b[i])
+            return -1;
+        if (a[i] > b[i])
+            return 1;
+    }
+    return 0;
+};

package/dist/src/Promise.d.ts

@@ -0,0 +1,180 @@
+import { Result } from "./Result.js";
+import { Predicate } from "./Types.js";
+/**
+ * Helper function to delay execution for a specified number of milliseconds.
+ *
+ * ### Example
+ *
+ * ```ts
+ * await wait(10);
+ * ```
+ */
+export declare const wait: (ms: number) => Promise<Result<void, never>>;
+/** Options for configuring retry behavior. */
+export interface RetryOptions<E> {
+    /**
+     * Maximum number of retry attempts after the initial attempt (default: 3).
+     * For example, with maxRetries = 3, the function will be called up to 4 times
+     * (1 initial attempt + 3 retries).
+     */
+    maxRetries?: number;
+    /**
+     * Initial delay between retry attempts in milliseconds (default: 100). This
+     * is the delay after the first failed attempt. Subsequent delays increase
+     * exponentially according to the factor option.
+     */
+    initialDelay?: number;
+    /**
+     * Maximum delay between retry attempts in milliseconds (default: 10000). This
+     * caps the exponential backoff to prevent extremely long delays after many
+     * retries.
+     */
+    maxDelay?: number;
+    /**
+     * Multiplier that determines how quickly the delay increases (default: 2).
+     * With the default value, each successive delay is twice as long as the
+     * previous one (e.g., 100ms, 200ms, 400ms, 800ms, etc).
+     */
+    factor?: number;
+    /**
+     * Random jitter factor between 0 and 1 (default: 0.1). Adds randomness to
+     * delay times to prevent retry storms in distributed systems.
+     */
+    jitter?: number;
+    /**
+     * Optional AbortSignal to cancel retries. If the signal is aborted, the retry
+     * operation stops and returns a RetryAbortError.
+     */
+    signal?: AbortSignal;
+    /**
+     * Optional predicate to determine if an error should be retried. Returns true
+     * if the error is retryable, false otherwise. This allows selectively
+     * retrying only certain types of errors. By default, all errors are
+     * considered retryable.
+     */
+    retryable?: Predicate<E>;
+    /**
+     * Optional callback called before each retry attempt. Receives the error that
+     * caused the retry, the current attempt number (starting at 1), and the delay
+     * in milliseconds before the next attempt.
+     */
+    onRetry?: (error: E, attempt: number, delay: number) => void;
+}
+/** Error representing a retry operation that failed after multiple attempts. */
+export interface RetryError<E> {
+    readonly type: "RetryError";
+    /** The original error that caused the retry to fail */
+    readonly cause: E;
+    /** Number of retry attempts made */
+    readonly attempts: number;
+}
+/** Error representing a retry operation that was aborted. */
+export interface RetryAbortError {
+    readonly type: "RetryAbortError";
+    readonly abortedBeforeExecution: boolean;
+}
+/**
+ * Executes a function with retry logic using exponential backoff and jitter.
+ *
+ * ### Example with Result-based API
+ *
+ * ```ts
+ * interface ApiError {
+ *   type: "ApiError";
+ *   statusCode: number;
+ * }
+ *
+ * const fetchData = async (
+ *   url: string,
+ * ): Promise<Result<Data, ApiError>> => {
+ *   // Implementation that returns Result
+ * };
+ *
+ * const result = await retry(
+ *   async () => fetchData("https://api.example.com/data"),
+ *   {
+ *     maxRetries: 5,
+ *     initialDelay: 200,
+ *     // Only retry on specific status codes
+ *     retryable: (error) =>
+ *       error.type === "ApiError" && [429, 503].includes(error.statusCode),
+ *   },
+ * );
+ *
+ * if (!result.ok) {
+ *   if (result.error.type === "RetryAbortError") {
+ *     console.log("Operation was aborted");
+ *   } else {
+ *     console.log(`Failed after ${result.error.attempts} attempts`);
+ *   }
+ *   return;
+ * }
+ *
+ * // Use result.value
+ * ```
+ *
+ * ### Example with tryAsync for exception-based API
+ *
+ * ```ts
+ * interface FetchError {
+ *   type: "FetchError";
+ *   message: string;
+ * }
+ *
+ * const controller = new AbortController();
+ *
+ * const result = await retry(
+ *   async () =>
+ *     tryAsync(
+ *       async () => {
+ *         const response = await fetch("https://api.example.com/data", {
+ *           signal: controller.signal,
+ *         });
+ *
+ *         if (!response.ok) {
+ *           throw new Error(`HTTP error ${response.status}`);
+ *         }
+ *
+ *         return await response.json();
+ *       },
+ *       (error): FetchError => ({
+ *         type: "FetchError",
+ *         message: String(error),
+ *       }),
+ *     ),
+ *   {
+ *     maxRetries: 3,
+ *     signal: controller.signal,
+ *   },
+ * );
+ * ```
+ *
+ * ## HTTP Request Recommendations
+ *
+ * For HTTP requests, configure the `retryable` option to only retry on
+ * appropriate errors:
+ *
+ * - **DO retry**: 429 (Too Many Requests), 503 (Service Unavailable), network
+ *   errors
+ * - **DON'T retry**: 4xx client errors (except 429), most 5xx server errors
+ */
+export declare const retry: <T, E>(fn: () => Promise<Result<T, E>>, options?: RetryOptions<E>) => Promise<Result<T, RetryError<E> | RetryAbortError>>;
+export interface TimeoutError {
+    readonly type: "TimeoutError";
+    readonly timeoutMs: number;
+}
+/**
+ * Wraps an async function with a timeout, returning {@link Result} that fails
+ * with {@link TimeoutError} if the timeout is exceeded. The provided function
+ * must accept an AbortSignal and return a Result.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const fetchWithTimeout = () =>
+ *   withTimeout((signal) => fetch("url", signal), 5000);
+ * const result = await retry(fetchWithTimeout, { maxRetries: 3 });
+ * ```
+ */
+export declare const withTimeout: <T, E>(fn: (signal: AbortSignal) => Promise<Result<T, E>>, timeoutMs: number) => Promise<Result<T, E | TimeoutError>>;
+//# sourceMappingURL=Promise.d.ts.map

package/dist/src/Promise.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Promise.d.ts","sourceRoot":"","sources":["../../src/Promise.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,EAAW,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAEvC;;;;;;;;GAQG;AACH,eAAO,MAAM,IAAI,GAAI,IAAI,MAAM,KAAG,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,CAK1D,CAAC;AAEJ,8CAA8C;AAC9C,MAAM,WAAW,YAAY,CAAC,CAAC;IAC7B;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;;OAGG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;IAErB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC;IAEzB;;;;OAIG;IACH,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;CAC9D;AAED,gFAAgF;AAChF,MAAM,WAAW,UAAU,CAAC,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,uDAAuD;IACvD,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;IAClB,oCAAoC;IACpC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,6DAA6D;AAC7D,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;IACjC,QAAQ,CAAC,sBAAsB,EAAE,OAAO,CAAC;CAC1C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoFG;AACH,eAAO,MAAM,KAAK,GAAU,CAAC,EAAE,CAAC,EAC9B,IAAI,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAC/B,UAAS,YAAY,CAAC,CAAC,CAAM,KAC5B,OAAO,CAAC,MAAM,CAAC,CAAC,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,eAAe,CAAC,CA2EpD,CAAC;AAEF,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAC9B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,WAAW,GAAU,CAAC,EAAE,CAAC,EACpC,IAAI,CAAC,MAAM,EAAE,WAAW,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAClD,WAAW,MAAM,KAChB,OAAO,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,GAAG,YAAY,CAAC,CAerC,CAAC"}