@evolu/common 8.0.0-next.4 → 8.0.0

package/dist/src/Result.d.ts

@@ -1,11 +1,12 @@
 /**
- * Type-safe error handling with Result types.
+ * Type-safe error handling with the Result type.
  *
  * @module
  */
-import { type NonEmptyReadonlyArray } from "./Array.js";
-import type { Lazy } from "./Function.js";
-import type { Typed } from "./Type.js";
+import { type NonEmptyReadonlyArray } from "./Array.ts";
+import { type Thunk } from "./Function.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
  * unknown type. We can't be sure all errors have been handled because the
@@ -16,28 +17,48 @@ import type { Typed } from "./Type.js";
  * `Either` where errors are part of the return type. TypeScript can do the
  * same.
  *
+ * ## Example
+ *
  * ```ts
- * // With throw - caught value is unknown, can't use exhaustiveCheck
+ * import { err, exhaustiveCheck, type Result } from "@evolu/common";
+ *
+ * // TypeScript can't know what was thrown.
  * try {
- *   doSomething();
+ *   throw new Error("Not found");
  * } catch (error) {
- *   // error is unknown - TypeScript can't help us here
+ *   expectTypeOf(error).toEqualTypeOf<unknown>();
  * }
  *
- * // With Result - error type is known, exhaustiveCheck works
+ * // With Result, errors are part of the return type.
+ * const doSomething = (): Result<
+ *   number,
+ *   NotFoundError | InvalidInputError
+ * > => err({ type: "NotFound" });
+ *
+ * interface NotFoundError {
+ *   readonly type: "NotFound";
+ * }
+ *
+ * interface InvalidInputError {
+ *   readonly type: "InvalidInput";
+ * }
+ *
+ * // With Result, the error type is known and exhaustiveCheck works.
+ * // If we add another error type, TypeScript tells us it isn't handled.
  * const result = doSomething();
  * if (!result.ok) {
  *   switch (result.error.type) {
  *     case "NotFound":
- *       // handle not found
+ *       expect(result.error).toEqual({ type: "NotFound" });
  *       break;
  *     case "InvalidInput":
- *       // handle invalid input
+ *       expect(result.error).toEqual({ type: "InvalidInput" });
  *       break;
  *     default:
- *       exhaustiveCheck(result.error); // TypeScript ensures all cases handled
+ *       exhaustiveCheck(result.error);
  *   }
  * }
+ * expectErr(result, { type: "NotFound" });
  * ```
  *
  * A `Result` is either {@link Ok} (success with a value) or {@link Err} (failure
@@ -57,143 +78,250 @@ import type { Typed } from "./Type.js";
  * }
  * ```
  *
- * ## Example
+ * 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.
+ *
+ * ## Composition
+ *
+ * Since `Result` is a plain object, imperative code works naturally.
  *
  * ```ts
- * // Typed<T> adds { type: T } for discriminated unions
- * interface ParseJsonError extends Typed<"ParseJsonError"> {
- *   readonly message: string;
+ * import { ok, type Result } from "@evolu/common";
+ *
+ * interface User {
+ *   readonly id: string;
  * }
  *
- * const parseJson = (value: string): Result<unknown, ParseJsonError> => {
- *   try {
- *     return ok(JSON.parse(value));
- *   } catch (error) {
- *     return err({ type: "ParseJsonError", message: String(error) });
- *   }
- * };
+ * interface UserNotFoundError {
+ *   readonly type: "UserNotFoundError";
+ * }
  *
- * const json = parseJson('{"name": "Alice"}');
- * if (!json.ok) return json; // short-circuit on error
+ * interface Profile {
+ *   readonly userId: string;
+ * }
  *
- * // Now we have access to json.value (type: unknown)
- * console.log(json.value);
- * ```
+ * interface ProfileNotFoundError {
+ *   readonly type: "ProfileNotFoundError";
+ * }
  *
- * The caller doesn't need `try/catch`, just `if (!json.ok)`, and the error is
- * `ParseJsonError`, not `unknown`.
+ * const getUser = (): Result<User, UserNotFoundError> =>
+ *   ok({ id: "user-1" });
+ * const getProfile = (
+ *   userId: string,
+ * ): Result<Profile, ProfileNotFoundError> => ok({ userId });
  *
- * Use this pattern when the caller can recover or choose a different flow.
- * Parsing unknown JSON is a good fit because invalid input is expected and
- * actionable.
+ * const getCurrentProfile = (): Result<
+ *   Profile,
+ *   UserNotFoundError | ProfileNotFoundError
+ * > => {
+ *   const user = getUser();
+ *   if (!user.ok) return user;
  *
- * To avoid `try/catch` inside `parseJson` too, use {@link trySync}:
+ *   return getProfile(user.value.id);
+ * };
  *
- * ```ts
- * const parseJson = (value: string): Result<unknown, ParseJsonError> =>
- *   trySync(
- *     () => JSON.parse(value) as unknown,
- *     (error) => ({ type: "ParseJsonError", message: String(error) }),
- *   );
+ * const profile = getCurrentProfile();
+ * expectTypeOf(profile).toEqualTypeOf<
+ *   Result<Profile, UserNotFoundError | ProfileNotFoundError>
+ * >();
+ * expectOk(profile, { userId: "user-1" });
  * ```
  *
- * `trySync` and {@link tryAsync} are for intentionally converting thrown errors
- * into typed, recoverable {@link Result} values.
+ * {@link flatMapResult} is for a single local composition.
  *
- * Do not wrap every throwing API in {@link Result}. If an error is unrecoverable
- * and the caller has no meaningful fallback, let it throw and handle it at the
- * app boundary.
+ * ```ts
+ * import { flatMapResult, ok, type Result } from "@evolu/common";
  *
- * Since `Result` is a plain object, imperative code works naturally:
+ * interface User {
+ *   readonly id: string;
+ * }
  *
- * ### Stop on error, map on success
+ * interface UserNotFoundError {
+ *   readonly type: "UserNotFoundError";
+ * }
  *
- * ```ts
- * const users = getActiveUsers();
- * if (!users.ok) return users;
- * const usernames = mapArray(users.value, (u) => u.username);
+ * 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" });
  * ```
  *
- * ### Iterate array, stop on first error
+ * Use {@link allResult} to collect the Ok values from a collection of Results,
+ * or return the first Err.
  *
  * ```ts
- * for (const user of users) {
- *   const result = validateUser(user); // Result<ValidUser, ValidateUserError>
- *   if (!result.ok) return result;
+ * import { allResult, err, ok, type Result } from "@evolu/common";
+ *
+ * interface User {
+ *   readonly id: string;
  * }
- * ```
  *
- * ## Style
+ * interface Preferences {
+ *   readonly theme: "dark" | "light";
+ * }
  *
- * Imperative code is the preferred way to compose sequential {@link Result}
- * operations.
+ * interface LoadAccountError {
+ *   readonly type: "LoadAccountError";
+ *   readonly resource: "user" | "preferences";
+ * }
  *
- * ```ts
- * const user = getUser();
- * if (!user.ok) return user;
+ * 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",
+ * });
+ * ```
  *
- * const profile = getProfile(user.value.id);
- * if (!profile.ok) return profile;
+ * `allResult` can also map collection values to Results before collecting their
+ * Ok values. Mapping stops on the first Err.
  *
- * return ok({ user: user.value, profile: profile.value });
- * ```
+ * ```ts
+ * import { allResult, err, ok, type Result } from "@evolu/common";
  *
- * This is an intentional style choice. Evolu does not provide helper
- * combinators for every sequential pattern because that would duplicate plain
- * control flow and create API ambiguity. Use helpers when they add semantics
- * over ordinary control flow, such as operating on collections of results.
- * While it may seem verbose, it is explicit, transparent, and avoids pipes and
- * nested helpers, which are harder to debug.
+ * interface OrderLine {
+ *   readonly productId: string;
+ *   readonly quantity: number;
+ * }
  *
- * ## Composition
+ * interface ProductUnavailableError {
+ *   readonly type: "ProductUnavailableError";
+ *   readonly productId: string;
+ * }
  *
- * Some patterns are common enough that deserve helpers. The previous example
- * can be written with {@link mapResult}:
+ * 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);
+ * };
  *
- * ```ts
- * const result = mapResult(users, validateUser);
- * // Result<ValidUser[], ValidateUserError>
+ * 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",
+ * });
  * ```
  *
- * For an array of results, {@link allResult} extracts all values or returns the
- * first error:
+ * 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
- * const result = allResult(validationResults);
+ * 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
- * const result = anyResult(parserResults);
- * ```
+ * import { anyResult, err, ok, type Result } from "@evolu/common";
  *
- * ## Naming convention
+ * interface CacheMissError {
+ *   readonly type: "CacheMissError";
+ * }
  *
- * - Result with a value: name it after the value (`user`, `config`)
- * - Result without a value: name it `result`
+ * const getCachedPrice = (): Result<number, CacheMissError> =>
+ *   err({ type: "CacheMissError" });
  *
- * ```ts
- * const processUser = (): Result<
- *   void,
- *   GetUserError | SaveToDatabaseError | SendWelcomeEmailError
- * > => {
- *   const user = getUser();
- *   if (!user.ok) return user;
- *
- *   const result = saveToDatabase(user.value);
- *   if (!result.ok) return result;
+ * const prices = [getCachedPrice(), ok(20)] as const;
+ * const price = anyResult(prices);
+ * expectTypeOf(price).toEqualTypeOf<Result<number, CacheMissError>>();
+ * expectOk(price, 20);
+ * ```
  *
- *   // To avoid a clash with the previous `result`, use a block scope.
- *   {
- *     const result = sendWelcomeEmail(user.value);
- *     if (!result.ok) return result;
- *   }
+ * ## Naming convention
  *
- *   return ok();
- * };
- * ```
+ * 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.
  *
  * ## Unrecoverable errors
  *
@@ -201,16 +329,49 @@ import type { Typed } from "./Type.js";
  * These are unrecoverable errors: expected (you know they can happen) but only
  * handleable at the app level.
  *
- * Do not force these errors into {@link Result} just because the underlying API
+ * 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.
  *
- * In Evolu apps, that boundary is typically a platform `createRun` adapter such
- * as `@evolu/web`, `@evolu/nodejs`, or `@evolu/react-native`, which add
- * platform-specific global error handling.
+ * In Evolu apps, the root Run reports defects and the platform lifecycle API
+ * owns application shutdown. For example, `@evolu/nodejs` provides `runMain`.
  *
  * ## FAQ
  *
+ * ### Is Result expensive?
+ *
+ * Wrapping a value in Result creates one small plain object and is very cheap.
+ * Its cost is usually worth considering only when a performance-critical loop
+ * creates millions of Results. Use Result by default; if profiling identifies
+ * such a loop as a bottleneck, benchmark the complete workload before
+ * optimizing it.
+ *
+ * ### Why not generators?
+ *
+ * Generator-based APIs make sequential workflows more concise: `yield*`
+ * combines error propagation (roughly replacing `if (!result.ok) return
+ * result`) with unwrapping the success value. That doesn't come for free.
+ * Supporting direct `yield*` requires adding iterator behavior to every Result;
+ * otherwise every use needs an adapter. That makes Result more than plain
+ * structural data: after serialization, its iterator behavior must be restored
+ * before direct `yield*` works. Generator machinery also makes control flow,
+ * debugger stepping, and stack traces less direct while adding runtime
+ * overhead. Evolu instead keeps Result as plain data and makes error
+ * propagation explicit. With AI, explicit checks are cheap to write.
+ *
+ * Generators do not make accidental omission impossible: a function returning a
+ * lazy operation can be called without composing the returned value with
+ * `yield*`, leaving the operation out of the workflow, just as a
+ * Result-returning function can be called and its Result ignored. Dedicated
+ * tooling can detect these omissions, but that safety comes from the tooling,
+ * not generator syntax itself.
+ *
+ * The intended way to write Evolu code is with test-driven development (TDD).
+ * Tests document the intended behavior and serve as its runnable specification,
+ * including failure paths. AI makes writing and maintaining those tests cheap.
+ * {@link exhaustiveCheck} complements tests by having TypeScript report newly
+ * added error variants.
+ *
  * ### What if a function doesn't return a value on success?
  *
  * Use `Result<void, E>` and return `ok()` (no argument). Don't return
@@ -238,15 +399,28 @@ export interface Ok<out T> {
  * ### Example
  *
  * ```ts
+ * import { err, ok, type Result, type Typed } from "@evolu/common";
+ *
+ * interface User {
+ *   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 });
  *   return ok(user);
  * };
+ *
+ * expectOk(findUser("user-1"), { id: "user-1" });
+ * expectErr(findUser("missing"), {
+ *   type: "NotFoundError",
+ *   id: "missing",
+ * });
  * ```
  */
 export interface Err<out E> {
@@ -254,13 +428,13 @@ export interface Err<out E> {
     readonly error: E;
 }
 /**
- * Extracts the value type from a {@link Result}.
+ * Infers the success value type from a {@link Result}.
  *
  * @group Utilities
  */
 export type InferOk<R extends Result<any, any>> = R extends Ok<infer T> ? T : never;
 /**
- * Extracts the error type from a {@link Result}.
+ * Infers the error type from a {@link Result}.
  *
  * @group Utilities
  */
@@ -275,11 +449,15 @@ export type InferErr<R extends Result<any, any>> = R extends Err<infer E> ? E :
  * ### Example
  *
  * ```ts
- * const noValue = ok();
- * console.log(noValue); // { ok: true, value: undefined }
+ * import { ok, type Result } from "@evolu/common";
  *
+ * const noValue = ok();
  * const success = ok(42);
- * console.log(success); // { ok: true, value: 42 }
+ *
+ * expectTypeOf(noValue).toEqualTypeOf<Result<void>>();
+ * expectTypeOf(success).toEqualTypeOf<Result<number>>();
+ * expectOk(noValue, undefined);
+ * expectOk(success, 42);
  * ```
  */
 export declare function ok(): Result<void>;
@@ -292,7 +470,7 @@ export declare const isOk: <T, E>(result: Result<T, E>) => result is Ok<T>;
 /** Type guard for {@link Err} results. */
 export declare const isErr: <T, E>(result: Result<T, E>) => result is Err<E>;
 /**
- * Returns the value from an `Ok` {@link Result}, or throws if it is an `Err`.
+ * Gets the value from an `Ok` {@link Result}, or throws if it is an `Err`.
  *
  * Use this where failure should crash the current flow instead of being handled
  * locally.
@@ -300,8 +478,8 @@ export declare 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, errors are handled by platform-specific
- *   `createRun` adapters at the app boundary.
+ *   program immediately. In Evolu apps, the root Run reports the defect and the
+ *   platform lifecycle API handles shutdown.
  * - Module-level constants
  * - Test setup with values that are expected to be valid
  *
@@ -311,17 +489,38 @@ export declare const isErr: <T, E>(result: Result<T, E>) => result is Err<E>;
  * ### Example
  *
  * ```ts
- * // At app startup, crash if config is invalid:
+ * import { err, getOrThrow, ok, type Result } from "@evolu/common";
+ *
+ * interface Config {
+ *   readonly port: number;
+ * }
+ * interface InvalidConfigError {
+ *   readonly type: "InvalidConfigError";
+ * }
+ * const loadConfig = (): Result<Config, InvalidConfigError> =>
+ *   ok({ port: 3000 });
+ *
+ * // At app startup, crash if the config is invalid.
  * const config = getOrThrow(loadConfig());
- * // Safe to use config here
+ * expectTypeOf(config).toEqualTypeOf<Config>();
+ * expect(config).toEqual({ port: 3000 });
+ *
+ * try {
+ *   getOrThrow(err({ type: "InvalidConfigError" }));
+ *   assert.fail("Expected getOrThrow to throw");
+ * } catch (error) {
+ *   assert(error instanceof Error);
+ *   expect(error.message).toBe("getOrThrow");
+ *   expect(error.cause).toEqual({ type: "InvalidConfigError" });
+ * }
  * ```
  *
  * Throws: `Error` with the original error attached as `cause`.
  */
 export declare const getOrThrow: <T, E>(result: Result<T, E>) => T;
 /**
- * Extracts the value from a {@link Result} if it is an `Ok`, or returns `null`
- * if it is an `Err`.
+ * Gets the value from an `Ok` {@link Result}, or returns `null` if it is an
+ * `Err`.
  *
  * **Intended usage:**
  *
@@ -332,59 +531,147 @@ export declare const getOrThrow: <T, E>(result: Result<T, E>) => T;
  * ### Example
  *
  * ```ts
- * // For APIs that expect T | null
- * const user = getOrNull(findUser(id));
+ * import { err, getOrNull, ok, type Result } 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" });
+ *
+ * // For APIs that expect T | null.
+ * const user = getOrNull(findUser("user-1"));
+ * const missingUser = getOrNull(findUser("missing"));
+ *
+ * expectTypeOf(user).toEqualTypeOf<User | null>();
+ * expect(user).toEqual({ id: "user-1" });
+ * expect(missingUser).toBeNull();
  * ```
  */
 export declare const getOrNull: <T, E>(result: Result<T, E>) => T | null;
 /**
- * Extracts the value from a {@link Result} whose error type is `never`.
+ * Gets the value from a {@link Result} whose error type is `never`.
  *
  * This is useful when the type system guarantees the result cannot fail (for
  * example `Result<T, never>`), avoiding impossible `if (!result.ok)` branches
  * at call sites.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import { getOk, ok, type Result } from "@evolu/common";
+ *
+ * const getCount = (): Result<number> => ok(2);
+ * const count = getOk(getCount());
+ * expectTypeOf(count).toEqualTypeOf<number>();
+ * expect(count).toBe(2);
+ * ```
  */
 export declare const getOk: <T>(result: Result<T>) => T;
 /**
  * Wraps a synchronous function that may throw, returning a {@link Result}.
  *
- * Use this when the thrown value should become a typed, recoverable error for
- * the caller. Do not use it for failures that should terminate the current flow
- * and propagate to a global handler.
+ * `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.
  *
  * ### Example
  *
  * ```ts
- * const parseJson = (value: string): Result<unknown, ParseJsonError> =>
+ * import { trySync, type Result } from "@evolu/common";
+ *
+ * interface ReserveSeatError {
+ *   readonly type: "ReserveSeatError";
+ *   readonly seat: string;
+ * }
+ *
+ * class LegacySeatUnavailableError extends Error {}
+ *
+ * const legacyReserveSeat = (seat: string): void => {
+ *   if (seat === "A1") throw new LegacySeatUnavailableError();
+ *   if (seat === "B1") throw new Error("Unexpected database error");
+ * };
+ *
+ * const reserveSeat = (seat: string): Result<void, ReserveSeatError> =>
  *   trySync(
- *     () => JSON.parse(value) as unknown,
- *     (error) => ({ type: "ParseJsonError", message: String(error) }),
+ *     () => legacyReserveSeat(seat),
+ *     (error) => {
+ *       if (error instanceof LegacySeatUnavailableError) {
+ *         return { type: "ReserveSeatError", seat };
+ *       }
+ *       throw error;
+ *     },
  *   );
+ *
+ * const result = reserveSeat("B2");
+ * expectTypeOf(result).toEqualTypeOf<Result<void, ReserveSeatError>>();
+ * expectOk(result, undefined);
+ * expectErr(reserveSeat("A1"), { type: "ReserveSeatError", seat: "A1" });
+ * expect(() => reserveSeat("B1")).toThrow("Unexpected database error");
  * ```
  */
-export declare const trySync: <T, E>(fn: () => T, mapError: (error: unknown) => E) => Result<T, E>;
+export declare function trySync<T>(fn: () => T): Result<T, unknown>;
+export declare function trySync<T, E>(fn: () => T, mapError: (error: unknown) => E): Result<T, E>;
 /**
- * Wraps an async function that may throw, returning a {@link Result}.
+ * Wraps an async function that may throw or reject, returning a {@link Result}.
+ *
+ * `mapError` converts the caught `unknown` value into a typed domain error.
  *
- * Use this when the rejection should become a typed, recoverable error for the
- * caller. Do not use it for failures that should terminate the current flow and
- * propagate to a global handler.
+ * 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.
  *
  * ### Example
  *
  * ```ts
- * const fetchJson = (url: string): Promise<Result<unknown, FetchError>> =>
+ * import { tryAsync, type Result } from "@evolu/common";
+ *
+ * interface ReserveSeatError {
+ *   readonly type: "ReserveSeatError";
+ *   readonly seat: string;
+ * }
+ *
+ * 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");
+ * };
+ *
+ * const reserveSeat = (
+ *   seat: string,
+ * ): Promise<Result<void, ReserveSeatError>> =>
  *   tryAsync(
- *     async () => {
- *       const response = await fetch(url);
- *       if (!response.ok) throw new Error(`Status ${response.status}`);
- *       return response.json();
+ *     () => legacyReserveSeat(seat),
+ *     (error) => {
+ *       if (error instanceof LegacySeatUnavailableError) {
+ *         return { type: "ReserveSeatError", seat };
+ *       }
+ *       throw error;
  *     },
- *     (error) => ({ type: "FetchError", message: String(error) }),
  *   );
+ *
+ * const result = await reserveSeat("B2");
+ * expectTypeOf(result).toEqualTypeOf<Result<void, ReserveSeatError>>();
+ * expectOk(result, undefined);
+ * expectErr(await reserveSeat("A1"), {
+ *   type: "ReserveSeatError",
+ *   seat: "A1",
+ * });
+ * await expect(reserveSeat("B1")).rejects.toThrow(
+ *   "Unexpected database error",
+ * );
  * ```
  */
-export declare const tryAsync: <T, E>(lazyPromise: Lazy<Promise<T>>, mapError: (error: unknown) => E) => Promise<Result<T, E>>;
+export declare function tryAsync<T>(promiseThunk: Thunk<Awaitable<T>>): Promise<Result<T, unknown>>;
+export declare function tryAsync<T, E>(promiseThunk: Thunk<Awaitable<T>>, mapError: (error: unknown) => E): Promise<Result<T, E>>;
 /**
  * A result for a pull-based protocol with three outcomes.
  *
@@ -396,6 +683,30 @@ export declare const tryAsync: <T, E>(lazyPromise: Lazy<Promise<T>>, mapError: (
  * - `Err<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";
+ * }
+ *
+ * const next = (index: number): NextResult<string, ReadError, number> => {
+ *   if (index === 0) return ok("first");
+ *   if (index === 1) return err({ type: "ReadError" });
+ *   return err(done(index));
+ * };
+ *
+ * const value = next(0);
+ * expectTypeOf(value).toEqualTypeOf<
+ *   NextResult<string, ReadError, number>
+ * >();
+ * expectOk(value, "first");
+ * expectErr(next(1), { type: "ReadError" });
+ * expectErr(next(2), { type: "Done", done: 2 });
+ * ```
  */
 export type NextResult<A, E = never, D = void> = Result<A, E | Done<D>>;
 /**
@@ -415,6 +726,19 @@ export interface Done<out D = unknown> extends Typed<"Done"> {
  *
  * - `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
+ *
+ * ```ts
+ * import { done, type Done } from "@evolu/common";
+ *
+ * const withoutValue = done();
+ * const withValue = done(42);
+ * expectTypeOf(withoutValue).toEqualTypeOf<Done<void>>();
+ * expectTypeOf(withValue).toEqualTypeOf<Done<number>>();
+ * expect(withoutValue).toEqual({ type: "Done", done: undefined });
+ * expect(withValue).toEqual({ type: "Done", done: 42 });
+ * ```
  */
 export declare function done(): Done<void>;
 /** With a done value. */
@@ -425,6 +749,15 @@ export declare function done<D>(value: D): Done<D>;
  * Useful for pull-based protocols where completion is encoded in the error
  * channel (for example {@link NextResult}).
  *
+ * ### Example
+ *
+ * ```ts
+ * import { type Done, type ExcludeDone } from "@evolu/common";
+ *
+ * type Errors = "ReadError" | Done<number>;
+ * expectTypeOf<ExcludeDone<Errors>>().toEqualTypeOf<"ReadError">();
+ * ```
+ *
  * @group Utilities
  */
 export type ExcludeDone<E> = Exclude<E, Done<any>>;
@@ -434,30 +767,124 @@ export type ExcludeDone<E> = Exclude<E, Done<any>>;
  * Useful for pull-based protocols where completion is encoded in the error
  * channel (for example {@link NextResult}).
  *
+ * ### Example
+ *
+ * ```ts
+ * import { type Done, type OnlyDone } from "@evolu/common";
+ *
+ * type Errors = "ReadError" | Done<number>;
+ * expectTypeOf<OnlyDone<Errors>>().toEqualTypeOf<Done<number>>();
+ * ```
+ *
  * @group Utilities
  */
 export type OnlyDone<E> = Extract<E, Done<any>>;
 /**
- * Extracts the done value type from a {@link NextResult}.
+ * Infers the done value type from a {@link NextResult}.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import { type InferDone, type NextResult } from "@evolu/common";
+ *
+ * type ReadResult = NextResult<string, "ReadError", number>;
+ * expectTypeOf<InferDone<ReadResult>>().toEqualTypeOf<number>();
+ * ```
  *
  * @group Utilities
  */
 export type InferDone<R extends Result<any, any>> = InferErr<R> extends infer Errors ? Errors extends Done<infer D> ? D : never : never;
 /**
- * Extracts all values from an array of {@link Result}s.
+ * Composes a successful {@link Result} with another Result-returning operation.
+ *
+ * Returns the existing error without calling the operation when the Result has
+ * failed.
+ *
+ * Do not nest `flatMapResult`. For longer workflows, use explicit checks, which
+ * keep names, intermediate values, and control flow flat and easy to read.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import { err, flatMapResult, ok, type Result } from "@evolu/common";
+ *
+ * interface User {
+ *   readonly id: string;
+ * }
+ * interface UserError {
+ *   readonly type: "UserError";
+ * }
+ *
+ * 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);
+ * expectTypeOf(profile).toEqualTypeOf<
+ *   Result<Profile, UserError | ProfileError>
+ * >();
+ * 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
+ */
+export declare const flatMapResult: <T, E, U, F>(result: Result<T, E>, fn: (value: T) => Result<U, F>) => Result<U, E | F>;
+/**
+ * Collects the Ok values from a collection of {@link Result}s, or maps
+ * collection values to Results and collects their Ok values.
  *
  * Returns the first error if any result fails.
  *
+ * Pass `{ collect: false }` to return `Result<void, E>` without storing the Ok
+ * values in an output collection.
+ *
  * ### Example
  *
  * ```ts
- * const results = [ok(1), ok(2), ok(3)];
- * const all = allResult(results);
- * // ok([1, 2, 3])
+ * import { allResult, err, ok, type Result } from "@evolu/common";
+ *
+ * interface CountError {
+ *   readonly type: "CountError";
+ * }
+ * interface LabelError {
+ *   readonly type: "LabelError";
+ * }
+ *
+ * const getCount = (): Result<number, CountError> => ok(2);
+ * const getLabel = (): Result<string, LabelError> => ok("books");
  *
- * const withError = [ok(1), err("fail"), ok(3)];
- * const failed = allResult(withError);
- * // err("fail")
+ * const values = allResult([getCount(), getLabel()]);
+ * expectTypeOf(values).toEqualTypeOf<
+ *   Result<readonly [number, string], CountError | LabelError>
+ * >();
+ * expectOk(values, [2, "books"]);
+ *
+ * const numbers = allResult([
+ *   ok(1),
+ *   err({ type: "CountError" }),
+ *   err({ type: "LabelError" }),
+ * ]);
+ * expectErr(numbers, { type: "CountError" });
  * ```
  *
  * @group Composition
@@ -466,11 +893,19 @@ export declare function allResult<const T extends readonly [AnyResult, ...Readon
     [K in keyof T]: InferOk<T[K]>;
 }, InferErr<T[number]>>;
 /**
- * Returns object with same keys.
+ * Returns an object with the same keys.
+ *
+ * ### Example
  *
  * ```ts
- * const result = allResult({ a: ok(1), b: ok(2) });
- * // ok({ a: 1, b: 2 })
+ * import { allResult, ok, type Result } from "@evolu/common";
+ *
+ * const resultsByName = { a: ok(1), b: ok(2) } as const;
+ * const valuesByName = allResult(resultsByName);
+ * expectTypeOf(valuesByName).toEqualTypeOf<
+ *   Result<{ readonly a: number; readonly b: number }>
+ * >();
+ * expectOk(valuesByName, { a: 1, b: 2 });
  * ```
  */
 export declare function allResult<T extends Readonly<Record<string, AnyResult>>>(results: T): Result<{
@@ -481,91 +916,303 @@ export declare function allResult<T extends Readonly<Record<string, AnyResult>>>
 /**
  * For dynamic or generated result lists.
  *
+ * Stops consuming the iterable on the first Err.
+ *
+ * ### Example
+ *
  * ```ts
- * const results: ReadonlyArray<Result<number, Error>> = getResults();
- * const all = allResult(results);
- * // Result<ReadonlyArray<number>, Error>
+ * import { allResult, err, ok, type Result } from "@evolu/common";
+ *
+ * interface LoadNumberError {
+ *   readonly type: "LoadNumberError";
+ * }
+ *
+ * const results: ReadonlyArray<Result<number, LoadNumberError>> = [
+ *   ok(1),
+ *   err({ type: "LoadNumberError" }),
+ * ];
+ * const numbers = allResult(results);
+ * expectTypeOf(numbers).toEqualTypeOf<
+ *   Result<ReadonlyArray<number>, LoadNumberError>
+ * >();
+ * expectErr(numbers, { type: "LoadNumberError" });
  * ```
  */
 export declare function allResult<T, E>(results: Iterable<Result<T, E>>): Result<ReadonlyArray<T>, E>;
 /**
- * Guarantees non-empty result.
+ * Preserves a non-empty array on success.
+ *
+ * ### Example
  *
  * ```ts
- * const results: NonEmptyReadonlyArray<Result<number, Error>> = [
- *   ok(1),
- *   ok(2),
- * ];
- * const all = allResult(results);
- * // Result<NonEmptyReadonlyArray<number>, Error>
+ * import {
+ *   allResult,
+ *   ok,
+ *   type NonEmptyReadonlyArray,
+ *   type Result,
+ * } from "@evolu/common";
+ *
+ * const results: NonEmptyReadonlyArray<Result<number>> = [ok(1), ok(2)];
+ * const numbers = allResult(results);
+ * expectTypeOf(numbers).toEqualTypeOf<
+ *   Result<NonEmptyReadonlyArray<number>>
+ * >();
+ * expectOk(numbers, [1, 2]);
  * ```
  */
 export declare function allResult<T, E>(results: NonEmptyReadonlyArray<Result<T, E>>): Result<NonEmptyReadonlyArray<T>, E>;
+/** Does not collect the Ok values from a record of Results. */
+export declare function allResult<T extends Readonly<Record<string, AnyResult>>>(results: T, options: {
+    readonly collect: false;
+}): Result<void, [keyof T] extends [never] ? never : InferErr<T[keyof T]>>;
 /**
- * Maps items to {@link Result}s and extracts all values.
+ * Does not collect the Ok values from an iterable of Results.
  *
- * Returns the first error if any result fails.
+ * 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.
  *
  * ### Example
  *
  * ```ts
- * const users = [{ id: 1 }, { id: 2 }];
- * const result = mapResult(users, validateUser);
- * // Result<ReadonlyArray<ValidUser>, ValidateUserError>
+ * import { allResult, err, ok, type Result } from "@evolu/common";
+ *
+ * interface SaveError {
+ *   readonly type: "SaveError";
+ * }
+ *
+ * const results: ReadonlyArray<Result<number, SaveError>> = [
+ *   ok(1),
+ *   err({ type: "SaveError" }),
+ * ];
+ * const result = allResult(results, { collect: false });
+ * expectTypeOf(result).toEqualTypeOf<Result<void, SaveError>>();
+ * expectErr(result, { type: "SaveError" });
  * ```
+ */
+export declare function allResult<R extends AnyResult>(results: Iterable<R>, options: {
+    readonly collect: false;
+}): Result<void, InferErr<R>>;
+/**
+ * Maps a non-empty array or tuple to Results and preserves its shape.
  *
- * @group Composition
+ * ### Example
+ *
+ * ```ts
+ * import {
+ *   allResult,
+ *   ok,
+ *   type NonEmptyReadonlyArray,
+ *   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>
+ * >();
+ * expectOk(invoices, [{ orderId: "order-1" }]);
+ *
+ * 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" }]);
+ * ```
+ */
+export declare function allResult<const A extends readonly [unknown, ...Array<unknown>], R extends AnyResult>(values: A, fn: (value: A[number]) => R): Result<{
+    [K in keyof A]: InferOk<R>;
+}, InferErr<R>>;
+/**
+ * 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);
+ * };
+ *
+ * const productIds: Iterable<string> = new Set(["book", "pen"]);
+ * const prices = allResult(productIds, getPrice);
+ * expectTypeOf(prices).toEqualTypeOf<
+ *   Result<ReadonlyArray<number>, ProductNotFoundError>
+ * >();
+ * expectOk(prices, [20, 5]);
+ * ```
  */
-export declare function mapResult<const A extends readonly [unknown, ...Array<unknown>], T, E>(items: A, fn: (a: A[number]) => Result<T, E>): Result<{
-    [K in keyof A]: T;
-}, E>;
+export declare function allResult<A, R extends AnyResult>(values: Iterable<A>, fn: (value: A) => R): Result<ReadonlyArray<InferOk<R>>, InferErr<R>>;
 /**
- * For dynamic or generated item lists.
+ * Maps record values to Results and preserves the record's keys.
+ *
+ * ### Example
  *
  * ```ts
- * const users = [{ id: 1 }, { id: 2 }];
- * const result = mapResult(users, validateUser);
- * // Result<ReadonlyArray<ValidUser>, ValidateUserError>
+ * import { allResult, err, 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 userIdsByRole = { owner: "user-1", reviewer: "user-2" } as const;
+ * const usersByRole = allResult(userIdsByRole, findUser);
+ * expectTypeOf(usersByRole).toEqualTypeOf<
+ *   Result<Readonly<Record<"owner" | "reviewer", User>>, UserNotFoundError>
+ * >();
+ * expectOk(usersByRole, {
+ *   owner: { id: "user-1" },
+ *   reviewer: { id: "user-2" },
+ * });
  * ```
  */
-export declare function mapResult<A, T, E>(items: Iterable<A>, fn: (a: A) => Result<T, E>): Result<ReadonlyArray<T>, E>;
+export declare function allResult<A, R extends AnyResult, K extends string>(values: Readonly<Record<K, A>>, fn: (value: A) => R): Result<Readonly<Record<K, InferOk<R>>>, InferErr<R>>;
 /**
- * Returns object with same keys.
+ * Maps values to Results without collecting their Ok values.
+ *
+ * This avoids allocating the output collection even when the mapped operations
+ * return success values.
+ *
+ * ### Example
  *
  * ```ts
- * const result = mapResult({ a: 1, b: 2 }, double);
- * // Result<{ a: number, b: number }, DoubleError>
+ * 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>>();
+ * expectOk(result, undefined);
+ * expect(updatedItemIds).toEqual(["item-1", "item-2"]);
  * ```
  */
-export declare function mapResult<A, T, E, K extends string>(items: Readonly<Record<K, A>>, fn: (a: A) => Result<T, E>): Result<Readonly<Record<K, T>>, E>;
+export declare function allResult<A, R extends AnyResult>(values: Iterable<A>, fn: (value: A) => R, options: {
+    readonly collect: false;
+}): Result<void, InferErr<R>>;
+/** Maps record values to Results without collecting their Ok values. */
+export declare function allResult<A, R extends AnyResult, K extends string>(values: Readonly<Record<K, A>>, fn: (value: A) => R, options: {
+    readonly collect: false;
+}): Result<void, InferErr<R>>;
 /**
  * Returns the first successful {@link Result}.
  *
  * If all results fail, returns the last error.
  *
  * Requires a non-empty array — there's no "first success" with zero
- * participants. Use {@link isNonEmptyArray} to guard:
+ * participants. Use {@link isNonEmptyArray} to guard.
+ *
+ * ### Example
  *
  * ```ts
+ * import {
+ *   anyResult,
+ *   err,
+ *   isNonEmptyArray,
+ *   ok,
+ *   type Result,
+ * } from "@evolu/common";
+ *
+ * interface LookupError {
+ *   readonly type: "LookupError";
+ * }
+ *
+ * const results: ReadonlyArray<Result<number, LookupError>> = [
+ *   err({ type: "LookupError" }),
+ *   ok(42),
+ * ];
  * if (isNonEmptyArray(results)) {
- *   const result = anyResult(results);
+ *   const number = anyResult(results);
+ *   expectTypeOf(number).toEqualTypeOf<Result<number, LookupError>>();
+ *   expectOk(number, 42);
  * }
  * ```
  *
- * ### Example
+ * A statically non-empty tuple needs no guard:
  *
  * ```ts
- * const results = [err("fail1"), ok(42), err("fail2")];
- * if (isNonEmptyArray(results)) {
- *   const result = anyResult(results);
- *   // ok(42)
- * }
+ * import { anyResult, err, ok, type Result } from "@evolu/common";
  *
- * const allFailed = [err("a"), err("b"), err("c")];
- * if (isNonEmptyArray(allFailed)) {
- *   const result = anyResult(allFailed);
- *   // err("c") — last error
+ * interface LookupError {
+ *   readonly type: "LookupError";
+ *   readonly source: string;
  * }
+ *
+ * const lookupError = (source: string): Result<never, LookupError> =>
+ *   err({ type: "LookupError", source });
+ *
+ * const results = [
+ *   lookupError("first"),
+ *   ok(42),
+ *   lookupError("second"),
+ * ] as const;
+ * const number = anyResult(results);
+ * expectTypeOf(number).toEqualTypeOf<Result<number, LookupError>>();
+ * 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