@evolu/common 8.10.0 → 8.11.0

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);