API reference / @evolu/common / local-first / Evolu

Interface: Evolu<S>

Defined in: packages/common/src/local-first/Evolu.ts:111

Extends

Disposable

Type Parameters

Type Parameter	Default type
`S` extends `EvoluSchema`	`EvoluSchema`

Properties

Property	Modifier	Type	Description	Defined in
`appOwner`	`readonly`	`Promise`<`AppOwner`>	Promise that resolves to 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
`createQuery`	`readonly`	`CreateQuery`<`S`>	Create type-safe SQL 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, Evolu#update, or Evolu#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
`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
`getError`	`readonly`	() => \| `EvoluError` \| `null`	Get EvoluError.	packages/common/src/local-first/Evolu.ts:127
`getQueryRows`	`readonly`	<`R`>(`query`) => `QueryRows`<`R`>	Get QueryRows. ### Example `const unsubscribe = evolu.subscribeQuery(allTodos)(() => { const rows = evolu.getQueryRows(allTodos); });`	packages/common/src/local-first/Evolu.ts:222
`insert`	`public`	`Mutation`<`S`, `"insert"`>	Inserts a row into the database and returns a Result with the new 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. ### 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
`loadQueries`	`readonly`	<`R`, `Q`>(`queries`) => [`...QueriesToQueryRowsPromises<Q>[]`]	Load an array of Query queries and return an array of 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
`loadQuery`	`readonly`	<`R`>(`query`) => `Promise`<`QueryRows`<`R`>>	Load Query and return a promise with 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. 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. ### 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
`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
`resetAppOwner`	`readonly`	(`options?`) => `Promise`<`void`>	Delete 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
`restoreAppOwner`	`readonly`	(`mnemonic`, `options?`) => `Promise`<`void`>	Restore AppOwner with all their synced data. It uses Evolu#resetAppOwner, so be careful.	packages/common/src/local-first/Evolu.ts:408
`subscribeError`	`readonly`	`StoreSubscribe`	Subscribe to EvoluError changes. ### Example `const unsubscribe = evolu.subscribeError(() => { const error = evolu.getError(); console.log(error); });`	packages/common/src/local-first/Evolu.ts:124
`subscribeQuery`	`readonly`	(`query`) => `StoreSubscribe`	Subscribe to Query QueryRows changes. ### Example `const unsubscribe = evolu.subscribeQuery(allTodos)(() => { const rows = evolu.getQueryRows(allTodos); });`	packages/common/src/local-first/Evolu.ts:209
`update`	`public`	`Mutation`<`S`, `"update"`>	Updates a row in the database and returns a Result with the existing 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. ### 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
`upsert`	`public`	`Mutation`<`S`, `"upsert"`>	Upserts a row in the database and returns a Result with the existing 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. ### 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
`useOwner`	`readonly`	(`owner`) => `UnuseOwner`	`Experimental` Use a SyncOwner. Returns a 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

Methods

[dispose]()

Defined in: node_modules/typescript/lib/lib.esnext.disposable.d.ts:36

Returns

void

Inherited from

Disposable.[dispose]

Defined in: node_modules/@types/node/compatibility/disposable.d.ts:9

Returns

void

Inherited from

Disposable.[dispose]