@livestore/common 0.3.1-dev.0 → 0.3.2-dev.0

package/src/schema/state/sqlite/db-schema/dsl/field-defs.ts

@@ -17,7 +17,7 @@ export const isColumnDefinition = (value: unknown): value is ColumnDefinition<an
     typeof value === 'object' &&
     value !== null &&
     'columnType' in value &&
-    validColumnTypes.includes(value['columnType'] as any)
+    validColumnTypes.includes(value.columnType as any)
   )
 }
 
@@ -36,7 +36,7 @@ export type SqlDefaultValue = {
 }
 
 export const isSqlDefaultValue = (value: unknown): value is SqlDefaultValue => {
-  return typeof value === 'object' && value !== null && 'sql' in value && typeof value['sql'] === 'string'
+  return typeof value === 'object' && value !== null && 'sql' in value && typeof value.sql === 'string'
 }
 
 export type ColDefFn<TColumnType extends FieldColumnType> = {

package/src/schema/state/sqlite/db-schema/hash.ts

@@ -1,8 +1,8 @@
 // Based on https://stackoverflow.com/a/7616484
 export const hashCode = (str: string) => {
-  let hash = 0,
-    i,
-    chr
+  let hash = 0
+  let i: number
+  let chr: number
   if (str.length === 0) return hash
   for (i = 0; i < str.length; i++) {
     // eslint-disable-next-line unicorn/prefer-code-point

package/src/schema/state/sqlite/mod.ts

@@ -6,7 +6,7 @@ import type { InternalState } from '../../schema.js'
 import { ClientDocumentTableDefSymbol, tableIsClientDocumentTable } from './client-document-def.js'
 import { SqliteAst } from './db-schema/mod.js'
 import { stateSystemTables } from './system-tables.js'
-import { type TableDef, type TableDefBase } from './table-def.js'
+import type { TableDef, TableDefBase } from './table-def.js'
 
 export * from './table-def.js'
 export {

package/src/schema/state/sqlite/query-builder/api.ts

@@ -19,7 +19,11 @@ export namespace QueryBuilderAst {
   export interface SelectQuery {
     readonly _tag: 'SelectQuery'
     readonly columns: string[]
-    readonly pickFirst: false | { fallback: () => any } | 'throws'
+    readonly pickFirst:
+      | { _tag: 'disabled' }
+      | { _tag: 'enabled'; behaviour: 'undefined' }
+      | { _tag: 'enabled'; behaviour: 'error' }
+      | { _tag: 'enabled'; behaviour: 'fallback'; fallback: () => any }
     readonly select: {
       columns: ReadonlyArray<string>
     }
@@ -117,7 +121,7 @@ export type QueryBuilder<
 > = {
   readonly [QueryBuilderTypeId]: QueryBuilderTypeId
   readonly [QueryBuilderAstSymbol]: QueryBuilderAst
-  readonly ['ResultType']: TResult
+  readonly ResultType: TResult
   readonly asSql: () => { query: string; bindValues: SqlValue[] }
   readonly toString: () => string
 } & Omit<QueryBuilder.ApiFull<TResult, TTableDef, TWithout>, TWithout>
@@ -167,6 +171,21 @@ export namespace QueryBuilder {
     direction: 'asc' | 'desc'
   }>
 
+  export type FirstQueryBehaviour<TResult, TFallback> =
+    | {
+        /** Will error if no matching row was found */
+        behaviour: 'error'
+      }
+    | {
+        /** Will return `undefined` if no matching row was found */
+        behaviour: 'undefined'
+      }
+    | {
+        /** Will return a fallback value if no matching row was found */
+        behaviour: 'fallback'
+        fallback: () => TResult | TFallback
+      }
+
   export type ApiFull<TResult, TTableDef extends TableDefBase, TWithout extends ApiFeature> = {
     /**
      * `SELECT *` is the default
@@ -285,16 +304,27 @@ export namespace QueryBuilder {
      * Example:
      * ```ts
      * db.todos.first()
-     * db.todos.where('id', '123').first()
+     * db.todos.where('id', '123').first() // will return `undefined` if no rows are returned
+     * db.todos.where('id', '123').first({ behaviour: 'error' }) // will throw if no rows are returned
+     * db.todos.first({ behaviour: 'fallback', fallback: () => ({ id: '123', text: 'Buy milk', status: 'active' }) })
      * ```
      *
-     * Query will throw if no rows are returned and no fallback is provided.
+     * Behaviour:
+     * - `undefined`: Will return `undefined` if no rows are returned (default behaviour)
+     * - `error`: Will throw if no rows are returned
+     * - `fallback`: Will return a fallback value if no rows are returned
      */
-    readonly first: <TFallback = never>(options?: {
-      /** @default 'throws' */
-      fallback?: (() => TFallback | GetSingle<TResult>) | 'throws'
-    }) => QueryBuilder<
-      TFallback | GetSingle<TResult>,
+    readonly first: <
+      TBehaviour extends QueryBuilder.FirstQueryBehaviour<GetSingle<TResult>, TFallback>,
+      TFallback = never,
+    >(
+      behaviour?: QueryBuilder.FirstQueryBehaviour<GetSingle<TResult>, TFallback> & TBehaviour,
+    ) => QueryBuilder<
+      TBehaviour extends { behaviour: 'fallback' }
+        ? ReturnType<TBehaviour['fallback']> | GetSingle<TResult>
+        : TBehaviour extends { behaviour: 'undefined' }
+          ? undefined | GetSingle<TResult>
+          : GetSingle<TResult>,
       TTableDef,
       TWithout | 'row' | 'first' | 'orderBy' | 'select' | 'limit' | 'offset' | 'where' | 'returning' | 'onConflict'
     >

package/src/schema/state/sqlite/query-builder/impl.test.ts

@@ -55,7 +55,7 @@ const UiStateWithDefaultId = State.SQLite.clientDocument({
   },
 })
 
-export const issue = State.SQLite.table({
+const issue = State.SQLite.table({
   name: 'issue',
   columns: {
     id: State.SQLite.integer({ primaryKey: true }),
@@ -120,7 +120,19 @@ describe('query builder', () => {
         }
       `)
 
-      expect(dump(db.todos.select('id', 'text').first({ fallback: () => undefined }))).toMatchInlineSnapshot(`
+      expect(dump(db.todos.select('id', 'text').first({ behaviour: 'error' }))).toMatchInlineSnapshot(`
+        {
+          "bindValues": [
+            1,
+          ],
+          "query": "SELECT id, text FROM 'todos' LIMIT ?",
+          "schema": "(ReadonlyArray<{ readonly id: string; readonly text: string }> <-> { readonly id: string; readonly text: string })",
+        }
+      `)
+
+      expect(
+        dump(db.todos.select('id', 'text').first({ behaviour: 'fallback', fallback: () => undefined })),
+      ).toMatchInlineSnapshot(`
         {
           "bindValues": [
             1,
@@ -166,8 +178,9 @@ describe('query builder', () => {
           "schema": "ReadonlyArray<{ readonly id: string; readonly text: string }>",
         }
       `)
-      expect(dump(db.todos.select('id', 'text').where({ deletedAt: { op: '<=', value: new Date('2024-01-01') } })))
-        .toMatchInlineSnapshot(`
+      expect(
+        dump(db.todos.select('id', 'text').where({ deletedAt: { op: '<=', value: new Date('2024-01-01') } })),
+      ).toMatchInlineSnapshot(`
           {
             "bindValues": [
               "2024-01-01T00:00:00.000Z",
@@ -176,8 +189,9 @@ describe('query builder', () => {
             "schema": "ReadonlyArray<{ readonly id: string; readonly text: string }>",
           }
         `)
-      expect(dump(db.todos.select('id', 'text').where({ status: { op: 'IN', value: ['active'] } })))
-        .toMatchInlineSnapshot(`
+      expect(
+        dump(db.todos.select('id', 'text').where({ status: { op: 'IN', value: ['active'] } })),
+      ).toMatchInlineSnapshot(`
           {
             "bindValues": [
               "active",
@@ -186,8 +200,9 @@ describe('query builder', () => {
             "schema": "ReadonlyArray<{ readonly id: string; readonly text: string }>",
           }
         `)
-      expect(dump(db.todos.select('id', 'text').where({ status: { op: 'NOT IN', value: ['active', 'completed'] } })))
-        .toMatchInlineSnapshot(`
+      expect(
+        dump(db.todos.select('id', 'text').where({ status: { op: 'NOT IN', value: ['active', 'completed'] } })),
+      ).toMatchInlineSnapshot(`
           {
             "bindValues": [
               "active",
@@ -197,6 +212,25 @@ describe('query builder', () => {
             "schema": "ReadonlyArray<{ readonly id: string; readonly text: string }>",
           }
         `)
+
+      expect(
+        dump(
+          db.todos
+            .select('id', 'text')
+            .where({ completed: false })
+            .where({ status: { op: 'IN', value: ['active'] } })
+            .where({ deletedAt: undefined }),
+        ),
+      ).toMatchInlineSnapshot(`
+          {
+            "bindValues": [
+              0,
+              "active",
+            ],
+            "query": "SELECT id, text FROM 'todos' WHERE completed = ? AND status IN (?)",
+            "schema": "ReadonlyArray<{ readonly id: string; readonly text: string }>",
+          }
+        `)
     })
 
     it('should handle OFFSET and LIMIT clauses', () => {
@@ -375,8 +409,9 @@ describe('query builder', () => {
     })
 
     it('should handle INSERT queries with undefined values', () => {
-      expect(dump(db.todos.insert({ id: '123', text: 'Buy milk', status: 'active', completed: undefined })))
-        .toMatchInlineSnapshot(`
+      expect(
+        dump(db.todos.insert({ id: '123', text: 'Buy milk', status: 'active', completed: undefined })),
+      ).toMatchInlineSnapshot(`
         {
           "bindValues": [
             "123",
@@ -443,8 +478,9 @@ describe('query builder', () => {
     })
 
     it('should handle UPDATE queries with undefined values', () => {
-      expect(dump(db.todos.update({ status: undefined, text: 'some text' }).where({ id: '123' })))
-        .toMatchInlineSnapshot(`
+      expect(
+        dump(db.todos.update({ status: undefined, text: 'some text' }).where({ id: '123' })),
+      ).toMatchInlineSnapshot(`
         {
           "bindValues": [
             "some text",
@@ -483,8 +519,9 @@ describe('query builder', () => {
     })
 
     it('should handle INSERT with ON CONFLICT', () => {
-      expect(dump(db.todos.insert({ id: '123', text: 'Buy milk', status: 'active' }).onConflict('id', 'ignore')))
-        .toMatchInlineSnapshot(`
+      expect(
+        dump(db.todos.insert({ id: '123', text: 'Buy milk', status: 'active' }).onConflict('id', 'ignore')),
+      ).toMatchInlineSnapshot(`
         {
           "bindValues": [
             "123",
@@ -516,8 +553,9 @@ describe('query builder', () => {
         }
       `)
 
-      expect(dump(db.todos.insert({ id: '123', text: 'Buy milk', status: 'active' }).onConflict('id', 'replace')))
-        .toMatchInlineSnapshot(`
+      expect(
+        dump(db.todos.insert({ id: '123', text: 'Buy milk', status: 'active' }).onConflict('id', 'replace')),
+      ).toMatchInlineSnapshot(`
         {
           "bindValues": [
             "123",
@@ -547,8 +585,9 @@ describe('query builder', () => {
     })
 
     it('should handle RETURNING clause', () => {
-      expect(dump(db.todos.insert({ id: '123', text: 'Buy milk', status: 'active' }).returning('id')))
-        .toMatchInlineSnapshot(`
+      expect(
+        dump(db.todos.insert({ id: '123', text: 'Buy milk', status: 'active' }).returning('id')),
+      ).toMatchInlineSnapshot(`
           {
             "bindValues": [
               "123",
@@ -560,8 +599,9 @@ describe('query builder', () => {
           }
         `)
 
-      expect(dump(db.todos.update({ status: 'completed' }).where({ id: '123' }).returning('id')))
-        .toMatchInlineSnapshot(`
+      expect(
+        dump(db.todos.update({ status: 'completed' }).where({ id: '123' }).returning('id')),
+      ).toMatchInlineSnapshot(`
           {
             "bindValues": [
               "completed",

package/src/schema/state/sqlite/query-builder/impl.ts

@@ -1,3 +1,4 @@
+/** biome-ignore-all lint/complexity/noArguments: using arguments is fine here */
 import { casesHandled, shouldNeverHappen } from '@livestore/utils'
 import { Match, Option, Predicate, Schema } from '@livestore/utils/effect'
 
@@ -36,7 +37,7 @@ export const makeQueryBuilder = <TResult, TTableDef extends TableDefBase>(
         select: { columns },
       }) as any
     },
-    // eslint-disable-next-line prefer-arrow/prefer-arrow-functions
+    // biome-ignore lint/complexity/useArrowFunction: prefer function over arrow function for this case
     where: function () {
       if (ast._tag === 'InsertQuery') return invalidQueryBuilder('Cannot use where with insert')
       if (ast._tag === 'RowQuery') return invalidQueryBuilder('Cannot use where with row')
@@ -136,7 +137,7 @@ export const makeQueryBuilder = <TResult, TTableDef extends TableDefBase>(
         ),
       })
     },
-    first: (options) => {
+    first: (behaviour) => {
       assertSelectQueryBuilderAst(ast)
 
       if (ast.limit._tag === 'Some') return invalidQueryBuilder(`.first() can't be called after .limit()`)
@@ -144,8 +145,7 @@ export const makeQueryBuilder = <TResult, TTableDef extends TableDefBase>(
       return makeQueryBuilder(tableDef, {
         ...ast,
         limit: Option.some(1),
-        pickFirst:
-          options?.fallback !== undefined && options.fallback !== 'throws' ? { fallback: options.fallback } : 'throws',
+        pickFirst: { _tag: 'enabled', ...(behaviour ?? { behaviour: 'undefined' }) },
       })
     },
     // // eslint-disable-next-line prefer-arrow/prefer-arrow-functions
@@ -249,7 +249,7 @@ export const makeQueryBuilder = <TResult, TTableDef extends TableDefBase>(
   return {
     [QueryBuilderTypeId]: QueryBuilderTypeId,
     [QueryBuilderAstSymbol]: ast,
-    ['ResultType']: 'only-for-type-inference' as TResult,
+    ResultType: 'only-for-type-inference' as TResult,
     asSql: () => astToSql(ast),
     toString: () => {
       try {
@@ -266,7 +266,7 @@ export const makeQueryBuilder = <TResult, TTableDef extends TableDefBase>(
 const emptyAst = (tableDef: TableDefBase): QueryBuilderAst.SelectQuery => ({
   _tag: 'SelectQuery',
   columns: [],
-  pickFirst: false,
+  pickFirst: { _tag: 'disabled' },
   select: { columns: [] },
   orderBy: [],
   offset: Option.none(),
@@ -280,28 +280,28 @@ const emptyAst = (tableDef: TableDefBase): QueryBuilderAst.SelectQuery => ({
 // eslint-disable-next-line prefer-arrow/prefer-arrow-functions
 function assertSelectQueryBuilderAst(ast: QueryBuilderAst): asserts ast is QueryBuilderAst.SelectQuery {
   if (ast._tag !== 'SelectQuery') {
-    return shouldNeverHappen('Expected SelectQuery but got ' + ast._tag)
+    return shouldNeverHappen(`Expected SelectQuery but got ${ast._tag}`)
   }
 }
 
 // eslint-disable-next-line prefer-arrow/prefer-arrow-functions
 function assertInsertQueryBuilderAst(ast: QueryBuilderAst): asserts ast is QueryBuilderAst.InsertQuery {
   if (ast._tag !== 'InsertQuery') {
-    return shouldNeverHappen('Expected InsertQuery but got ' + ast._tag)
+    return shouldNeverHappen(`Expected InsertQuery but got ${ast._tag}`)
   }
 }
 
 // eslint-disable-next-line prefer-arrow/prefer-arrow-functions
 function assertWriteQueryBuilderAst(ast: QueryBuilderAst): asserts ast is QueryBuilderAst.WriteQuery {
   if (ast._tag !== 'InsertQuery' && ast._tag !== 'UpdateQuery' && ast._tag !== 'DeleteQuery') {
-    return shouldNeverHappen('Expected WriteQuery but got ' + ast._tag)
+    return shouldNeverHappen(`Expected WriteQuery but got ${ast._tag}`)
   }
 }
 
 const isRowQuery = (ast: QueryBuilderAst): ast is QueryBuilderAst.RowQuery => ast._tag === 'RowQuery'
 
 export const invalidQueryBuilder = (msg?: string) => {
-  return shouldNeverHappen('Invalid query builder' + (msg ? `: ${msg}` : ''))
+  return shouldNeverHappen(`Invalid query builder${msg ? `: ${msg}` : ''}`)
 }
 
 export const getResultSchema = (qb: QueryBuilder<any, any, any>): Schema.Schema<any> => {
@@ -309,9 +309,12 @@ export const getResultSchema = (qb: QueryBuilder<any, any, any>): Schema.Schema<
   switch (queryAst._tag) {
     case 'SelectQuery': {
       const arraySchema = Schema.Array(queryAst.resultSchemaSingle)
-      if (queryAst.pickFirst === false) {
+      if (queryAst.pickFirst._tag === 'disabled') {
         return arraySchema
-      } else if (queryAst.pickFirst === 'throws') {
+      } else if (queryAst.pickFirst.behaviour === 'undefined') {
+        const arraySchema = Schema.Array(Schema.UndefinedOr(queryAst.resultSchemaSingle))
+        return arraySchema.pipe(Schema.headOrElse(() => undefined))
+      } else if (queryAst.pickFirst.behaviour === 'error') {
         // Will throw if the array is empty
         return arraySchema.pipe(Schema.headOrElse())
       } else {

package/src/schema/state/sqlite/system-tables.ts

@@ -4,7 +4,7 @@ import * as EventSequenceNumber from '../../EventSequenceNumber.js'
 import { SqliteDsl } from './db-schema/mod.js'
 import { table } from './table-def.js'
 
-/// Read model DB
+/// State DB
 
 export const SCHEMA_META_TABLE = '__livestore_schema'
 
@@ -46,6 +46,7 @@ export const sessionChangesetMetaTable = table({
     // TODO bring back primary key
     seqNumGlobal: SqliteDsl.integer({ schema: EventSequenceNumber.GlobalEventSequenceNumber }),
     seqNumClient: SqliteDsl.integer({ schema: EventSequenceNumber.ClientEventSequenceNumber }),
+    seqNumRebaseGeneration: SqliteDsl.integer({}),
     changeset: SqliteDsl.blob({ nullable: true }),
     debug: SqliteDsl.json({ nullable: true }),
   },
@@ -54,25 +55,7 @@ export const sessionChangesetMetaTable = table({
 
 export type SessionChangesetMetaRow = typeof sessionChangesetMetaTable.Type
 
-export const LEADER_MERGE_COUNTER_TABLE = '__livestore_leader_merge_counter'
-
-// TODO get rid of this table in favour of client-only merge generation
-export const leaderMergeCounterTable = table({
-  name: LEADER_MERGE_COUNTER_TABLE,
-  columns: {
-    id: SqliteDsl.integer({ primaryKey: true, schema: Schema.Literal(0) }),
-    mergeCounter: SqliteDsl.integer({ primaryKey: true }),
-  },
-})
-
-export type LeaderMergeCounterRow = typeof leaderMergeCounterTable.Type
-
-export const stateSystemTables = [
-  schemaMetaTable,
-  schemaEventDefsMetaTable,
-  sessionChangesetMetaTable,
-  leaderMergeCounterTable,
-]
+export const stateSystemTables = [schemaMetaTable, schemaEventDefsMetaTable, sessionChangesetMetaTable] as const
 
 export const isStateSystemTable = (tableName: string) => stateSystemTables.some((_) => _.sqliteDef.name === tableName)
 
@@ -86,8 +69,11 @@ export const eventlogMetaTable = table({
     // TODO Adjust modeling so a global event never needs a client id component
     seqNumGlobal: SqliteDsl.integer({ primaryKey: true, schema: EventSequenceNumber.GlobalEventSequenceNumber }),
     seqNumClient: SqliteDsl.integer({ primaryKey: true, schema: EventSequenceNumber.ClientEventSequenceNumber }),
+    seqNumRebaseGeneration: SqliteDsl.integer({ primaryKey: true }),
     parentSeqNumGlobal: SqliteDsl.integer({ schema: EventSequenceNumber.GlobalEventSequenceNumber }),
     parentSeqNumClient: SqliteDsl.integer({ schema: EventSequenceNumber.ClientEventSequenceNumber }),
+    parentSeqNumRebaseGeneration: SqliteDsl.integer({}),
+    /** Event definition name */
     name: SqliteDsl.text({}),
     argsJson: SqliteDsl.text({ schema: Schema.parseJson(Schema.Any) }),
     clientId: SqliteDsl.text({}),
@@ -97,7 +83,7 @@ export const eventlogMetaTable = table({
   },
   indexes: [
     { columns: ['seqNumGlobal'], name: 'idx_eventlog_seqNumGlobal' },
-    { columns: ['seqNumGlobal', 'seqNumClient'], name: 'idx_eventlog_seqNum' },
+    { columns: ['seqNumGlobal', 'seqNumClient', 'seqNumRebaseGeneration'], name: 'idx_eventlog_seqNum' },
   ],
 })
 
@@ -105,6 +91,7 @@ export type EventlogMetaRow = typeof eventlogMetaTable.Type
 
 export const SYNC_STATUS_TABLE = '__livestore_sync_status'
 
+// TODO support sync backend identity (to detect if sync backend changes)
 export const syncStatusTable = table({
   name: SYNC_STATUS_TABLE,
   columns: {
@@ -114,4 +101,4 @@ export const syncStatusTable = table({
 
 export type SyncStatusRow = typeof syncStatusTable.Type
 
-export const eventlogSystemTables = [eventlogMetaTable, syncStatusTable]
+export const eventlogSystemTables = [eventlogMetaTable, syncStatusTable] as const

package/src/schema/state/sqlite/table-def.ts

@@ -1,4 +1,4 @@
-import { type Nullable } from '@livestore/utils'
+import type { Nullable } from '@livestore/utils'
 import type { Schema, Types } from '@livestore/utils/effect'
 
 import { SqliteDsl } from './db-schema/mod.js'
@@ -177,7 +177,7 @@ export namespace FromColumns {
   export type InsertRowDecoded<TColumns extends SqliteDsl.Columns> = SqliteDsl.FromColumns.InsertRowDecoded<TColumns>
 }
 
-type SqliteTableDefForInput<
+export type SqliteTableDefForInput<
   TName extends string,
   TColumns extends SqliteDsl.Columns | SqliteDsl.ColumnDefinition<any, any>,
 > = SqliteDsl.TableDefinition<TName, PrettifyFlat<ToColumns<TColumns>>>

package/src/schema-management/migrations.ts

@@ -1,7 +1,9 @@
 import { memoizeByStringifyArgs } from '@livestore/utils'
 import { Effect, Schema as EffectSchema } from '@livestore/utils/effect'
 
-import type { MigrationsReport, MigrationsReportEntry, SqliteDb, UnexpectedError } from '../adapter-types.js'
+import type { SqliteDb } from '../adapter-types.js'
+import type { MigrationsReport, MigrationsReportEntry } from '../defs.js'
+import type { UnexpectedError } from '../errors.js'
 import type { LiveStoreSchema } from '../schema/mod.js'
 import { SqliteAst, SqliteDsl } from '../schema/state/sqlite/db-schema/mod.js'
 import type { SchemaEventDefsMetaRow, SchemaMetaRow } from '../schema/state/sqlite/system-tables.js'

package/src/sql-queries/sql-queries.ts

@@ -106,6 +106,7 @@ export const insertRows = <TColumns extends SqliteDsl.Columns>({
 
   const bindValues = valuesArray.reduce(
     (acc, values, itemIndex) => ({
+      // biome-ignore lint/performance/noAccumulatingSpread: TODO improve this some day
       ...acc,
       ...makeBindValues({ columns, values, variablePrefix: `item_${itemIndex}_` }),
     }),
@@ -292,6 +293,7 @@ Error: ${parseErrorStr}
 Value:`,
             value,
           )
+          // biome-ignore lint/suspicious/noDebugger: debug
           debugger
           throw res.left
         } else {

package/src/sqlite-db-helper.ts

@@ -0,0 +1,41 @@
+import { Schema } from '@livestore/utils/effect'
+
+import type { SqliteDb } from './adapter-types.js'
+import { getResultSchema, isQueryBuilder } from './schema/state/sqlite/query-builder/mod.js'
+import type { PreparedBindValues } from './util.js'
+
+export const makeExecute = (
+  execute: (
+    queryStr: string,
+    bindValues: PreparedBindValues | undefined,
+    options?: { onRowsChanged?: (rowsChanged: number) => void },
+  ) => void,
+): SqliteDb['execute'] => {
+  return (...args: any[]) => {
+    const [queryStrOrQueryBuilder, bindValuesOrOptions, maybeOptions] = args
+
+    if (isQueryBuilder(queryStrOrQueryBuilder)) {
+      const { query, bindValues } = queryStrOrQueryBuilder.asSql()
+      return execute(query, bindValues as unknown as PreparedBindValues, bindValuesOrOptions)
+    } else {
+      return execute(queryStrOrQueryBuilder, bindValuesOrOptions, maybeOptions)
+    }
+  }
+}
+
+export const makeSelect = <T>(
+  select: (queryStr: string, bindValues: PreparedBindValues | undefined) => ReadonlyArray<T>,
+): SqliteDb['select'] => {
+  return (...args: any[]) => {
+    const [queryStrOrQueryBuilder, maybeBindValues] = args
+
+    if (isQueryBuilder(queryStrOrQueryBuilder)) {
+      const { query, bindValues } = queryStrOrQueryBuilder.asSql()
+      const resultSchema = getResultSchema(queryStrOrQueryBuilder)
+      const results = select(query, bindValues as unknown as PreparedBindValues)
+      return Schema.decodeSync(resultSchema)(results)
+    } else {
+      return select(queryStrOrQueryBuilder, maybeBindValues)
+    }
+  }
+}

package/src/sqlite-types.ts

@@ -0,0 +1,76 @@
+import { type Effect, Schema } from '@livestore/utils/effect'
+import type { SqliteError, UnexpectedError } from './errors.js'
+import type { EventSequenceNumber } from './schema/mod.js'
+import type { QueryBuilder } from './schema/state/sqlite/query-builder/api.js'
+import type { PreparedBindValues } from './util.js'
+
+/**
+ * Common interface for SQLite databases used by LiveStore to facilitate a consistent API across different platforms.
+ * Always assumes a synchronous SQLite build with the `bytecode` and `session` extensions enabled.
+ * Can be either in-memory or persisted to disk.
+ */
+export interface SqliteDb<TReq = any, TMetadata extends TReq = TReq> {
+  _tag: 'SqliteDb'
+  metadata: TMetadata
+  /** Debug information (currently not persisted and only available at runtime) */
+  debug: SqliteDebugInfo
+  prepare(queryStr: string): PreparedStatement
+  execute(
+    queryStr: string,
+    bindValues?: PreparedBindValues | undefined,
+    options?: { onRowsChanged?: (rowsChanged: number) => void },
+  ): void
+  execute(queryBuilder: QueryBuilder.Any, options?: { onRowsChanged?: (rowsChanged: number) => void }): void
+
+  select<T>(queryStr: string, bindValues?: PreparedBindValues | undefined): ReadonlyArray<T>
+  select<T>(queryBuilder: QueryBuilder<T, any, any>): T
+
+  export(): Uint8Array
+  import: (data: Uint8Array | SqliteDb<TReq>) => void
+  close(): void
+  destroy(): void
+  session(): SqliteDbSession
+  makeChangeset: (data: Uint8Array) => SqliteDbChangeset
+}
+
+export type SqliteDebugInfo = { head: EventSequenceNumber.EventSequenceNumber }
+
+// TODO refactor this helper type. It's quite cumbersome to use and should be revisited.
+export type MakeSqliteDb<
+  TReq = { dbPointer: number; persistenceInfo: PersistenceInfo },
+  TInput_ extends { _tag: string } = { _tag: string },
+  TMetadata_ extends TReq = TReq,
+  R = never,
+> = <
+  TInput extends TInput_,
+  TMetadata extends TMetadata_ & { _tag: TInput['_tag'] } = TMetadata_ & { _tag: TInput['_tag'] },
+>(
+  input: TInput,
+) => Effect.Effect<SqliteDb<TReq, Extract<TMetadata, { _tag: TInput['_tag'] }>>, SqliteError | UnexpectedError, R>
+
+export interface PreparedStatement {
+  execute(bindValues: PreparedBindValues | undefined, options?: { onRowsChanged?: (rowsChanged: number) => void }): void
+  select<T>(bindValues: PreparedBindValues | undefined): ReadonlyArray<T>
+  finalize(): void
+  sql: string
+}
+
+export type SqliteDbSession = {
+  changeset: () => Uint8Array | undefined
+  finish: () => void
+}
+
+export type SqliteDbChangeset = {
+  // TODO combining changesets (requires changes in the SQLite WASM binding)
+  invert: () => SqliteDbChangeset
+  apply: () => void
+}
+
+export const PersistenceInfo = Schema.Struct(
+  {
+    fileName: Schema.String,
+  },
+  { key: Schema.String, value: Schema.Any },
+).annotations({ title: 'LiveStore.PersistenceInfo' })
+
+export type PersistenceInfo<With extends {} = {}> = typeof PersistenceInfo.Type & With