@evolu/common 8.3.3 → 8.5.0

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
  *
@@ -32,6 +33,7 @@ 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);
   }
@@ -40,8 +42,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 +56,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 +137,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 +147,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 +168,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/LeakDetector.ts

@@ -66,9 +66,10 @@ export const createLeakDetector = (deps: ConsoleDep): LeakDetector => {
   if (typeof globalThis.FinalizationRegistry !== "function")
     return noopLeakDetector;
 
-  const registry = new globalThis.FinalizationRegistry<TrackedLeak>(
-    reportLeak(deps),
-  );
+  const report = reportLeak(deps);
+  const registry = new globalThis.FinalizationRegistry<TrackedLeak>((leak) => {
+    report(leak);
+  });
 
   return {
     track: (target, leak, unregisterToken) => {

package/src/Lookup.ts

@@ -384,6 +384,7 @@ const structuralLookupInternal = (
   value: unknown,
   path: Set<object> = new Set(),
 ): string => {
+  // oxlint-disable-next-line typescript/switch-exhaustiveness-check -- The default rejects every unsupported unknown runtime type.
   switch (typeof value) {
     case "string":
       return `s:${JSON.stringify(value)}`;

package/src/Platform.ts

@@ -176,6 +176,7 @@ const createTestGlobalErrors = (
       globalThis.removeEventListener(webEvent, listener);
     });
   } else {
+    // oxlint-disable-next-line unicorn/prefer-type-error -- An unsupported runtime environment is not an invalid argument type.
     throw new Error(`Unsupported platform global ${errorType} reporting.`);
   }
 

package/src/Relation.ts

@@ -250,14 +250,14 @@ export function createRelation<A, B, LA = A, LB = B>({
     removeByA: (a) => {
       const relatedB = bByA.get(a);
       if (!relatedB) return false;
-      for (const b of [...relatedB.keys()]) removePair(a, b);
+      for (const b of relatedB.keys()) removePair(a, b);
       return true;
     },
 
     removeByB: (b) => {
       const relatedA = aByB.get(b);
       if (!relatedA) return false;
-      for (const a of [...relatedA.keys()]) removePair(a, b);
+      for (const a of relatedA.keys()) removePair(a, b);
       return true;
     },
 
@@ -306,7 +306,7 @@ export function createRelation<A, B, LA = A, LB = B>({
 const assertRelationMappingConsistency: (
   condition: unknown,
 ) => asserts condition = (condition) => {
-  assert(condition, "Relation mapping inconsistency");
+  assert(Boolean(condition), "Relation mapping inconsistency");
 };
 
 /**

package/src/Resource.ts

@@ -392,7 +392,7 @@ export const createSharedResource =
         // only.
         if (sharedResourceRun.getState().type !== "Running") return true;
 
-        if (idleDisposeAfter) {
+        if (idleDisposeAfter !== undefined) {
           idleDisposeFiber = sharedResourceRun.abortable<void, never>(
             async (run) => {
               await run.ok(sleep(idleDisposeAfter));
@@ -414,7 +414,9 @@ export const createSharedResource =
         resource: current as unknown as BorrowedResource<T>,
         created,
         release,
-        [Symbol.dispose]: release,
+        [Symbol.dispose]: () => {
+          release();
+        },
       };
 
       leakDetector.track(
@@ -832,6 +834,7 @@ export function createSharedResourceByKey<
         using leaseDisposer = new DisposableStack();
         const leasesByKey: Array<readonly [Lease<T>, K]> = [];
 
+        // oxlint-disable-next-line unicorn/no-useless-spread -- Snapshot keys because each acquisition awaits and can mutate the registry.
         for (const [key] of [...sharedResourcesByKey]) {
           const lease = await run.ok(sharedResourceByKey.acquireCurrent(key));
           if (lease) leasesByKey.push([leaseDisposer.use(lease), key]);
@@ -1346,7 +1349,9 @@ export const createSharedResourceByKeyWithClaims =
           const release = (): boolean => releaseClaimLease(heldClaimLease);
           const claimLease: ClaimLease = {
             release,
-            [Symbol.dispose]: release,
+            [Symbol.dispose]: () => {
+              release();
+            },
           };
 
           leakDetector.track(
@@ -1367,6 +1372,7 @@ export const createSharedResourceByKeyWithClaims =
               resourceKey,
             ] of firstClaimTransitions) {
               onFirstClaimAdded?.(claim, resource, resourceKey);
+              // oxlint-disable-next-line eslint/no-loop-func -- Captures this iteration's block-scoped transition values for rollback.
               compensations.defer(() => {
                 if (!succeeded) {
                   notifyLastClaimRemoved(claim, resource, resourceKey);

package/src/Result.ts

@@ -189,6 +189,7 @@
  * @module
  */
 import {
+  createMutableArray,
   emptyArray,
   isNonEmptyArray,
   type NonEmptyReadonlyArray,
@@ -442,9 +443,8 @@ export const isErr = <T, E>(result: Result<T, E>): result is Err<E> =>
 export const getOrThrow = <T, E>(result: Result<T, E>): T => {
   if (result.ok) {
     return result.value;
-  } else {
-    throw new Error("getOrThrow", { cause: result.error });
   }
+  throw new Error("getOrThrow", { cause: result.error });
 };
 
 /**
@@ -572,7 +572,7 @@ export function trySync<T, E>(
 export function trySync<T, E>(
   fn: () => T,
   mapError?: (error: unknown) => E,
-): Result<T, E | unknown> {
+): Result<T, unknown> {
   try {
     return ok(fn());
   } catch (error) {
@@ -644,7 +644,7 @@ export function tryAsync<T, E>(
 export async function tryAsync<T, E>(
   promiseThunk: Thunk<Awaitable<T>>,
   mapError?: (error: unknown) => E,
-): Promise<Result<T, E | unknown>> {
+): Promise<Result<T, unknown>> {
   try {
     return ok(await promiseThunk());
   } catch (error) {
@@ -1181,7 +1181,7 @@ export function allResult(
     const length = input.length;
     if (length === 0) return ok(emptyArray);
 
-    const values = new Array<unknown>(length);
+    const values = createMutableArray<unknown>(length);
     for (let i = 0; i < length; i++) {
       const result = fn ? fn(input[i]) : (input[i] as AnyResult);
       if (!result.ok) return result;

package/src/Sqlite.ts

@@ -256,12 +256,13 @@ export const createSqlite =
             console.debug({ query });
 
             const label =
-              query.options?.logQueryExecutionTime &&
-              `SqliteQueryExecutionTime ${query.sql}`;
+              query.options?.logQueryExecutionTime === true
+                ? `SqliteQueryExecutionTime ${query.sql}`
+                : null;
 
-            if (label) console.time(label);
+            if (label !== null) console.time(label);
             const result = driver.exec(query);
-            if (label) console.timeEnd(label);
+            if (label !== null) console.timeEnd(label);
 
             if (query.options?.logExplainQueryPlan) {
               const result = driver.exec({
@@ -343,11 +344,12 @@ const drawSqliteQueryPlan = (rows: Array<SqliteQueryPlanRow>): string =>
       let indent = 0;
 
       do {
+        // oxlint-disable-next-line eslint/no-loop-func -- find invokes the callback synchronously before parentId changes.
         const parent = rows.find((r) => r.id === parentId);
         if (!parent) break;
         parentId = parent.parent;
         indent++;
-        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition, no-constant-condition
+        // oxlint-disable-next-line eslint/no-constant-condition -- A missing parent terminates the traversal above.
       } while (true);
 
       return `${"  ".repeat(indent)}${row.detail}`;
@@ -395,7 +397,7 @@ export const createPreparedStatementsCache = <P>(
         if (alwaysPrepare !== true && !query.options?.prepare)
           return null as never;
         let statement = statementsBySql.get(query.sql);
-        if (!statement) {
+        if (statement === undefined) {
           statement = factory(query.sql);
           statementsBySql.set(query.sql, statement);
         }
@@ -492,7 +494,7 @@ export const sql = (
 sql.identifier = (identifier: string): SqlIdentifier => ({
   type: "SqlIdentifier",
   // From Kysely
-  sql: `"${identifier.replace(/"/g, '""')}"` as SafeSql,
+  sql: `"${identifier.replaceAll('"', '""')}"` as SafeSql,
 });
 
 /**

package/src/Store.ts

@@ -70,7 +70,9 @@ export const createStore = <T>(initialState: T, eq?: Eq<T>): Store<T> => {
     get: ref.get,
     subscribe: (listener) => {
       listeners.add(listener);
-      return () => listeners.delete(listener);
+      return () => {
+        listeners.delete(listener);
+      };
     },
 
     set: (state) => {

package/src/String.ts

@@ -9,7 +9,7 @@
  * pattern.
  */
 export const escapeRegExp = (value: string): string =>
-  value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  value.replaceAll(/[.*+?^${}()|[\]\\]/gu, "\\$&");
 
 /** Converts an unknown value to a compact, human-readable diagnostic string. */
 export const safelyStringifyUnknownValue = (value: unknown): string => {