@evolu/common 8.1.0 → 8.3.0

package/src/Result.ts

@@ -1,34 +1,27 @@
 /**
- * Type-safe error handling with the Result type.
+ * ## Intro
  *
- * @module
- */
-
-import {
-  emptyArray,
-  isNonEmptyArray,
-  type NonEmptyReadonlyArray,
-} from "./Array.ts";
-import { assert } from "./Assert.ts";
-import { exhaustiveCheck, type Thunk } from "./Function.ts";
-import { createMutableRecord, emptyRecord, isIterable } from "./Object.ts";
-import type { Typed } from "./Type.ts";
-import type { Awaitable } from "./Types.ts";
-
-/**
- * The problem with `throw` in JavaScript is that the caught value is always of
+ * Type-safe error handling with {@link Result}.
+ *
+ * The problem with exceptions in JavaScript is that a caught value is always of
  * unknown type. We can't be sure all errors have been handled because the
- * TypeScript compiler can't tell us what was thrown — we can't use
+ * TypeScript compiler can't tell us what might be thrown — we can't use
  * {@link exhaustiveCheck}.
  *
- * Languages like Rust and Haskell solve this with types like `Result` or
- * `Either` where errors are part of the return type. TypeScript can do the
- * same.
+ * Languages like Rust and Haskell model recoverable failures with types such as
+ * `Result` and `Either`, making errors part of the return type.
  *
- * ## Example
+ * TypeScript can express the same pattern with discriminated unions of plain
+ * objects. In Evolu, domain error interfaces extend {@link Typed} to avoid
+ * repeating the literal `type` discriminant.
  *
  * ```ts
- * import { err, exhaustiveCheck, type Result } from "@evolu/common";
+ * import {
+ *   err,
+ *   exhaustiveCheck,
+ *   type Result,
+ *   type Typed,
+ * } from "@evolu/common";
  *
  * // TypeScript can't know what was thrown.
  * try {
@@ -40,16 +33,12 @@ import type { Awaitable } from "./Types.ts";
  * // With Result, errors are part of the return type.
  * const doSomething = (): Result<
  *   number,
- *   NotFoundError | InvalidInputError
+ *   InvalidInputError | NotFoundError
  * > => err({ type: "NotFound" });
  *
- * interface NotFoundError {
- *   readonly type: "NotFound";
- * }
+ * interface InvalidInputError extends Typed<"InvalidInput"> {}
  *
- * interface InvalidInputError {
- *   readonly type: "InvalidInput";
- * }
+ * interface NotFoundError extends Typed<"NotFound"> {}
  *
  * // With Result, the error type is known and exhaustiveCheck works.
  * // If we add another error type, TypeScript tells us it isn't handled.
@@ -86,41 +75,37 @@ import type { Awaitable } from "./Types.ts";
  * }
  * ```
  *
- * Use {@link trySync} and {@link tryAsync} to intentionally convert thrown or
- * rejected errors into typed, recoverable `Result` values.
- *
- * Do not wrap every throwing API in `Result`. If an error is unrecoverable and
- * the caller has no meaningful fallback, let it throw.
+ * Use {@link trySync} and {@link tryAsync} to intentionally convert thrown values
+ * and Promise rejections into typed, recoverable errors represented by
+ * `Result`.
  *
- * ## Composition
+ * Do not wrap every API that throws or rejects in `Result`. If an error is
+ * unrecoverable and the caller has no meaningful fallback, let it propagate.
  *
  * Since `Result` is a plain object, imperative code works naturally.
  *
  * ```ts
- * import { ok, type Result } from "@evolu/common";
+ * import { ok, type Result, type Typed } from "@evolu/common";
  *
  * interface User {
  *   readonly id: string;
  * }
  *
- * interface UserNotFoundError {
- *   readonly type: "UserNotFoundError";
- * }
+ * const getUser = (): Result<User, UserNotFoundError> =>
+ *   ok({ id: "user-1" });
+ *
+ * interface UserNotFoundError extends Typed<"UserNotFound"> {}
  *
  * interface Profile {
  *   readonly userId: string;
  * }
  *
- * interface ProfileNotFoundError {
- *   readonly type: "ProfileNotFoundError";
- * }
- *
- * const getUser = (): Result<User, UserNotFoundError> =>
- *   ok({ id: "user-1" });
  * const getProfile = (
  *   userId: string,
  * ): Result<Profile, ProfileNotFoundError> => ok({ userId });
  *
+ * interface ProfileNotFoundError extends Typed<"ProfileNotFound"> {}
+ *
  * const getCurrentProfile = (): Result<
  *   Profile,
  *   UserNotFoundError | ProfileNotFoundError
@@ -138,211 +123,26 @@ import type { Awaitable } from "./Types.ts";
  * expectOk(profile, { userId: "user-1" });
  * ```
  *
- * {@link flatMapResult} is for a single local composition.
- *
- * ```ts
- * import { flatMapResult, ok, type Result } from "@evolu/common";
- *
- * interface User {
- *   readonly id: string;
- * }
- *
- * interface UserNotFoundError {
- *   readonly type: "UserNotFoundError";
- * }
- *
- * interface Profile {
- *   readonly userId: string;
- * }
- *
- * interface ProfileNotFoundError {
- *   readonly type: "ProfileNotFoundError";
- * }
- *
- * const getUser = (): Result<User, UserNotFoundError> =>
- *   ok({ id: "user-1" });
- * const getProfile = (
- *   userId: string,
- * ): Result<Profile, ProfileNotFoundError> => ok({ userId });
- *
- * const profile = flatMapResult(getUser(), (user) => getProfile(user.id));
- * expectTypeOf(profile).toEqualTypeOf<
- *   Result<Profile, UserNotFoundError | ProfileNotFoundError>
- * >();
- * expectOk(profile, { userId: "user-1" });
- * ```
- *
- * Use {@link allResult} to collect the Ok values from a collection of Results,
- * or return the first Err.
- *
- * ```ts
- * import { allResult, err, ok, type Result } from "@evolu/common";
- *
- * interface User {
- *   readonly id: string;
- * }
- *
- * interface Preferences {
- *   readonly theme: "dark" | "light";
- * }
- *
- * interface LoadAccountError {
- *   readonly type: "LoadAccountError";
- *   readonly resource: "user" | "preferences";
- * }
- *
- * const user: Result<User, LoadAccountError> = ok({ id: "user-1" });
- * const preferences: Result<Preferences, LoadAccountError> = ok({
- *   theme: "dark",
- * });
- * const account = allResult([user, preferences]);
- * expectTypeOf(account).toEqualTypeOf<
- *   Result<readonly [User, Preferences], LoadAccountError>
- * >();
- * expectOk(account, [{ id: "user-1" }, { theme: "dark" }]);
- *
- * const userError: Result<never, LoadAccountError> = err({
- *   type: "LoadAccountError",
- *   resource: "user",
- * });
- * const preferencesError: Result<never, LoadAccountError> = err({
- *   type: "LoadAccountError",
- *   resource: "preferences",
- * });
- * const failedAccount = allResult([userError, preferencesError]);
- * expectErr(failedAccount, {
- *   type: "LoadAccountError",
- *   resource: "user",
- * });
- * ```
- *
- * `allResult` can also map collection values to Results before collecting their
- * Ok values. Mapping stops on the first Err.
- *
- * ```ts
- * import { allResult, err, ok, type Result } from "@evolu/common";
- *
- * interface OrderLine {
- *   readonly productId: string;
- *   readonly quantity: number;
- * }
- *
- * interface ProductUnavailableError {
- *   readonly type: "ProductUnavailableError";
- *   readonly productId: string;
- * }
- *
- * const priceByProductId = new Map([["book", 20]]);
- * const priceOrderLine = ({
- *   productId,
- *   quantity,
- * }: OrderLine): Result<number, ProductUnavailableError> => {
- *   const price = priceByProductId.get(productId);
- *   if (price == null) {
- *     return err({ type: "ProductUnavailableError", productId });
- *   }
- *   return ok(price * quantity);
- * };
- *
- * const orderLines: ReadonlyArray<OrderLine> = [
- *   { productId: "book", quantity: 2 },
- *   { productId: "sold-out", quantity: 1 },
- * ];
- * const prices = allResult(orderLines, priceOrderLine);
- * expectTypeOf(prices).toEqualTypeOf<
- *   Result<ReadonlyArray<number>, ProductUnavailableError>
- * >();
- * expectErr(prices, {
- *   type: "ProductUnavailableError",
- *   productId: "sold-out",
- * });
- * ```
+ * Note `user` and `profile` are named after their success values, not after the
+ * Result (`userResult`, `profileResult`).
  *
- * For side effects, or whenever the success values aren't needed, disable
- * collection with `{ collect: false }`. `allResult` then returns `Result<void,
- * E>` without storing the successful values and still stops on the first Err.
- *
- * ```ts
- * import { allResult, err, ok, type Result } from "@evolu/common";
- *
- * interface User {
- *   readonly id: string;
- * }
- *
- * interface SaveUserError {
- *   readonly type: "SaveUserError";
- * }
- *
- * interface SendWelcomeEmailError {
- *   readonly type: "SendWelcomeEmailError";
- * }
- *
- * const saveUser = (_user: User): Result<number, SaveUserError> =>
- *   err({ type: "SaveUserError" });
- *
- * let welcomeEmailSent = false;
- * const sendWelcomeEmail = (
- *   _user: User,
- * ): Result<void, SendWelcomeEmailError> => {
- *   welcomeEmailSent = true;
- *   return ok();
- * };
- *
- * const registerUser = (
- *   user: User,
- * ): Result<void, SaveUserError | SendWelcomeEmailError> =>
- *   allResult(
- *     [saveUser, sendWelcomeEmail],
- *     (operation) => operation(user),
- *     { collect: false },
- *   );
- *
- * const result = registerUser({ id: "user-1" });
- * expectTypeOf(result).toEqualTypeOf<
- *   Result<void, SaveUserError | SendWelcomeEmailError>
- * >();
- * expectErr(result, { type: "SaveUserError" });
- * expect(welcomeEmailSent).toBe(false);
- * ```
- *
- * For the first success, {@link anyResult} returns the first Ok or the last
- * error if all fail:
- *
- * ```ts
- * import { anyResult, err, ok, type Result } from "@evolu/common";
- *
- * interface CacheMissError {
- *   readonly type: "CacheMissError";
- * }
- *
- * const getCachedPrice = (): Result<number, CacheMissError> =>
- *   err({ type: "CacheMissError" });
- *
- * const prices = [getCachedPrice(), ok(20)] as const;
- * const price = anyResult(prices);
- * expectTypeOf(price).toEqualTypeOf<Result<number, CacheMissError>>();
- * expectOk(price, 20);
- * ```
- *
- * ## Naming convention
- *
- * Name a Result after its value (`user`, `config`), not after the wrapper
- * (`userResult`, `configResult`). If it has no success value, name it `result`.
- * For several such operations, use `allResult` with `{ collect: false }` as
- * shown above.
+ * If a Result has no success value, name it `result`. For several such
+ * operations, use {@link allResult} with `{ collect: false }`.
  *
  * ## Unrecoverable errors
  *
- * Some errors can't be handled locally — they must propagate to the top level.
- * These are unrecoverable errors: expected (you know they can happen) but only
- * handleable at the app level.
+ * Unrecoverable errors are failures the application can't handle meaningfully.
+ * For example, a database failure is unrecoverable when the application has no
+ * useful fallback, retry, or degraded mode.
  *
- * Do not force these errors into `Result` just because the underlying API
- * throws. If the local caller cannot recover, let the error propagate to a
- * global handler or other app boundary.
+ * Do not turn such failures into `Result` merely because the underlying API
+ * throws or rejects. Let the exception or Promise rejection propagate to the
+ * top-level handler so the application stops instead of continuing in a
+ * potentially invalid state.
  *
- * In Evolu apps, the root Run reports defects and the platform lifecycle API
- * owns application shutdown. For example, `@evolu/nodejs` provides `runMain`.
+ * In Evolu apps, the root {@link Run} reports defects and the platform lifecycle
+ * API owns application shutdown. For example, `@evolu/nodejs` provides
+ * {@link @evolu/nodejs!runMain | runMain}.
  *
  * ## FAQ
  *
@@ -385,17 +185,56 @@ import type { Awaitable } from "./Types.ts";
  * Use `Result<void, E>` and return `ok()` (no argument). Don't return
  * `ok(true)`, `ok("success")`, or `ok("done")` — `ok()` already signals
  * success; redundant values add noise.
+ *
+ * @module
+ */
+import {
+  emptyArray,
+  isNonEmptyArray,
+  type NonEmptyReadonlyArray,
+} from "./Array.ts";
+import { assert } from "./Assert.ts";
+import { exhaustiveCheck, type Thunk } from "./Function.ts";
+import { createMutableRecord, emptyRecord, isIterable } from "./Object.ts";
+import type { Run } from "./Task.ts";
+import type { Typed } from "./Type.ts";
+import type { Awaitable } from "./Types.ts";
+
+/**
+ * A discriminated success or failure value: either {@link Ok} or {@link Err}.
+ *
+ * See the {@link @evolu/common!Result | Result overview}.
+ *
+ * @group Core
  */
 export type Result<T, E = never> = Ok<T> | Err<E>;
 
 /**
  * Shorthand for a {@link Result} with `any` type parameters.
  *
- * @group Utilities
+ * @group Core
  */
 export type AnyResult = Result<any, any>;
 
-/** A successful {@link Result}. */
+/**
+ * A successful {@link Result}.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import { ok, type Result } from "@evolu/common";
+ *
+ * const result = ok();
+ * const count = ok(42);
+ *
+ * expectTypeOf(result).toEqualTypeOf<Result<void>>();
+ * expectTypeOf(count).toEqualTypeOf<Result<number>>();
+ * expectOk(result, undefined);
+ * expectOk(count, 42);
+ * ```
+ *
+ * @group Core
+ */
 export interface Ok<out T> {
   readonly ok: true;
   readonly value: T;
@@ -405,7 +244,7 @@ export interface Ok<out T> {
  * An error {@link Result}.
  *
  * The `error` property can be any type that describes the error. For domain
- * errors, use a plain object with a `type` field for discrimination.
+ * errors, define a plain interface extending {@link Typed}.
  *
  * ### Example
  *
@@ -416,23 +255,25 @@ export interface Ok<out T> {
  *   readonly id: string;
  * }
  *
- * interface NotFoundError extends Typed<"NotFoundError"> {
- *   readonly id: string;
- * }
- *
  * const users = new Map<string, User>([["user-1", { id: "user-1" }]]);
  * const findUser = (id: string): Result<User, NotFoundError> => {
  *   const user = users.get(id);
- *   if (user == null) return err({ type: "NotFoundError", id });
+ *   if (user == null) return err({ type: "NotFound", id });
  *   return ok(user);
  * };
  *
+ * interface NotFoundError extends Typed<"NotFound"> {
+ *   readonly id: string;
+ * }
+ *
  * expectOk(findUser("user-1"), { id: "user-1" });
  * expectErr(findUser("missing"), {
- *   type: "NotFoundError",
+ *   type: "NotFound",
  *   id: "missing",
  * });
  * ```
+ *
+ * @group Core
  */
 export interface Err<out E> {
   readonly ok: false;
@@ -442,7 +283,7 @@ export interface Err<out E> {
 /**
  * Infers the success value type from a {@link Result}.
  *
- * @group Utilities
+ * @group Core
  */
 export type InferOk<R extends Result<any, any>> =
   R extends Ok<infer T> ? T : never;
@@ -450,7 +291,7 @@ export type InferOk<R extends Result<any, any>> =
 /**
  * Infers the error type from a {@link Result}.
  *
- * @group Utilities
+ * @group Core
  */
 export type InferErr<R extends Result<any, any>> =
   R extends Err<infer E> ? E : never;
@@ -462,19 +303,7 @@ export type InferErr<R extends Result<any, any>> =
  *   producing a value.
  * - `ok(value)` creates a `Result<T, never>` containing the specified value.
  *
- * ### Example
- *
- * ```ts
- * import { ok, type Result } from "@evolu/common";
- *
- * const noValue = ok();
- * const success = ok(42);
- *
- * expectTypeOf(noValue).toEqualTypeOf<Result<void>>();
- * expectTypeOf(success).toEqualTypeOf<Result<number>>();
- * expectOk(noValue, undefined);
- * expectOk(success, 42);
- * ```
+ * @group Core
  */
 export function ok(): Result<void>;
 /** Creates an {@link Ok} result with a specified value. */
@@ -487,18 +316,75 @@ export function ok<T>(value?: T): Result<T> {
 /** Cache ok() and ok(undefined) to avoid repeated allocations. */
 const okVoid: Result<void> = { ok: true, value: undefined };
 
-/** Creates an {@link Err} result. */
+/**
+ * Creates an {@link Err} result.
+ *
+ * @group Core
+ */
 export const err = <E>(error: E): Result<never, E> => ({ ok: false, error });
 
-/** Type guard for {@link Ok} results. */
+/**
+ * Type guard for {@link Ok} results.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import {
+ *   isOk,
+ *   ok,
+ *   type Ok,
+ *   type Result,
+ *   type Typed,
+ * } from "@evolu/common";
+ *
+ * const getCount = (): Result<number, CountUnavailableError> => ok(2);
+ *
+ * interface CountUnavailableError extends Typed<"CountUnavailable"> {}
+ *
+ * const count = getCount();
+ * if (isOk(count)) {
+ *   expectTypeOf(count).toEqualTypeOf<Ok<number>>();
+ *   expect(count.value).toBe(2);
+ * }
+ * ```
+ *
+ * @group Guards
+ */
 export const isOk = <T, E>(result: Result<T, E>): result is Ok<T> => result.ok;
 
-/** Type guard for {@link Err} results. */
+/**
+ * Type guard for {@link Err} results.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import {
+ *   err,
+ *   isErr,
+ *   type Err,
+ *   type Result,
+ *   type Typed,
+ * } from "@evolu/common";
+ *
+ * const getCount = (): Result<number, CountUnavailableError> =>
+ *   err({ type: "CountUnavailable" });
+ *
+ * interface CountUnavailableError extends Typed<"CountUnavailable"> {}
+ *
+ * const count = getCount();
+ * if (isErr(count)) {
+ *   expectTypeOf(count).toEqualTypeOf<Err<CountUnavailableError>>();
+ *   expect(count.error).toEqual({ type: "CountUnavailable" });
+ * }
+ * ```
+ *
+ * @group Guards
+ */
 export const isErr = <T, E>(result: Result<T, E>): result is Err<E> =>
   !result.ok;
 
 /**
- * Gets the value from an `Ok` {@link Result}, or throws if it is an `Err`.
+ * Gets the value from an {@link Ok}, or throws for an {@link Err}.
  *
  * Use this where failure should crash the current flow instead of being handled
  * locally.
@@ -506,8 +392,8 @@ export const isErr = <T, E>(result: Result<T, E>): result is Err<E> =>
  * **When to use:**
  *
  * - Application startup or composition-root setup where errors must stop the
- *   program immediately. In Evolu apps, the root Run reports the defect and the
- *   platform lifecycle API handles shutdown.
+ *   program immediately. In Evolu apps, the root {@link Run} reports the defect
+ *   and the platform lifecycle API handles shutdown.
  * - Module-level constants
  * - Test setup with values that are expected to be valid
  *
@@ -517,33 +403,41 @@ export const isErr = <T, E>(result: Result<T, E>): result is Err<E> =>
  * ### Example
  *
  * ```ts
- * import { err, getOrThrow, ok, type Result } from "@evolu/common";
+ * import {
+ *   err,
+ *   getOrThrow,
+ *   ok,
+ *   type Result,
+ *   type Typed,
+ * } from "@evolu/common";
  *
  * interface Config {
  *   readonly port: number;
  * }
- * interface InvalidConfigError {
- *   readonly type: "InvalidConfigError";
- * }
+ *
  * const loadConfig = (): Result<Config, InvalidConfigError> =>
  *   ok({ port: 3000 });
  *
+ * interface InvalidConfigError extends Typed<"InvalidConfig"> {}
+ *
  * // At app startup, crash if the config is invalid.
  * const config = getOrThrow(loadConfig());
  * expectTypeOf(config).toEqualTypeOf<Config>();
  * expect(config).toEqual({ port: 3000 });
  *
  * try {
- *   getOrThrow(err({ type: "InvalidConfigError" }));
+ *   getOrThrow(err({ type: "InvalidConfig" }));
  *   assert.fail("Expected getOrThrow to throw");
  * } catch (error) {
  *   assert(error instanceof Error);
  *   expect(error.message).toBe("getOrThrow");
- *   expect(error.cause).toEqual({ type: "InvalidConfigError" });
+ *   expect(error.cause).toEqual({ type: "InvalidConfig" });
  * }
  * ```
  *
  * Throws: `Error` with the original error attached as `cause`.
+ *
+ * @group Unwrapping
  */
 export const getOrThrow = <T, E>(result: Result<T, E>): T => {
   if (result.ok) {
@@ -554,8 +448,7 @@ export const getOrThrow = <T, E>(result: Result<T, E>): T => {
 };
 
 /**
- * Gets the value from an `Ok` {@link Result}, or returns `null` if it is an
- * `Err`.
+ * Gets the value from an {@link Ok}, or returns `null` for an {@link Err}.
  *
  * **Intended usage:**
  *
@@ -566,16 +459,22 @@ export const getOrThrow = <T, E>(result: Result<T, E>): T => {
  * ### Example
  *
  * ```ts
- * import { err, getOrNull, ok, type Result } from "@evolu/common";
+ * import {
+ *   err,
+ *   getOrNull,
+ *   ok,
+ *   type Result,
+ *   type Typed,
+ * } from "@evolu/common";
  *
  * interface User {
  *   readonly id: string;
  * }
- * interface UserNotFoundError {
- *   readonly type: "UserNotFoundError";
- * }
+ *
  * const findUser = (id: string): Result<User, UserNotFoundError> =>
- *   id === "user-1" ? ok({ id }) : err({ type: "UserNotFoundError" });
+ *   id === "user-1" ? ok({ id }) : err({ type: "UserNotFound" });
+ *
+ * interface UserNotFoundError extends Typed<"UserNotFound"> {}
  *
  * // For APIs that expect T | null.
  * const user = getOrNull(findUser("user-1"));
@@ -585,6 +484,8 @@ export const getOrThrow = <T, E>(result: Result<T, E>): T => {
  * expect(user).toEqual({ id: "user-1" });
  * expect(missingUser).toBeNull();
  * ```
+ *
+ * @group Unwrapping
  */
 export const getOrNull = <T, E>(result: Result<T, E>): T | null =>
   result.ok ? result.value : null;
@@ -606,6 +507,8 @@ export const getOrNull = <T, E>(result: Result<T, E>): T | null =>
  * expectTypeOf(count).toEqualTypeOf<number>();
  * expect(count).toBe(2);
  * ```
+ *
+ * @group Unwrapping
  */
 export const getOk = <T>(result: Result<T>): T => {
   assert(result.ok, "Expected Ok result.");
@@ -615,49 +518,53 @@ export const getOk = <T>(result: Result<T>): T => {
 /**
  * Wraps a synchronous function that may throw, returning a {@link Result}.
  *
- * `mapError` converts the caught `unknown` value into a typed domain error.
+ * When provided, `mapError` converts the caught `unknown` value into a typed
+ * domain error.
  *
- * Some APIs use exceptions for both recoverable and unrecoverable failures. In
- * that case, convert only the failures the caller can recover from and rethrow
- * the rest. `trySync` propagates rethrown failures instead of converting them
- * to Err.
+ * Some APIs throw for both recoverable and unrecoverable errors. In that case,
+ * convert only the errors the caller can recover from and rethrow the rest. The
+ * `trySync` error mapper propagates rethrown values instead of converting them
+ * to {@link Err}.
  *
  * ### Example
  *
  * ```ts
- * import { trySync, type Result } from "@evolu/common";
- *
- * interface ReserveSeatError {
- *   readonly type: "ReserveSeatError";
- *   readonly seat: string;
- * }
+ * import { trySync, type Result, type Typed } from "@evolu/common";
  *
  * class LegacySeatUnavailableError extends Error {}
  *
  * const legacyReserveSeat = (seat: string): void => {
  *   if (seat === "A1") throw new LegacySeatUnavailableError();
- *   if (seat === "B1") throw new Error("Unexpected database error");
+ *   if (seat === "B1") throw new Error("Database error");
  * };
  *
- * const reserveSeat = (seat: string): Result<void, ReserveSeatError> =>
+ * const reserveSeat = (seat: string): Result<void, SeatUnavailableError> =>
  *   trySync(
  *     () => legacyReserveSeat(seat),
  *     (error) => {
  *       if (error instanceof LegacySeatUnavailableError) {
- *         return { type: "ReserveSeatError", seat };
+ *         return { type: "SeatUnavailable", seat };
  *       }
  *       throw error;
  *     },
  *   );
  *
+ * interface SeatUnavailableError extends Typed<"SeatUnavailable"> {
+ *   readonly seat: string;
+ * }
+ *
  * const result = reserveSeat("B2");
- * expectTypeOf(result).toEqualTypeOf<Result<void, ReserveSeatError>>();
+ * expectTypeOf(result).toEqualTypeOf<Result<void, SeatUnavailableError>>();
  * expectOk(result, undefined);
- * expectErr(reserveSeat("A1"), { type: "ReserveSeatError", seat: "A1" });
- * expect(() => reserveSeat("B1")).toThrow("Unexpected database error");
+ * expectErr(reserveSeat("A1"), { type: "SeatUnavailable", seat: "A1" });
+ * expect(() => reserveSeat("B1")).toThrow("Database error");
  * ```
+ *
+ * @group Exception interop
  */
 export function trySync<T>(fn: () => T): Result<T, unknown>;
+
+/** Maps caught exceptions to a typed error. */
 export function trySync<T, E>(
   fn: () => T,
   mapError: (error: unknown) => E,
@@ -676,58 +583,60 @@ export function trySync<T, E>(
 /**
  * Wraps an async function that may throw or reject, returning a {@link Result}.
  *
- * `mapError` converts the caught `unknown` value into a typed domain error.
+ * When provided, `mapError` converts the caught `unknown` value into a typed
+ * domain error.
  *
- * Some APIs use exceptions for both recoverable and unrecoverable failures. In
- * that case, convert only the failures the caller can recover from and rethrow
- * the rest. `tryAsync` rejects with rethrown failures instead of converting
- * them to Err.
+ * Some async APIs throw or reject for both recoverable and unrecoverable
+ * errors. In that case, convert only the errors the caller can recover from and
+ * rethrow the rest. The `tryAsync` error mapper leaves rethrown values as
+ * Promise rejections instead of converting them to {@link Err}.
  *
  * ### Example
  *
  * ```ts
- * import { tryAsync, type Result } from "@evolu/common";
- *
- * interface ReserveSeatError {
- *   readonly type: "ReserveSeatError";
- *   readonly seat: string;
- * }
+ * import { tryAsync, type Result, type Typed } from "@evolu/common";
  *
  * class LegacySeatUnavailableError extends Error {}
  *
  * const legacyReserveSeat = async (seat: string): Promise<void> => {
  *   if (seat === "A1") throw new LegacySeatUnavailableError();
- *   if (seat === "B1") throw new Error("Unexpected database error");
+ *   if (seat === "B1") throw new Error("Database error");
  * };
  *
  * const reserveSeat = (
  *   seat: string,
- * ): Promise<Result<void, ReserveSeatError>> =>
+ * ): Promise<Result<void, SeatUnavailableError>> =>
  *   tryAsync(
  *     () => legacyReserveSeat(seat),
  *     (error) => {
  *       if (error instanceof LegacySeatUnavailableError) {
- *         return { type: "ReserveSeatError", seat };
+ *         return { type: "SeatUnavailable", seat };
  *       }
  *       throw error;
  *     },
  *   );
  *
+ * interface SeatUnavailableError extends Typed<"SeatUnavailable"> {
+ *   readonly seat: string;
+ * }
+ *
  * const result = await reserveSeat("B2");
- * expectTypeOf(result).toEqualTypeOf<Result<void, ReserveSeatError>>();
+ * expectTypeOf(result).toEqualTypeOf<Result<void, SeatUnavailableError>>();
  * expectOk(result, undefined);
  * expectErr(await reserveSeat("A1"), {
- *   type: "ReserveSeatError",
+ *   type: "SeatUnavailable",
  *   seat: "A1",
  * });
- * await expect(reserveSeat("B1")).rejects.toThrow(
- *   "Unexpected database error",
- * );
+ * await expect(reserveSeat("B1")).rejects.toThrow("Database error");
  * ```
+ *
+ * @group Exception interop
  */
 export function tryAsync<T>(
   promiseThunk: Thunk<Awaitable<T>>,
 ): Promise<Result<T, unknown>>;
+
+/** Maps thrown or rejected values to a typed error. */
 export function tryAsync<T, E>(
   promiseThunk: Thunk<Awaitable<T>>,
   mapError: (error: unknown) => E,
@@ -749,35 +658,43 @@ export async function tryAsync<T, E>(
  * The consumer requests the next value (e.g. via `next()`), and the producer
  * responds with one of:
  *
- * - `Ok<A>` — produced a value
- * - `Err<Done<D>>` — completed normally with a done value
- * - `Err<E>` — failed with an error
+ * - An {@link Ok} containing `A` — produced a value
+ * - An {@link Err} containing {@link Done} — completed normally with a done value
+ * - An {@link Err} containing `E` — failed with an error
  *
  * Inspired by JavaScript's `Iterator.next()`, which returns `{ value, done }`.
  *
  * ### Example
  *
  * ```ts
- * import { done, err, ok, type NextResult } from "@evolu/common";
- *
- * interface ReadError {
- *   readonly type: "ReadError";
- * }
+ * import {
+ *   done,
+ *   err,
+ *   ok,
+ *   type NextResult,
+ *   type Typed,
+ * } from "@evolu/common";
  *
- * const next = (index: number): NextResult<string, ReadError, number> => {
+ * const next = (
+ *   index: number,
+ * ): NextResult<string, ReadFailedError, number> => {
  *   if (index === 0) return ok("first");
- *   if (index === 1) return err({ type: "ReadError" });
+ *   if (index === 1) return err({ type: "ReadFailed" });
  *   return err(done(index));
  * };
  *
+ * interface ReadFailedError extends Typed<"ReadFailed"> {}
+ *
  * const value = next(0);
  * expectTypeOf(value).toEqualTypeOf<
- *   NextResult<string, ReadError, number>
+ *   NextResult<string, ReadFailedError, number>
  * >();
  * expectOk(value, "first");
- * expectErr(next(1), { type: "ReadError" });
+ * expectErr(next(1), { type: "ReadFailed" });
  * expectErr(next(2), { type: "Done", done: 2 });
  * ```
+ *
+ * @group Pull
  */
 export type NextResult<A, E = never, D = void> = Result<A, E | Done<D>>;
 
@@ -789,16 +706,6 @@ export type NextResult<A, E = never, D = void> = Result<A, E | Done<D>>;
  *
  * Inspired by JavaScript's `IteratorResult` where `{ done: true }` signals
  * completion.
- */
-export interface Done<out D = unknown> extends Typed<"Done"> {
-  readonly done: D;
-}
-
-/**
- * Constructs a {@link Done} value.
- *
- * - `done()` creates a `Done<void>` for protocols that don't need a done value.
- * - `done(value)` creates a `Done<D>` containing the specified value.
  *
  * ### Example
  *
@@ -812,6 +719,20 @@ export interface Done<out D = unknown> extends Typed<"Done"> {
  * expect(withoutValue).toEqual({ type: "Done", done: undefined });
  * expect(withValue).toEqual({ type: "Done", done: 42 });
  * ```
+ *
+ * @group Pull
+ */
+export interface Done<out D = unknown> extends Typed<"Done"> {
+  readonly done: D;
+}
+
+/**
+ * Constructs a {@link Done} value.
+ *
+ * - `done()` creates a `Done<void>` for protocols that don't need a done value.
+ * - `done(value)` creates a `Done<D>` containing the specified value.
+ *
+ * @group Pull
  */
 export function done(): Done<void>;
 /** With a done value. */
@@ -832,13 +753,16 @@ export function done<D>(value?: D): Done<D> {
  * ### Example
  *
  * ```ts
- * import { type Done, type ExcludeDone } from "@evolu/common";
+ * import { type Done, type ExcludeDone, type Typed } from "@evolu/common";
+ *
+ * type Errors = ReadFailedError | Done<number>;
  *
- * type Errors = "ReadError" | Done<number>;
- * expectTypeOf<ExcludeDone<Errors>>().toEqualTypeOf<"ReadError">();
+ * interface ReadFailedError extends Typed<"ReadFailed"> {}
+ *
+ * expectTypeOf<ExcludeDone<Errors>>().toEqualTypeOf<ReadFailedError>();
  * ```
  *
- * @group Utilities
+ * @group Pull
  */
 export type ExcludeDone<E> = Exclude<E, Done<any>>;
 
@@ -851,13 +775,16 @@ export type ExcludeDone<E> = Exclude<E, Done<any>>;
  * ### Example
  *
  * ```ts
- * import { type Done, type OnlyDone } from "@evolu/common";
+ * import { type Done, type OnlyDone, type Typed } from "@evolu/common";
+ *
+ * type Errors = ReadFailedError | Done<number>;
+ *
+ * interface ReadFailedError extends Typed<"ReadFailed"> {}
  *
- * type Errors = "ReadError" | Done<number>;
  * expectTypeOf<OnlyDone<Errors>>().toEqualTypeOf<Done<number>>();
  * ```
  *
- * @group Utilities
+ * @group Pull
  */
 export type OnlyDone<E> = Extract<E, Done<any>>;
 
@@ -867,13 +794,20 @@ export type OnlyDone<E> = Extract<E, Done<any>>;
  * ### Example
  *
  * ```ts
- * import { type InferDone, type NextResult } from "@evolu/common";
+ * import {
+ *   type InferDone,
+ *   type NextResult,
+ *   type Typed,
+ * } from "@evolu/common";
+ *
+ * type ReadResult = NextResult<string, ReadFailedError, number>;
+ *
+ * interface ReadFailedError extends Typed<"ReadFailed"> {}
  *
- * type ReadResult = NextResult<string, "ReadError", number>;
  * expectTypeOf<InferDone<ReadResult>>().toEqualTypeOf<number>();
  * ```
  *
- * @group Utilities
+ * @group Pull
  */
 export type InferDone<R extends Result<any, any>> =
   InferErr<R> extends infer Errors
@@ -894,44 +828,35 @@ export type InferDone<R extends Result<any, any>> =
  * ### Example
  *
  * ```ts
- * import { err, flatMapResult, ok, type Result } from "@evolu/common";
+ * import {
+ *   flatMapResult,
+ *   ok,
+ *   type Result,
+ *   type Typed,
+ * } from "@evolu/common";
  *
  * interface User {
  *   readonly id: string;
  * }
- * interface UserError {
- *   readonly type: "UserError";
- * }
+ *
+ * interface UserNotFoundError extends Typed<"UserNotFound"> {}
  *
  * interface Profile {
  *   readonly userId: string;
  * }
- * interface ProfileError {
- *   readonly type: "ProfileError";
- * }
- * const getProfile = (userId: string): Result<Profile, ProfileError> =>
- *   ok({ userId });
- *
- * let getProfileCalls = 0;
- * const getProfileForUser = (
- *   user: User,
- * ): Result<Profile, ProfileError> => {
- *   getProfileCalls++;
- *   return getProfile(user.id);
- * };
  *
- * const user: Result<User, UserError> = ok({ id: "user-1" });
- * const profile = flatMapResult(user, getProfileForUser);
+ * const getProfile = (
+ *   userId: string,
+ * ): Result<Profile, ProfileNotFoundError> => ok({ userId });
+ *
+ * interface ProfileNotFoundError extends Typed<"ProfileNotFound"> {}
+ *
+ * const user: Result<User, UserNotFoundError> = ok({ id: "user-1" });
+ * const profile = flatMapResult(user, ({ id }) => getProfile(id));
  * expectTypeOf(profile).toEqualTypeOf<
- *   Result<Profile, UserError | ProfileError>
+ *   Result<Profile, UserNotFoundError | ProfileNotFoundError>
  * >();
  * expectOk(profile, { userId: "user-1" });
- * expect(getProfileCalls).toBe(1);
- *
- * const missingUser: Result<User, UserError> = err({ type: "UserError" });
- * const missingProfile = flatMapResult(missingUser, getProfileForUser);
- * expectErr(missingProfile, { type: "UserError" });
- * expect(getProfileCalls).toBe(1);
  * ```
  *
  * @group Composition
@@ -942,41 +867,36 @@ export const flatMapResult = <T, E, U, F>(
 ): Result<U, E | F> => (result.ok ? fn(result.value) : result);
 
 /**
- * Collects the Ok values from a collection of {@link Result}s, or maps
- * collection values to Results and collects their Ok values.
+ * Collects successful values from {@link Result}s.
  *
- * Returns the first error if any result fails.
+ * Stops processing the input at the first {@link Err}. Mapping overloads do not
+ * call the mapper for the remaining input values.
  *
- * Pass `{ collect: false }` to return `Result<void, E>` without storing the Ok
- * values in an output collection.
+ * Pass `{ collect: false }` to return `Result<void, E>` without storing the
+ * {@link Ok} values in an output collection.
  *
  * ### Example
  *
  * ```ts
- * import { allResult, err, ok, type Result } from "@evolu/common";
+ * import { allResult, ok, type Result, type Typed } from "@evolu/common";
  *
- * interface CountError {
- *   readonly type: "CountError";
- * }
- * interface LabelError {
- *   readonly type: "LabelError";
- * }
+ * const getCount = (): Result<number, CountUnavailableError> => ok(2);
+ *
+ * interface CountUnavailableError extends Typed<"CountUnavailable"> {}
+ *
+ * const getLabel = (): Result<string, LabelUnavailableError> =>
+ *   ok("books");
  *
- * const getCount = (): Result<number, CountError> => ok(2);
- * const getLabel = (): Result<string, LabelError> => ok("books");
+ * interface LabelUnavailableError extends Typed<"LabelUnavailable"> {}
  *
  * const values = allResult([getCount(), getLabel()]);
  * expectTypeOf(values).toEqualTypeOf<
- *   Result<readonly [number, string], CountError | LabelError>
+ *   Result<
+ *     readonly [number, string],
+ *     CountUnavailableError | LabelUnavailableError
+ *   >
  * >();
  * expectOk(values, [2, "books"]);
- *
- * const numbers = allResult([
- *   ok(1),
- *   err({ type: "CountError" }),
- *   err({ type: "LabelError" }),
- * ]);
- * expectErr(numbers, { type: "CountError" });
  * ```
  *
  * @group Composition
@@ -1011,26 +931,15 @@ export function allResult<T extends Readonly<Record<string, AnyResult>>>(
 /**
  * For dynamic or generated result lists.
  *
- * Stops consuming the iterable on the first Err.
- *
  * ### Example
  *
  * ```ts
- * import { allResult, err, ok, type Result } from "@evolu/common";
- *
- * interface LoadNumberError {
- *   readonly type: "LoadNumberError";
- * }
+ * import { allResult, ok, type Result } from "@evolu/common";
  *
- * const results: ReadonlyArray<Result<number, LoadNumberError>> = [
- *   ok(1),
- *   err({ type: "LoadNumberError" }),
- * ];
+ * const results: ReadonlyArray<Result<number>> = [ok(1), ok(2)];
  * const numbers = allResult(results);
- * expectTypeOf(numbers).toEqualTypeOf<
- *   Result<ReadonlyArray<number>, LoadNumberError>
- * >();
- * expectErr(numbers, { type: "LoadNumberError" });
+ * expectTypeOf(numbers).toEqualTypeOf<Result<ReadonlyArray<number>>>();
+ * expectOk(numbers, [1, 2]);
  * ```
  */
 export function allResult<T, E>(
@@ -1062,7 +971,19 @@ export function allResult<T, E>(
   results: NonEmptyReadonlyArray<Result<T, E>>,
 ): Result<NonEmptyReadonlyArray<T>, E>;
 
-/** Does not collect the Ok values from a record of Results. */
+/**
+ * Does not collect the Ok values from a record of Results.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import { allResult, ok, type Result } from "@evolu/common";
+ *
+ * const result = allResult({ a: ok(1), b: ok(2) }, { collect: false });
+ * expectTypeOf(result).toEqualTypeOf<Result<void>>();
+ * expectOk(result, undefined);
+ * ```
+ */
 export function allResult<T extends Readonly<Record<string, AnyResult>>>(
   results: T,
   options: { readonly collect: false },
@@ -1072,25 +993,17 @@ export function allResult<T extends Readonly<Record<string, AnyResult>>>(
  * Does not collect the Ok values from an iterable of Results.
  *
  * Use this overload when the Results already exist and only their collective
- * success or failure matters. To stop invoking operations after the first Err,
- * use the mapping overload instead.
+ * success or failure matters.
  *
  * ### Example
  *
  * ```ts
- * import { allResult, err, ok, type Result } from "@evolu/common";
- *
- * interface SaveError {
- *   readonly type: "SaveError";
- * }
+ * import { allResult, ok, type Result } from "@evolu/common";
  *
- * const results: ReadonlyArray<Result<number, SaveError>> = [
- *   ok(1),
- *   err({ type: "SaveError" }),
- * ];
+ * const results: ReadonlyArray<Result<number>> = [ok(1), ok(2)];
  * const result = allResult(results, { collect: false });
- * expectTypeOf(result).toEqualTypeOf<Result<void, SaveError>>();
- * expectErr(result, { type: "SaveError" });
+ * expectTypeOf(result).toEqualTypeOf<Result<void>>();
+ * expectOk(result, undefined);
  * ```
  */
 export function allResult<R extends AnyResult>(
@@ -1111,35 +1024,16 @@ export function allResult<R extends AnyResult>(
  *   type Result,
  * } from "@evolu/common";
  *
- * interface Order {
- *   readonly id: string;
- * }
- * interface Invoice {
- *   readonly orderId: string;
- * }
- * interface CreateInvoiceError {
- *   readonly type: "CreateInvoiceError";
- * }
- *
- * const orders: NonEmptyReadonlyArray<Order> = [{ id: "order-1" }];
- * const createInvoice = (
- *   order: Order,
- * ): Result<Invoice, CreateInvoiceError> => ok({ orderId: order.id });
- *
- * const invoices = allResult(orders, createInvoice);
- * expectTypeOf(invoices).toEqualTypeOf<
- *   Result<NonEmptyReadonlyArray<Invoice>, CreateInvoiceError>
+ * const numbers: NonEmptyReadonlyArray<number> = [1, 2];
+ * const doubled = allResult(numbers, (number) => ok(number * 2));
+ * expectTypeOf(doubled).toEqualTypeOf<
+ *   Result<NonEmptyReadonlyArray<number>>
  * >();
- * expectOk(invoices, [{ orderId: "order-1" }]);
+ * expectOk(doubled, [2, 4]);
  *
- * const invoiceTuple = allResult(
- *   [{ id: "order-1" }, { id: "order-2" }] as const,
- *   createInvoice,
- * );
- * expectTypeOf(invoiceTuple).toEqualTypeOf<
- *   Result<readonly [Invoice, Invoice], CreateInvoiceError>
- * >();
- * expectOk(invoiceTuple, [{ orderId: "order-1" }, { orderId: "order-2" }]);
+ * const tuple = allResult([1, 2] as const, (number) => ok(number * 2));
+ * expectTypeOf(tuple).toEqualTypeOf<Result<readonly [number, number]>>();
+ * expectOk(tuple, [2, 4]);
  * ```
  */
 export function allResult<
@@ -1153,37 +1047,15 @@ export function allResult<
 /**
  * Maps a dynamic or generated value collection to Results.
  *
- * Stops consuming and mapping the iterable on the first Err.
- *
  * ### Example
  *
  * ```ts
- * import { allResult, err, ok, type Result } from "@evolu/common";
- *
- * interface ProductNotFoundError {
- *   readonly type: "ProductNotFoundError";
- *   readonly productId: string;
- * }
- *
- * const pricesByProductId = new Map([
- *   ["book", 20],
- *   ["pen", 5],
- * ]);
- * const getPrice = (
- *   productId: string,
- * ): Result<number, ProductNotFoundError> => {
- *   const price = pricesByProductId.get(productId);
- *   return price == null
- *     ? err({ type: "ProductNotFoundError", productId })
- *     : ok(price);
- * };
+ * import { allResult, ok, type Result } from "@evolu/common";
  *
- * const productIds: Iterable<string> = new Set(["book", "pen"]);
- * const prices = allResult(productIds, getPrice);
- * expectTypeOf(prices).toEqualTypeOf<
- *   Result<ReadonlyArray<number>, ProductNotFoundError>
- * >();
- * expectOk(prices, [20, 5]);
+ * const numbers: Iterable<number> = new Set([1, 2]);
+ * const doubled = allResult(numbers, (number) => ok(number * 2));
+ * expectTypeOf(doubled).toEqualTypeOf<Result<ReadonlyArray<number>>>();
+ * expectOk(doubled, [2, 4]);
  * ```
  */
 export function allResult<A, R extends AnyResult>(
@@ -1197,32 +1069,18 @@ export function allResult<A, R extends AnyResult>(
  * ### Example
  *
  * ```ts
- * import { allResult, err, ok, type Result } from "@evolu/common";
+ * import { allResult, ok, type Result } from "@evolu/common";
  *
  * interface User {
  *   readonly id: string;
  * }
  *
- * interface UserNotFoundError {
- *   readonly type: "UserNotFoundError";
- *   readonly userId: string;
- * }
- *
- * const usersById = new Map<string, User>([
- *   ["user-1", { id: "user-1" }],
- *   ["user-2", { id: "user-2" }],
- * ]);
- * const findUser = (userId: string): Result<User, UserNotFoundError> => {
- *   const user = usersById.get(userId);
- *   return user == null
- *     ? err({ type: "UserNotFoundError", userId })
- *     : ok(user);
- * };
+ * const toUser = (id: string): Result<User> => ok({ id });
  *
  * const userIdsByRole = { owner: "user-1", reviewer: "user-2" } as const;
- * const usersByRole = allResult(userIdsByRole, findUser);
+ * const usersByRole = allResult(userIdsByRole, toUser);
  * expectTypeOf(usersByRole).toEqualTypeOf<
- *   Result<Readonly<Record<"owner" | "reviewer", User>>, UserNotFoundError>
+ *   Result<Readonly<Record<"owner" | "reviewer", User>>>
  * >();
  * expectOk(usersByRole, {
  *   owner: { id: "user-1" },
@@ -1246,22 +1104,20 @@ export function allResult<A, R extends AnyResult, K extends string>(
  * ```ts
  * import { allResult, ok, type Result } from "@evolu/common";
  *
- * interface UpdateItemError {
- *   readonly type: "UpdateItemError";
- * }
- *
- * const updatedItemIds: Array<string> = [];
- * const updateItem = (itemId: string): Result<number, UpdateItemError> => {
- *   updatedItemIds.push(itemId);
- *   return ok(1);
- * };
- *
- * const result = allResult(["item-1", "item-2"], updateItem, {
- *   collect: false,
- * });
- * expectTypeOf(result).toEqualTypeOf<Result<void, UpdateItemError>>();
+ * const visited: Array<number> = [];
+ * const result = allResult(
+ *   [1, 2],
+ *   (number) => {
+ *     visited.push(number);
+ *     return ok(number * 2);
+ *   },
+ *   {
+ *     collect: false,
+ *   },
+ * );
+ * expectTypeOf(result).toEqualTypeOf<Result<void>>();
  * expectOk(result, undefined);
- * expect(updatedItemIds).toEqual(["item-1", "item-2"]);
+ * expect(visited).toEqual([1, 2]);
  * ```
  */
 export function allResult<A, R extends AnyResult>(
@@ -1270,7 +1126,21 @@ export function allResult<A, R extends AnyResult>(
   options: { readonly collect: false },
 ): Result<void, InferErr<R>>;
 
-/** Maps record values to Results without collecting their Ok values. */
+/**
+ * Maps record values to Results without collecting their Ok values.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import { allResult, ok, type Result } from "@evolu/common";
+ *
+ * const result = allResult({ a: 1, b: 2 }, (number) => ok(number * 2), {
+ *   collect: false,
+ * });
+ * expectTypeOf(result).toEqualTypeOf<Result<void>>();
+ * expectOk(result, undefined);
+ * ```
+ */
 export function allResult<A, R extends AnyResult, K extends string>(
   values: Readonly<Record<K, A>>,
   fn: (value: A) => R,
@@ -1357,52 +1227,19 @@ export function allResult(
  * import {
  *   anyResult,
  *   err,
- *   isNonEmptyArray,
  *   ok,
  *   type Result,
+ *   type Typed,
  * } from "@evolu/common";
  *
- * interface LookupError {
- *   readonly type: "LookupError";
- * }
- *
- * const results: ReadonlyArray<Result<number, LookupError>> = [
- *   err({ type: "LookupError" }),
- *   ok(42),
- * ];
- * if (isNonEmptyArray(results)) {
- *   const number = anyResult(results);
- *   expectTypeOf(number).toEqualTypeOf<Result<number, LookupError>>();
- *   expectOk(number, 42);
- * }
- * ```
- *
- * A statically non-empty tuple needs no guard:
- *
- * ```ts
- * import { anyResult, err, ok, type Result } from "@evolu/common";
- *
- * interface LookupError {
- *   readonly type: "LookupError";
- *   readonly source: string;
- * }
+ * const getCachedPrice = (): Result<number, CacheMissError> =>
+ *   err({ type: "CacheMiss" });
  *
- * const lookupError = (source: string): Result<never, LookupError> =>
- *   err({ type: "LookupError", source });
+ * interface CacheMissError extends Typed<"CacheMiss"> {}
  *
- * const results = [
- *   lookupError("first"),
- *   ok(42),
- *   lookupError("second"),
- * ] as const;
- * const number = anyResult(results);
- * expectTypeOf(number).toEqualTypeOf<Result<number, LookupError>>();
+ * const number = anyResult([getCachedPrice(), ok(42)]);
+ * expectTypeOf(number).toEqualTypeOf<Result<number, CacheMissError>>();
  * expectOk(number, 42);
- *
- * const allFailed = [lookupError("a"), lookupError("b")] as const;
- * const result = anyResult(allFailed);
- * expectTypeOf(result).toEqualTypeOf<Result<never, LookupError>>();
- * expectErr(result, { type: "LookupError", source: "b" });
  * ```
  *
  * @group Composition