@livestore/common 0.0.0-snapshot-83c6b3d6e39244b59235009057fd5c48f6c3103f → 0.0.0-snapshot-2b8a9de3ec1a701aca891ebc2c98eb328274ae9e

package/src/leader-thread/LeaderSyncProcessor.ts

@@ -74,6 +74,7 @@ export const makeLeaderSyncProcessor = ({
   dbMutationLog,
   clientId,
   initialBlockingSyncContext,
+  onError,
 }: {
   schema: LiveStoreSchema
   /** Only used to know whether we can safely query dbMutationLog during setup execution */
@@ -81,13 +82,14 @@ export const makeLeaderSyncProcessor = ({
   dbMutationLog: SqliteDb
   clientId: string
   initialBlockingSyncContext: InitialBlockingSyncContext
+  onError: 'shutdown' | 'ignore'
 }): Effect.Effect<LeaderSyncProcessor, UnexpectedError, Scope.Scope> =>
   Effect.gen(function* () {
     const syncBackendQueue = yield* BucketQueue.make<MutationEvent.EncodedWithMeta>()
 
     const syncStateSref = yield* SubscriptionRef.make<SyncState.SyncState | undefined>(undefined)
 
-    const isLocalEvent = (mutationEventEncoded: MutationEvent.EncodedWithMeta) => {
+    const isClientEvent = (mutationEventEncoded: MutationEvent.EncodedWithMeta) => {
       const mutationDef = getMutationDef(schema, mutationEventEncoded.mutation)
       return mutationDef.options.clientOnly
     }
@@ -234,8 +236,10 @@ export const makeLeaderSyncProcessor = ({
 
         const shutdownOnError = (cause: unknown) =>
           Effect.gen(function* () {
-            yield* shutdownChannel.send(UnexpectedError.make({ cause }))
-            yield* Effect.die(cause)
+            if (onError === 'shutdown') {
+              yield* shutdownChannel.send(UnexpectedError.make({ cause }))
+              yield* Effect.die(cause)
+            }
           })
 
         yield* backgroundApplyLocalPushes({
@@ -245,7 +249,7 @@ export const makeLeaderSyncProcessor = ({
           syncStateSref,
           syncBackendQueue,
           schema,
-          isLocalEvent,
+          isClientEvent,
           otelSpan,
           currentLocalPushGenerationRef,
         }).pipe(Effect.tapCauseLogPretty, Effect.catchAllCause(shutdownOnError), Effect.forkScoped)
@@ -265,7 +269,7 @@ export const makeLeaderSyncProcessor = ({
         yield* backgroundBackendPulling({
           dbReady,
           initialBackendHead,
-          isLocalEvent,
+          isClientEvent,
           restartBackendPushing: (filteredRebasedPending) =>
             Effect.gen(function* () {
               // Stop current pushing fiber
@@ -319,7 +323,7 @@ const backgroundApplyLocalPushes = ({
   syncStateSref,
   syncBackendQueue,
   schema,
-  isLocalEvent,
+  isClientEvent,
   otelSpan,
   currentLocalPushGenerationRef,
 }: {
@@ -329,7 +333,7 @@ const backgroundApplyLocalPushes = ({
   syncStateSref: SubscriptionRef.SubscriptionRef<SyncState.SyncState | undefined>
   syncBackendQueue: BucketQueue.BucketQueue<MutationEvent.EncodedWithMeta>
   schema: LiveStoreSchema
-  isLocalEvent: (mutationEventEncoded: MutationEvent.EncodedWithMeta) => boolean
+  isClientEvent: (mutationEventEncoded: MutationEvent.EncodedWithMeta) => boolean
   otelSpan: otel.Span | undefined
   currentLocalPushGenerationRef: { current: number }
 }) =>
@@ -366,20 +370,20 @@ const backgroundApplyLocalPushes = ({
       const syncState = yield* syncStateSref
       if (syncState === undefined) return shouldNeverHappen('Not initialized')
 
-      const updateResult = SyncState.updateSyncState({
+      const mergeResult = SyncState.merge({
         syncState,
         payload: { _tag: 'local-push', newEvents },
-        isLocalEvent,
+        isClientEvent,
         isEqualEvent: MutationEvent.isEqualEncoded,
       })
 
-      switch (updateResult._tag) {
+      switch (mergeResult._tag) {
         case 'unexpected-error': {
           otelSpan?.addEvent('local-push:unexpected-error', {
             batchSize: newEvents.length,
             newEvents: TRACE_VERBOSE ? JSON.stringify(newEvents) : undefined,
           })
-          return yield* Effect.fail(updateResult.cause)
+          return yield* Effect.fail(mergeResult.cause)
         }
         case 'rebase': {
           return shouldNeverHappen('The leader thread should never have to rebase due to a local push')
@@ -387,7 +391,7 @@ const backgroundApplyLocalPushes = ({
         case 'reject': {
           otelSpan?.addEvent('local-push:reject', {
             batchSize: newEvents.length,
-            updateResult: TRACE_VERBOSE ? JSON.stringify(updateResult) : undefined,
+            mergeResult: TRACE_VERBOSE ? JSON.stringify(mergeResult) : undefined,
           })
 
           /*
@@ -421,7 +425,7 @@ const backgroundApplyLocalPushes = ({
             Deferred.fail(
               deferred,
               LeaderAheadError.make({
-                minimumExpectedId: updateResult.expectedMinimumId,
+                minimumExpectedId: mergeResult.expectedMinimumId,
                 providedId,
                 // nextGeneration,
               }),
@@ -439,28 +443,28 @@ const backgroundApplyLocalPushes = ({
           break
         }
         default: {
-          casesHandled(updateResult)
+          casesHandled(mergeResult)
         }
       }
 
-      yield* SubscriptionRef.set(syncStateSref, updateResult.newSyncState)
+      yield* SubscriptionRef.set(syncStateSref, mergeResult.newSyncState)
 
       if (clientId === 'client-b') {
         // yield* Effect.log('offer upstream-advance due to local-push')
         // debugger
       }
       yield* connectedClientSessionPullQueues.offer({
-        payload: { _tag: 'upstream-advance', newEvents: updateResult.newEvents },
+        payload: { _tag: 'upstream-advance', newEvents: mergeResult.newEvents },
         remaining: 0,
       })
 
       otelSpan?.addEvent('local-push', {
         batchSize: newEvents.length,
-        updateResult: TRACE_VERBOSE ? JSON.stringify(updateResult) : undefined,
+        mergeResult: TRACE_VERBOSE ? JSON.stringify(mergeResult) : undefined,
       })
 
       // Don't sync clientOnly mutations
-      const filteredBatch = updateResult.newEvents.filter((mutationEventEncoded) => {
+      const filteredBatch = mergeResult.newEvents.filter((mutationEventEncoded) => {
         const mutationDef = getMutationDef(schema, mutationEventEncoded.mutation)
         return mutationDef.options.clientOnly === false
       })
@@ -527,7 +531,7 @@ const makeApplyMutationItems: Effect.Effect<ApplyMutationItems, UnexpectedError,
 const backgroundBackendPulling = ({
   dbReady,
   initialBackendHead,
-  isLocalEvent,
+  isClientEvent,
   restartBackendPushing,
   otelSpan,
   syncStateSref,
@@ -538,7 +542,7 @@ const backgroundBackendPulling = ({
 }: {
   dbReady: Deferred.Deferred<void>
   initialBackendHead: EventId.GlobalEventId
-  isLocalEvent: (mutationEventEncoded: MutationEvent.EncodedWithMeta) => boolean
+  isClientEvent: (mutationEventEncoded: MutationEvent.EncodedWithMeta) => boolean
   restartBackendPushing: (
     filteredRebasedPending: ReadonlyArray<MutationEvent.EncodedWithMeta>,
   ) => Effect.Effect<void, UnexpectedError, LeaderThreadCtx | HttpClient.HttpClient>
@@ -584,51 +588,51 @@ const backgroundBackendPulling = ({
 
         const trimRollbackUntil = newEvents.at(-1)!.id
 
-        const updateResult = SyncState.updateSyncState({
+        const mergeResult = SyncState.merge({
           syncState,
           payload: { _tag: 'upstream-advance', newEvents, trimRollbackUntil },
-          isLocalEvent,
+          isClientEvent,
           isEqualEvent: MutationEvent.isEqualEncoded,
-          ignoreLocalEvents: true,
+          ignoreClientEvents: true,
         })
 
-        if (updateResult._tag === 'reject') {
+        if (mergeResult._tag === 'reject') {
           return shouldNeverHappen('The leader thread should never reject upstream advances')
-        } else if (updateResult._tag === 'unexpected-error') {
+        } else if (mergeResult._tag === 'unexpected-error') {
           otelSpan?.addEvent('backend-pull:unexpected-error', {
             newEventsCount: newEvents.length,
             newEvents: TRACE_VERBOSE ? JSON.stringify(newEvents) : undefined,
           })
-          return yield* Effect.fail(updateResult.cause)
+          return yield* Effect.fail(mergeResult.cause)
         }
 
         const newBackendHead = newEvents.at(-1)!.id
 
         updateBackendHead(dbMutationLog, newBackendHead)
 
-        if (updateResult._tag === 'rebase') {
+        if (mergeResult._tag === 'rebase') {
           otelSpan?.addEvent('backend-pull:rebase', {
             newEventsCount: newEvents.length,
             newEvents: TRACE_VERBOSE ? JSON.stringify(newEvents) : undefined,
-            rollbackCount: updateResult.eventsToRollback.length,
-            updateResult: TRACE_VERBOSE ? JSON.stringify(updateResult) : undefined,
+            rollbackCount: mergeResult.eventsToRollback.length,
+            mergeResult: TRACE_VERBOSE ? JSON.stringify(mergeResult) : undefined,
           })
 
-          const filteredRebasedPending = updateResult.newSyncState.pending.filter((mutationEvent) => {
+          const filteredRebasedPending = mergeResult.newSyncState.pending.filter((mutationEvent) => {
             const mutationDef = getMutationDef(schema, mutationEvent.mutation)
             return mutationDef.options.clientOnly === false
           })
           yield* restartBackendPushing(filteredRebasedPending)
 
-          if (updateResult.eventsToRollback.length > 0) {
-            yield* rollback({ db, dbMutationLog, eventIdsToRollback: updateResult.eventsToRollback.map((_) => _.id) })
+          if (mergeResult.eventsToRollback.length > 0) {
+            yield* rollback({ db, dbMutationLog, eventIdsToRollback: mergeResult.eventsToRollback.map((_) => _.id) })
           }
 
           yield* connectedClientSessionPullQueues.offer({
             payload: {
               _tag: 'upstream-rebase',
-              newEvents: updateResult.newEvents,
-              rollbackUntil: updateResult.eventsToRollback.at(0)!.id,
+              newEvents: mergeResult.newEvents,
+              rollbackUntil: mergeResult.eventsToRollback.at(0)!.id,
               trimRollbackUntil,
             },
             remaining,
@@ -636,23 +640,23 @@ const backgroundBackendPulling = ({
         } else {
           otelSpan?.addEvent('backend-pull:advance', {
             newEventsCount: newEvents.length,
-            updateResult: TRACE_VERBOSE ? JSON.stringify(updateResult) : undefined,
+            mergeResult: TRACE_VERBOSE ? JSON.stringify(mergeResult) : undefined,
           })
 
           if (clientId === 'client-b') {
             // yield* Effect.log('offer upstream-advance due to pull')
           }
           yield* connectedClientSessionPullQueues.offer({
-            payload: { _tag: 'upstream-advance', newEvents: updateResult.newEvents, trimRollbackUntil },
+            payload: { _tag: 'upstream-advance', newEvents: mergeResult.newEvents, trimRollbackUntil },
             remaining,
           })
         }
 
         trimChangesetRows(db, newBackendHead)
 
-        yield* applyMutationItems({ batchItems: updateResult.newEvents, deferreds: undefined })
+        yield* applyMutationItems({ batchItems: mergeResult.newEvents, deferreds: undefined })
 
-        yield* SubscriptionRef.set(syncStateSref, updateResult.newSyncState)
+        yield* SubscriptionRef.set(syncStateSref, mergeResult.newSyncState)
 
         if (remaining === 0) {
           // Allow local pushes to be processed again
@@ -707,7 +711,9 @@ const rollback = ({
         sql`SELECT * FROM ${SESSION_CHANGESET_META_TABLE} WHERE (idGlobal, idClient) IN (${eventIdsToRollback.map((id) => `(${id.global}, ${id.client})`).join(', ')})`,
       )
       .map((_) => ({ id: { global: _.idGlobal, client: _.idClient }, changeset: _.changeset, debug: _.debug }))
-      .toSorted((a, b) => EventId.compare(a.id, b.id))
+      .sort((a, b) => EventId.compare(a.id, b.id))
+    // TODO bring back `.toSorted` once Expo supports it
+    // .toSorted((a, b) => EventId.compare(a.id, b.id))
 
     // Apply changesets in reverse order
     for (let i = rollbackEvents.length - 1; i >= 0; i--) {

package/src/leader-thread/leader-worker-devtools.ts

@@ -278,7 +278,7 @@ const listenToDevtools = ({
             case 'LSD.Leader.SyncingInfoReq': {
               const syncingInfo = Devtools.Leader.SyncingInfo.make({
                 enabled: syncBackend !== undefined,
-                metadata: {},
+                metadata: syncBackend?.metadata ?? {},
               })
 
               yield* sendMessage(Devtools.Leader.SyncingInfoRes.make({ syncingInfo, ...reqPayload }))

package/src/leader-thread/make-leader-thread-layer.ts

@@ -71,6 +71,7 @@ export const makeLeaderThreadLayer = ({
       dbMutationLog,
       initialBlockingSyncContext,
       clientId,
+      onError: syncOptions?.onSyncError ?? 'ignore',
     })
 
     const extraIncomingMessagesQueue = yield* Queue.unbounded<Devtools.Leader.MessageToApp>().pipe(

package/src/leader-thread/mutationlog.ts

@@ -7,6 +7,7 @@ import { MUTATION_LOG_META_TABLE, mutationLogMetaTable, SYNC_STATUS_TABLE } from
 import { prepareBindValues, sql } from '../util.js'
 import { LeaderThreadCtx } from './types.js'
 
+/** Exclusive of the "since event" */
 export const getMutationEventsSince = (
   since: EventId.EventId,
 ): Effect.Effect<ReadonlyArray<MutationEvent.AnyEncoded>, never, LeaderThreadCtx> =>

package/src/mutation.ts

@@ -1,8 +1,11 @@
 import { Schema } from '@livestore/utils/effect'
 
 import { SessionIdSymbol } from './adapter-types.js'
+import type { QueryBuilder } from './query-builder/api.js'
+import { isQueryBuilder } from './query-builder/api.js'
 import type * as MutationEvent from './schema/MutationEvent.js'
-import type { MutationDef } from './schema/mutations.js'
+import type { MutationDef, MutationHandlerResult } from './schema/mutations.js'
+import type { BindValues } from './sql-queries/sql-queries.js'
 import type { PreparedBindValues } from './util.js'
 import { prepareBindValues } from './util.js'
 
@@ -34,8 +37,22 @@ export const getExecArgsFromMutation = ({
     case 'function': {
       const mutationArgsDecoded =
         mutationEvent.decoded?.args ?? Schema.decodeUnknownSync(mutationDef.schema)(mutationEvent.encoded!.args)
-      const res = mutationDef.sql(mutationArgsDecoded)
-      statementRes = Array.isArray(res) ? res : [res]
+
+      const res = mutationDef.sql(mutationArgsDecoded, {
+        clientOnly: mutationDef.options.clientOnly,
+        // TODO properly implement this
+        currentFacts: new Map(),
+      })
+
+      statementRes = (Array.isArray(res) ? res : [res]).map((_: QueryBuilder.Any | MutationHandlerResult) => {
+        if (isQueryBuilder(_)) {
+          const { query, bindValues } = _.asSql()
+          return { sql: query, bindValues: bindValues as BindValues }
+        }
+
+        return _
+      })
+
       break
     }
     case 'string': {

package/src/query-builder/api.ts

@@ -7,10 +7,16 @@ import type { SqliteDsl } from '../schema/db-schema/mod.js'
 import type { DbSchema } from '../schema/mod.js'
 import type { SqlValue } from '../util.js'
 
-export type QueryBuilderAst = QueryBuilderAst.SelectQuery | QueryBuilderAst.CountQuery | QueryBuilderAst.RowQuery
+export type QueryBuilderAst =
+  | QueryBuilderAst.SelectQuery
+  | QueryBuilderAst.CountQuery
+  | QueryBuilderAst.RowQuery
+  | QueryBuilderAst.InsertQuery
+  | QueryBuilderAst.UpdateQuery
+  | QueryBuilderAst.DeleteQuery
 
 export namespace QueryBuilderAst {
-  export type SelectQuery = {
+  export interface SelectQuery {
     readonly _tag: 'SelectQuery'
     readonly columns: string[]
     readonly pickFirst: false | { fallback: () => any }
@@ -25,27 +31,67 @@ export namespace QueryBuilderAst {
     readonly resultSchemaSingle: Schema.Schema<any>
   }
 
-  export type CountQuery = {
+  export interface CountQuery {
     readonly _tag: 'CountQuery'
     readonly tableDef: DbSchema.TableDefBase
     readonly where: ReadonlyArray<QueryBuilderAst.Where>
     readonly resultSchema: Schema.Schema<number, ReadonlyArray<{ count: number }>>
   }
 
-  export type RowQuery = {
+  export interface RowQuery {
     readonly _tag: 'RowQuery'
     readonly tableDef: DbSchema.TableDefBase
     readonly id: string | SessionIdSymbol | number
     readonly insertValues: Record<string, unknown>
   }
 
-  export type Where = {
+  export interface InsertQuery {
+    readonly _tag: 'InsertQuery'
+    readonly tableDef: DbSchema.TableDefBase
+    readonly values: Record<string, unknown>
+    readonly onConflict: OnConflict | undefined
+    readonly returning: string[] | undefined
+    readonly resultSchema: Schema.Schema<any>
+  }
+
+  export interface OnConflict {
+    /** Conflicting column name */
+    readonly target: string
+    readonly action:
+      | { readonly _tag: 'ignore' }
+      | { readonly _tag: 'replace' }
+      | {
+          readonly _tag: 'update'
+          readonly update: Record<string, unknown>
+        }
+  }
+
+  export interface UpdateQuery {
+    readonly _tag: 'UpdateQuery'
+    readonly tableDef: DbSchema.TableDefBase
+    readonly values: Record<string, unknown>
+    readonly where: ReadonlyArray<QueryBuilderAst.Where>
+    readonly returning: string[] | undefined
+    readonly resultSchema: Schema.Schema<any>
+  }
+
+  export interface DeleteQuery {
+    readonly _tag: 'DeleteQuery'
+    readonly tableDef: DbSchema.TableDefBase
+    readonly where: ReadonlyArray<QueryBuilderAst.Where>
+    readonly returning: string[] | undefined
+    readonly resultSchema: Schema.Schema<any>
+  }
+
+  export type WriteQuery = InsertQuery | UpdateQuery | DeleteQuery
+
+  export interface Where {
     readonly col: string
     readonly op: QueryBuilder.WhereOps
     readonly value: unknown
   }
 
-  export type OrderBy = {
+  export interface OrderBy {
     readonly col: string
     readonly direction: 'asc' | 'desc'
   }
@@ -86,7 +132,20 @@ export namespace QueryBuilder {
     export type MultiValue = In
   }
 
-  export type ApiFeature = 'select' | 'where' | 'count' | 'orderBy' | 'offset' | 'limit' | 'first' | 'row'
+  export type ApiFeature =
+    | 'select'
+    | 'where'
+    | 'count'
+    | 'orderBy'
+    | 'offset'
+    | 'limit'
+    | 'first'
+    | 'row'
+    | 'insert'
+    | 'update'
+    | 'delete'
+    | 'returning'
+    | 'onConflict'
 
   export type WhereParams<TTableDef extends DbSchema.TableDefBase> = Partial<{
     [K in keyof TTableDef['sqliteDef']['columns']]:
@@ -130,7 +189,7 @@ export namespace QueryBuilder {
               readonly [K in TColumn]: TTableDef['sqliteDef']['columns'][K]['schema']['Type']
             }>,
         TTableDef,
-        TWithout | 'row' | 'select',
+        TWithout | 'row' | 'select' | 'returning' | 'onConflict',
         TQueryInfo
       >
       <TColumns extends keyof TTableDef['sqliteDef']['columns'] & string>(
@@ -142,7 +201,7 @@ export namespace QueryBuilder {
           readonly [K in TColumns]: TTableDef['sqliteDef']['columns'][K]['schema']['Type']
         }>,
         TTableDef,
-        TWithout | 'row' | 'select' | 'count',
+        TWithout | 'row' | 'select' | 'count' | 'returning' | 'onConflict',
         TQueryInfo
       >
     }
@@ -187,7 +246,7 @@ export namespace QueryBuilder {
     readonly count: () => QueryBuilder<
       number,
       TTableDef,
-      TWithout | 'row' | 'count' | 'select' | 'orderBy' | 'first' | 'offset' | 'limit',
+      TWithout | 'row' | 'count' | 'select' | 'orderBy' | 'first' | 'offset' | 'limit' | 'returning' | 'onConflict',
       TQueryInfo
     >
 
@@ -201,10 +260,10 @@ export namespace QueryBuilder {
       <TColName extends keyof TTableDef['sqliteDef']['columns'] & string>(
         col: TColName,
         direction: 'asc' | 'desc',
-      ): QueryBuilder<TResult, TTableDef, TWithout, TQueryInfo>
+      ): QueryBuilder<TResult, TTableDef, TWithout | 'returning' | 'onConflict', TQueryInfo>
       <TParams extends QueryBuilder.OrderByParams<TTableDef>>(
         params: TParams,
-      ): QueryBuilder<TResult, TTableDef, TWithout, TQueryInfo>
+      ): QueryBuilder<TResult, TTableDef, TWithout | 'returning' | 'onConflict', TQueryInfo>
     }
 
     /**
@@ -215,7 +274,12 @@ export namespace QueryBuilder {
      */
     readonly offset: (
       offset: number,
-    ) => QueryBuilder<TResult, TTableDef, TWithout | 'row' | 'offset' | 'orderBy', TQueryInfo>
+    ) => QueryBuilder<
+      TResult,
+      TTableDef,
+      TWithout | 'row' | 'offset' | 'orderBy' | 'returning' | 'onConflict',
+      TQueryInfo
+    >
 
     /**
      * Example:
@@ -225,7 +289,12 @@ export namespace QueryBuilder {
      */
     readonly limit: (
       limit: number,
-    ) => QueryBuilder<TResult, TTableDef, TWithout | 'row' | 'limit' | 'offset' | 'first' | 'orderBy', TQueryInfo>
+    ) => QueryBuilder<
+      TResult,
+      TTableDef,
+      TWithout | 'row' | 'limit' | 'offset' | 'first' | 'orderBy' | 'returning' | 'onConflict',
+      TQueryInfo
+    >
 
     /**
      * Example:
@@ -238,7 +307,7 @@ export namespace QueryBuilder {
     }) => QueryBuilder<
       TFallback | GetSingle<TResult>,
       TTableDef,
-      TWithout | 'row' | 'first' | 'orderBy' | 'select' | 'limit' | 'offset' | 'where',
+      TWithout | 'row' | 'first' | 'orderBy' | 'select' | 'limit' | 'offset' | 'where' | 'returning' | 'onConflict',
       TQueryInfo
     >
 
@@ -258,6 +327,114 @@ export namespace QueryBuilder {
               id: string | SessionIdSymbol | number,
               opts: TOptions,
             ) => QueryBuilder<RowQuery.Result<TTableDef>, TTableDef, QueryBuilder.ApiFeature, QueryInfo.Row>
+
+    /**
+     * Insert a new row into the table
+     *
+     * Example:
+     * ```ts
+     * db.todos.insert({ id: '123', text: 'Buy milk', status: 'active' })
+     * ```
+     */
+    readonly insert: (
+      values: TTableDef['insertSchema']['Type'],
+    ) => QueryBuilder<
+      TResult,
+      TTableDef,
+      TWithout | 'row' | 'select' | 'count' | 'orderBy' | 'first' | 'offset' | 'limit' | 'where',
+      QueryInfo.Write
+    >
+
+    /**
+     * Example: If the row already exists, it will be ignored.
+     * ```ts
+     * db.todos.insert({ id: '123', text: 'Buy milk', status: 'active' }).onConflict('id', 'ignore')
+     * ```
+     *
+     * Example: If the row already exists, it will be replaced.
+     * ```ts
+     * db.todos.insert({ id: '123', text: 'Buy milk', status: 'active' }).onConflict('id', 'replace')
+     * ```
+     *
+     * Example: If the row already exists, it will be updated.
+     * ```ts
+     * db.todos.insert({ id: '123', text: 'Buy milk', status: 'active' }).onConflict('id', 'update', { text: 'Buy soy milk' })
+     * ```
+     *
+     * NOTE This API doesn't yet support composite primary keys.
+     */
+    readonly onConflict: {
+      (
+        target: string,
+        action: 'ignore' | 'replace',
+      ): QueryBuilder<
+        TResult,
+        TTableDef,
+        TWithout | 'row' | 'select' | 'count' | 'orderBy' | 'first' | 'offset' | 'limit' | 'where',
+        TQueryInfo
+      >
+      <TTarget extends keyof TTableDef['sqliteDef']['columns'] & string>(
+        target: TTarget,
+        action: 'update',
+        updateValues: Partial<TTableDef['schema']['Type']>,
+      ): QueryBuilder<
+        TResult,
+        TTableDef,
+        TWithout | 'row' | 'select' | 'count' | 'orderBy' | 'first' | 'offset' | 'limit' | 'where',
+        TQueryInfo
+      >
+    }
+
+    /**
+     * Similar to the `.select` API but for write queries (insert, update, delete).
+     *
+     * Example:
+     * ```ts
+     * db.todos.insert({ id: '123', text: 'Buy milk', status: 'active' }).returning('id')
+     * ```
+     */
+    readonly returning: <TColumns extends keyof TTableDef['sqliteDef']['columns'] & string>(
+      ...columns: TColumns[]
+    ) => QueryBuilder<
+      ReadonlyArray<{
+        readonly [K in TColumns]: TTableDef['sqliteDef']['columns'][K]['schema']['Type']
+      }>,
+      TTableDef
+    >
+
+    /**
+     * Update rows in the table that match the where clause
+     *
+     * Example:
+     * ```ts
+     * db.todos.update({ status: 'completed' }).where({ id: '123' })
+     * ```
+     */
+    readonly update: (
+      values: Partial<TTableDef['schema']['Type']>,
+    ) => QueryBuilder<
+      TResult,
+      TTableDef,
+      TWithout | 'row' | 'select' | 'count' | 'orderBy' | 'first' | 'offset' | 'limit' | 'onConflict',
+      QueryInfo.Write
+    >
+
+    /**
+     * Delete rows from the table that match the where clause
+     *
+     * Example:
+     * ```ts
+     * db.todos.delete().where({ status: 'completed' })
+     * ```
+     *
+     * Note that it's generally recommended to do soft-deletes for synced apps.
+     */
+    readonly delete: () => QueryBuilder<
+      TResult,
+      TTableDef,
+      TWithout | 'row' | 'select' | 'count' | 'orderBy' | 'first' | 'offset' | 'limit' | 'onConflict',
+      QueryInfo.Write
+    >
   }
 }