API reference › @evolu/common › Type › array

function array<ElementType>(
  element: ValidateElement<ElementType>,
): ArrayType<ElementType>;

Defined in: packages/common/src/Type.ts:7501

Array Type.

Use array(Element) for readonly arrays in which every element must match the same Type, such as arrays of IDs or labels.

fromUnknown validates the array and every element. By default, it returns the first issue. Pass { errors: "all" } to collect issues across the whole array. Element errors identify the failing index.

from accepts an array of element Outputs. from.parent accepts an array of values typed as the element's parent Output. Each operation asserts its selected array and element boundary, then returns errors only from the remaining element stages. Additional suffixes move that boundary toward the element's root Type.

An Array must be recognized by Array.isArray, be dense, and have no own properties other than length and the indexed data properties from 0 through length - 1. Subclasses, custom-prototype arrays, and foreign-realm arrays are accepted when their own data representation is valid. Sparse arrays, accessor elements, and excess properties are rejected.

Example

import {
  assertEqual,
  assertErr,
  assertOk,
  assertType,
  Data,
  String,
  array,
  brand,
  type Brand,
  type Result,
} from "@evolu/common";

const UserId = brand("UserId", String);
const UserIds = array(UserId);
const result = UserIds.from.parent(["ada", "grace"]);

assertType<Result<ReadonlyArray<string & Brand<"UserId">>>, typeof result>();
assertOk(result, ["ada", "grace"]);
assertOk(UserIds.fromUnknown(["ada", "grace"]), ["ada", "grace"]);
const invalid = UserIds.fromUnknown("ada");
assertErr(invalid);
assertType(Data, invalid.error);
assertEqual(invalid.error, {
  type: "Array",
  reason: { kind: "NotArray", value: "ada" },
});