[experiment] Online Optimism

docs/reference/powersync-db-collection/classes/PowerSyncTransactor.md

@@ -11,8 +11,17 @@ Applies mutations to the PowerSync database. This method is called automatically
 insert, update, and delete operations. You typically don't need to call this directly unless you
 have special transaction requirements.
 
+By default, transactions resolve in [`TransactorMode.OFFLINE`](../enumerations/TransactorMode.md#offline)
+after the local SQLite write has been observed by TanStack DB. For workflows that
+need server acknowledgement, the experimental
+[`TransactorMode.ONLINE`](../enumerations/TransactorMode.md#online) mode waits
+for PowerSync to upload the mutation to the backend and sync the accepted change
+back down before resolving.
+
 ## Example
 
+Local-first transaction handling.
+
 ```typescript
 // Create a collection
 const collection = createCollection(
@@ -39,6 +48,33 @@ await addTx.commit()
 await addTx.isPersisted.promise
 ```
 
+## Example
+
+Experimental: wait for backend acknowledgement before resolving the transaction.
+
+```typescript
+const onlineTransactor = new PowerSyncTransactor({
+  database: db,
+  mode: TransactorMode.ONLINE,
+  timeoutMs: 30_000,
+})
+
+const confirmedTx = createTransaction({
+  autoCommit: false,
+  mutationFn: async ({ transaction }) => {
+    await onlineTransactor.applyTransaction(transaction)
+  },
+})
+
+confirmedTx.mutate(() => {
+  collection.insert({ id: randomUUID(), name: `confirmed-write` })
+})
+
+await confirmedTx.commit()
+await confirmedTx.isPersisted.promise
+// At this point the mutation has been uploaded and synced back down.
+```
+
 ## Param
 
 The transaction containing mutations to apply
@@ -95,6 +131,10 @@ Defined in: [PowerSyncTransactor.ts:66](https://github.com/TanStack/db/blob/main
 
 Persists a Transaction to the PowerSync SQLite database.
 
+The returned promise resolves according to the configured
+[`TransactorMode`](../enumerations/TransactorMode.md): local observation in
+offline mode, or backend upload plus sync-down observation in online mode.
+
 #### Parameters
 
 ##### transaction

docs/reference/powersync-db-collection/enumerations/TransactorMode.md

@@ -0,0 +1,48 @@
+---
+id: TransactorMode
+title: TransactorMode
+---
+
+# Enumeration: TransactorMode
+
+Controls when a [`PowerSyncTransactor`](../classes/PowerSyncTransactor.md)
+considers a TanStack DB mutation transaction complete.
+
+## Enumeration Members
+
+### OFFLINE
+
+```ts
+OFFLINE = "offline"
+```
+
+Resolve mutation transactions once the local PowerSync SQLite write has been
+observed by TanStack DB.
+
+This is the default mode. It gives fast local-first behavior: mutations are
+persisted locally, PowerSync can upload them later, and TanStack DB state is
+already consistent with the local database when the transaction resolves.
+
+***
+
+### ONLINE
+
+```ts
+ONLINE = "online"
+```
+
+> Experimental: This mode depends on PowerSync checkpoint internals and may
+> change as the PowerSync SDK exposes more direct backend-acknowledgement hooks.
+
+Resolve mutation transactions only after PowerSync has uploaded the local write
+to the backend and the resulting change has been synced back down and observed
+by TanStack DB.
+
+Use this mode when callers need backend confirmation before treating a mutation
+as complete, such as when showing committed server state, navigating away from a
+critical workflow, or coordinating with systems that only react after the backend
+has accepted the write.
+
+Because this waits for a full upload and sync-down cycle, transactions can take
+longer to resolve and may remain pending while the client is offline or the
+PowerSync connection is unable to complete a checkpoint.

docs/reference/powersync-db-collection/index.md

@@ -9,6 +9,10 @@ title: "@tanstack/powersync-db-collection"
 
 - [PowerSyncTransactor](classes/PowerSyncTransactor.md)
 
+## Enumerations
+
+- [TransactorMode](enumerations/TransactorMode.md)
+
 ## Type Aliases
 
 - [BasePowerSyncCollectionConfig](type-aliases/BasePowerSyncCollectionConfig.md)
@@ -22,6 +26,8 @@ title: "@tanstack/powersync-db-collection"
 - [PowerSyncCollectionMeta](type-aliases/PowerSyncCollectionMeta.md)
 - [PowerSyncCollectionUtils](type-aliases/PowerSyncCollectionUtils.md)
 - [SerializerConfig](type-aliases/SerializerConfig.md)
+- [OfflineTransactorOptions](type-aliases/OfflineTransactorOptions.md)
+- [OnlineTransactorOptions](type-aliases/OnlineTransactorOptions.md)
 - [TransactorOptions](type-aliases/TransactorOptions.md)
 
 ## Variables

docs/reference/powersync-db-collection/type-aliases/OfflineTransactorOptions.md

@@ -0,0 +1,34 @@
+---
+id: OfflineTransactorOptions
+title: OfflineTransactorOptions
+---
+
+# Type Alias: OfflineTransactorOptions
+
+```ts
+type OfflineTransactorOptions = BaseTransactorOptions & object;
+```
+
+Options for local-first transaction handling.
+
+## Properties
+
+### database
+
+```ts
+database: AbstractPowerSyncDatabase;
+```
+
+The PowerSync database that mutations will be written to.
+
+***
+
+### mode?
+
+```ts
+optional mode: TransactorMode.OFFLINE;
+```
+
+Resolve after the local write has been observed by TanStack DB.
+
+This is the default when `mode` is omitted.

docs/reference/powersync-db-collection/type-aliases/OnlineTransactorOptions.md

@@ -0,0 +1,70 @@
+---
+id: OnlineTransactorOptions
+title: OnlineTransactorOptions
+---
+
+# Type Alias: OnlineTransactorOptions
+
+```ts
+type OnlineTransactorOptions = BaseTransactorOptions & object;
+```
+
+Options for backend-confirmed transaction handling.
+
+> Experimental: Online transaction completion depends on PowerSync checkpoint
+> internals and may change as the PowerSync SDK exposes more direct
+> backend-acknowledgement hooks.
+
+## Properties
+
+### database
+
+```ts
+database: AbstractPowerSyncDatabase;
+```
+
+The PowerSync database that mutations will be written to.
+
+***
+
+### mode
+
+```ts
+mode: TransactorMode.ONLINE;
+```
+
+Resolve after the local write has been uploaded to the backend, synced back down,
+and observed by TanStack DB.
+
+> Experimental: This mode depends on PowerSync checkpoint internals and may
+> change as the PowerSync SDK exposes more direct backend-acknowledgement hooks.
+
+***
+
+### timeoutMs?
+
+```ts
+optional timeoutMs: number;
+```
+
+Maximum total time to wait for the backend checkpoint and synced-down diff
+records.
+
+If the timeout is reached before the write has completed the upload and sync-down
+cycle, the mutation transaction rejects.
+
+> Experimental: This option only applies to the experimental online transaction
+> mode.
+
+***
+
+### abortSignal?
+
+```ts
+optional abortSignal: AbortSignal;
+```
+
+Optional signal for cancelling the online wait.
+
+> Experimental: This option only applies to the experimental online transaction
+> mode.

docs/reference/powersync-db-collection/type-aliases/TransactorOptions.md

@@ -6,17 +6,30 @@ title: TransactorOptions
 # Type Alias: TransactorOptions
 
 ```ts
-type TransactorOptions = object;
+type TransactorOptions = OfflineTransactorOptions | OnlineTransactorOptions;
 ```
 
-Defined in: [PowerSyncTransactor.ts:15](https://github.com/TanStack/db/blob/main/packages/powersync-db-collection/src/PowerSyncTransactor.ts#L15)
+Configuration for a [`PowerSyncTransactor`](../classes/PowerSyncTransactor.md).
 
-## Properties
+`mode` is the discriminator:
 
-### database
+- omit `mode` or use [`TransactorMode.OFFLINE`](../enumerations/TransactorMode.md#offline) for fast local-first writes
+- use [`TransactorMode.ONLINE`](../enumerations/TransactorMode.md#online) to unlock backend-confirmed wait options
 
-```ts
-database: AbstractPowerSyncDatabase;
+## Example
+
+```typescript
+new PowerSyncTransactor({
+  database: db,
+})
 ```
 
-Defined in: [PowerSyncTransactor.ts:16](https://github.com/TanStack/db/blob/main/packages/powersync-db-collection/src/PowerSyncTransactor.ts#L16)
+## Example
+
+```typescript
+new PowerSyncTransactor({
+  database: db,
+  mode: TransactorMode.ONLINE,
+  timeoutMs: 30_000,
+})
+```

packages/db/src/index.ts

@@ -29,4 +29,5 @@ export * from './query/expression-helpers.js'
 // Re-export some stuff explicitly to ensure the type & value is exported
 export type { Collection } from './collection/index.js'
 export { IR }
+export { or } from './query/builder/functions.js'
 export { operators, type OperatorName } from './query/builder/functions.js'

packages/powersync-db-collection/package.json

@@ -62,8 +62,8 @@
     "@powersync/common": "^1.41.0"
   },
   "devDependencies": {
-    "@powersync/common": "0.0.0-dev-20260309101613",
-    "@powersync/node": "0.0.0-dev-20260309101613",
+    "@powersync/common": "^1.53.2",
+    "@powersync/node": "^0.18.7",
     "@types/debug": "^4.1.12",
     "@vitest/coverage-istanbul": "^3.2.4"
   }