@evolu/common 8.10.0 → 8.12.0

package/src/LockManager.ts

@@ -47,6 +47,8 @@ import type { Callback } from "./Types.ts";
  * );
  * assertEqual(result, "example");
  * ```
+ *
+ * @group Core
  */
 
 export interface LockManagerDep {
@@ -65,6 +67,8 @@ export interface LockManagerDep {
  * 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.
+ *
+ * @group Testing
  */
 export const testCreateLockManager = (
   nativeLockManager: LockManager = navigator.locks,
@@ -119,6 +123,8 @@ export const testCreateLockManager = (
  * 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.
+ *
+ * @group Leader election
  */
 export const acquireLeaderLock =
   (name: string): Task<AsyncDisposable, never, LockManagerDep> =>
@@ -156,6 +162,8 @@ export const acquireLeaderLock =
  * 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.
+ *
+ * @group Leader election
  */
 export const acquireLeaderLockCallback =
   (deps: LockManagerDep) =>

package/src/Object.test.ts

@@ -1,6 +1,12 @@
 import nodeAssert from "node:assert/strict";
 import { describe, it, test } from "node:test";
-import { assertEqual, assertFalse, assertSame, assertTrue } from "./Assert.ts";
+import {
+  assertEqual,
+  assertFalse,
+  assertNonNullable,
+  assertSame,
+  assertTrue,
+} from "./Assert.ts";
 
 import type { Brand } from "./Brand.ts";
 import type { ReadonlyRecord } from "./Object.ts";
@@ -105,6 +111,22 @@ test("isPlainObject", () => {
   assertFalse(isPlainObject(Object.create(partialObjectPrototype)));
 });
 
+test("isPlainObject checks the root markers of Object.prototype", () => {
+  for (const key of ["hasOwnProperty", "isPrototypeOf"]) {
+    const descriptor = Object.getOwnPropertyDescriptor(Object.prototype, key);
+    assertNonNullable(descriptor);
+    Reflect.deleteProperty(Object.prototype, key);
+    try {
+      assertFalse(isPlainObject({}));
+      assertTrue(isPlainObject(Object.create(null)));
+    } finally {
+      // oxlint-disable-next-line eslint/no-extend-native -- Restores the built-in property this test deleted.
+      Object.defineProperty(Object.prototype, key, descriptor);
+    }
+  }
+  assertTrue(isPlainObject({}));
+});
+
 test("isFunction", () => {
   assertTrue(isFunction(() => {}));
   assertTrue(isFunction(function () {}));
@@ -244,13 +266,12 @@ describe("filterObjectKeys", () => {
     >();
     assertEqual(selectedUsers, { u1: 1 });
 
-    const reject = () => {
+    void (() => {
       // @ts-expect-error filterObjectKeys requires an object source.
       filterObjectKeys("text", () => true);
       // @ts-expect-error Selected properties are readonly.
       selected.APP_PORT = "5000";
-    };
-    assertType<typeof reject, () => void>();
+    });
   });
 
   it("preserves descriptors without reading getters", () => {
@@ -360,16 +381,10 @@ test("createMutableRecord", () => {
   assertEqual(source, { name: "Ada" });
   assertSame(Object.getPrototypeOf(copy), null);
 
-  const compileTimeAssertions = () => {
+  void (() => {
     // @ts-expect-error createMutableRecord source must be an object.
     createMutableRecord("Ada");
-  };
-  assertType<
-    typeof compileTimeAssertions extends (...args: Array<never>) => unknown
-      ? true
-      : false,
-    true
-  >();
+  });
 });
 
 test("emptyRecord", () => {

package/src/Object.ts

@@ -87,6 +87,11 @@ export const isPlainObject = (
 
   const prototype = Object.getPrototypeOf(value) as object | null;
   if (prototype === null) return true;
+  // This realm's Object.prototype has an immutable null prototype, so `in`
+  // checks the same own properties as the structural test below, faster.
+  if (prototype === Object.prototype) {
+    return "hasOwnProperty" in prototype && "isPrototypeOf" in prototype;
+  }
   return (
     Object.getPrototypeOf(prototype) === null &&
     Object.hasOwn(prototype, "hasOwnProperty") &&

package/src/Platform.ts

@@ -4,10 +4,18 @@
  * @module
  */
 
-/** Returns true if running in React Native with Hermes engine. */
+/**
+ * Returns true if running in React Native with Hermes engine.
+ *
+ * @group Detection
+ */
 export const isHermes = "HermesInternal" in globalThis;
 
-/** Returns true if running in a server environment (no DOM). */
+/**
+ * Returns true if running in a server environment (no DOM).
+ *
+ * @group Detection
+ */
 export const isServer = typeof document === "undefined";
 
 /**
@@ -20,6 +28,8 @@ export const isServer = typeof document === "undefined";
  * where no bundler ran, such as un-bundled browser ESM, where it fails closed
  * to production behavior. Node.js reads it natively; React Native polyfills it.
  * A missing `NODE_ENV` counts as development, matching React semantics.
+ *
+ * @group Detection
  */
 export const isDev =
   typeof process === "undefined"
@@ -35,6 +45,7 @@ export const isDev =
  * Returns false in React Native even if Buffer is polyfilled, as we prefer
  * native methods in that environment.
  *
+ * @group Detection
  * @see https://github.com/craftzdog/react-native-quick-base64#installation
  */
 export const hasNodeBuffer =
@@ -49,9 +60,16 @@ export const hasNodeBuffer =
  * if an onComplete callback is used.
  *
  * https://react.dev/reference/react-dom/flushSync
+ *
+ * @group Integration
  */
 export type FlushSync = (callback: () => void) => void;
 
+/**
+ * Dependency wrapper for {@link FlushSync}.
+ *
+ * @group Integration
+ */
 export interface FlushSyncDep {
   readonly flushSync: FlushSync;
 }
@@ -59,18 +77,32 @@ export interface FlushSyncDep {
 /**
  * Reload the app in a platform-specific way.
  *
- * Use this after purging persistent storage to clear in-memory state and ensure
- * the app starts fresh. It does not purge storage itself.
+ * On the web, Evolu reloads tabs of a build when another build of the app waits
+ * for the local databases, so they load the build the server now serves. It can
+ * also clear in-memory state after persistent storage was purged; it does not
+ * purge storage itself.
  *
- * - Web: Redirects to the specified URL (defaults to `/`)
+ * - Web: Reloads the page, or loads the specified URL instead
  * - React Native: Restarts the app (URL ignored)
+ *
+ * @group Integration
  */
 export type ReloadApp = (url?: string) => void;
 
+/**
+ * Dependency wrapper for {@link ReloadApp}.
+ *
+ * @group Integration
+ */
 export interface ReloadAppDep {
   readonly reloadApp: ReloadApp;
 }
 
+/**
+ * Records platform global errors until disposed.
+ *
+ * @group Testing
+ */
 export interface TestGlobalErrors extends Disposable {
   readonly errors: ReadonlyArray<unknown>;
   readonly next: () => Promise<unknown>;
@@ -88,15 +120,25 @@ export interface TestGlobalErrors extends Disposable {
   readonly settle: () => Promise<ReadonlyArray<unknown>>;
 }
 
-/** Records platform global uncaught-error reporting until disposed. */
+/**
+ * Records platform global uncaught-error reporting until disposed.
+ *
+ * @group Testing
+ */
 export const testGlobalUncaughtErrors = (): TestGlobalErrors =>
   createTestGlobalErrors("uncaughtErrors");
 
-/** Records platform global unhandled-rejection reporting until disposed. */
+/**
+ * Records platform global unhandled-rejection reporting until disposed.
+ *
+ * @group Testing
+ */
 export const testGlobalUnhandledRejections = (): TestGlobalErrors =>
   createTestGlobalErrors("unhandledRejection");
 
-const settleSentinel = new Error("TestGlobalErrors.settle sentinel");
+const settleSentinel = /*#__PURE__*/ new Error(
+  "TestGlobalErrors.settle sentinel",
+);
 
 const createTestGlobalErrors = (
   kind: "uncaughtErrors" | "unhandledRejection",

package/src/Random.ts

@@ -11,6 +11,8 @@ import type { Brand } from "./Brand.ts";
  * A random floating point number in [0, 1).
  *
  * Branded to distinguish random values from arbitrary numbers.
+ *
+ * @group Core
  */
 export type RandomNumber = number & Brand<"RandomNumber">;
 
@@ -43,17 +45,28 @@ export type RandomNumber = number & Brand<"RandomNumber">;
  * const secondTestRandom = testCreateRandom("test");
  * assertEqual(firstTestRandom.next(), secondTestRandom.next());
  * ```
+ *
+ * @group Core
  */
 export interface Random {
   /** Returns a floating point number in [0, 1). Just like Math.random(). */
   readonly next: () => RandomNumber;
 }
 
+/**
+ * Dependency wrapper for {@link Random}.
+ *
+ * @group Core
+ */
 export interface RandomDep {
   readonly random: Random;
 }
 
-/** Creates a {@link Random} using Math.random(). */
+/**
+ * Creates a {@link Random} using Math.random().
+ *
+ * @group Core
+ */
 export const createRandom = (): Random => ({
   next: () => Math.random() as RandomNumber,
 });
@@ -62,6 +75,8 @@ export const createRandom = (): Random => ({
  * Creates a seeded {@link Random} for deterministic tests.
  *
  * Default seed "evolu".
+ *
+ * @group Testing
  */
 export const testCreateRandom = (seed = "evolu"): Random => {
   const random = new RandomLib(seed);
@@ -75,12 +90,18 @@ export const testCreateRandom = (seed = "evolu"): Random => {
  * provided by the NPM `random` package.
  *
  * https://github.com/transitive-bullshit/random
+ *
+ * @group Core
  */
 export interface RandomLibDep {
   readonly randomLib: RandomLib;
 }
 
-/** Creates a random number generator from the NPM `random` package. */
+/**
+ * Creates a random number generator from the NPM `random` package.
+ *
+ * @group Core
+ */
 export const createRandomLib = (): RandomLib => new RandomLib();
 
 /**
@@ -88,6 +109,8 @@ export const createRandomLib = (): RandomLib => new RandomLib();
  * deterministic tests.
  *
  * Default seed "evolu".
+ *
+ * @group Testing
  */
 export const testCreateRandomLib = (seed = "evolu"): RandomLib =>
   new RandomLib(seed);