API Reference / @evolu/common / Evolu/Internal

Evolu/Internal

🛠️

Example

import { Evolu } from "@evolu/common/evolu";

Interfaces

Interface	Description
AppOwner	The root owner of an Evolu app, created from a mnemonic safely generated on a device when the app is initialized or restored on another device using an existing mnemonic. It manages the app's core data, including the storage of other owners' mnemonics in an encrypted app table. Its `writeKey` is deterministic and rotatable. Never share the AppOwner mnemonic with anyone.
AppState	-
ClientStorage	Common interface for both client and relay SQLite storages.
ClientStorageDep	-
Config	-
ConfigDep	-
CreateAppStateDep	-
CreateDbWorkerDep	-
CreateSyncDep	-
DbSchema	-
DbSnapshot	-
Evolu	-
EvoluConfigWithInitialData	-
EvoluForInitialData	-
FlushSyncDep	-
MutationOptions	-
NetworkError	-
Owner	`Owner` is an entity in Evolu that owns data, meaning it is locally stored on a device under the user’s control. Data can be personal private, peer-to-peer shared, or aggregated from multiple owners.
OwnerRowStoreDep	-
OwnerWithWriteAccess	-
PaymentRequiredError	-
QueryPatches	-
QueryRowsCache	-
Relay	-
RelayConfig	-
ReplaceAllPatch	-
ReplaceAtPatch	-
Row	-
ServerError	-
ShardOwner	Used to shard data within an app for partial or deferred sync. Created in the Evolu `initialData` function or dynamically as needed. Its mnemonic is stored in an app table (encrypted by `AppOwner`) and synced between devices. Its `writeKey` is deterministic and rotatable, enabling selective syncing of data subsets. Not intended for sharing outside the app.
SharedOwner	Used to share data among one or more users, enabling collaboration or controlled access. Its `writeKey` is random (not derived from the mnemonic, stored alongside it in the app table) and rotatable, ensuring it cannot be regenerated by others if shared. Share the `mnemonic` alone for read-only access (as `SharedReadonlyOwner`) or share SharedOwner itself for write access.
SharedReadonlyOwner	Used for sharing data that can only be read, such as with followers or peers in a read-only sync scenario. It lacks a `writeKey`, containing only the `mnemonic` from which `id` and `encryptionKey` are derived by Evolu. Typically derived from a `SharedOwner` by sharing its `mnemonic` without the `writeKey`.
SubscribedQueries	-
Sync	-
SyncConfig	-
SyncDep	-
SyncStateInitial	The initial synchronization state when the app starts. In this state, the app needs to determine whether the data is synced.
SyncStateIsNotSynced	-
SyncStateIsSynced	-
SyncStateIsSyncing	-
Table	-
TimestampConfig	-
TimestampConfigDep	-
TimestampCounterOverflowError	-
TimestampDriftError	-
TimestampDuplicateNodeError	-
TimestampTimeOutOfRangeError	-
ValidEvoluSchemaError	-
ValidMutationSizeError	-

Type Aliases

Type Alias	Description
BinaryTimestamp	BinaryTimestamp is a binary and sortable version of Timestamp for DB.
Counter	-
CreateAppState	-
CreateDbWorker	-
CreateQuery	-
CreateSync	-
DbWorker	-
DbWorkerInput	-
DbWorkerOutput	-
DbWorkerPlatformDeps	-
DefaultColumns	-
EvoluDeps	-
EvoluError	Represent errors that can occur in Evolu.
EvoluSchema	Defines the schema of an Evolu database.
FlushSync	FlushSync is for libraries like React to flush updates synchronously inside the provided callback to ensure the DOM is updated immediately.
Index	-
Indexex	-
InferColumnErrors	-
InferEvoluSchemaError	-
InferMutationTypeErrors	-
InferRow	-
Insertable	-
InsertableProps	-
Millis	-
Mutation	-
MutationKind	-
MutationMapping	-
NodeId	-
OwnerId	-
OwnerRow	An `OwnerRow` represents a row in the `evolu_owner` table, based on an Owner with an added `timestamp` (TimestampString) for CRDT sync. It supports all Owner variants with an optional `writeKey`; use createOwnerRow to align it with a specific Owner.
Patch	-
Queries	-
QueriesToQueryRows	-
QueriesToQueryRowsPromises	-
Query	A type-safe SQL query.
QueryRows	Rows returned by a query.
QueryRowsMap	-
SyncState	The possible states of a synchronization process. The `SyncState` can be one of the following:
Timestamp	-
TimestampError	-
TimestampString	TimestampString is a sortable string version of Timestamp.
Updateable	-
UpdateableProps	-
Upsertable	-
UpsertableProps	-
ValidEvoluSchema	-
ValidMutationSize	-
WriteKey	-

Variables

Variable	Description
binaryTimestampLength	-
Counter	-
createIndex	-
createWebSocketSync	-
DefaultColumns	-
defaultColumnsNames	-
defaultConfig	-
emptyRows	-
formatValidMutationSizeError	-
Index	-
initialSyncState	-
kysely	-
kyselyJsonIdentifier	A unique identifier prepended to JSON-encoded strings. This allows safe detection and parsing of only those columns that require JSON.parse.
maxCounter	-
maxMillis	-
maxMutationSize	Evolu has to limit the maximum mutation size. Otherwise, sync couldn't use the max frame size. The max size is 640KB in bytes, measured via MessagePack. Evolu Protocol DbChange will be smaller thanks to various optimizations.
maxNodeId	-
Millis	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.
minCounter	-
minMillis	-
minNodeId	-
NodeId	A NodeId uniquely identifies an owner's device. Generated once per device using cryptographic randomness.
orderBinaryTimestamp	-
OwnerId	The unique identifier of Owner derived from the Mnemonic.
Timestamp	Hybrid Logical Clock timestamp.
ValidEvoluSchema	Valid EvoluSchema.
WriteKey	A secure token proving the initiator can write changes. Derived from a mnemonic or randomly generated. It's rotatable.
writeKeyLength	-

Functions

Function	Description
applyMessageToTimestampAndHistoryTables	-
applyPatches	-
assertValidEvoluSchema	Asserts that the given value is ValidEvoluSchema.
binaryTimestampToTimestamp	-
createAppOwner	Creates an AppOwner, optionally from an existing mnemonic to restore it on another device; otherwise, generates a new mnemonic.
createAppTable	-
createDbWorkerForPlatform	-
createEvolu	Creates an Evolu instance configured with the specified EvoluSchema and optional configuration.
createIndexes	-
createInitialTimestamp	-
createNamespaceName	-
createOwner	Creates an Owner with optional `mnemonic` and `writeKey`.
createOwnerRow	Creates an OwnerRow from any Owner variant for the `evolu_owner` table, adding a `timestamp` (TimestampString) for CRDT sync.
createQueryRowsCache	-
createRelayStorage	-
createShardOwner	Creates a ShardOwner for sharding app data with a freshly generated mnemonic. Unlike createAppOwner, it doesn’t accept an existing mnemonic because ShardOwner mnemonics are always generated and restored automatically via database sync.
createSharedOwner	Creates a fresh SharedOwner for sharing data with write access. Takes no arguments as both `mnemonic` and rotatable `writeKey` are newly generated; when shared, recipients use the provided `mnemonic` and `writeKey` directly as a SharedOwner without needing to recreate it.
createSharedReadonlyOwner	Creates a SharedReadonlyOwner from a SharedOwner for read-only data sharing. Extracts the `mnemonic` from the provided SharedOwner, omitting its `writeKey` to ensure read-only access.
createSubscribedQueries	-
createTimestamp	-
createWriteKey	-
deserializeQuery	-
getDbSchema	-
getDbSnapshot	-
insertable	Type Factory to create insertable Type. It makes nullable Types optional, omits Id, and ensures the maxMutationSize.
makePatches	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.
maybeMigrateToVersion0	-
parseSqliteJsonArray	-
receiveTimestamp	-
rotateWriteKey	Rotates the WriteKey for an AppOwner, ShardOwner, or SharedOwner, returning a new instance with the updated key.
sendTimestamp	-
serializeQuery	Evolu serializes SqliteQuery into a string to be easily used as a key and for comparison.
timestampStringToTimestamp	-
timestampToBinaryTimestamp	-
timestampToTimestampString	-
updateable	Type Factory to create updateable Type. It makes everything except for the `id` column partial (i.e. optional) and ensures the maxMutationSize.
upsertable	Type Factory to create upsertable Type. It makes nullable Types optional and ensures the maxMutationSize.
validEvoluSchemaToDbSchema	-