API Reference / @evolu/common / Type
Type
🧩 Validation, Parsing, and Transformation
Intro
You probably know Zod. Evolu has Type.
Evolu Type exists because no existing validation/parsing/transformation library fully met our needs:
- Result-based error handling: Leveraging Result instead of throwing exceptions.
- Consistent constraints: Enforcing Brand for all constraints.
- Typed errors with decoupled formatters: Avoiding coupling error messages with validators.
- No user-land chaining: Designed with ES pipe operator in mind.
- Selective validation/transformation: Skipping parent Type validations and transformations when TypeScript's type system can be relied upon.
- Bidirectional transformations: Supporting transformations in both directions.
- Minimal and transparent code: No runtime dependencies or hidden magic.
Note: A proper quickstart guide is on the way. In the meantime, each type includes its own usage example, and you can (and should) check the tests for practical demonstrations of the API. Or dang, just read the code. It's simple.
Base Factories
| Function | Description |
|---|---|
| array | Array of a specific Type. |
| base | Base Type. |
| brand | Branded Type. |
| instanceOf | instanceof Type. |
| literal | Literal Type. |
| nullishOr | union(undefined, null, T) Type. |
| nullOr | union(null, T) Type. |
| object | Object Type. |
| record | Record of a key Type and value Type. |
| recursive | Recursive Type. |
| transform | Type that transforms values between FromType and ToType. |
| tuple | Tuple Type. |
| undefinedOr | union(undefined, T) Type. |
| union | Union Type. |
Base Types
| Variable | Description |
|---|---|
| BigInt | - |
| Boolean | - |
| Date | JavaScript Date. |
| Function | - |
| JsonValue | JSON-compatible value: string, FiniteNumber, boolean, null, JsonArray, or JsonObject. |
| Null | - |
| Number | - |
| String | - |
| Uint8Array | - |
| Undefined | - |
| Unknown | - |
String
| Name | Description |
|---|---|
| Base64Url | URL-safe Base64 string. |
| CurrencyCode | A three-letter ISO 4217 currency code (e.g., USD, EUR). |
| DateIso | Transforms a Date into a DateIsoString string and vice versa. |
| DateIsoString | ISO 8601 date-time string. |
| Id | Id Type. |
| Json | JSON-string Type. |
| JsonValueFromString | Transform Type that parses a JSON into a JsonValue and serializes a JsonValue back into a JSON string. |
| length | Exact length. |
| maxLength | Maximum length. |
| minLength | Minimum length. |
| Mnemonic | The mnemonic, also known as a "seed phrase," is a set of 12 words in a specific order chosen from a predefined list (BIP39). It provides a human-readable way to store a private key securely. The mnemonic is generated safely on the user's device using cryptographically secure random number generation, ensuring it remains private and unique. |
| NanoId | Default NanoId. |
| NonEmptyString | - |
| NonEmptyString100 | - |
| NonEmptyString1000 | - |
| NonEmptyTrimmedString | - |
| NonEmptyTrimmedString100 | - |
| NonEmptyTrimmedString1000 | - |
| regex | String matching a regular expression. |
| SimpleName | Simple alphanumeric string for naming. |
| SimplePassword | Trimmed string between 8 and 64 characters, branded as SimplePassword. |
| String | - |
| String100 | - |
| String1000 | - |
| trim | Trims leading and trailing whitespace from a string. |
| trimmed | Trimmed string. |
| TrimmedString | Trimmed string |
| TrimmedString100 | - |
| TrimmedString1000 | - |
| TrimString | Trims leading and trailing whitespace from a string. |
| id | Type Factory to create branded Id Type for a specific table. |
Number
| Variable | Description |
|---|---|
| between | Number within a range, inclusive. |
| Between1And10 | - |
| finite | Finite number. |
| FiniteNumber | Finite number. |
| greaterThan | Number greater than a specified value. |
| greaterThanOrEqualTo | Number ≥ a specified value. |
| int | Integer within the safe range of JavaScript numbers. |
| Int | Integer within the safe range of JavaScript numbers. |
| Int64 | 64-bit signed integer. |
| Int64String | Stringified Int64. |
| lessThan | Number less than a specified value. |
| lessThanOrEqualTo | Number ≤ a specified value. |
| multipleOf | Number that is a multiple of a divisor. |
| negative | Negative number. |
| NegativeInt | - |
| NegativeNumber | - |
| nonNaN | Number that is not NaN. |
| NonNaNNumber | - |
| nonNegative | Non-negative number. |
| NonNegativeInt | - |
| NonNegativeNumber | - |
| nonPositive | Non-positive number. |
| NonPositiveInt | - |
| NonPositiveNumber | - |
| NumberFromString | Transforms a NonEmptyTrimmedString into a FiniteNumber. |
| positive | Positive number. |
| PositiveInt | - |
| PositiveNumber | - |
Array
| Name | Description |
|---|---|
| JsonArray | JSON-compatible array of JsonValue elements. |
| length | Exact length. |
| maxLength | Maximum length. |
| minLength | Minimum length. |
| array | Array of a specific Type. |
Object
| Name | Description |
|---|---|
| JsonObject | JSON-compatible object with string keys and JsonValue values. |
| nullableToOptional | Converts each “nullable” property (a union that includes Null) into an optional property. This means consumers can omit the property entirely, or set it to null, or set it to the non-null member of the union. |
| object | Object Type. |
| omit | Create a new object Type by omitting some keys. |
| partial | Creates a partial object type where all properties are optional. |
| record | Record of a key Type and value Type. |
Utilities
| Name | Description |
|---|---|
| BrandFactory | Helper type for Type Factory that creates a branded Type. |
| MergeObjectTypeErrors | Merge Error and ParentError into one ObjectError so tooltips and error messages are easier to read. |
| TypeErrors | Union of all TypeErrors defined in the Type.ts file, including base type errors (e.g., StringError, NumberError), composite type errors (ArrayError, ObjectError), and optionally, user-defined extra errors. |
| TypeName | Unique identifier for a Type. |
| createBaseTypeErrorFormatter | Creates a formatter function for a base TypeError. |
| createFormatTypeError | Creates a unified error formatter that handles both Evolu Type's built-in TypeErrors and custom errors. It also lets us override the default formatting for specific errors. |
| createTypeErrorFormatter | Creates a formatter function for TypeError. |
| isType | Checks if the given value is an Type. |