@evolu/common 7.0.0 → 7.2.0

package/src/Array.ts

@@ -1,8 +1,44 @@
 /**
- * 🔒 Type-safe array helpers that do not mutate
+ * Array types, type guards, operations, transformations, accessors, and (rare)
+ * 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.
  *
@@ -319,3 +414,20 @@ export const lastInArray = <T>(array: NonEmptyReadonlyArray<T>): T =>
  * @category Mutations
  */
 export const shiftArray = <T>(array: NonEmptyArray<T>): T => array.shift() as T;
+
+/**
+ * Pops an item from a non-empty mutable array, guaranteed to return T.
+ *
+ * **Mutates** the original array.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const arr: NonEmptyArray<number> = [1, 2, 3];
+ * popArray(arr); // 3
+ * arr; // [1, 2]
+ * ```
+ *
+ * @category Mutations
+ */
+export const popArray = <T>(array: NonEmptyArray<T>): T => array.pop() as T;

package/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";
 
 /**

package/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

package/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.

package/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

package/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
  */

package/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

package/src/Evolu/Public.ts

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

package/src/Order.ts

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

package/src/Platform.ts

@@ -1,9 +1,3 @@
-/**
- * Platform detection utilities for Evolu.
- *
- * @module
- */
-
 /** Detects if the code is running in React Native environment. */
 export const isReactNative =
   typeof navigator !== "undefined" &&

package/src/Random.ts

@@ -1,9 +1,3 @@
-/**
- * 🎲
- *
- * @module
- */
-
 import { Random as RandomLib } from "random";
 
 /**

package/src/Ref.ts

@@ -1,8 +1,3 @@
-/**
- * A mutable reference for managing state
- *
- * @module
- */
 import type { Store } from "./Store.js";
 
 /**

package/src/Result.ts

@@ -1,15 +1,13 @@
 /**
- * 🛡️ Type-safe errors
- *
  * The problem with throwing an exception in JavaScript is that the caught error
  * is always of an unknown type. The unknown type is a problem because we can't
  * be sure all errors have been handled because the TypeScript compiler can't
  * tell us.
  *
- * Languages like Rust 🦀 or Haskell 📚 use a type-safe approach to error
- * handling, where errors are explicitly represented as part of the return type,
- * such as Result or Either, allowing the developer to handle errors safely.
- * TypeScript can have this too via the `Result` type.
+ * Languages like Rust or Haskell use a type-safe approach to error handling,
+ * where errors are explicitly represented as part of the return type, such as
+ * Result or Either, allowing the developer to handle errors safely. TypeScript
+ * can have this too via the `Result` type.
  *
  * The `Result` type can be either {@link Ok} (success) or {@link Err} (error).
  * Use {@link ok} to create a successful result and {@link err} to create an error
@@ -63,7 +61,7 @@
  * - For safe code, use `ok` and `err`.
  * - For unsafe code, use `trySync` or `tryAsync`.
  *
- * Asynchronous safe (because of a Promise using Result) code:
+ * Safe asynchronous code (using Result with a Promise):
  *
  * ```ts
  * const fetchUser = async (
@@ -84,7 +82,7 @@
  * };
  * ```
  *
- * ### Naming Convention
+ * ### Naming convention
  *
  * - For values: `const user = getUser()`
  * - For a single void operation: `const result = foo()`
@@ -117,7 +115,7 @@
  *
  * ### Examples
  *
- * #### Sequential Operations with Short-Circuiting
+ * #### Sequential operations with short-circuiting
  *
  * When performing a sequence of operations where any failure should stop
  * further processing, use the `Result` type with early returns.
@@ -181,7 +179,7 @@
  * };
  * ```
  *
- * ### Handling Unexpected Errors
+ * ### Handling unexpected errors
  *
  * Even with disciplined use of `trySync` and `tryAsync`, unexpected errors can
  * still occur due to programming mistakes, third-party library bugs, or edge
@@ -192,7 +190,7 @@
  * expected errors handled via the `Result` type. Unexpected errors should fail
  * fast - the operation fails immediately and the error bubbles up.
  *
- * #### In Browser Environments
+ * #### In browser environments
  *
  * ```ts
  * // Global error handler for unexpected errors
@@ -209,7 +207,7 @@
  * });
  * ```
  *
- * #### In Node.js Environments
+ * #### In Node.js environments
  *
  * ```ts
  * // Handle uncaught exceptions - log and fail fast
@@ -347,16 +345,16 @@ export interface Ok<T> {
  * An error {@link Result}.
  *
  * The `error` property can be any type that describes the error. For normal
- * business logic, use a plain object. This allows us to structure errors with
+ * domain logic, use a plain object. This allows us to structure errors with
  * custom fields (e.g., `{ type: "MyError", code: 123 }`). Messages for users
  * belong to translations, not to error objects.
  *
- * If you need a stacktrace for debugging, use an `Error` instance or a custom
+ * If you need a stack trace for debugging, use an `Error` instance or a custom
  * error class to include additional metadata.
  *
  * ### Examples
  *
- * #### Business Logic Error (Plain Object, Recommended)
+ * #### Domain logic error (plain object, recommended)
  *
  * ```ts
  * const failure = err({
@@ -366,13 +364,13 @@ export interface Ok<T> {
  * });
  * ```
  *
- * #### Debugging with Stack Trace (Error Instance)
+ * #### Debugging with stack trace (error instance)
  *
  * ```ts
  * const failure = err(new Error("Something went wrong"));
  * ```
  *
- * #### Custom Error Class
+ * #### Custom error class
  *
  * ```ts
  * class MyCustomError extends Error {

package/src/Store.ts

@@ -1,8 +1,3 @@
-/**
- * A mutable reference for managing state with change notifications
- *
- * @module
- */
 import { Eq, eqStrict } from "./Eq.js";
 import { Ref } from "./Ref.js";
 

package/src/Task.ts

@@ -1,21 +1,14 @@
-/**
- * ⚡ Lazy, cancellable Promise that returns Result instead of throwing
- *
- * @module
- */
-
 import { isNonEmptyArray, shiftArray } from "./Array.js";
 import { Result, err, ok } from "./Result.js";
 import { Duration, durationToNonNegativeInt } from "./Time.js";
 import { NonNegativeInt, PositiveInt } from "./Type.js";
 
 /**
- * `Task` is a lazy, cancellable Promise that returns {@link Result} instead of
- * throwing.
+ * `Task` is a function that creates and returns an optionally cancellable
+ * Promise using {@link Result}.
  *
- * In other words, Task is a function that creates a Promise when it's called.
- * This laziness allows safe composition, e.g. retry logic because it prevents
- * eager execution.
+ * The laziness allows safe composition, e.g. retry logic, because it prevents
+ * eager execution until the Task is actually invoked.
  *
  * ### Cancellation
  *

package/src/Time.ts

@@ -1,9 +1,3 @@
-/**
- * ⏳
- *
- * @module
- */
-
 import { assert } from "./Assert.js";
 import { DateIso, NonNegativeInt } from "./Type.js";
 

package/src/Type.ts

@@ -1,5 +1,5 @@
 /**
- * 🧩 Type-safe runtime types
+ * Runtime types
  *
  * Evolu {@link Type} is like a type guard that returns typed errors (via
  * {@link Result}) instead of throwing. We either get a safely typed value or a
@@ -213,7 +213,7 @@ import { hasNodeBuffer } from "./Platform.js";
 import { err, getOrNull, getOrThrow, ok, Result, trySync } from "./Result.js";
 import { safelyStringifyUnknownValue } from "./String.js";
 import type { TimeDep } from "./Time.js";
-import type { Literal, Simplify, WidenLiteral } from "./Types.js";
+import type { Literal, Refinement, Simplify, WidenLiteral } from "./Types.js";
 import { IntentionalNever } from "./Types.js";
 
 export interface Type<
@@ -353,7 +353,7 @@ export interface Type<
    * console.log(filteredStrings); // ["hello", "world"]
    * ```
    */
-  readonly is: (value: unknown) => value is T;
+  readonly is: Refinement<unknown, T>;
 
   readonly [EvoluTypeSymbol]: true;
 

package/src/Types.ts

@@ -22,6 +22,23 @@ import * as Kysely from "kysely";
  */
 export type Predicate<T> = (value: T) => boolean;
 
+/**
+ * Checks a condition on a value at a given index and returns a boolean.
+ *
+ * Useful for callbacks that need both the element and its position.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const isEvenIndex: PredicateWithIndex<string> = (value, index) =>
+ *   index % 2 === 0;
+ *
+ * const items = ["a", "b", "c", "d"];
+ * const evenIndexItems = items.filter(isEvenIndex); // ["a", "c"]
+ * ```
+ */
+export type PredicateWithIndex<T> = (value: T, index: number) => boolean;
+
 /**
  * A type guard function that refines type `A` to a narrower type `B`.
  *
@@ -42,6 +59,31 @@ export type Predicate<T> = (value: T) => boolean;
  */
 export type Refinement<in A, out B extends A> = (a: A) => a is B;
 
+/**
+ * A type guard function that refines type `A` to a narrower type `B` at a given
+ * index.
+ *
+ * Useful for callbacks that need both the element and its position while
+ * maintaining type narrowing.
+ *
+ * ### Example
+ *
+ * ```ts
+ * type Item = { type: "number" | "string"; value: unknown };
+ *
+ * const isNumberItem: RefinementWithIndex<Item, Item & { type: "number" }> =
+ *   (item, index): item is Item & { type: "number" } =>
+ *     index > 0 && item.type === "number";
+ *
+ * const items: ReadonlyArray<Item> = [...];
+ * const [numbers, others] = partitionArray(items, isNumberItem);
+ * ```
+ */
+export type RefinementWithIndex<in A, out B extends A> = (
+  a: A,
+  index: number,
+) => a is B;
+
 /**
  * Makes properties optional if they accept `null` as a value.
  *

package/src/WebSocket.ts

@@ -1,9 +1,3 @@
-/**
- * Websocket with auto-reconnect and offline support
- *
- * @module
- */
-
 import { constVoid } from "./Function.js";
 import { err, ok, Result } from "./Result.js";
 import { retry, RetryError, RetryOptions } from "./Task.js";

package/src/Worker.ts

@@ -1,9 +1,3 @@
-/**
- * Cross-platform worker abstraction
- *
- * @module
- */
-
 import { assert } from "./Assert.js";
 import { createTransferableError, TransferableError } from "./Error.js";