Indexes
# Indexes
Are your queries taking too long to run? Measure their performance using the `logQueryExecutionTime` option:
```ts
const allTodos = evolu.createQuery(
(db) => db.selectFrom("todo").orderBy("createdAt").selectAll(),
{
logQueryExecutionTime: true,
// logExplainQueryPlan: false,
},
);
```
<Note>
While indexes may not be needed during early development, they are crucial for
production performance. Use the `logQueryExecutionTime` and
`logExplainQueryPlan` options in `createQuery` to measure and analyze
performance.
</Note>
For deeper insights into how SQLite indexes work under the hood, read [this in-depth guide](https://medium.com/@JasonWyatt/squeezing-performance-from-sqlite-indexes-indexes-c4e175f3c346).
<Heading level={2} id="usage">
Usage
</Heading>
```ts
const evolu = createEvolu(evoluReactWebDeps)(Schema, {
// ...
indexes: (create) => [create("todoCreatedAt").on("todo").column("createdAt")],
});
```
Evolu handles this automatically—it will create any new indexes you define and drop those no longer present in the `indexes` array.
<Heading level={2} id="recommendations">
Recommendations
</Heading>
SQLite offers a powerful [CLI tool](https://sqlite.org/cli.html#index_recommendations_sqlite_expert_) for index recommendations.
To use it:
1. Download the "Precompiled Binaries" [here](https://www.sqlite.org/download.html).
2. Open your database or create a new one.
3. Run `.expert` and paste in the SQL of the query you're analyzing.
You can get the query SQL using the `logQueryExecutionTime` option in `createQuery`, which logs the full SQL statement for easy copy-paste.
Migrations
# Migrations
Traditional centralized databases are versioned and updated using migration scripts. However, this approach isn't practical for local-first databases. Migration scripts can be slow when processing large amounts of local data, and if a migration fails, there's no centralized database to fix—each failed instance would need to be repaired individually.
For these reasons, Evolu embraces a version-less append-only schema—the same pattern as [GraphQL schema design](https://graphql.org/learn/schema-design/). Facebook adopted this pattern to maintain a single endpoint for countless clients, including those that had not been updated for years. Evolu applies this principle to local-first databases, ensuring compatibility across all versions.
## Append only schema
Once an Evolu app is released, the existing database schema must remain unchanged. That means:
- **No renaming tables**
- **No renaming columns**
- **No changing column types**
This is important because there's always a chance that some data has already been created using the previous schema. Changing it would break compatibility.
Instead of migrations, simply add new tables and columns to the existing schema. Newer app code must keep already existing tables and columns in the schema (don't delete them) and continue using them when receiving data from previous app versions. For example, if you replace a string `address` column with an `addressId` column (because we have a new address table), the app should use `addressId` when present, and fall back to `address` when it's not.
This append-only approach raises an important question: if new tables and columns can be added over time and obsolete ones can stop being used at all, how should Evolu apps handle that? The answer is another [GraphQL schema design](https://graphql.org/learn/schema-design/) pattern—nullability.
## Nullability
To understand how Evolu handles nullability, let's look at a simple schema:
```ts {{ title: 'schema.ts' }}
const TodoId = id("Todo");
const Schema = {
todo: {
id: TodoId,
title: NonEmptyString100,
isCompleted: nullOr(SqliteBoolean),
},
};
```
In this schema, `id` and `title` columns are not nullable, while `isCompleted` is nullable (it may have been added later, or it's just not required when a new todo is inserted).
However, even though `title` is not nullable—which is enforced in mutations—Evolu treats it as nullable when writing queries. This forces developers to explicitly define the shape they want.
```ts {{ title: 'query.ts' }}
// Evolu uses Kysely for type-safe SQL (https://kysely.dev/).
const todosQuery = evolu.createQuery((db) =>
db
// Type-safe SQL: try autocomplete for table and column names.
.selectFrom("todo")
.select(["id", "title", "isCompleted"])
// Soft delete: filter out deleted rows.
.where("isDeleted", "is not", sqliteTrue)
// Like with GraphQL, all columns except id are nullable in queries
// (even if defined without nullOr in the schema) to allow schema
// evolution without migrations. Filter nulls with where + $narrowType.
.where("title", "is not", null)
.$narrowType<{ title: kysely.NotNull }>()
// Columns createdAt, updatedAt, isDeleted are auto-added to all tables.
.orderBy("createdAt"),
);
```
This approach ensures data integrity even when CRDT messages arrive out of order. For example, a message deleting a todo might arrive before the message creating it. By explicitly filtering for the shape the current app expects, only valid rows—or rows the current version of the app can handle—are selected from the database.
Just like schemas, queries must be append-only as well. If we stop querying obsolete columns or tables, older data using those columns will suddenly disappear from the results.
Time Travel
# Time Travel
Evolu does not delete data—it only marks it as deleted. This is a fundamental design choice because **local-first is a distributed system**. There is no central authority (if there is, it’s not truly local-first).
Imagine this scenario: you delete a piece of data on a disconnected device, while another device updates that same data. Should the update be discarded? To enforce true deletion across all devices—even future ones—would require complex logic to reject the data forever, without exposing the original data (for security reasons). This is possible (and planned for Evolu), but it's not trivial.
By retaining all data, Evolu enables **time travel**. All mutations—including deletes and overrides—are stored in the `evolu_history` table.
Here’s how to query the history of a specific column:
```ts
const titleHistoryQuery = evolu.createQuery((db) =>
db
.selectFrom("evolu_history")
.select(["value", "timestamp"])
.where("table", "==", "todo")
.where("id", "==", idToIdBytes(id))
.where("column", "==", "title")
// `value` isn't typed; this is how we can narrow its type.
.$narrowType<{ value: (typeof Schema)["todo"]["title"]["Type"] }>()
.orderBy("timestamp", "desc"),
);
const handleHistoryClick = () => {
void evolu.loadQuery(titleHistoryQuery).then((rows) => {
const rowsWithTimestamp = rows.map((row) => ({
value: row.value,
timestamp: timestampToDateIso(timestampBytesToTimestamp(row.timestamp)),
}));
alert(JSON.stringify(rowsWithTimestamp, null, 2));
});
};
```
This API isn’t fully type-safe, but it’s not a concern. Evolu Schemas are append-only. Once an app is released, do not rename or change the type of an existing table or column — only add new tables or columns to evolve your schema; changing existing columns or types breaks compatibility with historical data.
API reference
export const sections = [];
# API Reference
## Modules
| Module | Description |
| ---------------------------------------------------------------- | ----------- |
| [@evolu/common](https://evolu.dev/docs/api-reference/common) | - |
| [@evolu/nodejs](https://evolu.dev/docs/api-reference/nodejs) | - |
| [@evolu/react](https://evolu.dev/docs/api-reference/react) | - |
| [@evolu/react-native](https://evolu.dev/docs/api-reference/react-native) | - |
| [@evolu/react-web](https://evolu.dev/docs/api-reference/react-web) | - |
| [@evolu/svelte](https://evolu.dev/docs/api-reference/svelte) | - |
| [@evolu/vue](https://evolu.dev/docs/api-reference/vue) | - |
| [@evolu/web](https://evolu.dev/docs/api-reference/web) | - |
API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / @evolu/common
# @evolu/common
## Modules
| Module | Description |
| -------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| [Array](https://evolu.dev/docs/api-reference/common/Array) | Array types, type guards, operations, transformations, accessors, and (rare) mutations |
| [Assert](https://evolu.dev/docs/api-reference/common/Assert) | - |
| [BigInt](https://evolu.dev/docs/api-reference/common/BigInt) | - |
| [Brand](https://evolu.dev/docs/api-reference/common/Brand) | - |
| [Buffer](https://evolu.dev/docs/api-reference/common/Buffer) | - |
| [Cache](https://evolu.dev/docs/api-reference/common/Cache) | - |
| [Callbacks](https://evolu.dev/docs/api-reference/common/Callbacks) | - |
| [Console](https://evolu.dev/docs/api-reference/common/Console) | - |
| [Crypto](https://evolu.dev/docs/api-reference/common/Crypto) | Cryptographic utilities |
| [Eq](https://evolu.dev/docs/api-reference/common/Eq) | - |
| [Error](https://evolu.dev/docs/api-reference/common/Error) | - |
| [Function](https://evolu.dev/docs/api-reference/common/Function) | - |
| [Identicon](https://evolu.dev/docs/api-reference/common/Identicon) | - |
| [Instances](https://evolu.dev/docs/api-reference/common/Instances) | - |
| [local-first](https://evolu.dev/docs/api-reference/common/local-first) | Internal local-first modules re-exported from "@evolu/common/local-first" |
| [local-first/Protocol](https://evolu.dev/docs/api-reference/common/local-first/Protocol) | Evolu Protocol |
| [local-first/Public](https://evolu.dev/docs/api-reference/common/local-first/Public) | Public local-first API exported from "@evolu/common" |
| [Number](https://evolu.dev/docs/api-reference/common/Number) | - |
| [Object](https://evolu.dev/docs/api-reference/common/Object) | - |
| [Order](https://evolu.dev/docs/api-reference/common/Order) | - |
| [Platform](https://evolu.dev/docs/api-reference/common/Platform) | - |
| [Random](https://evolu.dev/docs/api-reference/common/Random) | - |
| [Redacted](https://evolu.dev/docs/api-reference/common/Redacted) | - |
| [Ref](https://evolu.dev/docs/api-reference/common/Ref) | - |
| [Relation](https://evolu.dev/docs/api-reference/common/Relation) | - |
| [Resources](https://evolu.dev/docs/api-reference/common/Resources) | - |
| [Result](https://evolu.dev/docs/api-reference/common/Result) | - |
| [Sqlite](https://evolu.dev/docs/api-reference/common/Sqlite) | - |
| [Store](https://evolu.dev/docs/api-reference/common/Store) | - |
| [String](https://evolu.dev/docs/api-reference/common/String) | - |
| [Task](https://evolu.dev/docs/api-reference/common/Task) | - |
| [Time](https://evolu.dev/docs/api-reference/common/Time) | - |
| [Type](https://evolu.dev/docs/api-reference/common/Type) | - |
| [Types](https://evolu.dev/docs/api-reference/common/Types) | TypeScript utility types |
| [WebSocket](https://evolu.dev/docs/api-reference/common/WebSocket) | - |
| [Worker](https://evolu.dev/docs/api-reference/common/Worker) | - |
API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / @evolu/nodejs
# @evolu/nodejs
## Modules
| Module | Description |
| -------------------------------------------------- | ----------- |
| [index](https://evolu.dev/docs/api-reference/nodejs/index) | - |
API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / @evolu/react
# @evolu/react
## Modules
| Module | Description |
| ------------------------------------------------- | ----------- |
| [index](https://evolu.dev/docs/api-reference/react/index) | - |
API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / @evolu/react-native
# @evolu/react-native
## Modules
| Module | Description |
| ------------------------------------------------------------------------------------------ | ----------- |
| [exports/bare-op-sqlite](https://evolu.dev/docs/api-reference/react-native/exports/bare-op-sqlite) | - |
| [exports/expo-op-sqlite](https://evolu.dev/docs/api-reference/react-native/exports/expo-op-sqlite) | - |
| [exports/expo-sqlite](https://evolu.dev/docs/api-reference/react-native/exports/expo-sqlite) | - |
| [web](https://evolu.dev/docs/api-reference/react-native/web) | - |
API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / @evolu/svelte
# @evolu/svelte
## Modules
| Module | Description |
| ---------------------------------------------------------------- | ----------- |
| [index.svelte](https://evolu.dev/docs/api-reference/svelte/index.svelte) | - |
API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / @evolu/vue
# @evolu/vue
## Modules
| Module | Description |
| ----------------------------------------------- | ----------- |
| [index](https://evolu.dev/docs/api-reference/vue/index) | - |
API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / @evolu/react-web
# @evolu/react-web
## Modules
| Module | Description |
| ----------------------------------------------------- | ----------- |
| [index](https://evolu.dev/docs/api-reference/react-web/index) | - |
API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / @evolu/web
# @evolu/web
## Modules
| Module | Description |
| ----------------------------------------------- | ----------- |
| [index](https://evolu.dev/docs/api-reference/web/index) | - |
API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / Array
# Array
Array types, type 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.
```ts
// Data-first is natural for single operations.
const timestamps = mapArray(messages, (m) => m.timestamp);
// But data-first can be hard to read for nested calls.
const result = firstInArray(
mapArray(dedupeArray(appendToArray(value, 2)), (x) => x * 2),
);
// With the upcoming pipe operator, it's clear.
// const result = value
// |> appendToArray(%, 2)
// |> dedupeArray(%)
// |> mapArray(%, (x) => x * 2)
// |> firstInArray(%);
// Until the pipe operator lands, use nested calls or name each step:
const appended = appendToArray(value, 2);
const deduped = dedupeArray(appended);
const mapped = mapArray(deduped, (x) => x * 2);
const result = firstInArray(mapped);
```
### Why data-first?
Evolu optimizes for consistent code style. We can't have both data-first
single operations and curried data-last helpers without sacrificing
consistency. We chose data-first because:
- It's natural for single operations (for example `mapArray(messages, (m) =>
m.timestamp)`).
- It aligns with the upcoming JavaScript pipe operator.
**Note**: Feel free to use Array instance methods (mutation) if you think
it's better (performance, local scope, etc.).
## Accessors
| Function | Description |
| --------------------------------------------------------------------------- | ----------------------------------------------- |
| [firstInArray](https://evolu.dev/docs/api-reference/common/Array/functions/firstInArray) | Returns the first element of a non-empty array. |
| [lastInArray](https://evolu.dev/docs/api-reference/common/Array/functions/lastInArray) | Returns the last element of a non-empty array. |
## Mutations
| Function | Description |
| ----------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| [popArray](https://evolu.dev/docs/api-reference/common/Array/functions/popArray) | Pops an item from a non-empty mutable array, guaranteed to return T. |
| [shiftArray](https://evolu.dev/docs/api-reference/common/Array/functions/shiftArray) | Shifts an item from a non-empty mutable array, guaranteed to return T. |
## Operations
| Function | Description |
| ------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
| [appendToArray](https://evolu.dev/docs/api-reference/common/Array/functions/appendToArray) | Appends an item to an array, returning a new non-empty readonly array. |
| [prependToArray](https://evolu.dev/docs/api-reference/common/Array/functions/prependToArray) | Prepends an item to an array, returning a new non-empty readonly array. |
## Transformations
| Function | Description |
| ------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [dedupeArray](https://evolu.dev/docs/api-reference/common/Array/functions/dedupeArray) | Returns a new readonly array with duplicate items removed. If `by` is provided, it will be used to derive the key for uniqueness; otherwise values are used directly. Dedupes by reference equality of values (or extracted keys when `by` is used). |
| [filterArray](https://evolu.dev/docs/api-reference/common/Array/functions/filterArray) | Filters an array using a predicate or refinement function, returning a new readonly array. |
| [mapArray](https://evolu.dev/docs/api-reference/common/Array/functions/mapArray) | Maps an array using a mapper function. |
| [partitionArray](https://evolu.dev/docs/api-reference/common/Array/functions/partitionArray) | Partitions an array into two arrays based on a predicate or refinement function. |
## Type Guards
| Function | Description |
| ------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [isNonEmptyArray](https://evolu.dev/docs/api-reference/common/Array/functions/isNonEmptyArray) | Checks if an array is non-empty and narrows its type to [NonEmptyArray](https://evolu.dev/docs/api-reference/common/Array/type-aliases/NonEmptyArray). |
| [isNonEmptyReadonlyArray](https://evolu.dev/docs/api-reference/common/Array/functions/isNonEmptyReadonlyArray) | Checks if a readonly array is non-empty and narrows its type to [NonEmptyReadonlyArray](https://evolu.dev/docs/api-reference/common/Array/type-aliases/NonEmptyReadonlyArray). |
## Types
| Type Alias | Description |
| ------------------------------------------------------------------------------------------------ | ------------------------------------------- |
| [NonEmptyArray](https://evolu.dev/docs/api-reference/common/Array/type-aliases/NonEmptyArray) | An array with at least one element. |
| [NonEmptyReadonlyArray](https://evolu.dev/docs/api-reference/common/Array/type-aliases/NonEmptyReadonlyArray) | A readonly array with at least one element. |
API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / Assert
# Assert
## Variables
| Variable | Description |
| ---------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| [assert](https://evolu.dev/docs/api-reference/common/Assert/variables/assert) | Ensures a condition is true, throwing an error with the provided message if not. |
| [assertNonEmptyArray](https://evolu.dev/docs/api-reference/common/Assert/variables/assertNonEmptyArray) | Asserts that an array is non-empty. |
| [assertNonEmptyReadonlyArray](https://evolu.dev/docs/api-reference/common/Assert/variables/assertNonEmptyReadonlyArray) | Asserts that a readonly array is non-empty. |
API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / BigInt
# BigInt
## Functions
| Function | Description |
| ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| [clampBigInt](https://evolu.dev/docs/api-reference/common/BigInt/functions/clampBigInt) | Clamps a bigint within a given range. |
| [decrementBigInt](https://evolu.dev/docs/api-reference/common/BigInt/functions/decrementBigInt) | Decrements a bigint by 1. |
| [incrementBigInt](https://evolu.dev/docs/api-reference/common/BigInt/functions/incrementBigInt) | Increments a bigint by 1. |
| [isBetweenBigInt](https://evolu.dev/docs/api-reference/common/BigInt/functions/isBetweenBigInt) | Creates a predicate that checks if a BigInt is within a range, inclusive. |
API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / Brand
# Brand
## Interfaces
| Interface | Description |
| -------------------------------------------------------------- | ----------------------------------------------- |
| [Brand](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand) | A utility interface for creating branded types. |
## Type Aliases
| Type Alias | Description |
| ------------------------------------------------------------------------ | ------------------------------------------------ |
| [IsBranded](https://evolu.dev/docs/api-reference/common/Brand/type-aliases/IsBranded) | Determines whether a type `T` is a branded type. |
API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / Buffer
# Buffer
## Classes
| Class | Description |
| ------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [BufferError](https://evolu.dev/docs/api-reference/common/Buffer/classes/BufferError) | Custom error for [Buffer](https://evolu.dev/docs/api-reference/common/Buffer/interfaces/Buffer)-related failures like premature end of data. Provides better stack traces for debugging binary protocol issues. |
## Interfaces
| Interface | Description |
| ----------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Buffer](https://evolu.dev/docs/api-reference/common/Buffer/interfaces/Buffer) | A Buffer is a dynamic, resizable container for binary data, optimized for scenarios where the final size is unknown. It grows exponentially (doubling its capacity) to minimize memory reallocations and uses `subarray` for efficient, copy-free data access in methods like `unwrap` and `shift`. |
## Functions
| Function | Description |
| ---------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| [bytesToHex](https://evolu.dev/docs/api-reference/common/Buffer/functions/bytesToHex) | Convert byte array to hex string. Uses built-in function, when available. |
| [bytesToUtf8](https://evolu.dev/docs/api-reference/common/Buffer/functions/bytesToUtf8) | Converts bytes to string using UTF8 encoding. |
| [concatBytes](https://evolu.dev/docs/api-reference/common/Buffer/functions/concatBytes) | Copies several Uint8Arrays into one. |
| [createBuffer](https://evolu.dev/docs/api-reference/common/Buffer/functions/createBuffer) | Creates a [Buffer](https://evolu.dev/docs/api-reference/common/Buffer/interfaces/Buffer) for efficient byte operations. |
| [hexToBytes](https://evolu.dev/docs/api-reference/common/Buffer/functions/hexToBytes) | Convert hex string to byte array. Uses built-in function, when available. |
| [utf8ToBytes](https://evolu.dev/docs/api-reference/common/Buffer/functions/utf8ToBytes) | Converts string to bytes using UTF8 encoding. |
API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / Cache
# Cache
## Interfaces
| Interface | Description |
| -------------------------------------------------------------- | --------------------------------------------------------------------- |
| [Cache](https://evolu.dev/docs/api-reference/common/Cache/interfaces/Cache) | Generic cache interface providing basic key-value storage operations. |
## Functions
| Function | Description |
| ------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
| [createLruCache](https://evolu.dev/docs/api-reference/common/Cache/functions/createLruCache) | Creates an LRU (least recently used) cache with a maximum capacity. |
API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / Callbacks
# Callbacks
## Interfaces
| Interface | Description |
| -------------------------------------------------------------------------- | ------------------------------------------------------------- |
| [Callbacks](https://evolu.dev/docs/api-reference/common/Callbacks/interfaces/Callbacks) | Request-response correlation for callbacks across boundaries. |
## Type Aliases
| Type Alias | Description |
| ------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------- |
| [CallbackId](https://evolu.dev/docs/api-reference/common/Callbacks/type-aliases/CallbackId) | Unique identifier for a callback in [Callbacks](https://evolu.dev/docs/api-reference/common/Callbacks/interfaces/Callbacks). |
## Functions
| Function | Description |
| ------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| [createCallbacks](https://evolu.dev/docs/api-reference/common/Callbacks/functions/createCallbacks) | Creates a [Callbacks](https://evolu.dev/docs/api-reference/common/Callbacks/interfaces/Callbacks) registry for managing callbacks. |
API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / Console
# Console
## Interfaces
| Interface | Description |
| ------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Console](https://evolu.dev/docs/api-reference/common/Console/interfaces/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 these environments and expected to remain compatible in future versions. Output formatting may vary (e.g., interactive UI in browsers vs. text in Node.js/React Native), but functionality is consistent across platforms. |
| [ConsoleConfig](https://evolu.dev/docs/api-reference/common/Console/interfaces/ConsoleConfig) | - |
| [ConsoleDep](https://evolu.dev/docs/api-reference/common/Console/interfaces/ConsoleDep) | Dependency interface for injecting a Console instance. |
| [ConsoleWithTimeConfig](https://evolu.dev/docs/api-reference/common/Console/interfaces/ConsoleWithTimeConfig) | - |
## Functions
| Function | Description |
| ----------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| [createConsole](https://evolu.dev/docs/api-reference/common/Console/functions/createConsole) | Creates a [Console](https://evolu.dev/docs/api-reference/common/Console/interfaces/Console) for logging with configurable output. |
| [createConsoleWithTime](https://evolu.dev/docs/api-reference/common/Console/functions/createConsoleWithTime) | Creates a console instance with timestamp prefixes. |
API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / Crypto
# Crypto
Cryptographic utilities
Type-safe cryptographic operations including random number generation, SLIP21
key derivation, XChaCha20-Poly1305 symmetric encryption, PADMÉ padding, and
timing-safe comparisons.
## Interfaces
| Interface | Description |
| ----------------------------------------------------------------------------------------------------------- | ----------------------- |
| [RandomBytes](https://evolu.dev/docs/api-reference/common/Crypto/interfaces/RandomBytes) | - |
| [RandomBytesDep](https://evolu.dev/docs/api-reference/common/Crypto/interfaces/RandomBytesDep) | - |
| [SymmetricCrypto](https://evolu.dev/docs/api-reference/common/Crypto/interfaces/SymmetricCrypto) | Symmetric cryptography. |
| [SymmetricCryptoDecryptError](https://evolu.dev/docs/api-reference/common/Crypto/interfaces/SymmetricCryptoDecryptError) | - |
| [SymmetricCryptoDep](https://evolu.dev/docs/api-reference/common/Crypto/interfaces/SymmetricCryptoDep) | - |
| [TimingSafeEqualDep](https://evolu.dev/docs/api-reference/common/Crypto/interfaces/TimingSafeEqualDep) | - |
## Type Aliases
| Type Alias | Description |
| ------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [EncryptionKey](https://evolu.dev/docs/api-reference/common/Crypto/type-aliases/EncryptionKey) | - |
| [Entropy16](https://evolu.dev/docs/api-reference/common/Crypto/type-aliases/Entropy16) | - |
| [Entropy32](https://evolu.dev/docs/api-reference/common/Crypto/type-aliases/Entropy32) | - |
| [Entropy64](https://evolu.dev/docs/api-reference/common/Crypto/type-aliases/Entropy64) | - |
| [TimingSafeEqual](https://evolu.dev/docs/api-reference/common/Crypto/type-aliases/TimingSafeEqual) | Performs a timing-safe comparison of two Uint8Arrays. Returns true if they are equal, false otherwise. Takes constant time regardless of where the arrays differ. |
## Variables
| Variable | Description |
| ------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------- |
| [EncryptionKey](https://evolu.dev/docs/api-reference/common/Crypto/variables/EncryptionKey) | The encryption key for [SymmetricCrypto](https://evolu.dev/docs/api-reference/common/Crypto/interfaces/SymmetricCrypto). |
| [Entropy16](https://evolu.dev/docs/api-reference/common/Crypto/variables/Entropy16) | - |
| [Entropy32](https://evolu.dev/docs/api-reference/common/Crypto/variables/Entropy32) | - |
| [Entropy64](https://evolu.dev/docs/api-reference/common/Crypto/variables/Entropy64) | - |
## Functions
| Function | Description |
| -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
| [createPadmePaddedLength](https://evolu.dev/docs/api-reference/common/Crypto/functions/createPadmePaddedLength) | Returns the PADMÉ padded length for a given input length. |
| [createPadmePadding](https://evolu.dev/docs/api-reference/common/Crypto/functions/createPadmePadding) | Creates a PADMÉ padding array of zeros for the given input length. |
| [createRandomBytes](https://evolu.dev/docs/api-reference/common/Crypto/functions/createRandomBytes) | - |
| [createSlip21](https://evolu.dev/docs/api-reference/common/Crypto/functions/createSlip21) | SLIP21. |
| [createSymmetricCrypto](https://evolu.dev/docs/api-reference/common/Crypto/functions/createSymmetricCrypto) | XChaCha20-Poly1305 encryption |
| [deriveSlip21Node](https://evolu.dev/docs/api-reference/common/Crypto/functions/deriveSlip21Node) | Derives a single node in the SLIP-21 hierarchical key derivation. |
API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / Eq
# Eq
## Type Aliases
| Type Alias | Description |
| ------------------------------------------------------- | ------------------------------------------------------ |
| [Eq](https://evolu.dev/docs/api-reference/common/Eq/type-aliases/Eq) | Compares two values of the same type `A` for equality. |
## Variables
| Variable | Description |
| -------------------------------------------------------------------------- | ----------------------------------------------------------- |
| [eqArrayNumber](https://evolu.dev/docs/api-reference/common/Eq/variables/eqArrayNumber) | Compares two array-like structures of numbers for equality. |
| [eqBigInt](https://evolu.dev/docs/api-reference/common/Eq/variables/eqBigInt) | - |
| [eqBoolean](https://evolu.dev/docs/api-reference/common/Eq/variables/eqBoolean) | - |
| [eqNull](https://evolu.dev/docs/api-reference/common/Eq/variables/eqNull) | - |
| [eqNumber](https://evolu.dev/docs/api-reference/common/Eq/variables/eqNumber) | - |
| [eqString](https://evolu.dev/docs/api-reference/common/Eq/variables/eqString) | - |
| [eqUndefined](https://evolu.dev/docs/api-reference/common/Eq/variables/eqUndefined) | - |
## Functions
| Function | Description |
| ---------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| [createEqArrayLike](https://evolu.dev/docs/api-reference/common/Eq/functions/createEqArrayLike) | Creates an equivalence function for array-like structures based on an equivalence for their elements. |
| [createEqObject](https://evolu.dev/docs/api-reference/common/Eq/functions/createEqObject) | Creates an equivalence function for objects based on an equivalence for their fields. |
| [eqFromOrder](https://evolu.dev/docs/api-reference/common/Eq/functions/eqFromOrder) | Derives an [Eq](https://evolu.dev/docs/api-reference/common/Eq/type-aliases/Eq) from an [Order](https://evolu.dev/docs/api-reference/common/Order/type-aliases/Order). |
| [eqJsonValue](https://evolu.dev/docs/api-reference/common/Eq/functions/eqJsonValue) | Deeply compares two [JsonValue](https://evolu.dev/docs/api-reference/common/Type/variables/JsonValue) values for equality. |
| [eqJsonValueInput](https://evolu.dev/docs/api-reference/common/Eq/functions/eqJsonValueInput) | Deeply compares two [JsonValueInput](https://evolu.dev/docs/api-reference/common/Type/type-aliases/JsonValueInput) values for equality. |
| [eqStrict](https://evolu.dev/docs/api-reference/common/Eq/functions/eqStrict) | - |
API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / Error
# Error
## Interfaces
| Interface | Description |
| -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| [TransferableError](https://evolu.dev/docs/api-reference/common/Error/interfaces/TransferableError) | A serializable representation of an error for safe transfer between execution contexts, such as Web Workers and the main thread. |
## Functions
| Function | Description |
| ------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| [createTransferableError](https://evolu.dev/docs/api-reference/common/Error/functions/createTransferableError) | Creates a [TransferableError](https://evolu.dev/docs/api-reference/common/Error/interfaces/TransferableError) from an unknown error. |
API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / Function
# Function
## Type Aliases
| Type Alias | Description |
| --------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| [LazyValue](https://evolu.dev/docs/api-reference/common/Function/type-aliases/LazyValue) | A function that delays computation and returns a value of type T. |
## Variables
| Variable | Description |
| ---------------------------------------------------------------------------------- | ----------- |
| [constFalse](https://evolu.dev/docs/api-reference/common/Function/variables/constFalse) | - |
| [constNull](https://evolu.dev/docs/api-reference/common/Function/variables/constNull) | - |
| [constTrue](https://evolu.dev/docs/api-reference/common/Function/variables/constTrue) | - |
| [constUndefined](https://evolu.dev/docs/api-reference/common/Function/variables/constUndefined) | - |
| [constVoid](https://evolu.dev/docs/api-reference/common/Function/variables/constVoid) | - |
## Functions
| Function | Description |
| ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------- |
| [exhaustiveCheck](https://evolu.dev/docs/api-reference/common/Function/functions/exhaustiveCheck) | Helper function to ensure exhaustive matching in a switch statement. Throws an error if an unhandled case is encountered. |
| [identity](https://evolu.dev/docs/api-reference/common/Function/functions/identity) | Returns the input value unchanged. |
| [readonly](https://evolu.dev/docs/api-reference/common/Function/functions/readonly) | Casts an array, set, record, or map to its readonly counterpart. |
API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / Identicon
# Identicon
## Type Aliases
| Type Alias | Description |
| -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Identicon](https://evolu.dev/docs/api-reference/common/Identicon/type-aliases/Identicon) | SVG string representing a visual identicon for an [Id](https://evolu.dev/docs/api-reference/common/Type/variables/Id), created with [createIdenticon](https://evolu.dev/docs/api-reference/common/Identicon/functions/createIdenticon). |
| [IdenticonStyle](https://evolu.dev/docs/api-reference/common/Identicon/type-aliases/IdenticonStyle) | [Identicon](https://evolu.dev/docs/api-reference/common/Identicon/type-aliases/Identicon) style. |
## Functions
| Function | Description |
| ------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| [createIdenticon](https://evolu.dev/docs/api-reference/common/Identicon/functions/createIdenticon) | Creates a deterministic identicon SVG from an [Id](https://evolu.dev/docs/api-reference/common/Type/variables/Id). |
API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / Instances
# Instances
## Interfaces
| Interface | Description |
| -------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| [Instances](https://evolu.dev/docs/api-reference/common/Instances/interfaces/Instances) | Manages disposable instances by key, ensuring exactly one instance per key. |
## Functions
| Function | Description |
| ------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| [createInstances](https://evolu.dev/docs/api-reference/common/Instances/functions/createInstances) | Creates an [Instances](https://evolu.dev/docs/api-reference/common/Instances/interfaces/Instances). |
API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / Number
# Number
## Functions
| Function | Description |
| ------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [clamp](https://evolu.dev/docs/api-reference/common/Number/functions/clamp) | Clamps a number within a given range. |
| [computeBalancedBuckets](https://evolu.dev/docs/api-reference/common/Number/functions/computeBalancedBuckets) | Divides items into buckets as evenly as possible, ensuring each bucket has at least the minimum number of items. Returns a success result if the minimum is met, or an error result with the required number of items if not. |
| [decrement](https://evolu.dev/docs/api-reference/common/Number/functions/decrement) | - |
| [increment](https://evolu.dev/docs/api-reference/common/Number/functions/increment) | - |
| [isBetween](https://evolu.dev/docs/api-reference/common/Number/functions/isBetween) | Creates a predicate that checks if a number is within a range, inclusive. |
| [max](https://evolu.dev/docs/api-reference/common/Number/functions/max) | Returns the maximum value, preserving branded type if applicable. |
| [min](https://evolu.dev/docs/api-reference/common/Number/functions/min) | Returns the minimum value, preserving branded type if applicable. |
API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / Object
# Object
## Type Aliases
| Type Alias | Description |
| ----------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [ReadonlyRecord](https://evolu.dev/docs/api-reference/common/Object/type-aliases/ReadonlyRecord) | A read-only `Record<K, V>` with `K extends keyof any` to preserve branded key types (e.g., in [mapObject](https://evolu.dev/docs/api-reference/common/Object/functions/mapObject)). |
## Functions
| Function | Description |
| ---------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [createRecord](https://evolu.dev/docs/api-reference/common/Object/functions/createRecord) | Creates a prototype-less object typed as `Record<K, V>`. |
| [excludeProp](https://evolu.dev/docs/api-reference/common/Object/functions/excludeProp) | Conditionally excludes a property from an object. |
| [getProperty](https://evolu.dev/docs/api-reference/common/Object/functions/getProperty) | Safely gets a property from a record, returning `undefined` if the key doesn't exist. |
| [isPlainObject](https://evolu.dev/docs/api-reference/common/Object/functions/isPlainObject) | Checks if a value is a plain object (e.g., created with `{}` or `Object`). |
| [mapObject](https://evolu.dev/docs/api-reference/common/Object/functions/mapObject) | Maps a `ReadonlyRecord<K, V>` to a new `ReadonlyRecord<K, U>`, preserving branded key types (e.g., `type Id = 'id' & string`) lost by `Object.entries`. Uses `K extends string` for precision. |
| [objectToEntries](https://evolu.dev/docs/api-reference/common/Object/functions/objectToEntries) | Like `Object.entries` but preserves branded keys. |
API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / Order
# Order
## Type Aliases
| Type Alias | Description |
| ---------------------------------------------------------------------- | ----------------------------------------------------------- |
| [Order](https://evolu.dev/docs/api-reference/common/Order/type-aliases/Order) | Compares two values of type `A` and returns their ordering. |
| [Ordering](https://evolu.dev/docs/api-reference/common/Order/type-aliases/Ordering) | A type representing the result of an ordering operation. |
## Variables
| Variable | Description |
| --------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| [orderBigInt](https://evolu.dev/docs/api-reference/common/Order/variables/orderBigInt) | An order for bigints in ascending order. |
| [orderNumber](https://evolu.dev/docs/api-reference/common/Order/variables/orderNumber) | An order for numbers in ascending order. |
| [orderString](https://evolu.dev/docs/api-reference/common/Order/variables/orderString) | An order for `string` values in ascending order. |
| [orderUint8Array](https://evolu.dev/docs/api-reference/common/Order/variables/orderUint8Array) | An [Order](https://evolu.dev/docs/api-reference/common/Order/type-aliases/Order) for Uint8Array. |
## Functions
| Function | Description |
| --------------------------------------------------------------------------- | ------------------------------------------------------------ |
| [createOrder](https://evolu.dev/docs/api-reference/common/Order/functions/createOrder) | Creates an ordering function from a "less than" comparator. |
| [reverseOrder](https://evolu.dev/docs/api-reference/common/Order/functions/reverseOrder) | Returns an order that reverses the order of the given order. |
API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / Platform
# Platform
## Variables
| Variable | Description |
| -------------------------------------------------------------------------------- | ----------------------------------------------------------- |
| [hasNodeBuffer](https://evolu.dev/docs/api-reference/common/Platform/variables/hasNodeBuffer) | Detects if Node.js Buffer is available and should be used. |
| [isReactNative](https://evolu.dev/docs/api-reference/common/Platform/variables/isReactNative) | Detects if the code is running in React Native environment. |
API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / Random
# Random
## Interfaces
| Interface | Description |
| ----------------------------------------------------------------------------- | -------------------------------------------------------------------- |
| [Random](https://evolu.dev/docs/api-reference/common/Random/interfaces/Random) | A simple wrapper around Math.random(). |
| [RandomDep](https://evolu.dev/docs/api-reference/common/Random/interfaces/RandomDep) | - |
| [RandomLibDep](https://evolu.dev/docs/api-reference/common/Random/interfaces/RandomLibDep) | A random number generator using the NPM `random` package dependency. |
## Functions
| Function | Description |
| -------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [createRandom](https://evolu.dev/docs/api-reference/common/Random/functions/createRandom) | Creates a [Random](https://evolu.dev/docs/api-reference/common/Random/interfaces/Random) using Math.random(). |
| [createRandomLib](https://evolu.dev/docs/api-reference/common/Random/functions/createRandomLib) | Creates a `RandomLib` using the NPM `random` package. |
| [createRandomLibWithSeed](https://evolu.dev/docs/api-reference/common/Random/functions/createRandomLibWithSeed) | Creates [RandomLibDep](https://evolu.dev/docs/api-reference/common/Random/interfaces/RandomLibDep) using the NPM `random` package with a seed which is useful for tests. |
| [createRandomWithSeed](https://evolu.dev/docs/api-reference/common/Random/functions/createRandomWithSeed) | Creates [Random](https://evolu.dev/docs/api-reference/common/Random/interfaces/Random) using [RandomLibDep](https://evolu.dev/docs/api-reference/common/Random/interfaces/RandomLibDep) with a seed which is useful for tests. |
API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / Redacted
# Redacted
## Interfaces
| Interface | Description |
| ----------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| [Redacted](https://evolu.dev/docs/api-reference/common/Redacted/interfaces/Redacted) | A wrapper type that prevents sensitive values from being accidentally exposed through logging, serialization, or inspection. |
## Functions
| Function | Description |
| -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| [createEqRedacted](https://evolu.dev/docs/api-reference/common/Redacted/functions/createEqRedacted) | Creates an [Eq](https://evolu.dev/docs/api-reference/common/Eq/type-aliases/Eq) for [Redacted](https://evolu.dev/docs/api-reference/common/Redacted/interfaces/Redacted) values based on an equality function for the underlying type. |
| [createRedacted](https://evolu.dev/docs/api-reference/common/Redacted/functions/createRedacted) | Creates a [Redacted](https://evolu.dev/docs/api-reference/common/Redacted/interfaces/Redacted) wrapper for a sensitive value. |
| [isRedacted](https://evolu.dev/docs/api-reference/common/Redacted/functions/isRedacted) | Checks if a value is a [Redacted](https://evolu.dev/docs/api-reference/common/Redacted/interfaces/Redacted) wrapper. |
| [revealRedacted](https://evolu.dev/docs/api-reference/common/Redacted/functions/revealRedacted) | Reveals the original value from a [Redacted](https://evolu.dev/docs/api-reference/common/Redacted/interfaces/Redacted) wrapper. |
API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / Ref
# Ref
## Interfaces
| Interface | Description |
| -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Ref](https://evolu.dev/docs/api-reference/common/Ref/interfaces/Ref) | `Ref` provides a simple API to hold and update a value, similar to a "ref" in functional programming or React. It exposes methods to get, set, and modify the current state. |
## Functions
| Function | Description |
| ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| [createRef](https://evolu.dev/docs/api-reference/common/Ref/functions/createRef) | Creates a [Ref](https://evolu.dev/docs/api-reference/common/Ref/interfaces/Ref) with the given initial state. |
API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / Relation
# Relation
## Interfaces
| Interface | Description |
| ----------------------------------------------------------------------- | ----------------------------------------- |
| [Relation](https://evolu.dev/docs/api-reference/common/Relation/interfaces/Relation) | Bidirectional relation between two types. |
## Functions
| Function | Description |
| ---------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| [createRelation](https://evolu.dev/docs/api-reference/common/Relation/functions/createRelation) | Creates a [Relation](https://evolu.dev/docs/api-reference/common/Relation/interfaces/Relation). |
API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / Resources
# Resources
## Interfaces
| Interface | Description |
| -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| [ConsumerNotFoundError](https://evolu.dev/docs/api-reference/common/Resources/interfaces/ConsumerNotFoundError) | Error when trying to remove a consumer that wasn't added to a resource. |
| [ResourceNotFoundError](https://evolu.dev/docs/api-reference/common/Resources/interfaces/ResourceNotFoundError) | Error when trying to remove a consumer from a resource that doesn't exist. |
| [Resources](https://evolu.dev/docs/api-reference/common/Resources/interfaces/Resources) | A generic resource manager that handles reference counting and delayed disposal of shared resources. Useful for managing expensive resources like WebSocket connections that need to be shared among multiple consumers. |
| [ResourcesConfig](https://evolu.dev/docs/api-reference/common/Resources/interfaces/ResourcesConfig) | - |
## Functions
| Function | Description |
| ------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| [createResources](https://evolu.dev/docs/api-reference/common/Resources/functions/createResources) | Creates [Resources](https://evolu.dev/docs/api-reference/common/Resources/interfaces/Resources). |
API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / Result
# Result
## Utilities
| Type Alias | Description |
| ----------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| [InferErr](https://evolu.dev/docs/api-reference/common/Result/type-aliases/InferErr) | Extracts the error type from a [Result](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result). |
| [InferOk](https://evolu.dev/docs/api-reference/common/Result/type-aliases/InferOk) | Extracts the value type from a [Result](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result). |
## Other
| Name | Description |
| ------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Err](https://evolu.dev/docs/api-reference/common/Result/interfaces/Err) | An error [Result](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result). |
| [Ok](https://evolu.dev/docs/api-reference/common/Result/interfaces/Ok) | A successful [Result](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result). |
| [Result](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result) | 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. |
| [err](https://evolu.dev/docs/api-reference/common/Result/functions/err) | Creates an [Err](https://evolu.dev/docs/api-reference/common/Result/interfaces/Err) result. |
| [getOrNull](https://evolu.dev/docs/api-reference/common/Result/functions/getOrNull) | Extracts the value from a [Result](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result) if it is an `Ok`, or returns `null` if it is an `Err`. |
| [getOrThrow](https://evolu.dev/docs/api-reference/common/Result/functions/getOrThrow) | Extracts the value from a [Result](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result) if it is an `Ok`, or throws an error if it is an `Err`. |
| [ok](https://evolu.dev/docs/api-reference/common/Result/functions/ok) | Creates an [Ok](https://evolu.dev/docs/api-reference/common/Result/interfaces/Ok) result. |
| [tryAsync](https://evolu.dev/docs/api-reference/common/Result/functions/tryAsync) | Wraps async functions or any operation returning a promise, returning a [Result](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result). |
| [trySync](https://evolu.dev/docs/api-reference/common/Result/functions/trySync) | Wraps synchronous functions that may throw exceptions, returning a [Result](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result). |
API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / Sqlite
# Sqlite
## Interfaces
| Interface | Description |
| ----------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| [CreateSqliteDriverDep](https://evolu.dev/docs/api-reference/common/Sqlite/interfaces/CreateSqliteDriverDep) | - |
| [PreparedStatements](https://evolu.dev/docs/api-reference/common/Sqlite/interfaces/PreparedStatements) | - |
| [RawSql](https://evolu.dev/docs/api-reference/common/Sqlite/interfaces/RawSql) | - |
| [SqlIdentifier](https://evolu.dev/docs/api-reference/common/Sqlite/interfaces/SqlIdentifier) | - |
| [Sqlite](https://evolu.dev/docs/api-reference/common/Sqlite/interfaces/Sqlite) | Cross-platform SQLite abstraction. |
| [SqliteDep](https://evolu.dev/docs/api-reference/common/Sqlite/interfaces/SqliteDep) | - |
| [SqliteDriver](https://evolu.dev/docs/api-reference/common/Sqlite/interfaces/SqliteDriver) | SQLite driver interface. This is the minimal interface that platform-specific drivers must implement. |
| [SqliteDriverOptions](https://evolu.dev/docs/api-reference/common/Sqlite/interfaces/SqliteDriverOptions) | - |
| [SqliteError](https://evolu.dev/docs/api-reference/common/Sqlite/interfaces/SqliteError) | Represents an error that occurred during a SQLite operation. |
| [SqliteExecResult](https://evolu.dev/docs/api-reference/common/Sqlite/interfaces/SqliteExecResult) | Result of executing a SQLite query. |
| [SqliteQuery](https://evolu.dev/docs/api-reference/common/Sqlite/interfaces/SqliteQuery) | - |
| [SqliteQueryOptions](https://evolu.dev/docs/api-reference/common/Sqlite/interfaces/SqliteQueryOptions) | - |
| [SqliteQueryPlanRow](https://evolu.dev/docs/api-reference/common/Sqlite/interfaces/SqliteQueryPlanRow) | - |
## Type Aliases
| Type Alias | Description |
| ------------------------------------------------------------------------------------------- | ------------------------------------------- |
| [CreateSqliteDriver](https://evolu.dev/docs/api-reference/common/Sqlite/type-aliases/CreateSqliteDriver) | - |
| [SafeSql](https://evolu.dev/docs/api-reference/common/Sqlite/type-aliases/SafeSql) | A type representing a sanitized SQL string. |
| [SqliteBoolean](https://evolu.dev/docs/api-reference/common/Sqlite/type-aliases/SqliteBoolean) | - |
| [SqliteRow](https://evolu.dev/docs/api-reference/common/Sqlite/type-aliases/SqliteRow) | - |
| [SqliteValue](https://evolu.dev/docs/api-reference/common/Sqlite/type-aliases/SqliteValue) | - |
| [SqlTemplateParam](https://evolu.dev/docs/api-reference/common/Sqlite/type-aliases/SqlTemplateParam) | - |
## Variables
| Variable | Description |
| ------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------- |
| [eqSqliteValue](https://evolu.dev/docs/api-reference/common/Sqlite/variables/eqSqliteValue) | - |
| [isSqlMutation](https://evolu.dev/docs/api-reference/common/Sqlite/variables/isSqlMutation) | Checks if a SQL string contains mutation keywords (insert, update, delete, etc.). Results are cached for performance. |
| [SqliteBoolean](https://evolu.dev/docs/api-reference/common/Sqlite/variables/SqliteBoolean) | SQLite represents boolean values using `0` (false) and `1` (true) instead of a dedicated boolean type. |
| [sqliteFalse](https://evolu.dev/docs/api-reference/common/Sqlite/variables/sqliteFalse) | Represents the [SqliteBoolean](https://evolu.dev/docs/api-reference/common/Sqlite/variables/SqliteBoolean) value for `false`. |
| [sqliteTrue](https://evolu.dev/docs/api-reference/common/Sqlite/variables/sqliteTrue) | Represents the [SqliteBoolean](https://evolu.dev/docs/api-reference/common/Sqlite/variables/SqliteBoolean) value for `true`. |
| [SqliteValue](https://evolu.dev/docs/api-reference/common/Sqlite/variables/SqliteValue) | A value that can be stored in Sqlite. |
## Functions
| Function | Description |
| -------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [booleanToSqliteBoolean](https://evolu.dev/docs/api-reference/common/Sqlite/functions/booleanToSqliteBoolean) | Converts a JavaScript boolean to a [SqliteBoolean](https://evolu.dev/docs/api-reference/common/Sqlite/variables/SqliteBoolean). |
| [createPreparedStatementsCache](https://evolu.dev/docs/api-reference/common/Sqlite/functions/createPreparedStatementsCache) | - |
| [createSqlite](https://evolu.dev/docs/api-reference/common/Sqlite/functions/createSqlite) | Creates a fully featured [Sqlite](https://evolu.dev/docs/api-reference/common/Sqlite/interfaces/Sqlite) instance from a [SqliteDriver](https://evolu.dev/docs/api-reference/common/Sqlite/interfaces/SqliteDriver) implementation. |
| [explainSqliteQueryPlan](https://evolu.dev/docs/api-reference/common/Sqlite/functions/explainSqliteQueryPlan) | - |
| [sql](https://evolu.dev/docs/api-reference/common/Sqlite/functions/sql) | Creates a safe SQL query using a tagged template literal. |
| [sqliteBooleanToBoolean](https://evolu.dev/docs/api-reference/common/Sqlite/functions/sqliteBooleanToBoolean) | Converts a [SqliteBoolean](https://evolu.dev/docs/api-reference/common/Sqlite/variables/SqliteBoolean) to a JavaScript boolean. |
API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / Store
# Store
## Interfaces
| Interface | Description |
| -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| [Store](https://evolu.dev/docs/api-reference/common/Store/interfaces/Store) | A store for managing state with change notifications. Extends [Ref](https://evolu.dev/docs/api-reference/common/Ref/interfaces/Ref) with subscriptions. Provides methods to get, set, and modify state, and to notify listeners when the state changes. |
## Type Aliases
| Type Alias | Description |
| -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| [StoreListener](https://evolu.dev/docs/api-reference/common/Store/type-aliases/StoreListener) | A callback invoked whenever the store's state updates. |
| [StoreSubscribe](https://evolu.dev/docs/api-reference/common/Store/type-aliases/StoreSubscribe) | Registers a listener for state changes, returning an unsubscribe function. |
| [StoreUnsubscribe](https://evolu.dev/docs/api-reference/common/Store/type-aliases/StoreUnsubscribe) | A function to remove a previously added listener. |
## Functions
| Function | Description |
| ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| [createStore](https://evolu.dev/docs/api-reference/common/Store/functions/createStore) | Creates a store with the given initial state. The store encapsulates its state, which can be read with `get` and updated with `set` or `modify`. All changes are broadcast to subscribers. |
API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / String
# String
## Functions
| Function | Description |
| ---------------------------------------------------------------------------------------------------------- | ----------- |
| [safelyStringifyUnknownValue](https://evolu.dev/docs/api-reference/common/String/functions/safelyStringifyUnknownValue) | - |
API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / Task
# Task
## Interfaces
| Interface | Description |
| --------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [AbortError](https://evolu.dev/docs/api-reference/common/Task/interfaces/AbortError) | Error returned when a [Task](https://evolu.dev/docs/api-reference/common/Task/interfaces/Task) is cancelled via AbortSignal. |
| [Mutex](https://evolu.dev/docs/api-reference/common/Task/interfaces/Mutex) | A mutex (mutual exclusion) that ensures only one Task runs at a time. |
| [RetryError](https://evolu.dev/docs/api-reference/common/Task/interfaces/RetryError) | Error returned when [retry](https://evolu.dev/docs/api-reference/common/Task/functions/retry) exhausts all retry attempts. |
| [RetryOptions](https://evolu.dev/docs/api-reference/common/Task/interfaces/RetryOptions) | Options for configuring [retry](https://evolu.dev/docs/api-reference/common/Task/functions/retry) behavior. |
| [Semaphore](https://evolu.dev/docs/api-reference/common/Task/interfaces/Semaphore) | A semaphore that limits the number of concurrent async Tasks. |
| [Task](https://evolu.dev/docs/api-reference/common/Task/interfaces/Task) | `Task` is a function that creates and returns an optionally cancellable Promise using [Result](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result). |
| [TaskContext](https://evolu.dev/docs/api-reference/common/Task/interfaces/TaskContext) | Context passed to [Task](https://evolu.dev/docs/api-reference/common/Task/interfaces/Task)s for cancellation. |
| [TimeoutError](https://evolu.dev/docs/api-reference/common/Task/interfaces/TimeoutError) | Error returned when [timeout](https://evolu.dev/docs/api-reference/common/Task/functions/timeout) exceeds the specified duration. |
## Type Aliases
| Type Alias | Description |
| ------------------------------------------------------------------------- | ------------------------------------------------------------------ |
| [MaybeAsync](https://evolu.dev/docs/api-reference/common/Task/type-aliases/MaybeAsync) | Represents a value that can be either synchronous or asynchronous. |
## Functions
| Function | Description |
| -------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [createMutex](https://evolu.dev/docs/api-reference/common/Task/functions/createMutex) | Creates a new mutex for ensuring mutual exclusion. |
| [createSemaphore](https://evolu.dev/docs/api-reference/common/Task/functions/createSemaphore) | Creates a semaphore that limits concurrent async Tasks to the specified count. |
| [isAsync](https://evolu.dev/docs/api-reference/common/Task/functions/isAsync) | Type guard to check if a [MaybeAsync](https://evolu.dev/docs/api-reference/common/Task/type-aliases/MaybeAsync) value is async (a promise). |
| [requestIdleTask](https://evolu.dev/docs/api-reference/common/Task/functions/requestIdleTask) | Schedule a task to run after all interactions (animations, gestures, navigation) have completed. |
| [retry](https://evolu.dev/docs/api-reference/common/Task/functions/retry) | Adds retry logic with exponential backoff and jitter to a [Task](https://evolu.dev/docs/api-reference/common/Task/interfaces/Task). |
| [timeout](https://evolu.dev/docs/api-reference/common/Task/functions/timeout) | Adds timeout behavior to a [Task](https://evolu.dev/docs/api-reference/common/Task/interfaces/Task). |
| [toTask](https://evolu.dev/docs/api-reference/common/Task/functions/toTask) | Converts async function returning [Result](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result) to a [Task](https://evolu.dev/docs/api-reference/common/Task/interfaces/Task). |
| [wait](https://evolu.dev/docs/api-reference/common/Task/functions/wait) | Creates a [Task](https://evolu.dev/docs/api-reference/common/Task/interfaces/Task) that waits for the specified duration. |
API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / Time
# Time
## Interfaces
| Interface | Description |
| ----------------------------------------------------------------- | -------------------------------------------------------------------- |
| [Time](https://evolu.dev/docs/api-reference/common/Time/interfaces/Time) | Retrieves the current time in milliseconds, similar to `Date.now()`. |
| [TimeDep](https://evolu.dev/docs/api-reference/common/Time/interfaces/TimeDep) | - |
## Type Aliases
| Type Alias | Description |
| --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [D](https://evolu.dev/docs/api-reference/common/Time/type-aliases/D) | Single digit 0-9. Used internally for [DurationString](https://evolu.dev/docs/api-reference/common/Time/type-aliases/DurationString) validation. |
| [Days](https://evolu.dev/docs/api-reference/common/Time/type-aliases/Days) | Days 1-99. Used internally for [DurationString](https://evolu.dev/docs/api-reference/common/Time/type-aliases/DurationString) validation. |
| [Duration](https://evolu.dev/docs/api-reference/common/Time/type-aliases/Duration) | Duration can be either a [DurationString](https://evolu.dev/docs/api-reference/common/Time/type-aliases/DurationString) or milliseconds as [NonNegativeInt](https://evolu.dev/docs/api-reference/common/Type/variables/NonNegativeInt). |
| [DurationString](https://evolu.dev/docs/api-reference/common/Time/type-aliases/DurationString) | Template literal type for compile-time validated duration strings. |
| [Hours](https://evolu.dev/docs/api-reference/common/Time/type-aliases/Hours) | Hours 1-23. Used internally for [DurationString](https://evolu.dev/docs/api-reference/common/Time/type-aliases/DurationString) validation. |
| [MmSs](https://evolu.dev/docs/api-reference/common/Time/type-aliases/MmSs) | Minutes and seconds 1-59. Used internally for [DurationString](https://evolu.dev/docs/api-reference/common/Time/type-aliases/DurationString) validation. Uses single digits for 1-9, full numbers for 10-59. |
## Functions
| Function | Description |
| -------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| [createTestTime](https://evolu.dev/docs/api-reference/common/Time/functions/createTestTime) | Creates a [Time](https://evolu.dev/docs/api-reference/common/Time/interfaces/Time) that returns a monotonically increasing number based on a queueMicrotask. |
| [createTime](https://evolu.dev/docs/api-reference/common/Time/functions/createTime) | Creates a [Time](https://evolu.dev/docs/api-reference/common/Time/interfaces/Time) using Date.now(). |
| [durationToNonNegativeInt](https://evolu.dev/docs/api-reference/common/Time/functions/durationToNonNegativeInt) | Converts a duration to milliseconds. |
API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / Type
# Type
## Base Factories
| Function | Description |
| ------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| [array](https://evolu.dev/docs/api-reference/common/Type/functions/array) | Array of a specific [Type](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type). |
| [base](https://evolu.dev/docs/api-reference/common/Type/functions/base) | Base [Type](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type). |
| [brand](https://evolu.dev/docs/api-reference/common/Type/functions/brand) | Branded [Type](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type). |
| [instanceOf](https://evolu.dev/docs/api-reference/common/Type/functions/instanceOf) | `instanceof` [Type](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type). |
| [literal](https://evolu.dev/docs/api-reference/common/Type/functions/literal) | Literal [Type](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type). |
| [nullishOr](https://evolu.dev/docs/api-reference/common/Type/functions/nullishOr) | `union(undefined, null, T)` [Type](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type). |
| [nullOr](https://evolu.dev/docs/api-reference/common/Type/functions/nullOr) | `union(null, T)` [Type](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type). |
| [object](https://evolu.dev/docs/api-reference/common/Type/functions/object) | Object [Type](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type). |
| [record](https://evolu.dev/docs/api-reference/common/Type/functions/record) | Record of a key [Type](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type) and value [Type](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type). |
| [recursive](https://evolu.dev/docs/api-reference/common/Type/functions/recursive) | Recursive [Type](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type). |
| [set](https://evolu.dev/docs/api-reference/common/Type/functions/set) | Set of a specific [Type](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type). |
| [tuple](https://evolu.dev/docs/api-reference/common/Type/functions/tuple) | Tuple [Type](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type). |
| [undefinedOr](https://evolu.dev/docs/api-reference/common/Type/functions/undefinedOr) | `union(undefined, T)` [Type](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type). |
| [union](https://evolu.dev/docs/api-reference/common/Type/functions/union) | Union [Type](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type). |
## Base Types
| Variable | Description |
| ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [BigInt](https://evolu.dev/docs/api-reference/common/Type/variables/BigInt) | - |
| [Boolean](https://evolu.dev/docs/api-reference/common/Type/variables/Boolean) | - |
| [Date](https://evolu.dev/docs/api-reference/common/Type/variables/Date) | JavaScript Date. |
| [Function](https://evolu.dev/docs/api-reference/common/Type/variables/Function) | - |
| [JsonValue](https://evolu.dev/docs/api-reference/common/Type/variables/JsonValue) | JSON-compatible value: string, [FiniteNumber](https://evolu.dev/docs/api-reference/common/Type/variables/FiniteNumber), boolean, null, [JsonArray](https://evolu.dev/docs/api-reference/common/Type/variables/JsonArray), or [JsonObject](https://evolu.dev/docs/api-reference/common/Type/variables/JsonObject). |
| [Null](https://evolu.dev/docs/api-reference/common/Type/variables/Null) | - |
| [Number](https://evolu.dev/docs/api-reference/common/Type/variables/Number) | - |
| [String](https://evolu.dev/docs/api-reference/common/Type/variables/String) | - |
| [Uint8Array](https://evolu.dev/docs/api-reference/common/Type/variables/Uint8Array) | - |
| [Undefined](https://evolu.dev/docs/api-reference/common/Type/variables/Undefined) | - |
| [Unknown](https://evolu.dev/docs/api-reference/common/Type/variables/Unknown) | - |
## String
| Name | Description |
| ---------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Base64Url](https://evolu.dev/docs/api-reference/common/Type/variables/Base64Url) | Base64Url without padding. |
| [CurrencyCode](https://evolu.dev/docs/api-reference/common/Type/variables/CurrencyCode) | A three-letter ISO 4217 currency code (e.g., USD, EUR). |
| [DateIso](https://evolu.dev/docs/api-reference/common/Type/variables/DateIso) | ISO 8601 date-time string. |
| [Id](https://evolu.dev/docs/api-reference/common/Type/variables/Id) | Evolu Id: 16 bytes encoded as a 22‑character Base64Url string. |
| [Int64String](https://evolu.dev/docs/api-reference/common/Type/variables/Int64String) | Stringified [Int64](https://evolu.dev/docs/api-reference/common/Type/variables/Int64). |
| [Json](https://evolu.dev/docs/api-reference/common/Type/variables/Json) | JSON-string [Type](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type). |
| [length](https://evolu.dev/docs/api-reference/common/Type/variables/length) | Exact length. |
| [maxLength](https://evolu.dev/docs/api-reference/common/Type/variables/maxLength) | Maximum length. |
| [minLength](https://evolu.dev/docs/api-reference/common/Type/variables/minLength) | Minimum length. |
| [Mnemonic](https://evolu.dev/docs/api-reference/common/Type/variables/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. |
| [NonEmptyString](https://evolu.dev/docs/api-reference/common/Type/variables/NonEmptyString) | - |
| [NonEmptyString100](https://evolu.dev/docs/api-reference/common/Type/variables/NonEmptyString100) | - |
| [NonEmptyString1000](https://evolu.dev/docs/api-reference/common/Type/variables/NonEmptyString1000) | - |
| [NonEmptyTrimmedString](https://evolu.dev/docs/api-reference/common/Type/variables/NonEmptyTrimmedString) | - |
| [NonEmptyTrimmedString100](https://evolu.dev/docs/api-reference/common/Type/variables/NonEmptyTrimmedString100) | - |
| [NonEmptyTrimmedString1000](https://evolu.dev/docs/api-reference/common/Type/variables/NonEmptyTrimmedString1000) | - |
| [regex](https://evolu.dev/docs/api-reference/common/Type/variables/regex) | String matching a regular expression. |
| [SimpleName](https://evolu.dev/docs/api-reference/common/Type/variables/SimpleName) | Simple alphanumeric string for naming in file systems, URLs, and identifiers. |
| [SimplePassword](https://evolu.dev/docs/api-reference/common/Type/variables/SimplePassword) | Trimmed string between 8 and 64 characters, branded as `SimplePassword`. |
| [String](https://evolu.dev/docs/api-reference/common/Type/variables/String) | - |
| [String100](https://evolu.dev/docs/api-reference/common/Type/variables/String100) | - |
| [String1000](https://evolu.dev/docs/api-reference/common/Type/variables/String1000) | - |
| [trimmed](https://evolu.dev/docs/api-reference/common/Type/variables/trimmed) | Trimmed string. |
| [TrimmedString](https://evolu.dev/docs/api-reference/common/Type/variables/TrimmedString) | Trimmed string |
| [TrimmedString100](https://evolu.dev/docs/api-reference/common/Type/variables/TrimmedString100) | - |
| [TrimmedString1000](https://evolu.dev/docs/api-reference/common/Type/variables/TrimmedString1000) | - |
| [UrlSafeString](https://evolu.dev/docs/api-reference/common/Type/variables/UrlSafeString) | URL-safe string. |
| [createIdFromString](https://evolu.dev/docs/api-reference/common/Type/functions/createIdFromString) | Creates an [Id](https://evolu.dev/docs/api-reference/common/Type/variables/Id) from a string using SHA-256. |
| [id](https://evolu.dev/docs/api-reference/common/Type/functions/id) | Creates a branded [Id](https://evolu.dev/docs/api-reference/common/Type/variables/Id) Type for a table's primary key. |
## Number
| Variable | Description |
| ------------------------------------------------------------------------------------------ | ---------------------------------------------------- |
| [between](https://evolu.dev/docs/api-reference/common/Type/variables/between) | Number within a range, inclusive. |
| [finite](https://evolu.dev/docs/api-reference/common/Type/variables/finite) | Finite number. |
| [FiniteNumber](https://evolu.dev/docs/api-reference/common/Type/variables/FiniteNumber) | Finite number. |
| [greaterThan](https://evolu.dev/docs/api-reference/common/Type/variables/greaterThan) | Number greater than a specified value. |
| [greaterThanOrEqualTo](https://evolu.dev/docs/api-reference/common/Type/variables/greaterThanOrEqualTo) | Number ≥ a specified value. |
| [int](https://evolu.dev/docs/api-reference/common/Type/variables/int) | Integer within the safe range of JavaScript numbers. |
| [Int](https://evolu.dev/docs/api-reference/common/Type/variables/Int-1) | Integer within the safe range of JavaScript numbers. |
| [Int64](https://evolu.dev/docs/api-reference/common/Type/variables/Int64) | 64-bit signed integer. |
| [lessThan](https://evolu.dev/docs/api-reference/common/Type/variables/lessThan) | Number less than a specified value. |
| [lessThanOrEqualTo](https://evolu.dev/docs/api-reference/common/Type/variables/lessThanOrEqualTo) | Number ≤ a specified value. |
| [multipleOf](https://evolu.dev/docs/api-reference/common/Type/variables/multipleOf) | Number that is a multiple of a divisor. |
| [negative](https://evolu.dev/docs/api-reference/common/Type/variables/negative) | Negative number (< 0). |
| [NegativeInt](https://evolu.dev/docs/api-reference/common/Type/variables/NegativeInt) | Negative integer (< 0). |
| [NegativeNumber](https://evolu.dev/docs/api-reference/common/Type/variables/NegativeNumber) | Negative number (< 0). |
| [nonNaN](https://evolu.dev/docs/api-reference/common/Type/variables/nonNaN) | Number that is not NaN. |
| [NonNaNNumber](https://evolu.dev/docs/api-reference/common/Type/variables/NonNaNNumber) | - |
| [nonNegative](https://evolu.dev/docs/api-reference/common/Type/variables/nonNegative) | Non-negative number (≥ 0). |
| [NonNegativeInt](https://evolu.dev/docs/api-reference/common/Type/variables/NonNegativeInt) | Non-negative integer (≥ 0). |
| [NonNegativeNumber](https://evolu.dev/docs/api-reference/common/Type/variables/NonNegativeNumber) | Non-negative number (≥ 0). |
| [nonPositive](https://evolu.dev/docs/api-reference/common/Type/variables/nonPositive) | Non-positive number (≤ 0). |
| [NonPositiveInt](https://evolu.dev/docs/api-reference/common/Type/variables/NonPositiveInt) | Non-positive integer (≤ 0). |
| [NonPositiveNumber](https://evolu.dev/docs/api-reference/common/Type/variables/NonPositiveNumber) | Non-positive number (≤ 0). |
| [positive](https://evolu.dev/docs/api-reference/common/Type/variables/positive) | Positive number (> 0). |
| [PositiveInt](https://evolu.dev/docs/api-reference/common/Type/variables/PositiveInt) | Positive integer (> 0). |
| [PositiveNumber](https://evolu.dev/docs/api-reference/common/Type/variables/PositiveNumber) | Positive number (> 0). |
## Array
| Name | Description |
| -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| [JsonArray](https://evolu.dev/docs/api-reference/common/Type/variables/JsonArray) | JSON-compatible array of [JsonValue](https://evolu.dev/docs/api-reference/common/Type/variables/JsonValue) elements. |
| [length](https://evolu.dev/docs/api-reference/common/Type/variables/length) | Exact length. |
| [maxLength](https://evolu.dev/docs/api-reference/common/Type/variables/maxLength) | Maximum length. |
| [minLength](https://evolu.dev/docs/api-reference/common/Type/variables/minLength) | Minimum length. |
| [array](https://evolu.dev/docs/api-reference/common/Type/functions/array) | Array of a specific [Type](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type). |
## Object
| Name | Description |
| -------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [JsonObject](https://evolu.dev/docs/api-reference/common/Type/variables/JsonObject) | JSON-compatible object with string keys and [JsonValue](https://evolu.dev/docs/api-reference/common/Type/variables/JsonValue) values. |
| [nullableToOptional](https://evolu.dev/docs/api-reference/common/Type/functions/nullableToOptional) | Converts each “nullable” property (a union that includes [Null](https://evolu.dev/docs/api-reference/common/Type/variables/Null)) into an [optional](https://evolu.dev/docs/api-reference/common/Type/functions/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](https://evolu.dev/docs/api-reference/common/Type/functions/object) | Object [Type](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type). |
| [omit](https://evolu.dev/docs/api-reference/common/Type/functions/omit) | Create a new `object` [Type](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type) by omitting some keys. |
| [partial](https://evolu.dev/docs/api-reference/common/Type/functions/partial) | Creates a partial object type where all properties are optional. |
| [record](https://evolu.dev/docs/api-reference/common/Type/functions/record) | Record of a key [Type](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type) and value [Type](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type). |
## Utilities
| Name | Description |
| ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [BrandFactory](https://evolu.dev/docs/api-reference/common/Type/type-aliases/BrandFactory) | Helper type for Type Factory that creates a branded Type. |
| [InferError](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferError) | Extracts the specific error type from a [Type](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type). |
| [InferErrors](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferErrors) | Extracts all error types from a [Type](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type). |
| [InferInput](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferInput) | Extracts the input type from a [Type](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type). |
| [InferName](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferName) | Extracts the name from a [Type](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type). |
| [InferParent](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferParent) | Extracts the parent type from a [Type](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type). |
| [InferParentError](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferParentError) | Extracts the parent error type from a [Type](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type). |
| [InferType](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferType) | Extracts the type from a [Type](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type). |
| [MergeObjectTypeErrors](https://evolu.dev/docs/api-reference/common/Type/type-aliases/MergeObjectTypeErrors) | Merge Error and ParentError into one ObjectError so tooltips and error messages are easier to read. |
| [TypeErrors](https://evolu.dev/docs/api-reference/common/Type/type-aliases/TypeErrors) | Union of all `TypeError`s 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](https://evolu.dev/docs/api-reference/common/Type/type-aliases/TypeName) | Unique identifier for a [Type](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type). |
| [createBaseTypeErrorFormatter](https://evolu.dev/docs/api-reference/common/Type/functions/createBaseTypeErrorFormatter) | Creates a formatter function for a base [TypeError](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError). |
| [createFormatTypeError](https://evolu.dev/docs/api-reference/common/Type/functions/createFormatTypeError) | Formats Evolu Type errors into user-friendly messages. |
| [createTypeErrorFormatter](https://evolu.dev/docs/api-reference/common/Type/functions/createTypeErrorFormatter) | Creates a formatter function for [TypeError](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError). |
| [isType](https://evolu.dev/docs/api-reference/common/Type/functions/isType) | Checks if the given value is an [Type](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type). |
| [typeErrorToStandardSchemaIssues](https://evolu.dev/docs/api-reference/common/Type/functions/typeErrorToStandardSchemaIssues) | Converts an Evolu [TypeError](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError) to Standard Schema V1 issues format. |
## Other
| Name | Description |
| ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| [StandardSchemaV1](https://evolu.dev/docs/api-reference/common/Type/namespaces/StandardSchemaV1) | - |
| [ArrayError](https://evolu.dev/docs/api-reference/common/Type/interfaces/ArrayError) | - |
| [ArrayType](https://evolu.dev/docs/api-reference/common/Type/interfaces/ArrayType) | ArrayType extends Type with an additional `element` property for reflection. |
| [Base64UrlError](https://evolu.dev/docs/api-reference/common/Type/interfaces/Base64UrlError) | - |
| [BetweenError](https://evolu.dev/docs/api-reference/common/Type/interfaces/BetweenError) | - |
| [BigIntError](https://evolu.dev/docs/api-reference/common/Type/interfaces/BigIntError) | - |
| [BooleanError](https://evolu.dev/docs/api-reference/common/Type/interfaces/BooleanError) | - |
| [BrandType](https://evolu.dev/docs/api-reference/common/Type/interfaces/BrandType) | Evolu [Type](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type) is like a type guard that returns typed errors (via [Result](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result)) instead of throwing. We either get a safely typed value or a composable typed error telling us exactly why validation failed. |
| [BrandWithoutRefineError](https://evolu.dev/docs/api-reference/common/Type/interfaces/BrandWithoutRefineError) | - |
| [CurrencyCodeError](https://evolu.dev/docs/api-reference/common/Type/interfaces/CurrencyCodeError) | - |
| [DateIsoError](https://evolu.dev/docs/api-reference/common/Type/interfaces/DateIsoError) | - |
| [EvoluTypeError](https://evolu.dev/docs/api-reference/common/Type/interfaces/EvoluTypeError) | - |
| [FiniteError](https://evolu.dev/docs/api-reference/common/Type/interfaces/FiniteError) | - |
| [FunctionError](https://evolu.dev/docs/api-reference/common/Type/interfaces/FunctionError) | - |
| [GreaterThanError](https://evolu.dev/docs/api-reference/common/Type/interfaces/GreaterThanError) | - |
| [GreaterThanOrEqualToError](https://evolu.dev/docs/api-reference/common/Type/interfaces/GreaterThanOrEqualToError) | - |
| [IdError](https://evolu.dev/docs/api-reference/common/Type/interfaces/IdError) | - |
| [InstanceOfError](https://evolu.dev/docs/api-reference/common/Type/interfaces/InstanceOfError) | - |
| [InstanceOfType](https://evolu.dev/docs/api-reference/common/Type/interfaces/InstanceOfType) | Evolu [Type](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type) is like a type guard that returns typed errors (via [Result](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result)) instead of throwing. We either get a safely typed value or a composable typed error telling us exactly why validation failed. |
| [Int64Error](https://evolu.dev/docs/api-reference/common/Type/interfaces/Int64Error) | - |
| [Int64StringError](https://evolu.dev/docs/api-reference/common/Type/interfaces/Int64StringError) | - |
| [IntError](https://evolu.dev/docs/api-reference/common/Type/interfaces/IntError) | - |
| [JsonError](https://evolu.dev/docs/api-reference/common/Type/interfaces/JsonError) | - |
| [JsonObject](https://evolu.dev/docs/api-reference/common/Type/interfaces/JsonObject) | - |
| [JsonObjectInput](https://evolu.dev/docs/api-reference/common/Type/interfaces/JsonObjectInput) | - |
| [LengthError](https://evolu.dev/docs/api-reference/common/Type/interfaces/LengthError) | - |
| [LessThanError](https://evolu.dev/docs/api-reference/common/Type/interfaces/LessThanError) | - |
| [LessThanOrEqualToError](https://evolu.dev/docs/api-reference/common/Type/interfaces/LessThanOrEqualToError) | - |
| [LiteralError](https://evolu.dev/docs/api-reference/common/Type/interfaces/LiteralError) | - |
| [LiteralType](https://evolu.dev/docs/api-reference/common/Type/interfaces/LiteralType) | Evolu [Type](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type) is like a type guard that returns typed errors (via [Result](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result)) instead of throwing. We either get a safely typed value or a composable typed error telling us exactly why validation failed. |
| [MaxLengthError](https://evolu.dev/docs/api-reference/common/Type/interfaces/MaxLengthError) | - |
| [MinLengthError](https://evolu.dev/docs/api-reference/common/Type/interfaces/MinLengthError) | - |
| [MnemonicError](https://evolu.dev/docs/api-reference/common/Type/interfaces/MnemonicError) | - |
| [MultipleOfError](https://evolu.dev/docs/api-reference/common/Type/interfaces/MultipleOfError) | - |
| [NegativeError](https://evolu.dev/docs/api-reference/common/Type/interfaces/NegativeError) | - |
| [NonNaNError](https://evolu.dev/docs/api-reference/common/Type/interfaces/NonNaNError) | - |
| [NonNegativeError](https://evolu.dev/docs/api-reference/common/Type/interfaces/NonNegativeError) | - |
| [NonPositiveError](https://evolu.dev/docs/api-reference/common/Type/interfaces/NonPositiveError) | - |
| [NullError](https://evolu.dev/docs/api-reference/common/Type/interfaces/NullError) | - |
| [NumberError](https://evolu.dev/docs/api-reference/common/Type/interfaces/NumberError) | - |
| [ObjectError](https://evolu.dev/docs/api-reference/common/Type/interfaces/ObjectError) | - |
| [ObjectType](https://evolu.dev/docs/api-reference/common/Type/interfaces/ObjectType) | ObjectType extends [Type](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type) with an additional `props` property for reflection. |
| [ObjectWithRecordError](https://evolu.dev/docs/api-reference/common/Type/interfaces/ObjectWithRecordError) | - |
| [ObjectWithRecordType](https://evolu.dev/docs/api-reference/common/Type/interfaces/ObjectWithRecordType) | ObjectWithRecordType extends [Type](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type) with additional `props` and `record` properties for reflection. |
| [OptionalType](https://evolu.dev/docs/api-reference/common/Type/interfaces/OptionalType) | Evolu [Type](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type) is like a type guard that returns typed errors (via [Result](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result)) instead of throwing. We either get a safely typed value or a composable typed error telling us exactly why validation failed. |
| [PositiveError](https://evolu.dev/docs/api-reference/common/Type/interfaces/PositiveError) | - |
| [RecordError](https://evolu.dev/docs/api-reference/common/Type/interfaces/RecordError) | - |
| [RecordType](https://evolu.dev/docs/api-reference/common/Type/interfaces/RecordType) | RecordType extends [Type](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type) with additional `key` and `value` properties for reflection. |
| [RecursiveType](https://evolu.dev/docs/api-reference/common/Type/interfaces/RecursiveType) | Evolu [Type](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type) is like a type guard that returns typed errors (via [Result](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result)) instead of throwing. We either get a safely typed value or a composable typed error telling us exactly why validation failed. |
| [RegexError](https://evolu.dev/docs/api-reference/common/Type/interfaces/RegexError) | - |
| [SetError](https://evolu.dev/docs/api-reference/common/Type/interfaces/SetError) | - |
| [SetType](https://evolu.dev/docs/api-reference/common/Type/interfaces/SetType) | SetType extends Type with an additional `element` property for reflection. |
| [SimpleNameError](https://evolu.dev/docs/api-reference/common/Type/interfaces/SimpleNameError) | - |
| [StandardSchemaV1](https://evolu.dev/docs/api-reference/common/Type/interfaces/StandardSchemaV1) | The Standard Schema interface. |
| [StringError](https://evolu.dev/docs/api-reference/common/Type/interfaces/StringError) | - |
| [TableId](https://evolu.dev/docs/api-reference/common/Type/interfaces/TableId) | Evolu [Type](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type) is like a type guard that returns typed errors (via [Result](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result)) instead of throwing. We either get a safely typed value or a composable typed error telling us exactly why validation failed. |
| [TableIdError](https://evolu.dev/docs/api-reference/common/Type/interfaces/TableIdError) | - |
| [TrimmedError](https://evolu.dev/docs/api-reference/common/Type/interfaces/TrimmedError) | - |
| [TupleError](https://evolu.dev/docs/api-reference/common/Type/interfaces/TupleError) | - |
| [TupleType](https://evolu.dev/docs/api-reference/common/Type/interfaces/TupleType) | TupleType extends [Type](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type) with an additional `elements` property for reflection. |
| [Type](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type) | Evolu [Type](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type) is like a type guard that returns typed errors (via [Result](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result)) instead of throwing. We either get a safely typed value or a composable typed error telling us exactly why validation failed. |
| [TypeError](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError) | - |
| [TypeErrorWithReason](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeErrorWithReason) | - |
| [Uint8ArrayError](https://evolu.dev/docs/api-reference/common/Type/interfaces/Uint8ArrayError) | - |
| [UndefinedError](https://evolu.dev/docs/api-reference/common/Type/interfaces/UndefinedError) | - |
| [UnionError](https://evolu.dev/docs/api-reference/common/Type/interfaces/UnionError) | - |
| [UnionType](https://evolu.dev/docs/api-reference/common/Type/interfaces/UnionType) | UnionType extends [Type](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type) with an additional `members` property for reflection. |
| [ValidMutationSizeError](https://evolu.dev/docs/api-reference/common/Type/interfaces/ValidMutationSizeError) | - |
| [AnyType](https://evolu.dev/docs/api-reference/common/Type/type-aliases/AnyType) | - |
| [Base64Url](https://evolu.dev/docs/api-reference/common/Type/type-aliases/Base64Url) | - |
| [CurrencyCode](https://evolu.dev/docs/api-reference/common/Type/type-aliases/CurrencyCode) | - |
| [DateIso](https://evolu.dev/docs/api-reference/common/Type/type-aliases/DateIso) | - |
| [FiniteNumber](https://evolu.dev/docs/api-reference/common/Type/type-aliases/FiniteNumber) | - |
| [Id](https://evolu.dev/docs/api-reference/common/Type/type-aliases/Id) | - |
| [IdBytes](https://evolu.dev/docs/api-reference/common/Type/type-aliases/IdBytes) | - |
| [Int](https://evolu.dev/docs/api-reference/common/Type/type-aliases/Int) | - |
| [Int64](https://evolu.dev/docs/api-reference/common/Type/type-aliases/Int64) | - |
| [Int64String](https://evolu.dev/docs/api-reference/common/Type/type-aliases/Int64String) | - |
| [IsUnionWithNull](https://evolu.dev/docs/api-reference/common/Type/type-aliases/IsUnionWithNull) | - |
| [Json](https://evolu.dev/docs/api-reference/common/Type/type-aliases/Json) | - |
| [JsonArray](https://evolu.dev/docs/api-reference/common/Type/type-aliases/JsonArray) | - |
| [JsonArrayInput](https://evolu.dev/docs/api-reference/common/Type/type-aliases/JsonArrayInput) | - |
| [JsonValue](https://evolu.dev/docs/api-reference/common/Type/type-aliases/JsonValue) | - |
| [JsonValueError](https://evolu.dev/docs/api-reference/common/Type/type-aliases/JsonValueError) | - |
| [JsonValueInput](https://evolu.dev/docs/api-reference/common/Type/type-aliases/JsonValueInput) | - |
| [Mnemonic](https://evolu.dev/docs/api-reference/common/Type/type-aliases/Mnemonic) | - |
| [NegativeInt](https://evolu.dev/docs/api-reference/common/Type/type-aliases/NegativeInt) | - |
| [NegativeNumber](https://evolu.dev/docs/api-reference/common/Type/type-aliases/NegativeNumber) | - |
| [NonEmptyString](https://evolu.dev/docs/api-reference/common/Type/type-aliases/NonEmptyString) | - |
| [NonEmptyString100](https://evolu.dev/docs/api-reference/common/Type/type-aliases/NonEmptyString100) | - |
| [NonEmptyString1000](https://evolu.dev/docs/api-reference/common/Type/type-aliases/NonEmptyString1000) | - |
| [NonEmptyTrimmedString](https://evolu.dev/docs/api-reference/common/Type/type-aliases/NonEmptyTrimmedString) | - |
| [NonEmptyTrimmedString100](https://evolu.dev/docs/api-reference/common/Type/type-aliases/NonEmptyTrimmedString100) | - |
| [NonEmptyTrimmedString1000](https://evolu.dev/docs/api-reference/common/Type/type-aliases/NonEmptyTrimmedString1000) | - |
| [NonNaNNumber](https://evolu.dev/docs/api-reference/common/Type/type-aliases/NonNaNNumber) | - |
| [NonNegativeInt](https://evolu.dev/docs/api-reference/common/Type/type-aliases/NonNegativeInt) | - |
| [NonNegativeNumber](https://evolu.dev/docs/api-reference/common/Type/type-aliases/NonNegativeNumber) | - |
| [NonPositiveInt](https://evolu.dev/docs/api-reference/common/Type/type-aliases/NonPositiveInt) | - |
| [NonPositiveNumber](https://evolu.dev/docs/api-reference/common/Type/type-aliases/NonPositiveNumber) | - |
| [NullableToOptionalProps](https://evolu.dev/docs/api-reference/common/Type/type-aliases/NullableToOptionalProps) | - |
| [NullTypeInMembers](https://evolu.dev/docs/api-reference/common/Type/type-aliases/NullTypeInMembers) | - |
| [PositiveInt](https://evolu.dev/docs/api-reference/common/Type/type-aliases/PositiveInt) | - |
| [PositiveNumber](https://evolu.dev/docs/api-reference/common/Type/type-aliases/PositiveNumber) | - |
| [SimpleName](https://evolu.dev/docs/api-reference/common/Type/type-aliases/SimpleName) | - |
| [SimplePassword](https://evolu.dev/docs/api-reference/common/Type/type-aliases/SimplePassword) | - |
| [SimplePasswordError](https://evolu.dev/docs/api-reference/common/Type/type-aliases/SimplePasswordError) | - |
| [String100](https://evolu.dev/docs/api-reference/common/Type/type-aliases/String100) | - |
| [String1000](https://evolu.dev/docs/api-reference/common/Type/type-aliases/String1000) | - |
| [TransformNullable](https://evolu.dev/docs/api-reference/common/Type/type-aliases/TransformNullable) | - |
| [TrimmedString](https://evolu.dev/docs/api-reference/common/Type/type-aliases/TrimmedString) | - |
| [TrimmedString100](https://evolu.dev/docs/api-reference/common/Type/type-aliases/TrimmedString100) | - |
| [TrimmedString1000](https://evolu.dev/docs/api-reference/common/Type/type-aliases/TrimmedString1000) | - |
| [TypeErrorFormatter](https://evolu.dev/docs/api-reference/common/Type/type-aliases/TypeErrorFormatter) | - |
| [UrlSafeString](https://evolu.dev/docs/api-reference/common/Type/type-aliases/UrlSafeString) | - |
| [UrlSafeStringError](https://evolu.dev/docs/api-reference/common/Type/type-aliases/UrlSafeStringError) | - |
| [ValidMutationSize](https://evolu.dev/docs/api-reference/common/Type/type-aliases/ValidMutationSize) | - |
| [base64UrlToUint8Array](https://evolu.dev/docs/api-reference/common/Type/variables/base64UrlToUint8Array) | Decodes a [Base64Url](https://evolu.dev/docs/api-reference/common/Type/variables/Base64Url) string to a Uint8Array. |
| [EvoluType](https://evolu.dev/docs/api-reference/common/Type/variables/EvoluType) | Validates that an unknown value is an Evolu [Type](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type) (i.e., satisfies `AnyType`). |
| [formatBase64UrlError](https://evolu.dev/docs/api-reference/common/Type/variables/formatBase64UrlError) | - |
| [formatBetweenError](https://evolu.dev/docs/api-reference/common/Type/variables/formatBetweenError) | - |
| [formatBigIntError](https://evolu.dev/docs/api-reference/common/Type/variables/formatBigIntError) | - |
| [formatBooleanError](https://evolu.dev/docs/api-reference/common/Type/variables/formatBooleanError) | - |
| [formatCurrencyCodeError](https://evolu.dev/docs/api-reference/common/Type/variables/formatCurrencyCodeError) | - |
| [formatDateIsoError](https://evolu.dev/docs/api-reference/common/Type/variables/formatDateIsoError) | - |
| [formatFiniteError](https://evolu.dev/docs/api-reference/common/Type/variables/formatFiniteError) | - |
| [formatFunctionError](https://evolu.dev/docs/api-reference/common/Type/variables/formatFunctionError) | - |
| [formatGreaterThanError](https://evolu.dev/docs/api-reference/common/Type/variables/formatGreaterThanError) | - |
| [formatGreaterThanOrEqualToError](https://evolu.dev/docs/api-reference/common/Type/variables/formatGreaterThanOrEqualToError) | - |
| [formatIdError](https://evolu.dev/docs/api-reference/common/Type/variables/formatIdError) | - |
| [formatInstanceOfError](https://evolu.dev/docs/api-reference/common/Type/variables/formatInstanceOfError) | - |
| [formatInt64Error](https://evolu.dev/docs/api-reference/common/Type/variables/formatInt64Error) | - |
| [formatInt64StringError](https://evolu.dev/docs/api-reference/common/Type/variables/formatInt64StringError) | - |
| [formatIntError](https://evolu.dev/docs/api-reference/common/Type/variables/formatIntError) | - |
| [formatIsTypeError](https://evolu.dev/docs/api-reference/common/Type/variables/formatIsTypeError) | - |
| [formatJsonError](https://evolu.dev/docs/api-reference/common/Type/variables/formatJsonError) | - |
| [formatLengthError](https://evolu.dev/docs/api-reference/common/Type/variables/formatLengthError) | - |
| [formatLessThanError](https://evolu.dev/docs/api-reference/common/Type/variables/formatLessThanError) | - |
| [formatLessThanOrEqualToError](https://evolu.dev/docs/api-reference/common/Type/variables/formatLessThanOrEqualToError) | - |
| [formatLiteralError](https://evolu.dev/docs/api-reference/common/Type/variables/formatLiteralError) | - |
| [formatMaxLengthError](https://evolu.dev/docs/api-reference/common/Type/variables/formatMaxLengthError) | - |
| [formatMinLengthError](https://evolu.dev/docs/api-reference/common/Type/variables/formatMinLengthError) | - |
| [formatMnemonicError](https://evolu.dev/docs/api-reference/common/Type/variables/formatMnemonicError) | - |
| [formatMultipleOfError](https://evolu.dev/docs/api-reference/common/Type/variables/formatMultipleOfError) | - |
| [formatNegativeError](https://evolu.dev/docs/api-reference/common/Type/variables/formatNegativeError) | - |
| [formatNonNaNError](https://evolu.dev/docs/api-reference/common/Type/variables/formatNonNaNError) | - |
| [formatNonNegativeError](https://evolu.dev/docs/api-reference/common/Type/variables/formatNonNegativeError) | - |
| [formatNonPositiveError](https://evolu.dev/docs/api-reference/common/Type/variables/formatNonPositiveError) | - |
| [formatNullError](https://evolu.dev/docs/api-reference/common/Type/variables/formatNullError) | - |
| [formatNumberError](https://evolu.dev/docs/api-reference/common/Type/variables/formatNumberError) | - |
| [formatPositiveError](https://evolu.dev/docs/api-reference/common/Type/variables/formatPositiveError) | - |
| [formatRegexError](https://evolu.dev/docs/api-reference/common/Type/variables/formatRegexError) | - |
| [formatStringError](https://evolu.dev/docs/api-reference/common/Type/variables/formatStringError) | - |
| [formatTableIdError](https://evolu.dev/docs/api-reference/common/Type/variables/formatTableIdError) | - |
| [formatTrimmedError](https://evolu.dev/docs/api-reference/common/Type/variables/formatTrimmedError) | - |
| [formatUint8ArrayError](https://evolu.dev/docs/api-reference/common/Type/variables/formatUint8ArrayError) | - |
| [formatUndefinedError](https://evolu.dev/docs/api-reference/common/Type/variables/formatUndefinedError) | - |
| [formatValidMutationSizeError](https://evolu.dev/docs/api-reference/common/Type/variables/formatValidMutationSizeError) | - |
| [IdBytes](https://evolu.dev/docs/api-reference/common/Type/variables/IdBytes) | Binary representation of an [Id](https://evolu.dev/docs/api-reference/common/Type/variables/Id). |
| [idBytesTypeValueLength](https://evolu.dev/docs/api-reference/common/Type/variables/idBytesTypeValueLength) | - |
| [maxMutationSize](https://evolu.dev/docs/api-reference/common/Type/variables/maxMutationSize) | - |
| [maxPositiveInt](https://evolu.dev/docs/api-reference/common/Type/variables/maxPositiveInt) | Maximum safe positive integer value for practically infinite operations. |
| [uint8ArrayToBase64Url](https://evolu.dev/docs/api-reference/common/Type/variables/uint8ArrayToBase64Url) | Encodes a Uint8Array to a [Base64Url](https://evolu.dev/docs/api-reference/common/Type/variables/Base64Url) string. |
| [createId](https://evolu.dev/docs/api-reference/common/Type/functions/createId) | Creates a random [Id](https://evolu.dev/docs/api-reference/common/Type/variables/Id). This is the recommended default. |
| [createIdAsUuidv7](https://evolu.dev/docs/api-reference/common/Type/functions/createIdAsUuidv7) | Creates an [Id](https://evolu.dev/docs/api-reference/common/Type/variables/Id) embedding timestamp bits (UUID v7 layout) before Base64Url encoding. |
| [dateIsoToDate](https://evolu.dev/docs/api-reference/common/Type/functions/dateIsoToDate) | - |
| [dateToDateIso](https://evolu.dev/docs/api-reference/common/Type/functions/dateToDateIso) | - |
| [formatArrayError](https://evolu.dev/docs/api-reference/common/Type/functions/formatArrayError) | - |
| [formatObjectError](https://evolu.dev/docs/api-reference/common/Type/functions/formatObjectError) | - |
| [formatObjectWithRecordError](https://evolu.dev/docs/api-reference/common/Type/functions/formatObjectWithRecordError) | - |
| [formatRecordError](https://evolu.dev/docs/api-reference/common/Type/functions/formatRecordError) | - |
| [formatSetError](https://evolu.dev/docs/api-reference/common/Type/functions/formatSetError) | - |
| [formatSimplePasswordError](https://evolu.dev/docs/api-reference/common/Type/functions/formatSimplePasswordError) | - |
| [formatTupleError](https://evolu.dev/docs/api-reference/common/Type/functions/formatTupleError) | - |
| [formatUnionError](https://evolu.dev/docs/api-reference/common/Type/functions/formatUnionError) | - |
| [idBytesToId](https://evolu.dev/docs/api-reference/common/Type/functions/idBytesToId) | - |
| [idToIdBytes](https://evolu.dev/docs/api-reference/common/Type/functions/idToIdBytes) | - |
| [isOptionalType](https://evolu.dev/docs/api-reference/common/Type/functions/isOptionalType) | Determines if a given type is an [OptionalType](https://evolu.dev/docs/api-reference/common/Type/interfaces/OptionalType). |
| [isUnionType](https://evolu.dev/docs/api-reference/common/Type/functions/isUnionType) | - |
| [json](https://evolu.dev/docs/api-reference/common/Type/functions/json) | Creates a branded JSON string [Type](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type) and type-safe conversion functions for a given Type. |
| [jsonToJsonValue](https://evolu.dev/docs/api-reference/common/Type/functions/jsonToJsonValue) | - |
| [jsonValueToJson](https://evolu.dev/docs/api-reference/common/Type/functions/jsonValueToJson) | - |
| [optional](https://evolu.dev/docs/api-reference/common/Type/functions/optional) | Optional [Type](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type). |
| [parseJson](https://evolu.dev/docs/api-reference/common/Type/functions/parseJson) | - |
| [trim](https://evolu.dev/docs/api-reference/common/Type/functions/trim) | - |
| [validMutationSize](https://evolu.dev/docs/api-reference/common/Type/functions/validMutationSize) | Evolu has to limit the maximum mutation size. Otherwise, sync couldn't use the `maxProtocolMessageRangesSize`. The max size is 640KB in bytes, measured via MessagePack. Evolu Protocol DbChange will be smaller thanks to various optimizations. |
API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / Types
# Types
TypeScript utility types
## Type Aliases
| Type Alias | Description |
| -------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| [IntentionalNever](https://evolu.dev/docs/api-reference/common/Types/type-aliases/IntentionalNever) | A type alias for `never` that is used intentionally when casting is not needed and unit tests exist to ensure correctness. |
| [Literal](https://evolu.dev/docs/api-reference/common/Types/type-aliases/Literal) | String, number, bigint, boolean, undefined, null |
| [NullablePartial](https://evolu.dev/docs/api-reference/common/Types/type-aliases/NullablePartial) | Makes properties optional if they accept `null` as a value. |
| [PartialProp](https://evolu.dev/docs/api-reference/common/Types/type-aliases/PartialProp) | Makes a specific property of an object optional while keeping others unchanged. |
| [Predicate](https://evolu.dev/docs/api-reference/common/Types/type-aliases/Predicate) | Checks a condition on a value and returns a boolean. |
| [PredicateWithIndex](https://evolu.dev/docs/api-reference/common/Types/type-aliases/PredicateWithIndex) | Checks a condition on a value at a given index and returns a boolean. |
| [Refinement](https://evolu.dev/docs/api-reference/common/Types/type-aliases/Refinement) | A type guard function that refines type `A` to a narrower type `B`. |
| [RefinementWithIndex](https://evolu.dev/docs/api-reference/common/Types/type-aliases/RefinementWithIndex) | A type guard function that refines type `A` to a narrower type `B` at a given index. |
| [Simplify](https://evolu.dev/docs/api-reference/common/Types/type-aliases/Simplify) | Simplify an intersection type into a single mapped type. |
| [WidenLiteral](https://evolu.dev/docs/api-reference/common/Types/type-aliases/WidenLiteral) | Infers a broader type from a specific literal value type. |
API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / WebSocket
# WebSocket
## Interfaces
| Interface | Description |
| ------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------- |
| [CreateWebSocketDep](https://evolu.dev/docs/api-reference/common/WebSocket/interfaces/CreateWebSocketDep) | - |
| [WebSocket](https://evolu.dev/docs/api-reference/common/WebSocket/interfaces/WebSocket) | WebSocket with auto-reconnect and offline support. |
| [WebSocketConnectError](https://evolu.dev/docs/api-reference/common/WebSocket/interfaces/WebSocketConnectError) | An error that occurs when a connection cannot be established due to a network error. |
| [WebSocketConnectionCloseError](https://evolu.dev/docs/api-reference/common/WebSocket/interfaces/WebSocketConnectionCloseError) | - |
| [WebSocketConnectionError](https://evolu.dev/docs/api-reference/common/WebSocket/interfaces/WebSocketConnectionError) | An error that occurs when a connection is closed due to an issue (e.g., failure to send some data). |
| [WebSocketOptions](https://evolu.dev/docs/api-reference/common/WebSocket/interfaces/WebSocketOptions) | Options for creating [WebSocket](https://evolu.dev/docs/api-reference/common/WebSocket/interfaces/WebSocket) |
| [WebSocketSendError](https://evolu.dev/docs/api-reference/common/WebSocket/interfaces/WebSocketSendError) | An error that occurs when trying to send data but WebSocket is not available or is in the CONNECTING state. |
## Type Aliases
| Type Alias | Description |
| ------------------------------------------------------------------------------------------------ | ---------------------------- |
| [CreateWebSocket](https://evolu.dev/docs/api-reference/common/WebSocket/type-aliases/CreateWebSocket) | - |
| [WebSocketError](https://evolu.dev/docs/api-reference/common/WebSocket/type-aliases/WebSocketError) | - |
| [WebSocketReadyState](https://evolu.dev/docs/api-reference/common/WebSocket/type-aliases/WebSocketReadyState) | WebSocket connection states. |
| [WebSocketRetryError](https://evolu.dev/docs/api-reference/common/WebSocket/type-aliases/WebSocketRetryError) | - |
## Variables
| Variable | Description |
| ------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| [createWebSocket](https://evolu.dev/docs/api-reference/common/WebSocket/variables/createWebSocket) | Create a new [WebSocket](https://evolu.dev/docs/api-reference/common/WebSocket/interfaces/WebSocket). |
API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / Worker
# Worker
## Interfaces
| Interface | Description |
| --------------------------------------------------------------------------------------------- | ---------------------------------- |
| [Worker](https://evolu.dev/docs/api-reference/common/Worker/interfaces/Worker) | Cross-platform worker abstraction. |
| [WorkerPostMessageDep](https://evolu.dev/docs/api-reference/common/Worker/interfaces/WorkerPostMessageDep) | - |
## Type Aliases
| Type Alias | Description |
| ------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| [MessageHandlers](https://evolu.dev/docs/api-reference/common/Worker/type-aliases/MessageHandlers) | Type helper to extract message types from a union type |
| [WithErrorReporting](https://evolu.dev/docs/api-reference/common/Worker/type-aliases/WithErrorReporting) | Error reporting wrapper that catches synchronous errors in handlers and converts them to transferable error messages sent to the main thread. |
## Functions
| Function | Description |
| -------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [createInitializedWorker](https://evolu.dev/docs/api-reference/common/Worker/functions/createInitializedWorker) | Creates a [Worker](https://evolu.dev/docs/api-reference/common/Worker/interfaces/Worker) that supports initialization with dependencies and safe error handling. |
| [createInitializedWorkerWithHandlers](https://evolu.dev/docs/api-reference/common/Worker/functions/createInitializedWorkerWithHandlers) | Creates a [Worker](https://evolu.dev/docs/api-reference/common/Worker/interfaces/Worker) with type-safe message handlers for each message type. This provides better type safety and organization compared to a single onMessage handler. |
API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / local-first
# local-first
Internal local-first modules re-exported from "@evolu/common/local-first"
These exports expose the internal building blocks of Evolu's local-first
implementation (Db, Relay, Sync, Query, Storage, Timestamp, etc.). They are
primarily intended for use within Evolu packages and for advanced use-cases
that require direct access to local-first internals.
Public consumers should us top-level exports from `@evolu/common` unless you
have a specific need to import these internals.
## Utilities
| Interface | Description |
| ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| [Timestamp](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Timestamp) | Extracts the type from a [Type](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type). |
## Other
### applyProtocolMessageAsClient
Re-exports [applyProtocolMessageAsClient](https://evolu.dev/docs/api-reference/common/local-first/Protocol/functions/applyProtocolMessageAsClient)
---
### ApplyProtocolMessageAsClientOptions
Re-exports [ApplyProtocolMessageAsClientOptions](https://evolu.dev/docs/api-reference/common/local-first/Protocol/interfaces/ApplyProtocolMessageAsClientOptions)
---
### ApplyProtocolMessageAsClientResult
Re-exports [ApplyProtocolMessageAsClientResult](https://evolu.dev/docs/api-reference/common/local-first/Protocol/type-aliases/ApplyProtocolMessageAsClientResult)
---
### applyProtocolMessageAsRelay
Re-exports [applyProtocolMessageAsRelay](https://evolu.dev/docs/api-reference/common/local-first/Protocol/functions/applyProtocolMessageAsRelay)
---
### ApplyProtocolMessageAsRelayOptions
Re-exports [ApplyProtocolMessageAsRelayOptions](https://evolu.dev/docs/api-reference/common/local-first/Protocol/interfaces/ApplyProtocolMessageAsRelayOptions)
---
### ApplyProtocolMessageAsRelayResult
Re-exports [ApplyProtocolMessageAsRelayResult](https://evolu.dev/docs/api-reference/common/local-first/Protocol/interfaces/ApplyProtocolMessageAsRelayResult)
---
### createProtocolMessageBuffer
Re-exports [createProtocolMessageBuffer](https://evolu.dev/docs/api-reference/common/local-first/Protocol/functions/createProtocolMessageBuffer)
---
### createProtocolMessageForSync
Re-exports [createProtocolMessageForSync](https://evolu.dev/docs/api-reference/common/local-first/Protocol/functions/createProtocolMessageForSync)
---
### createProtocolMessageForUnsubscribe
Re-exports [createProtocolMessageForUnsubscribe](https://evolu.dev/docs/api-reference/common/local-first/Protocol/functions/createProtocolMessageForUnsubscribe)
---
### createProtocolMessageFromCrdtMessages
Re-exports [createProtocolMessageFromCrdtMessages](https://evolu.dev/docs/api-reference/common/local-first/Protocol/functions/createProtocolMessageFromCrdtMessages)
---
### createTimestampsBuffer
Re-exports [createTimestampsBuffer](https://evolu.dev/docs/api-reference/common/local-first/Protocol/functions/createTimestampsBuffer)
---
### decodeFlags
Re-exports [decodeFlags](https://evolu.dev/docs/api-reference/common/local-first/Protocol/functions/decodeFlags)
---
### decodeLength
Re-exports [decodeLength](https://evolu.dev/docs/api-reference/common/local-first/Protocol/variables/decodeLength)
---
### decodeNodeId
Re-exports [decodeNodeId](https://evolu.dev/docs/api-reference/common/local-first/Protocol/functions/decodeNodeId)
---
### decodeNonNegativeInt
Re-exports [decodeNonNegativeInt](https://evolu.dev/docs/api-reference/common/local-first/Protocol/functions/decodeNonNegativeInt)
---
### decodeNumber
Re-exports [decodeNumber](https://evolu.dev/docs/api-reference/common/local-first/Protocol/functions/decodeNumber)
---
### decodeProtocolMessageToJson
Re-exports [decodeProtocolMessageToJson](https://evolu.dev/docs/api-reference/common/local-first/Protocol/functions/decodeProtocolMessageToJson)
---
### decodeSqliteValue
Re-exports [decodeSqliteValue](https://evolu.dev/docs/api-reference/common/local-first/Protocol/functions/decodeSqliteValue)
---
### decodeString
Re-exports [decodeString](https://evolu.dev/docs/api-reference/common/local-first/Protocol/functions/decodeString)
---
### decryptAndDecodeDbChange
Re-exports [decryptAndDecodeDbChange](https://evolu.dev/docs/api-reference/common/local-first/Protocol/functions/decryptAndDecodeDbChange)
---
### defaultProtocolMessageMaxSize
Re-exports [defaultProtocolMessageMaxSize](https://evolu.dev/docs/api-reference/common/local-first/Protocol/variables/defaultProtocolMessageMaxSize)
---
### defaultProtocolMessageRangesMaxSize
Re-exports [defaultProtocolMessageRangesMaxSize](https://evolu.dev/docs/api-reference/common/local-first/Protocol/variables/defaultProtocolMessageRangesMaxSize)
---
### encodeAndEncryptDbChange
Re-exports [encodeAndEncryptDbChange](https://evolu.dev/docs/api-reference/common/local-first/Protocol/functions/encodeAndEncryptDbChange)
---
### encodeFlags
Re-exports [encodeFlags](https://evolu.dev/docs/api-reference/common/local-first/Protocol/functions/encodeFlags)
---
### encodeLength
Re-exports [encodeLength](https://evolu.dev/docs/api-reference/common/local-first/Protocol/functions/encodeLength)
---
### encodeNodeId
Re-exports [encodeNodeId](https://evolu.dev/docs/api-reference/common/local-first/Protocol/functions/encodeNodeId)
---
### encodeNonNegativeInt
Re-exports [encodeNonNegativeInt](https://evolu.dev/docs/api-reference/common/local-first/Protocol/functions/encodeNonNegativeInt)
---
### encodeNumber
Re-exports [encodeNumber](https://evolu.dev/docs/api-reference/common/local-first/Protocol/functions/encodeNumber)
---
### encodeSqliteValue
Re-exports [encodeSqliteValue](https://evolu.dev/docs/api-reference/common/local-first/Protocol/functions/encodeSqliteValue)
---
### encodeString
Re-exports [encodeString](https://evolu.dev/docs/api-reference/common/local-first/Protocol/functions/encodeString)
---
### MessageType
Re-exports [MessageType](https://evolu.dev/docs/api-reference/common/local-first/Protocol/variables/MessageType)
---
### ProtocolError
Re-exports [ProtocolError](https://evolu.dev/docs/api-reference/common/local-first/Protocol/type-aliases/ProtocolError)
---
### ProtocolErrorCode
Re-exports [ProtocolErrorCode](https://evolu.dev/docs/api-reference/common/local-first/Protocol/variables/ProtocolErrorCode)
---
### ProtocolInvalidDataError
Re-exports [ProtocolInvalidDataError](https://evolu.dev/docs/api-reference/common/local-first/Protocol/interfaces/ProtocolInvalidDataError)
---
### ProtocolMessage
Re-exports [ProtocolMessage](https://evolu.dev/docs/api-reference/common/local-first/Protocol/type-aliases/ProtocolMessage)
---
### ProtocolMessageBuffer
Re-exports [ProtocolMessageBuffer](https://evolu.dev/docs/api-reference/common/local-first/Protocol/interfaces/ProtocolMessageBuffer)
---
### ProtocolMessageMaxSize
Re-exports [ProtocolMessageMaxSize](https://evolu.dev/docs/api-reference/common/local-first/Protocol/variables/ProtocolMessageMaxSize)
---
### ProtocolMessageRangesMaxSize
Re-exports [ProtocolMessageRangesMaxSize](https://evolu.dev/docs/api-reference/common/local-first/Protocol/variables/ProtocolMessageRangesMaxSize)
---
### ProtocolQuotaError
Re-exports [ProtocolQuotaError](https://evolu.dev/docs/api-reference/common/local-first/Protocol/interfaces/ProtocolQuotaError)
---
### ProtocolSyncError
Re-exports [ProtocolSyncError](https://evolu.dev/docs/api-reference/common/local-first/Protocol/interfaces/ProtocolSyncError)
---
### ProtocolTimestampMismatchError
Re-exports [ProtocolTimestampMismatchError](https://evolu.dev/docs/api-reference/common/local-first/Protocol/interfaces/ProtocolTimestampMismatchError)
---
### ProtocolValueType
Re-exports [ProtocolValueType](https://evolu.dev/docs/api-reference/common/local-first/Protocol/variables/ProtocolValueType)
---
### protocolVersion
Re-exports [protocolVersion](https://evolu.dev/docs/api-reference/common/local-first/Protocol/variables/protocolVersion)
---
### ProtocolVersionError
Re-exports [ProtocolVersionError](https://evolu.dev/docs/api-reference/common/local-first/Protocol/interfaces/ProtocolVersionError)
---
### ProtocolWriteError
Re-exports [ProtocolWriteError](https://evolu.dev/docs/api-reference/common/local-first/Protocol/interfaces/ProtocolWriteError)
---
### ProtocolWriteKeyError
Re-exports [ProtocolWriteKeyError](https://evolu.dev/docs/api-reference/common/local-first/Protocol/interfaces/ProtocolWriteKeyError)
---
### SubscriptionFlag
Re-exports [SubscriptionFlag](https://evolu.dev/docs/api-reference/common/local-first/Protocol/type-aliases/SubscriptionFlag)
---
### SubscriptionFlags
Re-exports [SubscriptionFlags](https://evolu.dev/docs/api-reference/common/local-first/Protocol/variables/SubscriptionFlags)
---
### TimestampsBuffer
Re-exports [TimestampsBuffer](https://evolu.dev/docs/api-reference/common/local-first/Protocol/interfaces/TimestampsBuffer)
---
### TimestampsRangeWithTimestampsBuffer
Re-exports [TimestampsRangeWithTimestampsBuffer](https://evolu.dev/docs/api-reference/common/local-first/Protocol/interfaces/TimestampsRangeWithTimestampsBuffer)
API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/nodejs](https://evolu.dev/docs/api-reference/nodejs) / index
# index
## Interfaces
| Interface | Description |
| -------------------------------------------------------------------------------------- | ----------- |
| [NodeJsRelayConfig](https://evolu.dev/docs/api-reference/nodejs/index/interfaces/NodeJsRelayConfig) | - |
## Variables
| Variable | Description |
| --------------------------------------------------------------------------------------------------- | ----------- |
| [createBetterSqliteDriver](https://evolu.dev/docs/api-reference/nodejs/index/variables/createBetterSqliteDriver) | - |
## Functions
| Function | Description |
| --------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
| [createNodeJsRelay](https://evolu.dev/docs/api-reference/nodejs/index/functions/createNodeJsRelay) | Creates an Evolu relay server. |
| [createNodeJsRelayWithSqliteDriver](https://evolu.dev/docs/api-reference/nodejs/index/functions/createNodeJsRelayWithSqliteDriver) | Creates an Evolu relay server with a custom SQLite driver. |
API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/react](https://evolu.dev/docs/api-reference/react) / index
# index
## Variables
| Variable | Description |
| -------------------------------------------------------------------------- | ----------- |
| [EvoluContext](https://evolu.dev/docs/api-reference/react/index/variables/EvoluContext) | - |
## Functions
| Function | Description |
| ------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [createUseEvolu](https://evolu.dev/docs/api-reference/react/index/functions/createUseEvolu) | Creates a typed React Hook returning an instance of [Evolu](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Evolu). |
| [EvoluProvider](https://evolu.dev/docs/api-reference/react/index/functions/EvoluProvider) | - |
| [useEvolu](https://evolu.dev/docs/api-reference/react/index/functions/useEvolu) | React Hook returning a generic instance of [Evolu](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Evolu). |
| [useEvoluError](https://evolu.dev/docs/api-reference/react/index/functions/useEvoluError) | Subscribe to [EvoluError](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/EvoluError) changes. |
| [useIsSsr](https://evolu.dev/docs/api-reference/react/index/functions/useIsSsr) | Avoiding hydration mismatches. |
| [useOwner](https://evolu.dev/docs/api-reference/react/index/functions/useOwner) | React Hook for Evolu `useOwner` method. |
| [useQueries](https://evolu.dev/docs/api-reference/react/index/functions/useQueries) | The same as [useQuery](https://evolu.dev/docs/api-reference/react/index/functions/useQuery), but for many queries. |
| [useQuery](https://evolu.dev/docs/api-reference/react/index/functions/useQuery) | Load and subscribe to the Query, and return an object with `rows` and `row` properties that are automatically updated when data changes. |
| [useQuerySubscription](https://evolu.dev/docs/api-reference/react/index/functions/useQuerySubscription) | Subscribe to [Query](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/Query) [QueryRows](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/QueryRows) changes. |
API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/react-native](https://evolu.dev/docs/api-reference/react-native) / web
# web
## Variables
| Variable | Description |
| ----------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [createUseEvolu](https://evolu.dev/docs/api-reference/react-native/web/variables/createUseEvolu) | Creates a typed React Hook returning an instance of [Evolu](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Evolu). |
| [EvoluContext](https://evolu.dev/docs/api-reference/react-native/web/variables/EvoluContext) | - |
| [EvoluProvider](https://evolu.dev/docs/api-reference/react-native/web/variables/EvoluProvider) | - |
| [useEvolu](https://evolu.dev/docs/api-reference/react-native/web/variables/useEvolu) | React Hook returning a generic instance of [Evolu](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Evolu). |
| [useEvoluError](https://evolu.dev/docs/api-reference/react-native/web/variables/useEvoluError) | Subscribe to [EvoluError](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/EvoluError) changes. |
| [useIsSsr](https://evolu.dev/docs/api-reference/react-native/web/variables/useIsSsr) | Avoiding hydration mismatches. |
| [useOwner](https://evolu.dev/docs/api-reference/react-native/web/variables/useOwner) | React Hook for Evolu `useOwner` method. |
| [useQueries](https://evolu.dev/docs/api-reference/react-native/web/variables/useQueries) | The same as [useQuery](https://evolu.dev/docs/api-reference/react-native/web/variables/useQuery), but for many queries. |
| [useQuery](https://evolu.dev/docs/api-reference/react-native/web/variables/useQuery) | Load and subscribe to the Query, and return an object with `rows` and `row` properties that are automatically updated when data changes. |
| [useQuerySubscription](https://evolu.dev/docs/api-reference/react-native/web/variables/useQuerySubscription) | Subscribe to [Query](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/Query) [QueryRows](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/QueryRows) changes. |
API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/svelte](https://evolu.dev/docs/api-reference/svelte) / index.svelte
# index.svelte
## Variables
| Variable | Description |
| ---------------------------------------------------------------------------------------- | ----------- |
| [evoluSvelteDeps](https://evolu.dev/docs/api-reference/svelte/index.svelte/variables/evoluSvelteDeps) | - |
## Functions
| Function | Description |
| ------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------- |
| [appOwnerState](https://evolu.dev/docs/api-reference/svelte/index.svelte/functions/appOwnerState) | Get the [AppOwner](https://evolu.dev/docs/api-reference/common/local-first/interfaces/AppOwner) promise that resolves when available. |
| [queryState](https://evolu.dev/docs/api-reference/svelte/index.svelte/functions/queryState) | Load and subscribe to the Query, and return an object with `rows` property that are automatically updated when data changes. |
API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/vue](https://evolu.dev/docs/api-reference/vue) / index
# index
## Type Aliases
| Type Alias | Description |
| --------------------------------------------------------------------------------------------- | ----------- |
| [QueriesToQueryRowsRef](https://evolu.dev/docs/api-reference/vue/index/type-aliases/QueriesToQueryRowsRef) | - |
## Variables
| Variable | Description |
| -------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| [EvoluContext](https://evolu.dev/docs/api-reference/vue/index/variables/EvoluContext) | The injection key for providing Evolu. |
| [evoluInstanceMap](https://evolu.dev/docs/api-reference/vue/index/variables/evoluInstanceMap) | Stores the Evolu instance for a Vue component. This is most useful at the root component where provide/inject doesn't work. |
| [EvoluProvider](https://evolu.dev/docs/api-reference/vue/index/variables/EvoluProvider) | - |
## Functions
| Function | Description |
| ---------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| [createUseEvolu](https://evolu.dev/docs/api-reference/vue/index/functions/createUseEvolu) | Creates a helper function returning a type-aware instance of [Evolu](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Evolu). |
| [provideEvolu](https://evolu.dev/docs/api-reference/vue/index/functions/provideEvolu) | Provide the Evolu instance to components via Vue's provide/inject system. |
| [useEvolu](https://evolu.dev/docs/api-reference/vue/index/functions/useEvolu) | Vue composable returning a generic instance of [Evolu](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Evolu). |
| [useEvoluError](https://evolu.dev/docs/api-reference/vue/index/functions/useEvoluError) | Subscribe to [EvoluError](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/EvoluError) changes. |
| [useOwner](https://evolu.dev/docs/api-reference/vue/index/functions/useOwner) | Vue composable for Evolu `useOwner` method. |
| [useQueries](https://evolu.dev/docs/api-reference/vue/index/functions/useQueries) | The same as [useQuery](https://evolu.dev/docs/api-reference/vue/index/functions/useQuery), but for many queries. |
| [useQuery](https://evolu.dev/docs/api-reference/vue/index/functions/useQuery) | Load and subscribe to the query, returning a ref that stays in sync with Evolu changes. |
| [useSyncState](https://evolu.dev/docs/api-reference/vue/index/functions/useSyncState) | Subscribe to [SyncState](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/SyncState) changes. |
API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/react-web](https://evolu.dev/docs/api-reference/react-web) / index
# index
## Variables
| Variable | Description |
| ---------------------------------------------------------------------------------------- | ----------- |
| [EvoluIdenticon](https://evolu.dev/docs/api-reference/react-web/index/variables/EvoluIdenticon) | - |
| [evoluReactWebDeps](https://evolu.dev/docs/api-reference/react-web/index/variables/evoluReactWebDeps) | - |
| [localAuth](https://evolu.dev/docs/api-reference/react-web/index/variables/localAuth) | - |
API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/web](https://evolu.dev/docs/api-reference/web) / index
# index
## Variables
| Variable | Description |
| -------------------------------------------------------------------------------------------- | ----------- |
| [createWasmSqliteDriver](https://evolu.dev/docs/api-reference/web/index/variables/createWasmSqliteDriver) | - |
| [evoluWebDeps](https://evolu.dev/docs/api-reference/web/index/variables/evoluWebDeps) | - |
| [localAuth](https://evolu.dev/docs/api-reference/web/index/variables/localAuth) | - |
## Functions
| Function | Description |
| ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| [createSharedWebWorker](https://evolu.dev/docs/api-reference/web/index/functions/createSharedWebWorker) | Creates a shared Web Worker using BroadcastChannel and Web Locks. This allows multiple tabs to share a single Web Worker instance. The first tab to acquire the lock becomes the owner and runs the worker. Other tabs act as proxies, forwarding messages to the owner. |
| [wrapWebWorker](https://evolu.dev/docs/api-reference/web/index/functions/wrapWebWorker) | Wraps a Web Worker to provide a typed interface for sending and receiving messages. |
| [wrapWebWorkerSelf](https://evolu.dev/docs/api-reference/web/index/functions/wrapWebWorkerSelf) | - |
API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / local-first/Protocol
# local-first/Protocol
Evolu Protocol
Evolu Protocol is a local-first, end-to-end encrypted binary synchronization
protocol optimized for minimal size and maximum speed. It enables data sync
between a client and a relay. In the future, direct peer-to-peer (P2P) sync
between clients will be possible without a relay.
Relays don't need to sync with each other—clients using those relays will
sync them eventually. If a relay is offline (e.g., for maintenance), it will
sync automatically later via client sync logic. For relay backup using
SQLite, see https://sqlite.org/rsync.html (uses a similar algorithm to Evolu
RBSR).
Evolu Protocol is designed for SQLite but can be extended to any database. It
implements [Range-Based Set
Reconciliation](https://arxiv.org/abs/2212.13567). To learn how RBSR works,
check [Negentropy](https://logperiodic.com/rbsr.html). Evolu Protocol is
similar to Negentropy but uses different encoding and also provides data
transfer, ownership, real-time broadcasting, request-response semantics, and
error handling.
### Message structure
| Field | Notes |
| :----------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------- |
| **Header** | |
| - [protocolVersion](https://evolu.dev/docs/api-reference/common/local-first/Protocol/variables/protocolVersion) | |
| - [OwnerId](https://evolu.dev/docs/api-reference/common/local-first/variables/OwnerId) | [Owner](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Owner) |
| - messageType | [MessageType](https://evolu.dev/docs/api-reference/common/local-first/Protocol/variables/MessageType) |
| **Request (messageType=0)** | |
| - hasWriteKey | 0 = no, 1 = yes |
| - [OwnerWriteKey](https://evolu.dev/docs/api-reference/common/local-first/variables/OwnerWriteKey) | If hasWriteKey = 1 |
| - subscriptionFlag | [SubscriptionFlags](https://evolu.dev/docs/api-reference/common/local-first/Protocol/variables/SubscriptionFlags) |
| **Response (messageType=1)** | |
| - [ProtocolErrorCode](https://evolu.dev/docs/api-reference/common/local-first/Protocol/variables/ProtocolErrorCode) | |
| **Broadcast (messageType=2)** | |
| - (no additional fields) | |
| **Messages** | |
| - [NonNegativeInt](https://evolu.dev/docs/api-reference/common/Type/variables/NonNegativeInt) | A number of messages. |
| - [EncryptedCrdtMessage](https://evolu.dev/docs/api-reference/common/local-first/interfaces/EncryptedCrdtMessage) | |
| **Ranges** | |
| - [NonNegativeInt](https://evolu.dev/docs/api-reference/common/Type/variables/NonNegativeInt) | Number of ranges. |
| - [Range](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/Range) | |
### WriteKey validation
The initiator sends a hasWriteKey flag and optionally a WriteKey. The
WriteKey is required when sending messages as a secure token proving the
initiator can write changes. It's ok to not send a WriteKey if the initiator
is only syncing (read-only) and not sending messages. The non-initiator
validates the WriteKey immediately after parsing the initiator header, before
processing any messages or ranges.
### Synchronization
- **Messages**: Sends [EncryptedCrdtMessage](https://evolu.dev/docs/api-reference/common/local-first/interfaces/EncryptedCrdtMessage)s in either direction.
- **Ranges**: Determines messages to sync. Usage varies by transport—e.g., sent
only on WebSocket connection open or with every fetch request.
Synchronization involves an initiator and a non-initiator. The **initiator**
is typically a client, and the **non-initiator** is typically a relay. Each
side processes the received message and responds with a new `ProtocolMessage`
if further sync is needed or possible, continuing until both sides are
synchronized.
The **non-initiator always responds** to provide sync completion feedback,
even with empty messages containing only the header and no error. This allows
the initiator to detect when synchronization is complete.
Both **Messages** and **Ranges** are optional, allowing each side to send,
sync, or only subscribe data as needed.
When the initiator sends data, the [OwnerWriteKey](https://evolu.dev/docs/api-reference/common/local-first/variables/OwnerWriteKey) is required as a
secure token proving the initiator can write changes. The non-initiator
responds without a [OwnerWriteKey](https://evolu.dev/docs/api-reference/common/local-first/variables/OwnerWriteKey), since the initiator’s request
already signals it wants data. If the non-initiator detects an issue, it
sends an error code via the `Error` field in the header back to the
initiator. In relay-to-relay or P2P sync, both sides may require the
[OwnerWriteKey](https://evolu.dev/docs/api-reference/common/local-first/variables/OwnerWriteKey) depending on who is the initiator.
### Protocol errors
The protocol uses error codes in the header to signal issues:
- [ProtocolWriteKeyError](https://evolu.dev/docs/api-reference/common/local-first/Protocol/interfaces/ProtocolWriteKeyError): The provided WriteKey is invalid or missing.
- [ProtocolWriteError](https://evolu.dev/docs/api-reference/common/local-first/Protocol/interfaces/ProtocolWriteError): A serious relay-side write failure occurred.
- [ProtocolQuotaError](https://evolu.dev/docs/api-reference/common/local-first/Protocol/interfaces/ProtocolQuotaError): Storage or billing quota exceeded.
- [ProtocolSyncError](https://evolu.dev/docs/api-reference/common/local-first/Protocol/interfaces/ProtocolSyncError): A serious relay-side synchronization failure
occurred.
- [ProtocolVersionError](https://evolu.dev/docs/api-reference/common/local-first/Protocol/interfaces/ProtocolVersionError): Protocol version mismatch.
- [ProtocolInvalidDataError](https://evolu.dev/docs/api-reference/common/local-first/Protocol/interfaces/ProtocolInvalidDataError): The message is malformed or corrupted.
All protocol errors except `ProtocolInvalidDataError` include the `OwnerId`
to allow clients to associate errors with the correct owner.
### Message size limit
The protocol enforces a strict maximum size for all messages, defined by
[ProtocolMessageMaxSize](https://evolu.dev/docs/api-reference/common/local-first/Protocol/variables/ProtocolMessageMaxSize). This ensures every [ProtocolMessage](https://evolu.dev/docs/api-reference/common/local-first/Protocol/type-aliases/ProtocolMessage) is
less than or equal to this limit, enabling stateless transports, simplified
relay implementation, and predictable memory usage. When all messages don't
fit within the limit, the protocol automatically continues synchronization in
subsequent rounds using range-based reconciliation.
Database mutations are limited to 640KB, which is smaller than the protocol
message limit to ensure efficient sync with
[defaultProtocolMessageRangesMaxSize](https://evolu.dev/docs/api-reference/common/local-first/Protocol/variables/defaultProtocolMessageRangesMaxSize).
### Why Binary?
The protocol avoids JSON because:
- Encrypted data doesn’t compress well, unlike plain JSON.
- Message size must be controlled during creation.
- Sequential byte reading is faster than parsing and avoids conversions.
It uses structure-aware encoding, significantly outperforming generic binary
serialization formats with the following optimizations:
- **NonNegativeInt:** Up to 33% smaller than MessagePack.
- **DateIso:** Up to 75% smaller.
- **Timestamp Encoding:** Delta encoding for milliseconds and run-length
encoding (RLE) for counters and NodeIds.
- **Small Integers (0 to 19):** Reduces size by 1 byte per integer.
To avoid reinventing serialization where it’s unnecessary—like for JSON and
certain numbers—the Evolu Protocol relies on MessagePack.
### Versioning
Evolu Protocol uses explicit versioning to ensure compatibility between
clients and relays (or peers). Each protocol message begins with a version
number and an `ownerId` in its header.
**How version negotiation works:**
- The initiator (usually a client) sends a `ProtocolMessage` that includes its
protocol version and the `ownerId`.
- The non-initiator (usually a relay or peer) checks the version.
- If the versions match, synchronization proceeds as normal.
- If the versions do not match, the non-initiator responds with a message
containing **its own protocol version and the same `ownerId`**.
- The initiator can then detect the version mismatch for that specific owner
and handle it appropriately (e.g., prompt for an update or halt sync).
Version negotiation is per-owner, allowing Evolu Protocol to evolve safely
over time and provide clear feedback about version mismatches.
### Credible exit
The protocol specification is intentionally non-configurable to ensure
universal compatibility. This design allows applications (users) to switch
between any compliant relay without negotiation or compatibility checks
beyond version matching. Relays are generic infrastructure that any
application can use interchangeably making exit from any single provider
technically feasible and economically viable.
## Interfaces
| Interface | Description |
| ----------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| [ApplyProtocolMessageAsClientOptions](https://evolu.dev/docs/api-reference/common/local-first/Protocol/interfaces/ApplyProtocolMessageAsClientOptions) | - |
| [ApplyProtocolMessageAsRelayOptions](https://evolu.dev/docs/api-reference/common/local-first/Protocol/interfaces/ApplyProtocolMessageAsRelayOptions) | - |
| [ApplyProtocolMessageAsRelayResult](https://evolu.dev/docs/api-reference/common/local-first/Protocol/interfaces/ApplyProtocolMessageAsRelayResult) | Result type for [applyProtocolMessageAsRelay](https://evolu.dev/docs/api-reference/common/local-first/Protocol/functions/applyProtocolMessageAsRelay). |
| [ProtocolInvalidDataError](https://evolu.dev/docs/api-reference/common/local-first/Protocol/interfaces/ProtocolInvalidDataError) | Error for invalid or corrupted protocol message data. |
| [ProtocolMessageBuffer](https://evolu.dev/docs/api-reference/common/local-first/Protocol/interfaces/ProtocolMessageBuffer) | Mutable builder for constructing [ProtocolMessage](https://evolu.dev/docs/api-reference/common/local-first/Protocol/type-aliases/ProtocolMessage) respecting size limits. |
| [ProtocolQuotaError](https://evolu.dev/docs/api-reference/common/local-first/Protocol/interfaces/ProtocolQuotaError) | Error when storage or billing quota is exceeded. |
| [ProtocolSyncError](https://evolu.dev/docs/api-reference/common/local-first/Protocol/interfaces/ProtocolSyncError) | Error indicating a serious relay-side synchronization failure. Clients should log this error and show a generic sync error to the user. |
| [ProtocolTimestampMismatchError](https://evolu.dev/docs/api-reference/common/local-first/Protocol/interfaces/ProtocolTimestampMismatchError) | Error when embedded timestamp doesn't match expected timestamp in EncryptedDbChange. Indicates potential tampering or corruption of CRDT messages. |
| [ProtocolVersionError](https://evolu.dev/docs/api-reference/common/local-first/Protocol/interfaces/ProtocolVersionError) | Represents a version mismatch in the Evolu Protocol. Occurs when the initiator and non-initiator are using incompatible protocol versions. |
| [ProtocolWriteError](https://evolu.dev/docs/api-reference/common/local-first/Protocol/interfaces/ProtocolWriteError) | Error indicating a serious relay-side write failure. Clients should log this error and show a generic sync error to the user. |
| [ProtocolWriteKeyError](https://evolu.dev/docs/api-reference/common/local-first/Protocol/interfaces/ProtocolWriteKeyError) | Error when a [OwnerWriteKey](https://evolu.dev/docs/api-reference/common/local-first/variables/OwnerWriteKey) is invalid, missing, or fails validation. |
| [TimestampsBuffer](https://evolu.dev/docs/api-reference/common/local-first/Protocol/interfaces/TimestampsBuffer) | - |
| [TimestampsRangeWithTimestampsBuffer](https://evolu.dev/docs/api-reference/common/local-first/Protocol/interfaces/TimestampsRangeWithTimestampsBuffer) | - |
## Type Aliases
| Type Alias | Description |
| ----------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [ApplyProtocolMessageAsClientResult](https://evolu.dev/docs/api-reference/common/local-first/Protocol/type-aliases/ApplyProtocolMessageAsClientResult) | Result type for [applyProtocolMessageAsClient](https://evolu.dev/docs/api-reference/common/local-first/Protocol/functions/applyProtocolMessageAsClient) that distinguishes between responses to client requests and broadcast messages. |
| [MessageType](https://evolu.dev/docs/api-reference/common/local-first/Protocol/type-aliases/MessageType) | - |
| [ProtocolError](https://evolu.dev/docs/api-reference/common/local-first/Protocol/type-aliases/ProtocolError) | - |
| [ProtocolMessage](https://evolu.dev/docs/api-reference/common/local-first/Protocol/type-aliases/ProtocolMessage) | Evolu Protocol Message. |
| [ProtocolMessageMaxSize](https://evolu.dev/docs/api-reference/common/local-first/Protocol/type-aliases/ProtocolMessageMaxSize) | - |
| [ProtocolMessageRangesMaxSize](https://evolu.dev/docs/api-reference/common/local-first/Protocol/type-aliases/ProtocolMessageRangesMaxSize) | - |
| [SubscriptionFlag](https://evolu.dev/docs/api-reference/common/local-first/Protocol/type-aliases/SubscriptionFlag) | - |
## Variables
| Variable | Description |
| ---------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| [decodeLength](https://evolu.dev/docs/api-reference/common/local-first/Protocol/variables/decodeLength) | - |
| [defaultProtocolMessageMaxSize](https://evolu.dev/docs/api-reference/common/local-first/Protocol/variables/defaultProtocolMessageMaxSize) | Default [ProtocolMessageMaxSize](https://evolu.dev/docs/api-reference/common/local-first/Protocol/variables/ProtocolMessageMaxSize) (1MB). |
| [defaultProtocolMessageRangesMaxSize](https://evolu.dev/docs/api-reference/common/local-first/Protocol/variables/defaultProtocolMessageRangesMaxSize) | Default [ProtocolMessageRangesMaxSize](https://evolu.dev/docs/api-reference/common/local-first/Protocol/variables/ProtocolMessageRangesMaxSize) (30KB). |
| [MessageType](https://evolu.dev/docs/api-reference/common/local-first/Protocol/variables/MessageType) | - |
| [ProtocolErrorCode](https://evolu.dev/docs/api-reference/common/local-first/Protocol/variables/ProtocolErrorCode) | - |
| [ProtocolMessageMaxSize](https://evolu.dev/docs/api-reference/common/local-first/Protocol/variables/ProtocolMessageMaxSize) | Protocol message maximum size. |
| [ProtocolMessageRangesMaxSize](https://evolu.dev/docs/api-reference/common/local-first/Protocol/variables/ProtocolMessageRangesMaxSize) | Protocol message ranges maximum size. |
| [ProtocolValueType](https://evolu.dev/docs/api-reference/common/local-first/Protocol/variables/ProtocolValueType) | - |
| [protocolVersion](https://evolu.dev/docs/api-reference/common/local-first/Protocol/variables/protocolVersion) | Evolu Protocol version. |
| [SubscriptionFlags](https://evolu.dev/docs/api-reference/common/local-first/Protocol/variables/SubscriptionFlags) | - |
## Functions
| Function | Description |
| -------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [applyProtocolMessageAsClient](https://evolu.dev/docs/api-reference/common/local-first/Protocol/functions/applyProtocolMessageAsClient) | - |
| [applyProtocolMessageAsRelay](https://evolu.dev/docs/api-reference/common/local-first/Protocol/functions/applyProtocolMessageAsRelay) | - |
| [createProtocolMessageBuffer](https://evolu.dev/docs/api-reference/common/local-first/Protocol/functions/createProtocolMessageBuffer) | - |
| [createProtocolMessageForSync](https://evolu.dev/docs/api-reference/common/local-first/Protocol/functions/createProtocolMessageForSync) | Creates a [ProtocolMessage](https://evolu.dev/docs/api-reference/common/local-first/Protocol/type-aliases/ProtocolMessage) for sync. |
| [createProtocolMessageForUnsubscribe](https://evolu.dev/docs/api-reference/common/local-first/Protocol/functions/createProtocolMessageForUnsubscribe) | - |
| [createProtocolMessageFromCrdtMessages](https://evolu.dev/docs/api-reference/common/local-first/Protocol/functions/createProtocolMessageFromCrdtMessages) | Creates a [ProtocolMessage](https://evolu.dev/docs/api-reference/common/local-first/Protocol/type-aliases/ProtocolMessage) from CRDT messages. |
| [createTimestampsBuffer](https://evolu.dev/docs/api-reference/common/local-first/Protocol/functions/createTimestampsBuffer) | - |
| [decodeFlags](https://evolu.dev/docs/api-reference/common/local-first/Protocol/functions/decodeFlags) | Decodes a byte into an array of boolean flags. |
| [decodeNodeId](https://evolu.dev/docs/api-reference/common/local-first/Protocol/functions/decodeNodeId) | - |
| [decodeNonNegativeInt](https://evolu.dev/docs/api-reference/common/local-first/Protocol/functions/decodeNonNegativeInt) | Decodes a non-negative integer from a variable-length integer format. |
| [decodeNumber](https://evolu.dev/docs/api-reference/common/local-first/Protocol/functions/decodeNumber) | - |
| [decodeProtocolMessageToJson](https://evolu.dev/docs/api-reference/common/local-first/Protocol/functions/decodeProtocolMessageToJson) | Decodes a ProtocolMessage into a readable JSON object for debugging. |
| [decodeSqliteValue](https://evolu.dev/docs/api-reference/common/local-first/Protocol/functions/decodeSqliteValue) | - |
| [decodeString](https://evolu.dev/docs/api-reference/common/local-first/Protocol/functions/decodeString) | - |
| [decryptAndDecodeDbChange](https://evolu.dev/docs/api-reference/common/local-first/Protocol/functions/decryptAndDecodeDbChange) | Decrypts and decodes an [EncryptedCrdtMessage](https://evolu.dev/docs/api-reference/common/local-first/interfaces/EncryptedCrdtMessage) using the provided owner's encryption key. Verifies that the embedded timestamp matches the expected timestamp to ensure message integrity. |
| [encodeAndEncryptDbChange](https://evolu.dev/docs/api-reference/common/local-first/Protocol/functions/encodeAndEncryptDbChange) | Encodes and encrypts a [DbChange](https://evolu.dev/docs/api-reference/common/local-first/variables/DbChange) using the provided owner's encryption key. Returns an encrypted binary representation as [EncryptedDbChange](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/EncryptedDbChange). |
| [encodeFlags](https://evolu.dev/docs/api-reference/common/local-first/Protocol/functions/encodeFlags) | Encodes an array of boolean flags into a single byte. |
| [encodeLength](https://evolu.dev/docs/api-reference/common/local-first/Protocol/functions/encodeLength) | - |
| [encodeNodeId](https://evolu.dev/docs/api-reference/common/local-first/Protocol/functions/encodeNodeId) | - |
| [encodeNonNegativeInt](https://evolu.dev/docs/api-reference/common/local-first/Protocol/functions/encodeNonNegativeInt) | Encodes a non-negative integer into a variable-length integer format. It's more efficient than encoding via [encodeNumber](https://evolu.dev/docs/api-reference/common/local-first/Protocol/functions/encodeNumber). |
| [encodeNumber](https://evolu.dev/docs/api-reference/common/local-first/Protocol/functions/encodeNumber) | Evolu uses MessagePack to handle all number variants except for NonNegativeInt. For NonNegativeInt, Evolu provides more efficient encoding. |
| [encodeSqliteValue](https://evolu.dev/docs/api-reference/common/local-first/Protocol/functions/encodeSqliteValue) | - |
| [encodeString](https://evolu.dev/docs/api-reference/common/local-first/Protocol/functions/encodeString) | - |
API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / local-first/Public
# local-first/Public
Public local-first API exported from "@evolu/common"
This module provides the supported consumer-facing API for Evolu's
local-first system: prefer importing from `@evolu/common` (this module) when
using Evolu in applications. If you require access to lower level internals,
consider importing from `@evolu/common/local-first`.
## Namespaces
| Namespace | Description |
| ---------------------------------------------------------------------------------- | ----------- |
| [kysely](https://evolu.dev/docs/api-reference/common/local-first/Public/namespaces/kysely) | - |
## Interfaces
| Interface | Description |
| --------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| [AuthenticationPrompt](https://evolu.dev/docs/api-reference/common/local-first/Public/interfaces/AuthenticationPrompt) | Configuration for the biometric/device credential prompt shown when a protected item is accessed. |
| [AuthList](https://evolu.dev/docs/api-reference/common/local-first/Public/interfaces/AuthList) | - |
| [AuthResult](https://evolu.dev/docs/api-reference/common/local-first/Public/interfaces/AuthResult) | - |
| [LocalAuth](https://evolu.dev/docs/api-reference/common/local-first/Public/interfaces/LocalAuth) | Local authentication and authorization system for Evolu. This is API is subject to change and not recommended for production use. |
| [LocalAuthDep](https://evolu.dev/docs/api-reference/common/local-first/Public/interfaces/LocalAuthDep) | - |
| [LocalAuthOptions](https://evolu.dev/docs/api-reference/common/local-first/Public/interfaces/LocalAuthOptions) | - |
| [LocalAuthOptionsValues](https://evolu.dev/docs/api-reference/common/local-first/Public/interfaces/LocalAuthOptionsValues) | - |
| [MutationResult](https://evolu.dev/docs/api-reference/common/local-first/Public/interfaces/MutationResult) | - |
| [SecureStorage](https://evolu.dev/docs/api-reference/common/local-first/Public/interfaces/SecureStorage) | Secure storage interface that must be implemented by each platform. |
| [SecureStorageDep](https://evolu.dev/docs/api-reference/common/local-first/Public/interfaces/SecureStorageDep) | - |
| [SensitiveInfoGetRequest](https://evolu.dev/docs/api-reference/common/local-first/Public/interfaces/SensitiveInfoGetRequest) | - |
| [SensitiveInfoItem](https://evolu.dev/docs/api-reference/common/local-first/Public/interfaces/SensitiveInfoItem) | - |
| [StorageMetadata](https://evolu.dev/docs/api-reference/common/local-first/Public/interfaces/StorageMetadata) | - |
## Type Aliases
| Type Alias | Description |
| ----------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| [AccessControl](https://evolu.dev/docs/api-reference/common/local-first/Public/type-aliases/AccessControl) | Enumerates the access-control policy enforced by the underlying secure storage. |
| [SecurityLevel](https://evolu.dev/docs/api-reference/common/local-first/Public/type-aliases/SecurityLevel) | Enumerates the highest security tier that was effectively applied while storing a value. |
| [StorageBackend](https://evolu.dev/docs/api-reference/common/local-first/Public/type-aliases/StorageBackend) | Enumerates the native storage backend used to persist sensitive data. |
## Variables
| Variable | Description |
| -------------------------------------------------------------------------------------------------------------- | ----------- |
| [localAuth_Namespace](https://evolu.dev/docs/api-reference/common/local-first/Public/variables/localAuth_Namespace) | - |
| [localAuthDefaultOptions](https://evolu.dev/docs/api-reference/common/local-first/Public/variables/localAuthDefaultOptions) | - |
## Functions
| Function | Description |
| ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| [createLocalAuth](https://evolu.dev/docs/api-reference/common/local-first/Public/functions/createLocalAuth) | Creates a local auth using the given secure storage implementation. This factory function allows each platform to provide its own storage layer while sharing the common auth logic. |
## AppOwner
Re-exports [AppOwner](https://evolu.dev/docs/api-reference/common/local-first/interfaces/AppOwner)
---
## AppOwnerDep
Re-exports [AppOwnerDep](https://evolu.dev/docs/api-reference/common/local-first/interfaces/AppOwnerDep)
---
## createAppOwner
Re-exports [createAppOwner](https://evolu.dev/docs/api-reference/common/local-first/functions/createAppOwner)
---
## createEvolu
Re-exports [createEvolu](https://evolu.dev/docs/api-reference/common/local-first/functions/createEvolu)
---
## createOwnerSecret
Re-exports [createOwnerSecret](https://evolu.dev/docs/api-reference/common/local-first/functions/createOwnerSecret)
---
## createOwnerWebSocketTransport
Re-exports [createOwnerWebSocketTransport](https://evolu.dev/docs/api-reference/common/local-first/functions/createOwnerWebSocketTransport)
---
## createOwnerWriteKey
Re-exports [createOwnerWriteKey](https://evolu.dev/docs/api-reference/common/local-first/functions/createOwnerWriteKey)
---
## createShardOwner
Re-exports [createShardOwner](https://evolu.dev/docs/api-reference/common/local-first/functions/createShardOwner)
---
## createSharedOwner
Re-exports [createSharedOwner](https://evolu.dev/docs/api-reference/common/local-first/functions/createSharedOwner)
---
## createSharedReadonlyOwner
Re-exports [createSharedReadonlyOwner](https://evolu.dev/docs/api-reference/common/local-first/functions/createSharedReadonlyOwner)
---
## deriveShardOwner
Re-exports [deriveShardOwner](https://evolu.dev/docs/api-reference/common/local-first/functions/deriveShardOwner)
---
## Evolu
Re-exports [Evolu](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Evolu)
---
## EvoluConfig
Re-exports [EvoluConfig](https://evolu.dev/docs/api-reference/common/local-first/interfaces/EvoluConfig)
---
## EvoluDeps
Re-exports [EvoluDeps](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/EvoluDeps)
---
## EvoluError
Re-exports [EvoluError](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/EvoluError)
---
## EvoluSchema
Re-exports [EvoluSchema](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/EvoluSchema)
---
## InferRow
Re-exports [InferRow](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/InferRow)
---
## mnemonicToOwnerSecret
Re-exports [mnemonicToOwnerSecret](https://evolu.dev/docs/api-reference/common/local-first/functions/mnemonicToOwnerSecret)
---
## NetworkError
Re-exports [NetworkError](https://evolu.dev/docs/api-reference/common/local-first/interfaces/NetworkError)
---
## Owner
Re-exports [Owner](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Owner)
---
## OwnerEncryptionKey
Re-exports [OwnerEncryptionKey](https://evolu.dev/docs/api-reference/common/local-first/variables/OwnerEncryptionKey)
---
## OwnerError
Re-exports [OwnerError](https://evolu.dev/docs/api-reference/common/local-first/interfaces/OwnerError)
---
## OwnerId
Re-exports [OwnerId](https://evolu.dev/docs/api-reference/common/local-first/variables/OwnerId)
---
## OwnerIdBytes
Re-exports [OwnerIdBytes](https://evolu.dev/docs/api-reference/common/local-first/variables/OwnerIdBytes)
---
## ownerIdBytesToOwnerId
Re-exports [ownerIdBytesToOwnerId](https://evolu.dev/docs/api-reference/common/local-first/functions/ownerIdBytesToOwnerId)
---
## ownerIdToOwnerIdBytes
Re-exports [ownerIdToOwnerIdBytes](https://evolu.dev/docs/api-reference/common/local-first/functions/ownerIdToOwnerIdBytes)
---
## OwnerSecret
Re-exports [OwnerSecret](https://evolu.dev/docs/api-reference/common/local-first/variables/OwnerSecret)
---
## ownerSecretToMnemonic
Re-exports [ownerSecretToMnemonic](https://evolu.dev/docs/api-reference/common/local-first/functions/ownerSecretToMnemonic)
---
## OwnerTransport
Re-exports [OwnerTransport](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/OwnerTransport)
---
## OwnerUsage
Re-exports [OwnerUsage](https://evolu.dev/docs/api-reference/common/local-first/interfaces/OwnerUsage)
---
## OwnerWebSocketTransport
Re-exports [OwnerWebSocketTransport](https://evolu.dev/docs/api-reference/common/local-first/interfaces/OwnerWebSocketTransport)
---
## OwnerWriteKey
Re-exports [OwnerWriteKey](https://evolu.dev/docs/api-reference/common/local-first/variables/OwnerWriteKey)
---
## ownerWriteKeyLength
Re-exports [ownerWriteKeyLength](https://evolu.dev/docs/api-reference/common/local-first/variables/ownerWriteKeyLength)
---
## parseOwnerIdFromOwnerWebSocketTransportUrl
Re-exports [parseOwnerIdFromOwnerWebSocketTransportUrl](https://evolu.dev/docs/api-reference/common/local-first/functions/parseOwnerIdFromOwnerWebSocketTransportUrl)
---
## PaymentRequiredError
Re-exports [PaymentRequiredError](https://evolu.dev/docs/api-reference/common/local-first/interfaces/PaymentRequiredError)
---
## Query
Re-exports [Query](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/Query)
---
## QueryRows
Re-exports [QueryRows](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/QueryRows)
---
## ReadonlyOwner
Re-exports [ReadonlyOwner](https://evolu.dev/docs/api-reference/common/local-first/interfaces/ReadonlyOwner)
---
## Row
Re-exports [Row](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Row)
---
## ServerError
Re-exports [ServerError](https://evolu.dev/docs/api-reference/common/local-first/interfaces/ServerError)
---
## ShardOwner
Re-exports [ShardOwner](https://evolu.dev/docs/api-reference/common/local-first/interfaces/ShardOwner)
---
## SharedOwner
Re-exports [SharedOwner](https://evolu.dev/docs/api-reference/common/local-first/interfaces/SharedOwner)
---
## SharedReadonlyOwner
Re-exports [SharedReadonlyOwner](https://evolu.dev/docs/api-reference/common/local-first/interfaces/SharedReadonlyOwner)
---
## SyncOwner
Re-exports [SyncOwner](https://evolu.dev/docs/api-reference/common/local-first/interfaces/SyncOwner)
---
## SyncState
Re-exports [SyncState](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/SyncState)
---
## SyncStateInitial
Re-exports [SyncStateInitial](https://evolu.dev/docs/api-reference/common/local-first/interfaces/SyncStateInitial)
---
## SyncStateIsNotSynced
Re-exports [SyncStateIsNotSynced](https://evolu.dev/docs/api-reference/common/local-first/interfaces/SyncStateIsNotSynced)
---
## SyncStateIsSynced
Re-exports [SyncStateIsSynced](https://evolu.dev/docs/api-reference/common/local-first/interfaces/SyncStateIsSynced)
---
## SyncStateIsSyncing
Re-exports [SyncStateIsSyncing](https://evolu.dev/docs/api-reference/common/local-first/interfaces/SyncStateIsSyncing)
---
## Timestamp
Re-exports [Timestamp](https://evolu.dev/docs/api-reference/common/local-first/variables/Timestamp)
---
## TimestampBytes
Re-exports [TimestampBytes](https://evolu.dev/docs/api-reference/common/local-first/variables/TimestampBytes)
---
## timestampBytesToTimestamp
Re-exports [timestampBytesToTimestamp](https://evolu.dev/docs/api-reference/common/local-first/functions/timestampBytesToTimestamp)
---
## TimestampCounterOverflowError
Re-exports [TimestampCounterOverflowError](https://evolu.dev/docs/api-reference/common/local-first/interfaces/TimestampCounterOverflowError)
---
## TimestampDriftError
Re-exports [TimestampDriftError](https://evolu.dev/docs/api-reference/common/local-first/interfaces/TimestampDriftError)
---
## TimestampError
Re-exports [TimestampError](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/TimestampError)
---
## TimestampTimeOutOfRangeError
Re-exports [TimestampTimeOutOfRangeError](https://evolu.dev/docs/api-reference/common/local-first/interfaces/TimestampTimeOutOfRangeError)
---
## timestampToTimestampBytes
Re-exports [timestampToTimestampBytes](https://evolu.dev/docs/api-reference/common/local-first/functions/timestampToTimestampBytes)
---
## UnuseOwner
Re-exports [UnuseOwner](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/UnuseOwner)
API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/react-native](https://evolu.dev/docs/api-reference/react-native) / exports/bare-op-sqlite
# exports/bare-op-sqlite
## Variables
| Variable | Description |
| ------------------------------------------------------------------------------------------------------------------ | ----------- |
| [evoluReactNativeDeps](https://evolu.dev/docs/api-reference/react-native/exports/bare-op-sqlite/variables/evoluReactNativeDeps) | - |
| [localAuth](https://evolu.dev/docs/api-reference/react-native/exports/bare-op-sqlite/variables/localAuth) | - |
API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/react-native](https://evolu.dev/docs/api-reference/react-native) / exports/expo-op-sqlite
# exports/expo-op-sqlite
## Variables
| Variable | Description |
| ------------------------------------------------------------------------------------------------------------------ | ----------- |
| [evoluReactNativeDeps](https://evolu.dev/docs/api-reference/react-native/exports/expo-op-sqlite/variables/evoluReactNativeDeps) | - |
| [localAuth](https://evolu.dev/docs/api-reference/react-native/exports/expo-op-sqlite/variables/localAuth) | - |
API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/react-native](https://evolu.dev/docs/api-reference/react-native) / exports/expo-sqlite
# exports/expo-sqlite
## Variables
| Variable | Description |
| --------------------------------------------------------------------------------------------------------------- | ----------- |
| [evoluReactNativeDeps](https://evolu.dev/docs/api-reference/react-native/exports/expo-sqlite/variables/evoluReactNativeDeps) | - |
| [localAuth](https://evolu.dev/docs/api-reference/react-native/exports/expo-sqlite/variables/localAuth) | - |
appendToArray - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Array](https://evolu.dev/docs/api-reference/common/Array) / appendToArray
# Function: appendToArray()
```ts
function appendToArray<T>(array, item): readonly [T, T];
```
Defined in: [packages/common/src/Array.ts:155](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Array.ts#L155)
Appends an item to an array, returning a new non-empty readonly array.
Accepts both mutable and readonly arrays. Does not mutate the original array.
### Example
```ts
appendToArray([1, 2, 3], 4); // [1, 2, 3, 4]
```
## Type Parameters
| Type Parameter |
| -------------- |
| `T` |
## Parameters
| Parameter | Type |
| --------- | -------------- |
| `array` | readonly `T`[] |
| `item` | `T` |
## Returns
readonly \[`T`, `T`\]
dedupeArray - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Array](https://evolu.dev/docs/api-reference/common/Array) / dedupeArray
# Function: dedupeArray()
Defined in: [packages/common/src/Array.ts:280](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Array.ts#L280)
Returns a new readonly array with duplicate items removed. If `by` is
provided, it will be used to derive the key for uniqueness; otherwise values
are used directly. Dedupes by reference equality of values (or extracted keys
when `by` is used).
Accepts both mutable and readonly arrays. Does not mutate the original array.
Preserves non-empty type.
### Example
```ts
// Dedupe primitives by value
dedupeArray([1, 2, 1, 3, 2]); // [1, 2, 3]
// Dedupe objects by property
dedupeArray(
[
{ id: 1, name: "Alice" },
{ id: 2, name: "Bob" },
{ id: 1, name: "Alice 2" },
],
(item) => item.id,
); // [{ id: 1, name: "Alice" }, { id: 2, name: "Bob" }]
```
### Type Parameters
| Type Parameter |
| -------------- |
| `T` |
### Parameters
| Parameter | Type |
| --------- | ------------------------------------------ |
| `array` | readonly \[`T`, `T`\] \| \[`T`, `...T[]`\] |
| `by?` | (`item`) => `unknown` |
### Returns
readonly \[`T`, `T`\]
Defined in: [packages/common/src/Array.ts:284](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Array.ts#L284)
Returns a new readonly array with duplicate items removed. If `by` is
provided, it will be used to derive the key for uniqueness; otherwise values
are used directly. Dedupes by reference equality of values (or extracted keys
when `by` is used).
Accepts both mutable and readonly arrays. Does not mutate the original array.
Preserves non-empty type.
### Example
```ts
// Dedupe primitives by value
dedupeArray([1, 2, 1, 3, 2]); // [1, 2, 3]
// Dedupe objects by property
dedupeArray(
[
{ id: 1, name: "Alice" },
{ id: 2, name: "Bob" },
{ id: 1, name: "Alice 2" },
],
(item) => item.id,
); // [{ id: 1, name: "Alice" }, { id: 2, name: "Bob" }]
```
### Type Parameters
| Type Parameter |
| -------------- |
| `T` |
### Parameters
| Parameter | Type |
| --------- | ----------------------- |
| `array` | readonly `T`[] \| `T`[] |
| `by?` | (`item`) => `unknown` |
### Returns
readonly `T`[]
filterArray - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Array](https://evolu.dev/docs/api-reference/common/Array) / filterArray
# Function: filterArray()
Defined in: [packages/common/src/Array.ts:237](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Array.ts#L237)
Filters an array using a predicate or refinement function, returning a new
readonly 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`.
### 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)
```
### Type Parameters
| Type Parameter |
| -------------- |
| `T` |
| `S` |
### Parameters
| Parameter | Type |
| ------------ | ---------------------------------------------------------------------------------------------------------- |
| `array` | readonly `T`[] |
| `refinement` | [`RefinementWithIndex`](https://evolu.dev/docs/api-reference/common/Types/type-aliases/RefinementWithIndex)\<`T`, `S`\> |
### Returns
readonly `S`[]
Defined in: [packages/common/src/Array.ts:241](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Array.ts#L241)
Filters an array using a predicate or refinement function, returning a new
readonly 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`.
### 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)
```
### Type Parameters
| Type Parameter |
| -------------- |
| `T` |
### Parameters
| Parameter | Type |
| ----------- | --------------------------------------------------------------------------------------------------- |
| `array` | readonly `T`[] |
| `predicate` | [`PredicateWithIndex`](https://evolu.dev/docs/api-reference/common/Types/type-aliases/PredicateWithIndex)\<`T`\> |
### Returns
readonly `T`[]
firstInArray - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Array](https://evolu.dev/docs/api-reference/common/Array) / firstInArray
# Function: firstInArray()
```ts
function firstInArray<T>(array): T;
```
Defined in: [packages/common/src/Array.ts:383](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Array.ts#L383)
Returns the first element of a non-empty array.
Accepts both mutable and readonly arrays. Does not mutate the original array.
### Example
```ts
firstInArray(["a", "b", "c"]); // "a"
```
## Type Parameters
| Type Parameter |
| -------------- |
| `T` |
## Parameters
| Parameter | Type |
| --------- | --------------------- |
| `array` | readonly \[`T`, `T`\] |
## Returns
`T`
isNonEmptyArray - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Array](https://evolu.dev/docs/api-reference/common/Array) / isNonEmptyArray
# Function: isNonEmptyArray()
```ts
function isNonEmptyArray<T>(array): array is [T, ...T[]];
```
Defined in: [packages/common/src/Array.ts:117](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Array.ts#L117)
Checks if an array is non-empty and narrows its type to [NonEmptyArray](https://evolu.dev/docs/api-reference/common/Array/type-aliases/NonEmptyArray).
Use `if (!isNonEmptyArray(arr))` for empty checks.
### Example
```ts
const arr: Array<number> = [1, 2, 3];
if (isNonEmptyArray(arr)) {
firstInArray(arr); // arr is NonEmptyArray<number>
}
```
## Type Parameters
| Type Parameter |
| -------------- |
| `T` |
## Parameters
| Parameter | Type |
| --------- | ----- |
| `array` | `T`[] |
## Returns
`array is [T, ...T[]]`
isNonEmptyReadonlyArray - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Array](https://evolu.dev/docs/api-reference/common/Array) / isNonEmptyReadonlyArray
# Function: isNonEmptyReadonlyArray()
```ts
function isNonEmptyReadonlyArray<T>(array): array is readonly [T, T];
```
Defined in: [packages/common/src/Array.ts:138](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Array.ts#L138)
Checks if a readonly array is non-empty and narrows its type to
[NonEmptyReadonlyArray](https://evolu.dev/docs/api-reference/common/Array/type-aliases/NonEmptyReadonlyArray).
Use `if (!isNonEmptyReadonlyArray(arr))` for empty checks.
### Example
```ts
const arr: ReadonlyArray<number> = [1, 2, 3];
if (isNonEmptyReadonlyArray(arr)) {
firstInArray(arr); // arr is NonEmptyReadonlyArray<number>
}
```
## Type Parameters
| Type Parameter |
| -------------- |
| `T` |
## Parameters
| Parameter | Type |
| --------- | -------------- |
| `array` | readonly `T`[] |
## Returns
`array is readonly [T, T]`
lastInArray - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Array](https://evolu.dev/docs/api-reference/common/Array) / lastInArray
# Function: lastInArray()
```ts
function lastInArray<T>(array): T;
```
Defined in: [packages/common/src/Array.ts:398](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Array.ts#L398)
Returns the last element of a non-empty array.
Accepts both mutable and readonly arrays. Does not mutate the original array.
### Example
```ts
lastInArray(["a", "b", "c"]); // "c"
```
## Type Parameters
| Type Parameter |
| -------------- |
| `T` |
## Parameters
| Parameter | Type |
| --------- | --------------------- |
| `array` | readonly \[`T`, `T`\] |
## Returns
`T`
mapArray - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Array](https://evolu.dev/docs/api-reference/common/Array) / mapArray
# Function: mapArray()
Defined in: [packages/common/src/Array.ts:192](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Array.ts#L192)
Maps an array using a mapper function.
Accepts both mutable and readonly arrays. Preserves non-empty type.
### Example
```ts
mapArray([1, 2, 3], (x) => x * 2); // [2, 4, 6]
```
### Type Parameters
| Type Parameter |
| -------------- |
| `T` |
| `U` |
### Parameters
| Parameter | Type |
| --------- | ------------------------------------------ |
| `array` | readonly \[`T`, `T`\] \| \[`T`, `...T[]`\] |
| `mapper` | (`item`, `index`) => `U` |
### Returns
readonly \[`U`, `U`\]
Defined in: [packages/common/src/Array.ts:196](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Array.ts#L196)
Maps an array using a mapper function.
Accepts both mutable and readonly arrays. Preserves non-empty type.
### Example
```ts
mapArray([1, 2, 3], (x) => x * 2); // [2, 4, 6]
```
### Type Parameters
| Type Parameter |
| -------------- |
| `T` |
| `U` |
### Parameters
| Parameter | Type |
| --------- | ------------------------ |
| `array` | readonly `T`[] \| `T`[] |
| `mapper` | (`item`, `index`) => `U` |
### Returns
readonly `U`[]
partitionArray - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Array](https://evolu.dev/docs/api-reference/common/Array) / partitionArray
# Function: partitionArray()
Defined in: [packages/common/src/Array.ts:344](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Array.ts#L344)
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>)
```
### Type Parameters
| Type Parameter |
| -------------- |
| `T` |
| `S` |
### Parameters
| Parameter | Type |
| ------------ | ---------------------------------------------------------------------------------------------------------- |
| `array` | readonly `T`[] |
| `refinement` | [`RefinementWithIndex`](https://evolu.dev/docs/api-reference/common/Types/type-aliases/RefinementWithIndex)\<`T`, `S`\> |
### Returns
readonly \[readonly `S`[], readonly `Exclude`\<`T`, `S`\>[]\]
Defined in: [packages/common/src/Array.ts:348](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Array.ts#L348)
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>)
```
### Type Parameters
| Type Parameter |
| -------------- |
| `T` |
### Parameters
| Parameter | Type |
| ----------- | --------------------------------------------------------------------------------------------------- |
| `array` | readonly `T`[] |
| `predicate` | [`PredicateWithIndex`](https://evolu.dev/docs/api-reference/common/Types/type-aliases/PredicateWithIndex)\<`T`\> |
### Returns
readonly \[readonly `T`[], readonly `T`[]\]
popArray - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Array](https://evolu.dev/docs/api-reference/common/Array) / popArray
# Function: popArray()
```ts
function popArray<T>(array): T;
```
Defined in: [packages/common/src/Array.ts:433](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Array.ts#L433)
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]
```
## Type Parameters
| Type Parameter |
| -------------- |
| `T` |
## Parameters
| Parameter | Type |
| --------- | ----------------- |
| `array` | \[`T`, `...T[]`\] |
## Returns
`T`
prependToArray - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Array](https://evolu.dev/docs/api-reference/common/Array) / prependToArray
# Function: prependToArray()
```ts
function prependToArray<T>(array, item): readonly [T, T];
```
Defined in: [packages/common/src/Array.ts:174](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Array.ts#L174)
Prepends an item to an array, returning a new non-empty readonly array.
Accepts both mutable and readonly arrays. Does not mutate the original array.
### Example
```ts
prependToArray([2, 3], 1); // [1, 2, 3]
```
## Type Parameters
| Type Parameter |
| -------------- |
| `T` |
## Parameters
| Parameter | Type |
| --------- | -------------- |
| `array` | readonly `T`[] |
| `item` | `T` |
## Returns
readonly \[`T`, `T`\]
shiftArray - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Array](https://evolu.dev/docs/api-reference/common/Array) / shiftArray
# Function: shiftArray()
```ts
function shiftArray<T>(array): T;
```
Defined in: [packages/common/src/Array.ts:416](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Array.ts#L416)
Shifts 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];
shiftArray(arr); // 1
arr; // [2, 3]
```
## Type Parameters
| Type Parameter |
| -------------- |
| `T` |
## Parameters
| Parameter | Type |
| --------- | ----------------- |
| `array` | \[`T`, `...T[]`\] |
## Returns
`T`
NonEmptyArray - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Array](https://evolu.dev/docs/api-reference/common/Array) / NonEmptyArray
# Type Alias: NonEmptyArray\<T\>
```ts
type NonEmptyArray<T> = [T, ...T[]];
```
Defined in: [packages/common/src/Array.ts:92](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Array.ts#L92)
An array with at least one element.
## Type Parameters
| Type Parameter |
| -------------- |
| `T` |
NonEmptyReadonlyArray - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Array](https://evolu.dev/docs/api-reference/common/Array) / NonEmptyReadonlyArray
# Type Alias: NonEmptyReadonlyArray\<T\>
```ts
type NonEmptyReadonlyArray<T> = readonly [T, ...ReadonlyArray<T>];
```
Defined in: [packages/common/src/Array.ts:99](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Array.ts#L99)
A readonly array with at least one element.
## Type Parameters
| Type Parameter |
| -------------- |
| `T` |
assert - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Assert](https://evolu.dev/docs/api-reference/common/Assert) / assert
# Variable: assert()
```ts
const assert: (condition, message) => asserts condition;
```
Defined in: [packages/common/src/Assert.ts:29](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Assert.ts#L29)
Ensures a condition is true, throwing an error with the provided message if
not.
Prevents 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 [Type](https://evolu.dev/docs/api-reference/common/Type/interfaces/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).
### Example
```ts
assert(true, "true is not true"); // no-op
assert(false, "true is not true"); // throws Error
const length = buffer.getLength();
// We know length is logically non-negative, but TypeScript doesn't
assert(NonNegativeInt.is(length), "buffer length should be non-negative");
```
## Parameters
| Parameter | Type |
| ----------- | --------- |
| `condition` | `unknown` |
| `message` | `string` |
## Returns
`asserts condition`
assertNonEmptyArray - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Assert](https://evolu.dev/docs/api-reference/common/Assert) / assertNonEmptyArray
# Variable: assertNonEmptyArray()
```ts
const assertNonEmptyArray: <T>(arr, message?) => asserts arr is [T, ...T[]];
```
Defined in: [packages/common/src/Assert.ts:52](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Assert.ts#L52)
Asserts that an array is non-empty.
Ensures the provided array has at least one element, helping TypeScript infer
the array as non-empty when this is logically guaranteed but not statically
known.
### Example
```ts
assertNonEmptyArray([1, 2, 3]); // no-op
assertNonEmptyArray([]); // throws Error
```
## Type Parameters
| Type Parameter |
| -------------- |
| `T` |
## Parameters
| Parameter | Type |
| ---------- | -------- |
| `arr` | `T`[] |
| `message?` | `string` |
## Returns
`asserts arr is [T, ...T[]]`
assertNonEmptyReadonlyArray - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Assert](https://evolu.dev/docs/api-reference/common/Assert) / assertNonEmptyReadonlyArray
# Variable: assertNonEmptyReadonlyArray()
```ts
const assertNonEmptyReadonlyArray: <T>(
arr,
message?,
) => asserts arr is readonly [T, ...T[]];
```
Defined in: [packages/common/src/Assert.ts:76](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Assert.ts#L76)
Asserts that a readonly array is non-empty.
Ensures the provided readonly array has at least one element, helping
TypeScript infer non-emptiness when this is logically guaranteed but not
statically known.
### Example
```ts
assertNonEmptyReadonlyArray([1, 2, 3]); // no-op
assertNonEmptyReadonlyArray([]); // throws Error
```
## Type Parameters
| Type Parameter |
| -------------- |
| `T` |
## Parameters
| Parameter | Type |
| ---------- | ---------------------- |
| `arr` | `ReadonlyArray`\<`T`\> |
| `message?` | `string` |
## Returns
`asserts arr is readonly [T, ...T[]]`
clampBigInt - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [BigInt](https://evolu.dev/docs/api-reference/common/BigInt) / clampBigInt
# Function: clampBigInt()
```ts
function clampBigInt(min, max): (n) => bigint;
```
Defined in: [packages/common/src/BigInt.ts:11](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/BigInt.ts#L11)
Clamps a bigint within a given range.
## Parameters
| Parameter | Type |
| --------- | -------- |
| `min` | `bigint` |
| `max` | `bigint` |
## Returns
```ts
(n): bigint;
```
### Parameters
| Parameter | Type |
| --------- | -------- |
| `n` | `bigint` |
### Returns
`bigint`
decrementBigInt - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [BigInt](https://evolu.dev/docs/api-reference/common/BigInt) / decrementBigInt
# Function: decrementBigInt()
```ts
function decrementBigInt(n): bigint;
```
Defined in: [packages/common/src/BigInt.ts:7](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/BigInt.ts#L7)
Decrements a bigint by 1.
## Parameters
| Parameter | Type |
| --------- | -------- |
| `n` | `bigint` |
## Returns
`bigint`
incrementBigInt - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [BigInt](https://evolu.dev/docs/api-reference/common/BigInt) / incrementBigInt
# Function: incrementBigInt()
```ts
function incrementBigInt(n): bigint;
```
Defined in: [packages/common/src/BigInt.ts:4](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/BigInt.ts#L4)
Increments a bigint by 1.
## Parameters
| Parameter | Type |
| --------- | -------- |
| `n` | `bigint` |
## Returns
`bigint`
isBetweenBigInt - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [BigInt](https://evolu.dev/docs/api-reference/common/BigInt) / isBetweenBigInt
# Function: isBetweenBigInt()
```ts
function isBetweenBigInt(min, max): Predicate<bigint>;
```
Defined in: [packages/common/src/BigInt.ts:27](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/BigInt.ts#L27)
Creates a predicate that checks if a BigInt is within a range, inclusive.
### Example
```ts
const isBetween10And20 = isBetweenBigInt(10n, 20n);
console.log(isBetween10And20(15n)); // true
console.log(isBetween10And20(25n)); // false
```
## Parameters
| Parameter | Type |
| --------- | -------- |
| `min` | `bigint` |
| `max` | `bigint` |
## Returns
[`Predicate`](https://evolu.dev/docs/api-reference/common/Types/type-aliases/Predicate)\<`bigint`\>
Brand - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Brand](https://evolu.dev/docs/api-reference/common/Brand) / Brand
# Interface: Brand\<B\>
Defined in: [packages/common/src/Brand.ts:59](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Brand.ts#L59)
A utility interface for creating branded types.
Branded types enhance type safety by differentiating otherwise identical base
types, such as `number` or `string`, to enforce stricter type checks.
Supports multiple brands, allowing types to act like flags.
### Example 1: Single Brand
```ts
// A branded type definition
type UserId = number & Brand<"UserId">;
// A function that creates `UserId` values.
// Casting with `as UserId` is unsafe, so `createUserId` must be unit-tested.
const createUserId = (): UserId => {
return 123 as UserId; // Unsafe casting
};
const userId = createUserId();
// A function that accepts only `UserId`.
const getUser = (id: UserId) => {
// Implementation
};
getUser(userId); // ✅ Valid
getUser(123); // ❌ TypeScript error
getUser("123"); // ❌ TypeScript error
```
### Example 2: Multiple Brands
```ts
// Define branded types
type Min1 = string & Brand<"Min1">;
type Max100 = string & Brand<"Max100">;
type Min1Max100 = string & Brand<"Min1" | "Max100">;
// Functions requiring specific brands
const requiresMin1 = (value: Min1): void => {};
const requiresMax100 = (value: Max100): void => {};
// Values with single brands
const min1Value: Min1 = "hello" as Min1;
const max100Value: Max100 = "world" as Max100;
// Value with multiple brands
const min1Max100Value: Min1Max100 = "typescript" as Min1Max100;
// Valid cases
requiresMin1(min1Value); // ✅ Valid
requiresMax100(max100Value); // ✅ Valid
requiresMin1(min1Max100Value); // ✅ Valid: Min1Max100 satisfies Min1
requiresMax100(min1Max100Value); // ✅ Valid: Min1Max100 satisfies Max100
```
## Extended by
- [`Redacted`](https://evolu.dev/docs/api-reference/common/Redacted/interfaces/Redacted)
## Type Parameters
| Type Parameter |
| ---------------------- |
| `B` _extends_ `string` |
## Properties
| Property | Modifier | Type | Defined in |
| ---------------------------------- | ---------- | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="___brand"></a> `[___brand]` | `readonly` | `Readonly`\<`Record`\<`B`, `true`\>\> | [packages/common/src/Brand.ts:60](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Brand.ts#L60) |
IsBranded - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Brand](https://evolu.dev/docs/api-reference/common/Brand) / IsBranded
# Type Alias: IsBranded\<T\>
```ts
type IsBranded<T> = T extends Brand<string> ? true : false;
```
Defined in: [packages/common/src/Brand.ts:75](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Brand.ts#L75)
Determines whether a type `T` is a branded type.
Works with any base type intersected with a `Brand`.
### Example
- `IsBranded<string>` -> false
- `IsBranded<string & Brand<"X">>` -> true
## Type Parameters
| Type Parameter |
| -------------- |
| `T` |
BufferError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Buffer](https://evolu.dev/docs/api-reference/common/Buffer) / BufferError
# Class: BufferError
Defined in: [packages/common/src/Buffer.ts:15](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Buffer.ts#L15)
Custom error for [Buffer](https://evolu.dev/docs/api-reference/common/Buffer/interfaces/Buffer)-related failures like premature end of data.
Provides better stack traces for debugging binary protocol issues.
## Extends
- `Error`
## Constructors
### Constructor
```ts
new BufferError(message): BufferError;
```
Defined in: [packages/common/src/Buffer.ts:16](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Buffer.ts#L16)
#### Parameters
| Parameter | Type |
| --------- | -------- |
| `message` | `string` |
#### Returns
`BufferError`
#### Overrides
```ts
Error.constructor;
```
## Properties
| Property | Modifier | Type | Description | Inherited from | Defined in |
| ---------------------------------------------- | -------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- | ---------------------------------------------------- |
| <a id="cause"></a> `cause?` | `public` | `unknown` | - | `Error.cause` | node_modules/typescript/lib/lib.es2022.error.d.ts:26 |
| <a id="message"></a> `message` | `public` | `string` | - | `Error.message` | node_modules/typescript/lib/lib.es5.d.ts:1077 |
| <a id="name"></a> `name` | `public` | `string` | - | `Error.name` | node_modules/typescript/lib/lib.es5.d.ts:1076 |
| <a id="stack"></a> `stack?` | `public` | `string` | - | `Error.stack` | node_modules/typescript/lib/lib.es5.d.ts:1078 |
| <a id="stacktracelimit"></a> `stackTraceLimit` | `static` | `number` | The `Error.stackTraceLimit` property specifies the number of stack frames collected by a stack trace (whether generated by `new Error().stack` or `Error.captureStackTrace(obj)`). The default value is `10` but may be set to any valid JavaScript number. Changes will affect any stack trace captured _after_ the value has been changed. If set to a non-number value, or set to a negative number, stack traces will not capture any frames. | `Error.stackTraceLimit` | node_modules/@types/node/globals.d.ts:68 |
## Methods
### captureStackTrace()
```ts
static captureStackTrace(targetObject, constructorOpt?): void;
```
Defined in: node_modules/@types/node/globals.d.ts:52
Creates a `.stack` property on `targetObject`, which when accessed returns
a string representing the location in the code at which
`Error.captureStackTrace()` was called.
```js
const myObject = {};
Error.captureStackTrace(myObject);
myObject.stack; // Similar to `new Error().stack`
```
The first line of the trace will be prefixed with
`${myObject.name}: ${myObject.message}`.
The optional `constructorOpt` argument accepts a function. If given, all frames
above `constructorOpt`, including `constructorOpt`, will be omitted from the
generated stack trace.
The `constructorOpt` argument is useful for hiding implementation
details of error generation from the user. For instance:
```js
function a() {
b();
}
function b() {
c();
}
function c() {
// Create an error without stack trace to avoid calculating the stack trace twice.
const { stackTraceLimit } = Error;
Error.stackTraceLimit = 0;
const error = new Error();
Error.stackTraceLimit = stackTraceLimit;
// Capture the stack trace above function b
Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace
throw error;
}
a();
```
#### Parameters
| Parameter | Type |
| ----------------- | ---------- |
| `targetObject` | `object` |
| `constructorOpt?` | `Function` |
#### Returns
`void`
#### Inherited from
```ts
Error.captureStackTrace;
```
---
### isError()
```ts
static isError(error): error is Error;
```
Defined in: node_modules/typescript/lib/lib.esnext.error.d.ts:23
Indicates whether the argument provided is a built-in Error instance or not.
#### Parameters
| Parameter | Type |
| --------- | --------- |
| `error` | `unknown` |
#### Returns
`error is Error`
#### Inherited from
```ts
Error.isError;
```
---
### prepareStackTrace()
```ts
static prepareStackTrace(err, stackTraces): any;
```
Defined in: node_modules/@types/node/globals.d.ts:56
#### Parameters
| Parameter | Type |
| ------------- | ------------ |
| `err` | `Error` |
| `stackTraces` | `CallSite`[] |
#### Returns
`any`
#### See
https://v8.dev/docs/stack-trace-api#customizing-stack-traces
#### Inherited from
```ts
Error.prepareStackTrace;
```
bytesToHex - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Buffer](https://evolu.dev/docs/api-reference/common/Buffer) / bytesToHex
# Function: bytesToHex()
```ts
function bytesToHex(bytes): string;
```
Defined in: node_modules/@noble/ciphers/utils.d.ts:40
Convert byte array to hex string. Uses built-in function, when available.
## Parameters
| Parameter | Type |
| --------- | ------------ |
| `bytes` | `Uint8Array` |
## Returns
`string`
## Example
```ts
bytesToHex(Uint8Array.from([0xca, 0xfe, 0x01, 0x23])); // 'cafe0123'
```
bytesToUtf8 - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Buffer](https://evolu.dev/docs/api-reference/common/Buffer) / bytesToUtf8
# Function: bytesToUtf8()
```ts
function bytesToUtf8(bytes): string;
```
Defined in: node_modules/@noble/ciphers/utils.d.ts:58
Converts bytes to string using UTF8 encoding.
## Parameters
| Parameter | Type |
| --------- | ------------ |
| `bytes` | `Uint8Array` |
## Returns
`string`
## Example
```ts
bytesToUtf8(new Uint8Array([97, 98, 99])); // 'abc'
```
concatBytes - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Buffer](https://evolu.dev/docs/api-reference/common/Buffer) / concatBytes
# Function: concatBytes()
```ts
function concatBytes(...arrays): Uint8Array;
```
Defined in: node_modules/@noble/ciphers/utils.d.ts:72
Copies several Uint8Arrays into one.
## Parameters
| Parameter | Type |
| ----------- | ----------------------------------- |
| ...`arrays` | `Uint8Array`\<`ArrayBufferLike`\>[] |
## Returns
`Uint8Array`
createBuffer - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Buffer](https://evolu.dev/docs/api-reference/common/Buffer) / createBuffer
# Function: createBuffer()
```ts
function createBuffer(arrayLike?): Buffer;
```
Defined in: [packages/common/src/Buffer.ts:114](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Buffer.ts#L114)
Creates a [Buffer](https://evolu.dev/docs/api-reference/common/Buffer/interfaces/Buffer) for efficient byte operations.
## Parameters
| Parameter | Type |
| ------------ | ------------------------------------------------------------ |
| `arrayLike?` | `Uint8Array`\<`ArrayBufferLike`\> \| `ArrayLike`\<`number`\> |
## Returns
[`Buffer`](https://evolu.dev/docs/api-reference/common/Buffer/interfaces/Buffer)
hexToBytes - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Buffer](https://evolu.dev/docs/api-reference/common/Buffer) / hexToBytes
# Function: hexToBytes()
```ts
function hexToBytes(hex): Uint8Array;
```
Defined in: node_modules/@noble/ciphers/utils.d.ts:45
Convert hex string to byte array. Uses built-in function, when available.
## Parameters
| Parameter | Type |
| --------- | -------- |
| `hex` | `string` |
## Returns
`Uint8Array`
## Example
```ts
hexToBytes("cafe0123"); // Uint8Array.from([0xca, 0xfe, 0x01, 0x23])
```
utf8ToBytes - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Buffer](https://evolu.dev/docs/api-reference/common/Buffer) / utf8ToBytes
# Function: utf8ToBytes()
```ts
function utf8ToBytes(str): Uint8Array;
```
Defined in: node_modules/@noble/ciphers/utils.d.ts:53
Converts string to bytes using UTF8 encoding.
## Parameters
| Parameter | Type |
| --------- | -------- |
| `str` | `string` |
## Returns
`Uint8Array`
## Example
```ts
utf8ToBytes("abc"); // new Uint8Array([97, 98, 99])
```
Buffer - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Buffer](https://evolu.dev/docs/api-reference/common/Buffer) / Buffer
# Interface: Buffer
Defined in: [packages/common/src/Buffer.ts:65](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Buffer.ts#L65)
A Buffer is a dynamic, resizable container for binary data, optimized for
scenarios where the final size is unknown. It grows exponentially (doubling
its capacity) to minimize memory reallocations and uses `subarray` for
efficient, copy-free data access in methods like `unwrap` and `shift`.
### Recommended Usage
Create as few Buffers as possible—typically one main Buffer for the final
output. Temporary Buffers are allowed when necessary (e.g., for
variable-length headers), but avoid excessive allocations. Buffers can be
reused within functions by leveraging `reset` to clear contents while
preserving capacity, or `truncate` to adjust the length to a specific size,
reducing the need for new allocations. Pass Buffers to `encode*` functions to
append serialized data and use `decode*` functions to extract data. Both
`shift` and `shiftN` throw an [BufferError](https://evolu.dev/docs/api-reference/common/Buffer/classes/BufferError) with message "Buffer parse
ended prematurely" on failure, as do higher-level `decode*` functions,
providing stack traces for debugging instead of using [Result](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result). This
avoids allocation overhead in success cases and leverages exceptions'
diagnostic benefits.
### Example
```ts
const buffer = createBuffer();
encodeNonNegativeInt(buffer, someInt);
encodeId(buffer, someId);
const result = buffer.unwrap(); // Final serialized data
// Decoding example (throws on error)
try {
const num = decodeNonNegativeInt(buffer);
const id = decodeId(buffer);
} catch (e) {
console.error(e.stack); // Stack trace for debugging
}
```
For more on exponential growth, see:
https://blog.mozilla.org/nnethercote/2014/11/04/please-grow-your-buffers-exponentially
## Properties
| Property | Type | Description | Defined in |
| -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| <a id="extend"></a> `extend` | (`arg`) => `void` | Appends binary data to the buffer, resizing if necessary. Throws if `arg.length` is not a non-negative integer. | [packages/common/src/Buffer.ts:76](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Buffer.ts#L76) |
| <a id="getcapacity"></a> `getCapacity` | () => `number` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Int"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"NonNegative"`\> | Returns the current capacity of the buffer. | [packages/common/src/Buffer.ts:67](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Buffer.ts#L67) |
| <a id="getlength"></a> `getLength` | () => `number` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Int"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"NonNegative"`\> | Returns the current number of bytes stored in the buffer. | [packages/common/src/Buffer.ts:70](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Buffer.ts#L70) |
| <a id="reset"></a> `reset` | () => `void` | Resets the buffer to its initial empty state, preserving its capacity. This allows efficient buffer reuse without reallocating memory. Use this when you want to clear the buffer and write new data, avoiding unnecessary allocations. | [packages/common/src/Buffer.ts:103](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Buffer.ts#L103) |
| <a id="shift"></a> `shift` | () => `number` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Int"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"NonNegative"`\> | Removes and returns the first byte. Throws an `Error` with message "Buffer parse ended prematurely" if the buffer is empty. | [packages/common/src/Buffer.ts:82](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Buffer.ts#L82) |
| <a id="shiftn"></a> `shiftN` | (`n`) => `Uint8Array` | Removes and returns the first `n` bytes. Throws an `Error` with message "Buffer parse ended prematurely" if fewer than `n` bytes remain. | [packages/common/src/Buffer.ts:88](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Buffer.ts#L88) |
| <a id="truncate"></a> `truncate` | (`length`) => `void` | Truncates the buffer to the specified length, discarding data from the end. Throws if the new length is greater than the current length. | [packages/common/src/Buffer.ts:94](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Buffer.ts#L94) |
| <a id="unwrap"></a> `unwrap` | () => `Uint8Array` | Returns a view of the buffer’s current data. Do not modify this array, as it directly alters the buffer’s internal state, potentially breaking subsequent operations. | [packages/common/src/Buffer.ts:110](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Buffer.ts#L110) |
createLruCache - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Cache](https://evolu.dev/docs/api-reference/common/Cache) / createLruCache
# Function: createLruCache()
```ts
function createLruCache<K, V>(capacity): Cache<K, V>;
```
Defined in: [packages/common/src/Cache.ts:44](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Cache.ts#L44)
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.
### Example
```ts
const cache = createLruCache<string, number>(2);
cache.set("a", 1);
cache.set("b", 2);
cache.set("c", 3); // Evicts "a"
cache.has("a"); // false
```
## Type Parameters
| Type Parameter |
| -------------- |
| `K` |
| `V` |
## Parameters
| Parameter | Type |
| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `capacity` | `number` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Int"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"NonNegative"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Positive"`\> |
## Returns
[`Cache`](https://evolu.dev/docs/api-reference/common/Cache/interfaces/Cache)\<`K`, `V`\>
Cache - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Cache](https://evolu.dev/docs/api-reference/common/Cache) / Cache
# Interface: Cache\<K, V\>
Defined in: [packages/common/src/Cache.ts:11](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Cache.ts#L11)
Generic cache interface providing basic key-value storage operations.
Keys are compared by reference (standard Map semantics).
Note: Cache does not extend Map because eviction policies (like in LRU)
violate the Liskov Substitution Principle.
## Type Parameters
| Type Parameter |
| -------------- |
| `K` |
| `V` |
## Properties
| Property | Modifier | Type | Description | Defined in |
| ---------------------------- | ---------- | ----------------------------- | ----------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="delete"></a> `delete` | `public` | (`key`) => `void` | Removes a key from the cache. | [packages/common/src/Cache.ts:22](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Cache.ts#L22) |
| <a id="get"></a> `get` | `public` | (`key`) => `V` \| `undefined` | Retrieves the value for a key, or undefined if not present. | [packages/common/src/Cache.ts:16](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Cache.ts#L16) |
| <a id="has"></a> `has` | `public` | (`key`) => `boolean` | Checks if a key exists in the cache. | [packages/common/src/Cache.ts:13](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Cache.ts#L13) |
| <a id="map"></a> `map` | `readonly` | `ReadonlyMap`\<`K`, `V`\> | Returns a readonly view of the internal Map. | [packages/common/src/Cache.ts:25](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Cache.ts#L25) |
| <a id="set"></a> `set` | `public` | (`key`, `val`) => `void` | Stores a key-value pair in the cache. | [packages/common/src/Cache.ts:19](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Cache.ts#L19) |
createCallbacks - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Callbacks](https://evolu.dev/docs/api-reference/common/Callbacks) / createCallbacks
# Function: createCallbacks()
```ts
function createCallbacks<T>(deps): Callbacks<T>;
```
Defined in: [packages/common/src/Callbacks.ts:59](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Callbacks.ts#L59)
Creates a [Callbacks](https://evolu.dev/docs/api-reference/common/Callbacks/interfaces/Callbacks) registry for managing callbacks.
## Type Parameters
| Type Parameter | Default type |
| -------------- | ------------ |
| `T` | `undefined` |
## Parameters
| Parameter | Type |
| --------- | ----------------------------------------------------------------------------------- |
| `deps` | [`RandomBytesDep`](https://evolu.dev/docs/api-reference/common/Crypto/interfaces/RandomBytesDep) |
## Returns
[`Callbacks`](https://evolu.dev/docs/api-reference/common/Callbacks/interfaces/Callbacks)\<`T`\>
Callbacks - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Callbacks](https://evolu.dev/docs/api-reference/common/Callbacks) / Callbacks
# Interface: Callbacks\<T\>
Defined in: [packages/common/src/Callbacks.ts:45](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Callbacks.ts#L45)
Request-response correlation for callbacks across boundaries.
Stores callbacks with unique IDs and executes them once with an optional
argument. Executed callbacks are automatically removed.
This is useful for correlating asynchronous request-response operations
across boundaries where callback functions cannot be passed directly (e.g.,
web workers, message queues).
The `execute` method intentionally does not use try-catch or [Result](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result)
because it's the callback's responsibility to handle its own errors.
### Example
```ts
// No-argument callbacks
const callbacks = createCallbacks(deps);
const id = callbacks.register(() => console.log("called"));
callbacks.execute(id);
// With argument callbacks
const stringCallbacks = createCallbacks<string>(deps);
const id = stringCallbacks.register((value) => {
console.log(value);
});
stringCallbacks.execute(id, "hello");
// Promise.withResolvers pattern
const promiseCallbacks = createCallbacks<string>(deps);
const { promise, resolve } = Promise.withResolvers<string>();
const id = promiseCallbacks.register(resolve);
promiseCallbacks.execute(id, "resolved value");
await promise; // "resolved value"
```
## Type Parameters
| Type Parameter | Default type | Description |
| -------------- | ------------ | ------------------------------------------------------------------------------------------ |
| `T` | `undefined` | The type of argument passed to callbacks (defaults to undefined for no-argument callbacks) |
## Properties
| Property | Modifier | Type | Description | Defined in |
| -------------------------------- | ---------- | ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="execute"></a> `execute` | `readonly` | `T` _extends_ `undefined` ? (`id`) => `undefined` : (`id`, `arg`) => `undefined` | Executes and removes a callback associated with the given ID. | [packages/common/src/Callbacks.ts:50](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Callbacks.ts#L50) |
| <a id="register"></a> `register` | `readonly` | (`callback`) => [`CallbackId`](https://evolu.dev/docs/api-reference/common/Callbacks/type-aliases/CallbackId) | Registers a callback function and returns a unique ID. | [packages/common/src/Callbacks.ts:47](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Callbacks.ts#L47) |
CallbackId - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Callbacks](https://evolu.dev/docs/api-reference/common/Callbacks) / CallbackId
# Type Alias: CallbackId
```ts
type CallbackId = Id & Brand<"Callback">;
```
Defined in: [packages/common/src/Callbacks.ts:56](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Callbacks.ts#L56)
Unique identifier for a callback in [Callbacks](https://evolu.dev/docs/api-reference/common/Callbacks/interfaces/Callbacks).
createConsole - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Console](https://evolu.dev/docs/api-reference/common/Console) / createConsole
# Function: createConsole()
```ts
function createConsole(config): Console;
```
Defined in: [packages/common/src/Console.ts:100](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Console.ts#L100)
Creates a [Console](https://evolu.dev/docs/api-reference/common/Console/interfaces/Console) for logging with configurable output.
## Parameters
| Parameter | Type |
| --------- | ---------------------------------------------------------------------------------- |
| `config` | [`ConsoleConfig`](https://evolu.dev/docs/api-reference/common/Console/interfaces/ConsoleConfig) |
## Returns
[`Console`](https://evolu.dev/docs/api-reference/common/Console/interfaces/Console)
createConsoleWithTime - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Console](https://evolu.dev/docs/api-reference/common/Console) / createConsoleWithTime
# Function: createConsoleWithTime()
```ts
function createConsoleWithTime(config): Console;
```
Defined in: [packages/common/src/Console.ts:177](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Console.ts#L177)
Creates a console instance with timestamp prefixes.
## Parameters
| Parameter | Type |
| --------- | -------------------------------------------------------------------------------------------------- |
| `config` | [`ConsoleWithTimeConfig`](https://evolu.dev/docs/api-reference/common/Console/interfaces/ConsoleWithTimeConfig) |
## Returns
[`Console`](https://evolu.dev/docs/api-reference/common/Console/interfaces/Console)
Console - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Console](https://evolu.dev/docs/api-reference/common/Console) / Console
# Interface: Console
Defined in: [packages/common/src/Console.ts:37](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Console.ts#L37)
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
these environments and expected to remain compatible in future versions.
Output formatting may vary (e.g., interactive UI in browsers vs. text in
Node.js/React Native), but functionality is consistent across platforms.
**Convention**: Use a tag (e.g., `[db]`) as the first argument for log
filtering.
### Example
```ts
deps.console.log("[evolu]", "createEvoluInstance", { name });
```
**Tip**: In browser dev tools, you can filter logs by tag (e.g., `[db]`) to
quickly find relevant messages. In Node.js, use `grep` to filter output:
```bash
node app.js | grep "\[relay\]" # Show only relay logs
node app.js | grep -E "\[db\]|\[sql\]" # Show db and sql logs
node app.js | grep -v "\[debug\]" # Hide debug logs
```
Or add to package.json scripts:
```json
{
"scripts": {
"dev:relay": "node app.js | grep \"\\[relay\\]\"",
"dev:db": "node app.js | grep -E \"\\[db\\]|\\[sql\\]\""
}
}
```
## Properties
| Property | Type | Description | Defined in |
| ------------------------------------ | ---------------------------------------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| <a id="assert"></a> `assert` | (`value`, `message?`, ...`optionalParams`) => `void` | Writes a message if the value is falsy, otherwise does nothing | [packages/common/src/Console.ts:78](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Console.ts#L78) |
| <a id="count"></a> `count` | (`label?`) => `void` | Logs the number of times this has been called with the given label | [packages/common/src/Console.ts:72](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Console.ts#L72) |
| <a id="countreset"></a> `countReset` | (`label?`) => `void` | Resets the counter for the given label | [packages/common/src/Console.ts:75](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Console.ts#L75) |
| <a id="debug"></a> `debug` | (...`args`) => `void` | Outputs a debug message | [packages/common/src/Console.ts:54](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Console.ts#L54) |
| <a id="dir"></a> `dir` | (`object`, `options?`) => `void` | Displays an object's properties in a detailed format | [packages/common/src/Console.ts:66](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Console.ts#L66) |
| <a id="enabled"></a> `enabled?` | `boolean` | Controls whether console methods produce output (default: true) | [packages/common/src/Console.ts:39](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Console.ts#L39) |
| <a id="error"></a> `error` | (...`args`) => `void` | Outputs an error message | [packages/common/src/Console.ts:51](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Console.ts#L51) |
| <a id="info"></a> `info` | (...`args`) => `void` | Outputs an informational message (often same as log) | [packages/common/src/Console.ts:45](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Console.ts#L45) |
| <a id="log"></a> `log` | (...`args`) => `void` | Outputs a message to the console | [packages/common/src/Console.ts:42](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Console.ts#L42) |
| <a id="table"></a> `table` | (`tabularData`, `properties?`) => `void` | Displays tabular data as a table | [packages/common/src/Console.ts:69](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Console.ts#L69) |
| <a id="time"></a> `time` | (`label?`) => `void` | Starts a timer with an optional label | [packages/common/src/Console.ts:57](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Console.ts#L57) |
| <a id="timeend"></a> `timeEnd` | (`label?`) => `void` | Ends a timer and logs the elapsed time | [packages/common/src/Console.ts:63](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Console.ts#L63) |
| <a id="timelog"></a> `timeLog` | (`label?`, ...`data`) => `void` | Logs the elapsed time for a timer without ending it | [packages/common/src/Console.ts:60](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Console.ts#L60) |
| <a id="trace"></a> `trace` | (`message?`, ...`optionalParams`) => `void` | Prints a stack trace with an optional message | [packages/common/src/Console.ts:81](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Console.ts#L81) |
| <a id="warn"></a> `warn` | (...`args`) => `void` | Outputs a warning message | [packages/common/src/Console.ts:48](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Console.ts#L48) |
ConsoleConfig - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Console](https://evolu.dev/docs/api-reference/common/Console) / ConsoleConfig
# Interface: ConsoleConfig
Defined in: [packages/common/src/Console.ts:89](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Console.ts#L89)
## Extended by
- [`ConsoleWithTimeConfig`](https://evolu.dev/docs/api-reference/common/Console/interfaces/ConsoleWithTimeConfig)
- [`DbConfig`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/DbConfig)
- [`RelayConfig`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/RelayConfig)
## Properties
| Property | Modifier | Type | Description | Defined in |
| ------------------------------------------- | ---------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| <a id="enablelogging"></a> `enableLogging?` | `readonly` | `boolean` | Enable or disable console logging (default: false). When true, logs are output to the [Console](https://evolu.dev/docs/api-reference/common/Console/interfaces/Console); when false, logging is disabled for all methods except `error`, which always outputs to ensure critical issues are not missed. | [packages/common/src/Console.ts:96](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Console.ts#L96) |
ConsoleDep - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Console](https://evolu.dev/docs/api-reference/common/Console) / ConsoleDep
# Interface: ConsoleDep
Defined in: [packages/common/src/Console.ts:85](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Console.ts#L85)
Dependency interface for injecting a Console instance.
## Properties
| Property | Modifier | Type | Defined in |
| ------------------------------ | ---------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| <a id="console"></a> `console` | `readonly` | [`Console`](https://evolu.dev/docs/api-reference/common/Console/interfaces/Console) | [packages/common/src/Console.ts:86](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Console.ts#L86) |
ConsoleWithTimeConfig - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Console](https://evolu.dev/docs/api-reference/common/Console) / ConsoleWithTimeConfig
# Interface: ConsoleWithTimeConfig
Defined in: [packages/common/src/Console.ts:166](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Console.ts#L166)
## Extends
- [`ConsoleConfig`](https://evolu.dev/docs/api-reference/common/Console/interfaces/ConsoleConfig)
## Properties
| Property | Modifier | Type | Description | Inherited from | Defined in |
| ------------------------------------------- | ---------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="enablelogging"></a> `enableLogging?` | `readonly` | `boolean` | Enable or disable console logging (default: false). When true, logs are output to the [Console](https://evolu.dev/docs/api-reference/common/Console/interfaces/Console); when false, logging is disabled for all methods except `error`, which always outputs to ensure critical issues are not missed. | [`ConsoleConfig`](https://evolu.dev/docs/api-reference/common/Console/interfaces/ConsoleConfig).[`enableLogging`](https://evolu.dev/docs/api-reference/common/Console/interfaces/ConsoleConfig.mdx#enablelogging) | [packages/common/src/Console.ts:96](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Console.ts#L96) |
| <a id="timestamptype"></a> `timestampType` | `readonly` | `"absolute"` \| `"relative"` | Type of timestamp to prepend to log messages. - 'absolute': Shows actual time (e.g., "14:32:15.234") - 'relative': Shows time since console creation (e.g., "+1.234s") | - | [packages/common/src/Console.ts:173](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Console.ts#L173) |
createPadmePaddedLength - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Crypto](https://evolu.dev/docs/api-reference/common/Crypto) / createPadmePaddedLength
# Function: createPadmePaddedLength()
```ts
function createPadmePaddedLength(
length,
): number & Brand<"Int"> & Brand<"NonNegative">;
```
Defined in: [packages/common/src/Crypto.ts:183](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Crypto.ts#L183)
Returns the PADMÉ padded length for a given input length.
PADMÉ limits information leakage about the length of the plain-text for a
wide range of encrypted data sizes.
See the PURBs paper for details: https://bford.info/pub/sec/purb.pdf
## Parameters
| Parameter | Type |
| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `length` | `number` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Int"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"NonNegative"`\> |
## Returns
`number` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Int"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"NonNegative"`\>
createPadmePadding - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Crypto](https://evolu.dev/docs/api-reference/common/Crypto) / createPadmePadding
# Function: createPadmePadding()
```ts
function createPadmePadding(length): Uint8Array;
```
Defined in: [packages/common/src/Crypto.ts:195](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Crypto.ts#L195)
Creates a PADMÉ padding array of zeros for the given input length.
## Parameters
| Parameter | Type |
| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `length` | `number` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Int"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"NonNegative"`\> |
## Returns
`Uint8Array`
createRandomBytes - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Crypto](https://evolu.dev/docs/api-reference/common/Crypto) / createRandomBytes
# Function: createRandomBytes()
```ts
function createRandomBytes(): RandomBytes;
```
Defined in: [packages/common/src/Crypto.ts:66](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Crypto.ts#L66)
## Returns
[`RandomBytes`](https://evolu.dev/docs/api-reference/common/Crypto/interfaces/RandomBytes)
createSlip21 - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Crypto](https://evolu.dev/docs/api-reference/common/Crypto) / createSlip21
# Function: createSlip21()
```ts
function createSlip21(
seed,
path,
): Uint8Array<ArrayBufferLike> & Brand<"Entropy"> & Brand<"Length32">;
```
Defined in: [packages/common/src/Crypto.ts:75](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Crypto.ts#L75)
SLIP21.
https://github.com/satoshilabs/slips/blob/master/slip-0021.md
## Parameters
| Parameter | Type |
| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `seed` | \| `Uint8Array`\<`ArrayBufferLike`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Entropy"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Length16"`\> \| `Uint8Array`\<`ArrayBufferLike`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Entropy"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Length32"`\> \| `Uint8Array`\<`ArrayBufferLike`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Entropy"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Length64"`\> |
| `path` | readonly (`string` \| `number`)[] |
## Returns
`Uint8Array`\<`ArrayBufferLike`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Entropy"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Length32"`\>
createSymmetricCrypto - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Crypto](https://evolu.dev/docs/api-reference/common/Crypto) / createSymmetricCrypto
# Function: createSymmetricCrypto()
```ts
function createSymmetricCrypto(deps): SymmetricCrypto;
```
Defined in: [packages/common/src/Crypto.ts:146](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Crypto.ts#L146)
XChaCha20-Poly1305 encryption
https://github.com/paulmillr/noble-ciphers?tab=readme-ov-file#which-cipher-should-i-pick
## Parameters
| Parameter | Type |
| --------- | ----------------------------------------------------------------------------------- |
| `deps` | [`RandomBytesDep`](https://evolu.dev/docs/api-reference/common/Crypto/interfaces/RandomBytesDep) |
## Returns
[`SymmetricCrypto`](https://evolu.dev/docs/api-reference/common/Crypto/interfaces/SymmetricCrypto)
deriveSlip21Node - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Crypto](https://evolu.dev/docs/api-reference/common/Crypto) / deriveSlip21Node
# Function: deriveSlip21Node()
```ts
function deriveSlip21Node(
label,
parentNode,
): Uint8Array<ArrayBufferLike> & Brand<"Entropy"> & Brand<"Length64">;
```
Defined in: [packages/common/src/Crypto.ts:98](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Crypto.ts#L98)
Derives a single node in the SLIP-21 hierarchical key derivation.
## Parameters
| Parameter | Type |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `label` | `string` |
| `parentNode` | `Uint8Array`\<`ArrayBufferLike`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Entropy"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Length64"`\> |
## Returns
`Uint8Array`\<`ArrayBufferLike`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Entropy"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Length64"`\>
## See
[createSlip21](https://evolu.dev/docs/api-reference/common/Crypto/functions/createSlip21)
RandomBytes - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Crypto](https://evolu.dev/docs/api-reference/common/Crypto) / RandomBytes
# Interface: RandomBytes
Defined in: [packages/common/src/Crypto.ts:17](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Crypto.ts#L17)
## Methods
### create()
##
Defined in: [packages/common/src/Crypto.ts:44](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Crypto.ts#L44)
Creates cryptographically secure random bytes with type-safe length
branding.
Uses the operating system's cryptographically secure random number
generator (crypto.getRandomValues) to generate high-quality entropy
suitable for cryptographic operations.
### Type Safety
Returns specific branded types for common sizes:
- `Random16` for 16-byte values (128 bits)
- `Random32` for 32-byte values (256 bits)
- `Random64` for 64-byte values (512 bits)
- `Random` for any other size
### Example
```ts
const nonce = randomBytes.create(16); // Type: Random16
const key = randomBytes.create(32); // Type: Random32
const seed = randomBytes.create(64); // Type: Random64
const custom = randomBytes.create(48); // Type: Random
```
##### Parameters
| Parameter | Type |
| ------------- | ---- |
| `bytesLength` | `16` |
##### Returns
`Uint8Array`\<`ArrayBufferLike`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Entropy"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Length16"`\>
##
Defined in: [packages/common/src/Crypto.ts:45](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Crypto.ts#L45)
##### Parameters
| Parameter | Type |
| ------------- | ---- |
| `bytesLength` | `32` |
##### Returns
`Uint8Array`\<`ArrayBufferLike`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Entropy"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Length32"`\>
##
Defined in: [packages/common/src/Crypto.ts:46](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Crypto.ts#L46)
##### Parameters
| Parameter | Type |
| ------------- | ---- |
| `bytesLength` | `64` |
##### Returns
`Uint8Array`\<`ArrayBufferLike`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Entropy"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Length64"`\>
##
Defined in: [packages/common/src/Crypto.ts:47](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Crypto.ts#L47)
##### Parameters
| Parameter | Type |
| ------------- | -------- |
| `bytesLength` | `number` |
##### Returns
`Uint8Array`\<`ArrayBufferLike`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Entropy"`\>
RandomBytesDep - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Crypto](https://evolu.dev/docs/api-reference/common/Crypto) / RandomBytesDep
# Interface: RandomBytesDep
Defined in: [packages/common/src/Crypto.ts:50](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Crypto.ts#L50)
## Properties
| Property | Modifier | Type | Defined in |
| -------------------------------------- | ---------- | ----------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="randombytes"></a> `randomBytes` | `readonly` | [`RandomBytes`](https://evolu.dev/docs/api-reference/common/Crypto/interfaces/RandomBytes) | [packages/common/src/Crypto.ts:51](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Crypto.ts#L51) |
SymmetricCrypto - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Crypto](https://evolu.dev/docs/api-reference/common/Crypto) / SymmetricCrypto
# Interface: SymmetricCrypto
Defined in: [packages/common/src/Crypto.ts:114](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Crypto.ts#L114)
Symmetric cryptography.
## Properties
| Property | Modifier | Type | Defined in |
| -------------------------------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| <a id="decrypt"></a> `decrypt` | `readonly` | (`ciphertext`, `encryptionKey`, `nonce`) => [`Result`](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result)\<`Uint8Array`\<`ArrayBufferLike`\>, [`SymmetricCryptoDecryptError`](https://evolu.dev/docs/api-reference/common/Crypto/interfaces/SymmetricCryptoDecryptError)\> | [packages/common/src/Crypto.ts:125](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Crypto.ts#L125) |
| <a id="encrypt"></a> `encrypt` | `readonly` | (`plaintext`, `encryptionKey`) => `object` | [packages/common/src/Crypto.ts:117](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Crypto.ts#L117) |
| <a id="noncelength"></a> `nonceLength` | `readonly` | `number` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Int"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"NonNegative"`\> | [packages/common/src/Crypto.ts:115](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Crypto.ts#L115) |
SymmetricCryptoDecryptError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Crypto](https://evolu.dev/docs/api-reference/common/Crypto) / SymmetricCryptoDecryptError
# Interface: SymmetricCryptoDecryptError
Defined in: [packages/common/src/Crypto.ts:136](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Crypto.ts#L136)
## Properties
| Property | Modifier | Type | Defined in |
| -------------------------- | ---------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| <a id="error"></a> `error` | `readonly` | `unknown` | [packages/common/src/Crypto.ts:138](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Crypto.ts#L138) |
| <a id="type"></a> `type` | `readonly` | `"SymmetricCryptoDecryptError"` | [packages/common/src/Crypto.ts:137](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Crypto.ts#L137) |
SymmetricCryptoDep - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Crypto](https://evolu.dev/docs/api-reference/common/Crypto) / SymmetricCryptoDep
# Interface: SymmetricCryptoDep
Defined in: [packages/common/src/Crypto.ts:132](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Crypto.ts#L132)
## Properties
| Property | Modifier | Type | Defined in |
| ---------------------------------------------- | ---------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| <a id="symmetriccrypto"></a> `symmetricCrypto` | `readonly` | [`SymmetricCrypto`](https://evolu.dev/docs/api-reference/common/Crypto/interfaces/SymmetricCrypto) | [packages/common/src/Crypto.ts:133](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Crypto.ts#L133) |
TimingSafeEqualDep - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Crypto](https://evolu.dev/docs/api-reference/common/Crypto) / TimingSafeEqualDep
# Interface: TimingSafeEqualDep
Defined in: [packages/common/src/Crypto.ts:210](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Crypto.ts#L210)
## Properties
| Property | Modifier | Type | Defined in |
| ---------------------------------------------- | ---------- | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| <a id="timingsafeequal"></a> `timingSafeEqual` | `readonly` | [`TimingSafeEqual`](https://evolu.dev/docs/api-reference/common/Crypto/type-aliases/TimingSafeEqual) | [packages/common/src/Crypto.ts:211](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Crypto.ts#L211) |
EncryptionKey - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Crypto](https://evolu.dev/docs/api-reference/common/Crypto) / EncryptionKey
# Type Alias: EncryptionKey
```ts
type EncryptionKey = typeof Type;
```
Defined in: [packages/common/src/Crypto.ts:110](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Crypto.ts#L110)
Entropy16 - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Crypto](https://evolu.dev/docs/api-reference/common/Crypto) / Entropy16
# Type Alias: Entropy16
```ts
type Entropy16 = typeof Type;
```
Defined in: [packages/common/src/Crypto.ts:57](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Crypto.ts#L57)
Entropy32 - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Crypto](https://evolu.dev/docs/api-reference/common/Crypto) / Entropy32
# Type Alias: Entropy32
```ts
type Entropy32 = typeof Type;
```
Defined in: [packages/common/src/Crypto.ts:60](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Crypto.ts#L60)
Entropy64 - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Crypto](https://evolu.dev/docs/api-reference/common/Crypto) / Entropy64
# Type Alias: Entropy64
```ts
type Entropy64 = typeof Type;
```
Defined in: [packages/common/src/Crypto.ts:63](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Crypto.ts#L63)
TimingSafeEqual - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Crypto](https://evolu.dev/docs/api-reference/common/Crypto) / TimingSafeEqual
# Type Alias: TimingSafeEqual()
```ts
type TimingSafeEqual = (a, b) => boolean;
```
Defined in: [packages/common/src/Crypto.ts:208](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Crypto.ts#L208)
Performs a timing-safe comparison of two Uint8Arrays. Returns true if they
are equal, false otherwise. Takes constant time regardless of where the
arrays differ.
## Parameters
| Parameter | Type |
| --------- | ------------ |
| `a` | `Uint8Array` |
| `b` | `Uint8Array` |
## Returns
`boolean`
## See
https://nodejs.org/api/crypto.html#cryptotimingsafeequala-b
EncryptionKey - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Crypto](https://evolu.dev/docs/api-reference/common/Crypto) / EncryptionKey
# Variable: EncryptionKey
```ts
const EncryptionKey: BrandType<
BrandType<
Type<
"Brand",
Uint8Array<ArrayBufferLike> & Brand<"Entropy">,
Uint8Array<ArrayBufferLike>,
BrandWithoutRefineError<"Entropy", Uint8ArrayError>,
Uint8Array<ArrayBufferLike>,
never
>,
"Length32",
LengthError<32>,
BrandWithoutRefineError<"Entropy", Uint8ArrayError>
>,
"EncryptionKey",
BrandWithoutRefineError<
"EncryptionKey",
BrandWithoutRefineError<"Entropy", Uint8ArrayError> | LengthError<32>
>,
never
>;
```
Defined in: [packages/common/src/Crypto.ts:110](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Crypto.ts#L110)
The encryption key for [SymmetricCrypto](https://evolu.dev/docs/api-reference/common/Crypto/interfaces/SymmetricCrypto).
Entropy16 - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Crypto](https://evolu.dev/docs/api-reference/common/Crypto) / Entropy16
# Variable: Entropy16
```ts
const Entropy16: BrandType<
Type<
"Brand",
Uint8Array<ArrayBufferLike> & Brand<"Entropy">,
Uint8Array<ArrayBufferLike>,
BrandWithoutRefineError<"Entropy", Uint8ArrayError>,
Uint8Array<ArrayBufferLike>,
never
>,
"Length16",
LengthError<16>,
BrandWithoutRefineError<"Entropy", Uint8ArrayError>
>;
```
Defined in: [packages/common/src/Crypto.ts:57](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Crypto.ts#L57)
Entropy32 - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Crypto](https://evolu.dev/docs/api-reference/common/Crypto) / Entropy32
# Variable: Entropy32
```ts
const Entropy32: BrandType<
Type<
"Brand",
Uint8Array<ArrayBufferLike> & Brand<"Entropy">,
Uint8Array<ArrayBufferLike>,
BrandWithoutRefineError<"Entropy", Uint8ArrayError>,
Uint8Array<ArrayBufferLike>,
never
>,
"Length32",
LengthError<32>,
BrandWithoutRefineError<"Entropy", Uint8ArrayError>
>;
```
Defined in: [packages/common/src/Crypto.ts:60](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Crypto.ts#L60)
Entropy64 - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Crypto](https://evolu.dev/docs/api-reference/common/Crypto) / Entropy64
# Variable: Entropy64
```ts
const Entropy64: BrandType<
Type<
"Brand",
Uint8Array<ArrayBufferLike> & Brand<"Entropy">,
Uint8Array<ArrayBufferLike>,
BrandWithoutRefineError<"Entropy", Uint8ArrayError>,
Uint8Array<ArrayBufferLike>,
never
>,
"Length64",
LengthError<64>,
BrandWithoutRefineError<"Entropy", Uint8ArrayError>
>;
```
Defined in: [packages/common/src/Crypto.ts:63](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Crypto.ts#L63)
createEqArrayLike - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Eq](https://evolu.dev/docs/api-reference/common/Eq) / createEqArrayLike
# Function: createEqArrayLike()
```ts
function createEqArrayLike<A>(item): Eq<ArrayLike<A>>;
```
Defined in: [packages/common/src/Eq.ts:42](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Eq.ts#L42)
Creates an equivalence function for array-like structures based on an
equivalence for their elements.
### Example
```ts
const eqArrayNumber = createEqArrayLike(eqNumber);
eqArrayNumber([1, 2, 3], [1, 2, 3]); // true (works with regular arrays)
eqArrayNumber(new Uint8Array([1, 2, 3]), new Uint8Array([1, 2, 3])); // true (works with Uint8Array)
eqArrayNumber([1, 2, 3], [1, 2, 4]); // false
```
## Type Parameters
| Type Parameter |
| -------------- |
| `A` |
## Parameters
| Parameter | Type |
| --------- | ---------------------------------------------------------------- |
| `item` | [`Eq`](https://evolu.dev/docs/api-reference/common/Eq/type-aliases/Eq)\<`A`\> |
## Returns
[`Eq`](https://evolu.dev/docs/api-reference/common/Eq/type-aliases/Eq)\<`ArrayLike`\<`A`\>\>
createEqObject - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Eq](https://evolu.dev/docs/api-reference/common/Eq) / createEqObject
# Function: createEqObject()
```ts
function createEqObject<A>(
eqs,
): Eq<{ readonly [K in string | number | symbol]: A[K] }>;
```
Defined in: [packages/common/src/Eq.ts:80](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Eq.ts#L80)
Creates an equivalence function for objects based on an equivalence for their
fields.
### Example
```ts
const eqObjectNumber = createEqObject({ a: eqNumber });
eqObjectNumber({ a: 1 }, { a: 1 }); // true
eqObjectNumber({ a: 1 }, { a: 2 }); // false
```
## Type Parameters
| Type Parameter |
| -------------- |
| `A` |
## Parameters
| Parameter | Type |
| --------- | ------------------------------------------------------- |
| `eqs` | \{ \[K in string \| number \| symbol\]: Eq\<A\[K\]\> \} |
## Returns
[`Eq`](https://evolu.dev/docs/api-reference/common/Eq/type-aliases/Eq)\<\{ readonly \[K in string \| number \| symbol\]: A\[K\] \}\>
eqFromOrder - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Eq](https://evolu.dev/docs/api-reference/common/Eq) / eqFromOrder
# Function: eqFromOrder()
```ts
function eqFromOrder<A>(order): Eq<A>;
```
Defined in: [packages/common/src/Eq.ts:24](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Eq.ts#L24)
Derives an [Eq](https://evolu.dev/docs/api-reference/common/Eq/type-aliases/Eq) from an [Order](https://evolu.dev/docs/api-reference/common/Order/type-aliases/Order).
## Type Parameters
| Type Parameter |
| -------------- |
| `A` |
## Parameters
| Parameter | Type |
| --------- | ------------------------------------------------------------------------- |
| `order` | [`Order`](https://evolu.dev/docs/api-reference/common/Order/type-aliases/Order)\<`A`\> |
## Returns
[`Eq`](https://evolu.dev/docs/api-reference/common/Eq/type-aliases/Eq)\<`A`\>
eqJsonValue - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Eq](https://evolu.dev/docs/api-reference/common/Eq) / eqJsonValue
# Function: eqJsonValue()
```ts
function eqJsonValue(a, b): boolean;
```
Defined in: [packages/common/src/Eq.ts:111](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Eq.ts#L111)
Deeply compares two [JsonValue](https://evolu.dev/docs/api-reference/common/Type/variables/JsonValue) values for equality.
- Uses an iterative approach with a stack to handle large or deeply nested
objects without risking stack overflow.
- Handles circular references with a WeakMap to prevent infinite loops.
- Unlike JSON.stringify, this function directly compares values, avoiding
serialization overhead and leveraging short-circuit evaluation for faster
failure on mismatched structures.
### Example
```ts
const obj1: Json = { name: "Alice", hobbies: ["reading", "hiking"] };
const obj2: Json = { name: "Alice", hobbies: ["reading", "hiking"] };
console.log(eqJson(obj1, obj2)); // true
```
## Parameters
| Parameter | Type |
| --------- | ------------------------------------------------------------------------- |
| `a` | [`JsonValue`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/JsonValue) |
| `b` | [`JsonValue`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/JsonValue) |
## Returns
`boolean`
eqJsonValueInput - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Eq](https://evolu.dev/docs/api-reference/common/Eq) / eqJsonValueInput
# Function: eqJsonValueInput()
```ts
function eqJsonValueInput(a, b): boolean;
```
Defined in: [packages/common/src/Eq.ts:201](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Eq.ts#L201)
Deeply compares two [JsonValueInput](https://evolu.dev/docs/api-reference/common/Type/type-aliases/JsonValueInput) values for equality.
- Uses an iterative approach with a stack to handle large or deeply nested
objects without risking stack overflow.
- Handles circular references with a WeakMap to prevent infinite loops.
- Unlike JSON.stringify, this function directly compares values, avoiding
serialization overhead and leveraging short-circuit evaluation for faster
failure on mismatched structures.
### Example
```ts
const obj1: Json = { name: "Alice", hobbies: ["reading", "hiking"] };
const obj2: Json = { name: "Alice", hobbies: ["reading", "hiking"] };
console.log(eqJson(obj1, obj2)); // true
```
## Parameters
| Parameter | Type |
| --------- | ----------------------------------------------------------------------------------- |
| `a` | [`JsonValueInput`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/JsonValueInput) |
| `b` | [`JsonValueInput`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/JsonValueInput) |
## Returns
`boolean`
eqStrict - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Eq](https://evolu.dev/docs/api-reference/common/Eq) / eqStrict
# Function: eqStrict()
```ts
function eqStrict<A>(x, y): boolean;
```
Defined in: [packages/common/src/Eq.ts:13](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Eq.ts#L13)
## Type Parameters
| Type Parameter |
| -------------- |
| `A` |
## Parameters
| Parameter | Type |
| --------- | ---- |
| `x` | `A` |
| `y` | `A` |
## Returns
`boolean`
Eq - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Eq](https://evolu.dev/docs/api-reference/common/Eq) / Eq
# Type Alias: Eq()\<A\>
```ts
type Eq<A> = (x, y) => boolean;
```
Defined in: [packages/common/src/Eq.ts:11](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Eq.ts#L11)
Compares two values of the same type `A` for equality.
Equality functions start with an 'eq' prefix, e.g., `eqString`.
TODO: Explain, examples (composition etc.)
## Type Parameters
| Type Parameter |
| -------------- |
| `A` |
## Parameters
| Parameter | Type |
| --------- | ---- |
| `x` | `A` |
| `y` | `A` |
## Returns
`boolean`
eqArrayNumber - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Eq](https://evolu.dev/docs/api-reference/common/Eq) / eqArrayNumber
# Variable: eqArrayNumber
```ts
const eqArrayNumber: Eq<ArrayLike<number>>;
```
Defined in: [packages/common/src/Eq.ts:65](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Eq.ts#L65)
Compares two array-like structures of numbers for equality.
### Example
```ts
eqArrayNumber([1, 2, 3], [1, 2, 3]); // true (works with regular arrays)
eqArrayNumber(new Uint8Array([1, 2, 3]), new Uint8Array([1, 2, 3])); // true (works with Uint8Array)
eqArrayNumber([1, 2, 3], [1, 2, 4]); // false
```
eqBigInt - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Eq](https://evolu.dev/docs/api-reference/common/Eq) / eqBigInt
# Variable: eqBigInt
```ts
const eqBigInt: Eq<bigint> = eqStrict;
```
Defined in: [packages/common/src/Eq.ts:17](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Eq.ts#L17)
eqBoolean - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Eq](https://evolu.dev/docs/api-reference/common/Eq) / eqBoolean
# Variable: eqBoolean
```ts
const eqBoolean: Eq<boolean> = eqStrict;
```
Defined in: [packages/common/src/Eq.ts:18](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Eq.ts#L18)
eqNull - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Eq](https://evolu.dev/docs/api-reference/common/Eq) / eqNull
# Variable: eqNull
```ts
const eqNull: Eq<null> = eqStrict;
```
Defined in: [packages/common/src/Eq.ts:20](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Eq.ts#L20)
eqNumber - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Eq](https://evolu.dev/docs/api-reference/common/Eq) / eqNumber
# Variable: eqNumber
```ts
const eqNumber: Eq<number> = eqStrict;
```
Defined in: [packages/common/src/Eq.ts:16](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Eq.ts#L16)
eqString - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Eq](https://evolu.dev/docs/api-reference/common/Eq) / eqString
# Variable: eqString
```ts
const eqString: Eq<string> = eqStrict;
```
Defined in: [packages/common/src/Eq.ts:15](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Eq.ts#L15)
eqUndefined - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Eq](https://evolu.dev/docs/api-reference/common/Eq) / eqUndefined
# Variable: eqUndefined
```ts
const eqUndefined: Eq<undefined> = eqStrict;
```
Defined in: [packages/common/src/Eq.ts:19](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Eq.ts#L19)
createTransferableError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Error](https://evolu.dev/docs/api-reference/common/Error) / createTransferableError
# Function: createTransferableError()
```ts
function createTransferableError(error): TransferableError;
```
Defined in: [packages/common/src/Error.ts:19](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Error.ts#L19)
Creates a [TransferableError](https://evolu.dev/docs/api-reference/common/Error/interfaces/TransferableError) from an unknown error.
## Parameters
| Parameter | Type |
| --------- | --------- |
| `error` | `unknown` |
## Returns
[`TransferableError`](https://evolu.dev/docs/api-reference/common/Error/interfaces/TransferableError)
TransferableError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Error](https://evolu.dev/docs/api-reference/common/Error) / TransferableError
# Interface: TransferableError
Defined in: [packages/common/src/Error.ts:13](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Error.ts#L13)
A serializable representation of an error for safe transfer between execution
contexts, such as Web Workers and the main thread.
Use this type for unknown (unexpected) errors that need to be transferred
across boundaries where native Error objects cannot be sent directly. Not
intended for regular (expected) errors.
The `error` property contains a plain object with error details, a string, or
a fallback value if serialization fails to preserve as much debugging
information as possible.
## Properties
| Property | Modifier | Type | Defined in |
| -------------------------- | ---------- | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="error"></a> `error` | `readonly` | `unknown` | [packages/common/src/Error.ts:15](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Error.ts#L15) |
| <a id="type"></a> `type` | `readonly` | `"TransferableError"` | [packages/common/src/Error.ts:14](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Error.ts#L14) |
exhaustiveCheck - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Function](https://evolu.dev/docs/api-reference/common/Function) / exhaustiveCheck
# Function: exhaustiveCheck()
```ts
function exhaustiveCheck(value): never;
```
Defined in: [packages/common/src/Function.ts:33](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Function.ts#L33)
Helper function to ensure exhaustive matching in a switch statement. Throws
an error if an unhandled case is encountered.
Remember, it's useful only when we don't return anything from the switch
statement. Otherwise, a return type of a function is enough.
### Example
```ts
type Color = "red" | "green" | "blue";
function handleColor(color: Color): void {
switch (color) {
case "red":
console.log("Handling red");
break;
case "green":
console.log("Handling green");
break;
case "blue":
console.log("Handling blue");
break;
default:
exhaustiveCheck(color); // Ensures all cases are handled
}
}
```
## Parameters
| Parameter | Type |
| --------- | ------- |
| `value` | `never` |
## Returns
`never`
identity - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Function](https://evolu.dev/docs/api-reference/common/Function) / identity
# Function: identity()
```ts
function identity<A>(a): A;
```
Defined in: [packages/common/src/Function.ts:53](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Function.ts#L53)
Returns the input value unchanged.
Useful as a default transformation, placeholder callback, or when a function
is required but no transformation is needed.
### Example
```ts
const values = [1, 2, 3];
const same = values.map(identity); // [1, 2, 3]
const getTransform = (shouldDouble: boolean) =>
shouldDouble ? (x: number) => x * 2 : identity;
```
## Type Parameters
| Type Parameter |
| -------------- |
| `A` |
## Parameters
| Parameter | Type |
| --------- | ---- |
| `a` | `A` |
## Returns
`A`
readonly - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Function](https://evolu.dev/docs/api-reference/common/Function) / readonly
# Function: readonly()
Defined in: [packages/common/src/Function.ts:93](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Function.ts#L93)
**`Experimental`**
Casts an array, set, record, or map to its readonly counterpart.
Zero runtime cost — returns the same value with a readonly type. Use this to
enforce immutability at the type level. Preserves [NonEmptyArray](https://evolu.dev/docs/api-reference/common/Array/type-aliases/NonEmptyArray) as
[NonEmptyReadonlyArray](https://evolu.dev/docs/api-reference/common/Array/type-aliases/NonEmptyReadonlyArray).
### Example
```ts
// Array literals become NonEmptyReadonlyArray
const items = readonly([1, 2, 3]);
// Type: NonEmptyReadonlyArray<number>
// NonEmptyArray is preserved as NonEmptyReadonlyArray
const nonEmpty: NonEmptyArray<number> = [1, 2, 3];
const readonlyNonEmpty = readonly(nonEmpty);
// Type: NonEmptyReadonlyArray<number>
// Regular arrays become ReadonlyArray
const arr: Array<number> = getNumbers();
const readonlyArr = readonly(arr);
// Type: ReadonlyArray<number>
// Sets, Records, and Maps
const ids = readonly(new Set(["a", "b"]));
// Type: ReadonlySet<string>
const users: Record<UserId, string> = { ... };
const readonlyUsers = readonly(users);
// Type: ReadonlyRecord<UserId, string>
const lookup = readonly(new Map([["key", "value"]]));
// Type: ReadonlyMap<string, string>
```
### Type Parameters
| Type Parameter |
| -------------- |
| `T` |
### Parameters
| Parameter | Type |
| --------- | ----------------- |
| `array` | \[`T`, `...T[]`\] |
### Returns
readonly \[`T`, `T`\]
Defined in: [packages/common/src/Function.ts:94](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Function.ts#L94)
**`Experimental`**
Casts an array, set, record, or map to its readonly counterpart.
Zero runtime cost — returns the same value with a readonly type. Use this to
enforce immutability at the type level. Preserves [NonEmptyArray](https://evolu.dev/docs/api-reference/common/Array/type-aliases/NonEmptyArray) as
[NonEmptyReadonlyArray](https://evolu.dev/docs/api-reference/common/Array/type-aliases/NonEmptyReadonlyArray).
### Example
```ts
// Array literals become NonEmptyReadonlyArray
const items = readonly([1, 2, 3]);
// Type: NonEmptyReadonlyArray<number>
// NonEmptyArray is preserved as NonEmptyReadonlyArray
const nonEmpty: NonEmptyArray<number> = [1, 2, 3];
const readonlyNonEmpty = readonly(nonEmpty);
// Type: NonEmptyReadonlyArray<number>
// Regular arrays become ReadonlyArray
const arr: Array<number> = getNumbers();
const readonlyArr = readonly(arr);
// Type: ReadonlyArray<number>
// Sets, Records, and Maps
const ids = readonly(new Set(["a", "b"]));
// Type: ReadonlySet<string>
const users: Record<UserId, string> = { ... };
const readonlyUsers = readonly(users);
// Type: ReadonlyRecord<UserId, string>
const lookup = readonly(new Map([["key", "value"]]));
// Type: ReadonlyMap<string, string>
```
### Type Parameters
| Type Parameter |
| -------------- |
| `T` |
### Parameters
| Parameter | Type |
| --------- | ----- |
| `array` | `T`[] |
### Returns
readonly `T`[]
Defined in: [packages/common/src/Function.ts:95](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Function.ts#L95)
**`Experimental`**
Casts an array, set, record, or map to its readonly counterpart.
Zero runtime cost — returns the same value with a readonly type. Use this to
enforce immutability at the type level. Preserves [NonEmptyArray](https://evolu.dev/docs/api-reference/common/Array/type-aliases/NonEmptyArray) as
[NonEmptyReadonlyArray](https://evolu.dev/docs/api-reference/common/Array/type-aliases/NonEmptyReadonlyArray).
### Example
```ts
// Array literals become NonEmptyReadonlyArray
const items = readonly([1, 2, 3]);
// Type: NonEmptyReadonlyArray<number>
// NonEmptyArray is preserved as NonEmptyReadonlyArray
const nonEmpty: NonEmptyArray<number> = [1, 2, 3];
const readonlyNonEmpty = readonly(nonEmpty);
// Type: NonEmptyReadonlyArray<number>
// Regular arrays become ReadonlyArray
const arr: Array<number> = getNumbers();
const readonlyArr = readonly(arr);
// Type: ReadonlyArray<number>
// Sets, Records, and Maps
const ids = readonly(new Set(["a", "b"]));
// Type: ReadonlySet<string>
const users: Record<UserId, string> = { ... };
const readonlyUsers = readonly(users);
// Type: ReadonlyRecord<UserId, string>
const lookup = readonly(new Map([["key", "value"]]));
// Type: ReadonlyMap<string, string>
```
### Type Parameters
| Type Parameter |
| -------------- |
| `T` |
### Parameters
| Parameter | Type |
| --------- | ------------ |
| `set` | `Set`\<`T`\> |
### Returns
`ReadonlySet`\<`T`\>
Defined in: [packages/common/src/Function.ts:96](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Function.ts#L96)
**`Experimental`**
Casts an array, set, record, or map to its readonly counterpart.
Zero runtime cost — returns the same value with a readonly type. Use this to
enforce immutability at the type level. Preserves [NonEmptyArray](https://evolu.dev/docs/api-reference/common/Array/type-aliases/NonEmptyArray) as
[NonEmptyReadonlyArray](https://evolu.dev/docs/api-reference/common/Array/type-aliases/NonEmptyReadonlyArray).
### Example
```ts
// Array literals become NonEmptyReadonlyArray
const items = readonly([1, 2, 3]);
// Type: NonEmptyReadonlyArray<number>
// NonEmptyArray is preserved as NonEmptyReadonlyArray
const nonEmpty: NonEmptyArray<number> = [1, 2, 3];
const readonlyNonEmpty = readonly(nonEmpty);
// Type: NonEmptyReadonlyArray<number>
// Regular arrays become ReadonlyArray
const arr: Array<number> = getNumbers();
const readonlyArr = readonly(arr);
// Type: ReadonlyArray<number>
// Sets, Records, and Maps
const ids = readonly(new Set(["a", "b"]));
// Type: ReadonlySet<string>
const users: Record<UserId, string> = { ... };
const readonlyUsers = readonly(users);
// Type: ReadonlyRecord<UserId, string>
const lookup = readonly(new Map([["key", "value"]]));
// Type: ReadonlyMap<string, string>
```
### Type Parameters
| Type Parameter |
| -------------- |
| `K` |
| `V` |
### Parameters
| Parameter | Type |
| --------- | ----------------- |
| `map` | `Map`\<`K`, `V`\> |
### Returns
`ReadonlyMap`\<`K`, `V`\>
Defined in: [packages/common/src/Function.ts:97](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Function.ts#L97)
**`Experimental`**
Casts an array, set, record, or map to its readonly counterpart.
Zero runtime cost — returns the same value with a readonly type. Use this to
enforce immutability at the type level. Preserves [NonEmptyArray](https://evolu.dev/docs/api-reference/common/Array/type-aliases/NonEmptyArray) as
[NonEmptyReadonlyArray](https://evolu.dev/docs/api-reference/common/Array/type-aliases/NonEmptyReadonlyArray).
### Example
```ts
// Array literals become NonEmptyReadonlyArray
const items = readonly([1, 2, 3]);
// Type: NonEmptyReadonlyArray<number>
// NonEmptyArray is preserved as NonEmptyReadonlyArray
const nonEmpty: NonEmptyArray<number> = [1, 2, 3];
const readonlyNonEmpty = readonly(nonEmpty);
// Type: NonEmptyReadonlyArray<number>
// Regular arrays become ReadonlyArray
const arr: Array<number> = getNumbers();
const readonlyArr = readonly(arr);
// Type: ReadonlyArray<number>
// Sets, Records, and Maps
const ids = readonly(new Set(["a", "b"]));
// Type: ReadonlySet<string>
const users: Record<UserId, string> = { ... };
const readonlyUsers = readonly(users);
// Type: ReadonlyRecord<UserId, string>
const lookup = readonly(new Map([["key", "value"]]));
// Type: ReadonlyMap<string, string>
```
### Type Parameters
| Type Parameter |
| ---------------------------------------------- |
| `K` _extends_ `string` \| `number` \| `symbol` |
| `V` |
### Parameters
| Parameter | Type |
| --------- | -------------------- |
| `record` | `Record`\<`K`, `V`\> |
### Returns
[`ReadonlyRecord`](https://evolu.dev/docs/api-reference/common/Object/type-aliases/ReadonlyRecord)\<`K`, `V`\>
LazyValue - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Function](https://evolu.dev/docs/api-reference/common/Function) / LazyValue
# Type Alias: LazyValue()\<T\>
```ts
type LazyValue<T> = () => T;
```
Defined in: [packages/common/src/Function.ts:126](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Function.ts#L126)
A function that delays computation and returns a value of type T.
Useful for:
- Lazy evaluation
- Returning constant values
- Providing default or placeholder behaviors
### Example
```ts
const getRandomNumber: LazyValue<number> = () => Math.random();
const randomValue = getRandomNumber();
```
## Type Parameters
| Type Parameter |
| -------------- |
| `T` |
## Returns
`T`
constFalse - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Function](https://evolu.dev/docs/api-reference/common/Function) / constFalse
# Variable: constFalse
```ts
const constFalse: LazyValue<false>;
```
Defined in: [packages/common/src/Function.ts:132](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Function.ts#L132)
constNull - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Function](https://evolu.dev/docs/api-reference/common/Function) / constNull
# Variable: constNull
```ts
const constNull: LazyValue<null>;
```
Defined in: [packages/common/src/Function.ts:130](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Function.ts#L130)
constTrue - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Function](https://evolu.dev/docs/api-reference/common/Function) / constTrue
# Variable: constTrue
```ts
const constTrue: LazyValue<true>;
```
Defined in: [packages/common/src/Function.ts:131](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Function.ts#L131)
constUndefined - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Function](https://evolu.dev/docs/api-reference/common/Function) / constUndefined
# Variable: constUndefined
```ts
const constUndefined: LazyValue<undefined>;
```
Defined in: [packages/common/src/Function.ts:129](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Function.ts#L129)
constVoid - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Function](https://evolu.dev/docs/api-reference/common/Function) / constVoid
# Variable: constVoid
```ts
const constVoid: LazyValue<void>;
```
Defined in: [packages/common/src/Function.ts:128](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Function.ts#L128)
createIdenticon - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Identicon](https://evolu.dev/docs/api-reference/common/Identicon) / createIdenticon
# Function: createIdenticon()
```ts
function createIdenticon(id, style): Identicon;
```
Defined in: [packages/common/src/Identicon.ts:38](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Identicon.ts#L38)
Creates a deterministic identicon SVG from an [Id](https://evolu.dev/docs/api-reference/common/Type/variables/Id).
Works with any [Id](https://evolu.dev/docs/api-reference/common/Type/variables/Id) including branded IDs like `OwnerId`, etc.
Available styles:
- `"github"` (default): 5x5 grid with horizontal mirroring (GitHub-style)
- `"quadrant"`: 2x2 grid with direct RGB color mapping from bytes
- `"gradient"`: Diagonal stripes with smooth color gradients
- `"sutnar"`: Three compositional variants with adaptive colors
### Example
```ts
const svg = createIdenticon(id);
const quadrantStyle = createIdenticon(id, "quadrant");
const gradientStyle = createIdenticon(id, "gradient");
const sutnarStyle = createIdenticon(id, "sutnar");
// Works with branded IDs
const ownerSvg = createIdenticon(ownerId);
```
## Parameters
| Parameter | Type | Default value |
| --------- | ---------------------------------------------------------------------------------------- | ------------- |
| `id` | `string` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Id"`\> | `undefined` |
| `style` | [`IdenticonStyle`](https://evolu.dev/docs/api-reference/common/Identicon/type-aliases/IdenticonStyle) | `"github"` |
## Returns
[`Identicon`](https://evolu.dev/docs/api-reference/common/Identicon/type-aliases/Identicon)
Identicon - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Identicon](https://evolu.dev/docs/api-reference/common/Identicon) / Identicon
# Type Alias: Identicon
```ts
type Identicon = string & Brand<"Identicon">;
```
Defined in: [packages/common/src/Identicon.ts:9](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Identicon.ts#L9)
SVG string representing a visual identicon for an [Id](https://evolu.dev/docs/api-reference/common/Type/variables/Id), created with
[createIdenticon](https://evolu.dev/docs/api-reference/common/Identicon/functions/createIdenticon).
IdenticonStyle - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Identicon](https://evolu.dev/docs/api-reference/common/Identicon) / IdenticonStyle
# Type Alias: IdenticonStyle
```ts
type IdenticonStyle = "github" | "quadrant" | "gradient" | "sutnar";
```
Defined in: [packages/common/src/Identicon.ts:12](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Identicon.ts#L12)
[Identicon](https://evolu.dev/docs/api-reference/common/Identicon/type-aliases/Identicon) style.
createInstances - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Instances](https://evolu.dev/docs/api-reference/common/Instances) / createInstances
# Function: createInstances()
```ts
function createInstances<K, T>(): Instances<K, T>;
```
Defined in: [packages/common/src/Instances.ts:44](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Instances.ts#L44)
Creates an [Instances](https://evolu.dev/docs/api-reference/common/Instances/interfaces/Instances).
## Type Parameters
| Type Parameter |
| -------------------------- |
| `K` _extends_ `string` |
| `T` _extends_ `Disposable` |
## Returns
[`Instances`](https://evolu.dev/docs/api-reference/common/Instances/interfaces/Instances)\<`K`, `T`\>
Instances - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Instances](https://evolu.dev/docs/api-reference/common/Instances) / Instances
# Interface: Instances\<K, T\>
Defined in: [packages/common/src/Instances.ts:15](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Instances.ts#L15)
Manages disposable instances by key, ensuring exactly one instance per key.
Use cases:
- One mutex per key to prevent concurrent writes
- Preserving state during hot module reloading
**Important:** Do not use this as global shared state. Use it locally or pass
it as a dependency instead. The only exception is for hot reloading support,
where Evolu uses it to ensure only one instance exists across module reloads
(having two Evolu instances with the same name would mean two SQLite
connections to the same file, which could corrupt data).
## Extends
- `Disposable`
## Type Parameters
| Type Parameter |
| -------------------------- |
| `K` _extends_ `string` |
| `T` _extends_ `Disposable` |
## Properties
| Property | Modifier | Type | Description | Defined in |
| ---------------------------- | ---------- | --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="delete"></a> `delete` | `readonly` | (`key`) => `boolean` | Deletes and disposes an instance by key. Returns `true` if the instance existed and was deleted, `false` otherwise. | [packages/common/src/Instances.ts:40](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Instances.ts#L40) |
| <a id="ensure"></a> `ensure` | `readonly` | (`key`, `create`, `onCacheHit?`) => `T` | Ensures an instance exists for the given key, creating it if necessary. If the instance already exists, the optional `onCacheHit` callback is invoked to update the existing instance. | [packages/common/src/Instances.ts:24](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Instances.ts#L24) |
| <a id="get"></a> `get` | `readonly` | (`key`) => `T` \| `null` | Gets an instance by key, or returns `null` if it doesn't exist. | [packages/common/src/Instances.ts:31](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Instances.ts#L31) |
| <a id="has"></a> `has` | `readonly` | (`key`) => `boolean` | Checks if an instance exists for the given key. | [packages/common/src/Instances.ts:34](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Instances.ts#L34) |
## Methods
### \[dispose\]()
##
Defined in: node_modules/typescript/lib/lib.esnext.disposable.d.ts:36
##### Returns
`void`
##### Inherited from
```ts
Disposable.[dispose]
```
##
Defined in: node_modules/@types/node/compatibility/disposable.d.ts:9
##### Returns
`void`
##### Inherited from
```ts
Disposable.[dispose]
```
clamp - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Number](https://evolu.dev/docs/api-reference/common/Number) / clamp
# Function: clamp()
```ts
function clamp(min, max): (n) => number;
```
Defined in: [packages/common/src/Number.ts:14](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Number.ts#L14)
Clamps a number within a given range.
## Parameters
| Parameter | Type |
| --------- | -------- |
| `min` | `number` |
| `max` | `number` |
## Returns
```ts
(n): number;
```
### Parameters
| Parameter | Type |
| --------- | -------- |
| `n` | `number` |
### Returns
`number`
computeBalancedBuckets - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Number](https://evolu.dev/docs/api-reference/common/Number) / computeBalancedBuckets
# Function: computeBalancedBuckets()
```ts
function computeBalancedBuckets(
numberOfItems,
numberOfBuckets,
minNumberOfItemsPerBucket,
): Result<
readonly [
number & Brand<"Int"> & Brand<"NonNegative"> & Brand<"Positive">,
number & Brand<"Int"> & Brand<"NonNegative"> & Brand<"Positive">,
],
number & Brand<"Int"> & Brand<"NonNegative"> & Brand<"Positive">
>;
```
Defined in: [packages/common/src/Number.ts:58](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Number.ts#L58)
Divides items into buckets as evenly as possible, ensuring each bucket has at
least the minimum number of items. Returns a success result if the minimum is
met, or an error result with the required number of items if not.
### Example
```ts
computeBalancedBuckets(10, 3, 2); // Returns ok([4, 7, 10])
computeBalancedBuckets(5, 3, 2); // Returns err(6)
```
## Parameters
| Parameter | Type | Description |
| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| `numberOfItems` | `number` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Int"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"NonNegative"`\> | - |
| `numberOfBuckets` | `number` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Int"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"NonNegative"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Positive"`\> | Default: 16 |
| `minNumberOfItemsPerBucket` | `number` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Int"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"NonNegative"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Positive"`\> | Default: 2 |
## Returns
[`Result`](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result)\<readonly \[`number` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Int"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"NonNegative"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Positive"`\>, `number` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Int"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"NonNegative"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Positive"`\>\], `number` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Int"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"NonNegative"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Positive"`\>\>
decrement - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Number](https://evolu.dev/docs/api-reference/common/Number) / decrement
# Function: decrement()
```ts
function decrement(n): number;
```
Defined in: [packages/common/src/Number.ts:10](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Number.ts#L10)
## Parameters
| Parameter | Type |
| --------- | -------- |
| `n` | `number` |
## Returns
`number`
increment - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Number](https://evolu.dev/docs/api-reference/common/Number) / increment
# Function: increment()
```ts
function increment(n): number;
```
Defined in: [packages/common/src/Number.ts:8](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Number.ts#L8)
## Parameters
| Parameter | Type |
| --------- | -------- |
| `n` | `number` |
## Returns
`number`
isBetween - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Number](https://evolu.dev/docs/api-reference/common/Number) / isBetween
# Function: isBetween()
```ts
function isBetween(min, max): Predicate<number>;
```
Defined in: [packages/common/src/Number.ts:30](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Number.ts#L30)
Creates a predicate that checks if a number is within a range, inclusive.
### Example
```ts
const isBetween10And20 = isBetween(10, 20);
console.log(isBetween10And20(15)); // true
console.log(isBetween10And20(25)); // false
```
## Parameters
| Parameter | Type |
| --------- | -------- |
| `min` | `number` |
| `max` | `number` |
## Returns
[`Predicate`](https://evolu.dev/docs/api-reference/common/Types/type-aliases/Predicate)\<`number`\>
max - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Number](https://evolu.dev/docs/api-reference/common/Number) / max
# Function: max()
```ts
function max<T>(...values): IsBranded<T> extends true ? T : WidenLiteral<T>;
```
Defined in: [packages/common/src/Number.ts:41](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Number.ts#L41)
Returns the maximum value, preserving branded type if applicable.
## Type Parameters
| Type Parameter |
| ---------------------- |
| `T` _extends_ `number` |
## Parameters
| Parameter | Type |
| ----------- | ----------------- |
| ...`values` | \[`T`, `...T[]`\] |
## Returns
[`IsBranded`](https://evolu.dev/docs/api-reference/common/Brand/type-aliases/IsBranded)\<`T`\> _extends_ `true` ? `T` : [`WidenLiteral`](https://evolu.dev/docs/api-reference/common/Types/type-aliases/WidenLiteral)\<`T`\>
min - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Number](https://evolu.dev/docs/api-reference/common/Number) / min
# Function: min()
```ts
function min<T>(...values): IsBranded<T> extends true ? T : WidenLiteral<T>;
```
Defined in: [packages/common/src/Number.ts:35](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Number.ts#L35)
Returns the minimum value, preserving branded type if applicable.
## Type Parameters
| Type Parameter |
| ---------------------- |
| `T` _extends_ `number` |
## Parameters
| Parameter | Type |
| ----------- | ----------------- |
| ...`values` | \[`T`, `...T[]`\] |
## Returns
[`IsBranded`](https://evolu.dev/docs/api-reference/common/Brand/type-aliases/IsBranded)\<`T`\> _extends_ `true` ? `T` : [`WidenLiteral`](https://evolu.dev/docs/api-reference/common/Types/type-aliases/WidenLiteral)\<`T`\>
createRecord - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Object](https://evolu.dev/docs/api-reference/common/Object) / createRecord
# Function: createRecord()
```ts
function createRecord<K, V>(): Record<K, V>;
```
Defined in: [packages/common/src/Object.ts:88](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Object.ts#L88)
Creates a prototype-less object typed as `Record<K, V>`.
Use this function when you need a plain record without a prototype chain
(e.g. when keys are controlled by external sources) to avoid prototype
pollution and accidental collisions with properties like `__proto__`.
Example:
```ts
const values = createRecord<string, SqliteValue>();
values["__proto__"] = someValue; // safe, no prototype pollution
```
## Type Parameters
| Type Parameter | Default type |
| ---------------------- | ------------ |
| `K` _extends_ `string` | `string` |
| `V` | `unknown` |
## Returns
`Record`\<`K`, `V`\>
excludeProp - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Object](https://evolu.dev/docs/api-reference/common/Object) / excludeProp
# Function: excludeProp()
```ts
function excludeProp<T, K>(obj, prop, condition?): Omit<T, K>;
```
Defined in: [packages/common/src/Object.ts:62](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Object.ts#L62)
Conditionally excludes a property from an object.
## Type Parameters
| Type Parameter |
| ---------------------------------------------- |
| `T` _extends_ `object` |
| `K` _extends_ `string` \| `number` \| `symbol` |
## Parameters
| Parameter | Type |
| ------------ | --------- |
| `obj` | `T` |
| `prop` | `K` |
| `condition?` | `boolean` |
## Returns
`Omit`\<`T`, `K`\>
getProperty - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Object](https://evolu.dev/docs/api-reference/common/Object) / getProperty
# Function: getProperty()
```ts
function getProperty<K, V>(record, key): V | undefined;
```
Defined in: [packages/common/src/Object.ts:108](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Object.ts#L108)
Safely gets a property from a record, returning `undefined` if the key
doesn't exist.
TypeScript's `Record<K, V>` type assumes all keys exist, but at runtime
accessing a non-existent key returns `undefined`. This helper provides proper
typing for that case without needing a type assertion.
### Example
```ts
const users: Record<string, User> = { alice: { name: "Alice" } };
const user = getProperty(users, "bob"); // User | undefined
```
## Type Parameters
| Type Parameter |
| ---------------------- |
| `K` _extends_ `string` |
| `V` |
## Parameters
| Parameter | Type |
| --------- | ------------------------------------------------------------------------------------------------- |
| `record` | [`ReadonlyRecord`](https://evolu.dev/docs/api-reference/common/Object/type-aliases/ReadonlyRecord)\<`K`, `V`\> |
| `key` | `string` |
## Returns
`V` \| `undefined`
isPlainObject - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Object](https://evolu.dev/docs/api-reference/common/Object) / isPlainObject
# Function: isPlainObject()
```ts
function isPlainObject(value): value is Record<string, unknown>;
```
Defined in: [packages/common/src/Object.ts:13](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Object.ts#L13)
Checks if a value is a plain object (e.g., created with `{}` or `Object`).
### Example
```ts
isPlainObject({}); // true
isPlainObject(new Date()); // false
isPlainObject([]); // false
isPlainObject(null); // false
```
## Parameters
| Parameter | Type |
| --------- | --------- |
| `value` | `unknown` |
## Returns
`value is Record<string, unknown>`
mapObject - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Object](https://evolu.dev/docs/api-reference/common/Object) / mapObject
# Function: mapObject()
```ts
function mapObject<K, V, U>(record, fn): ReadonlyRecord<K, U>;
```
Defined in: [packages/common/src/Object.ts:50](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Object.ts#L50)
Maps a `ReadonlyRecord<K, V>` to a new `ReadonlyRecord<K, U>`, preserving
branded key types (e.g., `type Id = 'id' & string`) lost by `Object.entries`.
Uses `K extends string` for precision.
## Type Parameters
| Type Parameter |
| ---------------------- |
| `K` _extends_ `string` |
| `V` |
| `U` |
## Parameters
| Parameter | Type |
| --------- | ------------------------------------------------------------------------------------------------- |
| `record` | [`ReadonlyRecord`](https://evolu.dev/docs/api-reference/common/Object/type-aliases/ReadonlyRecord)\<`K`, `V`\> |
| `fn` | (`value`, `key`) => `U` |
## Returns
[`ReadonlyRecord`](https://evolu.dev/docs/api-reference/common/Object/type-aliases/ReadonlyRecord)\<`K`, `U`\>
objectToEntries - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Object](https://evolu.dev/docs/api-reference/common/Object) / objectToEntries
# Function: objectToEntries()
```ts
function objectToEntries<T>(
record,
): readonly [Extract<keyof T, string>, T[Extract<keyof T, string>]][];
```
Defined in: [packages/common/src/Object.ts:38](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Object.ts#L38)
Like `Object.entries` but preserves branded keys.
### Example
```ts
type UserId = string & { readonly __brand: "UserId" };
const users = createRecord<UserId, string>();
const entries = objectToEntries(users); // [UserId, string][]
```
## Type Parameters
| Type Parameter |
| ----------------------------------------- |
| `T` _extends_ `Record`\<`string`, `any`\> |
## Parameters
| Parameter | Type |
| --------- | ---- |
| `record` | `T` |
## Returns
readonly \[`Extract`\<keyof `T`, `string`\>, `T`\[`Extract`\<keyof `T`, `string`\>\]\][]
ReadonlyRecord - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Object](https://evolu.dev/docs/api-reference/common/Object) / ReadonlyRecord
# Type Alias: ReadonlyRecord\<K, V\>
```ts
type ReadonlyRecord<K, V> = Readonly<Record<K, V>>;
```
Defined in: [packages/common/src/Object.ts:22](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Object.ts#L22)
A read-only `Record<K, V>` with `K extends keyof any` to preserve branded key
types (e.g., in [mapObject](https://evolu.dev/docs/api-reference/common/Object/functions/mapObject)).
## Type Parameters
| Type Parameter |
| ------------------------- |
| `K` _extends_ keyof `any` |
| `V` |
createOrder - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Order](https://evolu.dev/docs/api-reference/common/Order) / createOrder
# Function: createOrder()
```ts
function createOrder<A>(isLessThan): Order<A>;
```
Defined in: [packages/common/src/Order.ts:32](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Order.ts#L32)
Creates an ordering function from a "less than" comparator.
### Example
```ts
const orderNumber = createOrder<number>((x, y) => x < y);
expect(orderNumber(1, 2)).toEqual(-1);
expect(orderNumber(2, 1)).toEqual(1);
expect(orderNumber(1, 1)).toEqual(0);
```
## Type Parameters
| Type Parameter |
| -------------- |
| `A` |
## Parameters
| Parameter | Type |
| ------------ | ----------------------- |
| `isLessThan` | (`x`, `y`) => `boolean` |
## Returns
[`Order`](https://evolu.dev/docs/api-reference/common/Order/type-aliases/Order)\<`A`\>
reverseOrder - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Order](https://evolu.dev/docs/api-reference/common/Order) / reverseOrder
# Function: reverseOrder()
```ts
function reverseOrder<A>(order): Order<A>;
```
Defined in: [packages/common/src/Order.ts:48](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Order.ts#L48)
Returns an order that reverses the order of the given order.
### Example
```ts
reverseOrder(orderNumber)(1, 2); // 1
reverseOrder(orderNumber)(2, 1); // -1
reverseOrder(orderNumber)(1, 1); // 0
```
## Type Parameters
| Type Parameter |
| -------------- |
| `A` |
## Parameters
| Parameter | Type |
| --------- | ------------------------------------------------------------------------- |
| `order` | [`Order`](https://evolu.dev/docs/api-reference/common/Order/type-aliases/Order)\<`A`\> |
## Returns
[`Order`](https://evolu.dev/docs/api-reference/common/Order/type-aliases/Order)\<`A`\>
Order - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Order](https://evolu.dev/docs/api-reference/common/Order) / Order
# Type Alias: Order()\<A\>
```ts
type Order<A> = (x, y) => Ordering;
```
Defined in: [packages/common/src/Order.ts:10](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Order.ts#L10)
Compares two values of type `A` and returns their ordering.
Ordering functions start with an 'order' prefix, e.g., `orderNumber`.
- Returns `-1` if `x` is less than `y`.
- Returns `0` if `x` is equal to `y`.
- Returns `1` if `x` is greater than `y`.
## Type Parameters
| Type Parameter |
| -------------- |
| `A` |
## Parameters
| Parameter | Type |
| --------- | ---- |
| `x` | `A` |
| `y` | `A` |
## Returns
[`Ordering`](https://evolu.dev/docs/api-reference/common/Order/type-aliases/Ordering)
Ordering - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Order](https://evolu.dev/docs/api-reference/common/Order) / Ordering
# Type Alias: Ordering
```ts
type Ordering = -1 | 0 | 1;
```
Defined in: [packages/common/src/Order.ts:17](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Order.ts#L17)
A type representing the result of an ordering operation.
Compatible with the return values expected by `Array.prototype.sort`.
orderBigInt - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Order](https://evolu.dev/docs/api-reference/common/Order) / orderBigInt
# Variable: orderBigInt
```ts
const orderBigInt: Order<bigint>;
```
Defined in: [packages/common/src/Order.ts:95](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Order.ts#L95)
An order for bigints in ascending order.
### Example
```ts
orderBigInt(1n, 2n); // -1
orderBigInt(2n, 1n); // 1
orderBigInt(1n, 1n); // 0
[2n, 1n, 3n].toSorted(orderBigInt); // [1n, 2n, 3n]
```
orderNumber - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Order](https://evolu.dev/docs/api-reference/common/Order) / orderNumber
# Variable: orderNumber
```ts
const orderNumber: Order<number>;
```
Defined in: [packages/common/src/Order.ts:81](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Order.ts#L81)
An order for numbers in ascending order.
### Example
```ts
orderNumber(1, 2); // -1
orderNumber(2, 1); // 1
orderNumber(1, 1); // 0
[2, 1, 3].toSorted(orderNumber); // [1, 2, 3]
reverseOrder(orderNumber)(1, 2); // 1
reverseOrder(orderNumber)(2, 1); // -1
reverseOrder(orderNumber)(1, 1); // 0
```
orderString - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Order](https://evolu.dev/docs/api-reference/common/Order) / orderString
# Variable: orderString
```ts
const orderString: Order<string>;
```
Defined in: [packages/common/src/Order.ts:64](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Order.ts#L64)
An order for `string` values in ascending order.
### Example
```ts
orderString("a", "b"); // -1
orderString("b", "a"); // 1
orderString("a", "a"); // 0
["c", "b", "a"].toSorted(orderString); // ["a", "b", "c"]
```
orderUint8Array - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Order](https://evolu.dev/docs/api-reference/common/Order) / orderUint8Array
# Variable: orderUint8Array
```ts
const orderUint8Array: Order<Uint8Array>;
```
Defined in: [packages/common/src/Order.ts:98](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Order.ts#L98)
An [Order](https://evolu.dev/docs/api-reference/common/Order/type-aliases/Order) for Uint8Array.
hasNodeBuffer - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Platform](https://evolu.dev/docs/api-reference/common/Platform) / hasNodeBuffer
# Variable: hasNodeBuffer
```ts
const hasNodeBuffer: boolean;
```
Defined in: [packages/common/src/Platform.ts:19](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Platform.ts#L19)
Detects if Node.js Buffer is available and should be used.
React Native apps often polyfill Node.js APIs like Buffer, but we want to use
native methods when available for better performance.
Returns false in React Native even if Buffer is polyfilled, as we prefer
native methods in that environment.
## See
https://github.com/craftzdog/react-native-quick-base64#installation
isReactNative - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Platform](https://evolu.dev/docs/api-reference/common/Platform) / isReactNative
# Variable: isReactNative
```ts
const isReactNative: boolean;
```
Defined in: [packages/common/src/Platform.ts:2](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Platform.ts#L2)
Detects if the code is running in React Native environment.
createRandom - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Random](https://evolu.dev/docs/api-reference/common/Random) / createRandom
# Function: createRandom()
```ts
function createRandom(): Random;
```
Defined in: [packages/common/src/Random.ts:30](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Random.ts#L30)
Creates a [Random](https://evolu.dev/docs/api-reference/common/Random/interfaces/Random) using Math.random().
## Returns
[`Random`](https://evolu.dev/docs/api-reference/common/Random/interfaces/Random)
createRandomLib - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Random](https://evolu.dev/docs/api-reference/common/Random) / createRandomLib
# Function: createRandomLib()
```ts
function createRandomLib(): Random;
```
Defined in: [packages/common/src/Random.ts:55](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Random.ts#L55)
Creates a `RandomLib` using the NPM `random` package.
## Returns
`Random`
createRandomLibWithSeed - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Random](https://evolu.dev/docs/api-reference/common/Random) / createRandomLibWithSeed
# Function: createRandomLibWithSeed()
```ts
function createRandomLibWithSeed(seed): RandomLibDep;
```
Defined in: [packages/common/src/Random.ts:61](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Random.ts#L61)
Creates [RandomLibDep](https://evolu.dev/docs/api-reference/common/Random/interfaces/RandomLibDep) using the NPM `random` package with a seed which
is useful for tests.
## Parameters
| Parameter | Type |
| --------- | -------- |
| `seed` | `string` |
## Returns
[`RandomLibDep`](https://evolu.dev/docs/api-reference/common/Random/interfaces/RandomLibDep)
createRandomWithSeed - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Random](https://evolu.dev/docs/api-reference/common/Random) / createRandomWithSeed
# Function: createRandomWithSeed()
```ts
function createRandomWithSeed(seed): Random;
```
Defined in: [packages/common/src/Random.ts:38](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Random.ts#L38)
Creates [Random](https://evolu.dev/docs/api-reference/common/Random/interfaces/Random) using [RandomLibDep](https://evolu.dev/docs/api-reference/common/Random/interfaces/RandomLibDep) with a seed which is useful
for tests.
## Parameters
| Parameter | Type |
| --------- | -------- |
| `seed` | `string` |
## Returns
[`Random`](https://evolu.dev/docs/api-reference/common/Random/interfaces/Random)
Random - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Random](https://evolu.dev/docs/api-reference/common/Random) / Random
# Interface: Random
Defined in: [packages/common/src/Random.ts:20](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Random.ts#L20)
A simple wrapper around Math.random().
For more complex needs check [RandomLibDep](https://evolu.dev/docs/api-reference/common/Random/interfaces/RandomLibDep).
### Example
```ts
// For apps
const random = createRandom();
random.next();
// For tests
const random = createRandomWithSeed("test");
random.next();
```
## Properties
| Property | Type | Description | Defined in |
| ------------------------ | -------------- | ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="next"></a> `next` | () => `number` | Returns a floating point number in [0, 1). Just like Math.random(). | [packages/common/src/Random.ts:22](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Random.ts#L22) |
RandomDep - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Random](https://evolu.dev/docs/api-reference/common/Random) / RandomDep
# Interface: RandomDep
Defined in: [packages/common/src/Random.ts:25](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Random.ts#L25)
## Properties
| Property | Type | Defined in |
| ---------------------------- | ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="random"></a> `random` | [`Random`](https://evolu.dev/docs/api-reference/common/Random/interfaces/Random) | [packages/common/src/Random.ts:26](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Random.ts#L26) |
RandomLibDep - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Random](https://evolu.dev/docs/api-reference/common/Random) / RandomLibDep
# Interface: RandomLibDep
Defined in: [packages/common/src/Random.ts:50](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Random.ts#L50)
A random number generator using the NPM `random` package dependency.
https://github.com/transitive-bullshit/random
## Properties
| Property | Type | Defined in |
| ---------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="random"></a> `random` | `Random` | [packages/common/src/Random.ts:51](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Random.ts#L51) |
createEqRedacted - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Redacted](https://evolu.dev/docs/api-reference/common/Redacted) / createEqRedacted
# Function: createEqRedacted()
```ts
function createEqRedacted<A>(eq): Eq<Redacted<A>>;
```
Defined in: [packages/common/src/Redacted.ts:116](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Redacted.ts#L116)
Creates an [Eq](https://evolu.dev/docs/api-reference/common/Eq/type-aliases/Eq) for [Redacted](https://evolu.dev/docs/api-reference/common/Redacted/interfaces/Redacted) values based on an equality function
for the underlying type.
### Example
```ts
type ApiKey = string & Brand<"ApiKey">;
const eqRedactedApiKey = createEqRedacted<ApiKey>(eqString);
const a = createRedacted("x" as ApiKey);
const b = createRedacted("x" as ApiKey);
eqRedactedApiKey(a, b); // true
```
## Type Parameters
| Type Parameter |
| -------------- |
| `A` |
## Parameters
| Parameter | Type |
| --------- | ---------------------------------------------------------------- |
| `eq` | [`Eq`](https://evolu.dev/docs/api-reference/common/Eq/type-aliases/Eq)\<`A`\> |
## Returns
[`Eq`](https://evolu.dev/docs/api-reference/common/Eq/type-aliases/Eq)\<[`Redacted`](https://evolu.dev/docs/api-reference/common/Redacted/interfaces/Redacted)\<`A`\>\>
createRedacted - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Redacted](https://evolu.dev/docs/api-reference/common/Redacted) / createRedacted
# Function: createRedacted()
```ts
function createRedacted<A>(value): Redacted<A>;
```
Defined in: [packages/common/src/Redacted.ts:65](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Redacted.ts#L65)
Creates a [Redacted](https://evolu.dev/docs/api-reference/common/Redacted/interfaces/Redacted) wrapper for a sensitive value.
## Type Parameters
| Type Parameter |
| -------------- |
| `A` |
## Parameters
| Parameter | Type |
| --------- | ---- |
| `value` | `A` |
## Returns
[`Redacted`](https://evolu.dev/docs/api-reference/common/Redacted/interfaces/Redacted)\<`A`\>
isRedacted - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Redacted](https://evolu.dev/docs/api-reference/common/Redacted) / isRedacted
# Function: isRedacted()
```ts
function isRedacted(value): value is Redacted<unknown>;
```
Defined in: [packages/common/src/Redacted.ts:95](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Redacted.ts#L95)
Checks if a value is a [Redacted](https://evolu.dev/docs/api-reference/common/Redacted/interfaces/Redacted) wrapper.
## Parameters
| Parameter | Type |
| --------- | --------- |
| `value` | `unknown` |
## Returns
`value is Redacted<unknown>`
revealRedacted - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Redacted](https://evolu.dev/docs/api-reference/common/Redacted) / revealRedacted
# Function: revealRedacted()
```ts
function revealRedacted<A>(redacted): A;
```
Defined in: [packages/common/src/Redacted.ts:89](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Redacted.ts#L89)
Reveals the original value from a [Redacted](https://evolu.dev/docs/api-reference/common/Redacted/interfaces/Redacted) wrapper.
This is a separate function rather than a method on [Redacted](https://evolu.dev/docs/api-reference/common/Redacted/interfaces/Redacted) to make
access visually explicit and easy to grep in code reviews. Accessing
sensitive values should feel intentional, not convenient.
## Type Parameters
| Type Parameter |
| -------------- |
| `A` |
## Parameters
| Parameter | Type |
| ---------- | -------------------------------------------------------------------------------- |
| `redacted` | [`Redacted`](https://evolu.dev/docs/api-reference/common/Redacted/interfaces/Redacted)\<`A`\> |
## Returns
`A`
Redacted - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Redacted](https://evolu.dev/docs/api-reference/common/Redacted) / Redacted
# Interface: Redacted\<A\>
Defined in: [packages/common/src/Redacted.ts:59](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Redacted.ts#L59)
**`Experimental`**
A wrapper type that prevents sensitive values from being accidentally exposed
through logging, serialization, or inspection.
The wrapped value is hidden and can only be accessed explicitly via
[revealRedacted](https://evolu.dev/docs/api-reference/common/Redacted/functions/revealRedacted). All standard methods (`toString`, `toJSON`, and
Node.js inspect) return `<redacted>`.
For type-level distinction between different secrets, use branded types.
The actual value lives in a `WeakMap`, so it never appears as a property and
is automatically garbage collected when the wrapper is dropped. This is
better than a class with a private field because private fields are still
visible in devtools. Symbols can't be used because they don't support custom
`toString`.
Implements `Disposable` for automatic cleanup via the `using` syntax.
### Example
```ts
// Define branded types for your secrets
type ApiKey = string & Brand<"ApiKey">;
type DbPassword = string & Brand<"DbPassword">;
// Wrap them with Redacted for safe passing
type RedactedApiKey = Redacted<ApiKey>;
type RedactedDbPassword = Redacted<DbPassword>;
// Create a redacted secret
const apiKey: ApiKey = "secret-123" as ApiKey;
const redactedKey: RedactedApiKey = createRedacted(apiKey);
console.log(redactedKey); // <redacted>
console.log(revealRedacted(redactedKey)); // secret-123
// Type safety: RedactedApiKey ≠ RedactedDbPassword
const fetchUser = (key: RedactedApiKey) => {
const value: ApiKey = revealRedacted(key);
// use value...
};
fetchUser(redactedKey); // ✅
// fetchUser(createRedacted("x" as DbPassword)); // ❌ type error
// Automatic cleanup with `using`
{
using secret = createRedacted("sensitive" as ApiKey);
// ... use secret ...
} // automatically wiped from memory
```
## Extends
- [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Redacted"`\>.`Disposable`
## Type Parameters
| Type Parameter |
| -------------- |
| `A` |
## Properties
| Property | Modifier | Type | Description | Inherited from | Defined in |
| ---------------------------------- | ---------- | ------------------------------------- | ----------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="___brand"></a> `[___brand]` | `readonly` | `Readonly`\<`Record`\<`B`, `true`\>\> | **`Experimental`** | [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand).[`[___brand]`](/docs/api-reference/common/Brand/interfaces/Brand.mdx#___brand) | [packages/common/src/Brand.ts:60](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Brand.ts#L60) |
| <a id="type"></a> `Type` | `readonly` | `A` | **`Experimental`** The inner type. Useful for inference via `typeof redacted.Type`. | - | [packages/common/src/Redacted.ts:61](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Redacted.ts#L61) |
## Methods
### \[dispose\]()
##
Defined in: node_modules/typescript/lib/lib.esnext.disposable.d.ts:36
**`Experimental`**
##### Returns
`void`
##### Inherited from
```ts
Disposable.[dispose]
```
##
Defined in: node_modules/@types/node/compatibility/disposable.d.ts:9
**`Experimental`**
##### Returns
`void`
##### Inherited from
```ts
Disposable.[dispose]
```
createRef - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Ref](https://evolu.dev/docs/api-reference/common/Ref) / createRef
# Function: createRef()
```ts
function createRef<T>(initialState): Ref<T>;
```
Defined in: [packages/common/src/Ref.ts:44](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Ref.ts#L44)
Creates a [Ref](https://evolu.dev/docs/api-reference/common/Ref/interfaces/Ref) with the given initial state.
## Type Parameters
| Type Parameter |
| -------------- |
| `T` |
## Parameters
| Parameter | Type |
| -------------- | ---- |
| `initialState` | `T` |
## Returns
[`Ref`](https://evolu.dev/docs/api-reference/common/Ref/interfaces/Ref)\<`T`\>
Ref - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Ref](https://evolu.dev/docs/api-reference/common/Ref) / Ref
# Interface: Ref\<T\>
Defined in: [packages/common/src/Ref.ts:32](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Ref.ts#L32)
`Ref` provides a simple API to hold and update a value, similar to a "ref" in
functional programming or React. It exposes methods to get, set, and modify
the current state.
Use a Ref instead of a variable when you want to pass state around as an
object or update it in a controlled way. If you need subscriptions, see
[Store](https://evolu.dev/docs/api-reference/common/Store/interfaces/Store).
Updating in a controlled way means all changes go through specific methods
(`set` or `modify`), making state updates predictable and easy to track.
### Example
```ts
const count = createRef(0);
count.set(1);
count.modify((n) => n + 1);
console.log(count.get()); // 2
```
### Example of using Ref as a dependency
```ts
interface CounterRefDep {
readonly counterRef: Ref<number>;
}
```
## Extended by
- [`Store`](https://evolu.dev/docs/api-reference/common/Store/interfaces/Store)
## Type Parameters
| Type Parameter |
| -------------- |
| `T` |
## Properties
| Property | Modifier | Type | Description | Defined in |
| ---------------------------- | ---------- | --------------------- | --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="get"></a> `get` | `readonly` | () => `T` | Returns the current state. | [packages/common/src/Ref.ts:34](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Ref.ts#L34) |
| <a id="modify"></a> `modify` | `readonly` | (`updater`) => `void` | Modifies the state using an updater function. | [packages/common/src/Ref.ts:40](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Ref.ts#L40) |
| <a id="set"></a> `set` | `readonly` | (`state`) => `void` | Sets the state. | [packages/common/src/Ref.ts:37](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Ref.ts#L37) |
createRelation - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Relation](https://evolu.dev/docs/api-reference/common/Relation) / createRelation
# Function: createRelation()
```ts
function createRelation<A, B>(): Relation<A, B>;
```
Defined in: [packages/common/src/Relation.ts:95](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Relation.ts#L95)
Creates a [Relation](https://evolu.dev/docs/api-reference/common/Relation/interfaces/Relation).
## Type Parameters
| Type Parameter |
| -------------- |
| `A` |
| `B` |
## Returns
[`Relation`](https://evolu.dev/docs/api-reference/common/Relation/interfaces/Relation)\<`A`, `B`\>
Relation - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Relation](https://evolu.dev/docs/api-reference/common/Relation) / Relation
# Interface: Relation\<A, B\>
Defined in: [packages/common/src/Relation.ts:35](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Relation.ts#L35)
Bidirectional relation between two types.
Why useful:
- Provides O(1) (amortized) lookup in both directions (A → B and B → A) without
maintaining two maps manually and risking them diverging.
- Natural fit for symmetric associations such as ownerId ↔ WebSocket, tag ↔
item, user ↔ role, entity ↔ subscription where both directions are
frequently queried.
- Supports fast membership tests via `has`, `hasA`, and `hasB`.
- Iteration helpers (`forEach`, iterator) allow treating the structure as a set
of pairs when needed.
Complexity:
- `add` / `remove` / `has*` / `get*` each perform a constant number of Map/Set
operations (O(1) expected).
- `deleteA` and `deleteB` are O(d) where d is the number of associated elements
(the degree). This is optimal because every associated pair must be touched
once.
Object identity:
- Elements are compared by reference (standard Map / Set semantics). Structural
hashing of objects in JavaScript is non-trivial, can be expensive, and
collision-prone if done naively. Prefer using stable primitive identifiers
(ids, strings) instead of attempting to hash full object structures.
- If structural equivalence is truly required, wrap objects in an adapter that
supplies a canonical hash/id and stores/retrieves the original objects
separately. This is a rare need; avoid unless you have clear requirements.
## Type Parameters
| Type Parameter |
| -------------- |
| `A` |
| `B` |
## Properties
| Property | Modifier | Type | Description | Defined in |
| ---------------------------------- | ---------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="iterator"></a> `[iterator]` | `readonly` | () => `IterableIterator`\<readonly \[`A`, `B`\]\> | Iterator over all pairs enabling for..of and spread. Yields readonly [a, b] tuples. | [packages/common/src/Relation.ts:64](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Relation.ts#L64) |
| <a id="acount"></a> `aCount` | `readonly` | () => `number` | Number of distinct A elements currently present. | [packages/common/src/Relation.ts:85](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Relation.ts#L85) |
| <a id="add"></a> `add` | `readonly` | (`a`, `b`) => `boolean` | Adds a pair to the relation. Returns true if the pair was newly added, false if it already existed. | [packages/common/src/Relation.ts:40](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Relation.ts#L40) |
| <a id="bcount"></a> `bCount` | `readonly` | () => `number` | Number of distinct B elements currently present. | [packages/common/src/Relation.ts:88](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Relation.ts#L88) |
| <a id="clear"></a> `clear` | `readonly` | () => `void` | Clears all pairs from the relation. | [packages/common/src/Relation.ts:82](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Relation.ts#L82) |
| <a id="deletea"></a> `deleteA` | `readonly` | (`a`) => `boolean` | Deletes all pairs containing the given A element. | [packages/common/src/Relation.ts:76](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Relation.ts#L76) |
| <a id="deleteb"></a> `deleteB` | `readonly` | (`b`) => `boolean` | Deletes all pairs containing the given B element. | [packages/common/src/Relation.ts:79](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Relation.ts#L79) |
| <a id="foreach"></a> `forEach` | `readonly` | (`callback`) => `void` | Iterates over each pair in the relation (in insertion order of A elements, then B elements per A). | [packages/common/src/Relation.ts:58](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Relation.ts#L58) |
| <a id="geta"></a> `getA` | `readonly` | (`b`) => `ReadonlySet`\<`A`\> \| `undefined` | Gets all A elements related to a B element. | [packages/common/src/Relation.ts:52](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Relation.ts#L52) |
| <a id="getb"></a> `getB` | `readonly` | (`a`) => `ReadonlySet`\<`B`\> \| `undefined` | Gets all B elements related to an A element. | [packages/common/src/Relation.ts:49](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Relation.ts#L49) |
| <a id="has"></a> `has` | `readonly` | (`a`, `b`) => `boolean` | Checks if a specific pair exists in the relation. | [packages/common/src/Relation.ts:67](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Relation.ts#L67) |
| <a id="hasa"></a> `hasA` | `readonly` | (`a`) => `boolean` | Checks if an A element exists in the relation. | [packages/common/src/Relation.ts:70](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Relation.ts#L70) |
| <a id="hasb"></a> `hasB` | `readonly` | (`b`) => `boolean` | Checks if a B element exists in the relation. | [packages/common/src/Relation.ts:73](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Relation.ts#L73) |
| <a id="remove"></a> `remove` | `readonly` | (`a`, `b`) => `boolean` | Removes a specific pair from the relation. Returns true if the pair existed and was removed, false if it was not present. | [packages/common/src/Relation.ts:46](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Relation.ts#L46) |
| <a id="size"></a> `size` | `readonly` | () => `number` | Number of pairs currently stored in the relation. | [packages/common/src/Relation.ts:91](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Relation.ts#L91) |
createResources - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Resources](https://evolu.dev/docs/api-reference/common/Resources) / createResources
# Function: createResources()
```ts
function createResources<
TResource,
TResourceKey,
TResourceConfig,
TConsumer,
TConsumerId,
>(
config,
): Resources<TResource, TResourceKey, TResourceConfig, TConsumer, TConsumerId>;
```
Defined in: [packages/common/src/Resources.ts:168](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Resources.ts#L168)
Creates [Resources](https://evolu.dev/docs/api-reference/common/Resources/interfaces/Resources).
This tracks which consumers are using which resources and maintains reference
counts to know when it's safe to dispose resources. Resources are created
on-demand and disposed with a configurable delay to avoid churn.
### Example Usage
```ts
// WebSocket connections
interface WebSocketConfig {
readonly url: WebSocketUrl;
}
type WebSocketUrl = string & Brand<"WebSocketUrl">;
type UserId = string & Brand<"UserId">;
const webSockets = createResources<
WebSocket,
WebSocketUrl,
WebSocketConfig,
User,
UserId
>({
createResource: (config) => new WebSocket(config.url),
getResourceKey: (config) => config.url,
getConsumerId: (user) => user.id,
disposalDelay: 1000,
});
// Add users to WebSocket connections
webSockets.addConsumer(user1, [
{ url: "ws://server1.com" as WebSocketUrl },
{ url: "ws://server2.com" as WebSocketUrl },
]);
webSockets.addConsumer(user2, [{ url: "ws://server1.com" as WebSocketUrl }]);
// Remove users - server1 stays alive (user2 still using it)
webSockets.removeConsumer(user1, [
{ url: "ws://server1.com" as WebSocketUrl },
{ url: "ws://server2.com" as WebSocketUrl },
]);
// server2 gets disposed after delay, server1 stays alive
```
## Type Parameters
| Type Parameter |
| ---------------------------------- |
| `TResource` _extends_ `Disposable` |
| `TResourceKey` _extends_ `string` |
| `TResourceConfig` |
| `TConsumer` |
| `TConsumerId` _extends_ `string` |
## Parameters
| Parameter | Type |
| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `config` | [`ResourcesConfig`](https://evolu.dev/docs/api-reference/common/Resources/interfaces/ResourcesConfig)\<`TResource`, `TResourceKey`, `TResourceConfig`, `TConsumer`, `TConsumerId`\> |
## Returns
[`Resources`](https://evolu.dev/docs/api-reference/common/Resources/interfaces/Resources)\<`TResource`, `TResourceKey`, `TResourceConfig`, `TConsumer`, `TConsumerId`\>
ConsumerNotFoundError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Resources](https://evolu.dev/docs/api-reference/common/Resources) / ConsumerNotFoundError
# Interface: ConsumerNotFoundError\<TConsumerId, TResourceKey\>
Defined in: [packages/common/src/Resources.ts:66](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Resources.ts#L66)
Error when trying to remove a consumer that wasn't added to a resource.
## Type Parameters
| Type Parameter | Default type |
| --------------------------------- | ------------ |
| `TConsumerId` _extends_ `string` | `string` |
| `TResourceKey` _extends_ `string` | `string` |
## Properties
| Property | Modifier | Type | Defined in |
| -------------------------------------- | ---------- | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="consumerid"></a> `consumerId` | `readonly` | `TConsumerId` | [packages/common/src/Resources.ts:71](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Resources.ts#L71) |
| <a id="resourcekey"></a> `resourceKey` | `readonly` | `TResourceKey` | [packages/common/src/Resources.ts:72](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Resources.ts#L72) |
| <a id="type"></a> `type` | `readonly` | `"ConsumerNotFoundError"` | [packages/common/src/Resources.ts:70](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Resources.ts#L70) |
ResourceNotFoundError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Resources](https://evolu.dev/docs/api-reference/common/Resources) / ResourceNotFoundError
# Interface: ResourceNotFoundError\<TResourceKey\>
Defined in: [packages/common/src/Resources.ts:60](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Resources.ts#L60)
Error when trying to remove a consumer from a resource that doesn't exist.
## Type Parameters
| Type Parameter | Default type |
| --------------------------------- | ------------ |
| `TResourceKey` _extends_ `string` | `string` |
## Properties
| Property | Modifier | Type | Defined in |
| -------------------------------------- | ---------- | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="resourcekey"></a> `resourceKey` | `readonly` | `TResourceKey` | [packages/common/src/Resources.ts:62](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Resources.ts#L62) |
| <a id="type"></a> `type` | `readonly` | `"ResourceNotFoundError"` | [packages/common/src/Resources.ts:61](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Resources.ts#L61) |
Resources - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Resources](https://evolu.dev/docs/api-reference/common/Resources) / Resources
# Interface: Resources\<TResource, TResourceKey, TResourceConfig, TConsumer, TConsumerId\>
Defined in: [packages/common/src/Resources.ts:9](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Resources.ts#L9)
A generic resource manager that handles reference counting and delayed
disposal of shared resources. Useful for managing expensive resources like
WebSocket connections that need to be shared among multiple consumers.
## Extends
- `Disposable`
## Type Parameters
| Type Parameter |
| ---------------------------------- |
| `TResource` _extends_ `Disposable` |
| `TResourceKey` _extends_ `string` |
| `TResourceConfig` |
| `TConsumer` |
| `TConsumerId` _extends_ `string` |
## Properties
| Property | Modifier | Type | Description | Defined in |
| -------------------------------------------------------------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="addconsumer"></a> `addConsumer` | `readonly` | (`consumer`, `resourceConfigs`) => `void` | Adds a consumer to resources, creating them if necessary. Increments reference counts for existing consumer-resource pairs. | [packages/common/src/Resources.ts:20](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Resources.ts#L20) |
| <a id="getconsumer"></a> `getConsumer` | `readonly` | (`consumerId`) => `TConsumer` \| `null` | Gets the consumer for the specified consumer ID, or null if not found or not using any resources. | [packages/common/src/Resources.ts:56](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Resources.ts#L56) |
| <a id="getconsumersforresource"></a> `getConsumersForResource` | `readonly` | (`key`) => readonly `TConsumerId`[] | Gets all consumer IDs currently using the specified resource key. | [packages/common/src/Resources.ts:45](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Resources.ts#L45) |
| <a id="getresource"></a> `getResource` | `readonly` | (`key`) => `TResource` \| `null` | Gets the resource for the specified key, or null if it doesn't exist. | [packages/common/src/Resources.ts:42](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Resources.ts#L42) |
| <a id="hasconsumeranyresource"></a> `hasConsumerAnyResource` | `readonly` | (`consumer`) => `boolean` | Checks if a consumer is currently using any resources. | [packages/common/src/Resources.ts:50](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Resources.ts#L50) |
| <a id="removeconsumer"></a> `removeConsumer` | `readonly` | (`consumer`, `resourceConfigs`) => [`Result`](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result)\<`void`, \| [`ResourceNotFoundError`](https://evolu.dev/docs/api-reference/common/Resources/interfaces/ResourceNotFoundError)\<`TResourceKey`\> \| [`ConsumerNotFoundError`](https://evolu.dev/docs/api-reference/common/Resources/interfaces/ConsumerNotFoundError)\<`TConsumerId`, `TResourceKey`\>\> | Removes a consumer from resources. Decrements reference counts and schedules disposal when no consumers remain. Returns an error if the resource doesn't exist or if the consumer wasn't added to the resource. | [packages/common/src/Resources.ts:32](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Resources.ts#L32) |
## Methods
### \[dispose\]()
##
Defined in: node_modules/typescript/lib/lib.esnext.disposable.d.ts:36
##### Returns
`void`
##### Inherited from
```ts
Disposable.[dispose]
```
##
Defined in: node_modules/@types/node/compatibility/disposable.d.ts:9
##### Returns
`void`
##### Inherited from
```ts
Disposable.[dispose]
```
ResourcesConfig - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Resources](https://evolu.dev/docs/api-reference/common/Resources) / ResourcesConfig
# Interface: ResourcesConfig\<TResource, TResourceKey, TResourceConfig, TConsumer, TConsumerId\>
Defined in: [packages/common/src/Resources.ts:75](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Resources.ts#L75)
## Type Parameters
| Type Parameter |
| ---------------------------------- |
| `TResource` _extends_ `Disposable` |
| `TResourceKey` _extends_ `string` |
| `TResourceConfig` |
| `TConsumer` |
| `TConsumerId` _extends_ `string` |
## Properties
| Property | Modifier | Type | Description | Defined in |
| --------------------------------------------------- | ---------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| <a id="createresource"></a> `createResource` | `readonly` | (`config`) => `TResource` | Creates a new resource for the given config. | [packages/common/src/Resources.ts:83](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Resources.ts#L83) |
| <a id="disposaldelay"></a> `disposalDelay?` | `readonly` | `number` | Delay in milliseconds before disposing unused resources. Helps avoid resource churn during rapid add/remove cycles. Defaults to 100ms. | [packages/common/src/Resources.ts:95](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Resources.ts#L95) |
| <a id="getconsumerid"></a> `getConsumerId` | `readonly` | (`consumer`) => `TConsumerId` | Extracts a unique identifier from a consumer for reference counting. | [packages/common/src/Resources.ts:89](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Resources.ts#L89) |
| <a id="getresourcekey"></a> `getResourceKey` | `readonly` | (`config`) => `TResourceKey` | Extracts a unique key from a resource config for deduplication. | [packages/common/src/Resources.ts:86](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Resources.ts#L86) |
| <a id="onconsumeradded"></a> `onConsumerAdded?` | `readonly` | (`consumer`, `resource`, `resourceKey`) => `void` | Called when a consumer is added to a resource for the first time. This happens when the consumer's reference count goes from 0 to 1 for this resource. | [packages/common/src/Resources.ts:102](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Resources.ts#L102) |
| <a id="onconsumerremoved"></a> `onConsumerRemoved?` | `readonly` | (`consumer`, `resource`, `resourceKey`) => `void` | Called when a consumer is completely removed from a resource. This happens when the consumer's reference count goes from 1 to 0 for this resource. | [packages/common/src/Resources.ts:112](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Resources.ts#L112) |
err - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Result](https://evolu.dev/docs/api-reference/common/Result) / err
# Function: err()
```ts
function err<E>(error): Err<E>;
```
Defined in: [packages/common/src/Result.ts:452](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Result.ts#L452)
Creates an [Err](https://evolu.dev/docs/api-reference/common/Result/interfaces/Err) result.
### Example
```ts
const failure = err("Something went wrong");
console.log(failure); // { ok: false, error: "Something went wrong" }
```
## Type Parameters
| Type Parameter |
| -------------- |
| `E` |
## Parameters
| Parameter | Type |
| --------- | ---- |
| `error` | `E` |
## Returns
[`Err`](https://evolu.dev/docs/api-reference/common/Result/interfaces/Err)\<`E`\>
getOrNull - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Result](https://evolu.dev/docs/api-reference/common/Result) / getOrNull
# Function: getOrNull()
```ts
function getOrNull<T, E>(result): T | null;
```
Defined in: [packages/common/src/Result.ts:505](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Result.ts#L505)
Extracts the value from a [Result](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result) if it is an `Ok`, or returns `null`
if it is an `Err`.
**Intended usage:**
- When you need to convert a `Result` to a nullable value for APIs that expect
`T | null`.
- When the error is not important and you just want the value or nothing.
### Example
```ts
const parseResult = parseJson('{"key": "value"}');
const value = getOrNull(parseResult);
// value is unknown | null
if (value != null) {
console.log("Parsed value:", value);
}
```
## Type Parameters
| Type Parameter |
| -------------- |
| `T` |
| `E` |
## Parameters
| Parameter | Type |
| --------- | --------------------------------------------------------------------------------- |
| `result` | [`Result`](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result)\<`T`, `E`\> |
## Returns
`T` \| `null`
getOrThrow - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Result](https://evolu.dev/docs/api-reference/common/Result) / getOrThrow
# Function: getOrThrow()
```ts
function getOrThrow<T, E>(result): T;
```
Defined in: [packages/common/src/Result.ts:475](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Result.ts#L475)
Extracts the value from a [Result](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result) if it is an `Ok`, or throws an error
if it is an `Err`.
**Intended usage:**
- For critical code paths (e.g., app startup, config values) where failure
should crash the app.
- Not recommended for general error handling in application logic—prefer
explicit checks.
### Example
```ts
// At app startup, crash if config is invalid:
const config = getOrThrow(loadConfig());
// Safe to use config here
```
Throws: `Error` with the original error attached as `cause`.
## Type Parameters
| Type Parameter |
| -------------- |
| `T` |
| `E` |
## Parameters
| Parameter | Type |
| --------- | --------------------------------------------------------------------------------- |
| `result` | [`Result`](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result)\<`T`, `E`\> |
## Returns
`T`
ok - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Result](https://evolu.dev/docs/api-reference/common/Result) / ok
# Function: ok()
Defined in: [packages/common/src/Result.ts:435](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Result.ts#L435)
Creates an [Ok](https://evolu.dev/docs/api-reference/common/Result/interfaces/Ok) result.
- `ok()` creates an `Ok<void>` for operations that succeed without producing a
value.
- `ok(value)` creates an `Ok<T>` containing the specified value.
### Example
```ts
const noValue = ok();
console.log(noValue); // { ok: true, value: undefined }
const success = ok(42);
console.log(success); // { ok: true, value: 42 }
```
### Returns
[`Ok`](https://evolu.dev/docs/api-reference/common/Result/interfaces/Ok)\<`void`\>
Defined in: [packages/common/src/Result.ts:437](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Result.ts#L437)
Creates an [Ok](https://evolu.dev/docs/api-reference/common/Result/interfaces/Ok) result with a specified value.
### Type Parameters
| Type Parameter |
| -------------- |
| `T` |
### Parameters
| Parameter | Type |
| --------- | ---- |
| `value` | `T` |
### Returns
[`Ok`](https://evolu.dev/docs/api-reference/common/Result/interfaces/Ok)\<`T`\>
tryAsync - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Result](https://evolu.dev/docs/api-reference/common/Result) / tryAsync
# Function: tryAsync()
```ts
function tryAsync<T, E>(promiseFn, mapError): Promise<Result<T, E>>;
```
Defined in: [packages/common/src/Result.ts:590](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Result.ts#L590)
Wraps async functions or any operation returning a promise, returning a
[Result](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result).
The `tryAsync` function provides a way to handle asynchronous code safely by
catching any rejected promises and mapping errors to a custom type. If the
promise resolves, it returns an `Ok` result. If the promise rejects, it maps
the error and returns an `Err` result.
### Example
```ts
interface FetchError {
readonly type: "FetchError";
readonly message: string;
}
const tryFetch = async (url: string): Promise<Result<unknown, FetchError>> =>
tryAsync(
async () => {
const response = await fetch(url);
if (!response.ok) {
throw new Error(`Request failed with status ${response.status}`);
}
return response.json();
},
(error) => ({
type: "FetchError",
message: String(error),
}),
);
const result = await tryFetch("https://jsonplaceholder.typicode.com/posts/1");
if (result.ok) {
console.log("Data:", result.value);
} else {
console.error("Error:", result.error);
}
```
## Type Parameters
| Type Parameter |
| -------------- |
| `T` |
| `E` |
## Parameters
| Parameter | Type |
| ----------- | ---------------------- |
| `promiseFn` | () => `Promise`\<`T`\> |
| `mapError` | (`error`) => `E` |
## Returns
`Promise`\<[`Result`](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result)\<`T`, `E`\>\>
trySync - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Result](https://evolu.dev/docs/api-reference/common/Result) / trySync
# Function: trySync()
```ts
function trySync<T, E>(fn, mapError): Result<T, E>;
```
Defined in: [packages/common/src/Result.ts:535](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Result.ts#L535)
Wraps synchronous functions that may throw exceptions, returning a
[Result](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result).
The `trySync` function is designed to handle synchronous code safely by
wrapping the execution in a try-catch block. If the function succeeds, it
returns an `Ok` result. If an exception is thrown, it maps the error to a
custom type and returns an `Err` result.
### Example
```ts
interface ParseJsonError {
readonly type: "ParseJsonError";
readonly message: string;
}
const parseJson = (value: string): Result<unknown, ParseJsonError> =>
trySync(
() => JSON.parse(value) as unknown,
(error): ParseJsonError => ({
type: "ParseJsonError",
message: String(error),
}),
);
```
## Type Parameters
| Type Parameter |
| -------------- |
| `T` |
| `E` |
## Parameters
| Parameter | Type |
| ---------- | ---------------- |
| `fn` | () => `T` |
| `mapError` | (`error`) => `E` |
## Returns
[`Result`](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result)\<`T`, `E`\>
Err - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Result](https://evolu.dev/docs/api-reference/common/Result) / Err
# Interface: Err\<E\>
Defined in: [packages/common/src/Result.ts:397](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Result.ts#L397)
An error [Result](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result).
The `error` property can be any type that describes the error. For normal
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 stack trace for debugging, use an `Error` instance or a custom
error class to include additional metadata.
### Examples
#### Domain logic error (plain object, recommended)
```ts
const failure = err({
type: "ParseJsonError",
code: 1001,
input: "foo",
});
```
#### Debugging with stack trace (error instance)
```ts
const failure = err(new Error("Something went wrong"));
```
#### Custom error class
```ts
class MyCustomError extends Error {
constructor(
public code: number,
public input: string,
) {
super(`Error ${code} on input: ${input}`);
this.name = "MyCustomError";
}
}
const failure = err(new MyCustomError(404, "bad-input"));
```
## Type Parameters
| Type Parameter |
| -------------- |
| `E` |
## Properties
| Property | Modifier | Type | Defined in |
| -------------------------- | ---------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| <a id="error"></a> `error` | `readonly` | `E` | [packages/common/src/Result.ts:399](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Result.ts#L399) |
| <a id="ok"></a> `ok` | `readonly` | `false` | [packages/common/src/Result.ts:398](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Result.ts#L398) |
Ok - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Result](https://evolu.dev/docs/api-reference/common/Result) / Ok
# Interface: Ok\<T\>
Defined in: [packages/common/src/Result.ts:348](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Result.ts#L348)
A successful [Result](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result).
## Type Parameters
| Type Parameter |
| -------------- |
| `T` |
## Properties
| Property | Modifier | Type | Defined in |
| -------------------------- | ---------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| <a id="ok"></a> `ok` | `readonly` | `true` | [packages/common/src/Result.ts:349](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Result.ts#L349) |
| <a id="value"></a> `value` | `readonly` | `T` | [packages/common/src/Result.ts:350](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Result.ts#L350) |
InferErr - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Result](https://evolu.dev/docs/api-reference/common/Result) / InferErr
# Type Alias: InferErr\<R\>
```ts
type InferErr<R> = R extends Err<infer E> ? E : never;
```
Defined in: [packages/common/src/Result.ts:415](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Result.ts#L415)
Extracts the error type from a [Result](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result).
## Type Parameters
| Type Parameter |
| --------------------------------------------------------------------------------------------------- |
| `R` _extends_ [`Result`](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result)\<`any`, `any`\> |
InferOk - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Result](https://evolu.dev/docs/api-reference/common/Result) / InferOk
# Type Alias: InferOk\<R\>
```ts
type InferOk<R> = R extends Ok<infer T> ? T : never;
```
Defined in: [packages/common/src/Result.ts:407](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Result.ts#L407)
Extracts the value type from a [Result](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result).
## Type Parameters
| Type Parameter |
| --------------------------------------------------------------------------------------------------- |
| `R` _extends_ [`Result`](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result)\<`any`, `any`\> |
Result - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Result](https://evolu.dev/docs/api-reference/common/Result) / Result
# Type Alias: Result\<T, E\>
```ts
type Result<T, E> = Ok<T> | Err<E>;
```
Defined in: [packages/common/src/Result.ts:345](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Result.ts#L345)
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.
The `Result` type can be either [Ok](https://evolu.dev/docs/api-reference/common/Result/interfaces/Ok) (success) or [Err](https://evolu.dev/docs/api-reference/common/Result/interfaces/Err) (error).
Use [ok](https://evolu.dev/docs/api-reference/common/Result/functions/ok) to create a successful result and [err](https://evolu.dev/docs/api-reference/common/Result/functions/err) to create an error
result.
Now let's look at how `Result` can be used for safe JSON parsing:
```ts
interface ParseJsonError {
readonly type: "ParseJsonError";
readonly message: string;
}
const parseJson = (value: string): Result<unknown, ParseJsonError> => {
try {
return ok(JSON.parse(value));
} catch (error) {
return err({ type: "ParseJsonError", message: String(error) });
}
};
// Result<unknown, ParseJsonError>
const json = parseJson('{"key": "value"}');
// Fail fast to handle errors early.
if (!json.ok) return json; // Err<ParseJsonError>
// Now, we have access to the json.value.
expectTypeOf(json.value).toBeUnknown();
```
Note how we didn't have to use the try/catch, just `if (!json.ok)`, and how
the error isn't unknown but has a type.
But we had to use `try/catch` in the `parseJson` function. For such a case,
wrapping unsafe code, Evolu provides the [trySync](https://evolu.dev/docs/api-reference/common/Result/functions/trySync) helper:
```ts
const parseJson = (value: string): Result<unknown, ParseJsonError> =>
trySync(
() => JSON.parse(value) as unknown,
(error) => ({ type: "ParseJsonError", message: String(error) }),
);
```
✨ [trySync](https://evolu.dev/docs/api-reference/common/Result/functions/trySync) helper makes unsafe (can throw) synchronous code safe; for
unsafe asynchronous code, use [tryAsync](https://evolu.dev/docs/api-reference/common/Result/functions/tryAsync).
Let's summarize it:
- For safe code, use `ok` and `err`.
- For unsafe code, use `trySync` or `tryAsync`.
Safe asynchronous code (using Result with a Promise):
```ts
const fetchUser = async (
userId: string,
): Promise<Result<User, FetchUserError>> => {
// Simulate an API call
return new Promise((resolve) => {
setTimeout(() => {
if (userId === "1") {
resolve(ok({ id: "1", name: "Alice" }));
} else {
resolve(err({ type: "FetchUserError", reason: "user not found" }));
}
}, 1000);
});
};
```
For lazy, cancellable async operations, see [Task](https://evolu.dev/docs/api-reference/common/Task/interfaces/Task).
### Naming convention
- **For values you need:** use a name without Result suffix (`user`, `config`)
- **For void operations:** use `result` (no value to name)
For multiple void operations, use block scopes to avoid potentially long
names like `createBaseTablesResult`, `createRelayTablesResult`, or counters
like `result1`, `result2`:
```ts
const processUser = () => {
const user = getUser();
if (!user.ok) return user;
const result = saveToDatabase(user.value);
if (!result.ok) return result;
return ok();
};
const setupDatabase = () => {
// Multiple void operations - use block scopes to avoid name clash
{
const result = createBaseTables();
if (!result.ok) return result;
}
{
const result = createRelayTables();
if (!result.ok) return result;
}
return ok();
};
```
### Examples
#### 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.
Here's an example of a database reset operation that drops tables, restores a
schema, and initializes the database, stopping on the first error:
```ts
const result = deps.sqlite.transaction(() => {
const result = dropAllTables(deps);
if (!result.ok) return result;
if (message.restore) {
const dbSchema = getDbSchema(deps)();
if (!dbSchema.ok) return dbSchema;
{
const result = ensureDbSchema(deps)(
message.restore.dbSchema,
dbSchema.value,
);
if (!result.ok) return result;
}
{
const result = initializeDb(deps)(message.restore.mnemonic);
if (!result.ok) return result;
}
}
return ok();
});
if (!result.ok) {
deps.postMessage({ type: "onError", error: result.error });
return;
}
```
In this pattern:
- Each operation returns a `Result` (e.g., `Result<void, E>` or `Result<T,
E>`).
- After each operation, check `if (!result.ok)` and return the `Err` to
short-circuit.
- If all operations succeed, return `ok()` (or another value if needed).
- Outside the transaction, handle the final `Result` to report success or
failure.
This approach ensures type-safe error handling, avoids nested try/catch
blocks, and clearly communicates the control flow.
#### A function with two different errors:
```ts
const example = (value: string): Result<number, FooError | BarError> => {
const foo = getFoo(value);
if (!foo.ok) return foo;
const bar = getBar(foo.value);
if (!bar.ok) return bar;
return ok(barToNumber(bar.value));
};
```
### 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
cases. These should be logged for debugging, but **unexpected errors are not
recoverable** - they represent bugs that must be fixed.
**Important**: "Graceful shutdown" and error recovery can only come from
expected errors handled via the `Result` type. Unexpected errors should fail
fast - the operation fails immediately and the error bubbles up.
#### In browser environments
```ts
// Global error handler for unexpected errors
window.addEventListener("error", (event) => {
console.error("Uncaught error:", event.error);
// Send to error reporting service
errorReportingService.report(event.error);
});
// For unhandled promise rejections
window.addEventListener("unhandledrejection", (event) => {
console.error("Unhandled promise rejection:", event.reason);
errorReportingService.report(event.reason);
});
```
#### In Node.js environments
```ts
// Handle uncaught exceptions - log and fail fast
process.on("uncaughtException", (error) => {
console.error("Uncaught exception:", error);
errorReportingService.report(error);
// Exit immediately - unexpected errors are not recoverable
process.exit(1);
});
// Handle unhandled promise rejections
process.on("unhandledRejection", (reason) => {
console.error("Unhandled promise rejection:", reason);
errorReportingService.report(reason);
});
```
These global handlers serve as a safety net to log and report unexpected
errors for debugging purposes. They do not attempt recovery - unexpected
errors represent bugs that must be fixed. The discipline of explicit error
handling through the `Result` pattern remains the primary approach for all
recoverable scenarios.
### FAQ
#### When should a function return a plain value instead of `Result<T, E>`?
Use `Result<T, E>` only when a function can fail with **known, expected
errors** that callers need to handle. If a function cannot fail with a known
error, return the value directly.
- ✅ Return `Result<User, UserNotFoundError>` - can fail with a known error
- ✅ Return `User` - cannot fail with a known error
- ❌ Don't return `Result<User, never>` - unnecessary wrapper
This keeps the codebase clean and makes error handling intentional. The type
system communicates which operations can fail and which cannot.
Unsafe code from external libraries (not under our control) should be wrapped
with `trySync` or `tryAsync` at the boundaries. Once wrapped, if the error is
not important to callers, functions can safely return plain values. If the
error matters, use `Result` with a typed error.
```ts
// ✅ Safe to return void - unsafe code is wrapped and error is handled
const processData = (data: string): void => {
const result = trySync(
() => JSON.parse(data),
(error) => ({ type: "ParseError", message: String(error) }),
);
if (!result.ok) {
logError(result.error);
return;
}
// Continue with safe operations...
};
// ✅ Can call without try-catch since it returns void
processData(jsonString);
```
#### What if my function doesn't return a value on success?
If your function performs an operation but doesn't need to return a value on
success, you can use `Result<void, E>`. Using `Result<void, E>` is clearer
than using `Result<true, E>` or `Result<null, E>` because it communicates
that the function doesn't produce a value but can produce errors.
#### How do I short-circuit processing of an array on the first error?
If you want to stop processing as soon as an error occurs (short-circuit),
you should produce and check each `Result` inside a loop:
```ts
for (const query of [
sql`drop table evolu_config;`,
sql`drop table evolu_message;`,
]) {
const result = deps.sqlite.exec(query);
if (!result.ok) return result;
}
// All queries succeeded
```
#### How do I handle an array of operations and short-circuit on the first error?
If you have an array of operations (not results), you should make them
_lazy_—that is, represent each operation as a function. This way, you only
execute each operation as needed, and can stop on the first error:
```ts
const operations: LazyValue<Result<void, MyError>>[] = [
() => doSomething(),
() => doSomethingElse(),
];
for (const op of operations) {
const result = op();
if (!result.ok) return result;
}
// All operations succeeded
```
If you already have an array of `Result`s, the processing has already
happened, so you can't short-circuit. In that case, you can check for the
first error:
```ts
const firstError = results.find((r) => !r.ok);
if (firstError) return firstError;
// All results are Ok
```
### Why doesn't Evolu provide "handy helpers"?
Evolu intentionally favors imperative patterns (like the `for...of` loop
above) over monadic helpers. Imperative code is generally more readable,
easier to debug, and more familiar to most JavaScript and TypeScript
developers. While monads and functional helpers can be powerful, they often
obscure control flow and make debugging harder.
## Type Parameters
| Type Parameter |
| -------------- |
| `T` |
| `E` |
booleanToSqliteBoolean - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Sqlite](https://evolu.dev/docs/api-reference/common/Sqlite) / booleanToSqliteBoolean
# Function: booleanToSqliteBoolean()
```ts
function booleanToSqliteBoolean(value): 0 | 1;
```
Defined in: [packages/common/src/Sqlite.ts:561](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Sqlite.ts#L561)
Converts a JavaScript boolean to a [SqliteBoolean](https://evolu.dev/docs/api-reference/common/Sqlite/variables/SqliteBoolean).
### Example
```ts
const isActive = true;
const sqlValue = booleanToSqliteBoolean(isActive); // Returns 1
```
## Parameters
| Parameter | Type |
| --------- | --------- |
| `value` | `boolean` |
## Returns
`0` \| `1`
createPreparedStatementsCache - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Sqlite](https://evolu.dev/docs/api-reference/common/Sqlite) / createPreparedStatementsCache
# Function: createPreparedStatementsCache()
```ts
function createPreparedStatementsCache<P>(
factory,
disposeFn,
): PreparedStatements<P>;
```
Defined in: [packages/common/src/Sqlite.ts:277](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Sqlite.ts#L277)
## Type Parameters
| Type Parameter |
| -------------- |
| `P` |
## Parameters
| Parameter | Type |
| ----------- | ----------------------- |
| `factory` | (`sql`) => `P` |
| `disposeFn` | (`statement`) => `void` |
## Returns
[`PreparedStatements`](https://evolu.dev/docs/api-reference/common/Sqlite/interfaces/PreparedStatements)\<`P`\>
createSqlite - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Sqlite](https://evolu.dev/docs/api-reference/common/Sqlite) / createSqlite
# Function: createSqlite()
```ts
function createSqlite(
deps,
): (name, options?) => Promise<Result<Sqlite, SqliteError>>;
```
Defined in: [packages/common/src/Sqlite.ts:146](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Sqlite.ts#L146)
Creates a fully featured [Sqlite](https://evolu.dev/docs/api-reference/common/Sqlite/interfaces/Sqlite) instance from a [SqliteDriver](https://evolu.dev/docs/api-reference/common/Sqlite/interfaces/SqliteDriver)
implementation.
## Parameters
| Parameter | Type |
| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `deps` | [`CreateSqliteDriverDep`](https://evolu.dev/docs/api-reference/common/Sqlite/interfaces/CreateSqliteDriverDep) & `Partial`\<[`ConsoleDep`](https://evolu.dev/docs/api-reference/common/Console/interfaces/ConsoleDep)\> |
## Returns
```ts
(name, options?): Promise<Result<Sqlite, SqliteError>>;
```
### Parameters
| Parameter | Type |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name` | `string` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"UrlSafeString"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"SimpleName"`\> |
| `options?` | [`SqliteDriverOptions`](https://evolu.dev/docs/api-reference/common/Sqlite/interfaces/SqliteDriverOptions) |
### Returns
`Promise`\<[`Result`](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result)\<[`Sqlite`](https://evolu.dev/docs/api-reference/common/Sqlite/interfaces/Sqlite), [`SqliteError`](https://evolu.dev/docs/api-reference/common/Sqlite/interfaces/SqliteError)\>\>
explainSqliteQueryPlan - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Sqlite](https://evolu.dev/docs/api-reference/common/Sqlite) / explainSqliteQueryPlan
# Function: explainSqliteQueryPlan()
```ts
function explainSqliteQueryPlan(deps): (query) => Result<void, SqliteError>;
```
Defined in: [packages/common/src/Sqlite.ts:483](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Sqlite.ts#L483)
## Parameters
| Parameter | Type |
| --------- | ------------------------------------------------------------------------- |
| `deps` | [`SqliteDep`](https://evolu.dev/docs/api-reference/common/Sqlite/interfaces/SqliteDep) |
## Returns
```ts
(query): Result<void, SqliteError>;
```
### Parameters
| Parameter | Type |
| --------- | ----------------------------------------------------------------------------- |
| `query` | [`SqliteQuery`](https://evolu.dev/docs/api-reference/common/Sqlite/interfaces/SqliteQuery) |
### Returns
[`Result`](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result)\<`void`, [`SqliteError`](https://evolu.dev/docs/api-reference/common/Sqlite/interfaces/SqliteError)\>
sql - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Sqlite](https://evolu.dev/docs/api-reference/common/Sqlite) / sql
# Function: sql()
```ts
function sql(strings, ...parameters): SqliteQuery;
```
Defined in: [packages/common/src/Sqlite.ts:355](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Sqlite.ts#L355)
Creates a safe SQL query using a tagged template literal.
Parameters are automatically escaped and bound as SQLite values. Use
`sql.identifier` for column/table names and `sql.raw` for unescaped SQL.
### Example
```ts
const id = 42;
const name = "Alice";
const result = sqlite.exec(sql`
select *
from users
where id = ${id} and name = ${name};
`);
// For identifiers
const tableName = "users";
sqlite.exec(sql`
create table ${sql.identifier(tableName)} (
"id" text primary key,
"name" text not null
);
`);
// For raw SQL (use with caution)
const orderBy = "created_at desc";
sqlite.exec(sql`select * from users order by ${sql.raw(orderBy)};`);
```
### TIP
Use `prettier-plugin-sql-cst` for SQL formatting. Like Prettier for
JavaScript, this plugin formats SQL expressions differently depending on
their length.
## Parameters
| Parameter | Type |
| --------------- | ------------------------------------------------------------------------------------------- |
| `strings` | `TemplateStringsArray` |
| ...`parameters` | [`SqlTemplateParam`](https://evolu.dev/docs/api-reference/common/Sqlite/type-aliases/SqlTemplateParam)[] |
## Returns
[`SqliteQuery`](https://evolu.dev/docs/api-reference/common/Sqlite/interfaces/SqliteQuery)
sqliteBooleanToBoolean - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Sqlite](https://evolu.dev/docs/api-reference/common/Sqlite) / sqliteBooleanToBoolean
# Function: sqliteBooleanToBoolean()
```ts
function sqliteBooleanToBoolean(value): boolean;
```
Defined in: [packages/common/src/Sqlite.ts:574](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Sqlite.ts#L574)
Converts a [SqliteBoolean](https://evolu.dev/docs/api-reference/common/Sqlite/variables/SqliteBoolean) to a JavaScript boolean.
### Example
```ts
const sqlValue: SqliteBoolean = 1;
const bool = sqliteBooleanToBoolean(sqlValue); // Returns true
```
## Parameters
| Parameter | Type |
| --------- | ---------- |
| `value` | `0` \| `1` |
## Returns
`boolean`
CreateSqliteDriverDep - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Sqlite](https://evolu.dev/docs/api-reference/common/Sqlite) / CreateSqliteDriverDep
# Interface: CreateSqliteDriverDep
Defined in: [packages/common/src/Sqlite.ts:33](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Sqlite.ts#L33)
## Properties
| Property | Modifier | Type | Defined in |
| ---------------------------------------------------- | ---------- | --------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="createsqlitedriver"></a> `createSqliteDriver` | `readonly` | [`CreateSqliteDriver`](https://evolu.dev/docs/api-reference/common/Sqlite/type-aliases/CreateSqliteDriver) | [packages/common/src/Sqlite.ts:34](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Sqlite.ts#L34) |
PreparedStatements - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Sqlite](https://evolu.dev/docs/api-reference/common/Sqlite) / PreparedStatements
# Interface: PreparedStatements\<P\>
Defined in: [packages/common/src/Sqlite.ts:270](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Sqlite.ts#L270)
## Extends
- `Disposable`
## Type Parameters
| Type Parameter |
| -------------- |
| `P` |
## Properties
| Property | Modifier | Type | Defined in |
| ---------------------- | ---------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| <a id="get"></a> `get` | `readonly` | \<`T`\>(`query`, `alwaysPrepare?`) => `T` _extends_ `true` ? `P` : `P` \| `null` | [packages/common/src/Sqlite.ts:271](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Sqlite.ts#L271) |
## Methods
### \[dispose\]()
##
Defined in: node_modules/typescript/lib/lib.esnext.disposable.d.ts:36
##### Returns
`void`
##### Inherited from
```ts
Disposable.[dispose]
```
##
Defined in: node_modules/@types/node/compatibility/disposable.d.ts:9
##### Returns
`void`
##### Inherited from
```ts
Disposable.[dispose]
```
RawSql - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Sqlite](https://evolu.dev/docs/api-reference/common/Sqlite) / RawSql
# Interface: RawSql
Defined in: [packages/common/src/Sqlite.ts:310](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Sqlite.ts#L310)
## Properties
| Property | Modifier | Type | Defined in |
| ------------------------ | ---------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| <a id="sql"></a> `sql` | `readonly` | `string` | [packages/common/src/Sqlite.ts:312](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Sqlite.ts#L312) |
| <a id="type"></a> `type` | `readonly` | `"RawSql"` | [packages/common/src/Sqlite.ts:311](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Sqlite.ts#L311) |
SqlIdentifier - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Sqlite](https://evolu.dev/docs/api-reference/common/Sqlite) / SqlIdentifier
# Interface: SqlIdentifier
Defined in: [packages/common/src/Sqlite.ts:305](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Sqlite.ts#L305)
## Properties
| Property | Modifier | Type | Defined in |
| ------------------------ | ---------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| <a id="sql"></a> `sql` | `readonly` | [`SafeSql`](https://evolu.dev/docs/api-reference/common/Sqlite/type-aliases/SafeSql) | [packages/common/src/Sqlite.ts:307](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Sqlite.ts#L307) |
| <a id="type"></a> `type` | `readonly` | `"SqlIdentifier"` | [packages/common/src/Sqlite.ts:306](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Sqlite.ts#L306) |
Sqlite - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Sqlite](https://evolu.dev/docs/api-reference/common/Sqlite) / Sqlite
# Interface: Sqlite
Defined in: [packages/common/src/Sqlite.ts:50](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Sqlite.ts#L50)
Cross-platform SQLite abstraction.
This API is sync only because SQLite is an embedded, single-threaded engine.
All operations are blocking and in-process, so async APIs add needless
complexity without any real benefit and are also slower. Check better-sqlite3
GitHub issues and docs for details.
## Extends
- `Disposable`
## Properties
| Property | Modifier | Type | Description | Defined in |
| -------------------------------------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="exec"></a> `exec` | `readonly` | \<`R`\>(`query`) => [`Result`](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result)\<[`SqliteExecResult`](https://evolu.dev/docs/api-reference/common/Sqlite/interfaces/SqliteExecResult)\<`R`\>, [`SqliteError`](https://evolu.dev/docs/api-reference/common/Sqlite/interfaces/SqliteError)\> | - | [packages/common/src/Sqlite.ts:51](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Sqlite.ts#L51) |
| <a id="export"></a> `export` | `readonly` | () => [`Result`](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result)\<`Uint8Array`\<`ArrayBufferLike`\>, [`SqliteError`](https://evolu.dev/docs/api-reference/common/Sqlite/interfaces/SqliteError)\> | - | [packages/common/src/Sqlite.ts:65](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Sqlite.ts#L65) |
| <a id="transaction"></a> `transaction` | `readonly` | \<`T`, `E`\>(`callback`) => [`Result`](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result)\<`T`, \| [`SqliteError`](https://evolu.dev/docs/api-reference/common/Sqlite/interfaces/SqliteError) \| `E`\> | Executes a transaction, running the provided callback within a begin/commit block. If the callback returns an error (E or [SqliteError](https://evolu.dev/docs/api-reference/common/Sqlite/interfaces/SqliteError)), the transaction is rolled back. If the rollback fails, a SqliteError is returned with both the original error and rollbackError. | [packages/common/src/Sqlite.ts:61](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Sqlite.ts#L61) |
## Methods
### \[dispose\]()
##
Defined in: node_modules/typescript/lib/lib.esnext.disposable.d.ts:36
##### Returns
`void`
##### Inherited from
```ts
Disposable.[dispose]
```
##
Defined in: node_modules/@types/node/compatibility/disposable.d.ts:9
##### Returns
`void`
##### Inherited from
```ts
Disposable.[dispose]
```
SqliteDep - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Sqlite](https://evolu.dev/docs/api-reference/common/Sqlite) / SqliteDep
# Interface: SqliteDep
Defined in: [packages/common/src/Sqlite.ts:68](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Sqlite.ts#L68)
## Properties
| Property | Modifier | Type | Defined in |
| ---------------------------- | ---------- | ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="sqlite"></a> `sqlite` | `readonly` | [`Sqlite`](https://evolu.dev/docs/api-reference/common/Sqlite/interfaces/Sqlite) | [packages/common/src/Sqlite.ts:69](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Sqlite.ts#L69) |
SqliteDriver - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Sqlite](https://evolu.dev/docs/api-reference/common/Sqlite) / SqliteDriver
# Interface: SqliteDriver
Defined in: [packages/common/src/Sqlite.ts:23](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Sqlite.ts#L23)
SQLite driver interface. This is the minimal interface that platform-specific
drivers must implement.
## Extends
- `Disposable`
## Properties
| Property | Modifier | Type | Defined in |
| ---------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="exec"></a> `exec` | `readonly` | (`query`, `isMutation`) => [`SqliteExecResult`](https://evolu.dev/docs/api-reference/common/Sqlite/interfaces/SqliteExecResult) | [packages/common/src/Sqlite.ts:24](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Sqlite.ts#L24) |
| <a id="export"></a> `export` | `readonly` | () => `Uint8Array` | [packages/common/src/Sqlite.ts:25](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Sqlite.ts#L25) |
## Methods
### \[dispose\]()
##
Defined in: node_modules/typescript/lib/lib.esnext.disposable.d.ts:36
##### Returns
`void`
##### Inherited from
```ts
Disposable.[dispose]
```
##
Defined in: node_modules/@types/node/compatibility/disposable.d.ts:9
##### Returns
`void`
##### Inherited from
```ts
Disposable.[dispose]
```
SqliteDriverOptions - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Sqlite](https://evolu.dev/docs/api-reference/common/Sqlite) / SqliteDriverOptions
# Interface: SqliteDriverOptions
Defined in: [packages/common/src/Sqlite.ts:37](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Sqlite.ts#L37)
## Properties
| Property | Modifier | Type | Defined in |
| ------------------------------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="encryptionkey"></a> `encryptionKey?` | `readonly` | `Uint8Array`\<`ArrayBufferLike`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Entropy"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Length32"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"EncryptionKey"`\> | [packages/common/src/Sqlite.ts:39](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Sqlite.ts#L39) |
| <a id="memory"></a> `memory?` | `readonly` | `boolean` | [packages/common/src/Sqlite.ts:38](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Sqlite.ts#L38) |
SqliteError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Sqlite](https://evolu.dev/docs/api-reference/common/Sqlite) / SqliteError
# Interface: SqliteError
Defined in: [packages/common/src/Sqlite.ts:133](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Sqlite.ts#L133)
Represents an error that occurred during a SQLite operation.
## Properties
| Property | Modifier | Type | Defined in |
| ------------------------------------------- | ---------- | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| <a id="error"></a> `error` | `readonly` | [`TransferableError`](https://evolu.dev/docs/api-reference/common/Error/interfaces/TransferableError) | [packages/common/src/Sqlite.ts:135](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Sqlite.ts#L135) |
| <a id="rollbackerror"></a> `rollbackError?` | `readonly` | [`TransferableError`](https://evolu.dev/docs/api-reference/common/Error/interfaces/TransferableError) | [packages/common/src/Sqlite.ts:136](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Sqlite.ts#L136) |
| <a id="type"></a> `type` | `readonly` | `"SqliteError"` | [packages/common/src/Sqlite.ts:134](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Sqlite.ts#L134) |
SqliteExecResult - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Sqlite](https://evolu.dev/docs/api-reference/common/Sqlite) / SqliteExecResult
# Interface: SqliteExecResult\<R\>
Defined in: [packages/common/src/Sqlite.ts:127](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Sqlite.ts#L127)
Result of executing a SQLite query.
## Type Parameters
| Type Parameter | Default type |
| ----------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| `R` _extends_ [`SqliteRow`](https://evolu.dev/docs/api-reference/common/Sqlite/type-aliases/SqliteRow) | [`SqliteRow`](https://evolu.dev/docs/api-reference/common/Sqlite/type-aliases/SqliteRow) |
## Properties
| Property | Modifier | Type | Defined in |
| ------------------------------ | ---------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| <a id="changes"></a> `changes` | `readonly` | `number` | [packages/common/src/Sqlite.ts:129](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Sqlite.ts#L129) |
| <a id="rows"></a> `rows` | `readonly` | readonly `R`[] | [packages/common/src/Sqlite.ts:128](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Sqlite.ts#L128) |
SqliteQuery - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Sqlite](https://evolu.dev/docs/api-reference/common/Sqlite) / SqliteQuery
# Interface: SqliteQuery
Defined in: [packages/common/src/Sqlite.ts:72](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Sqlite.ts#L72)
## Properties
| Property | Modifier | Type | Defined in |
| ------------------------------------ | ---------- | ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="options"></a> `options?` | `readonly` | [`SqliteQueryOptions`](https://evolu.dev/docs/api-reference/common/Sqlite/interfaces/SqliteQueryOptions) | [packages/common/src/Sqlite.ts:75](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Sqlite.ts#L75) |
| <a id="parameters"></a> `parameters` | `readonly` | (`string` \| `number` \| `Uint8Array`\<`ArrayBufferLike`\> \| `null`)[] | [packages/common/src/Sqlite.ts:74](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Sqlite.ts#L74) |
| <a id="sql"></a> `sql` | `readonly` | [`SafeSql`](https://evolu.dev/docs/api-reference/common/Sqlite/type-aliases/SafeSql) | [packages/common/src/Sqlite.ts:73](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Sqlite.ts#L73) |
SqliteQueryOptions - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Sqlite](https://evolu.dev/docs/api-reference/common/Sqlite) / SqliteQueryOptions
# Interface: SqliteQueryOptions
Defined in: [packages/common/src/Sqlite.ts:100](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Sqlite.ts#L100)
## Properties
| Property | Modifier | Type | Description | Defined in |
| ----------------------------------------------------------- | ---------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| <a id="logexplainqueryplan"></a> `logExplainQueryPlan?` | `readonly` | `boolean` | If set to `true`, logs the SQLite Explain Query Plan (EQP) for the query. This can help analyze how SQLite plans to execute the query and identify potential optimizations. See: [https://www.sqlite.org/eqp.html](https://www.sqlite.org/eqp.html). | [packages/common/src/Sqlite.ts:114](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Sqlite.ts#L114) |
| <a id="logqueryexecutiontime"></a> `logQueryExecutionTime?` | `readonly` | `boolean` | If set to `true`, logs the time taken to execute the SQL query. Useful for performance monitoring and identifying slow queries. | [packages/common/src/Sqlite.ts:105](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Sqlite.ts#L105) |
| <a id="prepare"></a> `prepare?` | `readonly` | `boolean` | If set to `true`, explicitly prepares the query before execution. Prepared statements can improve performance for repeated queries by reusing the compiled query. See: [https://sqlite.org/wasm/doc/trunk/api-oo1.md#db-prepare](https://sqlite.org/wasm/doc/trunk/api-oo1.md#db-prepare). | [packages/common/src/Sqlite.ts:123](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Sqlite.ts#L123) |
SqliteQueryPlanRow - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Sqlite](https://evolu.dev/docs/api-reference/common/Sqlite) / SqliteQueryPlanRow
# Interface: SqliteQueryPlanRow
Defined in: [packages/common/src/Sqlite.ts:476](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Sqlite.ts#L476)
## Properties
| Property | Type | Defined in |
| ---------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| <a id="detail"></a> `detail` | `string` | [packages/common/src/Sqlite.ts:479](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Sqlite.ts#L479) |
| <a id="id"></a> `id` | `number` | [packages/common/src/Sqlite.ts:477](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Sqlite.ts#L477) |
| <a id="parent"></a> `parent` | `number` | [packages/common/src/Sqlite.ts:478](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Sqlite.ts#L478) |
CreateSqliteDriver - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Sqlite](https://evolu.dev/docs/api-reference/common/Sqlite) / CreateSqliteDriver
# Type Alias: CreateSqliteDriver()
```ts
type CreateSqliteDriver = (name, options?) => Promise<SqliteDriver>;
```
Defined in: [packages/common/src/Sqlite.ts:28](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Sqlite.ts#L28)
## Parameters
| Parameter | Type |
| ---------- | --------------------------------------------------------------------------------------------- |
| `name` | [`SimpleName`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/SimpleName) |
| `options?` | [`SqliteDriverOptions`](https://evolu.dev/docs/api-reference/common/Sqlite/interfaces/SqliteDriverOptions) |
## Returns
`Promise`\<[`SqliteDriver`](https://evolu.dev/docs/api-reference/common/Sqlite/interfaces/SqliteDriver)\>
SafeSql - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Sqlite](https://evolu.dev/docs/api-reference/common/Sqlite) / SafeSql
# Type Alias: SafeSql
```ts
type SafeSql = string & Brand<"SafeSql">;
```
Defined in: [packages/common/src/Sqlite.ts:79](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Sqlite.ts#L79)
A type representing a sanitized SQL string.
SqlTemplateParam - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Sqlite](https://evolu.dev/docs/api-reference/common/Sqlite) / SqlTemplateParam
# Type Alias: SqlTemplateParam
```ts
type SqlTemplateParam = SqliteValue | SqlIdentifier | RawSql;
```
Defined in: [packages/common/src/Sqlite.ts:315](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Sqlite.ts#L315)
SqliteBoolean - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Sqlite](https://evolu.dev/docs/api-reference/common/Sqlite) / SqliteBoolean
# Type Alias: SqliteBoolean
```ts
type SqliteBoolean = typeof Type;
```
Defined in: [packages/common/src/Sqlite.ts:534](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Sqlite.ts#L534)
SqliteRow - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Sqlite](https://evolu.dev/docs/api-reference/common/Sqlite) / SqliteRow
# Type Alias: SqliteRow
```ts
type SqliteRow = Record<string, SqliteValue>;
```
Defined in: [packages/common/src/Sqlite.ts:139](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Sqlite.ts#L139)
SqliteValue - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Sqlite](https://evolu.dev/docs/api-reference/common/Sqlite) / SqliteValue
# Type Alias: SqliteValue
```ts
type SqliteValue = typeof Type;
```
Defined in: [packages/common/src/Sqlite.ts:87](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Sqlite.ts#L87)
SqliteBoolean - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Sqlite](https://evolu.dev/docs/api-reference/common/Sqlite) / SqliteBoolean
# Variable: SqliteBoolean
```ts
const SqliteBoolean: UnionType<[LiteralType<0>, LiteralType<1>]>;
```
Defined in: [packages/common/src/Sqlite.ts:534](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Sqlite.ts#L534)
SQLite represents boolean values using `0` (false) and `1` (true) instead of
a dedicated boolean type.
See: https://www.sqlite.org/quirks.html#no_separate_boolean_datatype
### Tips
- Use [sqliteTrue](https://evolu.dev/docs/api-reference/common/Sqlite/variables/sqliteTrue) and [sqliteFalse](https://evolu.dev/docs/api-reference/common/Sqlite/variables/sqliteFalse) constants for better
readability.
- Use [booleanToSqliteBoolean](https://evolu.dev/docs/api-reference/common/Sqlite/functions/booleanToSqliteBoolean) and [sqliteBooleanToBoolean](https://evolu.dev/docs/api-reference/common/Sqlite/functions/sqliteBooleanToBoolean) for
converting between JavaScript booleans and SQLite boolean values.
SqliteValue - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Sqlite](https://evolu.dev/docs/api-reference/common/Sqlite) / SqliteValue
# Variable: SqliteValue
```ts
const SqliteValue: UnionType<
[
Type<"Null", null, null, NullError, null, NullError>,
Type<"String", string, string, StringError, string, StringError>,
Type<"Number", number, number, NumberError, number, NumberError>,
Type<
"Uint8Array",
Uint8Array<ArrayBufferLike>,
Uint8Array<ArrayBufferLike>,
Uint8ArrayError,
Uint8Array<ArrayBufferLike>,
Uint8ArrayError
>,
]
>;
```
Defined in: [packages/common/src/Sqlite.ts:87](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Sqlite.ts#L87)
A value that can be stored in Sqlite.
Note that Evolu can't support Int64 because expo-sqlite (and some others) do
not support it.
eqSqliteValue - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Sqlite](https://evolu.dev/docs/api-reference/common/Sqlite) / eqSqliteValue
# Variable: eqSqliteValue
```ts
const eqSqliteValue: Eq<SqliteValue>;
```
Defined in: [packages/common/src/Sqlite.ts:90](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Sqlite.ts#L90)
isSqlMutation - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Sqlite](https://evolu.dev/docs/api-reference/common/Sqlite) / isSqlMutation
# Variable: isSqlMutation
```ts
const isSqlMutation: Predicate<string>;
```
Defined in: [packages/common/src/Sqlite.ts:406](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Sqlite.ts#L406)
Checks if a SQL string contains mutation keywords (insert, update, delete,
etc.). Results are cached for performance.
sqliteFalse - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Sqlite](https://evolu.dev/docs/api-reference/common/Sqlite) / sqliteFalse
# Variable: sqliteFalse
```ts
const sqliteFalse: 0 = 0;
```
Defined in: [packages/common/src/Sqlite.ts:549](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Sqlite.ts#L549)
Represents the [SqliteBoolean](https://evolu.dev/docs/api-reference/common/Sqlite/variables/SqliteBoolean) value for `false`.
See [SqliteBoolean](https://evolu.dev/docs/api-reference/common/Sqlite/variables/SqliteBoolean).
sqliteTrue - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Sqlite](https://evolu.dev/docs/api-reference/common/Sqlite) / sqliteTrue
# Variable: sqliteTrue
```ts
const sqliteTrue: 1 = 1;
```
Defined in: [packages/common/src/Sqlite.ts:542](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Sqlite.ts#L542)
Represents the [SqliteBoolean](https://evolu.dev/docs/api-reference/common/Sqlite/variables/SqliteBoolean) value for `true`.
See [SqliteBoolean](https://evolu.dev/docs/api-reference/common/Sqlite/variables/SqliteBoolean).
createStore - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Store](https://evolu.dev/docs/api-reference/common/Store) / createStore
# Function: createStore()
```ts
function createStore<T>(initialState, eq): Store<T>;
```
Defined in: [packages/common/src/Store.ts:49](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Store.ts#L49)
Creates a store with the given initial state. The store encapsulates its
state, which can be read with `get` and updated with `set` or `modify`. All
changes are broadcast to subscribers.
By default, state changes are detected using `===` (shallow equality). You
can provide a custom equality function as the second argument.
## Type Parameters
| Type Parameter |
| -------------- |
| `T` |
## Parameters
| Parameter | Type | Default value |
| -------------- | ---------------------------------------------------------------- | ------------- |
| `initialState` | `T` | `undefined` |
| `eq` | [`Eq`](https://evolu.dev/docs/api-reference/common/Eq/type-aliases/Eq)\<`T`\> | `eqStrict` |
## Returns
[`Store`](https://evolu.dev/docs/api-reference/common/Store/interfaces/Store)\<`T`\>
Store - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Store](https://evolu.dev/docs/api-reference/common/Store) / Store
# Interface: Store\<T\>
Defined in: [packages/common/src/Store.ts:9](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Store.ts#L9)
A store for managing state with change notifications. Extends [Ref](https://evolu.dev/docs/api-reference/common/Ref/interfaces/Ref) with
subscriptions. Provides methods to get, set, and modify state, and to notify
listeners when the state changes.
## Extends
- [`Ref`](https://evolu.dev/docs/api-reference/common/Ref/interfaces/Ref)\<`T`\>
## Type Parameters
| Type Parameter |
| -------------- |
| `T` |
## Properties
| Property | Modifier | Type | Description | Overrides | Defined in |
| ---------------------------------- | ---------- | ------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="get"></a> `get` | `readonly` | () => `T` | Returns the current state of the store. | [`Ref`](https://evolu.dev/docs/api-reference/common/Ref/interfaces/Ref).[`get`](https://evolu.dev/docs/api-reference/common/Ref/interfaces/Ref.mdx#get) | [packages/common/src/Store.ts:17](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Store.ts#L17) |
| <a id="modify"></a> `modify` | `readonly` | (`updater`) => `void` | Modifies the store's state by applying a callback function to the current state and notifies listeners if the state changes. | [`Ref`](https://evolu.dev/docs/api-reference/common/Ref/interfaces/Ref).[`modify`](https://evolu.dev/docs/api-reference/common/Ref/interfaces/Ref.mdx#modify) | [packages/common/src/Store.ts:29](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Store.ts#L29) |
| <a id="set"></a> `set` | `readonly` | (`state`) => `void` | Updates the store's state and notifies all subscribed listeners if the new state differs from the current one. | [`Ref`](https://evolu.dev/docs/api-reference/common/Ref/interfaces/Ref).[`set`](https://evolu.dev/docs/api-reference/common/Ref/interfaces/Ref.mdx#set) | [packages/common/src/Store.ts:23](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Store.ts#L23) |
| <a id="subscribe"></a> `subscribe` | `readonly` | [`StoreSubscribe`](https://evolu.dev/docs/api-reference/common/Store/type-aliases/StoreSubscribe) | Registers a listener to be called on state changes and returns a function to unsubscribe. | - | [packages/common/src/Store.ts:14](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Store.ts#L14) |
StoreListener - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Store](https://evolu.dev/docs/api-reference/common/Store) / StoreListener
# Type Alias: StoreListener()
```ts
type StoreListener = () => void;
```
Defined in: [packages/common/src/Store.ts:36](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Store.ts#L36)
A callback invoked whenever the store's state updates.
## Returns
`void`
StoreSubscribe - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Store](https://evolu.dev/docs/api-reference/common/Store) / StoreSubscribe
# Type Alias: StoreSubscribe()
```ts
type StoreSubscribe = (listener) => StoreUnsubscribe;
```
Defined in: [packages/common/src/Store.ts:33](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Store.ts#L33)
Registers a listener for state changes, returning an unsubscribe function.
## Parameters
| Parameter | Type |
| ---------- | ---------------------------------------------------------------------------------- |
| `listener` | [`StoreListener`](https://evolu.dev/docs/api-reference/common/Store/type-aliases/StoreListener) |
## Returns
[`StoreUnsubscribe`](https://evolu.dev/docs/api-reference/common/Store/type-aliases/StoreUnsubscribe)
StoreUnsubscribe - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Store](https://evolu.dev/docs/api-reference/common/Store) / StoreUnsubscribe
# Type Alias: StoreUnsubscribe()
```ts
type StoreUnsubscribe = () => void;
```
Defined in: [packages/common/src/Store.ts:39](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Store.ts#L39)
A function to remove a previously added listener.
## Returns
`void`
safelyStringifyUnknownValue - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [String](https://evolu.dev/docs/api-reference/common/String) / safelyStringifyUnknownValue
# Function: safelyStringifyUnknownValue()
```ts
function safelyStringifyUnknownValue(value): string;
```
Defined in: [packages/common/src/String.ts:1](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/String.ts#L1)
## Parameters
| Parameter | Type |
| --------- | --------- |
| `value` | `unknown` |
## Returns
`string`
createMutex - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Task](https://evolu.dev/docs/api-reference/common/Task) / createMutex
# Function: createMutex()
```ts
function createMutex(): Mutex;
```
Defined in: [packages/common/src/Task.ts:726](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Task.ts#L726)
Creates a new mutex for ensuring mutual exclusion.
A mutex is a [createSemaphore](https://evolu.dev/docs/api-reference/common/Task/functions/createSemaphore) with exactly one permit, ensuring that
only one Task can execute at a time.
### Example
```ts
const mutex = createMutex();
const updateTask = (id: number) =>
toTask((context) =>
tryAsync(
() => updateSharedResource(id, context),
(error): UpdateError => ({ type: "UpdateError", error }),
),
);
// These Tasks will execute one at a time
const results = await Promise.all([
mutex.withLock(updateTask(1))(),
mutex.withLock(updateTask(2))(),
mutex.withLock(updateTask(3))(),
]);
```
## Returns
[`Mutex`](https://evolu.dev/docs/api-reference/common/Task/interfaces/Mutex)
createSemaphore - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Task](https://evolu.dev/docs/api-reference/common/Task) / createSemaphore
# Function: createSemaphore()
```ts
function createSemaphore(maxConcurrent): Semaphore;
```
Defined in: [packages/common/src/Task.ts:620](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Task.ts#L620)
Creates a semaphore that limits concurrent async Tasks to the specified
count.
A semaphore controls access to a resource by maintaining a count of available
permits. Tasks acquire a permit before executing and release it when
complete.
For mutual exclusion (exactly one Task at a time), consider using
[createMutex](https://evolu.dev/docs/api-reference/common/Task/functions/createMutex) instead.
### Example
```ts
// Allow maximum 3 concurrent Tasks
const semaphore = createSemaphore(PositiveInt.orThrow(3));
let currentConcurrent = 0;
const events: Array<string> = [];
const fetchData = (id: number) =>
toTask<number, never>(async (context) => {
currentConcurrent++;
events.push(`start ${id} (concurrent: ${currentConcurrent})`);
await wait("10ms")(context);
currentConcurrent--;
events.push(`end ${id} (concurrent: ${currentConcurrent})`);
return ok(id * 10);
});
// These will execute with at most 3 running concurrently
const results = await Promise.all([
semaphore.withPermit(fetchData(1))(),
semaphore.withPermit(fetchData(2))(),
semaphore.withPermit(fetchData(3))(),
semaphore.withPermit(fetchData(4))(), // waits for one above to complete
semaphore.withPermit(fetchData(5))(), // waits for permit
]);
expect(results.map(getOrThrow)).toEqual([10, 20, 30, 40, 50]);
expect(events).toMatchInlineSnapshot(`
[
"start 1 (concurrent: 1)",
"start 2 (concurrent: 2)",
"start 3 (concurrent: 3)",
"end 1 (concurrent: 2)",
"start 4 (concurrent: 3)",
"end 2 (concurrent: 2)",
"start 5 (concurrent: 3)",
"end 3 (concurrent: 2)",
"end 4 (concurrent: 1)",
"end 5 (concurrent: 0)",
]
`);
```
## Parameters
| Parameter | Type |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `maxConcurrent` | `number` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Int"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"NonNegative"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Positive"`\> |
## Returns
[`Semaphore`](https://evolu.dev/docs/api-reference/common/Task/interfaces/Semaphore)
isAsync - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Task](https://evolu.dev/docs/api-reference/common/Task) / isAsync
# Function: isAsync()
```ts
function isAsync<T>(
value,
): value is T extends PromiseLike<unknown> ? never : PromiseLike<T>;
```
Defined in: [packages/common/src/Task.ts:844](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Task.ts#L844)
Type guard to check if a [MaybeAsync](https://evolu.dev/docs/api-reference/common/Task/type-aliases/MaybeAsync) value is async (a promise).
This function narrows the type of a [MaybeAsync](https://evolu.dev/docs/api-reference/common/Task/type-aliases/MaybeAsync) value, allowing you to
conditionally `await` only when necessary.
### Example
```ts
const getData = (id: string): MaybeAsync<Data> => {
const cached = cache.get(id);
if (cached) return cached; // Sync path
return fetchData(id); // Async path
};
const result = getData(id);
const data = isAsync(result) ? await result : result;
// No microtask overhead when cached!
```
## Type Parameters
| Type Parameter |
| -------------- |
| `T` |
## Parameters
| Parameter | Type |
| --------- | ---------------------------------------------------------------------------------- |
| `value` | [`MaybeAsync`](https://evolu.dev/docs/api-reference/common/Task/type-aliases/MaybeAsync)\<`T`\> |
## Returns
`value is T extends PromiseLike<unknown> ? never : PromiseLike<T>`
requestIdleTask - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Task](https://evolu.dev/docs/api-reference/common/Task) / requestIdleTask
# Function: requestIdleTask()
```ts
function requestIdleTask<T, E>(task): Task<T, E>;
```
Defined in: [packages/common/src/Task.ts:754](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Task.ts#L754)
Schedule a task to run after all interactions (animations, gestures,
navigation) have completed.
This uses `requestIdleCallback` when available, otherwise falls back to
`setTimeout(0)` for cross-platform compatibility.
### Example
```ts
const processDataTask: Task<void, ProcessError> = toTask(async () => {
// Heavy processing work
return ok();
});
// Schedule the task to run when idle
void requestIdleTask(processDataTask)();
```
## Type Parameters
| Type Parameter |
| -------------- |
| `T` |
| `E` |
## Parameters
| Parameter | Type |
| --------- | ------------------------------------------------------------------------- |
| `task` | [`Task`](https://evolu.dev/docs/api-reference/common/Task/interfaces/Task)\<`T`, `E`\> |
## Returns
[`Task`](https://evolu.dev/docs/api-reference/common/Task/interfaces/Task)\<`T`, `E`\>
retry - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Task](https://evolu.dev/docs/api-reference/common/Task) / retry
# Function: retry()
```ts
function retry<T, E>(__namedParameters, task): Task<T, E | RetryError<E>>;
```
Defined in: [packages/common/src/Task.ts:477](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Task.ts#L477)
Adds retry logic with exponential backoff and jitter to a [Task](https://evolu.dev/docs/api-reference/common/Task/interfaces/Task).
### Example
```ts
interface FetchError {
readonly type: "FetchError";
readonly error: unknown;
}
// Task version of fetch with proper error handling and cancellation support.
const fetch = (url: string) =>
toTask((context) =>
tryAsync(
() => globalThis.fetch(url, { signal: context?.signal ?? null }),
(error): FetchError => ({ type: "FetchError", error }),
),
);
// `satisfies` shows the expected type signature.
fetch satisfies (url: string) => Task<Response, FetchError>;
const fetchWithRetry = (url: string) =>
retry({ retries: PositiveInt.orThrow(3) }, fetch(url));
const result1 = await fetchWithRetry("https://api.example.com/data")();
result1 satisfies Result<Response, FetchError | RetryError<FetchError>>;
// With AbortController
const controller = new AbortController();
const result2 = await fetchWithRetry("https://api.example.com/data")(
controller,
);
result2 satisfies Result<
Response,
FetchError | RetryError<FetchError> | AbortError
>;
```
## Type Parameters
| Type Parameter |
| -------------- |
| `T` |
| `E` |
## Parameters
| Parameter | Type |
| ------------------- | ------------------------------------------------------------------------------------ |
| `__namedParameters` | [`RetryOptions`](https://evolu.dev/docs/api-reference/common/Task/interfaces/RetryOptions)\<`E`\> |
| `task` | [`Task`](https://evolu.dev/docs/api-reference/common/Task/interfaces/Task)\<`T`, `E`\> |
## Returns
[`Task`](https://evolu.dev/docs/api-reference/common/Task/interfaces/Task)\<`T`,
\| `E`
\| [`RetryError`](https://evolu.dev/docs/api-reference/common/Task/interfaces/RetryError)\<`E`\>\>
timeout - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Task](https://evolu.dev/docs/api-reference/common/Task) / timeout
# Function: timeout()
```ts
function timeout<T, E>(duration, task): Task<T, TimeoutError | E>;
```
Defined in: [packages/common/src/Task.ts:380](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Task.ts#L380)
Adds timeout behavior to a [Task](https://evolu.dev/docs/api-reference/common/Task/interfaces/Task).
### Example
```ts
interface FetchError {
readonly type: "FetchError";
readonly error: unknown;
}
// Task version of fetch with proper error handling and cancellation support.
const fetch = (url: string) =>
toTask((context) =>
tryAsync(
() => globalThis.fetch(url, { signal: context?.signal ?? null }),
(error): FetchError => ({ type: "FetchError", error }),
),
);
// `satisfies` shows the expected type signature.
fetch satisfies (url: string) => Task<Response, FetchError>;
const fetchWithTimeout = (url: string) => timeout("2m", fetch(url));
const result1 = await fetchWithTimeout("https://api.example.com/data")();
result1 satisfies Result<Response, FetchError | TimeoutError>;
// With AbortController
const controller = new AbortController();
const result2 = await fetchWithTimeout("https://api.example.com/data")(
controller,
);
result2 satisfies Result<Response, FetchError | TimeoutError | AbortError>;
```
## Type Parameters
| Type Parameter |
| -------------- |
| `T` |
| `E` |
## Parameters
| Parameter | Type |
| ---------- | ------------------------------------------------------------------------- |
| `duration` | [`Duration`](https://evolu.dev/docs/api-reference/common/Time/type-aliases/Duration) |
| `task` | [`Task`](https://evolu.dev/docs/api-reference/common/Task/interfaces/Task)\<`T`, `E`\> |
## Returns
[`Task`](https://evolu.dev/docs/api-reference/common/Task/interfaces/Task)\<`T`,
\| [`TimeoutError`](https://evolu.dev/docs/api-reference/common/Task/interfaces/TimeoutError)
\| `E`\>
toTask - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Task](https://evolu.dev/docs/api-reference/common/Task) / toTask
# Function: toTask()
```ts
function toTask<T, E>(fn): Task<T, E>;
```
Defined in: [packages/common/src/Task.ts:258](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Task.ts#L258)
Converts async function returning [Result](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result) to a [Task](https://evolu.dev/docs/api-reference/common/Task/interfaces/Task).
### Example
```ts
interface FetchError {
readonly type: "FetchError";
readonly error: unknown;
}
// Task version of fetch with proper error handling and cancellation support.
const fetch = (url: string) =>
toTask((context) =>
tryAsync(
() => globalThis.fetch(url, { signal: context?.signal ?? null }),
(error): FetchError => ({ type: "FetchError", error }),
),
);
// `satisfies` shows the expected type signature.
fetch satisfies (url: string) => Task<Response, FetchError>;
const result1 = await fetch("https://api.example.com/data")();
result1 satisfies Result<Response, FetchError>;
// With AbortController
const controller = new AbortController();
const result2 = await fetch("https://api.example.com/data")(controller);
result2 satisfies Result<Response, FetchError | AbortError>;
```
## Type Parameters
| Type Parameter |
| -------------- |
| `T` |
| `E` |
## Parameters
| Parameter | Type |
| --------- | -------------------------------------------------------------------------------------------------------------- |
| `fn` | (`context?`) => `Promise`\<[`Result`](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result)\<`T`, `E`\>\> |
## Returns
[`Task`](https://evolu.dev/docs/api-reference/common/Task/interfaces/Task)\<`T`, `E`\>
wait - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Task](https://evolu.dev/docs/api-reference/common/Task) / wait
# Function: wait()
```ts
function wait(duration): Task<void, never>;
```
Defined in: [packages/common/src/Task.ts:315](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Task.ts#L315)
Creates a [Task](https://evolu.dev/docs/api-reference/common/Task/interfaces/Task) that waits for the specified duration.
### Example
```ts
const result1 = await wait("10ms")();
result1 satisfies Result<void, never>;
// With AbortController
const controller = new AbortController();
const result2 = await wait("10ms")(controller);
result2 satisfies Result<void, AbortError>;
```
## Parameters
| Parameter | Type |
| ---------- | ----------------------------------------------------------------------- |
| `duration` | [`Duration`](https://evolu.dev/docs/api-reference/common/Time/type-aliases/Duration) |
## Returns
[`Task`](https://evolu.dev/docs/api-reference/common/Task/interfaces/Task)\<`void`, `never`\>
AbortError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Task](https://evolu.dev/docs/api-reference/common/Task) / AbortError
# Interface: AbortError
Defined in: [packages/common/src/Task.ts:201](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Task.ts#L201)
Error returned when a [Task](https://evolu.dev/docs/api-reference/common/Task/interfaces/Task) is cancelled via AbortSignal.
## Properties
| Property | Modifier | Type | Defined in |
| ----------------------------- | ---------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="reason"></a> `reason?` | `readonly` | `unknown` | [packages/common/src/Task.ts:203](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Task.ts#L203) |
| <a id="type"></a> `type` | `readonly` | `"AbortError"` | [packages/common/src/Task.ts:202](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Task.ts#L202) |
Mutex - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Task](https://evolu.dev/docs/api-reference/common/Task) / Mutex
# Interface: Mutex
Defined in: [packages/common/src/Task.ts:689](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Task.ts#L689)
A mutex (mutual exclusion) that ensures only one Task runs at a time.
This is a specialized version of a [Semaphore](https://evolu.dev/docs/api-reference/common/Task/interfaces/Semaphore) with a permit count of 1.
## See
[createMutex](https://evolu.dev/docs/api-reference/common/Task/functions/createMutex) to create a mutex instance.
## Extends
- `Disposable`
## Properties
| Property | Modifier | Type | Description | Defined in |
| -------------------------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="withlock"></a> `withLock` | `readonly` | \<`T`, `E`\>(`task`) => [`Task`](https://evolu.dev/docs/api-reference/common/Task/interfaces/Task)\<`T`, \| [`AbortError`](https://evolu.dev/docs/api-reference/common/Task/interfaces/AbortError) \| `E`\> | Executes a Task while holding the mutex lock. Only one Task can hold the lock at a time. Other Tasks will wait until the lock is released. Supports cancellation via AbortSignal. | [packages/common/src/Task.ts:696](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Task.ts#L696) |
## Methods
### \[dispose\]()
##
Defined in: node_modules/typescript/lib/lib.esnext.disposable.d.ts:36
##### Returns
`void`
##### Inherited from
```ts
Disposable.[dispose]
```
##
Defined in: node_modules/@types/node/compatibility/disposable.d.ts:9
##### Returns
`void`
##### Inherited from
```ts
Disposable.[dispose]
```
RetryError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Task](https://evolu.dev/docs/api-reference/common/Task) / RetryError
# Interface: RetryError\<E\>
Defined in: [packages/common/src/Task.ts:431](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Task.ts#L431)
Error returned when [retry](https://evolu.dev/docs/api-reference/common/Task/functions/retry) exhausts all retry attempts.
## Type Parameters
| Type Parameter |
| -------------- |
| `E` |
## Properties
| Property | Modifier | Type | Defined in |
| -------------------------------- | ---------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="attempts"></a> `attempts` | `readonly` | `number` | [packages/common/src/Task.ts:434](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Task.ts#L434) |
| <a id="cause"></a> `cause` | `readonly` | `E` | [packages/common/src/Task.ts:433](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Task.ts#L433) |
| <a id="type"></a> `type` | `readonly` | `"RetryError"` | [packages/common/src/Task.ts:432](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Task.ts#L432) |
RetryOptions - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Task](https://evolu.dev/docs/api-reference/common/Task) / RetryOptions
# Interface: RetryOptions\<E\>
Defined in: [packages/common/src/Task.ts:400](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Task.ts#L400)
Options for configuring [retry](https://evolu.dev/docs/api-reference/common/Task/functions/retry) behavior.
## Type Parameters
| Type Parameter |
| -------------- |
| `E` |
## Properties
| Property | Modifier | Type | Description | Defined in |
| ----------------------------------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="factor"></a> `factor?` | `readonly` | `number` | Exponential backoff multiplier. | [packages/common/src/Task.ts:415](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Task.ts#L415) |
| <a id="initialdelay"></a> `initialDelay?` | `readonly` | [`Duration`](https://evolu.dev/docs/api-reference/common/Time/type-aliases/Duration) | Initial delay for exponential backoff (1st retry uses this, 2nd uses this×factor, 3rd uses this×factor², etc.). Actual delays are randomized by [RetryOptions.jitter](https://evolu.dev/docs/api-reference/common/Task/interfaces/RetryOptions.mdx#jitter). | [packages/common/src/Task.ts:409](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Task.ts#L409) |
| <a id="jitter"></a> `jitter?` | `readonly` | `number` | Random jitter factor (0-1) to prevent thundering herd. | [packages/common/src/Task.ts:418](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Task.ts#L418) |
| <a id="maxdelay"></a> `maxDelay?` | `readonly` | [`Duration`](https://evolu.dev/docs/api-reference/common/Time/type-aliases/Duration) | Maximum delay between retries. | [packages/common/src/Task.ts:412](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Task.ts#L412) |
| <a id="onretry"></a> `onRetry?` | `readonly` | (`error`, `attempt`, `delay`) => `void` | Callback invoked before each retry attempt. | [packages/common/src/Task.ts:427](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Task.ts#L427) |
| <a id="retries"></a> `retries` | `readonly` | `number` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Int"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"NonNegative"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Positive"`\> | Number of retry attempts after the initial failure. | [packages/common/src/Task.ts:402](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Task.ts#L402) |
| <a id="retryable"></a> `retryable?` | `readonly` | (`error`) => `boolean` | Predicate to determine if error should trigger retry. Receives AbortError too. | [packages/common/src/Task.ts:424](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Task.ts#L424) |
Semaphore - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Task](https://evolu.dev/docs/api-reference/common/Task) / Semaphore
# Interface: Semaphore
Defined in: [packages/common/src/Task.ts:550](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Task.ts#L550)
A semaphore that limits the number of concurrent async Tasks.
For mutual exclusion (limiting to exactly one Task), consider using
[Mutex](https://evolu.dev/docs/api-reference/common/Task/interfaces/Mutex) instead.
## See
[createSemaphore](https://evolu.dev/docs/api-reference/common/Task/functions/createSemaphore) to create a semaphore instance.
## Extends
- `Disposable`
## Properties
| Property | Modifier | Type | Description | Defined in |
| ------------------------------------ | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="withpermit"></a> `withPermit` | `readonly` | \<`T`, `E`\>(`task`) => [`Task`](https://evolu.dev/docs/api-reference/common/Task/interfaces/Task)\<`T`, \| [`AbortError`](https://evolu.dev/docs/api-reference/common/Task/interfaces/AbortError) \| `E`\> | Executes a Task while holding a semaphore permit. The Task will wait until a permit is available before executing. Supports cancellation via AbortSignal - if the signal is aborted while waiting for a permit or during execution, the Task is cancelled and permits are properly released. | [packages/common/src/Task.ts:559](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Task.ts#L559) |
## Methods
### \[dispose\]()
##
Defined in: node_modules/typescript/lib/lib.esnext.disposable.d.ts:36
##### Returns
`void`
##### Inherited from
```ts
Disposable.[dispose]
```
##
Defined in: node_modules/@types/node/compatibility/disposable.d.ts:9
##### Returns
`void`
##### Inherited from
```ts
Disposable.[dispose]
```
Task - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Task](https://evolu.dev/docs/api-reference/common/Task) / Task
# Interface: Task()\<T, E\>
Defined in: [packages/common/src/Task.ts:145](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Task.ts#L145)
`Task` is a function that creates and returns an optionally cancellable
Promise using [Result](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result).
The laziness allows safe composition, e.g. retry logic, because it prevents
eager execution until the Task is actually invoked.
### Cancellation
Tasks support optional cancellation via signal in [TaskContext](https://evolu.dev/docs/api-reference/common/Task/interfaces/TaskContext). When a
Task is called without a signal, it cannot be cancelled and [AbortError](https://evolu.dev/docs/api-reference/common/Task/interfaces/AbortError)
will never be returned. When called with a signal, the Task can be cancelled
and AbortError is added to the error union with precise type safety.
When composing Tasks, we typically have context and want to abort ASAP by
passing it through. However, there are valid cases where we don't want to
abort because we need some atomic unit to complete. For simple scripts and
tests, omitting context is fine.
### Task Helpers
- [toTask](https://evolu.dev/docs/api-reference/common/Task/functions/toTask) - Convert async function to Task
- [wait](https://evolu.dev/docs/api-reference/common/Task/functions/wait) - Delay execution for a specified [Duration](https://evolu.dev/docs/api-reference/common/Time/type-aliases/Duration)
- [timeout](https://evolu.dev/docs/api-reference/common/Task/functions/timeout) - Add timeout to any Task
- [retry](https://evolu.dev/docs/api-reference/common/Task/functions/retry) - Retry failed Tasks with configurable backoff
### Example
```ts
interface FetchError {
readonly type: "FetchError";
readonly error: unknown;
}
// Task version of fetch with proper error handling and cancellation support.
const fetch = (url: string) =>
toTask((context) =>
tryAsync(
() => globalThis.fetch(url, { signal: context?.signal ?? null }),
(error): FetchError => ({ type: "FetchError", error }),
),
);
// `satisfies` shows the expected type signature.
fetch satisfies (url: string) => Task<Response, FetchError>;
// Add timeout to prevent hanging
const fetchWithTimeout = (url: string) => timeout("30s", fetch(url));
fetchWithTimeout satisfies (
url: string,
) => Task<Response, TimeoutError | FetchError>;
// Add retry for resilience
const fetchWithRetry = (url: string) =>
retry(
{
retries: PositiveInt.orThrow(3),
initialDelay: "100ms",
},
fetchWithTimeout(url),
);
fetchWithRetry satisfies (
url: string,
) => Task<
Response,
TimeoutError | FetchError | RetryError<TimeoutError | FetchError>
>;
const semaphore = createSemaphore(PositiveInt.orThrow(2));
// Control concurrency with semaphore
const fetchWithPermit = (url: string) =>
semaphore.withPermit(fetchWithRetry(url));
fetchWithPermit satisfies (url: string) => Task<
Response,
| TimeoutError
| FetchError
| AbortError // Semaphore dispose aborts Tasks
| RetryError<TimeoutError | FetchError>
>;
// Usage
const results = await Promise.all(
[
"https://api.example.com/users",
"https://api.example.com/posts",
"https://api.example.com/comments",
]
.map(fetchWithPermit)
.map((task) => task()),
);
results satisfies Array<
Result<
Response,
| AbortError
| TimeoutError
| FetchError
| RetryError<TimeoutError | FetchError>
>
>;
// Handle results
for (const result of results) {
if (result.ok) {
// Process successful response
const response = result.value;
expect(response).toBeInstanceOf(Response);
} else {
// Handle error (TimeoutError, FetchError, RetryError, or AbortError)
expect(result.error).toBeDefined();
}
}
// Cancellation support
const controller = new AbortController();
const cancelableTask = fetchWithPermit("https://api.example.com/data");
// Start task
const promise = cancelableTask(controller);
// Cancel after some time
setTimeout(() => {
controller.abort("User cancelled");
}, 1000);
const _result = await promise;
// Result will be AbortError if cancelled
```
### Dependency Injection Integration
Tasks integrate naturally with Evolu's DI pattern. Use `deps` for static
dependencies and `TaskContext` for execution context like cancellation. Usage
follows the pattern: deps → arguments → execution context.
## Type Parameters
| Type Parameter |
| -------------- |
| `T` |
| `E` |
```ts
Task<TContext>(context?): Promise<Result<T, TContext extends object ?
| E
| AbortError : E>>;
```
Defined in: [packages/common/src/Task.ts:187](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Task.ts#L187)
Invoke the Task.
Provide a context with an AbortSignal to enable cancellation. When called
without a signal, [AbortError](https://evolu.dev/docs/api-reference/common/Task/interfaces/AbortError) cannot occur and the error type narrows
accordingly.
### Example
```ts
interface FetchError {
readonly type: "FetchError";
readonly error: unknown;
}
// Task version of fetch with proper error handling and cancellation support.
const fetch = (url: string) =>
toTask((context) =>
tryAsync(
() => globalThis.fetch(url, { signal: context?.signal ?? null }),
(error): FetchError => ({ type: "FetchError", error }),
),
);
// `satisfies` shows the expected type signature.
fetch satisfies (url: string) => Task<Response, FetchError>;
const result1 = await fetch("https://api.example.com/data")();
expectTypeOf(result1).toEqualTypeOf<Result<Response, FetchError>>();
// With AbortController
const controller = new AbortController();
const result2 = await fetch("https://api.example.com/data")(controller);
expectTypeOf(result2).toEqualTypeOf<
Result<Response, FetchError | AbortError>
>();
```
## Type Parameters
| Type Parameter | Default type |
| ------------------------------------------------------------------------------------------------------------------ | ------------ |
| `TContext` _extends_ \| [`TaskContext`](https://evolu.dev/docs/api-reference/common/Task/interfaces/TaskContext) \| `undefined` | `undefined` |
## Parameters
| Parameter | Type |
| ---------- | ---------- |
| `context?` | `TContext` |
## Returns
`Promise`\<[`Result`](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result)\<`T`, `TContext` _extends_ `object` ?
\| `E`
\| [`AbortError`](https://evolu.dev/docs/api-reference/common/Task/interfaces/AbortError) : `E`\>\>
TaskContext - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Task](https://evolu.dev/docs/api-reference/common/Task) / TaskContext
# Interface: TaskContext
Defined in: [packages/common/src/Task.ts:195](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Task.ts#L195)
Context passed to [Task](https://evolu.dev/docs/api-reference/common/Task/interfaces/Task)s for cancellation.
## Properties
| Property | Modifier | Type | Description | Defined in |
| ----------------------------- | ---------- | ------------- | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="signal"></a> `signal?` | `readonly` | `AbortSignal` | Signal for cancellation | [packages/common/src/Task.ts:197](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Task.ts#L197) |
TimeoutError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Task](https://evolu.dev/docs/api-reference/common/Task) / TimeoutError
# Interface: TimeoutError
Defined in: [packages/common/src/Task.ts:336](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Task.ts#L336)
Error returned when [timeout](https://evolu.dev/docs/api-reference/common/Task/functions/timeout) exceeds the specified duration.
## Properties
| Property | Modifier | Type | Defined in |
| ---------------------------------- | ---------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="timeoutms"></a> `timeoutMs` | `readonly` | `number` | [packages/common/src/Task.ts:338](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Task.ts#L338) |
| <a id="type"></a> `type` | `readonly` | `"TimeoutError"` | [packages/common/src/Task.ts:337](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Task.ts#L337) |
MaybeAsync - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Task](https://evolu.dev/docs/api-reference/common/Task) / MaybeAsync
# Type Alias: MaybeAsync\<T\>
```ts
type MaybeAsync<T> = T | PromiseLike<T>;
```
Defined in: [packages/common/src/Task.ts:822](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Task.ts#L822)
Represents a value that can be either synchronous or asynchronous.
This type is useful for functions that may complete synchronously or
asynchronously depending on runtime conditions (e.g., cache hit vs network
fetch).
### Why MaybeAsync?
When a function can be sync or async, the typical approaches are:
1. **Always return Promise** - Simple but forces microtask overhead even for
sync values (see "await always adds microtask" test in Task.test.ts)
2. **Use callbacks** - Can avoid microtask, but calling code must still `await`
for sane composition, which adds microtask anyway
3. **Return `T | PromiseLike<T>`** - Calling code can check the value and only
`await` when needed, avoiding microtask overhead for sync cases
The third approach (MaybeAsync) provides:
- **Performance**: No microtask overhead for synchronous operations
- **Reliability**: No interleaving via microtask queue when operations are
_synchronous_, reducing need for mutexes to protect shared state
### Example
```ts
// Function that may be sync or async
const getData = (id: string): MaybeAsync<Data> => {
const cached = cache.get(id);
if (cached) return cached; // Sync path
return fetchData(id); // Async path
};
// Caller can optimize based on actual behavior
const result = getData(id);
const data = isAsync(result) ? await result : result;
```
### Alternative Approaches
It's possible to eliminate the sync/async distinction using complex
frameworks with custom schedulers. However, such frameworks require depending
on other people's code that controls how your code executes, resulting in
more complex stack traces and debugging experiences. With MaybeAsync, we
don't need that machinery - it works directly with JavaScript's native
primitives and TypeScript's type system.
### TODO: Consider
Use MaybeAsync in Task and Task helpers to preserve synchronous execution
when possible (e.g., mutex with available permit, retry on first success).
## Type Parameters
| Type Parameter |
| -------------- |
| `T` |
createTestTime - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Time](https://evolu.dev/docs/api-reference/common/Time) / createTestTime
# Function: createTestTime()
```ts
function createTestTime(): Time;
```
Defined in: [packages/common/src/Time.ts:40](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Time.ts#L40)
Creates a [Time](https://evolu.dev/docs/api-reference/common/Time/interfaces/Time) that returns a monotonically increasing number based on
a queueMicrotask.
## Returns
[`Time`](https://evolu.dev/docs/api-reference/common/Time/interfaces/Time)
createTime - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Time](https://evolu.dev/docs/api-reference/common/Time) / createTime
# Function: createTime()
```ts
function createTime(): Time;
```
Defined in: [packages/common/src/Time.ts:21](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Time.ts#L21)
Creates a [Time](https://evolu.dev/docs/api-reference/common/Time/interfaces/Time) using Date.now().
If the system clock is misconfigured (out of allowed range), the application
will fail with an assertion error. This is intentional - there's no
reasonable fallback when the system clock is fundamentally wrong.
## Returns
[`Time`](https://evolu.dev/docs/api-reference/common/Time/interfaces/Time)
durationToNonNegativeInt - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Time](https://evolu.dev/docs/api-reference/common/Time) / durationToNonNegativeInt
# Function: durationToNonNegativeInt()
```ts
function durationToNonNegativeInt(
duration,
): number & Brand<"Int"> & Brand<"NonNegative">;
```
Defined in: [packages/common/src/Time.ts:140](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Time.ts#L140)
Converts a duration to milliseconds.
Accepts either a [DurationString](https://evolu.dev/docs/api-reference/common/Time/type-aliases/DurationString) (e.g., "5m", "1h 30m") or milliseconds
as [NonNegativeInt](https://evolu.dev/docs/api-reference/common/Type/variables/NonNegativeInt).
### Example
```ts
durationToNonNegativeInt("0ms"); // 0 ✅
durationToNonNegativeInt("500ms"); // 500 ✅
durationToNonNegativeInt("30s"); // 30000 ✅
durationToNonNegativeInt("5m"); // 300000 ✅
durationToNonNegativeInt("12h"); // 43200000 ✅
durationToNonNegativeInt("7d"); // 604800000 ✅
durationToNonNegativeInt("2h 45m"); // 9900000 ✅
durationToNonNegativeInt(5000); // 5000 ✅ (already milliseconds)
```
## Parameters
| Parameter | Type |
| ---------- | ----------------------------------------------------------------------- |
| `duration` | [`Duration`](https://evolu.dev/docs/api-reference/common/Time/type-aliases/Duration) |
## Returns
`number` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Int"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"NonNegative"`\>
Time - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Time](https://evolu.dev/docs/api-reference/common/Time) / Time
# Interface: Time
Defined in: [packages/common/src/Time.ts:5](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Time.ts#L5)
Retrieves the current time in milliseconds, similar to `Date.now()`.
## Properties
| Property | Modifier | Type | Defined in |
| ---------------------------- | ---------- | ------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="now"></a> `now` | `readonly` | () => `number` | [packages/common/src/Time.ts:6](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Time.ts#L6) |
| <a id="nowiso"></a> `nowIso` | `readonly` | () => `string` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"DateIso"`\> | [packages/common/src/Time.ts:7](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Time.ts#L7) |
TimeDep - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Time](https://evolu.dev/docs/api-reference/common/Time) / TimeDep
# Interface: TimeDep
Defined in: [packages/common/src/Time.ts:10](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Time.ts#L10)
## Properties
| Property | Modifier | Type | Defined in |
| ------------------------ | ---------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| <a id="time"></a> `time` | `readonly` | [`Time`](https://evolu.dev/docs/api-reference/common/Time/interfaces/Time) | [packages/common/src/Time.ts:11](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Time.ts#L11) |
D - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Time](https://evolu.dev/docs/api-reference/common/Time) / D
# Type Alias: D
```ts
type D = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9";
```
Defined in: [packages/common/src/Time.ts:57](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Time.ts#L57)
Single digit 0-9. Used internally for [DurationString](https://evolu.dev/docs/api-reference/common/Time/type-aliases/DurationString) validation.
Days - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Time](https://evolu.dev/docs/api-reference/common/Time) / Days
# Type Alias: Days
```ts
type Days = Exclude<D, "0"> | `${Exclude<D, "0">}${D}`;
```
Defined in: [packages/common/src/Time.ts:78](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Time.ts#L78)
Days 1-99. Used internally for [DurationString](https://evolu.dev/docs/api-reference/common/Time/type-aliases/DurationString) validation.
Duration - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Time](https://evolu.dev/docs/api-reference/common/Time) / Duration
# Type Alias: Duration
```ts
type Duration = DurationString | NonNegativeInt;
```
Defined in: [packages/common/src/Time.ts:119](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Time.ts#L119)
Duration can be either a [DurationString](https://evolu.dev/docs/api-reference/common/Time/type-aliases/DurationString) or milliseconds as
[NonNegativeInt](https://evolu.dev/docs/api-reference/common/Type/variables/NonNegativeInt).
DurationString - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Time](https://evolu.dev/docs/api-reference/common/Time) / DurationString
# Type Alias: DurationString
```ts
type DurationString =
| `${D}ms`
| `${D}${D}ms`
| `${D}${D}${D}ms`
| `${MmSs}s`
| `${MmSs}m`
| `${Hours}h`
| `${Days}d`
| `${MmSs}s ${D}ms`
| `${MmSs}s ${D}${D}ms`
| `${MmSs}s ${D}${D}${D}ms`
| `${MmSs}m ${MmSs}s`
| `${Hours}h ${MmSs}m`
| `${Days}d ${Hours}h`;
```
Defined in: [packages/common/src/Time.ts:100](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Time.ts#L100)
Template literal type for compile-time validated duration strings.
Allowed patterns: basic units (ms, s, m, h, d) and logical combinations
(s+ms, m+s, h+m, d+h).
Supported formats:
- Milliseconds: `0ms`, `1ms`, `500ms`, `999ms`
- Seconds: `5s`, `30s` (1-59, single digit for 1-9)
- Minutes: `5m`, `30m` (1-59, single digit for 1-9)
- Hours: `1h`, `12h`, `23h` (1-23)
- Days: `1d`, `30d`, `99d` (1-99)
- Combinations: `1s 250ms`, `30m 15s`, `2h 45m`, `7d 12h`
Note: Duration strings are for developer experience only - they provide
readable, compile-time validated expressions but should never be persisted or
parsed from users as they are not localized. Always convert to NonNegativeInt
(milliseconds) for storage and APIs.
Hours - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Time](https://evolu.dev/docs/api-reference/common/Time) / Hours
# Type Alias: Hours
```ts
type Hours = Exclude<D, "0"> | `1${D}` | `2${"0" | "1" | "2" | "3"}`;
```
Defined in: [packages/common/src/Time.ts:72](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Time.ts#L72)
Hours 1-23. Used internally for [DurationString](https://evolu.dev/docs/api-reference/common/Time/type-aliases/DurationString) validation.
MmSs - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Time](https://evolu.dev/docs/api-reference/common/Time) / MmSs
# Type Alias: MmSs
```ts
type MmSs = Exclude<D, "0"> | `1${D}` | `2${D}` | `3${D}` | `4${D}` | `5${D}`;
```
Defined in: [packages/common/src/Time.ts:63](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Time.ts#L63)
Minutes and seconds 1-59. Used internally for [DurationString](https://evolu.dev/docs/api-reference/common/Time/type-aliases/DurationString)
validation. Uses single digits for 1-9, full numbers for 10-59.
array - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / array
# Function: array()
```ts
function array<ElementType>(element): ArrayType<ElementType>;
```
Defined in: [packages/common/src/Type.ts:2300](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L2300)
Array of a specific [Type](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).
Usage:
```ts
const NumberArray = array(Number);
const result1 = NumberArray.from([1, 2, 3]); // ok([1, 2, 3])
const result2 = NumberArray.from(["a", "b"]); // err(...)
```
## Type Parameters
| Type Parameter |
| --------------------------------------------------------------------------------------------- |
| `ElementType` _extends_ [`AnyType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/AnyType) |
## Parameters
| Parameter | Type |
| --------- | ------------- |
| `element` | `ElementType` |
## Returns
[`ArrayType`](https://evolu.dev/docs/api-reference/common/Type/interfaces/ArrayType)\<`ElementType`\>
base - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / base
# Function: base()
```ts
function base<Name, T, Error>(name, fromUnknown): Type<Name, T, T, Error>;
```
Defined in: [packages/common/src/Type.ts:633](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L633)
Base [Type](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).
A Base Type validates that a value conforms to a specific TypeScript type.
### Example
```ts
const String = base("String", (value) =>
typeof value === "string"
? ok(value)
: err<StringError>({ type: "String", value }),
);
interface StringError extends TypeError<"String"> {}
const formatStringError = createTypeErrorFormatter<StringError>(
(error) => `A value ${error.value} is not a string`,
);
```
## Type Parameters
| Type Parameter |
| --------------------------------------------------------------------------------------------------------------------- |
| `Name` _extends_ `string` |
| `T` |
| `Error` _extends_ [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError)\<`Capitalize`\<`string`\>\> |
## Parameters
| Parameter | Type |
| ------------- | -------------------------------------------------------------------------------------------------- |
| `name` | `Name` |
| `fromUnknown` | (`value`) => [`Result`](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result)\<`T`, `Error`\> |
## Returns
[`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type)\<`Name`, `T`, `T`, `Error`\>
brand - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / brand
# Function: brand()
Defined in: [packages/common/src/Type.ts:972](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L972)
Branded [Type](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).
The `brand` Type Factory takes the name of a new [Brand](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand), a parent Type
to be branded, and the optional `refine` function for additional constraint.
The `refine` function can be omitted if we only want to add a brand.
### Examples
A simple `CurrencyCode` Type:
```ts
const CurrencyCode = brand("CurrencyCode", String, (value) =>
/^[A-Z]{3}$/.test(value)
? ok(value)
: err<CurrencyCodeError>({ type: "CurrencyCode", value }),
);
// string & Brand<"CurrencyCode">
type CurrencyCode = typeof CurrencyCode.Type;
interface CurrencyCodeError extends TypeError<"CurrencyCode"> {}
const formatCurrencyCodeError = createTypeErrorFormatter<CurrencyCodeError>(
(error) => `Invalid currency code: ${error.value}`,
);
// Usage
const result = CurrencyCode.from("USD");
if (result.ok) {
console.log("Valid currency code:", result.value);
} else {
console.error(formatCurrencyCodeError(result.error));
}
```
Often, we want to make a branded Type reusable. For example, instead of
`TrimmedString`, we want the `trimmed` Type Factory:
```ts
const trimmed: BrandFactory<"Trimmed", string, TrimmedError> = (parent) =>
brand("Trimmed", parent, (value) =>
value.trim().length === value.length
? ok(value)
: err<TrimmedError>({ type: "Trimmed", value }),
);
interface TrimmedError extends TypeError<"Trimmed"> {}
const formatTrimmedError = createTypeErrorFormatter<TrimmedError>(
(error) => `A value ${error.value} is not trimmed`,
);
const TrimmedString = trimmed(String);
// string & Brand<"Trimmed">
type TrimmedString = typeof TrimmedString.Type;
const TrimmedNote = trimmed(Note);
```
As noted earlier, the `refine` function is optional. That's useful to add
semantic meaning to the existing Type without altering its functionality:
```ts
const SimplePassword = brand(
"SimplePassword",
minLength(8)(maxLength(64)(TrimmedString)),
);
// string & Brand<"Trimmed"> & Brand<"MinLength8"> & Brand<"MaxLength64"> & Brand<"SimplePassword">
type SimplePassword = typeof SimplePassword.Type;
```
We can use `brand` to enforce valid object as well:
```ts
const Form = object({
password: SimplePassword,
confirmPassword: SimplePassword,
});
const ValidForm = brand("ValidForm", Form, (value) => {
if (value.password !== value.confirmPassword)
return err<ValidFormError>({
type: "ValidForm",
value,
reason: { kind: "PasswordMismatch" },
});
return ok(value);
});
type ValidForm = typeof ValidForm.Type;
interface ValidFormError extends TypeError<"ValidForm"> {
readonly reason: { kind: "PasswordMismatch" };
}
const result = ValidForm.from({
password: "abcde123",
confirmPassword: "bbcde123",
});
const safeForm = (_form: ValidForm) => {
//
};
if (result.ok) {
safeForm(result.value);
}
expect(result).toEqual(
err({
type: "ValidForm",
value: {
confirmPassword: "bbcde123",
password: "abcde123",
},
reason: {
kind: "PasswordMismatch",
},
}),
);
```
### Type Parameters
| Type Parameter | Default type |
| --------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| `Name` _extends_ `string` | - |
| `ParentType` _extends_ [`AnyType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/AnyType) | - |
| `Parent` | [`InferType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferType)\<`ParentType`\> |
| `RefineError` _extends_ [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError)\<`Capitalize`\<`string`\>\> | `never` |
### Parameters
| Parameter | Type |
| --------- | ------------------------------------------------------------------------------------------------------------- |
| `name` | `Name` |
| `parent` | `ParentType` |
| `refine` | (`value`) => [`Result`](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result)\<`Parent`, `RefineError`\> |
### Returns
[`BrandType`](https://evolu.dev/docs/api-reference/common/Type/interfaces/BrandType)\<`ParentType`, `Name`, `RefineError`, [`InferErrors`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferErrors)\<`ParentType`\>\>
Defined in: [packages/common/src/Type.ts:983](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L983)
Branded [Type](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).
The `brand` Type Factory takes the name of a new [Brand](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand), a parent Type
to be branded, and the optional `refine` function for additional constraint.
The `refine` function can be omitted if we only want to add a brand.
### Examples
A simple `CurrencyCode` Type:
```ts
const CurrencyCode = brand("CurrencyCode", String, (value) =>
/^[A-Z]{3}$/.test(value)
? ok(value)
: err<CurrencyCodeError>({ type: "CurrencyCode", value }),
);
// string & Brand<"CurrencyCode">
type CurrencyCode = typeof CurrencyCode.Type;
interface CurrencyCodeError extends TypeError<"CurrencyCode"> {}
const formatCurrencyCodeError = createTypeErrorFormatter<CurrencyCodeError>(
(error) => `Invalid currency code: ${error.value}`,
);
// Usage
const result = CurrencyCode.from("USD");
if (result.ok) {
console.log("Valid currency code:", result.value);
} else {
console.error(formatCurrencyCodeError(result.error));
}
```
Often, we want to make a branded Type reusable. For example, instead of
`TrimmedString`, we want the `trimmed` Type Factory:
```ts
const trimmed: BrandFactory<"Trimmed", string, TrimmedError> = (parent) =>
brand("Trimmed", parent, (value) =>
value.trim().length === value.length
? ok(value)
: err<TrimmedError>({ type: "Trimmed", value }),
);
interface TrimmedError extends TypeError<"Trimmed"> {}
const formatTrimmedError = createTypeErrorFormatter<TrimmedError>(
(error) => `A value ${error.value} is not trimmed`,
);
const TrimmedString = trimmed(String);
// string & Brand<"Trimmed">
type TrimmedString = typeof TrimmedString.Type;
const TrimmedNote = trimmed(Note);
```
As noted earlier, the `refine` function is optional. That's useful to add
semantic meaning to the existing Type without altering its functionality:
```ts
const SimplePassword = brand(
"SimplePassword",
minLength(8)(maxLength(64)(TrimmedString)),
);
// string & Brand<"Trimmed"> & Brand<"MinLength8"> & Brand<"MaxLength64"> & Brand<"SimplePassword">
type SimplePassword = typeof SimplePassword.Type;
```
We can use `brand` to enforce valid object as well:
```ts
const Form = object({
password: SimplePassword,
confirmPassword: SimplePassword,
});
const ValidForm = brand("ValidForm", Form, (value) => {
if (value.password !== value.confirmPassword)
return err<ValidFormError>({
type: "ValidForm",
value,
reason: { kind: "PasswordMismatch" },
});
return ok(value);
});
type ValidForm = typeof ValidForm.Type;
interface ValidFormError extends TypeError<"ValidForm"> {
readonly reason: { kind: "PasswordMismatch" };
}
const result = ValidForm.from({
password: "abcde123",
confirmPassword: "bbcde123",
});
const safeForm = (_form: ValidForm) => {
//
};
if (result.ok) {
safeForm(result.value);
}
expect(result).toEqual(
err({
type: "ValidForm",
value: {
confirmPassword: "bbcde123",
password: "abcde123",
},
reason: {
kind: "PasswordMismatch",
},
}),
);
```
### Type Parameters
| Type Parameter |
| -------------------------------------------------------------------------------------------- |
| `Name` _extends_ `string` |
| `ParentType` _extends_ [`AnyType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/AnyType) |
### Parameters
| Parameter | Type |
| --------- | ------------ |
| `name` | `Name` |
| `parent` | `ParentType` |
### Returns
[`BrandType`](https://evolu.dev/docs/api-reference/common/Type/interfaces/BrandType)\<`ParentType`, `Name`, [`BrandWithoutRefineError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/BrandWithoutRefineError)\<`Name`, [`InferErrors`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferErrors)\<`ParentType`\>\>\>
createBaseTypeErrorFormatter - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / createBaseTypeErrorFormatter
# Function: createBaseTypeErrorFormatter()
```ts
function createBaseTypeErrorFormatter<Error>(): TypeErrorFormatter<Error>;
```
Defined in: [packages/common/src/Type.ts:657](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L657)
Creates a formatter function for a base [TypeError](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError).
This formatter is specifically for Base Types that only need a simple error
message indicating that the value is not of the expected type.
### Example
```ts
export const formatStringError = createBaseTypeErrorFormatter<StringError>();
```
## Type Parameters
| Type Parameter |
| --------------------------------------------------------------------------------------------------------------------- |
| `Error` _extends_ [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError)\<`Capitalize`\<`string`\>\> |
## Returns
[`TypeErrorFormatter`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/TypeErrorFormatter)\<`Error`\>
createFormatTypeError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / createFormatTypeError
# Function: createFormatTypeError()
```ts
function createFormatTypeError<ExtraErrors>(
extraFormatter?,
): TypeErrorFormatter<TypeErrors<ExtraErrors>>;
```
Defined in: [packages/common/src/Type.ts:4190](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L4190)
Formats Evolu Type errors into user-friendly messages.
Evolu Type typed errors ensure every error type must have a formatter.
TypeScript enforces this at compile-time, preventing unhandled validation
errors from reaching users.
The `createFormatTypeError` function handles both built-in [TypeErrors](https://evolu.dev/docs/api-reference/common/Type/type-aliases/TypeErrors)
and custom errors, and lets us override default formatting for specific
errors.
### Example
```ts
const formatTypeError = createFormatTypeError<MinLengthError | MaxLengthError>(
(error): string => {
switch (error.type) {
case "MinLength":
return `Text must be at least ${error.min} character${error.min === 1 ? "" : "s"} long`;
case "MaxLength":
return `Text is too long (maximum ${error.max} characters)`;
}
},
);
```
Alternatively, write a custom formatter from scratch without using
`createFormatTypeError`. This gives us full control over error formatting:
```ts
const Person = object({
name: NonEmptyTrimmedString100,
age: optional(PositiveInt),
});
// Define only the errors actually used by Person Type
type PersonErrors =
| StringError
| MaxLengthError
| MinLengthError
| TrimmedError
| PositiveError
| NonNegativeError
| IntError
| NumberError
| ObjectError<Record<string, PersonErrors>>;
const formatTypeError: TypeErrorFormatter<PersonErrors> = (error) => {
switch (error.type) {
case "String":
return formatStringError(error);
case "Number":
return "Must be a number";
case "MinLength":
return `Must be at least ${error.min} characters`;
case "MaxLength":
return `Cannot exceed ${error.max} characters`;
case "Trimmed":
return "Cannot have leading or trailing spaces";
case "Positive":
return "Must be a positive number";
case "NonNegative":
return "Must be zero or positive";
case "Int":
return "Must be an integer";
case "Object": {
if (error.reason.kind === "NotObject") return "Must be an object";
if (error.reason.kind === "ExtraKeys")
return "Contains unexpected fields";
const firstError = Object.values(error.reason.errors).find(
(e) => e !== undefined,
)!;
return formatTypeError(firstError);
}
}
};
```
## Type Parameters
| Type Parameter | Default type |
| --------------------------------------------------------------------------------------------------------------------------- | ------------ |
| `ExtraErrors` _extends_ [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError)\<`Capitalize`\<`string`\>\> | `never` |
## Parameters
| Parameter | Type |
| ----------------- | ------------------------------------------------------------------------------------------------------------ |
| `extraFormatter?` | [`TypeErrorFormatter`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/TypeErrorFormatter)\<`ExtraErrors`\> |
## Returns
[`TypeErrorFormatter`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/TypeErrorFormatter)\<[`TypeErrors`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/TypeErrors)\<`ExtraErrors`\>\>
createId - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / createId
# Function: createId()
```ts
function createId<B>(
deps,
): [B] extends [never] ? string & Brand<"Id"> : string & Brand<"Id"> & Brand<B>;
```
Defined in: [packages/common/src/Type.ts:1644](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1644)
Creates a random [Id](https://evolu.dev/docs/api-reference/common/Type/variables/Id). This is the recommended default.
Use [createIdFromString](https://evolu.dev/docs/api-reference/common/Type/functions/createIdFromString) for deterministic mapping of external IDs or
[createIdAsUuidv7](https://evolu.dev/docs/api-reference/common/Type/functions/createIdAsUuidv7) when you accept timestamp leakage for index
locality.
### Example
```ts
const id = createId(deps);
const todoId = createId<"Todo">(deps);
```
## Type Parameters
| Type Parameter | Default type |
| ---------------------- | ------------ |
| `B` _extends_ `string` | `never` |
## Parameters
| Parameter | Type |
| --------- | ----------------------------------------------------------------------------------- |
| `deps` | [`RandomBytesDep`](https://evolu.dev/docs/api-reference/common/Crypto/interfaces/RandomBytesDep) |
## Returns
\[`B`\] _extends_ \[`never`\] ? `string` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Id"`\> : `string` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Id"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`B`\>
createIdAsUuidv7 - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / createIdAsUuidv7
# Function: createIdAsUuidv7()
```ts
function createIdAsUuidv7<B>(
deps,
): [B] extends [never] ? string & Brand<"Id"> : string & Brand<"Id"> & Brand<B>;
```
Defined in: [packages/common/src/Type.ts:1709](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1709)
Creates an [Id](https://evolu.dev/docs/api-reference/common/Type/variables/Id) embedding timestamp bits (UUID v7 layout) before
Base64Url encoding.
Tradeoff: better insertion locality / index performance for huge datasets vs
leaking creation time everywhere the Id appears. Evolu uses [createId](https://evolu.dev/docs/api-reference/common/Type/functions/createId)
by default to avoid activity leakage; choose this only if you explicitly
accept timestamp exposure.
### Example
```ts
const id = createIdAsUuidv7({ randomBytes, time });
const todoId = createIdAsUuidv7<"Todo">({ randomBytes, time });
```
## Type Parameters
| Type Parameter | Default type |
| ---------------------- | ------------ |
| `B` _extends_ `string` | `never` |
## Parameters
| Parameter | Type |
| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `deps` | [`RandomBytesDep`](https://evolu.dev/docs/api-reference/common/Crypto/interfaces/RandomBytesDep) & [`TimeDep`](https://evolu.dev/docs/api-reference/common/Time/interfaces/TimeDep) |
## Returns
\[`B`\] _extends_ \[`never`\] ? `string` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Id"`\> : `string` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Id"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`B`\>
createIdFromString - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / createIdFromString
# Function: createIdFromString()
```ts
function createIdFromString<B>(
value,
): [B] extends [never] ? string & Brand<"Id"> : string & Brand<"Id"> & Brand<B>;
```
Defined in: [packages/common/src/Type.ts:1683](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1683)
Creates an [Id](https://evolu.dev/docs/api-reference/common/Type/variables/Id) from a string using SHA-256.
When integrating with external systems that use different ID formats, use
this function to convert external IDs into valid Evolu IDs.
In Evolu's CRDT, the ID serves as the unique identifier for conflict
resolution across distributed clients. When multiple clients create records
with the same external identifier, they must resolve to the same Evolu ID to
ensure data consistency.
### Example
```ts
// Both clients will generate the same ID
const id1 = createIdFromString("user-api-123");
const id2 = createIdFromString("user-api-123");
console.log(id1 === id2); // true
upsert("todo", {
id: createIdFromString("external-todo-456"),
title: "Synced from external system",
});
```
**Important**: This transformation uses the first 16 bytes of SHA-256 hash of
the string bytes, therefore it's not possible to recover the original
external string from the generated [Id](https://evolu.dev/docs/api-reference/common/Type/variables/Id). If you need to preserve the
original external ID, store it in a separate column.
## Type Parameters
| Type Parameter | Default type |
| ---------------------- | ------------ |
| `B` _extends_ `string` | `never` |
## Parameters
| Parameter | Type |
| --------- | -------- |
| `value` | `string` |
## Returns
\[`B`\] _extends_ \[`never`\] ? `string` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Id"`\> : `string` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Id"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`B`\>
createTypeErrorFormatter - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / createTypeErrorFormatter
# Function: createTypeErrorFormatter()
```ts
function createTypeErrorFormatter<Error>(format): TypeErrorFormatter<Error>;
```
Defined in: [packages/common/src/Type.ts:598](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L598)
Creates a formatter function for [TypeError](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError).
The formatter generates human-readable error messages using a custom
formatting function and a safely stringified error value.
### Example
```ts
const formatStringError = createTypeErrorFormatter<StringError>(
(value) => `A value ${value} is not a string.`,
);
```
## Type Parameters
| Type Parameter |
| --------------------------------------------------------------------------------------------------------------------- |
| `Error` _extends_ [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError)\<`Capitalize`\<`string`\>\> |
## Parameters
| Parameter | Type |
| --------- | --------------------- |
| `format` | (`error`) => `string` |
## Returns
[`TypeErrorFormatter`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/TypeErrorFormatter)\<`Error`\>
dateIsoToDate - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / dateIsoToDate
# Function: dateIsoToDate()
```ts
function dateIsoToDate(value): Date;
```
Defined in: [packages/common/src/Type.ts:1121](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1121)
## Parameters
| Parameter | Type |
| --------- | ------------------------------------------------------------------------------------------ |
| `value` | `string` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"DateIso"`\> |
## Returns
`Date`
dateToDateIso - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / dateToDateIso
# Function: dateToDateIso()
```ts
function dateToDateIso(value): Result<string & Brand<"DateIso">, DateIsoError>;
```
Defined in: [packages/common/src/Type.ts:1118](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1118)
## Parameters
| Parameter | Type |
| --------- | ------ |
| `value` | `Date` |
## Returns
[`Result`](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result)\<`string` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"DateIso"`\>, [`DateIsoError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/DateIsoError)\>
formatArrayError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / formatArrayError
# Function: formatArrayError()
```ts
function formatArrayError<Error>(
formatTypeError,
): TypeErrorFormatter<ArrayError<Error>>;
```
Defined in: [packages/common/src/Type.ts:2392](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L2392)
## Type Parameters
| Type Parameter |
| --------------------------------------------------------------------------------------------------------------------- |
| `Error` _extends_ [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError)\<`Capitalize`\<`string`\>\> |
## Parameters
| Parameter | Type |
| ----------------- | ------------------------------------------------------------------------------------------------------ |
| `formatTypeError` | [`TypeErrorFormatter`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/TypeErrorFormatter)\<`Error`\> |
## Returns
[`TypeErrorFormatter`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/TypeErrorFormatter)\<[`ArrayError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/ArrayError)\<`Error`\>\>
formatObjectError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / formatObjectError
# Function: formatObjectError()
```ts
function formatObjectError<Error>(
formatTypeError,
): TypeErrorFormatter<ObjectError<Record<string, Error>>>;
```
Defined in: [packages/common/src/Type.ts:3102](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L3102)
## Type Parameters
| Type Parameter |
| --------------------------------------------------------------------------------------------------------------------- |
| `Error` _extends_ [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError)\<`Capitalize`\<`string`\>\> |
## Parameters
| Parameter | Type |
| ----------------- | ------------------------------------------------------------------------------------------------------ |
| `formatTypeError` | [`TypeErrorFormatter`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/TypeErrorFormatter)\<`Error`\> |
## Returns
[`TypeErrorFormatter`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/TypeErrorFormatter)\<[`ObjectError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/ObjectError)\<`Record`\<`string`, `Error`\>\>\>
formatObjectWithRecordError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / formatObjectWithRecordError
# Function: formatObjectWithRecordError()
```ts
function formatObjectWithRecordError<Error>(
formatTypeError,
): TypeErrorFormatter<
ObjectWithRecordError<Record<string, Error>, Error, Error>
>;
```
Defined in: [packages/common/src/Type.ts:3183](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L3183)
## Type Parameters
| Type Parameter |
| --------------------------------------------------------------------------------------------------------------------- |
| `Error` _extends_ [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError)\<`Capitalize`\<`string`\>\> |
## Parameters
| Parameter | Type |
| ----------------- | ------------------------------------------------------------------------------------------------------ |
| `formatTypeError` | [`TypeErrorFormatter`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/TypeErrorFormatter)\<`Error`\> |
## Returns
[`TypeErrorFormatter`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/TypeErrorFormatter)\<[`ObjectWithRecordError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/ObjectWithRecordError)\<`Record`\<`string`, `Error`\>, `Error`, `Error`\>\>
formatRecordError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / formatRecordError
# Function: formatRecordError()
```ts
function formatRecordError<Error>(
formatTypeError,
): TypeErrorFormatter<RecordError<Error, Error>>;
```
Defined in: [packages/common/src/Type.ts:2719](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L2719)
## Type Parameters
| Type Parameter |
| --------------------------------------------------------------------------------------------------------------------- |
| `Error` _extends_ [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError)\<`Capitalize`\<`string`\>\> |
## Parameters
| Parameter | Type |
| ----------------- | ------------------------------------------------------------------------------------------------------ |
| `formatTypeError` | [`TypeErrorFormatter`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/TypeErrorFormatter)\<`Error`\> |
## Returns
[`TypeErrorFormatter`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/TypeErrorFormatter)\<[`RecordError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/RecordError)\<`Error`, `Error`\>\>
formatSetError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / formatSetError
# Function: formatSetError()
```ts
function formatSetError<Error>(
formatTypeError,
): TypeErrorFormatter<SetError<Error>>;
```
Defined in: [packages/common/src/Type.ts:2510](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L2510)
## Type Parameters
| Type Parameter |
| --------------------------------------------------------------------------------------------------------------------- |
| `Error` _extends_ [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError)\<`Capitalize`\<`string`\>\> |
## Parameters
| Parameter | Type |
| ----------------- | ------------------------------------------------------------------------------------------------------ |
| `formatTypeError` | [`TypeErrorFormatter`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/TypeErrorFormatter)\<`Error`\> |
## Returns
[`TypeErrorFormatter`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/TypeErrorFormatter)\<[`SetError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/SetError)\<`Error`\>\>
formatSimplePasswordError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / formatSimplePasswordError
# Function: formatSimplePasswordError()
```ts
function formatSimplePasswordError(
formatTypeError,
): TypeErrorFormatter<
BrandWithoutRefineError<
"SimplePassword",
StringError | TrimmedError | MinLengthError<8> | MaxLengthError<64>
>
>;
```
Defined in: [packages/common/src/Type.ts:1583](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1583)
## Parameters
| Parameter | Type |
| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `formatTypeError` | [`TypeErrorFormatter`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/TypeErrorFormatter)\< \| [`StringError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/StringError) \| [`TrimmedError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TrimmedError) \| [`MinLengthError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/MinLengthError)\<`8`\> \| [`MaxLengthError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/MaxLengthError)\<`64`\>\> |
## Returns
[`TypeErrorFormatter`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/TypeErrorFormatter)\<[`BrandWithoutRefineError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/BrandWithoutRefineError)\<`"SimplePassword"`,
\| [`StringError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/StringError)
\| [`TrimmedError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TrimmedError)
\| [`MinLengthError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/MinLengthError)\<`8`\>
\| [`MaxLengthError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/MaxLengthError)\<`64`\>\>\>
formatTupleError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / formatTupleError
# Function: formatTupleError()
```ts
function formatTupleError<Error>(
formatTypeError,
): TypeErrorFormatter<TupleError<Error>>;
```
Defined in: [packages/common/src/Type.ts:3585](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L3585)
## Type Parameters
| Type Parameter |
| --------------------------------------------------------------------------------------------------------------------- |
| `Error` _extends_ [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError)\<`Capitalize`\<`string`\>\> |
## Parameters
| Parameter | Type |
| ----------------- | ------------------------------------------------------------------------------------------------------ |
| `formatTypeError` | [`TypeErrorFormatter`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/TypeErrorFormatter)\<`Error`\> |
## Returns
[`TypeErrorFormatter`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/TypeErrorFormatter)\<[`TupleError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TupleError)\<`Error`\>\>
formatUnionError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / formatUnionError
# Function: formatUnionError()
```ts
function formatUnionError<Error>(
formatTypeError,
): TypeErrorFormatter<UnionError<Error>>;
```
Defined in: [packages/common/src/Type.ts:3306](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L3306)
## Type Parameters
| Type Parameter |
| --------------------------------------------------------------------------------------------------------------------- |
| `Error` _extends_ [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError)\<`Capitalize`\<`string`\>\> |
## Parameters
| Parameter | Type |
| ----------------- | ------------------------------------------------------------------------------------------------------ |
| `formatTypeError` | [`TypeErrorFormatter`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/TypeErrorFormatter)\<`Error`\> |
## Returns
[`TypeErrorFormatter`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/TypeErrorFormatter)\<[`UnionError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/UnionError)\<`Error`\>\>
id - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / id
# Function: id()
```ts
function id<Table>(table): TableId<Table>;
```
Defined in: [packages/common/src/Type.ts:1744](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1744)
Creates a branded [Id](https://evolu.dev/docs/api-reference/common/Type/variables/Id) Type for a table's primary key.
The table name becomes an additional brand for type safety.
### Example
```ts
const TodoId = id("Todo");
// string & Brand<"Id"> & Brand<"Todo">
type TodoId = typeof TodoId.Type;
```
## Type Parameters
| Type Parameter |
| -------------------------- |
| `Table` _extends_ `string` |
## Parameters
| Parameter | Type |
| --------- | ------- |
| `table` | `Table` |
## Returns
[`TableId`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TableId)\<`Table`\>
idBytesToId - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / idBytesToId
# Function: idBytesToId()
```ts
function idBytesToId(idBytes): string & Brand<"Id">;
```
Defined in: [packages/common/src/Type.ts:1796](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1796)
## Parameters
| Parameter | Type |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `idBytes` | `Uint8Array`\<`ArrayBufferLike`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Length16"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"IdBytes"`\> |
## Returns
`string` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Id"`\>
idToIdBytes - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / idToIdBytes
# Function: idToIdBytes()
```ts
function idToIdBytes(
id,
): Uint8Array<ArrayBufferLike> & Brand<"Length16"> & Brand<"IdBytes">;
```
Defined in: [packages/common/src/Type.ts:1792](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1792)
## Parameters
| Parameter | Type |
| --------- | ------------------------------------------------------------------------------------- |
| `id` | `string` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Id"`\> |
## Returns
`Uint8Array`\<`ArrayBufferLike`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Length16"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"IdBytes"`\>
instanceOf - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / instanceOf
# Function: instanceOf()
```ts
function instanceOf<T>(ctor): InstanceOfType<T>;
```
Defined in: [packages/common/src/Type.ts:779](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L779)
`instanceof` [Type](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).
Ensures that a value is an instance of the given class constructor.
### Example
```ts
class User {
constructor(public name: string) {}
}
const UserInstance = instanceOf(User);
const result = UserInstance.from(new User("Alice")); // ok
const error = UserInstance.from({}); // err
```
## Type Parameters
| Type Parameter |
| ---------------------------------- |
| `T` _extends_ (...`args`) => `any` |
## Parameters
| Parameter | Type |
| --------- | ---- |
| `ctor` | `T` |
## Returns
[`InstanceOfType`](https://evolu.dev/docs/api-reference/common/Type/interfaces/InstanceOfType)\<`T`\>
isOptionalType - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / isOptionalType
# Function: isOptionalType()
```ts
function isOptionalType(x): x is OptionalType<any>;
```
Defined in: [packages/common/src/Type.ts:3899](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L3899)
Determines if a given type is an [OptionalType](https://evolu.dev/docs/api-reference/common/Type/interfaces/OptionalType).
## Parameters
| Parameter | Type |
| --------- | --------- |
| `x` | `unknown` |
## Returns
`x is OptionalType<any>`
isType - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / isType
# Function: isType()
```ts
function isType(value): value is AnyType;
```
Defined in: [packages/common/src/Type.ts:516](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L516)
Checks if the given value is an [Type](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).
## Parameters
| Parameter | Type |
| --------- | --------- |
| `value` | `unknown` |
## Returns
`value is AnyType`
isUnionType - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / isUnionType
# Function: isUnionType()
```ts
function isUnionType(t): t is UnionType<[AnyType, ...AnyType[]]>;
```
Defined in: [packages/common/src/Type.ts:3317](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L3317)
## Parameters
| Parameter | Type |
| --------- | --------------------------------------------------------------------- |
| `t` | [`AnyType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/AnyType) |
## Returns
`t is UnionType<[AnyType, ...AnyType[]]>`
json - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / json
# Function: json()
```ts
function json<T, Name>(
type,
name,
): [
BrandType<
Type<"String", string, string, StringError, string, StringError>,
Name,
JsonError | InferErrors<T>,
StringError
>,
(value) => string & Brand<Name>,
(value) => InferType<T>,
];
```
Defined in: [packages/common/src/Type.ts:3825](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L3825)
Creates a branded JSON string [Type](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type) and type-safe conversion functions
for a given Type.
This factory creates:
1. A branded string Type that validates JSON parsing and structural conformity
2. A serialization function (Type → branded JSON string)
3. A parsing function (branded JSON string → Type, skipping validation)
Optimized for Evolu's SQLite workflow where we store typed JSON strings and
need type-safe conversions without double parsing.
### Example
```ts
const Person = object({
name: NonEmptyString100,
age: FiniteNumber,
});
type Person = typeof Person.Type;
const [PersonJson, personToPersonJson, personJsonToPerson] = json(
Person,
"PersonJson",
);
// string & Brand<"PersonJson">
type PersonJson = typeof PersonJson.Type;
// Usage:
const person: Person = { name: "Alice", age: 30 };
const jsonString = personToPersonJson(person); // PersonJson
const backToPerson = personJsonToPerson(jsonString); // Person
```
## Type Parameters
| Type Parameter |
| ----------------------------------------------------------------------------------- |
| `T` _extends_ [`AnyType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/AnyType) |
| `Name` _extends_ `string` |
## Parameters
| Parameter | Type |
| --------- | ------ |
| `type` | `T` |
| `name` | `Name` |
## Returns
\[[`BrandType`](https://evolu.dev/docs/api-reference/common/Type/interfaces/BrandType)\<[`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type)\<`"String"`, `string`, `string`, [`StringError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/StringError), `string`, [`StringError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/StringError)\>, `Name`,
\| [`JsonError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/JsonError)
\| [`InferErrors`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferErrors)\<`T`\>, [`StringError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/StringError)\>, (`value`) => `string` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`Name`\>, (`value`) => [`InferType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferType)\<`T`\>\]
jsonToJsonValue - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / jsonToJsonValue
# Function: jsonToJsonValue()
```ts
function jsonToJsonValue(value): JsonValue;
```
Defined in: [packages/common/src/Type.ts:3787](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L3787)
## Parameters
| Parameter | Type |
| --------- | --------------------------------------------------------------------------------------- |
| `value` | `string` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Json"`\> |
## Returns
[`JsonValue`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/JsonValue)
jsonValueToJson - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / jsonValueToJson
# Function: jsonValueToJson()
```ts
function jsonValueToJson(value): string & Brand<"Json">;
```
Defined in: [packages/common/src/Type.ts:3784](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L3784)
## Parameters
| Parameter | Type |
| --------- | ------------------------------------------------------------------------- |
| `value` | [`JsonValue`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/JsonValue) |
## Returns
`string` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Json"`\>
literal - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / literal
# Function: literal()
```ts
function literal<T>(expected): LiteralType<T>;
```
Defined in: [packages/common/src/Type.ts:2248](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L2248)
Literal [Type](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).
https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#literal-types
### Example
```ts
const LiteralHello = literal("Hello");
const result = LiteralHello.from("Hello"); // ok("Hello")
const errorResult = LiteralHello.from("World"); // err
```
TODO: Add JsonValue
## Type Parameters
| Type Parameter |
| ------------------------------------------------------------------------------------ |
| `T` _extends_ [`Literal`](https://evolu.dev/docs/api-reference/common/Types/type-aliases/Literal) |
## Parameters
| Parameter | Type |
| ---------- | ---- |
| `expected` | `T` |
## Returns
[`LiteralType`](https://evolu.dev/docs/api-reference/common/Type/interfaces/LiteralType)\<`T`\>
nullOr - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / nullOr
# Function: nullOr()
```ts
function nullOr<T>(
type,
): UnionType<[Type<"Null", null, null, NullError, null, NullError>, T]>;
```
Defined in: [packages/common/src/Type.ts:3417](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L3417)
`union(null, T)` [Type](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).
### Example
```ts
const NullOrString = nullOr(String);
NullOrString.from("hello"); // ok("hello")
NullOrString.from(null); // ok(null)
NullOrString.from(42); // err(...)
```
## Type Parameters
| Type Parameter |
| ----------------------------------------------------------------------------------- |
| `T` _extends_ [`AnyType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/AnyType) |
## Parameters
| Parameter | Type |
| --------- | ---- |
| `type` | `T` |
## Returns
[`UnionType`](https://evolu.dev/docs/api-reference/common/Type/interfaces/UnionType)\<\[[`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type)\<`"Null"`, `null`, `null`, [`NullError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/NullError), `null`, [`NullError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/NullError)\>, `T`\]\>
nullableToOptional - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / nullableToOptional
# Function: nullableToOptional()
```ts
function nullableToOptional<Props>(
props,
): ObjectType<NullableToOptionalProps<Props>>;
```
Defined in: [packages/common/src/Type.ts:3949](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L3949)
Converts each “nullable” property (a union that includes [Null](https://evolu.dev/docs/api-reference/common/Type/variables/Null)) into an
[optional](https://evolu.dev/docs/api-reference/common/Type/functions/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.
## Type Parameters
| Type Parameter |
| ------------------------------------------------------------------------------------------------------------- |
| `Props` _extends_ `Record`\<`string`, [`AnyType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/AnyType)\> |
## Parameters
| Parameter | Type |
| --------- | ------- |
| `props` | `Props` |
## Returns
[`ObjectType`](https://evolu.dev/docs/api-reference/common/Type/interfaces/ObjectType)\<[`NullableToOptionalProps`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/NullableToOptionalProps)\<`Props`\>\>
nullishOr - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / nullishOr
# Function: nullishOr()
```ts
function nullishOr<T>(
type,
): UnionType<
[
Type<
"Undefined",
undefined,
undefined,
UndefinedError,
undefined,
UndefinedError
>,
Type<"Null", null, null, NullError, null, NullError>,
T,
]
>;
```
Defined in: [packages/common/src/Type.ts:3457](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L3457)
`union(undefined, null, T)` [Type](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).
Learn more:
https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-7.html#nullish-coalescing
### Example
```ts
const NullishOrString = nullishOr(String);
NullishOrString.from("test"); // ok("test")
NullishOrString.from(null); // ok(null)
NullishOrString.from(undefined); // ok()
NullishOrString.from(42); // err(...)
```
## Type Parameters
| Type Parameter |
| ----------------------------------------------------------------------------------- |
| `T` _extends_ [`AnyType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/AnyType) |
## Parameters
| Parameter | Type |
| --------- | ---- |
| `type` | `T` |
## Returns
[`UnionType`](https://evolu.dev/docs/api-reference/common/Type/interfaces/UnionType)\<\[[`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type)\<`"Undefined"`, `undefined`, `undefined`, [`UndefinedError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/UndefinedError), `undefined`, [`UndefinedError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/UndefinedError)\>, [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type)\<`"Null"`, `null`, `null`, [`NullError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/NullError), `null`, [`NullError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/NullError)\>, `T`\]\>
object - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / object
# Function: object()
Defined in: [packages/common/src/Type.ts:2838](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L2838)
Object [Type](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).
This validates that:
- The value is a plain object (checked with [isPlainObject](https://evolu.dev/docs/api-reference/common/Object/functions/isPlainObject)).
- The object has no extra properties beyond the specified keys unless an index
signature is provided.
- Each property's value matches the specified Type.
When an index signature is included, the object can have additional keys that
conform to the specified key and value Types.
The resulting `ObjectType` includes `props` for reflection, which defines the
expected structure, and optionally an `record` for flexible key/value pairs.
https://www.typescriptlang.org/docs/handbook/2/objects.html#index-signatures
### Examples
#### Basic Object Validation
```ts
const User = object({
name: NonEmptyTrimmedString,
age: PositiveNumber,
});
type User = typeof User.Type;
const result = User.from({ name: "John", age: 30 }); // ok({ name: "John", age: 30 })
const error = User.from({ name: "John", age: -5 }); // err
```
#### Optional Properties
In this example the `age` property is marked as optional using
[optional](https://evolu.dev/docs/api-reference/common/Type/functions/optional).
```ts
const User = object({
name: NonEmptyString, // Required
age: optional(PositiveNumber), // Optional
});
type User = typeof User.Type;
```
#### Allowing Additional Properties
```ts
const UserWithAnyExtraProperties = object(
{
name: NonEmptyString,
age: PositiveNumber,
},
record(String, Unknown),
);
expect(UserWithAnyExtraProperties.from({ name: "a", age: 1, foo: 1 })).toEqual({
ok: true,
value: { age: 1, foo: 1, name: "a" },
});
```
#### Combining Fixed and Flexible Properties
```ts
const NumberDictionary = object({ length: Number }, record(String, Number));
const validInput = {
length: 5,
extraKey1: 10,
extraKey2: 15,
};
const fromResult = NumberDictionary.from(validInput);
expect(fromResult).toEqual(ok(validInput));
const invalidInput = {
length: 5,
extraKey1: "not a number",
extraKey2: 15,
};
const invalidFromResult = NumberDictionary.fromUnknown(invalidInput);
expect(invalidFromResult).toEqual(
err({
type: "Object",
value: invalidInput,
reason: {
kind: "IndexValue",
key: "extraKey1",
error: { type: "Number", value: "not a number" },
},
}),
);
```
### Type Parameters
| Type Parameter |
| ------------------------------------------------------------------------------------------------------------- |
| `Props` _extends_ `Record`\<`string`, [`AnyType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/AnyType)\> |
### Parameters
| Parameter | Type |
| --------- | ------- |
| `props` | `Props` |
### Returns
[`ObjectType`](https://evolu.dev/docs/api-reference/common/Type/interfaces/ObjectType)\<`Props`\>
Defined in: [packages/common/src/Type.ts:2842](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L2842)
Object [Type](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).
This validates that:
- The value is a plain object (checked with [isPlainObject](https://evolu.dev/docs/api-reference/common/Object/functions/isPlainObject)).
- The object has no extra properties beyond the specified keys unless an index
signature is provided.
- Each property's value matches the specified Type.
When an index signature is included, the object can have additional keys that
conform to the specified key and value Types.
The resulting `ObjectType` includes `props` for reflection, which defines the
expected structure, and optionally an `record` for flexible key/value pairs.
https://www.typescriptlang.org/docs/handbook/2/objects.html#index-signatures
### Examples
#### Basic Object Validation
```ts
const User = object({
name: NonEmptyTrimmedString,
age: PositiveNumber,
});
type User = typeof User.Type;
const result = User.from({ name: "John", age: 30 }); // ok({ name: "John", age: 30 })
const error = User.from({ name: "John", age: -5 }); // err
```
#### Optional Properties
In this example the `age` property is marked as optional using
[optional](https://evolu.dev/docs/api-reference/common/Type/functions/optional).
```ts
const User = object({
name: NonEmptyString, // Required
age: optional(PositiveNumber), // Optional
});
type User = typeof User.Type;
```
#### Allowing Additional Properties
```ts
const UserWithAnyExtraProperties = object(
{
name: NonEmptyString,
age: PositiveNumber,
},
record(String, Unknown),
);
expect(UserWithAnyExtraProperties.from({ name: "a", age: 1, foo: 1 })).toEqual({
ok: true,
value: { age: 1, foo: 1, name: "a" },
});
```
#### Combining Fixed and Flexible Properties
```ts
const NumberDictionary = object({ length: Number }, record(String, Number));
const validInput = {
length: 5,
extraKey1: 10,
extraKey2: 15,
};
const fromResult = NumberDictionary.from(validInput);
expect(fromResult).toEqual(ok(validInput));
const invalidInput = {
length: 5,
extraKey1: "not a number",
extraKey2: 15,
};
const invalidFromResult = NumberDictionary.fromUnknown(invalidInput);
expect(invalidFromResult).toEqual(
err({
type: "Object",
value: invalidInput,
reason: {
kind: "IndexValue",
key: "extraKey1",
error: { type: "Number", value: "not a number" },
},
}),
);
```
### Type Parameters
| Type Parameter |
| ------------------------------------------------------------------------------------------------------------------------------ |
| `Props` _extends_ `Record`\<`string`, [`AnyType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/AnyType)\> |
| `KeyName` _extends_ `string` |
| `KeyT` _extends_ `string` |
| `KeyInput` _extends_ `string` |
| `KeyError` _extends_ [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError)\<`Capitalize`\<`string`\>\> |
| `KeyParent` _extends_ `string` |
| `KeyParentError` _extends_ [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError)\<`Capitalize`\<`string`\>\> |
| `Value` _extends_ [`AnyType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/AnyType) |
### Parameters
| Parameter | Type |
| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `props` | `Props` |
| `record` | [`RecordType`](https://evolu.dev/docs/api-reference/common/Type/interfaces/RecordType)\<`KeyName`, `KeyT`, `KeyInput`, `KeyError`, `KeyParent`, `KeyParentError`, `Value`\> |
### Returns
[`ObjectWithRecordType`](https://evolu.dev/docs/api-reference/common/Type/interfaces/ObjectWithRecordType)\<`Props`, `KeyName`, `KeyT`, `KeyInput`, `KeyError`, `KeyParent`, `KeyParentError`, `Value`\>
omit - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / omit
# Function: omit()
```ts
function omit<T, Keys>(objectType, ...keys): ObjectType<Omit<T["props"], Keys>>;
```
Defined in: [packages/common/src/Type.ts:3995](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L3995)
Create a new `object` [Type](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type) by omitting some keys.
## Type Parameters
| Type Parameter |
| ------------------------------------------------------------------------------------------------ |
| `T` _extends_ [`ObjectType`](https://evolu.dev/docs/api-reference/common/Type/interfaces/ObjectType)\<`any`\> |
| `Keys` _extends_ `string` \| `number` \| `symbol` |
## Parameters
| Parameter | Type |
| ------------ | ----------------- |
| `objectType` | `T` |
| ...`keys` | readonly `Keys`[] |
## Returns
[`ObjectType`](https://evolu.dev/docs/api-reference/common/Type/interfaces/ObjectType)\<`Omit`\<`T`\[`"props"`\], `Keys`\>\>
optional - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / optional
# Function: optional()
```ts
function optional<T>(type): OptionalType<T>;
```
Defined in: [packages/common/src/Type.ts:3879](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L3879)
Optional [Type](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).
Marks a `Type` as **optional**, meaning:
- If the value is **present**, it must match the given `Type`.
- If the value is **absent**, it is **not included** in the final object.
This is different from [undefinedOr](https://evolu.dev/docs/api-reference/common/Type/functions/undefinedOr), which allows explicit `undefined`
but **still requires the key to exist**.
### Example:
```ts
const Todo = object({
id: TodoId,
title: NonEmptyString1000,
isCompleted: optional(SqliteBoolean),
});
```
## Type Parameters
| Type Parameter |
| ----------------------------------------------------------------------------------- |
| `T` _extends_ [`AnyType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/AnyType) |
## Parameters
| Parameter | Type |
| --------- | ---- |
| `type` | `T` |
## Returns
[`OptionalType`](https://evolu.dev/docs/api-reference/common/Type/interfaces/OptionalType)\<`T`\>
parseJson - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / parseJson
# Function: parseJson()
```ts
function parseJson(value): Result<JsonValue, JsonError>;
```
Defined in: [packages/common/src/Type.ts:3746](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L3746)
## Parameters
| Parameter | Type |
| --------- | -------- |
| `value` | `string` |
## Returns
[`Result`](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result)\<[`JsonValue`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/JsonValue), [`JsonError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/JsonError)\>
partial - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / partial
# Function: partial()
```ts
function partial<Props>(
props,
): ObjectType<{ [K in string | number | symbol]: OptionalType<Props[K]> }>;
```
Defined in: [packages/common/src/Type.ts:3929](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L3929)
Creates a partial object type where all properties are optional.
This is useful when we want to validate an object in which none of the keys
are required, but if they are present they must conform to their
corresponding Types.
### Example
```ts
const PartialUser = partial({
name: NonEmptyString,
age: PositiveNumber,
});
// Valid: an empty object is accepted
PartialUser.from({});
// Valid: when provided, the properties must validate correctly
PartialUser.from({ name: "Alice" });
// Invalid: if a property is present but fails validation it returns an error
PartialUser.from({ age: -5 });
```
## Type Parameters
| Type Parameter |
| ------------------------------------------------------------------------------------------------------------- |
| `Props` _extends_ `Record`\<`string`, [`AnyType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/AnyType)\> |
## Parameters
| Parameter | Type |
| --------- | ------- |
| `props` | `Props` |
## Returns
[`ObjectType`](https://evolu.dev/docs/api-reference/common/Type/interfaces/ObjectType)\<\{ \[K in string \| number \| symbol\]: OptionalType\<Props\[K\]\> \}\>
record - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / record
# Function: record()
```ts
function record<
KeyName,
KeyT,
KeyInput,
KeyError,
KeyParent,
KeyParentError,
Value,
>(
keyType,
valueType,
): RecordType<
KeyName,
KeyT,
KeyInput,
KeyError,
KeyParent,
KeyParentError,
Value
>;
```
Defined in: [packages/common/src/Type.ts:2549](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L2549)
Record of a key [Type](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type) and value [Type](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).
- The input must be a plain object (validated by [isPlainObject](https://evolu.dev/docs/api-reference/common/Object/functions/isPlainObject)).
- Each key is validated/transformed by the `key` Type.
- Each value is validated/transformed by the `value` Type.
The resulting type is `Readonly<Record<KeyT, ValueT>>`.
### Example
```ts
const StringToNumberRecord = record(String, Number);
// ok({ "a": 1, "b": 2 })
StringToNumberRecord.from({ a: 1, b: 2 });
// err => "Key" because 42 is not a string key
StringToNumberRecord.from({ 42: 1, b: 2 });
// err => "Value" because "x" is not a number
StringToNumberRecord.from({ a: "x", b: 2 });
```
## Type Parameters
| Type Parameter |
| ------------------------------------------------------------------------------------------------------------------------------ |
| `KeyName` _extends_ `string` |
| `KeyT` _extends_ `string` |
| `KeyInput` _extends_ `string` |
| `KeyError` _extends_ [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError)\<`Capitalize`\<`string`\>\> |
| `KeyParent` _extends_ `string` |
| `KeyParentError` _extends_ [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError)\<`Capitalize`\<`string`\>\> |
| `Value` _extends_ [`AnyType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/AnyType) |
## Parameters
| Parameter | Type |
| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `keyType` | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type)\<`KeyName`, `KeyT`, `KeyInput`, `KeyError`, `KeyParent`, `KeyParentError`\> |
| `valueType` | `Value` |
## Returns
[`RecordType`](https://evolu.dev/docs/api-reference/common/Type/interfaces/RecordType)\<`KeyName`, `KeyT`, `KeyInput`, `KeyError`, `KeyParent`, `KeyParentError`, `Value`\>
recursive - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / recursive
# Function: recursive()
```ts
function recursive<ParentType>(create): RecursiveType<ParentType>;
```
Defined in: [packages/common/src/Type.ts:3357](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L3357)
Recursive [Type](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).
Recursive types can't be inferred, so we must define them using an interface
and `recursive` Type Factory that returns a [Type](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).
### Example
```ts
interface Category {
readonly name: string;
readonly subcategories: ReadonlyArray<Category>;
}
interface CategoryInput {
readonly name: string;
readonly subcategories: ReadonlyArray<CategoryInput>;
}
type CategoryError = ObjectError<{
readonly name: typeof String.Error;
readonly subcategories: ArrayError<CategoryError>;
}>;
const Category = recursive(
(): Type<"Object", Category, CategoryInput, CategoryError> =>
object({
name: String,
subcategories: array(Category),
}),
);
```
## Type Parameters
| Type Parameter |
| -------------------------------------------------------------------------------------------- |
| `ParentType` _extends_ [`AnyType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/AnyType) |
## Parameters
| Parameter | Type |
| --------- | ------------------ |
| `create` | () => `ParentType` |
## Returns
[`RecursiveType`](https://evolu.dev/docs/api-reference/common/Type/interfaces/RecursiveType)\<`ParentType`\>
set - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / set
# Function: set()
```ts
function set<ElementType>(element): SetType<ElementType>;
```
Defined in: [packages/common/src/Type.ts:2418](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L2418)
Set of a specific [Type](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).
### Example
```ts
const NumberSet = set(Number);
const result1 = NumberSet.from(new Set([1, 2, 3])); // ok(Set { 1, 2, 3 })
const result2 = NumberSet.from(new Set(["a", "b"])); // err(...)
```
## Type Parameters
| Type Parameter |
| --------------------------------------------------------------------------------------------- |
| `ElementType` _extends_ [`AnyType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/AnyType) |
## Parameters
| Parameter | Type |
| --------- | ------------- |
| `element` | `ElementType` |
## Returns
[`SetType`](https://evolu.dev/docs/api-reference/common/Type/interfaces/SetType)\<`ElementType`\>
trim - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / trim
# Function: trim()
```ts
function trim(value): string & Brand<"Trimmed">;
```
Defined in: [packages/common/src/Type.ts:1204](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1204)
## Parameters
| Parameter | Type |
| --------- | -------- |
| `value` | `string` |
## Returns
`string` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Trimmed"`\>
tuple - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / tuple
# Function: tuple()
```ts
function tuple<Elements>(...elements): TupleType<Elements>;
```
Defined in: [packages/common/src/Type.ts:3478](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L3478)
Tuple [Type](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).
Represents a tuple of specific Types.
### Example
```ts
const NameAndAge = tuple(NonEmptyTrimmedString, PositiveNumber);
const result = NameAndAge.from(["Alice", 25]); // ok(["Alice", 25])
const error = NameAndAge.from(["Alice", -10]); // err
```
## Type Parameters
| Type Parameter |
| -------------------------------------------------------------------------------------------------------------- |
| `Elements` _extends_ \[[`AnyType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/AnyType), `...AnyType[]`\] |
## Parameters
| Parameter | Type |
| ------------- | ---------- |
| ...`elements` | `Elements` |
## Returns
[`TupleType`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TupleType)\<`Elements`\>
typeErrorToStandardSchemaIssues - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / typeErrorToStandardSchemaIssues
# Function: typeErrorToStandardSchemaIssues()
```ts
function typeErrorToStandardSchemaIssues<ExtraErrors>(
error,
formatTypeError,
path,
): readonly Issue[];
```
Defined in: [packages/common/src/Type.ts:4315](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L4315)
Converts an Evolu [TypeError](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError) to Standard Schema V1 issues format.
This function recursively converts Evolu's typed errors into the Standard
Schema issue format with proper path tracking for nested structures.
## Type Parameters
| Type Parameter | Default type |
| --------------------------------------------------------------------------------------------------------------------------- | ------------ |
| `ExtraErrors` _extends_ [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError)\<`Capitalize`\<`string`\>\> | `never` |
## Parameters
| Parameter | Type | Default value |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
| `error` | [`TypeErrors`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/TypeErrors)\<`ExtraErrors`\> | `undefined` |
| `formatTypeError` | [`TypeErrorFormatter`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/TypeErrorFormatter)\<[`TypeErrors`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/TypeErrors)\<`ExtraErrors`\>\> | `undefined` |
| `path` | readonly `PropertyKey`[] | `[]` |
## Returns
readonly [`Issue`](https://evolu.dev/docs/api-reference/common/Type/namespaces/StandardSchemaV1/interfaces/Issue)[]
undefinedOr - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / undefinedOr
# Function: undefinedOr()
```ts
function undefinedOr<T>(
type,
): UnionType<
[
Type<
"Undefined",
undefined,
undefined,
UndefinedError,
undefined,
UndefinedError
>,
T,
]
>;
```
Defined in: [packages/common/src/Type.ts:3435](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L3435)
`union(undefined, T)` [Type](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).
### Example
```ts
const UndefinedOrString = undefinedOr(String);
UndefinedOrString.from("world"); // ok("world")
UndefinedOrString.from(undefined); // ok()
UndefinedOrString.from(42); // err(...)
```
## Type Parameters
| Type Parameter |
| ----------------------------------------------------------------------------------- |
| `T` _extends_ [`AnyType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/AnyType) |
## Parameters
| Parameter | Type |
| --------- | ---- |
| `type` | `T` |
## Returns
[`UnionType`](https://evolu.dev/docs/api-reference/common/Type/interfaces/UnionType)\<\[[`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type)\<`"Undefined"`, `undefined`, `undefined`, [`UndefinedError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/UndefinedError), `undefined`, [`UndefinedError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/UndefinedError)\>, `T`\]\>
union - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / union
# Function: union()
Defined in: [packages/common/src/Type.ts:3229](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L3229)
Union [Type](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).
`UnionType` represents a union of multiple member Types. Accepts both
[Type](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type) and literal values as arguments.
Note that the `union` Type Factory delegates `fromParent` to `fromUnknown`.
That's because the union members can have different `Parent` types, and at
runtime, it is impossible to determine which member should process a given
`Parent` value.
### Example
```ts
const AorB = union("a", "b");
const result1 = AorB.from("a"); // ok("a")
const result2 = AorB.from("c"); // err
const StringOrNumber = union(String, Number);
const result3 = StringOrNumber.from(42); // ok(42)
```
### Type Parameters
| Type Parameter |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `Members` _extends_ \[[`AnyType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/AnyType), [`AnyType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/AnyType), `...AnyType[]`\] |
### Parameters
| Parameter | Type |
| ------------ | --------- |
| ...`members` | `Members` |
### Returns
[`UnionType`](https://evolu.dev/docs/api-reference/common/Type/interfaces/UnionType)\<`Members`\>
Defined in: [packages/common/src/Type.ts:3233](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L3233)
Union [Type](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).
`UnionType` represents a union of multiple member Types. Accepts both
[Type](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type) and literal values as arguments.
Note that the `union` Type Factory delegates `fromParent` to `fromUnknown`.
That's because the union members can have different `Parent` types, and at
runtime, it is impossible to determine which member should process a given
`Parent` value.
### Example
```ts
const AorB = union("a", "b");
const result1 = AorB.from("a"); // ok("a")
const result2 = AorB.from("c"); // err
const StringOrNumber = union(String, Number);
const result3 = StringOrNumber.from(42); // ok(42)
```
### Type Parameters
| Type Parameter |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Literals` _extends_ \[[`Literal`](https://evolu.dev/docs/api-reference/common/Types/type-aliases/Literal), [`Literal`](https://evolu.dev/docs/api-reference/common/Types/type-aliases/Literal), `...Literal[]`\] |
### Parameters
| Parameter | Type |
| ------------- | ---------- |
| ...`literals` | `Literals` |
### Returns
[`UnionType`](https://evolu.dev/docs/api-reference/common/Type/interfaces/UnionType)\<\{ \[K in string \| number \| symbol\]: LiteralType\<Literals\[K\<K\>\]\> \}\>
validMutationSize - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / validMutationSize
# Function: validMutationSize()
```ts
function validMutationSize<T>(
type,
): BrandType<T, "ValidMutationSize", ValidMutationSizeError, InferErrors<T>>;
```
Defined in: [packages/common/src/Type.ts:4018](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L4018)
Evolu has to limit the maximum mutation size. Otherwise, sync couldn't use
the `maxProtocolMessageRangesSize`. The max size is 640KB in bytes, measured
via MessagePack. Evolu Protocol DbChange will be smaller thanks to various
optimizations.
## Type Parameters
| Type Parameter |
| ----------------------------------------------------------------------------------- |
| `T` _extends_ [`AnyType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/AnyType) |
## Parameters
| Parameter | Type |
| --------- | ---- |
| `type` | `T` |
## Returns
[`BrandType`](https://evolu.dev/docs/api-reference/common/Type/interfaces/BrandType)\<`T`, `"ValidMutationSize"`, [`ValidMutationSizeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/ValidMutationSizeError), [`InferErrors`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferErrors)\<`T`\>\>
ArrayError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / ArrayError
# Interface: ArrayError\<Error\>
Defined in: [packages/common/src/Type.ts:2380](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L2380)
## Extends
- [`TypeErrorWithReason`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeErrorWithReason)\<`"Array"`,
\| \{
`kind`: `"NotArray"`;
\}
\| \{
`error`: `Error`;
`index`: `number`;
`kind`: `"Element"`;
\}\>
## Type Parameters
| Type Parameter | Default type |
| ----------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
| `Error` _extends_ [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError) | [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError) |
## Properties
| Property | Modifier | Type | Description | Inherited from | Defined in |
| ---------------------------- | ---------- | ------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="reason"></a> `reason` | `readonly` | \| \{ `kind`: `"NotArray"`; \} \| \{ `error`: `Error`; `index`: `number`; `kind`: `"Element"`; \} | The detailed reason for the error, represented as a tagged union. | [`TypeErrorWithReason`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeErrorWithReason).[`reason`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeErrorWithReason.mdx#reason-1) | [packages/common/src/Type.ts:444](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L444) |
| <a id="type"></a> `type` | `readonly` | `"Array"` | - | [`TypeErrorWithReason`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeErrorWithReason).[`type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeErrorWithReason.mdx#type) | [packages/common/src/Type.ts:428](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L428) |
| <a id="value"></a> `value` | `readonly` | `unknown` | The value that was received and caused the error. Provides additional context for debugging and validation feedback. | [`TypeErrorWithReason`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeErrorWithReason).[`value`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeErrorWithReason.mdx#value) | [packages/common/src/Type.ts:434](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L434) |
ArrayType - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / ArrayType
# Interface: ArrayType\<ElementType\>
Defined in: [packages/common/src/Type.ts:2369](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L2369)
ArrayType extends Type with an additional `element` property for reflection.
## Extends
- [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type)\<`"Array"`, `ReadonlyArray`\<[`InferType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferType)\<`ElementType`\>\>, `ReadonlyArray`\<[`InferInput`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferInput)\<`ElementType`\>\>, [`ArrayError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/ArrayError)\<[`InferError`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferError)\<`ElementType`\>\>, `ReadonlyArray`\<[`InferParent`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferParent)\<`ElementType`\>\>, [`ArrayError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/ArrayError)\<[`InferParentError`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferParentError)\<`ElementType`\>\>\>
## Type Parameters
| Type Parameter |
| --------------------------------------------------------------------------------------------- |
| `ElementType` _extends_ [`AnyType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/AnyType) |
## Properties
| Property | Modifier | Type | Description | Inherited from | Defined in |
| ------------------------------------------------ | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="evolutypesymbol"></a> `[EvoluTypeSymbol]` | `readonly` | `true` | - | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`[EvoluTypeSymbol]`](/docs/api-reference/common/Type/interfaces/Type.mdx#evolutypesymbol) | [packages/common/src/Type.ts:353](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L353) |
| <a id="standard"></a> `~standard` | `readonly` | [`Props`](https://evolu.dev/docs/api-reference/common/Type/namespaces/StandardSchemaV1/interfaces/Props)\<readonly [`InferInput`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferInput)\<`ElementType`\>[], readonly [`InferType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferType)\<`ElementType`\>[]\> | The Standard Schema properties. | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`~standard`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#standard) | [packages/common/src/Type.ts:4450](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L4450) |
| <a id="element"></a> `element` | `readonly` | `ElementType` | - | - | [packages/common/src/Type.ts:2377](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L2377) |
| <a id="error"></a> `Error` | `public` | [`ArrayError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/ArrayError)\<[`InferError`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferError)\<`ElementType`\>\> | The specific error introduced by this Type. ### Example `type StringError = typeof String.Error;` | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`Error`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#error) | [packages/common/src/Type.ts:221](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L221) |
| <a id="errors"></a> `Errors` | `readonly` | \| [`ArrayError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/ArrayError)\<[`InferError`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferError)\<`ElementType`\>\> \| [`ArrayError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/ArrayError)\<[`InferParentError`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferParentError)\<`ElementType`\>\> | ### Example `type StringParentErrors = typeof String.Errors;` | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`Errors`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#errors) | [packages/common/src/Type.ts:417](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L417) |
| <a id="from"></a> `from` | `readonly` | (`value`) => [`Result`](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result)\<readonly [`InferType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferType)\<`ElementType`\>[], \| [`ArrayError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/ArrayError)\<[`InferError`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferError)\<`ElementType`\>\> \| [`ArrayError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/ArrayError)\<[`InferParentError`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferParentError)\<`ElementType`\>\>\> | Creates `T` from an `Input` value. This is useful when we have a typed value. `from` is a typed alias of `fromUnknown`. | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`from`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#from) | [packages/common/src/Type.ts:236](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L236) |
| <a id="fromparent"></a> `fromParent` | `readonly` | (`value`) => [`Result`](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result)\<readonly [`InferType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferType)\<`ElementType`\>[], [`ArrayError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/ArrayError)\<[`InferError`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferError)\<`ElementType`\>\>\> | Creates `T` from `Parent` type. This function skips parent Types validations when we have already partially validated value. | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`fromParent`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#fromparent) | [packages/common/src/Type.ts:330](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L330) |
| <a id="fromunknown"></a> `fromUnknown` | `readonly` | (`value`) => [`Result`](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result)\<readonly [`InferType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferType)\<`ElementType`\>[], \| [`ArrayError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/ArrayError)\<[`InferError`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferError)\<`ElementType`\>\> \| [`ArrayError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/ArrayError)\<[`InferParentError`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferParentError)\<`ElementType`\>\>\> | Creates `T` from an unknown value. This is useful when a value is unknown. | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`fromUnknown`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#fromunknown) | [packages/common/src/Type.ts:322](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L322) |
| <a id="input"></a> `Input` | `public` | readonly [`InferInput`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferInput)\<`ElementType`\>[] | The type expected by `from` and `fromUnknown`. ### Example `type StringInput = typeof String.Input;` | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`Input`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#input) | [packages/common/src/Type.ts:219](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L219) |
| <a id="is"></a> `is` | `readonly` | [`Refinement`](https://evolu.dev/docs/api-reference/common/Types/type-aliases/Refinement)\<`unknown`, readonly [`InferType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferType)\<`ElementType`\>[]\> | A **type guard** that checks whether an unknown value satisfies the [Type](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type). ### Example `const value: unknown = "hello"; if (String.is(value)) { // TypeScript now knows `value`is a`string` here. console.log("This is a valid string!"); } const strings: unknown[] = [1, "hello", true, "world"]; const filteredStrings = strings.filter(String.is); console.log(filteredStrings); // ["hello", "world"]` | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`is`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#is) | [packages/common/src/Type.ts:351](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L351) |
| <a id="name"></a> `name` | `readonly` | `"Array"` | - | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`name`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#name-1) | [packages/common/src/Type.ts:227](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L227) |
| <a id="ornull"></a> `orNull` | `readonly` | (`value`) => \| readonly [`InferType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferType)\<`ElementType`\>[] \| `null` | Creates `T` from an `Input` value, returning `null` if validation fails. This is a convenience method that combines `from` with `getOrNull`. **When to use:** - When you need to convert a validation result to a nullable value - When the error is not important and you just want the value or nothing ### Example `// ✅ Good: Optional user input const age = PositiveInt.orNull(userInput); if (age != null) { console.log("Valid age:", age); } // ✅ Good: Default fallback const maxRetries = PositiveInt.orNull(config.retries) ?? 3; // ❌ Avoid: When you need to know why validation failed (use `from` instead) const result = PositiveInt.from(userInput); if (!result.ok) { console.error(formatPositiveError(result.error)); }` | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`orNull`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#ornull) | [packages/common/src/Type.ts:315](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L315) |
| <a id="orthrow"></a> `orThrow` | `readonly` | (`value`) => readonly [`InferType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferType)\<`ElementType`\>[] | Creates `T` from an `Input` value, throwing an error if validation fails. Throws an Error with the Type validation error in its `cause` property, making it debuggable while avoiding the need for custom error messages. This is a convenience method that combines `from` with `getOrThrow`. **When to use:** - Configuration values that are guaranteed to be valid (e.g., hardcoded constants) - Application startup where failure should crash the program - As an alternative to assertions when the Type error in the thrown Error's `cause` provides sufficient debugging information - Test code with known valid inputs (when error message clarity is not critical; for better test error messages, use Vitest `schemaMatching` + `assert` with `.is()`) ### Example `// ✅ Good: Known valid constant const maxRetries = PositiveInt.orThrow(3); // ✅ Good: App configuration that should crash on invalid values const appName = SimpleName.orThrow("MyApp"); // ✅ Good: Instead of assert when Type error is clear enough // Context makes it obvious: count increments from non-negative value const currentCount = counts.get(id) ?? 0; const newCount = PositiveInt.orThrow(currentCount + 1); // ✅ Good: Test setup with known valid values const testUser = User.orThrow({ name: "Alice", age: 30 }); // ❌ Avoid: User input (use `from` instead) const userAge = PositiveInt.orThrow(userInput); // Could crash! // ✅ Better: Handle user input gracefully const ageResult = PositiveInt.from(userInput); if (!ageResult.ok) { // Handle validation error }` | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`orThrow`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#orthrow) | [packages/common/src/Type.ts:284](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L284) |
| <a id="parent"></a> `Parent` | `public` | readonly [`InferParent`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferParent)\<`ElementType`\>[] | The parent type. ### Example `type StringParent = typeof String.Parent;` | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`Parent`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#parent) | [packages/common/src/Type.ts:223](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L223) |
| <a id="parenterror"></a> `ParentError` | `public` | [`ArrayError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/ArrayError)\<[`InferParentError`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferParentError)\<`ElementType`\>\> | The parent's error. ### Example `type StringParentError = typeof String.ParentError;` | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`ParentError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#parenterror) | [packages/common/src/Type.ts:225](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L225) |
| <a id="type"></a> `Type` | `readonly` | readonly [`InferType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferType)\<`ElementType`\>[] | The type this Type resolves to. ### Example `type String = typeof String.Type;` | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#type) | [packages/common/src/Type.ts:364](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L364) |
Base64UrlError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / Base64UrlError
# Interface: Base64UrlError
Defined in: [packages/common/src/Type.ts:1467](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1467)
## Extends
- [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError)\<`"Base64Url"`\>
## Properties
| Property | Modifier | Type | Description | Inherited from | Defined in |
| -------------------------- | ---------- | ------------- | -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="type"></a> `type` | `readonly` | `"Base64Url"` | - | [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError).[`type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError.mdx#type) | [packages/common/src/Type.ts:428](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L428) |
| <a id="value"></a> `value` | `readonly` | `unknown` | The value that was received and caused the error. Provides additional context for debugging and validation feedback. | [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError).[`value`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError.mdx#value) | [packages/common/src/Type.ts:434](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L434) |
BetweenError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / BetweenError
# Interface: BetweenError\<Min, Max\>
Defined in: [packages/common/src/Type.ts:2218](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L2218)
## Extends
- [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError)\<`"Between"`\>
## Type Parameters
| Type Parameter | Default type |
| ------------------------ | ------------ |
| `Min` _extends_ `number` | `number` |
| `Max` _extends_ `number` | `number` |
## Properties
| Property | Modifier | Type | Description | Inherited from | Defined in |
| -------------------------- | ---------- | ----------- | -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="max-1"></a> `max` | `readonly` | `Max` | - | - | [packages/common/src/Type.ts:2223](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L2223) |
| <a id="min-1"></a> `min` | `readonly` | `Min` | - | - | [packages/common/src/Type.ts:2222](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L2222) |
| <a id="type"></a> `type` | `readonly` | `"Between"` | - | [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError).[`type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError.mdx#type) | [packages/common/src/Type.ts:428](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L428) |
| <a id="value"></a> `value` | `readonly` | `unknown` | The value that was received and caused the error. Provides additional context for debugging and validation feedback. | [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError).[`value`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError.mdx#value) | [packages/common/src/Type.ts:434](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L434) |
BigIntError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / BigIntError
# Interface: BigIntError
Defined in: [packages/common/src/Type.ts:699](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L699)
## Extends
- [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError)\<`"BigInt"`\>
## Properties
| Property | Modifier | Type | Description | Inherited from | Defined in |
| -------------------------- | ---------- | ---------- | -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="type"></a> `type` | `readonly` | `"BigInt"` | - | [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError).[`type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError.mdx#type) | [packages/common/src/Type.ts:428](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L428) |
| <a id="value"></a> `value` | `readonly` | `unknown` | The value that was received and caused the error. Provides additional context for debugging and validation feedback. | [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError).[`value`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError.mdx#value) | [packages/common/src/Type.ts:434](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L434) |
BooleanError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / BooleanError
# Interface: BooleanError
Defined in: [packages/common/src/Type.ts:710](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L710)
## Extends
- [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError)\<`"Boolean"`\>
## Properties
| Property | Modifier | Type | Description | Inherited from | Defined in |
| -------------------------- | ---------- | ----------- | -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="type"></a> `type` | `readonly` | `"Boolean"` | - | [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError).[`type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError.mdx#type) | [packages/common/src/Type.ts:428](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L428) |
| <a id="value"></a> `value` | `readonly` | `unknown` | The value that was received and caused the error. Provides additional context for debugging and validation feedback. | [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError).[`value`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError.mdx#value) | [packages/common/src/Type.ts:434](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L434) |
BrandType - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / BrandType
# Interface: BrandType\<ParentType, Name, Error, ParentError\>
Defined in: [packages/common/src/Type.ts:1029](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1029)
Evolu [Type](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type) is like a type guard that returns typed errors (via
[Result](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result)) instead of throwing. We either get a safely typed value or a
composable typed error telling us exactly why validation failed.
Why another validation library?
- **Result-based error handling** – no exceptions for normal control flow.
- **Typed errors with decoupled formatters** – validation logic ≠ user
messages.
- **Consistent constraints via [Brand](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)** – every constraint becomes part
of the type.
- **Skippable validation** – parent validations can be skipped when already
proved by types.
- **Simple, top-down implementation** – readable source code from top to
bottom.
- **No user-land chaining DSL** – prepared for TC39 Hack pipes.
A distinctive feature of Evolu Type compared to other validation libraries is
that it returns typed errors rather than string messages. This allows
TypeScript to enforce that all validation errors are handled by type
checking, significantly improving the developer experience.
Evolu Type supports [Standard Schema](https://standardschema.dev/) for
interoperability with 40+ validation-compatible tools and frameworks.
### Base Types Quick Start
```ts
// Validate unknown values
const value: unknown = "hello";
const stringResult = String.fromUnknown(value);
if (!stringResult.ok) {
// console.error(formatStringError(stringResult.error));
return stringResult; // inside a function returning Result<string, _>
}
// Safe branch: value is now string
const upper = stringResult.value.toUpperCase();
// Type guard style
if (String.is(value)) {
// narrowed to string
}
// Composing: arrays & objects
const Numbers = array(Number); // ReadonlyArray<number>
const Point = object({ x: Number, y: Number });
Numbers.from([1, 2, 3]); // ok
Point.from({ x: 1, y: 2 }); // ok
Point.from({ x: 1, y: "2" }); // err -> nested Number error
```
### Branding Basics
Branding adds semantic meaning & constraints while preserving the runtime
shape:
```ts
const CurrencyCode = brand("CurrencyCode", String, (value) =>
/^[A-Z]{3}$/.test(value)
? ok(value)
: err<CurrencyCodeError>({ type: "CurrencyCode", value }),
);
type CurrencyCode = typeof CurrencyCode.Type; // string & Brand<"CurrencyCode">
interface CurrencyCodeError extends TypeError<"CurrencyCode"> {}
const formatCurrencyCodeError = createTypeErrorFormatter<CurrencyCodeError>(
(error) => `Invalid currency code: ${error.value}`,
);
const r = CurrencyCode.from("USD"); // ok("USD")
const e = CurrencyCode.from("usd"); // err(...)
```
See also reusable brand factories like `minLength`, `maxLength`, `trimmed`,
`positive`, `between`, etc.
### Objects & Optional Fields
```ts
const User = object({
name: NonEmptyTrimmedString100,
age: optional(PositiveInt),
});
type User = typeof User.Type;
User.from({ name: "Alice" }); // ok
User.from({ name: "Alice", age: -1 }); // err(PositiveInt)
```
### Deriving JSON String Types
```ts
const Person = object({
name: NonEmptyString50,
// Did you know that JSON.stringify converts NaN (a number) into null?
// To prevent this, use FiniteNumber.
age: FiniteNumber,
});
type Person = typeof Person.Type;
const [PersonJson, personToPersonJson, personJsonToPerson] = json(
Person,
"PersonJson",
);
// string & Brand<"PersonJson">
type PersonJson = typeof PersonJson.Type;
const person = Person.orThrow({
name: "Alice",
age: 30,
});
const personJson = personToPersonJson(person);
expect(personJsonToPerson(personJson)).toEqual(person);
```
### Error Formatting
Evolu separates validation logic from human-readable messages. There are two
layers:
1. Per-type formatters (e.g. `formatStringError`) – simple, focused, already
used earlier in the quick start example.
2. A unified formatter via `createFormatTypeError` – composes all built-in and
custom errors (including nested composite types) and lets us override
selected messages.
#### 1. Per-Type Formatter (recap)
```ts
const r = String.fromUnknown(42);
if (!r.ok) console.error(formatStringError(r.error));
```
#### 2. Unified Formatter with Overrides
```ts
// Override only what we care about; fall back to built-ins for the rest.
const formatTypeError = createFormatTypeError((error) => {
if (error.type === "MinLength") return `Min length is ${error.min}`;
});
const User = object({ name: NonEmptyTrimmedString100 });
const resultUser = User.from({ name: "" });
if (!resultUser.ok) console.error(formatTypeError(resultUser.error));
const badPoint = object({ x: Number, y: Number }).from({
x: 1,
y: "foo",
});
if (!badPoint.ok) console.error(formatTypeError(badPoint.error));
```
The unified formatter walks nested structures (object / array / record /
tuple / union) and applies overrides only where specified, greatly reducing
boilerplate when formatting complex validation errors.
### Tip
If necessary, write `globalThis.String` instead of `String` to avoid naming
clashes with native types.
### Design Decision: No Bidirectional Transformations
Evolu Type intentionally does not support bidirectional transformations. It
previously did, but supporting that while keeping typed error fidelity added
complexity that hurt readability & reliability. Most persistence pipelines
(e.g. SQLite) already require explicit mapping of query results, so implicit
reverse transforms would not buy much. We may revisit this if we can design a
minimal, 100% safe API that preserves simplicity.
### Prepared for TC39 Hack Pipes
Take a look how `SimplePassword` is defined:
```ts
export const SimplePassword = brand(
"SimplePassword",
minLength(8)(maxLength(64)(TrimmedString)),
);
```
Nested functions are often OK (if not, make a helper) and read well, but with
TC39 Hack pipes it would be clearer:
```ts
// TrimmedString
// |> minLength(8)(%)
// |> maxLength(64)(%)
// |> brand("SimplePassword", %)
```
Note `minLength` and `maxLength` are curried because they are factories.
## Extends
- [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type)\<`"Brand"`, [`InferType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferType)\<`ParentType`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`Name`\>, [`InferInput`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferInput)\<`ParentType`\>, `Error`, [`InferType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferType)\<`ParentType`\>, `ParentError`\>
## Type Parameters
| Type Parameter | Default type |
| ----------------------------------------------------------------------------------------------- | ------------ |
| `ParentType` _extends_ [`AnyType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/AnyType) | - |
| `Name` _extends_ [`TypeName`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/TypeName) | - |
| `Error` _extends_ [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError) | `never` |
| `ParentError` _extends_ [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError) | `never` |
## Properties
| Property | Modifier | Type | Description | Inherited from | Defined in |
| ------------------------------------------------ | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="evolutypesymbol"></a> `[EvoluTypeSymbol]` | `readonly` | `true` | - | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`[EvoluTypeSymbol]`](/docs/api-reference/common/Type/interfaces/Type.mdx#evolutypesymbol) | [packages/common/src/Type.ts:353](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L353) |
| <a id="standard"></a> `~standard` | `readonly` | [`Props`](https://evolu.dev/docs/api-reference/common/Type/namespaces/StandardSchemaV1/interfaces/Props)\<[`InferInput`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferInput)\<`ParentType`\>, [`InferType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferType)\<`ParentType`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`Name`\>\> | The Standard Schema properties. | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`~standard`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#standard) | [packages/common/src/Type.ts:4450](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L4450) |
| <a id="brand"></a> `brand` | `readonly` | `Name` | - | - | [packages/common/src/Type.ts:1042](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1042) |
| <a id="error-1"></a> `Error` | `public` | `Error` | The specific error introduced by this Type. ### Example `type StringError = typeof String.Error;` | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`Error`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#error) | [packages/common/src/Type.ts:221](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L221) |
| <a id="errors"></a> `Errors` | `readonly` | `Error` \| `ParentError` | ### Example `type StringParentErrors = typeof String.Errors;` | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`Errors`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#errors) | [packages/common/src/Type.ts:417](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L417) |
| <a id="from"></a> `from` | `readonly` | (`value`) => [`Result`](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result)\<[`InferType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferType)\<`ParentType`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`Name`\>, `Error` \| `ParentError`\> | Creates `T` from an `Input` value. This is useful when we have a typed value. `from` is a typed alias of `fromUnknown`. | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`from`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#from) | [packages/common/src/Type.ts:236](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L236) |
| <a id="fromparent"></a> `fromParent` | `readonly` | (`value`) => [`Result`](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result)\<[`InferType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferType)\<`ParentType`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`Name`\>, `Error`\> | Creates `T` from `Parent` type. This function skips parent Types validations when we have already partially validated value. | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`fromParent`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#fromparent) | [packages/common/src/Type.ts:330](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L330) |
| <a id="fromunknown"></a> `fromUnknown` | `readonly` | (`value`) => [`Result`](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result)\<[`InferType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferType)\<`ParentType`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`Name`\>, `Error` \| `ParentError`\> | Creates `T` from an unknown value. This is useful when a value is unknown. | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`fromUnknown`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#fromunknown) | [packages/common/src/Type.ts:322](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L322) |
| <a id="input"></a> `Input` | `public` | [`InferInput`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferInput)\<`ParentType`\> | The type expected by `from` and `fromUnknown`. ### Example `type StringInput = typeof String.Input;` | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`Input`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#input) | [packages/common/src/Type.ts:219](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L219) |
| <a id="is"></a> `is` | `readonly` | [`Refinement`](https://evolu.dev/docs/api-reference/common/Types/type-aliases/Refinement)\<`unknown`, [`InferType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferType)\<`ParentType`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`Name`\>\> | A **type guard** that checks whether an unknown value satisfies the [Type](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type). ### Example `const value: unknown = "hello"; if (String.is(value)) { // TypeScript now knows `value`is a`string` here. console.log("This is a valid string!"); } const strings: unknown[] = [1, "hello", true, "world"]; const filteredStrings = strings.filter(String.is); console.log(filteredStrings); // ["hello", "world"]` | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`is`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#is) | [packages/common/src/Type.ts:351](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L351) |
| <a id="name-1"></a> `name` | `readonly` | `"Brand"` | - | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`name`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#name-1) | [packages/common/src/Type.ts:227](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L227) |
| <a id="ornull"></a> `orNull` | `readonly` | (`value`) => \| [`InferType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferType)\<`ParentType`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`Name`\> \| `null` | Creates `T` from an `Input` value, returning `null` if validation fails. This is a convenience method that combines `from` with `getOrNull`. **When to use:** - When you need to convert a validation result to a nullable value - When the error is not important and you just want the value or nothing ### Example `// ✅ Good: Optional user input const age = PositiveInt.orNull(userInput); if (age != null) { console.log("Valid age:", age); } // ✅ Good: Default fallback const maxRetries = PositiveInt.orNull(config.retries) ?? 3; // ❌ Avoid: When you need to know why validation failed (use `from` instead) const result = PositiveInt.from(userInput); if (!result.ok) { console.error(formatPositiveError(result.error)); }` | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`orNull`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#ornull) | [packages/common/src/Type.ts:315](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L315) |
| <a id="orthrow"></a> `orThrow` | `readonly` | (`value`) => [`InferType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferType)\<`ParentType`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`Name`\> | Creates `T` from an `Input` value, throwing an error if validation fails. Throws an Error with the Type validation error in its `cause` property, making it debuggable while avoiding the need for custom error messages. This is a convenience method that combines `from` with `getOrThrow`. **When to use:** - Configuration values that are guaranteed to be valid (e.g., hardcoded constants) - Application startup where failure should crash the program - As an alternative to assertions when the Type error in the thrown Error's `cause` provides sufficient debugging information - Test code with known valid inputs (when error message clarity is not critical; for better test error messages, use Vitest `schemaMatching` + `assert` with `.is()`) ### Example `// ✅ Good: Known valid constant const maxRetries = PositiveInt.orThrow(3); // ✅ Good: App configuration that should crash on invalid values const appName = SimpleName.orThrow("MyApp"); // ✅ Good: Instead of assert when Type error is clear enough // Context makes it obvious: count increments from non-negative value const currentCount = counts.get(id) ?? 0; const newCount = PositiveInt.orThrow(currentCount + 1); // ✅ Good: Test setup with known valid values const testUser = User.orThrow({ name: "Alice", age: 30 }); // ❌ Avoid: User input (use `from` instead) const userAge = PositiveInt.orThrow(userInput); // Could crash! // ✅ Better: Handle user input gracefully const ageResult = PositiveInt.from(userInput); if (!ageResult.ok) { // Handle validation error }` | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`orThrow`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#orthrow) | [packages/common/src/Type.ts:284](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L284) |
| <a id="parent"></a> `Parent` | `public` | [`InferType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferType)\<`ParentType`\> | The parent type. ### Example `type StringParent = typeof String.Parent;` | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`Parent`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#parent) | [packages/common/src/Type.ts:223](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L223) |
| <a id="parenterror-1"></a> `ParentError` | `public` | `ParentError` | The parent's error. ### Example `type StringParentError = typeof String.ParentError;` | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`ParentError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#parenterror) | [packages/common/src/Type.ts:225](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L225) |
| <a id="parenttype-1"></a> `parentType` | `readonly` | `ParentType` | - | - | [packages/common/src/Type.ts:1043](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1043) |
| <a id="type"></a> `Type` | `readonly` | [`InferType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferType)\<`ParentType`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`Name`\> | The type this Type resolves to. ### Example `type String = typeof String.Type;` | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#type) | [packages/common/src/Type.ts:364](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L364) |
BrandWithoutRefineError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / BrandWithoutRefineError
# Interface: BrandWithoutRefineError\<Name, ParentError\>
Defined in: [packages/common/src/Type.ts:1046](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1046)
## Extends
- [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError)\<`Name`\>
## Type Parameters
| Type Parameter |
| ----------------------------------------------------------------------------------------------- |
| `Name` _extends_ [`TypeName`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/TypeName) |
| `ParentError` _extends_ [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError) |
## Properties
| Property | Modifier | Type | Description | Inherited from | Defined in |
| ---------------------------------------- | ---------- | ------------- | -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="parenterror-1"></a> `parentError` | `readonly` | `ParentError` | - | - | [packages/common/src/Type.ts:1050](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1050) |
| <a id="type"></a> `type` | `readonly` | `Name` | - | [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError).[`type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError.mdx#type) | [packages/common/src/Type.ts:428](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L428) |
| <a id="value"></a> `value` | `readonly` | `unknown` | The value that was received and caused the error. Provides additional context for debugging and validation feedback. | [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError).[`value`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError.mdx#value) | [packages/common/src/Type.ts:434](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L434) |
CurrencyCodeError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / CurrencyCodeError
# Interface: CurrencyCodeError
Defined in: [packages/common/src/Type.ts:1066](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1066)
## Extends
- [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError)\<`"CurrencyCode"`\>
## Properties
| Property | Modifier | Type | Description | Inherited from | Defined in |
| -------------------------- | ---------- | ---------------- | -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="type"></a> `type` | `readonly` | `"CurrencyCode"` | - | [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError).[`type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError.mdx#type) | [packages/common/src/Type.ts:428](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L428) |
| <a id="value"></a> `value` | `readonly` | `unknown` | The value that was received and caused the error. Provides additional context for debugging and validation feedback. | [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError).[`value`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError.mdx#value) | [packages/common/src/Type.ts:434](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L434) |
DateIsoError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / DateIsoError
# Interface: DateIsoError
Defined in: [packages/common/src/Type.ts:1112](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1112)
## Extends
- [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError)\<`"DateIso"`\>
## Properties
| Property | Modifier | Type | Description | Inherited from | Defined in |
| -------------------------- | ---------- | ----------- | -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="type"></a> `type` | `readonly` | `"DateIso"` | - | [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError).[`type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError.mdx#type) | [packages/common/src/Type.ts:428](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L428) |
| <a id="value"></a> `value` | `readonly` | `unknown` | The value that was received and caused the error. Provides additional context for debugging and validation feedback. | [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError).[`value`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError.mdx#value) | [packages/common/src/Type.ts:434](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L434) |
EvoluTypeError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / EvoluTypeError
# Interface: EvoluTypeError
Defined in: [packages/common/src/Type.ts:837](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L837)
## Extends
- [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError)\<`"EvoluType"`\>
## Properties
| Property | Modifier | Type | Description | Inherited from | Defined in |
| -------------------------- | ---------- | ------------- | -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="type"></a> `type` | `readonly` | `"EvoluType"` | - | [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError).[`type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError.mdx#type) | [packages/common/src/Type.ts:428](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L428) |
| <a id="value"></a> `value` | `readonly` | `unknown` | The value that was received and caused the error. Provides additional context for debugging and validation feedback. | [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError).[`value`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError.mdx#value) | [packages/common/src/Type.ts:434](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L434) |
FiniteError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / FiniteError
# Interface: FiniteError
Defined in: [packages/common/src/Type.ts:2147](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L2147)
## Extends
- [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError)\<`"Finite"`\>
## Properties
| Property | Modifier | Type | Description | Inherited from | Defined in |
| -------------------------- | ---------- | ---------- | -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="type"></a> `type` | `readonly` | `"Finite"` | - | [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError).[`type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError.mdx#type) | [packages/common/src/Type.ts:428](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L428) |
| <a id="value"></a> `value` | `readonly` | `unknown` | The value that was received and caused the error. Provides additional context for debugging and validation feedback. | [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError).[`value`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError.mdx#value) | [packages/common/src/Type.ts:434](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L434) |
FunctionError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / FunctionError
# Interface: FunctionError
Defined in: [packages/common/src/Type.ts:742](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L742)
## Extends
- [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError)\<`"Function"`\>
## Properties
| Property | Modifier | Type | Description | Inherited from | Defined in |
| -------------------------- | ---------- | ------------ | -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="type"></a> `type` | `readonly` | `"Function"` | - | [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError).[`type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError.mdx#type) | [packages/common/src/Type.ts:428](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L428) |
| <a id="value"></a> `value` | `readonly` | `unknown` | The value that was received and caused the error. Provides additional context for debugging and validation feedback. | [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError).[`value`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError.mdx#value) | [packages/common/src/Type.ts:434](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L434) |
GreaterThanError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / GreaterThanError
# Interface: GreaterThanError\<Min\>
Defined in: [packages/common/src/Type.ts:2023](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L2023)
## Extends
- [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError)\<`"GreaterThan"`\>
## Type Parameters
| Type Parameter | Default type |
| ------------------------ | ------------ |
| `Min` _extends_ `number` | `number` |
## Properties
| Property | Modifier | Type | Description | Inherited from | Defined in |
| -------------------------- | ---------- | --------------- | -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="min-1"></a> `min` | `readonly` | `Min` | - | - | [packages/common/src/Type.ts:2026](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L2026) |
| <a id="type"></a> `type` | `readonly` | `"GreaterThan"` | - | [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError).[`type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError.mdx#type) | [packages/common/src/Type.ts:428](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L428) |
| <a id="value"></a> `value` | `readonly` | `unknown` | The value that was received and caused the error. Provides additional context for debugging and validation feedback. | [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError).[`value`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError.mdx#value) | [packages/common/src/Type.ts:434](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L434) |
GreaterThanOrEqualToError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / GreaterThanOrEqualToError
# Interface: GreaterThanOrEqualToError\<Min\>
Defined in: [packages/common/src/Type.ts:2075](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L2075)
## Extends
- [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError)\<`"GreaterThanOrEqualTo"`\>
## Type Parameters
| Type Parameter | Default type |
| ------------------------ | ------------ |
| `Min` _extends_ `number` | `number` |
## Properties
| Property | Modifier | Type | Description | Inherited from | Defined in |
| -------------------------- | ---------- | ------------------------ | -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="min-1"></a> `min` | `readonly` | `Min` | - | - | [packages/common/src/Type.ts:2078](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L2078) |
| <a id="type"></a> `type` | `readonly` | `"GreaterThanOrEqualTo"` | - | [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError).[`type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError.mdx#type) | [packages/common/src/Type.ts:428](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L428) |
| <a id="value"></a> `value` | `readonly` | `unknown` | The value that was received and caused the error. Provides additional context for debugging and validation feedback. | [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError).[`value`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError.mdx#value) | [packages/common/src/Type.ts:434](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L434) |
IdError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / IdError
# Interface: IdError
Defined in: [packages/common/src/Type.ts:1624](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1624)
## Extends
- [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError)\<`"Id"`\>
## Properties
| Property | Modifier | Type | Description | Inherited from | Defined in |
| -------------------------- | ---------- | --------- | -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="type"></a> `type` | `readonly` | `"Id"` | - | [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError).[`type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError.mdx#type) | [packages/common/src/Type.ts:428](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L428) |
| <a id="value"></a> `value` | `readonly` | `unknown` | The value that was received and caused the error. Provides additional context for debugging and validation feedback. | [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError).[`value`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError.mdx#value) | [packages/common/src/Type.ts:434](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L434) |
InstanceOfError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / InstanceOfError
# Interface: InstanceOfError
Defined in: [packages/common/src/Type.ts:790](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L790)
## Extends
- [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError)\<`"InstanceOf"`\>
## Properties
| Property | Modifier | Type | Description | Inherited from | Defined in |
| -------------------------- | ---------- | -------------- | -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="ctor"></a> `ctor` | `readonly` | `string` | - | - | [packages/common/src/Type.ts:791](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L791) |
| <a id="type"></a> `type` | `readonly` | `"InstanceOf"` | - | [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError).[`type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError.mdx#type) | [packages/common/src/Type.ts:428](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L428) |
| <a id="value"></a> `value` | `readonly` | `unknown` | The value that was received and caused the error. Provides additional context for debugging and validation feedback. | [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError).[`value`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError.mdx#value) | [packages/common/src/Type.ts:434](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L434) |
InstanceOfType - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / InstanceOfType
# Interface: InstanceOfType\<T\>
Defined in: [packages/common/src/Type.ts:794](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L794)
Evolu [Type](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type) is like a type guard that returns typed errors (via
[Result](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result)) instead of throwing. We either get a safely typed value or a
composable typed error telling us exactly why validation failed.
Why another validation library?
- **Result-based error handling** – no exceptions for normal control flow.
- **Typed errors with decoupled formatters** – validation logic ≠ user
messages.
- **Consistent constraints via [Brand](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)** – every constraint becomes part
of the type.
- **Skippable validation** – parent validations can be skipped when already
proved by types.
- **Simple, top-down implementation** – readable source code from top to
bottom.
- **No user-land chaining DSL** – prepared for TC39 Hack pipes.
A distinctive feature of Evolu Type compared to other validation libraries is
that it returns typed errors rather than string messages. This allows
TypeScript to enforce that all validation errors are handled by type
checking, significantly improving the developer experience.
Evolu Type supports [Standard Schema](https://standardschema.dev/) for
interoperability with 40+ validation-compatible tools and frameworks.
### Base Types Quick Start
```ts
// Validate unknown values
const value: unknown = "hello";
const stringResult = String.fromUnknown(value);
if (!stringResult.ok) {
// console.error(formatStringError(stringResult.error));
return stringResult; // inside a function returning Result<string, _>
}
// Safe branch: value is now string
const upper = stringResult.value.toUpperCase();
// Type guard style
if (String.is(value)) {
// narrowed to string
}
// Composing: arrays & objects
const Numbers = array(Number); // ReadonlyArray<number>
const Point = object({ x: Number, y: Number });
Numbers.from([1, 2, 3]); // ok
Point.from({ x: 1, y: 2 }); // ok
Point.from({ x: 1, y: "2" }); // err -> nested Number error
```
### Branding Basics
Branding adds semantic meaning & constraints while preserving the runtime
shape:
```ts
const CurrencyCode = brand("CurrencyCode", String, (value) =>
/^[A-Z]{3}$/.test(value)
? ok(value)
: err<CurrencyCodeError>({ type: "CurrencyCode", value }),
);
type CurrencyCode = typeof CurrencyCode.Type; // string & Brand<"CurrencyCode">
interface CurrencyCodeError extends TypeError<"CurrencyCode"> {}
const formatCurrencyCodeError = createTypeErrorFormatter<CurrencyCodeError>(
(error) => `Invalid currency code: ${error.value}`,
);
const r = CurrencyCode.from("USD"); // ok("USD")
const e = CurrencyCode.from("usd"); // err(...)
```
See also reusable brand factories like `minLength`, `maxLength`, `trimmed`,
`positive`, `between`, etc.
### Objects & Optional Fields
```ts
const User = object({
name: NonEmptyTrimmedString100,
age: optional(PositiveInt),
});
type User = typeof User.Type;
User.from({ name: "Alice" }); // ok
User.from({ name: "Alice", age: -1 }); // err(PositiveInt)
```
### Deriving JSON String Types
```ts
const Person = object({
name: NonEmptyString50,
// Did you know that JSON.stringify converts NaN (a number) into null?
// To prevent this, use FiniteNumber.
age: FiniteNumber,
});
type Person = typeof Person.Type;
const [PersonJson, personToPersonJson, personJsonToPerson] = json(
Person,
"PersonJson",
);
// string & Brand<"PersonJson">
type PersonJson = typeof PersonJson.Type;
const person = Person.orThrow({
name: "Alice",
age: 30,
});
const personJson = personToPersonJson(person);
expect(personJsonToPerson(personJson)).toEqual(person);
```
### Error Formatting
Evolu separates validation logic from human-readable messages. There are two
layers:
1. Per-type formatters (e.g. `formatStringError`) – simple, focused, already
used earlier in the quick start example.
2. A unified formatter via `createFormatTypeError` – composes all built-in and
custom errors (including nested composite types) and lets us override
selected messages.
#### 1. Per-Type Formatter (recap)
```ts
const r = String.fromUnknown(42);
if (!r.ok) console.error(formatStringError(r.error));
```
#### 2. Unified Formatter with Overrides
```ts
// Override only what we care about; fall back to built-ins for the rest.
const formatTypeError = createFormatTypeError((error) => {
if (error.type === "MinLength") return `Min length is ${error.min}`;
});
const User = object({ name: NonEmptyTrimmedString100 });
const resultUser = User.from({ name: "" });
if (!resultUser.ok) console.error(formatTypeError(resultUser.error));
const badPoint = object({ x: Number, y: Number }).from({
x: 1,
y: "foo",
});
if (!badPoint.ok) console.error(formatTypeError(badPoint.error));
```
The unified formatter walks nested structures (object / array / record /
tuple / union) and applies overrides only where specified, greatly reducing
boilerplate when formatting complex validation errors.
### Tip
If necessary, write `globalThis.String` instead of `String` to avoid naming
clashes with native types.
### Design Decision: No Bidirectional Transformations
Evolu Type intentionally does not support bidirectional transformations. It
previously did, but supporting that while keeping typed error fidelity added
complexity that hurt readability & reliability. Most persistence pipelines
(e.g. SQLite) already require explicit mapping of query results, so implicit
reverse transforms would not buy much. We may revisit this if we can design a
minimal, 100% safe API that preserves simplicity.
### Prepared for TC39 Hack Pipes
Take a look how `SimplePassword` is defined:
```ts
export const SimplePassword = brand(
"SimplePassword",
minLength(8)(maxLength(64)(TrimmedString)),
);
```
Nested functions are often OK (if not, make a helper) and read well, but with
TC39 Hack pipes it would be clearer:
```ts
// TrimmedString
// |> minLength(8)(%)
// |> maxLength(64)(%)
// |> brand("SimplePassword", %)
```
Note `minLength` and `maxLength` are curried because they are factories.
## Extends
- [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type)\<`"InstanceOf"`, `InstanceType`\<`T`\>, `InstanceType`\<`T`\>, [`InstanceOfError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/InstanceOfError)\>
## Type Parameters
| Type Parameter |
| ---------------------------------- |
| `T` _extends_ (...`args`) => `any` |
## Properties
| Property | Modifier | Type | Description | Inherited from | Defined in |
| ------------------------------------------------ | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="evolutypesymbol"></a> `[EvoluTypeSymbol]` | `readonly` | `true` | - | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`[EvoluTypeSymbol]`](/docs/api-reference/common/Type/interfaces/Type.mdx#evolutypesymbol) | [packages/common/src/Type.ts:353](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L353) |
| <a id="standard"></a> `~standard` | `readonly` | [`Props`](https://evolu.dev/docs/api-reference/common/Type/namespaces/StandardSchemaV1/interfaces/Props)\<`InstanceType`\<`T`\>, `InstanceType`\<`T`\>\> | The Standard Schema properties. | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`~standard`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#standard) | [packages/common/src/Type.ts:4450](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L4450) |
| <a id="ctor"></a> `ctor` | `public` | `T` | - | - | [packages/common/src/Type.ts:802](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L802) |
| <a id="error"></a> `Error` | `public` | [`InstanceOfError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/InstanceOfError) | The specific error introduced by this Type. ### Example `type StringError = typeof String.Error;` | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`Error`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#error) | [packages/common/src/Type.ts:221](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L221) |
| <a id="errors"></a> `Errors` | `readonly` | [`InstanceOfError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/InstanceOfError) | ### Example `type StringParentErrors = typeof String.Errors;` | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`Errors`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#errors) | [packages/common/src/Type.ts:417](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L417) |
| <a id="from"></a> `from` | `readonly` | (`value`) => [`Result`](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result)\<`InstanceType`\<`T`\>, [`InstanceOfError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/InstanceOfError)\> | Creates `T` from an `Input` value. This is useful when we have a typed value. `from` is a typed alias of `fromUnknown`. | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`from`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#from) | [packages/common/src/Type.ts:236](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L236) |
| <a id="fromparent"></a> `fromParent` | `readonly` | (`value`) => [`Result`](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result)\<`InstanceType`\<`T`\>, [`InstanceOfError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/InstanceOfError)\> | Creates `T` from `Parent` type. This function skips parent Types validations when we have already partially validated value. | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`fromParent`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#fromparent) | [packages/common/src/Type.ts:330](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L330) |
| <a id="fromunknown"></a> `fromUnknown` | `readonly` | (`value`) => [`Result`](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result)\<`InstanceType`\<`T`\>, [`InstanceOfError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/InstanceOfError)\> | Creates `T` from an unknown value. This is useful when a value is unknown. | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`fromUnknown`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#fromunknown) | [packages/common/src/Type.ts:322](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L322) |
| <a id="input"></a> `Input` | `public` | `InstanceType`\<`T`\> | The type expected by `from` and `fromUnknown`. ### Example `type StringInput = typeof String.Input;` | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`Input`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#input) | [packages/common/src/Type.ts:219](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L219) |
| <a id="is"></a> `is` | `readonly` | [`Refinement`](https://evolu.dev/docs/api-reference/common/Types/type-aliases/Refinement)\<`unknown`, `InstanceType`\<`T`\>\> | A **type guard** that checks whether an unknown value satisfies the [Type](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type). ### Example `const value: unknown = "hello"; if (String.is(value)) { // TypeScript now knows `value`is a`string` here. console.log("This is a valid string!"); } const strings: unknown[] = [1, "hello", true, "world"]; const filteredStrings = strings.filter(String.is); console.log(filteredStrings); // ["hello", "world"]` | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`is`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#is) | [packages/common/src/Type.ts:351](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L351) |
| <a id="name"></a> `name` | `readonly` | `"InstanceOf"` | - | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`name`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#name-1) | [packages/common/src/Type.ts:227](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L227) |
| <a id="ornull"></a> `orNull` | `readonly` | (`value`) => `InstanceType`\<`T`\> \| `null` | Creates `T` from an `Input` value, returning `null` if validation fails. This is a convenience method that combines `from` with `getOrNull`. **When to use:** - When you need to convert a validation result to a nullable value - When the error is not important and you just want the value or nothing ### Example `// ✅ Good: Optional user input const age = PositiveInt.orNull(userInput); if (age != null) { console.log("Valid age:", age); } // ✅ Good: Default fallback const maxRetries = PositiveInt.orNull(config.retries) ?? 3; // ❌ Avoid: When you need to know why validation failed (use `from` instead) const result = PositiveInt.from(userInput); if (!result.ok) { console.error(formatPositiveError(result.error)); }` | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`orNull`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#ornull) | [packages/common/src/Type.ts:315](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L315) |
| <a id="orthrow"></a> `orThrow` | `readonly` | (`value`) => `InstanceType` | Creates `T` from an `Input` value, throwing an error if validation fails. Throws an Error with the Type validation error in its `cause` property, making it debuggable while avoiding the need for custom error messages. This is a convenience method that combines `from` with `getOrThrow`. **When to use:** - Configuration values that are guaranteed to be valid (e.g., hardcoded constants) - Application startup where failure should crash the program - As an alternative to assertions when the Type error in the thrown Error's `cause` provides sufficient debugging information - Test code with known valid inputs (when error message clarity is not critical; for better test error messages, use Vitest `schemaMatching` + `assert` with `.is()`) ### Example `// ✅ Good: Known valid constant const maxRetries = PositiveInt.orThrow(3); // ✅ Good: App configuration that should crash on invalid values const appName = SimpleName.orThrow("MyApp"); // ✅ Good: Instead of assert when Type error is clear enough // Context makes it obvious: count increments from non-negative value const currentCount = counts.get(id) ?? 0; const newCount = PositiveInt.orThrow(currentCount + 1); // ✅ Good: Test setup with known valid values const testUser = User.orThrow({ name: "Alice", age: 30 }); // ❌ Avoid: User input (use `from` instead) const userAge = PositiveInt.orThrow(userInput); // Could crash! // ✅ Better: Handle user input gracefully const ageResult = PositiveInt.from(userInput); if (!ageResult.ok) { // Handle validation error }` | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`orThrow`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#orthrow) | [packages/common/src/Type.ts:284](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L284) |
| <a id="parent"></a> `Parent` | `public` | `InstanceType`\<`T`\> | The parent type. ### Example `type StringParent = typeof String.Parent;` | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`Parent`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#parent) | [packages/common/src/Type.ts:223](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L223) |
| <a id="parenterror"></a> `ParentError` | `public` | [`InstanceOfError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/InstanceOfError) | The parent's error. ### Example `type StringParentError = typeof String.ParentError;` | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`ParentError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#parenterror) | [packages/common/src/Type.ts:225](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L225) |
| <a id="type"></a> `Type` | `readonly` | `InstanceType` | The type this Type resolves to. ### Example `type String = typeof String.Type;` | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#type) | [packages/common/src/Type.ts:364](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L364) |
Int64Error - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / Int64Error
# Interface: Int64Error
Defined in: [packages/common/src/Type.ts:3620](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L3620)
## Extends
- [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError)\<`"Int64"`\>
## Properties
| Property | Modifier | Type | Description | Inherited from | Defined in |
| -------------------------- | ---------- | --------- | -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="type"></a> `type` | `readonly` | `"Int64"` | - | [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError).[`type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError.mdx#type) | [packages/common/src/Type.ts:428](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L428) |
| <a id="value"></a> `value` | `readonly` | `unknown` | The value that was received and caused the error. Provides additional context for debugging and validation feedback. | [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError).[`value`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError.mdx#value) | [packages/common/src/Type.ts:434](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L434) |
Int64StringError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / Int64StringError
# Interface: Int64StringError
Defined in: [packages/common/src/Type.ts:3645](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L3645)
## Extends
- [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError)\<`"Int64String"`\>
## Properties
| Property | Modifier | Type | Description | Inherited from | Defined in |
| -------------------------- | ---------- | --------------- | -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="type"></a> `type` | `readonly` | `"Int64String"` | - | [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError).[`type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError.mdx#type) | [packages/common/src/Type.ts:428](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L428) |
| <a id="value"></a> `value` | `readonly` | `unknown` | The value that was received and caused the error. Provides additional context for debugging and validation feedback. | [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError).[`value`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError.mdx#value) | [packages/common/src/Type.ts:434](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L434) |
IntError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / IntError
# Interface: IntError
Defined in: [packages/common/src/Type.ts:1959](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1959)
## Extends
- [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError)\<`"Int"`\>
## Properties
| Property | Modifier | Type | Description | Inherited from | Defined in |
| -------------------------- | ---------- | --------- | -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="type"></a> `type` | `readonly` | `"Int"` | - | [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError).[`type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError.mdx#type) | [packages/common/src/Type.ts:428](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L428) |
| <a id="value"></a> `value` | `readonly` | `unknown` | The value that was received and caused the error. Provides additional context for debugging and validation feedback. | [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError).[`value`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError.mdx#value) | [packages/common/src/Type.ts:434](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L434) |
JsonError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / JsonError
# Interface: JsonError
Defined in: [packages/common/src/Type.ts:3776](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L3776)
## Extends
- [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError)\<`"Json"`\>
## Properties
| Property | Modifier | Type | Description | Inherited from | Defined in |
| ------------------------------ | ---------- | --------- | -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="message"></a> `message` | `readonly` | `string` | - | - | [packages/common/src/Type.ts:3777](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L3777) |
| <a id="type"></a> `type` | `readonly` | `"Json"` | - | [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError).[`type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError.mdx#type) | [packages/common/src/Type.ts:428](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L428) |
| <a id="value"></a> `value` | `readonly` | `unknown` | The value that was received and caused the error. Provides additional context for debugging and validation feedback. | [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError).[`value`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError.mdx#value) | [packages/common/src/Type.ts:434](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L434) |
JsonObject - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / JsonObject
# Interface: JsonObject
Defined in: [packages/common/src/Type.ts:3678](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L3678)
## Indexable
```ts
[key: string]: JsonValue
```
JsonObjectInput - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / JsonObjectInput
# Interface: JsonObjectInput
Defined in: [packages/common/src/Type.ts:3682](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L3682)
## Indexable
```ts
[key: string]: JsonValueInput
```
LengthError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / LengthError
# Interface: LengthError\<Exact\>
Defined in: [packages/common/src/Type.ts:1294](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1294)
## Extends
- [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError)\<`"Length"`\>
## Type Parameters
| Type Parameter | Default type |
| -------------------------- | ------------ |
| `Exact` _extends_ `number` | `number` |
## Properties
| Property | Modifier | Type | Description | Inherited from | Defined in |
| ---------------------------- | ---------- | ---------- | -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="exact-1"></a> `exact` | `readonly` | `Exact` | - | - | [packages/common/src/Type.ts:1297](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1297) |
| <a id="type"></a> `type` | `readonly` | `"Length"` | - | [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError).[`type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError.mdx#type) | [packages/common/src/Type.ts:428](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L428) |
| <a id="value"></a> `value` | `readonly` | `unknown` | The value that was received and caused the error. Provides additional context for debugging and validation feedback. | [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError).[`value`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError.mdx#value) | [packages/common/src/Type.ts:434](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L434) |
LessThanError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / LessThanError
# Interface: LessThanError\<Max\>
Defined in: [packages/common/src/Type.ts:2047](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L2047)
## Extends
- [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError)\<`"LessThan"`\>
## Type Parameters
| Type Parameter | Default type |
| ------------------------ | ------------ |
| `Max` _extends_ `number` | `number` |
## Properties
| Property | Modifier | Type | Description | Inherited from | Defined in |
| -------------------------- | ---------- | ------------ | -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="max-1"></a> `max` | `readonly` | `Max` | - | - | [packages/common/src/Type.ts:2050](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L2050) |
| <a id="type"></a> `type` | `readonly` | `"LessThan"` | - | [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError).[`type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError.mdx#type) | [packages/common/src/Type.ts:428](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L428) |
| <a id="value"></a> `value` | `readonly` | `unknown` | The value that was received and caused the error. Provides additional context for debugging and validation feedback. | [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError).[`value`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError.mdx#value) | [packages/common/src/Type.ts:434](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L434) |
LessThanOrEqualToError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / LessThanOrEqualToError
# Interface: LessThanOrEqualToError\<Max\>
Defined in: [packages/common/src/Type.ts:2102](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L2102)
## Extends
- [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError)\<`"LessThanOrEqualTo"`\>
## Type Parameters
| Type Parameter | Default type |
| ------------------------ | ------------ |
| `Max` _extends_ `number` | `number` |
## Properties
| Property | Modifier | Type | Description | Inherited from | Defined in |
| -------------------------- | ---------- | --------------------- | -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="max-1"></a> `max` | `readonly` | `Max` | - | - | [packages/common/src/Type.ts:2105](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L2105) |
| <a id="type"></a> `type` | `readonly` | `"LessThanOrEqualTo"` | - | [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError).[`type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError.mdx#type) | [packages/common/src/Type.ts:428](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L428) |
| <a id="value"></a> `value` | `readonly` | `unknown` | The value that was received and caused the error. Provides additional context for debugging and validation feedback. | [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError).[`value`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError.mdx#value) | [packages/common/src/Type.ts:434](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L434) |
LiteralError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / LiteralError
# Interface: LiteralError\<T\>
Defined in: [packages/common/src/Type.ts:2272](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L2272)
## Extends
- [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError)\<`"Literal"`\>
## Type Parameters
| Type Parameter | Default type |
| ------------------------------------------------------------------------------------ | ---------------------------------------------------------------------- |
| `T` _extends_ [`Literal`](https://evolu.dev/docs/api-reference/common/Types/type-aliases/Literal) | [`Literal`](https://evolu.dev/docs/api-reference/common/Types/type-aliases/Literal) |
## Properties
| Property | Modifier | Type | Description | Inherited from | Defined in |
| -------------------------------- | ---------- | ----------- | -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="expected"></a> `expected` | `readonly` | `T` | - | - | [packages/common/src/Type.ts:2275](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L2275) |
| <a id="type"></a> `type` | `readonly` | `"Literal"` | - | [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError).[`type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError.mdx#type) | [packages/common/src/Type.ts:428](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L428) |
| <a id="value"></a> `value` | `readonly` | `unknown` | The value that was received and caused the error. Provides additional context for debugging and validation feedback. | [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError).[`value`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError.mdx#value) | [packages/common/src/Type.ts:434](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L434) |
LiteralType - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / LiteralType
# Interface: LiteralType\<T\>
Defined in: [packages/common/src/Type.ts:2263](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L2263)
Evolu [Type](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type) is like a type guard that returns typed errors (via
[Result](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result)) instead of throwing. We either get a safely typed value or a
composable typed error telling us exactly why validation failed.
Why another validation library?
- **Result-based error handling** – no exceptions for normal control flow.
- **Typed errors with decoupled formatters** – validation logic ≠ user
messages.
- **Consistent constraints via [Brand](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)** – every constraint becomes part
of the type.
- **Skippable validation** – parent validations can be skipped when already
proved by types.
- **Simple, top-down implementation** – readable source code from top to
bottom.
- **No user-land chaining DSL** – prepared for TC39 Hack pipes.
A distinctive feature of Evolu Type compared to other validation libraries is
that it returns typed errors rather than string messages. This allows
TypeScript to enforce that all validation errors are handled by type
checking, significantly improving the developer experience.
Evolu Type supports [Standard Schema](https://standardschema.dev/) for
interoperability with 40+ validation-compatible tools and frameworks.
### Base Types Quick Start
```ts
// Validate unknown values
const value: unknown = "hello";
const stringResult = String.fromUnknown(value);
if (!stringResult.ok) {
// console.error(formatStringError(stringResult.error));
return stringResult; // inside a function returning Result<string, _>
}
// Safe branch: value is now string
const upper = stringResult.value.toUpperCase();
// Type guard style
if (String.is(value)) {
// narrowed to string
}
// Composing: arrays & objects
const Numbers = array(Number); // ReadonlyArray<number>
const Point = object({ x: Number, y: Number });
Numbers.from([1, 2, 3]); // ok
Point.from({ x: 1, y: 2 }); // ok
Point.from({ x: 1, y: "2" }); // err -> nested Number error
```
### Branding Basics
Branding adds semantic meaning & constraints while preserving the runtime
shape:
```ts
const CurrencyCode = brand("CurrencyCode", String, (value) =>
/^[A-Z]{3}$/.test(value)
? ok(value)
: err<CurrencyCodeError>({ type: "CurrencyCode", value }),
);
type CurrencyCode = typeof CurrencyCode.Type; // string & Brand<"CurrencyCode">
interface CurrencyCodeError extends TypeError<"CurrencyCode"> {}
const formatCurrencyCodeError = createTypeErrorFormatter<CurrencyCodeError>(
(error) => `Invalid currency code: ${error.value}`,
);
const r = CurrencyCode.from("USD"); // ok("USD")
const e = CurrencyCode.from("usd"); // err(...)
```
See also reusable brand factories like `minLength`, `maxLength`, `trimmed`,
`positive`, `between`, etc.
### Objects & Optional Fields
```ts
const User = object({
name: NonEmptyTrimmedString100,
age: optional(PositiveInt),
});
type User = typeof User.Type;
User.from({ name: "Alice" }); // ok
User.from({ name: "Alice", age: -1 }); // err(PositiveInt)
```
### Deriving JSON String Types
```ts
const Person = object({
name: NonEmptyString50,
// Did you know that JSON.stringify converts NaN (a number) into null?
// To prevent this, use FiniteNumber.
age: FiniteNumber,
});
type Person = typeof Person.Type;
const [PersonJson, personToPersonJson, personJsonToPerson] = json(
Person,
"PersonJson",
);
// string & Brand<"PersonJson">
type PersonJson = typeof PersonJson.Type;
const person = Person.orThrow({
name: "Alice",
age: 30,
});
const personJson = personToPersonJson(person);
expect(personJsonToPerson(personJson)).toEqual(person);
```
### Error Formatting
Evolu separates validation logic from human-readable messages. There are two
layers:
1. Per-type formatters (e.g. `formatStringError`) – simple, focused, already
used earlier in the quick start example.
2. A unified formatter via `createFormatTypeError` – composes all built-in and
custom errors (including nested composite types) and lets us override
selected messages.
#### 1. Per-Type Formatter (recap)
```ts
const r = String.fromUnknown(42);
if (!r.ok) console.error(formatStringError(r.error));
```
#### 2. Unified Formatter with Overrides
```ts
// Override only what we care about; fall back to built-ins for the rest.
const formatTypeError = createFormatTypeError((error) => {
if (error.type === "MinLength") return `Min length is ${error.min}`;
});
const User = object({ name: NonEmptyTrimmedString100 });
const resultUser = User.from({ name: "" });
if (!resultUser.ok) console.error(formatTypeError(resultUser.error));
const badPoint = object({ x: Number, y: Number }).from({
x: 1,
y: "foo",
});
if (!badPoint.ok) console.error(formatTypeError(badPoint.error));
```
The unified formatter walks nested structures (object / array / record /
tuple / union) and applies overrides only where specified, greatly reducing
boilerplate when formatting complex validation errors.
### Tip
If necessary, write `globalThis.String` instead of `String` to avoid naming
clashes with native types.
### Design Decision: No Bidirectional Transformations
Evolu Type intentionally does not support bidirectional transformations. It
previously did, but supporting that while keeping typed error fidelity added
complexity that hurt readability & reliability. Most persistence pipelines
(e.g. SQLite) already require explicit mapping of query results, so implicit
reverse transforms would not buy much. We may revisit this if we can design a
minimal, 100% safe API that preserves simplicity.
### Prepared for TC39 Hack Pipes
Take a look how `SimplePassword` is defined:
```ts
export const SimplePassword = brand(
"SimplePassword",
minLength(8)(maxLength(64)(TrimmedString)),
);
```
Nested functions are often OK (if not, make a helper) and read well, but with
TC39 Hack pipes it would be clearer:
```ts
// TrimmedString
// |> minLength(8)(%)
// |> maxLength(64)(%)
// |> brand("SimplePassword", %)
```
Note `minLength` and `maxLength` are curried because they are factories.
## Extends
- [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type)\<`"Literal"`, `T`, [`WidenLiteral`](https://evolu.dev/docs/api-reference/common/Types/type-aliases/WidenLiteral)\<`T`\>, [`LiteralError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/LiteralError)\<`T`\>\>
## Type Parameters
| Type Parameter |
| ------------------------------------------------------------------------------------ |
| `T` _extends_ [`Literal`](https://evolu.dev/docs/api-reference/common/Types/type-aliases/Literal) |
## Properties
| Property | Modifier | Type | Description | Inherited from | Defined in |
| ------------------------------------------------ | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="evolutypesymbol"></a> `[EvoluTypeSymbol]` | `readonly` | `true` | - | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`[EvoluTypeSymbol]`](/docs/api-reference/common/Type/interfaces/Type.mdx#evolutypesymbol) | [packages/common/src/Type.ts:353](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L353) |
| <a id="standard"></a> `~standard` | `readonly` | [`Props`](https://evolu.dev/docs/api-reference/common/Type/namespaces/StandardSchemaV1/interfaces/Props)\<[`WidenLiteral`](https://evolu.dev/docs/api-reference/common/Types/type-aliases/WidenLiteral)\<`T`\>, `T`\> | The Standard Schema properties. | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`~standard`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#standard) | [packages/common/src/Type.ts:4450](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L4450) |
| <a id="error"></a> `Error` | `public` | [`LiteralError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/LiteralError)\<`T`\> | The specific error introduced by this Type. ### Example `type StringError = typeof String.Error;` | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`Error`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#error) | [packages/common/src/Type.ts:221](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L221) |
| <a id="errors"></a> `Errors` | `readonly` | [`LiteralError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/LiteralError)\<`T`\> | ### Example `type StringParentErrors = typeof String.Errors;` | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`Errors`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#errors) | [packages/common/src/Type.ts:417](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L417) |
| <a id="expected"></a> `expected` | `public` | `T` | - | - | [packages/common/src/Type.ts:2269](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L2269) |
| <a id="from"></a> `from` | `readonly` | (`value`) => [`Result`](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result)\<`T`, [`LiteralError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/LiteralError)\<`T`\>\> | Creates `T` from an `Input` value. This is useful when we have a typed value. `from` is a typed alias of `fromUnknown`. | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`from`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#from) | [packages/common/src/Type.ts:236](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L236) |
| <a id="fromparent"></a> `fromParent` | `readonly` | (`value`) => [`Result`](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result)\<`T`, [`LiteralError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/LiteralError)\<`T`\>\> | Creates `T` from `Parent` type. This function skips parent Types validations when we have already partially validated value. | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`fromParent`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#fromparent) | [packages/common/src/Type.ts:330](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L330) |
| <a id="fromunknown"></a> `fromUnknown` | `readonly` | (`value`) => [`Result`](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result)\<`T`, [`LiteralError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/LiteralError)\<`T`\>\> | Creates `T` from an unknown value. This is useful when a value is unknown. | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`fromUnknown`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#fromunknown) | [packages/common/src/Type.ts:322](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L322) |
| <a id="input"></a> `Input` | `public` | [`WidenLiteral`](https://evolu.dev/docs/api-reference/common/Types/type-aliases/WidenLiteral)\<`T`\> | The type expected by `from` and `fromUnknown`. ### Example `type StringInput = typeof String.Input;` | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`Input`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#input) | [packages/common/src/Type.ts:219](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L219) |
| <a id="is"></a> `is` | `readonly` | [`Refinement`](https://evolu.dev/docs/api-reference/common/Types/type-aliases/Refinement)\<`unknown`, `T`\> | A **type guard** that checks whether an unknown value satisfies the [Type](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type). ### Example `const value: unknown = "hello"; if (String.is(value)) { // TypeScript now knows `value`is a`string` here. console.log("This is a valid string!"); } const strings: unknown[] = [1, "hello", true, "world"]; const filteredStrings = strings.filter(String.is); console.log(filteredStrings); // ["hello", "world"]` | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`is`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#is) | [packages/common/src/Type.ts:351](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L351) |
| <a id="name"></a> `name` | `readonly` | `"Literal"` | - | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`name`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#name-1) | [packages/common/src/Type.ts:227](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L227) |
| <a id="ornull"></a> `orNull` | `readonly` | (`value`) => `T` \| `null` | Creates `T` from an `Input` value, returning `null` if validation fails. This is a convenience method that combines `from` with `getOrNull`. **When to use:** - When you need to convert a validation result to a nullable value - When the error is not important and you just want the value or nothing ### Example `// ✅ Good: Optional user input const age = PositiveInt.orNull(userInput); if (age != null) { console.log("Valid age:", age); } // ✅ Good: Default fallback const maxRetries = PositiveInt.orNull(config.retries) ?? 3; // ❌ Avoid: When you need to know why validation failed (use `from` instead) const result = PositiveInt.from(userInput); if (!result.ok) { console.error(formatPositiveError(result.error)); }` | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`orNull`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#ornull) | [packages/common/src/Type.ts:315](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L315) |
| <a id="orthrow"></a> `orThrow` | `readonly` | (`value`) => `T` | Creates `T` from an `Input` value, throwing an error if validation fails. Throws an Error with the Type validation error in its `cause` property, making it debuggable while avoiding the need for custom error messages. This is a convenience method that combines `from` with `getOrThrow`. **When to use:** - Configuration values that are guaranteed to be valid (e.g., hardcoded constants) - Application startup where failure should crash the program - As an alternative to assertions when the Type error in the thrown Error's `cause` provides sufficient debugging information - Test code with known valid inputs (when error message clarity is not critical; for better test error messages, use Vitest `schemaMatching` + `assert` with `.is()`) ### Example `// ✅ Good: Known valid constant const maxRetries = PositiveInt.orThrow(3); // ✅ Good: App configuration that should crash on invalid values const appName = SimpleName.orThrow("MyApp"); // ✅ Good: Instead of assert when Type error is clear enough // Context makes it obvious: count increments from non-negative value const currentCount = counts.get(id) ?? 0; const newCount = PositiveInt.orThrow(currentCount + 1); // ✅ Good: Test setup with known valid values const testUser = User.orThrow({ name: "Alice", age: 30 }); // ❌ Avoid: User input (use `from` instead) const userAge = PositiveInt.orThrow(userInput); // Could crash! // ✅ Better: Handle user input gracefully const ageResult = PositiveInt.from(userInput); if (!ageResult.ok) { // Handle validation error }` | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`orThrow`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#orthrow) | [packages/common/src/Type.ts:284](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L284) |
| <a id="parent"></a> `Parent` | `public` | `T` | The parent type. ### Example `type StringParent = typeof String.Parent;` | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`Parent`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#parent) | [packages/common/src/Type.ts:223](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L223) |
| <a id="parenterror"></a> `ParentError` | `public` | [`LiteralError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/LiteralError)\<`T`\> | The parent's error. ### Example `type StringParentError = typeof String.ParentError;` | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`ParentError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#parenterror) | [packages/common/src/Type.ts:225](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L225) |
| <a id="type"></a> `Type` | `readonly` | `T` | The type this Type resolves to. ### Example `type String = typeof String.Type;` | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#type) | [packages/common/src/Type.ts:364](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L364) |
MaxLengthError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / MaxLengthError
# Interface: MaxLengthError\<Max\>
Defined in: [packages/common/src/Type.ts:1260](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1260)
## Extends
- [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError)\<`"MaxLength"`\>
## Type Parameters
| Type Parameter | Default type |
| ------------------------ | ------------ |
| `Max` _extends_ `number` | `number` |
## Properties
| Property | Modifier | Type | Description | Inherited from | Defined in |
| -------------------------- | ---------- | ------------- | -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="max-1"></a> `max` | `readonly` | `Max` | - | - | [packages/common/src/Type.ts:1263](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1263) |
| <a id="type"></a> `type` | `readonly` | `"MaxLength"` | - | [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError).[`type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError.mdx#type) | [packages/common/src/Type.ts:428](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L428) |
| <a id="value"></a> `value` | `readonly` | `unknown` | The value that was received and caused the error. Provides additional context for debugging and validation feedback. | [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError).[`value`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError.mdx#value) | [packages/common/src/Type.ts:434](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L434) |
MinLengthError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / MinLengthError
# Interface: MinLengthError\<Min\>
Defined in: [packages/common/src/Type.ts:1228](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1228)
## Extends
- [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError)\<`"MinLength"`\>
## Type Parameters
| Type Parameter | Default type |
| ------------------------ | ------------ |
| `Min` _extends_ `number` | `number` |
## Properties
| Property | Modifier | Type | Description | Inherited from | Defined in |
| -------------------------- | ---------- | ------------- | -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="min-1"></a> `min` | `readonly` | `Min` | - | - | [packages/common/src/Type.ts:1231](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1231) |
| <a id="type"></a> `type` | `readonly` | `"MinLength"` | - | [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError).[`type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError.mdx#type) | [packages/common/src/Type.ts:428](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L428) |
| <a id="value"></a> `value` | `readonly` | `unknown` | The value that was received and caused the error. Provides additional context for debugging and validation feedback. | [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError).[`value`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError.mdx#value) | [packages/common/src/Type.ts:434](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L434) |
MnemonicError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / MnemonicError
# Interface: MnemonicError
Defined in: [packages/common/src/Type.ts:1361](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1361)
## Extends
- [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError)\<`"Mnemonic"`\>
## Properties
| Property | Modifier | Type | Description | Inherited from | Defined in |
| -------------------------- | ---------- | ------------ | -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="type"></a> `type` | `readonly` | `"Mnemonic"` | - | [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError).[`type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError.mdx#type) | [packages/common/src/Type.ts:428](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L428) |
| <a id="value"></a> `value` | `readonly` | `unknown` | The value that was received and caused the error. Provides additional context for debugging and validation feedback. | [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError).[`value`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError.mdx#value) | [packages/common/src/Type.ts:434](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L434) |
MultipleOfError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / MultipleOfError
# Interface: MultipleOfError\<Divisor\>
Defined in: [packages/common/src/Type.ts:2184](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L2184)
## Extends
- [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError)\<`"MultipleOf"`\>
## Type Parameters
| Type Parameter | Default type |
| ---------------------------- | ------------ |
| `Divisor` _extends_ `number` | `number` |
## Properties
| Property | Modifier | Type | Description | Inherited from | Defined in |
| -------------------------------- | ---------- | -------------- | -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="divisor-1"></a> `divisor` | `readonly` | `Divisor` | - | - | [packages/common/src/Type.ts:2187](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L2187) |
| <a id="type"></a> `type` | `readonly` | `"MultipleOf"` | - | [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError).[`type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError.mdx#type) | [packages/common/src/Type.ts:428](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L428) |
| <a id="value"></a> `value` | `readonly` | `unknown` | The value that was received and caused the error. Provides additional context for debugging and validation feedback. | [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError).[`value`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError.mdx#value) | [packages/common/src/Type.ts:434](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L434) |
NegativeError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / NegativeError
# Interface: NegativeError
Defined in: [packages/common/src/Type.ts:1845](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1845)
## Extends
- [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError)\<`"Negative"`\>
## Properties
| Property | Modifier | Type | Description | Inherited from | Defined in |
| -------------------------- | ---------- | ------------ | -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="type"></a> `type` | `readonly` | `"Negative"` | - | [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError).[`type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError.mdx#type) | [packages/common/src/Type.ts:428](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L428) |
| <a id="value"></a> `value` | `readonly` | `unknown` | The value that was received and caused the error. Provides additional context for debugging and validation feedback. | [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError).[`value`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError.mdx#value) | [packages/common/src/Type.ts:434](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L434) |
NonNaNError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / NonNaNError
# Interface: NonNaNError
Defined in: [packages/common/src/Type.ts:2125](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L2125)
## Extends
- [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError)\<`"NonNaN"`\>
## Properties
| Property | Modifier | Type | Description | Inherited from | Defined in |
| -------------------------- | ---------- | ---------- | -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="type"></a> `type` | `readonly` | `"NonNaN"` | - | [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError).[`type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError.mdx#type) | [packages/common/src/Type.ts:428](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L428) |
| <a id="value"></a> `value` | `readonly` | `unknown` | The value that was received and caused the error. Provides additional context for debugging and validation feedback. | [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError).[`value`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError.mdx#value) | [packages/common/src/Type.ts:434](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L434) |
NonNegativeError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / NonNegativeError
# Interface: NonNegativeError
Defined in: [packages/common/src/Type.ts:1902](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1902)
## Extends
- [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError)\<`"NonNegative"`\>
## Properties
| Property | Modifier | Type | Description | Inherited from | Defined in |
| -------------------------- | ---------- | --------------- | -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="type"></a> `type` | `readonly` | `"NonNegative"` | - | [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError).[`type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError.mdx#type) | [packages/common/src/Type.ts:428](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L428) |
| <a id="value"></a> `value` | `readonly` | `unknown` | The value that was received and caused the error. Provides additional context for debugging and validation feedback. | [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError).[`value`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError.mdx#value) | [packages/common/src/Type.ts:434](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L434) |
NonPositiveError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / NonPositiveError
# Interface: NonPositiveError
Defined in: [packages/common/src/Type.ts:1873](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1873)
## Extends
- [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError)\<`"NonPositive"`\>
## Properties
| Property | Modifier | Type | Description | Inherited from | Defined in |
| -------------------------- | ---------- | --------------- | -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="type"></a> `type` | `readonly` | `"NonPositive"` | - | [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError).[`type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError.mdx#type) | [packages/common/src/Type.ts:428](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L428) |
| <a id="value"></a> `value` | `readonly` | `unknown` | The value that was received and caused the error. Provides additional context for debugging and validation feedback. | [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError).[`value`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError.mdx#value) | [packages/common/src/Type.ts:434](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L434) |
NullError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / NullError
# Interface: NullError
Defined in: [packages/common/src/Type.ts:731](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L731)
## Extends
- [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError)\<`"Null"`\>
## Properties
| Property | Modifier | Type | Description | Inherited from | Defined in |
| -------------------------- | ---------- | --------- | -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="type"></a> `type` | `readonly` | `"Null"` | - | [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError).[`type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError.mdx#type) | [packages/common/src/Type.ts:428](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L428) |
| <a id="value"></a> `value` | `readonly` | `unknown` | The value that was received and caused the error. Provides additional context for debugging and validation feedback. | [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError).[`value`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError.mdx#value) | [packages/common/src/Type.ts:434](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L434) |
NumberError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / NumberError
# Interface: NumberError
Defined in: [packages/common/src/Type.ts:688](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L688)
## Extends
- [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError)\<`"Number"`\>
## Properties
| Property | Modifier | Type | Description | Inherited from | Defined in |
| -------------------------- | ---------- | ---------- | -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="type"></a> `type` | `readonly` | `"Number"` | - | [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError).[`type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError.mdx#type) | [packages/common/src/Type.ts:428](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L428) |
| <a id="value"></a> `value` | `readonly` | `unknown` | The value that was received and caused the error. Provides additional context for debugging and validation feedback. | [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError).[`value`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError.mdx#value) | [packages/common/src/Type.ts:434](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L434) |
ObjectError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / ObjectError
# Interface: ObjectError\<PropsErrors\>
Defined in: [packages/common/src/Type.ts:3079](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L3079)
## Extends
- [`TypeErrorWithReason`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeErrorWithReason)\<`"Object"`,
\| \{
`kind`: `"NotObject"`;
\}
\| \{
`errors`: `Partial`\<`PropsErrors`\>;
`kind`: `"Props"`;
\}
\| \{
`extraKeys`: `ReadonlyArray`\<`string`\>;
`kind`: `"ExtraKeys"`;
\}\>
## Type Parameters
| Type Parameter | Default type |
| --------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| `PropsErrors` _extends_ `Record`\<`string`, [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError)\> | `Record`\<`string`, [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError)\> |
## Properties
| Property | Modifier | Type | Description | Inherited from | Defined in |
| ---------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="reason"></a> `reason` | `readonly` | \| \{ `kind`: `"NotObject"`; \} \| \{ `errors`: `Partial`\<`PropsErrors`\>; `kind`: `"Props"`; \} \| \{ `extraKeys`: readonly `string`[]; `kind`: `"ExtraKeys"`; \} | The detailed reason for the error, represented as a tagged union. | [`TypeErrorWithReason`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeErrorWithReason).[`reason`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeErrorWithReason.mdx#reason-1) | [packages/common/src/Type.ts:444](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L444) |
| <a id="type"></a> `type` | `readonly` | `"Object"` | - | [`TypeErrorWithReason`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeErrorWithReason).[`type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeErrorWithReason.mdx#type) | [packages/common/src/Type.ts:428](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L428) |
| <a id="value"></a> `value` | `readonly` | `unknown` | The value that was received and caused the error. Provides additional context for debugging and validation feedback. | [`TypeErrorWithReason`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeErrorWithReason).[`value`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeErrorWithReason.mdx#value) | [packages/common/src/Type.ts:434](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L434) |
ObjectType - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / ObjectType
# Interface: ObjectType\<Props\>
Defined in: [packages/common/src/Type.ts:3029](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L3029)
ObjectType extends [Type](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type) with an additional `props` property for
reflection.
## Extends
- [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type)\<`"Object"`, `Readonly`\<`ObjectT`\<`Props`\>\>, `Readonly`\<`ObjectInput`\<`Props`\>\>, [`ObjectError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/ObjectError)\<`{ [K in keyof Props]: InferError<Props[K]> }`\>, `Readonly`\<`ObjectParent`\<`Props`\>\>, [`ObjectError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/ObjectError)\<`{ [K in keyof Props]: InferParentError<Props[K]> }`\>\>
## Type Parameters
| Type Parameter |
| ------------------------------------------------------------------------------------------------------------- |
| `Props` _extends_ `Record`\<`string`, [`AnyType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/AnyType)\> |
## Properties
| Property | Modifier | Type | Description | Inherited from | Defined in |
| ------------------------------------------------ | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="evolutypesymbol"></a> `[EvoluTypeSymbol]` | `readonly` | `true` | - | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`[EvoluTypeSymbol]`](/docs/api-reference/common/Type/interfaces/Type.mdx#evolutypesymbol) | [packages/common/src/Type.ts:353](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L353) |
| <a id="standard"></a> `~standard` | `readonly` | [`Props`](https://evolu.dev/docs/api-reference/common/Type/namespaces/StandardSchemaV1/interfaces/Props)\<`Readonly`\<`DrainOuterGeneric`\<\{ \[K in string \| number \| symbol\]: (\{ \[K in string \| number \| symbol\]: InferInput\<Props\[K\]\> \} & \{ \[K in string \| number \| symbol\]?: Props\[K\] extends OptionalType\<U\> ? InferInput\<U\> : never \})\[K\] \}\>\>, `Readonly`\<`DrainOuterGeneric`\<\{ \[K in string \| number \| symbol\]: (\{ \[K in string \| number \| symbol\]: InferType\<Props\[K\]\> \} & \{ \[K in string \| number \| symbol\]?: Props\[K\] extends OptionalType\<U\> ? InferType\<U\> : never \})\[K\] \}\>\>\> | The Standard Schema properties. | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`~standard`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#standard) | [packages/common/src/Type.ts:4450](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L4450) |
| <a id="error"></a> `Error` | `public` | [`ObjectError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/ObjectError)\<\{ \[K in string \| number \| symbol\]: InferError\<Props\[K\]\> \}\> | The specific error introduced by this Type. ### Example `type StringError = typeof String.Error;` | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`Error`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#error) | [packages/common/src/Type.ts:221](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L221) |
| <a id="errors"></a> `Errors` | `readonly` | \| [`ObjectError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/ObjectError)\<\{ \[K in string \| number \| symbol\]: InferError\<Props\[K\]\> \}\> \| [`ObjectError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/ObjectError)\<\{ \[K in string \| number \| symbol\]: InferParentError\<Props\[K\]\> \}\> | ### Example `type StringParentErrors = typeof String.Errors;` | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`Errors`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#errors) | [packages/common/src/Type.ts:417](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L417) |
| <a id="from"></a> `from` | `readonly` | (`value`) => [`Result`](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result)\<`Readonly`\<`DrainOuterGeneric`\<\{ \[K in string \| number \| symbol\]: (\{ \[K in string \| number \| symbol\]: InferType\<Props\[K\]\> \} & \{ \[K in string \| number \| symbol\]?: (...)\[(...)\] extends OptionalType\<(...)\> ? InferType\<(...)\> : never \})\[K\] \}\>\>, \| [`ObjectError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/ObjectError)\<\{ \[K in string \| number \| symbol\]: InferError\<Props\[K\]\> \}\> \| [`ObjectError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/ObjectError)\<\{ \[K in string \| number \| symbol\]: InferParentError\<Props\[K\]\> \}\>\> | Creates `T` from an `Input` value. This is useful when we have a typed value. `from` is a typed alias of `fromUnknown`. | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`from`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#from) | [packages/common/src/Type.ts:236](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L236) |
| <a id="fromparent"></a> `fromParent` | `readonly` | (`value`) => [`Result`](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result)\<`Readonly`\<`DrainOuterGeneric`\<\{ \[K in string \| number \| symbol\]: (\{ \[K in string \| number \| symbol\]: InferType\<Props\[K\]\> \} & \{ \[K in string \| number \| symbol\]?: (...)\[(...)\] extends OptionalType\<(...)\> ? InferType\<(...)\> : never \})\[K\] \}\>\>, [`ObjectError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/ObjectError)\<\{ \[K in string \| number \| symbol\]: InferError\<Props\[K\]\> \}\>\> | Creates `T` from `Parent` type. This function skips parent Types validations when we have already partially validated value. | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`fromParent`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#fromparent) | [packages/common/src/Type.ts:330](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L330) |
| <a id="fromunknown"></a> `fromUnknown` | `readonly` | (`value`) => [`Result`](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result)\<`Readonly`\<`DrainOuterGeneric`\<\{ \[K in string \| number \| symbol\]: (\{ \[K in string \| number \| symbol\]: InferType\<Props\[K\]\> \} & \{ \[K in string \| number \| symbol\]?: (...)\[(...)\] extends OptionalType\<(...)\> ? InferType\<(...)\> : never \})\[K\] \}\>\>, \| [`ObjectError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/ObjectError)\<\{ \[K in string \| number \| symbol\]: InferError\<Props\[K\]\> \}\> \| [`ObjectError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/ObjectError)\<\{ \[K in string \| number \| symbol\]: InferParentError\<Props\[K\]\> \}\>\> | Creates `T` from an unknown value. This is useful when a value is unknown. | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`fromUnknown`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#fromunknown) | [packages/common/src/Type.ts:322](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L322) |
| <a id="input"></a> `Input` | `public` | `Readonly`\<`DrainOuterGeneric`\<\{ \[K in string \| number \| symbol\]: (\{ \[K in string \| number \| symbol\]: InferInput\<Props\[K\]\> \} & \{ \[K in string \| number \| symbol\]?: Props\[K\] extends OptionalType\<U\> ? InferInput\<U\> : never \})\[K\] \}\>\> | The type expected by `from` and `fromUnknown`. ### Example `type StringInput = typeof String.Input;` | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`Input`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#input) | [packages/common/src/Type.ts:219](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L219) |
| <a id="is"></a> `is` | `readonly` | [`Refinement`](https://evolu.dev/docs/api-reference/common/Types/type-aliases/Refinement)\<`unknown`, `Readonly`\<`DrainOuterGeneric`\<\{ \[K in string \| number \| symbol\]: (\{ \[K in string \| number \| symbol\]: InferType\<Props\[K\]\> \} & \{ \[K in string \| number \| symbol\]?: Props\[K\] extends OptionalType\<U\> ? InferType\<U\> : never \})\[K\] \}\>\>\> | A **type guard** that checks whether an unknown value satisfies the [Type](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type). ### Example `const value: unknown = "hello"; if (String.is(value)) { // TypeScript now knows `value`is a`string` here. console.log("This is a valid string!"); } const strings: unknown[] = [1, "hello", true, "world"]; const filteredStrings = strings.filter(String.is); console.log(filteredStrings); // ["hello", "world"]` | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`is`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#is) | [packages/common/src/Type.ts:351](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L351) |
| <a id="name"></a> `name` | `readonly` | `"Object"` | - | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`name`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#name-1) | [packages/common/src/Type.ts:227](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L227) |
| <a id="ornull"></a> `orNull` | `readonly` | (`value`) => \| `Readonly`\<`DrainOuterGeneric`\<\{ \[K in string \| number \| symbol\]: (\{ \[K in string \| number \| symbol\]: InferType\<Props\[K\]\> \} & \{ \[K in string \| number \| symbol\]?: (...)\[(...)\] extends OptionalType\<(...)\> ? InferType\<(...)\> : never \})\[K\] \}\>\> \| `null` | Creates `T` from an `Input` value, returning `null` if validation fails. This is a convenience method that combines `from` with `getOrNull`. **When to use:** - When you need to convert a validation result to a nullable value - When the error is not important and you just want the value or nothing ### Example `// ✅ Good: Optional user input const age = PositiveInt.orNull(userInput); if (age != null) { console.log("Valid age:", age); } // ✅ Good: Default fallback const maxRetries = PositiveInt.orNull(config.retries) ?? 3; // ❌ Avoid: When you need to know why validation failed (use `from` instead) const result = PositiveInt.from(userInput); if (!result.ok) { console.error(formatPositiveError(result.error)); }` | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`orNull`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#ornull) | [packages/common/src/Type.ts:315](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L315) |
| <a id="orthrow"></a> `orThrow` | `readonly` | (`value`) => `T` | Creates `T` from an `Input` value, throwing an error if validation fails. Throws an Error with the Type validation error in its `cause` property, making it debuggable while avoiding the need for custom error messages. This is a convenience method that combines `from` with `getOrThrow`. **When to use:** - Configuration values that are guaranteed to be valid (e.g., hardcoded constants) - Application startup where failure should crash the program - As an alternative to assertions when the Type error in the thrown Error's `cause` provides sufficient debugging information - Test code with known valid inputs (when error message clarity is not critical; for better test error messages, use Vitest `schemaMatching` + `assert` with `.is()`) ### Example `// ✅ Good: Known valid constant const maxRetries = PositiveInt.orThrow(3); // ✅ Good: App configuration that should crash on invalid values const appName = SimpleName.orThrow("MyApp"); // ✅ Good: Instead of assert when Type error is clear enough // Context makes it obvious: count increments from non-negative value const currentCount = counts.get(id) ?? 0; const newCount = PositiveInt.orThrow(currentCount + 1); // ✅ Good: Test setup with known valid values const testUser = User.orThrow({ name: "Alice", age: 30 }); // ❌ Avoid: User input (use `from` instead) const userAge = PositiveInt.orThrow(userInput); // Could crash! // ✅ Better: Handle user input gracefully const ageResult = PositiveInt.from(userInput); if (!ageResult.ok) { // Handle validation error }` | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`orThrow`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#orthrow) | [packages/common/src/Type.ts:284](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L284) |
| <a id="parent"></a> `Parent` | `public` | `Readonly`\<`DrainOuterGeneric`\<\{ \[K in string \| number \| symbol\]: (\{ \[K in string \| number \| symbol\]: InferParent\<Props\[K\]\> \} & \{ \[K in string \| number \| symbol\]?: Props\[K\] extends OptionalType\<U\> ? InferParent\<U\> : never \})\[K\] \}\>\> | The parent type. ### Example `type StringParent = typeof String.Parent;` | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`Parent`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#parent) | [packages/common/src/Type.ts:223](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L223) |
| <a id="parenterror"></a> `ParentError` | `public` | [`ObjectError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/ObjectError)\<\{ \[K in string \| number \| symbol\]: InferParentError\<Props\[K\]\> \}\> | The parent's error. ### Example `type StringParentError = typeof String.ParentError;` | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`ParentError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#parenterror) | [packages/common/src/Type.ts:225](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L225) |
| <a id="props-1"></a> `props` | `readonly` | `Props` | - | - | [packages/common/src/Type.ts:3037](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L3037) |
| <a id="type"></a> `Type` | `readonly` | `T` | The type this Type resolves to. ### Example `type String = typeof String.Type;` | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#type) | [packages/common/src/Type.ts:364](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L364) |
ObjectWithRecordError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / ObjectWithRecordError
# Interface: ObjectWithRecordError\<PropsErrors, KeyError, ValueError\>
Defined in: [packages/common/src/Type.ts:3163](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L3163)
## Extends
- [`TypeErrorWithReason`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeErrorWithReason)\<`"ObjectWithRecord"`,
\| \{
`kind`: `"NotObject"`;
\}
\| \{
`errors`: `Partial`\<`PropsErrors`\>;
`kind`: `"Props"`;
\}
\| \{
`error`: `KeyError`;
`key`: `unknown`;
`kind`: `"IndexKey"`;
\}
\| \{
`error`: `ValueError`;
`key`: `string`;
`kind`: `"IndexValue"`;
\}\>
## Type Parameters
| Type Parameter | Default type |
| --------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| `PropsErrors` _extends_ `Record`\<`string`, [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError)\> | `Record`\<`string`, [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError)\> |
| `KeyError` _extends_ [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError) | [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError) |
| `ValueError` _extends_ [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError) | [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError) |
## Properties
| Property | Modifier | Type | Description | Inherited from | Defined in |
| ---------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="reason"></a> `reason` | `readonly` | \| \{ `kind`: `"NotObject"`; \} \| \{ `errors`: `Partial`\<`PropsErrors`\>; `kind`: `"Props"`; \} \| \{ `error`: `KeyError`; `key`: `unknown`; `kind`: `"IndexKey"`; \} \| \{ `error`: `ValueError`; `key`: `string`; `kind`: `"IndexValue"`; \} | The detailed reason for the error, represented as a tagged union. | [`TypeErrorWithReason`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeErrorWithReason).[`reason`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeErrorWithReason.mdx#reason-1) | [packages/common/src/Type.ts:444](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L444) |
| <a id="type"></a> `type` | `readonly` | `"ObjectWithRecord"` | - | [`TypeErrorWithReason`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeErrorWithReason).[`type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeErrorWithReason.mdx#type) | [packages/common/src/Type.ts:428](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L428) |
| <a id="value"></a> `value` | `readonly` | `unknown` | The value that was received and caused the error. Provides additional context for debugging and validation feedback. | [`TypeErrorWithReason`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeErrorWithReason).[`value`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeErrorWithReason.mdx#value) | [packages/common/src/Type.ts:434](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L434) |
ObjectWithRecordType - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / ObjectWithRecordType
# Interface: ObjectWithRecordType\<Props, KeyName, KeyT, KeyInput, KeyError, KeyParent, KeyParentError, Value\>
Defined in: [packages/common/src/Type.ts:3125](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L3125)
ObjectWithRecordType extends [Type](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type) with additional `props` and `record`
properties for reflection.
## Extends
- [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type)\<`"ObjectWithRecord"`, `Readonly`\<`ObjectT`\<`Props`\>\> & `Readonly`\<`Record`\<`KeyT`, [`InferType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferType)\<`Value`\>\>\>, `Readonly`\<`ObjectInput`\<`Props`\>\> & `Readonly`\<`Record`\<`KeyInput`, [`InferInput`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferInput)\<`Value`\>\>\>, [`ObjectWithRecordError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/ObjectWithRecordError)\<`{ [K in keyof Props]: InferError<Props[K]> }`, `KeyError`, [`InferError`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferError)\<`Value`\>\>, `Readonly`\<`ObjectParent`\<`Props`\>\> & `Readonly`\<`Record`\<`KeyParent`, [`InferParent`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferParent)\<`Value`\>\>\>, [`ObjectWithRecordError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/ObjectWithRecordError)\<`{ [K in keyof Props]: InferParentError<Props[K]> }`, `KeyParentError`, [`InferParentError`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferParentError)\<`Value`\>\>\>
## Type Parameters
| Type Parameter |
| ------------------------------------------------------------------------------------------------------------- |
| `Props` _extends_ `Record`\<`string`, [`AnyType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/AnyType)\> |
| `KeyName` _extends_ [`TypeName`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/TypeName) |
| `KeyT` _extends_ `string` |
| `KeyInput` _extends_ `string` |
| `KeyError` _extends_ [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError) |
| `KeyParent` _extends_ `string` |
| `KeyParentError` _extends_ [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError) |
| `Value` _extends_ [`AnyType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/AnyType) |
## Properties
| Property | Modifier | Type | Description | Inherited from | Defined in |
| ------------------------------------------------ | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="evolutypesymbol"></a> `[EvoluTypeSymbol]` | `readonly` | `true` | - | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`[EvoluTypeSymbol]`](/docs/api-reference/common/Type/interfaces/Type.mdx#evolutypesymbol) | [packages/common/src/Type.ts:353](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L353) |
| <a id="standard"></a> `~standard` | `readonly` | [`Props`](https://evolu.dev/docs/api-reference/common/Type/namespaces/StandardSchemaV1/interfaces/Props)\<`Readonly`\<`DrainOuterGeneric`\<\{ \[K in string \| number \| symbol\]: (\{ \[K in string \| number \| symbol\]: InferInput\<Props\[K\]\> \} & \{ \[K in string \| number \| symbol\]?: (...)\[(...)\] extends OptionalType\<(...)\> ? InferInput\<(...)\> : never \})\[K\] \}\>\> & `Readonly`\<`Record`\<`KeyInput`, [`InferInput`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferInput)\<`Value`\>\>\>, `Readonly`\<`DrainOuterGeneric`\<\{ \[K in string \| number \| symbol\]: (\{ \[K in string \| number \| symbol\]: InferType\<Props\[K\]\> \} & \{ \[K in string \| number \| symbol\]?: (...)\[(...)\] extends OptionalType\<(...)\> ? InferType\<(...)\> : never \})\[K\] \}\>\> & `Readonly`\<`Record`\<`KeyT`, [`InferType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferType)\<`Value`\>\>\>\> | The Standard Schema properties. | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`~standard`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#standard) | [packages/common/src/Type.ts:4450](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L4450) |
| <a id="error"></a> `Error` | `public` | [`ObjectWithRecordError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/ObjectWithRecordError)\<\{ \[K in string \| number \| symbol\]: InferError\<Props\[K\]\> \}, `KeyError`, [`InferError`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferError)\<`Value`\>\> | The specific error introduced by this Type. ### Example `type StringError = typeof String.Error;` | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`Error`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#error) | [packages/common/src/Type.ts:221](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L221) |
| <a id="errors"></a> `Errors` | `readonly` | \| [`ObjectWithRecordError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/ObjectWithRecordError)\<\{ \[K in string \| number \| symbol\]: InferError\<Props\[K\]\> \}, `KeyError`, [`InferError`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferError)\<`Value`\>\> \| [`ObjectWithRecordError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/ObjectWithRecordError)\<\{ \[K in string \| number \| symbol\]: InferParentError\<Props\[K\]\> \}, `KeyParentError`, [`InferParentError`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferParentError)\<`Value`\>\> | ### Example `type StringParentErrors = typeof String.Errors;` | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`Errors`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#errors) | [packages/common/src/Type.ts:417](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L417) |
| <a id="from"></a> `from` | `readonly` | (`value`) => [`Result`](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result)\<`Readonly`\<`DrainOuterGeneric`\<\{ \[K in string \| number \| symbol\]: (\{ \[K in string \| number \| symbol\]: InferType\<(...)\[(...)\]\> \} & \{ \[K in string \| number \| symbol\]?: (...) extends (...) ? (...) : (...) \})\[K\] \}\>\> & `Readonly`\<`Record`\<`KeyT`, [`InferType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferType)\<`Value`\>\>\>, \| [`ObjectWithRecordError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/ObjectWithRecordError)\<\{ \[K in string \| number \| symbol\]: InferError\<Props\[K\]\> \}, `KeyError`, [`InferError`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferError)\<`Value`\>\> \| [`ObjectWithRecordError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/ObjectWithRecordError)\<\{ \[K in string \| number \| symbol\]: InferParentError\<Props\[K\]\> \}, `KeyParentError`, [`InferParentError`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferParentError)\<`Value`\>\>\> | Creates `T` from an `Input` value. This is useful when we have a typed value. `from` is a typed alias of `fromUnknown`. | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`from`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#from) | [packages/common/src/Type.ts:236](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L236) |
| <a id="fromparent"></a> `fromParent` | `readonly` | (`value`) => [`Result`](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result)\<`Readonly`\<`DrainOuterGeneric`\<\{ \[K in string \| number \| symbol\]: (\{ \[K in string \| number \| symbol\]: InferType\<(...)\[(...)\]\> \} & \{ \[K in string \| number \| symbol\]?: (...) extends (...) ? (...) : (...) \})\[K\] \}\>\> & `Readonly`\<`Record`\<`KeyT`, [`InferType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferType)\<`Value`\>\>\>, [`ObjectWithRecordError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/ObjectWithRecordError)\<\{ \[K in string \| number \| symbol\]: InferError\<Props\[K\]\> \}, `KeyError`, [`InferError`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferError)\<`Value`\>\>\> | Creates `T` from `Parent` type. This function skips parent Types validations when we have already partially validated value. | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`fromParent`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#fromparent) | [packages/common/src/Type.ts:330](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L330) |
| <a id="fromunknown"></a> `fromUnknown` | `readonly` | (`value`) => [`Result`](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result)\<`Readonly`\<`DrainOuterGeneric`\<\{ \[K in string \| number \| symbol\]: (\{ \[K in string \| number \| symbol\]: InferType\<(...)\[(...)\]\> \} & \{ \[K in string \| number \| symbol\]?: (...) extends (...) ? (...) : (...) \})\[K\] \}\>\> & `Readonly`\<`Record`\<`KeyT`, [`InferType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferType)\<`Value`\>\>\>, \| [`ObjectWithRecordError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/ObjectWithRecordError)\<\{ \[K in string \| number \| symbol\]: InferError\<Props\[K\]\> \}, `KeyError`, [`InferError`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferError)\<`Value`\>\> \| [`ObjectWithRecordError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/ObjectWithRecordError)\<\{ \[K in string \| number \| symbol\]: InferParentError\<Props\[K\]\> \}, `KeyParentError`, [`InferParentError`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferParentError)\<`Value`\>\>\> | Creates `T` from an unknown value. This is useful when a value is unknown. | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`fromUnknown`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#fromunknown) | [packages/common/src/Type.ts:322](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L322) |
| <a id="input"></a> `Input` | `public` | `Readonly`\<`DrainOuterGeneric`\<\{ \[K in string \| number \| symbol\]: (\{ \[K in string \| number \| symbol\]: InferInput\<Props\[K\]\> \} & \{ \[K in string \| number \| symbol\]?: Props\[K\] extends OptionalType\<U\> ? InferInput\<U\> : never \})\[K\] \}\>\> & `Readonly`\<`Record`\<`KeyInput`, [`InferInput`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferInput)\<`Value`\>\>\> | The type expected by `from` and `fromUnknown`. ### Example `type StringInput = typeof String.Input;` | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`Input`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#input) | [packages/common/src/Type.ts:219](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L219) |
| <a id="is"></a> `is` | `readonly` | [`Refinement`](https://evolu.dev/docs/api-reference/common/Types/type-aliases/Refinement)\<`unknown`, `Readonly`\<`DrainOuterGeneric`\<\{ \[K in string \| number \| symbol\]: (\{ \[K in string \| number \| symbol\]: InferType\<Props\[K\]\> \} & \{ \[K in string \| number \| symbol\]?: (...)\[(...)\] extends OptionalType\<(...)\> ? InferType\<(...)\> : never \})\[K\] \}\>\> & `Readonly`\<`Record`\<`KeyT`, [`InferType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferType)\<`Value`\>\>\>\> | A **type guard** that checks whether an unknown value satisfies the [Type](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type). ### Example `const value: unknown = "hello"; if (String.is(value)) { // TypeScript now knows `value`is a`string` here. console.log("This is a valid string!"); } const strings: unknown[] = [1, "hello", true, "world"]; const filteredStrings = strings.filter(String.is); console.log(filteredStrings); // ["hello", "world"]` | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`is`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#is) | [packages/common/src/Type.ts:351](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L351) |
| <a id="name"></a> `name` | `readonly` | `"ObjectWithRecord"` | - | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`name`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#name-1) | [packages/common/src/Type.ts:227](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L227) |
| <a id="ornull"></a> `orNull` | `readonly` | (`value`) => \| `Readonly`\<`DrainOuterGeneric`\<\{ \[K in string \| number \| symbol\]: (\{ \[K in string \| number \| symbol\]: InferType\<(...)\[(...)\]\> \} & \{ \[K in string \| number \| symbol\]?: (...) extends (...) ? (...) : (...) \})\[K\] \}\>\> & `Readonly`\<`Record`\<`KeyT`, [`InferType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferType)\<`Value`\>\>\> \| `null` | Creates `T` from an `Input` value, returning `null` if validation fails. This is a convenience method that combines `from` with `getOrNull`. **When to use:** - When you need to convert a validation result to a nullable value - When the error is not important and you just want the value or nothing ### Example `// ✅ Good: Optional user input const age = PositiveInt.orNull(userInput); if (age != null) { console.log("Valid age:", age); } // ✅ Good: Default fallback const maxRetries = PositiveInt.orNull(config.retries) ?? 3; // ❌ Avoid: When you need to know why validation failed (use `from` instead) const result = PositiveInt.from(userInput); if (!result.ok) { console.error(formatPositiveError(result.error)); }` | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`orNull`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#ornull) | [packages/common/src/Type.ts:315](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L315) |
| <a id="orthrow"></a> `orThrow` | `readonly` | (`value`) => `Readonly`\<`DrainOuterGeneric`\<\{ \[K in string \| number \| symbol\]: (\{ \[K in string \| number \| symbol\]: InferType\<Props\[K\]\> \} & \{ \[K in string \| number \| symbol\]?: (...)\[(...)\] extends OptionalType\<(...)\> ? InferType\<(...)\> : never \})\[K\] \}\>\> & `Readonly`\<`Record`\<`KeyT`, [`InferType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferType)\<`Value`\>\>\> | Creates `T` from an `Input` value, throwing an error if validation fails. Throws an Error with the Type validation error in its `cause` property, making it debuggable while avoiding the need for custom error messages. This is a convenience method that combines `from` with `getOrThrow`. **When to use:** - Configuration values that are guaranteed to be valid (e.g., hardcoded constants) - Application startup where failure should crash the program - As an alternative to assertions when the Type error in the thrown Error's `cause` provides sufficient debugging information - Test code with known valid inputs (when error message clarity is not critical; for better test error messages, use Vitest `schemaMatching` + `assert` with `.is()`) ### Example `// ✅ Good: Known valid constant const maxRetries = PositiveInt.orThrow(3); // ✅ Good: App configuration that should crash on invalid values const appName = SimpleName.orThrow("MyApp"); // ✅ Good: Instead of assert when Type error is clear enough // Context makes it obvious: count increments from non-negative value const currentCount = counts.get(id) ?? 0; const newCount = PositiveInt.orThrow(currentCount + 1); // ✅ Good: Test setup with known valid values const testUser = User.orThrow({ name: "Alice", age: 30 }); // ❌ Avoid: User input (use `from` instead) const userAge = PositiveInt.orThrow(userInput); // Could crash! // ✅ Better: Handle user input gracefully const ageResult = PositiveInt.from(userInput); if (!ageResult.ok) { // Handle validation error }` | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`orThrow`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#orthrow) | [packages/common/src/Type.ts:284](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L284) |
| <a id="parent"></a> `Parent` | `public` | `Readonly`\<`DrainOuterGeneric`\<\{ \[K in string \| number \| symbol\]: (\{ \[K in string \| number \| symbol\]: InferParent\<Props\[K\]\> \} & \{ \[K in string \| number \| symbol\]?: Props\[K\] extends OptionalType\<U\> ? InferParent\<U\> : never \})\[K\] \}\>\> & `Readonly`\<`Record`\<`KeyParent`, [`InferParent`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferParent)\<`Value`\>\>\> | The parent type. ### Example `type StringParent = typeof String.Parent;` | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`Parent`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#parent) | [packages/common/src/Type.ts:223](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L223) |
| <a id="parenterror"></a> `ParentError` | `public` | [`ObjectWithRecordError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/ObjectWithRecordError)\<\{ \[K in string \| number \| symbol\]: InferParentError\<Props\[K\]\> \}, `KeyParentError`, [`InferParentError`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferParentError)\<`Value`\>\> | The parent's error. ### Example `type StringParentError = typeof String.ParentError;` | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`ParentError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#parenterror) | [packages/common/src/Type.ts:225](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L225) |
| <a id="props-1"></a> `props` | `readonly` | `Props` | - | - | [packages/common/src/Type.ts:3151](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L3151) |
| <a id="record"></a> `record` | `readonly` | [`RecordType`](https://evolu.dev/docs/api-reference/common/Type/interfaces/RecordType)\<`KeyName`, `KeyT`, `KeyInput`, `KeyError`, `KeyParent`, `KeyParentError`, `Value`\> | - | - | [packages/common/src/Type.ts:3152](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L3152) |
| <a id="type"></a> `Type` | `readonly` | `Readonly`\<`DrainOuterGeneric`\<\{ \[K in string \| number \| symbol\]: (\{ \[K in string \| number \| symbol\]: InferType\<Props\[K\]\> \} & \{ \[K in string \| number \| symbol\]?: Props\[K\] extends OptionalType\<U\> ? InferType\<U\> : never \})\[K\] \}\>\> & `Readonly`\<`Record`\<`KeyT`, [`InferType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferType)\<`Value`\>\>\> | The type this Type resolves to. ### Example `type String = typeof String.Type;` | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#type) | [packages/common/src/Type.ts:364](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L364) |
OptionalType - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / OptionalType
# Interface: OptionalType\<T\>
Defined in: [packages/common/src/Type.ts:3887](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L3887)
Evolu [Type](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type) is like a type guard that returns typed errors (via
[Result](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result)) instead of throwing. We either get a safely typed value or a
composable typed error telling us exactly why validation failed.
Why another validation library?
- **Result-based error handling** – no exceptions for normal control flow.
- **Typed errors with decoupled formatters** – validation logic ≠ user
messages.
- **Consistent constraints via [Brand](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)** – every constraint becomes part
of the type.
- **Skippable validation** – parent validations can be skipped when already
proved by types.
- **Simple, top-down implementation** – readable source code from top to
bottom.
- **No user-land chaining DSL** – prepared for TC39 Hack pipes.
A distinctive feature of Evolu Type compared to other validation libraries is
that it returns typed errors rather than string messages. This allows
TypeScript to enforce that all validation errors are handled by type
checking, significantly improving the developer experience.
Evolu Type supports [Standard Schema](https://standardschema.dev/) for
interoperability with 40+ validation-compatible tools and frameworks.
### Base Types Quick Start
```ts
// Validate unknown values
const value: unknown = "hello";
const stringResult = String.fromUnknown(value);
if (!stringResult.ok) {
// console.error(formatStringError(stringResult.error));
return stringResult; // inside a function returning Result<string, _>
}
// Safe branch: value is now string
const upper = stringResult.value.toUpperCase();
// Type guard style
if (String.is(value)) {
// narrowed to string
}
// Composing: arrays & objects
const Numbers = array(Number); // ReadonlyArray<number>
const Point = object({ x: Number, y: Number });
Numbers.from([1, 2, 3]); // ok
Point.from({ x: 1, y: 2 }); // ok
Point.from({ x: 1, y: "2" }); // err -> nested Number error
```
### Branding Basics
Branding adds semantic meaning & constraints while preserving the runtime
shape:
```ts
const CurrencyCode = brand("CurrencyCode", String, (value) =>
/^[A-Z]{3}$/.test(value)
? ok(value)
: err<CurrencyCodeError>({ type: "CurrencyCode", value }),
);
type CurrencyCode = typeof CurrencyCode.Type; // string & Brand<"CurrencyCode">
interface CurrencyCodeError extends TypeError<"CurrencyCode"> {}
const formatCurrencyCodeError = createTypeErrorFormatter<CurrencyCodeError>(
(error) => `Invalid currency code: ${error.value}`,
);
const r = CurrencyCode.from("USD"); // ok("USD")
const e = CurrencyCode.from("usd"); // err(...)
```
See also reusable brand factories like `minLength`, `maxLength`, `trimmed`,
`positive`, `between`, etc.
### Objects & Optional Fields
```ts
const User = object({
name: NonEmptyTrimmedString100,
age: optional(PositiveInt),
});
type User = typeof User.Type;
User.from({ name: "Alice" }); // ok
User.from({ name: "Alice", age: -1 }); // err(PositiveInt)
```
### Deriving JSON String Types
```ts
const Person = object({
name: NonEmptyString50,
// Did you know that JSON.stringify converts NaN (a number) into null?
// To prevent this, use FiniteNumber.
age: FiniteNumber,
});
type Person = typeof Person.Type;
const [PersonJson, personToPersonJson, personJsonToPerson] = json(
Person,
"PersonJson",
);
// string & Brand<"PersonJson">
type PersonJson = typeof PersonJson.Type;
const person = Person.orThrow({
name: "Alice",
age: 30,
});
const personJson = personToPersonJson(person);
expect(personJsonToPerson(personJson)).toEqual(person);
```
### Error Formatting
Evolu separates validation logic from human-readable messages. There are two
layers:
1. Per-type formatters (e.g. `formatStringError`) – simple, focused, already
used earlier in the quick start example.
2. A unified formatter via `createFormatTypeError` – composes all built-in and
custom errors (including nested composite types) and lets us override
selected messages.
#### 1. Per-Type Formatter (recap)
```ts
const r = String.fromUnknown(42);
if (!r.ok) console.error(formatStringError(r.error));
```
#### 2. Unified Formatter with Overrides
```ts
// Override only what we care about; fall back to built-ins for the rest.
const formatTypeError = createFormatTypeError((error) => {
if (error.type === "MinLength") return `Min length is ${error.min}`;
});
const User = object({ name: NonEmptyTrimmedString100 });
const resultUser = User.from({ name: "" });
if (!resultUser.ok) console.error(formatTypeError(resultUser.error));
const badPoint = object({ x: Number, y: Number }).from({
x: 1,
y: "foo",
});
if (!badPoint.ok) console.error(formatTypeError(badPoint.error));
```
The unified formatter walks nested structures (object / array / record /
tuple / union) and applies overrides only where specified, greatly reducing
boilerplate when formatting complex validation errors.
### Tip
If necessary, write `globalThis.String` instead of `String` to avoid naming
clashes with native types.
### Design Decision: No Bidirectional Transformations
Evolu Type intentionally does not support bidirectional transformations. It
previously did, but supporting that while keeping typed error fidelity added
complexity that hurt readability & reliability. Most persistence pipelines
(e.g. SQLite) already require explicit mapping of query results, so implicit
reverse transforms would not buy much. We may revisit this if we can design a
minimal, 100% safe API that preserves simplicity.
### Prepared for TC39 Hack Pipes
Take a look how `SimplePassword` is defined:
```ts
export const SimplePassword = brand(
"SimplePassword",
minLength(8)(maxLength(64)(TrimmedString)),
);
```
Nested functions are often OK (if not, make a helper) and read well, but with
TC39 Hack pipes it would be clearer:
```ts
// TrimmedString
// |> minLength(8)(%)
// |> maxLength(64)(%)
// |> brand("SimplePassword", %)
```
Note `minLength` and `maxLength` are curried because they are factories.
## Extends
- [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type)\<`"Optional"`, [`InferType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferType)\<`T`\>, [`InferInput`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferInput)\<`T`\>, [`InferError`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferError)\<`T`\>, [`InferParent`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferParent)\<`T`\>, [`InferParentError`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferParentError)\<`T`\>\>
## Type Parameters
| Type Parameter |
| ----------------------------------------------------------------------------------- |
| `T` _extends_ [`AnyType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/AnyType) |
## Properties
| Property | Modifier | Type | Description | Inherited from | Defined in |
| ------------------------------------------------ | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="evolutypesymbol"></a> `[EvoluTypeSymbol]` | `readonly` | `true` | - | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`[EvoluTypeSymbol]`](/docs/api-reference/common/Type/interfaces/Type.mdx#evolutypesymbol) | [packages/common/src/Type.ts:353](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L353) |
| <a id="standard"></a> `~standard` | `readonly` | [`Props`](https://evolu.dev/docs/api-reference/common/Type/namespaces/StandardSchemaV1/interfaces/Props)\<[`InferInput`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferInput)\<`T`\>, [`InferType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferType)\<`T`\>\> | The Standard Schema properties. | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`~standard`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#standard) | [packages/common/src/Type.ts:4450](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L4450) |
| <a id="error"></a> `Error` | `public` | [`InferError`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferError)\<`T`\> | The specific error introduced by this Type. ### Example `type StringError = typeof String.Error;` | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`Error`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#error) | [packages/common/src/Type.ts:221](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L221) |
| <a id="errors"></a> `Errors` | `readonly` | \| [`InferError`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferError)\<`T`\> \| [`InferParentError`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferParentError)\<`T`\> | ### Example `type StringParentErrors = typeof String.Errors;` | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`Errors`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#errors) | [packages/common/src/Type.ts:417](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L417) |
| <a id="from"></a> `from` | `readonly` | (`value`) => [`Result`](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result)\<[`InferType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferType)\<`T`\>, \| [`InferError`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferError)\<`T`\> \| [`InferParentError`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferParentError)\<`T`\>\> | Creates `T` from an `Input` value. This is useful when we have a typed value. `from` is a typed alias of `fromUnknown`. | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`from`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#from) | [packages/common/src/Type.ts:236](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L236) |
| <a id="fromparent"></a> `fromParent` | `readonly` | (`value`) => [`Result`](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result)\<[`InferType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferType)\<`T`\>, [`InferError`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferError)\<`T`\>\> | Creates `T` from `Parent` type. This function skips parent Types validations when we have already partially validated value. | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`fromParent`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#fromparent) | [packages/common/src/Type.ts:330](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L330) |
| <a id="fromunknown"></a> `fromUnknown` | `readonly` | (`value`) => [`Result`](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result)\<[`InferType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferType)\<`T`\>, \| [`InferError`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferError)\<`T`\> \| [`InferParentError`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferParentError)\<`T`\>\> | Creates `T` from an unknown value. This is useful when a value is unknown. | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`fromUnknown`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#fromunknown) | [packages/common/src/Type.ts:322](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L322) |
| <a id="input"></a> `Input` | `public` | [`InferInput`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferInput)\<`T`\> | The type expected by `from` and `fromUnknown`. ### Example `type StringInput = typeof String.Input;` | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`Input`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#input) | [packages/common/src/Type.ts:219](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L219) |
| <a id="is"></a> `is` | `readonly` | [`Refinement`](https://evolu.dev/docs/api-reference/common/Types/type-aliases/Refinement)\<`unknown`, [`InferType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferType)\<`T`\>\> | A **type guard** that checks whether an unknown value satisfies the [Type](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type). ### Example `const value: unknown = "hello"; if (String.is(value)) { // TypeScript now knows `value`is a`string` here. console.log("This is a valid string!"); } const strings: unknown[] = [1, "hello", true, "world"]; const filteredStrings = strings.filter(String.is); console.log(filteredStrings); // ["hello", "world"]` | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`is`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#is) | [packages/common/src/Type.ts:351](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L351) |
| <a id="name"></a> `name` | `readonly` | `"Optional"` | - | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`name`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#name-1) | [packages/common/src/Type.ts:227](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L227) |
| <a id="ornull"></a> `orNull` | `readonly` | (`value`) => \| [`InferType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferType)\<`T`\> \| `null` | Creates `T` from an `Input` value, returning `null` if validation fails. This is a convenience method that combines `from` with `getOrNull`. **When to use:** - When you need to convert a validation result to a nullable value - When the error is not important and you just want the value or nothing ### Example `// ✅ Good: Optional user input const age = PositiveInt.orNull(userInput); if (age != null) { console.log("Valid age:", age); } // ✅ Good: Default fallback const maxRetries = PositiveInt.orNull(config.retries) ?? 3; // ❌ Avoid: When you need to know why validation failed (use `from` instead) const result = PositiveInt.from(userInput); if (!result.ok) { console.error(formatPositiveError(result.error)); }` | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`orNull`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#ornull) | [packages/common/src/Type.ts:315](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L315) |
| <a id="orthrow"></a> `orThrow` | `readonly` | (`value`) => [`InferType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferType) | Creates `T` from an `Input` value, throwing an error if validation fails. Throws an Error with the Type validation error in its `cause` property, making it debuggable while avoiding the need for custom error messages. This is a convenience method that combines `from` with `getOrThrow`. **When to use:** - Configuration values that are guaranteed to be valid (e.g., hardcoded constants) - Application startup where failure should crash the program - As an alternative to assertions when the Type error in the thrown Error's `cause` provides sufficient debugging information - Test code with known valid inputs (when error message clarity is not critical; for better test error messages, use Vitest `schemaMatching` + `assert` with `.is()`) ### Example `// ✅ Good: Known valid constant const maxRetries = PositiveInt.orThrow(3); // ✅ Good: App configuration that should crash on invalid values const appName = SimpleName.orThrow("MyApp"); // ✅ Good: Instead of assert when Type error is clear enough // Context makes it obvious: count increments from non-negative value const currentCount = counts.get(id) ?? 0; const newCount = PositiveInt.orThrow(currentCount + 1); // ✅ Good: Test setup with known valid values const testUser = User.orThrow({ name: "Alice", age: 30 }); // ❌ Avoid: User input (use `from` instead) const userAge = PositiveInt.orThrow(userInput); // Could crash! // ✅ Better: Handle user input gracefully const ageResult = PositiveInt.from(userInput); if (!ageResult.ok) { // Handle validation error }` | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`orThrow`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#orthrow) | [packages/common/src/Type.ts:284](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L284) |
| <a id="parent"></a> `parent` | `readonly` | `T` | - | - | [packages/common/src/Type.ts:3895](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L3895) |
| <a id="parent-1"></a> `Parent` | `public` | [`InferParent`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferParent)\<`T`\> | The parent type. ### Example `type StringParent = typeof String.Parent;` | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`Parent`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#parent) | [packages/common/src/Type.ts:223](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L223) |
| <a id="parenterror"></a> `ParentError` | `public` | [`InferParentError`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferParentError)\<`T`\> | The parent's error. ### Example `type StringParentError = typeof String.ParentError;` | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`ParentError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#parenterror) | [packages/common/src/Type.ts:225](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L225) |
| <a id="type"></a> `Type` | `readonly` | [`InferType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferType) | The type this Type resolves to. ### Example `type String = typeof String.Type;` | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#type) | [packages/common/src/Type.ts:364](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L364) |
PositiveError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / PositiveError
# Interface: PositiveError
Defined in: [packages/common/src/Type.ts:1821](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1821)
## Extends
- [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError)\<`"Positive"`\>
## Properties
| Property | Modifier | Type | Description | Inherited from | Defined in |
| -------------------------- | ---------- | ------------ | -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="type"></a> `type` | `readonly` | `"Positive"` | - | [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError).[`type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError.mdx#type) | [packages/common/src/Type.ts:428](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L428) |
| <a id="value"></a> `value` | `readonly` | `unknown` | The value that was received and caused the error. Provides additional context for debugging and validation feedback. | [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError).[`value`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError.mdx#value) | [packages/common/src/Type.ts:434](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L434) |
RecordError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / RecordError
# Interface: RecordError\<KeyError, ValueError\>
Defined in: [packages/common/src/Type.ts:2701](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L2701)
## Extends
- [`TypeErrorWithReason`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeErrorWithReason)\<`"Record"`,
\| \{
`kind`: `"NotRecord"`;
\}
\| \{
`error`: `KeyError`;
`key`: `unknown`;
`kind`: `"Key"`;
\}
\| \{
`error`: `ValueError`;
`key`: `unknown`;
`kind`: `"Value"`;
\}\>
## Type Parameters
| Type Parameter | Default type |
| ---------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
| `KeyError` _extends_ [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError) | [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError) |
| `ValueError` _extends_ [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError) | [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError) |
## Properties
| Property | Modifier | Type | Description | Inherited from | Defined in |
| ---------------------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="reason"></a> `reason` | `readonly` | \| \{ `kind`: `"NotRecord"`; \} \| \{ `error`: `KeyError`; `key`: `unknown`; `kind`: `"Key"`; \} \| \{ `error`: `ValueError`; `key`: `unknown`; `kind`: `"Value"`; \} | The detailed reason for the error, represented as a tagged union. | [`TypeErrorWithReason`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeErrorWithReason).[`reason`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeErrorWithReason.mdx#reason-1) | [packages/common/src/Type.ts:444](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L444) |
| <a id="type"></a> `type` | `readonly` | `"Record"` | - | [`TypeErrorWithReason`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeErrorWithReason).[`type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeErrorWithReason.mdx#type) | [packages/common/src/Type.ts:428](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L428) |
| <a id="value"></a> `value` | `readonly` | `unknown` | The value that was received and caused the error. Provides additional context for debugging and validation feedback. | [`TypeErrorWithReason`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeErrorWithReason).[`value`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeErrorWithReason.mdx#value) | [packages/common/src/Type.ts:434](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L434) |
RecordType - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / RecordType
# Interface: RecordType\<KeyName, KeyT, KeyInput, KeyError, KeyParent, KeyParentError, Value\>
Defined in: [packages/common/src/Type.ts:2674](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L2674)
RecordType extends [Type](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type) with additional `key` and `value` properties
for reflection.
## Extends
- [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type)\<`"Record"`, `Readonly`\<`Record`\<`KeyT`, [`InferType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferType)\<`Value`\>\>\>, `Readonly`\<`Record`\<`KeyInput`, [`InferInput`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferInput)\<`Value`\>\>\>, [`RecordError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/RecordError)\<`KeyError`, [`InferError`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferError)\<`Value`\>\>, `Readonly`\<`Record`\<`KeyParent`, [`InferParent`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferParent)\<`Value`\>\>\>, [`RecordError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/RecordError)\<`KeyParentError`, [`InferParentError`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferParentError)\<`Value`\>\>\>
## Type Parameters
| Type Parameter | Default type |
| -------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
| `KeyName` _extends_ [`TypeName`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/TypeName) | - |
| `KeyT` _extends_ `string` | - |
| `KeyInput` _extends_ `string` | - |
| `KeyError` _extends_ [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError) | - |
| `KeyParent` _extends_ `string` | - |
| `KeyParentError` _extends_ [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError) | - |
| `Value` _extends_ [`AnyType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/AnyType) | [`AnyType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/AnyType) |
## Properties
| Property | Modifier | Type | Description | Inherited from | Defined in |
| ------------------------------------------------ | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="evolutypesymbol"></a> `[EvoluTypeSymbol]` | `readonly` | `true` | - | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`[EvoluTypeSymbol]`](/docs/api-reference/common/Type/interfaces/Type.mdx#evolutypesymbol) | [packages/common/src/Type.ts:353](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L353) |
| <a id="standard"></a> `~standard` | `readonly` | [`Props`](https://evolu.dev/docs/api-reference/common/Type/namespaces/StandardSchemaV1/interfaces/Props)\<`Readonly`\<`Record`\<`KeyInput`, [`InferInput`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferInput)\<`Value`\>\>\>, `Readonly`\<`Record`\<`KeyT`, [`InferType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferType)\<`Value`\>\>\>\> | The Standard Schema properties. | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`~standard`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#standard) | [packages/common/src/Type.ts:4450](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L4450) |
| <a id="error"></a> `Error` | `public` | [`RecordError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/RecordError)\<`KeyError`, [`InferError`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferError)\<`Value`\>\> | The specific error introduced by this Type. ### Example `type StringError = typeof String.Error;` | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`Error`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#error) | [packages/common/src/Type.ts:221](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L221) |
| <a id="errors"></a> `Errors` | `readonly` | \| [`RecordError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/RecordError)\<`KeyError`, [`InferError`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferError)\<`Value`\>\> \| [`RecordError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/RecordError)\<`KeyParentError`, [`InferParentError`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferParentError)\<`Value`\>\> | ### Example `type StringParentErrors = typeof String.Errors;` | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`Errors`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#errors) | [packages/common/src/Type.ts:417](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L417) |
| <a id="from"></a> `from` | `readonly` | (`value`) => [`Result`](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result)\<`Readonly`\<`Record`\<`KeyT`, [`InferType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferType)\<`Value`\>\>\>, \| [`RecordError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/RecordError)\<`KeyError`, [`InferError`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferError)\<`Value`\>\> \| [`RecordError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/RecordError)\<`KeyParentError`, [`InferParentError`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferParentError)\<`Value`\>\>\> | Creates `T` from an `Input` value. This is useful when we have a typed value. `from` is a typed alias of `fromUnknown`. | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`from`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#from) | [packages/common/src/Type.ts:236](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L236) |
| <a id="fromparent"></a> `fromParent` | `readonly` | (`value`) => [`Result`](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result)\<`Readonly`\<`Record`\<`KeyT`, [`InferType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferType)\<`Value`\>\>\>, [`RecordError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/RecordError)\<`KeyError`, [`InferError`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferError)\<`Value`\>\>\> | Creates `T` from `Parent` type. This function skips parent Types validations when we have already partially validated value. | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`fromParent`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#fromparent) | [packages/common/src/Type.ts:330](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L330) |
| <a id="fromunknown"></a> `fromUnknown` | `readonly` | (`value`) => [`Result`](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result)\<`Readonly`\<`Record`\<`KeyT`, [`InferType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferType)\<`Value`\>\>\>, \| [`RecordError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/RecordError)\<`KeyError`, [`InferError`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferError)\<`Value`\>\> \| [`RecordError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/RecordError)\<`KeyParentError`, [`InferParentError`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferParentError)\<`Value`\>\>\> | Creates `T` from an unknown value. This is useful when a value is unknown. | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`fromUnknown`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#fromunknown) | [packages/common/src/Type.ts:322](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L322) |
| <a id="input"></a> `Input` | `public` | `Readonly`\<`Record`\<`KeyInput`, [`InferInput`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferInput)\<`Value`\>\>\> | The type expected by `from` and `fromUnknown`. ### Example `type StringInput = typeof String.Input;` | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`Input`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#input) | [packages/common/src/Type.ts:219](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L219) |
| <a id="is"></a> `is` | `readonly` | [`Refinement`](https://evolu.dev/docs/api-reference/common/Types/type-aliases/Refinement)\<`unknown`, `Readonly`\<`Record`\<`KeyT`, [`InferType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferType)\<`Value`\>\>\>\> | A **type guard** that checks whether an unknown value satisfies the [Type](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type). ### Example `const value: unknown = "hello"; if (String.is(value)) { // TypeScript now knows `value`is a`string` here. console.log("This is a valid string!"); } const strings: unknown[] = [1, "hello", true, "world"]; const filteredStrings = strings.filter(String.is); console.log(filteredStrings); // ["hello", "world"]` | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`is`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#is) | [packages/common/src/Type.ts:351](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L351) |
| <a id="key"></a> `key` | `readonly` | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type)\<`KeyName`, `KeyT`, `KeyInput`, `KeyError`, `KeyParent`, `KeyParentError`\> | - | - | [packages/common/src/Type.ts:2690](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L2690) |
| <a id="name"></a> `name` | `readonly` | `"Record"` | - | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`name`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#name-1) | [packages/common/src/Type.ts:227](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L227) |
| <a id="ornull"></a> `orNull` | `readonly` | (`value`) => \| `Readonly`\<`Record`\<`KeyT`, [`InferType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferType)\<`Value`\>\>\> \| `null` | Creates `T` from an `Input` value, returning `null` if validation fails. This is a convenience method that combines `from` with `getOrNull`. **When to use:** - When you need to convert a validation result to a nullable value - When the error is not important and you just want the value or nothing ### Example `// ✅ Good: Optional user input const age = PositiveInt.orNull(userInput); if (age != null) { console.log("Valid age:", age); } // ✅ Good: Default fallback const maxRetries = PositiveInt.orNull(config.retries) ?? 3; // ❌ Avoid: When you need to know why validation failed (use `from` instead) const result = PositiveInt.from(userInput); if (!result.ok) { console.error(formatPositiveError(result.error)); }` | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`orNull`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#ornull) | [packages/common/src/Type.ts:315](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L315) |
| <a id="orthrow"></a> `orThrow` | `readonly` | (`value`) => `T` | Creates `T` from an `Input` value, throwing an error if validation fails. Throws an Error with the Type validation error in its `cause` property, making it debuggable while avoiding the need for custom error messages. This is a convenience method that combines `from` with `getOrThrow`. **When to use:** - Configuration values that are guaranteed to be valid (e.g., hardcoded constants) - Application startup where failure should crash the program - As an alternative to assertions when the Type error in the thrown Error's `cause` provides sufficient debugging information - Test code with known valid inputs (when error message clarity is not critical; for better test error messages, use Vitest `schemaMatching` + `assert` with `.is()`) ### Example `// ✅ Good: Known valid constant const maxRetries = PositiveInt.orThrow(3); // ✅ Good: App configuration that should crash on invalid values const appName = SimpleName.orThrow("MyApp"); // ✅ Good: Instead of assert when Type error is clear enough // Context makes it obvious: count increments from non-negative value const currentCount = counts.get(id) ?? 0; const newCount = PositiveInt.orThrow(currentCount + 1); // ✅ Good: Test setup with known valid values const testUser = User.orThrow({ name: "Alice", age: 30 }); // ❌ Avoid: User input (use `from` instead) const userAge = PositiveInt.orThrow(userInput); // Could crash! // ✅ Better: Handle user input gracefully const ageResult = PositiveInt.from(userInput); if (!ageResult.ok) { // Handle validation error }` | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`orThrow`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#orthrow) | [packages/common/src/Type.ts:284](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L284) |
| <a id="parent"></a> `Parent` | `public` | `Readonly`\<`Record`\<`KeyParent`, [`InferParent`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferParent)\<`Value`\>\>\> | The parent type. ### Example `type StringParent = typeof String.Parent;` | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`Parent`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#parent) | [packages/common/src/Type.ts:223](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L223) |
| <a id="parenterror"></a> `ParentError` | `public` | [`RecordError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/RecordError)\<`KeyParentError`, [`InferParentError`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferParentError)\<`Value`\>\> | The parent's error. ### Example `type StringParentError = typeof String.ParentError;` | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`ParentError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#parenterror) | [packages/common/src/Type.ts:225](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L225) |
| <a id="type"></a> `Type` | `readonly` | `T` | The type this Type resolves to. ### Example `type String = typeof String.Type;` | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#type) | [packages/common/src/Type.ts:364](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L364) |
| <a id="value-1"></a> `value` | `readonly` | `Value` | - | - | [packages/common/src/Type.ts:2698](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L2698) |
RecursiveType - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / RecursiveType
# Interface: RecursiveType\<ParentType\>
Defined in: [packages/common/src/Type.ts:3392](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L3392)
Evolu [Type](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type) is like a type guard that returns typed errors (via
[Result](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result)) instead of throwing. We either get a safely typed value or a
composable typed error telling us exactly why validation failed.
Why another validation library?
- **Result-based error handling** – no exceptions for normal control flow.
- **Typed errors with decoupled formatters** – validation logic ≠ user
messages.
- **Consistent constraints via [Brand](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)** – every constraint becomes part
of the type.
- **Skippable validation** – parent validations can be skipped when already
proved by types.
- **Simple, top-down implementation** – readable source code from top to
bottom.
- **No user-land chaining DSL** – prepared for TC39 Hack pipes.
A distinctive feature of Evolu Type compared to other validation libraries is
that it returns typed errors rather than string messages. This allows
TypeScript to enforce that all validation errors are handled by type
checking, significantly improving the developer experience.
Evolu Type supports [Standard Schema](https://standardschema.dev/) for
interoperability with 40+ validation-compatible tools and frameworks.
### Base Types Quick Start
```ts
// Validate unknown values
const value: unknown = "hello";
const stringResult = String.fromUnknown(value);
if (!stringResult.ok) {
// console.error(formatStringError(stringResult.error));
return stringResult; // inside a function returning Result<string, _>
}
// Safe branch: value is now string
const upper = stringResult.value.toUpperCase();
// Type guard style
if (String.is(value)) {
// narrowed to string
}
// Composing: arrays & objects
const Numbers = array(Number); // ReadonlyArray<number>
const Point = object({ x: Number, y: Number });
Numbers.from([1, 2, 3]); // ok
Point.from({ x: 1, y: 2 }); // ok
Point.from({ x: 1, y: "2" }); // err -> nested Number error
```
### Branding Basics
Branding adds semantic meaning & constraints while preserving the runtime
shape:
```ts
const CurrencyCode = brand("CurrencyCode", String, (value) =>
/^[A-Z]{3}$/.test(value)
? ok(value)
: err<CurrencyCodeError>({ type: "CurrencyCode", value }),
);
type CurrencyCode = typeof CurrencyCode.Type; // string & Brand<"CurrencyCode">
interface CurrencyCodeError extends TypeError<"CurrencyCode"> {}
const formatCurrencyCodeError = createTypeErrorFormatter<CurrencyCodeError>(
(error) => `Invalid currency code: ${error.value}`,
);
const r = CurrencyCode.from("USD"); // ok("USD")
const e = CurrencyCode.from("usd"); // err(...)
```
See also reusable brand factories like `minLength`, `maxLength`, `trimmed`,
`positive`, `between`, etc.
### Objects & Optional Fields
```ts
const User = object({
name: NonEmptyTrimmedString100,
age: optional(PositiveInt),
});
type User = typeof User.Type;
User.from({ name: "Alice" }); // ok
User.from({ name: "Alice", age: -1 }); // err(PositiveInt)
```
### Deriving JSON String Types
```ts
const Person = object({
name: NonEmptyString50,
// Did you know that JSON.stringify converts NaN (a number) into null?
// To prevent this, use FiniteNumber.
age: FiniteNumber,
});
type Person = typeof Person.Type;
const [PersonJson, personToPersonJson, personJsonToPerson] = json(
Person,
"PersonJson",
);
// string & Brand<"PersonJson">
type PersonJson = typeof PersonJson.Type;
const person = Person.orThrow({
name: "Alice",
age: 30,
});
const personJson = personToPersonJson(person);
expect(personJsonToPerson(personJson)).toEqual(person);
```
### Error Formatting
Evolu separates validation logic from human-readable messages. There are two
layers:
1. Per-type formatters (e.g. `formatStringError`) – simple, focused, already
used earlier in the quick start example.
2. A unified formatter via `createFormatTypeError` – composes all built-in and
custom errors (including nested composite types) and lets us override
selected messages.
#### 1. Per-Type Formatter (recap)
```ts
const r = String.fromUnknown(42);
if (!r.ok) console.error(formatStringError(r.error));
```
#### 2. Unified Formatter with Overrides
```ts
// Override only what we care about; fall back to built-ins for the rest.
const formatTypeError = createFormatTypeError((error) => {
if (error.type === "MinLength") return `Min length is ${error.min}`;
});
const User = object({ name: NonEmptyTrimmedString100 });
const resultUser = User.from({ name: "" });
if (!resultUser.ok) console.error(formatTypeError(resultUser.error));
const badPoint = object({ x: Number, y: Number }).from({
x: 1,
y: "foo",
});
if (!badPoint.ok) console.error(formatTypeError(badPoint.error));
```
The unified formatter walks nested structures (object / array / record /
tuple / union) and applies overrides only where specified, greatly reducing
boilerplate when formatting complex validation errors.
### Tip
If necessary, write `globalThis.String` instead of `String` to avoid naming
clashes with native types.
### Design Decision: No Bidirectional Transformations
Evolu Type intentionally does not support bidirectional transformations. It
previously did, but supporting that while keeping typed error fidelity added
complexity that hurt readability & reliability. Most persistence pipelines
(e.g. SQLite) already require explicit mapping of query results, so implicit
reverse transforms would not buy much. We may revisit this if we can design a
minimal, 100% safe API that preserves simplicity.
### Prepared for TC39 Hack Pipes
Take a look how `SimplePassword` is defined:
```ts
export const SimplePassword = brand(
"SimplePassword",
minLength(8)(maxLength(64)(TrimmedString)),
);
```
Nested functions are often OK (if not, make a helper) and read well, but with
TC39 Hack pipes it would be clearer:
```ts
// TrimmedString
// |> minLength(8)(%)
// |> maxLength(64)(%)
// |> brand("SimplePassword", %)
```
Note `minLength` and `maxLength` are curried because they are factories.
## Extends
- [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type)\<`"Recursive"`, [`InferType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferType)\<`ParentType`\>, [`InferInput`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferInput)\<`ParentType`\>, [`InferError`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferError)\<`ParentType`\>, [`InferParent`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferParent)\<`ParentType`\>, [`InferParentError`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferParentError)\<`ParentType`\>\>
## Type Parameters
| Type Parameter |
| -------------------------------------------------------------------------------------------- |
| `ParentType` _extends_ [`AnyType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/AnyType) |
## Properties
| Property | Modifier | Type | Description | Inherited from | Defined in |
| ------------------------------------------------ | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="evolutypesymbol"></a> `[EvoluTypeSymbol]` | `readonly` | `true` | - | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`[EvoluTypeSymbol]`](/docs/api-reference/common/Type/interfaces/Type.mdx#evolutypesymbol) | [packages/common/src/Type.ts:353](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L353) |
| <a id="standard"></a> `~standard` | `readonly` | [`Props`](https://evolu.dev/docs/api-reference/common/Type/namespaces/StandardSchemaV1/interfaces/Props)\<[`InferInput`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferInput)\<`ParentType`\>, [`InferType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferType)\<`ParentType`\>\> | The Standard Schema properties. | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`~standard`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#standard) | [packages/common/src/Type.ts:4450](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L4450) |
| <a id="error"></a> `Error` | `public` | [`InferError`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferError)\<`ParentType`\> | The specific error introduced by this Type. ### Example `type StringError = typeof String.Error;` | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`Error`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#error) | [packages/common/src/Type.ts:221](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L221) |
| <a id="errors"></a> `Errors` | `readonly` | \| [`InferError`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferError)\<`ParentType`\> \| [`InferParentError`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferParentError)\<`ParentType`\> | ### Example `type StringParentErrors = typeof String.Errors;` | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`Errors`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#errors) | [packages/common/src/Type.ts:417](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L417) |
| <a id="from"></a> `from` | `readonly` | (`value`) => [`Result`](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result)\<[`InferType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferType)\<`ParentType`\>, \| [`InferError`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferError)\<`ParentType`\> \| [`InferParentError`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferParentError)\<`ParentType`\>\> | Creates `T` from an `Input` value. This is useful when we have a typed value. `from` is a typed alias of `fromUnknown`. | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`from`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#from) | [packages/common/src/Type.ts:236](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L236) |
| <a id="fromparent"></a> `fromParent` | `readonly` | (`value`) => [`Result`](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result)\<[`InferType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferType)\<`ParentType`\>, [`InferError`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferError)\<`ParentType`\>\> | Creates `T` from `Parent` type. This function skips parent Types validations when we have already partially validated value. | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`fromParent`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#fromparent) | [packages/common/src/Type.ts:330](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L330) |
| <a id="fromunknown"></a> `fromUnknown` | `readonly` | (`value`) => [`Result`](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result)\<[`InferType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferType)\<`ParentType`\>, \| [`InferError`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferError)\<`ParentType`\> \| [`InferParentError`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferParentError)\<`ParentType`\>\> | Creates `T` from an unknown value. This is useful when a value is unknown. | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`fromUnknown`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#fromunknown) | [packages/common/src/Type.ts:322](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L322) |
| <a id="input"></a> `Input` | `public` | [`InferInput`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferInput)\<`ParentType`\> | The type expected by `from` and `fromUnknown`. ### Example `type StringInput = typeof String.Input;` | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`Input`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#input) | [packages/common/src/Type.ts:219](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L219) |
| <a id="is"></a> `is` | `readonly` | [`Refinement`](https://evolu.dev/docs/api-reference/common/Types/type-aliases/Refinement)\<`unknown`, [`InferType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferType)\<`ParentType`\>\> | A **type guard** that checks whether an unknown value satisfies the [Type](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type). ### Example `const value: unknown = "hello"; if (String.is(value)) { // TypeScript now knows `value`is a`string` here. console.log("This is a valid string!"); } const strings: unknown[] = [1, "hello", true, "world"]; const filteredStrings = strings.filter(String.is); console.log(filteredStrings); // ["hello", "world"]` | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`is`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#is) | [packages/common/src/Type.ts:351](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L351) |
| <a id="name"></a> `name` | `readonly` | `"Recursive"` | - | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`name`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#name-1) | [packages/common/src/Type.ts:227](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L227) |
| <a id="ornull"></a> `orNull` | `readonly` | (`value`) => \| [`InferType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferType)\<`ParentType`\> \| `null` | Creates `T` from an `Input` value, returning `null` if validation fails. This is a convenience method that combines `from` with `getOrNull`. **When to use:** - When you need to convert a validation result to a nullable value - When the error is not important and you just want the value or nothing ### Example `// ✅ Good: Optional user input const age = PositiveInt.orNull(userInput); if (age != null) { console.log("Valid age:", age); } // ✅ Good: Default fallback const maxRetries = PositiveInt.orNull(config.retries) ?? 3; // ❌ Avoid: When you need to know why validation failed (use `from` instead) const result = PositiveInt.from(userInput); if (!result.ok) { console.error(formatPositiveError(result.error)); }` | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`orNull`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#ornull) | [packages/common/src/Type.ts:315](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L315) |
| <a id="orthrow"></a> `orThrow` | `readonly` | (`value`) => [`InferType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferType) | Creates `T` from an `Input` value, throwing an error if validation fails. Throws an Error with the Type validation error in its `cause` property, making it debuggable while avoiding the need for custom error messages. This is a convenience method that combines `from` with `getOrThrow`. **When to use:** - Configuration values that are guaranteed to be valid (e.g., hardcoded constants) - Application startup where failure should crash the program - As an alternative to assertions when the Type error in the thrown Error's `cause` provides sufficient debugging information - Test code with known valid inputs (when error message clarity is not critical; for better test error messages, use Vitest `schemaMatching` + `assert` with `.is()`) ### Example `// ✅ Good: Known valid constant const maxRetries = PositiveInt.orThrow(3); // ✅ Good: App configuration that should crash on invalid values const appName = SimpleName.orThrow("MyApp"); // ✅ Good: Instead of assert when Type error is clear enough // Context makes it obvious: count increments from non-negative value const currentCount = counts.get(id) ?? 0; const newCount = PositiveInt.orThrow(currentCount + 1); // ✅ Good: Test setup with known valid values const testUser = User.orThrow({ name: "Alice", age: 30 }); // ❌ Avoid: User input (use `from` instead) const userAge = PositiveInt.orThrow(userInput); // Could crash! // ✅ Better: Handle user input gracefully const ageResult = PositiveInt.from(userInput); if (!ageResult.ok) { // Handle validation error }` | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`orThrow`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#orthrow) | [packages/common/src/Type.ts:284](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L284) |
| <a id="parent"></a> `Parent` | `public` | [`InferParent`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferParent)\<`ParentType`\> | The parent type. ### Example `type StringParent = typeof String.Parent;` | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`Parent`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#parent) | [packages/common/src/Type.ts:223](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L223) |
| <a id="parenterror"></a> `ParentError` | `public` | [`InferParentError`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferParentError)\<`ParentType`\> | The parent's error. ### Example `type StringParentError = typeof String.ParentError;` | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`ParentError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#parenterror) | [packages/common/src/Type.ts:225](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L225) |
| <a id="type"></a> `Type` | `readonly` | [`InferType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferType) | The type this Type resolves to. ### Example `type String = typeof String.Type;` | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#type) | [packages/common/src/Type.ts:364](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L364) |
## Methods
### getParentType()
```ts
getParentType(): ParentType;
```
Defined in: [packages/common/src/Type.ts:3400](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L3400)
#### Returns
`ParentType`
RegexError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / RegexError
# Interface: RegexError\<Name\>
Defined in: [packages/common/src/Type.ts:1395](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1395)
## Extends
- [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError)\<`"Regex"`\>
## Type Parameters
| Type Parameter | Default type |
| ---------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
| `Name` _extends_ [`TypeName`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/TypeName) | [`TypeName`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/TypeName) |
## Properties
| Property | Modifier | Type | Description | Inherited from | Defined in |
| ------------------------------ | ---------- | --------- | -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="name-1"></a> `name` | `readonly` | `Name` | - | - | [packages/common/src/Type.ts:1398](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1398) |
| <a id="pattern"></a> `pattern` | `readonly` | `RegExp` | - | - | [packages/common/src/Type.ts:1399](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1399) |
| <a id="type"></a> `type` | `readonly` | `"Regex"` | - | [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError).[`type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError.mdx#type) | [packages/common/src/Type.ts:428](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L428) |
| <a id="value"></a> `value` | `readonly` | `unknown` | The value that was received and caused the error. Provides additional context for debugging and validation feedback. | [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError).[`value`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError.mdx#value) | [packages/common/src/Type.ts:434](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L434) |
SetError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / SetError
# Interface: SetError\<Error\>
Defined in: [packages/common/src/Type.ts:2498](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L2498)
## Extends
- [`TypeErrorWithReason`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeErrorWithReason)\<`"Set"`,
\| \{
`kind`: `"NotSet"`;
\}
\| \{
`error`: `Error`;
`index`: `number`;
`kind`: `"Element"`;
\}\>
## Type Parameters
| Type Parameter | Default type |
| ----------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
| `Error` _extends_ [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError) | [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError) |
## Properties
| Property | Modifier | Type | Description | Inherited from | Defined in |
| ---------------------------- | ---------- | ----------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="reason"></a> `reason` | `readonly` | \| \{ `kind`: `"NotSet"`; \} \| \{ `error`: `Error`; `index`: `number`; `kind`: `"Element"`; \} | The detailed reason for the error, represented as a tagged union. | [`TypeErrorWithReason`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeErrorWithReason).[`reason`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeErrorWithReason.mdx#reason-1) | [packages/common/src/Type.ts:444](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L444) |
| <a id="type"></a> `type` | `readonly` | `"Set"` | - | [`TypeErrorWithReason`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeErrorWithReason).[`type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeErrorWithReason.mdx#type) | [packages/common/src/Type.ts:428](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L428) |
| <a id="value"></a> `value` | `readonly` | `unknown` | The value that was received and caused the error. Provides additional context for debugging and validation feedback. | [`TypeErrorWithReason`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeErrorWithReason).[`value`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeErrorWithReason.mdx#value) | [packages/common/src/Type.ts:434](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L434) |
SetType - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / SetType
# Interface: SetType\<ElementType\>
Defined in: [packages/common/src/Type.ts:2487](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L2487)
SetType extends Type with an additional `element` property for reflection.
## Extends
- [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type)\<`"Set"`, `ReadonlySet`\<[`InferType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferType)\<`ElementType`\>\>, `ReadonlySet`\<[`InferInput`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferInput)\<`ElementType`\>\>, [`SetError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/SetError)\<[`InferError`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferError)\<`ElementType`\>\>, `ReadonlySet`\<[`InferParent`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferParent)\<`ElementType`\>\>, [`SetError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/SetError)\<[`InferParentError`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferParentError)\<`ElementType`\>\>\>
## Type Parameters
| Type Parameter |
| --------------------------------------------------------------------------------------------- |
| `ElementType` _extends_ [`AnyType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/AnyType) |
## Properties
| Property | Modifier | Type | Description | Inherited from | Defined in |
| ------------------------------------------------ | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="evolutypesymbol"></a> `[EvoluTypeSymbol]` | `readonly` | `true` | - | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`[EvoluTypeSymbol]`](/docs/api-reference/common/Type/interfaces/Type.mdx#evolutypesymbol) | [packages/common/src/Type.ts:353](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L353) |
| <a id="standard"></a> `~standard` | `readonly` | [`Props`](https://evolu.dev/docs/api-reference/common/Type/namespaces/StandardSchemaV1/interfaces/Props)\<`ReadonlySet`\<[`InferInput`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferInput)\<`ElementType`\>\>, `ReadonlySet`\<[`InferType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferType)\<`ElementType`\>\>\> | The Standard Schema properties. | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`~standard`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#standard) | [packages/common/src/Type.ts:4450](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L4450) |
| <a id="element"></a> `element` | `readonly` | `ElementType` | - | - | [packages/common/src/Type.ts:2495](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L2495) |
| <a id="error"></a> `Error` | `public` | [`SetError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/SetError)\<[`InferError`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferError)\<`ElementType`\>\> | The specific error introduced by this Type. ### Example `type StringError = typeof String.Error;` | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`Error`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#error) | [packages/common/src/Type.ts:221](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L221) |
| <a id="errors"></a> `Errors` | `readonly` | \| [`SetError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/SetError)\<[`InferError`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferError)\<`ElementType`\>\> \| [`SetError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/SetError)\<[`InferParentError`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferParentError)\<`ElementType`\>\> | ### Example `type StringParentErrors = typeof String.Errors;` | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`Errors`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#errors) | [packages/common/src/Type.ts:417](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L417) |
| <a id="from"></a> `from` | `readonly` | (`value`) => [`Result`](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result)\<`ReadonlySet`\<[`InferType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferType)\<`ElementType`\>\>, \| [`SetError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/SetError)\<[`InferError`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferError)\<`ElementType`\>\> \| [`SetError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/SetError)\<[`InferParentError`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferParentError)\<`ElementType`\>\>\> | Creates `T` from an `Input` value. This is useful when we have a typed value. `from` is a typed alias of `fromUnknown`. | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`from`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#from) | [packages/common/src/Type.ts:236](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L236) |
| <a id="fromparent"></a> `fromParent` | `readonly` | (`value`) => [`Result`](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result)\<`ReadonlySet`\<[`InferType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferType)\<`ElementType`\>\>, [`SetError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/SetError)\<[`InferError`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferError)\<`ElementType`\>\>\> | Creates `T` from `Parent` type. This function skips parent Types validations when we have already partially validated value. | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`fromParent`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#fromparent) | [packages/common/src/Type.ts:330](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L330) |
| <a id="fromunknown"></a> `fromUnknown` | `readonly` | (`value`) => [`Result`](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result)\<`ReadonlySet`\<[`InferType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferType)\<`ElementType`\>\>, \| [`SetError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/SetError)\<[`InferError`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferError)\<`ElementType`\>\> \| [`SetError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/SetError)\<[`InferParentError`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferParentError)\<`ElementType`\>\>\> | Creates `T` from an unknown value. This is useful when a value is unknown. | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`fromUnknown`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#fromunknown) | [packages/common/src/Type.ts:322](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L322) |
| <a id="input"></a> `Input` | `public` | `ReadonlySet`\<[`InferInput`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferInput)\<`ElementType`\>\> | The type expected by `from` and `fromUnknown`. ### Example `type StringInput = typeof String.Input;` | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`Input`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#input) | [packages/common/src/Type.ts:219](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L219) |
| <a id="is"></a> `is` | `readonly` | [`Refinement`](https://evolu.dev/docs/api-reference/common/Types/type-aliases/Refinement)\<`unknown`, `ReadonlySet`\<[`InferType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferType)\<`ElementType`\>\>\> | A **type guard** that checks whether an unknown value satisfies the [Type](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type). ### Example `const value: unknown = "hello"; if (String.is(value)) { // TypeScript now knows `value`is a`string` here. console.log("This is a valid string!"); } const strings: unknown[] = [1, "hello", true, "world"]; const filteredStrings = strings.filter(String.is); console.log(filteredStrings); // ["hello", "world"]` | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`is`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#is) | [packages/common/src/Type.ts:351](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L351) |
| <a id="name"></a> `name` | `readonly` | `"Set"` | - | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`name`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#name-1) | [packages/common/src/Type.ts:227](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L227) |
| <a id="ornull"></a> `orNull` | `readonly` | (`value`) => \| `ReadonlySet`\<[`InferType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferType)\<`ElementType`\>\> \| `null` | Creates `T` from an `Input` value, returning `null` if validation fails. This is a convenience method that combines `from` with `getOrNull`. **When to use:** - When you need to convert a validation result to a nullable value - When the error is not important and you just want the value or nothing ### Example `// ✅ Good: Optional user input const age = PositiveInt.orNull(userInput); if (age != null) { console.log("Valid age:", age); } // ✅ Good: Default fallback const maxRetries = PositiveInt.orNull(config.retries) ?? 3; // ❌ Avoid: When you need to know why validation failed (use `from` instead) const result = PositiveInt.from(userInput); if (!result.ok) { console.error(formatPositiveError(result.error)); }` | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`orNull`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#ornull) | [packages/common/src/Type.ts:315](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L315) |
| <a id="orthrow"></a> `orThrow` | `readonly` | (`value`) => `ReadonlySet` | Creates `T` from an `Input` value, throwing an error if validation fails. Throws an Error with the Type validation error in its `cause` property, making it debuggable while avoiding the need for custom error messages. This is a convenience method that combines `from` with `getOrThrow`. **When to use:** - Configuration values that are guaranteed to be valid (e.g., hardcoded constants) - Application startup where failure should crash the program - As an alternative to assertions when the Type error in the thrown Error's `cause` provides sufficient debugging information - Test code with known valid inputs (when error message clarity is not critical; for better test error messages, use Vitest `schemaMatching` + `assert` with `.is()`) ### Example `// ✅ Good: Known valid constant const maxRetries = PositiveInt.orThrow(3); // ✅ Good: App configuration that should crash on invalid values const appName = SimpleName.orThrow("MyApp"); // ✅ Good: Instead of assert when Type error is clear enough // Context makes it obvious: count increments from non-negative value const currentCount = counts.get(id) ?? 0; const newCount = PositiveInt.orThrow(currentCount + 1); // ✅ Good: Test setup with known valid values const testUser = User.orThrow({ name: "Alice", age: 30 }); // ❌ Avoid: User input (use `from` instead) const userAge = PositiveInt.orThrow(userInput); // Could crash! // ✅ Better: Handle user input gracefully const ageResult = PositiveInt.from(userInput); if (!ageResult.ok) { // Handle validation error }` | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`orThrow`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#orthrow) | [packages/common/src/Type.ts:284](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L284) |
| <a id="parent"></a> `Parent` | `public` | `ReadonlySet`\<[`InferParent`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferParent)\<`ElementType`\>\> | The parent type. ### Example `type StringParent = typeof String.Parent;` | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`Parent`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#parent) | [packages/common/src/Type.ts:223](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L223) |
| <a id="parenterror"></a> `ParentError` | `public` | [`SetError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/SetError)\<[`InferParentError`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferParentError)\<`ElementType`\>\> | The parent's error. ### Example `type StringParentError = typeof String.ParentError;` | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`ParentError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#parenterror) | [packages/common/src/Type.ts:225](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L225) |
| <a id="type"></a> `Type` | `readonly` | `ReadonlySet` | The type this Type resolves to. ### Example `type String = typeof String.Type;` | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#type) | [packages/common/src/Type.ts:364](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L364) |
SimpleNameError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / SimpleNameError
# Interface: SimpleNameError
Defined in: [packages/common/src/Type.ts:1549](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1549)
## Extends
- [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError)\<`"SimpleName"`\>
## Properties
| Property | Modifier | Type | Description | Inherited from | Defined in |
| -------------------------- | ---------- | -------------- | -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="type"></a> `type` | `readonly` | `"SimpleName"` | - | [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError).[`type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError.mdx#type) | [packages/common/src/Type.ts:428](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L428) |
| <a id="value"></a> `value` | `readonly` | `unknown` | The value that was received and caused the error. Provides additional context for debugging and validation feedback. | [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError).[`value`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError.mdx#value) | [packages/common/src/Type.ts:434](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L434) |
StandardSchemaV1 - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / StandardSchemaV1
# Interface: StandardSchemaV1\<Input, Output\>
Defined in: [packages/common/src/Type.ts:4448](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L4448)
The Standard Schema interface.
## Extended by
- [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type)
## Type Parameters
| Type Parameter | Default type |
| -------------- | ------------ |
| `Input` | `unknown` |
| `Output` | `Input` |
## Properties
| Property | Modifier | Type | Description | Defined in |
| --------------------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------- | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="standard"></a> `~standard` | `readonly` | [`Props`](https://evolu.dev/docs/api-reference/common/Type/namespaces/StandardSchemaV1/interfaces/Props)\<`Input`, `Output`\> | The Standard Schema properties. | [packages/common/src/Type.ts:4450](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L4450) |
StringError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / StringError
# Interface: StringError
Defined in: [packages/common/src/Type.ts:677](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L677)
## Extends
- [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError)\<`"String"`\>
## Properties
| Property | Modifier | Type | Description | Inherited from | Defined in |
| -------------------------- | ---------- | ---------- | -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="type"></a> `type` | `readonly` | `"String"` | - | [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError).[`type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError.mdx#type) | [packages/common/src/Type.ts:428](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L428) |
| <a id="value"></a> `value` | `readonly` | `unknown` | The value that was received and caused the error. Provides additional context for debugging and validation feedback. | [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError).[`value`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError.mdx#value) | [packages/common/src/Type.ts:434](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L434) |
TableId - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / TableId
# Interface: TableId\<Table\>
Defined in: [packages/common/src/Type.ts:1765](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1765)
Evolu [Type](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type) is like a type guard that returns typed errors (via
[Result](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result)) instead of throwing. We either get a safely typed value or a
composable typed error telling us exactly why validation failed.
Why another validation library?
- **Result-based error handling** – no exceptions for normal control flow.
- **Typed errors with decoupled formatters** – validation logic ≠ user
messages.
- **Consistent constraints via [Brand](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)** – every constraint becomes part
of the type.
- **Skippable validation** – parent validations can be skipped when already
proved by types.
- **Simple, top-down implementation** – readable source code from top to
bottom.
- **No user-land chaining DSL** – prepared for TC39 Hack pipes.
A distinctive feature of Evolu Type compared to other validation libraries is
that it returns typed errors rather than string messages. This allows
TypeScript to enforce that all validation errors are handled by type
checking, significantly improving the developer experience.
Evolu Type supports [Standard Schema](https://standardschema.dev/) for
interoperability with 40+ validation-compatible tools and frameworks.
### Base Types Quick Start
```ts
// Validate unknown values
const value: unknown = "hello";
const stringResult = String.fromUnknown(value);
if (!stringResult.ok) {
// console.error(formatStringError(stringResult.error));
return stringResult; // inside a function returning Result<string, _>
}
// Safe branch: value is now string
const upper = stringResult.value.toUpperCase();
// Type guard style
if (String.is(value)) {
// narrowed to string
}
// Composing: arrays & objects
const Numbers = array(Number); // ReadonlyArray<number>
const Point = object({ x: Number, y: Number });
Numbers.from([1, 2, 3]); // ok
Point.from({ x: 1, y: 2 }); // ok
Point.from({ x: 1, y: "2" }); // err -> nested Number error
```
### Branding Basics
Branding adds semantic meaning & constraints while preserving the runtime
shape:
```ts
const CurrencyCode = brand("CurrencyCode", String, (value) =>
/^[A-Z]{3}$/.test(value)
? ok(value)
: err<CurrencyCodeError>({ type: "CurrencyCode", value }),
);
type CurrencyCode = typeof CurrencyCode.Type; // string & Brand<"CurrencyCode">
interface CurrencyCodeError extends TypeError<"CurrencyCode"> {}
const formatCurrencyCodeError = createTypeErrorFormatter<CurrencyCodeError>(
(error) => `Invalid currency code: ${error.value}`,
);
const r = CurrencyCode.from("USD"); // ok("USD")
const e = CurrencyCode.from("usd"); // err(...)
```
See also reusable brand factories like `minLength`, `maxLength`, `trimmed`,
`positive`, `between`, etc.
### Objects & Optional Fields
```ts
const User = object({
name: NonEmptyTrimmedString100,
age: optional(PositiveInt),
});
type User = typeof User.Type;
User.from({ name: "Alice" }); // ok
User.from({ name: "Alice", age: -1 }); // err(PositiveInt)
```
### Deriving JSON String Types
```ts
const Person = object({
name: NonEmptyString50,
// Did you know that JSON.stringify converts NaN (a number) into null?
// To prevent this, use FiniteNumber.
age: FiniteNumber,
});
type Person = typeof Person.Type;
const [PersonJson, personToPersonJson, personJsonToPerson] = json(
Person,
"PersonJson",
);
// string & Brand<"PersonJson">
type PersonJson = typeof PersonJson.Type;
const person = Person.orThrow({
name: "Alice",
age: 30,
});
const personJson = personToPersonJson(person);
expect(personJsonToPerson(personJson)).toEqual(person);
```
### Error Formatting
Evolu separates validation logic from human-readable messages. There are two
layers:
1. Per-type formatters (e.g. `formatStringError`) – simple, focused, already
used earlier in the quick start example.
2. A unified formatter via `createFormatTypeError` – composes all built-in and
custom errors (including nested composite types) and lets us override
selected messages.
#### 1. Per-Type Formatter (recap)
```ts
const r = String.fromUnknown(42);
if (!r.ok) console.error(formatStringError(r.error));
```
#### 2. Unified Formatter with Overrides
```ts
// Override only what we care about; fall back to built-ins for the rest.
const formatTypeError = createFormatTypeError((error) => {
if (error.type === "MinLength") return `Min length is ${error.min}`;
});
const User = object({ name: NonEmptyTrimmedString100 });
const resultUser = User.from({ name: "" });
if (!resultUser.ok) console.error(formatTypeError(resultUser.error));
const badPoint = object({ x: Number, y: Number }).from({
x: 1,
y: "foo",
});
if (!badPoint.ok) console.error(formatTypeError(badPoint.error));
```
The unified formatter walks nested structures (object / array / record /
tuple / union) and applies overrides only where specified, greatly reducing
boilerplate when formatting complex validation errors.
### Tip
If necessary, write `globalThis.String` instead of `String` to avoid naming
clashes with native types.
### Design Decision: No Bidirectional Transformations
Evolu Type intentionally does not support bidirectional transformations. It
previously did, but supporting that while keeping typed error fidelity added
complexity that hurt readability & reliability. Most persistence pipelines
(e.g. SQLite) already require explicit mapping of query results, so implicit
reverse transforms would not buy much. We may revisit this if we can design a
minimal, 100% safe API that preserves simplicity.
### Prepared for TC39 Hack Pipes
Take a look how `SimplePassword` is defined:
```ts
export const SimplePassword = brand(
"SimplePassword",
minLength(8)(maxLength(64)(TrimmedString)),
);
```
Nested functions are often OK (if not, make a helper) and read well, but with
TC39 Hack pipes it would be clearer:
```ts
// TrimmedString
// |> minLength(8)(%)
// |> maxLength(64)(%)
// |> brand("SimplePassword", %)
```
Note `minLength` and `maxLength` are curried because they are factories.
## Extends
- [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type)\<`"Id"`, `string` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Id"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`Table`\>, `string`, [`TableIdError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TableIdError)\<`Table`\>, `string`, [`StringError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/StringError)\>
## Type Parameters
| Type Parameter |
| ----------------------------------------------------------------------------------------- |
| `Table` _extends_ [`TypeName`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/TypeName) |
## Properties
| Property | Modifier | Type | Description | Inherited from | Defined in |
| ------------------------------------------------ | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="evolutypesymbol"></a> `[EvoluTypeSymbol]` | `readonly` | `true` | - | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`[EvoluTypeSymbol]`](/docs/api-reference/common/Type/interfaces/Type.mdx#evolutypesymbol) | [packages/common/src/Type.ts:353](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L353) |
| <a id="standard"></a> `~standard` | `readonly` | [`Props`](https://evolu.dev/docs/api-reference/common/Type/namespaces/StandardSchemaV1/interfaces/Props)\<`string`, `string` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Id"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`Table`\>\> | The Standard Schema properties. | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`~standard`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#standard) | [packages/common/src/Type.ts:4450](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L4450) |
| <a id="error"></a> `Error` | `public` | [`TableIdError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TableIdError)\<`Table`\> | The specific error introduced by this Type. ### Example `type StringError = typeof String.Error;` | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`Error`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#error) | [packages/common/src/Type.ts:221](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L221) |
| <a id="errors"></a> `Errors` | `readonly` | \| [`StringError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/StringError) \| [`TableIdError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TableIdError)\<`Table`\> | ### Example `type StringParentErrors = typeof String.Errors;` | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`Errors`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#errors) | [packages/common/src/Type.ts:417](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L417) |
| <a id="from"></a> `from` | `readonly` | (`value`) => [`Result`](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result)\<`string` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Id"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`Table`\>, \| [`StringError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/StringError) \| [`TableIdError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TableIdError)\<`Table`\>\> | Creates `T` from an `Input` value. This is useful when we have a typed value. `from` is a typed alias of `fromUnknown`. | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`from`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#from) | [packages/common/src/Type.ts:236](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L236) |
| <a id="fromparent"></a> `fromParent` | `readonly` | (`value`) => [`Result`](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result)\<`string` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Id"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`Table`\>, [`TableIdError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TableIdError)\<`Table`\>\> | Creates `T` from `Parent` type. This function skips parent Types validations when we have already partially validated value. | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`fromParent`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#fromparent) | [packages/common/src/Type.ts:330](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L330) |
| <a id="fromunknown"></a> `fromUnknown` | `readonly` | (`value`) => [`Result`](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result)\<`string` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Id"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`Table`\>, \| [`StringError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/StringError) \| [`TableIdError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TableIdError)\<`Table`\>\> | Creates `T` from an unknown value. This is useful when a value is unknown. | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`fromUnknown`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#fromunknown) | [packages/common/src/Type.ts:322](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L322) |
| <a id="input"></a> `Input` | `public` | `string` | The type expected by `from` and `fromUnknown`. ### Example `type StringInput = typeof String.Input;` | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`Input`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#input) | [packages/common/src/Type.ts:219](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L219) |
| <a id="is"></a> `is` | `readonly` | [`Refinement`](https://evolu.dev/docs/api-reference/common/Types/type-aliases/Refinement)\<`unknown`, `string` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Id"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`Table`\>\> | A **type guard** that checks whether an unknown value satisfies the [Type](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type). ### Example `const value: unknown = "hello"; if (String.is(value)) { // TypeScript now knows `value`is a`string` here. console.log("This is a valid string!"); } const strings: unknown[] = [1, "hello", true, "world"]; const filteredStrings = strings.filter(String.is); console.log(filteredStrings); // ["hello", "world"]` | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`is`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#is) | [packages/common/src/Type.ts:351](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L351) |
| <a id="name"></a> `name` | `readonly` | `"Id"` | - | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`name`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#name-1) | [packages/common/src/Type.ts:227](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L227) |
| <a id="ornull"></a> `orNull` | `readonly` | (`value`) => \| `string` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Id"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`Table`\> \| `null` | Creates `T` from an `Input` value, returning `null` if validation fails. This is a convenience method that combines `from` with `getOrNull`. **When to use:** - When you need to convert a validation result to a nullable value - When the error is not important and you just want the value or nothing ### Example `// ✅ Good: Optional user input const age = PositiveInt.orNull(userInput); if (age != null) { console.log("Valid age:", age); } // ✅ Good: Default fallback const maxRetries = PositiveInt.orNull(config.retries) ?? 3; // ❌ Avoid: When you need to know why validation failed (use `from` instead) const result = PositiveInt.from(userInput); if (!result.ok) { console.error(formatPositiveError(result.error)); }` | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`orNull`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#ornull) | [packages/common/src/Type.ts:315](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L315) |
| <a id="orthrow"></a> `orThrow` | `readonly` | (`value`) => `string` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Id"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`Table`\> | Creates `T` from an `Input` value, throwing an error if validation fails. Throws an Error with the Type validation error in its `cause` property, making it debuggable while avoiding the need for custom error messages. This is a convenience method that combines `from` with `getOrThrow`. **When to use:** - Configuration values that are guaranteed to be valid (e.g., hardcoded constants) - Application startup where failure should crash the program - As an alternative to assertions when the Type error in the thrown Error's `cause` provides sufficient debugging information - Test code with known valid inputs (when error message clarity is not critical; for better test error messages, use Vitest `schemaMatching` + `assert` with `.is()`) ### Example `// ✅ Good: Known valid constant const maxRetries = PositiveInt.orThrow(3); // ✅ Good: App configuration that should crash on invalid values const appName = SimpleName.orThrow("MyApp"); // ✅ Good: Instead of assert when Type error is clear enough // Context makes it obvious: count increments from non-negative value const currentCount = counts.get(id) ?? 0; const newCount = PositiveInt.orThrow(currentCount + 1); // ✅ Good: Test setup with known valid values const testUser = User.orThrow({ name: "Alice", age: 30 }); // ❌ Avoid: User input (use `from` instead) const userAge = PositiveInt.orThrow(userInput); // Could crash! // ✅ Better: Handle user input gracefully const ageResult = PositiveInt.from(userInput); if (!ageResult.ok) { // Handle validation error }` | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`orThrow`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#orthrow) | [packages/common/src/Type.ts:284](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L284) |
| <a id="parent"></a> `Parent` | `public` | `string` | The parent type. ### Example `type StringParent = typeof String.Parent;` | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`Parent`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#parent) | [packages/common/src/Type.ts:223](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L223) |
| <a id="parenterror"></a> `ParentError` | `public` | [`StringError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/StringError) | The parent's error. ### Example `type StringParentError = typeof String.ParentError;` | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`ParentError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#parenterror) | [packages/common/src/Type.ts:225](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L225) |
| <a id="table-1"></a> `table` | `public` | `Table` | - | - | [packages/common/src/Type.ts:1773](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1773) |
| <a id="type"></a> `Type` | `readonly` | `string` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Id"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`Table`\> | The type this Type resolves to. ### Example `type String = typeof String.Type;` | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#type) | [packages/common/src/Type.ts:364](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L364) |
TableIdError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / TableIdError
# Interface: TableIdError\<Table\>
Defined in: [packages/common/src/Type.ts:1776](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1776)
## Extends
- [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError)\<`"TableId"`\>
## Type Parameters
| Type Parameter | Default type |
| ----------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
| `Table` _extends_ [`TypeName`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/TypeName) | [`TypeName`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/TypeName) |
## Properties
| Property | Modifier | Type | Description | Inherited from | Defined in |
| ---------------------------- | ---------- | ----------- | -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="table-1"></a> `table` | `readonly` | `Table` | - | - | [packages/common/src/Type.ts:1779](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1779) |
| <a id="type"></a> `type` | `readonly` | `"TableId"` | - | [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError).[`type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError.mdx#type) | [packages/common/src/Type.ts:428](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L428) |
| <a id="value"></a> `value` | `readonly` | `unknown` | The value that was received and caused the error. Provides additional context for debugging and validation feedback. | [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError).[`value`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError.mdx#value) | [packages/common/src/Type.ts:434](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L434) |
TrimmedError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / TrimmedError
# Interface: TrimmedError
Defined in: [packages/common/src/Type.ts:1187](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1187)
## Extends
- [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError)\<`"Trimmed"`\>
## Properties
| Property | Modifier | Type | Description | Inherited from | Defined in |
| -------------------------- | ---------- | ----------- | -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="type"></a> `type` | `readonly` | `"Trimmed"` | - | [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError).[`type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError.mdx#type) | [packages/common/src/Type.ts:428](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L428) |
| <a id="value"></a> `value` | `readonly` | `unknown` | The value that was received and caused the error. Provides additional context for debugging and validation feedback. | [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError).[`value`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError.mdx#value) | [packages/common/src/Type.ts:434](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L434) |
TupleError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / TupleError
# Interface: TupleError\<ElementError\>
Defined in: [packages/common/src/Type.ts:3573](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L3573)
## Extends
- [`TypeErrorWithReason`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeErrorWithReason)\<`"Tuple"`,
\| \{
`expected`: `number`;
`kind`: `"InvalidLength"`;
\}
\| \{
`error`: `ElementError`;
`index`: `number`;
`kind`: `"Element"`;
\}\>
## Type Parameters
| Type Parameter | Default type |
| ------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------- |
| `ElementError` _extends_ [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError) | [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError) |
## Properties
| Property | Modifier | Type | Description | Inherited from | Defined in |
| ---------------------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="reason"></a> `reason` | `readonly` | \| \{ `expected`: `number`; `kind`: `"InvalidLength"`; \} \| \{ `error`: `ElementError`; `index`: `number`; `kind`: `"Element"`; \} | The detailed reason for the error, represented as a tagged union. | [`TypeErrorWithReason`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeErrorWithReason).[`reason`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeErrorWithReason.mdx#reason-1) | [packages/common/src/Type.ts:444](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L444) |
| <a id="type"></a> `type` | `readonly` | `"Tuple"` | - | [`TypeErrorWithReason`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeErrorWithReason).[`type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeErrorWithReason.mdx#type) | [packages/common/src/Type.ts:428](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L428) |
| <a id="value"></a> `value` | `readonly` | `unknown` | The value that was received and caused the error. Provides additional context for debugging and validation feedback. | [`TypeErrorWithReason`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeErrorWithReason).[`value`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeErrorWithReason.mdx#value) | [packages/common/src/Type.ts:434](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L434) |
TupleType - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / TupleType
# Interface: TupleType\<Elements\>
Defined in: [packages/common/src/Type.ts:3560](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L3560)
TupleType extends [Type](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type) with an additional `elements` property for
reflection.
## Extends
- [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type)\<`"Tuple"`, readonly \[`...{ [K in keyof Elements]: InferType<Elements[K]> }`\], readonly \[`...{ [K in keyof Elements]: InferInput<Elements[K]> }`\], [`TupleError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TupleError)\<`{ [K in keyof Elements]: InferError<Elements[K]> }`\[`number`\]\>, readonly \[`...{ [K in keyof Elements]: InferParent<Elements[K]> }`\], [`TupleError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TupleError)\<`{ [K in keyof Elements]: InferParentError<Elements[K]> }`\[`number`\]\>\>
## Type Parameters
| Type Parameter |
| ------------------------------------------------------------------------------------------------------------------------------------ |
| `Elements` _extends_ readonly \[[`AnyType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/AnyType), `...ReadonlyArray<AnyType>`\] |
## Properties
| Property | Modifier | Type | Description | Inherited from | Defined in |
| ------------------------------------------------ | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="evolutypesymbol"></a> `[EvoluTypeSymbol]` | `readonly` | `true` | - | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`[EvoluTypeSymbol]`](/docs/api-reference/common/Type/interfaces/Type.mdx#evolutypesymbol) | [packages/common/src/Type.ts:353](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L353) |
| <a id="standard"></a> `~standard` | `readonly` | [`Props`](https://evolu.dev/docs/api-reference/common/Type/namespaces/StandardSchemaV1/interfaces/Props)\<readonly \[\{ \[K in string \| number \| symbol\]: InferInput\<Elements\[K\<K\>\]\> \}\], readonly \[\{ \[K in string \| number \| symbol\]: InferType\<Elements\[K\<K\>\]\> \}\]\> | The Standard Schema properties. | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`~standard`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#standard) | [packages/common/src/Type.ts:4450](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L4450) |
| <a id="elements-1"></a> `elements` | `readonly` | `Elements` | - | - | [packages/common/src/Type.ts:3570](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L3570) |
| <a id="error"></a> `Error` | `public` | [`TupleError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TupleError)\<\{ \[K in string \| number \| symbol\]: InferError\<Elements\[K\<K\>\]\> \}\[`number`\]\> | The specific error introduced by this Type. ### Example `type StringError = typeof String.Error;` | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`Error`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#error) | [packages/common/src/Type.ts:221](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L221) |
| <a id="errors"></a> `Errors` | `readonly` | \| [`TupleError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TupleError)\<\{ \[K in string \| number \| symbol\]: InferError\<Elements\[K\<K\>\]\> \}\[`number`\]\> \| [`TupleError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TupleError)\<\{ \[K in string \| number \| symbol\]: InferParentError\<Elements\[K\<K\>\]\> \}\[`number`\]\> | ### Example `type StringParentErrors = typeof String.Errors;` | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`Errors`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#errors) | [packages/common/src/Type.ts:417](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L417) |
| <a id="from"></a> `from` | `readonly` | (`value`) => [`Result`](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result)\<readonly \[\{ \[K in string \| number \| symbol\]: InferType\<Elements\[K\<K\>\]\> \}\], \| [`TupleError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TupleError)\<\{ \[K in string \| number \| symbol\]: InferError\<Elements\[K\<K\>\]\> \}\[`number`\]\> \| [`TupleError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TupleError)\<\{ \[K in string \| number \| symbol\]: InferParentError\<Elements\[K\<K\>\]\> \}\[`number`\]\>\> | Creates `T` from an `Input` value. This is useful when we have a typed value. `from` is a typed alias of `fromUnknown`. | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`from`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#from) | [packages/common/src/Type.ts:236](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L236) |
| <a id="fromparent"></a> `fromParent` | `readonly` | (`value`) => [`Result`](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result)\<readonly \[\{ \[K in string \| number \| symbol\]: InferType\<Elements\[K\<K\>\]\> \}\], [`TupleError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TupleError)\<\{ \[K in string \| number \| symbol\]: InferError\<Elements\[K\<K\>\]\> \}\[`number`\]\>\> | Creates `T` from `Parent` type. This function skips parent Types validations when we have already partially validated value. | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`fromParent`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#fromparent) | [packages/common/src/Type.ts:330](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L330) |
| <a id="fromunknown"></a> `fromUnknown` | `readonly` | (`value`) => [`Result`](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result)\<readonly \[\{ \[K in string \| number \| symbol\]: InferType\<Elements\[K\<K\>\]\> \}\], \| [`TupleError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TupleError)\<\{ \[K in string \| number \| symbol\]: InferError\<Elements\[K\<K\>\]\> \}\[`number`\]\> \| [`TupleError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TupleError)\<\{ \[K in string \| number \| symbol\]: InferParentError\<Elements\[K\<K\>\]\> \}\[`number`\]\>\> | Creates `T` from an unknown value. This is useful when a value is unknown. | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`fromUnknown`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#fromunknown) | [packages/common/src/Type.ts:322](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L322) |
| <a id="input"></a> `Input` | `public` | readonly \[\{ \[K in string \| number \| symbol\]: InferInput\<Elements\[K\<K\>\]\> \}\] | The type expected by `from` and `fromUnknown`. ### Example `type StringInput = typeof String.Input;` | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`Input`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#input) | [packages/common/src/Type.ts:219](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L219) |
| <a id="is"></a> `is` | `readonly` | [`Refinement`](https://evolu.dev/docs/api-reference/common/Types/type-aliases/Refinement)\<`unknown`, readonly \[\{ \[K in string \| number \| symbol\]: InferType\<Elements\[K\<K\>\]\> \}\]\> | A **type guard** that checks whether an unknown value satisfies the [Type](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type). ### Example `const value: unknown = "hello"; if (String.is(value)) { // TypeScript now knows `value`is a`string` here. console.log("This is a valid string!"); } const strings: unknown[] = [1, "hello", true, "world"]; const filteredStrings = strings.filter(String.is); console.log(filteredStrings); // ["hello", "world"]` | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`is`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#is) | [packages/common/src/Type.ts:351](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L351) |
| <a id="name"></a> `name` | `readonly` | `"Tuple"` | - | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`name`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#name-1) | [packages/common/src/Type.ts:227](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L227) |
| <a id="ornull"></a> `orNull` | `readonly` | (`value`) => \| readonly \[\{ \[K in string \| number \| symbol\]: InferType\<Elements\[K\<K\>\]\> \}\] \| `null` | Creates `T` from an `Input` value, returning `null` if validation fails. This is a convenience method that combines `from` with `getOrNull`. **When to use:** - When you need to convert a validation result to a nullable value - When the error is not important and you just want the value or nothing ### Example `// ✅ Good: Optional user input const age = PositiveInt.orNull(userInput); if (age != null) { console.log("Valid age:", age); } // ✅ Good: Default fallback const maxRetries = PositiveInt.orNull(config.retries) ?? 3; // ❌ Avoid: When you need to know why validation failed (use `from` instead) const result = PositiveInt.from(userInput); if (!result.ok) { console.error(formatPositiveError(result.error)); }` | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`orNull`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#ornull) | [packages/common/src/Type.ts:315](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L315) |
| <a id="orthrow"></a> `orThrow` | `readonly` | (`value`) => readonly \[\{ \[K in string \| number \| symbol\]: InferType\<Elements\[K\<K\>\]\> \}\] | Creates `T` from an `Input` value, throwing an error if validation fails. Throws an Error with the Type validation error in its `cause` property, making it debuggable while avoiding the need for custom error messages. This is a convenience method that combines `from` with `getOrThrow`. **When to use:** - Configuration values that are guaranteed to be valid (e.g., hardcoded constants) - Application startup where failure should crash the program - As an alternative to assertions when the Type error in the thrown Error's `cause` provides sufficient debugging information - Test code with known valid inputs (when error message clarity is not critical; for better test error messages, use Vitest `schemaMatching` + `assert` with `.is()`) ### Example `// ✅ Good: Known valid constant const maxRetries = PositiveInt.orThrow(3); // ✅ Good: App configuration that should crash on invalid values const appName = SimpleName.orThrow("MyApp"); // ✅ Good: Instead of assert when Type error is clear enough // Context makes it obvious: count increments from non-negative value const currentCount = counts.get(id) ?? 0; const newCount = PositiveInt.orThrow(currentCount + 1); // ✅ Good: Test setup with known valid values const testUser = User.orThrow({ name: "Alice", age: 30 }); // ❌ Avoid: User input (use `from` instead) const userAge = PositiveInt.orThrow(userInput); // Could crash! // ✅ Better: Handle user input gracefully const ageResult = PositiveInt.from(userInput); if (!ageResult.ok) { // Handle validation error }` | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`orThrow`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#orthrow) | [packages/common/src/Type.ts:284](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L284) |
| <a id="parent"></a> `Parent` | `public` | readonly \[\{ \[K in string \| number \| symbol\]: InferParent\<Elements\[K\<K\>\]\> \}\] | The parent type. ### Example `type StringParent = typeof String.Parent;` | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`Parent`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#parent) | [packages/common/src/Type.ts:223](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L223) |
| <a id="parenterror"></a> `ParentError` | `public` | [`TupleError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TupleError)\<\{ \[K in string \| number \| symbol\]: InferParentError\<Elements\[K\<K\>\]\> \}\[`number`\]\> | The parent's error. ### Example `type StringParentError = typeof String.ParentError;` | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`ParentError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#parenterror) | [packages/common/src/Type.ts:225](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L225) |
| <a id="type"></a> `Type` | `readonly` | readonly \[\{ \[K in string \| number \| symbol\]: InferType\<Elements\[K\<K\>\]\> \}\] | The type this Type resolves to. ### Example `type String = typeof String.Type;` | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#type) | [packages/common/src/Type.ts:364](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L364) |
Type - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / Type
# Interface: Type\<Name, T, Input, Error, Parent, ParentError\>
Defined in: [packages/common/src/Type.ts:214](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L214)
Evolu [Type](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type) is like a type guard that returns typed errors (via
[Result](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result)) instead of throwing. We either get a safely typed value or a
composable typed error telling us exactly why validation failed.
Why another validation library?
- **Result-based error handling** – no exceptions for normal control flow.
- **Typed errors with decoupled formatters** – validation logic ≠ user
messages.
- **Consistent constraints via [Brand](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)** – every constraint becomes part
of the type.
- **Skippable validation** – parent validations can be skipped when already
proved by types.
- **Simple, top-down implementation** – readable source code from top to
bottom.
- **No user-land chaining DSL** – prepared for TC39 Hack pipes.
A distinctive feature of Evolu Type compared to other validation libraries is
that it returns typed errors rather than string messages. This allows
TypeScript to enforce that all validation errors are handled by type
checking, significantly improving the developer experience.
Evolu Type supports [Standard Schema](https://standardschema.dev/) for
interoperability with 40+ validation-compatible tools and frameworks.
### Base Types Quick Start
```ts
// Validate unknown values
const value: unknown = "hello";
const stringResult = String.fromUnknown(value);
if (!stringResult.ok) {
// console.error(formatStringError(stringResult.error));
return stringResult; // inside a function returning Result<string, _>
}
// Safe branch: value is now string
const upper = stringResult.value.toUpperCase();
// Type guard style
if (String.is(value)) {
// narrowed to string
}
// Composing: arrays & objects
const Numbers = array(Number); // ReadonlyArray<number>
const Point = object({ x: Number, y: Number });
Numbers.from([1, 2, 3]); // ok
Point.from({ x: 1, y: 2 }); // ok
Point.from({ x: 1, y: "2" }); // err -> nested Number error
```
### Branding Basics
Branding adds semantic meaning & constraints while preserving the runtime
shape:
```ts
const CurrencyCode = brand("CurrencyCode", String, (value) =>
/^[A-Z]{3}$/.test(value)
? ok(value)
: err<CurrencyCodeError>({ type: "CurrencyCode", value }),
);
type CurrencyCode = typeof CurrencyCode.Type; // string & Brand<"CurrencyCode">
interface CurrencyCodeError extends TypeError<"CurrencyCode"> {}
const formatCurrencyCodeError = createTypeErrorFormatter<CurrencyCodeError>(
(error) => `Invalid currency code: ${error.value}`,
);
const r = CurrencyCode.from("USD"); // ok("USD")
const e = CurrencyCode.from("usd"); // err(...)
```
See also reusable brand factories like `minLength`, `maxLength`, `trimmed`,
`positive`, `between`, etc.
### Objects & Optional Fields
```ts
const User = object({
name: NonEmptyTrimmedString100,
age: optional(PositiveInt),
});
type User = typeof User.Type;
User.from({ name: "Alice" }); // ok
User.from({ name: "Alice", age: -1 }); // err(PositiveInt)
```
### Deriving JSON String Types
```ts
const Person = object({
name: NonEmptyString50,
// Did you know that JSON.stringify converts NaN (a number) into null?
// To prevent this, use FiniteNumber.
age: FiniteNumber,
});
type Person = typeof Person.Type;
const [PersonJson, personToPersonJson, personJsonToPerson] = json(
Person,
"PersonJson",
);
// string & Brand<"PersonJson">
type PersonJson = typeof PersonJson.Type;
const person = Person.orThrow({
name: "Alice",
age: 30,
});
const personJson = personToPersonJson(person);
expect(personJsonToPerson(personJson)).toEqual(person);
```
### Error Formatting
Evolu separates validation logic from human-readable messages. There are two
layers:
1. Per-type formatters (e.g. `formatStringError`) – simple, focused, already
used earlier in the quick start example.
2. A unified formatter via `createFormatTypeError` – composes all built-in and
custom errors (including nested composite types) and lets us override
selected messages.
#### 1. Per-Type Formatter (recap)
```ts
const r = String.fromUnknown(42);
if (!r.ok) console.error(formatStringError(r.error));
```
#### 2. Unified Formatter with Overrides
```ts
// Override only what we care about; fall back to built-ins for the rest.
const formatTypeError = createFormatTypeError((error) => {
if (error.type === "MinLength") return `Min length is ${error.min}`;
});
const User = object({ name: NonEmptyTrimmedString100 });
const resultUser = User.from({ name: "" });
if (!resultUser.ok) console.error(formatTypeError(resultUser.error));
const badPoint = object({ x: Number, y: Number }).from({
x: 1,
y: "foo",
});
if (!badPoint.ok) console.error(formatTypeError(badPoint.error));
```
The unified formatter walks nested structures (object / array / record /
tuple / union) and applies overrides only where specified, greatly reducing
boilerplate when formatting complex validation errors.
### Tip
If necessary, write `globalThis.String` instead of `String` to avoid naming
clashes with native types.
### Design Decision: No Bidirectional Transformations
Evolu Type intentionally does not support bidirectional transformations. It
previously did, but supporting that while keeping typed error fidelity added
complexity that hurt readability & reliability. Most persistence pipelines
(e.g. SQLite) already require explicit mapping of query results, so implicit
reverse transforms would not buy much. We may revisit this if we can design a
minimal, 100% safe API that preserves simplicity.
### Prepared for TC39 Hack Pipes
Take a look how `SimplePassword` is defined:
```ts
export const SimplePassword = brand(
"SimplePassword",
minLength(8)(maxLength(64)(TrimmedString)),
);
```
Nested functions are often OK (if not, make a helper) and read well, but with
TC39 Hack pipes it would be clearer:
```ts
// TrimmedString
// |> minLength(8)(%)
// |> maxLength(64)(%)
// |> brand("SimplePassword", %)
```
Note `minLength` and `maxLength` are curried because they are factories.
## Extends
- [`StandardSchemaV1`](https://evolu.dev/docs/api-reference/common/Type/interfaces/StandardSchemaV1)\<`Input`, `T`\>
## Extended by
- [`InstanceOfType`](https://evolu.dev/docs/api-reference/common/Type/interfaces/InstanceOfType)
- [`BrandType`](https://evolu.dev/docs/api-reference/common/Type/interfaces/BrandType)
- [`TableId`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TableId)
- [`LiteralType`](https://evolu.dev/docs/api-reference/common/Type/interfaces/LiteralType)
- [`ArrayType`](https://evolu.dev/docs/api-reference/common/Type/interfaces/ArrayType)
- [`SetType`](https://evolu.dev/docs/api-reference/common/Type/interfaces/SetType)
- [`RecordType`](https://evolu.dev/docs/api-reference/common/Type/interfaces/RecordType)
- [`ObjectType`](https://evolu.dev/docs/api-reference/common/Type/interfaces/ObjectType)
- [`ObjectWithRecordType`](https://evolu.dev/docs/api-reference/common/Type/interfaces/ObjectWithRecordType)
- [`UnionType`](https://evolu.dev/docs/api-reference/common/Type/interfaces/UnionType)
- [`RecursiveType`](https://evolu.dev/docs/api-reference/common/Type/interfaces/RecursiveType)
- [`TupleType`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TupleType)
- [`OptionalType`](https://evolu.dev/docs/api-reference/common/Type/interfaces/OptionalType)
## Type Parameters
| Type Parameter | Default type |
| ----------------------------------------------------------------------------------------------- | ------------ |
| `Name` _extends_ [`TypeName`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/TypeName) | - |
| `T` | - |
| `Input` | - |
| `Error` _extends_ [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError) | `never` |
| `Parent` | `T` |
| `ParentError` _extends_ [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError) | `Error` |
## Properties
| Property | Modifier | Type | Description | Inherited from | Defined in |
| ------------------------------------------------ | ---------- | ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="evolutypesymbol"></a> `[EvoluTypeSymbol]` | `readonly` | `true` | - | - | [packages/common/src/Type.ts:353](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L353) |
| <a id="standard"></a> `~standard` | `readonly` | [`Props`](https://evolu.dev/docs/api-reference/common/Type/namespaces/StandardSchemaV1/interfaces/Props)\<`Input`, `T`\> | The Standard Schema properties. | [`StandardSchemaV1`](https://evolu.dev/docs/api-reference/common/Type/interfaces/StandardSchemaV1).[`~standard`](https://evolu.dev/docs/api-reference/common/Type/interfaces/StandardSchemaV1.mdx#standard) | [packages/common/src/Type.ts:4450](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L4450) |
| <a id="error-1"></a> `Error` | `public` | `Error` | The specific error introduced by this Type. ### Example `type StringError = typeof String.Error;` | - | [packages/common/src/Type.ts:221](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L221) |
| <a id="errors"></a> `Errors` | `readonly` | `Error` \| `ParentError` | ### Example `type StringParentErrors = typeof String.Errors;` | - | [packages/common/src/Type.ts:417](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L417) |
| <a id="from"></a> `from` | `readonly` | (`value`) => [`Result`](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result)\<`T`, `Error` \| `ParentError`\> | Creates `T` from an `Input` value. This is useful when we have a typed value. `from` is a typed alias of `fromUnknown`. | - | [packages/common/src/Type.ts:236](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L236) |
| <a id="fromparent"></a> `fromParent` | `readonly` | (`value`) => [`Result`](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result)\<`T`, `Error`\> | Creates `T` from `Parent` type. This function skips parent Types validations when we have already partially validated value. | - | [packages/common/src/Type.ts:330](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L330) |
| <a id="fromunknown"></a> `fromUnknown` | `readonly` | (`value`) => [`Result`](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result)\<`T`, `Error` \| `ParentError`\> | Creates `T` from an unknown value. This is useful when a value is unknown. | - | [packages/common/src/Type.ts:322](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L322) |
| <a id="input-1"></a> `Input` | `public` | `Input` | The type expected by `from` and `fromUnknown`. ### Example `type StringInput = typeof String.Input;` | - | [packages/common/src/Type.ts:219](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L219) |
| <a id="is"></a> `is` | `readonly` | [`Refinement`](https://evolu.dev/docs/api-reference/common/Types/type-aliases/Refinement)\<`unknown`, `T`\> | A **type guard** that checks whether an unknown value satisfies the [Type](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type). ### Example `const value: unknown = "hello"; if (String.is(value)) { // TypeScript now knows `value`is a`string` here. console.log("This is a valid string!"); } const strings: unknown[] = [1, "hello", true, "world"]; const filteredStrings = strings.filter(String.is); console.log(filteredStrings); // ["hello", "world"]` | - | [packages/common/src/Type.ts:351](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L351) |
| <a id="name-1"></a> `name` | `readonly` | `Name` | - | - | [packages/common/src/Type.ts:227](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L227) |
| <a id="ornull"></a> `orNull` | `readonly` | (`value`) => `T` \| `null` | Creates `T` from an `Input` value, returning `null` if validation fails. This is a convenience method that combines `from` with `getOrNull`. **When to use:** - When you need to convert a validation result to a nullable value - When the error is not important and you just want the value or nothing ### Example `// ✅ Good: Optional user input const age = PositiveInt.orNull(userInput); if (age != null) { console.log("Valid age:", age); } // ✅ Good: Default fallback const maxRetries = PositiveInt.orNull(config.retries) ?? 3; // ❌ Avoid: When you need to know why validation failed (use `from` instead) const result = PositiveInt.from(userInput); if (!result.ok) { console.error(formatPositiveError(result.error)); }` | - | [packages/common/src/Type.ts:315](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L315) |
| <a id="orthrow"></a> `orThrow` | `readonly` | (`value`) => `T` | Creates `T` from an `Input` value, throwing an error if validation fails. Throws an Error with the Type validation error in its `cause` property, making it debuggable while avoiding the need for custom error messages. This is a convenience method that combines `from` with `getOrThrow`. **When to use:** - Configuration values that are guaranteed to be valid (e.g., hardcoded constants) - Application startup where failure should crash the program - As an alternative to assertions when the Type error in the thrown Error's `cause` provides sufficient debugging information - Test code with known valid inputs (when error message clarity is not critical; for better test error messages, use Vitest `schemaMatching` + `assert` with `.is()`) ### Example `// ✅ Good: Known valid constant const maxRetries = PositiveInt.orThrow(3); // ✅ Good: App configuration that should crash on invalid values const appName = SimpleName.orThrow("MyApp"); // ✅ Good: Instead of assert when Type error is clear enough // Context makes it obvious: count increments from non-negative value const currentCount = counts.get(id) ?? 0; const newCount = PositiveInt.orThrow(currentCount + 1); // ✅ Good: Test setup with known valid values const testUser = User.orThrow({ name: "Alice", age: 30 }); // ❌ Avoid: User input (use `from` instead) const userAge = PositiveInt.orThrow(userInput); // Could crash! // ✅ Better: Handle user input gracefully const ageResult = PositiveInt.from(userInput); if (!ageResult.ok) { // Handle validation error }` | - | [packages/common/src/Type.ts:284](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L284) |
| <a id="parent-1"></a> `Parent` | `public` | `Parent` | The parent type. ### Example `type StringParent = typeof String.Parent;` | - | [packages/common/src/Type.ts:223](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L223) |
| <a id="parenterror-1"></a> `ParentError` | `public` | `ParentError` | The parent's error. ### Example `type StringParentError = typeof String.ParentError;` | - | [packages/common/src/Type.ts:225](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L225) |
| <a id="type"></a> `Type` | `readonly` | `T` | The type this Type resolves to. ### Example `type String = typeof String.Type;` | - | [packages/common/src/Type.ts:364](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L364) |
TypeError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / TypeError
# Interface: TypeError\<Name\>
Defined in: [packages/common/src/Type.ts:427](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L427)
## Extended by
- [`TypeErrorWithReason`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeErrorWithReason)
- [`StringError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/StringError)
- [`NumberError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/NumberError)
- [`BigIntError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/BigIntError)
- [`BooleanError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/BooleanError)
- [`UndefinedError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/UndefinedError)
- [`NullError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/NullError)
- [`FunctionError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/FunctionError)
- [`Uint8ArrayError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Uint8ArrayError)
- [`InstanceOfError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/InstanceOfError)
- [`EvoluTypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/EvoluTypeError)
- [`BrandWithoutRefineError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/BrandWithoutRefineError)
- [`CurrencyCodeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/CurrencyCodeError)
- [`DateIsoError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/DateIsoError)
- [`TrimmedError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TrimmedError)
- [`MinLengthError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/MinLengthError)
- [`MaxLengthError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/MaxLengthError)
- [`LengthError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/LengthError)
- [`MnemonicError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/MnemonicError)
- [`RegexError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/RegexError)
- [`Base64UrlError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Base64UrlError)
- [`SimpleNameError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/SimpleNameError)
- [`IdError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/IdError)
- [`TableIdError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TableIdError)
- [`PositiveError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/PositiveError)
- [`NegativeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/NegativeError)
- [`NonPositiveError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/NonPositiveError)
- [`NonNegativeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/NonNegativeError)
- [`IntError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/IntError)
- [`GreaterThanError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/GreaterThanError)
- [`LessThanError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/LessThanError)
- [`GreaterThanOrEqualToError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/GreaterThanOrEqualToError)
- [`LessThanOrEqualToError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/LessThanOrEqualToError)
- [`NonNaNError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/NonNaNError)
- [`FiniteError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/FiniteError)
- [`MultipleOfError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/MultipleOfError)
- [`BetweenError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/BetweenError)
- [`LiteralError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/LiteralError)
- [`UnionError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/UnionError)
- [`Int64Error`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Int64Error)
- [`Int64StringError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Int64StringError)
- [`JsonError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/JsonError)
- [`ValidMutationSizeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/ValidMutationSizeError)
- [`ValidDbChangeValuesError`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/ValidDbChangeValuesError)
## Type Parameters
| Type Parameter | Default type |
| ---------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
| `Name` _extends_ [`TypeName`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/TypeName) | [`TypeName`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/TypeName) |
## Properties
| Property | Modifier | Type | Description | Defined in |
| -------------------------- | ---------- | --------- | -------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="type"></a> `type` | `readonly` | `Name` | - | [packages/common/src/Type.ts:428](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L428) |
| <a id="value"></a> `value` | `readonly` | `unknown` | The value that was received and caused the error. Provides additional context for debugging and validation feedback. | [packages/common/src/Type.ts:434](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L434) |
TypeErrorWithReason - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / TypeErrorWithReason
# Interface: TypeErrorWithReason\<Name, Reason\>
Defined in: [packages/common/src/Type.ts:437](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L437)
## Extends
- [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError)\<`Name`\>
## Extended by
- [`ArrayError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/ArrayError)
- [`SetError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/SetError)
- [`RecordError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/RecordError)
- [`ObjectError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/ObjectError)
- [`ObjectWithRecordError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/ObjectWithRecordError)
- [`TupleError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TupleError)
## Type Parameters
| Type Parameter | Default type |
| ---------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
| `Name` _extends_ [`TypeName`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/TypeName) | [`TypeName`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/TypeName) |
| `Reason` _extends_ `object` | `object` |
## Properties
| Property | Modifier | Type | Description | Inherited from | Defined in |
| ------------------------------ | ---------- | --------- | -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="reason-1"></a> `reason` | `readonly` | `Reason` | The detailed reason for the error, represented as a tagged union. | - | [packages/common/src/Type.ts:444](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L444) |
| <a id="type"></a> `type` | `readonly` | `Name` | - | [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError).[`type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError.mdx#type) | [packages/common/src/Type.ts:428](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L428) |
| <a id="value"></a> `value` | `readonly` | `unknown` | The value that was received and caused the error. Provides additional context for debugging and validation feedback. | [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError).[`value`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError.mdx#value) | [packages/common/src/Type.ts:434](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L434) |
Uint8ArrayError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / Uint8ArrayError
# Interface: Uint8ArrayError
Defined in: [packages/common/src/Type.ts:754](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L754)
## Extends
- [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError)\<`"Uint8Array"`\>
## Properties
| Property | Modifier | Type | Description | Inherited from | Defined in |
| -------------------------- | ---------- | -------------- | -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="type"></a> `type` | `readonly` | `"Uint8Array"` | - | [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError).[`type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError.mdx#type) | [packages/common/src/Type.ts:428](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L428) |
| <a id="value"></a> `value` | `readonly` | `unknown` | The value that was received and caused the error. Provides additional context for debugging and validation feedback. | [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError).[`value`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError.mdx#value) | [packages/common/src/Type.ts:434](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L434) |
UndefinedError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / UndefinedError
# Interface: UndefinedError
Defined in: [packages/common/src/Type.ts:721](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L721)
## Extends
- [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError)\<`"Undefined"`\>
## Properties
| Property | Modifier | Type | Description | Inherited from | Defined in |
| -------------------------- | ---------- | ------------- | -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="type"></a> `type` | `readonly` | `"Undefined"` | - | [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError).[`type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError.mdx#type) | [packages/common/src/Type.ts:428](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L428) |
| <a id="value"></a> `value` | `readonly` | `unknown` | The value that was received and caused the error. Provides additional context for debugging and validation feedback. | [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError).[`value`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError.mdx#value) | [packages/common/src/Type.ts:434](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L434) |
UnionError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / UnionError
# Interface: UnionError\<E\>
Defined in: [packages/common/src/Type.ts:3300](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L3300)
## Extends
- [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError)\<`"Union"`\>
## Type Parameters
| Type Parameter | Default type |
| ------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
| `E` _extends_ [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError) | [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError) |
## Properties
| Property | Modifier | Type | Description | Inherited from | Defined in |
| ---------------------------- | ---------- | --------- | -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="errors"></a> `errors` | `readonly` | `E`[] | - | - | [packages/common/src/Type.ts:3303](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L3303) |
| <a id="type"></a> `type` | `readonly` | `"Union"` | - | [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError).[`type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError.mdx#type) | [packages/common/src/Type.ts:428](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L428) |
| <a id="value"></a> `value` | `readonly` | `unknown` | The value that was received and caused the error. Provides additional context for debugging and validation feedback. | [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError).[`value`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError.mdx#value) | [packages/common/src/Type.ts:434](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L434) |
UnionType - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / UnionType
# Interface: UnionType\<Members\>
Defined in: [packages/common/src/Type.ts:3287](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L3287)
UnionType extends [Type](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type) with an additional `members` property for
reflection.
## Extends
- [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type)\<`"Union"`, [`InferType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferType)\<`Members`\[`number`\]\>, [`InferInput`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferInput)\<`Members`\[`number`\]\>, [`UnionError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/UnionError)\<[`InferErrors`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferErrors)\<`Members`\[`number`\]\>\>, [`InferInput`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferInput)\<`Members`\[`number`\]\>, `never`\>
## Type Parameters
| Type Parameter |
| -------------------------------------------------------------------------------------------------------------------------- |
| `Members` _extends_ \[[`AnyType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/AnyType), `...ReadonlyArray<AnyType>`\] |
## Properties
| Property | Modifier | Type | Description | Inherited from | Defined in |
| ------------------------------------------------ | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="evolutypesymbol"></a> `[EvoluTypeSymbol]` | `readonly` | `true` | - | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`[EvoluTypeSymbol]`](/docs/api-reference/common/Type/interfaces/Type.mdx#evolutypesymbol) | [packages/common/src/Type.ts:353](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L353) |
| <a id="standard"></a> `~standard` | `readonly` | [`Props`](https://evolu.dev/docs/api-reference/common/Type/namespaces/StandardSchemaV1/interfaces/Props)\<[`InferInput`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferInput)\<`Members`\[`number`\]\>, [`InferType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferType)\<`Members`\[`number`\]\>\> | The Standard Schema properties. | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`~standard`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#standard) | [packages/common/src/Type.ts:4450](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L4450) |
| <a id="error"></a> `Error` | `public` | [`UnionError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/UnionError)\<[`InferErrors`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferErrors)\<`Members`\[`number`\]\>\> | The specific error introduced by this Type. ### Example `type StringError = typeof String.Error;` | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`Error`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#error) | [packages/common/src/Type.ts:221](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L221) |
| <a id="errors"></a> `Errors` | `readonly` | [`UnionError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/UnionError)\<[`InferErrors`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferErrors)\<`Members`\[`number`\]\>\> | ### Example `type StringParentErrors = typeof String.Errors;` | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`Errors`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#errors) | [packages/common/src/Type.ts:417](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L417) |
| <a id="from"></a> `from` | `readonly` | (`value`) => [`Result`](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result)\<[`InferType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferType)\<`Members`\[`number`\]\>, [`UnionError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/UnionError)\<[`InferErrors`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferErrors)\<`Members`\[`number`\]\>\>\> | Creates `T` from an `Input` value. This is useful when we have a typed value. `from` is a typed alias of `fromUnknown`. | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`from`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#from) | [packages/common/src/Type.ts:236](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L236) |
| <a id="fromparent"></a> `fromParent` | `readonly` | (`value`) => [`Result`](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result)\<[`InferType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferType)\<`Members`\[`number`\]\>, [`UnionError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/UnionError)\<[`InferErrors`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferErrors)\<`Members`\[`number`\]\>\>\> | Creates `T` from `Parent` type. This function skips parent Types validations when we have already partially validated value. | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`fromParent`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#fromparent) | [packages/common/src/Type.ts:330](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L330) |
| <a id="fromunknown"></a> `fromUnknown` | `readonly` | (`value`) => [`Result`](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result)\<[`InferType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferType)\<`Members`\[`number`\]\>, [`UnionError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/UnionError)\<[`InferErrors`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferErrors)\<`Members`\[`number`\]\>\>\> | Creates `T` from an unknown value. This is useful when a value is unknown. | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`fromUnknown`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#fromunknown) | [packages/common/src/Type.ts:322](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L322) |
| <a id="input"></a> `Input` | `public` | [`InferInput`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferInput)\<`Members`\[`number`\]\> | The type expected by `from` and `fromUnknown`. ### Example `type StringInput = typeof String.Input;` | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`Input`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#input) | [packages/common/src/Type.ts:219](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L219) |
| <a id="is"></a> `is` | `readonly` | [`Refinement`](https://evolu.dev/docs/api-reference/common/Types/type-aliases/Refinement)\<`unknown`, [`InferType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferType)\<`Members`\[`number`\]\>\> | A **type guard** that checks whether an unknown value satisfies the [Type](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type). ### Example `const value: unknown = "hello"; if (String.is(value)) { // TypeScript now knows `value`is a`string` here. console.log("This is a valid string!"); } const strings: unknown[] = [1, "hello", true, "world"]; const filteredStrings = strings.filter(String.is); console.log(filteredStrings); // ["hello", "world"]` | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`is`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#is) | [packages/common/src/Type.ts:351](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L351) |
| <a id="members-1"></a> `members` | `readonly` | `Members` | - | - | [packages/common/src/Type.ts:3297](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L3297) |
| <a id="name"></a> `name` | `readonly` | `"Union"` | - | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`name`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#name-1) | [packages/common/src/Type.ts:227](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L227) |
| <a id="ornull"></a> `orNull` | `readonly` | (`value`) => \| [`InferType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferType)\<`Members`\[`number`\]\> \| `null` | Creates `T` from an `Input` value, returning `null` if validation fails. This is a convenience method that combines `from` with `getOrNull`. **When to use:** - When you need to convert a validation result to a nullable value - When the error is not important and you just want the value or nothing ### Example `// ✅ Good: Optional user input const age = PositiveInt.orNull(userInput); if (age != null) { console.log("Valid age:", age); } // ✅ Good: Default fallback const maxRetries = PositiveInt.orNull(config.retries) ?? 3; // ❌ Avoid: When you need to know why validation failed (use `from` instead) const result = PositiveInt.from(userInput); if (!result.ok) { console.error(formatPositiveError(result.error)); }` | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`orNull`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#ornull) | [packages/common/src/Type.ts:315](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L315) |
| <a id="orthrow"></a> `orThrow` | `readonly` | (`value`) => [`InferType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferType) | Creates `T` from an `Input` value, throwing an error if validation fails. Throws an Error with the Type validation error in its `cause` property, making it debuggable while avoiding the need for custom error messages. This is a convenience method that combines `from` with `getOrThrow`. **When to use:** - Configuration values that are guaranteed to be valid (e.g., hardcoded constants) - Application startup where failure should crash the program - As an alternative to assertions when the Type error in the thrown Error's `cause` provides sufficient debugging information - Test code with known valid inputs (when error message clarity is not critical; for better test error messages, use Vitest `schemaMatching` + `assert` with `.is()`) ### Example `// ✅ Good: Known valid constant const maxRetries = PositiveInt.orThrow(3); // ✅ Good: App configuration that should crash on invalid values const appName = SimpleName.orThrow("MyApp"); // ✅ Good: Instead of assert when Type error is clear enough // Context makes it obvious: count increments from non-negative value const currentCount = counts.get(id) ?? 0; const newCount = PositiveInt.orThrow(currentCount + 1); // ✅ Good: Test setup with known valid values const testUser = User.orThrow({ name: "Alice", age: 30 }); // ❌ Avoid: User input (use `from` instead) const userAge = PositiveInt.orThrow(userInput); // Could crash! // ✅ Better: Handle user input gracefully const ageResult = PositiveInt.from(userInput); if (!ageResult.ok) { // Handle validation error }` | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`orThrow`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#orthrow) | [packages/common/src/Type.ts:284](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L284) |
| <a id="parent"></a> `Parent` | `public` | [`InferInput`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferInput)\<`Members`\[`number`\]\> | The parent type. ### Example `type StringParent = typeof String.Parent;` | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`Parent`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#parent) | [packages/common/src/Type.ts:223](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L223) |
| <a id="parenterror"></a> `ParentError` | `public` | `never` | The parent's error. ### Example `type StringParentError = typeof String.ParentError;` | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`ParentError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#parenterror) | [packages/common/src/Type.ts:225](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L225) |
| <a id="type"></a> `Type` | `readonly` | [`InferType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferType) | The type this Type resolves to. ### Example `type String = typeof String.Type;` | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).[`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type.mdx#type) | [packages/common/src/Type.ts:364](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L364) |
ValidMutationSizeError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / ValidMutationSizeError
# Interface: ValidMutationSizeError
Defined in: [packages/common/src/Type.ts:4027](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L4027)
## Extends
- [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError)\<`"ValidMutationSize"`\>
## Properties
| Property | Modifier | Type | Description | Inherited from | Defined in |
| -------------------------- | ---------- | --------------------- | -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="type"></a> `type` | `readonly` | `"ValidMutationSize"` | - | [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError).[`type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError.mdx#type) | [packages/common/src/Type.ts:428](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L428) |
| <a id="value"></a> `value` | `readonly` | `unknown` | The value that was received and caused the error. Provides additional context for debugging and validation feedback. | [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError).[`value`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError.mdx#value) | [packages/common/src/Type.ts:434](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L434) |
API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / StandardSchemaV1
# StandardSchemaV1
## Interfaces
| Interface | Description |
| --------------------------------------------------------------------------------------------------------- | -------------------------------------------- |
| [FailureResult](https://evolu.dev/docs/api-reference/common/Type/namespaces/StandardSchemaV1/interfaces/FailureResult) | The result interface if validation fails. |
| [Issue](https://evolu.dev/docs/api-reference/common/Type/namespaces/StandardSchemaV1/interfaces/Issue) | The issue interface of the failure output. |
| [PathSegment](https://evolu.dev/docs/api-reference/common/Type/namespaces/StandardSchemaV1/interfaces/PathSegment) | The path segment interface of the issue. |
| [Props](https://evolu.dev/docs/api-reference/common/Type/namespaces/StandardSchemaV1/interfaces/Props) | The Standard Schema properties interface. |
| [SuccessResult](https://evolu.dev/docs/api-reference/common/Type/namespaces/StandardSchemaV1/interfaces/SuccessResult) | The result interface if validation succeeds. |
| [Types](https://evolu.dev/docs/api-reference/common/Type/namespaces/StandardSchemaV1/interfaces/Types) | The Standard Schema types interface. |
## Type Aliases
| Type Alias | Description |
| ------------------------------------------------------------------------------------------------------- | ---------------------------------------------- |
| [InferInput](https://evolu.dev/docs/api-reference/common/Type/namespaces/StandardSchemaV1/type-aliases/InferInput) | Infers the input type of a Standard Schema. |
| [InferOutput](https://evolu.dev/docs/api-reference/common/Type/namespaces/StandardSchemaV1/type-aliases/InferOutput) | Infers the output type of a Standard Schema. |
| [Result](https://evolu.dev/docs/api-reference/common/Type/namespaces/StandardSchemaV1/type-aliases/Result) | The result interface of the validate function. |
AnyType - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / AnyType
# Type Alias: AnyType
```ts
type AnyType = Type<any, any, any, any, any, any>;
```
Defined in: [packages/common/src/Type.ts:447](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L447)
Base64Url - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / Base64Url
# Type Alias: Base64Url
```ts
type Base64Url = typeof Type;
```
Defined in: [packages/common/src/Type.ts:1446](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1446)
BrandFactory - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / BrandFactory
# Type Alias: BrandFactory()\<Name, Input, RefineError\>
```ts
type BrandFactory<Name, Input, RefineError> = <
PName,
P,
PInput,
PParent,
PError,
PParentError,
>(
parent,
) => BrandType<
Type<PName, P, PInput, PError, PParent, PParentError>,
Name,
RefineError,
PError | PParentError
>;
```
Defined in: [packages/common/src/Type.ts:1142](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1142)
Helper type for Type Factory that creates a branded Type.
### Example
```ts
const trimmed: BrandFactory<"Trimmed", string, TrimmedError> = (parent) =>
brand("Trimmed", parent, (value) =>
value.trim().length === value.length
? ok(value)
: err<TrimmedError>({ type: "Trimmed", value }),
);
```
## Type Parameters
| Type Parameter |
| ----------------------------------------------------------------------------------------------- |
| `Name` _extends_ [`TypeName`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/TypeName) |
| `Input` |
| `RefineError` _extends_ [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError) |
## Type Parameters
| Type Parameter | Default type |
| ------------------------------------------------------------------------------------------------ | ------------ |
| `PName` _extends_ [`TypeName`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/TypeName) | - |
| `P` _extends_ `Input` | - |
| `PInput` | - |
| `PParent` | - |
| `PError` _extends_ [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError) | `never` |
| `PParentError` _extends_ [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError) | `never` |
## Parameters
| Parameter | Type |
| --------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `parent` | [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type)\<`PName`, `P`, `PInput`, `PError`, `PParent`, `PParentError`\> |
## Returns
[`BrandType`](https://evolu.dev/docs/api-reference/common/Type/interfaces/BrandType)\<[`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type)\<`PName`, `P`, `PInput`, `PError`, `PParent`, `PParentError`\>, `Name`, `RefineError`, `PError` \| `PParentError`\>
CurrencyCode - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / CurrencyCode
# Type Alias: CurrencyCode
```ts
type CurrencyCode = typeof Type;
```
Defined in: [packages/common/src/Type.ts:1058](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1058)
DateIso - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / DateIso
# Type Alias: DateIso
```ts
type DateIso = typeof Type;
```
Defined in: [packages/common/src/Type.ts:1094](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1094)
FiniteNumber - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / FiniteNumber
# Type Alias: FiniteNumber
```ts
type FiniteNumber = typeof Type;
```
Defined in: [packages/common/src/Type.ts:2166](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L2166)
Id - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / Id
# Type Alias: Id
```ts
type Id = typeof Type;
```
Defined in: [packages/common/src/Type.ts:1617](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1617)
IdBytes - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / IdBytes
# Type Alias: IdBytes
```ts
type IdBytes = typeof Type;
```
Defined in: [packages/common/src/Type.ts:1787](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1787)
InferError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / InferError
# Type Alias: InferError\<A\>
```ts
type InferError<A> =
A extends Type<any, any, any, infer Error, any, any> ? Error : never;
```
Defined in: [packages/common/src/Type.ts:478](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L478)
Extracts the specific error type from a [Type](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).
## Type Parameters
| Type Parameter |
| ----------------------------------------------------------------------------------- |
| `A` _extends_ [`AnyType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/AnyType) |
InferErrors - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / InferErrors
# Type Alias: InferErrors\<T\>
```ts
type InferErrors<T> =
T extends Type<any, any, any, infer Error, any, infer ParentError>
? Error | ParentError
: never;
```
Defined in: [packages/common/src/Type.ts:504](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L504)
Extracts all error types from a [Type](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).
## Type Parameters
| Type Parameter |
| ----------------------------------------------------------------------------------- |
| `T` _extends_ [`AnyType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/AnyType) |
InferInput - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / InferInput
# Type Alias: InferInput\<A\>
```ts
type InferInput<A> =
A extends Type<any, any, infer Input, any, any, any> ? Input : never;
```
Defined in: [packages/common/src/Type.ts:470](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L470)
Extracts the input type from a [Type](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).
## Type Parameters
| Type Parameter |
| ----------------------------------------------------------------------------------- |
| `A` _extends_ [`AnyType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/AnyType) |
InferName - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / InferName
# Type Alias: InferName\<A\>
```ts
type InferName<A> =
A extends Type<infer Name, any, any, any, any, any> ? Name : never;
```
Defined in: [packages/common/src/Type.ts:454](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L454)
Extracts the name from a [Type](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).
## Type Parameters
| Type Parameter |
| ----------------------------------------------------------------------------------- |
| `A` _extends_ [`AnyType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/AnyType) |
InferParent - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / InferParent
# Type Alias: InferParent\<A\>
```ts
type InferParent<A> =
A extends Type<any, any, any, any, infer Parent, any> ? Parent : never;
```
Defined in: [packages/common/src/Type.ts:486](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L486)
Extracts the parent type from a [Type](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).
## Type Parameters
| Type Parameter |
| ----------------------------------------------------------------------------------- |
| `A` _extends_ [`AnyType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/AnyType) |
InferParentError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / InferParentError
# Type Alias: InferParentError\<A\>
```ts
type InferParentError<A> =
A extends Type<any, any, any, any, any, infer ParentError>
? ParentError
: never;
```
Defined in: [packages/common/src/Type.ts:494](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L494)
Extracts the parent error type from a [Type](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).
## Type Parameters
| Type Parameter |
| ----------------------------------------------------------------------------------- |
| `A` _extends_ [`AnyType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/AnyType) |
InferType - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / InferType
# Type Alias: InferType\<A\>
```ts
type InferType<A> =
A extends Type<any, infer T, any, any, any, any> ? T : never;
```
Defined in: [packages/common/src/Type.ts:462](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L462)
Extracts the type from a [Type](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).
## Type Parameters
| Type Parameter |
| ----------------------------------------------------------------------------------- |
| `A` _extends_ [`AnyType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/AnyType) |
Int - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / Int
# Type Alias: Int
```ts
type Int = typeof Type;
```
Defined in: [packages/common/src/Type.ts:1970](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1970)
Int64 - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / Int64
# Type Alias: Int64
```ts
type Int64 = typeof Type;
```
Defined in: [packages/common/src/Type.ts:3614](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L3614)
Int64String - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / Int64String
# Type Alias: Int64String
```ts
type Int64String = typeof Type;
```
Defined in: [packages/common/src/Type.ts:3632](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L3632)
IsUnionWithNull - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / IsUnionWithNull
# Type Alias: IsUnionWithNull\<U\>
```ts
type IsUnionWithNull<U> =
U extends UnionType<infer Members>
? Members extends [AnyType, ...AnyType[]]
? NullTypeInMembers<Members>
: false
: false;
```
Defined in: [packages/common/src/Type.ts:3974](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L3974)
## Type Parameters
| Type Parameter |
| ----------------------------------------------------------------------------------- |
| `U` _extends_ [`AnyType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/AnyType) |
Json - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / Json
# Type Alias: Json
```ts
type Json = typeof Type;
```
Defined in: [packages/common/src/Type.ts:3768](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L3768)
JsonArray - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / JsonArray
# Type Alias: JsonArray
```ts
type JsonArray = ReadonlyArray<JsonValue>;
```
Defined in: [packages/common/src/Type.ts:3686](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L3686)
JsonArrayInput - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / JsonArrayInput
# Type Alias: JsonArrayInput
```ts
type JsonArrayInput = ReadonlyArray<JsonValueInput>;
```
Defined in: [packages/common/src/Type.ts:3687](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L3687)
JsonValue - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / JsonValue
# Type Alias: JsonValue
```ts
type JsonValue =
| string
| FiniteNumber
| boolean
| null
| JsonArray
| JsonObject;
```
Defined in: [packages/common/src/Type.ts:3652](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L3652)
JsonValueError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / JsonValueError
# Type Alias: JsonValueError
```ts
type JsonValueError = UnionError<
| StringError
| BooleanError
| NullError
| FiniteError
| NumberError
| ArrayError<JsonValueError>
| RecordError<StringError, JsonValueError>
>;
```
Defined in: [packages/common/src/Type.ts:3668](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L3668)
JsonValueInput - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / JsonValueInput
# Type Alias: JsonValueInput
```ts
type JsonValueInput =
| string
| number
| boolean
| null
| JsonArrayInput
| JsonObjectInput;
```
Defined in: [packages/common/src/Type.ts:3660](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L3660)
MergeObjectTypeErrors - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / MergeObjectTypeErrors
# Type Alias: MergeObjectTypeErrors\<T\>
```ts
type MergeObjectTypeErrors<T> =
T extends ObjectType<infer Props>
? ObjectError<{ [K in keyof Props]: InferErrors<Props[K]> }>
: never;
```
Defined in: [packages/common/src/Type.ts:3097](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L3097)
Merge Error and ParentError into one ObjectError so tooltips and error
messages are easier to read.
## Type Parameters
| Type Parameter |
| ------------------------------------------------------------------------------------------------ |
| `T` _extends_ [`ObjectType`](https://evolu.dev/docs/api-reference/common/Type/interfaces/ObjectType)\<`any`\> |
Mnemonic - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / Mnemonic
# Type Alias: Mnemonic
```ts
type Mnemonic = typeof Type;
```
Defined in: [packages/common/src/Type.ts:1354](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1354)
NegativeInt - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / NegativeInt
# Type Alias: NegativeInt
```ts
type NegativeInt = typeof Type;
```
Defined in: [packages/common/src/Type.ts:2007](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L2007)
NegativeNumber - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / NegativeNumber
# Type Alias: NegativeNumber
```ts
type NegativeNumber = typeof Type;
```
Defined in: [packages/common/src/Type.ts:1938](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1938)
NonEmptyString - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / NonEmptyString
# Type Alias: NonEmptyString
```ts
type NonEmptyString = typeof Type;
```
Defined in: [packages/common/src/Type.ts:1306](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1306)
NonEmptyString100 - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / NonEmptyString100
# Type Alias: NonEmptyString100
```ts
type NonEmptyString100 = typeof Type;
```
Defined in: [packages/common/src/Type.ts:1318](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1318)
NonEmptyString1000 - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / NonEmptyString1000
# Type Alias: NonEmptyString1000
```ts
type NonEmptyString1000 = typeof Type;
```
Defined in: [packages/common/src/Type.ts:1322](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1322)
NonEmptyTrimmedString - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / NonEmptyTrimmedString
# Type Alias: NonEmptyTrimmedString
```ts
type NonEmptyTrimmedString = typeof Type;
```
Defined in: [packages/common/src/Type.ts:1326](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1326)
NonEmptyTrimmedString100 - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / NonEmptyTrimmedString100
# Type Alias: NonEmptyTrimmedString100
```ts
type NonEmptyTrimmedString100 = typeof Type;
```
Defined in: [packages/common/src/Type.ts:1338](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1338)
NonEmptyTrimmedString1000 - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / NonEmptyTrimmedString1000
# Type Alias: NonEmptyTrimmedString1000
```ts
type NonEmptyTrimmedString1000 = typeof Type;
```
Defined in: [packages/common/src/Type.ts:1342](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1342)
NonNaNNumber - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / NonNaNNumber
# Type Alias: NonNaNNumber
```ts
type NonNaNNumber = typeof Type;
```
Defined in: [packages/common/src/Type.ts:2132](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L2132)
NonNegativeInt - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / NonNegativeInt
# Type Alias: NonNegativeInt
```ts
type NonNegativeInt = typeof Type;
```
Defined in: [packages/common/src/Type.ts:1978](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1978)
NonNegativeNumber - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / NonNegativeNumber
# Type Alias: NonNegativeNumber
```ts
type NonNegativeNumber = typeof Type;
```
Defined in: [packages/common/src/Type.ts:1914](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1914)
NonPositiveInt - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / NonPositiveInt
# Type Alias: NonPositiveInt
```ts
type NonPositiveInt = typeof Type;
```
Defined in: [packages/common/src/Type.ts:1999](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1999)
NonPositiveNumber - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / NonPositiveNumber
# Type Alias: NonPositiveNumber
```ts
type NonPositiveNumber = typeof Type;
```
Defined in: [packages/common/src/Type.ts:1930](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1930)
NullTypeInMembers - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / NullTypeInMembers
# Type Alias: NullTypeInMembers\<Members\>
```ts
type NullTypeInMembers<Members> = Members extends [infer Head, ...infer Tail]
? Head extends typeof Null
? true
: Tail extends [AnyType, ...AnyType[]]
? NullTypeInMembers<Tail>
: false
: false;
```
Defined in: [packages/common/src/Type.ts:3981](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L3981)
## Type Parameters
| Type Parameter |
| ------------------------------------------------------------------------------------------------------------- |
| `Members` _extends_ \[[`AnyType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/AnyType), `...AnyType[]`\] |
NullableToOptionalProps - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / NullableToOptionalProps
# Type Alias: NullableToOptionalProps\<Props\>
```ts
type NullableToOptionalProps<Props> = {
[K in keyof Props]: TransformNullable<Props[K]>;
};
```
Defined in: [packages/common/src/Type.ts:3967](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L3967)
## Type Parameters
| Type Parameter |
| ------------------------------------------------------------------------------------------------------------- |
| `Props` _extends_ `Record`\<`string`, [`AnyType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/AnyType)\> |
PositiveInt - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / PositiveInt
# Type Alias: PositiveInt
```ts
type PositiveInt = typeof Type;
```
Defined in: [packages/common/src/Type.ts:1986](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1986)
PositiveNumber - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / PositiveNumber
# Type Alias: PositiveNumber
```ts
type PositiveNumber = typeof Type;
```
Defined in: [packages/common/src/Type.ts:1922](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1922)
SimpleName - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / SimpleName
# Type Alias: SimpleName
```ts
type SimpleName = typeof Type;
```
Defined in: [packages/common/src/Type.ts:1543](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1543)
SimplePassword - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / SimplePassword
# Type Alias: SimplePassword
```ts
type SimplePassword = typeof Type;
```
Defined in: [packages/common/src/Type.ts:1575](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1575)
SimplePasswordError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / SimplePasswordError
# Type Alias: SimplePasswordError
```ts
type SimplePasswordError = typeof SimplePassword.Error;
```
Defined in: [packages/common/src/Type.ts:1581](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1581)
String100 - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / String100
# Type Alias: String100
```ts
type String100 = typeof Type;
```
Defined in: [packages/common/src/Type.ts:1310](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1310)
String1000 - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / String1000
# Type Alias: String1000
```ts
type String1000 = typeof Type;
```
Defined in: [packages/common/src/Type.ts:1314](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1314)
TransformNullable - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / TransformNullable
# Type Alias: TransformNullable\<P\>
```ts
type TransformNullable<P> =
IsUnionWithNull<P> extends true ? OptionalType<P> : P;
```
Defined in: [packages/common/src/Type.ts:3971](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L3971)
## Type Parameters
| Type Parameter |
| ----------------------------------------------------------------------------------- |
| `P` _extends_ [`AnyType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/AnyType) |
TrimmedString - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / TrimmedString
# Type Alias: TrimmedString
```ts
type TrimmedString = typeof Type;
```
Defined in: [packages/common/src/Type.ts:1201](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1201)
TrimmedString100 - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / TrimmedString100
# Type Alias: TrimmedString100
```ts
type TrimmedString100 = typeof Type;
```
Defined in: [packages/common/src/Type.ts:1330](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1330)
TrimmedString1000 - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / TrimmedString1000
# Type Alias: TrimmedString1000
```ts
type TrimmedString1000 = typeof Type;
```
Defined in: [packages/common/src/Type.ts:1334](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1334)
TypeErrorFormatter - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / TypeErrorFormatter
# Type Alias: TypeErrorFormatter()\<Error\>
```ts
type TypeErrorFormatter<Error> = (error) => string;
```
Defined in: [packages/common/src/Type.ts:606](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L606)
## Type Parameters
| Type Parameter |
| ----------------------------------------------------------------------------------------- |
| `Error` _extends_ [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError) |
## Parameters
| Parameter | Type |
| --------- | ------- |
| `error` | `Error` |
## Returns
`string`
TypeErrors - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / TypeErrors
# Type Alias: TypeErrors\<ExtraErrors\>
```ts
type TypeErrors<ExtraErrors> =
| StringError
| NumberError
| BigIntError
| BooleanError
| UndefinedError
| NullError
| FunctionError
| Uint8ArrayError
| InstanceOfError
| EvoluTypeError
| CurrencyCodeError
| DateIsoError
| TrimmedError
| MinLengthError
| MaxLengthError
| LengthError
| MnemonicError
| RegexError
| SimplePasswordError
| IdError
| TableIdError
| PositiveError
| NegativeError
| NonPositiveError
| NonNegativeError
| IntError
| GreaterThanError
| LessThanError
| GreaterThanOrEqualToError
| LessThanOrEqualToError
| NonNaNError
| FiniteError
| MultipleOfError
| BetweenError
| LiteralError
| Int64Error
| Int64StringError
| JsonError
| ValidMutationSizeError
| ExtraErrors
| ArrayError<TypeErrors<ExtraErrors>>
| SetError<TypeErrors<ExtraErrors>>
| RecordError<TypeErrors<ExtraErrors>, TypeErrors<ExtraErrors>>
| ObjectError<Record<string, TypeErrors<ExtraErrors>>>
| ObjectWithRecordError<
Record<string, TypeErrors<ExtraErrors>>,
TypeErrors<ExtraErrors>,
TypeErrors<ExtraErrors>
>
| UnionError<TypeErrors<ExtraErrors>>
| TupleError<TypeErrors<ExtraErrors>>;
```
Defined in: [packages/common/src/Type.ts:4056](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L4056)
Union of all `TypeError`s 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.
This type is **recursive**, meaning errors can be nested within composite
structures like arrays, objects, records, unions, and tuples.
Used by [createFormatTypeError](https://evolu.dev/docs/api-reference/common/Type/functions/createFormatTypeError) to generate human-readable error
messages.
## Type Parameters
| Type Parameter | Default type |
| ----------------------------------------------------------------------------------------------- | ------------ |
| `ExtraErrors` _extends_ [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError) | `never` |
TypeName - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / TypeName
# Type Alias: TypeName
```ts
type TypeName = Capitalize<string>;
```
Defined in: [packages/common/src/Type.ts:425](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L425)
Unique identifier for a [Type](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).
UrlSafeString - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / UrlSafeString
# Type Alias: UrlSafeString
```ts
type UrlSafeString = typeof Type;
```
Defined in: [packages/common/src/Type.ts:1434](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1434)
UrlSafeStringError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / UrlSafeStringError
# Type Alias: UrlSafeStringError
```ts
type UrlSafeStringError = typeof UrlSafeString.Error;
```
Defined in: [packages/common/src/Type.ts:1436](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1436)
ValidMutationSize - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / ValidMutationSize
# Type Alias: ValidMutationSize\<Props\>
```ts
type ValidMutationSize<Props> = BrandType<
ObjectType<Props>,
"ValidMutationSize",
ValidMutationSizeError,
InferErrors<ObjectType<Props>>
>;
```
Defined in: [packages/common/src/Type.ts:4035](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L4035)
## Type Parameters
| Type Parameter |
| ------------------------------------------------------------------------------------------------------------- |
| `Props` _extends_ `Record`\<`string`, [`AnyType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/AnyType)\> |
Base64Url - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / Base64Url
# Variable: Base64Url
```ts
const Base64Url: BrandType<
Type<"String", string, string, StringError, string, StringError>,
"Base64Url",
Base64UrlError,
StringError
>;
```
Defined in: [packages/common/src/Type.ts:1446](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1446)
Base64Url without padding.
Encode with [uint8ArrayToBase64Url](https://evolu.dev/docs/api-reference/common/Type/variables/uint8ArrayToBase64Url), decode with
[base64UrlToUint8Array](https://evolu.dev/docs/api-reference/common/Type/variables/base64UrlToUint8Array).
BigInt - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / BigInt
# Variable: BigInt
```ts
const BigInt: Type<"BigInt", bigint, bigint, BigIntError, bigint, BigIntError>;
```
Defined in: [packages/common/src/Type.ts:693](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L693)
Boolean - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / Boolean
# Variable: Boolean
```ts
const Boolean: Type<
"Boolean",
boolean,
boolean,
BooleanError,
boolean,
BooleanError
>;
```
Defined in: [packages/common/src/Type.ts:704](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L704)
CurrencyCode - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / CurrencyCode
# Variable: CurrencyCode
```ts
const CurrencyCode: BrandType<
Type<"String", string, string, StringError, string, StringError>,
"CurrencyCode",
CurrencyCodeError,
StringError
>;
```
Defined in: [packages/common/src/Type.ts:1058](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1058)
A three-letter ISO 4217 currency code (e.g., USD, EUR).
Date - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / Date
# Variable: Date
```ts
const Date: InstanceOfType<DateConstructor>;
```
Defined in: [packages/common/src/Type.ts:814](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L814)
JavaScript Date.
DateIso - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / DateIso
# Variable: DateIso
```ts
const DateIso: BrandType<
Type<"String", string, string, StringError, string, StringError>,
"DateIso",
DateIsoError,
StringError
>;
```
Defined in: [packages/common/src/Type.ts:1094](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1094)
ISO 8601 date-time string.
This [Type](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type) represents a date-time string that follows the ISO 8601
format and is compatible with SQLite, which lacks a native date type and
relies on ISO 8601 strings for sorting. Enforcing a 24-character format
ensures correct lexicographic ordering.
It must be a valid JavaScript Date string that can be parsed.
Valid range: `"0000-01-01T00:00:00.000Z"` to `"9999-12-31T23:59:59.999Z"`.
### Example
```ts
const result = DateIso.from("2023-01-01T12:00:00.000Z"); // ok
const error = DateIso.from("10000-01-01T00:00:00.000Z"); // err
```
EvoluType - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / EvoluType
# Variable: EvoluType
```ts
const EvoluType: Type<
"EvoluType",
AnyType,
AnyType,
EvoluTypeError,
AnyType,
EvoluTypeError
>;
```
Defined in: [packages/common/src/Type.ts:828](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L828)
Validates that an unknown value is an Evolu [Type](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type) (i.e., satisfies
`AnyType`).
### Example
```ts
const result = EvoluType.from(String); // ok(String)
const error = EvoluType.from("not a Type"); // err
```
FiniteNumber - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / FiniteNumber
# Variable: FiniteNumber
```ts
const FiniteNumber: BrandType<
Type<"Number", number, number, NumberError, number, NumberError>,
"Finite",
FiniteError,
NumberError
>;
```
Defined in: [packages/common/src/Type.ts:2166](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L2166)
Finite number.
This Type ensures that a number is finite.
**Why is this important?**
`JSON.stringify` serializes JavaScript numbers into `null` if they are not
finite (e.g., `Infinity`, `-Infinity`, or `NaN`). Using `FiniteNumber` helps
prevent these unexpected behaviors when working with JSON serialization.
Function - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / Function
# Variable: Function
```ts
const Function: Type<
"Function",
Function,
Function,
FunctionError,
Function,
FunctionError
>;
```
Defined in: [packages/common/src/Type.ts:736](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L736)
Id - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / Id
# Variable: Id
```ts
const Id: BrandType<
Type<"String", string, string, StringError, string, StringError>,
"Id",
IdError,
StringError
>;
```
Defined in: [packages/common/src/Type.ts:1617](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1617)
Evolu Id: 16 bytes encoded as a 22‑character Base64Url string.
There are three ways to create an Evolu Id:
- [createId](https://evolu.dev/docs/api-reference/common/Type/functions/createId) – default cryptographically secure random bytes
(privacy‑preserving)
- [createIdFromString](https://evolu.dev/docs/api-reference/common/Type/functions/createIdFromString) – deterministic: first 16 bytes of SHA‑256 of a
string
- [createIdAsUuidv7](https://evolu.dev/docs/api-reference/common/Type/functions/createIdAsUuidv7) – optional: embeds timestamp bits (UUID v7 layout)
Privacy: the default random Id does not leak creation time and is safe to
share or log. The UUID v7 variant leaks creation time anywhere the Id is
copied (logs, URLs, exports); only use it when you explicitly want insertion
locality for very large write‑heavy tables and accept timestamp exposure.
### Future
A possible hybrid masked‑time approach (`timestamp ^ H(cluster_id, timestamp
> > N)`) could provide locality without exposing raw creation time. See
> > https://brooker.co.za/blog/2025/10/22/uuidv7.html
IdBytes - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / IdBytes
# Variable: IdBytes
```ts
const IdBytes: BrandType<
BrandType<
Type<
"Uint8Array",
Uint8Array<ArrayBufferLike>,
Uint8Array<ArrayBufferLike>,
Uint8ArrayError,
Uint8Array<ArrayBufferLike>,
Uint8ArrayError
>,
"Length16",
LengthError<16>,
Uint8ArrayError
>,
"IdBytes",
BrandWithoutRefineError<"IdBytes", LengthError<16> | Uint8ArrayError>,
never
>;
```
Defined in: [packages/common/src/Type.ts:1787](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1787)
Binary representation of an [Id](https://evolu.dev/docs/api-reference/common/Type/variables/Id).
Int-1 - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / Int
# Variable: Int
```ts
const Int: BrandType<
Type<"Number", number, number, NumberError, number, NumberError>,
"Int",
IntError,
NumberError
>;
```
Defined in: [packages/common/src/Type.ts:1970](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1970)
Integer within the safe range of JavaScript numbers.
Int64 - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / Int64
# Variable: Int64
```ts
const Int64: BrandType<
Type<"BigInt", bigint, bigint, BigIntError, bigint, BigIntError>,
"Int64",
Int64Error,
BigIntError
>;
```
Defined in: [packages/common/src/Type.ts:3614](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L3614)
64-bit signed integer.
`Int64` represents a `BigInt` constrained to a 64-bit signed integer range,
which is useful for platforms that do not support the `bigint` type, such as
SQLite.
Because SQLite lacks a dedicated `bigint` type, it may return `number` or
'Int64` depending on the stored value or even a wrong value if a platform
wrapper does not support it. A workaround for SQLite is to insert 'Int64`
serialized as a string (SQLite will convert it to int) and manually cast the
result to a string in SQL query and then to `Int64` in JS.
https://www.sqlite.org/c3ref/int64.html
Int64String - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / Int64String
# Variable: Int64String
```ts
const Int64String: BrandType<
BrandType<
Type<
"Brand",
string & Brand<"Trimmed">,
string,
TrimmedError,
string,
StringError
>,
"MinLength1",
MinLengthError<1>,
StringError | TrimmedError
>,
"Int64",
Int64StringError,
StringError | TrimmedError | MinLengthError<1>
>;
```
Defined in: [packages/common/src/Type.ts:3632](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L3632)
Stringified [Int64](https://evolu.dev/docs/api-reference/common/Type/variables/Int64).
Json - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / Json
# Variable: Json
```ts
const Json: BrandType<
Type<"String", string, string, StringError, string, StringError>,
"Json",
JsonError,
StringError
>;
```
Defined in: [packages/common/src/Type.ts:3768](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L3768)
JSON-string [Type](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).
### Example
```ts
const result = Json.from('{"key":"value"}'); // ok
const error = Json.from("invalid json"); // err
```
JsonArray - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / JsonArray
# Variable: JsonArray
```ts
JsonArray: ArrayType<
RecursiveType<
UnionType<
[
Type<"String", string, string, StringError, string, StringError>,
BrandType<
Type<"Number", number, number, NumberError, number, NumberError>,
"Finite",
FiniteError,
NumberError
>,
Type<"Boolean", boolean, boolean, BooleanError, boolean, BooleanError>,
Type<"Null", null, null, NullError, null, NullError>,
ArrayType<
Type<
"Recursive",
JsonValue,
JsonValueInput,
JsonValueError,
JsonValueInput,
JsonValueError
>
>,
RecordType<
"String",
string,
string,
StringError,
string,
StringError,
Type<
"Recursive",
JsonValue,
JsonValueInput,
JsonValueError,
JsonValueInput,
JsonValueError
>
>,
]
>
>
>;
```
Defined in: [packages/common/src/Type.ts:3686](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L3686)
JSON-compatible array of [JsonValue](https://evolu.dev/docs/api-reference/common/Type/variables/JsonValue) elements.
JsonObject - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / JsonObject
# Variable: JsonObject
```ts
JsonObject: RecordType<
"String",
string,
string,
StringError,
string,
StringError,
RecursiveType<
UnionType<
[
Type<"String", string, string, StringError, string, StringError>,
BrandType<
Type<"Number", number, number, NumberError, number, NumberError>,
"Finite",
FiniteError,
NumberError
>,
Type<"Boolean", boolean, boolean, BooleanError, boolean, BooleanError>,
Type<"Null", null, null, NullError, null, NullError>,
ArrayType<
Type<
"Recursive",
JsonValue,
JsonValueInput,
JsonValueError,
JsonValueInput,
JsonValueError
>
>,
RecordType<
"String",
string,
string,
StringError,
string,
StringError,
Type<
"Recursive",
JsonValue,
JsonValueInput,
JsonValueError,
JsonValueInput,
JsonValueError
>
>,
]
>
>
>;
```
Defined in: [packages/common/src/Type.ts:3678](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L3678)
JSON-compatible object with string keys and [JsonValue](https://evolu.dev/docs/api-reference/common/Type/variables/JsonValue) values.
JsonValue - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / JsonValue
# Variable: JsonValue
```ts
JsonValue: RecursiveType<
UnionType<
[
Type<"String", string, string, StringError, string, StringError>,
BrandType<
Type<"Number", number, number, NumberError, number, NumberError>,
"Finite",
FiniteError,
NumberError
>,
Type<"Boolean", boolean, boolean, BooleanError, boolean, BooleanError>,
Type<"Null", null, null, NullError, null, NullError>,
ArrayType<
Type<
"Recursive",
JsonValue,
JsonValueInput,
JsonValueError,
JsonValueInput,
JsonValueError
>
>,
RecordType<
"String",
string,
string,
StringError,
string,
StringError,
Type<
"Recursive",
JsonValue,
JsonValueInput,
JsonValueError,
JsonValueInput,
JsonValueError
>
>,
]
>
>;
```
Defined in: [packages/common/src/Type.ts:3652](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L3652)
JSON-compatible value: string, [FiniteNumber](https://evolu.dev/docs/api-reference/common/Type/variables/FiniteNumber), boolean, null,
[JsonArray](https://evolu.dev/docs/api-reference/common/Type/variables/JsonArray), or [JsonObject](https://evolu.dev/docs/api-reference/common/Type/variables/JsonObject).
Mnemonic - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / Mnemonic
# Variable: Mnemonic
```ts
const Mnemonic: BrandType<
BrandType<
Type<
"Brand",
string & Brand<"Trimmed">,
string,
TrimmedError,
string,
StringError
>,
"MinLength1",
MinLengthError<1>,
StringError | TrimmedError
>,
"Mnemonic",
MnemonicError,
StringError | TrimmedError | MinLengthError<1>
>;
```
Defined in: [packages/common/src/Type.ts:1354](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1354)
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.
NegativeInt - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / NegativeInt
# Variable: NegativeInt
```ts
const NegativeInt: BrandType<
Type<
"Brand",
number & Brand<"Int"> & Brand<"NonPositive">,
number,
NonPositiveError,
number & Brand<"Int">,
IntError | NumberError
>,
"Negative",
NegativeError,
IntError | NumberError | NonPositiveError
>;
```
Defined in: [packages/common/src/Type.ts:2007](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L2007)
Negative integer (< 0).
NegativeNumber - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / NegativeNumber
# Variable: NegativeNumber
```ts
const NegativeNumber: BrandType<
Type<
"Brand",
number & Brand<"NonPositive">,
number,
NonPositiveError,
number,
NumberError
>,
"Negative",
NegativeError,
NumberError | NonPositiveError
>;
```
Defined in: [packages/common/src/Type.ts:1938](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1938)
Negative number (< 0).
NonEmptyString - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / NonEmptyString
# Variable: NonEmptyString
```ts
const NonEmptyString: BrandType<
Type<"String", string, string, StringError, string, StringError>,
"MinLength1",
MinLengthError<1>,
StringError
>;
```
Defined in: [packages/common/src/Type.ts:1306](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1306)
NonEmptyString100 - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / NonEmptyString100
# Variable: NonEmptyString100
```ts
const NonEmptyString100: BrandType<
Type<
"Brand",
string & Brand<"MaxLength100">,
string,
MaxLengthError<100>,
string,
StringError
>,
"MinLength1",
MinLengthError<1>,
StringError | MaxLengthError<100>
>;
```
Defined in: [packages/common/src/Type.ts:1318](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1318)
NonEmptyString1000 - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / NonEmptyString1000
# Variable: NonEmptyString1000
```ts
const NonEmptyString1000: BrandType<
Type<
"Brand",
string & Brand<"MaxLength1000">,
string,
MaxLengthError<1000>,
string,
StringError
>,
"MinLength1",
MinLengthError<1>,
StringError | MaxLengthError<1000>
>;
```
Defined in: [packages/common/src/Type.ts:1322](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1322)
NonEmptyTrimmedString - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / NonEmptyTrimmedString
# Variable: NonEmptyTrimmedString
```ts
const NonEmptyTrimmedString: BrandType<
Type<
"Brand",
string & Brand<"Trimmed">,
string,
TrimmedError,
string,
StringError
>,
"MinLength1",
MinLengthError<1>,
StringError | TrimmedError
>;
```
Defined in: [packages/common/src/Type.ts:1326](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1326)
NonEmptyTrimmedString100 - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / NonEmptyTrimmedString100
# Variable: NonEmptyTrimmedString100
```ts
const NonEmptyTrimmedString100: BrandType<
Type<
"Brand",
string & Brand<"Trimmed"> & Brand<"MaxLength100">,
string,
MaxLengthError<100>,
string & Brand<"Trimmed">,
StringError | TrimmedError
>,
"MinLength1",
MinLengthError<1>,
StringError | TrimmedError | MaxLengthError<100>
>;
```
Defined in: [packages/common/src/Type.ts:1338](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1338)
NonEmptyTrimmedString1000 - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / NonEmptyTrimmedString1000
# Variable: NonEmptyTrimmedString1000
```ts
const NonEmptyTrimmedString1000: BrandType<
Type<
"Brand",
string & Brand<"Trimmed"> & Brand<"MaxLength1000">,
string,
MaxLengthError<1000>,
string & Brand<"Trimmed">,
StringError | TrimmedError
>,
"MinLength1",
MinLengthError<1>,
StringError | TrimmedError | MaxLengthError<1000>
>;
```
Defined in: [packages/common/src/Type.ts:1342](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1342)
NonNaNNumber - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / NonNaNNumber
# Variable: NonNaNNumber
```ts
const NonNaNNumber: BrandType<
Type<"Number", number, number, NumberError, number, NumberError>,
"NonNaN",
NonNaNError,
NumberError
>;
```
Defined in: [packages/common/src/Type.ts:2132](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L2132)
NonNegativeInt - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / NonNegativeInt
# Variable: NonNegativeInt
```ts
const NonNegativeInt: BrandType<
Type<"Brand", number & Brand<"Int">, number, IntError, number, NumberError>,
"NonNegative",
NonNegativeError,
IntError | NumberError
>;
```
Defined in: [packages/common/src/Type.ts:1978](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1978)
Non-negative integer (≥ 0).
NonNegativeNumber - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / NonNegativeNumber
# Variable: NonNegativeNumber
```ts
const NonNegativeNumber: BrandType<
Type<"Number", number, number, NumberError, number, NumberError>,
"NonNegative",
NonNegativeError,
NumberError
>;
```
Defined in: [packages/common/src/Type.ts:1914](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1914)
Non-negative number (≥ 0).
NonPositiveInt - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / NonPositiveInt
# Variable: NonPositiveInt
```ts
const NonPositiveInt: BrandType<
Type<"Brand", number & Brand<"Int">, number, IntError, number, NumberError>,
"NonPositive",
NonPositiveError,
IntError | NumberError
>;
```
Defined in: [packages/common/src/Type.ts:1999](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1999)
Non-positive integer (≤ 0).
NonPositiveNumber - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / NonPositiveNumber
# Variable: NonPositiveNumber
```ts
const NonPositiveNumber: BrandType<
Type<"Number", number, number, NumberError, number, NumberError>,
"NonPositive",
NonPositiveError,
NumberError
>;
```
Defined in: [packages/common/src/Type.ts:1930](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1930)
Non-positive number (≤ 0).
Null - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / Null
# Variable: Null
```ts
const Null: Type<"Null", null, null, NullError, null, NullError>;
```
Defined in: [packages/common/src/Type.ts:727](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L727)
Number - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / Number
# Variable: Number
```ts
const Number: Type<"Number", number, number, NumberError, number, NumberError>;
```
Defined in: [packages/common/src/Type.ts:682](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L682)
PositiveInt - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / PositiveInt
# Variable: PositiveInt
```ts
const PositiveInt: BrandType<
Type<
"Brand",
number & Brand<"Int"> & Brand<"NonNegative">,
number,
NonNegativeError,
number & Brand<"Int">,
IntError | NumberError
>,
"Positive",
PositiveError,
NonNegativeError | IntError | NumberError
>;
```
Defined in: [packages/common/src/Type.ts:1986](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1986)
Positive integer (> 0).
PositiveNumber - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / PositiveNumber
# Variable: PositiveNumber
```ts
const PositiveNumber: BrandType<
Type<
"Brand",
number & Brand<"NonNegative">,
number,
NonNegativeError,
number,
NumberError
>,
"Positive",
PositiveError,
NonNegativeError | NumberError
>;
```
Defined in: [packages/common/src/Type.ts:1922](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1922)
Positive number (> 0).
SimpleName - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / SimpleName
# Variable: SimpleName
```ts
const SimpleName: BrandType<
BrandType<
Type<"String", string, string, StringError, string, StringError>,
"UrlSafeString",
RegexError<"UrlSafeString">,
StringError
>,
"SimpleName",
SimpleNameError,
StringError | RegexError<"UrlSafeString">
>;
```
Defined in: [packages/common/src/Type.ts:1543](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1543)
Simple alphanumeric string for naming in file systems, URLs, and identifiers.
Uses the same safe alphabet as [UrlSafeString](https://evolu.dev/docs/api-reference/common/Type/variables/UrlSafeString) (letters, digits, `-`,
`_`). See `UrlSafeString` for details.
The string must be between 1 and 64 characters.
### Example
```ts
const result = SimpleName.from("data-report-123");
if (result.ok) {
console.log("Valid SimpleName string:", result.value);
} else {
console.error("Invalid SimpleName string:", result.error);
}
```
SimplePassword - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / SimplePassword
# Variable: SimplePassword
```ts
const SimplePassword: BrandType<
BrandType<
Type<
"Brand",
string & Brand<"Trimmed"> & Brand<"MaxLength64">,
string,
MaxLengthError<64>,
string & Brand<"Trimmed">,
StringError | TrimmedError
>,
"MinLength8",
MinLengthError<8>,
StringError | TrimmedError | MaxLengthError<64>
>,
"SimplePassword",
BrandWithoutRefineError<
"SimplePassword",
StringError | TrimmedError | MinLengthError<8> | MaxLengthError<64>
>,
never
>;
```
Defined in: [packages/common/src/Type.ts:1575](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1575)
Trimmed string between 8 and 64 characters, branded as `SimplePassword`.
Take a look how `SimplePassword` is defined:
```ts
export const SimplePassword = brand(
"SimplePassword",
minLength(8)(maxLength(64)(TrimmedString)),
);
```
Nested functions are often OK (if not, make a helper), but with TC39 Hack
pipes it would be clearer:
```ts
// TrimmedString
// |> minLength(8)(%)
// |> maxLength(64)(%)
// |> brand("SimplePassword", %)
```
String - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / String
# Variable: String
```ts
const String: Type<"String", string, string, StringError, string, StringError>;
```
Defined in: [packages/common/src/Type.ts:671](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L671)
String100 - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / String100
# Variable: String100
```ts
const String100: BrandType<
Type<"String", string, string, StringError, string, StringError>,
"MaxLength100",
MaxLengthError<100>,
StringError
>;
```
Defined in: [packages/common/src/Type.ts:1310](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1310)
String1000 - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / String1000
# Variable: String1000
```ts
const String1000: BrandType<
Type<"String", string, string, StringError, string, StringError>,
"MaxLength1000",
MaxLengthError<1000>,
StringError
>;
```
Defined in: [packages/common/src/Type.ts:1314](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1314)
TrimmedString - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / TrimmedString
# Variable: TrimmedString
```ts
const TrimmedString: BrandType<
Type<"String", string, string, StringError, string, StringError>,
"Trimmed",
TrimmedError,
StringError
>;
```
Defined in: [packages/common/src/Type.ts:1201](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1201)
Trimmed string
- Use `TrimmedString.is` to check if an unknown value is trimmed.
- Use `TrimmedString.from` to check if a string is trimmed.
TrimmedString100 - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / TrimmedString100
# Variable: TrimmedString100
```ts
const TrimmedString100: BrandType<
Type<
"Brand",
string & Brand<"Trimmed">,
string,
TrimmedError,
string,
StringError
>,
"MaxLength100",
MaxLengthError<100>,
StringError | TrimmedError
>;
```
Defined in: [packages/common/src/Type.ts:1330](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1330)
TrimmedString1000 - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / TrimmedString1000
# Variable: TrimmedString1000
```ts
const TrimmedString1000: BrandType<
Type<
"Brand",
string & Brand<"Trimmed">,
string,
TrimmedError,
string,
StringError
>,
"MaxLength1000",
MaxLengthError<1000>,
StringError | TrimmedError
>;
```
Defined in: [packages/common/src/Type.ts:1334](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1334)
Uint8Array - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / Uint8Array
# Variable: Uint8Array
```ts
const Uint8Array: Type<
"Uint8Array",
Uint8Array<ArrayBufferLike>,
Uint8Array<ArrayBufferLike>,
Uint8ArrayError,
Uint8Array<ArrayBufferLike>,
Uint8ArrayError
>;
```
Defined in: [packages/common/src/Type.ts:748](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L748)
Undefined - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / Undefined
# Variable: Undefined
```ts
const Undefined: Type<
"Undefined",
undefined,
undefined,
UndefinedError,
undefined,
UndefinedError
>;
```
Defined in: [packages/common/src/Type.ts:715](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L715)
Unknown - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / Unknown
# Variable: Unknown
```ts
const Unknown: Type<"Unknown", unknown, unknown, never, unknown, never>;
```
Defined in: [packages/common/src/Type.ts:665](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L665)
UrlSafeString - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / UrlSafeString
# Variable: UrlSafeString
```ts
const UrlSafeString: BrandType<
Type<"String", string, string, StringError, string, StringError>,
"UrlSafeString",
RegexError<"UrlSafeString">,
StringError
>;
```
Defined in: [packages/common/src/Type.ts:1434](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1434)
URL-safe string.
A `UrlSafeString` uses a limited alphabet that is safe for URLs:
- Uppercase letters (`A-Z`)
- Lowercase letters (`a-z`)
- Digits (`0-9`)
- Dash (`-`)
- Underscore (`_`)
This is the same character set used by Base64Url encoding, but this type does
not validate that the string is actually Base64Url-encoded data.
### Example
```ts
const result = UrlSafeString.from("abc123_-");
if (result.ok) {
console.log("Valid URL-safe string:", result.value);
} else {
console.error("Invalid URL-safe string:", result.error);
}
```
base64UrlToUint8Array - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / base64UrlToUint8Array
# Variable: base64UrlToUint8Array()
```ts
const base64UrlToUint8Array: (str) => Uint8Array;
```
Defined in: [packages/common/src/Type.ts:1497](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1497)
Decodes a [Base64Url](https://evolu.dev/docs/api-reference/common/Type/variables/Base64Url) string to a Uint8Array.
## Parameters
| Parameter | Type |
| --------- | ------------------------------------------------------------------------- |
| `str` | [`Base64Url`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/Base64Url) |
## Returns
`Uint8Array`
between - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / between
# Variable: between()
```ts
const between: <Min, Max>(
min,
max,
) => BrandFactory<`Between${Min}-${Max}`, number, BetweenError<Min, Max>>;
```
Defined in: [packages/common/src/Type.ts:2207](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L2207)
Number within a range, inclusive.
### Example
```ts
const Between1And10 = between(1, 10)(PositiveNumber);
const result = Between1And10.from(5); // ok(5)
const errorResult = Between1And10.from(11); // err
```
## Type Parameters
| Type Parameter |
| ------------------------ |
| `Min` _extends_ `number` |
| `Max` _extends_ `number` |
## Parameters
| Parameter | Type |
| --------- | ----- |
| `min` | `Min` |
| `max` | `Max` |
## Returns
[`BrandFactory`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/BrandFactory)\<`` `Between${Min}-${Max}` ``, `number`, [`BetweenError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/BetweenError)\<`Min`, `Max`\>\>
finite - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / finite
# Variable: finite
```ts
const finite: BrandFactory<"Finite", number, FiniteError>;
```
Defined in: [packages/common/src/Type.ts:2140](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L2140)
Finite number.
formatBase64UrlError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / formatBase64UrlError
# Variable: formatBase64UrlError
```ts
const formatBase64UrlError: TypeErrorFormatter<Base64UrlError>;
```
Defined in: [packages/common/src/Type.ts:1469](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1469)
formatBetweenError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / formatBetweenError
# Variable: formatBetweenError
```ts
const formatBetweenError: TypeErrorFormatter<BetweenError<number, number>>;
```
Defined in: [packages/common/src/Type.ts:2226](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L2226)
formatBigIntError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / formatBigIntError
# Variable: formatBigIntError
```ts
const formatBigIntError: TypeErrorFormatter<BigIntError>;
```
Defined in: [packages/common/src/Type.ts:701](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L701)
formatBooleanError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / formatBooleanError
# Variable: formatBooleanError
```ts
const formatBooleanError: TypeErrorFormatter<BooleanError>;
```
Defined in: [packages/common/src/Type.ts:712](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L712)
formatCurrencyCodeError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / formatCurrencyCodeError
# Variable: formatCurrencyCodeError
```ts
const formatCurrencyCodeError: TypeErrorFormatter<CurrencyCodeError>;
```
Defined in: [packages/common/src/Type.ts:1068](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1068)
formatDateIsoError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / formatDateIsoError
# Variable: formatDateIsoError
```ts
const formatDateIsoError: TypeErrorFormatter<DateIsoError>;
```
Defined in: [packages/common/src/Type.ts:1114](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1114)
formatFiniteError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / formatFiniteError
# Variable: formatFiniteError
```ts
const formatFiniteError: TypeErrorFormatter<FiniteError>;
```
Defined in: [packages/common/src/Type.ts:2149](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L2149)
formatFunctionError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / formatFunctionError
# Variable: formatFunctionError
```ts
const formatFunctionError: TypeErrorFormatter<FunctionError>;
```
Defined in: [packages/common/src/Type.ts:744](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L744)
formatGreaterThanError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / formatGreaterThanError
# Variable: formatGreaterThanError
```ts
const formatGreaterThanError: TypeErrorFormatter<GreaterThanError<number>>;
```
Defined in: [packages/common/src/Type.ts:2029](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L2029)
formatGreaterThanOrEqualToError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / formatGreaterThanOrEqualToError
# Variable: formatGreaterThanOrEqualToError
```ts
const formatGreaterThanOrEqualToError: TypeErrorFormatter<
GreaterThanOrEqualToError<number>
>;
```
Defined in: [packages/common/src/Type.ts:2081](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L2081)
formatIdError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / formatIdError
# Variable: formatIdError
```ts
const formatIdError: TypeErrorFormatter<IdError>;
```
Defined in: [packages/common/src/Type.ts:1626](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1626)
formatInstanceOfError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / formatInstanceOfError
# Variable: formatInstanceOfError
```ts
const formatInstanceOfError: TypeErrorFormatter<InstanceOfError>;
```
Defined in: [packages/common/src/Type.ts:805](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L805)
formatInt64Error - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / formatInt64Error
# Variable: formatInt64Error
```ts
const formatInt64Error: TypeErrorFormatter<Int64Error>;
```
Defined in: [packages/common/src/Type.ts:3622](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L3622)
formatInt64StringError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / formatInt64StringError
# Variable: formatInt64StringError
```ts
const formatInt64StringError: TypeErrorFormatter<Int64StringError>;
```
Defined in: [packages/common/src/Type.ts:3647](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L3647)
formatIntError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / formatIntError
# Variable: formatIntError
```ts
const formatIntError: TypeErrorFormatter<IntError>;
```
Defined in: [packages/common/src/Type.ts:1961](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1961)
formatIsTypeError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / formatIsTypeError
# Variable: formatIsTypeError
```ts
const formatIsTypeError: TypeErrorFormatter<EvoluTypeError>;
```
Defined in: [packages/common/src/Type.ts:839](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L839)
formatJsonError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / formatJsonError
# Variable: formatJsonError
```ts
const formatJsonError: TypeErrorFormatter<JsonError>;
```
Defined in: [packages/common/src/Type.ts:3780](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L3780)
formatLengthError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / formatLengthError
# Variable: formatLengthError
```ts
const formatLengthError: TypeErrorFormatter<LengthError<number>>;
```
Defined in: [packages/common/src/Type.ts:1300](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1300)
formatLessThanError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / formatLessThanError
# Variable: formatLessThanError
```ts
const formatLessThanError: TypeErrorFormatter<LessThanError<number>>;
```
Defined in: [packages/common/src/Type.ts:2053](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L2053)
formatLessThanOrEqualToError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / formatLessThanOrEqualToError
# Variable: formatLessThanOrEqualToError
```ts
const formatLessThanOrEqualToError: TypeErrorFormatter<
LessThanOrEqualToError<number>
>;
```
Defined in: [packages/common/src/Type.ts:2108](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L2108)
formatLiteralError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / formatLiteralError
# Variable: formatLiteralError
```ts
const formatLiteralError: TypeErrorFormatter<LiteralError<Literal>>;
```
Defined in: [packages/common/src/Type.ts:2278](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L2278)
formatMaxLengthError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / formatMaxLengthError
# Variable: formatMaxLengthError
```ts
const formatMaxLengthError: TypeErrorFormatter<MaxLengthError<number>>;
```
Defined in: [packages/common/src/Type.ts:1266](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1266)
formatMinLengthError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / formatMinLengthError
# Variable: formatMinLengthError
```ts
const formatMinLengthError: TypeErrorFormatter<MinLengthError<number>>;
```
Defined in: [packages/common/src/Type.ts:1234](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1234)
formatMnemonicError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / formatMnemonicError
# Variable: formatMnemonicError
```ts
const formatMnemonicError: TypeErrorFormatter<MnemonicError>;
```
Defined in: [packages/common/src/Type.ts:1363](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1363)
formatMultipleOfError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / formatMultipleOfError
# Variable: formatMultipleOfError
```ts
const formatMultipleOfError: TypeErrorFormatter<MultipleOfError<number>>;
```
Defined in: [packages/common/src/Type.ts:2190](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L2190)
formatNegativeError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / formatNegativeError
# Variable: formatNegativeError
```ts
const formatNegativeError: TypeErrorFormatter<NegativeError>;
```
Defined in: [packages/common/src/Type.ts:1847](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1847)
formatNonNaNError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / formatNonNaNError
# Variable: formatNonNaNError
```ts
const formatNonNaNError: TypeErrorFormatter<NonNaNError>;
```
Defined in: [packages/common/src/Type.ts:2127](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L2127)
formatNonNegativeError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / formatNonNegativeError
# Variable: formatNonNegativeError
```ts
const formatNonNegativeError: TypeErrorFormatter<NonNegativeError>;
```
Defined in: [packages/common/src/Type.ts:1904](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1904)
formatNonPositiveError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / formatNonPositiveError
# Variable: formatNonPositiveError
```ts
const formatNonPositiveError: TypeErrorFormatter<NonPositiveError>;
```
Defined in: [packages/common/src/Type.ts:1875](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1875)
formatNullError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / formatNullError
# Variable: formatNullError
```ts
const formatNullError: TypeErrorFormatter<NullError>;
```
Defined in: [packages/common/src/Type.ts:733](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L733)
formatNumberError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / formatNumberError
# Variable: formatNumberError
```ts
const formatNumberError: TypeErrorFormatter<NumberError>;
```
Defined in: [packages/common/src/Type.ts:690](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L690)
formatPositiveError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / formatPositiveError
# Variable: formatPositiveError
```ts
const formatPositiveError: TypeErrorFormatter<PositiveError>;
```
Defined in: [packages/common/src/Type.ts:1823](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1823)
formatRegexError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / formatRegexError
# Variable: formatRegexError
```ts
const formatRegexError: TypeErrorFormatter<RegexError<Capitalize<string>>>;
```
Defined in: [packages/common/src/Type.ts:1402](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1402)
formatStringError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / formatStringError
# Variable: formatStringError
```ts
const formatStringError: TypeErrorFormatter<StringError>;
```
Defined in: [packages/common/src/Type.ts:679](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L679)
formatTableIdError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / formatTableIdError
# Variable: formatTableIdError
```ts
const formatTableIdError: TypeErrorFormatter<TableIdError<Capitalize<string>>>;
```
Defined in: [packages/common/src/Type.ts:1782](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1782)
formatTrimmedError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / formatTrimmedError
# Variable: formatTrimmedError
```ts
const formatTrimmedError: TypeErrorFormatter<TrimmedError>;
```
Defined in: [packages/common/src/Type.ts:1189](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1189)
formatUint8ArrayError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / formatUint8ArrayError
# Variable: formatUint8ArrayError
```ts
const formatUint8ArrayError: TypeErrorFormatter<Uint8ArrayError>;
```
Defined in: [packages/common/src/Type.ts:756](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L756)
formatUndefinedError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / formatUndefinedError
# Variable: formatUndefinedError
```ts
const formatUndefinedError: TypeErrorFormatter<UndefinedError>;
```
Defined in: [packages/common/src/Type.ts:723](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L723)
formatValidMutationSizeError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / formatValidMutationSizeError
# Variable: formatValidMutationSizeError
```ts
const formatValidMutationSizeError: TypeErrorFormatter<ValidMutationSizeError>;
```
Defined in: [packages/common/src/Type.ts:4029](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L4029)
greaterThan - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / greaterThan
# Variable: greaterThan()
```ts
const greaterThan: <Min>(
min,
) => BrandFactory<`GreaterThan${Min}`, number, GreaterThanError<Min>>;
```
Defined in: [packages/common/src/Type.ts:2015](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L2015)
Number greater than a specified value.
## Type Parameters
| Type Parameter |
| ------------------------ |
| `Min` _extends_ `number` |
## Parameters
| Parameter | Type |
| --------- | ----- |
| `min` | `Min` |
## Returns
[`BrandFactory`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/BrandFactory)\<`` `GreaterThan${Min}` ``, `number`, [`GreaterThanError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/GreaterThanError)\<`Min`\>\>
greaterThanOrEqualTo - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / greaterThanOrEqualTo
# Variable: greaterThanOrEqualTo()
```ts
const greaterThanOrEqualTo: <Min>(
min,
) => BrandFactory<
`GreaterThanOrEqualTo${Min}`,
number,
GreaterThanOrEqualToError<Min>
>;
```
Defined in: [packages/common/src/Type.ts:2062](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L2062)
Number ≥ a specified value.
## Type Parameters
| Type Parameter |
| ------------------------ |
| `Min` _extends_ `number` |
## Parameters
| Parameter | Type |
| --------- | ----- |
| `min` | `Min` |
## Returns
[`BrandFactory`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/BrandFactory)\<`` `GreaterThanOrEqualTo${Min}` ``, `number`, [`GreaterThanOrEqualToError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/GreaterThanOrEqualToError)\<`Min`\>\>
idBytesTypeValueLength - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / idBytesTypeValueLength
# Variable: idBytesTypeValueLength
```ts
const idBytesTypeValueLength: number & Brand<"Int"> & Brand<"NonNegative">;
```
Defined in: [packages/common/src/Type.ts:1790](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1790)
int - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / int
# Variable: int
```ts
const int: BrandFactory<"Int", number, IntError>;
```
Defined in: [packages/common/src/Type.ts:1952](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1952)
Integer within the safe range of JavaScript numbers.
### Example
```ts
const Int = int(Number);
```
length - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / length
# Variable: length()
```ts
const length: <Exact>(exact) => BrandFactory<
`Length${Exact}`,
{
length: number;
},
LengthError<Exact>
>;
```
Defined in: [packages/common/src/Type.ts:1284](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1284)
Exact length.
### Example
```ts
// string & Brand<"Length1">
const Length1String = length(1)(String);
```
## Type Parameters
| Type Parameter |
| -------------------------- |
| `Exact` _extends_ `number` |
## Parameters
| Parameter | Type |
| --------- | ------- |
| `exact` | `Exact` |
## Returns
[`BrandFactory`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/BrandFactory)\<`` `Length${Exact}` ``, \{
`length`: `number`;
\}, [`LengthError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/LengthError)\<`Exact`\>\>
lessThan - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / lessThan
# Variable: lessThan()
```ts
const lessThan: <Max>(
max,
) => BrandFactory<`LessThan${Max}`, number, LessThanError<Max>>;
```
Defined in: [packages/common/src/Type.ts:2039](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L2039)
Number less than a specified value.
## Type Parameters
| Type Parameter |
| ------------------------ |
| `Max` _extends_ `number` |
## Parameters
| Parameter | Type |
| --------- | ----- |
| `max` | `Max` |
## Returns
[`BrandFactory`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/BrandFactory)\<`` `LessThan${Max}` ``, `number`, [`LessThanError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/LessThanError)\<`Max`\>\>
lessThanOrEqualTo - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / lessThanOrEqualTo
# Variable: lessThanOrEqualTo()
```ts
const lessThanOrEqualTo: <Max>(
max,
) => BrandFactory<
`LessThanOrEqualTo${Max}`,
number,
LessThanOrEqualToError<Max>
>;
```
Defined in: [packages/common/src/Type.ts:2091](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L2091)
Number ≤ a specified value.
## Type Parameters
| Type Parameter |
| ------------------------ |
| `Max` _extends_ `number` |
## Parameters
| Parameter | Type |
| --------- | ----- |
| `max` | `Max` |
## Returns
[`BrandFactory`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/BrandFactory)\<`` `LessThanOrEqualTo${Max}` ``, `number`, [`LessThanOrEqualToError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/LessThanOrEqualToError)\<`Max`\>\>
maxLength - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / maxLength
# Variable: maxLength()
```ts
const maxLength: <Max>(max) => BrandFactory<
`MaxLength${Max}`,
{
length: number;
},
MaxLengthError<Max>
>;
```
Defined in: [packages/common/src/Type.ts:1252](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1252)
Maximum length.
### Example
```ts
// string & Brand<"MaxLength100">
const String100 = maxLength(100)(String);
```
## Type Parameters
| Type Parameter |
| ------------------------ |
| `Max` _extends_ `number` |
## Parameters
| Parameter | Type |
| --------- | ----- |
| `max` | `Max` |
## Returns
[`BrandFactory`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/BrandFactory)\<`` `MaxLength${Max}` ``, \{
`length`: `number`;
\}, [`MaxLengthError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/MaxLengthError)\<`Max`\>\>
maxMutationSize - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / maxMutationSize
# Variable: maxMutationSize
```ts
const maxMutationSize: 655360 = 655360;
```
Defined in: [packages/common/src/Type.ts:4010](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L4010)
maxPositiveInt - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / maxPositiveInt
# Variable: maxPositiveInt
```ts
const maxPositiveInt: number &
Brand<"Int"> &
Brand<"NonNegative"> &
Brand<"Positive">;
```
Defined in: [packages/common/src/Type.ts:1990](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1990)
Maximum safe positive integer value for practically infinite operations.
minLength - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / minLength
# Variable: minLength()
```ts
const minLength: <Min>(min) => BrandFactory<
`MinLength${Min}`,
{
length: number;
},
MinLengthError<Min>
>;
```
Defined in: [packages/common/src/Type.ts:1220](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1220)
Minimum length.
### Example
```ts
// string & Brand<"MinLength1">
const NonEmptyString = minLength(1)(String);
```
## Type Parameters
| Type Parameter |
| ------------------------ |
| `Min` _extends_ `number` |
## Parameters
| Parameter | Type |
| --------- | ----- |
| `min` | `Min` |
## Returns
[`BrandFactory`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/BrandFactory)\<`` `MinLength${Min}` ``, \{
`length`: `number`;
\}, [`MinLengthError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/MinLengthError)\<`Min`\>\>
multipleOf - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / multipleOf
# Variable: multipleOf()
```ts
const multipleOf: <Divisor>(
divisor,
) => BrandFactory<`MultipleOf${Divisor}`, number, MultipleOfError<Divisor>>;
```
Defined in: [packages/common/src/Type.ts:2174](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L2174)
Number that is a multiple of a divisor.
## Type Parameters
| Type Parameter |
| ---------------------------- |
| `Divisor` _extends_ `number` |
## Parameters
| Parameter | Type |
| --------- | --------- |
| `divisor` | `Divisor` |
## Returns
[`BrandFactory`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/BrandFactory)\<`` `MultipleOf${Divisor}` ``, `number`, [`MultipleOfError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/MultipleOfError)\<`Divisor`\>\>
negative - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / negative
# Variable: negative
```ts
const negative: BrandFactory<"Negative", number, NegativeError>;
```
Defined in: [packages/common/src/Type.ts:1838](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1838)
Negative number (< 0).
### Example
```ts
const NegativeNumber = negative(Number);
```
nonNaN - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / nonNaN
# Variable: nonNaN
```ts
const nonNaN: BrandFactory<"NonNaN", number, NonNaNError>;
```
Defined in: [packages/common/src/Type.ts:2118](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L2118)
Number that is not NaN.
nonNegative - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / nonNegative
# Variable: nonNegative
```ts
const nonNegative: BrandFactory<"NonNegative", number, NonNegativeError>;
```
Defined in: [packages/common/src/Type.ts:1891](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1891)
Non-negative number (≥ 0).
### Example
```ts
const NonNegativeNumber = nonNegative(Number);
```
nonPositive - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / nonPositive
# Variable: nonPositive
```ts
const nonPositive: BrandFactory<"NonPositive", number, NonPositiveError>;
```
Defined in: [packages/common/src/Type.ts:1862](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1862)
Non-positive number (≤ 0).
### Example
```ts
const NonPositiveNumber = nonPositive(Number);
```
positive - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / positive
# Variable: positive
```ts
const positive: BrandFactory<"Positive", number, PositiveError>;
```
Defined in: [packages/common/src/Type.ts:1814](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1814)
Positive number (> 0).
### Example
```ts
const PositiveNumber = positive(Number);
const result = PositiveNumber.from(42); // ok
const errorResult = PositiveNumber.from(-5); // err
```
regex - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / regex
# Variable: regex()
```ts
const regex: <Name>(
name,
pattern,
) => BrandFactory<Name, string, RegexError<Name>>;
```
Defined in: [packages/common/src/Type.ts:1378](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1378)
String matching a regular expression.
### Example
```ts
const Alphanumeric = regex("Alphanumeric", /^[a-z0-9]+$/i)(String);
```
## Type Parameters
| Type Parameter |
| ---------------------------------------------------------------------------------------- |
| `Name` _extends_ [`TypeName`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/TypeName) |
## Parameters
| Parameter | Type |
| --------- | -------- |
| `name` | `Name` |
| `pattern` | `RegExp` |
## Returns
[`BrandFactory`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/BrandFactory)\<`Name`, `string`, [`RegexError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/RegexError)\<`Name`\>\>
trimmed - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / trimmed
# Variable: trimmed
```ts
const trimmed: BrandFactory<"Trimmed", string, TrimmedError>;
```
Defined in: [packages/common/src/Type.ts:1178](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1178)
Trimmed string.
This Type Factory validates whether a string has no leading or trailing
whitespaces.
### Example
```ts
const TrimmedNonEmptyString = trimmed(minLength(1)(String));
// string & Brand<"MinLength1"> & Brand<"Trimmed">
type TrimmedNonEmptyString = typeof TrimmedNonEmptyString.Type;
```
uint8ArrayToBase64Url - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / uint8ArrayToBase64Url
# Variable: uint8ArrayToBase64Url()
```ts
const uint8ArrayToBase64Url: (bytes) => Base64Url;
```
Defined in: [packages/common/src/Type.ts:1476](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L1476)
Encodes a Uint8Array to a [Base64Url](https://evolu.dev/docs/api-reference/common/Type/variables/Base64Url) string.
## Parameters
| Parameter | Type |
| --------- | ------------ |
| `bytes` | `Uint8Array` |
## Returns
[`Base64Url`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/Base64Url)
IntentionalNever - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Types](https://evolu.dev/docs/api-reference/common/Types) / IntentionalNever
# Type Alias: IntentionalNever
```ts
type IntentionalNever = never;
```
Defined in: [packages/common/src/Types.ts:121](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Types.ts#L121)
A type alias for `never` that is used intentionally when casting is not
needed and unit tests exist to ensure correctness.
Literal - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Types](https://evolu.dev/docs/api-reference/common/Types) / Literal
# Type Alias: Literal
```ts
type Literal = string | number | bigint | boolean | undefined | null;
```
Defined in: [packages/common/src/Types.ts:128](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Types.ts#L128)
String, number, bigint, boolean, undefined, null
https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#literal-types
NullablePartial - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Types](https://evolu.dev/docs/api-reference/common/Types) / NullablePartial
# Type Alias: NullablePartial\<T, NK, NP\>
```ts
type NullablePartial<T, NK, NP> = { [K in keyof NP]: NP[K] };
```
Defined in: [packages/common/src/Types.ts:109](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Types.ts#L109)
Makes properties optional if they accept `null` as a value.
For each property in `T`, if `null` is a valid value for that property, the
property will be made optional in the resulting type.
### Example
```ts
type Example = {
required: string;
optionalWithNull: string | null;
};
type Result = NullablePartial<Example>;
// Result is:
// {
// required: string;
// optionalWithNull?: string | null;
// }
```
## Type Parameters
| Type Parameter | Default type |
| ------------------------ | ------------------------------------------------------------------------------ |
| `T` | - |
| `NK` _extends_ keyof `T` | `{ [K in keyof T]: null extends T[K] ? K : never }`\[keyof `T`\] |
| `NP` | `Pick`\<`T`, `Exclude`\<keyof `T`, `NK`\>\> & `Partial`\<`Pick`\<`T`, `NK`\>\> |
PartialProp - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Types](https://evolu.dev/docs/api-reference/common/Types) / PartialProp
# Type Alias: PartialProp\<T, K\>
```ts
type PartialProp<T, K> = Omit<T, K> & Partial<Pick<T, K>>;
```
Defined in: [packages/common/src/Types.ts:174](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Types.ts#L174)
Makes a specific property of an object optional while keeping others
unchanged.
## Type Parameters
| Type Parameter |
| ----------------------- |
| `T` |
| `K` _extends_ keyof `T` |
Predicate - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Types](https://evolu.dev/docs/api-reference/common/Types) / Predicate
# Type Alias: Predicate()\<T\>
```ts
type Predicate<T> = (value) => boolean;
```
Defined in: [packages/common/src/Types.ts:23](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Types.ts#L23)
Checks a condition on a value and returns a boolean.
A predicate starts with an 'is' prefix, e.g., `isEven`.
### Example
```ts
const isEven: Predicate<number> = (n) => n % 2 === 0;
const numbers = [1, 2, 3, 4];
const evenNumbers = numbers.filter(isEven); // [2, 4]
```
## Type Parameters
| Type Parameter |
| -------------- |
| `T` |
## Parameters
| Parameter | Type |
| --------- | ---- |
| `value` | `T` |
## Returns
`boolean`
PredicateWithIndex - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Types](https://evolu.dev/docs/api-reference/common/Types) / PredicateWithIndex
# Type Alias: PredicateWithIndex()\<T\>
```ts
type PredicateWithIndex<T> = (value, index) => boolean;
```
Defined in: [packages/common/src/Types.ts:40](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Types.ts#L40)
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"]
```
## Type Parameters
| Type Parameter |
| -------------- |
| `T` |
## Parameters
| Parameter | Type |
| --------- | -------- |
| `value` | `T` |
| `index` | `number` |
## Returns
`boolean`
Refinement - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Types](https://evolu.dev/docs/api-reference/common/Types) / Refinement
# Type Alias: Refinement()\<A, B\>
```ts
type Refinement<A, B> = (a) => a is B;
```
Defined in: [packages/common/src/Types.ts:60](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Types.ts#L60)
A type guard function that refines type `A` to a narrower type `B`.
### Example
```ts
type Animal = { name: string };
type Dog = Animal & { breed: string };
const isDog: Refinement<Animal, Dog> = (animal): animal is Dog =>
"breed" in animal;
const animal: Animal = { name: "Dog", breed: "Beagle" };
if (isDog(animal)) {
console.log(animal.breed); // Safe access to `breed`
}
```
## Type Parameters
| Type Parameter |
| ----------------- |
| `A` |
| `B` _extends_ `A` |
## Parameters
| Parameter | Type |
| --------- | ---- |
| `a` | `A` |
## Returns
`a is B`
RefinementWithIndex - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Types](https://evolu.dev/docs/api-reference/common/Types) / RefinementWithIndex
# Type Alias: RefinementWithIndex()\<A, B\>
```ts
type RefinementWithIndex<A, B> = (a, index) => a is B;
```
Defined in: [packages/common/src/Types.ts:82](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Types.ts#L82)
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);
```
## Type Parameters
| Type Parameter |
| ----------------- |
| `A` |
| `B` _extends_ `A` |
## Parameters
| Parameter | Type |
| --------- | -------- |
| `a` | `A` |
| `index` | `number` |
## Returns
`a is B`
Simplify - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Types](https://evolu.dev/docs/api-reference/common/Types) / Simplify
# Type Alias: Simplify\<T\>
```ts
type Simplify<T> = Kysely.Simplify<T>;
```
Defined in: [packages/common/src/Types.ts:168](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Types.ts#L168)
Simplify an intersection type into a single mapped type.
This utility forces TypeScript to "flatten" an intersection type into a
single object type so that tooltips and error messages are easier to read.
### Example
```ts
type A = { a: string } & { b: number };
// Without Simplify, TypeScript may display A as:
// { a: string } & { b: number }
type B = Simplify<A>;
// B is equivalent to:
// { a: string; b: number }
```
## Type Parameters
| Type Parameter |
| -------------- |
| `T` |
WidenLiteral - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Types](https://evolu.dev/docs/api-reference/common/Types) / WidenLiteral
# Type Alias: WidenLiteral\<T\>
```ts
type WidenLiteral<T> = T extends string
? string
: T extends number
? number
: T extends boolean
? boolean
: T extends bigint
? bigint
: T;
```
Defined in: [packages/common/src/Types.ts:140](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Types.ts#L140)
Infers a broader type from a specific literal value type.
Examples:
- "foo" -> string
- 42 -> number
- 42n -> bigint
- True -> boolean
## Type Parameters
| Type Parameter |
| ------------------------------------------------------------------------------------ |
| `T` _extends_ [`Literal`](https://evolu.dev/docs/api-reference/common/Types/type-aliases/Literal) |
CreateWebSocketDep - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [WebSocket](https://evolu.dev/docs/api-reference/common/WebSocket) / CreateWebSocketDep
# Interface: CreateWebSocketDep
Defined in: [packages/common/src/WebSocket.ts:40](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/WebSocket.ts#L40)
## Properties
| Property | Modifier | Type | Defined in |
| ---------------------------------------------- | ---------- | ------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="createwebsocket"></a> `createWebSocket` | `readonly` | [`CreateWebSocket`](https://evolu.dev/docs/api-reference/common/WebSocket/type-aliases/CreateWebSocket) | [packages/common/src/WebSocket.ts:41](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/WebSocket.ts#L41) |
WebSocket - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [WebSocket](https://evolu.dev/docs/api-reference/common/WebSocket) / WebSocket
# Interface: WebSocket
Defined in: [packages/common/src/WebSocket.ts:7](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/WebSocket.ts#L7)
WebSocket with auto-reconnect and offline support.
## Extends
- `Disposable`
## Properties
| Property | Modifier | Type | Description | Defined in |
| ------------------------------------------ | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="getreadystate"></a> `getReadyState` | `readonly` | () => [`WebSocketReadyState`](https://evolu.dev/docs/api-reference/common/WebSocket/type-aliases/WebSocketReadyState) | - | [packages/common/src/WebSocket.ts:16](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/WebSocket.ts#L16) |
| <a id="isopen"></a> `isOpen` | `readonly` | () => `boolean` | Returns true if the WebSocket is open and ready to send data. | [packages/common/src/WebSocket.ts:19](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/WebSocket.ts#L19) |
| <a id="send"></a> `send` | `public` | (`data`) => [`Result`](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result)\<`void`, [`WebSocketSendError`](https://evolu.dev/docs/api-reference/common/WebSocket/interfaces/WebSocketSendError)\> | Send data through the WebSocket connection. Returns [Result](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result) with an error if the data couldn't be sent. | [packages/common/src/WebSocket.ts:12](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/WebSocket.ts#L12) |
## Methods
### \[dispose\]()
##
Defined in: node_modules/typescript/lib/lib.esnext.disposable.d.ts:36
##### Returns
`void`
##### Inherited from
```ts
Disposable.[dispose]
```
##
Defined in: node_modules/@types/node/compatibility/disposable.d.ts:9
##### Returns
`void`
##### Inherited from
```ts
Disposable.[dispose]
```
WebSocketConnectError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [WebSocket](https://evolu.dev/docs/api-reference/common/WebSocket) / WebSocketConnectError
# Interface: WebSocketConnectError
Defined in: [packages/common/src/WebSocket.ts:86](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/WebSocket.ts#L86)
An error that occurs when a connection cannot be established due to a network
error.
## Properties
| Property | Modifier | Type | Defined in |
| -------------------------- | ---------- | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="event"></a> `event` | `readonly` | `Event` | [packages/common/src/WebSocket.ts:88](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/WebSocket.ts#L88) |
| <a id="type"></a> `type` | `readonly` | `"WebSocketConnectError"` | [packages/common/src/WebSocket.ts:87](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/WebSocket.ts#L87) |
WebSocketConnectionCloseError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [WebSocket](https://evolu.dev/docs/api-reference/common/WebSocket) / WebSocketConnectionCloseError
# Interface: WebSocketConnectionCloseError
Defined in: [packages/common/src/WebSocket.ts:106](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/WebSocket.ts#L106)
## Properties
| Property | Modifier | Type | Defined in |
| -------------------------- | ---------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| <a id="event"></a> `event` | `readonly` | `CloseEvent` | [packages/common/src/WebSocket.ts:108](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/WebSocket.ts#L108) |
| <a id="type"></a> `type` | `readonly` | `"WebSocketConnectionCloseError"` | [packages/common/src/WebSocket.ts:107](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/WebSocket.ts#L107) |
WebSocketConnectionError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [WebSocket](https://evolu.dev/docs/api-reference/common/WebSocket) / WebSocketConnectionError
# Interface: WebSocketConnectionError
Defined in: [packages/common/src/WebSocket.ts:97](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/WebSocket.ts#L97)
An error that occurs when a connection is closed due to an issue (e.g.,
failure to send some data).
https://developer.mozilla.org/en-US/docs/Web/API/WebSocket/error_event
## Properties
| Property | Modifier | Type | Defined in |
| -------------------------- | ---------- | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="event"></a> `event` | `readonly` | `Event` | [packages/common/src/WebSocket.ts:99](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/WebSocket.ts#L99) |
| <a id="type"></a> `type` | `readonly` | `"WebSocketConnectionError"` | [packages/common/src/WebSocket.ts:98](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/WebSocket.ts#L98) |
WebSocketOptions - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [WebSocket](https://evolu.dev/docs/api-reference/common/WebSocket) / WebSocketOptions
# Interface: WebSocketOptions
Defined in: [packages/common/src/WebSocket.ts:45](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/WebSocket.ts#L45)
Options for creating [WebSocket](https://evolu.dev/docs/api-reference/common/WebSocket/interfaces/WebSocket)
## Properties
| Property | Modifier | Type | Description | Defined in |
| --------------------------------------------------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="binarytype"></a> `binaryType?` | `public` | `"blob"` \| `"arraybuffer"` | Sets the binary type for the data being received. | [packages/common/src/WebSocket.ts:50](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/WebSocket.ts#L50) |
| <a id="onclose"></a> `onClose?` | `public` | (`event`) => `void` | Callback when the connection is closed. | [packages/common/src/WebSocket.ts:59](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/WebSocket.ts#L59) |
| <a id="onerror"></a> `onError?` | `public` | (`error`) => `void` | Callback when an error occurs. | [packages/common/src/WebSocket.ts:56](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/WebSocket.ts#L56) |
| <a id="onmessage"></a> `onMessage?` | `public` | (`data`) => `void` | Callback when message data is received. | [packages/common/src/WebSocket.ts:62](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/WebSocket.ts#L62) |
| <a id="onopen"></a> `onOpen?` | `public` | () => `void` | Callback when the connection is established. | [packages/common/src/WebSocket.ts:53](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/WebSocket.ts#L53) |
| <a id="protocols"></a> `protocols?` | `public` | `string` \| `string`[] | Protocol(s) to use with the WebSocket connection. | [packages/common/src/WebSocket.ts:47](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/WebSocket.ts#L47) |
| <a id="retryoptions"></a> `retryOptions?` | `public` | `Omit`\<[`RetryOptions`](https://evolu.dev/docs/api-reference/common/Task/interfaces/RetryOptions)\<[`WebSocketRetryError`](https://evolu.dev/docs/api-reference/common/WebSocket/type-aliases/WebSocketRetryError)\>, `"signal"`\> | Options for retry behavior. | [packages/common/src/WebSocket.ts:65](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/WebSocket.ts#L65) |
| <a id="websocketconstructor"></a> `WebSocketConstructor?` | `public` | \{ (`url`, `protocols?`): `WebSocket`; `CLOSED`: `3`; `CLOSING`: `2`; `CONNECTING`: `0`; `OPEN`: `1`; `prototype`: `WebSocket`; \} | For custom WebSocket implementations. This suppors blob: https://github.com/callstackincubator/react-native-fast-io | [packages/common/src/WebSocket.ts:74](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/WebSocket.ts#L74) |
| `WebSocketConstructor.CLOSED` | `readonly` | `3` | - | node_modules/typescript/lib/lib.dom.d.ts:36131 |
| `WebSocketConstructor.CLOSING` | `readonly` | `2` | - | node_modules/typescript/lib/lib.dom.d.ts:36130 |
| `WebSocketConstructor.CONNECTING` | `readonly` | `0` | - | node_modules/typescript/lib/lib.dom.d.ts:36128 |
| `WebSocketConstructor.OPEN` | `readonly` | `1` | - | node_modules/typescript/lib/lib.dom.d.ts:36129 |
| `WebSocketConstructor.prototype` | `public` | `WebSocket` | - | node_modules/typescript/lib/lib.dom.d.ts:36126 |
WebSocketSendError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [WebSocket](https://evolu.dev/docs/api-reference/common/WebSocket) / WebSocketSendError
# Interface: WebSocketSendError
Defined in: [packages/common/src/WebSocket.ts:28](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/WebSocket.ts#L28)
An error that occurs when trying to send data but WebSocket is not available
or is in the CONNECTING state.
https://developer.mozilla.org/en-US/docs/Web/API/WebSocket/send
## Properties
| Property | Modifier | Type | Defined in |
| ------------------------ | ---------- | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="type"></a> `type` | `readonly` | `"WebSocketSendError"` | [packages/common/src/WebSocket.ts:29](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/WebSocket.ts#L29) |
CreateWebSocket - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [WebSocket](https://evolu.dev/docs/api-reference/common/WebSocket) / CreateWebSocket
# Type Alias: CreateWebSocket()
```ts
type CreateWebSocket = (url, options?) => WebSocket;
```
Defined in: [packages/common/src/WebSocket.ts:35](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/WebSocket.ts#L35)
## Parameters
| Parameter | Type |
| ---------- | ------------------------------------------------------------------------------------------ |
| `url` | `string` |
| `options?` | [`WebSocketOptions`](https://evolu.dev/docs/api-reference/common/WebSocket/interfaces/WebSocketOptions) |
## Returns
[`WebSocket`](https://evolu.dev/docs/api-reference/common/WebSocket/interfaces/WebSocket)
WebSocketError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [WebSocket](https://evolu.dev/docs/api-reference/common/WebSocket) / WebSocketError
# Type Alias: WebSocketError
```ts
type WebSocketError =
| WebSocketConnectError
| WebSocketConnectionError
| RetryError<WebSocketRetryError>;
```
Defined in: [packages/common/src/WebSocket.ts:77](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/WebSocket.ts#L77)
WebSocketReadyState - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [WebSocket](https://evolu.dev/docs/api-reference/common/WebSocket) / WebSocketReadyState
# Type Alias: WebSocketReadyState
```ts
type WebSocketReadyState = "connecting" | "open" | "closing" | "closed";
```
Defined in: [packages/common/src/WebSocket.ts:33](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/WebSocket.ts#L33)
WebSocket connection states.
WebSocketRetryError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [WebSocket](https://evolu.dev/docs/api-reference/common/WebSocket) / WebSocketRetryError
# Type Alias: WebSocketRetryError
```ts
type WebSocketRetryError =
| WebSocketConnectError
| WebSocketConnectionCloseError;
```
Defined in: [packages/common/src/WebSocket.ts:102](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/WebSocket.ts#L102)
createWebSocket - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [WebSocket](https://evolu.dev/docs/api-reference/common/WebSocket) / createWebSocket
# Variable: createWebSocket
```ts
const createWebSocket: CreateWebSocket;
```
Defined in: [packages/common/src/WebSocket.ts:142](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/WebSocket.ts#L142)
Create a new [WebSocket](https://evolu.dev/docs/api-reference/common/WebSocket/interfaces/WebSocket).
The default behavior is that WebSocket tries to reconnect repeatedly in case
the application is offline, because online events (both web and native) are
not reliable. Once it connects and the connection is closed, it tries to
reconnect again. Retrying the connection can be controlled using the
retryOptions retryable predicate.
### How Binary Messages Work in WebSockets
The Server Chooses the Message Type:
- Text (0x1) → Sent as UTF-8 encoded text (always received as a string in the
browser).
- Binary (0x2) → Sent as raw binary data (received as a Blob or ArrayBuffer,
depending on binaryType).
The Client's binaryType Controls How Binary Data is Processed:
- If the server sends a text frame (0x1), the browser always delivers
event.data as a string, regardless of binaryType.
- If the server sends a binary frame (0x2), the browser delivers event.data as:
- A Blob (default: "blob")
- An ArrayBuffer ("arraybuffer")
### Example
TODO:
createInitializedWorker - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Worker](https://evolu.dev/docs/api-reference/common/Worker) / createInitializedWorker
# Function: createInitializedWorker()
```ts
function createInitializedWorker<Input, Output, Deps>(
__namedParameters,
): Worker<Input, Output>;
```
Defined in: [packages/common/src/Worker.ts:47](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Worker.ts#L47)
Creates a [Worker](https://evolu.dev/docs/api-reference/common/Worker/interfaces/Worker) that supports initialization with dependencies and
safe error handling.
## Type Parameters
| Type Parameter |
| -------------------------------------------------------------------------------- |
| `Input` _extends_ `object` |
| `Output` _extends_ `object` & \[`"Output.onError must have an error property"`\] |
| `Deps` |
## Parameters
| Parameter | Type |
| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `__namedParameters` | \{ `init`: (`initMessage`, `postMessage`, `withErrorReporting`) => `Promise`\<`Deps` \| `null`\>; `onMessage`: (`deps`) => (`message`) => `void`; \} |
| `__namedParameters.init` | (`initMessage`, `postMessage`, `withErrorReporting`) => `Promise`\<`Deps` \| `null`\> |
| `__namedParameters.onMessage` | (`deps`) => (`message`) => `void` |
## Returns
[`Worker`](https://evolu.dev/docs/api-reference/common/Worker/interfaces/Worker)\<`Input`, `Output`\>
createInitializedWorkerWithHandlers - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Worker](https://evolu.dev/docs/api-reference/common/Worker) / createInitializedWorkerWithHandlers
# Function: createInitializedWorkerWithHandlers()
```ts
function createInitializedWorkerWithHandlers<Input, Output, Deps>(
__namedParameters,
): Worker<Input, Output>;
```
Defined in: [packages/common/src/Worker.ts:147](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Worker.ts#L147)
Creates a [Worker](https://evolu.dev/docs/api-reference/common/Worker/interfaces/Worker) with type-safe message handlers for each message
type. This provides better type safety and organization compared to a single
onMessage handler.
## Type Parameters
| Type Parameter |
| -------------------------------------------------------------------------------- |
| `Input` _extends_ `object` |
| `Output` _extends_ `object` & \[`"Output.onError must have an error property"`\] |
| `Deps` |
## Parameters
| Parameter | Type |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `__namedParameters` | \{ `handlers`: `Omit`\<[`MessageHandlers`](https://evolu.dev/docs/api-reference/common/Worker/type-aliases/MessageHandlers)\<`Input`, `Deps`\>, `"init"`\>; `init`: (`initMessage`, `postMessage`, `withErrorReporting`) => `Promise`\<`Deps` \| `null`\>; \} |
| `__namedParameters.handlers` | `Omit`\<[`MessageHandlers`](https://evolu.dev/docs/api-reference/common/Worker/type-aliases/MessageHandlers)\<`Input`, `Deps`\>, `"init"`\> |
| `__namedParameters.init` | (`initMessage`, `postMessage`, `withErrorReporting`) => `Promise`\<`Deps` \| `null`\> |
## Returns
[`Worker`](https://evolu.dev/docs/api-reference/common/Worker/interfaces/Worker)\<`Input`, `Output`\>
Worker - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Worker](https://evolu.dev/docs/api-reference/common/Worker) / Worker
# Interface: Worker\<Input, Output\>
Defined in: [packages/common/src/Worker.ts:5](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Worker.ts#L5)
Cross-platform worker abstraction.
## Type Parameters
| Type Parameter |
| -------------- |
| `Input` |
| `Output` |
## Properties
| Property | Modifier | Type | Description | Defined in |
| -------------------------------------- | ---------- | ---------------------- | --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="onmessage"></a> `onMessage` | `readonly` | (`callback`) => `void` | Sets a callback for messages from the worker. | [packages/common/src/Worker.ts:10](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Worker.ts#L10) |
| <a id="postmessage"></a> `postMessage` | `readonly` | (`message`) => `void` | Sends a message to the worker. | [packages/common/src/Worker.ts:7](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Worker.ts#L7) |
WorkerPostMessageDep - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Worker](https://evolu.dev/docs/api-reference/common/Worker) / WorkerPostMessageDep
# Interface: WorkerPostMessageDep\<Output\>
Defined in: [packages/common/src/Worker.ts:13](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Worker.ts#L13)
## Type Parameters
| Type Parameter |
| -------------- |
| `Output` |
## Properties
| Property | Modifier | Type | Defined in |
| -------------------------------------- | ---------- | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="postmessage"></a> `postMessage` | `readonly` | (`message`) => `void` | [packages/common/src/Worker.ts:14](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Worker.ts#L14) |
MessageHandlers - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Worker](https://evolu.dev/docs/api-reference/common/Worker) / MessageHandlers
# Type Alias: MessageHandlers\<Input, Deps\>
```ts
type MessageHandlers<Input, Deps> = {
readonly [K in Input["type"]]: (
deps: Deps,
) => (message: Extract<Input, { type: K }>) => void;
};
```
Defined in: [packages/common/src/Worker.ts:136](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Worker.ts#L136)
Type helper to extract message types from a union type
## Type Parameters
| Type Parameter |
| -------------------------- |
| `Input` _extends_ `object` |
| `Deps` |
WithErrorReporting - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Worker](https://evolu.dev/docs/api-reference/common/Worker) / WithErrorReporting
# Type Alias: WithErrorReporting()
```ts
type WithErrorReporting = <A>(handler) => (...args) => void;
```
Defined in: [packages/common/src/Worker.ts:21](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Worker.ts#L21)
Error reporting wrapper that catches synchronous errors in handlers and
converts them to transferable error messages sent to the main thread.
## Type Parameters
| Type Parameter |
| --------------------- |
| `A` _extends_ `any`[] |
## Parameters
| Parameter | Type |
| --------- | --------------------- |
| `handler` | (...`args`) => `void` |
## Returns
```ts
(...args): void;
```
### Parameters
| Parameter | Type |
| --------- | ---- |
| ...`args` | `A` |
### Returns
`void`
applyLocalOnlyChange - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / applyLocalOnlyChange
# Function: applyLocalOnlyChange()
```ts
function applyLocalOnlyChange(deps): (change) => Result<void, SqliteError>;
```
Defined in: [packages/common/src/local-first/Sync.ts:663](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Sync.ts#L663)
## Parameters
| Parameter | Type |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `deps` | [`SqliteDep`](https://evolu.dev/docs/api-reference/common/Sqlite/interfaces/SqliteDep) & [`TimeDep`](https://evolu.dev/docs/api-reference/common/Time/interfaces/TimeDep) & [`AppOwnerDep`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/AppOwnerDep) |
## Returns
```ts
(change): Result<void, SqliteError>;
```
### Parameters
| Parameter | Type |
| --------- | ---------------------------------------------------------------------------------------- |
| `change` | [`MutationChange`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/MutationChange) |
### Returns
[`Result`](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result)\<`void`, [`SqliteError`](https://evolu.dev/docs/api-reference/common/Sqlite/interfaces/SqliteError)\>
applyPatches - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / applyPatches
# Function: applyPatches()
```ts
function applyPatches(patches, current): readonly Row[];
```
Defined in: [packages/common/src/local-first/Query.ts:294](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Query.ts#L294)
## Parameters
| Parameter | Type |
| --------- | ----------------------------------------------------------------------------------- |
| `patches` | readonly [`Patch`](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/Patch)[] |
| `current` | readonly [`Row`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Row)[] |
## Returns
readonly [`Row`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Row)[]
createAppOwner - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / createAppOwner
# Function: createAppOwner()
```ts
function createAppOwner(secret): AppOwner;
```
Defined in: [packages/common/src/local-first/Owner.ts:200](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Owner.ts#L200)
Creates an [AppOwner](https://evolu.dev/docs/api-reference/common/local-first/interfaces/AppOwner) from an [OwnerSecret](https://evolu.dev/docs/api-reference/common/local-first/variables/OwnerSecret).
## Parameters
| Parameter | Type |
| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `secret` | `Uint8Array`\<`ArrayBufferLike`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Entropy"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Length32"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"OwnerSecret"`\> |
## Returns
[`AppOwner`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/AppOwner)
createBaseSqliteStorage - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / createBaseSqliteStorage
# Function: createBaseSqliteStorage()
```ts
function createBaseSqliteStorage(deps): (config) => BaseSqliteStorage;
```
Defined in: [packages/common/src/local-first/Storage.ts:376](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Storage.ts#L376)
Creates a [BaseSqliteStorage](https://evolu.dev/docs/api-reference/common/local-first/interfaces/BaseSqliteStorage) implementation.
# Stateless Design
This implementation is fully stateless - it requires no in-memory state
between invocations. All necessary metadata (timestamp bounds for insertion
strategy optimization) is persisted in the evolu_usage table. This makes
Evolu Relay suitable for stateless serverless environments like AWS Lambda,
Cloudflare Workers with Durable Objects, and other platforms where memory
doesn't persist between requests. While not extensively tested in all these
environments yet, the stateless design should work well across them.
## Parameters
| Parameter | Type |
| --------- | ------------------------------------------------------------------------------------------------ |
| `deps` | [`SqliteStorageDeps`](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/SqliteStorageDeps) |
## Returns
```ts
(config): BaseSqliteStorage;
```
### Parameters
| Parameter | Type |
| --------- | ---------------------------------------------------------------------------------------------------------------------- |
| `config` | [`CreateBaseSqliteStorageConfig`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/CreateBaseSqliteStorageConfig) |
### Returns
[`BaseSqliteStorage`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/BaseSqliteStorage)
createBaseSqliteStorageTables - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / createBaseSqliteStorageTables
# Function: createBaseSqliteStorageTables()
```ts
function createBaseSqliteStorageTables(deps): Result<void, SqliteError>;
```
Defined in: [packages/common/src/local-first/Storage.ts:520](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Storage.ts#L520)
## Parameters
| Parameter | Type |
| --------- | ------------------------------------------------------------------------- |
| `deps` | [`SqliteDep`](https://evolu.dev/docs/api-reference/common/Sqlite/interfaces/SqliteDep) |
## Returns
[`Result`](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result)\<`void`, [`SqliteError`](https://evolu.dev/docs/api-reference/common/Sqlite/interfaces/SqliteError)\>
createClock - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / createClock
# Function: createClock()
```ts
function createClock(deps): (initialTimestamp) => Clock;
```
Defined in: [packages/common/src/local-first/Sync.ts:416](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Sync.ts#L416)
## Parameters
| Parameter | Type |
| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `deps` | [`RandomBytesDep`](https://evolu.dev/docs/api-reference/common/Crypto/interfaces/RandomBytesDep) & [`SqliteDep`](https://evolu.dev/docs/api-reference/common/Sqlite/interfaces/SqliteDep) |
## Returns
```ts
(initialTimestamp): Clock;
```
### Parameters
| Parameter | Type |
| ------------------ | ------------------------------------------------------------------------------ |
| `initialTimestamp` | [`Timestamp`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Timestamp) |
### Returns
[`Clock`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Clock)
createDbWorkerForPlatform - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / createDbWorkerForPlatform
# Function: createDbWorkerForPlatform()
```ts
function createDbWorkerForPlatform(platformDeps): DbWorker;
```
Defined in: [packages/common/src/local-first/Db.ts:329](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Db.ts#L329)
## Parameters
| Parameter | Type |
| -------------- | ------------------------------------------------------------------------------------------------------ |
| `platformDeps` | [`DbWorkerPlatformDeps`](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/DbWorkerPlatformDeps) |
## Returns
[`DbWorker`](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/DbWorker)
createEvolu - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / createEvolu
# Function: createEvolu()
```ts
function createEvolu(deps): <S>(schema, config?) => Evolu<S>;
```
Defined in: [packages/common/src/local-first/Evolu.ts:534](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Evolu.ts#L534)
Creates an [Evolu](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Evolu) instance for a platform configured with the specified
[EvoluSchema](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/EvoluSchema) and optional [EvoluConfig](https://evolu.dev/docs/api-reference/common/local-first/interfaces/EvoluConfig) providing a typed
interface for querying, mutating, and syncing your application's data.
### Example
```ts
const TodoId = id("Todo");
type TodoId = InferType<typeof TodoId>;
const TodoCategoryId = id("TodoCategory");
type TodoCategoryId = InferType<typeof TodoCategoryId>;
const NonEmptyString50 = maxLength(50, NonEmptyString);
type NonEmptyString50 = InferType<typeof NonEmptyString50>;
const Schema = {
todo: {
id: TodoId,
title: NonEmptyString1000,
isCompleted: nullOr(SqliteBoolean),
categoryId: nullOr(TodoCategoryId),
},
todoCategory: {
id: TodoCategoryId,
name: NonEmptyString50,
},
};
const evolu = createEvolu(evoluReactDeps)(Schema);
```
### Instance Caching
`createEvolu` caches instances using [Instances](https://evolu.dev/docs/api-reference/common/Instances/interfaces/Instances) by [EvoluConfig](https://evolu.dev/docs/api-reference/common/local-first/interfaces/EvoluConfig)
name to enable hot reloading and prevent database corruption from multiple
connections. For testing, use unique instance names to ensure proper
isolation.
## Parameters
| Parameter | Type |
| --------- | -------------------------------------------------------------------------------- |
| `deps` | [`EvoluDeps`](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/EvoluDeps) |
## Returns
```ts
<S>(schema, config?): Evolu<S>;
```
### Type Parameters
| Type Parameter |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `S` _extends_ `Readonly`\<`Record`\<`string`, `Readonly`\<`Record`\<`string`, [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type)\<`any`, `any`, `any`, `any`, `any`, `any`\>\>\>\>\> |
### Parameters
| Parameter | Type |
| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `schema` | [`ValidateSchema`](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/ValidateSchema)\<`S`\> _extends_ `never` ? `S` : [`ValidateSchema`](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/ValidateSchema)\<`S`\> |
| `config?` | [`EvoluConfig`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/EvoluConfig) |
### Returns
[`Evolu`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Evolu)\<`S`\>
createGetQueryRowsCache - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / createGetQueryRowsCache
# Function: createGetQueryRowsCache()
```ts
function createGetQueryRowsCache(): GetQueryRowsCache;
```
Defined in: [packages/common/src/local-first/Query.ts:175](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Query.ts#L175)
## Returns
[`GetQueryRowsCache`](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/GetQueryRowsCache)
createInitialTimestamp - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / createInitialTimestamp
# Function: createInitialTimestamp()
```ts
function createInitialTimestamp(deps): Timestamp;
```
Defined in: [packages/common/src/local-first/Timestamp.ts:189](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Timestamp.ts#L189)
## Parameters
| Parameter | Type |
| --------- | ----------------------------------------------------------------------------------- |
| `deps` | [`RandomBytesDep`](https://evolu.dev/docs/api-reference/common/Crypto/interfaces/RandomBytesDep) |
## Returns
[`Timestamp`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Timestamp)
createOwnerSecret - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / createOwnerSecret
# Function: createOwnerSecret()
```ts
function createOwnerSecret(
deps,
): Uint8Array<ArrayBufferLike> &
Brand<"Entropy"> &
Brand<"Length32"> &
Brand<"OwnerSecret">;
```
Defined in: [packages/common/src/local-first/Owner.ts:120](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Owner.ts#L120)
Creates a [OwnerSecret](https://evolu.dev/docs/api-reference/common/local-first/variables/OwnerSecret).
## Parameters
| Parameter | Type |
| --------- | ----------------------------------------------------------------------------------- |
| `deps` | [`RandomBytesDep`](https://evolu.dev/docs/api-reference/common/Crypto/interfaces/RandomBytesDep) |
## Returns
`Uint8Array`\<`ArrayBufferLike`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Entropy"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Length32"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"OwnerSecret"`\>
createOwnerWebSocketTransport - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / createOwnerWebSocketTransport
# Function: createOwnerWebSocketTransport()
```ts
function createOwnerWebSocketTransport(config): OwnerWebSocketTransport;
```
Defined in: [packages/common/src/local-first/Owner.ts:356](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Owner.ts#L356)
Creates an [OwnerWebSocketTransport](https://evolu.dev/docs/api-reference/common/local-first/interfaces/OwnerWebSocketTransport) for the given relay URL and
[OwnerId](https://evolu.dev/docs/api-reference/common/local-first/variables/OwnerId).
The URL must be a WebSocket base URL without query parameters or fragments
(e.g., `wss://relay.evolu.dev`, not `wss://relay.evolu.dev?foo=bar`). The
function appends the `ownerId` as a query parameter.
### Example
```ts
// Create transport "wss://relay.evolu.dev?ownerId=..."
const transport = createOwnerWebSocketTransport({
url: "wss://relay.evolu.dev",
ownerId: owner.id,
});
// Use with createEvolu
const evolu = createEvolu(deps)(Schema, {
transports: [transport],
});
```
## Parameters
| Parameter | Type |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `config` | \{ `ownerId`: `string` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Id"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"OwnerId"`\>; `url`: `string`; \} |
| `config.ownerId` | `string` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Id"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"OwnerId"`\> |
| `config.url` | `string` |
## Returns
[`OwnerWebSocketTransport`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/OwnerWebSocketTransport)
createOwnerWriteKey - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / createOwnerWriteKey
# Function: createOwnerWriteKey()
```ts
function createOwnerWriteKey(
deps,
): Uint8Array<ArrayBufferLike> &
Brand<"Entropy"> &
Brand<"Length16"> &
Brand<"OwnerWriteKey">;
```
Defined in: [packages/common/src/local-first/Owner.ts:107](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Owner.ts#L107)
Creates a new random [OwnerWriteKey](https://evolu.dev/docs/api-reference/common/local-first/variables/OwnerWriteKey) for rotation.
The initial OwnerWriteKey is deterministically derived from
[OwnerSecret](https://evolu.dev/docs/api-reference/common/local-first/variables/OwnerSecret). Use `createOwnerWriteKey` to rotate (replace) the write
key without changing the owner identity.
## Parameters
| Parameter | Type |
| --------- | ----------------------------------------------------------------------------------- |
| `deps` | [`RandomBytesDep`](https://evolu.dev/docs/api-reference/common/Crypto/interfaces/RandomBytesDep) |
## Returns
`Uint8Array`\<`ArrayBufferLike`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Entropy"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Length16"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"OwnerWriteKey"`\>
createQuery - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / createQuery
# Function: createQuery()
```ts
function createQuery<R>(queryCallback, options?): Query<R>;
```
Defined in: [packages/common/src/local-first/Evolu.ts:973](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Evolu.ts#L973)
## Type Parameters
| Type Parameter |
| -------------------------------------------------------------------------------- |
| `R` _extends_ [`Row`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Row) |
## Parameters
| Parameter | Type |
| --------------- | ------------------------------------------------------------------------------------------------------------------ |
| `queryCallback` | (`db`) => `SelectQueryBuilder`\<`any`, `any`, [`Row`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Row)\> |
| `options?` | [`SqliteQueryOptions`](https://evolu.dev/docs/api-reference/common/Sqlite/interfaces/SqliteQueryOptions) |
## Returns
[`Query`](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/Query)\<`R`\>
createRelayLogger - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / createRelayLogger
# Function: createRelayLogger()
```ts
function createRelayLogger(deps): RelayLogger;
```
Defined in: [packages/common/src/local-first/Relay.ts:392](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Relay.ts#L392)
## Parameters
| Parameter | Type |
| --------- | ---------------------------------------------------------------------------- |
| `deps` | [`ConsoleDep`](https://evolu.dev/docs/api-reference/common/Console/interfaces/ConsoleDep) |
## Returns
[`RelayLogger`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/RelayLogger)
createRelaySqliteStorage - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / createRelaySqliteStorage
# Function: createRelaySqliteStorage()
```ts
function createRelaySqliteStorage(deps): (config) => Storage;
```
Defined in: [packages/common/src/local-first/Relay.ts:103](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Relay.ts#L103)
## Parameters
| Parameter | Type |
| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `deps` | [`RandomDep`](https://evolu.dev/docs/api-reference/common/Random/interfaces/RandomDep) & [`SqliteDep`](https://evolu.dev/docs/api-reference/common/Sqlite/interfaces/SqliteDep) & [`TimingSafeEqualDep`](https://evolu.dev/docs/api-reference/common/Crypto/interfaces/TimingSafeEqualDep) |
## Returns
```ts
(config): Storage;
```
### Parameters
| Parameter | Type |
| --------- | ---------------------------------------------------------------------------------------------------------------------- |
| `config` | [`CreateBaseSqliteStorageConfig`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/CreateBaseSqliteStorageConfig) |
### Returns
[`Storage`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Storage)
createRelayStorageTables - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / createRelayStorageTables
# Function: createRelayStorageTables()
```ts
function createRelayStorageTables(deps): Result<void, SqliteError>;
```
Defined in: [packages/common/src/local-first/Relay.ts:329](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Relay.ts#L329)
## Parameters
| Parameter | Type |
| --------- | ------------------------------------------------------------------------- |
| `deps` | [`SqliteDep`](https://evolu.dev/docs/api-reference/common/Sqlite/interfaces/SqliteDep) |
## Returns
[`Result`](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result)\<`void`, [`SqliteError`](https://evolu.dev/docs/api-reference/common/Sqlite/interfaces/SqliteError)\>
createShardOwner - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / createShardOwner
# Function: createShardOwner()
```ts
function createShardOwner(secret): ShardOwner;
```
Defined in: [packages/common/src/local-first/Owner.ts:222](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Owner.ts#L222)
Creates a [ShardOwner](https://evolu.dev/docs/api-reference/common/local-first/interfaces/ShardOwner) from an [OwnerSecret](https://evolu.dev/docs/api-reference/common/local-first/variables/OwnerSecret).
## Parameters
| Parameter | Type |
| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `secret` | `Uint8Array`\<`ArrayBufferLike`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Entropy"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Length32"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"OwnerSecret"`\> |
## Returns
[`ShardOwner`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/ShardOwner)
createSharedOwner - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / createSharedOwner
# Function: createSharedOwner()
```ts
function createSharedOwner(secret): SharedOwner;
```
Defined in: [packages/common/src/local-first/Owner.ts:271](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Owner.ts#L271)
Creates a [SharedOwner](https://evolu.dev/docs/api-reference/common/local-first/interfaces/SharedOwner) from an [OwnerSecret](https://evolu.dev/docs/api-reference/common/local-first/variables/OwnerSecret) for collaborative
write access.
Use [createSharedReadonlyOwner](https://evolu.dev/docs/api-reference/common/local-first/functions/createSharedReadonlyOwner) to create a read-only version for
sharing.
## Parameters
| Parameter | Type |
| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `secret` | `Uint8Array`\<`ArrayBufferLike`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Entropy"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Length32"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"OwnerSecret"`\> |
## Returns
[`SharedOwner`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/SharedOwner)
createSharedReadonlyOwner - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / createSharedReadonlyOwner
# Function: createSharedReadonlyOwner()
```ts
function createSharedReadonlyOwner(sharedOwner): SharedReadonlyOwner;
```
Defined in: [packages/common/src/local-first/Owner.ts:286](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Owner.ts#L286)
Creates a [SharedReadonlyOwner](https://evolu.dev/docs/api-reference/common/local-first/interfaces/SharedReadonlyOwner) from a [SharedOwner](https://evolu.dev/docs/api-reference/common/local-first/interfaces/SharedOwner).
## Parameters
| Parameter | Type |
| ------------- | ---------------------------------------------------------------------------------- |
| `sharedOwner` | [`SharedOwner`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/SharedOwner) |
## Returns
[`SharedReadonlyOwner`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/SharedReadonlyOwner)
createSubscribedQueries - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / createSubscribedQueries
# Function: createSubscribedQueries()
```ts
function createSubscribedQueries(rowsStore): SubscribedQueries;
```
Defined in: [packages/common/src/local-first/Query.ts:134](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Query.ts#L134)
## Parameters
| Parameter | Type |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `rowsStore` | [`Store`](https://evolu.dev/docs/api-reference/common/Store/interfaces/Store)\<[`QueryRowsMap`](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/QueryRowsMap)\> |
## Returns
[`SubscribedQueries`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/SubscribedQueries)
createSync - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / createSync
# Function: createSync()
```ts
function createSync(deps): (config) => Result<Sync, SqliteError>;
```
Defined in: [packages/common/src/local-first/Sync.ts:157](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Sync.ts#L157)
## Parameters
| Parameter | Type |
| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `deps` | [`ClockDep`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/ClockDep) & [`ConsoleDep`](https://evolu.dev/docs/api-reference/common/Console/interfaces/ConsoleDep) & [`CreateWebSocketDep`](https://evolu.dev/docs/api-reference/common/WebSocket/interfaces/CreateWebSocketDep) & [`DbSchemaDep`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/DbSchemaDep) & [`RandomBytesDep`](https://evolu.dev/docs/api-reference/common/Crypto/interfaces/RandomBytesDep) & [`RandomDep`](https://evolu.dev/docs/api-reference/common/Random/interfaces/RandomDep) & [`SqliteDep`](https://evolu.dev/docs/api-reference/common/Sqlite/interfaces/SqliteDep) & [`SymmetricCryptoDep`](https://evolu.dev/docs/api-reference/common/Crypto/interfaces/SymmetricCryptoDep) & [`TimeDep`](https://evolu.dev/docs/api-reference/common/Time/interfaces/TimeDep) & [`TimestampConfigDep`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/TimestampConfigDep) |
## Returns
```ts
(config): Result<Sync, SqliteError>;
```
### Parameters
| Parameter | Type |
| --------- | -------------------------------------------------------------------------------- |
| `config` | [`SyncConfig`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/SyncConfig) |
### Returns
[`Result`](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result)\<[`Sync`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Sync), [`SqliteError`](https://evolu.dev/docs/api-reference/common/Sqlite/interfaces/SqliteError)\>
createTimestamp - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / createTimestamp
# Function: createTimestamp()
```ts
function createTimestamp(__namedParameters): Timestamp;
```
Defined in: [packages/common/src/local-first/Timestamp.ts:183](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Timestamp.ts#L183)
## Parameters
| Parameter | Type |
| ------------------- | ------------------------------------------------------------------------------------------- |
| `__namedParameters` | `Partial`\<[`Timestamp`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Timestamp)\> |
## Returns
[`Timestamp`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Timestamp)
deriveShardOwner - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / deriveShardOwner
# Function: deriveShardOwner()
```ts
function deriveShardOwner(owner, path): ShardOwner;
```
Defined in: [packages/common/src/local-first/Owner.ts:247](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Owner.ts#L247)
Derives a [ShardOwner](https://evolu.dev/docs/api-reference/common/local-first/interfaces/ShardOwner) from an [AppOwner](https://evolu.dev/docs/api-reference/common/local-first/interfaces/AppOwner) using the specified path.
**Advantages of derived owners:**
- **Deterministic**: Same path always produces the same ShardOwner across all
devices
- **Immediate availability**: Can be hardcoded and used before sync occurs
- **Consistent setup**: All devices start with identical data structure
- **Lifecycle management**: Can implement epoch patterns for clean data
deletion and recreation
**Common patterns:**
- Use paths like `["shard", 1]` for versioned data lifecycle
- Use paths like `["project", "MyApp", 1]` for named partitions with versions
- Each device can derive the same owners and set up initial structure
## Parameters
| Parameter | Type |
| --------- | ---------------------------------------------------------------------------- |
| `owner` | [`AppOwner`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/AppOwner) |
| `path` | readonly \[`string` \| `number`, `string` \| `number`\] |
## Returns
[`ShardOwner`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/ShardOwner)
deserializeQuery - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / deserializeQuery
# Function: deserializeQuery()
```ts
function deserializeQuery<R>(query): SqliteQuery;
```
Defined in: [packages/common/src/local-first/Query.ts:73](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Query.ts#L73)
## Type Parameters
| Type Parameter |
| -------------------------------------------------------------------------------- |
| `R` _extends_ [`Row`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Row) |
## Parameters
| Parameter | Type |
| --------- | ------------------------------------------------------------------------------- |
| `query` | [`Query`](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/Query)\<`R`\> |
## Returns
[`SqliteQuery`](https://evolu.dev/docs/api-reference/common/Sqlite/interfaces/SqliteQuery)
ensureDbSchema - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / ensureDbSchema
# Function: ensureDbSchema()
```ts
function ensureDbSchema(
deps,
): (newSchema, currentSchema?) => Result<void, SqliteError>;
```
Defined in: [packages/common/src/local-first/Schema.ts:546](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Schema.ts#L546)
## Parameters
| Parameter | Type |
| --------- | ------------------------------------------------------------------------- |
| `deps` | [`SqliteDep`](https://evolu.dev/docs/api-reference/common/Sqlite/interfaces/SqliteDep) |
## Returns
```ts
(newSchema, currentSchema?): Result<void, SqliteError>;
```
### Parameters
| Parameter | Type |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `newSchema` | [`DbSchema`](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/DbSchema) |
| `currentSchema?` | `Readonly`\<\{ `indexes`: readonly `Readonly`\<\{ `name`: `string`; `sql`: `string`; \}\>[]; `tables`: `Readonly`\<`Record`\<`string`, `ReadonlySet`\<`string`\>\>\>; \}\> |
### Returns
[`Result`](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result)\<`void`, [`SqliteError`](https://evolu.dev/docs/api-reference/common/Sqlite/interfaces/SqliteError)\>
evoluSchemaToDbSchema - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / evoluSchemaToDbSchema
# Function: evoluSchemaToDbSchema()
```ts
function evoluSchemaToDbSchema(schema, indexesConfig?): DbSchema;
```
Defined in: [packages/common/src/local-first/Schema.ts:176](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Schema.ts#L176)
## Parameters
| Parameter | Type |
| ---------------- | ---------------------------------------------------------------------------------------- |
| `schema` | [`EvoluSchema`](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/EvoluSchema) |
| `indexesConfig?` | [`IndexesConfig`](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/IndexesConfig) |
## Returns
[`DbSchema`](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/DbSchema)
getDbSchema - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / getDbSchema
# Function: getDbSchema()
```ts
function getDbSchema(deps): (__namedParameters) => Result<
Readonly<{
indexes: readonly Readonly<{
name: string;
sql: string;
}>[];
tables: Readonly<Record<string, ReadonlySet<string>>>;
}>,
SqliteError
>;
```
Defined in: [packages/common/src/local-first/Schema.ts:480](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Schema.ts#L480)
Get the current database schema by reading SQLite metadata.
## Parameters
| Parameter | Type |
| --------- | ------------------------------------------------------------------------- |
| `deps` | [`SqliteDep`](https://evolu.dev/docs/api-reference/common/Sqlite/interfaces/SqliteDep) |
## Returns
```ts
(__namedParameters): Result<Readonly<{
indexes: readonly Readonly<{
name: string;
sql: string;
}>[];
tables: Readonly<Record<string, ReadonlySet<string>>>;
}>, SqliteError>;
```
### Parameters
| Parameter | Type |
| ------------------------------- | ------------------------------- |
| `__namedParameters` | \{ `allIndexes?`: `boolean`; \} |
| `__namedParameters.allIndexes?` | `boolean` |
### Returns
[`Result`](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result)\<`Readonly`\<\{
`indexes`: readonly `Readonly`\<\{
`name`: `string`;
`sql`: `string`;
\}\>[];
`tables`: `Readonly`\<`Record`\<`string`, `ReadonlySet`\<`string`\>\>\>;
\}\>, [`SqliteError`](https://evolu.dev/docs/api-reference/common/Sqlite/interfaces/SqliteError)\>
getOwnerUsage - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / getOwnerUsage
# Function: getOwnerUsage()
```ts
function getOwnerUsage(deps): (
ownerIdBytes,
initialTimestamp,
) => Result<
{
firstTimestamp: Uint8Array<ArrayBufferLike> & Brand<"TimestampBytes">;
lastTimestamp: Uint8Array<ArrayBufferLike> & Brand<"TimestampBytes">;
storedBytes: (number & Brand<"Int"> & Brand<"NonNegative">) | null;
},
SqliteError
>;
```
Defined in: [packages/common/src/local-first/Storage.ts:1639](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Storage.ts#L1639)
Retrieves usage information for an owner from the evolu_usage table.
## Parameters
| Parameter | Type |
| --------- | ------------------------------------------------------------------------- |
| `deps` | [`SqliteDep`](https://evolu.dev/docs/api-reference/common/Sqlite/interfaces/SqliteDep) |
## Returns
```ts
(ownerIdBytes, initialTimestamp): Result<{
firstTimestamp: Uint8Array<ArrayBufferLike> & Brand<"TimestampBytes">;
lastTimestamp: Uint8Array<ArrayBufferLike> & Brand<"TimestampBytes">;
storedBytes: | number & Brand<"Int"> & Brand<"NonNegative">
| null;
}, SqliteError>;
```
### Parameters
| Parameter | Type |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ownerIdBytes` | `Uint8Array`\<`ArrayBufferLike`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Length16"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"IdBytes"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"OwnerIdBytes"`\> |
| `initialTimestamp` | `Uint8Array`\<`ArrayBufferLike`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"TimestampBytes"`\> |
### Returns
[`Result`](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result)\<\{
`firstTimestamp`: `Uint8Array`\<`ArrayBufferLike`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"TimestampBytes"`\>;
`lastTimestamp`: `Uint8Array`\<`ArrayBufferLike`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"TimestampBytes"`\>;
`storedBytes`: \| `number` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Int"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"NonNegative"`\>
\| `null`;
\}, [`SqliteError`](https://evolu.dev/docs/api-reference/common/Sqlite/interfaces/SqliteError)\>
getTimestampByIndex - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / getTimestampByIndex
# Function: getTimestampByIndex()
```ts
function getTimestampByIndex(
deps,
): (
ownerId,
index,
) => Result<Uint8Array<ArrayBufferLike> & Brand<"TimestampBytes">, SqliteError>;
```
Defined in: [packages/common/src/local-first/Storage.ts:1554](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Storage.ts#L1554)
## Parameters
| Parameter | Type |
| --------- | ------------------------------------------------------------------------- |
| `deps` | [`SqliteDep`](https://evolu.dev/docs/api-reference/common/Sqlite/interfaces/SqliteDep) |
## Returns
```ts
(ownerId, index): Result<Uint8Array<ArrayBufferLike> & Brand<"TimestampBytes">, SqliteError>;
```
### Parameters
| Parameter | Type |
| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ownerId` | `Uint8Array`\<`ArrayBufferLike`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Length16"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"IdBytes"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"OwnerIdBytes"`\> |
| `index` | `number` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Int"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"NonNegative"`\> |
### Returns
[`Result`](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result)\<`Uint8Array`\<`ArrayBufferLike`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"TimestampBytes"`\>, [`SqliteError`](https://evolu.dev/docs/api-reference/common/Sqlite/interfaces/SqliteError)\>
getTimestampInsertStrategy - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / getTimestampInsertStrategy
# Function: getTimestampInsertStrategy()
```ts
function getTimestampInsertStrategy(
timestamp,
firstTimestamp,
lastTimestamp,
): [
StorageInsertTimestampStrategy,
Uint8Array<ArrayBufferLike> & Brand<"TimestampBytes">,
Uint8Array<ArrayBufferLike> & Brand<"TimestampBytes">,
];
```
Defined in: [packages/common/src/local-first/Storage.ts:598](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Storage.ts#L598)
Determines the insertion strategy for a timestamp based on its position
relative to the current first and last timestamps.
Returns a tuple with the strategy and updated timestamp bounds.
## Parameters
| Parameter | Type |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `timestamp` | `Uint8Array`\<`ArrayBufferLike`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"TimestampBytes"`\> |
| `firstTimestamp` | `Uint8Array`\<`ArrayBufferLike`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"TimestampBytes"`\> |
| `lastTimestamp` | `Uint8Array`\<`ArrayBufferLike`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"TimestampBytes"`\> |
## Returns
\[[`StorageInsertTimestampStrategy`](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/StorageInsertTimestampStrategy), `Uint8Array`\<`ArrayBufferLike`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"TimestampBytes"`\>, `Uint8Array`\<`ArrayBufferLike`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"TimestampBytes"`\>\]
insertable - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / insertable
# Function: insertable()
```ts
function insertable<Props>(props): ValidMutationSize<InsertableProps<Props>>;
```
Defined in: [packages/common/src/local-first/Schema.ts:347](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Schema.ts#L347)
Type Factory to create insertable [Type](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type). It makes nullable Types
optional (so they are not required), omits Id, and ensures the
[maxMutationSize](https://evolu.dev/docs/api-reference/common/Type/variables/maxMutationSize).
### Example
```ts
const InsertableTodo = insertable(Schema.todo);
type InsertableTodo = typeof InsertableTodo.Type;
const todo = InsertableTodo.from({ title });
if (!todo.ok) return; // handle errors
```
## Type Parameters
| Type Parameter |
| ------------------------------------------------------------------------------------------------------------- |
| `Props` _extends_ `Record`\<`string`, [`AnyType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/AnyType)\> |
## Parameters
| Parameter | Type |
| --------- | ------- |
| `props` | `Props` |
## Returns
[`ValidMutationSize`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/ValidMutationSize)\<[`InsertableProps`](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/InsertableProps)\<`Props`\>\>
loadQueries - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / loadQueries
# Function: loadQueries()
```ts
function loadQueries(
deps,
): (tabId, queries) => Result<readonly QueryPatches[], SqliteError>;
```
Defined in: [packages/common/src/local-first/Query.ts:195](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Query.ts#L195)
## Parameters
| Parameter | Type |
| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `deps` | [`GetQueryRowsCacheDep`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/GetQueryRowsCacheDep) & [`SqliteDep`](https://evolu.dev/docs/api-reference/common/Sqlite/interfaces/SqliteDep) |
## Returns
```ts
(tabId, queries): Result<readonly QueryPatches[], SqliteError>;
```
### Parameters
| Parameter | Type |
| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `tabId` | `string` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Id"`\> |
| `queries` | readonly [`Query`](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/Query)\<[`Row`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Row)\>[] |
### Returns
[`Result`](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result)\<readonly [`QueryPatches`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/QueryPatches)[], [`SqliteError`](https://evolu.dev/docs/api-reference/common/Sqlite/interfaces/SqliteError)\>
makePatches - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / makePatches
# Function: makePatches()
```ts
function makePatches(previousRows, nextRows): readonly Patch[];
```
Defined in: [packages/common/src/local-first/Query.ts:257](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Query.ts#L257)
We detect only changes in the whole result and in-place edits. In the future,
we will add more heuristics. We will probably not implement the Myers diff
algorithm because it's faster to rerender all than to compute many detailed
patches. We will only implement logic a developer would implement manually,
if necessary.
## Parameters
| Parameter | Type |
| -------------- | ----------------------------------------------------------------------------------------------- |
| `previousRows` | \| readonly [`Row`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Row)[] \| `undefined` |
| `nextRows` | readonly [`Row`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Row)[] |
## Returns
readonly [`Patch`](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/Patch)[]
mnemonicToOwnerSecret - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / mnemonicToOwnerSecret
# Function: mnemonicToOwnerSecret()
```ts
function mnemonicToOwnerSecret(
mnemonic,
): Uint8Array<ArrayBufferLike> &
Brand<"Entropy"> &
Brand<"Length32"> &
Brand<"OwnerSecret">;
```
Defined in: [packages/common/src/local-first/Owner.ts:128](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Owner.ts#L128)
Converts a [Mnemonic](https://evolu.dev/docs/api-reference/common/Type/variables/Mnemonic) to an [OwnerSecret](https://evolu.dev/docs/api-reference/common/local-first/variables/OwnerSecret).
## Parameters
| Parameter | Type |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `mnemonic` | `string` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Trimmed"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"MinLength1"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Mnemonic"`\> |
## Returns
`Uint8Array`\<`ArrayBufferLike`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Entropy"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Length32"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"OwnerSecret"`\>
ownerIdBytesToOwnerId - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / ownerIdBytesToOwnerId
# Function: ownerIdBytesToOwnerId()
```ts
function ownerIdBytesToOwnerId(
ownerIdBytes,
): string & Brand<"Id"> & Brand<"OwnerId">;
```
Defined in: [packages/common/src/local-first/Owner.ts:84](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Owner.ts#L84)
Converts [OwnerIdBytes](https://evolu.dev/docs/api-reference/common/local-first/variables/OwnerIdBytes) to [OwnerId](https://evolu.dev/docs/api-reference/common/local-first/variables/OwnerId).
## Parameters
| Parameter | Type |
| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ownerIdBytes` | `Uint8Array`\<`ArrayBufferLike`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Length16"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"IdBytes"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"OwnerIdBytes"`\> |
## Returns
`string` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Id"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"OwnerId"`\>
ownerIdToOwnerIdBytes - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / ownerIdToOwnerIdBytes
# Function: ownerIdToOwnerIdBytes()
```ts
function ownerIdToOwnerIdBytes(
ownerId,
): Uint8Array<ArrayBufferLike> &
Brand<"Length16"> &
Brand<"IdBytes"> &
Brand<"OwnerIdBytes">;
```
Defined in: [packages/common/src/local-first/Owner.ts:80](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Owner.ts#L80)
Converts [OwnerId](https://evolu.dev/docs/api-reference/common/local-first/variables/OwnerId) to [OwnerIdBytes](https://evolu.dev/docs/api-reference/common/local-first/variables/OwnerIdBytes).
## Parameters
| Parameter | Type |
| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ownerId` | `string` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Id"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"OwnerId"`\> |
## Returns
`Uint8Array`\<`ArrayBufferLike`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Length16"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"IdBytes"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"OwnerIdBytes"`\>
ownerSecretToMnemonic - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / ownerSecretToMnemonic
# Function: ownerSecretToMnemonic()
```ts
function ownerSecretToMnemonic(
secret,
): string & Brand<"Trimmed"> & Brand<"MinLength1"> & Brand<"Mnemonic">;
```
Defined in: [packages/common/src/local-first/Owner.ts:124](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Owner.ts#L124)
Converts an [OwnerSecret](https://evolu.dev/docs/api-reference/common/local-first/variables/OwnerSecret) to a [Mnemonic](https://evolu.dev/docs/api-reference/common/Type/variables/Mnemonic).
## Parameters
| Parameter | Type |
| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `secret` | `Uint8Array`\<`ArrayBufferLike`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Entropy"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Length32"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"OwnerSecret"`\> |
## Returns
`string` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Trimmed"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"MinLength1"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Mnemonic"`\>
parseOwnerIdFromOwnerWebSocketTransportUrl - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / parseOwnerIdFromOwnerWebSocketTransportUrl
# Function: parseOwnerIdFromOwnerWebSocketTransportUrl()
```ts
function parseOwnerIdFromOwnerWebSocketTransportUrl(
url,
): (string & Brand<"Id"> & Brand<"OwnerId">) | null;
```
Defined in: [packages/common/src/local-first/Owner.ts:380](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Owner.ts#L380)
Extracts [OwnerId](https://evolu.dev/docs/api-reference/common/local-first/variables/OwnerId) from an [OwnerWebSocketTransport](https://evolu.dev/docs/api-reference/common/local-first/interfaces/OwnerWebSocketTransport) URL query
string.
Parses the query string `?ownerId=...` and validates that the extracted value
is a valid [OwnerId](https://evolu.dev/docs/api-reference/common/local-first/variables/OwnerId).
### Example
```ts
parseOwnerIdFromOwnerWebSocketTransportUrl("/sync?ownerId=_12345678abcdefgh");
// Returns: OwnerId or null
```
## Parameters
| Parameter | Type |
| --------- | -------- |
| `url` | `string` |
## Returns
\| `string` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Id"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"OwnerId"`\>
\| `null`
parseSqliteJsonArray - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / parseSqliteJsonArray
# Function: parseSqliteJsonArray()
```ts
function parseSqliteJsonArray<T>(arr): readonly T[];
```
Defined in: [packages/common/src/local-first/Query.ts:329](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Query.ts#L329)
## Type Parameters
| Type Parameter |
| -------------- |
| `T` |
## Parameters
| Parameter | Type |
| --------- | -------------- |
| `arr` | readonly `T`[] |
## Returns
readonly `T`[]
receiveTimestamp - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / receiveTimestamp
# Function: receiveTimestamp()
```ts
function receiveTimestamp(
deps,
): (
local,
remote,
) => Result<
Timestamp,
| TimestampDriftError
| TimestampCounterOverflowError
| TimestampTimeOutOfRangeError
>;
```
Defined in: [packages/common/src/local-first/Timestamp.ts:248](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Timestamp.ts#L248)
## Parameters
| Parameter | Type |
| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `deps` | [`TimeDep`](https://evolu.dev/docs/api-reference/common/Time/interfaces/TimeDep) & [`TimestampConfigDep`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/TimestampConfigDep) |
## Returns
```ts
(local, remote): Result<Timestamp,
| TimestampDriftError
| TimestampCounterOverflowError
| TimestampTimeOutOfRangeError>;
```
### Parameters
| Parameter | Type |
| --------- | ------------------------------------------------------------------------------ |
| `local` | [`Timestamp`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Timestamp) |
| `remote` | [`Timestamp`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Timestamp) |
### Returns
[`Result`](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result)\<[`Timestamp`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Timestamp),
\| [`TimestampDriftError`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/TimestampDriftError)
\| [`TimestampCounterOverflowError`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/TimestampCounterOverflowError)
\| [`TimestampTimeOutOfRangeError`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/TimestampTimeOutOfRangeError)\>
sendTimestamp - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / sendTimestamp
# Function: sendTimestamp()
```ts
function sendTimestamp(
deps,
): (
timestamp,
) => Result<
Timestamp,
| TimestampDriftError
| TimestampCounterOverflowError
| TimestampTimeOutOfRangeError
>;
```
Defined in: [packages/common/src/local-first/Timestamp.ts:222](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Timestamp.ts#L222)
## Parameters
| Parameter | Type |
| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `deps` | [`TimeDep`](https://evolu.dev/docs/api-reference/common/Time/interfaces/TimeDep) & [`TimestampConfigDep`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/TimestampConfigDep) |
## Returns
```ts
(timestamp): Result<Timestamp,
| TimestampDriftError
| TimestampCounterOverflowError
| TimestampTimeOutOfRangeError>;
```
### Parameters
| Parameter | Type |
| ----------- | ------------------------------------------------------------------------------ |
| `timestamp` | [`Timestamp`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Timestamp) |
### Returns
[`Result`](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result)\<[`Timestamp`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Timestamp),
\| [`TimestampDriftError`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/TimestampDriftError)
\| [`TimestampCounterOverflowError`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/TimestampCounterOverflowError)
\| [`TimestampTimeOutOfRangeError`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/TimestampTimeOutOfRangeError)\>
serializeQuery - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / serializeQuery
# Function: serializeQuery()
```ts
function serializeQuery<R>(query): Query<R>;
```
Defined in: [packages/common/src/local-first/Query.ts:59](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Query.ts#L59)
Evolu serializes [SqliteQuery](https://evolu.dev/docs/api-reference/common/Sqlite/interfaces/SqliteQuery) into a string to be easily used as a key
and for comparison.
## Type Parameters
| Type Parameter |
| -------------------------------------------------------------------------------- |
| `R` _extends_ [`Row`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Row) |
## Parameters
| Parameter | Type |
| --------- | ----------------------------------------------------------------------------- |
| `query` | [`SqliteQuery`](https://evolu.dev/docs/api-reference/common/Sqlite/interfaces/SqliteQuery) |
## Returns
[`Query`](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/Query)\<`R`\>
timestampBytesToFingerprint - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / timestampBytesToFingerprint
# Function: timestampBytesToFingerprint()
```ts
function timestampBytesToFingerprint(timestamp): Fingerprint;
```
Defined in: [packages/common/src/local-first/Storage.ts:1157](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Storage.ts#L1157)
## Parameters
| Parameter | Type |
| ----------- | -------------------------------------------------------------------------------------------------------------------------- |
| `timestamp` | `Uint8Array`\<`ArrayBufferLike`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"TimestampBytes"`\> |
## Returns
[`Fingerprint`](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/Fingerprint)
timestampBytesToTimestamp - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / timestampBytesToTimestamp
# Function: timestampBytesToTimestamp()
```ts
function timestampBytesToTimestamp(timestamp): Timestamp;
```
Defined in: [packages/common/src/local-first/Timestamp.ts:315](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Timestamp.ts#L315)
## Parameters
| Parameter | Type |
| ----------- | -------------------------------------------------------------------------------------------------------------------------- |
| `timestamp` | `Uint8Array`\<`ArrayBufferLike`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"TimestampBytes"`\> |
## Returns
[`Timestamp`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Timestamp)
timestampToDateIso - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / timestampToDateIso
# Function: timestampToDateIso()
```ts
function timestampToDateIso(timestamp): string & Brand<"DateIso">;
```
Defined in: [packages/common/src/local-first/Timestamp.ts:354](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Timestamp.ts#L354)
Convert a [Timestamp](https://evolu.dev/docs/api-reference/common/local-first/variables/Timestamp) to an ISO 8601 [DateIso](https://evolu.dev/docs/api-reference/common/Type/variables/DateIso) string.
The conversion uses the timestamp's `millis` (a [Millis](https://evolu.dev/docs/api-reference/common/local-first/variables/Millis) value) and
`Date.prototype.toISOString()` to produce a `DateIso`.
## Parameters
| Parameter | Type |
| ----------- | ------------------------------------------------------------------------------ |
| `timestamp` | [`Timestamp`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Timestamp) |
## Returns
`string` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"DateIso"`\>
timestampToTimestampBytes - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / timestampToTimestampBytes
# Function: timestampToTimestampBytes()
```ts
function timestampToTimestampBytes(
timestamp,
): Uint8Array<ArrayBufferLike> & Brand<"TimestampBytes">;
```
Defined in: [packages/common/src/local-first/Timestamp.ts:285](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Timestamp.ts#L285)
## Parameters
| Parameter | Type |
| ----------- | ------------------------------------------------------------------------------ |
| `timestamp` | [`Timestamp`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Timestamp) |
## Returns
`Uint8Array`\<`ArrayBufferLike`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"TimestampBytes"`\>
tryApplyQuarantinedMessages - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / tryApplyQuarantinedMessages
# Function: tryApplyQuarantinedMessages()
```ts
function tryApplyQuarantinedMessages(deps): () => Result<void, SqliteError>;
```
Defined in: [packages/common/src/local-first/Sync.ts:850](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Sync.ts#L850)
Attempts to apply quarantined messages that may now be valid after a schema
update. Messages are quarantined when they reference tables or columns that
don't exist in the current schema (e.g., from a newer app version).
## Parameters
| Parameter | Type |
| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `deps` | [`DbSchemaDep`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/DbSchemaDep) & [`SqliteDep`](https://evolu.dev/docs/api-reference/common/Sqlite/interfaces/SqliteDep) |
## Returns
```ts
(): Result<void, SqliteError>;
```
### Returns
[`Result`](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result)\<`void`, [`SqliteError`](https://evolu.dev/docs/api-reference/common/Sqlite/interfaces/SqliteError)\>
updateOwnerUsage - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / updateOwnerUsage
# Function: updateOwnerUsage()
```ts
function updateOwnerUsage(
deps,
): (
ownerIdBytes,
storedBytes,
firstTimestamp,
lastTimestamp,
) => Result<void, SqliteError>;
```
Defined in: [packages/common/src/local-first/Storage.ts:1688](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Storage.ts#L1688)
Updates timestamp bounds in evolu_usage table.
Used by both relay and client to maintain firstTimestamp/lastTimestamp after
processing messages.
## Parameters
| Parameter | Type |
| --------- | ------------------------------------------------------------------------- |
| `deps` | [`SqliteDep`](https://evolu.dev/docs/api-reference/common/Sqlite/interfaces/SqliteDep) |
## Returns
```ts
(
ownerIdBytes,
storedBytes,
firstTimestamp,
lastTimestamp): Result<void, SqliteError>;
```
### Parameters
| Parameter | Type |
| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ownerIdBytes` | `Uint8Array`\<`ArrayBufferLike`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Length16"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"IdBytes"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"OwnerIdBytes"`\> |
| `storedBytes` | `number` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Int"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"NonNegative"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Positive"`\> |
| `firstTimestamp` | `Uint8Array`\<`ArrayBufferLike`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"TimestampBytes"`\> |
| `lastTimestamp` | `Uint8Array`\<`ArrayBufferLike`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"TimestampBytes"`\> |
### Returns
[`Result`](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result)\<`void`, [`SqliteError`](https://evolu.dev/docs/api-reference/common/Sqlite/interfaces/SqliteError)\>
updateable - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / updateable
# Function: updateable()
```ts
function updateable<Props>(props): ValidMutationSize<UpdateableProps<Props>>;
```
Defined in: [packages/common/src/local-first/Schema.ts:383](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Schema.ts#L383)
Type Factory to create updateable [Type](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type). It makes everything except for
the `id` column optional (so they are not required) and ensures the
[maxMutationSize](https://evolu.dev/docs/api-reference/common/Type/variables/maxMutationSize).
### Example
```ts
const UpdateableTodo = updateable(Schema.todo);
type UpdateableTodo = typeof UpdateableTodo.Type;
// `id` is required; all other fields are optional.
const todoResult = UpdateableTodo.from({
id: "123",
title: "New Title",
});
if (!todo.ok) return; // handle errors
```
## Type Parameters
| Type Parameter |
| ------------------------------------------------------------------------------------------------------------- |
| `Props` _extends_ `Record`\<`string`, [`AnyType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/AnyType)\> |
## Parameters
| Parameter | Type |
| --------- | ------- |
| `props` | `Props` |
## Returns
[`ValidMutationSize`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/ValidMutationSize)\<[`UpdateableProps`](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/UpdateableProps)\<`Props`\>\>
upsertable - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / upsertable
# Function: upsertable()
```ts
function upsertable<Props>(
props,
): ValidMutationSize<NullableToOptionalProps<Props & object>>;
```
Defined in: [packages/common/src/local-first/Schema.ts:424](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Schema.ts#L424)
Type Factory to create an upsertable Type. It makes nullable Types optional
(so they are not required) and ensures the [maxMutationSize](https://evolu.dev/docs/api-reference/common/Type/variables/maxMutationSize).
Upsert is like insert, except it requires an ID. It's useful for inserting
rows with external ID via [createIdFromString](https://evolu.dev/docs/api-reference/common/Type/functions/createIdFromString).
Note that it's not possible to upsert a row with `createdAt` nor `updatedAt`,
because they are derived from [CrdtMessage](https://evolu.dev/docs/api-reference/common/local-first/interfaces/CrdtMessage) timestamp. For external
createdAt, use a different column.
### Example
```ts
const UpsertableTodo = upsertable(Schema.todo);
type UpsertableTodo = typeof UpsertableTodo.Type;
const todo = UpsertableTodo.from({
id,
title,
});
if (!todo.ok) return; // handle errors
```
## Type Parameters
| Type Parameter |
| ------------------------------------------------------------------------------------------------------------- |
| `Props` _extends_ `Record`\<`string`, [`AnyType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/AnyType)\> |
## Parameters
| Parameter | Type |
| --------- | ------- |
| `props` | `Props` |
## Returns
[`ValidMutationSize`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/ValidMutationSize)\<[`NullableToOptionalProps`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/NullableToOptionalProps)\<`Props` & `object`\>\>
AppOwner - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / AppOwner
# Interface: AppOwner
Defined in: [packages/common/src/local-first/Owner.ts:182](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Owner.ts#L182)
The AppOwner represents the application owner. It's created using a
cryptographically secure random generator or derived from an external source,
e.g., mnemonic stored securely in a hardware device.
While it's possible to store all application data in AppOwner, the better
approach is to use it only for sync coordination. Storing all app data in
AppOwner means that data will be stored/synced forever. And that's a problem
if we want to provide real data deletion or in-app data migration without
data duplication. In local-first apps/distributed systems, we can't delete
individual changes, we only mark them as deleted, otherwise sync could not
work.
If we really want to delete data or at least avoid syncing it, we must store
it using a different owner than AppOwner, e.g. [ShardOwner](https://evolu.dev/docs/api-reference/common/local-first/interfaces/ShardOwner) or
[SharedOwner](https://evolu.dev/docs/api-reference/common/local-first/interfaces/SharedOwner), and delete that owner. The AppOwner itself must be
preserved because it coordinates deletion information across devices. Other
devices need to sync the information that an owner was deleted so they can
delete their local data as well.
### Privacy Considerations
AppOwner must never be shared with anyone, except for its [OwnerId](https://evolu.dev/docs/api-reference/common/local-first/variables/OwnerId),
which can be used for authorization with
[createOwnerWebSocketTransport](https://evolu.dev/docs/api-reference/common/local-first/functions/createOwnerWebSocketTransport). It's safe because OwnerId is
pseudonymous (it can't be assigned to a specific person).
For data sharing scenarios, use [SharedOwner](https://evolu.dev/docs/api-reference/common/local-first/interfaces/SharedOwner) and
[SharedReadonlyOwner](https://evolu.dev/docs/api-reference/common/local-first/interfaces/SharedReadonlyOwner) instead, which are designed specifically for
collaborative access.
## Extends
- [`Owner`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Owner)
## Properties
| Property | Modifier | Type | Description | Inherited from | Defined in |
| ------------------------------------------ | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="encryptionkey"></a> `encryptionKey` | `readonly` | `Uint8Array`\<`ArrayBufferLike`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Entropy"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Length32"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"EncryptionKey"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"OwnerEncryptionKey"`\> | TODO: Wrap with `Redacted` in the next major version. | [`Owner`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Owner).[`encryptionKey`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Owner.mdx#encryptionkey) | [packages/common/src/local-first/Owner.ts:32](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Owner.ts#L32) |
| <a id="id"></a> `id` | `readonly` | `string` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Id"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"OwnerId"`\> | - | [`Owner`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Owner).[`id`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Owner.mdx#id) | [packages/common/src/local-first/Owner.ts:30](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Owner.ts#L30) |
| <a id="mnemonic"></a> `mnemonic?` | `readonly` | \| `string` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Trimmed"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"MinLength1"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Mnemonic"`\> \| `null` | The mnemonic that was used to derive the AppOwner keys. Optional when the AppOwner is created from external keys to avoid sharing the mnemonic with the Evolu app. TODO: Wrap with `Redacted` in the next major version. | - | [packages/common/src/local-first/Owner.ts:192](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Owner.ts#L192) |
| <a id="type"></a> `type` | `readonly` | `"AppOwner"` | - | - | [packages/common/src/local-first/Owner.ts:183](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Owner.ts#L183) |
| <a id="writekey"></a> `writeKey` | `readonly` | `Uint8Array`\<`ArrayBufferLike`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Entropy"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Length16"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"OwnerWriteKey"`\> | TODO: Wrap with `Redacted` in the next major version. | [`Owner`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Owner).[`writeKey`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Owner.mdx#writekey) | [packages/common/src/local-first/Owner.ts:68](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Owner.ts#L68) |
AppOwnerDep - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / AppOwnerDep
# Interface: AppOwnerDep
Defined in: [packages/common/src/local-first/Owner.ts:195](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Owner.ts#L195)
## Properties
| Property | Modifier | Type | Defined in |
| -------------------------------- | ---------- | ---------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="appowner"></a> `appOwner` | `readonly` | [`AppOwner`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/AppOwner) | [packages/common/src/local-first/Owner.ts:196](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Owner.ts#L196) |
BaseRange - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / BaseRange
# Interface: BaseRange
Defined in: [packages/common/src/local-first/Storage.ts:198](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Storage.ts#L198)
## Extended by
- [`TimestampsRangeWithTimestampsBuffer`](https://evolu.dev/docs/api-reference/common/local-first/Protocol/interfaces/TimestampsRangeWithTimestampsBuffer)
- [`SkipRange`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/SkipRange)
- [`FingerprintRange`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/FingerprintRange)
- [`TimestampsRange`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/TimestampsRange)
## Properties
| Property | Modifier | Type | Defined in |
| ------------------------------------ | ---------- | -------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="upperbound"></a> `upperBound` | `readonly` | [`RangeUpperBound`](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/RangeUpperBound) | [packages/common/src/local-first/Storage.ts:199](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Storage.ts#L199) |
BaseSqliteStorage - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / BaseSqliteStorage
# Interface: BaseSqliteStorage
Defined in: [packages/common/src/local-first/Storage.ts:326](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Storage.ts#L326)
Common interface for both client and relay SQLite storages.
Evolu uses a Skiplist, which leverages SQLite indexes. The core logic is
implemented in SQL, so it doesn't have to make roundtrips to the DB.
While the SQL implementation may look sophisticated, it's conceptually simple
and LLMs can explain how it works. The Skiplist data structure is well
explained in [this Stack Overflow
answer](https://stackoverflow.com/questions/61944198/what-is-a-zip-tree-and-how-does-it-work).
The logic resembles [Negentropy's C++
storage](https://github.com/hoytech/negentropy), except we use a Skiplist to
leverage SQLite indexes, which makes the code simpler.
Note: A paid review by the SQLite team is planned, as they use the same
algorithm for their rsync tool.
The ideal storage for a Relay should use an architecture like
[strfry](https://github.com/hoytech/strfry) (a KV storage), but with Skiplist
to ensure that insertion order doesn't matter (local-first apps can often
write in the past.)
The ideal client implementation should probably use the SQLite extension
instead of SQL or even a KV storage, when such a thing for browsers/native
will exist and will be faster than SQLite.
# Scaling
The load can be distributed by deploying multiple relays, synchronized with
each other, if necessary. One relay should handle hundreds of thousands of
users, and when it goes down, nothing happens, because it will be
synchronized later.
## Extends
- `Pick`\<[`Storage`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Storage),
\| `"getSize"`
\| `"fingerprint"`
\| `"fingerprintRanges"`
\| `"findLowerBound"`
\| `"iterate"`
\| `"deleteOwner"`\>
## Extended by
- [`ClientStorage`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/ClientStorage)
## Properties
| Property | Modifier | Type | Description | Inherited from | Defined in |
| ---------------------------------------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="deleteowner"></a> `deleteOwner` | `readonly` | (`ownerId`) => `boolean` | Delete all data for the given [Owner](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Owner). Returns `true` on success, `false` on failure. | [`Storage`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Storage).[`deleteOwner`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Storage.mdx#deleteowner) | [packages/common/src/local-first/Storage.ts:167](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Storage.ts#L167) |
| <a id="findlowerbound"></a> `findLowerBound` | `readonly` | (`ownerId`, `begin`, `end`, `upperBound`) => \| `number` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Int"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"NonNegative"`\> \| `null` | - | [`Storage`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Storage).[`findLowerBound`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Storage.mdx#findlowerbound) | [packages/common/src/local-first/Storage.ts:113](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Storage.ts#L113) |
| <a id="fingerprint"></a> `fingerprint` | `readonly` | (`ownerId`, `begin`, `end`) => \| [`Fingerprint`](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/Fingerprint) \| `null` | - | [`Storage`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Storage).[`fingerprint`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Storage.mdx#fingerprint) | [packages/common/src/local-first/Storage.ts:94](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Storage.ts#L94) |
| <a id="fingerprintranges"></a> `fingerprintRanges` | `readonly` | (`ownerId`, `buckets`, `upperBound?`) => \| readonly [`FingerprintRange`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/FingerprintRange)[] \| `null` | Computes fingerprints with their upper bounds in one call. This function can be replaced with many fingerprint/findLowerBound calls, but implementations can leverage it for batching and more efficient fingerprint computation. | [`Storage`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Storage).[`fingerprintRanges`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Storage.mdx#fingerprintranges) | [packages/common/src/local-first/Storage.ts:107](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Storage.ts#L107) |
| <a id="getexistingtimestamps"></a> `getExistingTimestamps` | `readonly` | (`ownerIdBytes`, `timestampsBytes`) => [`Result`](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result)\<readonly `Uint8Array`\<`ArrayBufferLike`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"TimestampBytes"`\>[], [`SqliteError`](https://evolu.dev/docs/api-reference/common/Sqlite/interfaces/SqliteError)\> | Efficiently checks which timestamps already exist in the database using a single CTE query instead of N individual queries. | - | [packages/common/src/local-first/Storage.ts:346](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Storage.ts#L346) |
| <a id="getsize"></a> `getSize` | `readonly` | (`ownerId`) => \| `number` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Int"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"NonNegative"`\> \| `null` | - | [`Storage`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Storage).[`getSize`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Storage.mdx#getsize) | [packages/common/src/local-first/Storage.ts:92](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Storage.ts#L92) |
| <a id="inserttimestamp"></a> `insertTimestamp` | `readonly` | (`ownerId`, `timestamp`, `strategy`) => [`Result`](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result)\<`void`, [`SqliteError`](https://evolu.dev/docs/api-reference/common/Sqlite/interfaces/SqliteError)\> | Inserts a timestamp for an owner into the skiplist-based storage. | - | [packages/common/src/local-first/Storage.ts:336](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Storage.ts#L336) |
| <a id="iterate"></a> `iterate` | `readonly` | (`ownerId`, `begin`, `end`, `callback`) => `void` | - | [`Storage`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Storage).[`iterate`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Storage.mdx#iterate) | [packages/common/src/local-first/Storage.ts:120](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Storage.ts#L120) |
BaseSqliteStorageDep - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / BaseSqliteStorageDep
# Interface: BaseSqliteStorageDep
Defined in: [packages/common/src/local-first/Storage.ts:352](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Storage.ts#L352)
## Properties
| Property | Modifier | Type | Defined in |
| ------------------------------ | ---------- | ---------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="storage"></a> `storage` | `readonly` | [`BaseSqliteStorage`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/BaseSqliteStorage) | [packages/common/src/local-first/Storage.ts:353](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Storage.ts#L353) |
ClientStorage - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / ClientStorage
# Interface: ClientStorage
Defined in: [packages/common/src/local-first/Sync.ts:440](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Sync.ts#L440)
Evolu Storage
Evolu protocol using Storage is agnostic to storage implementation
details—any storage can be plugged in, as long as it implements this
interface. Implementations must handle their own errors; return values only
indicate overall success or failure.
The Storage API is synchronous because SQLite's synchronous API is the
fastest way to use SQLite. Synchronous bindings (like better-sqlite3) call
SQLite's C API directly with no context switching between the event loop and
native code, and no promise microtasks or await overhead.
The only exception is [Storage#writeMessages](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Storage.mdx#writemessages), which is async to allow
for async validation logic before writing to storage. The write operation
itself remains synchronous.
## Extends
- [`Storage`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Storage).[`BaseSqliteStorage`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/BaseSqliteStorage)
## Properties
| Property | Modifier | Type | Description | Inherited from | Defined in |
| ---------------------------------------------------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="deleteowner"></a> `deleteOwner` | `readonly` | (`ownerId`) => `boolean` | Delete all data for the given [Owner](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Owner). Returns `true` on success, `false` on failure. | [`Storage`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Storage).[`deleteOwner`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Storage.mdx#deleteowner) | [packages/common/src/local-first/Storage.ts:167](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Storage.ts#L167) |
| <a id="findlowerbound"></a> `findLowerBound` | `readonly` | (`ownerId`, `begin`, `end`, `upperBound`) => \| `number` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Int"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"NonNegative"`\> \| `null` | - | [`Storage`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Storage).[`findLowerBound`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Storage.mdx#findlowerbound) | [packages/common/src/local-first/Storage.ts:113](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Storage.ts#L113) |
| <a id="fingerprint"></a> `fingerprint` | `readonly` | (`ownerId`, `begin`, `end`) => \| [`Fingerprint`](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/Fingerprint) \| `null` | - | [`Storage`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Storage).[`fingerprint`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Storage.mdx#fingerprint) | [packages/common/src/local-first/Storage.ts:94](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Storage.ts#L94) |
| <a id="fingerprintranges"></a> `fingerprintRanges` | `readonly` | (`ownerId`, `buckets`, `upperBound?`) => \| readonly [`FingerprintRange`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/FingerprintRange)[] \| `null` | Computes fingerprints with their upper bounds in one call. This function can be replaced with many fingerprint/findLowerBound calls, but implementations can leverage it for batching and more efficient fingerprint computation. | [`Storage`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Storage).[`fingerprintRanges`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Storage.mdx#fingerprintranges) | [packages/common/src/local-first/Storage.ts:107](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Storage.ts#L107) |
| <a id="getexistingtimestamps"></a> `getExistingTimestamps` | `readonly` | (`ownerIdBytes`, `timestampsBytes`) => [`Result`](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result)\<readonly `Uint8Array`\<`ArrayBufferLike`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"TimestampBytes"`\>[], [`SqliteError`](https://evolu.dev/docs/api-reference/common/Sqlite/interfaces/SqliteError)\> | Efficiently checks which timestamps already exist in the database using a single CTE query instead of N individual queries. | [`BaseSqliteStorage`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/BaseSqliteStorage).[`getExistingTimestamps`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/BaseSqliteStorage.mdx#getexistingtimestamps) | [packages/common/src/local-first/Storage.ts:346](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Storage.ts#L346) |
| <a id="getsize"></a> `getSize` | `readonly` | (`ownerId`) => \| `number` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Int"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"NonNegative"`\> \| `null` | - | [`Storage`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Storage).[`getSize`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Storage.mdx#getsize) | [packages/common/src/local-first/Storage.ts:92](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Storage.ts#L92) |
| <a id="inserttimestamp"></a> `insertTimestamp` | `readonly` | (`ownerId`, `timestamp`, `strategy`) => [`Result`](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result)\<`void`, [`SqliteError`](https://evolu.dev/docs/api-reference/common/Sqlite/interfaces/SqliteError)\> | Inserts a timestamp for an owner into the skiplist-based storage. | [`BaseSqliteStorage`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/BaseSqliteStorage).[`insertTimestamp`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/BaseSqliteStorage.mdx#inserttimestamp) | [packages/common/src/local-first/Storage.ts:336](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Storage.ts#L336) |
| <a id="iterate"></a> `iterate` | `readonly` | (`ownerId`, `begin`, `end`, `callback`) => `void` | - | [`Storage`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Storage).[`iterate`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Storage.mdx#iterate) | [packages/common/src/local-first/Storage.ts:120](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Storage.ts#L120) |
| <a id="readdbchange"></a> `readDbChange` | `readonly` | (`ownerId`, `timestamp`) => \| [`EncryptedDbChange`](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/EncryptedDbChange) \| `null` | Read encrypted [DbChange](https://evolu.dev/docs/api-reference/common/local-first/variables/DbChange)s from storage. | [`Storage`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Storage).[`readDbChange`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Storage.mdx#readdbchange) | [packages/common/src/local-first/Storage.ts:157](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Storage.ts#L157) |
| <a id="setwritekey"></a> `setWriteKey` | `readonly` | (`ownerId`, `writeKey`) => `boolean` | Sets the [OwnerWriteKey](https://evolu.dev/docs/api-reference/common/local-first/variables/OwnerWriteKey) for the given [Owner](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Owner). | [`Storage`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Storage).[`setWriteKey`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Storage.mdx#setwritekey) | [packages/common/src/local-first/Storage.ts:138](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Storage.ts#L138) |
| <a id="validatewritekey"></a> `validateWriteKey` | `readonly` | (`ownerId`, `writeKey`) => `boolean` | Validates the [OwnerWriteKey](https://evolu.dev/docs/api-reference/common/local-first/variables/OwnerWriteKey) for the given [Owner](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Owner). Returns `true` if the write key is valid, `false` otherwise. | [`Storage`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Storage).[`validateWriteKey`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Storage.mdx#validatewritekey) | [packages/common/src/local-first/Storage.ts:132](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Storage.ts#L132) |
| <a id="writemessages"></a> `writeMessages` | `readonly` | (`ownerIdBytes`, `messages`) => [`MaybeAsync`](https://evolu.dev/docs/api-reference/common/Task/type-aliases/MaybeAsync)\<[`Result`](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result)\<`void`, \| [`StorageWriteError`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/StorageWriteError) \| [`StorageQuotaError`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/StorageQuotaError)\>\> | Write encrypted [CrdtMessage](https://evolu.dev/docs/api-reference/common/local-first/interfaces/CrdtMessage)s to storage. Must use a mutex per ownerId to ensure sequential processing and proper protocol logic handling during sync operations. TODO: Use MaybeAsync | [`Storage`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Storage).[`writeMessages`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Storage.mdx#writemessages) | [packages/common/src/local-first/Storage.ts:151](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Storage.ts#L151) |
ClientStorageDep - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / ClientStorageDep
# Interface: ClientStorageDep
Defined in: [packages/common/src/local-first/Sync.ts:442](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Sync.ts#L442)
## Properties
| Property | Modifier | Type | Defined in |
| ------------------------------ | ---------- | -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="storage"></a> `storage` | `readonly` | [`ClientStorage`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/ClientStorage) | [packages/common/src/local-first/Sync.ts:443](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Sync.ts#L443) |
Clock - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / Clock
# Interface: Clock
Defined in: [packages/common/src/local-first/Sync.ts:410](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Sync.ts#L410)
## Properties
| Property | Modifier | Type | Defined in |
| ------------------------ | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="get"></a> `get` | `readonly` | () => [`Timestamp`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Timestamp) | [packages/common/src/local-first/Sync.ts:411](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Sync.ts#L411) |
| <a id="save"></a> `save` | `readonly` | (`timestamp`) => [`Result`](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result)\<`void`, [`SqliteError`](https://evolu.dev/docs/api-reference/common/Sqlite/interfaces/SqliteError)\> | [packages/common/src/local-first/Sync.ts:412](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Sync.ts#L412) |
ClockDep - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / ClockDep
# Interface: ClockDep
Defined in: [packages/common/src/local-first/Sync.ts:406](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Sync.ts#L406)
## Properties
| Property | Modifier | Type | Defined in |
| -------------------------- | ---------- | ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="clock"></a> `clock` | `readonly` | [`Clock`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Clock) | [packages/common/src/local-first/Sync.ts:407](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Sync.ts#L407) |
CrdtMessage - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / CrdtMessage
# Interface: CrdtMessage
Defined in: [packages/common/src/local-first/Storage.ts:251](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Storage.ts#L251)
A CRDT message combining a unique [Timestamp](https://evolu.dev/docs/api-reference/common/local-first/variables/Timestamp) with a [DbChange](https://evolu.dev/docs/api-reference/common/local-first/variables/DbChange).
Used in Evolu's sync protocol to replicate data changes across devices. Evolu
operates as a durable queue, providing exactly-once delivery guarantees for
reliable synchronization across application restarts and network failures.
## Properties
| Property | Modifier | Type | Defined in |
| ---------------------------------- | ---------- | ------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="change"></a> `change` | `readonly` | [`DbChange`](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/DbChange) | [packages/common/src/local-first/Storage.ts:253](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Storage.ts#L253) |
| <a id="timestamp"></a> `timestamp` | `readonly` | [`Timestamp`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Timestamp) | [packages/common/src/local-first/Storage.ts:252](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Storage.ts#L252) |
CreateBaseSqliteStorageConfig - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / CreateBaseSqliteStorageConfig
# Interface: CreateBaseSqliteStorageConfig
Defined in: [packages/common/src/local-first/Storage.ts:358](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Storage.ts#L358)
## Extends
- [`StorageConfig`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/StorageConfig)
## Properties
| Property | Modifier | Type | Description | Inherited from | Defined in |
| ---------------------------------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="isownerwithinquota"></a> `isOwnerWithinQuota` | `readonly` | (`ownerId`, `requiredBytes`) => [`MaybeAsync`](https://evolu.dev/docs/api-reference/common/Task/type-aliases/MaybeAsync)\<`boolean`\> | Callback called before an attempt to write, to check if an [OwnerId](https://evolu.dev/docs/api-reference/common/local-first/variables/OwnerId) has sufficient quota for the write. The callback receives the [OwnerId](https://evolu.dev/docs/api-reference/common/local-first/variables/OwnerId) and the total bytes that would be stored after the write (current stored bytes plus incoming bytes), and returns a [MaybeAsync](https://evolu.dev/docs/api-reference/common/Task/type-aliases/MaybeAsync) boolean: `true` to allow the write, or `false` to deny it due to quota limits. The callback can be synchronous (for SQLite or in-memory checks) or asynchronous (for calling remote APIs). The callback returns a boolean rather than an error because error handling and logging are the responsibility of the callback implementation. ### Example `// Client // evolu.subscribeError // Relay isOwnerWithinQuota: (ownerId, requiredBytes) => { console.log(ownerId, requiredBytes); // Check error via evolu.subscribeError return true; };` | [`StorageConfig`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/StorageConfig).[`isOwnerWithinQuota`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/StorageConfig.mdx#isownerwithinquota) | [packages/common/src/local-first/Storage.ts:68](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Storage.ts#L68) |
| <a id="onstorageerror"></a> `onStorageError` | `public` | (`error`) => `void` | - | - | [packages/common/src/local-first/Storage.ts:359](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Storage.ts#L359) |
CreateDbWorkerDep - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / CreateDbWorkerDep
# Interface: CreateDbWorkerDep
Defined in: [packages/common/src/local-first/Db.ts:225](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Db.ts#L225)
## Properties
| Property | Modifier | Type | Defined in |
| -------------------------------------------- | ---------- | ------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="createdbworker"></a> `createDbWorker` | `readonly` | [`CreateDbWorker`](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/CreateDbWorker) | [packages/common/src/local-first/Db.ts:226](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Db.ts#L226) |
DbConfig - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / DbConfig
# Interface: DbConfig
Defined in: [packages/common/src/local-first/Db.ts:78](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Db.ts#L78)
## Extends
- [`ConsoleConfig`](https://evolu.dev/docs/api-reference/common/Console/interfaces/ConsoleConfig).[`TimestampConfig`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/TimestampConfig)
## Properties
| Property | Modifier | Type | Description | Inherited from | Defined in |
| ------------------------------------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="enablelogging"></a> `enableLogging?` | `readonly` | `boolean` | Enable or disable console logging (default: false). When true, logs are output to the [Console](https://evolu.dev/docs/api-reference/common/Console/interfaces/Console); when false, logging is disabled for all methods except `error`, which always outputs to ensure critical issues are not missed. | [`ConsoleConfig`](https://evolu.dev/docs/api-reference/common/Console/interfaces/ConsoleConfig).[`enableLogging`](https://evolu.dev/docs/api-reference/common/Console/interfaces/ConsoleConfig.mdx#enablelogging) | [packages/common/src/Console.ts:96](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Console.ts#L96) |
| <a id="encryptionkey"></a> `encryptionKey?` | `readonly` | `Uint8Array`\<`ArrayBufferLike`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Entropy"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Length32"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"EncryptionKey"`\> | **`Experimental`** Encryption key for the SQLite database. Note: If an unencrypted SQLite database already exists and you provide an encryptionKey, SQLite will throw an error. | - | [packages/common/src/local-first/Db.ts:211](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Db.ts#L211) |
| <a id="externalappowner"></a> `externalAppOwner?` | `readonly` | [`AppOwner`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/AppOwner) | External AppOwner to use when creating Evolu instance. Use this when you want to manage AppOwner creation and persistence externally (e.g., with your own authentication system). If omitted, Evolu will automatically create and persist an AppOwner locally. For device-specific settings and account management state, we can use a separate local-only Evolu instance via `transports: []`. ### Example `const ConfigId = id("Config"); type ConfigId = typeof ConfigId.Type; const DeviceSchema = { config: { id: ConfigId, key: NonEmptyString50, value: NonEmptyString50, }, }; // Local-only instance for device settings (no sync) const deviceEvolu = createEvolu(evoluReactWebDeps)(DeviceSchema, { name: SimpleName.orThrow("MyApp-Device"), transports: [], // No sync - stays local to device }); // Main synced instance for user data const evolu = createEvolu(evoluReactWebDeps)(MainSchema, { name: SimpleName.orThrow("MyApp"), // Default transports for sync });` | - | [packages/common/src/local-first/Db.ts:190](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Db.ts#L190) |
| <a id="inmemory"></a> `inMemory?` | `readonly` | `boolean` | Use in-memory SQLite database instead of persistent storage. Useful for testing or temporary data that doesn't need persistence. In-memory databases exist only in RAM and are completely destroyed when the process ends, making them forensically safe for sensitive data. The default value is: `false`. | - | [packages/common/src/local-first/Db.ts:201](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Db.ts#L201) |
| <a id="maxdrift"></a> `maxDrift` | `readonly` | `number` | Maximum physical clock drift allowed in ms. The default value is 5 _ 60 _ 1000 (5 minutes). | [`TimestampConfig`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/TimestampConfig).[`maxDrift`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/TimestampConfig.mdx#maxdrift) | [packages/common/src/local-first/Timestamp.ts:26](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Timestamp.ts#L26) |
| <a id="name"></a> `name` | `readonly` | `string` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"UrlSafeString"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"SimpleName"`\> | The name of the Evolu instance. Evolu is multitenant - it can run multiple instances concurrently. Each instance must have a unique name. The instance name is used as the SQLite database filename for persistent storage, ensuring that database files are separated and invisible to each other. The default value is: `Evolu`. ### Example `// name: SimpleName.orThrow("MyApp")` | - | [packages/common/src/local-first/Db.ts:95](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Db.ts#L95) |
| <a id="transports"></a> `transports` | `readonly` | readonly [`OwnerWebSocketTransport`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/OwnerWebSocketTransport)[] | Transport configuration for data sync and backup. Supports single transport or multiple transports simultaneously for redundancy. **Redundancy:** The ideal setup uses at least two completely independent relays - for example, a home relay and a geographically separate relay. Data is sent to both relays simultaneously, providing true redundancy similar to using two independent clouds. This eliminates vendor lock-in and ensures your app continues working regardless of circumstances - whether home relay hardware is stolen or a remote relay provider shuts down. Currently supports: - WebSocket: Real-time bidirectional communication with relay servers Empty transports create local-only instances. Transports can be dynamically added and removed for any owner (including [AppOwner](https://evolu.dev/docs/api-reference/common/local-first/interfaces/AppOwner)) via [Evolu#useOwner](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Evolu.mdx#useowner). Use [createOwnerWebSocketTransport](https://evolu.dev/docs/api-reference/common/local-first/functions/createOwnerWebSocketTransport) to create WebSocket transport configurations with proper URL formatting and [OwnerId](https://evolu.dev/docs/api-reference/common/local-first/variables/OwnerId) inclusion. The [OwnerId](https://evolu.dev/docs/api-reference/common/local-first/variables/OwnerId) in the URL enables relay authentication, allowing relay servers to control access (e.g., for paid tiers or private instances). The default value is: `{ type: "WebSocket", url: "wss://free.evoluhq.com" }`. ### Example `// Single WebSocket relay transports: [{ type: "WebSocket", url: "wss://relay1.example.com" }]; // Multiple WebSocket relays for redundancy transports: [ { type: "WebSocket", url: "wss://relay1.example.com" }, { type: "WebSocket", url: "wss://relay2.example.com" }, { type: "WebSocket", url: "wss://relay3.example.com" }, ]; // Local-only instance (no sync) - useful for device settings or when relay // URL will be provided later (e.g., after authentication), allowing users // to work offline before the app connects transports: []; // Using createOwnerWebSocketTransport helper for relay authentication transports: [ createOwnerWebSocketTransport({ url: "ws://localhost:4000", ownerId, }), ];` | - | [packages/common/src/local-first/Db.ts:152](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Db.ts#L152) |
DbSchemaDep - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / DbSchemaDep
# Interface: DbSchemaDep
Defined in: [packages/common/src/local-first/Schema.ts:474](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Schema.ts#L474)
## Properties
| Property | Modifier | Type | Defined in |
| -------------------------------- | ---------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| <a id="dbschema"></a> `dbSchema` | `readonly` | [`DbSchema`](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/DbSchema) | [packages/common/src/local-first/Schema.ts:475](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Schema.ts#L475) |
EncryptedCrdtMessage - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / EncryptedCrdtMessage
# Interface: EncryptedCrdtMessage
Defined in: [packages/common/src/local-first/Storage.ts:236](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Storage.ts#L236)
An encrypted [CrdtMessage](https://evolu.dev/docs/api-reference/common/local-first/interfaces/CrdtMessage).
## Properties
| Property | Modifier | Type | Defined in |
| ---------------------------------- | ---------- | ------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="change"></a> `change` | `readonly` | [`EncryptedDbChange`](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/EncryptedDbChange) | [packages/common/src/local-first/Storage.ts:238](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Storage.ts#L238) |
| <a id="timestamp"></a> `timestamp` | `readonly` | [`Timestamp`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Timestamp) | [packages/common/src/local-first/Storage.ts:237](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Storage.ts#L237) |
Evolu - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / Evolu
# Interface: Evolu\<S\>
Defined in: [packages/common/src/local-first/Evolu.ts:111](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Evolu.ts#L111)
## Extends
- `Disposable`
## Type Parameters
| Type Parameter | Default type |
| -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| `S` _extends_ [`EvoluSchema`](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/EvoluSchema) | [`EvoluSchema`](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/EvoluSchema) |
## Properties
| Property | Modifier | Type | Description | Defined in |
| ---------------------------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="appowner"></a> `appOwner` | `readonly` | `Promise`\<[`AppOwner`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/AppOwner)\> | Promise that resolves to [AppOwner](https://evolu.dev/docs/api-reference/common/local-first/interfaces/AppOwner) when available. Note: With web-only deps, this promise will not resolve during SSR because there is no AppOwner on the server. ### Example `const owner = await evolu.appOwner;` | [packages/common/src/local-first/Evolu.ts:236](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Evolu.ts#L236) |
| <a id="createquery"></a> `createQuery` | `readonly` | [`CreateQuery`](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/CreateQuery)\<`S`\> | Create type-safe SQL [Query](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/Query). Evolu uses Kysely - the type-safe SQL query builder for TypeScript. See https://kysely.dev. All this function does is compile the Kysely query and serialize it into a unique string. Both operations are fast and cheap. For mutations, use [Evolu#insert](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Evolu.mdx#insert), [Evolu#update](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Evolu.mdx#update), or [Evolu#upsert](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Evolu.mdx#upsert). ### Example `const allTodos = evolu.createQuery((db) => db.selectFrom("todo").selectAll(), ); const todoById = (id: TodoId) => evolu.createQuery((db) => db.selectFrom("todo").selectAll().where("id", "=", id), );` | [packages/common/src/local-first/Evolu.ts:154](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Evolu.ts#L154) |
| <a id="exportdatabase"></a> `exportDatabase` | `readonly` | () => `Promise`\<`Uint8Array`\<`ArrayBuffer`\>\> | Export SQLite database file as Uint8Array. In the future, it will be possible to import a database and export/import history for 1:1 migrations across owners. | [packages/common/src/local-first/Evolu.ts:427](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Evolu.ts#L427) |
| <a id="geterror"></a> `getError` | `readonly` | () => \| [`EvoluError`](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/EvoluError) \| `null` | Get [EvoluError](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/EvoluError). | [packages/common/src/local-first/Evolu.ts:127](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Evolu.ts#L127) |
| <a id="getqueryrows"></a> `getQueryRows` | `readonly` | \<`R`\>(`query`) => [`QueryRows`](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/QueryRows)\<`R`\> | Get [QueryRows](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/QueryRows). ### Example `const unsubscribe = evolu.subscribeQuery(allTodos)(() => { const rows = evolu.getQueryRows(allTodos); });` | [packages/common/src/local-first/Evolu.ts:222](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Evolu.ts#L222) |
| <a id="insert"></a> `insert` | `public` | [`Mutation`](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/Mutation)\<`S`, `"insert"`\> | Inserts a row into the database and returns a [Result](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result) with the new [Id](https://evolu.dev/docs/api-reference/common/Type/variables/Id). The first argument is the table name, and the second is an object containing the row data. An optional third argument provides mutation options including an `onComplete` callback and `onlyValidate` flag. Returns a Result type - use `.ok` to check if the insertion succeeded, and `.value.id` to access the generated ID on success, or `.error` to handle validation errors. Evolu does not use SQL for mutations to ensure data can be safely and predictably merged without conflicts. Explicit mutations also allow Evolu to automatically update [SystemColumns](https://evolu.dev/docs/api-reference/common/local-first/variables/SystemColumns-1). ### Example `const result = evolu.insert("todo", { title: "Learn Evolu", isCompleted: false, }); if (result.ok) { console.log("Todo created with ID:", result.value.id); } else { console.error("Validation error:", result.error); } // With onComplete callback evolu.insert( "todo", { title: "Another todo" }, { onComplete: () => { console.log("Insert completed"); }, }, );` | [packages/common/src/local-first/Evolu.ts:280](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Evolu.ts#L280) |
| <a id="loadqueries"></a> `loadQueries` | `readonly` | \<`R`, `Q`\>(`queries`) => \[`...QueriesToQueryRowsPromises<Q>[]`\] | Load an array of [Query](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/Query) queries and return an array of [QueryRows](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/QueryRows) promises. It's like `queries.map(loadQuery)` but with proper types for returned promises. ### Example `evolu.loadQueries([allTodos, todoById(1)]);` | [packages/common/src/local-first/Evolu.ts:194](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Evolu.ts#L194) |
| <a id="loadquery"></a> `loadQuery` | `readonly` | \<`R`\>(`query`) => `Promise`\<[`QueryRows`](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/QueryRows)\<`R`\>\> | Load [Query](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/Query) and return a promise with [QueryRows](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/QueryRows). The returned promise always resolves successfully because there is no reason why loading should fail. All data are local, and the query is typed. Unexpected errors are handled with [Evolu#subscribeError](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Evolu.mdx#subscribeerror). Loading is batched, and returned promises are cached until resolved to prevent redundant database queries and to support React Suspense (which requires stable promise references while pending). To subscribe a query for automatic updates, use [Evolu#subscribeQuery](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Evolu.mdx#subscribequery). ### Example `const allTodos = evolu.createQuery((db) => db.selectFrom("todo").selectAll(), ); evolu.loadQuery(allTodos).then((rows) => { console.log(rows); });` | [packages/common/src/local-first/Evolu.ts:181](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Evolu.ts#L181) |
| <a id="reloadapp"></a> `reloadApp` | `readonly` | () => `void` | Reload the app in a platform-specific way. For browsers, this will reload all tabs using Evolu. For native apps, it will restart the app. | [packages/common/src/local-first/Evolu.ts:419](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Evolu.ts#L419) |
| <a id="resetappowner"></a> `resetAppOwner` | `readonly` | (`options?`) => `Promise`\<`void`\> | Delete [AppOwner](https://evolu.dev/docs/api-reference/common/local-first/interfaces/AppOwner) and all their data from the current device. After the deletion, Evolu will purge the application state. For browsers, this will reload all tabs using Evolu. For native apps, it will restart the app. Reloading can be turned off via options if you want to provide a different UX. | [packages/common/src/local-first/Evolu.ts:400](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Evolu.ts#L400) |
| <a id="restoreappowner"></a> `restoreAppOwner` | `readonly` | (`mnemonic`, `options?`) => `Promise`\<`void`\> | Restore [AppOwner](https://evolu.dev/docs/api-reference/common/local-first/interfaces/AppOwner) with all their synced data. It uses [Evolu#resetAppOwner](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Evolu.mdx#resetappowner), so be careful. | [packages/common/src/local-first/Evolu.ts:408](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Evolu.ts#L408) |
| <a id="subscribeerror"></a> `subscribeError` | `readonly` | [`StoreSubscribe`](https://evolu.dev/docs/api-reference/common/Store/type-aliases/StoreSubscribe) | Subscribe to [EvoluError](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/EvoluError) changes. ### Example `const unsubscribe = evolu.subscribeError(() => { const error = evolu.getError(); console.log(error); });` | [packages/common/src/local-first/Evolu.ts:124](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Evolu.ts#L124) |
| <a id="subscribequery"></a> `subscribeQuery` | `readonly` | (`query`) => [`StoreSubscribe`](https://evolu.dev/docs/api-reference/common/Store/type-aliases/StoreSubscribe) | Subscribe to [Query](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/Query) [QueryRows](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/QueryRows) changes. ### Example `const unsubscribe = evolu.subscribeQuery(allTodos)(() => { const rows = evolu.getQueryRows(allTodos); });` | [packages/common/src/local-first/Evolu.ts:209](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Evolu.ts#L209) |
| <a id="update"></a> `update` | `public` | [`Mutation`](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/Mutation)\<`S`, `"update"`\> | Updates a row in the database and returns a [Result](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result) with the existing [Id](https://evolu.dev/docs/api-reference/common/Type/variables/Id). The first argument is the table name, and the second is an object containing the row data including the required `id` field. An optional third argument provides mutation options including an `onComplete` callback and `onlyValidate` flag. Returns a Result type - use `.ok` to check if the update succeeded, and `.value.id` to access the ID on success, or `.error` to handle validation errors. Evolu does not use SQL for mutations to ensure data can be safely and predictably merged without conflicts. Explicit mutations also allow Evolu to automatically update [SystemColumns](https://evolu.dev/docs/api-reference/common/local-first/variables/SystemColumns-1). ### Example `const result = evolu.update("todo", { id: todoId, title: "Updated title", isCompleted: true, }); if (result.ok) { console.log("Todo updated with ID:", result.value.id); } else { console.error("Validation error:", result.error); } // To delete a row, set isDeleted to true evolu.update("todo", { id: todoId, isDeleted: true }); // With onComplete callback evolu.update( "todo", { id: todoId, title: "New title" }, { onComplete: () => { console.log("Update completed"); }, }, );` | [packages/common/src/local-first/Evolu.ts:329](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Evolu.ts#L329) |
| <a id="upsert"></a> `upsert` | `public` | [`Mutation`](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/Mutation)\<`S`, `"upsert"`\> | Upserts a row in the database and returns a [Result](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result) with the existing [Id](https://evolu.dev/docs/api-reference/common/Type/variables/Id). The first argument is the table name, and the second is an object containing the row data including the required `id` field. An optional third argument provides mutation options including an `onComplete` callback and `onlyValidate` flag. This function allows you to use custom IDs and optionally set `createdAt`, which is useful for external systems, data migrations, or when the same row may already be created on a different device. Returns a Result type - use `.ok` to check if the upsert succeeded, and `.value.id` to access the ID on success, or `.error` to handle validation errors. Evolu does not use SQL for mutations to ensure data can be safely and predictably merged without conflicts. Explicit mutations also allow Evolu to automatically update [SystemColumns](https://evolu.dev/docs/api-reference/common/local-first/variables/SystemColumns-1). ### Example `// Use deterministic ID for stable upserts across devices const stableId = createIdFromString("my-todo-1"); const result = evolu.upsert("todo", { id: stableId, title: "Learn Evolu", isCompleted: false, }); if (result.ok) { console.log("Todo upserted with ID:", result.value.id); } else { console.error("Validation error:", result.error); } // Data migration with custom createdAt evolu.upsert("todo", { id: externalId, title: "Migrated todo", createdAt: new Date("2023-01-01"), // Preserve original timestamp }); // With onComplete callback evolu.upsert( "todo", { id: stableId, title: "Updated title" }, { onComplete: () => { console.log("Upsert completed"); }, }, );` | [packages/common/src/local-first/Evolu.ts:389](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Evolu.ts#L389) |
| <a id="useowner"></a> `useOwner` | `readonly` | (`owner`) => [`UnuseOwner`](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/UnuseOwner) | **`Experimental`** Use a [SyncOwner](https://evolu.dev/docs/api-reference/common/local-first/interfaces/SyncOwner). Returns a [UnuseOwner](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/UnuseOwner). Using an owner means syncing it with its transports, or the transports defined in Evolu config if the owner has no transports defined. Transport are automatically deduplicated and reference-counted, so multiple owners using the same transport will share a single connection. ### Example `// Use an owner (starts syncing). const unuseOwner = evolu.useOwner(shardOwner); // Later, stop using the owner. unuseOwner(); // Bulk operations. const unuseOwners = owners.map((owner) => evolu.useOwner(owner)); // Later: for (const unuse of unuseOwners) unuse();` | [packages/common/src/local-first/Evolu.ts:454](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Evolu.ts#L454) |
## Methods
### \[dispose\]()
##
Defined in: node_modules/typescript/lib/lib.esnext.disposable.d.ts:36
##### Returns
`void`
##### Inherited from
```ts
Disposable.[dispose]
```
##
Defined in: node_modules/@types/node/compatibility/disposable.d.ts:9
##### Returns
`void`
##### Inherited from
```ts
Disposable.[dispose]
```
EvoluConfig - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / EvoluConfig
# Interface: EvoluConfig
Defined in: [packages/common/src/local-first/Evolu.ts:77](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Evolu.ts#L77)
## Extends
- `Partial`\<[`DbConfig`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/DbConfig)\>
## Properties
| Property | Modifier | Type | Description | Inherited from | Defined in |
| ------------------------------------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="enablelogging"></a> `enableLogging?` | `readonly` | `boolean` | Enable or disable console logging (default: false). When true, logs are output to the [Console](https://evolu.dev/docs/api-reference/common/Console/interfaces/Console); when false, logging is disabled for all methods except `error`, which always outputs to ensure critical issues are not missed. | [`ConsoleConfig`](https://evolu.dev/docs/api-reference/common/Console/interfaces/ConsoleConfig).[`enableLogging`](https://evolu.dev/docs/api-reference/common/Console/interfaces/ConsoleConfig.mdx#enablelogging) | [packages/common/src/Console.ts:96](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Console.ts#L96) |
| <a id="encryptionkey"></a> `encryptionKey?` | `readonly` | `Uint8Array`\<`ArrayBufferLike`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Entropy"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Length32"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"EncryptionKey"`\> | **`Experimental`** Encryption key for the SQLite database. Note: If an unencrypted SQLite database already exists and you provide an encryptionKey, SQLite will throw an error. | [`DbConfig`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/DbConfig).[`encryptionKey`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/DbConfig.mdx#encryptionkey) | [packages/common/src/local-first/Db.ts:211](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Db.ts#L211) |
| <a id="externalappowner"></a> `externalAppOwner?` | `readonly` | [`AppOwner`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/AppOwner) | External AppOwner to use when creating Evolu instance. Use this when you want to manage AppOwner creation and persistence externally (e.g., with your own authentication system). If omitted, Evolu will automatically create and persist an AppOwner locally. For device-specific settings and account management state, we can use a separate local-only Evolu instance via `transports: []`. ### Example `const ConfigId = id("Config"); type ConfigId = typeof ConfigId.Type; const DeviceSchema = { config: { id: ConfigId, key: NonEmptyString50, value: NonEmptyString50, }, }; // Local-only instance for device settings (no sync) const deviceEvolu = createEvolu(evoluReactWebDeps)(DeviceSchema, { name: SimpleName.orThrow("MyApp-Device"), transports: [], // No sync - stays local to device }); // Main synced instance for user data const evolu = createEvolu(evoluReactWebDeps)(MainSchema, { name: SimpleName.orThrow("MyApp"), // Default transports for sync });` | [`DbConfig`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/DbConfig).[`externalAppOwner`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/DbConfig.mdx#externalappowner) | [packages/common/src/local-first/Db.ts:190](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Db.ts#L190) |
| <a id="indexes"></a> `indexes?` | `readonly` | [`IndexesConfig`](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/IndexesConfig) | Use the `indexes` option to define SQLite indexes. Table and column names are not typed because Kysely doesn't support it. https://medium.com/@JasonWyatt/squeezing-performance-from-sqlite-indexes-indexes-c4e175f3c346 ### Example `const evolu = createEvolu(evoluReactDeps)(Schema, { indexes: (create) => [ create("todoCreatedAt").on("todo").column("createdAt"), create("todoCategoryCreatedAt") .on("todoCategory") .column("createdAt"), ], });` | - | [packages/common/src/local-first/Evolu.ts:98](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Evolu.ts#L98) |
| <a id="inmemory"></a> `inMemory?` | `readonly` | `boolean` | Use in-memory SQLite database instead of persistent storage. Useful for testing or temporary data that doesn't need persistence. In-memory databases exist only in RAM and are completely destroyed when the process ends, making them forensically safe for sensitive data. The default value is: `false`. | [`DbConfig`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/DbConfig).[`inMemory`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/DbConfig.mdx#inmemory) | [packages/common/src/local-first/Db.ts:201](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Db.ts#L201) |
| <a id="maxdrift"></a> `maxDrift?` | `readonly` | `number` | Maximum physical clock drift allowed in ms. The default value is 5 _ 60 _ 1000 (5 minutes). | [`DbConfig`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/DbConfig).[`maxDrift`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/DbConfig.mdx#maxdrift) | [packages/common/src/local-first/Timestamp.ts:26](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Timestamp.ts#L26) |
| <a id="name"></a> `name?` | `readonly` | `string` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"UrlSafeString"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"SimpleName"`\> | The name of the Evolu instance. Evolu is multitenant - it can run multiple instances concurrently. Each instance must have a unique name. The instance name is used as the SQLite database filename for persistent storage, ensuring that database files are separated and invisible to each other. The default value is: `Evolu`. ### Example `// name: SimpleName.orThrow("MyApp")` | [`DbConfig`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/DbConfig).[`name`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/DbConfig.mdx#name) | [packages/common/src/local-first/Db.ts:95](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Db.ts#L95) |
| <a id="reloadurl"></a> `reloadUrl?` | `readonly` | `string` | URL to reload browser tabs after reset or restore. The default value is `/`. Note: This option will be moved to web platform deps in the next major version. | - | [packages/common/src/local-first/Evolu.ts:108](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Evolu.ts#L108) |
| <a id="transports"></a> `transports?` | `readonly` | readonly [`OwnerWebSocketTransport`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/OwnerWebSocketTransport)[] | Transport configuration for data sync and backup. Supports single transport or multiple transports simultaneously for redundancy. **Redundancy:** The ideal setup uses at least two completely independent relays - for example, a home relay and a geographically separate relay. Data is sent to both relays simultaneously, providing true redundancy similar to using two independent clouds. This eliminates vendor lock-in and ensures your app continues working regardless of circumstances - whether home relay hardware is stolen or a remote relay provider shuts down. Currently supports: - WebSocket: Real-time bidirectional communication with relay servers Empty transports create local-only instances. Transports can be dynamically added and removed for any owner (including [AppOwner](https://evolu.dev/docs/api-reference/common/local-first/interfaces/AppOwner)) via [Evolu#useOwner](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Evolu.mdx#useowner). Use [createOwnerWebSocketTransport](https://evolu.dev/docs/api-reference/common/local-first/functions/createOwnerWebSocketTransport) to create WebSocket transport configurations with proper URL formatting and [OwnerId](https://evolu.dev/docs/api-reference/common/local-first/variables/OwnerId) inclusion. The [OwnerId](https://evolu.dev/docs/api-reference/common/local-first/variables/OwnerId) in the URL enables relay authentication, allowing relay servers to control access (e.g., for paid tiers or private instances). The default value is: `{ type: "WebSocket", url: "wss://free.evoluhq.com" }`. ### Example `// Single WebSocket relay transports: [{ type: "WebSocket", url: "wss://relay1.example.com" }]; // Multiple WebSocket relays for redundancy transports: [ { type: "WebSocket", url: "wss://relay1.example.com" }, { type: "WebSocket", url: "wss://relay2.example.com" }, { type: "WebSocket", url: "wss://relay3.example.com" }, ]; // Local-only instance (no sync) - useful for device settings or when relay // URL will be provided later (e.g., after authentication), allowing users // to work offline before the app connects transports: []; // Using createOwnerWebSocketTransport helper for relay authentication transports: [ createOwnerWebSocketTransport({ url: "ws://localhost:4000", ownerId, }), ];` | [`DbConfig`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/DbConfig).[`transports`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/DbConfig.mdx#transports) | [packages/common/src/local-first/Db.ts:152](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Db.ts#L152) |
FingerprintRange - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / FingerprintRange
# Interface: FingerprintRange
Defined in: [packages/common/src/local-first/Storage.ts:223](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Storage.ts#L223)
## Extends
- [`BaseRange`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/BaseRange)
## Properties
| Property | Modifier | Type | Inherited from | Defined in |
| -------------------------------------- | ---------- | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="fingerprint"></a> `fingerprint` | `readonly` | [`Fingerprint`](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/Fingerprint) | - | [packages/common/src/local-first/Storage.ts:225](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Storage.ts#L225) |
| <a id="type"></a> `type` | `readonly` | `1` | - | [packages/common/src/local-first/Storage.ts:224](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Storage.ts#L224) |
| <a id="upperbound"></a> `upperBound` | `readonly` | [`RangeUpperBound`](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/RangeUpperBound) | [`BaseRange`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/BaseRange).[`upperBound`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/BaseRange.mdx#upperbound) | [packages/common/src/local-first/Storage.ts:199](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Storage.ts#L199) |
FlushSyncDep - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / FlushSyncDep
# Interface: FlushSyncDep
Defined in: [packages/common/src/local-first/Platform.ts:13](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Platform.ts#L13)
## Properties
| Property | Modifier | Type | Defined in |
| ---------------------------------- | ---------- | -------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="flushsync"></a> `flushSync` | `readonly` | [`FlushSync`](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/FlushSync) | [packages/common/src/local-first/Platform.ts:14](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Platform.ts#L14) |
GetQueryRowsCacheDep - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / GetQueryRowsCacheDep
# Interface: GetQueryRowsCacheDep
Defined in: [packages/common/src/local-first/Query.ts:162](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Query.ts#L162)
## Properties
| Property | Modifier | Type | Defined in |
| -------------------------------------------------- | ---------- | ------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="getqueryrowscache"></a> `getQueryRowsCache` | `readonly` | [`GetQueryRowsCache`](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/GetQueryRowsCache) | [packages/common/src/local-first/Query.ts:163](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Query.ts#L163) |
MutationChange - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / MutationChange
# Interface: MutationChange
Defined in: [packages/common/src/local-first/Schema.ts:328](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Schema.ts#L328)
## Extends
- [`DbChange`](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/DbChange)
## Properties
| Property | Modifier | Type | Description | Inherited from | Defined in |
| -------------------------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| <a id="id"></a> `id` | `public` | `string` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Id"`\> | - | `DbChange.id` | |
| <a id="isdelete"></a> `isDelete` | `public` | `boolean` \| `null` | - | `DbChange.isDelete` | |
| <a id="isinsert"></a> `isInsert` | `public` | `boolean` | - | `DbChange.isInsert` | |
| <a id="ownerid"></a> `ownerId?` | `readonly` | `string` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Id"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"OwnerId"`\> | Owner of the change. If undefined, the change belongs to the AppOwner. | - | [packages/common/src/local-first/Schema.ts:330](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Schema.ts#L330) |
| <a id="table"></a> `table` | `public` | `string` | - | `DbChange.table` | |
| <a id="values"></a> `values` | `public` | `Readonly`\<`Record`\<`string`, `string` \| `number` \| `Uint8Array`\<`ArrayBufferLike`\> \| `null`\>\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"ValidDbChangeValues"`\> | - | `DbChange.values` | |
MutationOptions - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / MutationOptions
# Interface: MutationOptions
Defined in: [packages/common/src/local-first/Schema.ts:276](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Schema.ts#L276)
## Properties
| Property | Modifier | Type | Description | Defined in |
| ----------------------------------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| <a id="oncomplete"></a> `onComplete?` | `readonly` | () => `void` | Called after the mutation is completed and the local state is updated. Useful for triggering side effects (e.g., notifications, UI updates) after insert, update, or upsert. | [packages/common/src/local-first/Schema.ts:282](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Schema.ts#L282) |
| <a id="onlyvalidate"></a> `onlyValidate?` | `readonly` | `boolean` | Only validate, don't mutate. For example, `onChange` handler can call `insert`/`update`/`upsert` with `onlyValidate: true`. | [packages/common/src/local-first/Schema.ts:325](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Schema.ts#L325) |
| <a id="ownerid"></a> `ownerId?` | `readonly` | `string` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Id"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"OwnerId"`\> | **`Experimental`** Specifies the owner ID for this mutation. If omitted, the default [AppOwner](https://evolu.dev/docs/api-reference/common/local-first/interfaces/AppOwner) is used. The owner must be used with `evolu.useOwner()` to enable sync. Mutations with unused owners are stored locally but not synced until the owner is used. ### Example `// Partition your own data by project (derived from your AppOwner) const projectOwner = deriveShardOwner(appOwner, [ "project", projectId, ]); evolu.insert( "task", { title: "Task 1" }, { ownerId: projectOwner.id }, ); // Collaborative data (independent owner shared with others) const sharedOwner = createSharedOwner(sharedSecret); evolu.insert( "comment", { text: "Hello" }, { ownerId: sharedOwner.id }, );` | [packages/common/src/local-first/Schema.ts:317](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Schema.ts#L317) |
NetworkError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / NetworkError
# Interface: NetworkError
Defined in: [packages/common/src/local-first/Sync.ts:936](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Sync.ts#L936)
## Properties
| Property | Modifier | Type | Defined in |
| ------------------------ | ---------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="type"></a> `type` | `readonly` | `"NetworkError"` | [packages/common/src/local-first/Sync.ts:937](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Sync.ts#L937) |
Owner - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / Owner
# Interface: Owner
Defined in: [packages/common/src/local-first/Owner.ts:66](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Owner.ts#L66)
The Owner represents ownership of data in Evolu. Every database change is
assigned to an owner and encrypted with its [OwnerEncryptionKey](https://evolu.dev/docs/api-reference/common/local-first/variables/OwnerEncryptionKey). Owners
allow partial sync, only the [AppOwner](https://evolu.dev/docs/api-reference/common/local-first/interfaces/AppOwner) is synced by default.
Owners can also provide real data deletion, while individual changes in
local-first/distributed systems can only be soft deleted, entire owners can
be completely deleted from both relays and devices (except for
[AppOwner](https://evolu.dev/docs/api-reference/common/local-first/interfaces/AppOwner), which must be preserved for sync coordination).
Evolu provides different owner types depending on their use case:
- **Coordination**: [AppOwner](https://evolu.dev/docs/api-reference/common/local-first/interfaces/AppOwner) for sync coordination and long-term
persistence
- **Data partitioning**: [ShardOwner](https://evolu.dev/docs/api-reference/common/local-first/interfaces/ShardOwner) for partitioning application data
- **Collaboration**: [SharedOwner](https://evolu.dev/docs/api-reference/common/local-first/interfaces/SharedOwner) for collaborative write access
- **Data sharing**: [SharedReadonlyOwner](https://evolu.dev/docs/api-reference/common/local-first/interfaces/SharedReadonlyOwner) for read-only access to shared
data
Owners are cryptographically derived from an [OwnerSecret](https://evolu.dev/docs/api-reference/common/local-first/variables/OwnerSecret) using
SLIP-21, ensuring secure and deterministic key generation:
- [OwnerId](https://evolu.dev/docs/api-reference/common/local-first/variables/OwnerId): Globally unique public identifier
- [OwnerEncryptionKey](https://evolu.dev/docs/api-reference/common/local-first/variables/OwnerEncryptionKey): Symmetric encryption key for data protection
- [OwnerWriteKey](https://evolu.dev/docs/api-reference/common/local-first/variables/OwnerWriteKey): Authentication token for write operations (rotatable)
## See
- [createAppOwner](https://evolu.dev/docs/api-reference/common/local-first/functions/createAppOwner)
- [createShardOwner](https://evolu.dev/docs/api-reference/common/local-first/functions/createShardOwner)
- [createSharedOwner](https://evolu.dev/docs/api-reference/common/local-first/functions/createSharedOwner)
- [createSharedReadonlyOwner](https://evolu.dev/docs/api-reference/common/local-first/functions/createSharedReadonlyOwner)
## Extends
- [`ReadonlyOwner`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/ReadonlyOwner)
## Extended by
- [`AppOwner`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/AppOwner)
- [`ShardOwner`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/ShardOwner)
- [`SharedOwner`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/SharedOwner)
## Properties
| Property | Modifier | Type | Description | Inherited from | Defined in |
| ------------------------------------------ | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="encryptionkey"></a> `encryptionKey` | `readonly` | `Uint8Array`\<`ArrayBufferLike`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Entropy"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Length32"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"EncryptionKey"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"OwnerEncryptionKey"`\> | TODO: Wrap with `Redacted` in the next major version. | [`ReadonlyOwner`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/ReadonlyOwner).[`encryptionKey`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/ReadonlyOwner.mdx#encryptionkey) | [packages/common/src/local-first/Owner.ts:32](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Owner.ts#L32) |
| <a id="id"></a> `id` | `readonly` | `string` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Id"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"OwnerId"`\> | - | [`ReadonlyOwner`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/ReadonlyOwner).[`id`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/ReadonlyOwner.mdx#id) | [packages/common/src/local-first/Owner.ts:30](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Owner.ts#L30) |
| <a id="writekey"></a> `writeKey` | `readonly` | `Uint8Array`\<`ArrayBufferLike`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Entropy"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Length16"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"OwnerWriteKey"`\> | TODO: Wrap with `Redacted` in the next major version. | - | [packages/common/src/local-first/Owner.ts:68](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Owner.ts#L68) |
OwnerError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / OwnerError
# Interface: OwnerError
Defined in: [packages/common/src/local-first/Owner.ts:385](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Owner.ts#L385)
Common interface implemented by all owner domain errors.
## Extended by
- [`ProtocolVersionError`](https://evolu.dev/docs/api-reference/common/local-first/Protocol/interfaces/ProtocolVersionError)
- [`ProtocolWriteKeyError`](https://evolu.dev/docs/api-reference/common/local-first/Protocol/interfaces/ProtocolWriteKeyError)
- [`ProtocolWriteError`](https://evolu.dev/docs/api-reference/common/local-first/Protocol/interfaces/ProtocolWriteError)
- [`ProtocolQuotaError`](https://evolu.dev/docs/api-reference/common/local-first/Protocol/interfaces/ProtocolQuotaError)
- [`ProtocolSyncError`](https://evolu.dev/docs/api-reference/common/local-first/Protocol/interfaces/ProtocolSyncError)
- [`StorageWriteError`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/StorageWriteError)
- [`StorageQuotaError`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/StorageQuotaError)
## Properties
| Property | Modifier | Type | Defined in |
| ------------------------------ | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="ownerid"></a> `ownerId` | `readonly` | `string` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Id"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"OwnerId"`\> | [packages/common/src/local-first/Owner.ts:386](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Owner.ts#L386) |
OwnerUsage - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / OwnerUsage
# Interface: OwnerUsage
Defined in: [packages/common/src/local-first/Owner.ts:398](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Owner.ts#L398)
Usage data for an [OwnerId](https://evolu.dev/docs/api-reference/common/local-first/variables/OwnerId).
Tracks storage usage to enforce quotas if needed, and some other stuff.
TODO:
- Add transferredBytes for billing and monitoring network usage.
## Properties
| Property | Modifier | Type | Description | Defined in |
| -------------------------------------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="firsttimestamp"></a> `firstTimestamp` | `readonly` | \| `Uint8Array`\<`ArrayBufferLike`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"TimestampBytes"`\> \| `null` | Tracks the earliest timestamp for timestamp insertion strategies. | [packages/common/src/local-first/Owner.ts:419](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Owner.ts#L419) |
| <a id="lasttimestamp"></a> `lastTimestamp` | `readonly` | \| `Uint8Array`\<`ArrayBufferLike`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"TimestampBytes"`\> \| `null` | Tracks the latest timestamp for timestamp insertion strategies. Free relays can use it to identify inactive accounts for cleanup. | [packages/common/src/local-first/Owner.ts:426](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Owner.ts#L426) |
| <a id="ownerid"></a> `ownerId` | `readonly` | `Uint8Array`\<`ArrayBufferLike`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Length16"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"IdBytes"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"OwnerIdBytes"`\> | The [Owner](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Owner) this usage data belongs to. | [packages/common/src/local-first/Owner.ts:400](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Owner.ts#L400) |
| <a id="storedbytes"></a> `storedBytes` | `readonly` | `number` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Int"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"NonNegative"`\> | Total logical data bytes stored. Measures the size of [EncryptedDbChange](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/EncryptedDbChange)s only, excluding [Storage](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Storage) implementation overhead (with SqliteStorage: indexes, skiplist columns, etc.). This provides: - **Predictable measurement** - same data = same byte count across all instances - **Quota enforcement** - consistent billing/limits independent of storage implementation - **Overhead tracking** - actual Storage size can be compared against this to monitor efficiency | [packages/common/src/local-first/Owner.ts:416](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Owner.ts#L416) |
OwnerWebSocketTransport - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / OwnerWebSocketTransport
# Interface: OwnerWebSocketTransport
Defined in: [packages/common/src/local-first/Owner.ts:328](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Owner.ts#L328)
WebSocket transport configuration.
### Authentication via URL
The [OwnerId](https://evolu.dev/docs/api-reference/common/local-first/variables/OwnerId) is passed as a URL query parameter. While this approach is
generally discouraged for authentication tokens (they get logged), it's safe
here because OwnerId is pseudonymous and used only for access verification -
it provides no ability to read encrypted data or write changes.
See: [HTTP headers in Websockets client
API](https://stackoverflow.com/questions/4361173/http-headers-in-websockets-client-api/74564827#74564827)
### Error Handling
When a relay rejects a connection (invalid OwnerId, unauthorized owner, or
server error), the browser WebSocket API does not expose the specific HTTP
status code or reason - it only reports a generic connection failure. The
client automatically retries with exponential backoff and jitter, eventually
succeeding once the configuration or server issue is resolved.
Legitimate clients will be properly configured with valid credentials, so
automatic retry is OK.
## See
- [createOwnerWebSocketTransport](https://evolu.dev/docs/api-reference/common/local-first/functions/createOwnerWebSocketTransport)
- [parseOwnerIdFromOwnerWebSocketTransportUrl](https://evolu.dev/docs/api-reference/common/local-first/functions/parseOwnerIdFromOwnerWebSocketTransportUrl)
## Properties
| Property | Modifier | Type | Defined in |
| ------------------------ | ---------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="type"></a> `type` | `readonly` | `"WebSocket"` | [packages/common/src/local-first/Owner.ts:329](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Owner.ts#L329) |
| <a id="url"></a> `url` | `readonly` | `string` | [packages/common/src/local-first/Owner.ts:330](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Owner.ts#L330) |
PaymentRequiredError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / PaymentRequiredError
# Interface: PaymentRequiredError
Defined in: [packages/common/src/local-first/Sync.ts:945](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Sync.ts#L945)
## Properties
| Property | Modifier | Type | Defined in |
| ------------------------ | ---------- | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="type"></a> `type` | `readonly` | `"PaymentRequiredError"` | [packages/common/src/local-first/Sync.ts:946](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Sync.ts#L946) |
PostMessageDep - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / PostMessageDep
# Interface: PostMessageDep
Defined in: [packages/common/src/local-first/Db.ts:325](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Db.ts#L325)
## Properties
| Property | Modifier | Type | Defined in |
| -------------------------------------- | ---------- | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="postmessage"></a> `postMessage` | `readonly` | (`message`) => `void` | [packages/common/src/local-first/Db.ts:326](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Db.ts#L326) |
QueryPatches - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / QueryPatches
# Interface: QueryPatches
Defined in: [packages/common/src/local-first/Query.ts:232](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Query.ts#L232)
## Properties
| Property | Modifier | Type | Defined in |
| ------------------------------ | ---------- | ----------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="patches"></a> `patches` | `readonly` | readonly [`Patch`](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/Patch)[] | [packages/common/src/local-first/Query.ts:234](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Query.ts#L234) |
| <a id="query"></a> `query` | `readonly` | [`Query`](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/Query) | [packages/common/src/local-first/Query.ts:233](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Query.ts#L233) |
QueryRowsCache - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / QueryRowsCache
# Interface: QueryRowsCache
Defined in: [packages/common/src/local-first/Query.ts:168](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Query.ts#L168)
## Properties
| Property | Modifier | Type | Defined in |
| ---------------------- | ---------- | -------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="get"></a> `get` | `readonly` | () => [`QueryRowsMap`](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/QueryRowsMap) | [packages/common/src/local-first/Query.ts:172](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Query.ts#L172) |
| <a id="set"></a> `set` | `readonly` | (`queriesRows`) => `void` | [packages/common/src/local-first/Query.ts:169](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Query.ts#L169) |
ReadonlyOwner - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / ReadonlyOwner
# Interface: ReadonlyOwner
Defined in: [packages/common/src/local-first/Owner.ts:29](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Owner.ts#L29)
[Owner](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Owner) without a [OwnerWriteKey](https://evolu.dev/docs/api-reference/common/local-first/variables/OwnerWriteKey).
## See
[createSharedReadonlyOwner](https://evolu.dev/docs/api-reference/common/local-first/functions/createSharedReadonlyOwner)
## Extended by
- [`Owner`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Owner)
- [`SharedReadonlyOwner`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/SharedReadonlyOwner)
- [`SyncOwner`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/SyncOwner)
## Properties
| Property | Modifier | Type | Description | Defined in |
| ------------------------------------------ | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="encryptionkey"></a> `encryptionKey` | `readonly` | `Uint8Array`\<`ArrayBufferLike`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Entropy"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Length32"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"EncryptionKey"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"OwnerEncryptionKey"`\> | TODO: Wrap with `Redacted` in the next major version. | [packages/common/src/local-first/Owner.ts:32](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Owner.ts#L32) |
| <a id="id"></a> `id` | `readonly` | `string` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Id"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"OwnerId"`\> | - | [packages/common/src/local-first/Owner.ts:30](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Owner.ts#L30) |
Relay - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / Relay
# Interface: Relay
Defined in: [packages/common/src/local-first/Relay.ts:100](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Relay.ts#L100)
A completely interchangeable server for syncing and backing up encrypted data
between Evolu clients.
Unlike traditional servers, relays are blind by design—they transmit
encrypted data without understanding its shape or meaning. This enables true
decentralization and infinite horizontal scalability with minimal
infrastructure.
## Extends
- `Disposable`
## Methods
### \[dispose\]()
##
Defined in: node_modules/typescript/lib/lib.esnext.disposable.d.ts:36
##### Returns
`void`
##### Inherited from
```ts
Disposable.[dispose]
```
##
Defined in: node_modules/@types/node/compatibility/disposable.d.ts:9
##### Returns
`void`
##### Inherited from
```ts
Disposable.[dispose]
```
RelayConfig - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / RelayConfig
# Interface: RelayConfig
Defined in: [packages/common/src/local-first/Relay.ts:36](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Relay.ts#L36)
## Extends
- [`ConsoleConfig`](https://evolu.dev/docs/api-reference/common/Console/interfaces/ConsoleConfig).[`StorageConfig`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/StorageConfig)
## Extended by
- [`NodeJsRelayConfig`](https://evolu.dev/docs/api-reference/nodejs/index/interfaces/NodeJsRelayConfig)
## Properties
| Property | Modifier | Type | Description | Inherited from | Defined in |
| ---------------------------------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| <a id="enablelogging"></a> `enableLogging?` | `readonly` | `boolean` | Enable or disable console logging (default: false). When true, logs are output to the [Console](https://evolu.dev/docs/api-reference/common/Console/interfaces/Console); when false, logging is disabled for all methods except `error`, which always outputs to ensure critical issues are not missed. | [`ConsoleConfig`](https://evolu.dev/docs/api-reference/common/Console/interfaces/ConsoleConfig).[`enableLogging`](https://evolu.dev/docs/api-reference/common/Console/interfaces/ConsoleConfig.mdx#enablelogging) | [packages/common/src/Console.ts:96](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Console.ts#L96) |
| <a id="isownerallowed"></a> `isOwnerAllowed?` | `readonly` | (`ownerId`) => [`MaybeAsync`](https://evolu.dev/docs/api-reference/common/Task/type-aliases/MaybeAsync)\<`boolean`\> | Optional callback to check if an [OwnerId](https://evolu.dev/docs/api-reference/common/local-first/variables/OwnerId) is allowed to access the relay. If this callback is not provided, all owners are allowed. The callback receives the [OwnerId](https://evolu.dev/docs/api-reference/common/local-first/variables/OwnerId) and returns a [MaybeAsync](https://evolu.dev/docs/api-reference/common/Task/type-aliases/MaybeAsync) boolean: `true` to allow access, or `false` to deny. The callback can be synchronous (for SQLite or in-memory checks) or asynchronous (for calling remote APIs). The callback returns a boolean rather than an error type because error handling and logging are the responsibility of the callback implementation. OwnerId is used rather than short-lived tokens because this only controls relay access, not write permissions. Since all data is encrypted on the relay, OwnerId exposure is safe. Owners specify which relays to connect to via [OwnerTransport](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/OwnerTransport). In WebSocket-based implementations, this check occurs before accepting the connection, with the OwnerId typically extracted from the URL Path (e.g., `ws://localhost:4000/<ownerId>`). The relay requires the URL to be in the correct format for OwnerId extraction. ### Example `// Client const transport = createOwnerWebSocketTransport({ url: "wss://relay.evolu.dev", ownerId: owner.id, }); const evolu = createEvolu(deps)(Schema, { transports: [transport], }); // Relay isOwnerAllowed: (ownerId) => Promise.resolve(ownerId === "6jy_2F4RT5qqeLgJ14_dnQ"),` | - | [packages/common/src/local-first/Relay.ts:88](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Relay.ts#L88) |
| <a id="isownerwithinquota"></a> `isOwnerWithinQuota` | `readonly` | (`ownerId`, `requiredBytes`) => [`MaybeAsync`](https://evolu.dev/docs/api-reference/common/Task/type-aliases/MaybeAsync)\<`boolean`\> | Callback called before an attempt to write, to check if an [OwnerId](https://evolu.dev/docs/api-reference/common/local-first/variables/OwnerId) has sufficient quota for the write. The callback receives the [OwnerId](https://evolu.dev/docs/api-reference/common/local-first/variables/OwnerId) and the total bytes that would be stored after the write (current stored bytes plus incoming bytes), and returns a [MaybeAsync](https://evolu.dev/docs/api-reference/common/Task/type-aliases/MaybeAsync) boolean: `true` to allow the write, or `false` to deny it due to quota limits. The callback can be synchronous (for SQLite or in-memory checks) or asynchronous (for calling remote APIs). The callback returns a boolean rather than an error because error handling and logging are the responsibility of the callback implementation. ### Example `// Client // evolu.subscribeError // Relay isOwnerWithinQuota: (ownerId, requiredBytes) => { console.log(ownerId, requiredBytes); // Check error via evolu.subscribeError return true; };` | [`StorageConfig`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/StorageConfig).[`isOwnerWithinQuota`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/StorageConfig.mdx#isownerwithinquota) | [packages/common/src/local-first/Storage.ts:68](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Storage.ts#L68) |
| <a id="name"></a> `name?` | `readonly` | `string` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"UrlSafeString"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"SimpleName"`\> | The relay name. Implementations can use this for identification purposes (e.g., database file name, logging). | - | [packages/common/src/local-first/Relay.ts:43](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Relay.ts#L43) |
RelayLogger - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / RelayLogger
# Interface: RelayLogger
Defined in: [packages/common/src/local-first/Relay.ts:359](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Relay.ts#L359)
## Properties
| Property | Modifier | Type | Defined in |
| ---------------------------------------------------------------------------------------------- | ---------- | ---------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="applyprotocolmessageasrelayerror"></a> `applyProtocolMessageAsRelayError` | `readonly` | (`error`) => `void` | [packages/common/src/local-first/Relay.ts:381](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Relay.ts#L381) |
| <a id="applyprotocolmessageasrelayunknownerror"></a> `applyProtocolMessageAsRelayUnknownError` | `readonly` | (`error`) => `void` | [packages/common/src/local-first/Relay.ts:385](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Relay.ts#L385) |
| <a id="connectionclosed"></a> `connectionClosed` | `readonly` | (`totalConnectionCount`) => `void` | [packages/common/src/local-first/Relay.ts:386](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Relay.ts#L386) |
| <a id="connectionestablished"></a> `connectionEstablished` | `readonly` | (`totalConnectionCount`) => `void` | [packages/common/src/local-first/Relay.ts:365](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Relay.ts#L365) |
| <a id="connectionwebsocketerror"></a> `connectionWebSocketError` | `readonly` | (`error`) => `void` | [packages/common/src/local-first/Relay.ts:366](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Relay.ts#L366) |
| <a id="httpserverdisposed"></a> `httpServerDisposed` | `readonly` | () => `void` | [packages/common/src/local-first/Relay.ts:389](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Relay.ts#L389) |
| <a id="invalidormissingowneridinurl"></a> `invalidOrMissingOwnerIdInUrl` | `readonly` | (`url`) => `void` | [packages/common/src/local-first/Relay.ts:363](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Relay.ts#L363) |
| <a id="messagelength"></a> `messageLength` | `readonly` | (`messageLength`) => `void` | [packages/common/src/local-first/Relay.ts:380](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Relay.ts#L380) |
| <a id="relayoptionbroadcast"></a> `relayOptionBroadcast` | `readonly` | (`ownerId`, `broadcastCount`, `subscriberCount`) => `void` | [packages/common/src/local-first/Relay.ts:375](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Relay.ts#L375) |
| <a id="relayoptionsubscribe"></a> `relayOptionSubscribe` | `readonly` | (`ownerId`, `getSubscriberCount`) => `void` | [packages/common/src/local-first/Relay.ts:367](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Relay.ts#L367) |
| <a id="relayoptionunsubscribe"></a> `relayOptionUnsubscribe` | `readonly` | (`ownerId`, `getSubscriberCount`) => `void` | [packages/common/src/local-first/Relay.ts:371](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Relay.ts#L371) |
| <a id="responselength"></a> `responseLength` | `readonly` | (`responseLength`) => `void` | [packages/common/src/local-first/Relay.ts:384](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Relay.ts#L384) |
| <a id="shuttingdown"></a> `shuttingDown` | `readonly` | () => `void` | [packages/common/src/local-first/Relay.ts:387](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Relay.ts#L387) |
| <a id="started"></a> `started` | `readonly` | (`enableLogging`, `port`) => `void` | [packages/common/src/local-first/Relay.ts:360](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Relay.ts#L360) |
| <a id="storageerror"></a> `storageError` | `readonly` | (`error`) => `void` | [packages/common/src/local-first/Relay.ts:361](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Relay.ts#L361) |
| <a id="unauthorizedowner"></a> `unauthorizedOwner` | `readonly` | (`ownerId`) => `void` | [packages/common/src/local-first/Relay.ts:364](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Relay.ts#L364) |
| <a id="upgradesocketerror"></a> `upgradeSocketError` | `readonly` | (`error`) => `void` | [packages/common/src/local-first/Relay.ts:362](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Relay.ts#L362) |
| <a id="websocketserverdisposed"></a> `webSocketServerDisposed` | `readonly` | () => `void` | [packages/common/src/local-first/Relay.ts:388](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Relay.ts#L388) |
ReloadAppDep - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / ReloadAppDep
# Interface: ReloadAppDep
Defined in: [packages/common/src/local-first/Platform.ts:25](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Platform.ts#L25)
## Properties
| Property | Modifier | Type | Defined in |
| ---------------------------------- | ---------- | -------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="reloadapp"></a> `reloadApp` | `readonly` | [`ReloadApp`](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/ReloadApp) | [packages/common/src/local-first/Platform.ts:26](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Platform.ts#L26) |
ReplaceAllPatch - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / ReplaceAllPatch
# Interface: ReplaceAllPatch
Defined in: [packages/common/src/local-first/Query.ts:239](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Query.ts#L239)
## Properties
| Property | Modifier | Type | Defined in |
| -------------------------- | ---------- | ----------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="op"></a> `op` | `readonly` | `"replaceAll"` | [packages/common/src/local-first/Query.ts:240](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Query.ts#L240) |
| <a id="value"></a> `value` | `readonly` | readonly [`Row`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Row)[] | [packages/common/src/local-first/Query.ts:241](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Query.ts#L241) |
ReplaceAtPatch - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / ReplaceAtPatch
# Interface: ReplaceAtPatch
Defined in: [packages/common/src/local-first/Query.ts:244](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Query.ts#L244)
## Properties
| Property | Modifier | Type | Defined in |
| -------------------------- | ---------- | ------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="index"></a> `index` | `readonly` | `number` | [packages/common/src/local-first/Query.ts:246](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Query.ts#L246) |
| <a id="op"></a> `op` | `readonly` | `"replaceAt"` | [packages/common/src/local-first/Query.ts:245](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Query.ts#L245) |
| <a id="value"></a> `value` | `readonly` | [`Row`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Row) | [packages/common/src/local-first/Query.ts:247](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Query.ts#L247) |
Row - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / Row
# Interface: Row
Defined in: [packages/common/src/local-first/Query.ts:99](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Query.ts#L99)
## Indexable
```ts
[key: string]:
| string
| number
| Uint8Array<ArrayBufferLike>
| Row
| readonly Row[]
| null
```
ServerError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / ServerError
# Interface: ServerError
Defined in: [packages/common/src/local-first/Sync.ts:940](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Sync.ts#L940)
## Properties
| Property | Modifier | Type | Defined in |
| ---------------------------- | ---------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="status"></a> `status` | `readonly` | `number` | [packages/common/src/local-first/Sync.ts:942](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Sync.ts#L942) |
| <a id="type"></a> `type` | `readonly` | `"ServerError"` | [packages/common/src/local-first/Sync.ts:941](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Sync.ts#L941) |
ShardOwner - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / ShardOwner
# Interface: ShardOwner
Defined in: [packages/common/src/local-first/Owner.ts:217](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Owner.ts#L217)
An [Owner](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Owner) for sharding data.
ShardOwners are the recommended storage location for most application data
because they can be completely deleted (both on relays and devices) and
conditionally synced.
Can be created from [OwnerSecret](https://evolu.dev/docs/api-reference/common/local-first/variables/OwnerSecret) via [createShardOwner](https://evolu.dev/docs/api-reference/common/local-first/functions/createShardOwner) or
deterministically derived from [AppOwner](https://evolu.dev/docs/api-reference/common/local-first/interfaces/AppOwner) using
[deriveShardOwner](https://evolu.dev/docs/api-reference/common/local-first/functions/deriveShardOwner).
## Extends
- [`Owner`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Owner)
## Properties
| Property | Modifier | Type | Description | Inherited from | Defined in |
| ------------------------------------------ | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="encryptionkey"></a> `encryptionKey` | `readonly` | `Uint8Array`\<`ArrayBufferLike`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Entropy"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Length32"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"EncryptionKey"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"OwnerEncryptionKey"`\> | TODO: Wrap with `Redacted` in the next major version. | [`Owner`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Owner).[`encryptionKey`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Owner.mdx#encryptionkey) | [packages/common/src/local-first/Owner.ts:32](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Owner.ts#L32) |
| <a id="id"></a> `id` | `readonly` | `string` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Id"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"OwnerId"`\> | - | [`Owner`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Owner).[`id`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Owner.mdx#id) | [packages/common/src/local-first/Owner.ts:30](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Owner.ts#L30) |
| <a id="type"></a> `type` | `readonly` | `"ShardOwner"` | - | - | [packages/common/src/local-first/Owner.ts:218](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Owner.ts#L218) |
| <a id="writekey"></a> `writeKey` | `readonly` | `Uint8Array`\<`ArrayBufferLike`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Entropy"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Length16"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"OwnerWriteKey"`\> | TODO: Wrap with `Redacted` in the next major version. | [`Owner`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Owner).[`writeKey`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Owner.mdx#writekey) | [packages/common/src/local-first/Owner.ts:68](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Owner.ts#L68) |
SharedOwner - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / SharedOwner
# Interface: SharedOwner
Defined in: [packages/common/src/local-first/Owner.ts:260](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Owner.ts#L260)
An [Owner](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Owner) for collaborative data with write access.
## Extends
- [`Owner`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Owner)
## Properties
| Property | Modifier | Type | Description | Inherited from | Defined in |
| ------------------------------------------ | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="encryptionkey"></a> `encryptionKey` | `readonly` | `Uint8Array`\<`ArrayBufferLike`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Entropy"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Length32"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"EncryptionKey"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"OwnerEncryptionKey"`\> | TODO: Wrap with `Redacted` in the next major version. | [`Owner`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Owner).[`encryptionKey`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Owner.mdx#encryptionkey) | [packages/common/src/local-first/Owner.ts:32](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Owner.ts#L32) |
| <a id="id"></a> `id` | `readonly` | `string` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Id"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"OwnerId"`\> | - | [`Owner`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Owner).[`id`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Owner.mdx#id) | [packages/common/src/local-first/Owner.ts:30](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Owner.ts#L30) |
| <a id="type"></a> `type` | `readonly` | `"SharedOwner"` | - | - | [packages/common/src/local-first/Owner.ts:261](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Owner.ts#L261) |
| <a id="writekey"></a> `writeKey` | `readonly` | `Uint8Array`\<`ArrayBufferLike`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Entropy"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Length16"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"OwnerWriteKey"`\> | TODO: Wrap with `Redacted` in the next major version. | [`Owner`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Owner).[`writeKey`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Owner.mdx#writekey) | [packages/common/src/local-first/Owner.ts:68](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Owner.ts#L68) |
SharedReadonlyOwner - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / SharedReadonlyOwner
# Interface: SharedReadonlyOwner
Defined in: [packages/common/src/local-first/Owner.ts:281](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Owner.ts#L281)
Read-only version of a [SharedOwner](https://evolu.dev/docs/api-reference/common/local-first/interfaces/SharedOwner) for data sharing. Contains only the
[OwnerId](https://evolu.dev/docs/api-reference/common/local-first/variables/OwnerId) and [EncryptionKey](https://evolu.dev/docs/api-reference/common/Crypto/variables/EncryptionKey) needed for others to read the shared
data without write access.
## Extends
- [`ReadonlyOwner`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/ReadonlyOwner)
## Properties
| Property | Modifier | Type | Description | Inherited from | Defined in |
| ------------------------------------------ | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="encryptionkey"></a> `encryptionKey` | `readonly` | `Uint8Array`\<`ArrayBufferLike`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Entropy"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Length32"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"EncryptionKey"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"OwnerEncryptionKey"`\> | TODO: Wrap with `Redacted` in the next major version. | [`ReadonlyOwner`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/ReadonlyOwner).[`encryptionKey`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/ReadonlyOwner.mdx#encryptionkey) | [packages/common/src/local-first/Owner.ts:32](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Owner.ts#L32) |
| <a id="id"></a> `id` | `readonly` | `string` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Id"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"OwnerId"`\> | - | [`ReadonlyOwner`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/ReadonlyOwner).[`id`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/ReadonlyOwner.mdx#id) | [packages/common/src/local-first/Owner.ts:30](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Owner.ts#L30) |
| <a id="type"></a> `type` | `readonly` | `"SharedReadonlyOwner"` | - | - | [packages/common/src/local-first/Owner.ts:282](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Owner.ts#L282) |
SkipRange - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / SkipRange
# Interface: SkipRange
Defined in: [packages/common/src/local-first/Storage.ts:219](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Storage.ts#L219)
## Extends
- [`BaseRange`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/BaseRange)
## Properties
| Property | Modifier | Type | Inherited from | Defined in |
| ------------------------------------ | ---------- | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="type"></a> `type` | `readonly` | `0` | - | [packages/common/src/local-first/Storage.ts:220](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Storage.ts#L220) |
| <a id="upperbound"></a> `upperBound` | `readonly` | [`RangeUpperBound`](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/RangeUpperBound) | [`BaseRange`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/BaseRange).[`upperBound`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/BaseRange.mdx#upperbound) | [packages/common/src/local-first/Storage.ts:199](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Storage.ts#L199) |
Storage - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / Storage
# Interface: Storage
Defined in: [packages/common/src/local-first/Storage.ts:91](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Storage.ts#L91)
Evolu Storage
Evolu protocol using Storage is agnostic to storage implementation
details—any storage can be plugged in, as long as it implements this
interface. Implementations must handle their own errors; return values only
indicate overall success or failure.
The Storage API is synchronous because SQLite's synchronous API is the
fastest way to use SQLite. Synchronous bindings (like better-sqlite3) call
SQLite's C API directly with no context switching between the event loop and
native code, and no promise microtasks or await overhead.
The only exception is [Storage#writeMessages](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Storage.mdx#writemessages), which is async to allow
for async validation logic before writing to storage. The write operation
itself remains synchronous.
## Extended by
- [`ClientStorage`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/ClientStorage)
## Properties
| Property | Modifier | Type | Description | Defined in |
| -------------------------------------------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="deleteowner"></a> `deleteOwner` | `readonly` | (`ownerId`) => `boolean` | Delete all data for the given [Owner](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Owner). Returns `true` on success, `false` on failure. | [packages/common/src/local-first/Storage.ts:167](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Storage.ts#L167) |
| <a id="findlowerbound"></a> `findLowerBound` | `readonly` | (`ownerId`, `begin`, `end`, `upperBound`) => \| `number` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Int"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"NonNegative"`\> \| `null` | - | [packages/common/src/local-first/Storage.ts:113](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Storage.ts#L113) |
| <a id="fingerprint"></a> `fingerprint` | `readonly` | (`ownerId`, `begin`, `end`) => \| [`Fingerprint`](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/Fingerprint) \| `null` | - | [packages/common/src/local-first/Storage.ts:94](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Storage.ts#L94) |
| <a id="fingerprintranges"></a> `fingerprintRanges` | `readonly` | (`ownerId`, `buckets`, `upperBound?`) => \| readonly [`FingerprintRange`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/FingerprintRange)[] \| `null` | Computes fingerprints with their upper bounds in one call. This function can be replaced with many fingerprint/findLowerBound calls, but implementations can leverage it for batching and more efficient fingerprint computation. | [packages/common/src/local-first/Storage.ts:107](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Storage.ts#L107) |
| <a id="getsize"></a> `getSize` | `readonly` | (`ownerId`) => \| `number` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Int"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"NonNegative"`\> \| `null` | - | [packages/common/src/local-first/Storage.ts:92](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Storage.ts#L92) |
| <a id="iterate"></a> `iterate` | `readonly` | (`ownerId`, `begin`, `end`, `callback`) => `void` | - | [packages/common/src/local-first/Storage.ts:120](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Storage.ts#L120) |
| <a id="readdbchange"></a> `readDbChange` | `readonly` | (`ownerId`, `timestamp`) => \| [`EncryptedDbChange`](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/EncryptedDbChange) \| `null` | Read encrypted [DbChange](https://evolu.dev/docs/api-reference/common/local-first/variables/DbChange)s from storage. | [packages/common/src/local-first/Storage.ts:157](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Storage.ts#L157) |
| <a id="setwritekey"></a> `setWriteKey` | `readonly` | (`ownerId`, `writeKey`) => `boolean` | Sets the [OwnerWriteKey](https://evolu.dev/docs/api-reference/common/local-first/variables/OwnerWriteKey) for the given [Owner](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Owner). | [packages/common/src/local-first/Storage.ts:138](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Storage.ts#L138) |
| <a id="validatewritekey"></a> `validateWriteKey` | `readonly` | (`ownerId`, `writeKey`) => `boolean` | Validates the [OwnerWriteKey](https://evolu.dev/docs/api-reference/common/local-first/variables/OwnerWriteKey) for the given [Owner](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Owner). Returns `true` if the write key is valid, `false` otherwise. | [packages/common/src/local-first/Storage.ts:132](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Storage.ts#L132) |
| <a id="writemessages"></a> `writeMessages` | `readonly` | (`ownerIdBytes`, `messages`) => [`MaybeAsync`](https://evolu.dev/docs/api-reference/common/Task/type-aliases/MaybeAsync)\<[`Result`](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result)\<`void`, \| [`StorageWriteError`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/StorageWriteError) \| [`StorageQuotaError`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/StorageQuotaError)\>\> | Write encrypted [CrdtMessage](https://evolu.dev/docs/api-reference/common/local-first/interfaces/CrdtMessage)s to storage. Must use a mutex per ownerId to ensure sequential processing and proper protocol logic handling during sync operations. TODO: Use MaybeAsync | [packages/common/src/local-first/Storage.ts:151](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Storage.ts#L151) |
StorageConfig - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / StorageConfig
# Interface: StorageConfig
Defined in: [packages/common/src/local-first/Storage.ts:38](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Storage.ts#L38)
## Extended by
- [`RelayConfig`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/RelayConfig)
- [`CreateBaseSqliteStorageConfig`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/CreateBaseSqliteStorageConfig)
## Properties
| Property | Modifier | Type | Description | Defined in |
| ---------------------------------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| <a id="isownerwithinquota"></a> `isOwnerWithinQuota` | `readonly` | (`ownerId`, `requiredBytes`) => [`MaybeAsync`](https://evolu.dev/docs/api-reference/common/Task/type-aliases/MaybeAsync)\<`boolean`\> | Callback called before an attempt to write, to check if an [OwnerId](https://evolu.dev/docs/api-reference/common/local-first/variables/OwnerId) has sufficient quota for the write. The callback receives the [OwnerId](https://evolu.dev/docs/api-reference/common/local-first/variables/OwnerId) and the total bytes that would be stored after the write (current stored bytes plus incoming bytes), and returns a [MaybeAsync](https://evolu.dev/docs/api-reference/common/Task/type-aliases/MaybeAsync) boolean: `true` to allow the write, or `false` to deny it due to quota limits. The callback can be synchronous (for SQLite or in-memory checks) or asynchronous (for calling remote APIs). The callback returns a boolean rather than an error because error handling and logging are the responsibility of the callback implementation. ### Example `// Client // evolu.subscribeError // Relay isOwnerWithinQuota: (ownerId, requiredBytes) => { console.log(ownerId, requiredBytes); // Check error via evolu.subscribeError return true; };` | [packages/common/src/local-first/Storage.ts:68](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Storage.ts#L68) |
StorageDep - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / StorageDep
# Interface: StorageDep
Defined in: [packages/common/src/local-first/Storage.ts:170](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Storage.ts#L170)
## Properties
| Property | Modifier | Type | Defined in |
| ------------------------------ | ---------- | -------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="storage"></a> `storage` | `readonly` | [`Storage`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Storage) | [packages/common/src/local-first/Storage.ts:171](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Storage.ts#L171) |
StorageQuotaError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / StorageQuotaError
# Interface: StorageQuotaError
Defined in: [packages/common/src/local-first/Storage.ts:180](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Storage.ts#L180)
Error when storage or billing quota is exceeded.
## Extends
- [`OwnerError`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/OwnerError)
## Properties
| Property | Modifier | Type | Inherited from | Defined in |
| ------------------------------ | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="ownerid"></a> `ownerId` | `readonly` | `string` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Id"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"OwnerId"`\> | [`OwnerError`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/OwnerError).[`ownerId`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/OwnerError.mdx#ownerid) | [packages/common/src/local-first/Owner.ts:386](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Owner.ts#L386) |
| <a id="type"></a> `type` | `readonly` | `"StorageQuotaError"` | - | [packages/common/src/local-first/Storage.ts:181](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Storage.ts#L181) |
StorageWriteError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / StorageWriteError
# Interface: StorageWriteError
Defined in: [packages/common/src/local-first/Storage.ts:175](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Storage.ts#L175)
Error indicating a serious write failure.
## Extends
- [`OwnerError`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/OwnerError)
## Properties
| Property | Modifier | Type | Inherited from | Defined in |
| ------------------------------ | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="ownerid"></a> `ownerId` | `readonly` | `string` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Id"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"OwnerId"`\> | [`OwnerError`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/OwnerError).[`ownerId`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/OwnerError.mdx#ownerid) | [packages/common/src/local-first/Owner.ts:386](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Owner.ts#L386) |
| <a id="type"></a> `type` | `readonly` | `"StorageWriteError"` | - | [packages/common/src/local-first/Storage.ts:176](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Storage.ts#L176) |
SubscribedQueries - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / SubscribedQueries
# Interface: SubscribedQueries
Defined in: [packages/common/src/local-first/Query.ts:126](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Query.ts#L126)
## Properties
| Property | Type | Defined in |
| ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="get"></a> `get` | () => readonly [`Query`](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/Query)\<[`Row`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Row)\>[] | [packages/common/src/local-first/Query.ts:131](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Query.ts#L131) |
| <a id="has"></a> `has` | (`query`) => `boolean` | [packages/common/src/local-first/Query.ts:129](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Query.ts#L129) |
| <a id="subscribe"></a> `subscribe` | (`query`) => [`StoreSubscribe`](https://evolu.dev/docs/api-reference/common/Store/type-aliases/StoreSubscribe) | [packages/common/src/local-first/Query.ts:127](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Query.ts#L127) |
Sync - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / Sync
# Interface: Sync
Defined in: [packages/common/src/local-first/Sync.ts:93](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Sync.ts#L93)
## Extends
- `Disposable`
## Properties
| Property | Modifier | Type | Description | Defined in |
| ---------------------------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="applychanges"></a> `applyChanges` | `readonly` | (`changes`) => [`Result`](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result)\<`void`, \| [`SqliteError`](https://evolu.dev/docs/api-reference/common/Sqlite/interfaces/SqliteError) \| [`TimestampDriftError`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/TimestampDriftError) \| [`TimestampCounterOverflowError`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/TimestampCounterOverflowError) \| [`TimestampTimeOutOfRangeError`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/TimestampTimeOutOfRangeError)\> | - | [packages/common/src/local-first/Sync.ts:103](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Sync.ts#L103) |
| <a id="useowner"></a> `useOwner` | `readonly` | (`use`, `owner`) => `void` | Assigns or removes an owner to/from transports with reference counting. Owners are only synced if assigned to at least one transport. Uses `owner.transports` or falls back to [SyncConfig](https://evolu.dev/docs/api-reference/common/local-first/interfaces/SyncConfig) transports. Multiple calls increment/decrement reference counts (useful for React Hooks). | [packages/common/src/local-first/Sync.ts:101](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Sync.ts#L101) |
## Methods
### \[dispose\]()
##
Defined in: node_modules/typescript/lib/lib.esnext.disposable.d.ts:36
##### Returns
`void`
##### Inherited from
```ts
Disposable.[dispose]
```
##
Defined in: node_modules/@types/node/compatibility/disposable.d.ts:9
##### Returns
`void`
##### Inherited from
```ts
Disposable.[dispose]
```
SyncConfig - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / SyncConfig
# Interface: SyncConfig
Defined in: [packages/common/src/local-first/Sync.ts:129](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Sync.ts#L129)
## Properties
| Property | Modifier | Type | Description | Defined in |
| ----------------------------------------------- | ---------- | --------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="appowner"></a> `appOwner` | `readonly` | [`AppOwner`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/AppOwner) | - | [packages/common/src/local-first/Sync.ts:130](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Sync.ts#L130) |
| <a id="disposaldelayms"></a> `disposalDelayMs?` | `readonly` | `number` | Delay in milliseconds before disposing unused WebSocket connections. Defaults to 100ms. | [packages/common/src/local-first/Sync.ts:138](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Sync.ts#L138) |
| <a id="onerror"></a> `onError` | `readonly` | (`error`) => `void` | - | [packages/common/src/local-first/Sync.ts:140](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Sync.ts#L140) |
| <a id="onreceive"></a> `onReceive` | `readonly` | () => `void` | - | [packages/common/src/local-first/Sync.ts:153](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Sync.ts#L153) |
| <a id="transports"></a> `transports` | `readonly` | readonly [`OwnerWebSocketTransport`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/OwnerWebSocketTransport)[] | - | [packages/common/src/local-first/Sync.ts:132](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Sync.ts#L132) |
SyncDep - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / SyncDep
# Interface: SyncDep
Defined in: [packages/common/src/local-first/Sync.ts:114](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Sync.ts#L114)
## Properties
| Property | Modifier | Type | Defined in |
| ------------------------ | ---------- | -------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="sync"></a> `sync` | `readonly` | [`Sync`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Sync) | [packages/common/src/local-first/Sync.ts:115](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Sync.ts#L115) |
SyncOwner - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / SyncOwner
# Interface: SyncOwner
Defined in: [packages/common/src/local-first/Sync.ts:124](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Sync.ts#L124)
Represents an owner for sync operations.
Includes readonly owner fields plus optional write key (for clients that
write) and optional transports to override SyncConfig transports per owner.
## Extends
- [`ReadonlyOwner`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/ReadonlyOwner)
## Properties
| Property | Modifier | Type | Description | Inherited from | Defined in |
| ------------------------------------------ | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="encryptionkey"></a> `encryptionKey` | `readonly` | `Uint8Array`\<`ArrayBufferLike`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Entropy"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Length32"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"EncryptionKey"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"OwnerEncryptionKey"`\> | TODO: Wrap with `Redacted` in the next major version. | [`ReadonlyOwner`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/ReadonlyOwner).[`encryptionKey`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/ReadonlyOwner.mdx#encryptionkey) | [packages/common/src/local-first/Owner.ts:32](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Owner.ts#L32) |
| <a id="id"></a> `id` | `readonly` | `string` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Id"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"OwnerId"`\> | - | [`ReadonlyOwner`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/ReadonlyOwner).[`id`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/ReadonlyOwner.mdx#id) | [packages/common/src/local-first/Owner.ts:30](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Owner.ts#L30) |
| <a id="transports"></a> `transports?` | `readonly` | readonly [`OwnerWebSocketTransport`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/OwnerWebSocketTransport)[] | - | - | [packages/common/src/local-first/Sync.ts:126](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Sync.ts#L126) |
| <a id="writekey"></a> `writeKey?` | `readonly` | `Uint8Array`\<`ArrayBufferLike`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Entropy"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Length16"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"OwnerWriteKey"`\> | - | - | [packages/common/src/local-first/Sync.ts:125](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Sync.ts#L125) |
SyncStateInitial - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / SyncStateInitial
# Interface: SyncStateInitial
Defined in: [packages/common/src/local-first/Sync.ts:918](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Sync.ts#L918)
The initial synchronization state when the app starts. In this state, the app
needs to determine whether the data is synced.
## Properties
| Property | Modifier | Type | Defined in |
| ------------------------ | ---------- | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="type"></a> `type` | `readonly` | `"SyncStateInitial"` | [packages/common/src/local-first/Sync.ts:919](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Sync.ts#L919) |
SyncStateIsNotSynced - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / SyncStateIsNotSynced
# Interface: SyncStateIsNotSynced
Defined in: [packages/common/src/local-first/Sync.ts:931](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Sync.ts#L931)
## Properties
| Property | Modifier | Type | Defined in |
| -------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="error"></a> `error` | `readonly` | \| [`NetworkError`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/NetworkError) \| [`ServerError`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/ServerError) \| [`PaymentRequiredError`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/PaymentRequiredError) | [packages/common/src/local-first/Sync.ts:933](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Sync.ts#L933) |
| <a id="type"></a> `type` | `readonly` | `"SyncStateIsNotSynced"` | [packages/common/src/local-first/Sync.ts:932](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Sync.ts#L932) |
SyncStateIsSynced - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / SyncStateIsSynced
# Interface: SyncStateIsSynced
Defined in: [packages/common/src/local-first/Sync.ts:926](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Sync.ts#L926)
## Properties
| Property | Modifier | Type | Defined in |
| ------------------------ | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="time"></a> `time` | `readonly` | `number` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Int"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"NonNegative"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`` `LessThanOrEqualTo${number}` ``\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Millis"`\> | [packages/common/src/local-first/Sync.ts:928](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Sync.ts#L928) |
| <a id="type"></a> `type` | `readonly` | `"SyncStateIsSynced"` | [packages/common/src/local-first/Sync.ts:927](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Sync.ts#L927) |
SyncStateIsSyncing - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / SyncStateIsSyncing
# Interface: SyncStateIsSyncing
Defined in: [packages/common/src/local-first/Sync.ts:922](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Sync.ts#L922)
## Properties
| Property | Modifier | Type | Defined in |
| ------------------------ | ---------- | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="type"></a> `type` | `readonly` | `"SyncStateIsSyncing"` | [packages/common/src/local-first/Sync.ts:923](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Sync.ts#L923) |
Timestamp - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / Timestamp
# Interface: Timestamp
Defined in: [packages/common/src/local-first/Timestamp.ts:169](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Timestamp.ts#L169)
Extracts the type from a [Type](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type).
## Extends
- [`InferType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferType)\<_typeof_ [`Timestamp`](https://evolu.dev/docs/api-reference/common/local-first/variables/Timestamp)\>
## Properties
| Property | Type | Inherited from | Defined in |
| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
| <a id="counter"></a> `counter` | `number` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Int"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"NonNegative"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"LessThanOrEqualTo65535"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Counter"`\> | [`Timestamp`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Timestamp).[`counter`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Timestamp.mdx#counter) | |
| <a id="millis"></a> `millis` | `number` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Int"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"NonNegative"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`` `LessThanOrEqualTo${number}` ``\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Millis"`\> | [`Timestamp`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Timestamp).[`millis`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Timestamp.mdx#millis) | |
| <a id="nodeid"></a> `nodeId` | `string` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"NodeId"`\> | [`Timestamp`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Timestamp).[`nodeId`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Timestamp.mdx#nodeid) | |
TimestampConfig - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / TimestampConfig
# Interface: TimestampConfig
Defined in: [packages/common/src/local-first/Timestamp.ts:20](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Timestamp.ts#L20)
## Extended by
- [`DbConfig`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/DbConfig)
## Properties
| Property | Modifier | Type | Description | Defined in |
| -------------------------------- | ---------- | -------- | ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="maxdrift"></a> `maxDrift` | `readonly` | `number` | Maximum physical clock drift allowed in ms. The default value is 5 _ 60 _ 1000 (5 minutes). | [packages/common/src/local-first/Timestamp.ts:26](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Timestamp.ts#L26) |
TimestampConfigDep - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / TimestampConfigDep
# Interface: TimestampConfigDep
Defined in: [packages/common/src/local-first/Timestamp.ts:29](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Timestamp.ts#L29)
## Properties
| Property | Modifier | Type | Defined in |
| ---------------------------------------------- | ---------- | ------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="timestampconfig"></a> `timestampConfig` | `readonly` | [`TimestampConfig`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/TimestampConfig) | [packages/common/src/local-first/Timestamp.ts:30](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Timestamp.ts#L30) |
TimestampCounterOverflowError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / TimestampCounterOverflowError
# Interface: TimestampCounterOverflowError
Defined in: [packages/common/src/local-first/Timestamp.ts:44](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Timestamp.ts#L44)
## Properties
| Property | Modifier | Type | Defined in |
| ------------------------ | ---------- | --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="type"></a> `type` | `readonly` | `"TimestampCounterOverflowError"` | [packages/common/src/local-first/Timestamp.ts:45](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Timestamp.ts#L45) |
TimestampDriftError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / TimestampDriftError
# Interface: TimestampDriftError
Defined in: [packages/common/src/local-first/Timestamp.ts:38](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Timestamp.ts#L38)
## Properties
| Property | Modifier | Type | Defined in |
| ------------------------ | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="next"></a> `next` | `readonly` | `number` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Int"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"NonNegative"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`` `LessThanOrEqualTo${number}` ``\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Millis"`\> | [packages/common/src/local-first/Timestamp.ts:40](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Timestamp.ts#L40) |
| <a id="now"></a> `now` | `readonly` | `number` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Int"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"NonNegative"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`` `LessThanOrEqualTo${number}` ``\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Millis"`\> | [packages/common/src/local-first/Timestamp.ts:41](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Timestamp.ts#L41) |
| <a id="type"></a> `type` | `readonly` | `"TimestampDriftError"` | [packages/common/src/local-first/Timestamp.ts:39](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Timestamp.ts#L39) |
TimestampTimeOutOfRangeError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / TimestampTimeOutOfRangeError
# Interface: TimestampTimeOutOfRangeError
Defined in: [packages/common/src/local-first/Timestamp.ts:48](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Timestamp.ts#L48)
## Properties
| Property | Modifier | Type | Defined in |
| ------------------------ | ---------- | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="type"></a> `type` | `readonly` | `"TimestampTimeOutOfRangeError"` | [packages/common/src/local-first/Timestamp.ts:49](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Timestamp.ts#L49) |
TimestampsRange - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / TimestampsRange
# Interface: TimestampsRange
Defined in: [packages/common/src/local-first/Storage.ts:228](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Storage.ts#L228)
## Extends
- [`BaseRange`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/BaseRange)
## Properties
| Property | Modifier | Type | Inherited from | Defined in |
| ------------------------------------ | ---------- | ------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="timestamps"></a> `timestamps` | `readonly` | readonly `Uint8Array`\<`ArrayBufferLike`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"TimestampBytes"`\>[] | - | [packages/common/src/local-first/Storage.ts:230](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Storage.ts#L230) |
| <a id="type"></a> `type` | `readonly` | `2` | - | [packages/common/src/local-first/Storage.ts:229](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Storage.ts#L229) |
| <a id="upperbound"></a> `upperBound` | `readonly` | [`RangeUpperBound`](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/RangeUpperBound) | [`BaseRange`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/BaseRange).[`upperBound`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/BaseRange.mdx#upperbound) | [packages/common/src/local-first/Storage.ts:199](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Storage.ts#L199) |
ValidDbChangeValuesError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / ValidDbChangeValuesError
# Interface: ValidDbChangeValuesError
Defined in: [packages/common/src/local-first/Storage.ts:276](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Storage.ts#L276)
## Extends
- [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError)\<`"ValidDbChangeValues"`\>
## Properties
| Property | Modifier | Type | Description | Inherited from | Defined in |
| -------------------------------------------- | ---------- | ----------------------- | -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="invalidcolumns"></a> `invalidColumns` | `readonly` | readonly `string`[] | - | - | [packages/common/src/local-first/Storage.ts:277](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Storage.ts#L277) |
| <a id="type"></a> `type` | `readonly` | `"ValidDbChangeValues"` | - | [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError).[`type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError.mdx#type) | [packages/common/src/Type.ts:428](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L428) |
| <a id="value"></a> `value` | `readonly` | `unknown` | The value that was received and caused the error. Provides additional context for debugging and validation feedback. | [`TypeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError).[`value`](https://evolu.dev/docs/api-reference/common/Type/interfaces/TypeError.mdx#value) | [packages/common/src/Type.ts:434](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L434) |
Counter - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / Counter
# Type Alias: Counter
```ts
type Counter = typeof Type;
```
Defined in: [packages/common/src/local-first/Timestamp.ts:73](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Timestamp.ts#L73)
CreateDbWorker - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / CreateDbWorker
# Type Alias: CreateDbWorker()
```ts
type CreateDbWorker = (name) => DbWorker;
```
Defined in: [packages/common/src/local-first/Db.ts:223](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Db.ts#L223)
## Parameters
| Parameter | Type |
| --------- | --------------------------------------------------------------------------- |
| `name` | [`SimpleName`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/SimpleName) |
## Returns
[`DbWorker`](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/DbWorker)
CreateQuery - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / CreateQuery
# Type Alias: CreateQuery()\<S\>
```ts
type CreateQuery<S> = <R>(queryCallback, options?) => Query<Simplify<R>>;
```
Defined in: [packages/common/src/local-first/Schema.ts:197](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Schema.ts#L197)
## Type Parameters
| Type Parameter |
| -------------------------------------------------------------------------------------------------- |
| `S` _extends_ [`EvoluSchema`](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/EvoluSchema) |
## Type Parameters
| Type Parameter |
| -------------------------------------------------------------------------------- |
| `R` _extends_ [`Row`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Row) |
## Parameters
| Parameter | Type |
| --------------- | ------------------------------------------------------------------------------------------- |
| `queryCallback` | (`db`) => `Kysely.SelectQueryBuilder`\<`any`, `any`, `R`\> |
| `options?` | [`SqliteQueryOptions`](https://evolu.dev/docs/api-reference/common/Sqlite/interfaces/SqliteQueryOptions) |
## Returns
[`Query`](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/Query)\<[`Simplify`](https://evolu.dev/docs/api-reference/common/Types/type-aliases/Simplify)\<`R`\>\>
DbChange - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / DbChange
# Type Alias: DbChange
```ts
type DbChange = typeof Type;
```
Defined in: [packages/common/src/local-first/Storage.ts:284](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Storage.ts#L284)
DbChangeValues - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / DbChangeValues
# Type Alias: DbChangeValues
```ts
type DbChangeValues = typeof Type;
```
Defined in: [packages/common/src/local-first/Storage.ts:256](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Storage.ts#L256)
DbIndex - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / DbIndex
# Type Alias: DbIndex
```ts
type DbIndex = typeof Type;
```
Defined in: [packages/common/src/local-first/Schema.ts:463](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Schema.ts#L463)
DbSchema - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / DbSchema
# Type Alias: DbSchema
```ts
type DbSchema = typeof Type;
```
Defined in: [packages/common/src/local-first/Schema.ts:466](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Schema.ts#L466)
DbWorker - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / DbWorker
# Type Alias: DbWorker
```ts
type DbWorker = Worker<DbWorkerInput, DbWorkerOutput>;
```
Defined in: [packages/common/src/local-first/Db.ts:221](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Db.ts#L221)
DbWorkerInput - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / DbWorkerInput
# Type Alias: DbWorkerInput
```ts
type DbWorkerInput =
| {
config: DbConfig;
dbSchema: DbSchema;
type: "init";
}
| {
type: "getAppOwner";
}
| {
changes: NonEmptyReadonlyArray<MutationChange>;
onCompleteIds: ReadonlyArray<CallbackId>;
subscribedQueries: ReadonlyArray<Query>;
tabId: Id;
type: "mutate";
}
| {
queries: NonEmptyReadonlyArray<Query>;
tabId: Id;
type: "query";
}
| {
onCompleteId: CallbackId;
reload: boolean;
restore?: {
dbSchema: DbSchema;
mnemonic: Mnemonic;
};
type: "reset";
}
| {
dbSchema: DbSchema;
type: "ensureDbSchema";
}
| {
onCompleteId: CallbackId;
type: "export";
}
| {
owner: SyncOwner;
type: "useOwner";
use: boolean;
};
```
Defined in: [packages/common/src/local-first/Db.ts:229](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Db.ts#L229)
DbWorkerOutput - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / DbWorkerOutput
# Type Alias: DbWorkerOutput
```ts
type DbWorkerOutput =
| {
error:
| ProtocolError
| SqliteError
| SymmetricCryptoDecryptError
| TimestampError
| TransferableError;
type: "onError";
}
| {
appOwner: AppOwner;
type: "onGetAppOwner";
}
| {
onCompleteIds: ReadonlyArray<CallbackId>;
queryPatches: ReadonlyArray<QueryPatches>;
tabId: Id;
type: "onQueryPatches";
}
| {
tabId?: Id;
type: "refreshQueries";
}
| {
onCompleteId: CallbackId;
reload: boolean;
type: "onReset";
}
| {
file: Uint8Array;
onCompleteId: CallbackId;
type: "onExport";
};
```
Defined in: [packages/common/src/local-first/Db.ts:273](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Db.ts#L273)
DbWorkerPlatformDeps - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / DbWorkerPlatformDeps
# Type Alias: DbWorkerPlatformDeps
```ts
type DbWorkerPlatformDeps = ConsoleDep &
CreateSqliteDriverDep &
CreateWebSocketDep &
RandomBytesDep &
RandomDep &
TimeDep;
```
Defined in: [packages/common/src/local-first/Db.ts:308](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Db.ts#L308)
EncryptedDbChange - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / EncryptedDbChange
# Type Alias: EncryptedDbChange
```ts
type EncryptedDbChange = Uint8Array & Brand<"EncryptedDbChange">;
```
Defined in: [packages/common/src/local-first/Storage.ts:242](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Storage.ts#L242)
Encrypted DbChange
EvoluDeps - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / EvoluDeps
# Type Alias: EvoluDeps
```ts
type EvoluDeps = ConsoleDep &
CreateDbWorkerDep &
Partial<FlushSyncDep> &
RandomBytesDep &
ReloadAppDep &
TimeDep;
```
Defined in: [packages/common/src/local-first/Evolu.ts:478](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Evolu.ts#L478)
EvoluError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / EvoluError
# Type Alias: EvoluError
```ts
type EvoluError =
| ProtocolError
| SqliteError
| SymmetricCryptoDecryptError
| TimestampError
| TransferableError;
```
Defined in: [packages/common/src/local-first/Evolu.ts:461](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Evolu.ts#L461)
Represents errors that can occur in Evolu.
EvoluSchema - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / EvoluSchema
# Type Alias: EvoluSchema
```ts
type EvoluSchema = ReadonlyRecord<
string,
ReadonlyRecord<string, Type<any, any, any, any, any, any>>
>;
```
Defined in: [packages/common/src/local-first/Schema.ts:88](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Schema.ts#L88)
Defines the schema of an Evolu database.
Table schema defines columns that are required for table rows. For not
required columns, use [nullOr](https://evolu.dev/docs/api-reference/common/Type/functions/nullOr).
### Example
```ts
const TodoId = id("Todo");
type TodoId = typeof TodoId.Type;
const TodoCategoryId = id("TodoCategory");
type TodoCategoryId = typeof TodoCategoryId.Type;
const NonEmptyString50 = maxLength(50)(NonEmptyString);
type NonEmptyString50 = typeof NonEmptyString50.Type;
// Database schema.
const Schema = {
todo: {
id: TodoId,
title: NonEmptyString1000,
isCompleted: nullable(SqliteBoolean),
categoryId: nullable(TodoCategoryId),
},
todoCategory: {
id: TodoCategoryId,
name: NonEmptyString50,
json: nullable(SomeJson),
},
};
```
Fingerprint - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / Fingerprint
# Type Alias: Fingerprint
```ts
type Fingerprint = Uint8Array & Brand<"Fingerprint">;
```
Defined in: [packages/common/src/local-first/Storage.ts:191](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Storage.ts#L191)
A cryptographic hash used for efficiently comparing collections of
[TimestampBytes](https://evolu.dev/docs/api-reference/common/local-first/variables/TimestampBytes)s.
It consists of the first [fingerprintSize](https://evolu.dev/docs/api-reference/common/local-first/variables/fingerprintSize) bytes of the SHA-256 hash of
one or more timestamps.
FlushSync - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / FlushSync
# Type Alias: FlushSync()
```ts
type FlushSync = (callback) => void;
```
Defined in: [packages/common/src/local-first/Platform.ts:11](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Platform.ts#L11)
FlushSync is for libraries like React to flush updates synchronously inside
the provided callback to ensure the DOM is updated immediately.
For example, with React, when we want to focus on an element rendered as a
result of a mutation, Evolu ensures all DOM changes are flushed synchronously
if an onComplete callback is used.
https://react.dev/reference/react-dom/flushSync
## Parameters
| Parameter | Type |
| ---------- | ------------ |
| `callback` | () => `void` |
## Returns
`void`
GetQueryRowsCache - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / GetQueryRowsCache
# Type Alias: GetQueryRowsCache()
```ts
type GetQueryRowsCache = (tabId) => QueryRowsCache;
```
Defined in: [packages/common/src/local-first/Query.ts:166](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Query.ts#L166)
## Parameters
| Parameter | Type |
| --------- | ----------------------------------------------------------- |
| `tabId` | [`Id`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/Id) |
## Returns
[`QueryRowsCache`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/QueryRowsCache)
IndexesConfig - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / IndexesConfig
# Type Alias: IndexesConfig()
```ts
type IndexesConfig = (create) => ReadonlyArray<Kysely.CreateIndexBuilder<any>>;
```
Defined in: [packages/common/src/local-first/Schema.ts:172](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Schema.ts#L172)
## Parameters
| Parameter | Type |
| --------- | -------------------------------------------- |
| `create` | (`indexName`) => `Kysely.CreateIndexBuilder` |
## Returns
`ReadonlyArray`\<`Kysely.CreateIndexBuilder`\<`any`\>\>
InferColumnErrors - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / InferColumnErrors
# Type Alias: InferColumnErrors\<T, M\>
```ts
type InferColumnErrors<T, M> = {
[Column in keyof MutationMapping<T, M>]: InferErrors<
MutationMapping<T, M>[Column]
>;
}[keyof MutationMapping<T, M>];
```
Defined in: [packages/common/src/local-first/Schema.ts:454](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Schema.ts#L454)
## Type Parameters
| Type Parameter |
| --------------------------------------------------------------------------------------------------------- |
| `T` _extends_ `Record`\<`string`, [`AnyType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/AnyType)\> |
| `M` _extends_ [`MutationKind`](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/MutationKind) |
InferEvoluSchemaError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / InferEvoluSchemaError
# Type Alias: InferEvoluSchemaError\<S\>
```ts
type InferEvoluSchemaError<S> = {
[Table in keyof S]: InferMutationTypeErrors<S[Table]>;
}[keyof S];
```
Defined in: [packages/common/src/local-first/Schema.ts:445](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Schema.ts#L445)
## Type Parameters
| Type Parameter |
| -------------------------------------------------------------------------------------------------- |
| `S` _extends_ [`EvoluSchema`](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/EvoluSchema) |
InferMutationTypeErrors - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / InferMutationTypeErrors
# Type Alias: InferMutationTypeErrors\<T\>
```ts
type InferMutationTypeErrors<T> =
| InferColumnErrors<T, "insert">
| InferColumnErrors<T, "update">
| InferColumnErrors<T, "upsert">;
```
Defined in: [packages/common/src/local-first/Schema.ts:449](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Schema.ts#L449)
## Type Parameters
| Type Parameter |
| --------------------------------------------------------------------------------------------------------- |
| `T` _extends_ `Record`\<`string`, [`AnyType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/AnyType)\> |
InferRow - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / InferRow
# Type Alias: InferRow\<T\>
```ts
type InferRow<T> = T extends Query<infer R> ? R : never;
```
Defined in: [packages/common/src/local-first/Query.ts:97](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Query.ts#L97)
## Type Parameters
| Type Parameter |
| -------------------------------------------------------------------------------------- |
| `T` _extends_ [`Query`](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/Query) |
InfiniteUpperBound - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / InfiniteUpperBound
# Type Alias: InfiniteUpperBound
```ts
type InfiniteUpperBound = typeof InfiniteUpperBound;
```
Defined in: [packages/common/src/local-first/Storage.ts:208](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Storage.ts#L208)
Insertable - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / Insertable
# Type Alias: Insertable\<Props\>
```ts
type Insertable<Props> = InferInput<ObjectType<InsertableProps<Props>>>;
```
Defined in: [packages/common/src/local-first/Schema.ts:360](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Schema.ts#L360)
## Type Parameters
| Type Parameter |
| ------------------------------------------------------------------------------------------------------------- |
| `Props` _extends_ `Record`\<`string`, [`AnyType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/AnyType)\> |
InsertableProps - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / InsertableProps
# Type Alias: InsertableProps\<Props\>
```ts
type InsertableProps<Props> = Omit<NullableToOptionalProps<Props>, "id">;
```
Defined in: [packages/common/src/local-first/Schema.ts:355](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Schema.ts#L355)
## Type Parameters
| Type Parameter |
| ------------------------------------------------------------------------------------------------------------- |
| `Props` _extends_ `Record`\<`string`, [`AnyType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/AnyType)\> |
Millis - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / Millis
# Type Alias: Millis
```ts
type Millis = typeof Type;
```
Defined in: [packages/common/src/local-first/Timestamp.ts:64](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Timestamp.ts#L64)
Mutation - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / Mutation
# Type Alias: Mutation()\<S, Kind\>
```ts
type Mutation<S, Kind> = <TableName>(
table,
props,
options?,
) => Result<
{
id: S[TableName]["id"]["Type"];
},
| ValidMutationSizeError
| MergeObjectTypeErrors<ObjectType<MutationMapping<S[TableName], Kind>>>
>;
```
Defined in: [packages/common/src/local-first/Schema.ts:255](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Schema.ts#L255)
## Type Parameters
| Type Parameter |
| ------------------------------------------------------------------------------------------------------- |
| `S` _extends_ [`EvoluSchema`](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/EvoluSchema) |
| `Kind` _extends_ [`MutationKind`](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/MutationKind) |
## Type Parameters
| Type Parameter |
| ------------------------------- |
| `TableName` _extends_ keyof `S` |
## Parameters
| Parameter | Type |
| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `table` | `TableName` |
| `props` | [`InferInput`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferInput)\<[`ObjectType`](https://evolu.dev/docs/api-reference/common/Type/interfaces/ObjectType)\<[`MutationMapping`](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/MutationMapping)\<`S`\[`TableName`\], `Kind`\>\>\> |
| `options?` | [`MutationOptions`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/MutationOptions) |
## Returns
[`Result`](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result)\<\{
`id`: `S`\[`TableName`\]\[`"id"`\]\[`"Type"`\];
\},
\| [`ValidMutationSizeError`](https://evolu.dev/docs/api-reference/common/Type/interfaces/ValidMutationSizeError)
\| [`MergeObjectTypeErrors`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/MergeObjectTypeErrors)\<[`ObjectType`](https://evolu.dev/docs/api-reference/common/Type/interfaces/ObjectType)\<[`MutationMapping`](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/MutationMapping)\<`S`\[`TableName`\], `Kind`\>\>\>\>
MutationKind - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / MutationKind
# Type Alias: MutationKind
```ts
type MutationKind = "insert" | "update" | "upsert";
```
Defined in: [packages/common/src/local-first/Schema.ts:253](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Schema.ts#L253)
MutationMapping - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / MutationMapping
# Type Alias: MutationMapping\<P, M\>
```ts
type MutationMapping<P, M> = M extends "insert"
? InsertableProps<P>
: M extends "update"
? UpdateableProps<P>
: UpsertableProps<P>;
```
Defined in: [packages/common/src/local-first/Schema.ts:267](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Schema.ts#L267)
## Type Parameters
| Type Parameter |
| --------------------------------------------------------------------------------------------------------- |
| `P` _extends_ `Record`\<`string`, [`AnyType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/AnyType)\> |
| `M` _extends_ [`MutationKind`](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/MutationKind) |
NodeId - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / NodeId
# Type Alias: NodeId
```ts
type NodeId = typeof Type;
```
Defined in: [packages/common/src/local-first/Timestamp.ts:107](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Timestamp.ts#L107)
OwnerEncryptionKey - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / OwnerEncryptionKey
# Type Alias: OwnerEncryptionKey
```ts
type OwnerEncryptionKey = typeof Type;
```
Defined in: [packages/common/src/local-first/Owner.ts:90](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Owner.ts#L90)
OwnerId - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / OwnerId
# Type Alias: OwnerId
```ts
type OwnerId = typeof Type;
```
Defined in: [packages/common/src/local-first/Owner.ts:72](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Owner.ts#L72)
OwnerIdBytes - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / OwnerIdBytes
# Type Alias: OwnerIdBytes
```ts
type OwnerIdBytes = typeof Type;
```
Defined in: [packages/common/src/local-first/Owner.ts:76](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Owner.ts#L76)
OwnerSecret - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / OwnerSecret
# Type Alias: OwnerSecret
```ts
type OwnerSecret = typeof Type;
```
Defined in: [packages/common/src/local-first/Owner.ts:116](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Owner.ts#L116)
OwnerTransport - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / OwnerTransport
# Type Alias: OwnerTransport
```ts
type OwnerTransport = OwnerWebSocketTransport;
```
Defined in: [packages/common/src/local-first/Owner.ts:299](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Owner.ts#L299)
Transport configuration for connecting to relays.
Currently only WebSocket, in the future Bluetooth, LocalNetwork, etc.
OwnerWriteKey - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / OwnerWriteKey
# Type Alias: OwnerWriteKey
```ts
type OwnerWriteKey = typeof Type;
```
Defined in: [packages/common/src/local-first/Owner.ts:97](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Owner.ts#L97)
Patch - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / Patch
# Type Alias: Patch
```ts
type Patch = ReplaceAllPatch | ReplaceAtPatch;
```
Defined in: [packages/common/src/local-first/Query.ts:237](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Query.ts#L237)
Queries - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / Queries
# Type Alias: Queries\<R\>
```ts
type Queries<R> = ReadonlyArray<Query<R>>;
```
Defined in: [packages/common/src/local-first/Query.ts:114](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Query.ts#L114)
## Type Parameters
| Type Parameter | Default type |
| -------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
| `R` _extends_ [`Row`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Row) | [`Row`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Row) |
QueriesToQueryRows - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / QueriesToQueryRows
# Type Alias: QueriesToQueryRows\<Q\>
```ts
type QueriesToQueryRows<Q> = {
[P in keyof Q]: Q[P] extends Query<infer R> ? QueryRows<R> : never;
};
```
Defined in: [packages/common/src/local-first/Query.ts:116](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Query.ts#L116)
## Type Parameters
| Type Parameter |
| ------------------------------------------------------------------------------------------ |
| `Q` _extends_ [`Queries`](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/Queries) |
QueriesToQueryRowsPromises - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / QueriesToQueryRowsPromises
# Type Alias: QueriesToQueryRowsPromises\<Q\>
```ts
type QueriesToQueryRowsPromises<Q> = {
[P in keyof Q]: Q[P] extends Query<infer R> ? Promise<QueryRows<R>> : never;
};
```
Defined in: [packages/common/src/local-first/Query.ts:120](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Query.ts#L120)
## Type Parameters
| Type Parameter |
| ------------------------------------------------------------------------------------------ |
| `Q` _extends_ [`Queries`](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/Queries) |
Query - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / Query
# Type Alias: Query\<R\>
```ts
type Query<R> = string & Brand<"Query"> & object;
```
Defined in: [packages/common/src/local-first/Query.ts:38](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Query.ts#L38)
A type-safe SQL query.
### Example
```ts
const allTodos = evolu.createQuery((db) => db.selectFrom("todo").selectAll());
type AllTodosRow = typeof allTodos.Row;
```
## Type Declaration
| Name | Type | Description | Defined in |
| ----- | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Row` | `R` | A shorthand for [InferRow](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/InferRow). ### Example `const allTodos = evolu.createQuery((db) => db.selectFrom("todo").selectAll(), ); type AllTodosRow = typeof allTodos.Row;` | [packages/common/src/local-first/Query.ts:52](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Query.ts#L52) |
## Type Parameters
| Type Parameter | Default type |
| -------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
| `R` _extends_ [`Row`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Row) | [`Row`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Row) |
QueryRows - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / QueryRows
# Type Alias: QueryRows\<R\>
```ts
type QueryRows<R> = ReadonlyArray<Readonly<Simplify<R>>>;
```
Defined in: [packages/common/src/local-first/Query.ts:110](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Query.ts#L110)
Rows returned by a query.
## Type Parameters
| Type Parameter | Default type |
| -------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
| `R` _extends_ [`Row`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Row) | [`Row`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Row) |
QueryRowsMap - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / QueryRowsMap
# Type Alias: QueryRowsMap
```ts
type QueryRowsMap = ReadonlyMap<Query, ReadonlyArray<Row>>;
```
Defined in: [packages/common/src/local-first/Query.ts:124](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Query.ts#L124)
Range - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / Range
# Type Alias: Range
```ts
type Range = SkipRange | FingerprintRange | TimestampsRange;
```
Defined in: [packages/common/src/local-first/Storage.ts:233](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Storage.ts#L233)
RangeType - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / RangeType
# Type Alias: RangeType
```ts
type RangeType = (typeof RangeType)[keyof typeof RangeType];
```
Defined in: [packages/common/src/local-first/Storage.ts:211](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Storage.ts#L211)
RangeUpperBound - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / RangeUpperBound
# Type Alias: RangeUpperBound
```ts
type RangeUpperBound = TimestampBytes | InfiniteUpperBound;
```
Defined in: [packages/common/src/local-first/Storage.ts:206](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Storage.ts#L206)
Union type for Range's upperBound: either a [TimestampBytes](https://evolu.dev/docs/api-reference/common/local-first/variables/TimestampBytes) or
[InfiniteUpperBound](https://evolu.dev/docs/api-reference/common/local-first/variables/InfiniteUpperBound).
ReloadApp - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / ReloadApp
# Type Alias: ReloadApp()
```ts
type ReloadApp = (url) => void;
```
Defined in: [packages/common/src/local-first/Platform.ts:23](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Platform.ts#L23)
Reload the app in a platform-specific way.
- **Web**: Redirects to the specified URL
- **React Native**: Restarts the app (URL parameter ignored)
## Parameters
| Parameter | Type |
| --------- | -------- |
| `url` | `string` |
## Returns
`void`
SchemaValidationError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / SchemaValidationError
# Type Alias: SchemaValidationError\<Message\>
```ts
type SchemaValidationError<Message> = `❌ Schema Error: ${Message}`;
```
Defined in: [packages/common/src/local-first/Schema.ts:169](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Schema.ts#L169)
Schema validation error that shows clear, readable messages
## Type Parameters
| Type Parameter |
| ---------------------------- |
| `Message` _extends_ `string` |
SqliteStorageDeps - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / SqliteStorageDeps
# Type Alias: SqliteStorageDeps
```ts
type SqliteStorageDeps = RandomDep & SqliteDep;
```
Defined in: [packages/common/src/local-first/Storage.ts:356](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Storage.ts#L356)
StorageInsertTimestampStrategy - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / StorageInsertTimestampStrategy
# Type Alias: StorageInsertTimestampStrategy
```ts
type StorageInsertTimestampStrategy = "append" | "prepend" | "insert";
```
Defined in: [packages/common/src/local-first/Storage.ts:590](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Storage.ts#L590)
SyncState - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / SyncState
# Type Alias: SyncState
```ts
type SyncState =
| SyncStateInitial
| SyncStateIsSyncing
| SyncStateIsSynced
| SyncStateIsNotSynced;
```
Defined in: [packages/common/src/local-first/Sync.ts:908](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Sync.ts#L908)
TODO: Rework for the new owners API.
The possible states of a synchronization process. The `SyncState` can be one
of the following:
- [SyncStateInitial](https://evolu.dev/docs/api-reference/common/local-first/interfaces/SyncStateInitial)
- [SyncStateIsSyncing](https://evolu.dev/docs/api-reference/common/local-first/interfaces/SyncStateIsSyncing)
- [SyncStateIsSynced](https://evolu.dev/docs/api-reference/common/local-first/interfaces/SyncStateIsSynced)
- [SyncStateIsNotSynced](https://evolu.dev/docs/api-reference/common/local-first/interfaces/SyncStateIsNotSynced)
SystemColumns - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / SystemColumns
# Type Alias: SystemColumns
```ts
type SystemColumns = typeof Type;
```
Defined in: [packages/common/src/local-first/Schema.ts:239](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Schema.ts#L239)
TimestampBytes - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / TimestampBytes
# Type Alias: TimestampBytes
```ts
type TimestampBytes = typeof Type;
```
Defined in: [packages/common/src/local-first/Timestamp.ts:280](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Timestamp.ts#L280)
TimestampError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / TimestampError
# Type Alias: TimestampError
```ts
type TimestampError =
| TimestampDriftError
| TimestampCounterOverflowError
| TimestampTimeOutOfRangeError;
```
Defined in: [packages/common/src/local-first/Timestamp.ts:33](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Timestamp.ts#L33)
UnuseOwner - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / UnuseOwner
# Type Alias: UnuseOwner()
```ts
type UnuseOwner = () => void;
```
Defined in: [packages/common/src/local-first/Evolu.ts:458](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Evolu.ts#L458)
Function returned by [Evolu#useOwner](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Evolu.mdx#useowner) to stop using an [SyncOwner](https://evolu.dev/docs/api-reference/common/local-first/interfaces/SyncOwner).
## Returns
`void`
Updateable - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / Updateable
# Type Alias: Updateable\<Props\>
```ts
type Updateable<Props> = InferInput<ObjectType<UpdateableProps<Props>>>;
```
Defined in: [packages/common/src/local-first/Schema.ts:397](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Schema.ts#L397)
## Type Parameters
| Type Parameter |
| ------------------------------------------------------------------------------------------------------------- |
| `Props` _extends_ `Record`\<`string`, [`AnyType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/AnyType)\> |
UpdateableProps - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / UpdateableProps
# Type Alias: UpdateableProps\<Props\>
```ts
type UpdateableProps<Props> = {
[K in keyof Props]: K extends "id" ? Props[K] : OptionalType<Props[K]>;
} & object;
```
Defined in: [packages/common/src/local-first/Schema.ts:393](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Schema.ts#L393)
## Type Declaration
| Name | Type | Defined in |
| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `isDeleted` | [`OptionalType`](https://evolu.dev/docs/api-reference/common/Type/interfaces/OptionalType)\<_typeof_ [`SqliteBoolean`](https://evolu.dev/docs/api-reference/common/Sqlite/variables/SqliteBoolean)\> | [packages/common/src/local-first/Schema.ts:395](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Schema.ts#L395) |
## Type Parameters
| Type Parameter |
| ------------------------------------------------------------------------------------------------------------- |
| `Props` _extends_ `Record`\<`string`, [`AnyType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/AnyType)\> |
Upsertable - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / Upsertable
# Type Alias: Upsertable\<Props\>
```ts
type Upsertable<Props> = InferInput<ObjectType<UpsertableProps<Props>>>;
```
Defined in: [packages/common/src/local-first/Schema.ts:441](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Schema.ts#L441)
## Type Parameters
| Type Parameter |
| ------------------------------------------------------------------------------------------------------------- |
| `Props` _extends_ `Record`\<`string`, [`AnyType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/AnyType)\> |
UpsertableProps - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / UpsertableProps
# Type Alias: UpsertableProps\<Props\>
```ts
type UpsertableProps<Props> = NullableToOptionalProps<Props & object>;
```
Defined in: [packages/common/src/local-first/Schema.ts:434](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Schema.ts#L434)
## Type Parameters
| Type Parameter |
| ------------------------------------------------------------------------------------------------------------- |
| `Props` _extends_ `Record`\<`string`, [`AnyType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/AnyType)\> |
ValidDbChangeValues - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / ValidDbChangeValues
# Type Alias: ValidDbChangeValues
```ts
type ValidDbChangeValues = typeof Type;
```
Defined in: [packages/common/src/local-first/Storage.ts:259](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Storage.ts#L259)
ValidateColumnTypes - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / ValidateColumnTypes
# Type Alias: ValidateColumnTypes\<S\>
```ts
type ValidateColumnTypes<S> = keyof S extends infer TableName
? TableName extends keyof S
? keyof S[TableName] extends infer ColumnName
? ColumnName extends keyof S[TableName]
? InferType<S[TableName][ColumnName]> extends SqliteValue
? never
: SchemaValidationError<`Table "${TableName & string}" column "${ColumnName & string}" type is not compatible with SQLite. Column types must extend SqliteValue (string, number, Uint8Array, or null).`>
: never
: never
: never
: never;
```
Defined in: [packages/common/src/local-first/Schema.ts:155](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Schema.ts#L155)
## Type Parameters
| Type Parameter |
| -------------------------------------------------------------------------------------------------- |
| `S` _extends_ [`EvoluSchema`](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/EvoluSchema) |
ValidateIdColumnType - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / ValidateIdColumnType
# Type Alias: ValidateIdColumnType\<S\>
```ts
type ValidateIdColumnType<S> = keyof S extends infer TableName
? TableName extends keyof S
? "id" extends keyof S[TableName]
? S[TableName]["id"] extends TableId<any>
? never
: SchemaValidationError<`Table "${TableName & string}" id column must be a branded ID type (created with id("${TableName & string}")).`>
: never
: never
: never;
```
Defined in: [packages/common/src/local-first/Schema.ts:127](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Schema.ts#L127)
## Type Parameters
| Type Parameter |
| -------------------------------------------------------------------------------------------------- |
| `S` _extends_ [`EvoluSchema`](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/EvoluSchema) |
ValidateNoSystemColumns - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / ValidateNoSystemColumns
# Type Alias: ValidateNoSystemColumns\<S\>
```ts
type ValidateNoSystemColumns<S> = keyof S extends infer TableName
? TableName extends keyof S
? keyof S[TableName] extends infer ColumnName
? ColumnName extends keyof S[TableName]
? ColumnName extends "createdAt" | "updatedAt" | "isDeleted" | "ownerId"
? SchemaValidationError<`Table "${TableName & string}" uses system column name "${ColumnName & string}". System columns (createdAt, updatedAt, isDeleted, ownerId) are added automatically.`>
: never
: never
: never
: never
: never;
```
Defined in: [packages/common/src/local-first/Schema.ts:138](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Schema.ts#L138)
## Type Parameters
| Type Parameter |
| -------------------------------------------------------------------------------------------------- |
| `S` _extends_ [`EvoluSchema`](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/EvoluSchema) |
ValidateSchema - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / ValidateSchema
# Type Alias: ValidateSchema\<S\>
```ts
type ValidateSchema<S> =
ValidateSchemaHasId<S> extends never
? ValidateIdColumnType<S> extends never
? ValidateNoSystemColumns<S> extends never
? ValidateColumnTypes<S> extends never
? S
: ValidateColumnTypes<S>
: ValidateNoSystemColumns<S>
: ValidateIdColumnType<S>
: ValidateSchemaHasId<S>;
```
Defined in: [packages/common/src/local-first/Schema.ts:107](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Schema.ts#L107)
Validates an [EvoluSchema](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/EvoluSchema) at compile time, returning the first error
found as a readable string literal type. This approach provides much clearer
and more actionable TypeScript errors than the default, which are often hard
to read.
Validates the following schema requirements:
1. All tables must have an 'id' column
2. The 'id' column must be a branded ID type (created with id() function)
3. Tables cannot use system column names (createdAt, updatedAt, isDeleted)
4. All column types must be compatible with SQLite (extend SqliteValue)
## Type Parameters
| Type Parameter |
| -------------------------------------------------------------------------------------------------- |
| `S` _extends_ [`EvoluSchema`](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/EvoluSchema) |
ValidateSchemaHasId - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / ValidateSchemaHasId
# Type Alias: ValidateSchemaHasId\<S\>
```ts
type ValidateSchemaHasId<S> = keyof S extends infer TableName
? TableName extends keyof S
? "id" extends keyof S[TableName]
? never
: SchemaValidationError<`Table "${TableName & string}" is missing required id column.`>
: never
: never;
```
Defined in: [packages/common/src/local-first/Schema.ts:118](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Schema.ts#L118)
## Type Parameters
| Type Parameter |
| -------------------------------------------------------------------------------------------------- |
| `S` _extends_ [`EvoluSchema`](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/EvoluSchema) |
Counter - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / Counter
# Variable: Counter
```ts
const Counter: BrandType<
BrandType<
Type<
"Brand",
number & Brand<"Int"> & Brand<"NonNegative">,
number,
NonNegativeError,
number & Brand<"Int">,
IntError | NumberError
>,
"LessThanOrEqualTo65535",
LessThanOrEqualToError<65535>,
NonNegativeError | IntError | NumberError
>,
"Counter",
BrandWithoutRefineError<
"Counter",
NonNegativeError | IntError | NumberError | LessThanOrEqualToError<65535>
>,
never
>;
```
Defined in: [packages/common/src/local-first/Timestamp.ts:73](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Timestamp.ts#L73)
DbChange - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / DbChange
# Variable: DbChange
```ts
const DbChange: ObjectType<{
id: BrandType<
Type<"String", string, string, StringError, string, StringError>,
"Id",
IdError,
StringError
>;
isDelete: UnionType<
[
Type<"Null", null, null, NullError, null, NullError>,
Type<"Boolean", boolean, boolean, BooleanError, boolean, BooleanError>,
]
>;
isInsert: Type<
"Boolean",
boolean,
boolean,
BooleanError,
boolean,
BooleanError
>;
table: Type<"String", string, string, StringError, string, StringError>;
values: BrandType<
RecordType<
"String",
string,
string,
StringError,
string,
StringError,
UnionType<
[
Type<"Null", null, null, NullError, null, NullError>,
Type<"String", string, string, StringError, string, StringError>,
Type<"Number", number, number, NumberError, number, NumberError>,
Type<
"Uint8Array",
Uint8Array<ArrayBufferLike>,
Uint8Array<ArrayBufferLike>,
Uint8ArrayError,
Uint8Array<ArrayBufferLike>,
Uint8ArrayError
>,
]
>
>,
"ValidDbChangeValues",
ValidDbChangeValuesError,
| RecordError<StringError, never>
| RecordError<
StringError,
UnionError<StringError | NumberError | Uint8ArrayError | NullError>
>
>;
}>;
```
Defined in: [packages/common/src/local-first/Storage.ts:284](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Storage.ts#L284)
A DbChange is a change to a table row. Together with a unique
[Timestamp](https://evolu.dev/docs/api-reference/common/local-first/variables/Timestamp), it forms a [CrdtMessage](https://evolu.dev/docs/api-reference/common/local-first/interfaces/CrdtMessage).
DbChangeValues - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / DbChangeValues
# Variable: DbChangeValues
```ts
const DbChangeValues: RecordType<
"String",
string,
string,
StringError,
string,
StringError,
UnionType<
[
Type<"Null", null, null, NullError, null, NullError>,
Type<"String", string, string, StringError, string, StringError>,
Type<"Number", number, number, NumberError, number, NumberError>,
Type<
"Uint8Array",
Uint8Array<ArrayBufferLike>,
Uint8Array<ArrayBufferLike>,
Uint8ArrayError,
Uint8Array<ArrayBufferLike>,
Uint8ArrayError
>,
]
>
>;
```
Defined in: [packages/common/src/local-first/Storage.ts:256](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Storage.ts#L256)
DbIndex - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / DbIndex
# Variable: DbIndex
```ts
const DbIndex: ObjectType<{
name: Type<"String", string, string, StringError, string, StringError>;
sql: Type<"String", string, string, StringError, string, StringError>;
}>;
```
Defined in: [packages/common/src/local-first/Schema.ts:463](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Schema.ts#L463)
DbSchema - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / DbSchema
# Variable: DbSchema
```ts
const DbSchema: ObjectType<{
indexes: ArrayType<
ObjectType<{
name: Type<"String", string, string, StringError, string, StringError>;
sql: Type<"String", string, string, StringError, string, StringError>;
}>
>;
tables: RecordType<
"String",
string,
string,
StringError,
string,
StringError,
SetType<Type<"String", string, string, StringError, string, StringError>>
>;
}>;
```
Defined in: [packages/common/src/local-first/Schema.ts:466](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Schema.ts#L466)
InfiniteUpperBound - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / InfiniteUpperBound
# Variable: InfiniteUpperBound
```ts
const InfiniteUpperBound: typeof InfiniteUpperBound;
```
Defined in: [packages/common/src/local-first/Storage.ts:208](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Storage.ts#L208)
Millis - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / Millis
# Variable: Millis
```ts
const Millis: BrandType<
BrandType<
Type<
"Brand",
number & Brand<"Int"> & Brand<"NonNegative">,
number,
NonNegativeError,
number & Brand<"Int">,
IntError | NumberError
>,
`LessThanOrEqualTo${number}`,
LessThanOrEqualToError<number>,
NonNegativeError | IntError | NumberError
>,
"Millis",
BrandWithoutRefineError<
"Millis",
NonNegativeError | IntError | NumberError | LessThanOrEqualToError<number>
>,
never
>;
```
Defined in: [packages/common/src/local-first/Timestamp.ts:64](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Timestamp.ts#L64)
Millis is a timestamp in milliseconds, like `Date.now()`, but limited to the
maximum value representable in 6 bytes (281474976710655) minus 1 (reserved
for infinity). This enables more efficient binary serialization, saving 2
bytes compared to the typical 8-byte (64-bit) timestamp representation.
This limit is enforced to prevent data corruption. If a device's clock
exceeds this range, Evolu will stop saving data until the clock is
corrected.
`new Date(281474976710654).toString()` = Tue Aug 02 10889 07:31:49
NodeId - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / NodeId
# Variable: NodeId
```ts
const NodeId: BrandType<
Type<"String", string, string, StringError, string, StringError>,
"NodeId",
RegexError<"NodeId">,
StringError
>;
```
Defined in: [packages/common/src/local-first/Timestamp.ts:107](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Timestamp.ts#L107)
A NodeId uniquely identifies an owner's device. Generated once per device
using cryptographic randomness.
Collision probability (birthday paradox):
- 1,000 devices: ~0.00000000000271% (negligible).
- 1M devices: ~0.00000271% (1 in 37M chance).
- 135M devices: ~1% chance.
- 4.29B devices: ~50% chance.
https://lemire.me/blog/2019/12/12/are-64-bit-random-identifiers-free-from-collision
What happens if different devices generate the same NodeId?
If devices with the same NodeId use different owners, no issues occur.
If devices with the same NodeId use the same owner, problems only arise when
they generate CRDT messages with identical timestamps (same millis, counter,
and NodeId). In this case, the protocol sync algorithm treats them as the
same message: the first will be synced with the relay, while the affected
message will not be delivered. The affected devices will see different data
yet they will think they are synced. This is extremely rare and can be
resolved by resetting one device to generate a new NodeId.
OwnerEncryptionKey - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / OwnerEncryptionKey
# Variable: OwnerEncryptionKey
```ts
const OwnerEncryptionKey: BrandType<
BrandType<
BrandType<
Type<
"Brand",
Uint8Array<ArrayBufferLike> & Brand<"Entropy">,
Uint8Array<ArrayBufferLike>,
BrandWithoutRefineError<"Entropy", Uint8ArrayError>,
Uint8Array<ArrayBufferLike>,
never
>,
"Length32",
LengthError<32>,
BrandWithoutRefineError<"Entropy", Uint8ArrayError>
>,
"EncryptionKey",
BrandWithoutRefineError<
"EncryptionKey",
BrandWithoutRefineError<"Entropy", Uint8ArrayError> | LengthError<32>
>,
never
>,
"OwnerEncryptionKey",
BrandWithoutRefineError<
"OwnerEncryptionKey",
BrandWithoutRefineError<
"EncryptionKey",
BrandWithoutRefineError<"Entropy", Uint8ArrayError> | LengthError<32>
>
>,
never
>;
```
Defined in: [packages/common/src/local-first/Owner.ts:90](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Owner.ts#L90)
Symmetric encryption key for [Owner](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Owner) data protection.
OwnerId - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / OwnerId
# Variable: OwnerId
```ts
const OwnerId: BrandType<
BrandType<
Type<"String", string, string, StringError, string, StringError>,
"Id",
IdError,
StringError
>,
"OwnerId",
BrandWithoutRefineError<"OwnerId", StringError | IdError>,
never
>;
```
Defined in: [packages/common/src/local-first/Owner.ts:72](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Owner.ts#L72)
OwnerId is a branded [Id](https://evolu.dev/docs/api-reference/common/Type/variables/Id) that uniquely identifies an [Owner](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Owner).
OwnerIdBytes - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / OwnerIdBytes
# Variable: OwnerIdBytes
```ts
const OwnerIdBytes: BrandType<
BrandType<
BrandType<
Type<
"Uint8Array",
Uint8Array<ArrayBufferLike>,
Uint8Array<ArrayBufferLike>,
Uint8ArrayError,
Uint8Array<ArrayBufferLike>,
Uint8ArrayError
>,
"Length16",
LengthError<16>,
Uint8ArrayError
>,
"IdBytes",
BrandWithoutRefineError<"IdBytes", LengthError<16> | Uint8ArrayError>,
never
>,
"OwnerIdBytes",
BrandWithoutRefineError<
"OwnerIdBytes",
BrandWithoutRefineError<"IdBytes", LengthError<16> | Uint8ArrayError>
>,
never
>;
```
Defined in: [packages/common/src/local-first/Owner.ts:76](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Owner.ts#L76)
Bytes representation of [OwnerId](https://evolu.dev/docs/api-reference/common/local-first/variables/OwnerId).
OwnerSecret - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / OwnerSecret
# Variable: OwnerSecret
```ts
const OwnerSecret: BrandType<
BrandType<
Type<
"Brand",
Uint8Array<ArrayBufferLike> & Brand<"Entropy">,
Uint8Array<ArrayBufferLike>,
BrandWithoutRefineError<"Entropy", Uint8ArrayError>,
Uint8Array<ArrayBufferLike>,
never
>,
"Length32",
LengthError<32>,
BrandWithoutRefineError<"Entropy", Uint8ArrayError>
>,
"OwnerSecret",
BrandWithoutRefineError<
"OwnerSecret",
BrandWithoutRefineError<"Entropy", Uint8ArrayError> | LengthError<32>
>,
never
>;
```
Defined in: [packages/common/src/local-first/Owner.ts:116](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Owner.ts#L116)
32 bytes of cryptographic entropy used to derive [Owner](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Owner) keys.
Can be created using [createOwnerSecret](https://evolu.dev/docs/api-reference/common/local-first/functions/createOwnerSecret) or converted from a
[Mnemonic](https://evolu.dev/docs/api-reference/common/Type/variables/Mnemonic) using [mnemonicToOwnerSecret](https://evolu.dev/docs/api-reference/common/local-first/functions/mnemonicToOwnerSecret).
OwnerWriteKey - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / OwnerWriteKey
# Variable: OwnerWriteKey
```ts
const OwnerWriteKey: BrandType<
BrandType<
Type<
"Brand",
Uint8Array<ArrayBufferLike> & Brand<"Entropy">,
Uint8Array<ArrayBufferLike>,
BrandWithoutRefineError<"Entropy", Uint8ArrayError>,
Uint8Array<ArrayBufferLike>,
never
>,
"Length16",
LengthError<16>,
BrandWithoutRefineError<"Entropy", Uint8ArrayError>
>,
"OwnerWriteKey",
BrandWithoutRefineError<
"OwnerWriteKey",
LengthError<16> | BrandWithoutRefineError<"Entropy", Uint8ArrayError>
>,
never
>;
```
Defined in: [packages/common/src/local-first/Owner.ts:97](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Owner.ts#L97)
A secure token for write operations. It's derived from [OwnerSecret](https://evolu.dev/docs/api-reference/common/local-first/variables/OwnerSecret) by
default and can be rotated via [createOwnerWriteKey](https://evolu.dev/docs/api-reference/common/local-first/functions/createOwnerWriteKey).
RangeType - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / RangeType
# Variable: RangeType
```ts
const RangeType: object;
```
Defined in: [packages/common/src/local-first/Storage.ts:211](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Storage.ts#L211)
## Type Declaration
| Name | Type | Default value | Defined in |
| -------------------------------------- | ---- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="fingerprint"></a> `Fingerprint` | `1` | `1` | [packages/common/src/local-first/Storage.ts:212](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Storage.ts#L212) |
| <a id="skip"></a> `Skip` | `0` | `0` | [packages/common/src/local-first/Storage.ts:213](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Storage.ts#L213) |
| <a id="timestamps"></a> `Timestamps` | `2` | `2` | [packages/common/src/local-first/Storage.ts:214](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Storage.ts#L214) |
SystemColumns-1 - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / SystemColumns
# Variable: SystemColumns
```ts
const SystemColumns: ObjectType<{
createdAt: BrandType<
Type<"String", string, string, StringError, string, StringError>,
"DateIso",
DateIsoError,
StringError
>;
isDeleted: UnionType<
[
Type<"Null", null, null, NullError, null, NullError>,
UnionType<[LiteralType<0>, LiteralType<1>]>,
]
>;
ownerId: BrandType<
BrandType<
Type<"String", string, string, StringError, string, StringError>,
"Id",
IdError,
StringError
>,
"OwnerId",
BrandWithoutRefineError<"OwnerId", StringError | IdError>,
never
>;
updatedAt: BrandType<
Type<"String", string, string, StringError, string, StringError>,
"DateIso",
DateIsoError,
StringError
>;
}>;
```
Defined in: [packages/common/src/local-first/Schema.ts:239](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Schema.ts#L239)
System columns that are implicitly defined by Evolu.
- `createdAt`: Set by Evolu on row creation, derived from [Timestamp](https://evolu.dev/docs/api-reference/common/local-first/variables/Timestamp).
- `updatedAt`: Set by Evolu on every row change, derived from [Timestamp](https://evolu.dev/docs/api-reference/common/local-first/variables/Timestamp).
- `isDeleted`: Soft delete flag created by Evolu and used by the developer to
mark rows as deleted.
- `ownerId`: Represents ownership and logically partitions the database.
Timestamp - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / Timestamp
# Variable: Timestamp
```ts
const Timestamp: ObjectType<{
counter: BrandType<
BrandType<
Type<
"Brand",
number & Brand<"Int"> & Brand<"NonNegative">,
number,
NonNegativeError,
number & Brand<"Int">,
IntError | NumberError
>,
"LessThanOrEqualTo65535",
LessThanOrEqualToError<65535>,
NonNegativeError | IntError | NumberError
>,
"Counter",
BrandWithoutRefineError<
"Counter",
NonNegativeError | IntError | NumberError | LessThanOrEqualToError<65535>
>,
never
>;
millis: BrandType<
BrandType<
Type<
"Brand",
number & Brand<"Int"> & Brand<"NonNegative">,
number,
NonNegativeError,
number & Brand<"Int">,
IntError | NumberError
>,
`LessThanOrEqualTo${number}`,
LessThanOrEqualToError<number>,
NonNegativeError | IntError | NumberError
>,
"Millis",
BrandWithoutRefineError<
"Millis",
NonNegativeError | IntError | NumberError | LessThanOrEqualToError<number>
>,
never
>;
nodeId: BrandType<
Type<"String", string, string, StringError, string, StringError>,
"NodeId",
RegexError<"NodeId">,
StringError
>;
}>;
```
Defined in: [packages/common/src/local-first/Timestamp.ts:169](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Timestamp.ts#L169)
Hybrid Logical Clock timestamp.
Timestamps serve as globally unique, causally ordered identifiers for CRDT
messages in Evolu's sync protocol.
### Why Hybrid Logical Clocks
Evolu uses Hybrid Logical Clocks (HLC), which combine physical time (millis)
with a logical counter. This hybrid approach preserves causality like logical
clocks while staying close to physical time for better human
interpretability.
The counter component ensures causality is maintained even when physical
clocks are imperfect. When clocks drift or operations occur concurrently, the
counter increments to establish a total order. This means Evolu achieves
well-defined, eventually-consistent behavior regardless of physical clock
accuracy.
Vector clocks can accurately track causality and detect concurrent
operations, but they require unbounded space in peer-to-peer systems and
crucially, still don't solve our fundamental problem: when they detect
operations as concurrent, we still need a deterministic way to choose a
winner. Additionally, any deterministic conflict resolution can be gamed by
malicious actors.
HLC timestamps work well in practice because modern device clocks accurately
reflect the order of sequential edits in the common case. Evolu's `maxDrift`
configuration protects against buggy clocks and prevents problematic
future-dated entries from propagating through the network.
### References
- https://muratbuffalo.blogspot.com/2014/07/hybrid-logical-clocks.html
- https://sergeiturukin.com/2017/06/26/hybrid-logical-clocks.html
- https://jaredforsyth.com/posts/hybrid-logical-clocks/
- https://willowprotocol.org/more/timestamps_really/index.html
### Privacy Considerations
Timestamps are metadata visible to relays and collaborators. While it can be
considered a privacy leak, let us explain why it's necessary, and how to
avoid it if maximum privacy is required.
With real-time communication, participants always see activity (receiving
bytes). We cannot trust anyone not to store that information, so explicitly
exposing timestamps doesn't add additional risk.
If we really want not to leak user activity, we can implement a local write
queue:
1. Write changes immediately to a local-only table
2. Periodically and randomly flush messages to sync tables
**Trade-off:** It breaks real-time collaboration.
TimestampBytes - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / TimestampBytes
# Variable: TimestampBytes
```ts
const TimestampBytes: BrandType<
Type<
"Uint8Array",
Uint8Array<ArrayBufferLike>,
Uint8Array<ArrayBufferLike>,
Uint8ArrayError,
Uint8Array<ArrayBufferLike>,
Uint8ArrayError
>,
"TimestampBytes",
BrandWithoutRefineError<"TimestampBytes", Uint8ArrayError>,
never
>;
```
Defined in: [packages/common/src/local-first/Timestamp.ts:280](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Timestamp.ts#L280)
Sortable bytes representation of [Timestamp](https://evolu.dev/docs/api-reference/common/local-first/variables/Timestamp).
ValidDbChangeValues - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / ValidDbChangeValues
# Variable: ValidDbChangeValues
```ts
const ValidDbChangeValues: BrandType<
RecordType<
"String",
string,
string,
StringError,
string,
StringError,
UnionType<
[
Type<"Null", null, null, NullError, null, NullError>,
Type<"String", string, string, StringError, string, StringError>,
Type<"Number", number, number, NumberError, number, NumberError>,
Type<
"Uint8Array",
Uint8Array<ArrayBufferLike>,
Uint8Array<ArrayBufferLike>,
Uint8ArrayError,
Uint8Array<ArrayBufferLike>,
Uint8ArrayError
>,
]
>
>,
"ValidDbChangeValues",
ValidDbChangeValuesError,
| RecordError<StringError, never>
| RecordError<
StringError,
UnionError<StringError | NumberError | Uint8ArrayError | NullError>
>
>;
```
Defined in: [packages/common/src/local-first/Storage.ts:259](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Storage.ts#L259)
defaultDbConfig - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / defaultDbConfig
# Variable: defaultDbConfig
```ts
const defaultDbConfig: DbConfig;
```
Defined in: [packages/common/src/local-first/Db.ts:214](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Db.ts#L214)
emptyRows - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / emptyRows
# Variable: emptyRows
```ts
const emptyRows: ReadonlyArray<Row> = [];
```
Defined in: [packages/common/src/local-first/Query.ts:107](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Query.ts#L107)
eqTimestamp - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / eqTimestamp
# Variable: eqTimestamp
```ts
const eqTimestamp: Eq<{
counter: number &
Brand<"Int"> &
Brand<"NonNegative"> &
Brand<"LessThanOrEqualTo65535"> &
Brand<"Counter">;
millis: number &
Brand<"Int"> &
Brand<"NonNegative"> &
Brand<`LessThanOrEqualTo${number}`> &
Brand<"Millis">;
nodeId: string & Brand<"NodeId">;
}>;
```
Defined in: [packages/common/src/local-first/Timestamp.ts:177](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Timestamp.ts#L177)
Equality function for comparing [Timestamp](https://evolu.dev/docs/api-reference/common/local-first/variables/Timestamp).
fingerprintSize - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / fingerprintSize
# Variable: fingerprintSize
```ts
const fingerprintSize: number & Brand<"Int"> & Brand<"NonNegative">;
```
Defined in: [packages/common/src/local-first/Storage.ts:193](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Storage.ts#L193)
initialSyncState - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / initialSyncState
# Variable: initialSyncState
```ts
const initialSyncState: SyncStateInitial;
```
Defined in: [packages/common/src/local-first/Sync.ts:949](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Sync.ts#L949)
kysely - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / kysely
# Variable: kysely
```ts
const kysely: Kysely<unknown>;
```
Defined in: [packages/common/src/local-first/Schema.ts:623](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Schema.ts#L623)
kyselyJsonIdentifier - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / kyselyJsonIdentifier
# Variable: kyselyJsonIdentifier
```ts
const kyselyJsonIdentifier: string & Brand<"Id">;
```
Defined in: [packages/common/src/local-first/Query.ts:325](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Query.ts#L325)
A unique identifier prepended to JSON-encoded strings. This allows safe
detection and parsing of only those columns that require JSON.parse.
The identifier is a cryptographically random Evolu Id, ensuring uniqueness
and preventing malicious actors from inserting fake data that could be
misinterpreted as JSON by the application.
Note: The same queries created by different browser tabs will have different
identifiers and thus be considered different and cached separately. This is
usually not a big deal, but if needed, the DB cache can be optimized by
passing the kyselyJsonIdentifier into the DB worker during initialization,
allowing queries to be grouped and recognized across tabs or sessions.
See: https://github.com/kysely-org/kysely/issues/1372#issuecomment-2702773948
maxCounter - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / maxCounter
# Variable: maxCounter
```ts
const maxCounter: number &
Brand<"Int"> &
Brand<"NonNegative"> &
Brand<"LessThanOrEqualTo65535"> &
Brand<"Counter">;
```
Defined in: [packages/common/src/local-first/Timestamp.ts:80](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Timestamp.ts#L80)
maxMillis - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / maxMillis
# Variable: maxMillis
```ts
const maxMillis: number &
Brand<"Int"> &
Brand<"NonNegative"> &
Brand<`LessThanOrEqualTo${number}`> &
Brand<"Millis">;
```
Defined in: [packages/common/src/local-first/Timestamp.ts:71](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Timestamp.ts#L71)
maxNodeId - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / maxNodeId
# Variable: maxNodeId
```ts
const maxNodeId: string & Brand<"NodeId">;
```
Defined in: [packages/common/src/local-first/Timestamp.ts:111](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Timestamp.ts#L111)
minCounter - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / minCounter
# Variable: minCounter
```ts
const minCounter: number &
Brand<"Int"> &
Brand<"NonNegative"> &
Brand<"LessThanOrEqualTo65535"> &
Brand<"Counter">;
```
Defined in: [packages/common/src/local-first/Timestamp.ts:79](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Timestamp.ts#L79)
minMillis - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / minMillis
# Variable: minMillis
```ts
const minMillis: number &
Brand<"Int"> &
Brand<"NonNegative"> &
Brand<`LessThanOrEqualTo${number}`> &
Brand<"Millis">;
```
Defined in: [packages/common/src/local-first/Timestamp.ts:70](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Timestamp.ts#L70)
minNodeId - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / minNodeId
# Variable: minNodeId
```ts
const minNodeId: string & Brand<"NodeId">;
```
Defined in: [packages/common/src/local-first/Timestamp.ts:110](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Timestamp.ts#L110)
orderTimestampBytes - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / orderTimestampBytes
# Variable: orderTimestampBytes
```ts
const orderTimestampBytes: Order<TimestampBytes> = orderUint8Array;
```
Defined in: [packages/common/src/local-first/Timestamp.ts:346](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Timestamp.ts#L346)
An [Order](https://evolu.dev/docs/api-reference/common/Order/type-aliases/Order) for [TimestampBytes](https://evolu.dev/docs/api-reference/common/local-first/variables/TimestampBytes).
This `Order` uses lexicographic byte order to compare serialized
[TimestampBytes](https://evolu.dev/docs/api-reference/common/local-first/variables/TimestampBytes) produced by [timestampToTimestampBytes](https://evolu.dev/docs/api-reference/common/local-first/functions/timestampToTimestampBytes). See
[orderUint8Array](https://evolu.dev/docs/api-reference/common/Order/variables/orderUint8Array) for the underlying implementation.
ownerWriteKeyLength - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / ownerWriteKeyLength
# Variable: ownerWriteKeyLength
```ts
const ownerWriteKeyLength: number & Brand<"Int"> & Brand<"NonNegative">;
```
Defined in: [packages/common/src/local-first/Owner.ts:87](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Owner.ts#L87)
systemColumns - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / systemColumns
# Variable: systemColumns
```ts
const systemColumns: ReadonlySet<string>;
```
Defined in: [packages/common/src/local-first/Schema.ts:247](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Schema.ts#L247)
systemColumnsWithId - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / systemColumnsWithId
# Variable: systemColumnsWithId
```ts
const systemColumnsWithId: readonly string[];
```
Defined in: [packages/common/src/local-first/Schema.ts:251](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Schema.ts#L251)
timestampBytesLength - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / timestampBytesLength
# Variable: timestampBytesLength
```ts
const timestampBytesLength: number & Brand<"Int"> & Brand<"NonNegative">;
```
Defined in: [packages/common/src/local-first/Timestamp.ts:283](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Timestamp.ts#L283)
zeroFingerprint - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first](https://evolu.dev/docs/api-reference/common/local-first) / zeroFingerprint
# Variable: zeroFingerprint
```ts
const zeroFingerprint: Fingerprint;
```
Defined in: [packages/common/src/local-first/Storage.ts:196](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Storage.ts#L196)
A fingerprint of an empty range.
createNodeJsRelay - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/nodejs](https://evolu.dev/docs/api-reference/nodejs) / [index](https://evolu.dev/docs/api-reference/nodejs/index) / createNodeJsRelay
# Function: createNodeJsRelay()
```ts
function createNodeJsRelay(
deps,
): (config) => Promise<Result<Relay, SqliteError>>;
```
Defined in: [nodejs/src/local-first/Relay.ts:48](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/nodejs/src/local-first/Relay.ts#L48)
Creates an Evolu relay server.
This implementation uses Node.js and better-sqlite3. Additional relay
implementations will be provided for other platforms (Bun, Deno, Cloudflare
Workers, Vercel Edge, etc.).
## Parameters
| Parameter | Type |
| --------- | ---------------------------------------------------------------------------- |
| `deps` | [`ConsoleDep`](https://evolu.dev/docs/api-reference/common/Console/interfaces/ConsoleDep) |
## Returns
```ts
(config): Promise<Result<Relay, SqliteError>>;
```
### Parameters
| Parameter | Type |
| --------- | ---------------------------------------------------------------------------------------- |
| `config` | [`NodeJsRelayConfig`](https://evolu.dev/docs/api-reference/nodejs/index/interfaces/NodeJsRelayConfig) |
### Returns
`Promise`\<[`Result`](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result)\<[`Relay`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Relay), [`SqliteError`](https://evolu.dev/docs/api-reference/common/Sqlite/interfaces/SqliteError)\>\>
createNodeJsRelayWithSqliteDriver - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/nodejs](https://evolu.dev/docs/api-reference/nodejs) / [index](https://evolu.dev/docs/api-reference/nodejs/index) / createNodeJsRelayWithSqliteDriver
# Function: createNodeJsRelayWithSqliteDriver()
```ts
function createNodeJsRelayWithSqliteDriver(
deps,
): (config) => Promise<Result<Relay, SqliteError>>;
```
Defined in: [nodejs/src/local-first/Relay.ts:62](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/nodejs/src/local-first/Relay.ts#L62)
Creates an Evolu relay server with a custom SQLite driver.
Use this when you need to provide a different SQLite driver implementation
(e.g., using alternative SQLite libraries).
## Parameters
| Parameter | Type |
| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `deps` | [`ConsoleDep`](https://evolu.dev/docs/api-reference/common/Console/interfaces/ConsoleDep) & [`CreateSqliteDriverDep`](https://evolu.dev/docs/api-reference/common/Sqlite/interfaces/CreateSqliteDriverDep) |
## Returns
```ts
(config): Promise<Result<Relay, SqliteError>>;
```
### Parameters
| Parameter | Type |
| --------- | ---------------------------------------------------------------------------------------- |
| `config` | [`NodeJsRelayConfig`](https://evolu.dev/docs/api-reference/nodejs/index/interfaces/NodeJsRelayConfig) |
### Returns
`Promise`\<[`Result`](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result)\<[`Relay`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Relay), [`SqliteError`](https://evolu.dev/docs/api-reference/common/Sqlite/interfaces/SqliteError)\>\>
NodeJsRelayConfig - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/nodejs](https://evolu.dev/docs/api-reference/nodejs) / [index](https://evolu.dev/docs/api-reference/nodejs/index) / NodeJsRelayConfig
# Interface: NodeJsRelayConfig
Defined in: [nodejs/src/local-first/Relay.ts:35](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/nodejs/src/local-first/Relay.ts#L35)
## Extends
- [`RelayConfig`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/RelayConfig)
## Properties
| Property | Modifier | Type | Description | Inherited from | Defined in |
| ---------------------------------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="enablelogging"></a> `enableLogging?` | `readonly` | `boolean` | Enable or disable console logging (default: false). When true, logs are output to the [Console](https://evolu.dev/docs/api-reference/common/Console/interfaces/Console); when false, logging is disabled for all methods except `error`, which always outputs to ensure critical issues are not missed. | [`RelayConfig`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/RelayConfig).[`enableLogging`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/RelayConfig.mdx#enablelogging) | common/dist/src/Console.d.ts:80 |
| <a id="isownerallowed"></a> `isOwnerAllowed?` | `readonly` | (`ownerId`) => [`MaybeAsync`](https://evolu.dev/docs/api-reference/common/Task/type-aliases/MaybeAsync)\<`boolean`\> | Optional callback to check if an [OwnerId](https://evolu.dev/docs/api-reference/common/local-first/variables/OwnerId) is allowed to access the relay. If this callback is not provided, all owners are allowed. The callback receives the [OwnerId](https://evolu.dev/docs/api-reference/common/local-first/variables/OwnerId) and returns a [MaybeAsync](https://evolu.dev/docs/api-reference/common/Task/type-aliases/MaybeAsync) boolean: `true` to allow access, or `false` to deny. The callback can be synchronous (for SQLite or in-memory checks) or asynchronous (for calling remote APIs). The callback returns a boolean rather than an error type because error handling and logging are the responsibility of the callback implementation. OwnerId is used rather than short-lived tokens because this only controls relay access, not write permissions. Since all data is encrypted on the relay, OwnerId exposure is safe. Owners specify which relays to connect to via [OwnerTransport](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/OwnerTransport). In WebSocket-based implementations, this check occurs before accepting the connection, with the OwnerId typically extracted from the URL Path (e.g., `ws://localhost:4000/<ownerId>`). The relay requires the URL to be in the correct format for OwnerId extraction. ### Example `// Client const transport = createOwnerWebSocketTransport({ url: "wss://relay.evolu.dev", ownerId: owner.id, }); const evolu = createEvolu(deps)(Schema, { transports: [transport], }); // Relay isOwnerAllowed: (ownerId) => Promise.resolve(ownerId === "6jy_2F4RT5qqeLgJ14_dnQ"),` | [`RelayConfig`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/RelayConfig).[`isOwnerAllowed`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/RelayConfig.mdx#isownerallowed) | common/dist/src/local-first/Relay.d.ts:62 |
| <a id="isownerwithinquota"></a> `isOwnerWithinQuota` | `readonly` | (`ownerId`, `requiredBytes`) => [`MaybeAsync`](https://evolu.dev/docs/api-reference/common/Task/type-aliases/MaybeAsync)\<`boolean`\> | Callback called before an attempt to write, to check if an [OwnerId](https://evolu.dev/docs/api-reference/common/local-first/variables/OwnerId) has sufficient quota for the write. The callback receives the [OwnerId](https://evolu.dev/docs/api-reference/common/local-first/variables/OwnerId) and the total bytes that would be stored after the write (current stored bytes plus incoming bytes), and returns a [MaybeAsync](https://evolu.dev/docs/api-reference/common/Task/type-aliases/MaybeAsync) boolean: `true` to allow the write, or `false` to deny it due to quota limits. The callback can be synchronous (for SQLite or in-memory checks) or asynchronous (for calling remote APIs). The callback returns a boolean rather than an error because error handling and logging are the responsibility of the callback implementation. ### Example `// Client // evolu.subscribeError // Relay isOwnerWithinQuota: (ownerId, requiredBytes) => { console.log(ownerId, requiredBytes); // Check error via evolu.subscribeError return true; };` | [`RelayConfig`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/RelayConfig).[`isOwnerWithinQuota`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/RelayConfig.mdx#isownerwithinquota) | common/dist/src/local-first/Storage.d.ts:40 |
| <a id="name"></a> `name?` | `readonly` | `string` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"UrlSafeString"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"SimpleName"`\> | The relay name. Implementations can use this for identification purposes (e.g., database file name, logging). | [`RelayConfig`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/RelayConfig).[`name`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/RelayConfig.mdx#name) | common/dist/src/local-first/Relay.d.ts:18 |
| <a id="port"></a> `port?` | `readonly` | `number` | The port number for the HTTP server. | - | [nodejs/src/local-first/Relay.ts:37](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/nodejs/src/local-first/Relay.ts#L37) |
createBetterSqliteDriver - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/nodejs](https://evolu.dev/docs/api-reference/nodejs) / [index](https://evolu.dev/docs/api-reference/nodejs/index) / createBetterSqliteDriver
# Variable: createBetterSqliteDriver
```ts
const createBetterSqliteDriver: CreateSqliteDriver;
```
Defined in: [nodejs/src/BetterSqliteDriver.ts:10](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/nodejs/src/BetterSqliteDriver.ts#L10)
EvoluProvider - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/react](https://evolu.dev/docs/api-reference/react) / [index](https://evolu.dev/docs/api-reference/react/index) / EvoluProvider
# Function: EvoluProvider()
```ts
function EvoluProvider(__namedParameters): ReactElement;
```
Defined in: [EvoluProvider.tsx:7](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/react/src/EvoluProvider.tsx#L7)
## Parameters
| Parameter | Type |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `__namedParameters` | \{ `children?`: `ReactNode`; `value`: [`Evolu`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Evolu)\<`any`\>; \} |
| `__namedParameters.children?` | `ReactNode` |
| `__namedParameters.value` | [`Evolu`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Evolu)\<`any`\> |
## Returns
`ReactElement`
createUseEvolu - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/react](https://evolu.dev/docs/api-reference/react) / [index](https://evolu.dev/docs/api-reference/react/index) / createUseEvolu
# Function: createUseEvolu()
```ts
function createUseEvolu<S>(evolu): () => Evolu<S>;
```
Defined in: [createUseEvolu.ts:14](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/react/src/createUseEvolu.ts#L14)
Creates a typed React Hook returning an instance of [Evolu](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Evolu).
### Example
```ts
const useEvolu = createUseEvolu(evolu);
const { insert, update } = useEvolu();
```
## Type Parameters
| Type Parameter |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `S` _extends_ `Readonly`\<`Record`\<`string`, `Readonly`\<`Record`\<`string`, [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type)\<`any`, `any`, `any`, `any`, `any`, `any`\>\>\>\>\> |
## Parameters
| Parameter | Type |
| --------- | ----------------------------------------------------------------------------- |
| `evolu` | [`Evolu`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Evolu)\<`S`\> |
## Returns
```ts
(): Evolu<S>;
```
### Returns
[`Evolu`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Evolu)\<`S`\>
useEvolu - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/react](https://evolu.dev/docs/api-reference/react) / [index](https://evolu.dev/docs/api-reference/react/index) / useEvolu
# Function: useEvolu()
```ts
function useEvolu(): Evolu;
```
Defined in: [useEvolu.ts:12](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/react/src/useEvolu.ts#L12)
React Hook returning a generic instance of [Evolu](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Evolu).
This is intended for internal usage. Applications should use
[createUseEvolu](https://evolu.dev/docs/api-reference/react/index/functions/createUseEvolu), which provides a correctly typed instance.
## Returns
[`Evolu`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Evolu)
useEvoluError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/react](https://evolu.dev/docs/api-reference/react) / [index](https://evolu.dev/docs/api-reference/react/index) / useEvoluError
# Function: useEvoluError()
```ts
function useEvoluError(): EvoluError | null;
```
Defined in: [useEvoluError.ts:6](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/react/src/useEvoluError.ts#L6)
Subscribe to [EvoluError](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/EvoluError) changes.
## Returns
\| [`EvoluError`](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/EvoluError)
\| `null`
useIsSsr - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/react](https://evolu.dev/docs/api-reference/react) / [index](https://evolu.dev/docs/api-reference/react/index) / useIsSsr
# Function: useIsSsr()
```ts
function useIsSsr(): boolean;
```
Defined in: [useIsSsr.ts:12](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/react/src/useIsSsr.ts#L12)
Avoiding hydration mismatches.
## Returns
`boolean`
## See
https://kurtextrem.de/posts/react-uses-hydration
useOwner - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/react](https://evolu.dev/docs/api-reference/react) / [index](https://evolu.dev/docs/api-reference/react/index) / useOwner
# Function: useOwner()
```ts
function useOwner(owner): void;
```
Defined in: [useOwner.ts:11](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/react/src/useOwner.ts#L11)
React Hook for Evolu `useOwner` method.
Using an owner means syncing it with its transports, or the transports
defined in Evolu config if the owner has no transports defined.
## Parameters
| Parameter | Type |
| --------- | ------------------------------------------------------------------------------------------- |
| `owner` | \| [`SyncOwner`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/SyncOwner) \| `null` |
## Returns
`void`
useQueries - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/react](https://evolu.dev/docs/api-reference/react) / [index](https://evolu.dev/docs/api-reference/react/index) / useQueries
# Function: useQueries()
```ts
function useQueries<R, Q, OQ>(
queries,
options,
): [...QueriesToQueryRows<Q>[], ...QueriesToQueryRows<OQ>[]];
```
Defined in: [useQueries.ts:18](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/react/src/useQueries.ts#L18)
The same as [useQuery](https://evolu.dev/docs/api-reference/react/index/functions/useQuery), but for many queries.
The number of queries must remain stable across renders.
## Type Parameters
| Type Parameter |
| -------------------------------------------------------------------------------------------------- |
| `R` _extends_ [`Row`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Row) |
| `Q` _extends_ [`Queries`](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/Queries)\<`R`\> |
| `OQ` _extends_ [`Queries`](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/Queries)\<`R`\> |
## Parameters
| Parameter | Type |
| --------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `queries` | \[`...Q[]`\] |
| `options` | `Partial`\<\{ `once`: \[`...OQ`\]; `promises`: \[`...QueriesToQueryRowsPromises<Q>`, `...QueriesToQueryRowsPromises<OQ>`\]; \}\> |
## Returns
\[`...QueriesToQueryRows<Q>[]`, `...QueriesToQueryRows<OQ>[]`\]
useQuery - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/react](https://evolu.dev/docs/api-reference/react) / [index](https://evolu.dev/docs/api-reference/react/index) / useQuery
# Function: useQuery()
```ts
function useQuery<R>(query, options): QueryRows<R>;
```
Defined in: [useQuery.ts:37](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/react/src/useQuery.ts#L37)
Load and subscribe to the Query, and return an object with `rows` and `row`
properties that are automatically updated when data changes.
Note that [useQuery](https://evolu.dev/docs/api-reference/react/index/functions/useQuery) uses React Suspense. It means every usage of
[useQuery](https://evolu.dev/docs/api-reference/react/index/functions/useQuery) blocks rendering until loading is completed. To avoid loading
waterfall with more queries, use [useQueries](https://evolu.dev/docs/api-reference/react/index/functions/useQueries).
The `promise` option allows preloading queries before rendering, which can be
useful for complex queries that might take noticeable time even with local
data. However, this is rarely needed as local queries are typically fast.
### Example
```ts
// Get all rows.
const rows = useQuery(allTodos);
// Get rows for a specific todo (the first row can be null).
const rows = useQuery(todoById(1));
// Get all rows, but without subscribing to changes.
const rows = useQuery(allTodos, { once: true });
// Preload a query (rarely needed).
const allTodosPromise = evolu.loadQuery(allTodos);
const rows = useQuery(allTodos, { promise: allTodosPromise });
```
## Type Parameters
| Type Parameter |
| -------------------------------------------------------------------------------- |
| `R` _extends_ [`Row`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Row) |
## Parameters
| Parameter | Type |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `query` | [`Query`](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/Query)\<`R`\> |
| `options` | `Partial`\<\{ `once`: `boolean`; `promise`: `Promise`\<[`QueryRows`](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/QueryRows)\<`R`\>\>; \}\> |
## Returns
[`QueryRows`](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/QueryRows)\<`R`\>
useQuerySubscription - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/react](https://evolu.dev/docs/api-reference/react) / [index](https://evolu.dev/docs/api-reference/react/index) / useQuerySubscription
# Function: useQuerySubscription()
```ts
function useQuerySubscription<R>(query, options): QueryRows<R>;
```
Defined in: [useQuerySubscription.ts:7](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/react/src/useQuerySubscription.ts#L7)
Subscribe to [Query](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/Query) [QueryRows](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/QueryRows) changes.
## Type Parameters
| Type Parameter |
| -------------------------------------------------------------------------------- |
| `R` _extends_ [`Row`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Row) |
## Parameters
| Parameter | Type |
| --------- | ------------------------------------------------------------------------------- |
| `query` | [`Query`](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/Query)\<`R`\> |
| `options` | `Partial`\<\{ `once`: `boolean`; \}\> |
## Returns
[`QueryRows`](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/QueryRows)\<`R`\>
EvoluContext - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/react](https://evolu.dev/docs/api-reference/react) / [index](https://evolu.dev/docs/api-reference/react/index) / EvoluContext
# Variable: EvoluContext
```ts
const EvoluContext: Context<Evolu<any> | null>;
```
Defined in: [EvoluContext.ts:4](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/react/src/EvoluContext.ts#L4)
EvoluContext - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/react-native](https://evolu.dev/docs/api-reference/react-native) / [web](https://evolu.dev/docs/api-reference/react-native/web) / EvoluContext
# Variable: EvoluContext
```ts
const EvoluContext: Context;
```
Defined in: react/dist/EvoluContext.d.ts:2
EvoluProvider - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/react-native](https://evolu.dev/docs/api-reference/react-native) / [web](https://evolu.dev/docs/api-reference/react-native/web) / EvoluProvider
# Variable: EvoluProvider()
```ts
const EvoluProvider: ({ children, value }) => React.ReactElement;
```
Defined in: react/dist/EvoluProvider.d.ts:3
## Parameters
| Parameter | Type |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `{ children, value, }` | \{ `children?`: `ReactNode`; `value`: [`Evolu`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Evolu)\<`any`\>; \} |
| `{ children, value, }.children?` | `ReactNode` |
| `{ children, value, }.value` | [`Evolu`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Evolu)\<`any`\> |
## Returns
`React.ReactElement`
createUseEvolu - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/react-native](https://evolu.dev/docs/api-reference/react-native) / [web](https://evolu.dev/docs/api-reference/react-native/web) / createUseEvolu
# Variable: createUseEvolu()
```ts
const createUseEvolu: <S>(evolu) => () => Evolu<S>;
```
Defined in: react/dist/createUseEvolu.d.ts:12
Creates a typed React Hook returning an instance of [Evolu](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Evolu).
### Example
```ts
const useEvolu = createUseEvolu(evolu);
const { insert, update } = useEvolu();
```
## Type Parameters
| Type Parameter |
| -------------------------------------------------------------------------------------------------- |
| `S` _extends_ [`EvoluSchema`](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/EvoluSchema) |
## Parameters
| Parameter | Type |
| --------- | ----------------------------------------------------------------------------- |
| `evolu` | [`Evolu`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Evolu)\<`S`\> |
## Returns
```ts
(): Evolu<S>;
```
### Returns
[`Evolu`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Evolu)\<`S`\>
useEvolu - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/react-native](https://evolu.dev/docs/api-reference/react-native) / [web](https://evolu.dev/docs/api-reference/react-native/web) / useEvolu
# Variable: useEvolu()
```ts
const useEvolu: () => Evolu;
```
Defined in: react/dist/useEvolu.d.ts:8
React Hook returning a generic instance of [Evolu](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Evolu).
This is intended for internal usage. Applications should use
[createUseEvolu](https://evolu.dev/docs/api-reference/react-native/web/variables/createUseEvolu), which provides a correctly typed instance.
## Returns
[`Evolu`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Evolu)
useEvoluError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/react-native](https://evolu.dev/docs/api-reference/react-native) / [web](https://evolu.dev/docs/api-reference/react-native/web) / useEvoluError
# Variable: useEvoluError()
```ts
const useEvoluError: () => EvoluError | null;
```
Defined in: react/dist/useEvoluError.d.ts:3
Subscribe to [EvoluError](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/EvoluError) changes.
## Returns
\| [`EvoluError`](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/EvoluError)
\| `null`
useIsSsr - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/react-native](https://evolu.dev/docs/api-reference/react-native) / [web](https://evolu.dev/docs/api-reference/react-native/web) / useIsSsr
# Variable: useIsSsr()
```ts
const useIsSsr: () => boolean;
```
Defined in: react/dist/useIsSsr.d.ts:6
Avoiding hydration mismatches.
## Returns
`boolean`
## See
https://kurtextrem.de/posts/react-uses-hydration
useOwner - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/react-native](https://evolu.dev/docs/api-reference/react-native) / [web](https://evolu.dev/docs/api-reference/react-native/web) / useOwner
# Variable: useOwner()
```ts
const useOwner: (owner) => void;
```
Defined in: react/dist/useOwner.d.ts:8
React Hook for Evolu `useOwner` method.
Using an owner means syncing it with its transports, or the transports
defined in Evolu config if the owner has no transports defined.
## Parameters
| Parameter | Type |
| --------- | ------------------------------------------------------------------------------------------- |
| `owner` | \| [`SyncOwner`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/SyncOwner) \| `null` |
## Returns
`void`
useQueries - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/react-native](https://evolu.dev/docs/api-reference/react-native) / [web](https://evolu.dev/docs/api-reference/react-native/web) / useQueries
# Variable: useQueries()
```ts
const useQueries: <R, Q, OQ>(
queries,
options?,
) => [...QueriesToQueryRows<Q>, ...QueriesToQueryRows<OQ>];
```
Defined in: react/dist/useQueries.d.ts:7
The same as [useQuery](https://evolu.dev/docs/api-reference/react-native/web/variables/useQuery), but for many queries.
The number of queries must remain stable across renders.
## Type Parameters
| Type Parameter |
| -------------------------------------------------------------------------------------------------- |
| `R` _extends_ [`Row`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Row) |
| `Q` _extends_ [`Queries`](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/Queries)\<`R`\> |
| `OQ` _extends_ [`Queries`](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/Queries)\<`R`\> |
## Parameters
| Parameter | Type |
| ---------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `queries` | \[`...Q`\] |
| `options?` | `Partial`\<\{ `once`: \[`...OQ`\]; `promises`: \[`...QueriesToQueryRowsPromises<Q>`, `...QueriesToQueryRowsPromises<OQ>`\]; \}\> |
## Returns
\[`...QueriesToQueryRows<Q>`, `...QueriesToQueryRows<OQ>`\]
useQuery - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/react-native](https://evolu.dev/docs/api-reference/react-native) / [web](https://evolu.dev/docs/api-reference/react-native/web) / useQuery
# Variable: useQuery()
```ts
const useQuery: <R>(query, options?) => QueryRows<R>;
```
Defined in: react/dist/useQuery.d.ts:31
Load and subscribe to the Query, and return an object with `rows` and `row`
properties that are automatically updated when data changes.
Note that [useQuery](https://evolu.dev/docs/api-reference/react-native/web/variables/useQuery) uses React Suspense. It means every usage of
[useQuery](https://evolu.dev/docs/api-reference/react-native/web/variables/useQuery) blocks rendering until loading is completed. To avoid loading
waterfall with more queries, use [useQueries](https://evolu.dev/docs/api-reference/react-native/web/variables/useQueries).
The `promise` option allows preloading queries before rendering, which can be
useful for complex queries that might take noticeable time even with local
data. However, this is rarely needed as local queries are typically fast.
### Example
```ts
// Get all rows.
const rows = useQuery(allTodos);
// Get rows for a specific todo (the first row can be null).
const rows = useQuery(todoById(1));
// Get all rows, but without subscribing to changes.
const rows = useQuery(allTodos, { once: true });
// Preload a query (rarely needed).
const allTodosPromise = evolu.loadQuery(allTodos);
const rows = useQuery(allTodos, { promise: allTodosPromise });
```
## Type Parameters
| Type Parameter |
| -------------------------------------------------------------------------------- |
| `R` _extends_ [`Row`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Row) |
## Parameters
| Parameter | Type |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `query` | [`Query`](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/Query)\<`R`\> |
| `options?` | `Partial`\<\{ `once`: `boolean`; `promise`: `Promise`\<[`QueryRows`](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/QueryRows)\<`R`\>\>; \}\> |
## Returns
[`QueryRows`](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/QueryRows)\<`R`\>
useQuerySubscription - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/react-native](https://evolu.dev/docs/api-reference/react-native) / [web](https://evolu.dev/docs/api-reference/react-native/web) / useQuerySubscription
# Variable: useQuerySubscription()
```ts
const useQuerySubscription: <R>(query, options?) => QueryRows<R>;
```
Defined in: react/dist/useQuerySubscription.d.ts:3
Subscribe to [Query](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/Query) [QueryRows](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/QueryRows) changes.
## Type Parameters
| Type Parameter |
| -------------------------------------------------------------------------------- |
| `R` _extends_ [`Row`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Row) |
## Parameters
| Parameter | Type |
| ---------- | ------------------------------------------------------------------------------- |
| `query` | [`Query`](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/Query)\<`R`\> |
| `options?` | `Partial`\<\{ `once`: `boolean`; \}\> |
## Returns
[`QueryRows`](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/QueryRows)\<`R`\>
appOwnerState - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/svelte](https://evolu.dev/docs/api-reference/svelte) / [index.svelte](https://evolu.dev/docs/api-reference/svelte/index.svelte) / appOwnerState
# Function: appOwnerState()
```ts
function appOwnerState<Schema>(evolu): object;
```
Defined in: [index.svelte.ts:133](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/svelte/src/lib/index.svelte.ts#L133)
Get the [AppOwner](https://evolu.dev/docs/api-reference/common/local-first/interfaces/AppOwner) promise that resolves when available.
### Example
```ts
const owner = appOwnerState(evolu);
// use owner.current in your Svelte templates
// it will be undefined initially and set once the promise resolves
```
## Type Parameters
| Type Parameter |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Schema` _extends_ `Readonly`\<`Record`\<`string`, `Readonly`\<`Record`\<`string`, [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type)\<`any`, `any`, `any`, `any`, `any`, `any`\>\>\>\>\> |
## Parameters
| Parameter | Type |
| --------- | ---------------------------------------------------------------------------------- |
| `evolu` | [`Evolu`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Evolu)\<`Schema`\> |
## Returns
`object`
| Name | Type | Defined in |
| --------- | ---------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `current` | \| [`AppOwner`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/AppOwner) \| `undefined` | [index.svelte.ts:136](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/svelte/src/lib/index.svelte.ts#L136) |
queryState - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/svelte](https://evolu.dev/docs/api-reference/svelte) / [index.svelte](https://evolu.dev/docs/api-reference/svelte/index.svelte) / queryState
# Function: queryState()
```ts
function queryState<R, Schema, MappedRow>(
evolu,
observedQuery,
options?,
): object;
```
Defined in: [index.svelte.ts:52](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/svelte/src/lib/index.svelte.ts#L52)
Load and subscribe to the Query, and return an object with `rows` property
that are automatically updated when data changes.
### Example
```ts
// Create your query
const allTodos = evolu.createQuery((db) => ...);
// Get all rows.
const allTodosState = queryState(evolu, () => allTodos);
```
### Example
```ts
// some kind of state
let someKindOfState = $state('someId');
// derive your query based other props
const allTodos = $derived(evolu.createQuery((db) => use someKindOfState here ));
// Get all rows, once someKindOfState changes, this allTodosState will be updated with the evolu query result
const allTodosState = queryState(evolu, () => allTodos);
// use allTodosState.rows in further calculations / UI
```
## Type Parameters
| Type Parameter | Default type |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ |
| `R` _extends_ [`Row`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Row) | - |
| `Schema` _extends_ `Readonly`\<`Record`\<`string`, `Readonly`\<`Record`\<`string`, [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type)\<`any`, `any`, `any`, `any`, `any`, `any`\>\>\>\>\> | - |
| `MappedRow` | `R` |
## Parameters
| Parameter | Type | Description |
| ------------------ | ------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `evolu` | [`Evolu`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Evolu)\<`Schema`\> | - |
| `observedQuery` | () => \| [`Query`](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/Query)\<`R`\> \| `undefined` | Can be a normal query or a derived query. Svelte reactivity: it needs to be a callback, if the query is $derived this will re-trigger the load/subscription based on the new query. |
| `options?` | \{ `mapping?`: (`row`) => `MappedRow`; \} | - |
| `options.mapping?` | (`row`) => `MappedRow` | This is a little helper so that you can map the results instead of using a $derive operation. |
## Returns
`object`
| Name | Type | Defined in |
| ------ | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `rows` | `MappedRow`[] | [index.svelte.ts:74](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/svelte/src/lib/index.svelte.ts#L74) |
evoluSvelteDeps - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/svelte](https://evolu.dev/docs/api-reference/svelte) / [index.svelte](https://evolu.dev/docs/api-reference/svelte/index.svelte) / evoluSvelteDeps
# Variable: evoluSvelteDeps
```ts
const evoluSvelteDeps: EvoluDeps;
```
Defined in: [index.svelte.ts:19](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/svelte/src/lib/index.svelte.ts#L19)
createUseEvolu - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/vue](https://evolu.dev/docs/api-reference/vue) / [index](https://evolu.dev/docs/api-reference/vue/index) / createUseEvolu
# Function: createUseEvolu()
```ts
function createUseEvolu<S>(evolu): () => Evolu<S>;
```
Defined in: [packages/vue/src/createUseEvolu.ts:14](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/vue/src/createUseEvolu.ts#L14)
Creates a helper function returning a type-aware instance of [Evolu](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Evolu).
### Example
```ts
const useEvolu = createUseEvolu(evolu);
const { insert, update } = useEvolu();
```
## Type Parameters
| Type Parameter |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `S` _extends_ `Readonly`\<`Record`\<`string`, `Readonly`\<`Record`\<`string`, [`Type`](https://evolu.dev/docs/api-reference/common/Type/interfaces/Type)\<`any`, `any`, `any`, `any`, `any`, `any`\>\>\>\>\> |
## Parameters
| Parameter | Type |
| --------- | ----------------------------------------------------------------------------- |
| `evolu` | [`Evolu`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Evolu)\<`S`\> |
## Returns
```ts
(): Evolu<S>;
```
### Returns
[`Evolu`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Evolu)\<`S`\>
provideEvolu - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/vue](https://evolu.dev/docs/api-reference/vue) / [index](https://evolu.dev/docs/api-reference/vue/index) / provideEvolu
# Function: provideEvolu()
```ts
function provideEvolu(evolu): void;
```
Defined in: [packages/vue/src/provideEvolu.ts:23](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/vue/src/provideEvolu.ts#L23)
Provide the Evolu instance to components via Vue's provide/inject system.
## Parameters
| Parameter | Type |
| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `evolu` | \| [`Evolu`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Evolu)\<`any`\> \| () => [`Evolu`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Evolu)\<`any`\> |
## Returns
`void`
useEvolu - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/vue](https://evolu.dev/docs/api-reference/vue) / [index](https://evolu.dev/docs/api-reference/vue/index) / useEvolu
# Function: useEvolu()
```ts
function useEvolu(): Evolu;
```
Defined in: [packages/vue/src/useEvolu.ts:11](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/vue/src/useEvolu.ts#L11)
Vue composable returning a generic instance of [Evolu](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Evolu).
Applications should prefer [createUseEvolu](https://evolu.dev/docs/api-reference/vue/index/functions/createUseEvolu) for proper typing.
## Returns
[`Evolu`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Evolu)
useEvoluError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/vue](https://evolu.dev/docs/api-reference/vue) / [index](https://evolu.dev/docs/api-reference/vue/index) / useEvoluError
# Function: useEvoluError()
```ts
function useEvoluError(): Ref<EvoluError | null>;
```
Defined in: [packages/vue/src/useEvoluError.ts:6](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/vue/src/useEvoluError.ts#L6)
Subscribe to [EvoluError](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/EvoluError) changes.
## Returns
`Ref`\<
\| [`EvoluError`](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/EvoluError)
\| `null`\>
useOwner - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/vue](https://evolu.dev/docs/api-reference/vue) / [index](https://evolu.dev/docs/api-reference/vue/index) / useOwner
# Function: useOwner()
```ts
function useOwner(owner): void;
```
Defined in: [packages/vue/src/useOwner.ts:10](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/vue/src/useOwner.ts#L10)
Vue composable for Evolu `useOwner` method.
Using an owner means syncing it with its transports, or the transports
defined in Evolu config if the owner has no transports defined.
## Parameters
| Parameter | Type |
| --------- | ------------------------------------------------------------------------------------------- |
| `owner` | \| [`SyncOwner`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/SyncOwner) \| `null` |
## Returns
`void`
useQueries - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/vue](https://evolu.dev/docs/api-reference/vue) / [index](https://evolu.dev/docs/api-reference/vue/index) / useQueries
# Function: useQueries()
```ts
function useQueries<R, Q, OQ>(
queries,
options,
): [...QueriesToQueryRowsRef<Q>[], ...QueriesToQueryRowsRef<OQ>[]];
```
Defined in: [packages/vue/src/useQueries.ts:16](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/vue/src/useQueries.ts#L16)
The same as [useQuery](https://evolu.dev/docs/api-reference/vue/index/functions/useQuery), but for many queries.
## Type Parameters
| Type Parameter |
| -------------------------------------------------------------------------------------------------- |
| `R` _extends_ [`Row`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Row) |
| `Q` _extends_ [`Queries`](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/Queries)\<`R`\> |
| `OQ` _extends_ [`Queries`](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/Queries)\<`R`\> |
## Parameters
| Parameter | Type |
| --------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `queries` | \[`...Q[]`\] |
| `options` | `Partial`\<\{ `once`: \[`...OQ`\]; `promises`: \[`...QueriesToQueryRowsPromises<Q>`, `...QueriesToQueryRowsPromises<OQ>`\]; \}\> |
## Returns
\[`...QueriesToQueryRowsRef<Q>[]`, `...QueriesToQueryRowsRef<OQ>[]`\]
useQuery - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/vue](https://evolu.dev/docs/api-reference/vue) / [index](https://evolu.dev/docs/api-reference/vue/index) / useQuery
# Function: useQuery()
```ts
function useQuery<R>(query, options): Readonly<Ref<QueryRows<R>>>;
```
Defined in: [packages/vue/src/useQuery.ts:31](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/vue/src/useQuery.ts#L31)
Load and subscribe to the query, returning a ref that stays in sync with
Evolu changes.
### Example
```ts
// Get all rows.
const rows = useQuery(allTodos);
// Get rows for a specific todo (the first row can be null).
const rows = useQuery(todoById(1));
// Get all rows, but without subscribing to changes.
const rows = useQuery(allTodos, { once: true });
// Prefetch rows.
const allTodos = evolu.createQuery((db) => db.selectFrom("todo").selectAll());
const allTodosPromise = evolu.loadQuery(allTodos);
// Use prefetched rows.
const rows = useQuery(allTodos, { promise: allTodosPromise });
```
## Type Parameters
| Type Parameter |
| -------------------------------------------------------------------------------- |
| `R` _extends_ [`Row`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Row) |
## Parameters
| Parameter | Type |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `query` | [`Query`](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/Query)\<`R`\> |
| `options` | `Partial`\<\{ `once`: `boolean`; `promise`: `Promise`\<[`QueryRows`](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/QueryRows)\<`R`\>\>; \}\> |
## Returns
`Readonly`\<`Ref`\<[`QueryRows`](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/QueryRows)\<`R`\>\>\>
useSyncState - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/vue](https://evolu.dev/docs/api-reference/vue) / [index](https://evolu.dev/docs/api-reference/vue/index) / useSyncState
# Function: useSyncState()
```ts
function useSyncState(): Ref<SyncState>;
```
Defined in: [packages/vue/src/useSyncState.ts:6](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/vue/src/useSyncState.ts#L6)
Subscribe to [SyncState](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/SyncState) changes.
## Returns
`Ref`\<[`SyncState`](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/SyncState)\>
QueriesToQueryRowsRef - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/vue](https://evolu.dev/docs/api-reference/vue) / [index](https://evolu.dev/docs/api-reference/vue/index) / QueriesToQueryRowsRef
# Type Alias: QueriesToQueryRowsRef\<Q\>
```ts
type QueriesToQueryRowsRef<Q> = {
[P in keyof Q]: Q[P] extends Query<infer R> ? Ref<QueryRows<R>> : never;
};
```
Defined in: [packages/vue/src/useQueries.ts:11](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/vue/src/useQueries.ts#L11)
## Type Parameters
| Type Parameter |
| ------------------------------------------------------------------------------------------ |
| `Q` _extends_ [`Queries`](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/Queries) |
EvoluContext - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/vue](https://evolu.dev/docs/api-reference/vue) / [index](https://evolu.dev/docs/api-reference/vue/index) / EvoluContext
# Variable: EvoluContext
```ts
const EvoluContext: InjectionKey<Evolu<any> | null>;
```
Defined in: [packages/vue/src/provideEvolu.ts:19](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/vue/src/provideEvolu.ts#L19)
The injection key for providing Evolu.
EvoluProvider - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/vue](https://evolu.dev/docs/api-reference/vue) / [index](https://evolu.dev/docs/api-reference/vue/index) / EvoluProvider
# Variable: EvoluProvider
```ts
const EvoluProvider: DefineComponent<
ExtractPropTypes<{
evolu: {
required: true;
type: () => Evolu<any>;
};
}>,
() =>
| VNode<
RendererNode,
RendererElement,
{
[key: string]: any;
}
>[]
| undefined,
{},
{},
{},
ComponentOptionsMixin,
ComponentOptionsMixin,
{},
string,
PublicProps,
ToResolvedProps<
ExtractPropTypes<{
evolu: {
required: true;
type: () => Evolu<any>;
};
}>,
{}
>,
{},
{},
{},
{},
string,
ComponentProvideOptions,
true,
{},
any
>;
```
Defined in: [packages/vue/src/EvoluProvider.ts:5](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/vue/src/EvoluProvider.ts#L5)
evoluInstanceMap - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/vue](https://evolu.dev/docs/api-reference/vue) / [index](https://evolu.dev/docs/api-reference/vue/index) / evoluInstanceMap
# Variable: evoluInstanceMap
```ts
const evoluInstanceMap: WeakMap<ComponentInternalInstance, Evolu<any>>;
```
Defined in: [packages/vue/src/provideEvolu.ts:13](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/vue/src/provideEvolu.ts#L13)
Stores the Evolu instance for a Vue component. This is most useful at the
root component where provide/inject doesn't work.
EvoluIdenticon - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/react-web](https://evolu.dev/docs/api-reference/react-web) / [index](https://evolu.dev/docs/api-reference/react-web/index) / EvoluIdenticon
# Variable: EvoluIdenticon
```ts
const EvoluIdenticon: FC<{
borderRadius?: number;
id: OwnerId;
size?: number;
style?: IdenticonStyle;
}>;
```
Defined in: [react-web/src/components/EvoluIdenticon.tsx:8](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/react-web/src/components/EvoluIdenticon.tsx#L8)
evoluReactWebDeps - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/react-web](https://evolu.dev/docs/api-reference/react-web) / [index](https://evolu.dev/docs/api-reference/react-web/index) / evoluReactWebDeps
# Variable: evoluReactWebDeps
```ts
const evoluReactWebDeps: EvoluDeps;
```
Defined in: [react-web/src/index.ts:8](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/react-web/src/index.ts#L8)
localAuth - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/react-web](https://evolu.dev/docs/api-reference/react-web) / [index](https://evolu.dev/docs/api-reference/react-web/index) / localAuth
# Variable: localAuth
```ts
const localAuth: LocalAuth;
```
Defined in: web/dist/src/local-first/index.d.ts:2
createSharedWebWorker - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/web](https://evolu.dev/docs/api-reference/web) / [index](https://evolu.dev/docs/api-reference/web/index) / createSharedWebWorker
# Function: createSharedWebWorker()
```ts
function createSharedWebWorker<Input, Output>(
name,
createWebWorker,
): Worker<Input, Output>;
```
Defined in: [SharedWebWorker.ts:59](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/web/src/SharedWebWorker.ts#L59)
Creates a shared Web Worker using BroadcastChannel and Web Locks. This allows
multiple tabs to share a single Web Worker instance. The first tab to acquire
the lock becomes the owner and runs the worker. Other tabs act as proxies,
forwarding messages to the owner.
## Type Parameters
| Type Parameter |
| -------------- |
| `Input` |
| `Output` |
## Parameters
| Parameter | Type |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name` | `string` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"UrlSafeString"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"SimpleName"`\> |
| `createWebWorker` | () => `Worker` |
## Returns
[`Worker`](https://evolu.dev/docs/api-reference/common/Worker/interfaces/Worker)\<`Input`, `Output`\>
wrapWebWorker - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/web](https://evolu.dev/docs/api-reference/web) / [index](https://evolu.dev/docs/api-reference/web/index) / wrapWebWorker
# Function: wrapWebWorker()
```ts
function wrapWebWorker<Input, Output>(createWebWorker): Worker<Input, Output>;
```
Defined in: [WebWorker.ts:17](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/web/src/WebWorker.ts#L17)
Wraps a Web Worker to provide a typed interface for sending and receiving
messages.
## Type Parameters
| Type Parameter |
| -------------- |
| `Input` |
| `Output` |
## Parameters
| Parameter | Type |
| ----------------- | -------------- |
| `createWebWorker` | () => `Worker` |
## Returns
[`Worker`](https://evolu.dev/docs/api-reference/common/Worker/interfaces/Worker)\<`Input`, `Output`\>
wrapWebWorkerSelf - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/web](https://evolu.dev/docs/api-reference/web) / [index](https://evolu.dev/docs/api-reference/web/index) / wrapWebWorkerSelf
# Function: wrapWebWorkerSelf()
```ts
function wrapWebWorkerSelf<Input, Output>(worker): void;
```
Defined in: [WebWorker.ts:44](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/web/src/WebWorker.ts#L44)
## Type Parameters
| Type Parameter |
| -------------- |
| `Input` |
| `Output` |
## Parameters
| Parameter | Type |
| --------- | ---------------------------------------------------------------------------------------- |
| `worker` | [`Worker`](https://evolu.dev/docs/api-reference/common/Worker/interfaces/Worker)\<`Input`, `Output`\> |
## Returns
`void`
createWasmSqliteDriver - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/web](https://evolu.dev/docs/api-reference/web) / [index](https://evolu.dev/docs/api-reference/web/index) / createWasmSqliteDriver
# Variable: createWasmSqliteDriver
```ts
const createWasmSqliteDriver: CreateSqliteDriver;
```
Defined in: [WasmSqliteDriver.ts:31](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/web/src/WasmSqliteDriver.ts#L31)
evoluWebDeps - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/web](https://evolu.dev/docs/api-reference/web) / [index](https://evolu.dev/docs/api-reference/web/index) / evoluWebDeps
# Variable: evoluWebDeps
```ts
const evoluWebDeps: EvoluDeps;
```
Defined in: [local-first/index.ts:35](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/web/src/local-first/index.ts#L35)
localAuth - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/web](https://evolu.dev/docs/api-reference/web) / [index](https://evolu.dev/docs/api-reference/web/index) / localAuth
# Variable: localAuth
```ts
const localAuth: LocalAuth;
```
Defined in: [local-first/index.ts:30](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/web/src/local-first/index.ts#L30)
applyProtocolMessageAsClient - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first/Protocol](https://evolu.dev/docs/api-reference/common/local-first/Protocol) / applyProtocolMessageAsClient
# Function: applyProtocolMessageAsClient()
```ts
function applyProtocolMessageAsClient(
deps,
): (
inputMessage,
options,
) => Promise<
Result<
ApplyProtocolMessageAsClientResult,
| ProtocolVersionError
| ProtocolInvalidDataError
| ProtocolWriteKeyError
| ProtocolWriteError
| ProtocolSyncError
| ProtocolQuotaError
>
>;
```
Defined in: [packages/common/src/local-first/Protocol.ts:903](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Protocol.ts#L903)
## Parameters
| Parameter | Type |
| --------- | -------------------------------------------------------------------------------- |
| `deps` | [`StorageDep`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/StorageDep) |
## Returns
```ts
(inputMessage, options): Promise<Result<ApplyProtocolMessageAsClientResult,
| ProtocolVersionError
| ProtocolInvalidDataError
| ProtocolWriteKeyError
| ProtocolWriteError
| ProtocolSyncError
| ProtocolQuotaError>>;
```
### Parameters
| Parameter | Type |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `inputMessage` | `Uint8Array` |
| `options` | [`ApplyProtocolMessageAsClientOptions`](https://evolu.dev/docs/api-reference/common/local-first/Protocol/interfaces/ApplyProtocolMessageAsClientOptions) |
### Returns
`Promise`\<[`Result`](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result)\<[`ApplyProtocolMessageAsClientResult`](https://evolu.dev/docs/api-reference/common/local-first/Protocol/type-aliases/ApplyProtocolMessageAsClientResult),
\| [`ProtocolVersionError`](https://evolu.dev/docs/api-reference/common/local-first/Protocol/interfaces/ProtocolVersionError)
\| [`ProtocolInvalidDataError`](https://evolu.dev/docs/api-reference/common/local-first/Protocol/interfaces/ProtocolInvalidDataError)
\| [`ProtocolWriteKeyError`](https://evolu.dev/docs/api-reference/common/local-first/Protocol/interfaces/ProtocolWriteKeyError)
\| [`ProtocolWriteError`](https://evolu.dev/docs/api-reference/common/local-first/Protocol/interfaces/ProtocolWriteError)
\| [`ProtocolSyncError`](https://evolu.dev/docs/api-reference/common/local-first/Protocol/interfaces/ProtocolSyncError)
\| [`ProtocolQuotaError`](https://evolu.dev/docs/api-reference/common/local-first/Protocol/interfaces/ProtocolQuotaError)\>\>
applyProtocolMessageAsRelay - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first/Protocol](https://evolu.dev/docs/api-reference/common/local-first/Protocol) / applyProtocolMessageAsRelay
# Function: applyProtocolMessageAsRelay()
```ts
function applyProtocolMessageAsRelay(
deps,
): (
inputMessage,
options,
version,
) => Promise<
Result<ApplyProtocolMessageAsRelayResult, ProtocolInvalidDataError>
>;
```
Defined in: [packages/common/src/local-first/Protocol.ts:1052](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Protocol.ts#L1052)
## Parameters
| Parameter | Type |
| --------- | -------------------------------------------------------------------------------- |
| `deps` | [`StorageDep`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/StorageDep) |
## Returns
```ts
(
inputMessage,
options,
version): Promise<Result<ApplyProtocolMessageAsRelayResult, ProtocolInvalidDataError>>;
```
### Parameters
| Parameter | Type | Default value | Description |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- | --------------- |
| `inputMessage` | `Uint8Array` | `undefined` | - |
| `options` | [`ApplyProtocolMessageAsRelayOptions`](https://evolu.dev/docs/api-reference/common/local-first/Protocol/interfaces/ApplyProtocolMessageAsRelayOptions) | `{}` | - |
| `version` | `number` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Int"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"NonNegative"`\> | `protocolVersion` | For tests only. |
### Returns
`Promise`\<[`Result`](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result)\<[`ApplyProtocolMessageAsRelayResult`](https://evolu.dev/docs/api-reference/common/local-first/Protocol/interfaces/ApplyProtocolMessageAsRelayResult), [`ProtocolInvalidDataError`](https://evolu.dev/docs/api-reference/common/local-first/Protocol/interfaces/ProtocolInvalidDataError)\>\>
createProtocolMessageBuffer - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first/Protocol](https://evolu.dev/docs/api-reference/common/local-first/Protocol) / createProtocolMessageBuffer
# Function: createProtocolMessageBuffer()
```ts
function createProtocolMessageBuffer(ownerId, options): ProtocolMessageBuffer;
```
Defined in: [packages/common/src/local-first/Protocol.ts:575](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Protocol.ts#L575)
## Parameters
| Parameter | Type |
| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ownerId` | `string` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Id"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"OwnerId"`\> |
| `options` | `object` & \| \{ `messageType`: `0`; `subscriptionFlag?`: SubscriptionFlag \| undefined; `writeKey?`: `Uint8Array`\<`ArrayBufferLike`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Entropy"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Length16"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"OwnerWriteKey"`\>; \} \| \{ `errorCode`: [`ProtocolErrorCode`](https://evolu.dev/docs/api-reference/common/local-first/Protocol/variables/ProtocolErrorCode); `messageType`: `1`; \} \| \{ `messageType`: `2`; \} |
## Returns
[`ProtocolMessageBuffer`](https://evolu.dev/docs/api-reference/common/local-first/Protocol/interfaces/ProtocolMessageBuffer)
createProtocolMessageForSync - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first/Protocol](https://evolu.dev/docs/api-reference/common/local-first/Protocol) / createProtocolMessageForSync
# Function: createProtocolMessageForSync()
```ts
function createProtocolMessageForSync(
deps,
): (ownerId, subscriptionFlag?) => ProtocolMessage | null;
```
Defined in: [packages/common/src/local-first/Protocol.ts:517](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Protocol.ts#L517)
Creates a [ProtocolMessage](https://evolu.dev/docs/api-reference/common/local-first/Protocol/type-aliases/ProtocolMessage) for sync.
## Parameters
| Parameter | Type |
| --------- | -------------------------------------------------------------------------------- |
| `deps` | [`StorageDep`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/StorageDep) |
## Returns
```ts
(ownerId, subscriptionFlag?):
| ProtocolMessage
| null;
```
### Parameters
| Parameter | Type |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ownerId` | `string` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Id"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"OwnerId"`\> |
| `subscriptionFlag?` | [`SubscriptionFlag`](https://evolu.dev/docs/api-reference/common/local-first/Protocol/type-aliases/SubscriptionFlag) |
### Returns
\| [`ProtocolMessage`](https://evolu.dev/docs/api-reference/common/local-first/Protocol/type-aliases/ProtocolMessage)
\| `null`
createProtocolMessageForUnsubscribe - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first/Protocol](https://evolu.dev/docs/api-reference/common/local-first/Protocol) / createProtocolMessageForUnsubscribe
# Function: createProtocolMessageForUnsubscribe()
```ts
function createProtocolMessageForUnsubscribe(ownerId): ProtocolMessage;
```
Defined in: [packages/common/src/local-first/Protocol.ts:543](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Protocol.ts#L543)
## Parameters
| Parameter | Type |
| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ownerId` | `string` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Id"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"OwnerId"`\> |
## Returns
[`ProtocolMessage`](https://evolu.dev/docs/api-reference/common/local-first/Protocol/type-aliases/ProtocolMessage)
createProtocolMessageFromCrdtMessages - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first/Protocol](https://evolu.dev/docs/api-reference/common/local-first/Protocol) / createProtocolMessageFromCrdtMessages
# Function: createProtocolMessageFromCrdtMessages()
```ts
function createProtocolMessageFromCrdtMessages(
deps,
): (owner, messages, maxSize?) => ProtocolMessage;
```
Defined in: [packages/common/src/local-first/Protocol.ts:456](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Protocol.ts#L456)
Creates a [ProtocolMessage](https://evolu.dev/docs/api-reference/common/local-first/Protocol/type-aliases/ProtocolMessage) from CRDT messages.
If the message size would exceed [defaultProtocolMessageMaxSize](https://evolu.dev/docs/api-reference/common/local-first/Protocol/variables/defaultProtocolMessageMaxSize), the
protocol ensures all messages will be sent in the next round(s) even over
unidirectional and stateless transports.
## Parameters
| Parameter | Type |
| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `deps` | [`RandomBytesDep`](https://evolu.dev/docs/api-reference/common/Crypto/interfaces/RandomBytesDep) & [`SymmetricCryptoDep`](https://evolu.dev/docs/api-reference/common/Crypto/interfaces/SymmetricCryptoDep) |
## Returns
```ts
(
owner,
messages,
maxSize?): ProtocolMessage;
```
### Parameters
| Parameter | Type |
| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `owner` | [`Owner`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Owner) |
| `messages` | readonly \[[`CrdtMessage`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/CrdtMessage), [`CrdtMessage`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/CrdtMessage)\] |
| `maxSize?` | `number` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Int"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Between1000000-100000000"`\> |
### Returns
[`ProtocolMessage`](https://evolu.dev/docs/api-reference/common/local-first/Protocol/type-aliases/ProtocolMessage)
createTimestampsBuffer - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first/Protocol](https://evolu.dev/docs/api-reference/common/local-first/Protocol) / createTimestampsBuffer
# Function: createTimestampsBuffer()
```ts
function createTimestampsBuffer(): TimestampsBuffer;
```
Defined in: [packages/common/src/local-first/Protocol.ts:792](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Protocol.ts#L792)
## Returns
[`TimestampsBuffer`](https://evolu.dev/docs/api-reference/common/local-first/Protocol/interfaces/TimestampsBuffer)
decodeFlags - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first/Protocol](https://evolu.dev/docs/api-reference/common/local-first/Protocol) / decodeFlags
# Function: decodeFlags()
```ts
function decodeFlags(buffer, count): readonly boolean[];
```
Defined in: [packages/common/src/local-first/Protocol.ts:1697](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Protocol.ts#L1697)
Decodes a byte into an array of boolean flags.
### Example
```ts
const flags = decodeFlags(buffer, 3); // Decode 3 flags
```
## Parameters
| Parameter | Type |
| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `buffer` | [`Buffer`](https://evolu.dev/docs/api-reference/common/Buffer/interfaces/Buffer) |
| `count` | `number` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Int"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"NonNegative"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Positive"`\> |
## Returns
readonly `boolean`[]
decodeNodeId - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first/Protocol](https://evolu.dev/docs/api-reference/common/local-first/Protocol) / decodeNodeId
# Function: decodeNodeId()
```ts
function decodeNodeId(buffer): string & Brand<"NodeId">;
```
Defined in: [packages/common/src/local-first/Protocol.ts:1916](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Protocol.ts#L1916)
## Parameters
| Parameter | Type |
| --------- | ------------------------------------------------------------------- |
| `buffer` | [`Buffer`](https://evolu.dev/docs/api-reference/common/Buffer/interfaces/Buffer) |
## Returns
`string` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"NodeId"`\>
decodeNonNegativeInt - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first/Protocol](https://evolu.dev/docs/api-reference/common/local-first/Protocol) / decodeNonNegativeInt
# Function: decodeNonNegativeInt()
```ts
function decodeNonNegativeInt(
buffer,
): number & Brand<"Int"> & Brand<"NonNegative">;
```
Defined in: [packages/common/src/local-first/Protocol.ts:1875](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Protocol.ts#L1875)
Decodes a non-negative integer from a variable-length integer format.
https://en.wikipedia.org/wiki/Variable-length_quantity
## Parameters
| Parameter | Type |
| --------- | ------------------------------------------------------------------- |
| `buffer` | [`Buffer`](https://evolu.dev/docs/api-reference/common/Buffer/interfaces/Buffer) |
## Returns
`number` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Int"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"NonNegative"`\>
decodeNumber - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first/Protocol](https://evolu.dev/docs/api-reference/common/local-first/Protocol) / decodeNumber
# Function: decodeNumber()
```ts
function decodeNumber(buffer): number;
```
Defined in: [packages/common/src/local-first/Protocol.ts:1640](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Protocol.ts#L1640)
## Parameters
| Parameter | Type |
| --------- | ------------------------------------------------------------------- |
| `buffer` | [`Buffer`](https://evolu.dev/docs/api-reference/common/Buffer/interfaces/Buffer) |
## Returns
`number`
decodeProtocolMessageToJson - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first/Protocol](https://evolu.dev/docs/api-reference/common/local-first/Protocol) / decodeProtocolMessageToJson
# Function: decodeProtocolMessageToJson()
```ts
function decodeProtocolMessageToJson(_protocolMessage, _isInitiator): unknown;
```
Defined in: [packages/common/src/local-first/Protocol.ts:2111](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Protocol.ts#L2111)
Decodes a ProtocolMessage into a readable JSON object for debugging.
Note: This is a stub for future implementation. It should use:
- DecodeVersionAndOwner
- DecodeError or decodeWriteKeys (depending on context)
- DecodeMessages
- DecodeRanges
If you want to help, please contribute to this function.
## Parameters
| Parameter | Type |
| ------------------ | ----------------------------------------------------------------------------------------------------- |
| `_protocolMessage` | [`ProtocolMessage`](https://evolu.dev/docs/api-reference/common/local-first/Protocol/type-aliases/ProtocolMessage) |
| `_isInitiator` | `boolean` |
## Returns
`unknown`
decodeSqliteValue - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first/Protocol](https://evolu.dev/docs/api-reference/common/local-first/Protocol) / decodeSqliteValue
# Function: decodeSqliteValue()
```ts
function decodeSqliteValue(
buffer,
): string | number | Uint8Array<ArrayBufferLike> | null;
```
Defined in: [packages/common/src/local-first/Protocol.ts:2040](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Protocol.ts#L2040)
## Parameters
| Parameter | Type |
| --------- | ------------------------------------------------------------------- |
| `buffer` | [`Buffer`](https://evolu.dev/docs/api-reference/common/Buffer/interfaces/Buffer) |
## Returns
`string` \| `number` \| `Uint8Array`\<`ArrayBufferLike`\> \| `null`
decodeString - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first/Protocol](https://evolu.dev/docs/api-reference/common/local-first/Protocol) / decodeString
# Function: decodeString()
```ts
function decodeString(buffer): string;
```
Defined in: [packages/common/src/local-first/Protocol.ts:1906](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Protocol.ts#L1906)
## Parameters
| Parameter | Type |
| --------- | ------------------------------------------------------------------- |
| `buffer` | [`Buffer`](https://evolu.dev/docs/api-reference/common/Buffer/interfaces/Buffer) |
## Returns
`string`
decryptAndDecodeDbChange - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first/Protocol](https://evolu.dev/docs/api-reference/common/local-first/Protocol) / decryptAndDecodeDbChange
# Function: decryptAndDecodeDbChange()
```ts
function decryptAndDecodeDbChange(deps): (
message,
key,
) => Result<
Readonly<{
id: string & Brand<"Id">;
isDelete: boolean | null;
isInsert: boolean;
table: string;
values: Readonly<
Record<string, string | number | Uint8Array<ArrayBufferLike> | null>
> &
Brand<"ValidDbChangeValues">;
}>,
| SymmetricCryptoDecryptError
| ProtocolInvalidDataError
| ProtocolTimestampMismatchError
>;
```
Defined in: [packages/common/src/local-first/Protocol.ts:1767](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Protocol.ts#L1767)
Decrypts and decodes an [EncryptedCrdtMessage](https://evolu.dev/docs/api-reference/common/local-first/interfaces/EncryptedCrdtMessage) using the provided
owner's encryption key. Verifies that the embedded timestamp matches the
expected timestamp to ensure message integrity.
## Parameters
| Parameter | Type |
| --------- | ------------------------------------------------------------------------------------------- |
| `deps` | [`SymmetricCryptoDep`](https://evolu.dev/docs/api-reference/common/Crypto/interfaces/SymmetricCryptoDep) |
## Returns
```ts
(message, key): Result<Readonly<{
id: string & Brand<"Id">;
isDelete: boolean | null;
isInsert: boolean;
table: string;
values: Readonly<Record<string, string | number | Uint8Array<ArrayBufferLike> | null>> & Brand<"ValidDbChangeValues">;
}>,
| SymmetricCryptoDecryptError
| ProtocolInvalidDataError
| ProtocolTimestampMismatchError>;
```
### Parameters
| Parameter | Type |
| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `message` | [`EncryptedCrdtMessage`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/EncryptedCrdtMessage) |
| `key` | `Uint8Array`\<`ArrayBufferLike`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Entropy"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Length32"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"EncryptionKey"`\> |
### Returns
[`Result`](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result)\<`Readonly`\<\{
`id`: `string` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Id"`\>;
`isDelete`: `boolean` \| `null`;
`isInsert`: `boolean`;
`table`: `string`;
`values`: `Readonly`\<`Record`\<`string`, `string` \| `number` \| `Uint8Array`\<`ArrayBufferLike`\> \| `null`\>\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"ValidDbChangeValues"`\>;
\}\>,
\| [`SymmetricCryptoDecryptError`](https://evolu.dev/docs/api-reference/common/Crypto/interfaces/SymmetricCryptoDecryptError)
\| [`ProtocolInvalidDataError`](https://evolu.dev/docs/api-reference/common/local-first/Protocol/interfaces/ProtocolInvalidDataError)
\| [`ProtocolTimestampMismatchError`](https://evolu.dev/docs/api-reference/common/local-first/Protocol/interfaces/ProtocolTimestampMismatchError)\>
encodeAndEncryptDbChange - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first/Protocol](https://evolu.dev/docs/api-reference/common/local-first/Protocol) / encodeAndEncryptDbChange
# Function: encodeAndEncryptDbChange()
```ts
function encodeAndEncryptDbChange(deps): (message, key) => EncryptedDbChange;
```
Defined in: [packages/common/src/local-first/Protocol.ts:1718](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Protocol.ts#L1718)
Encodes and encrypts a [DbChange](https://evolu.dev/docs/api-reference/common/local-first/variables/DbChange) using the provided owner's encryption
key. Returns an encrypted binary representation as [EncryptedDbChange](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/EncryptedDbChange).
The format includes the protocol version for backward compatibility and the
timestamp for tamper-proof verification that the timestamp matches the change
data.
## Parameters
| Parameter | Type |
| --------- | ------------------------------------------------------------------------------------------- |
| `deps` | [`SymmetricCryptoDep`](https://evolu.dev/docs/api-reference/common/Crypto/interfaces/SymmetricCryptoDep) |
## Returns
```ts
(message, key): EncryptedDbChange;
```
### Parameters
| Parameter | Type |
| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `message` | [`CrdtMessage`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/CrdtMessage) |
| `key` | `Uint8Array`\<`ArrayBufferLike`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Entropy"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Length32"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"EncryptionKey"`\> |
### Returns
[`EncryptedDbChange`](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/EncryptedDbChange)
encodeFlags - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first/Protocol](https://evolu.dev/docs/api-reference/common/local-first/Protocol) / encodeFlags
# Function: encodeFlags()
```ts
function encodeFlags(buffer, flags): void;
```
Defined in: [packages/common/src/local-first/Protocol.ts:1675](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Protocol.ts#L1675)
Encodes an array of boolean flags into a single byte.
Each element in the array corresponds to a bit (0-7). Array can have 0-8
elements.
### Example
```ts
encodeFlags(buffer, [true, false, true]); // Encodes bits 0, 1, 2
```
## Parameters
| Parameter | Type |
| --------- | ------------------------------------------------------------------- |
| `buffer` | [`Buffer`](https://evolu.dev/docs/api-reference/common/Buffer/interfaces/Buffer) |
| `flags` | readonly `boolean`[] |
## Returns
`void`
encodeLength - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first/Protocol](https://evolu.dev/docs/api-reference/common/local-first/Protocol) / encodeLength
# Function: encodeLength()
```ts
function encodeLength(buffer, value): void;
```
Defined in: [packages/common/src/local-first/Protocol.ts:1894](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Protocol.ts#L1894)
## Parameters
| Parameter | Type |
| --------- | ------------------------------------------------------------------- |
| `buffer` | [`Buffer`](https://evolu.dev/docs/api-reference/common/Buffer/interfaces/Buffer) |
| `value` | `ArrayLike`\<`any`\> |
## Returns
`void`
encodeNodeId - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first/Protocol](https://evolu.dev/docs/api-reference/common/local-first/Protocol) / encodeNodeId
# Function: encodeNodeId()
```ts
function encodeNodeId(buffer, nodeId): void;
```
Defined in: [packages/common/src/local-first/Protocol.ts:1912](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Protocol.ts#L1912)
## Parameters
| Parameter | Type |
| --------- | ----------------------------------------------------------------------------------------- |
| `buffer` | [`Buffer`](https://evolu.dev/docs/api-reference/common/Buffer/interfaces/Buffer) |
| `nodeId` | `string` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"NodeId"`\> |
## Returns
`void`
encodeNonNegativeInt - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first/Protocol](https://evolu.dev/docs/api-reference/common/local-first/Protocol) / encodeNonNegativeInt
# Function: encodeNonNegativeInt()
```ts
function encodeNonNegativeInt(buffer, int): void;
```
Defined in: [packages/common/src/local-first/Protocol.ts:1845](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Protocol.ts#L1845)
Encodes a non-negative integer into a variable-length integer format. It's
more efficient than encoding via [encodeNumber](https://evolu.dev/docs/api-reference/common/local-first/Protocol/functions/encodeNumber).
https://en.wikipedia.org/wiki/Variable-length_quantity
## Parameters
| Parameter | Type |
| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `buffer` | [`Buffer`](https://evolu.dev/docs/api-reference/common/Buffer/interfaces/Buffer) |
| `int` | `number` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Int"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"NonNegative"`\> |
## Returns
`void`
encodeNumber - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first/Protocol](https://evolu.dev/docs/api-reference/common/local-first/Protocol) / encodeNumber
# Function: encodeNumber()
```ts
function encodeNumber(buffer, number): void;
```
Defined in: [packages/common/src/local-first/Protocol.ts:1636](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Protocol.ts#L1636)
Evolu uses MessagePack to handle all number variants except for
NonNegativeInt. For NonNegativeInt, Evolu provides more efficient encoding.
## Parameters
| Parameter | Type |
| --------- | ------------------------------------------------------------------- |
| `buffer` | [`Buffer`](https://evolu.dev/docs/api-reference/common/Buffer/interfaces/Buffer) |
| `number` | `number` |
## Returns
`void`
encodeSqliteValue - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first/Protocol](https://evolu.dev/docs/api-reference/common/local-first/Protocol) / encodeSqliteValue
# Function: encodeSqliteValue()
```ts
function encodeSqliteValue(buffer, value): void;
```
Defined in: [packages/common/src/local-first/Protocol.ts:1954](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Protocol.ts#L1954)
## Parameters
| Parameter | Type |
| --------- | ------------------------------------------------------------------- |
| `buffer` | [`Buffer`](https://evolu.dev/docs/api-reference/common/Buffer/interfaces/Buffer) |
| `value` | `string` \| `number` \| `Uint8Array`\<`ArrayBufferLike`\> \| `null` |
## Returns
`void`
encodeString - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first/Protocol](https://evolu.dev/docs/api-reference/common/local-first/Protocol) / encodeString
# Function: encodeString()
```ts
function encodeString(buffer, value): void;
```
Defined in: [packages/common/src/local-first/Protocol.ts:1900](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Protocol.ts#L1900)
## Parameters
| Parameter | Type |
| --------- | ------------------------------------------------------------------- |
| `buffer` | [`Buffer`](https://evolu.dev/docs/api-reference/common/Buffer/interfaces/Buffer) |
| `value` | `string` |
## Returns
`void`
ApplyProtocolMessageAsClientOptions - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first/Protocol](https://evolu.dev/docs/api-reference/common/local-first/Protocol) / ApplyProtocolMessageAsClientOptions
# Interface: ApplyProtocolMessageAsClientOptions
Defined in: [packages/common/src/local-first/Protocol.ts:884](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Protocol.ts#L884)
## Properties
| Property | Type | Description | Defined in |
| ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="getwritekey"></a> `getWriteKey?` | (`ownerId`) => \| `Uint8Array`\<`ArrayBufferLike`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Entropy"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Length16"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"OwnerWriteKey"`\> \| `null` | - | [packages/common/src/local-first/Protocol.ts:885](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Protocol.ts#L885) |
| <a id="rangesmaxsize"></a> `rangesMaxSize?` | `number` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Int"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Between3000-100000"`\> | - | [packages/common/src/local-first/Protocol.ts:887](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Protocol.ts#L887) |
| <a id="version"></a> `version?` | `number` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Int"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"NonNegative"`\> | For tests only. | [packages/common/src/local-first/Protocol.ts:890](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Protocol.ts#L890) |
ApplyProtocolMessageAsRelayOptions - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first/Protocol](https://evolu.dev/docs/api-reference/common/local-first/Protocol) / ApplyProtocolMessageAsRelayOptions
# Interface: ApplyProtocolMessageAsRelayOptions
Defined in: [packages/common/src/local-first/Protocol.ts:1023](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Protocol.ts#L1023)
## Properties
| Property | Type | Description | Defined in |
| ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| <a id="broadcast"></a> `broadcast?` | (`ownerId`, `message`) => `void` | To broadcast a protocol message to all subscribers. | [packages/common/src/local-first/Protocol.ts:1031](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Protocol.ts#L1031) |
| <a id="rangesmaxsize"></a> `rangesMaxSize?` | `number` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Int"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Between3000-100000"`\> | - | [packages/common/src/local-first/Protocol.ts:1034](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Protocol.ts#L1034) |
| <a id="subscribe"></a> `subscribe?` | (`ownerId`) => `void` | To subscribe an owner for broadcasting. | [packages/common/src/local-first/Protocol.ts:1025](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Protocol.ts#L1025) |
| <a id="totalmaxsize"></a> `totalMaxSize?` | `number` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Int"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Between1000000-100000000"`\> | - | [packages/common/src/local-first/Protocol.ts:1033](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Protocol.ts#L1033) |
| <a id="unsubscribe"></a> `unsubscribe?` | (`ownerId`) => `void` | To unsubscribe an owner from broadcasting. | [packages/common/src/local-first/Protocol.ts:1028](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Protocol.ts#L1028) |
ApplyProtocolMessageAsRelayResult - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first/Protocol](https://evolu.dev/docs/api-reference/common/local-first/Protocol) / ApplyProtocolMessageAsRelayResult
# Interface: ApplyProtocolMessageAsRelayResult
Defined in: [packages/common/src/local-first/Protocol.ts:1046](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Protocol.ts#L1046)
Result type for [applyProtocolMessageAsRelay](https://evolu.dev/docs/api-reference/common/local-first/Protocol/functions/applyProtocolMessageAsRelay).
Unlike [ApplyProtocolMessageAsClientResult](https://evolu.dev/docs/api-reference/common/local-first/Protocol/type-aliases/ApplyProtocolMessageAsClientResult), relays always respond with
a message to provide sync completion feedback. This ensures the initiator can
reliably detect when synchronization is complete, even when there's nothing
to sync. Clients may choose not to respond in certain cases (like when they
receive broadcast messages or when they lack a write key for syncing).
## Properties
| Property | Modifier | Type | Defined in |
| ------------------------------ | ---------- | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| <a id="message"></a> `message` | `readonly` | [`ProtocolMessage`](https://evolu.dev/docs/api-reference/common/local-first/Protocol/type-aliases/ProtocolMessage) | [packages/common/src/local-first/Protocol.ts:1048](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Protocol.ts#L1048) |
| <a id="type"></a> `type` | `readonly` | `"response"` | [packages/common/src/local-first/Protocol.ts:1047](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Protocol.ts#L1047) |
ProtocolInvalidDataError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first/Protocol](https://evolu.dev/docs/api-reference/common/local-first/Protocol) / ProtocolInvalidDataError
# Interface: ProtocolInvalidDataError
Defined in: [packages/common/src/local-first/Protocol.ts:393](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Protocol.ts#L393)
Error for invalid or corrupted protocol message data.
## Properties
| Property | Modifier | Type | Defined in |
| -------------------------- | ---------- | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="data"></a> `data` | `readonly` | `Uint8Array` | [packages/common/src/local-first/Protocol.ts:395](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Protocol.ts#L395) |
| <a id="error"></a> `error` | `readonly` | `unknown` | [packages/common/src/local-first/Protocol.ts:396](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Protocol.ts#L396) |
| <a id="type"></a> `type` | `readonly` | `"ProtocolInvalidDataError"` | [packages/common/src/local-first/Protocol.ts:394](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Protocol.ts#L394) |
ProtocolMessageBuffer - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first/Protocol](https://evolu.dev/docs/api-reference/common/local-first/Protocol) / ProtocolMessageBuffer
# Interface: ProtocolMessageBuffer
Defined in: [packages/common/src/local-first/Protocol.ts:555](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Protocol.ts#L555)
Mutable builder for constructing [ProtocolMessage](https://evolu.dev/docs/api-reference/common/local-first/Protocol/type-aliases/ProtocolMessage) respecting size
limits.
## Properties
| Property | Modifier | Type | Defined in |
| ------------------------------------------------------------------------------ | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="addmessage"></a> `addMessage` | `readonly` | (`message`) => `void` | [packages/common/src/local-first/Protocol.ts:558](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Protocol.ts#L558) |
| <a id="addrange"></a> `addRange` | `readonly` | (`range`) => `void` | [packages/common/src/local-first/Protocol.ts:567](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Protocol.ts#L567) |
| <a id="canaddmessage"></a> `canAddMessage` | `readonly` | (`message`) => `boolean` | [packages/common/src/local-first/Protocol.ts:556](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Protocol.ts#L556) |
| <a id="canaddtimestampsrangeandmessage"></a> `canAddTimestampsRangeAndMessage` | `readonly` | (`timestamps`, `message`) => `boolean` | [packages/common/src/local-first/Protocol.ts:562](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Protocol.ts#L562) |
| <a id="cansplitrange"></a> `canSplitRange` | `readonly` | () => `boolean` | [packages/common/src/local-first/Protocol.ts:560](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Protocol.ts#L560) |
| <a id="getsize"></a> `getSize` | `readonly` | () => `number` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Int"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"NonNegative"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Positive"`\> | [packages/common/src/local-first/Protocol.ts:572](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Protocol.ts#L572) |
| <a id="unwrap"></a> `unwrap` | `readonly` | () => [`ProtocolMessage`](https://evolu.dev/docs/api-reference/common/local-first/Protocol/type-aliases/ProtocolMessage) | [packages/common/src/local-first/Protocol.ts:571](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Protocol.ts#L571) |
ProtocolQuotaError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first/Protocol](https://evolu.dev/docs/api-reference/common/local-first/Protocol) / ProtocolQuotaError
# Interface: ProtocolQuotaError
Defined in: [packages/common/src/local-first/Protocol.ts:425](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Protocol.ts#L425)
Error when storage or billing quota is exceeded.
When relay rejects writes due to quota, the affected device stops syncing
because RBSR requires both sides to converge—if the relay won't accept the
client's data, they can never reach the same state. Only the device with
excess local data is affected. Other devices that haven't exceeded quota can
still sync normally.
Clients should prompt the user to contact the relay provider or upgrade their
plan. Quota monitoring and management is the relay provider's
responsibility.
## Extends
- [`OwnerError`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/OwnerError)
## Properties
| Property | Modifier | Type | Inherited from | Defined in |
| ------------------------------ | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="ownerid"></a> `ownerId` | `readonly` | `string` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Id"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"OwnerId"`\> | [`OwnerError`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/OwnerError).[`ownerId`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/OwnerError.mdx#ownerid) | [packages/common/src/local-first/Owner.ts:386](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Owner.ts#L386) |
| <a id="type"></a> `type` | `readonly` | `"ProtocolQuotaError"` | - | [packages/common/src/local-first/Protocol.ts:426](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Protocol.ts#L426) |
ProtocolSyncError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first/Protocol](https://evolu.dev/docs/api-reference/common/local-first/Protocol) / ProtocolSyncError
# Interface: ProtocolSyncError
Defined in: [packages/common/src/local-first/Protocol.ts:433](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Protocol.ts#L433)
Error indicating a serious relay-side synchronization failure. Clients should
log this error and show a generic sync error to the user.
## Extends
- [`OwnerError`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/OwnerError)
## Properties
| Property | Modifier | Type | Inherited from | Defined in |
| ------------------------------ | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="ownerid"></a> `ownerId` | `readonly` | `string` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Id"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"OwnerId"`\> | [`OwnerError`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/OwnerError).[`ownerId`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/OwnerError.mdx#ownerid) | [packages/common/src/local-first/Owner.ts:386](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Owner.ts#L386) |
| <a id="type"></a> `type` | `readonly` | `"ProtocolSyncError"` | - | [packages/common/src/local-first/Protocol.ts:434](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Protocol.ts#L434) |
ProtocolTimestampMismatchError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first/Protocol](https://evolu.dev/docs/api-reference/common/local-first/Protocol) / ProtocolTimestampMismatchError
# Interface: ProtocolTimestampMismatchError
Defined in: [packages/common/src/local-first/Protocol.ts:442](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Protocol.ts#L442)
Error when embedded timestamp doesn't match expected timestamp in
EncryptedDbChange. Indicates potential tampering or corruption of CRDT
messages.
## Properties
| Property | Modifier | Type | Defined in |
| ---------------------------------- | ---------- | ------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="expected"></a> `expected` | `readonly` | [`Timestamp`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Timestamp) | [packages/common/src/local-first/Protocol.ts:444](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Protocol.ts#L444) |
| <a id="timestamp"></a> `timestamp` | `readonly` | [`Timestamp`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/Timestamp) | [packages/common/src/local-first/Protocol.ts:445](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Protocol.ts#L445) |
| <a id="type"></a> `type` | `readonly` | `"ProtocolTimestampMismatchError"` | [packages/common/src/local-first/Protocol.ts:443](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Protocol.ts#L443) |
ProtocolVersionError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first/Protocol](https://evolu.dev/docs/api-reference/common/local-first/Protocol) / ProtocolVersionError
# Interface: ProtocolVersionError
Defined in: [packages/common/src/local-first/Protocol.ts:385](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Protocol.ts#L385)
Represents a version mismatch in the Evolu Protocol. Occurs when the
initiator and non-initiator are using incompatible protocol versions.
## Extends
- [`OwnerError`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/OwnerError)
## Properties
| Property | Modifier | Type | Description | Inherited from | Defined in |
| -------------------------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="isinitiator"></a> `isInitiator` | `readonly` | `boolean` | Indicates which side is obsolete and should update. | - | [packages/common/src/local-first/Protocol.ts:389](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Protocol.ts#L389) |
| <a id="ownerid"></a> `ownerId` | `readonly` | `string` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Id"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"OwnerId"`\> | - | [`OwnerError`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/OwnerError).[`ownerId`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/OwnerError.mdx#ownerid) | [packages/common/src/local-first/Owner.ts:386](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Owner.ts#L386) |
| <a id="type"></a> `type` | `readonly` | `"ProtocolVersionError"` | - | - | [packages/common/src/local-first/Protocol.ts:386](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Protocol.ts#L386) |
| <a id="version"></a> `version` | `readonly` | `number` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Int"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"NonNegative"`\> | - | - | [packages/common/src/local-first/Protocol.ts:387](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Protocol.ts#L387) |
ProtocolWriteError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first/Protocol](https://evolu.dev/docs/api-reference/common/local-first/Protocol) / ProtocolWriteError
# Interface: ProtocolWriteError
Defined in: [packages/common/src/local-first/Protocol.ts:408](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Protocol.ts#L408)
Error indicating a serious relay-side write failure. Clients should log this
error and show a generic sync error to the user.
## Extends
- [`OwnerError`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/OwnerError)
## Properties
| Property | Modifier | Type | Inherited from | Defined in |
| ------------------------------ | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="ownerid"></a> `ownerId` | `readonly` | `string` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Id"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"OwnerId"`\> | [`OwnerError`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/OwnerError).[`ownerId`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/OwnerError.mdx#ownerid) | [packages/common/src/local-first/Owner.ts:386](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Owner.ts#L386) |
| <a id="type"></a> `type` | `readonly` | `"ProtocolWriteError"` | - | [packages/common/src/local-first/Protocol.ts:409](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Protocol.ts#L409) |
ProtocolWriteKeyError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first/Protocol](https://evolu.dev/docs/api-reference/common/local-first/Protocol) / ProtocolWriteKeyError
# Interface: ProtocolWriteKeyError
Defined in: [packages/common/src/local-first/Protocol.ts:400](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Protocol.ts#L400)
Error when a [OwnerWriteKey](https://evolu.dev/docs/api-reference/common/local-first/variables/OwnerWriteKey) is invalid, missing, or fails validation.
## Extends
- [`OwnerError`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/OwnerError)
## Properties
| Property | Modifier | Type | Inherited from | Defined in |
| ------------------------------ | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="ownerid"></a> `ownerId` | `readonly` | `string` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Id"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"OwnerId"`\> | [`OwnerError`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/OwnerError).[`ownerId`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/OwnerError.mdx#ownerid) | [packages/common/src/local-first/Owner.ts:386](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Owner.ts#L386) |
| <a id="type"></a> `type` | `readonly` | `"ProtocolWriteKeyError"` | - | [packages/common/src/local-first/Protocol.ts:401](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Protocol.ts#L401) |
TimestampsBuffer - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first/Protocol](https://evolu.dev/docs/api-reference/common/local-first/Protocol) / TimestampsBuffer
# Interface: TimestampsBuffer
Defined in: [packages/common/src/local-first/Protocol.ts:784](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Protocol.ts#L784)
## Properties
| Property | Modifier | Type | Defined in |
| -------------------------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="add"></a> `add` | `readonly` | (`timestamp`) => `void` | [packages/common/src/local-first/Protocol.ts:785](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Protocol.ts#L785) |
| <a id="addinfinite"></a> `addInfinite` | `readonly` | () => `void` | [packages/common/src/local-first/Protocol.ts:786](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Protocol.ts#L786) |
| <a id="append"></a> `append` | `readonly` | (`buffer`) => `void` | [packages/common/src/local-first/Protocol.ts:789](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Protocol.ts#L789) |
| <a id="getcount"></a> `getCount` | `readonly` | () => `number` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Int"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"NonNegative"`\> | [packages/common/src/local-first/Protocol.ts:787](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Protocol.ts#L787) |
| <a id="getlength"></a> `getLength` | `readonly` | () => `number` | [packages/common/src/local-first/Protocol.ts:788](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Protocol.ts#L788) |
TimestampsRangeWithTimestampsBuffer - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first/Protocol](https://evolu.dev/docs/api-reference/common/local-first/Protocol) / TimestampsRangeWithTimestampsBuffer
# Interface: TimestampsRangeWithTimestampsBuffer
Defined in: [packages/common/src/local-first/Protocol.ts:779](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Protocol.ts#L779)
## Extends
- [`BaseRange`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/BaseRange)
## Properties
| Property | Modifier | Type | Inherited from | Defined in |
| ------------------------------------ | ---------- | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="timestamps"></a> `timestamps` | `readonly` | [`TimestampsBuffer`](https://evolu.dev/docs/api-reference/common/local-first/Protocol/interfaces/TimestampsBuffer) | - | [packages/common/src/local-first/Protocol.ts:781](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Protocol.ts#L781) |
| <a id="type"></a> `type` | `readonly` | `2` | - | [packages/common/src/local-first/Protocol.ts:780](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Protocol.ts#L780) |
| <a id="upperbound"></a> `upperBound` | `readonly` | [`RangeUpperBound`](https://evolu.dev/docs/api-reference/common/local-first/type-aliases/RangeUpperBound) | [`BaseRange`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/BaseRange).[`upperBound`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/BaseRange.mdx#upperbound) | [packages/common/src/local-first/Storage.ts:199](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Storage.ts#L199) |
ApplyProtocolMessageAsClientResult - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first/Protocol](https://evolu.dev/docs/api-reference/common/local-first/Protocol) / ApplyProtocolMessageAsClientResult
# Type Alias: ApplyProtocolMessageAsClientResult
```ts
type ApplyProtocolMessageAsClientResult =
| {
message: ProtocolMessage;
type: "response";
}
| {
type: "no-response";
}
| {
type: "broadcast";
};
```
Defined in: [packages/common/src/local-first/Protocol.ts:897](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Protocol.ts#L897)
Result type for [applyProtocolMessageAsClient](https://evolu.dev/docs/api-reference/common/local-first/Protocol/functions/applyProtocolMessageAsClient) that distinguishes
between responses to client requests and broadcast messages.
MessageType - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first/Protocol](https://evolu.dev/docs/api-reference/common/local-first/Protocol) / MessageType
# Type Alias: MessageType
```ts
type MessageType = (typeof MessageType)[keyof typeof MessageType];
```
Defined in: [packages/common/src/local-first/Protocol.ts:334](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Protocol.ts#L334)
ProtocolError - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first/Protocol](https://evolu.dev/docs/api-reference/common/local-first/Protocol) / ProtocolError
# Type Alias: ProtocolError
```ts
type ProtocolError =
| ProtocolVersionError
| ProtocolInvalidDataError
| ProtocolWriteKeyError
| ProtocolWriteError
| ProtocolSyncError
| ProtocolQuotaError
| ProtocolTimestampMismatchError;
```
Defined in: [packages/common/src/local-first/Protocol.ts:372](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Protocol.ts#L372)
ProtocolMessage - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first/Protocol](https://evolu.dev/docs/api-reference/common/local-first/Protocol) / ProtocolMessage
# Type Alias: ProtocolMessage
```ts
type ProtocolMessage = Uint8Array & Brand<"ProtocolMessage">;
```
Defined in: [packages/common/src/local-first/Protocol.ts:329](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Protocol.ts#L329)
Evolu Protocol Message.
ProtocolMessageMaxSize - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first/Protocol](https://evolu.dev/docs/api-reference/common/local-first/Protocol) / ProtocolMessageMaxSize
# Type Alias: ProtocolMessageMaxSize
```ts
type ProtocolMessageMaxSize = typeof Type;
```
Defined in: [packages/common/src/local-first/Protocol.ts:288](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Protocol.ts#L288)
ProtocolMessageRangesMaxSize - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first/Protocol](https://evolu.dev/docs/api-reference/common/local-first/Protocol) / ProtocolMessageRangesMaxSize
# Type Alias: ProtocolMessageRangesMaxSize
```ts
type ProtocolMessageRangesMaxSize = typeof Type;
```
Defined in: [packages/common/src/local-first/Protocol.ts:315](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Protocol.ts#L315)
SubscriptionFlag - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first/Protocol](https://evolu.dev/docs/api-reference/common/local-first/Protocol) / SubscriptionFlag
# Type Alias: SubscriptionFlag
```ts
type SubscriptionFlag =
(typeof SubscriptionFlags)[keyof typeof SubscriptionFlags];
```
Defined in: [packages/common/src/local-first/Protocol.ts:354](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Protocol.ts#L354)
MessageType - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first/Protocol](https://evolu.dev/docs/api-reference/common/local-first/Protocol) / MessageType
# Variable: MessageType
```ts
const MessageType: object;
```
Defined in: [packages/common/src/local-first/Protocol.ts:334](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Protocol.ts#L334)
## Type Declaration
| Name | Type | Default value | Description | Defined in |
| ---------------------------------- | ---- | ------------- | ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="broadcast"></a> `Broadcast` | `2` | `2` | Broadcast message from non-initiator (relay) to subscribed clients. | [packages/common/src/local-first/Protocol.ts:340](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Protocol.ts#L340) |
| <a id="request"></a> `Request` | `0` | `0` | Request message from initiator (client) to non-initiator (relay). | [packages/common/src/local-first/Protocol.ts:336](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Protocol.ts#L336) |
| <a id="response"></a> `Response` | `1` | `1` | Response message from non-initiator (relay) to initiator (client). | [packages/common/src/local-first/Protocol.ts:338](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Protocol.ts#L338) |
ProtocolErrorCode - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first/Protocol](https://evolu.dev/docs/api-reference/common/local-first/Protocol) / ProtocolErrorCode
# Variable: ProtocolErrorCode
```ts
const ProtocolErrorCode: object;
```
Defined in: [packages/common/src/local-first/Protocol.ts:357](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Protocol.ts#L357)
## Type Declaration
| Name | Type | Default value | Description | Defined in |
| ------------------------------------------ | ---- | ------------- | ------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="noerror"></a> `NoError` | `0` | `0` | - | [packages/common/src/local-first/Protocol.ts:358](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Protocol.ts#L358) |
| <a id="quotaerror"></a> `QuotaError` | `3` | `3` | A code for [ProtocolQuotaError](https://evolu.dev/docs/api-reference/common/local-first/Protocol/interfaces/ProtocolQuotaError). | [packages/common/src/local-first/Protocol.ts:364](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Protocol.ts#L364) |
| <a id="syncerror"></a> `SyncError` | `4` | `4` | A code for [ProtocolSyncError](https://evolu.dev/docs/api-reference/common/local-first/Protocol/interfaces/ProtocolSyncError). | [packages/common/src/local-first/Protocol.ts:366](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Protocol.ts#L366) |
| <a id="writeerror"></a> `WriteError` | `2` | `2` | A code for [ProtocolWriteError](https://evolu.dev/docs/api-reference/common/local-first/Protocol/interfaces/ProtocolWriteError). | [packages/common/src/local-first/Protocol.ts:362](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Protocol.ts#L362) |
| <a id="writekeyerror"></a> `WriteKeyError` | `1` | `1` | A code for [ProtocolWriteKeyError](https://evolu.dev/docs/api-reference/common/local-first/Protocol/interfaces/ProtocolWriteKeyError). | [packages/common/src/local-first/Protocol.ts:360](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Protocol.ts#L360) |
ProtocolMessageMaxSize - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first/Protocol](https://evolu.dev/docs/api-reference/common/local-first/Protocol) / ProtocolMessageMaxSize
# Variable: ProtocolMessageMaxSize
```ts
const ProtocolMessageMaxSize: BrandType<
Type<"Brand", number & Brand<"Int">, number, IntError, number, NumberError>,
"Between1000000-100000000",
BetweenError<1000000, 100000000>,
IntError | NumberError
>;
```
Defined in: [packages/common/src/local-first/Protocol.ts:288](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Protocol.ts#L288)
Protocol message maximum size.
Defines the upper limit for how large a single protocol message can be.
Implementations must enforce a maximum size between 1MB and 100MB to ensure
compatibility across all Evolu implementations (the maximum size of mutation
change is hardcoded and enforced hence the maximum size can't be smaller).
Larger maximum sizes can be configured by relays to reduce roundtrips. For
example, a dedicated relay with ample resources could configure a 100MB
maximum to minimize roundtrips for large syncs.
Only relays can safely configure larger sizes, as clients will handle them.
Increasing this value on the client side would break compatibility with
relays that enforce smaller limits.
ProtocolMessageRangesMaxSize - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first/Protocol](https://evolu.dev/docs/api-reference/common/local-first/Protocol) / ProtocolMessageRangesMaxSize
# Variable: ProtocolMessageRangesMaxSize
```ts
const ProtocolMessageRangesMaxSize: BrandType<
Type<"Brand", number & Brand<"Int">, number, IntError, number, NumberError>,
"Between3000-100000",
BetweenError<3000, 100000>,
IntError | NumberError
>;
```
Defined in: [packages/common/src/local-first/Protocol.ts:315](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Protocol.ts#L315)
Protocol message ranges maximum size.
Defines the upper limit for how large the ranges section of a protocol
message can be. Implementations must enforce a maximum size between 3KB and
100KB to ensure compatibility.
The upper bound is set to ensure ranges fit within the default 1MB
[defaultProtocolMessageMaxSize](https://evolu.dev/docs/api-reference/common/local-first/Protocol/variables/defaultProtocolMessageMaxSize), maintaining compatibility between all
clients and relays.
ProtocolValueType - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first/Protocol](https://evolu.dev/docs/api-reference/common/local-first/Protocol) / ProtocolValueType
# Variable: ProtocolValueType
```ts
const ProtocolValueType: object;
```
Defined in: [packages/common/src/local-first/Protocol.ts:1925](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Protocol.ts#L1925)
## Type Declaration
| Name | Type | Defined in |
| -------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| <a id="base64url"></a> `Base64Url` | `number` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Int"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"NonNegative"`\> | [packages/common/src/local-first/Protocol.ts:1940](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Protocol.ts#L1940) |
| <a id="bytes"></a> `Bytes` | `number` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Int"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"NonNegative"`\> | [packages/common/src/local-first/Protocol.ts:1932](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Protocol.ts#L1932) |
| <a id="dateisowithnegativetime"></a> `DateIsoWithNegativeTime` | `number` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Int"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"NonNegative"`\> | [packages/common/src/local-first/Protocol.ts:1948](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Protocol.ts#L1948) |
| <a id="dateisowithnonnegativetime"></a> `DateIsoWithNonNegativeTime` | `number` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Int"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"NonNegative"`\> | [packages/common/src/local-first/Protocol.ts:1947](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Protocol.ts#L1947) |
| <a id="emptystring"></a> `EmptyString` | `number` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Int"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"NonNegative"`\> | [packages/common/src/local-first/Protocol.ts:1939](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Protocol.ts#L1939) |
| <a id="id"></a> `Id` | `number` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Int"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"NonNegative"`\> | [packages/common/src/local-first/Protocol.ts:1941](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Protocol.ts#L1941) |
| <a id="json"></a> `Json` | `number` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Int"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"NonNegative"`\> | [packages/common/src/local-first/Protocol.ts:1942](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Protocol.ts#L1942) |
| <a id="nonnegativeint"></a> `NonNegativeInt` | `number` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Int"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"NonNegative"`\> | [packages/common/src/local-first/Protocol.ts:1936](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Protocol.ts#L1936) |
| <a id="null"></a> `Null` | `number` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Int"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"NonNegative"`\> | [packages/common/src/local-first/Protocol.ts:1931](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Protocol.ts#L1931) |
| <a id="number"></a> `Number` | `number` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Int"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"NonNegative"`\> | [packages/common/src/local-first/Protocol.ts:1930](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Protocol.ts#L1930) |
| <a id="string"></a> `String` | `number` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Int"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"NonNegative"`\> | [packages/common/src/local-first/Protocol.ts:1929](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Protocol.ts#L1929) |
SubscriptionFlags - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first/Protocol](https://evolu.dev/docs/api-reference/common/local-first/Protocol) / SubscriptionFlags
# Variable: SubscriptionFlags
```ts
const SubscriptionFlags: object;
```
Defined in: [packages/common/src/local-first/Protocol.ts:345](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Protocol.ts#L345)
## Type Declaration
| Name | Type | Default value | Description | Defined in |
| -------------------------------------- | ---- | ------------- | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="none"></a> `None` | `0` | `0` | No subscription changes for this owner. | [packages/common/src/local-first/Protocol.ts:347](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Protocol.ts#L347) |
| <a id="subscribe"></a> `Subscribe` | `1` | `1` | Subscribe to updates for this owner. | [packages/common/src/local-first/Protocol.ts:349](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Protocol.ts#L349) |
| <a id="unsubscribe"></a> `Unsubscribe` | `2` | `2` | Unsubscribe from updates for this owner. | [packages/common/src/local-first/Protocol.ts:351](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Protocol.ts#L351) |
decodeLength - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first/Protocol](https://evolu.dev/docs/api-reference/common/local-first/Protocol) / decodeLength
# Variable: decodeLength()
```ts
const decodeLength: (buffer) => number & Brand<"Int"> & Brand<"NonNegative"> =
decodeNonNegativeInt;
```
Defined in: [packages/common/src/local-first/Protocol.ts:1898](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Protocol.ts#L1898)
Decodes a non-negative integer from a variable-length integer format.
https://en.wikipedia.org/wiki/Variable-length_quantity
## Parameters
| Parameter | Type |
| --------- | ------------------------------------------------------------------- |
| `buffer` | [`Buffer`](https://evolu.dev/docs/api-reference/common/Buffer/interfaces/Buffer) |
## Returns
`number` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Int"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"NonNegative"`\>
defaultProtocolMessageMaxSize - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first/Protocol](https://evolu.dev/docs/api-reference/common/local-first/Protocol) / defaultProtocolMessageMaxSize
# Variable: defaultProtocolMessageMaxSize
```ts
const defaultProtocolMessageMaxSize: number &
Brand<"Int"> &
Brand<"Between1000000-100000000">;
```
Defined in: [packages/common/src/local-first/Protocol.ts:301](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Protocol.ts#L301)
Default [ProtocolMessageMaxSize](https://evolu.dev/docs/api-reference/common/local-first/Protocol/variables/ProtocolMessageMaxSize) (1MB).
The standard size used across Evolu implementations. Relays with more
resources can configure larger sizes to reduce roundtrips.
defaultProtocolMessageRangesMaxSize - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first/Protocol](https://evolu.dev/docs/api-reference/common/local-first/Protocol) / defaultProtocolMessageRangesMaxSize
# Variable: defaultProtocolMessageRangesMaxSize
```ts
const defaultProtocolMessageRangesMaxSize: number &
Brand<"Int"> &
Brand<"Between3000-100000">;
```
Defined in: [packages/common/src/local-first/Protocol.ts:325](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Protocol.ts#L325)
Default [ProtocolMessageRangesMaxSize](https://evolu.dev/docs/api-reference/common/local-first/Protocol/variables/ProtocolMessageRangesMaxSize) (30KB).
The standard size used across Evolu implementations. Relays with more
resources can configure larger sizes to reduce roundtrips.
protocolVersion - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first/Protocol](https://evolu.dev/docs/api-reference/common/local-first/Protocol) / protocolVersion
# Variable: protocolVersion
```ts
const protocolVersion: number & Brand<"Int"> & Brand<"NonNegative">;
```
Defined in: [packages/common/src/local-first/Protocol.ts:332](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/Protocol.ts#L332)
Evolu Protocol version.
createLocalAuth - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first/Public](https://evolu.dev/docs/api-reference/common/local-first/Public) / createLocalAuth
# Function: createLocalAuth()
```ts
function createLocalAuth(deps): LocalAuth;
```
Defined in: [packages/common/src/local-first/LocalAuth.ts:80](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/LocalAuth.ts#L80)
Creates a local auth using the given secure storage implementation. This
factory function allows each platform to provide its own storage layer while
sharing the common auth logic.
## Parameters
| Parameter | Type |
| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `deps` | [`SecureStorageDep`](https://evolu.dev/docs/api-reference/common/local-first/Public/interfaces/SecureStorageDep) & [`RandomBytesDep`](https://evolu.dev/docs/api-reference/common/Crypto/interfaces/RandomBytesDep) |
## Returns
[`LocalAuth`](https://evolu.dev/docs/api-reference/common/local-first/Public/interfaces/LocalAuth)
AuthList - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first/Public](https://evolu.dev/docs/api-reference/common/local-first/Public) / AuthList
# Interface: AuthList
Defined in: [packages/common/src/local-first/LocalAuth.ts:337](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/LocalAuth.ts#L337)
## Properties
| Property | Modifier | Type | Description | Defined in |
| -------------------------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| <a id="ownerid"></a> `ownerId` | `readonly` | `string` & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"Id"`\> & [`Brand`](https://evolu.dev/docs/api-reference/common/Brand/interfaces/Brand)\<`"OwnerId"`\> | The app owner ID. | [packages/common/src/local-first/LocalAuth.ts:339](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/LocalAuth.ts#L339) |
| <a id="username"></a> `username` | `readonly` | `string` | The name provided by the user during registration. | [packages/common/src/local-first/LocalAuth.ts:341](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/LocalAuth.ts#L341) |
AuthResult - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first/Public](https://evolu.dev/docs/api-reference/common/local-first/Public) / AuthResult
# Interface: AuthResult
Defined in: [packages/common/src/local-first/LocalAuth.ts:330](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/LocalAuth.ts#L330)
## Properties
| Property | Modifier | Type | Description | Defined in |
| -------------------------------- | ---------- | ---------------------------------------------------------------------------------------------- | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| <a id="owner"></a> `owner` | `readonly` | \| [`AppOwner`](https://evolu.dev/docs/api-reference/common/local-first/interfaces/AppOwner) \| `undefined` | The app owner created during registration. | [packages/common/src/local-first/LocalAuth.ts:332](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/LocalAuth.ts#L332) |
| <a id="username"></a> `username` | `readonly` | `string` | The name provided by the user during registration. | [packages/common/src/local-first/LocalAuth.ts:334](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/LocalAuth.ts#L334) |
AuthenticationPrompt - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first/Public](https://evolu.dev/docs/api-reference/common/local-first/Public) / AuthenticationPrompt
# Interface: AuthenticationPrompt
Defined in: [packages/common/src/local-first/LocalAuth.ts:406](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/LocalAuth.ts#L406)
Configuration for the biometric/device credential prompt shown when a
protected item is accessed.
## Properties
| Property | Modifier | Type | Defined in |
| --------------------------------------- | ---------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| <a id="cancel"></a> `cancel?` | `readonly` | `string` | [packages/common/src/local-first/LocalAuth.ts:410](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/LocalAuth.ts#L410) |
| <a id="description"></a> `description?` | `readonly` | `string` | [packages/common/src/local-first/LocalAuth.ts:409](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/LocalAuth.ts#L409) |
| <a id="subtitle"></a> `subtitle?` | `readonly` | `string` | [packages/common/src/local-first/LocalAuth.ts:408](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/LocalAuth.ts#L408) |
| <a id="title"></a> `title` | `readonly` | `string` | [packages/common/src/local-first/LocalAuth.ts:407](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/LocalAuth.ts#L407) |
LocalAuth - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first/Public](https://evolu.dev/docs/api-reference/common/local-first/Public) / LocalAuth
# Interface: LocalAuth
Defined in: [packages/common/src/local-first/LocalAuth.ts:19](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/LocalAuth.ts#L19)
**`Experimental`**
Local authentication and authorization system for Evolu. This is API is
subject to change and not recommended for production use.
## Properties
| Property | Type | Description | Defined in |
| -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="clearall"></a> `clearAll` | (`options?`) => `Promise`\<`void`\> | **`Experimental`** Clears all owners and metadata from the local auth. | [packages/common/src/local-first/LocalAuth.ts:42](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/LocalAuth.ts#L42) |
| <a id="getowner"></a> `getOwner` | (`options?`) => `Promise`\< \| [`AuthResult`](https://evolu.dev/docs/api-reference/common/local-first/Public/interfaces/AuthResult) \| `null`\> | **`Experimental`** Gets the current owner (last logged in or last registered owner) | [packages/common/src/local-first/LocalAuth.ts:36](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/LocalAuth.ts#L36) |
| <a id="getprofiles"></a> `getProfiles` | (`options?`) => `Promise`\<[`AuthList`](https://evolu.dev/docs/api-reference/common/local-first/Public/interfaces/AuthList)[]\> | **`Experimental`** Lists all registered owner ids with associated usernames. | [packages/common/src/local-first/LocalAuth.ts:39](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/LocalAuth.ts#L39) |
| <a id="login"></a> `login` | (`ownerId`, `options?`) => `Promise`\< \| [`AuthResult`](https://evolu.dev/docs/api-reference/common/local-first/Public/interfaces/AuthResult) \| `null`\> | **`Experimental`** Logs in with the given owner ID, or loads the target owner if not provided. | [packages/common/src/local-first/LocalAuth.ts:21](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/LocalAuth.ts#L21) |
| <a id="register"></a> `register` | (`username`, `options?`) => `Promise`\< \| [`AuthResult`](https://evolu.dev/docs/api-reference/common/local-first/Public/interfaces/AuthResult) \| `null`\> | **`Experimental`** Registers a new owner with the given username. | [packages/common/src/local-first/LocalAuth.ts:27](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/LocalAuth.ts#L27) |
| <a id="unregister"></a> `unregister` | (`ownerId`, `options?`) => `Promise`\<`void`\> | **`Experimental`** Unregisters an owner with the given owner ID. | [packages/common/src/local-first/LocalAuth.ts:33](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/LocalAuth.ts#L33) |
LocalAuthDep - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first/Public](https://evolu.dev/docs/api-reference/common/local-first/Public) / LocalAuthDep
# Interface: LocalAuthDep
Defined in: [packages/common/src/local-first/LocalAuth.ts:45](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/LocalAuth.ts#L45)
## Properties
| Property | Modifier | Type | Defined in |
| ---------------------------------- | ---------- | ------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="localauth"></a> `localAuth` | `readonly` | [`LocalAuth`](https://evolu.dev/docs/api-reference/common/local-first/Public/interfaces/LocalAuth) | [packages/common/src/local-first/LocalAuth.ts:46](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/LocalAuth.ts#L46) |
LocalAuthOptions - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first/Public](https://evolu.dev/docs/api-reference/common/local-first/Public) / LocalAuthOptions
# Interface: LocalAuthOptions
Defined in: [packages/common/src/local-first/LocalAuth.ts:346](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/LocalAuth.ts#L346)
## Extended by
- [`LocalAuthOptionsValues`](https://evolu.dev/docs/api-reference/common/local-first/Public/interfaces/LocalAuthOptionsValues)
- [`SensitiveInfoGetRequest`](https://evolu.dev/docs/api-reference/common/local-first/Public/interfaces/SensitiveInfoGetRequest)
## Properties
| Property | Modifier | Type | Description | Defined in |
| ------------------------------------------------------------------------------- | ---------- | ----------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| <a id="accesscontrol"></a> `accessControl?` | `readonly` | [`AccessControl`](https://evolu.dev/docs/api-reference/common/local-first/Public/type-aliases/AccessControl) | Native: Desired access-control policy. The native implementation will automatically fall back to the strongest supported policy for the current device (Secure Enclave ➝ Biometry ➝ Device Credential ➝ None). | [packages/common/src/local-first/LocalAuth.ts:364](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/LocalAuth.ts#L364) |
| <a id="androidbiometricsstrongonly"></a> `androidBiometricsStrongOnly?` | `readonly` | `boolean` | Android: Fine tune whether the hardware-authenticated key should require biometrics only. | [packages/common/src/local-first/LocalAuth.ts:370](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/LocalAuth.ts#L370) |
| <a id="authenticationprompt"></a> `authenticationPrompt?` | `readonly` | [`AuthenticationPrompt`](https://evolu.dev/docs/api-reference/common/local-first/Public/interfaces/AuthenticationPrompt) | Native: Optional prompt configuration that will be shown when protected keys require user presence. | [packages/common/src/local-first/LocalAuth.ts:376](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/LocalAuth.ts#L376) |
| <a id="iossynchronizable"></a> `iosSynchronizable?` | `readonly` | `boolean` | IOS: Enable keychain item synchronization via iCloud. | [packages/common/src/local-first/LocalAuth.ts:354](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/LocalAuth.ts#L354) |
| <a id="keychaingroup"></a> `keychainGroup?` | `readonly` | `string` | IOS: Custom keychain access group. | [packages/common/src/local-first/LocalAuth.ts:357](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/LocalAuth.ts#L357) |
| <a id="relyingpartyid"></a> `relyingPartyID?` | `readonly` | `string` | Web: The relying party ID for WebAuthn. Defaults to the current hostname. | [packages/common/src/local-first/LocalAuth.ts:379](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/LocalAuth.ts#L379) |
| <a id="relyingpartyname"></a> `relyingPartyName?` | `readonly` | `string` | Web: The relying party name for WebAuthn. Defaults to 'Evolu'. | [packages/common/src/local-first/LocalAuth.ts:382](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/LocalAuth.ts#L382) |
| <a id="service"></a> `service?` | `readonly` | `string` | Native: Namespaces the stored entry. Defaults to the bundle identifier (when available) or `default`. | [packages/common/src/local-first/LocalAuth.ts:351](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/LocalAuth.ts#L351) |
| <a id="webauthnauthenticatorattachment"></a> `webAuthnAuthenticatorAttachment?` | `readonly` | `AuthenticatorAttachment` | Web: The authenticator attachment for WebAuthn. Defaults to 'platform'. | [packages/common/src/local-first/LocalAuth.ts:394](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/LocalAuth.ts#L394) |
| <a id="webauthnusername"></a> `webAuthnUsername?` | `readonly` | `string` | Web: The username for WebAuthn. Defaults to 'Evolu User'. | [packages/common/src/local-first/LocalAuth.ts:385](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/LocalAuth.ts#L385) |
| <a id="webauthnuserverification"></a> `webAuthnUserVerification?` | `readonly` | `UserVerificationRequirement` | Web: The user verification requirement for WebAuthn. Defaults to 'required'. | [packages/common/src/local-first/LocalAuth.ts:391](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/LocalAuth.ts#L391) |
LocalAuthOptionsValues - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first/Public](https://evolu.dev/docs/api-reference/common/local-first/Public) / LocalAuthOptionsValues
# Interface: LocalAuthOptionsValues
Defined in: [packages/common/src/local-first/LocalAuth.ts:397](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/LocalAuth.ts#L397)
## Extends
- [`LocalAuthOptions`](https://evolu.dev/docs/api-reference/common/local-first/Public/interfaces/LocalAuthOptions)
## Properties
| Property | Modifier | Type | Description | Inherited from | Defined in |
| ------------------------------------------------------------------------------- | ---------- | ----------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| <a id="accesscontrol"></a> `accessControl?` | `readonly` | [`AccessControl`](https://evolu.dev/docs/api-reference/common/local-first/Public/type-aliases/AccessControl) | Native: Desired access-control policy. The native implementation will automatically fall back to the strongest supported policy for the current device (Secure Enclave ➝ Biometry ➝ Device Credential ➝ None). | [`LocalAuthOptions`](https://evolu.dev/docs/api-reference/common/local-first/Public/interfaces/LocalAuthOptions).[`accessControl`](https://evolu.dev/docs/api-reference/common/local-first/Public/interfaces/LocalAuthOptions.mdx#accesscontrol) | [packages/common/src/local-first/LocalAuth.ts:364](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/LocalAuth.ts#L364) |
| <a id="androidbiometricsstrongonly"></a> `androidBiometricsStrongOnly?` | `readonly` | `boolean` | Android: Fine tune whether the hardware-authenticated key should require biometrics only. | [`LocalAuthOptions`](https://evolu.dev/docs/api-reference/common/local-first/Public/interfaces/LocalAuthOptions).[`androidBiometricsStrongOnly`](https://evolu.dev/docs/api-reference/common/local-first/Public/interfaces/LocalAuthOptions.mdx#androidbiometricsstrongonly) | [packages/common/src/local-first/LocalAuth.ts:370](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/LocalAuth.ts#L370) |
| <a id="authenticationprompt"></a> `authenticationPrompt?` | `readonly` | [`AuthenticationPrompt`](https://evolu.dev/docs/api-reference/common/local-first/Public/interfaces/AuthenticationPrompt) | Native: Optional prompt configuration that will be shown when protected keys require user presence. | [`LocalAuthOptions`](https://evolu.dev/docs/api-reference/common/local-first/Public/interfaces/LocalAuthOptions).[`authenticationPrompt`](https://evolu.dev/docs/api-reference/common/local-first/Public/interfaces/LocalAuthOptions.mdx#authenticationprompt) | [packages/common/src/local-first/LocalAuth.ts:376](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/LocalAuth.ts#L376) |
| <a id="includevalues"></a> `includeValues?` | `readonly` | `boolean` | When true, the stored value is returned for each item. Defaults to false. | - | [packages/common/src/local-first/LocalAuth.ts:399](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/LocalAuth.ts#L399) |
| <a id="iossynchronizable"></a> `iosSynchronizable?` | `readonly` | `boolean` | IOS: Enable keychain item synchronization via iCloud. | [`LocalAuthOptions`](https://evolu.dev/docs/api-reference/common/local-first/Public/interfaces/LocalAuthOptions).[`iosSynchronizable`](https://evolu.dev/docs/api-reference/common/local-first/Public/interfaces/LocalAuthOptions.mdx#iossynchronizable) | [packages/common/src/local-first/LocalAuth.ts:354](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/LocalAuth.ts#L354) |
| <a id="keychaingroup"></a> `keychainGroup?` | `readonly` | `string` | IOS: Custom keychain access group. | [`LocalAuthOptions`](https://evolu.dev/docs/api-reference/common/local-first/Public/interfaces/LocalAuthOptions).[`keychainGroup`](https://evolu.dev/docs/api-reference/common/local-first/Public/interfaces/LocalAuthOptions.mdx#keychaingroup) | [packages/common/src/local-first/LocalAuth.ts:357](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/LocalAuth.ts#L357) |
| <a id="relyingpartyid"></a> `relyingPartyID?` | `readonly` | `string` | Web: The relying party ID for WebAuthn. Defaults to the current hostname. | [`LocalAuthOptions`](https://evolu.dev/docs/api-reference/common/local-first/Public/interfaces/LocalAuthOptions).[`relyingPartyID`](https://evolu.dev/docs/api-reference/common/local-first/Public/interfaces/LocalAuthOptions.mdx#relyingpartyid) | [packages/common/src/local-first/LocalAuth.ts:379](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/LocalAuth.ts#L379) |
| <a id="relyingpartyname"></a> `relyingPartyName?` | `readonly` | `string` | Web: The relying party name for WebAuthn. Defaults to 'Evolu'. | [`LocalAuthOptions`](https://evolu.dev/docs/api-reference/common/local-first/Public/interfaces/LocalAuthOptions).[`relyingPartyName`](https://evolu.dev/docs/api-reference/common/local-first/Public/interfaces/LocalAuthOptions.mdx#relyingpartyname) | [packages/common/src/local-first/LocalAuth.ts:382](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/LocalAuth.ts#L382) |
| <a id="service"></a> `service?` | `readonly` | `string` | Native: Namespaces the stored entry. Defaults to the bundle identifier (when available) or `default`. | [`LocalAuthOptions`](https://evolu.dev/docs/api-reference/common/local-first/Public/interfaces/LocalAuthOptions).[`service`](https://evolu.dev/docs/api-reference/common/local-first/Public/interfaces/LocalAuthOptions.mdx#service) | [packages/common/src/local-first/LocalAuth.ts:351](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/LocalAuth.ts#L351) |
| <a id="webauthnauthenticatorattachment"></a> `webAuthnAuthenticatorAttachment?` | `readonly` | `AuthenticatorAttachment` | Web: The authenticator attachment for WebAuthn. Defaults to 'platform'. | [`LocalAuthOptions`](https://evolu.dev/docs/api-reference/common/local-first/Public/interfaces/LocalAuthOptions).[`webAuthnAuthenticatorAttachment`](https://evolu.dev/docs/api-reference/common/local-first/Public/interfaces/LocalAuthOptions.mdx#webauthnauthenticatorattachment) | [packages/common/src/local-first/LocalAuth.ts:394](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/LocalAuth.ts#L394) |
| <a id="webauthnusername"></a> `webAuthnUsername?` | `readonly` | `string` | Web: The username for WebAuthn. Defaults to 'Evolu User'. | [`LocalAuthOptions`](https://evolu.dev/docs/api-reference/common/local-first/Public/interfaces/LocalAuthOptions).[`webAuthnUsername`](https://evolu.dev/docs/api-reference/common/local-first/Public/interfaces/LocalAuthOptions.mdx#webauthnusername) | [packages/common/src/local-first/LocalAuth.ts:385](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/LocalAuth.ts#L385) |
| <a id="webauthnuserverification"></a> `webAuthnUserVerification?` | `readonly` | `UserVerificationRequirement` | Web: The user verification requirement for WebAuthn. Defaults to 'required'. | [`LocalAuthOptions`](https://evolu.dev/docs/api-reference/common/local-first/Public/interfaces/LocalAuthOptions).[`webAuthnUserVerification`](https://evolu.dev/docs/api-reference/common/local-first/Public/interfaces/LocalAuthOptions.mdx#webauthnuserverification) | [packages/common/src/local-first/LocalAuth.ts:391](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/LocalAuth.ts#L391) |
MutationResult - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first/Public](https://evolu.dev/docs/api-reference/common/local-first/Public) / MutationResult
# Interface: MutationResult
Defined in: [packages/common/src/local-first/LocalAuth.ts:433](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/LocalAuth.ts#L433)
## Properties
| Property | Modifier | Type | Defined in |
| -------------------------------- | ---------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| <a id="metadata"></a> `metadata` | `readonly` | [`StorageMetadata`](https://evolu.dev/docs/api-reference/common/local-first/Public/interfaces/StorageMetadata) | [packages/common/src/local-first/LocalAuth.ts:434](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/LocalAuth.ts#L434) |
SecureStorage - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first/Public](https://evolu.dev/docs/api-reference/common/local-first/Public) / SecureStorage
# Interface: SecureStorage
Defined in: [packages/common/src/local-first/LocalAuth.ts:54](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/LocalAuth.ts#L54)
**`Experimental`**
Secure storage interface that must be implemented by each platform.
## Properties
| Property | Type | Description | Defined in |
| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="clearservice"></a> `clearService` | (`options?`) => `Promise`\<`void`\> | **`Experimental`** | [packages/common/src/local-first/LocalAuth.ts:68](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/LocalAuth.ts#L68) |
| <a id="deleteitem"></a> `deleteItem` | (`key`, `options?`) => `Promise`\<`boolean`\> | **`Experimental`** | [packages/common/src/local-first/LocalAuth.ts:64](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/LocalAuth.ts#L64) |
| <a id="getallitems"></a> `getAllItems` | (`options?`) => `Promise`\<[`SensitiveInfoItem`](https://evolu.dev/docs/api-reference/common/local-first/Public/interfaces/SensitiveInfoItem)[]\> | **`Experimental`** | [packages/common/src/local-first/LocalAuth.ts:65](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/LocalAuth.ts#L65) |
| <a id="getitem"></a> `getItem` | (`key`, `options?`) => `Promise`\< \| [`SensitiveInfoItem`](https://evolu.dev/docs/api-reference/common/local-first/Public/interfaces/SensitiveInfoItem) \| `null`\> | **`Experimental`** | [packages/common/src/local-first/LocalAuth.ts:60](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/LocalAuth.ts#L60) |
| <a id="setitem"></a> `setItem` | (`key`, `value`, `options?`) => `Promise`\<[`MutationResult`](https://evolu.dev/docs/api-reference/common/local-first/Public/interfaces/MutationResult)\> | **`Experimental`** | [packages/common/src/local-first/LocalAuth.ts:55](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/LocalAuth.ts#L55) |
SecureStorageDep - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first/Public](https://evolu.dev/docs/api-reference/common/local-first/Public) / SecureStorageDep
# Interface: SecureStorageDep
Defined in: [packages/common/src/local-first/LocalAuth.ts:71](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/LocalAuth.ts#L71)
## Properties
| Property | Modifier | Type | Defined in |
| ------------------------------------------ | ---------- | --------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="securestorage"></a> `secureStorage` | `readonly` | [`SecureStorage`](https://evolu.dev/docs/api-reference/common/local-first/Public/interfaces/SecureStorage) | [packages/common/src/local-first/LocalAuth.ts:72](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/LocalAuth.ts#L72) |
SensitiveInfoGetRequest - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first/Public](https://evolu.dev/docs/api-reference/common/local-first/Public) / SensitiveInfoGetRequest
# Interface: SensitiveInfoGetRequest
Defined in: [packages/common/src/local-first/LocalAuth.ts:413](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/LocalAuth.ts#L413)
## Extends
- [`LocalAuthOptions`](https://evolu.dev/docs/api-reference/common/local-first/Public/interfaces/LocalAuthOptions)
## Properties
| Property | Modifier | Type | Description | Inherited from | Defined in |
| ------------------------------------------------------------------------------- | ---------- | ----------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| <a id="accesscontrol"></a> `accessControl?` | `readonly` | [`AccessControl`](https://evolu.dev/docs/api-reference/common/local-first/Public/type-aliases/AccessControl) | Native: Desired access-control policy. The native implementation will automatically fall back to the strongest supported policy for the current device (Secure Enclave ➝ Biometry ➝ Device Credential ➝ None). | [`LocalAuthOptions`](https://evolu.dev/docs/api-reference/common/local-first/Public/interfaces/LocalAuthOptions).[`accessControl`](https://evolu.dev/docs/api-reference/common/local-first/Public/interfaces/LocalAuthOptions.mdx#accesscontrol) | [packages/common/src/local-first/LocalAuth.ts:364](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/LocalAuth.ts#L364) |
| <a id="androidbiometricsstrongonly"></a> `androidBiometricsStrongOnly?` | `readonly` | `boolean` | Android: Fine tune whether the hardware-authenticated key should require biometrics only. | [`LocalAuthOptions`](https://evolu.dev/docs/api-reference/common/local-first/Public/interfaces/LocalAuthOptions).[`androidBiometricsStrongOnly`](https://evolu.dev/docs/api-reference/common/local-first/Public/interfaces/LocalAuthOptions.mdx#androidbiometricsstrongonly) | [packages/common/src/local-first/LocalAuth.ts:370](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/LocalAuth.ts#L370) |
| <a id="authenticationprompt"></a> `authenticationPrompt?` | `readonly` | [`AuthenticationPrompt`](https://evolu.dev/docs/api-reference/common/local-first/Public/interfaces/AuthenticationPrompt) | Native: Optional prompt configuration that will be shown when protected keys require user presence. | [`LocalAuthOptions`](https://evolu.dev/docs/api-reference/common/local-first/Public/interfaces/LocalAuthOptions).[`authenticationPrompt`](https://evolu.dev/docs/api-reference/common/local-first/Public/interfaces/LocalAuthOptions.mdx#authenticationprompt) | [packages/common/src/local-first/LocalAuth.ts:376](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/LocalAuth.ts#L376) |
| <a id="includevalue"></a> `includeValue?` | `readonly` | `boolean` | Include the encrypted value when available. Defaults to true. | - | [packages/common/src/local-first/LocalAuth.ts:416](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/LocalAuth.ts#L416) |
| <a id="iossynchronizable"></a> `iosSynchronizable?` | `readonly` | `boolean` | IOS: Enable keychain item synchronization via iCloud. | [`LocalAuthOptions`](https://evolu.dev/docs/api-reference/common/local-first/Public/interfaces/LocalAuthOptions).[`iosSynchronizable`](https://evolu.dev/docs/api-reference/common/local-first/Public/interfaces/LocalAuthOptions.mdx#iossynchronizable) | [packages/common/src/local-first/LocalAuth.ts:354](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/LocalAuth.ts#L354) |
| <a id="key"></a> `key` | `readonly` | `string` | - | - | [packages/common/src/local-first/LocalAuth.ts:414](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/LocalAuth.ts#L414) |
| <a id="keychaingroup"></a> `keychainGroup?` | `readonly` | `string` | IOS: Custom keychain access group. | [`LocalAuthOptions`](https://evolu.dev/docs/api-reference/common/local-first/Public/interfaces/LocalAuthOptions).[`keychainGroup`](https://evolu.dev/docs/api-reference/common/local-first/Public/interfaces/LocalAuthOptions.mdx#keychaingroup) | [packages/common/src/local-first/LocalAuth.ts:357](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/LocalAuth.ts#L357) |
| <a id="relyingpartyid"></a> `relyingPartyID?` | `readonly` | `string` | Web: The relying party ID for WebAuthn. Defaults to the current hostname. | [`LocalAuthOptions`](https://evolu.dev/docs/api-reference/common/local-first/Public/interfaces/LocalAuthOptions).[`relyingPartyID`](https://evolu.dev/docs/api-reference/common/local-first/Public/interfaces/LocalAuthOptions.mdx#relyingpartyid) | [packages/common/src/local-first/LocalAuth.ts:379](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/LocalAuth.ts#L379) |
| <a id="relyingpartyname"></a> `relyingPartyName?` | `readonly` | `string` | Web: The relying party name for WebAuthn. Defaults to 'Evolu'. | [`LocalAuthOptions`](https://evolu.dev/docs/api-reference/common/local-first/Public/interfaces/LocalAuthOptions).[`relyingPartyName`](https://evolu.dev/docs/api-reference/common/local-first/Public/interfaces/LocalAuthOptions.mdx#relyingpartyname) | [packages/common/src/local-first/LocalAuth.ts:382](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/LocalAuth.ts#L382) |
| <a id="service"></a> `service?` | `readonly` | `string` | Native: Namespaces the stored entry. Defaults to the bundle identifier (when available) or `default`. | [`LocalAuthOptions`](https://evolu.dev/docs/api-reference/common/local-first/Public/interfaces/LocalAuthOptions).[`service`](https://evolu.dev/docs/api-reference/common/local-first/Public/interfaces/LocalAuthOptions.mdx#service) | [packages/common/src/local-first/LocalAuth.ts:351](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/LocalAuth.ts#L351) |
| <a id="webauthnauthenticatorattachment"></a> `webAuthnAuthenticatorAttachment?` | `readonly` | `AuthenticatorAttachment` | Web: The authenticator attachment for WebAuthn. Defaults to 'platform'. | [`LocalAuthOptions`](https://evolu.dev/docs/api-reference/common/local-first/Public/interfaces/LocalAuthOptions).[`webAuthnAuthenticatorAttachment`](https://evolu.dev/docs/api-reference/common/local-first/Public/interfaces/LocalAuthOptions.mdx#webauthnauthenticatorattachment) | [packages/common/src/local-first/LocalAuth.ts:394](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/LocalAuth.ts#L394) |
| <a id="webauthnusername"></a> `webAuthnUsername?` | `readonly` | `string` | Web: The username for WebAuthn. Defaults to 'Evolu User'. | [`LocalAuthOptions`](https://evolu.dev/docs/api-reference/common/local-first/Public/interfaces/LocalAuthOptions).[`webAuthnUsername`](https://evolu.dev/docs/api-reference/common/local-first/Public/interfaces/LocalAuthOptions.mdx#webauthnusername) | [packages/common/src/local-first/LocalAuth.ts:385](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/LocalAuth.ts#L385) |
| <a id="webauthnuserverification"></a> `webAuthnUserVerification?` | `readonly` | `UserVerificationRequirement` | Web: The user verification requirement for WebAuthn. Defaults to 'required'. | [`LocalAuthOptions`](https://evolu.dev/docs/api-reference/common/local-first/Public/interfaces/LocalAuthOptions).[`webAuthnUserVerification`](https://evolu.dev/docs/api-reference/common/local-first/Public/interfaces/LocalAuthOptions.mdx#webauthnuserverification) | [packages/common/src/local-first/LocalAuth.ts:391](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/LocalAuth.ts#L391) |
SensitiveInfoItem - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first/Public](https://evolu.dev/docs/api-reference/common/local-first/Public) / SensitiveInfoItem
# Interface: SensitiveInfoItem
Defined in: [packages/common/src/local-first/LocalAuth.ts:426](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/LocalAuth.ts#L426)
## Properties
| Property | Modifier | Type | Defined in |
| -------------------------------- | ---------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| <a id="key"></a> `key` | `readonly` | `string` | [packages/common/src/local-first/LocalAuth.ts:427](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/LocalAuth.ts#L427) |
| <a id="metadata"></a> `metadata` | `readonly` | [`StorageMetadata`](https://evolu.dev/docs/api-reference/common/local-first/Public/interfaces/StorageMetadata) | [packages/common/src/local-first/LocalAuth.ts:430](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/LocalAuth.ts#L430) |
| <a id="service"></a> `service` | `readonly` | `string` | [packages/common/src/local-first/LocalAuth.ts:428](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/LocalAuth.ts#L428) |
| <a id="value"></a> `value?` | `readonly` | `string` | [packages/common/src/local-first/LocalAuth.ts:429](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/LocalAuth.ts#L429) |
StorageMetadata - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first/Public](https://evolu.dev/docs/api-reference/common/local-first/Public) / StorageMetadata
# Interface: StorageMetadata
Defined in: [packages/common/src/local-first/LocalAuth.ts:419](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/LocalAuth.ts#L419)
## Properties
| Property | Modifier | Type | Defined in |
| ------------------------------------------ | ---------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| <a id="accesscontrol"></a> `accessControl` | `readonly` | [`AccessControl`](https://evolu.dev/docs/api-reference/common/local-first/Public/type-aliases/AccessControl) | [packages/common/src/local-first/LocalAuth.ts:422](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/LocalAuth.ts#L422) |
| <a id="backend"></a> `backend` | `readonly` | [`StorageBackend`](https://evolu.dev/docs/api-reference/common/local-first/Public/type-aliases/StorageBackend) | [packages/common/src/local-first/LocalAuth.ts:421](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/LocalAuth.ts#L421) |
| <a id="securitylevel"></a> `securityLevel` | `readonly` | [`SecurityLevel`](https://evolu.dev/docs/api-reference/common/local-first/Public/type-aliases/SecurityLevel) | [packages/common/src/local-first/LocalAuth.ts:420](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/LocalAuth.ts#L420) |
| <a id="timestamp"></a> `timestamp` | `readonly` | `number` | [packages/common/src/local-first/LocalAuth.ts:423](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/LocalAuth.ts#L423) |
API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first/Public](https://evolu.dev/docs/api-reference/common/local-first/Public) / kysely
# kysely
## Type Aliases
| Type Alias | Description |
| --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| [NotNull](https://evolu.dev/docs/api-reference/common/local-first/Public/namespaces/kysely/type-aliases/NotNull) | A type constant for marking a column as not null. Can be used with `$narrowPartial`. |
## Variables
| Variable | Description |
| ---------------------------------------------------------------------------------------- | ----------- |
| [sql](https://evolu.dev/docs/api-reference/common/local-first/Public/namespaces/kysely/variables/sql) | - |
## Functions
| Function | Description |
| -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
| [getJsonObjectArgs](https://evolu.dev/docs/api-reference/common/local-first/Public/namespaces/kysely/functions/getJsonObjectArgs) | - |
| [jsonArrayFrom](https://evolu.dev/docs/api-reference/common/local-first/Public/namespaces/kysely/functions/jsonArrayFrom) | A SQLite helper for aggregating a subquery into a JSON array. |
| [jsonBuildObject](https://evolu.dev/docs/api-reference/common/local-first/Public/namespaces/kysely/functions/jsonBuildObject) | The SQLite `json_object` function. |
| [jsonObjectFrom](https://evolu.dev/docs/api-reference/common/local-first/Public/namespaces/kysely/functions/jsonObjectFrom) | A SQLite helper for turning a subquery into a JSON object. |
AccessControl - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first/Public](https://evolu.dev/docs/api-reference/common/local-first/Public) / AccessControl
# Type Alias: AccessControl
```ts
type AccessControl =
| "secureEnclaveBiometry"
| "biometryCurrentSet"
| "biometryAny"
| "devicePasscode"
| "none";
```
Defined in: [packages/common/src/local-first/LocalAuth.ts:458](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/LocalAuth.ts#L458)
Enumerates the access-control policy enforced by the underlying secure
storage.
SecurityLevel - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first/Public](https://evolu.dev/docs/api-reference/common/local-first/Public) / SecurityLevel
# Type Alias: SecurityLevel
```ts
type SecurityLevel =
| "secureEnclave"
| "strongBox"
| "biometry"
| "deviceCredential"
| "software";
```
Defined in: [packages/common/src/local-first/LocalAuth.ts:441](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/LocalAuth.ts#L441)
Enumerates the highest security tier that was effectively applied while
storing a value.
StorageBackend - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first/Public](https://evolu.dev/docs/api-reference/common/local-first/Public) / StorageBackend
# Type Alias: StorageBackend
```ts
type StorageBackend =
| "keychain"
| "androidKeystore"
| "encryptedSharedPreferences";
```
Defined in: [packages/common/src/local-first/LocalAuth.ts:449](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/LocalAuth.ts#L449)
Enumerates the native storage backend used to persist sensitive data.
localAuthDefaultOptions - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first/Public](https://evolu.dev/docs/api-reference/common/local-first/Public) / localAuthDefaultOptions
# Variable: localAuthDefaultOptions
```ts
const localAuthDefaultOptions: LocalAuthOptions;
```
Defined in: [packages/common/src/local-first/LocalAuth.ts:316](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/LocalAuth.ts#L316)
localAuth_Namespace - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first/Public](https://evolu.dev/docs/api-reference/common/local-first/Public) / localAuth_Namespace
# Variable: localAuth_Namespace
```ts
const localAuth_Namespace: "evolu" = "evolu";
```
Defined in: [packages/common/src/local-first/LocalAuth.ts:314](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/LocalAuth.ts#L314)
evoluReactNativeDeps - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/react-native](https://evolu.dev/docs/api-reference/react-native) / [exports/bare-op-sqlite](https://evolu.dev/docs/api-reference/react-native/exports/bare-op-sqlite) / evoluReactNativeDeps
# Variable: evoluReactNativeDeps
```ts
const evoluReactNativeDeps: EvoluDeps;
```
Defined in: [react-native/src/exports/bare-op-sqlite.ts:23](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/react-native/src/exports/bare-op-sqlite.ts#L23)
localAuth - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/react-native](https://evolu.dev/docs/api-reference/react-native) / [exports/bare-op-sqlite](https://evolu.dev/docs/api-reference/react-native/exports/bare-op-sqlite) / localAuth
# Variable: localAuth
```ts
const localAuth: LocalAuth;
```
Defined in: [react-native/src/exports/bare-op-sqlite.ts:28](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/react-native/src/exports/bare-op-sqlite.ts#L28)
evoluReactNativeDeps - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/react-native](https://evolu.dev/docs/api-reference/react-native) / [exports/expo-op-sqlite](https://evolu.dev/docs/api-reference/react-native/exports/expo-op-sqlite) / evoluReactNativeDeps
# Variable: evoluReactNativeDeps
```ts
evoluReactNativeDeps: EvoluDeps;
```
Defined in: [react-native/src/exports/expo-op-sqlite.ts:12](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/react-native/src/exports/expo-op-sqlite.ts#L12)
localAuth - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/react-native](https://evolu.dev/docs/api-reference/react-native) / [exports/expo-op-sqlite](https://evolu.dev/docs/api-reference/react-native/exports/expo-op-sqlite) / localAuth
# Variable: localAuth
```ts
localAuth: LocalAuth;
```
Defined in: [react-native/src/exports/expo-op-sqlite.ts:12](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/react-native/src/exports/expo-op-sqlite.ts#L12)
evoluReactNativeDeps - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/react-native](https://evolu.dev/docs/api-reference/react-native) / [exports/expo-sqlite](https://evolu.dev/docs/api-reference/react-native/exports/expo-sqlite) / evoluReactNativeDeps
# Variable: evoluReactNativeDeps
```ts
evoluReactNativeDeps: EvoluDeps;
```
Defined in: [react-native/src/exports/expo-sqlite.ts:11](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/react-native/src/exports/expo-sqlite.ts#L11)
localAuth - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/react-native](https://evolu.dev/docs/api-reference/react-native) / [exports/expo-sqlite](https://evolu.dev/docs/api-reference/react-native/exports/expo-sqlite) / localAuth
# Variable: localAuth
```ts
localAuth: LocalAuth;
```
Defined in: [react-native/src/exports/expo-sqlite.ts:11](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/react-native/src/exports/expo-sqlite.ts#L11)
FailureResult - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / [StandardSchemaV1](https://evolu.dev/docs/api-reference/common/Type/namespaces/StandardSchemaV1) / FailureResult
# Interface: FailureResult
Defined in: [packages/common/src/Type.ts:4481](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L4481)
The result interface if validation fails.
## Properties
| Property | Modifier | Type | Description | Defined in |
| ---------------------------- | ---------- | ------------------------------------------------------------------------------------------------------ | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="issues"></a> `issues` | `readonly` | readonly [`Issue`](https://evolu.dev/docs/api-reference/common/Type/namespaces/StandardSchemaV1/interfaces/Issue)[] | The issues of failed validation. | [packages/common/src/Type.ts:4483](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L4483) |
Issue - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / [StandardSchemaV1](https://evolu.dev/docs/api-reference/common/Type/namespaces/StandardSchemaV1) / Issue
# Interface: Issue
Defined in: [packages/common/src/Type.ts:4487](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L4487)
The issue interface of the failure output.
## Properties
| Property | Modifier | Type | Description | Defined in |
| ------------------------------ | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="message"></a> `message` | `readonly` | `string` | The error message of the issue. | [packages/common/src/Type.ts:4489](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L4489) |
| <a id="path"></a> `path?` | `readonly` | readonly ( \| `PropertyKey` \| [`PathSegment`](https://evolu.dev/docs/api-reference/common/Type/namespaces/StandardSchemaV1/interfaces/PathSegment))[] | The path of the issue, if any. | [packages/common/src/Type.ts:4491](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L4491) |
PathSegment - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / [StandardSchemaV1](https://evolu.dev/docs/api-reference/common/Type/namespaces/StandardSchemaV1) / PathSegment
# Interface: PathSegment
Defined in: [packages/common/src/Type.ts:4495](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L4495)
The path segment interface of the issue.
## Properties
| Property | Modifier | Type | Description | Defined in |
| ---------------------- | ---------- | ------------- | ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="key"></a> `key` | `readonly` | `PropertyKey` | The key representing a path segment. | [packages/common/src/Type.ts:4497](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L4497) |
Props - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / [StandardSchemaV1](https://evolu.dev/docs/api-reference/common/Type/namespaces/StandardSchemaV1) / Props
# Interface: Props\<Input, Output\>
Defined in: [packages/common/src/Type.ts:4456](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L4456)
The Standard Schema properties interface.
## Type Parameters
| Type Parameter | Default type |
| -------------- | ------------ |
| `Input` | `unknown` |
| `Output` | `Input` |
## Properties
| Property | Modifier | Type | Description | Defined in |
| -------------------------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="types"></a> `types?` | `readonly` | [`Types`](https://evolu.dev/docs/api-reference/common/Type/namespaces/StandardSchemaV1/interfaces/Types)\<`Input`, `Output`\> | Inferred types associated with the schema. | [packages/common/src/Type.ts:4466](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L4466) |
| <a id="validate"></a> `validate` | `readonly` | (`value`) => \| [`Result`](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result)\<`Output`\> \| `Promise`\<[`Result`](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result)\<`Output`\>\> | Validates unknown input values. | [packages/common/src/Type.ts:4462](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L4462) |
| <a id="vendor"></a> `vendor` | `readonly` | `string` | The vendor name of the schema library. | [packages/common/src/Type.ts:4460](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L4460) |
| <a id="version"></a> `version` | `readonly` | `1` | The version number of the standard. | [packages/common/src/Type.ts:4458](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L4458) |
SuccessResult - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / [StandardSchemaV1](https://evolu.dev/docs/api-reference/common/Type/namespaces/StandardSchemaV1) / SuccessResult
# Interface: SuccessResult\<Output\>
Defined in: [packages/common/src/Type.ts:4473](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L4473)
The result interface if validation succeeds.
## Type Parameters
| Type Parameter |
| -------------- |
| `Output` |
## Properties
| Property | Modifier | Type | Description | Defined in |
| ----------------------------- | ---------- | ----------- | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="issues"></a> `issues?` | `readonly` | `undefined` | The non-existent issues. | [packages/common/src/Type.ts:4477](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L4477) |
| <a id="value"></a> `value` | `readonly` | `Output` | The typed output value. | [packages/common/src/Type.ts:4475](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L4475) |
Types - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / [StandardSchemaV1](https://evolu.dev/docs/api-reference/common/Type/namespaces/StandardSchemaV1) / Types
# Interface: Types\<Input, Output\>
Defined in: [packages/common/src/Type.ts:4501](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L4501)
The Standard Schema types interface.
## Type Parameters
| Type Parameter | Default type |
| -------------- | ------------ |
| `Input` | `unknown` |
| `Output` | `Input` |
## Properties
| Property | Modifier | Type | Description | Defined in |
| ------------------------------ | ---------- | -------- | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="input-1"></a> `input` | `readonly` | `Input` | The input type of the schema. | [packages/common/src/Type.ts:4503](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L4503) |
| <a id="output-1"></a> `output` | `readonly` | `Output` | The output type of the schema. | [packages/common/src/Type.ts:4505](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L4505) |
InferInput - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / [StandardSchemaV1](https://evolu.dev/docs/api-reference/common/Type/namespaces/StandardSchemaV1) / InferInput
# Type Alias: InferInput\<Schema\>
```ts
type InferInput<Schema> = NonNullable<Schema["~standard"]["types"]>["input"];
```
Defined in: [packages/common/src/Type.ts:4509](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L4509)
Infers the input type of a Standard Schema.
## Type Parameters
| Type Parameter |
| -------------------------------------------------------------------------------------------------------- |
| `Schema` _extends_ [`StandardSchemaV1`](https://evolu.dev/docs/api-reference/common/Type/interfaces/StandardSchemaV1) |
InferOutput - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / [StandardSchemaV1](https://evolu.dev/docs/api-reference/common/Type/namespaces/StandardSchemaV1) / InferOutput
# Type Alias: InferOutput\<Schema\>
```ts
type InferOutput<Schema> = NonNullable<Schema["~standard"]["types"]>["output"];
```
Defined in: [packages/common/src/Type.ts:4514](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L4514)
Infers the output type of a Standard Schema.
## Type Parameters
| Type Parameter |
| -------------------------------------------------------------------------------------------------------- |
| `Schema` _extends_ [`StandardSchemaV1`](https://evolu.dev/docs/api-reference/common/Type/interfaces/StandardSchemaV1) |
Result - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [Type](https://evolu.dev/docs/api-reference/common/Type) / [StandardSchemaV1](https://evolu.dev/docs/api-reference/common/Type/namespaces/StandardSchemaV1) / Result
# Type Alias: Result\<Output\>
```ts
type Result<Output> = SuccessResult<Output> | FailureResult;
```
Defined in: [packages/common/src/Type.ts:4470](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/Type.ts#L4470)
The result interface of the validate function.
## Type Parameters
| Type Parameter |
| -------------- |
| `Output` |
getJsonObjectArgs - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first/Public](https://evolu.dev/docs/api-reference/common/local-first/Public) / [kysely](https://evolu.dev/docs/api-reference/common/local-first/Public/namespaces/kysely) / getJsonObjectArgs
# Function: getJsonObjectArgs()
```ts
function getJsonObjectArgs(node, table): (string | Expression<unknown>)[];
```
Defined in: [packages/common/src/local-first/PublicKysely.ts:207](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/PublicKysely.ts#L207)
## Parameters
| Parameter | Type |
| --------- | ----------------- |
| `node` | `SelectQueryNode` |
| `table` | `string` |
## Returns
(`string` \| `Expression`\<`unknown`\>)[]
jsonArrayFrom - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first/Public](https://evolu.dev/docs/api-reference/common/local-first/Public) / [kysely](https://evolu.dev/docs/api-reference/common/local-first/Public/namespaces/kysely) / jsonArrayFrom
# Function: jsonArrayFrom()
```ts
function jsonArrayFrom<O>(expr): RawBuilder<Simplify<O>[]>;
```
Defined in: [packages/common/src/local-first/PublicKysely.ts:70](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/PublicKysely.ts#L70)
A SQLite helper for aggregating a subquery into a JSON array.
### Examples
```ts
// TODO: Update for Evolu
const result = await db
.selectFrom("person")
.select((eb) => [
"id",
kysely
.jsonArrayFrom(
eb
.selectFrom("pet")
.select(["pet.id as pet_id", "pet.name"])
.whereRef("pet.owner_id", "=", "person.id")
.orderBy("pet.name"),
)
.as("pets"),
])
.execute();
result[0]?.id;
result[0]?.pets[0].pet_id;
result[0]?.pets[0].name;
```
The generated SQL (SQLite):
```sql
select "id", (
select coalesce(json_group_array(json_object(
'pet_id', "agg"."pet_id",
'name', "agg"."name"
)), '[]') from (
select "pet"."id" as "pet_id", "pet"."name"
from "pet"
where "pet"."owner_id" = "person"."id"
order by "pet"."name"
) as "agg"
) as "pets"
from "person"
```
## Type Parameters
| Type Parameter |
| -------------- |
| `O` |
## Parameters
| Parameter | Type |
| --------- | ------------------------------------- |
| `expr` | `SelectQueryBuilderExpression`\<`O`\> |
## Returns
`RawBuilder`\<`Simplify`\<`O`\>[]\>
jsonBuildObject - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first/Public](https://evolu.dev/docs/api-reference/common/local-first/Public) / [kysely](https://evolu.dev/docs/api-reference/common/local-first/Public/namespaces/kysely) / jsonBuildObject
# Function: jsonBuildObject()
```ts
function jsonBuildObject<O>(
obj,
): RawBuilder<
Simplify<{
[K in string | number | symbol]: O[K] extends Expression<V> ? V : never;
}>
>;
```
Defined in: [packages/common/src/local-first/PublicKysely.ts:177](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/PublicKysely.ts#L177)
The SQLite `json_object` function.
### Examples
```ts
// TODO: Update for Evolu
const result = await db
.selectFrom("person")
.select((eb) => [
"id",
kysely
.jsonBuildObject({
first: eb.ref("first_name"),
last: eb.ref("last_name"),
full: kysely.sql<string>`first_name || ' ' || last_name`,
})
.as("name"),
])
.execute();
result[0]?.id;
result[0]?.name.first;
result[0]?.name.last;
result[0]?.name.full;
```
The generated SQL (SQLite):
```sql
select "id", json_object(
'first', first_name,
'last', last_name,
'full', "first_name" || ' ' || "last_name"
) as "name"
from "person"
```
## Type Parameters
| Type Parameter |
| ------------------------------------------------------------- |
| `O` _extends_ `Record`\<`string`, `Expression`\<`unknown`\>\> |
## Parameters
| Parameter | Type |
| --------- | ---- |
| `obj` | `O` |
## Returns
`RawBuilder`\<`Simplify`\<\{ \[K in string \| number \| symbol\]: O\[K\] extends Expression\<V\> ? V : never \}\>\>
jsonObjectFrom - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first/Public](https://evolu.dev/docs/api-reference/common/local-first/Public) / [kysely](https://evolu.dev/docs/api-reference/common/local-first/Public/namespaces/kysely) / jsonObjectFrom
# Function: jsonObjectFrom()
```ts
function jsonObjectFrom<O>(expr): RawBuilder<Simplify<O> | null>;
```
Defined in: [packages/common/src/local-first/PublicKysely.ts:127](https://github.com/evoluhq/evolu/blob/c80ab9b71a57e4d502002a463fd2e6cf42d00103/packages/common/src/local-first/PublicKysely.ts#L127)
A SQLite helper for turning a subquery into a JSON object.
The subquery must only return one row.
### Examples
```ts
// TODO: Update for Evolu
const result = await db
.selectFrom("person")
.select((eb) => [
"id",
jsonObjectFrom(
eb
.selectFrom("pet")
.select(["pet.id as pet_id", "pet.name"])
.whereRef("pet.owner_id", "=", "person.id")
.where("pet.is_favorite", "=", true),
).as("favorite_pet"),
])
.execute();
result[0]?.id;
result[0]?.favorite_pet?.pet_id;
result[0]?.favorite_pet?.name;
```
The generated SQL (SQLite):
```sql
select "id", (
select json_object(
'pet_id', "obj"."pet_id",
'name', "obj"."name"
) from (
select "pet"."id" as "pet_id", "pet"."name"
from "pet"
where "pet"."owner_id" = "person"."id"
and "pet"."is_favorite" = ?
) as obj
) as "favorite_pet"
from "person";
```
## Type Parameters
| Type Parameter |
| -------------- |
| `O` |
## Parameters
| Parameter | Type |
| --------- | ------------------------------------- |
| `expr` | `SelectQueryBuilderExpression`\<`O`\> |
## Returns
`RawBuilder`\<`Simplify`\<`O`\> \| `null`\>
NotNull - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first/Public](https://evolu.dev/docs/api-reference/common/local-first/Public) / [kysely](https://evolu.dev/docs/api-reference/common/local-first/Public/namespaces/kysely) / NotNull
# Type Alias: NotNull
```ts
type NotNull = object;
```
Defined in: node_modules/kysely/dist/esm/util/type-utils.d.ts:137
A type constant for marking a column as not null. Can be used with `$narrowPartial`.
Example:
```ts
await db
.selectFrom("person")
.where("nullable_column", "is not", null)
.selectAll()
.$narrowType<{ nullable_column: NotNull }>()
.executeTakeFirstOrThrow();
```
## Properties
### \_\_notNull\_\_
```ts
readonly __notNull__: unique symbol;
```
Defined in: node_modules/kysely/dist/esm/util/type-utils.d.ts:138
sql - API reference
export const sections = [];
[API reference](https://evolu.dev/docs/api-reference) / [@evolu/common](https://evolu.dev/docs/api-reference/common) / [local-first/Public](https://evolu.dev/docs/api-reference/common/local-first/Public) / [kysely](https://evolu.dev/docs/api-reference/common/local-first/Public/namespaces/kysely) / sql
# Variable: sql
```ts
const sql: Sql;
```
Defined in: node_modules/kysely/dist/esm/raw-builder/sql.d.ts:366
Get started with the library
# Get started with the library
This guide will get you up and running with Evolu Library.
<Note>
Requirements: `TypeScript 5.7` or later with the `strict` flag enabled in
`tsconfig.json` file.
</Note>
## Installation
```bash
npm install @evolu/common
```
## Learning path
We recommend learning Evolu Library in this order:
### 1. Result – Error handling
Start with [`Result`](https://evolu.dev/docs/api-reference/common/Result/type-aliases/Result), which provides a type-safe way to handle errors without exceptions. It's the foundation for composable error handling throughout Evolu.
### 2. Task – Asynchronous operations
Learn [`Task`](https://evolu.dev/docs/api-reference/common/Task/interfaces/Task), which represents asynchronous computations in a lazy, composable way.
### 3. Type – Runtime validation
Understand the [`Type`](https://evolu.dev/docs/api-reference/common/Type) system for runtime validation and parsing. This enables you to enforce constraints at compile-time and validate untrusted data at runtime.
### 4. Dependency injection
Explore the [dependency injection pattern](https://evolu.dev/docs/dependency-injection) used throughout Evolu for decoupled, testable code.
### 5. Conventions
Review the [Evolu conventions](https://evolu.dev/docs/conventions) to understand the codebase style and patterns.
## Exploring the API
After understanding the core concepts, explore the full API in the [API reference](https://evolu.dev/docs/api-reference/common). All code is commented and test files are written to be read as examples—they demonstrate practical usage patterns and edge cases.
Get started with local-first
# Get started with local-first
This guide will get you all set up and ready to use Evolu.
<Note>
Requirements: `TypeScript 5.7` or later with the `strict` and
`exactOptionalPropertyTypes` flags enabled in `tsconfig.json` file.
</Note>
## Installation
Evolu offers SDKs for a variety of frameworks, including React, Svelte, React Native, Expo, and others. Below, you can see how to install the SDKs for each framework.
<SinglePlatformCodeGroup>
```bash {{ title: 'React' }}
npm install @evolu/common @evolu/react @evolu/react-web
```
```bash {{ title: 'React Native' }}
npm install @evolu/common @evolu/react @evolu/react-native \
@op-engineering/op-sqlite react-native-quick-crypto
```
```bash {{ title: 'Expo' }}
npm install @evolu/common @evolu/react @evolu/react-native \
expo-sqlite react-native-quick-crypto
```
```bash {{ title: 'Svelte' }}
npm install @evolu/common @evolu/web @evolu/svelte
```
```bash {{ title: 'Vue' }}
npm install @evolu/common @evolu/web @evolu/vue
```
```bash {{ title: 'Vanilla JS' }}
npm install @evolu/common @evolu/web
```
</SinglePlatformCodeGroup>
<ConditionalPlatformAlert platform={["Expo"]} type="warning">
**Expo Go is not supported** as it requires native dependencies
(`react-native-quick-crypto`). Use `expo-sqlite` for standard performance or
`expo-op-sqlite` for better performance.
</ConditionalPlatformAlert>
<ConditionalPlatformAlert platform={["Expo", "React Native"]} type="info">
Make sure to follow the [react-native-quick-crypto setup
instructions](https://github.com/margelo/react-native-quick-crypto#installation)
for proper native dependency configuration. See the [react-expo
example](https://github.com/evoluhq/evolu/tree/main/examples/react-expo) for
required polyfills.
</ConditionalPlatformAlert>
## Define schema
First, define your app database schema—tables, columns, and types.
Evolu uses [Type](https://evolu.dev/docs/api-reference/common/Type) for data modeling. Instead of plain JS types like string or number, we recommend using branded types to enforce domain rules.
```ts
// Primary keys are branded types, preventing accidental use of IDs across
// different tables (e.g., a TodoId can't be used where a UserId is expected).
const TodoId = Evolu.id("Todo");
type TodoId = typeof TodoId.Type;
// Schema defines database structure with runtime validation.
// Column types validate data on insert/update/upsert.
const Schema = {
todo: {
id: TodoId,
// Branded type ensuring titles are non-empty and ≤100 chars.
title: Evolu.NonEmptyString100,
// SQLite doesn't support the boolean type; it uses 0 and 1 instead.
isCompleted: Evolu.nullOr(Evolu.SqliteBoolean),
},
};
```
<Note>
Evolu automatically adds [system
columns](https://evolu.dev/docs/api-reference/common/local-first/variables/SystemColumns-1):
`createdAt`, `updatedAt`, `isDeleted`, and `ownerId`.
</Note>
## Create Evolu
After defining the schema, create an Evolu instance for your environment.
<SinglePlatformCodeGroup>
```ts {{ title: 'React', language: 'tsx' }}
const evolu = createEvolu(evoluReactWebDeps)(Schema, {
name: SimpleName.orThrow("your-app-name"),
transports: [{ type: "WebSocket", url: "wss://your-sync-url" }], // optional, defaults to free.evoluhq.com
});
// Wrap your app with <EvoluProvider>
<EvoluProvider value={evolu}>
{/* ... */}
</EvoluProvider>
// Create a typed React Hook returning an instance of Evolu
const useEvolu = createUseEvolu(evolu);
// Use the Hook in your app
const { insert, update } = useEvolu();
```
```ts {{ title: 'React Native', language: 'tsx' }}
const evolu = createEvolu(evoluReactNativeDeps)(Schema, {
name: SimpleName.orThrow("your-app-name"),
transports: [{ type: "WebSocket", url: "wss://your-sync-url" }], // optional, defaults to free.evoluhq.com
});
// Wrap your app with <EvoluProvider>
<EvoluProvider value={evolu}>
{/* ... */}
</EvoluProvider>
// Create a typed React Hook returning an instance of Evolu
const useEvolu = createUseEvolu(evolu);
// Use the Hook in your app
const { insert, update } = useEvolu();
```
```ts {{ title: 'Expo', language: 'tsx' }}
const evolu = createEvolu(evoluReactNativeDeps)(Schema, {
name: SimpleName.orThrow("your-app-name"),
transports: [{ type: "WebSocket", url: "wss://your-sync-url" }], // optional, defaults to free.evoluhq.com
});
// Wrap your app with <EvoluProvider>
<EvoluProvider value={evolu}>
{/* ... */}
</EvoluProvider>
// Create a typed React Hook returning an instance of Evolu
const useEvolu = createUseEvolu(evolu);
// Use the Hook in your app
const { insert, update } = useEvolu();
```
```ts {{ title: 'Svelte'}}
const evolu = Evolu.createEvolu(evoluSvelteDeps)(Schema, {
name: Evolu.SimpleName.orThrow("your-app-name"),
transports: [{ type: "WebSocket", url: "wss://your-sync-url" }], // optional, defaults to free.evoluhq.com
});
```
```ts {{ title: 'Vue', language: 'ts' }}
const evolu = createEvolu(evoluWebDeps)(Schema, {
name: SimpleName.orThrow("your-app-name"),
transports: [{ type: "WebSocket", url: "wss://your-sync-url" }], // optional, defaults to free.evoluhq.com
});
export default defineComponent({
setup() {
provideEvolu(evolu);
const { insert, update } = evolu;
return { insert, update };
},
});
```
```ts {{ title: 'Vanilla JS' }}
const evolu = createEvolu(evoluWebDeps)(Schema, {
name: SimpleName.orThrow("your-app-name"),
transports: [{ type: "WebSocket", url: "wss://your-sync-url" }], // optional, defaults to free.evoluhq.com
});
```
</SinglePlatformCodeGroup>
## Mutate data
<SinglePlatformCodeGroup>
```ts {{ title: 'React', language: 'tsx' }}
const { insert, update } = useEvolu();
const result = insert("todo", {
title: "New Todo",
isCompleted: Evolu.sqliteFalse,
});
if (result.ok) {
update("todo", { id: result.value.id, isCompleted: Evolu.sqliteTrue });
}
```
```ts {{ title: 'React Native', language: 'tsx' }}
const { insert, update } = useEvolu();
const result = insert("todo", {
title: "New Todo",
isCompleted: Evolu.sqliteFalse,
});
if (result.ok) {
update("todo", { id: result.value.id, isCompleted: Evolu.sqliteTrue });
}
```
```ts {{ title: 'Expo', language: 'tsx' }}
const { insert, update } = useEvolu();
const result = insert("todo", {
title: "New Todo",
isCompleted: Evolu.sqliteFalse,
});
if (result.ok) {
update("todo", { id: result.value.id, isCompleted: Evolu.sqliteTrue });
}
```
```ts {{ title: 'Svelte', language: 'ts' }}
const result = evolu.insert("todo", {
title: "New Todo",
isCompleted: Evolu.sqliteFalse,
});
if (result.ok) {
evolu.update("todo", { id: result.value.id, isCompleted: Evolu.sqliteTrue });
}
```
```ts {{ title: 'Vue', language: 'ts' }}
const { insert, update } = evolu;
const result = insert("todo", {
title: "New Todo",
isCompleted: Evolu.sqliteFalse,
});
if (result.ok) {
update("todo", { id: result.value.id, isCompleted: Evolu.sqliteTrue });
}
```
```ts {{ title: 'Vanilla JS' }}
const result = evolu.insert("todo", {
title: "New Todo",
isCompleted: Evolu.sqliteFalse,
});
if (result.ok) {
evolu.update("todo", { id: result.value.id, isCompleted: Evolu.sqliteTrue });
}
```
</SinglePlatformCodeGroup>
## Query data
Evolu uses type-safe TypeScript SQL query builder [Kysely](https://github.com/koskimas/kysely), so autocompletion works out-of-the-box.
Let's start with a simple `Query`.
```ts
const allTodos = evolu.createQuery((db) => db.selectFrom("todo").selectAll());
```
Once we have a query, we can load or subscribe to it.
<SinglePlatformCodeGroup>
```ts {{ title: 'React' }}
// ...
const todos = useQuery(allTodos);
```
```ts {{ title: 'React Native' }}
// ...
const todos = useQuery(allTodos);
```
```ts {{ title: 'Expo' }}
// ...
const todos = useQuery(allTodos);
```
```ts {{ title: 'Svelte' }}
// Query once
const todosOnce = await evolu.loadQuery(allTodos);
// todosOnce.rows for all entries
// Subscribe to changes, automatically filled when the Data changes
const todos = queryState(evolu, () => allTodos);
// todos.rows for all entries
// Note this only works in .svelte or .svelte.js / .svelte.ts files due to the Svelte compiler
```
```ts {{ title: 'Vue' }}
const todos = useQuery(allTodos);
```
```ts {{ title: 'Vanilla JS' }}
// Query once
const todos = await evolu.loadQuery(allTodos);
const unsubscribe = evolu.subscribeQuery(allTodos)(() => {
const rows = evolu.getQueryRows(allTodos);
// do something with rows
});
```
</SinglePlatformCodeGroup>
## Delete data
To delete a row, set `isDeleted` to `sqliteTrue` (1). Evolu uses **soft deletes** instead of permanent deletion.
<SinglePlatformCodeGroup>
```ts {{ title: 'React', language: 'tsx' }}
const { update } = useEvolu();
// Mark a todo as deleted
update("todo", { id: todoId, isDeleted: Evolu.sqliteTrue });
```
```ts {{ title: 'React Native', language: 'tsx' }}
const { update } = useEvolu();
// Mark a todo as deleted
update("todo", { id: todoId, isDeleted: Evolu.sqliteTrue });
```
```ts {{ title: 'Expo', language: 'tsx' }}
const { update } = useEvolu();
// Mark a todo as deleted
update("todo", { id: todoId, isDeleted: Evolu.sqliteTrue });
```
```ts {{ title: 'Svelte', language: 'ts' }}
// Mark a todo as deleted
evolu.update("todo", { id: todoId, isDeleted: Evolu.sqliteTrue });
```
```ts {{ title: 'Vue', language: 'ts' }}
const { update } = evolu;
// Mark a todo as deleted
update("todo", { id: todoId, isDeleted: Evolu.sqliteTrue });
```
```ts {{ title: 'Vanilla JS' }}
// Mark a todo as deleted
evolu.update("todo", { id: todoId, isDeleted: Evolu.sqliteTrue });
```
</SinglePlatformCodeGroup>
When querying, filter out deleted rows:
```ts
const activeTodos = evolu.createQuery((db) =>
db
.selectFrom("todo")
.selectAll()
// Filter out deleted rows
.where("isDeleted", "is not", Evolu.sqliteTrue)
.orderBy("createdAt"),
);
```
<Warn>
Evolu does not permanently delete data—it marks them as deleted to support
merging across devices and time travel. This is essential for local-first
systems where devices sync asynchronously. See [Time
Travel](https://evolu.dev/docs/time-travel) to learn how to recover deleted data.
</Warn>
## Protect data
**Privacy is essential for Evolu**, so all data are **encrypted** with an encryption key derived from a cryptographically strong secret (which can be represented as a [mnemonic](https://github.com/bitcoin/bips/blob/master/bip-0039.mediawiki)) or provided by an external hardware device.
<SinglePlatformCodeGroup>
```ts {{ title: 'React', language: 'tsx' }}
// ...
const evolu = useEvolu();
const owner = use(evolu.appOwner);
console.log(owner.mnemonic);
// this will print the mnemonic in the console
```
```ts {{ title: 'React Native', language: 'tsx' }}
// ...
const evolu = useEvolu();
const owner = use(evolu.appOwner);
console.log(owner.mnemonic);
// this will print the mnemonic in the console
```
```ts {{ title: 'Expo', language: 'tsx' }}
// ...
const evolu = useEvolu();
const owner = use(evolu.appOwner);
console.log(owner.mnemonic);
// this will print the mnemonic in the console
```
```ts {{ title: 'Svelte' }}
const owner = appOwnerState(evolu);
// use owner.current in your templates
```
```ts {{ title: 'Vue', language: 'ts' }}
const evolu = useEvolu();
const owner = await evolu.appOwner;
console.log(owner.mnemonic);
```
```ts {{ title: 'Vanilla JS' }}
const owner = await evolu.appOwner;
console.log(owner.mnemonic);
```
</SinglePlatformCodeGroup>
## Purge data
To clear all local data from the device (this is different from soft deletes):
```ts
evolu.resetAppOwner();
```
<Note>
This removes all data from the local database. This is not a soft delete—it's
a complete reset.
</Note>
## Restore data
To restore synced data on any device:
```ts
evolu.restoreAppOwner(mnemonic);
```
To learn more about Evolu, explore our [playgrounds](https://evolu.dev/docs/playgrounds) and [examples](https://evolu.dev/docs/examples).
Documentation
# Documentation
Evolu is both a **TypeScript library** and a **local-first platform**. Choose your path below.
## TypeScript library
For anyone who wants to write TypeScript code that scales. Built on proven design patterns like Result, dependency injection, immutability, and more. Created by someone who spent years with functional programming, but then decided to go back to the simple and idiomatic TypeScript code—no pipes, no black-box abstractions, no unreadable stacktraces.
[**Get started with the library** →](https://evolu.dev/docs/library)
## Local-first platform
A complete platform for building apps where users own their data. Works offline-first with sync via self-hostable or cloud relays. End-to-end encrypted by default. Built on SQLite with a scalable sync protocol designed for real-world use. No vendor lock-in, no data hostage situations.
[**Get started with local-first** →](https://evolu.dev/docs/local-first)
Privacy
export const sections = [];
# Privacy
Privacy is fundamental to local-first software, and Evolu takes it seriously. Unlike traditional client-server applications where data lives on someone else's servers, Evolu ensures that data remains under the user's complete control while providing the synchronization and backup benefits needed.
## End-to-end encryption by default
Everything in Evolu is encrypted end-to-end. This means:
- Data is stored in encrypted SQLite on the device
- Data is always encrypted when it leaves the device
- The Evolu Relay receives only encrypted data
- Only devices with the correct encryption keys can decrypt the data
- Even if someone intercepts the data in transit or gains access to the relay, they see only meaningless encrypted bytes
The encryption happens automatically—developers don't need to configure it, and users don't need to think about it.
## API design prevents data leaks
Evolu's API is designed to prevent developers from accidentally leaking sensitive data:
- **No public data options**: There is no API to mark data as "public" or "unencrypted"
- **No configuration required**: Developers cannot disable encryption or create security vulnerabilities through misconfiguration
## Traffic analysis protection
To prevent traffic analysis attacks, Evolu uses message padding (PADMÉ)—a [technique](https://lbarman.ch/blog/padme/) that pads binary messages to obscure their actual size. Combined with end-to-end encryption, this ensures that traffic analysis cannot reveal information about data or usage patterns.
## Relay blindness by design
The Evolu Relay is completely blind to user data. What the relay sees:
- **OwnerId**: A unique identifier for the data owner (but not who that owner is)
- **Timestamps**: When changes occurred (for synchronization ordering)
- **Encrypted binary blobs**: The actual data, completely encrypted and padded to obscure size
- **IP addresses**: Network addresses of connecting clients (standard for any network service unless using Tor or similar privacy networks)
The relay functions purely as a message buffer for synchronization and backup—it stores and forwards encrypted messages without any ability to decrypt, analyze, or understand them.
## Timestamp metadata & activity privacy
Relays and collaborators can see timestamps (user activity). This does not increase risk compared to any real‑time messaging system where traffic timing is observable.
### Why timestamps are visible
Real‑time communication inherently reveals that “something happened” (bytes were transferred). Even if we hid explicit timestamps, an observer could record packet timing. Relying on participants not to store this information is unsafe, so explicitly exposing timestamp metadata doesn't add additional risk.
### Mitigating activity leakage
If maximum privacy is required (e.g., hiding interaction cadence), an application can implement a local write queue:
1. Write changes immediately to a local‑only table
2. Periodically and randomly flush messages to sync tables
- **Trade-off:** It breaks real-time collaboration.
## Post-quantum resistance
### Evolu Relay
The Evolu Relay is post-quantum safe, so "harvest now, decrypt later" attacks (where adversaries collect encrypted data today to decrypt with future quantum computers) are not possible. Unlike public-key cryptography systems that use asymmetric encryption (which quantum computers could potentially break), the relay uses only symmetric encryption.
The Evolu Relay never sees or stores public keys—it only handles symmetrically encrypted data. Symmetric encryption algorithms are considered quantum-safe.
### Collaboration
For collaboration, asymmetric cryptography is required, and asymmetric cryptography can be vulnerable to quantum attacks. Detailed documentation will be provided soon.