@evolu/common 8.5.0 → 8.6.1

package/src/Function.ts

@@ -15,7 +15,7 @@ import type { Writable } from "./Types.ts";
  * ### Example
  *
  * ```ts
- * import { exhaustiveCheck } from "@evolu/common";
+ * import { assertEqual, exhaustiveCheck } from "@evolu/common";
  *
  * type Color = "red" | "green" | "blue";
  * const handled: Array<string> = [];
@@ -37,7 +37,7 @@ import type { Writable } from "./Types.ts";
  * };
  *
  * handleColor("blue");
- * expect(handled).toEqual(["Handling blue"]);
+ * assertEqual(handled, ["Handling blue"]);
  * ```
  *
  * Use this primarily in side-effect switches (`void` branches). For
@@ -47,6 +47,8 @@ import type { Writable } from "./Types.ts";
  * ### Return from every case
  *
  * ```ts
+ * import { assertEqual } from "@evolu/common";
+ *
  * type Color = "red" | "green" | "blue";
  *
  * const colorToHex = (color: Color): string => {
@@ -60,12 +62,14 @@ import type { Writable } from "./Types.ts";
  *   }
  * };
  *
- * expect(colorToHex("green")).toBe("#00ff00");
+ * assertEqual(colorToHex("green"), "#00ff00");
  * ```
  *
  * ### Assign in every case
  *
  * ```ts
+ * import { assertEqual } from "@evolu/common";
+ *
  * type Input =
  *   | { readonly type: "Mutate" }
  *   | { readonly type: "Query" }
@@ -89,7 +93,7 @@ import type { Writable } from "./Types.ts";
  *   return result;
  * };
  *
- * expect(inputToKind({ type: "Query" })).toBe("B");
+ * assertEqual(inputToKind({ type: "Query" }), "B");
  * ```
  */
 export const exhaustiveCheck = (value: never): never => {
@@ -105,16 +109,16 @@ export const exhaustiveCheck = (value: never): never => {
  * ### Example
  *
  * ```ts
- * import { identity } from "@evolu/common";
+ * import { assertEqual, assertSame, identity } from "@evolu/common";
  *
  * const values = [1, 2, 3];
  * const object = { value: 1 };
  * const getTransform = (shouldDouble: boolean) =>
  *   shouldDouble ? (value: number) => value * 2 : identity;
  *
- * expect(values.map(identity)).toEqual([1, 2, 3]);
- * expect(identity(object)).toBe(object);
- * expect(getTransform(false)(2)).toBe(2);
+ * assertEqual(values.map(identity), [1, 2, 3]);
+ * assertSame(identity(object), object);
+ * assertEqual(getTransform(false)(2), 2);
  * ```
  */
 export const identity = <A>(a: A): A => a;
@@ -139,7 +143,14 @@ export const identity = <A>(a: A): A => a;
  * ### Example
  *
  * ```ts
- * import { disposable } from "@evolu/common";
+ * import {
+ *   assert,
+ *   assertEqual,
+ *   assertErr,
+ *   assertTrue,
+ *   disposable,
+ *   trySync,
+ * } from "@evolu/common";
  *
  * let cleaned = false;
  * const createResource = () => {
@@ -151,11 +162,17 @@ export const identity = <A>(a: A): A => a;
  * };
  *
  * const resource = createResource();
- * expect(resource.read()).toBe("ready");
+ * assertEqual(resource.read(), "ready");
  * resource[Symbol.dispose]();
  *
- * expect(cleaned).toBe(true);
- * expect(() => resource.read()).toThrow("Cannot use a disposed object.");
+ * assertTrue(cleaned);
+ * const result = trySync(() => resource.read());
+ * assertErr(result);
+ * assert(
+ *   result.error instanceof Error &&
+ *     result.error.message === "Cannot use a disposed object.",
+ *   "Expected the disposed-object error.",
+ * );
  * ```
  */
 export function disposable<T extends object>(
@@ -217,7 +234,7 @@ export const isDisposable = (
  * ### Example
  *
  * ```ts
- * import { constVoid, type Thunk } from "@evolu/common";
+ * import { assertEqual, constVoid, type Thunk } from "@evolu/common";
  *
  * const notify = (onDone: Thunk<void> = constVoid) => onDone();
  * notify();
@@ -234,8 +251,8 @@ export const isDisposable = (
  *
  * const computed = compute();
  * jobs.shift()?.();
- * expect(computed).toBe(1);
- * expect(value).toBe(11);
+ * assertEqual(computed, 1);
+ * assertEqual(value, 11);
  * ```
  */
 export type Thunk<T> = () => T;
@@ -249,17 +266,17 @@ export type Thunk<T> = () => T;
  * ### Example
  *
  * ```ts
- * import { constant } from "@evolu/common";
+ * import { assertEqual, assertSame, constant } from "@evolu/common";
  *
  * let version = 0;
  * const readConfig = () => ({ version: ++version });
  * const getConstantConfig = constant(readConfig());
  * const getFreshConfig = () => readConfig();
  *
- * expect(getConstantConfig()).toBe(getConstantConfig());
- * expect(getConstantConfig().version).toBe(1);
- * expect(getFreshConfig().version).toBe(2);
- * expect(getFreshConfig().version).toBe(3);
+ * assertSame(getConstantConfig(), getConstantConfig());
+ * assertEqual(getConstantConfig().version, 1);
+ * assertEqual(getFreshConfig().version, 2);
+ * assertEqual(getFreshConfig().version, 3);
  * ```
  */
 export const constant =
@@ -293,7 +310,13 @@ export const constVoid: Thunk<void> = constUndefined;
  * ### Example
  *
  * ```ts
- * import { todo } from "@evolu/common";
+ * import {
+ *   assert,
+ *   assertErr,
+ *   assertType,
+ *   todo,
+ *   trySync,
+ * } from "@evolu/common";
  *
  * interface Config {
  *   readonly theme: string;
@@ -302,10 +325,17 @@ export const constVoid: Thunk<void> = constUndefined;
  * const getCount = (): number => todo();
  * const getConfig = () => todo<Config>();
  *
- * expectTypeOf<
+ * assertType<
+ *   [number, Config],
  *   [ReturnType<typeof getCount>, ReturnType<typeof getConfig>]
- * >().toEqualTypeOf<[number, Config]>();
- * expect(getCount).toThrow("not yet implemented");
+ * >();
+ * const result = trySync(getCount);
+ * assertErr(result);
+ * assert(
+ *   result.error instanceof Error &&
+ *     result.error.message === "not yet implemented",
+ *   "Expected the not-yet-implemented error.",
+ * );
  * ```
  */
 // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-parameters

package/src/Http.ts

@@ -194,7 +194,11 @@ export type FetchConsume<T, E = never> = (
  *
  * ```ts
  * import {
+ *   assertEqual,
+ *   assertOk,
+ *   assertType,
  *   createRun,
+ *   Data,
  *   exponential,
  *   fetch,
  *   retry,
@@ -220,7 +224,10 @@ export type FetchConsume<T, E = never> = (
  * };
  * await using run = createRun({ nativeFetch });
  *
- * expectOk(await run(fetchWithRetry("/api/user")), { name: "Ada" });
+ * const result = await run(fetchWithRetry("/api/user"));
+ * assertOk(result);
+ * assertType(Data, result.value);
+ * assertEqual(result.value, { name: "Ada" });
  * ```
  *
  * App conventions belong in small app-owned helpers. For example, posting JSON
@@ -229,7 +236,11 @@ export type FetchConsume<T, E = never> = (
  *
  * ```ts
  * import {
+ *   assertEqual,
+ *   assertOk,
+ *   assertType,
  *   createRun,
+ *   Data,
  *   fetch,
  *   type FetchError,
  *   type NativeFetch,
@@ -250,9 +261,10 @@ export type FetchConsume<T, E = never> = (
  *   Promise.resolve(new Response('{"id":"user-1"}'));
  * await using run = createRun({ nativeFetch });
  *
- * expectOk(await run(postJson("/api/users", { name: "Ada" })), {
- *   id: "user-1",
- * });
+ * const result = await run(postJson("/api/users", { name: "Ada" }));
+ * assertOk(result);
+ * assertType(Data, result.value);
+ * assertEqual(result.value, { id: "user-1" });
  * ```
  *
  * Your app's version will grow your conventions — auth, envelopes, error
@@ -265,7 +277,13 @@ export type FetchConsume<T, E = never> = (
  * libraries that expose client instances.
  *
  * ```ts
- * import { createRun, fetch, type NativeFetch } from "@evolu/common";
+ * import {
+ *   assertEqual,
+ *   assertOk,
+ *   createRun,
+ *   fetch,
+ *   type NativeFetch,
+ * } from "@evolu/common";
  *
  * const token = "secret-token";
  * const baseUrl = "https://api.example.com/v1/";
@@ -287,14 +305,17 @@ export type FetchConsume<T, E = never> = (
  * };
  *
  * await using run = createRun({ nativeFetch });
- * expectOk(await run(fetch("users", "text")), "ok");
- * expect({
- *   url: interceptedRequest?.url,
- *   authorization: interceptedRequest?.headers.get("authorization"),
- * }).toEqual({
- *   url: "https://api.example.com/v1/users",
- *   authorization: "Bearer secret-token",
- * });
+ * assertOk(await run(fetch("users", "text")), "ok");
+ * assertEqual(
+ *   {
+ *     url: interceptedRequest?.url,
+ *     authorization: interceptedRequest?.headers.get("authorization"),
+ *   },
+ *   {
+ *     url: "https://api.example.com/v1/users",
+ *     authorization: "Bearer secret-token",
+ *   },
+ * );
  * ```
  *
  * ### Consuming responses
@@ -305,7 +326,11 @@ export type FetchConsume<T, E = never> = (
  *
  * ```ts
  * import {
+ *   assertEqual,
+ *   assertOk,
+ *   assertType,
  *   createRun,
+ *   Data,
  *   fetch,
  *   ok,
  *   type FetchTransportError,
@@ -315,7 +340,7 @@ export type FetchConsume<T, E = never> = (
  *
  * const nativeFetch: NativeFetch = (input) =>
  *   Promise.resolve(
- *     String(input).endsWith("/metadata")
+ *     input === "/api/user/metadata"
  *       ? new Response(null, {
  *           status: 204,
  *           headers: { "cache-control": "max-age=60" },
@@ -331,11 +356,14 @@ export type FetchConsume<T, E = never> = (
  *     cache: response.headers.get("cache-control"),
  *   }),
  * );
- * expectTypeOf(metadata).toEqualTypeOf<
- *   Task<{ status: number; cache: string | null }, FetchTransportError>
+ * assertType<
+ *   Task<{ status: number; cache: string | null }, FetchTransportError>,
+ *   typeof metadata
  * >();
- * expectOk(user, { name: "Ada" });
- * expectOk(await run(metadata), { status: 204, cache: "max-age=60" });
+ * assertOk(user);
+ * assertType(Data, user.value);
+ * assertEqual(user.value, { name: "Ada" });
+ * assertOk(await run(metadata), { status: 204, cache: "max-age=60" });
  * ```
  *
  * ### Aborting fetch
@@ -346,6 +374,7 @@ export type FetchConsume<T, E = never> = (
  *
  * ```ts
  * import {
+ *   assert,
  *   AbortError,
  *   createRun,
  *   fetch,
@@ -356,6 +385,7 @@ export type FetchConsume<T, E = never> = (
  *   new Promise<Response>((_resolve, reject) => {
  *     const signal = init?.signal;
  *     if (!signal) throw new Error("Missing signal");
+ *     // oxlint-disable-next-line typescript/prefer-promise-reject-errors -- Fetch aborts with Task's structured AbortError.
  *     signal.addEventListener("abort", () => reject(signal.reason), {
  *       once: true,
  *     });
@@ -366,7 +396,10 @@ export type FetchConsume<T, E = never> = (
  * fiber.abort();
  * const result = await fiber;
  *
- * expect(!result.ok && AbortError.is(result.error)).toBe(true);
+ * assert(
+ *   !result.ok && AbortError.is(result.error),
+ *   "Expected an AbortError.",
+ * );
  * ```
  *
  * @group Fetch

package/src/Identicon.ts

@@ -32,7 +32,12 @@ export type IdenticonStyle = "github" | "quadrant" | "gradient" | "sutnar";
  * ### Example
  *
  * ```ts
- * import { createIdFromString, createIdenticon } from "@evolu/common";
+ * import {
+ *   assertEqual,
+ *   assertTrue,
+ *   createIdFromString,
+ *   createIdenticon,
+ * } from "@evolu/common";
  *
  * const id = createIdFromString("identicon-example");
  * const svg = createIdenticon(id);
@@ -45,9 +50,9 @@ export type IdenticonStyle = "github" | "quadrant" | "gradient" | "sutnar";
  * const todoId = createIdFromString<"Todo">("todo-1");
  * const todoSvg = createIdenticon(todoId);
  *
- * expect(svg.startsWith("<svg")).toBe(true);
- * expect(new Set([svg, ...alternativeSvgs]).size).toBe(4);
- * expect(todoSvg.startsWith("<svg")).toBe(true);
+ * assertTrue(svg.startsWith("<svg"));
+ * assertEqual(new Set([svg, ...alternativeSvgs]).size, 4);
+ * assertTrue(todoSvg.startsWith("<svg"));
  * ```
  */
 export const createIdenticon = (

package/src/LockManager.ts

@@ -20,30 +20,32 @@ import type { Callback } from "./Types.ts";
  * ### Web and Node.js 24+
  *
  * ```ts
- * import type { LockManagerDep } from "@evolu/common";
+ * import { assertEqual, type LockManagerDep } from "@evolu/common";
  *
  * const deps: LockManagerDep = {
  *   lockManager: globalThis.navigator.locks,
  * };
  *
- * const result = await deps.lockManager.request("example", (lock) => {
- *   return lock?.name;
- * });
- * expect(result).toBe("example");
+ * const result = await deps.lockManager.request(
+ *   "example",
+ *   (lock) => lock?.name,
+ * );
+ * assertEqual(result, "example");
  * ```
  *
  * ### React Native
  *
  * ```ts
- * import type { LockManagerDep } from "@evolu/common";
+ * import { assertEqual, type LockManagerDep } from "@evolu/common";
  * import { lockManager } from "@evolu/react-native";
  *
  * const deps: LockManagerDep = { lockManager };
  *
- * const result = await deps.lockManager.request("example", (lock) => {
- *   return lock?.name;
- * });
- * expect(result).toBe("example");
+ * const result = await deps.lockManager.request(
+ *   "example",
+ *   (lock) => lock?.name,
+ * );
+ * assertEqual(result, "example");
  * ```
  */
 

package/src/Lookup.ts

@@ -344,6 +344,8 @@ export type StructuralFunction = (...args: ReadonlyArray<unknown>) => unknown;
  *
  * ```ts
  * import {
+ *   assertEqual,
+ *   assertSame,
  *   createLookupMap,
  *   structuralLookup,
  *   type StructuralLookupKey,
@@ -368,8 +370,8 @@ export type StructuralFunction = (...args: ReadonlyArray<unknown>) => unknown;
  * };
  * byFilter.set(cachedFilter, "cached");
  *
- * expect(byFilter.get(equivalentFilter)).toBe("cached");
- * expect(byFilter.getKey(equivalentFilter)).toBe(cachedFilter);
+ * assertEqual(byFilter.get(equivalentFilter), "cached");
+ * assertSame(byFilter.getKey(equivalentFilter), cachedFilter);
  * ```
  *
  * @see {@link StructuralKey}

package/src/Number.ts

@@ -41,6 +41,7 @@ export type Int1To100 = Int1To99 | 100;
  *
  * ```ts
  * import {
+ *   assertEqual,
  *   NonNegativeInt,
  *   type Int0To100OrNonNegativeInt,
  * } from "@evolu/common";
@@ -48,8 +49,8 @@ export type Int1To100 = Int1To99 | 100;
  * const literal: Int0To100OrNonNegativeInt = 10;
  * const validated: Int0To100OrNonNegativeInt = NonNegativeInt.orThrow(101);
  *
- * assert(literal === 10);
- * assert(validated === 101);
+ * assertEqual(literal, 10);
+ * assertEqual(validated, 101);
  * ```
  */
 export type Int0To100OrNonNegativeInt = 0 | Int1To100 | NonNegativeInt;
@@ -63,13 +64,17 @@ export type Int0To100OrNonNegativeInt = 0 | Int1To100 | NonNegativeInt;
  * ### Example
  *
  * ```ts
- * import { PositiveInt, type Int1To100OrPositiveInt } from "@evolu/common";
+ * import {
+ *   assertEqual,
+ *   PositiveInt,
+ *   type Int1To100OrPositiveInt,
+ * } from "@evolu/common";
  *
  * const literal: Int1To100OrPositiveInt = 10;
  * const validated: Int1To100OrPositiveInt = PositiveInt.orThrow(101);
  *
- * assert(literal === 10);
- * assert(validated === 101);
+ * assertEqual(literal, 10);
+ * assertEqual(validated, 101);
  * ```
  */
 export type Int1To100OrPositiveInt = Int1To100 | PositiveInt;
@@ -83,12 +88,12 @@ export type Int1To100OrPositiveInt = Int1To100 | PositiveInt;
  * ### Example
  *
  * ```ts
- * import { Ratio, jitter } from "@evolu/common";
+ * import { Ratio, assertType, jitter } from "@evolu/common";
  *
  * const readableJitter = jitter("50%");
  * const computedJitter = jitter(Ratio.orThrow(0.5));
  *
- * expectTypeOf(readableJitter).toEqualTypeOf(computedJitter);
+ * assertType<typeof computedJitter, typeof readableJitter>();
  * ```
  */
 export type Percentage = PercentageLiteral | Ratio;
@@ -134,12 +139,12 @@ export const clamp =
  * ### Example
  *
  * ```ts
- * import { isBetween } from "@evolu/common";
+ * import { assertFalse, assertTrue, isBetween } from "@evolu/common";
  *
  * const isBetween10And20 = isBetween(10, 20);
  *
- * expect(isBetween10And20(20)).toBe(true);
- * expect(isBetween10And20(25)).toBe(false);
+ * assertTrue(isBetween10And20(20));
+ * assertFalse(isBetween10And20(25));
  * ```
  */
 export const isBetween =
@@ -168,27 +173,26 @@ export const max = <T extends number>(
  *
  * ```ts
  * import {
+ *   assertErr,
+ *   assertOk,
  *   computeBalancedBuckets,
  *   NonNegativeInt,
  *   PositiveInt,
  * } from "@evolu/common";
  *
- * expectOk(
- *   computeBalancedBuckets(
- *     NonNegativeInt.orThrow(10),
- *     PositiveInt.orThrow(3),
- *     PositiveInt.orThrow(2),
- *   ),
- *   [4, 7, 10],
+ * const balanced = computeBalancedBuckets(
+ *   NonNegativeInt.orThrow(10),
+ *   PositiveInt.orThrow(3),
+ *   PositiveInt.orThrow(2),
  * );
- * expectErr(
- *   computeBalancedBuckets(
- *     NonNegativeInt.orThrow(5),
- *     PositiveInt.orThrow(3),
- *     PositiveInt.orThrow(2),
- *   ),
- *   6,
+ * assertOk(balanced, [4, 7, 10]);
+ *
+ * const insufficient = computeBalancedBuckets(
+ *   NonNegativeInt.orThrow(5),
+ *   PositiveInt.orThrow(3),
+ *   PositiveInt.orThrow(2),
  * );
+ * assertErr(insufficient, 6);
  * ```
  */
 export const computeBalancedBuckets = (