@evolu/common 8.3.2 → 8.4.0

package/dist/src/Assert.d.ts

@@ -3,6 +3,7 @@
  *
  * @module
  */
+import type { NonEmptyArray, NonEmptyReadonlyArray } from "./Array.ts";
 /**
  * Ensures a condition is true, throwing an error with the provided message if
  * not.
@@ -10,9 +11,9 @@
  * Prevents invalid states from propagating through the system by halting
  * execution when a condition fails, improving reliability and debuggability.
  *
- * Do not use this instead of {@link Type}. Assertions are intended for
- * conditions that are logically guaranteed but not statically known by
- * TypeScript, or for catching and signaling developer mistakes eagerly.
+ * Do not use this instead of {@link Type}. Assertions are intended when a
+ * condition is logically guaranteed to be true but TypeScript cannot prove it,
+ * or for catching and signaling developer mistakes eagerly.
  *
  * ### Example
  *
@@ -29,52 +30,94 @@ export declare const assert: (condition: unknown, message: string) => asserts co
 /**
  * Asserts that a value is non-nullable.
  *
- * Narrows a nullable value to {@link NonNullable} when null or undefined is
- * logically impossible but TypeScript cannot prove it.
+ * Following TypeScript's {@link NonNullable}, non-nullable here means neither
+ * null nor undefined. Use this when a value is logically guaranteed to be
+ * non-nullable but TypeScript cannot prove it.
  */
 export declare const assertNonNullable: <T>(value: T, message?: string) => asserts value is NonNullable<T>;
+/**
+ * Asserts that a value is not null while preserving undefined.
+ *
+ * Use this when a value is logically guaranteed not to be null but TypeScript
+ * cannot prove it.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import { assertNotNull } 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.",
+ * );
+ * ```
+ */
+export declare const assertNotNull: <T>(value: T, message?: string) => asserts value is T & ({} | undefined);
+/**
+ * Asserts that a value is not undefined while preserving null.
+ *
+ * Use this when a value is logically guaranteed not to be undefined but
+ * TypeScript cannot prove it.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import { assertNotUndefined } 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.",
+ * );
+ * ```
+ */
+export declare const assertNotUndefined: <T>(value: T, message?: string) => asserts value is T & ({} | null);
 /**
  * Asserts that an array is non-empty.
  *
- * Ensures the provided array has at least one element, helping TypeScript infer
- * the array as non-empty when this is logically guaranteed but not statically
- * known.
+ * Use this when an array is logically guaranteed to be non-empty but TypeScript
+ * cannot prove it.
  *
  * ### Example
  *
  * ```ts
- * import { assertNonEmptyArray } from "@evolu/common";
+ * import { assertNonEmptyArray, type NonEmptyArray } from "@evolu/common";
  *
  * const values = [1, 2, 3];
  * assertNonEmptyArray(values);
- * expectTypeOf(values).toEqualTypeOf<[number, ...Array<number>]>();
+ * expectTypeOf(values).toEqualTypeOf<NonEmptyArray<number>>();
  * expect(values[0]).toBe(1);
  * expect(() => assertNonEmptyArray([])).toThrow();
  * ```
  */
-export declare const assertNonEmptyArray: <T>(arr: Array<T>, message?: string) => asserts arr is [T, ...Array<T>];
+export declare const assertNonEmptyArray: <T>(arr: Array<T>, message?: string) => asserts arr is NonEmptyArray<T>;
 /**
  * Asserts that a readonly array is non-empty.
  *
- * Ensures the provided readonly array has at least one element, helping
- * TypeScript infer non-emptiness when this is logically guaranteed but not
- * statically known.
+ * Use this when a readonly array is logically guaranteed to be non-empty but
+ * TypeScript cannot prove it.
  *
  * ### Example
  *
  * ```ts
- * import { assertNonEmptyReadonlyArray } from "@evolu/common";
+ * import {
+ *   assertNonEmptyReadonlyArray,
+ *   type NonEmptyReadonlyArray,
+ * } from "@evolu/common";
  *
  * const values: ReadonlyArray<number> = [1, 2, 3];
  * assertNonEmptyReadonlyArray(values);
- * expectTypeOf(values).toEqualTypeOf<
- *   readonly [number, ...Array<number>]
- * >();
+ * expectTypeOf(values).toEqualTypeOf<NonEmptyReadonlyArray<number>>();
  * expect(values[0]).toBe(1);
  * expect(() => assertNonEmptyReadonlyArray([])).toThrow();
  * ```
  */
-export declare const assertNonEmptyReadonlyArray: <T>(arr: ReadonlyArray<T>, message?: string) => asserts arr is readonly [T, ...Array<T>];
+export declare const assertNonEmptyReadonlyArray: <T>(arr: ReadonlyArray<T>, message?: string) => asserts arr is NonEmptyReadonlyArray<T>;
 /**
  * Guards synchronous methods on objects that may be called after disposal.
  *

package/dist/src/Assert.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Assert.d.ts","sourceRoot":"","sources":["../../src/Assert.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,MAAM,EAAE,CACnB,SAAS,EAAE,OAAO,EAClB,OAAO,EAAE,MAAM,KACZ,OAAO,CAAC,SAIZ,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,EAAE,CAAC,CAAC,EAChC,KAAK,EAAE,CAAC,EACR,OAAO,CAAC,EAAE,MAAM,KACb,OAAO,CAAC,KAAK,IAAI,WAAW,CAAC,CAAC,CAKlC,CAAC;AAEF;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,mBAAmB,EAAE,CAAC,CAAC,EAClC,GAAG,EAAE,KAAK,CAAC,CAAC,CAAC,EACb,OAAO,CAAC,EAAE,MAAM,KACb,OAAO,CAAC,GAAG,IAAI,CAAC,CAAC,EAAE,GAAG,KAAK,CAAC,CAAC,CAAC,CAKlC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,2BAA2B,EAAE,CAAC,CAAC,EAC1C,GAAG,EAAE,aAAa,CAAC,CAAC,CAAC,EACrB,OAAO,CAAC,EAAE,MAAM,KACb,OAAO,CAAC,GAAG,IAAI,SAAS,CAAC,CAAC,EAAE,GAAG,KAAK,CAAC,CAAC,CAAC,CAK3C,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,iBAAiB,UAE1B,eAAe,GAAG,oBAAoB,GAAG;IAAE,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;CAAE,KACxE,IAEF,CAAC"}
+{"version":3,"file":"Assert.d.ts","sourceRoot":"","sources":["../../src/Assert.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAGvE;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,MAAM,EAAE,CACnB,SAAS,EAAE,OAAO,EAClB,OAAO,EAAE,MAAM,KACZ,OAAO,CAAC,SAIZ,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,EAAE,CAAC,CAAC,EAChC,KAAK,EAAE,CAAC,EACR,OAAO,CAAC,EAAE,MAAM,KACb,OAAO,CAAC,KAAK,IAAI,WAAW,CAAC,CAAC,CAKlC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,aAAa,EAAE,CAAC,CAAC,EAC5B,KAAK,EAAE,CAAC,EACR,OAAO,CAAC,EAAE,MAAM,KACb,OAAO,CAAC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,GAAG,SAAS,CAKxC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,kBAAkB,EAAE,CAAC,CAAC,EACjC,KAAK,EAAE,CAAC,EACR,OAAO,CAAC,EAAE,MAAM,KACb,OAAO,CAAC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,GAAG,IAAI,CAKnC,CAAC;AAEF;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,mBAAmB,EAAE,CAAC,CAAC,EAClC,GAAG,EAAE,KAAK,CAAC,CAAC,CAAC,EACb,OAAO,CAAC,EAAE,MAAM,KACb,OAAO,CAAC,GAAG,IAAI,aAAa,CAAC,CAAC,CAKlC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,2BAA2B,EAAE,CAAC,CAAC,EAC1C,GAAG,EAAE,aAAa,CAAC,CAAC,CAAC,EACrB,OAAO,CAAC,EAAE,MAAM,KACb,OAAO,CAAC,GAAG,IAAI,qBAAqB,CAAC,CAAC,CAK1C,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,iBAAiB,UAE1B,eAAe,GAAG,oBAAoB,GAAG;IAAE,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;CAAE,KACxE,IAEF,CAAC"}

package/dist/src/Assert.js

@@ -10,9 +10,9 @@
  * Prevents invalid states from propagating through the system by halting
  * execution when a condition fails, improving reliability and debuggability.
  *
- * Do not use this instead of {@link Type}. Assertions are intended for
- * conditions that are logically guaranteed but not statically known by
- * TypeScript, or for catching and signaling developer mistakes eagerly.
+ * Do not use this instead of {@link Type}. Assertions are intended when a
+ * condition is logically guaranteed to be true but TypeScript cannot prove it,
+ * or for catching and signaling developer mistakes eagerly.
  *
  * ### Example
  *
@@ -33,27 +33,73 @@ export const assert = (condition, message) => {
 /**
  * Asserts that a value is non-nullable.
  *
- * Narrows a nullable value to {@link NonNullable} when null or undefined is
- * logically impossible but TypeScript cannot prove it.
+ * Following TypeScript's {@link NonNullable}, non-nullable here means neither
+ * null nor undefined. Use this when a value is logically guaranteed to be
+ * non-nullable but TypeScript cannot prove it.
  */
 export const assertNonNullable = (value, message = "Expected value to be non-nullable.") => {
     assert(value != null, message);
 };
+/**
+ * Asserts that a value is not null while preserving undefined.
+ *
+ * Use this when a value is logically guaranteed not to be null but TypeScript
+ * cannot prove it.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import { assertNotNull } 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.",
+ * );
+ * ```
+ */
+export const assertNotNull = (value, message = "Expected value not to be null.") => {
+    assert(value !== null, message);
+};
+/**
+ * Asserts that a value is not undefined while preserving null.
+ *
+ * Use this when a value is logically guaranteed not to be undefined but
+ * TypeScript cannot prove it.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import { assertNotUndefined } 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.",
+ * );
+ * ```
+ */
+export const assertNotUndefined = (value, message = "Expected value not to be undefined.") => {
+    assert(value !== undefined, message);
+};
 /**
  * Asserts that an array is non-empty.
  *
- * Ensures the provided array has at least one element, helping TypeScript infer
- * the array as non-empty when this is logically guaranteed but not statically
- * known.
+ * Use this when an array is logically guaranteed to be non-empty but TypeScript
+ * cannot prove it.
  *
  * ### Example
  *
  * ```ts
- * import { assertNonEmptyArray } from "@evolu/common";
+ * import { assertNonEmptyArray, type NonEmptyArray } from "@evolu/common";
  *
  * const values = [1, 2, 3];
  * assertNonEmptyArray(values);
- * expectTypeOf(values).toEqualTypeOf<[number, ...Array<number>]>();
+ * expectTypeOf(values).toEqualTypeOf<NonEmptyArray<number>>();
  * expect(values[0]).toBe(1);
  * expect(() => assertNonEmptyArray([])).toThrow();
  * ```
@@ -64,20 +110,20 @@ export const assertNonEmptyArray = (arr, message = "Expected a non-empty array."
 /**
  * Asserts that a readonly array is non-empty.
  *
- * Ensures the provided readonly array has at least one element, helping
- * TypeScript infer non-emptiness when this is logically guaranteed but not
- * statically known.
+ * Use this when a readonly array is logically guaranteed to be non-empty but
+ * TypeScript cannot prove it.
  *
  * ### Example
  *
  * ```ts
- * import { assertNonEmptyReadonlyArray } from "@evolu/common";
+ * import {
+ *   assertNonEmptyReadonlyArray,
+ *   type NonEmptyReadonlyArray,
+ * } from "@evolu/common";
  *
  * const values: ReadonlyArray<number> = [1, 2, 3];
  * assertNonEmptyReadonlyArray(values);
- * expectTypeOf(values).toEqualTypeOf<
- *   readonly [number, ...Array<number>]
- * >();
+ * expectTypeOf(values).toEqualTypeOf<NonEmptyReadonlyArray<number>>();
  * expect(values[0]).toBe(1);
  * expect(() => assertNonEmptyReadonlyArray([])).toThrow();
  * ```

package/dist/src/local-first/Db.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Db.d.ts","sourceRoot":"","sources":["../../../src/local-first/Db.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAaH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,EACL,aAAa,EAGd,MAAM,cAAc,CAAC;AAEtB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAIxD,OAAO,KAAK,EACV,qBAAqB,EAGrB,YAAY,EACb,MAAM,cAAc,CAAC;AAUtB,OAAO,EAAsB,KAAK,IAAI,EAAE,MAAM,YAAY,CAAC;AAE3D,OAAO,EAOL,KAAK,IAAI,EAEV,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EACV,yBAAyB,EACzB,iBAAiB,EACjB,MAAM,EACN,UAAU,EACV,UAAU,EACX,MAAM,cAAc,CAAC;AAqBtB,OAAO,KAAK,EAEV,aAAa,EACb,cAAc,EAGf,MAAM,aAAa,CAAC;AA+BrB,MAAM,MAAM,QAAQ,GAAG,MAAM,CAAC,YAAY,CAAC,CAAC;AAE5C,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAC9B,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IACpB,QAAQ,CAAC,YAAY,EAAE,YAAY,CAAC;IACpC,QAAQ,CAAC,YAAY,EAAE,YAAY,CAAC;IACpC,QAAQ,CAAC,aAAa,EAAE,aAAa,CAAC;IACtC,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC,cAAc,EAAE,aAAa,CAAC,CAAC;CACjE;AAED,MAAM,MAAM,cAAc,GAAG,MAAM,QAAQ,CAAC;AAE5C,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,cAAc,EAAE,cAAc,CAAC;CACzC;AAED,MAAM,MAAM,YAAY,GAAG,UAAU,GACnC,yBAAyB,GACzB,cAAc,GACd,qBAAqB,CAAC;AAExB;;;GAGG;AACH,eAAO,MAAM,aAAa,SACjB,UAAU,CAAC,YAAY,CAAC,KAAG,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE,YAAY,CAwM/D,CAAC"}
+{"version":3,"file":"Db.d.ts","sourceRoot":"","sources":["../../../src/local-first/Db.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAaH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,EACL,aAAa,EAGd,MAAM,cAAc,CAAC;AAEtB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAIxD,OAAO,KAAK,EACV,qBAAqB,EAGrB,YAAY,EACb,MAAM,cAAc,CAAC;AAUtB,OAAO,EAAsB,KAAK,IAAI,EAAE,MAAM,YAAY,CAAC;AAE3D,OAAO,EAQL,KAAK,IAAI,EACV,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EACV,yBAAyB,EACzB,iBAAiB,EACjB,MAAM,EACN,UAAU,EACV,UAAU,EACX,MAAM,cAAc,CAAC;AAqBtB,OAAO,KAAK,EAEV,aAAa,EACb,cAAc,EAGf,MAAM,aAAa,CAAC;AA+BrB,MAAM,MAAM,QAAQ,GAAG,MAAM,CAAC,YAAY,CAAC,CAAC;AAE5C,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAC9B,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IACpB,QAAQ,CAAC,YAAY,EAAE,YAAY,CAAC;IACpC,QAAQ,CAAC,YAAY,EAAE,YAAY,CAAC;IACpC,QAAQ,CAAC,aAAa,EAAE,aAAa,CAAC;IACtC,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC,cAAc,EAAE,aAAa,CAAC,CAAC;CACjE;AAED,MAAM,MAAM,cAAc,GAAG,MAAM,QAAQ,CAAC;AAE5C,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,cAAc,EAAE,cAAc,CAAC;CACzC;AAED,MAAM,MAAM,YAAY,GAAG,UAAU,GACnC,yBAAyB,GACzB,cAAc,GACd,qBAAqB,CAAC;AAExB;;;GAGG;AACH,eAAO,MAAM,aAAa,SACjB,UAAU,CAAC,YAAY,CAAC,KAAG,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE,YAAY,CAwM/D,CAAC"}

package/dist/src/local-first/Db.js

@@ -56,7 +56,7 @@ var __disposeResources = (this && this.__disposeResources) || (function (Suppres
     return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
 });
 import { appendToArray, firstInArray, } from "../Array.js";
-import { assert, assertNonEmptyReadonlyArray, assertNonNullable, } from "../Assert.js";
+import { assertNonEmptyReadonlyArray, assertNonNullable, assertNotUndefined, } from "../Assert.js";
 import { EncryptionKey, } from "../Crypto.js";
 import { constFalse, constVoid } from "../Function.js";
 import { acquireLeaderLock } from "../LockManager.js";
@@ -414,7 +414,7 @@ const createClientStorage = (deps) => ({ onError, }) => {
     let encryptionKey = null;
     let didWriteMessages = false;
     const getEncryptionKey = () => {
-        assert(encryptionKey != null, "ClientStorage encryption key must be set");
+        assertNonNullable(encryptionKey, "ClientStorage encryption key must be set");
         return encryptionKey;
     };
     return {
@@ -557,7 +557,7 @@ const applyLocalOnlyChange = (deps) => (change) => {
         const ownerId = change.ownerId;
         const columns = dbChangeToColumns(change, deps.time.now());
         for (const [column, value] of columns) {
-            assertNonNullable(value);
+            assertNotUndefined(value);
             deps.sqlite.exec(sql.prepared `
           insert into ${sql.identifier(change.table)}
             ("ownerId", "id", ${sql.identifier(column)})
@@ -577,7 +577,7 @@ const applyMessages = (deps) => (ownerId, messages) => {
         const idBytes = idToIdBytes(change.id);
         const timestampBytes = timestampToTimestampBytes(timestamp);
         for (const [column, value] of columns) {
-            assertNonNullable(value);
+            assertNotUndefined(value);
             if (validateColumnValue(deps)(change.table, column, value)) {
                 applyColumnChange(deps)(ownerIdBytes, ownerId, change.table, idBytes, change.id, column, value, timestampBytes);
             }

package/dist/src/local-first/Protocol.js

@@ -884,7 +884,7 @@ const sync = (deps) => (ranges, output, ownerIdBytes) => {
         nonSkipRangeAdded = true;
         if (skip) {
             skip = false;
-            assert(prevUpperBound != null, "prevUpperBound is null");
+            assertNonNullable(prevUpperBound, "prevUpperBound is null");
             // There is always a space for a skip range before adding.
             output.addRange({
                 type: RangeType.Skip,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@evolu/common",
-  "version": "8.3.2",
+  "version": "8.4.0",
   "description": "TypeScript library and local-first platform",
   "keywords": [
     "evolu",
@@ -72,7 +72,7 @@
     "@standard-schema/spec": "^1.1.0",
     "kysely": "^0.29.5",
     "msgpackr": "^2.0.5",
-    "random": "^5.4.1"
+    "random": "5.5.1"
   },
   "devDependencies": {
     "@types/node": "^24.10.9",

package/src/Assert.ts

@@ -4,6 +4,7 @@
  * @module
  */
 
+import type { NonEmptyArray, NonEmptyReadonlyArray } from "./Array.ts";
 import type { Type } from "./Type.ts";
 
 /**
@@ -13,9 +14,9 @@ import type { Type } from "./Type.ts";
  * Prevents invalid states from propagating through the system by halting
  * execution when a condition fails, improving reliability and debuggability.
  *
- * Do not use this instead of {@link Type}. Assertions are intended for
- * conditions that are logically guaranteed but not statically known by
- * TypeScript, or for catching and signaling developer mistakes eagerly.
+ * Do not use this instead of {@link Type}. Assertions are intended when a
+ * condition is logically guaranteed to be true but TypeScript cannot prove it,
+ * or for catching and signaling developer mistakes eagerly.
  *
  * ### Example
  *
@@ -40,8 +41,9 @@ export const assert: (
 /**
  * Asserts that a value is non-nullable.
  *
- * Narrows a nullable value to {@link NonNullable} when null or undefined is
- * logically impossible but TypeScript cannot prove it.
+ * Following TypeScript's {@link NonNullable}, non-nullable here means neither
+ * null nor undefined. Use this when a value is logically guaranteed to be
+ * non-nullable but TypeScript cannot prove it.
  */
 export const assertNonNullable: <T>(
   value: T,
@@ -53,21 +55,80 @@ export const assertNonNullable: <T>(
   assert(value != null, message);
 };
 
+/**
+ * Asserts that a value is not null while preserving undefined.
+ *
+ * Use this when a value is logically guaranteed not to be null but TypeScript
+ * cannot prove it.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import { assertNotNull } 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.",
+ * );
+ * ```
+ */
+export const assertNotNull: <T>(
+  value: T,
+  message?: string,
+) => asserts value is T & ({} | undefined) = (
+  value,
+  message = "Expected value not to be null.",
+) => {
+  assert(value !== null, message);
+};
+
+/**
+ * Asserts that a value is not undefined while preserving null.
+ *
+ * Use this when a value is logically guaranteed not to be undefined but
+ * TypeScript cannot prove it.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import { assertNotUndefined } 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.",
+ * );
+ * ```
+ */
+export const assertNotUndefined: <T>(
+  value: T,
+  message?: string,
+) => asserts value is T & ({} | null) = (
+  value,
+  message = "Expected value not to be undefined.",
+) => {
+  assert(value !== undefined, message);
+};
+
 /**
  * Asserts that an array is non-empty.
  *
- * Ensures the provided array has at least one element, helping TypeScript infer
- * the array as non-empty when this is logically guaranteed but not statically
- * known.
+ * Use this when an array is logically guaranteed to be non-empty but TypeScript
+ * cannot prove it.
  *
  * ### Example
  *
  * ```ts
- * import { assertNonEmptyArray } from "@evolu/common";
+ * import { assertNonEmptyArray, type NonEmptyArray } from "@evolu/common";
  *
  * const values = [1, 2, 3];
  * assertNonEmptyArray(values);
- * expectTypeOf(values).toEqualTypeOf<[number, ...Array<number>]>();
+ * expectTypeOf(values).toEqualTypeOf<NonEmptyArray<number>>();
  * expect(values[0]).toBe(1);
  * expect(() => assertNonEmptyArray([])).toThrow();
  * ```
@@ -75,7 +136,7 @@ export const assertNonNullable: <T>(
 export const assertNonEmptyArray: <T>(
   arr: Array<T>,
   message?: string,
-) => asserts arr is [T, ...Array<T>] = (
+) => asserts arr is NonEmptyArray<T> = (
   arr,
   message = "Expected a non-empty array.",
 ) => {
@@ -85,20 +146,20 @@ export const assertNonEmptyArray: <T>(
 /**
  * Asserts that a readonly array is non-empty.
  *
- * Ensures the provided readonly array has at least one element, helping
- * TypeScript infer non-emptiness when this is logically guaranteed but not
- * statically known.
+ * Use this when a readonly array is logically guaranteed to be non-empty but
+ * TypeScript cannot prove it.
  *
  * ### Example
  *
  * ```ts
- * import { assertNonEmptyReadonlyArray } from "@evolu/common";
+ * import {
+ *   assertNonEmptyReadonlyArray,
+ *   type NonEmptyReadonlyArray,
+ * } from "@evolu/common";
  *
  * const values: ReadonlyArray<number> = [1, 2, 3];
  * assertNonEmptyReadonlyArray(values);
- * expectTypeOf(values).toEqualTypeOf<
- *   readonly [number, ...Array<number>]
- * >();
+ * expectTypeOf(values).toEqualTypeOf<NonEmptyReadonlyArray<number>>();
  * expect(values[0]).toBe(1);
  * expect(() => assertNonEmptyReadonlyArray([])).toThrow();
  * ```
@@ -106,7 +167,7 @@ export const assertNonEmptyArray: <T>(
 export const assertNonEmptyReadonlyArray: <T>(
   arr: ReadonlyArray<T>,
   message?: string,
-) => asserts arr is readonly [T, ...Array<T>] = (
+) => asserts arr is NonEmptyReadonlyArray<T> = (
   arr,
   message = "Expected a non-empty readonly array.",
 ) => {

package/src/local-first/Db.ts

@@ -11,9 +11,9 @@ import {
   type NonEmptyReadonlyArray,
 } from "../Array.ts";
 import {
-  assert,
   assertNonEmptyReadonlyArray,
   assertNonNullable,
+  assertNotUndefined,
 } from "../Assert.ts";
 import type { ConsoleLevel } from "../Console.ts";
 import {
@@ -45,13 +45,13 @@ import { callback, type Run, type Task } from "../Task.ts";
 import { Millis, millisToDateIso, type TimeDep } from "../Time.ts";
 import {
   assertType,
-  type ExtractTyped,
   Id,
   IdBytes,
   idBytesToId,
   idToIdBytes,
-  type Name,
   onePositiveInt,
+  type ExtractTyped,
+  type Name,
 } from "../Type.ts";
 import type {
   CreateBroadcastChannelDep,
@@ -634,7 +634,10 @@ const createClientStorage =
     let didWriteMessages = false;
 
     const getEncryptionKey = (): EncryptionKey => {
-      assert(encryptionKey != null, "ClientStorage encryption key must be set");
+      assertNonNullable(
+        encryptionKey,
+        "ClientStorage encryption key must be set",
+      );
       return encryptionKey;
     };
 
@@ -841,7 +844,7 @@ const applyLocalOnlyChange =
       const columns = dbChangeToColumns(change, deps.time.now());
 
       for (const [column, value] of columns) {
-        assertNonNullable(value);
+        assertNotUndefined(value);
         deps.sqlite.exec(sql.prepared`
           insert into ${sql.identifier(change.table)}
             ("ownerId", "id", ${sql.identifier(column)})
@@ -871,7 +874,7 @@ const applyMessages =
       const timestampBytes = timestampToTimestampBytes(timestamp);
 
       for (const [column, value] of columns) {
-        assertNonNullable(value);
+        assertNotUndefined(value);
         if (validateColumnValue(deps)(change.table, column, value)) {
           applyColumnChange(deps)(
             ownerIdBytes,

package/src/local-first/Protocol.ts

@@ -1370,7 +1370,7 @@ const sync =
       nonSkipRangeAdded = true;
       if (skip) {
         skip = false;
-        assert(prevUpperBound != null, "prevUpperBound is null");
+        assertNonNullable(prevUpperBound, "prevUpperBound is null");
         // There is always a space for a skip range before adding.
         output.addRange({
           type: RangeType.Skip,