Merge remote-tracking branch 'upstream/common-v8' into dev

Author: miccy

.changeset/array-module-refactor.md

@@ -0,0 +1,48 @@
+---
+"@evolu/common": major
+---
+
+Refactored the Array module with breaking changes, better naming, and new helpers.
+
+### Breaking Changes
+
+**Removed `isNonEmptyReadonlyArray`** — use `isNonEmptyArray` instead. The function now handles both mutable and readonly arrays via overloads:
+
+```ts
+// Before
+if (isNonEmptyReadonlyArray(readonlyArr)) { ... }
+if (isNonEmptyArray(mutableArr)) { ... }
+
+// After — one function for both
+if (isNonEmptyArray(readonlyArr)) { ... }
+if (isNonEmptyArray(mutableArr)) { ... }
+```
+
+**Renamed mutation functions** for consistency with the `...Array` suffix pattern:
+
+- `shiftArray` → `shiftFromArray`
+- `popArray` → `popFromArray`
+
+### New Functions
+
+- **`flatMapArray`** — maps each element to an array and flattens the result, preserving non-empty type when applicable
+- **`concatArrays`** — concatenates two arrays, returning non-empty when at least one input is non-empty
+- **`sortArray`** — returns a new sorted array (wraps `toSorted`), preserving non-empty type
+- **`reverseArray`** — returns a new reversed array (wraps `toReversed`), preserving non-empty type
+- **`spliceArray`** — returns a new array with elements removed/replaced (wraps `toSpliced`)
+
+### Migration
+
+```ts
+// isNonEmptyReadonlyArray → isNonEmptyArray
+-import { isNonEmptyReadonlyArray } from "@evolu/common";
++import { isNonEmptyArray } from "@evolu/common";
+
+// shiftArray → shiftFromArray
+-import { shiftArray } from "@evolu/common";
++import { shiftFromArray } from "@evolu/common";
+
+// popArray → popFromArray
+-import { popArray } from "@evolu/common";
++import { popFromArray } from "@evolu/common";
+```

.github/copilot-instructions.md

@@ -120,6 +120,7 @@ export type MessageType = (typeof MessageType)[keyof typeof MessageType];
 - **Use `### Example` instead of `@example`** - for better markdown rendering and consistency
 - **Write clear descriptions** - explain what the function does, not how to use it
 - **Use `{@link}` for references** - link to types, interfaces, functions, and exported symbols on first mention for discoverability
+- **Avoid pipe characters in first sentence** - TypeDoc extracts the first sentence for table descriptions, and pipe characters (even in inline code like `T | undefined`) break markdown table rendering. Move such details to subsequent sentences.
 
 ````ts
 // ✅ Good

apps/web/scripts/fix-api-reference.mts

@@ -8,7 +8,7 @@ const reference = path.join(
   "src/app/(docs)/docs/api-reference",
 );
 
-function rearrangeMdxFilesRecursively(dir: string) {
+const rearrangeMdxFilesRecursively = (dir: string): void => {
   for (const item of fs.readdirSync(dir)) {
     const fullPath = path.join(dir, item);
     const stat = fs.statSync(fullPath);
@@ -20,7 +20,7 @@ function rearrangeMdxFilesRecursively(dir: string) {
         const newFolder = path.join(dir, baseName);
         fs.mkdirSync(newFolder, { recursive: true });
         fs.renameSync(fullPath, path.join(newFolder, "page.mdx"));
-        fixLinksInMdxFile(
+        fixMdxFile(
           path.join(newFolder, "page.mdx"),
           `${baseName} - API reference`,
         );
@@ -29,13 +29,13 @@ function rearrangeMdxFilesRecursively(dir: string) {
           dir === reference
             ? "API reference"
             : `${path.basename(dir)} - API reference`;
-        fixLinksInMdxFile(fullPath, title);
+        fixMdxFile(fullPath, title);
       }
     }
   }
-}
+};
 
-function fixLinksInMdxFile(filePath: string, title: string) {
+const fixMdxFile = (filePath: string, title: string): void => {
   const content = fs.readFileSync(filePath, "utf-8");
   // first let's replace /page.mdx with /
   let newContent = content.replace(/\/page\.mdx/g, "");
@@ -56,52 +56,16 @@ function fixLinksInMdxFile(filePath: string, title: string) {
     },
   );
 
-  // Extract ## headings to generate sections for "On this page" navigation
-  const sections = extractSections(newContent);
-  const sectionsExport =
-    sections.length > 0
-      ? `export const sections = ${JSON.stringify(sections)};`
-      : "export const sections = [];";
+  newContent = newContent
+    .replace(/^export const metadata = \{ title: [^}]*\};\s*\r?\n\s*/, "")
+    .replace(/^export const sections = .*;\s*\r?\n\s*/m, "");
 
-  // add meta tags (idempotent)
-  newContent = newContent.replace(
-    /^export const metadata = \{ title: [^}]*\};\s*\r?\n\s*/,
-    "",
-  );
-  newContent = newContent.replace(
-    /^export const sections = .*;\s*\r?\n\s*/m,
-    "",
-  );
   newContent = `export const metadata = { title: '${title}' };
-${sectionsExport}
 	
 ${newContent}`;
 
   fs.writeFileSync(filePath, newContent);
-}
-
-/** Extract ## headings from MDX content to generate sections */
-function extractSections(
-  content: string,
-): Array<{ id: string; title: string }> {
-  const sections: Array<{ id: string; title: string }> = [];
-  // Match ## headings (not ### or deeper)
-  const headingRegex = /^## (.+)$/gm;
-  let match;
-  while ((match = headingRegex.exec(content)) !== null) {
-    const title = match[1].trim();
-    // Generate id from title (kebab-case)
-    const id = title
-      .toLowerCase()
-      .replace(/[^a-z0-9\s-]/g, "")
-      .replace(/\s+/g, "-")
-      .replace(/-+/g, "-");
-    if (id) {
-      sections.push({ id, title });
-    }
-  }
-  return sections;
-}
+};
 
 // Run the script
 rearrangeMdxFilesRecursively(reference);

apps/web/src/app/(docs)/docs/library/page.mdx

@@ -6,7 +6,7 @@ export const metadata = {
 
 # Get started with the library
 
-This guide will get you up and running with Evolu Library.
+This guide will help you get started with the Evolu Library.
 
 <Note>
   Requirements: `TypeScript 5.7` or later with the `strict` flag enabled in
@@ -21,32 +21,36 @@ npm install @evolu/common
 
 ## Learning path
 
-We recommend learning Evolu Library in this order:
+We recommend learning the Evolu Library in this order:
 
-### 1. Result – Error handling
+### 1. Array
 
-Start with [`Result`](/docs/api-reference/common/Result/type-aliases/Result), which provides a type-safe way to handle errors without exceptions. It's the foundation for composable error handling throughout Evolu.
+Start with [`Array`](/docs/api-reference/common/Array), which provides helpers for improved type-safety and developer experience.
 
-### 2. Task – Asynchronous operations
+### 2. Result
 
-Learn [`Task`](/docs/api-reference/common/Task/interfaces/Task), which represents asynchronous computations in a lazy, composable way.
+Learn [`Result`](/docs/api-reference/common/Result/type-aliases/Result), a type-safe way to handle errors. It's the foundation for composable error handling.
 
-### 3. Type – Runtime validation
+### 3. Task
 
-Understand the [`Type`](/docs/api-reference/common/Type) system for runtime validation and parsing. This enables you to enforce constraints at compile-time and validate untrusted data at runtime.
+Continue with [`Task`](/docs/api-reference/common/Task/interfaces/Task) for structured concurrency (promises that can be aborted, monitored, and do not leak).
 
-### 4. Dependency injection
+### 4. Type
 
-Explore the [dependency injection pattern](/docs/dependency-injection) used throughout Evolu for decoupled, testable code.
+Check the [`Type`](/docs/api-reference/common/Type) to enforce constraints at compile-time and validate data at runtime.
 
-### 5. Resource management
+### 5. Dependency injection
 
-Learn [resource management](/docs/resource-management) with `using`, `DisposableStack`, and how it integrates with `Result` for reliable cleanup.
+Explore [dependency injection](/docs/dependency-injection), the pattern Evolu uses to swap implementations and simplify testing.
 
-### 6. Conventions
+### 6. Resource management
+
+See [resource management](/docs/resource-management) — `using`, `DisposableStack`, and how it integrates with `Result` for reliable cleanup.
+
+### 7. Conventions
 
 Review the [Evolu conventions](/docs/conventions) to understand the codebase style and patterns.
 
 ## Exploring the API
 
-After understanding the core concepts, explore the full API in the [API reference](/docs/api-reference/common). All code is commented and test files are written to be read as examples—they demonstrate practical usage patterns and edge cases.
+After understanding the core concepts, explore the full API in the [API reference](/docs/api-reference/common). All code is commented, and tests are written to be read as examples—they demonstrate practical usage patterns and edge cases.

apps/web/src/app/(docs)/docs/local-first/page.mdx

@@ -4,7 +4,7 @@ export const metadata = {
 
 # Get started with local-first
 
-This guide will get you all set up and ready to use Evolu.
+This guide will help you get started with the Evolu local-first platform.
 
 <PlatformSelector />
 

apps/web/src/app/(docs)/docs/page.mdx

@@ -4,6 +4,8 @@ export const metadata = {
     "Learn how to use Evolu, whether you're building with the library or the local-first platform.",
 };
 
+export const sections = [];
+
 # Documentation
 
 Evolu is both a **TypeScript library** and a **local-first platform**. Choose your path below.

apps/web/src/components/Features.tsx

@@ -17,14 +17,14 @@ import {
   IconLibrary,
   IconShieldLock,
   IconSql,
-  TablerIcon,
+  IconProps,
 } from "@tabler/icons-react";
 
 interface Feature {
   id: string;
   name: string;
   description: string;
-  icon: TablerIcon;
+  icon: React.ComponentType<IconProps>;
   pattern: Omit<
     React.ComponentPropsWithoutRef<typeof GridPattern>,
     "width" | "height"

apps/web/src/lib/navigation.ts

@@ -15,6 +15,10 @@ export const navigation: Array<NavGroup> = [
     title: "Library",
     links: [
       { title: "Getting started", href: "/docs/library" },
+      {
+        title: "Array",
+        href: "/docs/api-reference/common/Array",
+      },
       {
         title: "Result",
         href: "/docs/api-reference/common/Result/type-aliases/Result",

apps/web/tsconfig.json

@@ -15,6 +15,7 @@
     "next-env.d.ts",
     "**/*.ts",
     "**/*.tsx",
+    "**/*.mts",
     "next.config.ts",
     ".next/types/**/*.ts",
     "tailwind.config.js"

apps/web/typography.mts

@@ -1,4 +1,3 @@
-/* eslint-disable @typescript-eslint/no-unsafe-assignment */
 import type { Config } from "tailwindcss";
 
 const typographyStyles: Config = {