Update docs headings from '###' to '##'

Author: steida

packages/common/src/Array.ts

@@ -2,7 +2,7 @@
  * Array types, type guards, operations, transformations, accessors, and (rare)
  * mutations
  *
- * ### Example
+ * ## Example
  *
  * ```ts
  * // Types - compile-time guarantee of at least one element
@@ -66,7 +66,7 @@
  * const result = firstInArray(mapped);
  * ```
  *
- * ### Why data-first?
+ * ## Why data-first?
  *
  * Evolu optimizes for consistent code style. We can't have both data-first
  * single operations and curried data-last helpers without sacrificing
@@ -103,7 +103,7 @@ export type NonEmptyReadonlyArray<T> = readonly [T, ...ReadonlyArray<T>];
  *
  * Use `if (!isNonEmptyArray(arr))` for empty checks.
  *
- * ### Example
+ * ## Example
  *
  * ```ts
  * const arr: Array<number> = [1, 2, 3];
@@ -124,7 +124,7 @@ export const isNonEmptyArray = <T>(
  *
  * Use `if (!isNonEmptyReadonlyArray(arr))` for empty checks.
  *
- * ### Example
+ * ## Example
  *
  * ```ts
  * const arr: ReadonlyArray<number> = [1, 2, 3];
@@ -144,7 +144,7 @@ export const isNonEmptyReadonlyArray = <T>(
  *
  * Accepts both mutable and readonly arrays. Does not mutate the original array.
  *
- * ### Example
+ * ## Example
  *
  * ```ts
  * appendToArray([1, 2, 3], 4); // [1, 2, 3, 4]
@@ -163,7 +163,7 @@ export const appendToArray = <T>(
  *
  * Accepts both mutable and readonly arrays. Does not mutate the original array.
  *
- * ### Example
+ * ## Example
  *
  * ```ts
  * prependToArray([2, 3], 1); // [1, 2, 3]
@@ -181,7 +181,7 @@ export const prependToArray = <T>(
  *
  * Accepts both mutable and readonly arrays. Preserves non-empty type.
  *
- * ### Example
+ * ## Example
  *
  * ```ts
  * mapArray([1, 2, 3], (x) => x * 2); // [2, 4, 6]
@@ -213,15 +213,15 @@ export function mapArray<T, U>(
  * type to the narrowed type, making it useful for filtering with Evolu Types
  * like `PositiveInt.is`.
  *
- * ### Examples
+ * ## Examples
  *
- * #### With predicate
+ * ### With predicate
  *
  * ```ts
  * filterArray([1, 2, 3, 4, 5], (x) => x % 2 === 0); // [2, 4]
  * ```
  *
- * #### With refinement
+ * ### With refinement
  *
  * ```ts
  * const mixed: ReadonlyArray<NonEmptyString | PositiveInt> = [
@@ -258,7 +258,7 @@ export function filterArray<T>(
  * Accepts both mutable and readonly arrays. Does not mutate the original array.
  * Preserves non-empty type.
  *
- * ### Example
+ * ## Example
  *
  * ```ts
  * // Dedupe primitives by value
@@ -314,9 +314,9 @@ export function dedupeArray<T>(
  * TypeScript will narrow the first array to the narrowed type, making it useful
  * for filtering with Evolu Types like `PositiveInt.is`.
  *
- * ### Examples
+ * ## Examples
  *
- * #### With predicate
+ * ### With predicate
  *
  * ```ts
  * const [evens, odds] = partitionArray(
@@ -327,7 +327,7 @@ export function dedupeArray<T>(
  * odds; // [1, 3, 5]
  * ```
  *
- * #### With refinement
+ * ### With refinement
  *
  * ```ts
  * const mixed: ReadonlyArray<NonEmptyString | PositiveInt> = [
@@ -372,7 +372,7 @@ export function partitionArray<T>(
  *
  * Accepts both mutable and readonly arrays. Does not mutate the original array.
  *
- * ### Example
+ * ## Example
  *
  * ```ts
  * firstInArray(["a", "b", "c"]); // "a"
@@ -387,7 +387,7 @@ export const firstInArray = <T>(array: NonEmptyReadonlyArray<T>): T => array[0];
  *
  * Accepts both mutable and readonly arrays. Does not mutate the original array.
  *
- * ### Example
+ * ## Example
  *
  * ```ts
  * lastInArray(["a", "b", "c"]); // "c"
@@ -403,7 +403,7 @@ export const lastInArray = <T>(array: NonEmptyReadonlyArray<T>): T =>
  *
  * **Mutates** the original array.
  *
- * ### Example
+ * ## Example
  *
  * ```ts
  * const arr: NonEmptyArray<number> = [1, 2, 3];
@@ -420,7 +420,7 @@ export const shiftArray = <T>(array: NonEmptyArray<T>): T => array.shift() as T;
  *
  * **Mutates** the original array.
  *
- * ### Example
+ * ## Example
  *
  * ```ts
  * const arr: NonEmptyArray<number> = [1, 2, 3];

packages/common/src/Assert.ts

@@ -12,7 +12,7 @@ import type { Type } from "./Type.js";
  * TypeScript, or for catching and signaling developer mistakes eagerly (e.g.,
  * invalid configuration).
  *
- * ### Example
+ * ## Example
  *
  * ```ts
  * assert(true, "true is not true"); // no-op
@@ -42,7 +42,7 @@ export const assert: (
  * the array as non-empty when this is logically guaranteed but not statically
  * known.
  *
- * ### Example
+ * ## Example
  *
  * ```ts
  * assertNonEmptyArray([1, 2, 3]); // no-op
@@ -66,7 +66,7 @@ export const assertNonEmptyArray: <T>(
  * TypeScript infer non-emptiness when this is logically guaranteed but not
  * statically known.
  *
- * ### Example
+ * ## Example
  *
  * ```ts
  * assertNonEmptyReadonlyArray([1, 2, 3]); // no-op

packages/common/src/BigInt.ts

@@ -15,7 +15,7 @@ export const clampBigInt =
 /**
  * Creates a predicate that checks if a BigInt is within a range, inclusive.
  *
- * ### Example
+ * ## Example
  *
  * ```ts
  * const isBetween10And20 = isBetweenBigInt(10n, 20n);

packages/common/src/Brand.ts

@@ -6,7 +6,7 @@
  *
  * Supports multiple brands, allowing types to act like flags.
  *
- * ### Example 1: Single Brand
+ * ## Example 1: Single Brand
  *
  * ```ts
  * // A branded type definition
@@ -30,7 +30,7 @@
  * getUser("123"); // ❌ TypeScript error
  * ```
  *
- * ### Example 2: Multiple Brands
+ * ## Example 2: Multiple Brands
  *
  * ```ts
  * // Define branded types
@@ -56,7 +56,7 @@
  * requiresMax100(min1Max100Value); // ✅ Valid: Min1Max100 satisfies Max100
  * ```
  *
- * ### Example 3: Standalone Brand
+ * ## Example 3: Standalone Brand
  *
  * Brand can be used alone without a base type for purely nominal typing. This
  * is useful for opaque values where the internal structure is hidden and type
@@ -87,7 +87,7 @@ declare const __brand: unique symbol;
  *
  * Works with any base type intersected with a `Brand`.
  *
- * ### Example
+ * ## Example
  *
  * - `IsBranded<string>` -> false
  * - `IsBranded<string & Brand<"X">>` -> true

packages/common/src/Buffer.ts

@@ -27,7 +27,7 @@ export class BufferError extends Error {
  * its capacity) to minimize memory reallocations and uses `subarray` for
  * efficient, copy-free data access in methods like `unwrap` and `shift`.
  *
- * ### Recommended Usage
+ * ## Recommended Usage
  *
  * Create as few Buffers as possible—typically one main Buffer for the final
  * output. Temporary Buffers are allowed when necessary (e.g., for
@@ -42,7 +42,7 @@ export class BufferError extends Error {
  * avoids allocation overhead in success cases and leverages exceptions'
  * diagnostic benefits.
  *
- * ### Example
+ * ## Example
  *
  * ```ts
  * const buffer = createBuffer();

packages/common/src/Cache.ts

@@ -31,7 +31,7 @@ export interface Cache<K, V> {
  * When the cache reaches capacity, the least recently used entry is evicted.
  * Both `get` and `set` operations update the access order.
  *
- * ### Example
+ * ## Example
  *
  * ```ts
  * const cache = createLruCache<string, number>(2);

packages/common/src/Callbacks.ts

@@ -16,7 +16,7 @@ import { createId, Id } from "./Type.js";
  * The `execute` method intentionally does not use try-catch or {@link Result}
  * because it's the callback's responsibility to handle its own errors.
  *
- * ### Example
+ * ## Example
  *
  * ```ts
  * // No-argument callbacks

packages/common/src/Console.ts

@@ -9,13 +9,13 @@
  * **Convention**: Use a tag (e.g., `[db]`) as the first argument for log
  * filtering.
  *
- * ### Example
+ * ## Example
  *
  * ```ts
  * deps.console.log("[evolu]", "createEvoluInstance", { name });
  * ```
  *
- * **Tip**: In browser dev tools, you can filter logs by tag (e.g., `[db]`) to
+ * **Tip**: In browser dev tools, we can filter logs by tag (e.g., `[db]`) to
  * quickly find relevant messages. In Node.js, use `grep` to filter output:
  *
  * ```bash

packages/common/src/Crypto.ts

@@ -23,7 +23,7 @@ export interface RandomBytes {
    * generator (crypto.getRandomValues) to generate high-quality entropy
    * suitable for cryptographic operations.
    *
-   * ### Type Safety
+   * ## Type Safety
    *
    * Returns specific branded types for common sizes:
    *
@@ -33,7 +33,7 @@ export interface RandomBytes {
    * - `Random64` for 64-byte values (512 bits)
    * - `Random` for any other size
    *
-   * ### Example
+   * ## Example
    *
    * ```ts
    * const nonce = randomBytes.create(16); // Type: Random16
@@ -137,7 +137,7 @@ export type XChaCha20Poly1305Ciphertext =
  * Generates a random nonce internally and returns both the ciphertext and
  * nonce. The nonce must be stored alongside the ciphertext for decryption.
  *
- * ### Example
+ * ## Example
  *
  * ```ts
  * const deps = { randomBytes: createRandomBytes() };
@@ -174,7 +174,7 @@ export interface DecryptWithXChaCha20Poly1305Error {
  * {@link Result} that may contain a decryption error if the ciphertext was
  * tampered with or the wrong key/nonce was used.
  *
- * ### Example
+ * ## Example
  *
  * ```ts
  * const result = decryptWithXChaCha20Poly1305(

packages/common/src/Eq.ts

@@ -29,7 +29,7 @@ export const eqFromOrder =
  * Creates an equivalence function for array-like structures based on an
  * equivalence for their elements.
  *
- * ### Example
+ * ## Example
  *
  * ```ts
  * const eqArrayNumber = createEqArrayLike(eqNumber);
@@ -54,7 +54,7 @@ export const createEqArrayLike =
 /**
  * Compares two array-like structures of numbers for equality.
  *
- * ### Example
+ * ## Example
  *
  * ```ts
  * eqArrayNumber([1, 2, 3], [1, 2, 3]); // true (works with regular arrays)
@@ -68,7 +68,7 @@ export const eqArrayNumber = createEqArrayLike(eqNumber);
  * Creates an equivalence function for objects based on an equivalence for their
  * fields.
  *
- * ### Example
+ * ## Example
  *
  * ```ts
  * const eqObjectNumber = createEqObject({ a: eqNumber });
@@ -100,7 +100,7 @@ export const createEqObject =
  *   serialization overhead and leveraging short-circuit evaluation for faster
  *   failure on mismatched structures.
  *
- * ### Example
+ * ## Example
  *
  * ```ts
  * const obj1: Json = { name: "Alice", hobbies: ["reading", "hiking"] };
@@ -190,7 +190,7 @@ export const eqJsonValue = (a: JsonValue, b: JsonValue): boolean => {
  *   serialization overhead and leveraging short-circuit evaluation for faster
  *   failure on mismatched structures.
  *
- * ### Example
+ * ## Example
  *
  * ```ts
  * const obj1: Json = { name: "Alice", hobbies: ["reading", "hiking"] };