@evolu/common 8.4.0 → 8.6.0

package/src/Assert.ts

@@ -1,11 +1,21 @@
 /**
- * Runtime assertions for invariant checking.
+ * Runtime assertions for invariants and value checks.
  *
  * @module
  */
 
 import type { NonEmptyArray, NonEmptyReadonlyArray } from "./Array.ts";
-import type { Type } from "./Type.ts";
+import { eqData, eqStrict, type Eq } from "./Eq.ts";
+import type {
+  AnyResult,
+  Err,
+  InferErr,
+  InferOk,
+  Ok,
+  Result,
+} from "./Result.ts";
+import type { Data, IsData, Type } from "./Type.ts";
+import type { CompileTimeError } from "./Types.ts";
 
 /**
  * Ensures a condition is true, throwing an error with the provided message if
@@ -21,23 +31,283 @@ import type { Type } from "./Type.ts";
  * ### Example
  *
  * ```ts
- * import { assert as assertInvariant } from "@evolu/common";
+ * import { assert, assertEqual, assertErr, trySync } from "@evolu/common";
  *
- * expect(() => assertInvariant(true, "Expected true.")).not.toThrow();
- * expect(() => assertInvariant(false, "Expected true.")).toThrow(
- *   "Expected true.",
- * );
+ * assert(true, "Expected true.");
+ * const result = trySync(() => assert(false, "Expected true."));
+ * assertErr(result);
+ * assert(result.error instanceof Error, "Expected an Error.");
+ * assertEqual(result.error.message, "Expected true.");
  * ```
  */
 export const assert: (
   condition: unknown,
   message: string,
 ) => asserts condition = (condition, message) => {
+  // oxlint-disable-next-line typescript/strict-boolean-expressions -- JavaScript truthiness is the contract of assert.
   if (!condition) {
     throw new Error(message);
   }
 };
 
+/**
+ * Asserts that two values are the same according to {@link eqStrict}.
+ *
+ * `eqStrict` uses SameValue equality: it considers `NaN` the same as itself,
+ * distinguishes `0` from `-0`, and compares objects by reference identity.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import { assertSame, assertType } from "@evolu/common";
+ *
+ * interface User {
+ *   readonly name: string;
+ * }
+ *
+ * const user: User = { name: "Ada" };
+ * const value: unknown = user;
+ *
+ * assertSame(value, user);
+ * assertType<User, typeof value>();
+ * ```
+ */
+export const assertSame: <Expected>(
+  actual: unknown,
+  expected: Expected,
+) => asserts actual is Expected = (actual, expected) => {
+  assert(eqStrict(actual, expected), "Expected values to be the same.");
+};
+
+/**
+ * Asserts that a value is exactly `true` and narrows it to `true`.
+ *
+ * Unlike {@link assert}, this checks an exact boolean value instead of
+ * truthiness and does not require a custom message.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import { assertTrue, assertType } from "@evolu/common";
+ *
+ * const value: unknown = true;
+ * assertTrue(value);
+ * assertType<true, typeof value>();
+ * ```
+ */
+export const assertTrue: (value: unknown) => asserts value is true = (
+  value,
+) => {
+  assert(value === true, "Expected true.");
+};
+
+/**
+ * Asserts that a value is exactly `false` and narrows it to `false`.
+ *
+ * Unlike {@link assert}, this checks an exact boolean value instead of falsiness
+ * and does not require a custom message.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import { assertFalse, assertType } from "@evolu/common";
+ *
+ * const value: unknown = false;
+ * assertFalse(value);
+ * assertType<false, typeof value>();
+ * ```
+ */
+export const assertFalse: (value: unknown) => asserts value is false = (
+  value,
+) => {
+  assert(value === false, "Expected false.");
+};
+
+/**
+ * Asserts that two {@link Data} values are equal according to {@link eqData}.
+ *
+ * Use this for concise value checks in platform-independent examples. Use
+ * {@link assert} with a descriptive message for application invariants.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import { assertEqual } from "@evolu/common";
+ *
+ * const actual = new Map([["roles", new Set(["admin", "author"])]]);
+ * const expected = new Map([["roles", new Set(["author", "admin"])]]);
+ *
+ * assertEqual(actual, expected);
+ * ```
+ */
+export function assertEqual<Actual, Expected>(
+  actual: Actual,
+  expected: Expected,
+  ...dataError: AssertEqualError<Actual | Expected>
+): void;
+export function assertEqual(actual: Data, expected: Data): void {
+  assert(eqData(actual, expected), "Expected values to be equal.");
+}
+
+type AssertEqualError<Value> =
+  IsData<Value> extends true
+    ? []
+    : [
+        error: CompileTimeError<
+          "assertEqual",
+          "Actual and expected values must consist only of Data."
+        >,
+      ];
+
+/**
+ * Asserts that a {@link Result} is an {@link Ok}, optionally compares its value,
+ * and narrows the Result.
+ *
+ * With only a Result, this checks the variant without inspecting the value.
+ * When an expected value is provided, it uses {@link eqData}; its Data type is
+ * inferred independently, so an unbranded literal can compare a branded
+ * primitive or collection. Pass a custom {@link Eq} when either value is outside
+ * {@link Data} or needs domain-specific equality.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import {
+ *   assertEqual,
+ *   assertOk,
+ *   assertType,
+ *   ok,
+ *   type Ok,
+ *   type Result,
+ *   type Typed,
+ * } from "@evolu/common";
+ *
+ * interface User {
+ *   readonly id: string;
+ * }
+ *
+ * interface UserNotFoundError extends Typed<"UserNotFound"> {}
+ *
+ * const result: Result<User, UserNotFoundError> = ok({ id: "user-1" });
+ *
+ * assertOk(result);
+ * assertType<Ok<User>, typeof result>();
+ * assertEqual(result.value.id, "user-1");
+ * ```
+ */
+export function assertOk<R extends Result<unknown, unknown>>(
+  result: R,
+): asserts result is Extract<R, Ok<unknown>>;
+export function assertOk<R extends Result<unknown, unknown>>(
+  result: R,
+  expectedValue: InferOk<R>,
+  eq: Eq<InferOk<R>>,
+): asserts result is Extract<R, Ok<unknown>>;
+// Constrain the argument tuple so any cannot absorb the CompileTimeError.
+export function assertOk<R extends Result<unknown, unknown>, ExpectedValue>(
+  result: R,
+  ...comparison: [expectedValue: ExpectedValue] &
+    (IsData<InferOk<R> | ExpectedValue> extends true
+      ? unknown
+      : {
+          readonly [
+            Error in CompileTimeError<
+              "assertOk",
+              "Result value and expected value must consist only of Data when no custom Eq is provided."
+            >
+          ]: never;
+        })
+): asserts result is Extract<R, Ok<unknown>>;
+export function assertOk(
+  result: AnyResult,
+  ...comparison: [] | [expectedValue: unknown, eq?: Eq<any>]
+): asserts result is Ok<unknown> {
+  assert(result.ok, "Expected an Ok result.");
+  if (comparison.length === 0) return;
+
+  const expectedValue = comparison[0];
+  const eq: Eq<any> = comparison[1] ?? eqData;
+  assert(
+    eq(result.value, expectedValue),
+    "Expected the value to equal the expected value.",
+  );
+}
+
+/**
+ * Asserts that a {@link Result} is an {@link Err}, optionally compares its error,
+ * and narrows the Result.
+ *
+ * With only a Result, this checks the variant without inspecting the error.
+ * When an expected error is provided, it uses {@link eqData}; its Data type is
+ * inferred independently, so an unbranded literal can compare a branded
+ * primitive or collection. Pass a custom {@link Eq} when either value is outside
+ * {@link Data} or needs domain-specific equality.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import {
+ *   assertEqual,
+ *   assertErr,
+ *   assertType,
+ *   err,
+ *   type Err,
+ *   type Result,
+ *   type Typed,
+ * } from "@evolu/common";
+ *
+ * interface UserNotFoundError extends Typed<"UserNotFound"> {
+ *   readonly id: string;
+ * }
+ *
+ * const result: Result<string, UserNotFoundError> = err({
+ *   type: "UserNotFound",
+ *   id: "user-1",
+ * });
+ *
+ * assertErr(result);
+ * assertType<Err<UserNotFoundError>, typeof result>();
+ * assertEqual(result.error.id, "user-1");
+ * ```
+ */
+export function assertErr<R extends Result<unknown, unknown>>(
+  result: R,
+): asserts result is Extract<R, Err<unknown>>;
+export function assertErr<R extends Result<unknown, unknown>>(
+  result: R,
+  expectedError: InferErr<R>,
+  eq: Eq<InferErr<R>>,
+): asserts result is Extract<R, Err<unknown>>;
+// Constrain the argument tuple so any cannot absorb the CompileTimeError.
+export function assertErr<R extends Result<unknown, unknown>, ExpectedError>(
+  result: R,
+  ...comparison: [expectedError: ExpectedError] &
+    (IsData<InferErr<R> | ExpectedError> extends true
+      ? unknown
+      : {
+          readonly [
+            Error in CompileTimeError<
+              "assertErr",
+              "Result error and expected error must consist only of Data when no custom Eq is provided."
+            >
+          ]: never;
+        })
+): asserts result is Extract<R, Err<unknown>>;
+export function assertErr(
+  result: AnyResult,
+  ...comparison: [] | [expectedError: unknown, eq?: Eq<any>]
+): asserts result is Err<unknown> {
+  assert(!result.ok, "Expected an Err result.");
+  if (comparison.length === 0) return;
+
+  const expectedError = comparison[0];
+  const eq: Eq<any> = comparison[1] ?? eqData;
+  assert(
+    eq(result.error, expectedError),
+    "Expected the error to equal the expected error.",
+  );
+}
+
 /**
  * Asserts that a value is non-nullable.
  *
@@ -64,15 +334,23 @@ export const assertNonNullable: <T>(
  * ### Example
  *
  * ```ts
- * import { assertNotNull } from "@evolu/common";
+ * import {
+ *   assert,
+ *   assertEqual,
+ *   assertErr,
+ *   assertNotNull,
+ *   assertType,
+ *   trySync,
+ * } from "@evolu/common";
  *
  * const value = undefined as string | null | undefined;
  * assertNotNull(value);
- * expectTypeOf(value).toEqualTypeOf<string | undefined>();
- * expect(value).toBeUndefined();
- * expect(() => assertNotNull(null)).toThrow(
- *   "Expected value not to be null.",
- * );
+ * assertType<string | undefined, typeof value>();
+ * assertEqual(value, undefined);
+ * const result = trySync(() => assertNotNull(null));
+ * assertErr(result);
+ * assert(result.error instanceof Error, "Expected an Error.");
+ * assertEqual(result.error.message, "Expected value not to be null.");
  * ```
  */
 export const assertNotNull: <T>(
@@ -94,15 +372,23 @@ export const assertNotNull: <T>(
  * ### Example
  *
  * ```ts
- * import { assertNotUndefined } from "@evolu/common";
+ * import {
+ *   assert,
+ *   assertEqual,
+ *   assertErr,
+ *   assertNotUndefined,
+ *   assertType,
+ *   trySync,
+ * } from "@evolu/common";
  *
  * const value = null as string | null | undefined;
  * assertNotUndefined(value);
- * expectTypeOf(value).toEqualTypeOf<string | null>();
- * expect(value).toBeNull();
- * expect(() => assertNotUndefined(undefined)).toThrow(
- *   "Expected value not to be undefined.",
- * );
+ * assertType<string | null, typeof value>();
+ * assertEqual(value, null);
+ * const result = trySync(() => assertNotUndefined(undefined));
+ * assertErr(result);
+ * assert(result.error instanceof Error, "Expected an Error.");
+ * assertEqual(result.error.message, "Expected value not to be undefined.");
  * ```
  */
 export const assertNotUndefined: <T>(
@@ -124,13 +410,21 @@ export const assertNotUndefined: <T>(
  * ### Example
  *
  * ```ts
- * import { assertNonEmptyArray, type NonEmptyArray } from "@evolu/common";
+ * import {
+ *   assertEqual,
+ *   assertErr,
+ *   assertNonEmptyArray,
+ *   assertType,
+ *   trySync,
+ *   type NonEmptyArray,
+ * } from "@evolu/common";
  *
  * const values = [1, 2, 3];
  * assertNonEmptyArray(values);
- * expectTypeOf(values).toEqualTypeOf<NonEmptyArray<number>>();
- * expect(values[0]).toBe(1);
- * expect(() => assertNonEmptyArray([])).toThrow();
+ * assertType<NonEmptyArray<number>, typeof values>();
+ * assertEqual(values[0], 1);
+ * const result = trySync(() => assertNonEmptyArray([]));
+ * assertErr(result);
  * ```
  */
 export const assertNonEmptyArray: <T>(
@@ -153,15 +447,20 @@ export const assertNonEmptyArray: <T>(
  *
  * ```ts
  * import {
+ *   assertEqual,
+ *   assertErr,
  *   assertNonEmptyReadonlyArray,
+ *   assertType,
+ *   trySync,
  *   type NonEmptyReadonlyArray,
  * } from "@evolu/common";
  *
  * const values: ReadonlyArray<number> = [1, 2, 3];
  * assertNonEmptyReadonlyArray(values);
- * expectTypeOf(values).toEqualTypeOf<NonEmptyReadonlyArray<number>>();
- * expect(values[0]).toBe(1);
- * expect(() => assertNonEmptyReadonlyArray([])).toThrow();
+ * assertType<NonEmptyReadonlyArray<number>, typeof values>();
+ * assertEqual(values[0], 1);
+ * const result = trySync(() => assertNonEmptyReadonlyArray([]));
+ * assertErr(result);
  * ```
  */
 export const assertNonEmptyReadonlyArray: <T>(
@@ -182,14 +481,21 @@ export const assertNonEmptyReadonlyArray: <T>(
  * ### Example
  *
  * ```ts
- * import { assertNotDisposed } from "@evolu/common";
+ * import {
+ *   assert,
+ *   assertEqual,
+ *   assertErr,
+ *   assertNotDisposed,
+ *   trySync,
+ * } from "@evolu/common";
  *
  * await using disposer = new globalThis.AsyncDisposableStack();
- * expect(() => assertNotDisposed(disposer)).not.toThrow();
+ * assertNotDisposed(disposer);
  * await disposer.disposeAsync();
- * expect(() => assertNotDisposed(disposer)).toThrow(
- *   "Cannot use a disposed object.",
- * );
+ * const result = trySync(() => assertNotDisposed(disposer));
+ * assertErr(result);
+ * assert(result.error instanceof Error, "Expected an Error.");
+ * assertEqual(result.error.message, "Cannot use a disposed object.");
  * ```
  *
  * This is the JavaScript equivalent of the .NET `ObjectDisposedException`

package/src/BigInt.ts

@@ -24,12 +24,12 @@ export const clampBigInt =
  * ### Example
  *
  * ```ts
- * import { isBetweenBigInt } from "@evolu/common";
+ * import { assertFalse, assertTrue, isBetweenBigInt } from "@evolu/common";
  *
  * const isBetween10And20 = isBetweenBigInt(10n, 20n);
  *
- * expect(isBetween10And20(20n)).toBe(true);
- * expect(isBetween10And20(25n)).toBe(false);
+ * assertTrue(isBetween10And20(20n));
+ * assertFalse(isBetween10And20(25n));
  * ```
  */
 export const isBetweenBigInt =

package/src/Brand.ts

@@ -18,7 +18,7 @@
  * ### Single brand
  *
  * ```ts
- * import type { Brand } from "@evolu/common";
+ * import { assertEqual, type Brand } from "@evolu/common";
  *
  * type UserId = number & Brand<"UserId">;
  *
@@ -27,7 +27,7 @@
  * const createUserId = (value: number): UserId => value as UserId;
  * const getUser = (id: UserId): number => id;
  * const userId = createUserId(123);
- * expect(getUser(userId)).toBe(123);
+ * assertEqual(getUser(userId), 123);
  * // @ts-expect-error A plain number is not a UserId.
  * getUser(123);
  * ```
@@ -35,7 +35,7 @@
  * ### Multiple brands
  *
  * ```ts
- * import type { Brand } from "@evolu/common";
+ * import { assertEqual, type Brand } from "@evolu/common";
  *
  * type Min1 = string & Brand<"Min1">;
  * type Max100 = string & Brand<"Max100">;
@@ -46,8 +46,8 @@
  *
  * const min1Max100Value: Min1Max100 = "typescript" as Min1Max100;
  *
- * expect(requiresMin1(min1Max100Value)).toBe("typescript");
- * expect(requiresMax100(min1Max100Value)).toBe("typescript");
+ * assertEqual(requiresMin1(min1Max100Value), "typescript");
+ * assertEqual(requiresMax100(min1Max100Value), "typescript");
  * ```
  *
  * ### Standalone brand
@@ -59,7 +59,7 @@
  * code platform-agnostic.
  *
  * ```ts
- * import type { Brand } from "@evolu/common";
+ * import { assertSame, type Brand } from "@evolu/common";
  *
  * type NativePort = Brand<"NativePort">;
  *
@@ -67,7 +67,7 @@
  *
  * const nativeValue: unknown = { id: 1 };
  * const port = nativeValue as NativePort;
- * expect(requiresNativePort(port)).toBe(nativeValue);
+ * assertSame(requiresNativePort(port), nativeValue);
  * // @ts-expect-error An unknown value is not a NativePort.
  * requiresNativePort(nativeValue);
  * ```

package/src/Buffer.ts

@@ -52,6 +52,9 @@ export class BufferError extends Error {
  *
  * ```ts
  * import {
+ *   assert,
+ *   assertEqual,
+ *   assertErr,
  *   createBuffer,
  *   createIdFromString,
  *   IdBytes,
@@ -59,6 +62,7 @@ export class BufferError extends Error {
  *   idBytesTypeValueLength,
  *   idToIdBytes,
  *   NonNegativeInt,
+ *   trySync,
  * } from "@evolu/common";
  * import {
  *   decodeNonNegativeInt,
@@ -71,13 +75,17 @@ export class BufferError extends Error {
  * buffer.extend(idToIdBytes(id));
  *
  * const decoder = createBuffer(buffer.unwrap());
- * expect(decodeNonNegativeInt(decoder)).toBe(300);
+ * assertEqual(decodeNonNegativeInt(decoder), 300);
  * const decodedId = idBytesToId(
  *   IdBytes.orThrow(decoder.shiftN(idBytesTypeValueLength)),
  * );
- * expect(decodedId).toBe(id);
- * expect(() => decodeNonNegativeInt(decoder)).toThrow(
- *   "Buffer parse ended prematurely",
+ * assertEqual(decodedId, id);
+ * const result = trySync(() => decodeNonNegativeInt(decoder));
+ * assertErr(result);
+ * assert(
+ *   result.error instanceof Error &&
+ *     result.error.message === "Buffer parse ended prematurely",
+ *   "Expected the premature-buffer-end error.",
  * );
  * ```
  *

package/src/Cache.ts

@@ -43,16 +43,21 @@ export interface Cache<K, V> {
  * ### Example
  *
  * ```ts
- * import { createLruCache, PositiveInt } from "@evolu/common";
+ * import {
+ *   assertEqual,
+ *   assertFalse,
+ *   createLruCache,
+ *   PositiveInt,
+ * } from "@evolu/common";
  *
  * const cache = createLruCache<string, number>(PositiveInt.orThrow(2));
  * cache.set("a", 1);
  * cache.set("b", 2);
  * // Reading "a" makes "b" the least recently used entry.
- * expect(cache.get("a")).toBe(1);
+ * assertEqual(cache.get("a"), 1);
  * cache.set("c", 3);
  *
- * expect(cache.has("b")).toBe(false);
+ * assertFalse(cache.has("b"));
  * ```
  */
 export const createLruCache = <K, V>(capacity: PositiveInt): Cache<K, V> => {

package/src/Callbacks.ts

@@ -25,7 +25,11 @@ import type { Callback } from "./Types.ts";
  * ### Correlating callback responses
  *
  * ```ts
- * import { createCallbacks, testCreateDeps } from "@evolu/common";
+ * import {
+ *   assertEqual,
+ *   createCallbacks,
+ *   testCreateDeps,
+ * } from "@evolu/common";
  *
  * const deps = testCreateDeps();
  *
@@ -37,7 +41,7 @@ import type { Callback } from "./Types.ts";
  * });
  * callbacks.execute(noArgumentId);
  * callbacks.execute(noArgumentId);
- * expect(noArgumentCalls).toBe(1);
+ * assertEqual(noArgumentCalls, 1);
  *
  * // Typed callback
  * using stringCallbacks = createCallbacks<string>(deps);
@@ -46,14 +50,14 @@ import type { Callback } from "./Types.ts";
  *   received = value;
  * });
  * stringCallbacks.execute(stringCallbackId, "hello");
- * expect(received).toBe("hello");
+ * assertEqual(received, "hello");
  *
  * // Promise.withResolvers
  * using promiseCallbacks = createCallbacks<string>(deps);
  * const { promise, resolve } = Promise.withResolvers<string>();
  * const promiseCallbackId = promiseCallbacks.register(resolve);
  * promiseCallbacks.execute(promiseCallbackId, "resolved value");
- * expect(await promise).toBe("resolved value");
+ * assertEqual(await promise, "resolved value");
  * ```
  *
  * @template T - The type of argument passed to callbacks (defaults to undefined