@evolu/common 5.4.8 → 6.0.0

package/src/Number.ts

@@ -0,0 +1,90 @@
+import { NonEmptyReadonlyArray } from "./Array.js";
+import { assertNonEmptyReadonlyArray } from "./Assert.js";
+import { err, ok, Result } from "./Result.js";
+import { NonNegativeInt, PositiveInt } from "./Type.js";
+import {
+  IntentionalNever,
+  IsBranded,
+  Predicate,
+  WidenLiteral,
+} from "./Types.js";
+
+export const increment = (n: number): number => n + 1;
+
+export const decrement = (n: number): number => n - 1;
+
+/** Clamps a number within a given range. */
+export const clamp =
+  (min: number, max: number) =>
+  (n: number): number =>
+    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: number, max: number): Predicate<number> =>
+  (value) =>
+    value >= min && value <= max;
+
+/** Returns the minimum value, preserving branded type if applicable. */
+export const min = <T extends number>(
+  ...values: [T, ...ReadonlyArray<T>]
+): IsBranded<T> extends true ? T : WidenLiteral<T> =>
+  values.reduce((a, b) => (a < b ? a : b)) as IntentionalNever;
+
+/** Returns the maximum value, preserving branded type if applicable. */
+export const max = <T extends number>(
+  ...values: [T, ...ReadonlyArray<T>]
+): IsBranded<T> extends true ? T : WidenLiteral<T> =>
+  values.reduce((a, b) => (a > b ? a : b)) as IntentionalNever;
+
+/**
+ * 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: NonNegativeInt,
+
+  /** Default: 16 */
+  numberOfBuckets = 16 as PositiveInt,
+
+  /** Default: 2 */
+  minNumberOfItemsPerBucket = 2 as PositiveInt,
+): Result<NonEmptyReadonlyArray<PositiveInt>, PositiveInt> => {
+  const minRequiredItems = numberOfBuckets * minNumberOfItemsPerBucket;
+
+  if (numberOfItems < minRequiredItems)
+    return err(minRequiredItems as PositiveInt);
+
+  const indexes: Array<PositiveInt> = [];
+  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 as PositiveInt);
+  }
+
+  assertNonEmptyReadonlyArray(indexes);
+  return ok(indexes);
+};

package/src/Object.ts

@@ -0,0 +1,64 @@
+/**
+ * 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: unknown,
+): value is Record<string, unknown> =>
+  Object.prototype.toString.call(value) === "[object Object]";
+
+/**
+ * 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>>;
+
+// A helper type to remove symbol keys (e.g for branded objects).
+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 const objectToEntries = <T extends Record<string, any>>(
+  record: T,
+): Array<[StringKeyOf<T>, T[StringKeyOf<T>]]> =>
+  Object.entries(record) as 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 const mapObject = <K extends string, V, U>(
+  record: ReadonlyRecord<K, V>,
+  fn: (value: V, key: K) => U,
+): ReadonlyRecord<K, U> =>
+  Object.fromEntries(
+    Object.entries(record).map(([key, value]) => [
+      key,
+      fn(value as V, key as K),
+    ]),
+  ) as ReadonlyRecord<K, U>;
+
+/** Conditionally excludes a property from an object. */
+export const excludeProp = <T extends object, K extends keyof T>(
+  obj: T,
+  prop: K,
+  condition?: boolean,
+): typeof condition extends true ? T : Omit<T, K> => {
+  if (condition) {
+    return { ...obj };
+  }
+  const { [prop]: _, ...rest } = obj;
+  return rest;
+};

package/src/Order.ts

@@ -0,0 +1,113 @@
+/**
+ * 🔢
+ *
+ * @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 const createOrder =
+  <A>(isLessThan: (x: A, y: A) => boolean): Order<A> =>
+  (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 =
+  <A>(order: Order<A>): Order<A> =>
+  (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: Order<string> = 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<number>((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<bigint>((a, b) => a < b);
+
+export const orderUint8Array: Order<globalThis.Uint8Array> = (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/src/Promise.ts

@@ -0,0 +1,295 @@
+import { constTrue } from "./Function.js";
+import { Result, err, ok } 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 const wait = (ms: number): Promise<Result<void, never>> =>
+  new Promise((resolve) =>
+    setTimeout(() => {
+      resolve(ok());
+    }, ms),
+  );
+
+/** 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 const retry = async <T, E>(
+  fn: () => Promise<Result<T, E>>,
+  options: RetryOptions<E> = {},
+): Promise<Result<T, RetryError<E> | RetryAbortError>> => {
+  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<Result<never, RetryAbortError>>(
+        (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);
+    }
+  }
+};
+
+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 const withTimeout = async <T, E>(
+  fn: (signal: AbortSignal) => Promise<Result<T, E>>,
+  timeoutMs: number,
+): Promise<Result<T, E | TimeoutError>> => {
+  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/src/Random.ts

@@ -0,0 +1,68 @@
+/**
+ * 🎲
+ *
+ * @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 const createRandom = (): Random => ({
+  next: () => Math.random(),
+});
+
+/**
+ * Creates {@link Random} using {@link RandomLibDep} with a seed which is useful
+ * for tests.
+ */
+export const createRandomWithSeed = (seed: string): Random => {
+  const random = new RandomLib(seed);
+  return {
+    next: () => random.next(),
+  };
+};
+
+/**
+ * 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 const createRandomLib = (): RandomLib => new RandomLib();
+
+/**
+ * Creates {@link RandomLibDep} using the NPM `random` package with a seed which
+ * is useful for tests.
+ */
+export const createRandomLibWithSeed = (seed: string): RandomLibDep => ({
+  random: new RandomLib(seed),
+});

package/src/Ref.ts

@@ -0,0 +1,63 @@
+/**
+ * A mutable reference for managing state
+ *
+ * @module
+ */
+import type { Store } from "./Store.js";
+
+/**
+ * `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 const createRef = <T>(initialState: T): Ref<T> => {
+  let currentState = initialState;
+
+  return {
+    get: () => currentState,
+
+    set: (state) => {
+      currentState = state;
+    },
+
+    modify: (updater) => {
+      currentState = updater(currentState);
+    },
+  };
+};