Add partitionArray and refinement support to filterArray

Introduces the partitionArray function for type-safe array partitioning with support for type narrowing via refinements. Enhances filterArray to accept refinement overloads, enabling type-safe filtering (e.g., PositiveInt.is). Adds PredicateWithIndex and RefinementWithIndex types for index-aware predicates and type guards, updates documentation, and cleans up module headers.

Author: steida

.changeset/gold-carrots-worry.md

@@ -0,0 +1,10 @@
+---
+"@evolu/common": minor
+---
+
+Added `partitionArray` function and refinement support to `filterArray`.
+
+- New `partitionArray` function partitions arrays returning a tuple of matched/unmatched with type narrowing support
+- Enhanced `filterArray` with refinement overloads for type-safe filtering (e.g., `PositiveInt.is`)
+- Added `PredicateWithIndex` and `RefinementWithIndex` types for index-aware predicates and type guards
+- Improved documentation and cleaned up module headers

packages/common/src/Array.ts

@@ -1,8 +1,44 @@
 /**
- * 🔒 Type-safe array helpers that do not mutate
+ * Array types, type guards, operations, transformations, accessors, and
+ * mutations
  *
- * Array types, guards, operations, transformations, accessors, and (rare)
- * mutations.
+ * ### Example
+ *
+ * ```ts
+ * // Types - compile-time guarantee of at least one element
+ * const _valid: NonEmptyReadonlyArray<number> = [1, 2, 3];
+ * // ts-expect-error - empty array is not a valid NonEmptyReadonlyArray
+ * const _invalid: NonEmptyReadonlyArray<number> = [];
+ *
+ * // Type guards
+ * const arr: ReadonlyArray<number> = [1, 2, 3];
+ * if (isNonEmptyReadonlyArray(arr)) {
+ *   firstInArray(arr);
+ * }
+ *
+ * // Operations
+ * const appended = appendToArray([1, 2, 3], 4); // [1, 2, 3, 4]
+ * const prepended = prependToArray([2, 3], 1); // [1, 2, 3]
+ *
+ * // Transformations
+ * const readonly: ReadonlyArray<number> = [1, 2, 3];
+ * const mapped = mapArray(readonly, (x) => x * 2); // [2, 4, 6]
+ * const filtered = filterArray(readonly, (x) => x > 1); // [2, 3]
+ * const deduped = dedupeArray([1, 2, 1, 3, 2]); // [1, 2, 3]
+ * const [evens, odds] = partitionArray(
+ *   [1, 2, 3, 4, 5],
+ *   (x) => x % 2 === 0,
+ * ); // [[2, 4], [1, 3, 5]]
+ *
+ * // Accessors
+ * const first = firstInArray(["a", "b", "c"]); // "a"
+ * const last = lastInArray(["a", "b", "c"]); // "c"
+ *
+ * // Mutations
+ * const mutable: NonEmptyArray<number> = [1, 2, 3];
+ * shiftArray(mutable); // 1 (guaranteed to exist)
+ * mutable; // [2, 3]
+ * ```
  *
  * Functions are intentionally data-first to be prepared for the upcoming
  * JavaScript pipe operator.
@@ -43,43 +79,11 @@
  * **Note**: Feel free to use Array instance methods (mutation) if you think
  * it's better (performance, local scope, etc.).
  *
- * ### Example
- *
- * ```ts
- * // Types - compile-time guarantee of at least one element
- * const _valid: NonEmptyReadonlyArray<number> = [1, 2, 3];
- * // ts-expect-error - empty array is not a valid NonEmptyReadonlyArray
- * const _invalid: NonEmptyReadonlyArray<number> = [];
- *
- * // Guards
- * const arr: ReadonlyArray<number> = [1, 2, 3];
- * if (isNonEmptyReadonlyArray(arr)) {
- *   firstInArray(arr);
- * }
- *
- * // Operations
- * const appended = appendToArray([1, 2, 3], 4); // [1, 2, 3, 4]
- * const prepended = prependToArray([2, 3], 1); // [1, 2, 3]
- *
- * // Transformations
- * const readonly: ReadonlyArray<number> = [1, 2, 3];
- * const mapped = mapArray(readonly, (x) => x * 2); // [2, 4, 6]
- * const filtered = filterArray(readonly, (x) => x > 1); // [2, 3]
- * const deduped = dedupeArray([1, 2, 1, 3, 2]); // [1, 2, 3]
- *
- * // Accessors
- * const first = firstInArray(["a", "b", "c"]); // "a"
- * const last = lastInArray(["a", "b", "c"]); // "c"
- *
- * // Mutations
- * const mutable: NonEmptyArray<number> = [1, 2, 3];
- * shiftArray(mutable); // 1 (guaranteed to exist)
- * mutable; // [2, 3]
- * ```
- *
  * @module
  */
 
+import { PredicateWithIndex, RefinementWithIndex } from "./Types.js";
+
 /**
  * An array with at least one element.
  *
@@ -175,8 +179,7 @@ export const prependToArray = <T>(
 /**
  * Maps an array using a mapper function.
  *
- * Accepts both mutable and readonly arrays. Does not mutate the original array.
- * Preserves non-empty type.
+ * Accepts both mutable and readonly arrays. Preserves non-empty type.
  *
  * ### Example
  *
@@ -202,22 +205,49 @@ export function mapArray<T, U>(
 }
 
 /**
- * Filters an array using a predicate function, returning a new readonly array.
+ * Filters an array using a predicate or refinement function, returning a new
+ * readonly array.
  *
- * Accepts both mutable and readonly arrays. Does not mutate the original array.
+ * Accepts both mutable and readonly arrays. When used with a refinement
+ * function (with `value is Type` syntax), TypeScript will narrow the result
+ * type to the narrowed type, making it useful for filtering with Evolu Types
+ * like `PositiveInt.is`.
  *
- * ### Example
+ * ### Examples
+ *
+ * #### With predicate
  *
  * ```ts
  * filterArray([1, 2, 3, 4, 5], (x) => x % 2 === 0); // [2, 4]
  * ```
  *
+ * #### With refinement
+ *
+ * ```ts
+ * const mixed: ReadonlyArray<NonEmptyString | PositiveInt> = [
+ *   NonEmptyString.orThrow("hello"),
+ *   PositiveInt.orThrow(42),
+ * ];
+ * const positiveInts = filterArray(mixed, PositiveInt.is);
+ * // positiveInts: ReadonlyArray<PositiveInt> (narrowed type)
+ * ```
+ *
  * @category Transformations
  */
-export const filterArray = <T>(
+export function filterArray<T, S extends T>(
+  array: ReadonlyArray<T>,
+  refinement: RefinementWithIndex<T, S>,
+): ReadonlyArray<S>;
+export function filterArray<T>(
+  array: ReadonlyArray<T>,
+  predicate: PredicateWithIndex<T>,
+): ReadonlyArray<T>;
+export function filterArray<T>(
   array: ReadonlyArray<T>,
-  predicate: (item: T, index: number) => boolean,
-): ReadonlyArray<T> => array.filter(predicate) as ReadonlyArray<T>;
+  predicate: PredicateWithIndex<T>,
+): ReadonlyArray<T> {
+  return array.filter(predicate) as ReadonlyArray<T>;
+}
 
 /**
  * Returns a new readonly array with duplicate items removed. If `by` is
@@ -272,6 +302,71 @@ export function dedupeArray<T>(
   }) as ReadonlyArray<T>;
 }
 
+/**
+ * Partitions an array into two arrays based on a predicate or refinement
+ * function.
+ *
+ * Returns a tuple where the first array contains elements that satisfy the
+ * predicate, and the second array contains elements that do not. Accepts both
+ * mutable and readonly arrays.
+ *
+ * When used with a refinement function (with `value is Type` syntax),
+ * TypeScript will narrow the first array to the narrowed type, making it useful
+ * for filtering with Evolu Types like `PositiveInt.is`.
+ *
+ * ### Examples
+ *
+ * #### With predicate
+ *
+ * ```ts
+ * const [evens, odds] = partitionArray(
+ *   [1, 2, 3, 4, 5],
+ *   (x) => x % 2 === 0,
+ * );
+ * evens; // [2, 4]
+ * odds; // [1, 3, 5]
+ * ```
+ *
+ * #### With refinement
+ *
+ * ```ts
+ * const mixed: ReadonlyArray<NonEmptyString | PositiveInt> = [
+ *   NonEmptyString.orThrow("hello"),
+ *   PositiveInt.orThrow(42),
+ * ];
+ * const [positiveInts, strings] = partitionArray(mixed, PositiveInt.is);
+ * // positiveInts: ReadonlyArray<PositiveInt> (narrowed type)
+ * // strings: ReadonlyArray<NonEmptyString> (Exclude<T, PositiveInt>)
+ * ```
+ *
+ * @category Transformations
+ */
+export function partitionArray<T, S extends T>(
+  array: ReadonlyArray<T>,
+  refinement: RefinementWithIndex<T, S>,
+): readonly [ReadonlyArray<S>, ReadonlyArray<Exclude<T, S>>];
+export function partitionArray<T>(
+  array: ReadonlyArray<T>,
+  predicate: PredicateWithIndex<T>,
+): readonly [ReadonlyArray<T>, ReadonlyArray<T>];
+export function partitionArray<T>(
+  array: ReadonlyArray<T>,
+  predicate: PredicateWithIndex<T>,
+): readonly [ReadonlyArray<T>, ReadonlyArray<T>] {
+  const trueArray: Array<T> = [];
+  const falseArray: Array<T> = [];
+
+  for (let i = 0; i < array.length; i++) {
+    if (predicate(array[i], i)) {
+      trueArray.push(array[i]);
+    } else {
+      falseArray.push(array[i]);
+    }
+  }
+
+  return [trueArray as ReadonlyArray<T>, falseArray as ReadonlyArray<T>];
+}
+
 /**
  * Returns the first element of a non-empty array.
  *

packages/common/src/Assert.ts

@@ -1,17 +1,3 @@
-/**
- * 🚨
- *
- * This module provides assertion utilities to prevent invalid states from
- * propagating through the system by halting execution when a condition fails,
- * improving reliability and debuggability.
- *
- * **Warning**: Do not use this instead of {@link Type}. Assertions are intended
- * for conditions that are logically guaranteed but not statically known by
- * TypeScript, or for catching and signaling developer mistakes eagerly (e.g.,
- * invalid configuration).
- *
- * @module
- */
 import type { Type } from "./Type.js";
 
 /**

packages/common/src/Brand.ts

@@ -67,7 +67,7 @@ declare const __brand: unique symbol;
  *
  * Works with any base type intersected with a `Brand`.
  *
- * ### Examples
+ * ### Example
  *
  * - `IsBranded<string>` -> false
  * - `IsBranded<string & Brand<"X">>` -> true

packages/common/src/Cache.ts

@@ -1,9 +1,3 @@
-/**
- * 🗄️ Generic cache interface and LRU cache implementation.
- *
- * @module
- */
-
 import { PositiveInt } from "./Type.js";
 
 /**
@@ -32,7 +26,7 @@ export interface Cache<K, V> {
 }
 
 /**
- * Creates a Least Recently Used (LRU) cache with a maximum capacity.
+ * Creates an LRU (least recently used) cache with a maximum capacity.
  *
  * When the cache reaches capacity, the least recently used entry is evicted.
  * Both `get` and `set` operations update the access order.

packages/common/src/Console.ts

@@ -1,5 +1,5 @@
 /**
- * 📝 Cross-platform console
+ * Cross-platform console
  *
  * Console abstraction for Chrome 123+, Firefox 125+, Safari 18.1+, Node.js
  * 22.x+, and React Native 0.75+. Includes methods guaranteed to be available in

packages/common/src/Crypto.ts

@@ -1,5 +1,9 @@
 /**
- * 🔒
+ * Cryptographic utilities
+ *
+ * Type-safe cryptographic operations including random number generation, SLIP21
+ * key derivation, XChaCha20-Poly1305 symmetric encryption, PADMÉ padding, and
+ * timing-safe comparisons.
  *
  * @module
  */

packages/common/src/Evolu/Internal.ts

@@ -1,10 +1,10 @@
 /**
- * 🛠️
+ * Internal Evolu
  *
  * ### Example
  *
  * ```ts
- * import { Evolu } from "@evolu/common/evolu";
+ * import { createTimestamp } from "@evolu/common/evolu";
  * ```
  *
  * @module

packages/common/src/Evolu/Public.ts

@@ -1,5 +1,5 @@
 /**
- * 💾
+ * Public Evolu
  *
  * @module
  */

packages/common/src/Order.ts

@@ -1,9 +1,3 @@
-/**
- * 🔢
- *
- * @module
- */
-
 /**
  * Compares two values of type `A` and returns their ordering.
  *