@evolu/common 5.4.7 → 6.0.0

package/dist/src/Promise.js

@@ -0,0 +1,176 @@
+import { constTrue } from "./Function.js";
+import { err, ok } from "./Result.js";
+/**
+ * Helper function to delay execution for a specified number of milliseconds.
+ *
+ * ### Example
+ *
+ * ```ts
+ * await wait(10);
+ * ```
+ */
+export const wait = (ms) => new Promise((resolve) => setTimeout(() => {
+    resolve(ok());
+}, ms));
+/**
+ * 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 const retry = async (fn, options = {}) => {
+    const { maxRetries = 3, initialDelay = 100, maxDelay = 10000, factor = 2, jitter = 0.1, signal, retryable = constTrue, onRetry, } = options;
+    let attempt = 0;
+    if (signal?.aborted) {
+        return err({ type: "RetryAbortError", abortedBeforeExecution: true });
+    }
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+    while (true) {
+        const result = await fn();
+        if (result.ok) {
+            return result;
+        }
+        attempt += 1;
+        if (attempt > maxRetries || !retryable(result.error)) {
+            return err({
+                type: "RetryError",
+                cause: result.error,
+                attempts: attempt,
+            });
+        }
+        // Calculate delay with exponential backoff
+        const exponentialDelay = initialDelay * Math.pow(factor, attempt);
+        const cappedDelay = Math.min(exponentialDelay, maxDelay);
+        // Apply jitter to prevent thundering herd problem
+        const randomFactor = 1 - jitter + Math.random() * jitter * 2;
+        const delay = Math.floor(cappedDelay * randomFactor);
+        if (onRetry) {
+            onRetry(result.error, attempt, delay);
+        }
+        if (signal?.aborted) {
+            return err({ type: "RetryAbortError", abortedBeforeExecution: false });
+        }
+        // Wait with abort support
+        if (signal) {
+            const abortPromise = new Promise((resolve) => {
+                const onAbort = () => {
+                    resolve(err({ type: "RetryAbortError", abortedBeforeExecution: false }));
+                };
+                signal.addEventListener("abort", onAbort, { once: true });
+            });
+            const delayPromise = wait(delay);
+            const raceResult = await Promise.race([abortPromise, delayPromise]);
+            if (!raceResult.ok) {
+                return raceResult;
+            }
+        }
+        else {
+            await wait(delay);
+        }
+    }
+};
+/**
+ * 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 const withTimeout = async (fn, timeoutMs) => {
+    const controller = new AbortController();
+    const signal = controller.signal;
+    const timeoutId = setTimeout(() => {
+        controller.abort();
+    }, timeoutMs);
+    const result = await fn(signal);
+    clearTimeout(timeoutId);
+    if (signal.aborted) {
+        return err({ type: "TimeoutError", timeoutMs });
+    }
+    return result;
+};

package/dist/src/Random.d.ts

@@ -0,0 +1,52 @@
+/**
+ * 🎲
+ *
+ * @module
+ */
+import { Random as RandomLib } from "random";
+/**
+ * A simple wrapper around Math.random(). Most apps need only this. For more
+ * complex needs check {@link RandomLibDep}.
+ *
+ * ### Example
+ *
+ * ```ts
+ * // For apps
+ * const random = createRandom();
+ * random.next();
+ *
+ * // For tests
+ * const random = createRandomWithSeed("test");
+ * random.next();
+ * ```
+ */
+export interface Random {
+    /** Returns a floating point number in [0, 1). Just like Math.random(). */
+    next: () => number;
+}
+export interface RandomDep {
+    random: Random;
+}
+/** Creates a {@link Random} using Math.random(). */
+export declare const createRandom: () => Random;
+/**
+ * Creates {@link Random} using {@link RandomLibDep} with a seed which is useful
+ * for tests.
+ */
+export declare const createRandomWithSeed: (seed: string) => Random;
+/**
+ * A random number generator using the NPM `random` package dependency.
+ *
+ * https://github.com/transitive-bullshit/random
+ */
+export interface RandomLibDep {
+    random: RandomLib;
+}
+/** Creates a `RandomLib` using the NPM `random` package. */
+export declare const createRandomLib: () => RandomLib;
+/**
+ * Creates {@link RandomLibDep} using the NPM `random` package with a seed which
+ * is useful for tests.
+ */
+export declare const createRandomLibWithSeed: (seed: string) => RandomLibDep;
+//# sourceMappingURL=Random.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Random.d.ts","sourceRoot":"","sources":["../../src/Random.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,MAAM,IAAI,SAAS,EAAE,MAAM,QAAQ,CAAC;AAE7C;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,MAAM;IACrB,0EAA0E;IAC1E,IAAI,EAAE,MAAM,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,oDAAoD;AACpD,eAAO,MAAM,YAAY,QAAO,MAE9B,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,oBAAoB,GAAI,MAAM,MAAM,KAAG,MAKnD,CAAC;AAEF;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,SAAS,CAAC;CACnB;AAED,4DAA4D;AAC5D,eAAO,MAAM,eAAe,QAAO,SAA4B,CAAC;AAEhE;;;GAGG;AACH,eAAO,MAAM,uBAAuB,GAAI,MAAM,MAAM,KAAG,YAErD,CAAC"}

package/dist/src/Random.js

@@ -0,0 +1,29 @@
+/**
+ * 🎲
+ *
+ * @module
+ */
+import { Random as RandomLib } from "random";
+/** Creates a {@link Random} using Math.random(). */
+export const createRandom = () => ({
+    next: () => Math.random(),
+});
+/**
+ * Creates {@link Random} using {@link RandomLibDep} with a seed which is useful
+ * for tests.
+ */
+export const createRandomWithSeed = (seed) => {
+    const random = new RandomLib(seed);
+    return {
+        next: () => random.next(),
+    };
+};
+/** Creates a `RandomLib` using the NPM `random` package. */
+export const createRandomLib = () => new RandomLib();
+/**
+ * Creates {@link RandomLibDep} using the NPM `random` package with a seed which
+ * is useful for tests.
+ */
+export const createRandomLibWithSeed = (seed) => ({
+    random: new RandomLib(seed),
+});

package/dist/src/Ref.d.ts

@@ -0,0 +1,40 @@
+/**
+ * `Ref` provides a simple API to hold and update a value, similar to a "ref" in
+ * functional programming or React. It exposes methods to get, set, and modify
+ * the current state.
+ *
+ * Use a Ref instead of a variable when you want to pass state around as an
+ * object or update it in a controlled way. If you need subscriptions, see
+ * {@link Store}.
+ *
+ * Updating in a controlled way means all changes go through specific methods
+ * (`set` or `modify`), making state updates predictable and easy to track.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const count = createRef(0);
+ * count.set(1);
+ * count.modify((n) => n + 1);
+ * console.log(count.get()); // 2
+ * ```
+ *
+ * ### Example of using Ref as a dependency
+ *
+ * ```ts
+ * interface CounterRefDep {
+ *   readonly counterRef: Ref<number>;
+ * }
+ * ```
+ */
+export interface Ref<T> {
+    /** Returns the current state. */
+    readonly get: () => T;
+    /** Sets the state. */
+    readonly set: (state: T) => void;
+    /** Modifies the state using an updater function. */
+    readonly modify: (updater: (current: T) => T) => void;
+}
+/** Creates a {@link Ref} with the given initial state. */
+export declare const createRef: <T>(initialState: T) => Ref<T>;
+//# sourceMappingURL=Ref.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Ref.d.ts","sourceRoot":"","sources":["../../src/Ref.ts"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,WAAW,GAAG,CAAC,CAAC;IACpB,iCAAiC;IACjC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;IAEtB,sBAAsB;IACtB,QAAQ,CAAC,GAAG,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,CAAC;IAEjC,oDAAoD;IACpD,QAAQ,CAAC,MAAM,EAAE,CAAC,OAAO,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,CAAC,KAAK,IAAI,CAAC;CACvD;AAED,0DAA0D;AAC1D,eAAO,MAAM,SAAS,GAAI,CAAC,EAAE,cAAc,CAAC,KAAG,GAAG,CAAC,CAAC,CAcnD,CAAC"}

package/dist/src/Ref.js

@@ -0,0 +1,13 @@
+/** Creates a {@link Ref} with the given initial state. */
+export const createRef = (initialState) => {
+    let currentState = initialState;
+    return {
+        get: () => currentState,
+        set: (state) => {
+            currentState = state;
+        },
+        modify: (updater) => {
+            currentState = updater(currentState);
+        },
+    };
+};