Merge branch 'main' into fix/no-flush-on-init

Author: Chriztiaan

.changeset/clean-query-ownership.md

@@ -0,0 +1,5 @@
+---
+'@tanstack/powersync-db-collection': patch
+---
+
+Fix: applyTransaction hangs forever when a transaction mixes delete+insert on one collection for a same-millisecond tie.

.changeset/hot-bats-camp.md

@@ -241,6 +241,57 @@ Some TanStack Query fields are owned or reinterpreted by Query Collection and ar
 
 `placeholderData` is intentionally unsupported. TanStack Query treats placeholder data as observer-local presentation state rather than cached Query data. Materializing it would expose temporary UI data as collection-wide normalized rows. Render placeholders in the consuming UI instead.
 
+### Request Cancellation with `QueryFunctionContext.signal`
+
+TanStack Query passes an `AbortSignal` to `queryFn` through the query function
+context. Forward `ctx.signal` to `fetch` or another abortable client to make the
+request cancellable:
+
+```typescript
+const todosCollection = createCollection(
+  queryCollectionOptions({
+    queryKey: ["todos"],
+    queryFn: async (ctx) => {
+      const response = await fetch("/api/todos", {
+        signal: ctx.signal,
+      })
+
+      if (!response.ok) {
+        throw new Error("Failed to fetch todos")
+      }
+
+      return response.json() as Promise<Array<Todo>>
+    },
+    queryClient,
+    getKey: (todo) => todo.id,
+  }),
+)
+```
+
+Explicit collection cleanup cancels each exact Query key the collection is
+currently tracking before removing it from the Query cache:
+
+```typescript
+await todosCollection.cleanup()
+```
+
+The underlying request is aborted only when its client consumes `ctx.signal`.
+A client that ignores the signal may continue its request even though the
+collection has been cleaned up.
+
+An unloaded on-demand subset is no longer tracked. A later explicit collection
+cleanup does not revisit its Query key.
+
+Query cache entries are shared within a `QueryClient`. Explicit cleanup can
+affect other consumers using the same exact Query keys.
+
+On-demand subset unloading does not explicitly call
+`queryClient.cancelQueries()`. It removes the subset's Query observer. If this
+was the final observer and the query function consumed `ctx.signal`, TanStack
+Query aborts the request. If the signal was ignored, or another observer still
+uses the same exact Query key, the request may finish and remain cached until
+`gcTime`.
+
 ### Using with `queryOptions(...)`
 
 If your app already uses TanStack Query's `queryOptions` helper (e.g. from `@tanstack/react-query`), you can spread compatible top-level options into `queryCollectionOptions`. Note that `queryFn` must be explicitly provided since query collections require it both in types and at runtime, and Query Collection's `select` option is for row extraction rather than TanStack Query observer-level selection:

.changeset/young-cats-initialize.md

@@ -5,7 +5,7 @@ title: DeleteOperationItemNotFoundError
 
 # Class: DeleteOperationItemNotFoundError
 
-Defined in: [packages/query-db-collection/src/errors.ts:76](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/errors.ts#L76)
+Defined in: [packages/query-db-collection/src/errors.ts:85](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/errors.ts#L85)
 
 ## Extends
 
@@ -19,7 +19,7 @@ Defined in: [packages/query-db-collection/src/errors.ts:76](https://github.com/T
 new DeleteOperationItemNotFoundError(key): DeleteOperationItemNotFoundError;
 ```
 
-Defined in: [packages/query-db-collection/src/errors.ts:77](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/errors.ts#L77)
+Defined in: [packages/query-db-collection/src/errors.ts:86](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/errors.ts#L86)
 
 #### Parameters
 

docs/collections/query-collection.md

@@ -5,7 +5,7 @@ title: DuplicateKeyInBatchError
 
 # Class: DuplicateKeyInBatchError
 
-Defined in: [packages/query-db-collection/src/errors.ts:62](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/errors.ts#L62)
+Defined in: [packages/query-db-collection/src/errors.ts:71](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/errors.ts#L71)
 
 ## Extends
 
@@ -19,7 +19,7 @@ Defined in: [packages/query-db-collection/src/errors.ts:62](https://github.com/T
 new DuplicateKeyInBatchError(key): DuplicateKeyInBatchError;
 ```
 
-Defined in: [packages/query-db-collection/src/errors.ts:63](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/errors.ts#L63)
+Defined in: [packages/query-db-collection/src/errors.ts:72](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/errors.ts#L72)
 
 #### Parameters
 

docs/reference/query-db-collection/classes/DeleteOperationItemNotFoundError.md

@@ -0,0 +1,214 @@
+---
+id: InitialDataInOnDemandModeError
+title: InitialDataInOnDemandModeError
+---
+
+# Class: InitialDataInOnDemandModeError
+
+Defined in: [packages/query-db-collection/src/errors.ts:39](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/errors.ts#L39)
+
+## Extends
+
+- [`QueryCollectionError`](QueryCollectionError.md)
+
+## Constructors
+
+### Constructor
+
+```ts
+new InitialDataInOnDemandModeError(): InitialDataInOnDemandModeError;
+```
+
+Defined in: [packages/query-db-collection/src/errors.ts:40](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/errors.ts#L40)
+
+#### Returns
+
+`InitialDataInOnDemandModeError`
+
+#### Overrides
+
+[`QueryCollectionError`](QueryCollectionError.md).[`constructor`](QueryCollectionError.md#constructor)
+
+## Properties
+
+### cause?
+
+```ts
+optional cause: unknown;
+```
+
+Defined in: node\_modules/.pnpm/typescript@5.9.3/node\_modules/typescript/lib/lib.es2022.error.d.ts:26
+
+#### Inherited from
+
+[`QueryCollectionError`](QueryCollectionError.md).[`cause`](QueryCollectionError.md#cause)
+
+***
+
+### message
+
+```ts
+message: string;
+```
+
+Defined in: node\_modules/.pnpm/typescript@5.9.3/node\_modules/typescript/lib/lib.es5.d.ts:1077
+
+#### Inherited from
+
+[`QueryCollectionError`](QueryCollectionError.md).[`message`](QueryCollectionError.md#message)
+
+***
+
+### name
+
+```ts
+name: string;
+```
+
+Defined in: node\_modules/.pnpm/typescript@5.9.3/node\_modules/typescript/lib/lib.es5.d.ts:1076
+
+#### Inherited from
+
+[`QueryCollectionError`](QueryCollectionError.md).[`name`](QueryCollectionError.md#name)
+
+***
+
+### stack?
+
+```ts
+optional stack: string;
+```
+
+Defined in: node\_modules/.pnpm/typescript@5.9.3/node\_modules/typescript/lib/lib.es5.d.ts:1078
+
+#### Inherited from
+
+[`QueryCollectionError`](QueryCollectionError.md).[`stack`](QueryCollectionError.md#stack)
+
+***
+
+### stackTraceLimit
+
+```ts
+static stackTraceLimit: number;
+```
+
+Defined in: node\_modules/.pnpm/@types+node@25.2.2/node\_modules/@types/node/globals.d.ts:67
+
+The `Error.stackTraceLimit` property specifies the number of stack frames
+collected by a stack trace (whether generated by `new Error().stack` or
+`Error.captureStackTrace(obj)`).
+
+The default value is `10` but may be set to any valid JavaScript number. Changes
+will affect any stack trace captured _after_ the value has been changed.
+
+If set to a non-number value, or set to a negative number, stack traces will
+not capture any frames.
+
+#### Inherited from
+
+[`QueryCollectionError`](QueryCollectionError.md).[`stackTraceLimit`](QueryCollectionError.md#stacktracelimit)
+
+## Methods
+
+### captureStackTrace()
+
+```ts
+static captureStackTrace(targetObject, constructorOpt?): void;
+```
+
+Defined in: node\_modules/.pnpm/@types+node@25.2.2/node\_modules/@types/node/globals.d.ts:51
+
+Creates a `.stack` property on `targetObject`, which when accessed returns
+a string representing the location in the code at which
+`Error.captureStackTrace()` was called.
+
+```js
+const myObject = {};
+Error.captureStackTrace(myObject);
+myObject.stack;  // Similar to `new Error().stack`
+```
+
+The first line of the trace will be prefixed with
+`${myObject.name}: ${myObject.message}`.
+
+The optional `constructorOpt` argument accepts a function. If given, all frames
+above `constructorOpt`, including `constructorOpt`, will be omitted from the
+generated stack trace.
+
+The `constructorOpt` argument is useful for hiding implementation
+details of error generation from the user. For instance:
+
+```js
+function a() {
+  b();
+}
+
+function b() {
+  c();
+}
+
+function c() {
+  // Create an error without stack trace to avoid calculating the stack trace twice.
+  const { stackTraceLimit } = Error;
+  Error.stackTraceLimit = 0;
+  const error = new Error();
+  Error.stackTraceLimit = stackTraceLimit;
+
+  // Capture the stack trace above function b
+  Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace
+  throw error;
+}
+
+a();
+```
+
+#### Parameters
+
+##### targetObject
+
+`object`
+
+##### constructorOpt?
+
+`Function`
+
+#### Returns
+
+`void`
+
+#### Inherited from
+
+[`QueryCollectionError`](QueryCollectionError.md).[`captureStackTrace`](QueryCollectionError.md#capturestacktrace)
+
+***
+
+### prepareStackTrace()
+
+```ts
+static prepareStackTrace(err, stackTraces): any;
+```
+
+Defined in: node\_modules/.pnpm/@types+node@25.2.2/node\_modules/@types/node/globals.d.ts:55
+
+#### Parameters
+
+##### err
+
+`Error`
+
+##### stackTraces
+
+`CallSite`[]
+
+#### Returns
+
+`any`
+
+#### See
+
+https://v8.dev/docs/stack-trace-api#customizing-stack-traces
+
+#### Inherited from
+
+[`QueryCollectionError`](QueryCollectionError.md).[`prepareStackTrace`](QueryCollectionError.md#preparestacktrace)

docs/reference/query-db-collection/classes/DuplicateKeyInBatchError.md

@@ -5,7 +5,7 @@ title: InvalidItemStructureError
 
 # Class: InvalidItemStructureError
 
-Defined in: [packages/query-db-collection/src/errors.ts:48](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/errors.ts#L48)
+Defined in: [packages/query-db-collection/src/errors.ts:57](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/errors.ts#L57)
 
 ## Extends
 
@@ -19,7 +19,7 @@ Defined in: [packages/query-db-collection/src/errors.ts:48](https://github.com/T
 new InvalidItemStructureError(message): InvalidItemStructureError;
 ```
 
-Defined in: [packages/query-db-collection/src/errors.ts:49](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/errors.ts#L49)
+Defined in: [packages/query-db-collection/src/errors.ts:58](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/errors.ts#L58)
 
 #### Parameters
 

docs/reference/query-db-collection/classes/InitialDataInOnDemandModeError.md

@@ -5,7 +5,7 @@ title: InvalidSyncOperationError
 
 # Class: InvalidSyncOperationError
 
-Defined in: [packages/query-db-collection/src/errors.ts:83](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/errors.ts#L83)
+Defined in: [packages/query-db-collection/src/errors.ts:92](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/errors.ts#L92)
 
 ## Extends
 
@@ -19,7 +19,7 @@ Defined in: [packages/query-db-collection/src/errors.ts:83](https://github.com/T
 new InvalidSyncOperationError(message): InvalidSyncOperationError;
 ```
 
-Defined in: [packages/query-db-collection/src/errors.ts:84](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/errors.ts#L84)
+Defined in: [packages/query-db-collection/src/errors.ts:93](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/errors.ts#L93)
 
 #### Parameters
 

docs/reference/query-db-collection/classes/InvalidItemStructureError.md

@@ -5,7 +5,7 @@ title: ItemNotFoundError
 
 # Class: ItemNotFoundError
 
-Defined in: [packages/query-db-collection/src/errors.ts:55](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/errors.ts#L55)
+Defined in: [packages/query-db-collection/src/errors.ts:64](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/errors.ts#L64)
 
 ## Extends
 
@@ -19,7 +19,7 @@ Defined in: [packages/query-db-collection/src/errors.ts:55](https://github.com/T
 new ItemNotFoundError(key): ItemNotFoundError;
 ```
 
-Defined in: [packages/query-db-collection/src/errors.ts:56](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/errors.ts#L56)
+Defined in: [packages/query-db-collection/src/errors.ts:65](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/errors.ts#L65)
 
 #### Parameters