@evolu/common 8.0.0-next.2 → 8.0.0-next.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@evolu/common",
-  "version": "8.0.0-next.2",
+  "version": "8.0.0-next.4",
   "description": "TypeScript library and local-first platform",
   "keywords": [
     "evolu",

package/src/Array.ts

@@ -326,7 +326,7 @@ export function mapArray<T, U>(
   const length = array.length;
   const result = new Array<U>(length);
   for (let i = 0; i < length; i++) result[i] = mapper(array[i], i);
-  return result as ReadonlyArray<U>;
+  return result;
 }
 
 /**
@@ -394,7 +394,7 @@ export function flatMapArray<T, U>(
     index: number,
   ) => ReadonlyArray<U> | Array<U>,
 ): ReadonlyArray<U> {
-  return array.flatMap(mapper) as ReadonlyArray<U>;
+  return array.flatMap(mapper);
 }
 
 /**
@@ -475,7 +475,7 @@ export function filterArray<T>(
   array: ReadonlyArray<T>,
   predicate: PredicateWithIndex<T>,
 ): ReadonlyArray<T> {
-  return array.filter(predicate) as ReadonlyArray<T>;
+  return array.filter(predicate);
 }
 
 /**
@@ -519,7 +519,7 @@ export function dedupeArray<T>(
   by?: (item: T) => unknown,
 ): ReadonlyArray<T> {
   if (by == null) {
-    return Array.from(new Set(array)) as ReadonlyArray<T>;
+    return Array.from(new Set(array));
   }
 
   const seen = new Set<unknown>();
@@ -528,7 +528,7 @@ export function dedupeArray<T>(
     if (seen.has(key)) return false;
     seen.add(key);
     return true;
-  }) as ReadonlyArray<T>;
+  });
 }
 
 /**
@@ -593,7 +593,7 @@ export function partitionArray<T>(
     }
   }
 
-  return [trueArray as ReadonlyArray<T>, falseArray as ReadonlyArray<T>];
+  return [trueArray, falseArray];
 }
 
 /**
@@ -622,7 +622,7 @@ export function sortArray<T>(
   array: ReadonlyArray<T>,
   compareFn?: (a: T, b: T) => number,
 ): ReadonlyArray<T> {
-  return array.toSorted(compareFn) as ReadonlyArray<T>;
+  return array.toSorted(compareFn);
 }
 
 /**
@@ -644,7 +644,7 @@ export function reverseArray<T>(
 /** Possibly empty array. */
 export function reverseArray<T>(array: ReadonlyArray<T>): ReadonlyArray<T>;
 export function reverseArray<T>(array: ReadonlyArray<T>): ReadonlyArray<T> {
-  return array.toReversed() as ReadonlyArray<T>;
+  return array.toReversed();
 }
 
 /**

package/src/Assert.ts

@@ -146,14 +146,14 @@ export function assertNotAborted<T, E>(
  * ### Example
  *
  * ```ts
- * const stack = new globalThis.AsyncDisposableStack();
- * assertNotDisposed(stack); // no-op
- * await stack.disposeAsync();
- * assertNotDisposed(stack); // throws Error
+ * using disposer = new globalThis.AsyncDisposableStack();
+ * assertNotDisposed(disposer); // no-op
+ * await disposer.disposeAsync();
+ * assertNotDisposed(disposer); // throws Error
  * ```
  */
 export const assertNotDisposed = (
-  value: globalThis.DisposableStack | globalThis.AsyncDisposableStack,
+  value: DisposableStack | AsyncDisposableStack,
 ): void => {
   assert(!value.disposed, "Expected value to not be disposed.");
 };

package/src/Identicon.ts

@@ -147,8 +147,8 @@ export const createIdenticon = (
     case "sutnar": {
       // Three compositional variants with adaptive colors.
       const hue = (bytes[0] / 255) * 360;
-      const saturation = 50 + (bytes[1] / 255) * 30;
-      const lightness = 50 + (bytes[2] / 255) * 20;
+      const saturation = 60 + (bytes[1] / 255) * 30;
+      const lightness = 35 + (bytes[2] / 255) * 20;
 
       // Generate palette from base hue with variations
       const toHsl = (h: number, s: number, l: number) =>
@@ -157,11 +157,11 @@ export const createIdenticon = (
       const color1 = toHsl(hue, saturation, lightness);
       const color2 = toHsl((hue + 120) % 360, saturation, lightness);
       const color3 = toHsl((hue + 240) % 360, saturation, lightness);
-      const color4 = toHsl(hue, saturation * 0.3, lightness * 0.5);
+      const color4 = toHsl(hue, saturation * 0.5, lightness * 0.6);
       const color5 = toHsl(
         hue,
         saturation * 0.5,
-        Math.min(lightness * 1.3, 90),
+        Math.min(lightness * 1.3, 60),
       );
 
       const palette = [color1, color2, color3, color4, color5] as const;

package/src/LockManager.ts

@@ -0,0 +1,181 @@
+/**
+ * {@link LockManager} helpers.
+ *
+ * @module
+ */
+
+import { createRandomBytes } from "./Crypto.js";
+import { lazyVoid } from "./Function.js";
+import { tryAsync } from "./Result.js";
+import { AbortError, type Task } from "./Task.js";
+import { createId } from "./Type.js";
+import type { Callback } from "./Types.js";
+
+/**
+ * Dependency wrapper for {@link LockManager}.
+ *
+ * For React Native, use the `lockManager` ponyfill from `@evolu/react-native`.
+ * For tests, use {@link testCreateLockManager}.
+ *
+ * ### Example
+ *
+ * ```ts
+ * // Web or Node.js 24+
+ * import { testCreateLockManager } from "@evolu/common";
+ *
+ * const deps: LockManagerDep = {
+ *   lockManager: testCreateLockManager(),
+ * };
+ * ```
+ *
+ * ### Example
+ *
+ * ```ts
+ * // React Native
+ * import { lockManager } from "@evolu/react-native";
+ *
+ * const deps: LockManagerDep = { lockManager };
+ * ```
+ */
+
+export interface LockManagerDep {
+  readonly lockManager: LockManager;
+}
+
+/**
+ * Creates a test {@link LockManager} backed by the native platform
+ * {@link LockManager}.
+ *
+ * Native backing is intentional: tests must observe the same locking behavior
+ * as the platform runtime, and a userland implementation cannot reproduce it.
+ *
+ * The platform `LockManager` cannot be instantiated, so tests cannot create an
+ * isolated native lock per case. This helper isolates lock usage per instance
+ * via internal namespacing, so tests can reuse the same lock names without
+ * contending through the global Web Locks. Query results are filtered to that
+ * private namespace and returned with the original visible names.
+ */
+export const testCreateLockManager = (
+  nativeLockManager: LockManager = globalThis.navigator.locks,
+): LockManager => {
+  const namespace = createId({ randomBytes: createRandomBytes() });
+
+  const filterLockInfosByNamespace = <T extends LockInfo>(
+    locks: ReadonlyArray<T>,
+  ): Array<T> =>
+    locks.flatMap((lock) =>
+      lock.name?.endsWith(namespace) === true
+        ? [{ ...lock, name: lock.name.slice(0, -namespace.length) }]
+        : [],
+    );
+
+  return {
+    request: <T>(
+      name: string,
+      optionsOrCallback: LockOptions | LockGrantedCallback<T>,
+      maybeCallback?: LockGrantedCallback<T>,
+    ): Promise<Awaited<T>> => {
+      const [options, callback] =
+        typeof optionsOrCallback === "function"
+          ? [{}, optionsOrCallback]
+          : [optionsOrCallback, maybeCallback!];
+
+      return nativeLockManager.request(`${name}${namespace}`, options, (lock) =>
+        callback(lock && { mode: lock.mode, name }),
+      );
+    },
+
+    query: async () => {
+      const locks = await nativeLockManager.query();
+      return {
+        ...(locks.held && {
+          held: filterLockInfosByNamespace(locks.held),
+        }),
+        ...(locks.pending && {
+          pending: filterLockInfosByNamespace(locks.pending),
+        }),
+      };
+    },
+  };
+};
+
+/**
+ * Competes to become the current leader for `name` using {@link LockManager}.
+ *
+ * Only one caller can lead for a given name at a time, and the returned
+ * {@link AsyncDisposable} represents that leadership.
+ *
+ * Leadership is held until the returned handle is disposed. Once released,
+ * another waiting caller may become the next leader. Waiting for leadership is
+ * abortable via the calling {@link Task}'s signal.
+ */
+export const acquireLeaderLock =
+  (name: string): Task<AsyncDisposable, AbortError, LockManagerDep> =>
+  (run) =>
+    tryAsync(
+      async () => {
+        const acquisition = Promise.withResolvers<void>();
+        const released = Promise.withResolvers<void>();
+
+        const request = run.deps.lockManager.request(
+          createLeaderLockName(name),
+          { mode: "exclusive", signal: run.signal },
+          async () => {
+            acquisition.resolve();
+            await released.promise;
+          },
+        );
+        void request.catch(acquisition.reject);
+
+        await acquisition.promise;
+
+        return {
+          [Symbol.asyncDispose]: async () => {
+            released.resolve();
+            await request;
+          },
+        };
+      },
+      (error): AbortError =>
+        AbortError.is(error) ? error : { type: "AbortError", reason: error },
+    );
+
+/**
+ * Competes to become the current leader for `name` using {@link LockManager}.
+ *
+ * Only one caller can lead for a given name at a time. The callback runs when
+ * leadership is acquired, and the returned {@link Disposable} represents that
+ * leadership request.
+ *
+ * Leadership is held until the returned handle is disposed. Once released,
+ * another waiting caller may become the next leader. Waiting for leadership is
+ * abortable by disposing the returned handle.
+ */
+export const acquireLeaderLockCallback =
+  (deps: LockManagerDep) =>
+  (name: string, callback: Callback<void>): Disposable => {
+    const abortController = new AbortController();
+    let release: (() => void) | null = null;
+
+    const request = deps.lockManager.request(
+      createLeaderLockName(name),
+      { mode: "exclusive", signal: abortController.signal },
+      async () => {
+        const released = Promise.withResolvers<void>();
+        release = released.resolve;
+        callback();
+        await released.promise;
+      },
+    );
+    void request.catch(lazyVoid);
+
+    return {
+      [Symbol.dispose]: () => {
+        abortController.abort();
+        release?.();
+      },
+    };
+  };
+
+const createLeaderLockName = (name: string): string =>
+  `evolu-leaderlock-${name}`;

package/src/Microtask.ts

@@ -5,6 +5,7 @@
  */
 
 import { appendToArray, type NonEmptyReadonlyArray } from "./Array.js";
+import { assertNotDisposed } from "./Assert.js";
 
 /**
  * Batches values and flushes them in a single microtask.
@@ -24,11 +25,17 @@ export interface MicrotaskBatch<T> extends Disposable {
 export const createMicrotaskBatch = <T>(
   onFlush: (items: NonEmptyReadonlyArray<T>) => void,
 ): MicrotaskBatch<T> => {
+  using disposer = new DisposableStack();
   let queue: NonEmptyReadonlyArray<T> | null = null;
-  let disposed = false;
 
-  const flushNow = () => {
-    if (disposed || queue == null) return;
+  disposer.defer(() => {
+    queue = null;
+  });
+
+  const disposables = disposer.move();
+
+  const flushQueuedItems = () => {
+    if (queue == null) return;
     const queuedItems = queue;
     queue = null;
     onFlush(queuedItems);
@@ -36,23 +43,22 @@ export const createMicrotaskBatch = <T>(
 
   return {
     push: (item) => {
-      if (disposed) return;
+      assertNotDisposed(disposables);
 
       if (queue == null) {
         queue = [item];
-        queueMicrotask(flushNow);
+        queueMicrotask(flushQueuedItems);
         return;
       }
 
       queue = appendToArray(queue, item);
     },
 
-    flushNow,
-
-    [Symbol.dispose]: () => {
-      if (disposed) return;
-      disposed = true;
-      queue = null;
+    flushNow: () => {
+      assertNotDisposed(disposables);
+      flushQueuedItems();
     },
+
+    [Symbol.dispose]: () => disposables.dispose(),
   };
 };

package/src/Object.ts

@@ -89,7 +89,7 @@ export const objectToEntries = <T extends Record<string, any>>(
 ): ReadonlyArray<[StringKeyOf<T>, T[StringKeyOf<T>]]> =>
   Object.entries(record) as Array<
     [StringKeyOf<T>, T[StringKeyOf<T>]]
-  > as ReadonlyArray<[StringKeyOf<T>, T[StringKeyOf<T>]]>;
+  >;
 
 // A helper type to remove symbol keys (e.g for branded objects).
 type StringKeyOf<T> = Extract<keyof T, string>;
@@ -148,10 +148,10 @@ export const mapObject = <K extends string, V, U>(
   const out = Object.create(null) as Record<K, U>;
 
   for (const key in record) {
-    out[key as K] = fn(record[key as K], key as K);
+    out[key as K] = fn(record[key as K], key);
   }
 
-  return out as ReadonlyRecord<K, U>;
+  return out;
 };
 
 /** Conditionally excludes a property from an object. */

package/src/RefCount.ts

@@ -34,34 +34,32 @@ export interface RefCount extends Disposable {
 
 /** Creates {@link RefCount}. */
 export const createRefCount = (): RefCount => {
+  // We use DisposableStack only because of assertNotDisposed.
+  using disposer = new DisposableStack();
   let count = zeroNonNegativeInt;
-  const stack = new DisposableStack();
-  stack.defer(() => {
-    count = zeroNonNegativeInt;
-  });
-  const moved = stack.move();
+  const disposables = disposer.move();
 
   return {
     increment: () => {
-      assertNotDisposed(moved);
+      assertNotDisposed(disposables);
       const nextCount = PositiveInt.orThrow(count + 1);
       count = nextCount;
       return nextCount;
     },
 
     decrement: () => {
-      assertNotDisposed(moved);
+      assertNotDisposed(disposables);
       assert(count > 0, "RefCount must not be decremented below zero.");
       count = NonNegativeInt.orThrow(count - 1);
       return count;
     },
 
     getCount: () => {
-      assertNotDisposed(moved);
+      assertNotDisposed(disposables);
       return count;
     },
 
-    [Symbol.dispose]: () => moved.dispose(),
+    [Symbol.dispose]: () => disposables.dispose(),
   };
 };
 
@@ -112,17 +110,23 @@ export function createRefCountByKey<TKey, L>(
 export function createRefCountByKey<TKey, L = TKey>({
   lookup = identity as Lookup<TKey, L>,
 }: CreateRefCountByKeyOptions<TKey, L> = {}): RefCountByKey<TKey> {
-  const stack = new DisposableStack();
+  // We use DisposableStack only because of assertNotDisposed.
+  using disposer = new DisposableStack();
 
-  const refCountByKey = stack.adopt(
+  const refCountByKey = disposer.adopt(
     createLookupMap<TKey, RefCount, L>({ lookup }),
     (refCountByKey) => {
-      for (const refCount of refCountByKey.values()) refCount[Symbol.dispose]();
-      refCountByKey.clear();
+      using disposer = new DisposableStack();
+      disposer.defer(() => {
+        refCountByKey.clear();
+      });
+      for (const refCount of refCountByKey.values()) {
+        disposer.use(refCount);
+      }
     },
   );
 
-  const moved = stack.move();
+  const disposables = disposer.move();
 
   const getRefCount = (key: TKey): RefCount => {
     let refCount = refCountByKey.get(key);
@@ -135,36 +139,36 @@ export function createRefCountByKey<TKey, L = TKey>({
 
   return {
     increment: (key) => {
-      assertNotDisposed(moved);
+      assertNotDisposed(disposables);
       return getRefCount(key).increment();
     },
 
     decrement: (key) => {
-      assertNotDisposed(moved);
+      assertNotDisposed(disposables);
       const refCount = getRefCount(key);
       const nextCount = refCount.decrement();
       if (nextCount === 0) {
-        refCount[Symbol.dispose]();
         refCountByKey.delete(key);
+        refCount[Symbol.dispose]();
       }
       return nextCount;
     },
 
     getCount: (key) => {
-      assertNotDisposed(moved);
+      assertNotDisposed(disposables);
       return refCountByKey.get(key)?.getCount() ?? zeroNonNegativeInt;
     },
 
     has: (key) => {
-      assertNotDisposed(moved);
+      assertNotDisposed(disposables);
       return refCountByKey.has(key);
     },
 
     keys: () => {
-      assertNotDisposed(moved);
+      assertNotDisposed(disposables);
       return new Set(refCountByKey.keys());
     },
 
-    [Symbol.dispose]: () => moved.dispose(),
+    [Symbol.dispose]: () => disposables.dispose(),
   };
 }