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.
-
Evolu
Typeis: -
A TypeScript type with a Brand whenever it's possible.
-
A function to create a value of that type, which may fail.
-
A function to transform value back to its original representation, which cannot fail.
Types are chainable. The chain starts with a Base Type that refines an
unknown value into something and can continue with further refinements or
transformations. For example, NonEmptyTrimmedString100 chain looks like
this:
Unknown -> String -> TrimmedString -> NonEmptyTrimmedString100
For NonEmptyTrimmedString100, the parent Type is TrimmedString. For
TrimmedString, the parent Type is String.
The parent of the String Type is the String Type itself. All Base Types
fromParent functions are just a typed alias to fromUnknown to ensure that
fromParent and toParent can be called on any Type.
Speaking of fromParent and toParent, those functions exist to bypass
parent Types when we can rely on TypeScript types.
Type transformations should be reversible. If you need an irreversible
transformation, such as TrimString (trimming is not reversible as untrim
can't know what has been trimmed), you can do that, but note in JSDoc that
to will not restore the original representation. You can also use
assert: assert(false, "Untrim is not possible").
Tip
If necessary, write globalThis.String instead of String to avoid naming
clashes with Base Types.
Design Decision:
While the from function can fail, the to function cannot. This simplifies
the model by ensuring that every valid input has a corresponding valid
output, eliminating the risk of edge cases caused by irreversible
operations.
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. |